@tiagojct/subsub 0.7.0 → 0.9.0

package/docs/Subsub.md

@@ -1,18 +1,19 @@
-Sub-Sub is a Zotero librarian and research assistant that runs in pi. It uses the same Python servers as the OpenCode setup ([[Zotero MCP]]), so the library safety is the same: previews, version checks, journal and undo, the tag vocabulary. The OpenCode setup keeps working in parallel.
+Sub-Sub is a Zotero librarian and research assistant that runs in pi. It uses the Python servers of zotero-local-mcp for the library: previews, version checks, journal and undo, the tag vocabulary.
 
 - Code: ~/Projects/subsub (git). Servers: ~/Projects/zotero-local-mcp
 - Shared rules: [[Zotero agent]]. Tag vocabulary: [[Zotero tags]]
-- Settings: ~/.config/subsub/config.json (written by `subsub init`) and ~/.config/opencode/zotero.env (same file as OpenCode)
+- Settings: ~/.config/subsub/config.json (written by `subsub init`) and ~/.config/zotero-local-mcp/env (also read by the weekly alerts in launchd)
+- Sub-Sub folder: ~/Obsidian/Powerslave/Sub-Sub, with Inbox/, Literature/, Syntheses/, Research/ and Zotero/ (tag list, note formats, alert searches). Sub-Sub writes only there without asking.
 - Models: librarian opencode-go/glm-5.3-flash, researcher opencode-go/mimo-v2.6-pro
 - Public docs: the README in ~/Projects/subsub (source for subsub.tiagojacinto.eu)
 
-## Differences from the OpenCode setup
+## Safety
 
 - Approval is enforced in code. Before any library change, Sub-Sub asks the server for the preview and shows it in a dialog. The change runs only after you select Yes. The model cannot skip this.
 - The model does not need to do a dry run first. You see one dialog per change.
 - Library tools run one at a time, so each preview includes the effect of earlier changes in the same step.
 - The researcher does not have the library write tools at all. It can only add a linked note (with a dialog) and add works to the import queue.
-- bash is off in both modes. File writes outside the vault, and writes to the rule files, config folders and code folders, need a Yes.
+- bash is off in both modes. File writes outside the Sub-Sub folder, and writes to the rule files, config folders and code folders, need a Yes.
 
 ## Install
 
@@ -20,9 +21,9 @@ Sub-Sub is a Zotero librarian and research assistant that runs in pi. It uses th
 2. Type `cd ~/Projects/subsub && npm install --omit=dev`.
 3. Type `npm link`. This adds the `subsub` command.
 4. Optional: type `pi remove ~/Projects/subsub`. Then plain `pi` stays a plain coding agent without Sub-Sub.
-5. Type `subsub`. If pi already has your OpenCode Go key, Sub-Sub uses the same key. If not, type `/login`, select OpenCode Zen and Go, and paste the key.
+5. Type `subsub`. If pi has no OpenCode Go key yet, type `/login`, select OpenCode Zen and Go, and paste the key.
 6. Type `/subsub`. Make sure that the result shows "Zotero: reachable" and the model mimo-v2.6-pro.
-7. Type `subsub init` once. Keep the notes folder (the vault), the tag list, the email and the models. For the profile, select Editor.
+7. Type `subsub init` once. Keep the Sub-Sub folder, the tag list, the email and the models. For the profile, select Editor.
 8. Type `subsub doctor`. Make sure that no line shows FIX.
 
 If you change the Node version with fnm, do step 3 again.
@@ -30,7 +31,7 @@ If you change the Node version with fnm, do step 3 again.
 ## Use
 
 1. Start Zotero.
-2. Type `subsub`. From the home folder, Sub-Sub starts in the vault. From a different folder (for example a manuscript folder), it starts in that folder. To stay in the home folder, type `subsub --here`.
+2. Type `subsub`. From the home folder, Sub-Sub starts in the Sub-Sub folder. From a different folder (for example a manuscript folder), it starts in that folder. To stay in the home folder, type `subsub --here`.
 3. Sub-Sub starts in the researcher mode. To start in the librarian mode, type `subsub --librarian`.
 4. To change the mode, type `/librarian` or `/researcher`. The mode also changes the model.
 5. When a dialog shows a preview, read it. Select Yes to apply the change, or No to stop it. After No, tell Sub-Sub what to change.
@@ -105,7 +106,7 @@ The themes are in ~/Projects/subsub/themes. To make them again after a change in
 
 ## Model test
 
-The model test runs several models on the same tasks against your library and compares them. Nothing in the library changes: each library change is recorded with its preview and then blocked. Notes go to ~/Projects/subsub/bench-results/<date>/, not to the vault.
+The model test runs several models on the same tasks against your library and compares them. Nothing in the library changes: each library change is recorded with its preview and then blocked. Notes go to ~/Projects/subsub/bench-results/<date>/, not to the Sub-Sub folder.
 
 Tasks:
 
@@ -131,7 +132,7 @@ Each model gets a code (for example M417), so the notes can be judged blind. key
 - "command not found: subsub": type `cd ~/Projects/subsub && npm link`.
 - To update Sub-Sub after new code arrives, type `cd ~/Projects/subsub && npm install --omit=dev`. Do not use `subsub update`.
 - A tool call is refused with "not available in researcher mode": type `/librarian`.
-- `subsub review` says "No note matches": check the note numbers in Inbox/. A path is written from the vault folder, in quotes (for example "Inbox/Zotero tag review 13.md").
+- `subsub review` says "No note matches": check the note numbers in Inbox/. A path is written from the Sub-Sub folder, in quotes (for example "Inbox/Zotero tag review 13.md").
 
 ## Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiagojct/subsub",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Sub-Sub: a Zotero librarian and research assistant in the browser or the terminal, built on pi",
   "type": "module",
   "license": "MIT",
@@ -29,7 +29,7 @@
     "@modelcontextprotocol/sdk": "^1.30.1"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^1.0.2"
+    "@earendil-works/pi-coding-agent": "^1.0.4"
   },
   "engines": {
     "node": ">=22.19.0"
@@ -61,7 +61,7 @@
     "THIRD_PARTY_NOTICES"
   ],
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.0.2",
+    "@earendil-works/pi-coding-agent": "1.0.4",
     "@types/node": "^24.19.0",
     "typescript": "^5.9.3"
   },

package/prompts/compare.md

@@ -17,7 +17,7 @@ Make a short slug: lower case, hyphens, at most five words. Use today's date (YY
    - Confidence: high, moderate or low, with one reason.
 4. Below the matrix, write: where the sources agree; where they disagree and the most likely reason (population, design, outcome definition, analysis); what no source answers. Cite source numbers in every sentence. Write "inference:" before a statement that no single source makes.
 5. Check the sources: verify_check_references when the verify_ tools are available, otherwise scholar_get_work for each identifier. Never write "verified" for a check you did not run.
-6. Write one note: `Research/<date> <slug> comparison.md` in the notes folder (do not overwrite; add -2). Front matter: title, date, type: comparison, sources (the identifiers), verification (PASS, PASS WITH NOTES or BLOCKED), reference_check (path of the Starbuck report, or none). End with a Sources section: [@citekey] for library items, full reference with DOI and "(not in library)" for the others.
+6. Write one note: `Research/<date> <slug> comparison.md` in the Sub-Sub folder (do not overwrite; add -2). Front matter: title, date, type: comparison, sources (the identifiers), verification (PASS, PASS WITH NOTES or BLOCKED), reference_check (path of the Starbuck report, or none). End with a Sources section: [@citekey] for library items, full reference with DOI and "(not in library)" for the others.
 7. If a step fails, finish the note anyway and mark the step "BLOCKED: <what failed>".
 
 Give the user the path and three lines on what the comparison shows.

package/prompts/digest.md

@@ -4,7 +4,7 @@ argument-hint: "[days, default 7] [topic]"
 ---
 Write a digest of the last ${1:-7} days. Topic, if given: ${@:2}
 
-1. Collect, in the notes folder:
+1. Collect, in the Sub-Sub folder:
    - the alert notes `Inbox/Literature alerts YYYY-MM-DD.md` dated in the period (the date is in the file name);
    - the notes in `Research/` whose front matter `date:` is in the period;
    - the literature notes whose front matter `created:` is in the period.

package/prompts/lit.md

@@ -11,7 +11,7 @@ Make a short slug from the topic: lower case, hyphens, at most five words. Use t
 1. Write the question in one sentence. If it is a clinical question, state population, exposure or intervention, comparison and outcome when they apply.
 2. Decide the scale:
    - Narrow question ("what is X", one fact, one test): at most 10 tool calls, a short answer, no plan file.
-   - Review question: write the plan to `Research/.plans/<slug>.md` in the notes folder: the question, the search phrasings, the study designs that answer it (for example randomised trials, cohorts, diagnostic accuracy studies, systematic reviews), the years, and a task list.
+   - Review question: write the plan to `Research/.plans/<slug>.md` in the Sub-Sub folder: the question, the search phrasings, the study designs that answer it (for example randomised trials, cohorts, diagnostic accuracy studies, systematic reviews), the years, and a task list.
 3. Tell the user the plan in three lines. Then continue at once. Do not wait for an answer unless the user asked to see the plan first.
 
 ## 2. Gather
@@ -47,7 +47,7 @@ Make a short slug from the topic: lower case, hyphens, at most five words. Use t
 
 ## 6. Deliver
 
-Write one note: `Research/<date> <slug>.md` in the notes folder. Do not overwrite an existing note; add -2 to the name. Use this structure:
+Write one note: `Research/<date> <slug>.md` in the Sub-Sub folder. Do not overwrite an existing note; add -2 to the name. Use this structure:
 
 ```markdown
 ---

package/prompts/request-copy.md

@@ -6,7 +6,7 @@ Draft an email to ask the corresponding author of $1 for a copy of the paper.
 
 1. Find the work: zotero_get_item for a citekey or Zotero key, otherwise scholar_get_work. If it is open access (open_access, or scholar_read_oa_fulltext gives the full text), tell the user where to read it and stop: no email is needed.
 2. Find the address with scholar_find_contact. Use only an address it returns. Never guess or build an address from a name. If it returns none, give the user the article link and say: look for "Correspondence" on the article page; then stop.
-3. Write the draft to `Inbox/Copy request <citekey or DOI>.md` in the notes folder (do not overwrite; add -2):
+3. Write the draft to `Inbox/Copy request <citekey or DOI>.md` in the Sub-Sub folder (do not overwrite; add -2):
 
 ```markdown
 ---

package/roles/researcher.md

@@ -1,6 +1,6 @@
 You are Sub-Sub, the research assistant for {{user}}. {{about}} Reply briefly. No emojis.
 
-You read the Zotero library (zotero_ read tools), search PubMed, Europe PMC and OpenAlex (scholar_ tools) and write notes in the notes folder. You cannot change the library, with one exception: scholar_attach_note adds a short child note (summary plus obsidian:// link). To add works, use scholar_queue_imports; {{user}} ticks them and the librarian (/librarian) imports them.
+You read the Zotero library (zotero_ read tools), search PubMed, Europe PMC and OpenAlex (scholar_ tools) and write notes in the Sub-Sub folder. You cannot change the library, with one exception: scholar_attach_note adds a short child note (summary plus obsidian:// link). To add works, use scholar_queue_imports; {{user}} ticks them and the librarian (/librarian) imports them.
 
 ## Always
 
@@ -32,7 +32,7 @@ You read the Zotero library (zotero_ read tools), search PubMed, Europe PMC and
 ## Literature notes and syntheses
 
 - Follow the formats in the shared rules.
-- After a literature note is written, offer scholar_attach_note with 3 to 4 lines of summary and the path of the vault note.
+- After a literature note is written, offer scholar_attach_note with 3 to 4 lines of summary and the path of the note.
 - For a synthesis: show the candidate list first and let {{user}} choose. Read full texts only for the chosen items.
 - For a synthesis of a tag ("what does my library say about X"): find the items with zotero_find_items tags=["topic/x"] and include every one. The table has one row per item; if you leave an item out, say which and why.
 - Say for each item whether you used the full text or the abstract. Never state a number or a claim that is not in what you read.

package/src/config.ts

@@ -5,7 +5,7 @@
  * {
  *   "profile": "scholar",
  *   "userName": "Ana", "about": "a master's student in health informatics", "language": "English",
- *   "vault": "~/Notes",
+ *   "vault": "~/Documents/Sub-Sub",
  *   "models": { "librarian": "opencode-go/glm-5.3-flash", "researcher": "opencode-go/mimo-v2.6-pro" },
  *   "defaultMode": "researcher"
  * }
@@ -22,6 +22,7 @@
 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.ts";
 
 export type Mode = "librarian" | "researcher";
 export type Profile = "reader" | "scholar" | "author" | "editor";
@@ -160,11 +161,15 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): SubsubConfig {
 			researcher: "opencode-go/mimo-v2.6-pro",
 		},
 		defaultMode: mode,
-		vaultContext: (user.vaultContext ?? (vault ? [join(vault, ".claude", "CLAUDE.md")] : [])).map((p) => expand(p, home)),
+		// 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)),
 		sharedRules: user.sharedRules
 			? expand(user.sharedRules, home)
 			: vault
-				? join(vault, "Systems", "Zotero agent.md")
+				? settingsFile(vault, "rules")
 				: undefined,
 		startTimeout: user.startTimeout ?? 45,
 		uvPath: user.uvPath ? expand(user.uvPath, home) : undefined,

package/src/doctor.ts

@@ -21,6 +21,7 @@ import {
 	starbuckEnabled,
 	type SubsubConfig,
 } from "./config.ts";
+import { isObsidianVault, LEGACY_SETTINGS_DIR, SETTINGS_FILES, settingsFile } from "./layout.ts";
 import { profileSpec } from "./profiles.ts";
 
 export interface Check {
@@ -137,11 +138,7 @@ export function runChecks(
 					: undefined,
 		});
 	}
-	out.push(
-		cfg.vault && existsSync(cfg.vault)
-			? { name: "Notes folder", ok: true, detail: cfg.vault }
-			: { name: "Notes folder", ok: false, detail: cfg.vault ? `${cfg.vault} does not exist` : "not set", fix: "Type subsub init." },
-	);
+	out.push(folderCheck(cfg.vault));
 	out.push(
 		st.contact_email_set
 			? { name: "Contact email", ok: true, detail: "set" }
@@ -199,3 +196,19 @@ export async function doctorMain(env: NodeJS.ProcessEnv = process.env): Promise<
 	console.log(bad ? `\n${bad} problem(s) to fix.` : "\nEverything needed is in place.");
 	return bad ? 1 : 0;
 }
+
+/** The Sub-Sub folder: it exists, it is not a whole vault, and its settings files are in Zotero/. */
+export function folderCheck(folder: string | undefined): Check {
+	const name = "Sub-Sub folder";
+	if (!folder || !existsSync(folder)) {
+		return { name, ok: false, detail: folder ? `${folder} does not exist` : "not set", fix: "Type subsub init." };
+	}
+	if (isObsidianVault(folder)) {
+		return { name, ok: true, warn: true, detail: `${folder} is a whole Obsidian vault`, fix: "Type subsub init: it moves Sub-Sub's files into a Sub-Sub folder inside the vault." };
+	}
+	const legacy = (["rules", "tags", "alerts"] as const).some((w) => settingsFile(folder, w) === join(folder, LEGACY_SETTINGS_DIR, SETTINGS_FILES[w]));
+	if (legacy) {
+		return { name, ok: true, warn: true, detail: `${folder}; the settings files are still in ${LEGACY_SETTINGS_DIR}/`, fix: "Type subsub init: it moves them to Zotero/." };
+	}
+	return { name, ok: true, detail: folder };
+}

package/src/init.ts

@@ -6,14 +6,20 @@
  * - the settings file (~/.config/subsub/config.json): profile, name, language,
  *   notes folder, models;
  * - the server settings file (~/.config/zotero-local-mcp/env, or the one that
- *   already exists): notes folder, tag list, contact email. Other lines stay;
- * - in the notes folder: Inbox/, Systems/Zotero tags.md (a starter list) and
- *   Systems/Zotero agent.md (note formats). Existing files are never replaced.
+ *   already exists): the Sub-Sub folder, tag list, alerts file, contact email.
+ *   Other lines stay;
+ * - the Sub-Sub folder (see layout.ts): Inbox/, Literature/, Syntheses/,
+ *   Research/, and Zotero/ with Zotero tags.md (a starter list) and Zotero
+ *   agent.md (note formats). Existing files are never replaced.
+ *
+ * An Obsidian vault given as the folder becomes <vault>/Sub-Sub. Files of the old
+ * layout (Systems/, or Sub-Sub's notes in the Inbox/ of a whole vault) are moved
+ * when the user agrees.
  *
  * Flags (for scripts and tests): --yes (take every default), --setup
- * standard|fmup, --name, --about, --language, --notes, --profile, --tags
- * health-sciences|health-informatics|any-field, --email, --starbuck on|off,
- * --models keep|later|opencode-go.
+ * 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.
  */
 
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -35,6 +41,7 @@ import {
 	withStarbuck,
 } 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 { PROFILE_SPECS } from "./profiles.ts";
 
 const TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates");
@@ -58,6 +65,7 @@ export interface InitResult {
 	envFile: string;
 	notes: string;
 	created: string[];
+	moved: number;
 	zotero: boolean;
 }
 
@@ -108,8 +116,18 @@ export async function runInit(
 	const envValues = existsSync(envFile) ? parseEnvFile(envFile) : {};
 	const created: string[] = [];
 
-	io.say(existsSync(configFile) ? `Sub-Sub settings (${configFile}). Press Enter to keep the value in brackets.` : "Sub-Sub setup. Press Enter to take the value in brackets.");
+	const first = !existsSync(configFile);
+	io.say(
+		first
+			? "Sub-Sub setup. A few questions; press Enter to take the value in brackets. To change an answer later, type subsub init again."
+			: `Sub-Sub settings (${configFile}). Press Enter to keep the value in brackets.`,
+	);
+	const explain = (title: string, text: string) => {
+		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",
 		[
@@ -119,45 +137,92 @@ export async function runInit(
 		flags.setup ?? existing.setup ?? "standard",
 	);
 	const fmup = setup === "fmup";
-	const userName = (await io.ask("Your name, for Sub-Sub's replies (Enter for none)", flags.name ?? existing.userName ?? "")).trim();
+
+	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();
 	const language = (await io.ask("Language for replies and notes (a language, or auto for the language you write in)", flags.language ?? existing.language ?? "English")).trim() || "English";
-	const notes = expand(
-		(await io.ask("Notes folder (Markdown files; an Obsidian vault works)", flags.notes ?? current.vault ?? envValues.ZOTERO_VAULT ?? join(home, "Documents", "Sub-Sub"))).trim(),
-		home,
+
+	explain(
+		"Sub-Sub folder",
+		`Sub-Sub keeps everything it writes in one folder: Inbox/ (review notes, the import queue, alerts), Literature/, Syntheses/, Research/, and ${SETTINGS_DIR}/ (your tag list and note formats). If you use Obsidian, give the vault folder: Sub-Sub then works in a ${FOLDER_NAME} folder inside the vault and leaves the rest of the vault alone.`,
 	);
+	const oldFolder = current.vault;
+	// Without questions (--yes), an existing folder stays exactly as it is.
+	const keepAsIs = Boolean(flags.yes) && !flags.folder && !flags.notes && oldFolder !== undefined;
+	const folderDefault = flags.folder ?? flags.notes ?? (oldFolder ? (keepAsIs ? oldFolder : subsubFolder(oldFolder)) : join(home, "Documents", FOLDER_NAME));
+	const answer = expand((await io.ask("Sub-Sub folder (or an Obsidian vault)", folderDefault)).trim() || folderDefault, home);
+	const notes = keepAsIs && answer === oldFolder ? answer : subsubFolder(answer);
+	if (notes !== answer) io.say(`That is an Obsidian vault. Sub-Sub will use ${notes}.`);
+
+	// ---- files of the old layout
+	const from = oldFolder && existsSync(oldFolder) ? oldFolder : notes;
+	const moves = planMoves(from, notes);
+	let move = "no";
+	if (moves.length) {
+		explain(
+			"Earlier files",
+			`${moves.length} file(s) from an earlier Sub-Sub layout can move into ${notes}: the settings files go to ${SETTINGS_DIR}/, and Sub-Sub's review notes, alerts and import queue go to Inbox/. Nothing is replaced.`,
+		);
+		for (const m of moves.slice(0, 6)) io.say(`  ${m.from}`);
+		if (moves.length > 6) io.say(`  and ${moves.length - 6} more`);
+		move = await io.choose(
+			"Move them",
+			[
+				{ value: "yes", label: "Move them (recommended)" },
+				{ value: "no", label: from === notes ? "Leave them; Sub-Sub still reads them from Systems/" : "Leave them where they are" },
+			],
+			flags.move ?? (flags.yes ? "no" : "yes"),
+		);
+	}
+
+	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 (change it later with /profile)",
+		"Profile",
 		PROFILES.map((p) => ({ value: p, label: `${PROFILE_SPECS[p].label}: ${PROFILE_SPECS[p].summary}` })),
 		isProfile(profileDefault) ? profileDefault : "scholar",
 	);
 
-	const vocab = envValues.ZOTERO_VOCAB ? expand(envValues.ZOTERO_VOCAB, home) : join(notes, "Systems", "Zotero tags.md");
+	// The tag list: a custom path in the server settings stays; otherwise Zotero/Zotero tags.md (moved, kept or new).
+	const vocabTarget = join(notes, SETTINGS_DIR, SETTINGS_FILES.tags);
+	const oldDefaults = new Set([join(from, "Systems", SETTINGS_FILES.tags), join(from, SETTINGS_DIR, SETTINGS_FILES.tags)]);
+	const envVocab = envValues.ZOTERO_VOCAB ? expand(envValues.ZOTERO_VOCAB, home) : undefined;
+	const customVocab = envVocab && existsSync(envVocab) && !oldDefaults.has(envVocab) && envVocab !== vocabTarget ? envVocab : undefined;
+	const movingVocab = move === "yes" && moves.some((m) => m.to === vocabTarget);
+	// An old tag list counts only in the same folder; a new folder gets the moved list or a new one.
+	const legacyVocab = !movingVocab && from === notes && [...oldDefaults].find((p) => existsSync(p));
+	const vocab = customVocab ?? (movingVocab || existsSync(vocabTarget) ? vocabTarget : legacyVocab || vocabTarget);
 	let tags = "keep";
-	if (existsSync(vocab)) {
+	if (existsSync(vocab) || movingVocab) {
+		io.say("");
 		io.say(`Tag list: keeping ${vocab}.`);
 	} else {
+		explain("Tag list", `The librarian tags items only with the tags in this list. Pick a start; you edit the list later in ${SETTINGS_DIR}/${SETTINGS_FILES.tags}.`);
 		tags = await io.choose(
-			"Starter tag list (edit it later in the notes folder)",
+			"Starter tag list",
 			Object.entries(STARTER_TAGS).map(([value, label]) => ({ value, label })),
 			flags.tags ?? (fmup ? "health-sciences" : "any-field"),
 		);
 	}
-	const email = (
-		await io.ask("Email for Unpaywall and Crossref, to find open-access PDFs (optional)", flags.email ?? envValues.ZOTERO_CONTACT_EMAIL ?? "")
-	).trim();
+
+	explain("Contact email", "Unpaywall needs an email address to find open-access PDFs. Sub-Sub sends it only to Unpaywall, Crossref, OpenAlex and PubMed, as they ask.");
+	const email = (await io.ask("Email (optional)", flags.email ?? envValues.ZOTERO_CONTACT_EMAIL ?? "")).trim();
+
+	explain("Reference checks (Starbuck)", "An optional add-on for manuscripts: it checks that each cited work exists, matches its citation and was not retracted. The researcher then has /verify.");
 	const starbuck = await io.choose(
-		"Reference checks (Starbuck): check that cited works exist, match their citation and were not retracted",
+		"Reference checks",
 		[
 			{ value: "off", label: "Off" },
-			{ value: "on", label: "On (the researcher gets /verify; uses the email above)" },
+			{ value: "on", label: "On (downloads Starbuck now; uses the email above)" },
 		],
 		flags.starbuck ?? (starbuckEnabled(current) ? "on" : "off"),
 	);
+
+	explain("Models", "Sub-Sub needs an account with a model provider. You can connect one later in Sub-Sub with the model button (or /login in the terminal).");
 	const modelOptions = [
 		...(existing.models ? [{ value: "keep", label: `Keep: ${JSON.stringify(existing.models)}` }] : []),
-		{ value: "later", label: "Choose later in Sub-Sub (/login, then /model)" },
+		{ 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` },
 	];
 	const agentDir = initEnv.SUBSUB_AGENT_DIR ? expand(initEnv.SUBSUB_AGENT_DIR, home) : join(home, ".subsub", "agent");
@@ -165,7 +230,8 @@ export async function runInit(
 	const models = await io.choose("Models", modelOptions, flags.models ?? modelDefault);
 
 	// ---- write
-	for (const dir of [notes, join(notes, "Inbox"), join(notes, "Systems")]) {
+	if (move === "yes") applyMoves(moves);
+	for (const dir of [notes, ...NOTE_DIRS.map((d) => join(notes, d)), join(notes, SETTINGS_DIR)]) {
 		if (!existsSync(dir)) {
 			mkdirSync(dir, { recursive: true });
 			created.push(dir);
@@ -176,14 +242,18 @@ export async function runInit(
 		copyFileSync(join(TEMPLATES, "vocabularies", `${tags}.md`), vocab);
 		created.push(vocab);
 	}
-	const rules = join(notes, "Systems", "Zotero agent.md");
-	if (!existsSync(rules)) {
-		copyFileSync(join(TEMPLATES, "Zotero agent.md"), rules);
-		created.push(rules);
+	const rulesTarget = join(notes, SETTINGS_DIR, SETTINGS_FILES.rules);
+	const legacyRules = join(notes, "Systems", SETTINGS_FILES.rules);
+	if (!existsSync(rulesTarget) && !existsSync(legacyRules)) {
+		copyFileSync(join(TEMPLATES, "Zotero agent.md"), rulesTarget);
+		created.push(rulesTarget);
 	}
+	const alertsTarget = join(notes, SETTINGS_DIR, SETTINGS_FILES.alerts);
+	const legacyAlerts = join(notes, "Systems", SETTINGS_FILES.alerts);
+	const alerts = !existsSync(alertsTarget) && existsSync(legacyAlerts) ? legacyAlerts : alertsTarget;
 	mkdirSync(dirname(envFile), { recursive: true });
 	const before = existsSync(envFile) ? readFileSync(envFile, "utf8") : "# Settings for the Sub-Sub Zotero servers (zotero-local-mcp). Written by subsub init.\n";
-	writeFileSync(envFile, upsertEnv(before, { ZOTERO_VAULT: notes, ZOTERO_VOCAB: vocab, ZOTERO_CONTACT_EMAIL: email || undefined }));
+	writeFileSync(envFile, upsertEnv(before, { ZOTERO_VAULT: notes, ZOTERO_VOCAB: vocab, ZOTERO_ALERTS: alerts, ZOTERO_CONTACT_EMAIL: email || undefined }));
 
 	const patch: Record<string, unknown> = {
 		profile,
@@ -205,6 +275,8 @@ export async function runInit(
 	io.say(`Saved: ${configFile}`);
 	io.say(`Saved: ${envFile}`);
 	for (const c of created) io.say(`Created: ${c}`);
+	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(
 		zotero
 			? "Zotero: reachable."
@@ -213,7 +285,7 @@ export async function runInit(
 	if (starbuck === "on") io.say(starbuckNote || "Reference checks: on. The first start downloads Starbuck.");
 	if (fmup) io.say("FMUP / U.Porto: the FMUP model service will come in a later version. Until then, connect a model provider yourself.");
 	io.say("Next: type subsub web to open Sub-Sub in your browser (or subsub for the terminal). Connect a model provider with the model button (or /login in the terminal). To check the setup, type subsub doctor.");
-	return { configFile, envFile, notes, created, zotero };
+	return { configFile, envFile, notes, created, moved: move === "yes" ? moves.length : 0, zotero };
 }
 
 export function parseFlags(args: string[]): Record<string, string> {
@@ -266,7 +338,8 @@ function terminalIO(): InitIO & { close(): void } {
 
 export async function initMain(args: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
 	const flags = parseFlags(args);
-	const io = flags.yes || !process.stdin.isTTY ? defaultsIO((l) => console.log(l)) : terminalIO();
+	if (!process.stdin.isTTY) flags.yes ??= "true";
+	const io = flags.yes ? defaultsIO((l) => console.log(l)) : terminalIO();
 	try {
 		await runInit(io, flags, env, { prepareStarbuck: (cfg) => {
 			// Download Starbuck now, so that the first start of Sub-Sub does not wait for it.

package/src/layout.ts

@@ -0,0 +1,103 @@
+/**
+ * The Sub-Sub folder: everything Sub-Sub writes lives in one folder, by default
+ * "Sub-Sub" (~/Documents/Sub-Sub, or <vault>/Sub-Sub inside an Obsidian vault):
+ *
+ *   Sub-Sub/
+ *     Inbox/        tag review notes, the import queue, alerts, drafts
+ *     Literature/   one note per item
+ *     Syntheses/    notes on several items
+ *     Research/     literature reviews, comparisons, digests (.plans/ for plans and logs)
+ *     Zotero/       Zotero tags.md, Zotero agent.md, Literature alerts.md
+ *
+ * Before 0.9, the settings files were in Systems/ and the folder could be a whole
+ * vault. Those files are still found there until they are moved (subsub init).
+ */
+
+import { existsSync, mkdirSync, readdirSync, renameSync, rmdirSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+export const FOLDER_NAME = "Sub-Sub";
+export const SETTINGS_DIR = "Zotero";
+export const LEGACY_SETTINGS_DIR = "Systems";
+export const NOTE_DIRS = ["Inbox", "Literature", "Syntheses", "Research"];
+
+/** The files in Zotero/ that Sub-Sub and the Zotero server read. */
+export const SETTINGS_FILES = { tags: "Zotero tags.md", rules: "Zotero agent.md", alerts: "Literature alerts.md" } as const;
+type SettingsFile = keyof typeof SETTINGS_FILES;
+
+/** True when the folder is the root of an Obsidian vault. */
+export function isObsidianVault(dir: string): boolean {
+	return existsSync(join(dir, ".obsidian"));
+}
+
+/** The folder that a user's answer means: a vault root becomes <vault>/Sub-Sub. */
+export function subsubFolder(answer: string): string {
+	return isObsidianVault(answer) && basename(answer) !== FOLDER_NAME ? join(answer, FOLDER_NAME) : answer;
+}
+
+/** The path of a settings file: Zotero/<file>, or Systems/<file> while only the old one exists. */
+export function settingsFile(folder: string, which: SettingsFile): string {
+	const name = SETTINGS_FILES[which];
+	const current = join(folder, SETTINGS_DIR, name);
+	const legacy = join(folder, LEGACY_SETTINGS_DIR, name);
+	return !existsSync(current) && existsSync(legacy) ? legacy : current;
+}
+
+/** Every place a settings file may be, for the write gate. */
+export function settingsPaths(folder: string): string[] {
+	return Object.values(SETTINGS_FILES).flatMap((n) => [join(folder, SETTINGS_DIR, n), join(folder, LEGACY_SETTINGS_DIR, n)]);
+}
+
+export interface Move {
+	from: string;
+	to: string;
+}
+
+/** Inbox notes that Sub-Sub and the Zotero server write. */
+const SUBSUB_INBOX = /^(Zotero |Literature alerts|Copy request )/;
+
+/**
+ * What to move from the old layout (`from`: the old notes folder) to the new one
+ * (`to`: the Sub-Sub folder). Only files that Sub-Sub made, and never over an
+ * existing file:
+ * - the settings files, from Systems/ to Zotero/;
+ * - when the Sub-Sub folder is new (the old folder was a whole vault): Sub-Sub's
+ *   notes in Inbox/. Literature/, Syntheses/ and Research/ of a vault may hold the
+ *   user's own notes, so they stay; the user moves them.
+ */
+export function planMoves(from: string, to: string): Move[] {
+	const moves: Move[] = [];
+	const add = (src: string, dest: string) => {
+		if (existsSync(src) && !existsSync(dest) && !moves.some((m) => m.to === dest)) moves.push({ from: src, to: dest });
+	};
+	for (const name of Object.values(SETTINGS_FILES)) {
+		add(join(from, LEGACY_SETTINGS_DIR, name), join(to, SETTINGS_DIR, name));
+		if (from !== to) add(join(from, SETTINGS_DIR, name), join(to, SETTINGS_DIR, name));
+	}
+	if (from !== to) {
+		const inbox = join(from, "Inbox");
+		if (existsSync(inbox)) {
+			for (const f of readdirSync(inbox).sort()) {
+				if (SUBSUB_INBOX.test(f) && statSync(join(inbox, f)).isFile()) add(join(inbox, f), join(to, "Inbox", f));
+			}
+		}
+	}
+	return moves;
+}
+
+/** Folders of the old layout that may hold Sub-Sub's notes but are left for the user. */
+export function leftBehind(from: string, to: string): string[] {
+	if (from === to) return [];
+	return ["Literature", "Syntheses", "Research"].map((d) => join(from, d)).filter((d) => existsSync(d) && readdirSync(d).length > 0);
+}
+
+/** Do the moves. An old Systems/ folder that is now empty is removed. */
+export function applyMoves(moves: Move[]): void {
+	for (const m of moves) {
+		mkdirSync(dirname(m.to), { recursive: true });
+		renameSync(m.from, m.to);
+	}
+	for (const dir of new Set(moves.map((m) => dirname(m.from)))) {
+		if (basename(dir) === LEGACY_SETTINGS_DIR && existsSync(dir) && readdirSync(dir).length === 0) rmdirSync(dir);
+	}
+}

package/src/paths.ts

@@ -10,6 +10,7 @@ import { existsSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { settingsPaths } from "./layout.ts";
 
 export function normalizeToolPath(raw: string, cwd: string): string {
 	let p = String(raw ?? "").trim();
@@ -80,11 +81,7 @@ export function buildPolicy(opts: { vault?: string; cwd: string; serverDir: stri
 			join(v, ".claude"),
 			join(v, ".opencode"),
 			join(v, ".obsidian"),
-			join(v, "Systems", "Zotero agent.md"),
-			join(v, "Systems", "Zotero tags.md"),
-			join(v, "Systems", "Zotero librarian.md"),
-			join(v, "Systems", "Zotero researcher.md"),
-			join(v, "Systems", "Literature alerts.md"),
+			...settingsPaths(v),
 		);
 	}
 	return { allowed, protectedPaths };

package/src/prompt.ts

@@ -1,7 +1,7 @@
 /**
  * The Sub-Sub part of the system prompt: role text for the current mode, the
- * profile rules, the shared Zotero rules from the notes folder, the vault
- * conventions when pi runs inside the notes folder, and the language rule.
+ * profile rules, the shared Zotero rules from the Sub-Sub folder, the vault
+ * conventions when pi runs inside the Sub-Sub folder, and the language rule.
  *
  * Role and profile texts use placeholders: {{user}} / {{User}} (the user's name,
  * or "the user"), {{about}} (one line about the user) and {{batch}}.
@@ -63,7 +63,7 @@ export function systemAddition(mode: Mode, cfg: SubsubConfig, cwd: string): stri
 	const shared = readIf(cfg.sharedRules);
 	if (shared) {
 		parts.push(
-			"# Shared Zotero rules (from the notes folder)",
+			"# Shared Zotero rules (from the Sub-Sub folder)",
 			shared,
 			`Sub-Sub note: in Sub-Sub you do not need a separate dry run before a change. Call the write tool with dry_run=false; Sub-Sub shows ${user} the server's preview and applies it only on approval. This replaces the dry-run steps above.`,
 		);

package/src/web.ts

@@ -604,10 +604,10 @@ export async function startWeb(opts: WebOptions, env: NodeJS.ProcessEnv = proces
 					const body = await readJson(req);
 					const target = resolve(cwd, expand(String(body.path ?? "")));
 					const vault = cfg.vault;
-					// Judge the real file, so a link inside the notes folder cannot open a document outside it.
+					// Judge the real file, so a link inside the Sub-Sub folder cannot open a document outside it.
 					const real = realish(target);
 					const inside = within(real, realish(cwd)) || Boolean(vault && within(real, realish(vault)));
-					if (!inside || !existsSync(target)) return send(res, 404, { error: "not found in the notes folder" });
+					if (!inside || !existsSync(target)) return send(res, 404, { error: "not found in the Sub-Sub folder" });
 					// Documents only: a file that the model wrote must never be run.
 					if (!OPENABLE.has(extname(target).toLowerCase())) return send(res, 403, { error: "Sub-Sub opens only notes and documents (.md, .txt, .pdf, .bib, .csv, .qmd)." });
 					if (vault && within(target, vault) && existsSync(join(vault, ".obsidian"))) openExternal(`obsidian://open?path=${encodeURIComponent(target)}`);