@tiagojct/subsub 0.6.1 → 0.7.0

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,6 +66,10 @@ 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, home?: string): string {
@@ -158,6 +171,8 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): SubsubConfig {
 		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),
 	};
 }
 
@@ -190,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";

package/src/doctor.ts

@@ -3,14 +3,24 @@
  *
  * Checks Node, the settings file, uv, the Zotero server (it runs
  * `zotero-local-mcp --check`), Zotero itself, the tag list, the notes folder,
- * the contact email and the model login. Exit code 1 when something needs a fix.
+ * the contact email, Starbuck (when the add-on is on) and the model login. Exit
+ * code 1 when something needs a fix.
  */
 
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { findUv, loadConfig, SERVER_VERSION, serverCommand, type SubsubConfig } from "./config.ts";
+import {
+	findUv,
+	loadConfig,
+	SERVER_VERSION,
+	serverCommand,
+	STARBUCK_SOURCE,
+	starbuckCommand,
+	starbuckEnabled,
+	type SubsubConfig,
+} from "./config.ts";
 import { profileSpec } from "./profiles.ts";
 
 export interface Check {
@@ -137,6 +147,7 @@ export function runChecks(
 			? { name: "Contact email", ok: true, detail: "set" }
 			: { name: "Contact email", ok: true, warn: true, detail: "not set: open-access PDFs cannot be found", fix: "Type subsub init and give an email address." },
 	);
+	if (starbuckEnabled(cfg)) out.push(starbuckCheck(cfg, env, run));
 	const agentDir = deps.agentDir ?? (env.SUBSUB_AGENT_DIR ? env.SUBSUB_AGENT_DIR : join(homedir(), ".subsub", "agent"));
 	out.push(
 		hasLogin(agentDir)
@@ -146,6 +157,25 @@ export function runChecks(
 	return out;
 }
 
+/** The Starbuck add-on: can uv start it? (`starbuck --version`, from the local folder or the pinned release) */
+export function starbuckCheck(cfg: SubsubConfig, env: NodeJS.ProcessEnv, run: Runner): Check {
+	const cmd = starbuckCommand(cfg, env);
+	const local = cmd.args.includes("--directory");
+	const args = cmd.args.slice(0, -1).concat(["starbuck", "--version"]);
+	const res = run(cmd.command, args, env);
+	if (res.status === 0) {
+		return { name: "Starbuck", ok: true, detail: `${res.stdout.trim()} ${local ? `from ${cfg.starbuckDir}` : `from ${STARBUCK_SOURCE}`}` };
+	}
+	return {
+		name: "Starbuck",
+		ok: false,
+		detail: local ? `cannot start from ${cfg.starbuckDir}` : `cannot install ${STARBUCK_SOURCE} with uv`,
+		fix: local
+			? `Type: cd "${cfg.starbuckDir}" && uv sync`
+			: "Check the internet connection and run subsub doctor again. To turn reference checks off, type subsub init.",
+	};
+}
+
 export function formatChecks(checks: Check[]): string {
 	return checks
 		.map((c) => {

package/src/init.ts

@@ -12,7 +12,8 @@
  *
  * Flags (for scripts and tests): --yes (take every default), --setup
  * standard|fmup, --name, --about, --language, --notes, --profile, --tags
- * health-sciences|health-informatics|any-field, --email, --models keep|later|opencode-go.
+ * health-sciences|health-informatics|any-field, --email, --starbuck on|off,
+ * --models keep|later|opencode-go.
  */
 
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -20,7 +21,20 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
-import { configPath, expand, isProfile, loadConfig, parseEnvFile, PROFILES, readConfigFile, saveConfig } from "./config.ts";
+import {
+	configPath,
+	expand,
+	isProfile,
+	loadConfig,
+	parseEnvFile,
+	PROFILES,
+	readConfigFile,
+	saveConfig,
+	starbuckEnabled,
+	type SubsubConfig,
+	withStarbuck,
+} from "./config.ts";
+import { defaultRunner, starbuckCheck } from "./doctor.ts";
 import { PROFILE_SPECS } from "./profiles.ts";
 
 const TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates");
@@ -83,7 +97,7 @@ export async function runInit(
 	io: InitIO,
 	flags: Record<string, string>,
 	env: NodeJS.ProcessEnv = process.env,
-	deps: { fetch?: typeof fetch; home?: string } = {},
+	deps: { fetch?: typeof fetch; home?: string; prepareStarbuck?: (cfg: SubsubConfig) => string } = {},
 ): Promise<InitResult> {
 	const home = deps.home ?? env.HOME ?? homedir();
 	const initEnv: NodeJS.ProcessEnv = { ...env, HOME: home };
@@ -133,6 +147,14 @@ export async function runInit(
 	const email = (
 		await io.ask("Email for Unpaywall and Crossref, to find open-access PDFs (optional)", flags.email ?? envValues.ZOTERO_CONTACT_EMAIL ?? "")
 	).trim();
+	const starbuck = await io.choose(
+		"Reference checks (Starbuck): check that cited works exist, match their citation and were not retracted",
+		[
+			{ value: "off", label: "Off" },
+			{ value: "on", label: "On (the researcher gets /verify; uses the email above)" },
+		],
+		flags.starbuck ?? (starbuckEnabled(current) ? "on" : "off"),
+	);
 	const modelOptions = [
 		...(existing.models ? [{ value: "keep", label: `Keep: ${JSON.stringify(existing.models)}` }] : []),
 		{ value: "later", label: "Choose later in Sub-Sub (/login, then /model)" },
@@ -171,12 +193,14 @@ export async function runInit(
 		setup: fmup ? "fmup" : undefined,
 		vault: notes,
 		envFile,
+		addons: withStarbuck(current.addons, starbuck === "on"),
 	};
 	if (models === "later") patch.models = {};
 	if (models === "opencode-go") patch.models = TESTED_MODELS;
 	saveConfig(patch, initEnv);
 
 	const zotero = await zoteroReachable(deps.fetch);
+	const starbuckNote = starbuck === "on" && deps.prepareStarbuck ? deps.prepareStarbuck(loadConfig(initEnv)) : "";
 	io.say("");
 	io.say(`Saved: ${configFile}`);
 	io.say(`Saved: ${envFile}`);
@@ -186,6 +210,7 @@ export async function runInit(
 			? "Zotero: reachable."
 			: "Zotero: not reachable. Start Zotero 10, then in Zotero open Settings > Advanced and turn on \"Allow other applications on this computer to communicate with Zotero\".",
 	);
+	if (starbuck === "on") io.say(starbuckNote || "Reference checks: on. The first start downloads Starbuck.");
 	if (fmup) io.say("FMUP / U.Porto: the FMUP model service will come in a later version. Until then, connect a model provider yourself.");
 	io.say("Next: type subsub web to open Sub-Sub in your browser (or subsub for the terminal). Connect a model provider with the model button (or /login in the terminal). To check the setup, type subsub doctor.");
 	return { configFile, envFile, notes, created, zotero };
@@ -243,7 +268,11 @@ export async function initMain(args: string[], env: NodeJS.ProcessEnv = process.
 	const flags = parseFlags(args);
 	const io = flags.yes || !process.stdin.isTTY ? defaultsIO((l) => console.log(l)) : terminalIO();
 	try {
-		await runInit(io, flags, env);
+		await runInit(io, flags, env, { prepareStarbuck: (cfg) => {
+			// Download Starbuck now, so that the first start of Sub-Sub does not wait for it.
+			const c = starbuckCheck(cfg, env, defaultRunner);
+			return c.ok ? `Reference checks: on (${c.detail}).` : `Reference checks: on, but ${c.detail}. ${c.fix ?? ""}`.trim();
+		} });
 		return 0;
 	} catch (err) {
 		console.error(`Sub-Sub init: ${(err as Error).message}`);

package/src/notes.ts

@@ -0,0 +1,46 @@
+/**
+ * Checks on the literature notes the researcher writes (a note whose front matter has a
+ * citekey). Each note must say what it was written from (evidence: full text, abstract
+ * or metadata), and only a note written from the full text may give page numbers.
+ * The write gate calls these before a write or edit runs; a failed check blocks the call
+ * with a reason, so the model corrects the note.
+ */
+
+export const EVIDENCE = ["full text", "abstract", "metadata"] as const;
+
+const FRONT = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+const PAGES = /\b(?:pp?\.|pages?)\s?\d+/i;
+
+export function frontMatter(text: string): string | undefined {
+	return FRONT.exec(text)?.[1];
+}
+
+export function field(front: string, name: string): string | undefined {
+	const m = new RegExp(`^${name}:[ \\t]*(.*)$`, "m").exec(front);
+	return m ? m[1].trim().replace(/^["']|["']$/g, "").trim() : undefined;
+}
+
+/** Why a new literature note cannot be written as it is, or undefined when it can. */
+export function checkLiteratureNote(text: string): string | undefined {
+	const m = FRONT.exec(text);
+	if (!m || !field(m[1], "citekey")) return undefined;
+	const evidence = field(m[1], "evidence")?.toLowerCase();
+	if (!evidence || !(EVIDENCE as readonly string[]).includes(evidence)) {
+		return 'A literature note needs "evidence:" in its front matter, with one of: full text, abstract, metadata (what you read to write it). Add it and write the note again.';
+	}
+	const body = text.slice(m[0].length);
+	if (evidence !== "full text" && PAGES.test(body)) {
+		return `This note says evidence: ${evidence}, but it gives page numbers. Page numbers come only from the full text: remove them, or read the full text and set evidence: full text.`;
+	}
+	return undefined;
+}
+
+/** The text of a file after pi's edit tool applies edits[] (each oldText matched against the original). */
+export function applyEdits(current: string, edits: Array<{ oldText?: unknown; newText?: unknown }>): string {
+	let out = current;
+	for (const e of edits) {
+		const oldText = String(e.oldText ?? "");
+		if (oldText && out.includes(oldText)) out = out.replace(oldText, () => String(e.newText ?? ""));
+	}
+	return out;
+}

package/src/profiles.ts

@@ -19,6 +19,8 @@ export interface ProfileSpec {
 	summary: string;
 	/** Tools this profile does not offer (full names). */
 	without: string[];
+	/** Prompt commands this profile does not run (names without the slash). */
+	withoutPrompts: string[];
 	/** Items per review note and per batch. */
 	batch: number;
 	/** Added to the system prompt. {{user}} is the user's name or "the user". */
@@ -36,6 +38,7 @@ export const PROFILE_SPECS: Record<Profile, ProfileSpec> = {
 		label: "Reader",
 		summary: "explains each step; reading notes are quotes and questions; no summaries; no bulk library changes",
 		without: [...BULK_LIBRARY, ...MANUSCRIPT],
+		withoutPrompts: ["lit", "compare", "review", "digest"],
 		batch: 10,
 		rules: [
 			"Profile: Reader. {{User}} is learning to work with the literature and wants to do the reading and the writing.",
@@ -51,6 +54,7 @@ export const PROFILE_SPECS: Record<Profile, ProfileSpec> = {
 		label: "Scholar",
 		summary: "literature notes, syntheses, searches and alerts; the full librarian",
 		without: MANUSCRIPT,
+		withoutPrompts: ["review"],
 		batch: 25,
 		rules: [
 			"Profile: Scholar.",
@@ -64,6 +68,7 @@ export const PROFILE_SPECS: Record<Profile, ProfileSpec> = {
 		label: "Author",
 		summary: "Scholar plus manuscripts: citation check, bibliography, comments on the argument",
 		without: [],
+		withoutPrompts: [],
 		batch: 25,
 		rules: [
 			"Profile: Author.",
@@ -78,6 +83,7 @@ export const PROFILE_SPECS: Record<Profile, ProfileSpec> = {
 		label: "Editor",
 		summary: "everything, including drafting manuscript text on request",
 		without: [],
+		withoutPrompts: [],
 		batch: 25,
 		rules: [
 			"Profile: Editor. All tools.",
@@ -92,6 +98,17 @@ export function profileSpec(p: Profile): ProfileSpec {
 	return PROFILE_SPECS[p];
 }
 
+/** Why a prompt command does not run in this profile, or undefined when it does. */
+export function promptBlocked(text: string, profile: Profile): string | undefined {
+	const m = /^\/([\w-]+)(?:\s|$)/.exec(text.trim());
+	if (!m || !PROFILE_SPECS[profile].withoutPrompts.includes(m[1])) return undefined;
+	const allowed = Object.values(PROFILE_SPECS)
+		.filter((s) => !s.withoutPrompts.includes(m[1]))
+		.map((s) => s.label)
+		.join(", ");
+	return `/${m[1]} is not part of the ${PROFILE_SPECS[profile].label} profile (it is in: ${allowed}). Change the profile with /profile.`;
+}
+
 export function profileList(current?: Profile): string {
 	return Object.values(PROFILE_SPECS)
 		.map((s) => `${s.name === current ? "*" : " "} ${s.label.padEnd(8)} ${s.summary}`)

package/src/prompt.ts

@@ -74,6 +74,12 @@ export function systemAddition(mode: Mode, cfg: SubsubConfig, cwd: string): stri
 			if (t) parts.push(`# Vault conventions (${f})`, t);
 		}
 	}
+	if (cfg.setup === "fmup") {
+		parts.push(
+			"# U.Porto",
+			`${capital(user)} works at the University of Porto. Papers that are not open access often open through the university's subscriptions when ${user} uses Sub-Sub on the U.Porto network: say so when a work is not open access.`,
+		);
+	}
 	// The profile and the language rule come last, so they win over the shared rules and the vault conventions.
 	parts.push("# Profile", fill(profileSpec(cfg.profile).rules, cfg));
 	parts.push("# Language", languageRule(cfg.language, user));

package/src/roles.ts

@@ -7,6 +7,9 @@ import { profileSpec } from "./profiles.ts";
 
 export const FILE_TOOLS = ["read", "edit", "write", "grep", "find", "ls"];
 
+/** Prefixes of the tools that Sub-Sub's servers provide (the gate checks the mode for these). */
+export const SERVER_PREFIXES = ["zotero_", "scholar_", "verify_"];
+
 export const ZOTERO_READ = [
 	"status",
 	"library_overview",
@@ -51,7 +54,11 @@ export function toolsFor(mode: Mode, registered: string[], profile: Profile = "e
 	const wanted =
 		mode === "librarian"
 			? [...registered.filter((n) => n.startsWith("zotero_")), ...FILE_TOOLS]
-			: [...ZOTERO_READ, ...registered.filter((n) => n.startsWith("scholar_")), ...FILE_TOOLS];
+			: [
+					...ZOTERO_READ,
+					...registered.filter((n) => n.startsWith("scholar_") || n.startsWith("verify_")),
+					...FILE_TOOLS,
+				];
 	return [...new Set(wanted)].filter((n) => has.has(n) && !without.has(n));
 }