fix(launcher): address sync review feedback

fix(launcher): address code review findings in stats sync
- merge-catalog: stop dropping anilist_id on every new anime insert (bun:sqlite .get() returns null, so the old !== undefined guard always fired); the guard was dead anyway since a colliding id is caught earlier - sync-command: throw instead of fail() inside runHostSync so the finally block runs and temp dirs holding snapshot data are cleaned up on failure - ssh: shell-quote the user-supplied --remote-cmd in the probe, and reject option-like (-prefixed) SSH hosts that ssh/scp would parse as flags - sync-db: close the remote handle if opening the local DB throws - sync-shared: treat EPERM from process.kill(pid, 0) as alive, not dead - cli-parser: trim the sync host before the mode-exclusivity check - tests: cover anilist_id preservation, anilist-based anime matching, and the SSH host/shell-quote guards
2026-07-27 16:49:51 -07:00 · 2026-07-09 00:30:43 -07:00 · 2026-07-08 23:51:46 -07:00 · 2026-07-08 23:28:10 -07:00 · 2026-07-08 22:35:47 -07:00 · 2026-07-08 22:26:34 -07:00
569 changed files with 42977 additions and 10625 deletions
@@ -1,7 +1,7 @@
 name: Bug Report
 description: Report something that is broken or behaving incorrectly
-title: "[Bug]: "
-labels: ["bug"]
+title: '[Bug]: '
+labels: ['bug']
 body:
  - type: markdown
    attributes:
@@ -1,7 +1,7 @@
 name: Feature Request
 description: Suggest a new feature or an improvement to an existing one
-title: "[Feature]: "
-labels: ["enhancement"]
+title: '[Feature]: '
+labels: ['enhancement']
 body:
  - type: markdown
    attributes:
@@ -31,6 +31,6 @@ If docs-site/ changed, also: bun run docs:test && bun run docs:build

 ## Checklist

- [ ] Added a changelog fragment, or this PR is labeled `skip-changelog` (see [`changes/README.md`](../changes/README.md))
+- [ ] Reconciled current-outcome changelog fragment(s), or this PR is labeled `skip-changelog` (see [`changes/README.md`](../changes/README.md))
 - [ ] Docs updated in the same PR if behavior, defaults, flags, shortcuts, ports, or APIs changed
 - [ ] Relevant checks pass locally (typecheck, tests, build)
@@ -55,9 +55,6 @@ jobs:
      - name: Verify generated config examples
        run: bun run verify:config-example

-      - name: Internal docs knowledge-base checks
-        run: bun run test:docs:kb
-
      - name: Test suite (source)
        run: bun run test:fast

@@ -71,6 +68,9 @@ jobs:
          path: coverage/test-src/lcov.info
          if-no-files-found: error

+      - name: Stats UI tests
+        run: bun run test:stats
+
      - name: Launcher smoke suite (source)
        run: bun run test:launcher:smoke:src

@@ -70,6 +70,9 @@ jobs:
          path: coverage/test-src/lcov.info
          if-no-files-found: error

+      - name: Stats UI tests
+        run: bun run test:stats
+
      - name: Launcher smoke suite (source)
        run: bun run test:launcher:smoke:src

@@ -61,6 +61,9 @@ jobs:
          path: coverage/test-src/lcov.info
          if-no-files-found: error

+      - name: Stats UI tests
+        run: bun run test:stats
+
      - name: Launcher smoke suite (source)
        run: bun run test:launcher:smoke:src

@@ -1,5 +1,6 @@
 # Dependencies
 node_modules/
+/package-lock.json

 # Superpowers brainstorming
 .superpowers/
@@ -16,6 +17,8 @@ coverage/

 # Launcher build artifact (produced by make build-launcher)
 /subminer
+/main-entry.js
+/main-entry.js.map

 # Logs
 *.log
@@ -42,7 +42,10 @@ Start here, then leave this file.
 - Config/schema/defaults: `bun run test:config`; if template/defaults changed, `bun run generate:config-example`
 - Launcher/plugin: `bun run test:launcher` or `bun run test:env`
 - Runtime-compat / dist-sensitive: `bun run test:runtime:compat`
+- Stats dashboard UI (`stats/`): `bun run test:stats`
+- Build/release scripts (`scripts/**`): `bun run test:scripts`
 - Docs-only: `bun run docs:test`, then `bun run docs:build`
+- Test lanes are directory-discovered via `scripts/test-lanes.ts`; never hand-list test files in `package.json`

 ## Docs Upkeep

@@ -68,7 +71,7 @@ Start here, then leave this file.

 ## Release / PR Notes

- User-visible PRs need one fragment in `changes/*.md` — format and rules in [`changes/README.md`](./changes/README.md) (`type` + `area` keys required; apply the `skip-changelog` label to opt out)
+- User-visible PRs need reconciled current-outcome fragment(s) in `changes/*.md` — format and rules in [`changes/README.md`](./changes/README.md) (`type` + `area` keys required; inspect existing same-PR fragments, then update/remove stale bullets or add only genuinely separate outcomes; apply the `skip-changelog` label to opt out)
 - User-visible docs changes get a `type: docs` fragment
 - CI enforces `bun run changelog:lint` and `bun run changelog:pr-check`
 - PR review helpers:
@@ -1,12 +1,121 @@
 # Changelog

+## v0.17.2 (2026-06-28)
+
+### Fixed
+- YouTube Background Cache: Fixed Windows YouTube background media cache startup for YouTube URLs opened directly in mpv, including resolved stream URLs when mpv still exposes the original YouTube playlist entry, so queued Anki media updates can append audio and images after the cache finishes.
+- YouTube Subtitle Picker: Manual subtitle picker requests now show an immediate configured notification while SubMiner probes tracks and opens the modal. Subtitle download progress is replaced with a transient success notification after tracks load.
+
+## v0.17.1 (2026-06-27)
+
+### Added
+- YouTube Media Cache Mode: Adds `youtube.mediaCache.mode` with `direct` and `background` options. Background mode uses a yt-dlp cache download when direct stream extraction is unreliable — creates a text-only card immediately, queues media updates for mined notes, and fills audio/image fields once the download finishes. Progress is announced via overlay/OSD notifications. Downloads are capped at 720p by default (`youtube.mediaCache.maxHeight`). Switching back to direct mode cancels any in-flight background download.
+
+### Fixed
+- Log Export: Fixed log filenames to use the local date so exports around UTC midnight include the current day's logs rather than stale prior-day files. Expanded export redaction to mask IPs, emails, auth and cookie headers, yt-dlp cookie arguments, URL credentials, token/key/password fields, and signed YouTube media URL parameters.
+- YouTube Card Media: Improved media generation reliability by sending safer ffmpeg options for resolved streams and skipping stale stream maps (including cached YouTube files). Hardened background cache downloads with IPv4 and extractor retry flags; failed downloads now notify the user and clear queued media updates instead of leaving them silently pending. Stale background cache files are cleaned on startup and before each new download.
+
+## v0.17.0 (2026-06-15)
+
+### Changed
+
+- **Subtitle Delay Keybindings**: Updated default overlay subtitle delay and step bindings to match mpv conventions: `z`, `Z`, and `x` adjust `sub-delay`; `Ctrl+Shift+Left/Right` run native `sub-step` with OSD feedback. The previous SubMiner-only adjacent-cue delay action has been removed.
+- **Update Notifications**: New installs now default update notifications to overlay-only instead of overlay + system notifications.
+
+### Fixed
+
+- **Anki – Highlight Word**: Fixed bolding of the mined word in Kiku sentence and sentence-furigana fields when the source Yomitan sentence did not already contain bold markup.
+- **Anki – Lapis/Kiku Word Cards**: Fixed word-and-sentence marker missing from Lapis/Kiku word cards enriched through SubMiner, which could hide sentence context on the card front.
+- **Anki – Windows Media Generation**: Fixed known-word cache refreshes when no deck is configured, and fixed audio/image generation after background launches by recreating missing FFmpeg temp directories before clipping.
+- **Character Dictionary – Windows**: Fixed the Windows "SubMiner mpv" shortcut so character dictionary auto-sync can fall back to mpv's current video path when app media state is not yet ready.
+- **Notifications**: Restored the SubMiner app icon on system notifications that do not supply a custom notification image.
+- **Overlay – macOS Yomitan Popup**: Fixed Yomitan popup focus after card mining or popup reload; fixed popups staying open when clicking transparent overlay space — click-away now closes the popup and returns click passthrough to mpv without a hide/reappear cycle.
+- **Overlay – Linux Auto-Pause Startup**: Fixed the visible overlay on Linux auto-paused startup to stay interactive during the initial measurement gap; startup subtitle cache misses now paint raw text before tokenization finishes, and temporarily empty `sub-text` refreshes are resolved before warm readiness resumes playback.
+- **Overlay – Playlist Advance**: Fixed the visible overlay being dismissed when mpv advances to the next playlist item, including when the next episode loads after the warm transition delay.
+- **Overlay – Windows Subtitle Bar**: Fixed shaky hover and click interaction on the Windows subtitle bar when a video attaches to an already-running background SubMiner instance.
+- **Stats – AniList Linking**: Fixed manual AniList linking from the stats anime page so auto-searches strip the generated "Season N" suffix and query only the anime title.
+- **Updates – Linux Support Assets**: Fixed Linux updates to correctly install and refresh the launcher runtime plugin copy and rofi theme alongside AppImage and launcher updates; unrelated SubMiner data directories are now left untouched and plugin copies are staged before replacing the live runtime. Fixed first-launch playback on fresh installs by auto-installing missing managed support assets from the bundled app before mpv starts.
+
+### Docs
+
+- **Linux Update Flows**: Documented that Linux update flows manage the launcher runtime plugin copy and rofi theme from `subminer-assets.tar.gz`, and that normal launcher playback auto-installs those managed support assets on a fresh install if either is missing.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+
+- **Runtime Modules**: Split main-process runtime wiring into focused modules without changing user-facing behavior; hardened helpers against stale background stats daemon PIDs, stalled subtitle extraction, and dropped async errors.
+- **Release CI**: Fixed GitHub release notes to preserve the `What's Changed` and `New Contributors` attribution sections when CI regenerates from the committed changelog; scoped prerelease note reuse to the same base version so a new beta line starts from current fragments.
+
+</details>
+
+## v0.16.0 (2026-06-10)
+
+### Breaking Changes
+
+- **Notification Mode `both`**: `notificationType: "both"` now routes to overlay + system notifications. Users who previously used `"both"` for mpv OSD + system notifications should set `notificationType` to `"osd-system"` in `config.jsonc`. The `osd` and `osd-system` values remain valid as config-file entries but no longer appear in Settings.
+
+### Added
+
+- **Overlay Notifications**: New overlay notification stack (Catppuccin Macchiato theme) with configurable screen position (`notifications.overlayPosition`: top-left, top-center, top-right), 3-second transient dismissals, and persistent cards for long-running jobs like character dictionary sync.
+- **Notification History Panel**: `Ctrl/Cmd+N` (configurable via `shortcuts.toggleNotificationHistory`) opens a session log of all notifications. Works whether the overlay or mpv has focus; slides in from the notification edge; entries can be individually removed or cleared.
+- **Mined-Card Notification Actions**: Mined-card overlay notifications show generated card thumbnails and include an Open in Anki button in both live cards and history entries.
+- **Update Notification Action**: Update-available overlay notifications include an Update button to start the app update flow directly from the notification.
+- **Stats Search**: New Search tab in Stats for realtime subtitle sentence search with media context, headword matching, and mining actions for source-backed sentence cards or exact-match word/audio cards.
+
+### Changed
+
+- **AniSkip**: Moved intro detection from the mpv plugin to the SubMiner app. Lookups now cover every file loaded during a session including playlist advances, and `mpv.aniskipEnabled`/`mpv.aniskipButtonKey` hot-reload without restarting playback. The bundled plugin no longer makes network calls. Note: AniSkip now requires the SubMiner app to be connected; plugin-only mpv sessions will not fetch skip windows.
+- **Stats Library**: Entries are now split by detected season (season folder first, filename parsing as fallback). Existing combined-series rows are automatically migrated to per-season entries on startup. Cover art and anime details refresh immediately after a manual AniList entry change.
+- **Stats Vocabulary**: Remembers Hide Known/Hide Kana filters across sessions, applies Hide Kana filtering cross-title, collapses duplicate token variants in exclusions, and matches Related Seen Words by shared readings or kanji.
+- **Stats Trends**: Reorganized into Activity, Cumulative Totals, Efficiency, Patterns, and Library sections; disambiguated per-period vs. cumulative charts; added Words/Min and Cards/Hour efficiency charts.
+- **Stats Mining**: Sentence cards are created before slow media generation finishes; stored/requested secondary subtitles are preserved before falling back to sidecar or alass-retimed English subtitles; empty `ankiConnect.deck` falls back to Yomitan's mining deck; partial media failures are surfaced.
+- **Stats Browsing**: Remembers library card size; retries stored cover art without extra AniList lookups; preserves PNG/WebP MIME types; honors custom AnkiConnect URLs for Browse; shows progress during session deletes.
+- **Startup Notifications**: Tokenization, subtitle annotation, and character dictionary status now route through queued overlay notifications in `overlay`/`both` mode instead of falling back to mpv OSD while the overlay loads.
+- **Notification Deduplication**: Cycling subtitle modes updates the active overlay card in place rather than stacking duplicates; repeated progress updates (e.g. subsync) tick in place without flickering.
+- **Update Notification Default**: New installs default `notificationType` to `both` so update alerts appear in both overlay and system notifications.
+
+### Fixed
+
+- **AniList Completion**: Entries are now marked completed when a post-watch update reaches the final known episode of the season.
+- **AniSkip Markers**: Fixed intro markers disappearing after same-media mpv reloads; fixed metadata detection for intros that start at 0 seconds and common release-group filenames.
+- **Jellyfin Session**: Remote session now restarts after setup login so the websocket reconnects with fresh credentials, and stops cleanly on logout.
+- **Sentence Card Audio**: Mining a sentence card no longer fills the expression audio field; generated audio goes only to the configured sentence audio field.
+- **Stats Mining Fields**: Sentence clips update `SentenceAudio` correctly; word audio uses configured Yomitan sources; English subtitle text is not written to word cards; secondary subtitle auto-selection prefers regular English tracks over Signs/Songs tracks.
+- **Overlay Hover Readiness**: Subtitle bars are hoverable and clickable from the first subtitle line on visible overlay startup or resume, without waiting for the next subtitle event.
+- **Startup Autoplay**: Playback is released after tokenization and overlay content are ready even when playback begins before the first subtitle line appears.
+- **Overlay Startup Feedback**: Restored mpv OSD loading spinner that starts on connect, media open, or overlay request, and clears once the overlay is content-ready and visible.
+- **Linux Overlay Input**: Notification close and action buttons remain clickable above subtitle bars on Linux.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+- **Build**: `make deps` now initializes git submodules before installing dependencies on a fresh source checkout.
+- **Release Tooling**: Release notes now credit contributors and first-time authors resolved from changelog fragments via git and the GitHub API.
+- **Changelog Guidance**: PR fragment guidance updated to preserve separate-outcome fragments while directing contributors to consolidate same-PR follow-up notes before adding churn.
+
+</details>
+
+## v0.15.2 (2026-06-02)
+
+### Changed
+- Yomitan: Updated the bundled Yomitan build to the latest vendored revision.
+
+### Fixed
+- Anki - Animated AVIF: Clip timing no longer starts or ends early; word-audio lead-in and clip duration are now aligned to frame boundaries.
+- Overlay (Hyprland): Fixed fullscreen overlay alignment - modal, stats, and sidebar content no longer shift below the mpv window.
+- Overlay (macOS): Subtitle bars are now interactive immediately after autoplay starts with "wait for overlay to be ready" enabled, without requiring a manual click.
+- Overlay (macOS): Fixed overlay, subtitles, and subtitle sidebar staying hidden after a modal closes until the user clicked the mpv window; focus is now restored to mpv when the last modal closes, so playback shortcuts and the overlay reappear correctly - including in native fullscreen.
+
 ## v0.15.1 (2026-05-31)

 ### Fixed

 - **Linux Overlay Stacking**: Fixed the overlay intermittently dropping behind mpv on KDE Plasma and other non-Hyprland/Sway Wayland sessions; restored subtitle hover, pause-on-hover, and Yomitan lookups on X11/XWayland; the overlay now correctly layers above/below mpv based on fullscreen state, yields to foreground windows (Settings, Yomitan, AniList, etc.), and avoids startup flashes and fullscreen transition glitches.
 - **Linux Overlay (Hyprland Lua)**: Fixed overlay placement on Hyprland 0.55+ when using a Lua-based config.
- **Manual Overlay Startup**: Fixed manual visible-overlay startup from mpv — now correctly attaches to playback, keeps the window bounds synced with mpv, and primes current subtitles before showing.
+- **Manual Overlay Startup**: Fixed manual visible-overlay startup from mpv - now correctly attaches to playback, keeps the window bounds synced with mpv, and primes current subtitles before showing.
 - **Playlist Transitions**: Reused the warm overlay when mpv advances to the next playlist item, avoiding a redundant tokenization pause and preserving visible subtitles across tracks.
 - **macOS Overlay**: Fixed the visible subtitle overlay staying click-through after pause-until-ready releases playback; restored mpv focus after closing modal windows so subtitles and keybinds resume without clicking the player.
 - **Mouse Keybindings**: Fixed keybinding capture and runtime handling for mouse buttons, including side buttons like `MBTN_BACK` and `MBTN_FORWARD`.
@@ -25,7 +134,7 @@
  - Subsync now always opens the manual subtitle picker regardless of any previously set default mode
 - **N+1 Highlighting:**
  - N+1 highlighting now has its own dedicated `ankiConnect.nPlusOne.enabled` option, separate from known-word highlighting
-  - It is no longer enabled automatically when known-word highlighting is on — enable it explicitly to keep N+1 annotations
+  - It is no longer enabled automatically when known-word highlighting is on - enable it explicitly to keep N+1 annotations

 ### Added

@@ -172,7 +281,7 @@

 ### Added

- **Character Dictionary:** Added AniList-based character dictionary selection for resolving title mismatches — open it in-app with the new `Ctrl+Alt+A` shortcut or from the CLI with `subminer dictionary --candidates` / `--select`. Series-scoped overrides replace stale entries in the merged dictionary.
+- **Character Dictionary:** Added AniList-based character dictionary selection for resolving title mismatches - open it in-app with the new `Ctrl+Alt+A` shortcut or from the CLI with `subminer dictionary --candidates` / `--select`. Series-scoped overrides replace stale entries in the merged dictionary.
 - **Primary Subtitle Bar:** Added a `V` shortcut and mpv plugin binding to toggle the primary subtitle bar without affecting mpv's native subtitle visibility.
 - **Texthooker:** Added `subminer texthooker -o` and a tray menu item to open the local texthooker page in the default browser.

@@ -226,7 +335,7 @@
 ### Internal

 - Replaced the changelog renderer with an AI polish pass that merges related fragments and writes user-facing release notes. `CHANGELOG.md` keeps internal items in a collapsed `<details>` block; GitHub release notes omit them entirely.
- Release CI no longer auto-builds pending `changes/*.md` fragments on tag. Tagging now fails fast if fragments remain — run `bun run changelog:build` (requires the `claude` CLI) and commit before tagging.
+- Release CI no longer auto-builds pending `changes/*.md` fragments on tag. Tagging now fails fast if fragments remain - run `bun run changelog:build` (requires the `claude` CLI) and commit before tagging.

 </details>

@@ -245,8 +354,8 @@
 - Stats: Episode detail hides card events whose Anki notes have been deleted, instead of showing phantom mining activity.
 - Stats: Trend and watch-time charts share a unified theme with horizontal gridlines and larger ticks for legibility.
 - Stats: Overview, Library, Trends, Sessions, and Vocabulary now use generic "title" wording so YouTube videos and anime live comfortably side by side in the dashboard.
- Stats: Session timeline no longer plots seek-forward/seek-backward markers — they were too noisy on sessions with lots of rewinds.
- Stats: Replaced the "Library — Per Day" section on the Stats → Trends page with a "Library — Summary" section. The new section shows a top-10 watch-time leaderboard chart and a sortable per-title table (watch time, videos, sessions, cards, words, lookups, lookups/100w, date range), all scoped to the current date range selector.
+- Stats: Session timeline no longer plots seek-forward/seek-backward markers - they were too noisy on sessions with lots of rewinds.
+- Stats: Replaced the "Library - Per Day" section on the Stats → Trends page with a "Library - Summary" section. The new section shows a top-10 watch-time leaderboard chart and a sortable per-title table (watch time, videos, sessions, cards, words, lookups, lookups/100w, date range), all scoped to the current date range selector.

 ### Fixed

@@ -1 +0,0 @@
-AGENTS.md
@@ -1,4 +1,4 @@
-.PHONY: help deps build build-launcher install build-linux build-macos build-macos-unsigned clean install-linux install-macos install-windows uninstall uninstall-linux uninstall-macos uninstall-windows print-dirs pretty lint ensure-bun generate-config generate-example-config dev-start dev-start-macos dev-watch dev-watch-macos dev-toggle dev-stop docs-test docs-build docs-build-versioned docs-dev
+.PHONY: help submodules deps build build-launcher install build-linux build-macos build-macos-unsigned clean install-linux install-macos install-windows uninstall uninstall-linux uninstall-macos uninstall-windows print-dirs pretty lint ensure-bun generate-config generate-example-config dev-start dev-start-macos dev-watch dev-watch-macos dev-toggle dev-stop docs-test docs-build docs-build-versioned docs-dev

 APP_NAME := subminer
 THEME_SOURCE := assets/themes/subminer.rasi
@@ -72,7 +72,8 @@ help:
 		"  generate-config  Generate ~/.config/SubMiner/config.jsonc from centralized defaults" \
 		"" \
 		"Other targets:" \
-		"  deps             Install JS dependencies (root + stats + texthooker-ui)" \
+		"  submodules       Initialize/update git submodules" \
+		"  deps             Initialize submodules and install JS dependencies (root + stats + texthooker-ui)" \
 		"  uninstall-linux  Remove Linux install artifacts" \
 		"  uninstall-macos  Remove macOS install artifacts" \
 		"  uninstall-windows Remove Windows mpv plugin artifacts" \
@@ -105,8 +106,10 @@ print-dirs:
 		"MACOS_APP_SRC=$(MACOS_APP_SRC)" \
 		"MACOS_ZIP_SRC=$(MACOS_ZIP_SRC)"

-deps:
-	@$(MAKE) --no-print-directory ensure-bun
+submodules:
+	@git submodule update --init --recursive
+
+deps: submodules ensure-bun
 	@bun install
 	@cd stats && bun install --frozen-lockfile
 	@cd vendor/texthooker-ui && bun install --frozen-lockfile
@@ -121,6 +121,7 @@ Only **mpv** and Anki+AnkiConnect are required. Everything else is optional but
 | yt-dlp               | Optional    | YouTube playback                         |
 | fzf / rofi           | Optional    | Video picker in the launcher             |
 | alass / ffsubsync    | Optional    | Subtitle sync                            |
+| guessit              | Optional    | Better anime title and episode detection |

 <details>
 <summary><b>Platform-specific install commands</b></summary>
@@ -212,6 +213,7 @@ On **Windows**, just run `SubMiner.exe` and the setup will open automatically on
 subminer video.mkv          # launch mpv with SubMiner
 subminer /path/to/dir       # pick a file with fzf
 subminer -R /path/to/dir    # pick a file with rofi (Linux only)
+subminer -H                 # browse local watch history (replay / next episode / browse)
 ```

 On **Windows**, use the **SubMiner mpv** shortcut created during setup. Double-click it or drag a video file onto it.
@@ -228,6 +230,7 @@ SubMiner builds on the work of these open-source projects:

 | Project                                                                                     | Role                                                                    |
 | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| [ani-skip](https://github.com/synacktraa/ani-skip)                                          | AniSkip API client for anime intro/outro skip timestamps                |
 | [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script)                          | Inspiration for the mining workflow                                     |
 | [asbplayer](https://github.com/killergerbah/asbplayer)                                      | Inspiration for subtitle sidebar and logic for YouTube subtitle parsing |
 | [Bee's Character Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary) | Character name recognition in subtitles                                 |
@@ -31,6 +31,13 @@ Rules:
 - `README.md` is ignored by the generator
 - if a PR should not produce release notes, apply the `skip-changelog` label instead of adding a fragment

+PR branch workflow:
+
+- Before adding a fragment or bullet, inspect the `changes/*.md` files already changed in the PR
+- If the new work fixes, modifies, renames, or supersedes behavior introduced or referenced by that fragment, edit or remove the stale bullet instead of adding follow-up churn
+- Add a new bullet only when it describes a truly separate user-visible outcome
+- Multiple fragment files are allowed when one PR has genuinely separate release-note outcomes, but keep them minimized and current
+
 How fragments turn into a release:

 - At release time, `bun run changelog:build` (and `bun run changelog:prerelease-notes`) pipes every pending fragment through `claude -p` to merge related items, drop noise, and rewrite into a clean user-facing release body. Write fragments as raw, informative notes — don't worry about polished prose, deduping across PRs, or line-by-line phrasing. The polish step handles all of that.
@@ -0,0 +1,4 @@
+type: added
+area: mining
+
+- Normalized generated card audio by default during media extraction, with `ankiConnect.media.normalizeAudio` available to keep raw source loudness when needed.
@@ -0,0 +1,4 @@
+type: fixed
+area: stats
+
+- `subminer app` background launches now start the stats server automatically when `stats.autoStartServer` is enabled, and skip startup when a background stats server is already running.
@@ -0,0 +1,6 @@
+type: fixed
+area: overlay
+
+- Fixed character-dictionary surname/given-name splitting for unspaced AniList native names where romanized reading length misled the boundary guess (東紫乃 split as 東紫+乃, 渡辺真奈美 as 渡辺真+奈美), so surnames like 東 and 渡辺 were never highlighted with character portraits and unmatched leading kanji (渡) lost hover lookup entirely. Name parts are now resolved with MeCab person-name POS tags and reading validation when MeCab is available; without MeCab, terms are generated for both plausible boundaries so the real surname still matches. Existing snapshots regenerate automatically (format version bump), and snapshots built without MeCab are upgraded to exact MeCab splits once MeCab is detected.
+- Fixed subtitle tokenization dropping a character entirely when Yomitan's greedy scan consumed trailing punctuation/whitespace past the term (e.g. 平 in 「（東）平　（平）え？」 matched across the paren with no exact-source headword). The scanner now retries shorter windows so the prefix term still tokenizes with its name match and portrait.
+- Fixed character-name highlights being stripped when MeCab's context-dependent POS tag put the token in the annotation noise filter (e.g. 平 tagged as prefix 接頭詞 in 「あっ 平 これ…」 lost its highlight and portrait even though hover lookup showed the character). Confirmed name matches now survive the POS exclusion filter, and name matching alone keeps the annotation stage active when all other annotations are disabled.
@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Removed 確かに and やはり from the annotation stop-word list so they get frequency/JLPT highlighting again and count toward vocabulary stats; the list now only covers interjections, pronouns, and grammar fragments.
@@ -0,0 +1,4 @@
+type: fixed
+area: stats
+
+- Cover art is now fetched eagerly when a new series starts playing, instead of waiting for the first visit to its series detail page, so the stats timeline shows the best-guess AniList image right away. The stats covers endpoint also backfills missing series art in the background, so existing series without an image pick one up on the next stats page load.
@@ -0,0 +1,4 @@
+type: changed
+area: launcher
+
+- Moved fzf previews below launcher menus so long titles and metadata have more horizontal room.
@@ -0,0 +1,4 @@
+type: added
+area: launcher
+
+- Show cover art icons in the rofi watch-history picker, reusing AniList covers already stored in the stats database (extracted to `~/.cache/subminer/covers`).
@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Kanji-bearing nouns that MeCab tags as non-independent (非自立) — e.g. 日 in いい日だったな, 点, 以外 — now keep frequency/JLPT highlighting and count toward vocabulary stats. Yomitan segments them as standalone vocabulary tokens, so the MeCab POS filter only suppresses kana grammar nouns (こと, もの, とき) it was meant for.
@@ -0,0 +1,4 @@
+type: fixed
+area: anki
+
+- Fixed cancelling the Kiku field grouping dialog showing two "Field grouping cancelled" notifications when grouping was started via the trigger shortcut: the manual workflow already notifies about its outcome (cancelled, UI unavailable, failed), and the trigger path re-notified on top of it. The workflow now owns all outcome notifications, and a previously silent failure (the original card no longer loadable) gets its own message.
@@ -0,0 +1,6 @@
+type: fixed
+area: overlay
+
+- Fixed Kiku manual field grouping freezing the overlay after adding a duplicate card: the field grouping modal now reliably appears above fullscreen mpv on Hyprland/Wayland by re-asserting window placement until the compositor maps the modal window, instead of a single post-show attempt that raced the async map and left the dialog invisible.
+- Fixed manual field grouping staying broken after the first attempt: the request resolver is now always cleared once a choice is made or the request is abandoned, so later grouping attempts no longer short-circuit to an instant "Field grouping cancelled".
+- Fixed a timed-out or failed field grouping request leaving an orphaned, invisible modal window covering mpv: abandoned requests now tear down the modal window and close the dialog so the overlay recovers immediately.
@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed words being highlighted green as known when a same-spelled Anki card taught a different reading (e.g. とこ parsed as 床 "bed" matching a known 床/ゆか "floor" card). The known-word cache now stores each card's word together with its reading and only matches when the token's reading agrees; cards without a reading field keep matching in any reading as before.
@@ -0,0 +1,4 @@
+type: added
+area: launcher
+
+- Added `subminer -H` / `--history` to browse local watch history, replay the last watched episode, continue to the next episode, or browse episodes with fzf/rofi.
@@ -0,0 +1,4 @@
+type: added
+area: launcher
+
+- Added `subminer sync <host>` to merge immersion stats and watch history between two machines over SSH. Each side snapshots its database (`VACUUM INTO`), snapshots are exchanged with `scp`, and each machine merges the other's data as an insert-only union keyed on session UUIDs / video keys / series title keys, so re-syncing is idempotent and nothing is double-counted. Lifetime totals and daily/monthly rollups are updated incrementally (history older than the session retention window is preserved); remote-only historical rollups are copied only when they do not conflict with retained local session history. `subminer sync --snapshot <file>` and `subminer sync --merge <file>` expose the underlying steps for manual transfers. The command refuses to run while the stats daemon or an mpv session is active (`--force` overrides), keeps that guard in place through local/remote merges, reports remote stderr on failures, and aborts on stats schema version mismatches.
@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed character-name annotations dropping for an entire subtitle line when it contained any chunk the dictionary scanner could not match (e.g. an interjection like やほっ before a name): scanner metadata is now merged per token into the parseText segmentation instead of being discarded on any span mismatch.
@@ -0,0 +1,5 @@
+type: fixed
+area: overlay
+
+- Fixed single-kana grammar tokens counting as known words by borrowing the reading of an unrelated Anki note (よ in 全然いいよ matched a card read よ such as 夜, standalone え matched 絵), which painted them with the known-word highlight. Reading-only known-word matching now requires at least two kana; single-kana cards still match by their word field, and tokens genuinely present in the known-words cache (e.g. です) keep their highlight.
+- Standalone suffix tokens (MeCab pos2 接尾, e.g. さん, れる) are now excluded from JLPT/frequency/N+1 annotations by default, matching how particles and interjections are treated. Cache-backed known-word highlighting still applies; override via the pos2 exclusion config if you want them annotated.
@@ -0,0 +1,4 @@
+type: changed
+area: branding
+
+- Replaced the SubMiner app icon with new pixel-art submarine artwork contributed by an anonymous community member, used across the app icon, tray, notifications, README, docs site, and stats page.
@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed secondary subtitles stacking dozens of one-syllable lines down the screen during karaoke-typeset openings/endings, which made the hover-pause band cover the whole video: karaoke-like event spam is now collapsed into a single deduped line, and the secondary subtitle area is height-capped so it always stays a strip at the top.
@@ -0,0 +1,4 @@
+type: fixed
+area: stats
+
+- Session known-word counts no longer show 0 everywhere. The stats server's known-word cache parser only understood the v1/v2 cache formats, so after the reading-aware v3 cache upgrade it silently treated the cache as missing; it now flattens v3 note entries into the headword set.
@@ -0,0 +1,4 @@
+type: fixed
+area: stats
+
+- Show all trend chart titles by default, persist hidden-title choices, and add a per-chart top-title limit selector.
@@ -0,0 +1,7 @@
+type: internal
+area: testing
+
+- Test lanes are now defined once in `scripts/test-lanes.ts` and discovered by directory instead of hand-maintained file lists in `package.json`; the unused `test:core:*`/`test:config:dist`/`test:full` scripts were removed.
+- `scripts/run-test-lane.mjs` runs each test file in an isolated `bun test` process with a wall timeout, so a hanging test or leaked global can no longer cascade failures across the lane.
+- Previously orphaned suites now run in CI: the stats dashboard tests (`bun run test:stats`), the `scripts/**` tests (`bun run test:scripts`, including the change-verification skill tests), the `test-plugin-process-start-retries.lua` plugin test, and the runtime-compat dist slice (now part of `bun run test:fast`).
+- The change-verification skill gained a `stats` lane for `stats/` edits.
@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed subtitle text that Yomitan's parser cannot match (e.g. the truncated volitional in とこ戻ろ…) being rendered as plain, non-interactive text: it was invisible to hover/lookup and excluded from the n+1 word count, which could wrongly mark a sentence as n+1. Unparsed runs are now kept as hoverable tokens matching Yomitan's own segmentation; bracketed SFX/speaker captions and punctuation-only runs are still skipped.
@@ -0,0 +1,4 @@
+type: fixed
+area: youtube
+
+- Fixed direct YouTube stream media extraction by parsing mpv EDL stream URLs with their byte-length guards, preventing trailing EDL segment options from corrupting signed googlevideo URLs and causing ffmpeg 403 errors.
@@ -172,10 +172,19 @@
  "updates": {
    "enabled": true, // Run automatic update checks in the background. Values: true | false
    "checkIntervalHours": 24, // Minimum hours between automatic update checks.
-    "notificationType": "system", // How SubMiner announces available updates. Values: system | osd | both | none
+    "notificationType": "overlay", // How SubMiner announces available updates. overlay shows notifications on the overlay, system uses OS notifications, both uses overlay and system. osd and osd-system are legacy config-file-only values. Values: overlay | system | both | none | osd | osd-system
    "channel": "stable" // Release channel used for update checks. Values: stable | prerelease
  }, // Automatic update check behavior.

+  // ==========================================
+  // Notifications
+  // Overlay notification display behavior.
+  // Hot-reload: position changes apply to the next overlay notification.
+  // ==========================================
+  "notifications": {
+    "overlayPosition": "top-right" // Position for in-overlay notification cards. Values: top-left | top | top-right
+  }, // Overlay notification display behavior.
+
  // ==========================================
  // Keyboard Shortcuts
  // Overlay keyboard shortcuts. Set a shortcut to null to disable.
@@ -199,7 +208,8 @@
    "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
    "openControllerSelect": "Alt+C", // Accelerator that opens the controller selection and learn-mode modal.
    "openControllerDebug": "Alt+Shift+C", // Accelerator that opens the controller debug modal with live axis/button readouts.
-    "toggleSubtitleSidebar": "Backslash" // Accelerator that toggles the subtitle sidebar visibility.
+    "toggleSubtitleSidebar": "Backslash", // Accelerator that toggles the subtitle sidebar visibility.
+    "toggleNotificationHistory": "CommandOrControl+N" // Accelerator that toggles the overlay notification history panel.
  }, // Overlay keyboard shortcuts. Set a shortcut to null to disable.

  // ==========================================
@@ -280,15 +290,41 @@
      ] // Command setting.
    },
    {
-      "key": "Shift+BracketRight", // Key setting.
+      "key": "Ctrl+Shift+ArrowLeft", // Key setting.
      "command": [
-        "__sub-delay-next-line"
+        "sub-step",
+        -1
      ] // Command setting.
    },
    {
-      "key": "Shift+BracketLeft", // Key setting.
+      "key": "Ctrl+Shift+ArrowRight", // Key setting.
      "command": [
-        "__sub-delay-prev-line"
+        "sub-step",
+        1
+      ] // Command setting.
+    },
+    {
+      "key": "KeyZ", // Key setting.
+      "command": [
+        "add",
+        "sub-delay",
+        -0.1
+      ] // Command setting.
+    },
+    {
+      "key": "Shift+KeyZ", // Key setting.
+      "command": [
+        "add",
+        "sub-delay",
+        0.1
+      ] // Command setting.
+    },
+    {
+      "key": "KeyX", // Key setting.
+      "command": [
+        "add",
+        "sub-delay",
+        0.1
      ] // Command setting.
    },
    {
@@ -496,7 +532,7 @@
    "tags": [
      "SubMiner"
    ], // Tags to add to cards mined or updated by SubMiner. Provide an empty array to disable automatic tagging.
-    "deck": "", // Restrict duplicate detection and card enrichment to this Anki deck. Leave empty to search all decks.
+    "deck": "", // Restrict duplicate detection and card enrichment to this Anki deck. Leave empty to use the Yomitan mining deck when available.
    "fields": {
      "word": "Expression", // Card field for the mined word or expression text.
      "audio": "ExpressionAudio", // Card field that receives generated sentence audio.
@@ -523,6 +559,7 @@
      "animatedMaxHeight": 0, // Maximum height for animated AVIF captures, in pixels. Set to 0 to preserve aspect ratio.
      "animatedCrf": 35, // Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.
      "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
+      "normalizeAudio": true, // Normalize generated sentence audio loudness during media extraction. Values: true | false
      "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio and animated AVIF clips.
      "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.
@@ -532,14 +569,14 @@
      "refreshMinutes": 1440, // Minutes between known-word cache refreshes.
      "addMinedWordsImmediately": true, // Immediately append newly mined card words into the known-word cache. Values: true | false
      "matchMode": "headword", // Known-word matching strategy for subtitle annotations. Cache matches always receive known-word highlighting even when POS filters suppress other annotation types. Values: headword | surface
-      "decks": {} // Decks and expression/word fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word"] }.
+      "decks": {} // Decks and expression/word fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word"] }. Reading fields (Reading, Word Reading, ExpressionReading) are always probed so cached words match only in the reading their note teaches; words from notes without readings match in any reading.
    }, // Known words setting.
    "behavior": {
      "overwriteAudio": true, // When updating an existing card, overwrite the audio field instead of skipping it. Values: true | false
      "overwriteImage": true, // When updating an existing card, overwrite the image field instead of skipping it. Values: true | false
      "mediaInsertMode": "append", // Whether new media is appended after or prepended before existing field contents on update. Values: append | prepend
      "highlightWord": true, // Bold the mined word inside the sentence field on the saved Anki card. Values: true | false
-      "notificationType": "osd", // Notification surface used to announce mining and update outcomes. Values: osd | system | both | none
+      "notificationType": "overlay", // Notification surface used to announce mining and update outcomes. overlay shows notifications on the overlay, system uses OS notifications, both uses overlay and system. osd and osd-system are legacy config-file-only values. Values: overlay | system | both | none | osd | osd-system
      "autoUpdateNewCards": true // Automatically update newly added cards. Values: true | false
    }, // Behavior setting.
    "nPlusOne": {
@@ -582,7 +619,11 @@
    "primarySubLanguages": [
      "ja",
      "jpn"
-    ] // Comma-separated primary subtitle language priority for managed subtitle auto-selection.
+    ], // Comma-separated primary subtitle language priority for managed subtitle auto-selection.
+    "mediaCache": {
+      "mode": "direct", // How YouTube card audio/images are extracted. Values: direct | background
+      "maxHeight": 720 // Maximum video height downloaded for the YouTube background media cache. Set to 0 for unlimited.
+    } // Media cache setting.
  }, // Defaults for managed subtitle language preferences and YouTube subtitle loading.

  // ==========================================
@@ -634,8 +675,8 @@
    "autoStartSubMiner": true, // Start SubMiner in the background when SubMiner-managed mpv loads a file. Values: true | false
    "pauseUntilOverlayReady": true, // Pause mpv on visible-overlay auto-start until SubMiner signals subtitle tokenization readiness. Values: true | false
    "subminerBinaryPath": "", // Optional SubMiner app binary path passed to the bundled mpv plugin. Leave empty to use the launcher-detected app path.
-    "aniskipEnabled": true, // Enable AniSkip intro detection and skip markers in the bundled mpv plugin. Values: true | false
-    "aniskipButtonKey": "TAB" // mpv key used to trigger the AniSkip button while the skip marker is visible.
+    "aniskipEnabled": true, // Enable AniSkip intro detection, chapter markers, and the skip-intro key. Values: true | false
+    "aniskipButtonKey": "TAB" // mpv key used to skip the detected intro while the skip prompt is visible.
  }, // SubMiner-managed mpv launch and bundled plugin options.

  // ==========================================
@@ -328,6 +328,7 @@ const sidebar: DefaultTheme.SidebarItem[] = [
      { text: 'YouTube', link: '/youtube-integration' },
      { text: 'Jimaku', link: '/jimaku-integration' },
      { text: 'AniList', link: '/anilist-integration' },
+      { text: 'AniSkip', link: '/aniskip-integration' },
      { text: 'Character Dictionary', link: '/character-dictionary' },
    ],
  },
@@ -4,7 +4,7 @@ SubMiner can sync your watch progress to [AniList](https://anilist.co) automatic

 AniList data also powers two additional features: [cover art](#cover-art) for the stats dashboard and the [Character Dictionary](/character-dictionary) for in-overlay name lookup.

-[AniList](https://anilist.co) is a free website for tracking which anime you have watched. An **access token** is a private key SubMiner stores so it can update your list on your behalf — you approve it once during setup, and you never paste a password into SubMiner.
+[AniList](https://anilist.co) is a free website for tracking which anime you have watched. An **access token** is a private key SubMiner stores so it can update your list on your behalf - you approve it once during setup, and you never paste a password into SubMiner.

 ## Setup

@@ -38,7 +38,7 @@ SubMiner monitors playback and triggers an AniList progress update when an episo

 The update flow:

-1. **Title detection** -- SubMiner extracts the anime title, season, and episode number from the media filename. It tries [`guessit`](https://github.com/guessit-io/guessit) first for accurate parsing, then falls back to an internal filename parser if guessit is unavailable.
+1. **Title detection** -- SubMiner extracts the anime title, season, and episode number from the media filename and path. Season folders such as `Season 2` are treated as a strong season signal. SubMiner tries [`guessit`](https://github.com/guessit-io/guessit) first for accurate parsing, then falls back to an internal filename parser if guessit is unavailable.
 2. **AniList search** -- The detected title is searched against the AniList GraphQL API. For season 2 and later files, SubMiner searches the season-specific title first, then falls back to the base title. SubMiner picks the best match by comparing titles (romaji, English, native) and filtering by episode count.
 3. **Progress check** -- SubMiner fetches your current list entry for the matched media. The media must already be in Planning or Watching; otherwise SubMiner shows an MPV message explaining that the update is not possible. If your recorded progress already meets or exceeds the detected episode, the update is skipped.
 4. **Mutation** -- A `SaveMediaListEntry` mutation sets the new progress and marks the entry as `CURRENT`.
@@ -0,0 +1,51 @@
+# AniSkip Integration
+
+SubMiner integrates with [AniSkip](https://aniskip.com) to automatically detect anime intro intervals and let you skip them with a single key press.
+
+Intro detection runs in the SubMiner app over the mpv IPC socket. It is available whenever the overlay is connected to mpv - not just at launch - and covers every local file loaded during an mpv session, including playlist advances.
+
+## Setup
+
+AniSkip is opt-in. Enable it in your config:
+
+```jsonc
+{
+  "mpv": {
+    "aniskipEnabled": true,
+    "aniskipButtonKey": "TAB",
+  },
+}
+```
+
+Both settings hot-reload: changing them in your config takes effect immediately without restarting playback or mpv.
+
+For best title and episode detection, install [`guessit`](https://github.com/guessit-io/guessit):
+
+```bash
+python3 -m pip install --user guessit
+```
+
+Without `guessit`, SubMiner falls back to an internal filename parser which handles most common naming conventions but may miss unusual formats.
+
+## How It Works
+
+On each local file load:
+
+1. SubMiner infers the anime title, season, and episode number from the filename and path (using `guessit` if available, otherwise the built-in parser). Remote URLs are skipped entirely.
+2. The title is matched against MyAnimeList to resolve a MAL id.
+3. SubMiner queries the AniSkip API for an OP skip interval for that MAL id and episode.
+4. If an interval is found, SubMiner adds `AniSkip Intro Start` and `AniSkip Intro End` chapter markers to the current file and binds the skip key (`mpv.aniskipButtonKey`, default `TAB`).
+5. At the start of the intro, an OSD prompt appears for 3 seconds: `You can skip by pressing TAB` (reflects your configured key). Pressing the key at any point during the intro seeks to the intro end.
+
+Results are cached per file for the app session. Reload detection is also handled: if mpv reloads the same file, SubMiner re-applies the chapter markers without a new API lookup.
+
+## Triggering from mpv
+
+You can trigger AniSkip actions from mpv script-messages:
+
+| Command | Effect |
+| ------- | ------ |
+| `script-message subminer-skip-intro` | Skip to the intro end immediately (same as pressing the key) |
+| `script-message subminer-aniskip-refresh` | Force a fresh lookup for the current file, discarding any cached result |
+
+These are handled by the SubMiner app over the IPC socket.
@@ -4,11 +4,12 @@ SubMiner uses the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) add-
 This project is built primarily for [Kiku](https://kiku.youyoumu.my.id/) and [Lapis](https://github.com/donkuri/lapis) note types, including sentence-card and field-grouping behavior.

 ::: tip New to these terms?
+
 - **Anki** is the flashcard app where your study cards live.
 - **AnkiConnect** is a free add-on that lets other programs (like SubMiner) talk to Anki over a local connection. SubMiner needs it installed to add or edit cards.
- A **note type** (also called a "model") is the template that defines what a card looks like — for example the Kiku or Lapis templates many Japanese learners use.
+- A **note type** (also called a "model") is the template that defines what a card looks like - for example the Kiku or Lapis templates many Japanese learners use.
 - A **field** is one labeled slot in that template, such as `Sentence`, `Expression`, or `Picture`. SubMiner fills these fields when it mines a card.
-:::
+  :::

 ## Prerequisites

@@ -22,9 +23,9 @@ AnkiConnect listens on `http://127.0.0.1:8765` by default. If you changed the po

 When you add a word via Yomitan, SubMiner detects the new card and fills in the sentence, audio, image, and translation fields automatically. Two detection methods are available:

-**Proxy mode** (default) — SubMiner runs a local *proxy*: a small middleman server that sits between Yomitan and Anki. Yomitan sends new cards to SubMiner, SubMiner enriches them, then passes them along to Anki. This makes enrichment instant.
+**Proxy mode** (default) - SubMiner runs a local _proxy_: a small middleman server that sits between Yomitan and Anki. Yomitan sends new cards to SubMiner, SubMiner enriches them, then passes them along to Anki. This makes enrichment instant.

-**Polling mode** (fallback, when the proxy is disabled) — SubMiner asks AnkiConnect every few seconds whether any new cards were added, then enriches them. Simpler setup, but with a short delay (~3 seconds).
+**Polling mode** (fallback, when the proxy is disabled) - SubMiner asks AnkiConnect every few seconds whether any new cards were added, then enriches them. Simpler setup, but with a short delay (~3 seconds).

 Use proxy mode if you want immediate enrichment. Use polling mode if your Yomitan instance is external (browser-based) or you prefer minimal configuration.

@@ -36,7 +37,7 @@ In both modes, the enrichment workflow is the same:
 4. Fills the translation field from the secondary subtitle or AI.
 5. Writes metadata to the miscInfo field.

-Polling mode uses the query `"deck:<ankiConnect.deck>" added:1` to find recently added cards. If no deck is configured, it searches all decks. In Settings, the AnkiConnect deck dropdown auto-fills from Yomitan's current mining deck when available, then falls back to the decks reported by AnkiConnect.
+Polling mode uses the query `"deck:<ankiConnect.deck>" added:1` to find recently added cards. If no deck is configured, it uses Yomitan's current mining deck when available; otherwise it searches all decks. In Settings, the AnkiConnect deck dropdown auto-fills and persists Yomitan's current mining deck when available, then falls back to the decks reported by AnkiConnect.
 Known-word sync scope is controlled by `ankiConnect.knownWords.decks`.

 ### Proxy Mode Setup (Yomitan / Texthooker)
@@ -160,13 +161,14 @@ Audio is extracted from the video file using the subtitle's start and end timest
 "ankiConnect": {
  "media": {
    "generateAudio": true,
+    "normalizeAudio": true,      // normalize generated clip loudness
    "audioPadding": 0,           // optional seconds before and after subtitle timing
    "maxMediaDuration": 30       // cap total duration in seconds
  }
 }
 ```

-Output format: MP3 at 44100 Hz. If the video has multiple audio streams, SubMiner uses the active stream.
+Output format: MP3 at 44100 Hz. If the video has multiple audio streams, SubMiner uses the active stream. Generated sentence audio is loudness-normalized by default during extraction; set `normalizeAudio` to `false` to keep raw source loudness.

 The audio is uploaded to Anki's media folder and inserted as `[sound:audio_<timestamp>.mp3]`.

@@ -215,11 +217,15 @@ Animated AVIF requires an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`)
    "overwriteImage": true,         // replace existing image, or append
    "mediaInsertMode": "append",    // "append" or "prepend" to field content
    "autoUpdateNewCards": true,     // auto-update when new card detected
-    "notificationType": "osd"       // "osd", "system", "both", or "none"
+    "notificationType": "overlay"   // "overlay", "system", "both", or "none"
  }
 }
 ```

+`both` now means overlay + system notification. `osd` and `osd-system` are legacy config-file-only values; set `notificationType` to `"osd-system"` in `config.jsonc` if you previously used `both` and want to keep mpv OSD + system notifications. The Settings window shows `osd` or `osd-system` when already configured, but only offers `overlay`, `system`, `both`, and `none` as normal choices.
+
+When media is available, mined-card overlay and system notifications include the same current-frame thumbnail.
+
 `overwriteAudio` applies to automatic card updates and duplicate-card enrichment. Manual clipboard subtitle updates (`Ctrl/Cmd+C`, then `Ctrl/Cmd+V`) always replace generated sentence audio, while leaving the word audio field unchanged.

 ## AI Translation
@@ -342,6 +348,7 @@ When you mine the same word multiple times, SubMiner can merge the cards instead
      "imageType": "static",
      "imageFormat": "jpg",
      "imageQuality": 92,
+      "normalizeAudio": true,
      "audioPadding": 0,
      "maxMediaDuration": 30,
    },
@@ -350,7 +357,7 @@ When you mine the same word multiple times, SubMiner can merge the cards instead
      "overwriteImage": true,
      "mediaInsertMode": "append",
      "autoUpdateNewCards": true,
-      "notificationType": "osd",
+      "notificationType": "overlay",
    },
    "ai": {
      "enabled": false,
@@ -30,11 +30,11 @@ launcher/                 # Standalone CLI launcher wrapper and mpv helpers
 plugin/
  subminer/               # Modular mpv plugin (init · main · bootstrap · lifecycle · process
                          #   state · messages · hover · ui · options · environment · log
-                          #   binary · aniskip · aniskip_match)
+                          #   binary)
 src/
  ai/                      # AI translation provider utilities (client, config)
  main-entry.ts           # Background-mode bootstrap wrapper before loading main.js
-  main.ts                  # Entry point — delegates to runtime composers/domain modules
+  main.ts                  # Entry point - delegates to runtime composers/domain modules
  preload.ts               # Electron preload bridge
  types.ts                 # Shared type definitions
  main/                    # Main-process composition/runtime adapters
@@ -130,7 +130,7 @@ src/renderer/
 ### Launcher + Plugin Runtimes

 - `launcher/main.ts` dispatches commands through `launcher/commands/*` and shared config readers in `launcher/config/*`. It handles mpv startup, app passthrough, Jellyfin helper commands, and playback handoff.
- `plugin/subminer/init.lua` runs inside mpv and loads modular Lua files: `main.lua` (orchestration), `bootstrap.lua` (startup), `lifecycle.lua` (connect/disconnect), `process.lua` (process management), `state.lua` (shared state), `messages.lua` (IPC), `hover.lua` (hover-token highlight rendering), `ui.lua` (OSD rendering), `options.lua` (config), `environment.lua` (detection), `log.lua` (logging), `binary.lua` (path resolution), `aniskip.lua` + `aniskip_match.lua` (intro-skip UX).
+- `plugin/subminer/init.lua` runs inside mpv and loads modular Lua files: `main.lua` (orchestration), `bootstrap.lua` (startup), `lifecycle.lua` (connect/disconnect), `process.lua` (process management), `state.lua` (shared state), `messages.lua` (IPC), `hover.lua` (hover-token highlight rendering), `ui.lua` (OSD rendering), `options.lua` (config), `environment.lua` (detection), `log.lua` (logging), `binary.lua` (path resolution). AniSkip intro detection lives in the SubMiner app (`src/main/runtime/aniskip-runtime.ts`), which drives mpv chapters and the skip key over the IPC socket.

 ## Flow Diagram

@@ -226,17 +226,17 @@ Most runtime code follows a dependency-injection pattern:

 The composition root (`src/main.ts`) delegates to focused modules in `src/main/` and `src/main/runtime/composers/`:

- `startup.ts` — argv/env processing and bootstrap flow
- `app-lifecycle.ts` — Electron lifecycle event registration
- `startup-lifecycle.ts` — app-ready initialization sequence
- `state.ts` — centralized application runtime state container
- `ipc-runtime.ts` — IPC channel registration and handler wiring
- `cli-runtime.ts` — CLI command parsing and dispatch
- `overlay-runtime.ts` — overlay window selection and modal state management
- `subsync-runtime.ts` — subsync command orchestration
- `runtime/composers/anilist-tracking-composer.ts` — AniList media tracking/probe/retry wiring
- `runtime/composers/jellyfin-runtime-composer.ts` — Jellyfin config/client/playback/command/setup composition wiring
- `runtime/composers/mpv-runtime-composer.ts` — MPV event/factory/tokenizer/warmup wiring
+- `startup.ts` - argv/env processing and bootstrap flow
+- `app-lifecycle.ts` - Electron lifecycle event registration
+- `startup-lifecycle.ts` - app-ready initialization sequence
+- `state.ts` - centralized application runtime state container
+- `ipc-runtime.ts` - IPC channel registration and handler wiring
+- `cli-runtime.ts` - CLI command parsing and dispatch
+- `overlay-runtime.ts` - overlay window selection and modal state management
+- `subsync-runtime.ts` - subsync command orchestration
+- `runtime/composers/anilist-tracking-composer.ts` - AniList media tracking/probe/retry wiring
+- `runtime/composers/jellyfin-runtime-composer.ts` - Jellyfin config/client/playback/command/setup composition wiring
+- `runtime/composers/mpv-runtime-composer.ts` - MPV event/factory/tokenizer/warmup wiring

 Composer modules share contract conventions via `src/main/runtime/composers/contracts.ts`:

@@ -271,9 +271,9 @@ For domains migrated to reducer-style transitions (for example AniList token/que

 ## Playback Startup Flow

-Before the app boots, something has to launch mpv, inject the plugin, and bring the overlay up. SubMiner-managed launches own this step — the `subminer` launcher, the app's own playback, and the packaged Windows shortcut all follow the same path. The launcher reads `config.jsonc`, spawns mpv with the IPC socket and the bundled plugin, and passes runtime settings as `--script-opts`. The plugin never reads a config file: the shipped `subminer.conf` is intentionally empty so command-line opts always win.
+Before the app boots, something has to launch mpv, inject the plugin, and bring the overlay up. SubMiner-managed launches own this step - the `subminer` launcher, the app's own playback, and the packaged Windows shortcut all follow the same path. The launcher reads `config.jsonc`, spawns mpv with the IPC socket and the bundled plugin, and passes runtime settings as `--script-opts`. The plugin never reads a config file: the shipped `subminer.conf` is intentionally empty so command-line opts always win.

-Once mpv is up, exactly one of two triggers brings up the overlay. On a first launch the plugin's `file-loaded` hook self-starts the app once the socket is ready (because the launcher injected `auto_start=yes`). When the app is already running — or for explicit `--start-overlay` and YouTube flows — the launcher instead attaches over the control socket and suppresses the plugin's auto-start, so the two never fire together. Both converge on the same app bring-up, which then runs the Program Lifecycle below.
+Once mpv is up, exactly one of two triggers brings up the overlay. On a first launch the plugin's `file-loaded` hook self-starts the app once the socket is ready (because the launcher injected `auto_start=yes`). When the app is already running - or for explicit `--start-overlay` and YouTube flows - the launcher instead attaches over the control socket and suppresses the plugin's auto-start, so the two never fire together. Both converge on the same app bring-up, which then runs the Program Lifecycle below.

 ```mermaid
 flowchart TB
@@ -1,12 +1,131 @@
 # Changelog

-## v0.15.1 (2026-05-31)
+## v0.17.2 (2026-06-28)
+
+**Fixed**
+- YouTube Background Cache: Fixed Windows YouTube background media cache startup for YouTube URLs opened directly in mpv, including resolved stream URLs when mpv still exposes the original YouTube playlist entry, so queued Anki media updates can append audio and images after the cache finishes.
+- YouTube Subtitle Picker: Manual subtitle picker requests now show an immediate configured notification while SubMiner probes tracks and opens the modal. Subtitle download progress is replaced with a transient success notification after tracks load.
+
+## v0.17.1 (2026-06-27)
+
+**Added**
+- YouTube Media Cache Mode: Adds `youtube.mediaCache.mode` with `direct` and `background` options. Background mode uses a yt-dlp cache download when direct stream extraction is unreliable — creates a text-only card immediately, queues media updates for mined notes, and fills audio/image fields once the download finishes. Progress is announced via overlay/OSD notifications. Downloads are capped at 720p by default (`youtube.mediaCache.maxHeight`). Switching back to direct mode cancels any in-flight background download.
+
+**Fixed**
+- Log Export: Fixed log filenames to use the local date so exports around UTC midnight include the current day's logs rather than stale prior-day files. Expanded export redaction to mask IPs, emails, auth and cookie headers, yt-dlp cookie arguments, URL credentials, token/key/password fields, and signed YouTube media URL parameters.
+- YouTube Card Media: Improved media generation reliability by sending safer ffmpeg options for resolved streams and skipping stale stream maps (including cached YouTube files). Hardened background cache downloads with IPv4 and extractor retry flags; failed downloads now notify the user and clear queued media updates instead of leaving them silently pending. Stale background cache files are cleaned on startup and before each new download.
+
+## v0.17.0 (2026-06-15)
+
+**Changed**
+
+- **Subtitle Delay Keybindings**: Updated default overlay subtitle delay and step bindings to match mpv conventions: `z`, `Z`, and `x` adjust `sub-delay`; `Ctrl+Shift+Left/Right` run native `sub-step` with OSD feedback. The previous SubMiner-only adjacent-cue delay action has been removed.
+- **Update Notifications**: New installs now default update notifications to overlay-only instead of overlay + system notifications.
+
+**Fixed**
+
+- **Anki – Highlight Word**: Fixed bolding of the mined word in Kiku sentence and sentence-furigana fields when the source Yomitan sentence did not already contain bold markup.
+- **Anki – Lapis/Kiku Word Cards**: Fixed word-and-sentence marker missing from Lapis/Kiku word cards enriched through SubMiner, which could hide sentence context on the card front.
+- **Anki – Windows Media Generation**: Fixed known-word cache refreshes when no deck is configured, and fixed audio/image generation after background launches by recreating missing FFmpeg temp directories before clipping.
+- **Character Dictionary – Windows**: Fixed the Windows "SubMiner mpv" shortcut so character dictionary auto-sync can fall back to mpv's current video path when app media state is not yet ready.
+- **Notifications**: Restored the SubMiner app icon on system notifications that do not supply a custom notification image.
+- **Overlay – macOS Yomitan Popup**: Fixed Yomitan popup focus after card mining or popup reload; fixed popups staying open when clicking transparent overlay space — click-away now closes the popup and returns click passthrough to mpv without a hide/reappear cycle.
+- **Overlay – Linux Auto-Pause Startup**: Fixed the visible overlay on Linux auto-paused startup to stay interactive during the initial measurement gap; startup subtitle cache misses now paint raw text before tokenization finishes, and temporarily empty `sub-text` refreshes are resolved before warm readiness resumes playback.
+- **Overlay – Playlist Advance**: Fixed the visible overlay being dismissed when mpv advances to the next playlist item, including when the next episode loads after the warm transition delay.
+- **Overlay – Windows Subtitle Bar**: Fixed shaky hover and click interaction on the Windows subtitle bar when a video attaches to an already-running background SubMiner instance.
+- **Stats – AniList Linking**: Fixed manual AniList linking from the stats anime page so auto-searches strip the generated "Season N" suffix and query only the anime title.
+- **Updates – Linux Support Assets**: Fixed Linux updates to correctly install and refresh the launcher runtime plugin copy and rofi theme alongside AppImage and launcher updates; unrelated SubMiner data directories are now left untouched and plugin copies are staged before replacing the live runtime. Fixed first-launch playback on fresh installs by auto-installing missing managed support assets from the bundled app before mpv starts.
+
+**Docs**
+
+- **Linux Update Flows**: Documented that Linux update flows manage the launcher runtime plugin copy and rofi theme from `subminer-assets.tar.gz`, and that normal launcher playback auto-installs those managed support assets on a fresh install if either is missing.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+
+- **Runtime Modules**: Split main-process runtime wiring into focused modules without changing user-facing behavior; hardened helpers against stale background stats daemon PIDs, stalled subtitle extraction, and dropped async errors.
+- **Release CI**: Fixed GitHub release notes to preserve the `What's Changed` and `New Contributors` attribution sections when CI regenerates from the committed changelog; scoped prerelease note reuse to the same base version so a new beta line starts from current fragments.
+
+</details>
+
+## Previous Versions
+
+<details>
+<summary>v0.16.x</summary>
+
+<h2>v0.16.0 (2026-06-10)</h2>
+
+**Breaking Changes**
+
+- **Notification Mode `both`**: `notificationType: "both"` now routes to overlay + system notifications. Users who previously used `"both"` for mpv OSD + system notifications should set `notificationType` to `"osd-system"` in `config.jsonc`. The `osd` and `osd-system` values remain valid as config-file entries but no longer appear in Settings.
+
+**Added**
+
+- **Overlay Notifications**: New overlay notification stack (Catppuccin Macchiato theme) with configurable screen position (`notifications.overlayPosition`: top-left, top-center, top-right), 3-second transient dismissals, and persistent cards for long-running jobs like character dictionary sync.
+- **Notification History Panel**: `Ctrl/Cmd+N` (configurable via `shortcuts.toggleNotificationHistory`) opens a session log of all notifications. Works whether the overlay or mpv has focus; slides in from the notification edge; entries can be individually removed or cleared.
+- **Mined-Card Notification Actions**: Mined-card overlay notifications show generated card thumbnails and include an Open in Anki button in both live cards and history entries.
+- **Update Notification Action**: Update-available overlay notifications include an Update button to start the app update flow directly from the notification.
+- **Stats Search**: New Search tab in Stats for realtime subtitle sentence search with media context, headword matching, and mining actions for source-backed sentence cards or exact-match word/audio cards.
+
+**Changed**
+
+- **AniSkip**: Moved intro detection from the mpv plugin to the SubMiner app. Lookups now cover every file loaded during a session including playlist advances, and `mpv.aniskipEnabled`/`mpv.aniskipButtonKey` hot-reload without restarting playback. The bundled plugin no longer makes network calls. Note: AniSkip now requires the SubMiner app to be connected; plugin-only mpv sessions will not fetch skip windows.
+- **Stats Library**: Entries are now split by detected season (season folder first, filename parsing as fallback). Existing combined-series rows are automatically migrated to per-season entries on startup. Cover art and anime details refresh immediately after a manual AniList entry change.
+- **Stats Vocabulary**: Remembers Hide Known/Hide Kana filters across sessions, applies Hide Kana filtering cross-title, collapses duplicate token variants in exclusions, and matches Related Seen Words by shared readings or kanji.
+- **Stats Trends**: Reorganized into Activity, Cumulative Totals, Efficiency, Patterns, and Library sections; disambiguated per-period vs. cumulative charts; added Words/Min and Cards/Hour efficiency charts.
+- **Stats Mining**: Sentence cards are created before slow media generation finishes; stored/requested secondary subtitles are preserved before falling back to sidecar or alass-retimed English subtitles; empty `ankiConnect.deck` falls back to Yomitan's mining deck; partial media failures are surfaced.
+- **Stats Browsing**: Remembers library card size; retries stored cover art without extra AniList lookups; preserves PNG/WebP MIME types; honors custom AnkiConnect URLs for Browse; shows progress during session deletes.
+- **Startup Notifications**: Tokenization, subtitle annotation, and character dictionary status now route through queued overlay notifications in `overlay`/`both` mode instead of falling back to mpv OSD while the overlay loads.
+- **Notification Deduplication**: Cycling subtitle modes updates the active overlay card in place rather than stacking duplicates; repeated progress updates (e.g. subsync) tick in place without flickering.
+- **Update Notification Default**: New installs default `notificationType` to `both` so update alerts appear in both overlay and system notifications.
+
+**Fixed**
+
+- **AniList Completion**: Entries are now marked completed when a post-watch update reaches the final known episode of the season.
+- **AniSkip Markers**: Fixed intro markers disappearing after same-media mpv reloads; fixed metadata detection for intros that start at 0 seconds and common release-group filenames.
+- **Jellyfin Session**: Remote session now restarts after setup login so the websocket reconnects with fresh credentials, and stops cleanly on logout.
+- **Sentence Card Audio**: Mining a sentence card no longer fills the expression audio field; generated audio goes only to the configured sentence audio field.
+- **Stats Mining Fields**: Sentence clips update `SentenceAudio` correctly; word audio uses configured Yomitan sources; English subtitle text is not written to word cards; secondary subtitle auto-selection prefers regular English tracks over Signs/Songs tracks.
+- **Overlay Hover Readiness**: Subtitle bars are hoverable and clickable from the first subtitle line on visible overlay startup or resume, without waiting for the next subtitle event.
+- **Startup Autoplay**: Playback is released after tokenization and overlay content are ready even when playback begins before the first subtitle line appears.
+- **Overlay Startup Feedback**: Restored mpv OSD loading spinner that starts on connect, media open, or overlay request, and clears once the overlay is content-ready and visible.
+- **Linux Overlay Input**: Notification close and action buttons remain clickable above subtitle bars on Linux.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+- **Build**: `make deps` now initializes git submodules before installing dependencies on a fresh source checkout.
+- **Release Tooling**: Release notes now credit contributors and first-time authors resolved from changelog fragments via git and the GitHub API.
+- **Changelog Guidance**: PR fragment guidance updated to preserve separate-outcome fragments while directing contributors to consolidate same-PR follow-up notes before adding churn.
+
+</details>
+
+</details>
+
+<details>
+<summary>v0.15.x</summary>
+
+<h2>v0.15.2 (2026-06-02)</h2>
+
+**Changed**
+- Yomitan: Updated the bundled Yomitan build to the latest vendored revision.
+
+**Fixed**
+- Anki - Animated AVIF: Clip timing no longer starts or ends early; word-audio lead-in and clip duration are now aligned to frame boundaries.
+- Overlay (Hyprland): Fixed fullscreen overlay alignment - modal, stats, and sidebar content no longer shift below the mpv window.
+- Overlay (macOS): Subtitle bars are now interactive immediately after autoplay starts with "wait for overlay to be ready" enabled, without requiring a manual click.
+- Overlay (macOS): Fixed overlay, subtitles, and subtitle sidebar staying hidden after a modal closes until the user clicked the mpv window; focus is now restored to mpv when the last modal closes, so playback shortcuts and the overlay reappear correctly - including in native fullscreen.
+
+<h2>v0.15.1 (2026-05-31)</h2>

 **Fixed**

 - **Linux Overlay Stacking**: Fixed the overlay intermittently dropping behind mpv on KDE Plasma and other non-Hyprland/Sway Wayland sessions; restored subtitle hover, pause-on-hover, and Yomitan lookups on X11/XWayland; the overlay now correctly layers above/below mpv based on fullscreen state, yields to foreground windows (Settings, Yomitan, AniList, etc.), and avoids startup flashes and fullscreen transition glitches.
 - **Linux Overlay (Hyprland Lua)**: Fixed overlay placement on Hyprland 0.55+ when using a Lua-based config.
- **Manual Overlay Startup**: Fixed manual visible-overlay startup from mpv — now correctly attaches to playback, keeps the window bounds synced with mpv, and primes current subtitles before showing.
+- **Manual Overlay Startup**: Fixed manual visible-overlay startup from mpv - now correctly attaches to playback, keeps the window bounds synced with mpv, and primes current subtitles before showing.
 - **Playlist Transitions**: Reused the warm overlay when mpv advances to the next playlist item, avoiding a redundant tokenization pause and preserving visible subtitles across tracks.
 - **macOS Overlay**: Fixed the visible subtitle overlay staying click-through after pause-until-ready releases playback; restored mpv focus after closing modal windows so subtitles and keybinds resume without clicking the player.
 - **Mouse Keybindings**: Fixed keybinding capture and runtime handling for mouse buttons, including side buttons like `MBTN_BACK` and `MBTN_FORWARD`.
@@ -16,7 +135,7 @@

 - **Troubleshooting**: Updated Hyprland overlay docs with current Lua (`hl.window_rule`) and legacy config syntax; added troubleshooting for KDE/Wayland and other non-Hyprland/Sway Wayland sessions; added a Character Dictionary troubleshooting section; added a "See Also" index linking each feature's troubleshooting page.

-## v0.15.0 (2026-05-29)
+<h2>v0.15.0 (2026-05-29)</h2>

 **Breaking Changes**

@@ -25,7 +144,7 @@
  - Subsync now always opens the manual subtitle picker regardless of any previously set default mode
 - **N+1 Highlighting:**
  - N+1 highlighting now has its own dedicated `ankiConnect.nPlusOne.enabled` option, separate from known-word highlighting
-  - It is no longer enabled automatically when known-word highlighting is on — enable it explicitly to keep N+1 annotations
+  - It is no longer enabled automatically when known-word highlighting is on - enable it explicitly to keep N+1 annotations

 **Added**

@@ -168,7 +287,7 @@

 </details>

-## Previous Versions
+</details>

 <details>
 <summary>v0.14.x</summary>
@@ -177,7 +296,7 @@

 **Added**

- **Character Dictionary:** Added AniList-based character dictionary selection for resolving title mismatches — open it in-app with the new `Ctrl+Alt+A` shortcut or from the CLI with `subminer dictionary --candidates` / `--select`. Series-scoped overrides replace stale entries in the merged dictionary.
+- **Character Dictionary:** Added AniList-based character dictionary selection for resolving title mismatches - open it in-app with the new `Ctrl+Alt+A` shortcut or from the CLI with `subminer dictionary --candidates` / `--select`. Series-scoped overrides replace stale entries in the merged dictionary.
 - **Primary Subtitle Bar:** Added a `V` shortcut and mpv plugin binding to toggle the primary subtitle bar without affecting mpv's native subtitle visibility.
 - **Texthooker:** Added `subminer texthooker -o` and a tray menu item to open the local texthooker page in the default browser.

@@ -231,7 +350,7 @@
 **Internal**

 - Replaced the changelog renderer with an AI polish pass that merges related fragments and writes user-facing release notes. `CHANGELOG.md` keeps internal items in a collapsed `<details>` block; GitHub release notes omit them entirely.
- Release CI no longer auto-builds pending `changes/*.md` fragments on tag. Tagging now fails fast if fragments remain — run `bun run changelog:build` (requires the `claude` CLI) and commit before tagging.
+- Release CI no longer auto-builds pending `changes/*.md` fragments on tag. Tagging now fails fast if fragments remain - run `bun run changelog:build` (requires the `claude` CLI) and commit before tagging.

 </details>

@@ -255,8 +374,8 @@
 - Stats: Episode detail hides card events whose Anki notes have been deleted, instead of showing phantom mining activity.
 - Stats: Trend and watch-time charts share a unified theme with horizontal gridlines and larger ticks for legibility.
 - Stats: Overview, Library, Trends, Sessions, and Vocabulary now use generic "title" wording so YouTube videos and anime live comfortably side by side in the dashboard.
- Stats: Session timeline no longer plots seek-forward/seek-backward markers — they were too noisy on sessions with lots of rewinds.
- Stats: Replaced the "Library — Per Day" section on the Stats → Trends page with a "Library — Summary" section. The new section shows a top-10 watch-time leaderboard chart and a sortable per-title table (watch time, videos, sessions, cards, words, lookups, lookups/100w, date range), all scoped to the current date range selector.
+- Stats: Session timeline no longer plots seek-forward/seek-backward markers - they were too noisy on sessions with lots of rewinds.
+- Stats: Replaced the "Library - Per Day" section on the Stats → Trends page with a "Library - Summary" section. The new section shows a top-10 watch-time leaderboard chart and a sortable per-title table (watch time, videos, sessions, cards, words, lookups, lookups/100w, date range), all scoped to the current date range selector.

 **Fixed**

@@ -1,6 +1,6 @@
 # Character Dictionary

-SubMiner can build a Yomitan-compatible character dictionary from [AniList](https://anilist.co) metadata so that character names in subtitles are recognized, highlighted, and enrichable with context — portraits, roles, voice actors, and biographical detail — without leaving the overlay. (AniList is an online anime/manga database; SubMiner pulls each show's character list from it.)
+SubMiner can build a Yomitan-compatible character dictionary from [AniList](https://anilist.co) metadata so that character names in subtitles are recognized, highlighted, and enrichable with context - portraits, roles, voice actors, and biographical detail - without leaving the overlay. (AniList is an online anime/manga database; SubMiner pulls each show's character list from it.)

 This is helpful because proper names rarely appear in normal dictionaries, so character names would otherwise be flagged as "unknown" words and clutter your mining. Recognizing them keeps your N+1 highlighting focused on real vocabulary.

@@ -10,25 +10,25 @@ The dictionary is generated per-media, merged across your recently-watched title

 The feature has three stages: **snapshot**, **merge**, and **match**.

-1. **Snapshot** — When you start watching a new title, SubMiner queries the AniList GraphQL API for the media's character list. Each character's names, reading, role, description, birthday, voice actors, and portrait are fetched and saved as a local JSON snapshot in `character-dictionaries/snapshots/anilist-{mediaId}.json`. Images are downloaded and base64-encoded into the snapshot.
+1. **Snapshot** - When you start watching a new title, SubMiner queries the AniList GraphQL API for the media's character list. Each character's names, reading, role, description, birthday, voice actors, and portrait are fetched and saved as a local JSON snapshot in `character-dictionaries/snapshots/anilist-{mediaId}.json`. Images are downloaded and base64-encoded into the snapshot.

-2. **Merge** — SubMiner maintains a most-recently-used list of media IDs (default: 3). Snapshots from those titles are merged into a single Yomitan ZIP — `character-dictionaries/merged.zip` — which is always named "SubMiner Character Dictionary" so Yomitan treats it as a single stable dictionary across rebuilds.
+2. **Merge** - SubMiner maintains a most-recently-used list of media IDs (default: 3). Snapshots from those titles are merged into a single Yomitan ZIP - `character-dictionaries/merged.zip` - which is always named "SubMiner Character Dictionary" so Yomitan treats it as a single stable dictionary across rebuilds.

-3. **Match** — During subtitle rendering, Yomitan scans subtitle text against all loaded dictionaries including the character dictionary. SubMiner only accepts character entries for the current AniList media when that media ID is known, then flags matching tokens with `isNameMatch` and highlights them in the overlay with a distinct color.
+3. **Match** - During subtitle rendering, Yomitan scans subtitle text against all loaded dictionaries including the character dictionary. SubMiner only accepts character entries for the current AniList media when that media ID is known, then flags matching tokens with `isNameMatch` and highlights them in the overlay with a distinct color.

 ## Enabling the Feature

 Character dictionary sync is disabled by default. To turn it on:

 1. Enable **Name Match** in Settings → Subtitle Style, or set `subtitleStyle.nameMatchEnabled: true` in your config.
-2. Start watching — SubMiner queries AniList's public GraphQL API (no authentication required) and imports the merged dictionary into Yomitan automatically.
+2. Start watching - SubMiner queries AniList's public GraphQL API (no authentication required) and imports the merged dictionary into Yomitan automatically.
 3. Optionally enable **Name Match Images** (Settings → Subtitle Style) to show inline circular character portraits next to matched names in subtitles.

 ```jsonc
 {
  "subtitleStyle": {
    "nameMatchEnabled": true,
-    "nameMatchImagesEnabled": true, // optional — inline portraits
+    "nameMatchImagesEnabled": true, // optional - inline portraits
  },
 }
 ```
@@ -38,7 +38,7 @@ The first sync for a media title takes a few seconds while character data and po
 :::

 ::: info
-AniList character data is fetched via public GraphQL queries — no account or access token is needed. AniList authentication is only required for the separate [watch-progress sync](/anilist-integration) feature.
+AniList character data is fetched via public GraphQL queries - no account or access token is needed. AniList authentication is only required for the separate [watch-progress sync](/anilist-integration) feature.
 :::

 ::: warning
@@ -56,11 +56,13 @@ A single character produces many searchable terms so that names are recognized r
 - Family name alone: 須々木
 - Given name alone: 心一

+Unspaced native names (AniList often stores 渡辺真奈美 without a separator) are split into family/given parts with MeCab when it is available: person-name POS tags (姓/名) decide the boundary, validated against AniList's romanized first/last name readings. Without MeCab, a length heuristic based on the romanized readings guesses the boundary — and because that guess can be ambiguous (東紫乃 could be 東+紫乃 or 東紫+乃), terms are generated for the top two candidate boundaries so the real surname still matches. Snapshots built without MeCab are regenerated automatically once MeCab becomes available, upgrading them to the exact splits.
+
 **Middle-dot removal** (common in katakana foreign names):

 - ア・リ・ス → アリス (combined), plus individual segments

-**Honorific suffixes** — each base name is expanded with 15 common suffixes:
+**Honorific suffixes** - each base name is expanded with 15 common suffixes:

 | Honorific | Reading    |
 | --------- | ---------- |
@@ -80,16 +82,16 @@ A single character produces many searchable terms so that names are recognized r
 | 社長      | しゃちょう |
 | 部長      | ぶちょう   |

-**Romanized names** — names stored in romaji on AniList are converted to kana aliases so they can match against Japanese subtitle text.
+**Romanized names** - names stored in romaji on AniList are converted to kana aliases so they can match against Japanese subtitle text.

-This means a character like "太郎" generates entries for 太郎, 太郎さん, 太郎先生, 太郎君, 太郎ちゃん, and so on — all with correct readings.
+This means a character like "太郎" generates entries for 太郎, 太郎さん, 太郎先生, 太郎君, 太郎ちゃん, and so on - all with correct readings.

 ## Name Matching

 Name matching runs inside Yomitan's scanning pipeline during subtitle tokenization.

 1. Yomitan receives subtitle text and scans for dictionary matches.
-2. Entries from "SubMiner Character Dictionary" are checked with exact primary-source matching — the token must match the entry's `originalText` with `isPrimary: true` and `matchType: 'exact'`.
+2. Entries from "SubMiner Character Dictionary" are checked with exact primary-source matching - the token must match the entry's `originalText` with `isPrimary: true` and `matchType: 'exact'`.
 3. When the current AniList media ID is known, entries whose embedded media ID belongs to a different title are ignored for name matching and inline portraits.
 4. Matched tokens are flagged `isNameMatch: true` and forwarded to the renderer.
 5. If `subtitleStyle.nameMatchEnabled` is enabled, the renderer applies the name-match highlight color (default: `#f5bde6`).
@@ -111,7 +113,7 @@ Name matches are visually distinct from [N+1 targeting, frequency highlighting,

 When `subtitleStyle.nameMatchImagesEnabled` is enabled, SubMiner injects a small circular portrait image directly into the subtitle line next to each matched character name.

-Portraits are sourced from the local snapshot — they are embedded at snapshot-generation time and served from the cached ZIP, so no network request happens during playback. Images are downloaded from AniList CDN once per character and stored in `character-dictionaries/img/`.
+Portraits are sourced from the local snapshot - they are embedded at snapshot-generation time and served from the cached ZIP, so no network request happens during playback. Images are downloaded from AniList CDN once per character and stored in `character-dictionaries/img/`.

 If a snapshot was generated before portrait data was available (e.g. during an earlier version or offline sync), SubMiner detects the missing image data on the next media match and automatically refreshes the snapshot so portraits are included in the next merged dictionary build.

@@ -123,20 +125,20 @@ If a snapshot was generated before portrait data was available (e.g. during an e
 The portrait size is controlled by the surrounding subtitle font size and renders as a circle clipped from the character's AniList cover image.

 ::: tip
-Inline portraits help you quickly associate names with faces while building vocabulary — especially useful for shows with large casts where you're still learning who's who.
+Inline portraits help you quickly associate names with faces while building vocabulary - especially useful for shows with large casts where you're still learning who's who.
 :::

 ## Dictionary Entries

 Each character entry in the Yomitan dictionary includes structured content:

- **Name** — the matched Japanese name form
- **Known names** — generated non-honorific Japanese aliases for that character, excluding raw romanized/English aliases from lookup results
- **Role badge** — color-coded by role: main (score 100), supporting (90), side (80), background (70)
- **Portrait** — character image from AniList, embedded in the ZIP
- **Description** — biography text from AniList (collapsible)
- **Character information** — age, birthday, gender, blood type (collapsible)
- **Voiced by** — voice actor name and portrait (collapsible)
+- **Name** - the matched Japanese name form
+- **Known names** - generated non-honorific Japanese aliases for that character, excluding raw romanized/English aliases from lookup results
+- **Role badge** - color-coded by role: main (score 100), supporting (90), side (80), background (70)
+- **Portrait** - character image from AniList, embedded in the ZIP
+- **Description** - biography text from AniList (collapsible)
+- **Character information** - age, birthday, gender, blood type (collapsible)
+- **Voiced by** - voice actor name and portrait (collapsible)

 The three collapsible sections can be configured to start open or closed:

@@ -158,14 +160,16 @@ The three collapsible sections can be configured to start open or closed:

 When `subtitleStyle.nameMatchEnabled` is `true`, SubMiner runs an auto-sync routine whenever the active media changes.

+These phases are emitted through the configured notification surface. Some phases are skipped when unnecessary: `generating` only appears on a cache miss, `building` only appears when the merged ZIP must be rebuilt, and `importing` only appears when Yomitan needs a new dictionary import.
+
 **Phases:**

-1. **checking** — Is there already a cached snapshot for this media ID?
-2. **generating** — No cache hit: fetch characters from AniList GraphQL, download portraits (250ms throttle between image requests), save snapshot JSON.
-3. **syncing** — Add the media ID to the most-recently-used list. Evict old entries beyond `maxLoaded`.
-4. **building** — Merge active snapshots into a single Yomitan ZIP. A SHA-1 revision hash is computed from the media set — if it matches the previously imported revision, the import is skipped.
-5. **importing** — Push the ZIP into Yomitan. Waits for Yomitan mutation readiness (7-second timeout per operation).
-6. **ready** — Dictionary is live. Character names will match on the next subtitle line.
+1. **checking** - Is there already a cached snapshot for this media ID?
+2. **generating** - No cache hit: fetch characters from AniList GraphQL, download portraits (250ms throttle between image requests), save snapshot JSON.
+3. **syncing** - Add the media ID to the most-recently-used list. Evict old entries beyond `maxLoaded`.
+4. **building** - Merge active snapshots into a single Yomitan ZIP. A SHA-1 revision hash is computed from the media set - if it matches the previously imported revision, the import is skipped.
+5. **importing** - Push the ZIP into Yomitan. Waits for Yomitan mutation readiness (7-second timeout per operation).
+6. **ready** - Dictionary is live. Character names will match on the next subtitle line.

 **State tracking** is persisted in `character-dictionaries/auto-sync-state.json`. AniList media matches are cached separately in `character-dictionaries/anilist-resolution-cache.json` so snapshot hits do not need another AniList search.

@@ -274,9 +278,9 @@ merged.zip

 ## Reference Implementation

-SubMiner's character dictionary builder is inspired by the [Japanese Character Name Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary) project — a standalone Rust web service that generates Yomitan character dictionaries from AniList and VNDB data.
+SubMiner's character dictionary builder is inspired by the [Japanese Character Name Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary) project - a standalone Rust web service that generates Yomitan character dictionaries from AniList and VNDB data.

-The reference implementation covers similar ground — name variant generation, honorific expansion, structured Yomitan content, portrait embedding — and additionally supports VNDB as a data source for visual novel characters. Key differences:
+The reference implementation covers similar ground - name variant generation, honorific expansion, structured Yomitan content, portrait embedding - and additionally supports VNDB as a data source for visual novel characters. Key differences:

 |                        | SubMiner                                     | Reference Implementation              |
 | ---------------------- | -------------------------------------------- | ------------------------------------- |
@@ -291,7 +295,7 @@ If you work with visual novels or want a standalone dictionary generator indepen

 ## Troubleshooting

- **Names not highlighting:** Confirm `subtitleStyle.nameMatchEnabled` is `true`. Check that the current media has an AniList entry — SubMiner needs a media ID to fetch characters.
+- **Names not highlighting:** Confirm `subtitleStyle.nameMatchEnabled` is `true`. Check that the current media has an AniList entry - SubMiner needs a media ID to fetch characters.
 - **Inline portraits missing:** Confirm `subtitleStyle.nameMatchImagesEnabled` is `true`. On the next character dictionary sync, SubMiner refreshes current-version snapshots that do not contain usable cached character portrait data. Portraits still require AniList to return an image and the image download to succeed.
 - **Sync seems stuck:** The auto-sync debounces for 800ms after media changes and throttles image downloads at 250ms per image. Large casts (50+ characters) take longer. Check the status bar for the current sync phase.
 - **Wrong characters showing:** Open the in-app character dictionary manager (`Ctrl/Cmd+D`) to remove/reorder loaded titles, then use **Override** to correct the active AniList match. You can also run `--dictionary-candidates`, then save the correct media with `--dictionary-select --dictionary-anilist-id <id>`. SubMiner ignores character entries from other loaded titles for subtitle name matching and inline portraits once the current media ID is known.
@@ -300,6 +304,6 @@ If you work with visual novels or want a standalone dictionary generator indepen

 ## Related

- [Subtitle Annotations](/subtitle-annotations) — how name matches interact with N+1, frequency, and JLPT layers
- [AniList Integration](/anilist-integration) — watch-progress sync and AniList authentication (separate from character dictionary)
- [Configuration Reference](/configuration) — full config options
+- [Subtitle Annotations](/subtitle-annotations) - how name matches interact with N+1, frequency, and JLPT layers
+- [AniList Integration](/anilist-integration) - watch-progress sync and AniList authentication (separate from character dictionary)
+- [Configuration Reference](/configuration) - full config options
@@ -8,7 +8,7 @@ outline: [2, 3]
 import { withBase } from 'vitepress';
 </script>

-SubMiner is configured through a single file (`config.jsonc`). Most settings are also editable from the in-app **Settings** window — you rarely need to edit the file by hand. This page is the full reference: it explains the Settings window, where the config file lives, and documents every option grouped by topic. New to SubMiner? The Quick Start below plus the [Settings window](#settings) cover everything most users need.
+SubMiner is configured through a single file (`config.jsonc`). Most settings are also editable from the in-app **Settings** window - you rarely need to edit the file by hand. This page is the full reference: it explains the Settings window, where the config file lives, and documents every option grouped by topic. New to SubMiner? The Quick Start below plus the [Settings window](#settings) cover everything most users need.

 ## Quick Start

@@ -39,7 +39,7 @@ Then customize as needed using the sections below.

 ## Settings

-SubMiner includes a dedicated **Settings** window accessible from the tray menu, the app `--settings` flag, or launcher commands such as `subminer --settings` and `subminer settings`. It is the primary way to configure SubMiner — all changes are written directly to `config.jsonc`, so manual file editing is not required for most users.
+SubMiner includes a dedicated **Settings** window accessible from the tray menu, the app `--settings` flag, or launcher commands such as `subminer --settings` and `subminer settings`. It is the primary way to configure SubMiner - all changes are written directly to `config.jsonc`, so manual file editing is not required for most users.

 The Settings window groups options by workflow instead of mirroring the raw config-file shape:

@@ -52,7 +52,7 @@ The Settings window groups options by workflow instead of mirroring the raw conf
 - Tracking & App
 - Advanced

-Each field still writes to its current `config.jsonc` path. For example, subtitle hover pause appears under **Behavior** / playback behavior, but saves to `subtitleStyle.autoPauseVideoOnHover`. Anki-aware fields can query AnkiConnect for deck names, note types, and field names. The AnkiConnect deck field also reads Yomitan's current mining deck and auto-fills an empty setting when one is found. Keybinding fields use click-to-learn controls instead of raw text boxes.
+Each field still writes to its current `config.jsonc` path. For example, subtitle hover pause appears under **Behavior** / playback behavior, but saves to `subtitleStyle.autoPauseVideoOnHover`. Anki-aware fields can query AnkiConnect for deck names, note types, and field names. The AnkiConnect deck field also reads Yomitan's current mining deck and persists it into an empty setting when one is found. Stats mining also uses Yomitan's current mining deck when `ankiConnect.deck` is empty. Keybinding fields use click-to-learn controls instead of raw text boxes.

 The Settings window preserves existing JSONC comments, trailing commas, and unrelated keys. Resetting a field removes the explicit config path so the built-in default applies.

@@ -158,6 +158,7 @@ The configuration file includes several main sections:
 - [**MPV Launcher**](#mpv-launcher) - mpv executable path, profile, and window launch mode
 - [**YouTube Playback Settings**](#youtube-playback-settings) - Defaults for YouTube subtitle loading
 - [**Updates**](#updates) - Automatic update checks, notifications, and prerelease testing
+- [**Notifications**](#notifications) - Overlay notification placement

 ## Core Settings

@@ -187,6 +188,9 @@ Control the minimum log level for runtime output:
 | `files.launcher` | boolean                                  | Write launcher command logs (default: `true`)                        |
 | `files.mpv`      | boolean                                  | Write mpv player logs. Enable temporarily for mpv/plugin debugging.  |

+Log filenames use the local calendar date, for example `app-YYYY-MM-DD.log`, `launcher-YYYY-MM-DD.log`, and `mpv-YYYY-MM-DD.log`.
+Log export creates a sanitized copy of those files; it does not rewrite the original log files on disk.
+
 ### Updates

 Configure automatic update checks and update notifications:
@@ -196,18 +200,46 @@ Configure automatic update checks and update notifications:
  "updates": {
    "enabled": true,
    "checkIntervalHours": 24,
-    "notificationType": "system",
+    "notificationType": "overlay",
    "channel": "stable"
  }
 }
 ```

-| Option               | Values                                        | Description                                                                                         |
-| -------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `updates.enabled`    | `true`, `false`                               | Enable automatic background update checks. Manual tray and `subminer -u` checks are always allowed. |
-| `checkIntervalHours` | number                                        | Minimum hours between automatic update checks. Default `24`.                                        |
-| `notificationType`   | `"system"` \| `"osd"` \| `"both"` \| `"none"` | How SubMiner announces available updates. Default `"system"`.                                       |
-| `channel`            | `"stable"` \| `"prerelease"`                  | Release channel used for update checks. Use `"prerelease"` to test beta/RC releases.                |
+| Option               | Values                                            | Description                                                                                         |
+| -------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `updates.enabled`    | `true`, `false`                                   | Enable automatic background update checks. Manual tray and `subminer -u` checks are always allowed. |
+| `checkIntervalHours` | number                                            | Minimum hours between automatic update checks. Default `24`.                                        |
+| `notificationType`   | `"overlay"` \| `"system"` \| `"both"` \| `"none"` | How SubMiner announces available updates. Default `"overlay"`. `"both"` means overlay + system.     |
+| `channel`            | `"stable"` \| `"prerelease"`                      | Release channel used for update checks. Use `"prerelease"` to test beta/RC releases.                |
+
+When `notificationType` is `"overlay"` or `"both"`, update-available overlay notifications include an **Update** button that starts the app update flow.
+
+`osd` and `osd-system` are legacy config-file-only notification values. The Settings window offers `overlay`, `system`, `both`, and `none`; if your config already contains `osd` or `osd-system`, it is shown as the selected value but not offered as a normal choice. If you previously used `both` for mpv OSD + system notifications, set `notificationType` to `"osd-system"` in `config.jsonc` to keep that behavior.
+
+### Notifications
+
+Configure where overlay notification cards appear:
+
+```json
+{
+  "notifications": {
+    "overlayPosition": "top-right"
+  }
+}
+```
+
+| Option            | Values                                   | Description                                                        |
+| ----------------- | ---------------------------------------- | ------------------------------------------------------------------ |
+| `overlayPosition` | `"top-left"` \| `"top"` \| `"top-right"` | Position for in-overlay notification cards. Default `"top-right"`. |
+
+#### Notification history panel
+
+Every overlay notification shown during a session is also recorded in a notification history panel. Press `Ctrl/Cmd+N` (configurable via [`shortcuts.toggleNotificationHistory`](#shortcuts-configuration)) to toggle the panel; the binding works whether the overlay or mpv has focus. The panel slides in from the same edge the notifications use — left when `overlayPosition` is `"top-left"`, and right for `"top-right"` or `"top"` (centered). Character dictionary sync uses one live card but records each distinct phase in history. Each entry can be removed individually, or use **Clear** to empty the history. History is session-only and is not persisted across restarts.
+
+Startup tokenization, subtitle annotation, and character dictionary status follow the configured notification surface. When the surface is `"overlay"` or `"both"`, SubMiner queues those startup notifications until the overlay renderer is ready instead of falling back to mpv OSD. If loading and ready states both finish before the overlay can paint, the loading card is delivered first and then updates to ready shortly after. With `"both"`, character dictionary checking/building/importing/ready status also goes to system notifications; building and importing are only emitted when that work is actually needed. The bundled mpv plugin only shows its startup OSD messages when `ankiConnect.behavior.notificationType` is set to `"osd"` or `"osd-system"` in `config.jsonc`; AniSkip prompts and skip result messages are playback feedback and still route to overlay notifications when configured.
+
+The equivalent direct CLI command is `--playback-feedback <text>` (`playbackFeedback` internally). It sends that one non-empty feedback string through the same route controlled by `ankiConnect.behavior.notificationType`; it does not change the saved config.

 ### Auto-Start Overlay

@@ -223,7 +255,7 @@ Control whether the overlay automatically becomes visible when it connects to mp
 | -------------------- | --------------- | ----------------------------------------------------- |
 | `auto_start_overlay` | `true`, `false` | Auto-show overlay on mpv connection (default: `true`) |

-When you launch through the SubMiner app or the `subminer` wrapper, the launcher reads these settings from this config and injects them into the mpv plugin at runtime — there is no separate plugin config file to edit. `auto_start_overlay` controls whether the visible overlay shows on auto-start. Two related keys in the `mpv` block tune startup behavior: `mpv.autoStartSubMiner` starts the overlay automatically when a file loads, and `mpv.pauseUntilOverlayReady` pauses mpv on visible auto-start until SubMiner signals overlay/tokenization readiness.
+When you launch through the SubMiner app or the `subminer` wrapper, the launcher reads these settings from this config and injects them into the mpv plugin at runtime - there is no separate plugin config file to edit. `auto_start_overlay` controls whether the visible overlay shows on auto-start. Two related keys in the `mpv` block tune startup behavior: `mpv.autoStartSubMiner` starts the overlay automatically when a file loads, and `mpv.pauseUntilOverlayReady` pauses mpv on visible auto-start until SubMiner signals overlay/tokenization readiness. On visible-overlay startup, SubMiner brings up the tray and visible overlay shell before tokenization and annotation warmups finish, then releases playback only after autoplay readiness.

 On Windows, packaged plugin installs also rewrite the plugin socket path to `\\.\pipe\subminer-socket`.

@@ -360,7 +392,7 @@ See `config.example.jsonc` for detailed configuration options.

 | Option                             | Values   | Description                                                                                                                  |
 | ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `primaryDefaultMode`               | string   | Default primary subtitle bar visibility mode: `"hidden"`, `"visible"`, or `"hover"` (default: `"visible"`)                 |
+| `primaryDefaultMode`               | string   | Default primary subtitle bar visibility mode: `"hidden"`, `"visible"`, or `"hover"` (default: `"visible"`)                   |
 | `subtitleStyle.css`                | object   | CSS declaration object applied to primary subtitles after normal style defaults. Use CSS property names such as `font-size`. |
 | `secondary.css`                    | object   | CSS declaration object applied to secondary subtitles after normal secondary style defaults.                                 |
 | `enableJlpt`                       | boolean  | Enable JLPT level underline styling (`false` by default)                                                                     |
@@ -516,19 +548,19 @@ See `config.example.jsonc` for detailed configuration options.
 }
 ```

-| Option                  | Values                             | Description                                            |
-| ----------------------- | ---------------------------------- | ------------------------------------------------------ |
-| `secondarySubLanguages` | string[]                           | Language codes to auto-load (e.g., `["eng", "en"]`)    |
-| `autoLoadSecondarySub`  | `true`, `false`                    | Auto-detect and load matching secondary subtitle track |
-| `defaultMode`           | `"hidden"`, `"visible"`, `"hover"` | Initial display mode (default: `"hover"`)              |
+| Option                  | Values                             | Description                                                                                                         |
+| ----------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `secondarySubLanguages` | string[]                           | Language codes to auto-load (e.g., `["eng", "en"]`); non-Signs/Songs tracks are preferred when several tracks match |
+| `autoLoadSecondarySub`  | `true`, `false`                    | Auto-detect and load matching secondary subtitle track                                                              |
+| `defaultMode`           | `"hidden"`, `"visible"`, `"hover"` | Initial display mode (default: `"hover"`)                                                                           |

 The secondary-subtitle language list also acts as the fallback secondary-language priority for managed startup subtitle selection on local playback and YouTube playback.

 **Display modes:**

- **hidden** — Secondary subtitles not shown
- **visible** — Always visible at top of overlay
- **hover** — Only visible when hovering over the subtitle area (default)
+- **hidden** - Secondary subtitles not shown
+- **visible** - Always visible at top of overlay
+- **hover** - Only visible when hovering over the subtitle area (default)

 **See `config.example.jsonc`** for additional secondary subtitle configuration options.

@@ -542,26 +574,29 @@ See `config.example.jsonc` for detailed configuration options and more examples.

 **Default keybindings:**

-| Key                  | Command                       | Description                             |
-| -------------------- | ----------------------------- | --------------------------------------- |
-| `Space`              | `["cycle", "pause"]`          | Toggle pause                            |
-| `KeyF`               | `["cycle", "fullscreen"]`     | Toggle fullscreen                       |
-| `KeyJ`               | `["cycle", "sid"]`            | Cycle primary subtitle track            |
-| `Shift+KeyJ`         | `["cycle", "secondary-sid"]`  | Cycle secondary subtitle track          |
-| `Ctrl+Alt+KeyP`      | `["__playlist-browser-open"]` | Open playlist browser                   |
-| `Ctrl+Alt+KeyC`      | `["__youtube-picker-open"]`   | Open the manual YouTube subtitle picker |
-| `ArrowRight`         | `["seek", 5]`                 | Seek forward 5 seconds                  |
-| `ArrowLeft`          | `["seek", -5]`                | Seek backward 5 seconds                 |
-| `ArrowUp`            | `["seek", 60]`                | Seek forward 60 seconds                 |
-| `ArrowDown`          | `["seek", -60]`               | Seek backward 60 seconds                |
-| `Shift+KeyH`         | `["sub-seek", -1]`            | Jump to previous subtitle               |
-| `Shift+KeyL`         | `["sub-seek", 1]`             | Jump to next subtitle                   |
-| `Shift+BracketLeft`  | `["__sub-delay-prev-line"]`   | Shift subtitle delay to previous cue    |
-| `Shift+BracketRight` | `["__sub-delay-next-line"]`   | Shift subtitle delay to next cue        |
-| `Ctrl+Shift+KeyH`    | `["__replay-subtitle"]`       | Replay current subtitle, pause at end   |
-| `Ctrl+Shift+KeyL`    | `["__play-next-subtitle"]`    | Play next subtitle, pause at end        |
-| `KeyQ`               | `["quit"]`                    | Quit mpv                                |
-| `Ctrl+KeyW`          | `["quit"]`                    | Quit mpv                                |
+| Key                     | Command                       | Description                             |
+| ----------------------- | ----------------------------- | --------------------------------------- |
+| `Space`                 | `["cycle", "pause"]`          | Toggle pause                            |
+| `KeyF`                  | `["cycle", "fullscreen"]`     | Toggle fullscreen                       |
+| `KeyJ`                  | `["cycle", "sid"]`            | Cycle primary subtitle track            |
+| `Shift+KeyJ`            | `["cycle", "secondary-sid"]`  | Cycle secondary subtitle track          |
+| `Ctrl+Alt+KeyP`         | `["__playlist-browser-open"]` | Open playlist browser                   |
+| `Ctrl+Alt+KeyC`         | `["__youtube-picker-open"]`   | Open the manual YouTube subtitle picker |
+| `ArrowRight`            | `["seek", 5]`                 | Seek forward 5 seconds                  |
+| `ArrowLeft`             | `["seek", -5]`                | Seek backward 5 seconds                 |
+| `ArrowUp`               | `["seek", 60]`                | Seek forward 60 seconds                 |
+| `ArrowDown`             | `["seek", -60]`               | Seek backward 60 seconds                |
+| `Shift+KeyH`            | `["sub-seek", -1]`            | Jump to previous subtitle               |
+| `Shift+KeyL`            | `["sub-seek", 1]`             | Jump to next subtitle                   |
+| `Ctrl+Shift+ArrowLeft`  | `["sub-step", -1]`            | Shift subtitle delay to previous cue    |
+| `Ctrl+Shift+ArrowRight` | `["sub-step", 1]`             | Shift subtitle delay to next cue        |
+| `KeyZ`                  | `["add", "sub-delay", -0.1]`  | Shift subtitles 100 ms earlier          |
+| `Shift+KeyZ`            | `["add", "sub-delay", 0.1]`   | Delay subtitles by 100 ms               |
+| `KeyX`                  | `["add", "sub-delay", 0.1]`   | Delay subtitles by 100 ms               |
+| `Ctrl+Shift+KeyH`       | `["__replay-subtitle"]`       | Replay current subtitle, pause at end   |
+| `Ctrl+Shift+KeyL`       | `["__play-next-subtitle"]`    | Play next subtitle, pause at end        |
+| `KeyQ`                  | `["quit"]`                    | Quit mpv                                |
+| `Ctrl+KeyW`             | `["quit"]`                    | Quit mpv                                |

 **Custom keybindings example:**

@@ -587,11 +622,11 @@ See `config.example.jsonc` for detailed configuration options and more examples.
 { "key": "Space", "command": null }
 ```

-**Special commands:** Commands prefixed with `__` are handled internally by the overlay rather than sent to mpv. `__playlist-browser-open` opens the split-pane playlist browser for the current file's parent directory and the live mpv queue. `__replay-subtitle` replays the current subtitle and pauses at its end. `__play-next-subtitle` seeks to the next subtitle, plays it, and pauses at its end. `__sub-delay-next-line` shifts subtitle delay so the active line aligns to the next cue start in the active subtitle source. `__sub-delay-prev-line` shifts subtitle delay so the active line aligns to the previous cue start. `__runtime-options-open` opens the runtime options palette. `__runtime-option-cycle:<id>[:next|prev]` cycles a runtime option value.
+**Special commands:** Commands prefixed with `__` are handled internally by the overlay rather than sent to mpv. `__playlist-browser-open` opens the split-pane playlist browser for the current file's parent directory and the live mpv queue. `__replay-subtitle` replays the current subtitle and pauses at its end. `__play-next-subtitle` seeks to the next subtitle, plays it, and pauses at its end. `__runtime-options-open` opens the runtime options palette. `__runtime-option-cycle:<id>[:next|prev]` cycles a runtime option value.

 **Supported commands:** Any valid mpv JSON IPC command array (`["cycle", "pause"]`, `["seek", 5]`, `["script-binding", "..."]`, etc.)

-For subtitle-position and subtitle-track proxy commands (`sub-pos`, `sid`, `secondary-sid`) and subtitle delay commands (`sub-delay`), SubMiner also shows an mpv OSD notification after the command runs.
+Subtitle delay commands (`sub-delay`, `sub-step`) show a native mpv OSD notification after the command runs. Subtitle-position and subtitle-track proxy commands (`sub-pos`, `sid`, `secondary-sid`) show playback feedback through the configured notification surface.

 **See `config.example.jsonc`** for more keybinding examples and configuration options.

@@ -620,31 +655,33 @@ See `config.example.jsonc` for detailed configuration options.
    "openControllerDebug": "Alt+Shift+C",
    "openJimaku": "Ctrl+Shift+J",
    "toggleSubtitleSidebar": "Backslash",
+    "toggleNotificationHistory": "CommandOrControl+N",
    "multiCopyTimeoutMs": 3000
  }
 }
 ```

-| Option                           | Values           | Description                                                                                                                               |
-| -------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `toggleVisibleOverlayGlobal`     | string \| `null` | Global accelerator for toggling visible subtitle overlay (default: `"Alt+Shift+O"`)                                                       |
-| `copySubtitle`                   | string \| `null` | Accelerator for copying current subtitle (default: `"CommandOrControl+C"`)                                                                |
-| `copySubtitleMultiple`           | string \| `null` | Accelerator for multi-copy mode (default: `"CommandOrControl+Shift+C"`)                                                                   |
-| `updateLastCardFromClipboard`    | string \| `null` | Accelerator for updating card from clipboard (default: `"CommandOrControl+V"`)                                                            |
-| `triggerFieldGrouping`           | string \| `null` | Accelerator for Kiku field grouping on last card (default: `"CommandOrControl+G"`; only active when automatic card updates are disabled)  |
-| `triggerSubsync`                 | string \| `null` | Accelerator for running Subsync (default: `"Ctrl+Alt+S"`)                                                                                 |
-| `mineSentence`                   | string \| `null` | Accelerator for creating sentence card from current subtitle (default: `"CommandOrControl+S"`)                                            |
-| `mineSentenceMultiple`           | string \| `null` | Accelerator for multi-mine sentence card mode (default: `"CommandOrControl+Shift+S"`)                                                     |
-| `multiCopyTimeoutMs`             | number           | Timeout in ms for multi-copy/mine digit input (default: `3000`)                                                                           |
-| `toggleSecondarySub`             | string \| `null` | Accelerator for cycling secondary subtitle mode (default: `"CommandOrControl+Shift+V"`)                                                   |
-| `markAudioCard`                  | string \| `null` | Accelerator for marking last card as audio card (default: `"CommandOrControl+Shift+A"`)                                                   |
-| `openCharacterDictionaryManager` | string \| `null` | Opens the loaded character dictionary manager (default: `"CommandOrControl+D"`)                                                           |
-| `openRuntimeOptions`             | string \| `null` | Opens runtime options palette for live session-only toggles (default: `"CommandOrControl+Shift+O"`)                                       |
-| `openSessionHelp`                | string \| `null` | Opens the in-overlay session help modal (default: `"CommandOrControl+Slash"`)                                                             |
-| `openControllerSelect`           | string \| `null` | Opens the controller config/remap modal (default: `"Alt+C"`)                                                                              |
-| `openControllerDebug`            | string \| `null` | Opens the controller debug modal (default: `"Alt+Shift+C"`)                                                                               |
-| `openJimaku`                     | string \| `null` | Opens the Jimaku search modal (default: `"Ctrl+Shift+J"`)                                                                                 |
-| `toggleSubtitleSidebar`          | string \| `null` | Dispatches the subtitle sidebar toggle action (default: `"Backslash"`). `subtitleSidebar.toggleKey` remains the primary bare-key setting. |
+| Option                           | Values           | Description                                                                                                                                                                        |
+| -------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `toggleVisibleOverlayGlobal`     | string \| `null` | Global accelerator for toggling visible subtitle overlay (default: `"Alt+Shift+O"`)                                                                                                |
+| `copySubtitle`                   | string \| `null` | Accelerator for copying current subtitle (default: `"CommandOrControl+C"`)                                                                                                         |
+| `copySubtitleMultiple`           | string \| `null` | Accelerator for multi-copy mode (default: `"CommandOrControl+Shift+C"`)                                                                                                            |
+| `updateLastCardFromClipboard`    | string \| `null` | Accelerator for updating card from clipboard (default: `"CommandOrControl+V"`)                                                                                                     |
+| `triggerFieldGrouping`           | string \| `null` | Accelerator for Kiku field grouping on last card (default: `"CommandOrControl+G"`; only active when automatic card updates are disabled)                                           |
+| `triggerSubsync`                 | string \| `null` | Accelerator for running Subsync (default: `"Ctrl+Alt+S"`)                                                                                                                          |
+| `mineSentence`                   | string \| `null` | Accelerator for creating sentence card from current subtitle (default: `"CommandOrControl+S"`)                                                                                     |
+| `mineSentenceMultiple`           | string \| `null` | Accelerator for multi-mine sentence card mode (default: `"CommandOrControl+Shift+S"`)                                                                                              |
+| `multiCopyTimeoutMs`             | number           | Timeout in ms for multi-copy/mine digit input (default: `3000`)                                                                                                                    |
+| `toggleSecondarySub`             | string \| `null` | Accelerator for cycling secondary subtitle mode (default: `"CommandOrControl+Shift+V"`)                                                                                            |
+| `markAudioCard`                  | string \| `null` | Accelerator for marking last card as audio card (default: `"CommandOrControl+Shift+A"`)                                                                                            |
+| `openCharacterDictionaryManager` | string \| `null` | Opens the loaded character dictionary manager (default: `"CommandOrControl+D"`)                                                                                                    |
+| `openRuntimeOptions`             | string \| `null` | Opens runtime options palette for live session-only toggles (default: `"CommandOrControl+Shift+O"`)                                                                                |
+| `openSessionHelp`                | string \| `null` | Opens the in-overlay session help modal (default: `"CommandOrControl+Slash"`)                                                                                                      |
+| `openControllerSelect`           | string \| `null` | Opens the controller config/remap modal (default: `"Alt+C"`)                                                                                                                       |
+| `openControllerDebug`            | string \| `null` | Opens the controller debug modal (default: `"Alt+Shift+C"`)                                                                                                                        |
+| `openJimaku`                     | string \| `null` | Opens the Jimaku search modal (default: `"Ctrl+Shift+J"`)                                                                                                                          |
+| `toggleSubtitleSidebar`          | string \| `null` | Dispatches the subtitle sidebar toggle action (default: `"Backslash"`). `subtitleSidebar.toggleKey` remains the primary bare-key setting.                                          |
+| `toggleNotificationHistory`      | string \| `null` | Toggles the overlay notification history panel (default: `"CommandOrControl+N"`). The panel slides in from the same edge as notifications (right when notifications are centered). |

 **See `config.example.jsonc`** for the complete list of shortcut configuration options.

@@ -914,6 +951,7 @@ Enable automatic Anki card creation and updates with media generation:
      "animatedMaxWidth": 640,
      "animatedMaxHeight": 0,
      "animatedCrf": 35,
+      "normalizeAudio": true,
      "audioPadding": 0,
      "fallbackDuration": 3,
      "maxMediaDuration": 30
@@ -943,57 +981,58 @@ This example is intentionally compact. The option table below documents availabl

 **Requirements:** [AnkiConnect](https://github.com/FooSoft/anki-connect) plugin must be installed and running in Anki. ffmpeg must be installed for media generation.

-| Option                                            | Values                                  | Description                                                                                                                                                                                                 |
-| ------------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ankiConnect.enabled`                             | `true`, `false`                         | Enable AnkiConnect integration (default: `true`)                                                                                                                                                            |
-| `url`                                             | string (URL)                            | AnkiConnect API URL (default: `http://127.0.0.1:8765`)                                                                                                                                                      |
-| `pollingRate`                                     | number (ms)                             | How often to check for new cards in polling mode (default: `3000`; ignored for direct proxy `addNote`/`addNotes` updates)                                                                                   |
-| `proxy.enabled`                                   | `true`, `false`                         | Enable local AnkiConnect-compatible proxy for push-based auto-enrichment (default: `true`)                                                                                                                  |
-| `proxy.host`                                      | string                                  | Bind host for local AnkiConnect proxy (default: `127.0.0.1`)                                                                                                                                                |
-| `proxy.port`                                      | number                                  | Bind port for local AnkiConnect proxy (default: `8766`)                                                                                                                                                     |
-| `proxy.upstreamUrl`                               | string (URL)                            | Upstream AnkiConnect URL that proxy forwards to (default: `http://127.0.0.1:8765`)                                                                                                                          |
-| `tags`                                            | array of strings                        | Tags automatically added to cards mined/updated by SubMiner (default: `['SubMiner']`; set `[]` to disable automatic tagging).                                                                               |
-| `ankiConnect.deck`                                | string                                  | Restrict duplicate detection and card enrichment to this Anki deck. Leave empty to search all decks. In Settings, this dropdown auto-fills from Yomitan's current mining deck when available.               |
-| `fields.word`                                     | string                                  | Card field for mined word / expression text (default: `Expression`)                                                                                                                                         |
-| `fields.audio`                                    | string                                  | Card field for audio files (default: `ExpressionAudio`)                                                                                                                                                     |
-| `fields.image`                                    | string                                  | Card field for images (default: `Picture`)                                                                                                                                                                  |
-| `fields.sentence`                                 | string                                  | Card field for sentences (default: `Sentence`)                                                                                                                                                              |
-| `fields.miscInfo`                                 | string                                  | Card field for metadata (default: `"MiscInfo"`, set to `null` to disable)                                                                                                                                   |
-| `fields.translation`                              | string                                  | Card field for sentence-card translation/back text (default: `SelectionText`)                                                                                                                               |
-| `ankiConnect.ai.enabled`                          | `true`, `false`                         | Use AI translation for sentence cards. Also auto-attempted when secondary subtitle is missing.                                                                                                              |
-| `ankiConnect.ai.model`                            | string                                  | Optional model override for Anki AI translation/enrichment flows.                                                                                                                                           |
-| `ankiConnect.ai.systemPrompt`                     | string                                  | Optional system prompt override for Anki AI translation/enrichment flows.                                                                                                                                   |
-| `media.generateAudio`                             | `true`, `false`                         | Generate audio clips from video (default: `true`)                                                                                                                                                           |
-| `media.generateImage`                             | `true`, `false`                         | Generate image/animation screenshots (default: `true`)                                                                                                                                                      |
-| `media.imageType`                                 | `"static"`, `"avif"`                    | Image type: static screenshot or animated AVIF (default: `"static"`)                                                                                                                                        |
-| `media.imageFormat`                               | `"jpg"`, `"png"`, `"webp"`              | Image format (default: `"jpg"`)                                                                                                                                                                             |
-| `media.imageQuality`                              | number (1-100)                          | Image quality for JPG/WebP; PNG ignores this (default: `92`)                                                                                                                                                |
-| `media.imageMaxWidth`                             | number (px)                             | Optional max width for static screenshots. Unset keeps source width.                                                                                                                                        |
-| `media.imageMaxHeight`                            | number (px)                             | Optional max height for static screenshots. Unset keeps source height.                                                                                                                                      |
-| `media.animatedFps`                               | number (1-60)                           | FPS for animated AVIF (default: `10`)                                                                                                                                                                       |
-| `media.animatedMaxWidth`                          | number (px)                             | Max width for animated AVIF (default: `640`)                                                                                                                                                                |
-| `media.animatedMaxHeight`                         | number (px)                             | Optional max height for animated AVIF. Unset keeps source aspect-constrained height.                                                                                                                        |
-| `media.animatedCrf`                               | number (0-63)                           | CRF quality for AVIF; lower = higher quality (default: `35`)                                                                                                                                                |
-| `media.syncAnimatedImageToWordAudio`              | `true`, `false`                         | Whether animated AVIF includes an opening frame synced to sentence word-audio timing (default: `true`).                                                                                                     |
-| `media.audioPadding`                              | number (seconds)                        | Optional padding around generated sentence media timing (default: `0`). Animated AVIF clips include the same padded source range as sentence audio.                                                         |
-| `media.fallbackDuration`                          | number (seconds)                        | Default duration if timing unavailable (default: `3.0`)                                                                                                                                                     |
-| `media.maxMediaDuration`                          | number (seconds)                        | Max duration for generated media from multi-line copy (default: `30`, `0` to disable)                                                                                                                       |
-| `behavior.overwriteAudio`                         | `true`, `false`                         | Replace existing audio on updates; when `false`, new audio is appended/prepended using the configured media insert mode; manual clipboard updates always replace generated sentence audio (default: `true`) |
-| `behavior.overwriteImage`                         | `true`, `false`                         | Replace existing images on updates; when `false`, new images are appended/prepended using the configured media insert mode (default: `true`)                                                                |
-| `behavior.mediaInsertMode`                        | `"append"`, `"prepend"`                 | Where to insert new media when overwrite is off (default: `"append"`)                                                                                                                                       |
-| `behavior.highlightWord`                          | `true`, `false`                         | Highlight the word in sentence context (default: `true`)                                                                                                                                                    |
-| `ankiConnect.knownWords.highlightEnabled`         | `true`, `false`                         | Enable fast local highlighting for words already known in Anki (default: `false`)                                                                                                                           |
-| `ankiConnect.knownWords.addMinedWordsImmediately` | `true`, `false`                         | Add words from successful mines into the local known-word cache immediately (default: `true`)                                                                                                               |
-| `ankiConnect.knownWords.matchMode`                | `"headword"`, `"surface"`               | Matching strategy for known-word highlighting (default: `"headword"`). `headword` uses token headwords; `surface` uses visible subtitle text.                                                               |
-| `ankiConnect.knownWords.refreshMinutes`           | number                                  | Minutes between known-word cache refreshes (default: `1440`)                                                                                                                                                |
-| `ankiConnect.knownWords.decks`                    | object                                  | Deck→fields mapping used for known-word cache query scope (e.g. `{ "Kaishi 1.5k": ["Word"] }`).                                                                                                             |
-| `ankiConnect.nPlusOne.enabled`                    | `true`, `false`                         | Enable N+1 subtitle highlighting (highlights the one unknown word in a sentence). Independent from `knownWords.highlightEnabled`. Requires known-word cache data (default: `false`).                        |
-| `ankiConnect.nPlusOne.minSentenceWords`           | number                                  | Minimum number of words required in a sentence before single unknown-word N+1 highlighting can trigger (default: `3`).                                                                                      |
-| `behavior.notificationType`                       | `"osd"`, `"system"`, `"both"`, `"none"` | Notification type on card update (default: `"osd"`)                                                                                                                                                         |
-| `behavior.autoUpdateNewCards`                     | `true`, `false`                         | Automatically update cards on creation (default: `true`)                                                                                                                                                    |
-| `metadata.pattern`                                | string                                  | Format pattern for metadata: `%f`=filename, `%F`=filename+ext, `%t`=time                                                                                                                                    |
-| `isLapis`                                         | object                                  | Lapis/shared sentence-card config: `{ enabled, sentenceCardModel }`. Sentence/audio field names are fixed to `Sentence` and `SentenceAudio`.                                                                |
-| `isKiku`                                          | object                                  | Kiku-only config: `{ enabled, fieldGrouping, deleteDuplicateInAuto }` (shared sentence/audio/model settings are inherited from `isLapis`)                                                                   |
+| Option                                            | Values                                      | Description                                                                                                                                                                                                                     |
+| ------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ankiConnect.enabled`                             | `true`, `false`                             | Enable AnkiConnect integration (default: `true`)                                                                                                                                                                                |
+| `url`                                             | string (URL)                                | AnkiConnect API URL (default: `http://127.0.0.1:8765`)                                                                                                                                                                          |
+| `pollingRate`                                     | number (ms)                                 | How often to check for new cards in polling mode (default: `3000`; ignored for direct proxy `addNote`/`addNotes` updates)                                                                                                       |
+| `proxy.enabled`                                   | `true`, `false`                             | Enable local AnkiConnect-compatible proxy for push-based auto-enrichment (default: `true`)                                                                                                                                      |
+| `proxy.host`                                      | string                                      | Bind host for local AnkiConnect proxy (default: `127.0.0.1`)                                                                                                                                                                    |
+| `proxy.port`                                      | number                                      | Bind port for local AnkiConnect proxy (default: `8766`)                                                                                                                                                                         |
+| `proxy.upstreamUrl`                               | string (URL)                                | Upstream AnkiConnect URL that proxy forwards to (default: `http://127.0.0.1:8765`)                                                                                                                                              |
+| `tags`                                            | array of strings                            | Tags automatically added to cards mined/updated by SubMiner (default: `['SubMiner']`; set `[]` to disable automatic tagging).                                                                                                   |
+| `ankiConnect.deck`                                | string                                      | Restrict duplicate detection and card enrichment to this Anki deck. Leave empty to use the Yomitan mining deck when available. In Settings, this dropdown auto-fills and persists Yomitan's current mining deck when available. |
+| `fields.word`                                     | string                                      | Card field for mined word / expression text (default: `Expression`)                                                                                                                                                             |
+| `fields.audio`                                    | string                                      | Card field for audio files (default: `ExpressionAudio`)                                                                                                                                                                         |
+| `fields.image`                                    | string                                      | Card field for images (default: `Picture`)                                                                                                                                                                                      |
+| `fields.sentence`                                 | string                                      | Card field for sentences (default: `Sentence`)                                                                                                                                                                                  |
+| `fields.miscInfo`                                 | string                                      | Card field for metadata (default: `"MiscInfo"`, set to `null` to disable)                                                                                                                                                       |
+| `fields.translation`                              | string                                      | Card field for sentence-card translation/back text (default: `SelectionText`)                                                                                                                                                   |
+| `ankiConnect.ai.enabled`                          | `true`, `false`                             | Use AI translation for sentence cards. Also auto-attempted when secondary subtitle is missing.                                                                                                                                  |
+| `ankiConnect.ai.model`                            | string                                      | Optional model override for Anki AI translation/enrichment flows.                                                                                                                                                               |
+| `ankiConnect.ai.systemPrompt`                     | string                                      | Optional system prompt override for Anki AI translation/enrichment flows.                                                                                                                                                       |
+| `media.generateAudio`                             | `true`, `false`                             | Generate audio clips from video (default: `true`)                                                                                                                                                                               |
+| `media.normalizeAudio`                            | `true`, `false`                             | Normalize generated sentence-audio loudness during media extraction (default: `true`). Set to `false` to keep raw source loudness.                                                                                              |
+| `media.generateImage`                             | `true`, `false`                             | Generate image/animation screenshots (default: `true`)                                                                                                                                                                          |
+| `media.imageType`                                 | `"static"`, `"avif"`                        | Image type: static screenshot or animated AVIF (default: `"static"`)                                                                                                                                                            |
+| `media.imageFormat`                               | `"jpg"`, `"png"`, `"webp"`                  | Image format (default: `"jpg"`)                                                                                                                                                                                                 |
+| `media.imageQuality`                              | number (1-100)                              | Image quality for JPG/WebP; PNG ignores this (default: `92`)                                                                                                                                                                    |
+| `media.imageMaxWidth`                             | number (px)                                 | Optional max width for static screenshots. Unset keeps source width.                                                                                                                                                            |
+| `media.imageMaxHeight`                            | number (px)                                 | Optional max height for static screenshots. Unset keeps source height.                                                                                                                                                          |
+| `media.animatedFps`                               | number (1-60)                               | FPS for animated AVIF (default: `10`)                                                                                                                                                                                           |
+| `media.animatedMaxWidth`                          | number (px)                                 | Max width for animated AVIF (default: `640`)                                                                                                                                                                                    |
+| `media.animatedMaxHeight`                         | number (px)                                 | Optional max height for animated AVIF. Unset keeps source aspect-constrained height.                                                                                                                                            |
+| `media.animatedCrf`                               | number (0-63)                               | CRF quality for AVIF; lower = higher quality (default: `35`)                                                                                                                                                                    |
+| `media.syncAnimatedImageToWordAudio`              | `true`, `false`                             | Whether animated AVIF includes an opening frame synced to sentence word-audio timing (default: `true`).                                                                                                                         |
+| `media.audioPadding`                              | number (seconds)                            | Optional padding around generated sentence media timing (default: `0`). Animated AVIF clips include the same padded source range as sentence audio.                                                                             |
+| `media.fallbackDuration`                          | number (seconds)                            | Default duration if timing unavailable (default: `3.0`)                                                                                                                                                                         |
+| `media.maxMediaDuration`                          | number (seconds)                            | Max duration for generated media from multi-line copy (default: `30`, `0` to disable)                                                                                                                                           |
+| `behavior.overwriteAudio`                         | `true`, `false`                             | Replace existing audio on updates; when `false`, new audio is appended/prepended using the configured media insert mode; manual clipboard updates always replace generated sentence audio (default: `true`)                     |
+| `behavior.overwriteImage`                         | `true`, `false`                             | Replace existing images on updates; when `false`, new images are appended/prepended using the configured media insert mode (default: `true`)                                                                                    |
+| `behavior.mediaInsertMode`                        | `"append"`, `"prepend"`                     | Where to insert new media when overwrite is off (default: `"append"`)                                                                                                                                                           |
+| `behavior.highlightWord`                          | `true`, `false`                             | Highlight the word in sentence context (default: `true`)                                                                                                                                                                        |
+| `ankiConnect.knownWords.highlightEnabled`         | `true`, `false`                             | Enable fast local highlighting for words already known in Anki (default: `false`)                                                                                                                                               |
+| `ankiConnect.knownWords.addMinedWordsImmediately` | `true`, `false`                             | Add words from successful mines into the local known-word cache immediately (default: `true`)                                                                                                                                   |
+| `ankiConnect.knownWords.matchMode`                | `"headword"`, `"surface"`                   | Matching strategy for known-word highlighting (default: `"headword"`). `headword` uses token headwords; `surface` uses visible subtitle text.                                                                                   |
+| `ankiConnect.knownWords.refreshMinutes`           | number                                      | Minutes between known-word cache refreshes (default: `1440`)                                                                                                                                                                    |
+| `ankiConnect.knownWords.decks`                    | object                                      | Deck→fields mapping used for known-word cache query scope (e.g. `{ "Kaishi 1.5k": ["Word"] }`).                                                                                                                                 |
+| `ankiConnect.nPlusOne.enabled`                    | `true`, `false`                             | Enable N+1 subtitle highlighting (highlights the one unknown word in a sentence). Independent from `knownWords.highlightEnabled`. Requires known-word cache data (default: `false`).                                            |
+| `ankiConnect.nPlusOne.minSentenceWords`           | number                                      | Minimum number of words required in a sentence before single unknown-word N+1 highlighting can trigger (default: `3`).                                                                                                          |
+| `behavior.notificationType`                       | `"overlay"`, `"system"`, `"both"`, `"none"` | Notification type on card update (default: `"overlay"`). `"both"` means overlay + system. `osd` and `osd-system` are legacy config-file-only values; use `"osd-system"` to keep the old OSD + system behavior.                  |
+| `behavior.autoUpdateNewCards`                     | `true`, `false`                             | Automatically update cards on creation (default: `true`)                                                                                                                                                                        |
+| `metadata.pattern`                                | string                                      | Format pattern for metadata: `%f`=filename, `%F`=filename+ext, `%t`=time                                                                                                                                                        |
+| `isLapis`                                         | object                                      | Lapis/shared sentence-card config: `{ enabled, sentenceCardModel }`. Sentence/audio field names are fixed to `Sentence` and `SentenceAudio`.                                                                                    |
+| `isKiku`                                          | object                                      | Kiku-only config: `{ enabled, fieldGrouping, deleteDuplicateInAuto }` (shared sentence/audio/model settings are inherited from `isLapis`)                                                                                       |

 `ankiConnect.ai` only controls feature-local enablement plus optional `model` / `systemPrompt` overrides.
 API key resolution, base URL, and timeout live under the shared top-level [`ai`](#shared-ai-provider) config.
@@ -1101,8 +1140,8 @@ Set `openBrowser` to `false` to only print the URL without opening a browser.

 Sync the active subtitle track from the overlay picker using `alass` or `ffsubsync`. Both are **optional external tools** that must be installed separately and available on your `PATH` (or configured via the path options below).

- [`alass`](https://github.com/kaegi/alass) — fast, audio-independent sync using a secondary subtitle as reference
- [`ffsubsync`](https://github.com/smacke/ffsubsync) — audio-based sync using the video file as reference
+- [`alass`](https://github.com/kaegi/alass) - fast, audio-independent sync using a secondary subtitle as reference
+- [`ffsubsync`](https://github.com/smacke/ffsubsync) - audio-based sync using the video file as reference

 ```json
 {
@@ -1122,6 +1161,8 @@ Sync the active subtitle track from the overlay picker using `alass` or `ffsubsy
 | `ffmpeg_path`    | string path     | Path to `ffmpeg` (used for internal subtitle extraction). Empty or `null` falls back to `/usr/bin/ffmpeg`.                |
 | `replace`        | `true`, `false` | When `true` (default), overwrite the active subtitle file on successful sync. When `false`, write `<name>_retimed.<ext>`. |

+Stats dashboard sentence mining also uses `alass_path` when available to align a local English sidecar against the local Japanese sidecar before filling the card translation field. This stats-only retime writes a temporary cached copy and never edits the original subtitle files.
+
 Default trigger is `Ctrl+Alt+S` via `shortcuts.triggerSubsync`.
 Customize it there, or set it to `null` to disable.

@@ -1380,9 +1421,9 @@ Enable or disable local immersion analytics stored in SQLite for mined subtitles
 | `retention.dailyRollupsDays`   | integer (`0`-`36500`)               | Daily rollup retention window. Default `0` (keep all).                                                      |
 | `retention.monthlyRollupsDays` | integer (`0`-`36500`)               | Monthly rollup retention window. Default `0` (keep all).                                                    |
 | `retention.vacuumIntervalDays` | integer (`0`-`3650`)                | Minimum spacing between `VACUUM` passes. `0` disables vacuum. Default `0` (disabled).                       |
-| `lifetimeSummaries.global`     | `true`, `false`                     | Maintain global lifetime stats rows (default: `true`).                                                              |
-| `lifetimeSummaries.anime`      | `true`, `false`                     | Maintain per-anime lifetime stats rows (default: `true`).                                                           |
-| `lifetimeSummaries.media`      | `true`, `false`                     | Maintain per-media lifetime stats rows (default: `true`).                                                           |
+| `lifetimeSummaries.global`     | `true`, `false`                     | Maintain global lifetime stats rows (default: `true`).                                                      |
+| `lifetimeSummaries.anime`      | `true`, `false`                     | Maintain per-anime lifetime stats rows (default: `true`).                                                   |
+| `lifetimeSummaries.media`      | `true`, `false`                     | Maintain per-media lifetime stats rows (default: `true`).                                                   |

 You can also disable immersion tracking for a single session using:

@@ -1433,7 +1474,7 @@ Usage notes:
 - The browser UI is served at `http://127.0.0.1:<serverPort>`.
 - The overlay toggle is local to the focused visible overlay window; it is not registered as a global OS shortcut.
 - The dashboard reads from the same immersion-tracking database, so keep `immersionTracking.enabled` on if you want data to appear.
- The UI includes Overview, Library, Trends, Vocabulary, and Sessions tabs.
+- The UI includes Overview, Library, Trends, Vocabulary, Search, and Sessions tabs.

 ### MPV Launcher

@@ -1456,26 +1497,26 @@ Configure the mpv executable, profile, and window state for SubMiner-managed mpv
 }
 ```

-| Option                  | Values                                                              | Description                                                                                                                         |
-| ----------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `executablePath`        | string                                                              | Absolute path to `mpv.exe` for Windows launch flows. Leave empty to auto-discover from `SUBMINER_MPV_PATH` or `PATH` (default `""`) |
-| `profile`               | string                                                              | mpv profile name passed as `--profile=<name>`. Leave empty to pass no profile (default `""`)                                        |
-| `launchMode`            | `"normal"` \| `"maximized"` \| `"fullscreen"`                       | Window state when SubMiner spawns mpv (default `"normal"`)                                                                          |
-| `socketPath`            | string                                                              | mpv IPC socket path used by SubMiner-managed playback and the bundled mpv plugin (default: `\\\\.\\pipe\\subminer-socket`)          |
-| `backend`               | `"auto"` \| `"hyprland"` \| `"sway"` \| `"x11"` \| `"macos"` \| `"windows"` | Window tracking backend passed to the bundled mpv plugin. Auto detects the current platform (default: `"auto"`)                     |
-| `autoStartSubMiner`     | `true`, `false`                                                     | Start SubMiner in the background when SubMiner-managed mpv loads a file (default: `true`)                                           |
-| `pauseUntilOverlayReady`| `true`, `false`                                                     | Pause mpv on visible-overlay auto-start until SubMiner signals subtitle tokenization readiness (default: `true`)                    |
-| `subminerBinaryPath`    | string                                                              | SubMiner app binary path passed to the bundled mpv plugin. Leave empty to use the launcher-detected app path (default: `""`)        |
-| `aniskipEnabled`        | `true`, `false`                                                     | Enable AniSkip intro detection and skip markers in the bundled mpv plugin (default: `true`)                                         |
-| `aniskipButtonKey`      | string                                                              | mpv key used to trigger the AniSkip button while the skip marker is visible (default: `"TAB"`)                                      |
+| Option                   | Values                                                                      | Description                                                                                                                                 |
+| ------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `executablePath`         | string                                                                      | Absolute path to `mpv.exe` for Windows launch flows. Leave empty to auto-discover from `SUBMINER_MPV_PATH` or `PATH` (default `""`)         |
+| `profile`                | string                                                                      | mpv profile name passed as `--profile=<name>`. Leave empty to pass no profile (default `""`)                                                |
+| `launchMode`             | `"normal"` \| `"maximized"` \| `"fullscreen"`                               | Window state when SubMiner spawns mpv (default `"normal"`)                                                                                  |
+| `socketPath`             | string                                                                      | mpv IPC socket path used by SubMiner-managed playback and the bundled mpv plugin (default: `\\\\.\\pipe\\subminer-socket`)                  |
+| `backend`                | `"auto"` \| `"hyprland"` \| `"sway"` \| `"x11"` \| `"macos"` \| `"windows"` | Window tracking backend passed to the bundled mpv plugin. Auto detects the current platform (default: `"auto"`)                             |
+| `autoStartSubMiner`      | `true`, `false`                                                             | Start SubMiner in the background when SubMiner-managed mpv loads a file (default: `true`)                                                   |
+| `pauseUntilOverlayReady` | `true`, `false`                                                             | Pause mpv on visible-overlay auto-start until SubMiner signals subtitle tokenization readiness, with a 30-second fallback (default: `true`) |
+| `subminerBinaryPath`     | string                                                                      | SubMiner app binary path passed to the bundled mpv plugin. Leave empty to use the launcher-detected app path (default: `""`)                |
+| `aniskipEnabled`         | `true`, `false`                                                             | Enable AniSkip intro detection, chapter markers, and the skip-intro key (default: `true`)                                                   |
+| `aniskipButtonKey`       | string                                                                      | mpv key used to skip the detected intro while the skip prompt is visible (default: `"TAB"`)                                                 |

 If `mpv.profile` is configured and the launcher also receives `--profile`, SubMiner passes both as a comma-separated mpv profile list.

 Launch mode behavior:

- **`normal`** — mpv opens at its default window size with no extra flags.
- **`maximized`** — mpv starts maximized via `--window-maximized=yes`, keeping taskbar access.
- **`fullscreen`** — mpv starts in true fullscreen via `--fullscreen`.
+- **`normal`** - mpv opens at its default window size with no extra flags.
+- **`maximized`** - mpv starts maximized via `--window-maximized=yes`, keeping taskbar access.
+- **`fullscreen`** - mpv starts in true fullscreen via `--fullscreen`.

 ### YouTube Playback Settings

@@ -1484,14 +1525,24 @@ Set defaults used by managed subtitle auto-selection and the `subminer` launcher
 ```json
 {
  "youtube": {
-    "primarySubLanguages": ["ja", "jpn"]
+    "primarySubLanguages": ["ja", "jpn"],
+    "mediaCache": {
+      "mode": "direct",
+      "maxHeight": 720
+    }
  }
 }
 ```

-| Option                | Values   | Description                                                                                      |
-| --------------------- | -------- | ------------------------------------------------------------------------------------------------ |
-| `primarySubLanguages` | string[] | Primary subtitle language priority for managed subtitle auto-selection (default `["ja", "jpn"]`) |
+| Option                 | Values                   | Description                                                                                      |
+| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
+| `primarySubLanguages`  | string[]                 | Primary subtitle language priority for managed subtitle auto-selection (default `["ja", "jpn"]`) |
+| `mediaCache.mode`      | `direct` \| `background` | YouTube card audio/image extraction mode (default `direct`)                                      |
+| `mediaCache.maxHeight` | number                   | Maximum background cache download height. Set `0` for unlimited (default `720`)                  |
+
+`mediaCache.mode: "direct"` extracts card media from the active YouTube stream URL. `mediaCache.mode: "background"` starts a separate yt-dlp media download after YouTube playback has loaded, including YouTube URLs opened directly in mpv and resolved stream URLs when mpv still exposes the original YouTube playlist entry. Playback and subtitle loading do not wait for that download. Use background mode if direct card media generation hits YouTube `403` errors from expiring stream URLs.
+
+Background cache downloads are capped by `mediaCache.maxHeight`, which defaults to 720p; set it to `0` to let yt-dlp choose the best available height. Downloads use IPv4 and yt-dlp retry flags to reduce YouTube throttling failures. SubMiner announces when the background cache download starts and when the cache is ready, using the configured notification surface; overlay and OSD messages queue until the overlay or mpv is ready. If you mine cards before the cache is ready, SubMiner creates the text fields immediately, queues the audio/image work for those note IDs, shows a status notification, and fills the media fields once the cached file is ready. If the cache download fails, SubMiner shows a failure notification, shows queued-card failure notifications, and clears the pending updates.

 Current launcher behavior:

@@ -25,7 +25,7 @@ Mine vocabulary cards from Yomitan or directly from subtitle lines. SubMiner aut

 ## Subtitle Download & Sync

-Search and download subtitles from Jimaku, then retime them with alass or ffsubsync — all from within SubMiner.
+Search and download subtitles from Jimaku, then retime them with alass or ffsubsync - all from within SubMiner.

 <!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/subtitle-sync-poster.jpg?v=${v}`)">
  <source :src="withBase(`/assets/demos/subtitle-sync.webm?v=${v}`)" type="video/webm" />
@@ -11,15 +11,10 @@ For internal architecture/workflow guidance, use `docs/README.md` at the repo ro
 ```bash
 git clone --recurse-submodules https://github.com/ksyasuda/SubMiner.git
 cd SubMiner
-# if you cloned without --recurse-submodules:
-git submodule update --init --recursive
-
-bun install
-(cd stats && bun install --frozen-lockfile)
-(cd vendor/texthooker-ui && bun install --frozen-lockfile)
+make deps
 ```

-`make deps` is still available as a convenience wrapper around the same dependency install flow.
+`make deps` initializes submodules and installs root, `stats/`, and `vendor/texthooker-ui` dependencies. The Yomitan submodule installs its own dependencies on demand during `bun run build`.

 ## Building

@@ -85,18 +80,24 @@ Default lanes:

 ```bash
 bun run test           # alias for test:fast
-bun run test:fast      # default fast lane
-bun run test:full      # maintained source + launcher-unit + runtime compat surface
+bun run test:fast      # full source lanes: src + launcher-unit + scripts + runtime compat
 bun run test:runtime:compat # compiled/runtime compatibility slice only
 bun run test:env       # launcher/plugin + env-sensitive verification
+bun run test:stats     # stats dashboard UI suite
 bun run test:immersion:sqlite # SQLite persistence lane
 bun run test:subtitle  # maintained alass/ffsubsync subtitle surface
 ```

- `bun run test` and `bun run test:fast` cover config/core suites plus representative entry/runtime, Anki integration, release-workflow coverage, typecheck, and runtime-registry checks.
- `bun run test:full` is the maintained full surface: Bun-compatible `src/**` discovery, Bun-compatible launcher unit discovery, and the compiled/runtime compatibility lane for suites routed through `dist/**`.
+Test lane membership is defined once in `scripts/test-lanes.ts` and discovered by
+directory, so new test files join their lane automatically. `scripts/run-test-lane.mjs`
+runs each test file in its own `bun test` process (per-file isolation) so a hanging
+test or leaked global in one file cannot cascade into the rest of the lane; pass
+`--jobs N` to parallelize or `--single-process` for one shared process.
+
+- `bun run test` and `bun run test:fast` cover the full discovered `src/**` suite, launcher unit tests, `scripts/**` tests, and the compiled/runtime compatibility lane.
 - `bun run test:runtime:compat` covers the compiled/runtime slice directly: `ipc`, `anki-jimaku-ipc`, `overlay-manager`, `config-validation`, `startup-config`, and `registry`.
 - `bun run test:env` covers environment-sensitive checks: launcher smoke/plugin verification plus the Bun source SQLite lane.
+- `bun run test:stats` runs the stats dashboard suite under `stats/src/**`.
 - `bun run test:immersion:sqlite` is the reproducible persistence lane when you need real DB-backed SQLite coverage under Bun.

 The Bun-managed discovery lanes intentionally exclude a small compiled/runtime-focused set: `src/core/services/ipc.test.ts`, `src/core/services/anki-jimaku-ipc.test.ts`, `src/core/services/overlay-manager.test.ts`, `src/main/config-validation.test.ts`, `src/main/runtime/startup-config.test.ts`, and `src/main/runtime/registry.test.ts`. `bun run test:runtime:compat` keeps them in the standard workflow via `dist/**`.
@@ -131,11 +132,11 @@ Focused commands:
 ```bash
 bun run test:config       # Source-level config schema/validation tests
 bun run test:launcher     # Launcher regression tests (config discovery + command routing)
-bun run test:core         # Source-level core regression tests (default lane)
 bun run test:launcher:smoke:src # Launcher e2e smoke: launcher -> mpv IPC -> overlay start/stop wiring
 bun run test:launcher:env:src # Launcher smoke + Lua plugin gate
 bun run test:src          # Bun-managed maintained src/** discovery lane
 bun run test:launcher:unit:src # Bun-managed maintained launcher unit lane
+bun run test:scripts      # Bun-managed scripts/** test lane
 bun run test:immersion:sqlite:src # Bun source lane
 ```

@@ -149,8 +150,6 @@ Smoke and optional deep dist commands:
 bun run build                 # compile dist artifacts
 bun run test:immersion:sqlite # compile + run SQLite-backed immersion tests under Bun
 bun run test:smoke:dist       # explicit smoke scope for compiled runtime
-bun run test:config:dist      # optional full dist config suite
-bun run test:core:dist        # optional full dist core suite
 ```

 Use `bun run test:immersion:sqlite` when you need real DB-backed coverage for the immersion tracker.
@@ -216,7 +215,7 @@ Run `make help` for a full list of targets. Key ones:
 | `make build`                | Build platform package for detected OS                            |
 | `make build-launcher`       | Generate Bun launcher wrapper at `dist/launcher/subminer`         |
 | `make install`              | Install platform artifacts (wrapper, theme, AppImage/app bundle)  |
-| `make deps`                 | Install JS dependencies (root + stats + texthooker-ui)            |
+| `make deps`                 | Init submodules and install root/stats/texthooker-ui deps         |
 | `make pretty`               | Run scoped Prettier formatting for maintained source/config files |
 | `make generate-config`      | Generate default config from centralized registry                 |
 | `make build-linux`          | Convenience wrapper for Linux packaging                           |
@@ -2,12 +2,12 @@

 SubMiner can log your watching and mining activity to a local SQLite database, then surface it in the built-in stats dashboard. Tracking is enabled by default and can be turned off if you do not want local analytics.

-"Immersion" here means time spent watching and reading native Japanese content. **All data stays on your computer** — nothing is uploaded anywhere. (SQLite is just a single-file database; you do not need to install or manage anything.)
+"Immersion" here means time spent watching and reading native Japanese content. **All data stays on your computer** - nothing is uploaded anywhere. (SQLite is just a single-file database; you do not need to install or manage anything.)

 When enabled, SubMiner records per-session statistics (watch time, subtitle lines seen, words encountered, cards mined) and maintains exact lifetime summary tables plus daily/monthly rollups. You can view that data in SubMiner's stats UI or query the database directly with any SQLite tool.

 ::: tip For most users
-Just leave tracking on and use the built-in [Stats Dashboard](#stats-dashboard). The retention, performance, SQL, and schema sections further down are reference material for advanced users who want to inspect or tune the database — you can safely skip them.
+Just leave tracking on and use the built-in [Stats Dashboard](#stats-dashboard). The retention, performance, SQL, and schema sections further down are reference material for advanced users who want to inspect or tune the database - you can safely skip them.
 :::

 Episode completion for local `watched` state uses the shared `DEFAULT_MIN_WATCH_RATIO` (`85%`) value from `src/shared/watch-threshold.ts`.
@@ -18,13 +18,14 @@ Episode completion for local `watched` state uses the shared `DEFAULT_MIN_WATCH_
 {
  "immersionTracking": {
    "enabled": true,
-    "dbPath": ""
-  }
+    "dbPath": "",
+  },
 }
 ```

 - Leave `dbPath` empty to use the default location (`immersion.sqlite` in SubMiner's app-data directory).
 - Set an explicit path to move the database (useful for backups, cloud syncing, or external tools).
+- To share stats and watch history between two machines, use [`subminer sync <host>`](/launcher-script#sync-between-machines) instead of file-level cloud sync — it merges both databases without one side overwriting the other.

 ## Stats Dashboard

@@ -48,13 +49,19 @@ Recent sessions, streak calendar, watch-time history, and a tracking snapshot wi

 Cover-art library with search and sorting, per-series progress, episode drill-down, and direct links into mined cards.

+Local files and Jellyfin items with detected season numbers are split into season-specific library entries, so `Season 1` and `Season 2` folders do not merge into one show card.
+
+When older stats already grouped multiple seasons under one series entry, SubMiner moves parsed episodes into the season-specific entries on startup and rebuilds the affected summaries.
+
+Jellyfin stream URLs are normalized to stable item links before stats titles are shown, so playback query parameters are not displayed in the dashboard.
+
 When YouTube channel metadata is available, the Library tab groups videos by creator/channel and treats each tracked video as an episode-like entry inside that channel section.

 ![Stats Library](/screenshots/stats-library.png)

 #### Trends

-Watch time, sessions, words seen, and per-anime progress/pattern charts with configurable date ranges and grouping.
+Grouped into Activity (per-day/month watch time, cards, words, sessions), Cumulative Totals (running totals incl. new words seen and episodes), Efficiency (words/min, cards/hour, lookups per 100 words), Patterns (watch time by day of week and hour), and per-anime Library charts — all with configurable date ranges and grouping.

 ![Stats Trends](/screenshots/stats-trends.png)

@@ -66,10 +73,14 @@ Expandable session history with new-word activity, cumulative totals, and pause/

 #### Vocabulary

-Top repeated words (click a bar to open the word), new-word timeline, frequency rank table with full readings, kanji breakdown, word exclusion list, and click-through occurrence drilldown with Mine Word / Mine Sentence / Mine Audio buttons.
+Top repeated words (click a bar to open the word), new-word timeline, cross-title and frequency rank tables with Hide Known / Hide Kana filters, kanji breakdown, word exclusion list, and click-through occurrence drilldown with Mine Word / Mine Sentence / Mine Audio buttons.

 ![Stats Vocabulary](/screenshots/stats-vocabulary.png)

+#### Search
+
+Realtime search across tracked primary subtitle lines and media titles. Results show the source media, session, line number, timing, and sentence text. Secondary subtitle text is not shown or searched here because separate subtitle tracks may not line up sentence-for-sentence. Sentence cards can be mined from any result with a valid local source and timing. Word and audio card buttons appear only when the searched word exactly appears in the primary sentence text; matching text is highlighted in the result.
+
 Stats server config lives under `stats`:

 ```jsonc
@@ -78,14 +89,14 @@ Stats server config lives under `stats`:
    "toggleKey": "Backquote",
    "serverPort": 6969,
    "autoStartServer": true,
-    "autoOpenBrowser": false
-  }
+    "autoOpenBrowser": false,
+  },
 }
 ```

 - `toggleKey` is overlay-local, not a system-wide shortcut.
 - `serverPort` controls the localhost dashboard URL.
- `autoStartServer` starts the local stats HTTP server on launch once immersion tracking is active, or reuses the dedicated background stats server when one is already running.
+- `autoStartServer` starts the local stats HTTP server on launch once immersion tracking is active, or reuses the dedicated background stats server when one is already running. Background app launches (`subminer app`) start the stats server immediately, registering it so later launches reuse it instead of starting another one.
 - `autoOpenBrowser` controls whether `subminer stats` launches the dashboard URL in your browser after ensuring the server is running.
 - `subminer stats` forces the dashboard server to start even when `autoStartServer` is `false`.
 - `subminer stats -b` starts or reuses the dedicated background stats daemon and exits after startup acknowledgement.
@@ -96,15 +107,15 @@ Stats server config lives under `stats`:

 ## Mining Cards from the Stats Page

-The Vocabulary tab's word detail panel shows example lines from your viewing history. Each example line with a valid source file offers three mining buttons:
+The Search tab and the Vocabulary tab's word detail panel both mine from subtitle lines in your viewing history. Search matches sentence text and media titles, and **Search by headword** is enabled by default so dictionary-form searches such as `知らない` can find tracked subtitle lines with inflected variants. Turn that toggle off for exact text/title matching only. Each line with a valid source file offers sentence-card mining; word/audio mining is available when the selected word or searched word appears in the sentence:

- **Mine Word** — performs a full Yomitan dictionary lookup for the word (definition, reading, pitch accent, etc.) via a short-lived hidden helper, then enriches the card with sentence audio, a screenshot or animated AVIF clip, the highlighted sentence, and metadata extracted from the source video file. Requires Anki and Yomitan dictionaries to be loaded.
- **Mine Sentence** — creates a sentence card directly with the `IsSentenceCard` flag set (for Lapis/Kiku workflows), along with audio, image, and translation from the secondary subtitle if available.
- **Mine Audio** — creates an audio-only card with the `IsAudioCard` flag, attaching only the sentence audio clip.
+- **Mine Word** - performs a full Yomitan dictionary lookup for the word (definition, reading, pitch accent, etc.) via a short-lived hidden helper, then enriches the card with sentence audio, a screenshot or animated AVIF clip, the highlighted sentence, and metadata extracted from the source video file. Requires Anki and Yomitan dictionaries to be loaded.
+- **Mine Sentence** - creates a sentence card directly with the `IsSentenceCard` flag set (for Lapis/Kiku workflows), along with audio and image from the source video.
+- **Mine Audio** - creates an audio-only card with the `IsAudioCard` flag, attaching only the sentence audio clip.

 All three modes respect your `ankiConnect` config: deck, model, field mappings, media settings (static vs AVIF, quality, dimensions), audio padding, metadata pattern, and tags. Media generation runs in parallel for faster card creation.

-Secondary subtitle text (typically English translations) is stored alongside primary subtitles during playback and used as the translation field when mining from the stats page.
+Secondary subtitle text (typically English translations) is stored alongside primary subtitles during playback and can be used as the translation field when mining sentence cards from Search or vocabulary occurrences. The Search tab does not use that text for display or matching.

 ### Word Exclusion List

@@ -114,12 +125,12 @@ The Vocabulary tab toolbar includes an **Exclusions** button for hiding words fr

 By default, SubMiner keeps all retention tables and raw data (`0` means keep all) while continuing daily/monthly rollup maintenance:

-| Data type      | Retention |
-| -------------- | --------- |
-| Raw events     | 0 (keep all)   |
-| Telemetry      | 0 (keep all)   |
-| Sessions      | 0 (keep all)   |
-| Daily rollups  | 0 (keep all)   |
+| Data type       | Retention    |
+| --------------- | ------------ |
+| Raw events      | 0 (keep all) |
+| Telemetry       | 0 (keep all) |
+| Sessions        | 0 (keep all) |
+| Daily rollups   | 0 (keep all) |
 | Monthly rollups | 0 (keep all) |

 Maintenance runs on startup and every 24 hours. Vacuum runs only when `retention.vacuumIntervalDays` is non-zero.
@@ -146,24 +157,24 @@ The tracker is optimized for "keep everything" defaults:

 All policy options live under `immersionTracking` in your config:

-| Option | Description |
-| ------ | ----------- |
-| `batchSize` | Writes per flush batch |
-| `flushIntervalMs` | Max delay between flushes (default: 500ms) |
-| `queueCap` | Max queued writes before oldest are dropped |
-| `payloadCapBytes` | Max payload size per write |
-| `maintenanceIntervalMs` | How often maintenance runs |
-| `retention.eventsDays` | Raw event retention |
-| `retention.telemetryDays` | Telemetry retention |
-| `retention.sessionsDays` | Session retention |
-| `retention.dailyRollupsDays` | Daily rollup retention |
-| `retention.monthlyRollupsDays` | Monthly rollup retention |
-| `retention.vacuumIntervalDays` | Minimum spacing between vacuums |
-| `retentionMode` | `preset` or `advanced` |
-| `retentionPreset` | `minimal`, `balanced`, or `deep-history` (used by `retentionMode`) |
-| `lifetimeSummaries.global` | Maintain global lifetime totals |
-| `lifetimeSummaries.anime` | Maintain per-anime lifetime totals |
-| `lifetimeSummaries.media` | Maintain per-media lifetime totals |
+| Option                         | Description                                                        |
+| ------------------------------ | ------------------------------------------------------------------ |
+| `batchSize`                    | Writes per flush batch                                             |
+| `flushIntervalMs`              | Max delay between flushes (default: 500ms)                         |
+| `queueCap`                     | Max queued writes before oldest are dropped                        |
+| `payloadCapBytes`              | Max payload size per write                                         |
+| `maintenanceIntervalMs`        | How often maintenance runs                                         |
+| `retention.eventsDays`         | Raw event retention                                                |
+| `retention.telemetryDays`      | Telemetry retention                                                |
+| `retention.sessionsDays`       | Session retention                                                  |
+| `retention.dailyRollupsDays`   | Daily rollup retention                                             |
+| `retention.monthlyRollupsDays` | Monthly rollup retention                                           |
+| `retention.vacuumIntervalDays` | Minimum spacing between vacuums                                    |
+| `retentionMode`                | `preset` or `advanced`                                             |
+| `retentionPreset`              | `minimal`, `balanced`, or `deep-history` (used by `retentionMode`) |
+| `lifetimeSummaries.global`     | Maintain global lifetime totals                                    |
+| `lifetimeSummaries.anime`      | Maintain per-anime lifetime totals                                 |
+| `lifetimeSummaries.media`      | Maintain per-media lifetime totals                                 |

 ## Query Templates

@@ -281,11 +292,11 @@ LIMIT ?;

 Core tables:

- `imm_videos` — video key/title/source metadata
- `imm_sessions` — session UUID, video reference, timing/status, final denormalized totals
- `imm_session_telemetry` — high-frequency session aggregates over time
- `imm_session_events` — event stream with compact numeric event types
- `imm_subtitle_lines` — persisted subtitle text and timing per session/video
+- `imm_videos` - video key/title/source metadata
+- `imm_sessions` - session UUID, video reference, timing/status, final denormalized totals
+- `imm_session_telemetry` - high-frequency session aggregates over time
+- `imm_session_events` - event stream with compact numeric event types
+- `imm_subtitle_lines` - persisted subtitle text and timing per session/video

 Lifetime summary tables:

@@ -306,5 +317,5 @@ Vocabulary tables:

 Media-art tables:

- `imm_media_art` — per-video cover metadata plus shared blob reference
- `imm_cover_art_blobs` — deduplicated image bytes keyed by blob hash
+- `imm_media_art` - per-video cover metadata plus shared blob reference
+- `imm_cover_art_blobs` - deduplicated image bytes keyed by blob hash
@@ -24,7 +24,7 @@ features:
      src: /assets/mpv.svg
      alt: mpv icon
    title: Built for mpv
-    details: Tracks subtitles via mpv IPC in real time. Launch with the wrapper script or the mpv plugin — no external bridge needed.
+    details: Tracks subtitles via mpv IPC in real time. Launch with the wrapper script or the mpv plugin - no external bridge needed.
    link: /usage
    linkText: How it works
  - icon:
@@ -45,14 +45,14 @@ features:
      src: /assets/highlight.svg
      alt: Highlight icon
    title: Reading Annotations
-    details: N+1 targeting, character-name matching, frequency highlighting, and JLPT tagging — all layered on subtitle text in real time.
+    details: N+1 targeting, character-name matching, frequency highlighting, and JLPT tagging - all layered on subtitle text in real time.
    link: /subtitle-annotations
    linkText: Annotation details
  - icon:
      src: /assets/video.svg
      alt: Video playback icon
    title: YouTube Playback
-    details: Play YouTube URLs or ytsearch targets directly — SubMiner automatically selects and loads subtitles for the video.
+    details: Play YouTube URLs or ytsearch targets directly - SubMiner automatically selects and loads subtitles for the video.
    link: /usage#youtube-playback
    linkText: YouTube playback
  - icon:
@@ -66,14 +66,14 @@ features:
      src: /assets/subtitle-download.svg
      alt: Subtitle download icon
    title: Subtitle Download & Sync
-    details: Search and pull subtitles from Jimaku, then retime subtitles with alass or ffsubsync — all from the overlay.
+    details: Search and pull subtitles from Jimaku, then retime subtitles with alass or ffsubsync - all from the overlay.
    link: /jimaku-integration
    linkText: Jimaku integration
  - icon:
      src: /assets/tokenization.svg
      alt: Tracking chart icon
    title: Stats Dashboard
-    details: Browse session history, streak calendars, vocabulary frequency, and per-series progress in a local dashboard — then mine cards straight from your viewing history.
+    details: Browse session history, streak calendars, vocabulary frequency, and per-series progress in a local dashboard - then mine cards straight from your viewing history.
    link: /immersion-tracking
    linkText: Dashboard & tracking
  - icon:
@@ -1,42 +1,42 @@
 # Installation

-SubMiner is a desktop app that draws an interactive layer — an **overlay** — on top of the [mpv](https://mpv.io) video player. As you watch native Japanese media, you can click or hover any word in the subtitles to look it up, then turn it into an Anki flashcard without pausing to switch apps. Building flashcards from real content you're watching is called **sentence mining**, and it's what SubMiner is built for. It bundles its own copy of **Yomitan** (a pop-up dictionary) and talks to **AnkiConnect** (an add-on that lets other programs add cards to Anki) so cards get filled in automatically.
+SubMiner is a desktop app that draws an interactive layer - an **overlay** - on top of the [mpv](https://mpv.io) video player. As you watch native Japanese media, you can click or hover any word in the subtitles to look it up, then turn it into an Anki flashcard without pausing to switch apps. Building flashcards from real content you're watching is called **sentence mining**, and it's what SubMiner is built for. It bundles its own copy of **Yomitan** (a pop-up dictionary) and talks to **AnkiConnect** (an add-on that lets other programs add cards to Anki) so cards get filled in automatically.

 Three steps to get started:

-1. **Install requirements** — mpv and a few optional extras
-2. **Install SubMiner** — from the AUR, or download from GitHub Releases
-3. **Launch the app** — first-run setup walks you through dictionaries, the launcher, and everything else
+1. **Install requirements** - mpv and a few optional extras
+2. **Install SubMiner** - from the AUR, or download from GitHub Releases
+3. **Launch the app** - first-run setup walks you through dictionaries, the launcher, and everything else

 ## 1. Install Requirements

 Only **mpv** is strictly required to run SubMiner. Everything else enhances the experience but is optional.

-| Dependency           | Status      | What it does                                                                                                    |
-| -------------------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
-| mpv                  | Required    | The video player SubMiner overlays on. Must support `--input-ipc-server`.                                       |
-| ffmpeg               | Recommended | Audio extraction and screenshots for Anki cards. Without it SubMiner still runs, but media fields will be empty. |
+| Dependency           | Status      | What it does                                                                                                                                                   |
+| -------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| mpv                  | Required    | The video player SubMiner overlays on. Must support `--input-ipc-server`.                                                                                      |
+| ffmpeg               | Recommended | Audio extraction and screenshots for Anki cards. Without it SubMiner still runs, but media fields will be empty.                                               |
 | MeCab + mecab-ipadic | Recommended | Part-of-speech filtering for more precise N+1, JLPT, and frequency annotations. Without it annotations still render, but POS-based filtering is less accurate. |
-| yt-dlp               | Optional    | YouTube playback and subtitle extraction.                                                                       |
-| fzf                  | Optional    | Terminal-based video picker in the launcher.                                                                     |
-| rofi                 | Optional    | GUI-based video picker (Linux).                                                                                  |
-| chafa                | Optional    | Thumbnail previews in fzf.                                                                                       |
-| ffmpegthumbnailer    | Optional    | Video thumbnail generation for the picker.                                                                       |
-| guessit              | Optional    | Better AniSkip title/season/episode parsing.                                                                     |
-| alass                | Optional    | Subtitle sync engine (preferred). Disabled without alass or ffsubsync.                                           |
-| ffsubsync            | Optional    | Audio-based subtitle sync engine. Disabled without alass or ffsubsync.                                           |
-| fuse2                | Linux only  | Required to run the AppImage.                                                                                    |
+| yt-dlp               | Optional    | YouTube playback and subtitle extraction.                                                                                                                      |
+| fzf                  | Optional    | Terminal-based video picker in the launcher.                                                                                                                   |
+| rofi                 | Optional    | GUI-based video picker (Linux).                                                                                                                                |
+| chafa                | Optional    | Thumbnail previews in fzf.                                                                                                                                     |
+| ffmpegthumbnailer    | Optional    | Video thumbnail generation for the picker.                                                                                                                     |
+| guessit              | Optional    | Better AniSkip title/season/episode parsing.                                                                                                                   |
+| alass                | Optional    | Subtitle sync engine (preferred). Disabled without alass or ffsubsync.                                                                                         |
+| ffsubsync            | Optional    | Audio-based subtitle sync engine. Disabled without alass or ffsubsync.                                                                                         |
+| fuse2                | Linux only  | Required to run the AppImage.                                                                                                                                  |

 ### Linux

-**Window backend** — you need one of these depending on your compositor:
+**Window backend** - you need one of these depending on your compositor:

- **Hyprland** — native Wayland support (uses `hyprctl`)
- **Sway** — native Wayland support (uses `swaymsg`)
- **X11 / Xwayland** — for X11 sessions or any other Wayland compositor (uses `xdotool` and `xwininfo`)
+- **Hyprland** - native Wayland support (uses `hyprctl`)
+- **Sway** - native Wayland support (uses `swaymsg`)
+- **X11 / Xwayland** - for X11 sessions or any other Wayland compositor (uses `xdotool` and `xwininfo`)

 ::: warning Wayland support is compositor-specific
-Wayland has no universal API for window positioning — each compositor exposes its own IPC, so SubMiner needs a dedicated backend per compositor. Only Hyprland and Sway have native Wayland backends. If you run a different Wayland compositor (GNOME, KDE Plasma, river, etc.), both mpv **and** SubMiner must run under X11 or Xwayland. The `subminer` launcher handles this automatically when `--backend x11` is set or the X11 backend is auto-detected.
+Wayland has no universal API for window positioning - each compositor exposes its own IPC, so SubMiner needs a dedicated backend per compositor. Only Hyprland and Sway have native Wayland backends. If you run a different Wayland compositor (GNOME, KDE Plasma, river, etc.), both mpv **and** SubMiner must run under X11 or Xwayland. The `subminer` launcher handles this automatically when `--backend x11` is set or the X11 backend is auto-detected.
 :::

 <details>
@@ -69,7 +69,7 @@ sudo apt install yt-dlp fzf rofi chafa ffmpegthumbnailer
 sudo apt install xdotool x11-utils
 # Optional: subtitle sync
 pip install ffsubsync
-# alass is not in apt — install via cargo: cargo install alass-cli
+# alass is not in apt - install via cargo: cargo install alass-cli
 ```

 </details>
@@ -94,7 +94,7 @@ pip install ffsubsync

 ### macOS

-macOS 11 (Big Sur) or later. Accessibility permission — the macOS setting that lets one app observe and position another app's windows — is required so the overlay can follow the mpv window (see [step 2](#macos-dmg)).
+macOS 11 (Big Sur) or later. Accessibility permission - the macOS setting that lets one app observe and position another app's windows - is required so the overlay can follow the mpv window (see [step 2](#macos-dmg)).

 ```bash
 brew install mpv ffmpeg
@@ -111,7 +111,7 @@ pip install ffsubsync

 Windows 10 or later. Install [`mpv`](https://mpv.io/installation/) and [`ffmpeg`](https://ffmpeg.org/download.html) and ensure both are on `PATH`. Optionally install [MeCab for Windows](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary.

-No compositor tools or window helpers are needed — native window tracking is built in.
+No compositor tools or window helpers are needed - native window tracking is built in.

 ## 2. Install SubMiner

@@ -172,8 +172,8 @@ If you prefer to install it manually, see [manual launcher install](#manual-laun

 Download the latest installer from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest):

- `SubMiner-<version>.exe` — installer (recommended)
- `SubMiner-<version>-win.zip` — portable fallback
+- `SubMiner-<version>.exe` - installer (recommended)
+- `SubMiner-<version>-win.zip` - portable fallback

 Make sure `mpv.exe` is on your `PATH`, or set `mpv.executablePath` in the config during first-run setup.

@@ -185,7 +185,7 @@ Make sure `mpv.exe` is on your `PATH`, or set `mpv.executablePath` in the config
 ```bash
 git clone --recurse-submodules https://github.com/ksyasuda/SubMiner.git
 cd SubMiner
-bun install
+make deps
 bun run build

 # Optional: build AppImage
@@ -202,7 +202,7 @@ Bundled Yomitan is built during `bun run build`.
 ```bash
 git clone --recurse-submodules https://github.com/ksyasuda/SubMiner.git
 cd SubMiner
-git submodule update --init --recursive
+make deps
 make build-macos
 ```

@@ -216,14 +216,14 @@ The built app will be in the `release` directory (`.dmg` and `.zip`). For unsign
 ```powershell
 git clone https://github.com/ksyasuda/SubMiner.git
 cd SubMiner
+git submodule update --init --recursive
 bun install
-
-# Windows requires building texthooker-ui manually before the main build
-Set-Location vendor/texthooker-ui
+Set-Location stats
+bun install --frozen-lockfile
+Set-Location ../vendor/texthooker-ui
 bun install --frozen-lockfile
 bun run build
 Set-Location ../..
-
 bun run build:win
 ```

@@ -240,18 +240,18 @@ subminer app --setup
 # Linux (AppImage directly)
 ~/.local/bin/SubMiner.AppImage --setup

-# macOS — launch SubMiner.app from /Applications, or:
+# macOS - launch SubMiner.app from /Applications, or:
 subminer app --setup
 ```

-On **Windows**, just run `SubMiner.exe` — the setup wizard opens automatically on first launch.
+On **Windows**, just run `SubMiner.exe` - the setup wizard opens automatically on first launch.

 The setup wizard walks you through:

- **Config file** — auto-created at `~/.config/SubMiner/config.jsonc` (Linux/macOS) or `%APPDATA%\SubMiner\config.jsonc` (Windows)
- **Yomitan dictionaries** — import at least one dictionary so word lookups work
- **Bun + `subminer` launcher** _(optional)_ — installs the command-line launcher into a writable PATH directory
- **Windows shortcut** _(Windows only)_ — create a `SubMiner mpv` Start Menu/Desktop shortcut
+- **Config file** - auto-created at `~/.config/SubMiner/config.jsonc` (Linux/macOS) or `%APPDATA%\SubMiner\config.jsonc` (Windows)
+- **Yomitan dictionaries** - import at least one dictionary so word lookups work
+- **Bun + `subminer` launcher** _(optional)_ - installs the command-line launcher into a writable PATH directory
+- **Windows shortcut** _(Windows only)_ - create a `SubMiner mpv` Start Menu/Desktop shortcut

 The `Finish setup` button requires a config file and at least one Yomitan dictionary. Bun and the launcher are optional and never block setup completion.

@@ -268,7 +268,7 @@ subminer video.mkv

 You should see the overlay appear over mpv. If subtitles are loaded, they will appear as interactive text in the overlay.

-On **Windows**, the recommended way to play video is with the **SubMiner mpv** shortcut created during setup — double-click it, or drag a video file onto it.
+On **Windows**, the recommended way to play video is with the **SubMiner mpv** shortcut created during setup - double-click it, or drag a video file onto it.

 ### Verify Setup

@@ -285,7 +285,7 @@ This checks for the app binary, mpv, ffmpeg, config file, and socket path. Fix a
 If you plan to mine Anki cards:

 1. Install [Anki](https://apps.ankiweb.net/)
-2. Install [AnkiConnect](https://ankiweb.net/shared/info/2055492159) — open Anki → **Tools → Add-ons → Get Add-ons** → enter code `2055492159`
+2. Install [AnkiConnect](https://ankiweb.net/shared/info/2055492159) - open Anki → **Tools → Add-ons → Get Add-ons** → enter code `2055492159`
 3. Restart Anki and keep it running while using SubMiner

 AnkiConnect listens on `http://127.0.0.1:8765` by default. SubMiner connects automatically with no extra config needed.
@@ -300,25 +300,26 @@ subminer -u
 subminer --update
 ```

-SubMiner verifies AppImage, launcher, and rofi theme downloads against `SHA256SUMS.txt`. If the binary is in a protected path, SubMiner shows the exact command to run rather than elevating itself.
+SubMiner verifies AppImage, launcher, and Linux support-asset downloads against `SHA256SUMS.txt`. On Linux those support assets include the launcher-managed runtime plugin copy under `SubMiner/plugin/subminer` plus the rofi theme at `SubMiner/themes/subminer.rasi`. If the binary is in a protected path, SubMiner shows the exact command to run rather than elevating itself.

-The tray "Check for Updates" entry installs the new app automatically on Linux, macOS, and Windows. On Linux it replaces the running `.AppImage` in place via `electron-updater`; AppImages managed by a system package (for example the AUR `/opt/SubMiner/SubMiner.AppImage`) are skipped so the package manager stays in charge.
+The tray "Check for Updates" entry installs the new app automatically on Linux, macOS, and Windows. On Linux it replaces the running `.AppImage` in place via `electron-updater` and refreshes the managed support assets from `subminer-assets.tar.gz`; AppImages managed by a system package (for example the AUR `/opt/SubMiner/SubMiner.AppImage`) are skipped so the package manager stays in charge.

-`subminer -u` also performs the AppImage update directly from the launcher process, which is useful when SubMiner is not currently running.
+`subminer -u` also performs the AppImage, launcher, and managed support-asset updates directly from the launcher process, which is useful when SubMiner is not currently running.

 ## How It All Fits Together

 SubMiner is an overlay that sits on top of mpv. It connects to mpv through an IPC socket, renders subtitles as interactive text using a bundled Yomitan dictionary engine, and optionally creates Anki flashcards via AnkiConnect.

-The `subminer` launcher handles mpv IPC socket setup automatically. If you launch mpv yourself or from another tool, you must pass `--input-ipc-server=/tmp/subminer-socket` (or `\\.\pipe\subminer-socket` on Windows) — without it the overlay starts but subtitles won't appear.
+The `subminer` launcher handles mpv IPC socket setup automatically. If you launch mpv yourself or from another tool, you must pass `--input-ipc-server=/tmp/subminer-socket` (or `\\.\pipe\subminer-socket` on Windows) - without it the overlay starts but subtitles won't appear.

-The bundled mpv plugin is injected at runtime automatically — you don't need to install it separately. It provides in-player keybindings (the `y` chord) for controlling the overlay from within mpv. See [MPV Plugin](/mpv-plugin) for the full keybinding and configuration reference.
+The bundled mpv plugin is injected at runtime automatically - you don't need to install it separately. On Linux, the `subminer` launcher now checks for its managed runtime plugin copy and rofi theme before every mpv-managed launch and installs those support assets from the bundled app automatically if either one is missing. It provides in-player keybindings (the `y` chord) for controlling the overlay from within mpv. See [MPV Plugin](/mpv-plugin) for the full keybinding and configuration reference.

 ## Platform Notes

 ### macOS

 **MeCab paths (Homebrew):**
+
 - Apple Silicon (M1/M2): `/opt/homebrew/bin/mecab`
 - Intel: `/usr/local/bin/mecab`

@@ -330,7 +331,7 @@ Ensure `mecab` is available on your PATH when launching SubMiner.

 - The **SubMiner mpv** shortcut is the recommended way to launch playback. It starts `mpv.exe` with the right IPC socket and subtitle defaults.
 - First-run setup adds only `%LOCALAPPDATA%\SubMiner\bin` to the HKCU user PATH. It does not add `SubMiner.exe` to PATH.
- IPC socket on Windows is `\\.\pipe\subminer-socket` — do not use `/tmp/subminer-socket`.
+- IPC socket on Windows is `\\.\pipe\subminer-socket` - do not use `/tmp/subminer-socket`.
 - Config is stored at `%APPDATA%\SubMiner\config.jsonc`.

 ## Manual Launcher Install
@@ -361,17 +362,21 @@ sudo chmod +x /usr/local/bin/subminer

 ## Optional Extras

-### Rofi Theme (Linux Only)
+### Linux Support Assets

-SubMiner ships a custom rofi theme in the release assets:
+SubMiner ships the Linux rofi theme plus the launcher-managed runtime plugin copy in `subminer-assets.tar.gz`:

 ```bash
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
 tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
 mkdir -p ~/.local/share/SubMiner/themes
 cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi
+mkdir -p ~/.local/share/SubMiner/plugin
+cp -R /tmp/plugin/subminer ~/.local/share/SubMiner/plugin/subminer
 ```

-Override with `SUBMINER_ROFI_THEME=/absolute/path/to/theme.rasi`.
+`subminer -u` and the tray updater keep those Linux support assets in sync automatically once the `SubMiner` data dir exists. Normal Linux launcher playback also auto-installs the managed runtime plugin copy and rofi theme from the bundled app if either support asset is missing, so manual extraction is mainly useful for pre-seeding or custom setups.

-Next: [Usage](/usage) — learn about the `subminer` wrapper, keybindings, and YouTube playback.
+Override the theme path with `SUBMINER_ROFI_THEME=/absolute/path/to/theme.rasi`.
+
+Next: [Usage](/usage) - learn about the `subminer` wrapper, keybindings, and YouTube playback.
@@ -1,8 +1,8 @@
 # IPC + Runtime Contracts

-SubMiner's Electron app runs two isolated processes — main and renderer — that can only communicate through IPC channels. This boundary is intentional: the renderer is an untrusted surface (it loads Yomitan, renders user-controlled subtitle text, and runs in a Chromium sandbox), so every message crossing the bridge passes through a validation layer before it can reach domain logic.
+SubMiner's Electron app runs two isolated processes - main and renderer - that can only communicate through IPC channels. This boundary is intentional: the renderer is an untrusted surface (it loads Yomitan, renders user-controlled subtitle text, and runs in a Chromium sandbox), so every message crossing the bridge passes through a validation layer before it can reach domain logic.

-The contract system enforces this by making channel names, payload shapes, and validators co-located and co-evolved. A change to any IPC surface touches the contract, the validator, the preload bridge, and the handler in the same commit — drift between any of those layers is treated as a bug.
+The contract system enforces this by making channel names, payload shapes, and validators co-located and co-evolved. A change to any IPC surface touches the contract, the validator, the preload bridge, and the handler in the same commit - drift between any of those layers is treated as a bug.

 ## Message Flow

@@ -38,7 +38,7 @@ flowchart TB

 ## Runtime Sockets

-The renderer↔main bridge above lives *inside* the Electron app. A separate set of OS sockets connects the app to the other runtimes — mpv and the launcher/plugin. These carry no renderer payloads and bypass the contract/validator layer; they are command and property channels between processes.
+The renderer↔main bridge above lives *inside* the Electron app. A separate set of OS sockets connects the app to the other runtimes - mpv and the launcher/plugin. These carry no renderer payloads and bypass the contract/validator layer; they are command and property channels between processes.

 - **mpv IPC socket** (`/tmp/subminer-socket`, or `\\.\pipe\subminer-socket` on Windows): the `MpvIpcClient` in the main process connects here to send JSON commands and subscribe to playback/subtitle properties via `observe_property`. Created by mpv's `--input-ipc-server`.
 - **App control socket** (`/tmp/subminer-control-<uid>-<hash>.sock`, or a named pipe on Windows): the launcher and the mpv plugin send CLI-style commands (`--start`, `--show-visible-overlay`, `--texthooker`) to a running app here. It also dedupes a second `subminer` invocation into the existing instance instead of launching twice.
@@ -73,7 +73,7 @@ How these sockets are established during launch is covered in [Playback Startup
 | --- | --- |
 | `src/shared/ipc/contracts.ts` | Canonical channel names and payload type contracts. Single source of truth for both processes. |
 | `src/shared/ipc/validators.ts` | Runtime payload parsers and type guards. Every `invoke` payload is validated here before the handler runs. |
-| `src/preload.ts` | Renderer-side bridge. Exposes a typed API surface to the renderer — only approved channels are accessible. |
+| `src/preload.ts` | Renderer-side bridge. Exposes a typed API surface to the renderer - only approved channels are accessible. |
 | `src/main/ipc-runtime.ts` | Main-process handler registration and routing. Wires validated channels to domain handlers. |
 | `src/core/services/ipc.ts` | Service-level invoke handling. Applies guardrails (validation, error wrapping) before calling domain logic. |
 | `src/core/services/anki-jimaku-ipc.ts` | Integration-specific IPC boundary for Anki and Jimaku operations. |
@@ -81,19 +81,19 @@ How these sockets are established during launch is covered in [Playback Startup

 ## Contract Rules

-These rules exist to prevent a class of bugs where the renderer and main process silently disagree about message shapes — which surfaces as undefined fields, swallowed errors, or state corruption.
+These rules exist to prevent a class of bugs where the renderer and main process silently disagree about message shapes - which surfaces as undefined fields, swallowed errors, or state corruption.

 - **Use shared constants.** Channel names come from `contracts.ts`, never ad-hoc literal strings. This makes channels greppable and refactor-safe.
 - **Validate before handling.** Every `invoke` payload passes through `validators.ts` before reaching domain logic. This catches shape drift at the boundary instead of deep inside a service.
 - **Return structured failures.** Handlers return `{ ok: false, error: string }` on failure rather than throwing. The renderer can always distinguish success from failure without try/catch.
- **Keep payloads narrow.** Send only what the handler needs. Avoid passing entire state objects across the bridge — it couples the renderer to internal main-process structure.
+- **Keep payloads narrow.** Send only what the handler needs. Avoid passing entire state objects across the bridge - it couples the renderer to internal main-process structure.
 - **Co-evolve all layers.** When a payload shape changes, update `contracts.ts`, `validators.ts`, `preload.ts`, and the handler in the same commit. Partial updates are treated as bugs.

 ## Two Message Patterns

-**Invoke (request/response):** The renderer calls a typed bridge method and awaits a result. The main process validates the payload, runs the handler, and returns a structured response. Used for operations where the renderer needs a result — lookups, config reads, mining actions.
+**Invoke (request/response):** The renderer calls a typed bridge method and awaits a result. The main process validates the payload, runs the handler, and returns a structured response. Used for operations where the renderer needs a result - lookups, config reads, mining actions.

-**Fire-and-forget (send):** The renderer sends a message with no response. The main process validates and handles it silently. Malformed payloads are dropped. Used for notifications where the renderer doesn't need confirmation — UI state hints, focus events, position updates.
+**Fire-and-forget (send):** The renderer sends a message with no response. The main process validates and handles it silently. Malformed payloads are dropped. Used for notifications where the renderer doesn't need confirmation - UI state hints, focus events, position updates.

 ## Add a New IPC Action

@@ -108,7 +108,7 @@ These rules exist to prevent a class of bugs where the renderer and main process

 - Prefer runtime/domain composition via `src/main/runtime/composers/*` and `src/main/runtime/domains/*`. IPC handlers should delegate to composers rather than containing orchestration logic.
 - Route shared mutable state updates through transition helpers in `src/main/state.ts` for migrated domains. Direct mutation from IPC handlers bypasses invariant checks.
- Keep IPC handlers thin — they validate, delegate, and return. Business logic belongs in services.
+- Keep IPC handlers thin - they validate, delegate, and return. Business logic belongs in services.

 ## Troubleshooting

@@ -1,12 +1,12 @@
 # Jellyfin Integration

-[Jellyfin](https://jellyfin.org) is a free, self-hosted media server — think of it as your own private streaming service for video you own. If you keep your anime on a Jellyfin server, SubMiner can play episodes through mpv with the full mining overlay.
+[Jellyfin](https://jellyfin.org) is a free, self-hosted media server - think of it as your own private streaming service for video you own. If you keep your anime on a Jellyfin server, SubMiner can play episodes through mpv with the full mining overlay.

 ::: tip Who needs this?
 This page is only relevant if you already run (or have access to) a Jellyfin server. If you watch local files or YouTube, you can skip it. The in-app setup window (`subminer jellyfin`) is the easiest starting point.
 :::

-SubMiner can act as a **cast-to-device target** for Jellyfin (similar to jellyfin-mpv-shim). Sign in once, turn on discovery, and SubMiner shows up in the "Play on…" / cast menu of any Jellyfin app — web, phone, or TV. Pick an episode, cast it to SubMiner, and it plays in SubMiner's mpv window with the full overlay and Yomitan click-to-lookup.
+SubMiner can act as a **cast-to-device target** for Jellyfin (similar to jellyfin-mpv-shim). Sign in once, turn on discovery, and SubMiner shows up in the "Play on…" / cast menu of any Jellyfin app - web, phone, or TV. Pick an episode, cast it to SubMiner, and it plays in SubMiner's mpv window with the full overlay and Yomitan click-to-lookup.

 This is the recommended way to use Jellyfin with SubMiner. A terminal-only option is covered in [Launcher playback](#launcher-playback) at the end.

@@ -28,7 +28,7 @@ Open the tray menu and click **Configure Jellyfin**. In the window that opens, e

 On success, SubMiner:

- saves an encrypted session token — your password is never stored,
+- saves an encrypted session token - your password is never stored,
 - turns the Jellyfin integration on, and
 - remembers the server and username for next time.

@@ -38,12 +38,12 @@ Reopen this window any time to switch servers or **Logout**.

 Discovery is what makes SubMiner appear as a cast target. Two ways to enable it:

- **For the current session** — open the tray menu and tick **Jellyfin Discovery**. (This item appears once you've signed in.)
- **Automatically on every launch** — already on by default. After your first sign-in, SubMiner auto-connects to Jellyfin at startup, so the cast target is ready without touching the tray. You can change this under [Settings](#settings).
+- **For the current session** - open the tray menu and tick **Jellyfin Discovery**. (This item appears once you've signed in.)
+- **Automatically on every launch** - already on by default. After your first sign-in, SubMiner auto-connects to Jellyfin at startup, so the cast target is ready without touching the tray. You can change this under [Settings](#settings).

 ### 4. Cast from any Jellyfin app

-In the Jellyfin web UI or mobile app, start playing something, open the **cast / "Play on"** menu, and pick your device — SubMiner appears there named after your computer's hostname. Playback opens in SubMiner.
+In the Jellyfin web UI or mobile app, start playing something, open the **cast / "Play on"** menu, and pick your device - SubMiner appears there named after your computer's hostname. Playback opens in SubMiner.

 From then on, pause / resume / seek / stop and audio or subtitle track changes you make in the Jellyfin app are mirrored in SubMiner, and your watch progress syncs back to Jellyfin (now-playing and resume position).

@@ -63,7 +63,7 @@ All Jellyfin options live under **Settings → Integrations → Jellyfin** (open
 | Setting                         | Default | What it does                                                                                                          |
 | ------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
 | **Enabled**                     | Off     | Turns the Jellyfin integration on. Switched on for you when you sign in.                                              |
-| **Server Url**                  | —       | Your Jellyfin server. Filled in when you sign in.                                                                     |
+| **Server Url**                  | -       | Your Jellyfin server. Filled in when you sign in.                                                                     |
 | **Remote Control Enabled**      | On      | Lets SubMiner act as a cast target.                                                                                   |
 | **Remote Control Auto Connect** | On      | Connects to Jellyfin at startup so discovery is automatic. Turn off if you'd rather start it from the tray each time. |
 | **Auto Announce**               | Off     | Re-broadcasts visibility on connect. Enable if your device is slow to appear in the cast menu.                        |
@@ -88,14 +88,14 @@ See [Configuration](/configuration) for the full list (transcode codec, direct-p
 **SubMiner doesn't appear in the cast menu**

 - Make sure SubMiner is running.
- Make sure you're signed in — reopen **Configure Jellyfin** and log in again if your token expired.
+- Make sure you're signed in - reopen **Configure Jellyfin** and log in again if your token expired.
 - Make sure discovery is on (tray **Jellyfin Discovery**, or **Remote Control Auto Connect** in settings).
 - Make sure SubMiner and the Jellyfin client point at the same server.

 **Casting starts but nothing plays**

 - Confirm the item plays normally in another Jellyfin client.
- If mpv was closed, give it a moment — SubMiner launches it on demand and retries.
+- If mpv was closed, give it a moment - SubMiner launches it on demand and retries.

 **SubMiner keeps disconnecting**

@@ -104,7 +104,7 @@ See [Configuration](/configuration) for the full list (transcode codec, direct-p
 ## Security notes

 - The Jellyfin session (access token + user ID) is kept in SubMiner's local encrypted token storage. Your password is used only to log in and is never saved.
- Treat the token storage and your `config.jsonc` as secrets — don't commit them.
+- Treat the token storage and your `config.jsonc` as secrets - don't commit them.
 - Advanced/headless: the `SUBMINER_JELLYFIN_ACCESS_TOKEN` and `SUBMINER_JELLYFIN_USER_ID` environment variables can supply a session without the sign-in window.

 ## Launcher playback
@@ -1,6 +1,6 @@
 # Jimaku Integration

-[Jimaku](https://jimaku.cc) is a community-driven subtitle repository for anime — a shared online library of subtitle files contributed by other learners. SubMiner integrates with the Jimaku API so you can search, browse, and download Japanese subtitle files directly from the overlay — no alt-tabbing or manual file management required. Downloaded subtitles are loaded into mpv immediately.
+[Jimaku](https://jimaku.cc) is a community-driven subtitle repository for anime - a shared online library of subtitle files contributed by other learners. SubMiner integrates with the Jimaku API so you can search, browse, and download Japanese subtitle files directly from the overlay - no alt-tabbing or manual file management required. Downloaded subtitles are loaded into mpv immediately.

 ::: tip Prerequisite: a free API key
 You need a Jimaku account and an API key (a personal access string) before this feature works. Create an account at [jimaku.cc](https://jimaku.cc), copy your key, and add it to your config as shown under [Configuration](#configuration) below. Without a key, the search modal will report "Jimaku API key not set."
@@ -10,14 +10,14 @@ You need a Jimaku account and an API key (a personal access string) before this

 The Jimaku integration runs through an in-overlay modal accessible via a keyboard shortcut (`Ctrl+Shift+J` by default).

-When you open the modal, SubMiner parses the current video filename to extract a title, season, and episode number. Common naming conventions are supported — `S01E03`, `1x03`, `E03`, and dash-separated episode numbers all work. If the filename yields a high-confidence match (title + episode), SubMiner auto-searches immediately.
+When you open the modal, SubMiner parses the current video filename to extract a title, season, and episode number. Common naming conventions are supported - `S01E03`, `1x03`, `E03`, and dash-separated episode numbers all work. If the filename yields a high-confidence match (title + episode), SubMiner auto-searches immediately.

 From there:

-1. **Search** — SubMiner queries the Jimaku API with the parsed title. Results appear as a list of anime entries (Japanese and English names).
-2. **Browse entries** — Select an entry to load its available subtitle files, filtered by episode if one was detected.
-3. **Browse files** — Files show name, size, and last-modified date. If a language preference is configured, files are sorted accordingly (e.g., Japanese-tagged files first).
-4. **Download** — Selecting a file downloads it to the same directory as the video (or a temp directory for remote/streamed media) and loads it into mpv as a new subtitle track.
+1. **Search** - SubMiner queries the Jimaku API with the parsed title. Results appear as a list of anime entries (Japanese and English names).
+2. **Browse entries** - Select an entry to load its available subtitle files, filtered by episode if one was detected.
+3. **Browse files** - Files show name, size, and last-modified date. If a language preference is configured, files are sorted accordingly (e.g., Japanese-tagged files first).
+4. **Download** - Selecting a file downloads it to the same directory as the video (or a temp directory for remote/streamed media) and loads it into mpv as a new subtitle track.

 If no files match the current episode filter, a "Show all files" button lets you broaden the search to all episodes for that entry.

@@ -48,8 +48,8 @@ Add a `jimaku` section to your `config.jsonc`:

 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `jimaku.apiKey` | `string` | — | Jimaku API key (plaintext). Mutually exclusive with `apiKeyCommand`. |
-| `jimaku.apiKeyCommand` | `string` | — | Shell command that prints the API key to stdout. Useful for secret managers (e.g., `pass jimaku/api-key`). |
+| `jimaku.apiKey` | `string` | - | Jimaku API key (plaintext). Mutually exclusive with `apiKeyCommand`. |
+| `jimaku.apiKeyCommand` | `string` | - | Shell command that prints the API key to stdout. Useful for secret managers (e.g., `pass jimaku/api-key`). |
 | `jimaku.apiBaseUrl` | `string` | `"https://jimaku.cc"` | Base URL for the Jimaku API. Only change this if using a mirror or local instance. |
 | `jimaku.languagePreference` | `"ja"` \| `"en"` \| `"none"` | `"ja"` | Sort subtitle files by language tag. `"ja"` pushes Japanese-tagged files to the top; `"en"` does the same for English. `"none"` preserves the API order. |
 | `jimaku.maxEntryResults` | `number` | `10` | Maximum number of anime entries returned per search. |
@@ -68,8 +68,8 @@ The keyboard shortcut is configured separately under `shortcuts`:

 An API key is required to use the Jimaku integration. You can get one from [jimaku.cc](https://jimaku.cc). There are two ways to provide it:

- **`apiKey`** — set the key directly in config. Simple, but the key is stored in plaintext.
- **`apiKeyCommand`** — a shell command that outputs the key. Runs with a 10-second timeout. Preferred if you use a secret manager like `pass`, `gpg`, or a keychain tool.
+- **`apiKey`** - set the key directly in config. Simple, but the key is stored in plaintext.
+- **`apiKeyCommand`** - a shell command that outputs the key. Runs with a 10-second timeout. Preferred if you use a secret manager like `pass`, `gpg`, or a keychain tool.

 If both are set, `apiKey` takes priority.

@@ -79,8 +79,8 @@ SubMiner extracts media info from the current video path to pre-fill the search

 - **Season + episode patterns:** `S01E03`, `1x03`
 - **Episode-only patterns:** `E03`, `EP03`, or dash-separated numbers like `Title - 03 -`
- **Bracket tags:** `[SubGroup]`, `[1080p]`, `[HEVC]` — stripped before title extraction
- **Year tags:** `(2024)` — stripped
+- **Bracket tags:** `[SubGroup]`, `[1080p]`, `[HEVC]` - stripped before title extraction
+- **Year tags:** `(2024)` - stripped
 - **Dots and underscores:** treated as spaces
 - **Remote/streamed URLs:** SubMiner checks URL query parameters (`title`, `name`, `q`) and path segments to extract a meaningful title

@@ -98,7 +98,7 @@ The Jimaku API has rate limits. If you see 429 errors, wait for the retry durati

 **No entries found**

-Try simplifying the title — remove season/episode qualifiers and search with just the anime name. Jimaku's search matches against its own database of anime titles, so the exact spelling matters.
+Try simplifying the title - remove season/episode qualifiers and search with just the anime name. Jimaku's search matches against its own database of anime titles, so the exact spelling matters.

 **No files found for this episode**

@@ -110,6 +110,6 @@ Verify mpv is running and connected via IPC. SubMiner loads the subtitle by issu

 ## Related

- [Configuration Reference](/configuration#jimaku) — full config options
- [Mining Workflow](/mining-workflow#jimaku-subtitle-search) — how Jimaku fits into the sentence mining loop
- [Troubleshooting](/troubleshooting#jimaku) — additional error guidance
+- [Configuration Reference](/configuration#jimaku) - full config options
+- [Mining Workflow](/mining-workflow#jimaku-subtitle-search) - how Jimaku fits into the sentence mining loop
+- [Troubleshooting](/troubleshooting#jimaku) - additional error guidance
@@ -3,7 +3,7 @@
 The `subminer` launcher is an all-in-one script that handles video selection, mpv startup, and overlay management. It is the recommended way to use SubMiner on Linux and macOS because it guarantees mpv is launched with the correct IPC socket and SubMiner defaults. It's a Bun script distributed as a release asset alongside the AppImage and DMG.

 ::: tip Windows users
-On Windows, the recommended way to launch playback is the **SubMiner mpv** shortcut created during first-run setup — double-click it, drag a file onto it, or run `SubMiner.exe --launch-mpv` from a terminal. See [Windows mpv Shortcut](/usage#windows-mpv-shortcut) for details.
+On Windows, the recommended way to launch playback is the **SubMiner mpv** shortcut created during first-run setup - double-click it, drag a file onto it, or run `SubMiner.exe --launch-mpv` from a terminal. See [Windows mpv Shortcut](/usage#windows-mpv-shortcut) for details.
 :::

 ## Video Picker
@@ -34,15 +34,19 @@ subminer -R -r -d ~/Anime              # rofi picker, recursive
 subminer -R /directory                 # rofi picker, directory shortcut
 ```

-rofi shows a GUI menu with icon thumbnails when available. SubMiner ships a custom rofi theme bundled in the release assets tarball:
+rofi shows a GUI menu with icon thumbnails when available. SubMiner ships the rofi theme plus the Linux launcher-managed runtime plugin copy in the release assets tarball:

 ```bash
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
 tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
 mkdir -p ~/.local/share/SubMiner/themes
 cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi
+mkdir -p ~/.local/share/SubMiner/plugin
+cp -R /tmp/plugin/subminer ~/.local/share/SubMiner/plugin/subminer
 ```

+Once the `SubMiner` data dir exists, `subminer -u` refreshes both assets automatically. Normal Linux launcher playback also checks for the managed runtime plugin copy and rofi theme before mpv launch and installs them from the bundled app automatically if either one is missing.
+
 The theme is auto-detected from these paths (first match wins):

 - `$SUBMINER_ROFI_THEME` environment variable (absolute path)
@@ -57,6 +61,46 @@ Override with the `SUBMINER_ROFI_THEME` environment variable:
 SUBMINER_ROFI_THEME=/path/to/custom-theme.rasi subminer -R
 ```

+## Watch History
+
+`subminer -H` (or `--history`) browses your local watch history, sourced from the immersion tracker database. It works with both pickers: fzf by default, rofi with `-R -H`.
+
+```bash
+subminer -H                            # fzf history browser
+subminer -R -H                         # rofi history browser
+```
+
+The first menu lists every locally watched series, most recently watched first, using the parsed media title (e.g. the anime title) when available and the directory name otherwise. Selecting a series opens an action menu:
+
+- **Replay last watched** — replays the most recently watched episode
+- **Next episode** — plays the episode after the last watched one (continues into the next season directory when the season ends)
+- **Browse episodes** — lists the video files in the series directory in episode order, using the same fzf/rofi episode picker as directory browsing; if the series has multiple season directories, a season menu is shown first
+
+Series whose directories are not currently accessible (e.g. an unmounted network share) are hidden from the list. Watch history requires the immersion tracker database (`immersionTracking.dbPath`, default `<config dir>/immersion.sqlite`), which SubMiner populates during playback.
+
+## Sync Between Machines
+
+`subminer sync <host>` merges immersion stats and watch history between two machines over SSH, so both end up with the union of sessions, lifetime totals, vocabulary counts, daily/monthly charts, and `--history` entries. `<host>` is anything `ssh` accepts (`user@hostname` or an ssh config alias); SubMiner must be installed on both machines at the same version.
+
+```bash
+subminer sync macbook                  # two-way sync with the host "macbook"
+subminer sync user@192.168.1.20       # explicit user@host
+subminer sync macbook --remote-cmd ~/bin/subminer  # custom remote launcher path
+```
+
+How it works: each side takes a consistent snapshot of its database (`VACUUM INTO`), the snapshots are exchanged over `scp`, and each machine merges the other's snapshot into its own database. The merge is an insert-only union keyed on stable identifiers (session UUIDs, video keys, series title keys, word/kanji identity), so it is safe to re-run at any time — syncing twice changes nothing, and nothing is ever overwritten or summed twice. Lifetime totals and rollup charts are updated incrementally, so history older than the session retention window is preserved on both sides.
+
+Close SubMiner (and stop the background stats daemon, `subminer stats -s`) on both machines before syncing; the command refuses to run while a SubMiner process may be writing the database (`--force` overrides). Both machines must be on the same SubMiner version — the sync aborts on a stats schema mismatch.
+
+Two lower-level modes are used internally over SSH and also work standalone for manual transfers (e.g. via a USB drive):
+
+```bash
+subminer sync --snapshot /tmp/stats.sqlite   # write a consistent snapshot of the local database
+subminer sync --merge /tmp/stats.sqlite      # merge a snapshot file into the local database
+```
+
+Unfinished sessions (a crash mid-playback) are skipped until the app finalizes them; they sync on the next run. Word/kanji "known" state from Anki is not part of the database and does not sync — each machine derives it from its own Anki collection.
+
 ## Common Commands

 ```bash
@@ -79,12 +123,13 @@ subminer stats -b                       # start background stats daemon
 | `subminer stats cleanup`                   | Backfill vocabulary metadata and prune stale rows                  |
 | `subminer doctor`                          | Dependency + config + socket diagnostics                           |
 | `subminer settings`                        | Open the SubMiner settings window                                  |
-| `subminer logs -e`                         | Export a sanitized log ZIP and print its path                      |
+| `subminer logs -e`                         | Export a sanitized local-date log ZIP and print its path           |
 | `subminer config path`                     | Print active config file path                                      |
 | `subminer config show`                     | Print active config contents                                       |
 | `subminer mpv status`                      | Check mpv socket readiness                                         |
 | `subminer mpv socket`                      | Print active socket path                                           |
 | `subminer mpv idle`                        | Launch detached idle mpv instance                                  |
+| `subminer sync <host>`                     | Two-way stats/history sync with another machine over SSH           |
 | `subminer dictionary <path>`               | Generate character dictionary ZIP from file/dir target             |
 | `subminer dictionary --candidates <path>`  | List AniList candidate matches for character dictionary correction |
 | `subminer dictionary --select <id> <path>` | Pin an AniList media ID for that target series                     |
@@ -101,6 +146,7 @@ Use `subminer <subcommand> -h` for command-specific help.
 | `-d, --directory`     | Video search directory (default: cwd)                                |
 | `-r, --recursive`     | Search directories recursively                                       |
 | `-R, --rofi`          | Use rofi instead of fzf                                              |
+| `-H, --history`       | Browse local watch history (see [Watch History](#watch-history))     |
 | `--setup`             | Open first-run setup popup manually                                  |
 | `-v, --version`       | Print installed SubMiner version                                     |
 | `-u, --update`        | Check for SubMiner updates and update the app/launcher when possible |
@@ -113,7 +159,7 @@ Use `subminer <subcommand> -h` for command-specific help.
 | `--log-level`         | Logger verbosity (`debug`, `info`, `warn`, `error`)                  |
 | `--dev`, `--debug`    | Enable app dev-mode (not tied to log level)                          |

-On Linux, `subminer -u` updates from the launcher process itself. It can check and replace the AppImage, launcher, and rofi theme even when SubMiner is already running in the tray.
+On Linux, `subminer -u` updates from the launcher process itself. It can check and replace the AppImage, launcher, runtime plugin copy, and rofi theme even when SubMiner is already running in the tray.

 With default plugin settings (`auto_start=yes`, `auto_start_visible_overlay=yes`, `auto_start_pause_until_ready=yes`), explicit start flags are usually unnecessary.

@@ -121,4 +167,4 @@ With default plugin settings (`auto_start=yes`, `auto_start_visible_overlay=yes`

 - Default log level is `info`
 - `--background` mode defaults to `warn` unless `--log-level` is explicitly set
- `--dev` / `--debug` control app behavior, not logging verbosity — use `--log-level` for that
+- `--dev` / `--debug` control app behavior, not logging verbosity - use `--log-level` for that
@@ -1,14 +1,14 @@
 # Mining Workflow

-This guide walks through the sentence mining loop — from watching a video to creating Anki cards with audio, screenshots, and context.
+This guide walks through the sentence mining loop - from watching a video to creating Anki cards with audio, screenshots, and context.

 ## Overview

-*Sentence mining* means turning real sentences you encounter while watching native video into Anki flashcards, so you learn vocabulary in the context where you actually met it. SubMiner automates the tedious parts of that loop.
+_Sentence mining_ means turning real sentences you encounter while watching native video into Anki flashcards, so you learn vocabulary in the context where you actually met it. SubMiner automates the tedious parts of that loop.

-SubMiner runs as a transparent overlay on top of mpv (the video player). As subtitles play, the overlay displays them as interactive text. You hover a word, trigger a Yomitan dictionary lookup with your configured lookup key/modifier, then create an Anki card with a single action. SubMiner automatically attaches the sentence, an audio clip, and a screenshot to that card — no manual copy-pasting or screen capturing.
+SubMiner runs as a transparent overlay on top of mpv (the video player). As subtitles play, the overlay displays them as interactive text. You hover a word, trigger a Yomitan dictionary lookup with your configured lookup key/modifier, then create an Anki card with a single action. SubMiner automatically attaches the sentence, an audio clip, and a screenshot to that card - no manual copy-pasting or screen capturing.

-> **Yomitan** is the popup dictionary that shows definitions when you hover or scan a word. **AnkiConnect** is the add-on that lets SubMiner talk to Anki. Both are set up during installation — see [Anki Integration](/anki-integration) if you have not configured them yet.
+> **Yomitan** is the popup dictionary that shows definitions when you hover or scan a word. **AnkiConnect** is the add-on that lets SubMiner talk to Anki. Both are set up during installation - see [Anki Integration](/anki-integration) if you have not configured them yet.

 ## Creating Anki Cards

@@ -39,7 +39,7 @@ If you prefer a hands-on approach (animecards-style), you can copy the current s
 1. Add a word via Yomitan as usual.
 2. Press `Ctrl/Cmd+C` to copy the current subtitle line to the clipboard.
   - For multiple lines: press `Ctrl/Cmd+Shift+C`, then a digit `1`–`9` to select how many recent subtitle lines to combine. The combined text is copied to the clipboard.
-3. Press `Ctrl/Cmd+V` to update the last-added card with the clipboard contents plus audio, image, and translation — the same fields auto-update would fill.
+3. Press `Ctrl/Cmd+V` to update the last-added card with the clipboard contents plus audio, image, and translation - the same fields auto-update would fill.

 Manual clipboard updates always replace generated sentence audio, even when `ankiConnect.behavior.overwriteAudio` is disabled. The word audio field is left unchanged because the word itself does not change in this flow.

@@ -61,7 +61,7 @@ Create a standalone sentence card without going through Yomitan:
 The sentence card uses the note type configured in `isLapis.sentenceCardModel` and always maps sentence/audio to `Sentence` and `SentenceAudio`.

 ::: warning Requires Lapis/Kiku note type
-Sentence card creation requires a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type and `ankiConnect.isLapis.enabled: true` in your config. See [Anki Integration — Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
+Sentence card creation requires a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type and `ankiConnect.isLapis.enabled: true` in your config. See [Anki Integration - Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
 :::

 ### 4. Mark as Audio Card
@@ -69,7 +69,7 @@ Sentence card creation requires a [Lapis](https://github.com/donkuri/lapis) or [
 After adding a word via Yomitan, press the audio card shortcut to overwrite the audio with a longer clip spanning the full subtitle timing.

 ::: warning Requires Lapis/Kiku note type
-Audio card marking requires a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type and `ankiConnect.isLapis.enabled: true` in your config. See [Anki Integration — Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
+Audio card marking requires a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type and `ankiConnect.isLapis.enabled: true` in your config. See [Anki Integration - Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
 :::

 ### Field Grouping (Kiku)
@@ -82,11 +82,11 @@ If you mine the same word from different sentences, SubMiner can merge the cards
   - **Auto mode** (`ankiConnect.isKiku.fieldGrouping: "auto"`): Merges automatically. Both sentences, audio clips, and images are combined into the existing card. The duplicate is optionally deleted.
   - **Manual mode** (`ankiConnect.isKiku.fieldGrouping: "manual"`): A modal appears showing both cards side by side. You choose which card to keep and preview the merged result before confirming.

-See [Anki Integration — Field Grouping](/anki-integration#field-grouping-kiku) for configuration options, merge behavior, and modal keyboard shortcuts.
+See [Anki Integration - Field Grouping](/anki-integration#field-grouping-kiku) for configuration options, merge behavior, and modal keyboard shortcuts.

 ## Overlay Model

-SubMiner uses one overlay window with modal surfaces. It carries two subtitle bars — a primary reading bar and a secondary translation/context bar — plus modal dialogs that open on top.
+SubMiner uses one overlay window with modal surfaces. It carries two subtitle bars - a primary reading bar and a secondary translation/context bar - plus modal dialogs that open on top.

 Toggle the entire overlay window with `Alt+Shift+O` (global) or `y-t` (mpv plugin).

@@ -99,14 +99,14 @@ The primary bar renders subtitles as tokenized hoverable word spans. Each word i
 - Auto pause/resume while the Yomitan popup is open (enabled by default via `subtitleStyle.autoPauseVideoOnYomitanPopup`)
 - Right-click to pause/resume
 - Right-click + drag to reposition subtitles
- **Reading annotations** — known words, N+1 targets, character-name matches, JLPT levels, and frequency hits can all be visually highlighted
+- **Reading annotations** - known words, N+1 targets, character-name matches, JLPT levels, and frequency hits can all be visually highlighted

 ### Secondary Subtitle Bar

 The secondary bar is a compact top-strip region in the same overlay window. It shows a secondary subtitle track (typically English) for translation/context while keeping the primary reading flow below. It is useful for:

 - Quick comprehension checks without leaving the mining flow.
- Auto-populating the translation field on mined cards — when a card is created, SubMiner uses the secondary subtitle text as the translation field value (unless AI translation is configured to override it).
+- Auto-populating the translation field on mined cards - when a card is created, SubMiner uses the secondary subtitle text as the translation field value (unless AI translation is configured to override it).

 It is controlled by `secondarySub` configuration and shares its lifecycle with the main overlay window. Cycle which track feeds it with `Shift+J`.

@@ -114,18 +114,18 @@ It is controlled by `secondarySub` configuration and shares its lifecycle with t

 Both the primary and secondary subtitle bars share the same three visibility modes, and each can be changed independently at runtime:

- **Hidden** — the bar is not shown.
- **Visible** — the bar is always shown.
- **Hover** — the bar is revealed only while you hover over the overlay.
+- **Hidden** - the bar is not shown.
+- **Visible** - the bar is always shown.
+- **Hover** - the bar is revealed only while you hover over the overlay.

 By default the **primary** bar is `visible` (`subtitleStyle.primaryDefaultMode`) and the **secondary** bar is `hover` (`secondarySub.defaultMode`).

 Cycle each bar's mode at runtime with its own shortcut:

-| Shortcut             | Action                                                   | Config key                     |
-| -------------------- | -------------------------------------------------------- | ------------------------------ |
-| `V`                  | Cycle primary subtitle mode (hidden → visible → hover)   | overlay-local                  |
-| `Ctrl/Cmd+Shift+V`   | Cycle secondary subtitle mode (hidden → visible → hover) | `shortcuts.toggleSecondarySub` |
+| Shortcut           | Action                                                   | Config key                     |
+| ------------------ | -------------------------------------------------------- | ------------------------------ |
+| `V`                | Cycle primary subtitle mode (hidden → visible → hover)   | overlay-local                  |
+| `Ctrl/Cmd+Shift+V` | Cycle secondary subtitle mode (hidden → visible → hover) | `shortcuts.toggleSecondarySub` |

 ### Modal Surfaces

@@ -133,7 +133,7 @@ Jimaku search, field-grouping, runtime options, and manual subsync open as modal

 ## Looking Up Words

-1. Hover over the subtitle area — the overlay activates pointer events.
+1. Hover over the subtitle area - the overlay activates pointer events.
 2. Hover the word you want. SubMiner keeps per-token boundaries so Yomitan can target that token cleanly.
 3. Trigger Yomitan lookup with your configured lookup key/modifier (for example `Shift` if that is how your Yomitan profile is set up).
 4. Yomitan opens its lookup popup for the hovered token.
@@ -143,17 +143,17 @@ Jimaku search, field-grouping, runtime options, and manual subsync open as modal

 With a gamepad connected and keyboard-only mode enabled, the full mining loop works without a mouse or keyboard:

-1. **Navigate** — push the left stick left/right to move the token highlight across subtitle words.
-2. **Look up** — press `A` to trigger Yomitan lookup on the highlighted word.
-3. **Browse the popup** — push the left stick up/down to smooth-scroll through the Yomitan popup, or use the right stick for larger jumps.
-4. **Cycle audio** — press `R1` to move to the next dictionary audio entry, `L1` to play the current one.
-5. **Mine** — press `X` to create an Anki card for the current sentence (same as `Ctrl+S`).
-6. **Close** — press `B` to dismiss the Yomitan popup and return to subtitle navigation.
-7. **Pause/resume** — press `L3` (left stick click) to toggle mpv pause at any time.
+1. **Navigate** - push the left stick left/right to move the token highlight across subtitle words.
+2. **Look up** - press `A` to trigger Yomitan lookup on the highlighted word.
+3. **Browse the popup** - push the left stick up/down to smooth-scroll through the Yomitan popup, or use the right stick for larger jumps.
+4. **Cycle audio** - press `R1` to move to the next dictionary audio entry, `L1` to play the current one.
+5. **Mine** - press `X` to create an Anki card for the current sentence (same as `Ctrl+S`).
+6. **Close** - press `B` to dismiss the Yomitan popup and return to subtitle navigation.
+7. **Pause/resume** - press `L3` (left stick click) to toggle mpv pause at any time.

-After controller support is enabled, the controller and keyboard can be used interchangeably — switching mid-session is seamless. Toggle keyboard-only mode on or off with `Y` on the controller.
+After controller support is enabled, the controller and keyboard can be used interchangeably - switching mid-session is seamless. Toggle keyboard-only mode on or off with `Y` on the controller.

-See [Usage — Controller Support](/usage#controller-support) for setup details and [Configuration — Controller Support](/configuration#controller-support) for the full mapping and tuning options.
+See [Usage - Controller Support](/usage#controller-support) for setup details and [Configuration - Controller Support](/configuration#controller-support) for the full mapping and tuning options.

 ## Subtitle Sync (Subsync)

@@ -166,11 +166,13 @@ If your subtitle file is out of sync with the audio, SubMiner can resynchronize

 For remote streams, including Jellyfin playback, the modal only offers alass. Jellyfin subtitle URLs are cached as temporary subtitle files so alass can read them, but the video stream is not downloaded. ffsubsync needs direct access to the local media file and is unavailable for stream URLs.

-Install the sync tools separately — see [Troubleshooting](/troubleshooting#subtitle-sync-subsync) if the tools are not found.
+When you mine a sentence card from the stats dashboard, SubMiner can also use `alass` automatically to align a local English sidecar against the matching local Japanese sidecar before filling the card translation field. The source subtitle files are not modified; SubMiner writes a temporary retimed copy and reuses it while the stats server is running.
+
+Install the sync tools separately - see [Troubleshooting](/troubleshooting#subtitle-sync-subsync) if the tools are not found.

 ## Texthooker

-SubMiner runs a local HTTP server at `http://127.0.0.1:5174` (configurable port) that serves a texthooker UI. This allows external tools — such as a browser-based Yomitan instance — to receive subtitle text in real time.
+SubMiner runs a local HTTP server at `http://127.0.0.1:5174` (configurable port) that serves a texthooker UI. This allows external tools - such as a browser-based Yomitan instance - to receive subtitle text in real time.

 The texthooker page displays the current subtitle and updates as new lines arrive. This is useful if you prefer to do lookups in a browser rather than through the overlay's built-in Yomitan.

@@ -180,8 +182,8 @@ If you want to build your own browser client, websocket consumer, or automation

 These features support the mining loop but have their own dedicated pages:

- **[Jimaku subtitle search](/jimaku-integration)** — search and download anime subtitle files directly from the overlay (`Ctrl+Shift+J` by default), then load them into mpv.
- **[N+1 word highlighting](/subtitle-annotations#n1-word-highlighting)** — cross-reference your Anki decks to highlight known words, making true N+1 sentences (exactly one unknown word) easy to spot during immersion.
- **[Immersion tracking](/immersion-tracking)** — log watching and mining activity to a local database and view session times, words seen, and cards mined in the built-in stats dashboard.
+- **[Jimaku subtitle search](/jimaku-integration)** - search and download anime subtitle files directly from the overlay (`Ctrl+Shift+J` by default), then load them into mpv.
+- **[N+1 word highlighting](/subtitle-annotations#n1-word-highlighting)** - cross-reference your Anki decks to highlight known words, making true N+1 sentences (exactly one unknown word) easy to spot during immersion.
+- **[Immersion tracking](/immersion-tracking)** - log watching and mining activity to a local database and view session times, words seen, and cards mined in the built-in stats dashboard.

-Next: [Anki Integration](/anki-integration) — field mapping, media generation, and card enrichment configuration.
+Next: [Anki Integration](/anki-integration) - field mapping, media generation, and card enrichment configuration.
@@ -1,8 +1,8 @@
 # MPV Plugin

-**What this is:** mpv is the video player SubMiner overlays subtitles on. The SubMiner mpv plugin is a small Lua script that runs *inside* mpv and gives you in-player keybindings to control the SubMiner overlay (start/stop/toggle, skip intro, etc.) without leaving the player window.
+**What this is:** mpv is the video player SubMiner overlays subtitles on. The SubMiner mpv plugin is a small Lua script that runs _inside_ mpv and gives you in-player keybindings to control the SubMiner overlay (start/stop/toggle, skip intro, etc.) without leaving the player window.

-**Who needs this page:** Most users never touch the plugin directly — SubMiner-managed launches (the app, the `subminer` launcher, or the Windows shortcut) inject the bundled plugin automatically for that session, so there is nothing to install into mpv's global `scripts` directory. Read on if you launch mpv from another tool and want SubMiner's in-player controls, or you want to script mpv against SubMiner.
+**Who needs this page:** Most users never touch the plugin directly - SubMiner-managed launches (the app, the `subminer` launcher, or the Windows shortcut) inject the bundled plugin automatically for that session, so there is nothing to install into mpv's global `scripts` directory. Read on if you launch mpv from another tool and want SubMiner's in-player controls, or you want to script mpv against SubMiner.

 The plugin ships as a modular Lua package under `plugin/subminer/` (entry point `init.lua`, which loads `main.lua` and sibling modules). Earlier releases shipped a single global `main.lua`; runtime loading replaces it.

@@ -10,6 +10,8 @@ The plugin ships as a modular Lua package under `plugin/subminer/` (entry point

 Launch mpv through the SubMiner app, the `subminer` launcher, or the packaged Windows SubMiner mpv shortcut. These paths pass mpv a bundled plugin path for that playback session only, leaving regular mpv playback untouched.

+On Linux, the launcher-managed runtime plugin copy lives under the SubMiner data dir (`$XDG_DATA_HOME/SubMiner/plugin/subminer` by default, plus `/usr/local/share/SubMiner` or `/usr/share/SubMiner` for system installs). `subminer -u` and the tray updater keep that managed copy current. This is separate from mpv's global `scripts/` directory.
+
 If setup detects an older global SubMiner plugin in mpv's `scripts` directory, use **Remove legacy mpv plugin** in first-run setup. The global plugin is not needed once runtime loading is available.

 mpv must have IPC enabled for SubMiner to connect:
@@ -27,28 +29,28 @@ input-ipc-server=\\.\pipe\subminer-socket

 ## Keybindings

-Most plugin actions use a `y` chord prefix — press `y`, then the second key (a "chord"):
+Most plugin actions use a `y` chord prefix - press `y`, then the second key (a "chord"):

-| Chord            | Action                                 |
-| ---------------- | -------------------------------------- |
-| `y-y`            | Open menu                              |
-| `y-s`            | Start overlay                          |
-| `y-S`            | Stop overlay                           |
-| `y-t`            | Toggle visible overlay                 |
-| `y-o`            | Open settings window                   |
-| `y-r`            | Restart overlay                        |
-| `y-c`            | Check status                           |
-| `y-h`            | Open session help / keybinding modal   |
-| `v`              | Toggle primary subtitle bar visibility |
-| `TAB` (default)  | Skip intro (AniSkip)                   |
+| Chord           | Action                                 |
+| --------------- | -------------------------------------- |
+| `y-y`           | Open menu                              |
+| `y-s`           | Start overlay                          |
+| `y-S`           | Stop overlay                           |
+| `y-t`           | Toggle visible overlay                 |
+| `y-o`           | Open settings window                   |
+| `y-r`           | Restart overlay                        |
+| `y-c`           | Check status                           |
+| `y-h`           | Open session help / keybinding modal   |
+| `v`             | Toggle primary subtitle bar visibility |
+| `TAB` (default) | Skip intro (AniSkip)                   |

-The AniSkip key is **not** a `y` chord. It defaults to `TAB` and is configurable via `mpv.aniskipButtonKey`. The legacy `y-k` chord still works as a fallback unless you remap the AniSkip key onto it.
+The AniSkip key is **not** a `y` chord and is not bound by the plugin: the SubMiner app binds it over the mpv IPC socket while it is connected. It defaults to `TAB` and is configurable via `mpv.aniskipButtonKey`. The legacy `y-k` chord still works as a fallback unless you remap the AniSkip key onto it. See [AniSkip Integration](/aniskip-integration) for setup and details.

 The bare `v` binding is a forced mpv binding. It overrides mpv's default primary subtitle visibility toggle and routes the action to SubMiner's primary subtitle bar instead.

 ## Shared Shortcuts (Session Bindings)

-The `y-*` chords above are built into the plugin. Everything else you configure under [`shortcuts.*`](/shortcuts) — plus any custom [`keybindings`](/configuration) and the stats toggle/mark-watched keys — is **injected into mpv at runtime**, so the same shortcut works both inside mpv and in the SubMiner overlay. You do not edit any mpv config to enable them.
+The `y-*` chords above are built into the plugin. Everything else you configure under [`shortcuts.*`](/shortcuts) - plus any custom [`keybindings`](/configuration) and the stats toggle/mark-watched keys - is **injected into mpv at runtime**, so the same shortcut works both inside mpv and in the SubMiner overlay. You do not edit any mpv config to enable them.

 How it works:

@@ -58,11 +60,11 @@ How it works:

 Because the bindings come from the same configuration the overlay uses, you maintain one set of shortcuts for both surfaces.

-Live updates: changing a shortcut in the app rewrites `session-bindings.json` and sends the plugin a `subminer-reload-session-bindings` script message, so mpv re-registers the bindings immediately — no mpv restart required.
+Live updates: changing a shortcut in the app rewrites `session-bindings.json` and sends the plugin a `subminer-reload-session-bindings` script message, so mpv re-registers the bindings immediately - no mpv restart required.

 Notes:

- Accelerators are normalized per platform — `CommandOrControl` resolves to `Cmd` on macOS and `Ctrl` elsewhere.
+- Accelerators are normalized per platform - `CommandOrControl` resolves to `Cmd` on macOS and `Ctrl` elsewhere.
 - Multi-line actions (`copySubtitleMultiple`, `mineSentenceMultiple`) register temporary `1`–`9` digit follow-up bindings after the trigger key, with `Esc` to cancel.
 - If two shortcuts compile to the same key, or an accelerator can't be mapped to an mpv key, the app logs a warning and skips that binding instead of registering a broken one.

@@ -110,14 +112,14 @@ Packaged Windows plugin installs also rewrite `socket_path` to `\\.\pipe\submine

 When `backend=auto`, the plugin detects the window manager:

-1. **macOS** — detected via platform or `OSTYPE`.
-2. **Hyprland** — detected via `HYPRLAND_INSTANCE_SIGNATURE`.
-3. **Sway** — detected via `SWAYSOCK`.
-4. **X11** — detected via `XDG_SESSION_TYPE=x11` or `DISPLAY`.
-5. **Fallback** — defaults to X11 with a warning.
+1. **macOS** - detected via platform or `OSTYPE`.
+2. **Hyprland** - detected via `HYPRLAND_INSTANCE_SIGNATURE`.
+3. **Sway** - detected via `SWAYSOCK`.
+4. **X11** - detected via `XDG_SESSION_TYPE=x11` or `DISPLAY`.
+5. **Fallback** - defaults to X11 with a warning.

 ::: tip Wayland is compositor-specific
-Native Wayland support is only available for Hyprland and Sway. If you use a different Wayland compositor, auto-detection will fall back to X11 — both mpv and SubMiner must be running under Xwayland, and `xdotool` and `xwininfo` must be installed.
+Native Wayland support is only available for Hyprland and Sway. If you use a different Wayland compositor, auto-detection will fall back to X11 - both mpv and SubMiner must be running under Xwayland, and `xdotool` and `xwininfo` must be installed.
 :::

 ## Script Messages
@@ -133,10 +135,10 @@ script-message subminer-options
 script-message subminer-restart
 script-message subminer-status
 script-message subminer-autoplay-ready
-script-message subminer-aniskip-refresh
-script-message subminer-skip-intro
 ```

+The AniSkip messages (`subminer-skip-intro`, `subminer-aniskip-refresh`) still exist, but they are handled by the SubMiner app over the IPC socket rather than by the plugin - see [AniSkip Integration](/aniskip-integration#triggering-from-mpv).
+
 The `subminer-start` message accepts overrides:

 ```
@@ -146,27 +148,12 @@ script-message subminer-start backend=hyprland socket=/custom/path texthooker=no
 `log-level` here controls only logging verbosity passed to SubMiner.
 `--debug` is a separate app/dev-mode flag in the main CLI and should not be used here for logging.

-## AniSkip Intro Skip
-
- AniSkip lookups are gated. The plugin only runs lookup when:
-  - SubMiner launcher metadata is present, or
-  - SubMiner app process is already running, or
-  - You explicitly call `script-message subminer-aniskip-refresh`.
- Lookups are asynchronous (no blocking `ps`/`curl` on `file-loaded`).
- MAL/title resolution is cached for the current mpv session.
- When launched via `subminer`, launcher can pass `aniskip_payload` (pre-fetched AniSkip `skip-times` payload) and the plugin applies it directly without making API calls.
- If the payload is absent or invalid, lookup falls back to title/MAL-based async fetch.
- Install `guessit` for best detection quality (`python3 -m pip install --user guessit`).
- If OP interval exists, plugin adds `AniSkip Intro Start` and `AniSkip Intro End` chapters.
- At intro start, plugin shows an OSD hint for the first 3 seconds (`You can skip by pressing TAB` by default; the key reflects `mpv.aniskipButtonKey`).
- Use `script-message subminer-aniskip-refresh` after changing media metadata/options to retry lookup.
-
 ## Lifecycle

-For how the plugin's auto-start fits into the full launch sequence — including when the launcher starts the overlay instead of the plugin — see [Playback Startup Flow](./architecture#playback-startup-flow).
+For how the plugin's auto-start fits into the full launch sequence - including when the launcher starts the overlay instead of the plugin - see [Playback Startup Flow](./architecture#playback-startup-flow).

- **File loaded**: If `auto_start=yes`, the plugin starts the overlay, then defers AniSkip lookup until after startup delay.
- **Auto-start pause gate**: If `auto_start_visible_overlay=yes` and `auto_start_pause_until_ready=yes`, launcher starts mpv paused and the plugin resumes playback after SubMiner reports tokenization-ready (with timeout fallback).
+- **File loaded**: If `auto_start=yes`, the plugin starts the overlay.
+- **Auto-start pause gate**: If `auto_start_visible_overlay=yes` and `auto_start_pause_until_ready=yes`, launcher starts mpv paused. On cold managed background startup, SubMiner opens the tray and visible overlay shell before tokenization warmups finish, then the plugin resumes playback after SubMiner reports tokenization-ready (with a 30-second timeout fallback).
 - **Duplicate auto-start events**: Repeated `file-loaded` hooks while overlay is already running are ignored for auto-start triggers (prevents duplicate start attempts).
 - **MPV shutdown**: The plugin sends a stop command to gracefully shut down both the overlay and the texthooker server.
 - **Texthooker**: Starts as a separate subprocess before the overlay to ensure the app lock is acquired first.
@@ -181,4 +168,4 @@ The plugin is useful when you:
 - Want on-demand overlay control without the wrapper.
 - Use mpv's built-in file browser or playlist features.

-You can install both — the plugin provides chord keybindings for convenience, while the wrapper handles the full lifecycle.
+You can install both - the plugin provides chord keybindings for convenience, while the wrapper handles the full lifecycle.
@@ -172,10 +172,19 @@
  "updates": {
    "enabled": true, // Run automatic update checks in the background. Values: true | false
    "checkIntervalHours": 24, // Minimum hours between automatic update checks.
-    "notificationType": "system", // How SubMiner announces available updates. Values: system | osd | both | none
+    "notificationType": "overlay", // How SubMiner announces available updates. overlay shows notifications on the overlay, system uses OS notifications, both uses overlay and system. osd and osd-system are legacy config-file-only values. Values: overlay | system | both | none | osd | osd-system
    "channel": "stable" // Release channel used for update checks. Values: stable | prerelease
  }, // Automatic update check behavior.

+  // ==========================================
+  // Notifications
+  // Overlay notification display behavior.
+  // Hot-reload: position changes apply to the next overlay notification.
+  // ==========================================
+  "notifications": {
+    "overlayPosition": "top-right" // Position for in-overlay notification cards. Values: top-left | top | top-right
+  }, // Overlay notification display behavior.
+
  // ==========================================
  // Keyboard Shortcuts
  // Overlay keyboard shortcuts. Set a shortcut to null to disable.
@@ -199,7 +208,8 @@
    "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
    "openControllerSelect": "Alt+C", // Accelerator that opens the controller selection and learn-mode modal.
    "openControllerDebug": "Alt+Shift+C", // Accelerator that opens the controller debug modal with live axis/button readouts.
-    "toggleSubtitleSidebar": "Backslash" // Accelerator that toggles the subtitle sidebar visibility.
+    "toggleSubtitleSidebar": "Backslash", // Accelerator that toggles the subtitle sidebar visibility.
+    "toggleNotificationHistory": "CommandOrControl+N" // Accelerator that toggles the overlay notification history panel.
  }, // Overlay keyboard shortcuts. Set a shortcut to null to disable.

  // ==========================================
@@ -280,15 +290,41 @@
      ] // Command setting.
    },
    {
-      "key": "Shift+BracketRight", // Key setting.
+      "key": "Ctrl+Shift+ArrowLeft", // Key setting.
      "command": [
-        "__sub-delay-next-line"
+        "sub-step",
+        -1
      ] // Command setting.
    },
    {
-      "key": "Shift+BracketLeft", // Key setting.
+      "key": "Ctrl+Shift+ArrowRight", // Key setting.
      "command": [
-        "__sub-delay-prev-line"
+        "sub-step",
+        1
+      ] // Command setting.
+    },
+    {
+      "key": "KeyZ", // Key setting.
+      "command": [
+        "add",
+        "sub-delay",
+        -0.1
+      ] // Command setting.
+    },
+    {
+      "key": "Shift+KeyZ", // Key setting.
+      "command": [
+        "add",
+        "sub-delay",
+        0.1
+      ] // Command setting.
+    },
+    {
+      "key": "KeyX", // Key setting.
+      "command": [
+        "add",
+        "sub-delay",
+        0.1
      ] // Command setting.
    },
    {
@@ -496,7 +532,7 @@
    "tags": [
      "SubMiner"
    ], // Tags to add to cards mined or updated by SubMiner. Provide an empty array to disable automatic tagging.
-    "deck": "", // Restrict duplicate detection and card enrichment to this Anki deck. Leave empty to search all decks.
+    "deck": "", // Restrict duplicate detection and card enrichment to this Anki deck. Leave empty to use the Yomitan mining deck when available.
    "fields": {
      "word": "Expression", // Card field for the mined word or expression text.
      "audio": "ExpressionAudio", // Card field that receives generated sentence audio.
@@ -523,6 +559,7 @@
      "animatedMaxHeight": 0, // Maximum height for animated AVIF captures, in pixels. Set to 0 to preserve aspect ratio.
      "animatedCrf": 35, // Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.
      "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
+      "normalizeAudio": true, // Normalize generated sentence audio loudness during media extraction. Values: true | false
      "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio and animated AVIF clips.
      "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.
@@ -532,14 +569,14 @@
      "refreshMinutes": 1440, // Minutes between known-word cache refreshes.
      "addMinedWordsImmediately": true, // Immediately append newly mined card words into the known-word cache. Values: true | false
      "matchMode": "headword", // Known-word matching strategy for subtitle annotations. Cache matches always receive known-word highlighting even when POS filters suppress other annotation types. Values: headword | surface
-      "decks": {} // Decks and expression/word fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word"] }.
+      "decks": {} // Decks and expression/word fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word"] }. Reading fields (Reading, Word Reading, ExpressionReading) are always probed so cached words match only in the reading their note teaches; words from notes without readings match in any reading.
    }, // Known words setting.
    "behavior": {
      "overwriteAudio": true, // When updating an existing card, overwrite the audio field instead of skipping it. Values: true | false
      "overwriteImage": true, // When updating an existing card, overwrite the image field instead of skipping it. Values: true | false
      "mediaInsertMode": "append", // Whether new media is appended after or prepended before existing field contents on update. Values: append | prepend
      "highlightWord": true, // Bold the mined word inside the sentence field on the saved Anki card. Values: true | false
-      "notificationType": "osd", // Notification surface used to announce mining and update outcomes. Values: osd | system | both | none
+      "notificationType": "overlay", // Notification surface used to announce mining and update outcomes. overlay shows notifications on the overlay, system uses OS notifications, both uses overlay and system. osd and osd-system are legacy config-file-only values. Values: overlay | system | both | none | osd | osd-system
      "autoUpdateNewCards": true // Automatically update newly added cards. Values: true | false
    }, // Behavior setting.
    "nPlusOne": {
@@ -582,7 +619,11 @@
    "primarySubLanguages": [
      "ja",
      "jpn"
-    ] // Comma-separated primary subtitle language priority for managed subtitle auto-selection.
+    ], // Comma-separated primary subtitle language priority for managed subtitle auto-selection.
+    "mediaCache": {
+      "mode": "direct", // How YouTube card audio/images are extracted. Values: direct | background
+      "maxHeight": 720 // Maximum video height downloaded for the YouTube background media cache. Set to 0 for unlimited.
+    } // Media cache setting.
  }, // Defaults for managed subtitle language preferences and YouTube subtitle loading.

  // ==========================================
@@ -634,8 +675,8 @@
    "autoStartSubMiner": true, // Start SubMiner in the background when SubMiner-managed mpv loads a file. Values: true | false
    "pauseUntilOverlayReady": true, // Pause mpv on visible-overlay auto-start until SubMiner signals subtitle tokenization readiness. Values: true | false
    "subminerBinaryPath": "", // Optional SubMiner app binary path passed to the bundled mpv plugin. Leave empty to use the launcher-detected app path.
-    "aniskipEnabled": true, // Enable AniSkip intro detection and skip markers in the bundled mpv plugin. Values: true | false
-    "aniskipButtonKey": "TAB" // mpv key used to trigger the AniSkip button while the skip marker is visible.
+    "aniskipEnabled": true, // Enable AniSkip intro detection, chapter markers, and the skip-intro key. Values: true | false
+    "aniskipButtonKey": "TAB" // mpv key used to skip the detected intro while the skip prompt is visible.
  }, // SubMiner-managed mpv launch and bundled plugin options.

  // ==========================================
@@ -1,12 +1,12 @@
 # Keyboard Shortcuts

-This page is the complete reference for every keystroke SubMiner responds to. If you are just getting started, focus on the **Mining Shortcuts** and **Overlay Controls** sections — those cover the day-to-day mining loop. The rest can wait until you need them.
+This page is the complete reference for every keystroke SubMiner responds to. If you are just getting started, focus on the **Mining Shortcuts** and **Overlay Controls** sections - those cover the day-to-day mining loop. The rest can wait until you need them.

 A few terms used throughout:

- **Overlay** — the transparent SubMiner window that sits on top of mpv and shows the interactive subtitles. Most shortcuts only work while this window has focus (click the video once if a shortcut seems to do nothing).
- **`Ctrl/Cmd`** — use `Ctrl` on Windows/Linux and `Cmd` (⌘) on macOS. In the config file this is written as `CommandOrControl`.
- **Accelerator** — Electron's name for a shortcut string like `Alt+Shift+O`.
+- **Overlay** - the transparent SubMiner window that sits on top of mpv and shows the interactive subtitles. Most shortcuts only work while this window has focus (click the video once if a shortcut seems to do nothing).
+- **`Ctrl/Cmd`** - use `Ctrl` on Windows/Linux and `Cmd` (⌘) on macOS. In the config file this is written as `CommandOrControl`.
+- **Accelerator** - Electron's name for a shortcut string like `Alt+Shift+O`.

 All shortcuts are configurable in `config.jsonc` under `shortcuts` and `keybindings`. Set any shortcut to `null` to disable it.

@@ -43,31 +43,34 @@ The multi-line shortcuts open a digit selector with a 3-second timeout (`shortcu

 These control playback and subtitle display. They require overlay window focus.

-| Shortcut             | Action                                              |
-| -------------------- | --------------------------------------------------- |
-| `Space`              | Toggle mpv pause                                    |
-| `F`                  | Toggle fullscreen                                   |
+| Shortcut             | Action                                                     |
+| -------------------- | ---------------------------------------------------------- |
+| `Space`              | Toggle mpv pause                                           |
+| `F`                  | Toggle fullscreen                                          |
 | `V`                  | Cycle primary subtitle bar mode (hidden → visible → hover) |
-| `J`                  | Cycle primary subtitle track                        |
-| `Shift+J`            | Cycle secondary subtitle track                      |
-| `Ctrl+Alt+P`         | Open playlist browser for current directory + queue |
-| `ArrowRight`         | Seek forward 5 seconds                              |
-| `ArrowLeft`          | Seek backward 5 seconds                             |
-| `ArrowUp`            | Seek forward 60 seconds                             |
-| `ArrowDown`          | Seek backward 60 seconds                            |
-| `Shift+H`            | Jump to previous subtitle                           |
-| `Shift+L`            | Jump to next subtitle                               |
-| `Shift+[`            | Shift subtitle delay to previous subtitle cue       |
-| `Shift+]`            | Shift subtitle delay to next subtitle cue           |
-| `Ctrl+Shift+H`       | Replay current subtitle (play to end, then pause)   |
-| `Ctrl+Shift+L`       | Play next subtitle (jump, play to end, then pause)  |
-| `Q`                  | Quit mpv                                            |
-| `Ctrl+W`             | Quit mpv                                            |
-| `Right-click`        | Toggle pause (outside subtitle area)                |
-| `Right-click + drag` | Reposition subtitles (on subtitle area)             |
-| `Ctrl/Cmd+A`         | Append clipboard video path to mpv playlist         |
+| `J`                  | Cycle primary subtitle track                               |
+| `Shift+J`            | Cycle secondary subtitle track                             |
+| `Ctrl+Alt+P`         | Open playlist browser for current directory + queue        |
+| `ArrowRight`         | Seek forward 5 seconds                                     |
+| `ArrowLeft`          | Seek backward 5 seconds                                    |
+| `ArrowUp`            | Seek forward 60 seconds                                    |
+| `ArrowDown`          | Seek backward 60 seconds                                   |
+| `Shift+H`            | Jump to previous subtitle                                  |
+| `Shift+L`            | Jump to next subtitle                                      |
+| `Ctrl+Shift+Left`    | Shift subtitle delay to previous subtitle cue              |
+| `Ctrl+Shift+Right`   | Shift subtitle delay to next subtitle cue                  |
+| `z`                  | Shift subtitles 100 ms earlier                             |
+| `Shift+Z`            | Delay subtitles by 100 ms                                  |
+| `x`                  | Delay subtitles by 100 ms                                  |
+| `Ctrl+Shift+H`       | Replay current subtitle (play to end, then pause)          |
+| `Ctrl+Shift+L`       | Play next subtitle (jump, play to end, then pause)         |
+| `Q`                  | Quit mpv                                                   |
+| `Ctrl+W`             | Quit mpv                                                   |
+| `Right-click`        | Toggle pause (outside subtitle area)                       |
+| `Right-click + drag` | Reposition subtitles (on subtitle area)                    |
+| `Ctrl/Cmd+A`         | Append clipboard video path to mpv playlist                |

-The mpv-command rows above (`Space`, `F`, `J`, `Shift+J`, the seek/sub-seek/sub-delay keys, replay/play-next, and quit) are merged from the `keybindings` config array and can be remapped or disabled there. `V`, `Ctrl/Cmd+A`, and the mouse actions are built-in overlay behaviors and are not part of the `keybindings` array. The playlist browser opens a split overlay modal with sibling video files on the left and the live mpv playlist on the right.
+The mpv-command rows above (`Space`, `F`, `J`, `Shift+J`, the seek/sub-seek/sub-step/sub-delay keys, replay/play-next, and quit) are merged from the `keybindings` config array and can be remapped or disabled there. `V`, `Ctrl/Cmd+A`, and the mouse actions are built-in overlay behaviors and are not part of the `keybindings` array. The playlist browser opens a split overlay modal with sibling video files on the left and the live mpv playlist on the right.

 On macOS managed playback, SubMiner disables mpv's menu-bar shortcuts so configured SubMiner shortcuts like `Cmd+Shift+O` reach the mpv plugin instead of opening native mpv menu actions.

@@ -75,18 +78,19 @@ Mouse-hover playback behavior is configured separately from shortcuts: `subtitle

 ## Subtitle & Feature Shortcuts

-| Shortcut           | Action                                                   | Config key                                      |
-| ------------------ | -------------------------------------------------------- | ----------------------------------------------- |
-| `Ctrl/Cmd+Shift+V` | Cycle secondary subtitle mode (hidden → visible → hover) | `shortcuts.toggleSecondarySub`                  |
-| `Ctrl/Cmd+D`       | Open loaded character dictionary manager                 | `shortcuts.openCharacterDictionaryManager`      |
-| `Ctrl/Cmd+Shift+O` | Open runtime options palette                             | `shortcuts.openRuntimeOptions`                  |
-| `Ctrl/Cmd+/`       | Open session help modal                                  | `shortcuts.openSessionHelp`                     |
-| `Ctrl+Shift+J`     | Open Jimaku subtitle search modal                        | `shortcuts.openJimaku`                          |
-| `Ctrl+Alt+C`       | Open the manual YouTube subtitle picker                  | `keybindings`                                   |
-| `Ctrl+Alt+S`       | Open subtitle sync (subsync) modal                       | `shortcuts.triggerSubsync`                      |
-| `\`                | Toggle subtitle sidebar                                  | `subtitleSidebar.toggleKey`                     |
-| `` ` ``            | Toggle stats overlay                                     | `stats.toggleKey`                               |
-| `W`                | Mark current video watched and advance to next in queue  | `stats.markWatchedKey`                          |
+| Shortcut           | Action                                                   | Config key                                 |
+| ------------------ | -------------------------------------------------------- | ------------------------------------------ |
+| `Ctrl/Cmd+Shift+V` | Cycle secondary subtitle mode (hidden → visible → hover) | `shortcuts.toggleSecondarySub`             |
+| `Ctrl/Cmd+D`       | Open loaded character dictionary manager                 | `shortcuts.openCharacterDictionaryManager` |
+| `Ctrl/Cmd+Shift+O` | Open runtime options palette                             | `shortcuts.openRuntimeOptions`             |
+| `Ctrl/Cmd+/`       | Open session help modal                                  | `shortcuts.openSessionHelp`                |
+| `Ctrl+Shift+J`     | Open Jimaku subtitle search modal                        | `shortcuts.openJimaku`                     |
+| `Ctrl/Cmd+N`       | Toggle overlay notification history panel                | `shortcuts.toggleNotificationHistory`      |
+| `Ctrl+Alt+C`       | Open the manual YouTube subtitle picker                  | `keybindings`                              |
+| `Ctrl+Alt+S`       | Open subtitle sync (subsync) modal                       | `shortcuts.triggerSubsync`                 |
+| `\`                | Toggle subtitle sidebar                                  | `subtitleSidebar.toggleKey`                |
+| `` ` ``            | Toggle stats overlay                                     | `stats.toggleKey`                          |
+| `W`                | Mark current video watched and advance to next in queue  | `stats.markWatchedKey`                     |

 The stats toggle is handled inside the focused visible overlay window. It is configurable through the top-level `stats.toggleKey` setting and defaults to `Backquote`.

@@ -105,19 +109,19 @@ Controller input only drives the overlay while keyboard-only mode is enabled. Th

 ## MPV Plugin Chords

-When the mpv plugin is installed, all commands use a `y` chord prefix — press `y`, then the second key within 1 second.
+When the mpv plugin is installed, all commands use a `y` chord prefix - press `y`, then the second key within 1 second.

-| Chord | Action                                 |
-| ----- | -------------------------------------- |
-| `y-y` | Open SubMiner menu (OSD)               |
-| `y-s` | Start overlay                          |
-| `y-S` | Stop overlay                           |
-| `y-t` | Toggle visible overlay                 |
+| Chord | Action                                                     |
+| ----- | ---------------------------------------------------------- |
+| `y-y` | Open SubMiner menu (OSD)                                   |
+| `y-s` | Start overlay                                              |
+| `y-S` | Stop overlay                                               |
+| `y-t` | Toggle visible overlay                                     |
 | `v`   | Cycle primary subtitle bar mode (hidden → visible → hover) |
-| `y-o` | Open Yomitan settings                  |
-| `y-r` | Restart overlay                        |
-| `y-c` | Check overlay status                   |
-| `y-h` | Open session help                      |
+| `y-o` | Open Yomitan settings                                      |
+| `y-r` | Restart overlay                                            |
+| `y-c` | Check overlay status                                       |
+| `y-h` | Open session help                                          |

 The bare `v` plugin binding intentionally overrides mpv's native primary subtitle visibility toggle so it cycles the SubMiner primary subtitle bar (hidden → visible → hover) instead.

@@ -161,4 +165,4 @@ The `keybindings` array overrides or extends the overlay's built-in key handling

 Mouse keybinding names are `MBTN_LEFT`, `MBTN_MID`, `MBTN_RIGHT`, `MBTN_BACK`, and `MBTN_FORWARD`.

-Both `shortcuts`, `keybindings`, and `subtitleSidebar` are [hot-reloadable](/configuration#hot-reload-behavior) — changes take effect without restarting SubMiner.
+Both `shortcuts`, `keybindings`, and `subtitleSidebar` are [hot-reloadable](/configuration#hot-reload-behavior) - changes take effect without restarting SubMiner.
@@ -2,7 +2,11 @@

 SubMiner annotates subtitle tokens in real time as they appear in the overlay. Four annotation layers work together to surface useful context while you watch: **N+1 highlighting**, **character-name highlighting**, **frequency highlighting**, and **JLPT tagging**.

-All four are opt-in and configured under `subtitleStyle`, `ankiConnect.knownWords`, and `ankiConnect.nPlusOne` in your config. They apply independently — you can enable any combination.
+All four are opt-in and configured under `subtitleStyle`, `ankiConnect.knownWords`, and `ankiConnect.nPlusOne` in your config. They apply independently - you can enable any combination.
+
+::: tip Tokenization
+SubMiner's primary tokenizer is Yomitan itself - subtitle text is tokenized based entirely on the dictionaries you have installed in Yomitan. Installing many large dictionaries can increase noise and slow down lookups, so be selective about which dictionaries you install and their priority order.
+:::

 Before any of those layers render, SubMiner strips annotation metadata from tokens that are usually just subtitle glue or annotation noise. Standalone particles, auxiliaries, adnominals, common explanatory endings like `んです` / `のだ`, merged trailing quote-particle forms like `...って`, auxiliary-stem grammar tails like `そうだ` (MeCab POS3 `助動詞語幹`), repeated kana interjections, and similar non-lexical helper tokens remain hoverable in the subtitle text, but they render as plain tokens without known-word, N+1, frequency, JLPT, or name-match annotation styling.

@@ -39,7 +43,7 @@ Set `refreshMinutes` to `1440` (24 hours) for daily sync if your Anki collection

 ## Character-Name Highlighting

-Character-name matches are built from the active merged SubMiner character dictionary, which auto-syncs character data from AniList for your recently-watched titles. When the current AniList media ID is known, SubMiner ignores loaded entries from other titles for subtitle name matching and inline portraits. Matching names are highlighted in subtitles and become available for hover-driven Yomitan character profiles — portraits, roles, voice actors, and biographical detail.
+Character-name matches are built from the active merged SubMiner character dictionary, which auto-syncs character data from AniList for your recently-watched titles. When the current AniList media ID is known, SubMiner ignores loaded entries from other titles for subtitle name matching and inline portraits. Matching names are highlighted in subtitles and become available for hover-driven Yomitan character profiles - portraits, roles, voice actors, and biographical detail.

 **How it works:**

@@ -60,12 +64,12 @@ For full details on dictionary generation, name variant expansion, auto-sync lif

 ## Frequency Highlighting

-Frequency highlighting colors tokens based on how common they are, using dictionary frequency rank data. This helps you spot high-value vocabulary at a glance.
+Frequency highlighting colors tokens based on how common they are, using dictionary frequency rank data. This helps you spot high-value vocabulary at a glance. Frequency ranks are sourced from the **highest-ranked frequency dictionary** installed in Yomitan - other frequency dictionaries are not consulted.

 **Modes:**

- **Single** — all highlighted tokens share one color (`singleColor`).
- **Banded** — tokens are assigned to five color bands from most common to least common within the `topX` window.
+- **Single** - all highlighted tokens share one color (`singleColor`).
+- **Banded** - tokens are assigned to five color bands from most common to least common within the `topX` window.

 SubMiner looks up each token's `frequencyRank` from `term_meta_bank_*.json` files. Only tokens with a positive rank at or below `topX` are highlighted.

@@ -130,14 +134,14 @@ All annotation layers can be toggled at runtime via the mpv command menu without
 - `subtitleStyle.enableJlpt` (`On` / `Off`)
 - `subtitleStyle.frequencyDictionary.enabled` (`On` / `Off`)

-Toggles only apply to new subtitle lines after the change — the currently displayed line is not re-tokenized in place.
+Toggles only apply to new subtitle lines after the change - the currently displayed line is not re-tokenized in place.

 ## Rendering Priority

 When multiple annotations apply to the same token, the visual priority is:

-1. **N+1 target** (highest) — the single unknown word in an N+1 sentence
-2. **Character-name match** — dictionary-driven character-name token styling
-3. **Known-word color** — already-learned token tint
-4. **Frequency highlight** — common-word coloring (not applied when N+1/character-name/known-word already matched)
-5. **JLPT underline** — level-based underline (stacks with the above since it uses underline rather than text color)
+1. **N+1 target** (highest) - the single unknown word in an N+1 sentence
+2. **Character-name match** - dictionary-driven character-name token styling
+3. **Known-word color** - already-learned token tint
+4. **Frequency highlight** - common-word coloring (not applied when N+1/character-name/known-word already matched)
+5. **JLPT underline** - level-based underline (stacks with the above since it uses underline rather than text color)
@@ -10,7 +10,7 @@ When SubMiner parses the active subtitle source into a cue list, the sidebar bec

 - The active cue is highlighted and kept in view as playback advances (when `autoScroll` is `true`).
 - Clicking any cue seeks mpv to that timestamp.
- The sidebar stays synchronized with the overlay — media transitions and subtitle source changes update both simultaneously.
+- The sidebar stays synchronized with the overlay - media transitions and subtitle source changes update both simultaneously.

 The sidebar only appears when a parsed cue list is available. External subtitle sources that SubMiner cannot parse (for example, embedded ASS tracks rendered directly by mpv) will not populate the sidebar.

@@ -18,9 +18,9 @@ The sidebar only appears when a parsed cue list is available. External subtitle

 Two layout modes are available via `subtitleSidebar.layout`:

-**`overlay`** (default) — The sidebar floats over mpv as a panel. It does not affect the player window size or position.
+**`overlay`** (default) - The sidebar floats over mpv as a panel. It does not affect the player window size or position.

-**`embedded`** — Reserves space on the right side of the player and shifts the video area to mimic a split-pane layout. Useful if you want the cue list visible without it covering the video. If you see unexpected positioning in your environment, switch back to `overlay` to isolate the issue.
+**`embedded`** - Reserves space on the right side of the player and shifts the video area to mimic a split-pane layout. Useful if you want the cue list visible without it covering the video. If you see unexpected positioning in your environment, switch back to `overlay` to isolate the issue.

 ## Configuration

@@ -1,6 +1,6 @@
 # Troubleshooting

-Common issues and how to resolve them. Most problems fall into one of a few buckets — the overlay shows but subtitles don't (see [MPV Connection](#mpv-connection)), cards aren't being created or come out empty (see [AnkiConnect](#ankiconnect)), or word lookups don't appear (see [Yomitan](#yomitan)). If an error message popped up on screen, search this page for the exact text — most headings below are quoted error strings.
+Common issues and how to resolve them. Most problems fall into one of a few buckets - the overlay shows but subtitles don't (see [MPV Connection](#mpv-connection)), cards aren't being created or come out empty (see [AnkiConnect](#ankiconnect)), or word lookups don't appear (see [Yomitan](#yomitan)). If an error message popped up on screen, search this page for the exact text - most headings below are quoted error strings.

 ## MPV Connection

@@ -102,7 +102,7 @@ If the overlay never appears at all, see [Playback Startup Flow](./architecture#

 **"Failed to parse MPV message"**

-Logged when a malformed JSON line arrives from the mpv socket. Usually harmless — SubMiner skips the bad line and continues. If it happens constantly, check that nothing else is writing to the same socket path.
+Logged when a malformed JSON line arrives from the mpv socket. Usually harmless - SubMiner skips the bad line and continues. If it happens constantly, check that nothing else is writing to the same socket path.

 ## Updates

@@ -126,13 +126,13 @@ The detected launcher is installed in a protected path such as `/usr/local/bin/s

 **OSD update notification did not appear**

-`updates.notificationType: "osd"` uses the existing mpv/overlay notification path. If mpv is disconnected, SubMiner logs the update and does not force-start the overlay. Use `"system"` or `"both"` if you want OS notifications outside playback.
+`updates.notificationType: "osd"` uses the legacy mpv OSD path. If mpv is disconnected, SubMiner logs the update and does not force-start the overlay. Use `"system"` for OS notifications, `"both"` for overlay + OS notifications, or `"osd-system"` in `config.jsonc` if you want the legacy OSD + OS combination.

 ## AnkiConnect

 **"AnkiConnect: unable to connect"**

-First confirm you've completed the [Anki Integration prerequisites](/anki-integration#prerequisites) — Anki must be running with the AnkiConnect add-on installed.
+First confirm you've completed the [Anki Integration prerequisites](/anki-integration#prerequisites) - Anki must be running with the AnkiConnect add-on installed.

 SubMiner connects to the active Anki endpoint:

@@ -148,7 +148,7 @@ SubMiner retries with exponential backoff (up to 5 s) and suppresses repeated er

 **Cards are created but fields are empty**

-Field names in your config must match your Anki note type exactly (case-sensitive). Check `ankiConnect.fields` — for example, if your note type uses `SentenceAudio` but your config says `Audio`, the field will not be populated.
+Field names in your config must match your Anki note type exactly (case-sensitive). Check `ankiConnect.fields` - for example, if your note type uses `SentenceAudio` but your config says `Audio`, the field will not be populated.

 See [Anki Integration](/anki-integration) for the full field mapping reference.

@@ -169,7 +169,7 @@ Shown when SubMiner tries to update a card that no longer exists, or when AnkiCo

 **Overlay appears but clicks pass through / cannot interact**

- Make sure you are hovering over subtitle text — the overlay only becomes interactive when the cursor is over a subtitle.
+- Make sure you are hovering over subtitle text - the overlay only becomes interactive when the cursor is over a subtitle.
 - On macOS/Windows: toggle the overlay off and back on (`Alt+Shift+O`) to re-enable pointer events.
 - On Linux: mouse event handling is unreliable in some Electron/compositor combinations. If clicks consistently fail, toggle the overlay off, click the underlying mpv window, then toggle it back on.

@@ -208,7 +208,7 @@ If you installed from the AppImage and see this error, the package may be incomp

 **Yomitan lookup popup does not appear when hovering words or triggering lookup**

- Verify Yomitan loaded successfully — check the terminal output for "Loaded Yomitan extension".
+- Verify Yomitan loaded successfully - check the terminal output for "Loaded Yomitan extension".
 - Yomitan requires dictionaries to be installed. Open Yomitan settings (`Alt+Shift+Y` or `SubMiner.AppImage --yomitan`) and confirm at least one dictionary is imported.
 - If `yomitan.externalProfilePath` is set, import/check dictionaries in the external app/profile instead. SubMiner treats that profile as read-only and does not open its own Yomitan settings window.
 - If the overlay shows subtitles but hover lookup never resolves on tokens, the tokenizer may have failed. See the MeCab section below.
@@ -234,9 +234,9 @@ Japanese word boundaries depend on Yomitan parser output. If segmentation seems

 ## Character Dictionary

-Character names from AniList are matched and highlighted in subtitles via the bundled Yomitan. See [Character Dictionary](/character-dictionary) for setup and the full troubleshooting list — the most common issues:
+Character names from AniList are matched and highlighted in subtitles via the bundled Yomitan. See [Character Dictionary](/character-dictionary) for setup and the full troubleshooting list - the most common issues:

- **Names not highlighting:** Confirm `subtitleStyle.nameMatchEnabled` is `true`, and that the current media resolved to an AniList entry (SubMiner needs a media ID to fetch characters). No AniList account or token is required — character data uses public GraphQL queries.
+- **Names not highlighting:** Confirm `subtitleStyle.nameMatchEnabled` is `true`, and that the current media resolved to an AniList entry (SubMiner needs a media ID to fetch characters). No AniList account or token is required - character data uses public GraphQL queries.
 - **Inline portraits missing:** Confirm `subtitleStyle.nameMatchImagesEnabled` is `true`. Portraits also require AniList to return an image and the download to succeed during snapshot generation.
 - **Wrong characters showing:** Open the in-app manager (`Ctrl/Cmd+D`) and use **Override** to pin the correct AniList match for the series.
 - **Feature unavailable:** If `yomitan.externalProfilePath` is set, SubMiner runs in read-only external-profile mode and its character-dictionary features are disabled.
@@ -269,7 +269,7 @@ Global shortcuts (`Alt+Shift+O`, `Alt+Shift+Y`) may conflict with other applicat

 - Check your DE/WM keybinding settings for conflicts.
 - Change the shortcut in your config under `shortcuts.toggleVisibleOverlayGlobal`.
- On Wayland, global shortcut registration has limitations depending on the compositor. Only Hyprland and Sway are supported natively — see the [Hyprland](#hyprland) section below for shortcut passthrough rules. Other Wayland compositors require X11/Xwayland.
+- On Wayland, global shortcut registration has limitations depending on the compositor. Only Hyprland and Sway are supported natively - see the [Hyprland](#hyprland) section below for shortcut passthrough rules. Other Wayland compositors require X11/Xwayland.

 **Overlay keybindings not working**

@@ -326,14 +326,14 @@ The Jimaku API has rate limits. If you see 429 errors, wait for the retry durati

 ### Linux

- **Wayland (Hyprland/Sway only)**: Native Wayland support is limited to Hyprland and Sway. Window tracking uses compositor-specific commands (`hyprctl` / `swaymsg`). If these are not on `PATH`, tracking will fail silently. Other Wayland compositors (KDE Plasma, GNOME, …) are not supported natively — both mpv and SubMiner must run under X11 or Xwayland instead. On those sessions SubMiner forces XWayland automatically for itself and for every mpv it launches (see [KDE Plasma & other Wayland compositors](#kde-plasma--other-wayland-compositors)).
- **X11 / Xwayland**: Requires `xdotool`, `xprop`, and `xwininfo`. If missing, the overlay cannot track the mpv window position. This is the required backend for any Wayland compositor other than Hyprland or Sway — both mpv and SubMiner must be running under X11/Xwayland for window tracking _and_ for the overlay to stay above mpv (Wayland forbids clients from controlling window stacking). SubMiner uses a managed X11 overlay while mpv is windowed, switches to an override-redirect X11 overlay while tracked mpv is fullscreen, and hides/releases that overlay when another X11/Xwayland app takes focus. The visible overlay stays hidden until SubMiner has tracked mpv geometry, so startup should not create a display-sized fallback overlay while tokenization warms up.
+- **Wayland (Hyprland/Sway only)**: Native Wayland support is limited to Hyprland and Sway. Window tracking uses compositor-specific commands (`hyprctl` / `swaymsg`). If these are not on `PATH`, tracking will fail silently. Other Wayland compositors (KDE Plasma, GNOME, …) are not supported natively - both mpv and SubMiner must run under X11 or Xwayland instead. On those sessions SubMiner forces XWayland automatically for itself and for every mpv it launches (see [KDE Plasma & other Wayland compositors](#kde-plasma--other-wayland-compositors)).
+- **X11 / Xwayland**: Requires `xdotool`, `xprop`, and `xwininfo`. If missing, the overlay cannot track the mpv window position. This is the required backend for any Wayland compositor other than Hyprland or Sway - both mpv and SubMiner must be running under X11/Xwayland for window tracking _and_ for the overlay to stay above mpv (Wayland forbids clients from controlling window stacking). SubMiner uses a managed X11 overlay while mpv is windowed, switches to an override-redirect X11 overlay while tracked mpv is fullscreen, and hides/releases that overlay when another X11/Xwayland app takes focus. The visible overlay stays hidden until SubMiner has tracked mpv geometry, so startup should not create a display-sized fallback overlay while tokenization warms up.
 - **Tray icon missing**: SubMiner creates an Electron tray icon in `--background` mode, but Linux trays require a StatusNotifier/AppIndicator host. Hyprland does not provide one by itself; enable a tray in Waybar, Hyprpanel, or another panel. If Electron cannot register the tray, SubMiner logs a warning that mentions the missing tray host.
 - **Mouse passthrough**: On Linux X11/Xwayland, SubMiner uses `xdotool` to poll the cursor and only enables overlay input while the cursor is over subtitle or popup regions. Outside those regions, pointer input passes through to mpv. Native Wayland compositors other than Hyprland/Sway cannot provide the stacking control SubMiner needs.

 ### Hyprland

-SubMiner's overlay is a transparent, frameless Electron window that must be kept above mpv. SubMiner tries to apply the floating, borderless, no-shadow, and no-blur properties itself each time it places the overlay. It detects Hyprland's active config provider and uses Lua `hl.dsp.window.*` dispatchers for recent Hyprland Lua configs, or the legacy dispatcher syntax for older hyprlang configs. On many configurations that is enough, but if your Hyprland version doesn't honor those runtime dispatches — or a broad rule in your config forces opacity/blur on every window — add explicit window rules so the overlay is exempt. You also need `pass` bindings to forward global shortcuts to SubMiner (see below).
+SubMiner's overlay is a transparent, frameless Electron window that must be kept above mpv. SubMiner tries to apply the floating, borderless, no-shadow, and no-blur properties itself each time it places the overlay. It detects Hyprland's active config provider and uses Lua `hl.dsp.window.*` dispatchers for recent Hyprland Lua configs, or the legacy dispatcher syntax for older hyprlang configs. On many configurations that is enough, but if your Hyprland version doesn't honor those runtime dispatches - or a broad rule in your config forces opacity/blur on every window - add explicit window rules so the overlay is exempt. You also need `pass` bindings to forward global shortcuts to SubMiner (see below).

 **Overlay is not transparent or has a visible border**

@@ -364,7 +364,7 @@ windowrule = no_shadow on, match:class SubMiner
 windowrule = no_blur on, match:class SubMiner
 ```

-If you still see a solid background or visual artifacts instead of the mpv video underneath, the culprit is almost always a global opacity/blur rule applying to the overlay — the `opaque`/`opacity` and `no_blur` fields above override it.
+If you still see a solid background or visual artifacts instead of the mpv video underneath, the culprit is almost always a global opacity/blur rule applying to the overlay - the `opaque`/`opacity` and `no_blur` fields above override it.

 **Global shortcuts not working**

@@ -387,12 +387,12 @@ For more details, see the Hyprland docs on [global keybinds](https://wiki.hypr.l

 ### KDE Plasma & other Wayland compositors

-On any Wayland session that is not Hyprland or Sway (KDE Plasma, GNOME, and others), the overlay can only stay above mpv when both processes run under **XWayland** — the Wayland protocol forbids clients from controlling window stacking, so the overlay's "always on top" becomes a no-op on a native Wayland surface.
+On any Wayland session that is not Hyprland or Sway (KDE Plasma, GNOME, and others), the overlay can only stay above mpv when both processes run under **XWayland** - the Wayland protocol forbids clients from controlling window stacking, so the overlay's "always on top" becomes a no-op on a native Wayland surface.

 SubMiner handles this automatically:

 - It launches its own window under XWayland (it sets `--ozone-platform-hint=x11`).
- Every mpv it launches (via the `subminer` launcher, Jellyfin, or YouTube) is pinned to XWayland too — Wayland environment hints are stripped and an X11 GPU context (`--gpu-context=x11egl,x11`) is applied.
+- Every mpv it launches (via the `subminer` launcher, Jellyfin, or YouTube) is pinned to XWayland too - Wayland environment hints are stripped and an X11 GPU context (`--gpu-context=x11egl,x11`) is applied.
 - While mpv is windowed, the overlay is a managed X11 window owned by the tracked mpv window (`WM_TRANSIENT_FOR`), so it stays above mpv while other foreground X11/Xwayland apps can still cover both windows.
 - While tracked mpv is fullscreen, SubMiner swaps the visible overlay to a focusable-false X11 override-redirect window. That path can stay above the active fullscreen mpv window without requiring a KDE/KWin-specific rule, and SubMiner hides/releases it when mpv is no longer the active X11/Xwayland window.
 - The visible overlay is shown inactive on Linux, so normal hover should not steal keyboard focus from mpv.
@@ -423,15 +423,15 @@ SubMiner can only detect focus for X11/Xwayland windows in this mode. If a nativ

 Feature-specific issues are covered in each feature's own page:

- [Anki Integration](/anki-integration) — card creation, field mapping, and AnkiConnect setup
- [AniList Integration](/anilist-integration) — watch-progress sync and authentication
- [Character Dictionary](/character-dictionary) — AniList character name matching and inline portraits
- [Jellyfin Integration](/jellyfin-integration) — remote playback and library connection
- [Jimaku Integration](/jimaku-integration) — subtitle fetching and API rate limits
- [YouTube Integration](/youtube-integration) — subtitle generation and playback
- [Immersion Tracking](/immersion-tracking) — telemetry and session logging
- [WebSocket / Texthooker API](/websocket-texthooker-api) — external texthooker clients
- [Subtitle Annotations](/subtitle-annotations) — N+1, frequency, JLPT, and name-match layers
- [Subtitle Sidebar](/subtitle-sidebar) — sidebar navigation and behavior
- [Configuration Reference](/configuration) — full config options
- [Shortcuts](/shortcuts) — keybinding reference
+- [Anki Integration](/anki-integration) - card creation, field mapping, and AnkiConnect setup
+- [AniList Integration](/anilist-integration) - watch-progress sync and authentication
+- [Character Dictionary](/character-dictionary) - AniList character name matching and inline portraits
+- [Jellyfin Integration](/jellyfin-integration) - remote playback and library connection
+- [Jimaku Integration](/jimaku-integration) - subtitle fetching and API rate limits
+- [YouTube Integration](/youtube-integration) - subtitle generation and playback
+- [Immersion Tracking](/immersion-tracking) - telemetry and session logging
+- [WebSocket / Texthooker API](/websocket-texthooker-api) - external texthooker clients
+- [Subtitle Annotations](/subtitle-annotations) - N+1, frequency, JLPT, and name-match layers
+- [Subtitle Sidebar](/subtitle-sidebar) - sidebar navigation and behavior
+- [Configuration Reference](/configuration) - full config options
+- [Shortcuts](/shortcuts) - keybinding reference
@@ -8,7 +8,7 @@ Play a video with SubMiner:
 subminer video.mkv
 ```

-On **Windows**, use the **SubMiner mpv** shortcut created during first-run setup — double-click it, or drag a video file onto it.
+On **Windows**, use the **SubMiner mpv** shortcut created during first-run setup - double-click it, or drag a video file onto it.

 That's the simplest way to get started. The `subminer` launcher handles mpv, the IPC socket, and the overlay automatically.

@@ -41,20 +41,20 @@ Field names must match your Anki note type exactly (case-sensitive). See [Anki I
 When you launch SubMiner, it wires up mpv and the overlay for you:

 1. SubMiner starts the overlay app in the background
-2. mpv runs with an **IPC socket** at `/tmp/subminer-socket` — a small local channel two programs use to talk to each other, so the overlay can ask mpv what subtitle is on screen right now
+2. mpv runs with an **IPC socket** at `/tmp/subminer-socket` - a small local channel two programs use to talk to each other, so the overlay can ask mpv what subtitle is on screen right now
 3. The overlay connects and subscribes to subtitle changes

-From there, subtitles render as interactive, hoverable word spans and you mine cards directly from the overlay. For the overlay anatomy and the full mining loop — word lookup, card creation, annotations — see [Mining Workflow](/mining-workflow).
+From there, subtitles render as interactive, hoverable word spans and you mine cards directly from the overlay. For the overlay anatomy and the full mining loop - word lookup, card creation, annotations - see [Mining Workflow](/mining-workflow).

 ### Ways to Launch

 | Approach                            | Use when                                                                                                                               | How                                                                   |
 | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| **`subminer` launcher**             | You want SubMiner to handle everything — launch mpv, set up the socket, start the overlay. **Recommended for most users.**             | `subminer video.mkv`                                                  |
+| **`subminer` launcher**             | You want SubMiner to handle everything - launch mpv, set up the socket, start the overlay. **Recommended for most users.**             | `subminer video.mkv`                                                  |
 | **SubMiner mpv shortcut** (Windows) | The recommended Windows entry point. Created during first-run setup, launches mpv with SubMiner's defaults.                            | Double-click, drag a file onto it, or run `SubMiner.exe --launch-mpv` |
 | **mpv plugin** (all platforms)      | Bundled and injected at runtime. Provides `y` chord keybindings for controlling the overlay from within mpv. No manual install needed. | Automatic when using the launcher or shortcut                         |

-The mpv plugin is always available — it's bundled with SubMiner and injected at runtime. If you launch mpv yourself (without the launcher), pass `--input-ipc-server=/tmp/subminer-socket` in your mpv config for the overlay to connect.
+The mpv plugin is always available - it's bundled with SubMiner and injected at runtime. On Linux, normal `subminer` playback auto-installs the launcher-managed runtime plugin copy from the bundled app if that managed copy is missing, so no separate plugin install is needed for standard launcher usage. If you launch mpv yourself (without the launcher), pass `--input-ipc-server=/tmp/subminer-socket` in your mpv config for the overlay to connect.

 ## Live Config Reload

@@ -111,6 +111,9 @@ subminer config show              # Print active config contents
 subminer mpv socket               # Print active mpv socket path
 subminer mpv status               # Exit 0 if socket is ready, else exit 1
 subminer mpv idle                 # Launch detached idle mpv with SubMiner defaults
+subminer sync media-box           # Sync stats/watch history with an SSH host
+subminer sync --snapshot ~/subminer-snapshot.sqlite  # Write a local DB snapshot
+subminer sync --merge ~/subminer-snapshot.sqlite     # Merge a snapshot into the local DB
 subminer dictionary /path/to/file-or-directory  # Generate character dictionary ZIP from target (manual Yomitan import)
 subminer dictionary --candidates /path/to/file.mkv
 subminer dictionary --select 21355 /path/to/file.mkv
@@ -132,6 +135,7 @@ SubMiner.AppImage --toggle-primary-subtitle-bar       # Toggle primary subtitle
 SubMiner.AppImage --start --dev                         # Enable app/dev mode only
 SubMiner.AppImage --start --debug                       # Alias for --dev
 SubMiner.AppImage --start --log-level debug             # Force verbose logging without app/dev mode
+SubMiner.AppImage --playback-feedback "your feedback"   # Route playback feedback through the configured feedback surface
 SubMiner.AppImage --yomitan               # Open Yomitan settings
 SubMiner.AppImage --settings              # Open SubMiner settings window
 SubMiner.AppImage --jellyfin              # Open Jellyfin setup window
@@ -147,7 +151,7 @@ SubMiner.AppImage --dictionary-select --dictionary-anilist-id 21355  # Pin corre
 SubMiner.AppImage --help                  # Show all options
 ```

-The tray menu includes `Export Logs`, which creates the same sanitized log ZIP as `subminer logs -e` and shows the archive path when complete.
+The tray menu includes `Export Logs`, which creates the same sanitized local-date log ZIP as `subminer logs -e` and shows the archive path when complete. Export sanitization masks common PII and secrets, including home-directory usernames, IP addresses, emails, auth/cookie headers, yt-dlp cookie arguments, URL credentials, token/key/password fields, and signed YouTube media URL query strings. The exported copy is sanitized; source log files remain unredacted on disk.

 Once Jellyfin is configured, the tray menu includes `Jellyfin Discovery` for starting or stopping cast discovery in the current app session without changing config.

@@ -163,6 +167,7 @@ Once Jellyfin is configured, the tray menu includes `Jellyfin Discovery` for sta
  Launcher pass-through commands also support `--password-store=<backend>` and forward it to the app when present.
  Override with e.g. `--password-store=basic_text`.
 - Use both when needed, for example `SubMiner.AppImage --start --dev --log-level debug` (or `SubMiner.exe --start --dev --log-level debug` on Windows).
+- `--playback-feedback <text>` (also `--playback-feedback=<text>`) sends a non-empty text string through the playback-feedback route used for recording/playback prompts. For example: `SubMiner.AppImage --playback-feedback "your feedback"`.

 ### Windows mpv Shortcut

@@ -189,9 +194,10 @@ This flow requires `mpv.exe` to be discoverable. Leave `mpv.executablePath` blan
 - `subminer jellyfin` / `subminer jf`: Jellyfin-focused workflow aliases.
 - `subminer doctor`: health checks for core dependencies and runtime paths.
 - `subminer settings`: open the SubMiner settings window (also `subminer --settings`).
- `subminer logs -e`: export a sanitized ZIP of today's logs, or the most recent logs when no current-day log exists.
+- `subminer logs -e`: export a sanitized ZIP of today's local-date logs, or the most recent logs when no current-day log exists. The exported copy masks common PII and secrets; on-disk logs are unchanged.
 - `subminer config`: config file helpers (`path`, `show`).
 - `subminer mpv`: mpv helpers (`status`, `socket`, `idle`).
+- `subminer sync <host>`: sync immersion stats and watch history with another machine over SSH. The host is the SSH destination (`user@host` or an SSH config alias). Use `--snapshot <file>` to write a consistent local stats DB snapshot, `--merge <file>` to merge a snapshot into the local stats DB, and `--force` to skip the running stats/mpv safety check. Advanced options: `--db <file>` overrides the local stats DB path, and `--remote-cmd <cmd>` overrides the `subminer` command used on the remote host.
 - `subminer dictionary <path>`: generates a Yomitan-importable character dictionary ZIP from a file/directory target.
 - Use `subminer dictionary --candidates <path>` and `subminer dictionary --select <id> <path>` to correct AniList character-dictionary matches for a whole series.
 - `subminer texthooker`: texthooker-only shortcut (same behavior as `--texthooker`). A _texthooker_ is a web page that displays the current subtitle line as selectable text, so browser-based dictionary extensions and other tools can read along with playback.
@@ -287,7 +293,7 @@ Notes:
 - For YouTube URLs, `subminer` probes available YouTube subtitle tracks, reuses existing authoritative tracks when available, and downloads only missing sides.
 - Native mpv secondary subtitle rendering stays hidden so the overlay remains the visible secondary subtitle surface.
 - Primary subtitle target languages come from `youtube.primarySubLanguages` (defaults to `["ja","jpn"]`).
- Secondary target languages come from `secondarySub.secondarySubLanguages` (empty by default; when empty, no language-based secondary track is auto-selected, though mpv's `--slang` list above still prefers English variants).
+- Secondary target languages come from `secondarySub.secondarySubLanguages` (empty by default; when empty, no language-based secondary track is auto-selected, though mpv's `--slang` list above still prefers English variants). When multiple matching secondary tracks exist, SubMiner prefers a non-Signs/Songs track.
 - Configure defaults in `$XDG_CONFIG_HOME/SubMiner/config.jsonc` (or `~/.config/SubMiner/config.jsonc`) under `youtube` and `secondarySub`.

 For local video files, SubMiner uses the same config-driven language priorities to auto-select the primary and secondary subtitle tracks from internal and external subtitle sources.
@@ -301,7 +307,7 @@ SubMiner supports gamepad/controller input for couch-friendly usage via the Chro
 1. Connect a controller before or after launching SubMiner.
 2. Set `controller.enabled` to `true` in your config.
 3. Press `Alt+C` in the overlay by default to pick the controller you want to save and remap any action inline.
-4. Enable keyboard-only mode — press `Y` on the controller (default binding) or use the overlay keybinding.
+4. Enable keyboard-only mode - press `Y` on the controller (default binding) or use the overlay keybinding.
 5. Click the binding badge, edit pencil, or `Learn` on the overlay action you want, then press the matching button, trigger, or stick direction on the controller.
 6. Use the left stick to navigate subtitle tokens and scroll the popup; use the right stick vertically for popup page jumps.
 7. Press `A` to look up the selected word, `X` to mine a card, `B` to close the popup.
@@ -333,7 +339,7 @@ By default SubMiner uses the first connected controller after controller support

 Learn mode ignores already-held inputs and waits for the next fresh button press or axis direction, which avoids accidental captures when you open the modal mid-input.

-All button and axis mappings are configurable under the `controller` config block. Learned remaps are saved under `controller.profiles` for the selected controller id. See [Configuration — Controller Support](/configuration#controller-support) for the full options.
+All button and axis mappings are configurable under the `controller` config block. Learned remaps are saved under `controller.profiles` for the selected controller id. See [Configuration - Controller Support](/configuration#controller-support) for the full options.

 ## Keybindings

@@ -361,4 +367,4 @@ Hovering over subtitle text pauses mpv by default; leaving resumes it. Yomitan p
 - Drop video files onto the overlay to replace current playback.
 - Hold `Shift` while dropping to append to the playlist instead.

-Next: [Mining Workflow](/mining-workflow) — word lookup, card creation, and the full mining loop.
+Next: [Mining Workflow](/mining-workflow) - word lookup, card creation, and the full mining loop.
@@ -1,6 +1,6 @@
 # WebSocket / Texthooker API & Integration

-**Who this page is for:** developers and tinkerers who want to consume SubMiner's live subtitle stream from their own tools — a browser tab, an automation script, or another mpv plugin. If you just want subtitles in a browser tab for Yomitan, skip to [Texthooker Integration Guide](#texthooker-integration-guide); the rest is reference for building custom clients.
+**Who this page is for:** developers and tinkerers who want to consume SubMiner's live subtitle stream from their own tools - a browser tab, an automation script, or another mpv plugin. If you just want subtitles in a browser tab for Yomitan, skip to [Texthooker Integration Guide](#texthooker-integration-guide); the rest is reference for building custom clients.

 A *texthooker* is a page/tool that receives the text currently on screen so a dictionary extension (like Yomitan) can look words up. SubMiner ships its own texthooker UI and also broadcasts subtitle text over local WebSockets that any client can connect to.

@@ -24,7 +24,7 @@ This page documents those integration points and shows how to build custom consu

 ## Enable and Configure the Services

-SubMiner's integration ports are configured in `config.jsonc`. All three services are **off by default** — the block below shows the values to set to turn them on.
+SubMiner's integration ports are configured in `config.jsonc`. All three services are **off by default** - the block below shows the values to set to turn them on.

 ```jsonc
 {
@@ -50,7 +50,7 @@ SubMiner's integration ports are configured in `config.jsonc`. All three service
 - `texthooker.launchAtStartup` defaults to `false`. Set it to `true` to start the local HTTP UI automatically.
 - `texthooker.openBrowser` controls whether SubMiner opens the texthooker page in your browser when it starts.

-If you use the [mpv plugin](/mpv-plugin), it can also start a texthooker-only helper process. The launcher derives the plugin's texthooker setting from your SubMiner config (`texthooker.launchAtStartup`) and injects it at runtime — there is no plugin config file to edit.
+If you use the [mpv plugin](/mpv-plugin), it can also start a texthooker-only helper process. The launcher derives the plugin's texthooker setting from your SubMiner config (`texthooker.launchAtStartup`) and injects it at runtime - there is no plugin config file to edit.

 ## Developer API Documentation

@@ -265,10 +265,10 @@ script-message subminer-options
 script-message subminer-restart
 script-message subminer-status
 script-message subminer-autoplay-ready
-script-message subminer-aniskip-refresh
-script-message subminer-skip-intro
 ```

+The AniSkip messages (`subminer-skip-intro`, `subminer-aniskip-refresh`) are handled by the SubMiner app over the mpv IPC socket while it is connected.
+
 The start command also accepts inline overrides:

 ```text
@@ -283,7 +283,7 @@ Examples:

 - send `subminer-start` after your own media-selection script chooses a file
 - send `subminer-status` before running follow-up automation
- send `subminer-aniskip-refresh` after you update title/episode metadata
+- send `subminer-aniskip-refresh` after you update title/episode metadata (handled by the SubMiner app)

 #### Build a launcher wrapper

@@ -368,7 +368,7 @@ ws.on('message', async (raw) => {
 ## Related Pages

 - [Configuration](/configuration#websocket-server)
- [Mining Workflow — Texthooker](/mining-workflow#texthooker)
+- [Mining Workflow - Texthooker](/mining-workflow#texthooker)
 - [MPV Plugin](/mpv-plugin)
 - [Launcher Script](/launcher-script)
 - [Anki Integration](/anki-integration#proxy-mode-setup-yomitan--texthooker)
@@ -4,8 +4,8 @@ SubMiner auto-loads Japanese subtitles when you play a YouTube URL, giving you t

 ## Requirements

- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** must be installed and on your `PATH`. yt-dlp is a free command-line tool that reads YouTube video and subtitle info; SubMiner calls it behind the scenes. (`PATH` is the list of folders your system searches for programs — most installers add yt-dlp to it automatically. If yours did not, set `SUBMINER_YTDLP_BIN` to the full path of the yt-dlp binary.)
- mpv with `--input-ipc-server` configured (handled automatically when you launch playback through the `subminer` launcher — no manual setup needed).
+- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** must be installed and on your `PATH`. yt-dlp is a free command-line tool that reads YouTube video and subtitle info; SubMiner calls it behind the scenes. (`PATH` is the list of folders your system searches for programs - most installers add yt-dlp to it automatically. If yours did not, set `SUBMINER_YTDLP_BIN` to the full path of the yt-dlp binary.)
+- mpv with `--input-ipc-server` configured (handled automatically when you launch playback through the `subminer` launcher - no manual setup needed).

 ## How It Works

@@ -32,7 +32,7 @@ flowchart TD
    C[Track discovery]:::action
    D{Auto or manual selection?}:::step
    E[Auto-select best tracks]:::action
-    F[Manual picker — Ctrl+Alt+C]:::action
+    F[Manual picker - Ctrl+Alt+C]:::action
    G[Download subtitle files]:::action
    H[Convert TimedText to VTT]:::enrich
    I[Normalize auto-caption duplicates]:::enrich
@@ -74,20 +74,30 @@ Press **Ctrl+Alt+C** during YouTube playback to open the subtitle picker overlay
 - Select different primary and secondary tracks
 - Retry track loading if the auto-load failed or picked the wrong track

+SubMiner shows an "Opening YouTube subtitle picker..." status through your configured notification
+surface while it probes tracks and prepares the modal, then updates the subtitle download progress
+card to a success notification after the selected tracks load.
+
 The picker displays each track with its language, kind (manual/auto), and title when available.

 ## Subtitle Format Handling

 SubMiner handles several YouTube subtitle formats transparently:

-| Format | Handling |
-| ------ | -------- |
-| `srt`, `vtt` | Used directly (preferred for manual tracks) |
+| Format                 | Handling                                                 |
+| ---------------------- | -------------------------------------------------------- |
+| `srt`, `vtt`           | Used directly (preferred for manual tracks)              |
 | `srv1`, `srv2`, `srv3` | YouTube TimedText XML --- converted to VTT automatically |
-| Auto-generated VTT | Normalized to remove rolling-caption text duplication |
+| Auto-generated VTT     | Normalized to remove rolling-caption text duplication    |

 For auto-generated tracks, SubMiner prefers `srv3` > `srv2` > `srv1` > `vtt` (TimedText XML produces cleaner output). For manual tracks, `srt` > `vtt` is preferred.

+## Card Media Cache
+
+By default, YouTube card audio and screenshots are extracted directly from mpv's active stream URLs. If generated card media fails with YouTube `403` errors, set `youtube.mediaCache.mode` to `"background"`. Background mode starts a separate `yt-dlp` media download after playback loads, including YouTube URLs opened directly in mpv and resolved stream URLs when mpv still exposes the original YouTube playlist entry. It creates text fields immediately, queues audio/image work for mined notes, and fills those fields once the local cache file is ready.
+
+Background cache downloads use IPv4 and retry flags to reduce YouTube throttling failures. If the background download still fails, SubMiner shows a cache failure notification, shows queued-card failure notifications, and clears those pending updates so cards are not left waiting silently.
+
 ## Configuration Reference

 ### Primary Subtitle Languages
@@ -95,13 +105,13 @@ For auto-generated tracks, SubMiner prefers `srv3` > `srv2` > `srv1` > `vtt` (Ti
 ```jsonc
 {
  "youtube": {
-    "primarySubLanguages": ["ja", "jpn"]
-  }
+    "primarySubLanguages": ["ja", "jpn"],
+  },
 }
 ```

-| Option | Type | Description |
-| ------ | ---- | ----------- |
+| Option                | Type       | Description                                                                           |
+| --------------------- | ---------- | ------------------------------------------------------------------------------------- |
 | `primarySubLanguages` | `string[]` | Language priority for YouTube primary subtitle auto-loading (default `["ja", "jpn"]`) |

 ### Secondary Subtitle Languages
@@ -113,16 +123,16 @@ Secondary track selection uses the shared `secondarySub` config:
  "secondarySub": {
    "secondarySubLanguages": [],
    "autoLoadSecondarySub": false,
-    "defaultMode": "hover"
-  }
+    "defaultMode": "hover",
+  },
 }
 ```

-| Option | Type | Description |
-| ------ | ---- | ----------- |
-| `secondarySubLanguages` | `string[]` | Extra language codes (e.g. `["eng", "en"]`) used when auto-selecting a secondary track. Default is empty (`[]`). For YouTube, SubMiner always tries an English track first regardless of this list. |
-| `autoLoadSecondarySub` | `boolean` | Auto-detect and load a matching secondary track (default: `false`) |
-| `defaultMode` | `"hidden"` / `"visible"` / `"hover"` | Initial display mode for secondary subtitles (default: `"hover"`) |
+| Option                  | Type                                 | Description                                                                                                                                                                                         |
+| ----------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `secondarySubLanguages` | `string[]`                           | Extra language codes (e.g. `["eng", "en"]`) used when auto-selecting a secondary track. Default is empty (`[]`). For YouTube, SubMiner always tries an English track first regardless of this list. |
+| `autoLoadSecondarySub`  | `boolean`                            | Auto-detect and load a matching secondary track (default: `false`)                                                                                                                                  |
+| `defaultMode`           | `"hidden"` / `"visible"` / `"hover"` | Initial display mode for secondary subtitles (default: `"hover"`)                                                                                                                                   |

 Precedence: CLI flag > environment variable > `config.jsonc` > built-in default.

@@ -131,6 +141,7 @@ Precedence: CLI flag > environment variable > `config.jsonc` > built-in default.
 - **No subtitles found**: The video may not have Japanese subtitles. Open the picker with `Ctrl+Alt+C` to see all available tracks.
 - **yt-dlp not found**: Install `yt-dlp` and ensure it is on `PATH`, or set `SUBMINER_YTDLP_BIN` to the binary path.
 - **Probe timeout**: `yt-dlp` has a 15-second timeout per operation. Slow connections or rate-limited IPs may hit this. Retry or update `yt-dlp`.
+- **Card media `403` errors**: Switch `youtube.mediaCache.mode` from `"direct"` to `"background"` so card media is generated from a local `yt-dlp` cache instead of ffmpeg reading an expiring YouTube stream URL.
 - **Auto-caption quality**: YouTube auto-generated captions vary in quality. Manual subtitles (when available) are always preferred.
 - **`ytsearch:` targets**: `subminer ytsearch:"keyword"` plays the first search result. Subtitle availability depends on the matched video.
 - **Secondary subtitle fails**: Secondary track failures never block playback. The primary subtitle loads independently.
@@ -61,8 +61,10 @@
   committed file — so review it before committing. If you add more
   `changes/*.md` fragments for a later beta/RC, rerun
   `bun run changelog:prerelease-notes --version <version>`; the generator uses
-   the existing prerelease notes as the baseline and asks Claude to merge only
-   the new fragment material. Do not run `bun run changelog:build`.
+   the existing prerelease notes as the baseline only when their hidden
+   `prerelease-base-version` marker matches the current base version, and asks
+   Claude to merge only the new fragment material. Do not run
+   `bun run changelog:build`.
 6. Tag the commit: `git tag v<version>`.
 7. Push commit + tag.

@@ -77,6 +79,7 @@ Notes:
 - `changelog:check` now rejects tag/package version mismatches.
 - `changelog:prerelease-notes` also rejects tag/package version mismatches and writes `release/prerelease-notes.md` without mutating tracked changelog files. When that file already exists, the generator includes it in the Claude prompt so later beta/RC notes reuse the reviewed text instead of starting over.
 - `changelog:build` generates `CHANGELOG.md` + `release/release-notes.md` (both polished by `claude -p`) and removes the released `changes/*.md` fragments. The CHANGELOG keeps internal notes inside a `<details><summary>Internal changes</summary>` collapse; the release notes drop them entirely.
+- `release/release-notes.md` (and `release/prerelease-notes.md`) include GitHub-style attribution after `## Highlights`: a `## What's Changed` list crediting each released fragment as `by @<author> in #<pr>`, plus a `## New Contributors` section for first-time authors. Attribution is resolved per fragment via `git log` (the commit that added the fragment) + `gh api .../commits/<sha>/pulls`, with one `gh` search per author for the first-contribution check. It needs `gh` installed and authenticated; if `gh` is unavailable or a lookup fails, the generator warns and emits notes without the attribution sections rather than failing. The CHANGELOG itself stays attribution-free.
 - The release workflow no longer auto-runs `changelog:build`. If pending `changes/*.md` fragments are present on a tag-based run, CI exits with a clear `::error::` pointing at the local fix. Run `bun run changelog:build --version <version>` locally, commit the polished output, then tag.
 - Do not tag while `changes/*.md` fragments still exist.
 - Prerelease tags intentionally keep `changes/*.md` fragments in place so multiple prereleases can reuse the same cumulative pending notes until the final stable cut. `make clean` preserves `release/prerelease-notes.md` while deleting generated build artifacts.
@@ -61,7 +61,7 @@ External subtitle files only (SRT, VTT, ASS). Embedded subtitle tracks are out o

 #### Subtitle File Parsing

-A new cue parser that extracts both timing and text content from subtitle files. The existing `parseSrtOrVttStartTimes` in `subtitle-delay-shift.ts` only extracts timing; this needs a companion that also extracts the dialogue text.
+A cue parser extracts both timing and text content from subtitle files for prefetching.

 **Parsed cue structure:**
 ```typescript
@@ -3,7 +3,7 @@
 # Subtitle Overlay Priming

 Status: active
-Last verified: 2026-06-01
+Last verified: 2026-06-14
 Owner: Kyle Yasuda
 Read when: debugging subtitle state or blank Linux/X11 overlay windows when the visible overlay is shown or recreated

@@ -64,6 +64,35 @@ prefetch work and re-centers prefetch around the live playback time.
 - If secondary `requestProperty` fails, the primary flow stays complete and only a debug line is
  written.

+## Startup Ready Release
+
+- `mpv.pauseUntilOverlayReady` waits for tokenization warmup plus visible-overlay readiness before
+  releasing the mpv startup gate.
+- Visible-overlay startup creates the tray and visible overlay shell before tokenization and
+  annotation warmups continue. Cold `--start --background --managed-playback` launches still handle
+  initial args before the deferred Yomitan wait.
+- Overlay-routed startup notifications are queued in the main process until an overlay window has
+  finished loading. Progress notifications with the same id are upserted so spinner ticks do not
+  flood a cold-start overlay, while events with distinct history ids are retained for phase-level
+  history such as character dictionary checking/building/importing.
+- The mpv plugin has a 30-second fallback for cold starts; app-side retry/release budgets match that
+  window so readiness can still arrive before fallback resumes playback.
+- If mpv is already on a subtitle, SubMiner still prefers the resolved current subtitle payload and
+  waits for a fresh measured subtitle rectangle before signaling readiness.
+- If the startup subtitle has no cached annotations yet, autoplay priming emits a raw first-paint
+  subtitle payload before background tokenization. The tokenized payload replaces it when ready, but
+  the visible overlay can paint and measure the line before the mpv startup gate resumes playback.
+- If startup `sub-text` is temporarily empty, autoplay priming refreshes the active subtitle source
+  and then awaits cue-based priming before synthetic warm readiness can proceed. A parsed current or
+  imminent cue is treated as the startup subtitle so the visible overlay can paint and measure it
+  before playback resumes.
+- If mpv is before the first subtitle, SubMiner sends a synthetic warm readiness payload after
+  tokenization warmup and visible overlay content-ready. This releases playback without waiting for
+  a later subtitle event that cannot happen while mpv is paused.
+- After a synthetic warm readiness release, SubMiner briefly polls/refreshes the current subtitle
+  again. This covers Linux/mpv startup cases where `sub-text` is still empty while paused but becomes
+  available right after playback resumes, without waiting for the next subtitle property change.
+
 ## Linux/X11 Window Shape

 - `restoreLinuxOverlayWindowShape()` reads `BrowserWindow.getBounds()` and calls `setShape()` with
@@ -76,6 +105,15 @@ prefetch work and re-centers prefetch around the live playback time.
  overlay window remained mapped above mpv.
 - Pointer pass-through should continue to use `setIgnoreMouseEvents(true, { forward: true })` and
  the Linux cursor-poll fallback, not bounding-shape clipping.
+- Visible-overlay show/reset marks Linux pointer passthrough state dirty even when the logical
+  interaction state is already inactive. The next cursor-poll tick must still reapply
+  `setIgnoreMouseEvents(true, { forward: true })`; otherwise a newly shown Electron overlay can keep
+  full-window input capture and block both mpv and overlay controls before the first subtitle
+  measurement.
+- Visible-overlay show also starts a short Linux input grace before the first content measurement.
+  Native Wayland surfaces can become inert while `setIgnoreMouseEvents(true)` is active; keeping the
+  overlay interactive during this startup gap lets notifications and overlay mouse bindings work
+  until subtitle/sidebar/notification rectangles are reported.

 ## Config And Migration

@@ -0,0 +1,29 @@
+<!-- read_when: changing managed mpv startup, pause-until-ready, or visible overlay boot ordering -->
+
+# Early Managed Overlay Startup Design
+
+Status: approved
+Date: 2026-06-06
+
+## Problem
+
+Managed mpv startup can pause playback immediately, then leave SubMiner's tray and visible overlay
+unavailable until Yomitan/tokenization warmups finish. Startup notifications therefore miss the
+overlay surface and fall back to non-overlay status paths.
+
+## Chosen Approach
+
+For cold `--start --background --managed-playback` launches, handle initial args before waiting for
+the deferred overlay warmup. That lets the tray and visible overlay shell initialize immediately
+while the existing tokenization warmups continue in the background.
+
+The mpv plugin pause gate stays armed. Playback release still waits for SubMiner's autoplay-ready
+signal, which is emitted only after tokenization warmup and visible-overlay readiness. Existing
+second-instance attach behavior remains unchanged: when the launcher finds an already-running
+background app, it sends the same control command to that process and reuses its warmups/tokenizer.
+
+## Checks
+
+- Add a startup ordering regression test for managed background playback.
+- Keep the existing deferred startup ordering for non-managed launches.
+- Run the startup/runtime test slice plus SubMiner verification lane.
@@ -0,0 +1,27 @@
+<!-- read_when: changing overlay notification hover, macOS mouse passthrough, or notification actions -->
+
+# macOS Notification Hover Stability Design
+
+Status: approved
+Date: 2026-06-09
+
+## Problem
+
+On macOS, hovering a character dictionary build notification can make the card flicker and slide as
+if it is hiding, then snap back. The likely trigger is the notification stack changing the overlay
+window's mouse-passthrough state for a progress card that has no user action.
+
+## Chosen Approach
+
+Keep non-action overlay notifications visually stable and click-through on hover. Only notifications
+with explicit actions should request interactive overlay input. The notification history panel keeps
+its existing interactive behavior.
+
+This avoids a macOS mouseenter/mouseleave passthrough loop for passive progress cards while
+preserving clickable notification actions.
+
+## Checks
+
+- Add a renderer regression test for passive notification hover.
+- Keep action-bearing notification cards interactive.
+- Run the targeted overlay notification and mouse-ignore tests.
@@ -3,10 +3,22 @@
 # Verification

 Status: active  
-Last verified: 2026-05-23  
+Last verified: 2026-07-06  
 Owner: Kyle Yasuda  
 Read when: selecting the right verification lane for a change

+## Lane Infrastructure
+
+- Lane membership is defined once in `scripts/test-lanes.ts` and discovered by
+  directory — new test files join their lane automatically; never hand-list test
+  files in `package.json`.
+- `scripts/run-test-lane.mjs` runs each test file in its own `bun test` process
+  (per-file isolation with a wall timeout) so a hanging test or leaked global in
+  one file cannot cascade into the rest of the lane. `--jobs N` parallelizes;
+  `--single-process` restores the shared-process mode for debugging.
+- `bun run test:fast` is the full source gate: discovered `src/**`, launcher
+  unit, `scripts/**`, and the compiled runtime-compat slice.
+
 ## Default Handoff Gate

 ```bash
@@ -31,6 +43,8 @@ bun run docs:build
 - Config/schema/defaults: `bun run test:config`, then `bun run generate:config-example` if template/defaults changed
 - Launcher/plugin: `bun run test:launcher` or `bun run test:env`
 - Runtime-compat / compiled behavior: `bun run test:runtime:compat`
+- Stats dashboard UI: `bun run test:stats`
+- Build/release scripts (`scripts/**`): `bun run test:scripts`
 - Coverage for the maintained source lane: `bun run test:coverage:src`
 - Deep/local full gate: default handoff gate above

@@ -0,0 +1,30 @@
+// Minimal ambient typing for bun:sqlite. The launcher always runs under bun
+// (see the build banner in package.json), but the repo typechecks with plain
+// tsc which has no bun type definitions.
+declare module 'bun:sqlite' {
+  export interface RunResult {
+    changes: number;
+    lastInsertRowid: number | bigint;
+  }
+
+  export interface Statement<ReturnType = unknown, ParamsType extends unknown[] = unknown[]> {
+    all(...params: ParamsType): ReturnType[];
+    get(...params: ParamsType): ReturnType | undefined;
+    run(...params: ParamsType): RunResult;
+  }
+
+  export class Database {
+    constructor(
+      filename: string,
+      options?: { readonly?: boolean; readwrite?: boolean; create?: boolean },
+    );
+    query<ReturnType = unknown, ParamsType extends unknown[] = unknown[]>(
+      sql: string,
+    ): Statement<ReturnType, ParamsType>;
+    prepare<ReturnType = unknown, ParamsType extends unknown[] = unknown[]>(
+      sql: string,
+    ): Statement<ReturnType, ParamsType>;
+    run(sql: string, ...params: unknown[]): RunResult;
+    close(throwOnError?: boolean): void;
+  }
+}
@@ -7,7 +7,7 @@ import { runConfigCommand } from './config-command.js';
 import { runDictionaryCommand } from './dictionary-command.js';
 import { runDoctorCommand } from './doctor-command.js';
 import { runLogsCommand } from './logs-command.js';
-import { runMpvPreAppCommand } from './mpv-command.js';
+import { runMpvPostAppCommand, runMpvPreAppCommand } from './mpv-command.js';
 import { runAppPassthroughCommand } from './app-command.js';
 import { runStatsCommand } from './stats-command.js';
 import { runUpdateCommand } from './update-command.js';
@@ -45,9 +45,8 @@ function createContext(overrides: Partial<LauncherCommandContext> = {}): Launche
      autoStart: true,
      autoStartVisibleOverlay: true,
      autoStartPauseUntilReady: true,
+      osdMessages: false,
      texthookerEnabled: false,
-      aniskipEnabled: true,
-      aniskipButtonKey: 'TAB',
    },
    appPath: '/tmp/subminer.app',
    launcherJellyfinConfig: {},
@@ -263,7 +262,9 @@ test('mpv pre-app command exits non-zero when socket is not ready', async () =>
  await assert.rejects(
    async () => {
      await runMpvPreAppCommand(context, {
+        ensureRuntimePluginReady: async () => {},
        waitForUnixSocketReady: async () => false,
+        resolveRuntimePluginPath: () => null,
        launchMpvIdleDetached: async () => {},
      });
    },
@@ -271,6 +272,32 @@ test('mpv pre-app command exits non-zero when socket is not ready', async () =>
  );
 });

+test('mpv idle command ensures Linux runtime plugin before detached launch', async () => {
+  const context = createContext();
+  context.args.mpvIdle = true;
+  const calls: string[] = [];
+
+  const handled = await runMpvPostAppCommand(context, {
+    ensureRuntimePluginReady: async () => {
+      calls.push('plugin');
+    },
+    waitForUnixSocketReady: async () => {
+      calls.push('wait');
+      return true;
+    },
+    launchMpvIdleDetached: async () => {
+      calls.push('launch');
+    },
+    resolveRuntimePluginPath: () => {
+      calls.push('resolve');
+      return '/tmp/plugin/main.lua';
+    },
+  });
+
+  assert.equal(handled, true);
+  assert.deepEqual(calls, ['plugin', 'resolve', 'launch', 'wait']);
+});
+
 test('dictionary command forwards --dictionary and target path to app binary', () => {
  const context = createContext();
  context.args.dictionary = true;
@@ -362,7 +389,7 @@ test('update command runs direct Linux release update without launching Electron
    'direct:/tmp/subminer.app:/tmp/subminer:stable',
    'info:AppImage update: not-found',
    'info:Launcher update: updated',
-    'info:Rofi theme update: skipped',
+    'info:Support assets update: skipped',
  ]);
 });

@@ -0,0 +1,228 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fail, log } from '../log.js';
+import { commandExists } from '../util.js';
+import {
+  collectVideos,
+  findRofiTheme,
+  formatPickerLaunchError,
+  showFzfMenu,
+  showRofiMenu,
+} from '../picker.js';
+import {
+  findNextEpisode,
+  groupHistoryBySeries,
+  listSeasonDirs,
+  materializeCoverArt,
+  queryLocalWatchHistory,
+  resolveImmersionDbPath,
+  sortVideosByEpisode,
+  type HistorySeriesEntry,
+} from '../history.js';
+import type { Args } from '../types.js';
+import type { LauncherCommandContext } from './context.js';
+
+function checkPickerDependencies(args: Args): void {
+  if (args.useRofi) {
+    if (!commandExists('rofi')) fail('Missing dependency: rofi');
+    return;
+  }
+  if (!commandExists('fzf')) fail('Missing dependency: fzf');
+}
+
+function showRofiIndexMenu(
+  labels: string[],
+  prompt: string,
+  themePath: string | null,
+  icons: Array<string | null> = [],
+): number {
+  const rofiArgs = ['-dmenu', '-i', '-matching', 'fuzzy', '-format', 'i', '-p', prompt];
+  const hasIcons = icons.some(Boolean);
+  if (hasIcons) rofiArgs.push('-show-icons');
+  if (themePath) {
+    rofiArgs.push('-theme', themePath);
+  } else {
+    rofiArgs.push('-theme-str', 'configuration { font: "Noto Sans CJK JP Regular 8";}');
+  }
+  if (hasIcons) {
+    rofiArgs.push('-theme-str', 'configuration { show-icons: true; }');
+    rofiArgs.push('-theme-str', 'element-icon { enabled: true; size: 3em; }');
+  }
+  const lines = labels.map((label, index) =>
+    icons[index] ? `${label}\u0000icon\u001f${icons[index]}` : label,
+  );
+  const result = spawnSync('rofi', rofiArgs, {
+    input: `${lines.join('\n')}\n`,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'ignore'],
+  });
+  if (result.error) {
+    fail(formatPickerLaunchError('rofi', result.error as NodeJS.ErrnoException));
+  }
+  const out = (result.stdout || '').trim();
+  if (!out) return -1;
+  const idx = Number.parseInt(out, 10);
+  return Number.isInteger(idx) && idx >= 0 && idx < labels.length ? idx : -1;
+}
+
+function showFzfIndexMenu(labels: string[], prompt: string): number {
+  const lines = labels.map((label, index) => `${index}\t${label}`);
+  const result = spawnSync(
+    'fzf',
+    [
+      '--ansi',
+      '--reverse',
+      '--ignore-case',
+      `--prompt=${prompt}: `,
+      '--delimiter=\t',
+      '--with-nth=2..',
+    ],
+    {
+      input: `${lines.join('\n')}\n`,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'inherit'],
+    },
+  );
+  if (result.error) {
+    fail(formatPickerLaunchError('fzf', result.error as NodeJS.ErrnoException));
+  }
+  const picked = (result.stdout || '').trim();
+  const tab = picked.indexOf('\t');
+  if (tab === -1) return -1;
+  const idx = Number.parseInt(picked.slice(0, tab), 10);
+  return Number.isInteger(idx) && idx >= 0 && idx < labels.length ? idx : -1;
+}
+
+function pickIndex(
+  labels: string[],
+  prompt: string,
+  useRofi: boolean,
+  themePath: string | null,
+  icons: Array<string | null> = [],
+): number {
+  if (labels.length === 0) return -1;
+  return useRofi
+    ? showRofiIndexMenu(labels, prompt, themePath, icons)
+    : showFzfIndexMenu(labels, prompt);
+}
+
+function formatEpisodeLabel(entry: HistorySeriesEntry): string {
+  const { parsedSeason, parsedEpisode } = entry.lastWatched;
+  if (parsedEpisode === null) return '';
+  return parsedSeason !== null ? `S${parsedSeason}E${parsedEpisode}` : `E${parsedEpisode}`;
+}
+
+function formatSeriesLabel(entry: HistorySeriesEntry): string {
+  const episodeLabel = formatEpisodeLabel(entry);
+  return episodeLabel ? `${entry.displayName}  [last: ${episodeLabel}]` : entry.displayName;
+}
+
+function pickEpisodeFromDir(dir: string, context: LauncherCommandContext): string | null {
+  const { args, scriptPath } = context;
+  const videos = sortVideosByEpisode(collectVideos(dir, false));
+  if (videos.length === 0) {
+    fail(`No video files found in: ${dir}`);
+  }
+  const selected = args.useRofi
+    ? showRofiMenu(videos, dir, false, scriptPath, args.logLevel)
+    : showFzfMenu(videos);
+  return selected || null;
+}
+
+function browseEpisodes(
+  entry: HistorySeriesEntry,
+  context: LauncherCommandContext,
+  themePath: string | null,
+): string | null {
+  const { args } = context;
+  const seasons = listSeasonDirs(entry.seriesRoot);
+  let dir = entry.seriesRoot;
+
+  if (seasons.length > 1) {
+    const idx = pickIndex(
+      seasons.map((season) => season.name),
+      `${entry.displayName} — Season`,
+      args.useRofi,
+      themePath,
+    );
+    if (idx < 0) return null;
+    dir = seasons[idx]!.path;
+  } else if (seasons.length === 1 && collectVideos(dir, false).length === 0) {
+    dir = seasons[0]!.path;
+  }
+
+  return pickEpisodeFromDir(dir, context);
+}
+
+export async function runHistoryCommand(context: LauncherCommandContext): Promise<string | null> {
+  const { args, scriptPath } = context;
+
+  checkPickerDependencies(args);
+  const themePath = args.useRofi ? findRofiTheme(scriptPath) : null;
+
+  const dbPath = resolveImmersionDbPath();
+  if (!fs.existsSync(dbPath)) {
+    fail(`Watch history database not found: ${dbPath}`);
+  }
+
+  const rows = queryLocalWatchHistory(dbPath);
+  const series = groupHistoryBySeries(rows);
+  if (series.length === 0) {
+    fail('No local watch history found (or watched directories are not accessible).');
+  }
+
+  log('info', args.logLevel, `Watch history: ${series.length} series found in ${dbPath}`);
+
+  const coverPaths = args.useRofi
+    ? materializeCoverArt(
+        dbPath,
+        series.map((seriesEntry) => seriesEntry.coverBlobHash),
+      )
+    : new Map<string, string>();
+  const seriesIcons = series.map((seriesEntry) =>
+    seriesEntry.coverBlobHash ? (coverPaths.get(seriesEntry.coverBlobHash) ?? null) : null,
+  );
+
+  const seriesIdx = pickIndex(
+    series.map(formatSeriesLabel),
+    'Watch History',
+    args.useRofi,
+    themePath,
+    seriesIcons,
+  );
+  if (seriesIdx < 0) return null;
+  const entry = series[seriesIdx]!;
+
+  const lastPath = path.resolve(entry.lastWatched.sourcePath);
+  const lastExists = fs.existsSync(lastPath);
+  const nextEpisode = findNextEpisode(lastPath);
+
+  const actions: Array<{ kind: 'replay' | 'next' | 'browse'; label: string }> = [];
+  if (lastExists) {
+    actions.push({ kind: 'replay', label: `Replay last watched — ${path.basename(lastPath)}` });
+  }
+  if (nextEpisode) {
+    actions.push({ kind: 'next', label: `Next episode — ${path.basename(nextEpisode)}` });
+  }
+  actions.push({ kind: 'browse', label: 'Browse episodes' });
+
+  const entryIcon = seriesIcons[seriesIdx] ?? null;
+  const actionIdx = pickIndex(
+    actions.map((action) => action.label),
+    entry.displayName,
+    args.useRofi,
+    themePath,
+    actions.map(() => entryIcon),
+  );
+  if (actionIdx < 0) return null;
+
+  switch (actions[actionIdx]!.kind) {
+    case 'replay':
+      return lastPath;
+    case 'next':
+      return nextEpisode;
+    case 'browse':
+      return browseEpisodes(entry, context, themePath);
+  }
+}
@@ -5,9 +5,12 @@ import {
  resolveLauncherRuntimePluginPath,
 } from '../mpv.js';
 import type { LauncherCommandContext } from './context.js';
+import { ensureLinuxRuntimePluginAvailable } from '../runtime-plugin-preflight.js';

 interface MpvCommandDeps {
+  ensureRuntimePluginReady(context: LauncherCommandContext): Promise<void>;
  waitForUnixSocketReady(socketPath: string, timeoutMs: number): Promise<boolean>;
+  resolveRuntimePluginPath(context: LauncherCommandContext): string | null;
  launchMpvIdleDetached(
    socketPath: string,
    appPath: string,
@@ -18,7 +21,19 @@ interface MpvCommandDeps {
 }

 const defaultDeps: MpvCommandDeps = {
+  ensureRuntimePluginReady: async (context) => {
+    await ensureLinuxRuntimePluginAvailable({
+      appPath: context.appPath ?? undefined,
+      scriptPath: context.scriptPath,
+      logLevel: context.args.logLevel,
+    });
+  },
  waitForUnixSocketReady,
+  resolveRuntimePluginPath: (context) =>
+    resolveLauncherRuntimePluginPath({
+      appPath: context.appPath ?? '',
+      scriptPath: context.scriptPath,
+    }),
  launchMpvIdleDetached,
 };

@@ -58,11 +73,12 @@ export async function runMpvPostAppCommand(
    fail('SubMiner app binary not found. Install to ~/.local/bin/ or set SUBMINER_APPIMAGE_PATH.');
  }

+  await deps.ensureRuntimePluginReady(context);
  await deps.launchMpvIdleDetached(
    mpvSocketPath,
    appPath,
    args,
-    resolveLauncherRuntimePluginPath({ appPath, scriptPath }),
+    deps.resolveRuntimePluginPath(context),
    {
      ...pluginRuntimeConfig,
      backend: args.backend,
@@ -35,6 +35,14 @@ function createContext(): LauncherCommandContext {
      texthookerOnly: false,
      texthookerOpenBrowser: false,
      useRofi: false,
+      history: false,
+      sync: false,
+      syncHost: '',
+      syncSnapshotPath: '',
+      syncMergePath: '',
+      syncRemoteCmd: '',
+      syncDbPath: '',
+      syncForce: false,
      logLevel: 'info',
      logRotation: 7,
      passwordStore: '',
@@ -82,9 +90,8 @@ function createContext(): LauncherCommandContext {
      autoStart: true,
      autoStartVisibleOverlay: true,
      autoStartPauseUntilReady: true,
+      osdMessages: false,
      texthookerEnabled: false,
-      aniskipEnabled: true,
-      aniskipButtonKey: 'TAB',
    },
    appPath: '/tmp/SubMiner.AppImage',
    launcherJellyfinConfig: {},
@@ -113,6 +120,7 @@ test('youtube playback launches overlay with app-owned youtube flow args', async

  await runPlaybackCommandWithDeps(context, {
    ensurePlaybackSetupReady: async () => {},
+    ensureRuntimePluginReady: async () => {},
    chooseTarget: async (_args, _scriptPath) => ({ target: context.args.target, kind: 'url' }),
    checkDependencies: () => {},
    registerCleanup: () => {},
@@ -162,6 +170,7 @@ test('youtube app-owned playback disables mpv plugin auto-start', async () => {

  await runPlaybackCommandWithDeps(context, {
    ensurePlaybackSetupReady: async () => {},
+    ensureRuntimePluginReady: async () => {},
    chooseTarget: async () => ({ target: context.args.target, kind: 'url' }),
    checkDependencies: () => {},
    registerCleanup: () => {},
@@ -209,9 +218,8 @@ test('plugin auto-start playback leaves app lifetime to managed-playback owner',
    autoStart: true,
    autoStartVisibleOverlay: false,
    autoStartPauseUntilReady: false,
+    osdMessages: false,
    texthookerEnabled: false,
-    aniskipEnabled: true,
-    aniskipButtonKey: 'TAB',
  };
  const appPath = context.appPath ?? '';
  state.appPath = appPath;
@@ -229,6 +237,7 @@ test('plugin auto-start playback leaves app lifetime to managed-playback owner',
  try {
    await runPlaybackCommandWithDeps(context, {
      ensurePlaybackSetupReady: async () => {},
+      ensureRuntimePluginReady: async () => {},
      chooseTarget: async () => ({ target: context.args.target, kind: 'file' }),
      checkDependencies: () => {},
      registerCleanup: () => {},
@@ -272,15 +281,15 @@ test('plugin auto-start playback attaches a warm background app through the laun
    autoStart: true,
    autoStartVisibleOverlay: true,
    autoStartPauseUntilReady: true,
+    osdMessages: false,
    texthookerEnabled: true,
-    aniskipEnabled: true,
-    aniskipButtonKey: 'TAB',
  };
  const calls: string[] = [];
  const receivedStartMpvOptions: Record<string, unknown>[] = [];

  await runPlaybackCommandWithDeps(context, {
    ensurePlaybackSetupReady: async () => {},
+    ensureRuntimePluginReady: async () => {},
    chooseTarget: async () => ({ target: context.args.target, kind: 'file' }),
    checkDependencies: () => {},
    registerCleanup: () => {},
@@ -341,12 +350,12 @@ test('plugin auto-start attach mode reuses launcher-resolved config dir for app
    autoStart: true,
    autoStartVisibleOverlay: true,
    autoStartPauseUntilReady: true,
+    osdMessages: false,
    texthookerEnabled: true,
-    aniskipEnabled: true,
-    aniskipButtonKey: 'TAB',
  };
  let availabilityConfigDir: string | undefined;
  let overlayConfigDir: string | undefined;
+  let overlayLoadingOsd: boolean | undefined;

  try {
    process.env.XDG_CONFIG_HOME = xdgConfigHome;
@@ -354,10 +363,23 @@ test('plugin auto-start attach mode reuses launcher-resolved config dir for app

    await runPlaybackCommandWithDeps(context, {
      ensurePlaybackSetupReady: async () => {},
+      ensureRuntimePluginReady: async () => {},
      chooseTarget: async () => ({ target: context.args.target, kind: 'file' }),
      checkDependencies: () => {},
      registerCleanup: () => {},
-      startMpv: async () => {},
+      startMpv: async (
+        _target,
+        _targetKind,
+        _args,
+        _socketPath,
+        _appPath,
+        _preloadedSubtitles,
+        options,
+      ) => {
+        overlayLoadingOsd = (
+          options?.runtimePluginConfig as { overlayLoadingOsd?: boolean } | undefined
+        )?.overlayLoadingOsd;
+      },
      waitForUnixSocketReady: async () => true,
      startOverlay: async (_appPath, _args, _socketPath, _extraAppArgs = [], configDir) => {
        overlayConfigDir = configDir;
@@ -374,6 +396,7 @@ test('plugin auto-start attach mode reuses launcher-resolved config dir for app

    assert.equal(availabilityConfigDir, expectedConfigDir);
    assert.equal(overlayConfigDir, expectedConfigDir);
+    assert.equal(overlayLoadingOsd, true);
  } finally {
    if (originalXdgConfigHome === undefined) {
      delete process.env.XDG_CONFIG_HOME;
@@ -403,14 +426,14 @@ test('plugin auto-start attach mode omits texthooker flag when CLI texthooker is
    autoStart: true,
    autoStartVisibleOverlay: true,
    autoStartPauseUntilReady: true,
+    osdMessages: false,
    texthookerEnabled: true,
-    aniskipEnabled: true,
-    aniskipButtonKey: 'TAB',
  };
  const calls: string[] = [];

  await runPlaybackCommandWithDeps(context, {
    ensurePlaybackSetupReady: async () => {},
+    ensureRuntimePluginReady: async () => {},
    chooseTarget: async () => ({ target: context.args.target, kind: 'file' }),
    checkDependencies: () => {},
    registerCleanup: () => {},
@@ -432,3 +455,34 @@ test('plugin auto-start attach mode omits texthooker flag when CLI texthooker is

  assert.deepEqual(calls, ['startMpv', 'startOverlay:--show-visible-overlay']);
 });
+
+test('playback command ensures Linux runtime plugin before mpv launch', async () => {
+  const context = createContext();
+  context.args = {
+    ...context.args,
+    target: '/tmp/movie.mkv',
+    targetKind: 'file',
+  };
+  const calls: string[] = [];
+
+  await runPlaybackCommandWithDeps(context, {
+    ensurePlaybackSetupReady: async () => {},
+    ensureRuntimePluginReady: async () => {
+      calls.push('plugin');
+    },
+    chooseTarget: async () => ({ target: context.args.target, kind: 'file' }),
+    checkDependencies: () => {},
+    registerCleanup: () => {},
+    startMpv: async () => {
+      calls.push('startMpv');
+    },
+    waitForUnixSocketReady: async () => true,
+    startOverlay: async () => {},
+    launchAppCommandDetached: () => {},
+    log: () => {},
+    cleanupPlaybackSession: async () => {},
+    getMpvProc: () => null,
+  });
+
+  assert.deepEqual(calls, ['plugin', 'startMpv']);
+});
@@ -19,6 +19,7 @@ import type { Args } from '../types.js';
 import { nowMs } from '../time.js';
 import type { LauncherCommandContext } from './context.js';
 import { ensureLauncherSetupReady } from '../setup-gate.js';
+import { ensureLinuxRuntimePluginAvailable } from '../runtime-plugin-preflight.js';
 import {
  getDefaultConfigDir,
  getSetupStatePath,
@@ -144,6 +145,13 @@ async function ensurePlaybackSetupReady(context: LauncherCommandContext): Promis
 export async function runPlaybackCommand(context: LauncherCommandContext): Promise<void> {
  return runPlaybackCommandWithDeps(context, {
    ensurePlaybackSetupReady,
+    ensureRuntimePluginReady: async (commandContext) => {
+      await ensureLinuxRuntimePluginAvailable({
+        appPath: commandContext.appPath ?? undefined,
+        scriptPath: commandContext.scriptPath,
+        logLevel: commandContext.args.logLevel,
+      });
+    },
    chooseTarget,
    checkDependencies,
    registerCleanup,
@@ -160,6 +168,7 @@ export async function runPlaybackCommand(context: LauncherCommandContext): Promi

 type PlaybackCommandDeps = {
  ensurePlaybackSetupReady: (context: LauncherCommandContext) => Promise<void>;
+  ensureRuntimePluginReady: (context: LauncherCommandContext) => Promise<void>;
  chooseTarget: (
    args: Args,
    scriptPath: string,
@@ -232,6 +241,14 @@ export async function runPlaybackCommandWithDeps(
    ? { ...pluginRuntimeConfig, autoStart: false }
    : pluginRuntimeConfig;

+  const shouldShowOverlayLoadingOsd =
+    !isAppOwnedYoutubeFlow &&
+    (pluginRuntimeConfig.autoStartVisibleOverlay || args.startOverlay || args.autoStartOverlay) &&
+    (pluginRuntimeConfig.autoStart ||
+      args.startOverlay ||
+      args.autoStartOverlay ||
+      shouldLauncherAttachRunningApp);
+
  const shouldPauseUntilOverlayReady =
    pluginRuntimeConfig.autoStart &&
    pluginRuntimeConfig.autoStartVisibleOverlay &&
@@ -245,6 +262,8 @@ export async function runPlaybackCommandWithDeps(
    );
  }

+  await deps.ensureRuntimePluginReady(context);
+
  await deps.startMpv(
    selectedTarget.target,
    selectedTarget.kind,
@@ -266,6 +285,7 @@ export async function runPlaybackCommandWithDeps(
            }
          : {}),
        backend: args.backend,
+        overlayLoadingOsd: shouldShowOverlayLoadingOsd,
        texthookerEnabled: args.useTexthooker && effectivePluginRuntimeConfig.texthookerEnabled,
      },
    },
@@ -0,0 +1,165 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { Args } from '../types.js';
+import { createEmptyMergeSummary } from '../sync/sync-shared.js';
+import type { LauncherCommandContext } from './context.js';
+import { runSyncCommand, type SyncCommandDeps } from './sync-command.js';
+
+function makeContext(overrides: Partial<Args>): LauncherCommandContext {
+  return {
+    args: {
+      sync: true,
+      syncHost: '',
+      syncSnapshotPath: '',
+      syncMergePath: '',
+      syncRemoteCmd: '',
+      syncDbPath: '',
+      syncForce: false,
+      logLevel: 'warn',
+      ...overrides,
+    } as Args,
+    scriptPath: '/tmp/subminer',
+    scriptName: 'subminer',
+    mpvSocketPath: '',
+    pluginRuntimeConfig: {},
+    appPath: null,
+    launcherJellyfinConfig: {},
+    processAdapter: process,
+  } as unknown as LauncherCommandContext;
+}
+
+function ok(stdout = ''): { status: number; stdout: string; stderr: string } {
+  return { status: 0, stdout, stderr: '' };
+}
+
+test('runSyncCommand dispatches snapshot, merge, host, and missing-target modes', () => {
+  const calls: string[] = [];
+  const deps: Partial<SyncCommandDeps> = {
+    createDbSnapshot: (dbPath: string, outPath: string) => {
+      calls.push(`snapshot:${dbPath}->${outPath}`);
+    },
+    mergeSnapshotIntoDb: (dbPath: string, snapshotPath: string) => {
+      calls.push(`merge:${dbPath}<-${snapshotPath}`);
+      return createEmptyMergeSummary();
+    },
+    formatMergeSummary: () => 'summary',
+    ensureTrackerQuiescent: () => {
+      calls.push('quiescent');
+    },
+    assertSafeSshHost: (host: string) => {
+      calls.push(`host:${host}`);
+    },
+    resolveRemoteSubminerCommand: () => 'subminer',
+    runSsh: (_host: string, command: string) => {
+      calls.push(`ssh:${command}`);
+      return command.startsWith('mktemp ') ? ok('/tmp/subminer-sync.remote\n') : ok();
+    },
+    runScp: (from: string, to: string) => {
+      calls.push(`scp:${from}->${to}`);
+    },
+    fail: (message: string): never => {
+      throw new Error(message);
+    },
+  };
+
+  assert.equal(
+    runSyncCommand(
+      makeContext({ syncDbPath: '/tmp/local.sqlite', syncSnapshotPath: '/tmp/out.sqlite' }),
+      deps,
+    ),
+    true,
+  );
+  assert.ok(calls.includes('snapshot:/tmp/local.sqlite->/tmp/out.sqlite'));
+
+  runSyncCommand(
+    makeContext({ syncDbPath: '/tmp/local.sqlite', syncMergePath: '/tmp/in.sqlite' }),
+    deps,
+  );
+  assert.ok(calls.includes('quiescent'));
+  assert.ok(calls.includes('merge:/tmp/local.sqlite<-/tmp/in.sqlite'));
+
+  runSyncCommand(makeContext({ syncDbPath: '/tmp/local.sqlite', syncHost: 'media-box' }), deps);
+  assert.ok(calls.includes('host:media-box'));
+
+  assert.throws(
+    () => runSyncCommand(makeContext({ syncDbPath: '/tmp/local.sqlite' }), deps),
+    /sync requires a host, --snapshot <file>, or --merge <file>/,
+  );
+});
+
+test('runHostSync keeps tracker quiescent through local and remote merge and cleans up after failure', () => {
+  const calls: string[] = [];
+  let localTmpDir = '';
+  const deps: Partial<SyncCommandDeps> = {
+    createDbSnapshot: (_dbPath: string, outPath: string) => {
+      calls.push(`snapshot:${outPath}`);
+      fs.writeFileSync(outPath, 'snapshot');
+    },
+    mergeSnapshotIntoDb: () => {
+      calls.push('local-merge');
+      return createEmptyMergeSummary();
+    },
+    formatMergeSummary: () => 'summary',
+    ensureTrackerQuiescent: () => {
+      calls.push('quiescent');
+    },
+    assertSafeSshHost: () => {},
+    resolveRemoteSubminerCommand: () => 'subminer',
+    mkdtempSync: ((prefix: string) => {
+      localTmpDir = fs.mkdtempSync(path.join(os.tmpdir(), path.basename(prefix)));
+      return localTmpDir;
+    }) as typeof fs.mkdtempSync,
+    runSsh: (_host: string, command: string) => {
+      calls.push(`ssh:${command}`);
+      if (command.startsWith('mktemp ')) return ok('/tmp/subminer-sync.remote\n');
+      if (command.includes(' sync --snapshot ')) return ok();
+      if (command.includes(' sync --merge ')) {
+        return { status: 9, stdout: 'remote output', stderr: 'remote merge exploded' };
+      }
+      return ok();
+    },
+    runScp: (from: string, to: string) => {
+      calls.push(`scp:${from}->${to}`);
+      if (!to.includes(':')) fs.writeFileSync(to, 'pulled');
+    },
+  };
+
+  assert.throws(
+    () =>
+      runSyncCommand(makeContext({ syncDbPath: '/tmp/local.sqlite', syncHost: 'media-box' }), deps),
+    /Remote merge failed on media-box[\s\S]*remote merge exploded/,
+  );
+  assert.equal(calls.filter((call) => call === 'quiescent').length, 3);
+  assert.ok(calls.indexOf('quiescent') < calls.findIndex((call) => call.startsWith('snapshot:')));
+  assert.ok(calls.includes('local-merge'));
+  assert.ok(calls.some((call) => call.startsWith('ssh:rm -rf ')));
+  assert.equal(fs.existsSync(localTmpDir), false);
+});
+
+test('runHostSync includes remote snapshot stderr in failures', () => {
+  const deps: Partial<SyncCommandDeps> = {
+    createDbSnapshot: (_dbPath: string, outPath: string) => {
+      fs.writeFileSync(outPath, 'snapshot');
+    },
+    ensureTrackerQuiescent: () => {},
+    assertSafeSshHost: () => {},
+    resolveRemoteSubminerCommand: () => 'subminer',
+    runSsh: (_host: string, command: string) => {
+      if (command.startsWith('mktemp ')) return ok('/tmp/subminer-sync.remote\n');
+      if (command.includes(' sync --snapshot ')) {
+        return { status: 5, stdout: '', stderr: 'snapshot permission denied' };
+      }
+      return ok();
+    },
+    runScp: () => {},
+  };
+
+  assert.throws(
+    () =>
+      runSyncCommand(makeContext({ syncDbPath: '/tmp/local.sqlite', syncHost: 'media-box' }), deps),
+    /Remote snapshot failed on media-box[\s\S]*snapshot permission denied/,
+  );
+});
@@ -0,0 +1,238 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fail, log } from '../log.js';
+import { resolveImmersionDbPath } from '../history-db.js';
+import {
+  createDbSnapshot,
+  findLiveStatsDaemonPid,
+  formatMergeSummary,
+  mergeSnapshotIntoDb,
+} from '../sync/sync-db.js';
+import {
+  assertSafeSshHost,
+  resolveRemoteSubminerCommand,
+  runScp,
+  runSsh,
+  shellQuote,
+} from '../sync/ssh.js';
+import { resolvePathMaybe } from '../util.js';
+import type { LauncherCommandContext } from './context.js';
+import type { RemoteRunResult } from '../sync/ssh.js';
+
+export interface SyncCommandDeps {
+  createDbSnapshot: typeof createDbSnapshot;
+  mergeSnapshotIntoDb: typeof mergeSnapshotIntoDb;
+  formatMergeSummary: typeof formatMergeSummary;
+  findLiveStatsDaemonPid: typeof findLiveStatsDaemonPid;
+  assertSafeSshHost: typeof assertSafeSshHost;
+  resolveRemoteSubminerCommand: typeof resolveRemoteSubminerCommand;
+  runScp: typeof runScp;
+  runSsh: typeof runSsh;
+  fail: typeof fail;
+  log: typeof log;
+  existsSync: typeof fs.existsSync;
+  realpathSync: typeof fs.realpathSync;
+  mkdtempSync: typeof fs.mkdtempSync;
+  rmSync: typeof fs.rmSync;
+  consoleLog: typeof console.log;
+  writeStdout: typeof process.stdout.write;
+  ensureTrackerQuiescent: (context: LauncherCommandContext, dbPath: string) => void;
+}
+
+function resolveDbPath(context: LauncherCommandContext): string {
+  const override = context.args.syncDbPath.trim();
+  return override ? resolvePathMaybe(override) : resolveImmersionDbPath();
+}
+
+function isTrackerDb(dbPath: string, deps: SyncCommandDeps): boolean {
+  const trackerDbPath = resolveImmersionDbPath();
+  try {
+    return deps.realpathSync(dbPath) === deps.realpathSync(trackerDbPath);
+  } catch {
+    return dbPath === trackerDbPath;
+  }
+}
+
+export function ensureTrackerQuiescent(
+  context: LauncherCommandContext,
+  dbPath: string,
+  inputDeps: Partial<SyncCommandDeps> = {},
+): void {
+  const deps = resolveSyncCommandDeps(inputDeps);
+  if (context.args.syncForce) return;
+  // A running SubMiner only holds the tracker's own database; --db pointed
+  // elsewhere needs no guard.
+  if (!isTrackerDb(dbPath, deps)) return;
+  const daemonPid = deps.findLiveStatsDaemonPid(dbPath);
+  if (daemonPid !== null) {
+    deps.fail(
+      `The SubMiner stats server is running (pid ${daemonPid}). Stop it with "subminer stats -s" (or close SubMiner) before syncing, or pass --force.`,
+    );
+  }
+  if (context.mpvSocketPath && deps.existsSync(context.mpvSocketPath)) {
+    deps.fail(
+      `An mpv/SubMiner session appears to be running (socket ${context.mpvSocketPath}). Close it before syncing, or pass --force.`,
+    );
+  }
+}
+
+const defaultSyncCommandDeps: SyncCommandDeps = {
+  createDbSnapshot,
+  mergeSnapshotIntoDb,
+  formatMergeSummary,
+  findLiveStatsDaemonPid,
+  assertSafeSshHost,
+  resolveRemoteSubminerCommand,
+  runScp,
+  runSsh,
+  fail,
+  log,
+  existsSync: fs.existsSync,
+  realpathSync: fs.realpathSync,
+  mkdtempSync: fs.mkdtempSync,
+  rmSync: fs.rmSync,
+  consoleLog: console.log,
+  writeStdout: process.stdout.write.bind(process.stdout),
+  ensureTrackerQuiescent: (context, dbPath) => ensureTrackerQuiescent(context, dbPath),
+};
+
+function resolveSyncCommandDeps(inputDeps: Partial<SyncCommandDeps> = {}): SyncCommandDeps {
+  return { ...defaultSyncCommandDeps, ...inputDeps };
+}
+
+export function runSnapshotMode(
+  context: LauncherCommandContext,
+  dbPath: string,
+  inputDeps: Partial<SyncCommandDeps> = {},
+): void {
+  const deps = resolveSyncCommandDeps(inputDeps);
+  const outPath = resolvePathMaybe(context.args.syncSnapshotPath);
+  deps.createDbSnapshot(dbPath, outPath);
+  deps.consoleLog(outPath);
+}
+
+export function runMergeMode(
+  context: LauncherCommandContext,
+  dbPath: string,
+  inputDeps: Partial<SyncCommandDeps> = {},
+): void {
+  const deps = resolveSyncCommandDeps(inputDeps);
+  deps.ensureTrackerQuiescent(context, dbPath);
+  const snapshotPath = resolvePathMaybe(context.args.syncMergePath);
+  const summary = deps.mergeSnapshotIntoDb(dbPath, snapshotPath);
+  deps.consoleLog(deps.formatMergeSummary(summary));
+}
+
+function cleanupRemote(host: string, remoteTmpDir: string, deps: SyncCommandDeps): void {
+  if (!remoteTmpDir.startsWith('/tmp/')) return;
+  deps.runSsh(host, `rm -rf ${shellQuote(remoteTmpDir)}`);
+}
+
+function formatRemoteRunError(message: string, run: RemoteRunResult): string {
+  const stderr = run.stderr.trim();
+  return stderr ? `${message}\n${stderr}` : message;
+}
+
+export function runHostSync(
+  context: LauncherCommandContext,
+  dbPath: string,
+  inputDeps: Partial<SyncCommandDeps> = {},
+): void {
+  const deps = resolveSyncCommandDeps(inputDeps);
+  const { args } = context;
+  const host = args.syncHost;
+  deps.assertSafeSshHost(host);
+
+  deps.ensureTrackerQuiescent(context, dbPath);
+
+  const remoteCmd = deps.resolveRemoteSubminerCommand(host, args.syncRemoteCmd || null);
+  deps.log('debug', args.logLevel, `Remote subminer command: ${remoteCmd}`);
+
+  const localTmpDir = deps.mkdtempSync(path.join(os.tmpdir(), 'subminer-sync-'));
+  let remoteTmpDir = '';
+  try {
+    // Signal failures by throwing (not fail(), which exits synchronously and
+    // would skip the finally cleanup, leaking temp dirs holding snapshot data).
+    // main().catch() reports the message the same way fail() would.
+    const mktemp = deps.runSsh(host, 'mktemp -d /tmp/subminer-sync.XXXXXX');
+    remoteTmpDir = mktemp.stdout.trim();
+    if (mktemp.status !== 0 || !remoteTmpDir.startsWith('/tmp/')) {
+      throw new Error(`Could not create a temporary directory on ${host}.`);
+    }
+
+    const forceFlag = args.syncForce ? ' --force' : '';
+
+    deps.consoleLog(`Snapshotting local database (${dbPath})...`);
+    const localSnapshot = path.join(localTmpDir, 'local.sqlite');
+    deps.createDbSnapshot(dbPath, localSnapshot);
+
+    deps.consoleLog(`Snapshotting ${host}...`);
+    const remoteSnapshot = `${remoteTmpDir}/snapshot.sqlite`;
+    const snapshotRun = deps.runSsh(
+      host,
+      `${remoteCmd} sync --snapshot ${shellQuote(remoteSnapshot)}${forceFlag}`,
+    );
+    if (snapshotRun.status !== 0) {
+      throw new Error(formatRemoteRunError(`Remote snapshot failed on ${host}.`, snapshotRun));
+    }
+
+    const pulledSnapshot = path.join(localTmpDir, 'remote.sqlite');
+    deps.runScp(`${host}:${remoteSnapshot}`, pulledSnapshot);
+    const incomingSnapshot = `${remoteTmpDir}/incoming.sqlite`;
+    deps.runScp(localSnapshot, `${host}:${incomingSnapshot}`);
+
+    deps.consoleLog(`\nMerging ${host} -> local:`);
+    deps.ensureTrackerQuiescent(context, dbPath);
+    const summary = deps.mergeSnapshotIntoDb(dbPath, pulledSnapshot);
+    deps.consoleLog(deps.formatMergeSummary(summary));
+
+    deps.consoleLog(`\nMerging local -> ${host}:`);
+    deps.ensureTrackerQuiescent(context, dbPath);
+    const mergeRun = deps.runSsh(
+      host,
+      `${remoteCmd} sync --merge ${shellQuote(incomingSnapshot)}${forceFlag}`,
+    );
+    deps.writeStdout(mergeRun.stdout);
+    if (mergeRun.status !== 0) {
+      throw new Error(
+        formatRemoteRunError(
+          `Remote merge failed on ${host}. The local database was updated; re-run "subminer sync ${host}" once the remote issue is fixed.`,
+          mergeRun,
+        ),
+      );
+    }
+
+    deps.consoleLog('\nSync complete.');
+  } finally {
+    deps.rmSync(localTmpDir, { recursive: true, force: true });
+    if (remoteTmpDir) {
+      try {
+        cleanupRemote(host, remoteTmpDir, deps);
+      } catch {
+        // best effort
+      }
+    }
+  }
+}
+
+export function runSyncCommand(
+  context: LauncherCommandContext,
+  inputDeps: Partial<SyncCommandDeps> = {},
+): boolean {
+  const deps = resolveSyncCommandDeps(inputDeps);
+  const { args } = context;
+  if (!args.sync) return false;
+
+  const dbPath = resolveDbPath(context);
+  if (args.syncSnapshotPath) {
+    runSnapshotMode(context, dbPath, deps);
+  } else if (args.syncMergePath) {
+    runMergeMode(context, dbPath, deps);
+  } else if (args.syncHost) {
+    runHostSync(context, dbPath, deps);
+  } else {
+    deps.fail('sync requires a host, --snapshot <file>, or --merge <file>.');
+  }
+  return true;
+}
@@ -34,7 +34,10 @@ test('runUpdateCommand updates directly on Linux without launching Electron', as
      return {
        appImage: { status: 'updated' },
        launcher: { status: 'updated' },
-        supportAssets: [{ status: 'skipped' }],
+        supportAssets: [
+          { status: 'updated', component: 'theme', message: 'Installed theme.' },
+          { status: 'skipped', component: 'plugin', message: 'Plugin already up to date.' },
+        ],
      };
    },
    readMainConfig: () => ({ updates: { channel: 'prerelease' } }),
@@ -48,7 +51,8 @@ test('runUpdateCommand updates directly on Linux without launching Electron', as
    'direct:/home/kyle/.local/bin/SubMiner.AppImage:/home/kyle/.local/bin/subminer:prerelease',
    'info:AppImage update: updated',
    'info:Launcher update: updated',
-    'info:Rofi theme update: skipped',
+    'info:Support assets (theme) update: updated - Installed theme.',
+    'info:Support assets (plugin) update: skipped - Plugin already up to date.',
  ]);
 });

@@ -101,7 +105,7 @@ test('runUpdateCommand skips Linux asset replacement when release is not newer',
      'fetch:https://api.github.com/repos/ksyasuda/SubMiner/releases',
      'info:AppImage update: up to date',
      'info:Launcher update: up to date',
-      'info:Rofi theme update: up to date',
+      'info:Support assets update: up to date',
    ]);
  } finally {
    globalThis.fetch = originalFetch;
@@ -39,7 +39,12 @@ type DirectReleaseUpdateRequest = {
 type DirectReleaseUpdateResult = {
  appImage: { status: string; command?: string; message?: string };
  launcher: { status: string; command?: string; message?: string };
-  supportAssets: Array<{ status: string; command?: string; message?: string }>;
+  supportAssets: Array<{
+    status: string;
+    component?: 'theme' | 'plugin';
+    command?: string;
+    message?: string;
+  }>;
 };

 type UpdateCommandDeps = {
@@ -124,20 +129,29 @@ function readUpdateChannel(root: Record<string, unknown> | null): UpdateChannel

 function logUpdateResult(
  label: string,
-  result: { status: string; command?: string; message?: string },
+  result: {
+    status: string;
+    component?: 'theme' | 'plugin';
+    command?: string;
+    message?: string;
+  },
  configuredLogLevel: NonNullable<LauncherCommandContext['args']['logLevel']>,
  deps: Pick<UpdateCommandDeps, 'log'>,
 ): void {
  const displayStatus = result.status === 'up-to-date' ? 'up to date' : result.status;
-  deps.log('info', configuredLogLevel, `${label} update: ${displayStatus}`);
+  const componentLabel = result.component ? ` (${result.component})` : '';
+  const detailSuffix = result.message ? ` - ${result.message}` : '';
+  deps.log(
+    'info',
+    configuredLogLevel,
+    `${label}${componentLabel} update: ${displayStatus}${detailSuffix}`,
+  );
  if (result.command) {
    deps.log(
      'warn',
      configuredLogLevel,
-      `${label} update requires manual command: ${result.command}`,
+      `${label}${componentLabel} update requires manual command: ${result.command}`,
    );
-  } else if (result.message) {
-    deps.log('warn', configuredLogLevel, `${label} update note: ${result.message}`);
  }
 }

@@ -187,7 +201,7 @@ export async function runUpdateCommand(
    logUpdateResult('AppImage', result.appImage, logLevel, resolvedDeps);
    logUpdateResult('Launcher', result.launcher, logLevel, resolvedDeps);
    for (const supportResult of result.supportAssets) {
-      logUpdateResult('Rofi theme', supportResult, logLevel, resolvedDeps);
+      logUpdateResult('Support assets', supportResult, logLevel, resolvedDeps);
    }
    return true;
  }
@@ -91,8 +91,6 @@ test('parseLauncherMpvConfig reads launch mode preference', () => {
      autoStartSubMiner: false,
      pauseUntilOverlayReady: false,
      subminerBinaryPath: '/opt/SubMiner/SubMiner.AppImage',
-      aniskipEnabled: false,
-      aniskipButtonKey: 'F8',
    },
  });

@@ -102,8 +100,6 @@ test('parseLauncherMpvConfig reads launch mode preference', () => {
  assert.equal(parsed.autoStartSubMiner, false);
  assert.equal(parsed.pauseUntilOverlayReady, false);
  assert.equal(parsed.subminerBinaryPath, '/opt/SubMiner/SubMiner.AppImage');
-  assert.equal(parsed.aniskipEnabled, false);
-  assert.equal(parsed.aniskipButtonKey, 'F8');
 });

 test('parseLauncherMpvConfig ignores blank subminer binary paths', () => {
@@ -129,6 +125,11 @@ test('parseLauncherMpvConfig ignores invalid launch mode values', () => {
 test('parsePluginRuntimeConfigFromMainConfig maps config.jsonc values over plugin defaults', () => {
  const parsed = parsePluginRuntimeConfigFromMainConfig({
    auto_start_overlay: false,
+    ankiConnect: {
+      behavior: {
+        notificationType: 'osd-system',
+      },
+    },
    texthooker: {
      launchAtStartup: false,
    },
@@ -138,8 +139,6 @@ test('parsePluginRuntimeConfigFromMainConfig maps config.jsonc values over plugi
      autoStartSubMiner: true,
      pauseUntilOverlayReady: true,
      subminerBinaryPath: '/opt/SubMiner/SubMiner.AppImage',
-      aniskipEnabled: false,
-      aniskipButtonKey: 'F8',
    },
  });

@@ -148,10 +147,21 @@ test('parsePluginRuntimeConfigFromMainConfig maps config.jsonc values over plugi
  assert.equal(parsed.autoStart, true);
  assert.equal(parsed.autoStartVisibleOverlay, false);
  assert.equal(parsed.autoStartPauseUntilReady, true);
+  assert.equal(parsed.osdMessages, true);
  assert.equal(parsed.binaryPath, '/opt/SubMiner/SubMiner.AppImage');
  assert.equal(parsed.texthookerEnabled, false);
-  assert.equal(parsed.aniskipEnabled, false);
-  assert.equal(parsed.aniskipButtonKey, 'F8');
+});
+
+test('parsePluginRuntimeConfigFromMainConfig disables plugin osd messages for overlay notification routing', () => {
+  const parsed = parsePluginRuntimeConfigFromMainConfig({
+    ankiConnect: {
+      behavior: {
+        notificationType: 'both',
+      },
+    },
+  });
+
+  assert.equal(parsed.osdMessages, false);
 });

 test('parsePluginRuntimeConfigFromMainConfig defaults to background-only managed startup', () => {
@@ -160,9 +170,8 @@ test('parsePluginRuntimeConfigFromMainConfig defaults to background-only managed
  assert.equal(parsed.autoStart, true);
  assert.equal(parsed.autoStartVisibleOverlay, false);
  assert.equal(parsed.autoStartPauseUntilReady, true);
+  assert.equal(parsed.osdMessages, false);
  assert.equal(parsed.texthookerEnabled, false);
-  assert.equal(parsed.aniskipEnabled, true);
-  assert.equal(parsed.aniskipButtonKey, 'TAB');
 });

 test('buildPluginRuntimeScriptOptParts emits config values that override plugin defaults', () => {
@@ -175,9 +184,8 @@ test('buildPluginRuntimeScriptOptParts emits config values that override plugin
        autoStart: true,
        autoStartVisibleOverlay: false,
        autoStartPauseUntilReady: true,
+        osdMessages: true,
        texthookerEnabled: false,
-        aniskipEnabled: false,
-        aniskipButtonKey: 'F8',
      },
      '/fallback/SubMiner.AppImage',
    ),
@@ -187,10 +195,11 @@ test('buildPluginRuntimeScriptOptParts emits config values that override plugin
      'subminer-backend=x11',
      'subminer-auto_start=yes',
      'subminer-auto_start_visible_overlay=no',
+      'subminer-overlay_loading_osd=no',
      'subminer-auto_start_pause_until_ready=yes',
+      'subminer-auto_start_pause_until_ready_timeout_seconds=30',
+      'subminer-osd_messages=yes',
      'subminer-texthooker_enabled=no',
-      'subminer-aniskip_enabled=no',
-      'subminer-aniskip_button_key=F8',
    ],
  );
 });
@@ -205,9 +214,8 @@ test('buildPluginRuntimeScriptOptParts strips script-option delimiters from stri
        autoStart: true,
        autoStartVisibleOverlay: false,
        autoStartPauseUntilReady: true,
+        osdMessages: false,
        texthookerEnabled: false,
-        aniskipEnabled: false,
-        aniskipButtonKey: 'F8,\nF9',
      },
      '/fallback/SubMiner.AppImage',
    ),
@@ -217,10 +225,11 @@ test('buildPluginRuntimeScriptOptParts strips script-option delimiters from stri
      'subminer-backend=x11',
      'subminer-auto_start=yes',
      'subminer-auto_start_visible_overlay=no',
+      'subminer-overlay_loading_osd=no',
      'subminer-auto_start_pause_until_ready=yes',
+      'subminer-auto_start_pause_until_ready_timeout_seconds=30',
+      'subminer-osd_messages=no',
      'subminer-texthooker_enabled=no',
-      'subminer-aniskip_enabled=no',
-      'subminer-aniskip_button_key=F8 F9',
    ],
  );
 });
@@ -244,8 +253,6 @@ test('parseLauncherMpvConfig reads configured mpv profile', () => {
      pauseUntilOverlayReady: undefined,
      subminerBinaryPath: undefined,
      profile: 'anime',
-      aniskipEnabled: undefined,
-      aniskipButtonKey: undefined,
    },
  );

@@ -135,6 +135,14 @@ test('applyInvocationsToArgs maps config and jellyfin invocation state', () => {
    statsCleanupVocab: false,
    statsCleanupLifetime: false,
    statsLogLevel: null,
+    syncTriggered: false,
+    syncHost: null,
+    syncSnapshotPath: null,
+    syncMergePath: null,
+    syncRemoteCmd: null,
+    syncDbPath: null,
+    syncForce: false,
+    syncLogLevel: null,
    doctorTriggered: false,
    doctorLogLevel: null,
    doctorRefreshKnownWords: false,
@@ -181,6 +189,14 @@ test('applyInvocationsToArgs maps settings invocation to settings window', () =>
    statsCleanupVocab: false,
    statsCleanupLifetime: false,
    statsLogLevel: null,
+    syncTriggered: false,
+    syncHost: null,
+    syncSnapshotPath: null,
+    syncMergePath: null,
+    syncRemoteCmd: null,
+    syncDbPath: null,
+    syncForce: false,
+    syncLogLevel: null,
    doctorTriggered: false,
    doctorLogLevel: null,
    doctorRefreshKnownWords: false,
@@ -220,6 +236,14 @@ test('applyInvocationsToArgs fails when config invocation has no action', () =>
      statsCleanupVocab: false,
      statsCleanupLifetime: false,
      statsLogLevel: null,
+      syncTriggered: false,
+      syncHost: null,
+      syncSnapshotPath: null,
+      syncMergePath: null,
+      syncRemoteCmd: null,
+      syncDbPath: null,
+      syncForce: false,
+      syncLogLevel: null,
      doctorTriggered: false,
      doctorLogLevel: null,
      doctorRefreshKnownWords: false,
@@ -257,6 +281,14 @@ test('applyInvocationsToArgs maps texthooker browser-open request', () => {
    statsCleanupVocab: false,
    statsCleanupLifetime: false,
    statsLogLevel: null,
+    syncTriggered: false,
+    syncHost: null,
+    syncSnapshotPath: null,
+    syncMergePath: null,
+    syncRemoteCmd: null,
+    syncDbPath: null,
+    syncForce: false,
+    syncLogLevel: null,
    doctorTriggered: false,
    doctorLogLevel: null,
    doctorRefreshKnownWords: false,
@@ -198,6 +198,14 @@ export function createDefaultArgs(
    texthookerOnly: false,
    texthookerOpenBrowser: false,
    useRofi: false,
+    history: false,
+    sync: false,
+    syncHost: '',
+    syncSnapshotPath: '',
+    syncMergePath: '',
+    syncRemoteCmd: '',
+    syncDbPath: '',
+    syncForce: false,
    logLevel: loggingConfig.level ?? 'warn',
    logRotation: loggingConfig.rotation ?? 7,
    passwordStore: '',
@@ -231,6 +239,7 @@ export function applyRootOptionsToArgs(
  if (typeof options.logLevel === 'string') parsed.logLevel = parseLogLevel(options.logLevel);
  if (typeof options.passwordStore === 'string') parsed.passwordStore = options.passwordStore;
  if (options.rofi === true) parsed.useRofi = true;
+  if (options.history === true) parsed.history = true;
  if (options.update === true) parsed.update = true;
  if (options.version === true) parsed.version = true;
  if (options.settings === true) parsed.settings = true;
@@ -262,6 +271,16 @@ export function applyInvocationsToArgs(parsed: Args, invocations: CliInvocations
  ) {
    fail('Dictionary target path is required.');
  }
+  if (invocations.syncTriggered) {
+    parsed.sync = true;
+    parsed.syncHost = invocations.syncHost ?? '';
+    parsed.syncSnapshotPath = invocations.syncSnapshotPath ?? '';
+    parsed.syncMergePath = invocations.syncMergePath ?? '';
+    parsed.syncRemoteCmd = invocations.syncRemoteCmd ?? '';
+    parsed.syncDbPath = invocations.syncDbPath ?? '';
+    parsed.syncForce = invocations.syncForce;
+    if (invocations.syncLogLevel) parsed.logLevel = parseLogLevel(invocations.syncLogLevel);
+  }
  if (invocations.doctorTriggered) parsed.doctor = true;
  if (invocations.doctorRefreshKnownWords) parsed.doctorRefreshKnownWords = true;
  if (invocations.logsTriggered && !invocations.logsExport) {
@@ -38,6 +38,14 @@ export interface CliInvocations {
  statsCleanupVocab: boolean;
  statsCleanupLifetime: boolean;
  statsLogLevel: string | null;
+  syncTriggered: boolean;
+  syncHost: string | null;
+  syncSnapshotPath: string | null;
+  syncMergePath: string | null;
+  syncRemoteCmd: string | null;
+  syncDbPath: string | null;
+  syncForce: boolean;
+  syncLogLevel: string | null;
  doctorTriggered: boolean;
  doctorLogLevel: string | null;
  doctorRefreshKnownWords: boolean;
@@ -64,6 +72,7 @@ function applyRootOptions(program: Command): void {
    .option('--settings', 'Open settings window')
    .option('-u, --update', 'Check for updates')
    .option('-R, --rofi', 'Use rofi picker')
+    .option('-H, --history', 'Browse local watch history')
    .option('-S, --start-overlay', 'Auto-start overlay')
    .option('-T, --no-texthooker', 'Disable texthooker-ui server');
 }
@@ -97,6 +106,7 @@ function getTopLevelCommand(argv: string[]): { name: string; index: number } | n
    'dictionary',
    'dict',
    'stats',
+    'sync',
    'texthooker',
    'app',
    'bin',
@@ -159,6 +169,14 @@ export function parseCliPrograms(
  let statsCleanupVocab = false;
  let statsCleanupLifetime = false;
  let statsLogLevel: string | null = null;
+  let syncTriggered = false;
+  let syncHost: string | null = null;
+  let syncSnapshotPath: string | null = null;
+  let syncMergePath: string | null = null;
+  let syncRemoteCmd: string | null = null;
+  let syncDbPath: string | null = null;
+  let syncForce = false;
+  let syncLogLevel: string | null = null;
  let doctorLogLevel: string | null = null;
  let doctorRefreshKnownWords = false;
  let logsTriggered = false;
@@ -288,6 +306,37 @@ export function parseCliPrograms(
      statsLogLevel = typeof options.logLevel === 'string' ? options.logLevel : null;
    });

+  commandProgram
+    .command('sync')
+    .description('Sync stats and watch history with another machine over SSH')
+    .argument('[host]', 'SSH destination (user@host or an ssh config alias)')
+    .option('--snapshot <file>', 'Write a consistent snapshot of the local stats database')
+    .option('--merge <file>', 'Merge a snapshot database file into the local stats database')
+    .option('--db <file>', 'Override the local stats database path')
+    .option('--remote-cmd <cmd>', 'subminer command to run on the remote host')
+    .option('-f, --force', 'Skip the running-app safety check')
+    .option('--log-level <level>', 'Log level')
+    .action((rawHost: string | undefined, options: Record<string, unknown>) => {
+      const host = typeof rawHost === 'string' ? rawHost.trim() : '';
+      const snapshot = typeof options.snapshot === 'string' ? options.snapshot.trim() : '';
+      const merge = typeof options.merge === 'string' ? options.merge.trim() : '';
+      const modes = [Boolean(host), Boolean(snapshot), Boolean(merge)].filter(Boolean).length;
+      if (modes === 0) {
+        throw new Error('Sync requires a host, --snapshot <file>, or --merge <file>.');
+      }
+      if (modes > 1) {
+        throw new Error('Sync host, --snapshot, and --merge cannot be combined.');
+      }
+      syncTriggered = true;
+      syncHost = host || null;
+      syncSnapshotPath = snapshot || null;
+      syncMergePath = merge || null;
+      syncRemoteCmd = typeof options.remoteCmd === 'string' ? options.remoteCmd.trim() || null : null;
+      syncDbPath = typeof options.db === 'string' ? options.db.trim() || null : null;
+      syncForce = options.force === true;
+      syncLogLevel = typeof options.logLevel === 'string' ? options.logLevel : null;
+    });
+
  commandProgram
    .command('doctor')
    .description('Run dependency and environment checks')
@@ -399,6 +448,14 @@ export function parseCliPrograms(
      statsCleanupVocab,
      statsCleanupLifetime,
      statsLogLevel,
+      syncTriggered,
+      syncHost,
+      syncSnapshotPath,
+      syncMergePath,
+      syncRemoteCmd,
+      syncDbPath,
+      syncForce,
+      syncLogLevel,
      doctorTriggered,
      doctorLogLevel,
      doctorRefreshKnownWords,
@@ -39,7 +39,5 @@ export function parseLauncherMpvConfig(root: Record<string, unknown>): LauncherM
    pauseUntilOverlayReady:
      typeof mpv.pauseUntilOverlayReady === 'boolean' ? mpv.pauseUntilOverlayReady : undefined,
    subminerBinaryPath: parseNonEmptyString(mpv.subminerBinaryPath),
-    aniskipEnabled: typeof mpv.aniskipEnabled === 'boolean' ? mpv.aniskipEnabled : undefined,
-    aniskipButtonKey: parseNonEmptyString(mpv.aniskipButtonKey),
  };
 }
@@ -16,10 +16,9 @@ function booleanOrDefault(value: unknown, fallback: boolean): boolean {
  return typeof value === 'boolean' ? value : fallback;
 }

-function nonEmptyStringOrDefault(value: unknown, fallback: string): string {
-  if (typeof value !== 'string') return fallback;
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : fallback;
+function pluginOsdMessagesFromNotificationType(root: Record<string, unknown> | null): boolean {
+  const notificationType = rootObject(rootObject(root, 'ankiConnect'), 'behavior').notificationType;
+  return notificationType === 'osd' || notificationType === 'osd-system';
 }

 function validBackendOrDefault(value: unknown, fallback: Backend): Backend {
@@ -53,9 +52,8 @@ export function parsePluginRuntimeConfigFromMainConfig(
    autoStart: booleanOrDefault(mpvConfig.autoStartSubMiner, true),
    autoStartVisibleOverlay: booleanOrDefault(root?.auto_start_overlay, false),
    autoStartPauseUntilReady: booleanOrDefault(mpvConfig.pauseUntilOverlayReady, true),
+    osdMessages: pluginOsdMessagesFromNotificationType(root),
    texthookerEnabled: booleanOrDefault(texthooker.launchAtStartup, false),
-    aniskipEnabled: booleanOrDefault(mpvConfig.aniskipEnabled, true),
-    aniskipButtonKey: nonEmptyStringOrDefault(mpvConfig.aniskipButtonKey, 'TAB'),
  };
 }

@@ -72,7 +70,7 @@ export function readPluginRuntimeConfig(logLevel: LogLevel): PluginRuntimeConfig
  log(
    'debug',
    logLevel,
-    `Using mpv plugin settings from SubMiner config: socket_path=${parsed.socketPath}, backend=${parsed.backend}, auto_start=${parsed.autoStart}, auto_start_visible_overlay=${parsed.autoStartVisibleOverlay}, auto_start_pause_until_ready=${parsed.autoStartPauseUntilReady}, texthooker_enabled=${parsed.texthookerEnabled}, aniskip_enabled=${parsed.aniskipEnabled}, aniskip_button_key=${parsed.aniskipButtonKey}`,
+    `Using mpv plugin settings from SubMiner config: socket_path=${parsed.socketPath}, backend=${parsed.backend}, auto_start=${parsed.autoStart}, auto_start_visible_overlay=${parsed.autoStartVisibleOverlay}, auto_start_pause_until_ready=${parsed.autoStartPauseUntilReady}, osd_messages=${parsed.osdMessages}, texthooker_enabled=${parsed.texthookerEnabled}`,
  );
  return parsed;
 }
@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Database } from 'bun:sqlite';
+import { withReadonlyWalRetry } from './history-db.js';
+
+const COVER_EXTENSIONS = ['.jpg', '.png', '.webp', '.gif'] as const;
+const SAFE_COVER_HASH_PATTERN = /^[a-z0-9_-]+$/i;
+
+export function getDefaultCoverCacheDir(): string {
+  return path.join(os.homedir(), '.cache', 'subminer', 'covers');
+}
+
+export function detectImageExtension(blob: Buffer): string {
+  if (blob.length >= 8 && blob.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex'))) {
+    return '.png';
+  }
+  if (blob.length >= 3 && blob[0] === 0xff && blob[1] === 0xd8 && blob[2] === 0xff) {
+    return '.jpg';
+  }
+  if (
+    blob.length >= 12 &&
+    blob.subarray(0, 4).toString('ascii') === 'RIFF' &&
+    blob.subarray(8, 12).toString('ascii') === 'WEBP'
+  ) {
+    return '.webp';
+  }
+  if (blob.length >= 4 && blob.subarray(0, 3).toString('ascii') === 'GIF') {
+    return '.gif';
+  }
+  return '.jpg';
+}
+
+function findCachedCover(cacheDir: string, hash: string): string | null {
+  for (const ext of COVER_EXTENSIONS) {
+    const candidate = path.join(cacheDir, `${hash}${ext}`);
+    try {
+      if (fs.statSync(candidate).size > 0) return candidate;
+    } catch {
+      // not cached with this extension
+    }
+  }
+  return null;
+}
+
+function queryCoverBlobs(
+  dbPath: string,
+  hashes: string[],
+  options: { readonly?: boolean; readwrite?: boolean; create?: boolean },
+): Map<string, Buffer> {
+  const blobs = new Map<string, Buffer>();
+  const db = new Database(dbPath, options);
+  try {
+    const hasBlobTable = db
+      .query(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'imm_cover_art_blobs'`)
+      .get();
+    if (!hasBlobTable) return blobs;
+
+    const stmt = db.query<{ cover_blob: Uint8Array | null }>(
+      'SELECT cover_blob FROM imm_cover_art_blobs WHERE blob_hash = ?',
+    );
+    for (const hash of hashes) {
+      const row = stmt.get(hash);
+      if (row?.cover_blob && row.cover_blob.length > 0) {
+        blobs.set(hash, Buffer.from(row.cover_blob));
+      }
+    }
+    return blobs;
+  } finally {
+    db.close();
+  }
+}
+
+function isSafeCoverHash(hash: string | null | undefined): hash is string {
+  return typeof hash === 'string' && SAFE_COVER_HASH_PATTERN.test(hash);
+}
+
+/**
+ * Ensures cover art blobs referenced by hash exist as image files in the cache
+ * directory, extracting missing ones from the stats database. Returns a map of
+ * blob hash to on-disk image path for every cover that could be materialized.
+ */
+export function materializeCoverArt(
+  dbPath: string,
+  hashes: Array<string | null | undefined>,
+  cacheDir: string = getDefaultCoverCacheDir(),
+): Map<string, string> {
+  const wanted = Array.from(new Set(hashes.filter(isSafeCoverHash)));
+  const resolved = new Map<string, string>();
+  if (wanted.length === 0) return resolved;
+
+  const missing: string[] = [];
+  for (const hash of wanted) {
+    const cached = findCachedCover(cacheDir, hash);
+    if (cached) {
+      resolved.set(hash, cached);
+    } else {
+      missing.push(hash);
+    }
+  }
+  if (missing.length === 0) return resolved;
+
+  let blobs: Map<string, Buffer>;
+  try {
+    blobs = withReadonlyWalRetry(dbPath, (options) => queryCoverBlobs(dbPath, missing, options));
+  } catch {
+    return resolved;
+  }
+  if (blobs.size === 0) return resolved;
+
+  try {
+    fs.mkdirSync(cacheDir, { recursive: true });
+  } catch {
+    return resolved;
+  }
+  for (const [hash, blob] of blobs) {
+    const target = path.join(cacheDir, `${hash}${detectImageExtension(blob)}`);
+    try {
+      fs.writeFileSync(target, blob);
+      resolved.set(hash, target);
+    } catch {
+      // cache write failure just means no icon for this entry
+    }
+  }
+  return resolved;
+}
@@ -0,0 +1,151 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Database } from 'bun:sqlite';
+import { resolveConfigDir } from '../src/config/path-resolution.js';
+import { readLauncherMainConfigObject } from './config/shared-config-reader.js';
+import type { HistoryVideoRow } from './history-types.js';
+import { resolvePathMaybe } from './util.js';
+
+export function resolveImmersionDbPath(): string {
+  const root = readLauncherMainConfigObject();
+  const tracking =
+    root?.immersionTracking &&
+    typeof root.immersionTracking === 'object' &&
+    !Array.isArray(root.immersionTracking)
+      ? (root.immersionTracking as Record<string, unknown>)
+      : null;
+  const configured = typeof tracking?.dbPath === 'string' ? tracking.dbPath.trim() : '';
+  if (configured) return resolvePathMaybe(configured);
+
+  const configDir = resolveConfigDir({
+    platform: process.platform,
+    appDataDir: process.env.APPDATA,
+    xdgConfigHome: process.env.XDG_CONFIG_HOME,
+    homeDir: os.homedir(),
+    existsSync: fs.existsSync,
+  });
+  return path.join(configDir, 'immersion.sqlite');
+}
+
+interface RawHistoryRow {
+  video_id: number;
+  source_path: string | null;
+  parsed_title: string | null;
+  parsed_season: number | null;
+  parsed_episode: number | null;
+  anime_title: string | null;
+  last_watched_ms: number | bigint | null;
+  cover_blob_hash: string | null;
+}
+
+export function queryLocalWatchHistory(dbPath: string): HistoryVideoRow[] {
+  return withReadonlyWalRetry(dbPath, (options) => readHistoryRows(dbPath, options));
+}
+
+export function withReadonlyWalRetry<T>(
+  dbPath: string,
+  query: (options: { readonly?: boolean; readwrite?: boolean; create?: boolean }) => T,
+): T {
+  try {
+    return query({ readonly: true });
+  } catch (error) {
+    if (!isReadonlyWalRetryError(error, dbPath)) throw error;
+    return query({ readwrite: true, create: false });
+  }
+}
+
+export function isReadonlyWalRetryError(error: unknown, dbPath: string): boolean {
+  if (!isWalModeSqliteDatabase(dbPath)) return false;
+  const code =
+    typeof error === 'object' && error !== null && 'code' in error
+      ? String((error as { code?: unknown }).code ?? '')
+      : '';
+  const message = error instanceof Error ? error.message : String(error);
+  const text = `${code} ${message}`.toLowerCase();
+  return (
+    text.includes('readonly') ||
+    text.includes('read-only') ||
+    text.includes('attempt to write a readonly database') ||
+    text.includes('sqlite_cantopen') ||
+    text.includes('unable to open database file')
+  );
+}
+
+function isWalModeSqliteDatabase(dbPath: string): boolean {
+  const header = Buffer.alloc(20);
+  let fd: number | null = null;
+  try {
+    fd = fs.openSync(dbPath, 'r');
+    if (fs.readSync(fd, header, 0, header.length, 0) < header.length) return false;
+  } catch {
+    return false;
+  } finally {
+    if (fd !== null) fs.closeSync(fd);
+  }
+  return header.subarray(0, 16).toString('ascii') === 'SQLite format 3\0' && header[18] === 2;
+}
+
+function tableExists(db: Database, tableName: string): boolean {
+  return Boolean(
+    db.query(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?`).get(tableName),
+  );
+}
+
+function readHistoryRows(
+  dbPath: string,
+  options: { readonly?: boolean; readwrite?: boolean; create?: boolean },
+): HistoryVideoRow[] {
+  const db = new Database(dbPath, options);
+  try {
+    const hasMediaArt = tableExists(db, 'imm_media_art');
+    const coverSelect = hasMediaArt
+      ? `COALESCE(
+          ma.cover_blob_hash,
+          (SELECT ma2.cover_blob_hash
+           FROM imm_media_art ma2
+           JOIN imm_videos v2 ON v2.video_id = ma2.video_id
+           WHERE v2.anime_id = v.anime_id AND ma2.cover_blob_hash IS NOT NULL
+           LIMIT 1)
+        ) AS cover_blob_hash`
+      : 'NULL AS cover_blob_hash';
+    const coverJoin = hasMediaArt ? 'LEFT JOIN imm_media_art ma ON ma.video_id = v.video_id' : '';
+    const rows = db
+      .query<RawHistoryRow>(
+        `
+        SELECT
+          v.video_id,
+          v.source_path,
+          v.parsed_title,
+          v.parsed_season,
+          v.parsed_episode,
+          COALESCE(a.title_romaji, a.canonical_title) AS anime_title,
+          MAX(CAST(s.started_at_ms AS INTEGER)) AS last_watched_ms,
+          ${coverSelect}
+        FROM imm_sessions s
+        JOIN imm_videos v ON v.video_id = s.video_id
+        LEFT JOIN imm_anime a ON a.anime_id = v.anime_id
+        ${coverJoin}
+        WHERE v.source_type = 1 AND v.source_path IS NOT NULL AND v.source_path != ''
+        GROUP BY v.video_id
+        ORDER BY last_watched_ms DESC
+        `,
+      )
+      .all();
+
+    return rows
+      .filter((row) => typeof row.source_path === 'string' && row.source_path.length > 0)
+      .map((row) => ({
+        videoId: row.video_id,
+        sourcePath: row.source_path!,
+        parsedTitle: row.parsed_title,
+        parsedSeason: row.parsed_season,
+        parsedEpisode: row.parsed_episode,
+        animeTitle: row.anime_title,
+        lastWatchedMs: Number(row.last_watched_ms ?? 0),
+        coverBlobHash: row.cover_blob_hash,
+      }));
+  } finally {
+    db.close();
+  }
+}
@@ -0,0 +1,132 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseMediaInfo } from '../src/jimaku/utils.js';
+import { collectVideos } from './picker.js';
+import type { HistorySeriesEntry, HistoryVideoRow, SeasonDirEntry } from './history-types.js';
+
+const SEASON_DIR_PATTERN = /^(?:season|s)[\s._-]*(\d{1,3})\b/i;
+
+export function seasonNumberFromDirName(name: string): number | null {
+  const match = name.trim().match(SEASON_DIR_PATTERN);
+  if (!match) return null;
+  const parsed = Number.parseInt(match[1]!, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+export function resolveSeriesRoot(filePath: string): string {
+  const parent = path.dirname(filePath);
+  if (seasonNumberFromDirName(path.basename(parent)) !== null) {
+    return path.dirname(parent);
+  }
+  return parent;
+}
+
+export function groupHistoryBySeries(
+  rows: HistoryVideoRow[],
+  existsFn: (candidate: string) => boolean = fs.existsSync,
+): HistorySeriesEntry[] {
+  const byRoot = new Map<string, HistorySeriesEntry>();
+  const sorted = [...rows].sort((a, b) => b.lastWatchedMs - a.lastWatchedMs);
+
+  for (const row of sorted) {
+    const seriesRoot = resolveSeriesRoot(row.sourcePath);
+    const existing = byRoot.get(seriesRoot);
+    if (existing) {
+      if (existing.coverBlobHash === null && row.coverBlobHash !== null) {
+        existing.coverBlobHash = row.coverBlobHash;
+      }
+      continue;
+    }
+    if (!existsFn(seriesRoot)) continue;
+    const displayName =
+      row.parsedTitle?.trim() || row.animeTitle?.trim() || path.basename(seriesRoot);
+    byRoot.set(seriesRoot, {
+      seriesRoot,
+      displayName,
+      lastWatched: row,
+      coverBlobHash: row.coverBlobHash,
+    });
+  }
+
+  return Array.from(byRoot.values());
+}
+
+function compareNatural(a: string, b: string): number {
+  return a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' });
+}
+
+export function sortVideosByEpisode(videos: string[]): string[] {
+  const parsed = videos.map((video) => ({ video, info: parseMediaInfo(video) }));
+  parsed.sort((a, b) => {
+    if (a.info.episode !== null && b.info.episode !== null) {
+      const seasonA = a.info.season ?? 0;
+      const seasonB = b.info.season ?? 0;
+      if (seasonA !== seasonB) return seasonA - seasonB;
+      if (a.info.episode !== b.info.episode) return a.info.episode - b.info.episode;
+    }
+    return compareNatural(a.video, b.video);
+  });
+  return parsed.map((entry) => entry.video);
+}
+
+function dirContainsVideo(dir: string): boolean {
+  return collectVideos(dir, true).length > 0;
+}
+
+export function listSeasonDirs(seriesRoot: string): SeasonDirEntry[] {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(seriesRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const dirs = entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => ({
+      name: entry.name,
+      path: path.join(seriesRoot, entry.name),
+      season: seasonNumberFromDirName(entry.name),
+    }))
+    .filter((entry) => dirContainsVideo(entry.path));
+
+  dirs.sort((a, b) => {
+    if (a.season !== null && b.season !== null && a.season !== b.season) {
+      return a.season - b.season;
+    }
+    return compareNatural(a.name, b.name);
+  });
+  return dirs;
+}
+
+function findFirstEpisodeInNextSeason(resolvedLast: string, dir: string): string | null {
+  const seriesRoot = resolveSeriesRoot(resolvedLast);
+  if (seriesRoot === dir) return null;
+  const seasons = listSeasonDirs(seriesRoot);
+  const currentIdx = seasons.findIndex((season) => path.resolve(season.path) === dir);
+  if (currentIdx < 0 || currentIdx + 1 >= seasons.length) return null;
+  const nextSeason = sortVideosByEpisode(collectVideos(seasons[currentIdx + 1]!.path, false));
+  return nextSeason[0] ?? null;
+}
+
+export function findNextEpisode(lastPath: string): string | null {
+  const resolvedLast = path.resolve(lastPath);
+  const dir = path.dirname(resolvedLast);
+  const episodes = sortVideosByEpisode(collectVideos(dir, false));
+  const idx = episodes.indexOf(resolvedLast);
+
+  if (idx >= 0) {
+    if (idx + 1 < episodes.length) return episodes[idx + 1]!;
+  } else {
+    const lastInfo = parseMediaInfo(resolvedLast);
+    if (lastInfo.episode !== null) {
+      const candidate = episodes.find((episode) => {
+        const info = parseMediaInfo(episode);
+        return info.episode !== null && info.episode > lastInfo.episode!;
+      });
+      if (candidate) return candidate;
+    }
+  }
+
+  return findFirstEpisodeInNextSeason(resolvedLast, dir);
+}
@@ -0,0 +1,23 @@
+export interface HistoryVideoRow {
+  videoId: number;
+  sourcePath: string;
+  parsedTitle: string | null;
+  parsedSeason: number | null;
+  parsedEpisode: number | null;
+  animeTitle: string | null;
+  lastWatchedMs: number;
+  coverBlobHash: string | null;
+}
+
+export interface HistorySeriesEntry {
+  seriesRoot: string;
+  displayName: string;
+  lastWatched: HistoryVideoRow;
+  coverBlobHash: string | null;
+}
+
+export interface SeasonDirEntry {
+  name: string;
+  path: string;
+  season: number | null;
+}
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
sudacode	dfde19cc4d	fix(launcher): address sync review feedback	2026-07-09 00:30:43 -07:00
sudacode	58d54311d8	fix(launcher): address code review findings in stats sync - merge-catalog: stop dropping anilist_id on every new anime insert (bun:sqlite .get() returns null, so the old !== undefined guard always fired); the guard was dead anyway since a colliding id is caught earlier - sync-command: throw instead of fail() inside runHostSync so the finally block runs and temp dirs holding snapshot data are cleaned up on failure - ssh: shell-quote the user-supplied --remote-cmd in the probe, and reject option-like (-prefixed) SSH hosts that ssh/scp would parse as flags - sync-db: close the remote handle if opening the local DB throws - sync-shared: treat EPERM from process.kill(pid, 0) as alive, not dead - cli-parser: trim the sync host before the mode-exclusivity check - tests: cover anilist_id preservation, anilist-based anime matching, and the SSH host/shell-quote guards	2026-07-08 23:51:46 -07:00
sudacode	be31f96f02	feat(launcher): add sync command to merge stats and history between machines over SSH subminer sync <host> exchanges VACUUM INTO snapshots over ssh/scp and each side merges the other's data as an insert-only union keyed on session UUIDs, video keys, series title keys, and word/kanji identity. Lifetime totals and daily/monthly rollups are applied incrementally so pre-retention history survives, remote-only historical rollups are copied, and re-syncing is idempotent. sync --snapshot/--merge expose the underlying steps for manual transfers; a pid-file/mpv-socket guard refuses to run while SubMiner may be writing the database and schema-version mismatches abort the merge.	2026-07-08 23:28:10 -07:00
sudacode	cdb1475a54	chore(assets): update icons and favicons	2026-07-08 22:35:47 -07:00
sudacode	a2e49b369b	fix(tokenizer): merge scanner metadata per token instead of all-or-nothi - Replace hasSameTokenSpans + full-discard with mergeScannerTokensIntoParseTokens - Grafts isNameMatch/frequencyRank/etc onto matching parse spans; filler chunks degrade only themselves - Fixes name annotations dropping for entire subtitle lines containing unmatched interjections	2026-07-08 22:26:34 -07:00
sudacode	7f13aed50a	fix(overlay): keep frequency/JLPT highlight for kanji non-independent nouns (#150 )	2026-07-08 22:25:32 -07:00
sudacode	8b21a2bca8	fix(overlay): remove content adverbs from annotation stop-word list - 確かに and やはり no longer excluded from frequency/JLPT highlighting and vocab stats - Stop-word list now covers only interjections, pronouns, and grammar fragments	2026-07-08 20:15:45 -07:00
sudacode	925413adfe	chore(release): prepare 0.18.0-beta.2	2026-07-08 02:31:14 -07:00
sudacode	d0644ab2eb	fix(stats): parse v3 reading-aware known-word cache in stats server (#149 )	2026-07-08 02:15:58 -07:00
sudacode	d253710c2e	fix(stats): fetch cover art eagerly at session start instead of on series page visit (#148 )	2026-07-08 00:59:35 -07:00
sudacode	c3df510e4f	docs(release): reclassify audio normalization as added, not fixed - Move card audio normalization entry from Fixed → Added in prerelease notes - Update changes/audio-normalization.md type: fixed → added	2026-07-08 00:38:38 -07:00
sudacode	187f68e5b6	fix(tokenizer): prevent grammar tokens from borrowing known-word highlight via unrelated readings (#147 )	2026-07-07 23:57:47 -07:00
sudacode	0e254cbbef	fix(launcher): move fzf previews below menus	2026-07-07 22:36:56 -07:00
sudacode	7b94adafbd	chore(release): prepare 0.18.0-beta.1	2026-07-07 02:40:05 -07:00
sudacode	61f39d1e09	fix(overlay): resolve unspaced Japanese name splits and scan recovery (#146 )	2026-07-07 02:33:46 -07:00
sudacode	e7739de51c	fix(tokenizer): keep unparsed Yomitan tokens hoverable (#145 )	2026-07-07 02:01:04 -07:00
sudacode	ad1d240f20	refactor(tests): centralize lane definitions and add per-file isolation (#143 )	2026-07-07 01:51:05 -07:00
sudacode	8b0ef662bc	chore: remove shipped changelog entries and demo asset - Drop changes/kiku-field-grouping-modal-wiring.md (landed in #138) - Drop changes/known-word-partial-reading-highlight.md (landed in #142) - Remove assets/minecard.mkv demo video	2026-07-07 00:18:48 -07:00
sudacode	0a58c20ad7	fix(stats): start stats server on background app launch (#144 )	2026-07-07 00:16:57 -07:00
sudacode	38ddb29aa0	feat(anki): reading-aware known-word matching (cache v3) (#142 )	2026-07-07 00:13:10 -07:00
sudacode	8b9a70c5a6	feat(stats): Trends dashboard overhaul — title visibility, ranking modes, calendar-accurate windows, tooltips (#140 )	2026-07-06 23:52:43 -07:00
sudacode	48a084914a	feat(branding): replace app icon with contributed pixel-art set (#141 )	2026-07-06 23:31:19 -07:00
sudacode	a042b04357	fix(overlay): prevent field grouping modal from freezing overlay on Hyprland (#138 )	2026-07-06 22:13:14 -07:00
sudacode	35ca2afc6f	fix(overlay): collapse karaoke syllable spam in secondary subtitles (#139 )	2026-07-06 01:09:06 -07:00
sudacode	b14f977e33	fix(tokenizer): stop partial furigana readings from marking words known (#137 )	2026-07-05 17:02:44 -07:00
sudacode	eef4500599	feat(launcher): add -H/--history command to browse local watch history (#136 )	2026-07-05 16:46:05 -07:00
sudacode	73af1451b7	fix(anki): lower audio normalization target to -23 LUFS (EBU R128)	2026-07-05 01:13:54 -07:00
sudacode	36a3704815	fix(youtube): parse mpv EDL stream URLs with byte-length guards (#134 )	2026-07-02 01:37:37 -07:00
sudacode	359cb0a301	Normalize generated Anki audio by default (#135 )	2026-07-02 00:34:16 -07:00
sudacode	4b10e85053	chore(release): prepare v0.17.2	2026-06-28 23:03:18 -07:00
sudacode	c942a2cf2d	fFix(youtube): recover source URL for background media cache on direct mpv open (#132 )	2026-06-28 22:46:11 -07:00
sudacode	f65afa6046	feat(youtube): notify on manual picker open and show success after track load (#133 )	2026-06-28 22:43:16 -07:00
sudacode	389d8e06e0	chore: remove stale npm artifacts	2026-06-28 20:18:08 -07:00
sudacode	0008b55b70	chore(release): prepare v0.17.1	2026-06-27 22:59:28 -07:00
sudacode	d16ae9c745	chore(release): prepare v0.17.1-beta.1	2026-06-27 22:10:02 -07:00
sudacode	36f94151b8	fix(logs): use local date for log filenames and expand export redaction (#131 )	2026-06-27 21:08:11 -07:00
sudacode	5326ad32f5	feat(youtube): add mediaCache mode and safer stream media extraction (#130 )	2026-06-27 19:20:18 -07:00
sudacode	d199376364	chore(release): prepare v0.17.0	2026-06-15 01:58:42 -07:00
sudacode	3aee88c150	chore(release): prepare v0.17.0-beta.2	2026-06-14 20:58:26 -07:00
sudacode	70da3ee8bd	Fix Windows Anki startup and overlay regressions (#128 )	2026-06-14 20:51:56 -07:00
sudacode	aa8eb753f6	fix: scope prerelease note reuse by version	2026-06-14 18:04:03 -07:00
sudacode	8d73de8731	docs: scope 0.17.0 beta prerelease notes	2026-06-14 17:50:09 -07:00
sudacode	5a98397efe	chore: prepare 0.17.0-beta.1 prerelease	2026-06-14 17:34:05 -07:00
sudacode	a117c5759c	fix(linux): auto-install managed plugin copy; include in asset updates (#127 )	2026-06-14 17:25:28 -07:00
sudacode	ae7e6f82a8	fix(overlay): restore macOS Yomitan popup focus without breaking click-away (#125 )	2026-06-14 16:46:13 -07:00
sudacode	1158be5b39	fix(overlay): preserve visible state across playlist item transitions (#124 )	2026-06-12 23:38:54 -07:00
sudacode	33e767458f	refactor(main): split main.ts into focused runtime modules (#123 )	2026-06-12 17:35:46 -07:00
sudacode	94a65416ae	fix(stats): strip Season N suffix from AniList title searches (#121 )	2026-06-12 01:07:11 -07:00
sudacode	0a384a22c9	Replace subtitle delay actions with native mpv keybindings (#120 )	2026-06-12 00:03:06 -07:00
sudacode	b3b45521b6	fix(release): preserve attribution placement; default update notifs to o - Move What's Changed/New Contributors before Installation in release notes - Preserve committed attribution when regenerating via writeReleaseNotesForVersion - Change notificationType default from 'both' to 'overlay' for new installs	2026-06-10 23:53:31 -07:00
sudacode	131b23efa9	chore(release): prepare v0.16.0	2026-06-10 23:05:37 -07:00
sudacode	e2afceb492	fix(anki): write sentence card audio only to sentence audio field (#118 )	2026-06-10 22:51:19 -07:00
sudacode	7be1843c41	feat(notifications): add overlay notifications with position config (#110 )	2026-06-10 22:46:52 -07:00
sudacode	c09d009a3e	docs: add ani-skip to credits table in README	2026-06-10 00:01:51 -07:00
sudacode	2007e28be8	feat(aniskip): move intro detection from mpv plugin to app runtime (#117 )	2026-06-09 23:55:43 -07:00
sudacode	d5bfdcae7b	fix(stats): repair legacy combined-season anime rows on startup (#116 )	2026-06-09 12:41:07 -07:00
sudacode	311f1e8ee5	feat(stats): speed up session maintenance and improve stats UI (#111 )	2026-06-08 02:20:52 -07:00
sudacode	e6a16a069b	fix(anilist): mark entry completed when final episode is reached (#115 )	2026-06-07 23:45:09 -07:00
Autumn (Bee)	af67c53dd6	[codex] Restart Jellyfin remote session after setup login (#112 )	2026-06-06 11:52:16 -07:00
sudacode	ea79e331fa	build: make deps initializes submodules before installing JS deps - Add `submodules` target that runs `git submodule update --init --recursive` - `deps` now depends on `submodules` so fresh checkouts work out of the box - Update docs to replace manual install steps with `make deps` - Fix Windows build-from-source steps to include stats and submodule init	2026-06-06 01:25:01 -07:00
sudacode	ee89b0c8a9	feat(release): add contributor attribution to release notes (#114 )	2026-06-06 01:07:47 -07:00
sudacode	f2fd58cd2b	docs(changelog): require reconciled fragments, not just new ones (#113 )	2026-06-06 00:55:34 -07:00
sudacode	1280a30216	chore(release): prepare 0.15.2	2026-06-02 23:45:03 -07:00
sudacode	a80ed72b2d	docs: replace em-dashes with hyphens across docs-site	2026-06-02 23:36:44 -07:00
sudacode	4cc6c12dc7	chore(vendor): update subminer-yomitan submodule (#109 )	2026-06-02 00:37:45 -07:00
sudacode	425004879a	fix(anki): align animated AVIF clip bounds to frame boundaries (#108 )	2026-06-01 15:20:06 -07:00
sudacode	76f99e6518	fix(overlay): correct Hyprland fullscreen overlay alignment on Linux (#107 )	2026-06-01 02:12:16 -07:00
sudacode	f1e260e996	fix(overlay): fix macOS overlay interactivity and focus after autoplay (#106 )	2026-06-01 01:34:27 -07:00