docs: clarify catalog and favorites rails

Author: queukat

AniLibertyStrmPlugin.Tests/BuildConfigurationTests.cs

@@ -134,8 +134,16 @@ public void PublicReadme_DocumentsOperationalCapabilities()
     {
         var root = FindRepoRoot();
         var readme = File.ReadAllText(Path.Combine(root, "README.md"));
+        var configPage = File.ReadAllText(Path.Combine(root, "Configuration", "configPage.html"));
 
         Assert.Contains("Append picked folder", readme, StringComparison.Ordinal);
+        Assert.Contains("Full Catalog and Favorites Are Separate Rails", readme, StringComparison.Ordinal);
+        Assert.Contains("Do not point **All Titles STRM Path** and **Favorites STRM Path** at the same directory", readme, StringComparison.Ordinal);
+        Assert.Contains("Each output", readme, StringComparison.Ordinal);
+        Assert.Contains("Running a scheduled task is not enough by itself", readme, StringComparison.Ordinal);
+        Assert.Contains("If the matching enable flag is off", readme, StringComparison.Ordinal);
+        Assert.Contains("Requires **Generate full catalog library** to be enabled", readme, StringComparison.Ordinal);
+        Assert.Contains("Requires **Generate favorites library** to be enabled", readme, StringComparison.Ordinal);
         Assert.Contains("Mirror Governance, plain rule", readme, StringComparison.Ordinal);
         Assert.Contains("does not delete anything", readme, StringComparison.Ordinal);
         Assert.Contains("Existing `.nfo` files and artwork that were not generated by this plugin are preserved", readme, StringComparison.Ordinal);
@@ -145,6 +153,9 @@ public void PublicReadme_DocumentsOperationalCapabilities()
         Assert.Contains("Run manually through **Sync AniLiberty watch progress to Jellyfin**", readme, StringComparison.Ordinal);
         Assert.Contains("If the server has exactly one Jellyfin user", readme, StringComparison.Ordinal);
         Assert.Contains("Sync step (seconds)", readme, StringComparison.Ordinal);
+        Assert.Contains("Do not reuse the favorites path", configPage, StringComparison.Ordinal);
+        Assert.Contains("When OFF, the task exits without updating Favorites STRM Path", configPage, StringComparison.Ordinal);
+        Assert.Contains("When OFF, the task exits without updating All Titles STRM Path", configPage, StringComparison.Ordinal);
     }
 
     [Fact]

Configuration/configPage.html

@@ -306,6 +306,7 @@ <h2 class="sectionTitle">
                             </label>
                         </div>
                         <div class="fieldDescription picker-note">
+                            Use a dedicated full-catalog output root. Do not reuse the favorites path.
                             The browser directory picker can only return the selected folder name.
                             Enable append mode to add that folder name to the current path instead of replacing it.
                         </div>
@@ -326,6 +327,7 @@ <h2 class="sectionTitle">
                             </label>
                         </div>
                         <div class="fieldDescription picker-note">
+                            Use a dedicated favorites output root. Do not reuse the full-catalog path.
                             The browser directory picker can only return the selected folder name.
                             Enable append mode to add that folder name to the current path instead of replacing it.
                         </div>
@@ -344,11 +346,17 @@ <h2 class="sectionTitle">
                         <input id="EnableFavorites" is="emby-checkbox" type="checkbox">
                         <span>Generate favorites library</span>
                     </label>
+                    <div class="fieldDescription">
+                        Controls the Favorites scheduled task. When OFF, the task exits without updating Favorites STRM Path.
+                    </div>
 
                     <label class="checkboxContainer">
                         <input id="EnableAll" is="emby-checkbox" type="checkbox">
                         <span>Generate full catalog library</span>
                     </label>
+                    <div class="fieldDescription">
+                        Controls the full-catalog scheduled task. When OFF, the task exits without updating All Titles STRM Path.
+                    </div>
 
                     <!-- All titles -->
                     <fieldset>

README.md

@@ -204,6 +204,38 @@ server path. For Docker and headless servers, type the real server-visible path
 **Append picked folder** only when the current text box already contains the parent path and you
 want the picker to append one child folder name.
 
+### Full Catalog and Favorites Are Separate Rails
+
+AniLiberty STRM Plugin deliberately writes the full catalog and favorites into different output
+roots:
+
+- **All Titles STRM Path** is the full-catalog reconstruction rail.
+- **Favorites STRM Path** is the personal favorites reconstruction rail.
+
+The rails are operated separately:
+
+- **Generate full catalog library** enables or disables the full-catalog rail.
+- **Generate favorites library** enables or disables the favorites rail.
+- **Generate AniLiberty STRM library** updates only the full-catalog root.
+- **Generate AniLiberty STRM (Favorites Only)** updates only the favorites root and requires a valid
+  AniLiberty token.
+
+Running a scheduled task is not enough by itself. If the matching enable flag is off, or the matching
+path is empty, that task exits without generating files. Save plugin settings before running either
+task.
+
+This is not duplication by accident. Favorites are often a smaller, authenticated operational
+surface that you may want to scan, schedule, or expose separately from the full catalog. In Jellyfin
+you can add them as two separate libraries, for example:
+
+- `/media/aniliberty-strm/all`
+- `/media/aniliberty-strm/favorites`
+
+Do not point **All Titles STRM Path** and **Favorites STRM Path** at the same directory. Each output
+root owns its own `.aniliberty-strm-plugin/manifest.json`; cleanup decisions are made per root. If
+both rails share one folder, one rail can treat the other rail's generated files as stale, especially
+when **Stale generated files** is set to `Delete managed stale files`.
+
 Recommended first run:
 
 1. Open **Dashboard → Plugins → AniLiberty STRM**.
@@ -223,14 +255,17 @@ The first successful run creates the governance manifest
 artwork, and skip-control files where the upstream signal contains them.
 
 For favorites, complete **AniLiberty authentication** first, set **Favorites STRM Path** to a
-container-visible path such as `/media/aniliberty-strm/favorites`, then run
-**Generate AniLiberty STRM (Favorites Only)**.
+container-visible path such as `/media/aniliberty-strm/favorites`, keep **Generate favorites
+library** enabled, then run **Generate AniLiberty STRM (Favorites Only)**. Add that favorites path
+as a separate Jellyfin library if you want a dedicated favorites surface.
 
 If the output directory stays empty, check these control points:
 
 - The plugin path is the Docker container path, not the host path.
 - The mounted folder is writable by the Jellyfin container user.
 - The selected rail is enabled in plugin settings.
+- The scheduled task matches the path you expect: full catalog task writes only **All Titles STRM Path**,
+  favorites task writes only **Favorites STRM Path**.
 - The scheduled task was run after saving settings.
 - Favorites generation has a valid AniLiberty token.
 - Playback clients can reach **Jellyfin Playback Proxy Base URL** if the playback proxy is enabled.
@@ -295,8 +330,8 @@ Open **Dashboard → Plugins → AniLiberty STRM**.
 
 | Field                        | Meaning                                                                 |
 |------------------------------|-------------------------------------------------------------------------|
-| **All Titles STRM Path**     | Root for the full-catalog reconstruction rail. Leave empty to disable. |
-| **Favorites STRM Path**      | Root for the favorites reconstruction rail.                            |
+| **All Titles STRM Path**     | Dedicated root for the full-catalog reconstruction rail. Leave empty to disable. |
+| **Favorites STRM Path**      | Dedicated root for the favorites reconstruction rail. Keep it separate from the full-catalog root. |
 | **Preferred Resolution**     | HLS quality policy for STRM playback entries: 1080 / 720 / 480.        |
 | **Generate favorites library** | Enables the favorites orchestration rail.                            |
 | **Generate full catalog library** | Enables the full-catalog orchestration rail.                       |
@@ -378,14 +413,18 @@ Three orchestration rails appear under **Dashboard → Scheduled Tasks → AniLi
 
 1. **Full Catalog Reconstruction Rail**
    - Acquires the complete AniLiberty catalog signal from `/anime/catalog/releases`.
+   - Requires **Generate full catalog library** to be enabled.
    - Applies `AllTitlesPageSize` and `AllTitlesMaxPages` as acquisition pressure controls.
    - Produces STRM playback entries, metadata, skip markers, thumbnails, and optional chapters
      under **All Titles STRM Path**.
+   - Does nothing when **All Titles STRM Path** is empty.
    - By default runs **once per day**.
 
 2. **Favorites Reconstruction Rail**
    - Requires a valid `AniLibertyToken`.
+   - Requires **Generate favorites library** to be enabled.
    - Converts the authenticated favorites signal into the same governed media surface under **Favorites STRM Path**.
+   - Does nothing when **Favorites STRM Path** is empty.
    - Has no default trigger; you can enable and schedule it as you like.
 
 3. **Watch-State Recovery Rail**