@tiagojct/subsub 0.11.4 → 0.12.1

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# 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.1 (2026-10-07)
+
+Files and notes without a parent item (Zotero server 0.5.5):
+
+- Sub-Sub lists them, reads each file, finds the reference and makes the parent item: from a DOI, PMID or ISBN, or from the file's own text (magazines, reports, books). An item already in the library is used instead of a copy. One preview for up to 25 files; undo puts the files back and moves the new items to the trash.
+- Reference search for these files in Crossref, Google Books, Internet Archive, Open Library and Wikidata, without a key. Web search through Brave Search when you save a key in `subsub init`.
+- A search of the library for attachments or notes now says that it covers regular items only, instead of finding nothing.
+
+Also:
+
+- Sub-Sub no longer offers to change its own programs; it says what it cannot do.
+- Citekeys for long organisation names are shorter (europeancommission2026), and an item without creators takes the first main word of its title (economist2026, not the2026). Existing keys do not change.
+- OpenCode's "requires Global regions" error is explained in plain words.
+
+## 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 |
 |---|---|
@@ -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. 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";
@@ -408,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,

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

@@ -36,20 +36,30 @@ 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).
+ * 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.5";
 /** 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}`;
@@ -163,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,14 +19,14 @@
  * 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|google-free.
+ * --email, --starbuck on|off, --models keep|later|opencode-go|mistral-eu|google-free.
  */
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, 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, FREE_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";
@@ -132,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);
@@ -155,11 +164,19 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
     }
     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("Web search", "Optional. To identify files without a parent item, such as magazines and reports, Sub-Sub can search the web through Brave Search. Brave needs a key: https://brave.com/search/api/ (free tier; a card is asked at sign-up). Searches then go to Brave, in the United States. Without a key Sub-Sub uses Crossref, Google Books, Internet Archive, Open Library and Wikidata.");
+    const hadBrave = Boolean(envValues.BRAVE_API_KEY);
+    const brave = (await io.ask(hadBrave ? "Brave Search key (Enter keeps the saved key)" : "Brave Search key (Enter for none)", flags.brave ?? "")).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.");
     const starbuck = await io.choose("Reference checks", [
         { 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");
@@ -167,6 +184,7 @@ 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");
@@ -203,7 +221,9 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
     const alerts = !existsSync(alertsTarget) && existsSync(legacyAlerts) ? legacyAlerts : alertsTarget;
     mkdirSync(dirname(envFile), { recursive: true });
     const before = existsSync(envFile) ? readFileSync(envFile, "utf8") : "# Settings for the Sub-Sub Zotero servers (zotero-local-mcp). Written by subsub init.\n";
-    writeFileSync(envFile, upsertEnv(before, { ZOTERO_VAULT: notes, ZOTERO_VOCAB: vocab, ZOTERO_ALERTS: alerts, ZOTERO_CONTACT_EMAIL: email || undefined }));
+    writeFileSync(envFile, upsertEnv(before, { ZOTERO_VAULT: notes, ZOTERO_VOCAB: vocab, ZOTERO_ALERTS: alerts, ZOTERO_CONTACT_EMAIL: email || undefined, BRAVE_API_KEY: brave || undefined }));
+    if (brave || hadBrave)
+        chmodSync(envFile, 0o600); // the file holds a key
     const patch = {
         profile,
         userName: userName || undefined,
@@ -214,6 +234,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;
@@ -225,6 +246,8 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         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) {
@@ -236,6 +259,9 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
             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.";
     }

package/dist/keys.js

@@ -1,14 +1,18 @@
 /** 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" },
-    { id: "openrouter", label: "OpenRouter", url: "https://openrouter.ai/keys" },
-    { id: "anthropic", label: "Anthropic", url: "https://console.anthropic.com/settings/keys" },
-    { id: "openai", label: "OpenAI", url: "https://platform.openai.com/api-keys" },
-    { id: "google", label: "Google Gemini", url: "https://aistudio.google.com/apikey" },
-    { id: "mistral", label: "Mistral", url: "https://console.mistral.ai/api-keys" },
-    { id: "deepseek", label: "DeepSeek", url: "https://platform.deepseek.com/api_keys" },
+    { 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) {
@@ -36,6 +40,8 @@ export function saveApiKey(agentDir, provider, key) {
 export function providerTrouble(text) {
     if (!text)
         return undefined;
+    if (/requires Global regions|not available in your region|region.{0,40}not (supported|allowed)/i.test(text))
+        return "region";
     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))
@@ -46,10 +52,34 @@ export function providerTrouble(text) {
         return "key";
     return undefined;
 }
-/** The terminal's words for each kind (the web view has its own, in English and Portuguese). */
+/** 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.",
+    region: "O fornecedor recusa este modelo com a definição de região da sua conta. No OpenCode, permita as regiões globais (Global) nas definições de privacidade do workspace, ou escolha um modelo que a sua região permita (/model).",
+};
 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.",
+    region: "The provider refuses this model with your account's region setting. In OpenCode, allow Global regions in the workspace's Privacy settings, or choose a model your region allows (/model).",
 };
+/**
+ * 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,82 @@
  * 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:`,
+        wouldParent: (n) => `${n} file(s) or note(s) would get a parent item:`,
+        newItem: "new",
+        existingItem: "existing item",
+        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:`,
+        wouldParent: (n) => `${n} ficheiro(s) ou nota(s) vão ter um item principal:`,
+        newItem: "novo",
+        existingItem: "item existente",
+        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 +89,107 @@ 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 (Array.isArray(p.would_set_parent)) {
+        lines.push(w.wouldParent(p.would_set_parent.length));
+        const rows = [];
+        for (const r of p.would_set_parent.slice(0, 6)) {
+            rows.push(`${s(r.file, 60)}`);
+            if (r.parent === "new") {
+                const f = r.fields ?? {};
+                const where = ["publicationTitle", "date", "issue", "volume", "pages", "publisher", "ISBN", "DOI"]
+                    .filter((k) => f[k])
+                    .map((k) => `${k}: ${s(f[k], 40)}`)
+                    .join(", ");
+                rows.push(`  -> ${w.newItem} ${r.type} ${r.citekey}: ${s(r.item, 80)}`);
+                if (where)
+                    rows.push(`     ${where}`);
+            }
+            else {
+                rows.push(`  -> ${w.existingItem} ${r.parent_key}: ${s(r.item, 70)}`);
+            }
+        }
+        lines.push(...rows);
+        if (p.would_set_parent.length > 6)
+            lines.push(w.more(p.would_set_parent.length - 6));
     }
     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)

package/dist/roles.js

@@ -9,6 +9,7 @@ export const ZOTERO_READ = [
     "status",
     "library_overview",
     "find_items",
+    "standalone_items",
     "get_item",
     "get_fulltext",
     "list_tags",
@@ -35,13 +36,23 @@ export const PREVIEW_WRITES = new Set([
         "import_queue",
         "repair_metadata",
         "attach_oa_pdfs",
+        "set_parent_items",
     ].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"]);
 /** Zotero tools that look at the library or write only a note in the Sub-Sub folder. */
-export const ZOTERO_CHECKS = ["tag_audit", "audit_metadata", "find_duplicates", "check_retractions", "missing_pdfs", "write_tag_review"].map((n) => `zotero_${n}`);
+export const ZOTERO_CHECKS = [
+    "tag_audit",
+    "audit_metadata",
+    "find_duplicates",
+    "check_retractions",
+    "missing_pdfs",
+    "write_tag_review",
+    "find_reference",
+    "web_search",
+].map((n) => `zotero_${n}`);
 /**
  * The tools of a mode. The Librarian manages the library: Zotero tools and files.
  * The Researcher has the same, plus searches, notes and reference checks. The