@tiagojct/subsub 0.6.0 → 0.7.0

package/docs/Subsub.md

@@ -58,8 +58,10 @@ Templates (type the name, then the argument):
 2. To add a shortcut (Applications on macOS), type `subsub shortcut`. To remove it, type `subsub shortcut --remove`.
 3. The server listens only on 127.0.0.1 and needs the random key in the address that `subsub web` opens. A second `subsub web` opens the running one.
 4. The server stops 10 minutes after the last page closes. `subsub web --stay` keeps it running.
-5. The labels are in European Portuguese when the language setting is Portuguese.
-6. The model button lists the models and saves an API key for a provider (the same auth.json as `/login`).
+5. The labels are in European Portuguese when the language setting is Portuguese. A theme toggle button in the header switches between light, dark and system themes.
+6. Faster review: in approval dialogs, press `y` to apply or `n` to cancel without using the mouse.
+7. One-click copy buttons appear on every code block and assistant note. The sidebar includes real-time conversation search and an Export button to download the discussion as Markdown.
+8. The model button lists the models and saves an API key for a provider (the same auth.json as `/login`).
 
 The log is in ~/.subsub/web.log.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiagojct/subsub",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Sub-Sub: a Zotero librarian and research assistant in the browser or the terminal, built on pi",
   "type": "module",
   "license": "MIT",
@@ -26,9 +26,11 @@
     ]
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "0.87.1",
     "@modelcontextprotocol/sdk": "^1.30.1"
   },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.0.2"
+  },
   "engines": {
     "node": ">=22.19.0"
   },
@@ -55,9 +57,11 @@
     "src",
     "templates",
     "themes",
-    "web"
+    "web",
+    "THIRD_PARTY_NOTICES"
   ],
   "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.0.2",
     "@types/node": "^24.19.0",
     "typescript": "^5.9.3"
   },

package/prompts/compare.md

@@ -0,0 +1,23 @@
+---
+description: "Researcher: compare sources on a question (a source matrix: claim, evidence type, caveats, confidence)"
+argument-hint: "<question, or citekeys, DOIs or PMIDs>"
+---
+Compare the sources on: $ARGUMENTS
+
+Make a short slug: lower case, hyphens, at most five words. Use today's date (YYYY-MM-DD).
+
+1. Find the sources.
+   - If the user gave citekeys, DOIs or PMIDs, use exactly those.
+   - Otherwise: library first (zotero_find_items), then scholar_search_multi with three phrasings. Choose 3 to 10 sources and say why.
+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.
+   - 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.
+5. Check the sources: verify_check_references when the verify_ tools are available, otherwise scholar_get_work for each identifier. Never write "verified" for a check you did not run.
+6. Write one note: `Research/<date> <slug> comparison.md` in the notes folder (do not overwrite; add -2). Front matter: title, date, type: comparison, sources (the identifiers), verification (PASS, PASS WITH NOTES or BLOCKED), reference_check (path of the Starbuck report, or none). End with a Sources section: [@citekey] for library items, full reference with DOI and "(not in library)" for the others.
+7. If a step fails, finish the note anyway and mark the step "BLOCKED: <what failed>".
+
+Give the user the path and three lines on what the comparison shows.

package/prompts/digest.md

@@ -0,0 +1,23 @@
+---
+description: "Researcher: digest of the last days: new works from the alerts and what the recent notes changed"
+argument-hint: "[days, default 7] [topic]"
+---
+Write a digest of the last ${1:-7} days. Topic, if given: ${@:2}
+
+1. Collect, in the notes folder:
+   - the alert notes `Inbox/Literature alerts YYYY-MM-DD.md` dated in the period (the date is in the file name);
+   - the notes in `Research/` whose front matter `date:` is in the period;
+   - the literature notes whose front matter `created:` is in the period.
+   Use ls and find to list them, and read their front matter for the dates. If a topic is given, keep only what is about it.
+2. Read each note you use. Do not describe a work that you did not read in a note, an abstract (scholar_get_work) or a full text.
+3. Write `Research/Digest <today, YYYY-MM-DD>.md` (do not overwrite; add -2) with these sections, in this order:
+   - What changed in our understanding: what the period's notes and works add to or change in what the user knew, each point with its sources.
+   - New works worth reading: at most ten from the alerts, one line each on why, with DOI or PMID and whether it is in the library. Mark the ones the alert pre-screen excluded only if you keep them, and say why.
+   - Disagreements and open questions: between the new works, or between them and the earlier notes.
+   - Questions for the user: decisions that need the user (what to read, what to import, what to drop).
+   - Sources: [@citekey] for library items; full reference with DOI and "(not in library)" for the others.
+   Front matter: title, date, type: digest, period (from and to), sources (the notes and alert files used).
+4. If there is nothing in the period, say so in one line and do not write a note.
+5. Offer scholar_queue_imports for the works the user wants to add.
+
+Give the user the path and the three most important points.

package/prompts/lit.md

@@ -0,0 +1,87 @@
+---
+description: "Researcher: literature review on a health research question (library first, then PubMed, Europe PMC, OpenAlex)"
+argument-hint: "<question or topic>"
+---
+Do a literature review on: $ARGUMENTS
+
+Make a short slug from the topic: lower case, hyphens, at most five words. Use today's date (YYYY-MM-DD).
+
+## 1. Plan
+
+1. Write the question in one sentence. If it is a clinical question, state population, exposure or intervention, comparison and outcome when they apply.
+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 notes 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.
+
+## 2. Gather
+
+1. Library first: zotero_find_items for the topic (and the topic tags). Note what the library already has.
+2. Outside: scholar_search_multi with three or four phrasings of the question (synonyms, the test or drug name, the condition name, MeSH terms). Give include_terms (the key concepts) and exclude_terms (populations or designs outside the question) so that the server pre-screens the results. Use year limits when the question needs recent work.
+3. Screen. For every work in the merged list, decide: read, maybe, or exclude, with a reason of a few words. Prefer systematic reviews, guidelines and primary studies with the right design. Write the screening log to `Research/.plans/<slug>-screening.md`: a table (#, work, identifier, pre-screen, decision, reason) and the counts for a flow diagram: found by the searches, unique works, pre-screen excluded, screened, read, used.
+4. Read before you summarise:
+   - 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.
+
+## 3. Synthesise
+
+- Separate what the sources agree on, where they disagree (and why: population, design, outcome definition, follow-up), and what is still open.
+- Every factual sentence cites at least one source number. Write "inference:" before a statement that combines sources and is not stated in any of them.
+- Say for each source whether you read the full text or only the abstract.
+- Give numbers (effect sizes, accuracy, sample sizes) only from what you read, with the source.
+- Do not draft text for the user's own manuscript.
+
+## 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.
+
+## 5. Verify
+
+- If the verify_ tools are available: verify_check_references with the identifiers of every source in the evidence table. Fix the sources that fail. Report the ones that need checking.
+- If not: check each DOI or PMID with scholar_get_work.
+- Never write "verified" for a check you did not run.
+
+## 6. Deliver
+
+Write one note: `Research/<date> <slug>.md` in the notes folder. Do not overwrite an existing note; add -2 to the name. Use this structure:
+
+```markdown
+---
+title: "<question>"
+date: <YYYY-MM-DD>
+type: literature-review
+question: "<question in one sentence>"
+searches: ["<phrasing 1>", "<phrasing 2>", "<phrasing 3>"]
+sources_found: <number of unique works>
+sources_screened: <number>
+sources_read: <number>
+sources_used: <number>
+screening_log: "Research/.plans/<slug>-screening.md"
+verification: PASS | PASS WITH NOTES | BLOCKED
+reference_check: "<path of the Starbuck report, or none>"
+---
+
+## Answer
+(three to six sentences, with source numbers)
+
+## Evidence table
+| # | Source | Design | Population | Key finding | Read | In library |
+|---|---|---|---|---|---|---|
+
+## Agreement
+## Disagreement
+## Open questions
+## Methods
+(where you searched, the phrasings, the pre-screen terms, the screening counts, the gap searches, what you included and left out, and why)
+
+## Sources
+1. [@citekey] for library items; for other works: Authors, year, title, journal. doi:... (not in library)
+```
+
+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.
+
+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 scholar_queue_imports).

package/prompts/request-copy.md

@@ -0,0 +1,35 @@
+---
+description: "Researcher: draft an email asking the corresponding author for a copy of a paper (you send it)"
+argument-hint: "<citekey, DOI or PMID>"
+---
+Draft an email to ask the corresponding author of $1 for a copy of the paper.
+
+1. Find the work: zotero_get_item for a citekey or Zotero key, otherwise scholar_get_work. If it is open access (open_access, or scholar_read_oa_fulltext gives the full text), tell the user where to read it and stop: no email is needed.
+2. Find the address with scholar_find_contact. Use only an address it returns. Never guess or build an address from a name. If it returns none, give the user the article link and say: look for "Correspondence" on the article page; then stop.
+3. Write the draft to `Inbox/Copy request <citekey or DOI>.md` in the notes folder (do not overwrite; add -2):
+
+```markdown
+---
+title: "Copy request: <short title>"
+date: <YYYY-MM-DD>
+type: copy-request
+work: "<DOI or PMID>"
+to: "<address>"
+status: draft
+---
+
+[Open in the mail program](mailto:<address>?subject=<subject, URL-encoded>&body=<body, URL-encoded>)
+
+To: <address> (<author name>, from the PubMed record)
+Subject: Request for a copy of "<short title>"
+
+Dear Dr <family name>,
+
+<two or three sentences: who the user is (name, and the line about the user if set), why the paper matters for their work, and the request for a copy for personal research use.>
+
+Best regards,
+<the user's name>
+```
+
+4. Write the email in English unless the user asks for another language, or the author's affiliation and the user's language are both Portuguese. Keep it short and polite. Do not claim things about the user that you do not know.
+5. Do not send anything. Tell the user the path, and that the link opens the draft in their mail program.

package/prompts/review.md

@@ -0,0 +1,31 @@
+---
+description: "Researcher: critical review of a manuscript (FATAL, MAJOR, MINOR issues, annotations, revision plan); comments only"
+argument-hint: "<path to .qmd, .md or .docx>"
+---
+Review the manuscript $1 as a critical reader before submission. Comment only: do not rewrite the user's paragraphs and do not change the file.
+
+1. Read the whole manuscript (the read tool; for .docx, ask the user to convert it with `quarto pandoc $1 -o draft.md`). Identify the study design and the reporting guideline that applies: CONSORT (randomised trials), STROBE (observational studies), PRISMA (systematic reviews), STARD (diagnostic accuracy), TRIPOD or TRIPOD+AI (prediction models), CHEERS (economic evaluations), SRQR or COREQ (qualitative research). Say which one you used and why.
+2. Check, with the line or section where each issue is:
+   - Question and aims: clear, and matched by the design.
+   - Reporting: the items of the guideline that are missing or incomplete.
+   - Risk of bias: selection, confounding, measurement, missing data, selective reporting.
+   - Outcomes: defined before analysis, measured the same way in all groups, clinically meaningful.
+   - Statistics: sample size, the right test or model, effect sizes with confidence intervals (not only P values), multiple comparisons, handling of missing data.
+   - Claims beyond the data: causal language for associations, results generalised past the population studied, conclusions not supported by the results.
+   - References: if the verify_ tools are available, run verify_check_manuscript on $1 and include its Fail and Check results. Do not judge whether a source supports a claim unless you read the source.
+3. Rank every issue:
+   - FATAL: the main conclusion does not follow, or the study cannot answer its question.
+   - MAJOR: needs new analysis, new data or substantial rewriting.
+   - MINOR: wording, presentation, small reporting gaps.
+4. Write the review next to the manuscript as `<name>-review.md` (do not overwrite; add -2). Structure:
+   - Summary (three to five sentences: design, main finding, overall judgement)
+   - Strengths
+   - FATAL issues, MAJOR issues, MINOR issues: each with its location, a short quotation of the text, the problem, and what would fix it
+   - Reporting checklist: the guideline items missing or incomplete
+   - Reference check (Starbuck results, or "not run")
+   - Revision plan: the order in which to fix the issues
+   Front matter: title, date, type: manuscript-review, manuscript (path), guideline, verification (PASS, PASS WITH NOTES or BLOCKED).
+5. Quote the manuscript exactly. Do not invent line numbers: use section names when the file has no line numbers in view.
+6. If a check cannot run, write "BLOCKED: <what failed>" in that section and keep going.
+
+Give the user the path, the number of FATAL, MAJOR and MINOR issues, and the three most important ones.

package/prompts/verify.md

@@ -0,0 +1,18 @@
+---
+description: "Researcher: check the references of a manuscript or of a Sub-Sub report"
+argument-hint: "<path to .qmd or .md> [claims]"
+---
+Check the references of $1 with Starbuck.
+
+1. If the verify_ tools are not available, tell the user that reference checks need Starbuck: add "addons": ["starbuck"] to the Sub-Sub settings file and start Sub-Sub again. Then stop.
+2. Call verify_check_manuscript with path $1.
+3. Report the summary: how many references failed, need checking, have notes and passed.
+4. For each Fail and each Check, give the citation key, Starbuck's reason and its suggested action. Keep Starbuck's result; do not make it stronger or weaker.
+5. List the cited keys without a bibliography entry.
+6. Give the path of the HTML report.
+7. If the second argument is "claims", or the user asks whether the sources support the text:
+   1. Call verify_prepare_claims with path $1. Get all pages (offset, limit).
+   2. Judge each claim with status ready from its passages only: supported, partly_supported, not_supported or cannot_assess. Copy the passage you rely on character for character into quote.
+   3. Call verify_record_claims once, with the verdicts of all claims.
+   4. Report the claims that are not supported or only partly supported, with the line and the reason. Say for each whether the evidence was the full text or the abstract only.
+8. Do not change the manuscript. Offer fixes and wait for the user's answer.

package/roles/researcher.md

@@ -1,6 +1,6 @@
 You are Sub-Sub, the research assistant for {{user}}. {{about}} Reply briefly. No emojis.
 
-You read the Zotero library (zotero_ read tools), search PubMed and OpenAlex (scholar_ tools) and write notes in the notes folder. You cannot change the library, with one exception: scholar_attach_note adds a short child note (summary plus obsidian:// link). To add works, use scholar_queue_imports; {{user}} ticks them and the librarian (/librarian) imports them.
+You read the Zotero library (zotero_ read tools), search PubMed, Europe PMC and OpenAlex (scholar_ tools) and write notes in the notes folder. You cannot change the library, with one exception: scholar_attach_note adds a short child note (summary plus obsidian:// link). To add works, use scholar_queue_imports; {{user}} ticks them and the librarian (/librarian) imports them.
 
 ## Always
 
@@ -8,7 +8,13 @@ You read the Zotero library (zotero_ read tools), search PubMed and OpenAlex (sc
 - 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.
-- Prefer PubMed for clinical and physiology questions, OpenAlex for informatics, education and books.
+- 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.
+- Mark inferences: write "inference:" before a statement that combines sources and that no single source makes.
+- 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.
+- In reviews and comparisons, keep an evidence table with a number for each source that does not change ([1], [2]), and cite those numbers.
 - For scholar_attach_note and scholar_export_bibliography, Sub-Sub asks {{user}} before anything is written.
 
 ## Questions about the library
@@ -18,9 +24,10 @@ You read the Zotero library (zotero_ read tools), search PubMed and OpenAlex (sc
 ## Outside search and gaps
 
 1. If the question is vague, clarify it in one line.
-2. Search PubMed and/or OpenAlex. Report total hits and how many are already in the library.
-3. List the most relevant works not in the library, one line each on why it matters.
-4. Ask which to queue, then call scholar_queue_imports.
+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.
+5. Ask which to queue, then call scholar_queue_imports.
 
 ## Literature notes and syntheses
 
@@ -35,3 +42,9 @@ You read the Zotero library (zotero_ read tools), search PubMed and OpenAlex (sc
 1. scholar_check_manuscript on the file.
 2. Propose fixes for missing keys. Do not edit the manuscript text without approval.
 3. scholar_export_bibliography to the file named in the YAML header, or references.json next to the manuscript.
+
+## Reference checks (Starbuck, when the verify_ tools are available)
+
+- verify_check_manuscript checks that each cited work exists, matches its citation and was not retracted. Use it on {{user}}'s manuscripts and on your own reports before you deliver them.
+- Report Starbuck's results as Starbuck states them. Do not turn a Check into a Fail, or a Pass into "verified". Give the path of the report.
+- Claim support (level 4) only when {{user}} asks: verify_prepare_claims, then judge each claim from its passages only, then verify_record_claims with all verdicts. Quote the passage you rely on character for character. With an abstract only, answer cannot_assess for details an abstract would not report.

package/src/bench.ts

@@ -16,7 +16,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { expand, loadConfig, type Mode } from "./config.ts";
+import { expand, loadConfig, type Mode, starbuckCommand, starbuckEnabled } from "./config.ts";
 import { findUv } from "./subsub.ts";
 
 export const PACKAGE_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -28,7 +28,7 @@ export const DEFAULT_MODELS: Record<Mode, string[]> = {
 
 export const TASKS: Record<Mode, string[]> = {
 	librarian: ["tagging", "facet_fix", "import"],
-	researcher: ["lit_note", "synthesis", "search"],
+	researcher: ["lit_note", "synthesis", "search", "lit"],
 };
 
 export interface Tasks {
@@ -85,6 +85,12 @@ export function promptFor(task: string, t: Tasks, code: string, out: string): st
 				? `Write a synthesis of what my library says about ${about(t)}, following the synthesis format in the shared rules. ` +
 						`This is a model test: save it as ${join(out, "Synthesis.md")}.`
 				: undefined;
+		case "lit":
+			// The /lit template, with the model-test paths in its arguments.
+			return t.synthesis
+				? `/lit ${about(t)}. This is a model test: write the review as ${join(out, "Lit.md")}, the plan and the screening log ` +
+						`in ${join(out, ".plans")}, nothing in Research/, and do not queue imports.`
+				: undefined;
 		case "search":
 			return t.synthesis
 				? `Find up to 5 important papers published from ${t.search.year_from} onwards on ${about(t)} that are not yet in my library. ` +
@@ -300,7 +306,33 @@ export function citekeysIn(text: string): string[] {
 
 // ---------------------------------------------------------------- score one run
 
-export function scoreRun(task: string, dir: string, t: Tasks, index: IndexRow[], blindRef: Record<string, string[]>): Record<string, any> {
+/** Starbuck's verdicts on a file: runs `starbuck check` and reads its JSON report (undefined when it cannot run). */
+export type StarbuckScorer = (file: string) => Record<string, any> | undefined;
+
+export function starbuckScorer(cfg = loadConfig(), env: NodeJS.ProcessEnv = process.env): StarbuckScorer | undefined {
+	if (!starbuckEnabled(cfg)) return undefined;
+	const cmd = starbuckCommand(cfg, env);
+	return (file) => {
+		const claims = env.STARBUCK_JUDGE_URL && env.STARBUCK_JUDGE_MODEL ? ["--claims"] : [];
+		const args = [...cmd.args.slice(0, -1), "starbuck", "check", file, "--to", "", "--quiet", ...claims];
+		const r = spawnSync(cmd.command, args, { env, encoding: "utf8", timeout: 20 * 60_000 });
+		const report = join(dirname(file), "_starbuck", `${file.split(/[\\/]/).pop()!.replace(/\.[^.]+$/, "")}-references.json`);
+		if (!existsSync(report)) return { error: (r.stderr || r.error?.message || "no report").trim().slice(0, 300) };
+		const res = JSON.parse(readFileSync(report, "utf8"));
+		const run = res.claims_run ?? {};
+		return {
+			references: res.summary?.references_checked,
+			fail: res.summary?.fail,
+			check: res.summary?.warn,
+			uncited_sentences: res.summary?.uncited_sentences,
+			citation_recall: run.citation_recall?.value,
+			citation_precision: run.citation_precision?.value,
+		};
+	};
+}
+
+export function scoreRun(task: string, dir: string, t: Tasks, index: IndexRow[], blindRef: Record<string, string[]>,
+	starbuck?: StarbuckScorer): Record<string, any> {
 	const events = readEvents(dir);
 	const calls = toolCalls(events);
 	const entries = benchEntries(events);
@@ -410,6 +442,29 @@ export function scoreRun(task: string, dir: string, t: Tasks, index: IndexRow[],
 		}
 		return res;
 	}
+	if (task === "lit") {
+		const text = readFile("Lit.md") ?? "";
+		const seen = calls.map((c) => c.result).join("\n").toLowerCase();
+		const dois = [...new Set([...text.matchAll(DOI_RE)].map((m) => normDoi(m[0])))];
+		const pmids = [...new Set([...text.matchAll(PMID_RE)].map((m) => m[1]))];
+		const rows = text.split("\n").filter((l) => /^\|\s*\[?\d+\]?\s*\|/.test(l));
+		const readCol = rows.map((l) => l.split("|").map((c) => c.trim().toLowerCase())).map((c) => c.find((x) => /^(full text|abstract|metadata)$/.test(x)));
+		const plans = join(dir, ".plans");
+		return {
+			...base,
+			written: !!text,
+			words: text ? text.split(/\s+/).filter(Boolean).length : 0,
+			evidence_rows: rows.length,
+			evidence_labelled: readCol.filter(Boolean).length,
+			dois: dois.length,
+			pmids: pmids.length,
+			ungrounded: [...dois.filter((d) => !seen.includes(d)), ...pmids.filter((p) => !seen.includes(p))],
+			screening_log: existsSync(plans) && readdirSync(plans).some((f) => /screening/i.test(f)),
+			multi_searches: calls.filter((c) => c.name === "scholar_search_multi").length,
+			fulltext_reads: calls.filter((c) => c.name === "scholar_read_oa_fulltext" || c.name === "zotero_get_fulltext").length,
+			starbuck: text && starbuck ? starbuck(join(dir, "Lit.md")) : undefined,
+		};
+	}
 	if (task === "search") {
 		const text = readFile("Search.md") ?? "";
 		const seen = calls.map((c) => c.result).join("\n").toLowerCase();
@@ -453,6 +508,9 @@ export function renderResults(rows: Array<{ model: string; role: Mode; task: str
 		lit_note: ["written", "words", "read_fulltext", "cites_itself", "citekeys_unknown"],
 		synthesis: ["written", "words", "topic_items", "topic_items_cited", "citekeys_unknown"],
 		search: ["written", "dois", "pmids", "ungrounded", "already_in_library", "queued", "searches"],
+		lit: ["written", "words", "evidence_rows", "evidence_labelled", "dois", "pmids", "ungrounded", "screening_log",
+			"multi_searches", "fulltext_reads", "starbuck.fail", "starbuck.check", "starbuck.uncited_sentences",
+			"starbuck.citation_recall", "starbuck.citation_precision"],
 	};
 	const common = ["seconds", "tool_calls", "tool_errors", "wrong_mode", "tokens_in", "tokens_out", "cost", "error"];
 	for (const task of Object.keys(cols)) {
@@ -562,12 +620,13 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
 		const key: Record<string, string> = JSON.parse(readFileSync(join(dir, "key.json"), "utf8"));
 		const blind = existsSync(join(dir, "reference.json")) ? JSON.parse(readFileSync(join(dir, "reference.json"), "utf8")) : {};
 		const rows: Array<{ model: string; role: Mode; task: string; s: Record<string, any> }> = [];
+		const scorer = starbuckScorer(cfg);
 		for (const code of Object.keys(key).sort()) {
 			for (const role of ["librarian", "researcher"] as Mode[])
 				for (const task of TASKS[role]) {
 					const d = join(dir, "runs", code, task);
 					if (!existsSync(join(d, "summary.json"))) continue;
-					rows.push({ model: key[code], role, task, s: scoreRun(task, d, t, index, blind) });
+					rows.push({ model: key[code], role, task, s: scoreRun(task, d, t, index, blind, scorer) });
 				}
 		}
 		writeFileSync(join(dir, "results.json"), JSON.stringify(rows, null, 1));

package/src/config.ts

@@ -12,6 +12,11 @@
  *
  * `subsub init` writes this file. Without "serverDir" (or when that folder does
  * not exist), the Zotero servers run from PyPI with uv.
+ *
+ * Add-ons: "addons": ["starbuck"] starts Starbuck (reference checks) as a third
+ * server, "verify". It runs from "starbuckDir" when that folder has a
+ * pyproject.toml, otherwise from the pinned PyPI release (STARBUCK_SOURCE).
+ * `subsub init` and the web view turn it on and off.
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -23,7 +28,11 @@ export type Profile = "reader" | "scholar" | "author" | "editor";
 export const PROFILES: Profile[] = ["reader", "scholar", "author", "editor"];
 
 /** The Zotero server release that this Sub-Sub version runs when there is no local server folder. */
-export const SERVER_VERSION = "0.4.1";
+export const SERVER_VERSION = "0.5.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}`;
 
 export interface SubsubConfig {
 	/** The settings file (written by `subsub init` and `/profile`). */
@@ -57,10 +66,15 @@ export interface SubsubConfig {
 	quotes?: boolean;
 	/** Theme per mode, without -dark/-light; false keeps your pi theme. */
 	themes?: Partial<Record<Mode, string>> | false;
+	/** Optional servers to start, e.g. ["starbuck"]. */
+	addons?: string[];
+	/** Local Starbuck folder (used when it has a pyproject.toml). */
+	starbuckDir?: string;
 }
 
-export function expand(p: string): string {
-	return resolve(p.replace(/^~(?=$|\/)/, homedir()));
+export function expand(p: string, home?: string): string {
+	const base = home ?? process.env.HOME ?? homedir();
+	return resolve(p.replace(/^~(?=$|\/)/, base));
 }
 
 export function parseEnvFile(path: string): Record<string, string> {
@@ -81,7 +95,7 @@ export function parseEnvFile(path: string): Record<string, string> {
 }
 
 export function configPath(env: NodeJS.ProcessEnv = process.env): string {
-	return expand(env.SUBSUB_CONFIG ?? "~/.config/subsub/config.json");
+	return expand(env.SUBSUB_CONFIG ?? "~/.config/subsub/config.json", env.HOME);
 }
 
 export function readConfigFile(file: string): Record<string, unknown> {
@@ -108,6 +122,7 @@ export function isProfile(x: unknown): x is Profile {
 }
 
 export function loadConfig(env: NodeJS.ProcessEnv = process.env): SubsubConfig {
+	const home = env.HOME;
 	const file = configPath(env);
 	let user: Partial<SubsubConfig> = {};
 	if (existsSync(file)) {
@@ -117,16 +132,18 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): SubsubConfig {
 			throw new Error(`Sub-Sub: cannot read ${file}: ${(err as Error).message}`);
 		}
 	}
-	const envCandidates = [
-		user.envFile,
-		env.ZOTERO_MCP_ENV,
-		"~/.config/zotero-local-mcp/env",
-		"~/.config/opencode/zotero.env",
-	].filter((x): x is string => Boolean(x));
-	const envFile = envCandidates.map(expand).find((p) => existsSync(p));
-	const envValues = envFile ? parseEnvFile(envFile) : {};
+	const explicitEnv = user.envFile ?? env.ZOTERO_MCP_ENV;
+	const envFile = explicitEnv
+		? expand(explicitEnv, home)
+		: [
+				"~/.config/zotero-local-mcp/env",
+				"~/.config/opencode/zotero.env",
+		  ]
+				.map((p) => expand(p, home))
+				.find((p) => existsSync(p));
+	const envValues = envFile && existsSync(envFile) ? parseEnvFile(envFile) : {};
 	const vaultRaw = user.vault ?? env.ZOTERO_VAULT ?? envValues.ZOTERO_VAULT;
-	const vault = vaultRaw ? expand(vaultRaw) : undefined;
+	const vault = vaultRaw ? expand(vaultRaw, home) : undefined;
 	const mode = user.defaultMode === "librarian" ? "librarian" : "researcher";
 	return {
 		configFile: file,
@@ -135,7 +152,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): SubsubConfig {
 		about: typeof user.about === "string" && user.about.trim() ? user.about.trim() : undefined,
 		language: typeof user.language === "string" && user.language.trim() ? user.language.trim() : "English",
 		setup: user.setup,
-		serverDir: expand(user.serverDir ?? "~/Projects/zotero-local-mcp"),
+		serverDir: expand(user.serverDir ?? "~/Projects/zotero-local-mcp", home),
 		envFile,
 		vault,
 		models: user.models ?? {
@@ -143,27 +160,30 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): SubsubConfig {
 			researcher: "opencode-go/mimo-v2.6-pro",
 		},
 		defaultMode: mode,
-		vaultContext: (user.vaultContext ?? (vault ? [join(vault, ".claude", "CLAUDE.md")] : [])).map(expand),
+		vaultContext: (user.vaultContext ?? (vault ? [join(vault, ".claude", "CLAUDE.md")] : [])).map((p) => expand(p, home)),
 		sharedRules: user.sharedRules
-			? expand(user.sharedRules)
+			? expand(user.sharedRules, home)
 			: vault
 				? join(vault, "Systems", "Zotero agent.md")
 				: undefined,
 		startTimeout: user.startTimeout ?? 45,
-		uvPath: user.uvPath ? expand(user.uvPath) : undefined,
+		uvPath: user.uvPath ? expand(user.uvPath, home) : undefined,
 		look: user.look,
 		quotes: user.quotes,
 		themes: user.themes,
+		addons: Array.isArray(user.addons) ? user.addons.filter((a): a is string => typeof a === "string") : [],
+		starbuckDir: expand(user.starbuckDir ?? "~/Projects/starbuck", home),
 	};
 }
 
 /** uv is often missing from PATH when pi is started outside a login shell. */
 export function findUv(cfg: Pick<SubsubConfig, "uvPath">, env: NodeJS.ProcessEnv = process.env, platform: string = process.platform): string {
+	const home = env.HOME;
 	const unix = ["~/.local/bin/uv", "/opt/homebrew/bin/uv", "/usr/local/bin/uv", "~/.cargo/bin/uv"];
 	const windows = ["~/.local/bin/uv.exe", "~/.cargo/bin/uv.exe", env.LOCALAPPDATA ? join(env.LOCALAPPDATA, "uv", "uv.exe") : ""];
 	const candidates = [cfg.uvPath, env.SUBSUB_UV, ...(platform === "win32" ? windows : unix)]
 		.filter((x): x is string => Boolean(x))
-		.map(expand);
+		.map((p) => expand(p, home));
 	return candidates.find((p) => existsSync(p)) ?? "uv";
 }
 
@@ -185,6 +205,29 @@ export function serverCommand(
 	return { command: uv, args: ["tool", "run", "--quiet", "--from", `zotero-local-mcp==${SERVER_VERSION}`, program, ...args] };
 }
 
+export function starbuckEnabled(cfg: Pick<SubsubConfig, "addons">): boolean {
+	return (cfg.addons ?? []).includes("starbuck");
+}
+
+/** How to start Starbuck's MCP server: from the local folder when it exists, otherwise the pinned release. */
+export function starbuckCommand(
+	cfg: Pick<SubsubConfig, "starbuckDir" | "uvPath">,
+	env: NodeJS.ProcessEnv = process.env,
+): { command: string; args: string[] } {
+	const uv = findUv(cfg, env);
+	if (cfg.starbuckDir && existsSync(join(cfg.starbuckDir, "pyproject.toml"))) {
+		return { command: uv, args: ["run", "--quiet", "--directory", cfg.starbuckDir, "starbuck-mcp"] };
+	}
+	return { command: uv, args: ["tool", "run", "--quiet", "--from", STARBUCK_SOURCE, "starbuck-mcp"] };
+}
+
+/** The addons setting with Starbuck turned on or off; other add-ons stay. Undefined (no setting) when empty. */
+export function withStarbuck(addons: string[] | undefined, on: boolean): string[] | undefined {
+	const rest = (addons ?? []).filter((a) => a !== "starbuck");
+	const out = on ? [...rest, "starbuck"] : rest;
+	return out.length ? out : undefined;
+}
+
 /** How prompts name the user. */
 export function who(cfg: Pick<SubsubConfig, "userName">): string {
 	return cfg.userName ?? "the user";