@tiagojct/subsub 0.7.0 → 0.9.0

package/README.md

@@ -19,7 +19,7 @@ A Zotero librarian and research assistant that runs on your computer, in your br
 * **Full Journal & Reversible Edits**: Every library modification is recorded with a unique journal ID and can be reverted anytime using `/undo`.
 * **Two Dedicated Roles**:
   * 📚 **The Librarian**: Cleans tags, imports references (DOI, PMID, ISBN), deduplicates, fixes metadata, retrieves open-access PDFs, creates collections, and checks retractions. *Runs completely offline with no web search access.*
-  * 🔬 **The Researcher**: Reads items, searches PubMed and OpenAlex, finds gaps, checks citations in manuscripts, and writes structured Markdown notes in your notes vault (e.g. Obsidian). *Cannot modify library records.*
+  * 🔬 **The Researcher**: Reads items, searches PubMed and OpenAlex, finds gaps, checks citations in manuscripts, and writes structured Markdown notes in your Sub-Sub folder (it can sit inside an Obsidian vault). *Cannot modify library records.*
 * **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.
 
@@ -77,7 +77,7 @@ Automated installers handle Node.js, uv, and desktop shortcuts:
    ```sh
    subsub init
    ```
-   Answer the interactive prompts (press <kbd>Enter</kbd> to accept defaults). This creates your notes folder (`Inbox/` and `Systems/`), sets up starter tag vocabularies, and writes note templates (`Systems/Zotero agent.md`).
+   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
@@ -176,7 +176,7 @@ subsub review apply 13-31
 | `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 Markdown notes folder / Obsidian vault | `$ZOTERO_VAULT` |
+| `vault` | string | Path to your Sub-Sub folder | `$ZOTERO_VAULT` |
 | `models` | object | Model overrides per mode (e.g. `{"librarian": "opencode-go/glm-5.3-flash"}`) | Current model |
 | `defaultMode`| string | Default launch mode (`"researcher"` or `"librarian"`) | `"researcher"` |
 | `serverDir` | string | Local development path for `zotero-local-mcp` | PyPI package |
@@ -186,7 +186,7 @@ subsub review apply 13-31
 | `addons` | array | Optional servers; `["starbuck"]` adds reference checks | `[]` |
 | `starbuckDir` | string | Local Starbuck folder (used when it has a `pyproject.toml`) | `~/Projects/starbuck` |
 
-Server-level configurations (notes folder path, tag vocabulary path, Unpaywall email) reside in `~/.config/zotero-local-mcp/env`.
+Server-level configurations (Sub-Sub folder, tag list, alerts file, Unpaywall email) reside in `~/.config/zotero-local-mcp/env`.
 
 ### Papers that are not open access
 
@@ -203,7 +203,7 @@ Sub-Sub finds open-access copies (Unpaywall, Europe PMC). For other papers, use
 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`.
 
-The researcher 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 notes 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.
+The researcher 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.
 
 ---
 

package/THIRD_PARTY_NOTICES

@@ -53,3 +53,101 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+
+web/fonts/ and the website use IBM Plex Sans, IBM Plex Serif and IBM Plex Mono,
+https://github.com/IBM/plex. Their licence:
+
+Copyright © 2017 IBM Corp. with Reserved Font Name "Plex"
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/config.js

@@ -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"
  * }
@@ -21,6 +21,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.js";
 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.0";
@@ -116,11 +117,13 @@ export function loadConfig(env = process.env) {
             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/dist/doctor.js

@@ -11,6 +11,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { findUv, loadConfig, SERVER_VERSION, serverCommand, STARBUCK_SOURCE, starbuckCommand, starbuckEnabled, } from "./config.js";
+import { isObsidianVault, LEGACY_SETTINGS_DIR, SETTINGS_FILES, settingsFile } from "./layout.js";
 import { profileSpec } from "./profiles.js";
 export const defaultRunner = (command, args, env) => {
     const r = spawnSync(command, args, { env, encoding: "utf8", timeout: 120_000 });
@@ -95,9 +96,7 @@ export function runChecks(cfg, env, deps = {}) {
                     : 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" }
         : { name: "Contact email", ok: true, warn: true, detail: "not set: open-access PDFs cannot be found", fix: "Type subsub init and give an email address." });
@@ -150,3 +149,18 @@ export async function doctorMain(env = process.env) {
     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) {
+    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"].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/dist/init.js

@@ -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";
 import { homedir } from "node:os";
@@ -22,6 +28,7 @@ import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { configPath, 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 { PROFILE_SPECS } from "./profiles.js";
 const TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates");
 export const STARTER_TAGS = {
@@ -73,41 +80,89 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
     const envFile = current.envFile ?? expand(initEnv.ZOTERO_MCP_ENV ?? join(home, ".config", "zotero-local-mcp", "env"), home);
     const envValues = existsSync(envFile) ? parseEnvFile(envFile) : {};
     const created = [];
-    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, text) => {
+        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";
-    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)", 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");
+    const profile = await io.choose("Profile", PROFILES.map((p) => ({ value: p, label: `${PROFILE_SPECS[p].label}: ${PROFILE_SPECS[p].summary}` })), isProfile(profileDefault) ? profileDefault : "scholar");
+    // The tag list: a custom path in the server settings stays; otherwise Zotero/Zotero tags.md (moved, kept or new).
+    const vocabTarget = join(notes, SETTINGS_DIR, SETTINGS_FILES.tags);
+    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 {
-        tags = await io.choose("Starter tag list (edit it later in the notes folder)", Object.entries(STARTER_TAGS).map(([value, label]) => ({ value, label })), flags.tags ?? (fmup ? "health-sciences" : "any-field"));
+        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", 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();
-    const starbuck = await io.choose("Reference checks (Starbuck): check that cited works exist, match their citation and were not retracted", [
+    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", [
         { 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");
     const modelDefault = existing.models ? "keep" : hasProvider(agentDir, "opencode") ? "opencode-go" : "later";
     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);
@@ -118,14 +173,18 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         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 = {
         profile,
         userName: userName || undefined,
@@ -148,6 +207,10 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
     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."
         : "Zotero: not reachable. Start Zotero 10, then in Zotero open Settings > Advanced and turn on \"Allow other applications on this computer to communicate with Zotero\".");
@@ -156,7 +219,7 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
     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) {
     const out = {};
@@ -211,7 +274,9 @@ function terminalIO() {
 }
 export async function initMain(args, env = process.env) {
     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/dist/layout.js

@@ -0,0 +1,91 @@
+/**
+ * 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" };
+/** True when the folder is the root of an Obsidian vault. */
+export function isObsidianVault(dir) {
+    return existsSync(join(dir, ".obsidian"));
+}
+/** The folder that a user's answer means: a vault root becomes <vault>/Sub-Sub. */
+export function subsubFolder(answer) {
+    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, which) {
+    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) {
+    return Object.values(SETTINGS_FILES).flatMap((n) => [join(folder, SETTINGS_DIR, n), join(folder, LEGACY_SETTINGS_DIR, n)]);
+}
+/** 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, to) {
+    const moves = [];
+    const add = (src, dest) => {
+        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, to) {
+    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) {
+    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/dist/paths.js

@@ -9,6 +9,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.js";
 export function normalizeToolPath(raw, cwd) {
     let p = String(raw ?? "").trim();
     if (p.startsWith("@"))
@@ -72,7 +73,7 @@ export function buildPolicy(opts) {
     ];
     if (opts.vault) {
         const v = realish(opts.vault);
-        protectedPaths.push(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"));
+        protectedPaths.push(join(v, ".claude"), join(v, ".opencode"), join(v, ".obsidian"), ...settingsPaths(v));
     }
     return { allowed, protectedPaths };
 }

package/dist/prompt.js

@@ -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}}.
@@ -56,7 +56,7 @@ export function systemAddition(mode, cfg, cwd) {
     const parts = [`# Sub-Sub: ${mode} mode`, roleText(mode, cfg)];
     const shared = readIf(cfg.sharedRules);
     if (shared) {
-        parts.push("# Shared Zotero rules (from the notes 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.`);
+        parts.push("# 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.`);
     }
     if (inside(cwd, cfg.vault)) {
         for (const f of cfg.vaultContext) {

package/dist/web.js

@@ -591,11 +591,11 @@ export async function startWeb(opts, env = process.env, log = () => { }) {
                     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" });
+                        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)." });