feat(subtitles): optimize anime stream audio extraction

- Prefer matching audio and lower-resolution sources with HLS sampling
- Reuse verified audio within sessions and clean temporary files on shutdown
- Allow character dictionary sync without loaded subtitles

.agents/skills/subminer-change-verification/SKILL.md

@@ -27,7 +27,6 @@ Do not use hidden wrapper commands. Verification commands are owned by `package.
 - Launcher or mpv plugin: `bun run test:launcher` or `bun run test:env`, based on the behavior changed
 - Runtime compatibility or dist-sensitive wiring: `bun run test:runtime:compat`
 - Stats dashboard: `bun run test:stats`
-- Overlay, renderer, mpv, or mining behavior in the running app: `bun run build`, then `bun run test:e2e`
 - Build/release scripts: `bun run test:scripts`
 
 For substantial changes, use the full gate documented in `AGENTS.md` and `docs/workflow/verification.md`.

.github/workflows/ci.yml

@@ -9,83 +9,3 @@ on:
 jobs:
   build-test-audit:
     uses: ./.github/workflows/quality-gate.yml
-
-  # Boots the built app with a real mpv on each platform. Kept outside the
-  # reusable quality gate so releases do not depend on it while the lane is new.
-  e2e:
-    name: E2E (${{ matrix.os }})
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 30
-    permissions:
-      contents: read
-    defaults:
-      run:
-        shell: bash
-    env:
-      SUBMINER_E2E_KEEP: '1'
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-          persist-credentials: false
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Point temp files at an uploadable directory
-        run: |
-          # os.tmpdir() follows these, so the kept session logs land under runner.temp.
-          dir="$RUNNER_TEMP/e2e"
-          mkdir -p "$dir"
-          { echo "TMPDIR=$dir"; echo "TEMP=$dir"; echo "TMP=$dir"; } >> "$GITHUB_ENV"
-
-      - name: Install mpv and ffmpeg (Linux)
-        if: runner.os == 'Linux'
-        run: |
-          # Only Ubuntu sources are needed; unrelated runner repositories can be unavailable.
-          apt_sources=(-o Dir::Etc::sourcelist=sources.list.d/ubuntu.sources -o Dir::Etc::sourceparts=-)
-          sudo apt-get "${apt_sources[@]}" update
-          sudo apt-get "${apt_sources[@]}" install -y mpv ffmpeg xvfb
-
-      - name: Install mpv and ffmpeg (macOS)
-        if: runner.os == 'macOS'
-        run: brew install mpv ffmpeg
-
-      - name: Install mpv and ffmpeg (Windows)
-        if: runner.os == 'Windows'
-        run: |
-          choco install mpv ffmpeg -y --no-progress
-          # The mpv package adds no shim, so put its directory on PATH for later steps.
-          mpv_exe="$(find /c/ProgramData/chocolatey/lib /c/ProgramData/chocolatey/bin "/c/Program Files" /c/tools -maxdepth 6 -iname mpv.exe 2>/dev/null | head -n 1)"
-          test -n "$mpv_exe"
-          cygpath -w "$(dirname "$mpv_exe")" >> "$GITHUB_PATH"
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Build
-        run: bun run build
-
-      - name: End-to-end suite
-        run: bun run test:e2e
-
-      - name: Dictionary backend windows (Linux)
-        if: runner.os == 'Linux'
-        run: xvfb-run -a bun run test:dictionary:electron
-
-      - name: Upload session logs (on failure)
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: e2e-logs-${{ matrix.os }}
-          path: ${{ runner.temp }}/e2e/subminer-e2e-*/*.log
-          if-no-files-found: ignore

.github/workflows/docs-pages.yml

@@ -2,11 +2,6 @@ name: Docs Pages
 
 on:
   workflow_dispatch:
-    inputs:
-      rebuild_archives:
-        description: 'Stable tags to rebuild in R2 (comma-separated, or "all"); archives are otherwise built once'
-        required: false
-        default: ''
   push:
     branches:
       - main
@@ -15,8 +10,6 @@ on:
     paths:
       - 'docs-site/**'
       - 'scripts/docs-versioning.ts'
-      - 'scripts/docs-versioned-assets.ts'
-      - 'scripts/docs-archive-store.ts'
       - 'scripts/build-versioned-docs.ts'
       - '.github/workflows/docs-pages.yml'
       - 'package.json'
@@ -61,21 +54,20 @@ jobs:
           bun install --frozen-lockfile
           cd docs-site && bun install --frozen-lockfile
 
+      - name: Cache versioned docs archives
+        if: steps.tag_guard.outputs.stable_tag != 'false'
+        uses: actions/cache@v4
+        with:
+          path: .tmp/docs-versioned-archive-cache
+          key: docs-versioned-archives-${{ runner.os }}-${{ hashFiles('docs-site/.vitepress/**', 'docs-site/public/assets/fonts/**', 'docs-site/package.json', 'docs-site/bun.lock', 'scripts/build-versioned-docs.ts', 'scripts/docs-versioning.ts') }}
+
       - name: Test docs
         if: steps.tag_guard.outputs.stable_tag != 'false'
         run: bun run docs:test
 
-      # Builds only archives missing from R2 (plus any requested rebuilds), then the
-      # root and /main/ builds that make up the Pages deployment.
       - name: Build versioned docs
         if: steps.tag_guard.outputs.stable_tag != 'false'
-        env:
-          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          DOCS_ARCHIVE_R2_ACCESS_KEY_ID: ${{ secrets.DOCS_ARCHIVE_R2_ACCESS_KEY_ID }}
-          DOCS_ARCHIVE_R2_SECRET_ACCESS_KEY: ${{ secrets.DOCS_ARCHIVE_R2_SECRET_ACCESS_KEY }}
-          DOCS_ARCHIVE_R2_BUCKET: ${{ vars.DOCS_ARCHIVE_R2_BUCKET }}
-          REBUILD_ARCHIVES: ${{ inputs.rebuild_archives }}
-        run: bun run scripts/build-versioned-docs.ts --require-archives "--rebuild-archives=${REBUILD_ARCHIVES}"
+        run: bun run docs:build:versioned
 
       - name: Deploy docs to Cloudflare Pages
         if: steps.tag_guard.outputs.stable_tag != 'false'
@@ -83,6 +75,4 @@ jobs:
         with:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          # Run from docs-site so Wrangler bundles docs-site/functions (the /v/* archive server).
-          workingDirectory: docs-site
-          command: pages deploy ../.tmp/docs-versioned-site --project-name "${{ vars.CLOUDFLARE_PAGES_PROJECT_NAME }}" --branch main
+          command: pages deploy .tmp/docs-versioned-site --project-name "${{ vars.CLOUDFLARE_PAGES_PROJECT_NAME }}" --branch main

.github/workflows/package-release.yml

@@ -59,6 +59,17 @@ jobs:
           bun install --frozen-lockfile
           bun run build
 
+      - name: Download previous package size reports
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          mkdir -p .tmp/package-baseline
+          previous=$(gh api "repos/$GITHUB_REPOSITORY/releases" --jq '[.[] | select(.draft == false and .tag_name != env.GITHUB_REF_NAME)] | sort_by(.published_at) | last | .tag_name // empty')
+          if [ -n "$previous" ]; then
+            gh release download "$previous" --pattern 'package-size-*.json' --dir .tmp/package-baseline || echo 'Previous release has no package size reports; size comparison will be skipped.'
+          fi
+
       - name: Build AppImage
         run: bun run build:appimage
         env:
@@ -87,6 +98,7 @@ jobs:
             release/*.AppImage
             release/latest*.yml
             release/*.blockmap
+            release/package-size-*.json
           if-no-files-found: error
 
   build-macos:
@@ -147,6 +159,17 @@ jobs:
           bun install --frozen-lockfile
           bun run build
 
+      - name: Download previous package size reports
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          mkdir -p .tmp/package-baseline
+          previous=$(gh api "repos/$GITHUB_REPOSITORY/releases" --jq '[.[] | select(.draft == false and .tag_name != env.GITHUB_REF_NAME)] | sort_by(.published_at) | last | .tag_name // empty')
+          if [ -n "$previous" ]; then
+            gh release download "$previous" --pattern 'package-size-*.json' --dir .tmp/package-baseline || echo 'Previous release has no package size reports; size comparison will be skipped.'
+          fi
+
       - name: Build signed + notarized macOS artifacts
         run: bun run build:mac
         env:
@@ -170,6 +193,7 @@ jobs:
             release/*.zip
             release/latest*.yml
             release/*.blockmap
+            release/package-size-*.json
           if-no-files-found: error
 
   build-windows:
@@ -211,6 +235,17 @@ jobs:
           bun install --frozen-lockfile
           bun run build
 
+      - name: Download previous package size reports
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          mkdir -p .tmp/package-baseline
+          previous=$(gh api "repos/$GITHUB_REPOSITORY/releases" --jq '[.[] | select(.draft == false and .tag_name != env.GITHUB_REF_NAME)] | sort_by(.published_at) | last | .tag_name // empty')
+          if [ -n "$previous" ]; then
+            gh release download "$previous" --pattern 'package-size-*.json' --dir .tmp/package-baseline || echo 'Previous release has no package size reports; size comparison will be skipped.'
+          fi
+
       - name: Verify managed Windows launcher
         run: bun test src/main/runtime/managed-launcher.test.ts
 
@@ -235,4 +270,5 @@ jobs:
             release/*.zip
             release/latest*.yml
             release/*.blockmap
+            release/package-size-*.json
           if-no-files-found: error

.github/workflows/prerelease.yml

@@ -105,6 +105,7 @@ jobs:
         run: |
           shopt -s nullglob
           files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz release/latest*.yml release/*.blockmap dist/launcher/subminer dist/launcher/subminer.cmd)
+          files+=(release/package-size-*.json)
           if [ "${#files[@]}" -eq 0 ]; then
             echo "No release artifacts found for checksum generation."
             exit 1
@@ -151,6 +152,7 @@ jobs:
             release/latest*.yml
             release/*.blockmap
             release/SHA256SUMS.txt
+            release/package-size-*.json
             dist/launcher/subminer
             dist/launcher/subminer.cmd
           )

.github/workflows/quality-gate.yml

@@ -29,9 +29,6 @@ jobs:
       - name: Verify Windows launcher bootstrap
         run: bun test src/main/runtime/windows-launcher-bootstrap.test.ts
 
-      - name: Verify native mpv process launch
-        run: bun test src/main/runtime/mpv-process.test.ts
-
       - name: Verify POSIX launcher bootstrap
         run: bun test src/main/runtime/posix-launcher-bootstrap.test.ts
 

.github/workflows/release.yml

@@ -106,6 +106,7 @@ jobs:
         run: |
           shopt -s nullglob
           files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz release/latest*.yml release/*.blockmap dist/launcher/subminer dist/launcher/subminer.cmd)
+          files+=(release/package-size-*.json)
           if [ "${#files[@]}" -eq 0 ]; then
             echo "No release artifacts found for checksum generation."
             exit 1
@@ -170,6 +171,7 @@ jobs:
             release/latest*.yml
             release/*.blockmap
             release/SHA256SUMS.txt
+            release/package-size-*.json
             dist/launcher/subminer
             dist/launcher/subminer.cmd
           )
@@ -253,31 +255,22 @@ jobs:
           echo "skip=true" >> "$GITHUB_OUTPUT"
 
       - name: Download release assets for AUR
-        id: aur_assets
         if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
         env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
           set -euo pipefail
           version="$RELEASE_VERSION"
           install -dm755 .tmp/aur-release-assets
-          for asset in "SubMiner-${version#v}.AppImage" subminer subminer-assets.tar.gz; do
-            destination=".tmp/aur-release-assets/$asset"
-            if ! curl --fail --silent --show-error --location \
-              --retry 3 --retry-delay 1 --retry-all-errors \
-              --connect-timeout 30 --max-time 600 \
-              --output "$destination.partial" \
-              "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/releases/download/$version/$asset"; then
-              echo "::warning::Unable to download $asset after retries; skipping automated AUR publish."
-              echo "skip=true" >> "$GITHUB_OUTPUT"
-              exit 0
-            fi
-            mv "$destination.partial" "$destination"
-          done
-          echo "skip=false" >> "$GITHUB_OUTPUT"
+          gh release download "$version" \
+            --dir .tmp/aur-release-assets \
+            --pattern "SubMiner-${version#v}.AppImage" \
+            --pattern "subminer" \
+            --pattern "subminer-assets.tar.gz"
 
       - name: Update AUR packaging metadata
-        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true' && steps.aur_assets.outputs.skip != 'true'
+        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
         env:
           RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
@@ -294,7 +287,7 @@ jobs:
             --assets ".tmp/aur-release-assets/subminer-assets.tar.gz"
 
       - name: Commit and push AUR update
-        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true' && steps.aur_assets.outputs.skip != 'true'
+        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
         working-directory: aur-subminer-bin
         env:
           GIT_SSH_COMMAND: ssh -i ~/.ssh/aur -o IdentitiesOnly=yes

.gitignore

@@ -20,8 +20,6 @@ coverage/
 /main-entry.js
 /main-entry.js.map
 
-/build/hachidori/
-
 # Logs
 *.log
 npm-debug.log*

.gitmodules

@@ -8,7 +8,3 @@
 [submodule "vendor/subminer-yomitan"]
 	path = vendor/subminer-yomitan
 	url = https://github.com/ksyasuda/subminer-yomitan
-[submodule "vendor/hachidori"]
-	path = vendor/hachidori
-	url = https://github.com/ksyasuda/hachidori.git
-	branch = subminer

AGENTS.md

@@ -8,7 +8,6 @@ Start here, then leave this file.
 - Architecture map: [`docs/architecture/README.md`](./docs/architecture/README.md)
 - Workflow map: [`docs/workflow/README.md`](./docs/workflow/README.md)
 - Verification lanes: [`docs/workflow/verification.md`](./docs/workflow/verification.md)
-- Testing guidelines: [`docs/workflow/testing.md`](./docs/workflow/testing.md)
 - Knowledge-base rules: [`docs/knowledge-base/README.md`](./docs/knowledge-base/README.md)
 - Release guide: [`docs/RELEASING.md`](./docs/RELEASING.md)
 
@@ -45,11 +44,10 @@ Start here, then leave this file.
 - 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`
-- Overlay / renderer / mpv / mining behavior in the running app: `bun run build`, then `bun run test:e2e` (headless, sandboxed; `bun run e2e start` for exploratory checks)
 - Build/release scripts (`scripts/**`): `bun run test:scripts`
 - Internal docs, `AGENTS.md`, or repo skills: `bun run test:docs:kb`
 - User-facing `docs-site/`: `bun run docs:test`, then `bun run docs:build`
-- macOS mpv window helper (`scripts/get-mpv-window-macos.swift`): compile it on macOS with `bun run build`
+- macOS mpv window helper: `bun test scripts/get-mpv-window-macos.test.ts`
 - Test lanes are directory-discovered via `scripts/test-lanes.ts`; never hand-list test files in `package.json`
 
 ## Docs Upkeep

CHANGELOG.md

@@ -1,176 +1,5 @@
 # Changelog
 
-## v0.20.1 (2026-10-03)
-
-### Added
-- **YouTube Browser Window**:
-  - Browse YouTube with your login kept across restarts. Open it with `subminer youtube`, `subminer yt`, or tray **Browse YouTube**.
-  - Clicking a video plays it in mpv. Middle-click, Shift/Ctrl-click, or the right-click menu adds it to mpv's playlist.
-  - Queued videos get the same Japanese subtitle setup, and the rest of the queue is kept on Windows.
-  - Closing the window quits a SubMiner started by `subminer youtube`.
-- **Whisper Subtitles for YouTube**:
-  - Set `youtube.subtitleSource` to `whisper` to transcribe YouTube videos with Whisper instead of using YouTube's captions.
-  - The video stays paused while Whisper transcribes, and the subtitle generation modal shows progress.
-  - The subtitle generation modal (`Ctrl+Shift+G`) now works on YouTube videos, including Windows stream playback.
-- **Scroll Wheel and Mouse Bindings**: `keybindings` now accepts scroll wheel keys, and the settings key editor can capture them. Mouse button and wheel bindings from mpv now work while the cursor is over the overlay, including on Hyprland.
-- **Run Commands from Session Help**: During playback, press `Enter` or double-click a row in session help to run that command.
-
-### Changed
-- **Release Assets**: Releases no longer include package-size reports.
-
-### Fixed
-- **Hyprland Overlay**: The overlay stays clickable after mpv goes fullscreen with `mpv.backend: x11`, and it no longer interrupts mpv while mpv enters fullscreen.
-- **mpv Key Bindings**: Bindings from mpv such as `9`/`0` for volume now work while the overlay has focus, even if the overlay loaded before mpv connected.
-- **Jellyfin**:
-  - The Japanese subtitle track is selected as soon as it downloads, without waiting for the other tracks.
-  - Japanese and English tracks are auto-selected on episodes whose embedded subtitles are images.
-  - Timing review previews and mined card audio use the audio track you are playing.
-- **Media Timing Review**: Trim handles are now thin lines on the clip edges, and original subtitle boundaries no longer cover the waveform. The preview cursor no longer stutters on macOS with Bluetooth headphones.
-- **YouTube Subtitles**: Japanese subtitles no longer fail with "HTTP 429" on videos where YouTube also lists a machine-translated Japanese track.
-- **Stats**:
-  - Mined cards are counted once in session and lifetime stats.
-  - Word and kanji dates and the new-words charts stay accurate after deleting sessions. Existing data is repaired in the background.
-  - Overview totals, charts, and the activity calendar refresh after deleting sessions.
-- **Yomitan Data Safety**: Electron is updated to 43.7.7. SubMiner now refuses to load your Yomitan data with an unsupported or downgraded runtime. Automatic character dictionary changes stop if Yomitan suddenly reports no dictionaries.
-- **AppImage in Sandboxes**: The AppImage now opens its window when launched in a sandbox such as `firejail --appimage`.
-- **Ctrl+C Crash**: SubMiner no longer crashes with "write EPIPE" when the terminal command that started it is stopped with Ctrl+C.
-
-### Docs
-- **Docs Site**: The docs site is shorter and easier to scan, with a key and default table for each config block. Outdated pages were corrected, and the MeCab install command for Arch Linux is fixed.
-- **Stats Docs**: The docs now cover the Overview refresh after deleting sessions and how discovery dates are kept after old sessions are pruned.
-
-<details>
-<summary>Internal changes</summary>
-
-### Internal
-- **Release Notes**: Release notes and `CHANGELOG.md` are now generated as short items per feature or area.
-- **Dev Profile**: Development launches use a separate `SubMiner-dev` profile unless production-profile access is requested.
-- **Dependencies**: undici is updated to 7.29.1 to clear the security advisories that were blocking CI.
-- **Package Checks**: CI no longer compares package sizes. Package content checks still run.
-
-</details>
-
-## v0.20.0 (2026-09-23)
-
-### Added
-- **Japanese Subtitle Generation**:
-  - Generate Japanese SRT subtitles locally with whisper.cpp. Start it from a new modal (Ctrl+Shift+G), from the generate button in an empty subtitle sidebar, or with `subminer generate-subs`.
-  - Generation shows progress, can be cancelled, and loads the finished subtitles into mpv automatically.
-  - Pick an official multilingual Whisper model, including quantized variants, with size and accuracy guidance. You can download it in the app or point Settings at a model you already have.
-  - `large-v3-turbo` is recommended when CUDA support is detected, and `small` otherwise.
-  - whisper-cli, ffmpeg, and ffprobe are found on PATH unless you override them. SubMiner names any missing tools before a download starts.
-  - An optional "Focus on spoken dialogue" mode uses a separately downloaded Silero VAD model. It keeps audible sections it is unsure about, so dialogue under music is not dropped, but songs may also be transcribed.
-  - Long passages are split near speech starts or quiet pauses to reduce subtitles that appear too early. When an eligible embedded or external subtitle track is loaded in mpv, it guides the split points.
-  - Each passage runs in a fresh Whisper process, which prevents repeated-character output.
-- **Subtitle Selection Modal**:
-  - An optional modal for choosing primary and secondary mpv subtitle tracks.
-  - Turn it on in Settings under Behavior, then press g followed by s to open it. Turning it off restores mpv's own subtitle selection binding.
-  - Single-key actions take priority over configured key sequence prefixes.
-  - Conflicting sequences are disabled with a warning, and the existing y commands stay reserved.
-- **Subtitle Sidebar Copy**:
-  - Select dialogue across several sidebar rows and copy it without timestamps using Ctrl/Cmd+C or the Copy button.
-  - Selecting text does not seek playback and does not require mining a card.
-- **Media Timing Review Screenshot Picker**:
-  - Choose the still screenshot separately from the audio range, with a live preview and its own time slider.
-  - Step through decoded frames one at a time to get the exact frame you want.
-  - Works with local video and with seekable remote streams such as Jellyfin.
-- **mpv Keybindings in the Overlay**:
-  - The overlay now picks up keyboard bindings from mpv defaults, `input.conf`, and loaded scripts when they do not conflict with SubMiner.
-  - SubMiner controls and bindings you explicitly disabled take precedence.
-  - These bindings apply only to the current session and are not listed in the help menu.
-- **Jimaku Live Action Search**: The Jimaku modal has new Anime and Live action tabs, so you can search Jimaku's live action catalogue as well as anime. Use Arrow Left and Arrow Right to switch tabs.
-- **TMDB Live-Action Library**:
-  - Live-action dramas and movies in the stats Library now get posters, synopses, and titles from TMDB.
-  - Release builds include a project key. Setting `tmdb.apiKey` or `tmdb.apiKeyCommand` overrides it, and one of them is required when running from source.
-  - Titles that AniList cannot match are looked up on TMDB automatically when the parsed filename exactly matches a Japanese live-action title. For everything else, use the new **Link to TMDB** action.
-  - Entries linked to the same TMDB title merge into one card, and the Library kind selector has a new Live Action option.
-  - If a replacement download fails during provider reassignment, the previous link and artwork are kept. Merges and sync keep AniList and TMDB identities separate, and the merge dialog explains mixed selections instead of failing.
-- **YouTube Library Kind**:
-  - YouTube channels are now their own Library media kind. Existing channel entries migrate automatically, and viewing history and manual video assignments are unchanged.
-  - New All Titles, Anime, and YouTube Library filters.
-  - Channels are excluded from AniList matching, season repair, and duplicate recommendations.
-  - Merges and video moves can no longer combine an anime entry with a YouTube channel.
-
-### Changed
-- **Launcher Uses Bundled Bun**:
-  - Every installed and downloadable launcher now runs on the Bun runtime that ships with SubMiner. A system Bun is no longer needed.
-  - Recognized legacy launchers migrate automatically.
-  - Windows gets a `subminer.cmd` launcher download.
-  - First-run setup is reduced to one optional launcher control. Runtime repair guidance appears only when it is needed.
-- **Faster Sync Transfers**:
-  - Sync between compatible macOS and Linux machines now uses compressed, incremental rsync transfers.
-  - The last snapshot received from each peer is cached, which reduces traffic on later syncs.
-  - Machines without a compatible rsync, including Windows, fall back to compressed scp.
-  - Older peers still work without the upload cache.
-  - Transfers abort after 30 minutes.
-- **Stats Server Request Safety**:
-  - The stats server now accepts loopback hosts only and rejects requests from browser origins other than its own.
-  - Requests that change data must send an `application/json` body. Scripts that POST to the server need to set a JSON content type.
-  - The in-app stats overlay now loads from the local server, so it gets the same protection.
-  - Dashboards served through a reverse proxy or Tailscale Serve are no longer supported.
-- **Smaller Downloads**:
-  - Installers and unpacked apps are smaller. Demo media, source maps, TypeScript sources, test fixtures, and unused Koffi binaries are no longer packaged.
-  - All windows now share one Japanese UI font.
-  - Release builds publish package size reports that compare against the previous release.
-- **Bundled Yomitan**: Updated with upstream Yomitan 26.9.8 changes, including historical Japanese kana transformations, Ukrainian language support, and improvements to Anki duplicate searches and audio retrieval.
-
-### Fixed
-- **Jellyfin 12 Compatibility**:
-  - Playback, subtitle, artwork, and remote-control requests now authenticate with the `ApiKey` query parameter, so the integration works on Jellyfin 12, where legacy authorization is off by default.
-  - "Play on SubMiner" stays available. The cast connection now answers keep-alive requests and reconnects when the server stops responding, instead of silently dying after about a minute.
-  - The Jellyfin "now playing" bar clears when you close or finish a cast video instead of running on to the end of the episode.
-  - Cards mined during Jellyfin playback get the episode title in the misc info field again instead of "Unknown media".
-- **Jellyfin Privacy and Playback**:
-  - Jellyfin streams no longer leak titles taken from the stream URL, or stream URLs that contain credentials, into metadata lookups, Anki source fields, Discord presence, stats, or AniList retries.
-  - Previously cached metadata that contained credentials is cleaned up. Watch history and library assignments are not touched.
-  - Jellyfin playback and casting now use your configured mpv executable, so they work when mpv is installed outside PATH. Portable plugins next to that executable are detected.
-- **Anki Mining**:
-  - New `ankiConnect.fields.wordAudio` setting reads word audio separately from the sentence audio field. This fixes animated images that started moving immediately when `fields.audio` pointed to `SentenceAudio`. Existing animated images need to be regenerated to pick up the fix.
-  - Sentence furigana on word cards stays in sync with the full stats-search context and with expanded timing review selections. Stale readings are cleared if regeneration fails.
-  - Closing the overlay while media timing review is still loading now cancels the review, resumes playback if the review paused it, and cleans up the hidden preview player.
-  - `ankiConnect.media.maxMediaDuration: 0` now means unlimited when mining from the stats dashboard, matching overlay mining.
-  - Invalid AnkiConnect, Kiku, and Senren settings are now rejected with a warning and fall back to defaults.
-- **Stats Server Stability**:
-  - A port conflict is now reported in a status notification instead of crashing SubMiner.
-  - Simultaneous startup requests share one server start. Stopping the background server no longer disconnects dashboards open in the foreground.
-  - Shutdown waits only a limited time for active requests to finish.
-  - Malformed resource IDs, and ID lists with any invalid entries, are rejected before Library changes or cover backfills run.
-- **Subtitle Sidebar**:
-  - Clicking a cue no longer leaves the row focused, and Space no longer seeks back to a focused cue. Enter still seeks to the focused cue, and Space keeps its configured playback action.
-  - The sidebar stays near the current playback position during gaps when the subtitle file has a cue that starts at zero.
-- **Settings Save Feedback**:
-  - Settings marked LIVE no longer show false restart warnings, including for notifications and subtitle generation.
-  - When a save mixes live and restart-only changes, the live changes apply right away and only the changed sections that need a restart are listed.
-- **Overlay Windows**:
-  - On Hyprland, recovery dialogs stay above SubMiner windows so overlay placement updates no longer cover their Wait and Close buttons.
-  - On Linux, a delayed close callback during teardown can no longer reopen the overlay.
-- **First Launch on macOS**: SubMiner no longer exits on first launch when the config directory does not exist yet.
-
-### Docs
-- **Launcher**: Documented the launcher install that uses the bundled runtime, migration from legacy launchers, package-managed updates, and the bundled Bun runtime's MIT and LGPL notices. The AUR package installs these notices under `/usr/share/licenses/subminer-bin`, and they are also included in `subminer-assets.tar.gz`.
-- **Subtitle Generation**: Documented model choice, VAD behavior, splitting guided by a reference track, fallback behavior, and known limits.
-- **Subtitle Selection**: Documented the subtitle selector setting, its shortcut override, and the primary and secondary track controls.
-- **Settings**: Clarified save feedback for live settings, warnings for saves that mix live and restart-only changes, and how subtitle generation settings reload.
-- **Jellyfin**:
-  - Clarified that Windows mpv playback and Jellyfin casting can use a configured executable path instead of PATH.
-  - Documented how Jellyfin media titles and stats identities keep stream credentials out of metadata.
-- **Stats Library**:
-  - Documented TMDB linking, provider reassignment, merge compatibility, and caching of the credential command's output.
-  - Documented YouTube channel filtering and video statistics in the Library.
-- **Mining**:
-  - Documented choosing the screenshot separately in media timing review.
-  - Documented the separate word audio field mapping, including that existing animated images need to be regenerated.
-- **Sync**: Documented compressed transfers, where the incremental sync cache is stored, and compatibility with older peers.
-
-<details>
-<summary>Internal changes</summary>
-
-### Internal
-- Removed duplicate source and launcher smoke runs from the reusable CI quality gate. Every distinct test lane and failure artifact is kept.
-- Replaced mislabeled dist source reruns with a small Electron-runtime smoke check. It covers compiled stats startup, the HTTP service, native SQLite, port conflicts, and cleanup.
-
-</details>
-
 ## v0.19.6 (2026-09-04)
 
 ### Added

README.md

@@ -4,7 +4,7 @@
 
 # SubMiner
 
-Look up words with Yomitan or Hachidori, mine them to Anki, and track your immersion without leaving mpv
+Integrates Yomitan and mpv - on-screen lookups, mine to Anki, and track immersion without leaving the player
 
 [Installation](#quick-start) · [Requirements](#requirements) · [Usage](https://docs.subminer.moe/usage) · [Documentation](https://docs.subminer.moe)
 
@@ -23,9 +23,7 @@ Look up words with Yomitan or Hachidori, mine them to Anki, and track your immer
 
 ### Dictionary Lookups
 
-Hover over any word in the subtitles to open the full Yomitan popup with definitions, pitch accent, and frequency data. SubMiner bundles its own Yomitan, separate from any browser install.
-
-Yomitan remains the default. Select the bundled Hachidori backend with `dictionaryBackend: "hachidori"` and restart SubMiner. The tray opens the selected backend's settings. See [dictionary setup](https://docs.subminer.moe/usage#hachidori-setup) for importing dictionaries, linking an external Hachidori host, and configuring Anki.
+Hover over any word and trigger a lookup to get the full Yomitan popup - definitions, pitch accent, and frequency data - without ever leaving mpv.
 
 <div align="center">
   <img src="docs-site/public/screenshots/yomitan-lookup.png" width="800" alt="Yomitan dictionary popup over annotated subtitles in mpv">
@@ -35,7 +33,7 @@ Yomitan remains the default. Select the bundled Hachidori backend with `dictiona
 
 ### Instant Anki Mining
 
-Create an Anki card from the exact playback moment with one key press, click, or controller input. SubMiner fills in the sentence, an audio clip, and a screenshot or animated image.
+Create an Anki card with the sentence, audio clip, screenshot, and machine translation from the exact playback moment with one key press, click, or controller input.
 
 <div align="center">
   <img src="docs-site/public/screenshots/one-key-mining.png" width="800" alt="Anki card created from SubMiner with sentence, audio, and screenshot">
@@ -45,7 +43,7 @@ Create an Anki card from the exact playback moment with one key press, click, or
 
 ### Reading Annotations
 
-Subtitles are annotated as they play with frequency highlighting, JLPT tags, N+1 targeting, and character names from a generated dictionary. Particles and grammar-only tokens stay plain so the words worth learning stand out.
+Real-time subtitle annotations with frequency highlighting, JLPT tags, N+1 targeting, and a character name dictionary. Grammar-only tokens and particles render as plain text so you focus on what matters.
 
 <div align="center">
   <img src="docs-site/public/screenshots/annotations.png" width="800" alt="Annotated subtitles with frequency coloring, JLPT underlines, and N+1 targets">
@@ -55,7 +53,7 @@ Subtitles are annotated as they play with frequency highlighting, JLPT tags, N+1
 
 ### Immersion Dashboard
 
-A stats dashboard tracks watch time, vocabulary growth, mining throughput, session history, and trends. Everything stays on your machine, with no third-party tracking.
+Local stats dashboard tracking watch time, vocabulary growth, mining throughput, session history, and trends. All stored locally, no third-party tracking.
 
 <div align="center">
   <img src="docs-site/public/screenshots/stats-overview.png" width="800" alt="Stats dashboard showing watch time, cards mined, streaks, and tracking data">
@@ -63,12 +61,22 @@ A stats dashboard tracks watch time, vocabulary growth, mining throughput, sessi
 
 <br>
 
+### Playlist Browser
+
+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.
+
+<div align="center">
+  <img src="docs-site/public/screenshots/playlist-browser.png" width="800" alt="Playlist browser modal showing sibling episode files beside the active mpv queue">
+</div>
+
+<br>
+
 ### Integrations
 
 <table>
   <tr>
     <td><b>YouTube</b></td>
-    <td>Play YouTube URLs with subtitle tracks picked by your language priorities, or choose tracks yourself in the overlay picker (<code>Ctrl+Alt+C</code>). Requires <code>yt-dlp</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>
@@ -76,19 +84,23 @@ A stats dashboard tracks watch time, vocabulary growth, mining throughput, sessi
   </tr>
   <tr>
     <td><b>Jellyfin</b></td>
-    <td>Browse your Jellyfin library, or cast to SubMiner from any Jellyfin client. Setup and discovery live in the tray menu</td>
+    <td>Browse, launch, and cast media from your Jellyfin server with setup and discovery controls in the app tray</td>
+  </tr>
+  <tr>
+    <td><b>Anime Browser</b></td>
+    <td>Search anime sources you supply as <a href="https://github.com/aniyomiorg/aniyomi">Aniyomi</a> extension APKs and play an episode in mpv with the overlay attached (<code>subminer anime</code>); SubMiner ships no repositories and bundles no sources</td>
   </tr>
   <tr>
     <td><b>Jimaku</b></td>
-    <td>Search and download Japanese subtitles. Requires a free Jimaku API key</td>
+    <td>Search and download Japanese subtitles</td>
+  </tr>
+  <tr>
+    <td><b>Japanese Subtitle Generation</b></td>
+    <td>Generate Japanese subtitles from local files or finite anime streams in a standalone modal (<code>Ctrl+Shift+G</code>) or the sidebar button. The launcher supports local files. Transcription runs locally with whisper.cpp and FFmpeg, with progress and optional managed model downloads. Stream subtitles are saved in the application cache. Optional Silero speech detection prioritizes dialogue in separately timed passages. <a href="https://docs.subminer.moe/main/subtitle-generation">Setup guide</a></td>
   </tr>
   <tr>
     <td><b>TsukiHime</b></td>
-    <td>Search and download subtitles extracted from anime releases, with Japanese and secondary-language tabs (<code>Ctrl+Shift+T</code>). Requires <code>xz</code> on your <code>PATH</code></td>
-  </tr>
-  <tr>
-    <td><b>Subtitle generation</b></td>
-    <td>Transcribe a video's audio into Japanese subtitles locally from the generation modal (<code>Ctrl+Shift+G</code>), the subtitle sidebar, or the launcher. SubMiner can download models for you; optional Silero speech detection helps focus on dialogue. Requires whisper.cpp and FFmpeg. <a href="https://docs.subminer.moe/subtitle-generation">Setup guide</a></td>
+    <td>Search and download subtitles extracted from anime releases, with Japanese and secondary-language tabs (<code>Ctrl+Shift+T</code>) — no API key, requires <code>xz</code> on your <code>PATH</code></td>
   </tr>
   <tr>
     <td><b>AniSkip</b></td>
@@ -96,7 +108,7 @@ A stats dashboard tracks watch time, vocabulary growth, mining throughput, sessi
   </tr>
   <tr>
     <td><b>alass / ffsubsync</b></td>
-    <td>Retime a subtitle against the audio or another subtitle track (<code>Ctrl+Alt+S</code>). Requires <code>alass</code> or <code>ffsubsync</code>; set <code>subsync.alass_path</code> or <code>subsync.ffsubsync_path</code> if they are not in <code>/usr/bin</code></td>
+    <td>Manual subtitle retiming — requires <code>alass</code> or <code>ffsubsync</code> on your <code>PATH</code> (optional; subtitle syncing is disabled without them)</td>
   </tr>
   <tr>
     <td><b>WebSocket</b></td>
@@ -104,29 +116,29 @@ A stats dashboard tracks watch time, vocabulary growth, mining throughput, sessi
   </tr>
 </table>
 
+<div align="center">
+  <img src="docs-site/public/screenshots/texthooker.png" width="800" alt="Texthooker page receiving annotated subtitle lines via WebSocket">
+</div>
+
 <br>
 
 ---
 
 ## Requirements
 
-SubMiner runs on Linux, macOS 11+, and Windows 10+. Only **mpv** is required to run it (plus `fuse2` for the Linux AppImage). Mining cards also needs Anki with the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) add-on. Everything else is optional.
+Only **mpv** is required to run SubMiner. Anki + AnkiConnect are required to mine cards, which is the point of the app, but everything else is optional.
 
-| Dependency               | Status           | What it does                                                         |
-| ------------------------ | ---------------- | -------------------------------------------------------------------- |
-| mpv                      | Required         | The video player SubMiner draws over                                 |
-| fuse2                    | Required (Linux) | Running the AppImage                                                 |
-| Anki + AnkiConnect       | Required to mine | Card creation from the Yomitan popup                                 |
-| ffmpeg                   | Recommended      | Audio clips and screenshots on cards                                 |
-| MeCab + mecab-ipadic     | Recommended      | More accurate N+1, JLPT, and frequency highlighting                  |
-| xdotool + xwininfo       | Required (X11)   | Window tracking on desktops other than Hyprland or Sway              |
-| yt-dlp                   | Optional         | YouTube playback                                                     |
-| xz                       | Optional         | TsukiHime subtitle downloads (most Linux distros already have it)    |
-| alass / ffsubsync        | Optional         | Subtitle sync                                                        |
-| whisper.cpp              | Optional         | [Subtitle generation](https://docs.subminer.moe/subtitle-generation) |
-| guessit                  | Optional         | Better title, season, and episode detection for AniSkip and AniList  |
-| fzf / rofi               | Optional         | Video picker in the `subminer` launcher (rofi is Linux only)         |
-| chafa, ffmpegthumbnailer | Optional         | Thumbnail previews in the launcher pickers                           |
+| Dependency           | Status           | What it does                                             |
+| -------------------- | ---------------- | -------------------------------------------------------- |
+| mpv                  | Required         | The video player SubMiner overlays on                    |
+| Anki + AnkiConnect   | Required to mine | Card creation from the Yomitan popup                     |
+| ffmpeg               | Recommended      | Audio clips & screenshots for Anki cards                 |
+| MeCab + mecab-ipadic | Recommended      | More precise annotations and filtering                   |
+| yt-dlp               | Optional         | YouTube playback                                         |
+| xz                   | Optional         | TsukiHime subtitle downloads (not on Windows by default) |
+| alass / ffsubsync    | Optional         | Subtitle sync                                            |
+| guessit              | Optional         | Better anime title and episode detection                 |
+| fzf / rofi           | Optional         | Video picker in the `subminer` launcher (Linux/macOS)    |
 
 <details>
 <summary><b>Platform-specific install commands</b></summary>
@@ -134,12 +146,9 @@ SubMiner runs on Linux, macOS 11+, and Windows 10+. Only **mpv** is required to
 **Arch Linux:**
 
 ```bash
-sudo pacman -S --needed mpv ffmpeg
-paru -S --needed mecab-git mecab-ipadic   # MeCab is only in the AUR
+sudo pacman -S --needed mpv ffmpeg mecab mecab-ipadic
 ```
 
-On desktops other than Hyprland or Sway, also install `xdotool` and `xorg-xwininfo`.
-
 **macOS:**
 
 ```bash
@@ -153,16 +162,16 @@ winget install shinchiro.mpv
 winget install Gyan.FFmpeg
 ```
 
-Then reopen your terminal and check `mpv --version` and `ffmpeg -version`. ffmpeg must be on `PATH`; mpv does not have to be. If `mpv` is not found, either add its folder (usually `%LOCALAPPDATA%\Programs\mpv`) to `PATH` or enter the full path to `mpv.exe` during first-run setup.
+Then reopen your terminal and check `mpv --version` and `ffmpeg -version`. winget puts `ffmpeg` on `PATH` automatically; mpv uses a regular installer that may not, so if `mpv` is not found, either add its folder (usually `%LOCALAPPDATA%\Programs\mpv`) to `PATH` or set `mpv.executablePath` during first-run setup.
 
-[Scoop](https://scoop.sh) is the alternative if you want one package manager for everything. It is the only one that also carries `xz`:
+[Scoop](https://scoop.sh) is the alternative if you want one package manager for everything, since it is the only one that also carries `xz`:
 
 ```powershell
 scoop bucket add extras
 scoop install extras/mpv main/ffmpeg main/yt-dlp main/xz
 ```
 
-See the [installation guide](https://docs.subminer.moe/installation#_1-install-requirements) for Ubuntu, Debian, and Fedora commands and the full optional package lists.
+See the [full requirements list](https://docs.subminer.moe/installation#_1-install-requirements) for optional dependencies.
 
 </details>
 
@@ -177,10 +186,10 @@ See the [installation guide](https://docs.subminer.moe/installation#_1-install-r
 
 ```bash
 paru -S subminer-bin
+# optional: the anime browser bridge, shared with Mangatan and updated by pacman
+paru -S mangatan-extension-server
 ```
 
-Includes the AppImage and the `subminer` command.
-
 </details>
 
 <details>
@@ -192,7 +201,14 @@ wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppI
  && chmod +x ~/.local/bin/SubMiner.AppImage
 ```
 
-The AppImage is all you need. First-run setup can install the optional `subminer` command, which runs on a copy of Bun bundled with the app, so you do not need Bun installed.
+The AppImage is all you need. First-run setup can install the optional `subminer` command-line launcher. Every current launcher uses Bun included with the app, so you do not need Bun installed or on `PATH`.
+
+You can also download the launcher wrapper directly:
+
+```bash
+wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer \
+ && chmod +x ~/.local/bin/subminer
+```
 
 </details>
 
@@ -201,14 +217,14 @@ The AppImage is all you need. First-run setup can install the optional `subminer
 
 Download the latest DMG from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest) and drag `SubMiner.app` into `/Applications`.
 
-Then enable SubMiner under **System Settings > Privacy & Security > Accessibility**, or the overlay cannot follow the mpv window. If macOS blocks the first launch, right-click the app and choose **Open**.
-
 </details>
 
 <details>
 <summary><b>Windows</b></summary>
 
-Download and run the latest installer (`SubMiner-<version>.exe`) from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). A portable `.zip` is also available.
+Download and run the latest installer (`.exe`) from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest).
+
+For terminal use, download `subminer.cmd`. It locates the installed app and uses its private Bun runtime.
 
 </details>
 
@@ -221,30 +237,28 @@ See the [build-from-source guide](https://docs.subminer.moe/installation#from-so
 
 ### 2. Launch & Set Up
 
-Start SubMiner and the setup window opens on first launch. It creates your config file, imports Yomitan dictionaries (you need at least one for lookups), and can install the `subminer` command. On Windows it also creates a **SubMiner mpv** shortcut.
+Run the installed app and the first-run setup wizard will guide you through importing Yomitan dictionaries and optionally installing the `subminer` command-line launcher. Setup records a custom app location when needed, and the wrapper runs with the app's private Bun runtime.
 
 ```bash
-subminer app --setup                     # AUR
-~/.local/bin/SubMiner.AppImage --setup   # AppImage
+# Linux
+~/.local/bin/SubMiner.AppImage --setup
+
+# macOS
+open -a SubMiner --args --setup
 ```
 
-On **macOS**, open `SubMiner.app` from `/Applications`. On **Windows**, run SubMiner from the Start menu. To reopen setup later, run `subminer app --setup`.
-
-For card creation, keep Anki open with AnkiConnect installed. SubMiner connects to it at its default address with no extra setup.
+On **Windows**, just run `SubMiner.exe` and the setup will open automatically on first launch.
 
 ### 3. Mine
 
 ```bash
-subminer video.mkv          # play a video with SubMiner
+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                 # watch history: replay, next, or previous episode
-subminer doctor             # check your setup
+subminer -H                 # browse history, then previous / replay / next / select / quit
 ```
 
-On **Windows**, double-click the **SubMiner mpv** shortcut or drag a video file onto it.
-
-Starting mpv some other way? See [Launching mpv yourself](https://docs.subminer.moe/installation#launching-mpv-yourself) for the IPC socket option the overlay needs.
+On **Windows**, use the **SubMiner mpv** shortcut created during setup. Double-click it or drag a video file onto it.
 
 ## Documentation
 
@@ -256,23 +270,40 @@ Full guides on configuration, Anki setup, Jellyfin, immersion tracking, and more
 
 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                                 |
-| [Bun](https://github.com/oven-sh/bun)                                                       | Bundled runtime for the `subminer` command-line launcher                |
-| [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner)                          | Inspiration for Electron overlay with Yomitan integration               |
-| [jellyfin-mpv-shim](https://github.com/jellyfin/jellyfin-mpv-shim)                          | Jellyfin integration                                                    |
-| [Jimaku.cc](https://jimaku.cc)                                                              | Japanese subtitle search and downloads                                  |
-| [Renji's Texthooker Page](https://github.com/Renji-XD/texthooker-ui)                        | Base for the WebSocket texthooker integration                           |
-| [Yomitan](https://github.com/yomidevs/yomitan)                                              | Default dictionary engine and morphological parser                     |
-| [Hachidori](https://github.com/bee-san/hachidori)                                           | Alternative dictionary backend, powered by HoshiDicts                   |
-| [yomitan-jlpt-vocab](https://github.com/stephenmk/yomitan-jlpt-vocab)                       | JLPT level tags for vocabulary                                          |
+| 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                                          |
+| [Aniyomi](https://github.com/aniyomiorg/aniyomi)                                            | Anime extension API and data model the anime browser targets                 |
+| [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                                      |
+| [Bun](https://github.com/oven-sh/bun)                                                       | Bundled runtime for the `subminer` command-line launcher                     |
+| [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner)                          | Inspiration for Electron overlay with Yomitan integration                    |
+| [jellyfin-mpv-shim](https://github.com/jellyfin/jellyfin-mpv-shim)                          | Jellyfin integration                                                         |
+| [Jimaku.cc](https://jimaku.cc)                                                              | Japanese subtitle search and downloads                                       |
+| [M-Extension-Server](https://github.com/1Selxo/M-Extension-Server)                          | Runs Aniyomi extension APKs off Android; the bridge the anime browser drives |
+| [Mangatan](https://github.com/1Selxo/Mangatan)                                              | Reference client for the bridge protocol the anime browser speaks            |
+| [Renji's Texthooker Page](https://github.com/Renji-XD/texthooker-ui)                        | Base for the WebSocket texthooker integration                                |
+| [Yomitan](https://github.com/yomidevs/yomitan)                                              | Dictionary engine powering all lookups and the morphological parser          |
+| [yomitan-jlpt-vocab](https://github.com/stephenmk/yomitan-jlpt-vocab)                       | JLPT level tags for vocabulary                                               |
+
+## Disclaimer
+
+SubMiner is a media player and language-learning tool. The project does not
+host, supply, or link to anime, video streams, or subtitle libraries. The anime
+browser runs Aniyomi extensions that you install yourself from repositories you
+choose; SubMiner bundles none and recommends none. The SubMiner developers are
+not affiliated with any content provider and have no control over what those
+sources offer, whether they stay available, or the quality of what they serve.
 
 ## License
 
-SubMiner is released under the [GNU General Public License v3.0](LICENSE).
+[GNU General Public License v3.0](LICENSE)
+
+The anime browser drives [M-Extension-Server](https://github.com/1Selxo/M-Extension-Server),
+downloaded from its upstream releases at runtime rather than
+bundled or redistributed here; its bundles carry their own dependencies, including a JRE and
+GPL-3.0 NewPipe Extractor. SubMiner includes none of them and talks to the bridge
+over its own HTTP protocol. It ships no extensions or repositories by default.
 
 Release packages also bundle an unmodified copy of [Bun](https://github.com/oven-sh/bun), which is MIT licensed and statically links JavaScriptCore (LGPL 2.0) and TinyCC (LGPL 2.1). Its license texts and third-party notices ship inside the app under `resources/bun/licenses`, and each release publishes `bun-v1.3.5-source.tar.gz` with the corresponding source. See [Bundled Bun runtime](https://docs.subminer.moe/installation#bundled-bun-runtime).

bun.lock

@@ -5,8 +5,10 @@
     "": {
       "name": "subminer",
       "dependencies": {
+        "@fontsource-variable/geist": "^5.2.8",
+        "@fontsource-variable/geist-mono": "^5.2.7",
         "@xhayper/discord-rpc": "^1.3.4",
-        "axios": "^1.20.0",
+        "axios": "^1.18.1",
         "commander": "^14.0.3",
         "electron-updater": "^6.8.9",
         "hono": "^4.12.28",
@@ -19,12 +21,13 @@
         "@electron/asar": "3.4.1",
         "@types/node": "^24.10.0",
         "@types/ws": "^8.18.1",
-        "electron": "43.7.7",
-        "electron-builder": "26.16.1",
+        "electron": "42.6.0",
+        "electron-builder": "26.15.3",
         "esbuild": "^0.25.12",
+        "eslint": "^10.8.0",
         "prettier": "^3.8.1",
         "typescript": "^5.9.3",
-        "undici": "7.29.1",
+        "undici": "7.29.0",
       },
     },
   },
@@ -33,10 +36,10 @@
   },
   "overrides": {
     "@xmldom/xmldom": "0.8.15",
-    "app-builder-lib": "26.16.1",
-    "brace-expansion": "5.0.11",
-    "electron-builder-squirrel-windows": "26.16.1",
-    "fast-uri": "3.1.7",
+    "app-builder-lib": "26.15.3",
+    "brace-expansion": "5.0.9",
+    "electron-builder-squirrel-windows": "26.15.3",
+    "fast-uri": "3.1.6",
     "form-data": "4.0.6",
     "ip-address": "10.2.0",
     "js-yaml": "4.3.2",
@@ -45,7 +48,7 @@
     "picomatch": "4.0.4",
     "tar": "7.5.21",
     "tmp": "0.2.7",
-    "undici": "7.29.1",
+    "undici": "7.29.0",
   },
   "packages": {
     "@discordjs/collection": ["@discordjs/collection@2.1.1", "", {}, "sha512-LiSusze9Tc7qF03sLCujF5iZp7K+vRNEDBZ86FT9aQAv3vxMLihUvKvpsCWiQ2DJq1tVckopKm1rxomgNUc9hg=="],
@@ -124,6 +127,34 @@
 
     "@esbuild/win32-x64": ["@esbuild/win32-x64@0.25.12", "", { "os": "win32", "cpu": "x64" }, "sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA=="],
 
+    "@eslint-community/eslint-utils": ["@eslint-community/eslint-utils@4.9.1", "", { "dependencies": { "eslint-visitor-keys": "^3.4.3" }, "peerDependencies": { "eslint": "^6.0.0 || ^7.0.0 || >=8.0.0" } }, "sha512-phrYmNiYppR7znFEdqgfWHXR6NCkZEK7hwWDHZUjit/2/U0r6XvkDl0SYnoM51Hq7FhCGdLDT6zxCCOY1hexsQ=="],
+
+    "@eslint-community/regexpp": ["@eslint-community/regexpp@4.12.2", "", {}, "sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew=="],
+
+    "@eslint/config-array": ["@eslint/config-array@0.23.5", "", { "dependencies": { "@eslint/object-schema": "^3.0.5", "debug": "^4.3.1", "minimatch": "^10.2.4" } }, "sha512-Y3kKLvC1dvTOT+oGlqNQ1XLqK6D1HU2YXPc52NmAlJZbMMWDzGYXMiPRJ8TYD39muD/OTjlZmNJ4ib7dvSrMBA=="],
+
+    "@eslint/config-helpers": ["@eslint/config-helpers@0.7.0", "", { "dependencies": { "@eslint/core": "^1.2.1" } }, "sha512-DObd/KKUsU+FaFv4PLxSRenpXfQWmPXXP3pPZ6/K1PCrMu2vQpMDMuQe/BqYeoLcz8ro0bVDF1RxOJgfVEdhUw=="],
+
+    "@eslint/core": ["@eslint/core@1.2.1", "", { "dependencies": { "@types/json-schema": "^7.0.15" } }, "sha512-MwcE1P+AZ4C6DWlpin/OmOA54mmIZ/+xZuJiQd4SyB29oAJjN30UW9wkKNptW2ctp4cEsvhlLY/CsQ1uoHDloQ=="],
+
+    "@eslint/object-schema": ["@eslint/object-schema@3.0.5", "", {}, "sha512-vqTaUEgxzm+YDSdElad6PiRoX4t8VGDjCtt05zn4nU810UIx/uNEV7/lZJ6KwFThKZOzOxzXy48da+No7HZaMw=="],
+
+    "@eslint/plugin-kit": ["@eslint/plugin-kit@0.7.2", "", { "dependencies": { "@eslint/core": "^1.2.1", "levn": "^0.4.1" } }, "sha512-+CNAzxglkrpNf/kKywqQfk74QjtceuOE7Qm+AF8miRvPF/wmmK5+OJOgVh3AVTT3RP2mH3+FOaxlE5v72owk0A=="],
+
+    "@fontsource-variable/geist": ["@fontsource-variable/geist@5.2.8", "", {}, "sha512-cJ6m9e+8MQ5dCYJsLylfZrgBh6KkG4bOLckB35Tr9J/EqdkEM6QllH5PxqP1dhTvFup+HtMRPuz9xOjxXJggxw=="],
+
+    "@fontsource-variable/geist-mono": ["@fontsource-variable/geist-mono@5.2.7", "", {}, "sha512-ZKlZ5sjtalb2TwXKs400mAGDlt/+2ENLNySPx0wTz3bP3mWARCsUW+rpxzZc7e05d2qGch70pItt3K4qttbIYA=="],
+
+    "@humanfs/core": ["@humanfs/core@0.19.2", "", { "dependencies": { "@humanfs/types": "^0.15.0" } }, "sha512-UhXNm+CFMWcbChXywFwkmhqjs3PRCmcSa/hfBgLIb7oQ5HNb1wS0icWsGtSAUNgefHeI+eBrA8I1fxmbHsGdvA=="],
+
+    "@humanfs/node": ["@humanfs/node@0.16.8", "", { "dependencies": { "@humanfs/core": "^0.19.2", "@humanfs/types": "^0.15.0", "@humanwhocodes/retry": "^0.4.0" } }, "sha512-gE1eQNZ3R++kTzFUpdGlpmy8kDZD/MLyHqDwqjkVQI0JMdI1D51sy1H958PNXYkM2rAac7e5/CnIKZrHtPh3BQ=="],
+
+    "@humanfs/types": ["@humanfs/types@0.15.0", "", {}, "sha512-ZZ1w0aoQkwuUuC7Yf+7sdeaNfqQiiLcSRbfI08oAxqLtpXQr9AIVX7Ay7HLDuiLYAaFPu8oBYNq/QIi9URHJ3Q=="],
+
+    "@humanwhocodes/module-importer": ["@humanwhocodes/module-importer@1.0.1", "", {}, "sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA=="],
+
+    "@humanwhocodes/retry": ["@humanwhocodes/retry@0.4.3", "", {}, "sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ=="],
+
     "@isaacs/fs-minipass": ["@isaacs/fs-minipass@4.0.1", "", { "dependencies": { "minipass": "^7.0.4" } }, "sha512-wgm9Ehl2jpeqP3zw/7mo3kRHFp5MEDhqAdwy1fTGkHAwnkGOVsgpvQhL8B5n1qlb01jV3n/bI0ZfZp5lWA1k4w=="],
 
     "@libsql/darwin-arm64": ["@libsql/darwin-arm64@0.5.28", "", { "os": "darwin", "cpu": "arm64" }, "sha512-Lc/b8JXO2W2+H+5UXfw7PCHZCim1jlrB0CmLPsjfVmihMluBpdYafFImhjAHxHlWGfuZ32WzjVPUap5fGmkthw=="],
@@ -150,7 +181,7 @@
 
     "@neon-rs/load": ["@neon-rs/load@0.0.4", "", {}, "sha512-kTPhdZyTQxB+2wpiRcFWrDcejc4JI6tkPuS7UZCG4l6Zvc5kU/gGQ/ozvHTh1XR5tS+UlfAfGuPajjzQjCiHCw=="],
 
-    "@noble/hashes": ["@noble/hashes@1.8.0", "", {}, "sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A=="],
+    "@noble/hashes": ["@noble/hashes@2.2.0", "", {}, "sha512-IYqDGiTXab6FniAgnSdZwgWbomxpy9FtYvLKs7wCUs2a8RkITG+DFGO1DM9cr+E3/RgADRpFjrKVaJ1z6sjtEg=="],
 
     "@peculiar/asn1-schema": ["@peculiar/asn1-schema@2.8.0", "", { "dependencies": { "@peculiar/utils": "^2.0.2", "asn1js": "^3.0.10", "tslib": "^2.8.1" } }, "sha512-7YT0U/ze0tF2QOBbE15gKZwy5tvgGyLRiRHLzhlbOpf7BT032oBSd0haZqXn5W6l26WLlu3dyxzjM+2638/z2Q=="],
 
@@ -172,10 +203,16 @@
 
     "@types/debug": ["@types/debug@4.1.13", "", { "dependencies": { "@types/ms": "*" } }, "sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw=="],
 
+    "@types/esrecurse": ["@types/esrecurse@4.3.1", "", {}, "sha512-xJBAbDifo5hpffDBuHl0Y8ywswbiAp/Wi7Y/GtAgSlZyIABppyurxVueOPE8LUQOxdlgi6Zqce7uoEpqNTeiUw=="],
+
+    "@types/estree": ["@types/estree@1.0.9", "", {}, "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg=="],
+
     "@types/fs-extra": ["@types/fs-extra@9.0.13", "", { "dependencies": { "@types/node": "*" } }, "sha512-nEnwB++1u5lVDM2UI4c1+5R+FYaKfaAzS4OococimjVm3nQw3TuzH5UNsocrcTBbhnerblyHj4A49qXbIiZdpA=="],
 
     "@types/http-cache-semantics": ["@types/http-cache-semantics@4.2.0", "", {}, "sha512-L3LgimLHXtGkWikKnsPg0/VFx9OGZaC+eN1u4r+OB1XRqH3meBIAVC2zr1WdMH+RHmnRkqliQAOHNJ/E0j/e0Q=="],
 
+    "@types/json-schema": ["@types/json-schema@7.0.15", "", {}, "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA=="],
+
     "@types/keyv": ["@types/keyv@3.1.4", "", { "dependencies": { "@types/node": "*" } }, "sha512-BQ5aZNSCpj7D6K2ksrRCTmKRLEpnPvWDiLPfoGyhZ++8YtiK9d/3DBKPJgry359X/P1PfruyYwvnvwFjuEiEIg=="],
 
     "@types/ms": ["@types/ms@2.1.0", "", {}, "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA=="],
@@ -194,15 +231,19 @@
 
     "abbrev": ["abbrev@4.0.0", "", {}, "sha512-a1wflyaL0tHtJSmLSOVybYhy22vRih4eduhhrkcjgrWGnRfrZtovJ2FRjxuTtkkj47O/baf0R86QU5OuYpz8fA=="],
 
+    "acorn": ["acorn@8.16.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw=="],
+
+    "acorn-jsx": ["acorn-jsx@5.3.2", "", { "peerDependencies": { "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ=="],
+
     "agent-base": ["agent-base@6.0.2", "", { "dependencies": { "debug": "4" } }, "sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ=="],
 
-    "ajv": ["ajv@8.20.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA=="],
+    "ajv": ["ajv@6.14.0", "", { "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", "json-schema-traverse": "^0.4.1", "uri-js": "^4.2.2" } }, "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw=="],
 
     "ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
 
     "ansi-styles": ["ansi-styles@4.3.0", "", { "dependencies": { "color-convert": "^2.0.1" } }, "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg=="],
 
-    "app-builder-lib": ["app-builder-lib@26.16.1", "", { "dependencies": { "@electron/asar": "3.4.1", "@electron/fuses": "^1.8.0", "@electron/get": "^3.0.0", "@electron/notarize": "2.5.0", "@electron/osx-sign": "1.3.3", "@electron/rebuild": "^4.0.4", "@electron/universal": "2.0.3", "@malept/flatpak-bundler": "^0.4.0", "@noble/hashes": "^1.8.0", "@peculiar/webcrypto": "^1.7.1", "@types/fs-extra": "9.0.13", "ajv": "^8.18.0", "asn1js": "^3.0.10", "async-exit-hook": "^2.0.1", "builder-util": "26.16.0", "builder-util-runtime": "9.7.0", "chromium-pickle-js": "^0.2.0", "ci-info": "4.3.1", "debug": "^4.3.4", "dotenv": "^16.4.5", "dotenv-expand": "^11.0.6", "ejs": "^3.1.8", "electron-publish": "26.16.0", "fs-extra": "^10.1.0", "hosted-git-info": "^4.1.0", "isbinaryfile": "^5.0.0", "jiti": "^2.4.2", "js-yaml": "^4.1.0", "json5": "^2.2.3", "lazy-val": "^1.0.5", "minimatch": "^10.2.5", "pkijs": "^3.4.0", "plist": "3.1.0", "proper-lockfile": "^4.1.2", "resedit": "^1.7.0", "semver": "~7.7.3", "tar": "^7.5.7", "temp-file": "^3.4.0", "tiny-async-pool": "1.3.0", "unzipper": "^0.12.3", "which": "^5.0.0" }, "peerDependencies": { "dmg-builder": "26.16.1", "electron-builder-squirrel-windows": "26.16.1" } }, "sha512-FhaO6YOup01ZfQW0Z6gt3AyukJjv1gW4uFK47jTgwcHZKqyN/fSlK2LqPf9tAeZYLP2bRJLDzeOkRImsw2X4Pg=="],
+    "app-builder-lib": ["app-builder-lib@26.15.3", "", { "dependencies": { "@electron/asar": "3.4.1", "@electron/fuses": "^1.8.0", "@electron/get": "^3.0.0", "@electron/notarize": "2.5.0", "@electron/osx-sign": "1.3.3", "@electron/rebuild": "^4.0.4", "@electron/universal": "2.0.3", "@malept/flatpak-bundler": "^0.4.0", "@noble/hashes": "^2.2.0", "@peculiar/webcrypto": "^1.7.1", "@types/fs-extra": "9.0.13", "ajv": "^8.18.0", "asn1js": "^3.0.10", "async-exit-hook": "^2.0.1", "builder-util": "26.15.3", "builder-util-runtime": "9.7.0", "chromium-pickle-js": "^0.2.0", "ci-info": "4.3.1", "debug": "^4.3.4", "dotenv": "^16.4.5", "dotenv-expand": "^11.0.6", "ejs": "^3.1.8", "electron-publish": "26.15.3", "fs-extra": "^10.1.0", "hosted-git-info": "^4.1.0", "isbinaryfile": "^5.0.0", "jiti": "^2.4.2", "js-yaml": "^4.1.0", "json5": "^2.2.3", "lazy-val": "^1.0.5", "minimatch": "^10.2.5", "pkijs": "^3.4.0", "plist": "3.1.0", "proper-lockfile": "^4.1.2", "resedit": "^1.7.0", "semver": "~7.7.3", "tar": "^7.5.7", "temp-file": "^3.4.0", "tiny-async-pool": "1.3.0", "unzipper": "^0.12.3", "which": "^5.0.0" }, "peerDependencies": { "dmg-builder": "26.15.3", "electron-builder-squirrel-windows": "26.15.3" } }, "sha512-2VnyWkqsP5v5XbBhL3tD5Syx8iNPBYsoU7kY4S2fz7wg8Rj/nztWKCUzGKaFRTv0Xwf3/H058CR1Kvtd/3lRow=="],
 
     "argparse": ["argparse@2.0.1", "", {}, "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="],
 
@@ -218,7 +259,7 @@
 
     "aws4": ["aws4@1.13.2", "", {}, "sha512-lHe62zvbTB5eEABUVi/AwVh0ZKY9rMMDhmm+eeyuuUQbQ3+J+fONVQOZyj+DdrvD4BY33uYniyRJ4UJIaSKAfw=="],
 
-    "axios": ["axios@1.20.0", "", { "dependencies": { "follow-redirects": "^1.16.0", "form-data": "^4.0.6", "https-proxy-agent": "^5.0.1", "proxy-from-env": "^2.1.0" } }, "sha512-r8aOh8j9cGKpgQAqpzrUHnSIc6a59Y3Xf/cv8sy1DrHCkZHzQGEuoq1tARk6qSyDdtQGSDgpb9kFlruzPvrgwg=="],
+    "axios": ["axios@1.18.1", "", { "dependencies": { "follow-redirects": "^1.16.0", "form-data": "^4.0.5", "https-proxy-agent": "^5.0.1", "proxy-from-env": "^2.1.0" } }, "sha512-3nTvFlvpn9Zu/RkHUqtc7/+al4UpRW5az71ap5zccp6e8RAYEzhMTecX8Dz1wWDYrPpUoB1HAQEGEAEvUr7S9g=="],
 
     "balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
 
@@ -228,11 +269,11 @@
 
     "boolean": ["boolean@3.2.0", "", {}, "sha512-d0II/GO9uf9lfUHH2BQsjxzRJZBdsjgsBiW4BvhWk/3qoKwQFjIDVN19PfX8F2D/r9PCMTtLWjYVCFrpeYUzsw=="],
 
-    "brace-expansion": ["brace-expansion@5.0.11", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-awigjhi6cLTh90bdw6+QJ9CtmJmyYhEIi70iCbc8Rozn04Fw9FeQIBjv/E22FFGuCGx1bLJyUfB64x/szUSXUg=="],
+    "brace-expansion": ["brace-expansion@5.0.9", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg=="],
 
     "buffer-from": ["buffer-from@1.1.2", "", {}, "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ=="],
 
-    "builder-util": ["builder-util@26.16.0", "", { "dependencies": { "@types/debug": "^4.1.6", "builder-util-runtime": "9.7.0", "chalk": "^4.1.2", "cross-spawn": "^7.0.6", "debug": "^4.3.4", "fs-extra": "^10.1.0", "http-proxy-agent": "^7.0.0", "https-proxy-agent": "^7.0.0", "js-yaml": "^4.1.0", "sanitize-filename": "^1.6.3", "source-map-support": "^0.5.19", "stat-mode": "^1.0.0", "temp-file": "^3.4.0", "tiny-async-pool": "1.3.0" } }, "sha512-RLyJhB7Si3YkzKR9ubQslWuXW3Vhs3CGe1i+SeixBZ0qTd1mk3XBmssvY22TlB6CS5blyko8Gu1JzpYk8UkYAg=="],
+    "builder-util": ["builder-util@26.15.3", "", { "dependencies": { "@types/debug": "^4.1.6", "builder-util-runtime": "9.7.0", "chalk": "^4.1.2", "cross-spawn": "^7.0.6", "debug": "^4.3.4", "fs-extra": "^10.1.0", "http-proxy-agent": "^7.0.0", "https-proxy-agent": "^7.0.0", "js-yaml": "^4.1.0", "sanitize-filename": "^1.6.3", "source-map-support": "^0.5.19", "stat-mode": "^1.0.0", "temp-file": "^3.4.0", "tiny-async-pool": "1.3.0" } }, "sha512-q2hn7Mbo2nFNkVekPiHFx6Nfo3hURmES3tfBn+k5Pqxl2RkmP3QGqZUhH/q9Pch/4G05NRhPjDlVj1O8q4Txvw=="],
 
     "builder-util-runtime": ["builder-util-runtime@9.7.0", "", { "dependencies": { "debug": "^4.3.4", "sax": "^1.2.4" } }, "sha512-g/kR520giAFYkSXTzcmF3kqQq7wi8F6N6SzeDgZrqTBN+VHdmgWOyTdD1yD7AATDId/yXLvuP34CxW46/BwCdw=="],
 
@@ -276,6 +317,8 @@
 
     "decompress-response": ["decompress-response@6.0.0", "", { "dependencies": { "mimic-response": "^3.1.0" } }, "sha512-aW35yZM6Bb/4oJlZncMH2LCoZtJXTRxES17vE3hoRiowU2kWHaJKFkSBDnDR+cm9J+9QhXmREyIfv0pji9ejCQ=="],
 
+    "deep-is": ["deep-is@0.1.4", "", {}, "sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ=="],
+
     "defer-to-connect": ["defer-to-connect@2.0.1", "", {}, "sha512-4tvttepXG1VaYGrRibk5EwJd1t4udunSOVMdLSAL6mId1ix438oPwPZMALY41FCijukO1L0twNcGsdzS7dHgDg=="],
 
     "define-data-property": ["define-data-property@1.1.4", "", { "dependencies": { "es-define-property": "^1.0.0", "es-errors": "^1.3.0", "gopd": "^1.0.1" } }, "sha512-rBMvIzlpA8v6E+SJZoo++HAYqsLrkg7MSfIinMPFhmkorw7X+dOXVJQs+QT69zGkzMyfDnIMN2Wid1+NbL3T+A=="],
@@ -292,7 +335,7 @@
 
     "discord-api-types": ["discord-api-types@0.38.49", "", {}, "sha512-XnqcWmnFZFAE8ZM8SHAw9DIV8D3Or00rMQ8iQLotrEA2PmXhl+ykaf6L6q4l474hrSUH1JaYcv+iOMRWp2p6Tg=="],
 
-    "dmg-builder": ["dmg-builder@26.16.1", "", { "dependencies": { "app-builder-lib": "26.16.1", "builder-util": "26.16.0", "fs-extra": "^10.1.0", "js-yaml": "^4.1.0" } }, "sha512-pnI/3Qb24Uk+rMTgIUrsVUKosVgwmBUdF8Zeb8TexOSbpq8MWc7v6l+n+FrEqVkjNZwzBN+XpDS9ENgZ/rkWAw=="],
+    "dmg-builder": ["dmg-builder@26.15.3", "", { "dependencies": { "app-builder-lib": "26.15.3", "builder-util": "26.15.3", "fs-extra": "^10.1.0", "js-yaml": "^4.1.0" } }, "sha512-O3zJUFUYHJKgzPqioHxfxzBzlSC1eXCSr79gMSBKBP5AgjjpmrydMsMLotEg9fAJF36vdUncb+4ndRNxoPdlSQ=="],
 
     "dotenv": ["dotenv@16.6.1", "", {}, "sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow=="],
 
@@ -304,13 +347,13 @@
 
     "ejs": ["ejs@3.1.10", "", { "dependencies": { "jake": "^10.8.5" }, "bin": { "ejs": "bin/cli.js" } }, "sha512-UeJmFfOrAQS8OJWPZ4qtgHyWExa088/MtK5UEyoJGFH67cDEXkZSviOiKRCZ4Xij0zxI3JECgYs3oKx+AizQBA=="],
 
-    "electron": ["electron@43.7.7", "", { "dependencies": { "@electron-internal/extract-zip": "^1.0.1", "@electron/get": "^5.0.0", "@types/node": "^24.9.0" }, "bin": { "electron": "cli.js", "install-electron": "install.js" } }, "sha512-y0pg+KhWLAkW2Ts2njkFFNFl3KtB1FmbUp9Te9i+R2Og2v1fcI/I6MADJ7jvnzB5UKdt+U+0EUoCnVL79xMPMA=="],
+    "electron": ["electron@42.6.0", "", { "dependencies": { "@electron-internal/extract-zip": "^1.0.1", "@electron/get": "^5.0.0", "@types/node": "^24.9.0" }, "bin": { "electron": "cli.js", "install-electron": "install.js" } }, "sha512-axGNgd+yCTg+vi1VEGrQqAj9WVWkePKwbICSAvMiT2eTaxhij9a/xhBHD6rXV8wrlW9ZfJzE5+xg752ImxrmTw=="],
 
-    "electron-builder": ["electron-builder@26.16.1", "", { "dependencies": { "app-builder-lib": "26.16.1", "builder-util": "26.16.0", "builder-util-runtime": "9.7.0", "chalk": "^4.1.2", "ci-info": "^4.2.0", "dmg-builder": "26.16.1", "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-LrLK65QX5PUYYODXqp23FKrV7CILTtVY7mrJckNknO9jLNSMiqFkKbSMiDRw4CjOADMPVDdWLxY4mezOZWswxg=="],
+    "electron-builder": ["electron-builder@26.15.3", "", { "dependencies": { "app-builder-lib": "26.15.3", "builder-util": "26.15.3", "builder-util-runtime": "9.7.0", "chalk": "^4.1.2", "ci-info": "^4.2.0", "dmg-builder": "26.15.3", "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-a1KM5heqS3gQCZzizXEI8RjJy3QVogULPdeSknt76uLDpBIW/HDGsMg/XgP0riP6PI9COsRvFITKKGDqA8fJxA=="],
 
-    "electron-builder-squirrel-windows": ["electron-builder-squirrel-windows@26.16.1", "", { "dependencies": { "app-builder-lib": "26.16.1", "builder-util": "26.16.0", "electron-winstaller": "5.4.0" } }, "sha512-w0y44wSaT1l6R7CAGmeHn4nHPfvzDyCAU1xJyi1w9SbPYJpYn76SmHDzqHf8Y7l91cPWTdPYBpGQtB2T5mJ08A=="],
+    "electron-builder-squirrel-windows": ["electron-builder-squirrel-windows@26.15.3", "", { "dependencies": { "app-builder-lib": "26.15.3", "builder-util": "26.15.3", "electron-winstaller": "5.4.0" } }, "sha512-Jc19XPV9y9+2bAdZPkXuVNGNIEFBq9poHC61l8Kv6FdK7DRG3+Ic0rerC0DXOaeHNz8yW0fg/JnF8GQROOF5MA=="],
 
-    "electron-publish": ["electron-publish@26.16.0", "", { "dependencies": { "@types/fs-extra": "^9.0.11", "aws4": "^1.13.2", "builder-util": "26.16.0", "builder-util-runtime": "9.7.0", "chalk": "^4.1.2", "form-data": "^4.0.5", "fs-extra": "^10.1.0", "lazy-val": "^1.0.5", "mime": "^2.5.2" } }, "sha512-Vt3KzQIiw9BImvNOYtndg9Mjki+tl4+1sQiC/+G5j8khWaENOJFWodiB+sUl6yyHwtd37avehskdtPw7f8y/+Q=="],
+    "electron-publish": ["electron-publish@26.15.3", "", { "dependencies": { "@types/fs-extra": "^9.0.11", "aws4": "^1.13.2", "builder-util": "26.15.3", "builder-util-runtime": "9.7.0", "chalk": "^4.1.2", "form-data": "^4.0.5", "fs-extra": "^10.1.0", "lazy-val": "^1.0.5", "mime": "^2.5.2" } }, "sha512-g/2bn8YTavY4cuS5F+jOS7zmZbXXBV8KZ8yHKfJjFPoKtzBqrpCdNPxBd3tqdBwP7BVd0lGzf7Bk2s0KesWZ4Q=="],
 
     "electron-updater": ["electron-updater@6.8.9", "", { "dependencies": { "builder-util-runtime": "9.7.0", "fs-extra": "^10.1.0", "js-yaml": "^4.1.0", "lazy-val": "^1.0.5", "lodash.escaperegexp": "^4.1.2", "lodash.isequal": "^4.5.0", "semver": "~7.7.3", "tiny-typed-emitter": "^2.1.0" } }, "sha512-ZhVxM9iGONUpZGI1FxdMRgJjUFXi7AYGVa5PwKlO1tV1/4zDxQmfKpXOHVztKrd6L9rLcFjERvi1Mf2vxyTkig=="],
 
@@ -340,16 +383,44 @@
 
     "escape-string-regexp": ["escape-string-regexp@4.0.0", "", {}, "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA=="],
 
+    "eslint": ["eslint@10.8.0", "", { "dependencies": { "@eslint-community/eslint-utils": "^4.8.0", "@eslint-community/regexpp": "^4.12.2", "@eslint/config-array": "^0.23.5", "@eslint/config-helpers": "^0.7.0", "@eslint/core": "^1.2.1", "@eslint/plugin-kit": "^0.7.2", "@humanfs/node": "^0.16.6", "@humanwhocodes/module-importer": "^1.0.1", "@humanwhocodes/retry": "^0.4.2", "@types/estree": "^1.0.6", "ajv": "^6.14.0", "cross-spawn": "^7.0.6", "debug": "^4.3.2", "escape-string-regexp": "^4.0.0", "eslint-scope": "^9.1.2", "eslint-visitor-keys": "^5.0.1", "espree": "^11.2.0", "esquery": "^1.7.0", "esutils": "^2.0.2", "fast-deep-equal": "^3.1.3", "file-entry-cache": "^8.0.0", "find-up": "^5.0.0", "glob-parent": "^6.0.2", "ignore": "^5.2.0", "imurmurhash": "^0.1.4", "is-glob": "^4.0.0", "json-stable-stringify-without-jsonify": "^1.0.1", "minimatch": "^10.2.5", "natural-compare": "^1.4.0", "optionator": "^0.9.3" }, "peerDependencies": { "jiti": "*" }, "optionalPeers": ["jiti"], "bin": { "eslint": "bin/eslint.js" } }, "sha512-nuKKvN+oIBO0koN7Tm7dlkmnkc21mtt0QJLwAKzjLq14y6lRTdVG36MZHJ8eQHwdJMwZbQNMlPOYedMq/oVJvQ=="],
+
+    "eslint-scope": ["eslint-scope@9.1.2", "", { "dependencies": { "@types/esrecurse": "^4.3.1", "@types/estree": "^1.0.8", "esrecurse": "^4.3.0", "estraverse": "^5.2.0" } }, "sha512-xS90H51cKw0jltxmvmHy2Iai1LIqrfbw57b79w/J7MfvDfkIkFZ+kj6zC3BjtUwh150HsSSdxXZcsuv72miDFQ=="],
+
+    "eslint-visitor-keys": ["eslint-visitor-keys@5.0.1", "", {}, "sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA=="],
+
+    "espree": ["espree@11.2.0", "", { "dependencies": { "acorn": "^8.16.0", "acorn-jsx": "^5.3.2", "eslint-visitor-keys": "^5.0.1" } }, "sha512-7p3DrVEIopW1B1avAGLuCSh1jubc01H2JHc8B4qqGblmg5gI9yumBgACjWo4JlIc04ufug4xJ3SQI8HkS/Rgzw=="],
+
+    "esquery": ["esquery@1.7.0", "", { "dependencies": { "estraverse": "^5.1.0" } }, "sha512-Ap6G0WQwcU/LHsvLwON1fAQX9Zp0A2Y6Y/cJBl9r/JbW90Zyg4/zbG6zzKa2OTALELarYHmKu0GhpM5EO+7T0g=="],
+
+    "esrecurse": ["esrecurse@4.3.0", "", { "dependencies": { "estraverse": "^5.2.0" } }, "sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag=="],
+
+    "estraverse": ["estraverse@5.3.0", "", {}, "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA=="],
+
+    "esutils": ["esutils@2.0.3", "", {}, "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g=="],
+
     "exponential-backoff": ["exponential-backoff@3.1.3", "", {}, "sha512-ZgEeZXj30q+I0EN+CbSSpIyPaJ5HVQD18Z1m+u1FXbAeT94mr1zw50q4q6jiiC447Nl/YTcIYSAftiGqetwXCA=="],
 
     "fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
 
-    "fast-uri": ["fast-uri@3.1.7", "", {}, "sha512-dOvZVzjdZdz7phd9v6jCbwxrBW3fK6n8Rc0CtdmM4bumzMnxywBYhuph6J819RRw/ku+rLbelwfMunktuzVVHg=="],
+    "fast-json-stable-stringify": ["fast-json-stable-stringify@2.1.0", "", {}, "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw=="],
+
+    "fast-levenshtein": ["fast-levenshtein@2.0.6", "", {}, "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw=="],
+
+    "fast-uri": ["fast-uri@3.1.6", "", {}, "sha512-7Ical1vFEMr0onbVzEDIreM22I4khW+fzyQPwvAFWBp1iwdshSZRsL4jjRvPG9JP1uiqMHRto+YU6R2/CzDz5Q=="],
 
     "fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],
 
+    "file-entry-cache": ["file-entry-cache@8.0.0", "", { "dependencies": { "flat-cache": "^4.0.0" } }, "sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ=="],
+
     "filelist": ["filelist@1.0.6", "", { "dependencies": { "minimatch": "^5.0.1" } }, "sha512-5giy2PkLYY1cP39p17Ech+2xlpTRL9HLspOfEgm0L6CwBXBTgsK5ou0JtzYuepxkaQ/tvhCFIJ5uXo0OrM2DxA=="],
 
+    "find-up": ["find-up@5.0.0", "", { "dependencies": { "locate-path": "^6.0.0", "path-exists": "^4.0.0" } }, "sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng=="],
+
+    "flat-cache": ["flat-cache@4.0.1", "", { "dependencies": { "flatted": "^3.2.9", "keyv": "^4.5.4" } }, "sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw=="],
+
+    "flatted": ["flatted@3.4.2", "", {}, "sha512-PjDse7RzhcPkIJwy5t7KPWQSZ9cAbzQXcafsetQoD7sOJRQlGikNbx7yZp2OotDnJyrDcbyRq3Ttb18iYOqkxA=="],
+
     "follow-redirects": ["follow-redirects@1.16.0", "", {}, "sha512-y5rN/uOsadFT/JfYwhxRS5R7Qce+g3zG97+JrtFZlC9klX/W5hD7iiLzScI4nZqUS7DNUdhPgw4xI8W2LuXlUw=="],
 
     "form-data": ["form-data@4.0.6", "", { "dependencies": { "asynckit": "^0.4.0", "combined-stream": "^1.0.8", "es-set-tostringtag": "^2.1.0", "hasown": "^2.0.4", "mime-types": "^2.1.35" } }, "sha512-vKatAh4SlVfgbv+YtmhiRjhEMJsYpsG1Y2rMQtR+SVSbytsSD1YGzDIcrAJmdFec88u/+VoGmxnl+80gL1tRCQ=="],
@@ -370,6 +441,8 @@
 
     "glob": ["glob@7.2.3", "", { "dependencies": { "fs.realpath": "^1.0.0", "inflight": "^1.0.4", "inherits": "2", "minimatch": "^3.1.1", "once": "^1.3.0", "path-is-absolute": "^1.0.0" } }, "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q=="],
 
+    "glob-parent": ["glob-parent@6.0.2", "", { "dependencies": { "is-glob": "^4.0.3" } }, "sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A=="],
+
     "global-agent": ["global-agent@3.0.0", "", { "dependencies": { "boolean": "^3.0.1", "es6-error": "^4.1.1", "matcher": "^3.0.0", "roarr": "^2.15.3", "semver": "^7.3.2", "serialize-error": "^7.0.1" } }, "sha512-PT6XReJ+D07JvGoxQMkT6qji/jVNfX/h364XHZOWeRzy64sSFr+xJ5OX7LI3b4MPQzdL4H8Y8M0xzPpsVMwA8Q=="],
 
     "globalthis": ["globalthis@1.0.4", "", { "dependencies": { "define-properties": "^1.2.1", "gopd": "^1.0.1" } }, "sha512-DpLKbNU4WylpxJykQujfCcwYWiV/Jhm50Goo0wrVILAv5jOr9d+H+UR3PhSCD2rCCEIg0uc+G+muBTwD54JhDQ=="],
@@ -394,7 +467,7 @@
 
     "hosted-git-info": ["hosted-git-info@4.1.0", "", { "dependencies": { "lru-cache": "^6.0.0" } }, "sha512-kyCuEOWjJqZuDbRHzL8V93NzQhwIB71oFWSyzVo+KPZI+pnQPPxucdkrOZvkLRnrf5URsQM+IJ09Dw29cRALIA=="],
 
-    "http-cache-semantics": ["http-cache-semantics@4.3.0", "", {}, "sha512-M5t5LlJpS1UHMjvwRQVdFHvPISGeLAxNcrWuJkeGh0KxsqCHZ1O3NXZU/8x7cD0BDcGW8kapxMKTvwlqrNkHkA=="],
+    "http-cache-semantics": ["http-cache-semantics@4.2.0", "", {}, "sha512-dTxcvPXqPvXBQpq5dUr6mEMJX4oIEFv6bwom3FDwKRDsuIjjJGANqhBuoAn9c1RQJIdAKav33ED65E2ys+87QQ=="],
 
     "http-proxy-agent": ["http-proxy-agent@7.0.2", "", { "dependencies": { "agent-base": "^7.1.0", "debug": "^4.3.4" } }, "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig=="],
 
@@ -402,12 +475,20 @@
 
     "https-proxy-agent": ["https-proxy-agent@5.0.1", "", { "dependencies": { "agent-base": "6", "debug": "4" } }, "sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA=="],
 
+    "ignore": ["ignore@5.3.2", "", {}, "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g=="],
+
+    "imurmurhash": ["imurmurhash@0.1.4", "", {}, "sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA=="],
+
     "inflight": ["inflight@1.0.6", "", { "dependencies": { "once": "^1.3.0", "wrappy": "1" } }, "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA=="],
 
     "inherits": ["inherits@2.0.4", "", {}, "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="],
 
+    "is-extglob": ["is-extglob@2.1.1", "", {}, "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ=="],
+
     "is-fullwidth-code-point": ["is-fullwidth-code-point@3.0.0", "", {}, "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="],
 
+    "is-glob": ["is-glob@4.0.3", "", { "dependencies": { "is-extglob": "^2.1.1" } }, "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg=="],
+
     "isarray": ["isarray@1.0.0", "", {}, "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ=="],
 
     "isbinaryfile": ["isbinaryfile@5.0.7", "", {}, "sha512-gnWD14Jh3FzS3CPhF0AxNOJ8CxqeblPTADzI38r0wt8ZyQl5edpy75myt08EG2oKvpyiqSqsx+Wkz9vtkbTqYQ=="],
@@ -422,7 +503,9 @@
 
     "json-buffer": ["json-buffer@3.0.1", "", {}, "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ=="],
 
-    "json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
+    "json-schema-traverse": ["json-schema-traverse@0.4.1", "", {}, "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg=="],
+
+    "json-stable-stringify-without-jsonify": ["json-stable-stringify-without-jsonify@1.0.1", "", {}, "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw=="],
 
     "json-stringify-safe": ["json-stringify-safe@5.0.1", "", {}, "sha512-ZClg6AaYvamvYEE82d3Iyd3vSSIjQ+odgjaTzRuO3s7toCdFKczob2i0zCh7JE8kWn17yvAWhUVxvqGwUalsRA=="],
 
@@ -438,8 +521,12 @@
 
     "lazy-val": ["lazy-val@1.0.5", "", {}, "sha512-0/BnGCCfyUMkBpeDgWihanIAF9JmZhHBgUhEqzvf+adhNGLoP6TaiI5oF8oyb3I45P+PcnrqihSf01M0l0G5+Q=="],
 
+    "levn": ["levn@0.4.1", "", { "dependencies": { "prelude-ls": "^1.2.1", "type-check": "~0.4.0" } }, "sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ=="],
+
     "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=="],
 
+    "locate-path": ["locate-path@6.0.0", "", { "dependencies": { "p-locate": "^5.0.0" } }, "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw=="],
+
     "lodash": ["lodash@4.18.0", "", {}, "sha512-l1mfj2atMqndAHI3ls7XqPxEjV2J9ZkcNyHpoZA3r2T1LLwDB69jgkMWh71YKwhBbK0G2f4WSn05ahmQXVxupA=="],
 
     "lodash.escaperegexp": ["lodash.escaperegexp@4.1.2", "", {}, "sha512-TM9YBvyC84ZxE3rgfefxUWiQKLilstD6k7PTGt6wfbtXF8ixIJLOL3VYyV/z+ZiPLsVxAsKAFVwWlWeb2Y8Yyw=="],
@@ -476,6 +563,8 @@
 
     "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
 
+    "natural-compare": ["natural-compare@1.4.0", "", {}, "sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw=="],
+
     "node-abi": ["node-abi@4.28.0", "", { "dependencies": { "semver": "^7.6.3" } }, "sha512-Qfp5XZL1cJDOabOT8H5gnqMTmM4NjvYzHp4I/Kt/Sl76OVkOBBHRFlPspGV0hYvMoqQsypFjT/Yp7Km0beXW9g=="],
 
     "node-api-version": ["node-api-version@0.2.1", "", { "dependencies": { "semver": "^7.3.5" } }, "sha512-2xP/IGGMmmSQpI1+O/k72jF/ykvZ89JeuKX3TLJAYPDVLUalrshrLHkeVcCCZqG/eEa635cr8IBYzgnDvM2O8Q=="],
@@ -492,10 +581,16 @@
 
     "once": ["once@1.4.0", "", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="],
 
+    "optionator": ["optionator@0.9.4", "", { "dependencies": { "deep-is": "^0.1.3", "fast-levenshtein": "^2.0.6", "levn": "^0.4.1", "prelude-ls": "^1.2.1", "type-check": "^0.4.0", "word-wrap": "^1.2.5" } }, "sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g=="],
+
     "p-cancelable": ["p-cancelable@2.1.1", "", {}, "sha512-BZOr3nRQHOntUjTrH8+Lh54smKHoHyur8We1V8DSMVrl5A2malOOwuJRnKRDjSnkoeBh4at6BwEnb5I7Jl31wg=="],
 
     "p-limit": ["p-limit@3.1.0", "", { "dependencies": { "yocto-queue": "^0.1.0" } }, "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ=="],
 
+    "p-locate": ["p-locate@5.0.0", "", { "dependencies": { "p-limit": "^3.0.2" } }, "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw=="],
+
+    "path-exists": ["path-exists@4.0.0", "", {}, "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w=="],
+
     "path-is-absolute": ["path-is-absolute@1.0.1", "", {}, "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg=="],
 
     "path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
@@ -512,6 +607,8 @@
 
     "postject": ["postject@1.0.0-alpha.6", "", { "dependencies": { "commander": "^9.4.0" }, "bin": { "postject": "dist/cli.js" } }, "sha512-b9Eb8h2eVqNE8edvKdwqkrY6O7kAwmI8kcnBv1NScolYJbo59XUF0noFq+lxbC1yN20bmC0WBEbDC5H/7ASb0A=="],
 
+    "prelude-ls": ["prelude-ls@1.2.1", "", {}, "sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g=="],
+
     "prettier": ["prettier@3.8.1", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg=="],
 
     "proc-log": ["proc-log@6.1.0", "", {}, "sha512-iG+GYldRf2BQ0UDUAd6JQ/RwzaQy6mXmsk/IzlYyal4A4SNFw54MeH4/tLkF4I5WoWG9SQwuqWzS99jaFQHBuQ=="],
@@ -528,6 +625,8 @@
 
     "pump": ["pump@3.0.4", "", { "dependencies": { "end-of-stream": "^1.1.0", "once": "^1.3.1" } }, "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA=="],
 
+    "punycode": ["punycode@2.3.1", "", {}, "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg=="],
+
     "pvtsutils": ["pvtsutils@1.3.6", "", { "dependencies": { "tslib": "^2.8.1" } }, "sha512-PLgQXQ6H2FWCaeRak8vvk1GW462lMxB5s3Jm673N82zI4vqtVUPuZdffdZbPDFRoU8kAhItWFtPCWiPpp4/EDg=="],
 
     "pvutils": ["pvutils@1.1.5", "", {}, "sha512-KTqnxsgGiQ6ZAzZCVlJH5eOjSnvlyEgx1m8bkRJfOhmGRqfo5KLvmAlACQkrjEtOQ4B7wF9TdSLIs9O90MX9xA=="],
@@ -612,11 +711,13 @@
 
     "tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
 
+    "type-check": ["type-check@0.4.0", "", { "dependencies": { "prelude-ls": "^1.2.1" } }, "sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew=="],
+
     "type-fest": ["type-fest@0.13.1", "", {}, "sha512-34R7HTnG0XIJcBSn5XhDd7nNFPRcXYRZrBB2O2jdKqYODldSzBAqzsWoZYYvduky73toYS/ESqxPvkDf/F0XMg=="],
 
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
-    "undici": ["undici@7.29.1", "", {}, "sha512-RYONW2MeafgYlkVOKYKkA/Ag7BmXqgIWCa8t1m0JcxrQg9pI9lEqRhAOruOBCbAohOa/gkCF+iPi9hrgvTzu6Q=="],
+    "undici": ["undici@7.29.0", "", {}, "sha512-IDxfleLmmbSskfWSUATiN1nfn2rDuvnMOqb5CWR92iIfojA0Ud+ulOAAEQ57LPr9rWmsreUyf5lwyao+7GNNVw=="],
 
     "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
 
@@ -624,6 +725,8 @@
 
     "unzipper": ["unzipper@0.12.5", "", { "dependencies": { "bluebird": "~3.7.2", "duplexer2": "~0.1.4", "fs-extra": "11.3.1", "graceful-fs": "^4.2.2", "node-int64": "^0.4.0" } }, "sha512-tXYOi9R57Uj/2Z25SOs5RRSzq886MBQj2gY8dPL+xl/kv6s6SvByoKfAtvfVeEuhntWDgjd2o9p2lb4TVPAz0A=="],
 
+    "uri-js": ["uri-js@4.4.1", "", { "dependencies": { "punycode": "^2.1.0" } }, "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg=="],
+
     "utf8-byte-length": ["utf8-byte-length@1.0.5", "", {}, "sha512-Xn0w3MtiQ6zoz2vFyUVruaCL53O/DwUvkEeOvj+uulMm0BkUGYWmBYVyElqZaSLhY6ZD0ulfU3aBra2aVT4xfA=="],
 
     "util-deprecate": ["util-deprecate@1.0.2", "", {}, "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw=="],
@@ -632,6 +735,8 @@
 
     "which": ["which@5.0.0", "", { "dependencies": { "isexe": "^3.1.1" }, "bin": { "node-which": "bin/which.js" } }, "sha512-JEdGzHwwkrbWoGOlIHqQ5gtprKGOenpDHpxE9zVR1bWbOtYRyPPHMe9FaP6x61CmNaTThSkb0DAJte5jD+DmzQ=="],
 
+    "word-wrap": ["word-wrap@1.2.5", "", {}, "sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA=="],
+
     "wrap-ansi": ["wrap-ansi@7.0.0", "", { "dependencies": { "ansi-styles": "^4.0.0", "string-width": "^4.1.0", "strip-ansi": "^6.0.0" } }, "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q=="],
 
     "wrappy": ["wrappy@1.0.2", "", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="],
@@ -666,6 +771,8 @@
 
     "@electron/windows-sign/fs-extra": ["fs-extra@11.3.4", "", { "dependencies": { "graceful-fs": "^4.2.0", "jsonfile": "^6.0.1", "universalify": "^2.0.0" } }, "sha512-CTXd6rk/M3/ULNQj8FBqBWHYBVYybQ3VPBw0xGKFe3tuH7ytT6ACnvzpIQ3UZtB8yvUKC2cXn1a+x+5EVQLovA=="],
 
+    "@eslint-community/eslint-utils/eslint-visitor-keys": ["eslint-visitor-keys@3.4.3", "", {}, "sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag=="],
+
     "@malept/flatpak-bundler/fs-extra": ["fs-extra@9.1.0", "", { "dependencies": { "at-least-node": "^1.0.0", "graceful-fs": "^4.2.0", "jsonfile": "^6.0.1", "universalify": "^2.0.0" } }, "sha512-hcg3ZmepS30/7BSFqRvoo3DOMQu7IjqxO5nCDt+zM9XWjb33Wg7ziNT+Qvqbuc3+gWpzO02JubVyk2G4Zvo1OQ=="],
 
     "@types/cacheable-request/@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
@@ -680,6 +787,8 @@
 
     "app-builder-lib/@electron/get": ["@electron/get@3.1.0", "", { "dependencies": { "debug": "^4.1.1", "env-paths": "^2.2.0", "fs-extra": "^8.1.0", "got": "^11.8.5", "progress": "^2.0.3", "semver": "^6.2.0", "sumchecker": "^3.0.1" }, "optionalDependencies": { "global-agent": "^3.0.0" } }, "sha512-F+nKc0xW+kVbBRhFzaMgPy3KwmuNTYX1fx6+FxxoSnNgwYX6LD7AKBTWkU0MQ6IBoe7dz069CNkR673sPAgkCQ=="],
 
+    "app-builder-lib/ajv": ["ajv@8.20.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA=="],
+
     "app-builder-lib/ci-info": ["ci-info@4.3.1", "", {}, "sha512-Wdy2Igu8OcBpI2pZePZ5oWjPC38tmDVx5WKUXKwlLYkA0ozo85sLsLvkBbBn/sZaSCMFOGZJ14fvW9t5/d7kdA=="],
 
     "builder-util/https-proxy-agent": ["https-proxy-agent@7.0.6", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "4" } }, "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw=="],
@@ -726,6 +835,8 @@
 
     "app-builder-lib/@electron/get/semver": ["semver@6.3.1", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="],
 
+    "app-builder-lib/ajv/json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
+
     "builder-util/https-proxy-agent/agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
 
     "cross-spawn/which/isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],

changes/README.md

@@ -42,7 +42,7 @@ 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.
 - The polish step treats pending fragments as the final release outcome, not prerelease history. If a feature is added and then renamed or fixed before the stable cut, ship the final feature bullet instead of separate prerelease-only breaking/fix entries.
-- `CHANGELOG.md`, GitHub release notes, and prerelease notes all use one item per feature or area, inline by default: `- **Name**: one or two short sentences.` Items with several separate changes may use a few short nested bullets instead of a run-on sentence. Items say what changed and how to reach it; implementation details, edge cases, and step-by-step usage belong in the docs, not the release body.
+- `CHANGELOG.md`, GitHub release notes, and prerelease notes all use short top-level items with one nested bullet per distinct change, instead of packing a release's worth of detail into a single paragraph bullet. An item with only one thing to say stays inline on the top-level bullet. Release notes and prerelease notes additionally cover user benefit and any useful action note in their nested bullets.
 - `internal` fragments stay in `CHANGELOG.md` (inside a collapsed `<details>` block) but are dropped from the GitHub release notes entirely.
 - The polished `CHANGELOG.md` and `release/release-notes.md` are committed and reviewed before tagging — edit the Markdown by hand if Claude misses something.
 

changes/anilist-season-resolution.md

@@ -0,0 +1,7 @@
+type: fixed
+area: anilist
+
+- Resolving "season N" against AniList no longer lands one season short for franchises whose broadcast seasons are listed as several entries. AniList records the back half of a split cour ("… Season 2 Part 2", "… Cour 2", "第2クール") as its own sequel, and the resolver counted each as a season — so Mushoku Tensei season 3 resolved to the season 2 entry and Re:ZERO season 4 to season 3, which then drove the character dictionary and AniList progress updates to the wrong series. A sequel carrying a part or cour marker that matches the season it continues is now followed without advancing the season count, in both the relation walk and the air-order fallback. Titles are compared ignoring punctuation, and the marker is looked for in every title and synonym rather than just the display title. A wrong match cached before this fix is remembered in `character-dictionaries/anilist-resolution-cache.json` and needs removing (or overriding from the character dictionary picker) for the affected series.
+- A special or OVA sitting in a franchise's sequel chain is walked through without counting as a season. Dr. STONE links STONE WARS to New World through a one-episode special, which made New World resolve as season 4 and every later season shift with it.
+- An AniList rate limit or network failure while walking sequel relations is reported so the caller can retry, instead of falling through to the air-date fallback. That fallback is for a franchise with missing relation edges; running it after a failed lookup turned a transient 429 into a confidently wrong season.
+- The shared title parser recognizes spelled-out episode labels (`Episode 4`, `第4話`) and a season named at the end of the title (`… Season 3`, `… 3rd Season`, `… S3`), which now fill the Season field instead of being searched for as part of the series name. The TsukiHime modal gained a Season field to match Jimaku, and seasons after the first are included in its search query so a later season's releases are actually found.

changes/anime-browser-disclaimer-docs.md

@@ -0,0 +1,4 @@
+type: docs
+area: anime
+
+- Added a README disclaimer stating that SubMiner hosts no content, ships no anime sources or repositories, is not affiliated with any content provider, and that users are responsible for the content they access. The anime browser docs no longer describe SubMiner as a "host" of extensions.

changes/anime-browser.md

@@ -0,0 +1,36 @@
+type: added
+area: anime
+
+- Added an anime browser window that searches Aniyomi extension sources, shows cover art and episode lists, and plays an episode in mpv so the overlay and mining tools attach as usual.
+- Browser failures show a dismissible explanation with next steps and expandable technical details, including the bridge's error response instead of only its HTTP status.
+- Added `subminer anime` and the `--anime` flag to open the browser, plus a "Browse Anime" tray entry.
+- Anime extensions are read from `<userData>/anime-extensions`; drop Aniyomi `.apk` files there to add sources.
+- Added a source settings tab so extensions that need configuration (server address, credentials, quality) can be set up from the browser; values persist per extension and source, and updated extension schemas replace stale saved field definitions without losing values. Older unscoped preferences are discarded once because their package ownership cannot be proven safely.
+- Added an Extensions tab for adding repository URLs and installing, updating, or removing extensions in place; extensions that fail to load are listed with the reason. Repository requests time out instead of hanging, APK updates are staged before replacing the installed copy, and removing an extension refreshes the runtime even when saved credential cleanup fails while still reporting that failure.
+- Browse, Extensions, and Source settings are tabs, so each one gets the full window instead of sharing it with the search results.
+- Repository URLs only need to be an https URL to a `.json` index; the file name is not restricted to `index.min.json`.
+- The source picker offers "All sources", which searches every installed source at once. Results stream in as each source answers, with per-source progress in the status bar. Results are tagged with their source, failures do not blank the grid, and **Load more** appends later pages without duplicating streamed entries.
+- The Extensions tab opens with an Installed section listing every extension on disk with Remove, including ones added by hand or whose repository has since been removed. It compares APK and repository version codes, enables Update only for newer builds, marks current extensions as Up to date, and offers Update all when multiple updates are waiting.
+- Added `anime.repos`, `anime.extensionsDir`, `anime.preferredQuality`, and `anime.defaultSource` config keys; **Set default** on an Installed row in the Extensions tab makes that source (or All sources) the one the browser opens on, and the current default carries a tag. SubMiner ships no extension repositories and performs no discovery.
+- The settings app now groups Anime Browser config under an **Aniyomi** section in Integrations. A new `anime.autoOpenJimaku` option pauses newly loaded Anime Browser episodes, waits for mpv's video window to appear, closes the in-player browser, hides the standalone browser window so it is not pulled in front of mpv when the modals close, opens Jimaku with the episode details filled in, and resumes after a subtitle loads or the modal closes without overriding playback that was already paused.
+- Anime playback targets Japanese audio: dub-labelled entries are skipped when the source offers an alternative, `alang` prefers Japanese, and the source's own audio and subtitle tracks are loaded into mpv (Japanese selected) instead of being discarded, so all of them can be switched from mpv's track menu.
+- The primary subtitle slot stays reserved for Japanese: a source that only has, say, English subtitles gets them added with a normalized language tag (`English` → `en`) but not selected, so the regular `secondarySub` auto-load can route them to the secondary slot instead.
+- HLS streams pass through a local strip proxy that removes fake image headers some hosts glue onto their video segments and gives disguised segment URLs (`.image`, `.jpg`, `.css`, and other rotating fake extensions) a media-safe local alias, so those streams play in mpv and support Anki audio and image extraction with current ffmpeg releases. Upstream responses use identity encoding so playlists remain readable for URL rewriting.
+- The strip proxy retries a failed segment fetch once after a short pause and logs upstream error statuses; a host that errors on the very first fetches right after an episode resolves no longer kills the whole playback, disconnecting clients release their active upstream fetch instead of consuming the socket and bandwidth in the background, stalled response bodies retain the upstream inactivity timeout, and only origin-form requests can reach the configured local bridge.
+- The strip proxy no longer forwards `Range` headers to the bridge: ffmpeg opens every HLS segment with `Range: bytes=0-`, the bridge answers some of those with 206, and a partial response bypassed the disguise strip, so whether an episode played depended on the bridge's cache state.
+- A bridge that dies out from under the app (killed, crashed, or stopped mid-operation) no longer leaves the browser failing every request until an app restart: the exit is detected, surfaced in the status bar, and the bridge restarts on the next request.
+- "Playing" is only reported once mpv actually configures a video output; slow streams remain loading while mpv opens them, and failed streams show mpv's error.
+- The bridge bundle is downloaded from the newest upstream release that ships a bundle for the platform (skipping releases older than the oldest server SubMiner is known to work with), the same way Mangatan fetches it, so all four published bundles (macOS arm64 and x64, Linux x64, Windows x64) work without a maintainer hashing each one first.
+- The Extensions tab's available list has a language chip row: pick one or more languages to narrow a repository index that otherwise lists every language it knows, or "All" to clear the filter. Rows name the language ("Japanese" instead of `ja`) and the Available heading counts what the filter leaves.
+- A stream's subtitle tracks are downloaded to a temp directory and loaded into mpv as files rather than streamed from the source URL, so they can serve as the alass reference in Subsync the way Jellyfin subtitles do. The format is detected from the file's own content, a track that fails to download falls back to its URL so the episode still plays, and the directory is removed when the next episode starts or the app exits.
+- An episode launched from the browser carries its series, season and episode number through the app instead of a single joined string: stats group by series (every stream previously landed in one entry named `m3u8`), rewatching reuses the existing entry, the Jimaku and TsukiHime modals prefill Title/Season/Episode from the source's own listing, AniList updates use those fields directly, and the mpv title reads `Series S03E04 - Episode Name`.
+- Opening the browser shows a tray icon on every platform and — on macOS — puts the app in the Cmd+Tab switcher and Dock, so you can switch between it and mpv; the Dock icon is released again when the window closes during playback. Launching a video starts a regular SubMiner session, and in `subminer anime` standalone mode closing the window during playback no longer quits the app and kills the stream.
+- The episode list has a filter box: type an episode number (`12`), a range (`12-18`), or part of an episode name to narrow a long list, with a `6 of 25` counter while it is applied. Escape inside the box clears the filter instead of leaving the detail page.
+- Episodes already watched are dimmed and marked in the episode list, with a watched count in the header. The marks come from the stats history playback already writes (an episode is marked once a session passes the completion threshold), so they match the stats window and survive the stream URL changing between playbacks. They refresh when the browser window comes back to the front, and stay empty when immersion tracking is disabled.
+- Right-clicking an episode opens a menu for marking it watched or unwatched by hand, plus "Mark this and N below watched/unwatched" for the episode and every episode listed under it. Sources list newest first, so a span covers the back catalogue, which is how a series watched elsewhere gets caught up. A filter never narrows what a span covers, and the status bar reports how many episodes were touched.
+- Marking an episode that was never played creates its stats row, carrying the same series, season and episode fields playback would have recorded. Both stats library views join the lifetime tables, so a manual mark does not show up there as watch time nobody spent, and clearing a mark creates nothing.
+- Episodes can be queued instead of replacing what is playing. Every episode row has **Play** and **Queue** buttons (clicking the row still plays now), the right-click menu offers the same two, and a queued episode shows its place in line ("next up", "#2 in queue") with a queue count and **Clear queue** in the episode header. The queue spans anime, resolves and appends each episode to mpv's real playlist as soon as it is queued while subtitle tracks cache in the background, so next/previous navigation works immediately and the next episode starts without a resolution pause when the current one ends. Queueing with nothing playing just plays.
+- Added an in-player Anime Browser modal on `Ctrl+Alt+A`. The shortcut toggles it without losing its page or scroll position. It stays within the player bounds and shares the active episode, playback queue, source configuration, and watch history with the standalone browser, while each surface keeps independent search and navigation state. The modal validates its embedded page before changing overlay state, so a load setup failure leaves it closed rather than revealing a broken modal. The SubMiner logo identifies the Anime Browser in both the modal and standalone window.
+- The bridge is reused from a package-manager install when one exists: on Arch the AUR `mangatan-extension-server` package (shared with Mangatan) is picked up from `/usr/share/mangatan/extension_server`, so nothing is downloaded and pacman keeps it current. `anime.bridgeDir` points SubMiner at a bundle anywhere else. `subminer-bin` lists the package as an optional dependency.
+- Once the bridge is running, SubMiner checks GitHub for a newer release, including for AUR and custom installations. AUR update notices direct users to their AUR helper; custom installs get manual-update guidance. Only SubMiner-managed copies offer an **Update to vX** button. The new release is downloaded beside the running bridge, then the bridge restarts on it. The updater waits for a bridge still starting to stop and keeps the previous bundle until the replacement is active. The Extensions tab shows the bridge version, where it lives, and who updates it without describing an unchecked install as current.
+- The detail page keeps its episode list when only the details call fails: the episodes render with a "Details unavailable" note and the error in the status bar, instead of an empty page.

changes/anime-playback-loading-docs.md

@@ -0,0 +1,4 @@
+type: docs
+area: anime
+
+- Document how the anime browser waits for slow streams to start without reporting a premature playback failure.

changes/anime-stream-subtitle-generation-docs.md

@@ -0,0 +1,5 @@
+type: docs
+area: subtitles
+
+- Document anime stream generation, audio-only and lower-resolution extraction candidates, concurrent HLS downloads, temporary disk usage, audio cache reuse and limits, full-episode processing, supported audio tracks, and stream access limitations.
+- Explain HLS source-check diagnostics and session-only audio cleanup on quit and after crashes.

changes/anime-stream-subtitle-generation.md

@@ -0,0 +1,6 @@
+type: added
+area: subtitles
+
+- Generate Japanese subtitles from finite HTTP/HTTPS anime episode streams in the existing generation modal. Reuse mpv's supported request headers and the anime proxy, transcribe downloaded audio locally, retain generated SRT files in the application cache, and load them only into the matching stream. Local-file generation and the launcher keep their existing behavior.
+- Prepare plain HLS episodes with up to four concurrent segment downloads, preserving audio order and timing. Show download progress, cancel active requests together, and retain FFmpeg extraction for complex playlists.
+- Reduce anime-stream extraction downloads by preferring separate Japanese audio or lower-resolution video when duration and sampled audio match playback. Sample HLS through short local segment windows, account for timestamp origins, retry empty original samples, and report why candidates are rejected. Selected external HTTP audio tracks are extracted directly with their playback delay preserved. Reuse verified completed audio across transcription retries and model changes within the current app session. Remove downloaded audio and working files on quit, recover abandoned sessions on startup, and preserve saved subtitles.

changes/bundled-bun-runtime-docs.md

@@ -0,0 +1,5 @@
+type: docs
+area: launcher
+
+- Documented private-runtime launcher installation, simplified first-run setup, custom app locations, legacy launcher migration, and package-managed updates. Updated release-note download guidance for the bundled runtime and Windows launcher.
+- Documented the bundled Bun runtime's MIT and LGPL licensing, where the notices live in the app, and the corresponding-source release asset. The AUR package now lists the bundled runtime licenses and installs their notices under `/usr/share/licenses/subminer-bin`, and `subminer-assets.tar.gz` includes the same notices.

changes/bundled-bun-runtime.md

@@ -0,0 +1,5 @@
+type: changed
+area: launcher
+
+- Made every installed and downloadable launcher use the Bun runtime included with SubMiner. Added a Windows `subminer.cmd` download, persistent private runtime caches for Linux and Windows, and migration for recognized legacy launchers. Deferred migrations survive overlapping update checks and remain pending when startup cannot safely refresh the launcher.
+- Simplified first-run setup to a single optional launcher control, with runtime repair guidance shown only when needed.

changes/character-dictionary-without-subtitles-docs.md

@@ -0,0 +1,4 @@
+type: docs
+area: subtitles
+
+- Clarify that character dictionary sync works without a subtitle track and explain readiness and import timeouts.

changes/character-dictionary-without-subtitles.md

@@ -0,0 +1,4 @@
+type: fixed
+area: subtitles
+
+- Let character dictionaries finish syncing when no Japanese subtitles are loaded. Wait for Yomitan extension readiness instead of the first processed subtitle, and report readiness failures instead of leaving the notification stuck on Checking.

changes/ci-test-deduplication.md

@@ -0,0 +1,4 @@
+type: internal
+area: ci
+
+- Removed duplicate source and launcher smoke executions from the reusable quality gate while preserving every distinct test lane and failure artifact.

changes/compiled-runtime-smoke.md

@@ -0,0 +1,4 @@
+type: internal
+area: verification
+
+- Replaced mislabeled dist source reruns with a small Electron-runtime smoke check for compiled stats startup, HTTP service, native SQLite, port conflicts, and cleanup.

changes/compressed-incremental-sync.md

@@ -0,0 +1,6 @@
+type: changed
+area: sync
+
+- Sync uses compressed, incremental rsync transfers on compatible macOS and Linux machines, caching the last received snapshot per peer to reduce traffic on subsequent syncs. Cache helpers work through the launcher; older apps and launchers fall back to compressed transfers without an upload cache.
+- Machines without compatible rsync, including Windows endpoints, automatically use compressed scp transfers.
+- Rsync explicitly uses SSH and aborts transfers that exceed 30 minutes before merging.

changes/e2e-harness.md

@@ -1,4 +0,0 @@
-type: internal
-area: testing
-
-- Added a headless end-to-end harness (`bun run test:e2e`, `bun run e2e`) that boots the built app with a real mpv, a synthetic clip, a fixture Yomitan dictionary, and a fake AnkiConnect on an offscreen display.

changes/fix-animated-word-audio-sync.md

@@ -0,0 +1,4 @@
+type: fixed
+area: anki
+
+- Added `ankiConnect.fields.wordAudio` to read word audio separately from the generated sentence-audio destination, fixing animated images that start moving immediately when `fields.audio` points to `SentenceAudio`.

changes/fix-anki-config-validation.md

@@ -0,0 +1,4 @@
+type: fixed
+area: config
+
+- Validate direct AnkiConnect, Kiku, and Senren settings before admitting them to runtime config, with warnings and defaults for invalid values.

changes/fix-cleanup-and-tsukihime-callbacks.md

@@ -0,0 +1,5 @@
+type: fixed
+area: runtime
+
+- Shutdown finishes independent media and Discord cleanup and waits for sync shutdown even when Jellyfin cleanup fails, then reports the first cleanup error.
+- Tsukihime ignores delayed media-info results and errors from a closed modal session.

changes/fix-first-launch-config-directory.md

@@ -0,0 +1,4 @@
+type: fixed
+area: startup
+
+- Fixed first launch exiting on macOS when the SubMiner config directory did not yet exist by creating it before acquiring the startup lock.

changes/fix-jellyfin-media-identity.md

@@ -0,0 +1,7 @@
+type: fixed
+area: jellyfin
+
+- Set the mpv title before loading Jellyfin streams and reject URL-derived titles from metadata lookups, Anki source fields, Discord presence, and stats.
+- Keep authenticated stream URLs out of stats identities even when playback metadata has not arrived.
+- Remove previously cached credential-bearing Jellyfin stream parser metadata without changing unrelated anime metadata, watch history, or library assignments.
+- Use safe media identities for persisted AniList retry keys, discard URL-derived queued searches, and skip updates and retries whose media identity is empty.

changes/fix-sidebar-space-seek.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Clicking a subtitle sidebar cue releases row focus, and Space no longer seeks back to a focused cue. Enter still seeks the focused cue, and Space keeps its configured playback action.

changes/fix-stats-resource-id-validation.md

@@ -0,0 +1,4 @@
+type: fixed
+area: stats
+
+- Reject malformed resource IDs and partly invalid ID lists before stats library mutations or cover backfills run.

changes/fix-stats-server-lifecycle.md

@@ -0,0 +1,5 @@
+type: fixed
+area: stats
+
+- Stats server startup reports port conflicts without crashing SubMiner, shares concurrent startup requests, and shows in-app startup errors through configured status notifications.
+- Background stop cancels pending background startup without disconnecting foreground-only dashboards. Shutdown bounds the wait for active HTTP requests and awaits tracker finalization before exit, with a deadline for forced application exit.

changes/fix-timing-review-cancellation.md

@@ -0,0 +1,4 @@
+type: fixed
+area: anki
+
+- Closing the overlay while media timing review is still loading now cancels setup and modal retries, restores playback if the review paused it, and cleans up the hidden preview player.

changes/fix-timing-review-playback-hold.md

@@ -1,4 +0,0 @@
-type: fixed
-area: anki
-
-- Media timing review now keeps playback paused while it is open when the dictionary popup or subtitle hover pause ends, as with Hachidori popups closing when the review appears. Playback resumes after the review closes unless a dictionary popup is still open.

changes/fix-unlimited-mining-duration.md

@@ -0,0 +1,4 @@
+type: fixed
+area: anki
+
+- Treat `ankiConnect.media.maxMediaDuration: 0` as unlimited for stats dashboard mining, matching overlay mining and configuration.

changes/hachidori-backend.md

@@ -1,15 +0,0 @@
-type: added
-area: dictionary
-
-- Added a bundled Hachidori dictionary backend alongside the default Yomitan backend. Select it with `dictionaryBackend` and restart SubMiner.
-- The tray and dictionary-settings shortcut follow the selected backend. `--hachidori` opens Hachidori settings, while `--yomitan` opens Yomitan settings unless a read-only external Yomitan profile is configured. This restriction also applies with Hachidori active, without blocking Hachidori settings.
-- Hachidori integrates with subtitle scanning, popup controls, lookup tracking, character dictionaries, and Anki media enrichment, with separate dictionaries and settings for each backend. Character dictionaries reach a linked host over the link (Hachidori 0.2.3 or later, or a current Docker host), retry busy imports, and replace the previous dictionary only after a successful import. Older hosts report where to import the dictionary manually.
-- Hachidori auto-populates its first Anki template from SubMiner's deck, tags (kept alongside its own `hachidori` tag), and field mappings, detects an unambiguous matching note type, and preserves existing custom templates apart from the deck, which follows `ankiConnect.deck` so polling mode enriches Hachidori cards. Anki discovery retries after an unavailable connection.
-- Hachidori saves downloadable word audio before sending a note through SubMiner's Anki proxy, so freshly mined animated cards include the word-audio delay.
-- Both bundled dictionary backends reload their background code on startup so extension updates take effect while preserving installed dictionaries and settings. Failed Yomitan connection-setting updates can be retried without manually resetting the managed Anki endpoint.
-- First-run setup remembers each backend that finished it, including when reopened for legacy plugin cleanup, so switching back does not repeat setup, and the launcher gates playback on the backend the running app started with. Current incomplete or cancelled setup takes precedence over stale completion history. A running Yomitan session keeps using its external profile until it restarts into Hachidori.
-- Stats dashboard mining and deck lookup use the selected backend, with the Anki proxy enabled or disabled. Dashboard cards retain the selected history line and media instead of being processed again with the current mpv subtitle, with both Yomitan and Hachidori. Stats cards carry a `SubMiner::Stats` tag so polling also preserves their context. Hachidori word mining supplies dictionary aliases, IDs, and frequency metadata to its native Anki renderer. Settings labels for popup pause and the dictionary deck no longer name Yomitan, and the backend selector sits with the other dictionary settings.
-- Hachidori scans, dictionary counts, and settings reads wait for the dictionary engine to finish loading or importing instead of caching empty results.
-- Character dictionary imports report completion as soon as the archive is read instead of waiting out the temporary server's keep-alive timeout.
-- First-run setup can link an external Hachidori dictionary host in an app, browser, or Docker container, verify its library, and unlink back to local dictionaries. The optional host controls are collapsed by default and explain which apps or containers must stay running. Unresponsive connection checks time out so setup remains usable. Anki mining, media enrichment, and custom toolbar buttons stay in SubMiner, including when editing buttons while linked.
-- Hachidori frequency highlighting reuses dictionary-entry ranks and fills missing ranks through its existing API. Entries without a matching definition may remain unranked. The bundled integration is maintained in a pinned fork submodule using upstream HoshiDicts and WASM binaries.

changes/hachidori-setup-docs.md

@@ -1,4 +0,0 @@
-type: docs
-area: dictionary
-
-- Documented backend selection, separate Hachidori dictionary and Anki setup, the settings flags and shortcuts, and external host linking with local Anki mining and the running requirements for each host type.

changes/hyprland-recovery-dialog.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Keep Hyprland recovery dialogs above SubMiner windows so overlay placement updates do not cover their Wait and Close buttons.

changes/japanese-subtitle-generation-docs.md

@@ -0,0 +1,5 @@
+type: docs
+area: subtitles
+
+- Explain how dialogue generation retains uncertain audible sections, why songs may also be transcribed, how detected speech starts guide long-passage cuts to reduce early subtitles, and why each passage uses a fresh Whisper process.
+- Document automatic loaded subtitle references, English dialogue preference, signs/songs filtering, fallback behavior, and the limits of reference-guided timing.

changes/japanese-subtitle-generation.md

@@ -0,0 +1,8 @@
+type: added
+area: subtitles
+
+- Generate local Japanese SRT subtitles with whisper.cpp from a standalone modal opened with Ctrl+Shift+G, the empty subtitle sidebar's generation button, or `subminer generate-subs`, with shared progress reporting, cancellation, safe output files, and automatic loading into the matching mpv video. The sidebar button hides while subtitle lines are loaded.
+- Configure an existing multilingual model in Settings or choose an official multilingual model, including quantized variants, in the modal or launcher. The modal shows download sizes, speed and accuracy guidance, and a recommended starting model before explicitly downloading a verified SubMiner-managed model. Executable paths are optional overrides; empty fields find whisper-cli, ffmpeg, and ffprobe on PATH. The modal's Local tools check and the launcher name any missing executable and its setting before downloading a model or extracting audio, and generation confirms the destination directory grants write and search permissions up front.
+- Optionally select Focus on spoken dialogue in the modal and use Download speech detection model to install the separate Silero model with progress and cancellation. The choice lasts for the session; a configured VAD model path sets the default. Retain uncertain audible sections so VAD rejection does not discard dialogue under music, accepting that songs may also be transcribed. Keep passages intact within Whisper's audio window, split longer passages near detected speech starts or quiet pauses with overlapping context to reduce early subtitle timing, and combine overlapping duplicate cues even when punctuation differs. Run each passage in a fresh Whisper process to prevent repeated-character output caused by state carried between files, at the cost of reloading the model per passage. Preserve original media timing and separate repeated dialogue.
+- Recommend large-v3-turbo in the model picker when NVIDIA hardware and CUDA device support in the selected Whisper executable are confirmed; recommend small otherwise. Preserve configured and session model selections. Use a wider generation modal to reduce text wrapping and scrolling, while keeping it within smaller player windows.
+- Automatically use an eligible embedded or external subtitle track loaded in mpv to guide long-passage cuts, preferring English dialogue and excluding tracks marked signs, songs, forced, or generated. Honor active subtitle delays, retain unreferenced audio, and fall back to audio timing when references cannot be read. Available in the overlay and launcher, with or without VAD. The launcher captures audio selection, reference tracks, and delays before model setup so playback changes during a download do not mix inputs from different times, and rejects an unverified media snapshot before using mpv's selected audio stream.

changes/jellyfin-cli-running-app.md

@@ -1,7 +0,0 @@
-type: fixed
-area: jellyfin
-
-- Fixed `subminer jellyfin -p` reporting "No Jellyfin libraries found." when SubMiner was already running (for example right after `subminer jellyfin` login). The app now hands library, item, and preview-auth results to the launcher directly instead of through log files, so picker image previews work again and real errors (expired session, unreachable server) are shown instead of an empty list.
-- The rofi "Jellyfin Search (optional)" step after picking a library is now a compact input box with a "Type to search, or press Enter to browse all" hint instead of a blank list.
-- Playing from the terminal (`subminer jellyfin -p`) now reports watch progress to Jellyfin even when cast discovery is off, so Jellyfin remembers where you stopped and marks finished episodes as played. Previously progress was only sent while the cast connection was active.
-- When `subminer jellyfin -p` has to start SubMiner itself, the app now shows its tray icon and quits when you close mpv, the same as playing a local file. Before, it had no tray icon and kept running hidden after playback. A SubMiner that was already running is still reused and left running.

changes/jellyfin-media-identity-docs.md

@@ -0,0 +1,5 @@
+type: docs
+area: jellyfin
+
+- Explain how Jellyfin media titles, unknown-title fallbacks, and stats identities keep stream credentials out of metadata.
+- Document AniList rejection of empty media identities and the conditions for clearing cached Jellyfin parser metadata.

changes/jellyfin-startup-connect-docs.md

@@ -1,4 +0,0 @@
-type: docs
-area: jellyfin
-
-- Corrected the Jellyfin docs: SubMiner only joins the cast menu at startup when `startupWarmups.jellyfinRemoteSession` is on (off by default) along with `jellyfin.remoteControlAutoConnect`. Otherwise tick **Jellyfin Discovery** in the tray.

changes/jellyfin-subtitle-generation.md

@@ -1,4 +0,0 @@
-type: added
-area: subtitles
-
-- Japanese subtitle generation now works while playing a Jellyfin episode. SubMiner reads the original file from the server, saves the subtitles to a cache folder, and loads them into mpv. Direct-play and transcoded playback are both supported.

changes/jimaku-live-action-search.md

@@ -0,0 +1,4 @@
+type: added
+area: jimaku
+
+- Jimaku modal gains Anime / Live action tabs so searches can pull from Jimaku's live action catalogue instead of only anime entries (Arrow Left / Right switch tabs).

changes/keyboard-mode-modal-input.md

@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
-- Keyboard-only mode no longer swallows `h`, `l`, and the left/right arrows while a modal is open or a text field has focus, so typing into fields like the Jimaku or TsukiHime title works and no longer seeks mpv. Pressing `Ctrl/Cmd+Shift+Y` (or the controller toggle) inside a modal no longer turns on a hidden keyboard-only mode in the modal window.

changes/linux-overlay-content-ready-fallback.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed the overlay never loading (stuck on the "Overlay loading" OSD spinner) when the Yomitan content-script reload raced overlay window creation at startup, most visible when playing from the anime browser on Linux/Wayland: a hidden window stops painting after that reload, so the ready-to-show signal that gates showing the overlay never fired. Content-ready now falls back to did-finish-load after a short grace period.

changes/macos-login-shell-path.md

@@ -1,4 +0,0 @@
-type: fixed
-area: setup
-
-- Fixed the command-line launcher showing "Not on PATH" on macOS when SubMiner was opened from Finder or the Dock, even though the launcher directory was already on your terminal PATH.

changes/macos-window-activation.md

@@ -0,0 +1,4 @@
+type: fixed
+area: macos
+
+- `subminer anime` (and `--settings` / `--sync`) now bring their window to the front on macOS. `show()`/`focus()` only reorder windows inside the app that is already active, so the window opened behind the terminal that launched it; SubMiner now activates itself when opening one. The anime browser also restores its Dock icon before showing rather than after, because the overlay's fullscreen transform leaves the app as an accessory process that macOS refuses to bring forward at all.

changes/media-review-frame-picker-docs.md

@@ -0,0 +1,4 @@
+type: docs
+area: mining
+
+- Document independent screenshot selection in media timing review.

changes/media-review-frame-picker.md

@@ -0,0 +1,4 @@
+type: added
+area: mining
+
+- Choose a still screenshot independently of the audio in media timing review, with a live preview, a separate time slider, and decoded-frame stepping. Local video and seekable remote streams such as Jellyfin are supported.

changes/mpv-overlay-bindings.md

@@ -0,0 +1,4 @@
+type: added
+area: overlay
+
+- The overlay discovers non-conflicting keyboard bindings from mpv defaults, input.conf, and loaded scripts in the background. SubMiner controls and explicitly disabled bindings take precedence. Discovered bindings stay session-only and do not appear in SubMiner's help menu.

changes/overlay-modal-first-open.md

@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
-- Overlay modals such as the media timing review open on the first attempt when their dedicated window is created on demand, instead of after a four-second retry.

changes/package-size-cleanup.md

@@ -0,0 +1,5 @@
+type: changed
+area: release
+
+- Reduced installer and unpacked app size by excluding documentation demo media, dependency source maps, TypeScript files, test and fixture directories, other development files, and unused Koffi platform binaries, and sharing the existing Japanese UI font across windows.
+- Added package content checks, published size reports with release comparisons, and packaged asset/native-module smoke checks to the shared stable and prerelease build workflow. Size growth is reported without blocking releases.

changes/prefetch-startup-restarts.md

@@ -1,5 +0,0 @@
-type: fixed
-area: annotations
-
-- Subtitle lines shown while two cues overlap (common in Jimaku and Jellyfin SRTs, and usually the long lines) are now prefetched, so their annotations appear immediately instead of after a delay.
-- Subtitle prefetching no longer restarts each time the same subtitle file is re-selected during startup, and a line tokenized before a restart or seek is kept instead of discarded.

changes/remove-dead-code-docs.md

@@ -1,4 +0,0 @@
-type: docs
-area: launcher
-
-- Removed `SUBMINER_JIMAKU_API_KEY`, `SUBMINER_JIMAKU_API_KEY_COMMAND`, and `SUBMINER_JIMAKU_API_BASE_URL` from the development docs' environment variable table. The launcher never used them; set the Jimaku key with `jimaku.apiKey` / `jimaku.apiKeyCommand` in the config instead.

changes/remove-dead-code.md

@@ -1,5 +0,0 @@
-type: internal
-area: cleanup
-
-- Removed dead code: the unused launcher Jimaku client (the `SUBMINER_JIMAKU_*` env vars it read were documented but had no effect), the mpv plugin's hover-highlight module (no sender since Overlay 2.0; custom mpv scripts that still send `subminer-hover-token` or `yomipv-hover-token` are now ignored), the never-read `anilist.characterDictionary.refreshTtlHours` / `evictionPolicy` config keys, unused root dependencies (eslint, geist fonts), and a committed draft plan doc.
-- Typecheck now runs with `noUnusedLocals`; removed the unused locals, imports, and the Windows overlay focus-handoff values they fed, which were computed but never used.

changes/remove-dead-ipc.md

@@ -1,4 +0,0 @@
-type: internal
-area: overlay
-
-- Removed 16 overlay preload/IPC methods that nothing called, plus their main-process handlers. SubMiner no longer observes mpv's `sub-text/ass` or sends every ASS line to overlay windows that never listened.

changes/runtime-ownership.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Cancel pending Linux overlay window replacements during teardown so a delayed close callback cannot reopen the overlay.

changes/settings-live-save-feedback-docs.md

@@ -0,0 +1,4 @@
+type: docs
+area: config
+
+- Clarified live-setting save feedback, mixed restart warnings, and subtitle-generation reload behavior.

changes/settings-live-save-feedback.md

@@ -0,0 +1,5 @@
+type: fixed
+area: config
+
+- Settings marked LIVE now use the same reload policy as save results, fixing false restart warnings for notifications and subtitle generation.
+- Mixed saves apply live changes and list only sections with changed fields that require a restart.

changes/setup-launcher-badge-label.md

@@ -1,4 +0,0 @@
-type: fixed
-area: setup
-
-- First-run setup now labels a missing command-line launcher "Not set up" instead of "Not installed", so the AppImage catalog test no longer reads the setup window as an error screen.

changes/sidebar-selection-copy.md

@@ -0,0 +1,4 @@
+type: added
+area: overlay
+
+- Select dialogue across subtitle sidebar rows and copy it without timestamps using Ctrl/Cmd+C or the Copy button. Selection keeps the excerpt in view during playback and does not seek or require mining a card.

changes/sidebar-snapshot-poll.md

@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
-- The open subtitle sidebar no longer re-fetches the whole subtitle list and re-queries mpv about 12 times a second. It polls only the current time and line, and reloads the list when the subtitle track, file, or parsed cues change (plus a slow ~2 s fallback), cutting idle sidebar IPC and renderer work during playback.

changes/stats-request-safety.md

@@ -0,0 +1,6 @@
+type: changed
+breaking: true
+area: stats
+
+- Reject requests from untrusted browser origins and hosts before stats data, media, or Anki operations run, and require JSON for mutation bodies.
+- Load the in-app stats overlay from the local server so it uses the same origin protection as the browser dashboard.

changes/stats-widen-halfwidth-kana.md

@@ -1,5 +0,0 @@
-type: fixed
-area: stats
-
-- Subtitle lines recorded before halfwidth katakana widening now show fullwidth katakana in the stats dashboard (word/kanji occurrences, sentence search), and cards mined from stats history get the fullwidth sentence and word.
-- Sentence search matches katakana in either width, so searching アンタ also finds older lines stored as ｱﾝﾀ.

changes/subsync-file-url-tracks.md

@@ -0,0 +1,4 @@
+type: fixed
+area: subsync
+
+- Subsync no longer fails with `Protocol "file:" not supported` on a subtitle that was dropped onto mpv. mpv reports such a track as a percent-encoded `file://` URL, which subsync read as a stream and tried to fetch over HTTP; the URL is now decoded back to its path, so both the retimed target and an alass reference work. A `file://` video path is treated as local too, which restores the video reference and ffsubsync for a dropped file.

changes/subsync-stream-tracks.md

@@ -0,0 +1,7 @@
+type: fixed
+area: subsync
+
+- Subsync now works when mpv loaded a subtitle track from a URL, which is how Aniyomi extension streams and Jellyfin add theirs. The track is downloaded to a temporary file first — reusing mpv's own request headers, so authenticated and referer-gated hosts stay reachable — instead of being rejected with "Subtitle file not found: https://…". This applies to both the sync target and the alass reference, so a Jimaku or TsukiHime download can be retimed against a stream's own subtitles. Internal tracks of a stream also pass mpv's headers through to `ffmpeg`.
+- Alass now works on tracks that arrive as WebVTT, which is what Aniyomi extension streams serve. Alass picks its parser from the file extension and has no WebVTT support, so it treated a `.vtt` reference as a video file and failed with "no audio stream in file". Both the target and the reference are rewritten as SRT for alass, keeping the cue text as-is, and the originals are left untouched.
+- Leaving `subsync.alass_path`, `ffsubsync_path`, or `ffmpeg_path` empty now actually auto-discovers the binary, as the config help has always claimed. Previously it fell back to a hard-coded `/usr/bin/<tool>`, which does not exist on macOS and broke subsync for every default-config install there. Discovery searches `PATH` plus the usual install prefixes (a GUI launch inherits a minimal `PATH`) and accepts `alass-cli` as well as `alass`. An explicitly configured path is still used verbatim and never silently substituted.
+- Subsync failures are written to the application log. Previously the only trace was an OSD toast that vanished after a few seconds, leaving nothing to diagnose from.

changes/subtitle-sidebar-gap-follow.md

@@ -0,0 +1,4 @@
+type: fixed
+area: subtitles
+
+- Keep the subtitle sidebar near playback during gaps when the subtitle file has a cue starting at zero.

changes/sync-transfer-docs.md

@@ -0,0 +1,4 @@
+type: docs
+area: sync
+
+- Documented compressed transfers, incremental sync cache storage, and compatibility with older peers.

changes/tmdb-linking-docs.md

@@ -0,0 +1,4 @@
+type: docs
+area: stats
+
+- Documented provider reassignment, merge compatibility, and TMDB credential command caching and retry cooldown.

changes/tmdb-live-action-library.md

@@ -0,0 +1,8 @@
+type: added
+area: stats
+
+- Live-action dramas and movies in the stats Library now get posters, synopses, and titles from TMDB. Release builds include a project key, so it works out of the box; `tmdb.apiKey` (or `tmdb.apiKeyCommand`) overrides it, and is required when running from source.
+- Unlinked titles that AniList cannot match are looked up on TMDB automatically when the parsed filename matches a Japanese live-action title exactly; otherwise use the new **Link to TMDB** action on a title to pick it by hand.
+- Entries linked to the same TMDB title are merged into one card even when they came from different season folders, and the Library kind selector gained a Live Action option alongside Anime and YouTube.
+- Provider reassignment preserves the previous link and artwork if the replacement download fails, and refreshes completion totals when the episode count changes. Merges and sync keep conflicting AniList and TMDB identities separate, and the merge dialog explains when a selection mixes the two instead of failing.
+- TMDB credential commands cache successful output and wait 30 seconds before retrying failed or empty output, using the bundled key in the meantime when available.

changes/tracker-async-poll.md

@@ -1,5 +0,0 @@
-type: fixed
-area: overlay
-
-- Hyprland and Sway window tracking no longer freezes the app when `hyprctl` or `swaymsg` is slow or hangs: polls now run in the background with a timeout and no longer pile up.
-- The Hyprland/Sway trackers read each mpv process's command line once instead of spawning `ps` on every poll.

changes/widen-halfwidth-kana.md

@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
-- Halfwidth katakana in subtitles (common in broadcast-derived Japanese subs, e.g. ｱﾝﾀ, ﾀﾞｷﾆ) now displays as normal fullwidth katakana, so lines no longer mix squashed and normal-width text. Mined sentences and stats get the fullwidth form too.

changes/word-audio-mapping-docs.md

@@ -0,0 +1,4 @@
+type: docs
+area: anki
+
+- Documented the separate word-audio mapping for animated-image synchronization and that existing images need regeneration to pick up the corrected freeze.

changes/yomitan-upstream-26-9-8.md

@@ -0,0 +1,4 @@
+type: changed
+area: yomitan
+
+- Updated bundled Yomitan with upstream 26.9.8 changes, including historical Japanese kana transformations, Ukrainian language support, and improvements to Anki duplicate searches and audio retrieval.

changes/youtube-library-kind-docs.md

@@ -0,0 +1,4 @@
+type: docs
+area: stats
+
+- Document YouTube channel filtering and video statistics in the Library.

changes/youtube-library-kind.md

@@ -0,0 +1,7 @@
+type: added
+area: stats
+
+- Store YouTube channels as a separate media kind and migrate existing channel entries without changing viewing history or manual video assignments, including channels created after temporarily returning to an older build.
+- Add All Titles, Anime, and YouTube Library filters, identify channel pages, and keep channels out of AniList matching, season repair, and duplicate recommendations.
+- Keep same-title anime and YouTube records separate in storage and sync while repairing legacy channel classification.
+- Refuse merges and video moves that would mix an anime entry with a YouTube channel; the move picker and merge selection only combine entries of the same kind.

config.example.jsonc

@@ -6,22 +6,6 @@
  */
 {
 
-  // ==========================================
-  // Dictionary Backend
-  // Select the dictionary lookup backend: yomitan or hachidori.
-  // Restart SubMiner after changing the backend. Each backend keeps separate settings and dictionaries.
-  // ==========================================
-  "dictionaryBackend": "yomitan", // Dictionary lookup backend. Restart SubMiner after changing this setting. Values: yomitan | hachidori
-
-  // ==========================================
-  // Subtitle Selection
-  // Select primary and secondary mpv subtitle tracks from the overlay.
-  // Hot-reload: enabling or disabling updates the session shortcut immediately.
-  // ==========================================
-  "subtitleSelection": {
-    "enabled": false // Use the SubMiner modal to select primary and secondary subtitle tracks. When enabled, its shortcut overrides mpv subtitle selection. Values: true | false
-  }, // Select primary and secondary mpv subtitle tracks from the overlay.
-
   // ==========================================
   // Japanese Subtitle Generation
   // Generate timed Japanese subtitles from local audio using whisper.cpp.
@@ -239,7 +223,6 @@
     "openRuntimeOptions": "CommandOrControl+Shift+O", // Accelerator that opens the runtime options modal.
     "openJimaku": "Ctrl+Shift+J", // Accelerator that opens the Jimaku subtitle search modal.
     "openTsukihime": "Ctrl+Shift+T", // Accelerator that opens the TsukiHime subtitle search modal (configured secondary/Japanese primary tabs).
-    "openSubtitleSelection": "g-s", // Open subtitle selection when enabled. Use g-s to press g then s. Set null to unbind.
     "openSubtitleGeneration": "Ctrl+Shift+G", // Accelerator that opens the standalone Japanese subtitle generation modal.
     "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
     "openControllerSelect": "Alt+C", // Accelerator that opens the controller selection and learn-mode modal.
@@ -376,6 +359,12 @@
         "__playlist-browser-open"
       ] // Command setting.
     },
+    {
+      "key": "Ctrl+Alt+KeyA", // Key setting.
+      "command": [
+        "__anime-browser-open"
+      ] // Command setting.
+    },
     {
       "key": "Ctrl+Shift+KeyH", // Key setting.
       "command": [
@@ -653,6 +642,21 @@
     } // Lapis kiku setting.
   }, // Automatic Anki updates and media generation options.
 
+  // ==========================================
+  // Anime Browser
+  // Anime browser sources. SubMiner ships no extension repositories and bundles no sources;
+  // add a repository index URL here (or drop .apk files in the extensions directory) to have any.
+  // Hot-reload: autoOpenJimaku applies to the next episode; other anime changes apply the next time the anime browser opens.
+  // ==========================================
+  "anime": {
+    "autoOpenJimaku": false, // Pause Anime Browser playback and open Jimaku when an episode loads. Playback resumes after a subtitle loads or the modal closes only when auto-open initiated the pause. Values: true | false
+    "extensionsDir": "", // Directory holding Aniyomi extension .apk files. Empty uses <userData>/anime-extensions.
+    "repos": [], // Extension repository index URLs (any https .json index, e.g. https://.../index.min.json). Empty by default; SubMiner ships no repositories.
+    "preferredQuality": "", // Preferred stream quality label, matched as a substring (for example: 1080). Empty uses the source order.
+    "defaultSource": "", // Source the Anime Browser selects when it opens: a source id (<package>:<source>) or "all" for every installed source. Empty selects the first installed source. "Set default" in the Extensions tab writes this value.
+    "bridgeDir": "" // Directory holding an M-Extension-Server bundle (java runtime plus server jar) to run instead of the copy SubMiner downloads. Empty checks the package-manager install (Arch: mangatan-extension-server), then <userData>/anime-bridge.
+  }, // Anime browser sources. SubMiner ships no extension repositories and bundles no sources;
+
   // ==========================================
   // Jimaku
   // Jimaku API configuration and defaults.
@@ -689,14 +693,13 @@
   // ==========================================
   // YouTube Playback Settings
   // Defaults for managed subtitle language preferences and YouTube subtitle loading.
-  // Hot-reload: primarySubLanguages and subtitleSource apply to the next YouTube subtitle load.
+  // Hot-reload: primarySubLanguages applies to the next YouTube subtitle load.
   // ==========================================
   "youtube": {
     "primarySubLanguages": [
       "ja",
       "jpn"
     ], // Comma-separated primary subtitle language priority for managed subtitle auto-selection.
-    "subtitleSource": "youtube", // Where primary YouTube subtitles come from. Whisper transcribes the audio locally using the subtitleGeneration settings. Values: youtube | whisper
     "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.

docs-site/.vitepress/config.ts

@@ -1,6 +1,6 @@
 import { spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { extname, join, posix, resolve, sep } from 'node:path';
 import type { DefaultTheme, HeadConfig, TransformContext, UserConfig } from 'vitepress';
 
 const DOCS_HOSTNAME = 'https://docs.subminer.moe';
@@ -14,6 +14,12 @@ const PLAUSIBLE_INIT_SCRIPT = [
 
 type DocsChannel = 'stable-root' | 'stable-archive' | 'main';
 
+type VersionManifest = {
+  latestStable: string;
+  channels: Array<{ label: string; path: string }>;
+  versions: Array<{ version: string; path: string }>;
+};
+
 function optionalEnv(value: string | undefined): string | undefined {
   return value && value !== 'undefined' ? value : undefined;
 }
@@ -26,6 +32,17 @@ const docsSourceDir = optionalEnv(process.env.SUBMINER_DOCS_SOURCE_DIR) ?? proce
 const repoDocsDir = optionalEnv(process.env.SUBMINER_DOCS_REPO_DIR) ?? process.cwd();
 const channel = normalizeChannel(optionalEnv(process.env.SUBMINER_DOCS_CHANNEL));
 const docsVersion = optionalEnv(process.env.SUBMINER_DOCS_VERSION);
+const latestStable = optionalEnv(process.env.SUBMINER_DOCS_LATEST_STABLE) ?? 'v0.18.0';
+const versionManifest = parseVersionManifest(process.env.SUBMINER_DOCS_VERSION_MANIFEST);
+const versionLinkOrigin =
+  optionalEnv(process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN) ?? 'production';
+
+function getLocalArchiveDir(): string {
+  return resolve(
+    optionalEnv(process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR) ??
+      join(docsSourceDir, '..', '.tmp/docs-versioned-site'),
+  );
+}
 
 function normalizeBase(value: string): string {
   if (!value || value === '/') return '/';
@@ -37,6 +54,21 @@ function normalizeChannel(value: string | undefined): DocsChannel {
   return 'stable-root';
 }
 
+function parseVersionManifest(value: string | undefined): VersionManifest {
+  if (!value || value === 'undefined') {
+    return {
+      latestStable,
+      channels: [
+        { label: 'Latest stable', path: '/' },
+        { label: 'main', path: '/main/' },
+      ],
+      versions: [{ version: latestStable, path: `/v/${latestStable.replace(/^v/, '')}/` }],
+    };
+  }
+
+  return JSON.parse(value) as VersionManifest;
+}
+
 function withDocsBase(path: string): string {
   if (/^[a-z]+:\/\//i.test(path)) return path;
   const normalizedPath = path.startsWith('/') ? path : `/${path}`;
@@ -132,16 +164,137 @@ function filterSidebar(items: DefaultTheme.SidebarItem[]): DefaultTheme.SidebarI
     .filter((item): item is DefaultTheme.SidebarItem => Boolean(item));
 }
 
-// Version navigation targets other builds (root, `/main/`, `/versions`), so it links to
-// production by absolute URL: base-relative links would stay inside this build, and
-// `target: '_self'` makes the VitePress router do a full page load. The list is
-// deliberately static; the full release list lives on the root-only `/versions` page
-// so frozen `/v/<version>/` archives never need a rebuild when a new tag ships.
-const versionItems: DefaultTheme.NavItemWithLink[] = [
-  { text: 'Latest stable', link: `${DOCS_HOSTNAME}/` },
-  { text: 'main', link: `${DOCS_HOSTNAME}/main/` },
-  { text: 'All versions', link: `${DOCS_HOSTNAME}/versions` },
-].map((item) => ({ ...item, target: '_self', noIcon: true }));
+function versionSwitchLink(path: string): string {
+  if (/^[a-z]+:\/\//i.test(path)) return path;
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  if (versionLinkOrigin === 'local') return localVersionSwitchLink(normalizedPath);
+  return `${DOCS_HOSTNAME}${normalizedPath}`;
+}
+
+function localVersionSwitchLink(path: string): string {
+  if (base === '/') return path;
+
+  const basePath = base.replace(/\/$/, '');
+  const targetPath = path === '/' ? '/' : path.replace(/\/$/, '');
+  const relativePath = posix.relative(basePath, targetPath) || '.';
+
+  return path.endsWith('/') ? `${relativePath}/` : relativePath;
+}
+
+function shouldHandleLocalVersionRoute(pathname: string): boolean {
+  if (base !== '/' || channel !== 'stable-root') return false;
+  return /^\/main(?:\/|$)/.test(pathname) || /^\/v\/[^/]+(?:\/|$)/.test(pathname);
+}
+
+function contentTypeForPath(path: string): string {
+  switch (extname(path)) {
+    case '.css':
+      return 'text/css; charset=utf-8';
+    case '.gif':
+      return 'image/gif';
+    case '.ico':
+      return 'image/x-icon';
+    case '.jpg':
+    case '.jpeg':
+      return 'image/jpeg';
+    case '.js':
+    case '.mjs':
+      return 'text/javascript; charset=utf-8';
+    case '.json':
+    case '.jsonc':
+      return 'application/json; charset=utf-8';
+    case '.mp4':
+      return 'video/mp4';
+    case '.png':
+      return 'image/png';
+    case '.svg':
+      return 'image/svg+xml';
+    case '.ttf':
+      return 'font/ttf';
+    case '.webm':
+      return 'video/webm';
+    case '.woff':
+      return 'font/woff';
+    case '.woff2':
+      return 'font/woff2';
+    case '.xml':
+      return 'application/xml; charset=utf-8';
+    default:
+      return 'text/html; charset=utf-8';
+  }
+}
+
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function archiveFileForPathname(pathname: string): string | null {
+  if (!shouldHandleLocalVersionRoute(pathname)) return null;
+
+  const localArchiveDir = getLocalArchiveDir();
+  const routePath = decodeURIComponent(pathname).replace(/^\/+/, '');
+  const filePath = resolve(localArchiveDir, routePath);
+  if (filePath !== localArchiveDir && !filePath.startsWith(`${localArchiveDir}${sep}`)) {
+    return null;
+  }
+
+  const candidates = pathname.endsWith('/')
+    ? [join(filePath, 'index.html')]
+    : extname(filePath)
+      ? [filePath]
+      : [`${filePath}.html`, join(filePath, 'index.html')];
+
+  return candidates.find(isFile) ?? null;
+}
+
+function serveLocalArchiveRoute(pathname: string, response: DevServerResponse): boolean {
+  if (
+    (optionalEnv(process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN) ?? versionLinkOrigin) !== 'local'
+  ) {
+    return false;
+  }
+
+  const filePath = archiveFileForPathname(pathname);
+  if (!filePath) return false;
+
+  response.statusCode = 200;
+  response.setHeader('Content-Type', contentTypeForPath(filePath));
+  response.end(readFileSync(filePath));
+  return true;
+}
+
+type DevServerResponse = {
+  statusCode: number;
+  setHeader(name: string, value: string): void;
+  end(chunk?: string | Uint8Array): void;
+};
+
+const versionItems = [
+  {
+    text: `Latest stable (${versionManifest.latestStable})`,
+    link: versionSwitchLink('/'),
+    target: '_self',
+    noIcon: true,
+  },
+  ...versionManifest.channels
+    .filter((entry) => entry.label !== 'Latest stable')
+    .map((entry) => ({
+      text: entry.label,
+      link: versionSwitchLink(entry.path),
+      target: '_self',
+      noIcon: true,
+    })),
+  ...versionManifest.versions.map((entry) => ({
+    text: entry.version,
+    link: versionSwitchLink(entry.path),
+    target: '_self',
+    noIcon: true,
+  })),
+];
 
 function sitemapUrlToPage(url: string): string {
   const route = url.replace(/\.html$/, '').replace(/^\/+|\/+$/g, '');
@@ -183,7 +336,7 @@ const nav: DefaultTheme.NavItem[] = [
   { text: 'Configuration', link: '/configuration' },
   { text: 'Changelog', link: '/changelog' },
   { text: 'Troubleshooting', link: '/troubleshooting' },
-  { text: docsVersion ?? 'main', items: versionItems },
+  { text: docsVersion ?? (channel === 'main' ? 'main' : latestStable), items: versionItems },
 ];
 
 const sidebar: DefaultTheme.SidebarItem[] = [
@@ -215,6 +368,7 @@ const sidebar: DefaultTheme.SidebarItem[] = [
       { text: 'Anki', link: '/anki-integration' },
       { text: 'Jellyfin', link: '/jellyfin-integration' },
       { text: 'YouTube', link: '/youtube-integration' },
+      { text: 'Anime Browser', link: '/anime-browser' },
       { text: 'Jimaku', link: '/jimaku-integration' },
       { text: 'Subtitle Generation', link: '/subtitle-generation' },
       { text: 'TsukiHime', link: '/tsukihime-integration' },
@@ -241,6 +395,33 @@ const config: UserConfig = {
     'SubMiner: an MPV immersion-mining overlay with Yomitan and AnkiConnect integration.',
   base,
   ...(outDir ? { outDir } : {}),
+  vite: {
+    plugins: [
+      {
+        name: 'subminer-docs-local-version-redirects',
+        configureServer(server) {
+          server.middlewares.use((request, response, next) => {
+            const requestUrl = new URL(request.url ?? '/', 'http://localhost');
+            if (serveLocalArchiveRoute(requestUrl.pathname, response)) {
+              return;
+            }
+
+            if (!shouldHandleLocalVersionRoute(requestUrl.pathname)) {
+              next();
+              return;
+            }
+
+            response.statusCode = 302;
+            response.setHeader(
+              'Location',
+              `${DOCS_HOSTNAME}${requestUrl.pathname}${requestUrl.search}`,
+            );
+            response.end();
+          });
+        },
+      },
+    ],
+  },
   head: [
     ['link', { rel: 'preconnect', href: PLAUSIBLE_PROXY_HOSTNAME }],
     [

docs-site/.vitepress/theme/components/StatusLine.vue

@@ -1,10 +1,10 @@
 <script setup>
 import { useRoute, useData } from 'vitepress';
-import { computed, onMounted, ref } from 'vue';
-import { formatStatusLineDate, formatStatusLineFilePath } from '../status-line';
+import { computed } from 'vue';
+import { formatStatusLineFilePath } from '../status-line';
 
 const route = useRoute();
-const { frontmatter } = useData();
+const { page, frontmatter } = useData();
 
 const mode = computed(() => {
   const layout = frontmatter.value.layout;
@@ -23,10 +23,10 @@ const section = computed(() => {
   return parts[0] || 'root';
 });
 
-// Set on the client only, so the prerendered HTML never bakes in the build date.
-const today = ref('');
-onMounted(() => {
-  today.value = formatStatusLineDate(new Date());
+const lastUpdated = computed(() => {
+  if (!page.value.lastUpdated) return '';
+  const date = new Date(page.value.lastUpdated);
+  return date.toISOString().slice(0, 10);
 });
 </script>
 
@@ -40,8 +40,8 @@ onMounted(() => {
     <div class="tui-statusline__right">
       <span class="tui-statusline__section">{{ section }}</span>
       <span class="tui-statusline__sep"></span>
-      <span v-if="today" class="tui-statusline__date">{{ today }}</span>
-      <span v-if="today" class="tui-statusline__sep"></span>
+      <span v-if="lastUpdated" class="tui-statusline__date">{{ lastUpdated }}</span>
+      <span v-if="lastUpdated" class="tui-statusline__sep"></span>
       <span class="tui-statusline__branch">GPL-3.0</span>
     </div>
   </footer>

docs-site/.vitepress/theme/status-line.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from 'bun:test';
-import { formatStatusLineDate, formatStatusLineFilePath } from './status-line';
+import { formatStatusLineFilePath } from './status-line';
 
 test('status line file path formats root home as index markdown', () => {
   expect(formatStatusLineFilePath('/')).toBe('index.md');
@@ -10,9 +10,7 @@ test('status line file path formats version archive home without trailing slash'
 });
 
 test('status line file path keeps normal docs routes as markdown files', () => {
-  expect(formatStatusLineFilePath('/v/0.12.0/configuration')).toBe('v/0.12.0/configuration.md');
-});
-
-test('status line date uses the local calendar day, zero padded', () => {
-  expect(formatStatusLineDate(new Date(2026, 0, 5, 23, 59))).toBe('2026-01-05');
+  expect(formatStatusLineFilePath('/v/0.12.0/configuration')).toBe(
+    'v/0.12.0/configuration.md',
+  );
 });

docs-site/.vitepress/theme/status-line.ts

@@ -2,10 +2,3 @@ export function formatStatusLineFilePath(routePath: string): string {
   if (routePath === '/') return 'index.md';
   return `${routePath.replace(/^\/|\/$/g, '')}.md`;
 }
-
-// Local calendar date as YYYY-MM-DD (toISOString would give the UTC date).
-export function formatStatusLineDate(date: Date): string {
-  const month = String(date.getMonth() + 1).padStart(2, '0');
-  const day = String(date.getDate()).padStart(2, '0');
-  return `${date.getFullYear()}-${month}-${day}`;
-}

docs-site/README.md

@@ -40,23 +40,8 @@ The public docs root is stable-only:
 - `/` serves the latest stable release docs.
 - `/main/` serves development docs from `main`.
 - `/v/<version>/` serves stable release archives.
-- `/versions` (root build only) lists every published version.
 - Prerelease tags do not update the docs site.
 
-Only `/` is indexable. `/main/` and every `/v/<version>/` page carries a self-referential canonical plus `noindex,follow`, repeated as an `X-Robots-Tag` header (by the generated `_headers` file for `/main/`, by the archive function for `/v/`). They stay crawlable so their links still resolve, but ~30 archived copies of every page would otherwise consume the crawl budget the current docs need. Only the root build emits `sitemap.xml`, and its `<lastmod>` dates come from `git log` against the tracked checkout at the released tag, because the build renders from an untracked snapshot that VitePress cannot date itself.
+Only `/` is indexable. `/main/` and every `/v/<version>/` page carries a self-referential canonical plus `noindex,follow`, and the generated `_headers` file repeats that as an `X-Robots-Tag`. They stay crawlable so their links still resolve, but ~30 archived copies of every page would otherwise consume the crawl budget the current docs need. Only the root build emits `sitemap.xml`, and its `<lastmod>` dates come from `git log` against the tracked checkout at the released tag, because the build renders from an untracked snapshot that VitePress cannot date itself.
 
 Keep Cloudflare Git auto-deploy disabled. The production deploy is `.github/workflows/docs-pages.yml`, which uploads `.tmp/docs-versioned-site` with `--branch main` so tag-triggered runs update Production instead of creating preview deployments.
-
-### Stable archives in R2
-
-`/v/<version>/` archives are not part of the Pages deployment. Each one is built once, uploaded to an R2 bucket under `v/<version>/`, and served by the Pages Function in `functions/v/[[path]].ts`. Each deploy builds only archives the bucket is missing (an archive counts as present once its `_archive.json` marker exists), plus the root and `/main/` builds. Archive nav links to `/versions` instead of listing releases, so a new tag never invalidates old archives.
-
-To re-render archives on purpose (theme change, docs fix), run the `Docs Pages` workflow manually with `rebuild_archives` set to comma-separated tags or `all`.
-
-One-time setup:
-
-- R2 bucket for archives; its name goes in the `DOCS_ARCHIVE_R2_BUCKET` repository variable.
-- R2 API token with Object Read & Write on that bucket; its S3 credentials go in the `DOCS_ARCHIVE_R2_ACCESS_KEY_ID` and `DOCS_ARCHIVE_R2_SECRET_ACCESS_KEY` repository secrets.
-- Pages project: Settings > Bindings > R2 bucket, variable name `DOCS_ARCHIVES`, pointing at the same bucket.
-
-The first deploy after setup builds and uploads every stable archive; later deploys only add new tags.

docs-site/anilist-integration.md

@@ -1,68 +1,137 @@
 # AniList integration
 
-SubMiner updates your [AniList](https://anilist.co) watch progress when you finish an episode. The same connection supplies cover art for the stats dashboard and names for the [character dictionary](/character-dictionary).
+SubMiner syncs your watch progress to [AniList](https://anilist.co). Finish an episode and it reads the title and episode number off the filename, finds the matching AniList entry, and updates your progress through the GraphQL API. A failed update retries in the background with exponential backoff.
+
+The same AniList data feeds [cover art](#cover-art) in the stats dashboard and the [Character Dictionary](/character-dictionary) for in-overlay name lookup.
+
+[AniList](https://anilist.co) is a free anime tracking site. The **access token** is a private key SubMiner keeps so it can update your list for you. You approve it once during setup, and your AniList password never touches SubMiner.
 
 ## Setup
 
-1. Set `anilist.enabled` to `true`:
+AniList integration is opt-in. To enable it:
 
-   ```jsonc
-   {
-     "anilist": {
-       "enabled": true,
-     },
-   }
-   ```
+1. Set `anilist.enabled` to `true` in your config.
+2. Leave `anilist.accessToken` empty and restart SubMiner (or run `--anilist-setup`).
+3. Approve access in the AniList authorization page.
+4. The callback returns to SubMiner via the `subminer://anilist-setup?...` protocol URL, and SubMiner stores the token automatically.
 
-2. Restart SubMiner. With no token stored, it opens the AniList setup window. You can also open it from the tray (**Configure AniList**) or with `subminer app --anilist-setup`.
-3. Approve access on the AniList page. SubMiner receives the token through a `subminer://` link and stores it encrypted.
+```jsonc
+{
+  "anilist": {
+    "enabled": true,
+    "accessToken": "",
+  },
+}
+```
 
-If the setup window does not render, SubMiner opens the authorization page in your browser instead. To skip the flow entirely, paste a token into `anilist.accessToken`.
+The access token is encrypted at rest using Electron's `safeStorage` API. On Linux this defaults to `gnome-libsecret`; override the backend with `--password-store=<backend>` (for example `--password-store=basic_text`).
 
-On Linux, the token is stored with `gnome-libsecret` by default. If your keyring is unavailable, start it (gnome-keyring or KWallet) or launch SubMiner with `--password-store=basic_text`.
+If the embedded auth UI fails to render, SubMiner opens the authorize URL in your default browser and shows fallback instructions in-app.
 
-## How updates work
+::: tip
+You can also set `anilist.accessToken` directly in config to skip the setup flow entirely. When blank, SubMiner uses the locally stored encrypted token.
+:::
 
-An episode counts as watched after 85% of its length and at least 10 minutes of playback. SubMiner then:
+## How tracking works
 
-1. Reads the title, season, and episode from the file name and folder. Install [guessit](https://github.com/guessit-io/guessit) for better parsing. A folder named `Season 2` is a strong season hint.
-2. Finds the matching AniList entry. For season 2 and later, it follows the show's sequels.
-3. Sets your progress to that episode and marks the entry Watching, or Completed on the final episode.
+SubMiner watches playback and pushes an AniList progress update once an episode counts as watched. That means at least 85% of its duration, and at least 10 minutes either way.
 
-The show must already be on your Planning or Watching list. SubMiner does not add new entries, and it never lowers your progress.
+The update flow:
 
-Failed updates are saved and retried in the background, up to 8 times with growing delays. The queue survives restarts.
+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 base title (with any `Season N` / `SN` marker stripped) is searched against the AniList GraphQL API, and SubMiner picks the best match by comparing titles (romaji, English, native, synonyms) and filtering by episode count. AniList has no notion of numbered seasons - sequels are separate entries with their own titles (`Zoku`, `Kan`, `2nd Season`), so searching `<title> Season 3` finds nothing. For season 2 and later, SubMiner instead walks `SEQUEL` relations from the season 1 entry, preferring the TV line, and falls back to ordering the franchise's TV entries by air date when the relation chain is incomplete. If neither locates the season, SubMiner **skips the update** rather than writing progress to the season 1 entry, and tells you to pin the right entry with a [character dictionary override](/character-dictionary#correcting-anilist-matches).
+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`, or `COMPLETED` when the watched episode is the final episode of the season (the "already at this progress" skip is bypassed for the final episode so completion still lands).
 
-## Fixing a wrong match
+## Update queue and retry
 
-If a cover or title in the stats Library is wrong, open the title and use **Change AniList Entry**.
+Failed AniList updates are persisted to a retry queue on disk and retried with exponential backoff.
 
-If SubMiner cannot find a later season, it skips the update rather than writing progress to season 1. Pin the right entry with the character dictionary's AniList override. See [Character dictionary](/character-dictionary).
+Updates are skipped if the media path cannot produce a safe, nonempty identity. Invalid entries are discarded when loading or adding to the retry queue.
 
-## Commands
+| Parameter        | Value      |
+| ---------------- | ---------- |
+| Initial backoff  | 30 seconds |
+| Maximum backoff  | 6 hours    |
+| Maximum attempts | 8          |
+| Queue capacity   | 500 items  |
 
-| Command                              | What it does                            |
-| ------------------------------------ | --------------------------------------- |
-| `subminer app --anilist-setup`       | Open the AniList setup window           |
-| `subminer app --anilist-status`      | Show token state and retry queue counts |
-| `subminer app --anilist-logout`      | Remove the stored token                 |
-| `subminer app --anilist-retry-queue` | Retry one queued update now             |
+After 8 failed attempts, the update is moved to a dead-letter queue and no longer retried automatically. The queue is persisted across restarts so no updates are lost if SubMiner exits before a retry succeeds.
 
-## Options
+Use `--anilist-retry-queue` to manually process one ready item from the queue.
 
-| Key                   | What it does                                                  |
-| --------------------- | ------------------------------------------------------------- |
-| `anilist.enabled`     | Turns on progress updates.                                    |
-| `anilist.accessToken` | Token override. Leave empty to use the token stored by setup. |
+## Cover art
 
-Character dictionary settings live under `anilist.characterDictionary` and are covered on the [Character dictionary](/character-dictionary) page. See [Configuration](/configuration#anilist) for defaults.
+SubMiner fetches cover art from AniList for display in the stats dashboard. When a new video starts playing, the cover art fetcher:
+
+1. Checks the local database for cached art.
+2. If missing, parses the media title (guessit then fallback) and searches the AniList API.
+3. Downloads the cover image from the AniList CDN and caches it locally (both URL and blob).
+4. Stores AniList metadata (romaji/English titles, total episodes) alongside the cover for dashboard display.
+
+A no-match result is cached for 5 minutes before SubMiner retries, preventing repeated API calls for unrecognized media.
+
+When AniList has no match, SubMiner tries [TMDB](/configuration#tmdb) next so live-action dramas and movies get a poster and synopsis too. See [Immersion tracking](/immersion-tracking#library) for how live-action entries are grouped.
+
+If the automatic match is wrong, use **Change AniList Entry** on a title in the stats Library. Relinking rewrites the cached art for every episode of that title, and both the detail view and the Library grid pick up the new cover right away: the grid refetches after a relink, and cover responses carry an ETag and are revalidated on each request instead of being cached for a day.
+
+## Rate limiting
+
+All AniList API calls go through a shared rate limiter that enforces a sliding window of 20 requests per minute. The limiter also reads AniList's `X-RateLimit-Remaining` and `Retry-After` response headers and pauses requests when the server signals throttling. This applies to both episode tracking and cover art fetching.
+
+## Configuration reference
+
+```jsonc
+{
+  "anilist": {
+    "enabled": true,
+    "accessToken": "",
+    "characterDictionary": {
+      "maxLoaded": 3,
+      "profileScope": "all",
+      "collapsibleSections": {
+        "description": false,
+        "characterInformation": false,
+        "voicedBy": false,
+      },
+    },
+  },
+}
+```
+
+| Option                                      | Values                  | Description                                                                                                  |
+| ------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `enabled`                                   | `true`, `false`         | Enable AniList post-watch progress updates (default: `false`)                                                |
+| `accessToken`                               | string                  | Explicit AniList access token override; when blank, SubMiner uses the stored encrypted token (default: `""`) |
+| `characterDictionary.maxLoaded`             | number                  | Number of recent media snapshots kept in the merged dictionary (default: `3`)                                |
+| `characterDictionary.refreshTtlHours`       | number                  | Hours before a cached media snapshot is refreshed (default: `168`, clamped to 1–8760)                        |
+| `characterDictionary.evictionPolicy`        | `"delete"`, `"disable"` | What happens to snapshots evicted beyond `maxLoaded` (default: `"delete"`)                                   |
+| `characterDictionary.profileScope`          | `"all"`, `"active"`     | Apply dictionary to all Yomitan profiles or only the active one                                              |
+| `characterDictionary.collapsibleSections.*` | `true`, `false`         | Control which dictionary entry sections start expanded                                                       |
+
+There is no `characterDictionary.enabled` key: character dictionary sync is enabled by `subtitleStyle.nameMatchEnabled`. See the [Character Dictionary](/character-dictionary) page for full details on the character dictionary feature, including name generation, matching, auto-sync lifecycle, and dictionary entry format.
+
+## CLI commands
+
+| Command                 | Description                                                   |
+| ----------------------- | ------------------------------------------------------------- |
+| `--anilist-setup`       | Open AniList setup/auth flow helper window                    |
+| `--anilist-status`      | Print current token resolution state and retry queue counters |
+| `--anilist-logout`      | Clear stored AniList token from local persisted state         |
+| `--anilist-retry-queue` | Process one ready retry queue item immediately                |
 
 ## Troubleshooting
 
-**No update after an episode.** Check that `anilist.enabled` is `true` and that you watched at least 85% of the episode.
+- **Updates not triggering:** Confirm `anilist.enabled` is `true`. SubMiner requires at least 85% of the episode watched and a minimum of 10 minutes. Short episodes or partial watches will not trigger an update.
+- **Update not possible:** Add the season to your AniList Planning or Watching list first. SubMiner will not create new AniList list entries automatically.
+- **Wrong episode or title matched:** Detection quality is best when `guessit` is installed and on your `PATH`. Without it, SubMiner falls back to internal filename parsing which can be less accurate with unusual naming conventions.
+- **Token issues:** Run `--anilist-status` to check token state. If the token is invalid or expired, run `--anilist-setup` or `--anilist-logout` and re-authenticate.
+- **Updates failing repeatedly:** Run `--anilist-status` to see retry queue counters. Items that fail 8 times are moved to the dead-letter queue. Check network connectivity and AniList API status.
+- **Cover art missing:** Cover art is fetched on a best-effort basis using title matching. If the filename is hard to parse, the search may return no results. The fetcher retries after 5 minutes.
+- **Encryption unavailable on Linux:** If you see warnings about safeStorage, try `--password-store=basic_text` as a workaround, or start your desktop keyring (gnome-keyring, KWallet).
 
-**"AniList update not possible."** Add the show to your Planning or Watching list, then mark the episode watched again.
+## Related
 
-**Wrong show or episode.** Install guessit and make sure it is on your `PATH`. Unusual file names parse poorly without it.
-
-**Token errors.** Run `subminer app --anilist-status`. If the token is invalid, run `--anilist-logout`, then `--anilist-setup`.
+- [Character Dictionary](/character-dictionary) - AniList-powered character name dictionary for Yomitan
+- [Configuration Reference](/configuration) - full config options
+- [Jellyfin Integration](/jellyfin-integration) - media server integration

docs-site/anime-browser.md

@@ -0,0 +1,419 @@
+# Anime Browser
+
+Search anime sources, pick an episode, and play it in mpv with SubMiner's overlay
+and mining tools attached — the same way a local file or a Jellyfin stream works.
+
+Open it with `subminer anime`, with `SubMiner.AppImage --anime`, or from
+**Browse Anime** in the tray menu. The window stays open while you watch, so you
+can queue the next episode without reopening it.
+
+During playback, `Ctrl+Alt+A` toggles the same browser as a modal inside the mpv
+player bounds. It uses a dedicated modal surface, so it stays above fullscreen
+playback and closes like the other in-player tools. Toggling it off keeps its
+current page and scroll position ready for the next toggle. The standalone
+window and the modal keep their own search, selected source, tab, and scroll
+state, so using one does not replace or cancel what you were doing in the other.
+
+Both surfaces use the same playback queue, source configuration, and stats
+history. Queue changes and the currently playing episode appear in both
+immediately, and watched marks come from the same history that playback and the
+stats window update. Closing and reopening the modal therefore picks up progress
+made from either browser surface.
+
+While the window is open, SubMiner shows a tray icon and — on macOS — appears
+in the Cmd+Tab switcher and the Dock (macOS ties the two together), so you can
+flip between the browser and mpv. SubMiner normally hides itself from the Dock
+because the subtitle overlay needs that to float above fullscreen video; it
+hides again when the window closes during playback.
+
+Launching an episode starts a full SubMiner playback session, the same as
+playing a local file: the overlay and mining tools attach, and the tray icon
+stays available. In standalone `subminer anime` mode, closing the window while
+a video is playing leaves playback running — reopen the browser from the tray
+(**Browse Anime**). The app only exits with the window when nothing is playing.
+
+## How it works
+
+SubMiner does not implement any anime source itself. It runs **Aniyomi extension
+APKs** through a bundled JVM sidecar ([M-Extension-Server][mes]), asks the
+selected extension to resolve an episode, and hands the resulting URL to mpv.
+
+```
+extension APK  →  bridge (JVM)  →  { url, headers }  →  mpv  →  SubMiner overlay
+```
+
+Because the extension resolves the stream, whichever sources you install decide
+what is available. SubMiner runs the installed extensions locally and nothing
+more.
+
+## Installing extensions
+
+**SubMiner ships no extension repositories and bundles no sources.** There is no
+default repository, no suggested list, and no discovery. Until you add one, the
+browser has nothing to search — that is deliberate. Every repository and
+extension comes from you, and SubMiner is not affiliated with any of the sites
+they connect to.
+
+There are two ways to add extensions.
+
+### From a repository
+
+The window has three tabs — **Browse**, **Extensions**, and **Source settings** —
+and each one fills the window, so a long extension list is not squeezed in above
+the search results.
+
+Open the **Extensions** tab, paste a repository index URL, and choose
+**Add repository**. The URL must be `https` and point at a `.json` index file —
+`index.min.json` is the common Aniyomi name, but repositories are free to publish
+under another one (for example `video.min.json`). Anything else is rejected
+immediately rather than failing later. Everything before the file name is treated
+as the repository root, so `.apk` and icon URLs are resolved relative to it.
+
+Extensions your repositories offer but you do not have appear under
+**Available**, each with **Install**. Repositories are stored in config under
+`anime.repos`, so you can also manage them there and keep them in a dotfile.
+
+Every row carries the extension's icon, as the repository publishes it, so a
+site is recognisable before you read the name. A repository row shows its host's
+favicon instead. Icons are the only part of a row that is fetched from the
+network, and a row whose icon is missing falls back to the first letter of its
+name rather than an empty box.
+
+A repository index lists every language it knows about, which is far more than
+any one person reads, so the **Available** list has a language chip row above
+it. Pick one or more languages to narrow it, or **All** to clear the filter;
+picking a language replaces **All** rather than sitting beside it. Rows name the
+language in full ("Japanese" rather than `ja`), extensions whose sources span
+languages are grouped under **Multi-language**, and the Available heading counts
+how many of the offered extensions the filter leaves.
+
+### Managing what is installed
+
+The Extensions tab opens with an **Installed** section listing everything in the
+extensions directory, with the sources each one provides and a **Remove**
+button. It is built from the directory rather than from a repository, so an
+extension you dropped in by hand — or one whose repository you have since
+removed — is still listed and still removable. An installed extension borrows
+its icon from the catalogue, so one no repository carries shows its monogram.
+
+SubMiner compares the APK's Android version code with the newest build in the
+configured repositories. **Update** is clickable only when the repository has a
+newer build. A current extension says **Up to date**. If an unusual APK has no
+readable version code, its disabled button says **Version unknown**. **Update
+all** installs every newer build in one pass and disables itself when there is
+nothing to update.
+
+### From a file
+
+Drop Aniyomi `.apk` files into the extensions directory, shown at the top of the
+Extensions tab. It defaults to `<userData>/anime-extensions` — on macOS,
+`~/Library/Application Support/SubMiner/anime-extensions` — and can be moved with
+`anime.extensionsDir`.
+
+A single APK may provide several sources; each appears separately in the
+**Source** picker. Extensions that fail to load are listed in the Installed
+section with the reason, so a broken APK is visible rather than silently
+missing.
+
+An extension that fails to load is skipped rather than blocking the others, so
+one bad APK will not hide the rest.
+
+### Default source
+
+The browser opens on the first installed source. To open on a different one,
+press **Set default** on its row in the Installed list; the row then carries a
+**default** tag, and only one source can carry it. The choice is written to
+`anime.defaultSource` and applies the next time a browser window or the
+in-player modal opens. With more than one source installed, an **All sources**
+row at the top of the list can be the default too. A default that is no longer
+installed falls back to the first source.
+
+## Searching every source at once
+
+With more than one source installed, the **Source** picker gains an
+**All sources** entry. Searching with it selected runs the query against every
+installed source at once, and each source's results appear the moment that
+source answers — a fast source is on screen while a slow one is still
+resolving. The status bar counts sources as they finish
+(`Searching… 3/5 sources · 42 results`).
+
+Each cover is labelled with the source it came from, and opening one always
+queries that source, whatever the picker says afterwards.
+
+A source that errors is named in the status bar and the rest still show their
+results; one extension that needs a login cannot blank the grid. If every
+source fails, the first error is shown in full.
+
+Typing a new search while one is still running simply starts over: results
+from the superseded search are discarded, even if its sources answer late.
+
+When a source reports another page, **Load more** appears below the covers.
+It appends the next page without duplicating entries that already arrived in
+the live result stream. A failed next-page request remains available to retry.
+
+Source settings belong to a single extension, so the **Source settings** tab
+asks you to pick one while **All sources** is selected.
+
+## Finding an episode, and what you have watched
+
+An episode list can run to hundreds of entries, so the episode header carries a
+filter box:
+
+- A number, `12`, keeps that episode. Sources that report no numbers at all
+  are still searched by name, so `12` also matches `Episode 12` in a title.
+- A range, `12-18`, keeps the episodes between the two, in either order
+  (`18-12` reads the same). Episodes the source gave no number are left out of
+  a range.
+- Anything else is a case-insensitive substring of the episode name, so `beach`
+  finds `OVA: Beach Special`.
+
+The counter next to **Episodes** reads `6 of 25` while a filter is applied.
+Pressing Escape in the filter box clears it; pressing it anywhere else goes back
+to the results grid.
+
+Episodes you have already watched are dimmed and marked `✓ watched`, with a
+count in the header. This is not a separate list the browser keeps: it reads the
+same stats history the rest of SubMiner writes to, where an episode is marked
+watched once a session runs past the completion threshold. Streams are recorded
+under a stable per-episode identity, so the mark survives the stream URL
+changing between playbacks, and it is the same mark the stats window and
+`--mark-watched` use.
+
+Because playback marks an episode partway through the session, the marks
+refresh when the browser window comes back to the front: finish an episode in
+mpv, switch back, and it is marked. With
+[immersion tracking](configuration.md) disabled there is no history to read, so
+no episode is marked.
+
+### Marking by hand, and catching up
+
+Right-click an episode for:
+
+- **Mark watched** / **Mark unwatched**: the single episode, whichever way it
+  is not already.
+- **Mark this and N below watched** / **... unwatched**: that episode and every
+  episode listed below it. Sources list newest first, so "below" is the back
+  catalogue: right-click the last episode you saw and mark everything down to
+  the start, which is how you catch up a series you watched somewhere else.
+
+A filter narrows what you are looking at, not what you mark: a span always
+covers the full episode list, and the status bar says how many episodes it
+touched. The oldest episode has nothing below it, so it only offers the single
+entry. Escape closes the menu.
+
+Marking an episode you have never played creates its stats row so the mark has
+somewhere to live. That row carries the same series, season and episode fields
+playback would have recorded, and both stats library views join the lifetime
+tables, so a manually marked episode does not appear there as watch time you
+never spent. Clearing a mark never creates anything.
+
+Marks are written to the stats history, so with immersion tracking disabled
+there is nowhere to write them and the status bar says so.
+
+## Settings
+
+| Key                      | Purpose                                                                  |
+| ------------------------ | ------------------------------------------------------------------------ |
+| `anime.autoOpenJimaku`   | Pause new episodes and open Jimaku for Japanese subtitles.               |
+| `anime.repos`            | Repository index URLs. Empty by default.                                 |
+| `anime.extensionsDir`    | Where APKs are read from. Empty uses `<userData>/anime-extensions`.      |
+| `anime.preferredQuality` | Preferred stream label, matched as a substring (for example `1080`).     |
+| `anime.defaultSource`    | Source the browser opens on: a source id or `all`. Empty uses the first. |
+| `anime.bridgeDir`        | A bridge bundle to run instead of the downloaded one. Empty by default.  |
+
+Enable `anime.autoOpenJimaku` to hand each newly loaded Anime Browser episode
+to Jimaku. SubMiner pauses playback on its first frame, waits for mpv's video
+window to appear, closes the in-player browser if it is open, hides the
+standalone browser window, and opens Jimaku with the source title, season, and
+episode already filled in. Playback resumes after the selected subtitle loads.
+Closing Jimaku also releases the automatic pause, while playback that was
+already paused stays paused. A stream that never shows a window resumes without
+opening Jimaku. Reopen the browser window with `subminer anime`, the tray
+entry, or the shortcut to keep browsing.
+
+## Source settings
+
+Most extensions need configuration before they return anything — a server
+address and credentials, a preferred quality, a language filter. Open the
+**Source settings** tab to edit them. Changes save as you make them and
+persist across restarts in `<userData>/anime-source-preferences.json`.
+
+Each save is handed back to the extension, so it can react: the Jellyfin source
+logs in when the address and password land, then fills in its media-library
+picker. Password-like fields are masked. Because that file can hold
+credentials, it is written with owner-only permissions. Values are scoped to
+the exact extension package and source, so two extensions that reuse the same
+internal source ID cannot read each other's settings. Preferences saved by an
+older build without package ownership are discarded; re-enter those source
+settings once after upgrading.
+
+## The bridge
+
+SubMiner looks for the server in three places, in order, and runs the first
+one it finds:
+
+1. `anime.bridgeDir`, if set. It must hold a Java runtime and the
+   `MExtensionServer-*.jar`, laid out as upstream ships them. A directory that
+   holds neither is an error rather than a silent fallback.
+2. A package-manager install. On Arch that is the AUR
+   [`mangatan-extension-server`](https://aur.archlinux.org/packages/mangatan-extension-server)
+   package, which Mangatan also uses, at `/usr/share/mangatan/extension_server`.
+   Installing it means no download, and pacman keeps the bridge current. The
+   `subminer-bin` package lists it as an optional dependency.
+3. SubMiner's own copy in `<userData>/anime-bridge`. The first launch downloads
+   the newest upstream release that ships a bundle for your platform (~130 MB,
+   containing the server and a matching Java runtime, so no system JDK is
+   required), the same way Mangatan does. Releases older than the oldest server
+   SubMiner is known to work with are skipped. Progress appears in the banner
+   at the top of the window.
+
+The **Bridge** note at the bottom of the Extensions tab says which one is in
+use, its version, and who updates it.
+
+### Updating the bridge
+
+Only the copy SubMiner downloaded is ever updated by SubMiner. A package-manager
+install or an `anime.bridgeDir` belongs to whoever put it there.
+
+Once the bridge is running, SubMiner asks GitHub for the newest release and
+compares it with the installed version, including package-manager installs and
+custom bridge directories. When upstream has published a newer release, the
+banner reads "Extension bridge v… is installed; v… is available".
+
+For an AUR bridge, the banner directs you to update `mangatan-extension-server`
+through your AUR helper, for example `paru -S mangatan-extension-server`, then
+restart SubMiner. Custom installations get a reminder to use their package
+manager or original installation method. These notices have no in-app update
+button. The check uses upstream releases, so AUR packaging may lag behind the
+notice. External installations with an unreadable version do not show a notice.
+
+For SubMiner's own copy, the banner includes an **Update to v…** button.
+Clicking it downloads the new release beside the
+running bridge, so a failed download changes nothing, then stops the bridge,
+swaps the directories, and starts it again. The restart takes a few seconds
+and kills the stream of an episode that is playing, the same as when the
+bridge exits for any other reason; the queue and browser state survive. The
+check is one unauthenticated GitHub API call per bridge start; if it fails
+(offline, rate limited) it is logged and no update is offered until the next
+start.
+
+Upstream publishes no checksums, so the download is trusted the way Mangatan
+and the AUR package trust it: TLS to GitHub and the maintainer's account. That
+is the same trust running the server implies in the first place.
+
+The bridge stays running while the window is open. Resolved video URLs point at
+its own loopback proxy so the extension's cookies and headers apply, which means
+those URLs stop working once it exits — the window keeps it alive for the whole
+session.
+
+If the bridge dies anyway (killed by hand, crashed, or stopped mid-operation),
+the exit is detected and named in the status bar, and the next request starts a
+new one. Playback already in flight still ends when its stream URL dies, but the
+browser recovers without an app restart.
+
+Two known limits:
+
+- There is no Android WebView, so extensions that need one (typically for
+  Cloudflare challenges) will fail with an error from the source.
+- Bundles are published for macOS (arm64, x64), Linux (x64), and Windows (x64).
+  Other platforms are unsupported outright.
+
+## Playback
+
+Selecting an episode resolves the best available stream, applies the source's
+required headers as mpv `http-header-fields`, and loads it. The headers are
+readable back off mpv, so Anki card audio and screenshots fetch correctly too.
+
+HLS streams are routed through a small local proxy before mpv sees them. Some
+hosts disguise their video segments by prepending a fake image header (a real
+1x1 PNG) so scrapers back off; Aniyomi's own player strips this, but ffmpeg
+probes the segment as a picture and playback dies with "no audio or video data
+played". The proxy scans each segment for the first genuine MPEG-TS packet run
+and drops whatever junk sits in front of it. Segments that are not TS (fMP4,
+subtitles, encryption keys) pass through untouched, and direct-file streams
+skip the proxy entirely. Segment URLs disguised behind fake extensions
+(`.image`, `.jpg`, `.css`, and friends) are exposed locally with a `.ts`
+suffix so current ffmpeg releases accept them when Anki extracts audio,
+screenshots, or animated images from the playing stream.
+
+"Playing" in the status bar means playing: after handing mpv the stream,
+SubMiner waits until mpv actually configures a video output before reporting
+success. If mpv gives up instead — a dead host, an undecodable stream — the
+browser shows mpv's error rather than pretending playback started (a failed
+load leaves no mpv window, because the player idles windowless).
+Slow streams stay in the loading state while mpv is still opening them, even
+after the initial playback confirmation deadline. Loading ends when video
+appears, mpv reports an error or returns to idle, or another episode replaces
+the request.
+
+Failed requests appear in a dismissible panel at the bottom of the browser.
+It explains the failed action and suggests a next step. Expand **Technical
+details** to read the bridge or mpv error when reporting a problem. Missing
+bridge APIs and incomplete extension data have distinct explanations; an
+update may be needed, but a compatible release may not yet be available.
+
+Choosing **Queue** resolves the episode and appends the playable stream to mpv's
+own playlist immediately, while its subtitle tracks cache in the background.
+That makes mpv's next command available at once and lets the next episode begin
+automatically when the current one ends, without waiting for another source
+request. Resolved stream URLs can be short-lived, so a very long queue can still
+outlive what its source issued; dequeue and queue that episode again to refresh
+it.
+
+### Japanese audio, and switching tracks
+
+Sources often return a dub and the original audio as two separate entries — or
+as two audio tracks of one stream — and the dub is frequently listed first.
+SubMiner always aims at the Japanese audio:
+
+- Entries labelled as a dub are skipped as long as another entry exists. This
+  outranks `anime.preferredQuality`: a 1080p dub is the wrong file, not a better
+  one. If every entry is a dub, it still plays.
+- mpv's `alang` is set to `ja,jpn,jp,japanese` before the file loads, so a
+  stream carrying several audio tracks starts on the Japanese one. With no
+  Japanese track, mpv falls back to the first one as usual.
+- Any audio or subtitle tracks the extension supplies separately are added to
+  mpv with `audio-add` / `sub-add`, tagged with their language, and the
+  Japanese one is selected.
+
+The primary subtitle slot is reserved for Japanese — it is what the overlay
+mines. A source that only carries, say, English subtitles does not get them
+promoted to primary; instead the track is added with a normalized language tag
+(`English` → `en`), and the regular [dual-subtitle settings](configuration.md)
+apply: with `secondarySub.autoLoadSecondarySub` enabled and the language listed
+in `secondarySub.secondarySubLanguages`, it is picked up as the secondary
+subtitle, exactly as it would be for a local file.
+
+Every track is added, including the ones that are not selected, so all of them
+appear in mpv's track menu and can be switched by hand while watching
+(`#` cycles audio, `j` cycles subtitles by default).
+
+The extension hands over subtitle tracks as URLs, but SubMiner downloads each
+one to a temporary directory and gives mpv the local file. mpv is happy either
+way; [Subsync](/troubleshooting#subtitle-sync-subsync) is not, because alass
+needs a file on disk to use as the timing reference. A track that fails to
+download falls back to its URL so the episode still plays, the format is
+detected from the file's own content rather than its URL, and the directory is
+removed when the next episode starts or the app exits.
+
+### Generating Japanese subtitles
+
+While an episode is playing, press **Ctrl+Shift+G** to [generate Japanese subtitles](/subtitle-generation#generating-for-anime-streams) from its audio. SubMiner fetches the complete episode audio, transcribes it locally with whisper.cpp, and loads the resulting SRT if the same stream is still playing. Generated subtitles stay in the application cache. This requires a finite HTTP/HTTPS stream with an internal audio track; live streams and separately attached audio tracks are not supported.
+
+### Series, season, and episode
+
+The episode's identity travels with it instead of being guessed back out of the
+stream URL, which carries nothing but a proxy path and a file extension. The
+title and episode label from the source's own listing are split into series,
+season, and episode number once, at launch, and everything downstream reads
+those fields:
+
+- mpv's title reads `Series S03E04 - Episode Name`.
+- Stats group by series, and rewatching an episode reuses its entry instead of
+  creating a new one.
+- The [Jimaku](/jimaku-integration) and [TsukiHime](/tsukihime-integration)
+  modals open with Title, Season, and Episode already filled in, so a subtitle
+  search is one keypress rather than a retype.
+- [AniList](/anilist-integration) progress updates use those fields directly.
+
+[mes]: https://github.com/1Selxo/M-Extension-Server

docs-site/aniskip-integration.md

@@ -1,39 +1,53 @@
 # AniSkip integration
 
-SubMiner looks up opening timestamps on [AniSkip](https://aniskip.com) so you can skip an anime's intro with one key.
+SubMiner looks up anime intro timings from [AniSkip](https://aniskip.com) so you can jump past the OP with one key.
+
+Intro detection runs in the SubMiner app over the mpv IPC socket. It works whenever the overlay is connected to mpv, not only at launch, and covers every local file loaded during the session including playlist advances.
 
 ## Setup
 
-AniSkip is on by default. To turn it off or change the key:
+AniSkip is enabled by default. Disable it or change the skip key in your config:
 
 ```jsonc
 {
   "mpv": {
-    "aniskipEnabled": true,
+    "aniskipEnabled": true, // default: true
     "aniskipButtonKey": "TAB",
   },
 }
 ```
 
-Both settings apply immediately, without restarting mpv. For better title and episode detection, install [guessit](https://github.com/guessit-io/guessit):
+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
 ```
 
-## Usage
+Without `guessit`, SubMiner falls back to its own filename parser. That handles the usual release naming, but unusual formats slip past it.
 
-When a local file loads, SubMiner reads the title and episode from the file name, finds the show on MyAnimeList, and asks AniSkip for the intro's timestamps. Streams and URLs are skipped.
+## How it works
 
-If AniSkip has an intro, SubMiner adds `AniSkip Intro Start` and `AniSkip Intro End` chapters. When the intro starts, mpv shows "You can skip by pressing TAB" (with your key) for 3 seconds. Press the key any time during the intro to jump to its end.
+On each local file load:
 
-With a custom key other than `TAB` or `y-k`, `y-k` also skips.
+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.
+
+When a custom key (other than `TAB` or `y-k`) is configured, the legacy `y-k` chord is also bound as a fallback skip trigger.
+
+Results are cached per file for the app session. Only a definitive "no intro found" is cached, so a failed lookup gets retried on the next load rather than sticking. If mpv reloads the same file, SubMiner re-applies the chapter markers without hitting the API again.
 
 ## Triggering from mpv
 
-| Command                                   | What it does                                            |
-| ----------------------------------------- | ------------------------------------------------------- |
-| `script-message subminer-skip-intro`      | Skip to the end of the intro                            |
-| `script-message subminer-aniskip-refresh` | Look up the current file again, ignoring cached results |
+AniSkip actions are also reachable from mpv script-messages:
 
-Use `subminer-aniskip-refresh` after a lookup failed or matched the wrong show.
+| 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 |
+
+The SubMiner app handles both over the IPC socket.

docs-site/anki-integration.md

@@ -1,34 +1,51 @@
 # Anki integration
 
-SubMiner talks to Anki through the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) add-on. It fills new cards with the sentence, an audio clip, and a screenshot, and can create sentence cards and merge duplicate words. It is built for the [Lapis](https://github.com/donkuri/lapis), [Kiku](https://kiku.youyoumu.my.id/), and [Senren](https://github.com/BrenoAqua/Senren) note types, but works with any note type once you map its fields.
+SubMiner uses the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) add-on to create and update Anki cards with sentence context, audio, and screenshots.
+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.
 
-For the day-to-day flow, see [Mining workflow](/mining-workflow). Every key on this page, with its default, is listed in the [AnkiConnect config reference](/configuration#ankiconnect).
+::: 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 **field** is one labeled slot in that template, such as `Sentence`, `Expression`, or `Picture`. SubMiner fills these fields when it mines a card.
+  :::
 
 ## Prerequisites
 
 1. Install [Anki](https://apps.ankiweb.net/).
-2. Install AnkiConnect (add-on code `2055492159`).
-3. Install FFmpeg and make sure it is on your `PATH`. SubMiner uses it for audio and images.
-4. Keep Anki running while you mine.
+2. Install the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) add-on (code: `2055492159`).
+3. Keep Anki running while using SubMiner.
 
-If you changed AnkiConnect's port, set `ankiConnect.url` to match.
+AnkiConnect listens on `http://127.0.0.1:8765` by default. If you changed the port in AnkiConnect's settings, update `ankiConnect.url` in your SubMiner config.
 
-## How cards get filled
+AnkiConnect and Kiku/Senren settings follow the [configuration validation rules](/configuration#configuration-file): invalid values produce a warning and fall back to the option's default. Use JSON booleans such as `true`, not strings such as `"true"`, and a positive number for `ankiConnect.pollingRate`.
 
-When Yomitan or Hachidori adds a note, SubMiner fills the sentence, audio, image, and MiscInfo fields. It finds new notes in one of two ways:
+## Auto-enrichment transport
 
-- **Proxy (default).** SubMiner runs a local AnkiConnect-compatible server. The dictionary sends notes through it, and SubMiner fills each one right after Anki accepts it.
-- **Polling.** With `ankiConnect.proxy.enabled` set to `false`, SubMiner asks AnkiConnect for recently added notes every `ankiConnect.pollingRate` milliseconds.
+When you add a word via Yomitan, SubMiner detects the new card and fills in the sentence, audio, and image fields automatically. Two detection methods are available:
 
-Set `ankiConnect.behavior.autoUpdateNewCards` to `false` to stop automatic filling and update cards by hand with `Ctrl/Cmd+V` instead.
+**Proxy mode** (default) - SubMiner runs a small local server between Yomitan and Anki. Yomitan sends the new card to SubMiner, SubMiner fills in the media fields, and the finished card goes on to Anki. There is no polling delay.
 
-`ankiConnect.deck` limits enrichment and duplicate checks to one deck. If it is empty, SubMiner uses Yomitan's mining deck when it can read it, and otherwise searches all decks.
+**Polling mode** (fallback, when the proxy is disabled) - SubMiner asks AnkiConnect every few seconds whether new cards showed up, then fills them in. Less to configure, at the cost of roughly a 3 second delay.
 
-### Proxy mode setup (Yomitan / texthooker) {#proxy-mode-setup-yomitan-texthooker}
+Use proxy mode unless your Yomitan runs in a browser rather than the bundled instance, in which case polling is the simpler path.
+
+In both modes, the enrichment workflow is the same:
+
+1. Checks if a duplicate expression already exists (for field grouping).
+2. Updates the sentence field with the current subtitle.
+3. Generates and uploads audio and image media.
+4. 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 (`added:1`). 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; stats-dashboard mining also falls back to Yomitan's mining deck when `ankiConnect.deck` is empty.
+Known-word sync scope is controlled by `ankiConnect.knownWords.decks`.
+
+### Proxy mode setup (Yomitan / texthooker)
 
 ```jsonc
 "ankiConnect": {
-  "url": "http://127.0.0.1:8765",
+  "url": "http://127.0.0.1:8765", // real AnkiConnect
   "proxy": {
     "enabled": true,
     "host": "127.0.0.1",
@@ -38,205 +55,371 @@ Set `ankiConnect.behavior.autoUpdateNewCards` to `false` to stop automatic filli
 }
 ```
 
-Clients must send notes to the proxy (`http://127.0.0.1:8766` here), not to AnkiConnect directly.
+Then point Yomitan/clients to `http://127.0.0.1:8766` instead of `8765`.
 
-- **Bundled Yomitan.** SubMiner sets the active Yomitan profile's Anki server for you. With the proxy on, it always points the profile at the proxy. With the proxy off, it sets `ankiConnect.url`, but only if the profile's server is blank or the stock `http://127.0.0.1:8765`.
-- **Browser Yomitan or other clients.** Set the Anki server to the proxy URL yourself. To leave your main profile alone, create a separate Yomitan profile for SubMiner, set its Anki server (Settings, Anki) to the proxy URL, and make it active while you mine.
-- **Hachidori.** SubMiner routes Hachidori to the proxy while it is active. Keep the proxy on for screenshots and sentence audio.
+When SubMiner loads the bundled Yomitan extension, it also attempts to update the **currently active Yomitan profile**'s Anki server to the active SubMiner endpoint (falling back to `profiles[0]` if the active-profile index is invalid):
 
-### Hachidori settings from SubMiner
+- proxy URL when `ankiConnect.proxy.enabled` is `true`
+- direct `ankiConnect.url` when proxy mode is disabled
 
-With the [Hachidori backend](/usage#hachidori-setup), SubMiner fills Hachidori's first Anki template from your `ankiConnect` settings on startup and whenever you open Hachidori Settings:
+To avoid clobbering custom setups, this auto-update only changes the profile when its current server is blank or the stock Yomitan default (`http://127.0.0.1:8765`).
 
-- The deck always follows `ankiConnect.deck`, because polling only looks for new cards in that deck.
-- While the template still has Hachidori's default `hachidori` tag, the configured tags are added ahead of it so cards carry both. Tags you edit in Hachidori settings are kept as written.
-- Missing word, sentence, pronunciation-audio, and picture mappings are filled with fields that exist in Anki. Pronunciation uses `fields.wordAudio`, or `fields.audio` when no word-audio field is set.
-- If the note type is unset, SubMiner picks the one note type that has your word and sentence fields. Enabled Lapis, Kiku, or Senren narrows the search. A fresh mapping also gets Hachidori's matching preset for readings, definitions, and other known fields.
+For browser-based Yomitan or other external clients (for example Texthooker in a normal browser profile), set their Anki server to the same proxy URL separately: `http://127.0.0.1:8766` (or your configured `proxy.host` + `proxy.port`).
 
-Apart from the deck, SubMiner only fills missing settings. Custom tags, field mappings, advanced templates, and extra templates stay as you set them. If several note types match, pick one in Hachidori Settings. If Anki was closed, start it and open Hachidori Settings again to retry.
+### Browser/Yomitan external setup (separate profile)
 
-Sentence audio, image timing, translation, metadata, and field grouping stay under SubMiner's control. Pronunciation sources are set in Hachidori. Linking an external dictionary host does not change any of this.
+If you want SubMiner to use proxy mode without touching your main/default Yomitan profile, create or select a separate Yomitan profile just for SubMiner and set its Anki server to the proxy URL.
 
-### Proxy troubleshooting
+That profile isolation gives you both benefits:
 
-If cards are not getting filled:
+- SubMiner can auto-enrich immediately via proxy.
+- Your default Yomitan profile keeps its existing Anki server setting.
 
-1. Check that the proxy is listening while SubMiner runs:
+In Yomitan, go to Settings → Profile and:
 
-   ```bash
-   ss -ltnp | grep 8766
-   ```
+1. Create a profile for SubMiner (or choose one dedicated profile).
+2. Open Anki settings for that profile.
+3. Set server to `http://127.0.0.1:8766` (or your configured proxy URL).
+4. Save and make that profile active when using SubMiner.
 
-2. Check that requests pass through to Anki:
+This is only for non-bundled, external/browser Yomitan or other clients. The bundled profile auto-update logic only targets the active profile when its server is blank or still default.
 
-   ```bash
-   curl -sS http://127.0.0.1:8766 \
-     -H 'content-type: application/json' \
-     -d '{"action":"version","version":2}'
-   ```
+### Proxy troubleshooting (quick checks)
 
-3. Read the app log (`app-YYYY-MM-DD.log`) in the logs folder. See [Troubleshooting](/troubleshooting) for where logs live.
+If auto-enrichment appears to do nothing:
+
+1. Confirm proxy listener is running while SubMiner is active:
+
+```bash
+ss -ltnp | rg 8766
+```
+
+2. Confirm requests can pass through the proxy:
+
+```bash
+curl -sS http://127.0.0.1:8766 \
+  -H 'content-type: application/json' \
+  -d '{"action":"version","version":2}'
+```
+
+3. Check the log sinks in `~/.config/SubMiner/logs/`:
+
+- App runtime log: `app-YYYY-MM-DD.log`
+- Launcher log: `launcher-YYYY-MM-DD.log`
+- mpv log: `mpv-YYYY-MM-DD.log`
+
+4. Check that the config JSONC parses and the logging shape is right:
+
+```jsonc
+"logging": {
+  "level": "debug"
+}
+```
+
+`"logging": "debug"` is invalid for current schema and can break reload/start behavior.
 
 ## Field mapping
 
-`ankiConnect.fields` maps SubMiner's data to fields on your note type.
-
-| Key                | Receives                                                                  |
-| ------------------ | ------------------------------------------------------------------------- |
-| `fields.word`      | The mined word                                                            |
-| `fields.audio`     | Sentence audio cut from the video                                         |
-| `fields.wordAudio` | Read only: Yomitan's word audio, used to time animated images (see below) |
-| `fields.image`     | Screenshot or animated clip                                               |
-| `fields.sentence`  | Subtitle text                                                             |
-| `fields.miscInfo`  | Text from `ankiConnect.metadata.pattern`                                  |
+SubMiner maps its data to your Anki note fields. Configure these under `ankiConnect.fields`:
 
 ```jsonc
 "ankiConnect": {
   "fields": {
-    "audio": "SentenceAudio",
-    "sentence": "Sentence"
+    "word": "Expression",        // mined word / expression text
+    "audio": "SentenceAudio",    // sentence audio clip cut from the video
+    "wordAudio": "ExpressionAudio", // existing Yomitan word audio, read for animation sync
+    "image": "Picture",          // screenshot or animated clip
+    "sentence": "Sentence",      // subtitle text
+    "miscInfo": "MiscInfo"       // metadata (filename, timestamp)
   }
 }
 ```
 
-Field names are matched case-insensitively. A mapped field that is missing from the note type is skipped.
+`fields.audio` receives the **sentence** audio SubMiner cuts from the video, not word audio. Yomitan writes its own dictionary audio when you mine, so point this at a separate field such as `SentenceAudio` to keep the two apart. The built-in default is still `ExpressionAudio`, which collides with Yomitan on note types that use that field for word audio.
 
-Hachidori prepares downloadable word audio before it saves a note through the proxy, so the animated image delay works on the first mine. Set a downloadable pronunciation source in Hachidori's Audio settings. Browser speech cannot be saved to Anki. Without word audio, Hachidori shows a warning and the card gets no word-audio hold.
+Field names are matched against your Anki note type case-insensitively (an exact match wins, then a lowercase comparison). If a configured field does not exist on the note type, SubMiner skips it without error.
 
-`fields.audio` gets sentence audio, not word audio. Yomitan writes its own dictionary audio into your note, so point `fields.audio` at a separate field such as `SentenceAudio`. The default, `ExpressionAudio`, is the field many note types use for Yomitan's word audio, so leaving it would overwrite that audio.
+`fields.wordAudio` selects the existing dictionary-audio field used to calculate the animated image's opening freeze. This mapping only reads audio; `fields.audio` still controls where generated sentence audio is written. See [config.example.jsonc](/config.example.jsonc) for defaults.
 
-`ankiConnect.tags` adds tags to every mined or updated card. Set it to `[]` to add none.
+These mappings always control normal word-card enrichment, including Yomitan proxy/polling updates and manual clipboard updates. Enabling Lapis or Kiku does not replace the configured word-card sentence and audio fields with `Sentence` and `SentenceAudio`. The dedicated sentence-card and audio-card shortcuts still use those Lapis/Kiku field names.
 
-`ankiConnect.metadata.pattern` builds the MiscInfo text. Tokens: `%f` file name, `%F` file name with extension, `%t` timestamp, `%T` timestamp with milliseconds, `<br>` line break.
+Two related options live alongside `fields`: `ankiConnect.deck` (target deck; empty falls back as described above) and `ankiConnect.tags` (tags added to mined cards, default `["SubMiner"]`; set `[]` to disable tagging). The `miscInfo` content is controlled by `ankiConnect.metadata.pattern` (default `[SubMiner] %f (%t)`; tokens: `%f` filename, `%F` filename with extension, `%t` timestamp, `%T` timestamp with milliseconds, `<br>` newline).
 
-## Media
+### Minimal config
 
-| Key                                  | What it does                                                                                                              |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
-| `media.generateAudio`                | Cut sentence audio (MP3) from the subtitle's start and end time                                                           |
-| `media.audioPadding`                 | Seconds added before and after the clip                                                                                   |
-| `media.fallbackDuration`             | Clip length when the subtitle has no timing                                                                               |
-| `media.maxMediaDuration`             | Longest allowed clip, in seconds (`0` removes the cap)                                                                    |
-| `media.normalizeAudio`               | Normalize clip loudness                                                                                                   |
-| `media.mirrorMpvVolume`              | Scale the clip by mpv's current volume, so quiet playback gives quiet clips                                               |
-| `media.generateImage`                | Capture an image                                                                                                          |
-| `media.imageType`                    | `static` for one frame, `avif` for an animated clip of the line                                                           |
-| `media.imageFormat`                  | Static format: `jpg`, `png`, or `webp`                                                                                    |
-| `media.imageQuality`                 | Static image quality                                                                                                      |
-| `media.imageMaxWidth` / `Height`     | Static size limit (`0` keeps source size)                                                                                 |
-| `media.animatedFps`                  | Animated clip frame rate                                                                                                  |
-| `media.animatedMaxWidth` / `Height`  | Animated size limit (`0` keeps aspect ratio)                                                                              |
-| `media.animatedCrf`                  | Animated quality, `0` to `63`, lower is better                                                                            |
-| `media.syncAnimatedImageToWordAudio` | Hold the first frame for the length of the word audio in `fields.wordAudio`, so the motion starts with the sentence audio |
-| `media.reviewTiming`                 | Pause and let you adjust the clip before media is made (see below)                                                        |
+If you only want sentence and audio on your cards:
 
-Animated AVIF needs an FFmpeg build with an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`).
+```jsonc
+"ankiConnect": {
+  "enabled": true,
+  "fields": {
+    "sentence": "Sentence",
+    "audio": "SentenceAudio"
+  }
+}
+```
 
-Media settings apply to the next card without a restart.
+## Media generation
 
-### Review media timing
+SubMiner shells out to FFmpeg for audio clips and screenshots, so FFmpeg has to be installed and on `PATH`.
 
-With `media.reviewTiming` on, SubMiner pauses before making media for word, sentence, and audio cards and opens a review dialog. You can also toggle it for the current session with **Review Media Timing** in the runtime options palette (`Ctrl/Cmd+Shift+O`). Clipboard updates and stats-dashboard mining skip the review.
+For remote streams such as Jellyfin playback, SubMiner downloads the clip's time window once into a temporary Matroska file (a stream copy, no re-encoding) and reads the timing review waveform, audio preview, audio, and image from that file instead of fetching the stream again for each step. The window covers the clip plus padding, plus the visible timeline in timing review, and grows when you reveal more of the timeline. It is deleted when a different window replaces it, after ten minutes without use, or when SubMiner exits. If the download fails, media generation reads the remote stream directly as before.
 
-Playback stays paused while the dialog is open, even if the popup or hover that paused it goes away. When the dialog closes, playback resumes if it was playing before, or if the popup closed in the meantime. A popup that is still open keeps it paused.
+### Audio
 
-The dialog shows the clip over a speech waveform. When the waveform loads, an untouched clip end moves back to just after the last speech in the line. The orange bars still mark the subtitle's original start and end.
+Audio is extracted from the video file using the subtitle's start and end timestamps. Padding is opt-in; keep it at `0` when you want sentence audio to start exactly at the mined sentence.
 
-During preview, the yellow cursor follows the audio player's position through the selected range and stays at the end when playback finishes. Buffering pauses the cursor too. If the player stops reporting progress for 15 seconds, the preview stops so you can retry.
+```jsonc
+"ankiConnect": {
+  "media": {
+    "generateAudio": true,
+    "normalizeAudio": true,      // normalize generated clip loudness
+    "mirrorMpvVolume": true,     // apply the current mpv volume level
+    "reviewTiming": false,       // review and adjust timing before media generation
+    "audioPadding": 0,           // optional seconds before and after subtitle timing
+    "maxMediaDuration": 30       // cap total duration in seconds
+  }
+}
+```
 
-| Action                   | How                                                                   |
-| ------------------------ | --------------------------------------------------------------------- |
-| Trim                     | Drag either edge, or click the waveform to move the nearer edge there |
-| Nudge an edge            | Arrow keys on a focused edge (100 ms, `Shift` for 500 ms)             |
-| Slide the clip           | Drag the middle                                                       |
-| Show more timeline       | Earlier / Later                                                       |
-| Pick the screenshot      | Screenshot slider or Frame buttons (static images only)               |
-| Add previous / next line | `P` / `N` (`Shift+P` / `Shift+N` removes)                             |
-| Preview                  | `Space`                                                               |
-| Confirm                  | `Enter`                                                               |
-| Cancel                   | `Escape`                                                              |
+Output format: MP3 at 44100 Hz. If the video has multiple audio streams, SubMiner uses the active stream. Generated sentence audio is loudness-normalized to -23 LUFS by default during extraction; set `normalizeAudio` to `false` to keep raw source loudness. When subtitle timing is missing, clips fall back to `media.fallbackDuration` seconds (default `3`). Changing these settings applies to the next extraction without restarting SubMiner.
 
-The confirmed range is used as is, with no extra padding. Added lines go into the sentence field. Reset restores the original timing and removes added lines.
+`mirrorMpvVolume` is also enabled by default. Immediately before extracting each playback-overlay card's audio, SubMiner reads mpv's numeric `volume` and applies mpv's cubic software-volume curve after loudness normalization. For example, mpv volume `50` produces `0.5³ = 0.125` gain. Amplified output above mpv volume `100` is limited to a `-1 dBFS` ceiling before MP3 encoding to prevent clipping. It ignores mpv's separate `mute` state. If the volume property is missing, invalid, or unavailable, extraction continues with unity scaling; disabling this option skips the query and volume filter. Changing this setting applies to the next extraction without restarting SubMiner. YouTube cards queued for a background media-cache download retain the volume captured when the card was mined. Stats-dashboard mining does not currently have access to the active mpv property client, so it does not apply mpv volume scaling.
 
-When you cancel, you can go back to editing, keep the original timing, create the card without media, or discard it. Discard deletes the Yomitan note or audio card, and skips creation for a sentence card.
+The audio is uploaded to Anki's media folder and inserted as `[sound:audio_<timestamp>.mp3]`.
 
-### Update behavior
+Overlay and stats-dashboard mining use the same `media.maxMediaDuration` limit. See the [configuration example](/config.example.jsonc) for its default and how to disable the cap.
 
-| Key                           | What it does                                         |
-| ----------------------------- | ---------------------------------------------------- |
-| `behavior.overwriteAudio`     | Replace existing audio instead of adding to it       |
-| `behavior.overwriteImage`     | Replace the existing image instead of adding to it   |
-| `behavior.mediaInsertMode`    | `append` or `prepend` new media when not overwriting |
-| `behavior.autoUpdateNewCards` | Fill new Yomitan notes automatically                 |
-| `behavior.highlightWord`      | Bold the mined word in the sentence field            |
-| `behavior.notificationType`   | `overlay`, `system`, `both`, or `none`               |
+Set `media.reviewTiming` to `true` to pause playback and check the clip before its media is generated. It applies to word, sentence, and audio cards.
 
-Manual clipboard updates (`Ctrl/Cmd+V`) always replace the sentence audio, whatever `overwriteAudio` says.
+The review opens on the subtitle range plus your configured audio padding. Subtitles usually hang around after the dialogue has stopped, so once the waveform loads, an untouched clip end pulls back to just after the last speech in the line. The Line end rail still marks the original subtitle timing, Reset puts it back, and a line whose speech runs right through its end is left alone.
 
-## Sentence cards (Lapis) {#sentence-cards-lapis}
+**Adjusting the clip.** Drag either edge to trim, drag the middle to slide the whole clip without changing its length, or click anywhere on the waveform to snap the nearer edge there. A focused edge also moves with the arrow keys: 100 ms per press, or 500 ms with Shift. The 100 ms buttons do the same thing. Earlier and Later each reveal two more seconds of timeline without moving the selection.
 
-`Ctrl/Cmd+S` creates a standalone sentence card from the current line, and `Ctrl/Cmd+Shift+S` then a digit combines several lines. The card uses the note type named in `ankiConnect.isLapis.sentenceCardModel`, which must exist in Anki. If it is empty, no card is created.
+**Choosing the screenshot.** With still images enabled, drag the screenshot slider or use the Frame buttons to choose a video frame independently of the audio. Earlier and Later reveal more time for both sliders. The image follows the audio midpoint until you pick a frame, then stays fixed while you trim audio. Reset below the image restores automatic selection; the audio Reset affects only the audio. The screenshot slider also supports arrow keys, Home, and End.
+
+The picker supports local video and seekable remote streams, including Jellyfin, without seeking the main player. A selected frame must load before you can confirm; if it fails, choose another frame or Reset. The picker is hidden when image generation is disabled or animated AVIF is selected. Animated images continue to use the reviewed audio range.
+
+**Keys.** Space previews the selection with a playhead sweeping the clip. The preview ends when the hidden player has actually played the last sample, so Bluetooth output latency does not clip the tail. Enter confirms and Escape cancels.
+
+**The waveform.** SubMiner reads a center channel when one carries dialogue and falls back to a mono mix otherwise, keeps only the 250 to 3500 Hz speech band, and draws each slice's loudness against the clip's own noise floor. Steady background music flattens out and dialogue stands up, which makes it much easier to tell adjacent lines apart. The mined subtitle appears as a tinted band with labeled line-start and line-end rails. If waveform analysis fails, the timing controls still work.
+
+The range you confirm is used exactly as-is; SubMiner does not add audio padding a second time. Static screenshots take its midpoint, and animated AVIF clips cover the whole range.
+
+**Pulling in adjacent lines.** Press `P` or `N`, or use the Prev and Next steppers above the sentence preview, to add the previous or next subtitle line. Repeat for as many lines as exist. Shift+`P` and Shift+`N` remove them again. The sentence preview lists every included line with the mined one highlighted, so you always see the sentence field before confirming. The clip bounds and the waveform rails follow the outermost added line, keeping the review's audio padding.
+
+Confirming writes the combined lines to the sentence field. Reset drops the added lines along with any timing changes. Adjacent lines come from the parsed subtitle track when one is loaded; otherwise you only get lines that already played. A clip capped by `media.maxMediaDuration` still keeps the full combined sentence even when the audio cannot stretch to cover every added line.
+
+**Canceling.** You can go back to editing, finish with the original timing, create the card without audio or an image, or discard it. Discard deletes an existing Yomitan or audio card, and skips creation entirely for a direct sentence card. A failed audio preview does not block confirmation or card creation.
+
+Clipboard updates and stats-dashboard mining never open timing review. The option is off by default and hot-reloads. **Review Media Timing** in the runtime options palette (`Ctrl/Cmd+Shift+O`) toggles it for the current session.
+
+If SubMiner closes the overlay while a timing review is still loading, it cancels pending setup and modal retries and restores playback if the review paused it. A new timing review can start after the overlay reopens.
+
+### Screenshots (static)
+
+A single frame is captured at the current playback position.
+
+```jsonc
+"ankiConnect": {
+  "media": {
+    "generateImage": true,
+    "imageType": "static",
+    "imageFormat": "jpg",        // "jpg", "png", or "webp"
+    "imageQuality": 92,          // 1–100
+    "imageMaxWidth": 0,          // 0 = preserve source resolution
+    "imageMaxHeight": 0
+  }
+}
+```
+
+### Animated clips (AVIF)
+
+SubMiner can produce an animated AVIF spanning the subtitle duration instead of a still frame.
+
+```jsonc
+"ankiConnect": {
+  "media": {
+    "generateImage": true,
+    "imageType": "avif",
+    "animatedFps": 10,
+    "animatedMaxWidth": 640,
+    "animatedMaxHeight": 0,      // 0 = preserve aspect ratio
+    "animatedCrf": 35            // 0–63, lower = better quality
+  }
+}
+```
+
+Animated AVIF requires an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`) in your FFmpeg build. Generation timeout is 60 seconds. `media.syncAnimatedImageToWordAudio` (default `true`) prepends a frozen first frame matching the existing audio duration in `fields.wordAudio`, so the motion starts together with the sentence audio. The freeze is baked into the image when mined; changing the mapping does not repair previously generated images.
+
+### Behavior options
+
+```jsonc
+"ankiConnect": {
+  "behavior": {
+    "overwriteAudio": true,         // replace existing audio, or append
+    "overwriteImage": true,         // replace existing image, or append
+    "mediaInsertMode": "append",    // "append" or "prepend" to field content
+    "autoUpdateNewCards": true,     // auto-update when new card detected
+    "highlightWord": true,          // bold the mined word inside the sentence field
+    "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 in `ankiConnect.fields.audio`, even when `overwriteAudio` is disabled.
+
+## Sentence cards (Lapis)
+
+SubMiner can create standalone sentence cards (without a word/expression) using a separate note type. This is designed for use with [Lapis](https://github.com/donkuri/Lapis) and similar sentence-focused note types.
+
+::: warning Required config
+Sentence card creation and audio card marking require a non-empty `ankiConnect.isLapis.sentenceCardModel` naming a note type that exists in Anki (default: `"Lapis"`). If the model is empty or missing, the `Ctrl/Cmd+S` and `Ctrl/Cmd+Shift+A` shortcuts will not create cards.
+:::
 
 ```jsonc
 "ankiConnect": {
   "isLapis": {
     "enabled": true,
-    "sentenceCardModel": "Lapis"
+    "sentenceCardModel": "Lapis" // default; point at your Lapis/Kiku note type
   }
 }
 ```
 
-Sentence cards and audio cards (`Ctrl/Cmd+Shift+A`) always write to the `Sentence` and `SentenceAudio` fields. Normal word cards keep using your `ankiConnect.fields` mapping.
+Trigger with the mine sentence shortcut (`Ctrl/Cmd+S` by default). The card is created directly via AnkiConnect with the sentence, audio, and image filled in.
+
+The dedicated sentence-card and audio-card shortcuts use the Lapis/Kiku-compatible `Sentence` and `SentenceAudio` fields. This does not affect the configured fields used to enrich normal word cards.
+
+To mine multiple subtitle lines as one sentence card, use `Ctrl/Cmd+Shift+S` followed by a digit (1–9) to select how many recent lines to combine.
 
 ## Word card type (Kiku/Lapis)
 
-When `isKiku` or `isLapis` is enabled, SubMiner sets a card-type flag on word cards it fills. Choose the flag with `ankiConnect.lapisKiku.wordCardKind`:
+Word cards get a card-type flag when SubMiner fills their sentence, whether that comes from Yomitan auto-enrichment, a manual clipboard update, or stats-dashboard word mining. By default the flag is `IsWordAndSentenceCard`; pick a different one with `ankiConnect.lapisKiku.wordCardKind`.
 
-| Value               | Flag                    |
-| ------------------- | ----------------------- |
-| `word-and-sentence` | `IsWordAndSentenceCard` |
-| `click`             | `IsClickCard`           |
-| `sentence`          | `IsSentenceCard`        |
-| `audio`             | `IsAudioCard`           |
-| `none`              | Leaves flags alone      |
+```jsonc
+"ankiConnect": {
+  "isKiku": { "enabled": true },
+  "lapisKiku": {
+    "wordCardKind": "click" // word-and-sentence (default), click, sentence, audio, none
+  }
+}
+```
 
-The other card-type flags are cleared. Sentence cards and audio cards keep their own flag.
+`click` marks `IsClickCard`, `sentence` marks `IsSentenceCard`, `audio` marks `IsAudioCard`, and `none` leaves the flags untouched for templates that manage them elsewhere. Whichever flag is chosen, the other card-type flags are cleared so the note never claims two card types. The setting is only read when `isKiku` or `isLapis` is enabled, and cards mined with Mine Sentence or Mine Audio keep their own flag.
 
-## Field grouping (Kiku/Senren) {#field-grouping-kiku-senren}
+## Field grouping (Kiku/Senren)
 
-When you mine a word that already has a card, SubMiner can merge the new card into the old one. The sentence, audio, image, and MiscInfo from both cards are kept as grouped entries, and the template lets you switch between them. This works with [Kiku](https://github.com/youyoumu/kiku) and [Senren](https://github.com/BrenoAqua/Senren) (which calls it [scene switching](https://github.com/BrenoAqua/Senren/blob/main/docs/scene_switching.md)).
-
-Enable one of them. They write different markup to the same fields, so only one can be on. If both are enabled, Kiku is used and SubMiner logs a config warning.
+When you mine the same word multiple times, SubMiner can merge the cards instead of creating duplicates. This is designed for note types that support grouped fields: [Kiku](https://github.com/youyoumu/kiku) and [Senren](https://github.com/BrenoAqua/Senren) (which calls the feature scene switching).
 
 ```jsonc
 "ankiConnect": {
   "isKiku": {
     "enabled": true,
-    "fieldGrouping": "manual",
-    "deleteDuplicateInAuto": true
+    "fieldGrouping": "manual",         // "auto", "manual", or "disabled"
+    "deleteDuplicateInAuto": true      // delete new card after auto-merge
   }
 }
 ```
 
-For Senren, use the same keys under `isSenren`.
+For Senren note types, enable `isSenren` instead. Kiku and Senren write incompatible markup into the same fields, so only one can be enabled at a time; if both are enabled, Kiku wins and a config warning is emitted.
 
-| `fieldGrouping` | Behavior                                                                        |
-| --------------- | ------------------------------------------------------------------------------- |
-| `disabled`      | No duplicate check                                                              |
-| `auto`          | Merge into the existing card. With `deleteDuplicateInAuto`, delete the new card |
-| `manual`        | Show both cards, let you choose which to keep and preview the merge             |
+```jsonc
+"ankiConnect": {
+  "isSenren": {
+    "enabled": true,
+    "fieldGrouping": "auto",           // "auto" (default), "manual", or "disabled"
+    "deleteDuplicateInAuto": true      // delete new card after auto-merge
+  }
+}
+```
 
-Grouping runs when a new note is added while duplicates exist. With Hachidori, that is the popup's **Add anyway** choice. **Overwrite** updates the existing note in place and only gets media.
+### Modes
 
-The manual dialog cancels itself after 90 seconds. Identical entries are not deduplicated. Press `Ctrl/Cmd+G` to run the duplicate check on the last card yourself.
+**Disabled** (`"disabled"`): No duplicate detection. Each card is independent.
 
-| Key         | Action                                |
-| ----------- | ------------------------------------- |
-| `1` / `2`   | Keep card 1 or card 2                 |
-| `Enter`     | Confirm                               |
-| `Backspace` | Back from the merge preview           |
-| `Esc`       | Cancel and leave both cards unchanged |
+**Auto** (`"auto"`): When a duplicate expression is found, SubMiner merges the new card into the existing one automatically. Both cards' sentences, audio clips, and images are preserved as grouped entries. If `deleteDuplicateInAuto` is true, the new card is deleted after merging.
 
-## Config validation
+**Manual** (`"manual"`): A modal appears in the overlay showing both cards. You choose which card to keep, preview the merge result, then confirm. The modal has a 90-second timeout, after which it cancels automatically.
 
-Invalid `ankiConnect` values produce a warning and fall back to the default. Use JSON booleans (`true`, not `"true"`) and a positive number for `pollingRate`.
+### What gets merged
+
+| Field    | Merge behavior                                  |
+| -------- | ----------------------------------------------- |
+| Sentence | Both cards' sentences kept as grouped entries   |
+| Audio    | Both cards' `[sound:...]` entries kept          |
+| Image    | Both cards' images kept                         |
+| MiscInfo | Both cards' source info kept as grouped entries |
+
+Identical values from both cards are kept as separate grouped entries; the merge does not deduplicate.
+
+The merge markup depends on the note type. Kiku entries are wrapped in `<span data-group-id="...">` spans ordered newest first. Senren entries follow the [scene switching](https://github.com/BrenoAqua/Senren/blob/main/docs/scene_switching.md) format: sentence, sentenceFurigana, and miscInfo entries use `group` spans when ordinal order is sufficient and numbered `groupN` spans when they need an absolute scene target. Audio and pictures are appended positionally, and the number of sentenceAudio entries drives Senren's scene count. Ungrouped legacy content is wrapped into a group span on first merge, and source `groupN` spans are rebased after the kept note's existing audio scenes.
+
+### Keyboard shortcuts in the modal
+
+| Key         | Action                             |
+| ----------- | ---------------------------------- |
+| `1` / `2`   | Select card 1 or card 2 to keep    |
+| `Enter`     | Confirm selection                  |
+| `Backspace` | Go back from the merge preview     |
+| `Esc`       | Cancel (keep both cards unchanged) |
+
+## Full config example
+
+```jsonc
+{
+  "ankiConnect": {
+    "enabled": true,
+    "url": "http://127.0.0.1:8765",
+    "pollingRate": 3000,
+    "deck": "",
+    "tags": ["SubMiner"],
+    "proxy": {
+      "enabled": true, // default
+      "host": "127.0.0.1",
+      "port": 8766,
+      "upstreamUrl": "http://127.0.0.1:8765",
+    },
+    "fields": {
+      "word": "Expression",
+      "audio": "SentenceAudio",
+      "image": "Picture",
+      "sentence": "Sentence",
+      "miscInfo": "MiscInfo",
+    },
+    "media": {
+      "generateAudio": true,
+      "generateImage": true,
+      "imageType": "static",
+      "imageFormat": "jpg",
+      "imageQuality": 92,
+      "normalizeAudio": true,
+      "mirrorMpvVolume": true,
+      "audioPadding": 0,
+      "maxMediaDuration": 30,
+    },
+    "behavior": {
+      "overwriteAudio": true,
+      "overwriteImage": true,
+      "mediaInsertMode": "append",
+      "autoUpdateNewCards": true,
+      "notificationType": "overlay",
+    },
+    "metadata": {
+      "pattern": "[SubMiner] %f (%t)",
+    },
+    "isKiku": {
+      "enabled": false,
+      "fieldGrouping": "disabled",
+      "deleteDuplicateInAuto": true,
+    },
+    "isLapis": {
+      "enabled": false,
+      "sentenceCardModel": "Lapis",
+    },
+  },
+}
+```

docs-site/architecture.md

@@ -1,55 +1,148 @@
 # Architecture
 
-A contributor-facing map of how SubMiner is put together. The canonical internal guidance, including domain ownership and layering rules, is [`docs/architecture/README.md`](https://github.com/ksyasuda/SubMiner/blob/main/docs/architecture/README.md) in the repo.
+This page is a contributor-facing architecture summary. Canonical internal architecture guidance lives in `docs/architecture/README.md` at the repo root.
 
-SubMiner runs as three cooperating runtimes:
+SubMiner is split into three cooperating runtimes:
 
-- the Electron desktop app (`src/`): overlay, UI, and runtime orchestration
-- the launcher CLI (`launcher/`): mpv and app command workflows
-- the mpv Lua plugin (`plugin/subminer/`): player-side controls and handoff to the app
+- Electron desktop app (`src/`) for overlay/UI/runtime orchestration.
+- Launcher CLI (`launcher/`) for mpv/app command workflows.
+- mpv Lua plugin (`plugin/subminer/main.lua` + module files) for player-side controls and IPC handoff.
 
-Inside the app, `src/main.ts` is a composition root. It owns wiring and state, and delegates behavior to small runtime and domain modules that can be tested without Electron or mpv.
+Within the desktop app, `src/main.ts` is a composition root that wires small runtime/domain modules plus core services.
 
-## Project layout
+## Goals
+
+- Keep behavior stable while reducing coupling.
+- Prefer small, single-purpose units that can be tested in isolation.
+- Keep `main.ts` focused on wiring and state ownership, not implementation detail.
+- Follow Unix-style composability:
+  - each service does one job
+  - services compose through explicit inputs/outputs
+  - orchestration is separate from implementation
+
+## Project structure
 
 ```text
-launcher/
-  main.ts                 # entrypoint and command dispatch
-  commands/               # one module per subcommand (playback, jellyfin, stats, sync, ...)
-  config/                 # launcher config readers and CLI parser
-plugin/subminer/          # mpv plugin; main.lua loads init.lua, which boots the other modules
+launcher/                 # Standalone CLI launcher wrapper and mpv helpers
+  commands/               # Command modules (doctor/config/mpv/jellyfin/playback/app passthrough/
+                          #   dictionary/history/logs/stats/update)
+  config/                 # Launcher config parsers + CLI parser builder
+  main.ts                 # Launcher entrypoint and command dispatch
+plugin/
+  subminer/               # Modular mpv plugin (main · init · bootstrap · lifecycle · process
+                          #   state · messages · hover · ui · options · environment · log
+                          #   binary · session_bindings · version)
 src/
-  main-entry.ts           # bootstrap wrapper that runs before main.js
-  main.ts                 # composition root
-  preload*.ts             # preload bridges (overlay, settings, stats, sync, Jellyfin setup)
-  main/                   # main-process runtime modules and IPC/CLI wiring
-    boot/                 # pre-ready boot helpers
-    runtime/composers/    # larger runtime clusters assembled for main.ts
-    runtime/domains/      # domain barrels (startup, overlay, mpv, ipc, shortcuts, anilist, jellyfin, mining)
-  core/services/          # focused services: mpv client, overlay, tokenizer, mining, integrations, stats
-  core/utils/             # pure helpers
-  shared/ipc/             # IPC channel constants and payload validators
-  renderer/               # overlay renderer: subtitle rendering, input handlers, modals
-  config/                 # definitions/ (defaults + option registries) and resolve/ (resolution pipeline)
-  cli/                    # app CLI parsing and help output
-  settings/, syncui/      # settings and sync windows
-  window-trackers/        # Hyprland, Sway, X11, macOS, and Windows trackers
-  anki-integration/       # AnkiConnect proxy and note-update workflow
-  jimaku/, subsync/, tsukihime/  # integration helpers
-  types/                  # shared domain types
-stats/                    # stats dashboard UI (Vite)
-vendor/                   # Yomitan fork, texthooker-ui, JLPT vocab
+  main-entry.ts           # Background-mode bootstrap wrapper before loading main.js
+  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
+    boot/                  # Pre-ready boot helpers
+    app-lifecycle.ts       # App lifecycle + app-ready runtime runner factories
+    character-dictionary-runtime.ts # Character-dictionary orchestration/public runtime API
+    cli-runtime.ts         # CLI command runtime service adapters
+    config-validation.ts   # Startup/hot-reload config error formatting and fail-fast helpers
+    dependencies.ts        # Shared dependency builders for IPC/runtime services
+    ipc-runtime.ts         # IPC runtime registration wrappers
+    overlay-runtime.ts     # Overlay modal routing + active-window selection
+    overlay-shortcuts-runtime.ts # Overlay keyboard shortcut handling
+    overlay-visibility-runtime.ts # Overlay visibility + tracker-driven bounds service
+    frequency-dictionary-runtime.ts # Frequency dictionary runtime adapter
+    jlpt-runtime.ts         # JLPT dictionary runtime adapter
+    media-runtime.ts        # Media path/title/subtitle-position runtime service
+    startup.ts              # Startup bootstrap dependency builder
+    startup-lifecycle.ts    # Lifecycle runtime runner adapter
+    state.ts                # Application runtime state container + reducer transitions
+    subsync-runtime.ts      # Subsync command runtime adapter
+    character-dictionary-runtime/ # Character-dictionary fetch/build/cache modules + focused tests
+    runtime/
+      composers/            # High-level composition clusters used by main.ts
+      domains/              # Domain barrel exports (startup/overlay/mpv/jellyfin/...)
+      registry.ts           # Domain registry consumed by main.ts
+  core/
+    services/              # Focused runtime services (Electron adapters + pure logic)
+      anilist/             # AniList token store/update queue/update helpers
+      immersion-tracker/   # Immersion persistence/session/metadata modules
+      tokenizer/           # Tokenizer stage modules (selection/enrichment/annotation)
+    utils/                 # Pure helpers and coercion/config utilities
+  cli/                     # CLI parsing and help output
+  config/                  # Config defaults/definitions, loading, parse, resolution pipeline
+    definitions/           # Domain-specific defaults + option registries
+    resolve/               # Domain-specific config resolution pipeline stages
+  shared/ipc/              # Cross-process IPC channel constants + payload validators
+  renderer/                # Overlay renderer (modularized UI/runtime)
+    handlers/              # Keyboard/mouse/gamepad interaction modules
+    modals/                # Modal flows (Anime Browser, Jimaku, Kiku, subsync, runtime options,
+                           #   session help, changelog, character dictionary, playlist browser, subtitle
+                           #   sidebar, YouTube track picker, controller config/debug/select)
+    positioning/           # Subtitle position controller (drag-to-reposition)
+  settings/                # Settings window UI (model, controls, markup)
+  types/                   # Domain type modules (anki, config, integrations, ...)
+  window-trackers/         # Backend-specific tracker implementations (Hyprland, Sway, X11, macOS, Windows)
+  jimaku/                  # Jimaku API integration helpers
+  subsync/                 # Subtitle sync (alass/ffsubsync) helpers
+  anki-integration/        # AnkiConnect proxy server + note-update enrichment workflow
 ```
 
-A few ownership notes that are hard to guess from file names:
+### Service layer (`src/core/services/`)
 
-- mpv access is split into transport (`mpv-transport.ts`), protocol (`mpv-protocol.ts`), and property modules under `src/core/services/`.
-- The renderer keeps `renderer.ts` to orchestration. Keyboard, mouse, and gamepad input live in `renderer/handlers/`, and each modal flow has its own file in `renderer/modals/`.
-- AniSkip intro detection runs in the app (`src/main/runtime/aniskip-runtime.ts`), which drives mpv chapters and the skip key over the mpv IPC socket. The plugin does not handle it.
+- **Overlay/window runtime:** `overlay-manager.ts`, `overlay-window.ts`, `overlay-visibility.ts`, `overlay-bridge.ts`, `overlay-runtime-init.ts`, `overlay-content-measurement.ts`
+- **Shortcuts/input:** `shortcut.ts`, `overlay-shortcut.ts`, `overlay-shortcut-handler.ts`, `shortcut-fallback.ts`, `numeric-shortcut.ts`
+- **MPV runtime:** `mpv.ts`, `mpv-transport.ts`, `mpv-protocol.ts`, `mpv-properties.ts`, `mpv-render-metrics.ts`
+- **Mining + Anki/Jimaku runtime:** `mining.ts`, `field-grouping.ts`, `field-grouping-overlay.ts`, `anki-jimaku.ts`, `anki-jimaku-ipc.ts`
+- **Subtitle/token pipeline:** `subtitle-processing-controller.ts`, `subtitle-position.ts`, `subtitle-ws.ts`, `tokenizer.ts` + `tokenizer/*` stage modules (including `parser-enrichment-worker-runtime.ts` for async MeCab enrichment and `yomitan-parser-runtime.ts`)
+- **Integrations:** `jimaku.ts`, `subsync.ts`, `subsync-runner.ts`, `texthooker.ts`, `jellyfin.ts`, `jellyfin-remote.ts`, `discord-presence.ts`, `yomitan-extension-loader.ts`, `yomitan-settings.ts`
+- **Anki integration (repo `src/` root, not under `core/services/`):** `src/anki-integration.ts`, `src/anki-integration/anki-connect-proxy.ts` (local proxy for push-based auto-enrichment), `src/anki-integration/note-update-workflow.ts`
+- **Config/runtime controls:** `config-hot-reload.ts`, `runtime-options-ipc.ts`, `cli-command.ts`, `startup.ts`
+- **Domain submodules:** `anilist/*` (token/update queue/updater), `immersion-tracker/*` (storage/session/metadata/query/reducer)
 
-## Component diagram
+### Renderer layer (`src/renderer/`)
 
-The main process drives one primary overlay window plus modal surfaces. Primary and secondary subtitle layers render in the same overlay renderer, connected to the main process through `preload.ts`. The launcher and mpv plugin run as separate processes and talk to the app through sockets or CLI passthrough.
+The renderer keeps `renderer.ts` focused on orchestration. UI behavior is delegated to per-concern modules.
+
+```text
+src/renderer/
+  renderer.ts              # Entrypoint/orchestration only
+  context.ts               # Shared runtime context contract
+  state.ts                 # Centralized renderer mutable state (visible overlay only)
+  error-recovery.ts        # Global renderer error boundary + recovery actions
+  overlay-content-measurement.ts # Reports rendered bounds to main process
+  subtitle-render.ts       # Primary/secondary subtitle rendering + style application
+  positioning.ts           # Facade export for positioning controller
+  yomitan-popup.ts         # Yomitan popup iframe detection utilities
+  positioning/
+    controller.ts          # Subtitle drag-position controller
+    position-state.ts      # Position state helpers (yPercent)
+  handlers/
+    keyboard.ts            # Keybindings, chord handling, modal key routing
+    mouse.ts               # Hover/drag behavior, selection + observer wiring
+    gamepad-controller.ts  # Gamepad/controller input handling
+    controller-binding-capture.ts # Controller binding capture flow
+  modals/
+    jimaku.ts              # Jimaku modal flow
+    kiku.ts                # Kiku field-grouping modal flow
+    runtime-options.ts     # Runtime options modal flow
+    session-help.ts        # Keyboard shortcuts/help modal flow
+    subsync.ts             # Manual subsync modal flow
+    character-dictionary.ts # Character dictionary modal flow
+    playlist-browser.ts    # Playlist browser modal flow
+    subtitle-sidebar.ts    # Subtitle sidebar modal flow
+    youtube-track-picker.ts # YouTube subtitle track picker
+    controller-*.ts        # Controller config/debug/select modals
+  utils/
+    dom.ts                 # Required DOM lookups + typed handles
+    platform.ts            # Layer/platform capability detection
+```
+
+### 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/main.lua` is the mpv entrypoint: it sets up the module path and loads `init.lua`, a thin shim that boots the modular Lua files: `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), `session_bindings.lua` (configurable session keybindings), `version.lua` (version metadata). 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
+
+The main process orchestrates a single primary overlay window plus modal surfaces: `main.ts` delegates to composition modules that wire together domain services. Subtitle layers (primary + secondary bar) are rendered in the same overlay renderer process, connected through `preload.ts`. External runtimes (launcher CLI and mpv plugin) operate independently and communicate via IPC socket or CLI passthrough.
 
 ```mermaid
 flowchart TB
@@ -132,39 +225,63 @@ flowchart TB
 
 ## Composition pattern
 
-Runtime code uses dependency injection:
+Most runtime code follows a dependency-injection pattern:
 
-1. Put the logic in a service under `src/core/services/`, as pure or side-effect-bounded functions.
-2. Build its runtime dependencies in a `src/main/` module. Pass simple dependencies inline; extract an adapter only when it adds behavior or gets reused.
-3. Call the service from lifecycle or command wiring.
+1. Define a service interface in `src/core/services/*`.
+2. Keep core logic in pure or side-effect-bounded functions.
+3. Build runtime deps in `src/main/` composition modules; extract an adapter/helper only when it adds meaningful behavior or reuse.
+4. Call the service from lifecycle/command wiring points.
 
-`main.ts` gets domain handlers through `createMainRuntimeRegistry()` (`src/main/runtime/registry.ts`), which exposes the barrels in `src/main/runtime/domains/`. Larger clusters, such as app-ready startup, mpv, Jellyfin, AniList tracking, shortcuts, and IPC, are assembled by composers in `src/main/runtime/composers/`. Many handlers take a `*MainDeps` object built by a `createBuild*MainDepsHandler` builder, which keeps side effects out of the unit under test.
+The composition root (`src/main.ts`) delegates to focused modules in `src/main/` and `src/main/runtime/composers/`:
 
-Composers declare their inputs with `ComposerInputs<T>` and results with `ComposerOutputs<T>` from `src/main/runtime/composers/contracts.ts`. A missing dependency then fails at compile time.
+- `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
 
-### IPC boundary
+Composer modules share contract conventions via `src/main/runtime/composers/contracts.ts`:
 
-Channel names live in `src/shared/ipc/contracts.ts` and payload validators in `src/shared/ipc/validators.ts`. Renderer payloads are validated at the IPC entry points (`src/core/services/ipc.ts`, `src/core/services/anki-jimaku-ipc.ts`) before any domain handler runs. See [IPC + runtime contracts](/ipc-contracts) for the full rules.
+- composer input surfaces are declared with `ComposerInputs<T>` so required dependencies cannot be omitted at compile time
+- composer outputs are declared with `ComposerOutputs<T>` to keep result contracts explicit and stable
+- builder return payload extraction should use shared type helpers instead of inline ad-hoc inference
 
-### Runtime state ownership
+This keeps side effects explicit and makes behavior easy to unit-test with fakes.
 
-Some domains, such as AniList token, queue, and media-guess state, use reducer-style transitions:
+Additional conventions in the current code:
 
-- Composition modules own the mutable state and expose narrow `get*`/`set*` accessors.
-- Handlers change another domain's state only through its transition helpers in `src/main/state.ts`, never by mutating the object directly.
-- A transition may update derived counters or snapshots, but must leave metadata it does not own untouched.
-- Tests for these domains check both the fields that should change and the ones that should not.
+- `main.ts` uses `createMainRuntimeRegistry()` (`src/main/runtime/registry.ts`) to access domain handlers (`startup`, `overlay`, `mpv`, `ipc`, `shortcuts`, `anilist`, `jellyfin`, `mining`) without importing every runtime module directly.
+- Domain barrels in `src/main/runtime/domains/*` re-export runtime handlers + main-deps builders, while composers in `src/main/runtime/composers/*` assemble larger runtime clusters.
+- Many runtime handlers accept `*MainDeps` objects generated by `createBuild*MainDepsHandler` builders to isolate side effects and keep units testable.
+
+### IPC contract + validation boundary
+
+- Central channel constants live in `src/shared/ipc/contracts.ts` and are consumed by both main (`ipcMain`) and renderer preload (`ipcRenderer`) wiring.
+- Runtime payload parsers/type guards live in `src/shared/ipc/validators.ts`.
+- Rule: renderer-supplied payloads must be validated at IPC entry points (`src/core/services/ipc.ts`, `src/core/services/anki-jimaku-ipc.ts`) before calling domain handlers.
+- Malformed invoke payloads return explicit structured errors (for example `{ ok: false, error: ... }`) and malformed fire-and-forget payloads are ignored safely.
+
+### Runtime state ownership (migrated domains)
+
+For domains migrated to reducer-style transitions (for example AniList token/queue/media-guess runtime state), follow these rules:
+
+- Composition/runtime modules own mutable state cells and expose narrow `get*`/`set*` accessors.
+- Domain handlers do not mutate foreign state directly; they call explicit transition helpers that encode invariants.
+- Transition helpers may sync derived counters/snapshots, but must preserve non-owned metadata unless the transition explicitly owns that metadata.
+- Reducer boundary: when a domain has transition helpers in `src/main/state.ts`, new callsites should route updates through those helpers instead of ad-hoc object mutation in `main.ts` or composers.
+- Tests for migrated domains should assert both the intended field changes and non-targeted field invariants.
 
 ## Playback startup flow
 
-A SubMiner-managed launch (the `subminer` launcher, the app's own playback, or the packaged Windows shortcut) starts mpv, injects the plugin, and brings up the overlay. 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` has no settings, so command-line options 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 starts the overlay:
-
-- On a first launch, the launcher sets `auto_start=yes` and the plugin's `file-loaded` hook starts the app once the socket is ready.
-- When the app is already running, or for `--start-overlay` and YouTube flows, the launcher attaches over the app control socket and suppresses the plugin's auto-start.
-
-Both paths end in 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
@@ -195,17 +312,17 @@ flowchart TB
   Conn --> Show["Transparent overlay over mpv<br/>Yomitan lookup · mine"]:::overlay
 ```
 
-The sockets in this flow are described in [IPC + runtime contracts](./ipc-contracts#runtime-sockets).
+The runtime sockets in this flow are detailed in [IPC + Runtime Contracts](./ipc-contracts#runtime-sockets).
 
 ## Program lifecycle
 
-1. **Module init.** Before `app.ready`, the composition root registers protocols, sets platform flags, constructs services, and wires dependencies. `runAndApplyStartupState()` parses CLI args and detects the compositor backend.
-2. **Startup.** `--generate-config` writes the template and exits. Otherwise `app-lifecycle.ts` takes the single-instance lock and registers Electron lifecycle hooks.
-3. **App ready.** `composeAppReadyRuntime()` reloads config strictly, resolves keybindings, creates the `MpvIpcClient` (which connects and observes subtitle and playback properties), and starts the runtime options manager, subtitle timing tracker, and immersion tracker.
-4. **Overlay.** `initializeOverlayRuntime()` creates the overlay window, registers global shortcuts, and tracks mpv's window bounds through the active window tracker. `src/main/runtime/overlay-mpv-sub-visibility.ts` hides mpv's own subtitles while the overlay shows them.
-5. **Background warmups.** MeCab, Yomitan, JLPT and frequency dictionaries, the optional Jellyfin remote session, Discord presence, AniList token refresh, and the optional AnkiConnect proxy start asynchronously. `startupWarmups` controls which run; its low-power mode defers everything except Yomitan.
-6. **Runtime.** Event-driven. mpv property changes, IPC messages, CLI commands, shortcuts, and config hot-reloads route through handlers and composers. Subtitle text goes through `SubtitleProcessingController` (normalize, tokenize, merge) and out to the overlay renderer and modals.
-7. **Shutdown.** `onWillQuitCleanup` tears down the tray, config watcher, shortcuts, WebSocket and texthooker servers, mpv socket, window tracker, and Yomitan parser window. It flushes the immersion tracker to SQLite and stops Jellyfin, Discord, and the AnkiConnect proxy.
+- **Module-level init:** Before `app.ready`, the composition root registers protocols, sets platform flags, constructs all services, and wires dependency injection. `runAndApplyStartupState()` parses CLI args and detects the compositor backend.
+- **Startup:** If `--generate-config` is passed, it writes the template and exits. Otherwise `app-lifecycle.ts` acquires the single-instance lock and registers Electron lifecycle hooks.
+- **Critical-path init:** Once `app.whenReady()` fires, `composeAppReadyRuntime()` runs strict config reload, resolves keybindings, creates the `MpvIpcClient` (which immediately connects and subscribes to mpv subtitle/playback properties via `observe_property`), and initializes the `RuntimeOptionsManager`, `SubtitleTimingTracker`, and `ImmersionTrackerService`.
+- **Overlay runtime:** `initializeOverlayRuntime()` creates the primary overlay window (interactive Yomitan lookups and subtitle rendering), registers global shortcuts, and sets up bounds tracking via the active window tracker. mpv subtitle suppression is handled by a dedicated `overlay-mpv-sub-visibility` service.
+- **Background warmups:** Non-critical services are launched asynchronously: MeCab tokenizer check (with async worker thread), Yomitan extension load, JLPT + frequency dictionary prewarm, optional Jellyfin remote session, Discord presence service, AniList token refresh, and optional AnkiConnect proxy server. Warmup coverage is configurable through `startupWarmups` (including low-power mode that defers all but Yomitan).
+- **Runtime:** Event-driven. mpv property changes, IPC messages, CLI commands, overlay shortcuts, and hot-reload notifications route through runtime handlers/composers. Subtitle text flows through the `SubtitleProcessingController` (normalize → tokenize → merge), and results are sent to the main overlay renderer and modal surfaces.
+- **Shutdown:** `onWillQuitCleanup` destroys tray + config watcher, unregisters shortcuts, stops WebSocket + texthooker servers, closes the mpv socket + flushes OSD log, stops the window tracker, closes the Yomitan parser window, flushes the immersion tracker (SQLite), stops Jellyfin/Discord services, stops the AnkiConnect proxy server, and cleans Anki/AniList state.
 
 ```mermaid
 flowchart TB
@@ -269,11 +386,11 @@ flowchart TB
   style Loop fill:#363a4f,stroke:#494d64,color:#cad3f5
 ```
 
-## Subtitle prefetch
+## Subtitle prefetch pipeline
 
-SubMiner tokenizes upcoming subtitle lines before they appear, so they render from a warm cache. `SubtitlePrefetchService` (`src/core/services/subtitle-prefetch.ts`) gets the cue list from the active track: an external subtitle file, or for local media an embedded text track extracted with ffmpeg. It parses the cues with `subtitle-cue-parser.ts`, picks a window of upcoming lines from the playback position, and tokenizes them through the live pipeline, storing results in the `SubtitleProcessingController` cache.
+SubMiner can pre-tokenize upcoming subtitle lines before they appear on screen. When an external subtitle file (SRT, VTT, or ASS) is detected on the active track, the `SubtitlePrefetchService` parses all cues via the subtitle cue parser (`subtitle-cue-parser.ts`), identifies a priority window of upcoming lines based on the current playback position, and tokenizes them in the background through the same pipeline used for live subtitles. Results are stored directly into the `SubtitleProcessingController` cache, so when a subtitle actually appears during playback, it hits a warm cache and renders in ~30-50ms instead of ~200-320ms.
 
-Live subtitle processing always takes priority; the prefetcher pauses while the on-screen line is being processed. It recomputes its window on seek and re-prefetches when the cache is invalidated, for example after a word is marked known.
+The prefetcher yields to live subtitle processing (which always takes priority over background work) and re-computes its priority window on seek. Cache invalidation events (e.g. marking a word as known) trigger re-prefetching of the current window to keep results fresh.
 
 ```mermaid
 flowchart TB
@@ -282,7 +399,7 @@ flowchart TB
   classDef runtime fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
   classDef warmup fill:#eed49f,stroke:#494d64,color:#24273a,stroke-width:1.5px
 
-  SubFile["Subtitle Track"]:::init
+  SubFile["External Sub File"]:::init
   Parse["Cue Parser"]:::phase
   Window["Upcoming Lines"]:::phase
   Tokenize["Pre-tokenize"]:::warmup
@@ -299,11 +416,22 @@ flowchart TB
   style Render stroke-width:2px
 ```
 
+## Why this design
+
+- **Smaller blast radius:** changing one feature usually touches one service.
+- **Better testability:** most behavior can be tested without Electron windows/mpv.
+- **Better reviewability:** PRs can be scoped to one subsystem.
+- **Backward compatibility:** CLI flags and IPC channels can remain stable while internals evolve.
+- **Runtime registry + domain barrels:** `src/main/runtime/registry.ts` and `src/main/runtime/domains/*` reduce direct fan-in inside `main.ts` while keeping domain ownership explicit.
+- **Extracted composition root:** `main.ts` delegates to focused modules under `src/main/` and `src/main/runtime/composers/` for lifecycle, IPC, overlay, mpv, shortcut, and integration wiring.
+- **Split MPV service layers:** MPV internals are separated into transport (`mpv-transport.ts`), protocol (`mpv-protocol.ts`), and properties/render metrics modules for maintainability.
+- **Config by domain:** defaults, option registries, and resolution are split by domain under `src/config/definitions/*` and `src/config/resolve/*`, keeping config evolution localized.
+
 ## Extension rules
 
-- Add behavior to a service in `src/core/services/` or a focused module under `src/main/runtime/`. Keep new logic out of `main.ts`.
-- For changes that span startup, overlay, mpv, or integration wiring, compose through `src/main/runtime/domains/` and `src/main/runtime/composers/` instead of wiring directly in `main.ts`.
-- Add a cross-process channel in `src/shared/ipc/contracts.ts` first, validate it in `src/shared/ipc/validators.ts`, then wire the handler. See [IPC + runtime contracts](/ipc-contracts#add-a-new-ipc-action).
-- Config is split by domain under `src/config/definitions/` and `src/config/resolve/`. Keep config changes in the matching domain file.
-- Keep CLI flags and IPC channels stable unless a change is meant to break them.
-- Add or update focused tests when a runtime boundary or contract changes, including malformed-payload tests for IPC.
+- Add behavior to an existing service in `src/core/services/*` or create a focused runtime module under `src/main/runtime/*`; avoid ad-hoc logic in `main.ts`.
+- Add new cross-process channels in `src/shared/ipc/contracts.ts` first, validate payloads in `src/shared/ipc/validators.ts`, then wire handlers in IPC runtime modules.
+- See also the contributor IPC onboarding page: [IPC + Runtime Contracts](/ipc-contracts).
+- If change spans startup/overlay/mpv/integration wiring, prefer composing through `src/main/runtime/domains/*` + `src/main/runtime/composers/*` rather than direct wiring in `main.ts`.
+- Keep service APIs explicit and narrowly scoped, and preserve existing CLI flag / IPC channel behavior unless the change is intentionally breaking.
+- Add or update focused tests (including malformed-payload IPC tests) when runtime boundaries or contracts change.

docs-site/archive-function.test.ts

@@ -1,116 +0,0 @@
-import { expect, test } from 'bun:test';
-import { onRequest, resolveArchiveRoute, type ArchiveBucket } from './functions/v/[[path]]';
-
-// In-memory stand-in for the R2 binding, including the range and precondition behavior
-// the function relies on.
-function fakeBucket(objects: Record<string, string>): ArchiveBucket {
-  return {
-    async get(key, options) {
-      const content = objects[key];
-      if (content === undefined) return null;
-      const bytes = new TextEncoder().encode(content);
-      const httpEtag = `"${key}"`;
-
-      if (options?.onlyIf?.get('if-none-match') === httpEtag) {
-        return { size: bytes.length, httpEtag };
-      }
-
-      const rangeHeader = options?.range?.get('range');
-      const match = rangeHeader ? /^bytes=(\d+)-(\d*)$/.exec(rangeHeader) : null;
-      if (match) {
-        const offset = Number(match[1]);
-        const end = match[2] ? Number(match[2]) : bytes.length - 1;
-        const slice = bytes.slice(offset, end + 1);
-        return {
-          size: bytes.length,
-          httpEtag,
-          range: { offset, length: slice.length },
-          body: new Blob([slice]).stream(),
-        };
-      }
-
-      return { size: bytes.length, httpEtag, body: new Blob([bytes]).stream() };
-    },
-  };
-}
-
-const bucket = fakeBucket({
-  'v/0.19.6/index.html': '<h1>home</h1>',
-  'v/0.19.6/usage.html': '<h1>usage</h1>',
-  'v/0.19.6/404.html': '<h1>missing</h1>',
-  'v/0.19.6/assets/app.abc123.js': 'console.log(1)',
-});
-
-function request(path: string, init?: RequestInit) {
-  return onRequest({
-    request: new Request(`https://docs.subminer.moe${path}`, init),
-    env: { DOCS_ARCHIVES: bucket },
-  });
-}
-
-test('archive routes follow the clean-URL layout of the built archives', () => {
-  expect(resolveArchiveRoute('/v/0.19.6/usage')).toEqual({
-    kind: 'lookup',
-    version: '0.19.6',
-    keys: ['v/0.19.6/usage.html', 'v/0.19.6/usage/index.html'],
-  });
-  expect(resolveArchiveRoute('/v/0.19.6/')).toEqual({
-    kind: 'lookup',
-    version: '0.19.6',
-    keys: ['v/0.19.6/index.html'],
-  });
-  expect(resolveArchiveRoute('/v/0.19.6', '?q=1')).toEqual({
-    kind: 'redirect',
-    location: '/v/0.19.6/?q=1',
-    status: 301,
-  });
-  expect(resolveArchiveRoute('/v/')).toEqual({
-    kind: 'redirect',
-    location: '/versions',
-    status: 302,
-  });
-  expect(resolveArchiveRoute('/v/0.19.6/%2e%2e/secret')).toEqual({ kind: 'not-found' });
-  expect(resolveArchiveRoute('/v/latest/')).toEqual({ kind: 'not-found' });
-});
-
-test('serves archive pages and hashed assets with their cache policy', async () => {
-  const page = await request('/v/0.19.6/usage');
-  expect(page.status).toBe(200);
-  expect(page.headers.get('content-type')).toBe('text/html; charset=utf-8');
-  expect(page.headers.get('cache-control')).toBe('public, max-age=3600');
-  expect(page.headers.get('x-robots-tag')).toBe('noindex, follow');
-  expect(await page.text()).toBe('<h1>usage</h1>');
-
-  const asset = await request('/v/0.19.6/assets/app.abc123.js');
-  expect(asset.headers.get('content-type')).toBe('text/javascript; charset=utf-8');
-  expect(asset.headers.get('cache-control')).toContain('immutable');
-});
-
-test('missing archive pages fall back to the archive 404 page', async () => {
-  const response = await request('/v/0.19.6/nope');
-  expect(response.status).toBe(404);
-  expect(await response.text()).toBe('<h1>missing</h1>');
-
-  const unknownVersion = await request('/v/0.1.0/usage');
-  expect(unknownVersion.status).toBe(404);
-});
-
-test('supports byte ranges, conditional requests, and HEAD', async () => {
-  const partial = await request('/v/0.19.6/usage', { headers: { Range: 'bytes=4-8' } });
-  expect(partial.status).toBe(206);
-  expect(partial.headers.get('content-range')).toBe('bytes 4-8/14');
-  expect(await partial.text()).toBe('usage');
-
-  const notModified = await request('/v/0.19.6/usage', {
-    headers: { 'If-None-Match': '"v/0.19.6/usage.html"' },
-  });
-  expect(notModified.status).toBe(304);
-
-  const head = await request('/v/0.19.6/usage', { method: 'HEAD' });
-  expect(head.status).toBe(200);
-  expect(head.headers.get('content-length')).toBe('14');
-  expect(await head.text()).toBe('');
-
-  const post = await request('/v/0.19.6/usage', { method: 'POST' });
-  expect(post.status).toBe(405);
-});

docs-site/changelog.md

@@ -1,182 +1,6 @@
 # Changelog
 
-## v0.20.1 (2026-10-03)
-
-**Added**
-- **YouTube Browser Window**:
-  - Browse YouTube with your login kept across restarts. Open it with `subminer youtube`, `subminer yt`, or tray **Browse YouTube**.
-  - Clicking a video plays it in mpv. Middle-click, Shift/Ctrl-click, or the right-click menu adds it to mpv's playlist.
-  - Queued videos get the same Japanese subtitle setup, and the rest of the queue is kept on Windows.
-  - Closing the window quits a SubMiner started by `subminer youtube`.
-- **Whisper Subtitles for YouTube**:
-  - Set `youtube.subtitleSource` to `whisper` to transcribe YouTube videos with Whisper instead of using YouTube's captions.
-  - The video stays paused while Whisper transcribes, and the subtitle generation modal shows progress.
-  - The subtitle generation modal (`Ctrl+Shift+G`) now works on YouTube videos, including Windows stream playback.
-- **Scroll Wheel and Mouse Bindings**: `keybindings` now accepts scroll wheel keys, and the settings key editor can capture them. Mouse button and wheel bindings from mpv now work while the cursor is over the overlay, including on Hyprland.
-- **Run Commands from Session Help**: During playback, press `Enter` or double-click a row in session help to run that command.
-
-**Changed**
-- **Release Assets**: Releases no longer include package-size reports.
-
-**Fixed**
-- **Hyprland Overlay**: The overlay stays clickable after mpv goes fullscreen with `mpv.backend: x11`, and it no longer interrupts mpv while mpv enters fullscreen.
-- **mpv Key Bindings**: Bindings from mpv such as `9`/`0` for volume now work while the overlay has focus, even if the overlay loaded before mpv connected.
-- **Jellyfin**:
-  - The Japanese subtitle track is selected as soon as it downloads, without waiting for the other tracks.
-  - Japanese and English tracks are auto-selected on episodes whose embedded subtitles are images.
-  - Timing review previews and mined card audio use the audio track you are playing.
-- **Media Timing Review**: Trim handles are now thin lines on the clip edges, and original subtitle boundaries no longer cover the waveform. The preview cursor no longer stutters on macOS with Bluetooth headphones.
-- **YouTube Subtitles**: Japanese subtitles no longer fail with "HTTP 429" on videos where YouTube also lists a machine-translated Japanese track.
-- **Stats**:
-  - Mined cards are counted once in session and lifetime stats.
-  - Word and kanji dates and the new-words charts stay accurate after deleting sessions. Existing data is repaired in the background.
-  - Overview totals, charts, and the activity calendar refresh after deleting sessions.
-- **Yomitan Data Safety**: Electron is updated to 43.7.7. SubMiner now refuses to load your Yomitan data with an unsupported or downgraded runtime. Automatic character dictionary changes stop if Yomitan suddenly reports no dictionaries.
-- **AppImage in Sandboxes**: The AppImage now opens its window when launched in a sandbox such as `firejail --appimage`.
-- **Ctrl+C Crash**: SubMiner no longer crashes with "write EPIPE" when the terminal command that started it is stopped with Ctrl+C.
-
-**Docs**
-- **Docs Site**: The docs site is shorter and easier to scan, with a key and default table for each config block. Outdated pages were corrected, and the MeCab install command for Arch Linux is fixed.
-- **Stats Docs**: The docs now cover the Overview refresh after deleting sessions and how discovery dates are kept after old sessions are pruned.
-
-<details>
-<summary>Internal changes</summary>
-
-**Internal**
-- **Release Notes**: Release notes and `CHANGELOG.md` are now generated as short items per feature or area.
-- **Dev Profile**: Development launches use a separate `SubMiner-dev` profile unless production-profile access is requested.
-- **Dependencies**: undici is updated to 7.29.1 to clear the security advisories that were blocking CI.
-- **Package Checks**: CI no longer compares package sizes. Package content checks still run.
-
-</details>
-
-## v0.20.0 (2026-09-23)
-
-**Added**
-- **Japanese Subtitle Generation**:
-  - Generate Japanese SRT subtitles locally with whisper.cpp. Start it from a new modal (Ctrl+Shift+G), from the generate button in an empty subtitle sidebar, or with `subminer generate-subs`.
-  - Generation shows progress, can be cancelled, and loads the finished subtitles into mpv automatically.
-  - Pick an official multilingual Whisper model, including quantized variants, with size and accuracy guidance. You can download it in the app or point Settings at a model you already have.
-  - `large-v3-turbo` is recommended when CUDA support is detected, and `small` otherwise.
-  - whisper-cli, ffmpeg, and ffprobe are found on PATH unless you override them. SubMiner names any missing tools before a download starts.
-  - An optional "Focus on spoken dialogue" mode uses a separately downloaded Silero VAD model. It keeps audible sections it is unsure about, so dialogue under music is not dropped, but songs may also be transcribed.
-  - Long passages are split near speech starts or quiet pauses to reduce subtitles that appear too early. When an eligible embedded or external subtitle track is loaded in mpv, it guides the split points.
-  - Each passage runs in a fresh Whisper process, which prevents repeated-character output.
-- **Subtitle Selection Modal**:
-  - An optional modal for choosing primary and secondary mpv subtitle tracks.
-  - Turn it on in Settings under Behavior, then press g followed by s to open it. Turning it off restores mpv's own subtitle selection binding.
-  - Single-key actions take priority over configured key sequence prefixes.
-  - Conflicting sequences are disabled with a warning, and the existing y commands stay reserved.
-- **Subtitle Sidebar Copy**:
-  - Select dialogue across several sidebar rows and copy it without timestamps using Ctrl/Cmd+C or the Copy button.
-  - Selecting text does not seek playback and does not require mining a card.
-- **Media Timing Review Screenshot Picker**:
-  - Choose the still screenshot separately from the audio range, with a live preview and its own time slider.
-  - Step through decoded frames one at a time to get the exact frame you want.
-  - Works with local video and with seekable remote streams such as Jellyfin.
-- **mpv Keybindings in the Overlay**:
-  - The overlay now picks up keyboard bindings from mpv defaults, `input.conf`, and loaded scripts when they do not conflict with SubMiner.
-  - SubMiner controls and bindings you explicitly disabled take precedence.
-  - These bindings apply only to the current session and are not listed in the help menu.
-- **Jimaku Live Action Search**: The Jimaku modal has new Anime and Live action tabs, so you can search Jimaku's live action catalogue as well as anime. Use Arrow Left and Arrow Right to switch tabs.
-- **TMDB Live-Action Library**:
-  - Live-action dramas and movies in the stats Library now get posters, synopses, and titles from TMDB.
-  - Release builds include a project key. Setting `tmdb.apiKey` or `tmdb.apiKeyCommand` overrides it, and one of them is required when running from source.
-  - Titles that AniList cannot match are looked up on TMDB automatically when the parsed filename exactly matches a Japanese live-action title. For everything else, use the new **Link to TMDB** action.
-  - Entries linked to the same TMDB title merge into one card, and the Library kind selector has a new Live Action option.
-  - If a replacement download fails during provider reassignment, the previous link and artwork are kept. Merges and sync keep AniList and TMDB identities separate, and the merge dialog explains mixed selections instead of failing.
-- **YouTube Library Kind**:
-  - YouTube channels are now their own Library media kind. Existing channel entries migrate automatically, and viewing history and manual video assignments are unchanged.
-  - New All Titles, Anime, and YouTube Library filters.
-  - Channels are excluded from AniList matching, season repair, and duplicate recommendations.
-  - Merges and video moves can no longer combine an anime entry with a YouTube channel.
-
-**Changed**
-- **Launcher Uses Bundled Bun**:
-  - Every installed and downloadable launcher now runs on the Bun runtime that ships with SubMiner. A system Bun is no longer needed.
-  - Recognized legacy launchers migrate automatically.
-  - Windows gets a `subminer.cmd` launcher download.
-  - First-run setup is reduced to one optional launcher control. Runtime repair guidance appears only when it is needed.
-- **Faster Sync Transfers**:
-  - Sync between compatible macOS and Linux machines now uses compressed, incremental rsync transfers.
-  - The last snapshot received from each peer is cached, which reduces traffic on later syncs.
-  - Machines without a compatible rsync, including Windows, fall back to compressed scp.
-  - Older peers still work without the upload cache.
-  - Transfers abort after 30 minutes.
-- **Stats Server Request Safety**:
-  - The stats server now accepts loopback hosts only and rejects requests from browser origins other than its own.
-  - Requests that change data must send an `application/json` body. Scripts that POST to the server need to set a JSON content type.
-  - The in-app stats overlay now loads from the local server, so it gets the same protection.
-  - Dashboards served through a reverse proxy or Tailscale Serve are no longer supported.
-- **Smaller Downloads**:
-  - Installers and unpacked apps are smaller. Demo media, source maps, TypeScript sources, test fixtures, and unused Koffi binaries are no longer packaged.
-  - All windows now share one Japanese UI font.
-  - Release builds publish package size reports that compare against the previous release.
-- **Bundled Yomitan**: Updated with upstream Yomitan 26.9.8 changes, including historical Japanese kana transformations, Ukrainian language support, and improvements to Anki duplicate searches and audio retrieval.
-
-**Fixed**
-- **Jellyfin 12 Compatibility**:
-  - Playback, subtitle, artwork, and remote-control requests now authenticate with the `ApiKey` query parameter, so the integration works on Jellyfin 12, where legacy authorization is off by default.
-  - "Play on SubMiner" stays available. The cast connection now answers keep-alive requests and reconnects when the server stops responding, instead of silently dying after about a minute.
-  - The Jellyfin "now playing" bar clears when you close or finish a cast video instead of running on to the end of the episode.
-  - Cards mined during Jellyfin playback get the episode title in the misc info field again instead of "Unknown media".
-- **Jellyfin Privacy and Playback**:
-  - Jellyfin streams no longer leak titles taken from the stream URL, or stream URLs that contain credentials, into metadata lookups, Anki source fields, Discord presence, stats, or AniList retries.
-  - Previously cached metadata that contained credentials is cleaned up. Watch history and library assignments are not touched.
-  - Jellyfin playback and casting now use your configured mpv executable, so they work when mpv is installed outside PATH. Portable plugins next to that executable are detected.
-- **Anki Mining**:
-  - New `ankiConnect.fields.wordAudio` setting reads word audio separately from the sentence audio field. This fixes animated images that started moving immediately when `fields.audio` pointed to `SentenceAudio`. Existing animated images need to be regenerated to pick up the fix.
-  - Sentence furigana on word cards stays in sync with the full stats-search context and with expanded timing review selections. Stale readings are cleared if regeneration fails.
-  - Closing the overlay while media timing review is still loading now cancels the review, resumes playback if the review paused it, and cleans up the hidden preview player.
-  - `ankiConnect.media.maxMediaDuration: 0` now means unlimited when mining from the stats dashboard, matching overlay mining.
-  - Invalid AnkiConnect, Kiku, and Senren settings are now rejected with a warning and fall back to defaults.
-- **Stats Server Stability**:
-  - A port conflict is now reported in a status notification instead of crashing SubMiner.
-  - Simultaneous startup requests share one server start. Stopping the background server no longer disconnects dashboards open in the foreground.
-  - Shutdown waits only a limited time for active requests to finish.
-  - Malformed resource IDs, and ID lists with any invalid entries, are rejected before Library changes or cover backfills run.
-- **Subtitle Sidebar**:
-  - Clicking a cue no longer leaves the row focused, and Space no longer seeks back to a focused cue. Enter still seeks to the focused cue, and Space keeps its configured playback action.
-  - The sidebar stays near the current playback position during gaps when the subtitle file has a cue that starts at zero.
-- **Settings Save Feedback**:
-  - Settings marked LIVE no longer show false restart warnings, including for notifications and subtitle generation.
-  - When a save mixes live and restart-only changes, the live changes apply right away and only the changed sections that need a restart are listed.
-- **Overlay Windows**:
-  - On Hyprland, recovery dialogs stay above SubMiner windows so overlay placement updates no longer cover their Wait and Close buttons.
-  - On Linux, a delayed close callback during teardown can no longer reopen the overlay.
-- **First Launch on macOS**: SubMiner no longer exits on first launch when the config directory does not exist yet.
-
-**Docs**
-- **Launcher**: Documented the launcher install that uses the bundled runtime, migration from legacy launchers, package-managed updates, and the bundled Bun runtime's MIT and LGPL notices. The AUR package installs these notices under `/usr/share/licenses/subminer-bin`, and they are also included in `subminer-assets.tar.gz`.
-- **Subtitle Generation**: Documented model choice, VAD behavior, splitting guided by a reference track, fallback behavior, and known limits.
-- **Subtitle Selection**: Documented the subtitle selector setting, its shortcut override, and the primary and secondary track controls.
-- **Settings**: Clarified save feedback for live settings, warnings for saves that mix live and restart-only changes, and how subtitle generation settings reload.
-- **Jellyfin**:
-  - Clarified that Windows mpv playback and Jellyfin casting can use a configured executable path instead of PATH.
-  - Documented how Jellyfin media titles and stats identities keep stream credentials out of metadata.
-- **Stats Library**:
-  - Documented TMDB linking, provider reassignment, merge compatibility, and caching of the credential command's output.
-  - Documented YouTube channel filtering and video statistics in the Library.
-- **Mining**:
-  - Documented choosing the screenshot separately in media timing review.
-  - Documented the separate word audio field mapping, including that existing animated images need to be regenerated.
-- **Sync**: Documented compressed transfers, where the incremental sync cache is stored, and compatibility with older peers.
-
-<details>
-<summary>Internal changes</summary>
-
-**Internal**
-- Removed duplicate source and launcher smoke runs from the reusable CI quality gate. Every distinct test lane and failure artifact is kept.
-- Replaced mislabeled dist source reruns with a small Electron-runtime smoke check. It covers compiled stats startup, the HTTP service, native SQLite, port conflicts, and cleanup.
-
-</details>
-
-## Previous Versions
-
-<details>
-<summary>v0.19.x</summary>
-
-<h2>v0.19.6 (2026-09-04)</h2>
+## v0.19.6 (2026-09-04)
 
 **Added**
 
@@ -207,7 +31,7 @@
 - **Jellyfin Subtitle Sync**: Jellyfin subtitle files now load with zero mpv delay instead of inferring and saving an offset from Japanese and English cue timelines.
 - **Secondary Subtitle Visibility**: Native mpv secondary subtitles stay hidden when switching secondary subtitle tracks during playback.
 
-<h2>v0.19.5 (2026-08-30)</h2>
+## v0.19.5 (2026-08-30)
 
 **Fixed**
 
@@ -222,7 +46,7 @@
   - Long speech is paged instead of covering the video with a wall of text.
   - Explicitly timed sound cues like `[音楽]` no longer cover later dialogue.
 
-<h2>v0.19.4 (2026-08-25)</h2>
+## v0.19.4 (2026-08-25)
 
 **Added**
 - **Library Merge & Move**: Duplicate library cards for the same show can now be combined. Select cards in the library grid and use "Merge Selected" to pick which entry to keep and move every episode onto it, preserving sessions, mined cards, and watch time. Episodes can also be reassigned individually via the "→" button, useful when a file lands under a stray title; manual assignments survive later filename parsing, Jellyfin refreshes, and season repair. Exact AniList title matches with compatible seasons now merge automatically, while fuzzy matches surface as dismissible "Possible duplicate" reviews instead of merging silently.
@@ -263,7 +87,7 @@
 
 </details>
 
-<h2>v0.19.3 (2026-08-13)</h2>
+## v0.19.3 (2026-08-13)
 
 **Added**
 - Changelog Modal: Adds an in-app changelog you can open from the tray ("View Changelog") or the "What's New" button on the update notification, so the notification stays reachable while you read. It shows the newest published release notes (falling back to the bundled changelog if that fetch fails), folds older versions while keeping the current one expanded, and supports keyboard navigation (`J`/`K`/arrows, `Enter`, `R`, `Esc`).
@@ -287,7 +111,7 @@
 
 </details>
 
-<h2>v0.19.2 (2026-08-04)</h2>
+## v0.19.2 (2026-08-04)
 
 **Changed**
 - Subsync: The sync modal now lets you choose both the reference subtitle (correct timing) and the out-of-sync subtitle to retime, for both alass and ffsubsync. alass can also use the loaded video's audio as a reference for local files. Retiming the secondary track now reloads the result into the secondary slot instead of overwriting the primary subtitle.
@@ -305,7 +129,7 @@
 
 </details>
 
-<h2>v0.19.1 (2026-08-01)</h2>
+## v0.19.1 (2026-08-01)
 
 **Added**
 - Word Card Type: Adds a setting (Settings > Mining/Anki > Kiku/Lapis Features > "Word Card Type") to choose which card-type flag SubMiner marks on Kiku/Lapis word cards — `word-and-sentence` (default), `click`, `sentence`, `audio`, or `none`. Click cards (`IsClickCard`) can now be flagged, and setting any card-type flag clears the others so a note can't claim two types at once.
@@ -314,7 +138,7 @@
 - Yomitan Popup: Fixes the macOS Yomitan popup going inert after mining a card — clicks outside the popup no longer pass through to mpv, and scrolling over the popup scrolls its definitions instead of seeking playback.
 - YouTube Playlist Links: Fixes opening a video from a playlist URL (e.g. a Watch Later link with `list=`/`index=`) timing out while probing subtitles, metadata, or the playback URL.
 
-<h2>v0.19.0 (2026-07-29)</h2>
+## v0.19.0 (2026-07-29)
 
 **Added**
 - Anki Maturity Highlighting: Known-word subtitle highlights can now be colored by Anki card maturity (new, learning, young, mature), similar to asbplayer. Tier thresholds and colors are configurable, with a runtime toggle and an updated help legend.
@@ -350,7 +174,7 @@
 
 </details>
 
-</details>
+## Previous Versions
 
 <details>
 <summary>v0.18.x</summary>

docs-site/character-dictionary.md

@@ -1,104 +1,315 @@
 # Character dictionary
 
-SubMiner builds a Yomitan dictionary of the characters in the show you are watching, using data from [AniList](https://anilist.co). Character names in subtitles get their own color, and hovering one shows the character's portrait, role, voice actor, and description.
+SubMiner builds a Yomitan-compatible dictionary of a show's characters from [AniList](https://anilist.co), the online anime and manga database. Once it is loaded, character names in subtitles get recognized and highlighted, and hovering one shows the portrait, role, voice actor, and biography without leaving the overlay.
 
-Ordinary dictionaries rarely contain character names, so without this every name counts as an unknown word and throws off [N+1 highlighting](/subtitle-annotations#n-1-word-highlighting).
+Proper names rarely appear in ordinary dictionaries, so without this every character name reads as an unknown word. That wrecks N+1 highlighting, since a line naming two characters looks like a line with two unknowns. Recognizing them keeps the highlighting pointed at real vocabulary.
 
-## Turning it on
+The dictionary is generated per-media, merged across your recently-watched titles, and auto-imported into Yomitan. When a character name appears in a subtitle line, it gets highlighted and becomes available for hover-driven Yomitan profile lookup.
 
-1. Set `subtitleStyle.nameMatchEnabled` to `true`, or turn it on in the Settings window under Annotation Display, Character Names.
-2. Optionally set `subtitleStyle.nameMatchImagesEnabled` to `true` to show a small portrait next to each name in the subtitle line.
-3. Play an episode.
+## How it works
+
+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.
+
+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.
+
+## 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, which needs no authentication, and imports the merged dictionary into Yomitan.
+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,
+    "nameMatchImagesEnabled": true, // optional - inline portraits
   },
 }
 ```
 
-No AniList account is needed. Logging in to AniList is only for [watch progress sync](/anilist-integration).
+::: tip
+The first sync for a media title takes a few seconds while character data and portraits are fetched from AniList. Subsequent launches reuse the cached media match and snapshot without a fresh AniList lookup.
 
-The character dictionary does not work when `yomitan.externalProfilePath` is set, because SubMiner then uses another app's Yomitan profile read-only.
+Dictionary sync does not require a loaded Japanese subtitle track. Once Yomitan is ready, SubMiner can reuse an installed character dictionary even before the first subtitle is processed. If Yomitan readiness times out, the status reports a failure instead of staying on **Checking**.
+:::
 
-## What happens when you play something
+::: 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.
+:::
 
-When a new show starts, SubMiner:
+::: warning
+If `yomitan.externalProfilePath` is set, SubMiner switches to read-only external-profile mode. In that mode SubMiner can reuse another app's installed Yomitan dictionaries/settings, but SubMiner's own character-dictionary features are fully disabled.
+:::
 
-1. Guesses the title from the filename and finds it on AniList.
-2. Downloads the cast list and portraits.
-3. Builds the dictionary and imports it into SubMiner's Yomitan.
+## Name generation
 
-A notification shows each step. Once it says the dictionary is ready, names match from the next subtitle line.
+A single character produces many searchable terms so that names are recognized regardless of how they appear in dialogue. SubMiner generates variants for:
 
-Each character gets entries for the full name, family name, given name, and common honorifics (`さん`, `君`, `ちゃん`, `先生`, and others), so `太郎さん` matches as well as `太郎`.
+**Spacing and combination:**
 
-SubMiner keeps your most recent shows loaded in one merged dictionary. `anilist.characterDictionary.maxLoaded` sets how many. Starting another show drops the oldest one. Only the current show's characters are highlighted.
+- Full name with space: 須々木 心一
+- Combined form: 須々木心一
+- Family name alone: 須々木
+- Given name alone: 心一
 
-### How long it takes
+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. That guess can be ambiguous, since 東紫乃 could be 東+紫乃 or 東紫+乃, so SubMiner generates terms for the top two candidate boundaries and the real surname still matches. Snapshots built without MeCab are regenerated automatically once MeCab becomes available, upgrading them to the exact splits.
 
-The first time you watch a show, most of the time goes into downloading portraits, one at a time. A typical cast takes seconds to a minute. A very large cast takes much longer: One Piece has over a thousand characters and takes around 10 minutes. After that the show is cached, and later episodes load it from disk.
+**Middle-dot removal** (common in katakana foreign names):
+
+- ア・リ・ス → アリス (combined), plus individual segments
+
+**Honorific suffixes** - each base name is expanded with 15 common suffixes:
+
+| Honorific | Reading    |
+| --------- | ---------- |
+| さん      | さん       |
+| 様        | さま       |
+| 先生      | せんせい   |
+| 先輩      | せんぱい   |
+| 後輩      | こうはい   |
+| 氏        | し         |
+| 君        | くん       |
+| くん      | くん       |
+| ちゃん    | ちゃん     |
+| たん      | たん       |
+| 坊        | ぼう       |
+| 殿        | どの       |
+| 博士      | はかせ     |
+| 社長      | しゃちょう |
+| 部長      | ぶちょう   |
+
+**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.
+
+## 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'`.
+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`).
+6. If `subtitleStyle.nameMatchImagesEnabled` is enabled, the renderer also injects a small circular AniList portrait from the cached snapshot image data.
+
+Older snapshot schema versions are regenerated automatically. Current-version snapshots are normally reused, but when `subtitleStyle.nameMatchImagesEnabled` is enabled SubMiner also checks whether the cached snapshot contains usable character portrait data. If it does not, the snapshot is refreshed so the merged dictionary can include images.
+
+Name matches are visually distinct from [N+1 targeting, frequency highlighting, and JLPT tags](/subtitle-annotations) so you can tell at a glance whether a highlighted word is a character name or a vocabulary target.
+
+**Key settings:**
+
+| Option                                 | Default   | Description                               |
+| -------------------------------------- | --------- | ----------------------------------------- |
+| `subtitleStyle.nameMatchEnabled`       | `false`   | Enable dictionary sync and highlighting   |
+| `subtitleStyle.nameMatchImagesEnabled` | `false`   | Show small AniList portraits beside names |
+| `subtitleStyle.nameMatchColor`         | `#f5bde6` | Highlight color for matched names         |
+
+## Inline character portraits
+
+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/`.
+
+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.
+
+**To enable:**
+
+- Settings → Subtitle Style → **Name Match Images**, or
+- `subtitleStyle.nameMatchImagesEnabled: true` in config.
+
+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.
+:::
+
+## 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 / "Protagonist" (score 100), primary / "Main Character" (75), side / "Side Character" (50), appears / "Minor Role" (25). AniList's MAIN maps to main, SUPPORTING to primary, and BACKGROUND to side.
+- **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:
+
+```jsonc
+{
+  "anilist": {
+    "characterDictionary": {
+      "collapsibleSections": {
+        "description": false,
+        "characterInformation": false,
+        "voicedBy": false,
+      },
+    },
+  },
+}
+```
+
+## Auto-sync lifecycle
+
+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. MRU update (no notification) - add the media ID to the most-recently-used list and 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 when the installed revision differs. Dictionary checks and settings updates wait for the extension to be ready, independently of subtitle processing. Readiness and quick operations have bounded timeouts; imports have a separate budget that grows with the ZIP size.
+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.
+
+```jsonc
+{
+  "activeMediaIds": ["170942 - Frieren", "163134 - ...", "154587 - ..."],
+  "mergedRevision": "a1b2c3d4e5f6",
+  "mergedDictionaryTitle": "SubMiner Character Dictionary",
+}
+```
+
+(Entries are `"<mediaId> - <title>"` label strings; bare numeric IDs from older versions are still read.)
+
+The `maxLoaded` setting (default: 3) controls how many media snapshots stay in the active set. When you start a 4th title, the oldest is evicted and the merged dictionary is rebuilt without it.
+
+## Manual generation
+
+You can generate a character dictionary from the command line without auto-sync:
+
+```bash
+# Generate for a file or directory
+subminer dictionary /path/to/media
+
+# Generate for current anime (AppImage)
+SubMiner.AppImage --dictionary
+```
+
+This creates a standalone dictionary ZIP for the target media and saves it alongside the snapshots.
 
 ## Correcting AniList matches
 
-SubMiner can match the wrong show when a filename is ambiguous, for example `Re - ZERO, Starting Life in Another World (2016)` matching a different `Re...` series. To fix it:
+SubMiner uses `guessit` to infer the anime title from the active filename before searching AniList. Some filenames can still resolve to the wrong title. For example, `Re - ZERO, Starting Life in Another World (2016)` can be misread as a different `Re...` series.
 
-1. Press `Ctrl/Cmd+D` to open the character dictionary manager.
-2. Click **Override**, edit the title if needed, search, and pick the right result.
+Use the in-app selector or CLI to pin the correct AniList media for the whole series:
 
-From the command line:
+- In-app: open the manager with `Ctrl/Cmd+D`, use the **Override** tab/button, edit the prefilled title if needed, then search and choose the correct result.
+- CLI: `--dictionary-candidates` still lists matches for the current filename guess.
 
 ```bash
-# List AniList matches for a file
+# List candidate AniList matches for a file
 subminer dictionary --candidates "/path/to/episode.mkv"
 
-# Save the correct AniList ID for that series
+# Save the correct AniList media ID for that series
 subminer dictionary --select 21355 "/path/to/episode.mkv"
+
+# Equivalent direct app flags
+SubMiner.AppImage --dictionary-candidates --dictionary-target "/path/to/episode.mkv"
+SubMiner.AppImage --dictionary-select --dictionary-anilist-id 21355 --dictionary-target "/path/to/episode.mkv"
+
+# Open the in-app selector from the running app
+subminer app --session-action '{"actionId":"openCharacterDictionaryManager"}'
 ```
 
-The override applies to every episode of that season in the same folder. Other seasons are not affected, even when they share the folder. The override also sets which entry [AniList watch progress](/anilist-integration) updates, so one fix covers both.
+SubMiner stores manual selections in `character-dictionaries/anilist-overrides.json`. The episode's parent directory **and detected season** define the override scope, so later episodes in the same season keep the selected AniList ID even if their filename guesses differ, while a different season never inherits the override - including when every season sits in one flat folder. When you replace a wrong match, SubMiner removes that stale media ID from the merged dictionary's active set and rebuilds/imports the merged character dictionary.
 
-## Managing loaded shows
+An override also pins the entry used for [AniList watch progress](/anilist-integration), so correcting a wrong match once fixes both the character dictionary and progress tracking.
 
-The manager (`Ctrl/Cmd+D`) lists the shows in the merged dictionary and marks the current one.
+## Managing loaded entries
 
-- **Remove** drops a show from the dictionary. You cannot remove the show you are watching.
-- **Up/Down** changes which show gets dropped first when a new one is added.
-- **Override** replaces a show's AniList match.
+Open the manager with `Ctrl/Cmd+D` (`shortcuts.openCharacterDictionaryManager`). The manager shows the merged dictionary's active MRU entries, marks the current anime, and lets you adjust eviction priority for the other loaded entries.
 
-## Generating from the command line
+- **Remove** drops a non-current entry from the active merged dictionary and rebuilds/imports once.
+- **Up/Down** changes MRU order for future eviction; the merged dictionary is rebuilt and re-imported after a reorder.
+- **Override** opens the AniList selector for that entry's title so you can replace a saved loaded entry.
 
-```bash
-subminer dictionary /path/to/media
+The current anime cannot be removed while you are watching it; it stays loaded until playback changes.
+
+## File structure
+
+All character dictionary data lives under `{userData}/character-dictionaries/`:
+
+```text
+character-dictionaries/
+  snapshots/
+    anilist-170942.json       # Per-media character snapshot
+    anilist-163134.json
+  merged.zip                  # Active merged dictionary (imported into Yomitan)
+  auto-sync-state.json        # Tracks active media IDs and revision
+  anilist-overrides.json      # Manual series-to-AniList overrides
+  img/
+    m170942-c12345.jpg        # Character portrait
+    m170942-va67890.jpg       # Voice actor portrait
 ```
 
-This builds a standalone dictionary file for that file or folder without playing it. With the AppImage directly, use `SubMiner.AppImage --dictionary`.
+**Snapshot format** (v19, `CHARACTER_DICTIONARY_FORMAT_VERSION`): each snapshot contains the media ID, title, entry count, timestamp, an array of Yomitan term entries, and base64-encoded images. Snapshots with a different format version are regenerated.
 
-## Configuration
+**ZIP structure** follows the Yomitan dictionary format:
 
-Defaults are in the [configuration reference](/configuration).
+```text
+merged.zip
+  index.json                  # { title, revision, format: 3, author: "SubMiner", description }
+  tag_bank_1.json             # Tag definitions
+  term_bank_1.json            # Up to 10,000 terms per bank
+  term_bank_2.json
+  img/                        # Embedded character and VA portraits
+```
 
-| Key                                                                    | What it does                                     |
-| ---------------------------------------------------------------------- | ------------------------------------------------ |
-| `subtitleStyle.nameMatchEnabled`                                       | Build the dictionary and color character names   |
-| `subtitleStyle.nameMatchImagesEnabled`                                 | Show a portrait next to matched names            |
-| `subtitleStyle.nameMatchColor`                                         | Color for character names                        |
-| `anilist.characterDictionary.maxLoaded`                                | Number of recent shows kept in the dictionary    |
-| `anilist.characterDictionary.collapsibleSections.description`          | Show the description expanded in the popup       |
-| `anilist.characterDictionary.collapsibleSections.characterInformation` | Show age, birthday, and similar details expanded |
-| `anilist.characterDictionary.collapsibleSections.voicedBy`             | Show the voice actor section expanded            |
-| `shortcuts.openCharacterDictionaryManager`                             | Shortcut for the manager                         |
+## Configuration reference
+
+| Option                                                                 | Default   | Description                                                     |
+| ---------------------------------------------------------------------- | --------- | --------------------------------------------------------------- |
+| `anilist.characterDictionary.maxLoaded`                                | `3`       | Number of recent media snapshots kept in the merged dictionary  |
+| `anilist.characterDictionary.profileScope`                             | `"all"`   | Apply dictionary to `"all"` Yomitan profiles or `"active"` only |
+| `anilist.characterDictionary.collapsibleSections.description`          | `false`   | Start Description section expanded                              |
+| `anilist.characterDictionary.collapsibleSections.characterInformation` | `false`   | Start Character Information section expanded                    |
+| `anilist.characterDictionary.collapsibleSections.voicedBy`             | `false`   | Start Voiced By section expanded                                |
+| `subtitleStyle.nameMatchEnabled`                                       | `false`   | Enable character-dictionary sync and name highlighting          |
+| `subtitleStyle.nameMatchImagesEnabled`                                 | `false`   | Show small AniList portraits beside matched names               |
+| `subtitleStyle.nameMatchColor`                                         | `#f5bde6` | Highlight color for character-name matches                      |
+
+## 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.
+
+The reference implementation covers the same ground: name variant generation, honorific expansion, structured Yomitan content, and portrait embedding. It also reads VNDB as a source for visual novel characters. Key differences:
+
+|                        | SubMiner                                     | Reference Implementation              |
+| ---------------------- | -------------------------------------------- | ------------------------------------- |
+| **Runtime**            | TypeScript, runs inside Electron             | Rust, standalone web service          |
+| **Data sources**       | AniList only                                 | AniList + VNDB                        |
+| **Delivery**           | Auto-synced into bundled Yomitan             | ZIP download via web UI               |
+| **Honorific strategy** | Eager generation at build time               | Lazy generation during ZIP export     |
+| **Caching**            | File-based snapshots                         | Multi-tier (memory + disk + SQLite)   |
+| **Updates**            | Revision-hashed; skips reimport if unchanged | URL-encoded settings for auto-refresh |
+
+If you work with visual novels or want a standalone dictionary generator independent of SubMiner, the reference implementation is worth checking out.
 
 ## Troubleshooting
 
-**It seems stuck.** Check the notification. While generating it shows counts (`image 120/400`), an estimate of time left, and an elapsed clock. If the clock moves, it is still working, and large casts are slow (see [how long it takes](#how-long-it-takes)). If you missed the notification, open the notification history with `Ctrl/Cmd+N`. For errors, check the app log ([log locations](/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.
+- **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.
+- **Yomitan import fails:** SubMiner waits up to 7 seconds for Yomitan to be ready for mutations. If Yomitan is still loading dictionaries or performing another import, the operation may time out. Restarting the overlay typically resolves this.
+- **Portraits missing:** Images are downloaded from AniList CDN during snapshot generation. If the network was unavailable during the initial sync, delete the snapshot file from `character-dictionaries/snapshots/` and let it regenerate.
 
-**Import failed or timed out.** Yomitan may have been busy importing another dictionary. Play the next episode or restart SubMiner. The import may have finished anyway, so check for the character popup before retrying.
+## Related
 
-**Names are not highlighted.** Check that `subtitleStyle.nameMatchEnabled` is `true`, that `yomitan.externalProfilePath` is empty, and that the show was found on AniList. The wrong show's cast means a wrong match. See [correcting AniList matches](#correcting-anilist-matches).
-
-**Portraits are missing.** Portraits need AniList to have an image and the download to succeed. If you were offline during the first sync, delete that show's file from `character-dictionaries/snapshots/` in the SubMiner config directory and replay it.
-
-SubMiner's generator is based on the [Japanese Character Name Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary) project, which also supports VNDB and works without SubMiner.
+- [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

docs-site/demos.md

@@ -2,7 +2,7 @@
 
 Short recordings from real playback sessions.
 
-_Yomitan_ is the pop-up dictionary. _Jimaku_ is a community subtitle database. _alass_ and _ffsubsync_ retime subtitles against the audio. _Jellyfin_ is a self-hosted media server. A _texthooker_ is a web page that mirrors the current subtitle as selectable text.
+Some vocabulary for what follows. _Yomitan_ is the pop-up dictionary. _Jimaku_ is a community subtitle database. _alass_ and _ffsubsync_ retime subtitles against the audio. _Jellyfin_ is a self-hosted media server. A _texthooker_ is a web page that mirrors the current subtitle as selectable text so browser tools can read it.
 
 <script setup>
 import { withBase } from 'vitepress';
@@ -18,7 +18,7 @@ Mine a card from Yomitan or straight from a subtitle line. SubMiner attaches the
   <source :src="withBase(`/assets/minecard.webm?v=${v}`)" type="video/webm" />
   <source :src="withBase(`/assets/minecard.mp4?v=${v}`)" type="video/mp4" />
   <a :href="withBase(`/assets/minecard.webm?v=${v}`)" target="_blank" rel="noreferrer">
-    <img :src="withBase(`/assets/minecard.webp?v=${v}`)" alt="Animated demo of mining a card" style="width: 100%; height: auto;" />
+    <img :src="withBase(`/assets/minecard.webp?v=${v}`)" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />
   </a>
 </video>
 
@@ -36,7 +36,7 @@ Search Jimaku, download a track, then retime it with alass or ffsubsync without
 
 ## Jellyfin integration
 
-Browse your Jellyfin library and play from SubMiner, or cast to SubMiner from another Jellyfin client. Watch progress syncs back to the server.
+Browse your Jellyfin library, cast to a device, and start playback from SubMiner. Watch progress goes back to the Jellyfin server.
 
 <!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/jellyfin-poster.jpg?v=${v}`)">
   <source :src="withBase(`/assets/demos/jellyfin.webm?v=${v}`)" type="video/webm" />

docs-site/development.md

@@ -1,12 +1,12 @@
 # Building and testing
 
-Build, run, and test SubMiner from source. Architecture and workflow rules live in the repo's internal docs, starting at [`docs/README.md`](https://github.com/ksyasuda/SubMiner/blob/main/docs/README.md). Module boundaries and layering rules are in [`docs/architecture/README.md`](https://github.com/ksyasuda/SubMiner/blob/main/docs/architecture/README.md). The lane-by-lane test guide is [`docs/workflow/verification.md`](https://github.com/ksyasuda/SubMiner/blob/main/docs/workflow/verification.md).
+Architecture and workflow guidance lives in `docs/README.md` at the repo root. This page covers build and test commands only.
 
 ## Prerequisites
 
-- [Bun](https://bun.sh), at the version pinned in `package.json`
-- A system `lua` interpreter for the mpv plugin tests (`bun run test:launcher`, `bun run test:env`)
-- macOS only: `bun run build` compiles a Swift window helper. Set `SUBMINER_SKIP_MACOS_HELPER_BUILD=1` to skip it.
+- [Bun](https://bun.sh)
+- A system `lua` interpreter for `bun run test:launcher` / `bun run test:plugin:src`
+- macOS builds compile a Swift helper via `scripts/prepare-build-assets.mjs` (skip with `SUBMINER_SKIP_MACOS_HELPER_BUILD=1`)
 
 ## Setup
 
@@ -16,20 +16,36 @@ cd SubMiner
 make deps
 ```
 
-`make deps` initializes submodules and installs dependencies for the root, `stats/`, and `vendor/texthooker-ui`. The Yomitan submodule installs its own dependencies during `bun run build`.
+`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`.
 
-## Build
+## Building
 
 ```bash
-bun run build               # app build, including bundled Yomitan from vendor/subminer-yomitan
+# Main app build
+bun run build
+
+# Platform packages
 bun run build:appimage      # Linux AppImage
 bun run build:mac           # macOS DMG + ZIP (signed)
 bun run build:mac:unsigned  # macOS DMG + ZIP (unsigned)
 bun run build:win           # Windows NSIS installer + ZIP
-make build-launcher         # launcher only, output: dist/launcher/subminer
+
+# Optional launcher artifact only
+make build-launcher
+# output: dist/launcher/subminer
 ```
 
-The launcher source is `launcher/*.ts`. `dist/launcher/subminer` is generated, so never edit it by hand. The repo-root `./subminer` is a stale path and verification rejects it. `make install-linux` and `make install-macos` copy from `dist/launcher/subminer`. To check the launcher build:
+`bun run build` includes the Yomitan build step. It builds the bundled Chrome extension directly from the `vendor/subminer-yomitan` submodule into `build/yomitan` using Bun.
+
+## Launcher artifact workflow
+
+- Source of truth: `launcher/*.ts`
+- Generated output: `dist/launcher/subminer`
+- Do not hand-edit generated launcher output.
+- Repo-root `./subminer` is a stale artifact path and is rejected by verification checks.
+- Install targets (`make install-linux`, `make install-macos`) copy from `dist/launcher/subminer`.
+
+Verify the workflow:
 
 ```bash
 make build-launcher
@@ -37,21 +53,20 @@ dist/launcher/subminer --help >/dev/null
 bash scripts/verify-generated-launcher.sh
 ```
 
-## Run locally
+## Running locally
 
 ```bash
-bun run dev                                  # build, then launch with --start --dev
-make dev-watch                               # watch TS + renderer and relaunch Electron
-make dev-watch-macos                         # same, forcing --backend macos
-electron . --start --dev --log-level debug   # verbose launch of an existing build
-electron . --background                      # tray/background mode
+bun run dev    # builds + launches with --start --dev
+electron . --start --dev --log-level debug   # equivalent Electron launch with verbose logging
+electron . --background                       # tray/background mode, minimal default logging
+make dev-start                                # build + launch via Makefile
+make dev-watch                                # watch TS + renderer and launch Electron (faster edit loop)
+make dev-watch-macos                          # same as dev-watch, forcing --backend macos
 ```
 
-Development and debug launches use a separate `SubMiner-dev` profile so runtime experiments cannot modify the installed app's configuration or Yomitan dictionaries. To intentionally use the production profile for a development launch, set `SUBMINER_USE_PRODUCTION_PROFILE=1`. Use that override only after backing up the profile.
-
-Launch source builds through `bun run dev` or `bun run electron`. SubMiner refuses to load its profile when the running Electron major differs from the version pinned by the repository.
-
-To test through the mpv plugin without exporting `SUBMINER_BINARY_PATH` each time, point `mpv.subminerBinaryPath` in your config at the dev script. The launcher passes it to the plugin at runtime:
+For mpv-plugin-driven testing without exporting `SUBMINER_BINARY_PATH` each run, set a one-time
+dev binary path with `mpv.subminerBinaryPath` in your SubMiner config. The launcher injects it into
+the mpv plugin at runtime:
 
 ```json
 {
@@ -61,9 +76,35 @@ To test through the mpv plugin without exporting `SUBMINER_BINARY_PATH` each tim
 }
 ```
 
-## Test
+## Testing
 
-Run the handoff gate before submitting substantial changes:
+Default lanes:
+
+```bash
+bun run test           # alias for test:fast
+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
+```
+
+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/**`.
+
+Suggested local gate before handoff:
 
 ```bash
 bun run typecheck
@@ -73,108 +114,133 @@ bun run build
 bun run test:smoke:dist
 ```
 
-For smaller changes, start with the cheapest lane that covers what you touched:
-
-| Command                         | Covers                                                                   |
-| ------------------------------- | ------------------------------------------------------------------------ |
-| `bun run test` / `test:fast`    | All `src/**` tests, launcher unit tests, and `scripts/**` tests          |
-| `bun run test:config`           | Config schema, defaults, and `config.example.jsonc` generation           |
-| `bun run test:launcher`         | Launcher tests plus the Lua plugin tests                                 |
-| `bun run test:env`              | Launcher e2e smoke, Lua plugin tests, SQLite immersion tests from source |
-| `bun run test:scripts`          | Build and release scripts under `scripts/**`                             |
-| `bun run test:stats`            | Stats dashboard UI under `stats/src/**`                                  |
-| `bun run test:runtime:compat`   | Compiled-runtime smoke against `dist/` (run `bun run build` first)       |
-| `bun run test:immersion:sqlite` | Compiles, then runs the SQLite-backed immersion tracker tests            |
-| `bun run test:subtitle`         | alass/ffsubsync subtitle sync                                            |
-| `bun run test:docs:kb`          | Internal docs, `AGENTS.md`, and repo skills                              |
-
-Lane membership is defined in `scripts/test-lanes.ts` and discovered by directory, so a new test file joins its lane automatically. Do not hand-list test files in `package.json`. `scripts/run-test-lane.mjs` runs each file in its own `bun test` process, so a hanging test cannot take down the rest of the lane. Pass `--jobs N` to parallelize or `--single-process` to share one process while debugging.
-
-Launcher smoke artifacts go to `.tmp/launcher-smoke`. CI uploads them when the smoke step fails.
-
-## Format
+If you changed docs in `docs-site/`, also run:
 
 ```bash
-make pretty               # format the maintained source and stats files
-bun run format:check:src  # check the same set without writing
+bun run docs:test
+bun run docs:build
 ```
 
-`bun run format` runs Prettier over the whole repo. Use it only when you mean to.
-
-## Config generation
-
-```bash
-bun run electron . --generate-config   # write a default config to ~/.config/SubMiner/config.jsonc (%APPDATA%\SubMiner\config.jsonc on Windows)
-bun run generate:config-example        # regenerate config.example.jsonc from the defaults
-```
-
-`make generate-config` and `make generate-example-config` wrap the same commands.
-
-Config definitions are split by domain under `src/config/definitions/`:
-
-- defaults: `defaults-*.ts`
-- option metadata: `options-*.ts`
-- generated template sections and comments: `template-sections.ts`
-
-`src/config/definitions.ts` composes them into the public API (`DEFAULT_CONFIG`, registries, template export). A new key also needs a resolver entry under `src/config/resolve/`, or the resolved config keeps the default.
-
-## Documentation site
-
-The user docs live in `docs-site/` (VitePress).
-
-```bash
-bun --cwd docs-site install
-bun run docs:dev      # dev server at http://localhost:5173
-bun run docs:test     # docs regression tests (links, pinned strings)
-bun run docs:build    # production build into docs-site/.vitepress/dist
-bun run docs:preview  # preview the build at http://localhost:4173
-```
-
-Run `bun run docs:test` and `bun run docs:build` whenever you change `docs-site/`.
-
-Production uses the versioned build:
+For production docs routing, run the versioned build:
 
 ```bash
 bun run docs:build:versioned
 ```
 
-It writes `.tmp/docs-versioned-site`: the latest stable docs at `/` with a generated `/versions` page, and development docs at `/main/`. Prerelease tags are skipped. Stable archives under `/v/<version>/` are built once and stored in R2. Without R2 credentials the build skips archive sync, so a local run only produces `/` and `/main/`.
+The versioned build writes `.tmp/docs-versioned-site` with latest stable docs at `/`, development docs at `/main/`, and stable archives under `/v/<version>/`. Prerelease tags are skipped. Public assets from `docs-site/public/assets` are shared from root `/assets/` so large demo media is not duplicated into every version archive; generated VitePress CSS and JS assets stay under each version route. Stale `.tmp/docs-versioned-archive-cache` generations are pruned after a successful build, and intermediate `.tmp/docs-versioned-build` workspaces are removed.
 
-The `docs-pages` GitHub Actions workflow uploads that output to Cloudflare Pages with Wrangler. Cloudflare's Git-integration builds are disabled on purpose, so do not re-enable them in the dashboard. `docs-site/README.md` has the full deployment setup.
+Focused commands:
 
-## Makefile targets
+```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:launcher:smoke:src # Launcher e2e smoke: launcher -> mpv IPC -> overlay start/stop wiring
+bun run test:env                # 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
+```
 
-Run `make help` for the full list.
+Dist-level tests are now an explicit smoke lane used to validate compiled/runtime assumptions.
 
-| Target                      | Description                                                  |
-| --------------------------- | ------------------------------------------------------------ |
-| `make deps`                 | Init submodules and install root, stats, and texthooker deps |
-| `make build`                | Build the platform package for the current OS                |
-| `make build-linux`          | Build the Linux package                                      |
-| `make build-macos`          | Build the signed macOS package                               |
-| `make build-macos-unsigned` | Build the unsigned macOS package                             |
-| `make build-launcher`       | Generate the launcher in `dist/launcher/`                    |
-| `make install`              | Install platform artifacts (wrapper, theme, AppImage or app) |
-| `make pretty`               | Run scoped Prettier formatting                               |
-| `make generate-config`      | Generate a default config                                    |
+Launcher smoke artifacts are written to `.tmp/launcher-smoke` locally and uploaded by CI/release workflows when the smoke step fails.
+
+Smoke and optional deep dist commands:
+
+```bash
+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
+```
+
+Use `bun run test:immersion:sqlite` when you need real DB-backed coverage for the immersion tracker.
+
+## Formatting
+
+Use the scoped formatter for normal app-repo work:
+
+```bash
+make pretty
+bun run format:check:src
+```
+
+- `make pretty` runs the maintained Prettier allowlists (`format:src` and `format:stats`).
+- `bun run format:check:src` checks the same scoped set without writing changes.
+- `bun run format` remains the broad repo-wide Prettier command; use it intentionally.
+
+## Config generation
+
+```bash
+# Generate default config to ~/.config/SubMiner/config.jsonc (or %APPDATA%\SubMiner\config.jsonc on Windows)
+bun run electron . --generate-config
+
+# Regenerate the repo's config.example.jsonc from centralized defaults
+bun run generate:config-example
+```
+
+Convenience wrappers still exist:
+
+- `make generate-config`
+- `make generate-example-config`
+
+## Documentation site
+
+The docs site now lives in `docs-site/` inside the main repo.
+
+From the SubMiner app repo:
+
+```bash
+bun --cwd docs-site install
+bun run docs:dev     # Dev server at http://localhost:5173
+bun run docs:build   # Production build into docs-site/.vitepress/dist
+bun run docs:preview # Preview built site at http://localhost:4173
+bun run docs:test    # Docs regression tests
+```
+
+Deployment: production docs are built with `bun run docs:build:versioned` and uploaded directly to Cloudflare Pages by the `docs-pages` GitHub Actions workflow using Wrangler (from `.tmp/docs-versioned-site`). Cloudflare's automatic Git-integration deployments are intentionally disabled - see `docs-site/README.md` for the deployment contract. Do not re-enable Pages build settings in the Cloudflare dashboard.
+
+## Makefile reference
+
+Run `make help` for a full list of targets. Key ones:
+
+| Target                      | Description                                                       |
+| --------------------------- | ----------------------------------------------------------------- |
+| `make build`                | Build platform package for detected OS                            |
+| `make build-launcher`       | Generate launcher wrappers and CLI payload in `dist/launcher/`    |
+| `make install`              | Install platform artifacts (wrapper, theme, AppImage/app bundle)  |
+| `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                           |
+| `make build-macos`          | Convenience wrapper for signed macOS packaging                    |
+| `make build-macos-unsigned` | Convenience wrapper for unsigned macOS packaging                  |
 
 ## Contributor notes
 
-- See [Architecture](/architecture) for module boundaries and [IPC + runtime contracts](/ipc-contracts) before adding IPC channels.
-- `src/core/services/overlay-manager.ts` owns overlay window and visibility state.
-- In `src/main/` modules, pass simple dependencies as inline objects. Add a helper or adapter only when it adapts, validates, or gets reused.
-- Packaged Linux desktop launches pass `--background` through `build.linux.executableArgs` in `package.json`.
+- To add/change a config default, edit the matching domain file in `src/config/definitions/defaults-*.ts`.
+- To add/change config option metadata, edit the matching domain file in `src/config/definitions/options-*.ts`.
+- To add/change generated config template blocks/comments, update `src/config/definitions/template-sections.ts`.
+- Keep `src/config/definitions.ts` as the composed public API (`DEFAULT_CONFIG`, registries, template export) that wires domain modules together.
+- Overlay window/visibility state is owned by `src/core/services/overlay-manager.ts`.
+- Runtime architecture/module-boundary conventions are summarized in [Architecture](/architecture), with canonical internal guidance in `docs/architecture/README.md` at the repo root.
+- Linux packaged desktop launches pass `--background` using electron-builder `build.linux.executableArgs` in `package.json`.
+- Prefer direct inline deps objects in `src/main/` modules for simple pass-through wiring.
+- Add a helper/adapter service only when it performs meaningful adaptation, validation, or reuse (not identity mapping).
 
 ## Environment variables
 
-| Variable                           | Description                                                      |
-| ---------------------------------- | ---------------------------------------------------------------- |
-| `SUBMINER_APPIMAGE_PATH`           | SubMiner app binary the launcher uses for playback               |
-| `SUBMINER_BINARY_PATH`             | Alias for `SUBMINER_APPIMAGE_PATH`                               |
-| `SUBMINER_ROFI_THEME`              | rofi theme for the launcher picker                               |
-| `SUBMINER_MPV_PLUGIN_PATH`         | mpv plugin directory the launcher injects                        |
-| `SUBMINER_LOG_LEVEL`               | App log level (`debug`, `info`, `warn`, `error`)                 |
-| `SUBMINER_MPV_LOG`                 | Shared mpv/app log file path                                     |
-| `SUBMINER_JELLYFIN_ACCESS_TOKEN`   | Jellyfin access token, used before the stored encrypted session  |
-| `SUBMINER_JELLYFIN_USER_ID`        | Jellyfin user ID                                                 |
-| `SUBMINER_SKIP_MACOS_HELPER_BUILD` | Set to `1` to skip the macOS helper build during `bun run build` |
+| Variable                           | Description                                                                    |
+| ---------------------------------- | ------------------------------------------------------------------------------ |
+| `SUBMINER_APPIMAGE_PATH`           | Override SubMiner app binary path for launcher playback commands               |
+| `SUBMINER_BINARY_PATH`             | Alias for `SUBMINER_APPIMAGE_PATH`                                             |
+| `SUBMINER_ROFI_THEME`              | Override rofi theme path for launcher picker                                   |
+| `SUBMINER_MPV_PLUGIN_PATH`         | Override the mpv plugin directory injected by the launcher                     |
+| `SUBMINER_LOG_LEVEL`               | Override app logger level (`debug`, `info`, `warn`, `error`)                   |
+| `SUBMINER_MPV_LOG`                 | Override mpv/app shared log file path                                          |
+| `SUBMINER_JIMAKU_API_KEY`          | Override Jimaku API key for launcher subtitle downloads                        |
+| `SUBMINER_JIMAKU_API_KEY_COMMAND`  | Command used to resolve Jimaku API key at runtime                              |
+| `SUBMINER_JIMAKU_API_BASE_URL`     | Override Jimaku API base URL                                                   |
+| `SUBMINER_JELLYFIN_ACCESS_TOKEN`   | Override Jellyfin access token (used before stored encrypted session fallback) |
+| `SUBMINER_JELLYFIN_USER_ID`        | Optional Jellyfin user ID override                                             |
+| `SUBMINER_SKIP_MACOS_HELPER_BUILD` | Set to `1` to skip building the macOS helper binary during `bun run build`     |

docs-site/docs-sync.test.ts

@@ -8,6 +8,7 @@ const installationContents = readFileSync(new URL('./installation.md', import.me
 const mpvPluginContents = readFileSync(new URL('./mpv-plugin.md', import.meta.url), 'utf8');
 const developmentContents = readFileSync(new URL('./development.md', import.meta.url), 'utf8');
 const changelogContents = readFileSync(new URL('./changelog.md', import.meta.url), 'utf8');
+const docsPackageContents = readFileSync(new URL('./package.json', import.meta.url), 'utf8');
 const ankiIntegrationContents = readFileSync(
   new URL('./anki-integration.md', import.meta.url),
   'utf8',
@@ -100,6 +101,15 @@ test('docs state the real secondary-subtitle and Anki field-matching behavior',
   expect(ankiIntegrationContents).toContain('case-insensitively');
 });
 
+test('docs dev server links version navigation to local dev routes', () => {
+  expect(docsPackageContents).toContain('scripts/build-versioned-docs.ts');
+  expect(docsPackageContents).toContain(
+    'SUBMINER_DOCS_VERSION_LINK_ORIGIN=local bun run ../scripts/build-versioned-docs.ts',
+  );
+  expect(docsPackageContents).toContain('SUBMINER_DOCS_VERSION_LINK_ORIGIN=local');
+  expect(docsPackageContents).toContain('SUBMINER_DOCS_VERSION_MANIFEST');
+});
+
 test('docs changelog keeps the current minor release headings aligned with the root changelog', () => {
   const docsHeadings = extractCurrentMinorHeadings(changelogContents);
   expect(docsHeadings.length).toBeGreaterThan(0);