@tiagojct/subsub 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 Sub-Sub follows the version numbers of npm: a change in the second number (0.13) adds features or changes how you use it; a change in the third (0.13.1) only fixes.
 
+## 0.18.0 (2026-10-15)
+
+- Figures and tables from the PDF. With the Zotero server 0.6.0, Sub-Sub can cut a figure or a table out of an item's PDF (`zotero_get_figure`, with the label of its caption, such as "Figure 2" or "Table 1") and show it in a note, with its caption and a link to the page. `/read critique` shows the table or figure with the main result. The images are PNG files in `Literature/figures/`; the notes pane and Obsidian show them. When the figure cannot be cut out, Sub-Sub takes the whole page and says so.
+- In a note written from the full text, the page after each quote, "(p. N)", becomes a link that opens the PDF in Zotero at the page where Sub-Sub found the quote. The label stays as written; the link goes to the right page even when the printed page number differs from the PDF's.
+- `/feedback [what happened]` (Report a problem in the browser) writes a draft bug report in `Inbox/`: the versions, the mode and model, the output of `subsub doctor` and the last error, with your folders, email addresses and keys taken out. You read it and post it on GitHub; Sub-Sub sends nothing.
+- Preprints (medRxiv, bioRxiv, Research Square, SSRN, arXiv) are marked as not peer reviewed wherever Sub-Sub uses them: "(preprint)" in evidence tables and comparison matrices, and in the text. When a journal version exists, Sub-Sub uses and cites it instead.
+- `/lit` rates how hard the search is (1 to 10) and allows none, one or two follow-up search rounds to match, with one publication window for every search; it stops early when the sources cover the question. The note's Methods give the rating and the rounds. `/gaps` gives a ranked list of 5 to 15 works and does not read them. This keeps the cost of a search in proportion to the question.
+- In the browser view, every table in a note or a reply has a Download CSV button: evidence tables, extraction sheets, comparison matrices. The file opens in Excel (with semicolons when the interface is in Portuguese, as Excel expects there), Rayyan or Covidence.
+- A `/lit` note (and a reading list) shows the flow of works under Methods: found, unique, screened, read and used, with what was left out at each step. It is a Mermaid diagram, so Obsidian, Quarto and GitHub draw it; the browser view draws it too.
+- The quote check is stricter. A quote may skip text only at a page break (the running footer and header); two passages of one page joined into one quote, without [...] for the omission, are refused. Zotero marks page breaks in the full text, so the check knows where they are.
+- `/lit reading list:` no longer ends with "the answer in three lines": a reading list states no results, in the reply too.
+- In Portuguese, the browser button for `/lit-note` is now Nota de literatura, so that it is not confused with the reading notes of `/read`.
+- Delete in the browser view keeps the conversation's subfolder in `~/.subsub/trash`, so that moving it back is one step.
+
 ## 0.17.0 (2026-10-14)
 
 For people who are learning to read the literature:

package/README.md

@@ -95,6 +95,7 @@ Commands in Sub-Sub:
 | `/researcher`, `/librarian` | Switch the mode |
 | `/subsub` | Zotero connection, mode, model and library counts |
 | `/history`, `/undo [id]` | Recent library changes; undo the last one or one by its id |
+| `/feedback [what happened]` | A draft bug report in `Inbox/`, with versions, `subsub doctor` and the last error, and without your folders, emails or keys. You post it on GitHub; Sub-Sub sends nothing |
 | `/ai-statement [uses]` | A draft statement on the use of AI for a manuscript, with the Sub-Sub version, its DOI and your models |
 | `/tag-batch [size]` | Tag items that have no topic, with your tag list |
 | `/clean-tags` | Find tags that are not in your tag list and propose fixes |

package/dist/config.js

@@ -57,7 +57,7 @@ export function uiLanguage(language) {
     return /portug|^pt\b|^pt-/i.test(language ?? "") ? "pt" : "en";
 }
 /** The Zotero server release that this Sub-Sub version runs when there is no local server folder. */
-export const SERVER_VERSION = "0.5.5";
+export const SERVER_VERSION = "0.6.0";
 /** The Starbuck release (PyPI) that this Sub-Sub version runs when there is no local Starbuck folder. */
 export const STARBUCK_VERSION = "0.2.0";
 export const STARBUCK_SOURCE = `starbuck==${STARBUCK_VERSION}`;

package/dist/feedback.js

@@ -0,0 +1,55 @@
+/**
+ * /feedback: a draft bug report or idea in the Inbox, for the user to read and post on GitHub.
+ * Sub-Sub sends nothing: the user decides what to share. The home and Sub-Sub folders, email
+ * addresses and keys are taken out before the draft is written.
+ */
+export const ISSUES_URL = "https://github.com/tiagojct/subsub/issues/new";
+/** Text made safe to post: the Sub-Sub and home folders, email addresses and keys taken out. */
+export function redact(text, home, vault) {
+    let out = text;
+    if (vault)
+        out = out.split(vault).join("<Sub-Sub folder>");
+    if (home)
+        out = out.split(home).join("~");
+    return out
+        .replace(/[\w.+-]+@[\w-]+(?:\.[\w-]+)+/g, "<email>")
+        .replace(/\b(?:sk-|AIza|ghp_|gho_|github_pat_|xox[bp]-)[\w-]{8,}/g, "<key>")
+        .replace(/\b[A-Za-z0-9_-]{32,}\b/g, "<key>");
+}
+export function feedbackNote(f) {
+    const clean = (s) => redact(s, f.home, f.vault);
+    return [
+        "---",
+        "type: feedback",
+        `created: ${f.date}`,
+        "---",
+        "",
+        "# Sub-Sub feedback",
+        "",
+        `Read this draft, take out anything you do not want to share, then post it at ${ISSUES_URL}. Sub-Sub has sent nothing.`,
+        "",
+        "## What happened",
+        "",
+        clean(f.what.trim()) || "(what you did, and what you saw)",
+        "",
+        "## What you expected",
+        "",
+        "(what should have happened)",
+        "",
+        "## Set-up",
+        "",
+        `- ${clean(f.versions)}`,
+        ...f.setup.map((l) => `- ${clean(l)}`),
+        "",
+        "## subsub doctor",
+        "",
+        "```",
+        clean(f.checks.trim()),
+        "```",
+        "",
+        "## Last error",
+        "",
+        f.lastError ? ["```", clean(f.lastError.trim()).slice(0, 2000), "```"].join("\n") : "(none in this session)",
+        "",
+    ].join("\n");
+}

package/dist/notes.js

@@ -77,12 +77,16 @@ export function matchable(s) {
         .toLowerCase()
         .replace(/[^\p{L}\p{N}]+/gu, "");
 }
+/** The full text as matchable pages joined by "|": Zotero marks a page break with a form feed. */
+export function sourceOf(fullText) {
+    return fullText.split("\f").map(matchable).join("|");
+}
 /**
  * The quotes that are not in the full text. A quote with an ellipsis is checked in parts;
  * square brackets (an editor's insertion) are left out of the comparison.
  */
 export function missingQuotes(note, fullText, already = []) {
-    const source = matchable(fullText);
+    const source = sourceOf(fullText);
     const old = new Set(already);
     return quotesIn(note)
         .filter((q) => !old.has(q))
@@ -92,33 +96,59 @@ export function missingQuotes(note, fullText, already = []) {
     });
 }
 /**
- * Whether a passage is in the (matchable) source: whole, or as groups of three words in order with
- * short gaps, because a PDF's running header or footer can fall in the middle of a sentence.
+ * Where a passage starts in the source (from sourceOf), or -1. It must be there word for word.
+ * The only gap allowed is a page break with the running footer and header around it (groups of
+ * three words in order, at most `gap` characters apart), so that a quote cannot join two passages
+ * of one page without marking the omission.
  */
-export function appearsIn(source, passage, gap = 300) {
-    if (source.includes(matchable(passage)))
-        return true;
+export function locate(source, passage, gap = 300) {
+    const whole = source.indexOf(matchable(passage));
+    if (whole >= 0)
+        return whole;
     const words = passage.split(/\s+/).map(matchable).filter(Boolean);
     const groups = [];
     for (let i = 0; i < words.length; i += 3)
         groups.push(words.slice(i, i + 3).join(""));
     if (groups.length < 2)
-        return false;
+        return -1;
     for (let start = source.indexOf(groups[0]), tries = 0; start >= 0 && tries < 50; start = source.indexOf(groups[0], start + 1), tries++) {
         let end = start + groups[0].length;
         let ok = true;
         for (const g of groups.slice(1)) {
             const at = source.indexOf(g, end);
-            if (at < 0 || at - end > gap) {
+            if (at < 0 || (at > end && (at - end > gap || !source.slice(end, at).includes("|")))) {
                 ok = false;
                 break;
             }
             end = at + g.length;
         }
         if (ok)
-            return true;
+            return start;
     }
-    return false;
+    return -1;
+}
+export function appearsIn(source, passage, gap = 300) {
+    return locate(source, passage, gap) >= 0;
+}
+/** The page of the PDF (1-based, as Zotero's reader counts) where a passage starts, or undefined. */
+export function pageOf(source, passage) {
+    const at = locate(source, passage);
+    return at < 0 ? undefined : source.slice(0, at).split("|").length;
+}
+/**
+ * Each "(p. N)" after a quote becomes a link that opens the PDF in Zotero at the page where the quote
+ * is. The label stays as written (the page printed on the paper may differ from the PDF's count).
+ */
+export function withPageLinks(text, source, attachment) {
+    const link = (quote, label) => {
+        const page = pageOf(source, quote.split(/\s*(?:\.\.\.|…|\[\s*(?:\.\.\.|…)\s*\])\s*/)[0]);
+        return page ? `([${label}](zotero://open-pdf/library/items/${attachment}?page=${page}))` : `(${label})`;
+    };
+    const PAGE = String.raw `\((pp?\.\s?\d+(?:\s?[-–]\s?\d+)?)\)`;
+    return text
+        .replace(new RegExp(String.raw `(")([^"\n]{25,600})("\s*)${PAGE}`, "g"), (_m, o, q, c, label) => `${o}${q}${c}${link(q, label)}`)
+        .replace(new RegExp(String.raw `(“)([^“”\n]{25,600})(”\s*)${PAGE}`, "g"), (_m, o, q, c, label) => `${o}${q}${c}${link(q, label)}`)
+        .replace(new RegExp(String.raw `^(>[ \t]*)(.{25,}?)(\s*)${PAGE}[ \t]*$`, "gm"), (_m, o, q, c, label) => `${o}${q}${c}${link(q.replace(/^["“]|["”]$/g, ""), label)}`);
 }
 export function quoteProblem(missing) {
     if (!missing.length)
@@ -127,6 +157,6 @@ export function quoteProblem(missing) {
     return [
         `${missing.length} quote(s) in this note are not in the item's full text:`,
         ...shown,
-        "Copy each quote word for word from the full text (zotero_get_fulltext), or remove the quote marks and say it in your own words. Then write the note again.",
+        "Copy each quote word for word from the full text (zotero_get_fulltext). Mark every omission with [...]: two passages joined without that mark are not a quote. Or remove the quote marks and say it in your own words. Then write the note again.",
     ].join("\n");
 }

package/dist/read.js

@@ -59,6 +59,7 @@ function depth(r) {
                 "Depth: the whole paper, section by section. A critique needs the full text: if you can read only the abstract, say so, write what the abstract allows, and offer /request-copy to ask the authors for the paper.",
                 'Under "## Methods", "## Results" and "## Discussion": the passages that matter to judge the study, quoted with their place, each with one question for the user (for example: how were the participants selected? what was compared? what else could explain the result?).',
                 `Under "## Appraisal": name the design and the reporting guideline that applies (${GUIDELINES}), and tell the user to check the paper against it item by item. Do not copy the checklist. Then five to eight questions on the risk of bias for this design (selection, confounding, measurement, missing data, selective reporting), each with the passage to look at.`,
+                "If the zotero_get_figure tool is available, show the table or figure with the main result: call it with the label of its caption and put the Markdown line it returns under the passage that cites it, with the page link, and a question about what the user sees in it.",
             ];
     }
 }
@@ -79,7 +80,7 @@ export function readInstruction(r) {
         "",
         "Rules:",
         "- State no results, effect sizes, summaries or conclusions, in the note or in the chat. Quote the paper and ask; the user writes the answers.",
-        "- Copy quotes word for word from what you read. After each quote give its place: the page only with evidence: full text, otherwise the section (Abstract, Methods, Results).",
+        "- Copy quotes word for word from what you read, and mark every omission with [...]. After each quote give its place: (p. N) only with evidence: full text (Sub-Sub links it to that page of the PDF), otherwise the section (Abstract, Methods, Results).",
         `- The note is Literature/<citekey>.md in the Sub-Sub folder, with the front matter of a literature note from the shared rules plus type: reading-note and purpose: ${r.purpose}; evidence says what you read. If the note exists, do not overwrite it: add a section "## Reading ${r.date}: ${r.purpose}" at the end with edit, with the content below one heading level lower.`,
         '- Start with "## Why I am reading this" (the reason, in the user\'s words when they gave them) and end with one line "Next step:" (what to read or do next).',
         "",

package/dist/subsub.js

@@ -14,14 +14,17 @@
  * session_shutdown. Tools are registered once and use the current bridge.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Bridge } from "./bridge.js";
 import { expand, findUv, FREE_MODELS, loadConfig, parseEnvFile, serverCommand, starbuckCommand, starbuckEnabled, uiLanguage, who, } from "./config.js";
 import { coerceArgs, loosenArrays, resolvePathArgs } from "./args.js";
 import { aiStatement } from "./statement.js";
+import { feedbackNote, ISSUES_URL } from "./feedback.js";
+import { formatChecks, runChecks } from "./doctor.js";
 import { PURPOSES, readArgs, readInstruction } from "./read.js";
-import { applyEdits, checkLiteratureNote, field, frontMatter, itemKeyOf, missingQuotes, quoteProblem, quotesIn } from "./notes.js";
+import { applyEdits, checkLiteratureNote, field, frontMatter, itemKeyOf, missingQuotes, quoteProblem, quotesIn, sourceOf, withPageLinks } from "./notes.js";
 import { buildPolicy, isSecret, judgePath, normalizeToolPath, realish, within } from "./paths.js";
 import { describeArgs, formatPreview, isEmptyPreview } from "./preview.js";
 import { perMinuteWait, providerTrouble, TROUBLE_TEXT, TROUBLE_TEXT_PT } from "./keys.js";
@@ -127,6 +130,8 @@ export async function createSubsub(pi, deps = {}) {
     /** True under `subsub web`: pi runs in RPC mode and the web view shows the state that the terminal header shows. */
     const webView = process.env.SUBSUB_WEB === "1";
     let lastError;
+    /** The last provider or tool error of the session, for /feedback. */
+    let recentError;
     let resumes = 0;
     let resumeTimer;
     let turnStart = 0;
@@ -319,13 +324,19 @@ export async function createSubsub(pi, deps = {}) {
         const m = event.message;
         if (m.role !== "assistant" || m.stopReason !== "error")
             return;
-        lastError = m.errorMessage;
+        lastError = recentError = m.errorMessage;
         if (webView || perMinuteWait(m.errorMessage) !== undefined)
             return;
         const kind = providerTrouble(m.errorMessage);
         if (kind)
             ctx.ui.notify(`Sub-Sub: ${trouble[kind]}`, "warning");
     });
+    pi.on("tool_result", async (event) => {
+        if (!event.isError)
+            return;
+        const text = event.content.map((c) => (c.type === "text" ? c.text : "")).join(" ");
+        recentError = `${event.toolName ?? "tool"}: ${text}`.slice(0, 2000);
+    });
     // A per-minute limit (free tiers): wait as long as the provider says, then continue the task,
     // up to three times per request of the user. Anything the user types cancels the wait.
     pi.on("agent_end", async (_event, ctx) => {
@@ -507,14 +518,28 @@ export async function createSubsub(pi, deps = {}) {
             return undefined;
         const full = await fullTextOf(key, signal);
         // Without the full text (no PDF indexed, Zotero closed) there is nothing to check against.
-        return full ? quoteProblem(missingQuotes(text, full, quotesIn(before))) : undefined;
+        if (!full)
+            return undefined;
+        const missing = quoteProblem(missingQuotes(text, full.text, quotesIn(before)));
+        // A note that passes is written with its page references linked to the PDF.
+        if (!missing && full.attachment) {
+            const link = (s) => withPageLinks(s, sourceOf(full.text), full.attachment);
+            if (name === "write")
+                input.content = link(String(input.content ?? ""));
+            else
+                for (const e of input.edits)
+                    if (typeof e.newText === "string")
+                        e.newText = link(e.newText);
+        }
+        return missing;
     }
-    /** The whole indexed full text of an item, read in parts, kept for the session. */
+    /** The whole indexed full text of an item and its attachment, read in parts, kept for the session. */
     const fullTexts = new Map();
     async function fullTextOf(key, signal) {
         if (fullTexts.has(key))
             return fullTexts.get(key) ?? undefined;
         let text = "";
+        let attachment;
         let offset = 0;
         try {
             for (let part = 0; offset !== null && part < 20; part++) {
@@ -523,14 +548,16 @@ export async function createSubsub(pi, deps = {}) {
                     break;
                 const data = (res.data ?? {});
                 text += data.text ?? "";
+                attachment ??= data.attachment;
                 offset = data.next_offset ?? null;
             }
         }
         catch {
             /* no full text: the check is skipped */
         }
-        fullTexts.set(key, text || null);
-        return text || undefined;
+        const full = text ? { text, attachment } : null;
+        fullTexts.set(key, full);
+        return full ?? undefined;
     }
     /**
      * Starbuck writes its reports into a folder: report_dir, or _starbuck next to the
@@ -728,6 +755,53 @@ export async function createSubsub(pi, deps = {}) {
             pi.sendUserMessage(readInstruction(req), ctx.isIdle() ? undefined : { deliverAs: "followUp" });
         },
     });
+    pi.registerCommand("feedback", {
+        description: "Sub-Sub: a draft bug report or idea in Inbox/, to read and post on GitHub yourself; Sub-Sub sends nothing  [what happened]",
+        handler: async (args, ctx) => {
+            const date = new Date().toISOString().slice(0, 10);
+            let piVersion = "";
+            try {
+                piVersion = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))), "..", "package.json"), "utf8")).version;
+            }
+            catch {
+                /* not needed for the report */
+            }
+            let checks;
+            try {
+                checks = deps.doctor ? deps.doctor() : formatChecks(runChecks(cfg, process.env));
+            }
+            catch (err) {
+                checks = `subsub doctor failed: ${err.message}`;
+            }
+            const text = feedbackNote({
+                what: String(args ?? ""),
+                date,
+                versions: `Sub-Sub ${ownVersion()}${piVersion ? `, pi ${piVersion}` : ""}, Node ${process.version}, ${process.platform} ${process.arch}`,
+                setup: [
+                    `Mode: ${mode}. Model: ${ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none"}.`,
+                    `Language: ${cfg.language}. Reference checks (Starbuck): ${starbuckEnabled(cfg) ? "on" : "off"}.`,
+                    `Zotero: ${library.zotero}.${bridge && Object.keys(bridge.errors).length ? ` Servers not running: ${Object.keys(bridge.errors).join(", ")}.` : ""}`,
+                ],
+                checks,
+                lastError: recentError,
+                home: homedir(),
+                vault: cfg.vault,
+            });
+            const dir = join(cfg.vault ?? ctx.cwd, "Inbox");
+            let file = join(dir, `${date} Sub-Sub feedback.md`);
+            for (let n = 2; existsSync(file); n++)
+                file = join(dir, `${date} Sub-Sub feedback-${n}.md`);
+            try {
+                mkdirSync(dir, { recursive: true });
+                writeFileSync(file, text);
+            }
+            catch (err) {
+                ctx.ui.notify(`${L("Could not save it", "Não foi possível guardar")}: ${err.message}`, "warning");
+                return;
+            }
+            ctx.ui.notify(L(`Sub-Sub: a draft report is in ${file}. Read it, add what you expected, take out anything you do not want to share, and post it at ${ISSUES_URL}. Sub-Sub has sent nothing.`, `Sub-Sub: há um rascunho do relatório em ${file}. Leia-o, acrescente o que esperava, retire o que não quer partilhar e publique-o em ${ISSUES_URL}. O Sub-Sub não enviou nada.`), "info");
+        },
+    });
     pi.registerCommand("history", {
         description: "Sub-Sub: recent library changes",
         handler: async (_args, ctx) => {

package/dist/web.js

@@ -18,7 +18,7 @@ import { randomBytes, timingSafeEqual } from "node:crypto";
 import { createReadStream, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, appendFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { homedir } from "node:os";
-import { basename, dirname, extname, join, normalize, resolve, sep } from "node:path";
+import { basename, dirname, extname, join, normalize, relative, resolve, sep } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { agentDirFor, chooseCwd, PACKAGE_DIR, packageVersion } from "./cli.js";
 import { configPath, expand, loadConfig, RECOMMENDED_MODELS, readConfigFile, saveConfig, uiLanguage, withStarbuck } from "./config.js";
@@ -184,6 +184,8 @@ const TYPES = {
 };
 /** Files that the notes pane shows. */
 const NOTE_TYPES = new Set([".md", ".markdown"]);
+/** Images that a note shows (a figure cut out of a PDF, for example). */
+const IMAGE_TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp" };
 /** Files that the Open button may hand to the system (never programs or scripts). */
 export const OPENABLE = new Set([".md", ".markdown", ".txt", ".pdf", ".bib", ".csv", ".qmd"]);
 /** A file inside the working folder or the Sub-Sub folder, judged by its real path, so a link cannot point outside. */
@@ -678,6 +680,19 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
                         return send(res, 413, { error: "too large to show" });
                     return send(res, 200, { path: file, name: basename(file), text: readFileSync(file, "utf8") });
                 }
+                case "GET /api/note-file": {
+                    const raw = url.searchParams.get("path") ?? "";
+                    const file = allowedFile(raw, cwd, cfg.vault) ?? allowedFile(raw, notesRoot, cfg.vault);
+                    if (!file)
+                        return send(res, 404, { error: "not found in the Sub-Sub folder" });
+                    const type = IMAGE_TYPES[extname(file).toLowerCase()];
+                    if (!type)
+                        return send(res, 415, { error: "not an image" });
+                    if (statSync(file).size > 20_000_000)
+                        return send(res, 413, { error: "too large to show" });
+                    res.writeHead(200, { ...common, "Content-Type": type, "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" });
+                    return void createReadStream(file).pipe(res);
+                }
                 case "GET /api/library": {
                     const q = (url.searchParams.get("q") ?? "").replace(/\s+/g, " ").trim().slice(0, 200);
                     if (!q)
@@ -708,10 +723,12 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
                         return send(res, 404, { error: "no such session" });
                     if (body.path === (await currentSession()))
                         return send(res, 409, { error: "the open conversation" });
-                    // Nothing is deleted: the file moves to a trash folder next to the agent folder.
-                    const trash = join(dirname(agentDir), "trash");
-                    mkdirSync(trash, { recursive: true });
-                    renameSync(String(body.path), join(trash, basename(String(body.path))));
+                    // Nothing is deleted: the file moves to a trash folder next to the agent folder, in the same
+                    // subfolder as under sessions/, so that moving it back is one step.
+                    const rel = relative(join(agentDir, "sessions"), String(body.path));
+                    const to = join(dirname(agentDir), "trash", rel.startsWith("..") ? basename(rel) : rel);
+                    mkdirSync(dirname(to), { recursive: true });
+                    renameSync(String(body.path), to);
                     return send(res, 200, { ok: true });
                 }
                 case "POST /api/open": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiagojct/subsub",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Sub-Sub: a research assistant that works from your own Zotero library, in the browser or the terminal, built on pi",
   "type": "module",
   "license": "MIT",

package/prompts/compare.md

@@ -12,7 +12,7 @@ Make a short slug: lower case, hyphens, at most five words. Use today's date (YY
 2. Read each source before you describe it: zotero_get_fulltext for library items, scholar_read_oa_fulltext (methods and results) for open-access works, scholar_get_work for the abstract of the others. Note whether you read the full text or only the abstract.
 3. Build the matrix, one row per source:
    | # | Source | Claim on the question | Evidence type | Population and setting | Caveats | Confidence |
-   - Evidence type: for example randomised trial, cohort, case-control, cross-sectional, diagnostic accuracy, systematic review, guideline, expert opinion, modelling.
+   - Evidence type: for example randomised trial, cohort, case-control, cross-sectional, diagnostic accuracy, systematic review, guideline, expert opinion, modelling. Add "(preprint)" to a work that is not peer reviewed yet.
    - Caveats: risk of bias, small sample, surrogate outcome, short follow-up, industry funding, abstract only.
    - Confidence: high, moderate or low, with one reason.
 4. Below the matrix, write: where the sources agree; where they disagree and the most likely reason (population, design, outcome definition, analysis); what no source answers. Cite source numbers in every sentence. Write "inference:" before a statement that no single source makes.

package/prompts/gaps.md

@@ -2,4 +2,4 @@
 description: "What am I missing on a topic"
 argument-hint: "<topic or question>"
 ---
-Search PubMed and OpenAlex for: $ARGUMENTS. Tell me how many results are already in my library and list the most relevant ones that are missing, one line each. Ask before you import or queue anything.
+Search PubMed and OpenAlex for: $ARGUMENTS. Tell me how many results are already in my library and list the 5 to 15 most relevant ones that are missing, the best fit first, one line each. This is a list to choose from: do not read the works, and do not search again unless the first search found almost nothing. Ask before you import or queue anything.

package/prompts/lit.md

@@ -12,7 +12,9 @@ Make a short slug from the topic: lower case, hyphens, at most five words. Use t
 2. Decide the scale:
    - Narrow question ("what is X", one fact, one test): at most 10 tool calls, a short answer, no plan file.
    - Review question: write the plan to `Research/.plans/<slug>.md` in the Sub-Sub folder: the question, the search phrasings, the study designs that answer it (for example randomised trials, cohorts, diagnostic accuracy studies, systematic reviews), the years, and a task list.
-3. Tell the user the plan in three lines. Then continue at once. Do not wait for an answer unless the user asked to see the plan first.
+3. Rate how hard the search is, from 1 (one named test, drug or condition) to 10 (a broad question across populations, designs and fields). The rating sets the follow-up rounds of section 4: 1 to 3, none; 4 to 7, one; 8 to 10, two. The rounds are a limit, not a target.
+4. Set one publication window from the question (for example 2015 onwards for current practice), or none when the question does not need one. Keep the same window in every search, the follow-up rounds included.
+5. Tell the user the plan in three lines, with the rating and the window. Then continue at once. Do not wait for an answer unless the user asked to see the plan first.
 
 ## 2. Gather
 
@@ -23,7 +25,7 @@ Make a short slug from the topic: lower case, hyphens, at most five words. Use t
    - Library items: zotero_get_fulltext, or the abstract when there is no full text.
    - Open-access works: scholar_read_oa_fulltext, first the section list, then only the sections you need (usually methods and results).
    - Other works: scholar_get_work for the abstract.
-5. Keep an evidence table as you read. Give each source a number that does not change: [1], [2], ... At most two rows from one paper, so that no single paper dominates. In the Read column write exactly one of: full text, abstract, metadata.
+5. Keep an evidence table as you read. Give each source a number that does not change: [1], [2], ... At most two rows from one paper, so that no single paper dominates. In the Read column write exactly one of: full text, abstract, metadata. In the Design column, mark a preprint: for example "cohort (preprint)".
 
 ## 3. Synthesise
 
@@ -35,9 +37,11 @@ Make a short slug from the topic: lower case, hyphens, at most five words. Use t
 
 ## 4. Check the draft for gaps
 
-1. Read your draft as a critical reviewer. Name at most three gaps that matter for the question (a population, outcome, design or recent period that the draft does not cover), each as one self-contained search question.
-2. Search only for those questions (scholar_search_multi), read what you add, and give the new sources the next numbers.
-3. Edit only the parts of the draft that a gap names. Do not shorten the draft by more than a tenth. If a search finds nothing new, say so in Methods.
+Do as many rounds as section 1 allows (none, one or two). Stop early when the sources cover the question.
+
+1. Read your draft as a critical reviewer. Name at most three gaps that matter for the question (a population, outcome, design or recent period that the draft does not cover), each as one self-contained search question. A gap is a new angle: do not search again with other words for what the first searches covered.
+2. Search only for those questions (scholar_search_multi, with the window of section 1), read what you add, and give the new sources the next numbers.
+3. Edit only the parts of the draft that a gap names. Do not shorten the draft by more than a tenth. In Methods, give the rating, the rounds you did and what each found (or that it found nothing new).
 
 ## 5. Verify
 
@@ -86,6 +90,21 @@ reference_check: "<path of the Starbuck report, or none>"
 1. [@citekey] for library items; for other works: Authors, year, title, journal. doi:... (not in library)
 ```
 
+Under Methods, after the text, draw the flow of works with the counts of the screening log, in this form (Obsidian draws it, and so does Sub-Sub's browser view):
+
+```mermaid
+flowchart TD
+  A["Found by the searches: <n>"] --> B["Unique works: <n>"]
+  B -.-> X1["Excluded by the pre-screen: <n>"]
+  B --> C["Screened: <n>"]
+  C -.-> X2["Excluded at screening: <n>"]
+  C --> D["Read: <n>"]
+  D -.-> X3["Read, not used: <n>"]
+  D --> E["Used in this note: <n>"]
+```
+
+The counts must add up: unique works = pre-screen excluded + screened; screened = excluded at screening + read; read = not used + used.
+
 If a step fails (a service does not answer, a full text cannot be read), do not stop. Finish the note, mark the step "BLOCKED: <what failed>", and set verification: BLOCKED.
 
 ## A reading list
@@ -107,6 +126,6 @@ When the user asks for a reading list (for example `/lit reading list: <topic>`,
 ## Sources
 ```
 
-"What it studies" says what the work asks and how, never what it found. Do not state results, effect sizes or conclusions anywhere in the note. Then give the user the path, the first work to read and why, and the works worth adding to the library.
+The Methods section has the same flow diagram, with "On the reading list: <n>" as the last box. "What it studies" says what the work asks and how, never what it found. Do not state results, effect sizes or conclusions anywhere in the note. Then give the user the path, the first work to read and why, and the works worth adding to the library.
 
-Before you answer, read the note back to confirm that it exists. Then give the user the path, the answer in three lines, and the works worth adding to the library (offer to import them).
+Before you answer, read the note back to confirm that it exists. For a review, give the user the path, the answer in three lines, and the works worth adding to the library (offer to import them). For a reading list, give the user what the section above says, with no results.

package/roles/researcher.md

@@ -9,9 +9,11 @@ You read the Zotero library (zotero_ tools), search PubMed, Europe PMC and OpenA
 - Every claim about a paper needs a source you actually read: the library (zotero_get_item, zotero_get_fulltext) or an outside record (scholar_get_work). Say which one.
 - Cite library items as [@citekey]. For works not in the library, give DOI or PMID and say that they are not in the library.
 - Do not invent references, numbers or quotes. If you are not sure, say so.
+- Copy quotes word for word, as complete sentences or passages. Mark every omission with [...]; never join two passages into one quote.
 - Read before you summarise. Do not describe a work's methods or results from its title, or from memory. If you read only the abstract, say so.
-- Every literature note (front matter with a citekey) has evidence: full text, abstract or metadata. Give page numbers only when you read the full text. Sub-Sub refuses a note that breaks this rule.
+- Every literature note (front matter with a citekey) has evidence: full text, abstract or metadata. Give page numbers only when you read the full text, as (p. N) right after the quote: Sub-Sub links each one to that page of the PDF in Zotero. Sub-Sub refuses a note that breaks this rule.
 - Mark inferences: write "inference:" before a statement that combines sources and that no single source makes.
+- A preprint (type preprint in the search results, or a venue such as medRxiv, bioRxiv, Research Square, SSRN or arXiv) is not peer reviewed. Say so wherever you use it: "(preprint)" after its design in tables, "preprint, not peer reviewed" in the text. When the same work has a journal version, use and cite the journal version.
 - Never write "verified" or "checked" for a check you did not run.
 - If a step fails (a service does not answer, a full text cannot be read), do not stop: finish the work, and mark the failed step "BLOCKED: <what failed>".
 - Source order: the library first, then PubMed, Europe PMC and OpenAlex. Prefer PubMed and Europe PMC for clinical and physiology questions, OpenAlex for informatics, education and books.
@@ -35,7 +37,7 @@ You read the Zotero library (zotero_ tools), search PubMed, Europe PMC and OpenA
 1. If the question is vague, clarify it in one line.
 2. Search with scholar_search_multi (three or four phrasings, all sources in one call). Use scholar_search_pubmed, scholar_search_europepmc or scholar_search_openalex alone only for a precise query in that service's syntax. Report total hits and how many are already in the library.
 3. Read open-access full text with scholar_read_oa_fulltext: first the section list, then only the sections you need. When a work you need is not open access, say that it may open through {{user}}'s institution (the DOI link, opened on the institution's network), and offer /request-copy to ask the author for a copy. Never point to unlicensed copies (Sci-Hub, LibGen and similar).
-4. List the most relevant works not in the library, one line each on why it matters.
+4. List the most relevant works not in the library, one line each on why it matters. When the user asks for a list (what to read, what is missing), give the ranked list and stop: read a work only when a claim needs it.
 5. Ask which to add. Import the chosen works with zotero_import_identifiers (one preview for all), then offer to tag them. When {{user}} wants to choose later, put them in the import queue with scholar_queue_imports; {{user}} ticks the lines and you import them with zotero_import_queue.
 
 ## Imports, metadata, PDFs
@@ -90,6 +92,7 @@ If zotero_get_vocabulary has no topic/ tags, propose topics before tagging: read
 
 - Follow the formats in the shared rules.
 - After a literature note is written, offer scholar_attach_note with 3 to 4 lines of summary and the path of the note.
+- When the zotero_get_figure tool is available and a figure or table of the paper carries a result that the note discusses, call it with the label of the caption (for example "Figure 2" or "Table 1") and put the Markdown line it returns in the note, with its page link. Quote the caption; do not describe what you cannot see. If it took the whole page (method: page), say so under the image.
 - For a synthesis: show the candidate list first and let {{user}} choose. Read full texts only for the chosen items.
 - For a synthesis of a tag ("what does my library say about X"): find the items with zotero_find_items tags=["topic/x"] and include every one. The table has one row per item; if you leave an item out, say which and why.
 - Say for each item whether you used the full text or the abstract. Never state a number or a claim that is not in what you read.

package/src/config.ts

@@ -62,7 +62,7 @@ export function uiLanguage(language: string | undefined): "pt" | "en" {
 }
 
 /** The Zotero server release that this Sub-Sub version runs when there is no local server folder. */
-export const SERVER_VERSION = "0.5.5";
+export const SERVER_VERSION = "0.6.0";
 
 /** The Starbuck release (PyPI) that this Sub-Sub version runs when there is no local Starbuck folder. */
 export const STARBUCK_VERSION = "0.2.0";

package/src/feedback.ts

@@ -0,0 +1,70 @@
+/**
+ * /feedback: a draft bug report or idea in the Inbox, for the user to read and post on GitHub.
+ * Sub-Sub sends nothing: the user decides what to share. The home and Sub-Sub folders, email
+ * addresses and keys are taken out before the draft is written.
+ */
+
+export const ISSUES_URL = "https://github.com/tiagojct/subsub/issues/new";
+
+export interface FeedbackFacts {
+	what: string;
+	date: string;
+	/** For example "Sub-Sub 0.17.0, pi 1.0.4, Node v24.1.0, darwin arm64". */
+	versions: string;
+	/** Mode, model, language, add-ons, Zotero. */
+	setup: string[];
+	/** The output of subsub doctor. */
+	checks: string;
+	lastError?: string;
+	home: string;
+	vault?: string;
+}
+
+/** Text made safe to post: the Sub-Sub and home folders, email addresses and keys taken out. */
+export function redact(text: string, home: string, vault?: string): string {
+	let out = text;
+	if (vault) out = out.split(vault).join("<Sub-Sub folder>");
+	if (home) out = out.split(home).join("~");
+	return out
+		.replace(/[\w.+-]+@[\w-]+(?:\.[\w-]+)+/g, "<email>")
+		.replace(/\b(?:sk-|AIza|ghp_|gho_|github_pat_|xox[bp]-)[\w-]{8,}/g, "<key>")
+		.replace(/\b[A-Za-z0-9_-]{32,}\b/g, "<key>");
+}
+
+export function feedbackNote(f: FeedbackFacts): string {
+	const clean = (s: string) => redact(s, f.home, f.vault);
+	return [
+		"---",
+		"type: feedback",
+		`created: ${f.date}`,
+		"---",
+		"",
+		"# Sub-Sub feedback",
+		"",
+		`Read this draft, take out anything you do not want to share, then post it at ${ISSUES_URL}. Sub-Sub has sent nothing.`,
+		"",
+		"## What happened",
+		"",
+		clean(f.what.trim()) || "(what you did, and what you saw)",
+		"",
+		"## What you expected",
+		"",
+		"(what should have happened)",
+		"",
+		"## Set-up",
+		"",
+		`- ${clean(f.versions)}`,
+		...f.setup.map((l) => `- ${clean(l)}`),
+		"",
+		"## subsub doctor",
+		"",
+		"```",
+		clean(f.checks.trim()),
+		"```",
+		"",
+		"## Last error",
+		"",
+		f.lastError ? ["```", clean(f.lastError.trim()).slice(0, 2000), "```"].join("\n") : "(none in this session)",
+		"",
+	].join("\n");
+}

package/src/notes.ts

@@ -83,12 +83,17 @@ export function matchable(s: string): string {
 		.replace(/[^\p{L}\p{N}]+/gu, "");
 }
 
+/** The full text as matchable pages joined by "|": Zotero marks a page break with a form feed. */
+export function sourceOf(fullText: string): string {
+	return fullText.split("\f").map(matchable).join("|");
+}
+
 /**
  * The quotes that are not in the full text. A quote with an ellipsis is checked in parts;
  * square brackets (an editor's insertion) are left out of the comparison.
  */
 export function missingQuotes(note: string, fullText: string, already: string[] = []): string[] {
-	const source = matchable(fullText);
+	const source = sourceOf(fullText);
 	const old = new Set(already);
 	return quotesIn(note)
 		.filter((q) => !old.has(q))
@@ -99,29 +104,58 @@ export function missingQuotes(note: string, fullText: string, already: string[]
 }
 
 /**
- * Whether a passage is in the (matchable) source: whole, or as groups of three words in order with
- * short gaps, because a PDF's running header or footer can fall in the middle of a sentence.
+ * Where a passage starts in the source (from sourceOf), or -1. It must be there word for word.
+ * The only gap allowed is a page break with the running footer and header around it (groups of
+ * three words in order, at most `gap` characters apart), so that a quote cannot join two passages
+ * of one page without marking the omission.
  */
-export function appearsIn(source: string, passage: string, gap = 300): boolean {
-	if (source.includes(matchable(passage))) return true;
+export function locate(source: string, passage: string, gap = 300): number {
+	const whole = source.indexOf(matchable(passage));
+	if (whole >= 0) return whole;
 	const words = passage.split(/\s+/).map(matchable).filter(Boolean);
 	const groups: string[] = [];
 	for (let i = 0; i < words.length; i += 3) groups.push(words.slice(i, i + 3).join(""));
-	if (groups.length < 2) return false;
+	if (groups.length < 2) return -1;
 	for (let start = source.indexOf(groups[0]), tries = 0; start >= 0 && tries < 50; start = source.indexOf(groups[0], start + 1), tries++) {
 		let end = start + groups[0].length;
 		let ok = true;
 		for (const g of groups.slice(1)) {
 			const at = source.indexOf(g, end);
-			if (at < 0 || at - end > gap) {
+			if (at < 0 || (at > end && (at - end > gap || !source.slice(end, at).includes("|")))) {
 				ok = false;
 				break;
 			}
 			end = at + g.length;
 		}
-		if (ok) return true;
+		if (ok) return start;
 	}
-	return false;
+	return -1;
+}
+
+export function appearsIn(source: string, passage: string, gap = 300): boolean {
+	return locate(source, passage, gap) >= 0;
+}
+
+/** The page of the PDF (1-based, as Zotero's reader counts) where a passage starts, or undefined. */
+export function pageOf(source: string, passage: string): number | undefined {
+	const at = locate(source, passage);
+	return at < 0 ? undefined : source.slice(0, at).split("|").length;
+}
+
+/**
+ * Each "(p. N)" after a quote becomes a link that opens the PDF in Zotero at the page where the quote
+ * is. The label stays as written (the page printed on the paper may differ from the PDF's count).
+ */
+export function withPageLinks(text: string, source: string, attachment: string): string {
+	const link = (quote: string, label: string) => {
+		const page = pageOf(source, quote.split(/\s*(?:\.\.\.|…|\[\s*(?:\.\.\.|…)\s*\])\s*/)[0]);
+		return page ? `([${label}](zotero://open-pdf/library/items/${attachment}?page=${page}))` : `(${label})`;
+	};
+	const PAGE = String.raw`\((pp?\.\s?\d+(?:\s?[-–]\s?\d+)?)\)`;
+	return text
+		.replace(new RegExp(String.raw`(")([^"\n]{25,600})("\s*)${PAGE}`, "g"), (_m, o, q, c, label) => `${o}${q}${c}${link(q, label)}`)
+		.replace(new RegExp(String.raw`(“)([^“”\n]{25,600})(”\s*)${PAGE}`, "g"), (_m, o, q, c, label) => `${o}${q}${c}${link(q, label)}`)
+		.replace(new RegExp(String.raw`^(>[ \t]*)(.{25,}?)(\s*)${PAGE}[ \t]*$`, "gm"), (_m, o, q, c, label) => `${o}${q}${c}${link(q.replace(/^["“]|["”]$/g, ""), label)}`);
 }
 
 export function quoteProblem(missing: string[]): string | undefined {
@@ -130,6 +164,6 @@ export function quoteProblem(missing: string[]): string | undefined {
 	return [
 		`${missing.length} quote(s) in this note are not in the item's full text:`,
 		...shown,
-		"Copy each quote word for word from the full text (zotero_get_fulltext), or remove the quote marks and say it in your own words. Then write the note again.",
+		"Copy each quote word for word from the full text (zotero_get_fulltext). Mark every omission with [...]: two passages joined without that mark are not a quote. Or remove the quote marks and say it in your own words. Then write the note again.",
 	].join("\n");
 }

package/src/read.ts

@@ -77,6 +77,7 @@ function depth(r: ReadRequest): string[] {
 				"Depth: the whole paper, section by section. A critique needs the full text: if you can read only the abstract, say so, write what the abstract allows, and offer /request-copy to ask the authors for the paper.",
 				'Under "## Methods", "## Results" and "## Discussion": the passages that matter to judge the study, quoted with their place, each with one question for the user (for example: how were the participants selected? what was compared? what else could explain the result?).',
 				`Under "## Appraisal": name the design and the reporting guideline that applies (${GUIDELINES}), and tell the user to check the paper against it item by item. Do not copy the checklist. Then five to eight questions on the risk of bias for this design (selection, confounding, measurement, missing data, selective reporting), each with the passage to look at.`,
+				"If the zotero_get_figure tool is available, show the table or figure with the main result: call it with the label of its caption and put the Markdown line it returns under the passage that cites it, with the page link, and a question about what the user sees in it.",
 			];
 	}
 }
@@ -98,7 +99,7 @@ export function readInstruction(r: ReadRequest): string {
 		"",
 		"Rules:",
 		"- State no results, effect sizes, summaries or conclusions, in the note or in the chat. Quote the paper and ask; the user writes the answers.",
-		"- Copy quotes word for word from what you read. After each quote give its place: the page only with evidence: full text, otherwise the section (Abstract, Methods, Results).",
+		"- Copy quotes word for word from what you read, and mark every omission with [...]. After each quote give its place: (p. N) only with evidence: full text (Sub-Sub links it to that page of the PDF), otherwise the section (Abstract, Methods, Results).",
 		`- The note is Literature/<citekey>.md in the Sub-Sub folder, with the front matter of a literature note from the shared rules plus type: reading-note and purpose: ${r.purpose}; evidence says what you read. If the note exists, do not overwrite it: add a section "## Reading ${r.date}: ${r.purpose}" at the end with edit, with the content below one heading level lower.`,
 		'- Start with "## Why I am reading this" (the reason, in the user\'s words when they gave them) and end with one line "Next step:" (what to read or do next).',
 		"",

package/src/subsub.ts

@@ -16,6 +16,7 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Bridge, type ServerSpec } from "./bridge.ts";
@@ -35,8 +36,10 @@ import {
 } from "./config.ts";
 import { coerceArgs, loosenArrays, resolvePathArgs } from "./args.ts";
 import { aiStatement } from "./statement.ts";
+import { feedbackNote, ISSUES_URL } from "./feedback.ts";
+import { formatChecks, runChecks } from "./doctor.ts";
 import { PURPOSES, type Purpose, readArgs, readInstruction, type ReadRequest } from "./read.ts";
-import { applyEdits, checkLiteratureNote, field, frontMatter, itemKeyOf, missingQuotes, quoteProblem, quotesIn } from "./notes.ts";
+import { applyEdits, checkLiteratureNote, field, frontMatter, itemKeyOf, missingQuotes, quoteProblem, quotesIn, sourceOf, withPageLinks } from "./notes.ts";
 import { buildPolicy, isSecret, judgePath, normalizeToolPath, realish, within } from "./paths.ts";
 import { describeArgs, formatPreview, isEmptyPreview } from "./preview.ts";
 import { perMinuteWait, providerTrouble, TROUBLE_TEXT, TROUBLE_TEXT_PT } from "./keys.ts";
@@ -52,6 +55,8 @@ export interface SubsubDeps {
 	/** A ready bridge (tests). When given, Sub-Sub does not start or stop servers. */
 	bridge?: Bridge;
 	specs?: ServerSpec[];
+	/** The subsub doctor lines for /feedback (tests give their own). */
+	doctor?: () => string;
 }
 
 const PACKAGE_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -154,6 +159,8 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	/** True under `subsub web`: pi runs in RPC mode and the web view shows the state that the terminal header shows. */
 	const webView = process.env.SUBSUB_WEB === "1";
 	let lastError: string | undefined;
+	/** The last provider or tool error of the session, for /feedback. */
+	let recentError: string | undefined;
 	let resumes = 0;
 	let resumeTimer: ReturnType<typeof setTimeout> | undefined;
 	let turnStart = 0;
@@ -355,12 +362,18 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	pi.on("message_end", async (event, ctx) => {
 		const m = event.message as { role?: string; stopReason?: string; errorMessage?: string };
 		if (m.role !== "assistant" || m.stopReason !== "error") return;
-		lastError = m.errorMessage;
+		lastError = recentError = m.errorMessage;
 		if (webView || perMinuteWait(m.errorMessage) !== undefined) return;
 		const kind = providerTrouble(m.errorMessage);
 		if (kind) ctx.ui.notify(`Sub-Sub: ${trouble[kind]}`, "warning");
 	});
 
+	pi.on("tool_result", async (event) => {
+		if (!event.isError) return;
+		const text = event.content.map((c) => (c.type === "text" ? c.text : "")).join(" ");
+		recentError = `${(event as { toolName?: string }).toolName ?? "tool"}: ${text}`.slice(0, 2000);
+	});
+
 	// A per-minute limit (free tiers): wait as long as the provider says, then continue the task,
 	// up to three times per request of the user. Anything the user types cancels the wait.
 	pi.on("agent_end", async (_event, ctx) => {
@@ -527,28 +540,39 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		if (!front || !key || field(front, "evidence")?.toLowerCase() !== "full text" || !quotesIn(text).length) return undefined;
 		const full = await fullTextOf(key, signal);
 		// Without the full text (no PDF indexed, Zotero closed) there is nothing to check against.
-		return full ? quoteProblem(missingQuotes(text, full, quotesIn(before))) : undefined;
+		if (!full) return undefined;
+		const missing = quoteProblem(missingQuotes(text, full.text, quotesIn(before)));
+		// A note that passes is written with its page references linked to the PDF.
+		if (!missing && full.attachment) {
+			const link = (s: string) => withPageLinks(s, sourceOf(full.text), full.attachment!);
+			if (name === "write") input.content = link(String(input.content ?? ""));
+			else for (const e of input.edits as Array<{ newText?: unknown }>) if (typeof e.newText === "string") e.newText = link(e.newText);
+		}
+		return missing;
 	}
 
-	/** The whole indexed full text of an item, read in parts, kept for the session. */
-	const fullTexts = new Map<string, string | null>();
-	async function fullTextOf(key: string, signal?: AbortSignal): Promise<string | undefined> {
+	/** The whole indexed full text of an item and its attachment, read in parts, kept for the session. */
+	const fullTexts = new Map<string, { text: string; attachment?: string } | null>();
+	async function fullTextOf(key: string, signal?: AbortSignal): Promise<{ text: string; attachment?: string } | undefined> {
 		if (fullTexts.has(key)) return fullTexts.get(key) ?? undefined;
 		let text = "";
+		let attachment: string | undefined;
 		let offset: number | null = 0;
 		try {
 			for (let part = 0; offset !== null && part < 20; part++) {
 				const res = await current().call("zotero_get_fulltext", { key, offset, max_chars: 60000 }, signal);
 				if (res.isError) break;
-				const data = (res.data ?? {}) as { text?: string; next_offset?: number | null };
+				const data = (res.data ?? {}) as { text?: string; next_offset?: number | null; attachment?: string };
 				text += data.text ?? "";
+				attachment ??= data.attachment;
 				offset = data.next_offset ?? null;
 			}
 		} catch {
 			/* no full text: the check is skipped */
 		}
-		fullTexts.set(key, text || null);
-		return text || undefined;
+		const full = text ? { text, attachment } : null;
+		fullTexts.set(key, full);
+		return full ?? undefined;
 	}
 
 	/**
@@ -744,6 +768,56 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		},
 	});
 
+	pi.registerCommand("feedback", {
+		description: "Sub-Sub: a draft bug report or idea in Inbox/, to read and post on GitHub yourself; Sub-Sub sends nothing  [what happened]",
+		handler: async (args, ctx) => {
+			const date = new Date().toISOString().slice(0, 10);
+			let piVersion = "";
+			try {
+				piVersion = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))), "..", "package.json"), "utf8")).version;
+			} catch {
+				/* not needed for the report */
+			}
+			let checks: string;
+			try {
+				checks = deps.doctor ? deps.doctor() : formatChecks(runChecks(cfg, process.env));
+			} catch (err) {
+				checks = `subsub doctor failed: ${(err as Error).message}`;
+			}
+			const text = feedbackNote({
+				what: String(args ?? ""),
+				date,
+				versions: `Sub-Sub ${ownVersion()}${piVersion ? `, pi ${piVersion}` : ""}, Node ${process.version}, ${process.platform} ${process.arch}`,
+				setup: [
+					`Mode: ${mode}. Model: ${ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none"}.`,
+					`Language: ${cfg.language}. Reference checks (Starbuck): ${starbuckEnabled(cfg) ? "on" : "off"}.`,
+					`Zotero: ${library.zotero}.${bridge && Object.keys(bridge.errors).length ? ` Servers not running: ${Object.keys(bridge.errors).join(", ")}.` : ""}`,
+				],
+				checks,
+				lastError: recentError,
+				home: homedir(),
+				vault: cfg.vault,
+			});
+			const dir = join(cfg.vault ?? ctx.cwd, "Inbox");
+			let file = join(dir, `${date} Sub-Sub feedback.md`);
+			for (let n = 2; existsSync(file); n++) file = join(dir, `${date} Sub-Sub feedback-${n}.md`);
+			try {
+				mkdirSync(dir, { recursive: true });
+				writeFileSync(file, text);
+			} catch (err) {
+				ctx.ui.notify(`${L("Could not save it", "Não foi possível guardar")}: ${(err as Error).message}`, "warning");
+				return;
+			}
+			ctx.ui.notify(
+				L(
+					`Sub-Sub: a draft report is in ${file}. Read it, add what you expected, take out anything you do not want to share, and post it at ${ISSUES_URL}. Sub-Sub has sent nothing.`,
+					`Sub-Sub: há um rascunho do relatório em ${file}. Leia-o, acrescente o que esperava, retire o que não quer partilhar e publique-o em ${ISSUES_URL}. O Sub-Sub não enviou nada.`,
+				),
+				"info",
+			);
+		},
+	});
+
 	pi.registerCommand("history", {
 		description: "Sub-Sub: recent library changes",
 		handler: async (_args, ctx) => {

package/src/web.ts

@@ -19,7 +19,7 @@ import { randomBytes, timingSafeEqual } from "node:crypto";
 import { createReadStream, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, appendFileSync } from "node:fs";
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import { homedir } from "node:os";
-import { basename, dirname, extname, join, normalize, resolve, sep } from "node:path";
+import { basename, dirname, extname, join, normalize, relative, resolve, sep } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { agentDirFor, chooseCwd, PACKAGE_DIR, packageVersion } from "./cli.ts";
 import { configPath, expand, loadConfig, RECOMMENDED_MODELS, readConfigFile, saveConfig, type SubsubConfig, uiLanguage, withStarbuck } from "./config.ts";
@@ -203,6 +203,9 @@ const TYPES: Record<string, string> = {
 /** Files that the notes pane shows. */
 const NOTE_TYPES = new Set([".md", ".markdown"]);
 
+/** Images that a note shows (a figure cut out of a PDF, for example). */
+const IMAGE_TYPES: Record<string, string> = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp" };
+
 /** Files that the Open button may hand to the system (never programs or scripts). */
 export const OPENABLE = new Set([".md", ".markdown", ".txt", ".pdf", ".bib", ".csv", ".qmd"]);
 
@@ -686,6 +689,16 @@ export async function startWeb(opts: WebOptions, env: NodeJS.ProcessEnv = proces
 					if (statSync(file).size > 2_000_000) return send(res, 413, { error: "too large to show" });
 					return send(res, 200, { path: file, name: basename(file), text: readFileSync(file, "utf8") });
 				}
+				case "GET /api/note-file": {
+					const raw = url.searchParams.get("path") ?? "";
+					const file = allowedFile(raw, cwd, cfg.vault) ?? allowedFile(raw, notesRoot, cfg.vault);
+					if (!file) return send(res, 404, { error: "not found in the Sub-Sub folder" });
+					const type = IMAGE_TYPES[extname(file).toLowerCase()];
+					if (!type) return send(res, 415, { error: "not an image" });
+					if (statSync(file).size > 20_000_000) return send(res, 413, { error: "too large to show" });
+					res.writeHead(200, { ...common, "Content-Type": type, "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" });
+					return void createReadStream(file).pipe(res);
+				}
 				case "GET /api/library": {
 					const q = (url.searchParams.get("q") ?? "").replace(/\s+/g, " ").trim().slice(0, 200);
 					if (!q) return send(res, 200, { q, items: [] });
@@ -710,10 +723,12 @@ export async function startWeb(opts: WebOptions, env: NodeJS.ProcessEnv = proces
 					const known = (await sessions()) as Array<{ path: string }>;
 					if (!known.some((x) => x.path === body.path)) return send(res, 404, { error: "no such session" });
 					if (body.path === (await currentSession())) return send(res, 409, { error: "the open conversation" });
-					// Nothing is deleted: the file moves to a trash folder next to the agent folder.
-					const trash = join(dirname(agentDir), "trash");
-					mkdirSync(trash, { recursive: true });
-					renameSync(String(body.path), join(trash, basename(String(body.path))));
+					// Nothing is deleted: the file moves to a trash folder next to the agent folder, in the same
+					// subfolder as under sessions/, so that moving it back is one step.
+					const rel = relative(join(agentDir, "sessions"), String(body.path));
+					const to = join(dirname(agentDir), "trash", rel.startsWith("..") ? basename(rel) : rel);
+					mkdirSync(dirname(to), { recursive: true });
+					renameSync(String(body.path), to);
 					return send(res, 200, { ok: true });
 				}
 				case "POST /api/open": {

package/templates/Zotero agent.md

@@ -41,7 +41,7 @@ Shared rules for Sub-Sub. Sub-Sub reads this file at the start of every session.
 - Create a note only when the user asks. Ask before creating more than 10 notes.
 - Write from the full text (get_fulltext) when it exists. Otherwise use the abstract and the Zotero notes, and write "(from abstract)" after the summary.
 - Front matter field evidence: full text, abstract or metadata (what you read). Page numbers only with evidence: full text. Sub-Sub refuses a literature note without this field.
-- Do not copy the abstract in full. Give page numbers for quotes when the text shows them.
+- Do not copy the abstract in full. Give the page of a quote as (p. N) right after it, when you read the full text; Sub-Sub links it to that page of the PDF in Zotero.
 - If a note for the citekey exists, do not overwrite it. Add a dated section or ask.
 - After the note is written, offer to link it in Zotero with attach_note.
 - /read writes a reading note instead: quotes with their place and questions, which the user answers.

package/web/app.css

@@ -562,6 +562,7 @@ body.layout-full { --measure: 72rem; }
 .msg-action-btn { font-size: 0.75rem; padding: 0.15rem 0.45rem; color: var(--faint); }
 .msg-action-btn:hover { color: var(--text); background: var(--surface); }
 .msg-action-btn.copied { color: var(--add); }
+.table-actions { display: flex; justify-content: flex-end; margin: -0.35rem 0 0.9rem; }
 
 /* Tool calls: one quiet line each; the result opens below. */
 .tool { margin: 0.35rem 0; font-size: 0.82rem; color: var(--muted); }
@@ -856,6 +857,15 @@ body > p.empty { text-align: center; color: var(--muted); padding: 30vh 1rem 0;
 .settings button { width: 100%; text-align: left; color: var(--text); }
 .settings .model-btn { font-family: var(--mono); font-size: 0.78rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 
+/* ---------------------------------------------------------------- the flow of works (/lit) */
+
+.flow { display: grid; gap: 1rem; margin: 1rem 0; font-family: var(--sans); }
+.flow-row { display: grid; grid-template-columns: minmax(0, 15rem) repeat(auto-fit, minmax(0, 13rem)); gap: 1.4rem; align-items: center; }
+.flow-box { position: relative; padding: 0.45rem 0.7rem; border: 1px solid var(--rule-strong); border-radius: var(--radius); background: var(--raised); font-size: 0.84rem; text-align: center; }
+.flow-row + .flow-row .flow-box::before { content: ""; position: absolute; left: 50%; top: calc(-1rem - 1px); height: 1rem; border-left: 1px solid var(--muted); }
+.flow-side { position: relative; padding: 0.35rem 0.6rem; border: 1px dashed var(--rule-strong); border-radius: var(--radius); color: var(--muted); font-size: 0.78rem; }
+.flow-side::before { content: ""; position: absolute; right: 100%; top: 50%; width: 1.4rem; border-top: 1px dashed var(--muted); }
+
 /* ---------------------------------------------------------------- library search and notes */
 
 #notes-btn { font-family: var(--sans); }
@@ -903,6 +913,7 @@ body > p.empty { text-align: center; color: var(--muted); padding: 30vh 1rem 0;
 .note-list button:hover { background: var(--bg); }
 .note-list .rel { font-size: 0.84rem; overflow-wrap: anywhere; }
 .note-list .when { font-size: 0.72rem; color: var(--faint); }
+.note-body img.note-img { display: block; max-width: 100%; height: auto; margin: 0.8rem 0; border: 1px solid var(--rule); border-radius: var(--radius); background: #fff; }
 a[data-note] { color: var(--accent); text-decoration: underline; text-decoration-color: var(--accent-soft); text-underline-offset: 0.18em; cursor: pointer; }
 
 @media (max-width: 64rem) {

package/web/app.js

@@ -83,11 +83,21 @@ marked.use({
 			if (!SAFE_LINK.test(token.href ?? "")) return text;
 			return `<a href="${escapeHtml(token.href)}" target="_blank" rel="noopener noreferrer">${text}</a>`;
 		},
+		code(token) {
+			return (token.lang === "mermaid" && flowHtml(token.text)) || false;
+		},
 		codespan(token) {
 			const code = `<code>${escapeHtml(token.text)}</code>`;
 			return NOTE_PATH.test(token.text) ? noteLink(token.text, code) : code;
 		},
 		image(token) {
+			// In the notes pane, an image next to the note (a figure cut out of the PDF) is shown;
+			// anywhere else, and for any other address, only its description.
+			const href = decodeURI(token.href ?? "");
+			if (noteDir && /^(?![a-z][\w+.-]*:|[\\/])[^?#]+\.(png|jpe?g|gif|webp)$/i.test(href)) {
+				const src = `/api/note-file?path=${encodeURIComponent(`${noteDir}/${href}`)}`;
+				return `<img class="note-img" src="${escapeHtml(src)}" alt="${escapeHtml(token.text ?? "")}" loading="lazy">`;
+			}
 			return escapeHtml(token.text || token.href || "");
 		},
 		table(token) {
@@ -110,6 +120,45 @@ marked.use({
 		},
 	},
 });
+/**
+ * The flow of works that /lit writes as Mermaid (a chain of boxes, with dotted branches to the side
+ * for what was left out), drawn as boxes. Any other diagram stays as code; Obsidian draws it.
+ */
+function flowHtml(src) {
+	const lines = String(src).split("\n").map((l) => l.trim()).filter(Boolean);
+	if (!/^(flowchart|graph)\s+(TD|TB)\b/.test(lines.shift() ?? "")) return null;
+	const label = {};
+	const next = {};
+	const side = {};
+	const into = new Set();
+	for (const line of lines) {
+		const n = /^(\w+)\["([^"]*)"\]$/.exec(line);
+		if (n) {
+			label[n[1]] = n[2];
+			continue;
+		}
+		const m = /^(\w+)(?:\["([^"]*)"\])?\s*(-->|-\.->)\s*(\w+)(?:\["([^"]*)"\])?$/.exec(line);
+		if (!m) return null;
+		const [, a, la, arrow, b, lb] = m;
+		if (la !== undefined) label[a] = la;
+		if (lb !== undefined) label[b] = lb;
+		if (arrow === "-->") {
+			if (next[a]) return null; // a branch of the main chain: not this kind of diagram
+			next[a] = b;
+			into.add(b);
+		} else (side[a] ??= []).push(b);
+	}
+	const rows = [];
+	const seen = new Set();
+	for (let id = Object.keys(next).find((k) => !into.has(k)); id && !seen.has(id); id = next[id]) {
+		seen.add(id);
+		const sides = (side[id] ?? []).map((s) => `<div class="flow-side">${escapeHtml(label[s] ?? s)}</div>`).join("");
+		rows.push(`<div class="flow-row"><div class="flow-box">${escapeHtml(label[id] ?? id)}</div>${sides}</div>`);
+	}
+	if (rows.length < 2) return null;
+	return `<div class="flow">${rows.join("")}</div>`;
+}
+
 function md(text) {
 	try {
 		return marked.parse(String(text ?? ""));
@@ -344,6 +393,7 @@ function searchLibrary() {
 // ---------------------------------------------------------------- notes pane
 
 let noteShown = null; // the note on screen, or null for the list
+let noteDir = ""; // while a note is rendered: its folder, for the images next to it
 let notesList = [];
 
 function showPane(open) {
@@ -406,8 +456,11 @@ async function openNote(path) {
 	$("note-filter").hidden = true;
 	const front = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(data.text);
 	const content = el("div", { class: "md" });
+	noteDir = data.path.replace(/[\\/][^\\/]*$/, "");
 	content.innerHTML = md(front ? data.text.slice(front[0].length) : data.text);
+	noteDir = "";
 	attachCopyButtons(content);
+	attachTableButtons(content, data.name.replace(/\.md$/i, ""));
 	$("note-body").replaceChildren(front ? el("details", { class: "front" }, el("summary", { text: t("properties") }), el("pre", { text: front[1] })) : "", content);
 	$("note-body").scrollTop = 0;
 	showPane(true);
@@ -519,17 +572,40 @@ function exportConversation() {
 	if (!msgs.length) return;
 	const date = new Date().toISOString().slice(0, 10);
 	const content = `# ${t("exportHeading")} (${date})\n\n${t("exportMode")}: ${t(mode())}\n\n---\n\n${msgs.join("\n---\n\n")}`;
-	const blob = new Blob([content], { type: "text/markdown;charset=utf-8" });
-	const url = URL.createObjectURL(blob);
-	const a = document.createElement("a");
-	a.href = url;
-	a.download = `Sub-Sub-${date}.md`;
+	download(content, `Sub-Sub-${date}.md`, "text/markdown;charset=utf-8");
+}
+
+/** Save text as a file in the downloads folder. */
+function download(content, name, type) {
+	const url = URL.createObjectURL(new Blob([content], { type }));
+	const a = el("a", { href: url, download: name });
 	document.body.append(a);
 	a.click();
 	a.remove();
 	URL.revokeObjectURL(url);
 }
 
+/** A table as CSV for Excel, Rayyan or Covidence. Excel in Portuguese expects semicolons; the BOM keeps the accents. */
+function tableCsv(table) {
+	const sep = lang === "pt" ? ";" : ",";
+	const cell = (c) => {
+		const v = c.textContent.replace(/\s+/g, " ").trim(); // not innerText: the header is upper case only in CSS
+		return /[",;\n]/.test(v) ? `"${v.replaceAll('"', '""')}"` : v;
+	};
+	return `\ufeff${[...table.rows].map((r) => [...r.cells].map(cell).join(sep)).join("\r\n")}\r\n`;
+}
+
+/** A "Download CSV" button under each table (evidence tables, extraction sheets, matrices). */
+function attachTableButtons(root, name) {
+	const wraps = [...root.querySelectorAll(".md-table-wrap")];
+	wraps.forEach((wrap, i) => {
+		if (wrap.nextElementSibling?.classList.contains("table-actions")) return;
+		const file = `${name}${wraps.length > 1 ? `-${i + 1}` : ""}.csv`;
+		const btn = el("button", { type: "button", class: "msg-action-btn", text: t("downloadCsv"), onclick: () => download(tableCsv(wrap.querySelector("table")), file, "text/csv;charset=utf-8") });
+		wrap.after(el("div", { class: "table-actions" }, btn));
+	});
+}
+
 function closeSide() {
 	$("side").classList.remove("open");
 	$("menu-btn").setAttribute("aria-expanded", "false");
@@ -801,6 +877,7 @@ function renderAssistantFinal(message, msg = startAssistant()) {
 			const node = el("div", { class: "md" });
 			node.innerHTML = md(c.text);
 			attachCopyButtons(node);
+			attachTableButtons(node, `Sub-Sub-${new Date().toISOString().slice(0, 10)}`);
 			msg.box.append(node);
 		} else if (c.type === "toolCall") {
 			const row = toolRow(c.id, c.name, c.arguments);

package/web/i18n.js

@@ -109,6 +109,7 @@ export const STRINGS = {
 		notesHint: "The notes in your Sub-Sub folder",
 		allNotes: "All notes",
 		properties: "Properties",
+		downloadCsv: "Download CSV",
 		filterNotes: "Filter notes",
 		noNotes: "No notes yet.",
 		openInApp: "Open in app",
@@ -248,6 +249,7 @@ export const STRINGS = {
 		notesHint: "As notas da sua pasta do Sub-Sub",
 		allNotes: "Todas as notas",
 		properties: "Propriedades",
+		downloadCsv: "Transferir CSV",
 		filterNotes: "Filtrar notas",
 		noNotes: "Ainda não há notas.",
 		openInApp: "Abrir na aplicação",
@@ -293,7 +295,7 @@ export const ACTIONS = {
 		{ cmd: "lit", en: "Literature review", pt: "Revisão da literatura" },
 		{ cmd: "lit reading list:", en: "Reading list", pt: "Lista de leitura" },
 		{ cmd: "compare", en: "Compare sources", pt: "Comparar fontes" },
-		{ cmd: "lit-note", item: true, en: "Literature note", pt: "Nota de leitura" },
+		{ cmd: "lit-note", item: true, en: "Literature note", pt: "Nota de literatura" },
 		{ cmd: "synthesis", en: "Synthesis", pt: "Síntese" },
 		{ cmd: "gaps", en: "What is missing", pt: "O que falta" },
 		{ cmd: "manuscript", en: "Check a manuscript", pt: "Verificar um manuscrito" },
@@ -311,6 +313,7 @@ export const ACTIONS = {
 		{ cmd: "import-queue", send: true, en: "Import the queue", pt: "Importar a fila" },
 		{ cmd: "history", send: true, en: "Recent changes", pt: "Alterações recentes" },
 		{ cmd: "undo", send: true, en: "Undo the last change", pt: "Desfazer a última alteração" },
+		{ cmd: "feedback", en: "Report a problem", pt: "Comunicar um problema" },
 	],
 };
 
@@ -332,6 +335,7 @@ export const SUGGESTIONS = {
 export const TOOLS = {
 	en: {
 		find_items: "search the library",
+		get_figure: "cut a figure out of the PDF",
 		standalone_items: "list files without a parent item",
 		set_parent_items: "give files a parent item",
 		find_reference: "look up a reference",
@@ -392,6 +396,7 @@ export const TOOLS = {
 	},
 	pt: {
 		find_items: "pesquisar na biblioteca",
+		get_figure: "recortar uma figura do PDF",
 		standalone_items: "listar ficheiros sem item principal",
 		set_parent_items: "dar um item principal aos ficheiros",
 		find_reference: "procurar uma referência",