chore(release): finalize v0.11.1 prep

Updated SubMiner demo image link to a GitHub asset.

CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## v0.11.1 (2026-04-04)
+
+### Fixed
+- Release: Linux packaged builds now expose the canonical `SubMiner` app identity to Electron's startup metadata so native Wayland compositors stop reporting the window class/app-id as lowercase `subminer`.
+- Linux: Linux now restores the runtime options, Jimaku, and Subsync shortcuts after the Electron 39 regression by routing those actions through the overlay's mpv/IPC shortcut path.
+
+## v0.11.0 (2026-04-03)
+
+### Added
+- Overlay: Added a playlist browser overlay modal for browsing sibling video files and the live mpv queue during playback.
+- Overlay: Added the default `Ctrl+Alt+P` keybinding to open the playlist browser and manage queue order without leaving playback.
+
+### Changed
+- Setup: Made mpv plugin installation mandatory in the first-run setup flow, removed the skip path, and kept Finish disabled until the plugin is installed.
+- Setup: Clarified that the mpv plugin requirement applies to setup on every platform, while the optional `SubMiner mpv` shortcut remains the recommended Windows playback entry point.
+- Launcher: Streamlined Windows setup and config by making the `SubMiner mpv` shortcut self-contained and keeping `mpv.executablePath` as the simple fallback when `mpv.exe` is not on `PATH`.
+- Overlay: Changed fresh-install default config to keep texthooker and stats from auto-opening browser tabs.
+- Overlay: Changed fresh-install default config to enable AnkiConnect, Discord Rich Presence, subtitle-sidebar, and Yomitan-popup auto-pause by default, while disabling controller input by default.
+
+### Fixed
+- Main: Resolve the YouTube playback socket path lazily so startup honors CLI and config overrides.
+- Main: Add regression coverage for the lazy socket-path lookup during Windows mpv startup.
+- Main: Keep integrated `--start --texthooker` launches on the full app-ready startup path so the texthooker page and websocket servers start together during normal playback startup.
+- Main: Stop the mpv/plugin auto-start flow from spawning a separate standalone texthooker helper during normal `subminer <video>` launches.
+- Overlay: Keep tracked macOS visible overlays click-through by default so subtitle sidebar passthrough works immediately without requiring a subtitle hover cycle first.
+- Overlay: Add regression coverage for the macOS visible-overlay passthrough default.
+- Anilist: Stop AniList post-watch from sending a second progress update when the current episode was already satisfied by a ready retry item in the same watch-completion pass.
+- Anilist: Add regression coverage for the retry-queue plus live-update duplicate path.
+- Overlay: Fixed Kiku duplicate grouping to reuse duplicate note IDs from both generic sentence-card creation and Yomitan popup mining instead of running extra duplicate scans after add.
+- Overlay: Fixed the Yomitan popup mining flow to add cards in the background while keeping the stock popup progress feedback, then pause playback and close the lookup popup before the Kiku merge modal opens.
+- Overlay: Fixed configured subtitle-jump keybindings so backward and forward subtitle seeks keep playback paused when invoked from a paused state.
+- Launcher: Fixed the Windows `SubMiner mpv` shortcut and `SubMiner.exe --launch-mpv` flow to launch mpv with SubMiner's required default args directly instead of requiring an `mpv.conf` profile named `subminer`.
+- Launcher: Clarified the Windows install and usage docs so the shortcut path is documented as self-contained, while the optional `subminer` mpv profile remains available for manual mpv launches.
+- Launcher: Hardened the first-run setup blocker copy and stale custom-scheme handling so setup messages stay aligned with config, plugin, and dictionary readiness.
+- Launcher: Fixed the Windows `SubMiner mpv` shortcut idle launch so loading a video after opening the shortcut keeps mpv in the expected SubMiner-managed session, auto-starts the overlay, and re-arms subtitle auto-selection for the newly opened file.
+- Launcher: Removed the redundant `.` subtitle search path from the Windows shortcut launch args and deduped repeated subtitle source tracks in the manual sync picker so duplicate external subtitle entries no longer appear from the shortcut path.
+- Playback: Fixed managed local playback so duplicate startup-ready retries no longer unpause media after a later manual pause on the same file.
+- Playback: Fixed managed local subtitle auto-selection so local files reuse configured primary and secondary subtitle language priorities instead of staying on mpv's initial `sid=auto` guess.
+- Launcher: Added a blank-by-default `mpv.executablePath` override for Windows playback so users can point SubMiner at `mpv.exe` when it is not on `PATH`.
+- Launcher: Kept the Windows shortcut and `--launch-mpv` flow simple by preserving PATH auto-discovery as the default and exposing the override in first-run setup.
+- Launcher: Added `windows` as a recognized launcher backend option and auto-detection target on Windows.
+- Launcher: Honored `SUBMINER_YTDLP_BIN` consistently across YouTube playback URL resolution, track probing, subtitle downloads, and metadata probing.
+- Launcher: Kept the first-run setup window from navigating away on unexpected URLs.
+- Launcher: Made Windows mpv honor an explicitly configured executable path instead of silently falling back to PATH.
+- Launcher: Hardened `--launch-mpv` parsing and Windows binary resolution so valueless flags do not swallow media targets and symlinked launcher installs do not short-circuit PATH lookup.
+- Launcher: Fixed first-run setup blocking playback on macOS when the SubMiner mpv plugin was already installed at the canonical `~/.config/mpv` path.
+- Launcher: Fixed setup gating so stale cancelled setup state no longer prevents playback when the canonical mpv plugin entrypoint already exists.
+- Playback: Prevented stale async playlist-browser subtitle rearm callbacks from overriding newer subtitle selections during rapid file changes.
+
+### Docs
+- Docs Site: Added a dedicated Subtitle Sidebar guide and linked it from the homepage and configuration docs.
+- Docs Site: Linked Jimaku integration from the homepage to its dedicated docs page.
+- Docs Site: Refreshed docs-site theme tokens and hover/selection styling for the updated pages.
+
+### Internal
+- Release: Retried AUR clone and push operations in the tagged release workflow.
+- Release: Kept GitHub Releases green when AUR publish flakes and needs manual follow-up.
+- Release: Updated Electron to 39.8.6 and pinned patched transitive build dependencies to clear the reported high-severity audit findings.
+
 ## v0.10.0 (2026-03-29)
 
 ### Changed

README.md

@@ -13,7 +13,7 @@ Look up words with Yomitan, export to Anki in one key, track your immersion —
 [![Docs](https://img.shields.io/badge/docs-docs.subminer.moe-e6a817?style=flat-square)](https://docs.subminer.moe)
 [![AUR](https://img.shields.io/aur/version/subminer-bin?style=flat-square&color=1a1a2e)](https://aur.archlinux.org/packages/subminer-bin)
 
-[![SubMiner demo](./assets/minecard.webp)](./assets/minecard.mp4)
+[![SubMiner demo](./assets/minecard.webp)](https://github.com/user-attachments/assets/89e61895-e2b7-4b47-8d50-a35afe4132b2)
 
 </div>
 
@@ -21,6 +21,8 @@ Look up words with Yomitan, export to Anki in one key, track your immersion —
 
 SubMiner runs as an invisible Electron overlay on top of mpv. Subtitles render as an interactive layer. Move your cursor over any word and trigger a [Yomitan](https://github.com/yomidevs/yomitan) lookup. Press one key to snapshot the sentence, audio, and screenshot into Anki via AnkiConnect.
 
+First-run setup requires the mpv plugin before it can finish. On Windows, the optional `SubMiner mpv` shortcut created during setup is the recommended playback entry point because it launches `mpv` with SubMiner's defaults directly, so you do not need an `mpv.conf` profile just to use it.
+
 ## Features
 
 ### Dictionary Lookups
@@ -67,6 +69,8 @@ Local stats dashboard — watch time, anime library, vocabulary growth, mining t
 
 Browse sibling episode files and the active mpv queue in one overlay modal. Open it with `Ctrl+Alt+P` to append episodes from the current directory, jump to queued items, remove entries, or reorder the playlist without leaving playback.
 
+Managed local playback now reapplies your configured subtitle language priorities after mpv loads track metadata, so mixed subtitle sets can settle onto the expected primary and secondary tracks instead of staying on mpv's initial `sid=auto` guess.
+
 <br>
 
 ### Integrations
@@ -74,7 +78,7 @@ Browse sibling episode files and the active mpv queue in one overlay modal. Open
 <table>
   <tr>
     <td><b>YouTube</b></td>
-    <td>Auto-loaded yt-dlp subtitle tracks at startup with a manual overlay picker on demand (<code>Ctrl+Alt+C</code>)</td>
+    <td>Auto-loaded yt-dlp subtitle tracks at startup with config-driven primary/secondary language priorities and a manual overlay picker on demand (<code>Ctrl+Alt+C</code>)</td>
   </tr>
   <tr>
     <td><b>AniList</b></td>
@@ -108,12 +112,12 @@ Browse sibling episode files and the active mpv queue in one overlay modal. Open
 
 ## Requirements
 
-|                | Required                                | Optional                               |
-| -------------- | --------------------------------------- | -------------------------------------- |
-| **Player**     | [`mpv`](https://mpv.io) with IPC socket | —                                      |
+|                | Required                                | Optional                                                   |
+| -------------- | --------------------------------------- | ---------------------------------------------------------- |
+| **Player**     | [`mpv`](https://mpv.io) with IPC socket | —                                                          |
 | **Processing** | `ffmpeg`, `mecab` + `mecab-ipadic`      | `guessit` (AniSkip), `alass` / `ffsubsync` (subtitle sync) |
-| **Media**      | —                                       | `yt-dlp`, `chafa`, `ffmpegthumbnailer` |
-| **Selection**  | —                                       | `fzf` / `rofi`                         |
+| **Media**      | —                                       | `yt-dlp`, `chafa`, `ffmpegthumbnailer`                     |
+| **Selection**  | —                                       | `fzf` / `rofi`                                             |
 
 > [!NOTE]
 > [`bun`](https://bun.sh) is required if building from source or using the CLI wrapper: `subminer`. Pre-built releases (AppImage, DMG, installer) do not require it.
@@ -224,7 +228,7 @@ See the [build-from-source guide](https://docs.subminer.moe/installation#from-so
 
 ### 2. First Launch
 
-Run the app. On first launch SubMiner starts in the system tray, creates a default config, and opens a setup popup to install the mpv plugin and configure Yomitan dictionaries.
+Run the app. On first launch SubMiner starts in the system tray, creates a default config, and opens a setup popup to finish config, install the mpv plugin, and configure Yomitan dictionaries.
 
 ### 3. Mine
 
@@ -236,8 +240,6 @@ subminer stats -b           # stats daemon in background
 subminer stats -s           # stop background stats daemon
 ```
 
----
-
 ## Documentation
 
 Full guides on configuration, Anki setup, Jellyfin, immersion tracking, and more: **[docs.subminer.moe](https://docs.subminer.moe)**

backlog/archive/tasks/task-279 - Prepare-v0.11.2-release-notes-and-verify-release-gate.md

@@ -0,0 +1,23 @@
+---
+id: TASK-279
+title: Prepare v0.11.2 release notes and verify release gate
+status: In Progress
+assignee: []
+created_date: '2026-04-04 07:38'
+labels: []
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Generate release metadata for the pending changelog fragments, review the resulting changelog/release notes output, and run the documented local release gate so the repo is ready for a v0.11.2 cut if checks pass.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 CHANGELOG.md and release/release-notes.md are generated for v0.11.2 using the pending changes fragments.
+- [ ] #2 The documented local release gate for release prep is run and the pass/fail state is recorded with any blockers.
+- [ ] #3 Any release-prep file updates needed for the generated notes are left in the worktree for review without tagging or pushing.
+<!-- AC:END -->

backlog/completed/task-272 - Assess-and-address-PR-40-CodeRabbit-review-follow-ups.md

@@ -0,0 +1,39 @@
+---
+id: TASK-272
+title: 'Assess and address PR #40 CodeRabbit review follow-ups'
+status: Done
+assignee: []
+created_date: '2026-04-03 07:52'
+updated_date: '2026-04-03 08:04'
+labels:
+  - coderabbit
+  - review
+  - launcher
+milestone: 'PR #40'
+dependencies: []
+references:
+  - 'https://github.com/ksyasuda/SubMiner/pull/40'
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Implement the valid CodeRabbit findings on PR #40 and keep the Windows mpv shortcut / first-run setup flow consistent end to end.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 Windows binary resolution does not return install directories as executable candidates
+- [ ] #2 Launch-mpv arg parsing preserves space-separated mpv option values and target separation
+- [ ] #3 Windows mpv launch args keep the final input-ipc-server and script-opts socket path in sync when custom values are supplied
+- [ ] #4 First-run setup navigation swallows stale or invalid custom-scheme actions without navigating away
+- [ ] #5 Setup messaging and footer copy reflect configReady, plugin, and dictionary gates consistently
+- [ ] #6 Regression tests cover the fixed behaviors
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Addressed CodeRabbit follow-ups for PR #40. Hardened launcher binary discovery on Windows and PATH resolution, fixed launch-mpv argument parsing for value-bearing flags, synced custom Windows mpv IPC socket values into script opts, and tightened first-run setup messaging/navigation to handle stale actions and blocker copy. Verified with `bun test src/main-entry-runtime.test.ts src/main/runtime/windows-mpv-launch.test.ts src/main/runtime/first-run-setup-window.test.ts launcher/mpv.test.ts`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-219 - Restore-streamed-video-progress-in-anime-episodes.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-22 21:25'
-updated_date: '2026-03-24 06:44'
+updated_date: '2026-03-31 19:37'
 labels:
   - stats
   - immersion-tracker
@@ -21,6 +21,7 @@ references:
   - >-
     /Users/sudacode/projects/japanese/SubMiner/src/core/services/immersion-tracker-service.test.ts
 priority: medium
+ordinal: 178500
 ---
 
 ## Description

backlog/tasks/task-234 - Address-PR-35-latest-CodeRabbit-review-round.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-26 03:59'
-updated_date: '2026-03-26 04:01'
+updated_date: '2026-03-31 19:37'
 labels:
   - review-comments
   - coderabbit
@@ -18,6 +18,7 @@ references:
   - >-
     /Users/sudacode/projects/japanese/SubMiner/src/main/runtime/youtube-playback-launch.ts
 priority: medium
+ordinal: 177500
 ---
 
 ## Description

backlog/tasks/task-235 - Address-PR-35-autoplay-retry-CodeRabbit-follow-up.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-26 04:30'
-updated_date: '2026-03-26 04:31'
+updated_date: '2026-03-31 19:37'
 labels:
   - review-comments
   - coderabbit
@@ -13,6 +13,7 @@ dependencies: []
 references:
   - /Users/sudacode/projects/japanese/SubMiner/src/main.ts
 priority: medium
+ordinal: 176500
 ---
 
 ## Description

backlog/tasks/task-238.3 - Introduce-domain-type-entrypoints-and-shrink-src-types.ts-import-surface.md

@@ -4,7 +4,7 @@ title: Introduce domain type entrypoints and shrink src/types.ts import surface
 status: Done
 assignee: []
 created_date: '2026-03-26 20:49'
-updated_date: '2026-03-27 00:14'
+updated_date: '2026-03-31 19:37'
 labels:
   - tech-debt
   - types
@@ -18,6 +18,7 @@ references:
   - docs/architecture/README.md
 parent_task_id: TASK-238
 priority: medium
+ordinal: 174500
 ---
 
 ## Description
@@ -27,7 +28,6 @@ priority: medium
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
 - [x] #1 Domain-focused type modules exist for the main clusters currently mixed together in `src/types.ts` (for example Anki, config/runtime, subtitle/media, and integration/runtime-option types).
 - [x] #2 `src/types.ts` becomes a thinner compatibility layer or barrel instead of the sole source of truth for every shared type.

backlog/tasks/task-238.4 - Decompose-character-dictionary-runtime-into-fetch-build-and-cache-modules.md

@@ -1,10 +1,10 @@
 ---
 id: TASK-238.4
-title: Decompose character dictionary runtime into fetch, build, and cache modules
+title: 'Decompose character dictionary runtime into fetch, build, and cache modules'
 status: Done
-updated_date: '2026-03-27 00:20'
 assignee: []
 created_date: '2026-03-26 20:49'
+updated_date: '2026-03-31 19:37'
 labels:
   - tech-debt
   - runtime
@@ -19,6 +19,7 @@ references:
   - docs/architecture/README.md
 parent_task_id: TASK-238
 priority: medium
+ordinal: 173500
 ---
 
 ## Description
@@ -28,7 +29,6 @@ priority: medium
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
 - [x] #1 AniList fetch/parsing logic, dictionary-entry building, and snapshot/cache/zip persistence no longer live in one giant file.
 - [x] #2 The public runtime API stays behavior-compatible for current callers.

backlog/tasks/task-238.5 - Split-immersion-tracker-query-layer-into-focused-read-model-modules.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-26 20:49'
-updated_date: '2026-03-27 00:00'
+updated_date: '2026-03-31 19:37'
 labels:
   - tech-debt
   - stats
@@ -20,6 +20,7 @@ references:
   - src/core/services/immersion-tracker-service.ts
 parent_task_id: TASK-238
 priority: medium
+ordinal: 175500
 ---
 
 ## Description
@@ -29,7 +30,6 @@ priority: medium
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
 - [x] #1 Query responsibilities are grouped into focused modules such as library/session detail, vocabulary/kanji detail, and maintenance/cleanup helpers.
 - [x] #2 The stats server and immersion tracker service depend on stable exported query surfaces instead of one monolithic file.

backlog/tasks/task-238.6 - Extract-remaining-inline-runtime-logic-and-composer-gaps-from-src-main.ts.md

@@ -4,7 +4,7 @@ title: Extract remaining inline runtime logic and composer gaps from src/main.ts
 status: Done
 assignee: []
 created_date: '2026-03-27 00:00'
-updated_date: '2026-03-27 22:13'
+updated_date: '2026-03-31 19:37'
 labels:
   - tech-debt
   - runtime
@@ -24,6 +24,7 @@ references:
   - src/main/runtime/composers
 parent_task_id: TASK-238
 priority: high
+ordinal: 172500
 ---
 
 ## Description
@@ -33,7 +34,6 @@ priority: high
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
 - [x] #1 `runYoutubePlaybackFlow`, `maybeSignalPluginAutoplayReady`, `refreshSubtitlePrefetchFromActiveTrack`, `publishDiscordPresence`, and `handleModalInputStateChange` no longer live as substantial inline logic in `src/main.ts`.
 - [x] #2 The large subtitle/prefetch, stats startup, and overlay visibility dependency groupings are wrapped behind named composer helpers instead of remaining inline in `src/main.ts`.

backlog/tasks/task-238.7 - Split-src-main.ts-into-boot-phase-services-runtimes-and-handlers.md

@@ -1,10 +1,10 @@
 ---
 id: TASK-238.7
-title: Split src/main.ts into boot-phase services, runtimes, and handlers
+title: 'Split src/main.ts into boot-phase services, runtimes, and handlers'
 status: Done
 assignee: []
 created_date: '2026-03-27 00:00'
-updated_date: '2026-03-27 22:45'
+updated_date: '2026-03-31 19:37'
 labels:
   - tech-debt
   - runtime
@@ -21,6 +21,7 @@ references:
   - src/main/runtime/composers
 parent_task_id: TASK-238
 priority: high
+ordinal: 171500
 ---
 
 ## Description
@@ -30,7 +31,6 @@ After the remaining inline runtime logic and composer gaps are extracted, `src/m
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
 - [x] #1 Service instantiation lives in a dedicated boot module instead of a large inline setup block in `src/main.ts`.
 - [x] #2 Domain runtime composition lives in a dedicated boot module, separate from lifecycle and handler dispatch.

backlog/tasks/task-242 - Fix-stats-server-Bun-fallback-in-coverage-lane.md

@@ -4,7 +4,7 @@ title: Fix stats server Bun fallback in coverage lane
 status: Done
 assignee: []
 created_date: '2026-03-29 07:31'
-updated_date: '2026-03-29 07:37'
+updated_date: '2026-03-31 19:37'
 labels:
   - ci
   - bug
@@ -13,6 +13,7 @@ dependencies: []
 references:
   - 'PR #36'
 priority: high
+ordinal: 170500
 ---
 
 ## Description

backlog/tasks/task-246 - Migrate-Discord-Rich-Presence-to-maintained-RPC-wrapper.md

@@ -4,13 +4,14 @@ title: Migrate Discord Rich Presence to maintained RPC wrapper
 status: Done
 assignee: []
 created_date: '2026-03-29 08:17'
-updated_date: '2026-03-29 08:22'
+updated_date: '2026-03-31 19:37'
 labels:
   - dependency
   - discord
   - presence
 dependencies: []
 priority: medium
+ordinal: 169500
 ---
 
 ## Description

backlog/tasks/task-247 - Strip-inline-subtitle-markup-from-subtitle-sidebar-cues.md

@@ -5,13 +5,14 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-29 10:01'
-updated_date: '2026-03-29 10:10'
+updated_date: '2026-03-31 19:37'
 labels: []
 dependencies: []
 references:
   - src/core/services/subtitle-cue-parser.ts
   - src/renderer/modals/subtitle-sidebar.ts
   - src/core/services/subtitle-cue-parser.test.ts
+ordinal: 168500
 ---
 
 ## Description

backlog/tasks/task-248 - Fix-macOS-visible-overlay-toggle-getting-immediately-restored.md

@@ -4,7 +4,7 @@ title: Fix macOS visible overlay toggle getting immediately restored
 status: Done
 assignee: []
 created_date: '2026-03-29 10:03'
-updated_date: '2026-03-29 22:14'
+updated_date: '2026-03-31 19:37'
 labels: []
 dependencies: []
 references:
@@ -13,6 +13,7 @@ references:
   - /Users/sudacode/projects/japanese/SubMiner/src/core/services/cli-command.ts
   - >-
     /Users/sudacode/projects/japanese/SubMiner/src/main/overlay-visibility-runtime.ts
+ordinal: 165500
 ---
 
 ## Description

backlog/tasks/task-249 - Fix-AniList-token-persistence-on-setup-login.md

@@ -4,7 +4,7 @@ title: Fix AniList token persistence on setup login
 status: Done
 assignee: []
 created_date: '2026-03-29 10:08'
-updated_date: '2026-03-29 19:42'
+updated_date: '2026-03-31 19:37'
 labels:
   - anilist
   - bug
@@ -15,6 +15,7 @@ documentation:
   - src/main/runtime/anilist-token-refresh.ts
   - docs-site/anilist-integration.md
 priority: high
+ordinal: 166500
 ---
 
 ## Description

backlog/tasks/task-250 - Restore-macOS-mpv-passthrough-while-overlay-subtitle-sidebar-is-open.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - '@codex'
 created_date: '2026-03-29 10:10'
-updated_date: '2026-03-29 10:23'
+updated_date: '2026-03-31 19:37'
 labels:
   - bug
   - macos
@@ -24,6 +24,7 @@ references:
   - >-
     /Users/sudacode/projects/japanese/SubMiner/src/renderer/overlay-mouse-ignore.test.ts
 priority: high
+ordinal: 167500
 ---
 
 ## Description

backlog/tasks/task-251 - Docs-add-subtitle-sidebar-and-Jimaku-integration-pages.md

@@ -4,11 +4,12 @@ title: 'Docs: add subtitle sidebar and Jimaku integration pages'
 status: Done
 assignee: []
 created_date: '2026-03-29 22:36'
-updated_date: '2026-03-29 22:38'
+updated_date: '2026-03-31 19:37'
 labels:
   - docs
 dependencies: []
 priority: medium
+ordinal: 164500
 ---
 
 ## Description

backlog/tasks/task-252 - Harden-AUR-publish-release-step-against-transient-SSH-failures.md

@@ -4,13 +4,14 @@ title: Harden AUR publish release step against transient SSH failures
 status: Done
 assignee: []
 created_date: '2026-03-29 23:46'
-updated_date: '2026-03-29 23:49'
+updated_date: '2026-03-31 19:37'
 labels:
   - release
   - ci
   - aur
 dependencies: []
 priority: high
+ordinal: 163500
 ---
 
 ## Description

backlog/tasks/task-253 - Fix-animated-AVIF-lead-in-alignment-with-sentence-audio.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-30 01:59'
-updated_date: '2026-03-30 02:03'
+updated_date: '2026-03-31 19:37'
 labels: []
 dependencies: []
 references:
@@ -14,6 +14,7 @@ references:
   - /Users/sudacode/projects/japanese/SubMiner/src/anki-integration.ts
   - /Users/sudacode/projects/japanese/SubMiner/src/core/services/stats-server.ts
   - /Users/sudacode/projects/japanese/SubMiner/src/media-generator.ts
+ordinal: 162500
 ---
 
 ## Description

backlog/tasks/task-254 - Fix-AniList-token-persistence-when-safe-storage-is-unavailable.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-30 02:10'
-updated_date: '2026-03-30 02:20'
+updated_date: '2026-03-31 19:37'
 labels:
   - bug
   - anilist
@@ -17,6 +17,7 @@ references:
   - >-
     /Users/sudacode/projects/japanese/SubMiner/src/main/runtime/anilist-token-refresh.ts
 priority: high
+ordinal: 161500
 ---
 
 ## Description

backlog/tasks/task-255 - Add-overlay-playlist-browser-modal-for-sibling-video-files-and-mpv-queue.md

@@ -1,17 +1,18 @@
 ---
 id: TASK-255
 title: Add overlay playlist browser modal for sibling video files and mpv queue
-status: In Progress
+status: Done
 assignee:
   - '@codex'
 created_date: '2026-03-30 05:46'
-updated_date: '2026-03-31 05:59'
+updated_date: '2026-03-31 19:37'
 labels:
   - feature
   - overlay
   - mpv
   - launcher
 dependencies: []
+ordinal: 180500
 ---
 
 ## Description
@@ -22,10 +23,10 @@ Add an in-session overlay modal that opens from a keybinding during active playb
 
 ## Acceptance Criteria
 <!-- AC:BEGIN -->
-- [ ] #1 An overlay modal can be opened during active playback from a dedicated keybinding and closed without disrupting existing modal behavior.
-- [ ] #2 The modal shows video files from the current media file's parent directory in best-effort episode order and highlights the current file when present.
-- [ ] #3 The modal shows the active mpv playlist/queue with enough metadata to identify the current item and queued order.
-- [ ] #4 The user can add a directory file to the mpv playlist, remove playlist items, and reorder playlist items from the modal using both mouse and keyboard interactions.
+- [x] #1 An overlay modal can be opened during active playback from a dedicated keybinding and closed without disrupting existing modal behavior.
+- [x] #2 The modal shows video files from the current media file's parent directory in best-effort episode order and highlights the current file when present.
+- [x] #3 The modal shows the active mpv playlist/queue with enough metadata to identify the current item and queued order.
+- [x] #4 The user can add a directory file to the mpv playlist, remove playlist items, and reorder playlist items from the modal using both mouse and keyboard interactions.
 - [x] #5 Modal state stays in sync after playlist mutations so the rendered queue reflects mpv's current playlist order.
 - [x] #6 Feature coverage includes automated tests for ordering/playlist behavior and docs or shortcut/help updates for the new modal.
 <!-- AC:END -->
@@ -84,4 +85,8 @@ Split playlist-browser UI row rendering into `src/renderer/modals/playlist-brows
 2026-03-30 latest CodeRabbit remediation on PR #37: switched nowMs() numeric test-clock branch from Math.floor() to Math.trunc() so numeric and string-backed mock clocks agree for negative fractional values. Refactored playlist-browser modal tests onto a shared setup/teardown fixture that restores global window/document descriptors correctly, and added regression coverage that injected globals are deleted when originally absent. Verification: `bun test src/core/services/immersion-tracker/time.test.ts src/renderer/modals/playlist-browser.test.ts`, `bun run typecheck`.
 
 2026-03-30 CodeRabbit follow-up: wrapped the injected-globals cleanup regression in try/finally so restore always runs, and changed the keydown test append mock to return createMutationSnapshot() before exercising Ctrl+ArrowDown. Verified with `bun test src/renderer/modals/playlist-browser.test.ts` and `bun run typecheck`.
+
+2026-03-31 assessment: the playlist-browser feature is landed on `main` via `d51e7fe4 Add playlist browser overlay modal (#37)` with runtime, IPC, renderer, keybinding, and changelog/docs coverage present. Verified passes: `bun test src/main/runtime/playlist-browser-runtime.test.ts src/main/runtime/playlist-browser-open.test.ts src/main/runtime/playlist-browser-sort.test.ts src/renderer/handlers/keyboard.test.ts src/core/services/ipc.test.ts src/core/services/ipc-command.test.ts src/config/definitions/domain-registry.test.ts`.
+
+Remaining action item before close: fix `src/renderer/modals/playlist-browser.test.ts` so the cleanup regression does not assume `globalThis.window` / `globalThis.document` start absent under Bun, rerun the playlist-browser modal lane (and then typecheck/build if you want the full closeout proof), then finalize the task.
 <!-- SECTION:NOTES:END -->

backlog/tasks/task-256 - Fix-texthooker-page-live-websocket-connect-send-regression.md

@@ -5,13 +5,14 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-30 06:04'
-updated_date: '2026-03-30 06:12'
+updated_date: '2026-03-31 19:37'
 labels:
   - bug
   - texthooker
   - websocket
 dependencies: []
 priority: medium
+ordinal: 160500
 ---
 
 ## Description

backlog/tasks/task-257 - Fix-texthooker-only-mode-startup-to-initialize-websocket-pipeline.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-30 06:15'
-updated_date: '2026-03-30 06:17'
+updated_date: '2026-03-31 19:37'
 labels:
   - bug
   - texthooker
@@ -13,6 +13,7 @@ labels:
   - startup
 dependencies: []
 priority: high
+ordinal: 159500
 ---
 
 ## Description

backlog/tasks/task-258 - Stop-plugin-auto-start-from-spawning-separate-texthooker-helper.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-30 06:25'
-updated_date: '2026-03-30 06:26'
+updated_date: '2026-03-31 19:37'
 labels:
   - bug
   - texthooker
@@ -14,6 +14,7 @@ labels:
   - startup
 dependencies: []
 priority: high
+ordinal: 158500
 ---
 
 ## Description

backlog/tasks/task-259 - Fix-integrated-start-texthooker-startup-skipping-texthooker-server.md

@@ -4,13 +4,14 @@ title: Fix integrated --start --texthooker startup skipping texthooker server
 status: Done
 assignee: []
 created_date: '2026-03-30 06:48'
-updated_date: '2026-03-30 06:56'
+updated_date: '2026-03-31 19:37'
 labels:
   - bug
   - texthooker
   - startup
 dependencies: []
 priority: high
+ordinal: 157500
 ---
 
 ## Description

backlog/tasks/task-260 - Fix-macOS-overlay-subtitle-sidebar-passthrough-without-requiring-a-subtitle-hover-cycle.md

@@ -7,7 +7,7 @@ status: Done
 assignee:
   - '@codex'
 created_date: '2026-03-31 00:58'
-updated_date: '2026-03-31 01:01'
+updated_date: '2026-03-31 19:37'
 labels:
   - bug
   - macos
@@ -27,6 +27,7 @@ references:
 documentation:
   - docs/workflow/verification.md
 priority: high
+ordinal: 156500
 ---
 
 ## Description

backlog/tasks/task-261 - Fix-immersion-tracker-SQLite-timestamp-truncation.md

@@ -1,9 +1,10 @@
 ---
 id: TASK-261
 title: Fix immersion tracker SQLite timestamp truncation
-status: In Progress
+status: Done
 assignee: []
 created_date: '2026-03-31 01:45'
+updated_date: '2026-03-31 19:37'
 labels:
   - immersion-tracker
   - sqlite
@@ -12,7 +13,7 @@ dependencies: []
 references:
   - src/core/services/immersion-tracker
 priority: medium
-ordinal: 1200
+ordinal: 179500
 ---
 
 ## Description
@@ -23,7 +24,17 @@ Current-epoch millisecond values are being truncated by the libsql driver when b
 
 ## Acceptance Criteria
 <!-- AC:BEGIN -->
-- [ ] #1 Current-epoch millisecond timestamps persist correctly in session, telemetry, lifetime, and rollup tables
-- [ ] #2 Startup backfill and destroy/finalize flows keep retained sessions and lifetime summaries consistent
-- [ ] #3 Regression tests cover the destroyed-session, startup backfill, and distinct-day/distinct-video lifetime semantics
+- [x] #1 Current-epoch millisecond timestamps persist correctly in session, telemetry, lifetime, and rollup tables
+- [x] #2 Startup backfill and destroy/finalize flows keep retained sessions and lifetime summaries consistent
+- [x] #3 Regression tests cover the destroyed-session, startup backfill, and distinct-day/distinct-video lifetime semantics
 <!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+2026-03-31 assessment: epoch-ms timestamp writes now route through `toDbMs()` / `toDbTimestamp()` in `src/core/services/immersion-tracker/query-shared.ts`, which avoids libsql numeric-parameter truncation by binding BigInt/string values before they hit SQLite. The fix is wired through the session, storage/telemetry, lifetime, and rollup-maintenance paths in `src/core/services/immersion-tracker/session.ts`, `src/core/services/immersion-tracker/storage.ts`, `src/core/services/immersion-tracker/lifetime.ts`, and `src/core/services/immersion-tracker/maintenance.ts`.
+
+Acceptance coverage is present: `bun test src/core/services/immersion-tracker-service.test.ts` passed with explicit regressions for destroy/finalize persistence, startup backfill when retained sessions exist but lifetime tables are empty, startup reconciliation of stale active sessions, `rebuildLifetimeSummaries`, and distinct-day / distinct-video lifetime semantics. `bun test src/core/services/immersion-tracker/time.test.ts src/core/services/immersion-tracker/maintenance.test.ts` also passed.
+
+Remaining action item before close: fix the two `src/main/runtime/stats-cli-command.test.ts` cleanup-lifetime assertions that currently use Bun-misparsed underscored millisecond literals (`1_710_000_000_000` evaluates to `-2147483648` under Bun 1.3.11), rerun that verification lane, then write the final summary and mark the task Done.
+<!-- SECTION:NOTES:END -->

backlog/tasks/task-262 - Fix-duplicate-AniList-post-watch-updates-for-watched-episodes.md

@@ -0,0 +1,51 @@
+---
+id: TASK-262
+title: Fix duplicate AniList post-watch updates for watched episodes
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-31 19:03'
+updated_date: '2026-03-31 19:37'
+labels:
+  - bug
+  - anilist
+dependencies: []
+ordinal: 155500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Watching an episode can currently produce two AniList activity updates for the same episode. The duplicate happens when the post-watch flow drains a queued retry for the current episode and then proceeds to run the live post-watch update for that same media/episode in the same pass. User report says this reproduces both when crossing the watched threshold naturally and when using the mark-watched keybinding. Fix the duplicate so one successful watch produces at most one AniList progress update for a given mediaKey/episode pair.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 A watched episode triggers at most one AniList post-watch progress update for a given media key and episode during a single post-watch pass, even if that episode already exists in the retry queue.
+- [x] #2 Both watched-threshold and manual mark-watched flows are protected by regression coverage for the duplicate-update case.
+- [x] #3 Relevant user-visible change note is added if required by repo policy.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Reproduce the duplicate in a unit test around `createMaybeRunAnilistPostWatchUpdateHandler` by simulating a ready retry for the same `mediaKey::episode` the live path would also submit.
+2. Fix the handler so that after processing a queued retry, it does not perform a second live update when the retry already satisfied the current attempt key.
+3. Run focused AniList runtime tests and adjacent immersion tests to confirm both threshold-driven and manual mark-watched entry points stay covered through the shared post-watch path.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added a regression in `src/main/runtime/anilist-post-watch.test.ts` for the case where `processNextAnilistRetryUpdate()` already satisfies the current `mediaKey::episode` before the live path runs.
+
+Updated `createMaybeRunAnilistPostWatchUpdateHandler` to re-check `hasAttemptedUpdateKey(attemptKey)` immediately after draining the retry queue and short-circuit before a second live AniList submission.
+
+Verification: `bun test src/main/runtime/anilist-post-watch.test.ts src/main/runtime/anilist-post-watch-main-deps.test.ts`; `bun test src/core/services/immersion-tracker-service.test.ts --test-name-pattern 'recordPlaybackPosition marks watched at 85% completion|markActiveVideoWatched'`; `bun run typecheck`; `bun run changelog:lint`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Fixed duplicate AniList post-watch submissions by short-circuiting the live update path when a ready retry item already handled the current `mediaKey::episode` in the same pass. Added a focused regression test for the retry-plus-live duplicate scenario and a changelog fragment documenting the fix.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-263 - Reuse-pre-add-duplicate-IDs-for-generic-Kiku-field-grouping.md

@@ -0,0 +1,39 @@
+---
+id: TASK-263
+title: Reuse pre-add duplicate IDs for generic Kiku field grouping
+status: Done
+assignee: []
+created_date: '2026-03-31 20:44'
+updated_date: '2026-03-31 20:48'
+labels:
+  - anki
+  - kiku
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Avoid the extra post-add duplicate lookup on the generic sentence-card creation path by capturing duplicate note IDs before add and reusing that result for Kiku field grouping. Keep Yomitan semantics aligned where practical so duplicate selection is consistent across mining paths.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Generic sentence-card creation captures duplicate note IDs before add and reuses them for Kiku field grouping instead of running the existing post-add duplicate finder
+- [x] #2 Duplicate selection remains deterministic when multiple matching notes exist
+- [x] #3 Regression tests cover the generic path duplicate reuse behavior and preserve existing non-Kiku behavior
+- [x] #4 Internal docs/config comments are updated if the behavior or operator-facing semantics changed
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+No docs update was required because this is internal duplicate-selection plumbing and does not change user-facing config surface.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Generic sentence-card creation now captures exact duplicate note IDs before add when Kiku field grouping is enabled and stores that context by created note ID. Manual field grouping reuses the tracked duplicate IDs first and deterministically picks the most recent matching note, falling back to the legacy duplicate finder only when no tracked context exists. Verified with bun test src/anki-integration/duplicate.test.ts src/anki-integration/card-creation.test.ts src/anki-integration/field-grouping.test.ts and bun run typecheck.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-263.1 - Reuse-Yomitan-popup-duplicate-IDs-in-SubMiner-bridge.md

@@ -0,0 +1,41 @@
+---
+id: TASK-263.1
+title: Reuse Yomitan popup duplicate IDs in SubMiner bridge
+status: Done
+assignee: []
+created_date: '2026-03-31 22:15'
+updated_date: '2026-03-31 22:21'
+labels:
+  - anki
+  - kiku
+  - yomitan
+dependencies: []
+parent_task_id: TASK-263
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Thread Yomitan popup/search duplicate note IDs through the existing SubMiner bridge so Kiku/manual grouping can reuse the same duplicate context that already drives the Add duplicate button. Implement and test against the vendored Yomitan copy first; do not rely on upstreamed fork changes yet.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Vendored Yomitan bridge returns duplicate note IDs for popup/search mining when available
+- [x] #2 SubMiner consumes the bridged duplicate IDs and prefers them for Kiku/manual grouping on the Yomitan mining path
+- [x] #3 Regression tests cover the popup/search bridge payload and duplicate-id reuse behavior
+- [x] #4 No commit is made for vendored Yomitan-only changes in this repo state
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Vendored files changed locally for validation only: vendor/subminer-yomitan/ext/js/display/display-anki.js, vendor/subminer-yomitan/ext/js/comm/api.js, vendor/subminer-yomitan/ext/js/comm/anki-connect.js, vendor/subminer-yomitan/ext/js/background/backend.js. Do not commit those vendor changes in this repo; port them to the fork instead.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Vendored Yomitan popup/search mining now precomputes duplicate note IDs, sends them to the SubMiner Anki proxy as private addNote metadata, and still returns note/duplicate data through the parser bridge. The proxy strips the private metadata before forwarding to upstream AnkiConnect, associates the duplicate IDs with the created note before auto-enrichment begins, and SubMiner also records the bridge result as a secondary cache path. Verified with bun test src/anki-integration/duplicate.test.ts src/anki-integration/card-creation.test.ts src/anki-integration/field-grouping.test.ts src/anki-integration/anki-connect-proxy.test.ts src/core/services/tokenizer/yomitan-parser-runtime.test.ts and bun run typecheck.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-263.2 - Keep-Yomitan-popup-responsive-during-background-add-and-pause-close-before-Kiku-modal.md

@@ -0,0 +1,43 @@
+---
+id: TASK-263.2
+title: >-
+  Keep Yomitan popup responsive during background add and pause/close before
+  Kiku modal
+status: Done
+assignee: []
+created_date: '2026-04-01 00:42'
+updated_date: '2026-04-01 02:35'
+labels:
+  - anki
+  - yomitan
+  - kiku
+  - ux
+dependencies: []
+parent_task_id: TASK-263
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Make Yomitan popup add run in background without blocking popup responsiveness. Before opening Kiku field-grouping modal, pause MPV and close the Yomitan popup/parser window if open.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Definition of Done
+<!-- DOD:BEGIN -->
+- [x] #1 Popup save path returns immediately and prevents duplicate submits
+- [x] #2 Field-grouping modal request pauses MPV and closes Yomitan popup window first
+- [x] #3 Regression tests cover async save dispatch and main-side pause/close hook
+<!-- DOD:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+2026-03-31: Removed the custom pending label/gray save-button presentation from vendored Yomitan. Background add still runs asynchronously with the internal pending-save guard, so duplicate clicks are ignored while the button keeps its stock appearance.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Yomitan popup save dispatches note creation/add in the background with an internal pending-save guard so repeated clicks are ignored without blocking the popup. Before opening the Kiku field-grouping modal, the renderer now closes the visible lookup popup and pauses MPV. Follow-up UX polish removed the custom pending label/gray styling so the save button keeps Yomitan’s stock presentation while the background action runs.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-264 - Replace-axios-with-native-fetch-across-the-project.md

@@ -0,0 +1,26 @@
+---
+id: TASK-264
+title: Replace axios with native fetch across the project
+status: To Do
+assignee: []
+created_date: '2026-04-01 00:44'
+labels: []
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Remove axios from the codebase and migrate all project HTTP requests to the platform fetch API, preserving existing request behavior and error handling where applicable.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 No production code paths import or depend on axios.
+- [ ] #2 All existing HTTP requests use fetch or a project-local abstraction built on fetch.
+- [ ] #3 Request behavior remains functionally equivalent for headers, query params, bodies, status handling, and abort/error cases that are currently supported.
+- [ ] #4 Tests are updated or added to cover the migrated request flows.
+- [ ] #5 Documentation is updated if any request semantics or setup steps change.
+- [ ] #6 axios is removed from project dependencies if it is no longer needed.
+<!-- AC:END -->

backlog/tasks/task-265 - Add-remote-backend-for-immersion-tracking-and-stats-prefer-Postgres.md

@@ -0,0 +1,53 @@
+---
+id: TASK-265
+title: Add remote backend for immersion tracking and stats (prefer Postgres)
+status: To Do
+assignee: []
+created_date: '2026-04-01 00:47'
+labels: []
+dependencies: []
+references:
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/core/services/immersion-tracker-service.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/core/services/immersion-tracker/storage.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/core/services/immersion-tracker/sqlite.ts
+  - /home/sudacode/projects/japanese/SubMiner/src/stats-daemon-runner.ts
+  - /home/sudacode/projects/japanese/SubMiner/src/core/services/stats-server.ts
+  - /home/sudacode/projects/japanese/SubMiner/src/main/boot/services.ts
+  - /home/sudacode/projects/japanese/SubMiner/package.json
+documentation:
+  - /home/sudacode/projects/japanese/SubMiner/docs/architecture/README.md
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/docs/architecture/stats-trends-data-flow.md
+  - /home/sudacode/projects/japanese/SubMiner/README.md
+  - /home/sudacode/projects/japanese/SubMiner/config.example.jsonc
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Enable immersion tracking/stats to use a remote authoritative backend so multiple devices can share the same history.
+
+Current state: `ImmersionTrackerService` opens a local `immersion.sqlite` file from the app data/config path, `stats-daemon-runner` points at that same local file, and `config.example.jsonc` only exposes `immersionTracking.dbPath` for a local path override. The stats API/dashboard reads from the same tracker service and assumes the local database is the source of truth.
+
+Goal: add a remote backend option that avoids shared filesystem/database-file syncing between devices. Do not use SSH/rsync/shared network filesystem as the primary sync strategy for live multi-device use.
+
+Backend choice: prefer Postgres if it can be integrated without a broad new dependency surface or destabilizing the current runtime; otherwise use the least invasive remote backend that can be shipped with the current stack and document the tradeoff clearly. Preserve the current local SQLite mode as the default/offline fallback if possible.
+
+This ticket should cover the full product/architecture change: configuration, storage access, stats reads, startup/error handling, migration/bootstrap from existing local data, tests, and docs.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 The app can be configured to use a remote authoritative backend for immersion tracking instead of only a local `immersion.sqlite` file.
+- [ ] #2 The chosen backend persists tracker writes and serves the existing stats read models across app restarts.
+- [ ] #3 Two devices can point at the same remote backend without relying on a shared filesystem or raw SQLite file sync.
+- [ ] #4 Local SQLite remains supported as the default or fallback mode for offline use.
+- [ ] #5 If the remote backend is unavailable or misconfigured, startup/write paths fail with actionable errors instead of silent data loss.
+- [ ] #6 A migration or bootstrap path exists to move existing local immersion data into the remote backend or seed a new device from it.
+- [ ] #7 Config/examples/docs explain the backend choice, required connection/setup details, and any security/network assumptions.
+- [ ] #8 Tests cover backend selection plus at least one representative write/read path against the remote backend.
+<!-- AC:END -->

backlog/tasks/task-266 - Preserve-paused-state-for-configured-subtitle-jump-keybindings.md

@@ -0,0 +1,34 @@
+---
+id: TASK-266
+title: Preserve paused state for configured subtitle-jump keybindings
+status: Done
+assignee: []
+created_date: '2026-04-01 03:19'
+updated_date: '2026-04-01 03:19'
+labels:
+  - renderer
+  - mpv
+  - keybindings
+  - regression
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Regression: configured overlay keybindings that forward raw mpv subtitle-jump commands (for example previous-subtitle on H) can resume playback when invoked while paused. Keyboard-driven edge jumps already preserve paused state; configured keybindings should match that behavior.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Configured subtitle-jump keybindings preserve paused playback state after backward seek
+- [x] #2 Existing keyboard-driven subtitle navigation behavior remains unchanged
+- [x] #3 Regression test covers paused configured subtitle-jump keybinding handling
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Configured overlay keybindings that forward `sub-seek` commands now re-check paused state and reapply pause after the seek when playback was already paused. This aligns raw configured subtitle-jump keybindings with the existing keyboard-driven edge-jump behavior and adds regression coverage for the paused backward-seek case.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-267 - Port-validated-Yomitan-popup-changes-to-fork-and-resync-submodule.md

@@ -0,0 +1,34 @@
+---
+id: TASK-267
+title: Port validated Yomitan popup changes to fork and resync submodule
+status: Done
+assignee: []
+created_date: '2026-04-01 03:30'
+updated_date: '2026-04-01 03:33'
+labels:
+  - yomitan
+  - submodule
+  - git
+  - integration
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Take the locally validated Yomitan popup/bridge changes from the vendored copy, apply them to the standalone `../subminer-yomitan` fork, verify the fork, push the fork commit, then reset the vendored working tree in SubMiner and update the submodule pointer to the pushed fork commit.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Standalone `../subminer-yomitan` contains the validated popup/bridge changes and passes the relevant regression test
+- [x] #2 The fork commit is pushed to its configured remote branch
+- [x] #3 SubMiner vendored Yomitan working tree is reset and the submodule pointer is updated to the pushed fork commit
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Applied the validated popup/bridge changes from the vendored Yomitan copy into `../subminer-yomitan`, added the focused async-save regression test there, installed fork deps, and verified with `npx vitest run test/display-anki-save.test.js`. Committed the fork changes as `feat: preserve async popup save state and duplicate metadata`, rebased onto the updated remote `main`, and pushed commit `69620abc` to `origin/main`. Then reset the vendored submodule working tree in SubMiner, checked it out at `69620abc`, and left the superproject with the submodule pointer updated from `3c9ee577` to `69620abc`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-268 - Address-CodeRabbit-review-action-items-for-PR-38.md

@@ -0,0 +1,44 @@
+---
+id: TASK-268
+title: 'Address CodeRabbit review action items for PR #38'
+status: Done
+assignee: []
+created_date: '2026-04-01 05:35'
+updated_date: '2026-04-01 06:07'
+labels:
+  - pr-review
+  - coderabbit
+dependencies: []
+references:
+  - 'https://github.com/ksyasuda/SubMiner/pull/38'
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Review unresolved CodeRabbit feedback on PR #38 and implement the actionable fixes without regressing duplicate grouping or popup behavior.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 All unresolved actionable CodeRabbit review comments on PR #38 are triaged and either fixed in code or explicitly identified as non-actionable or ambiguous.
+- [x] #2 Code changes preserve duplicate grouping and popup flow behavior covered by existing or added regression tests.
+- [x] #3 Relevant local verification for the affected areas passes.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+2026-04-01: Reopened for follow-up CodeRabbit round after commit 233bde58. Remaining actionable items: guard maxMatches <= 0 in duplicate exact-match helper and strengthen the duplicate tracking test fixture to prove deduplication as well as sorting.
+
+2026-04-01: Follow-up round addressed locally. Added guard for maxMatches <= 0 in duplicate exact-match scanning and strengthened the pre-add duplicate tracking test fixture to prove deduplication as well as sorting.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Addressed all unresolved actionable CodeRabbit comments on PR #38. Fixed duplicate tracking so empty duplicate lists are not persisted after sentence-card creation, sanitized Yomitan add-note noteId values to accept only positive integers, preserved paused playback for configured subtitle-seek keybindings when pause state is unknown, and short-circuited duplicate exact-match scanning for single-result lookups. Added regression tests for each case and verified with `bun test` on the affected suites plus `bun run typecheck`, `bun run test:fast`, `bun run test:env`, `bun run build`, and `bun run test:smoke:dist`.
+
+Follow-up CodeRabbit round addressed locally: `findExactDuplicateNoteIds()` now returns early when `maxMatches <= 0`, and the sentence-card duplicate tracking regression test now uses a repeated duplicate ID to assert deduplication plus sorting. Re-verified with targeted duplicate/card tests, `bun run typecheck`, and `bun run test:fast`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-270 - Make-Windows-mpv-shortcut-self-contained.md

@@ -0,0 +1,30 @@
+---
+id: TASK-270
+title: Make Windows mpv shortcut self-contained
+status: Done
+assignee: []
+created_date: '2026-04-02 07:13'
+updated_date: '2026-04-02 07:19'
+labels: []
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Remove the Windows mpv shortcut's dependency on a pre-existing mpv profile so the installer-created `SubMiner mpv` flow works out of the box without requiring the user to edit `mpv.conf`. Keep docs aligned with the new behavior and preserve the optional profile guidance for manual mpv usage.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 `SubMiner.exe --launch-mpv` launches mpv with SubMiner's required default args without requiring an mpv profile named `subminer`.
+- [x] #2 Windows shortcut/help/docs no longer describe `--launch-mpv` as depending on the SubMiner mpv profile.
+- [x] #3 Automated tests cover the Windows launch args behavior and pass after the change.
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Updated the Windows `--launch-mpv` path to pass SubMiner's default mpv args directly instead of requiring `--profile=subminer`. Adjusted Windows shortcut/help text to describe the self-contained defaults-based launch, and updated Windows docs to state that `mpv.conf` is not required for the shortcut path while preserving the optional profile guidance for manual mpv launches.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-271 - Fix-local-playback-subtitle-auto-selection-and-startup-pause-release.md

@@ -0,0 +1,56 @@
+---
+id: TASK-271
+title: Fix local playback subtitle auto-selection and startup pause release
+status: Done
+assignee:
+  - codex
+created_date: '2026-04-03 07:47'
+updated_date: '2026-04-03 08:03'
+labels:
+  - bug
+  - playback
+  - subtitles
+dependencies: []
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Investigate local-video startup on desktop playback where managed subtitle defaults can bind the wrong primary subtitle track and startup readiness retries can force playback to resume after the user manually pauses. Scope includes fixing the pause/unpause loop and making local subtitle auto-selection prefer the intended primary/secondary tracks for sentence mining sessions.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Desktop local playback no longer forces `pause=no` after the user manually pauses during or after startup readiness handling.
+- [x] #2 Managed local subtitle startup selects the expected primary track before secondary track selection for mixed-language subtitle sets like Japanese primary plus English secondary.
+- [x] #3 Regression tests cover the pause-release bug and the local subtitle auto-selection behavior.
+- [x] #4 Internal docs are updated if runtime behavior or operator expectations change.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add regression coverage for startup autoplay release so duplicate ready handling cannot unpause playback after the user manually pauses the same media.
+2. Add regression coverage for managed local subtitle startup selection using configured primary/secondary subtitle language preferences, with JA/EN remaining the default fallback behavior.
+3. Extract or add reusable subtitle track ranking logic that prefers configured primary and secondary subtitle languages, with stable scoring for external tracks and non-SDH labels.
+4. Update local playback startup/runtime wiring so managed subtitle defaults use explicit ranked selection instead of raw sid=auto / secondary-sid=auto while preserving config-driven language preference ordering.
+5. Run focused subtitle/playback tests, then update task notes/final summary with any behavior or docs impact.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented config-aware managed local subtitle selection runtime for local media path changes and playlist-browser local playback rearm, using `youtube.primarySubLanguages` for primary preference and `secondarySub.secondarySubLanguages` for secondary preference with JA/EN fallback defaults.
+
+Updated autoplay ready gate to ignore duplicate readiness signals for the same media so later manual pauses are not overridden by repeated tokenization-ready events.
+
+Updated config/template wording to document that the existing subtitle language preferences now drive managed subtitle auto-selection beyond YouTube-only flows.
+
+Verification: `bun test src/config/config.test.ts src/main/runtime/autoplay-ready-gate.test.ts src/main/runtime/local-subtitle-selection.test.ts src/main/runtime/playlist-browser-runtime.test.ts`; `bun run typecheck`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Stopped startup readiness retries from re-unpausing the same media after a later manual pause, and added config-aware managed local subtitle selection so local playback prefers the configured primary/secondary subtitle languages instead of relying on raw mpv `sid=auto` behavior. Added regression coverage for autoplay-ready gating, local subtitle selection, playlist-browser local playback rearm, and config template wording updates.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-273 - Fix-first-run-setup-false-positive-when-canonical-mpv-plugin-is-already-installed.md

@@ -0,0 +1,53 @@
+---
+id: TASK-273
+title: >-
+  Fix first-run setup false positive when canonical mpv plugin is already
+  installed
+status: Done
+assignee:
+  - Kyle Yasuda
+created_date: '2026-04-03 23:26'
+updated_date: '2026-04-04 00:31'
+labels:
+  - bug
+  - macos
+  - first-run-setup
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Investigate and fix launcher/app first-run setup gating so playback does not block when the SubMiner mpv plugin is already installed at the canonical mpv config path on macOS. Align mpv path resolution with the actual install location, keep plugin detection scoped to the canonical plugin entrypoint, and make launcher setup gating resilient to stale cancelled setup state.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 `resolveDefaultMpvInstallPaths` resolves the canonical macOS mpv config path used by existing installs.
+- [ ] #2 Playback launcher bypasses first-run setup when the canonical `scripts/subminer/main.lua` plugin entrypoint already exists, even if `setup-state.json` is stale.
+- [ ] #3 Regression tests cover canonical plugin detection and launcher handling of stale cancelled setup state.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Root cause ended up split across path resolution and launcher gating. No automated test command was executed in this pass by request.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Updated macOS mpv install path resolution to use the canonical `~/.config/mpv` location so first-run plugin detection matches the actual installed plugin path.
+
+Restricted plugin detection to the canonical `scripts/subminer/main.lua` entrypoint instead of config presence or legacy loader files.
+
+Updated the launcher setup gate to bypass stale `setup-state.json` when the mpv plugin is already installed, and to ignore an initially stale `cancelled` state after spawning setup.
+
+Added regression coverage for canonical macOS detection and launcher setup-gate bypass behavior. No automated test command was executed in this pass by request.
+<!-- SECTION:FINAL_SUMMARY:END -->
+
+## Definition of Done
+<!-- DOD:BEGIN -->
+- [ ] #1 Manual verification with scenario: existing plugin installed in custom mpv config path does not open first-run setup.
+<!-- DOD:END -->

backlog/tasks/task-274 - Stabilize-current-failing-test-regressions.md

@@ -0,0 +1,59 @@
+---
+id: TASK-274
+title: Stabilize current failing test regressions
+status: Done
+assignee:
+  - codex
+created_date: '2026-04-04 04:40'
+updated_date: '2026-04-04 05:01'
+labels: []
+dependencies: []
+documentation:
+  - docs/workflow/verification.md
+  - docs/architecture/README.md
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Investigate and fix the current src/test failures across stats CLI lifetime rebuild handling, immersion tracker lifetime rebuild idempotency, renderer test environment cleanup helpers, subtitle sidebar auto-follow behavior, and log retention pruning so the maintained test lanes pass again.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Stats CLI lifetime rebuild behavior passes the current regression coverage.
+- [x] #2 Immersion tracker lifetime rebuild backfill remains idempotent under the existing runtime test.
+- [x] #3 Renderer modal test helpers restore injected globals exactly to prior state.
+- [x] #4 Log pruning removes files older than the configured retention window deterministically.
+- [x] #5 Relevant targeted test files pass after the fixes.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Reproduce the failing specs in isolation to separate deterministic regressions from suite-order pollution.
+2. Fix source or test-helper logic for the three isolated failures: log retention cutoff, stats CLI lifetime rebuild timestamp handling, and subtitle sidebar initial jump behavior.
+3. Harden renderer modal cleanup regressions so tests verify descriptor restoration without assuming global window/document start absent.
+4. Re-run the targeted failing files, then the required verification gate for the touched areas and record results.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Targeted regressions fixed in log pruning, stats CLI lifetime logging/tests, subtitle sidebar auto-follow timing, and renderer global cleanup test isolation.
+
+Verification: `bun test src/main/runtime/stats-cli-command.test.ts src/shared/log-files.test.ts src/renderer/modals/playlist-browser.test.ts src/renderer/modals/youtube-track-picker.test.ts src/renderer/modals/subtitle-sidebar.test.ts` passed.
+
+Verification: `bun run test:src` still exits non-zero because of unrelated existing errors in `src/core/services/anilist/anilist-token-store.test.ts` (`Bun.serve is not a function`) plus one remaining non-task failure elsewhere; the originally reported regressions are green in the maintained lane.
+
+User reported `test:full` still failing after the first regression pass. Reopened to clear the remaining `test:src` fail plus the existing unhandled test errors before handoff.
+
+Verified final gate with `bun run test:launcher:unit:src` and `bun run test:full`; both pass after fixing the launcher AniSkip fallback title regression and the earlier src-lane regressions.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Stabilized the failing test regressions across source and launcher lanes. Fixed log pruning cutoff math under Bun BigInt mtimes, subtitle sidebar auto-follow timing, renderer global cleanup test isolation, stats CLI lifetime rebuild logging/tests, stats-server node:http fallback isolation, and launcher AniSkip fallback title resolution so basename titles beat generic parent directories while episode-only filenames still prefer the series directory. Verification passed with `bun test launcher/aniskip-metadata.test.ts`, `bun run test:launcher:unit:src`, and `bun run test:full`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-275 - Patch-high-severity-audit-findings-with-minimal-dependency-changes.md

@@ -0,0 +1,56 @@
+---
+id: TASK-275
+title: Patch high-severity audit findings with minimal dependency changes
+status: Done
+assignee:
+  - codex
+created_date: '2026-04-04 04:45'
+updated_date: '2026-04-04 04:50'
+labels:
+  - security
+  - dependencies
+dependencies: []
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Update SubMiner's direct Electron runtime and vulnerable build-time transitive dependencies to patched versions using the smallest safe version moves. Keep electron-builder on the current pinned line unless verification shows a blocker. Verify that bun audit no longer reports the current high-severity findings and that the standard project gate still passes.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Electron is updated to a patched supported release on the current supported line with no broader dependency refresh
+- [x] #2 Vulnerable transitive packages @xmldom/xmldom, lodash, and picomatch resolve to patched versions via targeted dependency changes
+- [x] #3 `bun audit --audit-level high` no longer reports the currently listed high-severity findings
+- [x] #4 The default handoff verification gate passes, or any failure is documented with the exact command and error output
+- [x] #5 Any dependency or lockfile changes remain minimal and do not change the pinned electron-builder line unless required
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Update package.json with the smallest set of dependency changes: bump electron from ^37.10.3 to 39.8.6 and add overrides for @xmldom/xmldom 0.8.12, lodash 4.18.0, and picomatch 4.0.4 while leaving electron-builder pinned at 26.8.2.
+2. Refresh bun.lock with a lockfile-only install/update and confirm the resolved versions for electron, @xmldom/xmldom, lodash, and picomatch.
+3. Run bun audit --audit-level high and verify the current high-severity findings are gone.
+4. Run the default verification gate: bun run typecheck, bun run test:fast, bun run test:env, bun run build, bun run test:smoke:dist.
+5. If any verification step fails, capture the exact failing command and error, assess whether it is caused by the dependency updates, and stop without broadening scope.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Updated package.json to pin electron 39.8.6 and add overrides for @xmldom/xmldom 0.8.12, lodash 4.18.0, and picomatch 4.0.4 while keeping electron-builder pinned at 26.8.2.
+
+Refreshed bun.lock with bun install and confirmed the patched versions resolved in the lockfile.
+
+Verification passed: bun audit --audit-level high, bun run typecheck, bun run test:fast, bun run test:env, bun run build, bun run test:smoke:dist.
+
+Added changelog fragment changes/patch-audit-dependencies.md for the security/dependency maintenance update. No internal docs or docs-site updates were needed because the change does not alter user-facing behavior, configuration, or workflows.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Cleared the reported high-severity audit findings with minimal dependency churn by pinning electron to 39.8.6 and overriding @xmldom/xmldom, lodash, and picomatch to patched versions. Kept electron-builder on 26.8.2. bun audit is clean and the full default handoff gate passed: typecheck, fast tests, env tests, build, and dist smoke tests.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-276 - Restore-canonical-SubMiner-Linux-app-id-metadata.md

@@ -0,0 +1,62 @@
+---
+id: TASK-276
+title: Restore canonical SubMiner Linux app-id metadata
+status: Done
+assignee:
+  - codex
+created_date: '2026-04-04 06:31'
+updated_date: '2026-04-04 06:34'
+labels:
+  - bug
+  - linux
+  - electron
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Fix the Linux/Wayland packaged app metadata so the OS-facing desktop/app-id metadata stays canonical `SubMiner` instead of the lowercase npm package name `subminer`. Add regression coverage around packaged metadata so future Electron/runtime changes do not silently reintroduce the lowercase class/app-id behavior.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Top-level package metadata provides the canonical capitalized app name used by Electron runtime bootstrap on Linux
+- [x] #2 Packaged Linux app metadata resolves to `SubMiner`/`SubMiner.desktop` instead of lowercase `subminer`
+- [x] #3 Regression coverage fails before the fix and passes after it
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a focused packaging/runtime regression test that reads the packaged app metadata source and asserts the Linux Electron bootstrap-visible fields resolve to canonical `SubMiner` / `SubMiner.desktop`.
+2. Run the targeted test first to capture the failing pre-fix state.
+3. Update top-level package metadata in `package.json` with the canonical Electron runtime-facing fields needed for Linux bootstrap.
+4. Re-run the targeted test and a lightweight packaging validation to confirm the packaged metadata now stays canonical.
+5. Record verification notes and complete the task if all acceptance criteria pass.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added a regression in `src/release-workflow.test.ts` asserting top-level `productName` and `desktopName` stay canonical for Linux Electron runtime bootstrap. Verified the new test failed before the fix because both fields were missing from top-level package metadata.
+
+Updated top-level `package.json` metadata with `productName: SubMiner` and `desktopName: SubMiner.desktop` so packaged `app.asar` exposes the canonical Linux startup identity Electron reads before app code runs.
+
+Verification passed with `bun test src/release-workflow.test.ts`, `bun run build && ./node_modules/.bin/electron-builder --linux dir --publish never`, packaged `release/linux-unpacked/resources/app.asar` inspection showing `{ name: subminer, productName: SubMiner, desktopName: SubMiner.desktop }`, and `bun run changelog:lint`.
+
+Ran the full default handoff gate after the targeted/package verification: `bun run typecheck`, `bun run test:fast`, `bun run test:env`, and `bun run test:smoke:dist` all passed.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Restored canonical Linux/Wayland app identity metadata by adding top-level Electron runtime fields to `package.json`: `productName: SubMiner` and `desktopName: SubMiner.desktop`. This fixes the packaged app metadata Electron reads before user code runs, so native Wayland compositors no longer need to derive the app-id/class from the lowercase npm package name alone.
+
+Added a regression test in `src/release-workflow.test.ts` that asserts the runtime-visible top-level metadata stays canonical. The new test was run first and failed before the fix because `productName` was missing, then passed after the metadata update.
+
+Verification: `bun test src/release-workflow.test.ts`; `bun run build && ./node_modules/.bin/electron-builder --linux dir --publish never`; inspected `release/linux-unpacked/resources/app.asar` and confirmed `productName: SubMiner` plus `desktopName: SubMiner.desktop`; `bun run changelog:lint`. Added changelog fragment `changes/2026-04-04-linux-app-id-metadata.md`.
+
+Full default handoff gate also passed: `bun run typecheck`; `bun run test:fast`; `bun run test:env`; `bun run test:smoke:dist`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-277 - Restore-Linux-shortcut-backed-modal-actions-after-Electron-39-upgrade.md

@@ -0,0 +1,58 @@
+---
+id: TASK-277
+title: Restore Linux shortcut-backed modal actions after Electron 39 upgrade
+status: Done
+assignee:
+  - codex
+created_date: '2026-04-04 06:49'
+updated_date: '2026-04-04 07:08'
+labels:
+  - bug
+  - linux
+  - electron
+  - shortcuts
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Linux builds on Electron 39 no longer open the runtime options, Jimaku, or Subsync flows from their configured shortcuts (`Ctrl/Cmd+Shift+O`, `Ctrl+Shift+J`, `Ctrl+Alt+S`). Other renderer-driven modals like session help, subtitle sidebar, and playlist browser still work, which points to the Linux `globalShortcut` / overlay shortcut path rather than modal rendering in general. Investigate the Electron 39 regression and restore these Linux shortcut-triggered actions without regressing macOS or Windows behavior.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 On Linux, the configured runtime options, Jimaku, and Subsync shortcuts trigger their existing actions again under Electron 39.
+- [x] #2 The fix is covered by automated tests around the Linux shortcut/backend behavior that regressed.
+- [x] #3 A changelog fragment is added for the Linux shortcut regression fix.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Extend the special-command / mpv IPC command path to cover Jimaku alongside the existing runtime-options and subsync commands.
+2. Add tests for IPC command dispatch and any keybinding/session-help metadata affected by the new special command.
+3. Route Linux modal-opening shortcuts through the working mpv/IPC command path instead of depending on Electron globalShortcut delivery for those actions.
+4. Re-run targeted tests, then the handoff verification gate, and update the changelog/task summary to reflect the final root cause and fix.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+User approved plan; proceeding with test-first implementation.
+
+Root cause: Linux startup unconditionally enabled Electron's GlobalShortcutsPortal path, so Electron 39 X11 sessions were routed through the portal-backed globalShortcut path even though that path should only be used for Wayland-style launches. The affected runtime-options, Jimaku, and Subsync actions all depend on that shortcut path, while renderer-driven modals did not regress.
+
+User retested after the portal gating fix; issue persists. Updating investigation scope from portal selection alone to Linux overlay shortcut delivery/registration under Electron 39.
+
+Revised fix path: Linux renderer now matches configured overlay shortcuts for runtime options, subsync, and Jimaku locally, then dispatches the existing mpv/IPC special-command route instead of depending on Electron globalShortcut delivery.
+
+Added Jimaku mpv special command plumbing through IPC/runtime deps and exposed an overlay-runtime helper for opening the Jimaku modal from that IPC path.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Restored Linux shortcut-backed modal actions by routing runtime options, Subsync, and Jimaku through the working mpv/IPC special-command path. Added renderer-side Linux shortcut matching for configured overlay shortcuts, threaded a new Jimaku special command through IPC/runtime deps, refreshed configured shortcuts on hot reload, and covered the regression with IPC/runtime keyboard tests. Verification: bun test src/core/services/ipc-command.test.ts src/renderer/handlers/keyboard.test.ts src/main/runtime/ipc-mpv-command-main-deps.test.ts; bun run typecheck; bun run test:fast; bun run test:env; bun run build; bun run test:smoke:dist.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-278 - Prepare-patch-release-0.11.1.md

@@ -0,0 +1,67 @@
+---
+id: TASK-278
+title: Prepare patch release 0.11.1
+status: Done
+assignee:
+  - '@codex'
+created_date: '2026-04-04 07:16'
+updated_date: '2026-04-04 07:41'
+labels:
+  - release
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Bump SubMiner from 0.11.0 to 0.11.1, run the local release checklist, and confirm whether the branch is ready for tagging/publishing.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 package.json is bumped to 0.11.1 without overwriting unrelated local metadata edits.
+- [x] #2 Release prep checks are run and summarized, including changelog/build verification and local build/test gates.
+- [x] #3 Any remaining release blockers are called out explicitly.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Generate release metadata with `bun run changelog:build --version 0.11.1 --date 2026-04-04`.
+2. Review the resulting `CHANGELOG.md` and `release/release-notes.md` content for the 0.11.1 section.
+3. Rerun the documented local release gate: `bun run changelog:check --version 0.11.1`, `bun run verify:config-example`, `bun run typecheck`, `bun run test:fast`, `bun run test:env`, and `bun run build`.
+4. Record results, remaining blockers, and ready-for-tagging status in the task notes/final summary.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Bumped package.json from 0.11.0 to 0.11.1 while preserving the existing local productName/desktopName edits.
+
+Fixed the Linux shortcut changelog fragment metadata so changelog lint now passes and the previously failing CI cause is addressed locally.
+
+Release checks run: bun run changelog:lint, bun run changelog:check --version 0.11.1, bun run verify:config-example, bun run typecheck, bun run test:fast, bun run test:env, bun run build. All passed except changelog:check, which is expected until pending fragments are built into CHANGELOG.md/release/release-notes.md.
+
+Current release blocker: pending changelog fragments /changes/2026-04-04-linux-app-id-metadata.md and /changes/2026-04-04-linux-shortcut-portal-regression.md still need bun run changelog:build --version 0.11.1 --date 2026-04-04 before tagging.
+
+Reopened to complete the remaining release-prep work: generate changelog/release notes artifacts, rerun the documented release gate, and confirm ready-for-tagging status.
+
+Completed the remaining release-prep step with `bun run changelog:build --version 0.11.1 --date 2026-04-04`, which prepended `CHANGELOG.md`, generated `release/release-notes.md`, and removed the two pending `changes/*.md` fragments.
+
+Reran the release gate after changelog generation: `bun run changelog:check --version 0.11.1`, `bun run verify:config-example`, `bun run typecheck`, `bun run test:fast`, `bun run test:env`, and `bun run build`; all passed.
+
+Extra confidence checks also passed: `bun run changelog:lint`, `bun run test:smoke:dist`, and `gh run list --workflow CI --limit 5` shows the two latest `main` CI runs succeeded on 2026-04-04 after the earlier pre-fix failure.
+
+`release/release-notes.md` is intentionally generated under the gitignored `release/` directory, so readiness evidence in git status is `CHANGELOG.md` plus deletion of the released change fragments.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Finished the 0.11.1 release prep by generating the changelog artifacts from the pending Linux fix fragments and re-running the full documented local release gate. `CHANGELOG.md` now contains the `v0.11.1 (2026-04-04)` section, `release/release-notes.md` was regenerated in the ignored `release/` directory, and the released `changes/2026-04-04-linux-app-id-metadata.md` plus `changes/2026-04-04-linux-shortcut-portal-regression.md` fragments were removed.
+
+Verification results: `bun run changelog:check --version 0.11.1`, `bun run verify:config-example`, `bun run typecheck`, `bun run test:fast`, `bun run test:env`, `bun run build`, `bun run changelog:lint`, and `bun run test:smoke:dist` all passed locally. Remote CI also looks green for the latest release-prep head: `gh run list --workflow CI --limit 5` showed successful `main` runs for `chore: prep 0.11.1 release` and `Change demo image link to GitHub asset` on 2026-04-04, with the earlier `fix: restore linux modal shortcuts` failure already superseded by later green runs.
+
+Remaining manual release step: commit the generated release-prep changes if desired, tag `v0.11.1`, and push the commit plus tag when ready.
+<!-- SECTION:FINAL_SUMMARY:END -->

bun.lock

@@ -18,7 +18,7 @@
       "devDependencies": {
         "@types/node": "^25.3.0",
         "@types/ws": "^8.18.1",
-        "electron": "^37.10.3",
+        "electron": "39.8.6",
         "electron-builder": "26.8.2",
         "esbuild": "^0.25.12",
         "prettier": "^3.8.1",
@@ -27,9 +27,12 @@
     },
   },
   "overrides": {
+    "@xmldom/xmldom": "0.8.12",
     "app-builder-lib": "26.8.2",
     "electron-builder-squirrel-windows": "26.8.2",
+    "lodash": "4.18.0",
     "minimatch": "10.2.3",
+    "picomatch": "4.0.4",
     "tar": "7.5.11",
   },
   "packages": {
@@ -185,7 +188,7 @@
 
     "@xhayper/discord-rpc": ["@xhayper/discord-rpc@1.3.3", "", { "dependencies": { "@discordjs/rest": "^2.6.1", "@vladfrangu/async_event_emitter": "^2.4.7", "discord-api-types": "^0.38.42", "ws": "^8.20.0" } }, "sha512-Ih48GHiua7TtZgKO+f0uZPhCeQqb84fY2qUys/oMh8UbUfiUkUJLVCmd/v2AK0/pV33euh0aqSXo7+9LiPSwGw=="],
 
-    "@xmldom/xmldom": ["@xmldom/xmldom@0.8.11", "", {}, "sha512-cQzWCtO6C8TQiYl1ruKNn2U6Ao4o4WBBcbL61yJl84x+j5sOWWFU9X7DpND8XZG3daDppSsigMdfAIl2upQBRw=="],
+    "@xmldom/xmldom": ["@xmldom/xmldom@0.8.12", "", {}, "sha512-9k/gHF6n/pAi/9tqr3m3aqkuiNosYTurLLUtc7xQ9sxB/wm7WPygCv8GYa6mS0fLJEHhqMC1ATYhz++U/lRHqg=="],
 
     "abbrev": ["abbrev@3.0.1", "", {}, "sha512-AO2ac6pjRB3SJmGJo+v5/aK6Omggp6fsLrs6wN9bd35ulu4cCwaAU9+7ZhXjeqHVkaHThLuzH0nZr0YpCDhygg=="],
 
@@ -321,7 +324,7 @@
 
     "ejs": ["ejs@3.1.10", "", { "dependencies": { "jake": "^10.8.5" }, "bin": { "ejs": "bin/cli.js" } }, "sha512-UeJmFfOrAQS8OJWPZ4qtgHyWExa088/MtK5UEyoJGFH67cDEXkZSviOiKRCZ4Xij0zxI3JECgYs3oKx+AizQBA=="],
 
-    "electron": ["electron@37.10.3", "", { "dependencies": { "@electron/get": "^2.0.0", "@types/node": "^22.7.7", "extract-zip": "^2.0.1" }, "bin": { "electron": "cli.js" } }, "sha512-3IjCGSjQmH50IbW2PFveaTzK+KwcFX9PEhE7KXb9v5IT8cLAiryAN7qezm/XzODhDRlLu0xKG1j8xWBtZ/bx/g=="],
+    "electron": ["electron@39.8.6", "", { "dependencies": { "@electron/get": "^2.0.0", "@types/node": "^22.7.7", "extract-zip": "^2.0.1" }, "bin": { "electron": "cli.js" } }, "sha512-uWX6Jh5LmwL13VwOSKBjebI+ck+03GOwc8V2Sgbmr9pJVJ/cHfli/PkjXuRDr+hq+SLHQuT9mGHSIfScebApRA=="],
 
     "electron-builder": ["electron-builder@26.8.2", "", { "dependencies": { "app-builder-lib": "26.8.2", "builder-util": "26.8.1", "builder-util-runtime": "9.5.1", "chalk": "^4.1.2", "ci-info": "^4.2.0", "dmg-builder": "26.8.2", "fs-extra": "^10.1.0", "lazy-val": "^1.0.5", "simple-update-notifier": "2.0.0", "yargs": "^17.6.2" }, "bin": { "electron-builder": "cli.js", "install-app-deps": "install-app-deps.js" } }, "sha512-ieiiXPdgH3qrG6lcvy2mtnI5iEmAopmLuVRMSJ5j40weU0tgpNx0OAk9J5X5nnO0j9+KIkxHzwFZVUDk1U3aGw=="],
 
@@ -479,7 +482,7 @@
 
     "libsql": ["libsql@0.5.28", "", { "dependencies": { "@neon-rs/load": "^0.0.4", "detect-libc": "2.0.2" }, "optionalDependencies": { "@libsql/darwin-arm64": "0.5.28", "@libsql/darwin-x64": "0.5.28", "@libsql/linux-arm-gnueabihf": "0.5.28", "@libsql/linux-arm-musleabihf": "0.5.28", "@libsql/linux-arm64-gnu": "0.5.28", "@libsql/linux-arm64-musl": "0.5.28", "@libsql/linux-x64-gnu": "0.5.28", "@libsql/linux-x64-musl": "0.5.28", "@libsql/win32-x64-msvc": "0.5.28" }, "os": [ "linux", "win32", "darwin", ], "cpu": [ "arm", "x64", "arm64", ] }, "sha512-wKqx9FgtPcKHdPfR/Kfm0gejsnbuf8zV+ESPmltFvsq5uXwdeN9fsWn611DmqrdXj1e94NkARcMA2f1syiAqOg=="],
 
-    "lodash": ["lodash@4.17.23", "", {}, "sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w=="],
+    "lodash": ["lodash@4.18.0", "", {}, "sha512-l1mfj2atMqndAHI3ls7XqPxEjV2J9ZkcNyHpoZA3r2T1LLwDB69jgkMWh71YKwhBbK0G2f4WSn05ahmQXVxupA=="],
 
     "log-symbols": ["log-symbols@4.1.0", "", { "dependencies": { "chalk": "^4.1.0", "is-unicode-supported": "^0.1.0" } }, "sha512-8XPvpAA8uyhfteu8pIvQxpJZ7SYYdpUivZpGy6sFsBuKRY/7rQGavedeB8aK+Zkyq6upMFVL/9AW6vOYzfRyLg=="],
 
@@ -569,7 +572,7 @@
 
     "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
 
-    "picomatch": ["picomatch@4.0.3", "", {}, "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q=="],
+    "picomatch": ["picomatch@4.0.4", "", {}, "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A=="],
 
     "plist": ["plist@3.1.0", "", { "dependencies": { "@xmldom/xmldom": "^0.8.8", "base64-js": "^1.5.1", "xmlbuilder": "^15.1.1" } }, "sha512-uysumyrvkUX0rX/dEVqt8gC3sTBzd4zoWfLeS29nb53imdaXVvLINYXTI2GNqzaMuvacNx4uJQ8+b3zXR0pkgQ=="],
 

changes/251-docs-site-sidebar.md

@@ -1,6 +0,0 @@
-type: docs
-area: docs-site
-
-- Added a dedicated Subtitle Sidebar guide and linked it from the homepage and configuration docs.
-- Linked Jimaku integration from the homepage to its dedicated docs page.
-- Refreshed docs-site theme tokens and hover/selection styling for the updated pages.

changes/252-youtube-playback-socket-path.md

@@ -1,5 +0,0 @@
-type: fixed
-area: main
-
-- Resolve the YouTube playback socket path lazily so startup honors CLI and config overrides.
-- Add regression coverage for the lazy socket-path lookup during Windows mpv startup.

changes/253-aur-release-best-effort.md

@@ -1,5 +0,0 @@
-type: internal
-area: release
-
-- Retried AUR clone and push operations in the tagged release workflow.
-- Kept GitHub Releases green when AUR publish flakes and needs manual follow-up.

changes/259-texthooker-integrated-startup.md

@@ -1,5 +0,0 @@
-type: fixed
-area: main
-
-- Keep integrated `--start --texthooker` launches on the full app-ready startup path so the texthooker page and websocket servers start together during normal playback startup.
-- Stop the mpv/plugin auto-start flow from spawning a separate standalone texthooker helper during normal `subminer <video>` launches.

changes/260-playlist-browser.md

@@ -1,5 +0,0 @@
-type: added
-area: overlay
-
-- Added a playlist browser overlay modal for browsing sibling video files and the live mpv queue during playback.
-- Added the default `Ctrl+Alt+P` keybinding to open the playlist browser and manage queue order without leaving playback.

changes/261-macos-overlay-passthrough.md

@@ -1,5 +0,0 @@
-type: fixed
-area: overlay
-
-- Keep tracked macOS visible overlays click-through by default so subtitle sidebar passthrough works immediately without requiring a subtitle hover cycle first.
-- Add regression coverage for the macOS visible-overlay passthrough default.