@tiagojct/subsub 0.11.0 → 0.11.1

package/dist/subsub.js

@@ -1,5 +1,5 @@
 /**
- * Sub-Sub: a Zotero librarian and research assistant for pi.
+ * Sub-Sub: a research assistant for pi that works from your own Zotero library.
  *
  * - Two modes: the Librarian manages the library (Zotero tools only); the
  *   Researcher does the same and also searches PubMed, Europe PMC and OpenAlex
@@ -23,7 +23,7 @@ import { expand, findUv, isProfile, loadConfig, parseEnvFile, saveConfig, server
 import { profileList, profileSpec, promptBlocked } from "./profiles.js";
 import { coerceArgs, loosenArrays, resolvePathArgs } from "./args.js";
 import { applyEdits, checkLiteratureNote } from "./notes.js";
-import { buildPolicy, judgePath, normalizeToolPath, realish, within } from "./paths.js";
+import { buildPolicy, isSecret, 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";
@@ -104,6 +104,7 @@ export async function createSubsub(pi, deps = {}) {
     if (deps.bridge)
         registerTools(deps.bridge);
     pi.registerFlag("librarian", { description: "Start Sub-Sub in the Librarian mode", type: "boolean", default: false });
+    pi.registerFlag("researcher", { description: "Start Sub-Sub in the Researcher mode", type: "boolean", default: false });
     let mode = cfg.defaultMode;
     const benchRun = Boolean(process.env.SUBSUB_BENCH_OUT);
     const toolOpts = () => ({ profile, bench: benchRun });
@@ -220,11 +221,12 @@ export async function createSubsub(pi, deps = {}) {
         webCtx = ctx;
         emitWeb();
     }
-    async function applyMode(ctx, next, remember) {
+    /** Set the mode's tools and, unless `switchModel` is false, the mode's model. */
+    async function applyMode(ctx, next, remember, switchModel = true) {
         mode = next;
         pi.setActiveTools(toolsFor(mode, registered(), toolOpts()));
         const spec = cfg.models[mode];
-        if (spec) {
+        if (spec && switchModel) {
             const i = spec.indexOf("/");
             const model = i > 0 ? ctx.modelRegistry.find(spec.slice(0, i), spec.slice(i + 1)) : undefined;
             const ok = model ? await pi.setModel(model) : false;
@@ -243,16 +245,19 @@ export async function createSubsub(pi, deps = {}) {
             registerTools(b);
         }
         let restored;
+        let modelChosen = false; // the session already has a model: a resumed conversation keeps it
         for (const e of ctx.sessionManager.getBranch()) {
             const m = e.customType === MODE_ENTRY ? e.data?.mode : undefined;
             if (m === "librarian" || m === "researcher")
                 restored = m;
+            if (e.type === "model_change")
+                modelChosen = true;
         }
         // Judge light or dark before Sub-Sub changes the theme.
         if (lookOn(ctx))
             scheme ??= schemeFromAnsi(ctx.ui.theme.getFgAnsi("text"), ctx.ui.theme.name);
         applyTheme(ctx);
-        await applyMode(ctx, restored ?? (pi.getFlag("librarian") ? "librarian" : cfg.defaultMode), false);
+        await applyMode(ctx, restored ?? (pi.getFlag("librarian") ? "librarian" : pi.getFlag("researcher") ? "researcher" : cfg.defaultMode), false, !modelChosen);
         if (lookOn(ctx)) {
             setHeader(ctx);
             void refreshLibrary();
@@ -271,10 +276,28 @@ export async function createSubsub(pi, deps = {}) {
         bridge = undefined;
         await b?.close();
     });
+    /** 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"];
+    // /tree moves to another branch: take that branch's mode (pi restores its model itself).
+    pi.on("session_tree", async (_event, ctx) => {
+        let m;
+        for (const e of ctx.sessionManager.getBranch()) {
+            const x = e.customType === MODE_ENTRY ? e.data?.mode : undefined;
+            if (x === "librarian" || x === "researcher")
+                m = x;
+        }
+        if (m && m !== mode)
+            await applyMode(ctx, m, false, false);
+    });
     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 cmd = /^\/([\w-]+)(?:\s|$)/.exec(event.text.trim())?.[1];
+        if (mode === "librarian" && cmd && RESEARCH_PROMPTS.includes(cmd)) {
+            ctx.ui.notify(`Sub-Sub: /${cmd} is part of the Researcher. Switch with /researcher.`, "warning");
+            return { action: "handled" };
+        }
         const why = promptBlocked(event.text, profile);
         if (!why)
             return { action: "continue" };
@@ -303,6 +326,9 @@ export async function createSubsub(pi, deps = {}) {
                 return { block: true, reason: why };
             }
         }
+        if (["read", "grep", "find", "ls"].includes(name) && typeof input.path === "string" && isSecret(normalizeToolPath(input.path, ctx.cwd), name === "grep")) {
+            return { block: true, reason: "That file holds keys or passwords. Sub-Sub does not read it." };
+        }
         if (name.startsWith("verify_"))
             return verifyGate(name, input, ctx);
         const kind = benchOut && name === "scholar_queue_imports" ? "confirm" : gateKind(name, input);
@@ -453,7 +479,7 @@ export async function createSubsub(pi, deps = {}) {
             catch (err) {
                 saved = ` Not saved: ${err.message}`;
             }
-            await applyMode(ctx, mode, false);
+            await applyMode(ctx, mode, false, false);
             ctx.ui.notify(`Sub-Sub: ${profileSpec(profile).label} profile (${profileSpec(profile).summary}).${saved}`, "info");
         },
     });

package/dist/web.js

@@ -21,7 +21,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.js";
-import { expand, loadConfig, saveConfig, withStarbuck } from "./config.js";
+import { configPath, expand, loadConfig, readConfigFile, saveConfig, withStarbuck } from "./config.js";
 import { TESTED_MODELS } from "./init.js";
 import { obsidianRoot } from "./layout.js";
 import { realish, within } from "./paths.js";
@@ -300,7 +300,7 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
     const bin = join(PACKAGE_DIR, "bin", "subsub.js");
     env.PI_CODING_AGENT_DIR = agentDir; // for the session list below
     const childEnv = { ...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
     const clients = new Set();
@@ -309,7 +309,19 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
     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;
     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() {
+        const shown = subsubState?.mode;
+        if (shown === "librarian" || shown === "researcher")
+            return [`--${shown}`];
+        return opts.librarian ? ["--librarian"] : [];
+    }
+    function startAgent() {
+        agent.start([...modeArgs(), ...(lastSession && existsSync(lastSession) ? ["--session", lastSession] : [])]);
+    }
     function broadcast(ev) {
         const data = `data: ${JSON.stringify(ev)}\n\n`;
         for (const c of clients)
@@ -352,11 +364,13 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
         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() {
         const out = {
             type: "hello",
@@ -369,6 +383,7 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
         };
         try {
             out.session = await agent.request({ type: "get_state" });
+            lastSession = out.session.sessionFile ?? lastSession;
             out.messages = (await agent.request({ type: "get_messages" })).messages;
             out.commands = (await agent.request({ type: "get_commands" })).commands;
         }
@@ -387,12 +402,11 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
             .map((s) => ({ path: s.path, name: s.name ?? null, first: s.firstMessage.slice(0, 140), modified: s.modified, messages: s.messageCount }));
     }
     async function restartAgent() {
-        let sessionFile;
         try {
-            sessionFile = (await agent.request({ type: "get_state" })).sessionFile;
+            lastSession = (await agent.request({ type: "get_state" })).sessionFile ?? lastSession;
         }
         catch {
-            /* start fresh */
+            /* keep the last one known */
         }
         restarting = true;
         for (const id of dialogs.keys())
@@ -401,9 +415,23 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
         await agent.stop();
         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, change) {
+        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(() => {
@@ -545,47 +573,50 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
                     return send(res, 200, { models: Array.isArray(data) ? data : (data.models ?? []) });
                 }
                 case "POST /api/model": {
-                    if (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?.mode === "librarian" ? "librarian" : "researcher";
-                    const models = { ...(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 : typeof raw.model === "string" && raw.model ? { librarian: raw.model, researcher: raw.model } : {};
+                    const models = { ...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 () => {
+                        await agent.request({ type: "set_model", provider: String(body.provider), modelId: String(body.id) });
+                    });
                 }
                 case "POST /api/addons": {
                     // Turn an add-on on or off, then restart pi so the extension starts or stops its server.
-                    if (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)
+                    if (agent.proc || switching)
                         return send(res, 200, { ok: true });
-                    agent.start();
+                    startAgent();
                     broadcast(await snapshot());
                     return send(res, 200, { ok: true });
                 case "POST /api/login": {
-                    if (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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tiagojct/subsub",
-  "version": "0.11.0",
-  "description": "Sub-Sub: a Zotero librarian and research assistant in the browser or the terminal, built on pi",
+  "version": "0.11.1",
+  "description": "Sub-Sub: a research assistant that works from your own Zotero library, in the browser or the terminal, built on pi",
   "type": "module",
   "license": "MIT",
   "author": "Tiago Jacinto",
@@ -49,7 +49,6 @@
     "assets",
     "bin",
     "dist",
-    "docs",
     "extensions",
     "prompts",
     "roles",

package/prompts/lit-note.md

@@ -2,4 +2,4 @@
 description: "Literature note for one item"
 argument-hint: "<citekey or title words>"
 ---
-Make a literature note for $ARGUMENTS in Resources/Zotero/, following the template in the shared rules. Read the full text if it is indexed. Then offer to link it in Zotero.
+Make a literature note for $ARGUMENTS in Literature/ in the Sub-Sub folder, following the template in the shared rules. Read the full text if it is indexed. Then offer to link it in Zotero.

package/src/bench.ts

@@ -1,6 +1,6 @@
 /**
  * subsub-bench: the same tasks for several models, against the real library,
- * with no changes applied. See docs/Subsub.md ("Model test").
+ * with no changes applied. See docs/model-test.md.
  *
  *   subsub-bench prepare [--seed 7]        pick the tasks (read-only)
  *   subsub-bench run [--models a,b] [--librarian a,b] [--researcher c,d] [--parallel 3] [--only task]
@@ -79,7 +79,7 @@ export function promptFor(task: string, t: Tasks, code: string, out: string): st
 		case "lit_note":
 			return t.lit_note
 				? `Make a literature note for ${t.lit_note.citekey}, following the literature-note format in the shared rules. Read the full text. ` +
-						`This is a model test: save the note as ${join(out, `${t.lit_note.citekey}.md`)} instead of Resources/Zotero/, and do not attach anything to Zotero.`
+						`This is a model test: save the note as ${join(out, `${t.lit_note.citekey}.md`)} instead of Literature/ in the Sub-Sub folder, and do not attach anything to Zotero.`
 				: undefined;
 		case "synthesis":
 			return t.synthesis

package/src/cli.ts

@@ -134,12 +134,38 @@ export function reviewCommand(args: string[], cfg: SubsubConfig, env: NodeJS.Pro
 	};
 }
 
+const HELP = `Sub-Sub: your research assistant, working from your own Zotero library.
+
+Usage:
+  subsub                 Start Sub-Sub in the terminal
+  subsub --librarian     Start in the Librarian, which only manages the library
+  subsub web             Open Sub-Sub in the browser
+  subsub init            Set up or change the settings (folder, tag list, profile, models)
+  subsub doctor          Check the set-up; each line marked FIX says what to do
+  subsub shortcut        Add a Sub-Sub shortcut (--remove takes it away)
+  subsub review preview|apply <note>
+                         Check or apply a tag review note from Inbox/
+  subsub --version       Show the versions
+
+Options:
+  --here                 Work in the current folder, not in the Sub-Sub folder
+
+In Sub-Sub, type /subsub for the state, /researcher or /librarian to switch modes,
+/profile to change the profile, /undo to undo the last change, and / for all commands.
+Sub-Sub runs on pi: pi's options (for example --model, --resume) also work.
+
+Docs: https://subsub.tiagojacinto.eu`;
+
 export async function run(argv: string[] = process.argv.slice(2)): Promise<void> {
 	const env = process.env;
 	const home = homedir();
 	const here = argv.includes("--here");
 	const args = argv.filter((a) => a !== "--here");
 
+	if (args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
+		console.log(HELP);
+		return;
+	}
 	if (args[0] === "--version" || args[0] === "-v") {
 		const piPkg = join(dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))), "..");
 		console.log(`subsub ${packageVersion()} (pi ${packageVersion(piPkg)})`);
@@ -173,7 +199,12 @@ export async function run(argv: string[] = process.argv.slice(2)): Promise<void>
 		return;
 	}
 	if (isSelfUpdate(args)) {
-		console.log(`Sub-Sub is not updated with "update". Its code is in ${PACKAGE_DIR}; after new code arrives, run "npm install" there.`);
+		if (PACKAGE_DIR.split(/[\\/]/).includes("node_modules")) {
+			console.log("Sub-Sub is not updated with \"update\". To update it, run the installer again (https://subsub.tiagojacinto.eu/install/);");
+			console.log("if you installed it with npm, type: npm install -g @tiagojct/subsub");
+		} else {
+			console.log(`Sub-Sub is not updated with "update". Its code is in ${PACKAGE_DIR}; after new code arrives, run "npm install" there.`);
+		}
 		console.log('To update packages added to Sub-Sub, use "subsub update --extensions".');
 		process.exitCode = 1;
 		return;
@@ -206,6 +237,8 @@ export async function run(argv: string[] = process.argv.slice(2)): Promise<void>
 	env.SUBSUB_CLI = "1";
 	// pi's update notice would point to the global pi, not to this copy.
 	env.PI_SKIP_VERSION_CHECK ??= "1";
+	// pi reports a first install to pi.dev and names itself to some providers; Sub-Sub sends no usage data.
+	env.PI_TELEMETRY ??= "0";
 
 	process.argv = [process.argv[0], process.argv[1], ...args];
 	const index = fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));

package/src/config.ts

@@ -159,7 +159,9 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): SubsubConfig {
 	// "models" per mode; "model" (0.10) for both; {} or "" means: the user chooses in pi (/login, /model).
 	const one = typeof user.model === "string" ? user.model : undefined;
 	const given = user.models && typeof user.models === "object" ? (user.models as Record<string, string>) : undefined;
-	const models: Partial<Record<Mode, string>> = given ?? (one !== undefined ? { librarian: one || undefined, researcher: one || undefined } : { ...DEFAULT_MODELS });
+	// Without a settings file (no subsub init yet), the user chooses in pi: no default that may lack a key.
+	const fallback = existsSync(file) ? { ...DEFAULT_MODELS } : {};
+	const models: Partial<Record<Mode, string>> = given ?? (one !== undefined ? { librarian: one || undefined, researcher: one || undefined } : fallback);
 	for (const k of Object.keys(models) as Mode[]) if (!models[k]) delete models[k];
 	const themes = user.themes === false ? false : typeof user.themes === "string" ? user.themes : user.themes?.researcher;
 	return {

package/src/doctor.ts

@@ -123,7 +123,8 @@ export function runChecks(
 	);
 	const v = st.vocabulary ?? {};
 	if (v.loaded === false || !v.tags) {
-		out.push({ name: "Tag list", ok: false, detail: v.path ? `cannot read ${v.path}` : "not set", fix: "Type subsub init: it creates a starter tag list." });
+		const path = v.path && v.path !== "None" ? v.path : undefined; // the server writes Python's None when unset
+		out.push({ name: "Tag list", ok: false, detail: path ? `cannot read ${path}` : "not set", fix: "Type subsub init: it creates a starter tag list." });
 	} else {
 		const noTopics = Array.isArray(v.facets) && !v.facets.includes("topic");
 		out.push({

package/src/init.ts

@@ -152,8 +152,8 @@ export async function runInit(
 	// Without questions (--yes), an existing folder stays exactly as it is.
 	const keepAsIs = Boolean(flags.yes) && !flags.folder && !flags.notes && oldFolder !== undefined;
 	const folderDefault = flags.folder ?? flags.notes ?? (oldFolder ? (keepAsIs ? oldFolder : subsubFolder(oldFolder)) : join(home, "Documents", FOLDER_NAME));
-	const answer = expand((await io.ask("Sub-Sub folder (or an Obsidian vault)", folderDefault)).trim() || folderDefault, home);
-	const notes = keepAsIs && answer === oldFolder ? answer : subsubFolder(answer);
+	const answer = expand(cleanPath(await io.ask("Sub-Sub folder (or an Obsidian vault)", folderDefault)) || folderDefault, home);
+	let notes = keepAsIs && answer === oldFolder ? answer : subsubFolder(answer);
 	if (notes !== answer) io.say(`That is an Obsidian vault. Sub-Sub will use ${notes}.`);
 
 	// ---- files of the old layout
@@ -171,10 +171,16 @@ export async function runInit(
 			"Move them",
 			[
 				{ value: "yes", label: "Move them (recommended)" },
-				{ value: "no", label: from === notes ? "Leave them; Sub-Sub still reads them from Systems/" : "Leave them where they are" },
+				// In a new folder, files left behind would not be read: then "no" means keeping the old folder.
+				{ value: "no", label: from === notes ? "Leave them; Sub-Sub still reads them from Systems/" : flags.folder || flags.notes ? "Leave them where they are" : `Leave them, and keep using ${from}` },
 			],
 			flags.move ?? (flags.yes ? "no" : "yes"),
 		);
+		// A folder given on the command line (--folder, --notes) is a deliberate choice and stays.
+		if (move === "no" && from !== notes && !flags.folder && !flags.notes) {
+			notes = from;
+			io.say(`Sub-Sub keeps using ${notes}.`);
+		}
 	}
 
 	explain("Profile", "The profile sets how much Sub-Sub writes for you and which tools it offers. Change it at any time with /profile.");
@@ -207,7 +213,7 @@ export async function runInit(
 		);
 	}
 
-	explain("Contact email", "Unpaywall needs an email address to find open-access PDFs. Sub-Sub sends it only to Unpaywall, Crossref, OpenAlex and PubMed, as they ask.");
+	explain("Contact email", "Unpaywall needs an email address to find open-access PDFs. Sub-Sub sends it with its requests to PubMed, Europe PMC, OpenAlex, Crossref and Unpaywall, as they ask, and to nobody else.");
 	const email = (await io.ask("Email (optional)", flags.email ?? envValues.ZOTERO_CONTACT_EMAIL ?? "")).trim();
 
 	explain("Reference checks (Starbuck)", "An optional add-on for manuscripts: it checks that each cited work exists, matches its citation and was not retracted. Sub-Sub then has /verify.");
@@ -364,3 +370,11 @@ export async function initMain(args: string[], env: NodeJS.ProcessEnv = process.
 		(io as { close?: () => void }).close?.();
 	}
 }
+
+/** A path as typed, dragged from Finder (spaces escaped) or copied from Explorer (in quotes). */
+export function cleanPath(raw: string): string {
+	let p = raw.trim();
+	if (p.length > 1 && (p[0] === '"' || p[0] === "'") && p.at(-1) === p[0]) return p.slice(1, -1);
+	if (process.platform !== "win32") p = p.replace(/\\([ '"()&])/g, "$1");
+	return p;
+}

package/src/paths.ts

@@ -92,6 +92,27 @@ export type PathVerdict = { ok: true } | { ok: false; why: string };
 export function judgePath(target: string, policy: PathPolicy): PathVerdict {
 	const hit = policy.protectedPaths.find((p) => within(target, p));
 	if (hit) return { ok: false, why: `it changes a protected file or folder (${hit})` };
+	// Notes never live in hidden folders; .git/hooks, .obsidian/plugins or .vscode can run code.
+	const hidden = target.split(/[\\/]/).find((part) => part.startsWith(".") && part !== "." && part !== "..");
+	if (hidden) return { ok: false, why: `it is in a hidden folder or file (${hidden})` };
 	if (policy.allowed.some((a) => within(target, a))) return { ok: true };
 	return { ok: false, why: "it is outside the vault and the working folder" };
 }
+
+/** Files with keys and passwords: the model may not read them, even when you ask. */
+export function secretPaths(): string[] {
+	const home = realish(homedir());
+	return [
+		join(home, ".subsub", "agent", "auth.json"),
+		join(home, ".pi", "agent", "auth.json"),
+		join(home, ".config", "zotero-local-mcp", "env"),
+		join(home, ".ssh"),
+		join(home, ".aws"),
+		join(home, ".netrc"),
+	];
+}
+
+/** True if reading `target` would read a secret; for grep, also a folder that holds one. */
+export function isSecret(target: string, recursive = false): boolean {
+	return secretPaths().some((p) => within(target, p) || (recursive && within(p, target)));
+}

package/src/prompt.ts

@@ -60,6 +60,12 @@ export function roleText(mode: Mode, cfg?: Pick<SubsubConfig, "userName" | "abou
 export function systemAddition(mode: Mode, cfg: SubsubConfig, cwd: string): string {
 	const user = who(cfg);
 	const parts = [`# Sub-Sub: ${mode === "librarian" ? "Librarian" : "Researcher"} mode`, roleText(mode, cfg)];
+	if (cfg.vault) {
+		parts.push(
+			"# The Sub-Sub folder",
+			`The Sub-Sub folder is ${cfg.vault}. Folder names in these instructions (Inbox/, Literature/, Syntheses/, Research/, Zotero/) are inside it. Write notes there with absolute paths, even when the working folder is somewhere else.`,
+		);
+	}
 	const shared = readIf(cfg.sharedRules);
 	if (shared) {
 		parts.push(

package/src/shortcut.ts

@@ -81,7 +81,7 @@ export function desktopEntry(p: ShortcutPlan): string {
 		"[Desktop Entry]",
 		"Type=Application",
 		"Name=Sub-Sub",
-		"Comment=Zotero librarian and research assistant",
+		"Comment=Research assistant for your Zotero library",
 		`Exec=${desktopQuote(p.node)} ${desktopQuote(p.bin)} web`,
 		`Path=${p.home}`,
 		`Icon=${join(p.packageDir, "assets", "icon.png")}`,
@@ -103,7 +103,7 @@ export function windowsScript(p: ShortcutPlan): string {
 		`  $s.Arguments = ${psQuote(`"${p.bin}" web`)}`,
 		`  $s.WorkingDirectory = ${psQuote(p.home)}`,
 		`  $s.IconLocation = ${psQuote(join(p.packageDir, "assets", "icon.ico"))}`,
-		"  $s.Description = 'Sub-Sub: Zotero librarian and research assistant'",
+		"  $s.Description = 'Sub-Sub: research assistant for your Zotero library'",
 		"  $s.WindowStyle = 7",
 		"  $s.Save()",
 		"  Write-Output (Join-Path $dir 'Sub-Sub.lnk')",

package/src/subsub.ts

@@ -1,5 +1,5 @@
 /**
- * Sub-Sub: a Zotero librarian and research assistant for pi.
+ * Sub-Sub: a research assistant for pi that works from your own Zotero library.
  *
  * - Two modes: the Librarian manages the library (Zotero tools only); the
  *   Researcher does the same and also searches PubMed, Europe PMC and OpenAlex
@@ -39,7 +39,7 @@ import {
 import { profileList, profileSpec, promptBlocked } from "./profiles.ts";
 import { coerceArgs, loosenArrays, resolvePathArgs } from "./args.ts";
 import { applyEdits, checkLiteratureNote } from "./notes.ts";
-import { buildPolicy, judgePath, normalizeToolPath, realish, within } from "./paths.ts";
+import { buildPolicy, isSecret, judgePath, normalizeToolPath, realish, within } from "./paths.ts";
 import { describeArgs, formatPreview } from "./preview.ts";
 import { headerLines, type LibraryState, paintPreview, QUOTES, type Scheme, schemeFromAnsi, themeName } from "./look.ts";
 import { systemAddition } from "./prompt.ts";
@@ -130,6 +130,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	if (deps.bridge) registerTools(deps.bridge);
 
 	pi.registerFlag("librarian", { description: "Start Sub-Sub in the Librarian mode", type: "boolean", default: false });
+	pi.registerFlag("researcher", { description: "Start Sub-Sub in the Researcher mode", type: "boolean", default: false });
 
 	let mode: Mode = cfg.defaultMode;
 	const benchRun = Boolean(process.env.SUBSUB_BENCH_OUT);
@@ -252,11 +253,12 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		emitWeb();
 	}
 
-	async function applyMode(ctx: ExtensionContext, next: Mode, remember: boolean): Promise<void> {
+	/** Set the mode's tools and, unless `switchModel` is false, the mode's model. */
+	async function applyMode(ctx: ExtensionContext, next: Mode, remember: boolean, switchModel = true): Promise<void> {
 		mode = next;
 		pi.setActiveTools(toolsFor(mode, registered(), toolOpts()));
 		const spec = cfg.models[mode];
-		if (spec) {
+		if (spec && switchModel) {
 			const i = spec.indexOf("/");
 			const model = i > 0 ? ctx.modelRegistry.find(spec.slice(0, i), spec.slice(i + 1)) : undefined;
 			const ok = model ? await pi.setModel(model) : false;
@@ -274,14 +276,16 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 			registerTools(b);
 		}
 		let restored: Mode | undefined;
-		for (const e of ctx.sessionManager.getBranch() as Array<{ customType?: string; data?: { mode?: unknown } }>) {
+		let modelChosen = false; // the session already has a model: a resumed conversation keeps it
+		for (const e of ctx.sessionManager.getBranch() as Array<{ type?: string; customType?: string; data?: { mode?: unknown } }>) {
 			const m = e.customType === MODE_ENTRY ? e.data?.mode : undefined;
 			if (m === "librarian" || m === "researcher") restored = m;
+			if (e.type === "model_change") modelChosen = true;
 		}
 		// Judge light or dark before Sub-Sub changes the theme.
 		if (lookOn(ctx)) scheme ??= schemeFromAnsi(ctx.ui.theme.getFgAnsi("text"), ctx.ui.theme.name);
 		applyTheme(ctx);
-		await applyMode(ctx, restored ?? (pi.getFlag("librarian") ? "librarian" : cfg.defaultMode), false);
+		await applyMode(ctx, restored ?? (pi.getFlag("librarian") ? "librarian" : pi.getFlag("researcher") ? "researcher" : cfg.defaultMode), false, !modelChosen);
 		if (lookOn(ctx)) {
 			setHeader(ctx);
 			void refreshLibrary();
@@ -300,11 +304,29 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		await b?.close();
 	});
 
+	/** 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"];
+
+	// /tree moves to another branch: take that branch's mode (pi restores its model itself).
+	pi.on("session_tree", async (_event, ctx) => {
+		let m: Mode | undefined;
+		for (const e of ctx.sessionManager.getBranch() as Array<{ customType?: string; data?: { mode?: unknown } }>) {
+			const x = e.customType === MODE_ENTRY ? e.data?.mode : undefined;
+			if (x === "librarian" || x === "researcher") m = x;
+		}
+		if (m && m !== mode) await applyMode(ctx, m, false, false);
+	});
+
 	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 cmd = /^\/([\w-]+)(?:\s|$)/.exec(event.text.trim())?.[1];
+		if (mode === "librarian" && cmd && RESEARCH_PROMPTS.includes(cmd)) {
+			ctx.ui.notify(`Sub-Sub: /${cmd} is part of the Researcher. Switch with /researcher.`, "warning");
+			return { action: "handled" };
+		}
 		const why = promptBlocked(event.text, profile);
 		if (!why) return { action: "continue" };
 		ctx.ui.notify(`Sub-Sub: ${why}`, "warning");
@@ -333,6 +355,9 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 				return { block: true, reason: why };
 			}
 		}
+		if (["read", "grep", "find", "ls"].includes(name) && typeof input.path === "string" && isSecret(normalizeToolPath(input.path, ctx.cwd), name === "grep")) {
+			return { block: true, reason: "That file holds keys or passwords. Sub-Sub does not read it." };
+		}
 		if (name.startsWith("verify_")) return verifyGate(name, input, ctx);
 		const kind = benchOut && name === "scholar_queue_imports" ? "confirm" : gateKind(name, input);
 		if (!kind) return undefined;
@@ -476,7 +501,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 			} catch (err) {
 				saved = ` Not saved: ${(err as Error).message}`;
 			}
-			await applyMode(ctx, mode, false);
+			await applyMode(ctx, mode, false, false);
 			ctx.ui.notify(`Sub-Sub: ${profileSpec(profile).label} profile (${profileSpec(profile).summary}).${saved}`, "info");
 		},
 	});