Zotero Watch Folder — what to try, what should happen

Chapter 1Setting it up for the first time

These are the six starting states a new user can land in. Match yours to the closest story and walk through what should happen.

1.1 · fresh start

My folder is empty and my Zotero library is empty

I just installed the plugin. I want to set things up so it's ready when I start downloading papers.

I want toOpen settings, point the plugin at a folder I'll be dropping PDFs into, pick a mode, turn it on.

What should happenA wizard offers: pick the local folder → pick a mode → pick where PDFs live (storage strategy) → confirm. There is no "pick a collection" step — the plugin mirrors your whole Zotero library. A PDF dropped at the watch-folder root lands as an Unfiled item; one dropped into a subfolder lands in the matching top-level collection. Nested subfolders produce nested collections. Zotero's Bin, Duplicates, and other special views are never mirrored. Defaults work for most people. After "Enable", the plugin is running. Nothing visible happens yet because there's nothing to sync.

If it looks offNo wizard appears → check that setupCompleted isn't already true from a previous attempt. Open prefs and re-run setup via "Re-run setup wizard…".

Covers: S.1, S.4, SETUP.1, P1.1, P1.2, P1.10

1.2 · disk-side already organized

My folder has PDFs in it, but my Zotero library is empty

I've been saving papers into ~/Papers for years. I want Zotero to catch up with what I already have.

I want toPoint the plugin at my existing folder, let it import everything I already have, and preserve the way I've organized subfolders.

What should happenWithin a few scan cycles, every PDF in the folder appears in Zotero. Files at the root of the watch folder land as Unfiled items; subfolders become matching collections (Papers/Methods/AI/ → Methods › AI). Metadata gets fetched for each file. Failures get a _needs-review tag.

If it looks offSome files imported, some didn't → check fileTypes matches your extensions (default is pdf only). Big folders take longer because metadata retrieval is throttled — give it a few minutes.

Covers: ADD.1, ADD.2, ADD.3, E.4, P1.3, P1.4, P1.5, P1.8

1.3 · zotero-side already organized

My Zotero library has items, but my folder is empty

I've been using Zotero for ages. I want a folder on my computer that reflects my library so I can browse my papers as normal files.

I want toPick Mode 2 or Mode 3, point the plugin at an empty folder, and have my library "materialized" out to disk on first run.

What should happenA first-run baseline runs. Each item with an attached file gets its file copied out of Zotero's storage to the equivalent path on disk. Subcollections become subfolders. Items without files (metadata-only entries) are skipped silently.

In Mode 1Mode 1 is import-only and won't write anything to disk. Switch to Mode 2 or Mode 3 if you want your library mirrored locally.

If it looks offNothing copies out → confirm the mode is mode2 or mode3, and that baselineCompletedForRoot is empty (clear it to force a re-run). Collections appear as subfolders; items in no collection land in the root folder as Unfiled. Disk space concern: consider importMode = linked for new items instead of copying.

Covers: BASE.1 (B.6 mkdir), BASE.2 (B.2 copy)

1.4 · both sides mostly agree

Both sides have stuff, and they mostly match

Some of these PDFs are already in Zotero (with attached files), but some are loose on disk. Don't make duplicates of anything.

I want toThe plugin to recognize what's the same and what's new, and only act on the differences.

What should happenFor each file on disk, the plugin computes a SHA-256 hash. Matches against an existing Zotero attachment? Link to it — don't duplicate, don't move. Match a hash that's stamped in a Zotero item's Extra field but no live attachment? Treat as a re-link to that item. No match? Import as new.

If it looks offDuplicates appeared → confirm duplicateCheck and duplicateMatchHash are both on (defaults). If you see a duplicate that's clearly the same file, the hash stamp in the parent item's Extra field may be missing — let the plugin run for a scan cycle, it back-stamps existing items.

Covers: BASE.3 (B.7 hash reconcile), DUP.1

1.5 · both sides disagree

Both sides have stuff, and the structure doesn't match at all

My folder layout is one thing; my Zotero collections are another. Don't force them to match.

I want toThe plugin to reconcile sanely without trashing anything or force-rewriting either side's structure.

What should happenFiles only on disk get imported into the Zotero collection matching their subfolder path. Items only in Zotero get their files copied out (Mode 2/3). Files that match by hash on both sides are linked in place — the plugin won't force-move a file to its "canonical" path just to make the structures align.

If it looks offFeels overwhelming → clear baselineCompletedForRoot and re-run setup. The plugin mirrors the whole library, so there is no single "sync root collection" to scope down to — but you can use Smart Rules or Mode 1 (import-only) to limit what it acts on while you orient yourself.

Covers: ADOPT.1, BASE.3

1.6 · linked attachments already

I'd already set up Zotero with "link to file" pointing into this folder

My Zotero items already link to PDFs in ~/Papers. The plugin shouldn't re-import them as duplicates.

I want toMy existing linked-file setup to keep working, and the plugin to recognize those files as already-known.

What should happenThe hash-based dedup catches matches against the linked-file items. No duplicates created. The plugin tracks them at their existing on-disk paths.

If it looks offDuplicates appeared → check the parent items' Extra field for watchfolder-hash:<sha256> stamps. If they're missing, the plugin's back-stamping pass should populate them on the next launch.

Covers: BASE.3, P1.9

Chapter 2Using it day to day

The everyday motions. Most of these "just work" — but it's useful to know what just works, so you can spot if something's off.

2.1 · the main use case

I just downloaded a paper to my watch folder

I clicked download in my browser, the PDF landed in my watch folder. Now I want to see it in Zotero, with the title and authors filled in.

I want toOpen Zotero a few seconds later and see the new paper, recognized and named.

What should happenWithin ~5 seconds the file shows up as an item — in the matching collection if dropped into a subfolder, or as Unfiled if dropped at the watch-folder root. Title, authors, year, DOI get populated. The file is renamed via the template (default: {firstCreator} - {year} - {title}.pdf) — both on disk and on the attachment.

If it looks offItem appeared but metadata is missing → look for a _needs-review tag; Zotero's recognizer didn't find a match. You can run "Retrieve Metadata for PDF" manually. Filename didn't get rewritten → check autoRename is on and the template variables resolved (some fields like {DOI} are empty for non-DOI papers).

Covers: S.2, P1.3, P1.4, P1.5

2.2 · drop in bulk

I dropped twenty papers at once

I just downloaded a batch from a results page. I want them all imported, but I don't want Zotero hammering the metadata API for all twenty at the same time.

I want toAll twenty to end up in Zotero with metadata, on a polite schedule.

What should happenAll twenty files import within a couple of scan cycles. Metadata retrieval is throttled to maxConcurrentMetadata at a time (default 2). Big batches may take a few minutes total, but nothing is lost.

If it looks offSome files appeared as imports but not all → wait one more scan cycle, very large files sit through a "stability" check before they're considered done copying.

Covers: E.4

2.3 · accidental re-save

I accidentally re-saved a paper I already have

I downloaded the same paper from a different page. I don't want a duplicate Zotero item — but I also don't want my file deleted off disk.

I want toQuietly skip the import. Leave my existing Zotero item alone.

What should happenThe plugin computes the new file's SHA-256, matches it against the existing tracking record (or the hash stamp in Zotero's Extra field), and skips the import. Both copies of the file may coexist on disk under different names; only one is the "canonical" one in Zotero's view.

If it looks offDuplicate did appear → check duplicateCheck = true and duplicateAction = skip (the default). If your existing item is missing the hash stamp, the live tracking store catches it instead.

Covers: S.3, DUP.1

2.4 · organize by subfolder

I want to organize PDFs into subfolders on disk

I create Methods/ in my watch folder and drag some PDFs into it. I want a matching Zotero subcollection.

I want toSubfolders to drive Zotero's collection tree.

What should happenThe moment I create a subfolder (or move files into one), a matching collection appears in Zotero. Top-level subfolders become top-level collections; nested subfolders produce nested collections. Items get filed in the matching collection. Empty subfolders create empty collections.

If it looks offCollection isn't appearing → confirm the subfolder is under the watch root (not its parent or sibling). Special folders (like .zotero-watch-trash/ and imported/) are reserved and skipped.

Covers: ADD.2, ADD.3

2.5 · organize by collection

I want to organize by creating a collection in Zotero

I create Research › Methodology in Zotero and drag some items into it.

I want toA matching folder to appear on disk, and the files of items I move into the collection to follow.

What should happenIn Mode 2 or Mode 3, the subfolder appears on disk almost immediately. Items moved into the collection have their files moved to the matching subfolder on the next scan.

In Mode 1Mode 1 is one-way (disk → Zotero). Collection changes in Zotero don't propagate to disk in Mode 1.

Covers: BASE.1, MEM.1

2.6 · rename in Zotero

I want to rename a subcollection in Zotero

I rename Methods to Methodology in Zotero. The disk folder should follow.

I want toBoth sides to keep agreeing without me doing anything else.

What should happenIn Mode 2 or Mode 3, the disk folder gets renamed atomically. The tracked paths inside (FileRecords) get rewritten to match.

Covers: REN.1

2.7 · rename on disk

I want to rename a subfolder on disk

I rename Methods to Methodology in my file manager.

I want toThe matching Zotero collection to rename.

What should happenOn the next scan, the Zotero collection gets renamed (same key, new name). All tracked files inside follow. Works in all three modes.

Covers: RENAME.1

2.8 · move between collections

I want to move an item between Zotero collections

A paper I categorized as "Methods" should really be in "Theory". I drag it across in Zotero.

I want toIts file to follow on disk.

What should happenIn Mode 2 or Mode 3, the file moves on disk to the new collection's subfolder. The old location is empty afterward. Items that live in multiple collections at once keep one "canonical" location (usually the first one) and that's where the file lives.

If it looks offFile didn't move → confirm you're running Mode 2 or 3. The whole library is in scope; no separate "sync root" scoping applies.

Covers: MEM.1

2.9 · weird filenames

The file I'm importing has special characters or a very long name

The download was "Doe & Smith (2024) — § étude.pdf", with spaces, ampersands, and Unicode.

I want toIt to import cleanly without confusing the filesystem.

What should happenImports work fine. Special characters are preserved on the tracking side. If autoRename is on, the rename template sanitizes anything the OS can't handle and caps the length at maxFilenameLength (default 150).

Covers: E.1, E.2

2.10 · late attachment

I attached a PDF to an existing Zotero item by hand

I had a citation in Zotero without a file; I just attached the PDF via "Add Attachment".

I want toThe file to appear on disk like everything else in the watch folder.

What should happenIn Mode 2 or Mode 3, the plugin copies the file out to the appropriate subfolder (matching the parent item's collection). A FileRecord is created.

Covers: LATE.1

2.11 · smart rules

I want incoming papers to be auto-tagged or routed

I want any paper with "transformer" in the title tagged nlp automatically.

I want toSet up rules once and have them apply to every new import.

What should happenOpen prefs → Smart Rules section → enable → paste JSON (or click "Insert example") → Save. New imports get matching rules applied. Bad JSON shows a parse error inline.

Covers: SR.1

Chapter 3When something looks off

The "uh-oh, did something break?" scenarios. Most have clean recovery paths — the plugin is designed to refuse destructive operations rather than silently do them.

3.1 · disk-side delete

I deleted a PDF from my watch folder by accident

I cleaned up my downloads folder a bit too aggressively and lost a paper I had in Zotero.

I want toGet it back without losing my metadata.

What should happen (Mode 3)The file gets moved to .zotero-watch-trash/ under the watch root before propagating. The Zotero attachment gets moved to Zotero's Bin. To restore: un-trash the attachment in Zotero (file moves back), or copy the file out of plugin trash yourself (the plugin recognizes it by hash and re-links).

In Mode 1 or 2Nothing dramatic. The tracking record flips to "missing." Zotero leaves the item alone. To restore, just put the file back.

Covers: DEL.1, RST.1, RST.3, LD.1, S.6, P1.12

3.2 · zotero-side trash

I accidentally trashed a paper in Zotero

I right-clicked → Move to Trash without thinking.

I want toGet it back, including the file on disk.

What should happen (Mode 3, default settings)A dialog asks: Plugin trash (recoverable, default) / OS trash / Permanent / Keep on disk. "Keep" leaves the file alone. "Plugin trash" moves it to .zotero-watch-trash/ — restore by un-trashing the attachment in Zotero later.

In Mode 1 or 2File stays on disk untouched. Item goes to the Bin. Restore the item in Zotero; the file is unaffected.

Covers: S.5, ZA.1, P1.11

3.3 · duplicate copies

I had two copies of the same paper, and I deleted one

I'd duplicated a paper into two folders by accident. I deleted the second copy. I don't want my "main" copy to disappear too.

I want toOnly the file I actually deleted to go away. Leave the main copy alone, and leave the Zotero item alone.

What should happenThe plugin recognizes the deleted file as a "shadow" (same content hash as the canonical record). It drops the shadow from tracking, leaves the canonical file on disk, leaves the Zotero attachment alone.

Covers: DEL.2

3.4 · folder delete

I deleted a whole subfolder by mistake

I dragged Methods/ to the trash without realizing what was in it.

I want toGet the whole folder back.

What should happen (Mode 3)The folder and all its files are moved into .zotero-watch-trash/<folder>/. Tracking for that collection (and child files) is dropped. Zotero attachments are NOT trashed — they just lose their membership in the deleted collection. To restore: prefs pane → "Trashed folders" row → "Restore folders…" → pick the one you want. The dir moves back, the Zotero collection is re-created, FileRecords are re-attached.

In Mode 2Mode 2 is warn-only on folder delete. Nothing actually gets moved; the collection tracking flips to "suppressed" and shows up in the prefs pane for you to act on.

Covers: FDEL.1, FRST.1

3.5 · bulk safety

I just deleted a lot of files (or folders) at once

I cleared out an old folder, or a cloud-sync glitch removed twenty files — or several top-level folders disappeared at once. I do NOT want my Zotero library shredded as a side effect.

I want toA safety stop. Make me confirm before something this big happens.

What should happenIf a single operation would affect more than 10 files or more than 20% of your tracked items, a confirmation dialog appears. Cancel → tracking flips to "missing" but nothing destructive happens. Proceed → normal propagation runs. If the confirm dialog can't render (no UI thread available), the plugin refuses rather than silently executing. Additionally: if many top-level folders vanish simultaneously (the signature of a cloud-sync glitch under whole-library scope), the plugin pauses deletion entirely rather than trashing all those collections — you'll see a warning in the prefs "Sync warnings" panel and can resume or investigate. And the very first time a two-way delete would fire under whole-library scope, you get a one-time confirmation explaining the scope and asking you to opt in.

Covers: DEL.3, FDEL.2

3.6 · content drift

I annotated a PDF — will the sync clobber my annotations?

I opened a paper in my PDF reader and added notes. Now the file's hash on disk is different from what Zotero thinks it should be.

I want toBe warned. Don't silently overwrite my edits.

What should happenAny sync operation that would move or overwrite the file refuses. The FileRecord state flips to "conflict-blocked" and shows up in the prefs pane under conflicts. You resolve via the prefs UI: re-stamp the new content as the baseline / discard the local changes / pause sync for this file.

Covers: CONF.1

3.7 · last-collection-removed

I removed an item from all of its collections

I cleaned up the categorization in Zotero and now an item isn't in any collection — it's essentially Unfiled. What happened to its file on disk?

I want toMy file to stay on disk. Don't delete things just because I reorganized.

What should happenThe file stays on disk. The FileRecord flips to "out-of-scope-suppressed." A "Suppressed items" row appears in prefs. From there I can: re-instate (put back), keep local (stop syncing but keep the file), trash, or move outside the watch root.

Covers: SUPP.1

3.8 · drive unplugged

My watch folder is on a drive that's not connected

My watch folder lives on an external SSD that I've unplugged. I don't want the plugin to think every file got deleted.

I want toThe plugin to wait quietly until the drive is back.

What should happenThe plugin notices the watch root itself is unreachable and pauses globally. Every tracking record flips to "paused" — no destructive operations run. When the drive comes back, the next scan resumes normally.

Covers: FM.1

3.9 · parent-trash restore

I trashed a parent item that had multiple attachments — can I bring them all back?

I trashed an item that had a PDF plus a supplementary file. Both files are now in plugin trash. I want everything back.

I want toA single un-trash on the parent to restore everything.

What should happen (Mode 3)Un-trash the parent in Zotero. Every child attachment is un-trashed too. Every file is moved out of plugin trash back to its original path.

Covers: RST.2, RST.4

3.10 · re-attach

I permanently erased an attachment, but the citation is still in Zotero

I emptied the Bin and the attachment is gone for good. But the bibliographic item it was attached to is still in my library. Now I want the file back.

I want toDrop the file back and have it re-attach to the existing parent — not create a new standalone item.

What should happenThe plugin matches the file's hash against a tombstone record, sees the parent item still exists, and attaches the file as a new child of that parent (via Zotero's importFromFile({parentItemID})). No duplicate standalone item is created.

Covers: RST.5

3.11 · restore collision

I'm restoring a file but a different file is at that path now

Between trashing the file and restoring it, a different file with the same name landed at the canonical path.

I want toNot lose either file. Don't overwrite.

What should happenThe restore lands at <name>.restored.<timestamp>.<ext>. The existing file is unchanged. Both are now tracked.

Covers: RST.6

3.12 · status check

I want to see what the plugin tried and what it refused

Something feels off. I want a list of recent warnings.

I want toOpen prefs and see at a glance how much weirdness is queued up.

What should happenA "Sync warnings" row in prefs shows the count + a per-category breakdown (conflict, missing file, I/O error, suppressed, unknown target). Click "View" for the recent 100 entries. Click "Clear" to reset (listeners survive Clear, so the prefs pane keeps tracking).

Covers: WARN.1

3.13 · check and repair

Things look out of sync and I'm not sure what drifted

I open Settings, find the "Check & repair" tool, and ask it to scan. A list of issues comes back — some files whose canonical copy moved, a folder that stopped syncing, a stale entry blocking a rename. I want to fix what I choose and leave the rest alone.

I want toOpen Settings, run the Check & Repair scan, review each suggested fix with its plain-English explanation, apply only the ones I want.

What should happenThe tool scans tracking state, the watch folder on disk, and Zotero, then lists every inconsistency it finds. Items with annotations or notes are shown first and are never deleted. Suggested fixes are additive (tracking corrections, collection membership additions) — no file deletions, no bypassing of Zotero. Each fix re-validates at apply time; if conditions changed since the scan, the fix is skipped with a note. Applying a subset works: uncheck what you want to skip.

If it looks offAn issue you expected isn't listed → it may already be covered by an existing warning in the Sync warnings panel. Issues that require a manual decision (e.g. a conflict-blocked file) appear in the Sync warnings panel instead, with their own resolution UI.

Covers: I.29

Chapter 4Changing how I use it

Settings I might change after the plugin has been running for a while.

4.1 · switch modes

I want to try a different sync mode

I started in Mode 1 (safe) and now I want to try Mode 3 (full mirror, recoverable trash).

I want toSwitch modes without restarting Zotero.

What should happenChange mode in prefs. The plugin's mode-pref observer reacts in-process: starts the sync coordinator if moving to Mode 2/3, stops it if moving back to Mode 1. A baseline pass runs on first activation of Mode 2/3 to reconcile state.

Covers: SETUP.M2.1, SETUP.M3.1

4.2 · disable temporarily

I want to disable the plugin temporarily

I'm doing something tricky in Zotero or on disk and I want the watcher paused while I work.

I want toPause without uninstalling, and pick up cleanly when I re-enable.

What should happenUncheck "Enable Watch Folder" in prefs. The scanner stops, the coordinator stops. Files added during the disabled period are picked up the next time I re-enable (no need to restart Zotero).

Covers: S.7, E.5

4.3 · move the folder

I want to point the plugin at a different watch folder

I'm moving from ~/Papers to ~/Documents/Library.

I want toRetarget without losing my Zotero side, and without re-importing what's already linked.

What should happenChange sourcePath in prefs. To get a clean baseline against the new location, also clear baselineCompletedForRoot. On next start, the plugin re-runs the baseline pass — existing Zotero items are matched against files in the new location by hash, so no duplicates.

If it looks offThe plugin keeps complaining about missing files → make sure you actually moved the files too, not just retargeted the pref. Or accept it and use the suppression resolver to clean up.

4.4 · upgrade + whole-library scope

I upgraded from an older version — do I still have my single-collection setup?

I was running v2.6 with a single sync-root collection. I upgraded to v2.7. Did anything change?

I want toKeep working exactly as before, unless I choose to switch to the new whole-library mode.

What should happenNothing changes automatically. Upgrading pins you to your existing single-collection behavior via a migration flag. The new whole-library scope (which maps your entire Zotero library to the watch folder, with top-level folders = top-level collections and root-level files = Unfiled items) is opt-in — re-run setup via "Re-run setup wizard…" in prefs and choose the whole-library option when prompted. Only then does the scope switch.

If it looks offIf you re-ran setup and want to go back to single-collection behavior, use "Re-run setup wizard…" again and pick the collection-scoped option. Clear baselineCompletedForRoot so the baseline re-runs against the new scope.

4.5 · smart-rule edits

I want to edit my smart rules

I want toOpen the rule editor in prefs, edit JSON, save, and have it take effect.

What should happenSmart Rules section in prefs: textarea + Save + Insert example + Reload. Save validates per-rule shape (e.g. that the action is one of the supported types). Bad rules show an inline error and the rest don't save.

Covers: SR.1

4.6 · zotero restart

I just restarted Zotero

I want toThe plugin to pick up where it left off without me doing anything.

What should happenOn Zotero relaunch, the plugin auto-starts. Tracking is restored from zotero-watch-folder-tracking-v2.json. New files dropped during the restart are picked up on the first scan.

Covers: E.6

4.7 · deletion policy

I want a different default for what happens when I trash in Zotero

I don't want to be asked every time. I want trashes to always go to plugin trash (recoverable).

I want toPre-set the action so the dialog doesn't show.

What should happenChange diskDeleteOnTrash to one of: plugin_trash (recoverable), os_trash, permanent, never, or ask (the default, shows the dialog).

Covers: P1.11

4.8 · file types

I want to import EPUBs too, not just PDFs

I want toExtend the extension filter without changing anything else.

What should happenChange fileTypes from pdf to pdf,epub. New EPUBs drop straight in. Existing EPUBs in the watch folder are picked up on the next scan.

Covers: P1.8

4.9 · where PDFs live

I want to pick where my PDFs are stored — and free up Zotero storage

My Zotero storage is nearly full. I'd rather Zotero point to the PDFs in my watch folder than keep its own copies — but I don't want to lose my highlights.

I want toChoose a PDF storage strategy (separate from the sync mode), and convert my existing stored PDFs to linked ones to reclaim space.

What should happenThe prefs pane offers three strategies: Store in Zotero (default), Link from watch folder (saves Zotero storage — your folder-sync tool backs the files up), and Store + mirror (both). Picking "Link" changes how new imports are stored. To convert existing ones, "Reclaim Zotero Storage Space…" previews what it'll do, then converts only PDFs without highlights/notes — each copied out, hash-verified, relinked, with the old stored copy sent to Zotero's recoverable trash. Your metadata, notes, and annotations keep syncing regardless of where the file sits.

If it looks offA PDF you expected to convert stayed stored → it has highlights/notes, which are deliberately kept stored so they can't be orphaned. Linked PDFs not opening on your phone → linked files don't sync to Zotero mobile; that's expected for the "Link" strategy.

Covers: P1.9, I.21, I.22, I.23, E.24, E.25

4.10 · post-import behavior

I want my source PDFs deleted (or moved) after import

I want the watch folder to act like an inbox — files leave once they're processed.

I want toEither delete the source after a successful import, or move it into a "done" subtree.

What should happenpostImportAction = delete removes the source after import (tracking flags expectedOnDisk=false so the missing file doesn't trigger anything). postImportAction = move shuffles the file into a sibling imported/ subtree preserving the subdirectory path. leave (the default) keeps the source in place.

Covers: P1.6, P1.7

Chapter 5Second computer, cloud, or removable drive

Less-common but legitimate setups: multi-device, cloud-synced folders, and external drives that come and go.

5.1 · second computer

I installed Zotero on my desktop too, with Zotero Sync turned on

My laptop is already set up with the plugin. Now I'm setting up the desktop. My Zotero library is already pulled down via Zotero Sync, but the desktop's watch folder is empty.

I want toInstall the plugin on the desktop and have my library mirrored locally — without re-importing every item as a new one.

What should happenThis is effectively the "Zotero populated, folder empty" case from Chapter 1. Run setup on the desktop and point it at a local watch folder (empty is fine). The plugin mirrors the whole library: the baseline writes attachment files out into the matching folder structure. Hash stamps in items' Extra fields prevent any cross-device duplicates.

Covers: BASE.2, BASE.3 (cross-device variant)

5.2 · cloud folder

My watch folder is in Dropbox / iCloud / Syncthing

I keep my Papers folder in cloud sync so I can read on my tablet. I want the plugin to treat it like any other folder.

I want toIt to work without surprises.

What should happenIt works fine as long as files are materialized locally (not cloud placeholders). If your cloud client uses "online-only" placeholders that are zero bytes until accessed, the plugin will skip them (the file-stability check refuses to import a file that's still growing or empty). Once the file is fully downloaded, the next scan picks it up.

If it looks offConflicts after another machine edits the same file → the conflict gate catches it; resolve via the prefs pane's "Resolve…" buttons.

Covers: CONF.1, FM.1

5.3 · external drive

My watch folder is on a drive I sometimes unplug

My PDFs live on an external SSD. I plug it in when I'm at my desk, unplug it when I travel.

I want toThe plugin to not panic when the drive is gone.

What should happenWhen the drive isn't connected, the plugin notices the watch root is unreachable, flips every tracking record to "paused," and stops processing. When the drive comes back, the next scan resumes normally. No destructive operations run during the offline period.

Covers: FM.1

5.4 · long absence

I haven't used this in months. Did things drift?

I set this up a year ago and forgot about it. I want to come back, see what happened, and clean up anything weird.

I want toA quick overview of the plugin's recent activity and any unresolved state.

What should happenOpen prefs. Check the "Sync warnings" row count. Click View — recent warnings (capped at 100) show what was refused or skipped and why. Check the "Suppressed items" and "Trashed folders" rows — both list things you may want to act on. Resolution is per-item via the dialogs.

Covers: WARN.1, SUPP.1, FRST.1