@tiagojct/subsub 0.11.0 → 0.11.2

package/src/web.ts

@@ -22,7 +22,7 @@ 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.ts";
-import { expand, loadConfig, saveConfig, type SubsubConfig, withStarbuck } from "./config.ts";
+import { configPath, expand, loadConfig, readConfigFile, saveConfig, type SubsubConfig, withStarbuck } from "./config.ts";
 import { TESTED_MODELS } from "./init.ts";
 import { obsidianRoot } from "./layout.ts";
 import { realish, within } from "./paths.ts";
@@ -336,7 +336,7 @@ export async function startWeb(opts: WebOptions, env: NodeJS.ProcessEnv = proces
 	env.PI_CODING_AGENT_DIR = agentDir; // for the session list below
 
 	const childEnv: NodeJS.ProcessEnv = { ...env, SUBSUB_WEB: "1" };
-	const baseArgs = [bin, "--mode", "rpc", "--here", ...(opts.librarian ? ["--librarian"] : []), ...opts.piArgs];
+	const baseArgs = [bin, "--mode", "rpc", "--here", ...opts.piArgs];
 	const agent = new Agent(process.execPath, baseArgs, cwd, childEnv);
 
 	// ---- state shared with the pages
@@ -346,8 +346,20 @@ export async function startWeb(opts: WebOptions, env: NodeJS.ProcessEnv = proces
 	let busy = false;
 	let lastSeen = Date.now();
 	let restarting = false;
+	let switching = false; // a restart for a new model, add-on or key is under way
+	let lastSession: string | undefined;
 	let refreshAfterRun = false;
 
+	/** The mode to start pi in: the one on screen, else the --librarian flag. A session's own mode still wins. */
+	function modeArgs(): string[] {
+		const shown = (subsubState as { mode?: string } | null)?.mode;
+		if (shown === "librarian" || shown === "researcher") return [`--${shown}`];
+		return opts.librarian ? ["--librarian"] : [];
+	}
+	function startAgent(): void {
+		agent.start([...modeArgs(), ...(lastSession && existsSync(lastSession) ? ["--session", lastSession] : [])]);
+	}
+
 	function broadcast(ev: unknown): void {
 		const data = `data: ${JSON.stringify(ev)}\n\n`;
 		for (const c of clients) c.write(data);
@@ -384,12 +396,13 @@ export async function startWeb(opts: WebOptions, env: NodeJS.ProcessEnv = proces
 	agent.onExit = (code) => {
 		if (restarting) return;
 		busy = false;
+		for (const id of dialogs.keys()) broadcast({ type: "dialog_closed", id });
 		dialogs.clear();
 		broadcast({ type: "agent_exit", code, stderr: agent.stderr.slice(-1500) });
 		log(`pi stopped (code ${code}).\n${agent.stderr.slice(-2000)}`);
 	};
 
-	agent.start();
+	startAgent();
 
 	async function snapshot(): Promise<Record<string, unknown>> {
 		const out: Record<string, unknown> = {
@@ -403,6 +416,7 @@ export async function startWeb(opts: WebOptions, env: NodeJS.ProcessEnv = proces
 		};
 		try {
 			out.session = await agent.request({ type: "get_state" });
+			lastSession = (out.session as { sessionFile?: string }).sessionFile ?? lastSession;
 			out.messages = ((await agent.request({ type: "get_messages" })) as { messages: unknown[] }).messages;
 			out.commands = ((await agent.request({ type: "get_commands" })) as { commands: unknown[] }).commands;
 		} catch (err) {
@@ -422,22 +436,37 @@ export async function startWeb(opts: WebOptions, env: NodeJS.ProcessEnv = proces
 	}
 
 	async function restartAgent(): Promise<void> {
-		let sessionFile: string | undefined;
 		try {
-			sessionFile = ((await agent.request({ type: "get_state" })) as { sessionFile?: string }).sessionFile;
+			lastSession = ((await agent.request({ type: "get_state" })) as { sessionFile?: string }).sessionFile ?? lastSession;
 		} catch {
-			/* start fresh */
+			/* keep the last one known */
 		}
 		restarting = true;
 		for (const id of dialogs.keys()) broadcast({ type: "dialog_closed", id });
 		dialogs.clear();
-		await agent.stop();
-		restarting = false;
+		try {
+			await agent.stop();
+		} finally {
+			restarting = false;
+		}
 		busy = false;
-		agent.start(sessionFile && existsSync(sessionFile) ? ["--session", sessionFile] : []);
+		startAgent();
 		broadcast(await snapshot());
 	}
 
+	/** Run a change that restarts pi, one at a time. */
+	async function withRestart(res: ServerResponse, change: () => Promise<void> | void): Promise<void> {
+		if (busy || switching) return send(res, 409, { error: "busy" });
+		switching = true;
+		try {
+			await change();
+			await restartAgent();
+		} finally {
+			switching = false;
+		}
+		return send(res, 200, { ok: true });
+	}
+
 	// ---- idle stop
 	let closing = false;
 	const idleTimer = setInterval(() => {
@@ -521,7 +550,13 @@ export async function startWeb(opts: WebOptions, env: NodeJS.ProcessEnv = proces
 					const body = await readJson(req);
 					const message = String(body.message ?? "").trim();
 					if (!message) return send(res, 400, { error: "empty message" });
-					await agent.request({ type: "prompt", message, ...(busy ? { streamingBehavior: "followUp" } : {}) });
+					try {
+						await agent.request({ type: "prompt", message, ...(busy ? { streamingBehavior: "followUp" } : {}) });
+					} catch (err) {
+						// No provider yet: the page opens the model dialog instead of showing pi's text.
+						if (/no api key|no model|no models available/i.test((err as Error).message)) return send(res, 409, { error: "nomodel" });
+						throw err;
+					}
 					return send(res, 200, { ok: true });
 				}
 				case "POST /api/abort":
@@ -565,40 +600,44 @@ export async function startWeb(opts: WebOptions, env: NodeJS.ProcessEnv = proces
 					return send(res, 200, { models: Array.isArray(data) ? data : (data.models ?? []) });
 				}
 				case "POST /api/model": {
-					if (busy) return send(res, 409, { error: "busy" });
+					if (busy || switching) return send(res, 409, { error: "busy" });
 					const body = await readJson(req);
 					const spec = `${String(body.provider)}/${String(body.id)}`;
 					// Remember the model for the current mode (or both), then restart pi so the extension reads it.
 					const mode = (subsubState as { mode?: string } | null)?.mode === "librarian" ? "librarian" : "researcher";
-					const models: Record<string, string> = { ...(loadConfig(env).models ?? {}), [mode]: spec };
+					// Start from what the file says, not from the built-in defaults, so a model the user never chose is not saved.
+					const raw = readConfigFile(configPath(env));
+					const saved = raw.models && typeof raw.models === "object" ? (raw.models as Record<string, string>) : typeof raw.model === "string" && raw.model ? { librarian: raw.model, researcher: raw.model } : {};
+					const models: Record<string, string> = { ...saved, [mode]: spec };
 					if (body.both) models[mode === "librarian" ? "researcher" : "librarian"] = spec;
-					saveConfig({ models, model: undefined }, env);
-					await agent.request({ type: "set_model", provider: String(body.provider), modelId: String(body.id) });
-					await restartAgent();
-					return send(res, 200, { ok: true });
+					return withRestart(res, async () => {
+						saveConfig({ models, model: undefined }, env);
+						// The open conversation records the new model, so it keeps it after the restart.
+						await agent.request({ type: "set_model", provider: String(body.provider), modelId: String(body.id) }).catch(() => {});
+					});
 				}
 				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" });
+					if (busy || switching) 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 });
+					return withRestart(res, () => {
+						saveConfig({ addons: withStarbuck(loadConfig(env).addons, body.starbuck) }, env);
+					});
 				}
 				case "POST /api/restart":
-					if (agent.proc) return send(res, 200, { ok: true });
-					agent.start();
+					if (agent.proc || switching) return send(res, 200, { ok: true });
+					startAgent();
 					broadcast(await snapshot());
 					return send(res, 200, { ok: true });
 				case "POST /api/login": {
-					if (busy) return send(res, 409, { error: "busy" });
+					if (busy || switching) return send(res, 409, { error: "busy" });
 					const body = await readJson(req);
-					saveApiKey(agentDir, String(body.provider ?? ""), String(body.key ?? ""));
-					const current = loadConfig(env);
-					if (body.provider === "opencode-go" && Object.keys(current.models).length === 0) saveConfig({ models: TESTED_MODELS, model: undefined }, env);
-					await restartAgent();
-					return send(res, 200, { ok: true });
+					return withRestart(res, () => {
+						saveApiKey(agentDir, String(body.provider ?? ""), String(body.key ?? ""));
+						const current = loadConfig(env);
+						if (body.provider === "opencode-go" && Object.keys(current.models).length === 0) saveConfig({ models: TESTED_MODELS, model: undefined }, env);
+					});
 				}
 				case "POST /api/open": {
 					const body = await readJson(req);

package/web/app.css

@@ -158,6 +158,7 @@ button:disabled { opacity: 0.45; cursor: default; }
 .icon-btn:hover { color: var(--text); background: var(--surface); }
 .icon-btn[aria-pressed="true"] { color: var(--accent); background: var(--accent-soft); }
 
+.model-btn.needs { color: var(--warn); border-color: var(--warn); font-family: var(--sans); }
 .chip-btn {
 	max-width: 16rem;
 	overflow: hidden;

package/web/app.js

@@ -183,7 +183,9 @@ function renderHeader() {
 	$("starbuck-toggle").checked = Boolean(state?.starbuck);
 	$("starbuck-label").title = t("starbuckHint");
 	const m = state?.model ?? session?.model;
-	$("model-btn").textContent = $("model-btn-side").textContent = m ? m.id : t("noModel");
+	const none = !m || !m.id || m.id === "unknown";
+	$("model-btn").textContent = $("model-btn-side").textContent = none ? t("noModel") : m.id;
+	for (const b of [$("model-btn"), $("model-btn-side")]) b.classList.toggle("needs", none);
 	const lib = $("library");
 	const txt = lib.querySelector(".library-text") ?? lib;
 	const L = state?.library;
@@ -650,6 +652,7 @@ function onEvent(ev) {
 			setBusy(!!ev.busy);
 			dialogs.length = 0;
 			for (const d of ev.dialogs ?? []) dialogs.push(d);
+			dropStaleDialog();
 			nextDialog();
 			loadSessions();
 			break;
@@ -743,6 +746,8 @@ function onEvent(ev) {
 			break;
 		case "agent_exit":
 			setBusy(false);
+			dialogs.length = 0;
+			dropStaleDialog();
 			log.append(
 				el(
 					"div",
@@ -776,6 +781,7 @@ function dialogTitle(d) {
 	if ((m = raw.match(/^apply (\S+)\?$/))) return t("apply", { x: toolLabel(m[1]) });
 	if ((m = raw.match(/^run (\S+)\?$/))) return t("run", { x: toolLabel(m[1]) });
 	if (raw === "undo?") return t("undo");
+	if ((m = raw.match(/^write the Starbuck report to (.+)\?$/))) return t("starbuckReport", { x: m[1] });
 	if ((m = raw.match(/^(write|edit) (.+)\?$/))) return t("write", { x: m[2] });
 	return raw;
 }
@@ -797,6 +803,14 @@ function paintPreview(pre, text) {
 	}
 }
 
+/** Close the dialog on screen if Sub-Sub no longer waits for it (pi restarted, or another tab answered). */
+function dropStaleDialog() {
+	if (shownDialog && !dialogs.some((d) => d.id === shownDialog.id)) {
+		shownDialog = null;
+		if ($("dialog").open) $("dialog").close();
+	}
+}
+
 function nextDialog() {
 	if (shownDialog || !dialogs.length) return;
 	const d = dialogs[0];
@@ -821,6 +835,7 @@ function nextDialog() {
 			note(err.message, "error");
 		}
 	};
+	$("dialog-form").onsubmit = (e) => e.preventDefault();
 	if (d.method === "confirm") {
 		buttons.append(
 			el("span", { class: "modal-shortcut-hint", text: t("confirmShortcutHint") }),
@@ -834,14 +849,26 @@ function nextDialog() {
 		const field = d.method === "editor" ? el("textarea", {}) : el("input", { type: "text", placeholder: d.placeholder ?? "" });
 		field.value = d.prefill ?? "";
 		body.append(field);
+		$("dialog-form").onsubmit = (e) => {
+			e.preventDefault();
+			answer({ value: field.value });
+		};
 		buttons.append(
 			el("button", { type: "button", class: "ghost", text: t("cancel"), onclick: () => answer({ cancelled: true }) }),
 			el("button", { type: "button", class: "primary", text: t("ok"), onclick: () => answer({ value: field.value }) }),
 		);
 	}
+	// Keys typed just before the dialog opened (the user was writing a message) must not answer it.
+	const openedAt = performance.now();
+	const yesKeys = lang === "pt" ? ["s", "S", "y", "Y"] : ["y", "Y"];
 	dlg.onkeydown = (e) => {
 		if (d.method === "confirm") {
-			if (e.key === "y" || e.key === "Y" || (e.key === "Enter" && (e.metaKey || e.ctrlKey))) {
+			if (e.repeat || performance.now() - openedAt < 700) {
+				// Escape still declines (through oncancel); Enter and Space would press the focused button.
+				if (e.key !== "Escape" && e.key !== "Tab") e.preventDefault();
+				return;
+			}
+			if (yesKeys.includes(e.key) || (e.key === "Enter" && (e.metaKey || e.ctrlKey))) {
 				e.preventDefault();
 				answer({ confirmed: true });
 			} else if (e.key === "n" || e.key === "N") {
@@ -867,6 +894,9 @@ function showModels() {
 
 async function openModels() {
 	const dlg = $("model-dialog");
+	// Name the mode the choice is saved for; "both modes" is a choice for this time only.
+	dlg.querySelector("h2").textContent = t(mode() === "librarian" ? "modelTitleLibrarian" : "modelTitleResearcher");
+	$("model-both").checked = false;
 	const ul = $("models");
 	ul.replaceChildren(el("li", { class: "empty-models", text: "…" }));
 	const sel = $("login-provider");
@@ -954,6 +984,16 @@ async function sendMessage(text) {
 		return true;
 	} catch (err) {
 		if (isTemplate) sentTemplates.pop();
+		if (err.message === "nomodel") {
+			// Keep what the user wrote, and show where to connect a provider.
+			if (!input.value.trim()) {
+				input.value = message;
+				autosize();
+			}
+			note(t("noModelSend"), "warning");
+			showModels();
+			return false;
+		}
 		note(err.message, "error");
 		return false;
 	}

package/web/i18n.js

@@ -5,7 +5,8 @@ export const STRINGS = {
 	en: {
 		profile: "Profile",
 		model: "Model",
-		noModel: "No model",
+		noModel: "Connect a model",
+		noModelSend: "No model is connected yet. Choose a provider and save its key; your message is still in the box.",
 		newConversation: "New conversation",
 		actions: "Actions",
 		conversations: "Conversations",
@@ -21,6 +22,7 @@ export const STRINGS = {
 		run: "Run {x}?",
 		undo: "Undo this change?",
 		write: "Allow writing to {x}?",
+		starbuckReport: "Write the Starbuck report to {x}?",
 		approveHint: "Nothing changes until you select Yes.",
 		zoteroChecking: "Zotero: checking",
 		zoteroDown: "Zotero is not running",
@@ -39,6 +41,8 @@ export const STRINGS = {
 		connectModel: "Connect a model to start.",
 		connect: "Connect",
 		modelTitle: "Model",
+		modelTitleResearcher: "Model for the Researcher",
+		modelTitleLibrarian: "Model for the Librarian",
 		chooseModel: "Choose a model",
 		noModels: "No models yet. Connect a provider below.",
 		connectProvider: "Connect a provider",
@@ -94,7 +98,8 @@ export const STRINGS = {
 	pt: {
 		profile: "Perfil",
 		model: "Modelo",
-		noModel: "Sem modelo",
+		noModel: "Ligar um modelo",
+		noModelSend: "Ainda não há um modelo ligado. Escolha um fornecedor e guarde a chave; a sua mensagem continua na caixa.",
 		newConversation: "Nova conversa",
 		actions: "Ações",
 		conversations: "Conversas",
@@ -110,6 +115,7 @@ export const STRINGS = {
 		run: "Executar {x}?",
 		undo: "Desfazer esta alteração?",
 		write: "Permitir escrever em {x}?",
+		starbuckReport: "Escrever o relatório do Starbuck em {x}?",
 		approveHint: "Nada muda até selecionar Sim.",
 		zoteroChecking: "Zotero: a verificar",
 		zoteroDown: "O Zotero não está aberto",
@@ -128,6 +134,8 @@ export const STRINGS = {
 		connectModel: "Ligue um modelo para começar.",
 		connect: "Ligar",
 		modelTitle: "Modelo",
+		modelTitleResearcher: "Modelo do Investigador",
+		modelTitleLibrarian: "Modelo do Bibliotecário",
 		chooseModel: "Escolha um modelo",
 		noModels: "Ainda não há modelos. Ligue um fornecedor abaixo.",
 		connectProvider: "Ligar um fornecedor",
@@ -161,7 +169,7 @@ export const STRINGS = {
 		searchConversations: "Procurar conversas",
 		export: "Exportar",
 		exportTitle: "Exportar conversa",
-		confirmShortcutHint: "Y para aprovar, N para recusar",
+		confirmShortcutHint: "S para aprovar, N para recusar",
 		starbuck: "Verificação de referências (Starbuck)",
 		starbuckHint: "Verifica se as obras citadas existem, correspondem à citação e não foram retratadas. O Sub-Sub reinicia quando muda esta opção.",
 		starbuckOn: "A verificação de referências está ligada. Use /verify, ou peça ao investigador que verifique as referências de um manuscrito.",

package/docs/Subsub.md

@@ -1,140 +0,0 @@
-Sub-Sub is a Zotero librarian and research assistant that runs in pi. It uses the Python servers of zotero-local-mcp for the library: previews, version checks, journal and undo, the tag vocabulary.
-
-- Code: ~/Projects/subsub (git). Servers: ~/Projects/zotero-local-mcp
-- Shared rules: [[Zotero agent]]. Tag vocabulary: [[Zotero tags]]
-- Settings: ~/.config/subsub/config.json (written by `subsub init`) and ~/.config/zotero-local-mcp/env (also read by the weekly alerts in launchd)
-- Sub-Sub folder: ~/Obsidian/Powerslave/Sub-Sub, with Inbox/, Literature/, Syntheses/, Research/ and Zotero/ (tag list, note formats, alert searches). Sub-Sub writes only there without asking.
-- Models: Librarian opencode-go/mimo-v2.6-flash, Researcher opencode-go/mimo-v2.6-pro
-- Public docs: the README in ~/Projects/subsub (source for subsub.tiagojacinto.eu)
-
-## Safety
-
-- Approval is enforced in code. Before any library change, Sub-Sub asks the server for the preview and shows it in a dialog. The change runs only after you select Yes. The model cannot skip this.
-- The model does not need to do a dry run first. You see one dialog per change.
-- Library tools run one at a time, so each preview includes the effect of earlier changes in the same step.
-- The Librarian has no search tools. The Researcher has all tools; every library change still needs a Yes.
-- bash is off. File writes outside the Sub-Sub folder, and writes to the rule files, config folders and code folders, need a Yes.
-
-## Install
-
-1. Make sure that Node is version 22.19 or later: type `node --version`.
-2. Type `cd ~/Projects/subsub && npm install --omit=dev`.
-3. Type `npm link`. This adds the `subsub` command.
-4. Optional: type `pi remove ~/Projects/subsub`. Then plain `pi` stays a plain coding agent without Sub-Sub.
-5. Type `subsub`. If pi has no OpenCode Go key yet, type `/login`, select OpenCode Zen and Go, and paste the key.
-6. Type `/subsub`. Make sure that the result shows "Zotero: reachable" and the model for the mode (mimo-v2.6-pro in the Researcher).
-7. Type `subsub init` once. Keep the Sub-Sub folder, the tag list, the email and the models. For the profile, select Editor.
-8. Type `subsub doctor`. Make sure that no line shows FIX.
-
-If you change the Node version with fnm, do step 3 again.
-
-## Use
-
-1. Start Zotero.
-2. Type `subsub`. From the home folder, Sub-Sub starts in the Sub-Sub folder. From a different folder (for example a manuscript folder), it starts in that folder. To stay in the home folder, type `subsub --here`.
-3. Sub-Sub starts in the Researcher. The Researcher reads, searches, writes notes and changes the library. The Librarian only manages the library. To start in the Librarian, type `subsub --librarian`.
-4. To change the mode, type `/librarian` or `/researcher`. The mode also changes the model. After research, ask the Researcher to import the works you choose. It imports them in the same conversation, with one preview, and offers to tag them.
-5. When a dialog shows a preview, read it. Select Yes to apply the change, or No to stop it. After No, tell Sub-Sub what to change.
-6. To continue the last session, type `subsub -c`. To select an older session, type `subsub -r`.
-
-Sub-Sub always replies in English and writes its notes in English. Quotations and titles of works stay in their original language.
-
-Sub-Sub keeps its pi settings, sessions and packages in ~/.subsub/agent, separate from plain pi (~/.pi/agent).
-
-Commands:
-
-- `/subsub`: Zotero connection and library overview
-- `/profile`: shows or changes the profile
-- `/history`: recent library changes
-- `/undo`: shows the last change, asks, and reverts it. `/undo <id>` reverts a specific change from `/history`.
-
-Templates (type the name, then the argument):
-
-- Library (both modes): `/tag-batch [size]`, `/clean-tags`, `/import-queue [note path]`
-- Research (Researcher): `/lit-note <citekey>`, `/synthesis <topic>`, `/gaps <topic>`, `/manuscript <path>`, `/alert`
-
-## Web view
-
-1. Type `subsub web`. Sub-Sub opens in the browser, with the same profiles, tools and approvals. The mode buttons are at the top. The side panel shows the actions of the mode. The approval dialog shows the server preview; the change runs only after Yes.
-2. To add a shortcut (Applications on macOS), type `subsub shortcut`. To remove it, type `subsub shortcut --remove`.
-3. The server listens only on 127.0.0.1 and needs the random key in the address that `subsub web` opens. A second `subsub web` opens the running one.
-4. The server stops 10 minutes after the last page closes. `subsub web --stay` keeps it running.
-5. The labels are in European Portuguese when the language setting is Portuguese. A theme toggle button in the header switches between light, dark and system themes.
-6. Faster review: in approval dialogs, press `y` to apply or `n` to cancel without using the mouse.
-7. One-click copy buttons appear on every code block and assistant note. The sidebar includes real-time conversation search and an Export button to download the discussion as Markdown.
-8. The model button lists the models and saves an API key for a provider (the same auth.json as `/login`). It saves the model for the current mode. To use the model in both modes, select "Use it in both modes".
-
-The log is in ~/.subsub/web.log.
-
-## Profiles
-
-The profile sets how much Sub-Sub does. To see the profile, type `/profile`. To change it, type `/profile reader` (or scholar, author, editor). The change is saved.
-
-- Reader: explains each step. Reading notes are quotes with page numbers, plus questions. No summaries or syntheses. No bulk library changes.
-- Scholar: literature notes, syntheses, searches and alerts. All library changes.
-- Author: Scholar plus manuscripts: citation check, bibliography, comments on the argument. It does not write the paragraphs.
-- Editor: everything, including drafted manuscript text when you ask.
-
-## Tag review notes
-
-Sub-Sub writes proposed tags in review notes in Inbox/ ("Zotero tag review NN.md"). Edit the Proposed tags column. Write skip to leave an item as it is.
-
-To apply one note, in either mode, type: apply the tag review Inbox/Zotero tag review NN.md.
-
-To apply many notes:
-
-1. Start Zotero.
-2. Type `subsub review preview 13-31` (the numbers of the notes). This shows what each note will change. Nothing changes.
-3. Type `subsub review apply 13-31`. Read the preview, then type y.
-4. If Zotero asks for permission, select Always Allow.
-
-Use note numbers, not a pattern such as "*.md": a pattern also takes older notes that have no Applied line, and applying an old note again replaces later tag changes.
-
-Notes that were already applied are left out. Each applied note gets an "Applied" line with the journal ID. To revert a note, type `/undo <journal ID>` in Sub-Sub. If a note shows "changed since the note was written", the tags of those items changed in Zotero after the note was made; applying the note replaces those changes.
-
-## Look
-
-When you start Sub-Sub with the `subsub` command, it shows a banner, a status line (mode, model, Zotero items, items to review) and a line from Moby-Dick. The theme is Glauca, in the dark or light version that matches your terminal (set "themes": "subsub-try-works" for the other one). The theme changes for the session only; your pi theme setting stays.
-
-To change this, add to ~/.config/subsub/config.json:
-
-- `"quotes": false`: no Moby-Dick line.
-- `"themes": false`: keep your own pi theme.
-- `"look": false`: no banner and no themes.
-
-The themes are in ~/Projects/subsub/themes. To make them again after a change in Gam, see scripts/make-themes.py.
-
-## Model test
-
-The model test runs several models on the same tasks against your library and compares them. Nothing in the library changes: each library change is recorded with its preview and then blocked. Notes go to ~/Projects/subsub/bench-results/<date>/, not to the Sub-Sub folder.
-
-Tasks:
-
-- Library tasks: tag 20 items against a blind reference (reference.md shows the items without their tags; the tags go in reference.json); fix the items without topic or status; import identifiers, one of them already in the library.
-- Research tasks: a literature note on one item with full text; a synthesis on one topic; a search for recent papers that are not in the library.
-
-Procedure:
-
-1. Start Zotero.
-2. Type `subsub-bench prepare`. This picks the tasks.
-3. Type `caffeinate -i subsub-bench run`. This takes 1 to 2 hours. caffeinate keeps the Mac awake. If the run stops, type the same command again: finished runs are not repeated.
-4. Type `subsub-bench score`. The result is results.md in the results folder.
-
-Options for `run`: `--models a,b` for all tasks, or `--librarian a,b` and `--researcher c,d` for each group of tasks (OpenCode Go model ids), `--only tagging,import`, `--parallel 3`, `--timeout 900`. Library tasks run in the Librarian. Research tasks run in the Researcher.
-
-Each model gets a code (for example M417), so the notes can be judged blind. key.json has the codes.
-
-## Problems
-
-- To find a setup problem, type `subsub doctor`. Each line marked FIX says what to do.
-- "the zotero server did not start": run `cd ~/Projects/zotero-local-mcp && uv sync`. If pi does not find uv, add `"uvPath": "/path/to/uv"` to ~/.config/subsub/config.json (type `which uv` to see the path).
-- "cannot use opencode-go/...": the OpenCode Go key is missing. In Sub-Sub, type `/login` again.
-- "command not found: subsub": type `cd ~/Projects/subsub && npm link`.
-- To update Sub-Sub after new code arrives, type `cd ~/Projects/subsub && npm install --omit=dev`. Do not use `subsub update`.
-- A tool call is refused with "part of the Researcher": type `/researcher`.
-- `subsub review` says "No note matches": check the note numbers in Inbox/. A path is written from the Sub-Sub folder, in quotes (for example "Inbox/Zotero tag review 13.md").
-
-## Tests
-
-- `cd ~/Projects/subsub && npm install && npm test`: unit tests.
-- `npm run test:e2e`: real pi and the `subsub` command with a scripted model and a fake Zotero.