fix(launcher): address review feedback on setup and runtime cleanup

fix(launcher): preserve arguments through Windows command wrappers
feat(launcher): use private Bun for all release launchers
2026-09-10 17:16:20 -07:00 · 2026-09-10 13:32:12 -07:00 · 2026-09-10 13:22:04 -07:00 · 2026-09-10 13:14:16 -07:00 · 2026-09-10 12:22:29 -07:00 · 2026-09-09 12:04:08 -07:00
450 changed files with 41767 additions and 7956 deletions
@@ -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"
-    }
-  ]
-}
@@ -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.
@@ -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" "$@"
@@ -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" "$@"
@@ -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.
@@ -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.
@@ -32,9 +32,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
@@ -195,6 +195,12 @@ jobs:
          bun install
          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

@@ -256,11 +262,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
@@ -274,12 +280,16 @@ jobs:
            config.example.jsonc \
            plugin/subminer \
            plugin/subminer.conf \
-            assets/themes/subminer.rasi
+            assets/themes/subminer.rasi \
+            assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer
+
+      - 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
@@ -296,15 +306,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

@@ -315,10 +332,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
@@ -326,27 +345,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
@@ -7,6 +7,31 @@ 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 POSIX launcher bootstrap
+        run: bun test src/main/runtime/posix-launcher-bootstrap.test.ts
+
  quality-gate:
    runs-on: ubuntu-latest
    steps:
@@ -60,8 +85,11 @@ jobs:

      - name: Install Lua
        run: |
-          sudo apt-get update
-          sudo apt-get install -y lua5.4
+          # 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

@@ -107,11 +135,11 @@ jobs:
      - name: Security audit
        run: bun audit --audit-level high

-      - 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
@@ -194,6 +194,12 @@ jobs:
          bun install
          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

@@ -255,11 +261,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
@@ -273,12 +279,16 @@ jobs:
            config.example.jsonc \
            plugin/subminer \
            plugin/subminer.conf \
-            assets/themes/subminer.rasi
+            assets/themes/subminer.rasi \
+            assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer
+
+      - 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
@@ -295,33 +305,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

@@ -332,10 +349,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
@@ -344,7 +363,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:
@@ -420,9 +439,10 @@ jobs:
        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 \
@@ -432,15 +452,17 @@ jobs:

      - name: Update AUR packaging metadata
        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
        run: |
          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"
@@ -450,6 +472,7 @@ jobs:
        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
@@ -459,7 +482,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
@@ -49,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
@@ -56,6 +57,8 @@ 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
@@ -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`
@@ -44,13 +45,15 @@ Start here, then leave this file.
 - Runtime-compat / dist-sensitive: `bun run test:runtime:compat`
 - Stats dashboard UI (`stats/`): `bun run test:stats`
 - Build/release scripts (`scripts/**`): `bun run test:scripts`
- Docs-only: `bun run docs:test`, then `bun run docs:build`
+- 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`
@@ -71,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.
@@ -1,5 +1,92 @@
 # Changelog

+## 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
@@ -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"
@@ -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>

@@ -191,7 +191,9 @@ wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppI
 && chmod +x ~/.local/bin/SubMiner.AppImage
 ```

-The AppImage is all you need. The optional `subminer` command-line launcher runs on [Bun](https://bun.sh), and first-run setup can install both for you. To grab it manually instead, install Bun first, then:
+The AppImage is all you need. First-run setup can install the optional `subminer` command-line launcher. Every current launcher uses Bun included with the app, so you do not need Bun installed or on `PATH`.
+
+You can also download the launcher wrapper directly:

 ```bash
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer \
@@ -212,6 +214,8 @@ Download the latest DMG from [GitHub Releases](https://github.com/ksyasuda/SubMi

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

+For terminal use, download `subminer.cmd`. It locates the installed app and uses its private Bun runtime.
+
 </details>

 <details>
@@ -223,14 +227,14 @@ 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.
+Run the installed app and the first-run setup wizard will guide you through importing Yomitan dictionaries and optionally installing the `subminer` command-line launcher. Setup records a custom app location when needed, and the wrapper runs with the app's private Bun runtime.

 ```bash
 # Linux
-subminer app --setup
+~/.local/bin/SubMiner.AppImage --setup

-# macOS — open SubMiner.app, or:
-subminer app --setup
+# macOS
+open -a SubMiner --args --setup
 ```

 On **Windows**, just run `SubMiner.exe` and the setup will open automatically on first launch.
@@ -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;
@@ -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"
+}
@@ -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"]
+    }
+  ]
+}
@@ -34,14 +34,14 @@
    "@discordjs/rest@2.6.1": "patches/@discordjs%2Frest@2.6.1.patch",
  },
  "overrides": {
-    "@xmldom/xmldom": "0.8.13",
+    "@xmldom/xmldom": "0.8.15",
    "app-builder-lib": "26.15.3",
    "brace-expansion": "5.0.9",
    "electron-builder-squirrel-windows": "26.15.3",
-    "fast-uri": "3.1.5",
+    "fast-uri": "3.1.6",
    "form-data": "4.0.6",
    "ip-address": "10.2.0",
-    "js-yaml": "4.3.1",
+    "js-yaml": "4.3.2",
    "lodash": "4.18.0",
    "minimatch": "10.2.5",
    "picomatch": "4.0.4",
@@ -226,7 +226,7 @@

    "@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.13", "", {}, "sha512-KRYzxepc14G/CEpEGc3Yn+JKaAeT63smlDr+vjB8jRfgTBBI9wRj/nkQEO+ucV8p8I9bfKLWp37uHgFrbntPvw=="],
+    "@xmldom/xmldom": ["@xmldom/xmldom@0.8.15", "", {}, "sha512-/5NV/vDALVFDXgLmfsy9TRCBlKwO2LNBFzpzvb9iIj+jR+eSc6DLYYvVOdivT/jm7MtU6TebYuRmzEOI7w40UA=="],

    "abbrev": ["abbrev@4.0.0", "", {}, "sha512-a1wflyaL0tHtJSmLSOVybYhy22vRih4eduhhrkcjgrWGnRfrZtovJ2FRjxuTtkkj47O/baf0R86QU5OuYpz8fA=="],

@@ -406,7 +406,7 @@

    "fast-levenshtein": ["fast-levenshtein@2.0.6", "", {}, "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw=="],

-    "fast-uri": ["fast-uri@3.1.5", "", {}, "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw=="],
+    "fast-uri": ["fast-uri@3.1.6", "", {}, "sha512-7Ical1vFEMr0onbVzEDIreM22I4khW+fzyQPwvAFWBp1iwdshSZRsL4jjRvPG9JP1uiqMHRto+YU6R2/CzDz5Q=="],

    "fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],

@@ -498,7 +498,7 @@

    "jiti": ["jiti@2.6.1", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ=="],

-    "js-yaml": ["js-yaml@4.3.1", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ=="],
+    "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=="],

@@ -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 short top-level items with one nested bullet per distinct change, instead of packing a release's worth of detail into a single paragraph bullet. An item with only one thing to say stays inline on the top-level bullet. Release notes and prerelease notes additionally cover user benefit and any useful action note in their nested bullets.
 - `internal` fragments stay in `CHANGELOG.md` (inside a collapsed `<details>` block) but are dropped from the GitHub release notes entirely.
 - The polished `CHANGELOG.md` and `release/release-notes.md` are committed and reviewed before tagging — edit the Markdown by hand if Claude misses something.

 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
@@ -0,0 +1,4 @@
+type: docs
+area: launcher
+
+- Documented private-runtime launcher installation, custom app locations, legacy launcher migration, and package-managed updates.
@@ -0,0 +1,4 @@
+type: changed
+area: launcher
+
+- Made every installed and downloadable launcher use the Bun runtime included with SubMiner. Added a Windows `subminer.cmd` download, persistent private runtime caches for Linux and Windows, and migration for recognized legacy launchers.
@@ -0,0 +1,4 @@
+type: fixed
+area: startup
+
+- Fixed first launch exiting on macOS when the SubMiner config directory did not yet exist by creating it before acquiring the startup lock.
@@ -0,0 +1,4 @@
+type: added
+area: overlay
+
+- Select dialogue across subtitle sidebar rows and copy it without timestamps using Ctrl/Cmd+C or the Copy button. Selection keeps the excerpt in view during playback and does not seek or require mining a card.
@@ -523,7 +523,7 @@
  // ==========================================
  // AnkiConnect Integration
  // Automatic Anki updates and media generation options.
-  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/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.
  // ==========================================
@@ -569,6 +569,7 @@
      "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.
@@ -606,6 +607,11 @@
      "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.
+    "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.
@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { extname, join, posix, resolve, sep } from 'node:path';
 import type { DefaultTheme, HeadConfig, TransformContext, UserConfig } from 'vitepress';
@@ -26,6 +27,9 @@ 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.18.0';
@@ -82,15 +86,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 +113,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' }]);
  }

@@ -287,6 +296,39 @@ const versionItems = [
  })),
 ];

+function sitemapUrlToPage(url: string): string {
+  const route = url.replace(/\.html$/, '').replace(/^\/+|\/+$/g, '');
+  return route ? `${route}.md` : 'index.md';
+}
+
+// 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',
+  });
+
+  return (result.status === 0 && result.stdout.trim()) || undefined;
+}
+
+// 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) }));
+      },
+    }
+  : undefined;
+
 const nav: DefaultTheme.NavItem[] = [
  { text: 'Home', link: '/' },
  { text: 'Get Started', link: '/installation' },
@@ -306,7 +348,6 @@ const sidebar: DefaultTheme.SidebarItem[] = [
      { text: 'Usage', link: '/usage' },
      { text: 'Mining Workflow', link: '/mining-workflow' },
      { text: 'Launcher Script', link: '/launcher-script' },
-      { text: 'Feature Demos', link: '/demos' },
    ],
  },
  {
@@ -420,14 +461,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'],
@@ -1,4 +1,4 @@
-# SubMiner Docs
+# SubMiner docs

 In-repo VitePress documentation source for SubMiner.

@@ -38,8 +38,10 @@ 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.
 - 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`, and the generated `_headers` file repeats that as an `X-Robots-Tag`. They stay crawlable so their links still resolve, but ~30 archived copies of every page would otherwise consume the crawl budget the current docs need. Only the root build emits `sitemap.xml`, and its `<lastmod>` dates come from `git log` against the tracked checkout at the released tag, because the build renders from an untracked snapshot that VitePress cannot date itself.
+
 Keep Cloudflare Git auto-deploy disabled. The production deploy is `.github/workflows/docs-pages.yml`, which uploads `.tmp/docs-versioned-site` with `--branch main` so tag-triggered runs update Production instead of creating preview deployments.
@@ -1,10 +1,10 @@
-# 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.
+SubMiner syncs your watch progress to [AniList](https://anilist.co). Finish an episode and it reads the title and episode number off the filename, finds the matching AniList entry, and updates your progress through the GraphQL API. A failed update retries in the background with exponential backoff.

-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.
+The same AniList data feeds [cover art](#cover-art) in the stats dashboard and the [Character Dictionary](/character-dictionary) for in-overlay name lookup.

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

 ## Setup

@@ -32,18 +32,18 @@ If the embedded auth UI fails to render, SubMiner opens the authorize URL in you
 You can also set `anilist.accessToken` directly in config to skip the setup flow entirely. When blank, SubMiner uses the locally stored encrypted token.
 :::

-## How Tracking Works
+## How tracking works

-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.
+SubMiner watches playback and pushes an AniList progress update once an episode counts as watched. That means at least 85% of its duration, and at least 10 minutes either way.

 The update flow:

-1. **Title detection** -- SubMiner extracts the anime title, season, and episode number from the media filename and path. Season folders such as `Season 2` are treated as a strong season signal. SubMiner tries [`guessit`](https://github.com/guessit-io/guessit) first for accurate parsing, then falls back to an internal filename parser if guessit is unavailable.
-2. **AniList search** -- The base title (with any `Season N` / `SN` marker stripped) is searched against the AniList GraphQL API, and SubMiner picks the best match by comparing titles (romaji, English, native, synonyms) and filtering by episode count. AniList has no notion of numbered seasons -- sequels are separate entries with their own titles (`Zoku`, `Kan`, `2nd Season`), so searching `<title> Season 3` finds nothing. For season 2 and later, SubMiner instead walks `SEQUEL` relations from the season 1 entry, preferring the TV line, and falls back to ordering the franchise's TV entries by air date when the relation chain is incomplete. If neither locates the season, SubMiner **skips the update** rather than writing progress to the season 1 entry, and tells you to pin the right entry with a [character dictionary override](/character-dictionary#correcting-anilist-matches).
-3. **Progress check** -- SubMiner fetches your current list entry for the matched media. The media must already be in Planning or Watching; otherwise SubMiner shows an MPV message explaining that the update is not possible. If your recorded progress already meets or exceeds the detected episode, the update is skipped.
-4. **Mutation** -- A `SaveMediaListEntry` mutation sets the new progress and marks the entry as `CURRENT`, or `COMPLETED` when the watched episode is the final episode of the season (the "already at this progress" skip is bypassed for the final episode so completion still lands).
+1. **Title detection** - SubMiner extracts the anime title, season, and episode number from the media filename and path. Season folders such as `Season 2` are treated as a strong season signal. SubMiner tries [`guessit`](https://github.com/guessit-io/guessit) first for accurate parsing, then falls back to an internal filename parser if guessit is unavailable.
+2. **AniList search** - The base title (with any `Season N` / `SN` marker stripped) is searched against the AniList GraphQL API, and SubMiner picks the best match by comparing titles (romaji, English, native, synonyms) and filtering by episode count. AniList has no notion of numbered seasons - sequels are separate entries with their own titles (`Zoku`, `Kan`, `2nd Season`), so searching `<title> Season 3` finds nothing. For season 2 and later, SubMiner instead walks `SEQUEL` relations from the season 1 entry, preferring the TV line, and falls back to ordering the franchise's TV entries by air date when the relation chain is incomplete. If neither locates the season, SubMiner **skips the update** rather than writing progress to the season 1 entry, and tells you to pin the right entry with a [character dictionary override](/character-dictionary#correcting-anilist-matches).
+3. **Progress check** - SubMiner fetches your current list entry for the matched media. The media must already be in Planning or Watching; otherwise SubMiner shows an MPV message explaining that the update is not possible. If your recorded progress already meets or exceeds the detected episode, the update is skipped.
+4. **Mutation** - A `SaveMediaListEntry` mutation sets the new progress and marks the entry as `CURRENT`, or `COMPLETED` when the watched episode is the final episode of the season (the "already at this progress" skip is bypassed for the final episode so completion still lands).

-## Update Queue and Retry
+## Update queue and retry

 Failed AniList updates are persisted to a retry queue on disk and retried with exponential backoff.

@@ -58,7 +58,7 @@ After 8 failed attempts, the update is moved to a dead-letter queue and no longe

 Use `--anilist-retry-queue` to manually process one ready item from the queue.

-## Cover Art
+## Cover art

 SubMiner fetches cover art from AniList for display in the stats dashboard. When a new video starts playing, the cover art fetcher:

@@ -71,11 +71,11 @@ A no-match result is cached for 5 minutes before SubMiner retries, preventing re

 If the automatic match is wrong, use **Change AniList Entry** on a title in the stats Library. Relinking rewrites the cached art for every episode of that title, and both the detail view and the Library grid pick up the new cover right away: the grid refetches after a relink, and cover responses carry an ETag and are revalidated on each request instead of being cached for a day.

-## Rate Limiting
+## 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
+## Configuration reference

 ```jsonc
 {
@@ -107,7 +107,7 @@ All AniList API calls go through a shared rate limiter that enforces a sliding w

 There is no `characterDictionary.enabled` key: character dictionary sync is enabled by `subtitleStyle.nameMatchEnabled`. See the [Character Dictionary](/character-dictionary) page for full details on the character dictionary feature, including name generation, matching, auto-sync lifecycle, and dictionary entry format.

-## CLI Commands
+## CLI commands

 | Command                 | Description                                                   |
 | ----------------------- | ------------------------------------------------------------- |
@@ -124,10 +124,10 @@ There is no `characterDictionary.enabled` key: character dictionary sync is enab
 - **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.
+- **Encryption unavailable on Linux:** If you see warnings about safeStorage, try `--password-store=basic_text` as a workaround, or start your desktop keyring (gnome-keyring, KWallet).

 ## Related

- [Character Dictionary](/character-dictionary) -- AniList-powered character name dictionary for Yomitan
- [Configuration Reference](/configuration) -- full config options
- [Jellyfin Integration](/jellyfin-integration) -- media server integration
+- [Character Dictionary](/character-dictionary) - AniList-powered character name dictionary for Yomitan
+- [Configuration Reference](/configuration) - full config options
+- [Jellyfin Integration](/jellyfin-integration) - media server integration
@@ -1,8 +1,8 @@
-# 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.
+SubMiner looks up anime intro timings from [AniSkip](https://aniskip.com) so you can jump past the OP with one key.

-Intro detection runs in the SubMiner app over the mpv IPC socket. It 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.
+Intro detection runs in the SubMiner app over the mpv IPC socket. It works whenever the overlay is connected to mpv, not only at launch, and covers every local file loaded during the session including playlist advances.

 ## Setup

@@ -25,9 +25,9 @@ For best title and episode detection, install [`guessit`](https://github.com/gue
 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.
+Without `guessit`, SubMiner falls back to its own filename parser. That handles the usual release naming, but unusual formats slip past it.

-## How It Works
+## How it works

 On each local file load:

@@ -39,15 +39,15 @@ On each local file load:

 When a custom key (other than `TAB` or `y-k`) is configured, the legacy `y-k` chord is also bound as a fallback skip trigger.

-Results are cached per file for the app session; only definitive "no intro found" results are cached, so transient lookup failures are retried on the next file load. Reload detection is also handled: if mpv reloads the same file, SubMiner re-applies the chapter markers without a new API lookup.
+Results are cached per file for the app session. Only a definitive "no intro found" is cached, so a failed lookup gets retried on the next load rather than sticking. If mpv reloads the same file, SubMiner re-applies the chapter markers without hitting the API again.

 ## Triggering from mpv

-You can trigger AniSkip actions from mpv script-messages:
+AniSkip actions are also reachable from mpv script-messages:

 | Command | Effect |
 | ------- | ------ |
 | `script-message subminer-skip-intro` | Skip to the intro end immediately (same as pressing the key) |
 | `script-message subminer-aniskip-refresh` | Force a fresh lookup for the current file, discarding any cached result |

-These are handled by the SubMiner app over the IPC socket.
+The SubMiner app handles both over the IPC socket.
@@ -1,4 +1,4 @@
-# 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.
@@ -19,28 +19,27 @@ This project is built primarily for [Kiku](https://kiku.youyoumu.my.id/) and [La

 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.

-## Auto-Enrichment Transport
+## Auto-enrichment transport

-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 you add a word via Yomitan, SubMiner detects the new card and fills in the sentence, audio, and image fields automatically. Two detection methods are available:

-**Proxy mode** (default) - SubMiner runs a local _proxy_: a small middleman server that sits between Yomitan and Anki. Yomitan sends new cards to SubMiner, SubMiner enriches them, then passes them along to Anki. This makes enrichment instant.
+**Proxy mode** (default) - SubMiner runs a small local server between Yomitan and Anki. Yomitan sends the new card to SubMiner, SubMiner fills in the media fields, and the finished card goes on to Anki. There is no polling delay.

-**Polling mode** (fallback, when the proxy is disabled) - SubMiner asks AnkiConnect every few seconds whether any new cards were added, then enriches them. Simpler setup, but with a short delay (~3 seconds).
+**Polling mode** (fallback, when the proxy is disabled) - SubMiner asks AnkiConnect every few seconds whether new cards showed up, then fills them in. Less to configure, at the cost of roughly a 3 second delay.

-Use proxy mode if you want immediate enrichment. Use polling mode if your Yomitan instance is external (browser-based) or you prefer minimal configuration.
+Use proxy mode unless your Yomitan runs in a browser rather than the bundled instance, in which case polling is the simpler path.

 In both modes, the enrichment workflow is the same:

 1. Checks if a duplicate expression already exists (for field grouping).
 2. Updates the sentence field with the current subtitle.
 3. Generates and uploads audio and image media.
-4. Fills the translation field from the secondary subtitle or AI.
-5. Writes metadata to the miscInfo field.
+4. Writes metadata to the miscInfo field.

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

-### Proxy Mode Setup (Yomitan / Texthooker)
+### Proxy mode setup (Yomitan / texthooker)

 ```jsonc
 "ankiConnect": {
@@ -83,7 +82,7 @@ In Yomitan, go to Settings → Profile and:

 This is only for non-bundled, external/browser Yomitan or other clients. The bundled profile auto-update logic only targets the active profile when its server is blank or still default.

-### Proxy Troubleshooting (quick checks)
+### Proxy troubleshooting (quick checks)

 If auto-enrichment appears to do nothing:

@@ -107,7 +106,7 @@ curl -sS http://127.0.0.1:8766 \
 - Launcher log: `launcher-YYYY-MM-DD.log`
 - mpv log: `mpv-YYYY-MM-DD.log`

-4. Ensure config JSONC is valid and logging shape is correct:
+4. Check that the config JSONC parses and the logging shape is right:

 ```jsonc
 "logging": {
@@ -117,28 +116,31 @@ curl -sS http://127.0.0.1:8766 \

 `"logging": "debug"` is invalid for current schema and can break reload/start behavior.

-## Field Mapping
+## Field mapping

 SubMiner maps its data to your Anki note fields. Configure these under `ankiConnect.fields`:

 ```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
+    "word": "Expression",        // mined word / expression text
+    "audio": "SentenceAudio",    // sentence audio clip cut from the video
+    "image": "Picture",          // screenshot or animated clip
+    "sentence": "Sentence",      // subtitle text
+    "miscInfo": "MiscInfo"       // metadata (filename, timestamp)
  }
 }
 ```

+`fields.audio` receives the **sentence** audio SubMiner cuts from the video, not word audio. Yomitan writes its own dictionary audio when you mine, so point this at a separate field such as `SentenceAudio` to keep the two apart. The built-in default is still `ExpressionAudio`, which collides with Yomitan on note types that use that field for word audio.
+
 Field names are matched against your Anki note type case-insensitively (an exact match wins, then a lowercase comparison). If a configured field does not exist on the note type, SubMiner skips it without error.

+These mappings always control normal word-card enrichment, including Yomitan proxy/polling updates and manual clipboard updates. Enabling Lapis or Kiku does not replace the configured word-card sentence and audio fields with `Sentence` and `SentenceAudio`. The dedicated sentence-card and audio-card shortcuts still use those Lapis/Kiku field names.
+
 Two related options live alongside `fields`: `ankiConnect.deck` (target deck; empty falls back as described above) and `ankiConnect.tags` (tags added to mined cards, default `["SubMiner"]`; set `[]` to disable tagging). The `miscInfo` content is controlled by `ankiConnect.metadata.pattern` (default `[SubMiner] %f (%t)`; tokens: `%f` filename, `%F` filename with extension, `%t` timestamp, `%T` timestamp with milliseconds, `<br>` newline).

-### Minimal Config
+### Minimal config

 If you only want sentence and audio on your cards:

@@ -147,14 +149,16 @@ If you only want sentence and audio on your cards:
  "enabled": true,
  "fields": {
    "sentence": "Sentence",
-    "audio": "ExpressionAudio"
+    "audio": "SentenceAudio"
  }
 }
 ```

-## Media Generation
+## Media generation

-SubMiner uses FFmpeg to generate audio and image media from the video. FFmpeg must be installed and on `PATH`.
+SubMiner shells out to FFmpeg for audio clips and screenshots, so FFmpeg has to be installed and on `PATH`.
+
+For remote streams such as Jellyfin playback, SubMiner downloads the clip's time window once into a temporary Matroska file (a stream copy, no re-encoding) and reads the timing review waveform, audio preview, audio, and image from that file instead of fetching the stream again for each step. The window covers the clip plus padding, plus the visible timeline in timing review, and grows when you reveal more of the timeline. It is deleted when a different window replaces it, after ten minutes without use, or when SubMiner exits. If the download fails, media generation reads the remote stream directly as before.

 ### Audio

@@ -166,6 +170,7 @@ Audio is extracted from the video file using the subtitle's start and end timest
    "generateAudio": true,
    "normalizeAudio": true,      // normalize generated clip loudness
    "mirrorMpvVolume": true,     // apply the current mpv volume level
+    "reviewTiming": false,       // review and adjust timing before media generation
    "audioPadding": 0,           // optional seconds before and after subtitle timing
    "maxMediaDuration": 30       // cap total duration in seconds
  }
@@ -178,7 +183,27 @@ Output format: MP3 at 44100 Hz. If the video has multiple audio streams, SubMine

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

-### Screenshots (Static)
+Set `media.reviewTiming` to `true` to pause playback and check the clip before its media is generated. It applies to word, sentence, and audio cards.
+
+The review opens on the subtitle range plus your configured audio padding. Subtitles usually hang around after the dialogue has stopped, so once the waveform loads, an untouched clip end pulls back to just after the last speech in the line. The Line end rail still marks the original subtitle timing, Reset puts it back, and a line whose speech runs right through its end is left alone.
+
+**Adjusting the clip.** Drag either edge to trim, drag the middle to slide the whole clip without changing its length, or click anywhere on the waveform to snap the nearer edge there. A focused edge also moves with the arrow keys: 100 ms per press, or 500 ms with Shift. The 100 ms buttons do the same thing. Earlier and Later each reveal two more seconds of timeline without moving the selection.
+
+**Keys.** Space previews the selection with a playhead sweeping the clip. The preview ends when the hidden player has actually played the last sample, so Bluetooth output latency does not clip the tail. Enter confirms and Escape cancels.
+
+**The waveform.** SubMiner reads a center channel when one carries dialogue and falls back to a mono mix otherwise, keeps only the 250 to 3500 Hz speech band, and draws each slice's loudness against the clip's own noise floor. Steady background music flattens out and dialogue stands up, which makes it much easier to tell adjacent lines apart. The mined subtitle appears as a tinted band with labeled line-start and line-end rails. If waveform analysis fails, the timing controls still work.
+
+The range you confirm is used exactly as-is; SubMiner does not add audio padding a second time. Static screenshots take its midpoint, and animated AVIF clips cover the whole range.
+
+**Pulling in adjacent lines.** Press `P` or `N`, or use the Prev and Next steppers above the sentence preview, to add the previous or next subtitle line. Repeat for as many lines as exist. Shift+`P` and Shift+`N` remove them again. The sentence preview lists every included line with the mined one highlighted, so you always see the sentence field before confirming. The clip bounds and the waveform rails follow the outermost added line, keeping the review's audio padding.
+
+Confirming writes the combined lines to the sentence field. Reset drops the added lines along with any timing changes. Adjacent lines come from the parsed subtitle track when one is loaded; otherwise you only get lines that already played. A clip capped by `media.maxMediaDuration` still keeps the full combined sentence even when the audio cannot stretch to cover every added line.
+
+**Canceling.** You can go back to editing, finish with the original timing, create the card without audio or an image, or discard it. Discard deletes an existing Yomitan or audio card, and skips creation entirely for a direct sentence card. A failed audio preview does not block confirmation or card creation.
+
+Clipboard updates and stats-dashboard mining never open timing review. The option is off by default and hot-reloads. **Review Media Timing** in the runtime options palette (`Ctrl/Cmd+Shift+O`) toggles it for the current session.
+
+### Screenshots (static)

 A single frame is captured at the current playback position.

@@ -195,9 +220,9 @@ A single frame is captured at the current playback position.
 }
 ```

-### Animated Clips (AVIF)
+### Animated clips (AVIF)

-Instead of a static screenshot, SubMiner can generate an animated AVIF covering the subtitle duration.
+SubMiner can produce an animated AVIF spanning the subtitle duration instead of a still frame.

 ```jsonc
 "ankiConnect": {
@@ -214,7 +239,7 @@ Instead of a static screenshot, SubMiner can generate an animated AVIF covering

 Animated AVIF requires an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`) in your FFmpeg build. Generation timeout is 60 seconds. `media.syncAnimatedImageToWordAudio` (default `true`) prepends a frozen first frame matching the existing word-audio duration, so the motion starts together with the sentence audio.

-### Behavior Options
+### Behavior options

 ```jsonc
 "ankiConnect": {
@@ -233,42 +258,9 @@ Animated AVIF requires an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`)

 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.
+`overwriteAudio` applies to automatic card updates and duplicate-card enrichment. Manual clipboard subtitle updates (`Ctrl/Cmd+C`, then `Ctrl/Cmd+V`) always replace generated sentence audio in `ankiConnect.fields.audio`, even when `overwriteAudio` is disabled.

-## 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)
+## 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.

@@ -287,9 +279,11 @@ Sentence card creation and audio card marking require a non-empty `ankiConnect.i

 Trigger with the mine sentence shortcut (`Ctrl/Cmd+S` by default). The card is created directly via AnkiConnect with the sentence, audio, and image filled in.

+The dedicated sentence-card and audio-card shortcuts use the Lapis/Kiku-compatible `Sentence` and `SentenceAudio` fields. This does not affect the configured fields used to enrich normal word cards.
+
 To mine multiple subtitle lines as one sentence card, use `Ctrl/Cmd+Shift+S` followed by a digit (1–9) to select how many recent lines to combine.

-## Word Card Type (Kiku/Lapis)
+## Word card type (Kiku/Lapis)

 Word cards get a card-type flag when SubMiner fills their sentence, whether that comes from Yomitan auto-enrichment, a manual clipboard update, or stats-dashboard word mining. By default the flag is `IsWordAndSentenceCard`; pick a different one with `ankiConnect.lapisKiku.wordCardKind`.

@@ -304,9 +298,9 @@ Word cards get a card-type flag when SubMiner fills their sentence, whether that

 `click` marks `IsClickCard`, `sentence` marks `IsSentenceCard`, `audio` marks `IsAudioCard`, and `none` leaves the flags untouched for templates that manage them elsewhere. Whichever flag is chosen, the other card-type flags are cleared so the note never claims two card types. The setting is only read when `isKiku` or `isLapis` is enabled, and cards mined with Mine Sentence or Mine Audio keep their own flag.

-## Field Grouping (Kiku)
+## Field grouping (Kiku/Senren)

-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.
+When you mine the same word multiple times, SubMiner can merge the cards instead of creating duplicates. This is designed for note types that support grouped fields: [Kiku](https://github.com/youyoumu/kiku) and [Senren](https://github.com/BrenoAqua/Senren) (which calls the feature scene switching).

 ```jsonc
 "ankiConnect": {
@@ -318,6 +312,18 @@ When you mine the same word multiple times, SubMiner can merge the cards instead
 }
 ```

+For Senren note types, enable `isSenren` instead. Kiku and Senren write incompatible markup into the same fields, so only one can be enabled at a time; if both are enabled, Kiku wins and a config warning is emitted.
+
+```jsonc
+"ankiConnect": {
+  "isSenren": {
+    "enabled": true,
+    "fieldGrouping": "auto",           // "auto" (default), "manual", or "disabled"
+    "deleteDuplicateInAuto": true      // delete new card after auto-merge
+  }
+}
+```
+
 ### Modes

 **Disabled** (`"disabled"`): No duplicate detection. Each card is independent.
@@ -326,17 +332,20 @@ When you mine the same word multiple times, SubMiner can merge the cards instead

 **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
+### What gets merged

-| Field    | Merge behavior                                |
-| -------- | --------------------------------------------- |
-| Sentence | Both cards' sentences kept as grouped entries |
-| Audio    | Both cards' `[sound:...]` entries kept        |
-| Image    | Both cards' images kept                       |
+| Field    | Merge behavior                                  |
+| -------- | ----------------------------------------------- |
+| Sentence | Both cards' sentences kept as grouped entries   |
+| Audio    | Both cards' `[sound:...]` entries kept          |
+| Image    | Both cards' images kept                         |
+| MiscInfo | Both cards' source info kept as grouped entries |

 Identical values from both cards are kept as separate grouped entries; the merge does not deduplicate.

-### Keyboard Shortcuts in the Modal
+The merge markup depends on the note type. Kiku entries are wrapped in `<span data-group-id="...">` spans ordered newest first. Senren entries follow the [scene switching](https://github.com/BrenoAqua/Senren/blob/main/docs/scene_switching.md) format: sentence, sentenceFurigana, and miscInfo entries use `group` spans when ordinal order is sufficient and numbered `groupN` spans when they need an absolute scene target. Audio and pictures are appended positionally, and the number of sentenceAudio entries drives Senren's scene count. Ungrouped legacy content is wrapped into a group span on first merge, and source `groupN` spans are rebased after the kept note's existing audio scenes.
+
+### Keyboard shortcuts in the modal

 | Key         | Action                             |
 | ----------- | ---------------------------------- |
@@ -345,7 +354,7 @@ Identical values from both cards are kept as separate grouped entries; the merge
 | `Backspace` | Go back from the merge preview     |
 | `Esc`       | Cancel (keep both cards unchanged) |

-## Full Config Example
+## Full config example

 ```jsonc
 {
@@ -363,11 +372,10 @@ Identical values from both cards are kept as separate grouped entries; the merge
    },
    "fields": {
      "word": "Expression",
-      "audio": "ExpressionAudio",
+      "audio": "SentenceAudio",
      "image": "Picture",
      "sentence": "Sentence",
      "miscInfo": "MiscInfo",
-      "translation": "SelectionText",
    },
    "media": {
      "generateAudio": true,
@@ -390,11 +398,6 @@ Identical values from both cards are kept as separate grouped entries; the merge
    "metadata": {
      "pattern": "[SubMiner] %f (%t)",
    },
-    "ai": {
-      "enabled": false,
-      "model": "", // e.g. "openai/gpt-4o-mini"
-      "systemPrompt": "",
-    },
    "isKiku": {
      "enabled": false,
      "fieldGrouping": "disabled",
@@ -405,12 +408,5 @@ Identical values from both cards are kept as separate grouped entries; the merge
      "sentenceCardModel": "Lapis",
    },
  },
-  "ai": {
-    "enabled": false,
-    "apiKey": "",
-    "apiKeyCommand": "",
-    "baseUrl": "https://openrouter.ai/api",
-    "requestTimeoutMs": 15000,
-  },
 }
 ```
@@ -20,7 +20,7 @@ Within the desktop app, `src/main.ts` is a composition root that wires small run
  - services compose through explicit inputs/outputs
  - orchestration is separate from implementation

-## Project Structure
+## Project structure

 ```text
 launcher/                 # Standalone CLI launcher wrapper and mpv helpers
@@ -33,7 +33,6 @@ plugin/
                          #   state · messages · hover · ui · options · environment · log
                          #   binary · session_bindings · version)
 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
@@ -86,7 +85,7 @@ src/
  anki-integration/        # AnkiConnect proxy server + note-update enrichment workflow
 ```

-### Service Layer (`src/core/services/`)
+### Service layer (`src/core/services/`)

 - **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`
@@ -98,7 +97,7 @@ src/
 - **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)

-### Renderer Layer (`src/renderer/`)
+### Renderer layer (`src/renderer/`)

 The renderer keeps `renderer.ts` focused on orchestration. UI behavior is delegated to per-concern modules.

@@ -136,12 +135,12 @@ src/renderer/
    platform.ts            # Layer/platform capability detection
 ```

-### Launcher + Plugin Runtimes
+### Launcher + plugin runtimes

 - `launcher/main.ts` dispatches commands through `launcher/commands/*` and shared config readers in `launcher/config/*`. It handles mpv startup, app passthrough, Jellyfin helper commands, and playback handoff.
 - `plugin/subminer/main.lua` is the mpv entrypoint: it sets up the module path and loads `init.lua`, a thin shim that boots the modular Lua files: `bootstrap.lua` (startup), `lifecycle.lua` (connect/disconnect), `process.lua` (process management), `state.lua` (shared state), `messages.lua` (IPC), `hover.lua` (hover-token highlight rendering), `ui.lua` (OSD rendering), `options.lua` (config), `environment.lua` (detection), `log.lua` (logging), `binary.lua` (path resolution), `session_bindings.lua` (configurable session keybindings), `version.lua` (version metadata). AniSkip intro detection lives in the SubMiner app (`src/main/runtime/aniskip-runtime.ts`), which drives mpv chapters and the skip key over the IPC socket.

-## Flow Diagram
+## 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.

@@ -224,7 +223,7 @@ flowchart TB
  style ExtRt fill:#363a4f,stroke:#494d64,color:#cad3f5
 ```

-## Composition Pattern
+## Composition pattern

 Most runtime code follows a dependency-injection pattern:

@@ -261,14 +260,14 @@ Additional conventions in the current code:
 - Domain barrels in `src/main/runtime/domains/*` re-export runtime handlers + main-deps builders, while composers in `src/main/runtime/composers/*` assemble larger runtime clusters.
 - Many runtime handlers accept `*MainDeps` objects generated by `createBuild*MainDepsHandler` builders to isolate side effects and keep units testable.

-### IPC Contract + Validation Boundary
+### IPC contract + validation boundary

 - Central channel constants live in `src/shared/ipc/contracts.ts` and are consumed by both main (`ipcMain`) and renderer preload (`ipcRenderer`) wiring.
 - Runtime payload parsers/type guards live in `src/shared/ipc/validators.ts`.
 - Rule: renderer-supplied payloads must be validated at IPC entry points (`src/core/services/ipc.ts`, `src/core/services/anki-jimaku-ipc.ts`) before calling domain handlers.
 - Malformed invoke payloads return explicit structured errors (for example `{ ok: false, error: ... }`) and malformed fire-and-forget payloads are ignored safely.

-### Runtime State Ownership (Migrated Domains)
+### Runtime state ownership (migrated domains)

 For domains migrated to reducer-style transitions (for example AniList token/queue/media-guess runtime state), follow these rules:

@@ -278,7 +277,7 @@ For domains migrated to reducer-style transitions (for example AniList token/que
 - 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
+## 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.

@@ -315,7 +314,7 @@ flowchart TB

 The runtime sockets in this flow are detailed 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.
@@ -387,7 +386,7 @@ flowchart TB
  style Loop fill:#363a4f,stroke:#494d64,color:#cad3f5
 ```

-## Subtitle Prefetch Pipeline
+## Subtitle prefetch pipeline

 SubMiner can pre-tokenize upcoming subtitle lines before they appear on screen. When an external subtitle file (SRT, VTT, or ASS) is detected on the active track, the `SubtitlePrefetchService` parses all cues via the subtitle cue parser (`subtitle-cue-parser.ts`), identifies a priority window of upcoming lines based on the current playback position, and tokenizes them in the background through the same pipeline used for live subtitles. Results are stored directly into the `SubtitleProcessingController` cache, so when a subtitle actually appears during playback, it hits a warm cache and renders in ~30-50ms instead of ~200-320ms.

@@ -417,7 +416,7 @@ flowchart TB
  style Render stroke-width:2px
 ```

-## Why This Design
+## Why this design

 - **Smaller blast radius:** changing one feature usually touches one service.
 - **Better testability:** most behavior can be tested without Electron windows/mpv.
@@ -428,7 +427,7 @@ flowchart TB
 - **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
+## 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.
@@ -1,5 +1,92 @@
 # Changelog

+## 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**
@@ -1,12 +1,12 @@
-# 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-compatible dictionary of a show's characters from [AniList](https://anilist.co), the online anime and manga database. Once it is loaded, character names in subtitles get recognized and highlighted, and hovering one shows the portrait, role, voice actor, and biography without leaving the overlay.

-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.
+Proper names rarely appear in ordinary dictionaries, so without this every character name reads as an unknown word. That wrecks N+1 highlighting, since a line naming two characters looks like a line with two unknowns. Recognizing them keeps the highlighting pointed at real vocabulary.

 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.

-## How It Works
+## How it works

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

@@ -16,12 +16,12 @@ The feature has three stages: **snapshot**, **merge**, and **match**.

 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
+## Enabling the feature

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

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

 ```jsonc
@@ -45,7 +45,7 @@ AniList character data is fetched via public GraphQL queries - no account or acc
 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.
 :::

-## Name Generation
+## Name generation

 A single character produces many searchable terms so that names are recognized regardless of how they appear in dialogue. SubMiner generates variants for:

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

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

 **Middle-dot removal** (common in katakana foreign names):

@@ -86,7 +86,7 @@ Unspaced native names (AniList often stores 渡辺真奈美 without a separator)

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

-## Name Matching
+## Name matching

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

@@ -109,7 +109,7 @@ Name matches are visually distinct from [N+1 targeting, frequency highlighting,
 | `subtitleStyle.nameMatchImagesEnabled` | `false`   | Show small AniList portraits beside names |
 | `subtitleStyle.nameMatchColor`         | `#f5bde6` | Highlight color for matched names         |

-## Inline Character Portraits
+## 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.

@@ -128,7 +128,7 @@ The portrait size is controlled by the surrounding subtitle font size and render
 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
+## Dictionary entries

 Each character entry in the Yomitan dictionary includes structured content:

@@ -156,7 +156,7 @@ The three collapsible sections can be configured to start open or closed:
 }
 ```

-## Auto-Sync Lifecycle
+## Auto-sync lifecycle

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

@@ -185,7 +185,7 @@ These phases are emitted through the configured notification surface. Some phase

 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
+## Manual generation

 You can generate a character dictionary from the command line without auto-sync:

@@ -199,7 +199,7 @@ SubMiner.AppImage --dictionary

 This creates a standalone dictionary ZIP for the target media and saves it alongside the snapshots.

-## Correcting AniList Matches
+## 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.

@@ -223,11 +223,11 @@ SubMiner.AppImage --dictionary-select --dictionary-anilist-id 21355 --dictionary
 subminer app --session-action '{"actionId":"openCharacterDictionaryManager"}'
 ```

-SubMiner stores manual selections in `character-dictionaries/anilist-overrides.json`. The episode's parent directory **and detected season** define the override scope, so later episodes in the same season keep the selected AniList ID even if their filename guesses differ, while a different season never inherits the override -- including when every season sits in one flat folder. When you replace a wrong match, SubMiner removes that stale media ID from the merged dictionary's active set and rebuilds/imports the merged character dictionary.
+SubMiner stores manual selections in `character-dictionaries/anilist-overrides.json`. The episode's parent directory **and detected season** define the override scope, so later episodes in the same season keep the selected AniList ID even if their filename guesses differ, while a different season never inherits the override - including when every season sits in one flat folder. When you replace a wrong match, SubMiner removes that stale media ID from the merged dictionary's active set and rebuilds/imports the merged character dictionary.

 An override also pins the entry used for [AniList watch progress](/anilist-integration), so correcting a wrong match once fixes both the character dictionary and progress tracking.

-## Managing Loaded Entries
+## Managing loaded entries

 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.

@@ -237,7 +237,7 @@ Open the manager with `Ctrl/Cmd+D` (`shortcuts.openCharacterDictionaryManager`).

 The current anime cannot be removed while you are watching it; it stays loaded until playback changes.

-## File Structure
+## File structure

 All character dictionary data lives under `{userData}/character-dictionaries/`:

@@ -267,7 +267,7 @@ merged.zip
  img/                        # Embedded character and VA portraits
 ```

-## Configuration Reference
+## Configuration reference

 | Option                                                                 | Default   | Description                                                     |
 | ---------------------------------------------------------------------- | --------- | --------------------------------------------------------------- |
@@ -280,11 +280,11 @@ merged.zip
 | `subtitleStyle.nameMatchImagesEnabled`                                 | `false`   | Show small AniList portraits beside matched names               |
 | `subtitleStyle.nameMatchColor`                                         | `#f5bde6` | Highlight color for character-name matches                      |

-## Reference Implementation
+## 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:
+The reference implementation covers the same ground: name variant generation, honorific expansion, structured Yomitan content, and portrait embedding. It also reads VNDB as a source for visual novel characters. Key differences:

 |                        | SubMiner                                     | Reference Implementation              |
 | ---------------------- | -------------------------------------------- | ------------------------------------- |
@@ -8,11 +8,13 @@ outline: [2, 3]
 import { withBase } from 'vitepress';
 </script>

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

-## Quick Start
+This page is the full reference. It covers the Settings window, where the config file lives, and every option grouped by topic. If you are just starting out, the Quick Start below and the [Settings window](#settings) are enough.

-For most users, start with this minimal configuration:
+## Quick start
+
+Start here:

 ```json
 {
@@ -35,11 +37,11 @@ For most users, start with this minimal configuration:

 Use the known-word deck map to choose which Anki decks and note fields feed the known-word cache.

-Then customize as needed using the sections below.
+Everything else is optional; the sections below cover it.

 ## Settings

-SubMiner includes a dedicated **Settings** window accessible from the tray menu, the app `--settings` flag, or launcher commands such as `subminer --settings` and `subminer settings`. It is the primary way to configure SubMiner - all changes are written directly to `config.jsonc`, so manual file editing is not required for most users.
+Open the **Settings** window from the tray menu, the app's `--settings` flag, or `subminer settings`. It writes straight to `config.jsonc`, so anything you change there is a normal config edit you can inspect afterward.

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

@@ -57,11 +59,11 @@ Each field still writes to its current `config.jsonc` path. For example, subtitl

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

-Secret fields do not display stored values. They show whether a value is configured; entering a new value writes it, and reset clears the explicit path. Prefer command-based secret options such as `ai.apiKeyCommand` when available.
+Secret fields do not display stored values. They show whether a value is configured; entering a new value writes it, and reset clears the explicit path. Prefer command-based secret options such as `jimaku.apiKeyCommand` when available.

 Saving validates the candidate config before writing. Live-reloadable changes are applied immediately; other changes return a restart-required banner in the window.

-## Configuration File
+## Configuration file

 The Settings window writes to `config.jsonc` directly, so most users do not need to edit the file by hand. The config file and the option reference below are provided for advanced use, scripting, or cases where you prefer editing config directly.

@@ -95,7 +97,7 @@ For valid JSON/JSONC with invalid option values, SubMiner uses warn-and-fallback

 On macOS, these validation warnings also open a native dialog with full details (desktop notification banners can truncate long messages).

-### Hot-Reload Behavior
+### Hot-reload behavior

 SubMiner watches the active config file (`config.jsonc` or `config.json`) while running and applies supported updates automatically.

@@ -103,7 +105,7 @@ Hot-reloadable settings include subtitle appearance, sidebar controls, keybindin
 shortcuts, notifications, logging level, selected source-language preferences,
 Jimaku/Subsync settings, AniSkip settings (`mpv.aniskipEnabled`, `mpv.aniskipButtonKey`),
 stats keys (`stats.toggleKey`, `stats.markWatchedKey`), the secondary-subtitle default
-mode, and the Anki deck, known-word, N+1, field, sentence-card, AI, and Kiku options
+mode, and the Anki deck, known-word, N+1, field, sentence-card, and Kiku options
 listed in the reference tables below.

 When these values change, SubMiner applies them live. Invalid config edits are rejected and the previous valid runtime config remains active.
@@ -111,11 +113,10 @@ When these values change, SubMiner applies them live. Invalid config edits are r
 Restart-required changes:

 - Any other config sections still require restart.
- Shared top-level `ai` provider settings still require restart.
 - AnkiConnect transport/proxy/media/tag fields still require restart unless listed above.
 - SubMiner shows an on-screen/system notification listing restart-required sections when they change.

-### Configuration Options Overview
+### Configuration options Overview

 The configuration file includes several main sections:

@@ -146,11 +147,10 @@ The configuration file includes several main sections:

 **Anki Integration**

- [**Shared AI Provider**](#shared-ai-provider) - Canonical OpenAI-compatible provider config shared by Anki and YouTube subtitle fixing
 - [**AnkiConnect**](#ankiconnect) - Automatic Anki card creation with media
- [**Kiku/Lapis Integration**](#kiku-lapis-integration) - Sentence cards and duplicate handling for Kiku/Lapis note types
+- [**Kiku/Lapis Integration**](#kiku-lapis-integration) - Sentence cards and duplicate handling for Kiku/Lapis/Senren note types
 - [**N+1 Word Highlighting**](#n-1-word-highlighting) - Known-word cache and single-target highlighting
- [**Field Grouping Modes**](#field-grouping-modes) - Kiku/Lapis duplicate card merging
+- [**Field Grouping Modes**](#field-grouping-modes) - Kiku/Senren duplicate card merging

 **External Integrations**

@@ -168,7 +168,7 @@ The configuration file includes several main sections:
 - [**Updates**](#updates) - Automatic update checks, notifications, and prerelease testing
 - [**Notifications**](#notifications) - Overlay notification placement

-## Core Settings
+## Core settings

 ### Logging

@@ -243,13 +243,13 @@ Configure where overlay notification cards appear:

 #### Notification history panel

-Every overlay notification shown during a session is also recorded in a notification history panel. Press `Ctrl/Cmd+N` (configurable via [`shortcuts.toggleNotificationHistory`](#shortcuts-configuration)) to toggle the panel; the binding works whether the overlay or mpv has focus. The panel slides in from the same edge the notifications use — left when `overlayPosition` is `"top-left"`, and right for `"top-right"` or `"top"` (centered). Character dictionary sync uses one live card but records each distinct phase in history. Each entry can be removed individually, or use **Clear** to empty the history. History is session-only and is not persisted across restarts.
+Every overlay notification shown during a session is also recorded in a notification history panel. Press `Ctrl/Cmd+N` (configurable via [`shortcuts.toggleNotificationHistory`](#shortcuts-configuration)) to toggle the panel; the binding works whether the overlay or mpv has focus. The panel slides in from the same edge the notifications use, so left when `overlayPosition` is `"top-left"` and right for `"top-right"` or `"top"` (centered). Character dictionary sync uses one live card but records each distinct phase in history. Each entry can be removed individually, or use **Clear** to empty the history. History is session-only and is not persisted across restarts.

 Startup tokenization, subtitle annotation, and character dictionary status follow the configured notification surface. When the surface is `"overlay"` or `"both"`, SubMiner queues those startup notifications until the overlay renderer is ready instead of falling back to mpv OSD. If loading and ready states both finish before the overlay can paint, the loading card is delivered first and then updates to ready shortly after. With `"both"`, character dictionary checking/building/importing/ready status also goes to system notifications; building and importing are only emitted when that work is actually needed. The bundled mpv plugin only shows its startup OSD messages when `ankiConnect.behavior.notificationType` is set to `"osd"` or `"osd-system"` in `config.jsonc`; AniSkip prompts and skip result messages are playback feedback and still route to overlay notifications when configured.

 The equivalent direct CLI command is `--playback-feedback <text>` (`playbackFeedback` internally). It sends that one non-empty feedback string through the same route controlled by `ankiConnect.behavior.notificationType`; it does not change the saved config.

-### Auto-Start Overlay
+### Auto-start overlay

 Control whether the overlay automatically becomes visible when it connects to mpv:

@@ -267,7 +267,7 @@ When you launch through the SubMiner app or the `subminer` wrapper, the launcher

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

-### Startup Warmups
+### Startup warmups

 Control which startup warmups run in the background versus deferring to first real usage:

@@ -293,7 +293,7 @@ Control which startup warmups run in the background versus deferring to first re

 Defaults warm local tokenizer/dictionary work (`true` for `mecab`, `yomitanExtension`, and `subtitleDictionaries`) with `lowPowerMode: false`; Jellyfin remote session warmup is opt-in (`false` by default). Setting a warmup toggle to `false` defers that work until first usage.

-### WebSocket Server
+### WebSocket server

 The overlay includes a built-in WebSocket server that broadcasts plain subtitle text to connected clients for external processing.

@@ -357,9 +357,9 @@ See `config.example.jsonc` for detailed configuration options.
 | `launchAtStartup` | `true`, `false` | Start texthooker automatically with SubMiner startup (default: `false`) |
 | `openBrowser`     | `true`, `false` | Open browser tab when texthooker starts (default: `false`)              |

-## Subtitle Display
+## Subtitle display

-### Subtitle Style
+### Subtitle style

 Customize the appearance of primary and secondary subtitles:

@@ -457,7 +457,7 @@ Secondary subtitle styling lives in the secondary subtitle CSS object. Any CSS p

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

-### Subtitle Sidebar
+### Subtitle sidebar

 Configure the parsed-subtitle sidebar modal.

@@ -519,7 +519,7 @@ For full details on layout modes, behavior, and the keyboard shortcut, see the [
 | `N4` | `#8bd5ca` | JLPT N4 underline color |
 | `N5` | `#8aadf4` | JLPT N5 underline color |

-### Subtitle Position
+### Subtitle position

 Set the initial vertical subtitle position (measured from the bottom of the screen):

@@ -537,7 +537,7 @@ Set the initial vertical subtitle position (measured from the bottom of the scre

 In the overlay, you can fine-tune subtitle position at runtime with `Right-click + drag` on subtitle text.

-### Secondary Subtitles
+### Secondary subtitles

 Display a second subtitle track (e.g., English alongside Japanese) in the overlay:

@@ -563,8 +563,6 @@ Secondary subtitles do **not** auto-load by default. To turn them on for local a

 These two settings apply to local and Jellyfin playback only. YouTube secondary selection is fixed to English and ignores them; see [YouTube Integration](/youtube-integration#secondary-subtitle-languages). `defaultMode` still controls how the loaded secondary bar is displayed in every case.

-Because the mined-card translation field is filled from the secondary subtitle when one is present, leaving `autoLoadSecondarySub` off means local-file cards fall back to AI translation (when configured) or the original sentence text.
-
 The secondary-subtitle language list also acts as the fallback secondary-language priority for managed startup subtitle selection on local playback and YouTube playback.

 **Display modes:**
@@ -575,7 +573,7 @@ The secondary-subtitle language list also acts as the fallback secondary-languag

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

-## Keyboard & Controls
+## Keyboard and controls

 ### Keybindings

@@ -641,7 +639,7 @@ Subtitle delay commands (`sub-delay`, `sub-step`) show a native mpv OSD notifica

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

-### Shortcuts Configuration
+### Shortcuts configuration

 Customize or disable the overlay keyboard shortcuts:

@@ -702,7 +700,7 @@ Set any shortcut to `null` to disable it.

 Feature-dependent shortcuts/keybindings only run when their related integration is enabled. For example, Anki/Kiku shortcuts require `ankiConnect.enabled` (and Kiku-specific behavior where applicable), and Jellyfin remote startup behavior requires Jellyfin to be enabled.

-### Controller Support
+### Controller support

 SubMiner can read controllers through the Chrome Gamepad API and map them onto the existing keyboard-only overlay workflow.

@@ -818,7 +816,7 @@ If you update this controller documentation or the generated controller examples

 Tune `scrollPixelsPerSecond`, `horizontalJumpPixels`, deadzones, repeat timing, and profile `buttonIndices` to match your controller. See [config.example.jsonc](/config.example.jsonc) for the full generated comments for every controller field.

-### Manual Card Update Shortcuts
+### Manual card update shortcuts

 When automatic card updates are disabled, new cards are detected but not automatically updated. Use these keyboard shortcuts for manual control:

@@ -845,7 +843,7 @@ When automatic card updates are disabled, new cards are detected but not automat

 These shortcuts are only active when the overlay window is visible and automatically disabled when hidden.

-### Session Help Modal
+### Session help modal

 The session help modal opens from the overlay with `Ctrl/Cmd+/` by default. The mpv plugin also exposes it through the `y-h` chord. It shows the current session keybindings and color legend.

@@ -869,13 +867,14 @@ The list is generated at runtime from:

 When config hot-reload updates shortcut/keybinding/style values, close and reopen the help modal to refresh the displayed entries.

-### Runtime Option Palette
+### Runtime option palette

 Use the runtime options palette to toggle settings live while SubMiner is running. These changes are session-only and reset on restart.

-Current runtime options cover automatic card updates, known-word highlighting,
-known-word maturity coloring, N+1 annotation, JLPT underlines, frequency
-highlighting, known-word match mode, and Kiku field grouping mode.
+Current runtime options cover automatic card updates, media timing review,
+known-word highlighting, known-word maturity coloring, N+1 annotation, JLPT
+underlines, frequency highlighting, known-word match mode, and Kiku field
+grouping mode.

 Annotation toggles only apply to new subtitle lines after the toggle. The currently displayed line is not re-tokenized in place.

@@ -888,39 +887,7 @@ Palette controls:
 - `Enter`: apply selected value
 - `Esc`: close

-## Anki Integration
-
-### Shared AI Provider
-
-This is the single, shared connection to an OpenAI-compatible LLM endpoint. Configure it **once** here at the top level, and SubMiner reuses it wherever AI is needed (Anki translation/enrichment and YouTube subtitle fixing). Per-feature toggles and prompt/model tweaks live in their own sections (for example `ankiConnect.ai` and `youtubeSubgen.ai`) and inherit this transport.
-
-```json
-{
-  "ai": {
-    "enabled": false,
-    "apiKey": "",
-    "apiKeyCommand": "",
-    "model": "openai/gpt-4o-mini",
-    "baseUrl": "https://openrouter.ai/api",
-    "requestTimeoutMs": 15000
-  }
-}
-```
-
-| Option             | Values               | Description                                                                          |
-| ------------------ | -------------------- | ------------------------------------------------------------------------------------ |
-| `ai.enabled`       | `true`, `false`      | Enable shared AI provider features (default: `false`)                                |
-| `apiKey`           | string               | Static API key for the shared provider                                               |
-| `apiKeyCommand`    | string               | Shell command used to resolve the API key (preferred over a plaintext `apiKey`)      |
-| `model`            | string               | Default model identifier requested from the provider (default: `openai/gpt-4o-mini`) |
-| `baseUrl`          | string (URL)         | OpenAI-compatible base URL (default: `https://openrouter.ai/api`)                    |
-| `systemPrompt`     | string               | Default system prompt sent with requests (default: a translation-engine prompt)      |
-| `requestTimeoutMs` | integer milliseconds | Shared request timeout (default: `15000`)                                            |
-
-SubMiner uses the shared provider for:
-
- Anki translation/enrichment when Anki AI is enabled
- YouTube generated-subtitle fixing when `youtubeSubgen.fixWithAi` is enabled (with optional `youtubeSubgen.ai.model` / `systemPrompt` overrides)
+## Anki integration

 ### AnkiConnect

@@ -942,16 +909,10 @@ Enable automatic Anki card creation and updates with media generation:
    "deck": "Learning::Japanese",
    "fields": {
      "word": "Expression",
-      "audio": "ExpressionAudio",
+      "audio": "SentenceAudio",
      "image": "Picture",
      "sentence": "Sentence",
-      "miscInfo": "MiscInfo",
-      "translation": "SelectionText"
-    },
-    "ai": {
-      "enabled": false,
-      "model": "",
-      "systemPrompt": ""
+      "miscInfo": "MiscInfo"
    },
    "media": {
      "generateAudio": true,
@@ -967,6 +928,7 @@ Enable automatic Anki card creation and updates with media generation:
      "animatedCrf": 35,
      "normalizeAudio": true,
      "mirrorMpvVolume": true,
+      "reviewTiming": false,
      "audioPadding": 0,
      "fallbackDuration": 3,
      "maxMediaDuration": 30
@@ -1008,17 +970,14 @@ This example is intentionally compact. The option table below documents availabl
 | `tags`                                            | array of strings                            | Tags automatically added to cards mined/updated by SubMiner (default: `['SubMiner']`; set `[]` to disable automatic tagging).                                                                                                   |
 | `ankiConnect.deck`                                | string                                      | Restrict duplicate detection and card enrichment to this Anki deck. Leave empty to use the Yomitan mining deck when available. In Settings, this dropdown auto-fills and persists Yomitan's current mining deck when available. |
 | `fields.word`                                     | string                                      | Card field for mined word / expression text (default: `Expression`)                                                                                                                                                             |
-| `fields.audio`                                    | string                                      | Card field for audio files (default: `ExpressionAudio`)                                                                                                                                                                         |
+| `fields.audio`                                    | string                                      | Card field for the generated sentence audio clip (default: `ExpressionAudio`). Set this to a dedicated field such as `SentenceAudio` so it does not collide with the word audio Yomitan writes.                                  |
 | `fields.image`                                    | string                                      | Card field for images (default: `Picture`)                                                                                                                                                                                      |
 | `fields.sentence`                                 | string                                      | Card field for sentences (default: `Sentence`)                                                                                                                                                                                  |
 | `fields.miscInfo`                                 | string                                      | Card field for metadata (default: `"MiscInfo"`, set to `null` to disable)                                                                                                                                                       |
-| `fields.translation`                              | string                                      | Card field for sentence-card translation/back text (default: `SelectionText`)                                                                                                                                                   |
-| `ankiConnect.ai.enabled`                          | `true`, `false`                             | Use AI translation for sentence cards. Also auto-attempted when secondary subtitle is missing.                                                                                                                                  |
-| `ankiConnect.ai.model`                            | string                                      | Optional model override for Anki AI translation/enrichment flows.                                                                                                                                                               |
-| `ankiConnect.ai.systemPrompt`                     | string                                      | Optional system prompt override for Anki AI translation/enrichment flows.                                                                                                                                                       |
 | `media.generateAudio`                             | `true`, `false`                             | Generate audio clips from video (default: `true`)                                                                                                                                                                               |
 | `media.normalizeAudio`                            | `true`, `false`                             | Normalize generated sentence-audio loudness during media extraction (default: `true`). Set to `false` to keep raw source loudness. Changes apply live.                                                                          |
 | `media.mirrorMpvVolume`                           | `true`, `false`                             | Apply mpv's cubic software-volume curve to each generated sentence-audio clip (default: `true`). This ignores mpv's separate mute state, falls back to unity scaling if volume cannot be read, and applies changes live.        |
+| `media.reviewTiming`                              | `true`, `false`                             | Pause playback and review word, sentence, and audio card timing before media generation (default: `false`). Clipboard updates and stats-dashboard mining do not open the review.                                                |
 | `media.generateImage`                             | `true`, `false`                             | Generate image/animation screenshots (default: `true`)                                                                                                                                                                          |
 | `media.imageType`                                 | `"static"`, `"avif"`                        | Image type: static screenshot or animated AVIF (default: `"static"`)                                                                                                                                                            |
 | `media.imageFormat`                               | `"jpg"`, `"png"`, `"webp"`                  | Image format (default: `"jpg"`)                                                                                                                                                                                                 |
@@ -1051,11 +1010,9 @@ This example is intentionally compact. The option table below documents availabl
 | `metadata.pattern`                                | string                                      | Format pattern for metadata: `%f`=filename, `%F`=filename+ext, `%t`=time, `%T`=time with milliseconds, `<br>`=newline                                                                                                           |
 | `isLapis`                                         | object                                      | Lapis/shared sentence-card config: `{ enabled, sentenceCardModel }`. Sentence/audio field names are fixed to `Sentence` and `SentenceAudio`.                                                                                    |
 | `isKiku`                                          | object                                      | Kiku-only config: `{ enabled, fieldGrouping, deleteDuplicateInAuto }` (shared sentence/audio/model settings are inherited from `isLapis`)                                                                                       |
+| `isSenren`                                        | object                                      | Senren-only config: `{ enabled, fieldGrouping, deleteDuplicateInAuto }`. Merges duplicates using Senren's scene-switching markup. Mutually exclusive with `isKiku.enabled`.                                                      |

-`ankiConnect.ai` only controls feature-local enablement plus optional `model` / `systemPrompt` overrides.
-API key resolution, base URL, and timeout live under the shared top-level [`ai`](#shared-ai-provider) config.
-
-### Kiku/Lapis Integration
+### Kiku/Lapis integration

 SubMiner is intentionally built for [Kiku](https://kiku.youyoumu.my.id/) and [Lapis](https://github.com/donkuri/lapis) workflows, with note-type-specific behavior built into Anki settings.

@@ -1080,9 +1037,10 @@ SubMiner is intentionally built for [Kiku](https://kiku.youyoumu.my.id/) and [La
 - Enable `isKiku` to turn on duplicate merge behavior for mined Word/Expression hits.
 - When both are enabled, Kiku behavior is applied for grouping while sentence-card model settings are still read from `isLapis`.
 - `isKiku.fieldGrouping` supports `disabled`, `auto`, and `manual` merge modes; see [Field Grouping Modes](#field-grouping-modes).
+- For [Senren](https://github.com/BrenoAqua/Senren) note types, enable `isSenren` instead of `isKiku`. Duplicate merges then use Senren's scene-switching markup (including grouped `miscInfo` entries), and `isSenren.fieldGrouping` supports the same three modes (default: `auto`). Kiku and Senren are mutually exclusive; if both are enabled, Kiku wins and Senren is turned off with a config warning.
 - `lapisKiku.wordCardKind` picks the card-type flag set on word cards; see [Word Card Type](#word-card-type). It is read only while `isLapis` or `isKiku` is enabled.

-### Word Card Type
+### Word card type

 When SubMiner fills the sentence on a mined word card - from Yomitan auto-enrichment, a manual clipboard update, or stats-dashboard word mining - it marks which card that note should generate. `ankiConnect.lapisKiku.wordCardKind` chooses the flag:

@@ -1096,7 +1054,7 @@ When SubMiner fills the sentence on a mined word card - from Yomitan auto-enrich

 The other card-type flags are cleared so a note never claims two card types at once. Notes are skipped when the note type has no field for the chosen flag, and when the note was already mined as a sentence or audio card. Cards created by Mine Sentence and Mine Audio keep their own flag regardless of this setting.

-### N+1 Word Highlighting
+### N+1 word highlighting

 When known-word highlighting is enabled, SubMiner builds a local cache of known words from Anki to highlight already learned tokens in subtitle rendering.

@@ -1133,7 +1091,7 @@ To refresh roughly once per day, set:
 }
 ```

-### Field Grouping Modes
+### Field grouping modes

 | Mode       | Behavior                                                                                                                   |
 | ---------- | -------------------------------------------------------------------------------------------------------------------------- |
@@ -1152,7 +1110,7 @@ When the manual merge popup opens, SubMiner pauses playback and closes any open

 <a :href="withBase('/assets/kiku-integration.webm')" target="_blank" rel="noreferrer">Open demo in a new tab</a>

-## External Integrations
+## External integrations

 ### Jimaku

@@ -1194,7 +1152,7 @@ The keyboard shortcut lives under `shortcuts.openTsukihime` (default `Ctrl+Shift

 See [TsukiHime Integration](/tsukihime-integration) for the modal workflow, language tabs, and troubleshooting.

-### Subtitle Sync
+### Subtitle sync

 Sync a subtitle track from the overlay picker using `alass` or `ffsubsync`. The picker lets you choose which track gets retimed (the active primary track by default) and, for alass, which reference it is aligned against (the secondary subtitle track by default). Both are **optional external tools** that must be installed separately and available on your `PATH` (or configured via the path options below).

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

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

@@ -1384,7 +1340,7 @@ Jellyfin playback auto-launched through SubMiner loads the mpv plugin the same w

 When Jellyfin is enabled with a server URL and SubMiner is running, the tray menu also shows a `Jellyfin Discovery` checkbox. It starts or stops discovery for the current runtime session only and does not write config. Starting discovery still requires a valid stored or environment-provided Jellyfin auth session.

-### Discord Rich Presence
+### Discord rich presence

 Discord Rich Presence is enabled by default. SubMiner publishes a polished activity card that reflects current media title, playback state, and session timer unless you turn it off.

@@ -1431,7 +1387,7 @@ Troubleshooting:
 - If images do not render, confirm asset keys exactly match uploaded Discord asset names.
 - If Discord is closed/not installed/disconnects, SubMiner continues running and quietly skips presence updates.

-### Immersion Tracking
+### Immersion tracking

 Enable or disable local immersion analytics stored in SQLite for mined subtitles and media sessions. This data also powers the stats dashboard:

@@ -1505,7 +1461,7 @@ Set `dbPath` only if you want to relocate the database (for backup, syncing, or

 See [Immersion Tracking Storage](/immersion-tracking) for schema details, query templates, dashboard access, retention/rollup behavior, backend portability notes, and the dedicated SQLite verification command.

-### Stats Dashboard
+### Stats dashboard

 Configure the local stats UI served from SubMiner and the in-app stats overlay toggle:

@@ -1536,7 +1492,7 @@ Usage notes:
 - The dashboard reads from the same immersion-tracking database, so keep `immersionTracking.enabled` on if you want data to appear.
 - The UI includes Overview, Library, Trends, Vocabulary, Search, and Sessions tabs.

-### MPV Launcher
+### MPV launcher

 Configure the mpv executable, profile, and window state for SubMiner-managed mpv launches (launcher playback, Windows `--launch-mpv`, and Jellyfin idle mpv startup):

@@ -1578,7 +1534,7 @@ Launch mode behavior:
 - **`maximized`** - mpv starts maximized via `--window-maximized=yes`, keeping taskbar access.
 - **`fullscreen`** - mpv starts in true fullscreen via `--fullscreen`.

-### YouTube Playback Settings
+### YouTube playback settings

 Set defaults used by managed subtitle auto-selection and the `subminer` launcher YouTube flow:

@@ -1622,6 +1578,6 @@ Track selection:

 These settings come from `config.jsonc` (or built-in defaults); there are no CLI flags or environment variables for subtitle language selection.

-#### YouTube Subtitle Generation (`youtubeSubgen`)
+#### YouTube subtitle generation (`youtubeSubgen`)

-An advanced, template-hidden section for Whisper-based YouTube subtitle generation: `whisperBin`, `whisperModel`, `whisperVadModel`, `whisperThreads` (default `4`), and `fixWithAi` (default `false`), which post-processes generated subtitles through the [Shared AI Provider](#shared-ai-provider) with optional `youtubeSubgen.ai.model` / `systemPrompt` overrides. These keys are accepted in `config.jsonc` but intentionally omitted from the generated template.
+An advanced, template-hidden section for Whisper-based YouTube subtitle generation: `whisperBin`, `whisperModel`, `whisperVadModel`, and `whisperThreads` (default `4`). These keys are accepted in `config.jsonc` but the generated template omits them.
@@ -1,16 +1,18 @@
-# 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.
+
+Some vocabulary for what follows. _Yomitan_ is the pop-up dictionary. _Jimaku_ is a community subtitle database. _alass_ and _ffsubsync_ retime subtitles against the audio. _Jellyfin_ is a self-hosted media server. A _texthooker_ is a web page that mirrors the current subtitle as selectable text so browser tools can read it.

 <script setup>
 import { withBase } from 'vitepress';

-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" />
@@ -20,9 +22,9 @@ Mine vocabulary cards from Yomitan or directly from subtitle lines. SubMiner aut
  </a>
 </video>

-## Subtitle Download & Sync
+## Subtitle download and 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" />
@@ -32,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, cast to a device, and start playback from SubMiner. Watch progress goes back to the Jellyfin server.

 <!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/jellyfin-poster.jpg?v=${v}`)">
  <source :src="withBase(`/assets/demos/jellyfin.webm?v=${v}`)" type="video/webm" />
@@ -46,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" />
@@ -1,12 +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.
+Architecture and workflow guidance lives in `docs/README.md` at the repo root. This page covers build and test commands only.

 ## Prerequisites

 - [Bun](https://bun.sh)
 - A system `lua` interpreter for `bun run test:launcher` / `bun run test:plugin:src`
- macOS builds compile a Swift helper via `scripts/build-macos-helper.sh` (skip with `SUBMINER_SKIP_MACOS_HELPER_BUILD=1`)
+- macOS builds compile a Swift helper via `scripts/prepare-build-assets.mjs` (skip with `SUBMINER_SKIP_MACOS_HELPER_BUILD=1`)

 ## Setup

@@ -37,7 +37,7 @@ make build-launcher

 `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
+## Launcher artifact workflow

 - Source of truth: `launcher/*.ts`
 - Generated output: `dist/launcher/subminer`
@@ -53,7 +53,7 @@ dist/launcher/subminer --help >/dev/null
 bash scripts/verify-generated-launcher.sh
 ```

-## Running Locally
+## Running locally

 ```bash
 bun run dev    # builds + launches with --start --dev
@@ -169,7 +169,7 @@ bun run format:check: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
+## Config generation

 ```bash
 # Generate default config to ~/.config/SubMiner/config.jsonc (or %APPDATA%\SubMiner\config.jsonc on Windows)
@@ -184,7 +184,7 @@ Convenience wrappers still exist:
 - `make generate-config`
 - `make generate-example-config`

-## Documentation Site
+## Documentation site

 The docs site now lives in `docs-site/` inside the main repo.

@@ -200,7 +200,7 @@ bun run docs:test    # Docs regression tests

 Deployment: production docs are built with `bun run docs:build:versioned` and uploaded directly to Cloudflare Pages by the `docs-pages` GitHub Actions workflow using Wrangler (from `.tmp/docs-versioned-site`). Cloudflare's automatic Git-integration deployments are intentionally disabled - see `docs-site/README.md` for the deployment contract. Do not re-enable Pages build settings in the Cloudflare dashboard.

-## Makefile Reference
+## Makefile reference

 Run `make help` for a full list of targets. Key ones:

@@ -216,7 +216,7 @@ Run `make help` for a full list of targets. Key ones:
 | `make build-macos`          | Convenience wrapper for signed macOS packaging                    |
 | `make build-macos-unsigned` | Convenience wrapper for unsigned macOS packaging                  |

-## 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`.
@@ -228,7 +228,7 @@ Run `make help` for a full list of targets. Key ones:
 - Prefer direct inline deps objects in `src/main/` modules for simple pass-through wiring.
 - Add a helper/adapter service only when it performs meaningful adaptation, validation, or reuse (not identity mapping).

-## Environment Variables
+## Environment variables

 | Variable                           | Description                                                                    |
 | ---------------------------------- | ------------------------------------------------------------------------------ |
@@ -57,7 +57,19 @@ 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)');
 });
@@ -1,13 +1,13 @@
-# 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 logs your watching and mining activity to a local SQLite database and shows it in the built-in stats dashboard. Tracking is on by default; turn it off if you would rather not keep the data.

-"Immersion" here means time spent watching and reading native Japanese content. **All data stays on your computer** - nothing is uploaded anywhere. (SQLite is just a single-file database; you do not need to install or manage anything.)
+"Immersion" here means time spent watching and reading native Japanese content. **All of it stays on your machine.** Nothing is uploaded anywhere. SQLite is a single file on disk, so there is no database server to install or run.

-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.
+Each session records watch time, subtitle lines seen, words encountered, and cards mined. SubMiner also keeps exact lifetime summary tables and daily and monthly rollups. Read it through the stats UI, or point any SQLite tool at the file.

 ::: 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.
+Leave tracking on and use the [Stats Dashboard](#stats-dashboard). The retention, performance, SQL, and schema sections below are reference material for querying or tuning the database yourself. Skip them.
 :::

 Episode completion for local `watched` state uses the shared `DEFAULT_MIN_WATCH_RATIO` (`85%`) value from `src/shared/watch-threshold.ts`.
@@ -25,19 +25,19 @@ 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).
- To share stats and watch history between two machines, use [`subminer sync <host>`](/launcher-script#sync-between-machines) instead of file-level cloud sync — it merges both databases without one side overwriting the other.
+- To share stats and watch history between two machines, use [`subminer sync <host>`](/launcher-script#sync-between-machines) instead of file-level cloud sync. It merges both databases instead of letting one side overwrite the other.

-## Stats Dashboard
+## Stats dashboard

 The same immersion data powers the stats 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 (it also opens the dashboard in your browser when `stats.autoOpenBrowser` is enabled; the default is `false`).
 - 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 commands: 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; `subminer stats cleanup -l` repairs lifetime summary tables. `subminer stats rebuild` and `subminer stats backfill` rebuild or backfill rollup data.
+- Maintenance commands: 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; `subminer stats cleanup -l` repairs lifetime summary tables non-destructively (recomputed from per-episode history, so lifetime totals older than the session retention window are kept); `subminer stats cleanup --duplicate-lines` collapses repeated lines left behind by typeset subtitles (see [Repeated Line Cleanup](#repeated-line-cleanup)). `subminer stats rebuild` and `subminer stats backfill` rebuild or backfill rollup data.
 - Browser page: open `http://127.0.0.1:6969` directly if the local stats server is already running.

-### Dashboard Tabs
+### Dashboard tabs

 #### Overview

@@ -57,13 +57,20 @@ Jellyfin stream URLs are normalized to stable item links before stats titles are

 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.

+A library entry is identified by its parsed title plus any detected season, so the same show can end up on several cards when releases disagree about the title or omit the season tag. Two fixes are available:
+
+- **Merge duplicates.** Hit **Select** above the grid, tick the cards that are the same show, and choose **Merge Selected**. Pick which entry to keep in the dialog; every episode moves onto it and the other cards are removed. Nothing is deleted, so sessions, mined cards and watch time all carry over. SubMiner remembers the merged title variants, so future episodes parsed with one of those names join the kept entry instead of recreating a duplicate card.
+- **Move a single episode.** Hover an episode row in a title's episode list and use the **→** button to reassign it to another library entry. The correction is remembered, so later filename parsing or Jellyfin metadata cannot move that episode back. For local files, later episodes in the same directory inherit the correction when their detected seasons are compatible and every manual correction there points to the same entry; a file that parses to a title which already has its own library entry keeps that identity instead. Conflicting seasons or manual destinations are left for review. If the move empties the old entry, that card is removed and you are returned to the grid.
+
+Once cover art resolves a series to an AniList entry, cards with compatible seasons are folded together automatically only when the searched title exactly matches an AniList title or synonym. A fuzzy result that points at an AniList entry already used by another card appears as a **Possible duplicate** review above the Library grid instead. Choose **Review merge** to compare the cards and pick which one to keep, or **Not duplicates** to dismiss that suggestion permanently. Entries with conflicting explicit season numbers are left alone rather than merged or suggested.
+
 Open a title and use **Delete Entry** in its header to remove a mistakenly tracked show outright. This deletes every episode of that title along with their sessions, subtitle lines, rollups and cover art, drops the words and kanji that were only seen there, and removes the card from the Library grid. Individual episodes and sessions can still be deleted on their own from the episode list and session rows. Entry deletion is refused while that title is the one currently playing.

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

 #### 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.
+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. Every chart takes a configurable date range and grouping.

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

@@ -75,7 +82,7 @@ Expandable session history with new-word activity, cumulative totals, and pause/

 #### Vocabulary

-Top repeated words (click a bar to open the word), new-word timeline, 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.
+The summary cards show all unique vocabulary and kanji recorded in the local tracking database; **New This Week** is the only weekly figure and uses a rolling seven-day window. The word and kanji tables load first while those complete totals calculate separately. Top Repeated Words and New Words by Day use complete tracking history rather than the table's browsing page. New-word history is maintained as a permanent daily lexical rollup using the same token-visibility rules as the totals, including normalization of older timestamps stored in either seconds or milliseconds and retroactive corrections when tracked material is removed or reprocessed. On the first launch after an applicable upgrade, that history is version-rebuilt in the background and the chart refreshes when it is ready; if it remains unavailable, polling stops and an inline Retry control appears. The cards and charts also refresh automatically after the word exclusion list changes. The rest of the tab includes cross-title and frequency rank tables with Hide Known / Hide Kana filters, kanji breakdown, word exclusion list, and click-through occurrence drilldown with Mine Word / Mine Sentence / Mine Audio buttons.

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

@@ -101,7 +108,7 @@ Stats server config lives under `stats`:
 - `markWatchedKey` toggles the watched state of the highlighted entry inside the stats dashboard.
 - `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. Background app launches (`subminer app`) start the stats server immediately, registering it so later launches reuse it instead of starting another one.
- `autoOpenBrowser` controls whether `subminer stats` launches the dashboard URL in your browser after ensuring the server is running.
+- `autoOpenBrowser` decides whether `subminer stats` opens the dashboard URL in your browser once the server is up.
 - `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.
@@ -109,7 +116,7 @@ Stats server config lives under `stats`:
 - `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.

-## Mining Cards from the Stats Page
+## Mining cards from the stats page

 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:

@@ -119,13 +126,43 @@ The Search tab and the Vocabulary tab's word detail panel both mine from subtitl

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

-Secondary subtitle text (typically English translations) is stored alongside primary subtitles during playback and 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.
+Secondary subtitle text is stored alongside primary subtitles during playback, but the Search tab does not use it for display or matching.

-### Word Exclusion List
+### Word exclusion list

 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
+### Repeated line cleanup
+
+Karaoke openings and animated signs are authored as one subtitle event per animation frame, all carrying the same text. Playback reports every one of those frames, so a single OP lyric could be recorded hundreds of times and dominate "Top Repeated Words".
+
+Recording now collapses those runs as they happen, matching what the subtitle sidebar shows:
+
+- When a typeset ASS file stores a clean lyric or sign in a timed authoring comment, or in full-line events surrounding generated fragments, the matching complete line is recorded once. The repeated glyph or clip-animation frames are not recorded. Dialogue spoken while such an animation is on screen records as itself, without the fragment lines beside it.
+- When karaoke styling redraws the same complete lyric across consecutive color or highlight phases, those phases are combined into one line with their full timing. Repeated ordinary dialogue remains separate.
+- When the active subtitle source has been parsed, its cue list has already had duplicate events and animation bursts merged. A line landing inside a surviving cue but after that cue's start is a frame the sidebar merged away, and is not recorded.
+- When no parsed cue covers the live timing, including while a subtitle source is changing or shifted, the strict metadata-free rule applies: a run of identical, contiguous lines each shorter than 0.1s stops being recorded after a few frames. Runs are tracked per line of text, so dual-line karaoke (a kanji and a romaji line frame-flipped together) collapses both lines. Ordinary repeated dialogue, and lines held for a normal beat, always record.
+
+For stats recorded before this, the Vocabulary tab toolbar has a **Duplicates** button:
+
+- Pick how far back to look (7 days, 30 days, 90 days, 1 year, or all time). A narrower window does less work and keeps older history untouched.
+- **Scan** reports the bursts found, the lines they added, and the word and kanji counts they inflated, without writing anything.
+- **Clean Up** applies exactly what the scan reported: each run collapses to its first line (extended to cover the run), and the removed lines' word and kanji occurrences are subtracted from the vocabulary aggregates.
+
+The same thing runs from the terminal:
+
+```bash
+subminer stats cleanup --duplicate-lines --dry-run --lookback-days 30
+subminer stats cleanup --duplicate-lines --lookback-days 30
+```
+
+`--duplicate-lines` (short: `-d`) picks the cleanup mode, so it cannot be combined with `--vocab` or `--lifetime`, and `--dry-run` and `--lookback-days <days>` only apply to it. Omitting `--lookback-days` scans all history; the value must be at least one day.
+
+The cleanup chains runs per line of text, so interleaved dual-line karaoke collapses each of its lines. It also removes the short residue the live rule stores before a run is long enough to recognize: a run one frame short of the usual minimum qualifies when every event is under the strict 0.1s bound.
+
+Runs never cross a session boundary, so rewatching an episode keeps both watches. Session telemetry (watch time, lines seen, tokens seen) and the rollups derived from it are left as recorded: they are cumulative samples taken during playback, and cannot be recomputed for sessions whose raw rows have since been pruned.
+
+## Retention defaults

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

@@ -145,10 +182,11 @@ In practice:
 - 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.
+- New-word charts use their own permanent lexical daily rollups, which are not pruned by activity-rollup retention.

-## Storage / Performance Model
+## Storage / performance model

-The tracker is optimized for "keep everything" defaults:
+The defaults keep everything, and the schema is shaped around that:

 - 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.
@@ -157,7 +195,7 @@ The tracker is optimized for "keep everything" defaults:
 - 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
+## Configurable knobs

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

@@ -180,7 +218,7 @@ All policy options live under `immersionTracking` in your config:
 | `lifetimeSummaries.anime`      | Maintain per-anime lifetime totals                                 |
 | `lifetimeSummaries.media`      | Maintain per-media lifetime totals                                 |

-## Query Templates
+## Query templates

 ### Session timeline

@@ -278,7 +316,7 @@ ORDER BY rollup_month DESC, video_id DESC
 LIMIT ?;
 ```

-## Technical Details
+## 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.
@@ -289,7 +327,7 @@ LIMIT ?;
 - 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 (v18)
+### Schema (v23)

 The exact schema version lives in `SCHEMA_VERSION` (`src/core/services/immersion-tracker/types.ts`) and is recorded in the `imm_schema_version` table.

@@ -297,6 +335,8 @@ Core tables:

 - `imm_videos` - video key/title/source metadata
 - `imm_anime` - anime/series metadata referenced by videos and lifetime tables
+- `imm_anime_title_aliases` - alternate titles that resolve to the same anime row
+- `imm_anime_merge_recommendations` - candidate duplicate-series merges surfaced in the dashboard
 - `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
@@ -314,6 +354,7 @@ Rollup tables:

 - `imm_daily_rollups`
 - `imm_monthly_rollups`
+- `imm_lexical_daily_rollups` - permanent first-discovery counts for vocabulary and kanji chart history
 - `imm_rollup_state` - incremental rollup progress bookkeeping

 Vocabulary tables:
@@ -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>
@@ -1,6 +1,8 @@
 # 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, hover any word in the subtitles to look it up, then turn it into an Anki card without switching apps.
+
+Building cards from the content you are actually watching is called **sentence mining**, and it is the whole point of SubMiner. It bundles its own copy of **Yomitan** (a pop-up dictionary) and talks to **AnkiConnect** (the add-on that lets other programs write cards into Anki), so the sentence, audio, and screenshot fields get filled in for you.

 Three steps to get started:

@@ -8,11 +10,11 @@ Three steps to get started:
 2. **Install SubMiner** - from the AUR, or download from GitHub Releases
 3. **Launch the app** - first-run setup walks you through dictionaries, the launcher, and everything else

-## 1. Install Requirements
+## 1. Install requirements

-Only **mpv** is strictly required to run SubMiner. Everything else enhances the experience but is optional.
+Only **mpv** is strictly required. Everything else is optional, though you will want ffmpeg unless you are fine with cards that have no audio or screenshot.

-Several entries below exist only for the `subminer` command-line launcher, which is Linux and macOS only. On Windows you launch playback with the **SubMiner mpv** shortcut instead, so you can ignore those rows.
+Some rows below matter only for the `subminer` command-line launcher's picker features. On Windows, the **SubMiner mpv** shortcut remains the recommended playback entry point.

 | Dependency           | Status      | Platforms    | What it does                                                                                                                                                   |
 | -------------------- | ----------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -39,7 +41,7 @@ Several entries below exist only for the `subminer` command-line launcher, which
 - **X11 / Xwayland** - for X11 sessions or any other Wayland compositor (uses `xdotool` and `xwininfo`)

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

 <details>
@@ -203,13 +205,13 @@ There is no equivalent setting for ffmpeg: SubMiner invokes it by bare name when

 **Optional extras:** [MeCab for Windows](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary improves annotation accuracy; it is not in any package manager, so install it from that page. `xz` is needed only for [TsukiHime](/tsukihime-integration) subtitle downloads and is not packaged by winget or Chocolatey, so use `scoop install main/xz` or download [XZ Utils](https://tukaani.org/xz/) and add its folder to `PATH`.

-The `subminer` command-line launcher and its picker tools (`fzf`, `rofi`, `chafa`, `ffmpegthumbnailer`) are Linux/macOS only; on Windows you use the **SubMiner mpv** shortcut instead.
+The launcher's picker tools (`fzf`, `rofi`, `chafa`, `ffmpegthumbnailer`) are for Linux and macOS. On Windows, use the **SubMiner mpv** shortcut for playback or install the optional `subminer` terminal wrapper during setup.

 ## 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) from the AUR. The package includes the SubMiner AppImage and its launcher wrapper. Bun is included with the app, so the package has no Bun dependency. Install updates through your AUR helper or package manager.

 ```bash
 paru -S subminer-bin
@@ -234,9 +236,7 @@ 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-line launcher for you. It uses Bun bundled with the AppImage, so it does not need a separate Bun installation or a Bun entry on `PATH`. The downloaded wrapper works the same way. See [manual launcher install](#manual-launcher-install-linux).
 :::

 ### macOS (DMG) {#macos-dmg}
@@ -255,21 +255,20 @@ xattr -d com.apple.quarantine /Applications/SubMiner.app
 2. Enable SubMiner in the list (add it if it does not appear)

 ::: 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-macos).
+First-run setup can install the `subminer` command-line launcher for you. It uses Bun bundled inside `SubMiner.app`, so it does not need a separate Bun installation or a Bun entry on `PATH`. The downloaded wrapper works the same way. See [manual launcher install](#manual-launcher-install-macos).
 :::

-### Windows (Installer) {#windows-installer}
+### 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
+- `subminer.cmd` - optional terminal launcher wrapper

 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>
@@ -286,6 +285,8 @@ bun run build:appimage

 Bundled Yomitan is built during `bun run build`.

+Source and development commands use Bun installed on your system.
+
 </details>

 <details>
@@ -321,9 +322,9 @@ 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:
+Launch SubMiner and the setup wizard opens on its own:

 ```bash
 # Linux (AUR install)
@@ -342,15 +343,17 @@ 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
+- **`subminer` launcher** _(optional)_ - installs a wrapper into a writable terminal PATH directory. The wrapper uses Bun packaged with the app.
 - **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.
+The `Finish setup` button requires a config file and at least one Yomitan dictionary. The launcher is optional and never blocks setup completion.
+
+On Linux and macOS, setup selects a writable directory already on your terminal `PATH`. If it cannot find one, it creates `~/.local/bin` and shows the `export PATH=...` command to run. Add that command to your shell configuration yourself if you want it in future terminals. Setup never edits shell configuration files. On Windows, setup adds only the wrapper directory to the user `PATH`. Setup stores a custom app location so the wrapper can find an AppImage or app bundle outside the usual install directories.

 > [!TIP]
 > You can re-open the setup wizard at any time with `subminer app --setup` or `SubMiner.AppImage --setup`.

-### Play a Video
+### Play a video

 Once setup is complete:

@@ -358,13 +361,13 @@ Once setup is complete:
 subminer video.mkv
 ```

-You should see the overlay appear over mpv. If subtitles are loaded, they will appear as interactive text in the overlay.
+The overlay appears over mpv. If a subtitle track loaded, its text shows up in the overlay as hoverable words.

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

-### Verify Setup
+### Verify setup

-Run the built-in diagnostic to confirm everything is working:
+Run the built-in diagnostic:

 ```bash
 subminer doctor
@@ -372,7 +375,7 @@ subminer doctor

 This checks for the app binary, mpv, ffmpeg, yt-dlp, fzf, rofi, your config file, and the mpv socket path. Only the app binary and mpv are hard failures; the rest are reported as optional. Fix any hard failures before continuing.

-## Anki Setup (Recommended)
+## Anki setup (recommended)

 If you plan to mine Anki cards:

@@ -392,21 +395,21 @@ subminer -u
 subminer --update
 ```

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

-The tray "Check for Updates" entry installs the new app automatically on Linux, macOS, and Windows. On Linux it replaces the running `.AppImage` in place via `electron-updater` and refreshes the managed support assets from `subminer-assets.tar.gz`; AppImages managed by a system package (for example the AUR `/opt/SubMiner/SubMiner.AppImage`) are skipped so the package manager stays in charge.
+The tray "Check for Updates" entry installs the new app automatically on Linux, macOS, and Windows. Current `subminer` wrappers remain small bootstraps that locate the installed app and its private runtime. On Linux the updater replaces the running `.AppImage` in place via `electron-updater` and refreshes managed support assets from `subminer-assets.tar.gz`. The next launcher invocation detects the changed AppImage fingerprint and prepares the matching Bun and CLI cache before running the command. App startup also refreshes this payload and migrates recognized writable legacy launchers. AppImages managed by a system package, for example the AUR `/opt/SubMiner/SubMiner.AppImage`, are skipped so the package manager stays in charge.

-`subminer -u` also performs the AppImage, launcher, and managed support-asset updates directly from the launcher process, which is useful when SubMiner is not currently running.
+On Linux, `subminer -u` updates the AppImage and managed support assets directly, even when the app is not running. The launcher cache refreshes when the app fingerprint changes. AUR installs remain under package-manager control and should be updated through the package manager.

-## How It All Fits Together
+## How it all fits together

-SubMiner is an overlay that sits on top of mpv. It connects to mpv through an IPC socket, renders subtitles as interactive text using a bundled Yomitan dictionary engine, and optionally creates Anki flashcards via AnkiConnect.
+SubMiner is an overlay window that sits on top of mpv. It talks to mpv over an IPC socket, renders each subtitle line as interactive text backed by the bundled Yomitan dictionary engine, and writes Anki cards through AnkiConnect when you ask it to.

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

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

-## Platform Notes
+## Platform notes

 ### macOS

@@ -415,9 +418,9 @@ The bundled mpv plugin is injected at runtime automatically - you don't need to
 - Apple Silicon (M1/M2): `/opt/homebrew/bin/mecab`
 - Intel: `/usr/local/bin/mecab`

-Ensure `mecab` is available on your PATH when launching SubMiner.
+`mecab` has to be on your PATH when SubMiner launches.

-**Fullscreen:** The overlay should appear correctly in fullscreen. If you encounter issues, check that accessibility permissions are granted.
+**Fullscreen:** The overlay follows mpv into fullscreen. If it does not, accessibility permission is the usual cause.

 ### Windows

@@ -426,16 +429,13 @@ Ensure `mecab` is available on your PATH when launching SubMiner.
 - 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
+## 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:
+Current launcher downloads use Bun included in the SubMiner app. The wrapper searches normal install locations and honors `SUBMINER_BINARY_PATH`; Linux also honors `SUBMINER_APPIMAGE_PATH`.

 ### 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
@@ -444,30 +444,35 @@ 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}

-### Linux Support Assets
+Download `subminer.cmd` from GitHub Releases and place it in a directory on your user `PATH`. It finds the installed app in the normal per-user or Program Files location. Set `SUBMINER_BINARY_PATH` if you use a portable or custom install.

-SubMiner ships the Linux rofi theme plus the launcher-managed runtime plugin copy in `subminer-assets.tar.gz`:
+Launchers installed before the private-runtime change may still be bundled JavaScript with a Bun shebang. Those old files need system Bun until a current app startup migrates a recognized writable launcher, or until you replace one with the current release wrapper.
+
+## Optional extras
+
+### Linux support assets
+
+SubMiner ships the Linux rofi theme, scoped Matroska thumbnailer registration, and launcher-managed runtime plugin copy in `subminer-assets.tar.gz`:

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

-`subminer -u` and the tray updater keep those Linux support assets in sync automatically once the `SubMiner` data dir exists. Normal Linux launcher playback also auto-installs the managed runtime plugin copy and rofi theme from the bundled app if either support asset is missing, so manual extraction is mainly useful for pre-seeding or custom setups.
+`subminer -u` and the tray updater keep those Linux support assets in sync automatically once the `SubMiner` data dir exists. Normal Linux launcher playback also auto-installs all three assets from the bundled app if one is missing, so manual extraction is mainly useful for pre-seeding or custom setups. Rofi receives the SubMiner data path through its process-local `XDG_DATA_DIRS`, so the thumbnailer registration does not change the desktop-wide configuration.

 Override the theme path with `SUBMINER_ROFI_THEME=/absolute/path/to/theme.rasi`.

@@ -1,10 +1,10 @@
-# 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.
+SubMiner's Electron app runs two isolated processes, main and renderer, and IPC channels are the only way they talk. That boundary is deliberate. The renderer is an untrusted surface: it loads Yomitan, renders subtitle text SubMiner did not write, and runs in a Chromium sandbox. Every message crossing the bridge goes through a validator before any 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 shapes, and validators all live together, so they change together. Touching an IPC surface means updating the contract, the validator, the preload bridge, and the handler in one commit. Drift between those four layers is a bug, not a style preference.

-## 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.

@@ -36,7 +36,7 @@ flowchart TB
  style E fill:#ed8796,stroke:#494d64,color:#24273a,stroke-width:1.5px
 ```

-## Runtime Sockets
+## Runtime sockets

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

@@ -67,7 +67,7 @@ flowchart LR

 How these sockets are established during launch is covered in [Playback Startup Flow](./architecture#playback-startup-flow).

-## Core Surfaces
+## Core surfaces

 | File | Role |
 | --- | --- |
@@ -79,7 +79,7 @@ How these sockets are established during launch is covered in [Playback Startup
 | `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. |

-## 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.

@@ -89,13 +89,13 @@ These rules exist to prevent a class of bugs where the renderer and main process
 - **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
+## 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`.
@@ -104,7 +104,7 @@ These rules exist to prevent a class of bugs where the renderer and main process
 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
+## 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.
@@ -116,7 +116,7 @@ These rules exist to prevent a class of bugs where the renderer and main process
 - **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.

-## Related Docs
+## Related docs

 - [Architecture](/architecture)
 - [Development](/development)
@@ -1,12 +1,12 @@
-# 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.
+[Jellyfin](https://jellyfin.org) is a free, self-hosted media server, a private streaming service for video you already own. If your anime lives on a Jellyfin server, SubMiner plays episodes from it through mpv with the mining overlay 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.
+This page only matters if you already run a Jellyfin server or have access to one. Watching local files or YouTube? Skip it. Otherwise start with the in-app setup window (`subminer jellyfin`).
 :::

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

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

@@ -18,11 +18,11 @@ This is the recommended way to use Jellyfin with SubMiner. A terminal-only optio

 ## Quick start

-### 1. Start SubMiner
+### 1. start SubMiner

-Launch SubMiner so it's running in the system tray.
+Launch SubMiner and leave it in the system tray.

-### 2. Sign in to your server
+### 2. sign in to your server

 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**.

@@ -34,14 +34,14 @@ On success, SubMiner:

 Reopen this window any time to switch servers or **Logout**.

-### 3. Turn on discovery
+### 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
+### 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.

@@ -54,7 +54,7 @@ From then on, pause / resume / seek / stop and audio or subtitle track changes y
 - **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.
+- **Downloaded subtitles keep their original timing.** 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 the subtitle files exposed by Jellyfin without letting mpv auto-switch between tracks, resets mpv's subtitle delay to zero, then selects the Japanese track. SubMiner does not compare Japanese and English cue timelines or save an inferred delay.

 ## Settings

@@ -1,16 +1,16 @@
-# 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 subtitle repository for anime, built from files other learners uploaded. SubMiner talks to the Jimaku API, so you search, browse, and download Japanese subtitle files from inside the overlay. No alt-tabbing, no moving files around. A downloaded track loads into mpv right away.

 ::: 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."
 :::

-## How It Works
+## 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.
+When you open the modal, SubMiner parses the current video filename to extract a title, season, and episode number. It handles `S01E03`, `1x03`, `E03`, and dash-separated episode numbers. If the filename yields a high-confidence match (title + episode), SubMiner auto-searches immediately.

 From there:

@@ -21,7 +21,7 @@ From there:

 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
+### Modal keyboard shortcuts

 | Key | Action |
 | --- | --- |
@@ -64,7 +64,7 @@ The keyboard shortcut is configured separately under `shortcuts`:
 }
 ```

-### API Key
+### API key

 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:

@@ -73,7 +73,7 @@ An API key is required to use the Jimaku integration. You can get one from [jima

 If both are set, `apiKey` takes priority.

-## Filename Parsing
+## Filename parsing

 SubMiner extracts media info from the current video path to pre-fill the search fields. The parser handles:

@@ -1,14 +1,22 @@
-# 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.
+The `subminer` launcher handles video selection, mpv startup, and overlay management in one script. It guarantees mpv starts with the right IPC socket and SubMiner defaults. On Windows, the **SubMiner mpv** shortcut remains the recommended playback entry point.
+
+The launcher is a small wrapper around the CLI bundled in the desktop app. It locates a normal SubMiner installation, or uses `SUBMINER_BINARY_PATH` when you set a custom executable. Linux also accepts `SUBMINER_APPIMAGE_PATH`. First-run setup records the selected app location for the wrapper. You do not need Bun installed or on `PATH`; only the directory containing `subminer` needs to be on `PATH`.
+
+On macOS, the wrapper runs Bun and the CLI directly from `SubMiner.app/Contents/Resources`. On Windows, `subminer.cmd` stages a versioned private Bun copy under `%LOCALAPPDATA%\SubMiner\launcher-runtime/<version>` and runs the CLI from the current app. Keeping the executable outside the app avoids locking an updater-owned file while a launcher is running. Old runtime versions are removed when no running launcher is using them.
+
+On Linux, the first launch caches Bun and its matching CLI and license files under `${XDG_DATA_HOME:-~/.local/share}/SubMiner/launcher`. Later launches make one `stat` call against the AppImage and run the cache without starting Electron. A missing cache or changed app fingerprint rebuilds it. App startup also refreshes the managed payload after an update.
+
+The downloaded `subminer` and `subminer.cmd` release assets use the same private runtime flow. Older launcher scripts that were installed before this change cannot update their own code retroactively and still need system Bun until the app migrates them at startup or you download a current wrapper.

 ::: 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
+## 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.
+Run `subminer` with no file and it opens an interactive picker. That is **fzf** in the terminal by default, or **rofi** with `-R`.

 ### fzf (default)

@@ -34,18 +42,22 @@ 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 the rofi theme plus the Linux launcher-managed runtime plugin copy in the release assets tarball:
+rofi shows a GUI menu with icon thumbnails when available. SubMiner ships the rofi theme, a scoped `ffmpegthumbnailer` MIME registration, and the Linux launcher-managed runtime plugin copy in the release assets tarball:

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

-Once the `SubMiner` data dir exists, `subminer -u` refreshes both assets automatically. Normal Linux launcher playback also checks for the managed runtime plugin copy and rofi theme before mpv launch and installs them from the bundled app automatically if either one is missing.
+Once the `SubMiner` data dir exists, `subminer -u` refreshes these assets automatically. Normal Linux launcher playback checks for all three assets and installs them from the bundled app when one is missing. For `subminer -R`, this repair runs before rofi opens.
+
+When `ffmpegthumbnailer` is installed, SubMiner prepends its own data directory to `XDG_DATA_DIRS` for the rofi process only. This lets rofi recognize the canonical Matroska MIME types used by newer GLib versions without changing the desktop-wide MIME or thumbnailer configuration. An existing registration in your own `$XDG_DATA_HOME/thumbnailers` still takes priority.

 The theme is auto-detected from these paths (first match wins):

@@ -62,7 +74,7 @@ Override with the `SUBMINER_ROFI_THEME` environment variable:
 SUBMINER_ROFI_THEME=/path/to/custom-theme.rasi subminer -R
 ```

-## Watch History
+## Watch history

 `subminer -H` (or `--history`) browses your local watch history, sourced from the immersion tracker database. It works with both pickers: fzf by default, rofi with `-R -H`.

@@ -83,7 +95,7 @@ After an episode ends or you close mpv, the launcher returns to an action menu f

 Series whose directories are not currently accessible (e.g. an unmounted network share) are hidden from the list. Watch history requires the immersion tracker database (`immersionTracking.dbPath`, default `<config dir>/immersion.sqlite`), which SubMiner populates during playback.

-## Sync Between Machines
+## Sync between machines

 `subminer sync <host>` merges immersion stats and watch history between two machines over SSH, so both end up with the union of sessions, lifetime totals, vocabulary counts, daily/monthly charts, and `--history` entries. `<host>` is anything `ssh` accepts (`user@hostname` or an ssh config alias); SubMiner must be installed on both machines at the same version. The sync engine runs only inside the app (`SubMiner --sync-cli sync ...`): the sync window spawns it that way, `subminer sync` is a thin proxy that forwards to the installed app, and the remote side is found automatically whether it has the launcher or just the app. The command-line launcher is optional everywhere.

@@ -131,7 +143,7 @@ Unfinished sessions (a crash mid-playback) are skipped until the app finalizes t

 Hosts with **Auto-sync** enabled are synced in the background on a configurable interval (default every 60 minutes), including during active playback; results surface as overlay notifications. The unfinished playback session is skipped until a later sync sees it finalized. Host bookkeeping lives in `<config dir>/sync-hosts.json`.

-## Common Commands
+## Common commands

 ```bash
 subminer video.mkv                      # play a specific file (managed launches auto-start the visible overlay by default)
@@ -151,6 +163,7 @@ subminer stats -b                       # start background stats daemon
 | `subminer stats`                           | Start the stats server (opens the dashboard when `stats.autoOpenBrowser` is on)                   |
 | `subminer stats -b` / `-s`                 | Start/reuse or stop the background stats daemon                                                   |
 | `subminer stats cleanup`                   | Backfill vocabulary metadata and prune stale rows (`-v` vocab, `-l` lifetime summaries)           |
+| `subminer stats cleanup -d`                | Collapse repeated lines from typeset subs (`--dry-run`, `--lookback-days <n>`)                    |
 | `subminer stats rebuild` / `backfill`      | Rebuild or backfill rollup data                                                                   |
 | `subminer doctor`                          | Dependency + config + socket diagnostics (`--refresh-known-words` refreshes the known-word cache) |
 | `subminer settings`                        | Open the SubMiner settings window                                                                 |
@@ -21,6 +21,7 @@ function slugify(heading: string): string {
 }

 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> {
@@ -114,7 +115,7 @@ test('slugify matches the VitePress cases these docs actually rely on', () => {
  expect(slugify('2. Install SubMiner')).toBe('_2-install-subminer');
 });

-test('every docs page is reachable from the sidebar', async () => {
+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 }>;
@@ -127,6 +128,8 @@ test('every docs page is reachable from the sidebar', async () => {
    }
  }

-  const orphans = [...pages.keys()].filter((route) => !linked.has(route));
+  const orphans = [...pages.keys()].filter(
+    (route) => !linked.has(route) && !UNLISTED_ROUTES.has(route),
+  );
  expect(orphans).toEqual([]);
 });
@@ -1,20 +1,20 @@
-# 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.
+This guide walks the whole sentence mining loop, from starting a video to ending up with an Anki card that has audio, a screenshot, and the surrounding sentence.

 ## Overview

-_Sentence mining_ means turning real sentences you encounter while watching native video into Anki flashcards, so you learn vocabulary in the context where you actually met it. SubMiner automates the tedious parts of that loop.
+_Sentence mining_ means turning sentences you hit while watching native video into Anki cards, so you learn a word in the context where you first met it. The idea is old. The tedious part is everything between spotting the word and having a finished card, and that is the part SubMiner does for you.

-SubMiner runs as a transparent overlay on top of mpv (the video player). As subtitles play, the overlay displays them as interactive text. You hover a word, trigger a Yomitan dictionary lookup with your configured lookup key/modifier, then create an Anki card with a single action. SubMiner automatically attaches the sentence, an audio clip, and a screenshot to that card - no manual copy-pasting or screen capturing.
+SubMiner draws a transparent overlay on top of mpv and renders each subtitle line as interactive text. Hover a word, trigger a Yomitan lookup with your configured key or modifier, then add the card. SubMiner attaches the sentence, an audio clip, and a screenshot on its own, so there is nothing to copy-paste or screenshot by hand.

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

-## Creating Anki Cards
+## Creating Anki cards

 There are four ways to create or enrich cards, depending on your workflow.

-### 1. Auto-Update from Yomitan
+### 1. Auto-update from Yomitan

 This is the most common flow. Yomitan creates a card in Anki, and SubMiner enriches it automatically.

@@ -27,23 +27,22 @@ This is the most common flow. Yomitan creates a card in Anki, and SubMiner enric
   - **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.

 Configure which fields to fill in `ankiConnect.fields`. See [Anki Integration](/anki-integration) for details.

-### 2. Manual Update from Clipboard
+### 2. manual update from clipboard

 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:

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

-Manual clipboard updates always replace generated sentence audio, even when `ankiConnect.behavior.overwriteAudio` is disabled. The word audio field is left unchanged because the word itself does not change in this flow.
+Manual clipboard updates always replace generated sentence audio in `ankiConnect.fields.audio`, even when `ankiConnect.behavior.overwriteAudio` is disabled. Normal word-card updates use the configured sentence and audio fields even when Lapis or Kiku support is enabled.

-This is useful when auto-update is disabled or when you want explicit control over which subtitle line gets attached to the card.
+Use this when auto-update is off, or when the line you want on the card is not the line currently on screen.

 | Shortcut                   | Action                          | Config key                              |
 | -------------------------- | ------------------------------- | --------------------------------------- |
@@ -51,7 +50,7 @@ This is useful when auto-update is disabled or when you want explicit control ov
 | `Ctrl/Cmd+Shift+C` + digit | Copy multiple recent lines      | `shortcuts.copySubtitleMultiple`        |
 | `Ctrl/Cmd+V`               | Update last card from clipboard | `shortcuts.updateLastCardFromClipboard` |

-### 3. Mine Sentence (Hotkey)
+### 3. mine Sentence (hotkey)

 Create a standalone sentence card without going through Yomitan:

@@ -64,7 +63,7 @@ The sentence card uses the note type configured in `isLapis.sentenceCardModel` a
 Sentence card creation requires `ankiConnect.isLapis.sentenceCardModel` to name a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type that exists in Anki (default: `"Lapis"`). See [Anki Integration - Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
 :::

-### 4. Mark as Audio Card
+### 4. mark as audio card

 After adding a word via Yomitan, press the audio card shortcut (`Ctrl/Cmd+Shift+A` by default, `shortcuts.markAudioCard`) to mark the card as an audio card. This sets the audio-card flag and fills sentence, image, and metadata fields alongside the full-subtitle audio clip.

@@ -72,27 +71,27 @@ After adding a word via Yomitan, press the audio card shortcut (`Ctrl/Cmd+Shift+
 Audio card marking uses the same `ankiConnect.isLapis.sentenceCardModel` note type as sentence cards. See [Anki Integration - Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
 :::

-### Field Grouping (Kiku)
+### Field grouping (Kiku/Senren)

-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 you mine the same word from different sentences, SubMiner can merge the cards instead of creating duplicates. This is built for [Kiku](https://github.com/youyoumu/kiku) and [Senren](https://github.com/BrenoAqua/Senren) note types that support grouped fields (Senren calls it scene switching).

 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.
+3. If a duplicate is found (this requires Kiku or Senren to be enabled with a field grouping mode of `"auto"` or `"manual"`):
+   - **Auto mode**: Merges automatically. Both sentences, audio clips, images, and source info are combined into the existing card. The duplicate is optionally deleted.
+   - **Manual mode**: A modal appears showing both cards side by side. You choose which card to keep and preview the merged result before confirming.

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

-## Overlay Model
+## 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
+### 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:
+The primary bar renders each subtitle as separate hoverable word spans, each carrying its reading and headword. Its styling is independent of mpv's own subtitle rendering. It supports:

 - Word-level hover targets for Yomitan lookup
 - Auto pause/resume on subtitle hover (enabled by default via `subtitleStyle.autoPauseVideoOnHover`)
@@ -101,16 +100,17 @@ The primary bar renders subtitles as tokenized hoverable word spans. Each word i
 - 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
+### 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:
+The secondary bar is a compact top-strip region in the same overlay window. It shows a secondary subtitle track, usually English, above the primary reading line. Use it to sanity-check your comprehension without breaking out of the mining flow.

- 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).
+For local media, SubMiner can parse supported embedded secondary tracks into timed cues. For remote URLs and files on network mounts, it uses mpv's live secondary subtitle text instead of scanning the media with ffmpeg.

-It is controlled by `secondarySub` configuration and shares its lifecycle with the main overlay window. Cycle which track feeds it with `Shift+J`.
+The `secondarySub` config controls it, and it opens and closes with the main overlay window. Cycle which track feeds it with `Shift+J`.

-### Display Modes
+SubMiner collapses duplicate ASS layers in parsed secondary tracks. Exact repeated lines collapse at any length, while distinct simultaneous short lines remain separate. Long dialogue and positioned-sign copies also collapse when they differ only in whitespace or terminal punctuation. Dense multi-row sign layouts, such as translated timetables, are excluded instead of being concatenated into the secondary bar.
+
+### Display modes

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

@@ -127,11 +127,11 @@ Cycle each bar's mode at runtime with its own shortcut:
 | `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
+### 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
+## 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.
@@ -139,7 +139,7 @@ Jimaku search, field-grouping, runtime options, and manual subsync open as modal
 4. Yomitan opens its lookup popup for the hovered token.
 5. From the popup, add the word to Anki.

-### Controller Workflow
+### Controller workflow

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

@@ -151,11 +151,11 @@ With a gamepad connected and keyboard-only mode enabled, the full mining loop wo
 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.
+Once controller support is on, the controller and keyboard both stay live. You can drop the controller mid-episode and keep going with the keyboard. Toggle keyboard-only mode 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)
+## 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).

@@ -169,24 +169,22 @@ The reference and the out-of-sync subtitle must be different tracks; the referen

 For remote streams, including Jellyfin playback, the modal only offers alass with a subtitle reference. Jellyfin subtitle URLs are cached as temporary subtitle files so alass can read them, but the video stream is not downloaded. ffsubsync and the video-file reference need direct access to the local media file and are 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.

 ## Texthooker

-SubMiner runs a local HTTP server at `http://127.0.0.1:5174` (fixed default port; overridable only via the mpv plugin's `texthooker_port` script-opt) that serves a texthooker UI. This allows external tools - such as a browser-based Yomitan instance - to receive subtitle text in real time.
+SubMiner serves a texthooker UI from a local HTTP server at `http://127.0.0.1:5174`. The port is fixed unless you override it with the mpv plugin's `texthooker_port` script-opt. External tools read subtitle text from it as lines arrive, which is how you would feed a browser-based Yomitan instance.

 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.

 If you want to build your own browser client, websocket consumer, or automation relay, see [WebSocket / Texthooker API & Integration](/websocket-texthooker-api).

-## Related Features
+## Related features

-These features support the mining loop but have their own dedicated pages:
+These feed into the mining loop but each has its own page:

 - **[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#n-1-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.
+- **[N+1 word highlighting](/subtitle-annotations#n-1-word-highlighting)** - reads your Anki decks and highlights words you already know, so a line with exactly one unknown word stands out while you watch.
 - **[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.
@@ -1,12 +1,12 @@
-# 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 small Lua script that runs _inside_ mpv. It binds in-player keys for controlling the overlay, so start, stop, toggle, and skip-intro all work without leaving the player window.

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

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

-## Runtime Loading
+## Runtime loading

 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.

@@ -67,7 +67,7 @@ The AniSkip key is **not** a `y` chord and is not bound by the plugin: the SubMi

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

-## Shared Shortcuts (Session Bindings)
+## Shared shortcuts (session bindings)

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

@@ -104,7 +104,7 @@ SubMiner:

 Select an item by pressing its number.

-## Binary Auto-Detection
+## Binary auto-detection

 When `binary_path` is empty, the plugin searches platform-specific locations:

@@ -131,7 +131,7 @@ A PowerShell system lookup runs first (running SubMiner process, registry App Pa

 On Windows the plugin also normalizes a Unix-style `socket_path` (`/tmp/subminer-socket`) to the named pipe `\\.\pipe\subminer-socket` at runtime.

-## Backend Detection
+## Backend detection

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

@@ -145,7 +145,7 @@ When `backend=auto`, the plugin detects the window manager:
 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
+## Script messages

 The plugin can be controlled from other mpv scripts or the mpv command line using script messages:

@@ -189,7 +189,7 @@ For how the plugin's auto-start fits into the full launch sequence - including w
 - **MPV shutdown**: The plugin clears its hover/OSD/gate state on shutdown; the overlay app notices the closed IPC socket and shuts itself down.
 - **Texthooker**: When `texthooker_enabled=yes`, the plugin appends `--texthooker` to the overlay start command so the app starts the texthooker server alongside the overlay.

-## Using with the `subminer` Wrapper
+## 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.

@@ -523,7 +523,7 @@
  // ==========================================
  // AnkiConnect Integration
  // Automatic Anki updates and media generation options.
-  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/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.
  // ==========================================
@@ -569,6 +569,7 @@
      "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.
@@ -606,6 +607,11 @@
      "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.
+    "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.
@@ -56,34 +56,43 @@ 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 () => {
-  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');
+test.each([
+  ['latest stable', 'v0.14.0', '/v/0.14.0/', 'https://docs.subminer.moe/v/0.14.0/usage'],
+  ['superseded', '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 (_label, 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 = base;
+    process.env.SUBMINER_DOCS_VERSION = version;
+    process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
+    try {
+      const { default: archiveConfig } = await import(`./.vitepress/config?archive-${version}`);

-  const head = await latestArchiveConfig.transformHead?.(makeTransformContext('usage.md'));
+      const head = await archiveConfig.transformHead?.(makeTransformContext('usage.md'));

-  expect(head).toContainEqual([
-    'link',
-    { rel: 'canonical', href: 'https://docs.subminer.moe/usage' },
-  ]);
-
-  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;
-});
+      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 () => {
  const previousCwd = process.cwd();
@@ -433,3 +442,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;
+  }
+});
@@ -1,4 +1,4 @@
-# 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.

@@ -10,7 +10,7 @@ A few terms used throughout:

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

-## App-Wide Shortcuts
+## App-wide shortcuts

 | Shortcut      | Action                 | Scope                                       | Configurable                           |
 | ------------- | ---------------------- | -------------------------------------------- | -------------------------------------- |
@@ -21,10 +21,12 @@ All shortcuts are configurable in `config.jsonc` under `shortcuts` and `keybindi
 `Alt+Shift+O` is dispatched by the overlay window and the mpv plugin, so it works from either surface without OS registration. Only `Alt+Shift+Y` is registered with the OS; if it conflicts with another application, that binding cannot be changed. All `shortcuts.*` keys hot-reload - no restart needed.
 :::

-## Mining Shortcuts
+## Mining shortcuts

 These work when the overlay window has focus.

+When text is selected in the [subtitle sidebar](./subtitle-sidebar.md#selecting-and-copying-dialogue), `Ctrl/Cmd+C` copies that selection without timestamps, taking priority over the current-subtitle action. `Escape` clears the sidebar selection.
+
 | Shortcut           | Action                                          | Config key                              |
 | ------------------ | ----------------------------------------------- | --------------------------------------- |
 | `Ctrl/Cmd+S`       | Mine current subtitle as sentence card          | `shortcuts.mineSentence`                |
@@ -35,9 +37,9 @@ These work when the overlay window has focus.
 | `Ctrl/Cmd+G`       | Trigger field grouping (Kiku merge check)       | `shortcuts.triggerFieldGrouping`        |
 | `Ctrl/Cmd+Shift+A` | Mark last card as 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.
+The multi-line shortcuts open a digit selector with a 3-second timeout (`shortcuts.multiCopyTimeoutMs`). Press `1`–`9` to select the total number of subtitle lines to combine, ending at the current line and moving backward through the subtitle timeline. The current line counts toward the selected total. When the shortcut starts from mpv, SubMiner focuses the visible overlay for that selector instead of reserving the number keys in the mpv plugin.

-## Overlay Controls
+## Overlay controls

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

@@ -73,7 +75,7 @@ On macOS managed playback, SubMiner disables mpv's menu-bar shortcuts so configu

 Mouse-hover playback behavior is configured separately from shortcuts: `subtitleStyle.autoPauseVideoOnHover` defaults to `true` (pause on subtitle hover, resume on leave).

-## Subtitle & Feature Shortcuts
+## Subtitle and feature shortcuts

 | Shortcut           | Action                                                   | Config key                                 |
 | ------------------ | -------------------------------------------------------- | ------------------------------------------ |
@@ -97,7 +99,7 @@ The stats toggle is handled inside the focused visible overlay window. It is con

 The subtitle sidebar toggle is overlay-local and only opens when SubMiner has a parsed cue list for the active subtitle source.

-## Controller Shortcuts
+## Controller shortcuts

 These overlay-local shortcuts open controller utilities for the Chrome Gamepad API integration.

@@ -108,7 +110,7 @@ These overlay-local shortcuts open controller utilities for the Chrome Gamepad A

 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
+## MPV plugin chords

 When the mpv plugin is installed, all commands use a `y` chord prefix - press `y`, then the second key (the overlay-side chord times out after 1 second; the mpv plugin uses native mpv key sequences).

@@ -128,14 +130,14 @@ The bare `v` plugin binding intentionally overrides mpv's native primary subtitl

 When the overlay has focus, press `y` then `d` to toggle DevTools (debugging helper).

-## Drag-and-Drop
+## 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
+## 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.

@@ -1,20 +1,20 @@
-# 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 annotates subtitle tokens as they appear in the overlay. There are four layers: **N+1 highlighting**, **character-name highlighting**, **frequency highlighting**, and **JLPT tagging**.

-All four are opt-in and configured under `subtitleStyle`, `ankiConnect.knownWords`, and `ankiConnect.nPlusOne` in your config. They apply independently - you can enable any combination.
+All four are off by default and live under `subtitleStyle`, `ankiConnect.knownWords`, and `ankiConnect.nPlusOne`. They are independent, so any combination works.

 ::: 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.
+Yomitan is the tokenizer, so the dictionaries you installed there decide where word boundaries fall. Piling on large dictionaries adds noise and slows lookups. Be picky about which ones you install and what order you rank them in.
 :::

 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.

 Kanji vocabulary that MeCab labels `名詞/非自立`, such as `日` or `以外`, remains content for every annotation layer. The `非自立` exclusion only suppresses kana grammar nouns such as `こと` and `もの`.

-## N+1 Word Highlighting
+## N+1 word highlighting

-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.
+An N+1 sentence is one where you know every word but a single unknown. Those are the best mining targets, because the rest of the sentence gives you the context for free. SubMiner caches your known vocabulary from Anki and marks the lines that qualify.

 **How it works:**

@@ -43,9 +43,9 @@ Prefer expression/word fields for `ankiConnect.knownWords.decks`. Reading-only f
 Set `refreshMinutes` to `1440` (24 hours) for daily sync if your Anki collection is large.
 :::

-## Known-Word Maturity Highlighting
+## Known-word maturity highlighting

-Instead of one color for every known word, maturity highlighting tints each known token by the review state of its Anki cards (like asbplayer), giving an at-a-glance sense of how much of a line is solidly learned.
+Maturity highlighting tints each known token by the review state of its Anki cards instead of painting every known word the same color, so you can see how much of a line you actually have down. asbplayer does the same thing.

 **How it works:**

@@ -81,7 +81,7 @@ bun run verify-known-word-highlights:electron -- --input /path/to/episode.ja.srt

 It tokenizes every cue through the real Yomitan/MeCab pipeline with your live known-word cache, prints each line in your configured tier colors, and summarizes the tier counts. `--audit` re-derives each highlighted tier from live Anki card data (`notesInfo` + `cardsInfo` intervals) and lists any token whose color disagrees, with the note ids and intervals behind it. Electron locks the Yomitan profile, so quit SubMiner first or pass `--profile-copy` to run against a scratch copy. Other useful flags: `--refresh` (refresh the cache first), `--limit <n>`, `--quiet`, `--json`.

-## Character-Name Highlighting
+## Character-name highlighting

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

@@ -102,9 +102,9 @@ Character-name matches are built from the active merged SubMiner character dicti

 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

-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. For each token, ranks from the installed Yomitan frequency dictionaries are consulted in priority order: the highest-priority dictionary that has the term wins, lower-priority dictionaries fill in terms it lacks, and occurrence-based dictionaries are skipped.
+Frequency highlighting colors tokens by how common the word is, so a rare word in an otherwise easy line stands out. Ranks come from your installed Yomitan frequency dictionaries, read in priority order. The highest-priority dictionary that has the term wins, lower-priority ones fill in terms it lacks, and occurrence-based dictionaries are skipped.

 **Modes:**

@@ -137,9 +137,9 @@ Frequency highlighting skips tokens that look like non-lexical noise (kana redup
 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.
 :::

-## JLPT Tagging
+## JLPT tagging

-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.
+JLPT tagging underlines each token in a color for its JLPT level (N1–N5), so the difficulty spread of a line is visible without reading it closely.

 **How it works:**

@@ -164,7 +164,7 @@ All colors are customizable via the `subtitleStyle.jlptColors` object.
 | `subtitleStyle.enableJlpt`         | `false`   | Enable JLPT underline styling |
 | `subtitleStyle.jlptColors.N1`–`N5` | see above | Per-level underline colors    |

-## Runtime Toggles
+## Runtime toggles

 These annotation layers can be toggled at runtime via the runtime options palette (`Ctrl/Cmd+Shift+O`) without restarting:

@@ -177,9 +177,9 @@ These annotation layers can be toggled at runtime via the runtime options palett

 (Character-name matching, `subtitleStyle.nameMatchEnabled`, is toggled through config or the Settings window, not the runtime palette.)

-Toggles only apply to new subtitle lines after the change - the currently displayed line is not re-tokenized in place.
+A toggle takes effect on the next subtitle line. SubMiner does not re-tokenize the line already on screen.

-## Rendering Priority
+## Rendering priority

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

@@ -1,26 +1,36 @@
-# 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 puts the whole parsed cue list for the active subtitle file in a scrollable panel next to mpv. Scroll back through lines you already passed, look ahead at what is coming, and click any cue to seek straight to it. The overlay only ever shows the current line; the sidebar shows the rest.

 The sidebar is enabled by default. Set `subtitleSidebar.enabled` to `false` if you want to turn it off.

-## How It Works
+## How it works

 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:

 - 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.
+- Clicking any cue seeks mpv into that line. For overlapping ASS karaoke, SubMiner moves past the previous line's exit animation when the selected cue has enough time remaining.
+- The sidebar and the overlay share one cue list, so a media change or subtitle source switch updates both at once.

-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 typeset ASS karaoke and animated signs, SubMiner collapses generated animation frames and repeated full-line color phases before they reach the sidebar. It recovers a clean complete line from a matching timed authoring comment or from full-line events surrounding generated fragments. Ordinary ASS comments, editor notes, alternate lines, repeated dialogue, and separately positioned signs remain distinct.

-## Layout Modes
+The sidebar only opens when a parsed cue list exists. Subtitle sources SubMiner cannot parse, such as embedded ASS tracks that mpv renders itself, leave it empty.
+
+## Selecting and copying dialogue
+
+Drag across subtitle text to select an excerpt, including across multiple rows. Scroll to extend a selection through a longer conversation. `Ctrl/Cmd+C` or the **Copy** button copies the highlighted text in subtitle order, without timestamps. Partial first and last lines are preserved, with a blank line between subtitle cues.
+
+Dragging to select does not seek playback. Playback-following auto-scroll stops while you drag or have a selection, so the excerpt stays in view. Press `Escape` to clear the selection. An ordinary click with no selection still seeks to that cue.
+
+Selection survives playback updates and Yomitan popup dismissal. Changing media or subtitle sources, refreshing the cue list, or closing the sidebar clears it. Copying an excerpt does not require creating an Anki card.
+
+## Layout modes

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

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

-**`embedded`** - Reserves space on the right side of the player and shifts the video area to mimic a split-pane layout. Useful if you want the cue list visible without it covering the video. If you see unexpected positioning in your environment, switch back to `overlay` to isolate the issue.
+**`embedded`** - Reserves space on the right side of the player and shifts the video area over, giving you a split pane. Use this when you want the cue list up without it covering the video. Positioning depends on the compositor, so switch back to `overlay` if the geometry comes out wrong.

 ## Configuration

@@ -75,7 +85,7 @@ Styling lives under the `css` object, using CSS property names and CSS custom pr
 | `--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
+## Keyboard shortcut

 | Key | Action                  | Config key                     |
 | --- | ----------------------- | ------------------------------ |
@@ -1,14 +1,16 @@
 # 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.
+Almost everything that goes wrong lands in one of three places. The overlay shows but no subtitles arrive, which is [MPV Connection](#mpv-connection). Cards get created but come out empty, which is [AnkiConnect](#ankiconnect). Or hovering a word does nothing, which is [Yomitan](#yomitan).

-## MPV Connection
+If you got an error message on screen, search this page for its exact text. Most headings below are quoted error strings.
+
+## MPV connection

 **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`.
+- Check that 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.

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

 **"Failed to parse MPV message"**

-Logged when a malformed JSON line arrives from the mpv socket. Usually harmless - SubMiner skips the bad line and continues. If it happens constantly, check that nothing else is writing to the same socket path.
+A malformed JSON line arrived from the mpv socket. SubMiner drops the line and keeps going, so a stray one is harmless. A constant stream of them means something else is writing to the same socket path.

 ## Updates

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

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

- Make sure you are hovering over subtitle text - the overlay only becomes interactive when the cursor is over a subtitle.
+- Hover directly over subtitle text. The overlay only takes pointer input while 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.

@@ -99,9 +101,9 @@ Shown when SubMiner tries to update a card that no longer exists, or when AnkiCo

 SubMiner positions the overlay by tracking the mpv window. If tracking fails:

- Hyprland: Ensure `hyprctl` is available.
- Sway: Ensure `swaymsg` is available.
- X11: Ensure `xdotool` and `xwininfo` are installed.
+- Hyprland: `hyprctl` must be on `PATH`.
+- Sway: `swaymsg` must be on `PATH`.
+- X11: `xdotool` and `xwininfo` must be installed.

 If the overlay position is slightly off, right-click and drag on subtitle text to fine-tune the overlay subtitle offset.

@@ -124,12 +126,12 @@ If you installed from the AppImage and see this error, the package may be incomp

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

- Verify Yomitan loaded successfully - check the terminal output for "Loaded Yomitan extension".
+- Look for "Loaded Yomitan extension" in the terminal output.
 - 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.

-## MeCab / Tokenization
+## MeCab / tokenization

 **"MeCab not found on system"**

@@ -145,19 +147,19 @@ To install MeCab:

 Japanese word boundaries depend on Yomitan parser output. If segmentation seems wrong:

- Verify Yomitan dictionaries are installed and active.
- Note that CJK characters without spaces are segmented using parser heuristics, which is not always perfect.
+- Check that Yomitan dictionaries are installed and active.
+- Japanese text has no spaces, so the parser guesses word boundaries. It gets some of them wrong.

-## Character Dictionary
+## Character dictionary

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

- **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.
+- **Names not highlighting:** Check that `subtitleStyle.nameMatchEnabled` is `true` and that the current media resolved to an AniList entry, since SubMiner needs a media ID to fetch characters. No AniList account or token is needed; character data comes from public GraphQL queries.
+- **Inline portraits missing:** Check that `subtitleStyle.nameMatchImagesEnabled` is `true`. AniList also has to return an image, and the download has to succeed while the snapshot is generated.
 - **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.

-## Media Generation
+## Media generation

 **"FFmpeg not found"**

@@ -171,7 +173,9 @@ Without FFmpeg, card creation still works but audio and image fields will be emp

 **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:
+Audio extraction has a 2-minute timeout. SubMiner also limits FFmpeg probing when mpv provides the selected audio stream, which avoids scanning unrelated subtitle and font-attachment streams in large MKV files. Screenshots retain a 30-second timeout, and animated AVIF uses 60 seconds.
+
+If your video file is on a slow or unresponsive network mount, generation may still time out. Try:

 - Using a local copy of the video file.
 - Reducing `ankiConnect.media.imageQuality` or switching from `avif` to `static` image type.
@@ -191,7 +195,7 @@ This warning refers to the OS-registered shortcut `Alt+Shift+Y` (Yomitan setting

 Overlay-local shortcuts (Space, arrow keys, etc.) only work when the overlay window has focus. Click on the overlay or use `Alt+Shift+O` (with the overlay or mpv focused) to toggle it and give it focus.

-## Subtitle Timing
+## Subtitle timing

 **"Subtitle timing not found; copy again while playing"**

@@ -203,7 +207,7 @@ This OSD message appears when you try to mine a sentence but SubMiner has no tim

 Resume playback and wait for the next subtitle to appear, then try mining again.

-## Subtitle Sync (Subsync)
+## Subtitle sync (subsync)

 Both **alass** and **ffsubsync** are optional external dependencies. Subtitle syncing requires at least one of them to be installed.

@@ -227,8 +231,8 @@ Install ffsubsync or configure the path:

 If subtitle sync fails (the error message is prefixed with the engine name):

- Ensure a reference is selected (alass needs either a second subtitle track or the local video file, and it cannot be the same track that is being retimed).
- Check that `ffmpeg` is available (used to extract the internal subtitle track).
+- Select a reference. alass needs either a second subtitle track or the local video file, and it cannot be the track being retimed.
+- Check that `ffmpeg` is available, since it extracts 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).

@@ -252,23 +256,23 @@ Most Linux distributions ship it already. See [TsukiHime Integration](/tsukihime

 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.

-## Logging and App Mode
+## 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
+## Performance and resource impact

-### At a glance
+### Where the cost comes from

- 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)
+Idle playback with the overlay up is cheap. The 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

@@ -283,19 +287,16 @@ The Jimaku API has rate limits. If you see 429 errors, wait for the retry durati
 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)
+- keep `ankiConnect.media.imageType` set to `static`, since animated AVIF encoding is the most expensive path
 - 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
+- set `immersionTracking.enabled: false` to stop session logging and its database writes

 ### Practical low-impact profile

@@ -318,9 +319,6 @@ The Jimaku API has rate limits. If you see 429 errors, wait for the retry durati
      "imageType": "static",
      "imageQuality": 80,
      "maxMediaDuration": 12
-    },
-    "ai": {
-      "enabled": false
    }
  },
  "immersionTracking": {
@@ -336,12 +334,12 @@ The Jimaku API has rate limits. If you see 429 errors, wait for the retry durati
 - 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.

-## Platform-Specific
+## Platform-specific

 ### Linux

- **Wayland (Hyprland/Sway only)**: Native Wayland support is limited to Hyprland and Sway. Window tracking uses compositor-specific commands (`hyprctl` / `swaymsg`). If these are not on `PATH`, tracking will fail silently. Other Wayland compositors (KDE Plasma, GNOME, …) are not supported natively - both mpv and SubMiner must run under X11 or Xwayland instead. On those sessions SubMiner forces XWayland automatically for itself and for every mpv it launches (see [KDE Plasma & other Wayland compositors](#kde-plasma-other-wayland-compositors)).
- **X11 / Xwayland**: Requires `xdotool`, `xprop`, and `xwininfo`. If missing, the overlay cannot track the mpv window position. This is the required backend for any Wayland compositor other than Hyprland or Sway - both mpv and SubMiner must be running under X11/Xwayland for window tracking _and_ for the overlay to stay above mpv (Wayland forbids clients from controlling window stacking). SubMiner uses a managed X11 overlay while mpv is windowed, switches to an override-redirect X11 overlay while tracked mpv is fullscreen, and hides/releases that overlay when another X11/Xwayland app takes focus. The visible overlay stays hidden until SubMiner has tracked mpv geometry, so startup should not create a display-sized fallback overlay while tokenization warms up.
+- **Wayland (Hyprland/Sway only)**: Native Wayland support covers Hyprland and Sway only. Window tracking shells out to `hyprctl` or `swaymsg`; if neither is on `PATH`, tracking fails silently. Other Wayland compositors such as KDE Plasma and GNOME have no native backend - 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-and-other-wayland-compositors)).
+- **X11 / Xwayland**: Needs `xdotool`, `xprop`, and `xwininfo`. Without them 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.

@@ -399,7 +397,7 @@ SubMiner watches mpv's `fullscreen` property and refreshes the overlay geometry

 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/).

-### KDE Plasma & other Wayland compositors
+### KDE Plasma and other Wayland compositors

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

@@ -421,7 +419,7 @@ Requirements: `xdotool`, `xprop`, and `xwininfo` must be installed. SubMiner use
 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=x11vk,x11egl,x11 …`, or launch with `WAYLAND_DISPLAY= mpv …`, or set `gpu-context=x11vk` (Vulkan) / `gpu-context=x11egl` (OpenGL) in your `mpv.conf`.
+- Force XWayland in your own mpv command, for example `mpv --gpu-context=x11vk,x11egl,x11 <file>`. Launching with `WAYLAND_DISPLAY= mpv <file>` works too, as does setting `gpu-context=x11vk` (Vulkan) or `gpu-context=x11egl` (OpenGL) 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).

@@ -434,7 +432,7 @@ SubMiner can only detect focus for X11/Xwayland windows in this mode. If a nativ
 - **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
+## See also

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

@@ -1,6 +1,6 @@
-# TsukiHime Integration
+# TsukiHime integration

-[TsukiHime](https://tsukihime.org) tracks anime torrent releases and extracts every attachment - including embedded subtitle tracks - from the release files, hosting them for direct download. SubMiner integrates with the TsukiHime API so you can pull English subtitles for the currently playing episode straight from the overlay, no torrent client involved. Downloaded subtitles are decompressed, saved next to the video, and loaded into mpv immediately.
+[TsukiHime](https://tsukihime.org) indexes anime torrent releases and pulls every attachment out of the release files, embedded subtitle tracks included, then hosts them for direct download. SubMiner talks to the TsukiHime API, so you can grab subtitles for the episode you are watching from the overlay without a torrent client. The download is decompressed, saved next to the video, and loaded into mpv straight away.

 This is the multi-language companion to the [Jimaku integration](/jimaku-integration). Releases that ship multiple languages (e.g. Netflix `[MultiSub]` rips) expose them all; the modal's tabs pick which ones you see, and each download is saved with its own language suffix.

@@ -12,9 +12,9 @@ TsukiHime replaces [Animetosho](https://animetosho.org), which stops processing
 Unlike Jimaku, TsukiHime needs no account or API key. The only requirement is the `xz` binary on your `PATH` - TsukiHime serves extracted subtitles xz-compressed, and SubMiner shells out to `xz` to decompress them. Most Linux distributions ship it by default (package `xz` or `xz-utils`).
 :::

-## How It Works
+## How it works

-The integration runs through an in-overlay modal opened with `Ctrl+Shift+T` by default. The modal has two tabs that filter the subtitle tracks of the selected release by role: the first follows `secondarySub.secondarySubLanguages` (English when unset), and the second is always **Japanese**, the currently supported primary subtitle language. Tracks with no language tag stay visible on the secondary tab.
+The integration runs through an in-overlay modal opened with `Ctrl+Shift+T` by default. The modal has two tabs that filter both the release list and the subtitle tracks of the selected release by role: the first follows `secondarySub.secondarySubLanguages` (English when unset), and the second is always **Japanese**, the currently supported primary subtitle language. Each tab lists only the releases whose reported subtitle languages include the tab's language, so the Japanese tab hides the many releases that ship English subtitles only. Releases and tracks with no language tag stay visible on the secondary tab. If nothing on the active tab qualifies, the status line says so and points at the other tab.

 When you open the modal, SubMiner parses the current video filename to extract a title and episode number (same parser as Jimaku - `S01E03`, `1x03`, `E03`, and dash-separated numbers all work). If the filename yields a high-confidence match, SubMiner auto-searches immediately.

@@ -24,9 +24,9 @@ From there:
 2. **Browse releases** - Select a release to list the text subtitle tracks extracted from its files. English tracks sort first; image-based tracks (PGS/VobSub) are filtered out.
 3. **Download** - Selecting a track downloads the xz-compressed subtitle from TsukiHime's storage, decompresses it, saves it next to the video (or a temp directory for remote/streamed media), and loads it into mpv. Japanese tracks are selected as mpv's **primary** subtitle. Tracks from the configured secondary tab are assigned to mpv's **secondary** subtitle slot without replacing the primary. The filename carries the track's language - `<video basename>.en.<ext>` for English, `.ja` for Japanese, and so on - so mpv and media servers detect the language correctly.

-Because releases on TsukiHime are the same files circulating as torrents, picking the release that matches your local file (same group, same version) gives you subtitles with exact timing - no resync needed. If your file is a raw or from a different group, pick any release of the same episode and adjust timing with the [subtitle sync tools](/troubleshooting#subtitle-sync-subsync) (`Ctrl+Alt+S`) if necessary.
+TsukiHime's releases are the same files that circulate as torrents. Pick the release matching your local file, same group and same version, and the timing lines up exactly with no resync. For a raw or a different group's encode, take any release of the episode and fix the offset with the [subtitle sync tools](/troubleshooting#subtitle-sync-subsync) (`Ctrl+Alt+S`).

-### Modal Keyboard Shortcuts
+### Modal keyboard shortcuts

 | Key                          | Action                          |
 | ---------------------------- | ------------------------------- |
@@ -38,7 +38,7 @@ Because releases on TsukiHime are the same files circulating as torrents, pickin

 ## Configuration

-The integration works out of the box. An optional `tsukihime` section in `config.jsonc` tunes it:
+There is nothing to configure to get started. An optional `tsukihime` section in `config.jsonc` tunes it:

 ```jsonc
 {
@@ -66,7 +66,7 @@ The keyboard shortcut is configured separately under `shortcuts`:

 Existing Animetosho configuration remains compatible. SubMiner treats the old `animetosho` section and `shortcuts.openAnimetosho` setting as deprecated aliases. When old and current names are both present, `tsukihime` and `shortcuts.openTsukihime` take precedence.

-## Other Ways to Open It
+## Other ways to open it

 - CLI: `subminer --open-tsukihime`
 - Keybinding command: bind any key to `["__tsukihime-open"]` in the `keybindings` array
@@ -76,6 +76,7 @@ The previous `--open-animetosho` flag and `__animetosho-open` keybinding command
 ## Troubleshooting

 - **"xz binary not found"** - install `xz`/`xz-utils` with your package manager.
+- **"No releases with Japanese subtitles"** - none of the search results carry a Japanese track. Most releases only ship English subtitles; try another search, or use the [Jimaku integration](/jimaku-integration) for Japanese subtitles.
 - **"Batch releases are not supported"** - TsukiHime only exposes extracted attachments for single-file torrents. Pick the single-episode release for your episode instead of a season batch.
 - **"No text subtitle tracks in this release"** - the release only carries image-based subtitles (PGS/VobSub) or none at all; try a different release (fansub and SubsPlease-style releases almost always carry ASS tracks).
 - **Timing is off** - the subtitle came from a different release than your video file. Use the subtitle sync modal (`Ctrl+Alt+S`) or pick the release matching your file exactly.
@@ -1,6 +1,6 @@
 # Usage

-## Quick Start
+## Quick start

 Play a video with SubMiner:

@@ -10,7 +10,9 @@ 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.

-That's the simplest way to get started. The `subminer` launcher handles mpv, the IPC socket, and the overlay automatically.
+That is the whole setup. The `subminer` launcher starts mpv, opens the IPC socket, and brings up the overlay.
+
+Every current launcher wrapper uses the Bun runtime included with the SubMiner app. This includes setup installs, release downloads, `make install`, and the AUR package. You only need the wrapper directory on your terminal `PATH`. Building SubMiner from source still requires Bun on the development machine.

 > [!IMPORTANT]
 > SubMiner requires the bundled Yomitan instance to have at least one dictionary imported for lookups to work.
@@ -36,17 +38,17 @@ If you want sentence, audio, and screenshot fields on your Anki cards, add this
 Field names must match a field on your Anki note type. Matching is case-insensitive (an exact match wins, then a lowercase comparison), but the spelling must otherwise match. See [Anki Integration](/anki-integration) for the full reference.
 :::

-## How It Works
+## How it works

-When you launch SubMiner, it wires up mpv and the overlay for you:
+Launching SubMiner 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).
+Subtitles then render as hoverable word spans, and you mine cards straight from the overlay. [Mining Workflow](/mining-workflow) covers the overlay layout, word lookup, card creation, and annotations.

-### Ways to Launch
+### Ways to launch

 | Approach                            | Use when                                                                                                                               | How                                                                   |
 | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
@@ -54,11 +56,11 @@ From there, subtitles render as interactive, hoverable word spans and you mine c
 | **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. On Linux, normal `subminer` playback auto-installs the launcher-managed runtime plugin copy from the bundled app if that managed copy is missing, so no separate plugin install is needed for standard launcher usage. If you launch mpv yourself (without the launcher), pass `--input-ipc-server=/tmp/subminer-socket` in your mpv config for the overlay to connect.
+The mpv plugin is always available, because SubMiner bundles it and injects it at runtime. On Linux, normal `subminer` playback auto-installs the launcher-managed runtime plugin copy from the bundled app if that managed copy is missing, so no separate plugin install is needed for standard launcher usage. If you launch mpv yourself (without the launcher), pass `--input-ipc-server=/tmp/subminer-socket` in your mpv config for the overlay to connect.

 ## Commands

-These are the commands you will actually use day to day. The full inventory of subcommands and flags lives in [Launcher Script](/launcher-script#subcommands).
+These are the ones you will use day to day. [Launcher Script](/launcher-script#subcommands) has every subcommand and flag.

 ```bash
 subminer video.mkv                # Play a specific file
@@ -74,7 +76,7 @@ subminer app --setup              # Re-open first-run setup
 subminer -u                       # Check for updates
 ```

-On **Windows** there is no `subminer` launcher. Use the **SubMiner mpv** shortcut for playback (see [Windows mpv Shortcut](#windows-mpv-shortcut)), and run `SubMiner.exe` directly for everything else.
+On **Windows**, first-run setup can install the optional `subminer` terminal wrapper. Use the **SubMiner mpv** shortcut for playback (see [Windows mpv Shortcut](#windows-mpv-shortcut)), or use `subminer` and `SubMiner.exe` from a terminal.

 Two flags are worth knowing early:

@@ -95,6 +97,8 @@ subminer texthooker               # Texthooker-only mode (-o also opens the brow
 subminer stats -b                 # Start/reuse the background stats daemon
 subminer stats -s                 # Stop the background stats daemon
 subminer stats cleanup            # Backfill vocabulary metadata, prune stale rows
+subminer stats cleanup -d --dry-run  # Preview cleanup of repeated typeset subtitle lines
+subminer stats cleanup -d --lookback-days 30  # Clean only lines recorded in the last 30 days
 subminer stats rebuild            # Rebuild rollup data
 subminer doctor --refresh-known-words  # Refresh the known-word cache
 subminer logs -e                  # Export a sanitized log ZIP and print its path
@@ -107,6 +111,8 @@ subminer app --stop               # Stop the background app
 subminer --version                # Print the launcher's version
 ```

+`stats cleanup` runs one mode per invocation: `-v`/`--vocab` (the default), `-l`/`--lifetime`, or `-d`/`--duplicate-lines`; explicitly selected modes cannot be combined. `--dry-run` and `--lookback-days <days>` apply to `--duplicate-lines` only and are rejected without it; `--lookback-days` must be at least one day, and leaving it off scans all history.
+
 Jellyfin, cross-machine sync, and character-dictionary commands have their own sections: [Jellyfin](/jellyfin-integration), [Sync Between Machines](/launcher-script#sync-between-machines), and [Character Dictionary](/character-dictionary).

 </details>
@@ -137,7 +143,7 @@ SubMiner.AppImage --start --log-level debug  # Verbose logging without dev mode
 SubMiner.AppImage --help                  # Show all options
 ```

-The remaining flags are internal or scripting-only surfaces: the `--jellyfin-*` family (login, library listing, item playback, cast announce), `--sync-cli` (the app's headless sync entrypoint that `subminer sync` proxies to), `--dictionary-candidates` / `--dictionary-select`, and `--playback-feedback <text>`. Run `SubMiner.AppImage --help` for the complete list. The previous `--open-animetosho` flag is still accepted as a deprecated alias for `--open-tsukihime`.
+The remaining flags are internal or scripting-only surfaces: the `--jellyfin-*` family (login, library listing, item playback, cast announce), `--sync-cli` (the app's headless sync entrypoint that `subminer sync` proxies to), the `--stats-cleanup-*` family that `subminer stats cleanup` forwards (`--stats-cleanup-vocab`, `--stats-cleanup-lifetime`, `--stats-cleanup-duplicate-lines`, and its `--stats-cleanup-dry-run` / `--stats-cleanup-lookback-days <days>` modifiers), `--dictionary-candidates` / `--dictionary-select`, and `--playback-feedback <text>`. Run `SubMiner.AppImage --help` for the complete list. The previous `--open-animetosho` flag is still accepted as a deprecated alias for `--open-tsukihime`.

 </details>

@@ -147,7 +153,7 @@ Once Jellyfin is configured, the tray menu includes `Jellyfin Discovery` for sta

 The tray menu also includes `View Changelog`, which opens the in-app changelog modal. It fetches the changelog from the newest published release, so you see release notes for versions newer than the one you run; if the download fails it falls back to the changelog bundled with your install and says so. Versions in the current `0.x` line are expanded by default and older lines are folded, matching this site's [Changelog](/changelog). A badge marks the version you have installed, and newer versions are tagged `New`. The same modal opens from the `What's New` button on the update-available overlay notification.

-### Logging and App Mode
+### Logging and app mode

 - `--log-level` controls logger verbosity.
 - `--dev` and `--debug` are app/dev-mode switches; they are not log-level aliases.
@@ -161,7 +167,7 @@ The tray menu also includes `View Changelog`, which opens the in-app changelog m
 - 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
+### Windows mpv shortcut

 First-run setup creates the config file, then requires Yomitan dictionaries before it can finish.

@@ -181,7 +187,7 @@ You can use it three ways:

 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
+### Launcher subcommands

 The launcher groups related work under subcommands: `jellyfin` (aliased `jf`), `stats`, `sync`, `dictionary` (aliased `dict`), `texthooker`, `doctor`, `settings`, `config`, `mpv`, `logs`, and `app` (aliased `bin`) for passing arguments straight to the SubMiner binary.

@@ -189,9 +195,9 @@ Every subcommand has its own help page, for example `subminer jellyfin -h`. See

 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.

-### First-Run Setup
+### First-run setup

-Setup popup appears on first launch, or when setup has not been completed.
+The setup window opens on first launch and on any later launch where setup never finished.

 You can also open it manually:

@@ -205,7 +211,8 @@ 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
+- dictionary check: confirm at least one bundled Yomitan dictionary is present, unless an external Yomitan profile is configured
+- command line launcher: optionally install or reinstall the managed `subminer` wrapper. Reinstall it to migrate an older launcher or after moving a macOS or Windows app install.
 - 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
@@ -221,7 +228,7 @@ AniList character dictionary auto-sync (optional):
 Use subcommands for Jellyfin workflows (`subminer jellyfin ...`).
 Top-level launcher flags like `--jellyfin-*` are intentionally rejected.

-### MPV Profile Example (mpv.conf)
+### MPV profile example (mpv.conf)

 `subminer` passes the following MPV options directly on launch by default:

@@ -260,13 +267,13 @@ secondary-sub-visibility=no

 ### 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.
+SubMiner bundles its own Yomitan extension for overlay lookups. It is a separate install from any Yomitan you run in a browser, with its own dictionaries and settings.

 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.

-If you also use Yomitan in a browser, configure that browser profile separately; it does not inherit dictionaries or settings from the bundled instance.
+If you also use Yomitan in a browser, set that profile up separately. It inherits nothing from the bundled instance.

-### YouTube Playback
+### YouTube playback

 `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.
@@ -284,7 +291,7 @@ Notes:

 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.

-## Live Config Reload
+## Live config reload

 While SubMiner is running, it watches your active config file and applies safe updates automatically.

@@ -301,16 +308,16 @@ Live-updated settings include:
 - `mpv.aniskipEnabled`, `mpv.aniskipButtonKey`
 - `stats.toggleKey`, `stats.markWatchedKey`
 - `youtube.primarySubLanguages`
- most `ankiConnect.*` settings (including `ankiConnect.ai`)
+- most `ankiConnect.*` settings

 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.

-## Controller Support
+## Controller support

-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.
+SubMiner reads gamepads through the Chrome Gamepad API, so you can mine from the couch. The controller drives the overlay while keyboard-only mode is on.

-### Getting Started
+### Getting started

 1. Connect a controller before or after launching SubMiner.
 2. Set `controller.enabled` to `true` in your config.
@@ -322,7 +329,7 @@ SubMiner supports gamepad/controller input for couch-friendly usage via the Chro

 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`.

-### Default Button Mapping
+### Default button mapping

 | Button                  | Action                                  |
 | ----------------------- | --------------------------------------- |
@@ -336,9 +343,9 @@ By default SubMiner uses the first connected controller after controller support
 | `Select` / `Minus`      | Quit mpv                                |
 | `L2` / `R2`             | Unbound (available for custom bindings) |

-Note: the default quit binding uses gamepad button index 6. Pads that follow the W3C standard gamepad layout report L2 as index 6 (Select is index 8), so on those controllers the quit action may fire on L2 instead - use `Alt+C` learn mode to remap it for your pad.
+The default quit binding uses gamepad button index 6. Pads that follow the W3C standard layout report L2 as index 6 and Select as index 8, so on those controllers quit fires on L2 instead. Remap it with `Alt+C` learn mode.

-### Analog Controls
+### Analog controls

 | Input                 | Action                                        |
 | --------------------- | --------------------------------------------- |
@@ -347,7 +354,7 @@ Note: the default quit binding uses gamepad button index 6. Pads that follow the
 | Right stick vertical  | Jump through Yomitan popup                    |
 | D-pad                 | Fallback for stick navigation when configured |

-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.
+Learn mode ignores inputs you are already holding and waits for the next fresh press or axis push, so opening the modal mid-input does not capture whatever your thumb was on.

 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.

@@ -374,7 +381,7 @@ The changelog modal (tray > `View Changelog`) works the same way: it renders ove

 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
+### Drag-and-drop

 - Drop video files onto the overlay to replace current playback.
 - Hold `Shift` while dropping to append to the playlist instead.
@@ -1,19 +1,19 @@
-# 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.
+This page is for people wiring SubMiner's live subtitle stream into their own tools: a browser tab, an automation script, another mpv plugin. If you only want subtitles in a browser tab for Yomitan, jump to [Texthooker Integration Guide](#texthooker-integration-guide). Everything else here is reference for building a client.

 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:
+SubMiner opens four local integration points:

 - **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.
+The rest of this page documents each one and shows how to build a consumer for it.

-## Quick Reference
+## Quick reference

 | Surface | Default | Purpose |
 | --- | --- | --- |
@@ -22,7 +22,7 @@ This page documents those integration points and shows how to build custom consu
 | `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 |

-## Enable and Configure the Services
+## Enable and configure the services

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

@@ -52,9 +52,9 @@ SubMiner's integration ports are configured in `config.jsonc`. All three service

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

-## Developer API Documentation
+## Developer API documentation

-### 1. Subtitle WebSocket
+### 1. subtitle WebSocket

 Use the basic subtitle websocket when you only need the current subtitle line as plain text.

@@ -86,7 +86,7 @@ When a client connects, SubMiner immediately sends the latest subtitle payload i
 | `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. |

-### 2. Annotation WebSocket
+### 2. annotation WebSocket

 Use the annotation websocket for custom clients that want the same structured token payload the bundled texthooker UI consumes.

@@ -167,7 +167,7 @@ SubMiner also adds tooltip-friendly data attributes when available:

 If you need a fully custom UI, ignore `sentence` and render from `tokens` instead.

-## Texthooker Integration Guide
+## Texthooker integration guide

 ### When to use the bundled texthooker page

@@ -221,7 +221,7 @@ Here is a minimal browser client for the annotation stream:
 </script>
 ```

-### Build a custom Node client
+### Build a custom node client

 ```js
 import WebSocket from 'ws';
@@ -245,7 +245,7 @@ ws.on('message', (raw) => {
 - 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.

-## Plugin Development
+## Plugin development

 SubMiner does **not** currently expose a general-purpose third-party plugin SDK inside the app itself. Today, the supported extension surfaces are:

@@ -309,7 +309,7 @@ Examples:
 - local vocabulary capture helper that writes interesting lines to a file
 - bridge service that forwards websocket events into your own workflow engine

-## Webhook Examples
+## 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.

@@ -342,7 +342,6 @@ ws.on('message', async (raw) => {
 - **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

@@ -365,7 +364,7 @@ ws.on('message', async (raw) => {
 });
 ```

-## Recommended Integration Combinations
+## Recommended integration combinations

 - **Browser Yomitan client:** `texthooker` + `annotationWebsocket`
 - **Custom dashboard:** `annotationWebsocket` only
@@ -373,7 +372,7 @@ ws.on('message', async (raw) => {
 - **mpv-side automation:** mpv plugin script messages + optional websocket relay
 - **Webhook-style workflows:** `annotationWebsocket` + your own local relay service

-## Related Pages
+## Related pages

 - [Configuration](/configuration#websocket-server)
 - [Mining Workflow - Texthooker](/mining-workflow#texthooker)
@@ -1,23 +1,23 @@
-# 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 loads Japanese subtitles for it, so mining works the same as it does on a local file. It probes the available tracks with `yt-dlp`, picks a primary and a secondary, downloads both, and loads them into mpv before playback resumes.

 ## Requirements

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

-## How It Works
+## How it works

 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. Every yt-dlp call passes `--no-playlist`, so playlist links (for example a Watch Later URL with `list=`/`index=`) resolve to the single video instead of the whole playlist.
-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.
+1. **Probe** - `yt-dlp --dump-single-json` extracts all available subtitle tracks (manual uploads and auto-generated captions) along with video metadata. Every yt-dlp call passes `--no-playlist`, so playlist links (for example a Watch Later URL with `list=`/`index=`) resolve to the single video instead of the whole playlist.
+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
+## Pipeline diagram

 ```mermaid
 flowchart TD
@@ -42,8 +42,8 @@ flowchart TD
    A --> B
    B --> C
    C --> D
-    D -- startup --> E
-    D -- user request --> F
+    D - startup --> E
+    D - user request --> F
    E --> G
    F --> G
    G --> H
@@ -52,7 +52,7 @@ flowchart TD
    K --> L
 ```

-## Auto-Load Flow
+## Auto-load flow

 On startup with a YouTube URL:

@@ -66,7 +66,7 @@ On startup with a YouTube URL:
 6. Missing tracks are downloaded to a temp directory and loaded via `sub-add`.
 7. Playback unpauses once the primary subtitle is ready.

-## Manual Subtitle Picker
+## Manual subtitle picker

 Press **Ctrl+Alt+C** during YouTube playback to open the subtitle picker overlay. This lets you:

@@ -80,27 +80,27 @@ card to a success notification after the selected tracks load.

 The picker displays each track with its language, kind (manual/auto), and title when available.

-## Subtitle Format Handling
+## Subtitle format handling

 SubMiner handles several YouTube subtitle formats transparently:

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

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

-## Card Media Cache
+## Card media cache

 By default, YouTube card audio and screenshots are extracted directly from mpv's active stream URLs. If generated card media fails with YouTube `403` errors, set `youtube.mediaCache.mode` to `"background"`. Background mode starts a separate `yt-dlp` media download after playback loads, including YouTube URLs opened directly in mpv and resolved stream URLs when mpv still exposes the original YouTube playlist entry. It creates text fields immediately, queues audio/image work for mined notes, and fills those fields once the local cache file is ready.

 Background cache downloads are capped at 720p by default (`youtube.mediaCache.maxHeight`; set `0` for unlimited) and use IPv4 and retry flags to reduce YouTube throttling failures. If the background download still fails, SubMiner shows a cache failure notification, shows queued-card failure notifications, and clears those pending updates so cards are not left waiting silently.

-## Configuration Reference
+## Configuration reference

-### Primary Subtitle Languages
+### Primary subtitle languages

 ```jsonc
 {
@@ -114,11 +114,11 @@ Background cache downloads are capped at 720p by default (`youtube.mediaCache.ma
 | --------------------- | ---------- | ------------------------------------------------------------------------------------- |
 | `primarySubLanguages` | `string[]` | Languages that count as a satisfactory primary subtitle (default `["ja", "jpn"]`). Used by the "primary subtitle missing" notification and by managed local/playlist subtitle selection. |

-YouTube auto-selection itself always picks a Japanese track first (manual over auto), then falls back to any manual track — `primarySubLanguages` does not change which YouTube track is auto-picked.
+YouTube auto-selection itself always picks a Japanese track first (manual over auto), then falls back to any manual track. `primarySubLanguages` does not change which YouTube track is auto-picked.

-### Secondary Subtitle Languages
+### Secondary subtitle languages

-YouTube secondary selection is fixed: SubMiner always tries an English track (manual over auto) and loads it when found. The shared `secondarySub` config does not change YouTube track selection — `secondarySubLanguages` and `autoLoadSecondarySub` apply only to local/Jellyfin sidecar selection — but `defaultMode` still controls how the loaded secondary bar is displayed:
+YouTube secondary selection is fixed: SubMiner always tries an English track (manual over auto) and loads it when found. The shared `secondarySub` config does not change YouTube track selection. `secondarySubLanguages` and `autoLoadSecondarySub` apply only to local and Jellyfin sidecar selection. `defaultMode` still controls how the loaded secondary bar is displayed:

 ```jsonc
 {
@@ -138,10 +138,10 @@ YouTube secondary selection is fixed: SubMiner always tries an English track (ma

 These settings come from `config.jsonc` (or built-in defaults); there are no CLI flags or environment variables for subtitle language selection.

-## Limitations and Troubleshooting
+## Limitations and troubleshooting

 - **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.
+- **yt-dlp not found**: Install `yt-dlp` and put it on `PATH`, or set `SUBMINER_YTDLP_BIN` to the binary path.
 - **Probe timeout**: `yt-dlp` has a 15-second timeout per operation. Slow connections or rate-limited IPs may hit this. Retry or update `yt-dlp`.
 - **Card media `403` errors**: Switch `youtube.mediaCache.mode` from `"direct"` to `"background"` so card media is generated from a local `yt-dlp` cache instead of ffmpeg reading an expiring YouTube stream URL.
 - **Auto-caption quality**: YouTube auto-generated captions vary in quality. Manual subtitles (when available) are always preferred.
@@ -149,10 +149,10 @@ These settings come from `config.jsonc` (or built-in defaults); there are no CLI
 - **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.

-## Related Pages
+## Related pages

- [Usage --- YouTube Playback](/usage#youtube-playback)
- [Configuration --- YouTube Playback Settings](/configuration#youtube-playback-settings)
- [Configuration --- Secondary Subtitles](/configuration#secondary-subtitles)
+- [Usage - YouTube Playback](/usage#youtube-playback)
+- [Configuration - YouTube Playback Settings](/configuration#youtube-playback-settings)
+- [Configuration - Secondary Subtitles](/configuration#secondary-subtitles)
 - [Keyboard Shortcuts](/shortcuts)
 - [Jellyfin Integration](/jellyfin-integration)
@@ -31,6 +31,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,16 +62,24 @@
   `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 only when their hidden
-   `prerelease-base-version` marker matches the current base version, and asks
-   Claude to merge only the new fragment material. Do not run
+   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.
@@ -78,6 +94,8 @@ 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`) 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.
@@ -92,6 +110,7 @@ Notes:
 - 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.
 - 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.
@@ -70,18 +70,27 @@ interface SubtitleCue {
  startTime: number; // seconds
  endTime: number; // seconds
  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, read the field order from the `Format:` row, and take everything after the Text field index as the text (Text can itself contain commas).
+- 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

 1. **Activation trigger:** When a subtitle track is activated (or changes), check if it's external via MPV's `track-list` property. If `external === true`, read the file via `external-filename` using the existing `loadSubtitleSourceText` infrastructure.
@@ -10,11 +10,13 @@ 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.
+
 ## Read Next

 - [Domains](./domains.md) - who owns what
@@ -40,3 +42,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.
@@ -25,7 +25,8 @@ Read when: you need to find the owner module for a behavior or test surface
 - Anki workflow: `src/anki-integration/`, `src/core/services/anki-jimaku*.ts`
 - 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.
-  `delete-maintenance-scheduler.ts` coalesces and serializes stats deletes; expensive deletion and summary rebuilds run in `delete-maintenance-worker-thread.ts` while the tracker queues playback writes. Each batch uses one transaction, lexical update, rollup refresh, and lifetime rebuild.
+  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.
 - AniList tracking + character dictionary: `src/core/services/anilist/`, `src/main/runtime/composers/anilist-*`, `src/main/character-dictionary-runtime.ts`, `src/main/character-dictionary-runtime/`
 - Jellyfin integration: `src/core/services/jellyfin*.ts`, `src/main/runtime/composers/jellyfin-*`
 - Window trackers: `src/window-trackers/`
@@ -36,6 +37,14 @@ Read when: you need to find the owner module for a behavior or test surface

 ## Shared Contract Entry Points

+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`
@@ -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

@@ -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

@@ -3,7 +3,7 @@
 # Subtitle Overlay Priming

 Status: active
-Last verified: 2026-08-04
+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

@@ -69,14 +69,97 @@ 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)`. Overlay windows and annotation
@@ -84,8 +167,8 @@ coming and prefetching would otherwise idle for the rest of the cue.
 - 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`, stores it in
-  `mpvClient.currentSecondarySubText`, and broadcasts `secondary-subtitle:set` to overlay windows.
+- 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.

@@ -129,7 +212,11 @@ coming and prefetching would otherwise idle for the rest of the cue.
  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
@@ -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
@@ -1,184 +0,0 @@
-# Library Summary Replaces Per-Day Trends — Design
-
-**Status:** Draft
-**Date:** 2026-04-09
-**Scope:** `stats/` frontend, `src/core/services/immersion-tracker/query-trends.ts` backend
-
-## Problem
-
-The "Library — Per Day" section on the stats Trends tab (`stats/src/components/trends/TrendsTab.tsx:224-254`) renders six stacked-area charts — Videos, Watch Time, Cards, Words, Lookups, and Lookups/100w, each broken down per title per day.
-
-In practice these charts are not useful:
-
- Most titles only have activity on one or two days in a window, so they render as isolated bumps on a noisy baseline.
- Stacking 7+ titles with mostly-zero days makes individual lines hard to follow.
- The top "Activity" and "Period Trends" sections already answer "what am I doing per day" globally.
- The "Library — Cumulative" section directly below already answers "which titles am I progressing through" with less noise.
-
-The per-day section occupies significant vertical space without carrying its weight, and the user has confirmed it should be replaced.
-
-## Goal
-
-Replace the six per-day stacked charts with a single "Library — Summary" section that surfaces per-title aggregate statistics over the selected date range. The new view should make it trivially easy to answer: "For the selected window, which titles am I spending time on, how much mining output have they produced, and how efficient is my lookup rate on each?"
-
-## Non-goals
-
- Changing the "Library — Cumulative" section (stays as-is).
- Changing the "Activity", "Period Trends", or "Patterns" sections.
- Adding a new API endpoint — the existing dashboard endpoint is extended in place.
- Renaming internal `anime*` data-model identifiers (`animeId`, `imm_anime`, etc.). Those stay per the convention established in `c5e778d7`; only new fields/types/user-visible strings use generic "title"/"library" wording.
- Supporting a true all-time library view on the Trends tab. If that's ever wanted, it belongs on a different tab.
-
-## Solution Overview
-
-Delete the "Library — Per Day" section. In its place, add "Library — Summary", composed of:
-
-1. A horizontal-bar leaderboard chart of watch time per title (top 10, descending).
-2. A sortable table of every title with activity in the selected window, with columns: Title, Watch Time, Videos, Sessions, Cards, Words, Lookups, Lookups/100w, Date Range.
-
-Both controls are scoped to the top-of-page date range selector. The existing shared Anime Visibility filter continues to work — it now gates Summary + Cumulative instead of Per-Day + Cumulative.
-
-## Backend
-
-### New type
-
-Add to `stats/src/types/stats.ts` and the backend query module:
-
-```ts
-type LibrarySummaryRow = {
-  title: string;              // display title — anime series, YouTube video title, etc.
-  watchTimeMin: number;       // sum(total_active_min) across the window
-  videos: number;             // distinct video_id count
-  sessions: number;           // session count from imm_sessions
-  cards: number;              // sum(total_cards)
-  words: number;              // sum(total_tokens_seen)
-  lookups: number;            // sum(lookup_count) from imm_sessions
-  lookupsPerHundred: number | null; // lookups / words * 100, null when words == 0
-  firstWatched: number;       // min(rollup_day) as epoch day, within the window
-  lastWatched: number;        // max(rollup_day) as epoch day, within the window
-};
-```
-
-### Query changes in `src/core/services/immersion-tracker/query-trends.ts`
-
- Add `librarySummary: LibrarySummaryRow[]` to `TrendsDashboardQueryResult`.
- Populate it from a single aggregating query over `imm_daily_rollups` joined to `imm_videos` → `imm_anime`, filtered by `rollup_day` within the selected window. Session count and lookup count come from `imm_sessions` aggregated by `video_id` and then grouped by the parent library entry. Use a single query (or at most two joined/unioned) — no N+1.
- `imm_anime` is the generic library-grouping table; anime series, YouTube videos, and yt-dlp imports all land there. The internal table name stays `imm_anime`; only the new field uses generic naming.
- Return rows pre-sorted by `watchTimeMin` descending so the leaderboard is zero-cost and the table default sort matches.
- Emit `lookupsPerHundred: null` when `words == 0`.
-
-### Removed from API response
-
-Drop the entire `animePerDay` field from `TrendsDashboardQueryResult` (both backend in `src/core/services/immersion-tracker/query-trends.ts` and frontend in `stats/src/types/stats.ts`).
-
-Internally, the existing helpers (`buildPerAnimeFromDailyRollups`, `buildEpisodesPerAnimeFromDailyRollups`) are still used as intermediates to build `animeCumulative.*` via `buildCumulativePerAnime`. Keep those helpers — just scope their output to local variables inside `getTrendsDashboard` instead of exposing them on the response. The `buildPerAnimeFromSessions` call for lookups and the `buildLookupsPerHundredPerAnime` helper become unused and can be deleted.
-
-Before removing `animePerDay` from the frontend type, verify no other file under `stats/src/` references it. Based on current inspection, only `TrendsTab.tsx` and `stats/src/types/stats.ts` touch it.
-
-## Frontend
-
-### New component: `stats/src/components/trends/LibrarySummarySection.tsx`
-
-Owns the header, leaderboard chart, visibility-filtered data, and the table. Keeps `TrendsTab.tsx` from growing. Component props: `{ rows: LibrarySummaryRow[]; hiddenTitles: ReadonlySet<string>; windowStart: Date; windowEnd: Date }`.
-
-Internal state: `useState<{ column: ColumnId; direction: 'asc' | 'desc' }>` for sort, defaulting to `{ column: 'watchTimeMin', direction: 'desc' }`.
-
-### Layout
-
-Replaces `TrendsTab.tsx:224-254`:
-
-```
-[SectionHeader: "Library — Summary"]
-[AnimeVisibilityFilter — unchanged, shared with Cumulative below]
-[Card, col-span-full: Leaderboard — horizontal bar chart, ~260px tall]
-[Card, col-span-full: Sortable table, auto height up to ~480px with internal scroll]
-```
-
-Both cards use the existing chart/card wrapper styling.
-
-### Leaderboard chart
-
- Recharts horizontal bar chart (matches the rest of the page — existing charts use `recharts`, not ECharts).
- Top 10 titles by watch time. If fewer titles have activity, render what's there.
- Y-axis: title (category), truncated with ellipsis at container width; full title visible in the Recharts tooltip.
- X-axis: minutes (number).
- Use `layout="vertical"` with `YAxis dataKey="title" type="category"` and `XAxis type="number"`.
- Single series color: `#8aadf4` (matching the existing Watch Time color).
- Reuse `CHART_DEFAULTS`, `CHART_THEME`, `TOOLTIP_CONTENT_STYLE` from `stats/src/lib/chart-theme.ts` so theming matches the rest of the dashboard.
- Chart order is fixed at watch-time desc regardless of table sort — the leaderboard's meaning is fixed.
-
-### Table
-
- Plain HTML `<table>` with Tailwind classes. No new deps.
- Columns, in order:
-  1. **Title** — left-aligned, sticky, truncated with ellipsis, full title on hover.
-  2. **Watch Time** — formatted `Xh Ym` when ≥60 min, else `Xm`.
-  3. **Videos** — integer.
-  4. **Sessions** — integer.
-  5. **Cards** — integer.
-  6. **Words** — integer.
-  7. **Lookups** — integer.
-  8. **Lookups/100w** — one decimal place, `—` when null.
-  9. **Date Range** — `Mon D → Mon D` using the title's `firstWatched` / `lastWatched` within the window.
- Click a column header to sort; click again to reverse. Visual arrow on the active column.
- Numeric columns right-aligned.
- Null `lookupsPerHundred` sorts as the lowest value in both directions (consistent with "no data").
- Row hover highlight; no row click action (read-only view).
- Empty state: "No library activity in the selected window."
-
-### Visibility filter integration
-
-Hiding a title via `AnimeVisibilityFilter` removes it from both the leaderboard and the table. The filter's set of available titles is built from the union of titles that appear in `librarySummary` and the existing `animeCumulative.*` arrays (matches current behavior in `buildAnimeVisibilityOptions`).
-
-### `TrendsTab.tsx` changes
-
- Remove the `filteredEpisodesPerAnime`, `filteredWatchTimePerAnime`, `filteredCardsPerAnime`, `filteredWordsPerAnime`, `filteredLookupsPerAnime`, `filteredLookupsPerHundredPerAnime` locals.
- Remove the six `<StackedTrendChart>` calls in the "Library — Per Day" section.
- Remove the `<SectionHeader>Library — Per Day</SectionHeader>` and the `<AnimeVisibilityFilter>` from that position.
- Insert `<SectionHeader>Library — Summary</SectionHeader>` + `<AnimeVisibilityFilter>` + `<LibrarySummarySection>` in the same place.
- Update `buildAnimeVisibilityOptions` input to use `librarySummary` titles instead of the six dropped `animePerDay.*` arrays.
-
-## Data flow
-
-1. `useTrends(range, groupBy)` calls `/api/stats/trends/dashboard`.
-2. Response now includes `librarySummary` (sorted by watch time desc).
-3. `TrendsTab` holds the shared `hiddenAnime` set (unchanged).
-4. `LibrarySummarySection` receives `librarySummary` + `hiddenAnime`, filters out hidden rows, renders the leaderboard from the top-10 slice of the filtered list, renders the table from the filtered list with local sort state applied.
-5. Date-range selector changes trigger a new fetch; `groupBy` toggle does not affect the summary section (it's always window-total).
-
-## Edge cases
-
- **No activity in window:** Section renders header + empty-state card. Leaderboard card hidden. Visibility filter hidden.
- **One title only:** Leaderboard renders a single bar; table renders one row. No special-casing.
- **Title with zero words but non-zero lookups:** `lookupsPerHundred` is `null`, rendered as `—`. Sort treats null as lowest.
- **Title with zero cards/lookups/words but non-zero watch time:** Normal zero rendering, still shown.
- **Very long titles:** Ellipsis in chart y-axis labels and table title column; full title in `title` attribute / ECharts tooltip.
- **Mixed sources (anime + YouTube):** No special case — both land in `imm_anime` and are grouped uniformly.
-
-## Testing
-
-### Backend (`query-trends.ts`)
-
-New unit tests, following the existing pattern:
-
-1. Empty window returns `librarySummary: []`.
-2. Single title with a few rollups: all aggregates are correct; `firstWatched`/`lastWatched` match the bounding days within the window.
-3. Multiple titles: rows returned sorted by watch time desc.
-4. Mixed sources (anime-style + YouTube-style entries in `imm_anime`): both appear in the summary with their own aggregates.
-5. Title with `words == 0`: `lookupsPerHundred` is `null`.
-6. Date range excludes some rollups: excluded rollups are not counted; `firstWatched`/`lastWatched` reflect only within-window activity.
-7. `sessions` and `lookups` come from `imm_sessions`, not `imm_daily_rollups`, and are correctly attributed to the parent library entry.
-
-### Frontend
-
- Existing Trends tab smoke test should continue to pass after wiring.
- Optional: a targeted render test for `LibrarySummarySection` (empty state, single title, sort toggle, visibility filter interaction). Not required for merge if the smoke test exercises the happy path.
-
-## Release / docs
-
- One fragment in `changes/*.md` summarizing the replacement.
- No user-facing docs (`docs-site/`) changes unless the per-day section was documented there — verify during implementation.
-
-## Open items
-
-None.
@@ -1,347 +0,0 @@
-# Stats Dashboard Feedback Pass — Design
-
-Date: 2026-04-09
-Scope: Stats dashboard UX follow-ups from user feedback (items 1–7).
-Delivery: **Single PR**, broken into logically scoped commits.
-
-## Goals
-
-Address seven concrete pieces of feedback against the Statistics menu:
-
-1. Library — collapse episodes behind a per-series dropdown.
-2. Sessions — roll up multiple sessions of the same episode within a day.
-3. Trends — add a 365d range option.
-4. Library — delete an episode (video) from its detail view.
-5. Vocabulary — tighten spacing between word and reading in the Top 50 table.
-6. Episode detail — hide cards whose Anki notes have been deleted.
-7. Trend/watch charts — add gridlines, fix tick legibility, unify theming.
-
-Out of scope for this pass: English-token ingestion cleanup and Overview stat-card drill-downs (feedback items 8 and 9). Those require a larger design decision and a migration respectively.
-
-## Files touched (inventory)
-
-Dashboard (`stats/src/`):
- `components/library/LibraryTab.tsx` — collapsible groups (item 1).
- `components/library/MediaDetailView.tsx`, `components/library/MediaHeader.tsx` — delete-episode action (item 4).
- `components/sessions/SessionsTab.tsx`, `components/library/MediaSessionList.tsx` — episode rollup (item 2).
- `components/trends/DateRangeSelector.tsx`, `hooks/useTrends.ts`, `lib/api-client.ts`, `lib/api-client.test.ts` — 365d (item 3).
- `components/vocabulary/FrequencyRankTable.tsx` — word/reading column collapse (item 5).
- `components/anime/EpisodeDetail.tsx` — filter deleted Anki cards (item 6).
- `components/trends/TrendChart.tsx`, `components/trends/StackedTrendChart.tsx`, `components/overview/WatchTimeChart.tsx`, `lib/chart-theme.ts` — chart clarity (item 7).
- New file: `stats/src/lib/session-grouping.ts` + `session-grouping.test.ts`.
-
-Backend (`src/core/services/`):
- `immersion-tracker/query-trends.ts` — extend `TrendRange` and `TREND_DAY_LIMITS` (item 3).
- `immersion-tracker/__tests__/query.test.ts` — 365d coverage (item 3).
- `stats-server.ts` — passthrough if range validation lives here (check before editing).
- `__tests__/stats-server.test.ts` — 365d coverage (item 3).
-
-## Commit plan
-
-One PR, one feature per commit. Order picks low-risk mechanical changes first so failures in later commits don't block merging of earlier ones.
-
-1. `feat(stats): add 365d range to trends dashboard` (item 3)
-2. `fix(stats): tighten word/reading column in Top 50 table` (item 5)
-3. `fix(stats): hide cards deleted from Anki in episode detail` (item 6)
-4. `feat(stats): delete episode from library detail view` (item 4)
-5. `feat(stats): collapsible series groups in library` (item 1)
-6. `feat(stats): roll up same-episode sessions within a day` (item 2)
-7. `feat(stats): gridlines and unified theme for trend charts` (item 7)
-
-Each commit must pass `bun run typecheck`, `bun run test:fast`, and any change-specific checks listed below.
-
---
-
-## Item 1 — Library collapsible series groups
-
-### Current behavior
-
-`LibraryTab.tsx` groups media via `groupMediaLibraryItems` and always renders the full grid of `MediaCard`s beneath each group header.
-
-### Target behavior
-
-Each group header becomes clickable. Groups with `items.length > 1` default to **collapsed**; single-video groups stay expanded (collapsing them would be visual noise).
-
-### Implementation
-
- State: `const [collapsedGroups, setCollapsedGroups] = useState<Set<string>>(...)`. Initialize from `grouped` where `items.length > 1`.
- Toggle helper: `toggleGroup(key: string)` adds/removes from the set.
- Group header: wrap in a `<button>` with `aria-expanded` and a chevron icon (`▶`/`▼`). Keep the existing cover + title + subtitle layout inside the button.
- Children grid is conditionally rendered on `!collapsedGroups.has(group.key)`.
- Header summary (`N videos · duration · cards`) stays visible in both states so collapsed groups remain informative.
-
-### Tests
-
- New `LibraryTab.test.tsx` (if not already present — check first) covering:
-  - Multi-video group renders collapsed on first mount.
-  - Single-video group renders expanded on first mount.
-  - Clicking the header toggles visibility.
-  - Header summary is visible in both states.
-
---
-
-## Item 2 — Sessions episode rollup within a day
-
-### Current behavior
-
-`SessionsTab.tsx:10-24` groups sessions by day label only (`formatSessionDayLabel(startedAtMs)`). Multiple sessions of the same episode on the same day show as independent rows. `MediaSessionList.tsx` has the same problem inside the library detail view.
-
-### Target behavior
-
-Within each day, sessions with the same `videoId` collapse into one parent row showing combined totals. A chevron reveals the individual sessions. Single-session buckets render flat (no pointless nesting).
-
-### Implementation
-
- New helper in `stats/src/lib/session-grouping.ts`:
-  ```ts
-  export interface SessionBucket {
-    key: string;              // videoId as string, or `s-${sessionId}` for singletons
-    videoId: number | null;
-    sessions: SessionSummary[];
-    totalActiveMs: number;
-    totalCardsMined: number;
-    representativeSession: SessionSummary; // most recent, for header display
-  }
-  export function groupSessionsByVideo(sessions: SessionSummary[]): SessionBucket[];
-  ```
-  Sessions missing a `videoId` become singleton buckets.
-
- `SessionsTab.tsx`: after day grouping, pipe each `daySessions` through `groupSessionsByVideo`. Render each bucket:
-  - `sessions.length === 1`: existing `SessionRow` behavior, unchanged.
-  - `sessions.length >= 2`: render a **bucket row** that looks like `SessionRow` but shows combined totals and session count (e.g. `3 sessions · 1h 24m · 12 cards`). Chevron state stored in a second `Set<string>` on bucket key. Expanded buckets render the child `SessionRow`s indented (`pl-8`) beneath the header.
- `MediaSessionList.tsx`: within the media detail view, a single video's sessions are all the same `videoId` by definition — grouping here is by day only, and within a day multiple sessions render nested under a day header. Re-use the same visual pattern; factor the bucket row into a shared `SessionBucketRow` component.
-
-### Delete semantics
-
- Deleting a bucket header offers "Delete all N sessions in this group" (reuse `confirmDayGroupDelete` pattern with a bucket-specific message, or add `confirmBucketDelete`).
- Deleting an individual session from inside an expanded bucket keeps the existing single-delete flow.
-
-### Tests
-
- `session-grouping.test.ts`:
-  - Empty input → empty output.
-  - All unique videos → N singleton buckets.
-  - Two sessions same videoId → one bucket with correct totals and representative (most recent start time).
-  - Missing videoId → singleton bucket keyed by sessionId.
- `SessionsTab.test.tsx` (extend or add) verifying the rendered bucket rows expand/collapse and delete hooks fire with the right ID set.
-
---
-
-## Item 3 — 365d trends range
-
-### Backend
-
-`src/core/services/immersion-tracker/query-trends.ts`:
- `type TrendRange = '7d' | '30d' | '90d' | '365d' | 'all';`
- Add `'365d': 365` to `TREND_DAY_LIMITS`.
- `getTrendDayLimit` picks up the new key automatically because of the `Exclude<TrendRange, 'all'>` generic.
-
-`src/core/services/stats-server.ts`:
- Search for any hardcoded range validation (e.g. allow-list in the trends route handler) and extend it.
-
-### Frontend
-
- `hooks/useTrends.ts`: widen the `TimeRange` union.
- `components/trends/DateRangeSelector.tsx`: add `'365d'` to the options list. Display label stays as `365d`.
- `lib/api-client.ts` / `api-client.test.ts`: if the client validates ranges, add `365d`.
-
-### Tests
-
- `query.test.ts`: extend the existing range table to cover `365d` returning 365 days of data.
- `stats-server.test.ts`: ensure the route accepts `range=365d`.
- `api-client.test.ts`: ensure the client emits the new range.
-
-### Change-specific checks
-
- `bun run test:config` is not required here (no schema/defaults change).
- Run `bun run typecheck` + `bun run test:fast`.
-
---
-
-## Item 4 — Delete episode from library detail
-
-### Current behavior
-
-`MediaDetailView.tsx` provides session-level delete only. The backend `deleteVideo` exists (`query-maintenance.ts:509`), the API is exposed at `stats-server.ts:559`, and `api-client.deleteVideo` is already wired (`stats/src/lib/api-client.ts:146`). `EpisodeList.tsx:46` already uses it from the anime tab.
-
-### Target behavior
-
-A "Delete Episode" action in `MediaHeader` (top-right, small, `text-ctp-red`), gated by `confirmEpisodeDelete(title)`. On success, call `onBack()` and make sure the parent `LibraryTab` refetches.
-
-### Implementation
-
- Add an `onDeleteEpisode?: () => void` prop to `MediaHeader` and render the button only if provided.
- In `MediaDetailView`:
-  - New handler `handleDeleteEpisode` that calls `apiClient.deleteVideo(videoId)`, then `onBack()`.
-  - Reuse `confirmEpisodeDelete` from `stats/src/lib/delete-confirm.ts`.
- In `LibraryTab`:
-  - `useMediaLibrary` returns fresh data on mount. The simplest fix: pass a `refresh` function from the hook (extend the hook if it doesn't already expose one) and call it when the detail view signals back.
-  - Alternative: force a remount by incrementing a `libraryVersion` key on the library list. Prefer `refresh` for clarity.
-
-### Tests
-
- Extend the existing `MediaDetailView.test.tsx`: mock `apiClient.deleteVideo`, click the new button, confirm `onBack` fires after success.
- `useMediaLibrary.test.ts`: if we add a `refresh` method, cover it.
-
---
-
-## Item 5 — Vocabulary word/reading column collapse
-
-### Current behavior
-
-`FrequencyRankTable.tsx:110-144` uses a 5-column table: `Rank | Word | Reading | POS | Seen`. Word and Reading are auto-sized, producing a large gap.
-
-### Target behavior
-
-Merge Word + Reading into a single column titled "Word". Reading sits immediately after the headword in a muted, smaller style.
-
-### Implementation
-
- Drop the `<th>Reading</th>` header and cell.
- Word cell becomes:
-  ```tsx
-  <td className="py-1.5 pr-3">
-    <span className="text-ctp-text font-medium">{w.headword}</span>
-    {reading && (
-      <span className="text-ctp-subtext0 text-xs ml-1.5">
-        【{reading}】
-      </span>
-    )}
-  </td>
-  ```
-  where `reading = fullReading(w.headword, w.reading)` and differs from `headword`.
- Keep `fullReading` import from `reading-utils`.
-
-### Tests
-
- Extend `FrequencyRankTable.test.tsx` (if present — otherwise add a focused test) to assert:
-  - Headword renders.
-  - Reading renders when different from headword.
-  - Reading does not render when equal to headword.
-
---
-
-## Item 6 — Hide Anki-deleted cards in Cards Mined
-
-### Current behavior
-
-`EpisodeDetail.tsx:109-147` iterates `cardEvents`, fetches note info via `ankiNotesInfo(allNoteIds)`, and for each `noteId` renders a row even if no matching `info` came back — the user sees an empty word with an "Open in Anki" button that leads nowhere.
-
-### Target behavior
-
-After `ankiNotesInfo` resolves:
- Drop `noteId`s that are not in the resolved map.
- Drop `cardEvents` whose `noteIds` list was non-empty but is now empty after filtering.
- Card events with a positive `cardsDelta` but no `noteIds` (legacy rollup path) still render as `+N cards` — we have no way to cross-reference them, so leave them alone.
-
-### Implementation
-
- Compute `filteredCardEvents` as a `useMemo` depending on `data.cardEvents` and `noteInfos`.
- Iterate `filteredCardEvents` instead of `cardEvents` in the render.
- Surface a subtle note (optional, muted) "N cards hidden (deleted from Anki)" at the end of the list if any were filtered — helps the user understand why counts here diverge from session totals. Final decision on the note can be made at PR review; default: **show it**.
-
-### Tests
-
- Add a test in `EpisodeDetail.test.tsx` (add the file if not present) that stubs `ankiNotesInfo` to return only a subset of notes and verifies the missing ones are not rendered.
-
-### Other call sites
-
- Grep so far shows `ankiNotesInfo` is only used in `EpisodeDetail.tsx`. Re-verify before landing the commit; if another call site appears, apply the same filter.
-
---
-
-## Item 7 — Trend/watch chart clarity pass
-
-### Current behavior
-
-`TrendChart.tsx`, `StackedTrendChart.tsx`, and `WatchTimeChart.tsx` render Recharts components with:
- No `CartesianGrid` → no horizontal reference lines.
- 9px axis ticks → borderline unreadable.
- Height 120 → cramped.
- Tooltip uses raw labels (`04/04` etc.).
- No shared theme object; each chart redefines colors and tooltip styles inline.
-
-`stats/src/lib/chart-theme.ts` already exists and currently exports a single `CHART_THEME` constant with tick/tooltip colors and `barFill`. It will be extended, not replaced, to preserve existing consumers.
-
-### Target behavior
-
-All three charts share a theme, have horizontal gridlines, readable ticks, and sensible tooltips.
-
-### Implementation
-
-Extend `stats/src/lib/chart-theme.ts` with the additional shared defaults (keeping the existing `CHART_THEME` export intact so current consumers don't break):
-```ts
-export const CHART_THEME = {
-  tick: '#a5adcb',
-  tooltipBg: '#363a4f',
-  tooltipBorder: '#494d64',
-  tooltipText: '#cad3f5',
-  tooltipLabel: '#b8c0e0',
-  barFill: '#8aadf4',
-  grid: '#494d64',
-  axisLine: '#494d64',
-} as const;
-
-export const CHART_DEFAULTS = {
-  height: 160,
-  tickFontSize: 11,
-  margin: { top: 8, right: 8, bottom: 0, left: 0 },
-  grid: { strokeDasharray: '3 3', vertical: false },
-} as const;
-
-export const TOOLTIP_CONTENT_STYLE = {
-  background: CHART_THEME.tooltipBg,
-  border: `1px solid ${CHART_THEME.tooltipBorder}`,
-  borderRadius: 6,
-  color: CHART_THEME.tooltipText,
-  fontSize: 12,
-};
-```
-
-Apply to each chart:
- Import `CartesianGrid` from recharts.
- Insert `<CartesianGrid stroke={CHART_THEME.grid} {...CHART_DEFAULTS.grid} />` inside each chart container.
- `<XAxis tick={{ fontSize: CHART_DEFAULTS.tickFontSize, fill: CHART_THEME.tick }} />` and equivalent `YAxis`.
- `YAxis` gains `axisLine={{ stroke: CHART_THEME.axisLine }}`.
- `ResponsiveContainer` height changes from 120 → `CHART_DEFAULTS.height`.
- `Tooltip` `contentStyle` uses `TOOLTIP_CONTENT_STYLE`, and charts pass a `labelFormatter` when the label is a date key (e.g. show `Fri Apr 4`).
-
-### Unit formatters
-
- `TrendChart` already accepts a `formatter` prop — extend usage sites to pass unit-aware formatters where they aren't already (`formatDuration`, `formatNumber`, etc.).
-
-### Tests
-
- `chart-theme.test.ts` (if present — otherwise add a trivial snapshot to keep the shape stable).
- `TrendChart` snapshot/render tests: no regression, gridline element present.
-
---
-
-## Verification gate
-
-Before requesting code review, run:
-
-```
-bun run typecheck
-bun run test:fast
-bun run test:env
-bun run test:runtime:compat   # dist-sensitive check for the charts
-bun run build
-bun run test:smoke:dist
-```
-
-No docs-site changes are planned in this spec; if `docs-site/` ends up touched (e.g. screenshots), also run `bun run docs:test` and `bun run docs:build`.
-
-No config schema changes → `bun run test:config` and `bun run generate:config-example` are not required.
-
-## Risks and open questions
-
- **MediaDetailView refresh**: `useMediaLibrary` may not expose a `refresh` function. If it doesn't, the simplest path is adding one; the alternative (keying a remount) works but is harder to test. Decide during implementation.
- **Session bucket delete UX**: "Delete all N sessions in this group" is powerful. The copy must make it clear the underlying sessions are being removed, not just the grouping. Reuse `confirmBucketDelete` wording from existing confirm helpers if possible.
- **Anki-deleted-cards hidden notice**: Showing a subtle "N cards hidden" footer is a call that can be made at PR review.
- **Bucket delete helper**: `confirmBucketDelete` does not currently exist in `delete-confirm.ts`. Implementation either adds it or reuses `confirmDayGroupDelete` with bucket-specific wording — decide during the session-rollup commit.
-
-## Changelog entry
-
-User-visible PR → needs a fragment under `changes/*.md`. Suggested title:
-`Stats dashboard: collapsible series, session rollups, 365d trends, chart polish, episode delete.`
@@ -3,7 +3,7 @@
 # Workflow

 Status: active  
-Last verified: 2026-05-23  
+Last verified: 2026-08-13
 Owner: Kyle Yasuda  
 Read when: planning or executing nontrivial work in this repo

@@ -13,7 +13,7 @@ This section is the internal workflow map for contributors and agents.

 - [Planning](./planning.md) - when to write a lightweight plan vs a full execution plan
 - [Verification](./verification.md) - maintained test/build lanes and handoff gate
- [Agent Plugins](./agent-plugins.md) - repo-local plugin ownership for agent workflow skills
+- [Agent Skills](./agent-skills.md) - repo-local workflow skill ownership
 - [Release Guide](../RELEASING.md) - tagged release workflow

 ## Default Flow
@@ -1,27 +0,0 @@
-<!-- read_when: using or modifying repo-local agent plugins -->
-
-# Agent Plugins
-
-Status: active
-Last verified: 2026-05-23
-Owner: Kyle Yasuda
-Read when: packaging or migrating repo-local agent workflow skills into plugins
-
-## SubMiner Workflow Plugin
-
- Canonical plugin path: `plugins/subminer-workflow/`
- Marketplace catalog: `.agents/plugins/marketplace.json`
- Canonical skill sources:
-  - `plugins/subminer-workflow/skills/subminer-scrum-master/`
-  - `plugins/subminer-workflow/skills/subminer-change-verification/`
-
-## Migration Rule
-
- Plugin-owned skills are the source of truth.
- `.agents/skills/subminer-*` remain only as compatibility shims.
- Existing script entrypoints under `.agents/skills/subminer-change-verification/scripts/` stay as wrappers so historical commands do not break.
-
-## Verification
-
- For plugin/docs-only changes, start with `bun run test:docs:kb`.
- Use the plugin-owned verifier when the change crosses from docs into scripts or workflow logic.
@@ -0,0 +1,34 @@
+<!-- read_when: using or modifying repo-local agent skills -->
+
+# Agent Skills
+
+Status: active
+Last verified: 2026-08-23
+Owner: Kyle Yasuda
+Read when: using, adding, or changing a repo-local agent workflow skill
+
+## Canonical Skills
+
+- `.agents/skills/subminer-change-verification/`
+  - Selects the cheapest sufficient repo-native verification lane.
+  - Defers command ownership to `package.json` and `docs/workflow/verification.md`.
+- `.agents/skills/subminer-release/`
+  - Prepares, cuts, publishes, or repairs stable and prerelease releases.
+  - Defers release procedure and policy to `docs/RELEASING.md`.
+
+Repo-local workflows stay as standalone skills. Do not add plugin packaging, marketplace metadata, or compatibility shims unless the workflow is intentionally being distributed beyond this repository.
+
+## Rules
+
+- Keep each skill focused on one repeatable repository task.
+- Prefer instructions over helper scripts unless deterministic tooling provides clear value beyond existing package commands.
+- Keep trigger descriptions narrow enough to avoid invoking skills for unrelated requests.
+- Update this page and the documentation catalog when skill ownership changes.
+
+## Verification
+
+For skill or internal workflow documentation changes, run:
+
+```bash
+bun run test:docs:kb
+```
@@ -3,14 +3,14 @@
 # Verification

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

 ## Lane Infrastructure

 - Lane membership is defined once in `scripts/test-lanes.ts` and discovered by
-  directory — new test files join their lane automatically; never hand-list test
+  directory, so new test files join their lane automatically; never hand-list test
  files in `package.json`.
 - `scripts/run-test-lane.mjs` runs each test file in its own `bun test` process
  (per-file isolation with a wall timeout) so a hanging test or leaked global in
@@ -23,6 +23,8 @@ Read when: selecting the right verification lane for a change
  there instead of copying them into caller workflows.
 - The reusable gate installs Lua and runs `bun run test:env`, so the shipped mpv
  plugin tests run for every pull request and tagged release.
+  Lua installation uses only the runner's Ubuntu package sources so unrelated
+  third-party repository failures do not block the gate.

 ## Default Handoff Gate

@@ -43,8 +45,8 @@ bun run docs:build

 ## Cheap-First Lane Selection

- Docs-only boundary/content changes: `bun run docs:test`, `bun run docs:build`
- Internal KB / `AGENTS.md` changes: `bun run test:docs:kb`
+- User-facing `docs-site/` changes: `bun run docs:test`, `bun run docs:build`
+- Internal KB, `AGENTS.md`, or `.agents/skills/**` changes: `bun run test:docs:kb`
 - Config/schema/defaults: `bun run test:config`, then `bun run generate:config-example` if template/defaults changed
 - Launcher/plugin: `bun run test:launcher` or `bun run test:env`
 - Runtime-compat / compiled behavior: `bun run test:runtime:compat`
@@ -23,6 +23,7 @@ import {
  type HistorySeriesEntry,
 } from '../history.js';
 import type { Args } from '../types.js';
+import { ensureLinuxRuntimePluginAvailable } from '../runtime-plugin-preflight.js';
 import type { LauncherCommandContext } from './context.js';

 export type HistorySessionAction = 'previous' | 'replay' | 'next' | 'browse' | 'quit';
@@ -333,6 +334,13 @@ export async function runHistoryCommand(
  const { args, scriptPath } = context;

  checkPickerDependencies(args);
+  if (args.useRofi) {
+    await ensureLinuxRuntimePluginAvailable({
+      appPath: context.appPath ?? undefined,
+      scriptPath,
+      logLevel: args.logLevel,
+    });
+  }
  const themePath = args.useRofi ? findRofiTheme(scriptPath) : null;

  const dbPath = resolveImmersionDbPath();
@@ -2,6 +2,7 @@ import { fail } from '../log.js';
 import { runAppCommandWithInherit } from '../mpv.js';
 import { commandExists } from '../util.js';
 import { runJellyfinPlayMenu } from '../jellyfin.js';
+import { ensureLinuxRuntimePluginAvailable } from '../runtime-plugin-preflight.js';
 import { shouldForwardLogLevel } from '../types.js';
 import type { LauncherCommandContext } from './context.js';

@@ -64,6 +65,13 @@ export async function runJellyfinCommand(context: LauncherCommandContext): Promi
    if (args.useRofi && !commandExists('rofi')) {
      fail('rofi not found. Install rofi or omit -R for fzf.');
    }
+    if (args.useRofi) {
+      await ensureLinuxRuntimePluginAvailable({
+        appPath,
+        scriptPath,
+        logLevel: args.logLevel,
+      });
+    }
    await runJellyfinPlayMenu(appPath, args, scriptPath, mpvSocketPath);
    return true;
  }
@@ -496,3 +496,39 @@ test('playback command ensures Linux runtime plugin before mpv launch', async ()

  assert.deepEqual(calls, ['plugin', 'startMpv']);
 });
+
+test('rofi playback repairs support assets before opening the picker', async () => {
+  const context = createContext();
+  context.args = {
+    ...context.args,
+    target: '',
+    targetKind: '',
+    useRofi: true,
+  };
+  const calls: string[] = [];
+
+  await runPlaybackCommandWithDeps(context, {
+    ensurePlaybackSetupReady: async () => {},
+    ensureRuntimePluginReady: async () => {
+      calls.push('assets');
+    },
+    chooseTarget: async () => {
+      calls.push('picker');
+      return { target: '/tmp/movie.mkv', kind: 'file' };
+    },
+    checkPickerDependencies: () => {},
+    checkDependencies: () => {},
+    registerCleanup: () => {},
+    startMpv: async () => {
+      calls.push('startMpv');
+    },
+    waitForUnixSocketReady: async () => true,
+    startOverlay: async () => {},
+    launchAppCommandDetached: () => {},
+    log: () => {},
+    cleanupPlaybackSession: async () => {},
+    getMpvProc: () => null,
+  });
+
+  assert.deepEqual(calls, ['assets', 'picker', 'startMpv']);
+});
@@ -157,6 +157,7 @@ export async function runPlaybackCommand(context: LauncherCommandContext): Promi
      });
    },
    chooseTarget,
+    checkPickerDependencies,
    checkDependencies,
    registerCleanup,
    startMpv,
@@ -177,6 +178,7 @@ type PlaybackCommandDeps = {
    args: Args,
    scriptPath: string,
  ) => Promise<{ target: string; kind: 'file' | 'url' } | null>;
+  checkPickerDependencies?: (args: Args) => void;
  checkDependencies: (args: Args) => void;
  registerCleanup: (context: LauncherCommandContext) => void;
  startMpv: typeof startMpv;
@@ -201,7 +203,18 @@ export async function runPlaybackCommandWithDeps(
  await deps.ensurePlaybackSetupReady(context);

  if (!args.target) {
-    checkPickerDependencies(args);
+    (deps.checkPickerDependencies ?? checkPickerDependencies)(args);
+  }
+
+  let runtimeAssetsReady = false;
+  const ensureRuntimeAssetsReady = async (): Promise<void> => {
+    if (runtimeAssetsReady) return;
+    await deps.ensureRuntimePluginReady(context);
+    runtimeAssetsReady = true;
+  };
+
+  if (!args.target && args.useRofi) {
+    await ensureRuntimeAssetsReady();
  }

  const targetChoice = await deps.chooseTarget(args, scriptPath);
@@ -266,7 +279,7 @@ export async function runPlaybackCommandWithDeps(
    );
  }

-  await deps.ensureRuntimePluginReady(context);
+  await ensureRuntimeAssetsReady();

  await deps.startMpv(
    selectedTarget.target,
@@ -157,6 +157,15 @@ export async function runStatsCommand(
    if (args.statsCleanupLifetime) {
      forwarded.push('--stats-cleanup-lifetime');
    }
+    if (args.statsCleanupDuplicateLines) {
+      forwarded.push('--stats-cleanup-duplicate-lines');
+    }
+    if (args.statsCleanupDryRun) {
+      forwarded.push('--stats-cleanup-dry-run');
+    }
+    if (args.statsCleanupLookbackDays) {
+      forwarded.push('--stats-cleanup-lookback-days', String(args.statsCleanupLookbackDays));
+    }
    if (shouldForwardLogLevel(args.logLevel)) {
      forwarded.push('--log-level', args.logLevel);
    }
@@ -1,5 +1,9 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { runUpdateCommand } from './update-command';
 import type { LauncherCommandContext } from './context';

@@ -36,6 +40,11 @@ test('runUpdateCommand updates directly on Linux without launching Electron', as
        launcher: { status: 'updated' },
        supportAssets: [
          { status: 'updated', component: 'theme', message: 'Installed theme.' },
+          {
+            status: 'updated',
+            component: 'thumbnailer',
+            message: 'Installed rofi thumbnailer.',
+          },
          { status: 'skipped', component: 'plugin', message: 'Plugin already up to date.' },
        ],
      };
@@ -52,10 +61,29 @@ test('runUpdateCommand updates directly on Linux without launching Electron', as
    'info:AppImage update: updated',
    'info:Launcher update: updated',
    'info:Support assets (theme) update: updated - Installed theme.',
+    'info:Support assets (thumbnailer) update: updated - Installed rofi thumbnailer.',
    'info:Support assets (plugin) update: skipped - Plugin already up to date.',
  ]);
 });

+test('runUpdateCommand sends symlinked AUR installs to the package helper without network access', async () => {
+  const calls: string[] = [];
+  const handled = await runUpdateCommand(makeContext({ appPath: '/usr/bin/SubMiner.AppImage' }), {
+    resolveRealPath: () => '/opt/SubMiner/SubMiner.AppImage',
+    runDirectReleaseUpdate: async () => {
+      throw new Error('must not check GitHub releases for an AUR install');
+    },
+    log: (level, _configured, message) => {
+      calls.push(`${level}:${message}`);
+    },
+  });
+
+  assert.equal(handled, true);
+  assert.deepEqual(calls, [
+    'warn:SubMiner is installed through subminer-bin. Update it with your AUR helper, for example: yay -S subminer-bin.',
+  ]);
+});
+
 test('runUpdateCommand skips Linux asset replacement when release is not newer', async () => {
  const calls: string[] = [];
  const originalFetch = globalThis.fetch;
@@ -112,6 +140,65 @@ test('runUpdateCommand skips Linux asset replacement when release is not newer',
  }
 });

+test('Linux update does not replace the launcher after an AppImage hash failure', async () => {
+  const workspace = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-update-order-'));
+  const appImagePath = path.join(workspace, 'SubMiner.AppImage');
+  const launcherPath = path.join(workspace, 'subminer');
+  fs.writeFileSync(appImagePath, 'old app');
+  fs.writeFileSync(launcherPath, '#!/bin/sh\n# SubMiner launcher\n');
+
+  const fetched: string[] = [];
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async (input: string | URL | Request) => {
+    const url = input instanceof Request ? input.url : String(input);
+    fetched.push(url);
+    if (url.endsWith('/releases')) {
+      return Response.json([
+        {
+          tag_name: 'v999.0.0',
+          prerelease: false,
+          draft: false,
+          assets: [
+            {
+              name: 'SHA256SUMS.txt',
+              browser_download_url: 'https://example.test/SHA256SUMS.txt',
+            },
+            {
+              name: 'SubMiner.AppImage',
+              browser_download_url: 'https://example.test/SubMiner.AppImage',
+            },
+            { name: 'subminer', browser_download_url: 'https://example.test/subminer' },
+          ],
+        },
+      ]);
+    }
+    if (url.endsWith('/SHA256SUMS.txt')) {
+      return new Response(
+        `${createHash('sha256').update('expected app').digest('hex')}  SubMiner.AppImage\n${createHash('sha256').update('new launcher').digest('hex')}  subminer\n`,
+      );
+    }
+    if (url.endsWith('/SubMiner.AppImage')) {
+      return new Response('corrupt app');
+    }
+    throw new Error(`launcher asset should not be fetched: ${url}`);
+  }) as typeof globalThis.fetch;
+
+  try {
+    const handled = await runUpdateCommand(
+      makeContext({ appPath: appImagePath, scriptPath: launcherPath }),
+      { readMainConfig: () => null, log: () => {} },
+    );
+
+    assert.equal(handled, true);
+    assert.equal(fs.readFileSync(appImagePath, 'utf8'), 'old app');
+    assert.equal(fs.readFileSync(launcherPath, 'utf8'), '#!/bin/sh\n# SubMiner launcher\n');
+    assert.equal(fetched.includes('https://example.test/subminer'), false);
+  } finally {
+    globalThis.fetch = originalFetch;
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
 test('runUpdateCommand keeps app-mediated update path on non-Linux', async () => {
  const calls: string[] = [];

@@ -142,3 +229,32 @@ test('runUpdateCommand keeps app-mediated update path on non-Linux', async () =>
    'remove:/tmp/subminer-update-test',
  ]);
 });
+
+test('managed launcher passes its wrapper to app updates, protecting signed resources', async () => {
+  const previous = process.env.SUBMINER_LAUNCHER_PATH;
+  process.env.SUBMINER_LAUNCHER_PATH = '/Users/tester/.local/bin/subminer';
+  try {
+    let forwarded: string[] = [];
+    await runUpdateCommand(
+      makeContext({
+        processAdapter: { ...makeContext().processAdapter, platform: () => 'darwin' },
+        scriptPath: '/Applications/SubMiner.app/Contents/Resources/launcher/subminer',
+        appPath: '/Applications/SubMiner.app/Contents/MacOS/SubMiner',
+      }),
+      {
+        createTempDir: () => '/tmp/subminer-update-test',
+        joinPath: (...parts) => parts.join('/'),
+        runAppCommandCaptureOutput: (_app, args) => {
+          forwarded = args;
+          return { status: 0, stdout: '', stderr: '' };
+        },
+        waitForUpdateResponse: async () => ({ ok: true }),
+        removeDir: () => {},
+      },
+    );
+    assert.equal(forwarded[2], '/Users/tester/.local/bin/subminer');
+  } finally {
+    if (previous === undefined) delete process.env.SUBMINER_LAUNCHER_PATH;
+    else process.env.SUBMINER_LAUNCHER_PATH = previous;
+  }
+});
@@ -21,7 +21,10 @@ import {
  parseSha256Sums,
  type FetchLike,
 } from '../../src/main/runtime/update/release-assets.js';
-import { updateSupportAssetsFromRelease } from '../../src/main/runtime/update/support-assets.js';
+import {
+  updateSupportAssetsFromRelease,
+  type SupportAssetsUpdateResult,
+} from '../../src/main/runtime/update/support-assets.js';

 type UpdateCommandResponse = {
  ok: boolean;
@@ -36,15 +39,14 @@ type DirectReleaseUpdateRequest = {
  channel: UpdateChannel;
 };

+type DirectSupportAssetsUpdateResult = Omit<SupportAssetsUpdateResult, 'status'> & {
+  status: string;
+};
+
 type DirectReleaseUpdateResult = {
  appImage: { status: string; command?: string; message?: string };
  launcher: { status: string; command?: string; message?: string };
-  supportAssets: Array<{
-    status: string;
-    component?: 'theme' | 'plugin';
-    command?: string;
-    message?: string;
-  }>;
+  supportAssets: DirectSupportAssetsUpdateResult[];
 };

 type UpdateCommandDeps = {
@@ -56,6 +58,7 @@ type UpdateCommandDeps = {
  ) => { status: number; stdout: string; stderr: string; error?: Error };
  waitForUpdateResponse: (responsePath: string) => Promise<UpdateCommandResponse>;
  removeDir: (targetPath: string) => void;
+  resolveRealPath: (targetPath: string) => string;
  runDirectReleaseUpdate: (
    request: DirectReleaseUpdateRequest,
  ) => Promise<DirectReleaseUpdateResult>;
@@ -96,25 +99,36 @@ async function runDirectReleaseUpdate(
      : new Map<string, string>();
  const downloadAsset = (url: string) => fetchReleaseAssetBuffer(fetchForUpdater, url);

-  const [appImage, launcher, supportAssets] = await Promise.all([
-    updateAppImageFromRelease({
-      release,
-      sha256Sums,
-      appImagePath: request.appPath,
-      downloadAsset,
-    }),
-    updateLauncherFromRelease({
+  const appImage = await updateAppImageFromRelease({
+    release,
+    sha256Sums,
+    appImagePath: request.appPath,
+    downloadAsset,
+  });
+  let launcher: DirectReleaseUpdateResult['launcher'];
+  if (appImage.status !== 'updated') {
+    launcher = {
+      status: 'skipped',
+      message: 'Launcher update requires a successful AppImage update first.',
+    };
+  } else if (process.env.SUBMINER_MANAGED_LAUNCHER === '1') {
+    launcher = {
+      status: 'skipped',
+      message: 'This launcher is updated with the SubMiner app.',
+    };
+  } else {
+    launcher = await updateLauncherFromRelease({
      release,
      sha256Sums,
      launcherPath: request.launcherPath,
      downloadAsset,
-    }),
-    updateSupportAssetsFromRelease({
-      release,
-      sha256Sums,
-      downloadAsset,
-    }),
-  ]);
+    });
+  }
+  const supportAssets = await updateSupportAssetsFromRelease({
+    release,
+    sha256Sums,
+    downloadAsset,
+  });

  return { appImage, launcher, supportAssets };
 }
@@ -129,12 +143,7 @@ function readUpdateChannel(root: Record<string, unknown> | null): UpdateChannel

 function logUpdateResult(
  label: string,
-  result: {
-    status: string;
-    component?: 'theme' | 'plugin';
-    command?: string;
-    message?: string;
-  },
+  result: DirectSupportAssetsUpdateResult,
  configuredLogLevel: NonNullable<LauncherCommandContext['args']['logLevel']>,
  deps: Pick<UpdateCommandDeps, 'log'>,
 ): void {
@@ -176,6 +185,13 @@ const defaultDeps: UpdateCommandDeps = {
  removeDir: (targetPath) => {
    fs.rmSync(targetPath, { recursive: true, force: true });
  },
+  resolveRealPath: (targetPath) => {
+    try {
+      return fs.realpathSync(targetPath);
+    } catch {
+      return targetPath;
+    }
+  },
  runDirectReleaseUpdate,
  readMainConfig: readLauncherMainConfigObject,
  log: launcherLog,
@@ -192,12 +208,20 @@ export async function runUpdateCommand(
  }

  if (context.processAdapter.platform() === 'linux') {
+    const logLevel = args.logLevel ?? 'warn';
+    if (resolvedDeps.resolveRealPath(appPath) === '/opt/SubMiner/SubMiner.AppImage') {
+      resolvedDeps.log(
+        'warn',
+        logLevel,
+        'SubMiner is installed through subminer-bin. Update it with your AUR helper, for example: yay -S subminer-bin.',
+      );
+      return true;
+    }
    const result = await resolvedDeps.runDirectReleaseUpdate({
      appPath,
      launcherPath: scriptPath,
      channel: readUpdateChannel(resolvedDeps.readMainConfig()),
    });
-    const logLevel = args.logLevel ?? 'warn';
    logUpdateResult('AppImage', result.appImage, logLevel, resolvedDeps);
    logUpdateResult('Launcher', result.launcher, logLevel, resolvedDeps);
    for (const supportResult of result.supportAssets) {
@@ -206,6 +230,7 @@ export async function runUpdateCommand(
    return true;
  }

+  const launcherPath = path.resolve(process.env.SUBMINER_LAUNCHER_PATH ?? scriptPath);
  const tempDir = resolvedDeps.createTempDir('subminer-update-');
  const responsePath = resolvedDeps.joinPath(tempDir, 'response.json');

@@ -213,7 +238,7 @@ export async function runUpdateCommand(
    const result = resolvedDeps.runAppCommandCaptureOutput(appPath, [
      '--update',
      '--update-launcher-path',
-      scriptPath,
+      launcherPath,
      '--update-response-path',
      responsePath,
    ]);
@@ -134,6 +134,9 @@ test('applyInvocationsToArgs maps config and jellyfin invocation state', () => {
    statsCleanup: false,
    statsCleanupVocab: false,
    statsCleanupLifetime: false,
+    statsCleanupDuplicateLines: false,
+    statsCleanupDryRun: false,
+    statsCleanupLookbackDays: null,
    statsLogLevel: null,
    syncTriggered: false,
    syncCliTokens: [],
@@ -185,6 +188,9 @@ test('applyInvocationsToArgs maps settings invocation to settings window', () =>
    statsCleanup: false,
    statsCleanupVocab: false,
    statsCleanupLifetime: false,
+    statsCleanupDuplicateLines: false,
+    statsCleanupDryRun: false,
+    statsCleanupLookbackDays: null,
    statsLogLevel: null,
    syncTriggered: false,
    syncCliTokens: [],
@@ -229,6 +235,9 @@ test('applyInvocationsToArgs fails when config invocation has no action', () =>
      statsCleanup: false,
      statsCleanupVocab: false,
      statsCleanupLifetime: false,
+      statsCleanupDuplicateLines: false,
+      statsCleanupDryRun: false,
+      statsCleanupLookbackDays: null,
      statsLogLevel: null,
      syncTriggered: false,
      syncCliTokens: [],
@@ -271,6 +280,9 @@ test('applyInvocationsToArgs maps texthooker browser-open request', () => {
    statsCleanup: false,
    statsCleanupVocab: false,
    statsCleanupLifetime: false,
+    statsCleanupDuplicateLines: false,
+    statsCleanupDryRun: false,
+    statsCleanupLookbackDays: null,
    statsLogLevel: null,
    syncTriggered: false,
    syncCliTokens: [],
@@ -162,6 +162,8 @@ export function createDefaultArgs(
    statsCleanup: false,
    statsCleanupVocab: false,
    statsCleanupLifetime: false,
+    statsCleanupDuplicateLines: false,
+    statsCleanupDryRun: false,
    doctor: false,
    doctorRefreshKnownWords: false,
    logsExport: false,
@@ -258,6 +260,11 @@ export function applyInvocationsToArgs(parsed: Args, invocations: CliInvocations
  if (invocations.statsCleanup) parsed.statsCleanup = true;
  if (invocations.statsCleanupVocab) parsed.statsCleanupVocab = true;
  if (invocations.statsCleanupLifetime) parsed.statsCleanupLifetime = true;
+  if (invocations.statsCleanupDuplicateLines) parsed.statsCleanupDuplicateLines = true;
+  if (invocations.statsCleanupDryRun) parsed.statsCleanupDryRun = true;
+  if (invocations.statsCleanupLookbackDays !== null) {
+    parsed.statsCleanupLookbackDays = invocations.statsCleanupLookbackDays;
+  }
  if (invocations.dictionaryTarget) {
    parsed.dictionaryTarget = parseDictionaryTarget(invocations.dictionaryTarget);
  } else if (
@@ -37,6 +37,9 @@ export interface CliInvocations {
  statsCleanup: boolean;
  statsCleanupVocab: boolean;
  statsCleanupLifetime: boolean;
+  statsCleanupDuplicateLines: boolean;
+  statsCleanupDryRun: boolean;
+  statsCleanupLookbackDays: number | null;
  statsLogLevel: string | null;
  syncTriggered: boolean;
  syncCliTokens: string[];
@@ -53,6 +56,16 @@ export interface CliInvocations {
  texthookerOpenBrowser: boolean;
 }

+/** `--lookback-days` narrows the duplicate-line cleanup; fractions are floored. */
+function parseStatsLookbackDays(value: unknown): number | null {
+  if (typeof value !== 'string' && typeof value !== 'number') return null;
+  const days = Number(value);
+  if (!Number.isFinite(days) || days < 1) {
+    throw new Error('Stats --lookback-days must be at least one day.');
+  }
+  return Math.floor(days);
+}
+
 function applyRootOptions(program: Command): void {
  program
    .option(
@@ -169,6 +182,9 @@ export function parseCliPrograms(
  let statsCleanup = false;
  let statsCleanupVocab = false;
  let statsCleanupLifetime = false;
+  let statsCleanupDuplicateLines = false;
+  let statsCleanupDryRun = false;
+  let statsCleanupLookbackDays: number | null = null;
  let statsLogLevel: string | null = null;
  let syncTriggered = false;
  let syncCliTokens: string[] = [];
@@ -269,6 +285,9 @@ export function parseCliPrograms(
    .option('-s, --stop', 'Stop the background stats server')
    .option('-v, --vocab', 'Clean vocabulary rows in the stats database')
    .option('-l, --lifetime', 'Rebuild lifetime summary rows from retained data')
+    .option('-d, --duplicate-lines', 'Collapse repeated subtitle lines from typeset animations')
+    .option('--dry-run', 'Report what a cleanup would remove without changing anything')
+    .option('--lookback-days <days>', 'Only clean lines recorded in the last N days')
    .option('--log-level <level>', 'Log level')
    .action((action: string | undefined, options: Record<string, unknown>) => {
      statsTriggered = true;
@@ -289,13 +308,35 @@ export function parseCliPrograms(
      if (normalizedAction && (statsBackground || statsStop)) {
        throw new Error('Stats background and stop flags cannot be combined with stats actions.');
      }
-      if (normalizedAction !== 'cleanup' && (options.vocab === true || options.lifetime === true)) {
-        throw new Error('Stats --vocab and --lifetime flags require the cleanup action.');
+      if (
+        normalizedAction !== 'cleanup' &&
+        (options.vocab === true || options.lifetime === true || options.duplicateLines === true)
+      ) {
+        throw new Error(
+          'Stats --vocab, --lifetime and --duplicate-lines flags require the cleanup action.',
+        );
+      }
+      if (
+        options.duplicateLines !== true &&
+        (options.dryRun === true || options.lookbackDays !== undefined)
+      ) {
+        throw new Error('Stats --dry-run and --lookback-days require --duplicate-lines.');
      }
      if (normalizedAction === 'cleanup') {
        statsCleanup = true;
        statsCleanupLifetime = options.lifetime === true;
-        statsCleanupVocab = statsCleanupLifetime ? false : options.vocab !== false;
+        statsCleanupDuplicateLines = options.duplicateLines === true;
+        const explicitModeCount = [options.vocab, options.lifetime, options.duplicateLines].filter(
+          (value) => value === true,
+        ).length;
+        if (explicitModeCount > 1) {
+          throw new Error('Stats cleanup runs one mode at a time.');
+        }
+        // Vocabulary cleanup stays the default so `stats cleanup` keeps its old meaning.
+        statsCleanupVocab =
+          statsCleanupLifetime || statsCleanupDuplicateLines ? false : options.vocab !== false;
+        statsCleanupDryRun = options.dryRun === true;
+        statsCleanupLookbackDays = parseStatsLookbackDays(options.lookbackDays);
      } else if (normalizedAction === 'rebuild' || normalizedAction === 'backfill') {
        statsCleanup = true;
        statsCleanupLifetime = true;
@@ -483,6 +524,9 @@ export function parseCliPrograms(
      statsCleanup,
      statsCleanupVocab,
      statsCleanupLifetime,
+      statsCleanupDuplicateLines,
+      statsCleanupDryRun,
+      statsCleanupLookbackDays,
      statsLogLevel,
      syncTriggered,
      syncCliTokens,
@@ -73,20 +73,21 @@ function makeTestEnv(homeDir: string, xdgConfigHome: string): NodeJS.ProcessEnv
  };
 }

-// On Linux the playback path runs `ensureLinuxRuntimePluginAvailable`, which —
-// when the runtime plugin/theme are missing — spawns the app with
-// `--ensure-linux-runtime-plugin-assets` and polls up to 30s
+// On Linux the playback path runs `ensureLinuxRuntimePluginAvailable`, which
+// spawns the app with `--ensure-linux-runtime-plugin-assets` when managed
+// support assets are missing and polls up to 30s
 // (RESPONSE_TIMEOUT_MS) for an install response. A fake app that just exits
 // never writes that response, so the launcher hangs and the test times out on
 // Linux CI (the preflight is a no-op on macOS/Windows). This shell prelude makes
-// the fake app install the managed plugin/theme and write the response, matching
+// the fake app install the managed support assets and write the response, matching
 // launcher/smoke.e2e.test.ts. Prepend it to each fake app that reaches playback.
 const RUNTIME_PLUGIN_PREFLIGHT_SH = `if [ "$1" = "--ensure-linux-runtime-plugin-assets" ]; then
  data="\${XDG_DATA_HOME:-$HOME/.local/share}/SubMiner"
-  mkdir -p "$data/plugin/subminer" "$data/themes"
+  mkdir -p "$data/plugin/subminer" "$data/themes" "$data/thumbnailers"
  printf -- '-- test plugin\\n' > "$data/plugin/subminer/main.lua"
  printf 'test=true\\n' > "$data/plugin/subminer.conf"
  printf '/* test theme */\\n' > "$data/themes/subminer.rasi"
+  printf '[Thumbnailer Entry]\\n' > "$data/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer"
  if [ "$2" = "--ensure-linux-runtime-plugin-assets-response-path" ] && [ -n "$3" ]; then
    mkdir -p "$(dirname "$3")"
    printf '{"ok":true,"status":"installed","path":"%s"}' "$data/plugin/subminer/main.lua" > "$3"
@@ -232,6 +232,75 @@ test('parseArgs maps lifetime stats cleanup flag', () => {
  assert.equal(parsed.statsCleanupLifetime, true);
 });

+test('parseArgs maps duplicate-line stats cleanup flags', () => {
+  const parsed = parseArgs(
+    ['stats', 'cleanup', '--duplicate-lines', '--dry-run', '--lookback-days', '30'],
+    'subminer',
+    {},
+  );
+
+  assert.equal(parsed.statsCleanup, true);
+  assert.equal(parsed.statsCleanupVocab, false);
+  assert.equal(parsed.statsCleanupDuplicateLines, true);
+  assert.equal(parsed.statsCleanupDryRun, true);
+  assert.equal(parsed.statsCleanupLookbackDays, 30);
+
+  const fractional = parseArgs(
+    ['stats', 'cleanup', '--duplicate-lines', '--lookback-days', '1.5'],
+    'subminer',
+    {},
+  );
+  assert.equal(fractional.statsCleanupLookbackDays, 1);
+});
+
+test('parseArgs rejects duplicate-line flags without the duplicate-lines mode', () => {
+  const error = withProcessExitIntercept(() => {
+    parseArgs(['stats', 'cleanup', '--dry-run'], 'subminer', {});
+  });
+
+  assert.equal(error.code, 1);
+  assert.match(error.stderr, /--dry-run and --lookback-days require --duplicate-lines/);
+});
+
+test('parseArgs rejects an empty lookback value outside duplicate-line cleanup', () => {
+  const error = withProcessExitIntercept(() => {
+    parseArgs(['stats', '--lookback-days', ''], 'subminer', {});
+  });
+
+  assert.equal(error.code, 1);
+  assert.match(error.stderr, /--dry-run and --lookback-days require --duplicate-lines/);
+});
+
+test('parseArgs rejects combining explicit cleanup modes', () => {
+  for (const modes of [
+    ['--lifetime', '--duplicate-lines'],
+    ['--vocab', '--duplicate-lines'],
+    ['--vocab', '--lifetime'],
+  ]) {
+    const error = withProcessExitIntercept(() => {
+      parseArgs(['stats', 'cleanup', ...modes], 'subminer', {});
+    });
+
+    assert.equal(error.code, 1);
+    assert.match(error.stderr, /Stats cleanup runs one mode at a time/);
+  }
+});
+
+test('parseArgs rejects unusable lookback windows', () => {
+  for (const value of ['0', '0.5', '-5', 'soon']) {
+    const error = withProcessExitIntercept(() => {
+      parseArgs(
+        ['stats', 'cleanup', '--duplicate-lines', '--lookback-days', value],
+        'subminer',
+        {},
+      );
+    });
+
+    assert.equal(error.code, 1);
+    assert.match(error.stderr, /--lookback-days must be at least one day/);
+  }
+});
+
 test('parseArgs rejects cleanup-only stats flags without cleanup action', () => {
  const error = withProcessExitIntercept(() => {
    parseArgs(['stats', '--vocab'], 'subminer', {});
@@ -239,7 +308,10 @@ test('parseArgs rejects cleanup-only stats flags without cleanup action', () =>

  assert.equal(error.code, 1);
  assert.match(error.message, /exit:1/);
-  assert.match(error.stderr, /Stats --vocab and --lifetime flags require the cleanup action/);
+  assert.match(
+    error.stderr,
+    /Stats --vocab, --lifetime and --duplicate-lines flags require the cleanup action/,
+  );
 });

 test('parseArgs maps stats rebuild action to cleanup lifetime mode', () => {
@@ -3,7 +3,12 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { findRofiTheme, formatRofiPrompt } from './picker';
+import {
+  findRofiTheme,
+  findRofiThumbnailerDataRoot,
+  formatRofiPrompt,
+  prependXdgDataDir,
+} from './picker';

 // ── formatRofiPrompt: spacing between prompt and input field ──────────────────

@@ -23,6 +28,7 @@ test('formatRofiPrompt leaves an empty prompt empty', () => {
 // ── findRofiTheme: Linux packaged path discovery ──────────────────────────────

 const ROFI_THEME_FILE = 'subminer.rasi';
+const ROFI_THUMBNAILER_FILE = 'subminer-ffmpegthumbnailer.thumbnailer';

 function makeFile(filePath: string): void {
  fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -121,3 +127,42 @@ test('findRofiTheme resolves ~/.local/share/SubMiner/themes/subminer.rasi when X
    fs.rmSync(baseDir, { recursive: true, force: true });
  }
 });
+
+test('findRofiThumbnailerDataRoot resolves the managed XDG data root', () => {
+  const xdgDataHome = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-test-xdg-'));
+  const originalXdgDataHome = process.env.XDG_DATA_HOME;
+  try {
+    process.env.XDG_DATA_HOME = xdgDataHome;
+    const dataRoot = path.join(xdgDataHome, 'SubMiner');
+    makeFile(path.join(dataRoot, 'thumbnailers', ROFI_THUMBNAILER_FILE));
+
+    const result = withPlatform('linux', () => findRofiThumbnailerDataRoot('/usr/bin/subminer'));
+    assert.equal(result, dataRoot);
+  } finally {
+    if (originalXdgDataHome === undefined) {
+      delete process.env.XDG_DATA_HOME;
+    } else {
+      process.env.XDG_DATA_HOME = originalXdgDataHome;
+    }
+    fs.rmSync(xdgDataHome, { recursive: true, force: true });
+  }
+});
+
+test('findRofiThumbnailerDataRoot is Linux-only', () => {
+  assert.equal(
+    withPlatform('darwin', () => findRofiThumbnailerDataRoot('/usr/bin/subminer')),
+    null,
+  );
+});
+
+test('prependXdgDataDir preserves existing roots and avoids duplicates', () => {
+  const root = '/tmp/subminer-data';
+  assert.equal(
+    prependXdgDataDir(root, `/opt/share${path.delimiter}${root}${path.delimiter}/usr/share`),
+    `${root}${path.delimiter}/opt/share${path.delimiter}/usr/share`,
+  );
+  assert.equal(
+    prependXdgDataDir(root),
+    `${root}${path.delimiter}/usr/local/share${path.delimiter}/usr/share`,
+  );
+});
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
sudacode	962442ccd5	fix(launcher): address review feedback on setup and runtime cleanup	2026-09-10 13:32:12 -07:00
sudacode	8c7ad75033	fix(launcher): preserve arguments through Windows command wrappers	2026-09-10 13:22:04 -07:00
sudacode	1213203228	feat(launcher): use private Bun for all release launchers	2026-09-10 13:14:16 -07:00
sudacode	84b234cc19	feat(launcher): bundle a private Bun runtime	2026-09-10 12:22:29 -07:00
sudacode	614a8ca912	fix(startup): create config directory before singleton lock (#242 )	2026-09-09 12:04:08 -07:00
sudacode	9eecb7358b	docs: refresh user-facing guides and examples - Clarify current integration, media review, and Anki behavior - Remove obsolete AI translation and configuration references - Standardize headings and prose across docs	2026-09-08 00:23:38 -07:00
sudacode	1e5d7747b4	feat(sidebar): add dialogue selection and copying (#238 )	2026-09-07 14:03:54 -07:00
sudacode	c14c690875	chore(release): prepare v0.19.6	2026-09-04 01:59:39 -07:00
sudacode	84f718043a	feat(anki): add media timing review before card creation (#203 )	2026-09-04 01:40:56 -07:00
sudacode	99266294b8	fix(tsukihime): filter releases by subtitle language (#235 )	2026-09-02 20:29:59 -07:00
sudacode	c055359be1	chore(deps): update fast-uri to 3.1.6	2026-09-02 20:16:08 -07:00
sudacode	ec5a147095	fix(subtitles): merge wrapped positioned caption rows (#234 )	2026-09-01 23:11:38 -07:00
sudacode	a0635f4360	fix(subtitles): drop ASS furigana from recorded cues (#233 )	2026-09-01 22:49:20 -07:00
sudacode	c0a78ef008	feat(anki): support Senren scene-switching field grouping (#230 )	2026-09-01 22:18:30 -07:00
sudacode	87b01155df	fix(mining): copy multi-line subtitles backward from current line (#231 )	2026-09-01 22:17:41 -07:00
sudacode	fc5c49e365	fix(subtitles): keep native secondary subtitles hidden (#232 ) - Reapply hidden visibility after secondary track changes - Relinquish suppression only after successful restoration	2026-09-01 00:49:37 -07:00
sudacode	a20269e9f5	fix(jellyfin): stop inferring subtitle delays (#227 )	2026-08-31 23:31:31 -07:00
sudacode	2ad491e95c	chore(release): prepare v0.19.5	2026-08-30 01:02:44 -07:00
sudacode	6fffcc731f	fix(youtube): keep auto captions on screen for their full span (#219 )	2026-08-29 13:18:55 -07:00
sudacode	5cc21113fd	fix(subtitles): drop ASS furigana from published cues (#224 )	2026-08-29 13:15:30 -07:00
sudacode	051140f910	fix(anki): respect configured fields for word-card enrichment (#223 )	2026-08-29 13:09:31 -07:00
sudacode	6e945f0872	fix(subtitles): keep overlapping lines that join an already active cue (#221 )	2026-08-27 23:13:29 -07:00
sudacode	c2c25c0da6	fix(anki): keep overlay progress visible through card updates (#218 )	2026-08-25 20:27:58 -07:00
sudacode	556de61756	chore(changelog): split release details into nested bullets - Update changelog generation guidance and tests - Reformat current release notes and document the new style	2026-08-25 12:39:45 -07:00
sudacode	a98fb0fddf	chore(release): prepare v0.19.4	2026-08-25 02:43:48 -07:00
sudacode	e816b3b371	fix(subtitles): recover positioned ASS word spacing and drop control debris (#217 )	2026-08-25 02:22:21 -07:00
sudacodeandsudacode	ed7d3f4c3d	feat(release): track prerelease deltas and validate committed notes (#216 ) Co-authored-by: sudacode <claude@lmaoxd.lol>	2026-08-23 15:24:18 -07:00
sudacode	509dc5bf7f	fix(subtitles): improve secondary subtitle extraction and display (#215 )	2026-08-23 01:56:49 -07:00
sudacode	0a0aa3ec98	chore(release): prepare v0.19.4-beta.4	2026-08-23 01:23:16 -07:00
sudacode	b87cc3cfdd	chore(workflow): add release skill	2026-08-23 01:14:03 -07:00
sudacode	8cb3c8c90a	fix(macos): pin window helper deployment target to fix older systems - Build the Swift window-tracking helper with an explicit `-target ...-apple-macos12.0` instead of letting swiftc stamp the build machine's OS, so the overlay attaches to mpv on older macOS (e.g. Ventura) instead of crashing at load - Fold the standalone build-macos-helper.sh into prepare-build-assets.mjs and update docs/tests to match	2026-08-23 00:58:24 -07:00
sudacode	03ea903927	fix(subtitles): preserve authored spaces in fragmented ASS karaoke - Only trim indentation before slicing ASS event fields so a trailing authored space at a fragment's end is kept, preventing words from being joined together when fragmented karaoke lines are reconstructed - Add regression test covering event-boundary word spacing	2026-08-22 23:32:35 -07:00
sudacode	3aea42e6f8	chore(release): prepare v0.19.4-beta.3	2026-08-21 23:25:37 -07:00
sudacode	88bb3edfa4	fix(subtitles): preserve lyric selection and deduplicate secondary text - Seek sidebar selections past overlapping karaoke exit spans - Collapse duplicate long ASS lines and omit reconstructed sign grids	2026-08-21 01:28:00 -07:00
sudacode	9445aef004	fix(subtitles): navigate by sanitized cues across ASS animation - Route subtitle navigation through parsed cue boundaries - Treat explicit short seeks as subtitle priming events	2026-08-20 00:20:51 -07:00
sudacode	c01bcd9d0f	fix(subtitles): collapse layered ASS lyrics across startup and seeks - Reconstruct fragment-only karaoke while preserving canonical animated signs - Reprocess live subtitles after initial playback and seek updates - Add a development launcher for playable media files	2026-08-19 22:55:10 -07:00
sudacode	695613b1e7	chore(release): prepare v0.19.4-beta.2	2026-08-19 02:19:40 -07:00
sudacode	20797772f8	fix(character-dictionary): cache completed MeCab refreshes (#212 )	2026-08-19 01:49:15 -07:00
sudacode	72c312810a	docs: link README demo to GitHub video playback - Use GitHub-hosted video playback for the README demo - Document the animated fallback behavior	2026-08-19 01:02:05 -07:00
sudacode	b61f050e78	docs: update mining demo and scale video crops - Refresh mining demo assets and documentation references - Scale mpv crop coordinates for resized OBS recordings	2026-08-19 00:55:31 -07:00
sudacode	2a77ba9dd4	fix(launcher): restore Matroska thumbnails in Linux rofi picker (#210 )	2026-08-18 20:30:58 -07:00
sudacode	4ed878270f	fix(stats): accept legacy lexical rollup state schemas	2026-08-18 02:24:49 -07:00
sudacode	1d1b0c7bb6	fix(subtitles): collapse duplicate primary ASS style layers - Use parsed cues when they fully explain mpv live text - Preserve unmatched overlapping dialogue and signs	2026-08-18 01:51:19 -07:00
sudacode	db61ce358d	fix(stats): preserve session rollups across schema upgrades - Stop deleting imm_daily_rollups/imm_monthly_rollups on unrelated schema version bumps; their source session/telemetry rows may already be pruned, so deleted buckets could not be rebuilt - Run startup session-rollup maintenance before the lexical rollup backfill takes the write lock, so recovery no longer races playback writes - Update the vocabulary summary totals changelog fragment to reflect that watch-time, activity, efficiency, and library charts are no longer cleared during rebuilds	2026-08-18 01:12:58 -07:00
sudacode	e9778a945a	fix(overlay): deduplicate secondary subtitle rendering (#208 )	2026-08-18 00:44:02 -07:00
sudacode	7de73e16a1	fix(stats): report complete vocabulary totals and new-word history (#202 )	2026-08-18 00:42:46 -07:00
sudacode	273652f781	fix(subtitles): recover canonical lines from ASS animation (#207 )	2026-08-18 00:30:48 -07:00
sudacode	14c0086520	chore(stats): reword duplicates popup	2026-08-17 18:42:58 -07:00
sudacode	ff0bc0af6d	fix(dictionary): prevent freezes and restore AppImage notifications (#205 )	2026-08-17 18:41:03 -07:00
sudacode	00b1b79bf4	fix(mpv): recover from stalled IPC connects (#204 )	2026-08-16 22:58:28 -07:00
sudacode	e11a5fea0d	chore(release): prepare v0.19.4-beta.1	2026-08-16 02:00:32 -07:00
sudacode	f73fe179d0	fix(docs): keep versioned pages out of search indexes - Add self-canonical noindex signals and headers for archived docs - Restore sitemap lastmod dates from the tracked checkout	2026-08-16 01:45:08 -07:00
sudacode	2938e7a32a	fix(overlay): prevent Windows mouse lag during click-through tracking (#201 )	2026-08-16 01:34:51 -07:00
sudacode	82f6b4705a	fix(overlay): recycle Windows modal windows after close - Refresh the hidden modal renderer between Windows sessions - Add regression coverage and stabilize launcher completion testing	2026-08-16 01:10:07 -07:00
sudacode	a02c33dac4	fix(overlay): keep macOS modal windows on fullscreen Spaces (#200 )	2026-08-15 21:43:26 -07:00
sudacode	2174e689a2	fix(overlay): support native Wayland file drag-and-drop (#199 )	2026-08-15 00:15:38 -07:00
sudacode	7d729cb60c	fix(notifications): replace Linux progress updates in place (#198 )	2026-08-14 22:20:33 -07:00
sudacode	d963def1a9	fix(stats): subtract lifetime totals incrementally on delete (#196 )	2026-08-14 22:13:59 -07:00
sudacode	6fb3d2eb13	feat(stats): add library entry merge and episode move (#190 )	2026-08-14 21:54:17 -07:00
sudacode	c5a77ac067	fix(anki): snapshot mining media clip timing (#197 )	2026-08-14 21:50:32 -07:00
sudacode	8ddc151435	docs: hide unfinished feature demos from sidebar	2026-08-14 21:50:08 -07:00
sudacode	b98d4d65c7	fix(stats): stop counting duplicate typeset subtitle lines (#191 )	2026-08-14 00:12:56 -07:00
sudacode	046e74ea91	chore(workflow): simplify agent tooling and docs	2026-08-13 23:34:04 -07:00
sudacode	8bf847503d	fix(media): tolerate slow MKV audio extraction (#195 )	2026-08-13 23:19:22 -07:00