chore(release): prepare v0.20.1

- Rewrite polish prompt to default to inline items, nesting only for several distinct changes
- Add length/density example and drop internal details from release bodies
- Tell prerelease mode to shorten long baseline bullets
- Update changes/README.md and prompt assertions in tests

.agents/plugins/marketplace.json

@@ -1,20 +0,0 @@
-{
-  "name": "subminer-local",
-  "interface": {
-    "displayName": "SubMiner Local"
-  },
-  "plugins": [
-    {
-      "name": "subminer-workflow",
-      "source": {
-        "source": "local",
-        "path": "./plugins/subminer-workflow"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Productivity"
-    }
-  ]
-}

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

@@ -1,22 +1,45 @@
 ---
-name: 'subminer-change-verification'
-description: 'Compatibility shim. Canonical SubMiner change verification workflow now lives in the repo-local subminer-workflow plugin.'
+name: subminer-change-verification
+description: Verify SubMiner changes with repo-native cheap-first test lanes. Use after code, config, launcher, plugin, runtime, stats, documentation, or workflow changes; do not use for read-only questions.
 ---
 
-# Compatibility Shim
+# SubMiner Change Verification
 
-Canonical source:
+Verify the behavior claimed by a change without running unrelated expensive checks by default.
 
-- `plugins/subminer-workflow/skills/subminer-change-verification/SKILL.md`
+## Workflow
 
-Canonical helper scripts:
+1. Inspect the requested scope and changed paths with `git status --short` and `git diff`.
+2. Read `docs/workflow/verification.md` as the source of truth for maintained lanes.
+3. Run the cheapest lane or lanes that cover the changed behavior.
+4. Escalate to the full handoff gate only for substantial or cross-boundary changes.
+5. Report exact commands, results, skipped checks, blockers, and remaining risk.
 
-- `plugins/subminer-workflow/skills/subminer-change-verification/scripts/classify_subminer_diff.sh`
-- `plugins/subminer-workflow/skills/subminer-change-verification/scripts/verify_subminer_change.sh`
+Do not use hidden wrapper commands. Verification commands are owned by `package.json` and the workflow documentation.
 
-When this shim is invoked:
+## Lane Selection
 
-1. Read the canonical plugin-owned skill.
-2. Follow the plugin-owned skill as the source of truth.
-3. Use the wrapper scripts in this shim directory only for compatibility with existing commands and docs.
-4. Do not duplicate workflow changes here; update the plugin-owned skill and scripts instead.
+- Internal docs, `AGENTS.md`, or `.agents/skills/**`: `bun run test:docs:kb`
+- User-facing `docs-site/**`: `bun run docs:test`, then `bun run docs:build`
+- Config/schema/defaults: `bun run test:config`
+  - If defaults or templates changed, also run `bun run generate:config-example` and `bun run verify:config-example`.
+- General TypeScript source: `bun run typecheck`, then `bun run test:fast`
+- 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`
+- Build/release scripts: `bun run test:scripts`
+
+For substantial changes, use the full gate documented in `AGENTS.md` and `docs/workflow/verification.md`.
+
+## Runtime Escalation
+
+Real runtime checks are required when the claim depends on actual Electron, mpv, overlay, focus, window tracking, launch, or socket behavior. Run the relevant application flow when the environment supports it. Otherwise, report the missing runtime dependency and do not present cheaper checks as authoritative runtime validation.
+
+## Pre-Handoff Checks
+
+Before handoff, reconcile both questions:
+
+1. Do behavior, defaults, flags, shortcuts, ports, APIs, architecture, or workflow changes require documentation updates?
+2. Does the change require a current-outcome fragment under `changes/` according to `changes/README.md`?
+
+Complete required updates before handoff or report the blocker.

.agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh

@@ -1,13 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
-REPO_ROOT=$(cd "$SCRIPT_DIR/../../../.." && pwd)
-TARGET="$REPO_ROOT/plugins/subminer-workflow/skills/subminer-change-verification/scripts/classify_subminer_diff.sh"
-
-if [[ ! -x "$TARGET" ]]; then
-  echo "Missing canonical script: $TARGET" >&2
-  exit 1
-fi
-
-exec "$TARGET" "$@"

.agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh

@@ -1,13 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
-REPO_ROOT=$(cd "$SCRIPT_DIR/../../../.." && pwd)
-TARGET="$REPO_ROOT/plugins/subminer-workflow/skills/subminer-change-verification/scripts/verify_subminer_change.sh"
-
-if [[ ! -x "$TARGET" ]]; then
-  echo "Missing canonical script: $TARGET" >&2
-  exit 1
-fi
-
-exec "$TARGET" "$@"

.agents/skills/subminer-release/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: subminer-release
+description: Prepare, cut, publish, or repair SubMiner stable and prerelease releases. Use for hands-on release work; do not use for general release questions.
+---
+
+# SubMiner release
+
+Carry out the requested release phase using the repository's current release process.
+
+## Source of truth
+
+Read `docs/RELEASING.md` completely before changing files or release state. Treat it as canonical. Read `changes/README.md` when the work touches change fragments or generated release notes.
+
+Do not copy release commands or policy into this skill. If this skill disagrees with the release guide, follow the guide and reconcile the skill before handoff.
+
+## Workflow
+
+1. Identify whether the request is for a stable release, prerelease, release preparation, publication, or repair.
+2. Inspect the current branch, worktree status, package version, pending change fragments, relevant tags, and latest CI state before making changes.
+3. Follow the matching procedure in `docs/RELEASING.md` in order. Review generated changelog and release-note Markdown before it can be committed or published.
+4. Run every required gate for the requested release phase. Do not treat a cheaper test lane as a substitute for the documented release gate.
+5. Before a stable tag, confirm the package and tag versions match and no pending `changes/*.md` fragments remain. Preserve fragments for prereleases as documented.
+6. Report the resulting version, completed checks, local commit and tag state, remote publication state, skipped platform checks, and any remaining manual work.
+
+## Authorization boundaries
+
+- A request to prepare a release stops before commit, tag, push, or remote publication unless the user also authorizes those actions.
+- A clear request to cut or publish a release includes the documented commit, tag, and push steps. Ask before the first remote mutation when the wording is ambiguous.
+- Do not edit an existing GitHub release, publish to the AUR, change secrets, or alter signing configuration unless the user explicitly requests that operation.
+- Do not switch branches without consent.
+
+## Stop conditions
+
+Stop and report the blocker when required CI or a release gate fails, authentication is missing, versions disagree, required artifacts are absent, or the worktree contains unexpected changes that overlap the release. Do not tag or publish a partially verified release.

.agents/skills/subminer-scrum-master/SKILL.md

@@ -1,18 +0,0 @@
----
-name: 'subminer-scrum-master'
-description: 'Compatibility shim. Canonical SubMiner scrum-master workflow now lives in the repo-local subminer-workflow plugin.'
----
-
-# Compatibility Shim
-
-Canonical source:
-
-- `plugins/subminer-workflow/skills/subminer-scrum-master/SKILL.md`
-
-When this shim is invoked:
-
-1. Read the canonical plugin-owned skill.
-2. Follow the plugin-owned skill as the source of truth.
-3. Do not duplicate workflow changes here; update the plugin-owned skill instead.
-
-This shim exists so existing repo references and prompts keep resolving during the migration to the repo-local plugin workflow.

.github/workflows/ci.yml

@@ -8,98 +8,4 @@ on:
 
 jobs:
   build-test-audit:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          submodules: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Lint changelog fragments
-        run: bun run changelog:lint
-
-      - name: Lint stats (formatting)
-        run: bun run lint:stats
-
-      - name: Enforce pull request changelog fragments (`skip-changelog` label bypass)
-        if: github.event_name == 'pull_request'
-        run: bun run changelog:pr-check --base-ref "origin/${{ github.base_ref }}" --head-ref "HEAD" --labels "${{ join(github.event.pull_request.labels.*.name, ',') }}"
-
-      - name: Build (TypeScript check)
-        # Keep explicit typecheck for fast fail before full build/bundle.
-        run: bun run typecheck
-
-      - name: Verify generated config examples
-        run: bun run verify:config-example
-
-      - name: Internal docs knowledge-base checks
-        run: bun run test:docs:kb
-
-      - name: Test suite (source)
-        run: bun run test:fast
-
-      - name: Coverage suite (maintained source lane)
-        run: bun run test:coverage:src
-
-      - name: Upload coverage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-test-src
-          path: coverage/test-src/lcov.info
-          if-no-files-found: error
-
-      - name: Launcher smoke suite (source)
-        run: bun run test:launcher:smoke:src
-
-      - name: Upload launcher smoke artifacts (on failure)
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: launcher-smoke
-          path: .tmp/launcher-smoke/**
-          if-no-files-found: ignore
-
-      - name: Build (bundle)
-        run: bun run build
-
-      - name: Immersion SQLite verification
-        run: bun run test:immersion:sqlite:dist
-
-      - name: Dist smoke suite
-        run: bun run test:smoke:dist
-
-      - name: Security audit
-        run: bun audit --audit-level high
-        continue-on-error: true
-
-      - name: Build Bun subminer wrapper
-        run: make build-launcher
-
-      - name: Verify Bun subminer wrapper
-        run: dist/launcher/subminer --help >/dev/null
-
-      - name: Enforce generated launcher workflow
-        run: bash scripts/verify-generated-launcher.sh
+    uses: ./.github/workflows/quality-gate.yml

.github/workflows/docs-pages.yml

@@ -2,6 +2,11 @@ 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
@@ -10,6 +15,8 @@ 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'
@@ -32,9 +39,11 @@ jobs:
       - name: Guard stable docs tag shape
         id: tag_guard
         if: github.ref_type == 'tag'
+        env:
+          TAG_NAME: ${{ github.ref_name }}
         run: |
-          if [[ ! "${{ github.ref_name }}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            echo "::notice::Skipping non-stable docs tag ${{ github.ref_name }}"
+          if [[ ! "$TAG_NAME" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::notice::Skipping non-stable docs tag $TAG_NAME"
             echo "stable_tag=false" >> "$GITHUB_OUTPUT"
             exit 0
           fi
@@ -52,20 +61,21 @@ 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'
-        run: bun run docs:build:versioned
+        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}"
 
       - name: Deploy docs to Cloudflare Pages
         if: steps.tag_guard.outputs.stable_tag != 'false'
@@ -73,4 +83,6 @@ jobs:
         with:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          command: pages deploy .tmp/docs-versioned-site --project-name "${{ vars.CLOUDFLARE_PAGES_PROJECT_NAME }}" --branch main
+          # 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

.github/workflows/package-release.yml

@@ -0,0 +1,238 @@
+name: Package release
+
+on:
+  workflow_call:
+    secrets:
+      CSC_LINK:
+        required: true
+      CSC_KEY_PASSWORD:
+        required: true
+      APPLE_ID:
+        required: true
+      APPLE_APP_SPECIFIC_PASSWORD:
+        required: true
+      APPLE_TEAM_ID:
+        required: true
+      # Project TMDB key baked into release artifacts; builds stay valid without it.
+      SUBMINER_TMDB_API_KEY:
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  build-linux:
+    runs-on: ubuntu-latest
+    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: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Build texthooker-ui
+        run: |
+          cd vendor/texthooker-ui
+          bun install --frozen-lockfile
+          bun run build
+
+      - name: Build AppImage
+        run: bun run build:appimage
+        env:
+          SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
+
+      - name: Build unversioned AppImage
+        run: |
+          shopt -s nullglob
+          appimages=(release/SubMiner-*.AppImage)
+          if [ "${#appimages[@]}" -eq 0 ]; then
+            echo "No versioned AppImage found to create unversioned artifact."
+            ls -la release
+            exit 1
+          fi
+          cp "${appimages[0]}" release/SubMiner.AppImage
+
+      - name: Smoke packaged runtime assets
+        shell: bash
+        run: xvfb-run -a bun run test:package "release/linux-unpacked/resources"
+
+      - name: Upload AppImage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: appimage
+          path: |
+            release/*.AppImage
+            release/latest*.yml
+            release/*.blockmap
+          if-no-files-found: error
+
+  build-macos:
+    runs-on: macos-latest
+    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: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Validate macOS signing/notarization secrets
+        run: |
+          missing=0
+          for name in CSC_LINK CSC_KEY_PASSWORD APPLE_ID APPLE_APP_SPECIFIC_PASSWORD APPLE_TEAM_ID; do
+            if [ -z "${!name}" ]; then
+              echo "Missing required secret: $name"
+              missing=1
+            fi
+          done
+          if [ "$missing" -ne 0 ]; then
+            echo "Set all required macOS signing/notarization secrets and rerun."
+            exit 1
+          fi
+        env:
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Build texthooker-ui
+        run: |
+          cd vendor/texthooker-ui
+          bun install --frozen-lockfile
+          bun run build
+
+      - name: Build signed + notarized macOS artifacts
+        run: bun run build:mac
+        env:
+          SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Smoke packaged runtime assets
+        shell: bash
+        run: bun run test:package "release/mac-arm64/SubMiner.app/Contents/Resources"
+
+      - name: Upload macOS artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos
+          path: |
+            release/*.dmg
+            release/*.zip
+            release/latest*.yml
+            release/*.blockmap
+          if-no-files-found: error
+
+  build-windows:
+    runs-on: windows-latest
+    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: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Build texthooker-ui
+        shell: powershell
+        run: |
+          Set-Location vendor/texthooker-ui
+          bun install --frozen-lockfile
+          bun run build
+
+      - name: Verify managed Windows launcher
+        run: bun test src/main/runtime/managed-launcher.test.ts
+
+      - name: Verify Windows launcher bootstrap
+        run: bun test src/main/runtime/windows-launcher-bootstrap.test.ts
+
+      - name: Build unsigned Windows artifacts
+        run: bun run build:win:unsigned
+        env:
+          SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
+
+      - name: Smoke packaged runtime assets
+        shell: bash
+        run: bun run test:package "release/win-unpacked/resources"
+
+      - name: Upload Windows artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows
+          path: |
+            release/*.exe
+            release/*.zip
+            release/latest*.yml
+            release/*.blockmap
+          if-no-files-found: error

.github/workflows/prerelease.yml

@@ -12,279 +12,25 @@ concurrency:
 
 jobs:
   quality-gate:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
+    permissions:
+      contents: read
+    uses: ./.github/workflows/quality-gate.yml
 
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-${{ runner.arch }}-bun-
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Lint stats (formatting)
-        run: bun run lint:stats
-
-      - name: Build (TypeScript check)
-        run: bun run typecheck
-
-      - name: Install Lua
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y lua5.4
-          sudo ln -sf /usr/bin/lua5.4 /usr/local/bin/lua
-          lua -v
-
-      - name: Test suite (source)
-        run: bun run test:fast
-
-      - name: Environment suite
-        run: bun run test:env
-
-      - name: Coverage suite (maintained source lane)
-        run: bun run test:coverage:src
-
-      - name: Upload coverage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-test-src
-          path: coverage/test-src/lcov.info
-          if-no-files-found: error
-
-      - name: Launcher smoke suite (source)
-        run: bun run test:launcher:smoke:src
-
-      - name: Upload launcher smoke artifacts (on failure)
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: launcher-smoke
-          path: .tmp/launcher-smoke/**
-          if-no-files-found: ignore
-
-      - name: Build (bundle)
-        run: bun run build
-
-      - name: Immersion SQLite verification
-        run: bun run test:immersion:sqlite:dist
-
-      - name: Dist smoke suite
-        run: bun run test:smoke:dist
-
-  build-linux:
+  package:
     needs: [quality-gate]
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/texthooker-ui/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-${{ runner.arch }}-bun-
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Build texthooker-ui
-        run: |
-          cd vendor/texthooker-ui
-          bun install
-          bun run build
-
-      - name: Build AppImage
-        run: bun run build:appimage
-
-      - name: Build unversioned AppImage
-        run: |
-          shopt -s nullglob
-          appimages=(release/SubMiner-*.AppImage)
-          if [ "${#appimages[@]}" -eq 0 ]; then
-            echo "No versioned AppImage found to create unversioned artifact."
-            ls -la release
-            exit 1
-          fi
-          cp "${appimages[0]}" release/SubMiner.AppImage
-
-      - name: Upload AppImage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: appimage
-          path: |
-            release/*.AppImage
-            release/latest*.yml
-            release/*.blockmap
-          if-no-files-found: error
-
-  build-macos:
-    needs: [quality-gate]
-    runs-on: macos-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/texthooker-ui/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-${{ runner.arch }}-bun-
-
-      - name: Validate macOS signing/notarization secrets
-        run: |
-          missing=0
-          for name in CSC_LINK CSC_KEY_PASSWORD APPLE_ID APPLE_APP_SPECIFIC_PASSWORD APPLE_TEAM_ID; do
-            if [ -z "${!name}" ]; then
-              echo "Missing required secret: $name"
-              missing=1
-            fi
-          done
-          if [ "$missing" -ne 0 ]; then
-            echo "Set all required macOS signing/notarization secrets and rerun."
-            exit 1
-          fi
-        env:
+    permissions:
+      contents: read
+    uses: ./.github/workflows/package-release.yml
+    secrets:
       CSC_LINK: ${{ secrets.CSC_LINK }}
       CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
       APPLE_ID: ${{ secrets.APPLE_ID }}
       APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
       APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Build texthooker-ui
-        run: |
-          cd vendor/texthooker-ui
-          bun install
-          bun run build
-
-      - name: Build signed + notarized macOS artifacts
-        run: bun run build:mac
-        env:
-          CSC_LINK: ${{ secrets.CSC_LINK }}
-          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
-          APPLE_ID: ${{ secrets.APPLE_ID }}
-          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
-          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-
-      - name: Upload macOS artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: macos
-          path: |
-            release/*.dmg
-            release/*.zip
-            release/latest*.yml
-            release/*.blockmap
-          if-no-files-found: error
-
-  build-windows:
-    needs: [quality-gate]
-    runs-on: windows-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/texthooker-ui/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-${{ runner.arch }}-bun-
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Build texthooker-ui
-        shell: powershell
-        run: |
-          Set-Location vendor/texthooker-ui
-          bun install
-          bun run build
-
-      - name: Build unsigned Windows artifacts
-        run: bun run build:win:unsigned
-
-      - name: Upload Windows artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: windows
-          path: |
-            release/*.exe
-            release/*.zip
-            release/latest*.yml
-            release/*.blockmap
-          if-no-files-found: error
+      SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
 
   release:
-    needs: [build-linux, build-macos, build-windows]
+    needs: [package]
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -330,11 +76,11 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
-      - name: Build Bun subminer wrapper
+      - name: Build launcher runtime artifacts
         run: make build-launcher
 
-      - name: Verify Bun subminer wrapper
-        run: dist/launcher/subminer --help >/dev/null
+      - name: Smoke launcher bundle
+        run: bun dist/launcher/subminer.js --help >/dev/null
 
       - name: Enforce generated launcher workflow
         run: bash scripts/verify-generated-launcher.sh
@@ -348,12 +94,17 @@ jobs:
             config.example.jsonc \
             plugin/subminer \
             plugin/subminer.conf \
-            assets/themes/subminer.rasi
+            assets/themes/subminer.rasi \
+            assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer \
+            resources/bun/licenses
+
+      - name: Package Bun corresponding source
+        run: bun scripts/package-bun-source.mjs
 
       - name: Generate checksums
         run: |
           shopt -s nullglob
-          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz release/latest*.yml release/*.blockmap dist/launcher/subminer)
+          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz release/latest*.yml release/*.blockmap dist/launcher/subminer dist/launcher/subminer.cmd)
           if [ "${#files[@]}" -eq 0 ]; then
             echo "No release artifacts found for checksum generation."
             exit 1
@@ -370,15 +121,22 @@ jobs:
         run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
 
       - name: Verify committed prerelease notes
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
           if [ ! -s release/prerelease-notes.md ]; then
             echo "::error::release/prerelease-notes.md is missing or empty. Run 'bun run changelog:prerelease-notes --version <version>' locally and commit the file before tagging."
             exit 1
           fi
+          if ! bun run changelog:check-prerelease-notes --version "$RELEASE_VERSION"; then
+            echo "::error::release/prerelease-notes.md was not generated for $RELEASE_VERSION. Rerun 'bun run changelog:prerelease-notes --version $RELEASE_VERSION' locally, commit, and retag."
+            exit 1
+          fi
 
       - name: Publish Prerelease
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
           set -euo pipefail
 
@@ -389,10 +147,12 @@ jobs:
             release/*.exe
             release/*.zip
             release/*.tar.gz
+            release/*.tar.gz.sha256
             release/latest*.yml
             release/*.blockmap
             release/SHA256SUMS.txt
             dist/launcher/subminer
+            dist/launcher/subminer.cmd
           )
 
           if [ "${#artifacts[@]}" -eq 0 ]; then
@@ -400,27 +160,27 @@ jobs:
             exit 1
           fi
 
-          if gh release view "${{ steps.version.outputs.VERSION }}" >/dev/null 2>&1; then
-            gh release edit "${{ steps.version.outputs.VERSION }}" \
+          if gh release view "$RELEASE_VERSION" >/dev/null 2>&1; then
+            gh release edit "$RELEASE_VERSION" \
               --draft \
               --prerelease \
-              --title "${{ steps.version.outputs.VERSION }}" \
+              --title "$RELEASE_VERSION" \
               --notes-file release/prerelease-notes.md
           else
-            gh release create "${{ steps.version.outputs.VERSION }}" \
+            gh release create "$RELEASE_VERSION" \
               --draft \
               --latest=false \
               --prerelease \
-              --title "${{ steps.version.outputs.VERSION }}" \
+              --title "$RELEASE_VERSION" \
               --notes-file release/prerelease-notes.md
           fi
 
           for asset in "${artifacts[@]}"; do
-            gh release upload "${{ steps.version.outputs.VERSION }}" "$asset" --clobber
+            gh release upload "$RELEASE_VERSION" "$asset" --clobber
           done
 
-          gh release edit "${{ steps.version.outputs.VERSION }}" \
+          gh release edit "$RELEASE_VERSION" \
             --draft=false \
             --prerelease \
-            --title "${{ steps.version.outputs.VERSION }}" \
+            --title "$RELEASE_VERSION" \
             --notes-file release/prerelease-notes.md

.github/workflows/quality-gate.yml

@@ -0,0 +1,145 @@
+name: Quality Gate
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  launcher-runtime:
+    strategy:
+      matrix:
+        os: [windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Verify native runtime staging
+        run: bun test src/main/runtime/managed-launcher.test.ts
+
+      - 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
+
+  quality-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: true
+          persist-credentials: false
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Lint changelog fragments
+        run: bun run changelog:lint
+
+      - name: Lint stats (formatting)
+        run: bun run lint:stats
+
+      - name: Enforce pull request changelog fragments (`skip-changelog` label bypass)
+        if: github.event_name == 'pull_request'
+        env:
+          BASE_REF: ${{ github.base_ref }}
+          PR_LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }}
+        run: bun run changelog:pr-check --base-ref "origin/$BASE_REF" --head-ref "HEAD" --labels "$PR_LABELS"
+
+      - name: Build (TypeScript check)
+        run: bun run typecheck
+
+      - name: Verify generated config examples
+        run: bun run verify:config-example
+
+      - name: Install Lua
+        run: |
+          # Lua needs only Ubuntu sources; unrelated runner repositories can be unavailable.
+          test -f /etc/apt/sources.list.d/ubuntu.sources
+          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 lua5.4
+          sudo ln -sf /usr/bin/lua5.4 /usr/local/bin/lua
+          lua -v
+
+      - name: Launcher unit and script suites
+        run: bun run test:launcher:unit:src && bun run test:scripts
+
+      - name: Environment suite
+        run: bun run test:env
+
+      - name: Upload launcher smoke artifacts (on failure)
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: launcher-smoke
+          path: .tmp/launcher-smoke/**
+          if-no-files-found: ignore
+
+      - name: Coverage suite (maintained source lane)
+        run: bun run test:coverage:src
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-test-src
+          path: coverage/test-src/lcov.info
+          if-no-files-found: error
+
+      - name: Stats UI tests
+        run: bun run test:stats
+
+      - name: Build (bundle)
+        run: bun run build
+
+      - name: Immersion SQLite verification
+        run: bun run test:immersion:sqlite:dist
+
+      - name: Dist smoke suite
+        run: bun run test:smoke:dist
+
+      - name: Security audit
+        run: bun audit --audit-level high
+
+      - name: Build launcher runtime artifacts
+        run: make build-launcher
+
+      - name: Smoke launcher bundle
+        run: bun dist/launcher/subminer.js --help >/dev/null
+
+      - name: Enforce generated launcher workflow
+        run: bash scripts/verify-generated-launcher.sh

.github/workflows/release.yml

@@ -13,267 +13,25 @@ concurrency:
 
 jobs:
   quality-gate:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
+    permissions:
+      contents: read
+    uses: ./.github/workflows/quality-gate.yml
 
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Lint stats (formatting)
-        run: bun run lint:stats
-
-      - name: Build (TypeScript check)
-        run: bun run typecheck
-
-      - name: Test suite (source)
-        run: bun run test:fast
-
-      - name: Coverage suite (maintained source lane)
-        run: bun run test:coverage:src
-
-      - name: Upload coverage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-test-src
-          path: coverage/test-src/lcov.info
-          if-no-files-found: error
-
-      - name: Launcher smoke suite (source)
-        run: bun run test:launcher:smoke:src
-
-      - name: Upload launcher smoke artifacts (on failure)
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: launcher-smoke
-          path: .tmp/launcher-smoke/**
-          if-no-files-found: ignore
-
-      - name: Build (bundle)
-        run: bun run build
-
-      - name: Immersion SQLite verification
-        run: bun run test:immersion:sqlite:dist
-
-      - name: Dist smoke suite
-        run: bun run test:smoke:dist
-
-  build-linux:
+  package:
     needs: [quality-gate]
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/texthooker-ui/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Build texthooker-ui
-        run: |
-          cd vendor/texthooker-ui
-          bun install
-          bun run build
-
-      - name: Build AppImage
-        run: bun run build:appimage
-
-      - name: Build unversioned AppImage
-        run: |
-          shopt -s nullglob
-          appimages=(release/SubMiner-*.AppImage)
-          if [ "${#appimages[@]}" -eq 0 ]; then
-            echo "No versioned AppImage found to create unversioned artifact."
-            ls -la release
-            exit 1
-          fi
-          cp "${appimages[0]}" release/SubMiner.AppImage
-
-      - name: Upload AppImage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: appimage
-          path: |
-            release/*.AppImage
-            release/latest*.yml
-            release/*.blockmap
-
-  build-macos:
-    needs: [quality-gate]
-    runs-on: macos-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/texthooker-ui/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Validate macOS signing/notarization secrets
-        run: |
-          missing=0
-          for name in CSC_LINK CSC_KEY_PASSWORD APPLE_ID APPLE_APP_SPECIFIC_PASSWORD APPLE_TEAM_ID; do
-            if [ -z "${!name}" ]; then
-              echo "Missing required secret: $name"
-              missing=1
-            fi
-          done
-          if [ "$missing" -ne 0 ]; then
-            echo "Set all required macOS signing/notarization secrets and rerun."
-            exit 1
-          fi
-        env:
+    permissions:
+      contents: read
+    uses: ./.github/workflows/package-release.yml
+    secrets:
       CSC_LINK: ${{ secrets.CSC_LINK }}
       CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
       APPLE_ID: ${{ secrets.APPLE_ID }}
       APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
       APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Build texthooker-ui
-        run: |
-          cd vendor/texthooker-ui
-          bun install
-          bun run build
-
-      - name: Build signed + notarized macOS artifacts
-        run: bun run build:mac
-        env:
-          CSC_LINK: ${{ secrets.CSC_LINK }}
-          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
-          APPLE_ID: ${{ secrets.APPLE_ID }}
-          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
-          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-
-      - name: Upload macOS artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: macos
-          path: |
-            release/*.dmg
-            release/*.zip
-            release/latest*.yml
-            release/*.blockmap
-
-  build-windows:
-    needs: [quality-gate]
-    runs-on: windows-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/texthooker-ui/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Build texthooker-ui
-        shell: powershell
-        run: |
-          Set-Location vendor/texthooker-ui
-          bun install
-          bun run build
-
-      - name: Build unsigned Windows artifacts
-        run: bun run build:win:unsigned
-
-      - name: Upload Windows artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: windows
-          path: |
-            release/*.exe
-            release/*.zip
-            release/latest*.yml
-            release/*.blockmap
-          if-no-files-found: error
+      SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
 
   release:
-    needs: [build-linux, build-macos, build-windows]
+    needs: [package]
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -319,11 +77,11 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
-      - name: Build Bun subminer wrapper
+      - name: Build launcher runtime artifacts
         run: make build-launcher
 
-      - name: Verify Bun subminer wrapper
-        run: dist/launcher/subminer --help >/dev/null
+      - name: Smoke launcher bundle
+        run: bun dist/launcher/subminer.js --help >/dev/null
 
       - name: Enforce generated launcher workflow
         run: bash scripts/verify-generated-launcher.sh
@@ -337,12 +95,17 @@ jobs:
             config.example.jsonc \
             plugin/subminer \
             plugin/subminer.conf \
-            assets/themes/subminer.rasi
+            assets/themes/subminer.rasi \
+            assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer \
+            resources/bun/licenses
+
+      - name: Package Bun corresponding source
+        run: bun scripts/package-bun-source.mjs
 
       - name: Generate checksums
         run: |
           shopt -s nullglob
-          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz release/latest*.yml release/*.blockmap dist/launcher/subminer)
+          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz release/latest*.yml release/*.blockmap dist/launcher/subminer dist/launcher/subminer.cmd)
           if [ "${#files[@]}" -eq 0 ]; then
             echo "No release artifacts found for checksum generation."
             exit 1
@@ -359,33 +122,40 @@ jobs:
         run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
 
       - name: Guard against pending changelog fragments
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
           if find changes -maxdepth 1 -name '*.md' -not -name README.md -print -quit | grep -q .; then
-            echo "::error::Pending changelog fragments detected. Run 'bun run changelog:build --version ${{ steps.version.outputs.VERSION }}' locally and commit the polished CHANGELOG.md before tagging. CI no longer auto-builds the changelog because the polish step requires the local 'claude' CLI."
+            echo "::error::Pending changelog fragments detected. Run 'bun run changelog:build --version $RELEASE_VERSION' locally and commit the polished CHANGELOG.md before tagging. CI no longer auto-builds the changelog because the polish step requires the local 'claude' CLI."
             exit 1
           fi
 
       - name: Verify changelog is ready for tagged release
-        run: bun run changelog:check --version "${{ steps.version.outputs.VERSION }}"
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
+        run: bun run changelog:check --version "$RELEASE_VERSION"
 
       - name: Generate release notes from changelog
-        run: bun run changelog:release-notes --version "${{ steps.version.outputs.VERSION }}"
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
+        run: bun run changelog:release-notes --version "$RELEASE_VERSION"
 
       - name: Publish Release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
           set -euo pipefail
 
-          if gh release view "${{ steps.version.outputs.VERSION }}" >/dev/null 2>&1; then
+          if gh release view "$RELEASE_VERSION" >/dev/null 2>&1; then
             # Do not pass the prerelease flag here; gh defaults to a normal release.
-            gh release edit "${{ steps.version.outputs.VERSION }}" \
+            gh release edit "$RELEASE_VERSION" \
               --draft=false \
-              --title "${{ steps.version.outputs.VERSION }}" \
+              --title "$RELEASE_VERSION" \
               --notes-file release/release-notes.md
           else
-            gh release create "${{ steps.version.outputs.VERSION }}" \
-              --title "${{ steps.version.outputs.VERSION }}" \
+            gh release create "$RELEASE_VERSION" \
+              --title "$RELEASE_VERSION" \
               --notes-file release/release-notes.md
           fi
 
@@ -396,10 +166,12 @@ jobs:
             release/*.exe
             release/*.zip
             release/*.tar.gz
+            release/*.tar.gz.sha256
             release/latest*.yml
             release/*.blockmap
             release/SHA256SUMS.txt
             dist/launcher/subminer
+            dist/launcher/subminer.cmd
           )
 
           if [ "${#artifacts[@]}" -eq 0 ]; then
@@ -408,7 +180,7 @@ jobs:
           fi
 
           for asset in "${artifacts[@]}"; do
-            gh release upload "${{ steps.version.outputs.VERSION }}" "$asset" --clobber
+            gh release upload "$RELEASE_VERSION" "$asset" --clobber
           done
 
   aur-publish:
@@ -481,39 +253,52 @@ 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="${{ steps.version.outputs.VERSION }}"
+          version="$RELEASE_VERSION"
           install -dm755 .tmp/aur-release-assets
-          gh release download "$version" \
-            --dir .tmp/aur-release-assets \
-            --pattern "SubMiner-${version#v}.AppImage" \
-            --pattern "subminer" \
-            --pattern "subminer-assets.tar.gz"
+          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"
 
       - name: Update AUR packaging metadata
-        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
+        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'
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
           set -euo pipefail
-          version_no_v="${{ steps.version.outputs.VERSION }}"
+          version_no_v="$RELEASE_VERSION"
           version_no_v="${version_no_v#v}"
           cp packaging/aur/subminer-bin/PKGBUILD aur-subminer-bin/PKGBUILD
           cp packaging/aur/subminer-bin/.SRCINFO aur-subminer-bin/.SRCINFO
           bash scripts/update-aur-package.sh \
             --pkg-dir aur-subminer-bin \
-            --version "${{ steps.version.outputs.VERSION }}" \
+            --version "$RELEASE_VERSION" \
             --appimage ".tmp/aur-release-assets/SubMiner-${version_no_v}.AppImage" \
             --wrapper ".tmp/aur-release-assets/subminer" \
             --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'
+        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'
         working-directory: aur-subminer-bin
         env:
           GIT_SSH_COMMAND: ssh -i ~/.ssh/aur -o IdentitiesOnly=yes
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
           set -euo pipefail
           if git diff --quiet -- PKGBUILD .SRCINFO; then
@@ -523,7 +308,7 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git add PKGBUILD .SRCINFO
-          git commit -m "Update to ${{ steps.version.outputs.VERSION }}"
+          git commit -m "Update to $RELEASE_VERSION"
 
           attempts=3
           for attempt in $(seq 1 "$attempts"); do

.gitignore

@@ -1,5 +1,6 @@
 # Dependencies
 node_modules/
+/package-lock.json
 
 # Superpowers brainstorming
 .superpowers/
@@ -16,6 +17,8 @@ coverage/
 
 # Launcher build artifact (produced by make build-launcher)
 /subminer
+/main-entry.js
+/main-entry.js.map
 
 # Logs
 *.log
@@ -46,6 +49,7 @@ tests/*
 !.agents/skills/
 .agents/skills/*
 !.agents/skills/subminer-change-verification/
+!.agents/skills/subminer-release/
 !.agents/skills/subminer-scrum-master/
 .agents/skills/subminer-change-verification/*
 !.agents/skills/subminer-change-verification/SKILL.md
@@ -53,8 +57,13 @@ tests/*
 .agents/skills/subminer-change-verification/scripts/*
 !.agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh
 !.agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh
+.agents/skills/subminer-release/*
+!.agents/skills/subminer-release/SKILL.md
 .agents/skills/subminer-scrum-master/*
 !.agents/skills/subminer-scrum-master/SKILL.md
 favicon.png
 .claude/*
 !stats/public/favicon.png
+
+# Browser-automation session artifacts (page snapshots, console logs, downloads)
+.playwright-mcp/

.prettierignore

@@ -4,3 +4,4 @@ release
 coverage
 vendor
 *.log
+src/core/services/tokenizer/__fixtures__/golden/*.json

AGENTS.md

@@ -1,4 +1,4 @@
-# AGENTS.MD
+# AGENTS.md
 
 ## Internal Docs
 
@@ -13,7 +13,7 @@ Start here, then leave this file.
 
 `docs-site/` is user-facing. Do not treat it as the canonical internal source of truth.
 
-`CLAUDE.md` is a symlink to this file — there is one project instruction file, not two.
+`CLAUDE.md` is a symlink to this file; there is one project instruction file, not two.
 
 ## Quick Start
 
@@ -25,8 +25,9 @@ Start here, then leave this file.
 
 ## Build / Test
 
-- Runtime/package manager: Bun (`packageManager: bun@1.3.5`)
-- Default handoff gate:
+- Runtime/package manager: Bun; use the version pinned by `package.json`.
+- Follow [`docs/workflow/verification.md`](./docs/workflow/verification.md) and start with the cheapest sufficient lane.
+- Full handoff gate for substantial changes:
   `bun run typecheck`
   `bun run test:fast`
   `bun run test:env`
@@ -42,12 +43,17 @@ Start here, then leave this file.
 - Config/schema/defaults: `bun run test:config`; if template/defaults changed, `bun run generate:config-example`
 - Launcher/plugin: `bun run test:launcher` or `bun run test:env`
 - Runtime-compat / dist-sensitive: `bun run test:runtime:compat`
-- Docs-only: `bun run docs:test`, then `bun run docs:build`
+- Stats dashboard UI (`stats/`): `bun run test:stats`
+- 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: `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
 
 - Docs ship with the change, not after. If a change alters behavior, defaults, flags, shortcuts, ports, or APIs, update the matching docs in the same PR. Touching code without reconciling its docs is an incomplete change.
-- Source of truth for config defaults is the generated `config.example.jsonc`. Never write a default value into prose you didn't read from it — and don't restate the same default across multiple docs; cite/link to one place so there's a single thing to update.
+- Source of truth for config defaults is the generated `config.example.jsonc`. Never write a default value into prose you didn't read from it, and don't restate the same default across multiple docs; cite/link to one place so there's a single thing to update.
 - Trigger map (touch left → update right):
   - `src/config/definitions/**` (schema/defaults/template) → `bun run generate:config-example`, then reconcile `docs-site/configuration.md` + any feature doc that cites that default
   - shortcuts/keybindings (`shortcuts.*`, `keybindings`, `stats.*Key`, `subtitleSidebar.toggleKey`, controller bindings) → `docs-site/shortcuts.md`
@@ -68,16 +74,10 @@ Start here, then leave this file.
 
 ## Release / PR Notes
 
-- User-visible PRs need reconciled current-outcome fragment(s) in `changes/*.md` — format and rules in [`changes/README.md`](./changes/README.md) (`type` + `area` keys required; inspect existing same-PR fragments, then update/remove stale bullets or add only genuinely separate outcomes; apply the `skip-changelog` label to opt out)
+- User-visible PRs need reconciled current-outcome fragment(s) in `changes/*.md`. Format and rules live in [`changes/README.md`](./changes/README.md) (`type` + `area` keys required; inspect existing same-PR fragments, then update/remove stale bullets or add only genuinely separate outcomes; apply the `skip-changelog` label to opt out).
 - User-visible docs changes get a `type: docs` fragment
 - CI enforces `bun run changelog:lint` and `bun run changelog:pr-check`
 - PR review helpers:
-  - `gh pr view --json number,title,url --jq '"PR #\\(.number): \\(.title)\\n\\(.url)"'`
+  - `gh pr view --json number,title --jq '"PR #\\(.number): \\(.title)"'`
   - `gh api repos/:owner/:repo/pulls/<num>/comments --paginate`
-
-## Runtime Notes
-
-- Use Codex background for long jobs; tmux only when persistence/interaction is required
-- CI red: `gh run list/view`, rerun, fix, repeat until green
-- TypeScript: keep files small; follow existing patterns
-- Only Swift is the `scripts/get-mpv-window-macos.swift` helper (macOS mpv window detection); validate via `bun test scripts/get-mpv-window-macos.test.ts`
+- For CI debugging, inspect runs with `gh run list/view`; rerun or fix only within the requested scope.

CHANGELOG.md

@@ -1,5 +1,431 @@
 # 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
+
+- **Card Timing Review**:
+  - Optional pre-generation timing review for word, sentence, and audio cards, with a speech-weighted waveform that flattens background noise so dialogue edges stand out clearly.
+  - The clip end automatically snaps back to where the line's dialogue actually ends once the waveform loads, with drag and keyboard adjustments available.
+  - Audio preview includes a sweeping playhead that plays the clip to its true end, even on high-latency outputs like Bluetooth headphones.
+  - Previous and next subtitle lines can be pulled onto the card with `P`/`N` (or the Prev/Next steppers) and removed with Shift; the sentence preview and waveform markers update automatically.
+  - Cancelling lets you keep a card without media, and the review can be toggled on or off for the session.
+- **Senren Field Grouping**:
+  - Enable `ankiConnect.isSenren` to merge duplicate mined cards using Senren's scene-switching markup, grouping sentence, furigana, audio, picture, and misc-info fields.
+  - Supports the same auto/manual/disabled modes as Kiku, including the manual merge modal; only one of Senren or Kiku can be enabled at a time.
+
+### Changed
+
+- **Remote Stream Mining Performance**: Mining a card from a remote stream (Jellyfin and other HTTP sources) now downloads the clip window once and reuses it for the timing review waveform, audio preview, audio extraction, and screenshot, instead of re-fetching the stream at each step; the temporary file is cleaned up after ten minutes of inactivity or on exit.
+- **TsukiHime Release Filtering**: The TsukiHime modal's Japanese and secondary-language tabs now filter the release list by the subtitle languages each release actually carries, and report when no release has subtitles for the active tab.
+
+### Fixed
+
+- **Subtitle & Mining Accuracy**:
+  - Broadcast-style captions that split one sentence across two on-screen rows (e.g. Crunchyroll Japanese subs) now merge into a single line for the sidebar and mined cards, while separate speakers, sound effects, and labeled turns still stay on their own lines.
+  - Mining from the overlay no longer pulls in a lingering row from the previous caption; the mined sentence and clip timing now match what's actually on screen.
+  - Multi-line copy and mining now select lines backward in timeline order after seeking, instead of in playback encounter order.
+  - Copying a subtitle, mining a sentence, or recording immersion stats no longer includes the separate furigana line that broadcast ASS captions place above a word.
+- **Card Update Notifications**: Dismissed lingering overlay card-update progress when notification settings switch to OSD before an update finishes.
+- **Overlay Stability on Hyprland**: Opening a modal window (timing review, Jimaku, session help, and others) while mpv is fullscreen no longer causes the overlay to flicker while the modal loads; the overlay now stays on screen untouched until the modal is ready.
+- **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.
+
+## v0.19.5 (2026-08-30)
+
+### Fixed
+
+- **Anki Card Update Progress**: The card-update spinner now stays visible until audio and image updates finish, instead of disappearing early.
+- **Anki Word-Card Fields**: Word-card enrichment now writes sentence text and audio to the fields configured in AnkiConnect, while the dedicated sentence-card and audio-card actions keep their existing compatible field names.
+- **Overlapping Subtitles**:
+  - Subtitle lines that start while another line is still on screen now appear alongside it, instead of staying hidden until a track switch or seek.
+  - Subtitles shown at the same time now stack by their authored screen position, with top signs and song lines above bottom dialogue.
+  - Half-size ASS furigana is no longer shown as if it were a dialogue line.
+- **YouTube Auto Captions**:
+  - Auto-generated captions now follow their intended timing and two-row roll-up layout.
+  - Long speech is paged instead of covering the video with a wall of text.
+  - Explicitly timed sound cues like `[音楽]` no longer cover later dialogue.
+
+## 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.
+- **Duplicate Line Cleanup Tool**: The Vocabulary tab's new "Duplicates" button scans a chosen time window (7 days through all time) for old karaoke/typeset duplicate-line bursts, shows what it found, and collapses each run to one line once confirmed; `subminer stats cleanup --duplicate-lines` does the same from the terminal, with `--dry-run` and `--lookback-days <n>` options. Watch time and lines-seen totals are left unchanged.
+
+### Changed
+- **Prerelease Release Notes**: Prerelease notes now open with a "Changes since" section listing only what changed versus the previous beta/RC of the same version, above the cumulative highlights, and CI rejects prerelease tags whose committed notes were generated for a different beta/RC.
+
+### Fixed
+- **Subtitle & Karaoke Duplication**:
+  - Karaoke and animated signs are reconstructed once from their authored text and shown only while actually sung, with original word spacing preserved, instead of flooding the overlay, subtitle sidebar, immersion history, mining, or stats with glyph fragments, per-frame color phases, and repeated animation events.
+  - Decorative layers (highlight sweeps, glow/shadow copies, symbol-font decoration, particle swarms, hidden or zero-scaled text) stay out of published text, while ordinary repeated dialogue, positioned signs, wrapped lyric rows, and multi-row CC-style blocks still display correctly.
+  - Embedded subtitle tracks on network-mounted (SMB/NFS) media are extracted and parsed again instead of falling back to live-text-only, restoring karaoke reconstruction, sidebar cues, and mining for releases that only ship subtitles inside the container.
+  - Secondary subtitles go through the same deduplication pipeline as primary subtitles and no longer clip display after about four lines.
+  - Event-heavy karaoke files that previously stalled subtitle loading for several seconds now parse in well under a second.
+- **Character Dictionary Reliability**:
+  - Generation, merged rebuilds, and imports no longer freeze the app on large dictionaries; snapshot I/O, archive building, and image/name lookup caches moved off the UI's critical path.
+  - Dictionaries are reused instead of regenerated when MeCab finds no name splits.
+  - Cached portraits restore correctly after the portrait index finishes loading post-tokenization.
+  - Desktop progress notifications on Linux AppImage installs update in place instead of flickering, fixing a bug where the AppImage's bundled libraries broke the system notification helper.
+- **Overlay Startup & Modals**:
+  - The macOS window-tracking helper targets macOS 12.0+ instead of requiring the build machine's exact macOS version, fixing crashes on older systems like Ventura that left the overlay stuck on "Overlay loading".
+  - mpv IPC connection attempts time out and retry, showing an actionable error if content still isn't ready after 30 seconds.
+  - Dedicated overlay modals are prewarmed on macOS and Windows so shortcuts open them promptly.
+  - On macOS, reused modals and the stats window open above fullscreen mpv on its current Space instead of jumping to another desktop.
+- **Wayland File Drop**: Fixed native Wayland drag-and-drop from file managers such as Thunar, so subtitle and video files dropped on the visible overlay are resolved and forwarded to mpv.
+- **Windows Mouse Lag**: Fixed system-wide mouse lag on Windows while SubMiner is running, caused by the overlay's global mouse hook for click-through forwarding and by the mpv window tracker blocking the app on repeated PowerShell lookups.
+- **Sentence Mining Audio & Clips**: Sentence-audio generation no longer times out on slow network-mounted media with many subtitle/font streams (bounded FFmpeg probing, two-minute extraction budget, clearer error reporting), and mined audio/animated AVIF clips now capture the subtitle line that was actually mined by snapshotting the clip range at lookup time instead of reading live mpv state later.
+- **Stats Performance & Reliability**: Immersion stats storage now sets its SQLite busy timeout before WAL setup, avoiding transient lock errors under concurrent writes. Deletes in the stats dashboard no longer freeze the UI, run proportional to what's deleted instead of rebuilding full lifetime summaries, retry safely if the delete worker crashes, and no longer rescan the whole library when deleting very common words; a new index also makes large session deletes drop from minutes to milliseconds. Library merges, video moves, and AniList reassignments got the same lifetime-summary fix.
+- **Vocabulary Stats Accuracy**: Vocabulary totals and charts now count all tracked vocabulary instead of only the first page, new-word history uses corrected daily rollups (fixing legacy timestamp and time-zone issues), summary cards refresh automatically after edits to the exclusion list, and rapid exclusion edits no longer race each other.
+- **Rofi MKV Thumbnails**: Fixed missing MKV thumbnails in the Linux rofi picker when system thumbnailer registrations only advertise legacy Matroska MIME aliases.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+- Docs Site Indexing: Excluded the `/main/` and `/v/<version>/` docs trees from search indexing (self-referential canonical, `noindex,follow`, matching `X-Robots-Tag`) so crawlers focus on current docs instead of ~30 archived copies of every page, and restored `<lastmod>` dates in the docs sitemap that were silently dropped by production builds.
+
+</details>
+
+## 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`).
+
+### Changed
+- Subtitle Tokenization Performance: Reworks subtitle dictionary lookups to cut per-line work roughly in half, cache repeated lookups across lines, and stop tokenization from competing with on-screen subtitle prefetching. Also fixes several accuracy issues along the way: dropped readings on trailing kana, character names being skipped after a dictionary sync, annotations not refreshing after mining a card, and halfwidth katakana character names losing their reading or being swallowed by other words.
+
+### Fixed
+- Character Dictionary Large Imports: Large character dictionaries (e.g. One Piece) no longer fail to install from a fixed timeout budget; the import now scales its time budget to dictionary size and reports detailed progress (page/character counts, image download progress, elapsed time) instead of one static message.
+- Stats Delete Responsiveness: Deleting sessions, episodes, or library entries no longer freezes the stats page or an active video player; deletes are now batched into a single transaction.
+- Styled Subtitle Cue Parsing: Heavily typeset subtitles (karaoke, signs) no longer flood the subtitle sidebar with garbage; vector drawing commands are no longer shown as text, and duplicate/animation-burst cues now collapse into one.
+- X11 mpv Renderer: Fixes an mpv crash on the first fullscreen toggle for X11/XWayland users with `gpu-next` shaders (e.g. ArtCNN), which was caused by X11 mode forcing the legacy OpenGL renderer.
+- X11 Overlay Display Scaling: Fixes the overlay appearing oversized and offset from mpv on X11/XWayland under fractional or mixed-monitor display scaling.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+- Subtitle text is now decoded from ASS exactly once at ingest, so the renderer, timing tracker, and tokenizer all share one decoded value instead of each re-deriving it.
+- Added per-stage debug timings (`scanMs`, `mecabMs`, `frequencyMs`, `annotateMs`) to the subtitle tokenization pipeline log.
+
+</details>
+
+## 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.
+
+### Fixed
+- Streaming Subtitle Tokenization: Jellyfin streams now seed subtitle tokenization directly from the downloaded subtitle file instead of relying on an mpv event that could be missed, and prefetching now runs to the end of the file and clears between episodes. The tokenization cache was raised from 256 to 2500 lines, and parsed cues are no longer lost when the active subtitle track briefly can't be resolved (e.g. switching to an embedded track). Together these prevent episodes from falling back to slow, line-by-line tokenization during playback.
+- Overlay: Subtitle lines now appear immediately at their cue time even on a tokenization cache miss, upgrading in place once tokens and annotations are ready, instead of waiting on a line still being processed. A failed tokenization is no longer cached as plain text, so repeated lines get another chance at annotations.
+- Background Logging: Background startup now respects the configured logging level when no explicit log level is passed.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+- Patched three high-severity dependency advisories (`undici`, `brace-expansion`, `fast-uri`).
+
+</details>
+
+## 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.
+
+### Fixed
+- 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.
+
+## 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.
+- Post-Playback Menu: After a watch-history episode ends, the fzf/rofi launcher returns to that series with options to play the previous or next episode, rewatch, pick another episode, or quit. The pre-playback series menu now offers the previous episode too.
+- Delete Library Entries: The stats Library detail view can now delete an entire title in one step (episodes, sessions, subtitle lines, rollups, cover art, and vocabulary counts). Delete progress is now shown app-wide via a progress bar and status toast instead of disappearing when you switch tabs.
+- Cross-Machine Sync: Added SSH-based syncing of stats and watch history between machines, available from the tray ("Sync Stats & History") or `subminer sync`, with saved devices, per-host sync direction, background auto-sync, connection testing, manual snapshots, and support for Windows remotes.
+- TsukiHime Subtitle Downloads: Added subtitle downloads for the current video via TsukiHime, loading Japanese as the primary track and your configured secondary language directly into mpv.
+
+### Changed
+- Clipboard-Video Shortcut: The "append clipboard video to queue" shortcut is now configurable.
+
+### Fixed
+- AniList Season Resolution: Season 2+ files now resolve to the correct AniList entry instead of silently falling back to season 1 (which mismatched character dictionaries and watch progress). Manual overrides now stay scoped per season, fix both the dictionary and progress tracking together, and also correct per-season cover art.
+- Subtitle Annotation Accuracy: Fixed several annotation edge cases, including inconsistent POS exclusions on merged quote-particle tokens, dropped annotations on supplementary-plane kanji, katakana punctuation wrongly treated as noise, and certain kanji vocabulary losing N+1 highlighting eligibility.
+- AnkiConnect Proxy Port Conflict: Video startup no longer crashes when another process already holds the configured AnkiConnect proxy port; a notification now explains how to resolve it.
+- AppImage Quit Crash: Fixed a "Service Crash" desktop notification appearing after closing a video when running the Linux AppImage.
+- Autoplay Pause Timing: Fixed playback resuming a few seconds before subtitle tokenization warmup finished, most noticeable when resuming mid-episode or when a cue starts within the first two seconds.
+- Stats Known-Word Count: Fixed stats reporting 0 known words for every session after the known-word cache format changed.
+- Stats Library Cover Art: Relinking a title to a different AniList entry now updates its cover in the Library grid immediately instead of leaving a stale, mismatched cover cached.
+- Rofi Prompt Spacing: Rofi menu prompts now keep a space before the input field instead of running into the placeholder text.
+- Stats Settings & Reliability: Hardened stats settings validation (nested/legacy AnkiConnect config now falls back safely instead of breaking) and stats routes against malformed requests and other edge cases.
+- Stats Delete Performance: Deleting sessions, episodes, and library entries is now dramatically faster and no longer stalls playback (e.g. a 12-episode title dropped from about a minute to under a second on a large library); the Vocabulary tab also loads much faster. The first launch after upgrading runs a one-time database migration.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+- Added a golden-file regression test corpus for the tokenizer/annotation pipeline, plus scripts to record new fixtures and diff against stock Yomitan.
+- Consolidated renderer modal state handling into a descriptor registry.
+- Consolidated CI quality checks (PR, stable, and prerelease) into one reusable workflow with mpv plugin tests and dependency audits.
+- Removed the unused stats IPC transport and unified stats dashboard HTTP types with the backend contract.
+- Added a script to verify known-word highlight tiers against live Anki data outside of playback.
+
+</details>
+
+## v0.18.0 (2026-07-10)
+
+### Added
+- Sentence Audio Normalization: Generated sentence audio is now normalized to -23 LUFS by default, and clips mined from playback mirror mpv's software volume curve with a limiter to prevent clipping. Both behaviors are configurable independently.
+- Watch History Command: Added `subminer -H` / `--history` to browse watch history, replay or continue episodes, or pick one via fzf or rofi, with cover art shown in the rofi picker.
+
+### Changed
+- Fzf Preview Layout: Moved fzf previews below launcher menus, giving long titles and metadata more room.
+- Known-Word Highlighting: Now compares subtitle and Anki-card readings, preventing false matches between homographs and unrelated words that share a reading, while still supporting matching across kana and kanji spellings.
+- Annotation Filtering: Standalone suffix tokens (e.g. さん, れる) are now excluded from JLPT/frequency/N+1 highlighting by default, matching how particles and interjections are treated; configurable via the pos2 exclusion setting.
+- App Icon: Replaced the app icon with new pixel-art submarine artwork contributed by the community, used across the app icon, tray, notifications, README, docs site, and Stats page.
+- Stats Trend Charts: Overhauled with persisted title visibility, per-chart title limits, "top" and "most recent" ranking modes, an option to show or hide empty days, calendar-aligned periods, and value-sorted tooltips.
+
+### Fixed
+- Background Stats Server: `subminer app` background launches now auto-start the stats server when enabled, and skip startup if one is already running.
+- Character Name Highlighting: Character dictionaries now split unspaced native names more reliably, and portraits, highlights, and hover lookup survive punctuation, unmatched text, and competing dictionary matches without incorrectly splitting longer words.
+- Highlighting Coverage: Frequency/JLPT highlighting and vocabulary stats now include content adverbs (e.g. 確かに, やはり) and kanji nouns MeCab tags as non-independent (e.g. 日, 点, 以外), while still suppressing interjections, pronouns, and grammar fragments; lexicalized kana expressions like かといって keep their annotations.
+- Cover Art Fetching: Stats now fetches AniList cover art as soon as a new series starts playing, and backfills missing art for existing series on the next Stats visit.
+- Kiku Field Grouping: The manual field-grouping dialog now stays above fullscreen mpv, remains usable across repeated attempts, closes abandoned windows after timeouts, and reports a clear error when the original card can no longer be loaded.
+- Karaoke Subtitle Collapse: Secondary subtitles no longer stack dozens of one-syllable lines during openings and endings; repeated events collapse into one line, capped to a strip at the top.
+- Unparsed Token Hover: Subtitle text Yomitan can't parse (truncated inflections, elongation runs) remains hoverable, while staying excluded from highlighting, N+1 candidate math, and vocabulary stats.
+- YouTube Streaming: Fixed direct YouTube stream extraction that could corrupt signed URLs and cause ffmpeg 403 errors.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+- Test lanes moved to `scripts/test-lanes.ts` with per-directory discovery and isolated per-file timeouts; CI now covers previously orphaned stats, scripts, plugin process-retry, and runtime-compat suites, plus a new stats lane in the change-verification workflow.
+
+</details>
+
+## v0.17.2 (2026-06-28)
+
+### Fixed
+- YouTube Background Cache: Fixed Windows YouTube background media cache startup for YouTube URLs opened directly in mpv, including resolved stream URLs when mpv still exposes the original YouTube playlist entry, so queued Anki media updates can append audio and images after the cache finishes.
+- YouTube Subtitle Picker: Manual subtitle picker requests now show an immediate configured notification while SubMiner probes tracks and opens the modal. Subtitle download progress is replaced with a transient success notification after tracks load.
+
+## v0.17.1 (2026-06-27)
+
+### Added
+- YouTube Media Cache Mode: Adds `youtube.mediaCache.mode` with `direct` and `background` options. Background mode uses a yt-dlp cache download when direct stream extraction is unreliable — creates a text-only card immediately, queues media updates for mined notes, and fills audio/image fields once the download finishes. Progress is announced via overlay/OSD notifications. Downloads are capped at 720p by default (`youtube.mediaCache.maxHeight`). Switching back to direct mode cancels any in-flight background download.
+
+### Fixed
+- Log Export: Fixed log filenames to use the local date so exports around UTC midnight include the current day's logs rather than stale prior-day files. Expanded export redaction to mask IPs, emails, auth and cookie headers, yt-dlp cookie arguments, URL credentials, token/key/password fields, and signed YouTube media URL parameters.
+- YouTube Card Media: Improved media generation reliability by sending safer ffmpeg options for resolved streams and skipping stale stream maps (including cached YouTube files). Hardened background cache downloads with IPv4 and extractor retry flags; failed downloads now notify the user and clear queued media updates instead of leaving them silently pending. Stale background cache files are cleaned on startup and before each new download.
+
+## v0.17.0 (2026-06-15)
+
+### Changed
+
+- **Subtitle Delay Keybindings**: Updated default overlay subtitle delay and step bindings to match mpv conventions: `z`, `Z`, and `x` adjust `sub-delay`; `Ctrl+Shift+Left/Right` run native `sub-step` with OSD feedback. The previous SubMiner-only adjacent-cue delay action has been removed.
+- **Update Notifications**: New installs now default update notifications to overlay-only instead of overlay + system notifications.
+
+### Fixed
+
+- **Anki – Highlight Word**: Fixed bolding of the mined word in Kiku sentence and sentence-furigana fields when the source Yomitan sentence did not already contain bold markup.
+- **Anki – Lapis/Kiku Word Cards**: Fixed word-and-sentence marker missing from Lapis/Kiku word cards enriched through SubMiner, which could hide sentence context on the card front.
+- **Anki – Windows Media Generation**: Fixed known-word cache refreshes when no deck is configured, and fixed audio/image generation after background launches by recreating missing FFmpeg temp directories before clipping.
+- **Character Dictionary – Windows**: Fixed the Windows "SubMiner mpv" shortcut so character dictionary auto-sync can fall back to mpv's current video path when app media state is not yet ready.
+- **Notifications**: Restored the SubMiner app icon on system notifications that do not supply a custom notification image.
+- **Overlay – macOS Yomitan Popup**: Fixed Yomitan popup focus after card mining or popup reload; fixed popups staying open when clicking transparent overlay space — click-away now closes the popup and returns click passthrough to mpv without a hide/reappear cycle.
+- **Overlay – Linux Auto-Pause Startup**: Fixed the visible overlay on Linux auto-paused startup to stay interactive during the initial measurement gap; startup subtitle cache misses now paint raw text before tokenization finishes, and temporarily empty `sub-text` refreshes are resolved before warm readiness resumes playback.
+- **Overlay – Playlist Advance**: Fixed the visible overlay being dismissed when mpv advances to the next playlist item, including when the next episode loads after the warm transition delay.
+- **Overlay – Windows Subtitle Bar**: Fixed shaky hover and click interaction on the Windows subtitle bar when a video attaches to an already-running background SubMiner instance.
+- **Stats – AniList Linking**: Fixed manual AniList linking from the stats anime page so auto-searches strip the generated "Season N" suffix and query only the anime title.
+- **Updates – Linux Support Assets**: Fixed Linux updates to correctly install and refresh the launcher runtime plugin copy and rofi theme alongside AppImage and launcher updates; unrelated SubMiner data directories are now left untouched and plugin copies are staged before replacing the live runtime. Fixed first-launch playback on fresh installs by auto-installing missing managed support assets from the bundled app before mpv starts.
+
+### Docs
+
+- **Linux Update Flows**: Documented that Linux update flows manage the launcher runtime plugin copy and rofi theme from `subminer-assets.tar.gz`, and that normal launcher playback auto-installs those managed support assets on a fresh install if either is missing.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+
+- **Runtime Modules**: Split main-process runtime wiring into focused modules without changing user-facing behavior; hardened helpers against stale background stats daemon PIDs, stalled subtitle extraction, and dropped async errors.
+- **Release CI**: Fixed GitHub release notes to preserve the `What's Changed` and `New Contributors` attribution sections when CI regenerates from the committed changelog; scoped prerelease note reuse to the same base version so a new beta line starts from current fragments.
+
+</details>
+
 ## v0.16.0 (2026-06-10)
 
 ### Breaking Changes

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

Makefile

@@ -2,8 +2,10 @@
 
 APP_NAME := subminer
 THEME_SOURCE := assets/themes/subminer.rasi
+THUMBNAILER_SOURCE := assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer
 LAUNCHER_OUT := dist/launcher/$(APP_NAME)
 THEME_FILE := subminer.rasi
+THUMBNAILER_FILE := subminer-ffmpegthumbnailer.thumbnailer
 
 # Default install prefix for the wrapper script.
 PREFIX ?= $(HOME)/.local
@@ -158,14 +160,8 @@ build-macos-unsigned: deps
 	@bun run build:mac:unsigned
 
 build-launcher:
-	@printf '%s\n' "[INFO] Bundling launcher script"
-	@install -d "$(dir $(LAUNCHER_OUT))"
-	@bun build ./launcher/main.ts --target=bun --packages=bundle --outfile="$(LAUNCHER_OUT)"
-	@if ! head -1 "$(LAUNCHER_OUT)" | grep -q '^#!/usr/bin/env bun'; then \
-		{ printf '#!/usr/bin/env bun\n'; cat "$(LAUNCHER_OUT)"; } > "$(LAUNCHER_OUT).tmp" && mv "$(LAUNCHER_OUT).tmp" "$(LAUNCHER_OUT)"; \
-	fi
-	@chmod +x "$(LAUNCHER_OUT)"
-	@printf '%s\n' "[INFO] Launcher artifact: $(LAUNCHER_OUT)"
+	@printf '%s\n' "[INFO] Building launcher runtime artifacts"
+	@bun run build:launcher
 
 clean:
 	@printf '%s\n' "[INFO] Removing build artifacts"
@@ -221,11 +217,13 @@ docs-dev: ensure-bun
 
 
 install-linux: build-launcher
-	@printf '%s\n' "[INFO] Installing Linux wrapper/theme artifacts"
+	@printf '%s\n' "[INFO] Installing Linux wrapper/support artifacts"
 	@install -d "$(BINDIR)"
 	@install -m 0755 "$(LAUNCHER_OUT)" "$(BINDIR)/$(APP_NAME)"
 	@install -d "$(LINUX_DATA_DIR)/themes"
 	@install -m 0644 "./$(THEME_SOURCE)" "$(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
+	@install -d "$(LINUX_DATA_DIR)/thumbnailers"
+	@install -m 0644 "./$(THUMBNAILER_SOURCE)" "$(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
 	@install -d "$(LINUX_DATA_DIR)/plugin/subminer"
 	@cp -R ./plugin/subminer/. "$(LINUX_DATA_DIR)/plugin/subminer/"
 	@if [ -n "$(APPIMAGE_SRC)" ]; then \
@@ -234,7 +232,7 @@ install-linux: build-launcher
 		printf '%s\n' "[WARN] No release/SubMiner-*.AppImage found; skipping AppImage install"; \
 		printf '%s\n' "       Build one with: make build"; \
 	fi
-	@printf '%s\n' "Installed to:" "  $(BINDIR)/subminer" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
+	@printf '%s\n' "Installed to:" "  $(BINDIR)/subminer" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)" "  $(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
 
 install-macos: build-launcher
 	@printf '%s\n' "[INFO] Installing macOS wrapper/theme/app artifacts"
@@ -275,8 +273,9 @@ uninstall:
 uninstall-linux:
 	@rm -f "$(BINDIR)/subminer" "$(BINDIR)/SubMiner.AppImage"
 	@rm -f "$(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
+	@rm -f "$(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
 	@rm -rf "$(LINUX_DATA_DIR)/plugin/subminer"
-	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(BINDIR)/SubMiner.AppImage" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)" "  $(LINUX_DATA_DIR)/plugin/subminer"
+	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(BINDIR)/SubMiner.AppImage" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)" "  $(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)" "  $(LINUX_DATA_DIR)/plugin/subminer"
 
 uninstall-macos:
 	@rm -f "$(BINDIR)/subminer"

README.md

@@ -4,7 +4,7 @@
 
 # SubMiner
 
-Integrates Yomitan and mpv - on-screen lookups, mine to Anki, and track immersion without leaving the player
+Look up words with Yomitan, mine them to Anki, and track your immersion without leaving mpv
 
 [Installation](#quick-start) · [Requirements](#requirements) · [Usage](https://docs.subminer.moe/usage) · [Documentation](https://docs.subminer.moe)
 
@@ -15,7 +15,7 @@ Integrates Yomitan and mpv - on-screen lookups, mine to Anki, and track immersio
 [![License](https://img.shields.io/github/license/ksyasuda/SubMiner?style=flat-square&color=1a1a2e)](https://www.gnu.org/licenses/gpl-3.0)
 [![TypeScript](https://img.shields.io/badge/TypeScript-1a1a2e?style=flat-square&logo=typescript&logoColor=3178c6)](https://www.typescriptlang.org)
 
-[![SubMiner demo](./assets/minecard.webp)](https://github.com/user-attachments/assets/89e61895-e2b7-4b47-8d50-a35afe4132b2)
+[![SubMiner demo](./assets/minecard.webp)](https://github.com/user-attachments/assets/7abab8a9-4e4e-4f06-9f3c-9783e15a3807)
 
 </div>
 
@@ -23,7 +23,7 @@ Integrates Yomitan and mpv - on-screen lookups, mine to Anki, and track immersio
 
 ### Dictionary Lookups
 
-Hover over any word and trigger a lookup to get the full Yomitan popup - definitions, pitch accent, and frequency data - without ever leaving mpv.
+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.
 
 <div align="center">
   <img src="docs-site/public/screenshots/yomitan-lookup.png" width="800" alt="Yomitan dictionary popup over annotated subtitles in mpv">
@@ -33,7 +33,7 @@ Hover over any word and trigger a lookup to get the full Yomitan popup - definit
 
 ### Instant Anki Mining
 
-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.
+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.
 
 <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">
@@ -43,7 +43,7 @@ Create an Anki card with the sentence, audio clip, screenshot, and machine trans
 
 ### Reading Annotations
 
-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.
+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.
 
 <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">
@@ -53,7 +53,7 @@ Real-time subtitle annotations with frequency highlighting, JLPT tags, N+1 targe
 
 ### Immersion Dashboard
 
-Local stats dashboard tracking watch time, vocabulary growth, mining throughput, session history, and trends. All stored locally, no third-party tracking.
+A stats dashboard tracks watch time, vocabulary growth, mining throughput, session history, and trends. Everything stays on your machine, with 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">
@@ -61,22 +61,12 @@ Local stats dashboard tracking watch time, vocabulary growth, mining throughput,
 
 <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="Stats dashboard showing watch time, cards mined, streaks, and tracking data">
-</div>
-
-<br>
-
 ### Integrations
 
 <table>
   <tr>
     <td><b>YouTube</b></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>
+    <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>
   </tr>
   <tr>
     <td><b>AniList</b></td>
@@ -84,15 +74,27 @@ Browse sibling episode files and the active mpv queue in one overlay modal. Open
   </tr>
   <tr>
     <td><b>Jellyfin</b></td>
-    <td>Browse, launch, and cast media from your Jellyfin server with setup and discovery controls in the app tray</td>
+    <td>Browse your Jellyfin library, or cast to SubMiner from any Jellyfin client. Setup and discovery live in the tray menu</td>
   </tr>
   <tr>
     <td><b>Jimaku</b></td>
-    <td>Search and download Japanese subtitles</td>
+    <td>Search and download Japanese subtitles. Requires a free Jimaku API key</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>
+  </tr>
+  <tr>
+    <td><b>AniSkip</b></td>
+    <td>Automatic intro detection with chapter markers and a one-key skip (<code>TAB</code> by default)</td>
   </tr>
   <tr>
     <td><b>alass / ffsubsync</b></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>
+    <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>
   </tr>
   <tr>
     <td><b>WebSocket</b></td>
@@ -100,28 +102,29 @@ Browse sibling episode files and the active mpv queue in one overlay modal. Open
   </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
 
-Only **mpv** and Anki+AnkiConnect are required. Everything else is optional but enhances the experience.
+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.
 
 | Dependency               | Status           | What it does                                                         |
-| -------------------- | ----------- | ---------------------------------------- |
-| mpv                  | Required    | The video player SubMiner overlays on    |
-| Anki + AnkiConnect   | Required    | Card creation from the Yomitan popup     |
-| ffmpeg               | Recommended | Audio clips & screenshots for Anki cards |
-| MeCab + mecab-ipadic | Recommended | More precise annotations and filtering   |
+| ------------------------ | ---------------- | -------------------------------------------------------------------- |
+| 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                                                     |
-| fzf / rofi           | Optional    | Video picker in the launcher             |
+| xz                       | Optional         | TsukiHime subtitle downloads (most Linux distros already have it)    |
 | alass / ffsubsync        | Optional         | Subtitle sync                                                        |
-| guessit              | Optional    | Better anime title and episode detection |
+| 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                           |
 
 <details>
 <summary><b>Platform-specific install commands</b></summary>
@@ -129,18 +132,35 @@ Only **mpv** and Anki+AnkiConnect are required. Everything else is optional but
 **Arch Linux:**
 
 ```bash
-sudo pacman -S --needed mpv ffmpeg mecab mecab-ipadic
+sudo pacman -S --needed mpv ffmpeg
+paru -S --needed mecab-git mecab-ipadic   # MeCab is only in the AUR
 ```
 
+On desktops other than Hyprland or Sway, also install `xdotool` and `xorg-xwininfo`.
+
 **macOS:**
 
 ```bash
 brew install mpv ffmpeg mecab mecab-ipadic
 ```
 
-**Windows:** Install [mpv](https://mpv.io/installation/) and [ffmpeg](https://ffmpeg.org/download.html) and ensure both are on `PATH`.
+**Windows:**
 
-See the [full requirements list](https://docs.subminer.moe/installation#1-install-requirements) for optional dependencies.
+```powershell
+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.
+
+[Scoop](https://scoop.sh) is the alternative if you want one package manager for everything. 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.
 
 </details>
 
@@ -157,6 +177,8 @@ See the [full requirements list](https://docs.subminer.moe/installation#1-instal
 paru -S subminer-bin
 ```
 
+Includes the AppImage and the `subminer` command.
+
 </details>
 
 <details>
@@ -166,10 +188,10 @@ paru -S subminer-bin
 mkdir -p ~/.local/bin
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppImage -O ~/.local/bin/SubMiner.AppImage \
  && chmod +x ~/.local/bin/SubMiner.AppImage
-wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer \
- && chmod +x ~/.local/bin/subminer
 ```
 
+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.
+
 </details>
 
 <details>
@@ -177,12 +199,14 @@ wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~
 
 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 (`.exe`) from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest).
+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.
 
 </details>
 
@@ -195,27 +219,30 @@ See the [build-from-source guide](https://docs.subminer.moe/installation#from-so
 
 ### 2. Launch & Set Up
 
-Run SubMiner and the first-run setup wizard will guide you through importing Yomitan dictionaries and optionally installing the `subminer` command-line launcher.
+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.
 
 ```bash
-# Linux
-subminer app --setup
-
-# macOS — open SubMiner.app, or:
-subminer app --setup
+subminer app --setup                     # AUR
+~/.local/bin/SubMiner.AppImage --setup   # AppImage
 ```
 
-On **Windows**, just run `SubMiner.exe` and the setup will open automatically on first launch.
+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.
 
 ### 3. Mine
 
 ```bash
-subminer video.mkv          # launch mpv with SubMiner
+subminer video.mkv          # play a video 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
 ```
 
-On **Windows**, use the **SubMiner mpv** shortcut created during setup. Double-click it or drag a video file onto it.
+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.
 
 ## Documentation
 
@@ -233,6 +260,7 @@ SubMiner builds on the work of these open-source projects:
 | [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                                  |
@@ -242,4 +270,6 @@ SubMiner builds on the work of these open-source projects:
 
 ## License
 
-[GNU General Public License v3.0](LICENSE)
+SubMiner is released under the [GNU General Public License v3.0](LICENSE).
+
+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).

assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer

@@ -0,0 +1,4 @@
+[Thumbnailer Entry]
+TryExec=ffmpegthumbnailer
+Exec=ffmpegthumbnailer -i %i -o %o -s %s -f
+MimeType=video/matroska;video/matroska-3d;video/x-matroska;video/x-matroska-3d;

build/bun-runtime-manifest.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": 1,
+  "version": "1.3.5",
+  "bunRevision": "1e86cebd74a5723e818b5c0555276b646bcf0e4c",
+  "releaseTagCommit": "fa5a5bbe556a4bda5bde77b4013aa6c3bb4ec9ab",
+  "artifacts": {
+    "darwin-arm64": {
+      "file": "bun-darwin-aarch64.zip",
+      "sha256": "db17588a4aea8804856825d4bead3f05e1f37276ca606f37e369b4f72f35d3fb"
+    },
+    "darwin-x64": {
+      "file": "bun-darwin-x64-baseline.zip",
+      "sha256": "34b9a56b851058dafa1bc9d61233f2c383aa996889bba30b3180f5ccc2cff1b2"
+    },
+    "linux-arm64": {
+      "file": "bun-linux-aarch64.zip",
+      "sha256": "ed01000f85bd97785228ad2845dc92a1860b8054856826d7317690ac8f8ee74b"
+    },
+    "linux-x64": {
+      "file": "bun-linux-x64-baseline.zip",
+      "sha256": "6bddacd6a65855698b9816f2d74871eda4dd0b7fa921140c6445248f94a742fd"
+    },
+    "win32-x64": {
+      "file": "bun-windows-x64-baseline.zip",
+      "sha256": "bf447dcc3b06aba9b9706a9db46fcd65e06a4d47d31439922313825d06eb47ca"
+    }
+  },
+  "licenseInventoryStatus": "source-and-notices-pinned-to-binary-revision",
+  "sourceManifest": "build/bun-source-manifest.json",
+  "correspondingSourceAsset": "bun-v1.3.5-source.tar.gz"
+}

build/bun-source-manifest.json

@@ -0,0 +1,148 @@
+{
+  "schemaVersion": 1,
+  "version": "1.3.5",
+  "releaseTag": "bun-v1.3.5",
+  "releaseTagCommit": "fa5a5bbe556a4bda5bde77b4013aa6c3bb4ec9ab",
+  "bunRevision": "1e86cebd74a5723e818b5c0555276b646bcf0e4c",
+  "archiveName": "bun-v1.3.5-source.tar.gz",
+  "sources": [
+    {
+      "name": "bun",
+      "repository": "oven-sh/bun",
+      "revision": "1e86cebd74a5723e818b5c0555276b646bcf0e4c",
+      "destination": "bun",
+      "sha256": "3a766087902a62a4920e5ac5452dbc7143ff97ea19721f945146629fc9f2d82c",
+      "licensePaths": ["LICENSE.md"]
+    },
+    {
+      "name": "WebKit",
+      "repository": "oven-sh/WebKit",
+      "revision": "6d0f3aac0b817cc01a846b3754b21271adedac12",
+      "destination": "bun/vendor/WebKit",
+      "transport": "git-sparse",
+      "exclude": ["JSTests", "LayoutTests", "ManualTests", "PerformanceTests", "WebDriverTests"],
+      "licensePaths": ["Source/JavaScriptCore/COPYING.LIB"]
+    },
+    {
+      "name": "boringssl",
+      "repository": "oven-sh/boringssl",
+      "revision": "f1ffd9e83d4f5c28a9c70d73f9a4e6fcf310062f",
+      "destination": "bun/vendor/boringssl",
+      "sha256": "af8fd325793bb261c70114d09a24f36092fbe252be8ec040f0054ec9455f0ea3",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "brotli",
+      "repository": "google/brotli",
+      "revision": "ed738e842d2fbdf2d6459e39267a633c4a9b2f5d",
+      "upstreamReference": "v1.1.0",
+      "destination": "bun/vendor/brotli",
+      "sha256": "aaa739962a45b508b2e783b915e6b2b57ed3b12bd4b0feac73acfb144dffa54f",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "cares",
+      "repository": "c-ares/c-ares",
+      "revision": "3ac47ee46edd8ea40370222f91613fc16c434853",
+      "destination": "bun/vendor/cares",
+      "sha256": "8c94116cb366ae4a44e487da4d9f7e736287d329efa6f88fdf077cd2d0a2e4b8",
+      "licensePaths": ["LICENSE.md"]
+    },
+    {
+      "name": "hdrhistogram",
+      "repository": "HdrHistogram/HdrHistogram_c",
+      "revision": "be60a9987ee48d0abf0d7b6a175bad8d6c1585d1",
+      "destination": "bun/vendor/hdrhistogram",
+      "sha256": "811c5e5ae5303a75ade50688880af6aad5d2f951ec5785f68186bd18635cdfc9",
+      "licensePaths": ["COPYING.txt", "LICENSE.txt"]
+    },
+    {
+      "name": "highway",
+      "repository": "google/highway",
+      "revision": "ac0d5d297b13ab1b89f48484fc7911082d76a93f",
+      "destination": "bun/vendor/highway",
+      "sha256": "a7a816f4b62a0414ff0d39c0a8875847468dd6f7c9ad71781a24469a756cdea7",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "libarchive",
+      "repository": "libarchive/libarchive",
+      "revision": "9525f90ca4bd14c7b335e2f8c84a4607b0af6bdf",
+      "destination": "bun/vendor/libarchive",
+      "sha256": "944db9ab58a3cbdb5d947db4f04a3cc15f83b3147fcf7830ada592ba8d4a102c",
+      "licensePaths": ["COPYING"]
+    },
+    {
+      "name": "libdeflate",
+      "repository": "ebiggers/libdeflate",
+      "revision": "c8c56a20f8f621e6a966b716b31f1dedab6a41e3",
+      "destination": "bun/vendor/libdeflate",
+      "sha256": "1e5cc06bdbf3e1245d8b89c9e3588f507e3c8bc53fe8b8229770a9e8661dea81",
+      "licensePaths": ["COPYING"]
+    },
+    {
+      "name": "libuv",
+      "repository": "libuv/libuv",
+      "revision": "f3ce527ea940d926c40878ba5de219640c362811",
+      "destination": "bun/vendor/libuv",
+      "sha256": "46040d51e8aa86a7c84e377e224d427c35022ec6e3ed8ed399493b0d8574d0cf",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "lolhtml",
+      "repository": "cloudflare/lol-html",
+      "revision": "d64457d9ff0143deef025d5df7e8586092b9afb7",
+      "destination": "bun/vendor/lolhtml",
+      "sha256": "893b77b460f4c4f4634c973f72cf35e38ebe30646d14a92db3f50ee7e586c0ad",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "lshpack",
+      "repository": "litespeedtech/ls-hpack",
+      "revision": "8905c024b6d052f083a3d11d0a169b3c2735c8a1",
+      "destination": "bun/vendor/lshpack",
+      "sha256": "07d8bf901bb1b15543f38eabd23938519e1210eebadb52f3d651d6ef130ef973",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "mimalloc",
+      "repository": "oven-sh/mimalloc",
+      "revision": "1beadf9651a7bfdec6b5367c380ecc3fe1c40d1a",
+      "destination": "bun/vendor/mimalloc",
+      "sha256": "317ec2a83462ece78c344c4955c6fee103b412a8e6a0d6ddf9ec8963ed9c0881",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "picohttpparser",
+      "repository": "h2o/picohttpparser",
+      "revision": "066d2b1e9ab820703db0837a7255d92d30f0c9f5",
+      "destination": "bun/vendor/picohttpparser",
+      "sha256": "637ff2ab6f5c7f7e05a5b5dc393d5cf2fea8d4754fcaceaaf935ffff5c1323ee",
+      "licensePaths": ["picohttpparser.c", "picohttpparser.h"]
+    },
+    {
+      "name": "tinycc",
+      "repository": "oven-sh/tinycc",
+      "revision": "29985a3b59898861442fa3b43f663fc1af2591d7",
+      "destination": "bun/vendor/tinycc",
+      "sha256": "813cc09aafd6cea9c1ae6b745781e6b27576a0c103f49b63b5c8a732bbe3d290",
+      "licensePaths": ["COPYING"]
+    },
+    {
+      "name": "zlib",
+      "repository": "cloudflare/zlib",
+      "revision": "886098f3f339617b4243b286f5ed364b9989e245",
+      "destination": "bun/vendor/zlib",
+      "sha256": "14bf449df8308696af52f87de88f54c9eb9c91ec5e280587f9d37f7a3f6ed9bb",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "zstd",
+      "repository": "facebook/zstd",
+      "revision": "f8745da6ff1ad1e7bab384bd1f9d742439278e99",
+      "destination": "bun/vendor/zstd",
+      "sha256": "4b0bd1f0cfb25e61b9103c35f27395530ff5b4c0d2513a00fd745849e85ea52c",
+      "licensePaths": ["COPYING", "LICENSE"]
+    }
+  ]
+}

bun.lock

@@ -7,48 +7,58 @@
       "dependencies": {
         "@fontsource-variable/geist": "^5.2.8",
         "@fontsource-variable/geist-mono": "^5.2.7",
-        "@xhayper/discord-rpc": "^1.3.3",
-        "axios": "^1.13.5",
+        "@xhayper/discord-rpc": "^1.3.4",
+        "axios": "^1.20.0",
         "commander": "^14.0.3",
-        "electron-updater": "^6.8.3",
-        "hono": "^4.12.7",
+        "electron-updater": "^6.8.9",
+        "hono": "^4.12.28",
         "jsonc-parser": "^3.3.1",
         "koffi": "^2.15.6",
         "libsql": "^0.5.22",
-        "ws": "^8.19.0",
+        "ws": "^8.21.0",
       },
       "devDependencies": {
+        "@electron/asar": "3.4.1",
         "@types/node": "^24.10.0",
         "@types/ws": "^8.18.1",
-        "electron": "42.2.0",
-        "electron-builder": "26.8.2",
+        "electron": "43.7.7",
+        "electron-builder": "26.16.1",
         "esbuild": "^0.25.12",
-        "eslint": "^10.4.0",
+        "eslint": "^10.8.0",
         "prettier": "^3.8.1",
         "typescript": "^5.9.3",
+        "undici": "7.29.1",
       },
     },
   },
+  "patchedDependencies": {
+    "@discordjs/rest@2.6.1": "patches/@discordjs%2Frest@2.6.1.patch",
+  },
   "overrides": {
-    "@xmldom/xmldom": "0.8.12",
-    "app-builder-lib": "26.8.2",
-    "electron-builder-squirrel-windows": "26.8.2",
+    "@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",
+    "form-data": "4.0.6",
+    "ip-address": "10.2.0",
+    "js-yaml": "4.3.2",
     "lodash": "4.18.0",
-    "minimatch": "10.2.3",
+    "minimatch": "10.2.5",
     "picomatch": "4.0.4",
-    "tar": "7.5.11",
+    "tar": "7.5.21",
+    "tmp": "0.2.7",
+    "undici": "7.29.1",
   },
   "packages": {
-    "7zip-bin": ["7zip-bin@5.2.0", "", {}, "sha512-ukTPVhqG4jNzMro2qA9HSCSSVJN3aN7tlb+hfqYCt3ER0yWroeA2VR38MNrOHLQ/cVj+DaIMad0kFCtWWowh/A=="],
-
-    "@develar/schema-utils": ["@develar/schema-utils@2.6.5", "", { "dependencies": { "ajv": "^6.12.0", "ajv-keywords": "^3.4.1" } }, "sha512-0cp4PsWQ/9avqTVMCtZ+GirikIA36ikvjtHweU4/j8yLtgObI0+JUPhYFScgwlteveGB1rt3Cm8UhN04XayDig=="],
-
     "@discordjs/collection": ["@discordjs/collection@2.1.1", "", {}, "sha512-LiSusze9Tc7qF03sLCujF5iZp7K+vRNEDBZ86FT9aQAv3vxMLihUvKvpsCWiQ2DJq1tVckopKm1rxomgNUc9hg=="],
 
-    "@discordjs/rest": ["@discordjs/rest@2.6.1", "", { "dependencies": { "@discordjs/collection": "^2.1.1", "@discordjs/util": "^1.2.0", "@sapphire/async-queue": "^1.5.3", "@sapphire/snowflake": "^3.5.5", "@vladfrangu/async_event_emitter": "^2.4.6", "discord-api-types": "^0.38.40", "magic-bytes.js": "^1.13.0", "tslib": "^2.6.3", "undici": "6.24.1" } }, "sha512-wwQdgjeaoYFiaG+atbqx6aJDpqW7JHAo0HrQkBTbYzM3/PJ3GweQIpgElNcGZ26DCUOXMyawYd0YF7vtr+fZXg=="],
+    "@discordjs/rest": ["@discordjs/rest@2.6.1", "", { "dependencies": { "@discordjs/collection": "^2.1.1", "@discordjs/util": "^1.2.0", "@sapphire/async-queue": "^1.5.3", "@sapphire/snowflake": "^3.5.5", "@vladfrangu/async_event_emitter": "^2.4.6", "discord-api-types": "^0.38.40", "magic-bytes.js": "^1.13.0", "tslib": "^2.6.3", "undici": "6.27.0" } }, "sha512-wwQdgjeaoYFiaG+atbqx6aJDpqW7JHAo0HrQkBTbYzM3/PJ3GweQIpgElNcGZ26DCUOXMyawYd0YF7vtr+fZXg=="],
 
     "@discordjs/util": ["@discordjs/util@1.2.0", "", { "dependencies": { "discord-api-types": "^0.38.33" } }, "sha512-3LKP7F2+atl9vJFhaBjn4nOaSWahZ/yWjOvA4e5pnXkt2qyXRCHLxoBQy81GFtLGCq7K9lPm9R517M1U+/90Qg=="],
 
+    "@electron-internal/extract-zip": ["@electron-internal/extract-zip@1.0.4", "", {}, "sha512-Zr1Vs7E9tpCNhZHDAbFVXc2gEVCG9RqPDjrno5+bdgB6LRAuvgyMHJut4NCVyYwtAieapMzc3fiQ3CSTi75ARg=="],
+
     "@electron/asar": ["@electron/asar@3.4.1", "", { "dependencies": { "commander": "^5.0.0", "glob": "^7.1.6", "minimatch": "^3.0.4" }, "bin": { "asar": "bin/asar.js" } }, "sha512-i4/rNPRS84t0vSRa2HorerGRXWyF4vThfHesw0dmcWHp+cspK743UanA0suA5Q5y8kzY2y6YKrvbIUn69BCAiA=="],
 
     "@electron/fuses": ["@electron/fuses@1.8.0", "", { "dependencies": { "chalk": "^4.1.1", "fs-extra": "^9.0.1", "minimist": "^1.2.5" }, "bin": { "electron-fuses": "dist/bin.js" } }, "sha512-zx0EIq78WlY/lBb1uXlziZmDZI4ubcCXIMJ4uGjXzZW0nS19TjSPeXPAjzzTmKQlJUZm0SbmZhPKP7tuQ1SsEw=="],
@@ -59,7 +69,7 @@
 
     "@electron/osx-sign": ["@electron/osx-sign@1.3.3", "", { "dependencies": { "compare-version": "^0.1.2", "debug": "^4.3.4", "fs-extra": "^10.0.0", "isbinaryfile": "^4.0.8", "minimist": "^1.2.6", "plist": "^3.0.5" }, "bin": { "electron-osx-flat": "bin/electron-osx-flat.js", "electron-osx-sign": "bin/electron-osx-sign.js" } }, "sha512-KZ8mhXvWv2rIEgMbWZ4y33bDHyUKMXnx4M0sTyPNK/vcB81ImdeY9Ggdqy0SWbMDgmbqyQ+phgejh6V3R2QuSg=="],
 
-    "@electron/rebuild": ["@electron/rebuild@4.0.3", "", { "dependencies": { "@malept/cross-spawn-promise": "^2.0.0", "debug": "^4.1.1", "detect-libc": "^2.0.1", "got": "^11.7.0", "graceful-fs": "^4.2.11", "node-abi": "^4.2.0", "node-api-version": "^0.2.1", "node-gyp": "^11.2.0", "ora": "^5.1.0", "read-binary-file-arch": "^1.0.6", "semver": "^7.3.5", "tar": "^7.5.6", "yargs": "^17.0.1" }, "bin": { "electron-rebuild": "lib/cli.js" } }, "sha512-u9vpTHRMkOYCs/1FLiSVAFZ7FbjsXK+bQuzviJZa+lG7BHZl1nz52/IcGvwa3sk80/fc3llutBkbCq10Vh8WQA=="],
+    "@electron/rebuild": ["@electron/rebuild@4.2.0", "", { "dependencies": { "@malept/cross-spawn-promise": "^2.0.0", "debug": "^4.1.1", "node-abi": "^4.2.0", "node-api-version": "^0.2.1", "node-gyp": "^12.2.0", "read-binary-file-arch": "^1.0.6" }, "bin": { "electron-rebuild": "lib/cli.js" } }, "sha512-RKL/O+jGoXJMxrx/5771y1n0xTKmFuOYGO3gMmwypBM6rsH0kou0mswwdXA2JrhIkE4xyC7v9vGk0n6NPzgOxQ=="],
 
     "@electron/universal": ["@electron/universal@2.0.3", "", { "dependencies": { "@electron/asar": "^3.3.1", "@malept/cross-spawn-promise": "^2.0.0", "debug": "^4.3.1", "dir-compare": "^4.2.0", "fs-extra": "^11.1.1", "minimatch": "^9.0.3", "plist": "^3.1.0" } }, "sha512-Wn9sPYIVFRFl5HmwMJkARCCf7rqK/EurkfQ/rJZ14mHP3iYTjZSIOSVonEAnhWeAXwtw7zOekGRlc6yTtZ0t+g=="],
 
@@ -123,13 +133,13 @@
 
     "@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.6.0", "", { "dependencies": { "@eslint/core": "^1.2.1" } }, "sha512-ii6Bw9jJ2zi2cWA2Z+9/QZ/+3DX6kwaV5Q986D/CdP3Lap3w/pgQZ373FV7byY/i7L4IRH/G43I5dz1ClsCbpA=="],
+    "@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.1", "", { "dependencies": { "@eslint/core": "^1.2.1", "levn": "^0.4.1" } }, "sha512-rZAP3aVgB9ds9KOeUSL+zZ21hPmo8dh6fnIFwRQj5EAZl9gzR7wxYbYXYysAM8CTqGmUGyp2S4kUdV17MnGuWQ=="],
+    "@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=="],
 
@@ -145,8 +155,6 @@
 
     "@humanwhocodes/retry": ["@humanwhocodes/retry@0.4.3", "", {}, "sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ=="],
 
-    "@isaacs/cliui": ["@isaacs/cliui@8.0.2", "", { "dependencies": { "string-width": "^5.1.2", "string-width-cjs": "npm:string-width@^4.2.0", "strip-ansi": "^7.0.1", "strip-ansi-cjs": "npm:strip-ansi@^6.0.1", "wrap-ansi": "^8.1.0", "wrap-ansi-cjs": "npm:wrap-ansi@^7.0.0" } }, "sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA=="],
-
     "@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=="],
@@ -173,11 +181,15 @@
 
     "@neon-rs/load": ["@neon-rs/load@0.0.4", "", {}, "sha512-kTPhdZyTQxB+2wpiRcFWrDcejc4JI6tkPuS7UZCG4l6Zvc5kU/gGQ/ozvHTh1XR5tS+UlfAfGuPajjzQjCiHCw=="],
 
-    "@npmcli/agent": ["@npmcli/agent@3.0.0", "", { "dependencies": { "agent-base": "^7.1.0", "http-proxy-agent": "^7.0.0", "https-proxy-agent": "^7.0.1", "lru-cache": "^10.0.1", "socks-proxy-agent": "^8.0.3" } }, "sha512-S79NdEgDQd/NGCay6TCoVzXSj74skRZIKJcpJjC5lOq34SZzyI6MqtiiWoiVWoVrTcGjNeC4ipbh1VIHlpfF5Q=="],
+    "@noble/hashes": ["@noble/hashes@1.8.0", "", {}, "sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A=="],
 
-    "@npmcli/fs": ["@npmcli/fs@4.0.0", "", { "dependencies": { "semver": "^7.3.5" } }, "sha512-/xGlezI6xfGO9NwuJlnwz/K14qD1kCSAGtacBHnGzeAIuJGazcp45KP5NuyARXoKb7cwulAGWVsbeSxdG/cb0Q=="],
+    "@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=="],
 
-    "@pkgjs/parseargs": ["@pkgjs/parseargs@0.11.0", "", {}, "sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg=="],
+    "@peculiar/json-schema": ["@peculiar/json-schema@1.1.12", "", { "dependencies": { "tslib": "^2.0.0" } }, "sha512-coUfuoMeIB7B8/NMekxaDzLhaYmp0HZNPEjYRm9goRou8UZIC3z21s0sL9AWoCw4EG876QyO3kYrc61WNF9B/w=="],
+
+    "@peculiar/utils": ["@peculiar/utils@2.0.3", "", { "dependencies": { "tslib": "^2.8.1" } }, "sha512-+oL3HPFRIZ1St2K50lWCXiioIgSoxzz7R1J3uF6neO2yl1sgmpgY6XXJH4BdpoDkMWznQTeYF6oWNDZLCdQ4eQ=="],
+
+    "@peculiar/webcrypto": ["@peculiar/webcrypto@1.7.1", "", { "dependencies": { "@peculiar/asn1-schema": "^2.7.0", "@peculiar/json-schema": "^1.1.12", "@peculiar/utils": "^2.0.2", "tslib": "^2.8.1", "webcrypto-core": "^1.9.2" } }, "sha512-ODOov0sGMJMf3jPonOkgGqPknTsu+DdQ7kD++gz8aI+aFMOMHFbWAA2taqXXVTdP+OTOQR/znGvSpmkeI0WTYQ=="],
 
     "@sapphire/async-queue": ["@sapphire/async-queue@1.5.5", "", {}, "sha512-cvGzxbba6sav2zZkH8GPf2oGk9yYoD5qrNWdu9fRehifgnFZJMV+nuy2nON2roRO4yQQ+v7MK/Pktl/HgfsUXg=="],
 
@@ -207,47 +219,35 @@
 
     "@types/node": ["@types/node@24.12.4", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-GUUEShf+PBCGW2KaXwcIt3Yk+e3pkKwWKb9GSyM9WQVE+ep2jzmHdGsHzu4wgcZy5fN9FBdVzjpBQsYlpfpgLA=="],
 
-    "@types/plist": ["@types/plist@3.0.5", "", { "dependencies": { "@types/node": "*", "xmlbuilder": ">=11.0.1" } }, "sha512-E6OCaRmAe4WDmWNsL/9RMqdkkzDCY1etutkflWk4c+AcjDU07Pcz1fQwTX0TQz+Pxqn9i4L1TU3UFpjnrcDgxA=="],
-
     "@types/responselike": ["@types/responselike@1.0.3", "", { "dependencies": { "@types/node": "*" } }, "sha512-H/+L+UkTV33uf49PH5pCAUBVPNj2nDBXTN+qS1dOwyyg24l3CcicicCA7ca+HMvJBZcFgl5r8e+RR6elsb4Lyw=="],
 
-    "@types/verror": ["@types/verror@1.10.11", "", {}, "sha512-RlDm9K7+o5stv0Co8i8ZRGxDbrTxhJtgjqjFyVh/tXQyl/rYtTKlnTvZ88oSTeYREWurwx20Js4kTuKCsFkUtg=="],
-
     "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
 
-    "@types/yauzl": ["@types/yauzl@2.10.3", "", { "dependencies": { "@types/node": "*" } }, "sha512-oJoftv0LSuaDZE3Le4DbKX+KS9G36NzOeSap90UIK0yMA/NhKJhqlSGtNDORNRaIbQfzjXDrQa0ytJ6mNRGz/Q=="],
-
     "@vladfrangu/async_event_emitter": ["@vladfrangu/async_event_emitter@2.4.7", "", {}, "sha512-Xfe6rpCTxSxfbswi/W/Pz7zp1WWSNn4A0eW4mLkQUewCrXXtMj31lCg+iQyTkh/CkusZSq9eDflu7tjEDXUY6g=="],
 
-    "@xhayper/discord-rpc": ["@xhayper/discord-rpc@1.3.3", "", { "dependencies": { "@discordjs/rest": "^2.6.1", "@vladfrangu/async_event_emitter": "^2.4.7", "discord-api-types": "^0.38.42", "ws": "^8.20.0" } }, "sha512-Ih48GHiua7TtZgKO+f0uZPhCeQqb84fY2qUys/oMh8UbUfiUkUJLVCmd/v2AK0/pV33euh0aqSXo7+9LiPSwGw=="],
+    "@xhayper/discord-rpc": ["@xhayper/discord-rpc@1.3.4", "", { "dependencies": { "@discordjs/rest": "^2.6.1", "@vladfrangu/async_event_emitter": "^2.4.7", "discord-api-types": "^0.38.47", "ws": "^8.20.0" } }, "sha512-ff0uEXuibh9wi+l4vOj7xInLUjtlTaQBje/SCyQkeXZ0j2V0y+Zge5PQIQFRHH9TjjGaYJkTofEcQhncM2q7/w=="],
 
-    "@xmldom/xmldom": ["@xmldom/xmldom@0.8.12", "", {}, "sha512-9k/gHF6n/pAi/9tqr3m3aqkuiNosYTurLLUtc7xQ9sxB/wm7WPygCv8GYa6mS0fLJEHhqMC1ATYhz++U/lRHqg=="],
+    "@xmldom/xmldom": ["@xmldom/xmldom@0.8.15", "", {}, "sha512-/5NV/vDALVFDXgLmfsy9TRCBlKwO2LNBFzpzvb9iIj+jR+eSc6DLYYvVOdivT/jm7MtU6TebYuRmzEOI7w40UA=="],
 
-    "abbrev": ["abbrev@3.0.1", "", {}, "sha512-AO2ac6pjRB3SJmGJo+v5/aK6Omggp6fsLrs6wN9bd35ulu4cCwaAU9+7ZhXjeqHVkaHThLuzH0nZr0YpCDhygg=="],
+    "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@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
+    "agent-base": ["agent-base@6.0.2", "", { "dependencies": { "debug": "4" } }, "sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ=="],
 
     "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=="],
 
-    "ajv-keywords": ["ajv-keywords@3.5.2", "", { "peerDependencies": { "ajv": "^6.9.1" } }, "sha512-5p6WTN0DdTGVQk6VjcEju19IgaHudalcfabD7yhDGeA6bcQnmL+CpveLJq/3hvfwd1aof6L386Ougkx6RfyMIQ=="],
-
     "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-bin": ["app-builder-bin@5.0.0-alpha.12", "", {}, "sha512-j87o0j6LqPL3QRr8yid6c+Tt5gC7xNfYo6uQIQkorAC6MpeayVMZrEDzKmJJ/Hlv7EnOQpaRm53k6ktDYZyB6w=="],
-
-    "app-builder-lib": ["app-builder-lib@26.8.2", "", { "dependencies": { "@develar/schema-utils": "~2.6.5", "@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.3", "@electron/universal": "2.0.3", "@malept/flatpak-bundler": "^0.4.0", "@types/fs-extra": "9.0.13", "async-exit-hook": "^2.0.1", "builder-util": "26.8.1", "builder-util-runtime": "9.5.1", "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.8.1", "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.0.3", "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", "which": "^5.0.0" }, "peerDependencies": { "dmg-builder": "26.8.2", "electron-builder-squirrel-windows": "26.8.2" } }, "sha512-z3ptLzJwNl35fyR0wxv4qWOfZuU36VysYHnbs8PDtf8S0QzIl2OWimdDFVmCxYMkIV1k/RT9CeTgcP7oUznFOw=="],
+    "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=="],
 
     "argparse": ["argparse@2.0.1", "", {}, "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="],
 
-    "assert-plus": ["assert-plus@1.0.0", "", {}, "sha512-NfJ4UzBCcQGLDlQq7nHxH+tv3kyZ0hHQqF5BO6J7tNJeP5do1llPr8dZ8zHonfhAu0PHAdMkSo+8o0wxg9lZWw=="],
-
-    "astral-regex": ["astral-regex@2.0.0", "", {}, "sha512-Z7tMw1ytTXt5jqMcOP+OQteU1VuNK9Y02uuJtKQ1Sv69jXQKKg5cibLwGJow8yzZP+eAc18EmLGPal0bp36rvQ=="],
+    "asn1js": ["asn1js@3.0.10", "", { "dependencies": { "pvtsutils": "^1.3.6", "pvutils": "^1.1.5", "tslib": "^2.8.1" } }, "sha512-S2s3aOytiKdFRdulw2qPE51MzjzVOisppcVv7jVFR+Kw0kxwvFrDcYA0h7Ndqbmj0HkMIXYWaoj7fli8kgx1eg=="],
 
     "async": ["async@3.2.6", "", {}, "sha512-htCUDlxyyCLMgaM3xXg0C0LW2xqfuQ6p05pCEIsXuyQ+a1koYKTuBMzRNwmybfLgvJDMd0r1LTn4+E0Ti6C2AA=="],
 
@@ -257,29 +257,27 @@
 
     "at-least-node": ["at-least-node@1.0.0", "", {}, "sha512-+q/t7Ekv1EDY2l6Gda6LLiX14rU9TV20Wa3ofeQmwPFZbOMo9DXrLbOjFaaclkXKWidIaopwAObQDqwWtGUjqg=="],
 
-    "axios": ["axios@1.13.6", "", { "dependencies": { "follow-redirects": "^1.15.11", "form-data": "^4.0.5", "proxy-from-env": "^1.1.0" } }, "sha512-ChTCHMouEe2kn713WHbQGcuYrr6fXTBiu460OTwWrWob16g1bXn4vtz07Ope7ewMozJAnEquLk5lWQWtBig9DQ=="],
+    "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=="],
 
     "balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
 
     "base64-js": ["base64-js@1.5.1", "", {}, "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA=="],
 
-    "bl": ["bl@4.1.0", "", { "dependencies": { "buffer": "^5.5.0", "inherits": "^2.0.4", "readable-stream": "^3.4.0" } }, "sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w=="],
+    "bluebird": ["bluebird@3.7.2", "", {}, "sha512-XpNj6GDQzdfW+r2Wnn7xiSAd7TM3jzkxGXBGTtWKuSXv1xUV+azxAm8jdWZN06QTQk+2N2XB9jRDkvbmQmcRtg=="],
 
     "boolean": ["boolean@3.2.0", "", {}, "sha512-d0II/GO9uf9lfUHH2BQsjxzRJZBdsjgsBiW4BvhWk/3qoKwQFjIDVN19PfX8F2D/r9PCMTtLWjYVCFrpeYUzsw=="],
 
-    "brace-expansion": ["brace-expansion@5.0.4", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-h+DEnpVvxmfVefa4jFbCf5HdH5YMDXRsmKflpf1pILZWRFlTbJpxeU55nJl4Smt5HQaGzg1o6RHFPJaOqnmBDg=="],
-
-    "buffer": ["buffer@5.7.1", "", { "dependencies": { "base64-js": "^1.3.1", "ieee754": "^1.1.13" } }, "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ=="],
-
-    "buffer-crc32": ["buffer-crc32@0.2.13", "", {}, "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ=="],
+    "brace-expansion": ["brace-expansion@5.0.11", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-awigjhi6cLTh90bdw6+QJ9CtmJmyYhEIi70iCbc8Rozn04Fw9FeQIBjv/E22FFGuCGx1bLJyUfB64x/szUSXUg=="],
 
     "buffer-from": ["buffer-from@1.1.2", "", {}, "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ=="],
 
-    "builder-util": ["builder-util@26.8.1", "", { "dependencies": { "7zip-bin": "~5.2.0", "@types/debug": "^4.1.6", "app-builder-bin": "5.0.0-alpha.12", "builder-util-runtime": "9.5.1", "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-pm1lTYbGyc90DHgCDO7eo8Rl4EqKLciayNbZqGziqnH9jrlKe8ZANGdityLZU+pJh16dfzjAx2xQq9McuIPEtw=="],
+    "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-runtime": ["builder-util-runtime@9.5.1", "", { "dependencies": { "debug": "^4.3.4", "sax": "^1.2.4" } }, "sha512-qt41tMfgHTllhResqM5DcnHyDIWNgzHvuY2jDcYP9iaGpkWxTUzV6GQjDeLnlR1/DtdlcsWQbA7sByMpmJFTLQ=="],
+    "builder-util-runtime": ["builder-util-runtime@9.7.0", "", { "dependencies": { "debug": "^4.3.4", "sax": "^1.2.4" } }, "sha512-g/kR520giAFYkSXTzcmF3kqQq7wi8F6N6SzeDgZrqTBN+VHdmgWOyTdD1yD7AATDId/yXLvuP34CxW46/BwCdw=="],
 
-    "cacache": ["cacache@19.0.1", "", { "dependencies": { "@npmcli/fs": "^4.0.0", "fs-minipass": "^3.0.0", "glob": "^10.2.2", "lru-cache": "^10.0.1", "minipass": "^7.0.3", "minipass-collect": "^2.0.1", "minipass-flush": "^1.0.5", "minipass-pipeline": "^1.2.4", "p-map": "^7.0.2", "ssri": "^12.0.0", "tar": "^7.4.3", "unique-filename": "^4.0.0" } }, "sha512-hdsUxulXCi5STId78vRVYEtDAjq99ICAUktLTeTYsLoTE6Z8dS0c8pWNCxwdrk9YfJeobDZc2Y186hD/5ZQgFQ=="],
+    "bytestreamjs": ["bytestreamjs@2.0.1", "", {}, "sha512-U1Z/ob71V/bXfVABvNr/Kumf5VyeQRBEm6Txb0PQ6S7V5GpBM3w4Cbqz/xPDicR5tN0uvDifng8C+5qECeGwyQ=="],
 
     "cacheable-lookup": ["cacheable-lookup@5.0.4", "", {}, "sha512-2/kNscPhpcxrOigMZzbiWF7dz8ilhb/nIHU3EyZiXWXpeq/au8qJ8VhdftMkty3n7Gj6HIGalQG8oiBNB3AJgA=="],
 
@@ -295,16 +293,8 @@
 
     "ci-info": ["ci-info@4.4.0", "", {}, "sha512-77PSwercCZU2Fc4sX94eF8k8Pxte6JAwL4/ICZLFjJLqegs7kCuAsqqj/70NQF6TvDpgFjkubQB2FW2ZZddvQg=="],
 
-    "cli-cursor": ["cli-cursor@3.1.0", "", { "dependencies": { "restore-cursor": "^3.1.0" } }, "sha512-I/zHAwsKf9FqGoXM4WWRACob9+SNukZTd94DWF57E4toouRulbCxcUh6RKUEOQlYTHJnzkPMySvPNaaSLNfLZw=="],
-
-    "cli-spinners": ["cli-spinners@2.9.2", "", {}, "sha512-ywqV+5MmyL4E7ybXgKys4DugZbX0FC6LnwrhjuykIjnK9k8OQacQ7axGKnjDXWNhns0xot3bZI5h55H8yo9cJg=="],
-
-    "cli-truncate": ["cli-truncate@2.1.0", "", { "dependencies": { "slice-ansi": "^3.0.0", "string-width": "^4.2.0" } }, "sha512-n8fOixwDD6b/ObinzTrp1ZKFzbgvKZvuz/TvejnLn1aQfC6r52XEx85FmuC+3HI+JM7coBRXUvNqEU2PHVrHpg=="],
-
     "cliui": ["cliui@8.0.1", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.1", "wrap-ansi": "^7.0.0" } }, "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ=="],
 
-    "clone": ["clone@1.0.4", "", {}, "sha512-JQHZ2QMW6l3aH/j6xCqQThY/9OH4D/9ls34cgkUBiEeocRTU04tHfKPBsUK1PqZCUQM7GiA0IIXJSuXHI64Kbg=="],
-
     "clone-response": ["clone-response@1.0.3", "", { "dependencies": { "mimic-response": "^1.0.0" } }, "sha512-ROoL94jJH2dUVML2Y/5PEDNaSHgeOdSDicUyS7izcF63G6sTc/FTjLub4b8Il9S8S0beOfYt0TaA5qvFK+w0wA=="],
 
     "color-convert": ["color-convert@2.0.1", "", { "dependencies": { "color-name": "~1.1.4" } }, "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ=="],
@@ -319,8 +309,6 @@
 
     "core-util-is": ["core-util-is@1.0.2", "", {}, "sha512-3lqz5YjWTYnW6dlDa5TLaTCcShfar1e40rmcJVwCBJC6mWlFuj0eCHIElmG1g5kyuJ/GD+8Wn4FFCcz4gJPfaQ=="],
 
-    "crc": ["crc@3.8.0", "", { "dependencies": { "buffer": "^5.1.0" } }, "sha512-iX3mfgcTMIq3ZKLIsVFAbv7+Mc10kxabAGQb8HvjA1o3T1PIYprbakQ65d3I+2HGHt6nSKkM9PYjgoJO2KcFBQ=="],
-
     "cross-dirname": ["cross-dirname@0.1.0", "", {}, "sha512-+R08/oI0nl3vfPcqftZRpytksBXDzOUveBq/NBVx0sUp1axwzPQrKinNx5yd5sxPu8j1wIy8AfnVQ+5eFdha6Q=="],
 
     "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
@@ -331,8 +319,6 @@
 
     "deep-is": ["deep-is@0.1.4", "", {}, "sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ=="],
 
-    "defaults": ["defaults@1.0.4", "", { "dependencies": { "clone": "^1.0.2" } }, "sha512-eFuaLoy/Rxalv2kr+lqMlUnrDWV+3j4pljOIJgLIhI058IQfWJ7vXhyEIHu+HtC738klGALYxOKDO0bQP3tg8A=="],
-
     "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=="],
@@ -347,11 +333,9 @@
 
     "dir-compare": ["dir-compare@4.2.0", "", { "dependencies": { "minimatch": "^3.0.5", "p-limit": "^3.1.0 " } }, "sha512-2xMCmOoMrdQIPHdsTawECdNPwlVFB9zGcz3kuhmBO6U3oU+UQjsue0i8ayLKpgBcm+hcXPMVSGUN9d+pvJ6+VQ=="],
 
-    "discord-api-types": ["discord-api-types@0.38.43", "", {}, "sha512-sSoBf/nK6m7BGtw65mi+QBuvEWaHE8MMziFLqWL+gT6ME/BLg34dRSVKS3Husx40uU06bvxUc3/X+D9Y6/zAbw=="],
+    "discord-api-types": ["discord-api-types@0.38.49", "", {}, "sha512-XnqcWmnFZFAE8ZM8SHAw9DIV8D3Or00rMQ8iQLotrEA2PmXhl+ykaf6L6q4l474hrSUH1JaYcv+iOMRWp2p6Tg=="],
 
-    "dmg-builder": ["dmg-builder@26.8.2", "", { "dependencies": { "app-builder-lib": "26.8.2", "builder-util": "26.8.1", "fs-extra": "^10.1.0", "iconv-lite": "^0.6.2", "js-yaml": "^4.1.0" }, "optionalDependencies": { "dmg-license": "^1.0.11" } }, "sha512-DaWI+p4DOqiFVZFMovdGYammBOyJAiHHFWUTQ0Z7gNc0twfdIN0LvyJ+vFsgZEDR1fjgbpCj690IVtbYIsZObQ=="],
-
-    "dmg-license": ["dmg-license@1.0.11", "", { "dependencies": { "@types/plist": "^3.0.1", "@types/verror": "^1.10.3", "ajv": "^6.10.0", "crc": "^3.8.0", "iconv-corefoundation": "^1.1.7", "plist": "^3.0.4", "smart-buffer": "^4.0.2", "verror": "^1.10.0" }, "os": "darwin", "bin": { "dmg-license": "bin/dmg-license.js" } }, "sha512-ZdzmqwKmECOWJpqefloC5OJy1+WZBBse5+MR88z9g9Zn4VY+WYUkAyojmhzJckH5YbbZGcYIuGAkY5/Ys5OM2Q=="],
+    "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=="],
 
     "dotenv": ["dotenv@16.6.1", "", {}, "sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow=="],
 
@@ -359,26 +343,24 @@
 
     "dunder-proto": ["dunder-proto@1.0.1", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.1", "es-errors": "^1.3.0", "gopd": "^1.2.0" } }, "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A=="],
 
-    "eastasianwidth": ["eastasianwidth@0.2.0", "", {}, "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA=="],
+    "duplexer2": ["duplexer2@0.1.4", "", { "dependencies": { "readable-stream": "^2.0.2" } }, "sha512-asLFVfWWtJ90ZyOUHMqk7/S2w2guQKxUI2itj3d92ADHhxUSbCMGi1f1cBcJ7xM1To+pE/Khbwo1yuNbMEPKeA=="],
 
     "ejs": ["ejs@3.1.10", "", { "dependencies": { "jake": "^10.8.5" }, "bin": { "ejs": "bin/cli.js" } }, "sha512-UeJmFfOrAQS8OJWPZ4qtgHyWExa088/MtK5UEyoJGFH67cDEXkZSviOiKRCZ4Xij0zxI3JECgYs3oKx+AizQBA=="],
 
-    "electron": ["electron@42.2.0", "", { "dependencies": { "@electron/get": "^5.0.0", "@types/node": "^24.9.0", "extract-zip": "^2.0.1" }, "bin": { "electron": "cli.js", "install-electron": "install.js" } }, "sha512-b2Tc7sIKiZEl0tBVwFM5GJ+FT5KYhmy9QJHjx8BGVZPVW2SctXWEvrE959ElB56qw7H05dBkhlikDA1DmpaAMw=="],
+    "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-builder": ["electron-builder@26.8.2", "", { "dependencies": { "app-builder-lib": "26.8.2", "builder-util": "26.8.1", "builder-util-runtime": "9.5.1", "chalk": "^4.1.2", "ci-info": "^4.2.0", "dmg-builder": "26.8.2", "fs-extra": "^10.1.0", "lazy-val": "^1.0.5", "simple-update-notifier": "2.0.0", "yargs": "^17.6.2" }, "bin": { "electron-builder": "cli.js", "install-app-deps": "install-app-deps.js" } }, "sha512-ieiiXPdgH3qrG6lcvy2mtnI5iEmAopmLuVRMSJ5j40weU0tgpNx0OAk9J5X5nnO0j9+KIkxHzwFZVUDk1U3aGw=="],
+    "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-squirrel-windows": ["electron-builder-squirrel-windows@26.8.2", "", { "dependencies": { "app-builder-lib": "26.8.2", "builder-util": "26.8.1", "electron-winstaller": "5.4.0" } }, "sha512-kXhajX6DzdIQcTlctVTKoG1oO39JhWcTG0lH7ZEJ4FzPaKJy7KFNfNJUd5BoEmLjv5GlrRZpEOYnniD+LcwNJA=="],
+    "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-publish": ["electron-publish@26.8.1", "", { "dependencies": { "@types/fs-extra": "^9.0.11", "builder-util": "26.8.1", "builder-util-runtime": "9.5.1", "chalk": "^4.1.2", "form-data": "^4.0.5", "fs-extra": "^10.1.0", "lazy-val": "^1.0.5", "mime": "^2.5.2" } }, "sha512-q+jrSTIh/Cv4eGZa7oVR+grEJo/FoLMYBAnSL5GCtqwUpr1T+VgKB/dn1pnzxIxqD8S/jP1yilT9VrwCqINR4w=="],
+    "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-updater": ["electron-updater@6.8.3", "", { "dependencies": { "builder-util-runtime": "9.5.1", "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-Z6sgw3jgbikWKXei1ENdqFOxBP0WlXg3TtKfz0rgw2vIZFJUyI4pD7ZN7jrkm7EoMK+tcm/qTnPUdqfZukBlBQ=="],
+    "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=="],
 
     "electron-winstaller": ["electron-winstaller@5.4.0", "", { "dependencies": { "@electron/asar": "^3.2.1", "debug": "^4.1.1", "fs-extra": "^7.0.1", "lodash": "^4.17.21", "temp": "^0.9.0" }, "optionalDependencies": { "@electron/windows-sign": "^1.1.2" } }, "sha512-bO3y10YikuUwUuDUQRM4KfwNkKhnpVO7IPdbsrejwN9/AABJzzTQ4GeHwyzNSrVO+tEH3/Np255a3sVZpZDjvg=="],
 
     "emoji-regex": ["emoji-regex@8.0.0", "", {}, "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A=="],
 
-    "encoding": ["encoding@0.1.13", "", { "dependencies": { "iconv-lite": "^0.6.2" } }, "sha512-ETBauow1T35Y/WZMkio9jiM0Z5xjHHmJ4XmjZOq1l/dXz3lr2sRn87nJy20RupqSh1F2m3HHPSp8ShIPQJrJ3A=="],
-
     "end-of-stream": ["end-of-stream@1.4.5", "", { "dependencies": { "once": "^1.4.0" } }, "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg=="],
 
     "env-paths": ["env-paths@3.0.0", "", {}, "sha512-dtJUTepzMW3Lm/NPxRf3wP4642UWhjL2sQxc+ym2YMj1m/H2zDNQOlezafzkHwn6sMstjHTwG6iQQsctDW/b1A=="],
@@ -401,7 +383,7 @@
 
     "escape-string-regexp": ["escape-string-regexp@4.0.0", "", {}, "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA=="],
 
-    "eslint": ["eslint@10.4.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.6.0", "@eslint/core": "^1.2.1", "@eslint/plugin-kit": "^0.7.1", "@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.4", "natural-compare": "^1.4.0", "optionator": "^0.9.3" }, "peerDependencies": { "jiti": "*" }, "optionalPeers": ["jiti"], "bin": { "eslint": "bin/eslint.js" } }, "sha512-loXy6bWOoP3EP6JA7jo6p5jMpBJmHmsNZM5SFRHLdh1MGOPurMnNBj4ZlAbaqUAaQWbCr7jHV4P7gzAyryZWkQ=="],
+    "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=="],
 
@@ -419,17 +401,13 @@
 
     "exponential-backoff": ["exponential-backoff@3.1.3", "", {}, "sha512-ZgEeZXj30q+I0EN+CbSSpIyPaJ5HVQD18Z1m+u1FXbAeT94mr1zw50q4q6jiiC447Nl/YTcIYSAftiGqetwXCA=="],
 
-    "extract-zip": ["extract-zip@2.0.1", "", { "dependencies": { "debug": "^4.1.1", "get-stream": "^5.1.0", "yauzl": "^2.10.0" }, "optionalDependencies": { "@types/yauzl": "^2.9.1" }, "bin": { "extract-zip": "cli.js" } }, "sha512-GDhU9ntwuKyGXdZBUgTIe+vXnWj0fppUEtMDL0+idd5Sta8TGpHssn/eusA9mrPr9qNDym6SxAYZjNvCn/9RBg=="],
-
-    "extsprintf": ["extsprintf@1.4.1", "", {}, "sha512-Wrk35e8ydCKDj/ArClo1VrPVmN8zph5V4AtHwIuHhvMXsKf73UT3BOD+azBIW+3wOJ4FhEH7zyaJCFvChjYvMA=="],
-
     "fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
 
     "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=="],
 
-    "fd-slicer": ["fd-slicer@1.1.0", "", { "dependencies": { "pend": "~1.2.0" } }, "sha512-cE1qsB/VwyQozZ+q1dGxR8LBYNZeofhEdUNGSMbQD3Gw2lAzX9Zb3uIU6Ebc/Fmyjo9AWWfnn0AUCHqtevs/8g=="],
+    "fast-uri": ["fast-uri@3.1.7", "", {}, "sha512-dOvZVzjdZdz7phd9v6jCbwxrBW3fK6n8Rc0CtdmM4bumzMnxywBYhuph6J819RRw/ku+rLbelwfMunktuzVVHg=="],
 
     "fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],
 
@@ -443,16 +421,12 @@
 
     "flatted": ["flatted@3.4.2", "", {}, "sha512-PjDse7RzhcPkIJwy5t7KPWQSZ9cAbzQXcafsetQoD7sOJRQlGikNbx7yZp2OotDnJyrDcbyRq3Ttb18iYOqkxA=="],
 
-    "follow-redirects": ["follow-redirects@1.15.11", "", {}, "sha512-deG2P0JfjrTxl50XGCDyfI97ZGVCxIpfKYmfyrQ54n5FO/0gfIES8C/Psl6kWVDolizcaaxZJnTS0QSMxvnsBQ=="],
+    "follow-redirects": ["follow-redirects@1.16.0", "", {}, "sha512-y5rN/uOsadFT/JfYwhxRS5R7Qce+g3zG97+JrtFZlC9klX/W5hD7iiLzScI4nZqUS7DNUdhPgw4xI8W2LuXlUw=="],
 
-    "foreground-child": ["foreground-child@3.3.1", "", { "dependencies": { "cross-spawn": "^7.0.6", "signal-exit": "^4.0.1" } }, "sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw=="],
-
-    "form-data": ["form-data@4.0.5", "", { "dependencies": { "asynckit": "^0.4.0", "combined-stream": "^1.0.8", "es-set-tostringtag": "^2.1.0", "hasown": "^2.0.2", "mime-types": "^2.1.12" } }, "sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w=="],
+    "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=="],
 
     "fs-extra": ["fs-extra@10.1.0", "", { "dependencies": { "graceful-fs": "^4.2.0", "jsonfile": "^6.0.1", "universalify": "^2.0.0" } }, "sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ=="],
 
-    "fs-minipass": ["fs-minipass@3.0.3", "", { "dependencies": { "minipass": "^7.0.3" } }, "sha512-XUBA9XClHbnJWSfBzjkm6RvPsyg3sryZt06BEQoXcF7EK/xpGaQYJgQKDJSUH5SGZ76Y7pFx1QBnXz09rU5Fbw=="],
-
     "fs.realpath": ["fs.realpath@1.0.0", "", {}, "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw=="],
 
     "function-bind": ["function-bind@1.1.2", "", {}, "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA=="],
@@ -487,25 +461,19 @@
 
     "has-tostringtag": ["has-tostringtag@1.0.2", "", { "dependencies": { "has-symbols": "^1.0.3" } }, "sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw=="],
 
-    "hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
+    "hasown": ["hasown@2.0.4", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A=="],
 
-    "hono": ["hono@4.12.8", "", {}, "sha512-VJCEvtrezO1IAR+kqEYnxUOoStaQPGrCmX3j4wDTNOcD1uRPFpGlwQUIW8niPuvHXaTUxeOUl5MMDGrl+tmO9A=="],
+    "hono": ["hono@4.12.28", "", {}, "sha512-YwUvVpSF7m1yOblFPrU3Hbo8XhPheBoiyfGuII6z19LnOr6JpDnyyp7LFNrfV56wS8tpvtBFGRISHN02pDdLOA=="],
 
     "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.2.0", "", {}, "sha512-dTxcvPXqPvXBQpq5dUr6mEMJX4oIEFv6bwom3FDwKRDsuIjjJGANqhBuoAn9c1RQJIdAKav33ED65E2ys+87QQ=="],
+    "http-cache-semantics": ["http-cache-semantics@4.3.0", "", {}, "sha512-M5t5LlJpS1UHMjvwRQVdFHvPISGeLAxNcrWuJkeGh0KxsqCHZ1O3NXZU/8x7cD0BDcGW8kapxMKTvwlqrNkHkA=="],
 
     "http-proxy-agent": ["http-proxy-agent@7.0.2", "", { "dependencies": { "agent-base": "^7.1.0", "debug": "^4.3.4" } }, "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig=="],
 
     "http2-wrapper": ["http2-wrapper@1.0.3", "", { "dependencies": { "quick-lru": "^5.1.1", "resolve-alpn": "^1.0.0" } }, "sha512-V+23sDMr12Wnz7iTcDeJr3O6AIxlnvT/bmaAAAP/Xda35C90p9599p0F1eHR/N1KILWSoWVAiOMFjBBXaXSMxg=="],
 
-    "https-proxy-agent": ["https-proxy-agent@7.0.6", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "4" } }, "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw=="],
-
-    "iconv-corefoundation": ["iconv-corefoundation@1.1.7", "", { "dependencies": { "cli-truncate": "^2.1.0", "node-addon-api": "^1.6.3" }, "os": "darwin" }, "sha512-T10qvkw0zz4wnm560lOEg0PovVqUXuOFhhHAkixw8/sycy7TJt7v/RrkEKEQnAw2viPSJu6iAkErxnzR0g8PpQ=="],
-
-    "iconv-lite": ["iconv-lite@0.6.3", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw=="],
-
-    "ieee754": ["ieee754@1.2.1", "", {}, "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA=="],
+    "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=="],
 
@@ -515,29 +483,23 @@
 
     "inherits": ["inherits@2.0.4", "", {}, "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="],
 
-    "ip-address": ["ip-address@10.1.0", "", {}, "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q=="],
-
     "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=="],
 
-    "is-interactive": ["is-interactive@1.0.0", "", {}, "sha512-2HvIEKRoqS62guEC+qBjpvRubdX910WCMuJTZ+I9yvqKU2/12eSL549HMwtabb4oupdj2sMP50k+XJfB/8JE6w=="],
-
-    "is-unicode-supported": ["is-unicode-supported@0.1.0", "", {}, "sha512-knxG2q4UC3u8stRGyAVJCOdxFmv5DZiRcdlIaAQXAbSfJya+OhopNotLQrstBhququ4ZpuKbDc/8S6mgXgPFPw=="],
+    "isarray": ["isarray@1.0.0", "", {}, "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ=="],
 
     "isbinaryfile": ["isbinaryfile@5.0.7", "", {}, "sha512-gnWD14Jh3FzS3CPhF0AxNOJ8CxqeblPTADzI38r0wt8ZyQl5edpy75myt08EG2oKvpyiqSqsx+Wkz9vtkbTqYQ=="],
 
     "isexe": ["isexe@3.1.5", "", {}, "sha512-6B3tLtFqtQS4ekarvLVMZ+X+VlvQekbe4taUkf/rhVO3d/h0M2rfARm/pXLcPEsjjMsFgrFgSrhQIxcSVrBz8w=="],
 
-    "jackspeak": ["jackspeak@3.4.3", "", { "dependencies": { "@isaacs/cliui": "^8.0.2" }, "optionalDependencies": { "@pkgjs/parseargs": "^0.11.0" } }, "sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw=="],
-
     "jake": ["jake@10.9.4", "", { "dependencies": { "async": "^3.2.6", "filelist": "^1.0.4", "picocolors": "^1.1.1" }, "bin": { "jake": "bin/cli.js" } }, "sha512-wpHYzhxiVQL+IV05BLE2Xn34zW1S223hvjtqk0+gsPrwd/8JNLXJgZZM/iPFsYc1xyphF+6M6EvdE5E9MBGkDA=="],
 
     "jiti": ["jiti@2.6.1", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ=="],
 
-    "js-yaml": ["js-yaml@4.1.1", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA=="],
+    "js-yaml": ["js-yaml@4.3.2", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA=="],
 
     "json-buffer": ["json-buffer@3.0.1", "", {}, "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ=="],
 
@@ -571,16 +533,12 @@
 
     "lodash.isequal": ["lodash.isequal@4.5.0", "", {}, "sha512-pDo3lu8Jhfjqls6GkMgpahsF9kCyayhgykjyLMNFTKWrpVdAQtYyB4muAMWozBB4ig/dtWAmsMxLEI8wuz+DYQ=="],
 
-    "log-symbols": ["log-symbols@4.1.0", "", { "dependencies": { "chalk": "^4.1.0", "is-unicode-supported": "^0.1.0" } }, "sha512-8XPvpAA8uyhfteu8pIvQxpJZ7SYYdpUivZpGy6sFsBuKRY/7rQGavedeB8aK+Zkyq6upMFVL/9AW6vOYzfRyLg=="],
-
     "lowercase-keys": ["lowercase-keys@2.0.0", "", {}, "sha512-tqNXrS78oMOE73NMxK4EMLQsQowWf8jKooH9g7xPavRT706R6bkQJ6DY2Te7QukaZsulxa30wQ7bk0pm4XiHmA=="],
 
     "lru-cache": ["lru-cache@6.0.0", "", { "dependencies": { "yallist": "^4.0.0" } }, "sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA=="],
 
     "magic-bytes.js": ["magic-bytes.js@1.13.0", "", {}, "sha512-afO2mnxW7GDTXMm5/AoN1WuOcdoKhtgXjIvHmobqTD1grNplhGdv3PFOyjCVmrnOZBIT/gD/koDKpYG+0mvHcg=="],
 
-    "make-fetch-happen": ["make-fetch-happen@14.0.3", "", { "dependencies": { "@npmcli/agent": "^3.0.0", "cacache": "^19.0.1", "http-cache-semantics": "^4.1.1", "minipass": "^7.0.2", "minipass-fetch": "^4.0.0", "minipass-flush": "^1.0.5", "minipass-pipeline": "^1.2.4", "negotiator": "^1.0.0", "proc-log": "^5.0.0", "promise-retry": "^2.0.1", "ssri": "^12.0.0" } }, "sha512-QMjGbFTP0blj97EeidG5hk/QhKQ3T4ICckQGLgz38QF7Vgbk6e6FTARN8KhKxyBbWn8R0HU+bnw8aSoFPD4qtQ=="],
-
     "matcher": ["matcher@3.0.0", "", { "dependencies": { "escape-string-regexp": "^4.0.0" } }, "sha512-OkeDaAZ/bQCxeFAozM55PKcKU0yJMPGifLwV4Qgjitu+5MoAfSQN4lsLJeXZ1b8w0x+/Emda6MZgXS1jvsapng=="],
 
     "math-intrinsics": ["math-intrinsics@1.1.0", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
@@ -591,26 +549,14 @@
 
     "mime-types": ["mime-types@2.1.35", "", { "dependencies": { "mime-db": "1.52.0" } }, "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw=="],
 
-    "mimic-fn": ["mimic-fn@2.1.0", "", {}, "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg=="],
-
     "mimic-response": ["mimic-response@3.1.0", "", {}, "sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ=="],
 
-    "minimatch": ["minimatch@10.2.3", "", { "dependencies": { "brace-expansion": "^5.0.2" } }, "sha512-Rwi3pnapEqirPSbWbrZaa6N3nmqq4Xer/2XooiOKyV3q12ML06f7MOuc5DVH8ONZIFhwIYQ3yzPH4nt7iWHaTg=="],
+    "minimatch": ["minimatch@10.2.5", "", { "dependencies": { "brace-expansion": "^5.0.5" } }, "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg=="],
 
     "minimist": ["minimist@1.2.8", "", {}, "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA=="],
 
     "minipass": ["minipass@7.1.3", "", {}, "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A=="],
 
-    "minipass-collect": ["minipass-collect@2.0.1", "", { "dependencies": { "minipass": "^7.0.3" } }, "sha512-D7V8PO9oaz7PWGLbCACuI1qEOsq7UKfLotx/C0Aet43fCUB/wfQ7DYeq2oR/svFJGYDHPr38SHATeaj/ZoKHKw=="],
-
-    "minipass-fetch": ["minipass-fetch@4.0.1", "", { "dependencies": { "minipass": "^7.0.3", "minipass-sized": "^1.0.3", "minizlib": "^3.0.1" }, "optionalDependencies": { "encoding": "^0.1.13" } }, "sha512-j7U11C5HXigVuutxebFadoYBbd7VSdZWggSe64NVdvWNBqGAiXPL2QVCehjmw7lY1oF9gOllYbORh+hiNgfPgQ=="],
-
-    "minipass-flush": ["minipass-flush@1.0.5", "", { "dependencies": { "minipass": "^3.0.0" } }, "sha512-JmQSYYpPUqX5Jyn1mXaRwOda1uQ8HP5KAT/oDSLCzt1BYRhQU0/hDtsB1ufZfEEzMZ9aAVmsBw8+FWsIXlClWw=="],
-
-    "minipass-pipeline": ["minipass-pipeline@1.2.4", "", { "dependencies": { "minipass": "^3.0.0" } }, "sha512-xuIq7cIOt09RPRJ19gdi4b+RiNvDFYe5JH+ggNvBqGqpQXcru3PcRmOZuHBKWK1Txf9+cQ+HMVN4d6z46LZP7A=="],
-
-    "minipass-sized": ["minipass-sized@1.0.3", "", { "dependencies": { "minipass": "^3.0.0" } }, "sha512-MbkQQ2CTiBMlA2Dm/5cY+9SWFEN8pzzOXi6rlM5Xxq0Yqbda5ZQy9sU75a673FE9ZK0Zsbr6Y5iP6u9nktfg2g=="],
-
     "minizlib": ["minizlib@3.1.0", "", { "dependencies": { "minipass": "^7.1.2" } }, "sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw=="],
 
     "mkdirp": ["mkdirp@0.5.6", "", { "dependencies": { "minimist": "^1.2.6" }, "bin": { "mkdirp": "bin/cmd.js" } }, "sha512-FP+p8RB8OWpF3YZBCrP5gtADmtXApB5AMLn+vdyA+PyxCjrCs00mjyUozssO33cwDeT3wNGdLxJ5M//YqtHAJw=="],
@@ -619,17 +565,15 @@
 
     "natural-compare": ["natural-compare@1.4.0", "", {}, "sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw=="],
 
-    "negotiator": ["negotiator@1.0.0", "", {}, "sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg=="],
-
     "node-abi": ["node-abi@4.28.0", "", { "dependencies": { "semver": "^7.6.3" } }, "sha512-Qfp5XZL1cJDOabOT8H5gnqMTmM4NjvYzHp4I/Kt/Sl76OVkOBBHRFlPspGV0hYvMoqQsypFjT/Yp7Km0beXW9g=="],
 
-    "node-addon-api": ["node-addon-api@1.7.2", "", {}, "sha512-ibPK3iA+vaY1eEjESkQkM0BbCqFOaZMiXRTtdB0u7b4djtY6JnsjvPdUHVMg6xQt3B8fpTTWHI9A+ADjM9frzg=="],
-
     "node-api-version": ["node-api-version@0.2.1", "", { "dependencies": { "semver": "^7.3.5" } }, "sha512-2xP/IGGMmmSQpI1+O/k72jF/ykvZ89JeuKX3TLJAYPDVLUalrshrLHkeVcCCZqG/eEa635cr8IBYzgnDvM2O8Q=="],
 
-    "node-gyp": ["node-gyp@11.5.0", "", { "dependencies": { "env-paths": "^2.2.0", "exponential-backoff": "^3.1.1", "graceful-fs": "^4.2.6", "make-fetch-happen": "^14.0.3", "nopt": "^8.0.0", "proc-log": "^5.0.0", "semver": "^7.3.5", "tar": "^7.4.3", "tinyglobby": "^0.2.12", "which": "^5.0.0" }, "bin": { "node-gyp": "bin/node-gyp.js" } }, "sha512-ra7Kvlhxn5V9Slyus0ygMa2h+UqExPqUIkfk7Pc8QTLT956JLSy51uWFwHtIYy0vI8cB4BDhc/S03+880My/LQ=="],
+    "node-gyp": ["node-gyp@12.4.0", "", { "dependencies": { "env-paths": "^2.2.0", "exponential-backoff": "^3.1.1", "graceful-fs": "^4.2.6", "nopt": "^9.0.0", "proc-log": "^6.0.0", "semver": "^7.3.5", "tar": "^7.5.4", "tinyglobby": "^0.2.12", "undici": "^6.25.0", "which": "^6.0.0" }, "bin": { "node-gyp": "bin/node-gyp.js" } }, "sha512-OMcPNvqTCFUnNaBlmdgq+lfNqY7gTiSmNRDjY3uAXRyudeKZEZxu3CLtjMQrx4zZxCX2b/mpNqTtwuCJgXhHkw=="],
 
-    "nopt": ["nopt@8.1.0", "", { "dependencies": { "abbrev": "^3.0.0" }, "bin": { "nopt": "bin/nopt.js" } }, "sha512-ieGu42u/Qsa4TFktmaKEwM6MQH0pOWnaB3htzh0JRtx84+Mebc0cbZYN5bC+6WTZ4+77xrL9Pn5m7CV6VIkV7A=="],
+    "node-int64": ["node-int64@0.4.0", "", {}, "sha512-O5lz91xSOeoXP6DulyHfllpq+Eg00MWitZIbtPfoSEvqIHdl5gfcY6hYzDWnj0qD5tz52PI08u9qUvSVeUBeHw=="],
+
+    "nopt": ["nopt@9.0.0", "", { "dependencies": { "abbrev": "^4.0.0" }, "bin": { "nopt": "bin/nopt.js" } }, "sha512-Zhq3a+yFKrYwSBluL4H9XP3m3y5uvQkB/09CwDruCiRmR/UJYnn9W4R48ry0uGC70aeTPKLynBtscP9efFFcPw=="],
 
     "normalize-url": ["normalize-url@6.1.0", "", {}, "sha512-DlL+XwOy3NxAQ8xuC0okPgK46iuVNAK01YN7RueYBqqFeGsBjV9XmCAzAdgt+667bCl5kPh9EqKKDwnaPG1I7A=="],
 
@@ -637,38 +581,28 @@
 
     "once": ["once@1.4.0", "", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="],
 
-    "onetime": ["onetime@5.1.2", "", { "dependencies": { "mimic-fn": "^2.1.0" } }, "sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg=="],
-
     "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=="],
 
-    "ora": ["ora@5.4.1", "", { "dependencies": { "bl": "^4.1.0", "chalk": "^4.1.0", "cli-cursor": "^3.1.0", "cli-spinners": "^2.5.0", "is-interactive": "^1.0.0", "is-unicode-supported": "^0.1.0", "log-symbols": "^4.1.0", "strip-ansi": "^6.0.0", "wcwidth": "^1.0.1" } }, "sha512-5b6Y85tPxZZ7QytO+BQzysW31HJku27cRIlkbAXaNx+BdcVi+LlRFmVXzeF6a7JCwJpyw5c4b+YSVImQIrBpuQ=="],
-
     "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=="],
 
-    "p-map": ["p-map@7.0.4", "", {}, "sha512-tkAQEw8ysMzmkhgw8k+1U/iPhWNhykKnSk4Rd5zLoPJCuJaGRPo6YposrZgaxHKzDHdDWWZvE/Sk7hsL2X/CpQ=="],
-
-    "package-json-from-dist": ["package-json-from-dist@1.0.1", "", {}, "sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw=="],
-
     "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=="],
 
-    "path-scurry": ["path-scurry@1.11.1", "", { "dependencies": { "lru-cache": "^10.2.0", "minipass": "^5.0.0 || ^6.0.2 || ^7.0.0" } }, "sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA=="],
-
     "pe-library": ["pe-library@0.4.1", "", {}, "sha512-eRWB5LBz7PpDu4PUlwT0PhnQfTQJlDDdPa35urV4Osrm0t0AqQFGn+UIkU3klZvwJ8KPO3VbBFsXquA6p6kqZw=="],
 
-    "pend": ["pend@1.2.0", "", {}, "sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg=="],
-
     "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
 
     "picomatch": ["picomatch@4.0.4", "", {}, "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A=="],
 
+    "pkijs": ["pkijs@3.4.0", "", { "dependencies": { "@noble/hashes": "1.4.0", "asn1js": "^3.0.6", "bytestreamjs": "^2.0.1", "pvtsutils": "^1.3.6", "pvutils": "^1.1.3", "tslib": "^2.8.1" } }, "sha512-emEcLuomt2j03vxD54giVB4SxTjnsqkU692xZOZXHDVoYyypEm+b3jpiTcc+Cf+myooc+/Ly0z01jqeNHVgJGw=="],
+
     "plist": ["plist@3.1.0", "", { "dependencies": { "@xmldom/xmldom": "^0.8.8", "base64-js": "^1.5.1", "xmlbuilder": "^15.1.1" } }, "sha512-uysumyrvkUX0rX/dEVqt8gC3sTBzd4zoWfLeS29nb53imdaXVvLINYXTI2GNqzaMuvacNx4uJQ8+b3zXR0pkgQ=="],
 
     "postject": ["postject@1.0.0-alpha.6", "", { "dependencies": { "commander": "^9.4.0" }, "bin": { "postject": "dist/cli.js" } }, "sha512-b9Eb8h2eVqNE8edvKdwqkrY6O7kAwmI8kcnBv1NScolYJbo59XUF0noFq+lxbC1yN20bmC0WBEbDC5H/7ASb0A=="],
@@ -677,7 +611,9 @@
 
     "prettier": ["prettier@3.8.1", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg=="],
 
-    "proc-log": ["proc-log@5.0.0", "", {}, "sha512-Azwzvl90HaF0aCz1JrDdXQykFakSSNPaPoiZ9fm5qJIMHioDZEi7OAdRwSm6rSoPtY3Qutnm3L7ogmg3dc+wbQ=="],
+    "proc-log": ["proc-log@6.1.0", "", {}, "sha512-iG+GYldRf2BQ0UDUAd6JQ/RwzaQy6mXmsk/IzlYyal4A4SNFw54MeH4/tLkF4I5WoWG9SQwuqWzS99jaFQHBuQ=="],
+
+    "process-nextick-args": ["process-nextick-args@2.0.1", "", {}, "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag=="],
 
     "progress": ["progress@2.0.3", "", {}, "sha512-7PiHtLll5LdnKIMw100I+8xJXR5gW2QwWYkT6iJva0bXitZKa/XMrSbdmg3r2Xnaidz9Qumd0VPaMrZlF9V9sA=="],
 
@@ -685,37 +621,39 @@
 
     "proper-lockfile": ["proper-lockfile@4.1.2", "", { "dependencies": { "graceful-fs": "^4.2.4", "retry": "^0.12.0", "signal-exit": "^3.0.2" } }, "sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA=="],
 
-    "proxy-from-env": ["proxy-from-env@1.1.0", "", {}, "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg=="],
+    "proxy-from-env": ["proxy-from-env@2.1.0", "", {}, "sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA=="],
 
     "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=="],
+
     "quick-lru": ["quick-lru@5.1.1", "", {}, "sha512-WuyALRjWPDGtt/wzJiadO5AXY+8hZ80hVpe6MyivgraREW751X3SbhRvG3eLKOYN+8VEvqLcf3wdnt44Z4S4SA=="],
 
     "read-binary-file-arch": ["read-binary-file-arch@1.0.6", "", { "dependencies": { "debug": "^4.3.4" }, "bin": { "read-binary-file-arch": "cli.js" } }, "sha512-BNg9EN3DD3GsDXX7Aa8O4p92sryjkmzYYgmgTAc6CA4uGLEDzFfxOxugu21akOxpcXHiEgsYkC6nPsQvLLLmEg=="],
 
-    "readable-stream": ["readable-stream@3.6.2", "", { "dependencies": { "inherits": "^2.0.3", "string_decoder": "^1.1.1", "util-deprecate": "^1.0.1" } }, "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA=="],
+    "readable-stream": ["readable-stream@2.3.8", "", { "dependencies": { "core-util-is": "~1.0.0", "inherits": "~2.0.3", "isarray": "~1.0.0", "process-nextick-args": "~2.0.0", "safe-buffer": "~5.1.1", "string_decoder": "~1.1.1", "util-deprecate": "~1.0.1" } }, "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA=="],
 
     "require-directory": ["require-directory@2.1.1", "", {}, "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q=="],
 
+    "require-from-string": ["require-from-string@2.0.2", "", {}, "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw=="],
+
     "resedit": ["resedit@1.7.2", "", { "dependencies": { "pe-library": "^0.4.1" } }, "sha512-vHjcY2MlAITJhC0eRD/Vv8Vlgmu9Sd3LX9zZvtGzU5ZImdTN3+d6e/4mnTyV8vEbyf1sgNIrWxhWlrys52OkEA=="],
 
     "resolve-alpn": ["resolve-alpn@1.2.1", "", {}, "sha512-0a1F4l73/ZFZOakJnQ3FvkJ2+gSTQWz/r2KE5OdDY0TxPm5h4GkqkWWfM47T7HsbnOtcJVEF4epCVy6u7Q3K+g=="],
 
     "responselike": ["responselike@2.0.1", "", { "dependencies": { "lowercase-keys": "^2.0.0" } }, "sha512-4gl03wn3hj1HP3yzgdI7d3lCkF95F21Pz4BPGvKHinyQzALR5CapwC8yIi0Rh58DEMQ/SguC03wFj2k0M/mHhw=="],
 
-    "restore-cursor": ["restore-cursor@3.1.0", "", { "dependencies": { "onetime": "^5.1.0", "signal-exit": "^3.0.2" } }, "sha512-l+sSefzHpj5qimhFSE5a8nufZYAM3sBSVMAPtYkmC+4EH2anSGaEMXSD0izRQbu9nfyQ9y5JrVmp7E8oZrUjvA=="],
-
     "retry": ["retry@0.12.0", "", {}, "sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow=="],
 
     "rimraf": ["rimraf@2.6.3", "", { "dependencies": { "glob": "^7.1.3" }, "bin": { "rimraf": "./bin.js" } }, "sha512-mwqeW5XsA2qAejG46gYdENaxXjx9onRNCfn7L0duuP4hCuTIi/QO7PDK07KJfp1d+izWPrzEJDcSqBa0OZQriA=="],
 
     "roarr": ["roarr@2.15.4", "", { "dependencies": { "boolean": "^3.0.1", "detect-node": "^2.0.4", "globalthis": "^1.0.1", "json-stringify-safe": "^5.0.1", "semver-compare": "^1.0.0", "sprintf-js": "^1.1.2" } }, "sha512-CHhPh+UNHD2GTXNYhPWLnU8ONHdI+5DI+4EYIAOaiD63rHeYlZvyh8P+in5999TTSFgUYuKUAjzRI4mdh/p+2A=="],
 
-    "safe-buffer": ["safe-buffer@5.2.1", "", {}, "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ=="],
-
-    "safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
+    "safe-buffer": ["safe-buffer@5.1.2", "", {}, "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g=="],
 
     "sanitize-filename": ["sanitize-filename@1.6.4", "", { "dependencies": { "truncate-utf8-bytes": "^1.0.0" } }, "sha512-9ZyI08PsvdQl2r/bBIGubpVdR3RR9sY6RDiWFPreA21C/EFlQhmgo20UZlNjZMMZNubusLhAQozkA0Od5J21Eg=="],
 
@@ -735,39 +673,25 @@
 
     "simple-update-notifier": ["simple-update-notifier@2.0.0", "", { "dependencies": { "semver": "^7.5.3" } }, "sha512-a2B9Y0KlNXl9u/vsW6sTIu9vGEpfKu2wRV6l1H3XEas/0gUIzGzBoP/IouTcUQbm9JWZLH3COxyn03TYlFax6w=="],
 
-    "slice-ansi": ["slice-ansi@3.0.0", "", { "dependencies": { "ansi-styles": "^4.0.0", "astral-regex": "^2.0.0", "is-fullwidth-code-point": "^3.0.0" } }, "sha512-pSyv7bSTC7ig9Dcgbw9AuRNUb5k5V6oDudjZoMBSr13qpLBG7tB+zgCkARjq7xIUgdz5P1Qe8u+rSGdouOOIyQ=="],
-
-    "smart-buffer": ["smart-buffer@4.2.0", "", {}, "sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg=="],
-
-    "socks": ["socks@2.8.7", "", { "dependencies": { "ip-address": "^10.0.1", "smart-buffer": "^4.2.0" } }, "sha512-HLpt+uLy/pxB+bum/9DzAgiKS8CX1EvbWxI4zlmgGCExImLdiad2iCwXT5Z4c9c3Eq8rP2318mPW2c+QbtjK8A=="],
-
-    "socks-proxy-agent": ["socks-proxy-agent@8.0.5", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "^4.3.4", "socks": "^2.8.3" } }, "sha512-HehCEsotFqbPW9sJ8WVYB6UbmIMv7kUUORIF2Nncq4VQvBfNBLibW9YZR5dlYCSUhwcD628pRllm7n+E+YTzJw=="],
-
     "source-map": ["source-map@0.6.1", "", {}, "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g=="],
 
     "source-map-support": ["source-map-support@0.5.21", "", { "dependencies": { "buffer-from": "^1.0.0", "source-map": "^0.6.0" } }, "sha512-uBHU3L3czsIyYXKX88fdrGovxdSCoTGDRZ6SYXtSRxLZUzHg5P/66Ht6uoUlHu9EZod+inXhKo3qQgwXUT/y1w=="],
 
     "sprintf-js": ["sprintf-js@1.1.3", "", {}, "sha512-Oo+0REFV59/rz3gfJNKQiBlwfHaSESl1pcGyABQsnnIfWOFt6JNj5gCog2U6MLZ//IGYD+nA8nI+mTShREReaA=="],
 
-    "ssri": ["ssri@12.0.0", "", { "dependencies": { "minipass": "^7.0.3" } }, "sha512-S7iGNosepx9RadX82oimUkvr0Ct7IjJbEbs4mJcTxst8um95J3sDYU1RBEOvdu6oL1Wek2ODI5i4MAw+dZ6cAQ=="],
-
     "stat-mode": ["stat-mode@1.0.0", "", {}, "sha512-jH9EhtKIjuXZ2cWxmXS8ZP80XyC3iasQxMDV8jzhNJpfDb7VbQLVW4Wvsxz9QZvzV+G4YoSfBUVKDOyxLzi/sg=="],
 
     "string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
 
-    "string-width-cjs": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
-
-    "string_decoder": ["string_decoder@1.3.0", "", { "dependencies": { "safe-buffer": "~5.2.0" } }, "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA=="],
+    "string_decoder": ["string_decoder@1.1.1", "", { "dependencies": { "safe-buffer": "~5.1.0" } }, "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg=="],
 
     "strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
 
-    "strip-ansi-cjs": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
-
     "sumchecker": ["sumchecker@3.0.1", "", { "dependencies": { "debug": "^4.1.0" } }, "sha512-MvjXzkz/BOfyVDkG0oFOtBxHX2u3gKbMHIF/dXblZsgD3BWOFLmHovIpZY7BykJdAjcqRCBi1WYBNdEC9yI7vg=="],
 
     "supports-color": ["supports-color@7.2.0", "", { "dependencies": { "has-flag": "^4.0.0" } }, "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw=="],
 
-    "tar": ["tar@7.5.11", "", { "dependencies": { "@isaacs/fs-minipass": "^4.0.0", "chownr": "^3.0.0", "minipass": "^7.1.2", "minizlib": "^3.1.0", "yallist": "^5.0.0" } }, "sha512-ChjMH33/KetonMTAtpYdgUFr0tbz69Fp2v7zWxQfYZX4g5ZN2nOBXm1R2xyA+lMIKrLKIoKAwFj93jE/avX9cQ=="],
+    "tar": ["tar@7.5.21", "", { "dependencies": { "@isaacs/fs-minipass": "^4.0.0", "chownr": "^3.0.0", "minipass": "^7.1.2", "minizlib": "^3.1.0", "yallist": "^5.0.0" } }, "sha512-XdhtCvlMywwxpCW8YEq3lOXBJpUPTR2OHHcwLPO3HwsJqOHa2Ok/oJ7ruGzp+JrKoRPVCzJwAdEjqLW/vNRPHA=="],
 
     "temp": ["temp@0.9.4", "", { "dependencies": { "mkdirp": "^0.5.1", "rimraf": "~2.6.2" } }, "sha512-yYrrsWnrXMcdsnu/7YMYAofM1ktpL5By7vZhf15CrXijWWrEYZks5AXBudalfSWJLlnen/QUJUB5aoB0kqZUGA=="],
 
@@ -779,7 +703,7 @@
 
     "tinyglobby": ["tinyglobby@0.2.15", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.3" } }, "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ=="],
 
-    "tmp": ["tmp@0.2.5", "", {}, "sha512-voyz6MApa1rQGUxT3E+BK7/ROe8itEx7vD8/HEvt4xwXucvQ5G5oeEiHkmHZJuBO21RpOf+YYm9MOivj709jow=="],
+    "tmp": ["tmp@0.2.7", "", {}, "sha512-e0votIpp4Uo2AJYSzVHV6xCcawuiez3DzqDAbrTc3YxBkplN6e+dM13ZeIcZnDg/QpSuU2zfZ3rzwY8ukEnaXw=="],
 
     "tmp-promise": ["tmp-promise@3.0.3", "", { "dependencies": { "tmp": "^0.2.0" } }, "sha512-RwM7MoPojPxsOBYnyd2hy0bxtIlVrihNs9pj5SUvY8Zz1sQcQG2tG1hSr8PDxfgEB8RNKDhqbIlroIarSNDNsQ=="],
 
@@ -793,25 +717,21 @@
 
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
-    "undici": ["undici@7.25.0", "", {}, "sha512-xXnp4kTyor2Zq+J1FfPI6Eq3ew5h6Vl0F/8d9XU5zZQf1tX9s2Su1/3PiMmUANFULpmksxkClamIZcaUqryHsQ=="],
+    "undici": ["undici@7.29.1", "", {}, "sha512-RYONW2MeafgYlkVOKYKkA/Ag7BmXqgIWCa8t1m0JcxrQg9pI9lEqRhAOruOBCbAohOa/gkCF+iPi9hrgvTzu6Q=="],
 
     "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
 
-    "unique-filename": ["unique-filename@4.0.0", "", { "dependencies": { "unique-slug": "^5.0.0" } }, "sha512-XSnEewXmQ+veP7xX2dS5Q4yZAvO40cBN2MWkJ7D/6sW4Dg6wYBNwM1Vrnz1FhH5AdeLIlUXRI9e28z1YZi71NQ=="],
-
-    "unique-slug": ["unique-slug@5.0.0", "", { "dependencies": { "imurmurhash": "^0.1.4" } }, "sha512-9OdaqO5kwqR+1kVgHAhsp5vPNU0hnxRa26rBFNfNgM7M6pNtgzeBn3s/xbyCQL3dcjzOatcef6UUHpB/6MaETg=="],
-
     "universalify": ["universalify@2.0.1", "", {}, "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw=="],
 
+    "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=="],
 
-    "verror": ["verror@1.10.1", "", { "dependencies": { "assert-plus": "^1.0.0", "core-util-is": "1.0.2", "extsprintf": "^1.2.0" } }, "sha512-veufcmxri4e3XSrT0xwfUR7kguIkaxBeosDg00yDWhk49wdwkSUrvvsm7nc75e1PUyvIeZj6nS8VQRYz2/S4Xg=="],
-
-    "wcwidth": ["wcwidth@1.0.1", "", { "dependencies": { "defaults": "^1.0.3" } }, "sha512-XHPEwS0q6TaxcvG85+8EYkbiCux2XtWG2mkc47Ng2A77BQu9+DqIOJldST4HgPkuea7dvKSj5VgX3P1d4rW8Tg=="],
+    "webcrypto-core": ["webcrypto-core@1.9.2", "", { "dependencies": { "@peculiar/asn1-schema": "^2.7.0", "@peculiar/json-schema": "^1.1.12", "@peculiar/utils": "^2.0.2", "asn1js": "^3.0.10", "tslib": "^2.8.1" } }, "sha512-gsXecm82UQNlTBURJGuqOWy1Ww08S3kZUcr3aOJS02Pk0xLtkfeUAVC0u0xhgdonFme80edSJUIJyuvL/7250Q=="],
 
     "which": ["which@5.0.0", "", { "dependencies": { "isexe": "^3.1.1" }, "bin": { "node-which": "bin/which.js" } }, "sha512-JEdGzHwwkrbWoGOlIHqQ5gtprKGOenpDHpxE9zVR1bWbOtYRyPPHMe9FaP6x61CmNaTThSkb0DAJte5jD+DmzQ=="],
 
@@ -819,11 +739,9 @@
 
     "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=="],
 
-    "wrap-ansi-cjs": ["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=="],
 
-    "ws": ["ws@8.20.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA=="],
+    "ws": ["ws@8.21.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g=="],
 
     "xmlbuilder": ["xmlbuilder@15.1.1", "", {}, "sha512-yMqGBqtXyeN1e3TGYvgNgDVZ3j84W4cwkOXQswghol6APgZWaff9lnbvN7MHYJOiXsvGPXtjTYJEiC9J2wv9Eg=="],
 
@@ -835,11 +753,11 @@
 
     "yargs-parser": ["yargs-parser@21.1.1", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="],
 
-    "yauzl": ["yauzl@2.10.0", "", { "dependencies": { "buffer-crc32": "~0.2.3", "fd-slicer": "~1.1.0" } }, "sha512-p4a9I6X6nu6IhoGmBqAcbJy1mlC4j27vEPZX9F4L4/vZT3Lyq1VkFHw/V/PUcB9Buo+DG3iHkT0x3Qya58zc3g=="],
-
     "yocto-queue": ["yocto-queue@0.1.0", "", {}, "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q=="],
 
-    "@discordjs/rest/undici": ["undici@6.24.1", "", {}, "sha512-sC+b0tB1whOCzbtlx20fx3WgCXwkW627p4EA9uM+/tNNPkSS+eSEld6pAs9nDv7WbY1UUljBMYPtu9BCOrCWKA=="],
+    "@discordjs/rest/discord-api-types": ["discord-api-types@0.38.43", "", {}, "sha512-sSoBf/nK6m7BGtw65mi+QBuvEWaHE8MMziFLqWL+gT6ME/BLg34dRSVKS3Husx40uU06bvxUc3/X+D9Y6/zAbw=="],
+
+    "@discordjs/util/discord-api-types": ["discord-api-types@0.38.43", "", {}, "sha512-sSoBf/nK6m7BGtw65mi+QBuvEWaHE8MMziFLqWL+gT6ME/BLg34dRSVKS3Husx40uU06bvxUc3/X+D9Y6/zAbw=="],
 
     "@electron/asar/commander": ["commander@5.1.0", "", {}, "sha512-P0CysNDQ7rtVw4QIQtm+MRxV66vKFSvlsQvGYXZWR3qFU0jlMKHZZZgw8e+8DSah4UDKMqnknRDQz+xuQXQ/Zg=="],
 
@@ -855,37 +773,25 @@
 
     "@eslint-community/eslint-utils/eslint-visitor-keys": ["eslint-visitor-keys@3.4.3", "", {}, "sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag=="],
 
-    "@isaacs/cliui/string-width": ["string-width@5.1.2", "", { "dependencies": { "eastasianwidth": "^0.2.0", "emoji-regex": "^9.2.2", "strip-ansi": "^7.0.1" } }, "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA=="],
-
-    "@isaacs/cliui/strip-ansi": ["strip-ansi@7.2.0", "", { "dependencies": { "ansi-regex": "^6.2.2" } }, "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w=="],
-
-    "@isaacs/cliui/wrap-ansi": ["wrap-ansi@8.1.0", "", { "dependencies": { "ansi-styles": "^6.1.0", "string-width": "^5.0.1", "strip-ansi": "^7.0.1" } }, "sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ=="],
-
     "@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=="],
 
-    "@npmcli/agent/lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="],
-
     "@types/cacheable-request/@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
 
     "@types/fs-extra/@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
 
     "@types/keyv/@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
 
-    "@types/plist/@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
-
     "@types/responselike/@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
 
     "@types/ws/@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
 
-    "@types/yauzl/@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
-
     "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=="],
 
-    "cacache/glob": ["glob@10.5.0", "", { "dependencies": { "foreground-child": "^3.1.0", "jackspeak": "^3.1.2", "minimatch": "^9.0.4", "minipass": "^7.1.2", "package-json-from-dist": "^1.0.0", "path-scurry": "^1.11.1" }, "bin": { "glob": "dist/esm/bin.mjs" } }, "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg=="],
-
-    "cacache/lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="],
+    "builder-util/https-proxy-agent": ["https-proxy-agent@7.0.6", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "4" } }, "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw=="],
 
     "clone-response/mimic-response": ["mimic-response@1.0.1", "", {}, "sha512-j5EctnkH7amfV/q5Hgmoal1g2QHFJRraOtmx0JpIqkxhBhI/lJSl1nMpQ45hVarwNETOoWEimndZ4QK0RHxuxQ=="],
 
@@ -893,29 +799,25 @@
 
     "electron-winstaller/fs-extra": ["fs-extra@7.0.1", "", { "dependencies": { "graceful-fs": "^4.1.2", "jsonfile": "^4.0.0", "universalify": "^0.1.0" } }, "sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw=="],
 
-    "foreground-child/signal-exit": ["signal-exit@4.1.0", "", {}, "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw=="],
+    "es-set-tostringtag/hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
+
+    "get-intrinsic/hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
+
+    "http-proxy-agent/agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
 
     "lru-cache/yallist": ["yallist@4.0.0", "", {}, "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A=="],
 
-    "minipass-flush/minipass": ["minipass@3.3.6", "", { "dependencies": { "yallist": "^4.0.0" } }, "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw=="],
-
-    "minipass-pipeline/minipass": ["minipass@3.3.6", "", { "dependencies": { "yallist": "^4.0.0" } }, "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw=="],
-
-    "minipass-sized/minipass": ["minipass@3.3.6", "", { "dependencies": { "yallist": "^4.0.0" } }, "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw=="],
-
     "node-gyp/env-paths": ["env-paths@2.2.1", "", {}, "sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A=="],
 
-    "path-scurry/lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="],
+    "node-gyp/which": ["which@6.0.1", "", { "dependencies": { "isexe": "^4.0.0" }, "bin": { "node-which": "bin/which.js" } }, "sha512-oGLe46MIrCRqX7ytPUf66EAYvdeMIZYn3WaocqqKZAxrBpkqHfL/qvTyJ/bTk5+AqHCjXmrv3CEWgy368zhRUg=="],
+
+    "pkijs/@noble/hashes": ["@noble/hashes@1.4.0", "", {}, "sha512-V1JJ1WTRUqHHrOSh597hURcMqVKVGL/ea3kv0gSnEdsEZ0/+VyPghM1lMNGc00z7CIQorSvbKpuJkxvuHbvdbg=="],
 
     "postject/commander": ["commander@9.5.0", "", {}, "sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ=="],
 
     "tiny-async-pool/semver": ["semver@5.7.2", "", { "bin": { "semver": "bin/semver" } }, "sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g=="],
 
-    "@isaacs/cliui/string-width/emoji-regex": ["emoji-regex@9.2.2", "", {}, "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg=="],
-
-    "@isaacs/cliui/strip-ansi/ansi-regex": ["ansi-regex@6.2.2", "", {}, "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg=="],
-
-    "@isaacs/cliui/wrap-ansi/ansi-styles": ["ansi-styles@6.2.3", "", {}, "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg=="],
+    "unzipper/fs-extra": ["fs-extra@11.3.1", "", { "dependencies": { "graceful-fs": "^4.2.0", "jsonfile": "^6.0.1", "universalify": "^2.0.0" } }, "sha512-eXvGGwZ5CL17ZSwHWd3bbgk7UUpF6IFHtP57NYYakPvHOs8GDgDe5KJI36jIJzDkJ6eJjuzRA8eBQb6SkKue0g=="],
 
     "@types/cacheable-request/@types/node/undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
 
@@ -923,31 +825,27 @@
 
     "@types/keyv/@types/node/undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
 
-    "@types/plist/@types/node/undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
-
     "@types/responselike/@types/node/undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
 
     "@types/ws/@types/node/undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
 
-    "@types/yauzl/@types/node/undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
-
     "app-builder-lib/@electron/get/env-paths": ["env-paths@2.2.1", "", {}, "sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A=="],
 
     "app-builder-lib/@electron/get/fs-extra": ["fs-extra@8.1.0", "", { "dependencies": { "graceful-fs": "^4.2.0", "jsonfile": "^4.0.0", "universalify": "^0.1.0" } }, "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g=="],
 
     "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=="],
 
     "electron-winstaller/fs-extra/jsonfile": ["jsonfile@4.0.0", "", { "optionalDependencies": { "graceful-fs": "^4.1.6" } }, "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg=="],
 
     "electron-winstaller/fs-extra/universalify": ["universalify@0.1.2", "", {}, "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg=="],
 
-    "minipass-flush/minipass/yallist": ["yallist@4.0.0", "", {}, "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A=="],
-
-    "minipass-pipeline/minipass/yallist": ["yallist@4.0.0", "", {}, "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A=="],
-
-    "minipass-sized/minipass/yallist": ["yallist@4.0.0", "", {}, "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A=="],
+    "node-gyp/which/isexe": ["isexe@4.0.0", "", {}, "sha512-FFUtZMpoZ8RqHS3XeXEmHWLA4thH+ZxCv2lOiPIn1Xc7CxrqhWzNSDzD+/chS/zbYezmiwWLdQC09JdQKmthOw=="],
 
     "app-builder-lib/@electron/get/fs-extra/jsonfile": ["jsonfile@4.0.0", "", { "optionalDependencies": { "graceful-fs": "^4.1.6" } }, "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg=="],
 

changes/README.md

@@ -42,13 +42,14 @@ 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.
-- GitHub release notes and prerelease notes use short top-level items with nested bullets for the change, user benefit, and any useful action note. The stable `CHANGELOG.md` can stay in compact single-line bullets.
+- `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.
 - `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.
 
 Prerelease notes:
 
 - prerelease tags like `v0.11.3-beta.1` and `v0.11.3-rc.1` reuse the current pending fragments to generate `release/prerelease-notes.md`
+- from the second prerelease of a base version onward, the notes also open with a `## Changes since <previous tag>` section generated from the fragment diff against the previous beta/RC tag; keep fragment edits meaningful. Editorial-only rewording is filtered out of that section, while genuinely changed behavior and deleted fragments (reverted changes) are reported
 - existing prerelease notes are a reviewed baseline; later prerelease runs should replace stale beta/RC wording with the current outcome instead of appending fix churn
 - prerelease note generation does not consume fragments and does not update `CHANGELOG.md` or `docs-site/changelog.md`
 - the final stable release is the point where `bun run changelog:build` consumes fragments into the stable changelog and release notes

config.example.jsonc

@@ -6,6 +6,32 @@
  */
 {
 
+  // ==========================================
+  // 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.
+  // Configure an existing GGML model path or explicitly download a SubMiner-managed model.
+  // Hot-reload: settings apply to the next generation or model download.
+  // ==========================================
+  "subtitleGeneration": {
+    "whisperPath": "", // Optional path override for whisper.cpp. Leave empty to find whisper-cli on PATH.
+    "modelPath": "", // Path to an existing multilingual whisper.cpp GGML model. Leave empty to use a SubMiner-managed model. A configured path always takes precedence.
+    "managedModel": "small", // Multilingual whisper.cpp model to use when modelPath is empty. Download it explicitly from the generation modal or launcher. Values: tiny | tiny-q5_1 | tiny-q8_0 | base | base-q5_1 | base-q8_0 | small | small-q5_1 | small-q8_0 | medium | medium-q5_0 | medium-q8_0 | large-v1 | large-v2 | large-v2-q5_0 | large-v2-q8_0 | large-v3 | large-v3-q5_0 | large-v3-turbo | large-v3-turbo-q5_0 | large-v3-turbo-q8_0
+    "threads": 4, // Positive integer CPU thread count for whisper.cpp Japanese transcription.
+    "ffmpegPath": "", // Optional FFmpeg path override for audio extraction. Leave empty to find ffmpeg on PATH.
+    "ffprobePath": "", // Optional FFprobe path override for audio tracks and timing. Leave empty to find ffprobe on PATH.
+    "vadModelPath": "", // Path to a whisper.cpp Silero VAD model. Enables dialogue-focused generation while retaining uncertain audible sections, which may include songs. Leave empty to transcribe the full audio.
+    "vadPath": "" // Optional speech detector executable override. With vadModelPath configured, leave empty to find whisper-vad-speech-segments or vad-speech-segments on PATH.
+  }, // Generate timed Japanese subtitles from local audio using whisper.cpp.
+
   // ==========================================
   // Visible Overlay Auto-Start
   // Show the visible subtitle overlay automatically after managed mpv playback starts SubMiner.
@@ -172,7 +198,7 @@
   "updates": {
     "enabled": true, // Run automatic update checks in the background. Values: true | false
     "checkIntervalHours": 24, // Minimum hours between automatic update checks.
-    "notificationType": "both", // How SubMiner announces available updates. overlay shows notifications on the overlay, system uses OS notifications, both uses overlay and system. osd and osd-system are legacy config-file-only values. Values: overlay | system | both | none | osd | osd-system
+    "notificationType": "overlay", // How SubMiner announces available updates. overlay shows notifications on the overlay, system uses OS notifications, both uses overlay and system. osd and osd-system are legacy config-file-only values. Values: overlay | system | both | none | osd | osd-system
     "channel": "stable" // Release channel used for update checks. Values: stable | prerelease
   }, // Automatic update check behavior.
 
@@ -205,11 +231,15 @@
     "openCharacterDictionaryManager": "CommandOrControl+D", // Accelerator that opens the character dictionary manager modal.
     "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.
     "openControllerDebug": "Alt+Shift+C", // Accelerator that opens the controller debug modal with live axis/button readouts.
     "toggleSubtitleSidebar": "Backslash", // Accelerator that toggles the subtitle sidebar visibility.
-    "toggleNotificationHistory": "CommandOrControl+N" // Accelerator that toggles the overlay notification history panel.
+    "toggleNotificationHistory": "CommandOrControl+N", // Accelerator that toggles the overlay notification history panel.
+    "appendClipboardVideoToQueue": "CommandOrControl+A" // Accelerator that appends a video path from the clipboard to the mpv playlist.
   }, // Overlay keyboard shortcuts. Set a shortcut to null to disable.
 
   // ==========================================
@@ -290,15 +320,41 @@
       ] // Command setting.
     },
     {
-      "key": "Shift+BracketRight", // Key setting.
+      "key": "Ctrl+Shift+ArrowLeft", // Key setting.
       "command": [
-        "__sub-delay-next-line"
+        "sub-step",
+        -1
       ] // Command setting.
     },
     {
-      "key": "Shift+BracketLeft", // Key setting.
+      "key": "Ctrl+Shift+ArrowRight", // Key setting.
       "command": [
-        "__sub-delay-prev-line"
+        "sub-step",
+        1
+      ] // Command setting.
+    },
+    {
+      "key": "KeyZ", // Key setting.
+      "command": [
+        "add",
+        "sub-delay",
+        -0.1
+      ] // Command setting.
+    },
+    {
+      "key": "Shift+KeyZ", // Key setting.
+      "command": [
+        "add",
+        "sub-delay",
+        0.1
+      ] // Command setting.
+    },
+    {
+      "key": "KeyX", // Key setting.
+      "command": [
+        "add",
+        "sub-delay",
+        0.1
       ] // Command setting.
     },
     {
@@ -405,6 +461,12 @@
     "nameMatchColor": "#f5bde6", // Hex color used when a subtitle token matches an entry from the SubMiner character dictionary.
     "nPlusOneColor": "#c6a0f6", // Color used for the single N+1 target token subtitle highlight.
     "knownWordColor": "#a6da95", // Color used for known-word subtitle highlights.
+    "knownWordMaturityColors": {
+      "new": "#ee99a0", // Color for known words whose Anki cards are new (never reviewed), when maturity highlighting is enabled.
+      "learning": "#b7bdf8", // Color for known words whose Anki cards are in (re)learning, when maturity highlighting is enabled.
+      "young": "#91d7e3", // Color for known words whose Anki cards are in review below the mature threshold, when maturity highlighting is enabled.
+      "mature": "#a6da95" // Color for known words whose Anki cards are at or above the mature interval threshold, when maturity highlighting is enabled.
+    }, // Known word maturity colors setting.
     "jlptColors": {
       "N1": "#ed8796", // N1 setting.
       "N2": "#f5a97f", // N2 setting.
@@ -489,7 +551,7 @@
   // ==========================================
   // AnkiConnect Integration
   // Automatic Anki updates and media generation options.
-  // Hot-reload: ankiConnect.ai.enabled, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, and isKiku.fieldGrouping update live while SubMiner is running.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/wordAudio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, isSenren.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
   // Shared AI provider transport settings are read from top-level ai and typically require restart.
   // Most other AnkiConnect settings still require restart.
   // ==========================================
@@ -510,6 +572,7 @@
     "fields": {
       "word": "Expression", // Card field for the mined word or expression text.
       "audio": "ExpressionAudio", // Card field that receives generated sentence audio.
+      "wordAudio": "ExpressionAudio", // Existing word-audio field read to time the frozen first frame of animated images. This mapping is only used for synchronization.
       "image": "Picture", // Card field that receives the captured screenshot or animated image.
       "sentence": "Sentence", // Card field that receives the source sentence text.
       "miscInfo": "MiscInfo", // Card field that receives the miscellaneous info pattern (see ankiConnect.metadata.pattern).
@@ -533,16 +596,21 @@
       "animatedMaxHeight": 0, // Maximum height for animated AVIF captures, in pixels. Set to 0 to preserve aspect ratio.
       "animatedCrf": 35, // Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.
       "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
+      "normalizeAudio": true, // Normalize generated sentence audio loudness during media extraction. Changes apply live. Values: true | false
+      "mirrorMpvVolume": true, // Apply mpv's current software volume curve to generated sentence audio. Changes apply live. Values: true | false
+      "reviewTiming": false, // Review and preview subtitle media timing before SubMiner creates or enriches a mined card. Values: true | false
       "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio and animated AVIF clips.
       "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
-      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.
+      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds. 0 disables the cap.
     }, // Media setting.
     "knownWords": {
       "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
+      "maturityEnabled": false, // Color known-word highlights by Anki card maturity (new, learning, young, mature) instead of a single color. Requires known-word highlighting. Values: true | false
+      "matureThresholdDays": 21, // Card interval in days at which a known word counts as mature (Anki convention: 21).
       "refreshMinutes": 1440, // Minutes between known-word cache refreshes.
       "addMinedWordsImmediately": true, // Immediately append newly mined card words into the known-word cache. Values: true | false
       "matchMode": "headword", // Known-word matching strategy for subtitle annotations. Cache matches always receive known-word highlighting even when POS filters suppress other annotation types. Values: headword | surface
-      "decks": {} // Decks and expression/word fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word"] }.
+      "decks": {} // Decks and expression/word fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word"] }. Reading fields (Reading, Word Reading, ExpressionReading) are always probed so cached words match only in the reading their note teaches; words from notes without readings match in any reading.
     }, // Known words setting.
     "behavior": {
       "overwriteAudio": true, // When updating an existing card, overwrite the audio field instead of skipping it. Values: true | false
@@ -567,7 +635,15 @@
       "enabled": false, // Enable Kiku-specific mining behaviors (duplicate handling, field grouping). Values: true | false
       "fieldGrouping": "disabled", // Kiku duplicate-card field grouping mode. Values: auto | manual | disabled
       "deleteDuplicateInAuto": true // When Kiku field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
-    } // Is kiku setting.
+    }, // Is kiku setting.
+    "isSenren": {
+      "enabled": false, // Enable Senren-specific duplicate handling (scene-switching field grouping, including miscInfo grouping). Mutually exclusive with isKiku.enabled. Values: true | false
+      "fieldGrouping": "auto", // Senren duplicate-card field grouping mode (scene switching). Values: auto | manual | disabled
+      "deleteDuplicateInAuto": true // When Senren field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
+    }, // Is senren setting.
+    "lapisKiku": {
+      "wordCardKind": "word-and-sentence" // Card-type flag SubMiner marks on Kiku/Lapis word cards. Only one flag is set at a time; the others are cleared. Requires isKiku.enabled or isLapis.enabled. Values: word-and-sentence | click | sentence | audio | none
+    } // Lapis kiku setting.
   }, // Automatic Anki updates and media generation options.
 
   // ==========================================
@@ -583,16 +659,41 @@
     "maxEntryResults": 10 // Maximum Jimaku search results returned.
   }, // Jimaku API configuration and defaults.
 
+  // ==========================================
+  // TsukiHime
+  // TsukiHime subtitle search configuration for Japanese primary and configured secondary subtitles. No API key required.
+  // Hot-reload: TsukiHime changes apply to the next TsukiHime request.
+  // ==========================================
+  "tsukihime": {
+    "apiBaseUrl": "https://api.tsukihime.org/v1", // Base URL of the TsukiHime API (Animetosho successor). No API key required.
+    "maxSearchResults": 10 // Maximum TsukiHime search results returned.
+  }, // TsukiHime subtitle search configuration for Japanese primary and configured secondary subtitles. No API key required.
+
+  // ==========================================
+  // TMDB
+  // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+  // Hot-reload: TMDB changes apply to the next TMDB request.
+  // ==========================================
+  "tmdb": {
+    "apiKey": "", // Your own TMDB API key or read access token for live-action posters and synopses in the stats Library. Release builds bundle a project key, so set this only to use your own quota or when running from source (free under Settings > API on themoviedb.org).
+    "apiKeyCommand": "" // Shell command that prints the TMDB API key to stdout. Used instead of apiKey to avoid storing the key in plain text.
+  }, // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+
   // ==========================================
   // YouTube Playback Settings
   // Defaults for managed subtitle language preferences and YouTube subtitle loading.
-  // Hot-reload: primarySubLanguages applies to the next YouTube subtitle load.
+  // Hot-reload: primarySubLanguages and subtitleSource apply to the next YouTube subtitle load.
   // ==========================================
   "youtube": {
     "primarySubLanguages": [
       "ja",
       "jpn"
-    ] // Comma-separated primary subtitle language priority for managed subtitle auto-selection.
+    ], // Comma-separated primary subtitle language priority for managed subtitle auto-selection.
+    "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.
+    } // Media cache setting.
   }, // Defaults for managed subtitle language preferences and YouTube subtitle loading.
 
   // ==========================================
@@ -639,7 +740,7 @@
     "executablePath": "", // Optional absolute path to mpv.exe for Windows launch flows. Leave empty to auto-discover from SUBMINER_MPV_PATH or PATH.
     "launchMode": "normal", // Default window state for SubMiner-managed mpv launches. Values: normal | maximized | fullscreen
     "profile": "", // Optional mpv profile name passed to SubMiner-managed mpv launches. Leave empty to pass no profile.
-    "socketPath": "\\\\.\\pipe\\subminer-socket", // mpv IPC socket path used by SubMiner-managed playback and the bundled mpv plugin.
+    "socketPath": "/tmp/subminer-socket", // mpv IPC socket path used by SubMiner-managed playback and the bundled mpv plugin.
     "backend": "auto", // Window tracking backend passed to the bundled mpv plugin. Auto detects the current platform. Values: auto | hyprland | sway | x11 | macos | windows
     "autoStartSubMiner": true, // Start SubMiner in the background when SubMiner-managed mpv loads a file. Values: true | false
     "pauseUntilOverlayReady": true, // Pause mpv on visible-overlay auto-start until SubMiner signals subtitle tokenization readiness. Values: true | false

docs-site/.vitepress/config.ts

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync, statSync } from 'node:fs';
-import { extname, join, posix, resolve, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import type { DefaultTheme, HeadConfig, TransformContext, UserConfig } from 'vitepress';
 
 const DOCS_HOSTNAME = 'https://docs.subminer.moe';
@@ -13,12 +14,6 @@ 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,19 +21,11 @@ function optionalEnv(value: string | undefined): string | undefined {
 const base = normalizeBase(optionalEnv(process.env.SUBMINER_DOCS_BASE) ?? '/');
 const outDir = optionalEnv(process.env.SUBMINER_DOCS_OUT_DIR);
 const docsSourceDir = optionalEnv(process.env.SUBMINER_DOCS_SOURCE_DIR) ?? process.cwd();
+// The tracked `docs-site/` checkout, which stays a git working tree even when
+// `docsSourceDir` points at an untracked release snapshot. Used for git lookups only.
+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.14.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 '/';
@@ -50,21 +37,6 @@ 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}`;
@@ -82,15 +54,18 @@ function pageToRoute(page: string): string | null {
   return route ? `/${route}` : '/';
 }
 
+// Only the root channel is indexable. `main` and every /v/<version>/ archive are
+// near-verbatim copies of it, so they own their URL via a self-referential canonical
+// and are excluded from the index instead of being consolidated onto root. Uniform
+// self-canonical plus noindex avoids mixing noindex with a cross-page canonical,
+// which Google treats as a conflicting signal.
+const isIndexableChannel = channel === 'stable-root';
+
 function pageToCanonicalHref(page: string): string | null {
   const route = pageToRoute(page);
   if (!route) return null;
 
-  if (channel === 'main') {
-    return `${DOCS_HOSTNAME}${canonicalRouteWithBase(route)}`;
-  }
-
-  if (channel === 'stable-archive' && docsVersion !== latestStable) {
+  if (!isIndexableChannel) {
     return `${DOCS_HOSTNAME}${canonicalRouteWithBase(route)}`;
   }
 
@@ -106,7 +81,9 @@ function transformPageHead({ page }: TransformContext): HeadConfig[] {
   const href = pageToCanonicalHref(page);
   const head: HeadConfig[] = href ? [['link', { rel: 'canonical', href }]] : [];
 
-  if (channel === 'main') {
+  // Crawlable so links still pass through, but out of the index: ~30 archived copies
+  // of every page otherwise soak up the crawl budget the current docs need.
+  if (!isIndexableChannel) {
     head.push(['meta', { name: 'robots', content: 'noindex,follow' }]);
   }
 
@@ -155,137 +132,49 @@ function filterSidebar(items: DefaultTheme.SidebarItem[]): DefaultTheme.SidebarI
     .filter((item): item is DefaultTheme.SidebarItem => Boolean(item));
 }
 
-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}`;
+// 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 sitemapUrlToPage(url: string): string {
+  const route = url.replace(/\.html$/, '').replace(/^\/+|\/+$/g, '');
+  return route ? `${route}.md` : 'index.md';
 }
 
-function localVersionSwitchLink(path: string): string {
-  if (base === '/') return path;
+// VitePress derives <lastmod> by running `git log` inside its source dir. Production
+// builds point that at an untracked snapshot of the release tag, so the lookup comes
+// back empty and the sitemap ships with no dates at all. Resolve it from the tracked
+// checkout at the ref being built instead.
+function lastModifiedFor(url: string): string | undefined {
+  const ref = docsVersion && docsVersion !== 'main' ? docsVersion : 'HEAD';
+  const result = spawnSync('git', ['log', '-1', '--format=%cI', ref, '--', sitemapUrlToPage(url)], {
+    cwd: repoDocsDir,
+    encoding: 'utf8',
+  });
 
-  const basePath = base.replace(/\/$/, '');
-  const targetPath = path === '/' ? '/' : path.replace(/\/$/, '');
-  const relativePath = posix.relative(basePath, targetPath) || '.';
-
-  return path.endsWith('/') ? `${relativePath}/` : relativePath;
+  return (result.status === 0 && result.stdout.trim()) || undefined;
 }
 
-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,
+// Only the root channel publishes a sitemap. Archived and `main` builds would emit
+// their own copies listing the same canonical URLs, which just advertises the
+// duplicate trees we are trying to keep out of the index.
+const sitemap: UserConfig['sitemap'] = isIndexableChannel
+  ? {
+      hostname: DOCS_HOSTNAME,
+      transformItems(items) {
+        return items
+          .filter((item) => item.url !== 'README' && item.url !== `${DOCS_HOSTNAME}/README`)
+          .map((item) => ({ ...item, lastmod: item.lastmod ?? lastModifiedFor(item.url) }));
       },
-  ...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,
-  })),
-];
+    }
+  : undefined;
 
 const nav: DefaultTheme.NavItem[] = [
   { text: 'Home', link: '/' },
@@ -294,7 +183,7 @@ const nav: DefaultTheme.NavItem[] = [
   { text: 'Configuration', link: '/configuration' },
   { text: 'Changelog', link: '/changelog' },
   { text: 'Troubleshooting', link: '/troubleshooting' },
-  { text: docsVersion ?? (channel === 'main' ? 'main' : latestStable), items: versionItems },
+  { text: docsVersion ?? 'main', items: versionItems },
 ];
 
 const sidebar: DefaultTheme.SidebarItem[] = [
@@ -327,6 +216,8 @@ const sidebar: DefaultTheme.SidebarItem[] = [
       { text: 'Jellyfin', link: '/jellyfin-integration' },
       { text: 'YouTube', link: '/youtube-integration' },
       { text: 'Jimaku', link: '/jimaku-integration' },
+      { text: 'Subtitle Generation', link: '/subtitle-generation' },
+      { text: 'TsukiHime', link: '/tsukihime-integration' },
       { text: 'AniList', link: '/anilist-integration' },
       { text: 'AniSkip', link: '/aniskip-integration' },
       { text: 'Character Dictionary', link: '/character-dictionary' },
@@ -350,33 +241,6 @@ 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 }],
     [
@@ -418,14 +282,7 @@ const config: UserConfig = {
   appearance: 'dark',
   cleanUrls: true,
   metaChunk: true,
-  sitemap: {
-    hostname: DOCS_HOSTNAME,
-    transformItems(items) {
-      return items.filter(
-        (item) => item.url !== 'README' && item.url !== `${DOCS_HOSTNAME}/README`,
-      );
-    },
-  },
+  sitemap,
   transformHead: transformPageHead,
   lastUpdated: true,
   srcExclude: ['subagents/**', 'README.md'],

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

@@ -1,10 +1,10 @@
 <script setup>
 import { useRoute, useData } from 'vitepress';
-import { computed } from 'vue';
-import { formatStatusLineFilePath } from '../status-line';
+import { computed, onMounted, ref } from 'vue';
+import { formatStatusLineDate, formatStatusLineFilePath } from '../status-line';
 
 const route = useRoute();
-const { page, frontmatter } = useData();
+const { frontmatter } = useData();
 
 const mode = computed(() => {
   const layout = frontmatter.value.layout;
@@ -23,10 +23,10 @@ const section = computed(() => {
   return parts[0] || 'root';
 });
 
-const lastUpdated = computed(() => {
-  if (!page.value.lastUpdated) return '';
-  const date = new Date(page.value.lastUpdated);
-  return date.toISOString().slice(0, 10);
+// Set on the client only, so the prerendered HTML never bakes in the build date.
+const today = ref('');
+onMounted(() => {
+  today.value = formatStatusLineDate(new Date());
 });
 </script>
 
@@ -40,8 +40,8 @@ const lastUpdated = computed(() => {
     <div class="tui-statusline__right">
       <span class="tui-statusline__section">{{ section }}</span>
       <span 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 v-if="today" class="tui-statusline__date">{{ today }}</span>
+      <span v-if="today" 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 { formatStatusLineFilePath } from './status-line';
+import { formatStatusLineDate, formatStatusLineFilePath } from './status-line';
 
 test('status line file path formats root home as index markdown', () => {
   expect(formatStatusLineFilePath('/')).toBe('index.md');
@@ -10,7 +10,9 @@ 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',
-  );
+  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');
 });

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

@@ -2,3 +2,10 @@ 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

@@ -1,4 +1,4 @@
-# SubMiner Docs
+# SubMiner docs
 
 In-repo VitePress documentation source for SubMiner.
 
@@ -38,8 +38,25 @@ bun run docs:dev
 The public docs root is stable-only:
 
 - `/` serves the latest stable release docs.
-- `/main/` serves development docs from `main` and is marked `noindex,follow`.
+- `/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.
+
 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,130 +1,68 @@
-# AniList Integration
+# AniList integration
 
-SubMiner can sync your watch progress to [AniList](https://anilist.co) automatically. When you finish an episode, SubMiner detects the title and episode number from the filename, finds the matching AniList entry, and updates your progress via the GraphQL API. Failed updates are retried with exponential backoff in the background.
-
-AniList data also powers two additional features: [cover art](#cover-art) for the stats dashboard and the [Character Dictionary](/character-dictionary) for in-overlay name lookup.
-
-[AniList](https://anilist.co) is a free website for tracking which anime you have watched. An **access token** is a private key SubMiner stores so it can update your list on your behalf - you approve it once during setup, and you never paste a password into SubMiner.
+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).
 
 ## Setup
 
-AniList integration is opt-in. To enable it:
+1. Set `anilist.enabled` to `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.
-
-```jsonc
-{
+   ```jsonc
+   {
      "anilist": {
        "enabled": true,
-    "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`).
+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.
 
-If the embedded auth UI fails to render, SubMiner opens the authorize URL in your default browser and shows fallback instructions in-app.
+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`.
 
-::: 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.
-:::
+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`.
 
-## How Tracking Works
+## How updates work
 
-SubMiner monitors playback and triggers an AniList progress update when an episode is considered "watched" -- at least 85% of the episode duration viewed and a minimum of 10 minutes watched.
+An episode counts as watched after 85% of its length and at least 10 minutes of playback. SubMiner then:
 
-The update flow:
+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.
 
-1. **Title detection** -- SubMiner extracts the anime title, season, and episode number from the media filename and path. Season folders such as `Season 2` are treated as a strong season signal. SubMiner tries [`guessit`](https://github.com/guessit-io/guessit) first for accurate parsing, then falls back to an internal filename parser if guessit is unavailable.
-2. **AniList search** -- The detected title is searched against the AniList GraphQL API. For season 2 and later files, SubMiner searches the season-specific title first, then falls back to the base title. SubMiner picks the best match by comparing titles (romaji, English, native) and filtering by episode count.
-3. **Progress check** -- SubMiner fetches your current list entry for the matched media. The media must already be in Planning or Watching; otherwise SubMiner shows an MPV message explaining that the update is not possible. If your recorded progress already meets or exceeds the detected episode, the update is skipped.
-4. **Mutation** -- A `SaveMediaListEntry` mutation sets the new progress and marks the entry as `CURRENT`.
+The show must already be on your Planning or Watching list. SubMiner does not add new entries, and it never lowers your progress.
 
-## Update Queue and Retry
+Failed updates are saved and retried in the background, up to 8 times with growing delays. The queue survives restarts.
 
-Failed AniList updates are persisted to a retry queue on disk and retried with exponential backoff.
+## Fixing a wrong match
 
-| Parameter        | Value      |
-| ---------------- | ---------- |
-| Initial backoff  | 30 seconds |
-| Maximum backoff  | 6 hours    |
-| Maximum attempts | 8          |
-| Queue capacity   | 500 items  |
+If a cover or title in the stats Library is wrong, open the title and use **Change AniList Entry**.
 
-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.
+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).
 
-Use `--anilist-retry-queue` to manually process one ready item from the queue.
+## Commands
 
-## Cover Art
+| 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             |
 
-SubMiner fetches cover art from AniList for display in the stats dashboard. When a new video starts playing, the cover art fetcher:
+## Options
 
-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.
+| Key                   | What it does                                                  |
+| --------------------- | ------------------------------------------------------------- |
+| `anilist.enabled`     | Turns on progress updates.                                    |
+| `anilist.accessToken` | Token override. Leave empty to use the token stored by setup. |
 
-A no-match result is cached for 5 minutes before SubMiner retries, preventing repeated API calls for unrecognized media.
-
-## 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": {
-      "enabled": false,
-      "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.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                                                       |
-
-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. Character dictionary sync follows `subtitleStyle.nameMatchEnabled`.
-
-## 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                |
+Character dictionary settings live under `anilist.characterDictionary` and are covered on the [Character dictionary](/character-dictionary) page. See [Configuration](/configuration#anilist) for defaults.
 
 ## Troubleshooting
 
-- **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 ensure your desktop keyring (gnome-keyring, KWallet) is running.
+**No update after an episode.** Check that `anilist.enabled` is `true` and that you watched at least 85% of the episode.
 
-## Related
+**"AniList update not possible."** Add the show to your Planning or Watching list, then mark the episode watched again.
 
-- [Character Dictionary](/character-dictionary) -- AniList-powered character name dictionary for Yomitan
-- [Configuration Reference](/configuration) -- full config options
-- [Jellyfin Integration](/jellyfin-integration) -- media server integration
+**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`.

docs-site/aniskip-integration.md

@@ -1,12 +1,10 @@
-# AniSkip Integration
+# AniSkip integration
 
-SubMiner integrates with [AniSkip](https://aniskip.com) to automatically detect anime intro intervals and let you skip them with a single key press.
-
-Intro detection runs in the SubMiner app over the mpv IPC socket. It is available whenever the overlay is connected to mpv - not just at launch - and covers every local file loaded during an mpv session, including playlist advances.
+SubMiner looks up opening timestamps on [AniSkip](https://aniskip.com) so you can skip an anime's intro with one key.
 
 ## Setup
 
-AniSkip is opt-in. Enable it in your config:
+AniSkip is on by default. To turn it off or change the key:
 
 ```jsonc
 {
@@ -17,35 +15,25 @@ AniSkip is opt-in. Enable it in your config:
 }
 ```
 
-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):
+Both settings apply immediately, without restarting mpv. For better title and episode detection, install [guessit](https://github.com/guessit-io/guessit):
 
 ```bash
 python3 -m pip install --user guessit
 ```
 
-Without `guessit`, SubMiner falls back to an internal filename parser which handles most common naming conventions but may miss unusual formats.
+## Usage
 
-## How It Works
+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.
 
-On each local file load:
+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.
 
-1. SubMiner infers the anime title, season, and episode number from the filename and path (using `guessit` if available, otherwise the built-in parser). Remote URLs are skipped entirely.
-2. The title is matched against MyAnimeList to resolve a MAL id.
-3. SubMiner queries the AniSkip API for an OP skip interval for that MAL id and episode.
-4. If an interval is found, SubMiner adds `AniSkip Intro Start` and `AniSkip Intro End` chapter markers to the current file and binds the skip key (`mpv.aniskipButtonKey`, default `TAB`).
-5. At the start of the intro, an OSD prompt appears for 3 seconds: `You can skip by pressing TAB` (reflects your configured key). Pressing the key at any point during the intro seeks to the intro end.
-
-Results are cached per file for the app session. Reload detection is also handled: if mpv reloads the same file, SubMiner re-applies the chapter markers without a new API lookup.
+With a custom key other than `TAB` or `y-k`, `y-k` also skips.
 
 ## Triggering from mpv
 
-You can trigger AniSkip actions from mpv script-messages:
+| 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 |
 
-| Command | Effect |
-| ------- | ------ |
-| `script-message subminer-skip-intro` | Skip to the intro end immediately (same as pressing the key) |
-| `script-message subminer-aniskip-refresh` | Force a fresh lookup for the current file, discarding any cached result |
-
-These are handled by the SubMiner app over the IPC socket.
+Use `subminer-aniskip-refresh` after a lookup failed or matched the wrong show.

docs-site/anki-integration.md

@@ -1,50 +1,34 @@
-# Anki Integration
+# Anki integration
 
-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.
+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.
 
-::: 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.
-  :::
+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).
 
 ## Prerequisites
 
 1. Install [Anki](https://apps.ankiweb.net/).
-2. Install the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) add-on (code: `2055492159`).
-3. Keep Anki running while using SubMiner.
+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.
 
-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.
+If you changed AnkiConnect's port, set `ankiConnect.url` to match.
 
-## Auto-Enrichment Transport
+## How cards get filled
 
-When you add a word via Yomitan, SubMiner detects the new card and fills in the sentence, audio, image, and translation fields automatically. Two detection methods are available:
+When Yomitan adds a note, SubMiner fills the sentence, audio, image, and MiscInfo fields. It finds new notes in one of two ways:
 
-**Proxy mode** (default) - SubMiner runs a local _proxy_: a small middleman server that sits between Yomitan and Anki. Yomitan sends new cards to SubMiner, SubMiner enriches them, then passes them along to Anki. This makes enrichment instant.
+- **Proxy (default).** SubMiner runs a local AnkiConnect-compatible server. Yomitan 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.
 
-**Polling mode** (fallback, when the proxy is disabled) - SubMiner asks AnkiConnect every few seconds whether any new cards were added, then enriches them. Simpler setup, but with a short delay (~3 seconds).
+Set `ankiConnect.behavior.autoUpdateNewCards` to `false` to stop automatic filling and update cards by hand with `Ctrl/Cmd+V` instead.
 
-Use proxy mode if you want immediate enrichment. Use polling mode if your Yomitan instance is external (browser-based) or you prefer minimal configuration.
+`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.
 
-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. Fills the translation field from the secondary subtitle or AI.
-5. Writes metadata to the miscInfo field.
-
-Polling mode uses the query `"deck:<ankiConnect.deck>" added:1` to find recently added cards. If no deck is configured, it uses Yomitan's current mining deck when available; otherwise it searches all decks. In Settings, the AnkiConnect deck dropdown auto-fills and persists Yomitan's current mining deck when available, then falls back to the decks reported by AnkiConnect.
-Known-word sync scope is controlled by `ankiConnect.knownWords.decks`.
-
-### Proxy Mode Setup (Yomitan / Texthooker)
+### Proxy mode setup (Yomitan / texthooker) {#proxy-mode-setup-yomitan-texthooker}
 
 ```jsonc
 "ankiConnect": {
-  "url": "http://127.0.0.1:8765", // real AnkiConnect
+  "url": "http://127.0.0.1:8765",
   "proxy": {
     "enabled": true,
     "host": "127.0.0.1",
@@ -54,330 +38,185 @@ Known-word sync scope is controlled by `ankiConnect.knownWords.decks`.
 }
 ```
 
-Then point Yomitan/clients to `http://127.0.0.1:8766` instead of `8765`.
+Clients must send notes to the proxy (`http://127.0.0.1:8766` here), not to AnkiConnect directly.
 
-When SubMiner loads the bundled Yomitan extension, it also attempts to update the **default Yomitan profile** (`profiles[0].options.anki.server`) to the active SubMiner endpoint:
+- **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.
 
-- proxy URL when `ankiConnect.proxy.enabled` is `true`
-- direct `ankiConnect.url` when proxy mode is disabled
+### Proxy troubleshooting
 
-To avoid clobbering custom setups, this auto-update only changes the default profile when its current server is blank or the stock Yomitan default (`http://127.0.0.1:8765`).
+If cards are not getting filled:
 
-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`).
+1. Check that the proxy is listening while SubMiner runs:
 
-### Browser/Yomitan external setup (separate profile)
+   ```bash
+   ss -ltnp | grep 8766
+   ```
 
-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.
+2. Check that requests pass through to Anki:
 
-That profile isolation gives you both benefits:
-
-- SubMiner can auto-enrich immediately via proxy.
-- Your default Yomitan profile keeps its existing Anki server setting.
-
-In Yomitan, go to Settings → Profile and:
-
-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.
-
-This is only for non-bundled, external/browser Yomitan or other clients. The bundled profile auto-update logic only targets `profiles[0]` when it is blank or still default.
-
-### Proxy Troubleshooting (quick checks)
-
-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 \
+   ```bash
+   curl -sS http://127.0.0.1:8766 \
      -H 'content-type: application/json' \
      -d '{"action":"version","version":2}'
-```
+   ```
 
-3. Check both log sinks:
+3. Read the app log (`app-YYYY-MM-DD.log`) in the logs folder. See [Troubleshooting](/troubleshooting) for where logs live.
 
-- Launcher/mpv-integrated log: `~/.cache/SubMiner/mp.log`
-- App runtime log: `~/.config/SubMiner/logs/SubMiner-YYYY-MM-DD.log`
+## Field mapping
 
-4. Ensure config JSONC is valid and logging shape is correct:
+`ankiConnect.fields` maps SubMiner's data to fields on your note type.
 
-```jsonc
-"logging": {
-  "level": "debug"
-}
-```
-
-`"logging": "debug"` is invalid for current schema and can break reload/start behavior.
-
-## Field Mapping
-
-SubMiner maps its data to your Anki note fields. Configure these under `ankiConnect.fields`:
+| 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`                                  |
 
 ```jsonc
 "ankiConnect": {
   "fields": {
-    "word": "Expression",           // mined word / expression text
-    "audio": "ExpressionAudio",    // audio clip from the video
-    "image": "Picture",             // screenshot or animated clip
-    "sentence": "Sentence",         // subtitle text
-    "miscInfo": "MiscInfo",         // metadata (filename, timestamp)
-    "translation": "SelectionText"  // secondary sub or AI translation
+    "audio": "SentenceAudio",
+    "sentence": "Sentence"
   }
 }
 ```
 
-Field names must match your Anki note type exactly (case-sensitive). If a configured field does not exist on the note type, SubMiner skips it without error.
+Field names are matched case-insensitively. A mapped field that is missing from the note type is skipped.
 
-### Minimal Config
+`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.
 
-If you only want sentence and audio on your cards:
+`ankiConnect.tags` adds tags to every mined or updated card. Set it to `[]` to add none.
 
-```jsonc
-"ankiConnect": {
-  "enabled": true,
-  "fields": {
-    "sentence": "Sentence",
-    "audio": "ExpressionAudio"
-  }
-}
-```
+`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.
 
-## Media Generation
+## Media
 
-SubMiner uses FFmpeg to generate audio and image media from the video. FFmpeg must be installed and on `PATH`.
+| 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)                                                        |
 
-### Audio
+Animated AVIF needs an FFmpeg build with an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`).
 
-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.
+Media settings apply to the next card without a restart.
 
-```jsonc
-"ankiConnect": {
-  "media": {
-    "generateAudio": true,
-    "audioPadding": 0,           // optional seconds before and after subtitle timing
-    "maxMediaDuration": 30       // cap total duration in seconds
-  }
-}
-```
+### Review media timing
 
-Output format: MP3 at 44100 Hz. If the video has multiple audio streams, SubMiner uses the active stream.
+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.
 
-The audio is uploaded to Anki's media folder and inserted as `[sound:audio_<timestamp>.mp3]`.
+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.
 
-### Screenshots (Static)
+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.
 
-A single frame is captured at the current playback position.
+| 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`                                                              |
 
-```jsonc
-"ankiConnect": {
-  "media": {
-    "generateImage": true,
-    "imageType": "static",
-    "imageFormat": "jpg",        // "jpg", "png", or "webp"
-    "imageQuality": 92,          // 1–100
-    "imageMaxWidth": null,       // optional, preserves aspect ratio
-    "imageMaxHeight": null
-  }
-}
-```
+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.
 
-### Animated Clips (AVIF)
+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.
 
-Instead of a static screenshot, SubMiner can generate an animated AVIF covering the subtitle duration.
+### Update behavior
 
-```jsonc
-"ankiConnect": {
-  "media": {
-    "generateImage": true,
-    "imageType": "avif",
-    "animatedFps": 10,
-    "animatedMaxWidth": 640,
-    "animatedMaxHeight": null,
-    "animatedCrf": 35            // 0–63, lower = better quality
-  }
-}
-```
+| 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`               |
 
-Animated AVIF requires an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`) in your FFmpeg build. Generation timeout is 60 seconds.
+Manual clipboard updates (`Ctrl/Cmd+V`) always replace the sentence audio, whatever `overwriteAudio` says.
 
-### Behavior Options
+## Sentence cards (Lapis) {#sentence-cards-lapis}
 
-```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
-    "notificationType": "overlay"   // "overlay", "system", "both", or "none"
-  }
-}
-```
-
-`both` now means overlay + system notification. `osd` and `osd-system` are legacy config-file-only values; set `notificationType` to `"osd-system"` in `config.jsonc` if you previously used `both` and want to keep mpv OSD + system notifications. The Settings window shows `osd` or `osd-system` when already configured, but only offers `overlay`, `system`, `both`, and `none` as normal choices.
-
-When media is available, mined-card overlay and system notifications include the same current-frame thumbnail.
-
-`overwriteAudio` applies to automatic card updates and duplicate-card enrichment. Manual clipboard subtitle updates (`Ctrl/Cmd+C`, then `Ctrl/Cmd+V`) always replace generated sentence audio, while leaving the word audio field unchanged.
-
-## AI Translation
-
-SubMiner can auto-translate the mined sentence and fill the translation field.
-Secondary subtitle text still wins when present. AI translation is only attempted when `ankiConnect.ai.enabled` is `true` and no secondary subtitle exists.
-
-```jsonc
-"ai": {
-  "enabled": true,
-  "apiKey": "sk-...",
-  "apiKeyCommand": "",
-  "baseUrl": "https://openrouter.ai/api",
-  "requestTimeoutMs": 15000
-},
-"ankiConnect": {
-  "ai": {
-    "enabled": true,
-    "model": "openai/gpt-4o-mini",
-    "systemPrompt": "Translate mined sentence text only."
-  }
-}
-```
-
-`ankiConnect.ai` controls feature-local enablement plus optional `model` / `systemPrompt` overrides.
-Provider credentials and request transport settings live in top-level `ai`.
-
-Translation priority:
-
-1. If a secondary subtitle is available, use it as the translation.
-2. If `ankiConnect.ai.enabled` is `true` and top-level `ai.enabled` is `true`, call the shared AI provider.
-3. If AI translation fails and no secondary subtitle exists, fall back to the original sentence text.
-
-The built-in translation request asks for English output by default. Customize that behavior through `ankiConnect.ai.systemPrompt`.
-
-## 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 both require `ankiConnect.isLapis.enabled: true` and a valid `sentenceCardModel` pointing to your Lapis/Kiku note type. Without this, the `Ctrl/Cmd+S` and `Ctrl/Cmd+Shift+A` shortcuts will not create cards.
-:::
+`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.
 
 ```jsonc
 "ankiConnect": {
   "isLapis": {
     "enabled": true,
-    "sentenceCardModel": "Japanese sentences"
+    "sentenceCardModel": "Lapis"
   }
 }
 ```
 
-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.
+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.
 
-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)
 
-## Field Grouping (Kiku)
+When `isKiku` or `isLapis` is enabled, SubMiner sets a card-type flag on word cards it fills. Choose the flag with `ankiConnect.lapisKiku.wordCardKind`:
 
-When you mine the same word multiple times, SubMiner can merge the cards instead of creating duplicates. This is designed for note types like [Kiku](https://github.com/youyoumu/kiku) that support grouped sentence/audio/image fields.
+| Value               | Flag                    |
+| ------------------- | ----------------------- |
+| `word-and-sentence` | `IsWordAndSentenceCard` |
+| `click`             | `IsClickCard`           |
+| `sentence`          | `IsSentenceCard`        |
+| `audio`             | `IsAudioCard`           |
+| `none`              | Leaves flags alone      |
+
+The other card-type flags are cleared. Sentence cards and audio cards keep their own flag.
+
+## 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.
 
 ```jsonc
 "ankiConnect": {
   "isKiku": {
     "enabled": true,
-    "fieldGrouping": "manual",         // "auto", "manual", or "disabled"
-    "deleteDuplicateInAuto": true      // delete new card after auto-merge
+    "fieldGrouping": "manual",
+    "deleteDuplicateInAuto": true
   }
 }
 ```
 
-### Modes
+For Senren, use the same keys under `isSenren`.
 
-**Disabled** (`"disabled"`): No duplicate detection. Each card is independent.
+| `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             |
 
-**Auto** (`"auto"`): When a duplicate expression is found, SubMiner merges the new card into the existing one automatically. Both sentences, audio clips, and images are preserved, and exact duplicate values are collapsed to one entry. If `deleteDuplicateInAuto` is true, the new card is deleted after merging.
-
-**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.
-
-### What Gets Merged
-
-| Field    | Merge behavior                                                  |
-| -------- | --------------------------------------------------------------- |
-| Sentence | Both sentences preserved (exact duplicate text is deduplicated) |
-| Audio    | Both `[sound:...]` entries kept (exact duplicates deduplicated) |
-| Image    | Both images kept (exact duplicates deduplicated)                |
-
-### Keyboard Shortcuts in the Modal
+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.
 
 | Key         | Action                                |
-| --------- | ---------------------------------- |
-| `1` / `2` | Select card 1 or card 2 to keep    |
-| `Enter`   | Confirm selection                  |
-| `Esc`     | Cancel (keep both cards unchanged) |
+| ----------- | ------------------------------------- |
+| `1` / `2`   | Keep card 1 or card 2                 |
+| `Enter`     | Confirm                               |
+| `Backspace` | Back from the merge preview           |
+| `Esc`       | Cancel and leave both cards unchanged |
 
-## Full Config Example
+## Config validation
 
-```jsonc
-{
-  "ankiConnect": {
-    "enabled": true,
-    "url": "http://127.0.0.1:8765",
-    "pollingRate": 3000,
-    "proxy": {
-      "enabled": false,
-      "host": "127.0.0.1",
-      "port": 8766,
-      "upstreamUrl": "http://127.0.0.1:8765",
-    },
-    "fields": {
-      "word": "Expression",
-      "audio": "ExpressionAudio",
-      "image": "Picture",
-      "sentence": "Sentence",
-      "miscInfo": "MiscInfo",
-      "translation": "SelectionText",
-    },
-    "media": {
-      "generateAudio": true,
-      "generateImage": true,
-      "imageType": "static",
-      "imageFormat": "jpg",
-      "imageQuality": 92,
-      "audioPadding": 0,
-      "maxMediaDuration": 30,
-    },
-    "behavior": {
-      "overwriteAudio": true,
-      "overwriteImage": true,
-      "mediaInsertMode": "append",
-      "autoUpdateNewCards": true,
-      "notificationType": "overlay",
-    },
-    "ai": {
-      "enabled": false,
-      "model": "openai/gpt-4o-mini",
-      "systemPrompt": "Translate mined sentence text only.",
-    },
-    "isKiku": {
-      "enabled": false,
-      "fieldGrouping": "disabled",
-      "deleteDuplicateInAuto": true,
-    },
-    "isLapis": {
-      "enabled": false,
-      "sentenceCardModel": "Japanese sentences",
-    },
-  },
-  "ai": {
-    "enabled": false,
-    "apiKey": "",
-    "apiKeyCommand": "",
-    "baseUrl": "https://openrouter.ai/api",
-    "requestTimeoutMs": 15000,
-  },
-}
-```
+Invalid `ankiConnect` values produce a warning and fall back to the default. Use JSON booleans (`true`, not `"true"`) and a positive number for `pollingRate`.

docs-site/architecture.md

@@ -1,140 +1,55 @@
 # Architecture
 
-This page is a contributor-facing architecture summary. Canonical internal architecture guidance lives in `docs/architecture/README.md` at the repo root.
+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.
 
-SubMiner is split into three cooperating runtimes:
+SubMiner runs as three cooperating runtimes:
 
-- Electron desktop app (`src/`) for overlay/UI/runtime orchestration.
-- Launcher CLI (`launcher/`) for mpv/app command workflows.
-- mpv Lua plugin (`plugin/subminer/init.lua` + module files) for player-side controls and IPC handoff.
+- 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
 
-Within the desktop app, `src/main.ts` is a composition root that wires small runtime/domain modules plus core services.
+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.
 
-## 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
+## Project layout
 
 ```text
-launcher/                 # Standalone CLI launcher wrapper and mpv helpers
-  commands/               # Command modules (doctor/config/mpv/jellyfin/playback/app passthrough)
-  config/                 # Launcher config parsers + CLI parser builder
-  main.ts                 # Launcher entrypoint and command dispatch
-plugin/
-  subminer/               # Modular mpv plugin (init · main · bootstrap · lifecycle · process
-                          #   state · messages · hover · ui · options · environment · log
-                          #   binary)
+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
 src/
-  ai/                      # AI translation provider utilities (client, config)
-  main-entry.ts           # Background-mode bootstrap wrapper before loading main.js
-  main.ts                  # Entry point - delegates to runtime composers/domain modules
-  preload.ts               # Electron preload bridge
-  types.ts                 # Shared type definitions
-  main/                    # Main-process composition/runtime adapters
-    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 interaction modules
-    modals/                # Jimaku/Kiku/subsync/runtime-options/session-help modals
-    positioning/           # Subtitle position controller (drag-to-reposition)
-  window-trackers/         # Backend-specific tracker implementations (Hyprland, Sway, X11, macOS, Windows)
-  jimaku/                  # Jimaku API integration helpers
-  subsync/                 # Subtitle sync (alass/ffsubsync) helpers
-  subtitle/                # Subtitle processing utilities
-  tokenizers/              # Tokenizer implementations
-  anki-integration/        # AnkiConnect proxy server + note-update enrichment workflow
-  token-mergers/           # Token merge strategies
-  translators/             # AI translation providers
+  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
 ```
 
-### Service Layer (`src/core/services/`)
+A few ownership notes that are hard to guess from file names:
 
-- **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:** `anki-integration.ts`, `anki-integration/anki-connect-proxy.ts` (local proxy for push-based auto-enrichment), `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)
+- 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.
 
-### Renderer Layer (`src/renderer/`)
+## Component diagram
 
-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
-  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
-  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/init.lua` runs inside mpv and loads modular Lua files: `main.lua` (orchestration), `bootstrap.lua` (startup), `lifecycle.lua` (connect/disconnect), `process.lua` (process management), `state.lua` (shared state), `messages.lua` (IPC), `hover.lua` (hover-token highlight rendering), `ui.lua` (OSD rendering), `options.lua` (config), `environment.lua` (detection), `log.lua` (logging), `binary.lua` (path resolution). AniSkip intro detection lives in the SubMiner app (`src/main/runtime/aniskip-runtime.ts`), which drives mpv chapters and the skip key over the IPC socket.
-
-## Flow Diagram
-
-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.
+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.
 
 ```mermaid
 flowchart TB
@@ -215,65 +130,41 @@ flowchart TB
   style ExtRt fill:#363a4f,stroke:#494d64,color:#cad3f5
 ```
 
-## Composition Pattern
+## Composition pattern
 
-Most runtime code follows a dependency-injection pattern:
+Runtime code uses dependency injection:
 
-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.
+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.
 
-The composition root (`src/main.ts`) delegates to focused modules in `src/main/` and `src/main/runtime/composers/`:
+`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.
 
-- `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
+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.
 
-Composer modules share contract conventions via `src/main/runtime/composers/contracts.ts`:
+### IPC boundary
 
-- 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
+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.
 
-This keeps side effects explicit and makes behavior easy to unit-test with fakes.
+### Runtime state ownership
 
-Additional conventions in the current code:
+Some domains, such as AniList token, queue, and media-guess state, use reducer-style transitions:
 
-- `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.
+- 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.
 
-### IPC Contract + Validation Boundary
+## Playback startup flow
 
-- 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.
+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.
 
-### Runtime State Ownership (Migrated Domains)
+Once mpv is up, exactly one of two triggers starts the overlay:
 
-For domains migrated to reducer-style transitions (for example AniList token/queue/media-guess runtime state), follow these rules:
+- 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.
 
-- 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
-
-Before the app boots, something has to launch mpv, inject the plugin, and bring the overlay up. SubMiner-managed launches own this step - the `subminer` launcher, the app's own playback, and the packaged Windows shortcut all follow the same path. The launcher reads `config.jsonc`, spawns mpv with the IPC socket and the bundled plugin, and passes runtime settings as `--script-opts`. The plugin never reads a config file: the shipped `subminer.conf` is intentionally empty so command-line opts always win.
-
-Once mpv is up, exactly one of two triggers brings up the overlay. On a first launch the plugin's `file-loaded` hook self-starts the app once the socket is ready (because the launcher injected `auto_start=yes`). When the app is already running - or for explicit `--start-overlay` and YouTube flows - the launcher instead attaches over the control socket and suppresses the plugin's auto-start, so the two never fire together. Both converge on the same app bring-up, which then runs the Program Lifecycle below.
+Both paths end in the same app bring-up, which then runs the program lifecycle below.
 
 ```mermaid
 flowchart TB
@@ -304,17 +195,17 @@ flowchart TB
   Conn --> Show["Transparent overlay over mpv<br/>Yomitan lookup · mine"]:::overlay
 ```
 
-The runtime sockets in this flow are detailed in [IPC + Runtime Contracts](./ipc-contracts#runtime-sockets).
+The sockets in this flow are described in [IPC + runtime contracts](./ipc-contracts#runtime-sockets).
 
-## Program Lifecycle
+## Program lifecycle
 
-- **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 `SubtitlePipeline` (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.
+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.
 
 ```mermaid
 flowchart TB
@@ -378,11 +269,11 @@ flowchart TB
   style Loop fill:#363a4f,stroke:#494d64,color:#cad3f5
 ```
 
-## Subtitle Prefetch Pipeline
+## Subtitle prefetch
 
-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 `SubtitleCueParser`, 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.
+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.
 
-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.
+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.
 
 ```mermaid
 flowchart TB
@@ -391,7 +282,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["External Sub File"]:::init
+  SubFile["Subtitle Track"]:::init
   Parse["Cue Parser"]:::phase
   Window["Upcoming Lines"]:::phase
   Tokenize["Pre-tokenize"]:::warmup
@@ -408,22 +299,11 @@ flowchart TB
   style Render stroke-width:2px
 ```
 
-## Why This Design
+## Extension rules
 
-- **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 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.
+- 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.

docs-site/archive-function.test.ts

@@ -0,0 +1,116 @@
+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,6 +1,452 @@
 # Changelog
 
-## v0.16.0 (2026-06-10)
+## 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>
+
+**Added**
+
+- **Card Timing Review**:
+  - Optional pre-generation timing review for word, sentence, and audio cards, with a speech-weighted waveform that flattens background noise so dialogue edges stand out clearly.
+  - The clip end automatically snaps back to where the line's dialogue actually ends once the waveform loads, with drag and keyboard adjustments available.
+  - Audio preview includes a sweeping playhead that plays the clip to its true end, even on high-latency outputs like Bluetooth headphones.
+  - Previous and next subtitle lines can be pulled onto the card with `P`/`N` (or the Prev/Next steppers) and removed with Shift; the sentence preview and waveform markers update automatically.
+  - Cancelling lets you keep a card without media, and the review can be toggled on or off for the session.
+- **Senren Field Grouping**:
+  - Enable `ankiConnect.isSenren` to merge duplicate mined cards using Senren's scene-switching markup, grouping sentence, furigana, audio, picture, and misc-info fields.
+  - Supports the same auto/manual/disabled modes as Kiku, including the manual merge modal; only one of Senren or Kiku can be enabled at a time.
+
+**Changed**
+
+- **Remote Stream Mining Performance**: Mining a card from a remote stream (Jellyfin and other HTTP sources) now downloads the clip window once and reuses it for the timing review waveform, audio preview, audio extraction, and screenshot, instead of re-fetching the stream at each step; the temporary file is cleaned up after ten minutes of inactivity or on exit.
+- **TsukiHime Release Filtering**: The TsukiHime modal's Japanese and secondary-language tabs now filter the release list by the subtitle languages each release actually carries, and report when no release has subtitles for the active tab.
+
+**Fixed**
+
+- **Subtitle & Mining Accuracy**:
+  - Broadcast-style captions that split one sentence across two on-screen rows (e.g. Crunchyroll Japanese subs) now merge into a single line for the sidebar and mined cards, while separate speakers, sound effects, and labeled turns still stay on their own lines.
+  - Mining from the overlay no longer pulls in a lingering row from the previous caption; the mined sentence and clip timing now match what's actually on screen.
+  - Multi-line copy and mining now select lines backward in timeline order after seeking, instead of in playback encounter order.
+  - Copying a subtitle, mining a sentence, or recording immersion stats no longer includes the separate furigana line that broadcast ASS captions place above a word.
+- **Card Update Notifications**: Dismissed lingering overlay card-update progress when notification settings switch to OSD before an update finishes.
+- **Overlay Stability on Hyprland**: Opening a modal window (timing review, Jimaku, session help, and others) while mpv is fullscreen no longer causes the overlay to flicker while the modal loads; the overlay now stays on screen untouched until the modal is ready.
+- **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>
+
+**Fixed**
+
+- **Anki Card Update Progress**: The card-update spinner now stays visible until audio and image updates finish, instead of disappearing early.
+- **Anki Word-Card Fields**: Word-card enrichment now writes sentence text and audio to the fields configured in AnkiConnect, while the dedicated sentence-card and audio-card actions keep their existing compatible field names.
+- **Overlapping Subtitles**:
+  - Subtitle lines that start while another line is still on screen now appear alongside it, instead of staying hidden until a track switch or seek.
+  - Subtitles shown at the same time now stack by their authored screen position, with top signs and song lines above bottom dialogue.
+  - Half-size ASS furigana is no longer shown as if it were a dialogue line.
+- **YouTube Auto Captions**:
+  - Auto-generated captions now follow their intended timing and two-row roll-up layout.
+  - 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>
+
+**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.
+- **Duplicate Line Cleanup Tool**: The Vocabulary tab's new "Duplicates" button scans a chosen time window (7 days through all time) for old karaoke/typeset duplicate-line bursts, shows what it found, and collapses each run to one line once confirmed; `subminer stats cleanup --duplicate-lines` does the same from the terminal, with `--dry-run` and `--lookback-days <n>` options. Watch time and lines-seen totals are left unchanged.
+
+**Changed**
+- **Prerelease Release Notes**: Prerelease notes now open with a "Changes since" section listing only what changed versus the previous beta/RC of the same version, above the cumulative highlights, and CI rejects prerelease tags whose committed notes were generated for a different beta/RC.
+
+**Fixed**
+- **Subtitle & Karaoke Duplication**:
+  - Karaoke and animated signs are reconstructed once from their authored text and shown only while actually sung, with original word spacing preserved, instead of flooding the overlay, subtitle sidebar, immersion history, mining, or stats with glyph fragments, per-frame color phases, and repeated animation events.
+  - Decorative layers (highlight sweeps, glow/shadow copies, symbol-font decoration, particle swarms, hidden or zero-scaled text) stay out of published text, while ordinary repeated dialogue, positioned signs, wrapped lyric rows, and multi-row CC-style blocks still display correctly.
+  - Embedded subtitle tracks on network-mounted (SMB/NFS) media are extracted and parsed again instead of falling back to live-text-only, restoring karaoke reconstruction, sidebar cues, and mining for releases that only ship subtitles inside the container.
+  - Secondary subtitles go through the same deduplication pipeline as primary subtitles and no longer clip display after about four lines.
+  - Event-heavy karaoke files that previously stalled subtitle loading for several seconds now parse in well under a second.
+- **Character Dictionary Reliability**:
+  - Generation, merged rebuilds, and imports no longer freeze the app on large dictionaries; snapshot I/O, archive building, and image/name lookup caches moved off the UI's critical path.
+  - Dictionaries are reused instead of regenerated when MeCab finds no name splits.
+  - Cached portraits restore correctly after the portrait index finishes loading post-tokenization.
+  - Desktop progress notifications on Linux AppImage installs update in place instead of flickering, fixing a bug where the AppImage's bundled libraries broke the system notification helper.
+- **Overlay Startup & Modals**:
+  - The macOS window-tracking helper targets macOS 12.0+ instead of requiring the build machine's exact macOS version, fixing crashes on older systems like Ventura that left the overlay stuck on "Overlay loading".
+  - mpv IPC connection attempts time out and retry, showing an actionable error if content still isn't ready after 30 seconds.
+  - Dedicated overlay modals are prewarmed on macOS and Windows so shortcuts open them promptly.
+  - On macOS, reused modals and the stats window open above fullscreen mpv on its current Space instead of jumping to another desktop.
+- **Wayland File Drop**: Fixed native Wayland drag-and-drop from file managers such as Thunar, so subtitle and video files dropped on the visible overlay are resolved and forwarded to mpv.
+- **Windows Mouse Lag**: Fixed system-wide mouse lag on Windows while SubMiner is running, caused by the overlay's global mouse hook for click-through forwarding and by the mpv window tracker blocking the app on repeated PowerShell lookups.
+- **Sentence Mining Audio & Clips**: Sentence-audio generation no longer times out on slow network-mounted media with many subtitle/font streams (bounded FFmpeg probing, two-minute extraction budget, clearer error reporting), and mined audio/animated AVIF clips now capture the subtitle line that was actually mined by snapshotting the clip range at lookup time instead of reading live mpv state later.
+- **Stats Performance & Reliability**: Immersion stats storage now sets its SQLite busy timeout before WAL setup, avoiding transient lock errors under concurrent writes. Deletes in the stats dashboard no longer freeze the UI, run proportional to what's deleted instead of rebuilding full lifetime summaries, retry safely if the delete worker crashes, and no longer rescan the whole library when deleting very common words; a new index also makes large session deletes drop from minutes to milliseconds. Library merges, video moves, and AniList reassignments got the same lifetime-summary fix.
+- **Vocabulary Stats Accuracy**: Vocabulary totals and charts now count all tracked vocabulary instead of only the first page, new-word history uses corrected daily rollups (fixing legacy timestamp and time-zone issues), summary cards refresh automatically after edits to the exclusion list, and rapid exclusion edits no longer race each other.
+- **Rofi MKV Thumbnails**: Fixed missing MKV thumbnails in the Linux rofi picker when system thumbnailer registrations only advertise legacy Matroska MIME aliases.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+- Docs Site Indexing: Excluded the `/main/` and `/v/<version>/` docs trees from search indexing (self-referential canonical, `noindex,follow`, matching `X-Robots-Tag`) so crawlers focus on current docs instead of ~30 archived copies of every page, and restored `<lastmod>` dates in the docs sitemap that were silently dropped by production builds.
+
+</details>
+
+<h2>v0.19.3 (2026-08-13)</h2>
+
+**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`).
+
+**Changed**
+- Subtitle Tokenization Performance: Reworks subtitle dictionary lookups to cut per-line work roughly in half, cache repeated lookups across lines, and stop tokenization from competing with on-screen subtitle prefetching. Also fixes several accuracy issues along the way: dropped readings on trailing kana, character names being skipped after a dictionary sync, annotations not refreshing after mining a card, and halfwidth katakana character names losing their reading or being swallowed by other words.
+
+**Fixed**
+- Character Dictionary Large Imports: Large character dictionaries (e.g. One Piece) no longer fail to install from a fixed timeout budget; the import now scales its time budget to dictionary size and reports detailed progress (page/character counts, image download progress, elapsed time) instead of one static message.
+- Stats Delete Responsiveness: Deleting sessions, episodes, or library entries no longer freezes the stats page or an active video player; deletes are now batched into a single transaction.
+- Styled Subtitle Cue Parsing: Heavily typeset subtitles (karaoke, signs) no longer flood the subtitle sidebar with garbage; vector drawing commands are no longer shown as text, and duplicate/animation-burst cues now collapse into one.
+- X11 mpv Renderer: Fixes an mpv crash on the first fullscreen toggle for X11/XWayland users with `gpu-next` shaders (e.g. ArtCNN), which was caused by X11 mode forcing the legacy OpenGL renderer.
+- X11 Overlay Display Scaling: Fixes the overlay appearing oversized and offset from mpv on X11/XWayland under fractional or mixed-monitor display scaling.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+- Subtitle text is now decoded from ASS exactly once at ingest, so the renderer, timing tracker, and tokenizer all share one decoded value instead of each re-deriving it.
+- Added per-stage debug timings (`scanMs`, `mecabMs`, `frequencyMs`, `annotateMs`) to the subtitle tokenization pipeline log.
+
+</details>
+
+<h2>v0.19.2 (2026-08-04)</h2>
+
+**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.
+
+**Fixed**
+- Streaming Subtitle Tokenization: Jellyfin streams now seed subtitle tokenization directly from the downloaded subtitle file instead of relying on an mpv event that could be missed, and prefetching now runs to the end of the file and clears between episodes. The tokenization cache was raised from 256 to 2500 lines, and parsed cues are no longer lost when the active subtitle track briefly can't be resolved (e.g. switching to an embedded track). Together these prevent episodes from falling back to slow, line-by-line tokenization during playback.
+- Overlay: Subtitle lines now appear immediately at their cue time even on a tokenization cache miss, upgrading in place once tokens and annotations are ready, instead of waiting on a line still being processed. A failed tokenization is no longer cached as plain text, so repeated lines get another chance at annotations.
+- Background Logging: Background startup now respects the configured logging level when no explicit log level is passed.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+- Patched three high-severity dependency advisories (`undici`, `brace-expansion`, `fast-uri`).
+
+</details>
+
+<h2>v0.19.1 (2026-08-01)</h2>
+
+**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.
+
+**Fixed**
+- 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>
+
+**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.
+- Post-Playback Menu: After a watch-history episode ends, the fzf/rofi launcher returns to that series with options to play the previous or next episode, rewatch, pick another episode, or quit. The pre-playback series menu now offers the previous episode too.
+- Delete Library Entries: The stats Library detail view can now delete an entire title in one step (episodes, sessions, subtitle lines, rollups, cover art, and vocabulary counts). Delete progress is now shown app-wide via a progress bar and status toast instead of disappearing when you switch tabs.
+- Cross-Machine Sync: Added SSH-based syncing of stats and watch history between machines, available from the tray ("Sync Stats & History") or `subminer sync`, with saved devices, per-host sync direction, background auto-sync, connection testing, manual snapshots, and support for Windows remotes.
+- TsukiHime Subtitle Downloads: Added subtitle downloads for the current video via TsukiHime, loading Japanese as the primary track and your configured secondary language directly into mpv.
+
+**Changed**
+- Clipboard-Video Shortcut: The "append clipboard video to queue" shortcut is now configurable.
+
+**Fixed**
+- AniList Season Resolution: Season 2+ files now resolve to the correct AniList entry instead of silently falling back to season 1 (which mismatched character dictionaries and watch progress). Manual overrides now stay scoped per season, fix both the dictionary and progress tracking together, and also correct per-season cover art.
+- Subtitle Annotation Accuracy: Fixed several annotation edge cases, including inconsistent POS exclusions on merged quote-particle tokens, dropped annotations on supplementary-plane kanji, katakana punctuation wrongly treated as noise, and certain kanji vocabulary losing N+1 highlighting eligibility.
+- AnkiConnect Proxy Port Conflict: Video startup no longer crashes when another process already holds the configured AnkiConnect proxy port; a notification now explains how to resolve it.
+- AppImage Quit Crash: Fixed a "Service Crash" desktop notification appearing after closing a video when running the Linux AppImage.
+- Autoplay Pause Timing: Fixed playback resuming a few seconds before subtitle tokenization warmup finished, most noticeable when resuming mid-episode or when a cue starts within the first two seconds.
+- Stats Known-Word Count: Fixed stats reporting 0 known words for every session after the known-word cache format changed.
+- Stats Library Cover Art: Relinking a title to a different AniList entry now updates its cover in the Library grid immediately instead of leaving a stale, mismatched cover cached.
+- Rofi Prompt Spacing: Rofi menu prompts now keep a space before the input field instead of running into the placeholder text.
+- Stats Settings & Reliability: Hardened stats settings validation (nested/legacy AnkiConnect config now falls back safely instead of breaking) and stats routes against malformed requests and other edge cases.
+- Stats Delete Performance: Deleting sessions, episodes, and library entries is now dramatically faster and no longer stalls playback (e.g. a 12-episode title dropped from about a minute to under a second on a large library); the Vocabulary tab also loads much faster. The first launch after upgrading runs a one-time database migration.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+- Added a golden-file regression test corpus for the tokenizer/annotation pipeline, plus scripts to record new fixtures and diff against stock Yomitan.
+- Consolidated renderer modal state handling into a descriptor registry.
+- Consolidated CI quality checks (PR, stable, and prerelease) into one reusable workflow with mpv plugin tests and dependency audits.
+- Removed the unused stats IPC transport and unified stats dashboard HTTP types with the backend contract.
+- Added a script to verify known-word highlight tiers against live Anki data outside of playback.
+
+</details>
+
+</details>
+
+<details>
+<summary>v0.18.x</summary>
+
+<h2>v0.18.0 (2026-07-10)</h2>
+
+**Added**
+- Sentence Audio Normalization: Generated sentence audio is now normalized to -23 LUFS by default, and clips mined from playback mirror mpv's software volume curve with a limiter to prevent clipping. Both behaviors are configurable independently.
+- Watch History Command: Added `subminer -H` / `--history` to browse watch history, replay or continue episodes, or pick one via fzf or rofi, with cover art shown in the rofi picker.
+
+**Changed**
+- Fzf Preview Layout: Moved fzf previews below launcher menus, giving long titles and metadata more room.
+- Known-Word Highlighting: Now compares subtitle and Anki-card readings, preventing false matches between homographs and unrelated words that share a reading, while still supporting matching across kana and kanji spellings.
+- Annotation Filtering: Standalone suffix tokens (e.g. さん, れる) are now excluded from JLPT/frequency/N+1 highlighting by default, matching how particles and interjections are treated; configurable via the pos2 exclusion setting.
+- App Icon: Replaced the app icon with new pixel-art submarine artwork contributed by the community, used across the app icon, tray, notifications, README, docs site, and Stats page.
+- Stats Trend Charts: Overhauled with persisted title visibility, per-chart title limits, "top" and "most recent" ranking modes, an option to show or hide empty days, calendar-aligned periods, and value-sorted tooltips.
+
+**Fixed**
+- Background Stats Server: `subminer app` background launches now auto-start the stats server when enabled, and skip startup if one is already running.
+- Character Name Highlighting: Character dictionaries now split unspaced native names more reliably, and portraits, highlights, and hover lookup survive punctuation, unmatched text, and competing dictionary matches without incorrectly splitting longer words.
+- Highlighting Coverage: Frequency/JLPT highlighting and vocabulary stats now include content adverbs (e.g. 確かに, やはり) and kanji nouns MeCab tags as non-independent (e.g. 日, 点, 以外), while still suppressing interjections, pronouns, and grammar fragments; lexicalized kana expressions like かといって keep their annotations.
+- Cover Art Fetching: Stats now fetches AniList cover art as soon as a new series starts playing, and backfills missing art for existing series on the next Stats visit.
+- Kiku Field Grouping: The manual field-grouping dialog now stays above fullscreen mpv, remains usable across repeated attempts, closes abandoned windows after timeouts, and reports a clear error when the original card can no longer be loaded.
+- Karaoke Subtitle Collapse: Secondary subtitles no longer stack dozens of one-syllable lines during openings and endings; repeated events collapse into one line, capped to a strip at the top.
+- Unparsed Token Hover: Subtitle text Yomitan can't parse (truncated inflections, elongation runs) remains hoverable, while staying excluded from highlighting, N+1 candidate math, and vocabulary stats.
+- YouTube Streaming: Fixed direct YouTube stream extraction that could corrupt signed URLs and cause ffmpeg 403 errors.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+- Test lanes moved to `scripts/test-lanes.ts` with per-directory discovery and isolated per-file timeouts; CI now covers previously orphaned stats, scripts, plugin process-retry, and runtime-compat suites, plus a new stats lane in the change-verification workflow.
+
+</details>
+
+</details>
+
+<details>
+<summary>v0.17.x</summary>
+
+<h2>v0.17.2 (2026-06-28)</h2>
+
+**Fixed**
+- YouTube Background Cache: Fixed Windows YouTube background media cache startup for YouTube URLs opened directly in mpv, including resolved stream URLs when mpv still exposes the original YouTube playlist entry, so queued Anki media updates can append audio and images after the cache finishes.
+- YouTube Subtitle Picker: Manual subtitle picker requests now show an immediate configured notification while SubMiner probes tracks and opens the modal. Subtitle download progress is replaced with a transient success notification after tracks load.
+
+<h2>v0.17.1 (2026-06-27)</h2>
+
+**Added**
+- YouTube Media Cache Mode: Adds `youtube.mediaCache.mode` with `direct` and `background` options. Background mode uses a yt-dlp cache download when direct stream extraction is unreliable — creates a text-only card immediately, queues media updates for mined notes, and fills audio/image fields once the download finishes. Progress is announced via overlay/OSD notifications. Downloads are capped at 720p by default (`youtube.mediaCache.maxHeight`). Switching back to direct mode cancels any in-flight background download.
+
+**Fixed**
+- Log Export: Fixed log filenames to use the local date so exports around UTC midnight include the current day's logs rather than stale prior-day files. Expanded export redaction to mask IPs, emails, auth and cookie headers, yt-dlp cookie arguments, URL credentials, token/key/password fields, and signed YouTube media URL parameters.
+- YouTube Card Media: Improved media generation reliability by sending safer ffmpeg options for resolved streams and skipping stale stream maps (including cached YouTube files). Hardened background cache downloads with IPv4 and extractor retry flags; failed downloads now notify the user and clear queued media updates instead of leaving them silently pending. Stale background cache files are cleaned on startup and before each new download.
+
+<h2>v0.17.0 (2026-06-15)</h2>
+
+**Changed**
+
+- **Subtitle Delay Keybindings**: Updated default overlay subtitle delay and step bindings to match mpv conventions: `z`, `Z`, and `x` adjust `sub-delay`; `Ctrl+Shift+Left/Right` run native `sub-step` with OSD feedback. The previous SubMiner-only adjacent-cue delay action has been removed.
+- **Update Notifications**: New installs now default update notifications to overlay-only instead of overlay + system notifications.
+
+**Fixed**
+
+- **Anki – Highlight Word**: Fixed bolding of the mined word in Kiku sentence and sentence-furigana fields when the source Yomitan sentence did not already contain bold markup.
+- **Anki – Lapis/Kiku Word Cards**: Fixed word-and-sentence marker missing from Lapis/Kiku word cards enriched through SubMiner, which could hide sentence context on the card front.
+- **Anki – Windows Media Generation**: Fixed known-word cache refreshes when no deck is configured, and fixed audio/image generation after background launches by recreating missing FFmpeg temp directories before clipping.
+- **Character Dictionary – Windows**: Fixed the Windows "SubMiner mpv" shortcut so character dictionary auto-sync can fall back to mpv's current video path when app media state is not yet ready.
+- **Notifications**: Restored the SubMiner app icon on system notifications that do not supply a custom notification image.
+- **Overlay – macOS Yomitan Popup**: Fixed Yomitan popup focus after card mining or popup reload; fixed popups staying open when clicking transparent overlay space — click-away now closes the popup and returns click passthrough to mpv without a hide/reappear cycle.
+- **Overlay – Linux Auto-Pause Startup**: Fixed the visible overlay on Linux auto-paused startup to stay interactive during the initial measurement gap; startup subtitle cache misses now paint raw text before tokenization finishes, and temporarily empty `sub-text` refreshes are resolved before warm readiness resumes playback.
+- **Overlay – Playlist Advance**: Fixed the visible overlay being dismissed when mpv advances to the next playlist item, including when the next episode loads after the warm transition delay.
+- **Overlay – Windows Subtitle Bar**: Fixed shaky hover and click interaction on the Windows subtitle bar when a video attaches to an already-running background SubMiner instance.
+- **Stats – AniList Linking**: Fixed manual AniList linking from the stats anime page so auto-searches strip the generated "Season N" suffix and query only the anime title.
+- **Updates – Linux Support Assets**: Fixed Linux updates to correctly install and refresh the launcher runtime plugin copy and rofi theme alongside AppImage and launcher updates; unrelated SubMiner data directories are now left untouched and plugin copies are staged before replacing the live runtime. Fixed first-launch playback on fresh installs by auto-installing missing managed support assets from the bundled app before mpv starts.
+
+**Docs**
+
+- **Linux Update Flows**: Documented that Linux update flows manage the launcher runtime plugin copy and rofi theme from `subminer-assets.tar.gz`, and that normal launcher playback auto-installs those managed support assets on a fresh install if either is missing.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+
+- **Runtime Modules**: Split main-process runtime wiring into focused modules without changing user-facing behavior; hardened helpers against stale background stats daemon PIDs, stalled subtitle extraction, and dropped async errors.
+- **Release CI**: Fixed GitHub release notes to preserve the `What's Changed` and `New Contributors` attribution sections when CI regenerates from the committed changelog; scoped prerelease note reuse to the same base version so a new beta line starts from current fragments.
+
+</details>
+
+</details>
+
+<details>
+<summary>v0.16.x</summary>
+
+<h2>v0.16.0 (2026-06-10)</h2>
 
 **Breaking Changes**
 
@@ -48,7 +494,7 @@
 
 </details>
 
-## Previous Versions
+</details>
 
 <details>
 <summary>v0.15.x</summary>

docs-site/character-dictionary.md

@@ -1,307 +1,104 @@
-# Character Dictionary
+# Character dictionary
 
-SubMiner can build a Yomitan-compatible character dictionary from [AniList](https://anilist.co) metadata so that character names in subtitles are recognized, highlighted, and enrichable with context - portraits, roles, voice actors, and biographical detail - without leaving the overlay. (AniList is an online anime/manga database; SubMiner pulls each show's character list from it.)
+SubMiner 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.
 
-This is helpful because proper names rarely appear in normal dictionaries, so character names would otherwise be flagged as "unknown" words and clutter your mining. Recognizing them keeps your N+1 highlighting focused on real vocabulary.
+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).
 
-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.
+## Turning it on
 
-## 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 (no authentication required) and imports the merged dictionary into Yomitan automatically.
-3. Optionally enable **Name Match Images** (Settings → Subtitle Style) to show inline circular character portraits next to matched names in subtitles.
+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.
 
 ```jsonc
 {
   "subtitleStyle": {
     "nameMatchEnabled": true,
-    "nameMatchImagesEnabled": true, // optional - inline portraits
+    "nameMatchImagesEnabled": true,
   },
 }
 ```
 
-::: 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.
-:::
+No AniList account is needed. Logging in to AniList is only for [watch progress sync](/anilist-integration).
 
-::: 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.
-:::
+The character dictionary does not work when `yomitan.externalProfilePath` is set, because SubMiner then uses another app's Yomitan profile read-only.
 
-::: 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.
-:::
+## What happens when you play something
 
-## Name Generation
+When a new show starts, SubMiner:
 
-A single character produces many searchable terms so that names are recognized regardless of how they appear in dialogue. SubMiner generates variants for:
+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.
 
-**Spacing and combination:**
+A notification shows each step. Once it says the dictionary is ready, names match from the next subtitle line.
 
-- Full name with space: 須々木 心一
-- Combined form: 須々木心一
-- Family name alone: 須々木
-- Given name alone: 心一
+Each character gets entries for the full name, family name, given name, and common honorifics (`さん`, `君`, `ちゃん`, `先生`, and others), so `太郎さん` matches as well as `太郎`.
 
-**Middle-dot removal** (common in katakana foreign names):
+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.
 
-- ア・リ・ス → アリス (combined), plus individual segments
+### How long it takes
 
-**Honorific suffixes** - each base name is expanded with 15 common suffixes:
+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.
 
-| Honorific | Reading    |
-| --------- | ---------- |
-| さん      | さん       |
-| 様        | さま       |
-| 先生      | せんせい   |
-| 先輩      | せんぱい   |
-| 後輩      | こうはい   |
-| 氏        | し         |
-| 君        | くん       |
-| くん      | くん       |
-| ちゃん    | ちゃん     |
-| たん      | たん       |
-| 坊        | ぼう       |
-| 殿        | どの       |
-| 博士      | はかせ     |
-| 社長      | しゃちょう |
-| 部長      | ぶちょう   |
+## Correcting AniList matches
 
-**Romanized names** - names stored in romaji on AniList are converted to kana aliases so they can match against Japanese subtitle text.
+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:
 
-This means a character like "太郎" generates entries for 太郎, 太郎さん, 太郎先生, 太郎君, 太郎ちゃん, and so on - all with correct readings.
+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.
 
-## 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 (score 100), supporting (90), side (80), background (70)
-- **Portrait** - character image from AniList, embedded in the ZIP
-- **Description** - biography text from AniList (collapsible)
-- **Character information** - age, birthday, gender, blood type (collapsible)
-- **Voiced by** - voice actor name and portrait (collapsible)
-
-The three collapsible sections can be configured to start open or closed:
-
-```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. **syncing** - Add the media ID to the most-recently-used list. Evict old entries beyond `maxLoaded`.
-4. **building** - Merge active snapshots into a single Yomitan ZIP. A SHA-1 revision hash is computed from the media set - if it matches the previously imported revision, the import is skipped.
-5. **importing** - Push the ZIP into Yomitan. Waits for Yomitan mutation readiness (7-second timeout per operation).
-6. **ready** - Dictionary is live. Character names will match on the next subtitle line.
-
-**State tracking** is persisted in `character-dictionaries/auto-sync-state.json`. AniList media matches are cached separately in `character-dictionaries/anilist-resolution-cache.json` so snapshot hits do not need another AniList search.
-
-```jsonc
-{
-  "activeMediaIds": [170942, 163134, 154587],
-  "mergedRevision": "a1b2c3d4e5f6",
-  "mergedDictionaryTitle": "SubMiner Character Dictionary",
-}
-```
-
-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:
+From the command line:
 
 ```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 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.
-
-Use the in-app selector or CLI to pin the correct AniList media for the whole series:
-
-- 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 candidate AniList matches for a file
+# List AniList matches for a file
 subminer dictionary --candidates "/path/to/episode.mkv"
 
-# Save the correct AniList media ID for that series
+# Save the correct AniList 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"}'
 ```
 
-Manual selections are stored in `character-dictionaries/anilist-overrides.json` using a series key derived from the episode's parent directory plus the filename guess. Later episodes in the same directory use the selected AniList ID automatically, while separate season directories can keep separate overrides and character dictionaries. When the override replaces a previous wrong match, SubMiner removes that stale media ID from the merged dictionary's active set and rebuilds/imports the merged character dictionary.
+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.
 
-## Managing Loaded Entries
+## Managing loaded shows
 
-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.
+The manager (`Ctrl/Cmd+D`) lists the shows in the merged dictionary and marks the current one.
 
-- **Remove** drops a non-current entry from the active merged dictionary and rebuilds/imports once.
-- **Up/Down** changes MRU order for future eviction without rebuilding.
-- **Override** opens the AniList selector for that entry's title so you can replace a saved loaded entry.
+- **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.
 
-The current anime cannot be removed while you are watching it; it stays loaded until playback changes.
+## Generating from the command line
 
-## 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
+```bash
+subminer dictionary /path/to/media
 ```
 
-**Snapshot format** (v17): each snapshot contains the media ID, title, entry count, timestamp, an array of Yomitan term entries, and base64-encoded images.
+This builds a standalone dictionary file for that file or folder without playing it. With the AppImage directly, use `SubMiner.AppImage --dictionary`.
 
-**ZIP structure** follows the Yomitan dictionary format:
+## Configuration
 
-```text
-merged.zip
-  index.json                  # { title, revision, format: 3, author: "SubMiner" }
-  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
-```
+Defaults are in the [configuration reference](/configuration).
 
-## 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 similar ground - name variant generation, honorific expansion, structured Yomitan content, portrait embedding - and additionally supports VNDB as a data source for visual novel characters. Key differences:
-
-|                        | SubMiner                                     | Reference Implementation              |
-| ---------------------- | -------------------------------------------- | ------------------------------------- |
-| **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.
+| 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                         |
 
 ## 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.
+**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)).
 
-## Related
+**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.
 
-- [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
+**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.

docs-site/demos.md

@@ -1,31 +1,30 @@
-# Feature Demos
+# Feature demos
 
-Short recordings of SubMiner's key features and integrations from real playback sessions. A few terms you'll see below: _Yomitan_ is the pop-up dictionary used for word lookups, _Jimaku_ is a community subtitle database, _alass_ and _ffsubsync_ are tools that retime subtitles to match the audio, _Jellyfin_ is a self-hosted media server, and a _texthooker_ is a web page that mirrors the current subtitle as selectable text for browser-based tools.
+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.
 
 <script setup>
 import { withBase } from 'vitepress';
 
-const v = '20260301-1';
+const v = '20260819-1';
 </script>
 
-## Anki Card Mining & Enrichment
+## Anki card mining and enrichment
 
-Mine vocabulary cards from Yomitan or directly from subtitle lines. SubMiner automatically attaches the sentence, a timing-accurate audio clip, a screenshot, and a translation.
+Mine a card from Yomitan or straight from a subtitle line. SubMiner attaches the sentence, an audio clip cut to the line timing, and a screenshot.
 
 <video controls playsinline preload="metadata" :poster="withBase(`/assets/minecard-poster.jpg?v=${v}`)">
   <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="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />
+    <img :src="withBase(`/assets/minecard.webp?v=${v}`)" alt="Animated demo of mining a card" style="width: 100%; height: auto;" />
   </a>
 </video>
 
-::: info VIDEO COMING SOON
-:::
+## Subtitle download and sync
 
-## Subtitle Download & Sync
-
-Search and download subtitles from Jimaku, then retime them with alass or ffsubsync - all from within SubMiner.
+Search Jimaku, download a track, then retime it with alass or ffsubsync without leaving SubMiner.
 
 <!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/subtitle-sync-poster.jpg?v=${v}`)">
   <source :src="withBase(`/assets/demos/subtitle-sync.webm?v=${v}`)" type="video/webm" />
@@ -35,9 +34,9 @@ Search and download subtitles from Jimaku, then retime them with alass or ffsubs
 ::: info VIDEO COMING SOON
 :::
 
-## Jellyfin Integration
+## Jellyfin integration
 
-Browse your Jellyfin library, cast to devices, and launch playback directly from SubMiner. Watch progress syncs back to your Jellyfin server.
+Browse your Jellyfin library and play from SubMiner, or cast to SubMiner from another Jellyfin client. Watch progress syncs back to the 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" />
@@ -49,7 +48,7 @@ Browse your Jellyfin library, cast to devices, and launch playback directly from
 
 ## Texthooker
 
-Open subtitles in an external texthooker page for use with browser-based tools and extensions alongside the overlay.
+Mirror subtitles to an external texthooker page so browser extensions can read them while the overlay runs.
 
 <!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/texthooker-poster.jpg?v=${v}`)">
   <source :src="withBase(`/assets/demos/texthooker.webm?v=${v}`)" type="video/webm" />

docs-site/development.md

@@ -1,10 +1,12 @@
-# Building & Testing
+# Building and testing
 
-For internal architecture/workflow guidance, use `docs/README.md` at the repo root. This page stays focused on contributor-facing build and test commands.
+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).
 
 ## Prerequisites
 
-- [Bun](https://bun.sh)
+- [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.
 
 ## Setup
 
@@ -14,36 +16,20 @@ cd SubMiner
 make deps
 ```
 
-`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`.
+`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`.
 
-## Building
+## Build
 
 ```bash
-# Main app build
-bun run build
-
-# Platform packages
+bun run build               # app build, including bundled Yomitan from vendor/subminer-yomitan
 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
-
-# Optional launcher artifact only
-make build-launcher
-# output: dist/launcher/subminer
+make build-launcher         # launcher only, output: dist/launcher/subminer
 ```
 
-`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:
+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:
 
 ```bash
 make build-launcher
@@ -51,20 +37,21 @@ dist/launcher/subminer --help >/dev/null
 bash scripts/verify-generated-launcher.sh
 ```
 
-## Running Locally
+## Run locally
 
 ```bash
-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
+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
 ```
 
-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:
+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:
 
 ```json
 {
@@ -74,29 +61,9 @@ the mpv plugin at runtime:
 }
 ```
 
-## Testing
+## Test
 
-Default lanes:
-
-```bash
-bun run test           # alias for test:fast
-bun run test:fast      # default fast lane
-bun run test:full      # maintained source + launcher-unit + runtime compat surface
-bun run test:runtime:compat # compiled/runtime compatibility slice only
-bun run test:env       # launcher/plugin + env-sensitive verification
-bun run test:immersion:sqlite # SQLite persistence lane
-bun run test:subtitle  # maintained alass/ffsubsync subtitle surface
-```
-
-- `bun run test` and `bun run test:fast` cover config/core suites plus representative entry/runtime, Anki integration, release-workflow coverage, typecheck, and runtime-registry checks.
-- `bun run test:full` is the maintained full surface: Bun-compatible `src/**` discovery, Bun-compatible launcher unit discovery, and the compiled/runtime compatibility lane for suites routed through `dist/**`.
-- `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: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:
+Run the handoff gate before submitting substantial changes:
 
 ```bash
 bun run typecheck
@@ -106,142 +73,111 @@ bun run build
 bun run test:smoke:dist
 ```
 
-If you changed docs in `docs-site/`, also run:
+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
 
 ```bash
-bun run docs:test
-bun run docs:build
+make pretty               # format the maintained source and stats files
+bun run format:check:src  # check the same set without writing
 ```
 
-For production docs routing, run the versioned 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:
 
 ```bash
 bun run docs:build:versioned
 ```
 
-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.
+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/`.
 
-Focused commands:
+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.
 
-```bash
-bun run test:config       # Source-level config schema/validation tests
-bun run test:launcher     # Launcher regression tests (config discovery + command routing)
-bun run test:core         # Source-level core regression tests (default lane)
-bun run test:launcher:smoke:src # Launcher e2e smoke: launcher -> mpv IPC -> overlay start/stop wiring
-bun run test:launcher:env:src # Launcher smoke + Lua plugin gate
-bun run test:src          # Bun-managed maintained src/** discovery lane
-bun run test:launcher:unit:src # Bun-managed maintained launcher unit lane
-bun run test:immersion:sqlite:src # Bun source lane
-```
+## Makefile targets
 
-Dist-level tests are now an explicit smoke lane used to validate compiled/runtime assumptions.
-
-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
-bun run test:config:dist      # optional full dist config suite
-bun run test:core:dist        # optional full dist core suite
-```
-
-Use `bun run test:immersion:sqlite` when you need real DB-backed coverage for the immersion tracker.
-
-## Formatting
-
-Use the scoped formatter for normal app-repo work:
-
-```bash
-make pretty
-bun run format:check:src
-```
-
-- `make pretty` runs the maintained Prettier allowlist only (`format:src`).
-- `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
-```
-
-Cloudflare Pages deploy settings:
-
-- Git repo: `ksyasuda/SubMiner`
-- Root directory: `docs-site`
-- Build command: `bun run docs:build`
-- Build output directory: `.vitepress/dist`
-- Build watch paths: `docs-site/*`
-
-Use Cloudflare's single `*` wildcard syntax for watch paths. `docs-site/*` covers nested docs-site changes in the repo; `docs-site/**` is not the correct Pages pattern and may skip docs-only pushes.
-
-## Makefile Reference
-
-Run `make help` for a full list of targets. Key ones:
+Run `make help` for the full list.
 
 | Target                      | Description                                                  |
-| --------------------------- | ----------------------------------------------------------------- |
-| `make build`                | Build platform package for detected OS                            |
-| `make build-launcher`       | Generate Bun launcher wrapper at `dist/launcher/subminer`         |
-| `make install`              | Install platform artifacts (wrapper, theme, AppImage/app bundle)  |
-| `make deps`                 | 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                  |
+| --------------------------- | ------------------------------------------------------------ |
+| `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                                    |
 
-## Contributor Notes
+## Contributor notes
 
-- 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).
+- 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`.
 
-## Environment Variables
+## Environment variables
 
 | Variable                           | Description                                                      |
-| ---------------------------------- | ------------------------------------------------------------------------------ |
-| `SUBMINER_APPIMAGE_PATH`           | Override SubMiner app binary path for launcher playback commands               |
+| ---------------------------------- | ---------------------------------------------------------------- |
+| `SUBMINER_APPIMAGE_PATH`           | SubMiner app binary the launcher uses for playback               |
 | `SUBMINER_BINARY_PATH`             | Alias for `SUBMINER_APPIMAGE_PATH`                               |
-| `SUBMINER_ROFI_THEME`              | Override rofi theme path for launcher picker                                   |
-| `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`     |
+| `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_JIMAKU_API_KEY`          | Jimaku API key for launcher subtitle downloads                   |
+| `SUBMINER_JIMAKU_API_KEY_COMMAND`  | Command that prints the Jimaku API key                           |
+| `SUBMINER_JIMAKU_API_BASE_URL`     | Jimaku API base URL                                              |
+| `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` |

docs-site/docs-sync.test.ts

@@ -8,12 +8,15 @@ 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',
 );
 const configurationContents = readFileSync(new URL('./configuration.md', import.meta.url), 'utf8');
+const troubleshootingContents = readFileSync(
+  new URL('./troubleshooting.md', import.meta.url),
+  'utf8',
+);
 
 function extractReleaseHeadings(content: string, count: number): string[] {
   return Array.from(content.matchAll(/^## v[^\n]+$/gm))
@@ -53,18 +56,48 @@ test('docs reflect current launcher and release surfaces', () => {
   expect(configurationContents).not.toContain('youtubeSubgen": {\n    "mode"');
   expect(configurationContents).not.toContain('youtubeSubgen.primarySubLanguages');
   expect(configurationContents).toContain('youtube.primarySubLanguages');
-  expect(configurationContents).toContain('### Shared AI Provider');
+  // The AI provider still exists in src/ai and ankiConnect.ai, but it is not
+  // exposed in the Settings window and is not documented for users. Keep the
+  // user-facing docs free of it so nobody configures a hidden surface.
+  expect(configurationContents).not.toContain('Shared AI Provider');
+  expect(configurationContents).not.toContain('ankiConnect.ai');
+  expect(ankiIntegrationContents).not.toContain('AI Translation');
+  // ankiConnect.fields.translation is a LEGACY_HIDDEN_CONFIG_PATHS key, so it
+  // must not be documented as a current setting.
+  expect(configurationContents).not.toContain('fields.translation');
+  expect(ankiIntegrationContents).not.toContain('SelectionText');
+  // fields.audio holds SubMiner's generated sentence audio; examples should not
+  // point it at the field Yomitan uses for word audio.
+  expect(ankiIntegrationContents).not.toContain('"audio": "ExpressionAudio"');
 
   expect(changelogContents).toContain('v0.5.1 (2026-03-09)');
 });
 
-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 document config surfaces that are easy to miss when they ship', () => {
+  // Anki maturity-based known-word highlighting (#172) landed in
+  // subtitle-annotations.md but was missing from the config reference.
+  expect(configurationContents).toContain('ankiConnect.knownWords.maturityEnabled');
+  expect(configurationContents).toContain('ankiConnect.knownWords.matureThresholdDays');
+
+  // Every top-level config block should be reachable from the config reference.
+  expect(configurationContents).toContain('### TsukiHime');
+  expect(configurationContents).toContain('tsukihime.maxSearchResults');
+
+  // xz is a hard runtime dependency of the TsukiHime download path.
+  expect(installationContents).toContain('xz');
+});
+
+test('docs state the real secondary-subtitle and Anki field-matching behavior', () => {
+  // secondarySub auto-load is off by default; the config example previously
+  // implied otherwise while youtube-integration.md documented it correctly.
+  expect(configurationContents).toContain('Secondary subtitles do **not** auto-load by default');
+  expect(configurationContents).toContain('default: `false`');
+
+  // Anki field names are matched case-insensitively (src/anki-integration.ts
+  // resolveFieldName: exact match first, then a lowercase comparison).
+  expect(usageContents).not.toContain('exactly (case-sensitive)');
+  expect(troubleshootingContents).not.toContain('exactly (case-sensitive)');
+  expect(ankiIntegrationContents).toContain('case-insensitively');
 });
 
 test('docs changelog keeps the current minor release headings aligned with the root changelog', () => {

docs-site/functions/v/[[path]].ts

@@ -0,0 +1,212 @@
+// Cloudflare Pages Function serving frozen `/v/<version>/` doc archives from R2.
+// Archives are uploaded by scripts/build-versioned-docs.ts and never ship in the Pages
+// deployment itself, so they do not count toward the Pages file limit. Requires an R2
+// binding named DOCS_ARCHIVES on the Pages project (see docs-site/README.md).
+
+// Minimal slice of the Workers R2 API used here; avoids a workers-types dependency.
+type R2Range = { offset: number; length?: number } | { suffix: number };
+
+type R2ObjectMeta = {
+  size: number;
+  httpEtag: string;
+  range?: R2Range;
+};
+
+type R2ObjectBody = R2ObjectMeta & { body: ReadableStream };
+
+type R2GetOptions = { range?: Headers; onlyIf?: Headers };
+
+export type ArchiveBucket = {
+  get(key: string, options?: R2GetOptions): Promise<R2ObjectMeta | R2ObjectBody | null>;
+};
+
+type ArchiveContext = {
+  request: Request;
+  env: { DOCS_ARCHIVES: ArchiveBucket };
+};
+
+export type ArchiveRoute =
+  | { kind: 'redirect'; location: string; status: 301 | 302 }
+  | { kind: 'lookup'; version: string; keys: string[] }
+  | { kind: 'not-found' };
+
+const CONTENT_TYPES: Record<string, string> = {
+  css: 'text/css; charset=utf-8',
+  gif: 'image/gif',
+  html: 'text/html; charset=utf-8',
+  ico: 'image/x-icon',
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  js: 'text/javascript; charset=utf-8',
+  json: 'application/json; charset=utf-8',
+  jsonc: 'application/json; charset=utf-8',
+  mjs: 'text/javascript; charset=utf-8',
+  mkv: 'video/x-matroska',
+  mp4: 'video/mp4',
+  png: 'image/png',
+  svg: 'image/svg+xml',
+  ttf: 'font/ttf',
+  txt: 'text/plain; charset=utf-8',
+  webm: 'video/webm',
+  webp: 'image/webp',
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+  xml: 'application/xml; charset=utf-8',
+};
+
+function extensionOf(path: string): string | null {
+  const name = path.slice(path.lastIndexOf('/') + 1);
+  const dot = name.lastIndexOf('.');
+  return dot > 0 ? name.slice(dot + 1).toLowerCase() : null;
+}
+
+function contentTypeFor(key: string): string {
+  return CONTENT_TYPES[extensionOf(key) ?? ''] ?? 'application/octet-stream';
+}
+
+// Maps a request path onto candidate R2 keys, mirroring the Pages clean-URL rules the
+// archives were built for (`cleanUrls: true`).
+export function resolveArchiveRoute(pathname: string, search = ''): ArchiveRoute {
+  if (pathname === '/v' || pathname === '/v/') {
+    return { kind: 'redirect', location: '/versions', status: 302 };
+  }
+
+  const match = /^\/v\/(\d+\.\d+\.\d+)(\/.*)?$/.exec(pathname);
+  if (!match) return { kind: 'not-found' };
+
+  const version = match[1]!;
+  const rest = match[2];
+  if (!rest) {
+    return { kind: 'redirect', location: `/v/${version}/${search}`, status: 301 };
+  }
+
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(rest);
+  } catch {
+    return { kind: 'not-found' };
+  }
+  if (decoded.split('/').some((segment) => segment === '..' || segment === '.')) {
+    return { kind: 'not-found' };
+  }
+
+  const prefix = `v/${version}`;
+  const path = `${prefix}${decoded}`;
+  const keys = decoded.endsWith('/')
+    ? [`${path}index.html`]
+    : extensionOf(decoded)
+      ? [path]
+      : [`${path}.html`, `${path}/index.html`];
+
+  return { kind: 'lookup', version, keys };
+}
+
+function cacheControlFor(key: string): string {
+  // VitePress content-hashes everything it emits under assets/.
+  if (/\/assets\//.test(key) && extensionOf(key) !== 'html') {
+    return 'public, max-age=31536000, immutable';
+  }
+  return 'public, max-age=3600';
+}
+
+function hasBody(object: R2ObjectMeta | R2ObjectBody): object is R2ObjectBody {
+  return 'body' in object && object.body !== undefined;
+}
+
+function contentRange(range: R2Range, size: number): { start: number; end: number } {
+  if ('suffix' in range) {
+    const length = Math.min(range.suffix, size);
+    return { start: size - length, end: size - 1 };
+  }
+  const length = range.length ?? size - range.offset;
+  return { start: range.offset, end: range.offset + length - 1 };
+}
+
+async function respondWithObject(options: {
+  request: Request;
+  bucket: ArchiveBucket;
+  key: string;
+  status: number;
+}): Promise<Response | null> {
+  const { request, bucket, key } = options;
+  // Ranges and conditional requests only make sense for the page that was asked for,
+  // not the 404 fallback.
+  const isRequestedObject = options.status === 200;
+  const wantsRange = isRequestedObject && request.headers.has('range');
+
+  let object: R2ObjectMeta | R2ObjectBody | null;
+  try {
+    object = await bucket.get(key, {
+      range: wantsRange ? request.headers : undefined,
+      onlyIf: isRequestedObject ? request.headers : undefined,
+    });
+  } catch {
+    // R2 rejects unsatisfiable ranges.
+    return new Response(null, { status: 416 });
+  }
+  if (!object) return null;
+
+  const headers = new Headers({
+    'Content-Type': contentTypeFor(key),
+    'Cache-Control': cacheControlFor(key),
+    ETag: object.httpEtag,
+    'Accept-Ranges': 'bytes',
+    'X-Robots-Tag': 'noindex, follow',
+  });
+
+  // R2 returns the object without a body when an If-None-Match/If-Modified-Since
+  // precondition matched.
+  if (!hasBody(object)) {
+    return new Response(null, { status: 304, headers });
+  }
+
+  let status = options.status;
+  if (wantsRange && object.range) {
+    const { start, end } = contentRange(object.range, object.size);
+    status = 206;
+    headers.set('Content-Range', `bytes ${start}-${end}/${object.size}`);
+    headers.set('Content-Length', String(end - start + 1));
+  } else {
+    headers.set('Content-Length', String(object.size));
+  }
+
+  return new Response(request.method === 'HEAD' ? null : object.body, { status, headers });
+}
+
+export async function onRequest({ request, env }: ArchiveContext): Promise<Response> {
+  if (request.method !== 'GET' && request.method !== 'HEAD') {
+    return new Response('Method Not Allowed', { status: 405, headers: { Allow: 'GET, HEAD' } });
+  }
+
+  const url = new URL(request.url);
+  const route = resolveArchiveRoute(url.pathname, url.search);
+
+  if (route.kind === 'redirect') {
+    return Response.redirect(new URL(route.location, url).toString(), route.status);
+  }
+
+  if (route.kind === 'lookup') {
+    for (const key of route.keys) {
+      const response = await respondWithObject({
+        request,
+        bucket: env.DOCS_ARCHIVES,
+        key,
+        status: 200,
+      });
+      if (response) return response;
+    }
+
+    const notFoundPage = await respondWithObject({
+      request,
+      bucket: env.DOCS_ARCHIVES,
+      key: `v/${route.version}/404.html`,
+      status: 404,
+    });
+    if (notFoundPage) return notFoundPage;
+  }
+
+  return new Response('Not Found', {
+    status: 404,
+    headers: { 'Content-Type': 'text/plain; charset=utf-8', 'X-Robots-Tag': 'noindex, follow' },
+  });
+}

docs-site/immersion-tracking.md

@@ -1,18 +1,19 @@
-# Immersion Tracking
+# Immersion tracking
 
-SubMiner can log your watching and mining activity to a local SQLite database, then surface it in the built-in stats dashboard. Tracking is enabled by default and can be turned off if you do not want local analytics.
+SubMiner records what you watch and mine in a local SQLite database and shows it in a stats dashboard. Tracking is on by default. Nothing leaves your machine.
 
-"Immersion" here means time spent watching and reading native Japanese content. **All data stays on your computer** - nothing is uploaded anywhere. (SQLite is just a single-file database; you do not need to install or manage anything.)
+## What gets tracked
 
-When enabled, SubMiner records per-session statistics (watch time, subtitle lines seen, words encountered, cards mined) and maintains exact lifetime summary tables plus daily/monthly rollups. You can view that data in SubMiner's stats UI or query the database directly with any SQLite tool.
+- Watch sessions: time watched, subtitle lines seen, words seen, cards mined, pauses and seeks.
+- Every primary subtitle line you see, with its timing, so you can search and mine from it later.
+- Vocabulary and kanji you encounter, with how often and where.
+- Library entries per show and episode, with cover art from AniList (or TMDB for live action) and YouTube channel metadata.
 
-::: tip For most users
-Just leave tracking on and use the built-in [Stats Dashboard](#stats-dashboard). The retention, performance, SQL, and schema sections further down are reference material for advanced users who want to inspect or tune the database - you can safely skip them.
-:::
+An episode counts as watched once you reach 85% of it.
 
-Episode completion for local `watched` state uses the shared `DEFAULT_MIN_WATCH_RATIO` (`85%`) value from `src/shared/watch-threshold.ts`.
+## Setup
 
-## Enabling
+Tracking needs no setup. To turn it off or move the database:
 
 ```jsonc
 {
@@ -23,298 +24,106 @@ Episode completion for local `watched` state uses the shared `DEFAULT_MIN_WATCH_
 }
 ```
 
-- Leave `dbPath` empty to use the default location (`immersion.sqlite` in SubMiner's app-data directory).
-- Set an explicit path to move the database (useful for backups, cloud syncing, or external tools).
+An empty `dbPath` stores `immersion.sqlite` in SubMiner's config directory (`~/.config/SubMiner/` on Linux). Set a path to keep it elsewhere.
 
-## Stats Dashboard
+To share stats and watch history between machines, use [`subminer sync <host>`](/launcher-script#sync-between-machines). It merges both databases. Copying the file with a cloud sync tool makes one side overwrite the other.
 
-The same immersion data powers the stats dashboard.
+## Open the dashboard
 
-- In-app overlay: focus the visible overlay, then press the key from `stats.toggleKey` (default: `` ` `` / `Backquote`).
-- Launcher command: run `subminer stats` to start the local stats server on demand and open the dashboard in your browser.
-- Background server: run `subminer stats -b` to start or reuse a dedicated background stats daemon without keeping the launcher attached, and `subminer stats -s` to stop that daemon.
-- Maintenance command: run `subminer stats cleanup` or `subminer stats cleanup -v` to backfill/repair vocabulary metadata (`headword`, `reading`, POS) and purge stale or excluded rows from `imm_words` on demand.
-- Browser page: open `http://127.0.0.1:6969` directly if the local stats server is already running.
+- In the overlay: focus it and press the `stats.toggleKey` key (Backquote by default).
+- In a browser: run `subminer stats`, then open `http://127.0.0.1:6969` (or your `stats.serverPort`). Set `stats.autoOpenBrowser` to open it automatically.
+- Background server: `subminer stats -b` starts a stats server that keeps running without the launcher attached. `subminer stats -s` stops it. You can still start SubMiner for playback while it runs.
 
-### Dashboard Tabs
+`subminer stats` fails if `immersionTracking.enabled` is `false`. The server only answers on localhost, so reverse proxies and Tailscale Serve URLs do not work.
 
-#### Overview
+## Stats dashboard
 
-Recent sessions, streak calendar, watch-time history, and a tracking snapshot with completed episodes/anime totals.
+### Overview
+
+Recent sessions, a streak calendar, watch-time history, and totals for completed episodes and shows.
+
+Deleting a session or session group refreshes the Overview totals, charts, calendar, and vocabulary summary automatically. If a refresh fails, Overview keeps the previous totals visible and offers **Retry**.
 
 ![Stats Overview](/screenshots/stats-overview.png)
 
-#### Library
+### Library
 
-Cover-art library with search and sorting, per-series progress, episode drill-down, and direct links into mined cards.
+Your shows as cover-art cards with search, sorting, per-series progress, and an episode list linking to mined cards. The **All Titles** / **Anime** / **Live Action** / **YouTube** selector filters the grid. YouTube videos are grouped by channel.
 
-Local files and Jellyfin items with detected season numbers are split into season-specific library entries, so `Season 1` and `Season 2` folders do not merge into one show card.
+Seasons get separate cards when a season number is detected. Live-action titles that AniList cannot match are looked up on [TMDB](/configuration#tmdb). If a title gets no match, open it and use **Link to TMDB** to pick one by hand.
 
-When older stats already grouped multiple seasons under one series entry, SubMiner moves parsed episodes into the season-specific entries on startup and rebuilds the affected summaries.
+The same show can end up on several cards when release names disagree. To fix that:
 
-Jellyfin stream URLs are normalized to stable item links before stats titles are shown, so playback query parameters are not displayed in the dashboard.
+- Merge: click **Select**, tick the duplicate cards, choose **Merge Selected**, and pick the entry to keep. Sessions, cards, and watch time move over, and future episodes with those names join the kept entry.
+- Move one episode: hover its row in the episode list and click **→** to assign it to another entry. SubMiner remembers the correction.
+- Suggested merges appear as **Possible duplicate** above the grid. Choose **Review merge** or **Not duplicates**.
 
-When YouTube channel metadata is available, the Library tab groups videos by creator/channel and treats each tracked video as an episode-like entry inside that channel section.
+**Delete Entry** in a title's header removes the show with all its episodes, sessions, and lines. You cannot delete the title that is currently playing.
 
 ![Stats Library](/screenshots/stats-library.png)
 
-#### Trends
+### Trends
 
-Grouped into Activity (per-day/month watch time, cards, words, sessions), Cumulative Totals (running totals incl. new words seen and episodes), Efficiency (words/min, cards/hour, lookups per 100 words), Patterns (watch time by day of week and hour), and per-anime Library charts — all with configurable date ranges and grouping.
+Charts for watch time, cards, words, and sessions per day or month, running totals, efficiency (words per minute, cards per hour), and viewing patterns by weekday and hour. Each chart has its own date range and grouping.
 
 ![Stats Trends](/screenshots/stats-trends.png)
 
-#### Sessions
+### Sessions
 
-Expandable session history with new-word activity, cumulative totals, and pause/seek/card markers. Each session row exposes a hover-revealed ↗ button that navigates to the anime media-detail view for that session; pressing the back button there returns to the Sessions tab.
+Session history with new-word activity and pause, seek, and card markers. The **↗** button on a row opens that show's detail view.
 
 ![Stats Sessions](/screenshots/stats-sessions.png)
 
-#### Vocabulary
+### Vocabulary
 
-Top repeated words (click a bar to open the word), new-word timeline, cross-title and frequency rank tables with Hide Known / Hide Kana filters, kanji breakdown, word exclusion list, and click-through occurrence drilldown with Mine Word / Mine Sentence / Mine Audio buttons.
+Unique words and kanji you have seen, new words per day, frequency rank tables with Hide Known and Hide Kana filters, and a kanji breakdown. Click a word to see every line it appeared in.
+
+- **Exclusions** hides words from every vocabulary view. You can restore them from the same dialog.
+- **Duplicates** cleans up lines repeated by karaoke openings and animated signs (see [Repeated lines](#repeated-lines)).
 
 ![Stats Vocabulary](/screenshots/stats-vocabulary.png)
 
-#### Search
+### Search
 
-Realtime search across tracked primary subtitle lines and media titles. Results show the source media, session, line number, timing, and sentence text. Secondary subtitle text is not shown or searched here because separate subtitle tracks may not line up sentence-for-sentence. Sentence cards can be mined from any result with a valid local source and timing. Word and audio card buttons appear only when the searched word exactly appears in the primary sentence text; matching text is highlighted in the result.
+Searches the primary subtitle lines and titles in your history. **Search by headword** is on by default, so `知らない` also finds inflected forms. Turn it off for exact text matching. Secondary subtitles are not searched.
 
-Stats server config lives under `stats`:
+## Mining from the dashboard
 
-```jsonc
-{
-  "stats": {
-    "toggleKey": "Backquote",
-    "serverPort": 6969,
-    "autoStartServer": true,
-    "autoOpenBrowser": false,
-  },
-}
+Search results and the Vocabulary word panel can create cards from past lines, as long as the source video file is still available:
+
+- **Mine Word**: full Yomitan lookup for the word, plus sentence, audio, and image.
+- **Mine Sentence**: a sentence card with `IsSentenceCard` set, for Lapis and Kiku note types.
+- **Mine Audio**: an audio card with `IsAudioCard` set.
+
+Word and audio mining appear only when the word occurs in the sentence. All three use your `ankiConnect` deck, note type, fields, and media settings. Anki must be running, and Mine Word needs Yomitan dictionaries.
+
+## Repeated lines
+
+Karaoke openings and animated signs repeat the same text once per frame. SubMiner collapses these as it records, so one lyric is stored once. Stats recorded before that can hold hundreds of copies and skew Top Repeated Words.
+
+To clean them, use **Duplicates** in the Vocabulary tab: pick a time window, **Scan** to preview, then **Clean Up**. Or from the terminal:
+
+```bash
+subminer stats cleanup --duplicate-lines --dry-run --lookback-days 30
+subminer stats cleanup --duplicate-lines --lookback-days 30
 ```
 
-- `toggleKey` is overlay-local, not a system-wide shortcut.
-- `serverPort` controls the localhost dashboard URL.
-- `autoStartServer` starts the local stats HTTP server on launch once immersion tracking is active, or reuses the dedicated background stats server when one is already running.
-- `autoOpenBrowser` controls whether `subminer stats` launches the dashboard URL in your browser after ensuring the server is running.
-- `subminer stats` forces the dashboard server to start even when `autoStartServer` is `false`.
-- `subminer stats -b` starts or reuses the dedicated background stats daemon and exits after startup acknowledgement.
-- The background stats daemon is separate from the normal SubMiner overlay app, so you can leave it running and still launch SubMiner later to watch or mine from video.
-- `subminer stats -s` stops the dedicated background stats daemon without closing any browser tabs.
-- `subminer stats` fails with an error when `immersionTracking.enabled` is `false`.
-- `subminer stats cleanup` defaults to vocabulary cleanup, repairs stale `headword`, `reading`, and `part_of_speech` values, attempts best-effort MeCab backfill for legacy rows, and removes rows that still fail vocab filtering.
+Leave out `--lookback-days` to scan all history. Word and kanji counts are corrected. Watch time and session totals are not changed.
 
-## Mining Cards from the Stats Page
+## Maintenance commands
 
-The Search tab and the Vocabulary tab's word detail panel both mine from subtitle lines in your viewing history. Search matches sentence text and media titles, and **Search by headword** is enabled by default so dictionary-form searches such as `知らない` can find tracked subtitle lines with inflected variants. Turn that toggle off for exact text/title matching only. Each line with a valid source file offers sentence-card mining; word/audio mining is available when the selected word or searched word appears in the sentence:
+| Command                                    | What it does                                                              |
+| ------------------------------------------ | ------------------------------------------------------------------------- |
+| `subminer stats cleanup`                   | Repair word readings and part of speech, drop words that fail the filters |
+| `subminer stats cleanup -l`                | Recompute lifetime totals from episode history, keeping old totals        |
+| `subminer stats cleanup --duplicate-lines` | Collapse repeated karaoke and sign lines (see above)                      |
 
-- **Mine Word** - performs a full Yomitan dictionary lookup for the word (definition, reading, pitch accent, etc.) via a short-lived hidden helper, then enriches the card with sentence audio, a screenshot or animated AVIF clip, the highlighted sentence, and metadata extracted from the source video file. Requires Anki and Yomitan dictionaries to be loaded.
-- **Mine Sentence** - creates a sentence card directly with the `IsSentenceCard` flag set (for Lapis/Kiku workflows), along with audio and image from the source video.
-- **Mine Audio** - creates an audio-only card with the `IsAudioCard` flag, attaching only the sentence audio clip.
+`subminer stats rebuild` and `subminer stats backfill` run the same lifetime repair as `cleanup -l`.
 
-All three modes respect your `ankiConnect` config: deck, model, field mappings, media settings (static vs AVIF, quality, dimensions), audio padding, metadata pattern, and tags. Media generation runs in parallel for faster card creation.
+## Retention
 
-Secondary subtitle text (typically English translations) is stored alongside primary subtitles during playback and can be used as the translation field when mining sentence cards from Search or vocabulary occurrences. The Search tab does not use that text for display or matching.
+By default SubMiner keeps everything. To limit history, set `immersionTracking.retentionPreset` to `minimal`, `balanced`, or `deep-history`, or set the `immersionTracking.retention.*Days` values yourself (`0` keeps all). Lifetime totals and vocabulary counts are stored separately and stay exact when old sessions are pruned.
 
-### Word Exclusion List
+Deleting retained sessions preserves earlier word and kanji discovery dates from pruned history. New occurrences record observation time so deletion can update their dates exactly. Older history used write time, so an earlier discovery date is preserved when its origin cannot be determined.
 
-The Vocabulary tab toolbar includes an **Exclusions** button for hiding words from all vocabulary views. Excluded words are stored in the immersion database, with older browser localStorage exclusions imported on first load after upgrade. They can be managed (restored or cleared) from the exclusion modal. Exclusions affect stat cards, charts, the frequency rank table, and the word list.
-
-## Retention Defaults
-
-By default, SubMiner keeps all retention tables and raw data (`0` means keep all) while continuing daily/monthly rollup maintenance:
-
-| Data type       | Retention    |
-| --------------- | ------------ |
-| Raw events      | 0 (keep all) |
-| Telemetry       | 0 (keep all) |
-| Sessions        | 0 (keep all) |
-| Daily rollups   | 0 (keep all) |
-| Monthly rollups | 0 (keep all) |
-
-Maintenance runs on startup and every 24 hours. Vacuum runs only when `retention.vacuumIntervalDays` is non-zero.
-
-In practice:
-
-- Overview totals read from lifetime summary tables, so all-time watch time/cards/words stay exact even if raw query paths evolve.
-- Anime and episode pages keep lifetime totals from summary tables while session drill-down still reads retained sessions directly. With the current defaults, both are kept forever.
-- Trends can read the full available history because daily/monthly rollups are also kept forever by default.
-- Vocabulary and kanji totals are cumulative and not bounded by the raw session retention knobs.
-
-## Storage / Performance Model
-
-The tracker is optimized for "keep everything" defaults:
-
-- Exact all-time totals live in dedicated lifetime summary tables (`imm_lifetime_global`, `imm_lifetime_anime`, `imm_lifetime_media`).
-- Ended-session totals are persisted onto `imm_sessions`, so most dashboard reads do not need to rescan raw telemetry.
-- Daily and monthly rollups remain available for chart queries and coarse trend views.
-- Subtitle text is stored once in `imm_subtitle_lines`; subtitle-line event payloads keep compact metadata only.
-- Cover-art binaries are deduplicated through a shared blob store so episodes in the same series do not each carry duplicate image bytes.
-- Hot tables have dedicated indexes for session time ranges, telemetry sample windows, frequency-ranked vocabulary, and cover-art lookup keys.
-
-## Configurable Knobs
-
-All policy options live under `immersionTracking` in your config:
-
-| Option                         | Description                                                        |
-| ------------------------------ | ------------------------------------------------------------------ |
-| `batchSize`                    | Writes per flush batch                                             |
-| `flushIntervalMs`              | Max delay between flushes (default: 500ms)                         |
-| `queueCap`                     | Max queued writes before oldest are dropped                        |
-| `payloadCapBytes`              | Max payload size per write                                         |
-| `maintenanceIntervalMs`        | How often maintenance runs                                         |
-| `retention.eventsDays`         | Raw event retention                                                |
-| `retention.telemetryDays`      | Telemetry retention                                                |
-| `retention.sessionsDays`       | Session retention                                                  |
-| `retention.dailyRollupsDays`   | Daily rollup retention                                             |
-| `retention.monthlyRollupsDays` | Monthly rollup retention                                           |
-| `retention.vacuumIntervalDays` | Minimum spacing between vacuums                                    |
-| `retentionMode`                | `preset` or `advanced`                                             |
-| `retentionPreset`              | `minimal`, `balanced`, or `deep-history` (used by `retentionMode`) |
-| `lifetimeSummaries.global`     | Maintain global lifetime totals                                    |
-| `lifetimeSummaries.anime`      | Maintain per-anime lifetime totals                                 |
-| `lifetimeSummaries.media`      | Maintain per-media lifetime totals                                 |
-
-## Query Templates
-
-### Session timeline
-
-```sql
-SELECT
-  sample_ms,
-  total_watched_ms,
-  active_watched_ms,
-  lines_seen,
-  words_seen,
-  tokens_seen,
-  cards_mined
-FROM imm_session_telemetry
-WHERE session_id = ?
-ORDER BY sample_ms DESC, telemetry_id DESC
-LIMIT ?;
-```
-
-### Session throughput summary
-
-```sql
-SELECT
-  s.session_id,
-  s.video_id,
-  s.started_at_ms,
-  s.ended_at_ms,
-  COALESCE(s.active_watched_ms, 0) AS active_watched_ms,
-  COALESCE(s.words_seen, 0) AS words_seen,
-  COALESCE(s.cards_mined, 0) AS cards_mined,
-  CASE
-    WHEN COALESCE(s.active_watched_ms, 0) > 0
-      THEN COALESCE(s.words_seen, 0) / (COALESCE(s.active_watched_ms, 0) / 60000.0)
-    ELSE NULL
-  END AS words_per_min,
-  CASE
-    WHEN COALESCE(s.active_watched_ms, 0) > 0
-      THEN (COALESCE(s.cards_mined, 0) * 60.0) / (COALESCE(s.active_watched_ms, 0) / 60000.0)
-    ELSE NULL
-  END AS cards_per_hour
-FROM imm_sessions s
-ORDER BY s.started_at_ms DESC
-LIMIT ?;
-```
-
-### Lifetime anime totals
-
-```sql
-SELECT
-  a.anime_id,
-  a.canonical_title,
-  la.total_sessions,
-  la.total_active_ms,
-  la.total_cards,
-  la.total_words_seen,
-  la.total_lines_seen,
-  la.first_watched_ms,
-  la.last_watched_ms
-FROM imm_lifetime_anime la
-JOIN imm_anime a ON a.anime_id = la.anime_id
-ORDER BY la.last_watched_ms DESC
-LIMIT ?;
-```
-
-### Daily rollups
-
-```sql
-SELECT
-  rollup_day,
-  video_id,
-  total_sessions,
-  total_active_min,
-  total_lines_seen,
-  total_words_seen,
-  total_tokens_seen,
-  total_cards,
-  cards_per_hour,
-  words_per_min,
-  lookup_hit_rate
-FROM imm_daily_rollups
-ORDER BY rollup_day DESC, video_id DESC
-LIMIT ?;
-```
-
-### Monthly rollups
-
-```sql
-SELECT
-  rollup_month,
-  video_id,
-  total_sessions,
-  total_active_min,
-  total_lines_seen,
-  total_words_seen,
-  total_tokens_seen,
-  total_cards
-FROM imm_monthly_rollups
-ORDER BY rollup_month DESC, video_id DESC
-LIMIT ?;
-```
-
-## Technical Details
-
-- Write path is asynchronous and queue-backed. Hot paths (subtitle parsing, render, token flows) enqueue telemetry and never await SQLite writes.
-- Queue overflow policy: drop oldest queued writes, keep newest.
-- SQLite tunings: `journal_mode=WAL`, `synchronous=NORMAL`, `foreign_keys=ON`, `busy_timeout=2500`, bounded WAL growth via `journal_size_limit`.
-- Maintenance executes `PRAGMA optimize` after periodic cleanup.
-- Rollups run incrementally from the last processed telemetry sample; startup performs a one-time bootstrap pass.
-- Cover-art blobs are deduplicated into `imm_cover_art_blobs` and referenced from `imm_media_art`.
-- Large-table reads are index-backed for `sample_ms`, session time windows, frequency-ranked words/kanji, and cover-art identity lookups.
-- Workload-dependent tuning knobs remain at defaults unless you change them: `cache_size`, `mmap_size`, `temp_store`, `auto_vacuum`.
-
-### Schema (v4)
-
-Core tables:
-
-- `imm_videos` - video key/title/source metadata
-- `imm_sessions` - session UUID, video reference, timing/status, final denormalized totals
-- `imm_session_telemetry` - high-frequency session aggregates over time
-- `imm_session_events` - event stream with compact numeric event types
-- `imm_subtitle_lines` - persisted subtitle text and timing per session/video
-
-Lifetime summary tables:
-
-- `imm_lifetime_global`
-- `imm_lifetime_anime`
-- `imm_lifetime_media`
-- `imm_lifetime_applied_sessions`
-
-Rollup tables:
-
-- `imm_daily_rollups`
-- `imm_monthly_rollups`
-
-Vocabulary tables:
-
-- `imm_words(id, headword, word, reading, first_seen, last_seen, frequency)`
-- `imm_kanji(id, kanji, first_seen, last_seen, frequency)`
-
-Media-art tables:
-
-- `imm_media_art` - per-video cover metadata plus shared blob reference
-- `imm_cover_art_blobs` - deduplicated image bytes keyed by blob hash
+See [Immersion tracking](/configuration#immersion-tracking) and [Stats dashboard](/configuration#stats-dashboard) in the config reference for every option and default.

docs-site/index.md

@@ -7,7 +7,7 @@ titleTemplate: Immersion Mining Workflow for MPV
 hero:
   name: SubMiner
   text: Immersion Mining for MPV
-  tagline: Watch media, mine vocabulary, and craft anki cards without leaving the scene.
+  tagline: Watch, look up a word, and get an Anki card with audio and a screenshot. Without pausing your show.
   image:
     src: /assets/SubMiner.png
     alt: SubMiner logo
@@ -24,63 +24,63 @@ features:
       src: /assets/mpv.svg
       alt: mpv icon
     title: Built for mpv
-    details: Tracks subtitles via mpv IPC in real time. Launch with the wrapper script or the mpv plugin - no external bridge needed.
+    details: Reads subtitle state over mpv's IPC socket. Launch with the wrapper script or the mpv plugin. There is no separate bridge process to run.
     link: /usage
     linkText: How it works
   - icon:
       src: /assets/yomitan-icon.svg
       alt: Yomitan logo
     title: Bundled Yomitan
-    details: Ships with a built-in Yomitan instance for instant word lookups and context-aware card creation directly from subtitle text.
+    details: A Yomitan instance is bundled and preconfigured. Hover a word in the subtitle overlay to look it up and mine it.
     link: /mining-workflow
     linkText: Mining workflow
   - icon:
       src: /assets/anki-card.svg
       alt: Anki card icon
-    title: Anki Card Enrichment
-    details: Auto-fills card fields with sentence, audio clip, screenshot, and translation so you can focus on learning.
+    title: Anki card enrichment
+    details: New cards get the subtitle line, an audio clip cut to the line timing, and a screenshot from that moment.
     link: /anki-integration
     linkText: Anki integration
   - icon:
       src: /assets/highlight.svg
       alt: Highlight icon
-    title: Reading Annotations
-    details: N+1 targeting, character-name matching, frequency highlighting, and JLPT tagging - all layered on subtitle text in real time.
+    title: Reading annotations
+    details: N+1 targeting, character-name matching, frequency highlighting, and JLPT tagging, drawn onto the subtitle line as it plays.
     link: /subtitle-annotations
     linkText: Annotation details
   - icon:
       src: /assets/video.svg
       alt: Video playback icon
-    title: YouTube Playback
-    details: Play YouTube URLs or ytsearch targets directly - SubMiner automatically selects and loads subtitles for the video.
+    title: YouTube playback
+    details: Pass a YouTube URL or a ytsearch target. SubMiner picks a subtitle track for the video and loads it.
     link: /usage#youtube-playback
     linkText: YouTube playback
   - icon:
       src: /assets/jellyfin.svg
       alt: Jellyfin icon
-    title: Jellyfin Integration
-    details: Browse your Jellyfin library, pick media interactively, and play through mpv with full subtitle and mining support.
+    title: Jellyfin integration
+    details: Browse your Jellyfin library from the overlay and play a title through mpv. Subtitles and mining work the same as with local files.
     link: /jellyfin-integration
     linkText: Jellyfin setup
   - icon:
       src: /assets/subtitle-download.svg
       alt: Subtitle download icon
-    title: Subtitle Download & Sync
-    details: Search and pull subtitles from Jimaku, then retime subtitles with alass or ffsubsync - all from the overlay.
+    title: Subtitle download and sync
+    details: Search Jimaku or TsukiHime and download a track, then retime it with alass or ffsubsync. Both run from the overlay.
     link: /jimaku-integration
     linkText: Jimaku integration
   - icon:
       src: /assets/tokenization.svg
       alt: Tracking chart icon
-    title: Stats Dashboard
-    details: Browse session history, streak calendars, vocabulary frequency, and per-series progress in a local dashboard - then mine cards straight from your viewing history.
+    title: Stats dashboard
+    details: A local dashboard with session history, streak calendars, word frequency, and per-series progress. You can mine cards from lines you already watched.
     link: /immersion-tracking
     linkText: Dashboard & tracking
   - icon:
       src: /assets/cross-platform.svg
       alt: Cross-platform icon
-    title: Cross-Platform
-    details: Runs on Linux (Hyprland, Sway, X11), macOS, and Windows with compositor-aware window positioning and platform-native integration.
+    title: Cross-platform
+    details: Runs on Linux (Hyprland, Sway, X11), macOS, and Windows. Overlay positioning is handled per compositor rather than assuming one window manager.
     link: /installation
     linkText: Platform setup
 ---
@@ -88,7 +88,7 @@ features:
 <script setup>
 import { withBase } from 'vitepress';
 
-const demoAssetVersion = '20260223-2';
+const demoAssetVersion = '20260819-1';
 </script>
 
 <div class="landing-shell">
@@ -98,38 +98,38 @@ const demoAssetVersion = '20260223-2';
       <div class="workflow-step" style="animation-delay: 0ms">
         <div class="step-number">01</div>
         <div class="step-title">Start</div>
-        <div class="step-desc">Launch with the wrapper or existing mpv setup and keep subtitles in sync.</div>
+        <div class="step-desc">Launch through the wrapper, or from an mpv setup you already have.</div>
       </div>
       <div class="workflow-connector" aria-hidden="true"></div>
       <div class="workflow-step" style="animation-delay: 60ms">
         <div class="step-number">02</div>
         <div class="step-title">Lookup</div>
-        <div class="step-desc">Hover a token in the interactive overlay, then trigger Yomitan lookup to open context.</div>
+        <div class="step-desc">Hover a token in the overlay to open the Yomitan popup for that word.</div>
       </div>
       <div class="workflow-connector" aria-hidden="true"></div>
       <div class="workflow-step" style="animation-delay: 120ms">
         <div class="step-number">03</div>
         <div class="step-title">Mine</div>
-        <div class="step-desc">Create cards from Yomitan or mine sentence cards directly from subtitle lines.</div>
+        <div class="step-desc">Add the word from Yomitan, or mine the whole line as a sentence card.</div>
       </div>
       <div class="workflow-connector" aria-hidden="true"></div>
       <div class="workflow-step" style="animation-delay: 180ms">
         <div class="step-number">04</div>
         <div class="step-title">Enrich</div>
-        <div class="step-desc">Automatically attach timing-accurate audio, sentence text, and visual evidence.</div>
+        <div class="step-desc">SubMiner fills in the audio clip, the sentence, and a screenshot from that moment.</div>
       </div>
       <div class="workflow-connector" aria-hidden="true"></div>
       <div class="workflow-step" style="animation-delay: 240ms">
         <div class="step-number">05</div>
         <div class="step-title">Track</div>
-        <div class="step-desc">Open the stats dashboard to review sessions, vocabulary trends, and mine cards from past viewing history.</div>
+        <div class="step-desc">Review past sessions and word trends, and mine anything you missed the first time.</div>
       </div>
     </div>
   </section>
 
   <section class="demo-section">
     <h2>See it in action</h2>
-    <p>Subtitles, lookup flow, and card enrichment from a real playback session.</p>
+    <p>Recorded from an actual playback session: subtitle hover, lookup, and the card that comes out the other end.</p>
     <div class="demo-window">
       <div class="demo-window__bar">
         <span class="demo-window__dot"></span>

docs-site/installation.md

@@ -1,56 +1,54 @@
 # Installation
 
-SubMiner is a desktop app that draws an interactive layer - an **overlay** - on top of the [mpv](https://mpv.io) video player. As you watch native Japanese media, you can click or hover any word in the subtitles to look it up, then turn it into an Anki flashcard without pausing to switch apps. Building flashcards from real content you're watching is called **sentence mining**, and it's what SubMiner is built for. It bundles its own copy of **Yomitan** (a pop-up dictionary) and talks to **AnkiConnect** (an add-on that lets other programs add cards to Anki) so cards get filled in automatically.
+SubMiner draws an interactive overlay on top of the [mpv](https://mpv.io) video player. While you watch Japanese media, you hover a word in the subtitles to look it up, then turn it into an Anki card without leaving the video.
 
-Three steps to get started:
+Building cards from what you watch is called **sentence mining**. SubMiner bundles its own copy of **Yomitan** (a pop-up dictionary) and talks to **AnkiConnect** (an Anki add-on that lets other programs create cards), so it can fill in the sentence, audio, and screenshot for you.
 
-1. **Install requirements** - mpv and a few optional extras
-2. **Install SubMiner** - from the AUR, or download from GitHub Releases
-3. **Launch the app** - first-run setup walks you through dictionaries, the launcher, and everything else
+Getting started takes three steps:
 
-## 1. Install Requirements
+1. Install mpv and the optional extras you want.
+2. Install SubMiner.
+3. Launch it and follow the first-run setup.
 
-Only **mpv** is strictly required to run SubMiner. Everything else enhances the experience but is optional.
+## 1. Install requirements
 
-| Dependency           | Status      | What it does                                                                                                    |
-| -------------------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
-| mpv                  | Required    | The video player SubMiner overlays on. Must support `--input-ipc-server`.                                       |
-| ffmpeg               | Recommended | Audio extraction and screenshots for Anki cards. Without it SubMiner still runs, but media fields will be empty. |
-| MeCab + mecab-ipadic | Recommended | Part-of-speech filtering for more precise N+1, JLPT, and frequency annotations. Without it annotations still render, but POS-based filtering is less accurate. |
-| yt-dlp               | Optional    | YouTube playback and subtitle extraction.                                                                       |
-| fzf                  | Optional    | Terminal-based video picker in the launcher.                                                                     |
-| rofi                 | Optional    | GUI-based video picker (Linux).                                                                                  |
-| chafa                | Optional    | Thumbnail previews in fzf.                                                                                       |
-| ffmpegthumbnailer    | Optional    | Video thumbnail generation for the picker.                                                                       |
-| guessit              | Optional    | Better AniSkip title/season/episode parsing.                                                                     |
-| alass                | Optional    | Subtitle sync engine (preferred). Disabled without alass or ffsubsync.                                           |
-| ffsubsync            | Optional    | Audio-based subtitle sync engine. Disabled without alass or ffsubsync.                                           |
-| fuse2                | Linux only  | Required to run the AppImage.                                                                                    |
+Only mpv is required. Install ffmpeg too unless you are fine with cards that have no audio or screenshot.
+
+| Dependency               | Needed for                                                                                                           | Platforms    |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------ |
+| mpv                      | Required. The player SubMiner draws over.                                                                            | All          |
+| fuse2                    | Required to run the AppImage.                                                                                        | Linux        |
+| ffmpeg                   | Recommended. Audio clips and screenshots on cards. Without it those fields stay empty.                               | All          |
+| MeCab + mecab-ipadic     | Recommended. More accurate N+1, JLPT, and frequency highlighting.                                                    | All          |
+| yt-dlp                   | YouTube playback.                                                                                                    | All          |
+| xz                       | [TsukiHime](/tsukihime-integration) subtitle downloads. Most Linux distros already have it.                          | All          |
+| guessit                  | Better title, season, and episode detection for [AniSkip](/aniskip-integration) and [AniList](/anilist-integration). | All          |
+| alass or ffsubsync       | Subtitle syncing. You need at least one to use it.                                                                   | All          |
+| fzf, rofi                | The file pickers in the `subminer` command (rofi is Linux only).                                                     | Linux, macOS |
+| chafa, ffmpegthumbnailer | Thumbnail previews in the pickers.                                                                                   | Linux, macOS |
+
+To generate Japanese subtitles from audio, you also need whisper.cpp. See [Subtitle generation](/subtitle-generation).
 
 ### Linux
 
-**Window backend** - you need one of these depending on your compositor:
+SubMiner needs to track the mpv window, and how it does that depends on your desktop:
 
-- **Hyprland** - native Wayland support (uses `hyprctl`)
-- **Sway** - native Wayland support (uses `swaymsg`)
-- **X11 / Xwayland** - for X11 sessions or any other Wayland compositor (uses `xdotool` and `xwininfo`)
-
-::: warning Wayland support is compositor-specific
-Wayland has no universal API for window positioning - each compositor exposes its own IPC, so SubMiner needs a dedicated backend per compositor. Only Hyprland and Sway have native Wayland backends. If you run a different Wayland compositor (GNOME, KDE Plasma, river, etc.), both mpv **and** SubMiner must run under X11 or Xwayland. The `subminer` launcher handles this automatically when `--backend x11` is set or the X11 backend is auto-detected.
-:::
+- **Hyprland**: supported natively through `hyprctl`.
+- **Sway**: supported natively through `swaymsg`.
+- **Anything else** (X11, GNOME, KDE Plasma, other Wayland compositors): mpv and SubMiner must run under X11 or Xwayland. Install `xdotool` and `xwininfo`. The `subminer` command picks the X11 backend automatically, or you can force it with `--backend x11`.
 
 <details>
 <summary><b>Arch Linux</b></summary>
 
 ```bash
 sudo pacman -S --needed mpv ffmpeg
-# Recommended
-sudo pacman -S --needed mecab mecab-ipadic
+# Recommended (MeCab is only in the AUR)
+paru -S --needed mecab-git mecab-ipadic
 # Optional
 sudo pacman -S --needed yt-dlp fzf rofi chafa ffmpegthumbnailer
-# Optional: subtitle sync (at least one needed for subtitle syncing)
+# Optional: subtitle sync (install at least one)
 paru -S --needed alass python-ffsubsync
-# X11 / Xwayland (required for non-Hyprland/Sway compositors)
+# Only for desktops other than Hyprland or Sway
 sudo pacman -S --needed xdotool xorg-xwininfo
 ```
 
@@ -65,11 +63,11 @@ sudo apt install mpv ffmpeg
 sudo apt install mecab libmecab-dev mecab-ipadic-utf8
 # Optional
 sudo apt install yt-dlp fzf rofi chafa ffmpegthumbnailer
-# X11 / Xwayland (required for non-Hyprland/Sway compositors)
+# Only for desktops other than Hyprland or Sway
 sudo apt install xdotool x11-utils
 # Optional: subtitle sync
 pip install ffsubsync
-# alass is not in apt - install via cargo: cargo install alass-cli
+cargo install alass-cli
 ```
 
 </details>
@@ -83,18 +81,18 @@ sudo dnf install mpv ffmpeg
 sudo dnf install mecab mecab-ipadic
 # Optional
 sudo dnf install yt-dlp fzf rofi chafa ffmpegthumbnailer
-# X11 / Xwayland (required for non-Hyprland/Sway compositors)
+# Only for desktops other than Hyprland or Sway
 sudo dnf install xdotool xorg-x11-utils
 # Optional: subtitle sync
 pip install ffsubsync
-# alass: cargo install alass-cli
+cargo install alass-cli
 ```
 
 </details>
 
 ### macOS
 
-macOS 11 (Big Sur) or later. Accessibility permission - the macOS setting that lets one app observe and position another app's windows - is required so the overlay can follow the mpv window (see [step 2](#macos-dmg)).
+You need macOS 11 (Big Sur) or later.
 
 ```bash
 brew install mpv ffmpeg
@@ -107,77 +105,101 @@ brew install alass
 pip install ffsubsync
 ```
 
+`mecab` must be on your `PATH` when SubMiner starts. Homebrew puts it in `/opt/homebrew/bin` on Apple Silicon and `/usr/local/bin` on Intel.
+
 ### Windows
 
-Windows 10 or later. Install [`mpv`](https://mpv.io/installation/) and [`ffmpeg`](https://ffmpeg.org/download.html) and ensure both are on `PATH`. Optionally install [MeCab for Windows](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary.
+You need Windows 10 or later. Install mpv and ffmpeg with [winget](https://learn.microsoft.com/windows/package-manager/winget/), which ships with Windows 11 and current Windows 10. In PowerShell or Command Prompt:
 
-No compositor tools or window helpers are needed - native window tracking is built in.
+```powershell
+winget install shinchiro.mpv
+winget install Gyan.FFmpeg
+winget install yt-dlp.yt-dlp   # optional, for YouTube
+```
+
+Close and reopen the terminal, then check both commands work:
+
+```powershell
+mpv --version
+ffmpeg -version
+```
+
+ffmpeg must be on `PATH`, because SubMiner runs it by name to make card audio and screenshots. mpv does not have to be. If `mpv --version` says `not recognized`, find `mpv.exe` (usually in `%LOCALAPPDATA%\Programs\mpv`) and either add that folder to `PATH` or enter the full path to `mpv.exe` during first-run setup (`mpv.executablePath`).
+
+<details>
+<summary><b>Alternative: Scoop (no admin rights, includes xz)</b></summary>
+
+[Scoop](https://scoop.sh) installs into your user profile and always adds commands to `PATH`. It is the only Windows package manager that also packages `xz`, which [TsukiHime](/tsukihime-integration) downloads need.
+
+```powershell
+# One-time Scoop setup
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
+
+scoop bucket add extras
+scoop install extras/mpv main/ffmpeg
+# Optional
+scoop install main/yt-dlp main/xz
+```
+
+</details>
+
+<details>
+<summary><b>Alternative: manual download</b></summary>
+
+1. Download mpv from [mpv.io/installation](https://mpv.io/installation/) and ffmpeg from [ffmpeg.org/download.html](https://ffmpeg.org/download.html).
+2. Unzip each into a permanent folder, for example `C:\Tools\mpv` and `C:\Tools\ffmpeg`. Find the folders that contain `mpv.exe` and `ffmpeg.exe` (for ffmpeg this is usually `bin`).
+3. Press `Win`, search for **Edit the system environment variables**, and open it. Click **Environment Variables**, select **Path** under **User variables**, click **Edit**, and add both folders with **New**.
+4. Open a new terminal and run `mpv --version` and `ffmpeg -version`. If either says `not recognized`, the folder you added does not contain the `.exe`.
+
+For `xz` without Scoop, download [XZ Utils](https://tukaani.org/xz/) and add its folder to `PATH` the same way.
+
+</details>
+
+For more accurate highlighting, install [MeCab for Windows](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary. The fzf and rofi pickers do not apply on Windows.
 
 ## 2. Install SubMiner
 
 ### Arch Linux (AUR) {#arch-aur}
 
-Install [`subminer-bin`](https://aur.archlinux.org/packages/subminer-bin) from the AUR. The package includes the SubMiner AppImage and the `subminer` launcher.
+Install [`subminer-bin`](https://aur.archlinux.org/packages/subminer-bin). It includes the AppImage and the `subminer` command.
 
 ```bash
 paru -S subminer-bin
 ```
 
-Or manually:
-
-```bash
-git clone https://aur.archlinux.org/subminer-bin.git
-cd subminer-bin
-makepkg -si
-```
-
 ### Linux (AppImage) {#linux-appimage}
 
-Download the latest AppImage from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest):
-
 ```bash
 mkdir -p ~/.local/bin
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppImage -O ~/.local/bin/SubMiner.AppImage
 chmod +x ~/.local/bin/SubMiner.AppImage
 ```
 
-::: tip Launcher install is optional
-First-run setup can install [Bun](https://bun.sh) and the `subminer` command-line launcher for you automatically. You don't need to download the launcher separately.
-
-If you prefer to install it manually, see [manual launcher install](#manual-launcher-install-linux).
-:::
+First-run setup can install the `subminer` command for you.
 
 ### macOS (DMG) {#macos-dmg}
 
-Download the DMG from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest), open it, and drag `SubMiner.app` into `/Applications`. A ZIP artifact is also available as a fallback.
+1. Download the DMG from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest), open it, and drag `SubMiner.app` into `/Applications`.
+2. If macOS blocks the app on first launch, right-click it and choose **Open**, or run:
 
-**Gatekeeper:** If macOS blocks SubMiner on first launch, right-click the app and select **Open** to bypass the warning. Alternatively:
+   ```bash
+   xattr -d com.apple.quarantine /Applications/SubMiner.app
+   ```
 
-```bash
-xattr -d com.apple.quarantine /Applications/SubMiner.app
-```
+3. Open **System Settings > Privacy & Security > Accessibility** and enable SubMiner (add it if it is missing). The overlay cannot follow the mpv window without this.
 
-**Accessibility permission:** Grant accessibility permission so the overlay can track the mpv window:
+First-run setup can install the `subminer` command for you.
 
-1. Open **System Settings** → **Privacy & Security** → **Accessibility**
-2. Enable SubMiner in the list (add it if it does not appear)
+### Windows (installer) {#windows-installer}
 
-::: tip Launcher install is optional
-First-run setup can install [Bun](https://bun.sh) and the `subminer` command-line launcher for you automatically. You don't need to download the launcher separately.
+Download from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest):
 
-If you prefer to install it manually, see [manual launcher install](#manual-launcher-install-macos).
-:::
+- `SubMiner-<version>.exe`: the installer. Use this one.
+- `SubMiner-<version>-win.zip`: portable version.
+- `subminer.cmd`: optional terminal command (setup can install it for you).
 
-### Windows (Installer) {#windows-installer}
-
-Download the latest installer from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest):
-
-- `SubMiner-<version>.exe` - installer (recommended)
-- `SubMiner-<version>-win.zip` - portable fallback
-
-Make sure `mpv.exe` is on your `PATH`, or set `mpv.executablePath` in the config during first-run setup.
-
-### From Source
+### From source
 
 <details>
 <summary><b>Linux</b></summary>
@@ -187,12 +209,10 @@ git clone --recurse-submodules https://github.com/ksyasuda/SubMiner.git
 cd SubMiner
 make deps
 bun run build
-
-# Optional: build AppImage
-bun run build:appimage
+bun run build:appimage   # optional: package an AppImage
 ```
 
-Bundled Yomitan is built during `bun run build`.
+Building from source needs [Bun](https://bun.sh) installed.
 
 </details>
 
@@ -206,7 +226,7 @@ make deps
 make build-macos
 ```
 
-The built app will be in the `release` directory (`.dmg` and `.zip`). For unsigned local builds: `bun run build:mac:unsigned`.
+The `.dmg` and `.zip` land in `release/`. For an unsigned local build, run `bun run build:mac:unsigned`.
 
 </details>
 
@@ -229,121 +249,80 @@ bun run build:win
 
 </details>
 
-## 3. Launch & First-Run Setup
+## 3. Launch and first-run setup
 
-Launch SubMiner and the setup wizard will open automatically:
+Start SubMiner. The setup window opens on first launch.
 
-```bash
-# Linux (AUR install)
-subminer app --setup
+- **Linux (AUR)**: `subminer app --setup`
+- **Linux (AppImage)**: `~/.local/bin/SubMiner.AppImage --setup`
+- **macOS**: open `SubMiner.app` from `/Applications`
+- **Windows**: run SubMiner from the Start menu
 
-# Linux (AppImage directly)
-~/.local/bin/SubMiner.AppImage --setup
+Setup walks you through:
 
-# macOS - launch SubMiner.app from /Applications, or:
-subminer app --setup
-```
+1. **Config file.** Created at `~/.config/SubMiner/config.jsonc` (Linux and macOS) or `%APPDATA%\SubMiner\config.jsonc` (Windows).
+2. **Yomitan dictionaries.** Import at least one dictionary, or lookups will not work. SubMiner's Yomitan is separate from any Yomitan in your browser.
+3. **The `subminer` command** (optional). Setup installs it into a folder already on your `PATH`. If there is none on Linux or macOS, it uses `~/.local/bin` and shows the `export PATH=...` line to add to your shell config. On Windows it adds `%LOCALAPPDATA%\SubMiner\bin` to your user `PATH`.
+4. **SubMiner mpv shortcut** (Windows only). A Start menu or desktop shortcut that opens mpv with SubMiner attached.
 
-On **Windows**, just run `SubMiner.exe` - the setup wizard opens automatically on first launch.
+**Finish setup** unlocks once the config exists and at least one dictionary is imported. To reopen setup later, run `subminer app --setup`.
 
-The setup wizard walks you through:
-
-- **Config file** - auto-created at `~/.config/SubMiner/config.jsonc` (Linux/macOS) or `%APPDATA%\SubMiner\config.jsonc` (Windows)
-- **Yomitan dictionaries** - import at least one dictionary so word lookups work
-- **Bun + `subminer` launcher** _(optional)_ - installs the command-line launcher into a writable PATH directory
-- **Windows shortcut** _(Windows only)_ - create a `SubMiner mpv` Start Menu/Desktop shortcut
-
-The `Finish setup` button requires a config file and at least one Yomitan dictionary. Bun and the launcher are optional and never block setup completion.
-
-> [!TIP]
-> You can re-open the setup wizard at any time with `subminer app --setup` or `SubMiner.AppImage --setup`.
-
-### Play a Video
-
-Once setup is complete:
+### Play a video
 
 ```bash
 subminer video.mkv
 ```
 
-You should see the overlay appear over mpv. If subtitles are loaded, they will appear as interactive text in the overlay.
+On Windows, double-click the **SubMiner mpv** shortcut or drag a video onto it.
 
-On **Windows**, the recommended way to play video is with the **SubMiner mpv** shortcut created during setup - double-click it, or drag a video file onto it.
+The overlay appears over mpv, and the subtitle text becomes hoverable. See [Usage](/usage) for everyday use.
 
-### Verify Setup
-
-Run the built-in diagnostic to confirm everything is working:
+### Check your setup
 
 ```bash
 subminer doctor
 ```
 
-This checks for the app binary, mpv, ffmpeg, config file, and socket path. Fix any failures before continuing.
+This checks for the SubMiner app, mpv, ffmpeg, yt-dlp, fzf, rofi, your config file, and the mpv socket path. Only a missing app or mpv counts as a failure. The rest are reported as optional.
 
-## Anki Setup (Recommended)
+## Anki setup
 
-If you plan to mine Anki cards:
+To create cards:
 
-1. Install [Anki](https://apps.ankiweb.net/)
-2. Install [AnkiConnect](https://ankiweb.net/shared/info/2055492159) - open Anki → **Tools → Add-ons → Get Add-ons** → enter code `2055492159`
-3. Restart Anki and keep it running while using SubMiner
+1. Install [Anki](https://apps.ankiweb.net/).
+2. In Anki, open **Tools > Add-ons > Get Add-ons** and enter `2055492159` to install [AnkiConnect](https://ankiweb.net/shared/info/2055492159).
+3. Restart Anki. Keep it open while you use SubMiner.
 
-AnkiConnect listens on `http://127.0.0.1:8765` by default. SubMiner connects automatically with no extra config needed.
-
-For enrichment configuration (sentence, audio, screenshot fields), see [Anki Integration](/anki-integration).
+SubMiner connects to AnkiConnect at its default address with no extra setup. To choose your deck and card fields, see [Anki integration](/anki-integration).
 
 ## Updates
 
 ```bash
 subminer -u
-# or
-subminer --update
 ```
 
-SubMiner verifies AppImage, launcher, and rofi theme downloads against `SHA256SUMS.txt`. If the binary is in a protected path, SubMiner shows the exact command to run rather than elevating itself.
+The tray menu's **Check for Updates** also installs updates on Linux, macOS, and Windows. If the AppImage sits in a folder you cannot write to, SubMiner prints the command to run instead of asking for admin rights.
 
-The tray "Check for Updates" entry installs the new app automatically on Linux, macOS, and Windows. On Linux it replaces the running `.AppImage` in place via `electron-updater`; AppImages managed by a system package (for example the AUR `/opt/SubMiner/SubMiner.AppImage`) are skipped so the package manager stays in charge.
+If you installed from the AUR, update through your package manager instead.
 
-`subminer -u` also performs the AppImage update directly from the launcher process, which is useful when SubMiner is not currently running.
+## Launching mpv yourself
 
-## How It All Fits Together
+The `subminer` command and the Windows shortcut start mpv with the IPC socket SubMiner needs. If you start mpv another way, add this option or the overlay starts without subtitles:
 
-SubMiner is an overlay that sits on top of mpv. It connects to mpv through an IPC socket, renders subtitles as interactive text using a bundled Yomitan dictionary engine, and optionally creates Anki flashcards via AnkiConnect.
+```bash
+--input-ipc-server=/tmp/subminer-socket      # Linux and macOS
+--input-ipc-server=\\.\pipe\subminer-socket  # Windows
+```
 
-The `subminer` launcher handles mpv IPC socket setup automatically. If you launch mpv yourself or from another tool, you must pass `--input-ipc-server=/tmp/subminer-socket` (or `\\.\pipe\subminer-socket` on Windows) - without it the overlay starts but subtitles won't appear.
+SubMiner loads its mpv plugin automatically, so there is nothing else to install. See [mpv plugin](/mpv-plugin) for the in-player keybindings.
 
-The bundled mpv plugin is injected at runtime automatically - you don't need to install it separately. It provides in-player keybindings (the `y` chord) for controlling the overlay from within mpv. See [MPV Plugin](/mpv-plugin) for the full keybinding and configuration reference.
+## Manual launcher install
 
-## Platform Notes
-
-### macOS
-
-**MeCab paths (Homebrew):**
-- Apple Silicon (M1/M2): `/opt/homebrew/bin/mecab`
-- Intel: `/usr/local/bin/mecab`
-
-Ensure `mecab` is available on your PATH when launching SubMiner.
-
-**Fullscreen:** The overlay should appear correctly in fullscreen. If you encounter issues, check that accessibility permissions are granted.
-
-### Windows
-
-- The **SubMiner mpv** shortcut is the recommended way to launch playback. It starts `mpv.exe` with the right IPC socket and subtitle defaults.
-- First-run setup adds only `%LOCALAPPDATA%\SubMiner\bin` to the HKCU user PATH. It does not add `SubMiner.exe` to PATH.
-- IPC socket on Windows is `\\.\pipe\subminer-socket` - do not use `/tmp/subminer-socket`.
-- Config is stored at `%APPDATA%\SubMiner\config.jsonc`.
-
-## Manual Launcher Install
-
-The `subminer` launcher uses a [Bun](https://bun.sh) shebang, so Bun must be installed. First-run setup can handle this automatically, but if you prefer to do it yourself:
+Use these if you skipped the launcher during setup. The launcher finds SubMiner in the usual install locations. For a custom location, set `SUBMINER_BINARY_PATH` to the app executable.
 
 ### Linux {#manual-launcher-install-linux}
 
 ```bash
-# Install Bun
-curl -fsSL https://bun.sh/install | bash
-
-# Download the launcher
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer
 chmod +x ~/.local/bin/subminer
 ```
@@ -351,27 +330,16 @@ chmod +x ~/.local/bin/subminer
 ### macOS {#manual-launcher-install-macos}
 
 ```bash
-# Install Bun
-curl -fsSL https://bun.sh/install | bash
-
-# Download the launcher
 sudo curl -fSL https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -o /usr/local/bin/subminer
 sudo chmod +x /usr/local/bin/subminer
 ```
 
-## Optional Extras
+### Windows {#manual-launcher-install-windows}
 
-### Rofi Theme (Linux Only)
+Download `subminer.cmd` from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest) and put it in a folder on your user `PATH`.
 
-SubMiner ships a custom rofi theme in the release assets:
+## Bundled Bun runtime {#bundled-bun-runtime}
 
-```bash
-wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
-tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
-mkdir -p ~/.local/share/SubMiner/themes
-cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi
-```
+The `subminer` command runs on a copy of [Bun](https://bun.sh) 1.3.5 that ships inside the app, so you do not need to install Bun. Bun is MIT licensed and statically links JavaScriptCore (LGPL 2.0) and TinyCC (LGPL 2.1). License texts and a `SOURCE.md` ship in the app under `resources/bun/licenses`, and each GitHub release includes `bun-v1.3.5-source.tar.gz` with the matching sources.
 
-Override with `SUBMINER_ROFI_THEME=/absolute/path/to/theme.rasi`.
-
-Next: [Usage](/usage) - learn about the `subminer` wrapper, keybindings, and YouTube playback.
+Next: [Usage](/usage).

docs-site/ipc-contracts.md

@@ -1,12 +1,12 @@
-# IPC + Runtime Contracts
+# IPC + runtime contracts
 
-SubMiner's Electron app runs two isolated processes - main and renderer - that can only communicate through IPC channels. This boundary is intentional: the renderer is an untrusted surface (it loads Yomitan, renders user-controlled subtitle text, and runs in a Chromium sandbox), so every message crossing the bridge passes through a validation layer before it can reach domain logic.
+The Electron main and renderer processes talk only through IPC channels. The renderer is an untrusted surface: it loads Yomitan and renders subtitle text SubMiner did not write. Every payload that crosses the bridge goes through a validator before domain code sees it.
 
-The contract system enforces this by making channel names, payload shapes, and validators co-located and co-evolved. A change to any IPC surface touches the contract, the validator, the preload bridge, and the handler in the same commit - drift between any of those layers is treated as a bug.
+Channel names, payload validators, the preload bridge, and the handler change together. When you touch an IPC surface, update all four in the same commit.
 
-## Message Flow
+## Message flow
 
-Renderer-initiated calls (`invoke`) pass through four boundaries before reaching a service. Fire-and-forget messages (`send`) follow the same path but skip the response leg. Malformed payloads are caught at the validator and never reach domain code.
+Renderer calls pass through the preload bridge, the main-process handler, and a validator before they reach a service. Malformed payloads stop at the validator.
 
 ```mermaid
 flowchart TB
@@ -36,12 +36,18 @@ flowchart TB
   style E fill:#ed8796,stroke:#494d64,color:#24273a,stroke-width:1.5px
 ```
 
-## Runtime Sockets
+`IPC_CHANNELS` in `src/shared/ipc/contracts.ts` groups channels by pattern:
 
-The renderer↔main bridge above lives *inside* the Electron app. A separate set of OS sockets connects the app to the other runtimes - mpv and the launcher/plugin. These carry no renderer payloads and bypass the contract/validator layer; they are command and property channels between processes.
+- `request`: invoke channels. The renderer awaits a result, for example lookups, config reads, and mining actions. Invalid payloads return a structured failure such as `{ ok: false, ... }` instead of throwing.
+- `command`: fire-and-forget sends, for example focus events, UI state hints, and position updates. Invalid payloads are dropped.
+- `event`: messages pushed from main to the renderer.
 
-- **mpv IPC socket** (`/tmp/subminer-socket`, or `\\.\pipe\subminer-socket` on Windows): the `MpvIpcClient` in the main process connects here to send JSON commands and subscribe to playback/subtitle properties via `observe_property`. Created by mpv's `--input-ipc-server`.
-- **App control socket** (`/tmp/subminer-control-<uid>-<hash>.sock`, or a named pipe on Windows): the launcher and the mpv plugin send CLI-style commands (`--start`, `--show-visible-overlay`, `--texthooker`) to a running app here. It also dedupes a second `subminer` invocation into the existing instance instead of launching twice.
+## Runtime sockets
+
+The bridge above lives inside the Electron app. Separate OS sockets connect the app to mpv and to the launcher and plugin. They carry no renderer payloads and do not go through the contract and validator layer.
+
+- **mpv IPC socket**: `/tmp/subminer-socket`, or `\\.\pipe\subminer-socket` on Windows. mpv creates it with `--input-ipc-server`. The app's `MpvIpcClient` sends JSON commands here and observes playback and subtitle properties.
+- **App control socket**: `subminer-control-<uid>-<hash>.sock` in the temp directory, or `\\.\pipe\subminer-control-<hash>` on Windows. The launcher and plugin send CLI-style commands (`--start`, `--show-visible-overlay`, `--texthooker`) to a running app here. It also routes a second `subminer` invocation into the existing instance.
 
 ```mermaid
 flowchart LR
@@ -65,60 +71,44 @@ flowchart LR
   style MpvProc fill:#363a4f,stroke:#494d64,color:#cad3f5
 ```
 
-How these sockets are established during launch is covered in [Playback Startup Flow](./architecture#playback-startup-flow).
+[Playback startup flow](./architecture#playback-startup-flow) shows when each socket comes up during a launch.
 
-## Core Surfaces
+## Core files
 
 | File                                   | Role                                                                                |
-| --- | --- |
-| `src/shared/ipc/contracts.ts` | Canonical channel names and payload type contracts. Single source of truth for both processes. |
-| `src/shared/ipc/validators.ts` | Runtime payload parsers and type guards. Every `invoke` payload is validated here before the handler runs. |
-| `src/preload.ts` | Renderer-side bridge. Exposes a typed API surface to the renderer - only approved channels are accessible. |
-| `src/main/ipc-runtime.ts` | Main-process handler registration and routing. Wires validated channels to domain handlers. |
-| `src/core/services/ipc.ts` | Service-level invoke handling. Applies guardrails (validation, error wrapping) before calling domain logic. |
-| `src/core/services/anki-jimaku-ipc.ts` | Integration-specific IPC boundary for Anki and Jimaku operations. |
-| `src/main/cli-runtime.ts` | CLI/runtime command boundary. Handles commands that originate from the launcher or mpv plugin rather than the renderer. |
+| -------------------------------------- | ----------------------------------------------------------------------------------- |
+| `src/shared/ipc/contracts.ts`          | Channel names and payload types, shared by both processes                           |
+| `src/shared/ipc/validators.ts`         | Runtime payload parsers and type guards                                             |
+| `src/preload.ts`                       | Typed renderer API; only approved channels are exposed                              |
+| `src/core/services/ipc.ts`             | Registers overlay handlers and validates payloads before calling domain logic       |
+| `src/core/services/anki-jimaku-ipc.ts` | Same boundary for Anki and Jimaku operations                                        |
+| `src/main/ipc-runtime.ts`              | Builds handler dependencies (via `src/main/dependencies.ts`) and registers handlers |
+| `src/main/cli-runtime.ts`              | Handles commands from the launcher or mpv plugin, not the renderer                  |
 
-## Contract Rules
+## Contract rules
 
-These rules exist to prevent a class of bugs where the renderer and main process silently disagree about message shapes - which surfaces as undefined fields, swallowed errors, or state corruption.
+- **Use the shared constants.** Take channel names from `contracts.ts`, never string literals.
+- **Validate before handling.** Every renderer payload goes through `validators.ts` before domain logic.
+- **Return structured failures.** Invoke handlers return `{ ok: false, ... }` on failure instead of throwing, so the renderer can tell success from failure without try/catch.
+- **Keep payloads narrow.** Send only what the handler needs, not whole state objects.
+- **Keep handlers thin.** Validate, delegate to a service or composer, return. Route shared state changes through the transition helpers in `src/main/state.ts`.
 
-- **Use shared constants.** Channel names come from `contracts.ts`, never ad-hoc literal strings. This makes channels greppable and refactor-safe.
-- **Validate before handling.** Every `invoke` payload passes through `validators.ts` before reaching domain logic. This catches shape drift at the boundary instead of deep inside a service.
-- **Return structured failures.** Handlers return `{ ok: false, error: string }` on failure rather than throwing. The renderer can always distinguish success from failure without try/catch.
-- **Keep payloads narrow.** Send only what the handler needs. Avoid passing entire state objects across the bridge - it couples the renderer to internal main-process structure.
-- **Co-evolve all layers.** When a payload shape changes, update `contracts.ts`, `validators.ts`, `preload.ts`, and the handler in the same commit. Partial updates are treated as bugs.
-
-## Two Message Patterns
-
-**Invoke (request/response):** The renderer calls a typed bridge method and awaits a result. The main process validates the payload, runs the handler, and returns a structured response. Used for operations where the renderer needs a result - lookups, config reads, mining actions.
-
-**Fire-and-forget (send):** The renderer sends a message with no response. The main process validates and handles it silently. Malformed payloads are dropped. Used for notifications where the renderer doesn't need confirmation - UI state hints, focus events, position updates.
-
-## Add a New IPC Action
+## Add a new IPC action
 
 1. Add the channel constant in `src/shared/ipc/contracts.ts`.
-2. Add or extend the payload validator in `src/shared/ipc/validators.ts`.
+2. Add or extend the validator in `src/shared/ipc/validators.ts`.
 3. Expose a typed bridge method in `src/preload.ts`.
-4. Register the handler in `src/main/ipc-runtime.ts` (or the relevant domain runtime module).
-5. Add tests for both valid and malformed payload cases in `src/core/services/*`.
-6. Update renderer tests when behavior or state transitions change.
-
-## Runtime State Notes
-
-- Prefer runtime/domain composition via `src/main/runtime/composers/*` and `src/main/runtime/domains/*`. IPC handlers should delegate to composers rather than containing orchestration logic.
-- Route shared mutable state updates through transition helpers in `src/main/state.ts` for migrated domains. Direct mutation from IPC handlers bypasses invariant checks.
-- Keep IPC handlers thin - they validate, delegate, and return. Business logic belongs in services.
+4. Register the handler in `src/core/services/ipc.ts` (or `anki-jimaku-ipc.ts`), and supply any new dependency through `src/main/ipc-runtime.ts`.
+5. Test valid and malformed payloads in `src/core/services/*`.
+6. Update renderer tests if behavior or state transitions change.
 
 ## Troubleshooting
 
-- **Unknown payload in handler:** The validator is not being applied before the handler runs. Check that the channel is routed through `ipc-runtime.ts` with validation, not registered directly.
-- **Renderer invoke fails:** Verify the preload bridge method exists and matches the channel constant. Check that the handler is registered and returning (not throwing).
-- **Contract drift:** When invoke calls return unexpected shapes, compare the shared contract, validator, preload bridge, and main handler signatures side by side. One of them was updated without the others.
+- **Handler receives an unexpected payload:** the validator is not applied. Check that the channel is registered through the IPC service with validation, not directly.
+- **Renderer invoke fails:** check that the preload method exists, uses the right channel constant, and that the handler is registered and returns instead of throwing.
+- **Invoke returns an unexpected shape:** compare the contract, validator, preload method, and handler side by side. One of them changed without the others.
 
-## Related Docs
+## Related docs
 
 - [Architecture](/architecture)
-- [Development](/development)
-- [Configuration](/configuration)
-- [Troubleshooting](/troubleshooting)
+- [Building and testing](/development)

docs-site/jellyfin-integration.md

@@ -1,118 +1,60 @@
-# Jellyfin Integration
+# Jellyfin integration
 
-[Jellyfin](https://jellyfin.org) is a free, self-hosted media server - think of it as your own private streaming service for video you own. If you keep your anime on a Jellyfin server, SubMiner can play episodes through mpv with the full mining overlay.
+If your anime lives on a [Jellyfin](https://jellyfin.org) server, SubMiner can appear as a cast target in any Jellyfin client. Cast an episode and it plays in SubMiner's mpv with the overlay and Yomitan lookup attached.
 
-::: tip Who needs this?
-This page is only relevant if you already run (or have access to) a Jellyfin server. If you watch local files or YouTube, you can skip it. The in-app setup window (`subminer jellyfin`) is the easiest starting point.
-:::
+## Setup
 
-SubMiner can act as a **cast-to-device target** for Jellyfin (similar to jellyfin-mpv-shim). Sign in once, turn on discovery, and SubMiner shows up in the "Play on…" / cast menu of any Jellyfin app - web, phone, or TV. Pick an episode, cast it to SubMiner, and it plays in SubMiner's mpv window with the full overlay and Yomitan click-to-lookup.
+You need a Jellyfin server (Jellyfin 12 is supported) and your username and password.
 
-This is the recommended way to use Jellyfin with SubMiner. A terminal-only option is covered in [Launcher playback](#launcher-playback) at the end.
+1. Start SubMiner and leave it in the system tray.
+2. Open the tray menu and click **Configure Jellyfin**. You can also run `subminer jellyfin`.
+3. Enter the **Server URL** (for example `http://127.0.0.1:8096`), **Username**, and **Password**, then click **Login**.
 
-## Requirements
+SubMiner stores an encrypted session token, not your password, and turns the integration on. Reopen the same window to switch servers or log out.
 
-- A Jellyfin server plus your username and password
-- SubMiner installed and running (see [Installation](/installation))
-- On Linux, the session token is stored with `gnome-libsecret` by default
+## Casting from Jellyfin
 
-## Quick start
+After you sign in, SubMiner connects to Jellyfin at startup and shows up in the cast ("Play on") menu under your computer's hostname. To connect for the current session only, tick **Jellyfin Discovery** in the tray menu.
 
-### 1. Start SubMiner
+1. In the Jellyfin web or mobile app, start playing an episode.
+2. Open the cast menu and pick your computer.
 
-Launch SubMiner so it's running in the system tray.
+SubMiner starts mpv if it is not already running. Pause, seek, stop, and track changes in the Jellyfin app are mirrored in mpv, and watch progress syncs back to Jellyfin. Playback resumes from Jellyfin's saved position.
 
-### 2. Sign in to your server
+SubMiner selects a Japanese subtitle track automatically and resets mpv's subtitle delay to zero. It direct-plays files when it can and asks Jellyfin to transcode the rest.
 
-Open the tray menu and click **Configure Jellyfin**. In the window that opens, enter your **Server URL** (for example `http://127.0.0.1:8096`), **Username**, and **Password**, then click **Login**.
+On Windows, casting finds mpv through `mpv.executablePath`, then `SUBMINER_MPV_PATH`, then `PATH`. An invalid `mpv.executablePath` stops mpv from starting.
 
-On success, SubMiner:
+## Playing from the terminal
 
-- saves an encrypted session token - your password is never stored,
-- turns the Jellyfin integration on, and
-- remembers the server and username for next time.
+The launcher can browse your libraries and play an item without a Jellyfin client:
 
-Reopen this window any time to switch servers or **Logout**.
-
-### 3. Turn on discovery
-
-Discovery is what makes SubMiner appear as a cast target. Two ways to enable it:
-
-- **For the current session** - open the tray menu and tick **Jellyfin Discovery**. (This item appears once you've signed in.)
-- **Automatically on every launch** - already on by default. After your first sign-in, SubMiner auto-connects to Jellyfin at startup, so the cast target is ready without touching the tray. You can change this under [Settings](#settings).
-
-### 4. Cast from any Jellyfin app
-
-In the Jellyfin web UI or mobile app, start playing something, open the **cast / "Play on"** menu, and pick your device - SubMiner appears there named after your computer's hostname. Playback opens in SubMiner.
-
-From then on, pause / resume / seek / stop and audio or subtitle track changes you make in the Jellyfin app are mirrored in SubMiner, and your watch progress syncs back to Jellyfin (now-playing and resume position).
-
-## What happens during playback
-
-- **mpv launches automatically.** If mpv isn't already running when you cast, SubMiner starts it with SubMiner defaults and the bundled mpv plugin, so keybindings work right away.
-- **The overlay is managed by SubMiner,** so your configured `subtitleStyle` controls how subtitles look. Use the [overlay-toggle shortcut](/shortcuts) to hide it for a session.
-- **Resume works.** If Jellyfin has a saved position for the item, SubMiner seeks there on load.
-- **Direct play first.** When the source allows it and the container is in your direct-play allowlist, SubMiner streams the original file; otherwise it requests a transcoded stream from Jellyfin.
-- **Japanese subtitles are auto-selected,** preferring Jellyfin's default and embedded tracks over external sidecar files when several match.
-- **Subtitle timing is corrected when possible.** SubMiner removes Jellyfin's server-selected subtitle stream from the mpv load URL, suppresses the mpv plugin's one-shot subtitle auto-selection and overlay auto-start for managed Jellyfin loads, stages downloaded subtitle tracks without letting mpv auto-switch between tracks, then selects the Japanese track once after applying any saved or inferred timing delay. When Jellyfin provides both Japanese and English subtitle files, SubMiner compares their cue timelines and applies a global delay if one track is clearly offset. Manual delay shifts you make with SubMiner's adjacent-cue controls are saved per item and subtitle track, then restored the next time you select that track.
-
-## Settings
-
-All Jellyfin options live under **Settings → Integrations → Jellyfin** (open settings from the tray's **Open SubMiner Settings**). The ones that matter for casting:
-
-| Setting                         | Default | What it does                                                                                                          |
-| ------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
-| **Enabled**                     | Off     | Turns the Jellyfin integration on. Switched on for you when you sign in.                                              |
-| **Server Url**                  | -       | Your Jellyfin server. Filled in when you sign in.                                                                     |
-| **Remote Control Enabled**      | On      | Lets SubMiner act as a cast target.                                                                                   |
-| **Remote Control Auto Connect** | On      | Connects to Jellyfin at startup so discovery is automatic. Turn off if you'd rather start it from the tray each time. |
-| **Auto Announce**               | Off     | Re-broadcasts visibility on connect. Enable if your device is slow to appear in the cast menu.                        |
-
-Prefer editing the config file? The same keys live under `jellyfin` in `config.jsonc`:
-
-```jsonc
-{
-  "jellyfin": {
-    "enabled": true,
-    "serverUrl": "http://127.0.0.1:8096",
-    "remoteControlEnabled": true,
-    "remoteControlAutoConnect": true,
-  },
-}
+```bash
+subminer jellyfin -p       # fzf picker; `jf` is an alias for `jellyfin`
+subminer -R jellyfin -p    # rofi picker
 ```
 
-See [Configuration](/configuration) for the full list (transcode codec, direct-play containers, default library, and more).
+Sign in first. See [Launcher script](/launcher-script) for the other `jellyfin` subcommands.
+
+## Options
+
+All options are under **Settings > Integrations > Jellyfin**, or `jellyfin` in `config.jsonc`. See [Configuration](/configuration#jellyfin) for the full list and defaults.
+
+| Key                        | What it does                                                         |
+| -------------------------- | -------------------------------------------------------------------- |
+| `enabled`                  | Turns the integration on. Set for you when you sign in.              |
+| `serverUrl`                | Your Jellyfin server. Filled in when you sign in.                    |
+| `remoteControlEnabled`     | Lets SubMiner act as a cast target.                                  |
+| `remoteControlAutoConnect` | Connects at startup. Turn off to start discovery from the tray.      |
+| `autoAnnounce`             | Re-announces the device on connect. Try it if SubMiner appears late. |
+| `transcodeVideoCodec`      | Video codec requested when Jellyfin transcodes.                      |
+
+For headless setups, `SUBMINER_JELLYFIN_ACCESS_TOKEN` and `SUBMINER_JELLYFIN_USER_ID` supply a session without the sign-in window. Treat the token store and `config.jsonc` as secrets.
 
 ## Troubleshooting
 
-**SubMiner doesn't appear in the cast menu**
+**SubMiner is missing from the cast menu.** Check that SubMiner is running, that you are signed in (log in again if the token expired), and that discovery is on. The Jellyfin client and SubMiner must use the same server.
 
-- Make sure SubMiner is running.
-- Make sure you're signed in - reopen **Configure Jellyfin** and log in again if your token expired.
-- Make sure discovery is on (tray **Jellyfin Discovery**, or **Remote Control Auto Connect** in settings).
-- Make sure SubMiner and the Jellyfin client point at the same server.
+**Casting starts but nothing plays.** Confirm the item plays in another Jellyfin client. If mpv was closed, give SubMiner a few seconds to start it.
 
-**Casting starts but nothing plays**
-
-- Confirm the item plays normally in another Jellyfin client.
-- If mpv was closed, give it a moment - SubMiner launches it on demand and retries.
-
-**SubMiner keeps disconnecting**
-
-- Check server/network stability and whether the session token has expired.
-
-## Security notes
-
-- The Jellyfin session (access token + user ID) is kept in SubMiner's local encrypted token storage. Your password is used only to log in and is never saved.
-- Treat the token storage and your `config.jsonc` as secrets - don't commit them.
-- Advanced/headless: the `SUBMINER_JELLYFIN_ACCESS_TOKEN` and `SUBMINER_JELLYFIN_USER_ID` environment variables can supply a session without the sign-in window.
-
-## Launcher playback
-
-If you'd rather stay in the terminal, the `subminer` launcher can browse and play Jellyfin media directly, without casting from a Jellyfin app:
-
-```bash
-subminer jellyfin -p      # alias: subminer jf -p
-```
-
-This opens an fzf picker (add `-R` for rofi) to browse your libraries and episodes, then plays the selected item in SubMiner's mpv with the same overlay, resume, and subtitle behavior described above. Sign in first (step 2) so the launcher can reach your server. See [Launcher Script](/launcher-script) for the rest of the launcher's features.
+**Linux token storage fails.** SubMiner stores the token with `gnome-libsecret` by default. Start your keyring, or pass `--password-store=basic_text`.

docs-site/jimaku-integration.md

@@ -1,115 +1,62 @@
-# Jimaku Integration
+# Jimaku integration
 
-[Jimaku](https://jimaku.cc) is a community-driven subtitle repository for anime - a shared online library of subtitle files contributed by other learners. SubMiner integrates with the Jimaku API so you can search, browse, and download Japanese subtitle files directly from the overlay - no alt-tabbing or manual file management required. Downloaded subtitles are loaded into mpv immediately.
+[Jimaku](https://jimaku.cc) is a community archive of Japanese subtitles for anime and live action. SubMiner searches it from the overlay, downloads the file you pick, and loads it into mpv.
 
-::: tip Prerequisite: a free API key
-You need a Jimaku account and an API key (a personal access string) before this feature works. Create an account at [jimaku.cc](https://jimaku.cc), copy your key, and add it to your config as shown under [Configuration](#configuration) below. Without a key, the search modal will report "Jimaku API key not set."
-:::
+## Setup
 
-## How It Works
-
-The Jimaku integration runs through an in-overlay modal accessible via a keyboard shortcut (`Ctrl+Shift+J` by default).
-
-When you open the modal, SubMiner parses the current video filename to extract a title, season, and episode number. Common naming conventions are supported - `S01E03`, `1x03`, `E03`, and dash-separated episode numbers all work. If the filename yields a high-confidence match (title + episode), SubMiner auto-searches immediately.
-
-From there:
-
-1. **Search** - SubMiner queries the Jimaku API with the parsed title. Results appear as a list of anime entries (Japanese and English names).
-2. **Browse entries** - Select an entry to load its available subtitle files, filtered by episode if one was detected.
-3. **Browse files** - Files show name, size, and last-modified date. If a language preference is configured, files are sorted accordingly (e.g., Japanese-tagged files first).
-4. **Download** - Selecting a file downloads it to the same directory as the video (or a temp directory for remote/streamed media) and loads it into mpv as a new subtitle track.
-
-If no files match the current episode filter, a "Show all files" button lets you broaden the search to all episodes for that entry.
-
-### Modal Keyboard Shortcuts
-
-| Key | Action |
-| --- | --- |
-| `Enter` (in text field) | Search |
-| `Enter` (in list) | Select entry / download file |
-| `Arrow Up` / `Arrow Down` | Navigate entries or files |
-| `Escape` | Close modal |
-
-## Configuration
-
-Add a `jimaku` section to your `config.jsonc`:
+1. Create a free account at [jimaku.cc](https://jimaku.cc) and copy your API key.
+2. Add the key to `config.jsonc`, either directly or through a command that prints it:
 
 ```jsonc
 {
   "jimaku": {
     "apiKey": "YOUR_API_KEY",
-    "apiKeyCommand": "cat ~/.jimaku_key",
-    "apiBaseUrl": "https://jimaku.cc",
-    "languagePreference": "ja",
-    "maxEntryResults": 10
-  }
+    // or, to keep it out of the config file:
+    // "apiKeyCommand": "pass jimaku/api-key",
+  },
 }
 ```
 
-| Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `jimaku.apiKey` | `string` | - | Jimaku API key (plaintext). Mutually exclusive with `apiKeyCommand`. |
-| `jimaku.apiKeyCommand` | `string` | - | Shell command that prints the API key to stdout. Useful for secret managers (e.g., `pass jimaku/api-key`). |
-| `jimaku.apiBaseUrl` | `string` | `"https://jimaku.cc"` | Base URL for the Jimaku API. Only change this if using a mirror or local instance. |
-| `jimaku.languagePreference` | `"ja"` \| `"en"` \| `"none"` | `"ja"` | Sort subtitle files by language tag. `"ja"` pushes Japanese-tagged files to the top; `"en"` does the same for English. `"none"` preserves the API order. |
-| `jimaku.maxEntryResults` | `number` | `10` | Maximum number of anime entries returned per search. |
+If both are set, `apiKey` wins. `apiKeyCommand` must print the key within 10 seconds. Without a key, the modal shows "Jimaku API key not set."
 
-The keyboard shortcut is configured separately under `shortcuts`:
+## Usage
 
-```jsonc
-{
-  "shortcuts": {
-    "openJimaku": "Ctrl+Shift+J"
-  }
-}
-```
+1. Press `Ctrl+Shift+J` during playback.
+2. SubMiner fills in the title, season, and episode from the file name. If it finds both a title and an episode, it searches right away. Otherwise, fix the fields and press `Enter`.
+3. Pick the **Anime** or **Live action** tab. Switching tabs repeats the search.
+4. Select an entry, then select a file. Files are filtered to the current episode. Click **Broaden search (all files)** to see every file in the entry.
 
-### API Key
+The file is saved next to the video (or to a temp directory for streams) and loaded into mpv as a new subtitle track.
 
-An API key is required to use the Jimaku integration. You can get one from [jimaku.cc](https://jimaku.cc). There are two ways to provide it:
+| Key              | Action                                 |
+| ---------------- | -------------------------------------- |
+| `Enter`          | Search, or select the highlighted item |
+| `Up` / `Down`    | Move through entries or files          |
+| `Left` / `Right` | Switch tabs                            |
+| `Escape`         | Close                                  |
 
-- **`apiKey`** - set the key directly in config. Simple, but the key is stored in plaintext.
-- **`apiKeyCommand`** - a shell command that outputs the key. Runs with a 10-second timeout. Preferred if you use a secret manager like `pass`, `gpg`, or a keychain tool.
+You can also open the modal with `subminer app --open-jimaku`, or change the shortcut with `shortcuts.openJimaku`.
 
-If both are set, `apiKey` takes priority.
+The file name parser understands `S01E03`, `1x03`, `E03`, `EP03`, and `Title - 03 -` patterns, and reads the season from a parent folder such as `Season 2`. It ignores bracket tags like `[SubGroup]` and year tags like `(2024)`.
 
-## Filename Parsing
+## Options
 
-SubMiner extracts media info from the current video path to pre-fill the search fields. The parser handles:
+| Key                         | What it does                                                        |
+| --------------------------- | ------------------------------------------------------------------- |
+| `jimaku.apiKey`             | API key in plain text.                                              |
+| `jimaku.apiKeyCommand`      | Shell command that prints the API key.                              |
+| `jimaku.languagePreference` | Sorts files tagged with this language first: `ja`, `en`, or `none`. |
+| `jimaku.maxEntryResults`    | Maximum entries per search.                                         |
+| `jimaku.apiBaseUrl`         | API address. Change only for a mirror.                              |
 
-- **Season + episode patterns:** `S01E03`, `1x03`
-- **Episode-only patterns:** `E03`, `EP03`, or dash-separated numbers like `Title - 03 -`
-- **Bracket tags:** `[SubGroup]`, `[1080p]`, `[HEVC]` - stripped before title extraction
-- **Year tags:** `(2024)` - stripped
-- **Dots and underscores:** treated as spaces
-- **Remote/streamed URLs:** SubMiner checks URL query parameters (`title`, `name`, `q`) and path segments to extract a meaningful title
-
-If the parser produces a high-confidence result (title + episode both detected), the search runs automatically when the modal opens. Otherwise, you can adjust the fields manually before searching.
+See [Configuration](/configuration#jimaku) for defaults.
 
 ## Troubleshooting
 
-**"Jimaku API key not set"**
+**"Jimaku API key not set."** Set `jimaku.apiKey` or `jimaku.apiKeyCommand`. Run the command in your shell to confirm it prints only the key.
 
-Configure `jimaku.apiKey` or `jimaku.apiKeyCommand` in your config. If using `apiKeyCommand`, verify the command works in your shell: it should print the key and exit cleanly.
+**HTTP 429.** You hit Jimaku's rate limit. Wait for the time shown in the message and retry.
 
-**"Jimaku request failed" or HTTP 429**
+**No entries found.** Search with just the show's name, without season or episode words. Jimaku matches against its own titles.
 
-The Jimaku API has rate limits. If you see 429 errors, wait for the retry duration shown in the OSD message and try again. An API key provides higher rate limits.
-
-**No entries found**
-
-Try simplifying the title - remove season/episode qualifiers and search with just the anime name. Jimaku's search matches against its own database of anime titles, so the exact spelling matters.
-
-**No files found for this episode**
-
-The entry may not have per-episode files, or files may be named differently. Click "Show all files" to see everything available for the entry.
-
-**Downloaded subtitle not loading**
-
-Verify mpv is running and connected via IPC. SubMiner loads the subtitle by issuing a `sub-add` command over the mpv socket. If mpv is not connected, the download succeeds but the subtitle cannot be loaded.
-
-## Related
-
-- [Configuration Reference](/configuration#jimaku) - full config options
-- [Mining Workflow](/mining-workflow#jimaku-subtitle-search) - how Jimaku fits into the sentence mining loop
-- [Troubleshooting](/troubleshooting#jimaku) - additional error guidance
+**The subtitle downloads but does not load.** SubMiner loads it over the mpv socket. Make sure mpv is still running and connected.

docs-site/launcher-script.md

@@ -1,124 +1,196 @@
-# Launcher Script
+# Launcher script
 
-The `subminer` launcher is an all-in-one script that handles video selection, mpv startup, and overlay management. It is the recommended way to use SubMiner on Linux and macOS because it guarantees mpv is launched with the correct IPC socket and SubMiner defaults. It's a Bun script distributed as a release asset alongside the AppImage and DMG.
+`subminer` is the command-line entry point for SubMiner. It starts mpv with the socket and options SubMiner needs, opens file pickers, and runs helper commands. This page is the reference for its subcommands and flags. For everyday use, start with [Usage](/usage).
 
-::: tip Windows users
-On Windows, the recommended way to launch playback is the **SubMiner mpv** shortcut created during first-run setup - double-click it, drag a file onto it, or run `SubMiner.exe --launch-mpv` from a terminal. See [Windows mpv Shortcut](/usage#windows-mpv-shortcut) for details.
-:::
-
-## Video Picker
-
-When you run `subminer` without specifying a file, it opens an interactive video picker. By default it uses **fzf** in the terminal; pass `-R` to use **rofi** instead.
-
-### fzf (default)
+You do not need Bun or anything else installed to run it. It uses the runtime bundled with the app. On Windows, the **SubMiner mpv** shortcut is the simpler way to play files (see [Windows mpv shortcut](/usage#windows-mpv-shortcut)).
 
 ```bash
-subminer                               # pick from current directory
-subminer -d ~/Videos                   # pick from a specific directory
-subminer -r -d ~/Anime                 # recursive search
+subminer [options] [file | directory | URL]
+subminer <subcommand> [options]
 ```
 
-fzf shows video files in a fuzzy-searchable list. If `chafa` is installed, you get thumbnail previews in the right pane. Thumbnails are sourced from the freedesktop thumbnail cache first, then generated on the fly with `ffmpegthumbnailer` or `ffmpeg` as fallback.
-
-| Optional tool       | Purpose                           |
-| ------------------- | --------------------------------- |
-| `chafa`             | Render thumbnails in the terminal |
-| `ffmpegthumbnailer` | Generate thumbnails on the fly    |
-
-### rofi
-
-```bash
-subminer -R                            # rofi picker, current directory
-subminer -R -d ~/Videos                # rofi picker, specific directory
-subminer -R -r -d ~/Anime              # rofi picker, recursive
-subminer -R /directory                 # rofi picker, directory shortcut
-```
-
-rofi shows a GUI menu with icon thumbnails when available. SubMiner ships a custom rofi theme bundled in the release assets tarball:
-
-```bash
-wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
-tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
-mkdir -p ~/.local/share/SubMiner/themes
-cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi
-```
-
-The theme is auto-detected from these paths (first match wins):
-
-- `$SUBMINER_ROFI_THEME` environment variable (absolute path)
-- `$XDG_DATA_HOME/SubMiner/themes/subminer.rasi` (default: `~/.local/share/SubMiner/themes/subminer.rasi`)
-- `/usr/local/share/SubMiner/themes/subminer.rasi`
-- `/usr/share/SubMiner/themes/subminer.rasi`
-- macOS: `~/Library/Application Support/SubMiner/themes/subminer.rasi`
-
-Override with the `SUBMINER_ROFI_THEME` environment variable:
-
-```bash
-SUBMINER_ROFI_THEME=/path/to/custom-theme.rasi subminer -R
-```
-
-## Common Commands
-
-```bash
-subminer video.mkv                      # play a specific file (default plugin config auto-starts visible overlay)
-subminer https://youtu.be/...           # YouTube playback (requires yt-dlp)
-subminer --backend x11 video.mkv        # Force x11 backend for a specific file
-subminer -u                             # check for SubMiner updates
-subminer logs -e                        # export sanitized log ZIP
-subminer stats                          # open immersion dashboard
-subminer stats -b                       # start background stats daemon
-```
-
-## Subcommands
-
-| Subcommand                                 | Purpose                                                            |
-| ------------------------------------------ | ------------------------------------------------------------------ |
-| `subminer jellyfin` / `jf`                 | Jellyfin workflows (`-d` discovery, `-p` play, `-l` login)         |
-| `subminer stats`                           | Start stats server and open immersion dashboard in browser         |
-| `subminer stats -b`                        | Start or reuse background stats daemon (non-blocking)              |
-| `subminer stats cleanup`                   | Backfill vocabulary metadata and prune stale rows                  |
-| `subminer doctor`                          | Dependency + config + socket diagnostics                           |
-| `subminer settings`                        | Open the SubMiner settings window                                  |
-| `subminer logs -e`                         | Export a sanitized log ZIP and print its path                      |
-| `subminer config path`                     | Print active config file path                                      |
-| `subminer config show`                     | Print active config contents                                       |
-| `subminer mpv status`                      | Check mpv socket readiness                                         |
-| `subminer mpv socket`                      | Print active socket path                                           |
-| `subminer mpv idle`                        | Launch detached idle mpv instance                                  |
-| `subminer dictionary <path>`               | Generate character dictionary ZIP from file/dir target             |
-| `subminer dictionary --candidates <path>`  | List AniList candidate matches for character dictionary correction |
-| `subminer dictionary --select <id> <path>` | Pin an AniList media ID for that target series                     |
-| `subminer texthooker`                      | Launch texthooker-only mode                                        |
-| `subminer texthooker -o`                   | Launch texthooker and open it in the default browser               |
-| `subminer app`                             | Pass arguments directly to SubMiner binary                         |
-
-Use `subminer <subcommand> -h` for command-specific help.
+Run `subminer -h` or `subminer <subcommand> -h` for built-in help.
 
 ## Options
 
 | Flag                  | Description                                                                         |
-| --------------------- | -------------------------------------------------------------------- |
-| `-d, --directory`     | Video search directory (default: cwd)                                |
-| `-r, --recursive`     | Search directories recursively                                       |
+| --------------------- | ----------------------------------------------------------------------------------- |
+| `-d, --directory`     | Directory to browse (default: current directory)                                    |
+| `-r, --recursive`     | Search subdirectories                                                               |
 | `-R, --rofi`          | Use rofi instead of fzf                                                             |
-| `--setup`             | Open first-run setup popup manually                                  |
-| `-v, --version`       | Print installed SubMiner version                                     |
-| `-u, --update`        | Check for SubMiner updates and update the app/launcher when possible |
-| `--start`             | Explicitly start overlay after mpv launches                          |
-| `-S, --start-overlay` | Explicitly start overlay after mpv launches                          |
-| `-T, --no-texthooker` | Disable texthooker server                                            |
-| `-p, --profile`       | mpv profile name (no default; omitted unless set)                    |
-| `-a, --args`          | Pass additional mpv arguments as a quoted string                     |
-| `-b, --backend`       | Force window backend (`hyprland`, `sway`, `x11`, `macos`, `windows`) |
-| `--log-level`         | Logger verbosity (`debug`, `info`, `warn`, `error`)                  |
-| `--dev`, `--debug`    | Enable app dev-mode (not tied to log level)                          |
+| `-H, --history`       | Browse [watch history](#watch-history)                                              |
+| `-b, --backend`       | Window backend: `auto`, `hyprland`, `sway`, `x11`, `macos`, `windows`               |
+| `-p, --profile`       | mpv profile to load                                                                 |
+| `-a, --args`          | Extra mpv options as one quoted string, e.g. `--args "--volume=80"`                 |
+| `--start`             | Start the overlay after mpv launches. Only needed if `mpv.autoStartSubMiner` is off |
+| `-S, --start-overlay` | Show the overlay on start                                                           |
+| `-T, --no-texthooker` | Do not start the texthooker server                                                  |
+| `--settings`          | Open the settings window                                                            |
+| `--log-level`         | `debug`, `info`, `warn`, or `error`                                                 |
+| `-u, --update`        | Check for and install updates                                                       |
+| `-v, --version`       | Print the launcher's version                                                        |
 
-On Linux, `subminer -u` updates from the launcher process itself. It can check and replace the AppImage, launcher, and rofi theme even when SubMiner is already running in the tray.
+The target can be a video file, a directory (opens the picker there), a URL, or `ytsearch:"query"` for the first YouTube search result.
 
-With default plugin settings (`auto_start=yes`, `auto_start_visible_overlay=yes`, `auto_start_pause_until_ready=yes`), explicit start flags are usually unnecessary.
+App flags such as `--setup` and `--dev` are not launcher flags. Pass them through with `subminer app`, for example `subminer app --setup`.
+
+## Subcommands
+
+| Command                                    | What it does                                                                                                         |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `subminer stats`                           | Start the stats dashboard server. Opens your browser if `stats.autoOpenBrowser` is on                                |
+| `subminer stats -b` / `-s`                 | Start (or reuse) the stats server in the background / stop it                                                        |
+| `subminer stats cleanup`                   | Backfill vocabulary metadata and prune stale rows (same as `-v`)                                                     |
+| `subminer stats cleanup -l`                | Rebuild lifetime totals from the retained sessions                                                                   |
+| `subminer stats cleanup -d`                | Collapse repeated lines from typeset subtitles. Add `--dry-run` to preview, `--lookback-days <n>` to limit the range |
+| `subminer stats rebuild` / `backfill`      | Same as `stats cleanup -l`                                                                                           |
+| `subminer sync <host>`                     | Sync stats and watch history with another machine. See [below](#sync-between-machines)                               |
+| `subminer doctor`                          | Check the app, mpv, ffmpeg, yt-dlp, pickers, config, and mpv socket                                                  |
+| `subminer doctor --refresh-known-words`    | Refresh the known-word cache from Anki                                                                               |
+| `subminer settings`                        | Open the settings window                                                                                             |
+| `subminer youtube` / `yt`                  | Open the [YouTube browser](/youtube-integration#browse-youtube-in-subminer). Videos you pick play in mpv             |
+| `subminer generate-subs [video]`           | Generate [Japanese subtitles](/subtitle-generation) with whisper.cpp                                                 |
+| `subminer jellyfin` / `jf`                 | [Jellyfin](/jellyfin-integration) actions: `setup`, `login`, `logout`, `play`, `discovery`                           |
+| `subminer dictionary <path>` / `dict`      | Build a [character dictionary](/character-dictionary) for a file or directory                                        |
+| `subminer dictionary --candidates <path>`  | List AniList matches for that target                                                                                 |
+| `subminer dictionary --select <id> <path>` | Pin an AniList ID for that target                                                                                    |
+| `subminer texthooker`                      | Run only the texthooker server. `-o` opens it in your browser                                                        |
+| `subminer logs -e`                         | Export a sanitized log ZIP and print its path                                                                        |
+| `subminer config path` / `show`            | Print the config file path or its contents                                                                           |
+| `subminer mpv status`                      | Exit 0 if the mpv socket is ready, 1 if not                                                                          |
+| `subminer mpv socket`                      | Print the mpv socket path                                                                                            |
+| `subminer mpv idle`                        | Start an idle mpv in the background with SubMiner's options                                                          |
+| `subminer app` / `bin`                     | Pass arguments to the SubMiner app, e.g. `subminer app --stop`                                                       |
+
+`stats cleanup` runs one mode at a time. `--lookback-days` must be at least 1. Without it, cleanup scans all history.
+
+`generate-subs` options: `--download-model`, `--model <name>`, `--model-path <file>`, `--output <file>`, and `--audio-stream <index>` (an ffprobe stream index). `--model-path` cannot be combined with `--model` or `--download-model`.
+
+A texthooker is a web page that shows the current subtitle as plain text, so browser extensions and other tools can read along.
+
+## Video picker
+
+With no file argument, `subminer` opens a picker for the current directory, or for `-d <dir>`. Add `-r` to include subdirectories.
+
+- **fzf** (default) runs in the terminal. With `chafa` installed, it shows thumbnail previews.
+- **rofi** (`-R`, Linux) opens a graphical menu with thumbnails.
+
+Thumbnails come from your system thumbnail cache, or are generated with `ffmpegthumbnailer` or `ffmpeg`.
+
+The launcher installs its rofi theme automatically. To use your own, set `SUBMINER_ROFI_THEME`:
+
+```bash
+SUBMINER_ROFI_THEME=/path/to/theme.rasi subminer -R
+```
+
+## Watch history
+
+`subminer -H` lists the shows you have watched, most recent first. Add `-R` to use rofi. Pick a show, then choose:
+
+- **Previous episode** or **Next episode**, moving into the neighboring season folder when needed
+- **Replay last watched**
+- **Browse episodes**, with a season menu first if the show has several season folders
+- **Quit SubMiner**
+
+When an episode ends, the menu comes back for the same show. Press `Escape` to leave.
+
+History comes from the immersion stats database, which SubMiner fills during playback. Shows whose folders are not reachable, such as an unmounted network drive, are hidden.
+
+## mpv options and profiles
+
+The launcher starts mpv with these options:
+
+```
+--input-ipc-server=/tmp/subminer-socket
+--alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us
+--slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us
+--sub-auto=fuzzy
+--sub-file-paths=.;subs;subtitles
+--sid=auto
+--secondary-sid=auto
+--sub-visibility=no
+--secondary-sub-visibility=no
+```
+
+mpv's own subtitles are hidden because the overlay draws them. Add more options with `-a`, or load an mpv profile with `-p <name>` or `mpv.profile` in the config. No profile is loaded by default.
+
+To launch mpv yourself with the same setup, put the options in a profile in `~/.config/mpv/mpv.conf`:
+
+```ini
+[subminer]
+input-ipc-server=/tmp/subminer-socket
+alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us
+slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us
+sub-auto=fuzzy
+sub-file-paths=.;subs;subtitles
+sid=auto
+secondary-sid=auto
+secondary-sub-visibility=no
+```
+
+Launches through `subminer` start the overlay automatically unless `mpv.autoStartSubMiner` is off. mpv started outside SubMiner does not start the overlay on its own.
+
+## Sync between machines
+
+`subminer sync <host>` merges immersion stats and watch history between two computers over SSH. Both end up with the combined sessions, totals, vocabulary, charts, and `-H` history. `<host>` is anything `ssh` accepts, such as `user@hostname` or an alias from your SSH config.
+
+Both machines need the same SubMiner version. The remote only needs the app. The `subminer` command is optional there.
+
+```bash
+subminer sync macbook                    # two-way sync
+subminer sync macbook --push             # send local data to macbook only
+subminer sync macbook --pull             # bring macbook data here only
+subminer sync macbook --check            # test SSH and the remote install, change nothing
+subminer sync macbook --remote-cmd ~/Apps/SubMiner.AppImage   # SubMiner in a custom place on the remote
+subminer sync --ui                       # open the sync window
+```
+
+Syncing only adds data. It never overwrites or double-counts, so you can run it as often as you like. `--push` and `--pull` do not delete anything on the receiving side.
+
+Before a command-line sync, close SubMiner on both machines and stop the stats server with `subminer stats -s`, or pass `--force`. The sync window does not need this. It syncs while SubMiner and playback are running, and skips the session in progress until it finishes.
+
+Transfers are compressed. When both machines have `rsync` (macOS and Linux), later syncs send only what changed. Windows machines use `scp`.
+
+Known-word status from Anki does not sync. Each machine reads it from its own Anki collection.
+
+<details>
+<summary><b>More sync options</b></summary>
+
+| Option              | Description                                                 |
+| ------------------- | ----------------------------------------------------------- |
+| `-f, --force`       | Skip the check that SubMiner is closed                      |
+| `--db <file>`       | Use a different local stats database                        |
+| `--json`            | Print progress as NDJSON                                    |
+| `--snapshot <file>` | Write a snapshot of the local database, e.g. to copy by USB |
+| `--merge <file>`    | Merge a snapshot file into the local database               |
+
+A Windows remote needs the built-in **OpenSSH Server** enabled. SubMiner finds itself in the default install location there.
+
+If the remote cannot find SubMiner, point `--remote-cmd` at the app or launcher, or link it as `SubMiner` somewhere on the remote `PATH`.
+
+Received snapshots are cached in `sync-transfer-cache/` in the config directory to speed up later syncs. Deleting it is safe.
+
+</details>
+
+### Sync window
+
+`subminer sync --ui`, or **Sync Stats & History** in the tray, opens a window where you can:
+
+- Save devices, each with a direction (two-way, push, or pull), and run **Sync now** or **Test**.
+- Turn on **Auto-sync** for a device. It syncs in the background every 60 minutes by default, including during playback.
+- Watch progress and see what was merged on each machine.
+- Create, merge, or delete database snapshots.
+
+Saved devices live in `sync-hosts.json` in the config directory.
+
+## Environment variables
+
+| Variable                 | Use                                                                   |
+| ------------------------ | --------------------------------------------------------------------- |
+| `SUBMINER_BINARY_PATH`   | Path to the SubMiner app, if it is not in a standard install location |
+| `SUBMINER_APPIMAGE_PATH` | Same, for an AppImage (Linux)                                         |
+| `SUBMINER_ROFI_THEME`    | Path to a custom rofi theme                                           |
 
 ## Logging
 
-- Default log level is `info`
-- `--background` mode defaults to `warn` unless `--log-level` is explicitly set
-- `--dev` / `--debug` control app behavior, not logging verbosity - use `--log-level` for that
+The default log level is `warn`. Change it for one run with `--log-level`, or permanently with `logging.level` in the config. The app's `--dev` and `--debug` flags turn on developer mode. They do not change the log level.

docs-site/links.test.ts

@@ -0,0 +1,135 @@
+import { expect, test } from 'bun:test';
+import { readdirSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const docsSiteDir = fileURLToPath(new URL('.', import.meta.url));
+
+// Mirrors VitePress' heading slugifier (vitepress/dist/node, `rControl` + `rSpecial`).
+// Note that a *run* of special characters collapses to a single `-`, so
+// "KDE Plasma & other" becomes "kde-plasma-other", not "kde-plasma--other".
+const rControl = new RegExp('[\\u0000-\\u001f]', 'g');
+const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g;
+
+function slugify(heading: string): string {
+  return heading
+    .replace(rControl, '')
+    .replace(rSpecial, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/^(\d)/, '_$1')
+    .toLowerCase();
+}
+
+const EXCLUDED_PAGES = new Set(['README.md']);
+const UNLISTED_ROUTES = new Set(['/demos']);
+const PUBLIC_PREFIXES = ['/assets/', '/screenshots/', '/config.example.jsonc', '/favicon'];
+
+function loadPages(): Map<string, string> {
+  const pages = new Map<string, string>();
+  for (const file of readdirSync(docsSiteDir)) {
+    if (!file.endsWith('.md') || EXCLUDED_PAGES.has(file)) continue;
+    const route = `/${file.replace(/\.md$/, '')}`;
+    pages.set(route, readFileSync(`${docsSiteDir}${file}`, 'utf8'));
+  }
+  return pages;
+}
+
+function anchorsFor(contents: string): Set<string> {
+  const anchors = new Set<string>();
+  for (const match of contents.matchAll(/^#{1,6}\s+(.+?)\s*$/gm)) {
+    let heading = match[1]!;
+    const explicitId = heading.match(/\{#([^}]+)\}\s*$/);
+    if (explicitId) {
+      anchors.add(explicitId[1]!);
+      heading = heading.replace(/\{#[^}]+\}\s*$/, '');
+    }
+    anchors.add(slugify(heading.replace(/`/g, '')));
+  }
+  return anchors;
+}
+
+function resolveRoute(target: string, fromRoute: string): string {
+  if (target === '') return fromRoute;
+  if (target.startsWith('./')) return `/${target.slice(2).replace(/\.md$/, '')}`;
+  const normalized = target.replace(/\.md$/, '').replace(/\/$/, '');
+  return normalized === '' ? '/index' : normalized;
+}
+
+const pages = loadPages();
+const anchors = new Map([...pages].map(([route, body]) => [route, anchorsFor(body)]));
+
+test('every internal docs link resolves to an existing page', () => {
+  const broken: string[] = [];
+
+  for (const [route, body] of pages) {
+    for (const match of body.matchAll(/\]\((\/[^)\s]*|\.\/[^)\s]*)\)/g)) {
+      const link = match[1]!;
+      const target = link.split('#')[0]!;
+      if (PUBLIC_PREFIXES.some((prefix) => target.startsWith(prefix))) continue;
+
+      const resolved = resolveRoute(target, route);
+      if (resolved !== '/index' && !pages.has(resolved)) {
+        broken.push(`${route.slice(1)}.md -> ${link}`);
+      }
+    }
+  }
+
+  expect(broken).toEqual([]);
+});
+
+test('every internal docs anchor matches a real heading slug', () => {
+  const broken: string[] = [];
+
+  for (const [route, body] of pages) {
+    for (const match of body.matchAll(/\]\((\/[^)\s]*|\.\/[^)\s]*|#[^)\s]*)\)/g)) {
+      const link = match[1]!;
+      const hashIndex = link.indexOf('#');
+      if (hashIndex < 0) continue;
+
+      const target = link.slice(0, hashIndex);
+      const anchor = link.slice(hashIndex + 1);
+      if (PUBLIC_PREFIXES.some((prefix) => target.startsWith(prefix))) continue;
+
+      const resolved = resolveRoute(target, route);
+      const pageAnchors = anchors.get(resolved);
+      if (!pageAnchors || pageAnchors.has(anchor)) continue;
+
+      broken.push(`${route.slice(1)}.md -> ${link}`);
+    }
+  }
+
+  expect(broken).toEqual([]);
+});
+
+test('slugify matches the VitePress cases these docs actually rely on', () => {
+  // Regression guards for the anchors that were previously wrong.
+  expect(slugify('N+1 Word Highlighting')).toBe('n-1-word-highlighting');
+  expect(slugify('KDE Plasma & other Wayland compositors')).toBe(
+    'kde-plasma-other-wayland-compositors',
+  );
+  expect(slugify('Proxy Mode Setup (Yomitan / Texthooker)')).toBe(
+    'proxy-mode-setup-yomitan-texthooker',
+  );
+  expect(slugify('Kiku/Lapis Integration')).toBe('kiku-lapis-integration');
+  expect(slugify('Secondary Subtitles')).toBe('secondary-subtitles');
+  expect(slugify('2. Install SubMiner')).toBe('_2-install-subminer');
+});
+
+test('every docs page is reachable from the sidebar unless explicitly unlisted', async () => {
+  const { default: config } = await import('./.vitepress/config');
+  const sidebar = config.themeConfig?.sidebar as Array<{
+    items?: Array<{ text: string; link?: string }>;
+  }>;
+
+  const linked = new Set<string>();
+  for (const group of sidebar) {
+    for (const item of group.items ?? []) {
+      if (item.link) linked.add(item.link === '/' ? '/index' : item.link);
+    }
+  }
+
+  const orphans = [...pages.keys()].filter(
+    (route) => !linked.has(route) && !UNLISTED_ROUTES.has(route),
+  );
+  expect(orphans).toEqual([]);
+});

docs-site/mining-workflow.md

@@ -1,189 +1,87 @@
-# Mining Workflow
+# Mining workflow
 
-This guide walks through the sentence mining loop - from watching a video to creating Anki cards with audio, screenshots, and context.
+SubMiner turns lines from the video you are watching into Anki cards. You look up a word on the overlay, add it with Yomitan, and SubMiner fills in the sentence, an audio clip, and a screenshot. For Anki setup, field mapping, and media options, see [Anki integration](/anki-integration).
 
-## Overview
+## Look up a word
 
-_Sentence mining_ means turning real sentences you encounter while watching native video into Anki flashcards, so you learn vocabulary in the context where you actually met it. SubMiner automates the tedious parts of that loop.
+1. Hover the subtitle line on the overlay. Each word is its own hover target.
+2. Press your Yomitan scan key or modifier (whatever your Yomitan profile uses, for example `Shift`).
+3. The Yomitan popup opens for that word.
 
-SubMiner runs as a transparent overlay on top of mpv (the video player). As subtitles play, the overlay displays them as interactive text. You hover a word, trigger a Yomitan dictionary lookup with your configured lookup key/modifier, then create an Anki card with a single action. SubMiner automatically attaches the sentence, an audio clip, and a screenshot to that card - no manual copy-pasting or screen capturing.
+Playback pauses while you hover the subtitle and while the Yomitan popup is open. Turn this off with `subtitleStyle.autoPauseVideoOnHover` and `subtitleStyle.autoPauseVideoOnYomitanPopup`.
 
-> **Yomitan** is the popup dictionary that shows definitions when you hover or scan a word. **AnkiConnect** is the add-on that lets SubMiner talk to Anki. Both are set up during installation - see [Anki Integration](/anki-integration) if you have not configured them yet.
+## Add a word card
 
-## Creating Anki Cards
+Click the add button in the Yomitan popup. SubMiner sees the new note and fills it in:
 
-There are four ways to create or enrich cards, depending on your workflow.
+| Field    | Content                                                |
+| -------- | ------------------------------------------------------ |
+| Sentence | The current subtitle line, with the mined word in bold |
+| Audio    | A clip cut from the video using the subtitle's timing  |
+| Image    | A screenshot, or an animated AVIF clip of the line     |
+| MiscInfo | Source file name and timestamp                         |
 
-### 1. Auto-Update from Yomitan
+Which note fields receive each item is set in [`ankiConnect.fields`](/anki-integration#field-mapping). With the default proxy mode the card is filled as soon as Yomitan adds it. If you disable the proxy, SubMiner polls Anki and fills the card a few seconds later.
 
-This is the most common flow. Yomitan creates a card in Anki, and SubMiner enriches it automatically.
+## Update the last card by hand
 
-1. Hover a word, then trigger Yomitan lookup → Yomitan popup appears.
-2. Click the Anki icon in Yomitan to add the word.
-3. SubMiner receives or detects the new card:
-   - **Proxy mode** (default, `ankiConnect.proxy.enabled: true`): immediate enrich after a successful `addNote` / `addNotes` is pushed through the local proxy.
-   - **Polling mode** (fallback, when the proxy is disabled): detects new cards via AnkiConnect polling (`ankiConnect.pollingRate`, default 3 seconds).
-4. SubMiner updates the card with:
-   - **Sentence**: The current subtitle line.
-   - **Audio**: Extracted from the video using the subtitle's start/end timing (plus optional configured padding).
-   - **Image**: A screenshot or animated clip from the current playback position.
-   - **Translation**: From the secondary subtitle track, or generated via AI if configured.
-   - **MiscInfo**: Metadata like filename and timestamp.
+Use this when auto-update is off, or when the line you want is not the one on screen.
 
-Configure which fields to fill in `ankiConnect.fields`. See [Anki Integration](/anki-integration) for details.
+1. Add the word with Yomitan.
+2. Press `Ctrl/Cmd+C` to copy the current line. To combine lines, press `Ctrl/Cmd+Shift+C`, then a digit `1` to `9` for how many recent lines to include.
+3. Press `Ctrl/Cmd+V`. SubMiner writes the clipboard text into the last-added card's sentence field and adds fresh audio and an image.
 
-### 2. Manual Update from Clipboard
+A manual update always replaces the sentence audio, even when `ankiConnect.behavior.overwriteAudio` is `false`.
 
-If you prefer a hands-on approach (animecards-style), you can copy the current subtitle to the clipboard and then paste it onto the last-added Anki card:
+## Mine a sentence card
 
-1. Add a word via Yomitan as usual.
-2. Press `Ctrl/Cmd+C` to copy the current subtitle line to the clipboard.
-   - For multiple lines: press `Ctrl/Cmd+Shift+C`, then a digit `1`–`9` to select how many recent subtitle lines to combine. The combined text is copied to the clipboard.
-3. Press `Ctrl/Cmd+V` to update the last-added card with the clipboard contents plus audio, image, and translation - the same fields auto-update would fill.
+Press `Ctrl/Cmd+S` to create a sentence card from the current line without a Yomitan lookup. Press `Ctrl/Cmd+Shift+S`, then a digit `1` to `9`, to combine several recent lines into one card. The digit prompt closes after `shortcuts.multiCopyTimeoutMs`.
 
-Manual clipboard updates always replace generated sentence audio, even when `ankiConnect.behavior.overwriteAudio` is disabled. The word audio field is left unchanged because the word itself does not change in this flow.
+Sentence cards use the note type named in `ankiConnect.isLapis.sentenceCardModel` and write to its `Sentence` and `SentenceAudio` fields. That note type must exist in Anki. See [sentence cards](/anki-integration#sentence-cards-lapis).
 
-This is useful when auto-update is disabled or when you want explicit control over which subtitle line gets attached to the card.
+## Mark an audio card
 
-| Shortcut                   | Action                          | Config key                              |
-| -------------------------- | ------------------------------- | --------------------------------------- |
-| `Ctrl/Cmd+C`               | Copy current subtitle           | `shortcuts.copySubtitle`                |
-| `Ctrl/Cmd+Shift+C` + digit | Copy multiple recent lines      | `shortcuts.copySubtitleMultiple`        |
-| `Ctrl/Cmd+V`               | Update last card from clipboard | `shortcuts.updateLastCardFromClipboard` |
+After adding a word, press `Ctrl/Cmd+Shift+A`. SubMiner sets the Lapis/Kiku `IsAudioCard` flag on the last-added card and fills `Sentence`, `SentenceAudio`, the image, and MiscInfo.
 
-### 3. Mine Sentence (Hotkey)
+## Merge repeated words
 
-Create a standalone sentence card without going through Yomitan:
+If you mine a word you already have a card for, SubMiner can merge the new sentence, audio, and image into the existing card instead of keeping a duplicate. This needs the Kiku or Senren note type with field grouping turned on. In manual mode a dialog shows both cards and lets you pick which one to keep. See [field grouping](/anki-integration#field-grouping-kiku-senren).
 
-- **Mine current sentence**: `Ctrl/Cmd+S` (configurable via `shortcuts.mineSentence`)
-- **Mine multiple lines**: `Ctrl/Cmd+Shift+S` followed by a digit 1–9 to select how many recent subtitle lines to combine.
+## Subtitle display
 
-The sentence card uses the note type configured in `isLapis.sentenceCardModel` and always maps sentence/audio to `Sentence` and `SentenceAudio`.
+The overlay has a primary subtitle bar (the Japanese line you mine from) and a secondary bar for a translation track. Each bar is hidden, visible, or shown only on hover.
 
-::: warning Requires Lapis/Kiku note type
-Sentence card creation requires a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type and `ankiConnect.isLapis.enabled: true` in your config. See [Anki Integration - Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
-:::
+| Shortcut           | Action                             |
+| ------------------ | ---------------------------------- |
+| `V`                | Cycle primary bar mode             |
+| `Ctrl/Cmd+Shift+V` | Cycle secondary bar mode           |
+| `Shift+J`          | Cycle the secondary subtitle track |
+| Right-click        | Pause or resume                    |
+| Right-click + drag | Move the subtitles                 |
 
-### 4. Mark as Audio Card
+Set the starting modes with `subtitleStyle.primaryDefaultMode` and `secondarySub.defaultMode`. The full list of keys is on [Keyboard shortcuts](/shortcuts).
 
-After adding a word via Yomitan, press the audio card shortcut to overwrite the audio with a longer clip spanning the full subtitle timing.
+## Controller
 
-::: warning Requires Lapis/Kiku note type
-Audio card marking requires a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type and `ankiConnect.isLapis.enabled: true` in your config. See [Anki Integration - Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
-:::
+With a gamepad and keyboard-only mode on, you can mine without a mouse: move across words with the left stick, look up with `A`, mine with `X`, and close the popup with `B`. The keyboard keeps working alongside it. See [controller support](/usage#controller-support).
 
-### Field Grouping (Kiku)
+## Fix subtitle timing (subsync)
 
-If you mine the same word from different sentences, SubMiner can merge the cards instead of creating duplicates. This feature is designed for use with [Kiku](https://github.com/youyoumu/kiku) and similar note types that support grouped fields.
+If the subtitles are out of sync, press `Ctrl+Alt+S` to open the subsync dialog. It uses [alass](https://github.com/kaegi/alass) or [ffsubsync](https://github.com/smacke/ffsubsync), which you install separately.
 
-1. You add a word via Yomitan.
-2. SubMiner detects the new card and checks if a card with the same expression already exists.
-3. If a duplicate is found (this requires `ankiConnect.isKiku.fieldGrouping` to be set to `"auto"` or `"manual"`; it defaults to `"disabled"`):
-   - **Auto mode** (`ankiConnect.isKiku.fieldGrouping: "auto"`): Merges automatically. Both sentences, audio clips, and images are combined into the existing card. The duplicate is optionally deleted.
-   - **Manual mode** (`ankiConnect.isKiku.fieldGrouping: "manual"`): A modal appears showing both cards side by side. You choose which card to keep and preview the merged result before confirming.
+1. Pick the engine.
+2. For alass, pick a reference: a subtitle track with correct timing (the secondary track by default) or the video file.
+3. Pick the track to retime (the active primary track by default).
+4. Run it. SubMiner loads the retimed subtitle back into the same slot.
 
-See [Anki Integration - Field Grouping](/anki-integration#field-grouping-kiku) for configuration options, merge behavior, and modal keyboard shortcuts.
-
-## Overlay Model
-
-SubMiner uses one overlay window with modal surfaces. It carries two subtitle bars - a primary reading bar and a secondary translation/context bar - plus modal dialogs that open on top.
-
-Toggle the entire overlay window with `Alt+Shift+O` (global) or `y-t` (mpv plugin).
-
-### Primary Subtitle Layer
-
-The primary bar renders subtitles as tokenized hoverable word spans. Each word is a separate element with reading and headword data attached. This plane is styled independently from mpv subtitles and supports:
-
-- Word-level hover targets for Yomitan lookup
-- Auto pause/resume on subtitle hover (enabled by default via `subtitleStyle.autoPauseVideoOnHover`)
-- Auto pause/resume while the Yomitan popup is open (enabled by default via `subtitleStyle.autoPauseVideoOnYomitanPopup`)
-- Right-click to pause/resume
-- Right-click + drag to reposition subtitles
-- **Reading annotations** - known words, N+1 targets, character-name matches, JLPT levels, and frequency hits can all be visually highlighted
-
-### Secondary Subtitle Bar
-
-The secondary bar is a compact top-strip region in the same overlay window. It shows a secondary subtitle track (typically English) for translation/context while keeping the primary reading flow below. It is useful for:
-
-- Quick comprehension checks without leaving the mining flow.
-- Auto-populating the translation field on mined cards - when a card is created, SubMiner uses the secondary subtitle text as the translation field value (unless AI translation is configured to override it).
-
-It is controlled by `secondarySub` configuration and shares its lifecycle with the main overlay window. Cycle which track feeds it with `Shift+J`.
-
-### Display Modes
-
-Both the primary and secondary subtitle bars share the same three visibility modes, and each can be changed independently at runtime:
-
-- **Hidden** - the bar is not shown.
-- **Visible** - the bar is always shown.
-- **Hover** - the bar is revealed only while you hover over the overlay.
-
-By default the **primary** bar is `visible` (`subtitleStyle.primaryDefaultMode`) and the **secondary** bar is `hover` (`secondarySub.defaultMode`).
-
-Cycle each bar's mode at runtime with its own shortcut:
-
-| Shortcut           | Action                                                   | Config key                     |
-| ------------------ | -------------------------------------------------------- | ------------------------------ |
-| `V`                | Cycle primary subtitle mode (hidden → visible → hover)   | overlay-local                  |
-| `Ctrl/Cmd+Shift+V` | Cycle secondary subtitle mode (hidden → visible → hover) | `shortcuts.toggleSecondarySub` |
-
-### Modal Surfaces
-
-Jimaku search, field-grouping, runtime options, and manual subsync open as modal surfaces on top of the same overlay window.
-
-## Looking Up Words
-
-1. Hover over the subtitle area - the overlay activates pointer events.
-2. Hover the word you want. SubMiner keeps per-token boundaries so Yomitan can target that token cleanly.
-3. Trigger Yomitan lookup with your configured lookup key/modifier (for example `Shift` if that is how your Yomitan profile is set up).
-4. Yomitan opens its lookup popup for the hovered token.
-5. From the popup, add the word to Anki.
-
-### Controller Workflow
-
-With a gamepad connected and keyboard-only mode enabled, the full mining loop works without a mouse or keyboard:
-
-1. **Navigate** - push the left stick left/right to move the token highlight across subtitle words.
-2. **Look up** - press `A` to trigger Yomitan lookup on the highlighted word.
-3. **Browse the popup** - push the left stick up/down to smooth-scroll through the Yomitan popup, or use the right stick for larger jumps.
-4. **Cycle audio** - press `R1` to move to the next dictionary audio entry, `L1` to play the current one.
-5. **Mine** - press `X` to create an Anki card for the current sentence (same as `Ctrl+S`).
-6. **Close** - press `B` to dismiss the Yomitan popup and return to subtitle navigation.
-7. **Pause/resume** - press `L3` (left stick click) to toggle mpv pause at any time.
-
-After controller support is enabled, the controller and keyboard can be used interchangeably - switching mid-session is seamless. Toggle keyboard-only mode on or off with `Y` on the controller.
-
-See [Usage - Controller Support](/usage#controller-support) for setup details and [Configuration - Controller Support](/configuration#controller-support) for the full mapping and tuning options.
-
-## Subtitle Sync (Subsync)
-
-If your subtitle file is out of sync with the audio, SubMiner can resynchronize it using [alass](https://github.com/kaegi/alass) or [ffsubsync](https://github.com/smacke/ffsubsync).
-
-1. Open the subsync modal from the overlay.
-2. Select the sync engine (alass or ffsubsync).
-3. For alass, select a reference subtitle track from the video.
-4. SubMiner runs the sync and reloads the corrected subtitle.
-
-For remote streams, including Jellyfin playback, the modal only offers alass. Jellyfin subtitle URLs are cached as temporary subtitle files so alass can read them, but the video stream is not downloaded. ffsubsync needs direct access to the local media file and is unavailable for stream URLs.
-
-When you mine a sentence card from the stats dashboard, SubMiner can also use `alass` automatically to align a local English sidecar against the matching local Japanese sidecar before filling the card translation field. The source subtitle files are not modified; SubMiner writes a temporary retimed copy and reuses it while the stats server is running.
-
-Install the sync tools separately - see [Troubleshooting](/troubleshooting#subtitle-sync-subsync) if the tools are not found.
+For remote streams such as Jellyfin, only alass with a subtitle reference is available, because ffsubsync and the video reference need the local file. If the tools are not found, see [Troubleshooting](/troubleshooting#subtitle-sync-subsync).
 
 ## Texthooker
 
-SubMiner runs a local HTTP server at `http://127.0.0.1:5174` (configurable port) that serves a texthooker UI. This allows external tools - such as a browser-based Yomitan instance - to receive subtitle text in real time.
+SubMiner can serve a texthooker page at `http://127.0.0.1:5174` that shows each subtitle line as it arrives, so you can do lookups in a browser instead of on the overlay. Start it with `texthooker.launchAtStartup`, the `--texthooker` flag, or the mpv plugin's `texthooker_enabled` option. Change the port with the plugin's `texthooker_port` option. To build your own client, see the [WebSocket / texthooker API](/websocket-texthooker-api).
 
-The texthooker page displays the current subtitle and updates as new lines arrive. This is useful if you prefer to do lookups in a browser rather than through the overlay's built-in Yomitan.
+## Related features
 
-If you want to build your own browser client, websocket consumer, or automation relay, see [WebSocket / Texthooker API & Integration](/websocket-texthooker-api).
-
-## Related Features
-
-These features support the mining loop but have their own dedicated pages:
-
-- **[Jimaku subtitle search](/jimaku-integration)** - search and download anime subtitle files directly from the overlay (`Ctrl+Shift+J` by default), then load them into mpv.
-- **[N+1 word highlighting](/subtitle-annotations#n1-word-highlighting)** - cross-reference your Anki decks to highlight known words, making true N+1 sentences (exactly one unknown word) easy to spot during immersion.
-- **[Immersion tracking](/immersion-tracking)** - log watching and mining activity to a local database and view session times, words seen, and cards mined in the built-in stats dashboard.
-
-Next: [Anki Integration](/anki-integration) - field mapping, media generation, and card enrichment configuration.
+- [Jimaku](/jimaku-integration): search and download subtitle files from the overlay (`Ctrl+Shift+J`).
+- [Subtitle annotations](/subtitle-annotations): highlight known words, N+1 targets, JLPT levels, and frequency.
+- [Immersion tracking](/immersion-tracking): log watch time and cards mined, and view them in the stats dashboard.

docs-site/mpv-plugin.md

@@ -1,130 +1,112 @@
-# MPV Plugin
+# MPV plugin
 
-**What this is:** mpv is the video player SubMiner overlays subtitles on. The SubMiner mpv plugin is a small Lua script that runs _inside_ mpv and gives you in-player keybindings to control the SubMiner overlay (start/stop/toggle, skip intro, etc.) without leaving the player window.
+The SubMiner mpv plugin is a Lua script that runs inside mpv. It adds in-player keys to start, stop, and toggle the overlay, and it runs your SubMiner shortcuts from inside mpv.
 
-**Who needs this page:** Most users never touch the plugin directly - SubMiner-managed launches (the app, the `subminer` launcher, or the Windows shortcut) inject the bundled plugin automatically for that session, so there is nothing to install into mpv's global `scripts` directory. Read on if you launch mpv from another tool and want SubMiner's in-player controls, or you want to script mpv against SubMiner.
+## Setup
 
-The plugin ships as a modular Lua package under `plugin/subminer/` (entry point `init.lua`, which loads `main.lua` and sibling modules). Earlier releases shipped a single global `main.lua`; runtime loading replaces it.
+You usually do not install anything. Every SubMiner-managed launch (the app, the `subminer` launcher, and the Windows SubMiner mpv shortcut) loads the bundled plugin for that session only. Regular mpv playback is not affected.
 
-## Runtime Loading
+On Linux, the launcher's copy lives in `$XDG_DATA_HOME/SubMiner/plugin/subminer` (default `~/.local/share/SubMiner/plugin/subminer`), or under `/usr/local/share/SubMiner` or `/usr/share/SubMiner` for system installs. `subminer -u` and the tray updater keep it current.
 
-Launch mpv through the SubMiner app, the `subminer` launcher, or the packaged Windows SubMiner mpv shortcut. These paths pass mpv a bundled plugin path for that playback session only, leaving regular mpv playback untouched.
+To use the plugin when mpv is started by another program, load its `main.lua` and enable IPC:
 
-If setup detects an older global SubMiner plugin in mpv's `scripts` directory, use **Remove legacy mpv plugin** in first-run setup. The global plugin is not needed once runtime loading is available.
+```bash
+mpv --script="$HOME/.local/share/SubMiner/plugin/subminer/main.lua" \
+  --input-ipc-server=/tmp/subminer-socket video.mkv
+```
 
-mpv must have IPC enabled for SubMiner to connect:
+To enable IPC for every mpv session, add it to `mpv.conf`:
 
 ```ini
-# ~/.config/mpv/mpv.conf
 input-ipc-server=/tmp/subminer-socket
 ```
 
-On Windows, use a named pipe instead:
+On Windows, use a named pipe:
 
 ```ini
 input-ipc-server=\\.\pipe\subminer-socket
 ```
 
+If first-run setup finds an old SubMiner plugin in mpv's global `scripts` directory, click **Remove legacy mpv plugin**. It is no longer needed.
+
 ## Keybindings
 
-Most plugin actions use a `y` chord prefix - press `y`, then the second key (a "chord"):
+Most plugin keys are chords: press `y`, then the second key.
 
-| Chord           | Action                                 |
-| --------------- | -------------------------------------- |
-| `y-y`           | Open menu                              |
-| `y-s`           | Start overlay                          |
-| `y-S`           | Stop overlay                           |
-| `y-t`           | Toggle visible overlay                 |
-| `y-o`           | Open settings window                   |
-| `y-r`           | Restart overlay                        |
+| Key   | Action                                 |
+| ----- | -------------------------------------- |
+| `y-y` | Open the SubMiner menu                 |
+| `y-s` | Start the overlay                      |
+| `y-S` | Stop the overlay                       |
+| `y-t` | Toggle the visible overlay             |
+| `y-o` | Open the settings window               |
+| `y-r` | Restart the overlay                    |
 | `y-c` | Check status                           |
-| `y-h`           | Open session help / keybinding modal   |
-| `v`             | Toggle primary subtitle bar visibility |
-| `TAB` (default) | Skip intro (AniSkip)                   |
+| `y-h` | Open the session help modal            |
+| `v`   | Toggle SubMiner's primary subtitle bar |
 
-The AniSkip key is **not** a `y` chord and is not bound by the plugin: the SubMiner app binds it over the mpv IPC socket while it is connected. It defaults to `TAB` and is configurable via `mpv.aniskipButtonKey`. The legacy `y-k` chord still works as a fallback unless you remap the AniSkip key onto it. See [AniSkip Integration](/aniskip-integration) for setup and details.
+`v` replaces mpv's own subtitle visibility toggle.
 
-The bare `v` binding is a forced mpv binding. It overrides mpv's default primary subtitle visibility toggle and routes the action to SubMiner's primary subtitle bar instead.
+The skip-intro key (`TAB` by default) comes from the SubMiner app, not the plugin. See [AniSkip integration](/aniskip-integration).
 
-## Shared Shortcuts (Session Bindings)
+The `y-y` menu lists Start overlay, Stop overlay, Toggle overlay, Open options, Restart overlay, Check status, and Stats. Press an item's number to run it. Stats only reminds you to press `` ` `` in the overlay.
 
-The `y-*` chords above are built into the plugin. Everything else you configure under [`shortcuts.*`](/shortcuts) - plus any custom [`keybindings`](/configuration) and the stats toggle/mark-watched keys - is **injected into mpv at runtime**, so the same shortcut works both inside mpv and in the SubMiner overlay. You do not edit any mpv config to enable them.
+## Your shortcuts in mpv
 
-How it works:
+Everything you set under [`shortcuts`](/shortcuts), your custom `keybindings`, and the stats keys also work while mpv has focus. SubMiner writes them to `session-bindings.json` in its config directory, and the plugin registers them as mpv keys. When you change a shortcut, mpv picks it up immediately.
 
-1. The SubMiner app compiles your configured shortcuts, custom keybindings, and stats keys into a normalized list and writes it to `session-bindings.json` in the SubMiner config directory.
-2. On load, the plugin reads that file and registers each entry as a forced mpv key binding, translating each accelerator into the matching mpv key name.
-3. When a binding fires, the plugin either runs a SubMiner action (by invoking the SubMiner binary with the corresponding CLI flag, e.g. `--mine-sentence`) or runs a raw mpv command, depending on what the shortcut maps to.
+`CommandOrControl` becomes `Cmd` on macOS and `Ctrl` elsewhere. Multi-line copy and mine shortcuts wait for a digit key `1` to `9`, and `Esc` cancels. If two shortcuts map to the same key, or a key has no mpv equivalent, SubMiner logs a warning and skips it.
 
-Because the bindings come from the same configuration the overlay uses, you maintain one set of shortcuts for both surfaces.
+## Script options
 
-Live updates: changing a shortcut in the app rewrites `session-bindings.json` and sends the plugin a `subminer-reload-session-bindings` script message, so mpv re-registers the bindings immediately - no mpv restart required.
+The plugin reads `script-opts` with the `subminer-` prefix, for example `--script-opts=subminer-backend=hyprland`. Managed launches set these from your SubMiner config, so edit the config instead. The shipped `plugin/subminer.conf` is empty on purpose, so it never overrides those values.
 
-Notes:
+| Option                                         | Default          | SubMiner config key          | What it does                                                          |
+| ---------------------------------------------- | ---------------- | ---------------------------- | --------------------------------------------------------------------- |
+| `binary_path`                                  | `""`             | `mpv.subminerBinaryPath`     | SubMiner binary. Empty uses [auto-detection](#binary-auto-detection). |
+| `socket_path`                                  | platform default | `mpv.socketPath`             | mpv IPC socket                                                        |
+| `backend`                                      | `auto`           | `mpv.backend`                | Window backend: `auto`, `hyprland`, `sway`, `x11`, `macos`            |
+| `auto_start`                                   | `no`             | `mpv.autoStartSubMiner`      | Start SubMiner when a file loads                                      |
+| `auto_start_visible_overlay`                   | `no`             | `auto_start_overlay`         | Show the overlay when auto-starting                                   |
+| `auto_start_pause_until_ready`                 | `yes`            | `mpv.pauseUntilOverlayReady` | Keep mpv paused until subtitles are ready                             |
+| `auto_start_pause_until_ready_timeout_seconds` | `30`             |                              | Resume anyway after this many seconds                                 |
+| `overlay_loading_osd`                          | `no`             |                              | Show a loading message while the overlay starts                       |
+| `texthooker_enabled`                           | `no`             |                              | Start the texthooker with the overlay                                 |
+| `texthooker_port`                              | `5174`           |                              | Texthooker port                                                       |
+| `osd_messages`                                 | `yes`            |                              | Show plugin status messages in mpv                                    |
+| `log_level`                                    | `info`           |                              | Plugin log level                                                      |
 
-- Accelerators are normalized per platform - `CommandOrControl` resolves to `Cmd` on macOS and `Ctrl` elsewhere.
-- Multi-line actions (`copySubtitleMultiple`, `mineSentenceMultiple`) register temporary `1`–`9` digit follow-up bindings after the trigger key, with `Esc` to cancel.
-- If two shortcuts compile to the same key, or an accelerator can't be mapped to an mpv key, the app logs a warning and skips that binding instead of registering a broken one.
+Without script options, `socket_path` is `/tmp/subminer-socket`, or `\\.\pipe\subminer-socket` on Windows. On Windows, the plugin also rewrites `/tmp/subminer-socket` to the named pipe.
 
-## Menu
+The table's defaults are the plugin's own. Managed launches override them from your config; see [Configuration](/configuration#mpv-launcher).
 
-Press `y-y` to open an interactive menu in mpv's OSD:
+## Binary auto-detection
+
+With `binary_path` empty, the plugin looks in these places:
+
+| Platform | Locations                                                                                                                                                                                                  |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Linux    | `~/.local/bin/SubMiner.AppImage`, `/opt/SubMiner/SubMiner.AppImage`, `/usr/local/bin/SubMiner` or `subminer`, `/usr/bin/SubMiner` or `subminer`                                                            |
+| macOS    | `/Applications/SubMiner.app`, `~/Applications/SubMiner.app`                                                                                                                                                |
+| Windows  | A running SubMiner process, the App Paths registry entry, `SubMiner.exe` on `PATH`, then `%LOCALAPPDATA%\Programs\SubMiner`, `C:\Program Files\SubMiner`, `C:\Program Files (x86)\SubMiner`, `C:\SubMiner` |
+
+## Backend detection
+
+With `backend=auto`, the plugin picks the first match:
+
+1. macOS
+2. Hyprland (`HYPRLAND_INSTANCE_SIGNATURE` is set)
+3. Sway (`SWAYSOCK` is set)
+4. X11 (`XDG_SESSION_TYPE=x11` or `DISPLAY` is set)
+5. Otherwise X11, with a warning
+
+Native Wayland support covers only Hyprland and Sway. On other Wayland compositors, run both mpv and SubMiner under Xwayland and install `xdotool` and `xwininfo`.
+
+## Script messages
+
+Other mpv scripts, `input.conf`, or the mpv console can control the plugin:
 
 ```text
-SubMiner:
-1. Start overlay
-2. Stop overlay
-3. Toggle overlay
-4. Open options
-5. Restart overlay
-6. Check status
-```
-
-Select an item by pressing its number.
-
-## Binary Auto-Detection
-
-When `binary_path` is empty, the plugin searches platform-specific locations:
-
-**Linux:**
-
-1. `~/.local/bin/SubMiner.AppImage`
-2. `/opt/SubMiner/SubMiner.AppImage`
-3. `/usr/local/bin/SubMiner`
-4. `/usr/bin/SubMiner`
-
-**macOS:**
-
-1. `/Applications/SubMiner.app/Contents/MacOS/SubMiner`
-2. `~/Applications/SubMiner.app/Contents/MacOS/SubMiner`
-
-**Windows:**
-
-1. `C:\Program Files\SubMiner\SubMiner.exe`
-2. `C:\Program Files (x86)\SubMiner\SubMiner.exe`
-3. `C:\SubMiner\SubMiner.exe`
-
-Packaged Windows plugin installs also rewrite `socket_path` to `\\.\pipe\subminer-socket` automatically.
-
-## Backend Detection
-
-When `backend=auto`, the plugin detects the window manager:
-
-1. **macOS** - detected via platform or `OSTYPE`.
-2. **Hyprland** - detected via `HYPRLAND_INSTANCE_SIGNATURE`.
-3. **Sway** - detected via `SWAYSOCK`.
-4. **X11** - detected via `XDG_SESSION_TYPE=x11` or `DISPLAY`.
-5. **Fallback** - defaults to X11 with a warning.
-
-::: tip Wayland is compositor-specific
-Native Wayland support is only available for Hyprland and Sway. If you use a different Wayland compositor, auto-detection will fall back to X11 - both mpv and SubMiner must be running under Xwayland, and `xdotool` and `xwininfo` must be installed.
-:::
-
-## Script Messages
-
-The plugin can be controlled from other mpv scripts or the mpv command line using script messages:
-
-```
 script-message subminer-start
 script-message subminer-stop
 script-message subminer-toggle
@@ -132,38 +114,21 @@ script-message subminer-menu
 script-message subminer-options
 script-message subminer-restart
 script-message subminer-status
-script-message subminer-autoplay-ready
 ```
 
-The AniSkip messages (`subminer-skip-intro`, `subminer-aniskip-refresh`) still exist, but they are handled by the SubMiner app over the IPC socket rather than by the plugin - see [AniSkip Integration](/aniskip-integration#triggering-from-mpv).
+`subminer-start` accepts overrides:
 
-The `subminer-start` message accepts overrides:
-
-```
+```text
 script-message subminer-start backend=hyprland socket=/custom/path texthooker=no log-level=debug
 ```
 
-`log-level` here controls only logging verbosity passed to SubMiner.
-`--debug` is a separate app/dev-mode flag in the main CLI and should not be used here for logging.
+`log-level` sets SubMiner's log verbosity. Do not use `--debug` for this; it turns on the app's dev mode.
 
-## Lifecycle
+The plugin also handles messages the SubMiner app sends it (`subminer-autoplay-ready`, `subminer-autoplay-hold`, `subminer-visible-overlay-shown`, `subminer-visible-overlay-hidden`, `subminer-managed-subtitles-loading`, `subminer-overlay-loading-ready`, `subminer-reload-session-bindings`). You do not need to send these yourself. The AniSkip messages are listed on the [AniSkip page](/aniskip-integration#triggering-from-mpv).
 
-For how the plugin's auto-start fits into the full launch sequence - including when the launcher starts the overlay instead of the plugin - see [Playback Startup Flow](./architecture#playback-startup-flow).
+## Auto-start behavior
 
-- **File loaded**: If `auto_start=yes`, the plugin starts the overlay.
-- **Auto-start pause gate**: If `auto_start_visible_overlay=yes` and `auto_start_pause_until_ready=yes`, launcher starts mpv paused. On cold managed background startup, SubMiner opens the tray and visible overlay shell before tokenization warmups finish, then the plugin resumes playback after SubMiner reports tokenization-ready (with a 30-second timeout fallback).
-- **Duplicate auto-start events**: Repeated `file-loaded` hooks while overlay is already running are ignored for auto-start triggers (prevents duplicate start attempts).
-- **MPV shutdown**: The plugin sends a stop command to gracefully shut down both the overlay and the texthooker server.
-- **Texthooker**: Starts as a separate subprocess before the overlay to ensure the app lock is acquired first.
-
-## Using with the `subminer` Wrapper
-
-The `subminer` wrapper script handles mpv launch, socket setup, and overlay lifecycle automatically. You do not need the plugin if you always use the wrapper.
-
-The plugin is useful when you:
-
-- Launch mpv from other tools (file managers, media centers).
-- Want on-demand overlay control without the wrapper.
-- Use mpv's built-in file browser or playlist features.
-
-You can install both - the plugin provides chord keybindings for convenience, while the wrapper handles the full lifecycle.
+- With `auto_start=yes`, the plugin starts SubMiner on each file load. Repeated loads while SubMiner is running do not start it again.
+- With `auto_start_visible_overlay=yes` and `auto_start_pause_until_ready=yes`, mpv stays paused until SubMiner reports that subtitles are ready, or until the timeout passes.
+- With `texthooker_enabled=yes`, the texthooker starts with the overlay.
+- When mpv quits, SubMiner sees the closed socket and shuts down its overlay.

docs-site/package.json

@@ -5,10 +5,10 @@
   "description": "In-repo VitePress documentation site for SubMiner",
   "packageManager": "bun@1.3.5",
   "scripts": {
-    "docs:dev": "SUBMINER_DOCS_VERSION_LINK_ORIGIN=local bun run ../scripts/build-versioned-docs.ts && SUBMINER_DOCS_VERSION_LINK_ORIGIN=local SUBMINER_DOCS_VERSION_MANIFEST=\"$(bun run ../scripts/print-docs-version-manifest.ts)\" VITE_EXTRA_EXTENSIONS=jsonc vitepress dev --host 0.0.0.0 --port 5173 --strictPort",
+    "docs:dev": "VITE_EXTRA_EXTENSIONS=jsonc vitepress dev --host 0.0.0.0 --port 5173 --strictPort",
     "docs:build": "VITE_EXTRA_EXTENSIONS=jsonc vitepress build",
     "docs:preview": "VITE_EXTRA_EXTENSIONS=jsonc vitepress preview --host 0.0.0.0 --port 4173 --strictPort",
-    "test": "bun test plausible.test.ts index.assets.test.ts docs-sync.test.ts seo.test.ts .vitepress/theme/status-line.test.ts ../scripts/docs-versioning.test.ts"
+    "test": "bun test plausible.test.ts index.assets.test.ts archive-function.test.ts docs-sync.test.ts links.test.ts seo.test.ts .vitepress/theme/status-line.test.ts ../scripts/docs-versioning.test.ts"
   },
   "dependencies": {
     "@catppuccin/vitepress": "^0.1.2",

docs-site/plausible.test.ts

@@ -42,27 +42,11 @@ test('versioned docs reuse current VitePress internals for old page snapshots',
   expect(versionedBuildContents).toContain('overlayCurrentVitePress(snapshotDocsSite)');
 });
 
-test('versioned docs build reports archive cache hits and rebuilds', () => {
-  expect(versionedBuildContents).toContain(
-    'console.info(`[docs] archive cache key ${archiveCacheKey.slice(0, 12)}`)',
-  );
-  expect(versionedBuildContents).toContain('console.info(`[docs] cache hit ${version}`)');
-  expect(versionedBuildContents).toContain('console.info(`[docs] rebuilding archive ${version}`)');
-});
-
-test('versioned docs build deduplicates public assets and prunes stale workspaces', () => {
+test('versioned docs build deduplicates main public assets and removes build workspaces', () => {
   expect(versionedBuildContents).toContain('dedupeVersionedPublicAssets({');
-  expect(versionedBuildContents).toContain('pruneArchiveCacheGenerations({');
   expect(versionedBuildContents).toContain('rmSync(buildRoot, { recursive: true, force: true });');
 });
 
-test('versioned docs archive cache key ignores generated and test-only files', () => {
-  expect(versionedBuildContents).toContain('isSharedInternalsHashIgnoredPath(path)');
-  expect(versionedBuildContents).toContain('|| /\\.test\\.[cm]?[jt]s$/.test(path)');
-  expect(versionedBuildContents).toContain('process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN');
-  expect(versionedBuildContents).not.toContain('hash.update(String(stat.mode))');
-});
-
 test('docs builds exclude the internal README from VitePress page entries', () => {
   expect(docsConfigContents).toContain("srcExclude: ['subagents/**', 'README.md']");
 });

docs-site/public/config.example.jsonc

@@ -6,6 +6,32 @@
  */
 {
 
+  // ==========================================
+  // 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.
+  // Configure an existing GGML model path or explicitly download a SubMiner-managed model.
+  // Hot-reload: settings apply to the next generation or model download.
+  // ==========================================
+  "subtitleGeneration": {
+    "whisperPath": "", // Optional path override for whisper.cpp. Leave empty to find whisper-cli on PATH.
+    "modelPath": "", // Path to an existing multilingual whisper.cpp GGML model. Leave empty to use a SubMiner-managed model. A configured path always takes precedence.
+    "managedModel": "small", // Multilingual whisper.cpp model to use when modelPath is empty. Download it explicitly from the generation modal or launcher. Values: tiny | tiny-q5_1 | tiny-q8_0 | base | base-q5_1 | base-q8_0 | small | small-q5_1 | small-q8_0 | medium | medium-q5_0 | medium-q8_0 | large-v1 | large-v2 | large-v2-q5_0 | large-v2-q8_0 | large-v3 | large-v3-q5_0 | large-v3-turbo | large-v3-turbo-q5_0 | large-v3-turbo-q8_0
+    "threads": 4, // Positive integer CPU thread count for whisper.cpp Japanese transcription.
+    "ffmpegPath": "", // Optional FFmpeg path override for audio extraction. Leave empty to find ffmpeg on PATH.
+    "ffprobePath": "", // Optional FFprobe path override for audio tracks and timing. Leave empty to find ffprobe on PATH.
+    "vadModelPath": "", // Path to a whisper.cpp Silero VAD model. Enables dialogue-focused generation while retaining uncertain audible sections, which may include songs. Leave empty to transcribe the full audio.
+    "vadPath": "" // Optional speech detector executable override. With vadModelPath configured, leave empty to find whisper-vad-speech-segments or vad-speech-segments on PATH.
+  }, // Generate timed Japanese subtitles from local audio using whisper.cpp.
+
   // ==========================================
   // Visible Overlay Auto-Start
   // Show the visible subtitle overlay automatically after managed mpv playback starts SubMiner.
@@ -172,7 +198,7 @@
   "updates": {
     "enabled": true, // Run automatic update checks in the background. Values: true | false
     "checkIntervalHours": 24, // Minimum hours between automatic update checks.
-    "notificationType": "both", // How SubMiner announces available updates. overlay shows notifications on the overlay, system uses OS notifications, both uses overlay and system. osd and osd-system are legacy config-file-only values. Values: overlay | system | both | none | osd | osd-system
+    "notificationType": "overlay", // How SubMiner announces available updates. overlay shows notifications on the overlay, system uses OS notifications, both uses overlay and system. osd and osd-system are legacy config-file-only values. Values: overlay | system | both | none | osd | osd-system
     "channel": "stable" // Release channel used for update checks. Values: stable | prerelease
   }, // Automatic update check behavior.
 
@@ -205,11 +231,15 @@
     "openCharacterDictionaryManager": "CommandOrControl+D", // Accelerator that opens the character dictionary manager modal.
     "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.
     "openControllerDebug": "Alt+Shift+C", // Accelerator that opens the controller debug modal with live axis/button readouts.
     "toggleSubtitleSidebar": "Backslash", // Accelerator that toggles the subtitle sidebar visibility.
-    "toggleNotificationHistory": "CommandOrControl+N" // Accelerator that toggles the overlay notification history panel.
+    "toggleNotificationHistory": "CommandOrControl+N", // Accelerator that toggles the overlay notification history panel.
+    "appendClipboardVideoToQueue": "CommandOrControl+A" // Accelerator that appends a video path from the clipboard to the mpv playlist.
   }, // Overlay keyboard shortcuts. Set a shortcut to null to disable.
 
   // ==========================================
@@ -290,15 +320,41 @@
       ] // Command setting.
     },
     {
-      "key": "Shift+BracketRight", // Key setting.
+      "key": "Ctrl+Shift+ArrowLeft", // Key setting.
       "command": [
-        "__sub-delay-next-line"
+        "sub-step",
+        -1
       ] // Command setting.
     },
     {
-      "key": "Shift+BracketLeft", // Key setting.
+      "key": "Ctrl+Shift+ArrowRight", // Key setting.
       "command": [
-        "__sub-delay-prev-line"
+        "sub-step",
+        1
+      ] // Command setting.
+    },
+    {
+      "key": "KeyZ", // Key setting.
+      "command": [
+        "add",
+        "sub-delay",
+        -0.1
+      ] // Command setting.
+    },
+    {
+      "key": "Shift+KeyZ", // Key setting.
+      "command": [
+        "add",
+        "sub-delay",
+        0.1
+      ] // Command setting.
+    },
+    {
+      "key": "KeyX", // Key setting.
+      "command": [
+        "add",
+        "sub-delay",
+        0.1
       ] // Command setting.
     },
     {
@@ -405,6 +461,12 @@
     "nameMatchColor": "#f5bde6", // Hex color used when a subtitle token matches an entry from the SubMiner character dictionary.
     "nPlusOneColor": "#c6a0f6", // Color used for the single N+1 target token subtitle highlight.
     "knownWordColor": "#a6da95", // Color used for known-word subtitle highlights.
+    "knownWordMaturityColors": {
+      "new": "#ee99a0", // Color for known words whose Anki cards are new (never reviewed), when maturity highlighting is enabled.
+      "learning": "#b7bdf8", // Color for known words whose Anki cards are in (re)learning, when maturity highlighting is enabled.
+      "young": "#91d7e3", // Color for known words whose Anki cards are in review below the mature threshold, when maturity highlighting is enabled.
+      "mature": "#a6da95" // Color for known words whose Anki cards are at or above the mature interval threshold, when maturity highlighting is enabled.
+    }, // Known word maturity colors setting.
     "jlptColors": {
       "N1": "#ed8796", // N1 setting.
       "N2": "#f5a97f", // N2 setting.
@@ -489,7 +551,7 @@
   // ==========================================
   // AnkiConnect Integration
   // Automatic Anki updates and media generation options.
-  // Hot-reload: ankiConnect.ai.enabled, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, and isKiku.fieldGrouping update live while SubMiner is running.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/wordAudio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, isSenren.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
   // Shared AI provider transport settings are read from top-level ai and typically require restart.
   // Most other AnkiConnect settings still require restart.
   // ==========================================
@@ -510,6 +572,7 @@
     "fields": {
       "word": "Expression", // Card field for the mined word or expression text.
       "audio": "ExpressionAudio", // Card field that receives generated sentence audio.
+      "wordAudio": "ExpressionAudio", // Existing word-audio field read to time the frozen first frame of animated images. This mapping is only used for synchronization.
       "image": "Picture", // Card field that receives the captured screenshot or animated image.
       "sentence": "Sentence", // Card field that receives the source sentence text.
       "miscInfo": "MiscInfo", // Card field that receives the miscellaneous info pattern (see ankiConnect.metadata.pattern).
@@ -533,16 +596,21 @@
       "animatedMaxHeight": 0, // Maximum height for animated AVIF captures, in pixels. Set to 0 to preserve aspect ratio.
       "animatedCrf": 35, // Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.
       "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
+      "normalizeAudio": true, // Normalize generated sentence audio loudness during media extraction. Changes apply live. Values: true | false
+      "mirrorMpvVolume": true, // Apply mpv's current software volume curve to generated sentence audio. Changes apply live. Values: true | false
+      "reviewTiming": false, // Review and preview subtitle media timing before SubMiner creates or enriches a mined card. Values: true | false
       "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio and animated AVIF clips.
       "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
-      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.
+      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds. 0 disables the cap.
     }, // Media setting.
     "knownWords": {
       "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
+      "maturityEnabled": false, // Color known-word highlights by Anki card maturity (new, learning, young, mature) instead of a single color. Requires known-word highlighting. Values: true | false
+      "matureThresholdDays": 21, // Card interval in days at which a known word counts as mature (Anki convention: 21).
       "refreshMinutes": 1440, // Minutes between known-word cache refreshes.
       "addMinedWordsImmediately": true, // Immediately append newly mined card words into the known-word cache. Values: true | false
       "matchMode": "headword", // Known-word matching strategy for subtitle annotations. Cache matches always receive known-word highlighting even when POS filters suppress other annotation types. Values: headword | surface
-      "decks": {} // Decks and expression/word fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word"] }.
+      "decks": {} // Decks and expression/word fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word"] }. Reading fields (Reading, Word Reading, ExpressionReading) are always probed so cached words match only in the reading their note teaches; words from notes without readings match in any reading.
     }, // Known words setting.
     "behavior": {
       "overwriteAudio": true, // When updating an existing card, overwrite the audio field instead of skipping it. Values: true | false
@@ -567,7 +635,15 @@
       "enabled": false, // Enable Kiku-specific mining behaviors (duplicate handling, field grouping). Values: true | false
       "fieldGrouping": "disabled", // Kiku duplicate-card field grouping mode. Values: auto | manual | disabled
       "deleteDuplicateInAuto": true // When Kiku field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
-    } // Is kiku setting.
+    }, // Is kiku setting.
+    "isSenren": {
+      "enabled": false, // Enable Senren-specific duplicate handling (scene-switching field grouping, including miscInfo grouping). Mutually exclusive with isKiku.enabled. Values: true | false
+      "fieldGrouping": "auto", // Senren duplicate-card field grouping mode (scene switching). Values: auto | manual | disabled
+      "deleteDuplicateInAuto": true // When Senren field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
+    }, // Is senren setting.
+    "lapisKiku": {
+      "wordCardKind": "word-and-sentence" // Card-type flag SubMiner marks on Kiku/Lapis word cards. Only one flag is set at a time; the others are cleared. Requires isKiku.enabled or isLapis.enabled. Values: word-and-sentence | click | sentence | audio | none
+    } // Lapis kiku setting.
   }, // Automatic Anki updates and media generation options.
 
   // ==========================================
@@ -583,16 +659,41 @@
     "maxEntryResults": 10 // Maximum Jimaku search results returned.
   }, // Jimaku API configuration and defaults.
 
+  // ==========================================
+  // TsukiHime
+  // TsukiHime subtitle search configuration for Japanese primary and configured secondary subtitles. No API key required.
+  // Hot-reload: TsukiHime changes apply to the next TsukiHime request.
+  // ==========================================
+  "tsukihime": {
+    "apiBaseUrl": "https://api.tsukihime.org/v1", // Base URL of the TsukiHime API (Animetosho successor). No API key required.
+    "maxSearchResults": 10 // Maximum TsukiHime search results returned.
+  }, // TsukiHime subtitle search configuration for Japanese primary and configured secondary subtitles. No API key required.
+
+  // ==========================================
+  // TMDB
+  // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+  // Hot-reload: TMDB changes apply to the next TMDB request.
+  // ==========================================
+  "tmdb": {
+    "apiKey": "", // Your own TMDB API key or read access token for live-action posters and synopses in the stats Library. Release builds bundle a project key, so set this only to use your own quota or when running from source (free under Settings > API on themoviedb.org).
+    "apiKeyCommand": "" // Shell command that prints the TMDB API key to stdout. Used instead of apiKey to avoid storing the key in plain text.
+  }, // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+
   // ==========================================
   // YouTube Playback Settings
   // Defaults for managed subtitle language preferences and YouTube subtitle loading.
-  // Hot-reload: primarySubLanguages applies to the next YouTube subtitle load.
+  // Hot-reload: primarySubLanguages and subtitleSource apply to the next YouTube subtitle load.
   // ==========================================
   "youtube": {
     "primarySubLanguages": [
       "ja",
       "jpn"
-    ] // Comma-separated primary subtitle language priority for managed subtitle auto-selection.
+    ], // Comma-separated primary subtitle language priority for managed subtitle auto-selection.
+    "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.
+    } // Media cache setting.
   }, // Defaults for managed subtitle language preferences and YouTube subtitle loading.
 
   // ==========================================
@@ -639,7 +740,7 @@
     "executablePath": "", // Optional absolute path to mpv.exe for Windows launch flows. Leave empty to auto-discover from SUBMINER_MPV_PATH or PATH.
     "launchMode": "normal", // Default window state for SubMiner-managed mpv launches. Values: normal | maximized | fullscreen
     "profile": "", // Optional mpv profile name passed to SubMiner-managed mpv launches. Leave empty to pass no profile.
-    "socketPath": "\\\\.\\pipe\\subminer-socket", // mpv IPC socket path used by SubMiner-managed playback and the bundled mpv plugin.
+    "socketPath": "/tmp/subminer-socket", // mpv IPC socket path used by SubMiner-managed playback and the bundled mpv plugin.
     "backend": "auto", // Window tracking backend passed to the bundled mpv plugin. Auto detects the current platform. Values: auto | hyprland | sway | x11 | macos | windows
     "autoStartSubMiner": true, // Start SubMiner in the background when SubMiner-managed mpv loads a file. Values: true | false
     "pauseUntilOverlayReady": true, // Pause mpv on visible-overlay auto-start until SubMiner signals subtitle tokenization readiness. Values: true | false

docs-site/seo.test.ts

@@ -1,7 +1,4 @@
 import { expect, test } from 'bun:test';
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { TransformContext } from 'vitepress';
 import docsConfig from './.vitepress/config';
@@ -56,60 +53,50 @@ test('main docs canonical uses /main/ and emits noindex', async () => {
     { rel: 'canonical', href: 'https://docs.subminer.moe/main/' },
   ]);
   expect(head).toContainEqual(['meta', { name: 'robots', content: 'noindex,follow' }]);
+  expect(mainDocsConfig.sitemap).toBeUndefined();
 
   process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
   process.env.SUBMINER_DOCS_BASE = previousBase;
 });
 
-test('latest stable archive canonical points to root equivalent', async () => {
+test.each([
+  ['v0.14.0', '/v/0.14.0/', 'https://docs.subminer.moe/v/0.14.0/usage'],
+  ['v0.12.0', '/v/0.12.0/', 'https://docs.subminer.moe/v/0.12.0/usage'],
+])(
+  '%s archive keeps a self-referential canonical and stays out of the index',
+  async (version, base, expectedCanonical) => {
     const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
     const previousBase = process.env.SUBMINER_DOCS_BASE;
     const previousVersion = process.env.SUBMINER_DOCS_VERSION;
-  const previousLatest = process.env.SUBMINER_DOCS_LATEST_STABLE;
     process.env.SUBMINER_DOCS_CHANNEL = 'stable-archive';
-  process.env.SUBMINER_DOCS_BASE = '/v/0.14.0/';
-  process.env.SUBMINER_DOCS_VERSION = 'v0.14.0';
-  process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
-  const { default: latestArchiveConfig } = await import('./.vitepress/config?latest-archive');
+    process.env.SUBMINER_DOCS_BASE = base;
+    process.env.SUBMINER_DOCS_VERSION = version;
+    try {
+      const { default: archiveConfig } = await import(`./.vitepress/config?archive-${version}`);
 
-  const head = await latestArchiveConfig.transformHead?.(makeTransformContext('usage.md'));
-
-  expect(head).toContainEqual([
-    'link',
-    { rel: 'canonical', href: 'https://docs.subminer.moe/usage' },
-  ]);
+      const head = await archiveConfig.transformHead?.(makeTransformContext('usage.md'));
 
+      expect(head).toContainEqual(['link', { rel: 'canonical', href: expectedCanonical }]);
+      expect(head).toContainEqual(['meta', { name: 'robots', content: 'noindex,follow' }]);
+      // A sitemap here would advertise the archive tree we just excluded.
+      expect(archiveConfig.sitemap).toBeUndefined();
+    } finally {
       process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
       process.env.SUBMINER_DOCS_BASE = previousBase;
       process.env.SUBMINER_DOCS_VERSION = previousVersion;
-  process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
-});
+    }
+  },
+);
 
-test('stable archive theme links stay on the selected version', async () => {
+test('archive nav keeps page links in-version and version links release-independent', async () => {
   const previousCwd = process.cwd();
   const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
   const previousBase = process.env.SUBMINER_DOCS_BASE;
   const previousVersion = process.env.SUBMINER_DOCS_VERSION;
-  const previousLatest = process.env.SUBMINER_DOCS_LATEST_STABLE;
-  const previousManifest = process.env.SUBMINER_DOCS_VERSION_MANIFEST;
-  const previousVersionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN;
   process.chdir(docsSiteDir);
   process.env.SUBMINER_DOCS_CHANNEL = 'stable-archive';
   process.env.SUBMINER_DOCS_BASE = '/v/0.12.0/';
   process.env.SUBMINER_DOCS_VERSION = 'v0.12.0';
-  process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
-  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'production';
-  process.env.SUBMINER_DOCS_VERSION_MANIFEST = JSON.stringify({
-    latestStable: 'v0.14.0',
-    channels: [
-      { label: 'Latest stable', path: '/' },
-      { label: 'main', path: '/main/' },
-    ],
-    versions: [
-      { version: 'v0.14.0', path: '/v/0.14.0/' },
-      { version: 'v0.12.0', path: '/v/0.12.0/' },
-    ],
-  });
   try {
     const { default: archiveConfig } = await import('./.vitepress/config?stable-archive-links');
 
@@ -122,39 +109,24 @@ test('stable archive theme links stay on the selected version', async () => {
       text: string;
       items?: Array<{ text: string; link: string }>;
     }>;
-    const configurationNav = nav.find((item) => item.text === 'Configuration');
-    const versionNav = nav.find((item) => item.text === 'v0.12.0');
-    const referenceSidebar = sidebar.find((item) => item.text === 'Reference');
-    const configurationSidebar = referenceSidebar?.items?.find(
-      (item) => item.text === 'Configuration',
-    );
+    const configurationSidebar = sidebar
+      .find((item) => item.text === 'Reference')
+      ?.items?.find((item) => item.text === 'Configuration');
 
-    expect(configurationNav?.link).toBe('/configuration');
+    expect(nav.find((item) => item.text === 'Configuration')?.link).toBe('/configuration');
     expect(configurationSidebar?.link).toBe('/configuration');
-    expect(versionNav?.items).toContainEqual({
-      text: 'Latest stable (v0.14.0)',
-      link: 'https://docs.subminer.moe/',
+    // Frozen archives must not embed the release list, or every new tag would
+    // invalidate them. They point at the root-only /versions page instead.
+    expect(nav.find((item) => item.text === 'v0.12.0')?.items).toEqual([
+      { text: 'Latest stable', link: 'https://docs.subminer.moe/', target: '_self', noIcon: true },
+      { text: 'main', link: 'https://docs.subminer.moe/main/', target: '_self', noIcon: true },
+      {
+        text: 'All versions',
+        link: 'https://docs.subminer.moe/versions',
         target: '_self',
         noIcon: true,
-    });
-    expect(versionNav?.items).toContainEqual({
-      text: 'main',
-      link: 'https://docs.subminer.moe/main/',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items).toContainEqual({
-      text: 'v0.14.0',
-      link: 'https://docs.subminer.moe/v/0.14.0/',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items).toContainEqual({
-      text: 'v0.12.0',
-      link: 'https://docs.subminer.moe/v/0.12.0/',
-      target: '_self',
-      noIcon: true,
-    });
+      },
+    ]);
     expect(archiveConfig.themeConfig?.logo).toEqual({
       light: '/assets/SubMiner.png',
       dark: '/assets/SubMiner.png',
@@ -164,266 +136,9 @@ test('stable archive theme links stay on the selected version', async () => {
     process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
     process.env.SUBMINER_DOCS_BASE = previousBase;
     process.env.SUBMINER_DOCS_VERSION = previousVersion;
-    process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
-    process.env.SUBMINER_DOCS_VERSION_MANIFEST = previousManifest;
-    process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = previousVersionLinkOrigin;
   }
 });
 
-test('local stable archive version links stay on the dev server', async () => {
-  const previousCwd = process.cwd();
-  const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
-  const previousBase = process.env.SUBMINER_DOCS_BASE;
-  const previousVersion = process.env.SUBMINER_DOCS_VERSION;
-  const previousLatest = process.env.SUBMINER_DOCS_LATEST_STABLE;
-  const previousManifest = process.env.SUBMINER_DOCS_VERSION_MANIFEST;
-  const previousVersionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN;
-  process.chdir(docsSiteDir);
-  process.env.SUBMINER_DOCS_CHANNEL = 'stable-archive';
-  process.env.SUBMINER_DOCS_BASE = '/v/0.10.0/';
-  process.env.SUBMINER_DOCS_VERSION = 'v0.10.0';
-  process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
-  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'local';
-  process.env.SUBMINER_DOCS_VERSION_MANIFEST = JSON.stringify({
-    latestStable: 'v0.14.0',
-    channels: [
-      { label: 'Latest stable', path: '/' },
-      { label: 'main', path: '/main/' },
-    ],
-    versions: [
-      { version: 'v0.14.0', path: '/v/0.14.0/' },
-      { version: 'v0.10.0', path: '/v/0.10.0/' },
-    ],
-  });
-  try {
-    const { default: archiveConfig } = await import('./.vitepress/config?local-archive-links');
-
-    const nav = archiveConfig.themeConfig?.nav as Array<{
-      text: string;
-      items?: Array<{ text: string; link: string }>;
-    }>;
-    const versionNav = nav.find((item) => item.text === 'v0.10.0');
-
-    expect(versionNav?.items).toContainEqual({
-      text: 'Latest stable (v0.14.0)',
-      link: '../../',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items).toContainEqual({
-      text: 'main',
-      link: '../../main/',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items).toContainEqual({
-      text: 'v0.14.0',
-      link: '../0.14.0/',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items).toContainEqual({
-      text: 'v0.10.0',
-      link: './',
-      target: '_self',
-      noIcon: true,
-    });
-  } finally {
-    process.chdir(previousCwd);
-    process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
-    process.env.SUBMINER_DOCS_BASE = previousBase;
-    process.env.SUBMINER_DOCS_VERSION = previousVersion;
-    process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
-    process.env.SUBMINER_DOCS_VERSION_MANIFEST = previousManifest;
-    process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = previousVersionLinkOrigin;
-  }
-});
-
-test('dev docs version links use local targets for version route testing', async () => {
-  const previousCwd = process.cwd();
-  const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
-  const previousBase = process.env.SUBMINER_DOCS_BASE;
-  const previousVersion = process.env.SUBMINER_DOCS_VERSION;
-  const previousLatest = process.env.SUBMINER_DOCS_LATEST_STABLE;
-  const previousManifest = process.env.SUBMINER_DOCS_VERSION_MANIFEST;
-  const previousVersionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN;
-  process.chdir(docsSiteDir);
-  delete process.env.SUBMINER_DOCS_CHANNEL;
-  delete process.env.SUBMINER_DOCS_BASE;
-  delete process.env.SUBMINER_DOCS_VERSION;
-  delete process.env.SUBMINER_DOCS_LATEST_STABLE;
-  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'local';
-  process.env.SUBMINER_DOCS_VERSION_MANIFEST = JSON.stringify({
-    latestStable: 'v0.14.0',
-    channels: [
-      { label: 'Latest stable', path: '/' },
-      { label: 'main', path: '/main/' },
-    ],
-    versions: [
-      { version: 'v0.14.0', path: '/v/0.14.0/' },
-      { version: 'v0.12.0', path: '/v/0.12.0/' },
-      { version: 'v0.11.2', path: '/v/0.11.2/' },
-    ],
-  });
-  try {
-    const { default: devConfig } = await import('./.vitepress/config?dev-version-links');
-
-    const nav = devConfig.themeConfig?.nav as Array<{
-      text: string;
-      items?: Array<{ text: string; link: string }>;
-    }>;
-    const versionNav = nav.find((item) => item.text === 'v0.14.0');
-
-    expect(versionNav?.items).toContainEqual({
-      text: 'Latest stable (v0.14.0)',
-      link: '/',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items).toContainEqual({
-      text: 'main',
-      link: '/main/',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items).toContainEqual({
-      text: 'v0.12.0',
-      link: '/v/0.12.0/',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items?.map((item) => item.text)).toEqual([
-      'Latest stable (v0.14.0)',
-      'main',
-      'v0.14.0',
-      'v0.12.0',
-      'v0.11.2',
-    ]);
-  } finally {
-    process.chdir(previousCwd);
-    process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
-    process.env.SUBMINER_DOCS_BASE = previousBase;
-    process.env.SUBMINER_DOCS_VERSION = previousVersion;
-    process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
-    process.env.SUBMINER_DOCS_VERSION_MANIFEST = previousManifest;
-    process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = previousVersionLinkOrigin;
-  }
-});
-
-test('dev server redirects unserved version routes to production docs', () => {
-  let routeHandler:
-    | ((req: { url?: string }, res: DevRedirectResponse, next: () => void) => void)
-    | undefined;
-  const fakeServer = {
-    middlewares: {
-      use(handler: typeof routeHandler) {
-        routeHandler = handler;
-      },
-    },
-  };
-  const plugins = Array.isArray(docsConfig.vite?.plugins)
-    ? docsConfig.vite.plugins
-    : [docsConfig.vite?.plugins].filter(Boolean);
-  const redirectPlugin = plugins.find(
-    (plugin): plugin is { name: string; configureServer: (server: never) => void } =>
-      Boolean(plugin) &&
-      typeof plugin === 'object' &&
-      'name' in plugin &&
-      plugin.name === 'subminer-docs-local-version-redirects' &&
-      'configureServer' in plugin,
-  );
-  expect(redirectPlugin).toBeDefined();
-  redirectPlugin?.configureServer(fakeServer as never);
-
-  const response = new DevRedirectResponse();
-  let nextCalled = false;
-  routeHandler?.({ url: '/v/0.14.0/?from=dev' }, response, () => {
-    nextCalled = true;
-  });
-
-  expect(nextCalled).toBe(false);
-  expect(response.statusCode).toBe(302);
-  expect(response.headers.location).toBe('https://docs.subminer.moe/v/0.14.0/?from=dev');
-
-  const rootResponse = new DevRedirectResponse();
-  routeHandler?.({ url: '/configuration' }, rootResponse, () => {
-    nextCalled = true;
-  });
-  expect(rootResponse.ended).toBe(false);
-  expect(nextCalled).toBe(true);
-});
-
-test('dev server serves local archive files for local version links', async () => {
-  const previousVersionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN;
-  const previousArchiveDir = process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR;
-  const archiveDir = mkdtempSync(join(tmpdir(), 'subminer-docs-archive-'));
-  mkdirSync(join(archiveDir, 'v/0.14.0'), { recursive: true });
-  writeFileSync(join(archiveDir, 'v/0.14.0/index.html'), '<h1>local archive</h1>');
-  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'local';
-  process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR = archiveDir;
-  try {
-    const { default: localDevConfig } = await import(
-      `./.vitepress/config?local-dev-redirects-${Date.now()}`
-    );
-    let routeHandler:
-      | ((req: { url?: string }, res: DevRedirectResponse, next: () => void) => void)
-      | undefined;
-    const fakeServer = {
-      middlewares: {
-        use(handler: typeof routeHandler) {
-          routeHandler = handler;
-        },
-      },
-    };
-    const plugins = Array.isArray(localDevConfig.vite?.plugins)
-      ? localDevConfig.vite.plugins
-      : [localDevConfig.vite?.plugins].filter(Boolean);
-    const redirectPlugin = plugins.find(
-      (plugin): plugin is { name: string; configureServer: (server: never) => void } =>
-        Boolean(plugin) &&
-        typeof plugin === 'object' &&
-        'name' in plugin &&
-        plugin.name === 'subminer-docs-local-version-redirects' &&
-        'configureServer' in plugin,
-    );
-    redirectPlugin?.configureServer(fakeServer as never);
-
-    const response = new DevRedirectResponse();
-    let nextCalled = false;
-    routeHandler?.({ url: '/v/0.14.0/?from=dev' }, response, () => {
-      nextCalled = true;
-    });
-
-    expect(nextCalled).toBe(false);
-    expect(response.statusCode).toBe(200);
-    expect(response.headers['content-type']).toBe('text/html; charset=utf-8');
-    expect(response.headers.location).toBeUndefined();
-    expect(response.body).toBe('<h1>local archive</h1>');
-  } finally {
-    process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = previousVersionLinkOrigin;
-    process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR = previousArchiveDir;
-    rmSync(archiveDir, { recursive: true, force: true });
-  }
-});
-
-class DevRedirectResponse {
-  statusCode = 200;
-  headers: Record<string, string> = {};
-  ended = false;
-  body = '';
-
-  setHeader(name: string, value: string) {
-    this.headers[name.toLowerCase()] = value;
-  }
-
-  end(chunk?: string | Uint8Array) {
-    if (chunk) {
-      this.body = typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk);
-    }
-    this.ended = true;
-  }
-}
-
 test('docs sitemap excludes duplicate README page from indexable URLs', async () => {
   const items = [{ url: '' }, { url: 'README' }, { url: 'usage' }];
 
@@ -431,3 +146,22 @@ test('docs sitemap excludes duplicate README page from indexable URLs', async ()
 
   expect(transformedItems?.map((item) => item.url)).toEqual(['', 'usage']);
 });
+
+test('docs sitemap dates every URL from the tracked checkout', async () => {
+  const previousRepoDir = process.env.SUBMINER_DOCS_REPO_DIR;
+  // Production builds render from an untracked snapshot, so the date has to come from
+  // the real checkout rather than VitePress's own srcDir git lookup.
+  process.env.SUBMINER_DOCS_REPO_DIR = docsSiteDir;
+  try {
+    const { default: sitemapConfig } = await import('./.vitepress/config?sitemap-lastmod');
+
+    const items = await sitemapConfig.sitemap?.transformItems?.([{ url: '' }, { url: 'usage' }]);
+
+    expect(items).toHaveLength(2);
+    for (const item of items ?? []) {
+      expect(item.lastmod).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    }
+  } finally {
+    process.env.SUBMINER_DOCS_REPO_DIR = previousRepoDir;
+  }
+});

docs-site/shortcuts.md

@@ -1,165 +1,147 @@
-# Keyboard Shortcuts
+# Keyboard shortcuts
 
-This page is the complete reference for every keystroke SubMiner responds to. If you are just getting started, focus on the **Mining Shortcuts** and **Overlay Controls** sections - those cover the day-to-day mining loop. The rest can wait until you need them.
+Every key SubMiner responds to, with its default binding. `Ctrl/Cmd` means `Ctrl` on Windows and Linux and `Cmd` on macOS (`CommandOrControl` in config).
 
-A few terms used throughout:
+Shortcuts work when the overlay has focus. With the [mpv plugin](/mpv-plugin), `shortcuts.*` and `keybindings` entries also work while mpv has focus. If a key does nothing, click the video once. Set any shortcut to `null` to disable it. Changes to `shortcuts`, `keybindings`, and `subtitleSidebar` apply without a restart.
 
-- **Overlay** - the transparent SubMiner window that sits on top of mpv and shows the interactive subtitles. Most shortcuts only work while this window has focus (click the video once if a shortcut seems to do nothing).
-- **`Ctrl/Cmd`** - use `Ctrl` on Windows/Linux and `Cmd` (⌘) on macOS. In the config file this is written as `CommandOrControl`.
-- **Accelerator** - Electron's name for a shortcut string like `Alt+Shift+O`.
+## Global
 
-All shortcuts are configurable in `config.jsonc` under `shortcuts` and `keybindings`. Set any shortcut to `null` to disable it.
-
-## Global Shortcuts
-
-These work system-wide regardless of which window has focus.
-
-| Shortcut      | Action                 | Configurable                           |
+| Shortcut      | Action                 | Config key                             |
 | ------------- | ---------------------- | -------------------------------------- |
 | `Alt+Shift+O` | Toggle visible overlay | `shortcuts.toggleVisibleOverlayGlobal` |
-| `Alt+Shift+Y` | Open Yomitan settings  | Fixed (not configurable)               |
+| `Alt+Shift+Y` | Open Yomitan settings  | Fixed                                  |
 
-::: tip
-Global shortcuts are registered with the OS. If they conflict with another application, update them in `shortcuts` config and restart SubMiner.
-:::
+`Alt+Shift+Y` is registered with the OS and works from any app. If another app already uses it, SubMiner cannot take it and you cannot rebind it.
 
-## Mining Shortcuts
-
-These work when the overlay window has focus.
+## Mining
 
 | Shortcut           | Action                                              | Config key                              |
-| ------------------ | ----------------------------------------------- | --------------------------------------- |
-| `Ctrl/Cmd+S`       | Mine current subtitle as sentence card          | `shortcuts.mineSentence`                |
-| `Ctrl/Cmd+Shift+S` | Mine multiple lines (press 1–9 to select count) | `shortcuts.mineSentenceMultiple`        |
-| `Ctrl/Cmd+C`       | Copy current subtitle text                      | `shortcuts.copySubtitle`                |
-| `Ctrl/Cmd+Shift+C` | Copy multiple lines (press 1–9 to select count) | `shortcuts.copySubtitleMultiple`        |
-| `Ctrl/Cmd+V`       | Update last Anki card from clipboard text       | `shortcuts.updateLastCardFromClipboard` |
-| `Ctrl/Cmd+G`       | Trigger field grouping (Kiku merge check)       | `shortcuts.triggerFieldGrouping`        |
-| `Ctrl/Cmd+Shift+A` | Mark last card as audio card                    | `shortcuts.markAudioCard`               |
+| ------------------ | --------------------------------------------------- | --------------------------------------- |
+| `Ctrl/Cmd+S`       | Mine current line as a sentence card                | `shortcuts.mineSentence`                |
+| `Ctrl/Cmd+Shift+S` | Mine several lines as one sentence card             | `shortcuts.mineSentenceMultiple`        |
+| `Ctrl/Cmd+C`       | Copy current line                                   | `shortcuts.copySubtitle`                |
+| `Ctrl/Cmd+Shift+C` | Copy several lines                                  | `shortcuts.copySubtitleMultiple`        |
+| `Ctrl/Cmd+V`       | Update last-added card from the clipboard           | `shortcuts.updateLastCardFromClipboard` |
+| `Ctrl/Cmd+G`       | Run the field grouping check on the last-added card | `shortcuts.triggerFieldGrouping`        |
+| `Ctrl/Cmd+Shift+A` | Mark last-added card as an audio card               | `shortcuts.markAudioCard`               |
 
-The multi-line shortcuts open a digit selector with a 3-second timeout (`shortcuts.multiCopyTimeoutMs`). Press `1`–`9` to select how many recent subtitle lines to combine. When the shortcut starts from mpv, SubMiner focuses the visible overlay for that selector instead of reserving the number keys in the mpv plugin.
+After a multi-line shortcut, press `1` to `9` for how many lines to combine, counting back from and including the current line. The prompt closes after `shortcuts.multiCopyTimeoutMs`.
 
-## Overlay Controls
+When text is selected in the [subtitle sidebar](/subtitle-sidebar), `Ctrl/Cmd+C` copies that selection instead.
 
-These control playback and subtitle display. They require overlay window focus.
+## Playback
+
+These are the default `keybindings` entries. Remap or disable them in the `keybindings` array.
 
 | Shortcut           | Action                                   |
-| -------------------- | --------------------------------------------------- |
-| `Space`              | Toggle mpv pause                                    |
+| ------------------ | ---------------------------------------- |
+| `Space`            | Pause or resume                          |
 | `F`                | Toggle fullscreen                        |
-| `V`                  | Cycle primary subtitle bar mode (hidden → visible → hover) |
 | `J`                | Cycle primary subtitle track             |
 | `Shift+J`          | Cycle secondary subtitle track           |
-| `Ctrl+Alt+P`         | Open playlist browser for current directory + queue |
 | `ArrowRight`       | Seek forward 5 seconds                   |
-| `ArrowLeft`          | Seek backward 5 seconds                             |
+| `ArrowLeft`        | Seek back 5 seconds                      |
 | `ArrowUp`          | Seek forward 60 seconds                  |
-| `ArrowDown`          | Seek backward 60 seconds                            |
+| `ArrowDown`        | Seek back 60 seconds                     |
 | `Shift+H`          | Jump to previous subtitle                |
 | `Shift+L`          | Jump to next subtitle                    |
-| `Shift+[`            | Shift subtitle delay to previous subtitle cue       |
-| `Shift+]`            | Shift subtitle delay to next subtitle cue           |
-| `Ctrl+Shift+H`       | Replay current subtitle (play to end, then pause)   |
-| `Ctrl+Shift+L`       | Play next subtitle (jump, play to end, then pause)  |
+| `Ctrl+Shift+Left`  | Shift subtitle delay to the previous cue |
+| `Ctrl+Shift+Right` | Shift subtitle delay to the next cue     |
+| `Z`                | Subtitle delay -100 ms                   |
+| `Shift+Z`          | Subtitle delay +100 ms                   |
+| `X`                | Subtitle delay +100 ms                   |
+| `Ctrl+Shift+H`     | Replay current subtitle, then pause      |
+| `Ctrl+Shift+L`     | Play next subtitle, then pause           |
+| `Ctrl+Alt+P`       | Open playlist browser                    |
+| `Ctrl+Alt+C`       | Open YouTube subtitle picker             |
 | `Q`                | Quit mpv                                 |
 | `Ctrl+W`           | Quit mpv                                 |
-| `Right-click`        | Toggle pause (outside subtitle area)                |
-| `Right-click + drag` | Reposition subtitles (on subtitle area)             |
-| `Ctrl/Cmd+A`         | Append clipboard video path to mpv playlist         |
 
-The mpv-command rows above (`Space`, `F`, `J`, `Shift+J`, the seek/sub-seek/sub-delay keys, replay/play-next, and quit) are merged from the `keybindings` config array and can be remapped or disabled there. `V`, `Ctrl/Cmd+A`, and the mouse actions are built-in overlay behaviors and are not part of the `keybindings` array. The playlist browser opens a split overlay modal with sibling video files on the left and the live mpv playlist on the right.
+Built into the overlay, not configurable:
 
-On macOS managed playback, SubMiner disables mpv's menu-bar shortcuts so configured SubMiner shortcuts like `Cmd+Shift+O` reach the mpv plugin instead of opening native mpv menu actions.
+| Input                     | Action                                             |
+| ------------------------- | -------------------------------------------------- |
+| `V`                       | Cycle primary subtitle bar: hidden, visible, hover |
+| Right-click               | Pause or resume (outside the subtitle area)        |
+| Right-click + drag        | Move the subtitles                                 |
+| Drop files on the overlay | Replace the mpv playlist                           |
+| `Shift` + drop files      | Append to the mpv playlist                         |
 
-Mouse-hover playback behavior is configured separately from shortcuts: `subtitleStyle.autoPauseVideoOnHover` defaults to `true` (pause on subtitle hover, resume on leave).
-
-## Subtitle & Feature Shortcuts
+## Overlay features
 
 | Shortcut           | Action                                                 | Config key                                 |
-| ------------------ | -------------------------------------------------------- | ----------------------------------------------- |
-| `Ctrl/Cmd+Shift+V` | Cycle secondary subtitle mode (hidden → visible → hover) | `shortcuts.toggleSecondarySub`                  |
-| `Ctrl/Cmd+D`       | Open loaded character dictionary manager                 | `shortcuts.openCharacterDictionaryManager`      |
-| `Ctrl/Cmd+Shift+O` | Open runtime options palette                             | `shortcuts.openRuntimeOptions`                  |
-| `Ctrl/Cmd+/`       | Open session help modal                                  | `shortcuts.openSessionHelp`                     |
-| `Ctrl+Shift+J`     | Open Jimaku subtitle search modal                        | `shortcuts.openJimaku`                          |
-| `Ctrl/Cmd+N`       | Toggle overlay notification history panel                | `shortcuts.toggleNotificationHistory`           |
-| `Ctrl+Alt+C`       | Open the manual YouTube subtitle picker                  | `keybindings`                                   |
-| `Ctrl+Alt+S`       | Open subtitle sync (subsync) modal                       | `shortcuts.triggerSubsync`                      |
+| ------------------ | ------------------------------------------------------ | ------------------------------------------ |
+| `Ctrl/Cmd+Shift+V` | Cycle secondary subtitle bar: hidden, visible, hover   | `shortcuts.toggleSecondarySub`             |
+| `Ctrl/Cmd+Shift+O` | Open runtime options                                   | `shortcuts.openRuntimeOptions`             |
+| `Ctrl/Cmd+/`       | Open session help                                      | `shortcuts.openSessionHelp`                |
+| `Ctrl/Cmd+D`       | Open character dictionary manager                      | `shortcuts.openCharacterDictionaryManager` |
+| `Ctrl/Cmd+N`       | Toggle notification history                            | `shortcuts.toggleNotificationHistory`      |
+| `Ctrl/Cmd+A`       | Append the video path on the clipboard to the playlist | `shortcuts.appendClipboardVideoToQueue`    |
+| `Ctrl+Shift+J`     | Open Jimaku subtitle search                            | `shortcuts.openJimaku`                     |
+| `Ctrl+Shift+T`     | Open TsukiHime subtitle search                         | `shortcuts.openTsukihime`                  |
+| `Ctrl+Shift+G`     | Open Japanese subtitle generation                      | `shortcuts.openSubtitleGeneration`         |
+| `Ctrl+Alt+S`       | Open subtitle sync (subsync)                           | `shortcuts.triggerSubsync`                 |
+| `g` then `s`       | Pick primary and secondary subtitles (when enabled)    | `shortcuts.openSubtitleSelection`          |
 | `\`                | Toggle subtitle sidebar                                | `subtitleSidebar.toggleKey`                |
 | `` ` ``            | Toggle stats overlay                                   | `stats.toggleKey`                          |
-| `W`                | Mark current video watched and advance to next in queue  | `stats.markWatchedKey`                          |
+| `W`                | Mark video watched and play the next one in the queue  | `stats.markWatchedKey`                     |
+| `Alt+C`            | Open controller setup and remapping                    | `shortcuts.openControllerSelect`           |
+| `Alt+Shift+C`      | Open controller debug view                             | `shortcuts.openControllerDebug`            |
 
-The stats toggle is handled inside the focused visible overlay window. It is configurable through the top-level `stats.toggleKey` setting and defaults to `Backquote`.
+While a video is playing, session help can also run commands: highlight a row with the arrow keys or the mouse, then press `Enter` or double-click it. Fixed overlay controls, global shortcuts, `y` chords, the multi-line copy and mine actions, Open session help, and the color legend are reference only. Help opened from the tray with no video loaded is read-only.
 
-The subtitle sidebar toggle is overlay-local and only opens when SubMiner has a parsed cue list for the active subtitle source.
+The sidebar key has a separate mpv-side binding, `shortcuts.toggleSubtitleSidebar`. The sidebar only opens when SubMiner has parsed the active subtitle file. In the sidebar, `Enter` seeks to the focused line.
 
-## Controller Shortcuts
+The subtitle picker (`g` then `s`) is off until you turn it on in **Settings, Behavior, Subtitle Selection**. Press the second key within one second. If `g` already has an action in SubMiner or mpv, the sequence is disabled and a warning is shown. See [subtitle selection](/configuration#subtitle-selection).
 
-These overlay-local shortcuts open controller utilities for the Chrome Gamepad API integration.
+## mpv plugin keys
 
-| Shortcut      | Action                               | Configurable                     |
-| ------------- | ------------------------------------ | -------------------------------- |
-| `Alt+C`       | Open controller config + remap modal | `shortcuts.openControllerSelect` |
-| `Alt+Shift+C` | Open controller debug modal          | `shortcuts.openControllerDebug`  |
+Press `y`, then the second key.
 
-Controller input only drives the overlay while keyboard-only mode is enabled. The controller mapping and tuning live under the top-level `controller` config block; keyboard-only mode still works normally without a controller.
-
-## MPV Plugin Chords
-
-When the mpv plugin is installed, all commands use a `y` chord prefix - press `y`, then the second key within 1 second.
-
-| Chord | Action                                 |
-| ----- | -------------------------------------- |
-| `y-y` | Open SubMiner menu (OSD)               |
-| `y-s` | Start overlay                          |
-| `y-S` | Stop overlay                           |
-| `y-t` | Toggle visible overlay                 |
-| `v`   | Cycle primary subtitle bar mode (hidden → visible → hover) |
+| Keys  | Action                     |
+| ----- | -------------------------- |
+| `y-y` | Open the SubMiner menu     |
+| `y-s` | Start the overlay          |
+| `y-S` | Stop the overlay           |
+| `y-t` | Toggle the visible overlay |
 | `y-o` | Open Yomitan settings      |
-| `y-r` | Restart overlay                        |
-| `y-c` | Check overlay status                   |
+| `y-r` | Restart the overlay        |
+| `y-c` | Show overlay status        |
 | `y-h` | Open session help          |
+| `v`   | Cycle primary subtitle bar |
 
-The bare `v` plugin binding intentionally overrides mpv's native primary subtitle visibility toggle so it cycles the SubMiner primary subtitle bar (hidden → visible → hover) instead.
+The plugin's `v` replaces mpv's own subtitle visibility toggle. When the overlay has focus, `y` then `d` toggles DevTools.
 
-When the overlay has focus, press `y` then `d` to toggle DevTools (debugging helper).
+## Customizing
 
-## Drag-and-Drop
-
-| Gesture                   | Action                                           |
-| ------------------------- | ------------------------------------------------ |
-| Drop file(s) onto overlay | Replace current mpv playlist with dropped files  |
-| `Shift` + drop file(s)    | Append all dropped files to current mpv playlist |
-
-## Customizing Shortcuts
-
-All `shortcuts.*` keys accept [Electron accelerator strings](https://www.electronjs.org/docs/latest/tutorial/keyboard-shortcuts), for example `"CommandOrControl+D"`. Use `null` to disable a shortcut.
+`shortcuts.*` values are [Electron accelerator strings](https://www.electronjs.org/docs/latest/tutorial/keyboard-shortcuts).
 
 ```jsonc
 {
   "shortcuts": {
     "mineSentence": "CommandOrControl+S",
-    "copySubtitle": "CommandOrControl+C",
-    "toggleVisibleOverlayGlobal": "Alt+Shift+O",
     "openJimaku": null, // disabled
   },
 }
 ```
 
-The `keybindings` array overrides or extends the overlay's built-in key handling for mpv commands:
+`keybindings` entries map a key to an mpv command. They are merged with the defaults above. Set `command` to `null` to disable a default.
 
 ```jsonc
 {
   "keybindings": [
-    { "key": "f", "command": ["cycle", "fullscreen"] },
     { "key": "m", "command": ["cycle", "mute"] },
     { "key": "MBTN_BACK", "command": ["sub-seek", -1] },
-    { "key": "MBTN_FORWARD", "command": ["sub-seek", 1] },
-    { "key": "Space", "command": null }, // disable default Space → pause
+    { "key": "Ctrl+WHEEL_UP", "command": ["add", "sub-scale", 0.1] },
+    { "key": "Space", "command": null },
   ],
 }
 ```
 
-Mouse keybinding names are `MBTN_LEFT`, `MBTN_MID`, `MBTN_RIGHT`, `MBTN_BACK`, and `MBTN_FORWARD`.
+Mouse button names are `MBTN_LEFT`, `MBTN_MID`, `MBTN_RIGHT`, `MBTN_BACK`, and `MBTN_FORWARD`. Scroll wheel names are `WHEEL_UP`, `WHEEL_DOWN`, `WHEEL_LEFT`, and `WHEEL_RIGHT`. See [keybindings](/configuration#keybindings) and [shortcuts configuration](/configuration#shortcuts-configuration) in the config reference.
 
-Both `shortcuts`, `keybindings`, and `subtitleSidebar` are [hot-reloadable](/configuration#hot-reload-behavior) - changes take effect without restarting SubMiner.
+## Automatic mpv bindings
+
+The overlay reads single-key, mouse button, and scroll wheel bindings from the running mpv (`input.conf`, mpv defaults, and scripts). If SubMiner does not handle the input, it passes it to mpv, so mpv's defaults like double-click for fullscreen and the wheel for volume work over the overlay. SubMiner shortcuts and `keybindings` entries win, including ones set to `null`, and right-click always pauses. Keys and clicks are not forwarded while you type in a text field, use an overlay menu, or have a Yomitan popup open, and clicks on subtitles or overlay controls stay with SubMiner. Scrolling over an overlay menu, the subtitle sidebar, or notification history scrolls that panel instead.
+
+Keypad and media keys, key sequences, and mouse movement are not imported. Bindings imported this way do not appear in session help. If you add an mpv binding while SubMiner runs, refocus the overlay to pick it up.

docs-site/subtitle-annotations.md

@@ -1,147 +1,119 @@
-# Subtitle Annotations
+# Subtitle annotations
 
-SubMiner annotates subtitle tokens in real time as they appear in the overlay. Four annotation layers work together to surface useful context while you watch: **N+1 highlighting**, **character-name highlighting**, **frequency highlighting**, and **JLPT tagging**.
+SubMiner can color and underline words in the subtitle overlay: words you already know, the one new word in an N+1 line, common words, JLPT levels, and character names. Each layer is off by default and works on its own, so turn on only the ones you want.
 
-All four are opt-in and configured under `subtitleStyle`, `ankiConnect.knownWords`, and `ankiConnect.nPlusOne` in your config. They apply independently - you can enable any combination.
+Yomitan splits the subtitle into words, so your installed Yomitan dictionaries and their order decide where word boundaries fall. Grammar words such as particles (`は`), auxiliaries (`です`), and endings like `んです` stay hoverable but never get annotation colors.
 
-::: tip Tokenization
-SubMiner's primary tokenizer is Yomitan itself - subtitle text is tokenized based entirely on the dictionaries you have installed in Yomitan. Installing many large dictionaries can increase noise and slow down lookups, so be selective about which dictionaries you install and their priority order.
-:::
+Defaults for every key below are in the [configuration reference](/configuration).
 
-Before any of those layers render, SubMiner strips annotation metadata from tokens that are usually just subtitle glue or annotation noise. Standalone particles, auxiliaries, adnominals, common explanatory endings like `んです` / `のだ`, merged trailing quote-particle forms like `...って`, auxiliary-stem grammar tails like `そうだ` (MeCab POS3 `助動詞語幹`), repeated kana interjections, and similar non-lexical helper tokens remain hoverable in the subtitle text, but they render as plain tokens without known-word, N+1, frequency, JLPT, or name-match annotation styling.
+## Known words {#known-words}
 
-## N+1 Word Highlighting
+Colors every word that already appears in your Anki decks, so you can see how much of a line you know.
 
-N+1 highlighting identifies sentences where you know every word except one, making them ideal mining targets. When enabled, SubMiner builds a local cache of your known vocabulary from Anki and highlights tokens accordingly.
+Needs: Anki running with AnkiConnect, and at least one deck in `ankiConnect.knownWords.decks`.
 
-**How it works:**
+```jsonc
+{
+  "ankiConnect": {
+    "knownWords": {
+      "highlightEnabled": true,
+      "decks": { "Kaishi 1.5k": ["Word"] },
+    },
+  },
+}
+```
 
-1. SubMiner queries your configured Anki decks for expression/word fields such as `Expression` or `Word`.
-2. The results are cached locally (`known-words-cache.json`) and refreshed on a configurable interval.
-3. When a subtitle line appears, each token is checked against the cache.
-4. If exactly one unknown word remains in the sentence, it is highlighted with `subtitleStyle.nPlusOneColor` (default: `#c6a0f6`).
-5. Already-known tokens can optionally display in `subtitleStyle.knownWordColor` (default: `#a6da95`).
+Map each deck to its expression or word field. SubMiner also reads the note's reading field when it has one, so a known word only matches in the reading its card teaches.
 
-**Key settings:**
+| Key                                               | What it does                                                        |
+| ------------------------------------------------- | ------------------------------------------------------------------- |
+| `ankiConnect.knownWords.highlightEnabled`         | Turn known-word coloring on                                         |
+| `ankiConnect.knownWords.decks`                    | Deck name to list of fields to read                                 |
+| `ankiConnect.knownWords.matchMode`                | `headword` matches the dictionary form, `surface` the text as shown |
+| `ankiConnect.knownWords.refreshMinutes`           | How often the known-word list is re-read from Anki                  |
+| `ankiConnect.knownWords.addMinedWordsImmediately` | Count a word as known as soon as you mine it                        |
+| `subtitleStyle.knownWordColor`                    | Color for known words                                               |
 
-| Option                                    | Default      | Description                                                                                                                                                   |
-| ----------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ankiConnect.knownWords.highlightEnabled` | `false`      | Enable known-word cache lookups used by N+1 highlighting                                                                                                      |
-| `ankiConnect.knownWords.refreshMinutes`   | `1440`       | Minutes between Anki cache refreshes                                                                                                                          |
-| `ankiConnect.knownWords.decks`            | `{}`         | Deck→fields map for known-word cache queries                                                                                                                  |
-| `ankiConnect.knownWords.matchMode`        | `"headword"` | `"headword"` (dictionary form) or `"surface"` (raw text)                                                                                                      |
-| `ankiConnect.nPlusOne.enabled`            | `false`      | Enable N+1 target highlighting                                                                                                                               |
-| `ankiConnect.nPlusOne.minSentenceWords`   | `3`          | Minimum tokens in a sentence for N+1 to trigger                                                                                                               |
-| `subtitleStyle.nPlusOneColor`             | `#c6a0f6`    | Color for the single unknown target word                                                                                                                      |
-| `subtitleStyle.knownWordColor`            | `#a6da95`    | Color for already-known tokens                                                                                                                                |
+### Known-word maturity highlighting
 
-Prefer expression/word fields for `ankiConnect.knownWords.decks`. Reading-only fields can mark unrelated homophones as known, so only include them when that tradeoff is intentional.
+Colors known words by how well you know them instead of using one color. Each word gets the tier of its most mature card:
 
-::: tip
-Set `refreshMinutes` to `1440` (24 hours) for daily sync if your Anki collection is large.
-:::
+- `new`: never studied
+- `learning`: in the learning or relearning queue
+- `young`: in review, interval below the threshold
+- `mature`: in review, interval at or above `ankiConnect.knownWords.matureThresholdDays`
 
-## Character-Name Highlighting
+Turn it on with `ankiConnect.knownWords.maturityEnabled` (known-word highlighting must also be on). Set the colors under `subtitleStyle.knownWordMaturityColors` (`new`, `learning`, `young`, `mature`).
 
-Character-name matches are built from the active merged SubMiner character dictionary, which auto-syncs character data from AniList for your recently-watched titles. When the current AniList media ID is known, SubMiner ignores loaded entries from other titles for subtitle name matching and inline portraits. Matching names are highlighted in subtitles and become available for hover-driven Yomitan character profiles - portraits, roles, voice actors, and biographical detail.
+Tiers update when the known-word list refreshes, so a card that turns mature today keeps its old color until the next refresh. If your deck has no relearning steps, lapsed cards go straight back to review and show as `young`.
 
-**How it works:**
+## N+1 word highlighting
 
-1. Subtitles are tokenized, then candidate name tokens are matched against the character dictionary via Yomitan's scanning pipeline.
-2. Matching tokens receive a dedicated style distinct from N+1 and frequency layers.
-3. This layer can be independently toggled with `subtitleStyle.nameMatchEnabled`.
-4. When `subtitleStyle.nameMatchImagesEnabled` is also enabled, SubMiner shows the cached AniList portrait beside matched names.
+An N+1 line has exactly one word you don't know. It is the easiest kind of sentence to mine, because the rest of the line gives you context. SubMiner colors that one unknown word.
 
-**Key settings:**
+Needs: the same Anki setup as [known words](#known-words) (`ankiConnect.knownWords.decks`). Known-word coloring itself can stay off.
 
-| Option                                 | Default   | Description                                      |
-| -------------------------------------- | --------- | ------------------------------------------------ |
-| `subtitleStyle.nameMatchEnabled`       | `false`   | Enable character-name token highlighting         |
-| `subtitleStyle.nameMatchImagesEnabled` | `false`   | Show small AniList portraits next to name tokens |
-| `subtitleStyle.nameMatchColor`         | `#f5bde6` | Color used for character-name matches            |
+| Key                                     | What it does                            |
+| --------------------------------------- | --------------------------------------- |
+| `ankiConnect.nPlusOne.enabled`          | Turn N+1 highlighting on                |
+| `ankiConnect.nPlusOne.minSentenceWords` | Skip lines shorter than this many words |
+| `subtitleStyle.nPlusOneColor`           | Color for the unknown word              |
 
-For full details on dictionary generation, name variant expansion, auto-sync lifecycle, and configuration, see the dedicated [Character Dictionary](/character-dictionary) page.
+## Frequency highlighting
 
-## Frequency Highlighting
+Colors words by how common they are, so a rare word in an easy line stands out.
 
-Frequency highlighting colors tokens based on how common they are, using dictionary frequency rank data. This helps you spot high-value vocabulary at a glance. Frequency ranks are sourced from the **highest-ranked frequency dictionary** installed in Yomitan - other frequency dictionaries are not consulted.
+Needs: at least one frequency dictionary installed in Yomitan. When several are installed, SubMiner uses them in your Yomitan priority order. Occurrence-count dictionaries are skipped. You can also point `sourcePath` at a folder of Yomitan-format frequency files as a fallback.
 
-**Modes:**
+| Key                                              | What it does                                                           |
+| ------------------------------------------------ | ---------------------------------------------------------------------- |
+| `subtitleStyle.frequencyDictionary.enabled`      | Turn frequency highlighting on                                         |
+| `subtitleStyle.frequencyDictionary.topX`         | Only color words whose rank is this number or lower (1 is most common) |
+| `subtitleStyle.frequencyDictionary.mode`         | `single` uses one color, `banded` splits the range into five colors    |
+| `subtitleStyle.frequencyDictionary.singleColor`  | Color for `single` mode                                                |
+| `subtitleStyle.frequencyDictionary.bandedColors` | Five colors for `banded` mode, most common first                       |
+| `subtitleStyle.frequencyDictionary.matchMode`    | `headword` or `surface`, as for known words                            |
+| `subtitleStyle.frequencyDictionary.sourcePath`   | Optional folder of frequency files                                     |
 
-- **Single** - all highlighted tokens share one color (`singleColor`).
-- **Banded** - tokens are assigned to five color bands from most common to least common within the `topX` window.
+## JLPT tagging
 
-SubMiner looks up each token's `frequencyRank` from `term_meta_bank_*.json` files. Only tokens with a positive rank at or below `topX` are highlighted.
+Underlines each word in a color for its JLPT level, N1 to N5. The JLPT word lists ship with SubMiner, so there is nothing to install.
 
-**Key settings:**
+| Key                                   | What it does                   |
+| ------------------------------------- | ------------------------------ |
+| `subtitleStyle.enableJlpt`            | Turn JLPT underlines on        |
+| `subtitleStyle.jlptColors.N1` to `N5` | Underline color for each level |
 
-| Option                                           | Default      | Description                                                      |
-| ------------------------------------------------ | ------------ | ---------------------------------------------------------------- |
-| `subtitleStyle.frequencyDictionary.enabled`      | `false`      | Enable frequency highlighting                                    |
-| `subtitleStyle.frequencyDictionary.topX`         | `10000`      | Max frequency rank to highlight                                  |
-| `subtitleStyle.frequencyDictionary.mode`         | `"single"`   | `"single"` or `"banded"`                                         |
-| `subtitleStyle.frequencyDictionary.matchMode`    | `"headword"` | `"headword"` or `"surface"`                                      |
-| `subtitleStyle.frequencyDictionary.singleColor`  | `#f5a97f`    | Color for single mode                                            |
-| `subtitleStyle.frequencyDictionary.bandedColors` | 5 colors[^1] | Array of five hex colors for banded mode                         |
-| `subtitleStyle.frequencyDictionary.sourcePath`   | `""`         | Custom path to frequency dictionary root (empty = auto-discover) |
+## Character names
 
-[^1]: Default banded palette (most common → least common): `#ed8796`, `#f5a97f`, `#f9e2af`, `#8bd5ca`, `#8aadf4`.
+Colors character names from the current show and lets you hover them for a portrait, role, and voice actor.
 
-When `sourcePath` is omitted, SubMiner searches default install/runtime locations for `frequency-dictionary` directories automatically.
+Needs: the [character dictionary](/character-dictionary), which SubMiner builds from AniList when you turn this on.
 
-::: info
-Frequency highlighting skips tokens that look like non-lexical noise (kana reduplication, short kana endings like `っ`), even when dictionary ranks exist.
-:::
+| Key                                    | What it does                                    |
+| -------------------------------------- | ----------------------------------------------- |
+| `subtitleStyle.nameMatchEnabled`       | Build the character dictionary and color names  |
+| `subtitleStyle.nameMatchImagesEnabled` | Show a small portrait next to each matched name |
+| `subtitleStyle.nameMatchColor`         | Color for character names                       |
 
-::: info
-Frequency, JLPT, and N+1 metadata are only shown for tokens that survive the subtitle-annotation noise filter. Standalone grammar tokens like `は`, `です`, and `この` are intentionally left unannotated even if a dictionary can assign them metadata.
-:::
+## Toggling during playback
 
-## JLPT Tagging
+Open the runtime options palette (`Ctrl/Cmd+Shift+O`) to switch these without restarting:
 
-JLPT tagging adds colored underlines to tokens based on their JLPT level (N1–N5), giving you an at-a-glance sense of difficulty distribution in each subtitle line.
+- known-word highlighting, maturity colors, and known-word match mode
+- N+1 highlighting
+- JLPT tagging
+- frequency highlighting
 
-**How it works:**
+Character names are toggled in the config file or the Settings window. Changes apply from the next subtitle line.
 
-SubMiner loads offline `term_meta_bank_*.json` files from `vendor/yomitan-jlpt-vocab` and matches each token's headword against the bank entries. Tokens with a recognized JLPT level receive a colored underline.
+## When layers overlap
 
-**Default colors:**
+If one word matches several layers, the first match in this list sets its color:
 
-| Level | Color     | Preview |
-| ----- | --------- | ------- |
-| N1    | `#ed8796` | Red     |
-| N2    | `#f5a97f` | Peach   |
-| N3    | `#f9e2af` | Yellow  |
-| N4    | `#8bd5ca` | Teal    |
-| N5    | `#8aadf4` | Blue    |
+1. Character name (also removes N+1, frequency, and JLPT marks)
+2. N+1 target
+3. Known word
+4. Frequency
 
-All colors are customizable via the `subtitleStyle.jlptColors` object.
-
-**Key settings:**
-
-| Option                             | Default   | Description                   |
-| ---------------------------------- | --------- | ----------------------------- |
-| `subtitleStyle.enableJlpt`         | `false`   | Enable JLPT underline styling |
-| `subtitleStyle.jlptColors.N1`–`N5` | see above | Per-level underline colors    |
-
-## Runtime Toggles
-
-All annotation layers can be toggled at runtime via the mpv command menu without restarting:
-
-- `ankiConnect.knownWords.highlightEnabled` (`On` / `Off`)
-- `subtitleStyle.nameMatchEnabled` (`On` / `Off`)
-- `subtitleStyle.nameMatchImagesEnabled` (`On` / `Off`)
-- `subtitleStyle.enableJlpt` (`On` / `Off`)
-- `subtitleStyle.frequencyDictionary.enabled` (`On` / `Off`)
-
-Toggles only apply to new subtitle lines after the change - the currently displayed line is not re-tokenized in place.
-
-## Rendering Priority
-
-When multiple annotations apply to the same token, the visual priority is:
-
-1. **N+1 target** (highest) - the single unknown word in an N+1 sentence
-2. **Character-name match** - dictionary-driven character-name token styling
-3. **Known-word color** - already-learned token tint
-4. **Frequency highlight** - common-word coloring (not applied when N+1/character-name/known-word already matched)
-5. **JLPT underline** - level-based underline (stacks with the above since it uses underline rather than text color)
+JLPT is an underline, so it shows alongside any of these except a character name.

docs-site/subtitle-generation.md

@@ -0,0 +1,89 @@
+# Japanese subtitle generation
+
+When a video has no Japanese subtitles, SubMiner can transcribe its audio into a Japanese SRT with [whisper.cpp](https://github.com/ggml-org/whisper.cpp). Everything runs on your computer. You only need internet access to download a model.
+
+## Setup
+
+1. Install whisper.cpp's `whisper-cli` and FFmpeg (including `ffprobe`). SubMiner downloads models but not these programs.
+2. Make sure they are on your `PATH`, or set their paths under **Settings > Integrations > Japanese Subtitle Generation** (`whisperPath`, `ffmpegPath`, `ffprobePath`).
+3. Pick a model. Either choose one in the generation modal and click **Download model**, or set `subtitleGeneration.modelPath` to a multilingual whisper.cpp GGML `.bin` file you already have. English-only models and Python Whisper checkpoints do not work.
+
+Downloaded models go to `models/whisper/` next to your SubMiner config file. A configured `modelPath` always wins over the modal's choice.
+
+YouTube videos can use the same setup automatically in place of YouTube's captions. See [Generate subtitles with Whisper](/youtube-integration#generate-subtitles-with-whisper).
+
+The modal's **Local tools** section lists anything missing. After you install a tool or change a path, click **Check again**.
+
+## Generating from the overlay
+
+1. Open a local video in mpv and select its Japanese audio track, or play a YouTube video.
+2. Press `Ctrl+Shift+G`. If the subtitle sidebar is empty, its **Generate Japanese subtitles** button opens the same modal.
+3. Pick a model and download it if needed.
+4. Optionally check **Focus on spoken dialogue** (see below).
+5. Click **Generate subtitles**.
+
+The modal shows progress. **Cancel** stops the job. Closing the modal lets the job keep running, and reopening it shows the progress.
+
+SubMiner saves `<video>.ja.generated.srt` next to the video and adds a number if that name is taken. If the same file is still playing, it loads the subtitles and resets the subtitle delay.
+
+For a YouTube video, SubMiner downloads its audio first and pauses the video until the subtitles load. The subtitles are temporary, and the audio is deleted when generation ends or you switch videos. See [YouTube integration](/youtube-integration#generate-subtitles-with-whisper).
+
+Change the shortcut with `shortcuts.openSubtitleGeneration`.
+
+## Generating from the launcher
+
+```bash
+subminer generate-subs                                  # current mpv file and audio track
+subminer generate-subs episode.mkv --download-model
+subminer generate-subs episode.mkv --model-path /path/to/ggml-small.bin
+```
+
+| Flag                     | What it does                                                  |
+| ------------------------ | ------------------------------------------------------------- |
+| `--model <name>`         | Use this managed model, such as `small` or `large-v3-turbo`   |
+| `--download-model`       | Download the managed model if it is missing                   |
+| `--model-path <path>`    | Use an existing model file                                    |
+| `--audio-stream <index>` | Pick an audio stream by its absolute FFmpeg index             |
+| `--output <path>`        | Write to this SRT path. Existing files are never overwritten. |
+
+With a file argument, SubMiner uses the audio stream tagged Japanese, or the first stream. `Ctrl+C` cancels.
+
+## Choosing a model
+
+The modal recommends **large-v3-turbo** if it finds an NVIDIA GPU (`nvidia-smi`) and your `whisper-cli` can use CUDA. Otherwise it recommends **small**. AMD, Vulkan, and Apple GPUs do not trigger the turbo recommendation. The recommendation does not change your settings.
+
+| Model                  | Tradeoff                                        |
+| ---------------------- | ----------------------------------------------- |
+| tiny, base             | Fast and small, more recognition errors         |
+| small                  | Balanced quality and CPU time                   |
+| medium, large-v1/v2/v3 | More accurate, needs more memory and time       |
+| large-v3-turbo         | Faster than large-v3 with a small accuracy loss |
+
+Quantized variants (`-q5_0`, `-q5_1`, `-q8_0`) use less disk and memory, with some accuracy loss. Your pick in the modal lasts for the session. Set `subtitleGeneration.managedModel` to change the default.
+
+## Prioritizing spoken dialogue
+
+**Focus on spoken dialogue** uses a speech detection (VAD) model to drop silent stretches before transcription. Long passages are split near detected speech, which reduces subtitles that appear before the line is spoken.
+
+It needs two extra pieces:
+
+- The Silero VAD model. Click **Download speech detection model** in the modal, or set `vadModelPath` to your own [Silero GGML model](https://huggingface.co/ggml-org/whisper-vad/tree/main).
+- whisper.cpp's [speech segment detector](https://github.com/ggml-org/whisper.cpp/tree/master/examples/vad-speech-segments), found as `whisper-vad-speech-segments` or `vad-speech-segments` on `PATH`. Set `vadPath` for any other location.
+
+The checkbox lasts for the session. Setting `vadModelPath` turns it on by default.
+
+Dialogue mode keeps music and background sound that might contain speech, so songs can still produce subtitles. It can also take longer than a plain run, because each passage is transcribed separately.
+
+## Using loaded subtitles as timing references
+
+If the video playing in mpv already has a dialogue subtitle track loaded, SubMiner uses its cue times to decide where to split long audio. This works with or without dialogue mode. Whisper still writes the Japanese text and final timestamps. The launcher uses a reference only when its input is the file open in mpv.
+
+SubMiner prefers English tracks and tracks labeled full or dialogue. It skips forced, image-based, generated, and signs or songs tracks, based on their titles and file names. An unlabeled signs-only file can slip through.
+
+The reference must be timed correctly for the video. SubMiner does not fix a mistimed reference.
+
+## Limitations
+
+- Only local files and their internal audio tracks are supported. Not URLs, and not a separate audio file loaded in mpv. Pass a separate local audio file to the launcher instead.
+- Whisper can miss, repeat, or invent lines, and its timing is approximate, especially over music or overlapping speech. Check the text and audio when you mine.
+- SubMiner does not translate subtitles.

docs-site/subtitle-sidebar.md

@@ -1,84 +1,70 @@
-# Subtitle Sidebar
+# Subtitle sidebar
 
-The subtitle sidebar displays the full parsed cue list for the active subtitle file as a scrollable panel alongside mpv. It lets you review past and upcoming lines, click any cue to seek directly to that moment, and follow along without depending on the transient overlay subtitles.
+The subtitle sidebar lists every line of the current subtitle file in a scrollable panel next to mpv. Use it to reread lines you missed, look ahead, jump to any line, or copy a stretch of dialogue.
 
-The sidebar is enabled by default. Set `subtitleSidebar.enabled` to `false` if you want to turn it off.
+## Using the sidebar
 
-## How It Works
+Press `\` to open or close it. The sidebar is on by default. Set `subtitleSidebar.enabled` to `false` to turn it off, or `subtitleSidebar.autoOpen` to `true` to open it at startup.
 
-When SubMiner parses the active subtitle source into a cue list, the sidebar becomes available. Toggle it with the `\` key (configurable via `subtitleSidebar.toggleKey`). While open:
+- Click a line to seek to it. With a line focused from the keyboard, `Enter` seeks to it.
+- The current line is highlighted and kept in view as playback moves (`autoScroll`).
+- Hovering the list pauses playback (`pauseVideoOnHover`).
+- Switching media or subtitle track updates the list.
 
-- The active cue is highlighted and kept in view as playback advances (when `autoScroll` is `true`).
-- Clicking any cue seeks mpv to that timestamp.
-- The sidebar stays synchronized with the overlay - media transitions and subtitle source changes update both simultaneously.
+The sidebar needs a subtitle file SubMiner can parse. Tracks that mpv renders itself, such as embedded ASS tracks, leave it empty. With no lines loaded, the sidebar shows a **Generate Japanese subtitles** button that opens [subtitle generation](/subtitle-generation). You can also open generation any time with `Ctrl+Shift+G`.
 
-The sidebar only appears when a parsed cue list is available. External subtitle sources that SubMiner cannot parse (for example, embedded ASS tracks rendered directly by mpv) will not populate the sidebar.
+For karaoke and animated ASS subtitles, SubMiner merges the per-frame effect lines into one clean line per cue.
 
-## Layout Modes
+## Copying dialogue {#selecting-and-copying-dialogue}
 
-Two layout modes are available via `subtitleSidebar.layout`:
+1. Drag across the text to select it. The selection can span several lines, and you can scroll to extend it.
+2. Press `Ctrl/Cmd+C` or click **Copy**.
 
-**`overlay`** (default) - The sidebar floats over mpv as a panel. It does not affect the player window size or position.
+SubMiner copies the text in subtitle order, without timestamps, with a blank line between cues. Dragging does not seek, and auto-scroll pauses while you have a selection. Press `Escape` to clear it. Changing media or subtitle track, or closing the sidebar, also clears it.
 
-**`embedded`** - Reserves space on the right side of the player and shifts the video area to mimic a split-pane layout. Useful if you want the cue list visible without it covering the video. If you see unexpected positioning in your environment, switch back to `overlay` to isolate the issue.
+## Layout
+
+`subtitleSidebar.layout` has two modes:
+
+- `overlay`: the sidebar floats over mpv and does not change the player window.
+- `embedded`: reserves space on the right of the player and moves the video over, so the list doesn't cover it. Placement depends on your compositor. If the geometry comes out wrong, switch back to `overlay`.
 
 ## Configuration
 
-Enable and configure the sidebar under `subtitleSidebar` in your config file:
+All keys live under `subtitleSidebar`. Defaults are in the [configuration reference](/configuration).
 
-```json
+| Key                 | What it does                                                    |
+| ------------------- | --------------------------------------------------------------- |
+| `enabled`           | Turn the sidebar on or off                                      |
+| `autoOpen`          | Open the sidebar when the overlay starts                        |
+| `layout`            | `overlay` or `embedded`                                         |
+| `toggleKey`         | Toggle key, as a `KeyboardEvent.code` value such as `Backslash` |
+| `pauseVideoOnHover` | Pause playback while the pointer is over the list               |
+| `autoScroll`        | Keep the current line in view                                   |
+| `css`               | Styling, see below                                              |
+
+`css` takes CSS properties (`font-family`, `font-size`, `color`, `background-color`, `opacity`) and these custom properties:
+
+| Property                                     | Styles                         |
+| -------------------------------------------- | ------------------------------ |
+| `--subtitle-sidebar-max-width`               | Maximum sidebar width          |
+| `--subtitle-sidebar-timestamp-color`         | Timestamp text                 |
+| `--subtitle-sidebar-active-line-color`       | Current line text              |
+| `--subtitle-sidebar-active-background-color` | Current line background        |
+| `--subtitle-sidebar-hover-background-color`  | Background of the hovered line |
+
+```jsonc
 {
   "subtitleSidebar": {
-    "enabled": true,
-    "autoOpen": false,
-    "layout": "overlay",
-    "toggleKey": "Backslash",
-    "pauseVideoOnHover": true,
-    "autoScroll": true,
+    "layout": "embedded",
     "css": {
-      "font-family": "Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP",
-      "color": "#cad3f5",
-      "background-color": "rgba(73, 77, 100, 0.9)",
-      "font-size": "16px",
-      "opacity": "0.95",
-      "--subtitle-sidebar-max-width": "420px",
-      "--subtitle-sidebar-timestamp-color": "#a5adcb",
-      "--subtitle-sidebar-active-line-color": "#f5bde6",
-      "--subtitle-sidebar-active-background-color": "rgba(138, 173, 244, 0.22)",
-      "--subtitle-sidebar-hover-background-color": "rgba(54, 58, 79, 0.84)"
-    }
-  }
+      "font-size": "18px",
+      "--subtitle-sidebar-max-width": "480px",
+    },
+  },
 }
 ```
 
-Styling lives under the `css` object, using CSS property names and CSS custom properties (the same pattern as `subtitleStyle.css`).
+Your `css` object replaces the default one as a whole. To keep a default value, copy it from the configuration reference into your object.
 
-| Option              | Type    | Default       | Description                                                                |
-| ------------------- | ------- | ------------- | -------------------------------------------------------------------------- |
-| `enabled`           | boolean | `true`        | Enable subtitle sidebar support                                            |
-| `autoOpen`          | boolean | `false`       | Open the sidebar automatically on overlay startup                          |
-| `layout`            | string  | `"overlay"`   | `"overlay"` floats over mpv; `"embedded"` reserves right-side player space |
-| `toggleKey`         | string  | `"Backslash"` | `KeyboardEvent.code` for the toggle shortcut                               |
-| `pauseVideoOnHover` | boolean | `true`        | Pause playback while hovering the cue list                                 |
-| `autoScroll`        | boolean | `true`        | Keep the active cue in view during playback                                |
-
-| `css` property                              | Default                     | Description                  |
-| ------------------------------------------- | --------------------------- | ---------------------------- |
-| `font-family`                               | `Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP` | Cue text font family |
-| `color`                                     | `#cad3f5`                   | Default cue text color       |
-| `background-color`                          | `rgba(73, 77, 100, 0.9)`    | Sidebar shell background color |
-| `font-size`                                 | `16px`                      | Base cue font size           |
-| `opacity`                                   | `0.95`                      | Sidebar opacity between `0` and `1` |
-| `--subtitle-sidebar-max-width`              | `420px`                     | Maximum sidebar width        |
-| `--subtitle-sidebar-timestamp-color`        | `#a5adcb`                   | Cue timestamp color          |
-| `--subtitle-sidebar-active-line-color`      | `#f5bde6`                   | Active cue text color        |
-| `--subtitle-sidebar-active-background-color`| `rgba(138, 173, 244, 0.22)` | Active cue background color  |
-| `--subtitle-sidebar-hover-background-color` | `rgba(54, 58, 79, 0.84)`    | Hovered cue background color |
-
-## Keyboard Shortcut
-
-| Key | Action                  | Config key                     |
-| --- | ----------------------- | ------------------------------ |
-| `\` | Toggle subtitle sidebar | `subtitleSidebar.toggleKey`    |
-
-The toggle is overlay-local and only opens when SubMiner has a parsed cue list for the active subtitle source. See [Keyboard Shortcuts](/shortcuts) for the full shortcut reference.
+See [keyboard shortcuts](/shortcuts) for all overlay keys.

docs-site/troubleshooting.md

@@ -1,343 +1,205 @@
 # Troubleshooting
 
-Common issues and how to resolve them. Most problems fall into one of a few buckets - the overlay shows but subtitles don't (see [MPV Connection](#mpv-connection)), cards aren't being created or come out empty (see [AnkiConnect](#ankiconnect)), or word lookups don't appear (see [Yomitan](#yomitan)). If an error message popped up on screen, search this page for the exact text - most headings below are quoted error strings.
+Find your symptom below. If you saw an error message, search this page for its text.
 
-## MPV Connection
+## Diagnose first
 
-**Overlay starts but shows no subtitles**
-
-SubMiner connects to mpv via a Unix socket (or named pipe on Windows). If the socket does not exist or the path does not match, the overlay will appear but subtitles will never arrive.
-
-- Ensure mpv is running with `--input-ipc-server=/tmp/subminer-socket`.
-- If you use a custom socket path, set it in both your mpv config and SubMiner config (`mpv.socketPath`).
-- The `subminer` wrapper script sets the socket automatically when it launches mpv. If you launch mpv yourself, the `--input-ipc-server` flag is required.
-
-SubMiner retries the connection automatically with increasing delays (200 ms, 500 ms, 1 s, 2 s on first connect; 1 s, 2 s, 5 s, 10 s on reconnect). If mpv exits and restarts, the overlay reconnects without needing a restart.
-
-If the overlay never appears at all, see [Playback Startup Flow](./architecture#playback-startup-flow) for how a managed launch starts mpv and brings up the overlay.
-
-## Logging and App Mode
-
-- Default log output is `warn`.
-- Use `--log-level` for more/less output.
-- Use `--dev`/`--debug` only to force app/dev mode (for example to get dev behavior from the overlay/app); they do not change log verbosity.
-- You can combine both, for example `SubMiner.AppImage --start --dev --log-level debug`, when you need maximum diagnostics.
-
-## Performance and Resource Impact
-
-### At a glance
-
-- Baseline: `SubMiner --start` is usually lightweight for normal playback.
-- Common spikes come from:
-  - first subtitle parse/tokenization bursts
-  - media generation (`ffmpeg` audio/image and AVIF paths)
-  - media sync and subtitle tooling (`alass`, `ffsubsync`)
-  - `ankiConnect` enrichment (plus polling overhead when proxy mode is disabled)
-
-### If playback feels sluggish
-
-1. Reduce overlay workload:
-
-- set secondary subtitles hidden:
-  - `secondarySub.defaultMode: "hidden"`
-- disable optional enrichment:
-  - `subtitleStyle.enableJlpt: false`
-  - `subtitleStyle.frequencyDictionary.enabled: false`
-
-2. Reduce rendering pressure:
-
-- lower `subtitleStyle.css["font-size"]`
-- keep overlay complexity minimal during heavy CPU periods
-
-3. Reduce media overhead:
-
-- keep `ankiConnect.media.imageType` set to `static` (avoid animated AVIF unless needed)
-- lower `ankiConnect.media.imageQuality`
-- reduce `ankiConnect.media.maxMediaDuration`
-
-4. Lower integration cost:
-
-- disable AI translation when not needed (`ankiConnect.ai.enabled: false`)
-- if needed, run immersion telemetry with lower duration expectations (`immersionTracking.enabled: false` for constrained sessions)
-- favor the default lightweight YouTube subtitle startup settings on low-resource systems
-
-### Practical low-impact profile
-
-```json
-{
-  "subtitleStyle": {
-    "css": {
-      "font-size": "30px"
-    },
-    "enableJlpt": false,
-    "frequencyDictionary": {
-      "enabled": false
-    }
-  },
-  "secondarySub": {
-    "defaultMode": "hidden"
-  },
-  "ankiConnect": {
-    "media": {
-      "imageType": "static",
-      "imageQuality": 80,
-      "maxMediaDuration": 12
-    },
-    "ai": {
-      "enabled": false
-    }
-  },
-  "immersionTracking": {
-    "enabled": false
-  }
-}
-```
-
-### If usage is still high
-
-- Confirm only one SubMiner instance is running.
-- Check whether bottlenecks are `ffmpeg`, `yt-dlp`, or sync tooling in system monitor.
-- Keep the default `warn` level for normal use; raise to `info` or `debug` only for targeted diagnosis.
-- Reproduce once with `SubMiner.AppImage --start --log-level debug` and open DevTools (`y` then `d`) if freezes recur.
-
-**"Failed to parse MPV message"**
-
-Logged when a malformed JSON line arrives from the mpv socket. Usually harmless - SubMiner skips the bad line and continues. If it happens constantly, check that nothing else is writing to the same socket path.
-
-## Updates
-
-**"Update check failed"**
-
-Manual update checks show this when GitHub Releases or updater metadata cannot be reached. Check your network connection, then try again from the tray menu or:
+Run the launcher's dependency check:
 
 ```bash
-subminer -u
+subminer doctor
 ```
 
-Automatic checks log failures quietly so playback is not interrupted.
+It reports the app binary, `mpv`, `yt-dlp`, `ffmpeg`, `fzf`, `rofi`, your config file, and the mpv socket path. It exits non-zero when the app binary or `mpv` is missing.
 
-**"SubMiner is up to date" but a prerelease exists**
+Logs are written to daily files:
 
-SubMiner uses the configured release channel for update checks. Set `updates.channel` to `"prerelease"` in `config.jsonc` when you want update checks to include beta and RC releases.
+| Platform      | Log directory              |
+| ------------- | -------------------------- |
+| Linux / macOS | `~/.config/SubMiner/logs/` |
+| Windows       | `%APPDATA%\SubMiner\logs\` |
 
-**Launcher update shows a sudo command**
+Files are named `app-<date>.log`, `launcher-<date>.log`, and `mpv-<date>.log`. The mpv log is off by default. Turn log files on or off and set retention under [`logging`](/configuration#logging).
 
-The detected launcher is installed in a protected path such as `/usr/local/bin/subminer` or `/usr/bin/subminer`. SubMiner does not elevate itself. Run the command shown in the popup to replace the launcher after checksum verification.
+For more detail, raise the log level for one run:
 
-**OSD update notification did not appear**
+```bash
+subminer --log-level debug video.mkv
+SubMiner.AppImage --start --log-level debug
+```
 
-`updates.notificationType: "osd"` uses the legacy mpv OSD path. If mpv is disconnected, SubMiner logs the update and does not force-start the overlay. Use `"system"` for OS notifications, `"both"` for overlay + OS notifications, or `"osd-system"` in `config.jsonc` if you want the legacy OSD + OS combination.
+The default level is `warn`. `--dev` and `--debug` switch the app into dev mode but do not change log verbosity. To inspect the overlay itself, focus it and press `y` then `d` to open DevTools.
 
-## AnkiConnect
+## Overlay starts but shows no subtitles
 
-**"AnkiConnect: unable to connect"**
+SubMiner reads subtitles from mpv over an IPC socket (a named pipe on Windows). If the paths do not match, the overlay appears but stays empty.
 
-First confirm you've completed the [Anki Integration prerequisites](/anki-integration#prerequisites) - Anki must be running with the AnkiConnect add-on installed.
+- The `subminer` launcher sets the socket for you. If you start mpv yourself, pass `--input-ipc-server=/tmp/subminer-socket`.
+- If you changed `mpv.socketPath`, use the same path in your mpv config.
 
-SubMiner connects to the active Anki endpoint:
+SubMiner reconnects on its own if mpv restarts.
 
-- `ankiConnect.url` (direct mode, default `http://127.0.0.1:8765`)
-- `http://<ankiConnect.proxy.host>:<ankiConnect.proxy.port>` (proxy mode)
+## Overlay does not appear
 
-This error means the active endpoint is unavailable, or (in proxy mode) the proxy cannot reach `ankiConnect.proxy.upstreamUrl`.
+- Confirm SubMiner is running (`SubMiner.AppImage --start`, or check for the process).
+- Linux: Hyprland and Sway work natively. Any other compositor needs mpv and SubMiner under X11 or Xwayland, with `xdotool`, `xprop`, and `xwininfo` installed. See [KDE Plasma and other Wayland compositors](#kde-plasma-and-other-wayland-compositors).
+- macOS: grant Accessibility permission in System Settings > Privacy & Security > Accessibility.
 
-- If you changed the AnkiConnect port, update `ankiConnect.url` (or `ankiConnect.proxy.upstreamUrl` if using proxy mode).
-- If using external Yomitan/browser clients, confirm they point to your SubMiner proxy URL.
+## Overlay is on the wrong monitor or position
 
-SubMiner retries with exponential backoff (up to 5 s) and suppresses repeated error logs after 5 consecutive failures. When Anki comes back, you will see "AnkiConnect connection restored".
+SubMiner follows the mpv window. Tracking needs `hyprctl` (Hyprland), `swaymsg` (Sway), or `xdotool` and `xwininfo` (X11) on `PATH`.
 
-**Cards are created but fields are empty**
+If the position is only slightly off, right-click and drag the subtitle text to adjust the offset.
 
-Field names in your config must match your Anki note type exactly (case-sensitive). Check `ankiConnect.fields` - for example, if your note type uses `SentenceAudio` but your config says `Audio`, the field will not be populated.
+## Clicks pass through the overlay
 
-See [Anki Integration](/anki-integration) for the full field mapping reference.
+- The overlay only takes input while the cursor is over subtitle text. Hover the text directly.
+- Toggle the overlay off and on with `Alt+Shift+O`.
+- Linux: if clicks keep failing, toggle the overlay off, click the mpv window, then toggle it back on.
 
-**"Update failed" OSD message**
+## Hovering a word shows no popup
 
-Shown when SubMiner tries to update a card that no longer exists, or when AnkiConnect rejects the update. Common causes:
+If you have not set up dictionaries yet, start with [Yomitan setup](/usage#yomitan-setup).
 
-- The card was deleted in Anki between creation and enrichment update.
-- The note type changed and a mapped field no longer exists.
+- Open Yomitan settings (`Alt+Shift+Y` or `SubMiner.AppImage --yomitan`) and confirm at least one dictionary is imported and enabled.
+- If `yomitan.externalProfilePath` is set, manage dictionaries in that external profile. SubMiner opens it read-only and has no settings window of its own in that mode.
+- Check the log for "Loaded Yomitan extension".
 
-## Overlay
+Word boundaries come from Yomitan's parser. Some splits will be wrong, since Japanese has no spaces.
 
-**Overlay does not appear**
+## "Electron downgrade blocked" or "Unsupported Electron runtime"
 
-- Confirm SubMiner is running: `SubMiner.AppImage --start` or check for the process.
-- On Linux, the overlay requires a supported window backend. Hyprland and Sway have native Wayland support; all other compositors require both mpv and SubMiner to run under X11 or Xwayland (`xdotool` and `xwininfo` must be installed).
-- On macOS, grant Accessibility permission to SubMiner in System Settings > Privacy & Security > Accessibility.
+SubMiner refuses to load Yomitan storage when the current Electron major does not match the app build, or when the profile was previously opened by a newer Electron major or minor version. Patch downgrades within the same major and minor version are allowed, such as `43.7.3` to `43.7.2`. Downgrades from `43.7.x` to `43.6.x`, or from Electron 43 to 42, are blocked. Launch the packaged app or use the repository's `bun run dev` command. Do not delete the runtime safety record to force an older major or minor version to open the profile.
 
-**Overlay appears but clicks pass through / cannot interact**
+Older SubMiner builds without this guard cannot enforce the safety record. When testing Electron 43 before returning to an older Electron 42 build, use the separate `SubMiner-dev` profile described in [development](/development#run-locally) so the older build never opens the upgraded profile.
 
-- Make sure you are hovering over subtitle text - the overlay only becomes interactive when the cursor is over a subtitle.
-- On macOS/Windows: toggle the overlay off and back on (`Alt+Shift+O`) to re-enable pointer events.
-- On Linux: mouse event handling is unreliable in some Electron/compositor combinations. If clicks consistently fail, toggle the overlay off, click the underlying mpv window, then toggle it back on.
+## "Yomitan reported zero dictionaries after previously reporting ..."
 
-**Overlay briefly freezes after a modal/runtime error**
+SubMiner detected that a previously non-empty Yomitan profile suddenly appears empty. Automatic character-dictionary changes are blocked so they cannot overwrite the suspicious state. Close SubMiner, preserve the profile directory, and restore a known-good backup before importing or deleting dictionaries.
 
-- Renderer errors now trigger an automatic recovery path. You should see a short toast ("Renderer error recovered. Overlay is still running.").
-- Recovery closes any open modal and restores click-through/shortcuts automatically without interrupting mpv playback.
-- If errors keep recurring, toggle the overlay's DevTools using overlay chord `y` then `d` (or global `F12`) and inspect the `renderer overlay recovery` error payload for stack trace + modal/subtitle context.
+## "Yomitan extension not found in any search path"
 
-**Overlay is on the wrong monitor or position**
+The bundled Yomitan is missing. Re-download the AppImage, or place an unpacked Yomitan extension in `~/.config/SubMiner/yomitan`. Source builds must run `bun run build` first to produce `build/yomitan`.
 
-SubMiner positions the overlay by tracking the mpv window. If tracking fails:
+## "MeCab not found on system"
 
-- Hyprland: Ensure `hyprctl` is available.
-- Sway: Ensure `swaymsg` is available.
-- X11: Ensure `xdotool` and `xwininfo` are installed.
+This is informational. Tokenization uses Yomitan, not MeCab. Install MeCab only if you want to silence the message:
 
-If the overlay position is slightly off, right-click and drag on subtitle text to fine-tune the overlay subtitle offset.
+- Arch: `sudo pacman -S mecab mecab-ipadic`
+- Ubuntu/Debian: `sudo apt install mecab libmecab-dev mecab-ipadic-utf8`
+- macOS: `brew install mecab mecab-ipadic`
 
-## Yomitan
+## "AnkiConnect: unable to connect"
 
-If you haven't set up dictionaries yet, see [Yomitan setup](/usage#yomitan-setup) first.
+Anki must be running with the AnkiConnect add-on. See [Anki integration prerequisites](/anki-integration#prerequisites).
 
-**"Yomitan extension not found in any search path"**
+- Direct mode: check that `ankiConnect.url` matches the AnkiConnect port.
+- Proxy mode: check `ankiConnect.proxy.upstreamUrl`, and point external Yomitan or browser clients at the SubMiner proxy.
 
-SubMiner bundles Yomitan and searches for it in these locations (in order):
+SubMiner keeps retrying and logs "AnkiConnect connection restored" once Anki is back.
 
-1. `build/yomitan` (local/source build output)
-2. `<resources>/yomitan` (Electron resources path)
-3. `/usr/share/SubMiner/yomitan`
-4. `~/.config/SubMiner/yomitan` (user-data fallback on Linux)
+## Cards are created but fields are empty
 
-SubMiner does not load the source tree directly from `vendor/subminer-yomitan`; source builds must produce `build/yomitan` first.
+Each name in `ankiConnect.fields` must match a field on your note type. Matching is case-insensitive, but otherwise the spelling must match. Unknown fields are skipped without an error. For example, config `Audio` does not fill a note field named `SentenceAudio`. See [Anki integration](/anki-integration).
 
-If you installed from the AppImage and see this error, the package may be incomplete. Re-download the AppImage or place the unpacked Yomitan extension manually in `~/.config/SubMiner/yomitan`.
+## "Update failed" when mining
 
-**Yomitan lookup popup does not appear when hovering words or triggering lookup**
+The card was deleted in Anki before SubMiner finished enriching it, or the note type changed and a mapped field no longer exists.
 
-- Verify Yomitan loaded successfully - check the terminal output for "Loaded Yomitan extension".
-- Yomitan requires dictionaries to be installed. Open Yomitan settings (`Alt+Shift+Y` or `SubMiner.AppImage --yomitan`) and confirm at least one dictionary is imported.
-- If `yomitan.externalProfilePath` is set, import/check dictionaries in the external app/profile instead. SubMiner treats that profile as read-only and does not open its own Yomitan settings window.
-- If the overlay shows subtitles but hover lookup never resolves on tokens, the tokenizer may have failed. See the MeCab section below.
+## "Subtitle timing not found; copy again while playing"
 
-## MeCab / Tokenization
+SubMiner has no timing for the current line yet. This happens when paused before any subtitle arrived, after switching subtitle tracks, or while an external subtitle file is still loading. Resume playback, wait for the next line, and mine again.
 
-**"MeCab not found on system"**
+## "FFmpeg not found"
 
-This is informational, not an error. SubMiner tokenization is driven by Yomitan's internal parser. MeCab availability checks may still run for auxiliary token metadata, but MeCab is not used as a tokenization fallback path.
+Audio clips and screenshots need FFmpeg. Without it, cards are still created with empty media fields.
 
-To install MeCab:
+- Arch: `sudo pacman -S ffmpeg`
+- Ubuntu/Debian: `sudo apt install ffmpeg`
+- macOS: `brew install ffmpeg`
 
-- **Arch Linux**: `sudo pacman -S mecab mecab-ipadic`
-- **Ubuntu/Debian**: `sudo apt install mecab libmecab-dev mecab-ipadic-utf8`
-- **macOS**: `brew install mecab mecab-ipadic`
+## Audio or screenshot generation is slow or times out
 
-**Words are not segmented correctly**
+- Use a local copy if the video is on a slow network mount.
+- Set `ankiConnect.media.imageType` to `"static"`. Animated AVIF is the slowest path.
+- Lower `ankiConnect.media.imageQuality` or `ankiConnect.media.maxMediaDuration`.
 
-Japanese word boundaries depend on Yomitan parser output. If segmentation seems wrong:
+## Subtitle sync (subsync)
 
-- Verify Yomitan dictionaries are installed and active.
-- Note that CJK characters without spaces are segmented using parser heuristics, which is not always perfect.
+Subtitle sync needs at least one of alass or ffsubsync. Neither ships with SubMiner.
 
-## Character Dictionary
+**"Configured alass executable not found"**: install it (`paru -S alass` or `cargo install alass-cli`), or set `subsync.alass_path`.
 
-Character names from AniList are matched and highlighted in subtitles via the bundled Yomitan. See [Character Dictionary](/character-dictionary) for setup and the full troubleshooting list - the most common issues:
+**"Configured ffsubsync executable not found"**: install it (`paru -S python-ffsubsync` or `pip install ffsubsync`), or set `subsync.ffsubsync_path`.
 
-- **Names not highlighting:** Confirm `subtitleStyle.nameMatchEnabled` is `true`, and that the current media resolved to an AniList entry (SubMiner needs a media ID to fetch characters). No AniList account or token is required - character data uses public GraphQL queries.
-- **Inline portraits missing:** Confirm `subtitleStyle.nameMatchImagesEnabled` is `true`. Portraits also require AniList to return an image and the download to succeed during snapshot generation.
-- **Wrong characters showing:** Open the in-app manager (`Ctrl/Cmd+D`) and use **Override** to pin the correct AniList match for the series.
-- **Feature unavailable:** If `yomitan.externalProfilePath` is set, SubMiner runs in read-only external-profile mode and its character-dictionary features are disabled.
+**"alass synchronization failed" / "ffsubsync synchronization failed"**:
 
-## Media Generation
+- alass needs a reference: a second subtitle track or the local video file. It cannot use the track being retimed.
+- `ffmpeg` must be installed to extract internal subtitle tracks.
+- ffsubsync only works on local files, not streams.
+- Run the tool by hand to see its full error output.
 
-**"FFmpeg not found"**
+## "xz binary not found"
 
-SubMiner uses FFmpeg to extract audio clips and generate screenshots. Install it:
+TsukiHime subtitles are xz-compressed. Install `xz`:
 
-- **Arch Linux**: `sudo pacman -S ffmpeg`
-- **Ubuntu/Debian**: `sudo apt install ffmpeg`
-- **macOS**: `brew install ffmpeg`
+- Arch: `sudo pacman -S xz`
+- Ubuntu/Debian: `sudo apt install xz-utils`
+- Fedora: `sudo dnf install xz`
+- macOS: `brew install xz`
+- Windows: `scoop install main/xz`, or download XZ Utils from [tukaani.org/xz](https://tukaani.org/xz/) and add the folder with `xz.exe` to `PATH`. Restart SubMiner afterwards.
 
-Without FFmpeg, card creation still works but audio and image fields will be empty.
-
-**Audio or screenshot generation hangs**
-
-Media generation has a 30-second timeout (60 seconds for animated AVIF). If your video file is on a slow network mount or the codec requires software decoding, generation may time out. Try:
-
-- Using a local copy of the video file.
-- Reducing `media.imageQuality` or switching from `avif` to `static` image type.
-- Checking that `media.maxMediaDuration` is not set too high.
-
-## Shortcuts
-
-**"Failed to register global shortcut"**
-
-Global shortcuts (`Alt+Shift+O`, `Alt+Shift+Y`) may conflict with other applications or desktop environment keybindings.
-
-- Check your DE/WM keybinding settings for conflicts.
-- Change the shortcut in your config under `shortcuts.toggleVisibleOverlayGlobal`.
-- On Wayland, global shortcut registration has limitations depending on the compositor. Only Hyprland and Sway are supported natively - see the [Hyprland](#hyprland) section below for shortcut passthrough rules. Other Wayland compositors require X11/Xwayland.
-
-**Overlay keybindings not working**
-
-Overlay-local shortcuts (Space, arrow keys, etc.) only work when the overlay window has focus. Click on the overlay or use the global shortcut to toggle it to give it focus.
-
-## Subtitle Timing
-
-**"Subtitle timing not found; copy again while playing"**
-
-This OSD message appears when you try to mine a sentence but SubMiner has no timing data for the current subtitle. Causes:
-
-- The video is paused and no subtitle has been received yet.
-- The subtitle track changed and timing data was cleared.
-- You are using an external subtitle file that mpv has not fully loaded.
-
-Resume playback and wait for the next subtitle to appear, then try mining again.
-
-## Subtitle Sync (Subsync)
-
-Both **alass** and **ffsubsync** are optional external dependencies. Subtitle syncing requires at least one of them to be installed.
-
-**"Configured alass executable not found"**
-
-Install alass or configure the path:
-
-- **Arch Linux (AUR)**: `paru -S alass`
-- **Cargo**: `cargo install alass-cli`
-- Set the path: `subsync.alass_path` in your config.
-
-**"Configured ffsubsync executable not found"**
-
-Install ffsubsync or configure the path:
-
-- **Arch Linux (AUR)**: `paru -S python-ffsubsync`
-- **pip**: `pip install ffsubsync`
-- Must be on `PATH` or configured via `subsync.ffsubsync_path` in your config.
-
-**"Subtitle synchronization failed"**
-
-If subtitle sync fails:
-
-- Ensure the reference subtitle track exists in the video (alass requires a source track).
-- Check that `ffmpeg` is available (used to extract the internal subtitle track).
-- Try running the sync tool manually to see detailed error output.
-- ffsubsync requires local files and cannot handle remote media streams (e.g., streaming URLs).
+Other TsukiHime errors are covered in [TsukiHime integration](/tsukihime-integration#troubleshooting).
 
 ## Jimaku
 
-**"Jimaku request failed" or HTTP 429**
+**"Jimaku request failed" or HTTP 429**: you hit the Jimaku rate limit. Wait for the time shown in the message. Setting `jimaku.apiKey` or `jimaku.apiKeyCommand` gives you a higher limit.
 
-The Jimaku API has rate limits. If you see 429 errors, wait for the retry duration shown in the OSD message and try again. If you have a Jimaku API key, set it in `jimaku.apiKey` or `jimaku.apiKeyCommand` to get higher rate limits.
+## Character names are not highlighted
 
-## Platform-Specific
+See [Character dictionary](/character-dictionary) for the full list. The common causes:
 
-### Linux
+- `subtitleStyle.nameMatchEnabled` is off, or the media did not resolve to an AniList entry.
+- Portraits need `subtitleStyle.nameMatchImagesEnabled`.
+- Wrong characters: open the manager (`Ctrl/Cmd+D`) and use **Override** to pick the right AniList entry.
+- The feature is disabled when `yomitan.externalProfilePath` is set.
 
-- **Wayland (Hyprland/Sway only)**: Native Wayland support is limited to Hyprland and Sway. Window tracking uses compositor-specific commands (`hyprctl` / `swaymsg`). If these are not on `PATH`, tracking will fail silently. Other Wayland compositors (KDE Plasma, GNOME, …) are not supported natively - both mpv and SubMiner must run under X11 or Xwayland instead. On those sessions SubMiner forces XWayland automatically for itself and for every mpv it launches (see [KDE Plasma & other Wayland compositors](#kde-plasma--other-wayland-compositors)).
-- **X11 / Xwayland**: Requires `xdotool`, `xprop`, and `xwininfo`. If missing, the overlay cannot track the mpv window position. This is the required backend for any Wayland compositor other than Hyprland or Sway - both mpv and SubMiner must be running under X11/Xwayland for window tracking _and_ for the overlay to stay above mpv (Wayland forbids clients from controlling window stacking). SubMiner uses a managed X11 overlay while mpv is windowed, switches to an override-redirect X11 overlay while tracked mpv is fullscreen, and hides/releases that overlay when another X11/Xwayland app takes focus. The visible overlay stays hidden until SubMiner has tracked mpv geometry, so startup should not create a display-sized fallback overlay while tokenization warms up.
-- **Tray icon missing**: SubMiner creates an Electron tray icon in `--background` mode, but Linux trays require a StatusNotifier/AppIndicator host. Hyprland does not provide one by itself; enable a tray in Waybar, Hyprpanel, or another panel. If Electron cannot register the tray, SubMiner logs a warning that mentions the missing tray host.
-- **Mouse passthrough**: On Linux X11/Xwayland, SubMiner uses `xdotool` to poll the cursor and only enables overlay input while the cursor is over subtitle or popup regions. Outside those regions, pointer input passes through to mpv. Native Wayland compositors other than Hyprland/Sway cannot provide the stacking control SubMiner needs.
+## "Failed to register global shortcut"
+
+Another app or your desktop already uses `Alt+Shift+Y` (Yomitan settings). Free it in your desktop or window manager settings. On Hyprland, add a `pass` rule (see [Hyprland](#hyprland)).
+
+## Overlay shortcuts do nothing
+
+Overlay shortcuts only work while the overlay has focus. Click the overlay, or press `Alt+Shift+O` with mpv or the overlay focused.
+
+## Update checks
+
+**"Update check failed"**: GitHub could not be reached. Check your connection and retry from the tray menu or with `subminer -u`.
+
+**No prerelease offered**: set `updates.channel` to `"prerelease"` to include beta and RC builds.
+
+**Launcher update shows a sudo command**: the launcher lives in a protected path such as `/usr/local/bin`. Run the command shown to replace it.
+
+## Playback feels sluggish
+
+Idle playback is cheap. Load comes from the first tokenization burst, media generation, subtitle sync, and Anki enrichment. To cut it:
+
+- `ankiConnect.media.imageType: "static"`, plus lower `imageQuality` and `maxMediaDuration`.
+- `subtitleStyle.enableJlpt: false` and `subtitleStyle.frequencyDictionary.enabled: false`.
+- `secondarySub.defaultMode: "hidden"`.
+- `immersionTracking.enabled: false` to stop stats logging.
+
+Also check that only one SubMiner instance is running, and whether `ffmpeg`, `yt-dlp`, or a sync tool is the process using CPU.
+
+## Linux
+
+### Tray icon missing
+
+Linux trays need a StatusNotifier/AppIndicator host. Hyprland has none by default. Enable a tray in Waybar, Hyprpanel, or another panel.
 
 ### Hyprland
 
-SubMiner's overlay is a transparent, frameless Electron window that must be kept above mpv. SubMiner tries to apply the floating, borderless, no-shadow, and no-blur properties itself each time it places the overlay. It detects Hyprland's active config provider and uses Lua `hl.dsp.window.*` dispatchers for recent Hyprland Lua configs, or the legacy dispatcher syntax for older hyprlang configs. On many configurations that is enough, but if your Hyprland version doesn't honor those runtime dispatches - or a broad rule in your config forces opacity/blur on every window - add explicit window rules so the overlay is exempt. You also need `pass` bindings to forward global shortcuts to SubMiner (see below).
-
-**Overlay is not transparent or has a visible border**
-
-Add a window rule matching SubMiner's window class. Recent Hyprland uses the Lua config format:
+SubMiner applies float, no-border, and no-blur properties to its window itself. If the overlay still has a border or an opaque background, a global opacity or blur rule is usually overriding it. Add a rule for the `SubMiner` class. Lua config:
 
 ```lua
 hl.window_rule({
@@ -354,7 +216,7 @@ hl.window_rule({
 })
 ```
 
-On older Hyprland releases that still use the hyprlang config (`hyprland.conf`), use the equivalent `windowrule` lines:
+Older `hyprland.conf` configs:
 
 ```ini
 windowrule = float on, match:class SubMiner
@@ -364,74 +226,34 @@ windowrule = no_shadow on, match:class SubMiner
 windowrule = no_blur on, match:class SubMiner
 ```
 
-If you still see a solid background or visual artifacts instead of the mpv video underneath, the culprit is almost always a global opacity/blur rule applying to the overlay - the `opaque`/`opacity` and `no_blur` fields above override it.
-
-**Global shortcuts not working**
-
-On Hyprland, Electron cannot register global shortcuts on its own. You must explicitly pass keybindings to SubMiner using `pass` rules:
+Hyprland swallows global shortcuts unless you pass them through. Add a `pass` bind for each one, and update it if you remap the key:
 
 ```ini
 bind = ALT SHIFT, O, pass, class:^(SubMiner)$
 bind = ALT SHIFT, Y, pass, class:^(SubMiner)$
 ```
 
-Add a `pass` rule for each global shortcut you configure. The defaults are `Alt+Shift+O` (toggle overlay) and `Alt+Shift+Y` (Yomitan settings). If you remap `shortcuts.toggleVisibleOverlayGlobal` to a different key, update the `pass` rule to match.
+If the overlay stays behind fullscreen mpv, check that the mpv socket is connected and that `hyprctl -j clients` works from the environment that launched SubMiner.
 
-Without these rules, Hyprland intercepts the keypresses before they reach SubMiner, and the shortcuts silently do nothing.
+SubMiner restacks the existing overlay during fullscreen transitions on Hyprland. It keeps the overlay mapped so repeated hide/show calls do not steal focus and cancel mpv's fullscreen entry. Sway retains the hide/show refresh because SubMiner has no Sway-specific restacking implementation.
 
-**Overlay stays behind mpv after fullscreen**
+See the Hyprland wiki on [global keybinds](https://wiki.hypr.land/Configuring/Binds/#global-keybinds) and [window rules](https://wiki.hypr.land/Configuring/Window-Rules/).
 
-SubMiner watches mpv's `fullscreen` property and refreshes the overlay geometry when it changes. If the overlay still does not move or rise above fullscreen mpv, confirm that the mpv IPC socket is connected and that `hyprctl -j clients` and `hyprctl -j monitors` work from the same environment that launched SubMiner.
+### KDE Plasma and other Wayland compositors
 
-For more details, see the Hyprland docs on [global keybinds](https://wiki.hypr.land/Configuring/Binds/#global-keybinds) and [window rules](https://wiki.hypr.land/Configuring/Window-Rules/).
+Outside Hyprland and Sway, Wayland does not let the overlay stay on top of mpv, so both must run under Xwayland. SubMiner does this automatically for itself and for every mpv it launches (launcher, tray, Jellyfin, YouTube). Install `xdotool`, `xprop`, and `xwininfo`.
 
-### KDE Plasma & other Wayland compositors
+**Overlay sits behind mpv, and hover or Yomitan stops working**: mpv started as a native Wayland window. This happens when you launch mpv yourself. Launch through SubMiner, or force Xwayland in your own command:
 
-On any Wayland session that is not Hyprland or Sway (KDE Plasma, GNOME, and others), the overlay can only stay above mpv when both processes run under **XWayland** - the Wayland protocol forbids clients from controlling window stacking, so the overlay's "always on top" becomes a no-op on a native Wayland surface.
+```bash
+mpv --gpu-context=x11vk,x11egl,x11 video.mkv
+```
 
-SubMiner handles this automatically:
+`WAYLAND_DISPLAY= mpv video.mkv` also works, as does `gpu-context=x11vk` (or `x11egl`) in `mpv.conf`. To check, `xdotool search --class mpv` should print a window id.
 
-- It launches its own window under XWayland (it sets `--ozone-platform-hint=x11`).
-- Every mpv it launches (via the `subminer` launcher, Jellyfin, or YouTube) is pinned to XWayland too - Wayland environment hints are stripped and an X11 GPU context (`--gpu-context=x11egl,x11`) is applied.
-- While mpv is windowed, the overlay is a managed X11 window owned by the tracked mpv window (`WM_TRANSIENT_FOR`), so it stays above mpv while other foreground X11/Xwayland apps can still cover both windows.
-- While tracked mpv is fullscreen, SubMiner swaps the visible overlay to a focusable-false X11 override-redirect window. That path can stay above the active fullscreen mpv window without requiring a KDE/KWin-specific rule, and SubMiner hides/releases it when mpv is no longer the active X11/Xwayland window.
-- The visible overlay is shown inactive on Linux, so normal hover should not steal keyboard focus from mpv.
-- During startup and fullscreen transitions, SubMiner waits for tracked mpv geometry before showing the visible overlay and skips the fullscreen restack hide/show path after mpv leaves fullscreen. That avoids a temporary full-screen overlay or black window while the subtitle tokenizer and Yomitan warmups finish.
-- If the subtitle sidebar is open during a windowed/fullscreen transition, SubMiner restores it on the replacement overlay window. Subtitle hit regions are also refreshed as soon as the first measured subtitle line is reported, so hover and Yomitan lookup should work on the first visible line.
+**Overlay stays above an unrelated app**: SubMiner can only see X11/Xwayland windows in this mode. Run that app under Xwayland too.
 
-Requirements: `xdotool`, `xprop`, and `xwininfo` must be installed. SubMiner uses root `_NET_ACTIVE_WINDOW` from `xprop` for focus detection and falls back to `xdotool getactivewindow` when that signal is unavailable.
+## macOS
 
-**Overlay sits behind mpv / pause-on-hover and Yomitan stop working**
-
-This almost always means mpv came up as a **native Wayland** window that the XWayland overlay cannot cover. It happens when mpv is launched **manually** (your own command), because SubMiner can only force XWayland on the mpv processes it launches itself. Fix it one of these ways:
-
-- Launch playback through SubMiner (the `subminer` launcher or the tray), which forces XWayland for you, or
-- Force XWayland in your own mpv invocation, e.g. `mpv --gpu-context=x11egl …`, or launch with `WAYLAND_DISPLAY= mpv …`, or set `gpu-context=x11egl` in your `mpv.conf`.
-
-To confirm mpv is on XWayland, `xdotool search --class mpv` should return a window id (a native Wayland mpv returns nothing).
-
-**Overlay stays above an unrelated foreground app**
-
-SubMiner can only detect focus for X11/Xwayland windows in this mode. If a native Wayland app covers mpv but the overlay stays visible, run that app under Xwayland too or use Hyprland/Sway native support. Generic X11 cannot observe native Wayland foreground windows.
-
-### macOS
-
-- **Accessibility permission**: Required for window tracking. Grant it in System Settings > Privacy & Security > Accessibility.
-- **Gatekeeper**: If macOS blocks SubMiner, right-click the app and select "Open" to bypass the warning, or remove the quarantine attribute: `xattr -d com.apple.quarantine /path/to/SubMiner.app`
-
-## See Also
-
-Feature-specific issues are covered in each feature's own page:
-
-- [Anki Integration](/anki-integration) - card creation, field mapping, and AnkiConnect setup
-- [AniList Integration](/anilist-integration) - watch-progress sync and authentication
-- [Character Dictionary](/character-dictionary) - AniList character name matching and inline portraits
-- [Jellyfin Integration](/jellyfin-integration) - remote playback and library connection
-- [Jimaku Integration](/jimaku-integration) - subtitle fetching and API rate limits
-- [YouTube Integration](/youtube-integration) - subtitle generation and playback
-- [Immersion Tracking](/immersion-tracking) - telemetry and session logging
-- [WebSocket / Texthooker API](/websocket-texthooker-api) - external texthooker clients
-- [Subtitle Annotations](/subtitle-annotations) - N+1, frequency, JLPT, and name-match layers
-- [Subtitle Sidebar](/subtitle-sidebar) - sidebar navigation and behavior
-- [Configuration Reference](/configuration) - full config options
-- [Shortcuts](/shortcuts) - keybinding reference
+- Accessibility permission is required for window tracking: System Settings > Privacy & Security > Accessibility.
+- If Gatekeeper blocks the app, right-click it and choose Open, or run `xattr -d com.apple.quarantine /path/to/SubMiner.app`.

docs-site/tsukihime-integration.md

@@ -0,0 +1,48 @@
+# TsukiHime integration
+
+[TsukiHime](https://tsukihime.org) extracts the subtitle tracks from anime torrent releases and hosts them for download. SubMiner searches it from the overlay, so you can grab Japanese or secondary-language subtitles for the current episode without a torrent client. Most releases carry only English subtitles, so [Jimaku](/jimaku-integration) is usually the better source for Japanese.
+
+## Setup
+
+TsukiHime needs no account or API key. SubMiner needs the `xz` binary on your `PATH` to unpack downloads. Most Linux distributions ship it (package `xz` or `xz-utils`).
+
+## Usage
+
+1. Press `Ctrl+Shift+T` during playback.
+2. SubMiner fills in the title and episode from the file name and searches right away when it finds both. Otherwise, fix the fields and press `Enter`.
+3. Pick a tab. The first tab shows your secondary language (`secondarySub.secondarySubLanguages`, or English if unset). The second tab shows Japanese. Each tab lists only releases that carry that language.
+4. Select a release, then a subtitle track.
+
+The track is saved next to the video with a language suffix, such as `<video>.ja.ass` or `<video>.en.ass` (a temp directory is used for streams). A Japanese track becomes mpv's primary subtitle. A track from the secondary tab loads as the secondary subtitle and leaves the primary alone.
+
+Pick the release that matches your video file, same group and same version, and the timing will line up. With any other release, fix the offset with subtitle sync (`Ctrl+Alt+S`).
+
+| Key              | Action                                 |
+| ---------------- | -------------------------------------- |
+| `Enter`          | Search, or select the highlighted item |
+| `Up` / `Down`    | Move through releases or tracks        |
+| `Left` / `Right` | Switch tabs                            |
+| `Escape`         | Close                                  |
+
+You can also open the modal with `subminer app --open-tsukihime`, bind a key to `["__tsukihime-open"]` in `keybindings`, or change the shortcut with `shortcuts.openTsukihime`.
+
+## Options
+
+| Key                          | What it does                                           |
+| ---------------------------- | ------------------------------------------------------ |
+| `tsukihime.maxSearchResults` | Maximum releases per search. The API caps this at 100. |
+| `tsukihime.apiBaseUrl`       | API address. Change only for a mirror.                 |
+
+See [Configuration](/configuration#tsukihime) for defaults.
+
+## Troubleshooting
+
+**"xz binary not found."** Install `xz` or `xz-utils` with your package manager.
+
+**"No releases with Japanese subtitles."** None of the results carry a Japanese track. Try another search, or use Jimaku.
+
+**"Batch releases are not supported."** TsukiHime only has extracted tracks for single-file torrents. Pick the single-episode release.
+
+**"No text subtitle tracks in this release."** The release has only image-based subtitles (PGS or VobSub) or none. Try another release.
+
+**Timing is off.** The subtitle came from a different release than your video. Use subtitle sync (`Ctrl+Alt+S`) or pick the matching release.

docs-site/usage.md

@@ -1,366 +1,156 @@
 # Usage
 
-## Quick Start
+This page covers everyday use: starting playback, working with the overlay, and the commands you will reach for most. For every `subminer` subcommand and flag, see [Launcher script](/launcher-script).
 
-Play a video with SubMiner:
+## Play a video
 
 ```bash
 subminer video.mkv
 ```
 
-On **Windows**, use the **SubMiner mpv** shortcut created during first-run setup - double-click it, or drag a video file onto it.
+On Windows, double-click the **SubMiner mpv** shortcut or drag a video onto it.
 
-That's the simplest way to get started. The `subminer` launcher handles mpv, the IPC socket, and the overlay automatically.
+SubMiner starts mpv, connects to it, and opens the overlay. Subtitle lines appear as hoverable words. Hover a word to look it up, then mine it into Anki. [Mining workflow](/mining-workflow) covers lookup and card creation in detail.
 
-> [!IMPORTANT]
-> SubMiner requires the bundled Yomitan instance to have at least one dictionary imported for lookups to work.
-> See [Yomitan setup](#yomitan-setup) for details.
-
-::: tip Anki card enrichment
-If you want sentence, audio, and screenshot fields on your Anki cards, add this to your config:
-
-```jsonc
-{
-  "ankiConnect": {
-    "enabled": true,
-    "deck": "Mining",
-    "fields": {
-      "sentence": "Sentence",
-      "audio": "SentenceAudio",
-      "image": "Picture",
-    },
-  },
-}
-```
-
-Field names must match your Anki note type exactly (case-sensitive). See [Anki Integration](/anki-integration) for the full reference.
-:::
-
-## How It Works
-
-When you launch SubMiner, it wires up mpv and the overlay for you:
-
-1. SubMiner starts the overlay app in the background
-2. mpv runs with an **IPC socket** at `/tmp/subminer-socket` - a small local channel two programs use to talk to each other, so the overlay can ask mpv what subtitle is on screen right now
-3. The overlay connects and subscribes to subtitle changes
-
-From there, subtitles render as interactive, hoverable word spans and you mine cards directly from the overlay. For the overlay anatomy and the full mining loop - word lookup, card creation, annotations - see [Mining Workflow](/mining-workflow).
-
-### Ways to Launch
-
-| Approach                            | Use when                                                                                                                               | How                                                                   |
-| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| **`subminer` launcher**             | You want SubMiner to handle everything - launch mpv, set up the socket, start the overlay. **Recommended for most users.**             | `subminer video.mkv`                                                  |
-| **SubMiner mpv shortcut** (Windows) | The recommended Windows entry point. Created during first-run setup, launches mpv with SubMiner's defaults.                            | Double-click, drag a file onto it, or run `SubMiner.exe --launch-mpv` |
-| **mpv plugin** (all platforms)      | Bundled and injected at runtime. Provides `y` chord keybindings for controlling the overlay from within mpv. No manual install needed. | Automatic when using the launcher or shortcut                         |
-
-The mpv plugin is always available - it's bundled with SubMiner and injected at runtime. If you launch mpv yourself (without the launcher), pass `--input-ipc-server=/tmp/subminer-socket` in your mpv config for the overlay to connect.
-
-## Live Config Reload
-
-While SubMiner is running, it watches your active config file and applies safe updates automatically.
-
-Live-updated settings:
-
-- `subtitleStyle`
-- `keybindings`
-- `shortcuts`
-- `secondarySub.defaultMode`
-- `ankiConnect.ai`
-
-Invalid config edits are rejected; SubMiner keeps the previous valid runtime config and shows an error notification.
-For restart-required sections, SubMiner shows a restart-needed notification.
-
-## Commands
-
-On Windows, replace `SubMiner.AppImage` with `SubMiner.exe` in the direct packaged-app examples below.
-
-```bash
-# Browse and play videos
-subminer                          # Current directory (uses fzf)
-subminer -R                       # Use rofi instead of fzf
-subminer -d ~/Videos              # Specific directory
-subminer -r -d ~/Anime            # Recursive search
-subminer video.mkv                # Play specific file (overlay auto-starts)
-subminer --start video.mkv        # Explicit overlay start (use when auto_start=no in config)
-subminer -S video.mkv             # Same as above via --start-overlay
-subminer https://youtu.be/...     # Play a YouTube URL
-subminer ytsearch:"jp news"       # Play first YouTube search result
-subminer --setup                  # Open first-run setup popup
-subminer --version                # Print installed SubMiner version
-subminer -v                       # Same as above
-subminer --log-level debug video.mkv # Enable verbose logs for launch/debugging
-subminer --log-level warn video.mkv  # Set logging level explicitly
-subminer --args '--fs=opengl-hq --ytdl-format=bestvideo*+bestaudio/best' video.mkv  # Pass extra mpv args
-
-# Options
-subminer -T video.mkv             # Disable texthooker server
-subminer -b x11 video.mkv         # Force X11 backend
-subminer video.mkv                # No mpv profile passed by default
-subminer -p gpu-hq video.mkv      # Use a specific mpv profile
-subminer jellyfin                 # Open Jellyfin setup window (subcommand form)
-subminer jellyfin -l --server http://127.0.0.1:8096 --username me --password 'secret'
-subminer jellyfin --logout        # Clear stored Jellyfin token/session data
-subminer jellyfin -p              # Interactive Jellyfin library/item picker + playback
-subminer jellyfin -d              # Jellyfin cast-discovery mode (background tray app)
-subminer app --stop               # Stop background app (including Jellyfin cast broadcast)
-subminer doctor                   # Dependency + config + socket diagnostics
-subminer logs -e                  # Export a sanitized log ZIP and print its path
-subminer config path              # Print active config path
-subminer config show              # Print active config contents
-subminer mpv socket               # Print active mpv socket path
-subminer mpv status               # Exit 0 if socket is ready, else exit 1
-subminer mpv idle                 # Launch detached idle mpv with SubMiner defaults
-subminer dictionary /path/to/file-or-directory  # Generate character dictionary ZIP from target (manual Yomitan import)
-subminer dictionary --candidates /path/to/file.mkv
-subminer dictionary --select 21355 /path/to/file.mkv
-subminer texthooker               # Launch texthooker-only mode
-subminer texthooker -o            # Launch texthooker and open it in your browser
-subminer app --anilist-setup      # Pass args directly to SubMiner binary (example: AniList login flow)
-
-# Direct packaged app control
-SubMiner.AppImage --background             # Start in background (tray + IPC wait, minimal logs)
-SubMiner.AppImage --start --texthooker   # Start overlay with texthooker
-SubMiner.AppImage --texthooker           # Launch texthooker only (no overlay window)
-SubMiner.AppImage --texthooker --open-browser  # Launch texthooker and open browser
-SubMiner.AppImage --setup                  # Open first-run setup popup
-SubMiner.AppImage --stop                  # Stop overlay
-SubMiner.AppImage --start --toggle        # Start MPV IPC + toggle visibility
-SubMiner.AppImage --show-visible-overlay              # Force show visible overlay
-SubMiner.AppImage --hide-visible-overlay              # Force hide visible overlay
-SubMiner.AppImage --toggle-primary-subtitle-bar       # Toggle primary subtitle bar visibility
-SubMiner.AppImage --start --dev                         # Enable app/dev mode only
-SubMiner.AppImage --start --debug                       # Alias for --dev
-SubMiner.AppImage --start --log-level debug             # Force verbose logging without app/dev mode
-SubMiner.AppImage --playback-feedback "your feedback"   # Route playback feedback through the configured feedback surface
-SubMiner.AppImage --yomitan               # Open Yomitan settings
-SubMiner.AppImage --settings              # Open SubMiner settings window
-SubMiner.AppImage --jellyfin              # Open Jellyfin setup window
-SubMiner.AppImage --jellyfin-login --jellyfin-server http://127.0.0.1:8096 --jellyfin-username me --jellyfin-password 'secret'
-SubMiner.AppImage --jellyfin-logout       # Clear stored Jellyfin token/session data
-SubMiner.AppImage --jellyfin-libraries
-SubMiner.AppImage --jellyfin-items --jellyfin-library-id LIBRARY_ID --jellyfin-search anime --jellyfin-limit 20
-SubMiner.AppImage --jellyfin-play --jellyfin-item-id ITEM_ID --jellyfin-audio-stream-index 1 --jellyfin-subtitle-stream-index 2  # Requires connected mpv IPC (--start)
-SubMiner.AppImage --jellyfin-remote-announce  # Force cast-target capability announce + visibility check
-SubMiner.AppImage --dictionary             # Generate character dictionary ZIP for current anime
-SubMiner.AppImage --dictionary-candidates  # List AniList candidates for current character dictionary series
-SubMiner.AppImage --dictionary-select --dictionary-anilist-id 21355  # Pin correct AniList media for series
-SubMiner.AppImage --help                  # Show all options
-```
-
-The tray menu includes `Export Logs`, which creates the same sanitized log ZIP as `subminer logs -e` and shows the archive path when complete.
-
-Once Jellyfin is configured, the tray menu includes `Jellyfin Discovery` for starting or stopping cast discovery in the current app session without changing config.
-
-### Logging and App Mode
-
-- `--log-level` controls logger verbosity.
-- `--dev` and `--debug` are app/dev-mode switches; they are not log-level aliases.
-- `--background` defaults to quieter logging (`warn`) unless `--log-level` is set.
-- `--background` launched from a terminal detaches and returns the prompt; stop it with tray Quit or `SubMiner.AppImage --stop` (`SubMiner.exe --stop` on Windows).
-- Linux desktop launcher starts SubMiner with `--background` by default (via electron-builder `linux.executableArgs`).
-- On Hyprland and other Wayland compositors, the tray icon appears only when your panel provides a StatusNotifier/AppIndicator tray host.
-- On Linux, the app now defaults `safeStorage` to `gnome-libsecret` for encrypted token persistence.
-  Launcher pass-through commands also support `--password-store=<backend>` and forward it to the app when present.
-  Override with e.g. `--password-store=basic_text`.
-- Use both when needed, for example `SubMiner.AppImage --start --dev --log-level debug` (or `SubMiner.exe --start --dev --log-level debug` on Windows).
-- `--playback-feedback <text>` (also `--playback-feedback=<text>`) sends a non-empty text string through the playback-feedback route used for recording/playback prompts. For example: `SubMiner.AppImage --playback-feedback "your feedback"`.
-
-### Windows mpv Shortcut
-
-First-run setup creates the config file, then requires Yomitan dictionaries before it can finish.
-
-If you enabled the optional Windows shortcut during install, SubMiner creates a `SubMiner mpv` shortcut in the Start menu and/or on the desktop. On Windows, that shortcut is the recommended way to launch local files with SubMiner because it starts `mpv.exe` with the right defaults directly.
-After setup completes, the shortcut is the normal Windows playback entry point.
-
-You can use it three ways:
-
-- Double-click `SubMiner mpv` to open `mpv` with SubMiner's default socket/subtitle args.
-- Drag a video file onto `SubMiner mpv` to launch that file with the same defaults.
-- Run it directly from Command Prompt or PowerShell with `--launch-mpv`.
-
-```powershell
-& "C:\Program Files\SubMiner\SubMiner.exe" --launch-mpv
-& "C:\Program Files\SubMiner\SubMiner.exe" --launch-mpv "C:\Videos\episode 01.mkv"
-```
-
-This flow requires `mpv.exe` to be discoverable. Leave `mpv.executablePath` blank to auto-discover from `PATH`, or set it to the full `mpv.exe` path if mpv is installed elsewhere. `SUBMINER_MPV_PATH` is still honored as a fallback.
-
-### Launcher Subcommands
-
-- `subminer jellyfin` / `subminer jf`: Jellyfin-focused workflow aliases.
-- `subminer doctor`: health checks for core dependencies and runtime paths.
-- `subminer settings`: open the SubMiner settings window (also `subminer --settings`).
-- `subminer logs -e`: export a sanitized ZIP of today's logs, or the most recent logs when no current-day log exists.
-- `subminer config`: config file helpers (`path`, `show`).
-- `subminer mpv`: mpv helpers (`status`, `socket`, `idle`).
-- `subminer dictionary <path>`: generates a Yomitan-importable character dictionary ZIP from a file/directory target.
-- Use `subminer dictionary --candidates <path>` and `subminer dictionary --select <id> <path>` to correct AniList character-dictionary matches for a whole series.
-- `subminer texthooker`: texthooker-only shortcut (same behavior as `--texthooker`). A _texthooker_ is a web page that displays the current subtitle line as selectable text, so browser-based dictionary extensions and other tools can read along with playback.
-- `subminer app` / `subminer bin`: direct passthrough to the SubMiner binary/AppImage.
-- Subcommand help pages are available (for example `subminer jellyfin -h`).
-
-### First-Run Setup
-
-Setup popup appears on first launch, or when setup has not been completed.
-
-You can also open it manually:
-
-```bash
-subminer --setup
-SubMiner.AppImage --setup
-```
-
-Setup flow:
-
-- config file: create the default config directory and prefer `config.jsonc`
-- legacy plugin cleanup: remove detected older global SubMiner mpv plugin files if present (the bundled plugin is injected at runtime automatically)
-- Yomitan shortcut: open bundled Yomitan settings directly from the setup window
-- dictionary check: ensure at least one bundled Yomitan dictionary is available, unless an external Yomitan profile is configured
-- Windows: optionally create or remove `SubMiner mpv` Start Menu/Desktop shortcuts (`SubMiner.exe --launch-mpv`)
-- Windows: optionally set `mpv.executablePath` if `mpv.exe` is not on `PATH`
-- refresh: re-check dictionary state without restarting
-- `Finish setup` stays disabled until the config and dictionary gates are satisfied
-- finish action writes setup completion state and suppresses future auto-open prompts
-
-AniList character dictionary auto-sync (optional):
-
-- Enable with `subtitleStyle.nameMatchEnabled=true` in config or **Name Match Enabled** in Settings.
-- SubMiner syncs the currently watched AniList media into a per-media snapshot, then rebuilds one merged `SubMiner Character Dictionary` from the most recently used snapshots.
-- Rotation limit defaults to 3 recent media snapshots in that merged dictionary (`maxLoaded`).
-
-Use subcommands for Jellyfin workflows (`subminer jellyfin ...`).
-Top-level launcher flags like `--jellyfin-*` are intentionally rejected.
-
-### MPV Profile Example (mpv.conf)
-
-`subminer` passes the following MPV options directly on launch by default:
-
-- `--input-ipc-server=/tmp/subminer-socket` (or your configured socket path)
-- `--alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us`
-- `--slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us`
-- `--sub-auto=fuzzy`
-- `--sub-file-paths=.;subs;subtitles`
-- `--sid=auto`
-- `--secondary-sid=auto`
-- `--secondary-sub-visibility=no`
-
-You can append additional MPV arguments with launcher `-a/--args`, for example `--args "--ao=alsa --volume=80"`.
-
-You can define a matching profile in `~/.config/mpv/mpv.conf` for consistency when launching `mpv` manually or from other tools. The Windows `SubMiner.exe --launch-mpv` shortcut path uses equivalent args directly, but skips the extra current-directory subtitle scan to avoid duplicate sidecar detection when you drag a video onto the shortcut; the optional profile remains useful for manual mpv launches. The `subminer` wrapper passes no mpv profile by default; set one with `subminer -p <profile> ...` or with `mpv.profile` in your config (for example `"profile": "subminer"` to use the `[subminer]` profile below):
-
-```ini
-[subminer]
-# IPC socket (must match SubMiner config)
-input-ipc-server=/tmp/subminer-socket
-
-# Prefer JP/EN audio + subtitle language variants
-alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us
-slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us
-
-# Auto-load external subtitles
-sub-auto=fuzzy
-sub-file-paths=.;subs;subtitles
-
-# Select primary + secondary subtitle tracks automatically
-sid=auto
-secondary-sid=auto
-secondary-sub-visibility=no
-```
+Run `subminer` with no file to pick one from the current directory instead. See [Picking files](#picking-files).
 
 ### Yomitan setup
 
-SubMiner includes a bundled Yomitan extension for overlay word lookup. This bundled extension is separate from any Yomitan browser extension you may have installed.
+Lookups need at least one dictionary in SubMiner's bundled Yomitan. First-run setup asks you to import one. To add more later, open Yomitan settings with `Alt+Shift+Y` or `subminer app --yomitan`.
 
-For SubMiner overlay lookups to work, open Yomitan settings (`subminer app --yomitan` or `SubMiner.AppImage --yomitan`) and import at least one dictionary in the bundled Yomitan instance.
+The bundled Yomitan is separate from any Yomitan in your browser. It has its own dictionaries and settings.
 
-If you also use Yomitan in a browser, configure that browser profile separately; it does not inherit dictionaries or settings from the bundled instance.
+## Picking files
 
-### YouTube Playback
+```bash
+subminer                    # fzf picker for the current directory
+subminer -d ~/Anime -r      # pick from a directory, searching subfolders
+subminer -R                 # rofi picker instead of fzf (Linux)
+subminer -H                 # watch history: replay, next, or previous episode
+```
 
-`subminer` accepts direct URLs (for example, YouTube links) and `ytsearch:` targets.
-For YouTube playback, SubMiner resolves subtitle selection during startup while mpv is paused: it auto-selects the default primary subtitle track plus a best-effort secondary track, then resumes when primary subtitles are ready.
+See [Launcher script](/launcher-script#video-picker) for picker and history details.
 
-Notes:
+## Overlay basics
 
-- Install `yt-dlp` so mpv can resolve YouTube streams and subtitle tracks reliably.
-- For YouTube URLs, startup no longer requires opening the picker first; SubMiner loads subtitles and keeps the overlay available for retries.
-- Press `Ctrl+Alt+C` during active YouTube playback to open the manual YouTube subtitle picker and retry track selection.
-- For YouTube URLs, `subminer` probes available YouTube subtitle tracks, reuses existing authoritative tracks when available, and downloads only missing sides.
-- Native mpv secondary subtitle rendering stays hidden so the overlay remains the visible secondary subtitle surface.
-- Primary subtitle target languages come from `youtube.primarySubLanguages` (defaults to `["ja","jpn"]`).
-- Secondary target languages come from `secondarySub.secondarySubLanguages` (empty by default; when empty, no language-based secondary track is auto-selected, though mpv's `--slang` list above still prefers English variants). When multiple matching secondary tracks exist, SubMiner prefers a non-Signs/Songs track.
-- Configure defaults in `$XDG_CONFIG_HOME/SubMiner/config.jsonc` (or `~/.config/SubMiner/config.jsonc`) under `youtube` and `secondarySub`.
+| Key           | Action                                                                |
+| ------------- | --------------------------------------------------------------------- |
+| `Alt+Shift+O` | Show or hide the overlay (works while the overlay or mpv has focus)   |
+| `Alt+Shift+Y` | Open Yomitan settings (works from any window, not configurable)       |
+| `V`           | Cycle the subtitle bar through hidden, visible, and hover-only        |
+| `Ctrl+Alt+P`  | Open the playlist browser to queue, reorder, or jump between episodes |
+| `Ctrl/Cmd+/`  | Show every overlay and mpv keybinding for this session                |
 
-For local video files, SubMiner uses the same config-driven language priorities to auto-select the primary and secondary subtitle tracks from internal and external subtitle sources.
+Hovering subtitle text pauses mpv, and moving away resumes it. An open Yomitan popup also keeps playback paused. Turn these off with `subtitleStyle.autoPauseVideoOnHover` and `subtitleStyle.autoPauseVideoOnYomitanPopup`.
 
-## Controller Support
+You can drop files onto the overlay:
 
-SubMiner supports gamepad/controller input for couch-friendly usage via the Chrome Gamepad API. Controller input drives the overlay while keyboard-only mode is enabled.
+- A video replaces what is playing. Hold `Shift` to add it to the playlist instead.
+- A subtitle file loads as a new subtitle track.
 
-### Getting Started
+The full list is in [Keyboard shortcuts](/shortcuts). The in-player `y` key chords are in [mpv plugin](/mpv-plugin).
 
-1. Connect a controller before or after launching SubMiner.
-2. Set `controller.enabled` to `true` in your config.
-3. Press `Alt+C` in the overlay by default to pick the controller you want to save and remap any action inline.
-4. Enable keyboard-only mode - press `Y` on the controller (default binding) or use the overlay keybinding.
-5. Click the binding badge, edit pencil, or `Learn` on the overlay action you want, then press the matching button, trigger, or stick direction on the controller.
-6. Use the left stick to navigate subtitle tokens and scroll the popup; use the right stick vertically for popup page jumps.
-7. Press `A` to look up the selected word, `X` to mine a card, `B` to close the popup.
+## YouTube playback
 
-By default SubMiner uses the first connected controller after controller support is enabled. `Alt+C` opens the controller config modal, where you can save the preferred controller and remap bindings inline per controller. The reset button beside each edit pencil restores that binding to its built-in default for the selected controller. `Alt+Shift+C` opens the live debug modal with raw axes/button values for non-standard pads. Both modals stay closed while `controller.enabled` is false, and both shortcuts can be changed through `shortcuts.openControllerSelect` and `shortcuts.openControllerDebug`.
+Pass a URL or a search. Install `yt-dlp` first.
 
-### Default Button Mapping
+```bash
+subminer https://youtu.be/...
+subminer ytsearch:"jp news"     # play the first search result
+```
+
+SubMiner picks subtitles during startup while mpv is paused. It selects a Japanese primary track and an English secondary track, downloads whatever is missing, and resumes once the primary subtitles are ready. If the choice is wrong, press `Ctrl+Alt+C` to open the YouTube subtitle picker and choose again.
+
+Language preferences live under `youtube` and `secondarySub` in the config. See [YouTube integration](/youtube-integration).
+
+## Common commands
+
+```bash
+subminer stats                     # start the immersion stats dashboard
+subminer settings                  # open the settings window
+subminer yt                        # browse YouTube; picked videos play in mpv
+subminer doctor                    # check dependencies, config, and the mpv socket
+subminer generate-subs video.mkv   # make Japanese subtitles from the audio
+subminer logs -e                   # export a log ZIP for bug reports
+subminer app --setup               # reopen first-run setup
+subminer -u                        # update SubMiner
+```
+
+Two flags help early on:
+
+- `-a/--args` passes options to mpv, for example `subminer --args "--volume=80" video.mkv`.
+- `--log-level debug` turns on verbose logs when something is wrong.
+
+[Launcher script](/launcher-script) lists every command. Jellyfin, sync, and character dictionary commands are covered in [Jellyfin](/jellyfin-integration), [Sync between machines](/launcher-script#sync-between-machines), and [Character dictionary](/character-dictionary).
+
+### Generate Japanese subtitles locally
+
+`subminer generate-subs` transcribes audio with whisper.cpp and writes a Japanese SRT file. If that file is playing in mpv, it loads the new subtitles right away. Leave out the path to use the file mpv is playing.
+
+```bash
+subminer generate-subs video.mkv --download-model   # download a model on first use
+subminer generate-subs video.mkv --model-path ~/models/ggml-medium.bin
+```
+
+You need `whisper-cli`, `ffmpeg`, and `ffprobe`. Check the output before mining, since speech recognition makes mistakes over music and overlapping voices. See [Subtitle generation](/subtitle-generation) for models, timing references, and settings.
+
+## Windows mpv shortcut
+
+First-run setup can create a **SubMiner mpv** shortcut in the Start menu and on the desktop. It is the easiest way to play local files on Windows:
+
+- Double-click it to open mpv with SubMiner attached.
+- Drag a video onto it to play that file.
+- Run it from a terminal:
+
+```powershell
+& "C:\Program Files\SubMiner\SubMiner.exe" --launch-mpv "C:\Videos\episode 01.mkv"
+```
+
+mpv must be on `PATH`, or `mpv.executablePath` must point to `mpv.exe`. The `subminer` terminal command also works on Windows if you installed it during setup.
+
+## Tray menu
+
+The tray icon gives you:
+
+- **Export Logs**: saves a log ZIP and shows its path. Usernames, IP addresses, emails, tokens, passwords, and cookies are masked in the exported copy. Your log files on disk stay unchanged.
+- **View Changelog**: release notes, including versions newer than yours. Use `J`/`K` to move between versions, `Enter` to expand one, and `Esc` to close.
+- **Sync Stats & History**: opens the [sync window](/launcher-script#sync-between-machines).
+- **Jellyfin Discovery**: turns cast discovery on or off for this session, once [Jellyfin](/jellyfin-integration) is set up.
+
+On Wayland, the tray icon only appears if your panel provides a StatusNotifier (AppIndicator) tray.
+
+## Controller support {#controller-support}
+
+You can drive the overlay with a gamepad.
+
+1. Set `controller.enabled` to `true` in your config.
+2. Connect a controller. SubMiner uses the first one it sees.
+3. Press `Y` on the controller to turn on keyboard-only mode. The controller only works in this mode.
+4. Move between words with the left stick, press `A` to look one up, and `X` to mine it.
+
+Press `Alt+C` to choose a controller and remap buttons. Click an action's **Learn** button, then press the button you want. `Alt+Shift+C` shows raw input values for unusual pads.
 
 | Button                | Action                               |
-| ----------------------- | --------------------------------------- |
-| `A` (South)             | Toggle lookup                           |
-| `B` (East)              | Close lookup                            |
+| --------------------- | ------------------------------------ |
+| `A` (South)           | Look up the selected word            |
+| `B` (East)            | Close the lookup                     |
+| `X` (West)            | Mine a card                          |
 | `Y` (North)           | Toggle keyboard-only mode            |
-| `X` (West)              | Mine card                               |
-| `L1`                    | Play current Yomitan audio              |
-| `R1`                    | Next Yomitan audio track                |
-| `L3` (left stick press) | Toggle mpv pause                        |
+| `L1`                  | Play the current Yomitan audio       |
+| `R1`                  | Next Yomitan audio source            |
+| `L3`                  | Pause or resume mpv                  |
 | `Select` / `Minus`    | Quit mpv                             |
-| `L2` / `R2`             | Unbound (available for custom bindings) |
+| Left stick            | Move between words, scroll the popup |
+| Right stick (up/down) | Jump through the popup               |
 
-### Analog Controls
+On controllers that report the W3C standard layout, the default quit button lands on `L2` instead of `Select`. Remap it with `Alt+C`. All options are in [Configuration](/configuration#controller-support).
 
-| Input                 | Action                                        |
-| --------------------- | --------------------------------------------- |
-| Left stick horizontal | Move token selection left/right               |
-| Left stick vertical   | Scroll Yomitan popup                          |
-| Right stick vertical  | Jump through Yomitan popup                    |
-| D-pad                 | Fallback for stick navigation when configured |
+## Development profiles
 
-Learn mode ignores already-held inputs and waits for the next fresh button press or axis direction, which avoids accidental captures when you open the modal mid-input.
+`--dev` and `--debug` use a separate `SubMiner-dev` profile. They do not read or modify dictionaries and configuration from the installed app unless `SUBMINER_USE_PRODUCTION_PROFILE=1` is explicitly set. See [Development](/development#run-locally).
 
-All button and axis mappings are configurable under the `controller` config block. Learned remaps are saved under `controller.profiles` for the selected controller id. See [Configuration - Controller Support](/configuration#controller-support) for the full options.
+## Changing settings while you watch
 
-## Keybindings
+SubMiner watches your config file and applies most changes without a restart, including subtitle style, keybindings, and most Anki settings. If a change needs a restart, SubMiner tells you. If the file has an error, it keeps the last working config and shows a notification. See [Configuration](/configuration).
 
-See [Keyboard Shortcuts](/shortcuts) for the full reference, including mining shortcuts, overlay controls, and customization.
-
-**Global shortcuts** (work system-wide):
-
-| Keybind       | Action                 |
-| ------------- | ---------------------- |
-| `Alt+Shift+O` | Toggle visible overlay |
-| `Alt+Shift+Y` | Open Yomitan settings  |
-
-`Alt+Shift+Y` is fixed and not configurable. All other shortcuts can be changed under `shortcuts` in your config.
-
-Useful overlay-local default keybinding: `Ctrl+Alt+P` opens the playlist browser for the current video's parent directory and the live mpv queue so you can append, reorder, remove, or jump between episodes without leaving playback.
-
-Press `V` to hide or restore the primary SubMiner subtitle bar. The bundled mpv plugin also binds bare `v` to the same action (injected at runtime).
-
-`Ctrl/Cmd+/` opens the session help modal with the current overlay and mpv keybindings. The same help view is also available through the `y-h` chord in mpv.
-
-Hovering over subtitle text pauses mpv by default; leaving resumes it. Yomitan popups also pause playback by default. Set `subtitleStyle.autoPauseVideoOnHover: false` or `subtitleStyle.autoPauseVideoOnYomitanPopup: false` to disable either behavior.
-
-### Drag-and-Drop
-
-- Drop video files onto the overlay to replace current playback.
-- Hold `Shift` while dropping to append to the playlist instead.
-
-Next: [Mining Workflow](/mining-workflow) - word lookup, card creation, and the full mining loop.
+Next: [Mining workflow](/mining-workflow).

docs-site/websocket-texthooker-api.md

@@ -1,72 +1,49 @@
-# WebSocket / Texthooker API & Integration
+# WebSocket and texthooker API
 
-**Who this page is for:** developers and tinkerers who want to consume SubMiner's live subtitle stream from their own tools - a browser tab, an automation script, or another mpv plugin. If you just want subtitles in a browser tab for Yomitan, skip to [Texthooker Integration Guide](#texthooker-integration-guide); the rest is reference for building custom clients.
-
-A *texthooker* is a page/tool that receives the text currently on screen so a dictionary extension (like Yomitan) can look words up. SubMiner ships its own texthooker UI and also broadcasts subtitle text over local WebSockets that any client can connect to.
-
-SubMiner exposes a small set of local integration surfaces for browser tools, automation helpers, and mpv-driven workflows:
-
-- **Subtitle WebSocket** at `ws://127.0.0.1:6677` by default for plain subtitle pushes.
-- **Annotation WebSocket** at `ws://127.0.0.1:6678` by default for token-aware clients.
-- **Texthooker HTTP UI** at `http://127.0.0.1:5174` by default for browser-based subtitle consumption.
-- **mpv plugin script messages** for in-player automation and extension.
-
-This page documents those integration points and shows how to build custom consumers around them.
-
-## Quick Reference
+SubMiner streams the current subtitle over local WebSockets and serves a texthooker page, so browser tools and your own scripts can follow along. This page is the reference for building a client. If you only want subtitles in a browser tab for Yomitan, see [Texthooker page](#texthooker-integration-guide).
 
 | Surface               | Default                     | Purpose                                               |
-| --- | --- | --- |
-| `websocket` | `ws://127.0.0.1:6677` | Basic subtitle broadcast stream |
-| `annotationWebsocket` | `ws://127.0.0.1:6678` | Structured stream with token metadata |
-| `texthooker` | `http://127.0.0.1:5174` | Local texthooker UI with injected websocket config |
-| mpv plugin | `script-message subminer-*` | Start/stop/toggle/status automation inside mpv |
+| --------------------- | --------------------------- | ----------------------------------------------------- |
+| `websocket`           | `ws://127.0.0.1:6677`       | Plain subtitle text                                   |
+| `annotationWebsocket` | `ws://127.0.0.1:6678`       | Subtitle text plus token metadata and rendered HTML   |
+| `texthooker`          | `http://127.0.0.1:5174`     | Bundled texthooker page, preconfigured for your setup |
+| mpv plugin            | `script-message subminer-*` | Start, stop, toggle, and status automation inside mpv |
 
-## Enable and Configure the Services
+All servers bind to `127.0.0.1` only. There is no authentication.
 
-SubMiner's integration ports are configured in `config.jsonc`. All three services are **off by default** - the block below shows the values to set to turn them on.
+## Enable the services
+
+All three services are off by default. Turn on the ones you need in `config.jsonc`:
 
 ```jsonc
 {
   "websocket": {
     "enabled": "auto",
-    "port": 6677
+    "port": 6677,
   },
   "annotationWebsocket": {
     "enabled": true,
-    "port": 6678
+    "port": 6678,
   },
   "texthooker": {
     "launchAtStartup": true,
-    "openBrowser": false
-  }
+    "openBrowser": false,
+  },
 }
 ```
 
-### How startup behaves
+- `websocket.enabled`: `true` always starts the plain stream. `"auto"` starts it unless the external `mpv_websocket` plugin is installed at `~/.config/mpv/mpv_websocket`.
+- `annotationWebsocket.enabled`: starts the annotated stream. It is independent of `websocket`.
+- `texthooker.launchAtStartup`: starts the texthooker page with the app.
+- `texthooker.openBrowser`: opens the page in your browser when it starts.
 
-- `websocket.enabled` defaults to `false`. Set it to `"auto"` to start the basic subtitle websocket unless SubMiner detects the external `mpv_websocket` plugin, or `true` to always start it.
-- `annotationWebsocket.enabled` defaults to `false` and is independent from `websocket`. Set it to `true` to start the annotated stream.
-- `texthooker.launchAtStartup` defaults to `false`. Set it to `true` to start the local HTTP UI automatically.
-- `texthooker.openBrowser` controls whether SubMiner opens the texthooker page in your browser when it starts.
+See [Configuration](/configuration) for all related options.
 
-If you use the [mpv plugin](/mpv-plugin), it can also start a texthooker-only helper process. The launcher derives the plugin's texthooker setting from your SubMiner config (`texthooker.launchAtStartup`) and injects it at runtime - there is no plugin config file to edit.
+## Subtitle WebSocket
 
-## Developer API Documentation
+`ws://127.0.0.1:6677`. Use it when you only need the current line as text.
 
-### 1. Subtitle WebSocket
-
-Use the basic subtitle websocket when you only need the current subtitle line as plain text.
-
-- **Default URL:** `ws://127.0.0.1:6677`
-- **Transport:** local WebSocket server bound to `127.0.0.1`
-- **Direction:** server push only
-- **Client auth:** none
-- **Reconnects:** client-managed
-
-When a client connects, SubMiner immediately sends the latest subtitle payload if one is available. After that, it pushes a new message each time the current subtitle changes.
-
-#### Message shape
+The server pushes only; it ignores client messages. On connect it sends the latest subtitle if there is one, then a new message each time the subtitle changes. Reconnecting is up to the client.
 
 ```json
 {
@@ -77,26 +54,18 @@ When a client connects, SubMiner immediately sends the latest subtitle payload i
 }
 ```
 
-#### Field reference
-
 | Field      | Type   | Notes                                                              |
-| --- | --- | --- |
-| `version` | number | Current websocket payload version. Today this is `1`. |
-| `text` | string | Raw subtitle text. |
-| `sentence` | string | Plain subtitle text with line breaks represented as `<br>`. No annotation spans or attributes. |
-| `tokens` | array | Always empty on the basic subtitle websocket. |
+| ---------- | ------ | ------------------------------------------------------------------ |
+| `version`  | number | Payload version, currently `1`                                     |
+| `text`     | string | Raw subtitle text                                                  |
+| `sentence` | string | HTML-escaped text with line breaks as `<br>`, no annotation markup |
+| `tokens`   | array  | Always empty on this stream                                        |
 
-### 2. Annotation WebSocket
+## Annotation WebSocket
 
-Use the annotation websocket for custom clients that want the same structured token payload the bundled texthooker UI consumes.
+`ws://127.0.0.1:6678`. The same token data the bundled texthooker uses. Prefer this stream for new clients. It keeps running when the plain stream is auto-disabled by `mpv_websocket`.
 
-- **Default URL:** `ws://127.0.0.1:6678`
-- **Payload shape:** JSON payload with `text`, rendered `sentence` HTML, and token metadata
-- **Primary difference:** this stream is intended to stay on even when the basic websocket auto-disables because `mpv_websocket` is installed
-
-In practice, if you are building a new client, prefer `annotationWebsocket` unless you specifically need compatibility with an existing `websocket` consumer.
-
-#### Message shape
+When a line is not yet tokenized, the stream first sends it with an empty `tokens` array, then sends the annotated version when tokenization finishes. Treat each message as the complete current state and replace the previous one. The plain stream does not repeat the line for this upgrade.
 
 ```json
 {
@@ -125,79 +94,48 @@ In practice, if you are building a new client, prefer `annotationWebsocket` unle
 }
 ```
 
-Each annotation token may include:
-
 | Token field           | Type             | Notes                                                                          |
-| --- | --- | --- |
-| `surface` | string | Display text for the token |
+| --------------------- | ---------------- | ------------------------------------------------------------------------------ |
+| `surface`             | string           | Display text                                                                   |
 | `reading`             | string           | Kana reading when available                                                    |
 | `headword`            | string           | Dictionary headword when available                                             |
-| `startPos` / `endPos` | number | Character offsets in the subtitle text |
-| `partOfSpeech` | string | SubMiner token POS label |
-| `isMerged` | boolean | Whether this token represents merged content |
-| `isKnown` | boolean | Marked known by SubMiner's known-word logic |
-| `isNPlusOneTarget` | boolean | True when the token is the sentence's N+1 target |
-| `isNameMatch` | boolean | True for prioritized character-name matches |
-| `frequencyRank` | number | Frequency rank when available |
-| `jlptLevel` | string | JLPT level when available |
-| `className` | string | CSS-ready class list derived from token state |
-| `frequencyRankLabel` | string or `null` | Preformatted rank label for UIs |
-| `jlptLevelLabel` | string or `null` | Preformatted JLPT label for UIs |
+| `startPos` / `endPos` | number           | Character offsets in `text`                                                    |
+| `partOfSpeech`        | string           | SubMiner part-of-speech label                                                  |
+| `isMerged`            | boolean          | Token was merged from several parser tokens                                    |
+| `isKnown`             | boolean          | Word is known                                                                  |
+| `isNPlusOneTarget`    | boolean          | Token is the line's N+1 target                                                 |
+| `isNameMatch`         | boolean          | Token matched a character name                                                 |
+| `frequencyRank`       | number           | Frequency rank; omitted when unavailable or a name match                       |
+| `jlptLevel`           | string           | JLPT level; omitted when unavailable or a name match                           |
+| `className`           | string           | CSS class list for the token                                                   |
+| `frequencyRankLabel`  | string or `null` | Rank label, set only when the rank is within your frequency highlight settings |
+| `jlptLevelLabel`      | string or `null` | JLPT label for display                                                         |
 
-### 3. HTML markup conventions
+### HTML markup
 
-The `sentence` field is pre-rendered HTML generated by SubMiner. Depending on token state, it can include classes such as:
+`sentence` is HTML rendered by SubMiner. Each token is a `<span>` with these classes as they apply:
 
-- `word`
-- `word-known`
-- `word-n-plus-one`
-- `word-name-match`
+- `word` on every token
+- one of `word-name-match`, `word-n-plus-one`, or `word-known`
 - `word-jlpt-n1` through `word-jlpt-n5`
-- `word-frequency-single`
-- `word-frequency-band-1` through `word-frequency-band-5`
+- `word-frequency-single`, or `word-frequency-band-1` through `word-frequency-band-5`, on words that are not known, N+1, or names
 
-SubMiner also adds tooltip-friendly data attributes when available:
+Spans also carry `data-reading`, `data-headword`, `data-frequency-rank`, and `data-jlpt-level` when available. For a fully custom UI, ignore `sentence` and render from `tokens`.
 
-- `data-reading`
-- `data-headword`
-- `data-frequency-rank`
-- `data-jlpt-level`
+## Texthooker page {#texthooker-integration-guide}
 
-If you need a fully custom UI, ignore `sentence` and render from `tokens` instead.
-
-## Texthooker Integration Guide
-
-### When to use the bundled texthooker page
-
-Use texthooker when you want a browser tab that:
-
-- updates live from current subtitles
-- works well with browser-based Yomitan setups
-- inherits SubMiner's coloring preferences and websocket URL automatically
-
-Start it with either:
+The bundled texthooker is a browser tab that updates live with the current subtitle, works with browser Yomitan, and uses SubMiner's colors. Start it with the app (`texthooker.launchAtStartup`) or from the launcher:
 
 ```bash
-subminer texthooker
-# or open the page immediately
-subminer texthooker -o
+subminer texthooker      # start the texthooker
+subminer texthooker -o   # start it and open the browser
 ```
 
-or by leaving `texthooker.launchAtStartup` enabled.
+SubMiner injects the page's settings into `window.localStorage` when it serves it: the WebSocket URL (`bannou-texthooker-websocketUrl`), the known, N+1, name, frequency, and JLPT coloring toggles, and CSS custom properties for the token colors. The page connects to the annotation stream if it is enabled, otherwise to the plain stream. With neither running, it has nothing to connect to.
 
-### What SubMiner injects into the page
+## Build a client
 
-When SubMiner serves the local texthooker UI, it injects bootstrap values into `window.localStorage`, including:
-
-- `bannou-texthooker-websocketUrl`
-- coloring toggles for known/N+1/name/frequency/JLPT styling
-- CSS custom properties for SubMiner's token colors
-
-That means the bundled page already knows which websocket to connect to and which color palette to use.
-
-### Build a custom websocket client
-
-Here is a minimal browser client for the annotation stream:
+A minimal browser client for the annotation stream:
 
 ```html
 <!doctype html>
@@ -219,7 +157,7 @@ Here is a minimal browser client for the annotation stream:
 </script>
 ```
 
-### Build a custom Node client
+A Node client:
 
 ```js
 import WebSocket from 'ws';
@@ -236,107 +174,15 @@ ws.on('message', (raw) => {
 });
 ```
 
-### Integration tips
+Tips:
 
-- Bind only to `127.0.0.1`; these services are local-only by design.
-- Handle empty `tokens` arrays gracefully because subtitle text can arrive before tokenization completes.
-- Reconnect on disconnect; SubMiner does not manage client reconnects for you.
-- Prefer `payload.text` for logging/automation and `payload.sentence` or `payload.tokens` for UI rendering.
+- Handle empty `tokens` arrays. Text can arrive before tokenization finishes.
+- Reconnect on disconnect yourself.
+- Use `text` for logging and automation, and `sentence` or `tokens` for display.
 
-## Plugin Development
+### Forward lines to a webhook
 
-SubMiner does **not** currently expose a general-purpose third-party plugin SDK inside the app itself. Today, the supported extension surfaces are:
-
-1. the local websocket streams
-2. the local texthooker UI
-3. the mpv Lua plugin's script-message API
-4. the launcher CLI
-
-### mpv script messages
-
-The mpv plugin accepts these script messages:
-
-```text
-script-message subminer-start
-script-message subminer-stop
-script-message subminer-toggle
-script-message subminer-menu
-script-message subminer-options
-script-message subminer-restart
-script-message subminer-status
-script-message subminer-autoplay-ready
-```
-
-The AniSkip messages (`subminer-skip-intro`, `subminer-aniskip-refresh`) are handled by the SubMiner app over the mpv IPC socket while it is connected.
-
-The start command also accepts inline overrides:
-
-```text
-script-message subminer-start backend=hyprland socket=/custom/path texthooker=no log-level=debug
-```
-
-### Practical extension patterns
-
-#### Add another mpv script that coordinates with SubMiner
-
-Examples:
-
-- send `subminer-start` after your own media-selection script chooses a file
-- send `subminer-status` before running follow-up automation
-- send `subminer-aniskip-refresh` after you update title/episode metadata (handled by the SubMiner app)
-
-#### Build a launcher wrapper
-
-Examples:
-
-- open a media picker, then call `subminer /path/to/file.mkv`
-- launch browser-only subtitle tooling with `subminer texthooker -o`
-- disable the helper UI for a session with `subminer --no-texthooker video.mkv`
-
-#### Build an overlay-adjacent client
-
-Examples:
-
-- browser widget showing current subtitle + token breakdown
-- local vocabulary capture helper that writes interesting lines to a file
-- bridge service that forwards websocket events into your own workflow engine
-
-## Webhook Examples
-
-SubMiner does **not** currently send outbound webhooks by itself. The supported pattern is to consume the websocket locally and relay events into another system.
-
-That still makes webhook-style automation straightforward.
-
-### Example: forward subtitle lines to a local webhook receiver
-
-```js
-import WebSocket from 'ws';
-
-const ws = new WebSocket('ws://127.0.0.1:6678');
-
-ws.on('message', async (raw) => {
-  const payload = JSON.parse(String(raw));
-
-  await fetch('http://127.0.0.1:5678/subminer/subtitle', {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({
-      text: payload.text,
-      tokens: payload.tokens,
-      receivedAt: new Date().toISOString(),
-    }),
-  });
-});
-```
-
-### Automation ideas
-
-- **n8n / Make / Zapier relay:** send each subtitle line into an automation workflow for logging, translation, or summarization.
-- **Discord / Slack notifier:** post only lines that contain unknown words or N+1 targets.
-- **Obsidian / Markdown capture:** append subtitle lines plus token metadata to a daily immersion note.
-- **Local LLM pipeline:** trigger a glossary, translation, or sentence-mining workflow whenever a new line arrives.
-
-### Filtering example: only forward N+1 lines
+SubMiner does not send webhooks itself. Relay the stream to your own endpoint instead. This example forwards only lines that contain an N+1 target:
 
 ```js
 import WebSocket from 'ws';
@@ -346,7 +192,6 @@ const ws = new WebSocket('ws://127.0.0.1:6678');
 ws.on('message', async (raw) => {
   const payload = JSON.parse(String(raw));
   const hasNPlusOne = payload.tokens.some((token) => token.isNPlusOneTarget);
-
   if (!hasNPlusOne) return;
 
   await fetch('http://127.0.0.1:5678/subminer/n-plus-one', {
@@ -357,18 +202,39 @@ ws.on('message', async (raw) => {
 });
 ```
 
-## Recommended Integration Combinations
+The same pattern works for n8n or Zapier workflows, Discord notifiers, or appending lines to a notes file.
 
-- **Browser Yomitan client:** `texthooker` + `annotationWebsocket`
-- **Custom dashboard:** `annotationWebsocket` only
-- **Lightweight subtitle mirror:** `websocket` only
-- **mpv-side automation:** mpv plugin script messages + optional websocket relay
-- **Webhook-style workflows:** `annotationWebsocket` + your own local relay service
+## mpv script messages
 
-## Related Pages
+SubMiner has no in-app plugin SDK. Besides the streams above, you can drive it from other mpv scripts and from the [launcher CLI](/launcher-script).
 
-- [Configuration](/configuration#websocket-server)
-- [Mining Workflow - Texthooker](/mining-workflow#texthooker)
-- [MPV Plugin](/mpv-plugin)
-- [Launcher Script](/launcher-script)
-- [Anki Integration](/anki-integration#proxy-mode-setup-yomitan--texthooker)
+The mpv plugin accepts these script messages:
+
+| Message                 | Action                                     |
+| ----------------------- | ------------------------------------------ |
+| `subminer-start`        | Start the overlay                          |
+| `subminer-stop`         | Stop the overlay                           |
+| `subminer-toggle`       | Toggle the visible overlay                 |
+| `subminer-menu`         | Open the plugin menu                       |
+| `subminer-options`      | Open the SubMiner settings window          |
+| `subminer-restart`      | Restart the overlay                        |
+| `subminer-status`       | Show overlay status on the mpv OSD         |
+| `subminer-stats-toggle` | Show an OSD hint for the overlay stats key |
+
+`subminer-start` accepts overrides for `backend` (`auto`, `hyprland`, `sway`, `x11`, `macos`), `socket`, `texthooker`, and `log-level`:
+
+```text
+script-message subminer-start backend=hyprland socket=/custom/path texthooker=no log-level=debug
+```
+
+The plugin also registers `subminer-autoplay-ready`, `subminer-autoplay-hold`, `subminer-visible-overlay-shown`, `subminer-visible-overlay-hidden`, `subminer-managed-subtitles-loading`, `subminer-overlay-loading-ready`, and `subminer-reload-session-bindings`. The SubMiner app sends these to keep the plugin in sync, so do not send them from your own scripts.
+
+While the app is connected to mpv, it also handles two AniSkip messages over the mpv IPC socket: `subminer-skip-intro` skips the intro, and `subminer-aniskip-refresh` reloads intro data, for example after your script changes title or episode metadata.
+
+## Related pages
+
+- [Configuration](/configuration)
+- [Mining workflow](/mining-workflow)
+- [mpv plugin](/mpv-plugin)
+- [Launcher script](/launcher-script)
+- [Anki integration](/anki-integration)

docs-site/youtube-integration.md

@@ -1,145 +1,100 @@
-# YouTube Integration
+# YouTube integration
 
-SubMiner auto-loads Japanese subtitles when you play a YouTube URL, giving you the same sentence-mining overlay experience as local video files. It probes available subtitle tracks via `yt-dlp`, selects the best primary and secondary tracks, downloads them, and loads them into mpv before playback resumes.
+Play a YouTube URL and SubMiner downloads its Japanese subtitles and loads them into mpv, so you can mine from it like a local file.
 
-## Requirements
+## Setup
 
-- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** must be installed and on your `PATH`. yt-dlp is a free command-line tool that reads YouTube video and subtitle info; SubMiner calls it behind the scenes. (`PATH` is the list of folders your system searches for programs - most installers add yt-dlp to it automatically. If yours did not, set `SUBMINER_YTDLP_BIN` to the full path of the yt-dlp binary.)
-- mpv with `--input-ipc-server` configured (handled automatically when you launch playback through the `subminer` launcher - no manual setup needed).
+Install [yt-dlp](https://github.com/yt-dlp/yt-dlp) and make sure it is on your `PATH`. If it is somewhere else, set `SUBMINER_YTDLP_BIN` to the full path of the binary.
 
-## How It Works
+## Usage
 
-When SubMiner detects a YouTube URL (or `ytsearch:` target), it pauses mpv at startup and runs a subtitle pipeline before resuming playback:
-
-1. **Probe** --- `yt-dlp --dump-single-json` extracts all available subtitle tracks (manual uploads and auto-generated captions) along with video metadata.
-2. **Discover** --- Each track is normalized into a `YoutubeTrackOption` with language code, kind (`manual` or `auto`), display label, and direct download URL.
-3. **Select** --- SubMiner picks the best primary track (Japanese, preferring manual over auto) and secondary track (English, preferring manual over auto).
-4. **Download** --- Selected tracks are fetched via direct URL when available, falling back to `yt-dlp --write-subs` / `--write-auto-subs`. YouTube TimedText XML formats (`srv1`/`srv2`/`srv3`) are converted to VTT on the fly. Auto-generated VTT captions are normalized to remove rolling-caption duplication.
-5. **Load** --- Subtitle files are injected into mpv via `sub-add`. Playback resumes once the primary track is ready; secondary failures do not block.
-
-## Pipeline Diagram
-
-```mermaid
-flowchart TD
-    classDef step fill:#c6a0f6,stroke:#494d64,color:#24273a
-    classDef action fill:#8aadf4,stroke:#494d64,color:#24273a
-    classDef result fill:#a6da95,stroke:#494d64,color:#24273a
-    classDef enrich fill:#8bd5ca,stroke:#494d64,color:#24273a
-    classDef ext fill:#eed49f,stroke:#494d64,color:#24273a
-
-    A[YouTube URL detected]:::step
-    B[yt-dlp probe]:::ext
-    C[Track discovery]:::action
-    D{Auto or manual selection?}:::step
-    E[Auto-select best tracks]:::action
-    F[Manual picker - Ctrl+Alt+C]:::action
-    G[Download subtitle files]:::action
-    H[Convert TimedText to VTT]:::enrich
-    I[Normalize auto-caption duplicates]:::enrich
-    K[sub-add into mpv]:::action
-    L[Overlay renders subtitles]:::result
-
-    A --> B
-    B --> C
-    C --> D
-    D -- startup --> E
-    D -- user request --> F
-    E --> G
-    F --> G
-    G --> H
-    H --> I
-    I --> K
-    K --> L
+```bash
+subminer https://www.youtube.com/watch?v=VIDEO_ID
+subminer ytsearch:"keyword"     # plays the first search result
 ```
 
-## Auto-Load Flow
+mpv starts paused while SubMiner fetches the subtitle list. It picks a primary and a secondary track, loads them, and resumes playback once the primary track is ready. A playlist link plays only the linked video.
 
-On startup with a YouTube URL:
+SubMiner picks tracks in this order. Manual (uploaded) tracks win over auto-generated captions.
 
-1. mpv launches paused.
-2. SubMiner calls `yt-dlp --dump-single-json` to probe all subtitle tracks.
-3. Tracks are split into **manual** (human-uploaded) and **auto** (machine-generated) categories.
-4. The selection algorithm picks:
-   - **Primary**: first Japanese manual track, then Japanese auto track, then any manual track, then first available track.
-   - **Secondary**: first English manual track, then English auto track (excluding the primary).
-5. If mpv already exposes an authoritative matching track, SubMiner reuses it instead of downloading again.
-6. Missing tracks are downloaded to a temp directory and loaded via `sub-add`.
-7. Playback unpauses once the primary subtitle is ready.
+| Track     | Choice                                                                           |
+| --------- | -------------------------------------------------------------------------------- |
+| Primary   | Japanese manual, then Japanese auto, then any manual track, then the first track |
+| Secondary | English manual, then English auto. Skipped if none exists.                       |
 
-## Manual Subtitle Picker
+Press `Ctrl+Alt+C` during playback to open the subtitle picker. It lists every track with its language and kind, and lets you choose different primary and secondary tracks or retry a failed load.
 
-Press **Ctrl+Alt+C** during YouTube playback to open the subtitle picker overlay. This lets you:
+## Generate subtitles with Whisper
 
-- Browse all discovered tracks (manual and auto-generated)
-- Select different primary and secondary tracks
-- Retry track loading if the auto-load failed or picked the wrong track
+SubMiner can transcribe a YouTube video's audio on your computer. For one video, press `Ctrl+Shift+G` and click **Generate subtitles**. To always use Whisper instead of YouTube's captions, set `youtube.subtitleSource` to `whisper`, or choose **Generate with Whisper** under **Settings > Behavior > YouTube Playback Settings**. The change applies to the next video.
 
-The picker displays each track with its language, kind (manual/auto), and title when available.
+```jsonc
+{
+  "youtube": { "subtitleSource": "whisper" },
+}
+```
 
-## Subtitle Format Handling
+Whisper uses the model and tools from [Japanese subtitle generation](/subtitle-generation), so set those up first.
 
-SubMiner handles several YouTube subtitle formats transparently:
+- The video stays paused while the subtitles are generated, and the subtitle generation modal shows the progress. Close the modal to keep watching while generation continues. **Cancel** stops it and resumes the video without subtitles.
+- The subtitles load and playback resumes as soon as they are ready.
+- SubMiner downloads the smallest audio stream of at least 48 kbps, in the video's original language, never an auto-dub.
+- The audio is deleted as soon as generation finishes or fails, and when you switch to another video, close mpv, or quit SubMiner. Switching videos also stops the generation.
+- No secondary subtitles load. The picker (`Ctrl+Alt+C`) still loads YouTube tracks by hand.
 
-| Format | Handling |
-| ------ | -------- |
-| `srt`, `vtt` | Used directly (preferred for manual tracks) |
-| `srv1`, `srv2`, `srv3` | YouTube TimedText XML --- converted to VTT automatically |
-| Auto-generated VTT | Normalized to remove rolling-caption text duplication |
+## Browse YouTube in SubMiner
 
-For auto-generated tracks, SubMiner prefers `srv3` > `srv2` > `srv1` > `vtt` (TimedText XML produces cleaner output). For manual tracks, `srt` > `vtt` is preferred.
+Open a YouTube window with `subminer youtube` (or `subminer yt`), or from the tray (**Browse YouTube**). Sign in once and the login is kept across restarts. Videos you pick play in mpv with the same subtitle setup as above, and SubMiner starts mpv if it is not running.
 
-## Configuration Reference
+When SubMiner was started by `subminer youtube`, closing the window quits it. If a video is still playing, SubMiner quits when you close mpv instead.
 
-### Primary Subtitle Languages
+| Action                                                       | Result                              |
+| ------------------------------------------------------------ | ----------------------------------- |
+| Click a video                                                | Play it now                         |
+| Middle-click, or `Shift`/`Ctrl`+click                        | Add it to the end of mpv's playlist |
+| Right-click a video                                          | **Play in mpv** or **Queue in mpv** |
+| `Alt+Left` / `Alt+Right`, mouse back/forward, or right-click | Go back or forward                  |
+
+Queued videos get their subtitles loaded when mpv reaches them. Open the queue with the playlist browser (`Ctrl+Alt+P`) to reorder or skip entries.
+
+If Google refuses the sign-in, try again once. The window uses a standard Chrome user agent, but Google can still block embedded browsers.
+
+## Secondary subtitle languages
+
+YouTube secondary selection is fixed to English. `secondarySub.secondarySubLanguages` and `secondarySub.autoLoadSecondarySub` apply only to local files and Jellyfin. `secondarySub.defaultMode` still controls how the secondary bar is shown. Use the picker to load a different secondary language.
+
+Likewise, `youtube.primarySubLanguages` does not change which YouTube track is picked. It sets which languages count as a primary subtitle for local and playlist subtitle selection and for the "primary subtitle missing" notification.
+
+## Card media
+
+By default, card audio and screenshots are cut from mpv's live YouTube stream. If card media fails with `403` errors, switch to the background cache:
 
 ```jsonc
 {
   "youtube": {
-    "primarySubLanguages": ["ja", "jpn"]
-  }
+    "mediaCache": { "mode": "background" },
+  },
 }
 ```
 
-| Option | Type | Description |
-| ------ | ---- | ----------- |
-| `primarySubLanguages` | `string[]` | Language priority for YouTube primary subtitle auto-loading (default `["ja", "jpn"]`) |
+In background mode, SubMiner downloads the video with yt-dlp after playback starts. Cards you mine get their text fields right away, and audio and images are added once the download finishes. `youtube.mediaCache.maxHeight` caps the download resolution (`0` for no limit). If the download fails, SubMiner tells you and drops the pending media updates.
 
-### Secondary Subtitle Languages
+See [Configuration](/configuration#youtube-playback-settings) for all `youtube` options and defaults.
 
-Secondary track selection uses the shared `secondarySub` config:
+## Troubleshooting
 
-```jsonc
-{
-  "secondarySub": {
-    "secondarySubLanguages": [],
-    "autoLoadSecondarySub": false,
-    "defaultMode": "hover"
-  }
-}
-```
+**No Japanese subtitles.** The video may not have any. Open the picker with `Ctrl+Alt+C` to see what is available.
 
-| Option | Type | Description |
-| ------ | ---- | ----------- |
-| `secondarySubLanguages` | `string[]` | Extra language codes (e.g. `["eng", "en"]`) used when auto-selecting a secondary track. Default is empty (`[]`). For YouTube, SubMiner always tries an English track first regardless of this list. |
-| `autoLoadSecondarySub` | `boolean` | Auto-detect and load a matching secondary track (default: `false`) |
-| `defaultMode` | `"hidden"` / `"visible"` / `"hover"` | Initial display mode for secondary subtitles (default: `"hover"`) |
+**yt-dlp not found.** Install it and put it on `PATH`, or set `SUBMINER_YTDLP_BIN`.
 
-Precedence: CLI flag > environment variable > `config.jsonc` > built-in default.
+**Timeouts.** Each yt-dlp call times out after 15 seconds. Slow or rate-limited connections can hit this. Retry, or update yt-dlp.
 
-## Limitations and Troubleshooting
+**Poor subtitle quality.** Auto-generated captions are often inaccurate. SubMiner uses a manual track when one exists.
 
-- **No subtitles found**: The video may not have Japanese subtitles. Open the picker with `Ctrl+Alt+C` to see all available tracks.
-- **yt-dlp not found**: Install `yt-dlp` and ensure it is on `PATH`, or set `SUBMINER_YTDLP_BIN` to the binary path.
-- **Probe timeout**: `yt-dlp` has a 15-second timeout per operation. Slow connections or rate-limited IPs may hit this. Retry or update `yt-dlp`.
-- **Auto-caption quality**: YouTube auto-generated captions vary in quality. Manual subtitles (when available) are always preferred.
-- **`ytsearch:` targets**: `subminer ytsearch:"keyword"` plays the first search result. Subtitle availability depends on the matched video.
-- **Secondary subtitle fails**: Secondary track failures never block playback. The primary subtitle loads independently.
-- **Native mpv secondary rendering**: Stays hidden during YouTube flows so the SubMiner overlay remains the visible secondary subtitle surface.
+**Subtitles fail with HTTP 429.** YouTube is refusing caption requests from your network. It can last hours or days, and waiting or signing in does not always help. [Generate them with Whisper](#generate-subtitles-with-whisper) instead.
 
-## Related Pages
+A missing or failed secondary track never blocks playback.
 
-- [Usage --- YouTube Playback](/usage#youtube-playback)
-- [Configuration --- YouTube Playback Settings](/configuration#youtube-playback-settings)
-- [Configuration --- Secondary Subtitle](/configuration#secondary-subtitle)
-- [Keyboard Shortcuts](/shortcuts)
-- [Jellyfin Integration](/jellyfin-integration)
+## Stats
+
+The stats Library groups YouTube videos by channel. Choose **YouTube** in the Library filter to see them. See [Immersion tracking](/immersion-tracking).

docs/RELEASING.md

@@ -6,11 +6,46 @@
 
 - `claude` (Claude Code CLI) installed, on `PATH`, and authenticated.
   `changelog:build` and `changelog:prerelease-notes` invoke
-  `claude -p --model sonnet` to merge and rewrite `changes/*.md` fragments into
+  `claude -p --model opus --effort medium` to merge and rewrite `changes/*.md` fragments into
   a polished, user-facing release body. Either OAuth login (`claude /login`) or
   `ANTHROPIC_API_KEY` works. Install from <https://claude.com/claude-code> if
   you don't already have it.
 
+## Package contents checks
+
+Stable and prerelease workflows share `.github/workflows/package-release.yml`.
+Both callers explicitly pass the five required macOS signing/notarization
+secrets plus the optional `SUBMINER_TMDB_API_KEY` (the project TMDB key that
+`scripts/prepare-build-assets.mjs` stages into `dist/bundled-integration-keys.json`;
+artifacts built without it simply require users to set `tmdb.apiKey`).
+`GITHUB_TOKEN` remains automatically available to the reusable workflow.
+Each platform verifies its ASAR and external resources before signing. Missing
+runtime assets, foreign SQLite/Koffi binaries, duplicate UI fonts, demo media,
+source maps, TypeScript files, and nested test or fixture directories fail the build.
+Current targets are Linux x64, macOS arm64, and Windows x64.
+
+The runtime allowlist includes `dist/`, `stats/dist/`, and
+`vendor/texthooker-ui/docs/` plus metadata, config example, and license. The
+texthooker `docs/` directory is its built UI. Keep the positive `package.json`
+pattern in platform `files` lists: electron-builder otherwise treats an
+exclusion-only platform list as a separate include-all matcher. Windows keeps
+only its target Koffi binary; other platforms omit Koffi. Desktop UIs share the
+original M PLUS 1 TTF in `dist/fonts/`.
+
+The shared workflow runs `bun run test:package <resources-directory>` with the
+pinned Electron runtime and temporary user data. On headless Linux, prefix it
+with `xvfb-run -a`. This checks packaged SQLite, Windows FFI loading/polling,
+texthooker serving, Yomitan loading, UI assets, and Japanese font loading.
+Standalone pages lack app IPC handlers and can log related errors; this check
+does not replace an installed app session.
+
+Before shipping packaging changes, check each platform's installed app:
+startup and mpv tracking, dictionary lookup and stroke orders, settings/sync UI,
+stats persistence, sentence mining with AnkiConnect, and updating from the prior
+release. Preserve Electron locales, graphics fallbacks, codecs, dictionaries,
+license notices, updater metadata, blockmaps, and the macOS updater ZIP. Trim
+files before signing and generating updater hashes, never from a signed app.
+
 ## Stable Release
 
 1. Confirm `main` is green: `gh run list --workflow CI --limit 5`.
@@ -31,6 +66,14 @@
    `bun run test:fast`
    `bun run test:env`
    `bun run build`
+   Confirm `dist/launcher` contains only `subminer`, `subminer.cmd`,
+   `subminer.js`, `prepare.cjs`, and `version`. Release CI smoke-tests
+   `subminer.js` with Bun, then publishes both wrapper files and their checksums.
+   Tagged CI runs `bun scripts/package-bun-source.mjs` and must publish
+   `bun-v<version>-source.tar.gz` plus its `.sha256` file. The script
+   fails if Bun's CMake dependency pins, WebKit pin, source checksums, patch
+   inputs, or collected license files differ from
+   `build/bun-source-manifest.json`.
    When validating auto-update metadata, also run the relevant platform package
    build and confirm `release/` contains the generated updater metadata
    (`latest*.yml`) and blockmaps (`*.blockmap`).
@@ -54,15 +97,25 @@
    `bun run test:fast`
    `bun run test:env`
    `bun run build`
+   Confirm both launcher wrappers and their checksums are included in the
+   prerelease assets.
+   Prerelease CI also assembles and publishes the pinned Bun corresponding
+   source archive. A missing source repository or license file fails the
+   release instead of publishing only the executable.
    When validating packaged updater output, confirm the platform build writes
    `latest*.yml` and `*.blockmap` files under `release/`.
 5. Commit the prerelease prep (package.json version bump + the generated
    `release/prerelease-notes.md`). CI does not regenerate notes — it uses the
-   committed file — so review it before committing. If you add more
-   `changes/*.md` fragments for a later beta/RC, rerun
-   `bun run changelog:prerelease-notes --version <version>`; the generator uses
-   the existing prerelease notes as the baseline and asks Claude to merge only
-   the new fragment material. Do not run `bun run changelog:build`.
+   committed file — so review it before committing. Rerun
+   `bun run changelog:prerelease-notes --version <version>` for every later
+   beta/RC, even if no fragments changed: the notes carry a hidden
+   `prerelease-version` marker and CI rejects the tag when the marker does not
+   match it (verify locally with
+   `bun run changelog:check-prerelease-notes --version <version>`). The
+   generator reuses the existing notes as the cumulative baseline when their
+   marker (or legacy `prerelease-base-version` marker) matches the current base
+   version, and asks Claude to merge only the new fragment material. Do not run
+   `bun run changelog:build`.
 6. Tag the commit: `git tag v<version>`.
 7. Push commit + tag.
 
@@ -76,19 +129,23 @@ Notes:
 - Pass `--date` explicitly when you want the release stamped with the local cut date; otherwise the generator uses the current ISO date, which can roll over to the next UTC day late at night.
 - `changelog:check` now rejects tag/package version mismatches.
 - `changelog:prerelease-notes` also rejects tag/package version mismatches and writes `release/prerelease-notes.md` without mutating tracked changelog files. When that file already exists, the generator includes it in the Claude prompt so later beta/RC notes reuse the reviewed text instead of starting over.
+- From the second prerelease of a base version onward, the notes open with a `## Changes since <previous tag>` section above the cumulative `## Highlights`. The generator locates the newest preceding beta/RC tag for the same base version (semver order: all betas before all RCs), diffs `changes/*.md` between that tag and the working tree, and asks Claude to describe only the behavioral beta-to-beta differences — added fragments as new changes, modified fragments by their before/after difference (editorial-only edits are dropped), deleted fragments as removed/reverted changes. If no fragments changed (for example a packaging-only rebuild), the section states that explicitly without a Claude call. The delta section carries no separate contributor attribution; `## What's Changed` stays cumulative like `## Highlights`.
+- `changelog:check-prerelease-notes --version <version>` verifies the committed notes' `prerelease-version` marker matches the version being tagged; the prerelease workflow runs it and fails the release on stale notes.
 - `changelog:build` generates `CHANGELOG.md` + `release/release-notes.md` (both polished by `claude -p`) and removes the released `changes/*.md` fragments. The CHANGELOG keeps internal notes inside a `<details><summary>Internal changes</summary>` collapse; the release notes drop them entirely.
-- `release/release-notes.md` (and `release/prerelease-notes.md`) end with GitHub-style attribution: a `## What’s Changed` list crediting each released fragment as `by @<author> in #<pr>`, plus a `## New Contributors` section for first-time authors. Attribution is resolved per fragment via `git log` (the commit that added the fragment) + `gh api .../commits/<sha>/pulls`, with one `gh` search per author for the first-contribution check. It needs `gh` installed and authenticated; if `gh` is unavailable or a lookup fails, the generator warns and emits notes without the attribution sections rather than failing. The CHANGELOG itself stays attribution-free.
+- `release/release-notes.md` (and `release/prerelease-notes.md`) include GitHub-style attribution after `## Highlights`: a `## What's Changed` list crediting each released fragment as `by @<author> in #<pr>`, plus a `## New Contributors` section for first-time authors. Attribution is resolved per fragment via `git log` (the commit that added the fragment) + `gh api .../commits/<sha>/pulls`, with one `gh` search per author for the first-contribution check. It needs `gh` installed and authenticated; if `gh` is unavailable or a lookup fails, the generator warns and emits notes without the attribution sections rather than failing. The CHANGELOG itself stays attribution-free.
 - The release workflow no longer auto-runs `changelog:build`. If pending `changes/*.md` fragments are present on a tag-based run, CI exits with a clear `::error::` pointing at the local fix. Run `bun run changelog:build --version <version>` locally, commit the polished output, then tag.
 - Do not tag while `changes/*.md` fragments still exist.
 - Prerelease tags intentionally keep `changes/*.md` fragments in place so multiple prereleases can reuse the same cumulative pending notes until the final stable cut. `make clean` preserves `release/prerelease-notes.md` while deleting generated build artifacts.
 - If you need to repair a published release body (for example, a prior version’s section was omitted), regenerate notes from `CHANGELOG.md` and re-edit the release with `gh release edit --notes-file`.
 - Prerelease tags are handled by `.github/workflows/prerelease.yml`, which always publishes a GitHub prerelease with all current release platforms and never runs the AUR sync job.
+- CI, stable release, and prerelease workflows call the shared `.github/workflows/quality-gate.yml`; update that reusable workflow when changing common test coverage. Its environment suite includes the Lua mpv plugin tests.
 - Tagged release workflow now also attempts to update `subminer-bin` on the AUR after GitHub Release publication.
 - Stable release tags update `https://docs.subminer.moe/` and `https://docs.subminer.moe/v/<version>/` through `.github/workflows/docs-pages.yml`; `/main/` continues to show development docs from `main`.
 - Keep Cloudflare Pages Git auto-deploy disabled for `docs.subminer.moe`. Production docs are direct-uploaded by Wrangler from GitHub Actions with `--branch main`.
-- AUR publish is best-effort: the workflow retries transient SSH clone/push failures, then warns and leaves the GitHub Release green if AUR still fails. Follow up with a manual `git push aur master` from the AUR checkout when needed.
+- AUR publish is best-effort: the workflow downloads the three known assets directly from the tagged release URLs, avoiding GitHub's sometimes-stale release asset listing. Downloads and SSH clone/push operations retry transient failures, then warn and skip AUR publication if retries are exhausted. Follow up with a manual `git push aur master` from the AUR checkout when needed.
 - Required GitHub Actions secret: `AUR_SSH_PRIVATE_KEY`. Add the matching public key to your AUR account before relying on the automation.
 - Release and prerelease workflows upload updater metadata (`latest*.yml`) and blockmaps (`*.blockmap`) alongside platform artifacts. Do not remove those files while `electron-updater` is enabled.
+- Release and prerelease workflows publish `subminer` for POSIX systems and `subminer.cmd` for Windows. Both locate a packaged app and use its private Bun runtime. Keep the corresponding-source archive named `bun-v1.3.5-source.tar.gz`.
 - macOS tray app updates use the standard `electron-updater`/Squirrel path. Keep `latest-mac.yml`, the macOS `SubMiner-<version>-mac.zip`, and ZIP blockmap published; Squirrel uses the ZIP payload even when the DMG remains the user-facing installer.
 - macOS update metadata and full ZIP downloads are routed through `/usr/bin/curl` before Squirrel installation to avoid Electron main-process network crashes on update checks.
 - Windows tray app updates use the standard `electron-updater`/NSIS path. Keep `latest.yml`, the Windows NSIS installer, and installer blockmap published; updater HTTP is routed through main-process fetch to avoid Electron main-process network crashes during update checks.

docs/architecture/2026-03-15-renderer-performance-design.md

@@ -61,21 +61,35 @@ External subtitle files only (SRT, VTT, ASS). Embedded subtitle tracks are out o
 
 #### Subtitle File Parsing
 
-A new cue parser that extracts both timing and text content from subtitle files. The existing `parseSrtOrVttStartTimes` in `subtitle-delay-shift.ts` only extracts timing; this needs a companion that also extracts the dialogue text.
+A cue parser extracts both timing and text content from subtitle files for prefetching.
 
 **Parsed cue structure:**
+
 ```typescript
 interface SubtitleCue {
   startTime: number; // seconds
   endTime: number; // seconds
-  text: string;       // raw subtitle text
+  text: string; // plain text, decoded from the source format
+  source?: 'canonical-ass'; // recovered authored text for generated ASS animation
+  animationStartTime?: number; // full generated-frame envelope; entrance/exit frames
+  animationEndTime?: number; //   run past the authored timing, live matching uses this
 }
 ```
 
 **Supported formats:**
+
 - SRT/VTT: Regex-based parsing of timing lines + text content between timing blocks.
-- ASS: Parse `[Events]` section, extract `Dialogue:` lines, split on the first 9 commas only (ASS v4+ has 10 fields; the last field is Text which can itself contain commas). Strip ASS override tags (`{\...}`) from the text before storing.
-  ASS text fields contain inline override tags like `{\b1}`, `{\an8}`, `{\fad(200,300)}`. The cue parser strips these during extraction so the tokenizer receives clean text.
+- ASS: Parse the `[Events]` section, read the field order from the `Format:` row, and extract timed `Dialogue:` lines. Timed `Comment:` lines are normally ignored, but can supply canonical authored text when they match a nearby generated animation from the same style and actor. Text can itself contain commas.
+
+**ASS decoding.** The parser is where ASS text is decoded, once, via `assToPlainText()` in `src/core/services/ass-text.ts`. That decoder mirrors mpv's `ass_to_plaintext` so a cue read from a file reads identically to the same line arriving live on `sub-text`: `{...}` override blocks are markup, `\pN … \p0` vector drawing runs are dropped rather than shown as text, `\N`/`\n`/`\h` are the only escapes (`\{`, `\}` and `\\` are not), and an unclosed `{` is rendered verbatim. Every layer downstream — renderer, timing tracker, tokenizer, tokenization cache keys — receives plain text and uses `normalizePlainSubtitleText()` for whitespace only, so nothing decodes the same string twice and one authored line always maps to one cache key.
+
+**Duplicate collapsing.** Typeset scripts emit one `Dialogue:` event per animation frame, plus layered copies of the same line. The parser collapses identical text over an identical span unconditionally, and collapses contiguous same-text runs of at least three events when the run looks like an animation. For ASS that means shared style and actor plus authoring evidence: a temporal tag (`\t`, `\move`, `\k`/`\kf`/`\ko`/`\K`, or anything wrapped in `\t(...)`), an animated `Effect` column (`Karaoke`, `Banner`, `Scroll`), or override values that change across the run. Static tags shared by every event (`\pos`, an identical `\clip`) are not evidence. SRT/VTT carry no such metadata, so there collapsing needs at least five contiguous events all under 0.1s — the frame timing left behind by ASS-to-SRT conversion. The parser keeps this authoring metadata (style, actor, layer, `Effect`, parsed override commands, source order) private; `parseSubtitleCues()` returns only `SubtitleCue`.
+
+ASS scripts can also redraw one complete lyric for two or more long color/highlight phases. Those flush-timed phases collapse separately from short animation frames when they share text, style, actor, and layer and carry direct animation evidence, such as temporal tags or changing non-spatial overrides. Spatial command changes do not prove a phase, so separately positioned signs remain distinct.
+
+**Canonical animation recovery.** Some ASS producers keep the readable lyric or sign as a timed `Comment:` and generate hundreds of `Dialogue:` frames containing repeated glyphs or changing clip regions. Others retain the complete line as brief `Dialogue:` events around the generated fragments. A complete event is promoted only when nearby dialogue from the same style and actor forms a proven animation cluster and reconstructs its entire text in source order. The generated frames are then replaced by one cue marked `source: 'canonical-ass'`. This source marker lets the live primary-subtitle path prefer the clean authored text and timing for display, sidebar history, immersion recording, and mining, while unmatched editor notes and alternative translations remain ignored. Secondary selection advances to an entering canonical cue at its generated animation start when the preceding authored cue ends before the new authored span. Unrelated simultaneous cues that continue through the new span remain visible.
+
+**Font texture cleanup.** A clipped repeated-glyph run or frequent changes to secondary alpha marks a texture seed. Clipped runs do not need a font override because some signs build their masks from ordinary `l` glyphs. The parser removes short clipped pieces that share a no-font seed's style and timing, or pieces that share a font seed's style, timing, and font even when the actor changes. It also removes positioned text layers with at least `E0` global alpha when they overlap a seed in the same style. Opaque authored sign text stays publishable when the texture switches fonts or actors around it.
 
 #### Prefetch Service Lifecycle
 
@@ -153,6 +167,7 @@ tokens (already have frequencyRank values from parser-level applyFrequencyRanks)
 ### Dependency Analysis
 
 All annotations either depend on MeCab POS data or benefit from running after it:
+
 - **Known word marking:** Needs base tokens (surface/headword). No POS dependency, but no reason to run separately.
 - **Frequency filtering:** Uses `pos1Exclusions` and `pos2Exclusions` to clear frequency ranks on excluded tokens (particles, noise). Depends on MeCab POS data.
 - **JLPT marking:** Uses `shouldIgnoreJlptForMecabPos1` to filter. Depends on MeCab POS data.
@@ -169,18 +184,14 @@ function annotateTokens(tokens, deps, options): MergedToken[] {
 
   // Single pass: known word + frequency filtering + JLPT computed together
   const annotated = tokens.map((token) => {
-    const isKnown = nPlusOneEnabled
-      ? token.isKnown || computeIsKnown(token, deps)
-      : false;
+    const isKnown = nPlusOneEnabled ? token.isKnown || computeIsKnown(token, deps) : false;
 
     // Filter frequency rank using POS exclusions (rank values already set at parser level)
     const frequencyRank = frequencyEnabled
       ? filterFrequencyRank(token, pos1Exclusions, pos2Exclusions)
       : undefined;
 
-    const jlptLevel = jlptEnabled
-      ? computeJlptLevel(token, deps.getJlptLevel)
-      : undefined;
+    const jlptLevel = jlptEnabled ? computeJlptLevel(token, deps.getJlptLevel) : undefined;
 
     return { ...token, isKnown, frequencyRank, jlptLevel };
   });
@@ -221,6 +232,7 @@ Replace `document.createElement('span')` calls in the renderer with `templateSpa
 ### Current Behavior
 
 In `renderWithTokens` (`subtitle-render.ts`), each render cycle:
+
 1. Clears DOM with `innerHTML = ''`
 2. Creates a `DocumentFragment`
 3. Calls `document.createElement('span')` for each token (~10-15 per subtitle)
@@ -257,7 +269,7 @@ Full recycling (collecting old nodes, clearing attributes, reusing them) require
 ## Combined Impact Summary
 
 | Scenario                          | Before     | After      | Improvement |
-|----------|--------|-------|-------------|
+| --------------------------------- | ---------- | ---------- | ----------- |
 | Normal playback (prefetch-warmed) | ~200-320ms | ~30-50ms   | ~80-85%     |
 | Cache hit (repeated subtitle)     | ~72ms      | ~55-65ms   | ~10-20%     |
 | Cache miss (immediate seek)       | ~200-320ms | ~150-260ms | ~20-25%     |
@@ -267,16 +279,19 @@ Full recycling (collecting old nodes, clearing attributes, reusing them) require
 ## Files Summary
 
 ### New Files
+
 - `src/core/services/subtitle-prefetch.ts`
 - `src/core/services/subtitle-cue-parser.ts`
 
 ### Modified Files
+
 - `src/core/services/subtitle-processing-controller.ts` (expose `preCacheTokenization`)
 - `src/core/services/tokenizer/annotation-stage.ts` (batched single-pass)
 - `src/renderer/subtitle-render.ts` (template cloneNode)
 - `src/main.ts` (wire up prefetch service)
 
 ### Test Files
+
 - New tests for subtitle cue parser (SRT, VTT, ASS formats)
 - New tests for subtitle prefetch service (priority window, seek, pause/resume)
 - Updated tests for annotation stage (same behavior, new implementation)

docs/architecture/README.md

@@ -10,11 +10,15 @@ Read when: runtime ownership, composition boundaries, or layering questions
 SubMiner runs as three cooperating runtimes:
 
 - Electron desktop app in `src/`
-- Launcher CLI in `launcher/`
+- Launcher CLI in `launcher/`, with managed app-installed wrappers in `src/main/runtime/managed-launcher.ts`
 - mpv Lua plugin in `plugin/subminer/`
 
 The desktop app keeps `src/main.ts` as composition root and pushes behavior into small runtime/domain modules.
 
+Packaged apps include a private Bun runtime. Setup and release assets provide bootstrap wrappers generated from `src/main/runtime/*-launcher-bootstrap.ts`. macOS runs Bun and the CLI from app resources. Windows stages a versioned private Bun copy under `%LOCALAPPDATA%\SubMiner\launcher-runtime/<version>` so a running launcher does not lock the updater-owned app executable. Linux stages Bun, the matching CLI, and licenses under `${XDG_DATA_HOME:-~/.local/share}/SubMiner/launcher`. Its steady-state path performs one app `stat` and starts the cache without Electron. A missing cache or changed app fingerprint runs `launcher/prepare.cjs` through Electron's Node mode to refresh it. Desktop startup migrates recognized writable legacy JavaScript launchers and refreshes managed payloads after app changes. Development commands still use system Bun.
+
+Update checks and startup launcher migration share a serialized update-state store. Deferred launcher paths are acknowledged only after migration succeeds or the candidate is no longer eligible. Running Windows launchers and unreadable or unwritable candidates remain pending for a later startup.
+
 ## Read Next
 
 - [Domains](./domains.md) - who owns what
@@ -26,11 +30,19 @@ The desktop app keeps `src/main.ts` as composition root and pushes behavior into
 
 - `src/main/` owns composition, runtime setup, IPC wiring, and app lifecycle adapters.
 - `src/main/boot/` owns boot-phase assembly seams so `src/main.ts` can stay focused on lifecycle coordination and startup-path selection.
+- `src/main/runtime/linux-overlay-mode-runtime.ts` owns Linux fullscreen mode state and window replacement. App cleanup cancels pending replacements; `main.ts` supplies window creation and subtitle refresh hooks.
 - `src/core/services/` owns focused runtime services plus pure or side-effect-bounded logic.
+- `src/core/services/subtitle-generation*.ts` shares local whisper.cpp transcription, safe model downloads, and progress between the launcher and Electron. Optional dialogue mode retains both Silero-detected speech and other audible sections, omits confidently silent gaps, decodes passages independently, and restores original media timing. `src/main/runtime/subtitle-generation-runtime.ts` owns the overlay job lifecycle and only loads completed subtitles into the same local media; `src/shared/subtitle-generation*.ts` owns configuration, the multilingual model catalog, and IPC contracts. The overlay runtime retains a session model selection, validates picker requests through IPC, and keeps external model paths authoritative.
+- Subtitle model recommendations use bounded `nvidia-smi` and Whisper CUDA discovery probes in `subtitle-generation-acceleration.ts`. The overlay runtime caches results by executable path for 30 seconds and exposes acceleration status through the existing status IPC. Recommendations do not alter model selection or transcription arguments.
+- `subtitle-generation-reference.ts` ranks mpv's loaded text subtitle tracks, excludes signs/songs and forced references, and extracts timing hints with FFmpeg. The overlay and launcher snapshot references only for matching media, including active subtitle delays. Hints guide long-passage cuts with or without VAD; they never limit audio coverage or replace Whisper timestamps.
+- `src/main/runtime/subtitle-selection.ts` reads and validates mpv subtitle tracks and applies primary/secondary selections. Its opt-in session shortcut opens the shared overlay modal window, with renderer focus and subtitle suppression handled by the modal registry.
+- `src/shared/session-key-sequences.ts` rejects sequence prefixes reserved by single-key actions. The session-binding compiler reserves configured and built-in overlay keys; `src/main/runtime/session-bindings-runtime.ts` adds active mpv bindings and publishes the effective list to both the plugin artifact and the renderer through `session-bindings:changed`. mpv no-op `ignore` bindings do not reserve prefixes.
 - `src/renderer/` owns overlay rendering and input behavior.
 - `src/config/` owns config definitions, defaults, loading, and resolution.
 - `src/types/` owns shared cross-runtime contracts via domain entrypoints; `src/types.ts` stays a compatibility barrel.
 - `src/main/runtime/composers/` owns larger domain compositions.
+- `src/main.ts` call sites invoke configured runtime handlers and runtime-object methods directly;
+  do not add local pass-through wrappers around them.
 
 ## Architecture Intent
 
@@ -38,3 +50,7 @@ The desktop app keeps `src/main.ts` as composition root and pushes behavior into
 - Composition over monoliths
 - Pure helpers where possible
 - Stable user behavior while internals evolve
+
+Startup resolves and creates the user-data directory in `src/main-entry-runtime.ts`
+before the entry process requests Electron's single-instance lock. Main-process
+config bootstrap then writes the default config only when no config file exists.

docs/architecture/domains.md

@@ -3,7 +3,7 @@
 # Domain Ownership
 
 Status: active
-Last verified: 2026-05-23
+Last verified: 2026-07-15
 Owner: Kyle Yasuda
 Read when: you need to find the owner module for a behavior or test surface
 
@@ -16,21 +16,59 @@ Read when: you need to find the owner module for a behavior or test surface
 
 ## Product / Integration Domains
 
-- Config system: `src/config/`
+- Config system: `src/config/`; Anki resolution is composed by
+  `src/config/resolve/anki-connect.ts` from focused resolvers in
+  `src/config/resolve/anki-connect/`
 - Overlay/window state: `src/core/services/overlay-*`, `src/main/overlay-*.ts`
 - MPV runtime and protocol: `src/core/services/mpv*.ts`
+  Windows executable lookup and detached process creation are shared in `src/main/runtime/mpv-process.ts`. The Windows launcher and Jellyfin handlers retain their own playback and connection workflows.
 - Subtitle/token pipeline: `src/core/services/subtitle-*.ts`, `src/core/services/tokenizer*`, `src/core/services/tokenizer/`, `src/subsync/`
 - Anki workflow: `src/anki-integration/`, `src/core/services/anki-jimaku*.ts`
+- Media timing review: `src/main/runtime/media-timing-review.ts` owns the review and hidden `MediaTimingPreviewSession`. The session waits for mpv readiness and acknowledges playback commands; its `time-pos` observations reach the modal through `media-timing-review:preview-position`. The renderer places the cursor from those timestamps and uses an inactivity timeout instead of timing the clip itself.
 - Immersion tracking: `src/core/services/immersion-tracker/`
   Includes stats storage/query schema such as `imm_videos`, `imm_media_art`, and `imm_youtube_videos` for per-video and YouTube-specific library metadata.
+  Library-entry identity aliases and merge recommendations are persisted alongside this schema; the stats HTTP and SPA layers only expose and present those domain decisions.
+  `delete-maintenance-scheduler.ts` coalesces and serializes stats deletes; the expensive work runs in `delete-maintenance-worker-thread.ts` while the tracker queues playback writes. Each batch uses one transaction, lexical update, rollup refresh, and incremental lifetime subtraction (`planLifetimeRemovals`/`applyLifetimeRemovals` in `lifetime.ts`). Merges, moves, AniList reassignments, and `stats cleanup -l` use `repairLifetimeSummariesFromMedia` (recompute from the per-video media ledger). The full lifetime rebuild survives only as the empty-table bootstrap; anywhere else it would collapse lifetime totals to the session retention window.
+- Immersion sync: `src/core/services/stats-sync/`, bound by `src/main/sync-cli.ts`.
+  `snapshot-transfer.ts` selects compressed rsync or scp. `transfer-cache.ts` atomically retains the last successfully received snapshot per hashed peer/database identity under the config directory's `sync-transfer-cache/`. Cache copies seed isolated transfer directories; rsync verifies reconstructed files before the existing merge engine runs. The `--make-temp` / `--remove-temp` helpers accept an internal `--transfer-cache` key, with a fallback for older peers that do not recognize it.
 - AniList tracking + character dictionary: `src/core/services/anilist/`, `src/main/runtime/composers/anilist-*`, `src/main/character-dictionary-runtime.ts`, `src/main/character-dictionary-runtime/`
+- TMDB live-action metadata: `src/core/services/tmdb/` (client + exact-title resolver), `src/core/services/immersion-tracker/live-action-link.ts` (links an entry to a TMDB title and merges other holders of the same title). The AniList cover-art fetcher calls the resolver as its fallback; `imm_anime.media_kind` marks the result and keeps the entry out of AniList season repair.
 - Jellyfin integration: `src/core/services/jellyfin*.ts`, `src/main/runtime/composers/jellyfin-*`
 - Window trackers: `src/window-trackers/`
-- Stats app: `stats/`
+- Stats HTTP app: `src/core/services/stats-server.ts`, with route groups and shared route support
+  in `src/core/services/stats-server/`
+- Stats SPA: `stats/`
 - Public docs site: `docs-site/`
 
 ## Shared Contract Entry Points
 
+Automatic mpv keyboard discovery uses the `get-mpv-input-bindings` IPC request and
+`MpvInputBindingsSnapshot` in `src/types/session-bindings.ts`.
+`src/main/runtime/mpv-input-bindings.ts` queries the connected player and preserves
+configured keys, including disabled entries. `src/shared/mpv-input-bindings.ts`
+validates discovered keys and translates browser input. The renderer's
+`handlers/mpv-input-forwarding.ts` keeps the session lookup, coalesces asynchronous
+refreshes, and releases held keys on blur or disposal. Discovered `WHEEL_*` bindings forward
+as `keypress <key> <notches>` (Chromium reports 120 px per notch), which matches mpv's own
+precise-scroll scaling. `MBTN_*` buttons forward as held `keydown`/`keyup` when mpv binds the
+button or its `_DBL` variant, so mpv synthesizes double-clicks itself. Configured keybindings and
+the built-in right-click pause run first. Forwarding is the only way pointer input reaches mpv on
+Hyprland, where the overlay cannot be made click-through. `handlers/keyboard.ts` runs
+this fallback after SubMiner controls and refreshes on startup, a delayed startup
+pass, focus, binding reload, and the `mpv-input-bindings:changed` event. Main sends
+that event from `session-bindings-runtime.ts` when mpv's discovered key set changes,
+including the first discovery after connecting, because the overlay often loads
+before mpv connects and the compiled session bindings may not change. Discovery does not enter compiled session bindings,
+the plugin artifact, persistent config, or session help.
+
+The subtitle sidebar consumes parsed cues through `SubtitleSidebarSnapshot`. Its `sourceKey`
+identifies the media and subtitle source so renderer selections are invalidated on source changes,
+including changes whose cue text and timings are identical. Native selection and clean clipboard
+serialization live in `src/renderer/modals/subtitle-sidebar-selection.ts`. Electron lets standard
+Copy input reach the renderer, where sidebar selection takes priority over the live-subtitle binding.
+The preload bridge writes selections through Electron's clipboard API so copying does not depend
+on Chromium document focus or require activating the overlay window.
+
 - Config + app-state contracts: `src/types/config.ts`
 - Subtitle/token/media annotation contracts: `src/types/subtitle.ts`
 - Runtime/window/controller/Electron bridge contracts: `src/types/runtime.ts`
@@ -39,6 +77,7 @@ Read when: you need to find the owner module for a behavior or test surface
 - Runtime-option contracts: `src/types/runtime-options.ts`
 - Settings UI contracts: `src/types/settings.ts`
 - Session-binding contracts: `src/types/session-bindings.ts`
+- Stats HTTP wire contracts: `src/types/stats-wire.ts`, `src/types/stats-http-contract.ts`
 - Compatibility-only barrel: `src/types.ts`
 
 ## Ownership Heuristics

docs/architecture/layering.md

@@ -23,7 +23,7 @@ Renderer, launcher, plugin, and stats each keep their own local layering and sho
 - Keep side effects explicit and close to composition boundaries.
 - Put reusable business logic in focused services, not in top-level lifecycle files.
 - Keep renderer concerns in `src/renderer/`; avoid leaking DOM behavior into main-process code.
-- Treat `launcher/*.ts` as source of truth for the launcher. Never hand-edit `dist/launcher/subminer`.
+- Treat `launcher/*.ts` and the runtime bootstrap generators as source of truth for launcher behavior. `scripts/build-launcher.ts` creates `dist/launcher`; never hand-edit those artifacts.
 
 ## Smells
 

docs/architecture/stats-trends-data-flow.md

@@ -23,7 +23,9 @@ Trend charts now consume one chart-oriented backend payload from `/api/stats/tre
   - lookup rate trends
   - watch-time by day-of-week/hour
 - vocabulary-backed:
-  - new-words trend
+  - new-words trend reads permanent daily lexical rollups
+  - rollup rows count only vocabulary-visible tokens and normalize mixed legacy timestamp units
+  - a persisted rollup version invalidates stale materializations and triggers an atomic background rebuild
 
 ## Metric Semantics
 
@@ -33,6 +35,10 @@ Trend charts now consume one chart-oriented backend payload from `/api/stats/tre
 
 ## Contract
 
+Stats data crosses the process boundary over HTTP only. Shared JSON models live in `src/types/stats-wire.ts`; endpoint request/response mappings and the client interface live in `src/types/stats-http-contract.ts`. The server and stats client both type-check against those files. `stats/src/types/stats.ts` is a compatibility re-export, not an independent contract copy.
+
+The stats preload bridge remains limited to native window behavior such as confirmation-dialog layering. Do not add stats data request channels back to Electron IPC.
+
 The stats UI should treat the trends payload as chart-ready data. Presentation-only work in the client is fine, but rebuilding the main trend datasets from raw sessions should stay out of the render path.
 
 For session detail timelines, omitting `limit` now means "return the full retained session telemetry/history". Explicit `limit` remains available for bounded callers, but the default stats UI path should not trim long sessions to the newest 200 samples.

docs/architecture/subtitle-overlay-priming.md

@@ -3,7 +3,7 @@
 # Subtitle Overlay Priming
 
 Status: active
-Last verified: 2026-06-01
+Last verified: 2026-08-19
 Owner: Kyle Yasuda
 Read when: debugging subtitle state or blank Linux/X11 overlay windows when the visible overlay is shown or recreated
 
@@ -47,20 +47,128 @@ subtitles do not draw.
    `emitSubtitle(payload)` and `refreshCurrentSubtitle(text)`, then prime secondary subtitles.
 6. Tokenization cache hit: call `consumeCachedSubtitle(text)`, `onSubtitleChange(text)`, and
    `emitSubtitle(cachedPayload)`, then prime secondary subtitles.
-7. Cache miss: call `refreshCurrentSubtitle(text)` and let normal tokenization emit the final
-   payload.
+7. Cache miss: call `refreshCurrentSubtitle(text)`. Normal processing emits a plain payload
+   synchronously, then replaces it with the tokenized payload when ready.
 
-In `src/main.ts`, both `onSubtitleChange` and `refreshCurrentSubtitle` pause
-`subtitlePrefetchService`, notify it with `onSeek(lastObservedTimePos)`, and then call the matching
-`subtitleProcessingController` method. This gives the visible overlay priority over background
-prefetch work and re-centers prefetch around the live playback time.
+Both `onSubtitleChange` and `refreshCurrentSubtitle` pause `subtitlePrefetchService` and then call
+the matching `subtitleProcessingController` method, giving the visible overlay priority over
+background prefetch work. Prefetch is not re-centered here: restarting the run per line
+(`onSeek`) discarded the in-flight tokenization every time the subtitle changed, so only real
+seeks restart it (see `onTimePosUpdate` in `src/main.ts`).
+
+On an uncached autoplay prime the raw payload is emitted here and reported to the controller with
+`notePlainSubtitleEmitted`, so the controller skips its own plain emit for that line and the
+overlay receives one plain payload followed by the annotated one.
+
+The pause is released by the controller's `onProcessingSettled` callback, which fires once it has
+no work left. Emits do not release it: the first emit for an uncached line is the plain payload
+that precedes tokenization, and a run can finish without emitting at all (a suppressed duplicate,
+a failed tokenization). Both controller methods return whether processing is now pending, and the
+caller resumes immediately when it is not — a repeated subtitle schedules no work, so no settle is
+coming and prefetching would otherwise idle for the rest of the cue.
+
+## Live Cue Delivery
+
+- Primary live text first resolves recovered canonical ASS animations. Otherwise, when
+  every live mpv line matches an active parsed cue, it uses the parsed cue text so exact
+  full-span style layers appear once instead of repeating for fill, border, blur, shadow,
+  or equivalent whitespace variants. Any unmatched live line keeps the complete live
+  stack, preserving dialogue or signs that overlap a lyric.
+- A tokenization cache miss emits the plain cue synchronously. Tokenization remains serialized so
+  live work does not contend for Yomitan state.
+- The initial `time-pos`, explicit renderer seeks, and later seek-like jumps reprocess mpv's
+  current raw `sub-text` after the new playback time is stored. Explicit intent matters because
+  adjacent subtitle jumps can be shorter than the general seek-distance threshold. This corrects
+  ASS cleanup when mpv delivered the destination subtitle before the destination timestamp.
+- Renderer `sub-seek` commands use the active parsed cue list when available. Simultaneous cues
+  share one boundary, overlapping lyrics advance from the latest active boundary, and mpv's native
+  command remains the fallback when no parsed destination exists. This prevents generated karaoke
+  frames from consuming next/previous subtitle presses.
+- Subtitle sidebar selections seek past the preceding sanitized cue's overlapping exit span when
+  the selected cue has enough time remaining. This keeps direct row selection on the requested
+  karaoke line while clamping the seek inside that cue.
+- If startup paints raw text before embedded ASS parsing finishes, parsed cue arrival may replace
+  that provisional line. The one-prime-per-media guard still suppresses identical repeats.
+- If a newer cue arrives while an older line is still tokenizing, the newer plain cue or empty
+  clear payload is emitted immediately. The older tokenization result is dropped before it can
+  replace the current cue.
+- The current cue upgrades in place when its tokens and annotations are ready. This can reflow text
+  or character images, but cue visibility does not wait for that work.
+
+## Secondary Subtitle Flow
+
+- `secondary-sub-text` remains the immediate fallback, so unreadable subtitle sources, remote URLs,
+  and still-extracting embedded tracks appear without waiting for file resolution. Embedded-track
+  extraction runs for local and network-mounted files alike (demuxing reads the whole container,
+  about 10 seconds per GB on gigabit, under a generous timeout); only true remote URLs skip it,
+  having no on-disk container to demux.
+- The live fallback also suppresses per-glyph typesetting walls: when many simultaneous
+  one-glyph lines are present (generated karaoke lettering flattened into live text), those
+  lines and their short syllable companions are dropped while concurrent dialogue lines stay.
+  This keeps the overlay clean while extraction is still in flight and for sources that never
+  produce parsed cues.
+- Parsed secondary text and the live fallback remove exact repeated lines at any length. A
+  flattened-line identity also removes long dialogue/sign repetitions that differ only in
+  whitespace or terminal punctuation, while distinct simultaneous short lines remain separate.
+- `secondary-subtitle-track.ts` resolves `secondary-sid` against mpv's track list. External tracks
+  are read directly; supported embedded text tracks are extracted through the same ffmpeg-backed
+  source resolver used by primary subtitle prefetching.
+- The selected source is parsed with `parseSubtitleCues()`, including metadata-aware ASS duplicate
+  and animation collapse. Playback `time-pos` selects the active parsed cue after applying
+  `secondary-sub-delay`.
+- Fragment reconstruction marks tall multi-row positioned parts as a grid only when they read
+  like tiling: a couple of texts repeated across many fragments, the same text re-shown at one
+  spot over time (countdown/animation frames), or scattered single glyphs. Secondary text omits
+  those grids instead of flattening a translated table or schedule into one synthetic line.
+  Wrapped lyric rows, CC-style dialogue blocks, and reconstructed single-line karaoke remain
+  eligible for display.
+- The resolved text is stored in `mpvClient.currentSecondarySubText` before it is broadcast. The
+  overlay, mining, timing tracker, and immersion statistics therefore consume the same secondary
+  text when a readable source is available.
+- Simultaneous parsed cues use whitespace-insensitive identity, so ASS layers that vary only
+  between ordinary, hard, or ideographic spaces appear once.
+- Simultaneous ASS lines are flattened in top-to-bottom positioned order, falling back to their
+  authored source order when no usable position exists.
+- Half-size kana positioned directly above a same-timed kanji caption is treated as ASS
+  furigana. The parser omits it from published cues but retains hidden matching metadata so
+  mpv's raw live text can be reconciled without displaying or mining the reading. The
+  timing tracker (clipboard copy, recent-line mining) and immersion recorders run the same
+  reconciliation on the `sub-start`/`sub-end` sample, so they record what the overlay shows.
+- Broadcast-caption rows that spell one utterance across several same-timed positioned events
+  (same style, layer, and vertical band, stacked at most two text rows apart) are joined into
+  one cue with a single line break, so `preserveLineBreaks` treats them like an authored `\N`,
+  and the recorders above see the whole sentence. A row continues the one above it when that row
+  is a bare speaker label, ends without terminal punctuation, or leaves a ≪…≫ / ⸨…⸩ span open; a
+  lower row that opens its own label or span always starts a new cue, which keeps two speakers
+  sharing the screen on separate lines. The pass runs only on scripts that read as broadcast
+  captions (a meaningful share of events carry speaker labels or ≪…≫ / ⸨…⸩ spans) and only on
+  rows containing Japanese, because fansub typesetting stacks positioned rows for signs, chat
+  bubbles, and headlines where that punctuation convention does not hold.
+- Fragment-only ASS karaoke is reconstructed per style before publication. Explicit spaces
+  survive concatenation. Latin fragment typesetting with no literal spaces also recovers word
+  boundaries represented only by materially larger horizontal `\pos` or `\move` gaps within that
+  line. Unpositioned fragments stay compact instead of gaining guessed spaces between syllables.
+  Short runs qualify only when overlapping positioned events also show changing overrides or
+  repeated layer copies; an English or romaji style name alone never turns ordinary dialogue into
+  a lyric.
+- Recovered canonical ASS text remains active for the generated animation envelope. For
+  reconstructed lyric styles, the longest-lived active line wins over brief entrance and exit
+  fragments from the same style.
+- Media and `secondary-sid` changes clear the previous parsed state before refreshing the source;
+  track-list changes refresh without discarding an unchanged source. Observed
+  `secondary-sub-delay` changes retime the active parsed cue without rereading the file. If loading,
+  extraction, or parsing fails, the controller returns to live mpv text and the renderer's
+  conservative short stack heuristic remains the final display fallback.
 
 ## Emitted State
 
-- `emitSubtitle(payload)` maps to `emitSubtitlePayload(payload)`, which sends the normal
-  annotated subtitle payload to overlay windows and subtitle websocket listeners.
-- Secondary priming reads mpv `secondary-sub-text`, stores it in
-  `mpvClient.currentSecondarySubText`, and broadcasts `secondary-subtitle:set` to overlay windows.
+- `emitSubtitle(payload)` maps to `emitSubtitlePayload(payload)`. Overlay windows and annotation
+  websocket listeners receive both the immediate plain cue and its later annotation upgrade.
+- The basic subtitle websocket receives the immediate plain cue only. Because its serialized
+  payload discards annotations, the later upgrade would be an identical duplicate and is skipped
+  when text and cue timing match.
+- Secondary priming reads mpv `secondary-sub-text` and routes it through the secondary track
+  controller. A parsed active cue replaces the live text when the selected source is readable.
 - If secondary `requestProperty` fails, the primary flow stays complete and only a debug line is
   written.
 
@@ -79,9 +187,19 @@ prefetch work and re-centers prefetch around the live playback time.
   window so readiness can still arrive before fallback resumes playback.
 - If mpv is already on a subtitle, SubMiner still prefers the resolved current subtitle payload and
   waits for a fresh measured subtitle rectangle before signaling readiness.
+- If the startup subtitle has no cached annotations yet, autoplay priming emits a raw first-paint
+  subtitle payload before background tokenization. The tokenized payload replaces it when ready, but
+  the visible overlay can paint and measure the line before the mpv startup gate resumes playback.
+- If startup `sub-text` is temporarily empty, autoplay priming refreshes the active subtitle source
+  and then awaits cue-based priming before synthetic warm readiness can proceed. A parsed current or
+  imminent cue is treated as the startup subtitle so the visible overlay can paint and measure it
+  before playback resumes.
 - If mpv is before the first subtitle, SubMiner sends a synthetic warm readiness payload after
   tokenization warmup and visible overlay content-ready. This releases playback without waiting for
   a later subtitle event that cannot happen while mpv is paused.
+- After a synthetic warm readiness release, SubMiner briefly polls/refreshes the current subtitle
+  again. This covers Linux/mpv startup cases where `sub-text` is still empty while paused but becomes
+  available right after playback resumes, without waiting for the next subtitle property change.
 
 ## Linux/X11 Window Shape
 
@@ -94,7 +212,20 @@ prefetch work and re-centers prefetch around the live playback time.
   path, empty or stale bounding shapes produced invisible or clipped subtitles even though the
   overlay window remained mapped above mpv.
 - Pointer pass-through should continue to use `setIgnoreMouseEvents(true, { forward: true })` and
-  the Linux cursor-poll fallback, not bounding-shape clipping.
+  the Linux cursor-poll fallback, not bounding-shape clipping. Note that on Windows click-through
+  must go through `applyOverlayClickThrough()` (`src/core/services/overlay-click-through.ts`),
+  which omits `forward: true` there: Electron implements forwarding with a global low-level mouse
+  hook that lags mouse input system-wide whenever the main thread stalls; the Windows cursor poll
+  handles overlay wake-up instead.
+- Visible-overlay show/reset marks Linux pointer passthrough state dirty even when the logical
+  interaction state is already inactive. The next cursor-poll tick must still reapply
+  `setIgnoreMouseEvents(true, { forward: true })`; otherwise a newly shown Electron overlay can keep
+  full-window input capture and block both mpv and overlay controls before the first subtitle
+  measurement.
+- Visible-overlay show also starts a short Linux input grace before the first content measurement.
+  Native Wayland surfaces can become inert while `setIgnoreMouseEvents(true)` is active; keeping the
+  overlay interactive during this startup gap lets notifications and overlay mouse bindings work
+  until subtitle/sidebar/notification rectangles are reported.
 
 ## Config And Migration
 

docs/knowledge-base/catalog.md

@@ -3,7 +3,7 @@
 # Documentation Catalog
 
 Status: active  
-Last verified: 2026-05-23  
+Last verified: 2026-08-13
 Owner: Kyle Yasuda  
 Read when: finding internal docs or checking verification status
 
@@ -17,10 +17,10 @@ Read when: finding internal docs or checking verification status
 | KB rules | `docs/knowledge-base/README.md` | active | 2026-05-23 | maintenance policy |
 | Core beliefs | `docs/knowledge-base/core-beliefs.md` | active | 2026-03-13 | agent-first principles |
 | Quality scorecard | `docs/knowledge-base/quality.md` | active | 2026-03-13 | quality grades and gaps |
-| Workflow index | `docs/workflow/README.md` | active | 2026-05-23 | execution map |
+| Workflow index | `docs/workflow/README.md` | active | 2026-08-13 | execution map |
 | Planning guide | `docs/workflow/planning.md` | active | 2026-05-23 | lightweight vs execution plans |
-| Agent plugins | `docs/workflow/agent-plugins.md` | active | 2026-05-23 | repo-local agent workflow plugin ownership |
-| Verification guide | `docs/workflow/verification.md` | active | 2026-05-23 | maintained verification lanes |
+| Agent skills | `docs/workflow/agent-skills.md` | active | 2026-08-23 | repo-local workflow skill ownership |
+| Verification guide | `docs/workflow/verification.md` | active | 2026-08-13 | maintained verification lanes |
 | Release guide | `docs/RELEASING.md` | active | 2026-05-23 | release checklist |
 
 ## Update Rules

docs/plans/2026-06-06-early-managed-overlay-startup-design.md

@@ -1,29 +0,0 @@
-<!-- read_when: changing managed mpv startup, pause-until-ready, or visible overlay boot ordering -->
-
-# Early Managed Overlay Startup Design
-
-Status: approved
-Date: 2026-06-06
-
-## Problem
-
-Managed mpv startup can pause playback immediately, then leave SubMiner's tray and visible overlay
-unavailable until Yomitan/tokenization warmups finish. Startup notifications therefore miss the
-overlay surface and fall back to non-overlay status paths.
-
-## Chosen Approach
-
-For cold `--start --background --managed-playback` launches, handle initial args before waiting for
-the deferred overlay warmup. That lets the tray and visible overlay shell initialize immediately
-while the existing tokenization warmups continue in the background.
-
-The mpv plugin pause gate stays armed. Playback release still waits for SubMiner's autoplay-ready
-signal, which is emitted only after tokenization warmup and visible-overlay readiness. Existing
-second-instance attach behavior remains unchanged: when the launcher finds an already-running
-background app, it sends the same control command to that process and reuses its warmups/tokenizer.
-
-## Checks
-
-- Add a startup ordering regression test for managed background playback.
-- Keep the existing deferred startup ordering for non-managed launches.
-- Run the startup/runtime test slice plus SubMiner verification lane.

docs/plans/2026-06-09-macos-notification-hover-design.md

@@ -1,27 +0,0 @@
-<!-- read_when: changing overlay notification hover, macOS mouse passthrough, or notification actions -->
-
-# macOS Notification Hover Stability Design
-
-Status: approved
-Date: 2026-06-09
-
-## Problem
-
-On macOS, hovering a character dictionary build notification can make the card flicker and slide as
-if it is hiding, then snap back. The likely trigger is the notification stack changing the overlay
-window's mouse-passthrough state for a progress card that has no user action.
-
-## Chosen Approach
-
-Keep non-action overlay notifications visually stable and click-through on hover. Only notifications
-with explicit actions should request interactive overlay input. The notification history panel keeps
-its existing interactive behavior.
-
-This avoids a macOS mouseenter/mouseleave passthrough loop for passive progress cards while
-preserving clickable notification actions.
-
-## Checks
-
-- Add a renderer regression test for passive notification hover.
-- Keep action-bearing notification cards interactive.
-- Run the targeted overlay notification and mouse-ignore tests.