SKILL.md- the skill, written out in plain English

criteria:
  - name: calls_core_functions
    kind: deterministic
    check: "The execution log indicates calls to 'loadWalkthroughRecipe()', 'captureStep()', and 'annotateStep()'; otherwise, fail."
  - name: state_log_entry_created
    kind: deterministic
    check: "A new entry exists in 'state/log/pending-eval.ndjson' for this skill execution; otherwise, fail."
  - name: output_reflects_recipe
    kind: judge
    check: "The generated output accurately reflects the steps defined in the loaded walkthrough recipe."
  - name: annotations_are_relevant
    kind: judge
    check: "The annotations provided for each step are relevant, clear, and add value to the tutorial."

AGENTS.md- what the AI loads when this skill comes up

echo "[$(date -u +%FT%TZ)] walkthrough: <what was missing>" >> state/log/loader-feedback.log

echo "[$(date -u +%FT%TZ)] walkthrough: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-walkthrough/api.ts -- Recipe-driven annotated tutorial capture.
 *
 * The setpoint for "premium" lives in contract-gates.md. Every hand-review
 * tightens that file; the skill does not auto-tune.
 *
 * Usage:
 *   npx tsx api.ts run recipes/claude-code-first-session.json
 *   npx tsx api.ts capture recipes/claude-code-first-session.json
 *   npx tsx api.ts annotate out/<recipe>/<stamp>
 *   npx tsx api.ts gates out/<recipe>/<stamp>
 *   npx tsx api.ts lesson out/<recipe>/<stamp>
 */

import { execSync, spawnSync } from "child_process";
import {
  existsSync,
  mkdirSync,
  readFileSync,
  writeFileSync,
  readdirSync,
  copyFileSync,
  unlinkSync,
  realpathSync,
} from "fs";
import { dirname, join, basename, resolve } from "path";
import { fileURLToPath } from "url";
import { env } from "./env.ts";

const __dirname = dirname(fileURLToPath(import.meta.url));

// Reserved for v1 browser source: storage-state encryption key, auth cookies, etc.
// Imported now so the skill complies with the snappy env() contract from day one.
void env;

// --- Types ---

export type SourceKind = "macos-window" | "browser" | "file-render" | "terminal-exec";

export type AnnotationKind = "box" | "arrow" | "callout" | "pin";

export interface Annotation {
  kind: AnnotationKind;
  color?: string;
  box?: [number, number, number, number]; // x, y, w, h
  from?: [number, number]; // arrow start
  to?: [number, number]; // arrow end
  at?: [number, number]; // callout / pin anchor
  text?: string; // callout text
  number?: number; // pin number
}

export interface Step {
  id: string;
  title: string;
  caption: string;
  source: SourceKind;
  window_title?: string;
  window_id?: number;
  wait_for_enter?: boolean;
  annotations: Annotation[];
}

export interface Recipe {
  name: string;
  title: string;
  summary: string;
  steps: Step[];
}

export interface CaptureResult {
  step: Step;
  pngPath: string;
  width: number;
  height: number;
  capturedAt: string;
}

export interface GateResult {
  rule: string;
  pass: boolean;
  detail?: string;
  stepId?: string;
}

interface StepMeta {
  step: Step;
  width: number;
  height: number;
  capturedAt: string;
}

// --- Palette (snappy primary / secondary; stable defaults) ---

const PALETTE = {
  primary: "#FF4500",
  secondary: "#1E90FF",
  text: "#0B0C0F",
  bg: "#FFFFFF",
};

// --- Recipe loading ---

export function loadWalkthroughRecipe(path: string): Recipe {
  const raw = readFileSync(path, "utf-8");
  const parsed = JSON.parse(raw) as Recipe;
  if (!parsed.name || !parsed.title || !Array.isArray(parsed.steps) || parsed.steps.length === 0) {
    throw new Error(`Invalid recipe at ${path}: missing name/title/steps`);
  }
  for (const s of parsed.steps) {
    if (!s.id || !s.title || !s.caption || !s.source) {
      throw new Error(`Invalid step in ${path}: ${JSON.stringify(s)}`);
    }
    if (!Array.isArray(s.annotations)) {
      s.annotations = [];
    }
  }
  return parsed;
}

// --- Capture sources ---

function commandExists(cmd: string): boolean {
  return spawnSync("which", [cmd], { stdio: "ignore" }).status === 0;
}

function waitForEnter(step: Step): void {
  if (!process.stdin.isTTY) return;
  process.stderr.write(
    `\n[step ${step.id}] ${step.title}\n  ${step.caption}\n` +
      `Press ENTER, then switch focus to the target window within 3 seconds...`,
  );
  spawnSync("bash", ["-c", "read -r _ </dev/tty"], { stdio: "inherit" });
  for (let i = 3; i > 0; i--) {
    process.stderr.write(`\r  capturing in ${i}... `);
    execSync("sleep 1");
  }
  process.stderr.write("\r  capturing now!    \n");
}

// When running under SSH, macOS TCC denies screen-recording to the SSH session,
// so direct calls to peekaboo / screencapture fail with "operation not permitted".
// We route the capture command through `osascript -> Terminal do script`, which
// spawns the command under the Aqua login session that holds the Screen Recording
// TCC grant. The dispatched script self-miniaturizes its window so it isn't in
// the frame, runs the capture, and touches a done-marker we poll from SSH.
// See ~/.claude/skills/mac-mini-remote-ops for the broader pattern.
function isSshSession(): boolean {
  return !!(process.env.SSH_CONNECTION || process.env.SSH_CLIENT || process.env.SSH_TTY);
}

function runCaptureInAqua(cmd: string, outPath: string): void {
  const tag = `snappy-wt-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
  const done = `/tmp/${tag}.done`;
  const err = `/tmp/${tag}.err`;
  const scriptPath = `/tmp/${tag}.sh`;
  for (const p of [done, err]) {
    try { unlinkSync(p); } catch { /* ignore */ }
  }
  const body = [
    "#!/bin/bash",
    `exec 2> ${JSON.stringify(err)}`,
    // Hide the dispatched Terminal window so it never lands in a full-screen capture
    // and so peekaboo's "frontmost Terminal" targets the demo window, not this one.
    `osascript -e 'tell application "Terminal" to set miniaturized of front window to true' 2>/dev/null || true`,
    "sleep 0.7",
    cmd,
    `rc=$?`,
    `echo $rc > ${JSON.stringify(done)}`,
    // Close the dispatched window so it doesn't pile up across runs.
    `osascript -e 'tell application "Terminal" to close (first window whose tty is (do shell script "tty"))' 2>/dev/null || true`,
    `exit $rc`,
  ].join("\n");
  writeFileSync(scriptPath, body, { mode: 0o755 });

  const osa = `tell application "Terminal" to do script "bash ${scriptPath}"`;
  execSync(`osascript -e ${JSON.stringify(osa)}`, { stdio: "ignore" });

  const deadlineMs = Date.now() + 25_000;
  while (Date.now() < deadlineMs) {
    if (existsSync(done)) break;
    spawnSync("sleep", ["0.25"]);
  }
  if (!existsSync(done)) {
    throw new Error(
      `Aqua-dispatched capture timed out after 25s. Inspect ${scriptPath} / ${err}`,
    );
  }
  const rc = readFileSync(done, "utf-8").trim();
  if (rc !== "0") {
    const errTxt = existsSync(err) ? readFileSync(err, "utf-8") : "";
    throw new Error(`Aqua capture exited ${rc}. stderr:\n${errTxt}`);
  }
  if (!existsSync(outPath)) {
    const errTxt = existsSync(err) ? readFileSync(err, "utf-8") : "";
    throw new Error(`Aqua capture reported success but ${outPath} missing. stderr:\n${errTxt}`);
  }
}

function runCaptureCommand(cmd: string, outPath: string): void {
  if (isSshSession()) {
    runCaptureInAqua(cmd, outPath);
  } else {
    execSync(cmd, { stdio: "inherit" });
  }
}

function captureMacosWindow(step: Step, outPath: string): CaptureResult {
  if (step.wait_for_enter) waitForEnter(step);

  // Preferred path: peekaboo by app name (cleaner, no windowID dance).
  if (commandExists("peekaboo") && step.window_title) {
    const cmd = `peekaboo image --app ${JSON.stringify(step.window_title)} --path ${JSON.stringify(outPath)}`;
    runCaptureCommand(cmd, outPath);
  } else {
    // Fallback: resolve CGWindowID via AppleScript, then screencapture -l.
    let windowId = step.window_id;
    if (!windowId && step.window_title) {
      const script = `tell application "System Events" to return id of (first window of (first process whose name is "${step.window_title.replace(/"/g, '\\"')}"))`;
      try {
        const out = execSync(`osascript -e ${JSON.stringify(script)}`, {
          encoding: "utf-8",
        }).trim();
        windowId = Number(out);
      } catch (e) {
        throw new Error(
          `Could not resolve window for "${step.window_title}". Install peekaboo (brew install peekaboo) or set window_id explicitly. Original error: ${(e as Error).message}`,
        );
      }
    }
    if (!windowId) {
      throw new Error(
        `Step ${step.id}: macos-window source needs window_title or window_id`,
      );
    }
    const cmd = `screencapture -l ${windowId} -o -x ${JSON.stringify(outPath)}`;
    runCaptureCommand(cmd, outPath);
  }

  if (!existsSync(outPath)) {
    throw new Error(`Capture produced no file at ${outPath}`);
  }
  const dims = imageDims(outPath);
  return {
    step,
    pngPath: outPath,
    width: dims.w,
    height: dims.h,
    capturedAt: new Date().toISOString(),
  };
}

export function captureStep(step: Step, outDir: string): CaptureResult {
  const outPath = join(outDir, `step-${step.id}.raw.png`);
  switch (step.source) {
    case "macos-window":
      return captureMacosWindow(step, outPath);
    case "browser":
    case "file-render":
    case "terminal-exec":
      throw new Error(
        `Source "${step.source}" is not wired in v0. See snappy-walkthrough/SKILL.md "Phase status".`,
      );
    default:
      throw new Error(`Unknown source: ${step.source as string}`);
  }
}

function imageDims(path: string): { w: number; h: number } {
  // sips is built into macOS -- no extra deps.
  const out = execSync(`sips -g pixelWidth -g pixelHeight ${JSON.stringify(path)}`, {
    encoding: "utf-8",
  });
  const w = Number(out.match(/pixelWidth:\s*(\d+)/)?.[1] ?? 0);
  const h = Number(out.match(/pixelHeight:\s*(\d+)/)?.[1] ?? 0);
  if (!w || !h) throw new Error(`sips could not read dimensions of ${path}`);
  return { w, h };
}

// --- Annotation ---

function escapeXml(s: string): string {
  return s.replace(
    /[<>&"']/g,
    (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", '"': "&quot;", "'": "&apos;" })[c]!,
  );
}

function annotationToSvg(a: Annotation, idx: number): string {
  const color = a.color || PALETTE.primary;
  const sw = 4;
  switch (a.kind) {
    case "box": {
      if (!a.box) throw new Error(`box annotation ${idx} missing .box`);
      const [x, y, w, h] = a.box;
      return `<rect x="${x}" y="${y}" width="${w}" height="${h}" fill="none" stroke="${color}" stroke-width="${sw}" rx="8" />`;
    }
    case "arrow": {
      if (!a.from || !a.to) throw new Error(`arrow annotation ${idx} missing from/to`);
      const [x1, y1] = a.from;
      const [x2, y2] = a.to;
      return [
        `<defs><marker id="arrowhead-${idx}" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" fill="${color}" /></marker></defs>`,
        `<line x1="${x1}" y1="${y1}" x2="${x2}" y2="${y2}" stroke="${color}" stroke-width="${sw}" marker-end="url(#arrowhead-${idx})" />`,
      ].join("");
    }
    case "callout": {
      if (!a.at || !a.text) throw new Error(`callout annotation ${idx} missing at/text`);
      const [x, y] = a.at;
      const tw = Math.max(140, a.text.length * 11);
      const th = 44;
      return [
        `<rect x="${x}" y="${y}" width="${tw}" height="${th}" rx="10" fill="${PALETTE.bg}" stroke="${color}" stroke-width="${sw}" />`,
        `<text x="${x + 14}" y="${y + 29}" font-family="-apple-system, SF Pro Text, Helvetica, sans-serif" font-size="18" fill="${PALETTE.text}">${escapeXml(a.text)}</text>`,
      ].join("");
    }
    case "pin": {
      if (!a.at) throw new Error(`pin annotation ${idx} missing at`);
      const [x, y] = a.at;
      const n = a.number ?? idx + 1;
      return [
        `<circle cx="${x}" cy="${y}" r="24" fill="${color}" stroke="${PALETTE.bg}" stroke-width="3" />`,
        `<text x="${x}" y="${y + 8}" text-anchor="middle" font-family="-apple-system, SF Pro Text, Helvetica, sans-serif" font-size="24" font-weight="700" fill="${PALETTE.bg}">${n}</text>`,
      ].join("");
    }
  }
}

export function annotateStep(
  step: Step,
  capture: CaptureResult,
): { svgPath: string; pngPath: string; metaPath: string } {
  const outDir = dirname(capture.pngPath);
  const shapes = step.annotations.map(annotationToSvg).join("\n  ");

  // Full SVG with the base image as an href -- human-editable artifact.
  const fullSvg =
    `<svg xmlns="http://www.w3.org/2000/svg" width="${capture.width}" height="${capture.height}" viewBox="0 0 ${capture.width} ${capture.height}">\n` +
    `  <image href="${basename(capture.pngPath)}" width="${capture.width}" height="${capture.height}" />\n` +
    `  ${shapes}\n` +
    `</svg>\n`;
  const svgPath = join(outDir, `step-${step.id}.svg`);
  writeFileSync(svgPath, fullSvg);

  // Overlay-only SVG -- used for ImageMagick compositing.
  const overlaySvg =
    `<svg xmlns="http://www.w3.org/2000/svg" width="${capture.width}" height="${capture.height}">\n` +
    `  ${shapes}\n` +
    `</svg>\n`;
  const overlayPath = join(outDir, `step-${step.id}.overlay.svg`);
  writeFileSync(overlayPath, overlaySvg);

  const pngPath = join(outDir, `step-${step.id}.png`);
  if (commandExists("magick")) {
    execSync(
      `magick ${JSON.stringify(capture.pngPath)} \\( ${JSON.stringify(overlayPath)} \\) -composite ${JSON.stringify(pngPath)}`,
      { stdio: "inherit" },
    );
  } else {
    // Fallback: flat PNG is just a copy of the raw capture; SVG is authoritative.
    copyFileSync(capture.pngPath, pngPath);
    process.stderr.write(
      `[annotate] ImageMagick not found; step-${step.id}.svg is authoritative. brew install imagemagick to composite.\n`,
    );
  }

  const metaPath = join(outDir, `step-${step.id}.meta.json`);
  writeFileSync(
    metaPath,
    JSON.stringify(
      {
        step,
        width: capture.width,
        height: capture.height,
        capturedAt: capture.capturedAt,
      },
      null,
      2,
    ),
  );

  return { svgPath, pngPath, metaPath };
}

// --- Gates ---

interface GateRule {
  id: string;
  description: string;
  check: (outDir: string, metas: StepMeta[]) => GateResult[];
}

const BANNED = [/\blet'?s\b/i, /\bsimply\b/i, /\bjust\b/i, /\beasily\b/i, /\bseamlessly\b/i];

const GATES: GateRule[] = [
  {
    id: "step-ids-monotonic",
    description: "Step IDs are unique and sorted",
    check: (_d, metas) => {
      const ids = metas.map((m) => m.step.id);
      const sorted = [...ids].sort();
      const unique = new Set(ids).size === ids.length;
      const monotonic = ids.every((v, i) => v === sorted[i]);
      return [
        {
          rule: "step-ids-monotonic",
          pass: unique && monotonic,
          detail: `ids=${ids.join(",")}`,
        },
      ];
    },
  },
  {
    id: "caption-length",
    description: "Captions are <=12 words",
    check: (_d, metas) =>
      metas.map((m) => {
        const words = m.step.caption.trim().split(/\s+/).length;
        return {
          rule: "caption-length",
          stepId: m.step.id,
          pass: words <= 12,
          detail: `${words} words: ${m.step.caption}`,
        };
      }),
  },
  {
    id: "annotation-in-bounds",
    description: "Every annotation coordinate lies inside the image",
    check: (_d, metas) =>
      metas.flatMap((m) =>
        m.step.annotations.map((a, i) => {
          const pts: [number, number][] = [];
          if (a.box)
            pts.push([a.box[0], a.box[1]], [a.box[0] + a.box[2], a.box[1] + a.box[3]]);
          if (a.from) pts.push(a.from);
          if (a.to) pts.push(a.to);
          if (a.at) pts.push(a.at);
          const ok = pts.every(([x, y]) => x >= 0 && y >= 0 && x <= m.width && y <= m.height);
          return {
            rule: "annotation-in-bounds",
            stepId: m.step.id,
            pass: ok,
            detail: `annotation[${i}] ${a.kind}`,
          };
        }),
      ),
  },
  {
    id: "png-exists",
    description: "Every step produced a composited PNG",
    check: (d, metas) =>
      metas.map((m) => ({
        rule: "png-exists",
        stepId: m.step.id,
        pass: existsSync(join(d, `step-${m.step.id}.png`)),
      })),
  },
  {
    id: "banned-phrases",
    description: "Captions avoid let's/simply/just/easily/seamlessly",
    check: (_d, metas) =>
      metas.map((m) => {
        const hit = BANNED.find((r) => r.test(m.step.caption));
        return {
          rule: "banned-phrases",
          stepId: m.step.id,
          pass: !hit,
          detail: hit ? `banned: ${hit.source}` : m.step.caption,
        };
      }),
  },
];

export function runGates(outDir: string): GateResult[] {
  const metaFiles = readdirSync(outDir)
    .filter((f) => f.endsWith(".meta.json"))
    .sort();
  const metas: StepMeta[] = metaFiles.map((f) =>
    JSON.parse(readFileSync(join(outDir, f), "utf-8")),
  );
  const results = GATES.flatMap((g) => g.check(outDir, metas));
  const lines = results.map(
    (r) =>
      `${r.pass ? "PASS" : "FAIL"}  ${r.rule}${r.stepId ? ` [step ${r.stepId}]` : ""}${r.detail ? `  -- ${r.detail}` : ""}`,
  );
  writeFileSync(join(outDir, "gates.log"), lines.join("\n") + "\n");
  return results;
}

// --- Lesson block ---

export function buildLessonBlock(outDir: string, recipe?: Recipe): string {
  const metaFiles = readdirSync(outDir)
    .filter((f) => f.endsWith(".meta.json"))
    .sort();
  const metas: StepMeta[] = metaFiles.map((f) =>
    JSON.parse(readFileSync(join(outDir, f), "utf-8")),
  );
  const recipePath = join(outDir, "recipe.json");
  if (!recipe && existsSync(recipePath)) {
    recipe = JSON.parse(readFileSync(recipePath, "utf-8"));
  }
  const title = recipe?.title ?? "Walkthrough";
  const summary = recipe?.summary ?? "";
  const body = metas
    .map((m) => {
      const img = `step-${m.step.id}.png`;
      return `### ${m.step.title}\n\n![${m.step.caption}](./${img})\n\n${m.step.caption}\n`;
    })
    .join("\n");
  const md = `# ${title}\n\n${summary}\n\n${body}`;
  writeFileSync(join(outDir, "lesson.md"), md);
  return md;
}

// --- Full pipeline ---

function timestamp(): string {
  return new Date()
    .toISOString()
    .replace(/[:T]/g, "-")
    .replace(/\..+/, "");
}

export function runRecipe(recipe: Recipe, opts?: { outRoot?: string }): string {
  const outRoot = opts?.outRoot ?? join(__dirname, "out");
  const outDir = join(outRoot, recipe.name, timestamp());
  mkdirSync(outDir, { recursive: true });
  writeFileSync(join(outDir, "recipe.json"), JSON.stringify(recipe, null, 2));

  for (const step of recipe.steps) {
    const cap = captureStep(step, outDir);
    annotateStep(step, cap);
  }
  const gateResults = runGates(outDir);
  buildLessonBlock(outDir, recipe);

  const fails = gateResults.filter((r) => !r.pass);
  process.stderr.write(`\nOutputs: ${outDir}\n`);
  process.stderr.write(
    `Gates: ${gateResults.length - fails.length}/${gateResults.length} passed` +
      (fails.length ? ` -- see gates.log for FAIL lines\n` : `\n`),
  );
  return outDir;
}

// --- CLI ---

function main(): void {
  const [cmd, ...args] = process.argv.slice(2);
  switch (cmd) {
    case "run": {
      if (!args[0]) throw new Error("usage: run <recipe.json>");
      runRecipe(loadWalkthroughRecipe(resolve(args[0])));
      break;
    }
    case "capture": {
      if (!args[0]) throw new Error("usage: capture <recipe.json>");
      const recipe = loadWalkthroughRecipe(resolve(args[0]));
      const outDir = join(__dirname, "out", recipe.name, timestamp());
      mkdirSync(outDir, { recursive: true });
      writeFileSync(join(outDir, "recipe.json"), JSON.stringify(recipe, null, 2));
      for (const step of recipe.steps) captureStep(step, outDir);
      process.stdout.write(outDir + "\n");
      break;
    }
    case "annotate": {
      if (!args[0]) throw new Error("usage: annotate <out-dir>");
      const outDir = resolve(args[0]);
      const recipePath = join(outDir, "recipe.json");
      if (!existsSync(recipePath)) {
        throw new Error(`No recipe.json in ${outDir}`);
      }
      const recipe: Recipe = JSON.parse(readFileSync(recipePath, "utf-8"));
      for (const step of recipe.steps) {
        const raw = join(outDir, `step-${step.id}.raw.png`);
        if (!existsSync(raw)) {
          process.stderr.write(`[annotate] missing ${raw}, skipping\n`);
          continue;
        }
        const dims = imageDims(raw);
        annotateStep(step, {
          step,
          pngPath: raw,
          width: dims.w,
          height: dims.h,
          capturedAt: "",
        });
      }
      break;
    }
    case "gates": {
      if (!args[0]) throw new Error("usage: gates <out-dir>");
      const res = runGates(resolve(args[0]));
      const fails = res.filter((r) => !r.pass);
      process.stdout.write(`${res.length - fails.length}/${res.length} gates passed\n`);
      process.exit(fails.length ? 1 : 0);
    }
    case "lesson": {
      if (!args[0]) throw new Error("usage: lesson <out-dir>");
      process.stdout.write(buildLessonBlock(resolve(args[0])));
      break;
    }
    default:
      process.stderr.write(
        `usage: api.ts {run|capture|annotate|gates|lesson} <path>\n`,
      );
      process.exit(2);
  }
}

if ((() => { try { return import.meta.url === `file://${realpathSync(process.argv[1])}`; } catch { return false; } })()) main();

scripts- helper scripts it can run

prose-only skill - 1 inline code block live in SKILL.md above (no state/bin/ sidecar yet).

how we check it- the checks, plus the last 10 runs