skilldrop-cli 0.16.31 → 0.16.33

package/bin/skilldrop.js

@@ -66,7 +66,7 @@ Usage:
   skilldrop uninstall --agent <name...>   remove subagents
   skilldrop uninstall --loop <name...>    remove loops (stage skills are left in place)
   skilldrop validate [--from <src>]       structural check of a catalog (for catalog authors)
-  skilldrop scan [<skill...>] [--from <src>]  supply-chain scan — flag network/exec/credential
+  skilldrop scan [<skill...>] [--agent] [--from <src>]  supply-chain scan of skills and agents — flag network/exec/credential
                                           patterns in scripts and injection-shaped instructions
                                           in SKILL.md before you trust a catalog (RFC-0022)
   skilldrop new-skill <name> --pack <p>   scaffold a skill in the catalog you're in (for catalog authors;
@@ -440,11 +440,11 @@ function gate(cat, names) {
 
 /* RFC-0050: the worst scan finding per skill, for a policy's scan.max. Eval fixtures and
    example inputs (⚪) never count. */
-function worstFindings(cat, names) {
+function worstFindings(cat, names, scanner = scanSkill) {
   const out = {};
   for (const s of names) {
     let w;
-    for (const f of scanSkill(cat, s)) if (!f.fixture && (!w || gov.SEVERITY[f.sev] > gov.SEVERITY[w])) w = f.sev;
+    for (const f of scanner(cat, s)) if (!f.fixture && (!w || gov.SEVERITY[f.sev] > gov.SEVERITY[w])) w = f.sev;
     if (w) out[s] = w;
   }
   return out;
@@ -455,7 +455,8 @@ function enforcePolicy(flags, cat, names, kind) {
   const policy = gov.load(flags);
   gov.prepare(policy);  // an audit log that can't be written stops the install before it starts
   if (!policy || !names.length) return policy;
-  const worst = kind === "skill" && policy.scan && policy.scan.max !== undefined ? worstFindings(cat, names) : {};
+  const worst = policy.scan && policy.scan.max !== undefined && (kind === "skill" || kind === "agent")
+    ? worstFindings(cat, names, kind === "agent" ? scanAgent : scanSkill) : {};
   const problems = gov.check(policy, { source: cat.source, pinned: cat.pinned, names, worst, kind });
   if (problems.length) {
     for (const pr of problems) console.error(`refused ${pr.name}: ${pr.why}`);
@@ -614,10 +615,73 @@ function permissionsOf(cat, s) {
   if (cat.shape === "apm") return null;
   try { return manifestOf(cat, s).permissions || null; } catch (e) { return null; }
 }
+/* RFC-0054: what a skill's instructions tell the agent to run. A skill with no scripts still
+   reaches the shell and the network through the agent, so its fenced shell blocks are read the
+   way a reviewer would: the program each command starts, and the hosts it names. Shell builtins,
+   keywords and the text tools every agent already has are left out, as are interpreters running
+   the skill's own scripts/ (those are covered by the script rules). Prose outside a fenced shell
+   block is not parsed: an instruction to run something belongs in one, where a reader sees it. */
+const SHELL_LANGS = new Set(["bash", "sh", "shell", "console", "zsh"]);
+const NOT_A_PROGRAM = new Set(("cd echo export set unset true false test printf read source exit return then fi do done " +
+  "for if elif else while until case esac in function local shift wait time eval exec alias type command " +
+  "mkdir ls cat cp mv rm touch head tail grep egrep sed awk sort uniq wc tr cut xargs tee diff find jq less more " +
+  "pwd basename dirname date sleep env which chmod ln realpath mktemp yes seq").split(" "));
+const INTERPRETERS = new Set(["python", "python3", "node", "bash", "sh", "zsh", "deno", "bun"]);
+function instructedRuns(dir) {
+  const files = ["SKILL.md", "reference.md"].map((f) => path.join(dir, f)).filter((f) => fs.existsSync(f));
+  const refs = path.join(dir, "references");
+  if (fs.existsSync(refs)) for (const f of fs.readdirSync(refs)) if (f.endsWith(".md")) files.push(path.join(refs, f));
+  const commands = new Map(), hosts = new Map();
+  for (const f of files) {
+    const lines = fs.readFileSync(f, "utf8").split(/\r?\n/);
+    let lang = null;
+    lines.forEach((raw, i) => {
+      const fence = raw.match(/^\s*```+\s*([\w-]*)/);
+      if (fence) { lang = lang === null ? fence[1].toLowerCase() : null; return; }
+      if (lang === null || !SHELL_LANGS.has(lang)) return;
+      const where = { file: path.relative(dir, f), line: i + 1, text: raw.trim().slice(0, 120) };
+      const line = raw.replace(/(^|\s)#.*$/, "").replace(/^\s*\$\s+/, "").trim();
+      if (!line) return;
+      for (const h of line.matchAll(/https?:\/\/([a-z0-9][a-z0-9.-]*\.[a-z]{2,})/gi))
+        if (!hosts.has(h[1].toLowerCase())) hosts.set(h[1].toLowerCase(), where);
+      // Quoted text is an argument (a grep pattern, a message), never a command, so blank it
+      // before splitting on | ; && — otherwise `grep 'a|b'` reads as a command named b.
+      const bare = line.replace(/'[^']*'|"(?:[^"\\]|\\.)*"/g, (q) => (/scripts\/|CLAUDE_SKILL_DIR/.test(q) ? q.slice(1, -1) : " X "));
+      for (let part of bare.replace(/\$\(/g, " ; ").replace(/[`()]/g, " ").split(/&&|\|\||\||;/)) {
+        let w = part.trim().split(/\s+/).filter(Boolean);
+        while (w.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(w[0])) w.shift();
+        if (w[0] === "sudo" || w[0] === "nohup") w.shift();
+        const c = w[0];
+        if (!c || !/^[a-z][\w.+-]*$/.test(c) || NOT_A_PROGRAM.has(c)) continue;
+        if (INTERPRETERS.has(c) && w.slice(1).some((x) => /(^|\/)scripts\//.test(x) || /CLAUDE_SKILL_DIR/.test(x))) continue;
+        const prog = INTERPRETERS.has(c) && w[1] === "-m" && /^[a-z][\w.-]*$/.test(w[2] || "") ? w[2] : c;  // python3 -m pip -> pip
+        if (!commands.has(prog)) commands.set(prog, where);
+      }
+    });
+  }
+  return { commands, hosts };
+}
+
 function permissionGaps(cat, s, findings) {
   const dir = skillDir(cat, s);
-  if (!dir || !fs.existsSync(path.join(dir, "scripts"))) return [];
+  if (!dir) return [];
+  const scripted = fs.existsSync(path.join(dir, "scripts"));
   const perm = permissionsOf(cat, s);
+  const told = cat.shape === "apm" ? { commands: new Map(), hosts: new Map() } : instructedRuns(dir);
+  const instructionGaps = () => {
+    const out = [];
+    const cmds = (perm && perm.commands) || [], net = (perm && perm.network) || [];
+    for (const [c, w] of told.commands)
+      if (!cmds.includes("*") && !cmds.includes(c))
+        out.push({ sev: "🟨", id: "undeclared-instructed-command", owasp: ["AST03", "AST10"], ...w,
+                   why: `the instructions tell the agent to run \`${c}\`, but the manifest's permissions.commands doesn't list it` });
+    for (const [h, w] of told.hosts)
+      if (!net.includes(h))
+        out.push({ sev: "🟨", id: "undeclared-instructed-network", owasp: ["AST03", "AST10"], ...w,
+                   why: `the instructions tell the agent to reach ${h}, but the manifest's permissions.network doesn't list it` });
+    return out;
+  };
+  if (!scripted) return instructionGaps();
   if (!perm)
     return [{ sev: "🟨", id: "no-permissions", owasp: ["AST03", "AST10"], file: "manifest.json", line: 0,
               why: "ships scripts but declares no permissions (network, commands, files) — nothing to check them against",
@@ -633,7 +697,7 @@ function permissionGaps(cat, s, findings) {
     if (f.id === "broad-fs" && perm.files !== "anywhere")
       gap("undeclared-files", f, `writes outside its own paths, but the manifest declares files: "${perm.files}"`);
   }
-  return gaps;
+  return gaps.concat(instructionGaps());
 }
 function permissionSummary(perm) {
   if (!perm) return "no permissions declared";
@@ -643,35 +707,82 @@ function permissionSummary(perm) {
   return `${net} · ${cmds} · ${files}`;
 }
 
-function printScan(cat, names, { compact = false } = {}) {
+/* RFC-0054: an agent is a system prompt the tool adopts whole, with the tools its frontmatter
+   grants, so it gets the prose rules a SKILL.md gets plus the checks only an agent needs. */
+function scanAgent(cat, a) {
+  const file = agentPath(cat, a);
+  const findings = [];
+  if (!file || !fs.existsSync(file)) return findings;
+  const rel = path.basename(file);
+  const text = fs.readFileSync(file, "utf8");
+  text.split(/\r?\n/).forEach((line, i) => {
+    if (line.length > 400) return;
+    for (const r of PROSE_RULES)
+      if (r.re.test(line)) findings.push({ sev: r.sev, id: r.id, why: r.why, owasp: r.owasp, file: rel, line: i + 1, text: line.trim().slice(0, 120) });
+  });
+  const fmEnd = text.startsWith("---") ? text.indexOf("\n---", 3) : -1;
+  const fm = fmEnd > 0 ? text.slice(0, fmEnd) : "";
+  const lineOf = (re) => { const i = fm.split("\n").findIndex((l) => re.test(l)); return i < 0 ? 1 : i + 1; };
+  const at = (re) => ({ file: rel, line: lineOf(re), text: (fm.split("\n")[lineOf(re) - 1] || "").trim().slice(0, 120) });
+  const tools = (fm.match(/^tools:\s*(.*)$/m) || [null, null])[1];
+  const list = tools === null ? null : tools.replace(/[[\]"']/g, "").split(",").map((t) => t.trim()).filter(Boolean);
+  if (list === null)
+    findings.push({ sev: "🟧", id: "agent-all-tools", owasp: ["AST03", "LLM06"], ...at(/^name:/),
+                    why: "has no `tools:` list, so it inherits every tool the session has, including any MCP server's" });
+  else {
+    const reads = list.filter((t) => /^(WebFetch|WebSearch)$/.test(t) || /^mcp__/.test(t));
+    const acts = list.filter((t) => /^(Bash|Write|Edit|NotebookEdit)$/.test(t));
+    if (reads.length && acts.length)
+      findings.push({ sev: "🟧", id: "agent-untrusted-and-act", owasp: ["AST03", "LLM01", "LLM06"], ...at(/^tools:/),
+                      why: `reads content from outside (${reads.join(", ")}) and can act on it (${acts.join(", ")}) in the same context: an injected instruction in what it reads can run` });
+  }
+  if (/^permissionMode:\s*(bypassPermissions|acceptEdits)/m.test(fm))
+    findings.push({ sev: "🟥", id: "agent-skips-approval", owasp: ["AST03", "LLM06"], ...at(/^permissionMode:/),
+                    why: "sets a permission mode that skips the user's approval for its actions" });
+  if (/^hooks:/m.test(fm))
+    findings.push({ sev: "🟧", id: "agent-hooks", owasp: ["AST03", "AST01"], ...at(/^hooks:/),
+                    why: "defines hooks: commands that run on events, outside the conversation the user reads" });
+  const order = { "🟥": 0, "🟧": 1, "🟨": 2, "⚪": 3 };
+  return findings.sort((x, y) => order[x.sev] - order[y.sev]);
+}
+
+function printScan(cat, names, { compact = false, scanner = scanSkill, kind = "" } = {}) {
   let total = 0, worst = null;
   for (const s of names) {
-    const f = scanSkill(cat, s);
+    const f = scanner(cat, s);
     if (!f.length) continue;
     total += f.length;
     if (!worst || f[0].sev === "🟥") worst = worst === "🟥" ? worst : f[0].sev;
-    console.log(`\n${s}`);
+    console.log(`\n${kind === "agent" ? "agent " : ""}${s}`);
     for (const x of (compact ? f.slice(0, 3) : f))
       console.log(`  ${x.sev} ${x.id} — ${x.why}  [${x.owasp.join(", ")}]\n     ${x.file}:${x.line}  ${x.text}`);
-    if (compact && f.length > 3) console.log(`     … ${f.length - 3} more (skilldrop scan ${s} --from ${cat.source})`);
+    if (compact && f.length > 3) console.log(`     … ${f.length - 3} more (skilldrop scan ${kind === "agent" ? "--agent " : ""}${s} --from ${cat.source})`);
   }
   return { total, worst };
 }
 
 function scan(args) {
   const cat = resolveCatalog(args.flags.from);
-  const names = args._.length ? args._.slice() : skillsIn(cat);
+  // `scan` alone covers every skill and agent; `scan <skills>` the named skills;
+  // `scan --agent [names]` agents only (--agents works too) (an agent may share a skill's name).
+  const agentsOnly = !!(args.flags.agent || args.flags.agents);
+  const names = agentsOnly ? [] : (args._.length ? args._.slice() : skillsIn(cat));
+  const agents = agentsOnly ? (args._.length ? args._.slice() : agentsIn(cat)) : (args._.length ? [] : agentsIn(cat));
   for (const s of names) if (!skillExists(cat, s)) die(`unknown skill '${s}' in catalog '${cat.source}'`);
+  for (const a of agents) if (!agentsIn(cat).includes(a)) die(`unknown agent '${a}' in catalog '${cat.source}'`);
 
   if (args.flags.json) {
     const out = names.map((s) => ({ skill: s, findings: scanSkill(cat, s) })).filter((r) => r.findings.length);
+    const aout = agents.map((a) => ({ agent: a, findings: scanAgent(cat, a) })).filter((r) => r.findings.length);
     return emitJSON({
-      catalog: cat.source, scanned: names.length,
-      flagged: out.length, findingCount: out.reduce((n, r) => n + r.findings.length, 0), skills: out,
+      catalog: cat.source, scanned: names.length, agentsScanned: agents.length,
+      flagged: out.length + aout.length,
+      findingCount: out.reduce((n, r) => n + r.findings.length, 0) + aout.reduce((n, r) => n + r.findings.length, 0),
+      skills: out, agents: aout,
     });
   }
-  console.log(`Scanning ${names.length} skill(s) in catalog '${cat.source}' for supply-chain patterns…`);
-  const { total } = printScan(cat, names);
+  console.log(`Scanning ${names.length} skill(s)${agents.length ? ` and ${agents.length} agent(s)` : ""} in catalog '${cat.source}' for supply-chain patterns…`);
+  const total = printScan(cat, names).total + printScan(cat, agents, { scanner: scanAgent, kind: "agent" }).total;
   if (!total) {
     console.log("\nNo flagged patterns found.");
   } else {
@@ -1373,9 +1484,9 @@ function install(args) {
     console.log(`\nWARNING: third-party catalog '${cat.source}'. Skills are instructions your AI agent will follow — review each installed SKILL.md under ${dest} before first use. Install copied files only; nothing was executed.`);
     // Supply-chain scan (RFC-0022): surface risky patterns at the moment of trust. Reports only —
     // the files are already copied, and a match is a prompt to read, not a verdict.
-    const scripted = names.filter((s) => fs.existsSync(path.join(skillDir(cat, s), "scripts")));
+    const scripted = names.filter((s) => fs.existsSync(path.join(skillDir(cat, s), "scripts")) || permissionsOf(cat, s));
     if (scripted.length) {
-      console.log(`\nWhat the scripts declare they do (RFC-0039):`);
+      console.log(`\nWhat each skill declares it runs and reaches (RFC-0039, RFC-0054):`);
       for (const s of scripted) console.log(`  ${s}: ${permissionSummary(permissionsOf(cat, s))}`);
     }
     const { total } = printScan(cat, names, { compact: true });
@@ -2255,8 +2366,12 @@ function installAgents(args) {
   if (ide === "copilot") console.log("Invoke with: copilot --agent <name>");
   if (ide === "codex") console.log("sandbox_mode is left unset, so each agent inherits the parent session's permissions.");
   if (ide === "antigravity") console.log("Emitted with `subagent: true` so invoke_subagent can reach them.");
-  if (cat.source !== BUNDLED)
+  if (cat.source !== BUNDLED) {
     console.log(`\nWARNING: third-party catalog '${cat.source}'. An agent is a system prompt your tool will adopt — read it before first use. Install copied files only; nothing was executed.`);
+    const { total } = printScan(cat, names, { compact: true, scanner: scanAgent, kind: "agent" });
+    console.log(total ? `\n${total} pattern(s) worth reading before you trust these agents. Full detail: skilldrop scan --agent --from ${cat.source}`
+                      : "\nSupply-chain scan: no flagged patterns.");
+  }
 }
 
 function uninstallAgents(args) {

package/contracts/skill.schema.json

@@ -42,12 +42,12 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["network", "commands", "files"],
-      "description": "RFC-0039 (OWASP AST03, AST10). What the skill's scripts do, declared so a reader and `skilldrop scan` can compare it with what the code does. Required for every skill that ships scripts/.",
+      "description": "RFC-0039, RFC-0054 (OWASP AST03, AST10). What the skill's scripts do and what its instructions tell the agent to run, declared so a reader and `skilldrop scan` can compare it with the code and with every fenced shell block in SKILL.md and its reference files. Required for every skill that ships scripts/, and for any skill whose instructions run a program or reach a host.",
       "properties": {
         "network": { "type": "array", "items": { "type": "string" },
-                     "description": "Hosts the scripts contact, e.g. api.figma.com. Empty means none." },
+                     "description": "Hosts the scripts contact or the instructed commands reach, e.g. api.figma.com. Empty means none." },
         "commands": { "type": "array", "items": { "type": "string" },
-                      "description": "External programs the scripts run, e.g. pdftotext. \"*\" means commands the user configures. Empty means none." },
+                      "description": "External programs the scripts run or the instructions tell the agent to run, e.g. pdftotext, terraform. \"*\" means commands the user configures. Empty means none." },
         "files": { "type": "string", "enum": ["none", "named-paths", "project", "anywhere"],
                    "description": "What the scripts write: nothing; only paths the user names; inside the current project; or anywhere." },
         "notes": { "type": "string", "description": "Anything a reviewer should know that the fields can't say." }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.16.31",
+  "version": "0.16.33",
   "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/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/converters/skills/mermaid-render/manifest.json

@@ -32,7 +32,17 @@
     "png",
     "render"
   ],
-  "permissions": {"network": [], "commands": ["mmdc"], "files": "named-paths", "notes": "mmdc (mermaid-cli) renders SVG, PNG and PDF if it is installed. Without it the script writes an HTML page that loads Mermaid from cdn.jsdelivr.net when opened; the script itself makes no network calls."},
+  "permissions": {
+    "network": [
+      "registry.npmjs.org"
+    ],
+    "commands": [
+      "mmdc",
+      "npm"
+    ],
+    "files": "named-paths",
+    "notes": "mmdc (mermaid-cli) renders SVG, PNG and PDF if it is installed. Without it the script writes an HTML page that loads Mermaid from cdn.jsdelivr.net when opened; the script itself makes no network calls. Its instructions suggest installing mermaid-cli with `npm install -g @mermaid-js/mermaid-cli`, which reaches the npm registry."
+  },
   "model": {
     "tier": "standard",
     "rationale": "The script lints and renders deterministically, but fixing a broken diagram means reading the author's intent and rewriting syntax without changing nodes, edges or labels, and knowing when to ask instead."

package/packs/dev-team/skills/codebase-tour/evals/files/3/.github/workflows/ci.yml

@@ -7,7 +7,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
         with:
-          go-version: "1.22"
+          go-version: "1.25"
       - run: make lint
       - run: make test
   integration:
@@ -24,5 +24,5 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
         with:
-          go-version: "1.22"
+          go-version: "1.25"
       - run: make test-integration

package/packs/dev-team/skills/codebase-tour/evals/files/3/go.mod

@@ -1,5 +1,5 @@
 module example.com/tidepool
 
-go 1.22
+go 1.25.0
 
-require github.com/jackc/pgx/v5 v5.5.5
+require github.com/jackc/pgx/v5 v5.9.2