@tiagojct/subsub 0.17.0 → 0.19.0

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.19.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.