dreamcontext 0.5.3 → 0.6.0

package/dist/skill-packs/excalidraw/scripts/lib/fractional-indexing.js

@@ -0,0 +1,311 @@
+// License: CC0 (no rights reserved).
+
+// This is based on https://observablehq.com/@dgreensp/implementing-fractional-indexing
+
+const BASE_62_DIGITS =
+  "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+
+// `a` may be empty string, `b` is null or non-empty string.
+// `a < b` lexicographically if `b` is non-null.
+// no trailing zeros allowed.
+// digits is a string such as '0123456789' for base 10.  Digits must be in
+// ascending character code order!
+/**
+ * @param {string} a
+ * @param {string | null | undefined} b
+ * @param {string} digits
+ * @returns {string}
+ */
+function midpoint(a, b, digits) {
+  const zero = digits[0];
+  if (b != null && a >= b) {
+    throw new Error(a + " >= " + b);
+  }
+  if (a.slice(-1) === zero || (b && b.slice(-1) === zero)) {
+    throw new Error("trailing zero");
+  }
+  if (b) {
+    // remove longest common prefix.  pad `a` with 0s as we
+    // go.  note that we don't need to pad `b`, because it can't
+    // end before `a` while traversing the common prefix.
+    let n = 0;
+    while ((a[n] || zero) === b[n]) {
+      n++;
+    }
+    if (n > 0) {
+      return b.slice(0, n) + midpoint(a.slice(n), b.slice(n), digits);
+    }
+  }
+  // first digits (or lack of digit) are different
+  const digitA = a ? digits.indexOf(a[0]) : 0;
+  const digitB = b != null ? digits.indexOf(b[0]) : digits.length;
+  if (digitB - digitA > 1) {
+    const midDigit = Math.round(0.5 * (digitA + digitB));
+    return digits[midDigit];
+  } else {
+    // first digits are consecutive
+    if (b && b.length > 1) {
+      return b.slice(0, 1);
+    } else {
+      // `b` is null or has length 1 (a single digit).
+      // the first digit of `a` is the previous digit to `b`,
+      // or 9 if `b` is null.
+      // given, for example, midpoint('49', '5'), return
+      // '4' + midpoint('9', null), which will become
+      // '4' + '9' + midpoint('', null), which is '495'
+      return digits[digitA] + midpoint(a.slice(1), null, digits);
+    }
+  }
+}
+
+/**
+ * @param {string} int
+ * @return {void}
+ */
+
+function validateInteger(int) {
+  if (int.length !== getIntegerLength(int[0])) {
+    throw new Error("invalid integer part of order key: " + int);
+  }
+}
+
+/**
+ * @param {string} head
+ * @return {number}
+ */
+
+function getIntegerLength(head) {
+  if (head >= "a" && head <= "z") {
+    return head.charCodeAt(0) - "a".charCodeAt(0) + 2;
+  } else if (head >= "A" && head <= "Z") {
+    return "Z".charCodeAt(0) - head.charCodeAt(0) + 2;
+  } else {
+    throw new Error("invalid order key head: " + head);
+  }
+}
+
+/**
+ * @param {string} key
+ * @return {string}
+ */
+
+function getIntegerPart(key) {
+  const integerPartLength = getIntegerLength(key[0]);
+  if (integerPartLength > key.length) {
+    throw new Error("invalid order key: " + key);
+  }
+  return key.slice(0, integerPartLength);
+}
+
+/**
+ * @param {string} key
+ * @param {string} digits
+ * @return {void}
+ */
+
+function validateOrderKey(key, digits) {
+  if (key === "A" + digits[0].repeat(26)) {
+    throw new Error("invalid order key: " + key);
+  }
+  // getIntegerPart will throw if the first character is bad,
+  // or the key is too short.  we'd call it to check these things
+  // even if we didn't need the result
+  const i = getIntegerPart(key);
+  const f = key.slice(i.length);
+  if (f.slice(-1) === digits[0]) {
+    throw new Error("invalid order key: " + key);
+  }
+}
+
+// note that this may return null, as there is a largest integer
+/**
+ * @param {string} x
+ * @param {string} digits
+ * @return {string | null}
+ */
+function incrementInteger(x, digits) {
+  validateInteger(x);
+  const [head, ...digs] = x.split("");
+  let carry = true;
+  for (let i = digs.length - 1; carry && i >= 0; i--) {
+    const d = digits.indexOf(digs[i]) + 1;
+    if (d === digits.length) {
+      digs[i] = digits[0];
+    } else {
+      digs[i] = digits[d];
+      carry = false;
+    }
+  }
+  if (carry) {
+    if (head === "Z") {
+      return "a" + digits[0];
+    }
+    if (head === "z") {
+      return null;
+    }
+    const h = String.fromCharCode(head.charCodeAt(0) + 1);
+    if (h > "a") {
+      digs.push(digits[0]);
+    } else {
+      digs.pop();
+    }
+    return h + digs.join("");
+  } else {
+    return head + digs.join("");
+  }
+}
+
+// note that this may return null, as there is a smallest integer
+/**
+ * @param {string} x
+ * @param {string} digits
+ * @return {string | null}
+ */
+
+function decrementInteger(x, digits) {
+  validateInteger(x);
+  const [head, ...digs] = x.split("");
+  let borrow = true;
+  for (let i = digs.length - 1; borrow && i >= 0; i--) {
+    const d = digits.indexOf(digs[i]) - 1;
+    if (d === -1) {
+      digs[i] = digits.slice(-1);
+    } else {
+      digs[i] = digits[d];
+      borrow = false;
+    }
+  }
+  if (borrow) {
+    if (head === "a") {
+      return "Z" + digits.slice(-1);
+    }
+    if (head === "A") {
+      return null;
+    }
+    const h = String.fromCharCode(head.charCodeAt(0) - 1);
+    if (h < "Z") {
+      digs.push(digits.slice(-1));
+    } else {
+      digs.pop();
+    }
+    return h + digs.join("");
+  } else {
+    return head + digs.join("");
+  }
+}
+
+// `a` is an order key or null (START).
+// `b` is an order key or null (END).
+// `a < b` lexicographically if both are non-null.
+// digits is a string such as '0123456789' for base 10.  Digits must be in
+// ascending character code order!
+/**
+ * @param {string | null | undefined} a
+ * @param {string | null | undefined} b
+ * @param {string=} digits
+ * @return {string}
+ */
+function generateKeyBetween(a, b, digits = BASE_62_DIGITS) {
+  if (a != null) {
+    validateOrderKey(a, digits);
+  }
+  if (b != null) {
+    validateOrderKey(b, digits);
+  }
+  if (a != null && b != null && a >= b) {
+    throw new Error(a + " >= " + b);
+  }
+  if (a == null) {
+    if (b == null) {
+      return "a" + digits[0];
+    }
+
+    const ib = getIntegerPart(b);
+    const fb = b.slice(ib.length);
+    if (ib === "A" + digits[0].repeat(26)) {
+      return ib + midpoint("", fb, digits);
+    }
+    if (ib < b) {
+      return ib;
+    }
+    const res = decrementInteger(ib, digits);
+    if (res == null) {
+      throw new Error("cannot decrement any more");
+    }
+    return res;
+  }
+
+  if (b == null) {
+    const ia = getIntegerPart(a);
+    const fa = a.slice(ia.length);
+    const i = incrementInteger(ia, digits);
+    return i == null ? ia + midpoint(fa, null, digits) : i;
+  }
+
+  const ia = getIntegerPart(a);
+  const fa = a.slice(ia.length);
+  const ib = getIntegerPart(b);
+  const fb = b.slice(ib.length);
+  if (ia === ib) {
+    return ia + midpoint(fa, fb, digits);
+  }
+  const i = incrementInteger(ia, digits);
+  if (i == null) {
+    throw new Error("cannot increment any more");
+  }
+  if (i < b) {
+    return i;
+  }
+  return ia + midpoint(fa, null, digits);
+}
+
+/**
+ * same preconditions as generateKeysBetween.
+ * n >= 0.
+ * Returns an array of n distinct keys in sorted order.
+ * If a and b are both null, returns [a0, a1, ...]
+ * If one or the other is null, returns consecutive "integer"
+ * keys.  Otherwise, returns relatively short keys between
+ * a and b.
+ * @param {string | null | undefined} a
+ * @param {string | null | undefined} b
+ * @param {number} n
+ * @param {string} digits
+ * @return {string[]}
+ */
+function generateNKeysBetween(a, b, n, digits = BASE_62_DIGITS) {
+  if (n === 0) {
+    return [];
+  }
+  if (n === 1) {
+    return [generateKeyBetween(a, b, digits)];
+  }
+  if (b == null) {
+    let c = generateKeyBetween(a, b, digits);
+    const result = [c];
+    for (let i = 0; i < n - 1; i++) {
+      c = generateKeyBetween(c, b, digits);
+      result.push(c);
+    }
+    return result;
+  }
+  if (a == null) {
+    let c = generateKeyBetween(a, b, digits);
+    const result = [c];
+    for (let i = 0; i < n - 1; i++) {
+      c = generateKeyBetween(a, c, digits);
+      result.push(c);
+    }
+    result.reverse();
+    return result;
+  }
+  const mid = Math.floor(n / 2);
+  const c = generateKeyBetween(a, b, digits);
+  return [
+    ...generateNKeysBetween(a, c, mid, digits),
+    c,
+    ...generateNKeysBetween(c, b, n - mid - 1, digits),
+  ];
+}
+
+module.exports = { BASE_62_DIGITS, generateKeyBetween, generateNKeysBetween };

package/dist/skill-packs/excalidraw/scripts/lib/imagesize.js

@@ -0,0 +1,65 @@
+// Minimal, dependency-free image dimension reader. Supports PNG, JPEG, GIF, WebP, BMP.
+// Returns { width, height, mime } or throws.
+const fs = require('fs');
+
+function fromBuffer(buf) {
+  // PNG: \x89PNG\r\n\x1a\n, IHDR width/height at bytes 16..24 (big-endian)
+  if (buf.length >= 24 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) {
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20), mime: 'image/png' };
+  }
+  // GIF: 'GIF87a' / 'GIF89a', width/height little-endian at bytes 6..10
+  if (buf.length >= 10 && buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46) {
+    return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8), mime: 'image/gif' };
+  }
+  // BMP
+  if (buf.length >= 26 && buf[0] === 0x42 && buf[1] === 0x4d) {
+    return { width: buf.readInt32LE(18), height: Math.abs(buf.readInt32LE(22)), mime: 'image/bmp' };
+  }
+  // WebP: RIFF....WEBP
+  if (buf.length >= 30 && buf.toString('ascii', 0, 4) === 'RIFF' && buf.toString('ascii', 8, 12) === 'WEBP') {
+    const fmt = buf.toString('ascii', 12, 16);
+    if (fmt === 'VP8 ') {
+      return { width: buf.readUInt16LE(26) & 0x3fff, height: buf.readUInt16LE(28) & 0x3fff, mime: 'image/webp' };
+    } else if (fmt === 'VP8L') {
+      const b = buf.readUInt32LE(21);
+      return { width: (b & 0x3fff) + 1, height: ((b >> 14) & 0x3fff) + 1, mime: 'image/webp' };
+    } else if (fmt === 'VP8X') {
+      const w = 1 + (buf[24] | (buf[25] << 8) | (buf[26] << 16));
+      const h = 1 + (buf[27] | (buf[28] << 8) | (buf[29] << 16));
+      return { width: w, height: h, mime: 'image/webp' };
+    }
+  }
+  // JPEG: scan SOFn markers
+  if (buf.length >= 4 && buf[0] === 0xff && buf[1] === 0xd8) {
+    let off = 2;
+    while (off < buf.length) {
+      if (buf[off] !== 0xff) { off++; continue; }
+      const marker = buf[off + 1];
+      // SOF0..SOF15 except DHT(c4) DAC(cc) RSTn — these carry frame dims
+      if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+        const height = buf.readUInt16BE(off + 5);
+        const width = buf.readUInt16BE(off + 7);
+        return { width, height, mime: 'image/jpeg' };
+      }
+      const len = buf.readUInt16BE(off + 2);
+      off += 2 + len;
+    }
+  }
+  throw new Error('unsupported or unrecognized image format');
+}
+
+function imageSize(filePath) {
+  // Read enough bytes for any header (JPEG may need more; read up to 256KB)
+  const fd = fs.openSync(filePath, 'r');
+  try {
+    const stat = fs.fstatSync(fd);
+    const n = Math.min(stat.size, 262144);
+    const buf = Buffer.alloc(n);
+    fs.readSync(fd, buf, 0, n, 0);
+    return fromBuffer(buf);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+module.exports = { imageSize, fromBuffer };

package/dist/skill-packs/excalidraw/scripts/lib/style.js

@@ -0,0 +1,130 @@
+// House style learned from the vault's presentation boards (MemoryOS High Level, Personalization
+// Module, Research). Excalifont (fontFamily 5), solid fills, always-rounded rects, 2px #1e1e1e ink,
+// Excalidraw's native pastel swatches used semantically. These helpers return ElementSpec[] for
+// build_excalidraw.js's buildExcalidraw({ elements }).
+
+const INK = '#1e1e1e';
+
+// semantic palette: { fill, stroke } — matches the vault's swatches and their meaning
+const PALETTE = {
+  green:      { fill: '#b2f2bb', stroke: '#2f9e44' }, // benefit / positive / go
+  paleGreen:  { fill: '#ebfbee', stroke: '#2f9e44' },
+  red:        { fill: '#ffc9c9', stroke: '#e03131' }, // problem / pain / risk
+  blue:       { fill: '#a5d8ff', stroke: '#1971c2' }, // system / neutral / flow node
+  paleBlue:   { fill: '#e7f5ff', stroke: '#1971c2' },
+  purple:     { fill: '#d0bfff', stroke: '#6741d9' }, // core service / special
+  palePurple: { fill: '#f3f0ff', stroke: '#6741d9' },
+  yellow:     { fill: '#ffec99', stroke: '#f08c00' }, // processing / attention
+  mint:       { fill: '#96f2d7', stroke: '#0c8599' }, // result / output
+  gray:       { fill: '#e9ecef', stroke: '#868e96' }, // muted / inactive
+};
+function pal(c) { return PALETTE[c] || { fill: c, stroke: INK }; }
+
+let _gc = 0;
+const newGroup = (hint) => `g${++_gc}-${hint || ''}`;
+const lines = (t) => String(t).split('\n').length;
+// word-wrapped line count at a given width — keeps card labels vertically centered when they wrap
+function wrapLineCount(text, fontSize, width) {
+  const perLine = Math.max(1, Math.floor(width / (fontSize * 0.52)));
+  let total = 0;
+  for (const ln of String(text).split('\n')) {
+    const words = ln.split(/\s+/).filter(Boolean);
+    if (!words.length) { total += 1; continue; }
+    let cur = 0, lc = 1;
+    for (const w of words) { const add = (cur ? 1 : 0) + w.length; if (cur + add > perLine && cur > 0) { lc++; cur = w.length; } else cur += add; }
+    total += lc;
+  }
+  return total;
+}
+
+// rounded card: filled rect + centered label, grouped so they move together
+function card(o) {
+  const { x, y, w = 260, h = 92, text = '', color = 'blue', fontSize = 20, stroke = INK, strokeWidth = 2, textColor = INK, roundness = true } = o;
+  const group = o.group || newGroup('card');
+  const p = pal(color);
+  const textH = wrapLineCount(text, fontSize, w) * fontSize * 1.25;
+  const ty = y + Math.max(6, (h - textH) / 2);
+  return [
+    { type: 'rectangle', x, y, width: w, height: h, strokeColor: stroke, backgroundColor: p.fill, fillStyle: 'solid', strokeWidth, roundness, group },
+    { type: 'text', x, y: ty, text, fontSize, color: textColor, width: w, align: 'center', fontFamily: 5, group },
+  ];
+}
+// small node (flow step) — card with tighter defaults
+function node(o) { return card(Object.assign({ w: 200, h: 64, fontSize: 18 }, o)); }
+
+// big plain section header (no box), like "Configuration" / "Flow"
+function sectionTitle(o) {
+  const { x, y, text, fontSize = 44, color = INK } = o;
+  return [{ type: 'text', x, y, text, fontSize, color, fontFamily: 5, width: Math.max(200, String(text).length * fontSize * 0.6) }];
+}
+
+// labeled connector arrow between two points (centers of cards, etc.)
+function connector(o) {
+  const { from, to, label, double = false, strokeColor = INK, strokeWidth = 2, dashed = false, labelColor = '#495057', fontSize = 16 } = o;
+  const out = [{ type: 'arrow', points: [from, to], strokeColor, strokeWidth, strokeStyle: dashed ? 'dashed' : 'solid', endArrow: 'arrow', startArrow: double ? 'arrow' : null }];
+  if (label) {
+    const mx = (from[0] + to[0]) / 2, my = (from[1] + to[1]) / 2;
+    const w = Math.max(40, String(label).length * fontSize * 0.62);
+    out.push({ type: 'text', x: mx - w / 2, y: my - fontSize - 4, text: label, fontSize, color: labelColor, width: w, align: 'center', fontFamily: 5 });
+  }
+  return out;
+}
+
+// side-annotation: short arrow from a node edge to a spec note (the "90sec / deepseek..." pattern)
+function annotate(o) {
+  const { from, to, text, fontSize = 16, color = '#495057' } = o;
+  return [
+    { type: 'arrow', points: [from, to], strokeColor: color, strokeWidth: 1.5, endArrow: 'arrow' },
+    { type: 'text', x: to[0] + 6, y: to[1] - fontSize * 0.6, text, fontSize, color, width: Math.max(80, String(text).split('\n')[0].length * fontSize * 0.62), align: 'left', fontFamily: 5 },
+  ];
+}
+
+// vertical stack of cards (benefit/risk columns)
+function column(o) {
+  const { x, y, w = 280, h = 70, gap = 16, fontSize = 18, color = 'green', items = [] } = o;
+  const out = [];
+  items.forEach((it, i) => {
+    const t = typeof it === 'string' ? it : it.text;
+    const c = (typeof it === 'object' && it.color) || color;
+    out.push(...card({ x, y: y + i * (h + gap), w, h, text: t, color: c, fontSize }));
+  });
+  return out;
+}
+
+// hub-and-spoke: central node + satellites with arrows (the "Personalization Layer" + APIs pattern)
+function hub(o) {
+  const { cx, cy, label, color = 'purple', rx = 64, ry = 44, radius = 170, spokes = [], spokeColor = 'blue', spokeRx = 30, spokeRy = 30, startAngle = -Math.PI / 2 } = o;
+  const group = newGroup('hub');
+  const out = [];
+  const p = pal(color);
+  out.push({ type: 'ellipse', x: cx - rx, y: cy - ry, width: rx * 2, height: ry * 2, strokeColor: p.stroke, backgroundColor: p.fill, fillStyle: 'solid', strokeWidth: 2 });
+  out.push({ type: 'text', x: cx - rx, y: cy - 10, text: label, fontSize: 16, color: INK, width: rx * 2, align: 'center', fontFamily: 5 });
+  const n = spokes.length;
+  spokes.forEach((s, i) => {
+    const a = startAngle + (i / Math.max(1, n)) * Math.PI * 2;
+    const sx = cx + Math.cos(a) * radius, sy = cy + Math.sin(a) * radius;
+    const c = (typeof s === 'object' && s.color) || spokeColor;
+    const t = typeof s === 'string' ? s : s.label;
+    const sp = pal(c);
+    out.push({ type: 'arrow', points: [[cx + Math.cos(a) * rx, cy + Math.sin(a) * ry], [sx - Math.cos(a) * spokeRx, sy - Math.sin(a) * spokeRy]], strokeColor: INK, strokeWidth: 2, endArrow: 'arrow' });
+    out.push({ type: 'ellipse', x: sx - spokeRx, y: sy - spokeRy, width: spokeRx * 2, height: spokeRy * 2, strokeColor: sp.stroke, backgroundColor: sp.fill, fillStyle: 'solid', strokeWidth: 2 });
+    out.push({ type: 'text', x: sx - spokeRx, y: sy - 8, text: t, fontSize: 14, color: INK, width: spokeRx * 2, align: 'center', fontFamily: 5 });
+  });
+  return out;
+}
+
+// bullet list as a single left-aligned block (their "Configuration" spec list pattern)
+function bullets(o) {
+  const { x, y, items = [], fontSize = 20, color = INK, bullet = '• ', width } = o;
+  const text = items.map((i) => bullet + i).join('\n');
+  return [{ type: 'text', x, y, text, fontSize, color, fontFamily: 5, width: width || Math.max(200, Math.max(...items.map((i) => i.length)) * fontSize * 0.6) }];
+}
+
+// center helpers for wiring connectors to card edges
+const center = (x, y, w, h) => [x + w / 2, y + h / 2];
+const rightOf = (x, y, w, h) => [x + w, y + h / 2];
+const leftOf = (x, y, w, h) => [x, y + h / 2];
+const bottomOf = (x, y, w, h) => [x + w / 2, y + h];
+const topOf = (x, y, w, h) => [x + w / 2, y];
+
+module.exports = { INK, PALETTE, pal, card, node, sectionTitle, connector, annotate, column, hub, bullets, center, rightOf, leftOf, bottomOf, topOf };

package/dist/skill-packs/video-watching/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: video-watching
+description: >-
+  Watch a video the way a human would — turn it into a time-mapped transcript
+  with the on-screen visuals (slides, UI, diagrams, text) described inline, then
+  reason about it. Triggers: "watch this video", "şu videoyu izle", "videoyu
+  analiz et", "transkript çıkar", "video transcript", "bu videoda ne var", or any
+  time the user hands over a video file/link. Produces a curated
+  <video>.transcript.md NEXT TO the source video, then continues per use-case
+  (marketing teardown, FTE analysis, knowledge capture, …).
+alwaysApply: false
+ruleType: "Tool Workflow"
+version: "1.0"
+---
+
+# Video Watching
+
+Turn a video into something an AI can fully reason about: a **time-mapped
+transcript** with **what's on screen described inline at the same timestamps**.
+The output is one self-contained file dropped **next to the source video**, so any
+model (our cloud, this session, anything) can read the whole video without the
+binary.
+
+The clever part: **transcript first, then YOU decide which frames to look at.**
+You don't blindly OCR every frame. You read the transcript, see where the speaker
+references something visual ("as you can see here", "this screen", "the chart"),
+look up that moment in `frames.json`, and open only those frames.
+
+## The loop (do these in order)
+
+### 0. Get the video
+Ask for the path or link if not given. Local files work today. Remote links
+(YouTube etc.) need `yt-dlp` (`brew install yt-dlp`) — the engine auto-downloads
+if it's installed.
+
+### 1. Run the engine (mechanical — one command)
+```bash
+.claude/skills/video-watching/scripts/transcribe.sh "/abs/path/to/video.mov"
+#   language auto-detects — no need to pass it. Override only if auto mislabels a
+#   short/ambiguous clip: ./transcribe.sh "/abs/path/clip.mp4" tr
+```
+This writes everything into `<video_dir>/<slug>.media/`:
+- `transcript.srt` / `.json` / `.txt` — timestamped transcript (large-v3-turbo)
+- `frames/anchor_first.jpg` / `anchor_last.jpg` — first + last frame, always captured
+  (short cut-heavy creatives carry the hook and CTA here; scene-detect misses both)
+- `frames/scene_*.jpg` — frames at each scene change (slides/UI transitions)
+- `frames/gap_*.jpg` — fill frames so no stretch > 10s goes unsampled (catches
+  static-but-important sections scene-detect misses: app demos, slides, CTAs)
+- `frames.json` — **the index you read**: `[{file, t, at, type}]`, sorted by time,
+  near-duplicate timestamps collapsed (anchors always kept)
+
+`audio.wav` is auto-deleted after transcription (it's a ~1.9MB/min whisper-only
+intermediate). The whole `*.media/` dir is gitignored — it stays next to the video
+as scratch but never enters the repo. Only `<slug>.transcript.md` is the keeper;
+delete a `.media/` folder anytime to reclaim disk (re-running regenerates it).
+
+### 2. Read the transcript
+Read `transcript.srt`. It carries the spoken content with `[mm:ss]` timing. Form a
+first-pass understanding of structure and topic.
+
+### 3. Decide which frames you NEED — then view them
+Read `frames.json`. For each moment where understanding depends on the visual —
+the speaker points at something, a slide/UI/diagram/number is on screen, or the
+transcript is ambiguous without the picture — pick the frame whose `at` is closest
+to that moment and **open it with the Read tool** (it renders images). Don't open
+all of them; open the ones that carry information. Talking-head stretches with
+nothing on screen need no frame.
+
+> Heuristic: the two `anchor` frames (first/last) almost always matter — the hook
+> and the CTA. Every `scene` frame is a candidate (the picture changed for a
+> reason). `gap` frames cover static stretches scene-detect skipped — often the
+> most informative part (an app demo or slide that doesn't "move"), so check them.
+
+**Need a frame the index doesn't have? Grab it on demand.** Scene-detect fires on
+motion, not on meaning — on fast-cut video the most informative moment often sits
+between the indexed frames. When the VO points at something ("look at this
+screen", a number, a result) and no indexed frame lands there, fetch that exact
+second yourself:
+```bash
+ffmpeg -y -loglevel error -ss <seconds> -i "<video>" -frames:v 1 -q:v 3 \
+  "<slug>.media/frames/grab_<mmss>.jpg"
+```
+This is the whole point of transcript-first: the frame set is yours to extend, not
+a fixed dump you're stuck with.
+
+### 4. Write the curated transcript NEXT TO the video
+Write `<video_dir>/<slug>.transcript.md` — the deliverable. One timeline, voice and
+visuals interleaved, every line timestamped:
+
+```markdown
+# <Video Title>
+source: <path or URL> · duration: <mm:ss> · transcribed: large-v3-turbo
+
+## Summary
+2–4 sentences: what this video is and what it's for.
+
+## Timeline
+- **[00:00]** <what's said>
+- **[00:06]** 🖼 <what's on screen — slide title, UI state, chart, on-screen text>
+- **[00:12]** <what's said> … 🖼 <visual if relevant>
+...
+
+## Visual notes
+- **[00:06]** Slide: "Funnel → Billing → Gateway → PSP" (4 layers)
+- ...
+```
+Rules: never invent content not in transcript or frames; mark anything uncertain;
+keep the source path in the header so the file stands alone.
+
+### 5. Hand off to the use-case
+Once the `.transcript.md` exists you know the video cold. Tell the user it's ready
+and ask what they want from it — the answer is domain-specific. Triage to the
+relevant dreamcontext skill (per the skill-triage rule) and load it:
+- **Marketing video** → teardown, hook/CTA analysis, "we could do X" (→ `growth` / `meta-marketing` skills)
+- **First-time-experience / app demo** → reconstruct the FTE flow, friction points (→ `design` / `onboarding-design`)
+- **Knowledge / training** → if it should persist for the project, hand the transcript to `dreamcontext knowledge` so it becomes durable context
+Don't guess the use-case — let the user direct it.
+
+## What this skill is NOT
+- Not a knowledge-base writer or ingestion pipeline. This skill produces the
+  transcript artifact; persisting it (chunking, embedding, ingest into a project's
+  long-term memory) is a separate, downstream concern — keep that boundary clean.
+- Not an auto-summarizer that skips the frames. The visual pass is the point —
+  that's what separates "watched the video" from "read the subtitles".
+
+## Setup (once per machine)
+```bash
+brew install whisper-cpp ffmpeg          # yt-dlp too, only for remote links
+# model: the engine prefers large-v3-turbo, falls back to large-v3 then medium.
+# pull turbo if missing:
+#   curl -L -o ~/.cache/whisper.cpp/models/ggml-large-v3-turbo.bin \
+#     https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin
+```
+`build_frame_index.py` is stdlib-only — no venv needed. Language **auto-detects**
+(whisper); only pass a code (`tr`, `en`) to force it on a short/ambiguous clip.
+
+## Files
+```
+.claude/skills/video-watching/
+├── SKILL.md                    ← you are here
+└── scripts/
+    ├── transcribe.sh           ← video → transcript + frames + frames.json (the engine)
+    ├── gap_fill.py             ← timestamps to fill scene-detect gaps (> MAX_GAP)
+    └── build_frame_index.py    ← frames/*.jpg → frames.json (pts_time index)
+```
+
+## Tuning
+- Too few frames on a slide-heavy video? `SCENE_THRESHOLD=0.1 ./transcribe.sh …`
+- Long static lecture over-sampled? Raise `MAX_GAP=20 ./transcribe.sh …` (default 10s).
+- Capturing too many near-identical frames? `DEDUPE_SEC=1.0 ./transcribe.sh …`
+- Force a model: `WHISPER_MODEL=/abs/ggml-large-v3.bin ./transcribe.sh …`