Document v1 folder watch: per-path poll, restore, wait/skip.

Docker no longer auto-polls via folders.interval; call out wait_extensions,
skip_empty, and history restore so upgrades do not leave an empty queue.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: davidnewhall

docs/install/compose.md

@@ -54,6 +54,21 @@ And if you're trying to watch a folder, add this `environment:` variable with _y
       - UN_FOLDER_0_PATH=/downloads/autoxtract
 ```
 
+On Docker, filesystem events are often missing. Add a poll interval on that
+same key if nothing shows in the queue:
+
+```yaml
+      - UN_FOLDER_0_INTERVAL=1s
+```
+
+Incomplete downloads can wait on a suffix instead of polling:
+
+```yaml
+      - UN_FOLDER_0_WAIT_EXTENSION_0=.part
+```
+
+See [Folder Watcher](docker#folder-watcher).
+
 ## Data Mount
 
 <DataMount />

docs/install/configuration.md

@@ -108,6 +108,34 @@ In the config file use `[sonarr.uhd]`, `[folder.software]`, `[webhook.discord]`;
 (`name = "Starrs & Stripes"`). Existing `[[sonarr]]` / `[[folder]]` / `[[webhook]]` tables still load as keys
 `0`, `1`, …. Open that section in the web UI and click Save: Unpackerr rewrites the file to named tables automatically.
 
+### Watch folders
+
+- Changed in v1.0.0 (September 2026).
+
+Folder watch is not Starr. Each `[folder.<key>]` is a path Unpackerr extracts
+on its own. The generated tables below list every option.
+
+**Poll interval** is per folder (`interval`, env `UN_FOLDER_<key>_INTERVAL`).
+Default `0s` uses filesystem events. Set `1s` (or similar) on Docker and CIFS
+when new archives never show in the queue. Global `folders.interval` /
+`UN_FOLDERS_INTERVAL` is gone; leftover `[folders] interval` is ignored.
+Details: [Docker Folder Watcher](docker#folder-watcher).
+
+**After a restart**, recent folder history returns to the live queue the same
+way Starr items do: EXTRACTED still waiting on `delete_after`, EXTRACTFAILED
+retries, interrupted EXTRACTING, QUEUED, and WAITING after a retry. A path
+you removed from config is not restored. Windows matches watch paths without
+regard to drive-letter case.
+
+**Incomplete downloads:** `wait_extensions` keeps the item WAITING while a
+matching file exists in that item's top folder (`.part`, `.crdownload`, …).
+Nested paths are not scanned. The queue shows the blocking filename.
+Recheck is every 5s and does not enable the poller.
+Env: `UN_FOLDER_<key>_WAIT_EXTENSION_0=.part`.
+
+**Empty folders:** `skip_empty` (env `UN_FOLDER_<key>_SKIP_EMPTY`) drops
+archive-free folders after `start_delay` with no history row and no webhook.
+
 {/* The Global content is generated from here: https://github.com/Unpackerr/unpackerr/tree/main/init/config */}
 <Global />
 

docs/install/docker.md

@@ -106,16 +106,28 @@ docker run -e PUID=1000 -e PGID=100 -d -v /mnt/data:/data -v /mnt/config:/config
 
 ## Folder Watcher
 
-Watching folders in Docker will cause Unpackerr to constantly poll the
-watched-folder for changes at a default rate of `1s` (1 second).
+The Folder Watch feature uses `inotify` (a.k.a. `fsnotify`) to notice new
+archives. Each watch path has its own `interval`. The default is `0s`, which
+means filesystem events only — Unpackerr does **not** poll.
 
-The Folder Watch feature uses `inotify` (a.k.a. `fsnotify`) to identify changes to the
-watched folder. A folder-poller is automatically started when run in Docker because
-`inotify` is unreliable. Disable the folder poller (and rely on `inotify` only) by
-setting `folders.interval` (`UN_FOLDERS_INTERVAL`) to `1ms`.
+Docker bind mounts and CIFS often drop or delay those events, so items never
+appear in the queue. Turn polling on for that path:
 
-If Unpackerr has trouble determining when downloads are finished, set
-`start_delay` high enough to avoid beginning extracting files that are
-still being transferred.
+- Web UI: **Settings → Folders** → **Poll interval** (try `1s`).
+- Config: `interval = "1s"` under `[folder.downloads]`.
+- Env: `UN_FOLDER_downloads_INTERVAL=1s` (same key as the table).
+
+Leave `interval` at `0s` when native fsnotify works. Polling increases disk
+reads. A folder with a poll interval uses the poller only; other folders keep
+fsnotify.
+
+v0.x Docker installs auto-polled every 1s via global `folders.interval`
+(`UN_FOLDERS_INTERVAL`). That setting is gone. An old `[folders] interval`
+line in the file is ignored.
+
+If Unpackerr starts extracting files that are still downloading, raise
+`start_delay`, or set `wait_extensions` (for example `.part`, `.crdownload`)
+on that folder. Waiting items are rechecked every 5 seconds without turning
+the poller on. See [Watch folders](configuration#watch-folders).
 
 **Alternatively, run Unpackerr as a native service instead of in Docker.**

docs/install/upgrading.md

@@ -30,10 +30,18 @@ If you are on 0.16.x or earlier today, read this page before you pull `latest`.
   `system:metrics:read` (`Authorization: Bearer` or `X-Api-Key`).
 - Docker: mount `/config` if you want the UI to persist settings. Unpackerr
   writes `/config/unpackerr.conf` when that directory exists.
-
-The extractor, Starr polling, and folder watch behave as they did. This release
-is mostly about operating the app from a browser instead of a pile of `UN_*`
-variables.
+- Folder poll interval is per watch path (`interval` on `[folder.foo]`, env
+  `UN_FOLDER_foo_INTERVAL`). Default `0s` is fsnotify only. Docker no longer
+  auto-polls every second. Global `folders.interval` / `UN_FOLDERS_INTERVAL`
+  is ignored.
+- Watched-folder extracts resume from history after a restart. Incomplete
+  downloads can wait on `wait_extensions`; archive-free folders can be
+  skipped with `skip_empty`.
+
+The extractor and Starr polling work as they did. Folder watch picked up a
+few v1 changes (per-path poll, restore after restart, wait/skip). See
+[Watched folders](#watched-folders). This release is still mostly about
+operating the app from a browser instead of a pile of `UN_*` variables.
 
 ## Config file permissions
 
@@ -169,6 +177,45 @@ Environment variables: `UN_WHISPARR_*` becomes `UN_RADARR_whisparr_*`
 (for example `UN_RADARR_whisparr_URL`). Prefer putting this in the file and
 dropping the env vars.
 
+## Watched folders
+
+v0.x Docker set a global `folders.interval` (default 1s in the container).
+That knob is gone. Each watch path has its own `interval`, default **off**.
+
+If you watched folders in Docker and items stop appearing after upgrade:
+
+1. Open **Settings → Folders**.
+2. Set **Poll interval** to `1s` on each path that lives on a bind mount or
+   CIFS share.
+3. Save.
+
+Config equivalent:
+
+```toml
+[folder.downloads]
+  path = "/downloads/extract"
+  interval = "1s"
+```
+
+Env: `UN_FOLDER_downloads_INTERVAL=1s`. Native installs that already saw
+fsnotify events can leave the default.
+
+Other folder behavior that changed in v1:
+
+- **Restart:** folder queue rows restore from history (delete-after,
+  retries, interrupted extracts, waiting after retry). Starr WAITING is
+  still not restored; the next poll recreates it. Removing a watch path
+  drops those rows.
+- **`wait_extensions`:** stay WAITING while `.part` / `.crdownload` (or
+  whatever you list) exists in the item's top folder.
+- **`skip_empty`:** after `start_delay`, folders with no archives leave the
+  queue silently.
+- Named tables: `[folder.software]` / `UN_FOLDER_software_PATH`. Old
+  `[[folder]]` rows load as `0`, `1`, ….
+
+Details: [Watch folders](/docs/install/configuration#watch-folders) and
+[Docker Folder Watcher](/docs/install/docker#folder-watcher).
+
 ## After upgrade
 
 1. Confirm the UI loads and you can Save a harmless setting (or a Starr
@@ -177,6 +224,8 @@ dropping the env vars.
 3. If you scrape Prometheus, add an API key with `system:metrics:read`.
 4. Optional: open the Starr (or folder/hook) page and Save once so named
    tables replace leftover `[[sonarr]]` arrays.
+5. If you watch folders in Docker, set a poll interval on each path. See
+   [Watched folders](#watched-folders).
 
 Day-to-day use after that is on the [Web UI](/docs/install/web-ui) page
 (password reset, log lines, reverse proxy).

docs/install/web-ui.md

@@ -16,6 +16,9 @@ locked in the form until you remove that variable.
 ## What you get
 
 - **Dashboard** — live extract queue (retry / forget) and Starr poll counts.
+  Progress shows archive index, speed/ETA, and countdowns (start delay,
+  retry, folder cleanup). Folder WAITING rows show the blocking filename
+  when `wait_extensions` is set.
 - **History** — completed extracts, with delete and clear.
 - **Logs** — follow the app log in the browser (and download rotated files).
 - **Settings** — general, Starr, folders, webhooks, command hooks, web server.

docs/unpackerr/faq.md

@@ -65,3 +65,10 @@ If hard links don't work **at all** it could indicate another problem
 with your Starr app setup. See [TRaSH's Guides](https://trash-guides.info/Hardlinks/Hardlinks-and-Instant-Moves/)
 and the [Servarr Team's Docker Guide](https://wiki.servarr.com/docker-guide)
 for details on Docker path best-practices.
+
+## 6. Why don't watched folders show up in Docker?
+
+v1 watches with filesystem events by default. Docker (and CIFS) often hide
+those events, so the queue stays empty. Set that folder's poll `interval`
+to `1s` in the UI or `UN_FOLDER_<key>_INTERVAL=1s`. See
+[Folder Watcher](/docs/install/docker#folder-watcher).

docs/unpackerr/troubleshooting.md

@@ -35,6 +35,16 @@ If transfers are in an Error state they will not be extracted.
 **Permissions** tend to mess things up too, so make sure the user Unpackerr runs as can read
 and write to your download location.
 
+## Folder watch never queues anything
+
+On Docker bind mounts and CIFS, `inotify` often never fires. v1 does not
+poll unless you set a per-folder `interval` (try `1s`). The old global
+`UN_FOLDERS_INTERVAL` does nothing.
+
+If extracts start while a download is still writing, set `wait_extensions`
+(`.part`, `.crdownload`) or raise `start_delay`. See
+[Watch folders](/docs/install/configuration#watch-folders).
+
 ## Log files
 
 If you set `log_file`, that path is where Unpackerr writes. The Windows tray install