@tiagojct/subsub 0.11.3 → 0.12.0

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changes
+
+Sub-Sub follows the version numbers of npm: a change in the second number (0.12) can change how you use it; a change in the third (0.12.1) only fixes. Until the pilot results are in, new versions are fixes only, apart from changes that the pilot asks for.
+
+## 0.12.0 (2026-10-07)
+
+For new users:
+
+- `subsub init` asks whether you are a student. Students start with the Reader profile: Sub-Sub helps them read and does not write summaries or syntheses unless asked.
+- The installers end with `subsub doctor`, which also downloads the Zotero server, so the first start is quicker.
+- The browser view shows what is still missing on the first start (Zotero, a model, the servers), each with its fix.
+- A tested EU option: Mistral, with servers in the European Union. The key form says where each provider processes your data.
+
+Library changes:
+
+- Every applied change has an Undo button in the browser view. It previews first, like `/undo`.
+- New collections are journaled too: undo moves them to the Zotero trash. (Zotero server 0.5.4.)
+- A preview of more than 10 items starts with a summary: each tag and field, and how many items it changes.
+- Previews, approvals and notices are in European Portuguese when the language is Portuguese.
+
+Free tiers and errors:
+
+- After a per-minute limit (Google's free tier), Sub-Sub waits as long as the provider says and continues the task, up to three times. pi does not retry these errors, because their text mentions billing.
+
+For the pilot:
+
+- An optional usage log, kept on your computer (`subsub usage`): times, counts, commands and tool names, never what you wrote. It is off unless you turn it on in `subsub init`.
+- The pilot page has a task that compares the same work with and without Sub-Sub.
+
+Robustness:
+
+- Sub-Sub accepts pi patch releases only (~1.0.4). A weekly test runs against pi's latest release, so a change in pi shows before users meet it.
+- Randomised tests of the path gate: 3000 spellings of paths (dot segments, case, accents, links) must agree with the rules.
+
+Models page: the limits of the tests come first. Most tested models are adequate; the table is not a ranking.
+
+## 0.11.4 (2026-10-07)
+
+- A free way to try Sub-Sub: Google AI Studio, with gemini-3.1-flash-lite in both modes (`subsub init`, or the model dialog).
+- Model dialog: search, and the tested models first, marked.
+- Provider errors in plain words: limit reached, provider busy, reply blocked, key refused.
+
+## 0.11.3 (2026-10-07)
+
+- `subsub init` asks about the FMUP set-up after the folder.
+- Created notes keep raw HTML as text; the preview shows the whole note (Zotero server 0.5.3).
+
+## 0.11.2 (2026-10-07)
+
+- The mode's model is applied again at start (a regression in 0.11.1).
+- After Yes, the preview is computed again; if the library changed meanwhile, the new preview is shown first.
+- Case and Unicode spellings no longer get round protected and key files.
+
+## 0.11.1 (2026-10-07)
+
+- Writes into hidden folders always ask; the model cannot read files with keys.
+- pi's install report is off.
+
+## 0.11.0 (2026-10-06)
+
+- Two modes again: the Librarian manages the library; the Researcher does that and the research.
+- Defaults from the October model test: mimo-v2.6-flash for the Librarian, mimo-v2.6-pro for the Researcher.
+
+Earlier versions: see the git history.

package/README.md

@@ -26,12 +26,12 @@ Every library change works the same way in both modes:
 
 - The Zotero server computes the change first. Sub-Sub shows it to you (added tags in green, removed tags in red) and applies it only when you select Yes. The check is in the program, so the model cannot skip it.
 - If you edit an item in Zotero while the preview is open, Sub-Sub shows you the new preview before it changes anything. Each change also sends the item's version, so a field you edit at the moment of writing is not overwritten.
-- Every change to an item is journaled. `/undo` reverts it. (A new collection is not; remove it in Zotero if you do not want it.)
+- Every change is journaled, including new collections. `/undo` reverts the last one, and the browser view shows an Undo button under each change.
 - Nothing is deleted: items go to the Zotero trash. Only tags from your tag list can be added.
 
 ## Profiles
 
-The profile sets how much Sub-Sub writes for you and which tools it offers. Choose it in `subsub init`, or change it with `/profile`.
+The profile sets how much Sub-Sub writes for you and which tools it offers. Choose it in `subsub init`, or change it with `/profile`. Students start with Reader.
 
 | Profile | What Sub-Sub does |
 |---|---|
@@ -46,7 +46,7 @@ The [Profiles page](https://subsub.tiagojacinto.eu/profiles/) lists the tools an
 
 - Zotero 10 or later, running, with Settings > Advanced > "Allow other applications on this computer to communicate with Zotero" on.
 - Node.js 22.19 or later, and [uv](https://docs.astral.sh/uv/). The installers add both if they are missing.
-- An account with a model provider that pi supports (for example OpenCode Go, OpenRouter, Anthropic, OpenAI, Mistral, Google), or a local model.
+- An account with a model provider that pi supports (for example OpenCode Go, OpenRouter, Anthropic, OpenAI, Mistral, Google), or a local model. To try Sub-Sub without paying, a free Google AI Studio key is enough (see [Use Sub-Sub for free](https://subsub.tiagojacinto.eu/models/#use-sub-sub-for-free)).
 - macOS, Linux or Windows.
 
 ## Install
@@ -129,13 +129,14 @@ subsub review apply 13-31
 
 | Setting | Meaning | Default |
 |---|---|---|
-| `profile` | `reader`, `scholar`, `author` or `editor` | `scholar` |
+| `profile` | `reader`, `scholar`, `author` or `editor` | `reader` for students, `scholar` for others (`subsub init` asks) |
 | `userName`, `about` | Your name and one line about you, for the replies | none |
 | `language` | Language of replies and notes, or `auto` for the language you write in | `English` |
 | `vault` | The Sub-Sub folder | from the server settings |
-| `models` | The model for each mode, as provider/id: `{"librarian": "...", "researcher": "..."}`. `{}` means you choose in Sub-Sub | `opencode-go/mimo-v2.6-flash` and `opencode-go/mimo-v2.6-pro` |
+| `models` | The model for each mode, as provider/id: `{"librarian": "...", "researcher": "..."}`. `{}` means you choose in Sub-Sub. The free choice in `subsub init` sets `google/gemini-3.1-flash-lite` for both | `opencode-go/mimo-v2.6-flash` and `opencode-go/mimo-v2.6-pro` |
 | `defaultMode` | `researcher` or `librarian` | `researcher` |
 | `addons` | `["starbuck"]` adds reference checks | `[]` |
+| `usageLog` | `true` keeps the pilot's usage log on this computer (`subsub usage`) | off |
 | `serverDir` | A local copy of zotero-local-mcp, for development | the PyPI release |
 | `starbuckDir` | A local copy of Starbuck, for development | the pinned release |
 | `look`, `quotes`, `themes` | The terminal header, the Moby-Dick quotations, and the terminal colours (`subsub-glauca`, `subsub-try-works`, or `false` for your pi theme) | on, on, `subsub-glauca` |
@@ -172,6 +173,10 @@ npm run build
 
 End-to-end tests (real pi and Python servers, a fake Zotero, a scripted model): `ZLM_DIR=/path/to/zotero-local-mcp npm run test:e2e`.
 
+## Changes
+
+See [CHANGELOG.md](CHANGELOG.md).
+
 ## Licence
 
 [MIT](LICENSE), Tiago Jacinto. The `/lit`, `/compare` and `/review` prompts adapt text from [Feynman](https://github.com/Companion-Inc/feynman) (MIT); see [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES). IBM Plex fonts: SIL Open Font License.

package/dist/bench.js

@@ -13,7 +13,7 @@
  * writes are allowed only in the run folder.
  */
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { expand, loadConfig, starbuckCommand, starbuckEnabled } from "./config.js";
@@ -80,7 +80,10 @@ export function promptFor(task, t, code, out) {
 const KEEP = new Set(["tool_execution_start", "tool_execution_end", "message_end", "entry_appended", "agent_end", "agent_settled", "auto_retry_start", "extension_error"]);
 export function runOne(opts) {
     mkdirSync(opts.out, { recursive: true });
-    const args = ["--mode", "rpc", "--no-session", "--provider", opts.provider ?? "opencode-go", "--model", opts.model];
+    // "google/gemini-x" or "openrouter/vendor/model:free" name their provider; a bare name is OpenCode Go.
+    const slash = opts.model.indexOf("/");
+    const [provider, model] = slash > 0 && !opts.provider ? [opts.model.slice(0, slash), opts.model.slice(slash + 1)] : [opts.provider ?? "opencode-go", opts.model];
+    const args = ["--mode", "rpc", "--no-session", "--provider", provider, "--model", model];
     if (opts.role === "librarian")
         args.push("--librarian");
     const env = { ...process.env, ...opts.extraEnv, SUBSUB_BENCH_OUT: opts.out, SUBSUB_CONFIG: opts.configFile };
@@ -405,7 +408,8 @@ export function scoreRun(task, dir, t, index, blindRef, starbuck) {
             dois: dois.length,
             pmids: pmids.length,
             ungrounded: [...dois.filter((d) => !seen.includes(d)), ...pmids.filter((p) => !seen.includes(p))],
-            screening_log: existsSync(plans) && readdirSync(plans).some((f) => /screening/i.test(f)),
+            // A model may write .plans as a file instead of a folder: then there is no screening log.
+            screening_log: existsSync(plans) && statSync(plans).isDirectory() && readdirSync(plans).some((f) => /screening/i.test(f)),
             multi_searches: calls.filter((c) => c.name === "scholar_search_multi").length,
             fulltext_reads: calls.filter((c) => c.name === "scholar_read_oa_fulltext" || c.name === "zotero_get_fulltext").length,
             starbuck: text && starbuck ? starbuck(join(dir, "Lit.md")) : undefined,
@@ -558,7 +562,9 @@ export async function main(argv = process.argv.slice(2)) {
             if (!prompt)
                 return;
             const cf = join(cfgDir, `${j.code}.json`);
-            writeFileSync(cf, JSON.stringify({ ...userCfg, profile: "editor", models: { librarian: `opencode-go/${j.model}`, researcher: `opencode-go/${j.model}` }, model: undefined, libraryChanges: undefined }));
+            // A bare name is an OpenCode Go model; provider/id (google/gemini-..., openrouter/x/y:free) is any provider.
+            const spec = j.model.includes("/") ? j.model : `opencode-go/${j.model}`;
+            writeFileSync(cf, JSON.stringify({ ...userCfg, profile: "editor", models: { librarian: spec, researcher: spec }, model: undefined, libraryChanges: undefined }));
             const s = await runOne({ ...j, prompt, out, cwd: cfg.vault, configFile: cf, timeoutSec });
             n++;
             console.log(`${n}/${jobs.length}  ${j.code}  ${j.task}  ${s.seconds}s  ${s.error ?? (s.settled ? "done" : "?")}`);

package/dist/cli.js

@@ -151,6 +151,7 @@ Usage:
   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 usage           The pilot's usage log (if turned on): a summary and where the file is
   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/
@@ -198,6 +199,11 @@ export async function run(argv = process.argv.slice(2)) {
         process.exitCode = await doctorMain(env);
         return;
     }
+    if (args[0] === "usage") {
+        const { usageMain } = await import("./usage.js");
+        process.exitCode = usageMain(env);
+        return;
+    }
     if (args[0] === "review") {
         const r = reviewCommand(args.slice(1), loadConfig(env), env);
         const res = spawnSync(r.command, r.args, { env: r.env, stdio: "inherit" });

package/dist/config.js

@@ -31,9 +31,35 @@ export const DEFAULT_MODELS = {
     librarian: "opencode-go/mimo-v2.6-flash",
     researcher: "opencode-go/mimo-v2.6-pro",
 };
+/** The tested free models (Google AI Studio free tier; see the Models page): enough to try Sub-Sub. */
+export const FREE_MODELS = {
+    librarian: "google/gemini-3.1-flash-lite",
+    researcher: "google/gemini-3.1-flash-lite",
+};
+/** The tested EU-hosted models (Mistral, servers in the EU; see the Models page). */
+export const EU_MODELS = {
+    librarian: "mistral/mistral-medium-3.5",
+    researcher: "mistral/mistral-medium-3.5",
+};
+/**
+ * Models marked in the model dialog, from the model tests (see the Models page). `why` is a
+ * key into the web view's strings: tested (a default), cheaper (tested, same quality, lower cost),
+ * free (tested, works on a free tier), eu (tested, servers in the EU).
+ */
+export const RECOMMENDED_MODELS = [
+    { spec: DEFAULT_MODELS.librarian, modes: ["librarian"], why: "tested" },
+    { spec: DEFAULT_MODELS.researcher, modes: ["researcher"], why: "tested" },
+    { spec: "opencode-go/qwen3.8-flash", modes: ["researcher"], why: "cheaper" },
+    { spec: EU_MODELS.researcher, modes: ["librarian", "researcher"], why: "eu" },
+    { spec: FREE_MODELS.librarian, modes: ["librarian", "researcher"], why: "free" },
+];
+/** "pt" when the language setting is Portuguese, else "en": the language of the interface. */
+export function uiLanguage(language) {
+    return /portug|^pt\b|^pt-/i.test(language ?? "") ? "pt" : "en";
+}
 export const PROFILES = ["reader", "scholar", "author", "editor"];
 /** The Zotero server release that this Sub-Sub version runs when there is no local server folder. */
-export const SERVER_VERSION = "0.5.3";
+export const SERVER_VERSION = "0.5.4";
 /** The Starbuck release (PyPI) that this Sub-Sub version runs when there is no local Starbuck folder. */
 export const STARBUCK_VERSION = "0.2.0";
 export const STARBUCK_SOURCE = `starbuck==${STARBUCK_VERSION}`;
@@ -147,6 +173,7 @@ export function loadConfig(env = process.env) {
         themes,
         addons: Array.isArray(user.addons) ? user.addons.filter((a) => typeof a === "string") : [],
         starbuckDir: expand(user.starbuckDir ?? "~/Projects/starbuck", home),
+        usageLog: user.usageLog === true,
     };
 }
 /** uv is often missing from PATH when pi is started outside a login shell. */

package/dist/init.js

@@ -19,16 +19,17 @@
  * Flags (for scripts and tests): --yes (take every default), --setup
  * standard|fmup, --name, --about, --language, --folder (or --notes), --move
  * yes|no, --profile, --tags health-sciences|health-informatics|any-field,
- * --email, --starbuck on|off, --models keep|later|opencode-go.
+ * --email, --starbuck on|off, --models keep|later|opencode-go|mistral-eu|google-free.
  */
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
-import { configPath, DEFAULT_MODELS, expand, isProfile, loadConfig, parseEnvFile, PROFILES, readConfigFile, saveConfig, starbuckEnabled, withStarbuck, } from "./config.js";
+import { configPath, DEFAULT_MODELS, EU_MODELS, FREE_MODELS, expand, isProfile, loadConfig, parseEnvFile, PROFILES, readConfigFile, saveConfig, starbuckEnabled, withStarbuck, } from "./config.js";
 import { defaultRunner, starbuckCheck } from "./doctor.js";
 import { applyMoves, FOLDER_NAME, leftBehind, NOTE_DIRS, planMoves, SETTINGS_DIR, SETTINGS_FILES, subsubFolder } from "./layout.js";
+import { KEY_PROVIDERS, saveApiKey } from "./keys.js";
 import { PROFILE_SPECS } from "./profiles.js";
 const TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates");
 export const STARTER_TAGS = {
@@ -131,8 +132,17 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         { value: "fmup", label: "FMUP / U.Porto: health-sciences tags, Reader profile (the FMUP model service is coming soon)" },
     ], flags.setup ?? existing.setup ?? "standard");
     const fmup = setup === "fmup";
+    // Students start in Reader: Sub-Sub helps them read and does not write syntheses for them unless asked.
+    let student = fmup;
+    if (!flags.profile && !existing.profile && !fmup) {
+        explain("Who you are", "Students start with the Reader profile: Sub-Sub helps you read (notes with quotations, page numbers and questions) and does not write summaries or syntheses unless you ask. You can change the profile at any time.");
+        student = (await io.choose("You are", [
+            { value: "student", label: "A student" },
+            { value: "researcher", label: "A researcher, teacher or clinician" },
+        ], flags.student === "no" ? "researcher" : "student")) === "student";
+    }
     explain("Profile", "The profile sets how much Sub-Sub writes for you and which tools it offers. Change it at any time with /profile.");
-    const profileDefault = flags.profile ?? existing.profile ?? (fmup ? "reader" : "scholar");
+    const profileDefault = flags.profile ?? existing.profile ?? (student ? "reader" : "scholar");
     const profile = await io.choose("Profile", PROFILES.map((p) => ({ value: p, label: `${PROFILE_SPECS[p].label}: ${PROFILE_SPECS[p].summary}` })), isProfile(profileDefault) ? profileDefault : "scholar");
     // The tag list: a custom path in the server settings stays; otherwise Zotero/Zotero tags.md (moved, kept or new).
     const vocabTarget = join(notes, SETTINGS_DIR, SETTINGS_FILES.tags);
@@ -159,6 +169,11 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         { value: "off", label: "Off" },
         { value: "on", label: "On (downloads Starbuck now; uses the email above)" },
     ], flags.starbuck ?? (starbuckEnabled(current) ? "on" : "off"));
+    explain("Usage log for the pilot", "If you take part in the Sub-Sub pilot, Sub-Sub can keep a log on this computer: when you used it, which commands, how long it worked and how many library changes you approved. Never what you wrote or what it replied. Nothing is sent; subsub usage shows the log, and you decide whether to send it.");
+    const usage = await io.choose("Usage log", [
+        { value: "off", label: "Off" },
+        { value: "on", label: "On (for the pilot)" },
+    ], flags.usage ?? (existing.usageLog === true ? "on" : "off"));
     explain("Models", "Sub-Sub needs an account with a model provider. Each mode can use its own model: the Librarian a fast, cheap one for tags and imports, the Researcher a stronger one for reading. You can connect a provider later in Sub-Sub with the model button (or /login in the terminal).");
     const hadModel = "model" in existing || "models" in existing;
     const show = (m) => (Object.keys(m).length ? Object.entries(m).map(([k, v]) => `${k} ${v}`).join(", ") : "choose in Sub-Sub");
@@ -166,10 +181,18 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         ...(hadModel ? [{ value: "keep", label: `Keep: ${show(current.models)}` }] : []),
         { value: "later", label: "Choose later in Sub-Sub" },
         { value: "opencode-go", label: `OpenCode Go, tested: ${TESTED_MODELS.librarian} for the Librarian, ${TESTED_MODELS.researcher} for the Researcher` },
+        { value: "mistral-eu", label: `Mistral, servers in the EU (GDPR): ${EU_MODELS.researcher} in both modes; about six times the cost of OpenCode Go` },
+        { value: "google-free", label: `Free, to try Sub-Sub: Google AI Studio, ${FREE_MODELS.researcher} in both modes (a free key, no card; limits per minute and per day; 18 or older)` },
     ];
     const agentDir = initEnv.SUBSUB_AGENT_DIR ? expand(initEnv.SUBSUB_AGENT_DIR, home) : join(home, ".subsub", "agent");
     const modelDefault = hadModel ? "keep" : hasProvider(agentDir, "opencode") ? "opencode-go" : "later";
     const models = await io.choose("Models", modelOptions, flags.models ?? modelDefault);
+    let googleKey = "";
+    if (models === "google-free" && !hasProvider(agentDir, "google")) {
+        const url = KEY_PROVIDERS.find((p) => p.id === "google")?.url;
+        explain("Free Google key", `Open ${url}, sign in with a Google account, and select "Create API key". Copy the key and paste it here. Sub-Sub saves it in ${join(agentDir, "auth.json")}, readable only by you. In the EU, the UK and Switzerland, Google does not use your prompts to improve its products; elsewhere, on the free tier, it may. When a limit is reached, Sub-Sub says so.`);
+        googleKey = (await io.ask("Google API key (Enter to add it later with the model button or /login)", "")).trim();
+    }
     // ---- write
     if (move === "yes")
         applyMoves(moves);
@@ -206,6 +229,7 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         envFile,
         libraryChanges: undefined,
         addons: withStarbuck(current.addons, starbuck === "on"),
+        usageLog: usage === "on" ? true : undefined,
     };
     // A model per mode; "model" (0.10, one for both) is replaced.
     patch.model = undefined;
@@ -215,7 +239,27 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         patch.models = {};
     if (models === "opencode-go")
         patch.models = TESTED_MODELS;
+    if (models === "google-free")
+        patch.models = FREE_MODELS;
+    if (models === "mistral-eu")
+        patch.models = EU_MODELS;
     saveConfig(patch, initEnv);
+    let keyNote = "";
+    if (googleKey) {
+        try {
+            saveApiKey(agentDir, "google", googleKey);
+            keyNote = `Saved: the Google key, in ${join(agentDir, "auth.json")}`;
+        }
+        catch (err) {
+            keyNote = `The Google key was not saved (${err.message}). Add it in Sub-Sub with the model button or /login.`;
+        }
+    }
+    else if (models === "mistral-eu" && !hasProvider(agentDir, "mistral")) {
+        keyNote = `No Mistral key yet. Get one at ${KEY_PROVIDERS.find((p) => p.id === "mistral")?.url}, then add it in Sub-Sub with the model button (subsub web) or /login (in the terminal).`;
+    }
+    else if (models === "google-free" && !hasProvider(agentDir, "google")) {
+        keyNote = "No Google key yet. Add it in Sub-Sub with the model button (subsub web) or /login (in the terminal), with the provider Google Gemini.";
+    }
     const zotero = await zoteroReachable(deps.fetch);
     const starbuckNote = starbuck === "on" && deps.prepareStarbuck ? deps.prepareStarbuck(loadConfig(initEnv)) : "";
     io.say("");
@@ -223,6 +267,8 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
     io.say(`Saved: ${envFile}`);
     for (const c of created)
         io.say(`Created: ${c}`);
+    if (keyNote)
+        io.say(keyNote);
     if (move === "yes")
         io.say(`Moved: ${moves.length} file(s) into ${notes}`);
     for (const d of leftBehind(from, notes))

package/dist/keys.js

@@ -0,0 +1,81 @@
+/** Model providers that take an API key, and plain words for their common errors. */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * `where`: where the provider processes the data, as a key into the web view's strings
+ * (eu, us, cn, varies). Shown next to the key form, so the choice of provider is an informed one.
+ */
+export const KEY_PROVIDERS = [
+    { id: "opencode-go", label: "OpenCode Go", url: "https://opencode.ai/auth", where: "varies" },
+    { id: "openrouter", label: "OpenRouter", url: "https://openrouter.ai/keys", where: "varies" },
+    { id: "anthropic", label: "Anthropic", url: "https://console.anthropic.com/settings/keys", where: "us" },
+    { id: "openai", label: "OpenAI", url: "https://platform.openai.com/api-keys", where: "us" },
+    { id: "google", label: "Google Gemini", url: "https://aistudio.google.com/apikey", where: "us" },
+    { id: "mistral", label: "Mistral (EU)", url: "https://console.mistral.ai/api-keys", where: "eu" },
+    { id: "deepseek", label: "DeepSeek", url: "https://platform.deepseek.com/api_keys", where: "cn" },
+];
+/** Save an API key the way pi's /login does: auth.json in the agent folder, readable only by the user. */
+export function saveApiKey(agentDir, provider, key) {
+    if (!KEY_PROVIDERS.some((p) => p.id === provider))
+        throw new Error(`Unknown provider: ${provider}`);
+    const clean = key.trim();
+    if (!clean || /\s/.test(clean) || clean.length > 400)
+        throw new Error("That does not look like an API key.");
+    mkdirSync(agentDir, { recursive: true });
+    const file = join(agentDir, "auth.json");
+    let data = {};
+    if (existsSync(file)) {
+        try {
+            data = JSON.parse(readFileSync(file, "utf8")) ?? {};
+        }
+        catch {
+            throw new Error(`${file} is not valid JSON; fix it or type /login in the terminal.`);
+        }
+    }
+    data[provider] = { type: "api_key", key: clean };
+    // Write through a symlink (a shared pi auth.json) rather than replacing it.
+    writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+}
+/** What a provider's error means for the user, or undefined when it is something else. */
+export function providerTrouble(text) {
+    if (!text)
+        return undefined;
+    if (/RESOURCE_EXHAUSTED|\b429\b|quota|rate.?limit|too many requests|usage limit/i.test(text))
+        return "quota";
+    if (/\b(503|529)\b|UNAVAILABLE|high demand|overloaded/i.test(text))
+        return "busy";
+    if (/RECITATION|SAFETY|PROHIBITED_CONTENT/.test(text))
+        return "blocked";
+    if (/\b(401|403)\b|API key not valid|invalid api key|PERMISSION_DENIED|UNAUTHENTICATED/i.test(text))
+        return "key";
+    return undefined;
+}
+/** The words for each kind in notices (the web view has its own, in web/i18n.js). */
+export const TROUBLE_TEXT_PT = {
+    quota: "O fornecedor do modelo recusou o pedido: atingiu um limite da sua conta. Os níveis gratuitos limitam o texto enviado por minuto e os pedidos por dia. Espere um minuto e peça ao Sub-Sub para continuar; se voltar a acontecer, esgotou o limite diário (renova-se no dia seguinte). Ou use outro modelo (/model).",
+    busy: "O fornecedor do modelo está sobrecarregado neste momento. Tente outra vez dentro de alguns minutos ou use outro modelo (/model).",
+    blocked: "O fornecedor do modelo interrompeu a resposta (por exemplo, por repetir uma fonte palavra por palavra). Peça outra vez por outras palavras ou use outro modelo (/model).",
+    key: "O fornecedor do modelo não aceitou a chave da API. Verifique-a ou introduza uma nova com /login.",
+};
+export const TROUBLE_TEXT = {
+    quota: "The model provider refused the request: a limit of your account was reached. Free tiers limit the text sent each minute and the requests each day. Wait a minute and ask Sub-Sub to continue; if it happens again, the daily limit is used up (it resets the next day). Or use another model (/model).",
+    busy: "The model provider is busy at the moment. Try again in a few minutes, or use another model (/model).",
+    blocked: "The model provider stopped the reply (for example, because it repeated a source word for word). Ask again in other words, or use another model (/model).",
+    key: "The model provider did not accept the API key. Check it, or enter a new one with /login.",
+};
+/**
+ * Seconds to wait before a per-minute limit lets the request through again, or undefined when the
+ * error is not a per-minute limit (a daily limit, a spent balance, anything else). pi does not
+ * retry Google's per-minute 429, because its text mentions billing.
+ */
+export function perMinuteWait(text) {
+    if (!text || providerTrouble(text) !== "quota")
+        return undefined;
+    if (/PerDay|per day|daily/i.test(text))
+        return undefined;
+    const delay = /retryDelay\\*"\s*:\s*\\*"(\d+(?:\.\d+)?)s/.exec(text);
+    const seconds = delay?.[1] ?? /retry in (\d+(?:\.\d+)?)s/i.exec(text)?.[1];
+    if (seconds)
+        return Math.min(120, Math.ceil(Number(seconds)) + 2);
+    return /PerMinute|per minute/i.test(text) ? 60 : undefined;
+}

package/dist/preview.js

@@ -3,23 +3,76 @@
  * reads in the approval dialog. Plain ASCII, at most about 20 lines.
  */
 const MAX_LINES = 14;
+/** The words of the preview in English and European Portuguese; tags, titles and values stay as they are. */
+const WORDS = {
+    en: {
+        more: (n) => `... and ${n} more`,
+        moreChars: (n) => `[${n} more characters not shown]`,
+        empty: "(empty)",
+        change: "(change)",
+        undo: "Undo",
+        already: "ALREADY APPLIED",
+        drift: (n) => `${n} item(s) changed after the note was written; the note overwrites them:`,
+        now: "now",
+        none: "(none)",
+        wouldChange: (n) => `${n} item(s) would change.`,
+        inShort: (listed, total) => (listed < total ? `In short (in the ${listed} items listed):` : "In short:"),
+        items: "Items:",
+        itemsN: (n) => `${n} item(s)`,
+        changed: "changed",
+        wouldImport: (n) => `${n} item(s) would be imported:`,
+        noAbstract: "(no abstract)",
+        wouldAttach: (n) => `${n} PDF(s) would be attached:`,
+        newCollection: "New collection",
+        inside: "inside",
+        noteOn: "Note on",
+        link: "Link",
+        skipped: "Skipped",
+        errors: "Errors",
+    },
+    pt: {
+        more: (n) => `... e mais ${n}`,
+        moreChars: (n) => `[mais ${n} caracteres não mostrados]`,
+        empty: "(vazio)",
+        change: "(alteração)",
+        undo: "Anular",
+        already: "JÁ APLICADO",
+        drift: (n) => `${n} item(ns) mudaram depois de a nota ser escrita; a nota substitui-os:`,
+        now: "agora",
+        none: "(nenhuma)",
+        wouldChange: (n) => `${n} item(ns) vão mudar.`,
+        inShort: (listed, total) => (listed < total ? `Em resumo (nos ${listed} itens listados):` : "Em resumo:"),
+        items: "Itens:",
+        itemsN: (n) => `${n} item(ns)`,
+        changed: "alterado",
+        wouldImport: (n) => `${n} item(ns) vão ser importados:`,
+        noAbstract: "(sem resumo)",
+        wouldAttach: (n) => `${n} PDF(s) vão ser anexados:`,
+        newCollection: "Nova coleção",
+        inside: "dentro de",
+        noteOn: "Nota sobre",
+        link: "Ligação",
+        skipped: "Ignorados",
+        errors: "Erros",
+    },
+};
 function s(v, n = 90) {
     const t = typeof v === "string" ? v : JSON.stringify(v);
     return t.length > n ? `${t.slice(0, n - 3)}...` : t;
 }
 /** What will be written: shown whole up to a large limit, and the rest is counted, never silently cut. */
-function whole(v, n = 3000) {
+function whole(v, w, n = 3000) {
     const t = typeof v === "string" ? v : JSON.stringify(v);
-    return t.length > n ? `${t.slice(0, n)} [${t.length - n} more characters not shown]` : t;
+    return t.length > n ? `${t.slice(0, n)} ${w.moreChars(t.length - n)}` : t;
 }
-function list(rows, total) {
+function list(rows, w, total) {
     const out = rows.slice(0, MAX_LINES);
     const rest = (total ?? rows.length) - out.length;
     if (rest > 0)
-        out.push(`... and ${rest} more`);
+        out.push(w.more(rest));
     return out;
 }
-function describeChange(c) {
+function describeChange(c, w) {
     const parts = [];
     if (Array.isArray(c.added) && c.added.length)
         parts.push(`+ ${c.added.join(", ")}`);
@@ -30,62 +83,84 @@ function describeChange(c) {
             continue;
         if (v && typeof v === "object" && "after" in v) {
             const b = v.before;
-            parts.push(`${k}: ${s(b || "(empty)", 40)} -> ${whole(v.after)}`);
+            parts.push(`${k}: ${s(b || w.empty, 40)} -> ${whole(v.after, w)}`);
         }
     }
-    return `${s(c.item ?? c.key, 60)}: ${parts.join("; ") || "(change)"}`;
+    return `${s(c.item ?? c.key, 60)}: ${parts.join("; ") || w.change}`;
 }
-export function formatPreview(tool, preview) {
+/** For a large batch: each tag and field with the number of items it changes, so the whole is readable at once. */
+function tally(changes, total, w) {
+    const count = new Map();
+    const add = (k) => count.set(k, (count.get(k) ?? 0) + 1);
+    for (const c of changes) {
+        for (const tag of c.added ?? [])
+            add(`+ ${tag}`);
+        for (const tag of c.removed ?? [])
+            add(`- ${tag}`);
+        for (const [k, v] of Object.entries(c))
+            if (v && typeof v === "object" && "after" in v)
+                add(`${k} ${w.changed}`);
+    }
+    if (!count.size)
+        return [];
+    const rank = (k) => (k.startsWith("+") ? 0 : k.startsWith("-") ? 1 : 2);
+    const rows = [...count].sort((a, b) => rank(a[0]) - rank(b[0]) || b[1] - a[1] || a[0].localeCompare(b[0])).map(([k, n]) => `  ${k}: ${w.itemsN(n)}`);
+    return [w.inShort(changes.length, total), ...list(rows, w), w.items];
+}
+export function formatPreview(tool, preview, lang = "en") {
+    const w = WORDS[lang];
     if (!preview || typeof preview !== "object")
         return s(preview, 1500);
     const p = preview;
     const lines = [];
     if (p.undoing && typeof p.undoing === "object") {
         const u = p.undoing;
-        lines.push(`Undo ${u.op}: ${s(u.summary, 80)}`);
+        lines.push(`${w.undo} ${u.op}: ${s(u.summary, 80)}`);
     }
     if (Array.isArray(p.already_applied) && p.already_applied.length) {
-        lines.push(`ALREADY APPLIED: ${p.already_applied.join(", ")}`);
+        lines.push(`${w.already}: ${p.already_applied.join(", ")}`);
     }
     const drift = p.changed_since_note;
     if (drift && typeof drift === "object" && typeof drift.count === "number") {
-        lines.push(`${drift.count} item(s) changed after the note was written; the note overwrites them:`);
-        const items = Object.entries(drift.items ?? {}).map(([k, v]) => `  ${k} now: ${v.now?.join(", ") || "(none)"}`);
+        lines.push(w.drift(drift.count));
+        const items = Object.entries(drift.items ?? {}).map(([k, v]) => `  ${k} ${w.now}: ${v.now?.join(", ") || w.none}`);
         lines.push(...items.slice(0, 4));
     }
     if (typeof p.would_change === "number") {
-        lines.push(`${p.would_change} item(s) would change.`);
+        lines.push(w.wouldChange(p.would_change));
         const changes = p.changes ?? [];
-        lines.push(...list(changes.map(describeChange), p.would_change));
+        if (p.would_change > 10)
+            lines.push(...tally(changes, p.would_change, w));
+        lines.push(...list(changes.map((c) => describeChange(c, w)), w, p.would_change));
     }
     if (Array.isArray(p.would_import)) {
-        lines.push(`${p.would_import.length} item(s) would be imported:`);
-        lines.push(...list(p.would_import.map((r) => `${r.citekey}  ${s(r.item, 70)}${r.has_abstract ? "" : "  (no abstract)"}`)));
+        lines.push(w.wouldImport(p.would_import.length));
+        lines.push(...list(p.would_import.map((r) => `${r.citekey}  ${s(r.item, 70)}${r.has_abstract ? "" : `  ${w.noAbstract}`}`), w));
     }
     if (Array.isArray(p.would_attach)) {
-        lines.push(`${p.would_attach.length} PDF(s) would be attached:`);
-        lines.push(...list(p.would_attach.map((r) => `${s(r.item, 60)}  [${r.host_type ?? "?"}, ${r.version ?? "?"}${r.license ? `, ${r.license}` : ""}]`)));
+        lines.push(w.wouldAttach(p.would_attach.length));
+        lines.push(...list(p.would_attach.map((r) => `${s(r.item, 60)}  [${r.host_type ?? "?"}, ${r.version ?? "?"}${r.license ? `, ${r.license}` : ""}]`), w));
     }
     if (p.would_create && typeof p.would_create === "object") {
-        const w = p.would_create;
-        lines.push(`New collection: ${w.name}${w.parent ? ` (inside ${w.parent})` : ""}`);
+        const nc = p.would_create;
+        lines.push(`${w.newCollection}: ${nc.name}${nc.parent ? ` (${w.inside} ${nc.parent})` : ""}`);
     }
     if (tool.endsWith("attach_note") || tool.endsWith("create_note")) {
         if (p.item || p.parent)
-            lines.push(`Note on: ${s(p.item ?? p.parent, 90)}`);
+            lines.push(`${w.noteOn}: ${s(p.item ?? p.parent, 90)}`);
         if (p.summary || p.note_preview)
-            lines.push(whole(p.summary ?? p.note_preview));
+            lines.push(whole(p.summary ?? p.note_preview, w));
         if (p.link)
-            lines.push(`Link: ${p.link}`);
+            lines.push(`${w.link}: ${p.link}`);
     }
     const skipped = p.skipped;
     if (skipped && typeof skipped === "object" && Object.keys(skipped).length) {
-        lines.push(`Skipped: ${Object.keys(skipped).length}`);
-        lines.push(...list(Object.entries(skipped).map(([k, v]) => `  ${k}: ${s(v, 70)}`)).slice(0, 5));
+        lines.push(`${w.skipped}: ${Object.keys(skipped).length}`);
+        lines.push(...list(Object.entries(skipped).map(([k, v]) => `  ${k}: ${s(v, 70)}`), w).slice(0, 5));
     }
     const errors = p.errors;
     if (errors && typeof errors === "object" && Object.keys(errors).length) {
-        lines.push(`Errors: ${Object.keys(errors).length}`);
+        lines.push(`${w.errors}: ${Object.keys(errors).length}`);
         lines.push(...Object.entries(errors).slice(0, 5).map(([k, v]) => `  ${k}: ${s(v, 70)}`));
     }
     if (!lines.length)