@tiagojct/subsub 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Sub-Sub follows the version numbers of npm: a change in the second number (0.13) adds features or changes how you use it; a change in the third (0.13.1) only fixes.
 
+## 0.16.0 (2026-10-08)
+
+For clinical researchers:
+
+- `/ai-statement [what you used it for]` writes a draft of the statement on the use of AI that journals ask for, with the Sub-Sub version, its DOI, your models and Sub-Sub's checks, in `Research/`. The parts in brackets are for you to complete. It is also a button in the browser view.
+- A `/lit` note now says what it is: an AI-assisted rapid review, with one AI screener, no second reviewer and no formal risk-of-bias assessment, for scoping, a background section or a first search, and not a systematic review.
+- The site has a page for clinical researchers, in English and Portuguese: what Sub-Sub does for them, what it is not, how to get it on a hospital computer, moving from EndNote or Mendeley, data protection, and journals and AI. The Install page has a section for your IT service: what is installed, what runs and which addresses it contacts.
+
 ## 0.15.0 (2026-10-08)
 
 Checks:

package/README.md

@@ -99,6 +99,7 @@ Commands in Sub-Sub:
 | `/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 |
+| `/ai-statement [uses]` | A draft statement on the use of AI for a manuscript, with the Sub-Sub version, its DOI and your models |
 | `/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 |
@@ -177,6 +178,12 @@ End-to-end tests (real pi and Python servers, a fake Zotero, a scripted model):
 
 See [CHANGELOG.md](CHANGELOG.md).
 
+## Cite
+
+Jacinto T. Sub-Sub: a research assistant for Zotero [software]. Porto: Faculdade de Medicina da Universidade do Porto; 2026. doi:[10.5281/zenodo.23238602](https://doi.org/10.5281/zenodo.23238602)
+
+This DOI always points to the latest version; each version also has its own DOI on [Zenodo](https://doi.org/10.5281/zenodo.23238602). `CITATION.cff` has the same reference for citation managers.
+
 ## Licence
 
 [MIT](LICENSE), Tiago Jacinto. The `/lit`, `/compare` and `/review` prompts adapt text from [Feynman](https://github.com/Companion-Inc/feynman) (MIT); see [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES). IBM Plex fonts: SIL Open Font License.

package/dist/statement.js

@@ -0,0 +1,35 @@
+/**
+ * /ai-statement: a draft of the statement on the use of AI that journals ask for (ICMJE and
+ * most publishers), with the facts Sub-Sub knows: its version, the models of each mode and their
+ * providers, and the checks the program makes. The authors complete the bracketed parts.
+ */
+export const SUBSUB_DOI = "10.5281/zenodo.23238602";
+/** "opencode-go/mimo-v2.6-pro" -> "mimo-v2.6-pro (OpenCode Go)". */
+export function modelLabel(spec) {
+    const i = spec.indexOf("/");
+    if (i < 0)
+        return spec;
+    const provider = spec.slice(0, i);
+    const names = { "opencode-go": "OpenCode Go", google: "Google", mistral: "Mistral AI", openai: "OpenAI", anthropic: "Anthropic", openrouter: "OpenRouter", deepseek: "DeepSeek" };
+    return `${spec.slice(i + 1)} (${names[provider] ?? provider})`;
+}
+export function aiStatement(f) {
+    const models = [...new Set(Object.values(f.models).filter(Boolean))].map(modelLabel);
+    const modelText = models.length ? `the language model${models.length > 1 ? "s" : ""} ${models.join(" and ")}` : "[the language model and its provider]";
+    const uses = f.uses?.trim() || "[the tasks: for example, literature searches, screening of search results, reading notes on included studies, checks of the references]";
+    return [
+        "## Use of AI tools",
+        "",
+        `We used Sub-Sub ${f.version} (Jacinto T., doi:${SUBSUB_DOI}), an open-source research assistant that works from a Zotero reference library, with ${modelText}, in [month and year]. We used it for ${uses}.`,
+        "",
+        "Sub-Sub records in each note whether it was written from the full text, the abstract or the bibliographic record, checks that quotations are in the full text, and makes no change to the reference library without the authors' approval." +
+            (f.starbuck ? " The cited works were checked for existence, bibliographic accuracy and retraction with Starbuck." : ""),
+        "",
+        "[Choose one: No text of this manuscript was written by an AI tool. | Sub-Sub drafted [which parts]; the authors revised and rewrote this text.]",
+        "",
+        "The authors checked every reference and every statement taken from the sources against the original publications, and take full responsibility for the content of this article.",
+        "",
+        "<!-- Draft made by Sub-Sub on " + f.date + ". Complete the parts in brackets, delete this line, and follow the journal's instructions on where the statement goes (often the Methods or the Acknowledgements). -->",
+        "",
+    ].join("\n");
+}

package/dist/subsub.js

@@ -15,13 +15,14 @@
  * The Python servers start in session_start (not in the factory) and stop in
  * session_shutdown. Tools are registered once and use the current bridge.
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Bridge } from "./bridge.js";
 import { expand, findUv, FREE_MODELS, isProfile, loadConfig, parseEnvFile, saveConfig, serverCommand, starbuckCommand, starbuckEnabled, uiLanguage, who, } from "./config.js";
 import { profileList, profileSpec, promptBlocked } from "./profiles.js";
 import { coerceArgs, loosenArrays, resolvePathArgs } from "./args.js";
+import { aiStatement } from "./statement.js";
 import { applyEdits, checkLiteratureNote, field, frontMatter, itemKeyOf, missingQuotes, quoteProblem, quotesIn } from "./notes.js";
 import { buildPolicy, isSecret, judgePath, normalizeToolPath, realish, within } from "./paths.js";
 import { describeArgs, formatPreview, isEmptyPreview } from "./preview.js";
@@ -673,6 +674,26 @@ export async function createSubsub(pi, deps = {}) {
             await refreshLibrary();
         },
     });
+    pi.registerCommand("ai-statement", {
+        description: "Sub-Sub: a draft statement on the use of AI for a manuscript (what journals ask for)",
+        handler: async (args, ctx) => {
+            const date = new Date().toISOString().slice(0, 10);
+            const text = aiStatement({ version: ownVersion(), models: cfg.models, uses: String(args ?? ""), date, starbuck: starbuckEnabled(cfg) });
+            const dir = join(cfg.vault ?? ctx.cwd, "Research");
+            let file = join(dir, `${date} AI use statement.md`);
+            for (let n = 2; existsSync(file); n++)
+                file = join(dir, `${date} AI use statement-${n}.md`);
+            try {
+                mkdirSync(dir, { recursive: true });
+                writeFileSync(file, text);
+            }
+            catch (err) {
+                ctx.ui.notify(`${text}\n${L("Could not save it", "Não foi possível guardar")}: ${err.message}`, "warning");
+                return;
+            }
+            ctx.ui.notify(L(`Sub-Sub: a draft statement on the use of AI is in ${file}. Complete the parts in brackets. To name the tasks, type /ai-statement followed by them, for example: /ai-statement literature searches and reading notes.`, `Sub-Sub: há um rascunho da declaração sobre o uso de IA em ${file}. Complete as partes entre parênteses retos. Para indicar as tarefas, escreva /ai-statement seguido delas, por exemplo: /ai-statement literature searches and reading notes.`), "info");
+        },
+    });
     pi.registerCommand("history", {
         description: "Sub-Sub: recent library changes",
         handler: async (_args, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiagojct/subsub",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "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/prompts/lit.md

@@ -54,6 +54,7 @@ Write one note: `Research/<date> <slug>.md` in the Sub-Sub folder. Do not overwr
 title: "<question>"
 date: <YYYY-MM-DD>
 type: literature-review
+review_type: AI-assisted rapid review (not a systematic review)
 question: "<question in one sentence>"
 searches: ["<phrasing 1>", "<phrasing 2>", "<phrasing 3>"]
 sources_found: <number of unique works>
@@ -78,6 +79,9 @@ reference_check: "<path of the Starbuck report, or none>"
 ## Methods
 (where you searched, the phrasings, the pre-screen terms, the screening counts, the gap searches, what you included and left out, and why)
 
+## What this review is
+(copy this paragraph as it is) An AI-assisted rapid review: one AI screener, no second reviewer, no registered protocol and no formal risk-of-bias assessment (such as RoB 2 or ROBINS-I). Use it to scope a question, to write a background section or as a first search. For a systematic review, use the searches and the screening log as a starting point, then screen in duplicate, assess the risk of bias and report to PRISMA.
+
 ## Sources
 1. [@citekey] for library items; for other works: Authors, year, title, journal. doi:... (not in library)
 ```

package/src/statement.ts

@@ -0,0 +1,45 @@
+/**
+ * /ai-statement: a draft of the statement on the use of AI that journals ask for (ICMJE and
+ * most publishers), with the facts Sub-Sub knows: its version, the models of each mode and their
+ * providers, and the checks the program makes. The authors complete the bracketed parts.
+ */
+
+export const SUBSUB_DOI = "10.5281/zenodo.23238602";
+
+export interface StatementFacts {
+	version: string;
+	models: Partial<Record<"librarian" | "researcher", string>>;
+	uses?: string;
+	date: string;
+	starbuck: boolean;
+}
+
+/** "opencode-go/mimo-v2.6-pro" -> "mimo-v2.6-pro (OpenCode Go)". */
+export function modelLabel(spec: string): string {
+	const i = spec.indexOf("/");
+	if (i < 0) return spec;
+	const provider = spec.slice(0, i);
+	const names: Record<string, string> = { "opencode-go": "OpenCode Go", google: "Google", mistral: "Mistral AI", openai: "OpenAI", anthropic: "Anthropic", openrouter: "OpenRouter", deepseek: "DeepSeek" };
+	return `${spec.slice(i + 1)} (${names[provider] ?? provider})`;
+}
+
+export function aiStatement(f: StatementFacts): string {
+	const models = [...new Set(Object.values(f.models).filter(Boolean) as string[])].map(modelLabel);
+	const modelText = models.length ? `the language model${models.length > 1 ? "s" : ""} ${models.join(" and ")}` : "[the language model and its provider]";
+	const uses = f.uses?.trim() || "[the tasks: for example, literature searches, screening of search results, reading notes on included studies, checks of the references]";
+	return [
+		"## Use of AI tools",
+		"",
+		`We used Sub-Sub ${f.version} (Jacinto T., doi:${SUBSUB_DOI}), an open-source research assistant that works from a Zotero reference library, with ${modelText}, in [month and year]. We used it for ${uses}.`,
+		"",
+		"Sub-Sub records in each note whether it was written from the full text, the abstract or the bibliographic record, checks that quotations are in the full text, and makes no change to the reference library without the authors' approval." +
+			(f.starbuck ? " The cited works were checked for existence, bibliographic accuracy and retraction with Starbuck." : ""),
+		"",
+		"[Choose one: No text of this manuscript was written by an AI tool. | Sub-Sub drafted [which parts]; the authors revised and rewrote this text.]",
+		"",
+		"The authors checked every reference and every statement taken from the sources against the original publications, and take full responsibility for the content of this article.",
+		"",
+		"<!-- Draft made by Sub-Sub on " + f.date + ". Complete the parts in brackets, delete this line, and follow the journal's instructions on where the statement goes (often the Methods or the Acknowledgements). -->",
+		"",
+	].join("\n");
+}

package/src/subsub.ts

@@ -17,7 +17,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Bridge, type ServerSpec } from "./bridge.ts";
@@ -40,6 +40,7 @@ import {
 } from "./config.ts";
 import { profileList, profileSpec, promptBlocked } from "./profiles.ts";
 import { coerceArgs, loosenArrays, resolvePathArgs } from "./args.ts";
+import { aiStatement } from "./statement.ts";
 import { applyEdits, checkLiteratureNote, field, frontMatter, itemKeyOf, missingQuotes, quoteProblem, quotesIn } from "./notes.ts";
 import { buildPolicy, isSecret, judgePath, normalizeToolPath, realish, within } from "./paths.ts";
 import { describeArgs, formatPreview, isEmptyPreview } from "./preview.ts";
@@ -695,6 +696,31 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		},
 	});
 
+	pi.registerCommand("ai-statement", {
+		description: "Sub-Sub: a draft statement on the use of AI for a manuscript (what journals ask for)",
+		handler: async (args, ctx) => {
+			const date = new Date().toISOString().slice(0, 10);
+			const text = aiStatement({ version: ownVersion(), models: cfg.models, uses: String(args ?? ""), date, starbuck: starbuckEnabled(cfg) });
+			const dir = join(cfg.vault ?? ctx.cwd, "Research");
+			let file = join(dir, `${date} AI use statement.md`);
+			for (let n = 2; existsSync(file); n++) file = join(dir, `${date} AI use statement-${n}.md`);
+			try {
+				mkdirSync(dir, { recursive: true });
+				writeFileSync(file, text);
+			} catch (err) {
+				ctx.ui.notify(`${text}\n${L("Could not save it", "Não foi possível guardar")}: ${(err as Error).message}`, "warning");
+				return;
+			}
+			ctx.ui.notify(
+				L(
+					`Sub-Sub: a draft statement on the use of AI is in ${file}. Complete the parts in brackets. To name the tasks, type /ai-statement followed by them, for example: /ai-statement literature searches and reading notes.`,
+					`Sub-Sub: há um rascunho da declaração sobre o uso de IA em ${file}. Complete as partes entre parênteses retos. Para indicar as tarefas, escreva /ai-statement seguido delas, por exemplo: /ai-statement literature searches and reading notes.`,
+				),
+				"info",
+			);
+		},
+	});
+
 	pi.registerCommand("history", {
 		description: "Sub-Sub: recent library changes",
 		handler: async (_args, ctx) => {

package/web/i18n.js

@@ -270,6 +270,7 @@ export const ACTIONS = {
 		{ cmd: "review", fill: true, profiles: ["author", "editor"], en: "Review a manuscript", pt: "Rever um manuscrito" },
 		{ cmd: "alert", send: true, en: "New publications", pt: "Novas publicações" },
 		{ cmd: "request-copy", fill: true, en: "Ask an author for a copy", pt: "Pedir uma cópia ao autor" },
+		{ cmd: "ai-statement", fill: true, en: "Statement on AI use", pt: "Declaração de uso de IA" },
 		{ cmd: "digest", send: true, profiles: ["scholar", "author", "editor"], en: "Digest of the week", pt: "Resumo da semana" },
 	],
 	library: [