dreamcontext 0.5.3 → 0.6.0

package/dist/skill-packs/video-watching/scripts/build_frame_index.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Build frames.json: map each extracted frame to its pts_time on the video timeline.
+
+Reads the per-frame pts_time dumps (scene_times.txt from ffmpeg metadata, gap_times.txt
+written by transcribe.sh) alongside the frames, pairs each timestamp with its
+zero-padded frame file in selection order, adds the first/last anchor frames, drops
+near-duplicate timestamps, and emits frames.json sorted by time.
+
+Stdlib only — no venv needed.
+Usage: build_frame_index.py <OUT_DIR> [DURATION_SEC]
+Env:   DEDUPE_SEC=0.4  collapse non-anchor frames closer than this to the kept one.
+"""
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+# metadata=print header line, e.g.: "frame:0    pts:321024  pts_time:12.852500"
+FRAME_RE = re.compile(r"frame:(\d+)\b.*?pts_time:([\d.]+)", re.DOTALL)
+DEDUPE_SEC = float(os.environ.get("DEDUPE_SEC", "0.4"))
+
+
+def parse_times(meta_file: Path) -> dict[int, float]:
+    """frame index (0-based, as ffmpeg numbers kept frames) -> pts_time seconds."""
+    if not meta_file.exists():
+        return {}
+    text = meta_file.read_text(errors="replace")
+    return {int(n): round(float(t), 2) for n, t in FRAME_RE.findall(text)}
+
+
+def collect(out_dir: Path, prefix: str, meta_name: str, kind: str) -> list[dict]:
+    times = parse_times(out_dir / "frames" / meta_name)
+    frames = sorted((out_dir / "frames").glob(f"{prefix}_*.jpg"))
+    # transcribe.sh names files 1-based (%04d starts at 0001); metadata frame: is 0-based.
+    return [{"file": f"frames/{f.name}", "t": times.get(i), "type": kind}
+            for i, f in enumerate(frames)]
+
+
+def anchors(out_dir: Path, duration: float) -> list[dict]:
+    rows = []
+    if (out_dir / "frames" / "anchor_first.jpg").exists():
+        rows.append({"file": "frames/anchor_first.jpg", "t": 0.0, "type": "anchor"})
+    if (out_dir / "frames" / "anchor_last.jpg").exists():
+        t = round(duration, 2) if duration > 0 else None
+        rows.append({"file": "frames/anchor_last.jpg", "t": t, "type": "anchor"})
+    return rows
+
+
+def fmt(t):
+    if t is None:
+        return "??:??"
+    m, s = divmod(int(t), 60)
+    return f"{m:02d}:{s:02d}"
+
+
+def dedupe(rows: list[dict]) -> list[dict]:
+    """Keep all anchors; drop a non-anchor frame within DEDUPE_SEC of the last kept."""
+    kept: list[dict] = []
+    last_t = None
+    for r in rows:
+        is_anchor = r["type"] == "anchor"
+        if (not is_anchor and last_t is not None and r["t"] is not None
+                and abs(r["t"] - last_t) < DEDUPE_SEC):
+            continue
+        kept.append(r)
+        if r["t"] is not None:
+            last_t = r["t"]
+    return kept
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("usage: build_frame_index.py <OUT_DIR> [DURATION_SEC]", file=sys.stderr)
+        return 2
+    out_dir = Path(sys.argv[1])
+    duration = float(sys.argv[2]) if len(sys.argv) > 2 else 0.0
+
+    rows = collect(out_dir, "scene", "scene_times.txt", "scene")
+    rows += collect(out_dir, "gap", "gap_times.txt", "gap")
+    rows += anchors(out_dir, duration)
+    # Sort by time; unknown timestamps sink to the end.
+    rows.sort(key=lambda r: (r["t"] is None, r["t"] or 0.0))
+    rows = dedupe(rows)
+    for r in rows:
+        r["at"] = fmt(r["t"])
+
+    (out_dir / "frames.json").write_text(json.dumps(rows, ensure_ascii=False, indent=2))
+    n_anchor = sum(r["type"] == "anchor" for r in rows)
+    print(f"   frames.json: {len(rows)} frames indexed ({n_anchor} anchors, dedupe<{DEDUPE_SEC}s)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/skill-packs/video-watching/scripts/gap_fill.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Print timestamps that keep every unsampled stretch of the video <= MAX_GAP.
+
+Scene-detect fires on motion, not on meaning — so static-but-information-rich
+sections (app demos, slides, talking heads) get no frame. This reads the scene
+timestamps, bounds them with 0 and the video duration, and for any gap larger than
+MAX_GAP emits evenly-spaced fill timestamps so no stretch goes unsampled.
+
+Stdlib only. Usage: gap_fill.py <OUT_DIR> <DURATION_SEC> [MAX_GAP_SEC]
+Prints one timestamp (seconds, 2dp) per line — transcribe.sh grabs each frame.
+"""
+import re
+import sys
+from pathlib import Path
+
+FRAME_RE = re.compile(r"frame:(\d+)\b.*?pts_time:([\d.]+)", re.DOTALL)
+
+
+def main() -> int:
+    if len(sys.argv) < 3:
+        print("usage: gap_fill.py <OUT_DIR> <DURATION_SEC> [MAX_GAP_SEC]", file=sys.stderr)
+        return 2
+    out_dir = Path(sys.argv[1])
+    duration = float(sys.argv[2])
+    max_gap = float(sys.argv[3]) if len(sys.argv) > 3 else 10.0
+    if duration <= 0 or max_gap <= 0:
+        return 0
+
+    meta = out_dir / "frames" / "scene_times.txt"
+    scene_times = []
+    if meta.exists():
+        scene_times = [round(float(t), 2)
+                       for _, t in FRAME_RE.findall(meta.read_text(errors="replace"))]
+
+    bounds = sorted(set([0.0] + scene_times + [round(duration, 2)]))
+    for a, b in zip(bounds, bounds[1:]):
+        gap = b - a
+        n = int(gap // max_gap)            # inserts that split the gap into <= max_gap pieces
+        for k in range(1, n + 1):
+            print(f"{a + gap * k / (n + 1):.2f}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/skill-packs/video-watching/scripts/transcribe.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# Video -> time-mapped transcript + significant frames (with per-frame timestamps).
+# whisper.cpp (large-v3-turbo by default) for the transcript, ffmpeg for frames.
+#
+# This is the MECHANICAL step. It produces artifacts; it does NOT understand the
+# video. Claude reads the outputs (transcript + frames.json), decides which frames
+# matter, views them, and writes the curated <video>.transcript.md (see SKILL.md).
+#
+# Usage: ./transcribe.sh "/abs/path/to/video.mov" [lang]
+#   lang: whisper language code. DEFAULT 'auto' — whisper detects it, no need to pass.
+#         Force only if auto mislabels a short/ambiguous clip (e.g. 'tr', 'en').
+#
+# Env overrides:
+#   WHISPER_MODEL=/abs/path/ggml-*.bin   force a specific model
+#   OUT_DIR=/abs/path                    where artifacts go (default: <video_dir>/<slug>.media)
+#   SCENE_THRESHOLD=0.15                 ffmpeg scene-change sensitivity (lower = more frames)
+#   MAX_GAP=10                           guarantee a frame at least every N seconds (fills static sections)
+#
+# Outputs (in OUT_DIR):
+#   transcript.srt       timestamped segments (human-friendly)
+#   transcript.json/.txt/.vtt
+#   frames/scene_*.jpg   frames at scene-change > SCENE_THRESHOLD
+#   frames/gap_*.jpg     fill frames where scene-detect left a stretch > MAX_GAP unsampled
+#   frames/anchor_first.jpg / anchor_last.jpg  always-captured first + last frame
+#   frames.json          [{file, t, at, type}] — each frame's pts_time, sorted (Claude reads this)
+#   source-meta.txt      ffprobe dump  (audio.wav is created then deleted after transcription)
+set -euo pipefail
+
+VIDEO="${1:?Usage: transcribe.sh <video> [lang]}"
+LANG_CODE="${2:-auto}"   # whisper auto-detects the spoken language unless overridden
+SCENE_THRESHOLD="${SCENE_THRESHOLD:-0.15}"
+MAX_GAP="${MAX_GAP:-10}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# --- remote link? download with yt-dlp (local files skip this) ------------------
+if [[ "$VIDEO" =~ ^https?:// ]]; then
+  command -v yt-dlp >/dev/null || { echo "remote link needs yt-dlp: brew install yt-dlp" >&2; exit 1; }
+  DL_DIR="${OUT_DIR:-$PWD}/_download"; mkdir -p "$DL_DIR"
+  echo "==> downloading remote video with yt-dlp"
+  yt-dlp -o "$DL_DIR/%(title)s.%(ext)s" "$VIDEO"
+  VIDEO="$(ls -t "$DL_DIR"/* | head -1)"
+  echo "==> downloaded: $VIDEO"
+fi
+[ -f "$VIDEO" ] || { echo "video not found: $VIDEO" >&2; exit 1; }
+
+# --- model: prefer turbo, then large-v3, then medium (override with WHISPER_MODEL)
+pick_model() {
+  if [ -n "${WHISPER_MODEL:-}" ]; then printf '%s' "$WHISPER_MODEL"; return; fi
+  local p
+  for p in \
+    "$HOME/.cache/whisper.cpp/models/ggml-large-v3-turbo.bin" \
+    "$HOME/.cache/openwhispr/whisper-models/ggml-large-v3-turbo.bin" \
+    "$HOME/.cache/whisper.cpp/models/ggml-large-v3.bin" \
+    "$HOME/.cache/whisper.cpp/models/ggml-medium.bin" \
+    "$HOME/.cache/openwhispr/whisper-models/ggml-medium.bin"; do
+    [ -f "$p" ] && { printf '%s' "$p"; return; }
+  done
+  printf ''
+}
+MODEL="$(pick_model)"
+[ -n "$MODEL" ] && [ -f "$MODEL" ] || {
+  echo "no whisper model found. Install one, e.g.:" >&2
+  echo "  curl -L -o ~/.cache/whisper.cpp/models/ggml-large-v3-turbo.bin \\" >&2
+  echo "    https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin" >&2
+  echo "  or set WHISPER_MODEL=/abs/path/ggml-*.bin" >&2
+  exit 1
+}
+
+WHISPER_BIN="$(command -v whisper-cli || command -v whisper-cpp || command -v main || true)"
+[ -n "$WHISPER_BIN" ] || { echo "whisper.cpp binary not found (brew install whisper-cpp)" >&2; exit 1; }
+command -v ffmpeg >/dev/null || { echo "ffmpeg not found (brew install ffmpeg)" >&2; exit 1; }
+
+# --- where artifacts go: next to the video by default ---------------------------
+SRC_DIR="$(cd "$(dirname "$VIDEO")" && pwd)"
+SLUG="$(basename "$VIDEO")"; SLUG="${SLUG%.*}"
+SLUG="$(echo "$SLUG" | tr ' ' '-' | tr -cd '[:alnum:]._-' | sed 's/--*/-/g; s/^-//; s/-$//')"
+OUT="${OUT_DIR:-$SRC_DIR/$SLUG.media}"
+mkdir -p "$OUT/frames"
+# even-dim scaling keeps the mjpeg encoder happy on odd-width sources
+SCALE="scale=trunc(iw/2)*2:trunc(ih/2)*2"
+
+echo "==> [$SLUG] probing"
+ffprobe -v error -show_entries format=duration,size:stream=codec_type,codec_name,width,height \
+  -of default=noprint_wrappers=1 "$VIDEO" | tee "$OUT/source-meta.txt"
+DURATION="$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$VIDEO" 2>/dev/null | head -1)"
+DURATION="${DURATION:-0}"
+
+echo "==> [$SLUG] extracting 16kHz mono audio"
+ffmpeg -y -loglevel error -i "$VIDEO" -ar 16000 -ac 1 -c:a pcm_s16le "$OUT/audio.wav"
+
+echo "==> [$SLUG] transcribing with $(basename "$MODEL") (lang=$LANG_CODE)"
+"$WHISPER_BIN" -m "$MODEL" -f "$OUT/audio.wav" -l "$LANG_CODE" \
+  --output-txt --output-srt --output-vtt --output-json -of "$OUT/transcript" -pp
+# audio.wav is a pure whisper intermediate (~1.9MB/min) — drop it once the transcript exists.
+rm -f "$OUT/audio.wav"
+
+echo "==> [$SLUG] extracting scene-change frames (scene > $SCENE_THRESHOLD)"
+# pix_fmt yuvj420p avoids mjpeg "non full-range YUV" failures on screen recordings;
+# even-dim scaling keeps the encoder happy on odd-width sources.
+# metadata=print dumps each kept frame's pts_time so frames map back to the timeline.
+ffmpeg -y -loglevel error -i "$VIDEO" \
+  -vf "select='gt(scene,$SCENE_THRESHOLD)',metadata=print:file=$OUT/frames/scene_times.txt,scale=trunc(iw/2)*2:trunc(ih/2)*2" \
+  -fps_mode vfr -pix_fmt yuvj420p -q:v 3 "$OUT/frames/scene_%04d.jpg" || true
+
+echo "==> [$SLUG] capturing first + last anchor frames"
+# Short, cut-heavy creatives carry the most information in the opening hook and the
+# closing CTA — but scene-detect rarely fires at t=0 or t=end. Always grab both.
+ffmpeg -y -loglevel error -i "$VIDEO" -vf "$SCALE" -frames:v 1 -q:v 3 \
+  "$OUT/frames/anchor_first.jpg" || true
+ffmpeg -y -loglevel error -sseof -0.5 -i "$VIDEO" -vf "$SCALE" -update 1 -frames:v 1 -q:v 3 \
+  "$OUT/frames/anchor_last.jpg" || true
+
+echo "==> [$SLUG] filling gaps > ${MAX_GAP}s (static sections scene-detect misses)"
+# scene-detect fires on motion, not meaning; a static-but-information-rich stretch
+# (app demo, slide, talking head) gets no frame. gap_fill.py returns timestamps that
+# keep every unsampled stretch <= MAX_GAP; we grab each and log its known pts_time.
+: > "$OUT/frames/gap_times.txt"
+gi=0
+while IFS= read -r t; do
+  [ -z "$t" ] && continue
+  printf -v fn "gap_%04d.jpg" "$((gi + 1))"
+  if ffmpeg -y -loglevel error -ss "$t" -i "$VIDEO" -vf "$SCALE" -frames:v 1 -q:v 3 "$OUT/frames/$fn"; then
+    echo "frame:$gi pts_time:$t" >> "$OUT/frames/gap_times.txt"
+    gi=$((gi + 1))
+  fi
+done < <(python3 "$SCRIPT_DIR/gap_fill.py" "$OUT" "$DURATION" "$MAX_GAP")
+echo "    gap frames added: $gi"
+
+echo "==> [$SLUG] building frames.json (timestamp index, dedup near-dups)"
+python3 "$SCRIPT_DIR/build_frame_index.py" "$OUT" "$DURATION"
+
+NFRAMES="$(ls -1 "$OUT/frames"/*.jpg 2>/dev/null | wc -l | tr -d ' ')"
+echo "==> [$SLUG] DONE"
+echo "    transcript: $OUT/transcript.srt"
+echo "    frames:     $NFRAMES  (index: $OUT/frames.json)"
+echo "    next: Claude reads transcript + frames.json, views key frames, writes the curated transcript.md"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dreamcontext",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "dreamcontext — the persistent brain for your AI agents. Remembers what you built, knows how your project works.",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
     "agents",
     "README.md",
     "LICENSE",
+    "NOTICE",
     "install.sh"
   ],
   "scripts": {
@@ -23,6 +24,7 @@
     "dev:dashboard": "cd dashboard && npm run dev",
     "test": "vitest",
     "test:e2e": "playwright test",
+    "diagrams": "node scripts/diagrams/build-all.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -36,7 +38,7 @@
     "gemini",
     "llm"
   ],
-  "license": "MIT",
+  "license": "Apache-2.0",
   "engines": {
     "node": ">=18"
   },

package/skill/SKILL.md

@@ -318,7 +318,9 @@ Sleep debt reminders are injected on every user message (via UserPromptSubmit ho
      - user hint mentions knowledge or a feature
    - When unsure, **over-fire** `sleep-product` — it no-ops cheaply.
    - Pass each specialist a small text brief in its prompt: epoch, session IDs, active task slugs, planning version, signals relevant to that specialist, optional user hint. Do **not** include transcript content — specialists call `dreamcontext transcript distill <id>` themselves.
+   - **Consolidation discipline (remind both specialists in the brief):** prefer *updating/extending* an existing entity over creating a new one. `sleep-tasks` folds a smaller slice into the task that already covers it (broaden its title + insert sub-items) rather than forking a duplicate or a needless sub-task; `sleep-product` keeps similar verticals/brands/topics in the fewest knowledge files, splitting only on a sharp topical boundary that sharpens tags. Duplicate tasks and fragmented near-duplicate knowledge are the top consolidation failure modes — but genuinely separate concerns/topics still get their own task/file.
 5. Wait for all specialist reports. Each returns a short structured report.
+5a. Run `dreamcontext reflect` — each candidate is a term seen across multiple sessions not yet in soul/user/memory/knowledge; promote into `2.memory.md` or a knowledge file ONLY if genuinely load-bearing; most are noise, discard; NEVER auto-promote.
 6. Marketing pass if `_dream_context/marketing/` exists: `dreamcontext mk rem-sleep`.
 7. Council promote check: `dreamcontext council list --unpromoted` — promote if user engaged positively.
 8. `dreamcontext sleep done "<one-paragraph summary stitched from specialist reports>"` — clears pre-epoch state, resets debt.
@@ -505,6 +507,7 @@ All commands prefixed with `dreamcontext`. For reading/searching, use native too
 | `trigger add "<when>" "<remind>" [-m max_fires] [-s source]` | Create contextual trigger |
 | `trigger list` | Show active triggers |
 | `trigger remove <id>` | Remove a trigger |
+| `reflect [--min-sessions N] [--max N] [--write]` | Detect recurring cross-session terms not yet in knowledge/memory as CANDIDATES; `--write` persists to `state/.reflection.md` |
 | `transcript distill <session_id>` | Extract high-signal content from session transcript |
 | `sleep status` | Show sleep state and history |
 | `sleep add <score> "<desc>"` | Manual debt add |
@@ -523,6 +526,8 @@ All commands prefixed with `dreamcontext`. For reading/searching, use native too
 | `snapshot --tokens` | Estimate snapshot token count |
 | `doctor` | Validate `_dream_context/` structure |
 | `install-skill` | Install skill + hooks |
+| `config show` | Print project config (platforms, packs, native-memory state) |
+| `config native-memory <enable\|disable>` | Toggle Claude's native auto-memory; disabled by default so dreamcontext owns project memory |
 | `upgrade [--check]` | Update the dreamcontext CLI itself to the latest npm release |
 
 Feature insert sections: `changelog`, `notes`, `technical_details`, `constraints`, `user_stories`, `acceptance_criteria`, `why`

package/skill-packs/catalog.json

@@ -352,6 +352,50 @@
         "security"
       ],
       "alwaysApply": false
+    },
+    {
+      "name": "excalidraw",
+      "file": "excalidraw/SKILL.md",
+      "description": "Generate or extend Obsidian Excalidraw (.excalidraw.md) boards — lay out images/screenshots, text, shapes, arrows, frames, lanes and grids — by writing a small JSON spec and running a deterministic script that emits valid plugin markup (near-zero tokens, always renders). Embeds local images via the plugin's sha1 wikilink trick (no base64). Triggers: 'draw this in excalidraw', 'make an excalidraw board', 'excalidraw diagram', 'funnel map board', 'embed screenshots into excalidraw', 'excalidraw çiz', 'excalidraw board oluştur'.",
+      "tags": [
+        "excalidraw",
+        "obsidian",
+        "diagram",
+        "board",
+        "visualization",
+        "screenshots",
+        "funnel-map",
+        "drawing"
+      ],
+      "alwaysApply": false,
+      "bundleDir": true
+    },
+    {
+      "name": "video-watching",
+      "file": "video-watching/SKILL.md",
+      "description": "Load when the user hands over a video file/link or asks to watch/analyze a video, extract a transcript, or 'bu videoda ne var'. Turns a video into a time-mapped transcript with on-screen visuals (slides, UI, charts, text) described inline, then reasons about it. Triggers: 'watch this video', 'videoyu izle/analiz et', 'transkript çıkar', 'video transcript'.",
+      "tags": [
+        "video",
+        "transcript",
+        "whisper",
+        "ffmpeg",
+        "frames",
+        "ocr",
+        "marketing-teardown",
+        "media"
+      ],
+      "alwaysApply": false,
+      "bundleDir": true,
+      "requiresBinaries": [
+        "whisper-cpp",
+        "ffmpeg",
+        "yt-dlp (remote links only)"
+      ],
+      "crossPackDeps": [
+        "growth (marketing-video teardown handoff)",
+        "meta-marketing (ad-creative teardown handoff)",
+        "design/onboarding-design (app-demo / FTE reconstruction handoff)"
+      ]
     }
   ],
   "agents": [

package/skill-packs/excalidraw/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: excalidraw
+description: >-
+  Generate or extend Obsidian Excalidraw (.excalidraw.md) boards in this vault — lay out
+  images/screenshots, text labels, shapes, arrows, frames, lanes and grids — by writing a small
+  JSON spec and letting a deterministic script emit valid plugin markup (so it costs ~no tokens and
+  always renders). Embeds local images via the plugin's sha1 wikilink trick (no base64). Triggers:
+  '/excalidraw', 'draw this in excalidraw', 'make an excalidraw board', 'excalidraw diagram',
+  'funnel map board', 'embed screenshots into excalidraw', 'add images to an excalidraw file',
+  'excalidraw çiz', 'excalidraw board oluştur', 'ekran görüntülerini excalidraw a ekle'.
+---
+
+# Excalidraw board generator (Obsidian)
+
+Write `.excalidraw.md` files that render natively in this vault's Obsidian Excalidraw plugin.
+**Do not hand-author the scene JSON.** Build a small spec and run the generator — it produces the
+frontmatter, `## Text Elements`, `## Embedded Files`, and the `%% ## Drawing … %%` JSON, with
+correct sha1 image links, fractional z-indices, and deterministic seeds (clean git diffs).
+
+## The one trick that makes images work
+An image element references `fileId` = **sha1 of the image file**. The `## Embedded Files` section
+maps `<sha1>: [[image.png]]`. The plugin resolves the picture from the vault via that wikilink —
+**no base64 needed.** The generator computes the sha1 and writes both sides for you.
+
+## Usage
+
+### CLI (most common)
+```bash
+node .claude/skills/excalidraw/scripts/build_excalidraw.js <spec.json> [--out <path.excalidraw.md>]
+```
+Write a spec JSON, then run it. The script prints `elements/images/texts` counts on success.
+
+### JS API (for pipelines that generate many boards)
+```js
+const { buildExcalidraw, lane, grid } = require('.../scripts/build_excalidraw.js');
+buildExcalidraw({ out, elements: [ ...lane({ title, images, x, y, thumbW }) ] });
+```
+
+## Spec schema
+```jsonc
+{
+  "out": "/abs/path/Board.excalidraw.md",   // required (or pass --out)
+  "vaultRoot": "/abs/vault",                  // optional; auto-detected by walking up to `.obsidian`
+  "attachDir": "Attachments",                 // external images get copied here (relative to board dir)
+  "wikilinkMode": "basename",                 // "basename" (default) or "path" (vault-relative)
+  "background": "#ffffff",
+  "elements": [ /* ElementSpec… */ ]
+}
+```
+
+### Element types
+- `text`     — `{ x, y, text, fontSize?, color?, width?, align?, fontFamily? }` (fontFamily 1=hand, 2=normal, 3=code). **Set `width` for any caption/label that must stay inside a column or card** → the text WRAPS to that width (autoResize off) and its height is computed from the wrapped line count. Omit `width` only for short single-line text you want sized to content (it renders on one line and will overlap neighbours if long).
+- `image`    — `{ x, y, path, width? , height? }` — give ONE of width/height; the other is derived from aspect. `path` is an absolute file path.
+- `rectangle`/`ellipse`/`diamond` — `{ x, y, width, height, strokeColor?, backgroundColor?, fillStyle?(solid|hachure|cross-hatch), strokeWidth?, roundness?(true=rounded) }`
+- `line`/`arrow` — `{ points: [[x1,y1],[x2,y2],…], strokeColor?, strokeWidth?, endArrow?, startArrow? }` (coords are absolute; arrows default to an end arrowhead)
+- `frame`    — `{ x, y, width, height, name }`
+
+### Layout helpers (JS API) — dimension-aware, never gap/overlap
+Both read each image's real pixel size at layout time, so every caption **hugs its own image's bottom**
+(no fixed-aspect guess → no big gap under a short screenshot, no overlap under a tall one). They return
+an `ElementSpec[]` you spread with `...`, and that array also carries `.height`, `.width`, and **`.nextY`**
+so you can stack lanes/grids/sections without doing height math by hand.
+- `lane({ title, images:[{path, caption}], x, y, thumbW, gap, captionSize, captionGap })` → titled horizontal
+  strip; caption wraps to `thumbW` under each thumb. Ideal for **funnel step maps** (one lane per funnel).
+- `grid({ images:[{path, caption}], x, y, cols, thumbW, gapX, gapY, captionSize })` → wrapping grid; each
+  row sizes to its tallest image, each caption hugs its image.
+- `thumbHeight(path, thumbW)` → the on-board height a thumbnail of width `thumbW` will get (exported for
+  custom layouts that need to place captions/rows themselves).
+```js
+const a = lane({ title:'Pilates', images, x:60, y:120, thumbW:150 });
+const b = lane({ title:'Fasting', images2, x:60, y:a.nextY, thumbW:150 }); // stacks under `a`, no overlap
+buildExcalidraw({ out, elements:[ ...a, ...b ] });
+```
+House-style `card()` labels are also vertically centered correctly even when the label **wraps** to the card width.
+
+## House style (`scripts/lib/style.js`) — learned from the vault's presentation boards
+Match the team's look by default. The builder now defaults text to **Excalifont (fontFamily 5)**.
+`style.js` exports the palette + ready-made builders so boards look hand-drawn and consistent:
+
+- **`PALETTE`** (semantic, = Excalidraw's native swatches): `green` benefit/go · `red` pain/risk ·
+  `blue` system/flow · `purple` core service · `yellow` processing · `mint` result · `gray` muted.
+  Each is `{ fill, stroke }`. `INK` = `#1e1e1e` (the default 2px card outline). Fills are **solid**,
+  rects are **always rounded**.
+- **`card({x,y,w,h,text,color,fontSize})`** → rounded filled rect + centered label, grouped (move as one).
+- **`node(...)`** → smaller card for flow steps.
+- **`sectionTitle({x,y,text,fontSize})`** → big plain header (no box), like "Configuration" / "Flow".
+- **`connector({from,to,label,double,dashed})`** → labeled arrow between two points.
+- **`annotate({from,to,text})`** → short arrow to a side-spec note (the "90sec / deepseek…" pattern).
+- **`column({x,y,items,color})`** → vertical stack of cards (benefit/risk lists). `items` may be
+  strings or `{text,color}`.
+- **`hub({cx,cy,label,spokes})`** → central node + satellites with arrows (the "Layer + APIs" pattern).
+- **`bullets({x,y,items})`** → one left-aligned bulleted text block (their spec-list pattern).
+- Edge helpers `center/rightOf/leftOf/topOf/bottomOf(x,y,w,h)` to wire connectors to card edges.
+
+Compose these into a `buildExcalidraw({ out, elements })` call. Runnable example: `examples/style_board.js`.
+Conventions: color nodes by ROLE, label every arrow, put specs in side-annotations, use big plain
+section titles to break the board into "slides", keep one idea per card.
+
+## Rules & gotchas
+- **Unique image filenames.** Obsidian resolves `[[name.png]]` by basename; if two different files
+  share a name anywhere in the vault the link is ambiguous. Name screenshots uniquely
+  (e.g. `bm-pilates-2707-step-03.png`) or use `"wikilinkMode": "path"`.
+- Images must live inside the vault. External paths are auto-copied into `attachDir`.
+- Output is uncompressed JSON inside `%% … %%`. The plugin reads it; on its first save it may
+  re-compress — that's expected and harmless.
+- Re-running with the same `out` + same spec yields a byte-stable file (seeds are derived from the
+  output path), so boards diff cleanly in git.
+- **Self-contained / portable.** No `npm install` — `build_excalidraw.js` uses only Node builtins +
+  the vendored `scripts/lib/*` (fractional-indexing, imagesize, style). Copy `.claude/skills/excalidraw/`
+  into any project and it works. `vaultRoot` auto-detects `.obsidian`; with none it falls back to the
+  board's own folder, so the `.excalidraw.md` is still written (it just renders inside Obsidian).
+
+## Verify
+Run the bundled examples from the skill folder (they use skill-relative paths + a bundled `sample.png`,
+so they work in any project):
+```bash
+cd .claude/skills/excalidraw
+node scripts/build_excalidraw.js examples/hello.spec.json   # spec-driven: text/shapes/image → examples/Hello Excalidraw.excalidraw.md
+node examples/style_board.js                                # JS API: card/connector/lane house style → examples/Style Demo.excalidraw.md
+```
+Then open the resulting board in Obsidian (Excalidraw view) to confirm it renders.
+
+See `reference/format.md` for the exact `.excalidraw.md` anatomy reverse-engineered from this vault.

package/skill-packs/excalidraw/examples/hello.spec.json

@@ -0,0 +1,14 @@
+{
+  "out": "examples/Hello Excalidraw.excalidraw.md",
+  "background": "#ffffff",
+  "elements": [
+    { "type": "text", "x": 0, "y": -70, "text": "excalidraw skill — portable smoke test", "fontSize": 28, "color": "#1971c2" },
+    { "type": "text", "x": 0, "y": -28, "text": "Give a text a width and it wraps to that width (no overlap). The image embeds via sha1 wikilink — no base64. Only skill-relative paths, so this runs in any project.", "fontSize": 15, "color": "#868e96", "width": 540 },
+    { "type": "rectangle", "x": 0, "y": 40, "width": 260, "height": 140, "strokeColor": "#1e1e1e", "backgroundColor": "#a5d8ff", "fillStyle": "solid", "strokeWidth": 2, "roundness": true },
+    { "type": "text", "x": 24, "y": 96, "text": "rounded rect\n+ fill", "fontSize": 20, "color": "#1e1e1e" },
+    { "type": "ellipse", "x": 340, "y": 40, "width": 160, "height": 140, "strokeColor": "#2f9e44", "backgroundColor": "#b2f2bb", "fillStyle": "hachure" },
+    { "type": "arrow", "points": [[260, 110], [340, 110]], "strokeColor": "#e8590c", "strokeWidth": 3 },
+    { "type": "text", "x": 0, "y": 220, "text": "embedded image (resolved from vault by sha1 wikilink):", "fontSize": 16, "color": "#555", "width": 420 },
+    { "type": "image", "x": 0, "y": 250, "path": "examples/sample.png", "width": 320 }
+  ]
+}

package/skill-packs/excalidraw/examples/style_board.js

@@ -0,0 +1,31 @@
+// style_board.js — house-style demo. Run from anywhere:  node examples/style_board.js
+// Shows card/connector/sectionTitle + the dimension-aware lane() (captions hug images, .nextY stacks).
+const path = require('path');
+const { buildExcalidraw, lane } = require(path.join(__dirname, '..', 'scripts', 'build_excalidraw.js'));
+const { card, connector, sectionTitle, rightOf, leftOf, bottomOf, topOf } = require(path.join(__dirname, '..', 'scripts', 'lib', 'style.js'));
+
+const SAMPLE = path.join(__dirname, 'sample.png');
+const els = [];
+const P = (...a) => els.push(...a.flat());
+
+// --- flow row with labeled connectors (color nodes by role) ---
+P(sectionTitle({ x: 0, y: 0, text: 'House style', fontSize: 40 }));
+const A = { x: 0, y: 90, w: 220, h: 84 }, B = { x: 360, y: 90, w: 220, h: 84 }, C = { x: 720, y: 90, w: 220, h: 84 };
+P(card({ ...A, text: 'input', color: 'blue' }));
+P(card({ ...B, text: 'core service', color: 'purple' }));
+P(card({ ...C, text: 'result', color: 'mint' }));
+P(connector({ from: rightOf(A.x, A.y, A.w, A.h), to: leftOf(B.x, B.y, B.w, B.h), label: 'request' }));
+P(connector({ from: rightOf(B.x, B.y, B.w, B.h), to: leftOf(C.x, C.y, C.w, C.h), label: 'response' }));
+
+// --- a dimension-aware lane: captions hug each image, .nextY gives the next free row ---
+const imgs = [
+  { path: SAMPLE, caption: 'lane() reads the real image size, so this caption hugs the bottom and wraps to the thumb width — no gap, no overlap.' },
+  { path: SAMPLE, caption: 'second thumb' },
+  { path: SAMPLE, caption: 'third thumb' },
+];
+const strip = lane({ title: 'lane()  — funnel-step style strip', images: imgs, x: 0, y: 220, thumbW: 200 });
+P(strip);
+P(sectionTitle({ x: 0, y: strip.nextY, text: 'stacked below via strip.nextY', fontSize: 22, color: '#868e96' }));
+
+buildExcalidraw({ out: path.join(__dirname, 'Style Demo.excalidraw.md'), elements: els, background: '#fbfbfb' });
+console.log('style demo →', path.join(__dirname, 'Style Demo.excalidraw.md'));

package/skill-packs/excalidraw/package.json

@@ -0,0 +1,5 @@
+{
+  "type": "commonjs",
+  "private": true,
+  "description": "Scopes the excalidraw skill's vendored scripts to CommonJS so `require()` works even when the host project sets \"type\": \"module\". No dependencies — scripts use only Node builtins + vendored lib/."
+}