@tiagojct/subsub 0.10.0 → 0.11.1

package/README.md

@@ -1,225 +1,166 @@
 # Sub-Sub
 
-[![npm version](https://img.shields.io/npm/v/@tiagojct/subsub.svg?style=flat-square&color=0b62cf)](https://www.npmjs.com/package/@tiagojct/subsub)
-[![Website](https://img.shields.io/badge/website-subsub.tiagojacinto.eu-e0832a.svg?style=flat-square)](https://subsub.tiagojacinto.eu)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![Node Version](https://img.shields.io/badge/node-%3E%3D22.19.0-339933.svg?style=flat-square)](https://nodejs.org)
-[![Platform: macOS | Linux | Windows](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg?style=flat-square)](#requirements)
+[![npm](https://img.shields.io/npm/v/@tiagojct/subsub.svg?style=flat-square&color=1d4f7c)](https://www.npmjs.com/package/@tiagojct/subsub)
+[![Website](https://img.shields.io/badge/website-subsub.tiagojacinto.eu-a33b14.svg?style=flat-square)](https://subsub.tiagojacinto.eu)
+[![Licence: MIT](https://img.shields.io/badge/licence-MIT-5f5c55.svg?style=flat-square)](LICENSE)
 
-A Zotero librarian and research assistant that runs on your computer, in your browser or in your terminal. It is built on the [pi](https://pi.dev) agent and connects directly to your local Zotero library through Zotero's local API.
+Your research assistant, working from your own Zotero library.
 
-> *"This mere painstaking burrower and grub-worm of a poor devil of a Sub-Sub appears to have gone through the long Vaticans and street-stalls of the earth, picking up whatever random allusions to whales he could anyways find in any book whatsoever."*  
-> — Herman Melville, *Moby-Dick* (Extracts)
+Sub-Sub reads what you already have, finds what you are missing in PubMed, Europe PMC and OpenAlex, and writes notes in Markdown. It also keeps the library in order: it imports, tags and repairs references, and shows you each change before it happens. It runs on your computer, in the browser or in the terminal. It is built on the [pi](https://pi.dev) agent and talks to Zotero through Zotero's local API.
 
----
+Website and guide: https://subsub.tiagojacinto.eu
 
-## Highlights
+> "This mere painstaking burrower and grub-worm of a poor devil of a Sub-Sub appears to have gone through the long Vaticans and street-stalls of the earth, picking up whatever random allusions to whales he could anyways find in any book whatsoever."
+> Herman Melville, Moby-Dick (1851), the Extracts
 
-* **Code-Enforced Safety Gate**: The model **cannot** modify your library without your explicit approval. Every change is calculated first as a dry-run preview (+added in green, -removed in red) and executed only when you confirm.
-* **Full Journal & Reversible Edits**: Every library modification is recorded with a unique journal ID and can be reverted anytime using `/undo`.
-* **One assistant, one switch**: Sub-Sub reads items, searches PubMed, Europe PMC and OpenAlex, finds gaps, checks citations in manuscripts and writes Markdown notes in your Sub-Sub folder (it can sit inside an Obsidian vault). With **library changes** on (the default), it also tags, imports by DOI, PMID or ISBN, repairs metadata, finds duplicates, attaches open-access PDFs and checks retractions, in the same conversation. Turn library changes off (`/library off`, or the switch in the browser view) to read only.
-* **Local & Private**: Listens strictly on `127.0.0.1` protected by an authenticated single-origin session cookie. Your library contents remain on your computer.
-* **Modern Web Interface & Terminal UI**: Use Sub-Sub in your browser with desktop shortcuts (`~/Applications/Sub-Sub.app`, Start menu, or `.desktop`), or launch it right in your terminal with adaptive color themes.
+## What it does
 
----
+Sub-Sub has two modes.
+
+- The Researcher (the default) reads items in your library, searches PubMed, Europe PMC and OpenAlex in one merged search, finds gaps, checks the citations in a manuscript, and writes notes in your Sub-Sub folder. It also does everything the Librarian does, so you can find papers and import and tag them in the same conversation.
+- The Librarian only manages the library: it tags items, imports by DOI, PMID or ISBN, repairs metadata, finds duplicates, attaches open-access PDFs and checks retractions. It has no search tools. Give it a fast, cheap model for long tagging sessions.
+
+Each mode can have its own model. Switch with `/researcher` and `/librarian`, or with the buttons in the browser view.
+
+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.
+- Each change sends the item's version, so an edit you make in Zotero at the same time is not overwritten.
+- Every change is journaled. `/undo` reverts it.
+- Nothing is deleted: items go to the Zotero trash. Only tags from your tag list can be added.
 
 ## Profiles
 
-Profiles calibrate how much Sub-Sub drafts and executes for you. Choose your profile during `subsub init` or change it on the fly with `/profile <name>`.
+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`.
 
-| Profile | Description |
+| Profile | What Sub-Sub does |
 |---|---|
-| **Reader** | Guided and instructional. Reading notes are quotes with page numbers and reflective questions. Never generates unrequested summaries or syntheses. No bulk library edits. |
-| **Scholar** | Full research workflow: literature notes, conceptual syntheses, database searches, alerts, and all library changes. |
-| **Author** | Scholar capabilities plus manuscript workflows: citation auditing against your library, automated Pandoc/Quarto bibliographies, and argument analysis. It critiques but does not write your paragraphs. |
-| **Editor** | Everything unlocked, including drafting full manuscript sections and abstracts upon request. |
-
-> [!NOTE]
-> A profile is your own operational baseline, not a rigid constraint. You can switch between profiles whenever your research focus shifts.
+| Reader | Reading notes with quotations, page numbers and questions for you. No summaries or syntheses unless you ask. No bulk library changes. |
+| Scholar | Literature notes, syntheses, searches, alerts and all library changes. |
+| Author | Scholar, plus manuscript work: citation checks against your library, bibliographies for Pandoc and Quarto, and comments on the argument. It does not write your paragraphs. |
+| Editor | Everything, including drafts of manuscript sections and abstracts when you ask. |
 
----
+The [Profiles page](https://subsub.tiagojacinto.eu/profiles/) lists the tools and commands for each profile and mode.
 
 ## Requirements
 
-* **Zotero 10 or later** running locally. In Zotero, enable:  
-  *Settings > Advanced > "Allow other applications on this computer to communicate with Zotero"*.
-* **Node.js 22.19** or later.
-* **[uv](https://docs.astral.sh/uv/)** fast Python package manager.
-* **Model Provider Account**: Any provider supported by pi (e.g., OpenCode Go, OpenRouter, Anthropic, OpenAI, Mistral, DeepSeek, Google Gemini, or local Ollama).
-* **OS**: macOS, Linux, or Windows.
-
----
+- 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.
+- macOS, Linux or Windows.
 
 ## Install
 
-### Quick Installers
-
-Automated installers handle Node.js, uv, and desktop shortcuts:
-
-* **macOS & Linux**:
-  ```sh
-  curl -fsSL https://subsub.tiagojacinto.eu/install.sh | sh
-  ```
-* **Windows (PowerShell)**:
-  ```powershell
-  powershell -ExecutionPolicy ByPass -c "irm https://subsub.tiagojacinto.eu/install.ps1 | iex"
-  ```
-
-### Manual Installation
-
-1. Install the global package:
-   ```sh
-   npm install -g @tiagojct/subsub
-   ```
-2. Run setup:
-   ```sh
-   subsub init
-   ```
-   Answer the interactive prompts (press <kbd>Enter</kbd> to accept defaults). This creates your Sub-Sub folder (`~/Documents/Sub-Sub`, or `Sub-Sub` inside your Obsidian vault) with `Inbox/`, `Literature/`, `Syntheses/`, `Research/` and `Zotero/`, sets up a starter tag list (`Zotero/Zotero tags.md`), and writes the note formats (`Zotero/Zotero agent.md`).
-3. Verify your environment:
-   ```sh
-   subsub doctor
-   ```
-   Resolve any items marked with `FIX`.
-4. Install system shortcuts:
-   ```sh
-   subsub shortcut
-   ```
-   Creates `~/Applications/Sub-Sub.app` on macOS, Start menu & desktop shortcuts on Windows, or an application launcher on Linux.
-5. Launch Sub-Sub:
-   Open the shortcut or run `subsub web`. Connect your model provider via the **Model** dialog with an API key (or in the terminal via `subsub`, then `/login`).
-
-If you already use [pi](https://pi.dev), you can add Sub-Sub as an extension:
+macOS and Linux:
+
 ```sh
-pi install npm:@tiagojct/subsub
+curl -fsSL https://subsub.tiagojacinto.eu/install.sh | sh
 ```
 
-The underlying Python servers ([zotero-local-mcp](https://github.com/tiagojct/zotero-local-mcp)) run via `uv` from PyPI. To run from a local checkout, specify `"serverDir": "/path/to/zotero-local-mcp"` in your configuration.
+Windows (PowerShell):
 
----
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://subsub.tiagojacinto.eu/install.ps1 | iex"
+```
 
-## Web View
+The installers put everything in your user folder (`~/.subsub`), run `subsub init`, and add a Sub-Sub shortcut. You do not need administrator rights.
 
-Starting Sub-Sub with `subsub web` (or `subsub serve`) launches the browser application:
+With npm:
 
-* **Approval Previews**: Shows server-computed dry-run diffs directly in the UI. Changes are applied only after clicking **Yes** or pressing <kbd>Y</kbd>.
-* **Keyboard-First Review**: In approval dialogs, press <kbd>Y</kbd> or <kbd>Cmd</kbd>/<kbd>Ctrl</kbd>+<kbd>Enter</kbd> to approve, or <kbd>N</kbd>/<kbd>Esc</kbd> to decline.
-* **Library changes switch**: In the header. Off, Sub-Sub reads, searches and writes notes only; the Library actions in the side panel are hidden.
-* **Theme Switcher**: Header toggle between **Light**, **Dark**, and **System** themes.
-* **One-Click Copy**: Built-in copy buttons on all code snippets, BibTeX records, and assistant literature notes.
-* **Session Search & Markdown Export**: Filter conversation history in real time and download full discussions as Markdown notes.
-* **Local Security**: Binds strictly to `127.0.0.1`. The initial link carries a random token that converts into an `HttpOnly`, `SameSite=Strict` cookie. Protected with strict Content Security Policy (CSP), origin validation, and sanitized output.
-* **Auto-Idle Management**: A single daemon serves requests and stops automatically after 10 minutes of inactivity when no pages remain open. Use `--stay` to keep running indefinitely, or `--idle N` to change the timeout.
+```sh
+npm install -g @tiagojct/subsub
+subsub init
+subsub doctor
+```
 
----
+`subsub init` asks a few questions. Press Enter to accept the default. It creates the Sub-Sub folder (`~/Documents/Sub-Sub`, or a `Sub-Sub` folder inside your Obsidian vault) with `Inbox/`, `Literature/`, `Syntheses/`, `Research/` and `Zotero/`, a starter tag list (`Zotero/Zotero tags.md`) and the note formats (`Zotero/Zotero agent.md`). `subsub doctor` checks the set-up; each line marked FIX says what to do.
 
-## Usage
+If you already use pi, you can add Sub-Sub to it: `pi install npm:@tiagojct/subsub`.
 
-### Starting and commands
+Sub-Sub runs its Zotero server, [zotero-local-mcp](https://github.com/tiagojct/zotero-local-mcp), from PyPI with uv.
 
-```sh
-subsub             # Start in the terminal
-subsub --read-only # Start with library changes off (this session only)
-subsub web         # Start browser view
-subsub -c          # Continue the previous session
-subsub -r          # Resume an older session
-```
+## Use
 
-Commands available within Sub-Sub:
-
-* `/library on|off`: Turn library changes on or off (saved). Without an argument, it toggles. `/librarian` and `/researcher`, the two modes before 0.10, still work: on and off.
-* `/profile [name]`: View or change active profile (`reader`, `scholar`, `author`, `editor`).
-* `/subsub`: Display Zotero connection health and library statistics.
-* `/history`: List recent library changes with journal IDs.
-* `/undo [id]`: Revert the last change (or a specific journal ID).
-
-### Built-in Prompt Templates
-
-Type the command followed by arguments:
-
-* **Library** (need library changes on):
-  * `/tag-batch [size]`: Tag untagged items using your tag vocabulary.
-  * `/clean-tags`: Find irregular tags and reconcile with your vocabulary.
-  * `/import-queue [path]`: Import pending references from an inbox note.
-* **Research**:
-  * `/lit <question>`: Literature review: the library first, then PubMed, Europe PMC and OpenAlex in one merged search; reads before it summarises; an evidence table, agreement, disagreement and open questions; references checked; one note in `Research/` (Scholar, Author, Editor).
-  * `/compare <question or citekeys>`: Source matrix (claim, evidence type, caveats, confidence), agreements and disagreements (Scholar, Author, Editor).
-  * `/review <path>`: Critical review of your own manuscript: FATAL, MAJOR and MINOR issues against the reporting guideline that applies (CONSORT, STROBE, PRISMA, STARD, TRIPOD), with quotations and a revision plan. Comments only (Author, Editor).
-  * `/digest [days] [topic]`: Digest of the last days (default 7): what the new notes and alerts change, works worth reading, open questions, decisions for you (Scholar, Author, Editor).
-  * `/request-copy <citekey, DOI or PMID>`: Draft an email to the corresponding author asking for a copy of a paper that is not open access. The address comes from the PubMed record; you send the email yourself.
-  * `/lit-note <citekey>`: Generate an in-depth literature note from item fulltext.
-  * `/synthesis <topic>`: Synthesize library findings on a specific topic.
-  * `/gaps <topic>`: Identify unanswered questions and literature gaps.
-  * `/manuscript <path>`: Cross-check manuscript citations against your library.
-  * `/verify <path> [claims]`: Check that each cited work exists, matches its citation and was not retracted (needs the Starbuck add-on). With `claims`, also check whether each source supports the sentence that cites it.
-  * `/alert`: Check PubMed and OpenAlex for new publications matching research topics.
-
-### Batch Tag Review
-
-To preview or apply batch tag reviews generated in your `Inbox/`:
 ```sh
-subsub review preview 13-31
-subsub review apply 13-31
+subsub web           # in the browser
+subsub               # in the terminal
+subsub --librarian   # in the terminal, in the Librarian
+subsub -c            # continue the last conversation
+subsub --help        # all commands
 ```
 
----
+In the browser view, connect a model provider with the model button. In the terminal, type `/login`.
 
-## Configuration
+Commands in Sub-Sub:
 
-`subsub init` writes settings to `~/.config/subsub/config.json` (or `$SUBSUB_CONFIG`):
+| Command | What it does |
+|---|---|
+| `/researcher`, `/librarian` | Switch the mode |
+| `/profile [name]` | Show or change the profile |
+| `/subsub` | Zotero connection, mode, model and library counts |
+| `/history`, `/undo [id]` | Recent library changes; undo the last one or one by its id |
+| `/tag-batch [size]` | Tag items that have no topic, with your tag list |
+| `/clean-tags` | Find tags that are not in your tag list and propose fixes |
+| `/import-queue [path]` | Import the references in the import queue note |
+| `/lit <question>` | Literature review: the library first, then one merged search; an evidence table, agreement, disagreement and open questions; one note in `Research/` |
+| `/compare <question or citekeys>` | A matrix of sources: claim, evidence, caveats, confidence |
+| `/lit-note <citekey>` | A literature note on one item, from its full text |
+| `/synthesis <topic>` | A synthesis of what the library says on a topic |
+| `/gaps <topic>` | Open questions and gaps in the literature |
+| `/manuscript <path>` | Check a manuscript's citations against the library |
+| `/review <path>` | Comments on your own manuscript against the reporting guideline that applies (CONSORT, STROBE, PRISMA, STARD, TRIPOD, CHEERS, SRQR, COREQ). Comments only, next to the manuscript |
+| `/verify <path> [claims]` | Check that each cited work exists, matches its citation and was not retracted; with `claims`, also whether each source supports its sentence (Starbuck add-on) |
+| `/alert` | New publications for your saved searches |
+| `/digest [days] [topic]` | What changed in the last days: new notes, alerts, works worth reading |
+| `/request-copy <citekey, DOI or PMID>` | A draft email to the corresponding author for a paper that is not open access. You send it yourself |
+
+The library commands work in both modes; the research commands need the Researcher. Some commands depend on the profile (see the Profiles page).
+
+To check or apply a tag review note from `Inbox/` outside Sub-Sub:
 
-| Setting | Type | Description | Default |
-|---|---|---|---|
-| `profile` | string | `reader`, `scholar`, `author`, or `editor` | `"scholar"` |
-| `userName` | string | Name used by the agent in replies | `"the user"` |
-| `about` | string | Brief background context about your research domain | `null` |
-| `language` | string | Response language, or `"auto"` to match your input | `"English"` |
-| `vault` | string | Path to your Sub-Sub folder | `$ZOTERO_VAULT` |
-| `model` | string | The model, as provider/id; `""` to choose it in Sub-Sub | `"opencode-go/mimo-v2.6-pro"` |
-| `libraryChanges` | boolean | Library changes on (each change still needs your Yes) | `true` |
-| `serverDir` | string | Local development path for `zotero-local-mcp` | PyPI package |
-| `look` | boolean| Show header banners and status lines in terminal | `true` |
-| `quotes` | boolean| Display quotes from *Moby-Dick* in terminal banner | `true` |
-| `themes` | string or false | Terminal theme family (`subsub-glauca` or `subsub-try-works`); `false` keeps your pi theme | `"subsub-glauca"` |
-| `addons` | array | Optional servers; `["starbuck"]` adds reference checks | `[]` |
-| `starbuckDir` | string | Local Starbuck folder (used when it has a `pyproject.toml`) | `~/Projects/starbuck` |
+```sh
+subsub review preview 13-31
+subsub review apply 13-31
+```
 
-Server-level configurations (Sub-Sub folder, tag list, alerts file, Unpaywall email) reside in `~/.config/zotero-local-mcp/env`.
+## Settings
 
-### Papers that are not open access
+`subsub init` writes `~/.config/subsub/config.json` (or the file in `$SUBSUB_CONFIG`). You can also edit it.
 
-Sub-Sub finds open-access copies (Unpaywall, Europe PMC). For other papers, use Sub-Sub on your institution's network (at FMUP: the U.Porto network), where the DOI link opens the publisher's version through the library's subscriptions, or use `/request-copy` to ask the author. Sub-Sub does not use unlicensed sources.
+| Setting | Meaning | Default |
+|---|---|---|
+| `profile` | `reader`, `scholar`, `author` or `editor` | `scholar` |
+| `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` |
+| `defaultMode` | `researcher` or `librarian` | `researcher` |
+| `addons` | `["starbuck"]` adds reference checks | `[]` |
+| `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` |
 
-### Reference checks (Starbuck add-on)
+The settings of the Zotero server (Sub-Sub folder, tag list, alerts file, contact email) are in `~/.config/zotero-local-mcp/env`.
 
-[Starbuck](https://github.com/tiagojct/starbuck) checks references: does each cited work exist, do the title, first author and year match, was it retracted or corrected, and (on request) does the source support the sentence that cites it.
+## Privacy
 
-1. Add the add-on to the settings file:
-   ```json
-   "addons": ["starbuck"]
-   ```
-2. Optional: set `"starbuckDir"` to a local copy of Starbuck. Without it, Sub-Sub runs the pinned Starbuck release with uv.
-3. Start Sub-Sub again and run `subsub doctor`. The line `Starbuck` must show `ok`.
+Your library stays in Zotero; Sub-Sub uses Zotero's local API and never your zotero.org account. The model provider you choose receives your messages and what the tools return (titles, abstracts, tags, and passages of full texts when you ask for them). PubMed, Europe PMC, OpenAlex, Crossref, Unpaywall and Open Library receive identifiers and search terms, with your contact email if you gave one. Sub-Sub sends no usage data. The browser view listens only on 127.0.0.1 and needs the random key in the address that `subsub web` opens. Details: https://subsub.tiagojacinto.eu/privacy/
 
-Sub-Sub gets four tools: `verify_check_manuscript`, `verify_check_references`, `verify_prepare_claims` and `verify_record_claims`. Starbuck writes its report to a `_starbuck` folder next to the manuscript. Inside the Sub-Sub folder or the working folder this needs no approval; elsewhere Sub-Sub asks first. Starbuck gets the contact email from the zotero-local-mcp env file. For the claim check, Sub-Sub's own model judges; Starbuck checks that every quoted passage is in the source.
+## Papers that are not open access
 
----
+Sub-Sub finds open-access copies through Unpaywall and Europe PMC. For other papers, use Sub-Sub on your institution's network, where the DOI link opens the publisher's version through the library's subscriptions, or use `/request-copy`. Sub-Sub does not use unlicensed sources.
 
-## Model Evaluation (`subsub-bench`)
+## Reference checks (Starbuck)
 
-Evaluate how accurately different LLMs tag, import, and synthesize literature against your own library without applying changes:
+[Starbuck](https://github.com/tiagojct/starbuck) is an optional add-on. It checks that each cited work exists, that its title, first author and year match the citation, and that it was not retracted or corrected. On request, it also checks whether the source supports the sentence that cites it; Sub-Sub's model judges, and Starbuck checks that every quoted passage is in the source.
 
-```sh
-subsub-bench prepare    # Sample realistic test tasks from your library
-subsub-bench run        # Run models in parallel against safety-isolated sandbox
-subsub-bench score      # Generate objective evaluation scorecard (results.md)
-```
+Turn it on in `subsub init`, with the switch in the browser view, or with `"addons": ["starbuck"]` in the settings. Then `subsub doctor` must show Starbuck ok. Starbuck writes its report in a `_starbuck` folder next to the manuscript.
 
-Measures tag accuracy, adherence to vocabulary, hallucinated citations, token usage, cost, and latency.
+## Model test
 
----
+`subsub-bench` runs several models on the same tasks against your own library and scores them. Nothing in the library changes. See [docs/model-test.md](https://github.com/tiagojct/subsub/blob/main/docs/model-test.md) and the [Models page](https://subsub.tiagojacinto.eu/models/) for the latest results.
 
-## Development & Testing
+## Development
 
 ```sh
 git clone https://github.com/tiagojct/subsub.git
@@ -229,13 +170,8 @@ npm test
 npm run build
 ```
 
-Run end-to-end integration tests (real agent, Python MCP servers, fake Zotero, scripted LLM):
-```sh
-ZLM_DIR=/path/to/zotero-local-mcp npm run test:e2e
-```
-
----
+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`.
 
-## License
+## 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).
+[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

@@ -1,6 +1,6 @@
 /**
  * subsub-bench: the same tasks for several models, against the real library,
- * with no changes applied. See docs/Subsub.md ("Model test").
+ * with no changes applied. See docs/model-test.md.
  *
  *   subsub-bench prepare [--seed 7]        pick the tasks (read-only)
  *   subsub-bench run [--models a,b] [--librarian a,b] [--researcher c,d] [--parallel 3] [--only task]
@@ -20,8 +20,8 @@ import { expand, loadConfig, starbuckCommand, starbuckEnabled } from "./config.j
 import { findUv } from "./subsub.js";
 export const PACKAGE_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 export const DEFAULT_MODELS = {
-    librarian: ["glm-5.3-flash", "deepseek-v4.1-flash", "qwen3.8-flash", "mimo-v2.6-flash", "minimax-m3", "mimo-v2.6-pro"],
-    researcher: ["mimo-v2.6-pro", "deepseek-v4-pro", "kimi-k2.6", "glm-5.3", "qwen3.7-plus", "minimax-m3"],
+    librarian: ["mimo-v2.6-flash", "glm-5.3-flash", "qwen3.8-flash", "gpt-5.6-luna", "hy3", "mimo-v2.6-pro"],
+    researcher: ["mimo-v2.6-pro", "qwen3.8-flash", "kimi-k3", "glm-5.3", "minimax-m3", "gpt-5.6-luna"],
 };
 export const TASKS = {
     librarian: ["tagging", "facet_fix", "import"],
@@ -54,7 +54,7 @@ export function promptFor(task, t, code, out) {
         case "lit_note":
             return t.lit_note
                 ? `Make a literature note for ${t.lit_note.citekey}, following the literature-note format in the shared rules. Read the full text. ` +
-                    `This is a model test: save the note as ${join(out, `${t.lit_note.citekey}.md`)} instead of Resources/Zotero/, and do not attach anything to Zotero.`
+                    `This is a model test: save the note as ${join(out, `${t.lit_note.citekey}.md`)} instead of Literature/ in the Sub-Sub folder, and do not attach anything to Zotero.`
                 : undefined;
         case "synthesis":
             return t.synthesis
@@ -81,7 +81,8 @@ const KEEP = new Set(["tool_execution_start", "tool_execution_end", "message_end
 export function runOne(opts) {
     mkdirSync(opts.out, { recursive: true });
     const args = ["--mode", "rpc", "--no-session", "--provider", opts.provider ?? "opencode-go", "--model", opts.model];
-    args.push("--librarian"); // library changes on for every task
+    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 });
     const events = [];
@@ -557,7 +558,7 @@ 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", model: `opencode-go/${j.model}`, models: undefined, libraryChanges: true }));
+            writeFileSync(cf, JSON.stringify({ ...userCfg, profile: "editor", models: { librarian: `opencode-go/${j.model}`, researcher: `opencode-go/${j.model}` }, model: undefined, libraryChanges: undefined }));
             const s = await runOne({ ...j, prompt, out, cwd: cfg.vault, configFile: cf, timeoutSec });
             n++;
             console.log(`${n}/${jobs.length}  ${j.code}  ${j.task}  ${s.seconds}s  ${s.error ?? (s.settled ? "done" : "?")}`);

package/dist/cli.js

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

package/dist/config.js

@@ -6,13 +6,13 @@
  *   "profile": "scholar",
  *   "userName": "Ana", "about": "a master's student in health informatics", "language": "English",
  *   "vault": "~/Documents/Sub-Sub",
- *   "model": "opencode-go/mimo-v2.6-pro",
- *   "libraryChanges": true
+ *   "models": { "librarian": "opencode-go/mimo-v2.6-flash", "researcher": "opencode-go/mimo-v2.6-pro" },
+ *   "defaultMode": "researcher"
  * }
  *
- * Before 0.10 there were two modes, each with a model ("models": {"librarian",
- * "researcher"}) and "defaultMode". Those keys are still read: the researcher's
- * model becomes the model.
+ * Two modes: the Librarian manages the library; the Researcher does that too,
+ * and searches and writes notes. "model" (0.10) sets one model for both;
+ * "libraryChanges" (0.10) is no longer used.
  *
  * `subsub init` writes this file. Without "serverDir" (or when that folder does
  * not exist), the Zotero servers run from PyPI with uv.
@@ -26,8 +26,11 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { isObsidianVault, settingsFile } from "./layout.js";
-/** The tested model (September 2026 model test). */
-export const DEFAULT_MODEL = "opencode-go/mimo-v2.6-pro";
+/** The tested models, one per mode (model test, see bench-results). */
+export const DEFAULT_MODELS = {
+    librarian: "opencode-go/mimo-v2.6-flash",
+    researcher: "opencode-go/mimo-v2.6-pro",
+};
 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.1";
@@ -107,10 +110,15 @@ export function loadConfig(env = process.env) {
     const envValues = envFile && existsSync(envFile) ? parseEnvFile(envFile) : {};
     const vaultRaw = user.vault ?? env.ZOTERO_VAULT ?? envValues.ZOTERO_VAULT;
     const vault = vaultRaw ? expand(vaultRaw, home) : undefined;
-    // Before 0.10: a model per mode, and themes per mode.
-    const legacyModels = user.models && typeof user.models === "object" ? user.models : undefined;
-    // "model": "" means: the user chooses in pi (/login, /model).
-    const model = "model" in user ? (typeof user.model === "string" && user.model) || undefined : legacyModels ? legacyModels.researcher || legacyModels.librarian || undefined : DEFAULT_MODEL;
+    // "models" per mode; "model" (0.10) for both; {} or "" means: the user chooses in pi (/login, /model).
+    const one = typeof user.model === "string" ? user.model : undefined;
+    const given = user.models && typeof user.models === "object" ? user.models : undefined;
+    // Without a settings file (no subsub init yet), the user chooses in pi: no default that may lack a key.
+    const fallback = existsSync(file) ? { ...DEFAULT_MODELS } : {};
+    const models = given ?? (one !== undefined ? { librarian: one || undefined, researcher: one || undefined } : fallback);
+    for (const k of Object.keys(models))
+        if (!models[k])
+            delete models[k];
     const themes = user.themes === false ? false : typeof user.themes === "string" ? user.themes : user.themes?.researcher;
     return {
         configFile: file,
@@ -122,8 +130,8 @@ export function loadConfig(env = process.env) {
         serverDir: expand(user.serverDir ?? "~/Projects/zotero-local-mcp", home),
         envFile,
         vault,
-        model,
-        libraryChanges: user.libraryChanges !== false,
+        models,
+        defaultMode: user.defaultMode === "librarian" ? "librarian" : "researcher",
         // A Sub-Sub folder inside an Obsidian vault also reads the vault's context file.
         vaultContext: (user.vaultContext ??
             (vault ? [join(vault, ".claude", "CLAUDE.md"), ...(isObsidianVault(dirname(vault)) ? [join(dirname(vault), ".claude", "CLAUDE.md")] : [])] : [])).map((p) => expand(p, home)),

package/dist/doctor.js

@@ -80,7 +80,8 @@ export function runChecks(cfg, env, deps = {}) {
         : { name: "Zotero", ok: false, detail: String(st.error ?? "not reachable"), fix: `Start Zotero 10 or later. ${ZOTERO_SETTING}` });
     const v = st.vocabulary ?? {};
     if (v.loaded === false || !v.tags) {
-        out.push({ name: "Tag list", ok: false, detail: v.path ? `cannot read ${v.path}` : "not set", fix: "Type subsub init: it creates a starter tag list." });
+        const path = v.path && v.path !== "None" ? v.path : undefined; // the server writes Python's None when unset
+        out.push({ name: "Tag list", ok: false, detail: path ? `cannot read ${path}` : "not set", fix: "Type subsub init: it creates a starter tag list." });
     }
     else {
         const noTopics = Array.isArray(v.facets) && !v.facets.includes("topic");
@@ -104,7 +105,7 @@ export function runChecks(cfg, env, deps = {}) {
         out.push(starbuckCheck(cfg, env, run));
     const agentDir = deps.agentDir ?? (env.SUBSUB_AGENT_DIR ? env.SUBSUB_AGENT_DIR : join(homedir(), ".subsub", "agent"));
     out.push(hasLogin(agentDir)
-        ? { name: "Model login", ok: true, detail: cfg.model ?? "pi's default model" }
+        ? { name: "Model login", ok: true, detail: Object.keys(cfg.models).length ? Object.entries(cfg.models).map(([m, id]) => `${m} ${id}`).join(", ") : "pi's default model" }
         : { name: "Model login", ok: false, detail: "no model provider yet", fix: "Type subsub, then /login." });
     return out;
 }