synorch 0.1.0

package/skill-sources/ingenium/skills/session-recap/scripts/extract_session.py

@@ -0,0 +1,409 @@
+#!/usr/bin/env python3
+"""Distill Claude Code session transcripts into a resumable digest.
+
+Reads ~/.claude/projects/<encoded-cwd>/*.jsonl without loading transcripts into
+the model's context. Stdlib only.
+
+  python extract_session.py --list
+  python extract_session.py --session latest
+  python extract_session.py --session <session-id> --json
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from collections import Counter, OrderedDict
+
+EDIT_TOOLS = ("Edit", "Write", "NotebookEdit", "MultiEdit")
+SHELL_TOOLS = ("Bash", "PowerShell")
+RESEARCH_TOOLS = ("WebSearch", "WebFetch")
+INTERRUPT_MARK = "[Request interrupted by user"
+NOISE_PREFIXES = ("<local-command", "<command-name>", "<command-message>")
+
+
+def projects_root():
+    return os.path.join(os.path.expanduser("~"), ".claude", "projects")
+
+
+def encode_cwd(path):
+    return re.sub(r"[^a-zA-Z0-9]", "-", path)
+
+
+def resolve_project_dir(cwd):
+    root = projects_root()
+    direct = os.path.join(root, encode_cwd(os.path.abspath(cwd)))
+    if os.path.isdir(direct):
+        return direct
+    target = os.path.abspath(cwd).rstrip("\\/").lower()
+    if not os.path.isdir(root):
+        return None
+    for name in os.listdir(root):
+        cand = os.path.join(root, name)
+        if not os.path.isdir(cand):
+            continue
+        for f in transcript_files(cand)[:1]:
+            for rec in read_records(f, limit=40):
+                rc = rec.get("cwd")
+                if rc and rc.rstrip("\\/").lower() == target:
+                    return cand
+    return None
+
+
+def transcript_files(project_dir):
+    """All transcripts, newest first."""
+    files = [
+        os.path.join(project_dir, n)
+        for n in os.listdir(project_dir)
+        if n.endswith(".jsonl")
+    ]
+    return sorted(files, key=os.path.getmtime, reverse=True)
+
+
+def seconds_idle(path):
+    import time
+
+    return time.time() - os.path.getmtime(path)
+
+
+def read_records(path, limit=None):
+    out = []
+    with open(path, "r", encoding="utf-8", errors="replace") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                out.append(json.loads(line))
+            except ValueError:
+                continue
+            if limit and len(out) >= limit:
+                break
+    return out
+
+
+def blocks(rec):
+    msg = rec.get("message")
+    if not isinstance(msg, dict):
+        return []
+    content = msg.get("content")
+    if isinstance(content, list):
+        return [b for b in content if isinstance(b, dict)]
+    return []
+
+
+def text_of(rec):
+    msg = rec.get("message")
+    if not isinstance(msg, dict):
+        return ""
+    content = msg.get("content")
+    if isinstance(content, str):
+        return content
+    return " ".join(b.get("text", "") for b in blocks(rec) if b.get("type") == "text")
+
+
+def is_real_prompt(rec):
+    if rec.get("type") != "user" or rec.get("isMeta") or rec.get("isSidechain"):
+        return False
+    if rec.get("promptSource") not in ("typed", "queued", None):
+        return False
+    txt = text_of(rec).strip()
+    if not txt or txt.startswith(NOISE_PREFIXES):
+        return False
+    return rec.get("promptSource") in ("typed", "queued")
+
+
+def squeeze(text, limit):
+    text = " ".join(text.split())
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+def rel(path, cwd):
+    if not path:
+        return path
+    norm = path.replace("/", os.sep).replace("\\", os.sep)
+    base = os.path.abspath(cwd).replace("/", os.sep).replace("\\", os.sep)
+    if norm.lower().startswith(base.lower()):
+        norm = norm[len(base) :].lstrip("\\/")
+    return norm.replace("\\", "/")
+
+
+def summarize(path, cwd, prompt_chars=400, cap=25):
+    recs = read_records(path)
+    stamps = [r["timestamp"] for r in recs if r.get("timestamp")]
+    title = next(
+        (r["aiTitle"] for r in reversed(recs) if r.get("type") == "ai-title" and r.get("aiTitle")),
+        None,
+    )
+    session_cwd = next((r["cwd"] for r in recs if r.get("cwd")), cwd)
+    branches = OrderedDict(
+        (r["gitBranch"], None) for r in recs if r.get("gitBranch")
+    )
+
+    prompts, edits, shell, research, skills, agents = [], Counter(), [], [], [], []
+    errors, denials, interrupts = [], [], 0
+    last_assistant = ""
+    tool_names = {}
+
+    def tool_of(rec):
+        """Resolve which tool a tool_result block belongs to."""
+        for blk in blocks(rec):
+            tid = blk.get("tool_use_id")
+            if tid and tid in tool_names:
+                return tool_names[tid]
+        return None
+
+    for rec in recs:
+        if is_real_prompt(rec):
+            txt = text_of(rec)
+            if INTERRUPT_MARK in txt:
+                interrupts += 1
+            prompts.append(squeeze(txt, prompt_chars))
+        if rec.get("toolDenialKind"):
+            denials.append(
+                "%s (%s)" % (tool_of(rec) or "unknown tool", rec["toolDenialKind"])
+            )
+        if rec.get("interruptedMessageId"):
+            interrupts += 1
+        if rec.get("type") == "file-history-delta" and rec.get("trackingPath"):
+            edits[rel(rec["trackingPath"], session_cwd)] += 0
+
+        msg = rec.get("message") or {}
+        role = msg.get("role") if isinstance(msg, dict) else None
+        if role == "assistant" and not rec.get("isSidechain"):
+            t = text_of(rec).strip()
+            if t:
+                last_assistant = t
+        for blk in blocks(rec):
+            kind = blk.get("type")
+            if kind == "tool_result" and blk.get("is_error"):
+                body = blk.get("content")
+                if isinstance(body, list):
+                    body = " ".join(
+                        b.get("text", "") for b in body if isinstance(b, dict)
+                    )
+                who = tool_names.get(blk.get("tool_use_id")) or "tool"
+                errors.append("%s: %s" % (who, squeeze(str(body), 180)))
+            if kind != "tool_use":
+                continue
+            name, inp = blk.get("name"), blk.get("input") or {}
+            if blk.get("id"):
+                tool_names[blk["id"]] = name
+            if name in EDIT_TOOLS:
+                fp = inp.get("file_path") or inp.get("notebook_path")
+                if fp:
+                    edits[rel(fp, session_cwd)] += 1
+            elif name in SHELL_TOOLS:
+                cmd = squeeze(str(inp.get("command", "")), 160)
+                if cmd:
+                    shell.append(cmd)
+            elif name in RESEARCH_TOOLS:
+                research.append(
+                    "%s: %s" % (name, squeeze(str(inp.get("query") or inp.get("url") or ""), 160))
+                )
+            elif name == "Skill":
+                if inp.get("skill"):
+                    skills.append(inp["skill"])
+            elif name == "Agent":
+                agents.append(squeeze(str(inp.get("description") or ""), 90))
+
+    return {
+        "session_id": os.path.basename(path)[:-6],
+        "file": path,
+        "title": title,
+        "cwd": session_cwd,
+        "started": stamps[0] if stamps else None,
+        "ended": stamps[-1] if stamps else None,
+        "branches": list(branches),
+        "prompts": prompts,
+        "files": [
+            {"path": p, "edits": n} for p, n in sorted(edits.items(), key=lambda kv: -kv[1])
+        ],
+        "commands": dedupe(shell)[:cap],
+        "research": dedupe(research)[:cap],
+        "skills": dedupe(skills),
+        "agents": dedupe(agents)[:cap],
+        "errors": dedupe(errors)[:cap],
+        "denials": denials,
+        "interrupts": interrupts,
+        "last_assistant": squeeze(last_assistant, 700),
+        "record_count": len(recs),
+    }
+
+
+def dedupe(items):
+    return list(OrderedDict((i, None) for i in items))
+
+
+def brief(path, cwd):
+    """Cheap listing entry."""
+    d = summarize(path, cwd, prompt_chars=110, cap=1)
+    return {
+        "session_id": d["session_id"],
+        "title": d["title"],
+        "started": d["started"],
+        "ended": d["ended"],
+        "prompts": len(d["prompts"]),
+        "files": len(d["files"]),
+        "first_prompt": d["prompts"][0] if d["prompts"] else "",
+    }
+
+
+def render(d):
+    L = ["# Session digest — %s" % (d["title"] or d["session_id"])]
+    L.append("")
+    L.append("- session: `%s`" % d["session_id"])
+    L.append("- window: %s → %s" % (d["started"], d["ended"]))
+    L.append("- cwd: `%s`" % d["cwd"])
+    if d["branches"]:
+        L.append("- branch(es): %s" % ", ".join("`%s`" % b for b in d["branches"]))
+    L.append("- records: %d" % d["record_count"])
+
+    def block(head, items, fmt=lambda x: "- %s" % x):
+        if not items:
+            return
+        L.append("")
+        L.append("## %s" % head)
+        L.extend(fmt(i) for i in items)
+
+    block("User prompts (verbatim intent, in order)", list(enumerate(d["prompts"], 1)),
+          lambda t: "%d. %s" % t)
+    block("Files touched", d["files"],
+          lambda f: "- `%s`%s" % (f["path"], "" if not f["edits"] else "  (%d edit calls)" % f["edits"]))
+    block("Research", d["research"])
+    block("Skills loaded", d["skills"])
+    block("Subagents", d["agents"])
+    block("Commands run", d["commands"])
+    block("Tool errors (dead-end candidates)", d["errors"])
+    if d["denials"] or d["interrupts"]:
+        L.append("")
+        L.append("## Friction signals")
+        if d["denials"]:
+            L.append("- denied tool calls: %s" % ", ".join(d["denials"]))
+        if d["interrupts"]:
+            L.append("- user interruptions: %d" % d["interrupts"])
+    if d["last_assistant"]:
+        L.append("")
+        L.append("## Final assistant state")
+        L.append(d["last_assistant"])
+    return "\n".join(L)
+
+
+def force_utf8():
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, ValueError):
+            pass
+
+
+def main():
+    force_utf8()
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--cwd", default=os.getcwd())
+    ap.add_argument("--list", action="store_true")
+    ap.add_argument("--session", help="'latest' or a session id")
+    ap.add_argument("--limit", type=int, default=10)
+    ap.add_argument("--prompt-chars", type=int, default=400)
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument(
+        "--exclude-session",
+        action="append",
+        default=[],
+        help="session id to leave out of 'latest' selection (repeatable) — use for the live session",
+    )
+    ap.add_argument(
+        "--active-window",
+        type=int,
+        default=60,
+        help="seconds of idleness below which a transcript is flagged as possibly live (default 60)",
+    )
+    ap.add_argument(
+        "--all",
+        action="store_true",
+        help="keep sessions with no typed prompt (headless -p runs, aborted starts)",
+    )
+    args = ap.parse_args()
+
+    pdir = resolve_project_dir(args.cwd)
+    if not pdir:
+        print("No transcript directory for cwd: %s" % args.cwd, file=sys.stderr)
+        print("Looked under: %s" % projects_root(), file=sys.stderr)
+        return 2
+    files = transcript_files(pdir)
+    if not files:
+        print("No transcripts in %s" % pdir, file=sys.stderr)
+        return 2
+
+    # An explicit id always wins: no emptiness, liveness or limit filtering.
+    if args.session and args.session != "latest":
+        target = next(
+            (f for f in files if os.path.basename(f).startswith(args.session)), None
+        )
+        if not target:
+            print("Session not found: %s" % args.session, file=sys.stderr)
+            print("Known ids: %s" % ", ".join(os.path.basename(f)[:8] for f in files[:10]), file=sys.stderr)
+            return 2
+        d = summarize(target, args.cwd, prompt_chars=args.prompt_chars)
+        print(json.dumps(d, indent=2, ensure_ascii=False) if args.json else render(d))
+        return 0
+
+    rows, kept, skipped = [], [], 0
+    for f in files:
+        r = brief(f, args.cwd)
+        if not args.all and r["prompts"] == 0:
+            skipped += 1
+            continue
+        idle = seconds_idle(f)
+        r["idle_seconds"] = int(idle)
+        r["maybe_live"] = idle < args.active_window
+        r["excluded"] = any(r["session_id"].startswith(x) for x in args.exclude_session)
+        rows.append(r)
+        kept.append(f)
+        if len(rows) >= args.limit:
+            break
+    if not kept:
+        print("No session with a typed prompt in %s (--all to inspect them)" % pdir, file=sys.stderr)
+        return 2
+
+    eligible = [
+        (r, f) for r, f in zip(rows, kept) if not r["excluded"] and not r["maybe_live"]
+    ] or [(r, f) for r, f in zip(rows, kept) if not r["excluded"]]
+
+    if args.list or not args.session:
+        if args.json:
+            print(json.dumps(
+                {"project_dir": pdir, "sessions": rows, "skipped_empty": skipped,
+                 "suggested": eligible[0][0]["session_id"] if eligible else None},
+                indent=2, ensure_ascii=False))
+        else:
+            print("# Recent sessions — %s\n" % pdir)
+            for i, r in enumerate(rows, 1):
+                flags = []
+                if r["maybe_live"]:
+                    flags.append("POSSIBLY THE SESSION YOU ARE IN — written %ds ago" % r["idle_seconds"])
+                if r["excluded"]:
+                    flags.append("excluded")
+                print("%d. **%s**%s" % (i, r["title"] or "(untitled)",
+                                        "  ⟨%s⟩" % "; ".join(flags) if flags else ""))
+                print("   id `%s` | %s → %s" % (r["session_id"], r["started"], r["ended"]))
+                print("   %d prompts, %d files | opened with: %s" % (r["prompts"], r["files"], r["first_prompt"]))
+            if skipped:
+                print("\n_(%d session(s) with no typed prompt hidden — headless or aborted runs; --all to show)_" % skipped)
+            if eligible:
+                print("\nSuggested: `%s`. Confirm it is not this conversation before summarizing." % eligible[0][0]["session_id"])
+        return 0
+
+    if not eligible:
+        print("Every candidate is excluded or possibly live; pass --session <id> explicitly.", file=sys.stderr)
+        return 2
+    target = eligible[0][1]
+    d = summarize(target, args.cwd, prompt_chars=args.prompt_chars)
+    print(json.dumps(d, indent=2, ensure_ascii=False) if args.json else render(d))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+

package/skill-sources/ingenium/skills/shader-vfx/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: shader-vfx
+description: Shaders and visual effects for web and games - fragment/vertex shader mental model, GLSL toolkit (SDFs, smoothstep, noise, fbm), ready recipes for game VFX (hit flash, dissolve, outline, water, shockwave, palette swap, CRT), pixel-art-safe effects, post-processing chains, per-environment usage (three.js, PixiJS filters, Phaser pipelines, Godot shading language) and shader debugging/performance. Use when writing or fixing shaders, adding visual effects like glow, dissolve, distortion or outlines, doing post-processing, or when an effect needs GPU work. Türkçe tetikleyiciler - "shader yaz", "efekt ekle", "glow efekti", "dissolve efekti", "outline shader", "su efekti", "ekran efekti", "crt efekti", "godot shader", "glsl".
+---
+
+# Shader VFX
+
+You write shaders that serve the game's look and run fast. Shaders are per-pixel programs running massively parallel: think "what color is *this* pixel, given its coordinates, time and textures" — not loops over the image.
+
+Always communicate with the user in their own language.
+
+## Mental model (2 minutes, saves hours)
+
+- **Vertex shader** positions geometry; **fragment shader** colors each pixel. 95% of 2D game VFX is fragment work.
+- Coordinates: work in **UV space** (0–1 across the texture/quad). Center-origin trick: `vec2 p = uv - 0.5;` (aspect-correct with `p.x *= aspect;`).
+- Everything is a gradient: you compute values (distances, noise, masks) and map them to color with `mix` and `smoothstep`. There is no "if pixel is inside shape" — there is "how far is this pixel from the shape edge".
+- Inputs come as **uniforms** (time, resolution, effect strength, textures); per-frame animation = a `time` uniform, not new shaders.
+
+## The core toolkit (memorize these five)
+
+1. `smoothstep(a, b, x)` — THE shaping function: soft thresholds, anti-aliased edges (`smoothstep(0.0, 2.0/resolution.y, d)`).
+2. `mix(a, b, t)` — blend anything: colors, positions, whole effects.
+3. **SDF shapes**: `length(p) - r` (circle), rect/segment SDFs; combine with `min` (union) / `max` (intersect); distance drives glow, outlines, soft shadows.
+4. `fract`/`mod` — repetition: tiles, stripes, scanlines (`fract(uv.y * 100.0)`).
+5. **Noise**: cheap hash → value noise → **fbm** (4–5 octaves of noise at doubling frequency, halving amplitude) for anything organic — fire, water, smoke, dissolve. Include a known-good hash/noise snippet rather than inventing one.
+
+## Recipe book (game VFX that ship)
+
+- **Hit flash**: `color = mix(color, vec3(1.0), u_flash)` — drive `u_flash` from gameplay (spike to 1, decay over ~80ms).
+- **Dissolve**: `if (noise(uv * scale) < u_threshold) discard;` + emissive edge where `noise - threshold < 0.05`. Animate threshold 0→1 to disintegrate.
+- **Outline (sprite)**: sample alpha at 4–8 neighbor offsets; outside pixels with an opaque neighbor get outline color. Pixel-art: 4 offsets of exactly one texel.
+- **Water**: scroll two noise layers at different speeds/scales, use them to distort sample UVs of the scene below + tint + specular band via smoothstep.
+- **Shockwave**: radial UV displacement — `uv += dir * sin((dist - u_t) * freq) * falloff(dist, u_t)` expanding ring.
+- **Heat haze / refraction**: small animated-noise UV offsets on the background sample.
+- **Palette swap / LUT grading**: map luminance (or index) through a lookup texture — day/night, damage states, retro palettes for free.
+- **CRT/retro post**: scanlines (sine on screen y), slight barrel distortion, chromatic aberration (offset R/B samples), vignette. Subtlety: each at 10–20% of what first looks cool.
+- **Glow/bloom**: threshold bright pixels → downscale-blur passes → additive composite. Use the engine's bloom before hand-rolling.
+
+## Pixel-art-safe VFX
+
+- Snap effect UVs to the texel grid (`floor(uv * texSize) / texSize`) or effects smear across the chunky pixels and break the look.
+- Render effects at the game's native low resolution, then integer-upscale — post applied after upscale reads as "HD filter on retro game".
+- Prefer **dither patterns** over smooth gradients (Bayer-matrix threshold) to stay on-palette; palette-swap via LUT beats hue-shifting.
+
+## Where shaders live per environment
+
+- **three.js**: `ShaderMaterial`/`onBeforeCompile`; post via `EffectComposer`.
+- **PixiJS**: `Filter` (fragment + uniforms) per-sprite or per-container.
+- **Phaser**: PostFX/PreFX pipelines (built-ins: bloom, glow, blur) or custom `PostFXPipeline` — check built-ins first.
+- **Godot**: `.gdshader`, GLSL-like with `shader_type canvas_item;` for 2D; `hint_range` uniforms editable in Inspector; screen-reading via `SCREEN_TEXTURE`/`hint_screen_texture`. Same recipes translate almost 1:1.
+- **WebGPU/WGSL**: different syntax, same mental model; compute shaders unlock particles/sim — port there when the target supports it (see tauri-game-dev webview notes for desktop caveats).
+
+## Post-processing chains
+
+Render scene → render target A → effect pass A→B → effect pass B→A (**ping-pong**) → screen. Order matters and is a look decision: grade → bloom → grain reads different from bloom → grade. Keep a debug toggle per pass.
+
+## Performance
+
+- Cost = pixels covered × work per pixel. Fullscreen passes are the budget hogs — count them; half-resolution for blurry effects (blur/bloom/haze) is visually free, 4× cheaper.
+- Texture fetches dominate: 8 neighbor samples per pixel is fine; 64 is a blur done wrong (separable blur: two 1D passes beat one 2D pass).
+- `mediump` default precision on mobile; branches on *uniforms* are fine, per-pixel divergent branches less so — but measure before contorting code.
+- Overdraw from stacked transparent quads (particles) kills mobile — fewer, bigger, smarter particles.
+- Profile with SpectorJS (WebGL frame inspector) or the engine's GPU timers; never optimize a shader you haven't measured.
+
+## Debugging (there is no console.log)
+
+- **Output the value as color**: `gl_FragColor = vec4(vec3(suspectValue), 1.0);` — the image *is* the debugger. Expect NaN to render black/weird: check divisions and `normalize(vec2(0))`.
+- Isolate: comment passes back to a solid color, re-add until it breaks.
+- Prototype on Shadertoy/The Book of Shaders playgrounds (instant iteration), then port — mind their uniform naming (`iTime` → your `u_time`).
+

package/skill-sources/ingenium/skills/tailwind-v4-tokens/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: tailwind-v4-tokens
+description: Tailwind CSS v4 token architecture and its silent failure modes - the three-layer setup (raw palette to theme-scoped semantic tokens to an @theme inline handoff), why @theme inline is mandatory for values that change at runtime, why hand-written CSS classes never get hover/focus variants and fail without a build error, @utility and @variant for real custom utilities, custom breakpoints via --breakpoint-*, opacity modifiers on custom tokens, and CSS-first config differences from v3. Carries executable diagnostics - grep patterns that find variant-on-custom-class bugs and escaped-selector verification in the compiled CSS. Use when setting up or migrating Tailwind 4 theming, when hover/focus/dark styles silently do nothing, when a class sits in the markup but has no effect, or when wiring CSS variables into Tailwind. Türkçe tetikleyiciler - "tailwind 4'e geç", "hover çalışmıyor", "sınıf uygulanmıyor", "tema token sistemi kur", "dark mode altyapısı", "css değişkenini tailwind'e bağla", "stil neden gitmiyor".
+---
+
+# Tailwind v4 Tokens
+
+Tailwind v4 fails **silently**. A class it does not own produces no CSS, no warning and no non-zero exit — the build is green and the pixels are missing. This skill owns that mechanic: which classes Tailwind can generate, how to hand CSS variables over so theming survives, and how to prove a class actually compiled. Token *taste* (which semantic roles exist, contrast in both themes) belongs to the design-system skill.
+
+Always communicate with the user in their own language.
+
+## Phase 1 — Diagnose an existing project
+
+The failure has one shape: a class is **hand-written CSS**, but used **with a variant**. Tailwind generates variants only for utilities it owns — its own, `@theme`-derived, or `@utility`-registered. `hover:bg-theme-card` where `.bg-theme-card` is your own rule compiles to nothing.
+
+**Why no error:** the compiler scans source files for candidate strings and emits CSS for recognized ones. An unrecognized candidate is indistinguishable from any ordinary class name (`card`, `swiper-slide`, a third-party class) — erroring would break every project on earth. Class attributes are opaque strings; nothing type-checks them. Missing pixels are the only signal.
+
+**Find variant-on-custom-class bugs** — every class defined in your CSS, cross-checked against variant usage in source:
+
+```bash
+rg -oNI -g '*.css' '^\.([a-z0-9-]+)' src | sed 's/^\.//' | sort -u | while read -r c; do
+  rg -qI "(hover|focus|focus-within|focus-visible|active|disabled|group-hover|peer-focus|dark|xs|sm|md|lg|xl|2xl):$c\b" src \
+    && echo "DEAD: variant used on hand-written class -> $c"
+done
+```
+
+It flags *variant* usage only — a hand-written class used bare (`class="bg-theme-card"`) still works as ordinary CSS, so that one is a naming problem, not a broken-pixel one.
+
+**Find invented breakpoints** — v4 ships `sm md lg xl 2xl` only; anything else must be a `--breakpoint-*` token, or the chain silently loses a step and two branches of a `hidden xs:inline sm:hidden` sequence show at once:
+
+```bash
+rg -oI '\b(xs|sm|md|lg|xl|2xl|3xl):' src | sort -u        # variants in use
+rg -n -g '*.css' -- '--breakpoint-' src                   # variants actually defined
+```
+
+**Prove a class compiled** — build, then find the escaped selector in the output CSS. Ground truth, not a guess. The output selector is `.hover\:bg-hover:hover`; match the backslash with a wildcard `.` instead of escaping it — a backslash eaten by a shell quoting layer turns a working class into a false zero, and a lying verifier is worse than none:
+
+```bash
+npm run build
+rg -c 'hover.:bg-hover|focus-within.:border-accent' dist/assets/*.css  # no output = not generated
+rg -o -- '--color-[a-z-]+' dist/assets/*.css | sort -u                 # tokens Tailwind knows
+```
+
+Calibrate it once against a class you know exists and once against an invented name that must return nothing.
+
+## Phase 2 — `@theme` vs `@theme inline`
+
+The single most consequential decision. `@theme` emits the token as a variable in `:root` and points utilities at *that* variable; `@theme inline` substitutes the referenced value straight into the utility. Both compile, so the difference only shows up as a theme toggle that does nothing.
+
+```css
+/* WRONG — one indirection too many */
+@theme {
+  --color-surface: var(--bg-surface);
+}
+/* emits :root { --color-surface: var(--bg-surface) }
+          .bg-surface { background-color: var(--color-surface) }
+   --bg-surface is resolved on the root element and inherited as a finished value. */
+```
+
+```css
+/* RIGHT */
+@theme inline {
+  --color-surface: var(--bg-surface);
+}
+/* emits .bg-surface { background-color: var(--bg-surface) }
+   resolved on the element itself, so the nearest .light/.dark ancestor wins. */
+```
+
+Be precise about when the wrong version bites, or you will "disprove" it by accident: with `.dark` on `<html>` (the root element) a global toggle appears to work, because root is where the resolution happens. It breaks when the theme class sits anywhere else (`<body>`, an app wrapper) and it breaks for **nested** theme scopes — a light-themed panel inside a dark page — even when the class is on `<html>`. The inline version is correct in all three cases, which is why it is the default here.
+
+**Rule:** literal value → `@theme`. A `var()` whose value is redefined in any scope (`.dark`, `[data-theme]`, a subtree) → `@theme inline`.
+
+## Phase 3 — Three-layer token architecture (copyable skeleton)
+
+```css
+@import "tailwindcss";
+
+@custom-variant dark (&:where(.dark, .dark *));
+
+/* Layer 1 — raw palette. Theme-independent, never referenced by components. */
+:root {
+  --gray-50: oklch(0.985 0 0); --gray-200: oklch(0.92 0.004 260);
+  --gray-400: oklch(0.71 0.012 260); --gray-800: oklch(0.28 0.014 260);
+  --gray-950: oklch(0.15 0.012 260);
+  --brand-400: oklch(0.70 0.16 255); --brand-500: oklch(0.62 0.19 255);
+}
+
+/* Layer 2 — semantic roles, redefined per theme. The only layer that knows themes. */
+.light {
+  --bg-base: var(--gray-50); --bg-surface: #fff; --bg-hover: var(--gray-200);
+  --fg-base: var(--gray-950); --fg-muted: var(--gray-400);
+  --line: var(--gray-200); --accent: var(--brand-500);
+}
+.dark {
+  --bg-base: var(--gray-950); --bg-surface: var(--gray-800);
+  --bg-hover: oklch(0.33 0.014 260);
+  --fg-base: var(--gray-50); --fg-muted: var(--gray-400);
+  --line: var(--gray-800); --accent: var(--brand-400);
+}
+
+/* Layer 3 — handoff. Runtime-swapped values MUST be inline. */
+@theme inline {
+  --color-base: var(--bg-base);
+  --color-surface: var(--bg-surface);
+  --color-hover: var(--bg-hover);
+  --color-fg: var(--fg-base);
+  --color-muted: var(--fg-muted);
+  --color-line: var(--line);
+  --color-accent: var(--accent);
+}
+
+/* Static scales — no runtime swap, so plain @theme. */
+@theme {
+  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
+  --radius-card: 0.75rem;
+  --text-caption: 0.8125rem; --text-caption--line-height: 1.4;
+  --shadow-card-lifted: 0 12px 32px oklch(0 0 0 / 0.16);
+  --breakpoint-xs: 30rem;
+  --animate-fade-in: fade-in 200ms ease-out;
+  @keyframes fade-in { from { opacity: 0 } to { opacity: 1 } }
+}
+```
+
+What this buys: `bg-surface`, `text-muted`, `border-line`, `hover:bg-hover`, `focus-within:border-accent`, `hover:shadow-card-lifted`, `xs:inline`, `animate-fade-in` all compile natively, with every variant, because Tailwind owns them. Note that `dark:` variants become largely unnecessary for color — the swap happens one layer below. Keep `@custom-variant dark` for the exceptions only (an inverted image filter, a different shadow strategy).
+
+## Phase 4 — v4 mechanics worth knowing
+
+- **Own utilities via `@utility`** — the fix for `transition-smooth` / `interactive-scale` style helpers. Registered utilities get variants; `.class {}` rules do not. `@variant` applies a Tailwind variant inside custom CSS:
+
+  ```css
+  @utility transition-smooth {
+    transition: all 200ms cubic-bezier(0.4, 0, 0.2, 1);
+  }
+  @utility interactive-scale {
+    transition: transform 150ms ease-out;
+    @variant hover { transform: scale(1.02); }
+    @variant active { transform: scale(0.98); }
+  }
+  ```
+  Verify with the Phase 1 escaped-selector grep — `rg -c 'md.:interactive-scale' dist/assets/*.css` must be non-zero.
+
+- **Opacity modifiers work on custom tokens**: `bg-surface/60` compiles to `color-mix(in oklab, var(--bg-surface) 60%, transparent)`, behind a `@supports` guard with the flat color as fallback. It requires the token to resolve to a *color* — a var holding a gradient or a shadow yields nothing usable.
+
+- **Custom breakpoints** are tokens: `--breakpoint-xs: 30rem` in `@theme` creates the `xs:` variant; without the token the prefix is simply dropped.
+
+| v3 | v4 |
+|---|---|
+| `tailwind.config.js` | CSS-first `@theme` (legacy opt-in: `@config "./tailwind.config.js"`) |
+| `@tailwind base/components/utilities` | `@import "tailwindcss"` |
+| `content: [...]` globs | automatic source detection |
+| `theme.extend.colors` | `--color-*` in `@theme` / `@theme inline` |
+| `@layer utilities { .foo {} }` | `@utility foo { }` |
+| `darkMode: 'class'` | `@custom-variant dark (&:where(.dark, .dark *))` |
+
+## Phase 5 — Migration order (each step has a done-check)
+
+1. **Tokens first.** Build the three layers; keep the old classes alive alongside so nothing breaks mid-flight. *Done-check:* toggling `.dark` on the root element changes computed colors in DevTools, and `--color-*` names appear in the built CSS.
+2. **Variant audit.** Replace every variant-prefixed custom class with a token-derived utility; register genuine helpers with `@utility`; define missing breakpoints. *Done-check:* the Phase 1 loop prints nothing, and every variant class in the diff appears as an escaped selector in `dist`.
+3. **Dead class sweep.** Delete the hand-written color classes and any never-defined utilities. *Done-check:* `rg -w '<class-name>' src` returns zero hits per removed class; CSS bundle size drops.
+4. **Contrast verification** in both themes — hand off to the design-system skill (4.5:1 body, 3:1 large text and UI); a token swap that compiles can still be unreadable.
+
+## Anti-patterns
+
+Hand-writing `.my-color { color: var(--x) }` for anything Tailwind could generate from a token; defining the same token in both `@theme` and `:root` (two sources of truth, whichever loses is the confusing one); `@theme` for a value redefined under `.dark`; using variants on classes you wrote yourself; relying on a utility that was never defined anywhere; inventing a breakpoint prefix without a `--breakpoint-*` token; hoarding tokens no component consumes; patching a cascade fight with `!important` instead of finding which layer owns the property.
+