rockycode 0.1.0__py3-none-any.whl

rockycode/runners/raw.py

@@ -0,0 +1,176 @@
+"""Raw single-shot runner: model gets the problem statement and emits a unified
+diff. No tools, no iteration. This is the lower-bound baseline against which
+the rockycode harness's value-add is measured.
+"""
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from openai import OpenAI
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+from rich.table import Table
+
+from rockycode.banner import amaze, confused, fail
+from rockycode.engine.effort import build_extra_body
+from rockycode.onboarding import require_base_url, require_key
+from rockycode.palette import PURPLE, VIOLET
+from rockycode.prompts.rocky import RAW_SINGLE_SHOT
+from rockycode.runners.data import load_verified
+
+PREDICTIONS_DIR = Path("results") / "predictions"
+
+# Pull the diff out of ```diff …``` first, then any fenced block, else raw.
+_DIFF_FENCE = re.compile(r"```diff\s*\n(.*?)```", re.DOTALL)
+_ANY_FENCE = re.compile(r"```\w*\s*\n(.*?)```", re.DOTALL)
+
+
+def _extract_diff(text: str) -> str:
+    if m := _DIFF_FENCE.search(text):
+        return m.group(1)
+    if m := _ANY_FENCE.search(text):
+        return m.group(1)
+    return text
+
+
+def _build_prompt(instance: dict) -> str:
+    return RAW_SINGLE_SHOT.format(
+        repo=instance.get("repo", "unknown"),
+        base_commit=instance.get("base_commit", "unknown"),
+        problem_statement=instance.get("problem_statement", ""),
+        hints=instance.get("hints_text", "") or "(none)",
+    )
+
+
+def _extract_usage(resp) -> dict:
+    """Flatten resp.usage including DeepSeek-specific extras (cache hit/miss).
+
+    DeepSeek surfaces `prompt_cache_hit_tokens` and `prompt_cache_miss_tokens`
+    in usage, which aren't in the openai-python SDK's typed Usage model.
+    Pull them via model_dump so we don't lose them.
+    """
+    if resp.usage is None:
+        return {}
+    try:
+        return resp.usage.model_dump()
+    except AttributeError:
+        return dict(resp.usage)
+
+
+def run(
+    model: str,
+    instance_ids: Optional[list[str]],
+    console: Console,
+    *,
+    thinking: bool = True,
+    reasoning_effort: str = "max",
+    max_tokens: int = 16384,
+    task_label: str = "tasks",
+    output_dir: Path = PREDICTIONS_DIR,
+) -> Path:
+    """Generate single-shot predictions for the requested instances.
+
+    Returns the path to a SWE-bench-format predictions JSONL file.
+    """
+    ds = load_verified(console, instance_ids)
+    console.print(f"  → {len(ds)} instances to predict\n")
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    safe_model = model.replace("/", "-")
+    # task-set + timestamp: no run ever overwrites another
+    stamp = datetime.now().strftime("%Y%m%d-%H%M")
+    out_path = output_dir / f"raw-{safe_model}-{task_label}-{stamp}.jsonl"
+
+    # Key AND endpoint from rocky's credential chain — never the SDK's ambient
+    # OPENAI_API_KEY / OPENAI_BASE_URL fallbacks.
+    # max_retries=5: DeepSeek is flakier than OpenAI; SDK default of 2 is too low.
+    client = OpenAI(api_key=require_key(), base_url=require_base_url(),
+                    max_retries=5, timeout=120.0)
+    extra_body = build_extra_body(thinking, reasoning_effort)
+
+    n_ok = n_fail = 0
+    totals = {
+        "prompt_tokens": 0,
+        "completion_tokens": 0,
+        "prompt_cache_hit_tokens": 0,
+        "prompt_cache_miss_tokens": 0,
+    }
+
+    with out_path.open("w") as f, Progress(
+        SpinnerColumn(style=PURPLE),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(complete_style=PURPLE, finished_style=VIOLET),
+        TextColumn("{task.completed}/{task.total}"),
+        TimeElapsedColumn(),
+        console=console,
+    ) as progress:
+        bar = progress.add_task("predicting", total=len(ds))
+        for instance in ds:
+            iid = instance["instance_id"]
+            try:
+                resp = client.chat.completions.create(
+                    model=model,
+                    messages=[{"role": "user", "content": _build_prompt(instance)}],
+                    temperature=0.0,
+                    max_tokens=max_tokens,
+                    extra_body=extra_body,
+                )
+                content = resp.choices[0].message.content or ""
+                patch = _extract_diff(content).strip()
+                if patch and not patch.endswith("\n"):
+                    patch += "\n"
+
+                usage = _extract_usage(resp)
+                for k in totals:
+                    totals[k] += usage.get(k, 0) or 0
+
+                n_ok += 1
+            except Exception as e:  # noqa: BLE001 — log + record empty patch, keep going
+                fail(console, f"{iid}: {e}")
+                patch = ""
+                n_fail += 1
+
+            f.write(json.dumps({
+                "instance_id": iid,
+                "model_name_or_path": f"raw-{safe_model}",
+                "model_patch": patch,
+            }) + "\n")
+            f.flush()
+            progress.update(bar, advance=1)
+
+    if n_fail == 0:
+        amaze(console, f"all {n_ok} predictions written to {out_path}!")
+    else:
+        confused(console, f"{n_ok} ok, {n_fail} failed. predictions at {out_path}")
+
+    _print_usage_summary(console, totals)
+    return out_path
+
+
+def _print_usage_summary(console: Console, totals: dict) -> None:
+    prompt = totals["prompt_tokens"]
+    completion = totals["completion_tokens"]
+    cache_hit = totals["prompt_cache_hit_tokens"]
+    cache_miss = totals["prompt_cache_miss_tokens"]
+    cache_seen = cache_hit + cache_miss
+    hit_rate = (cache_hit / cache_seen * 100) if cache_seen else 0.0
+
+    table = Table(title="token usage", show_header=True, header_style=f"bold {VIOLET}")
+    table.add_column("metric")
+    table.add_column("value", justify="right")
+    table.add_row("prompt tokens", f"{prompt:,}")
+    table.add_row("completion tokens", f"{completion:,}")
+    table.add_row("cache hit tokens", f"{cache_hit:,}")
+    table.add_row("cache miss tokens", f"{cache_miss:,}")
+    table.add_row("cache hit rate", f"{hit_rate:.1f}%")
+    console.print(table)

rockycode/score.py

@@ -0,0 +1,114 @@
+"""Wraps SWE-bench's official evaluation harness as a subprocess.
+
+We call `python -m swebench.harness.run_evaluation` rather than importing
+internals — the harness's public CLI is its stable contract; its Python API
+moves between releases.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+from rich.console import Console
+from rich.table import Table
+
+from rockycode.banner import amaze, fail, info
+from rockycode.palette import VIOLET
+
+DATASET = "princeton-nlp/SWE-bench_Verified"
+
+
+def score(
+    predictions_path: Path,
+    run_id: str,
+    instance_ids: Optional[list[str]],
+    console: Console,
+    max_workers: int = 4,
+    timeout: int = 1800,
+) -> dict:
+    """Run swebench eval and parse the report. Returns the parsed report dict."""
+    info(console, f"scoring run_id={run_id}")
+    info(console, f"predictions={predictions_path}")
+
+    cmd = [
+        sys.executable, "-m", "swebench.harness.run_evaluation",
+        "--dataset_name", DATASET,
+        "--predictions_path", str(predictions_path),
+        "--max_workers", str(max_workers),
+        "--run_id", run_id,
+        "--timeout", str(timeout),
+    ]
+    if instance_ids:
+        cmd += ["--instance_ids", *instance_ids]
+
+    info(console, f"$ {' '.join(cmd)}")
+    proc = subprocess.run(cmd, check=False)
+    if proc.returncode != 0:
+        fail(console, f"swebench harness exited {proc.returncode}")
+        raise SystemExit(proc.returncode)
+
+    report = _find_report(run_id)
+    if report is None:
+        fail(console, "no report file found after eval. check logs/run_evaluation/")
+        raise SystemExit(1)
+
+    _print_report(console, report, run_id)
+    return report
+
+
+def _find_report(run_id: str) -> Optional[dict]:
+    """The harness writes its summary as <model_name>.<run_id>.json in cwd
+    (older versions) or under logs/run_evaluation/<run_id>/ (newer). Match run_id
+    EXACTLY (delimited) and take the NEWEST match: a loose `*run_id*` glob matched
+    'v1' inside a 'v12' report, and with no freshness order a re-run of the same
+    run_id could pick up a stale report."""
+    candidates: list[Path] = []
+    candidates += list(Path(".").glob(f"*.{run_id}.json"))
+    candidates += list(Path("logs/run_evaluation").glob(f"{run_id}/**/results.json"))
+    candidates += list(Path("logs/run_evaluation").glob(f"{run_id}/**/*.json"))
+    candidates.sort(key=lambda p: p.stat().st_mtime if p.exists() else 0.0, reverse=True)
+    for path in candidates:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            if isinstance(data, dict) and ("resolved_ids" in data or "resolved_instances" in data):
+                return data
+        except (json.JSONDecodeError, OSError):
+            continue
+    return None
+
+
+def _count(report: dict, ids_key: str, count_key: str) -> int:
+    v = report.get(ids_key)
+    if isinstance(v, list):
+        return len(v)
+    c = report.get(count_key)
+    return int(c) if isinstance(c, (int, float)) else 0
+
+
+def _print_report(console: Console, report: dict, run_id: str) -> None:
+    resolved = _count(report, "resolved_ids", "resolved_instances")
+    submitted = _count(report, "submitted_ids", "submitted_instances")
+    error = _count(report, "error_ids", "error_instances")
+    total = report.get("total_instances") or 0
+    # Score over what we actually submitted. swebench's total_instances is the
+    # whole Verified set (500) — dividing by it made a 1-task run read as 0.2%.
+    pct = (resolved / submitted * 100) if submitted else 0.0
+
+    info(console, f"run: {run_id}")
+    table = Table(show_header=True, header_style=f"bold {VIOLET}")
+    table.add_column("metric")
+    table.add_column("value", justify="right")
+    table.add_row("submitted", str(submitted))
+    table.add_row("resolved", str(resolved))
+    table.add_row("errors", str(error))
+    table.add_row("score (resolved / submitted)", f"[bold]{pct:.1f}%[/bold]")
+    table.add_row("[dim]verified set size[/dim]", f"[dim]{total}[/dim]")
+    console.print(table)
+
+    if pct > 0:
+        amaze(console, f"score {pct:.1f}%! amaze!")
+    else:
+        console.print("[dim]we no resolve any. we try harness next, learn more.[/dim]")

rockycode/session.py

@@ -0,0 +1,298 @@
+"""Session storage: stable project identity + cross-folder discovery.
+
+Claude Code / Codex key sessions by a folder's absolute path in a global
+store, so renaming or moving the folder ORPHANS its sessions. rockycode does
+it differently:
+
+- Each project gets a STABLE id in `.rockycode/project.json`. The file lives
+  in the folder, so it travels on rename/move — the project keeps its identity
+  no matter where it is or what it's called.
+- Trajectories live in ONE global store (`~/.rockycode/trajectories`); each
+  file's meta records which project it belongs to, so sessions follow the
+  project identity, not the folder path.
+- A tiny global registry (`~/.rockycode/projects.json`) records where each
+  project currently lives, so sessions are discoverable ACROSS folders — the
+  resume picker can list "this folder" or "all folders", and `--resume <id>`
+  can land back in a project's CURRENT folder even after a rename.
+
+So: sessions survive folder renames AND are searchable across the machine —
+which neither Claude Code nor Codex manage.
+
+Public session ids are `rk_<hash>` — the uuid tail of the trajectory stem
+(filenames keep their sortable timestamp form on disk; humans get the short
+hash, like opencode's `ses_…`).
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+_HOME_ENV = os.environ.get("ROCKYCODE_HOME")
+HOME_ROOT = Path(_HOME_ENV).expanduser() if _HOME_ENV else Path.home() / ".rockycode"
+REGISTRY = HOME_ROOT / "projects.json"
+PROJECT_REL = Path(".rockycode") / "project.json"
+TRAJ_REL = Path(".rockycode") / "trajectories"
+
+
+@dataclass
+class Project:
+    id: str
+    name: str
+    root: Path
+
+
+@dataclass
+class SessionInfo:
+    session_id: str
+    path: Path
+    project_id: str
+    project_name: str
+    project_path: str
+    model: str
+    started_at: float
+    n_messages: int
+    summary: str
+    title: str = ""  # flash-generated; empty on old/offline sessions
+
+    @property
+    def display_title(self) -> str:
+        return self.title or self.summary
+
+
+# ---- project identity + registry -------------------------------------------
+
+def get_project(workdir: Path) -> Project:
+    """Stable identity for a folder. Creates `.rockycode/project.json` on first
+    use; that file travels with the folder, so the id survives renames."""
+    workdir = Path(workdir).resolve()
+    pf = workdir / PROJECT_REL
+    if pf.exists():
+        try:
+            data = json.loads(pf.read_text(encoding="utf-8"))
+            proj = Project(id=data["project_id"], name=data.get("name", workdir.name), root=workdir)
+        except (json.JSONDecodeError, OSError, KeyError):
+            proj = _new_project(workdir, pf)
+    else:
+        proj = _new_project(workdir, pf)
+    _register(proj)
+    return proj
+
+
+def _new_project(workdir: Path, pf: Path) -> Project:
+    proj = Project(id=uuid.uuid4().hex, name=workdir.name, root=workdir)
+    try:
+        pf.parent.mkdir(parents=True, exist_ok=True)
+        pf.write_text(
+            json.dumps({"project_id": proj.id, "name": proj.name, "created": time.time()}, indent=2),
+            encoding="utf-8",
+        )
+    except OSError:
+        # Read-only / unwritable cwd: use an ephemeral id for this run instead of
+        # crashing chat at startup. It just won't persist across launches (so
+        # resume-by-project won't find it), which is the right degradation.
+        pass
+    return proj
+
+
+def _load_registry() -> dict:
+    if REGISTRY.exists():
+        try:
+            return json.loads(REGISTRY.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return {}
+    return {}
+
+
+def _register(proj: Project) -> None:
+    """Record (and self-heal) where this project lives. `current` is the
+    authoritative path; old paths linger but are harmless. Best-effort: the
+    registry only powers cross-folder resume, so an unwritable home must never
+    block startup."""
+    try:
+        HOME_ROOT.mkdir(parents=True, exist_ok=True)
+        reg = _load_registry()
+        entry = reg.get(proj.id, {})
+        paths = set(entry.get("paths", []))
+        paths.add(str(proj.root))
+        reg[proj.id] = {
+            "name": proj.name,
+            "current": str(proj.root),
+            "paths": sorted(paths),
+            "last_seen": time.time(),
+        }
+        REGISTRY.write_text(json.dumps(reg, indent=2), encoding="utf-8")
+    except OSError:
+        pass
+
+
+# ---- session discovery -----------------------------------------------------
+
+def _is_chat_session(meta: dict) -> bool:
+    # bench, goal, and routine runs land in the same trajectories dir but
+    # carry a runner / instance_id; the resume picker only wants interactive
+    # chat sessions. (Goal/routine runs DO carry project_id now — that's for
+    # the dream, which grades them alongside chats, not for the picker.)
+    return "instance_id" not in meta and meta.get("runner") not in ("rockycode", "goal", "routine")
+
+
+def global_traj_dir() -> Path:
+    """The single global trajectory store. Read at call time so a test that
+    redirects HOME_ROOT takes effect."""
+    return HOME_ROOT / "trajectories"
+
+
+def _read_info(traj: Path) -> Optional[SessionInfo]:
+    """Build a SessionInfo from a trajectory; project identity comes from its
+    own meta (project_id/project_name/workdir), since all sessions share the
+    one global dir now."""
+    try:
+        lines = traj.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return None
+    if not lines:
+        return None
+    meta: dict = {}
+    summary = ""
+    title = ""
+    n_messages = 0
+    started_at = traj.stat().st_mtime
+    for ln in lines:
+        try:
+            rec = json.loads(ln)
+        except json.JSONDecodeError:
+            continue
+        kind, data = rec.get("kind"), rec.get("data", {})
+        if kind == "meta":
+            meta = data
+            started_at = rec.get("t", started_at)
+        elif kind == "title":
+            # last one wins — the trajectory is append-only, so regenerating a
+            # title later just appends a fresher record
+            t = data.get("title")
+            if isinstance(t, str) and t.strip():
+                title = t.strip()
+        elif kind == "message":
+            n_messages += 1
+            if not summary and data.get("role") == "user":
+                c = data.get("content")
+                if isinstance(c, str) and c.strip():
+                    summary = c.strip().splitlines()[0][:80]
+    if not _is_chat_session(meta):
+        return None
+    workdir = meta.get("workdir", "")
+    return SessionInfo(
+        session_id=traj.stem,
+        path=traj,
+        project_id=meta.get("project_id", ""),
+        project_name=meta.get("project_name") or (Path(workdir).name if workdir else "?"),
+        project_path=workdir,
+        model=meta.get("model", "?"),
+        started_at=started_at,
+        n_messages=n_messages,
+        summary=summary or "(no message)",
+        title=title,
+    )
+
+
+def list_sessions(
+    scope: str = "project",
+    *,
+    workdir: Optional[Path] = None,
+    query: Optional[str] = None,
+    limit: int = 50,
+) -> list[SessionInfo]:
+    """Chat sessions from the global store, newest first. scope='project'
+    keeps only this workdir's project (by project_id); scope='all' keeps every
+    project. query filters by summary/project-name substring."""
+    traj_dir = global_traj_dir()
+    if not traj_dir.is_dir():
+        return []
+    target_pid: Optional[str] = None
+    if scope != "all" and workdir is not None:
+        target_pid = get_project(workdir).id
+    infos: list[SessionInfo] = []
+    for f in traj_dir.glob("*.jsonl"):
+        info = _read_info(f)
+        if info is None:
+            continue
+        if target_pid is not None and info.project_id != target_pid:
+            continue
+        infos.append(info)
+    if query:
+        q = query.lower()
+        infos = [i for i in infos
+                 if q in i.title.lower() or q in i.summary.lower() or q in i.project_name.lower()]
+    infos.sort(key=lambda i: i.started_at, reverse=True)
+    return infos[:limit]
+
+
+# ---- public session ids ------------------------------------------------------
+
+ID_PREFIX = "rk_"
+
+
+def public_id(session_id: str) -> str:
+    """`rk_ab12cd34` — the uuid tail of the trajectory stem, rocky-prefixed.
+    The filename keeps its sortable stamp form on disk; humans get the hash."""
+    return ID_PREFIX + session_id.rsplit("-", 1)[-1]
+
+
+def resolve_session(token: str) -> tuple[Optional[SessionInfo], str]:
+    """One session from a user-typed id. Accepted forms: `rk_ab12cd34`, bare
+    `ab12cd34`, a unique hash prefix (≥4 chars), or a full legacy stem.
+    Returns (info, error) — exactly one is set."""
+    t = token.strip().lower()
+    if t.startswith(ID_PREFIX):
+        t = t[len(ID_PREFIX):]
+    if not t:
+        return None, "empty session id"
+    sessions = list_sessions(scope="all", limit=100_000)
+    exact = [s for s in sessions if s.session_id.lower() == t]
+    if exact:
+        return exact[0], ""
+    if len(t) >= 4:
+        hits = [s for s in sessions
+                if s.session_id.rsplit("-", 1)[-1].lower().startswith(t)]
+        if len(hits) == 1:
+            return hits[0], ""
+        if len(hits) > 1:
+            opts = ", ".join(f"{public_id(s.session_id)} ({s.display_title[:30]})" for s in hits[:5])
+            return None, f"'{token}' is ambiguous — matches {opts}"
+    return None, f"no session matches '{token}' — run `rockycode --resume` to browse"
+
+
+def project_current_path(project_id: str) -> Optional[Path]:
+    """Where a project lives NOW, per the registry — survives folder renames.
+    None when the registry has no entry (or the recorded path is gone)."""
+    entry = _load_registry().get(project_id) or {}
+    cur = entry.get("current")
+    if cur and Path(cur).is_dir():
+        return Path(cur)
+    for p in reversed(entry.get("paths", [])):
+        if Path(p).is_dir():
+            return Path(p)
+    return None
+
+
+def load_history(traj: Path) -> list[dict]:
+    """Reconstruct an engine message history from a trajectory file — exactly
+    the {role, content, tool_calls, tool_call_id} dicts that were sent to the
+    API (reasoning_content was never stored, so this is clean to replay)."""
+    history: list[dict] = []
+    try:
+        lines = Path(traj).read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return history
+    for ln in lines:
+        try:
+            rec = json.loads(ln)
+        except json.JSONDecodeError:
+            continue
+        if rec.get("kind") == "message":
+            history.append(rec["data"])
+    return history

rockycode/skills/architecture-viz/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: architecture-viz
+description: Visualize a neural-net block (attention, transformer, MoE, diffusion-LLM) as an artifact three linked ways — the paper diagram, the tensor-shape ribbon, and the user's PyTorch — cross-highlighted so hovering one lights the other two. Grounded in the real paper/code, never drawn from memory.
+---
+
+# architecture-viz — one block, three linked views
+
+The register (LOCKED — the user chose it after rejecting two others):
+**a recognizable paper diagram + a shape ribbon + the user's PyTorch code, all
+cross-highlighted.** Hover any box, shape-chip, or code line and the matching
+two light up. That link is the whole point — it's what turns an abstract figure
+into something the user can tie to the code they actually write.
+
+## Why exactly these three (do not drop any)
+
+- **Paper diagram** — the figure people recognize at a glance (e.g. Attention
+  Is All You Need's scaled-dot-product / multi-head). The anchor.
+- **Shape ribbon** — how the tensor shape changes step by step
+  (`(n,d) → (n,dₖ)×3 → (n,n) → (n,n) → (n,dₖ)`). This is the real value.
+- **PyTorch** — the language the user writes. NEVER show a formal language
+  (Lean/TorchLean syntax) as the teaching vehicle: a language they never
+  learned teaches nothing and frustrates. Proving stays a plain-English
+  footnote only: "want a shape proven for every n? `/research prove`".
+
+The three share a `data-step` id per stage; that shared id IS the cross-link.
+
+## Ground it — never draw from memory
+
+The diagram, shapes, and code must be DERIVED, not remembered — a subtly wrong
+architecture is worse than none (the user acts on it). Risk scales with how
+novel the block is:
+
+- **Standard transformer / attention** — well-known; still label real-vs-example.
+- **DeepSeek V3.2 MoE, diffusion-LLM, anything recent** — HIGH risk from memory.
+  First get ground truth: `read_file` the user's model code if they have it, or
+  `web_fetch` the paper / model card, and build the diagram + shapes + torch
+  from THAT. Diffusion-LLM is not autoregressive — its "forward" is a denoising
+  loop; don't force it into a transformer figure.
+- Put a provenance line at the bottom: `◆ derived` (what came from code/paper)
+  vs `◇ illustrative` (example sizes). Be honest about which.
+
+## Build it — rocky artifact rules (important)
+
+`create_artifact` takes BODY content only and STRIPS every `<style>` block, then
+applies rocky's light theme. So:
+
+- **No `<style>` block** — it will be deleted. Style with **inline `style=`**
+  attributes only (those survive), using rocky's light palette:
+  bg is themed for you; use `#efeafa` panels, `#9d7cd8`/`#7c5cba` strokes/accent,
+  `#6a4ca3` headings, `#2a2a38` text, `#ede6fb` for the lit/highlight state.
+- The cross-highlight is done in a **`<script>`** (scripts survive): on
+  `mouseenter`/`focus` of any `[data-step]`, set inline styles on every element
+  with the same `data-step`; revert on `mouseleave`/`blur`. No CSS `:hover`.
+- Self-contained: no CDN, no external fonts/images. Inline SVG for the diagram.
+- Use rocky's classes where they fit: `card`, `tag`/`tag-purple`/`tag-amber`.
+- Reuse the SAME artifact title to update in place on a re-run.
+
+## The scaffold
+
+`template.html` in this skill's directory is a complete, working example (scaled
+dot-product attention) in exactly this shape. **Copy it and adapt** the three
+panels for the block at hand — swap the SVG figure, the ribbon chips, and the
+torch lines, keeping the `data-step` ids matched across all three. Don't
+re-derive the highlight script; reuse it.
+
+## Multi-panel architectures
+
+For a whole model (MoE: router → experts → combine; a transformer layer:
+attention + FFN + residual/norm; diffusion: the denoising steps), give each
+sub-block its own diagram+ribbon+torch row, each internally linked, stacked top
+to bottom — one story, every stage labeled with the shape it carries.