skilldrop-cli 0.16.32 → 0.16.34

package/bin/skilldrop.js

@@ -37,6 +37,8 @@ const HELP = `skilldrop — portable AI-agent skills for Claude Code, Cursor, Ki
 
 Usage:
   skilldrop list [--from <src>]           all skills in a catalog (name, version, tier)
+  skilldrop search <words...> [--kind skill|loop|agent|pack] [--limit N] [--json]
+                                          find skills, loops, agents and packs by what they're for
   skilldrop info <skill> [--from <src>]   description, related, packs, deps
   skilldrop info --pack <name>            a pack's skills, loops, and what to try first (RFC-0032)
   skilldrop packs [--from <src>]          role-based packs
@@ -149,7 +151,8 @@ function parseArgs(argv) {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--pack" || a === "--ide" || a === "--dest" || a === "--from" || a === "--panel" || a === "--profile" || a === "--tier" || a === "--skills" || a === "--days" ||
-        a === "--policy" || a === "--merge" || a === "--label" || a === "--last" || a === "--html") out.flags[a.slice(2)] = argv[++i];
+        a === "--policy" || a === "--merge" || a === "--label" || a === "--last" || a === "--html" ||
+        a === "--kind" || a === "--limit") out.flags[a.slice(2)] = argv[++i];
     else if (a.startsWith("--")) out.flags[a.slice(2)] = true;
     else out._.push(a);
   }
@@ -2410,6 +2413,105 @@ function list(args) {
   console.log(`\n${rows.length} skills in catalog '${cat.source}'. Details: skilldrop info <skill>`);
 }
 
+/* search <words> (RFC-0056): find a skill, loop, agent or pack by what it is for, from the
+   terminal and offline. Every word must match (by prefix, so "deploy" finds "deployment");
+   a name match outweighs a tag, a tag a pack or outcome, and those the description or the
+   phrasings the skill's trigger evals route to it. Filler words are dropped. When no
+   entry matches every word, entries that match some are shown, and the reply says so. */
+function search(args) {
+  // Words that say nothing about what a skill does ("why did my…") are dropped, unless they
+  // are all there is.
+  const STOP = new Set(("a an and are as at be but by can could did do does for from get got had has have help how i in " +
+    "into is it its me my need of on or our please should so that the their them this to us want was we were what when " +
+    "where which who why will with would you your").split(" "));
+  const raw = args._.join(" ").toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 1);
+  const words = raw.filter((w) => !STOP.has(w)).length ? raw.filter((w) => !STOP.has(w)) : raw;
+  if (!words.length) die("usage: skilldrop search <words...> [--kind skill|loop|agent|pack] [--limit N] [--json] [--from <src>]");
+  const cat = resolveCatalog(args.flags.from);
+  const kinds = ["skill", "loop", "agent", "pack"];
+  const want = args.flags.kind;
+  if (want && !kinds.includes(want)) die(`--kind takes one of ${kinds.join(", ")}`);
+  const limit = Math.max(1, Number(args.flags.limit) || 10);
+  const toks = (x) => String(x || "").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+  const idx = cat.dir ? path.join(cat.dir, "catalogue.json") : null;
+  const outcomes = idx && fs.existsSync(idx) ? (readJSON(idx).outcomes || {}) : {};
+  const outcomeOf = {};
+  for (const [o, d] of Object.entries(outcomes)) for (const sk of d.skills || []) (outcomeOf[sk] = outcomeOf[sk] || []).push(o);
+  const ps = packsOf(cat) || {};
+  const packOf = {};
+  for (const [pn, pd] of Object.entries(ps)) for (const sk of pd.skills || []) if (!packOf[sk]) packOf[sk] = pn;
+  const entries = [];
+  const add = (kind, name, description, fields) => entries.push({ kind, name, description: description || "", fields });
+  for (const sk of skillsIn(cat)) {
+    let m = {};
+    try { m = manifestOf(cat, sk); } catch (e) { /* listed with what we have */ }
+    // The phrasings the skill's own trigger evals say should route to it: how people ask.
+    let asks = [];
+    try {
+      const q = path.join(skillDir(cat, sk), "evals", "eval_queries.json");
+      if (fs.existsSync(q)) asks = readJSON(q).filter((r) => r && r.should_trigger).map((r) => r.query);
+    } catch (e) { /* no phrasings, still searchable by its description */ }
+    add("skill", sk, m.description, { name: toks(sk), tags: toks((m.tags || []).join(" ")),
+      group: toks([packOf[sk], ...(outcomeOf[sk] || [])].join(" ")), text: toks(m.description), asks: toks(asks.join(" ")) });
+  }
+  for (const l of loopsIn(cat)) {
+    let spec = {};
+    try { spec = loopSpec(cat, l); } catch (e) { /* skip unreadable */ }
+    add("loop", l, spec.description, { name: toks(l), tags: toks((spec.stages || []).map((st) => st.id).join(" ")),
+      group: toks((spec.stages || []).flatMap((st) => st.skills || []).join(" ")), text: toks(spec.description) });
+  }
+  for (const a of agentsIn(cat)) {
+    let meta = {};
+    try { meta = agentMeta(cat, a); } catch (e) { /* skip unreadable */ }
+    add("agent", a, meta.description, { name: toks(a), tags: [], group: [], text: toks(meta.description) });
+  }
+  for (const [pn, pd] of Object.entries(ps))
+    add("pack", pn, pd.description, { name: toks(pn + " " + (pd.display_name || "")), tags: toks((pd.keywords || []).join(" ")),
+      group: toks((pd.skills || []).join(" ")), text: toks(pd.description) });
+  const WEIGHT = { name: 6, tags: 3, group: 2, text: 1, asks: 1 };
+  const stem = (w) => (w.length > 4 && w.endsWith("s") ? w.slice(0, -1) : w);
+  const score = (e) => {
+    let total = 0, hit = 0;
+    for (const w of words.map(stem)) {
+      let best = 0;
+      for (const [f, list] of Object.entries(e.fields))
+        for (const t of list)
+          if (t === w || t.startsWith(w)) best = Math.max(best, WEIGHT[f] * (t === w ? 1.5 : 1));
+      if (best) { total += best; hit++; }
+    }
+    return { total, hit };
+  };
+  let ranked = entries.filter((e) => !want || e.kind === want).map((e) => Object.assign(e, score(e)));
+  const all = ranked.filter((e) => e.hit === words.length);
+  const partial = !all.length;
+  ranked = (partial ? ranked.filter((e) => e.hit > 0) : all)
+    .sort((a, b) => b.hit - a.hit || b.total - a.total || a.name.localeCompare(b.name));
+  const shown = ranked.slice(0, limit);
+  // A retired skill searched for by name gets its note, not silence (RFC-0046).
+  const retired = [...new Set([args._.join("-"), ...args._].map((n) => String(n).toLowerCase()))]
+    .map((n) => retiredNote(cat, n)).filter(Boolean);
+  if (args.flags.json)
+    return emitJSON({ catalog: cat.source, query: words, matched: partial ? "some words" : "every word", total: ranked.length,
+      results: shown.map((e) => ({ kind: e.kind, name: e.name, pack: e.kind === "skill" ? packOf[e.name] || null : null,
+                                   description: e.description, score: Math.round(e.total * 10) / 10 })), retired });
+  for (const r of retired) console.log(`${r}\n`);
+  if (!ranked.length) {
+    console.log(`Nothing in catalog '${cat.source}' matches "${words.join(" ")}". Try fewer or different words, or: skilldrop list`);
+    return;
+  }
+  if (partial) console.log(`No entry matches every word of "${words.join(" ")}"; these match some:\n`);
+  const first = (d) => { const t = d.split(" Use when")[0].replace(/\s+/g, " ").trim(); return t.length > 150 ? t.slice(0, 147).replace(/\s+\S*$/, "") + "…" : t; };
+  for (const e of shown) {
+    const where = e.kind === "skill" ? (packOf[e.name] ? `skill, ${packOf[e.name]} pack` : "skill") : e.kind;
+    console.log(`${e.name}  (${where})\n  ${first(e.description)}`);
+  }
+  const more = ranked.length - shown.length;
+  const top = shown[0];
+  const how = { skill: `skilldrop info ${top.name}  ·  skilldrop install ${top.name}`, loop: `skilldrop install --loop ${top.name}`,
+                agent: `skilldrop install --agent ${top.name}`, pack: `skilldrop info --pack ${top.name}  ·  skilldrop install --pack ${top.name}` }[top.kind];
+  console.log(`\n${ranked.length} match${ranked.length === 1 ? "" : "es"}${more > 0 ? `, showing ${shown.length} (--limit to see more)` : ""}. Next: ${how}`);
+}
+
 /* RFC-0032: what to try first after installing a pack, how to tell it worked, what to do
    if it didn't — the same first-value block the pack's site page renders. */
 function firstValueLines(p) {
@@ -2666,7 +2768,7 @@ function bootstrap() {
 
 const args = parseArgs(process.argv.slice(2));
 const cmd = args._.shift();
-const commands = { list, info, packs: listPacks, profiles: listProfiles, agents: listAgents, loops: listLoops, install, update, outdated, uninstall, diff, doctor, "new-skill": newSkill, "loop-stats": loopStats, "init-catalogue": initCatalogue, package: packageCatalogue, validate: validateCmd, scan, bootstrap,
+const commands = { list, search, info, packs: listPacks, profiles: listProfiles, agents: listAgents, loops: listLoops, install, update, outdated, uninstall, diff, doctor, "new-skill": newSkill, "loop-stats": loopStats, "init-catalogue": initCatalogue, package: packageCatalogue, validate: validateCmd, scan, bootstrap,
                    inventory, audit: auditCmd, "verify-mirror": verifyMirrorCmd };
 if (args.flags.version || cmd === "version") console.log(readJSON(path.join(ROOT, "package.json")).version);
 else if (!cmd || cmd === "help" || args.flags.help) console.log(HELP);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.16.32",
+  "version": "0.16.34",
   "description": "Portable AI-agent skills, measured against the agent without them. ADRs, PRDs, runbooks, decks and reviews, installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",

package/packs/ai-engineering/skills/ai-usage-report/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-usage-report",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Generate a per-user or team-level report on how AI tools are being used — volume, breadth, and effectiveness signals (e.g. whether AI outputs landed in shipped artifacts vs were generated and discarded). Consumes usage-event logs exported from an MCP server or other telemetry source. Use when a manager or team lead needs to understand AI adoption beyond raw counts — including spotting \"AI theater\" where people invoke AI to claim usage but don't act on the outputs.",
   "entrypoint": "SKILL.md",
   "deps": { "npm": [], "pip": [] },

package/packs/ai-engineering/skills/ai-usage-report/scripts/build_report.py

@@ -212,7 +212,7 @@ def load_template(name: str, script_dir: Path) -> str:
     p = script_dir.parent / "templates" / name
     if not p.exists():
         raise SystemExit(f"error: template not found: {p}")
-    return p.read_text()
+    return p.read_text(encoding="utf-8")
 
 
 # --------------------------------------------------------------------- views
@@ -427,7 +427,7 @@ def main(argv) -> int:
 
     out_path = Path(args.out).expanduser().resolve() if args.out else input_path.with_suffix(".report.md")
     out_path.parent.mkdir(parents=True, exist_ok=True)
-    out_path.write_text(out)
+    out_path.write_text(out, encoding="utf-8")
     print(f"wrote {out_path} ({len(events)} events, {len(per_user)} users, view={args.view})")
     return 0
 

package/packs/converters/skills/file-to-markdown/SKILL.md

@@ -47,12 +47,16 @@ or a rewrite that goes back out through `md-to-docx` or `md-to-html`.
    | `.csv` / `.tsv` | One table, delimiter detected |
    | `.json` | An array of objects becomes a table; an object becomes a key/value table plus a table per array |
    | `.txt` / `.md` | Passed through |
-   | `.pdf` | Through `pdftotext`. Tables from aligned columns, lists from indentation, short standalone lines as `###` headings (guessed, and said so); pages with side-by-side columns are read in column order with nothing inferred. No images |
+   | `.pdf` | Through `pdftotext`. Tables from aligned columns, lists from indentation, short standalone lines as `###` headings (guessed, and said so); a table that runs onto the next page is joined into one, without the header the PDF repeats; pages with side-by-side columns are read in column order with nothing inferred. Scanned pages are read by OCR when `tesseract` is installed. No images |
 
 3. **PDF without `pdftotext`.** The script stops with install steps (`brew install poppler`
    on macOS, `sudo apt install poppler-utils` on Debian/Ubuntu). Pass those on; don't try to
-   read the PDF bytes yourself. A PDF with no text layer is a scan and needs OCR, which this
-   skill does not do.
+   read the PDF bytes yourself. A page with no text layer is a scan. The script reads it by
+   OCR when `tesseract` is installed (`brew install tesseract`, `sudo apt install tesseract-ocr`),
+   and otherwise stops with those steps. For a scan that isn't in English, pass `--ocr-lang`
+   with tesseract's code (`deu`, `fra`, `eng+fra`). OCR misreads characters, so the reply says
+   which pages were OCR'd and asks the user to check every number, name and date in them
+   against the PDF.
 
 4. **Old binary formats** (`.doc`, `.ppt`, `.xls`, `.rtf`, `.pages`, `.key`): the script
    refuses and names the format to save as. On macOS, `textutil -convert docx file.doc`
@@ -73,7 +77,7 @@ missing, emit `BLOCKED: need <the file | pdftotext on PATH>` and stop.
 
 ## Useful references in this skill
 
-- [`scripts/to_markdown.py`](scripts/to_markdown.py): the converter (stdlib only; `pdftotext` optional for PDF)
+- [`scripts/to_markdown.py`](scripts/to_markdown.py): the converter (stdlib only; `pdftotext` optional for PDF, `tesseract` for scanned pages)
 - [`examples/mixed-inputs.md`](examples/mixed-inputs.md): a Word brief, a deck, a workbook and a web page converted, with the real Markdown and stderr report
 
 ## Quality bar

package/packs/converters/skills/file-to-markdown/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "file-to-markdown",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Convert a Word document, PowerPoint deck, Excel workbook, web page, CSV, JSON, text file or PDF into clean Markdown that keeps headings, lists, tables, links, bold and italic, slide titles and speaker notes, and reports everything it dropped (images, charts, comments, formulas, tracked changes), so the content can be read, reviewed or fed to another skill. Use when the user hands over a .docx, .pptx, .xlsx, .html, .csv, .json or .pdf and says \"read this\", \"turn this into markdown\", \"extract the text\", or wants it critiqued or briefed.",
   "entrypoint": "SKILL.md",
   "deps": {
@@ -41,7 +41,16 @@
     "pdf",
     "extract"
   ],
-  "permissions": {"network": [], "commands": ["pdftotext"], "files": "named-paths", "notes": "pdftotext (Poppler) is used only for .pdf input, and only if it is installed."},
+  "permissions": {
+    "network": [],
+    "commands": [
+      "pdftotext",
+      "pdftoppm",
+      "tesseract"
+    ],
+    "files": "named-paths",
+    "notes": "pdftotext (Poppler) is used only for .pdf input, and only if it is installed. A page with no text layer is rendered with pdftoppm (Poppler) into a temporary folder that is deleted afterwards, and read with tesseract, only if tesseract is installed."
+  },
   "model": {
     "tier": "light",
     "rationale": "A deterministic stdlib script does the extraction; the model runs it, relays the dropped-content report and hands off. No generation beyond a short summary of losses."

package/packs/converters/skills/file-to-markdown/scripts/to_markdown.py

@@ -2,7 +2,8 @@
 """Convert a document into clean Markdown that another skill can read.
 
 Stdlib only, Python 3.9+. Handles .docx, .pptx, .xlsx, .html/.htm, .csv/.tsv,
-.json, .txt/.md, and .pdf (through `pdftotext` when it is installed).
+.json, .txt/.md, and .pdf (through `pdftotext` when it is installed). A PDF page with no
+text layer (a scan) is read by OCR when `tesseract` and `pdftoppm` are installed.
 Everything the conversion could not carry (images, charts, comments, formulas,
 tracked changes) is counted and reported on stderr, so nobody mistakes the
 Markdown for the whole document.
@@ -12,6 +13,7 @@ Usage:
     python3 to_markdown.py deck.pptx -o deck.md
     python3 to_markdown.py model.xlsx -o model.md --max-rows 200
     python3 to_markdown.py page.html -o -          # write to stdout
+    python3 to_markdown.py scan.pdf -o scan.md --ocr-lang deu   # OCR a German scan
 """
 
 import argparse
@@ -22,6 +24,7 @@ import re
 import shutil
 import subprocess
 import sys
+import tempfile
 import zipfile
 from collections import OrderedDict
 from datetime import datetime, timedelta
@@ -1122,8 +1125,9 @@ def _pdf_page_md(page, rep):
                     region.append(line); rows += 1; cols |= _col_starts(line); j += 1
                 elif line.strip() and _col_starts(line) and _col_starts(line) <= _near(cols):
                     region.append(line); j += 1
-                elif not line.strip() and j + 1 < n and lines[j + 1].strip() and (
-                        len(_cells(lines[j + 1])) >= 2 or _col_starts(lines[j + 1]) <= _near(cols)):
+                elif not line.strip() and j + 1 < n and len(_cells(lines[j + 1])) >= 2:
+                    # After a blank line only a full row continues the table. A one-cell line
+                    # there ("End of report.") is the next paragraph, not a wrapped cell.
                     j += 1
                 else:
                     break
@@ -1193,7 +1197,83 @@ def _pdf_page_md(page, rep):
     return out
 
 
-def pdf_to_md(path, rep):
+_FURNITURE = re.compile(r"^\s*(page\s+)?\d{1,4}(\s*(of|/)\s*\d{1,4})?\s*$|^\s*[-–—]\s*\d{1,4}\s*[-–—]\s*$", re.I)
+
+
+def _join_split_tables(pages, rep):
+    """A table that runs off the foot of one page continues at the top of the next, where it
+    would otherwise start a second table whose first data row reads as its header. When a page
+    ends in a table and the next page's first rows (after page numbers and any running header)
+    have the same number of cells, those rows are moved up to finish the table. A header row
+    the PDF repeats on the new page is dropped. Returns the pages, rewritten."""
+    pages = [p.split("\n") for p in pages]
+    first_lines = [next((l.strip() for l in p if l.strip()), "") for p in pages]
+    running = {t for t in first_lines if t and first_lines.count(t) > 1}  # a header on several pages
+    holder = None
+    for k in range(len(pages) - 1):
+        a_idx = k if holder is None else holder
+        a, b = pages[a_idx], pages[k + 1]
+        # the last table row on the holder page, before trailing page furniture
+        end = len(a) - 1
+        while end >= 0 and (not a[end].strip() or _FURNITURE.match(a[end])):
+            end -= 1
+        holder = None
+        if end < 0 or len(_cells(a[end])) < 2:
+            continue
+        width = len(_cells(a[end]))
+        start = end
+        while start - 1 >= 0 and (len(_cells(a[start - 1])) == width or
+                                  (not a[start - 1].strip() and start - 2 >= 0 and len(_cells(a[start - 2])) == width)):
+            start -= 1
+        header = " ".join(a[start].split())
+        # the first content on the next page, past page numbers and a running header
+        i = 0
+        while i < len(b) and (not b[i].strip() or _FURNITURE.match(b[i]) or b[i].strip() in running):
+            i += 1
+        if i >= len(b) or len(_cells(b[i])) != width:
+            continue
+        j = i
+        rows = []
+        while j < len(b) and (len(_cells(b[j])) == width or
+                              (not b[j].strip() and j + 1 < len(b) and len(_cells(b[j + 1])) == width)):
+            if b[j].strip():
+                rows.append(b[j])
+            j += 1
+        dropped = bool(rows) and " ".join(rows[0].split()) == header
+        if dropped:
+            rows = rows[1:]
+        if not rows:
+            continue
+        a[end + 1:end + 1] = rows
+        del b[i:j]
+        rep.notes.append("a table continued from page %d onto page %d was joined into one%s" % (
+            a_idx + 1, k + 2, ", and the header row repeated on page %d was dropped" % (k + 2) if dropped else ""))
+        rep.keep("pdf tables joined across pages", 1)
+        if not any(l.strip() and not _FURNITURE.match(l) and l.strip() not in running for l in b):
+            holder = a_idx  # the whole page was table: the next page may continue it too
+    return ["\n".join(p) for p in pages]
+
+
+def _ocr_page(path, n, ppm, tess, lang):
+    """Page n of the PDF as text, by rendering it at 300 dpi and reading it with tesseract.
+    Page segmentation mode 6 reads a uniform block and keeps the spacing between words, which
+    is what the table and list inference reads columns from."""
+    with tempfile.TemporaryDirectory(prefix="to-md-ocr-") as tmp:
+        stem = str(Path(tmp) / "page")
+        r = subprocess.run([ppm, "-r", "300", "-png", "-f", str(n), "-l", str(n), str(path), stem],
+                           stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
+        pngs = sorted(Path(tmp).glob("page*.png"))
+        if r.returncode != 0 or not pngs:
+            sys.exit("error: pdftoppm could not render page %d: %s" % (n, r.stderr.decode("utf-8", "replace").strip()))
+        r = subprocess.run([tess, str(pngs[0]), "stdout", "-l", lang, "--psm", "6",
+                            "-c", "preserve_interword_spaces=1"],
+                           stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
+        if r.returncode != 0:
+            sys.exit("error: tesseract failed on page %d: %s" % (n, r.stderr.decode("utf-8", "replace").strip()))
+        return r.stdout.decode("utf-8", "replace").replace("\f", "")
+
+
+def pdf_to_md(path, rep, ocr=True, ocr_lang="eng"):
     exe = shutil.which("pdftotext")
     if not exe:
         sys.exit("error: reading PDF needs `pdftotext` (part of Poppler), which is not on PATH.\n"
@@ -1211,9 +1291,33 @@ def pdf_to_md(path, rep):
         return pages[:-1] if pages and not pages[-1].strip() else pages
 
     layout, reading = run(["-layout"]), run([])
-    if not "".join(layout).strip():
-        sys.exit("error: %s has no text layer (probably scanned). It needs OCR first; "
-                 "this script does not do OCR." % path)
+    blank = [n for n, p in enumerate(layout, 1) if not p.strip()]
+    if blank and ocr is not False:
+        tess, ppm = shutil.which("tesseract"), shutil.which("pdftoppm")
+        if not (tess and ppm):
+            if len(blank) == len(layout):
+                sys.exit("error: %s has no text layer (probably scanned), so it needs OCR, which uses "
+                         "`tesseract`%s.\n"
+                         "  macOS:          brew install tesseract   (pdftoppm comes with poppler)\n"
+                         "  Debian/Ubuntu:  sudo apt install tesseract-ocr poppler-utils\n"
+                         "  Windows:        install Tesseract (UB Mannheim build) and add it to PATH\n"
+                         "Then rerun. Add --ocr-lang deu (or another installed language) for a non-English scan."
+                         % (path, "" if ppm else " and `pdftoppm`"))
+            rep.notes.append("page(s) %s have no text layer and were left empty: install tesseract to read them by OCR"
+                             % ", ".join(map(str, blank)))
+        else:
+            for n in blank:
+                text = _ocr_page(path, n, ppm, tess, ocr_lang)
+                layout[n - 1] = text
+                if n <= len(reading):
+                    reading[n - 1] = text
+            rep.keep("pages read by OCR", len(blank))
+            rep.notes.append("page(s) %s are scanned, so their text was read by OCR (tesseract, language %s, 300 dpi). "
+                             "OCR misreads characters: check every number, name and date against the PDF"
+                             % (", ".join(map(str, blank)), ocr_lang))
+    elif blank and len(blank) == len(layout):
+        sys.exit("error: %s has no text layer (probably scanned), and --no-ocr was given." % path)
+    layout = _join_split_tables(layout, rep)
     out, plain_pages = [], []
     for n, page in enumerate(layout, 1):
         out += ["<!-- page %d -->" % n, ""]
@@ -1250,7 +1354,12 @@ def main(argv=None):
     ap.add_argument("-o", "--output", required=True, help="Markdown file to write, or - for stdout")
     ap.add_argument("--max-rows", type=int, default=0,
                     help="xlsx only: keep at most this many data rows per sheet (0 = all)")
+    ap.add_argument("--ocr-lang", default="eng",
+                    help="pdf only: tesseract language for scanned pages, e.g. eng, deu, fra, eng+fra (default eng)")
+    ap.add_argument("--no-ocr", action="store_true", help="pdf only: never run OCR on scanned pages")
     a = ap.parse_args(argv)
+    if not re.fullmatch(r"[A-Za-z_]{3,}(\+[A-Za-z_]{3,})*", a.ocr_lang):
+        sys.exit("error: --ocr-lang takes tesseract language codes such as eng or eng+fra")
 
     path = Path(a.input)
     if not path.is_file():
@@ -1267,7 +1376,8 @@ def main(argv=None):
             md += "\n"
     elif ext in HANDLERS:
         fn = HANDLERS[ext]
-        md = fn(path, rep, a.max_rows) if fn is xlsx_to_md else fn(path, rep)
+        md = (fn(path, rep, a.max_rows) if fn is xlsx_to_md else
+              fn(path, rep, ocr=not a.no_ocr, ocr_lang=a.ocr_lang) if fn is pdf_to_md else fn(path, rep))
     else:
         sys.exit("error: unsupported file type %r. Supported: %s, .txt, .md"
                  % (ext, ", ".join(sorted(HANDLERS))))

package/packs/converters/skills/md-to-docx/examples/q3-support-review.md

@@ -66,6 +66,13 @@ has a shaded header row and right-aligned numbers, and the 480 × 240 px chart (
 DPI) is centred at 3.3 × 1.7 in. The numbered proposals run 1 to 3, the "support dashboard" and
 "the alias section" links are blue and underlined, and the quote is indented and italic.
 
+**Opened in Microsoft Word** for Mac 16.114 (2026-10-20), through AppleScript: it opened with
+no repair prompt, the first paragraph has the built-in Heading 1 style, and it holds one table
+and one inline picture. Word's own PDF export of it shows the nested bullets, both task boxes,
+the table with its numbers right-aligned, the code block and the quote, embeds the chart at
+480 × 240, and carries both links as live link annotations: the dashboard URL and the jump to
+"Retiring the alias".
+
 ---
 
 ## Reply to the user

package/packs/converters/skills/md-to-xlsx/examples/vendor-review.md

@@ -76,7 +76,12 @@ all well-formed. Row 2 of the first sheet reads back as:
 
 The frozen pane is `ySplit="1"` and the autofilter is `A1:G5`. A Quick Look preview shows
 `$1,240,500.00`, `12.5%` and `2027-03-31` as formatted values. Quick Look leaves boolean cells
-blank, which is a limitation of the previewer. Excel and LibreOffice show them as TRUE/FALSE.
+blank, which is a limitation of the previewer.
+
+**Opened in Microsoft Excel** for Mac 16.114 (2026-10-20), read through AppleScript without
+saving: three sheets; D2 is the number 1240500 shown as `$1,240,500.00`, E2 the number 0.125
+shown as `12.5%`, F2 a date shown as `2027-03-31`, G2 the boolean `TRUE`, and A2 the text
+`00412` with its zeros. The first sheet has its filter on and its header row frozen.
 
 ---
 

package/packs/design/skills/brand-kit/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "brand-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Capture a brand once as a reusable brand.json — logo files (and an on-dark version), colour roles as hex codes, heading and body fonts, voice, imagery rules, a PowerPoint template, contact details and the legal footer — plus a one-page BRAND.md, with text contrast checked and every value traced to where it came from. Use when the user wants decks, flyers or documents in their branding, says \"use our brand\", \"here's our logo and colours\", \"set up our brand kit\", or hands over brand guidelines.",
   "entrypoint": "SKILL.md",
   "deps": {

package/packs/design/skills/brand-kit/scripts/check_brand.py

@@ -42,7 +42,7 @@ def main(argv):
     path = Path(argv[0]).expanduser().resolve()
     base = path.parent
     try:
-        brand = json.loads(path.read_text())
+        brand = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError) as e:
         print(f"FAIL cannot read {path}: {e}")
         return 1

package/packs/design/skills/deck-builder/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "deck-builder",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Generate a real PowerPoint (.pptx) file from content, audience, and either a brand template or a color palette — with charts, tables and images, not only bullets. Slide count, density and layout are tuned to the audience: execs, boards, technical reviewers, sales prospects, investors, internal teams. Use when the user wants an actual editable .pptx rather than an outline, wants their corporate template or brand colours applied, or says \"build the deck\", \"make it a pptx\", \"use our template\".",
   "entrypoint": "SKILL.md",
   "deps": {

package/packs/design/skills/deck-builder/scripts/build_deck.py

@@ -161,7 +161,7 @@ def resolve_palette(p, script_dir: Path) -> dict:
         if not palettes_path.exists():
             warn(f"palettes file missing at {palettes_path}; using defaults")
             return DEFAULT_PALETTE
-        all_palettes = json.loads(palettes_path.read_text())
+        all_palettes = json.loads(palettes_path.read_text(encoding="utf-8"))
         if p not in all_palettes:
             warn(f"palette {p!r} not found; using defaults")
             return DEFAULT_PALETTE
@@ -965,7 +965,7 @@ def load_brand(ref, base: Path):
         warn(f"brand file not found: {path}; building without it")
         return {}, base
     try:
-        return json.loads(path.read_text()), path.parent
+        return json.loads(path.read_text(encoding="utf-8")), path.parent
     except json.JSONDecodeError as e:
         warn(f"brand file {path} is not valid JSON ({e}); building without it")
         return {}, base
@@ -1024,7 +1024,7 @@ def place_logo(slide, c: "Canvas", palette: dict, logical: str) -> None:
 
 
 def build(spec_path: Path, out_path: Path, script_dir: Path, *, strict: bool, brand_ref=None) -> None:
-    spec = json.loads(spec_path.read_text())
+    spec = json.loads(spec_path.read_text(encoding="utf-8"))
     spec_dir = spec_path.parent
     brand, brand_dir = load_brand(brand_ref or spec.get("brand"), spec_dir)
     if brand:

package/packs/design/skills/marketing-flyer/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "marketing-flyer",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Generate a print-ready, on-brand marketing flyer — event, launch, open day, offer, hiring — as one self-contained HTML file (Letter, A4, A5, or square and story sizes for social) that saves to PDF, built from the user's own logo, colours, fonts and content, with one call to action, a short headline, contrast checked, and no invented dates, prices or contact details. Use when the user wants a flyer, poster, one-pager, handout, leaflet or event announcement \"in our branding\", or says \"make a flyer for…\".",
   "entrypoint": "SKILL.md",
   "deps": {

package/packs/design/skills/marketing-flyer/scripts/build_flyer.py

@@ -79,7 +79,7 @@ def data_uri(path, label):
 
 def load_json(path):
     try:
-        return json.loads(Path(path).read_text())
+        return json.loads(Path(path).read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError) as e:
         die(f"cannot read {path}: {e}")
 

package/packs/dev-team/skills/pre-merge-review/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "pre-merge-review",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Gate an existing change for merge — run one skill that fires the whole production-readiness pass. First a deterministic mechanical gate (lint + typecheck + tests, via a script whose exit code decides), then the three-reviewer panel dispatched in parallel — devils-advocate (correctness), security-reviewer (exploitability), code-quality (craft) — then a single READY / NOT READY verdict. Use before opening a PR or merging, when you want the full review fleet run on a diff you already have. Do NOT use to implement a feature from a spec (that's feature-implement-loop) or to review a document (that's doc-critique).",
   "entrypoint": "SKILL.md",
   "deps": { "npm": [], "pip": [] },

package/packs/dev-team/skills/pre-merge-review/scripts/gate.py

@@ -43,7 +43,7 @@ def detect(root):
 
     if has("package.json"):
         try:
-            scripts = json.load(open(os.path.join(root, "package.json"))).get("scripts", {})
+            scripts = json.load(open(os.path.join(root, "package.json"), encoding="utf-8")).get("scripts", {})
         except (OSError, json.JSONDecodeError):
             scripts = {}
         if "lint" in scripts: