@tiagojct/subsub 0.16.0 → 0.18.0

package/src/read.ts

@@ -0,0 +1,108 @@
+/**
+ * /read: guided reading of one paper, for people who are learning to read the literature.
+ * Sub-Sub asks why the user reads the paper and reads only as deep as that reason needs. It finds
+ * the passages (quotes with their place) and asks questions; the user writes the answers. It states
+ * no results: /lit-note is the note that Sub-Sub writes for you.
+ */
+
+/** The reasons to read, with the labels of the choice (English, Portuguese). */
+export const PURPOSES = {
+	background: ["Background: is it worth reading? (title and abstract, keep or drop)", "Contexto: vale a pena ler? (título e resumo, manter ou pôr de parte)"],
+	fact: ["One fact: find a specific detail", "Um dado: encontrar um pormenor concreto"],
+	extract: ["Extraction: one row for my review (question, design, population, setting, finding)", "Extração: uma linha para a minha revisão (pergunta, desenho, população, contexto, resultado)"],
+	critique: ["Critique: read it closely (peer review, the paper closest to mine)", "Crítica: ler com atenção (revisão por pares, o artigo mais próximo do meu)"],
+} as const;
+
+export type Purpose = keyof typeof PURPOSES;
+
+export interface ReadRequest {
+	ref: string;
+	purpose: Purpose;
+	date: string;
+	/** fact: what the user looks for. */
+	fact?: string;
+	/** extract: an existing sheet, relative to the Sub-Sub folder. */
+	sheet?: string;
+	/** extract: the review question of a new sheet. */
+	question?: string;
+}
+
+/** "/read extract smith2026" -> purpose and reference; the first word is a purpose only when it is one exactly. */
+export function readArgs(args: string): { purpose?: Purpose; ref: string } {
+	const words = args.trim().split(/\s+/).filter(Boolean);
+	const first = words[0]?.toLowerCase();
+	if (first && Object.hasOwn(PURPOSES, first)) return { purpose: first as Purpose, ref: words.slice(1).join(" ") };
+	return { ref: words.join(" ") };
+}
+
+const GUIDELINES =
+	"CONSORT for randomised trials, STROBE for observational studies, PRISMA for systematic reviews, STARD for diagnostic accuracy, TRIPOD or TRIPOD+AI for prediction models, CHEERS for economic evaluations, SRQR or COREQ for qualitative research";
+
+function depth(r: ReadRequest): string[] {
+	switch (r.purpose) {
+		case "background":
+			return [
+				"Depth: the title and the abstract only. Do not read the full text.",
+				'Under "## The paper at a glance":',
+				"- What it asks: the sentence of the title or abstract that states the question or aim, quoted.",
+				"- How: the sentence that names the design and the population, quoted.",
+				'Under "## Keep or drop": the question "Does this paper fit your reason? Look at the population, the design and the outcome.", then the lines "- [ ] Keep", "- [ ] Drop" and "Reason:", empty for the user.',
+			];
+		case "fact":
+			return [
+				`The user looks for: ${r.fact}`,
+				"Depth: only the passages that hold this fact. Get the section list first and read only the sections you need.",
+				'Under "## Where the paper says it": each passage, quoted, with its place. Under each passage, one question that makes the user read it closely (for example: what exactly does it say, for which population, at what time?) and an empty line "Your answer:".',
+				"If the paper does not say it, write that you did not find it and where you looked.",
+			];
+		case "extract": {
+			const sheet = r.sheet
+				? `the sheet ${r.sheet}: read it first for its columns, then add the row under its table with edit.`
+				: `a new sheet Research/<slug> extraction.md (slug: the review question in lower case with hyphens, at most five words; do not overwrite an existing file). Front matter: title, question: "${r.question}", type: extraction-sheet, created: ${r.date}. Then a table with the columns | Study | Question | Design | Population | Setting | Outcome | Main finding |.`;
+			return [
+				"Depth: the methods and the results (the full text when there is one).",
+				'Under "## Extraction": for each field below, the passage that answers it, quoted with its place, then an empty line "Your answer:".',
+				"- The question or aim",
+				"- The design",
+				"- The population (who, how many)",
+				"- The setting (where, when)",
+				"- The outcome and how it was measured",
+				"- The main finding: quote the sentence of the results that answers the question. Do not restate it.",
+				`Then add one row for this paper to ${sheet}`,
+				"The row: [[citekey]] in the Study column, and in every other column only where the user finds it (the page or the section). Leave the content of the cells for the user.",
+			];
+		}
+		case "critique":
+			return [
+				"Depth: the whole paper, section by section. A critique needs the full text: if you can read only the abstract, say so, write what the abstract allows, and offer /request-copy to ask the authors for the paper.",
+				'Under "## Methods", "## Results" and "## Discussion": the passages that matter to judge the study, quoted with their place, each with one question for the user (for example: how were the participants selected? what was compared? what else could explain the result?).',
+				`Under "## Appraisal": name the design and the reporting guideline that applies (${GUIDELINES}), and tell the user to check the paper against it item by item. Do not copy the checklist. Then five to eight questions on the risk of bias for this design (selection, confounding, measurement, missing data, selective reporting), each with the passage to look at.`,
+				"If the zotero_get_figure tool is available, show the table or figure with the main result: call it with the label of its caption and put the Markdown line it returns under the passage that cites it, with the page link, and a question about what the user sees in it.",
+			];
+	}
+}
+
+/**
+ * The instruction for the model. The first line is the command itself: the chat shows a long
+ * message folded under its first line, so the user sees what they asked for.
+ */
+export function readInstruction(r: ReadRequest): string {
+	return [
+		`/read ${r.purpose} ${r.ref}`,
+		"",
+		`Guided reading of ${r.ref}. The user is learning to read papers: you find the passages and ask; the user reads and writes the answers.`,
+		"",
+		"1. Find the work: zotero_find_items first. For a DOI or PMID that is not in the library, scholar_get_work, and offer to import it.",
+		"2. Read only what the depth below needs: zotero_get_fulltext for a library item; otherwise scholar_read_oa_fulltext (the section list first, then only the sections you need); otherwise scholar_get_work for the abstract.",
+		"3. Write the reading note as described below.",
+		"4. Give the user the path of the note and the first question to answer. Do not answer the questions.",
+		"",
+		"Rules:",
+		"- State no results, effect sizes, summaries or conclusions, in the note or in the chat. Quote the paper and ask; the user writes the answers.",
+		"- Copy quotes word for word from what you read, and mark every omission with [...]. After each quote give its place: (p. N) only with evidence: full text (Sub-Sub links it to that page of the PDF), otherwise the section (Abstract, Methods, Results).",
+		`- The note is Literature/<citekey>.md in the Sub-Sub folder, with the front matter of a literature note from the shared rules plus type: reading-note and purpose: ${r.purpose}; evidence says what you read. If the note exists, do not overwrite it: add a section "## Reading ${r.date}: ${r.purpose}" at the end with edit, with the content below one heading level lower.`,
+		'- Start with "## Why I am reading this" (the reason, in the user\'s words when they gave them) and end with one line "Next step:" (what to read or do next).',
+		"",
+		...depth(r),
+	].join("\n");
+}

package/src/roles.ts

@@ -2,12 +2,11 @@
  * Which tools each mode may use, and which calls need the user's approval.
  */
 
-import type { Mode, Profile } from "./config.ts";
-import { profileSpec } from "./profiles.ts";
+import type { Mode } from "./config.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 and the profile for these). */
+/** 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 = [
@@ -66,19 +65,17 @@ export const ZOTERO_CHECKS = [
 
 
 export interface ToolOptions {
-	profile?: Profile;
 	/** The model test: also the bakeoff_ tools. */
 	bench?: boolean;
 }
 
 /**
  * The tools of a mode. The Librarian manages the library: Zotero tools and files.
- * The Researcher has the same, plus searches, notes and reference checks. The
- * profile then removes tools. Every library change is still previewed (gateKind).
+ * The Researcher has the same, plus searches, notes and reference checks. Every
+ * library change is still previewed (gateKind).
  */
 export function toolsFor(mode: Mode, registered: string[], opts: ToolOptions = {}): string[] {
 	const has = new Set(registered);
-	const without = new Set(profileSpec(opts.profile ?? "editor").without);
 	const zotero = registered.filter((n) => n.startsWith("zotero_") && (opts.bench || !n.startsWith("zotero_bakeoff_")));
 	const wanted = [
 		...ZOTERO_READ,
@@ -87,16 +84,12 @@ export function toolsFor(mode: Mode, registered: string[], opts: ToolOptions = {
 		...(mode === "researcher" ? registered.filter((n) => n.startsWith("scholar_") || n.startsWith("verify_")) : []),
 		...FILE_TOOLS,
 	];
-	return [...new Set(wanted)].filter((n) => has.has(n) && !without.has(n));
+	return [...new Set(wanted)].filter((n) => has.has(n));
 }
 
 /** Why a Sub-Sub tool is not available now, or undefined when it is. */
 export function unavailableReason(name: string, mode: Mode, registered: string[], opts: ToolOptions = {}): string | undefined {
 	if (toolsFor(mode, registered, opts).includes(name)) return undefined;
-	const profile = opts.profile ?? "editor";
-	if (profileSpec(profile).without.includes(name)) {
-		return `${name} is not part of the ${profileSpec(profile).label} profile. The user can change the profile with /profile.`;
-	}
 	if (mode === "librarian" && toolsFor("researcher", registered, opts).includes(name)) {
 		return `${name} is part of the Researcher, which also does everything the Librarian does. The user can switch with /researcher.`;
 	}

package/src/subsub.ts

@@ -6,9 +6,7 @@
  *   and writes notes. Each mode can have its own model.
  * - An approval gate: every library change is previewed by the server (dry run)
  *   and shown to the user; nothing is applied without a yes.
- * - 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.
+ * - Commands: /librarian, /researcher, /read, /subsub, /history, /undo.
  * - Add-on: with "addons": ["starbuck"], Starbuck runs as a third server
  *   ("verify") for reference checks.
  *
@@ -17,7 +15,8 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Bridge, type ServerSpec } from "./bridge.ts";
@@ -25,12 +24,9 @@ import {
 	expand,
 	findUv,
 	FREE_MODELS,
-	isProfile,
 	loadConfig,
 	parseEnvFile,
-	type Profile,
 	type Mode,
-	saveConfig,
 	serverCommand,
 	starbuckCommand,
 	starbuckEnabled,
@@ -38,10 +34,12 @@ import {
 	uiLanguage,
 	who,
 } from "./config.ts";
-import { profileList, profileSpec, promptBlocked } from "./profiles.ts";
 import { coerceArgs, loosenArrays, resolvePathArgs } from "./args.ts";
 import { aiStatement } from "./statement.ts";
-import { applyEdits, checkLiteratureNote, field, frontMatter, itemKeyOf, missingQuotes, quoteProblem, quotesIn } from "./notes.ts";
+import { feedbackNote, ISSUES_URL } from "./feedback.ts";
+import { formatChecks, runChecks } from "./doctor.ts";
+import { PURPOSES, type Purpose, readArgs, readInstruction, type ReadRequest } from "./read.ts";
+import { applyEdits, checkLiteratureNote, field, frontMatter, itemKeyOf, missingQuotes, quoteProblem, quotesIn, sourceOf, withPageLinks } from "./notes.ts";
 import { buildPolicy, isSecret, judgePath, normalizeToolPath, realish, within } from "./paths.ts";
 import { describeArgs, formatPreview, isEmptyPreview } from "./preview.ts";
 import { perMinuteWait, providerTrouble, TROUBLE_TEXT, TROUBLE_TEXT_PT } from "./keys.ts";
@@ -57,6 +55,8 @@ export interface SubsubDeps {
 	/** A ready bridge (tests). When given, Sub-Sub does not start or stop servers. */
 	bridge?: Bridge;
 	specs?: ServerSpec[];
+	/** The subsub doctor lines for /feedback (tests give their own). */
+	doctor?: () => string;
 }
 
 const PACKAGE_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -143,8 +143,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 
 	let mode: Mode = cfg.defaultMode;
 	const benchRun = Boolean(process.env.SUBSUB_BENCH_OUT);
-	const toolOpts = () => ({ profile, bench: benchRun });
-	let profile: Profile = cfg.profile;
+	const toolOpts = () => ({ bench: benchRun });
 	const user = who(cfg);
 	/** True when started with the `subsub` command (not as a package inside plain pi). */
 	const standalone = process.env.SUBSUB_CLI === "1";
@@ -160,6 +159,8 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	/** True under `subsub web`: pi runs in RPC mode and the web view shows the state that the terminal header shows. */
 	const webView = process.env.SUBSUB_WEB === "1";
 	let lastError: string | undefined;
+	/** The last provider or tool error of the session, for /feedback. */
+	let recentError: string | undefined;
 	let resumes = 0;
 	let resumeTimer: ReturnType<typeof setTimeout> | undefined;
 	let turnStart = 0;
@@ -171,8 +172,6 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		const down = bridge ? Object.keys(bridge.errors) : ["zotero", "scholar"];
 		const state = {
 			mode,
-			profile,
-			profileLabel: profileSpec(profile).label,
 			model: ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : null,
 			down,
 			library,
@@ -238,7 +237,6 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 					return headerLines({
 						version,
 						mode,
-						profile: profileSpec(profile).label,
 						model: modelId,
 						library,
 						quote,
@@ -260,7 +258,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	function status(ctx: ExtensionContext): void {
 		modelId = ctx.model ? `${ctx.model.id}` : "no model";
 		const down = bridge ? Object.keys(bridge.errors) : ["zotero", "scholar"];
-		ctx.ui.setStatus("subsub", `Sub-Sub: ${mode} | ${profileSpec(profile).label} | ${modelId}${down.length ? ` | not running: ${down.join(", ")}` : ""}`);
+		ctx.ui.setStatus("subsub", `Sub-Sub: ${mode} | ${modelId}${down.length ? ` | not running: ${down.join(", ")}` : ""}`);
 		if (standalone) ctx.ui.setTitle(`Sub-Sub: ${mode}`);
 		headerTui?.requestRender();
 		webCtx = ctx;
@@ -324,7 +322,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		if (lookOn(ctx)) scheme ??= schemeFromAnsi(ctx.ui.theme.getFgAnsi("text"), ctx.ui.theme.name);
 		applyTheme(ctx);
 		await applyMode(ctx, restored ?? (pi.getFlag("librarian") ? "librarian" : pi.getFlag("researcher") ? "researcher" : cfg.defaultMode), false, !modelChosen);
-		logUsage(cfg.usageLog, { ev: "session", mode, profile, model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined });
+		logUsage(cfg.usageLog, { ev: "session", mode, model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined });
 		if (lookOn(ctx)) {
 			setHeader(ctx);
 			void refreshLibrary();
@@ -347,6 +345,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 
 	/** Prompt commands for the Researcher; the Librarian has the library ones (tag-batch, clean-tags, import-queue). */
 	const RESEARCH_PROMPTS = ["lit", "compare", "lit-note", "synthesis", "gaps", "manuscript", "verify", "review", "alert", "request-copy", "digest"];
+	const researcherOnly = (cmd: string) => L(`Sub-Sub: /${cmd} is part of the Researcher. Switch with /researcher.`, `Sub-Sub: /${cmd} faz parte do Investigador. Mude com /researcher.`);
 
 	// /tree moves to another branch: take that branch's mode (pi restores its model itself).
 	pi.on("session_tree", async (_event, ctx) => {
@@ -363,12 +362,18 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	pi.on("message_end", async (event, ctx) => {
 		const m = event.message as { role?: string; stopReason?: string; errorMessage?: string };
 		if (m.role !== "assistant" || m.stopReason !== "error") return;
-		lastError = m.errorMessage;
+		lastError = recentError = m.errorMessage;
 		if (webView || perMinuteWait(m.errorMessage) !== undefined) return;
 		const kind = providerTrouble(m.errorMessage);
 		if (kind) ctx.ui.notify(`Sub-Sub: ${trouble[kind]}`, "warning");
 	});
 
+	pi.on("tool_result", async (event) => {
+		if (!event.isError) return;
+		const text = event.content.map((c) => (c.type === "text" ? c.text : "")).join(" ");
+		recentError = `${(event as { toolName?: string }).toolName ?? "tool"}: ${text}`.slice(0, 2000);
+	});
+
 	// A per-minute limit (free tiers): wait as long as the provider says, then continue the task,
 	// up to three times per request of the user. Anything the user types cancels the wait.
 	pi.on("agent_end", async (_event, ctx) => {
@@ -393,8 +398,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	});
 
 
-	// 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.
+	// Research prompts in the Librarian. The input event comes before pi expands a prompt template.
 	pi.on("input", async (event, ctx) => {
 		if (resumeTimer) clearTimeout(resumeTimer);
 		resumeTimer = undefined;
@@ -403,13 +407,15 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		// The usage log keeps the kind of request and its length, never its text.
 		if (cmd !== "subsub-refresh") logUsage(cfg.usageLog, { ev: "ask", kind: cmd ? `/${cmd}` : "message", words: event.text.trim().split(/\s+/).filter(Boolean).length });
 		if (mode === "librarian" && cmd && RESEARCH_PROMPTS.includes(cmd)) {
-			ctx.ui.notify(L(`Sub-Sub: /${cmd} is part of the Researcher. Switch with /researcher.`, `Sub-Sub: /${cmd} faz parte do Investigador. Mude com /researcher.`), "warning");
+			ctx.ui.notify(researcherOnly(cmd), "warning");
+			return { action: "handled" };
+		}
+		// shortcut: a notice for the habit of 0.16 and earlier; drop it a few versions on.
+		if (cmd === "profile") {
+			ctx.ui.notify(L("Sub-Sub no longer has profiles: every command is in the Researcher. To read a paper with guidance, type /read.", "O Sub-Sub já não tem perfis: todos os comandos estão no Investigador. Para ler um artigo com orientação, escreva /read."), "info");
 			return { action: "handled" };
 		}
-		const why = promptBlocked(event.text, profile);
-		if (!why) return { action: "continue" };
-		ctx.ui.notify(`Sub-Sub: ${why}`, "warning");
-		return { action: "handled" };
+		return { action: "continue" };
 	});
 
 	pi.on("agent_start", async () => {
@@ -418,7 +424,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	});
 
 	pi.on("before_agent_start", async (event, ctx) => ({
-		systemPrompt: `${event.systemPrompt}\n\n${systemAddition(mode, { ...cfg, profile }, ctx.cwd)}`,
+		systemPrompt: `${event.systemPrompt}\n\n${systemAddition(mode, cfg, ctx.cwd)}`,
 	}));
 
 	/** Model test (subsub-bench): record every change instead of asking, and apply none. */
@@ -534,28 +540,39 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		if (!front || !key || field(front, "evidence")?.toLowerCase() !== "full text" || !quotesIn(text).length) return undefined;
 		const full = await fullTextOf(key, signal);
 		// Without the full text (no PDF indexed, Zotero closed) there is nothing to check against.
-		return full ? quoteProblem(missingQuotes(text, full, quotesIn(before))) : undefined;
+		if (!full) return undefined;
+		const missing = quoteProblem(missingQuotes(text, full.text, quotesIn(before)));
+		// A note that passes is written with its page references linked to the PDF.
+		if (!missing && full.attachment) {
+			const link = (s: string) => withPageLinks(s, sourceOf(full.text), full.attachment!);
+			if (name === "write") input.content = link(String(input.content ?? ""));
+			else for (const e of input.edits as Array<{ newText?: unknown }>) if (typeof e.newText === "string") e.newText = link(e.newText);
+		}
+		return missing;
 	}
 
-	/** The whole indexed full text of an item, read in parts, kept for the session. */
-	const fullTexts = new Map<string, string | null>();
-	async function fullTextOf(key: string, signal?: AbortSignal): Promise<string | undefined> {
+	/** The whole indexed full text of an item and its attachment, read in parts, kept for the session. */
+	const fullTexts = new Map<string, { text: string; attachment?: string } | null>();
+	async function fullTextOf(key: string, signal?: AbortSignal): Promise<{ text: string; attachment?: string } | undefined> {
 		if (fullTexts.has(key)) return fullTexts.get(key) ?? undefined;
 		let text = "";
+		let attachment: string | undefined;
 		let offset: number | null = 0;
 		try {
 			for (let part = 0; offset !== null && part < 20; part++) {
 				const res = await current().call("zotero_get_fulltext", { key, offset, max_chars: 60000 }, signal);
 				if (res.isError) break;
-				const data = (res.data ?? {}) as { text?: string; next_offset?: number | null };
+				const data = (res.data ?? {}) as { text?: string; next_offset?: number | null; attachment?: string };
 				text += data.text ?? "";
+				attachment ??= data.attachment;
 				offset = data.next_offset ?? null;
 			}
 		} catch {
 			/* no full text: the check is skipped */
 		}
-		fullTexts.set(key, text || null);
-		return text || undefined;
+		const full = text ? { text, attachment } : null;
+		fullTexts.set(key, full);
+		return full ?? undefined;
 	}
 
 	/**
@@ -633,34 +650,10 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		},
 	});
 
-	pi.registerCommand("profile", {
-		description: "Sub-Sub: show or change the profile (reader, scholar, author, editor)",
-		handler: async (args, ctx) => {
-			const want = args.trim().toLowerCase();
-			if (!want) {
-				ctx.ui.notify(`Profile: ${profileSpec(profile).label}. To change it, type /profile <name>.\n${profileList(profile)}`, "info");
-				return;
-			}
-			if (!isProfile(want)) {
-				ctx.ui.notify(`Unknown profile "${want}". Choose one of:\n${profileList(profile)}`, "warning");
-				return;
-			}
-			profile = want;
-			let saved = "";
-			try {
-				saved = ` Saved in ${saveConfig({ profile })}.`;
-			} catch (err) {
-				saved = ` Not saved: ${(err as Error).message}`;
-			}
-			await applyMode(ctx, mode, false, false);
-			ctx.ui.notify(`Sub-Sub: ${profileSpec(profile).label} profile (${profileSpec(profile).summary}).${saved}`, "info");
-		},
-	});
-
 	pi.registerCommand("subsub", {
 		description: "Sub-Sub: Zotero connection and library overview",
 		handler: async (_args, ctx) => {
-			const lines = [`Mode: ${mode}. Profile: ${profileSpec(profile).label}. Model: ${ctx.model?.id ?? "none"}.`];
+			const lines = [`Mode: ${mode}. Model: ${ctx.model?.id ?? "none"}.`];
 			if (!bridge) {
 				ctx.ui.notify(`${lines[0]}\nThe Zotero servers are not running. Try /reload.`, "warning");
 				return;
@@ -696,6 +689,23 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		},
 	});
 
+	// The web view's library search: the result goes to the page through a status, like the library counts.
+	pi.registerCommand("subsub-find", {
+		description: "Sub-Sub: search the library for the web view",
+		handler: async (args, ctx) => {
+			if (ctx.mode !== "rpc") return;
+			const q = String(args ?? "").trim();
+			let out: Record<string, unknown>;
+			try {
+				const r = await current().call("zotero_find_items", { query: q, limit: 25 });
+				out = r.isError ? { error: r.text } : { items: (r.data as { items?: unknown[] })?.items ?? [] };
+			} catch (err) {
+				out = { error: (err as Error).message };
+			}
+			ctx.ui.setStatus("subsub.find", JSON.stringify({ q, ...out }));
+		},
+	});
+
 	pi.registerCommand("ai-statement", {
 		description: "Sub-Sub: a draft statement on the use of AI for a manuscript (what journals ask for)",
 		handler: async (args, ctx) => {
@@ -721,6 +731,93 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		},
 	});
 
+	// A registered command runs before the input hook, so /read checks the mode itself.
+	pi.registerCommand("read", {
+		description: "Sub-Sub: read a paper with guidance; Sub-Sub finds the passages and asks, you write the answers. /read [background|fact|extract|critique] <citekey, DOI, PMID or title words>",
+		handler: async (args, ctx) => {
+			if (mode === "librarian") return ctx.ui.notify(researcherOnly("read"), "warning");
+			let { purpose, ref } = readArgs(String(args ?? ""));
+			ref ||= (await ctx.ui.input(L("Which paper?", "Que artigo?"), L("citekey, DOI, PMID or title words", "citekey, DOI, PMID ou palavras do título")))?.trim() ?? "";
+			if (!ref) return;
+			if (!purpose) {
+				const labels = Object.values(PURPOSES).map(([en, pt]) => L(en, pt));
+				purpose = (Object.keys(PURPOSES) as Purpose[])[labels.indexOf((await ctx.ui.select(L("Why are you reading it?", "Porque vai ler este artigo?"), labels)) ?? "")];
+				if (!purpose) return;
+			}
+			const req: ReadRequest = { ref, purpose, date: new Date().toISOString().slice(0, 10) };
+			if (purpose === "fact") {
+				req.fact = (await ctx.ui.input(L("Which fact are you looking for?", "Que dado procura?")))?.trim();
+				if (!req.fact) return;
+			}
+			if (purpose === "extract") {
+				let sheets: string[] = [];
+				try {
+					sheets = readdirSync(join(cfg.vault ?? ctx.cwd, "Research")).filter((f) => f.endsWith(" extraction.md")).sort();
+				} catch {
+					// No Research folder yet: the first sheet is a new one.
+				}
+				const fresh = L("New sheet", "Nova folha");
+				const pick = sheets.length ? await ctx.ui.select(L("Which extraction sheet?", "Que folha de extração?"), [...sheets, fresh]) : fresh;
+				if (!pick) return;
+				if (pick === fresh) {
+					req.question = (await ctx.ui.input(L("The question of your review", "A pergunta da sua revisão")))?.trim();
+					if (!req.question) return;
+				} else req.sheet = `Research/${pick}`;
+			}
+			pi.sendUserMessage(readInstruction(req), ctx.isIdle() ? undefined : { deliverAs: "followUp" });
+		},
+	});
+
+	pi.registerCommand("feedback", {
+		description: "Sub-Sub: a draft bug report or idea in Inbox/, to read and post on GitHub yourself; Sub-Sub sends nothing  [what happened]",
+		handler: async (args, ctx) => {
+			const date = new Date().toISOString().slice(0, 10);
+			let piVersion = "";
+			try {
+				piVersion = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))), "..", "package.json"), "utf8")).version;
+			} catch {
+				/* not needed for the report */
+			}
+			let checks: string;
+			try {
+				checks = deps.doctor ? deps.doctor() : formatChecks(runChecks(cfg, process.env));
+			} catch (err) {
+				checks = `subsub doctor failed: ${(err as Error).message}`;
+			}
+			const text = feedbackNote({
+				what: String(args ?? ""),
+				date,
+				versions: `Sub-Sub ${ownVersion()}${piVersion ? `, pi ${piVersion}` : ""}, Node ${process.version}, ${process.platform} ${process.arch}`,
+				setup: [
+					`Mode: ${mode}. Model: ${ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none"}.`,
+					`Language: ${cfg.language}. Reference checks (Starbuck): ${starbuckEnabled(cfg) ? "on" : "off"}.`,
+					`Zotero: ${library.zotero}.${bridge && Object.keys(bridge.errors).length ? ` Servers not running: ${Object.keys(bridge.errors).join(", ")}.` : ""}`,
+				],
+				checks,
+				lastError: recentError,
+				home: homedir(),
+				vault: cfg.vault,
+			});
+			const dir = join(cfg.vault ?? ctx.cwd, "Inbox");
+			let file = join(dir, `${date} Sub-Sub feedback.md`);
+			for (let n = 2; existsSync(file); n++) file = join(dir, `${date} Sub-Sub feedback-${n}.md`);
+			try {
+				mkdirSync(dir, { recursive: true });
+				writeFileSync(file, text);
+			} catch (err) {
+				ctx.ui.notify(`${L("Could not save it", "Não foi possível guardar")}: ${(err as Error).message}`, "warning");
+				return;
+			}
+			ctx.ui.notify(
+				L(
+					`Sub-Sub: a draft report is in ${file}. Read it, add what you expected, take out anything you do not want to share, and post it at ${ISSUES_URL}. Sub-Sub has sent nothing.`,
+					`Sub-Sub: há um rascunho do relatório em ${file}. Leia-o, acrescente o que esperava, retire o que não quer partilhar e publique-o em ${ISSUES_URL}. O Sub-Sub não enviou nada.`,
+				),
+				"info",
+			);
+		},
+	});
+
 	pi.registerCommand("history", {
 		description: "Sub-Sub: recent library changes",
 		handler: async (_args, ctx) => {

package/src/usage.ts

@@ -10,7 +10,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
 export type UsageEvent =
-	| { ev: "session"; mode: string; profile: string; model?: string }
+	| { ev: "session"; mode: string; model?: string }
 	| { ev: "ask"; kind: string; words: number }
 	| { ev: "turn"; seconds: number; tools: number; error?: string }
 	| { ev: "change"; tool: string; approved: boolean };