@tiagojct/subsub 0.11.2 → 0.11.4

package/README.md

@@ -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
@@ -133,7 +133,7 @@ subsub review apply 13-31
 | `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 | `[]` |
 | `serverDir` | A local copy of zotero-local-mcp, for development | the PyPI release |

package/dist/bench.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 };
@@ -558,7 +561,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/config.js

@@ -31,9 +31,25 @@ 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",
+};
+/**
+ * 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).
+ */
+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: FREE_MODELS.librarian, modes: ["librarian", "researcher"], why: "free" },
+];
 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.2";
+export const SERVER_VERSION = "0.5.3";
 /** 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}`;

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|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, 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 = {
@@ -88,12 +89,6 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         io.say("");
         io.say(`${title}. ${text}`);
     };
-    explain("Setup", "Standard works for any field. FMUP / U.Porto starts with health-sciences tags and the Reader profile.");
-    const setup = await io.choose("Setup", [
-        { value: "standard", label: "Standard" },
-        { 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";
     explain("About you", "Sub-Sub uses your name and one line about you in its replies. Both are optional and stay on this computer, except in the messages to the model provider.");
     const userName = (await io.ask("Your name (Enter for none)", flags.name ?? existing.userName ?? "")).trim();
     const about = (await io.ask('One line about you, e.g. "a master\'s student in health informatics" (optional)', flags.about ?? existing.about ?? "")).trim();
@@ -130,6 +125,13 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
             io.say(`Sub-Sub keeps using ${notes}.`);
         }
     }
+    // Asked here, not first: it only changes the defaults of the next two questions.
+    explain("Faculty of Medicine, Porto", "Sub-Sub has a set-up for the Faculty of Medicine of the University of Porto (FMUP): health-sciences tags and the Reader profile. Everyone else keeps the standard set-up.");
+    const setup = await io.choose("Set-up", [
+        { value: "standard", label: "Standard (any field, any institution)" },
+        { 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";
     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 profile = await io.choose("Profile", PROFILES.map((p) => ({ value: p, label: `${PROFILE_SPECS[p].label}: ${PROFILE_SPECS[p].summary}` })), isProfile(profileDefault) ? profileDefault : "scholar");
@@ -165,10 +167,17 @@ 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: "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);
@@ -214,7 +223,22 @@ 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;
     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 === "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("");
@@ -222,6 +246,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,55 @@
+/** 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";
+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" },
+];
+/** 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 terminal's words for each kind (the web view has its own, in English and Portuguese). */
+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.",
+};

package/dist/subsub.js

@@ -25,6 +25,7 @@ import { coerceArgs, loosenArrays, resolvePathArgs } from "./args.js";
 import { applyEdits, checkLiteratureNote } from "./notes.js";
 import { buildPolicy, isSecret, judgePath, normalizeToolPath, realish, within } from "./paths.js";
 import { describeArgs, formatPreview } from "./preview.js";
+import { providerTrouble, TROUBLE_TEXT } from "./keys.js";
 import { headerLines, paintPreview, QUOTES, schemeFromAnsi, themeName } from "./look.js";
 import { systemAddition } from "./prompt.js";
 import { gateKind, SERVER_PREFIXES, toolsFor, unavailableReason } from "./roles.js";
@@ -298,6 +299,15 @@ export async function createSubsub(pi, deps = {}) {
             await applyMode(ctx, m, false, false);
     });
     pi.on("model_select", async (_event, ctx) => status(ctx));
+    // A provider error in plain words (quota, busy, blocked, key); the web view words its own.
+    pi.on("message_end", async (event, ctx) => {
+        const m = event.message;
+        if (webView || m.role !== "assistant" || m.stopReason !== "error")
+            return;
+        const kind = providerTrouble(m.errorMessage);
+        if (kind)
+            ctx.ui.notify(`Sub-Sub: ${TROUBLE_TEXT[kind]}`, "warning");
+    });
     // Prompt commands that the profile does not run (/lit for Reader, /review for Reader and Scholar).
     // The input event comes before pi expands a prompt template.
     pi.on("input", async (event, ctx) => {

package/dist/web.js

@@ -21,8 +21,9 @@ import { homedir } from "node:os";
 import { extname, join, normalize, resolve, sep } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { agentDirFor, chooseCwd, PACKAGE_DIR, packageVersion } from "./cli.js";
-import { configPath, expand, loadConfig, readConfigFile, saveConfig, withStarbuck } from "./config.js";
+import { configPath, expand, loadConfig, RECOMMENDED_MODELS, readConfigFile, saveConfig, withStarbuck } from "./config.js";
 import { TESTED_MODELS } from "./init.js";
+import { KEY_PROVIDERS, saveApiKey } from "./keys.js";
 import { obsidianRoot } from "./layout.js";
 import { realish, within } from "./paths.js";
 export function parseWebArgs(args) {
@@ -51,37 +52,7 @@ export function uiLanguage(language) {
     return /portug|^pt\b|^pt-/i.test(language ?? "") ? "pt" : "en";
 }
 // ---------------------------------------------------------------- providers (API keys)
-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" },
-];
-/** 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 });
-}
+export { KEY_PROVIDERS, saveApiKey } from "./keys.js";
 /** pi as a child process in RPC mode. Strict JSONL: records end at LF only. */
 export class Agent {
     proc;
@@ -582,7 +553,7 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
                 }
                 case "GET /api/models": {
                     const data = (await agent.request({ type: "get_available_models" }));
-                    return send(res, 200, { models: Array.isArray(data) ? data : (data.models ?? []) });
+                    return send(res, 200, { models: Array.isArray(data) ? data : (data.models ?? []), recommended: RECOMMENDED_MODELS });
                 }
                 case "POST /api/model": {
                     if (busy || switching)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiagojct/subsub",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "Sub-Sub: a research assistant that works from your own Zotero library, in the browser or the terminal, built on pi",
   "type": "module",
   "license": "MIT",

package/src/bench.ts

@@ -134,7 +134,10 @@ export function runOne(opts: {
 	provider?: string;
 }): Promise<RunSummary> {
 	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 };
 	const proc = spawn(process.execPath, [opts.cli ?? join(PACKAGE_DIR, "bin", "subsub.js"), ...args], { cwd: opts.cwd, env });
@@ -608,7 +611,9 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
 			const prompt = promptFor(j.task, t, j.code, out);
 			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/src/config.ts

@@ -35,11 +35,27 @@ export const DEFAULT_MODELS: Record<Mode, string> = {
 	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: Record<Mode, string> = {
+	librarian: "google/gemini-3.1-flash-lite",
+	researcher: "google/gemini-3.1-flash-lite",
+};
+/**
+ * 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).
+ */
+export const RECOMMENDED_MODELS: Array<{ spec: string; modes: Mode[]; why: "tested" | "cheaper" | "free" }> = [
+	{ 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: FREE_MODELS.librarian, modes: ["librarian", "researcher"], why: "free" },
+];
 export type Profile = "reader" | "scholar" | "author" | "editor";
 export const PROFILES: Profile[] = ["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.2";
+export const SERVER_VERSION = "0.5.3";
 
 /** The Starbuck release (PyPI) that this Sub-Sub version runs when there is no local Starbuck folder. */
 export const STARBUCK_VERSION = "0.2.0";

package/src/init.ts

@@ -19,7 +19,7 @@
  * 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|google-free.
  */
 
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -30,6 +30,7 @@ import { fileURLToPath } from "node:url";
 import {
 	configPath,
 	DEFAULT_MODELS,
+	FREE_MODELS,
 	expand,
 	isProfile,
 	loadConfig,
@@ -43,6 +44,7 @@ import {
 } from "./config.ts";
 import { defaultRunner, starbuckCheck } from "./doctor.ts";
 import { applyMoves, FOLDER_NAME, leftBehind, NOTE_DIRS, planMoves, SETTINGS_DIR, SETTINGS_FILES, subsubFolder } from "./layout.ts";
+import { KEY_PROVIDERS, saveApiKey } from "./keys.ts";
 import { PROFILE_SPECS } from "./profiles.ts";
 
 const TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates");
@@ -128,17 +130,6 @@ export async function runInit(
 		io.say(`${title}. ${text}`);
 	};
 
-	explain("Setup", "Standard works for any field. FMUP / U.Porto starts with health-sciences tags and the Reader profile.");
-	const setup = await io.choose(
-		"Setup",
-		[
-			{ value: "standard", label: "Standard" },
-			{ 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";
-
 	explain("About you", "Sub-Sub uses your name and one line about you in its replies. Both are optional and stay on this computer, except in the messages to the model provider.");
 	const userName = (await io.ask("Your name (Enter for none)", flags.name ?? existing.userName ?? "")).trim();
 	const about = (await io.ask('One line about you, e.g. "a master\'s student in health informatics" (optional)', flags.about ?? existing.about ?? "")).trim();
@@ -184,6 +175,18 @@ export async function runInit(
 		}
 	}
 
+	// Asked here, not first: it only changes the defaults of the next two questions.
+	explain("Faculty of Medicine, Porto", "Sub-Sub has a set-up for the Faculty of Medicine of the University of Porto (FMUP): health-sciences tags and the Reader profile. Everyone else keeps the standard set-up.");
+	const setup = await io.choose(
+		"Set-up",
+		[
+			{ value: "standard", label: "Standard (any field, any institution)" },
+			{ 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";
+
 	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 profile = await io.choose(
@@ -237,10 +240,20 @@ export async function runInit(
 		...(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: "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);
@@ -284,7 +297,19 @@ export async function runInit(
 	if (models === "keep") patch.models = current.models;
 	if (models === "later") patch.models = {};
 	if (models === "opencode-go") patch.models = TESTED_MODELS;
+	if (models === "google-free") patch.models = FREE_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 as Error).message}). Add it in Sub-Sub with the model button or /login.`;
+		}
+	} 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)) : "";
@@ -292,6 +317,7 @@ export async function runInit(
 	io.say(`Saved: ${configFile}`);
 	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)) io.say(`Not moved: ${d}. If Sub-Sub wrote these notes, move them into ${notes} yourself.`);
 	io.say(

package/src/keys.ts

@@ -0,0 +1,55 @@
+/** 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";
+
+export const KEY_PROVIDERS: Array<{ id: string; label: string; url: string }> = [
+	{ 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" },
+];
+
+/** 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: string, provider: string, key: string): void {
+	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: Record<string, unknown> = {};
+	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 });
+}
+
+
+export type Trouble = "quota" | "busy" | "blocked" | "key";
+
+/** What a provider's error means for the user, or undefined when it is something else. */
+export function providerTrouble(text: string | undefined): Trouble | undefined {
+	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 terminal's words for each kind (the web view has its own, in English and Portuguese). */
+export const TROUBLE_TEXT: Record<Trouble, string> = {
+	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.",
+};

package/src/subsub.ts

@@ -41,6 +41,7 @@ import { coerceArgs, loosenArrays, resolvePathArgs } from "./args.ts";
 import { applyEdits, checkLiteratureNote } from "./notes.ts";
 import { buildPolicy, isSecret, judgePath, normalizeToolPath, realish, within } from "./paths.ts";
 import { describeArgs, formatPreview } from "./preview.ts";
+import { providerTrouble, TROUBLE_TEXT } from "./keys.ts";
 import { headerLines, type LibraryState, paintPreview, QUOTES, type Scheme, schemeFromAnsi, themeName } from "./look.ts";
 import { systemAddition } from "./prompt.ts";
 import { gateKind, SERVER_PREFIXES, toolsFor, unavailableReason } from "./roles.ts";
@@ -324,6 +325,14 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	});
 
 	pi.on("model_select", async (_event, ctx) => status(ctx));
+	// A provider error in plain words (quota, busy, blocked, key); the web view words its own.
+	pi.on("message_end", async (event, ctx) => {
+		const m = event.message as { role?: string; stopReason?: string; errorMessage?: string };
+		if (webView || m.role !== "assistant" || m.stopReason !== "error") return;
+		const kind = providerTrouble(m.errorMessage);
+		if (kind) ctx.ui.notify(`Sub-Sub: ${TROUBLE_TEXT[kind]}`, "warning");
+	});
+
 
 	// Prompt commands that the profile does not run (/lit for Reader, /review for Reader and Scholar).
 	// The input event comes before pi expands a prompt template.

package/src/web.ts

@@ -22,8 +22,9 @@ import { homedir } from "node:os";
 import { extname, join, normalize, resolve, sep } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { agentDirFor, chooseCwd, PACKAGE_DIR, packageVersion } from "./cli.ts";
-import { configPath, expand, loadConfig, readConfigFile, saveConfig, type SubsubConfig, withStarbuck } from "./config.ts";
+import { configPath, expand, loadConfig, RECOMMENDED_MODELS, readConfigFile, saveConfig, type SubsubConfig, withStarbuck } from "./config.ts";
 import { TESTED_MODELS } from "./init.ts";
+import { KEY_PROVIDERS, saveApiKey } from "./keys.ts";
 import { obsidianRoot } from "./layout.ts";
 import { realish, within } from "./paths.ts";
 
@@ -62,35 +63,7 @@ export function uiLanguage(language: string | undefined): "pt" | "en" {
 
 // ---------------------------------------------------------------- providers (API keys)
 
-export const KEY_PROVIDERS: Array<{ id: string; label: string; url: string }> = [
-	{ 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" },
-];
-
-/** 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: string, provider: string, key: string): void {
-	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: Record<string, unknown> = {};
-	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 });
-}
+export { KEY_PROVIDERS, saveApiKey } from "./keys.ts";
 
 // ---------------------------------------------------------------- pi in RPC mode
 
@@ -597,7 +570,7 @@ export async function startWeb(opts: WebOptions, env: NodeJS.ProcessEnv = proces
 				}
 				case "GET /api/models": {
 					const data = (await agent.request({ type: "get_available_models" })) as { models?: unknown[] } | unknown[];
-					return send(res, 200, { models: Array.isArray(data) ? data : (data.models ?? []) });
+					return send(res, 200, { models: Array.isArray(data) ? data : (data.models ?? []), recommended: RECOMMENDED_MODELS });
 				}
 				case "POST /api/model": {
 					if (busy || switching) return send(res, 409, { error: "busy" });

package/web/app.css

@@ -631,6 +631,11 @@ body.layout-full { --measure: 72rem; }
 .note.mono { font-family: var(--mono); font-size: 0.76rem; line-height: 1.55; }
 .note pre { font-family: var(--mono); font-size: 0.74rem; white-space: pre-wrap; }
 .note button { margin-top: 0.5rem; }
+.note p { margin: 0; }
+.note details { margin-top: 0.4rem; color: var(--muted); }
+.note details summary { cursor: pointer; font-size: 0.78rem; }
+.note details pre { margin: 0.3rem 0 0; overflow-wrap: anywhere; }
+.free-note { border-left: 3px solid var(--accent); padding-left: 0.6rem; }
 
 .working {
 	margin-top: 1rem;
@@ -826,6 +831,14 @@ body > p.empty { text-align: center; color: var(--muted); padding: 30vh 1rem 0;
 .models button:hover { background: var(--bg); }
 .models .current { color: var(--accent); font-weight: 600; background: var(--accent-soft); }
 .models .empty-models { padding: 0.65rem 0.8rem; color: var(--muted); font-size: 0.88rem; }
+.model-search { width: 100%; margin-bottom: 0.5rem; }
+.models { max-height: 20rem; }
+.models .models-group { padding: 0.45rem 0.8rem 0.3rem; font-size: 0.78rem; font-weight: 600; color: var(--muted); background: var(--surface); }
+.models button { display: flex; flex-wrap: wrap; align-items: baseline; gap: 0.25rem 0.6rem; }
+.models .needs-key { opacity: 0.65; }
+.models .model-name { min-width: 0; overflow-wrap: anywhere; }
+.models .model-tag { font-family: var(--sans); font-size: 0.72rem; font-weight: 600; color: var(--accent); border: 1px solid currentColor; border-radius: 999px; padding: 0 0.45rem; }
+.models .model-why { font-family: var(--sans); font-size: 0.75rem; color: var(--muted); }
 
 /* ---------------------------------------------------------------- narrow screens */
 

package/web/app.js

@@ -207,8 +207,10 @@ function renderHeader() {
 		txt.textContent += ` · ${t("serversDown", { x: state.down.join(", ") })}`;
 		lib.classList.add("down");
 	}
-	lib.title = txt.textContent;
-	$("input").placeholder = mode() === "librarian" ? t("placeholderLibrarian") : t("placeholderResearcher");
+	lib.title = L?.toReview ? `${txt.textContent}\n${t("toReviewHint")}` : txt.textContent;
+	// On a phone the long hint does not fit in the box.
+	const narrow = window.matchMedia("(max-width: 560px)").matches;
+	$("input").placeholder = narrow ? t("placeholderShort") : mode() === "librarian" ? t("placeholderLibrarian") : t("placeholderResearcher");
 	if (log.querySelector(".empty")) {
 		clearEmpty();
 		renderEmpty();
@@ -366,6 +368,21 @@ function scrollDown(force = false) {
 	if (force || near) log.scrollTop = log.scrollHeight;
 }
 
+// A provider error in plain words (keep in step with providerTrouble in src/keys.ts), with the raw text below.
+function troubleOf(text) {
+	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 null;
+}
+
+function errorNote(text) {
+	const kind = troubleOf(text);
+	if (!kind) return el("div", { class: "note error", text });
+	return el("div", { class: "note error" }, el("p", { text: t(`trouble_${kind}`) }), el("details", {}, el("summary", { text: t("details") }), el("pre", { text })));
+}
+
 function note(text, kind = "info", mono = false) {
 	clearEmpty();
 	const n = el("div", { class: `note ${kind}${mono ? " mono" : ""}`, text });
@@ -594,7 +611,7 @@ function renderAssistantFinal(message, msg = startAssistant()) {
 		);
 		msg.box.append(actions);
 	}
-	if (message.stopReason === "error" && message.errorMessage) msg.box.append(el("div", { class: "note error", text: message.errorMessage }));
+	if (message.stopReason === "error" && message.errorMessage) msg.box.append(errorNote(message.errorMessage));
 	if (message.stopReason === "aborted") msg.box.append(el("div", { class: "note", text: t("stopped") }));
 	if (!msg.box.children.length) msg.box.remove();
 	scrollDown();
@@ -905,44 +922,93 @@ async function openModels() {
 	const setLink = () => {
 		const p = providers.find((x) => x.id === sel.value);
 		link.href = p?.url ?? "#";
+		const free = { google: "freeGoogle", openrouter: "freeOpenRouter" }[sel.value];
+		$("login-free").hidden = !free;
+		$("login-free").textContent = free ? t(free) : "";
 	};
 	sel.onchange = setLink;
 	setLink();
 	if (!dlg.open) dlg.showModal();
 	let models = [];
+	let recommended = [];
 	try {
-		models = (await api("/api/models")).models ?? [];
+		const data = await api("/api/models");
+		models = data.models ?? [];
+		recommended = data.recommended ?? [];
 	} catch (err) {
 		note(err.message, "error");
 	}
-	ul.replaceChildren();
-	if (!models.length) ul.append(el("li", { class: "empty-models", text: t("noModels") }));
 	const cur = state?.model ?? session?.model;
+	const specOf = (m) => `${m.provider}/${m.id}`;
 	const isCurrent = (m) => cur && cur.provider === m.provider && cur.id === m.id;
-	models.sort((a, b) => Number(isCurrent(b)) - Number(isCurrent(a)) || `${a.provider}/${a.id}`.localeCompare(`${b.provider}/${b.id}`));
-	for (const m of models) {
-		const isCur = cur && cur.provider === m.provider && cur.id === m.id;
-		ul.append(
+	const available = new Set(models.map(specOf));
+	// Recommended for this mode first (also when the provider has no key yet), then the rest.
+	const mine = recommended.filter((r) => r.modes.includes(mode()));
+	const recSpecs = new Set(mine.map((r) => r.spec));
+	const others = models
+		.filter((m) => !recSpecs.has(specOf(m)))
+		.sort((a, b) => Number(isCurrent(b)) - Number(isCurrent(a)) || specOf(a).localeCompare(specOf(b)));
+	const choose = async (m) => {
+		if (busy) return note(t("busy"), "warning");
+		try {
+			await api("/api/model", { provider: m.provider, id: m.id, both: $("model-both").checked });
+			dlg.close();
+		} catch (err) {
+			note(err.message, "error");
+		}
+	};
+	const row = (m, rec) => {
+		const spec = specOf(m);
+		const can = available.has(spec);
+		const label = providers.find((p) => p.id === m.provider)?.label ?? m.provider;
+		return el(
+			"li",
+			{ "data-spec": spec.toLowerCase() },
 			el(
-				"li",
-				{},
-				el("button", {
+				"button",
+				{
 					type: "button",
-					class: isCur ? "current" : "",
-					text: `${m.provider}/${m.id}`,
-					onclick: async () => {
-						if (busy) return note(t("busy"), "warning");
-						try {
-							await api("/api/model", { provider: m.provider, id: m.id, both: $("model-both").checked });
-							dlg.close();
-						} catch (err) {
-							note(err.message, "error");
+					class: [isCurrent(m) ? "current" : "", rec ? "rec" : "", can ? "" : "needs-key"].join(" ").trim(),
+					// Without a key, the click goes to the form below: that provider, and the key field.
+					onclick: () => {
+						if (can) return choose(m);
+						if (providers.some((p) => p.id === m.provider)) {
+							sel.value = m.provider;
+							setLink();
 						}
+						$("login-key").focus();
 					},
-				}),
+				},
+				el("span", { class: "model-name", text: spec }),
+				rec ? el("span", { class: "model-tag", text: t(`rec_${rec.why}`) }) : null,
+				rec && !can ? el("span", { class: "model-why", text: t("needsKey", { x: label }) }) : null,
 			),
 		);
-	}
+	};
+	const search = $("model-search");
+	const render = () => {
+		const q = search.value.trim().toLowerCase().split(/\s+/).filter(Boolean);
+		const hit = (spec) => q.every((w) => spec.toLowerCase().includes(w));
+		const recRows = mine.filter((r) => hit(r.spec)).map((r) => {
+			const i = r.spec.indexOf("/");
+			return row({ provider: r.spec.slice(0, i), id: r.spec.slice(i + 1) }, r);
+		});
+		const rest = others.filter((m) => hit(specOf(m))).map((m) => row(m, null));
+		ul.replaceChildren();
+		if (recRows.length) ul.append(el("li", { class: "models-group", text: t("recommended") }), ...recRows);
+		if (rest.length) ul.append(el("li", { class: "models-group", text: t(recRows.length ? "otherModels" : "allModels") }), ...rest);
+		if (!recRows.length && !rest.length) ul.append(el("li", { class: "empty-models", text: models.length ? t("noMatch") : t("noModels") }));
+	};
+	search.value = "";
+	search.oninput = render;
+	search.onkeydown = (e) => {
+		if (e.key === "Enter") {
+			e.preventDefault();
+			ul.querySelector("button:not(.needs-key)")?.click();
+		}
+	};
+	render();
+	search.focus();
 }
 
 $("login-form")?.addEventListener("submit", async (e) => {

package/web/i18n.js

@@ -27,7 +27,8 @@ export const STRINGS = {
 		zoteroChecking: "Zotero: checking",
 		zoteroDown: "Zotero is not running",
 		items: "{n} items",
-		toReview: "{n} to review",
+		toReview: "{n} to check",
+		toReviewHint: "Items that Sub-Sub tagged and that wait for your check (they carry the _agent tag). Select Library overview, or ask Sub-Sub to list them.",
 		serversDown: "Not running: {x}",
 		working: "Working",
 		using: "Using: {x}",
@@ -44,6 +45,15 @@ export const STRINGS = {
 		modelTitleResearcher: "Model for the Researcher",
 		modelTitleLibrarian: "Model for the Librarian",
 		chooseModel: "Choose a model",
+		searchModels: "Search, e.g. flash or openrouter free",
+		recommended: "Recommended for this mode",
+		otherModels: "Other models",
+		allModels: "All models",
+		noMatch: "No model matches.",
+		rec_tested: "tested default",
+		rec_cheaper: "tested, cheaper",
+		rec_free: "tested, free",
+		needsKey: "needs a key from {x}",
 		noModels: "No models yet. Connect a provider below.",
 		connectProvider: "Connect a provider",
 		provider: "Provider",
@@ -51,6 +61,13 @@ export const STRINGS = {
 		save: "Save",
 		getKey: "Get a key",
 		keyNote: "The key is saved on this computer, in Sub-Sub's settings folder, and is sent only to that provider.",
+		freeGoogle: "Free to try: a Google AI Studio key needs no card. The free tier limits the text sent each minute and the requests each day, enough to try Sub-Sub, and gemini-3.1-flash-lite is the tested free model. You must be 18 or older. In the EU, the UK and Switzerland, Google does not use your prompts to improve its products; elsewhere, on the free tier, it may.",
+		freeOpenRouter: "Free to try: models whose names end in :free cost nothing, with 50 requests a day (1000 after you buy 10 dollars of credit). The providers of some free models may keep your prompts.",
+		trouble_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 choose another model with the model button.",
+		trouble_busy: "The model provider is busy at the moment. Try again in a few minutes, or choose another model with the model button.",
+		trouble_blocked: "The model provider stopped the reply (for example, because it repeated a source word for word). Ask again in other words, or choose another model.",
+		trouble_key: "The model provider did not accept the API key. Enter it again with the model button.",
+		details: "Details",
 		oauthNote: "To sign in through a provider's website (for example with a subscription), open a terminal, type subsub, then /login.",
 		saving: "Saving",
 		saved: "Saved.",
@@ -89,6 +106,7 @@ export const STRINGS = {
 		librarianHint: "Manages the library only: tags, imports, metadata, PDFs. No literature search.",
 		placeholderResearcher: "Ask about your library or the literature, or type / for commands",
 		placeholderLibrarian: "Ask for a change to your library, or type / for commands",
+		placeholderShort: "Ask, or type / for commands",
 		emptyResearcher: "The Researcher reads your library, searches PubMed, Europe PMC and OpenAlex and writes notes. It also imports, tags and repairs items: every change shows a preview, and nothing changes until you approve it.",
 		emptyLibrarian: "The Librarian manages your library: tags, imports, metadata and PDFs. Every change shows a preview, and nothing changes until you approve it. For searches and notes, switch to the Researcher.",
 		forBoth: "Use it in both modes",
@@ -120,7 +138,8 @@ export const STRINGS = {
 		zoteroChecking: "Zotero: a verificar",
 		zoteroDown: "O Zotero não está aberto",
 		items: "{n} itens",
-		toReview: "{n} por rever",
+		toReview: "{n} por verificar",
+		toReviewHint: "Itens que o Sub-Sub etiquetou e que esperam a sua verificação (têm a etiqueta _agent). Selecione Resumo da biblioteca, ou peça ao Sub-Sub para os listar.",
 		serversDown: "Parados: {x}",
 		working: "A trabalhar",
 		using: "A usar: {x}",
@@ -137,6 +156,15 @@ export const STRINGS = {
 		modelTitleResearcher: "Modelo do Investigador",
 		modelTitleLibrarian: "Modelo do Bibliotecário",
 		chooseModel: "Escolha um modelo",
+		searchModels: "Pesquisar, por exemplo flash ou openrouter free",
+		recommended: "Recomendados para este modo",
+		otherModels: "Outros modelos",
+		allModels: "Todos os modelos",
+		noMatch: "Nenhum modelo corresponde.",
+		rec_tested: "testado, por omissão",
+		rec_cheaper: "testado, mais barato",
+		rec_free: "testado, gratuito",
+		needsKey: "precisa de uma chave de {x}",
 		noModels: "Ainda não há modelos. Ligue um fornecedor abaixo.",
 		connectProvider: "Ligar um fornecedor",
 		provider: "Fornecedor",
@@ -144,6 +172,13 @@ export const STRINGS = {
 		save: "Guardar",
 		getKey: "Obter uma chave",
 		keyNote: "A chave fica guardada neste computador, na pasta de definições do Sub-Sub, e só é enviada a esse fornecedor.",
+		freeGoogle: "Para experimentar sem pagar: uma chave do Google AI Studio não pede cartão. O nível gratuito limita o texto enviado por minuto e os pedidos por dia, o que chega para experimentar o Sub-Sub; o modelo gratuito testado é o gemini-3.1-flash-lite. Tem de ter 18 anos ou mais. Na UE, no Reino Unido e na Suíça, a Google não usa os seus pedidos para melhorar os produtos; noutros países, no nível gratuito, pode usar.",
+		freeOpenRouter: "Para experimentar sem pagar: os modelos cujo nome termina em :free não custam nada, com 50 pedidos por dia (1000 depois de comprar 10 dólares de crédito). Os fornecedores de alguns modelos gratuitos podem guardar os seus pedidos.",
+		trouble_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 escolha outro modelo no botão do modelo.",
+		trouble_busy: "O fornecedor do modelo está sobrecarregado neste momento. Tente outra vez dentro de alguns minutos ou escolha outro modelo no botão do modelo.",
+		trouble_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 escolha outro modelo.",
+		trouble_key: "O fornecedor do modelo não aceitou a chave da API. Volte a introduzi-la no botão do modelo.",
+		details: "Detalhes",
 		oauthNote: "Para entrar através do site de um fornecedor (por exemplo, com uma subscrição), abra um terminal, escreva subsub e depois /login.",
 		saving: "A guardar",
 		saved: "Guardado.",
@@ -182,6 +217,7 @@ export const STRINGS = {
 		librarianHint: "Só gere a biblioteca: etiquetas, importações, metadados, PDF. Não pesquisa a literatura.",
 		placeholderResearcher: "Pergunte sobre a sua biblioteca ou a literatura, ou escreva / para ver os comandos",
 		placeholderLibrarian: "Peça uma alteração à biblioteca, ou escreva / para ver os comandos",
+		placeholderShort: "Pergunte, ou escreva / para os comandos",
 		emptyResearcher: "O Investigador lê a sua biblioteca, pesquisa na PubMed, Europe PMC e OpenAlex e escreve notas. Também importa, etiqueta e corrige itens: cada alteração mostra uma pré-visualização, e nada muda até a aprovar.",
 		emptyLibrarian: "O Bibliotecário gere a sua biblioteca: etiquetas, importações, metadados e PDF. Cada alteração mostra uma pré-visualização, e nada muda até a aprovar. Para pesquisar e escrever notas, mude para o Investigador.",
 		forBoth: "Usar nos dois modos",

package/web/index.html

@@ -111,6 +111,7 @@
 		</div>
 		<h3 data-i18n="chooseModel">Choose a model</h3>
 		<label class="check"><input type="checkbox" id="model-both"> <span data-i18n="forBoth">Use it in both modes</span></label>
+		<input type="search" id="model-search" class="model-search" data-i18n-placeholder="searchModels" placeholder="Search models" autocomplete="off" spellcheck="false">
 		<ul class="models" id="models"></ul>
 		<h3 data-i18n="connectProvider">Connect a provider</h3>
 		<form id="login-form" class="login">
@@ -121,6 +122,7 @@
 				<input type="password" id="login-key" autocomplete="off" spellcheck="false" required>
 			</label>
 			<p class="small"><a id="login-link" href="#" target="_blank" rel="noopener noreferrer" data-i18n="getKey">Get a key</a></p>
+			<p class="small free-note" id="login-free" hidden></p>
 			<p class="small muted" data-i18n="keyNote"></p>
 			<div class="modal-buttons"><button type="submit" class="primary" id="login-save" data-i18n="save">Save</button></div>
 			<p class="small muted" data-i18n="oauthNote"></p>