Refresh project documentation

AGENTS.md

@@ -0,0 +1,7 @@
+- Always bump `VERSION` unless the only changed files are `Dockerfile`, `*.md`, or `VERSION` itself.
+- Always document code and behavior changes in `CHANGELOG.md` unless the only changed files are `Dockerfile`, `*.md`, or `VERSION` itself.
+- Update `README.md` whenever user-facing behavior, setup, runtime requirements, Docker usage, or provider state changes.
+- Commit changes with a clear commit message and push them after verification.
+- Preserve data from existing Kaizoku instances. Updates must not wipe `.kaizoku/` state, configuration, queue history, watchlists, thumbnails, downloads, or Jellyfin library content.
+- When needed, install project tools with `pip` or the platform package manager.
+- LAN URLs and `github.com` URLs may be accessed when needed for this project.

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+- Updated the bundled Anikoto, AniNeko, and AnimePahe provider notes to match the current upstream provider versions.
+- Documented the latest provider refresh: Anikoto `5.0.2`, AniNeko `3.0.3`, and AnimePahe `4.0.1`.
+- Documented the Config page provider update check and the current `unittest`-compatible local test command.
+- Clarified project maintenance notes for future agent work.
+
 ## 0.52.10 - 2026-08-10
 
 - Made Docker UID/GID startup ownership fixes best-effort per mount so read-only or policy-managed Jellyfin bind mounts do not prevent Kaizoku from starting.

README.md

@@ -1,11 +1,11 @@
 # Kaizoku
 
-Kaizoku is a local web app for searching, tracking, and downloading anime from Anikoto, AniNeko, and AnimePahe.
+Kaizoku is a local web app for searching, tracking, and downloading anime from Anikoto, AniNeko, and AnimePahe. It keeps its own SQLite state under `.kaizoku/`, resolves streams through bundled JavaScript provider modules, and finalizes downloads into Jellyfin-friendly TV or movie folders.
 
 ## Features
 
 - Search anime through the configured provider and tag results with available `SUB` and `DUB` episode languages.
-- Choose the active search provider directly from the Search page.
+- Choose the active provider from Config defaults or directly from the Search page.
 - Prefer provider-supplied search artwork, with a local title-based thumbnail fallback when provider artwork is missing or broken.
 - Fill Watchlist thumbnails from AnimeSchedule or AniDB title metadata when provider artwork is missing.
 - Queue single episodes or batches in subbed or dubbed mode.
@@ -20,6 +20,7 @@ Kaizoku is a local web app for searching, tracking, and downloading anime from A
 - Hand completed libraries to Jellyfin TV or movie folders.
 - Export/import watchlist backups.
 - Send unified Discord notifications for downloads, refreshes, Jellyfin handoff, and runtime errors.
+- Check bundled provider JavaScript against upstream `TheYogMehta/extensions` from the Config page.
 - Store configuration, queue state, and watchlist data in SQLite under `.kaizoku/`.
 
 ## Requirements
@@ -28,6 +29,7 @@ Kaizoku is a local web app for searching, tracking, and downloading anime from A
 - Node.js and npm for the provider bridge.
 - `ffmpeg` available in `PATH`.
 - `openssl` available in `PATH` for AES-128 encrypted HLS segments.
+- `pytest` is optional; the current regression tests are `unittest`-compatible and can run with the Python standard library.
 - Docker builds install the locked Node dependencies with `npm ci`; rebuild the image after dependency updates.
 
 Install Node dependencies once:
@@ -48,6 +50,12 @@ Then open:
 http://127.0.0.1:8421/
 ```
 
+Run the local regression tests:
+
+```sh
+python3 -m unittest -q
+```
+
 Useful environment variables:
 
 - `KAIZOKU_HOST=0.0.0.0`
@@ -91,7 +99,9 @@ Keep `./.kaizoku` mounted for production instances. That directory contains the
 
 ## Download Flow
 
-Kaizoku stores provider-backed show IDs as `provider:id`, for example `anikoto:some-show-slug`. Queue jobs resolve the episode source through `providers/bridge.js`, then `provider_downloader.py` downloads the media with `ffmpeg` into a staging directory. If a provider returns a master HLS playlist, Kaizoku selects the highest-bandwidth variant before starting `ffmpeg`. When a media playlist uses extensionless CDN segments, Kaizoku skips direct ffmpeg and uses a StrawVerse-style segment downloader: it fetches the media playlist, downloads and concatenates segments itself, strips short PNG wrappers when present, then remuxes the local transport stream to MP4. Direct ffmpeg attempts also have a timeout guard so stalled HLS inputs can fall back cleanly. Each episode is written as a temporary `.mp4.part` file and moved into place only after the download succeeds, so failed fallback attempts do not leave broken final MP4 files behind. If the primary provider cannot list, resolve, or download a requested episode, Kaizoku searches the same title on the remaining providers and tries the matching episode there. Existing finalization code moves staged files into the configured library layout, preserving data already present in production download folders.
+Kaizoku stores provider-backed show IDs as `provider:id`, for example `anikoto:some-show-slug`. Queue jobs resolve the episode source through `providers/bridge.js`, then `provider_downloader.py` downloads the media with `ffmpeg` into a staging directory. If a provider returns a master HLS playlist, Kaizoku selects the highest-bandwidth variant before starting `ffmpeg`. When a media playlist uses extensionless CDN segments, Kaizoku skips direct ffmpeg and uses a StrawVerse-style segment downloader: it fetches the media playlist, downloads and concatenates segments itself, strips short PNG wrappers when present, then remuxes the local transport stream to MP4. Direct ffmpeg attempts also have a timeout guard so stalled HLS inputs can fall back cleanly. Each episode is written as a temporary `.mp4.part` file and moved into place only after the download succeeds, so failed fallback attempts do not leave broken final MP4 files behind.
+
+If the primary provider cannot list, resolve, or download a requested episode, Kaizoku searches the same title on the remaining providers and tries the matching episode there. Existing finalization code moves staged files into the configured library layout, preserving data already present in production download folders.
 
 ## Data Safety
 
@@ -99,4 +109,10 @@ Kaizoku uses additive SQLite migrations for queue and watchlist schema changes.
 
 ## Provider Source
 
-The Anikoto, AniNeko, and AnimePahe parser modules in `providers/extensions/Anime/` are adapted from [TheYogMehta/extensions](https://github.com/TheYogMehta/extensions) and retain their GPL/license headers. Kaizoku acts as a local client-side parser/downloader wrapper and does not host media.
+The Anikoto, AniNeko, and AnimePahe parser modules in `providers/extensions/Anime/` are adapted from [TheYogMehta/extensions](https://github.com/TheYogMehta/extensions) and retain their GPL/license headers. The bundled anime provider versions are currently:
+
+- Anikoto `5.0.2`
+- AniNeko `3.0.3`
+- AnimePahe `4.0.1`
+
+The Config page checks the bundled JavaScript against the upstream `main` branch and reports whether local provider files differ. Kaizoku acts as a local client-side parser/downloader wrapper and does not host media.