@tiagojct/subsub 0.5.0

package/dist/roles.js

@@ -0,0 +1,73 @@
+/**
+ * Which tools each mode may use, and which calls need the user's approval.
+ */
+import { profileSpec } from "./profiles.js";
+export const FILE_TOOLS = ["read", "edit", "write", "grep", "find", "ls"];
+export const ZOTERO_READ = [
+    "status",
+    "library_overview",
+    "find_items",
+    "get_item",
+    "get_fulltext",
+    "list_tags",
+    "get_vocabulary",
+    "list_collections",
+    "history",
+].map((n) => `zotero_${n}`);
+/** Write tools that support dry_run: the gate previews them and asks. */
+export const PREVIEW_WRITES = new Set([
+    ...[
+        "tag_items",
+        "apply_tag_review",
+        "rename_tags",
+        "remove_tags",
+        "remove_automatic_tags",
+        "set_citekeys",
+        "update_fields",
+        "file_items",
+        "create_collection",
+        "create_note",
+        "trash_items",
+        "undo",
+        "import_identifiers",
+        "import_queue",
+        "repair_metadata",
+        "attach_oa_pdfs",
+    ].map((n) => `zotero_${n}`),
+    "scholar_attach_note",
+]);
+/** Writes without a dry run that still need a yes. */
+export const CONFIRM_WRITES = new Set(["scholar_export_bibliography"]);
+export function toolsFor(mode, registered, profile = "editor") {
+    const has = new Set(registered);
+    const without = new Set(profileSpec(profile).without);
+    const wanted = mode === "librarian"
+        ? [...registered.filter((n) => n.startsWith("zotero_")), ...FILE_TOOLS]
+        : [...ZOTERO_READ, ...registered.filter((n) => n.startsWith("scholar_")), ...FILE_TOOLS];
+    return [...new Set(wanted)].filter((n) => has.has(n) && !without.has(n));
+}
+/** Why a Sub-Sub tool is not available now, or undefined when it is. */
+export function unavailableReason(name, mode, registered, profile) {
+    if (toolsFor(mode, registered, profile).includes(name))
+        return undefined;
+    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.`;
+    }
+    return `${name} is not available in ${mode} mode. The user can switch with /${otherMode(mode)}.`;
+}
+/** A dry run only when dry_run is absent (server default true) or clearly true. */
+export function isDryRun(value) {
+    return value === undefined || value === true || value === "true";
+}
+export function gateKind(toolName, input) {
+    if (PREVIEW_WRITES.has(toolName))
+        return isDryRun(input.dry_run) ? null : "preview";
+    if (CONFIRM_WRITES.has(toolName))
+        return "confirm";
+    if (toolName === "write" || toolName === "edit")
+        return "path";
+    return null;
+}
+export function otherMode(mode) {
+    return mode === "librarian" ? "researcher" : "librarian";
+}

package/dist/subsub.js

@@ -0,0 +1,414 @@
+/**
+ * Sub-Sub: a Zotero librarian and research assistant for pi.
+ *
+ * - Two modes with different tool sets: librarian (changes the library, no web)
+ *   and researcher (reads the library, searches PubMed/OpenAlex, writes vault notes).
+ * - 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.
+ *
+ * The Python servers start in session_start (not in the factory) and stop in
+ * session_shutdown. Tools are registered once and use the current bridge.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Bridge } from "./bridge.js";
+import { expand, findUv, isProfile, loadConfig, saveConfig, serverCommand, who } from "./config.js";
+import { profileList, profileSpec } from "./profiles.js";
+import { coerceArgs, loosenArrays } from "./args.js";
+import { buildPolicy, judgePath, normalizeToolPath, realish, within } from "./paths.js";
+import { describeArgs, formatPreview } from "./preview.js";
+import { headerLines, paintPreview, QUOTES, schemeFromAnsi, themeName } from "./look.js";
+import { systemAddition } from "./prompt.js";
+import { gateKind, toolsFor, unavailableReason } from "./roles.js";
+const PACKAGE_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
+const MODE_ENTRY = "subsub-mode";
+const BENCH_ENTRY = "subsub-bench";
+function ownVersion() {
+    try {
+        return JSON.parse(readFileSync(join(PACKAGE_DIR, "package.json"), "utf8")).version ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+export { findUv };
+export function serverSpecs(cfg) {
+    const env = cfg.envFile ? { ZOTERO_MCP_ENV: cfg.envFile } : {};
+    return [
+        { name: "zotero", ...serverCommand(cfg, "zotero-local-mcp"), env },
+        { name: "scholar", ...serverCommand(cfg, "zotero-scholar-mcp"), env },
+    ];
+}
+export async function createSubsub(pi, deps = {}) {
+    const cfg = deps.config ?? loadConfig();
+    let bridge = deps.bridge;
+    const toolNames = new Set();
+    /** Original input schemas, to turn "[...]" strings back into lists. */
+    const schemas = new Map();
+    function current() {
+        if (!bridge)
+            throw new Error("The Zotero servers are not running. Try /reload.");
+        return bridge;
+    }
+    function registerTools(b) {
+        for (const t of b.tools) {
+            if (toolNames.has(t.fullName))
+                continue;
+            toolNames.add(t.fullName);
+            schemas.set(t.fullName, t.inputSchema);
+            pi.registerTool({
+                name: t.fullName,
+                label: `${t.server} ${t.name}`,
+                description: t.description,
+                parameters: loosenArrays(t.inputSchema),
+                // One at a time, so a preview always sees the effect of earlier calls in the same message.
+                executionMode: "sequential",
+                async execute(_id, params, signal) {
+                    const args = coerceArgs(t.inputSchema, { ...(params ?? {}) });
+                    const res = await current().call(t.fullName, args, signal);
+                    if (res.isError)
+                        throw new Error(res.text || `${t.fullName} failed`);
+                    return { content: [{ type: "text", text: res.text }], details: { tool: t.fullName } };
+                },
+            });
+        }
+    }
+    if (deps.bridge)
+        registerTools(deps.bridge);
+    pi.registerFlag("librarian", { description: "Start Sub-Sub in librarian mode", type: "boolean", default: false });
+    let mode = cfg.defaultMode;
+    let profile = cfg.profile;
+    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";
+    const registered = () => pi.getAllTools().map((t) => t.name);
+    // ---- look (only for the `subsub` command in the terminal UI)
+    let scheme;
+    let modelId = "no model";
+    let headerTui;
+    const library = { zotero: "checking" };
+    const quote = cfg.quotes === false ? undefined : QUOTES[Math.floor(Math.random() * QUOTES.length)];
+    const lookOn = (ctx) => standalone && cfg.look !== false && ctx.mode === "tui";
+    function applyTheme(ctx) {
+        if (!lookOn(ctx) || cfg.themes === false)
+            return;
+        scheme ??= schemeFromAnsi(ctx.ui.theme.getFgAnsi("text"), ctx.ui.theme.name);
+        const name = themeName(mode, scheme, cfg.themes);
+        const theme = name ? ctx.ui.getTheme(name) : undefined;
+        // A Theme object (not a name) changes the theme for this run only; the saved setting stays.
+        if (theme)
+            ctx.ui.setTheme(theme);
+    }
+    function paintFor(ctx) {
+        return (text) => ctx.mode === "tui"
+            ? paintPreview(text, (x) => ctx.ui.theme.fg("success", x), (x) => ctx.ui.theme.fg("error", x), (x) => ctx.ui.theme.fg("text", x))
+            : text;
+    }
+    async function refreshLibrary() {
+        try {
+            const st = await current().call("zotero_status", {});
+            const d = (st.data ?? {});
+            if (d.zotero !== "reachable") {
+                Object.assign(library, { zotero: "down", error: String(d.error ?? "") });
+            }
+            else {
+                const ov = await current().call("zotero_library_overview", {});
+                const o = (ov.data ?? {});
+                Object.assign(library, { zotero: "reachable", items: o.items, toReview: o.awaiting_review });
+            }
+        }
+        catch {
+            library.zotero = "down";
+        }
+        headerTui?.requestRender();
+    }
+    function setHeader(ctx) {
+        if (!lookOn(ctx))
+            return;
+        const version = ownVersion();
+        ctx.ui.setHeader((tui) => {
+            headerTui = tui;
+            return {
+                render: (width) => {
+                    const th = ctx.ui.theme;
+                    return headerLines({
+                        version,
+                        mode,
+                        profile: profileSpec(profile).label,
+                        model: modelId,
+                        library,
+                        quote,
+                        width,
+                        paint: {
+                            mark: (x) => th.fg("accent", x),
+                            text: (x) => th.fg("text", x),
+                            muted: (x) => th.fg("muted", x),
+                            dim: (x) => th.fg("dim", x),
+                            warn: (x) => th.fg("warning", x),
+                        },
+                    });
+                },
+                invalidate() { },
+            };
+        });
+    }
+    function status(ctx) {
+        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(", ")}` : ""}`);
+        if (standalone)
+            ctx.ui.setTitle(`Sub-Sub: ${mode}`);
+        headerTui?.requestRender();
+    }
+    async function applyMode(ctx, next, remember) {
+        mode = next;
+        pi.setActiveTools(toolsFor(mode, registered(), profile));
+        const spec = cfg.models[mode];
+        if (spec) {
+            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;
+            if (!ok)
+                ctx.ui.notify(`Sub-Sub: cannot use ${spec} (unknown model or no key); keeping the current model.`, "warning");
+        }
+        if (remember)
+            pi.appendEntry(MODE_ENTRY, { mode });
+        applyTheme(ctx);
+        status(ctx);
+    }
+    pi.on("session_start", async (_event, ctx) => {
+        if (!bridge) {
+            const b = new Bridge();
+            await b.start(deps.specs ?? serverSpecs(cfg), cfg.startTimeout * 1000);
+            bridge = b;
+            registerTools(b);
+        }
+        let restored;
+        for (const e of ctx.sessionManager.getBranch()) {
+            const m = e.customType === MODE_ENTRY ? e.data?.mode : undefined;
+            if (m === "librarian" || m === "researcher")
+                restored = m;
+        }
+        // Judge light or dark before Sub-Sub changes the theme.
+        if (lookOn(ctx))
+            scheme ??= schemeFromAnsi(ctx.ui.theme.getFgAnsi("text"), ctx.ui.theme.name);
+        await applyMode(ctx, restored ?? (pi.getFlag("librarian") ? "librarian" : cfg.defaultMode), false);
+        if (lookOn(ctx)) {
+            setHeader(ctx);
+            void refreshLibrary();
+        }
+        for (const [name, err] of Object.entries(bridge.errors)) {
+            ctx.ui.notify(`Sub-Sub: the ${name} server did not start: ${err.split("\n")[0]}`, "error");
+        }
+    });
+    pi.on("session_shutdown", async () => {
+        if (deps.bridge)
+            return;
+        const b = bridge;
+        bridge = undefined;
+        await b?.close();
+    });
+    pi.on("model_select", async (_event, ctx) => status(ctx));
+    pi.on("before_agent_start", async (event, ctx) => ({
+        systemPrompt: `${event.systemPrompt}\n\n${systemAddition(mode, { ...cfg, profile }, ctx.cwd)}`,
+    }));
+    /** Model test (subsub-bench): record every change instead of asking, and apply none. */
+    const benchOut = process.env.SUBSUB_BENCH_OUT ? expand(process.env.SUBSUB_BENCH_OUT) : undefined;
+    const record = (data) => pi.appendEntry(BENCH_ENTRY, data);
+    pi.on("tool_call", async (event, ctx) => {
+        const name = event.toolName;
+        const input = (event.input ?? {});
+        // Previews and the real call must see the same, repaired arguments.
+        const schema = schemas.get(name);
+        if (schema)
+            coerceArgs(schema, input);
+        if (name.startsWith("zotero_") || name.startsWith("scholar_")) {
+            const why = unavailableReason(name, mode, registered(), profile);
+            if (why) {
+                if (benchOut)
+                    record({ kind: "wrong_mode", tool: name, input });
+                return { block: true, reason: why };
+            }
+        }
+        const kind = benchOut && name === "scholar_queue_imports" ? "confirm" : gateKind(name, input);
+        if (!kind)
+            return undefined;
+        if (benchOut)
+            return benchGate(name, input, kind, ctx.cwd, ctx.signal);
+        if (kind === "path") {
+            const target = normalizeToolPath(String(input.path ?? ""), ctx.cwd);
+            const verdict = judgePath(target, buildPolicy({ vault: cfg.vault, cwd: ctx.cwd, serverDir: cfg.serverDir, packageDir: PACKAGE_DIR }));
+            if (verdict.ok)
+                return undefined;
+            if (!ctx.hasUI)
+                return { block: true, reason: `Writing ${target} needs ${user}'s approval: ${verdict.why}.` };
+            const ok = await ctx.ui.confirm(`Sub-Sub: ${name} ${target}?`, `Asking because ${verdict.why}.`);
+            return ok ? undefined : { block: true, reason: `${user} did not allow writing to that file.` };
+        }
+        if (!ctx.hasUI) {
+            return { block: true, reason: `Library changes need ${user}'s approval, which needs an interactive session.` };
+        }
+        if (kind === "confirm") {
+            const ok = await ctx.ui.confirm(`Sub-Sub: run ${name}?`, describeArgs(input));
+            return ok ? undefined : { block: true, reason: `${user} did not approve. Ask what to change.` };
+        }
+        // kind === "preview": the server computes the change first, then the user decides.
+        // Normalise dry_run so that what runs is exactly what was previewed and approved.
+        input.dry_run = false;
+        let preview;
+        try {
+            preview = await current().call(name, { ...input, dry_run: true }, ctx.signal);
+        }
+        catch (err) {
+            return { block: true, reason: `Preview failed: ${err.message}` };
+        }
+        if (preview.isError)
+            return { block: true, reason: preview.text };
+        const ok = await ctx.ui.confirm(`Sub-Sub: apply ${name.replace(/^(zotero|scholar)_/, "")}?`, paintFor(ctx)(formatPreview(name, preview.data ?? preview.text)));
+        return ok ? undefined : { block: true, reason: `${user} did not approve this change. Ask what to change; do not retry the same call.` };
+    });
+    async function benchGate(name, input, kind, cwd, signal) {
+        if (kind === "path") {
+            const target = normalizeToolPath(String(input.path ?? ""), cwd);
+            if (within(target, realish(benchOut)))
+                return undefined;
+            record({ kind: "path_blocked", tool: name, path: target });
+            return { block: true, reason: `Model test: write only inside ${benchOut}.` };
+        }
+        let preview;
+        if (kind === "preview") {
+            try {
+                const p = await current().call(name, { ...input, dry_run: true }, signal);
+                preview = p.isError ? { error: p.text } : (p.data ?? p.text);
+            }
+            catch (err) {
+                preview = { error: err.message };
+            }
+        }
+        record({ kind: "change", tool: name, input, preview });
+        const shown = preview === undefined ? "" : ` What the change would do (server preview): ${JSON.stringify(preview).slice(0, 4000)}`;
+        return {
+            block: true,
+            reason: "Model test: this change was recorded and not applied. Continue as if it had been applied: make any other " +
+                "changes the task needs, do not repeat this call, do not ask for approval, and finish with a short summary " +
+                `for ${user}.${shown}`,
+        };
+    }
+    pi.registerCommand("librarian", {
+        description: "Sub-Sub: switch to the librarian (changes the library, no web)",
+        handler: async (_args, ctx) => {
+            await applyMode(ctx, "librarian", true);
+            ctx.ui.notify("Sub-Sub: librarian mode", "info");
+        },
+    });
+    pi.registerCommand("researcher", {
+        description: "Sub-Sub: switch to the researcher (search, notes; library read-only)",
+        handler: async (_args, ctx) => {
+            await applyMode(ctx, "researcher", true);
+            ctx.ui.notify("Sub-Sub: researcher mode", "info");
+        },
+    });
+    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.message}`;
+            }
+            await applyMode(ctx, mode, 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"}.`];
+            if (!bridge) {
+                ctx.ui.notify(`${lines[0]}\nThe Zotero servers are not running. Try /reload.`, "warning");
+                return;
+            }
+            for (const [name, err] of Object.entries(bridge.errors))
+                lines.push(`${name} server not running: ${err.split("\n")[0]}`);
+            if (bridge.has("zotero_status")) {
+                const st = await bridge.call("zotero_status", {});
+                const d = (st.data ?? {});
+                lines.push(`Zotero: ${d.zotero ?? "?"}${d.error ? ` (${d.error})` : ""}. Write key remembered: ${d.write_key_remembered ?? "?"}.`);
+                library.zotero = d.zotero === "reachable" ? "reachable" : "down";
+                if (d.zotero === "reachable") {
+                    const ov = await bridge.call("zotero_library_overview", {});
+                    const o = (ov.data ?? {});
+                    if (!ov.isError)
+                        Object.assign(library, { items: o.items, toReview: o.awaiting_review });
+                    lines.push(ov.isError
+                        ? ov.text
+                        : `Items: ${o.items}. Without tags: ${o.without_manual_tags}. Missing facets: ${JSON.stringify(o.missing_facet)}. Awaiting review (_agent): ${o.awaiting_review}.`);
+                }
+            }
+            headerTui?.requestRender();
+            ctx.ui.notify(lines.join("\n"), "info");
+        },
+    });
+    pi.registerCommand("history", {
+        description: "Sub-Sub: recent library changes",
+        handler: async (_args, ctx) => {
+            let res;
+            try {
+                res = await current().call("zotero_history", { limit: 10 });
+            }
+            catch (err) {
+                ctx.ui.notify(err.message, "warning");
+                return;
+            }
+            if (res.isError) {
+                ctx.ui.notify(res.text, "warning");
+                return;
+            }
+            const rows = res.data ?? [];
+            const text = rows.length
+                ? rows.map((r) => `${r.id}  ${r.op}  ${r.items} item(s)${r.fully_undone ? "  (undone)" : ""}`).join("\n")
+                : "No changes yet.";
+            ctx.ui.notify(text, "info");
+        },
+    });
+    pi.registerCommand("undo", {
+        description: "Sub-Sub: revert the last library change (asks first)",
+        handler: async (args, ctx) => {
+            const input = args.trim() ? { journal_id: args.trim() } : {};
+            let preview;
+            try {
+                preview = await current().call("zotero_undo", { ...input, dry_run: true });
+            }
+            catch (err) {
+                ctx.ui.notify(err.message, "warning");
+                return;
+            }
+            if (preview.isError) {
+                ctx.ui.notify(preview.text, "warning");
+                return;
+            }
+            const ok = await ctx.ui.confirm("Sub-Sub: undo?", paintFor(ctx)(formatPreview("zotero_undo", preview.data)));
+            if (!ok)
+                return;
+            const res = await current().call("zotero_undo", { ...input, dry_run: false });
+            const d = (res.data ?? {});
+            ctx.ui.notify(res.isError ? res.text : `Undone: ${d.applied} item(s).`, res.isError ? "error" : "info");
+        },
+    });
+}

package/docs/Subsub.md

@@ -0,0 +1,126 @@
+Sub-Sub is a Zotero librarian and research assistant that runs in pi. It uses the same Python servers as the OpenCode setup ([[Zotero MCP]]), so the library safety is the same: previews, version checks, journal and undo, the tag vocabulary. The OpenCode setup keeps working in parallel.
+
+- 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/opencode/zotero.env (same file as OpenCode)
+- Models: librarian opencode-go/glm-5.3-flash, researcher opencode-go/mimo-v2.6-pro
+- Public docs: the README in ~/Projects/subsub (source for subsub.tiagojacinto.eu)
+
+## Differences from the OpenCode setup
+
+- 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 researcher does not have the library write tools at all. It can only add a linked note (with a dialog) and add works to the import queue.
+- bash is off in both modes. File writes outside the vault, 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 already has your OpenCode Go key, Sub-Sub uses the same key. If not, 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 mimo-v2.6-pro.
+7. Type `subsub init` once. Keep the notes folder (the vault), 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 vault. 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 mode. To start in the librarian mode, type `subsub --librarian`.
+4. To change the mode, type `/librarian` or `/researcher`. The mode also changes the model.
+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):
+
+- Librarian: `/tag-batch [size]`, `/clean-tags`, `/import-queue [note path]`
+- Researcher: `/lit-note <citekey>`, `/synthesis <topic>`, `/gaps <topic>`, `/manuscript <path>`, `/alert`
+
+## 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. The full librarian.
+- 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
+
+The librarian 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 the librarian 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. Each mode has its own theme: try-works for the librarian, Glauca for the researcher, in the dark or light version that matches your terminal. 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 vault.
+
+Tasks:
+
+- Librarian: 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.
+- Researcher: 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`: `--librarian a,b` and `--researcher c,d` (OpenCode Go model ids), `--only tagging,import`, `--parallel 3`, `--timeout 900`.
+
+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 "not available in researcher mode": type `/librarian`.
+- `subsub review` says "No note matches": check the note numbers in Inbox/. A path is written from the vault 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.

package/extensions/subsub.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createSubsub } from "../src/subsub.ts";
+
+export default async function subsub(pi: ExtensionAPI): Promise<void> {
+	await createSubsub(pi);
+}