@tiagojct/subsub 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 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.19.0 (2026-10-16)
+
+A new look for the browser view, the website, the tutorial and the workshop, after the engraved plates of 19th-century natural history books.
+
+- A grey-green paper, blue-black ink, and four colours with one meaning each: blue for the Researcher and for links, madder red for the Librarian, green for what is applied or checked, ochre for a preview. In dark mode the page is a blue-black plate.
+- Type: Literata for text, with true italics; Atkinson Hyperlegible Next for the interface; Atkinson Hyperlegible Mono for commands. They replace IBM Plex.
+- The notes pane shows what a note was written from: a line under `evidence:`, solid for the full text, dashed for the abstract, dotted for the metadata.
+- Reading mode in the notes pane: larger type and more space between lines, for long notes. Sub-Sub remembers it on this computer. The tutorial has the same button.
+- In a preview, a tag that would be removed is struck through instead of red. Errors show in ink, with a word, so that red belongs to the Librarian only. Each mode button keeps its own colour, selected or not.
+- A preview has a dashed frame: nothing has changed yet.
+
+## 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

@@ -1,6 +1,6 @@
 # Sub-Sub
 
-[![npm](https://img.shields.io/npm/v/@tiagojct/subsub.svg?style=flat-square&color=1d4f7c)](https://www.npmjs.com/package/@tiagojct/subsub)
+[![npm](https://img.shields.io/npm/v/@tiagojct/subsub.svg?style=flat-square&color=2c5d87)](https://www.npmjs.com/package/@tiagojct/subsub)
 [![Website](https://img.shields.io/badge/website-subsub.tiagojacinto.eu-a33b14.svg?style=flat-square)](https://subsub.tiagojacinto.eu)
 [![Licence: MIT](https://img.shields.io/badge/licence-MIT-5f5c55.svg?style=flat-square)](LICENSE)
 
@@ -24,7 +24,7 @@ Each mode can have its own model. Switch with `/researcher` and `/librarian`, or
 
 Every library change works the same way in both modes:
 
-- The Zotero server computes the change first. Sub-Sub shows it to you (added tags in green, removed tags in red) and applies it only when you select Yes. The check is in the program, so the model cannot skip it.
+- The Zotero server computes the change first. Sub-Sub shows it to you (the tags it adds and the tags it removes) and applies it only when you select Yes. The check is in the program, so the model cannot skip it.
 - If you edit an item in Zotero while the preview is open, Sub-Sub shows you the new preview before it changes anything. Each change also sends the item's version, so a field you edit at the moment of writing is not overwritten.
 - Every change is journaled, including new collections. `/undo` reverts the last one, and the browser view shows an Undo button under each change.
 - Nothing is deleted: items go to the Zotero trash. Only tags from your tag list can be added.
@@ -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 |
@@ -182,4 +183,4 @@ This DOI always points to the latest version; each version also has its own DOI
 
 ## Licence
 
-[MIT](LICENSE), Tiago Jacinto. The `/lit`, `/compare` and `/review` prompts adapt text from [Feynman](https://github.com/Companion-Inc/feynman) (MIT); see [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES). IBM Plex fonts: SIL Open Font License.
+[MIT](LICENSE), Tiago Jacinto. The `/lit`, `/compare` and `/review` prompts adapt text from [Feynman](https://github.com/Companion-Inc/feynman) (MIT); see [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES). Literata and Atkinson Hyperlegible fonts: SIL Open Font License.

package/THIRD_PARTY_NOTICES

@@ -55,99 +55,101 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 
-web/fonts/ and the website use IBM Plex Sans, IBM Plex Serif and IBM Plex Mono,
-https://github.com/IBM/plex. Their licence:
-
-Copyright © 2017 IBM Corp. with Reserved Font Name "Plex"
-
-This Font Software is licensed under the SIL Open Font License, Version 1.1.
-
-This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
-
-
------------------------------------------------------------
-SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
------------------------------------------------------------
-
-PREAMBLE
-The goals of the Open Font License (OFL) are to stimulate worldwide
-development of collaborative font projects, to support the font creation
-efforts of academic and linguistic communities, and to provide a free and
-open framework in which fonts may be shared and improved in partnership
-with others.
-
-The OFL allows the licensed fonts to be used, studied, modified and
-redistributed freely as long as they are not sold by themselves. The
-fonts, including any derivative works, can be bundled, embedded, 
-redistributed and/or sold with any software provided that any reserved
-names are not used by derivative works. The fonts and derivatives,
-however, cannot be released under any other type of license. The
-requirement for fonts to remain under this license does not apply
-to any document created using the fonts or their derivatives.
-
-DEFINITIONS
-"Font Software" refers to the set of files released by the Copyright
-Holder(s) under this license and clearly marked as such. This may
-include source files, build scripts and documentation.
-
-"Reserved Font Name" refers to any names specified as such after the
-copyright statement(s).
-
-"Original Version" refers to the collection of Font Software components as
-distributed by the Copyright Holder(s).
-
-"Modified Version" refers to any derivative made by adding to, deleting,
-or substituting -- in part or in whole -- any of the components of the
-Original Version, by changing formats or by porting the Font Software to a
-new environment.
-
-"Author" refers to any designer, engineer, programmer, technical
-writer or other person who contributed to the Font Software.
-
-PERMISSION & CONDITIONS
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of the Font Software, to use, study, copy, merge, embed, modify,
-redistribute, and sell modified and unmodified copies of the Font
-Software, subject to the following conditions:
-
-1) Neither the Font Software nor any of its individual components,
-in Original or Modified Versions, may be sold by itself.
-
-2) Original or Modified Versions of the Font Software may be bundled,
-redistributed and/or sold with any software, provided that each copy
-contains the above copyright notice and this license. These can be
-included either as stand-alone text files, human-readable headers or
-in the appropriate machine-readable metadata fields within text or
-binary files as long as those fields can be easily viewed by the user.
-
-3) No Modified Version of the Font Software may use the Reserved Font
-Name(s) unless explicit written permission is granted by the corresponding
-Copyright Holder. This restriction only applies to the primary font name as
-presented to the users.
-
-4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
-Software shall not be used to promote, endorse or advertise any
-Modified Version, except to acknowledge the contribution(s) of the
-Copyright Holder(s) and the Author(s) or with their explicit written
-permission.
-
-5) The Font Software, modified or unmodified, in part or in whole,
-must be distributed entirely under this license, and must not be
-distributed under any other license. The requirement for fonts to
-remain under this license does not apply to any document created
-using the Font Software.
-
-TERMINATION
-This license becomes null and void if any of the above conditions are
-not met.
-
-DISCLAIMER
-THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
-OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
-COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
-DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
-OTHER DEALINGS IN THE FONT SOFTWARE.
+web/fonts/, the website, the tutorial and the workshop use Literata, Atkinson
+Hyperlegible Next and Atkinson Hyperlegible Mono, subset to Latin. Their licence:
+
+Copyright 2017 The Literata Project Authors (https://github.com/googlefonts/literata)
+Copyright 2020-2024 The Atkinson Hyperlegible Next Project Authors (https://github.com/googlefonts/atkinson-hyperlegible-next)
+Copyright 2020-2024 The Atkinson Hyperlegible Mono Project Authors (https://github.com/googlefonts/atkinson-hyperlegible-next-mono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

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) => {