@tiagojct/subsub 0.6.1 → 0.7.0

package/dist/init.js

@@ -12,14 +12,16 @@
  *
  * 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";
 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.js";
+import { configPath, expand, isProfile, loadConfig, parseEnvFile, PROFILES, readConfigFile, saveConfig, starbuckEnabled, withStarbuck, } from "./config.js";
+import { defaultRunner, starbuckCheck } from "./doctor.js";
 import { PROFILE_SPECS } from "./profiles.js";
 const TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates");
 export const STARTER_TAGS = {
@@ -92,6 +94,10 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         tags = await io.choose("Starter tag list (edit it later in the notes folder)", Object.entries(STARTER_TAGS).map(([value, label]) => ({ value, label })), flags.tags ?? (fmup ? "health-sciences" : "any-field"));
     }
     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)" },
@@ -128,6 +134,7 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         setup: fmup ? "fmup" : undefined,
         vault: notes,
         envFile,
+        addons: withStarbuck(current.addons, starbuck === "on"),
     };
     if (models === "later")
         patch.models = {};
@@ -135,6 +142,7 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         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}`);
@@ -143,6 +151,8 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
     io.say(zotero
         ? "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.");
@@ -203,7 +213,11 @@ export async function initMain(args, env = process.env) {
     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) {

package/dist/notes.js

@@ -0,0 +1,42 @@
+/**
+ * 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"];
+const FRONT = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+const PAGES = /\b(?:pp?\.|pages?)\s?\d+/i;
+export function frontMatter(text) {
+    return FRONT.exec(text)?.[1];
+}
+export function field(front, name) {
+    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) {
+    const m = FRONT.exec(text);
+    if (!m || !field(m[1], "citekey"))
+        return undefined;
+    const evidence = field(m[1], "evidence")?.toLowerCase();
+    if (!evidence || !EVIDENCE.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, edits) {
+    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/dist/profiles.js

@@ -18,6 +18,7 @@ export const PROFILE_SPECS = {
         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.",
@@ -33,6 +34,7 @@ export const PROFILE_SPECS = {
         label: "Scholar",
         summary: "literature notes, syntheses, searches and alerts; the full librarian",
         without: MANUSCRIPT,
+        withoutPrompts: ["review"],
         batch: 25,
         rules: [
             "Profile: Scholar.",
@@ -46,6 +48,7 @@ export const PROFILE_SPECS = {
         label: "Author",
         summary: "Scholar plus manuscripts: citation check, bibliography, comments on the argument",
         without: [],
+        withoutPrompts: [],
         batch: 25,
         rules: [
             "Profile: Author.",
@@ -60,6 +63,7 @@ export const PROFILE_SPECS = {
         label: "Editor",
         summary: "everything, including drafting manuscript text on request",
         without: [],
+        withoutPrompts: [],
         batch: 25,
         rules: [
             "Profile: Editor. All tools.",
@@ -72,6 +76,17 @@ export const PROFILE_SPECS = {
 export function profileSpec(p) {
     return PROFILE_SPECS[p];
 }
+/** Why a prompt command does not run in this profile, or undefined when it does. */
+export function promptBlocked(text, profile) {
+    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) {
     return Object.values(PROFILE_SPECS)
         .map((s) => `${s.name === current ? "*" : " "} ${s.label.padEnd(8)} ${s.summary}`)

package/dist/prompt.js

@@ -65,6 +65,9 @@ export function systemAddition(mode, cfg, cwd) {
                 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/dist/roles.js

@@ -3,6 +3,8 @@
  */
 import { profileSpec } from "./profiles.js";
 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",
@@ -43,7 +45,11 @@ export function toolsFor(mode, registered, profile = "editor") {
     const without = new Set(profileSpec(profile).without);
     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));
 }
 /** Why a Sub-Sub tool is not available now, or undefined when it is. */

package/dist/subsub.js

@@ -8,22 +8,25 @@
  * - Profiles (reader, scholar, author, editor) set what Sub-Sub writes and which
  *   tools it offers; /profile changes it.
  * - Commands: /librarian, /researcher, /profile, /subsub, /history, /undo.
+ * - Add-on: with "addons": ["starbuck"], Starbuck runs as a third server
+ *   ("verify") for reference checks; its tools belong to researcher mode.
  *
  * The Python servers start in session_start (not in the factory) and stop in
  * session_shutdown. Tools are registered once and use the current bridge.
  */
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Bridge } from "./bridge.js";
-import { expand, findUv, isProfile, loadConfig, saveConfig, serverCommand, who } from "./config.js";
-import { profileList, profileSpec } from "./profiles.js";
+import { expand, findUv, isProfile, loadConfig, parseEnvFile, saveConfig, serverCommand, starbuckCommand, starbuckEnabled, who, } from "./config.js";
+import { profileList, profileSpec, promptBlocked } from "./profiles.js";
 import { coerceArgs, loosenArrays } from "./args.js";
+import { applyEdits, checkLiteratureNote } from "./notes.js";
 import { buildPolicy, judgePath, normalizeToolPath, realish, within } from "./paths.js";
 import { describeArgs, formatPreview } from "./preview.js";
 import { headerLines, paintPreview, QUOTES, schemeFromAnsi, themeName } from "./look.js";
 import { systemAddition } from "./prompt.js";
-import { gateKind, toolsFor, unavailableReason } from "./roles.js";
+import { gateKind, SERVER_PREFIXES, toolsFor, unavailableReason } from "./roles.js";
 const PACKAGE_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
 const MODE_ENTRY = "subsub-mode";
 const BENCH_ENTRY = "subsub-bench";
@@ -36,12 +39,32 @@ function ownVersion() {
     }
 }
 export { findUv };
-export function serverSpecs(cfg) {
+export function serverSpecs(cfg, processEnv = process.env) {
     const env = cfg.envFile ? { ZOTERO_MCP_ENV: cfg.envFile } : {};
-    return [
-        { name: "zotero", ...serverCommand(cfg, "zotero-local-mcp"), env },
-        { name: "scholar", ...serverCommand(cfg, "zotero-scholar-mcp"), env },
+    const specs = [
+        { name: "zotero", ...serverCommand(cfg, "zotero-local-mcp", [], processEnv), env },
+        { name: "scholar", ...serverCommand(cfg, "zotero-scholar-mcp", [], processEnv), env },
     ];
+    if (starbuckEnabled(cfg))
+        specs.push({ name: "verify", ...starbuckCommand(cfg, processEnv), env: starbuckEnv(cfg, processEnv) });
+    return specs;
+}
+/**
+ * Starbuck reads its contact address and API keys from the environment. Sub-Sub keeps
+ * them in the zotero-local-mcp env file, so they are passed on (the environment wins).
+ */
+export function starbuckEnv(cfg, processEnv = process.env) {
+    const file = cfg.envFile ? parseEnvFile(cfg.envFile) : {};
+    const out = {};
+    const email = processEnv.STARBUCK_EMAIL || file.STARBUCK_EMAIL || processEnv.ZOTERO_CONTACT_EMAIL || file.ZOTERO_CONTACT_EMAIL;
+    if (email)
+        out.STARBUCK_EMAIL = email;
+    for (const key of ["NCBI_API_KEY", "OPENALEX_API_KEY"]) {
+        const v = processEnv[key] || file[key];
+        if (v)
+            out[key] = v;
+    }
+    return out;
 }
 export async function createSubsub(pi, deps = {}) {
     const cfg = deps.config ?? loadConfig();
@@ -111,6 +134,7 @@ export async function createSubsub(pi, deps = {}) {
             language: cfg.language,
             userName: cfg.userName ?? null,
             vault: cfg.vault ?? null,
+            starbuck: starbuckEnabled(cfg),
         };
         try {
             ctx.ui.setStatus("subsub.web", JSON.stringify(state));
@@ -245,6 +269,15 @@ export async function createSubsub(pi, deps = {}) {
         await b?.close();
     });
     pi.on("model_select", async (_event, ctx) => status(ctx));
+    // Prompt commands that the profile does not run (/lit for Reader, /review for Reader and Scholar).
+    // The input event comes before pi expands a prompt template.
+    pi.on("input", async (event, ctx) => {
+        const why = promptBlocked(event.text, profile);
+        if (!why)
+            return { action: "continue" };
+        ctx.ui.notify(`Sub-Sub: ${why}`, "warning");
+        return { action: "handled" };
+    });
     pi.on("before_agent_start", async (event, ctx) => ({
         systemPrompt: `${event.systemPrompt}\n\n${systemAddition(mode, { ...cfg, profile }, ctx.cwd)}`,
     }));
@@ -258,7 +291,7 @@ export async function createSubsub(pi, deps = {}) {
         const schema = schemas.get(name);
         if (schema)
             coerceArgs(schema, input);
-        if (name.startsWith("zotero_") || name.startsWith("scholar_")) {
+        if (SERVER_PREFIXES.some((p) => name.startsWith(p))) {
             const why = unavailableReason(name, mode, registered(), profile);
             if (why) {
                 if (benchOut)
@@ -266,6 +299,8 @@ export async function createSubsub(pi, deps = {}) {
                 return { block: true, reason: why };
             }
         }
+        if (name.startsWith("verify_"))
+            return verifyGate(name, input, ctx);
         const kind = benchOut && name === "scholar_queue_imports" ? "confirm" : gateKind(name, input);
         if (!kind)
             return undefined;
@@ -273,6 +308,9 @@ export async function createSubsub(pi, deps = {}) {
             return benchGate(name, input, kind, ctx.cwd, ctx.signal);
         if (kind === "path") {
             const target = normalizeToolPath(String(input.path ?? ""), ctx.cwd);
+            const noteProblem = literatureNoteProblem(name, target, input);
+            if (noteProblem)
+                return { block: true, reason: noteProblem };
             const verdict = judgePath(target, buildPolicy({ vault: cfg.vault, cwd: ctx.cwd, serverDir: cfg.serverDir, packageDir: PACKAGE_DIR }));
             if (verdict.ok)
                 return undefined;
@@ -303,9 +341,56 @@ export async function createSubsub(pi, deps = {}) {
         const ok = await ctx.ui.confirm(`Sub-Sub: apply ${name.replace(/^(zotero|scholar)_/, "")}?`, paintFor(ctx)(formatPreview(name, preview.data ?? preview.text)));
         return ok ? undefined : { block: true, reason: `${user} did not approve this change. Ask what to change; do not retry the same call.` };
     });
+    /** A literature note (front matter with a citekey) must state its evidence; see notes.ts. */
+    function literatureNoteProblem(name, target, input) {
+        if (!target.toLowerCase().endsWith(".md"))
+            return undefined;
+        if (name === "write")
+            return checkLiteratureNote(String(input.content ?? ""));
+        if (name === "edit" && Array.isArray(input.edits) && existsSync(target)) {
+            const current = readFileSync(target, "utf8");
+            return checkLiteratureNote(applyEdits(current, input.edits));
+        }
+        return undefined;
+    }
+    /**
+     * Starbuck writes its reports into a folder: report_dir, or _starbuck next to the
+     * manuscript. Inside the vault or the working folder that needs no approval; elsewhere
+     * Sub-Sub asks, as for any file write. record_claims gets the current model's name.
+     */
+    async function verifyGate(name, input, ctx) {
+        if (name === "verify_record_claims") {
+            input.judged_by = ctx.model ? [ctx.model.provider, ctx.model.id].filter(Boolean).join("/") : "the agent's model";
+        }
+        if (name === "verify_check_references")
+            return undefined;
+        const dir = input.report_dir
+            ? normalizeToolPath(String(input.report_dir), ctx.cwd)
+            : input.path
+                ? join(dirname(normalizeToolPath(String(input.path), ctx.cwd)), "_starbuck")
+                : undefined;
+        if (!dir)
+            return undefined;
+        const verdict = judgePath(dir, buildPolicy({ vault: cfg.vault, cwd: ctx.cwd, serverDir: cfg.serverDir, packageDir: PACKAGE_DIR }));
+        if (verdict.ok)
+            return undefined;
+        if (benchOut) {
+            record({ kind: "path_blocked", tool: name, path: dir });
+            return { block: true, reason: `Model test: Starbuck reports only inside the vault or ${benchOut}.` };
+        }
+        if (!ctx.hasUI)
+            return { block: true, reason: `Writing a Starbuck report to ${dir} needs ${user}'s approval: ${verdict.why}.` };
+        const ok = await ctx.ui.confirm(`Sub-Sub: write the Starbuck report to ${dir}?`, `Asking because ${verdict.why}.`);
+        return ok ? undefined : { block: true, reason: `${user} did not allow writing the report there. Ask where to put it (report_dir).` };
+    }
     async function benchGate(name, input, kind, cwd, signal) {
         if (kind === "path") {
             const target = normalizeToolPath(String(input.path ?? ""), cwd);
+            const noteProblem = literatureNoteProblem(name, target, input);
+            if (noteProblem) {
+                record({ kind: "note_blocked", tool: name, path: target, reason: noteProblem });
+                return { block: true, reason: noteProblem };
+            }
             if (within(target, realish(benchOut)))
                 return undefined;
             record({ kind: "path_blocked", tool: name, path: target });

package/dist/web.js

@@ -21,9 +21,9 @@ import { homedir } from "node:os";
 import { extname, join, normalize, resolve, sep } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { agentDirFor, chooseCwd, PACKAGE_DIR, packageVersion } from "./cli.js";
-import { expand, loadConfig, saveConfig } from "./config.js";
+import { expand, loadConfig, saveConfig, withStarbuck } from "./config.js";
 import { TESTED_MODELS } from "./init.js";
-import { within } from "./paths.js";
+import { realish, within } from "./paths.js";
 export function parseWebArgs(args) {
     const o = { port: 0, open: true, librarian: false, here: false, idleMinutes: 10, piArgs: [] };
     for (let i = 0; i < args.length; i++) {
@@ -559,6 +559,17 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
                     await restartAgent();
                     return send(res, 200, { ok: true });
                 }
+                case "POST /api/addons": {
+                    // Turn an add-on on or off, then restart pi so the extension starts or stops its server.
+                    if (busy)
+                        return send(res, 409, { error: "busy" });
+                    const body = await readJson(req);
+                    if (typeof body.starbuck !== "boolean")
+                        return send(res, 400, { error: "starbuck must be true or false" });
+                    saveConfig({ addons: withStarbuck(loadConfig(env).addons, body.starbuck) }, env);
+                    await restartAgent();
+                    return send(res, 200, { ok: true });
+                }
                 case "POST /api/restart":
                     if (agent.proc)
                         return send(res, 200, { ok: true });
@@ -580,7 +591,10 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
                     const body = await readJson(req);
                     const target = resolve(cwd, expand(String(body.path ?? "")));
                     const vault = cfg.vault;
-                    if (!(within(target, cwd) || (vault && within(target, vault))) || !existsSync(target))
+                    // Judge the real file, so a link inside the notes folder cannot open a document outside it.
+                    const real = realish(target);
+                    const inside = within(real, realish(cwd)) || Boolean(vault && within(real, realish(vault)));
+                    if (!inside || !existsSync(target))
                         return send(res, 404, { error: "not found in the notes folder" });
                     // Documents only: a file that the model wrote must never be run.
                     if (!OPENABLE.has(extname(target).toLowerCase()))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiagojct/subsub",
-  "version": "0.6.1",
+  "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.