chore(release): prepare v0.14.0

- Delete Backlog.md and all backlog/ task files
- Remove Backlog.md MCP workflow instructions from AGENTS.md
- Drop "backlog history" from change-verification shim compatibility note

.agents/plugins/marketplace.json

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

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

@@ -0,0 +1,22 @@
+---
+name: 'subminer-change-verification'
+description: 'Compatibility shim. Canonical SubMiner change verification workflow now lives in the repo-local subminer-workflow plugin.'
+---
+
+# Compatibility Shim
+
+Canonical source:
+
+- `plugins/subminer-workflow/skills/subminer-change-verification/SKILL.md`
+
+Canonical helper scripts:
+
+- `plugins/subminer-workflow/skills/subminer-change-verification/scripts/classify_subminer_diff.sh`
+- `plugins/subminer-workflow/skills/subminer-change-verification/scripts/verify_subminer_change.sh`
+
+When this shim is invoked:
+
+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.

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

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

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

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

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

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

.github/pull_request_template.md

@@ -0,0 +1,3 @@
+## Checklist
+
+- [ ] Added a changelog fragment in `changes/`, or this PR is labeled `skip-changelog`

.github/workflows/ci.yml

@@ -13,6 +13,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
+          fetch-depth: 0
           submodules: true
 
       - name: Setup Bun
@@ -20,32 +21,56 @@ jobs:
         with:
           bun-version: 1.3.5
 
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22.12.0
-
       - name: Cache dependencies
         uses: actions/cache@v4
         with:
           path: |
             ~/.bun/install/cache
             node_modules
+            stats/node_modules
             vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
           restore-keys: |
             ${{ runner.os }}-bun-
 
       - name: Install dependencies
-        run: bun install --frozen-lockfile
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Lint changelog fragments
+        run: bun run changelog:lint
+
+      - name: Lint stats (formatting)
+        run: bun run lint:stats
+
+      - name: Enforce pull request changelog fragments (`skip-changelog` label bypass)
+        if: github.event_name == 'pull_request'
+        run: bun run changelog:pr-check --base-ref "origin/${{ github.base_ref }}" --head-ref "HEAD" --labels "${{ join(github.event.pull_request.labels.*.name, ',') }}"
 
       - name: Build (TypeScript check)
         # Keep explicit typecheck for fast fail before full build/bundle.
         run: bun run typecheck
 
+      - name: Verify generated config examples
+        run: bun run verify:config-example
+
+      - name: Internal docs knowledge-base checks
+        run: bun run test:docs:kb
+
       - name: Test suite (source)
         run: bun run test:fast
 
+      - name: Coverage suite (maintained source lane)
+        run: bun run test:coverage:src
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-test-src
+          path: coverage/test-src/lcov.info
+          if-no-files-found: error
+
       - name: Launcher smoke suite (source)
         run: bun run test:launcher:smoke:src
 

.github/workflows/prerelease.yml

@@ -0,0 +1,406 @@
+name: Prerelease
+
+on:
+  push:
+    tags:
+      - 'v*-beta.*'
+      - 'v*-rc.*'
+
+concurrency:
+  group: prerelease-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  quality-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Lint stats (formatting)
+        run: bun run lint:stats
+
+      - name: Build (TypeScript check)
+        run: bun run typecheck
+
+      - name: Test suite (source)
+        run: bun run test:fast
+
+      - name: Environment suite
+        run: bun run test:env
+
+      - name: Coverage suite (maintained source lane)
+        run: bun run test:coverage:src
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-test-src
+          path: coverage/test-src/lcov.info
+          if-no-files-found: error
+
+      - name: Launcher smoke suite (source)
+        run: bun run test:launcher:smoke:src
+
+      - name: Upload launcher smoke artifacts (on failure)
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: launcher-smoke
+          path: .tmp/launcher-smoke/**
+          if-no-files-found: ignore
+
+      - name: Build (bundle)
+        run: bun run build
+
+      - name: Immersion SQLite verification
+        run: bun run test:immersion:sqlite:dist
+
+      - name: Dist smoke suite
+        run: bun run test:smoke:dist
+
+  build-linux:
+    needs: [quality-gate]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Build texthooker-ui
+        run: |
+          cd vendor/texthooker-ui
+          bun install
+          bun run build
+
+      - name: Build AppImage
+        run: bun run build:appimage
+
+      - name: Build unversioned AppImage
+        run: |
+          shopt -s nullglob
+          appimages=(release/SubMiner-*.AppImage)
+          if [ "${#appimages[@]}" -eq 0 ]; then
+            echo "No versioned AppImage found to create unversioned artifact."
+            ls -la release
+            exit 1
+          fi
+          cp "${appimages[0]}" release/SubMiner.AppImage
+
+      - name: Upload AppImage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: appimage
+          path: release/*.AppImage
+          if-no-files-found: error
+
+  build-macos:
+    needs: [quality-gate]
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Validate macOS signing/notarization secrets
+        run: |
+          missing=0
+          for name in CSC_LINK CSC_KEY_PASSWORD APPLE_ID APPLE_APP_SPECIFIC_PASSWORD APPLE_TEAM_ID; do
+            if [ -z "${!name}" ]; then
+              echo "Missing required secret: $name"
+              missing=1
+            fi
+          done
+          if [ "$missing" -ne 0 ]; then
+            echo "Set all required macOS signing/notarization secrets and rerun."
+            exit 1
+          fi
+        env:
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Build texthooker-ui
+        run: |
+          cd vendor/texthooker-ui
+          bun install
+          bun run build
+
+      - name: Build signed + notarized macOS artifacts
+        run: bun run build:mac
+        env:
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Upload macOS artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos
+          path: |
+            release/*.dmg
+            release/*.zip
+          if-no-files-found: error
+
+  build-windows:
+    needs: [quality-gate]
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Build texthooker-ui
+        shell: powershell
+        run: |
+          Set-Location vendor/texthooker-ui
+          bun install
+          bun run build
+
+      - name: Build unsigned Windows artifacts
+        run: bun run build:win:unsigned
+
+      - name: Upload Windows artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows
+          path: |
+            release/*.exe
+            release/*.zip
+          if-no-files-found: error
+
+  release:
+    needs: [build-linux, build-macos, build-windows]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Download AppImage
+        uses: actions/download-artifact@v4
+        with:
+          name: appimage
+          path: release
+
+      - name: Download macOS artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: macos
+          path: release
+
+      - name: Download Windows artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: windows
+          path: release
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build Bun subminer wrapper
+        run: make build-launcher
+
+      - name: Verify Bun subminer wrapper
+        run: dist/launcher/subminer --help >/dev/null
+
+      - name: Enforce generated launcher workflow
+        run: bash scripts/verify-generated-launcher.sh
+
+      - name: Verify generated config examples
+        run: bun run verify:config-example
+
+      - name: Package optional assets bundle
+        run: |
+          tar -czf "release/subminer-assets.tar.gz" \
+            config.example.jsonc \
+            plugin/subminer \
+            plugin/subminer.conf \
+            assets/themes/subminer.rasi
+
+      - name: Generate checksums
+        run: |
+          shopt -s nullglob
+          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz dist/launcher/subminer)
+          if [ "${#files[@]}" -eq 0 ]; then
+            echo "No release artifacts found for checksum generation."
+            exit 1
+          fi
+          : > release/SHA256SUMS.txt
+          for file in "${files[@]}"; do
+            printf '%s  %s\n' \
+              "$(sha256sum "$file" | awk '{print $1}')" \
+              "${file##*/}" >> release/SHA256SUMS.txt
+          done
+
+      - name: Get version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+
+      - name: Generate prerelease notes from pending fragments
+        run: bun run changelog:prerelease-notes --version "${{ steps.version.outputs.VERSION }}"
+
+      - name: Publish Prerelease
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          shopt -s nullglob
+          artifacts=(
+            release/*.AppImage
+            release/*.dmg
+            release/*.exe
+            release/*.zip
+            release/*.tar.gz
+            release/SHA256SUMS.txt
+            dist/launcher/subminer
+          )
+
+          if [ "${#artifacts[@]}" -eq 0 ]; then
+            echo "No release artifacts found for upload."
+            exit 1
+          fi
+
+          if gh release view "${{ steps.version.outputs.VERSION }}" >/dev/null 2>&1; then
+            gh release edit "${{ steps.version.outputs.VERSION }}" \
+              --draft \
+              --prerelease \
+              --title "${{ steps.version.outputs.VERSION }}" \
+              --notes-file release/prerelease-notes.md
+          else
+            gh release create "${{ steps.version.outputs.VERSION }}" \
+              --draft \
+              --latest=false \
+              --prerelease \
+              --title "${{ steps.version.outputs.VERSION }}" \
+              --notes-file release/prerelease-notes.md
+          fi
+
+          for asset in "${artifacts[@]}"; do
+            gh release upload "${{ steps.version.outputs.VERSION }}" "$asset" --clobber
+          done
+
+          gh release edit "${{ steps.version.outputs.VERSION }}" \
+            --draft=false \
+            --prerelease \
+            --title "${{ steps.version.outputs.VERSION }}" \
+            --notes-file release/prerelease-notes.md

.github/workflows/release.yml

@@ -4,14 +4,13 @@ on:
   push:
     tags:
       - 'v*'
+      - '!v*-beta.*'
+      - '!v*-rc.*'
 
 concurrency:
   group: release-${{ github.ref }}
   cancel-in-progress: false
 
-permissions:
-  contents: write
-
 jobs:
   quality-gate:
     runs-on: ubuntu-latest
@@ -26,24 +25,25 @@ jobs:
         with:
           bun-version: 1.3.5
 
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22.12.0
-
       - name: Cache dependencies
         uses: actions/cache@v4
         with:
           path: |
             ~/.bun/install/cache
             node_modules
+            stats/node_modules
             vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
           restore-keys: |
             ${{ runner.os }}-bun-
 
       - name: Install dependencies
-        run: bun install --frozen-lockfile
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Lint stats (formatting)
+        run: bun run lint:stats
 
       - name: Build (TypeScript check)
         run: bun run typecheck
@@ -51,6 +51,16 @@ jobs:
       - name: Test suite (source)
         run: bun run test:fast
 
+      - name: Coverage suite (maintained source lane)
+        run: bun run test:coverage:src
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-test-src
+          path: coverage/test-src/lcov.info
+          if-no-files-found: error
+
       - name: Launcher smoke suite (source)
         run: bun run test:launcher:smoke:src
 
@@ -85,25 +95,23 @@ jobs:
         with:
           bun-version: 1.3.5
 
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22.12.0
-
       - name: Cache dependencies
         uses: actions/cache@v4
         with:
           path: |
             ~/.bun/install/cache
             node_modules
+            stats/node_modules
             vendor/texthooker-ui/node_modules
             vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
           restore-keys: |
             ${{ runner.os }}-bun-
 
       - name: Install dependencies
-        run: bun install --frozen-lockfile
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
 
       - name: Build texthooker-ui
         run: |
@@ -113,8 +121,6 @@ jobs:
 
       - name: Build AppImage
         run: bun run build:appimage
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build unversioned AppImage
         run: |
@@ -147,20 +153,16 @@ jobs:
         with:
           bun-version: 1.3.5
 
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22.12.0
-
       - name: Cache dependencies
         uses: actions/cache@v4
         with:
           path: |
             ~/.bun/install/cache
             node_modules
+            stats/node_modules
             vendor/texthooker-ui/node_modules
             vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
           restore-keys: |
             ${{ runner.os }}-bun-
 
@@ -185,7 +187,9 @@ jobs:
           APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
 
       - name: Install dependencies
-        run: bun install --frozen-lockfile
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
 
       - name: Build texthooker-ui
         run: |
@@ -196,7 +200,6 @@ jobs:
       - name: Build signed + notarized macOS artifacts
         run: bun run build:mac
         env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           CSC_LINK: ${{ secrets.CSC_LINK }}
           CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
           APPLE_ID: ${{ secrets.APPLE_ID }}
@@ -211,9 +214,62 @@ jobs:
             release/*.dmg
             release/*.zip
 
+  build-windows:
+    needs: [quality-gate]
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Build texthooker-ui
+        shell: powershell
+        run: |
+          Set-Location vendor/texthooker-ui
+          bun install
+          bun run build
+
+      - name: Build unsigned Windows artifacts
+        run: bun run build:win:unsigned
+
+      - name: Upload Windows artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows
+          path: |
+            release/*.exe
+            release/*.zip
+          if-no-files-found: error
+
   release:
-    needs: [build-linux, build-macos]
+    needs: [build-linux, build-macos, build-windows]
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -232,6 +288,12 @@ jobs:
           name: macos
           path: release
 
+      - name: Download Windows artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: windows
+          path: release
+
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
@@ -259,6 +321,9 @@ jobs:
       - name: Enforce generated launcher workflow
         run: bash scripts/verify-generated-launcher.sh
 
+      - name: Verify generated config examples
+        run: bun run verify:config-example
+
       - name: Package optional assets bundle
         run: |
           tar -czf "release/subminer-assets.tar.gz" \
@@ -270,34 +335,34 @@ jobs:
       - name: Generate checksums
         run: |
           shopt -s nullglob
-          files=(release/*.AppImage release/*.dmg release/*.zip release/*.tar.gz dist/launcher/subminer)
+          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz dist/launcher/subminer)
           if [ "${#files[@]}" -eq 0 ]; then
             echo "No release artifacts found for checksum generation."
             exit 1
           fi
-          sha256sum "${files[@]}" > release/SHA256SUMS.txt
+          : > release/SHA256SUMS.txt
+          for file in "${files[@]}"; do
+            printf '%s  %s\n' \
+              "$(sha256sum "$file" | awk '{print $1}')" \
+              "${file##*/}" >> release/SHA256SUMS.txt
+          done
 
       - name: Get version from tag
         id: version
-        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
 
-      - name: Generate changelog
-        id: changelog
+      - name: Guard against pending changelog fragments
         run: |
-          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
-          if [ -n "$PREV_TAG" ]; then
-            CHANGES=$(git log --pretty=format:"- %s" ${PREV_TAG}..HEAD)
-          else
-            COMMIT_COUNT=$(git rev-list --count HEAD)
-            if [ "$COMMIT_COUNT" -gt 10 ]; then
-              CHANGES=$(git log --pretty=format:"- %s" HEAD~10..HEAD)
-            else
-              CHANGES=$(git log --pretty=format:"- %s")
-            fi
+          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."
+            exit 1
           fi
-          echo "CHANGES<<EOF" >> $GITHUB_OUTPUT
-          echo "$CHANGES" >> $GITHUB_OUTPUT
-          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Verify changelog is ready for tagged release
+        run: bun run changelog:check --version "${{ steps.version.outputs.VERSION }}"
+
+      - name: Generate release notes from changelog
+        run: bun run changelog:release-notes --version "${{ steps.version.outputs.VERSION }}"
 
       - name: Publish Release
         env:
@@ -305,52 +370,23 @@ jobs:
         run: |
           set -euo pipefail
 
-          cat > release-body.md <<'EOF'
-          ## Changes
-          ${{ steps.changelog.outputs.CHANGES }}
-
-          ## Installation
-
-          ### AppImage (Recommended)
-          1. Download the AppImage below
-          2. Make it executable: `chmod +x SubMiner.AppImage`
-          3. Run: `./SubMiner.AppImage`
-
-          ### macOS
-          1. Download `subminer-*.dmg`
-          2. Open the DMG and drag `SubMiner.app` into `/Applications`
-          3. If needed, use the ZIP artifact as an alternative
-
-          ### Manual Installation
-          See the [README](https://github.com/${{ github.repository }}#installation) for manual installation instructions.
-
-          ### Optional Assets (config example + mpv plugin + rofi theme)
-          1. Download `subminer-assets.tar.gz`
-          2. Extract and copy `config.example.jsonc` to `~/.config/SubMiner/config.jsonc`
-          3. Copy `plugin/subminer/` directory contents to `~/.config/mpv/scripts/`
-          4. Copy `plugin/subminer.conf` to `~/.config/mpv/script-opts/`
-          5. Copy `assets/themes/subminer.rasi` to:
-             - Linux: `~/.local/share/SubMiner/themes/subminer.rasi`
-             - macOS: `~/Library/Application Support/SubMiner/themes/subminer.rasi`
-
-          Note: the `subminer` wrapper script uses Bun (`#!/usr/bin/env bun`), so `bun` must be installed and on `PATH`.
-          EOF
-
           if gh release view "${{ steps.version.outputs.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 }}" \
+              --draft=false \
               --title "${{ steps.version.outputs.VERSION }}" \
-              --notes-file release-body.md
+              --notes-file release/release-notes.md
           else
             gh release create "${{ steps.version.outputs.VERSION }}" \
               --title "${{ steps.version.outputs.VERSION }}" \
-              --notes-file release-body.md
+              --notes-file release/release-notes.md
           fi
 
           shopt -s nullglob
           artifacts=(
             release/*.AppImage
             release/*.dmg
+            release/*.exe
             release/*.zip
             release/*.tar.gz
             release/SHA256SUMS.txt
@@ -365,3 +401,130 @@ jobs:
           for asset in "${artifacts[@]}"; do
             gh release upload "${{ steps.version.outputs.VERSION }}" "$asset" --clobber
           done
+
+  aur-publish:
+    needs: [release]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Get version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+
+      - name: Check AUR publish prerequisites
+        id: aur_prereqs
+        env:
+          AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
+        run: |
+          set -euo pipefail
+          if [ -z "${AUR_SSH_PRIVATE_KEY}" ]; then
+            echo "::warning::Missing AUR_SSH_PRIVATE_KEY; skipping automated AUR publish."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "skip=false" >> "$GITHUB_OUTPUT"
+
+      - name: Configure SSH for AUR
+        id: aur_ssh
+        if: steps.aur_prereqs.outputs.skip != 'true'
+        env:
+          AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
+        run: |
+          set -euo pipefail
+          if install -dm700 ~/.ssh \
+            && printf '%s\n' "${AUR_SSH_PRIVATE_KEY}" > ~/.ssh/aur \
+            && chmod 600 ~/.ssh/aur \
+            && ssh-keyscan aur.archlinux.org >> ~/.ssh/known_hosts \
+            && chmod 644 ~/.ssh/known_hosts; then
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "::warning::Unable to configure SSH for AUR; skipping automated AUR publish."
+          echo "skip=true" >> "$GITHUB_OUTPUT"
+
+      - name: Clone AUR repo
+        id: aur_clone
+        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true'
+        env:
+          GIT_SSH_COMMAND: ssh -i ~/.ssh/aur -o IdentitiesOnly=yes
+        run: |
+          set -euo pipefail
+          attempts=3
+          for attempt in $(seq 1 "$attempts"); do
+            if git clone ssh://aur@aur.archlinux.org/subminer-bin.git aur-subminer-bin; then
+              echo "skip=false" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+
+            rm -rf aur-subminer-bin
+
+            if [ "$attempt" -lt "$attempts" ]; then
+              sleep $((attempt * 15))
+            fi
+          done
+
+          echo "::warning::Unable to clone subminer-bin from AUR after ${attempts} attempts; skipping automated AUR publish."
+          echo "skip=true" >> "$GITHUB_OUTPUT"
+
+      - name: Download release assets for AUR
+        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 }}
+        run: |
+          set -euo pipefail
+          version="${{ steps.version.outputs.VERSION }}"
+          install -dm755 .tmp/aur-release-assets
+          gh release download "$version" \
+            --dir .tmp/aur-release-assets \
+            --pattern "SubMiner-${version#v}.AppImage" \
+            --pattern "subminer" \
+            --pattern "subminer-assets.tar.gz"
+
+      - name: Update AUR packaging metadata
+        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
+        run: |
+          set -euo pipefail
+          version_no_v="${{ steps.version.outputs.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 }}" \
+            --appimage ".tmp/aur-release-assets/SubMiner-${version_no_v}.AppImage" \
+            --wrapper ".tmp/aur-release-assets/subminer" \
+            --assets ".tmp/aur-release-assets/subminer-assets.tar.gz"
+
+      - name: Commit and push AUR update
+        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
+        working-directory: aur-subminer-bin
+        env:
+          GIT_SSH_COMMAND: ssh -i ~/.ssh/aur -o IdentitiesOnly=yes
+        run: |
+          set -euo pipefail
+          if git diff --quiet -- PKGBUILD .SRCINFO; then
+            echo "AUR packaging already up to date."
+            exit 0
+          fi
+          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 }}"
+
+          attempts=3
+          for attempt in $(seq 1 "$attempts"); do
+            if git push origin HEAD:master; then
+              exit 0
+            fi
+
+            if [ "$attempt" -lt "$attempts" ]; then
+              sleep $((attempt * 15))
+            fi
+          done
+
+          echo "::warning::Unable to push the AUR update after ${attempts} attempts; GitHub release is published, but subminer-bin needs manual follow-up."

.gitignore

@@ -1,11 +1,17 @@
 # Dependencies
 node_modules/
 
+# Superpowers brainstorming
+.superpowers/
+
 # Electron build output
 out/
 dist/
-release/
+release/*
+!release/
+!release/release-notes.md
 build/yomitan/
+coverage/
 
 # Launcher build artifact (produced by make build-launcher)
 /subminer
@@ -22,9 +28,7 @@ Thumbs.db
 .idea/
 *.swp
 *.swo
-**/CLAUDE.md
 environment.toml
-**/CLAUDE.md
 .env
 .vscode/*
 
@@ -35,6 +39,21 @@ docs/.vitepress/cache/
 docs/.vitepress/dist/
 tests/*
 .worktrees/
+.tmp/
 .codex/*
 .agents/*
-docs/*
+!.agents/skills/
+.agents/skills/*
+!.agents/skills/subminer-change-verification/
+!.agents/skills/subminer-scrum-master/
+.agents/skills/subminer-change-verification/*
+!.agents/skills/subminer-change-verification/SKILL.md
+!.agents/skills/subminer-change-verification/scripts/
+.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-scrum-master/*
+!.agents/skills/subminer-scrum-master/SKILL.md
+favicon.png
+.claude/*
+!stats/public/favicon.png

AGENTS.md

@@ -1,29 +1,66 @@
+# AGENTS.MD
 
-<!-- BACKLOG.MD MCP GUIDELINES START -->
+## Internal Docs
 
-<CRITICAL_INSTRUCTION>
+Start here, then leave this file.
 
-## BACKLOG WORKFLOW INSTRUCTIONS
+- Internal system of record: [`docs/README.md`](./docs/README.md)
+- Architecture map: [`docs/architecture/README.md`](./docs/architecture/README.md)
+- Workflow map: [`docs/workflow/README.md`](./docs/workflow/README.md)
+- Verification lanes: [`docs/workflow/verification.md`](./docs/workflow/verification.md)
+- Knowledge-base rules: [`docs/knowledge-base/README.md`](./docs/knowledge-base/README.md)
+- Release guide: [`docs/RELEASING.md`](./docs/RELEASING.md)
 
-This project uses Backlog.md MCP for all task and project management activities.
+`docs-site/` is user-facing. Do not treat it as the canonical internal source of truth.
 
-**CRITICAL GUIDANCE**
+## Quick Start
 
-- If your client supports MCP resources, read `backlog://workflow/overview` to understand when and how to use Backlog for this project.
-- If your client only supports tools or the above request fails, call `backlog.get_workflow_overview()` tool to load the tool-oriented overview (it lists the matching guide tools).
+- Init workspace: `git submodule update --init --recursive`
+- Install deps: `make deps` or `bun install` plus `(cd vendor/texthooker-ui && bun install --frozen-lockfile)`
+- Fast dev loop: `make dev-watch`
+- Full local run: `bun run dev`
+- Verbose Electron debug: `electron . --start --dev --log-level debug`
 
-- **First time working here?** Read the overview resource IMMEDIATELY to learn the workflow
-- **Already familiar?** You should have the overview cached ("## Backlog.md Overview (MCP)")
-- **When to read it**: BEFORE creating tasks, or when you're unsure whether to track work
+## Build / Test
 
-These guides cover:
-- Decision framework for when to create tasks
-- Search-first workflow to avoid duplicates
-- Links to detailed guides for task creation, execution, and finalization
-- MCP tools reference
+- Runtime/package manager: Bun (`packageManager: bun@1.3.5`)
+- Default handoff gate:
+  `bun run typecheck`
+  `bun run test:fast`
+  `bun run test:env`
+  `bun run build`
+  `bun run test:smoke:dist`
+- If `docs-site/` changed, also run:
+  `bun run docs:test`
+  `bun run docs:build`
+- Prefer `make pretty` and `bun run format:check:src`
 
-You MUST read the overview resource to understand the complete workflow. The information is NOT summarized here.
+## Change-Specific Checks
 
-</CRITICAL_INSTRUCTION>
+- Config/schema/defaults: `bun run test:config`; if template/defaults changed, `bun run generate:config-example`
+- Launcher/plugin: `bun run test:launcher` or `bun run test:env`
+- Runtime-compat / dist-sensitive: `bun run test:runtime:compat`
+- Docs-only: `bun run docs:test`, then `bun run docs:build`
 
-<!-- BACKLOG.MD MCP GUIDELINES END -->
+## Sensitive Files
+
+- Launcher source of truth: `launcher/*.ts`
+- Generated launcher artifact: `dist/launcher/subminer`; never hand-edit it
+- Repo-root `./subminer` is stale; do not revive it
+- `bun run build` rebuilds bundled Yomitan from `vendor/subminer-yomitan`
+- Do not change signing/packaging identifiers unless the task explicitly requires it
+
+## Release / PR Notes
+
+- User-visible PRs need one fragment in `changes/*.md`
+- 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 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
+- Swift: use workspace helper/daemon; validate `swift build` + tests

CHANGELOG.md

@@ -0,0 +1,515 @@
+# Changelog
+
+## v0.14.0 (2026-05-12)
+
+### Added
+
+- **Character Dictionary:** Added AniList-based character dictionary selection for resolving title mismatches — open it in-app with the new `Ctrl+Alt+A` shortcut or from the CLI with `subminer dictionary --candidates` / `--select`. Series-scoped overrides replace stale entries in the merged dictionary.
+- **Primary Subtitle Bar:** Added a `V` shortcut and mpv plugin binding to toggle the primary subtitle bar without affecting mpv's native subtitle visibility.
+- **Texthooker:** Added `subminer texthooker -o` and a tray menu item to open the local texthooker page in the default browser.
+
+### Changed
+
+- **mpv Plugin Setup:** SubMiner-managed launches now automatically inject the bundled mpv plugin when no global plugin is installed. The legacy plugin removal prompt appears before mpv starts so users can trash the old global plugin and relaunch immediately.
+- **Tray Menu:** Replaced the "Open Overlay" menu item with "Open Help", which opens the session help modal.
+- **Stats Exclusions:** Vocabulary exclusions now persist in the immersion database and import any existing browser-local exclusions on first load.
+- **Config Example:** The generated example config now lists every built-in default keybinding, with regression coverage ensuring they compile, dispatch in the overlay, and register through the mpv plugin.
+- **Default Startup Options:** Texthooker startup and subtitle/annotation WebSocket servers are now disabled by default. Fresh installs also get updated primary subtitle style defaults: a Japanese font stack, transparent subtitle backgrounds, stronger text shadows, and teal N4/fourth-band coloring.
+
+### Fixed
+
+- **JLPT Underlines:** Restored persistent JLPT underlines on subtitle tokens; they now keep their JLPT color after dictionary lookups and when a token also carries a known-word or frequency annotation color.
+- **Hyprland Fullscreen Overlay:** Fixed fullscreen transitions on Hyprland so mpv fullscreen changes refresh overlay geometry, reassert topmost stacking, and keep hover-pause working through resize/toggle cycles. The overlay now aligns exactly with the mpv window, disables floating-window decoration on exact placement, and no longer pins across workspaces.
+- **macOS Overlay:** Kept the overlay visible and interactive during transient tracker refreshes and while mpv is the active tracked window. Fixed z-order so the overlay stays above mpv but behind other foreground windows.
+- **Subtitle Annotation Colors:** Fixed annotated token colors so `subtitleStyle` typography is preserved and higher-priority known-word and frequency colors correctly take precedence over JLPT colors. Added a subtle brightness lift for hover states so transparent hover backgrounds still show a visible affordance. Hid the browser focus ring on the overlay surface so focused overlays no longer show a viewport border.
+- **Grammar and Particle Annotation Filters:** Suppressed annotation styling (N+1, JLPT, frequency, name) for grammar-only tokens including auxiliary inflection fragments like `れる`/`れた`, polite copula tails like `です`/`ですよ`, negative copula phrases like `じゃないですか`, and standalone particles like `に`; lexical forms like `くれる` remain eligible.
+- **Interjection and Existence Verb Filters:** Suppressed annotations for ハァ-style interjections and `ある`/`有る` existence verbs; known-word highlighting still applies for `ある`.
+- **Known-Word Compound Tokens:** Preserved Yomitan compound token boundaries for known-word highlighting so known component words no longer color a larger unknown compound green.
+- **Kana Token Annotations:** Stopped kana-only tokens from being selected as N+1 targets or receiving N+1, JLPT, or frequency annotation metadata.
+- **Subtitle Bar Modes:** Changed `v` to cycle the primary subtitle bar through visible, hover, and hidden modes with OSD feedback. A new `subtitleStyle.primaryDefaultMode` config option sets the startup default independently of secondary subtitles.
+- **Subtitle Keybindings:** Fixed the default replay/next subtitle keybindings by moving session help to `Ctrl/Cmd+/`, freeing `Ctrl+Shift+H` and `Ctrl+Shift+L` for subtitle playback controls. The mpv plugin now registers shifted letter chords correctly so `Ctrl+Shift+L` reaches play-next-subtitle; play-next also starts playback from a paused state before re-pausing at subtitle end.
+- **Yomitan Popup Precedence:** Fixed keyboard-only Yomitan popup controls so popup shortcuts take precedence over overlay keybindings like `j`.
+- **Subtitle Prefetch:** Kept annotation prefetch running after immediate cache-hit renders so upcoming subtitle colors stay ready.
+- **Frequency Highlighting:** Fixed frequency highlighting for ordinal prefix-noun tokens like `第二` so JPDB ranks are preserved in subtitle annotations.
+- **Known-Word Refresh After Mining:** Refreshed the current subtitle after successful card mining so newly known words recolor immediately.
+- **Linux Multi-Line Copy:** Fixed multi-line subtitle copy on Linux so the overlay handles the follow-up digit selection locally, eliminating the timeout.
+- **mpv Crash Notifications:** Stopped mpv from owning long-running SubMiner subprocesses during shutdown, preventing desktop crash notifications when closing video.
+- **mpv Buffering Reload:** Kept the overlay alive across same-media reloads during buffering, avoiding duplicate startup gates and AniSkip lookups.
+- **mpv Playlist Navigation:** Playlist navigation now reuses the running overlay without repeating the pause-until-ready warmup gate.
+- **Anki Manual Updates:** Manual clipboard subtitle updates now replace sentence audio and media even when audio overwrite is disabled, while preserving existing word audio.
+- **AniList Progress Tracking:** Fixed post-watch progress to check on mpv time-position updates using the fresh mpv position, wired manual mark-watched to force a progress sync, and filled missing episode metadata from the filename parser. Prevented duplicate post-watch writes during concurrent checks and preserved manual watched marks when sync fails.
+- **AniList Setup:** Prevented config reload from opening the setup window during playback when token storage is unavailable; stopped setup from reporting success when encrypted token persistence fails.
+- **AniList Linux Keyring:** Retried keyring availability after transient GNOME libsecret startup failures so stored tokens load once the keyring becomes available.
+- **Stats Daemon:** Fixed stats background mode to route through the isolated stats daemon and deferred in-app stats startup when a daemon is already running, so video launches no longer fail when the stats port is in use.
+- **Stats Session Detail:** Fixed recent session detail pages showing "Media not found" before lifetime media summaries are available.
+- **Hover Background Config:** Accepted `subtitleStyle.hoverBackground` as an alias for `subtitleStyle.hoverTokenBackgroundColor` so setting it to `transparent` removes hover token backgrounds.
+- **Managed Playback Exit:** Launcher-managed playback now exits the background SubMiner app when the video closes; explicit background launches remain persistent.
+- **Multi-Mine Shortcuts:** Multi-line subtitle mining now accepts follow-up number-row digits even when the original shortcut modifiers are still held.
+- **Jellyfin Setup:** Improved setup with recent server selection and inline authentication feedback; added a tray "Jellyfin Discovery" toggle for runtime-only cast discovery.
+- **Subtitle POS Filtering:** Used Yomitan `wordClasses` metadata for subtitle part-of-speech filtering and backfilled blank MeCab POS detail fields during parser enrichment.
+
+### Docs
+
+- Improved the docs homepage with canonical URLs and a cleaner sitemap for better search engine indexing.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+
+- Replaced the changelog renderer with an AI polish pass that merges related fragments and writes user-facing release notes. `CHANGELOG.md` keeps internal items in a collapsed `<details>` block; GitHub release notes omit them entirely.
+- Release CI no longer auto-builds pending `changes/*.md` fragments on tag. Tagging now fails fast if fragments remain — run `bun run changelog:build` (requires the `claude` CLI) and commit before tagging.
+
+</details>
+
+## v0.12.0 (2026-04-11)
+
+### Changed
+
+- Overlay: Added configurable overlay shortcuts for session help, controller select, and controller debug actions.
+- Overlay: Added mpv/plugin and CLI routing for session help, controller utilities, and subtitle sidebar toggling through the shared session-action path.
+- Overlay: Improved dedicated overlay modal retry and focus handling for runtime options, Jimaku, session help, controller tools, and the playlist browser.
+- Overlay: Fixed controller configuration and controller debug shortcut opens so configured bindings bring up their modals again instead of tripping renderer recovery.
+- Stats: Sessions are rolled up per episode within each day, with a bulk delete that wipes every session in the group.
+- Stats: Trends add a 365-day range next to the existing 7d/30d/90d/all options.
+- Stats: Library detail view gets a delete-episode action that removes the video and all its sessions.
+- Stats: Vocabulary Top 50 tightens the word/reading column so katakana entries no longer push the scores off screen.
+- Stats: Episode detail hides card events whose Anki notes have been deleted, instead of showing phantom mining activity.
+- Stats: Trend and watch-time charts share a unified theme with horizontal gridlines and larger ticks for legibility.
+- Stats: Overview, Library, Trends, Sessions, and Vocabulary now use generic "title" wording so YouTube videos and anime live comfortably side by side in the dashboard.
+- Stats: Session timeline no longer plots seek-forward/seek-backward markers — they were too noisy on sessions with lots of rewinds.
+- Stats: Replaced the "Library — Per Day" section on the Stats → Trends page with a "Library — Summary" section. The new section shows a top-10 watch-time leaderboard chart and a sortable per-title table (watch time, videos, sessions, cards, words, lookups, lookups/100w, date range), all scoped to the current date range selector.
+
+### Fixed
+
+- Overlay: Fixed overlay drag-and-drop routing so dropping external subtitle files like `.ass` onto mpv still loads them when the overlay is visible.
+- Overlay: Addressed the latest CodeRabbit follow-ups on PR #49, including generation-scoped Lua session binding names, stricter session command validation, session-help shortcut visibility, the numeric-selection key guard, stats-overlay startup classification, and safer session-binding persistence.
+- Overlay: Addressed the latest CodeRabbit follow-ups on the Windows overlay flow, including exact mpv target resolution, lower-overlay helper arguments, Win32 failure detection, and overlay cleanup on tracker loss.
+- Overlay: Fixed Windows overlay z-order so the visible subtitle overlay stops staying above unrelated apps after mpv loses focus.
+- Overlay: Fixed Windows overlay tracking to use native window polling and owner/z-order binding, which keeps the subtitle overlay aligned to the active mpv window more reliably.
+- Overlay: Fixed Windows overlay hide/restore behavior so minimizing mpv immediately hides the overlay and restoring mpv brings it back on top of the mpv window without requiring a click.
+- Overlay: Fixed stats overlay layering so the in-player stats page now stays above mpv and the subtitle overlay while it is open.
+- Overlay: Fixed Windows subtitle overlay stability so transient tracker misses and restore events keep the current subtitle visible instead of waiting for the next subtitle line.
+- Overlay: Fixed Windows focus handoff from the interactive subtitle overlay back to mpv so the overlay no longer drops behind mpv and briefly disappears.
+- Overlay: Fixed Windows visible-overlay startup so it no longer briefly opens as an interactive or opaque surface before the tracked transparent overlay state settles.
+- Overlay: Fixed spurious auto-pause after overlay visibility recovery and window resize so the overlay no longer pauses mpv until the pointer genuinely re-enters the subtitle area.
+- Overlay: Fixed Windows secondary subtitle hover mode so the expanded hover hit area no longer blocks the native minimize, maximize, and close buttons.
+- Overlay: Fixed Windows Yomitan popup focus loss after closing nested lookups so the original popup stays interactive instead of falling through to mpv.
+- Stats: Fixed immersion-tracker timestamp handling under Bun/libsql so library rows, session timelines, and lifetime summaries keep real wall-clock millisecond values instead of truncating to invalid negative timestamps.
+- Mpv Plugin: Fixed the mpv Lua plugin so hover and environment modules no longer use the `goto continue` pattern that can fail to parse on some user Lua runtimes.
+
+### Internal
+
+- Release: Added a dedicated beta/rc prerelease GitHub Actions workflow that publishes GitHub prereleases without consuming pending changelog fragments or updating AUR.
+- Release: Added prerelease note generation so beta and release-candidate tags can reuse the current pending `changes/*.md` fragments while leaving stable changelog publication for the final release cut.
+
+## v0.11.2 (2026-04-07)
+
+### Changed
+
+- Launcher: Replaced the launcher-only fullscreen toggle with `mpv.launchMode` so SubMiner-managed mpv playback can start in normal, maximized, or fullscreen mode.
+
+### Fixed
+
+- Launcher: Fixed launcher-managed mpv spawning to force an explicit X11 GPU path when Wayland trackers are unavailable.
+- Launcher: Local playback now promotes a single unlabeled external subtitle sidecar to the primary slot instead of leaving mpv's embedded English auto-selection in place.
+- Release: Fixed Linux AppImage startup packaging so Chromium child relaunches can resolve the bundled `libffmpeg.so` instead of crash-looping on startup.
+
+## v0.11.1 (2026-04-04)
+
+### Fixed
+
+- Release: Linux packaged builds now expose the canonical `SubMiner` app identity to Electron's startup metadata so native Wayland compositors stop reporting the window class/app-id as lowercase `subminer`.
+- Linux: Linux now restores the runtime options, Jimaku, and Subsync shortcuts after the Electron 39 regression by routing those actions through the overlay's mpv/IPC shortcut path.
+
+## v0.11.0 (2026-04-03)
+
+### Added
+
+- Overlay: Added a playlist browser overlay modal for browsing sibling video files and the live mpv queue during playback.
+- Overlay: Added the default `Ctrl+Alt+P` keybinding to open the playlist browser and manage queue order without leaving playback.
+
+### Changed
+
+- Setup: Made mpv plugin installation mandatory in the first-run setup flow, removed the skip path, and kept Finish disabled until the plugin is installed.
+- Setup: Clarified that the mpv plugin requirement applies to setup on every platform, while the optional `SubMiner mpv` shortcut remains the recommended Windows playback entry point.
+- Launcher: Streamlined Windows setup and config by making the `SubMiner mpv` shortcut self-contained and keeping `mpv.executablePath` as the simple fallback when `mpv.exe` is not on `PATH`.
+- Overlay: Changed fresh-install default config to keep texthooker and stats from auto-opening browser tabs.
+- Overlay: Changed fresh-install default config to enable AnkiConnect, Discord Rich Presence, subtitle-sidebar, and Yomitan-popup auto-pause by default, while disabling controller input by default.
+
+### Fixed
+
+- Main: Resolve the YouTube playback socket path lazily so startup honors CLI and config overrides.
+- Main: Add regression coverage for the lazy socket-path lookup during Windows mpv startup.
+- Main: Keep integrated `--start --texthooker` launches on the full app-ready startup path so the texthooker page and websocket servers start together during normal playback startup.
+- Main: Stop the mpv/plugin auto-start flow from spawning a separate standalone texthooker helper during normal `subminer <video>` launches.
+- Overlay: Keep tracked macOS visible overlays click-through by default so subtitle sidebar passthrough works immediately without requiring a subtitle hover cycle first.
+- Overlay: Add regression coverage for the macOS visible-overlay passthrough default.
+- Anilist: Stop AniList post-watch from sending a second progress update when the current episode was already satisfied by a ready retry item in the same watch-completion pass.
+- Anilist: Add regression coverage for the retry-queue plus live-update duplicate path.
+- Overlay: Fixed Kiku duplicate grouping to reuse duplicate note IDs from both generic sentence-card creation and Yomitan popup mining instead of running extra duplicate scans after add.
+- Overlay: Fixed the Yomitan popup mining flow to add cards in the background while keeping the stock popup progress feedback, then pause playback and close the lookup popup before the Kiku merge modal opens.
+- Overlay: Fixed configured subtitle-jump keybindings so backward and forward subtitle seeks keep playback paused when invoked from a paused state.
+- Launcher: Fixed the Windows `SubMiner mpv` shortcut and `SubMiner.exe --launch-mpv` flow to launch mpv with SubMiner's required default args directly instead of requiring an `mpv.conf` profile named `subminer`.
+- Launcher: Clarified the Windows install and usage docs so the shortcut path is documented as self-contained, while the optional `subminer` mpv profile remains available for manual mpv launches.
+- Launcher: Hardened the first-run setup blocker copy and stale custom-scheme handling so setup messages stay aligned with config, plugin, and dictionary readiness.
+- Launcher: Fixed the Windows `SubMiner mpv` shortcut idle launch so loading a video after opening the shortcut keeps mpv in the expected SubMiner-managed session, auto-starts the overlay, and re-arms subtitle auto-selection for the newly opened file.
+- Launcher: Removed the redundant `.` subtitle search path from the Windows shortcut launch args and deduped repeated subtitle source tracks in the manual sync picker so duplicate external subtitle entries no longer appear from the shortcut path.
+- Playback: Fixed managed local playback so duplicate startup-ready retries no longer unpause media after a later manual pause on the same file.
+- Playback: Fixed managed local subtitle auto-selection so local files reuse configured primary and secondary subtitle language priorities instead of staying on mpv's initial `sid=auto` guess.
+- Launcher: Added a blank-by-default `mpv.executablePath` override for Windows playback so users can point SubMiner at `mpv.exe` when it is not on `PATH`.
+- Launcher: Kept the Windows shortcut and `--launch-mpv` flow simple by preserving PATH auto-discovery as the default and exposing the override in first-run setup.
+- Launcher: Added `windows` as a recognized launcher backend option and auto-detection target on Windows.
+- Launcher: Honored `SUBMINER_YTDLP_BIN` consistently across YouTube playback URL resolution, track probing, subtitle downloads, and metadata probing.
+- Launcher: Kept the first-run setup window from navigating away on unexpected URLs.
+- Launcher: Made Windows mpv honor an explicitly configured executable path instead of silently falling back to PATH.
+- Launcher: Hardened `--launch-mpv` parsing and Windows binary resolution so valueless flags do not swallow media targets and symlinked launcher installs do not short-circuit PATH lookup.
+- Launcher: Fixed first-run setup blocking playback on macOS when the SubMiner mpv plugin was already installed at the canonical `~/.config/mpv` path.
+- Launcher: Fixed setup gating so stale cancelled setup state no longer prevents playback when the canonical mpv plugin entrypoint already exists.
+- Playback: Prevented stale async playlist-browser subtitle rearm callbacks from overriding newer subtitle selections during rapid file changes.
+
+### Docs
+
+- Docs Site: Added a dedicated Subtitle Sidebar guide and linked it from the homepage and configuration docs.
+- Docs Site: Linked Jimaku integration from the homepage to its dedicated docs page.
+- Docs Site: Refreshed docs-site theme tokens and hover/selection styling for the updated pages.
+
+### Internal
+
+- Release: Retried AUR clone and push operations in the tagged release workflow.
+- Release: Kept GitHub Releases green when AUR publish flakes and needs manual follow-up.
+- Release: Updated Electron to 39.8.6 and pinned patched transitive build dependencies to clear the reported high-severity audit findings.
+
+## v0.10.0 (2026-03-29)
+
+### Changed
+
+- Integrations: Replaced the deprecated Discord Rich Presence wrapper with the maintained `@xhayper/discord-rpc` package.
+
+### Fixed
+
+- Stats: Fixed stats startup so the immersion tracker can run when `Bun.serve` is unavailable.
+- Stats: Stats server now falls back to a Node `http` listener in Electron/runtime paths that do not expose Bun.
+- Overlay: Fixed the macOS visible-overlay toggle path so manual hides stay hidden and the plugin uses the explicit visible-overlay toggle command.
+- Subtitle Sidebar: Restored macOS mpv passthrough while the overlay subtitle sidebar is open so clicks outside the sidebar can refocus mpv and keep native keybindings working.
+
+### Internal
+
+- Release: Added a maintained source coverage lane that shards Bun coverage one test file at a time and merges LCOV output into `coverage/test-src/lcov.info`.
+- Release: CI and release quality-gate now upload the merged source-lane LCOV artifact for inspection.
+- Runtime: Extracted remaining inline runtime logic from `src/main.ts` into dedicated runtime modules and composer helpers.
+- Runtime: Added focused regression tests for the extracted runtime/composer boundaries.
+- Runtime: Updated task tracking notes to mark TASK-238.6 complete and confirm follow-on boot-phase split can be deferred.
+- Runtime: Split `src/main.ts` boot wiring into dedicated `src/main/boot/services.ts`, `src/main/boot/runtimes.ts`, and `src/main/boot/handlers.ts` modules.
+- Runtime: Added focused tests for the new boot-phase seams and kept the startup/typecheck/build verification lanes green.
+- Runtime: Updated internal architecture/task docs to record the boot-phase split and new ownership boundary.
+
+## v0.9.3 (2026-03-25)
+
+### Changed
+
+- Launcher: Moved YouTube primary subtitle language defaults to `youtube.primarySubLanguages`.
+- Launcher: Removed the placeholder YouTube subtitle retime step and now uses downloaded primary subtitle tracks directly, so there is no fake path rewrite before playback/sidebar loading.
+- YouTube: Removed the `src/core/services/youtube/retime` helper and its tests after retiring the internal retime strategy.
+- Docs: Clarified optional `alass` / `ffsubsync` subtitle-sync requirements and setup steps, including fallback behavior when sync tools are absent.
+- Launcher: Removed the old `youtubeSubgen.primarySubLanguages` config path from the generated config and docs.
+
+## v0.9.2 (2026-03-25)
+
+### Fixed
+
+- Overlay: Fixed overlay pointer tracking so Windows click-through toggles immediately when the cursor enters or leaves subtitle regions, without waiting for a later hover resync.
+- Overlay: Fixed Windows overlay window tracking on scaled displays by converting native tracked window bounds to Electron DIP coordinates before applying overlay bounds.
+- Launcher: Fixed Windows direct `--youtube-play` startup so MPV boots reliably, stays paused until the app-owned subtitle flow is ready, and reuses an already-running SubMiner instance when available.
+- Launcher: Fixed standalone Windows `--youtube-play` sessions so closing MPV fully exits SubMiner instead of leaving hidden overlay windows or a background process behind.
+- Overlay: Fixed `subminer <youtube-url>` on Linux so the YouTube playback flow waits for Yomitan to load before creating the overlay window, avoiding the broken lookup popup state that previously required a manual overlay refresh.
+
+## v0.9.1 (2026-03-24)
+
+### Changed
+
+- Release: Reduced packaged release size by excluding duplicate `extraResources` payload and pruning docs, tests, sourcemaps, and other source-only files from Electron bundles.
+
+### Fixed
+
+- Overlay: Restored controller navigation and lookup/mining controls while the subtitle sidebar is open, while keeping true modal dialogs blocking controller actions.
+- Tokenizer: Fixed subtitle annotation clearing so explanatory contrast endings like `んですけど` are excluded consistently across the shared tokenizer filter and annotation stage.
+
+## v0.9.0 (2026-03-23)
+
+### Added
+
+- Docs: Added a new WebSocket / Texthooker API and integration guide covering WebSocket payloads, custom client patterns, mpv plugin automation, and webhook-style relay examples. Linked from configuration and mining workflow docs for easier discovery.
+
+### Changed
+
+- Launcher: Added an app-owned YouTube subtitle flow that pauses mpv, uses absPlayer-style YouTube timedtext parsing/conversion to download subtitle tracks, and injects them as external files before playback resumes.
+- Launcher: Changed YouTube subtitle startup to auto-load the best-available primary and secondary subtitle tracks at launch instead of forcing the picker modal first. Secondary subtitle failures no longer block playback resume.
+- Launcher: Added `Ctrl+Alt+C` as the default keybinding to manually open the YouTube subtitle picker during active YouTube playback.
+- Launcher: Added yt-dlp metadata probing so YouTube playback and immersion tracking record canonical video title and channel metadata.
+- Launcher: Stopped forcing `--ytdl-raw-options=` before user-provided mpv options so existing YouTube cookie integrations in user `--args` are no longer clobbered.
+- Launcher: Disabled mpv native YouTube subtitle auto-loading for the app-owned flow so injected external subtitle files remain authoritative.
+- Launcher: Added OSD status messages for YouTube playback startup, subtitle acquisition, and subtitle loading so the flow stays visible before and during the picker.
+- Subtitle Sidebar: Added startup-auto-open controls and resume positioning improvements so the sidebar jumps directly to the first resolved active cue.
+- Subtitle Sidebar: Improved subtitle prefetch and embedded overlay passthrough sync so sidebar and overlay subtitle states stay consistent across media transitions.
+- Subtitle Sidebar: Updated scroll handling, embedded layout styling, and active-cue visual behavior.
+- Stats: Stats Library tab now displays YouTube video title, channel name, and channel thumbnail for YouTube media entries, with retry logic to fill in metadata that arrives after initial load.
+
+### Fixed
+
+- Launcher: Fixed Anki media mining for mpv YouTube streams by unwrapping the stream URL so audio and screenshot capture work correctly for YouTube playback sessions.
+- Immersion: Fixed YouTube media path handling in the immersion runtime and tracking so YouTube sessions record correct media references, AniList guessing skips YouTube URLs, and post-watch state transitions do not fire for YouTube media.
+- Launcher: Fixed startup-launched YouTube playback so primary subtitle overlay updates continue after auto-load completes.
+- Launcher: Fixed auto-loaded YouTube primary subtitles so parsed cues appear in the subtitle sidebar without needing a manual picker retry.
+- Launcher: Fixed the YouTube picker to guard against duplicate subtitle submissions and tightened YouTube URL detection so follow-up runtime flows only treat real YouTube hosts as YouTube playback.
+- Launcher: Fixed primary subtitle failure notifications being shown while app-owned YouTube subtitle probing and downloads are still in flight.
+- Launcher: Preserved existing authoritative YouTube subtitle tracks when available; downloaded tracks are used only to fill missing sides, and native mpv secondary subtitle rendering is hidden so the overlay remains the sole secondary display.
+
+## v0.8.0 (2026-03-22)
+
+### Added
+
+- Overlay: Added the subtitle sidebar feature with a new `subtitleSidebar` configuration surface and rendered sidebar modal with cue list rendering, click-to-seek, active-cue highlighting, and embedded layout support.
+- IPC: Added sidebar snapshot plumbing between renderer and main process for overlay/sidebar synchronization.
+
+### Changed
+
+- Config: Added hot-reloadable sidebar options for enablement, layout, visibility, typography, opacity, sizing, and interaction behavior (`autoOpen`, `pauseOnHover`, `autoScroll`, toggle key).
+- Docs: Added full `subtitleSidebar` documentation coverage, including sample config, option table, and toggle shortcut notes.
+- Runtime: Improved subtitle prefetch/rendering flow so sidebar and overlay subtitle states stay in sync across media transitions.
+
+### Fixed
+
+- Overlay: Kept sidebar cue tracking stable across playback transitions and timing edge cases.
+- Overlay: Improved sidebar resume/start behavior to jump directly to the first resolved active cue.
+- Overlay: Stopped stale subtitle refreshes from regressing active-cue and text state.
+
+## v0.7.0 (2026-03-19)
+
+### Added
+
+- Immersion: Added Mine Word, Mine Sentence, and Mine Audio buttons to word detail example lines in the stats dashboard.
+- Immersion: Mine Word creates a full Yomitan card (definition, reading, pitch accent) via the hidden search page bridge, then enriches with sentence audio, screenshot, and metadata extracted from the source video.
+- Immersion: Mine Sentence and Mine Audio create cards directly with appropriate Lapis/Kiku flags, sentence highlighting, and media from the source file.
+- Immersion: Media generation (audio + image/AVIF) runs in parallel and respects all AnkiConnect config options.
+- Immersion: Added word exclusion list to the Vocabulary tab with localStorage persistence and a management modal.
+- Immersion: Fixed truncated readings in the frequency rank table (e.g. お前 now shows おまえ instead of まえ).
+- Immersion: Clicking a bar in the Top Repeated Words chart now opens the word detail panel.
+- Immersion: Secondary subtitle text is now stored alongside primary subtitle lines for use as translation when mining cards from the stats page.
+- Stats: Added `subminer stats -b` to start or reuse a dedicated background stats server without blocking normal SubMiner instances.
+- Stats: Added `subminer stats -s` to stop the dedicated background stats server without closing browser tabs.
+- Stats: Stats server startup now reuses a running background stats daemon instead of trying to bind a second local server in another SubMiner instance.
+- Launcher: Added launcher passthrough for `-a/--args` so mpv receives raw extra launch flags (`--fs`, `--ytdl-format`, custom audio/video settings, etc.) from the `subminer` command.
+- Launcher: Added `subminer stats` to launch the local stats dashboard, force-start the stats server on demand, and open the dashboard in your browser.
+- Launcher: Added `subminer stats cleanup` to backfill vocabulary metadata and prune stale or excluded immersion rows on demand.
+- Launcher: Added `stats.autoOpenBrowser` so browser launch after `subminer stats` can be enabled or disabled explicitly.
+- Immersion: Added a local stats dashboard for immersion tracking with Overview, Anime, Trends, Vocabulary, and Sessions views.
+- Immersion: Added anime progress, episode completion, Anki card links, and occurrence drill-down across the stats dashboard.
+- Immersion: Added richer session timelines with new-word activity, cumulative totals, and pause/seek/card event markers.
+- Immersion: Added completed-episodes and completed-anime totals to the Overview tracking snapshot.
+
+### Changed
+
+- Anki: Changed known-word cache settings to live under `ankiConnect.knownWords` instead of mixing them into `ankiConnect.nPlusOne`.
+- Anki: Kept legacy `ankiConnect.nPlusOne` known-word keys and older `ankiConnect.behavior.nPlusOne*` keys as deprecated compatibility fallbacks.
+- Stats: Added session deletion to the Sessions tab with the same confirmation prompt used by anime episode/session deletes, and removed all associated session rows from the stats database.
+- Immersion: Kept immersion tracking history by default while preserving daily/monthly rollup maintenance.
+- Immersion: Added exact lifetime summary reads for overview/anime/media stats so dashboard totals no longer depend on rescanning raw telemetry.
+- Immersion: Reduced tracker storage overhead by removing duplicated subtitle text from subtitle-line event payloads.
+- Immersion: Deduplicated episode cover-art blobs through a shared blob store and updated cover-art reads/writes to resolve shared images correctly.
+- Immersion: Added indexes for large-history session, telemetry, vocabulary, kanji, and cover-art queries to keep dashboard reads fast as the SQLite database grows.
+- Immersion: Renamed the stats dashboard's Anime tab to Library so the media browser label matches non-anime sources like YouTube and other yt-dlp-backed content.
+- Anilist: Standardized episode completion threshold by introducing `DEFAULT_MIN_WATCH_RATIO` and using it for both local watched state transitions and AniList post-watch progress updates.
+- Anilist: Episode auto-marking now uses the same threshold as AniList (`85%`), removing divergent completion behavior.
+- Overlay: Excluded interjections and sound-effect tokens from subtitle annotation styling so they no longer inherit misleading lexical highlight treatment while still remaining visible and hoverable as plain subtitle tokens.
+- Overlay: Expanded subtitle annotation noise filtering to also strip annotation metadata from standalone grammar-only helper tokens such as particles, auxiliaries, adnominals, common explanatory endings like `んです` / `のだ`, and merged trailing quote-particle forms like `...って` while keeping them tokenized for hover lookup.
+
+### Fixed
+
+- Launcher: Fixed mpv Lua plugin binary auto-detection on Linux to also search `/usr/bin/subminer` and `/usr/local/bin/subminer` (lowercase), matching the conventional Unix wrapper name used by packaged installs such as the AUR package.
+- Stats: Fixed the in-app stats overlay so it connects to the configured `stats.serverPort` instead of falling back to the default port.
+- Overlay: Fixed subtitle frequency tagging for merged lookup-backed tokens like `陰に` by falling back to exact surface-form Yomitan frequencies when the normalized headword lookup misses.
+- Overlay: Fixed MeCab merged-token position mapping across line breaks so merged content-plus-particle tokens like `陰に` keep their matched Yomitan frequency instead of inheriting shifted POS tags.
+- Overlay: Fixed grouped frequency parsing in both Yomitan and fallback frequency-dictionary lookups so display values like `118,121` use the leading rank instead of collapsing the rank and occurrence count into `118121`.
+- Overlay: Fixed frequency-rank ingestion to ignore Yomitan dictionaries explicitly marked `occurrence-based`, so raw occurrence counts are no longer treated as subtitle rank values.
+- Overlay: Fixed inflected headword frequency tagging to prefer ranks from the selected Yomitan `termsFind` popup entry itself, ordered by configured dictionary priority, so forms like `潜み` use primary-dictionary ranks like `4073` before falling back to lower-priority raw lemma metadata such as `CC100`.
+- Overlay: Fixed annotation-stage frequency filtering so exact kanji noun tokens like `者` keep their matched rank even when MeCab labels them `名詞/非自立`, instead of dropping the highlight after scan-time frequency lookup succeeds.
+- Anki: Fixed repeated character-dictionary startup work by scheduling auto-sync only from mpv media-path changes instead of also re-triggering it from connection and media-title events for the same title.
+- Overlay: Fixed macOS fullscreen overlay stability by keeping the passive visible overlay from stealing focus, re-raising the overlay window when reasserting its macOS topmost level, and tolerating one transient macOS tracker/helper miss before hiding the overlay.
+- Overlay: Kept subtitle tokenization warmup one-shot for the lifetime of the app so later fullscreen/media churn on macOS does not replay the startup warmup gate after the first file is ready.
+- Overlay: Added a bounded macOS tracker loss-grace window so fullscreen enter/leave transitions do not immediately hide and reload the overlay when the helper briefly loses the mpv window.
+- Overlay: Skipped subtitle/tokenization refresh invalidation on character-dictionary auto-sync completion when the dictionary was already current, preventing startup flash/reload loops on unchanged media.
+- Stats: Fixed session stats so known-word counts track real known-word occurrences without collapsing subtitle-line gaps.
+- Stats: Fixed session word totals in session-facing stats views to prefer token counts when available, preventing known words from exceeding total words in the session chart.
+- Stats: Fixed the stats Vocabulary tab blank-screen regression caused by a hook-order crash after vocabulary data finished loading.
+- Anki: Fixed card-mine OSD feedback so the final mine result stops the Anki spinner first, then shows a single-line `✓`/`x` status without being overwritten by a later spinner tick.
+- Stats: Removed the misleading `New words` series from expanded session charts; session detail now shows only the real total-word and known-word lines.
+- Stats: Restored the cross-anime word table behavior in stats vocabulary surfaces so shared vocabulary entries no longer disappear or merge incorrectly across related media.
+- Stats: `subminer stats -b` now runs as a standalone background stats daemon instead of reusing the main SubMiner app process, so the overlay app can still be launched separately for normal video watching.
+- Stats: Dashboard word mining still works against the background daemon by using a short-lived hidden helper for the Yomitan add-note flow.
+- Stats: Load full session timelines by default in stats session detail views so long sessions preserve complete telemetry history instead of being truncated by a fixed sample limit.
+- Stats: Replaced heuristic stats word counts with Yomitan token counts, so session, media, anime, and trend subtitle totals now come directly from parsed subtitle tokens.
+- Stats: Updated stats UI labels and lookup-rate copy to refer to tokens instead of words where those counts are shown.
+- Overlay: Reduced repeated `Overlay loading...` popups on macOS when fullscreen tracker flaps briefly hide and recover the visible overlay.
+- Stats: Scaled expanded session-detail known-word charts to the session's actual percentage range so small changes no longer render as a nearly flat line.
+- Jlpt: Reduced JLPT dictionary startup log noise by summarizing duplicate surface-form collisions instead of logging one line per duplicate entry.
+
+## v0.6.5 (2026-03-15)
+
+### Internal
+
+- Release: Seed the AUR checkout with the repo `.SRCINFO` template before rewriting metadata so tagged releases do not depend on prior AUR state.
+
+## v0.6.4 (2026-03-15)
+
+### Internal
+
+- Release: Reworked AUR metadata generation to update `.SRCINFO` directly instead of depending on runner `makepkg`, fixing tagged release publishing for `subminer-bin`.
+
+## v0.6.3 (2026-03-15)
+
+### Changed
+
+- Overlay: Expanded the `Alt+C` controller modal into an inline config/remap flow with preferred-controller saving and per-action learn mode for buttons, triggers, and stick directions.
+
+### Internal
+
+- Workflow: Hardened the `subminer-scrum-master` skill to explicitly answer whether docs updates and changelog fragments are required before handoff.
+- Release: Automate `subminer-bin` AUR package updates from the tagged release workflow.
+
+## v0.6.2 (2026-03-12)
+
+### Changed
+
+- Config: Added `yomitan.externalProfilePath` to reuse another Electron app's Yomitan profile in read-only mode.
+- Config: SubMiner now reuses external Yomitan dictionaries/settings without writing back to that profile.
+- Config: Launcher-managed playback now respects `yomitan.externalProfilePath` and no longer forces first-run setup when external Yomitan is configured.
+- Config: SubMiner now seeds `config.jsonc` even when the default config directory already exists.
+- Config: First-run setup now allows zero internal dictionaries when `yomitan.externalProfilePath` is configured, and falls back to requiring at least one internal dictionary if that external profile is later removed.
+
+## v0.6.1 (2026-03-12)
+
+### Added
+
+- Overlay: Added Chrome Gamepad API controller support for keyboard-only overlay mode, including configurable logical bindings for lookup, mining, popup navigation, Yomitan audio, mpv pause, d-pad fallback navigation, and slower smooth popup scrolling.
+- Overlay: Added `Alt+C` controller selection and `Alt+Shift+C` controller debug modals, with preferred controller persistence and live raw input inspection.
+- Overlay: Added a transient in-overlay controller-detected indicator when a controller is first found.
+- Overlay: Fixed stale keyboard-only token highlight cleanup when keyboard-only mode turns off or the Yomitan popup closes.
+
+### Docs
+
+- Install: Added Arch Linux AUR install docs for `subminer-bin` in the README and installation guide.
+
+### Internal
+
+- Config: add an enforced `verify:config-example` gate so checked-in example config artifacts cannot drift silently
+- Release: Fixed the release workflow token permissions so tagged builds can download `oven-sh/setup-bun` and publish artifacts again.
+
+## v0.5.6 (2026-03-10)
+
+### Fixed
+
+- Dictionary: Persist merged character-dictionary MRU state as soon as a new retained set is built so revisits do not get dropped if later Yomitan import work fails, and skip merged dictionary rebuilds for reorder-only revisits when the retained anime set itself has not changed.
+- Startup: Fixed early Electron startup writing config and user data under a lowercase `~/.config/subminer` path instead of the canonical `~/.config/SubMiner` directory.
+- Overlay: Kept JLPT underline colors stable during Yomitan hover and selection states, even when tokens also use known, N+1, name-match, or frequency styling.
+
+## v0.5.5 (2026-03-09)
+
+### Changed
+
+- Overlay: Added `f` as the default overlay fullscreen toggle and changed the default AniSkip intro-jump key to `Tab`.
+- Dictionary: Aligned AniList character dictionary generation more closely with the upstream reference by preserving duplicate shared names across characters, skipping characters without native Japanese names, restoring richer character info fields, and using upstream-style role mapping plus hint-aware kanji readings.
+- Startup: Ordered startup OSD messages so tokenization loads first, annotation loading appears next if still pending, and character dictionary sync progress waits until annotation loading finishes.
+- Dictionary: Added a visible startup OSD step for merged character-dictionary building so long rebuilds show progress before the later import/upload phase.
+
+### Fixed
+
+- Dictionary: Fixed AniList media guessing for character dictionary auto-sync by using filename-only `guessit` input and preserving multi-part guessit titles instead of truncating them to the first segment.
+- Dictionary: Refresh the current subtitle after character dictionary auto-sync completes so newly imported character names highlight on the active line instead of waiting for the next subtitle change.
+- Dictionary: Show character dictionary auto-sync progress on the mpv OSD without sending desktop notifications.
+- Dictionary: Keep character dictionary auto-sync non-blocking during startup by letting snapshot/build work run in parallel and delaying only the Yomitan import/settings phase until current-media tokenization is already ready.
+- Overlay: Fixed visible overlay keyboard handling so pressing `Tab` still reaches mpv and triggers the default AniSkip skip-intro binding while the overlay has focus.
+- Plugin: Fix Windows mpv plugin binary override lookup so `SUBMINER_BINARY_PATH` still resolves to `SubMiner.exe` when no AppImage override is set.
+
+## v0.5.3 (2026-03-09)
+
+### Changed
+
+- Release: Publish unsigned Windows `.exe` and `.zip` artifacts directly from release CI instead of routing them through SignPath.
+- Release: Added `bun run build:win:unsigned` for explicit local unsigned Windows packaging.
+
+## v0.5.2 (2026-03-09)
+
+### Internal
+
+- Release: Pinned the Windows SignPath submission workflow to an explicit artifact-configuration slug instead of relying on the SignPath project's default configuration.
+
+## v0.5.1 (2026-03-09)
+
+### Changed
+
+- Launcher: Removed the YouTube subtitle generation mode switch so YouTube playback always preloads subtitles before mpv starts.
+
+### Fixed
+
+- Launcher: Hardened YouTube AI subtitle fixing so fenced SRT output and text-only one-cue-per-block responses can still be applied without losing original cue timing.
+- Launcher: Skipped AniSkip lookup during URL playback and YouTube subtitle-preload playback, limiting AniSkip to local file targets where it can actually resolve anime metadata.
+- Launcher: Keep the background SubMiner process running after a launcher-managed mpv session exits so the next mpv instance can reconnect without restarting the app.
+- Launcher: Reuse prior tokenization readiness after the background app is already warm so reopening a video does not pause again waiting for duplicate warmup completion.
+- Windows: Acquire the app single-instance lock earlier so Windows overlay/video launches reuse the running background SubMiner process instead of booting a second full app and repeating startup warmups.
+
+## v0.3.0 (2026-03-05)
+
+- Added keyboard-driven Yomitan navigation and popup controls, including optional auto-pause.
+- Added subtitle/jump keyboard handling fixes for smoother subtitle playback control.
+- Improved Anki/Yomitan reliability with stronger Yomitan proxy syncing and safer extension refresh logic.
+- Added Subsync `replace` option and deterministic retime naming for subtitle workflows.
+- Moved aniskip resolution to launcher-script options for better control.
+- Tuned tokenizer frequency highlighting filters for improved term visibility.
+- Added release build quality-of-life for CLI publish (`gh`-based clobber upload).
+- Removed docs Plausible integration and cleaned associated tracker settings.
+
+## v0.2.3 (2026-03-02)
+
+- Added performance and tokenization optimizations (faster warmup, persistent MeCab usage, reduced enrichment lookups).
+- Added subtitle controls for no-jump delay shifts.
+- Improved subtitle highlight logic with priority and reliability fixes.
+- Fixed plugin loading behavior to keep OSD visible during startup.
+- Fixed Jellyfin remote resume behavior and improved autoplay/tokenization interaction.
+- Updated startup flow to load dictionaries asynchronously and unblock first tokenization sooner.
+
+## v0.2.2 (2026-03-01)
+
+- Improved subtitle highlighting reliability for frequency modes.
+- Fixed Jellyfin misc info formatting cleanup.
+- Version bump maintenance for 0.2.2.
+
+## v0.2.1 (2026-03-01)
+
+- Delivered Jellyfin and Subsync fixes from release patch cycle.
+- Version bump maintenance for 0.2.1.
+
+## v0.2.0 (2026-03-01)
+
+- Added task-related release work for the overlay 2.0 cycle.
+- Introduced Overlay 2.0.
+- Improved release automation reliability.
+
+## v0.1.2 (2026-02-24)
+
+- Added encrypted AniList token handling and default GNOME keyring support.
+- Added launcher passthrough for password-store flows (Jellyfin path).
+- Updated docs for auth and integration behavior.
+- Version bump maintenance for 0.1.2.
+
+## v0.1.1 (2026-02-23)
+
+- Fixed overlay modal focus handling (`grab input`) behavior.
+- Version bump maintenance for 0.1.1.
+
+## v0.1.0 (2026-02-23)
+
+- Bootstrapped Electron runtime, services, and composition model.
+- Added runtime asset packaging and dependency vendoring.
+- Added project docs baseline, setup guides, architecture notes, and submodule/runtime assets.
+- Added CI release job dependency ordering fixes before launcher build.

CLAUDE.md

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

Makefile

@@ -1,10 +1,9 @@
-.PHONY: help deps build build-launcher install build-linux build-macos build-macos-unsigned clean install-linux install-macos install-plugin uninstall uninstall-linux uninstall-macos print-dirs pretty ensure-bun generate-config generate-example-config dev-start dev-start-macos dev-watch dev-watch-macos dev-toggle dev-stop
+.PHONY: help deps build build-launcher install build-linux build-macos build-macos-unsigned clean install-linux install-macos install-windows uninstall uninstall-linux uninstall-macos uninstall-windows print-dirs pretty lint ensure-bun generate-config generate-example-config dev-start dev-start-macos dev-watch dev-watch-macos dev-toggle dev-stop
 
 APP_NAME := subminer
 THEME_SOURCE := assets/themes/subminer.rasi
 LAUNCHER_OUT := dist/launcher/$(APP_NAME)
 THEME_FILE := subminer.rasi
-PLUGIN_CONF := plugin/subminer.conf
 
 # Default install prefix for the wrapper script.
 PREFIX ?= $(HOME)/.local
@@ -20,11 +19,6 @@ MACOS_DATA_DIR ?= $(HOME)/Library/Application Support/SubMiner
 MACOS_APP_DIR ?= $(HOME)/Applications
 MACOS_APP_DEST ?= $(MACOS_APP_DIR)/SubMiner.app
 
-# mpv plugin install directories.
-MPV_CONFIG_DIR ?= $(HOME)/.config/mpv
-MPV_SCRIPTS_DIR ?= $(MPV_CONFIG_DIR)/scripts
-MPV_SCRIPT_OPTS_DIR ?= $(MPV_CONFIG_DIR)/script-opts
-
 # If building from source, the AppImage will typically land in release/.
 APPIMAGE_SRC := $(firstword $(wildcard release/SubMiner-*.AppImage))
 MACOS_APP_SRC := $(firstword $(wildcard release/*.app release/*/*.app))
@@ -41,6 +35,17 @@ else
 PLATFORM := unknown
 endif
 
+WINDOWS_APPDATA ?= $(if $(APPDATA),$(subst \,/,$(APPDATA)),$(HOME)/AppData/Roaming)
+
+# mpv plugin install directories.
+ifeq ($(PLATFORM),windows)
+MPV_CONFIG_DIR ?= $(WINDOWS_APPDATA)/mpv
+else
+MPV_CONFIG_DIR ?= $(HOME)/.config/mpv
+endif
+MPV_SCRIPTS_DIR ?= $(MPV_CONFIG_DIR)/scripts
+MPV_SCRIPT_OPTS_DIR ?= $(MPV_CONFIG_DIR)/script-opts
+
 help:
 	@printf '%s\n' \
 		"Targets:" \
@@ -58,14 +63,16 @@ help:
 		"  dev-stop         Stop a running local Electron app" \
 		"  install-linux    Install Linux wrapper/theme/app artifacts" \
 		"  install-macos    Install macOS wrapper/theme/app artifacts" \
-		"  install-plugin   Install mpv Lua plugin and plugin config" \
+		"  install-windows  Print Windows packaging/install guidance" \
 		"  generate-config  Generate ~/.config/SubMiner/config.jsonc from centralized defaults" \
 		"" \
 		"Other targets:" \
-		"  deps             Install JS dependencies (root + texthooker-ui)" \
+		"  deps             Install JS dependencies (root + stats + texthooker-ui)" \
 		"  uninstall-linux  Remove Linux install artifacts" \
 		"  uninstall-macos  Remove macOS install artifacts" \
+		"  uninstall-windows Remove Windows mpv plugin artifacts" \
 		"  print-dirs       Show resolved install locations" \
+		"  lint             Lint stats (format check)" \
 		"" \
 		"Variables:" \
 		"  PREFIX=...        Override wrapper install prefix (default: $$HOME/.local)" \
@@ -74,7 +81,7 @@ help:
 		"  LINUX_DATA_DIR=... Override Linux app data dir" \
 		"  MACOS_DATA_DIR=... Override macOS app data dir" \
 		"  MACOS_APP_DIR=...  Override macOS app install dir (default: $$HOME/Applications)" \
-		"  MPV_CONFIG_DIR=... Override mpv config dir (default: $$HOME/.config/mpv)"
+		"  MPV_CONFIG_DIR=... Override mpv config dir (default: $$HOME/.config/mpv or %APPDATA%/mpv on Windows)"
 
 print-dirs:
 	@printf '%s\n' \
@@ -85,6 +92,10 @@ print-dirs:
 		"MACOS_DATA_DIR=$(MACOS_DATA_DIR)" \
 		"MACOS_APP_DIR=$(MACOS_APP_DIR)" \
 		"MACOS_APP_DEST=$(MACOS_APP_DEST)" \
+		"WINDOWS_APPDATA=$(WINDOWS_APPDATA)" \
+		"MPV_CONFIG_DIR=$(MPV_CONFIG_DIR)" \
+		"MPV_SCRIPTS_DIR=$(MPV_SCRIPTS_DIR)" \
+		"MPV_SCRIPT_OPTS_DIR=$(MPV_SCRIPT_OPTS_DIR)" \
 		"APPIMAGE_SRC=$(APPIMAGE_SRC)" \
 		"MACOS_APP_SRC=$(MACOS_APP_SRC)" \
 		"MACOS_ZIP_SRC=$(MACOS_ZIP_SRC)"
@@ -92,6 +103,7 @@ print-dirs:
 deps:
 	@$(MAKE) --no-print-directory ensure-bun
 	@bun install
+	@cd stats && bun install --frozen-lockfile
 	@cd vendor/texthooker-ui && bun install --frozen-lockfile
 
 ensure-bun:
@@ -99,12 +111,17 @@ ensure-bun:
 
 pretty: ensure-bun
 	@bun run format:src
+	@bun run format:stats
+
+lint: ensure-bun
+	@bun run lint:stats
 
 build:
 	@printf '%s\n' "[INFO] Detected platform: $(PLATFORM)"
 	@case "$(PLATFORM)" in \
 		linux) $(MAKE) --no-print-directory build-linux ;; \
 		macos) $(MAKE) --no-print-directory build-macos ;; \
+		windows) printf '%s\n' "[INFO] Windows builds run via: bun run build:win" ;; \
 		*) printf '%s\n' "[ERROR] Unsupported OS for this Makefile target: $(PLATFORM)"; exit 1 ;; \
 	esac
 
@@ -113,6 +130,7 @@ install:
 	@case "$(PLATFORM)" in \
 		linux) $(MAKE) --no-print-directory install-linux ;; \
 		macos) $(MAKE) --no-print-directory install-macos ;; \
+		windows) $(MAKE) --no-print-directory install-windows ;; \
 		*) printf '%s\n' "[ERROR] Unsupported OS for this Makefile target: $(PLATFORM)"; exit 1 ;; \
 	esac
 
@@ -151,7 +169,6 @@ generate-config: ensure-bun
 	@bun run electron . --generate-config
 
 generate-example-config: ensure-bun
-	@bun run build
 	@bun run generate:config-example
 
 dev-start: ensure-bun
@@ -181,6 +198,8 @@ install-linux: build-launcher
 	@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)/plugin/subminer"
+	@cp -R ./plugin/subminer/. "$(LINUX_DATA_DIR)/plugin/subminer/"
 	@if [ -n "$(APPIMAGE_SRC)" ]; then \
 		install -m 0755 "$(APPIMAGE_SRC)" "$(BINDIR)/SubMiner.AppImage"; \
 	else \
@@ -195,6 +214,8 @@ install-macos: build-launcher
 	@install -m 0755 "$(LAUNCHER_OUT)" "$(BINDIR)/$(APP_NAME)"
 	@install -d "$(MACOS_DATA_DIR)/themes"
 	@install -m 0644 "./$(THEME_SOURCE)" "$(MACOS_DATA_DIR)/themes/$(THEME_FILE)"
+	@install -d "$(MACOS_DATA_DIR)/plugin/subminer"
+	@cp -R ./plugin/subminer/. "$(MACOS_DATA_DIR)/plugin/subminer/"
 	@install -d "$(MACOS_APP_DIR)"
 	@if [ -n "$(MACOS_APP_SRC)" ]; then \
 		rm -rf "$(MACOS_APP_DEST)"; \
@@ -210,26 +231,33 @@ install-macos: build-launcher
 	fi
 	@printf '%s\n' "Installed to:" "  $(BINDIR)/subminer" "  $(MACOS_DATA_DIR)/themes/$(THEME_FILE)" "  $(MACOS_APP_DEST)"
 
-install-plugin:
-	@printf '%s\n' "[INFO] Installing mpv plugin artifacts"
-	@install -d "$(MPV_SCRIPTS_DIR)"
-	@rm -f "$(MPV_SCRIPTS_DIR)/subminer.lua"
-	@install -d "$(MPV_SCRIPTS_DIR)/subminer"
-	@install -d "$(MPV_SCRIPT_OPTS_DIR)"
-	@cp -R ./plugin/subminer/. "$(MPV_SCRIPTS_DIR)/subminer/"
-	@install -m 0644 "./$(PLUGIN_CONF)" "$(MPV_SCRIPT_OPTS_DIR)/subminer.conf"
-	@printf '%s\n' "Installed to:" "  $(MPV_SCRIPTS_DIR)/subminer/main.lua" "  $(MPV_SCRIPTS_DIR)/subminer/" "  $(MPV_SCRIPT_OPTS_DIR)/subminer.conf"
+install-windows:
+	@printf '%s\n' "[INFO] Windows builds run via: bun run build:win"
+	@printf '%s\n' "[INFO] SubMiner-managed mpv launches inject the bundled runtime plugin; no global mpv plugin install is needed."
 
-# Uninstall behavior kept unchanged by default.
-uninstall: uninstall-linux
+uninstall:
+	@printf '%s\n' "[INFO] Detected platform: $(PLATFORM)"
+	@case "$(PLATFORM)" in \
+		linux) $(MAKE) --no-print-directory uninstall-linux ;; \
+		macos) $(MAKE) --no-print-directory uninstall-macos ;; \
+		windows) $(MAKE) --no-print-directory uninstall-windows ;; \
+		*) printf '%s\n' "[ERROR] Unsupported OS for this Makefile target: $(PLATFORM)"; exit 1 ;; \
+	esac
 
 uninstall-linux:
 	@rm -f "$(BINDIR)/subminer" "$(BINDIR)/SubMiner.AppImage"
 	@rm -f "$(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
-	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(BINDIR)/SubMiner.AppImage" "  $(LINUX_DATA_DIR)/themes/$(THEME_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"
 
 uninstall-macos:
 	@rm -f "$(BINDIR)/subminer"
 	@rm -f "$(MACOS_DATA_DIR)/themes/$(THEME_FILE)"
+	@rm -rf "$(MACOS_DATA_DIR)/plugin/subminer"
 	@rm -rf "$(MACOS_APP_DEST)"
-	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(MACOS_DATA_DIR)/themes/$(THEME_FILE)" "  $(MACOS_APP_DEST)"
+	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(MACOS_DATA_DIR)/themes/$(THEME_FILE)" "  $(MACOS_DATA_DIR)/plugin/subminer" "  $(MACOS_APP_DEST)"
+
+uninstall-windows:
+	@rm -rf "$(MPV_SCRIPTS_DIR)/subminer"
+	@rm -f "$(MPV_SCRIPTS_DIR)/subminer.lua" "$(MPV_SCRIPTS_DIR)/subminer-loader.lua" "$(MPV_SCRIPT_OPTS_DIR)/subminer.conf"
+	@printf '%s\n' "Removed:" "  $(MPV_SCRIPTS_DIR)/subminer" "  $(MPV_SCRIPT_OPTS_DIR)/subminer.conf"

README.md

@@ -1,122 +1,304 @@
 <div align="center">
-  <img src="assets/SubMiner.png" width="169" alt="SubMiner logo">
-  <h1>SubMiner</h1>
-  <strong>Look up words, mine to Anki, and enrich cards with context — without leaving mpv.</strong>
-  <br /><br />
 
-[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
-[![Linux](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-informational)]()
-[![Docs](https://img.shields.io/badge/docs-docs.subminer.moe-blueviolet)](https://docs.subminer.moe)
+<img src="assets/SubMiner.png" width="160" alt="SubMiner logo">
+
+# SubMiner
+
+Look up words with Yomitan, export to Anki in one key, track your immersion — all without leaving mpv.
+
+[Installation](#quick-start) · [Requirements](#requirements) · [Usage](https://docs.subminer.moe/usage) · [Documentation](https://docs.subminer.moe)
+
+[![Downloads](https://img.shields.io/github/downloads/ksyasuda/SubMiner/total?style=flat-square&color=1a1a2e)](https://github.com/ksyasuda/SubMiner/releases)
+[![Release](https://img.shields.io/github/v/release/ksyasuda/SubMiner?style=flat-square&color=1a1a2e)](https://github.com/ksyasuda/SubMiner/releases/latest)
+[![AUR](https://img.shields.io/aur/version/subminer-bin?style=flat-square&color=1a1a2e)](https://aur.archlinux.org/packages/subminer-bin)
+[![Platform](https://img.shields.io/badge/platform-Linux%20·%20macOS%20·%20Windows-1a1a2e?style=flat-square)](https://github.com/ksyasuda/SubMiner)
+[![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)
 
 </div>
 
-<br />
+## Features
+
+### Dictionary Lookups
+
+Yomitan runs inside the overlay. Trigger a lookup on any word for full dictionary popups — definitions, pitch accent, frequency data — without ever leaving mpv.
 
 <div align="center">
-
-[![SubMiner demo (Animated preview)](./assets/minecard.webp)](./assets/minecard.mp4)
-
+  <img src="docs-site/public/screenshots/yomitan-lookup.png" width="800" alt="Yomitan dictionary popup over annotated subtitles in mpv">
 </div>
 
-<br />
+<br>
 
-## What it does
+### Instant Anki Mining
 
-SubMiner is an Electron overlay that sits on top of mpv. It turns your video player into a full sentence-mining workstation:
+Create an Anki card with the sentence, audio clip, screenshot, and machine translation from the exact playback moment with one key press, click, or controller input.
 
-- **Hover to look up** — Yomitan dictionary popups directly on subtitles
-- **Keyboard-driven lookup mode** — Navigate token-by-token, keep lookup open across tokens, and control popup scrolling/audio/mining without leaving the overlay
-- **One-key mining** — Creates Anki cards with sentence, audio, screenshot, and translation
-- **Instant auto-enrichment** — Optional local AnkiConnect proxy enriches new Yomitan cards immediately
-- **Reading annotations** — Combines N+1 targeting, frequency-dictionary highlighting, and JLPT underlining while you read
-- **Hover-aware playback** — By default, hovering subtitle text pauses mpv and resumes on mouse leave (`subtitleStyle.autoPauseVideoOnHover`)
-- **Subtitle tools** — Download from Jimaku, sync with alass/ffsubsync
-- **Immersion tracking** — SQLite-powered stats on your watch time and mining activity
-- **Custom texthooker page** — Built-in custom texthooker page and websocket, no extra setup
-- **Annotated websocket API** — Dedicated annotation feed can serve bundled texthooker or external clients with rendered `sentence` HTML plus structured `tokens`
-- **Jellyfin integration** — Remote playback setup, cast device mode, and direct playback launch
-- **AniList progress** — Track episode completion and push watching progress automatically
+<div align="center">
+  <img src="docs-site/public/screenshots/one-key-mining.png" width="800" alt="Anki card created from SubMiner with sentence, audio, and screenshot">
+</div>
 
-## Quick start
+<br>
+
+### Reading Annotations
+
+Real-time subtitle annotations with frequency highlighting, JLPT tags, N+1 targeting, and a character name dictionary. Known words fade back; new words stand out. Grammar-only tokens render as plain text so you focus on what matters.
+
+<div align="center">
+  <img src="docs-site/public/screenshots/annotations.png" width="800" alt="Annotated subtitles with frequency coloring, JLPT underlines, and N+1 targets">
+</div>
+
+<br>
+
+### Immersion Dashboard
+
+Local stats dashboard — watch time, anime library, vocabulary growth, mining throughput, session history, and trends. All stored locally, no third-party tracking.
+
+<div align="center">
+  <img src="docs-site/public/screenshots/stats-overview.png" width="800" alt="Stats dashboard showing watch time, cards mined, streaks, and tracking data">
+</div>
+
+<br>
+
+### Playlist Browser
+
+Browse sibling episode files and the active mpv queue in one overlay modal. Open it with `Ctrl+Alt+P` to append episodes from the current directory, jump to queued items, remove entries, or reorder the playlist without leaving playback.
+
+<div align="center">
+  <img src="docs-site/public/screenshots/playlist-browser.png" width="800" alt="Stats dashboard showing watch time, cards mined, streaks, and tracking data">
+</div>
+
+<br>
+
+### Integrations
+
+<table>
+  <tr>
+    <td><b>YouTube</b></td>
+    <td>Auto-loaded yt-dlp subtitle tracks at startup with config-driven primary/secondary language priorities and a manual overlay picker on demand (<code>Ctrl+Alt+C</code>)</td>
+  </tr>
+  <tr>
+    <td><b>AniList</b></td>
+    <td>Automatic episode tracking and progress sync</td>
+  </tr>
+  <tr>
+    <td><b>Jellyfin</b></td>
+    <td>Browse, launch, and cast media from your Jellyfin server with setup and discovery controls in the app tray</td>
+  </tr>
+  <tr>
+    <td><b>Jimaku</b></td>
+    <td>Search and download Japanese subtitles</td>
+  </tr>
+  <tr>
+    <td><b>alass / ffsubsync</b></td>
+    <td>Automatic subtitle retiming — requires <code>alass</code> or <code>ffsubsync</code> on your <code>PATH</code> (optional; subtitle syncing is disabled without them)</td>
+  </tr>
+  <tr>
+    <td><b>WebSocket</b></td>
+    <td>Annotated subtitle feed for external clients (texthooker pages, custom tools)</td>
+  </tr>
+</table>
+
+<div align="center">
+  <img src="docs-site/public/screenshots/texthooker.png" width="800" alt="Texthooker page receiving annotated subtitle lines via WebSocket">
+</div>
+
+<br>
+
+---
+
+## Requirements
+
+|                | Required                                | Recommended                          | Optional                                                                                                        |
+| -------------- | --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| **Player**     | [`mpv`](https://mpv.io) with IPC socket | —                                    | —                                                                                                               |
+| **Processing** | —                                       | `ffmpeg` (audio clips & screenshots) | `mecab` + `mecab-ipadic` (annotation POS filtering), `guessit` (AniSkip), `alass` / `ffsubsync` (subtitle sync) |
+| **Media**      | —                                       | —                                    | `yt-dlp`, `chafa`, `ffmpegthumbnailer`                                                                          |
+| **Selection**  | —                                       | —                                    | `fzf` / `rofi`                                                                                                  |
+
+> [!TIP]
+> `ffmpeg` is not strictly required to run SubMiner, but without it audio clips and screenshots will not be attached to Anki cards. Most users will want it installed.
+
+> [!NOTE]
+> [`bun`](https://bun.sh) is required if building from source or using the CLI wrapper: `subminer`. Pre-built releases (AppImage, DMG, installer) do not require it.
+
+**Platform-specific:**
+
+| Linux                                                        | macOS                    | Windows       |
+| ------------------------------------------------------------ | ------------------------ | ------------- |
+| Hyprland (`hyprctl`) · X11/Xwayland (`xdotool` + `xwininfo`) | Accessibility permission | No extra deps |
+
+> [!NOTE]
+> **Wayland support is compositor-specific.** Wayland has no universal API for window positioning and each compositor exposes its own IPC, so SubMiner needs a dedicated backend per compositor. Hyprland is the only native Wayland backend supported currenlty. All other Linux compositors require both mpv and SubMiner to run under X11 or Xwayland. The launcher detects your compositor and configures this automatically.
+
+<details>
+<summary><b>Arch Linux</b></summary>
+
+```bash
+paru -S --needed mpv ffmpeg
+# Optional
+paru -S --needed mecab-git mecab-ipadic yt-dlp fzf rofi chafa ffmpegthumbnailer xdotool xorg-xwininfo
+# Optional: subtitle sync (install at least one for subtitle syncing to work)
+paru -S --needed alass python-ffsubsync
+# X11 / Xwayland (required for non-Hyprland compositors)
+paru -S --needed xdotool xorg-xwininfo
+```
+
+</details>
+
+<details>
+<summary><b>macOS</b></summary>
+
+```bash
+brew install mpv ffmpeg
+# Optional
+brew install mecab mecab-ipadic yt-dlp fzf rofi chafa ffmpegthumbnailer
+# Optional: subtitle sync (install at least one for subtitle syncing to work)
+brew install alass
+pip install ffsubsync
+```
+
+Grant Accessibility permission to SubMiner in **System Settings > Privacy & Security > Accessibility**.
+
+</details>
+
+<details>
+<summary><b>Windows</b></summary>
+
+Install [`mpv`](https://mpv.io/installation/) and [`ffmpeg`](https://ffmpeg.org/download.html) and ensure both are on your `PATH`.
+
+Optionally install [MeCab for Windows](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary for additional metadata enrichment.
+
+</details>
+
+---
+
+## Quick Start
 
 ### 1. Install
 
-**Linux (AppImage):**
+<details>
+<summary><b>Arch Linux (AUR)</b></summary>
 
 ```bash
-wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppImage -O ~/.local/bin/SubMiner.AppImage
-chmod +x ~/.local/bin/SubMiner.AppImage
-wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer
-chmod +x ~/.local/bin/subminer
+paru -S subminer-bin
+```
 
+Or manually:
+
+```bash
+git clone https://aur.archlinux.org/subminer-bin.git && cd subminer-bin && makepkg -si
+```
+
+</details>
+
+<details>
+<summary><b>Linux (AppImage)</b></summary>
+
+```bash
+mkdir -p ~/.local/bin
+wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppImage -O ~/.local/bin/SubMiner.AppImage \
+	&& chmod +x ~/.local/bin/SubMiner.AppImage
+wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer \
+	&& chmod +x ~/.local/bin/subminer
 ```
 
 > [!NOTE]
 > The `subminer` wrapper uses a [Bun](https://bun.sh) shebang. Make sure `bun` is on your `PATH`.
 
-**From source** or **macOS** — initialize submodules first (`git submodule update --init --recursive`). Source builds now also require Node.js 22 + npm because bundled Yomitan is built from the `vendor/subminer-yomitan` submodule into `build/yomitan` during `bun run build`. Full install guide: [docs.subminer.moe/installation#from-source](https://docs.subminer.moe/installation#from-source).
+</details>
 
-### 2. Launch the app once
+<details>
+<summary><b>macOS</b></summary>
+
+Download the latest DMG or ZIP from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest) and drag `SubMiner.app` into `/Applications`.
+
+Also download the `subminer` launcher (recommended):
 
 ```bash
-SubMiner.AppImage
+sudo curl -fSL https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -o /usr/local/bin/subminer \
+	&& sudo chmod +x /usr/local/bin/subminer
 ```
 
-On first launch, SubMiner now:
+> [!NOTE]
+> The `subminer` launcher uses a [Bun](https://bun.sh) shebang. Make sure `bun` is on your `PATH`.
 
-- starts in the tray/background
-- creates the default config directory and `config.jsonc`
-- opens a compact setup popup
-- can install the mpv plugin to the default mpv scripts location for you
-- links directly to Yomitan settings so you can install dictionaries before finishing setup
+</details>
 
-Existing installs that already have a valid config plus at least one Yomitan dictionary are auto-detected as complete and will not be re-prompted.
+<details>
+<summary><b>Windows</b></summary>
 
-### 3. Finish setup
+Download the latest installer or portable `.zip` from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). Make sure `mpv` is on your `PATH`.
 
-- click `Install mpv plugin` if you want the default plugin auto-start flow
-- click `Open Yomitan Settings` and install at least one dictionary
-- click `Refresh status`
-- click `Finish setup`
+**Windows support is experimental.** Core features such as mining, annotations, and dictionary lookups work, but some functionality may be missing or unstable. Bug reports welcome.
 
-The mpv plugin step is optional. Yomitan must report at least one installed dictionary before setup can be completed.
+**Note:** On Windows the `subminer` launcher requires [`bun`](https://bun.sh) and must be invoked with `bun run subminer` instead of running the script directly. The recommended alternative is the **SubMiner mpv** shortcut created during first-run setup — double-click it, drag files onto it, or run `SubMiner.exe --launch-mpv` from a terminal. See the [Windows mpv Shortcut](https://docs.subminer.moe/usage#windows-mpv-shortcut) section for details.
+
+</details>
+
+<details>
+<summary><b>From source</b></summary>
+
+See the [build-from-source guide](https://docs.subminer.moe/installation#from-source).
+
+</details>
+
+### 2. First Launch
+
+```bash
+subminer app --setup            # launch the first-run setup wizard
+```
+
+SubMiner creates a default config, starts in the system tray, and opens a setup popup that walks you through installing the mpv plugin and configuring Yomitan dictionaries. Follow the on-screen steps to complete setup.
+
+Jellyfin setup is available from the tray or `subminer jellyfin`; once Jellyfin is enabled with a server URL, the tray can toggle Jellyfin Discovery for the current app session.
+
+> [!NOTE]
+> On Windows, run `SubMiner.exe` directly — it opens the setup wizard automatically on first launch.
+
+### 3. Verify Setup
+
+```bash
+subminer doctor                 # verify mpv, ffmpeg, config, and socket
+```
+
+> [!NOTE]
+> On Windows, use `bun run subminer doctor` or run `SubMiner.exe` directly — first-run setup will guide you through dependency checks.
 
 ### 4. Mine
 
 ```bash
-subminer video.mkv # default plugin config auto-starts visible overlay + resumes playback when ready
-subminer --start video.mkv # optional explicit overlay start when plugin auto_start=no
+subminer video.mkv          # play video with overlay
+subminer --start video.mkv  # explicit overlay start
+subminer stats              # open immersion dashboard
+subminer stats -b           # stats daemon in background
+subminer stats -s           # stop background stats daemon
 ```
 
-## Requirements
-
-| Required                                   | Optional                                           |
-| ------------------------------------------ | -------------------------------------------------- |
-| `bun`, `node` 22, `npm`                    |                                                    |
-| `mpv` with IPC socket                      | `yt-dlp`                                           |
-| `ffmpeg`                                   | `guessit` (better AniSkip title/episode detection) |
-| `mecab` + `mecab-ipadic`                   | `fzf` / `rofi`                                     |
-| Linux: `hyprctl` or `xdotool` + `xwininfo` | `chafa`, `ffmpegthumbnailer`                       |
-| macOS: Accessibility permission            |                                                    |
+On **Windows**, the `subminer` script must be run with `bun run subminer` (e.g. `bun run subminer video.mkv`). The recommended alternative is the **SubMiner mpv** shortcut (created during setup) or `SubMiner.exe --launch-mpv`. Drag a video file onto the shortcut to play it, or double-click it to open mpv with SubMiner's defaults.
 
 ## Documentation
 
-For full guides on configuration, Anki, Jellyfin, and more, see [docs.subminer.moe](https://docs.subminer.moe).
+Full guides on configuration, Anki setup, Jellyfin, immersion tracking, and more: **[docs.subminer.moe](https://docs.subminer.moe)**
 
-## Testing
-
-- Run `bun run test` or `bun run test:fast` for the default fast lane: config/core coverage plus representative entry/runtime, Anki integration, and main runtime checks.
-- Run `bun run test:full` for the maintained test surface: Bun-compatible `src/**` coverage, Bun-compatible launcher unit coverage, and a Node compatibility lane for suites that depend on Electron named exports or `node:sqlite` behavior.
-- Run `bun run test:node:compat` directly when you only need the Node-backed compatibility slice: `ipc`, `anki-jimaku-ipc`, `overlay-manager`, `config-validation`, `startup-config`, and runtime registry coverage.
-- Run `bun run test:env` for environment-specific verification: launcher smoke/plugin checks plus the SQLite-backed immersion tracker lane.
-- Run `bun run test:immersion:sqlite` when you specifically need real SQLite persistence coverage under Node with `--experimental-sqlite`.
-- Run `bun run test:subtitle` for the maintained `alass`/`ffsubsync` subtitle surface.
-
-The Bun-managed discovery lanes intentionally exclude a small set of suites that are currently Node-only because of Bun runtime/tooling gaps rather than product behavior: Electron named-export tests in `src/core/services/ipc.test.ts`, `src/core/services/anki-jimaku-ipc.test.ts`, and `src/core/services/overlay-manager.test.ts`, plus runtime/config tests in `src/main/config-validation.test.ts`, `src/main/runtime/startup-config.test.ts`, and `src/main/runtime/registry.test.ts`. `bun run test:node:compat` keeps those suites in the standard workflow instead of leaving them untracked.
+---
 
 ## Acknowledgments
 
-Built on the shoulders of [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner), [Renji's Texthooker Page](https://github.com/Renji-XD/texthooker-ui), [mpvacious](https://github.com/Ajatt-Tools/mpvacious), [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script), and [Bee's Character Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary). Subtitles powered by [Jimaku.cc](https://jimaku.cc). Dictionary lookups via [Yomitan](https://github.com/yomidevs/yomitan).
+SubMiner builds on the work of these open-source projects:
+
+| Project                                                                                     | Role                                                                    |
+| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script)                          | Inspiration for the mining workflow                                     |
+| [asbplayer](https://github.com/killergerbah/asbplayer)                                      | Inspiration for subtitle sidebar and logic for YouTube subtitle parsing |
+| [Bee's Character Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary) | Character name recognition in subtitles                                 |
+| [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner)                          | Inspiration for Electron overlay with Yomitan integration               |
+| [jellyfin-mpv-shim](https://github.com/jellyfin/jellyfin-mpv-shim)                          | Jellyfin integration                                                    |
+| [Jimaku.cc](https://jimaku.cc)                                                              | Japanese subtitle search and downloads                                  |
+| [Renji's Texthooker Page](https://github.com/Renji-XD/texthooker-ui)                        | Base for the WebSocket texthooker integration                           |
+| [Yomitan](https://github.com/yomidevs/yomitan)                                              | Dictionary engine powering all lookups and the morphological parser     |
+| [yomitan-jlpt-vocab](https://github.com/stephenmk/yomitan-jlpt-vocab)                       | JLPT level tags for vocabulary                                          |
 
 ## License
 

backlog/archive/tasks/task-87.7 - Developer-workflow-hygiene-make-docs-watch-reproducible-and-remove-stale-small-surface-drift.md

@@ -1,51 +0,0 @@
----
-id: TASK-87.7
-title: >-
-  Developer workflow hygiene: make docs watch reproducible and remove stale
-  small-surface drift
-status: To Do
-assignee: []
-created_date: '2026-03-06 03:20'
-updated_date: '2026-03-06 03:21'
-labels:
-  - tooling
-  - tech-debt
-milestone: m-0
-dependencies: []
-references:
-  - package.json
-  - bun.lock
-  - src/anki-integration/field-grouping-workflow.ts
-documentation:
-  - docs/reports/2026-02-22-task-100-dead-code-report.md
-parent_task_id: TASK-87
-priority: low
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-The review found a few low-risk but recurring hygiene issues: docs:watch depends on bunx concurrently even though concurrently is not declared in package metadata, and small stale API surface remains after recent refactors, such as unused parameters in field-grouping workflow code. This task should make the developer workflow reproducible and clean up low-risk stale symbols that do not warrant a dedicated architecture task.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 The docs:watch workflow runs through declared project tooling or is rewritten to avoid undeclared dependencies.
-- [ ] #2 Small stale symbols or parameters identified during the review outside the main composition-root cleanup are removed without behavior changes.
-- [ ] #3 Any contributor-facing command changes are reflected in repository documentation.
-- [ ] #4 The cleanup remains scoped to low-risk workflow and hygiene fixes rather than expanding into large architectural refactors.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-1. Fix the docs:watch workflow so it relies on declared project tooling or an equivalent checked-in command path.
-2. Clean up low-risk stale symbols surfaced by the review outside the main.ts architecture task, such as unused parameters left behind by refactors.
-3. Keep the task scoped: avoid pulling in main composition-root cleanup or larger Anki/runtime refactors.
-4. Verify the affected developer commands still work and document any usage changes.
-<!-- SECTION:PLAN:END -->

backlog/config.yml

@@ -1,16 +0,0 @@
-project_name: "SubMiner"
-default_status: "To Do"
-statuses: ["To Do", "In Progress", "Done"]
-labels: []
-definition_of_done: []
-date_format: yyyy-mm-dd
-max_column_width: 20
-default_editor: "nvim"
-auto_open_browser: false
-default_port: 6420
-remote_operations: true
-auto_commit: false
-bypass_git_hooks: false
-check_active_branches: true
-active_branch_days: 30
-task_prefix: "task"

backlog/milestones/m-0 - codebase-health-remediation.md

@@ -1,8 +0,0 @@
----
-id: m-0
-title: 'Codebase Health Remediation'
----
-
-## Description
-
-Follow-up work from the March 6, 2026 codebase review: strengthen the runnable test gate, remove confirmed dead architecture, and continue decomposition of oversized runtime entrypoints.

backlog/tasks/task-100 - Add-configurable-texthooker-startup-launch.md

@@ -1,49 +0,0 @@
----
-id: TASK-100
-title: 'Add configurable texthooker startup launch'
-status: Done
-assignee: []
-created_date: '2026-03-06 23:30'
-updated_date: '2026-03-07 01:59'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 10000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add a config option under `texthooker` to launch the built-in texthooker server automatically when SubMiner starts.
-
-Scope:
-
-- Add `texthooker.launchAtStartup`.
-- Default to `true`.
-- Start the existing texthooker server during normal app startup when enabled.
-- Keep `texthooker.openBrowser` as separate behavior.
-- Add regression coverage and update generated config docs/example.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Default config enables automatic texthooker startup.
-- [x] #2 Config parser accepts valid boolean values and warns on invalid values.
-- [x] #3 App-ready startup launches texthooker when enabled.
-- [x] #4 Generated config template/example documents the new option.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Added `texthooker.launchAtStartup` with a default of `true`, wired it through config defaults/validation/template generation, and started the existing texthooker server during app-ready startup without coupling it to browser auto-open behavior.
-
-Also added regression coverage for config parsing/template output and app-ready dependency wiring, then regenerated the checked-in config example artifacts.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-101 - Index-AniList-character-alternative-names-in-the-character-dictionary.md

@@ -1,39 +0,0 @@
----
-id: TASK-101
-title: Index AniList character alternative names in the character dictionary
-status: Done
-assignee: []
-created_date: '2026-03-07 00:00'
-updated_date: '2026-03-08 00:11'
-labels:
-  - dictionary
-  - anilist
-dependencies: []
-references:
-  - src/main/character-dictionary-runtime.ts
-  - src/main/character-dictionary-runtime.test.ts
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Index AniList character alternative names in generated character dictionaries so aliases like Shadow resolve during subtitle lookup instead of falling through to unrelated generic dictionary entries.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Character fetch reads AniList alternative character names needed for lookup coverage
-- [x] #2 Generated term banks include alias-derived terms for subtitle lookups like シャドウ
-- [x] #3 Regression coverage proves alternative-name indexing works end to end
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Character dictionary generation now requests AniList `name.alternative`, indexes those aliases as term candidates, and expands mixed aliases like `Minoru Kagenou (影野ミノル)` into usable outer/inner variants. Also extended kana alias synthesis so the AniList alias `Shadow` emits `シャドウ`, which matches the subtitle token the user hit in The Eminence in Shadow.
-
-Bumped the character-dictionary snapshot format to invalidate stale cached snapshots, and updated merged-dictionary rebuilds to refresh invalid snapshots before composing the ZIP so old cache files do not hard-fail the merge path.
-
-Verified with `bun test src/main/character-dictionary-runtime.test.ts` and `bun run tsc --noEmit`.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-102 - Quiet-default-AppImage-startup-and-implicit-background-launch.md

@@ -1,65 +0,0 @@
----
-id: TASK-102
-title: Quiet default AppImage startup and implicit background launch
-status: Done
-assignee:
-  - codex
-created_date: '2026-03-06 21:20'
-updated_date: '2026-03-06 21:33'
-labels: []
-dependencies: []
-references:
-  - /home/sudacode/projects/japanese/SubMiner/src/main-entry-runtime.ts
-  - /home/sudacode/projects/japanese/SubMiner/src/core/services/cli-command.ts
-  - /home/sudacode/projects/japanese/SubMiner/src/main.ts
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Make the packaged Linux no-arg launch path behave like a quiet background start instead of surfacing startup-only noise.
-
-Scope:
-
-- Treat default background entry launches as implicit `--start --background`.
-- Keep the `--password-store` diagnostic out of normal startup output.
-- Suppress known startup-only `node:sqlite` and `lsfg-vk` warnings for the entry/background launch path.
-- Avoid noisy protocol-registration warnings during normal startup when registration is unsupported.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-- [x] #1 Initial background launch reaches the start path without logging `No running instance. Use --start to launch the app.`
-- [x] #2 Default startup no longer emits the `Applied --password-store gnome-libsecret` line at normal log levels.
-- [x] #3 Entry/background launch sanitization suppresses the observed `ExperimentalWarning: SQLite...` and `lsfg-vk ... unsupported configuration version` startup noise.
-- [x] #4 Regression coverage documents the new startup behavior.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-Normalized no-arg/password-store-only entry launches to append implicit `--start --background`, and upgraded `--background`-only entry launches to include `--start`.
-
-Applied shared entry env sanitization before loading the main process so default startup strips the `lsfg-vk` Vulkan layer and sets `NODE_NO_WARNINGS=1`; background children keep the same sanitized env.
-
-Downgraded startup-only protocol-registration failure logging to debug, and routed the Linux password-store diagnostic through the scoped debug logger instead of raw console output.
-
-Verification:
-
-- `bun test src/main-entry-runtime.test.ts src/main/runtime/anilist-setup-protocol.test.ts src/main/runtime/anilist-setup-protocol-main-deps.test.ts`
-- `bun run test:fast`
-
-Note: the final `node --experimental-sqlite --test dist/main/runtime/registry.test.js` step in `bun run test:fast` still prints Node's own experimental SQLite warning because that test command explicitly enables the feature flag outside the app entrypoint.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Default packaged startup is now quiet and behaves like an implicit `--start --background` launch.
-
-- No-arg AppImage entry launches now append `--start --background`, and `--background`-only launches append the missing `--start`.
-- Entry/background startup sanitization now suppresses the observed `lsfg-vk` and `node:sqlite` warnings on the app launch path.
-- Linux password-store and unsupported protocol-registration diagnostics now stay at debug level instead of normal startup output.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-103 - Add-dedicated-annotation-websocket-for-texthooker.md

@@ -1,38 +0,0 @@
----
-id: TASK-103
-title: Add dedicated annotation websocket for texthooker
-status: Done
-assignee:
-  - codex
-created_date: '2026-03-07 02:20'
-updated_date: '2026-03-07 02:20'
-labels:
-  - texthooker
-  - websocket
-  - subtitle
-dependencies: []
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Add a separate annotated subtitle websocket for bundled texthooker so token/JLPT/frequency markup is available on a stable dedicated port even when the regular websocket is in `auto` mode and skipped because `mpv_websocket` is installed.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-- [x] #1 Regular `websocket.enabled: "auto"` behavior remains unchanged and still skips the regular websocket when `mpv_websocket` is installed.
-- [x] #2 A separate `annotationWebsocket` config controls an independent annotated websocket with default port `6678`.
-- [x] #3 Bundled texthooker is pointed at the annotation websocket when it is enabled.
-- [x] #4 Focused regression tests cover config parsing, startup wiring, and texthooker bootstrap injection.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Added `annotationWebsocket.enabled`/`annotationWebsocket.port` with defaults of `true`/`6678`, started that websocket independently from the regular auto-managed websocket, and injected the bundled texthooker websocket URL so it connects to the annotation feed by default.
-
-Also added focused regression coverage and regenerated the checked-in config examples.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-104 - Mirror-overlay-annotation-hover-behavior-in-vendored-texthooker.md

@@ -1,43 +0,0 @@
----
-id: TASK-104
-title: Mirror overlay annotation hover behavior in vendored texthooker
-status: Done
-assignee:
-  - codex
-created_date: '2026-03-06 21:45'
-updated_date: '2026-03-06 21:45'
-labels:
-  - texthooker
-  - subtitle
-  - websocket
-dependencies:
-  - TASK-103
-references:
-  - /home/sudacode/projects/japanese/SubMiner/src/core/services/subtitle-ws.ts
-  - /home/sudacode/projects/japanese/SubMiner/vendor/texthooker-ui/src/components/App.svelte
-  - /home/sudacode/projects/japanese/SubMiner/vendor/texthooker-ui/src/line-markup.ts
-  - /home/sudacode/projects/japanese/SubMiner/vendor/texthooker-ui/src/app.css
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Bring bundled texthooker annotation rendering closer to the visible overlay. Keep the lightweight texthooker UX, but preserve token metadata for hover, match overlay color-precedence rules across known/N+1/name/frequency/JLPT, expose name-match highlighting as a toggle, and emit a structured annotation payload on the dedicated websocket so non-SubMiner clients can treat it as an API.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-- [x] #1 Annotation websocket payload includes both rendered `sentence` HTML and structured token metadata for generic clients.
-- [x] #2 Vendored texthooker preserves annotation metadata attrs needed for hover labels and uses overlay-matching color precedence rules.
-- [x] #3 Vendored texthooker supports character-name highlighting with a user-facing toggle and standalone-web note.
-- [x] #4 Hovering annotated texthooker tokens reveals JLPT/frequency metadata without adding the full overlay popup workflow.
-- [x] #5 Focused serializer, texthooker markup, socket parsing, CSS, and build verification pass.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Extended the dedicated annotation websocket payload to ship `version`, plain `text`, rendered `sentence`, and structured `tokens` metadata while keeping backward-compatible `sentence` consumers working. Updated the vendored texthooker to preserve hover metadata attrs, follow overlay color precedence for known/N+1/name/frequency/JLPT annotations, add a character-name highlight toggle plus standalone-web dictionary note, and render lightweight hover labels for frequency/JLPT metadata. Added focused regression coverage and rebuilt both the vendored texthooker bundle and SubMiner.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-105 - Stop-local-docs-artifact-writes-after-docs-repo-split.md

@@ -1,47 +0,0 @@
----
-id: TASK-105
-title: Stop local docs artifact writes after docs repo split
-status: Done
-assignee: []
-created_date: '2026-03-07 00:00'
-updated_date: '2026-03-07 00:20'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 10500
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Now that user-facing docs live in `../subminer-docs`, first-party scripts in this repo should not keep writing generated artifacts into the local `docs/` tree.
-
-Scope:
-
-- Audit first-party scripts/automation for writes to `docs/`.
-- Keep repo-local outputs only where they are still intentionally owned by this repo.
-- Repoint generated docs artifacts to `../subminer-docs` when that is the maintained source of truth.
-- Add regression coverage for the config-example generation path contract.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 The config-example generator no longer writes to `docs/public/config.example.jsonc` inside this repo.
-- [x] #2 When `../subminer-docs` exists, the generator updates `../subminer-docs/public/config.example.jsonc`.
-- [x] #3 Automated coverage guards the output-path contract so local docs writes do not regress.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Removed the first-party local `docs/public` config-example write path from `src/generate-config-example.ts` and replaced it with sibling-docs-repo detection that targets `../subminer-docs/public/config.example.jsonc` only when that repo exists.
-
-Added a project-local regression suite for output-path resolution and artifact writing, wired that suite into the maintained config test lane, and removed the stale generated `docs/public/config.example.jsonc` artifact from the working tree.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-106 - Add-first-run-setup-gate-and-auto-install-flow.md

@@ -1,69 +0,0 @@
----
-id: TASK-106
-title: Add first-run setup gate and auto-install flow
-status: Done
-assignee:
-  - codex
-created_date: '2026-03-07 06:10'
-updated_date: '2026-03-07 06:20'
-labels: []
-dependencies: []
-references:
-  - /home/sudacode/projects/japanese/SubMiner/src/main.ts
-  - /home/sudacode/projects/japanese/SubMiner/src/shared/setup-state.ts
-  - /home/sudacode/projects/japanese/SubMiner/src/main/runtime/first-run-setup-service.ts
-  - /home/sudacode/projects/japanese/SubMiner/src/main/runtime/first-run-setup-window.ts
-  - /home/sudacode/projects/japanese/SubMiner/launcher/commands/playback-command.ts
-priority: high
-ordinal: 10600
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Replace the current manual install flow with a first-run setup gate:
-
-- bootstrap the default config dir/config file automatically
-- detect legacy installs and mark them complete when config + Yomitan dictionaries are already present
-- open a compact Catppuccin Macchiato setup popup for incomplete installs
-- optionally install the mpv plugin into the default mpv location
-- block launcher playback until setup completes, then resume the original playback flow
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-- [x] #1 First app launch seeds the default config dir/config file without manual copy steps.
-- [x] #2 Existing installs with config plus at least one Yomitan dictionary are auto-detected as already complete.
-- [x] #3 Incomplete installs get a first-run setup popup with mpv plugin install, Yomitan settings, refresh, skip, and finish actions.
-- [x] #4 Launcher playback waits for setup completion and does not start mpv while setup is incomplete.
-- [x] #5 Plugin assets are packaged into the Electron bundle and regression tests cover the new flow.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-Added shared setup-state/config/mpv path helpers so Electron and launcher read the same onboarding state file.
-
-Introduced a first-run setup service plus compact BrowserWindow popup using Catppuccin Macchiato styling. The popup supports optional mpv plugin install, opening Yomitan settings, status refresh, skip-plugin, and gated finish once at least one Yomitan dictionary is installed.
-
-Electron startup now bootstraps a default config file, auto-detects legacy-complete installs, adds `--setup` CLI support, exposes a tray `Complete Setup` action while incomplete, and avoids reopening setup once completion is recorded.
-
-Launcher playback now checks the shared setup-state file before starting mpv. If setup is incomplete, it launches the app with `--background --setup`, waits for completion, and only then proceeds.
-
-Verification:
-
-- `bun run typecheck`
-- `bun run test:fast`
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-SubMiner now supports a download-and-launch install flow.
-
-- First launch auto-creates config and opens setup only when needed.
-- Existing users with working installs are silently migrated to completed setup.
-- The setup popup handles optional mpv plugin install and Yomitan dictionary readiness.
-- Launcher playback is gated on setup completion and resumes automatically afterward.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-107 - Fix-Yomitan-scan-token-fallback-fragmentation.md

@@ -1,42 +0,0 @@
----
-id: TASK-107
-title: 'Fix Yomitan scan-token fallback fragmentation on exact-source misses'
-status: Done
-assignee: []
-created_date: '2026-03-07 01:10'
-updated_date: '2026-03-07 01:12'
-labels: []
-dependencies: []
-priority: high
-ordinal: 9007
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Left-to-right Yomitan scanning can emit bogus fallback tokens when `termsFind` returns entries but none of their headwords carries an exact primary source for the consumed substring. Repro: `だが それでも届かぬ高みがあった` currently yields trailing fragments like `があ` / `た`, which blocks the real `あった` token from receiving frequency highlighting.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Scanner skips `termsFind` fallback entries that are not backed by an exact primary source for the consumed substring.
-- [x] #2 Repro line no longer yields bogus trailing fragments such as `があ`.
-- [x] #3 Regression coverage added for the scan-token path.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Removed the scan-token helper fallback that previously emitted a token from the first returned headword even when Yomitan did not report an exact primary source for the consumed substring. Added a focused regression test covering `だが それでも届かぬ高みがあった`, ensuring bogus `があ` fragmentation is skipped so the later `あった` exact match can still be tokenized and highlighted.
-
-Verification:
-
-- `bun test src/core/services/tokenizer/yomitan-parser-runtime.test.ts src/core/services/tokenizer.test.ts --timeout 20000`
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-108 - Exclude-single-kana-tokens-from-frequency-highlighting.md

@@ -1,43 +0,0 @@
----
-id: TASK-108
-title: 'Exclude single kana tokens from frequency highlighting'
-status: Done
-assignee: []
-created_date: '2026-03-07 01:18'
-updated_date: '2026-03-07 01:22'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 9008
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Suppress frequency highlighting for single-character hiragana or katakana tokens. Scope is frequency-only: known/N+1/JLPT behavior stays unchanged.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Single-character hiragana tokens do not retain `frequencyRank`.
-- [x] #2 Single-character katakana tokens do not retain `frequencyRank`.
-- [x] #3 Regression coverage exists at annotation-stage and tokenizer levels.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Added a frequency-only suppression rule for single-character kana tokens based on token `surface`, so bogus merged fragments like `た` and standalone one-character kana no longer keep `frequencyRank`. Regression coverage now exists both in the annotation stage and in the tokenizer path, while multi-character tokens and N+1/JLPT behavior remain unchanged.
-
-Verification:
-
-- `bun test src/core/services/tokenizer/annotation-stage.test.ts --timeout 20000`
-- `bun test src/core/services/tokenizer.test.ts --timeout 20000`
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-110 - Replace-vendored-Yomitan-with-submodule-built-chrome-artifact-workflow.md

@@ -1,51 +0,0 @@
----
-id: TASK-110
-title: Replace vendored Yomitan with submodule-built Chrome artifact workflow
-status: Done
-assignee: []
-created_date: '2026-03-07 11:05'
-updated_date: '2026-03-07 11:22'
-labels:
-  - yomitan
-  - build
-  - release
-dependencies: []
-priority: high
-ordinal: 9010
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Replace the checked-in `vendor/yomitan` release tree with a `subminer-yomitan` git submodule. Build Yomitan from source, extract the Chromium zip artifact into a stable local build directory, and make SubMiner dev/runtime/tests/release packaging load that extracted extension instead of the source tree or vendored files.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Repo tracks Yomitan as a git submodule instead of committed extension files under `vendor/yomitan`.
-- [x] #2 SubMiner has a reproducible build/extract step that produces a local Chromium extension directory from `subminer-yomitan`.
-- [x] #3 Dev/runtime/tests resolve the extracted build output as the default Yomitan extension path.
-- [x] #4 Release packaging includes the extracted Chromium extension files instead of the old vendored tree.
-- [x] #5 Docs and verification commands reflect the new workflow.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Replaced the checked-in `vendor/yomitan` extension tree with a `vendor/subminer-yomitan` git submodule and added a reproducible `bun run build:yomitan` workflow that builds `yomitan-chrome.zip`, extracts it into `build/yomitan`, and reuses a source-state stamp to skip redundant rebuilds. Runtime path resolution, helper CLIs, Yomitan integration tests, packaging, CI cache keys, and README source-build notes now all target that generated artifact instead of the old vendored files.
-
-Verification:
-
-- `bun run build:yomitan`
-- `bun test src/core/services/yomitan-extension-paths.test.ts src/core/services/yomitan-structured-content-generator.test.ts src/yomitan-translator-sort.test.ts`
-- `bun run typecheck`
-- `bun run build`
-- `bun run test:core:src`
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-111 - Fix-subtitle-cycle-OSD-labels-for-J-keybindings.md

@@ -1,71 +0,0 @@
----
-id: TASK-111
-title: Fix subtitle-cycle OSD labels for J keybindings
-status: Done
-assignee:
-  - Codex
-created_date: '2026-03-07 23:45'
-updated_date: '2026-03-08 00:06'
-labels: []
-dependencies: []
-references:
-  - /Users/sudacode/projects/japanese/SubMiner/src/core/services/ipc-command.ts
-  - /Users/sudacode/projects/japanese/SubMiner/src/core/services/mpv.ts
-  - >-
-    /Users/sudacode/projects/japanese/SubMiner/src/core/services/ipc-command.test.ts
-  - >-
-    /Users/sudacode/projects/japanese/SubMiner/src/core/services/mpv-control.test.ts
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-When cycling subtitle tracks with the default J/Shift+J keybindings, the mpv OSD currently shows raw template text like `${sid}` instead of a resolved subtitle label. Update the keybinding OSD behavior so users see the active subtitle selection clearly when cycling tracks, and ensure placeholder-based OSD messages sent through the mpv client API render correctly.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Pressing the primary subtitle cycle keybinding shows a resolved subtitle label on the OSD instead of a raw `${sid}` placeholder.
-- [x] #2 Pressing the secondary subtitle cycle keybinding shows a resolved subtitle label on the OSD instead of a raw `${secondary-sid}` placeholder.
-- [x] #3 Proxy OSD messages that rely on mpv property expansion render resolved values when sent through the mpv client API.
-- [x] #4 Regression tests cover the subtitle-cycle OSD behavior and the placeholder-expansion OSD path.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-1. Add focused failing tests for subtitle-cycle OSD labels and mpv placeholder-expansion behavior.
-2. Update the IPC mpv command handler to resolve primary and secondary subtitle track labels from mpv `track-list` data after cycling subtitle tracks.
-3. Update the mpv OSD runtime path so placeholder-based `show-text` messages sent through the client API opt into property expansion.
-4. Run focused tests, then the relevant core test lane, and record results in the task notes.
-<!-- SECTION:PLAN:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-Initial triage: `ipc-command.ts` emits raw `${sid}`/`${secondary-sid}` placeholder strings, and `showMpvOsdRuntime` sends `show-text` via mpv client API without enabling property expansion.
-
-User approved implementation plan on 2026-03-07.
-
-Implementation: proxy mpv command OSD now supports an async resolver so subtitle track cycling can show human-readable labels instead of raw `${sid}` placeholders.
-
-Implementation: `showMpvOsdRuntime` now prefixes placeholder-based messages with mpv client-api `expand-properties`, which fixes raw `${...}` OSD output for subtitle delay/position messages.
-
-Testing: `bun test src/core/services/ipc-command.test.ts src/core/services/mpv-control.test.ts src/main/runtime/mpv-proxy-osd.test.ts src/main/runtime/ipc-mpv-command-main-deps.test.ts src/main/runtime/ipc-bridge-actions.test.ts src/main/runtime/ipc-bridge-actions-main-deps.test.ts src/main/runtime/composers/ipc-runtime-composer.test.ts` passed.
-
-Testing: `bun x tsc --noEmit` passed.
-
-Testing: `bun run test:core:src` passed (423 pass, 6 skip, 0 fail).
-
-Docs: no update required because no checked-in docs or help text describe the J/Shift+J OSD output behavior.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Fixed subtitle-cycle OSD handling for the default J/Shift+J keybindings. The IPC mpv command path now supports resolving proxy OSD text asynchronously, and the main-runtime resolver reads mpv `track-list` state so primary and secondary subtitle cycling show human-readable track labels instead of raw `${sid}` / `${secondary-sid}` placeholders.
-
-Also fixed the lower-level mpv OSD transport so placeholder-based `show-text` messages sent through the client API opt into `expand-properties`. That preserves existing template-based OSD messages like subtitle delay and subtitle position without leaking the raw `${...}` syntax.
-
-Added regression coverage for the async proxy OSD path, the placeholder-expansion `showMpvOsdRuntime` path, and the runtime subtitle-track label resolver. Verification run: `bun x tsc --noEmit`; focused mpv/IPC tests; and the maintained `bun run test:core:src` lane (423 pass, 6 skip, 0 fail).
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-112 - Address-Claude-review-items-on-PR-15.md

@@ -1,61 +0,0 @@
----
-id: TASK-112
-title: Address Claude review items on PR 15
-status: Done
-assignee:
-  - codex
-created_date: '2026-03-08 00:11'
-updated_date: '2026-03-08 00:12'
-labels:
-  - pr-review
-  - ci
-dependencies: []
-references:
-  - .github/workflows/release.yml
-  - .github/workflows/ci.yml
-  - .gitmodules
-  - >-
-    backlog/tasks/task-101 -
-    Index-AniList-character-alternative-names-in-the-character-dictionary.md
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Review Claude's PR feedback on PR #15, implement only the technically valid fixes on the current branch, and document which comments are non-actionable or already acceptable.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Validated Claude's concrete PR review items against current branch state and repo conventions
-- [x] #2 Implemented the accepted fixes with regression coverage or verification where applicable
-- [x] #3 Documented which review items are non-blocking or intentionally left unchanged
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-1. Validate each Claude review item against current branch files and repo workflow.
-2. Patch release quality-gate to match CI ordering and add explicit typecheck.
-3. Remove duplicate .gitmodules stanza and normalize the TASK-101 reference path through Backlog MCP.
-4. Run relevant verification for workflow/config metadata changes and record which review items remain non-actionable.
-<!-- SECTION:PLAN:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-User asked to address Claude PR comments on PR #15 and assess whether any action items remain. Treat review suggestions skeptically; only fix validated defects.
-
-Validated Claude's five review items. Fixed release workflow ordering/typecheck, removed the duplicate .gitmodules entry, and normalized TASK-101 references to repo-relative paths via Backlog MCP.
-
-Left the vendor/subminer-yomitan branch-pin suggestion unchanged. The committed submodule SHA already controls reproducibility; adding a branch would only affect update ergonomics and was not required to address a concrete defect.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Validated Claude's PR #15 review summary against the current branch and applied the actionable fixes. In `.github/workflows/release.yml`, the release `quality-gate` job now restores the dependency cache before installation, no longer installs twice, and runs `bun run typecheck` before the fast test suite to match CI expectations. In `.gitmodules`, removed the duplicate `vendor/yomitan-jlpt-vocab` stanza with the conflicting duplicate path. Through Backlog MCP, updated `TASK-101` references from an absolute local path to repo-relative paths so the task metadata is portable across contributors.
-
-Verification: `git diff --check`, `git config -f .gitmodules --get-regexp '^submodule\..*\.path$'`, `bun run typecheck`, and `bun run test:fast` all passed. `bun run format:check` still fails on many pre-existing unrelated files already present on the branch, including multiple backlog task files and existing source/docs files; this review patch did not attempt a repo-wide formatting sweep.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-113 - Scope-make-pretty-to-maintained-source-files.md

@@ -1,59 +0,0 @@
----
-id: TASK-113
-title: Scope make pretty to maintained source files
-status: Done
-assignee:
-  - codex
-created_date: '2026-03-08 00:20'
-updated_date: '2026-03-08 00:22'
-labels:
-  - tooling
-  - formatting
-dependencies: []
-references:
-  - Makefile
-  - package.json
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Change the `make pretty` workflow so it formats only the maintained source/config files we intentionally keep under Prettier, instead of sweeping backlog/docs/generated content across the whole repository.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 `make pretty` formats only the approved maintained source/config paths
-- [x] #2 The allowlist is reusable for check/write flows instead of duplicating path logic
-- [x] #3 Verification shows the scoped formatting command targets the intended files without touching backlog or vendored content
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-1. Inspect current Prettier config/ignore behavior and keep the broad repo-wide format command unchanged.
-2. Add a reusable scoped Prettier script that targets maintained source/config paths only.
-3. Update `make pretty` to call the scoped script.
-4. Verify the scoped command resolves only intended files and does not traverse backlog or vendor paths.
-<!-- SECTION:PLAN:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-User approved the allowlist approach: keep repo-wide `format` intact, make `make pretty` use a maintained-path formatter scope.
-
-Added `scripts/prettier-scope.sh` as the single allowlist for scoped Prettier paths and wired `format:src` / `format:check:src` to it.
-
-Updated `make pretty` to call `bun run format:src`. Verified with `make -n pretty` and shell tracing that the helper only targets the maintained allowlist and does not traverse `backlog/` or `vendor/`.
-
-Excluded `Makefile` and `.prettierignore` from the allowlist after verification showed Prettier cannot infer parsers for them.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Scoped the repo's day-to-day formatting entrypoint without changing the existing broad repo-wide Prettier scripts. Added `scripts/prettier-scope.sh` as the shared allowlist for maintained source/config paths (`.github`, `build`, `launcher`, `scripts`, `src`, plus selected root JSON config files), added `format:src` and `format:check:src` in `package.json`, and updated `make pretty` to run the scoped formatter.
-
-Verification: `make -n pretty` now resolves to `bun run format:src`. `bash -n scripts/prettier-scope.sh` passed, and shell-traced `bash -x scripts/prettier-scope.sh --check` confirmed the exact allowlist passed to Prettier. `bun run format:check:src` fails only because existing files inside the allowed source scope are not currently formatted; it no longer touches `backlog/` or `vendor/`.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-114 - Fix-failing-CI-checks-on-PR-15.md

@@ -1,62 +0,0 @@
----
-id: TASK-114
-title: Fix failing CI checks on PR 15
-status: Done
-assignee:
-  - codex
-created_date: '2026-03-08 00:34'
-updated_date: '2026-03-08 00:37'
-labels:
-  - ci
-  - test
-dependencies: []
-references:
-  - src/renderer/subtitle-render.test.ts
-  - src/renderer/style.css
-  - .github/workflows/ci.yml
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Investigate the failing GitHub Actions CI run for PR #15 on branch `yomitan-fork`, fix the underlying test or code regression, and verify the affected local test/CI lane passes.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Identified the concrete failing CI job and captured the relevant failure context
-- [x] #2 Implemented the minimal code or test change needed to resolve the CI failure
-- [x] #3 Verified the affected local test target and the broader fast CI test lane pass
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-1. Inspect the failing GitHub Actions run and confirm the exact failing test/assertion.
-2. Reproduce the failing renderer stylesheet test locally and compare the assertion against current CSS.
-3. Apply the minimal test or stylesheet fix needed to restore the intended hover/selection behavior.
-4. Re-run the targeted renderer test, then re-run `bun run test` to verify the fast CI lane is green.
-<!-- SECTION:PLAN:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-GitHub Actions run 22810400921 failed in job build-test-audit, step `Test suite (source)`, with a single failing test: `JLPT CSS rules use underline-only styling in renderer stylesheet` in src/renderer/subtitle-render.test.ts.
-
-Reproduced the failing test locally with `bun test src/renderer/subtitle-render.test.ts`. The failure was a brittle stylesheet assertion, not a renderer behavior regression.
-
-Updated the renderer stylesheet test helper to split selectors safely across `:is(...)` commas and normalize multiline selector whitespace, then switched the failing hover/JLPT assertions to inspect extracted rule blocks instead of matching the entire CSS file text.
-
-Verification passed with `bun test src/renderer/subtitle-render.test.ts` and `bun run test`.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Investigated GitHub Actions CI run `22810400921` for PR #15 and confirmed the only failing job was `build-test-audit`, step `Test suite (source)`, with a single failure in `src/renderer/subtitle-render.test.ts` (`JLPT CSS rules use underline-only styling in renderer stylesheet`).
-
-The renderer CSS itself was still correct; the regression was in the test helper. `extractClassBlock` was splitting selector lists on every comma, which breaks selectors containing `:is(...)`, and the affected assertions fell back to brittle whole-file regex matching against a multiline selector. Fixed the test by teaching the helper to split selectors only at top-level commas, normalizing selector whitespace around multiline `:not(...)` / `:is(...)` clauses, and asserting on extracted rule blocks for the plain-word hover and JLPT-only hover/selection rules.
-
-Verification: `bun test src/renderer/subtitle-render.test.ts` passed, and `bun run test` passed end to end (the same fast lane that failed in CI).
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-115 - Refresh-subminer-docs-contributor-docs-for-current-repo-workflow.md

@@ -1,59 +0,0 @@
----
-id: TASK-115
-title: Refresh subminer-docs contributor docs for current repo workflow
-status: Done
-assignee:
-  - codex
-created_date: '2026-03-08 00:40'
-updated_date: '2026-03-08 00:42'
-labels:
-  - docs
-dependencies: []
-references:
-  - ../subminer-docs/development.md
-  - ../subminer-docs/README.md
-  - Makefile
-  - package.json
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Update the sibling `subminer-docs` repo so contributor/development docs match the current SubMiner repo workflow after the docs split and recent tooling changes, including removing stale in-repo docs build steps and documenting the scoped formatting command.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Contributor docs in `subminer-docs` no longer reference stale in-repo docs build commands for the app repo
-- [x] #2 Contributor docs mention the current scoped formatting workflow (`make pretty` / `format:src`) where relevant
-- [x] #3 Removed stale or no-longer-needed instructions that no longer match the current repo layout
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-1. Inspect `subminer-docs` for contributor/development instructions that drifted after the docs repo split and recent tooling changes.
-2. Update contributor docs to remove stale app-repo docs commands and document the current scoped formatting workflow.
-3. Verify the modified docs page and build the docs site from the sibling docs repo when local dependencies are available.
-<!-- SECTION:PLAN:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-Detected concrete doc drift in `subminer-docs/development.md`: stale in-repo docs build commands and no mention of the scoped `make pretty` formatter.
-
-Updated `../subminer-docs/development.md` to remove stale app-repo docs build steps from the local gate, document `make pretty` / `format:check:src`, and point docs-site work to the sibling docs repo explicitly.
-
-Installed docs repo dependencies locally with `bun install` and verified the docs site with `bun run docs:build` in `../subminer-docs`.
-
-Did not change `../subminer-docs/README.md`; it was already accurate for the docs repo itself.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Refreshed the contributor/development docs in the sibling `subminer-docs` repo to match the current SubMiner workflow. In `development.md`, removed the stale app-repo `bun run docs:build` step from the local CI-equivalent gate, added an explicit note to run docs builds from `../subminer-docs` when docs change, documented the scoped formatting workflow (`make pretty` and `bun run format:check:src`), and replaced the old in-repo `make docs*` instructions with the correct sibling-repo `bun run docs:*` commands. Also updated the Makefile reference to include `make pretty` and removed the obsolete `make docs-dev` entry.
-
-Verification: installed docs repo dependencies with `bun install` in `../subminer-docs` and ran `bun run docs:build` successfully. Left `README.md` unchanged because it was already accurate for the standalone docs repo.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-116 - Audit-branch-commits-for-remaining-subminer-docs-updates.md

@@ -1,53 +0,0 @@
----
-id: TASK-116
-title: Audit branch commits for remaining subminer-docs updates
-status: Done
-assignee:
-  - codex
-created_date: '2026-03-08 00:46'
-updated_date: '2026-03-08 00:48'
-labels:
-  - docs
-dependencies: []
-references:
-  - ../subminer-docs/installation.md
-  - ../subminer-docs/troubleshooting.md
-  - src/core/services/yomitan-extension-paths.ts
-  - scripts/build-yomitan.mjs
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Review recent `yomitan-fork` commits against the sibling `subminer-docs` repo, identify any concrete documentation drift that remains after the earlier contributor-doc updates, and patch the docs for behavior/tooling changes that are now outdated or misleading.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Reviewed recent branch commits for user-facing or contributor-facing changes that may require docs updates
-- [x] #2 Updated `subminer-docs` pages where branch changes introduced concrete doc drift
-- [x] #3 Verified the docs site still builds after the updates
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-1. Review branch commit themes against `subminer-docs` and identify only concrete drift introduced by recent workflow/runtime changes.
-2. Patch docs for the Yomitan submodule build workflow, updated source-build prerequisites, and current runtime Yomitan search paths/manual fallback path.
-3. Rebuild the docs site to verify the updated pages render cleanly.
-<!-- SECTION:PLAN:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-Concrete remaining drift after commit audit: installation/development docs still understate the Node/npm + submodule requirements for the Yomitan build flow, and troubleshooting still points at obsolete `vendor/yomitan` / `extensions/yomitan` paths.
-
-Audited branch commits against subminer-docs coverage. Existing docs already cover first-run setup, texthooker startup/annotated websocket config, AniList merged character dictionaries, configurable collapsible sections, and subtitle name highlighting. Patched remaining drift around source-build prerequisites and Yomitan build/install paths in installation.md, development.md, and troubleshooting.md. Verified with `bun run docs:build` in ../subminer-docs.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Audited branch commits for missing documentation updates in ../subminer-docs. Updated installation, development, and troubleshooting docs to match the current Yomitan submodule build flow, source-build prerequisites, and runtime extension search/manual fallback paths. Confirmed other recent branch features were already documented and rebuilt the docs site successfully.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-118 - Fix-GitHub-release-workflow-publish-step-failure.md

@@ -1,64 +0,0 @@
----
-id: TASK-118
-title: Fix GitHub release workflow publish step failure
-status: Done
-assignee:
-  - Codex
-created_date: '2026-03-08 03:34'
-updated_date: '2026-03-08 03:38'
-labels:
-  - ci
-  - release
-  - github-actions
-dependencies: []
-references:
-  - /Users/sudacode/projects/japanese/SubMiner/.github/workflows/release.yml
-  - 'https://github.com/ksyasuda/SubMiner/actions/runs/22812335927'
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-The GitHub Actions Release workflow fails during the Publish Release step for tag releases because the gh CLI invocation passes invalid arguments when creating or editing the GitHub release. Restore successful release publication for tagged builds without changing unrelated release packaging behavior.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Tagged Release workflow completes the Publish Release step without gh CLI argument errors.
-- [x] #2 Release workflow still creates or updates the GitHub release as a non-prerelease for normal version tags.
-- [x] #3 A regression check covers the publish command shape or workflow behavior that caused this failure.
-- [x] #4 Any release workflow behavior change is documented in repository docs or workflow comments if needed.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-1. Add a targeted regression test for .github/workflows/release.yml that fails if the publish step passes an argument to the gh --prerelease boolean flag or otherwise omits explicit non-prerelease behavior.
-2. Run the targeted test to confirm the current workflow fails for the expected reason.
-3. Patch the Publish Release step in .github/workflows/release.yml to remove the invalid gh CLI usage while preserving non-prerelease release creation/update behavior.
-4. Re-run the targeted regression test and any relevant lightweight verification, then record results in task notes.
-<!-- SECTION:PLAN:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-Identified root cause from GitHub Actions run 22812335927: Publish Release failed with `accepts 1 arg(s), received 2` because the workflow passed a value to gh's boolean prerelease flag.
-
-Added a workflow comment clarifying that omitting the prerelease flag keeps normal releases as non-prerelease releases.
-
-Added src/release-workflow.test.ts and wired it into `bun run test:fast` so CI catches the invalid workflow shape before the next tag.
-
-Verification: `bun test src/release-workflow.test.ts`, `bun run typecheck`, and `bun run test:fast` all passed locally.
-
-Code-review pass found no issues; remaining caveat is that prerelease tag semantics are still not modeled for tags like `v1.0.0-beta.1`, which is outside this fix scope.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Fixed the GitHub Actions release publish step so tagged releases no longer fail on invalid gh CLI usage. The workflow now omits the prerelease flag when creating or editing normal releases, which preserves existing non-prerelease behavior and avoids the `accepts 1 arg(s), received 2` failure seen in run 22812335927.
-
-Added a small regression test that reads `.github/workflows/release.yml` and asserts the publish step does not set the prerelease flag, then included that test in `bun run test:fast` so the main verification lane catches this class of workflow regression before the next release.
-
-Validation run locally: `bun test src/release-workflow.test.ts`, `bun run typecheck`, and `bun run test:fast`. Residual risk: prerelease-tag semantics remain unchanged for tags such as `v1.0.0-beta.1`; this fix is intentionally scoped to restoring normal tagged release publication.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-70 - Overlay-runtime-refactor-remove-invisible-mode-and-bind-visible-overlay-to-mpv-subtitles.md

@@ -1,51 +0,0 @@
----
-id: TASK-70
-title: >-
-  Overlay runtime refactor: remove invisible mode and bind visible overlay to
-  mpv subtitles
-status: Done
-assignee: []
-created_date: '2026-02-28 02:38'
-updated_date: '2026-02-28 22:36'
-labels: []
-dependencies: []
-references:
-  - 'commit:a14c9da'
-  - 'commit:74554a3'
-  - 'commit:75442a4'
-  - 'commit:dde51f8'
-  - 'commit:9e4e588'
-  - src/main/overlay-runtime.ts
-  - src/main/runtime/overlay-mpv-sub-visibility.ts
-  - src/renderer/renderer.ts
-  - docs/plans/2026-02-26-secondary-subtitles-main-overlay.md
-priority: medium
-ordinal: 1000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Scope: Branch-only commits main..HEAD on refactor-overlay (a14c9da through 9e4e588) rebuilt overlay behavior around visible overlay mode and removed legacy invisible overlay paths.
-
-Delivered behavior:
-
-- Removed renderer invisible overlay layout/offset helpers and main hover-highlight runtime code paths.
-- Added explicit overlay-to-mpv subtitle visibility synchronization so visible overlay state controls primary subtitle visibility consistently.
-- Hardened overlay runtime/bootstrap lifecycle around modal fallback open state and bridge send path edge cases.
-- Updated plugin/config/docs defaults to reflect visible-overlay-first behavior and subtitle binding controls.
-
-Risk/impact context:
-
-- Large cross-layer refactor touching runtime wiring, renderer event handling, and plugin behavior.
-- Regression coverage added/updated for overlay runtime, mpv protocol handling, renderer cleanup, and subtitle rendering paths.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Completed and validated in branch commit set before merge. Refactor reduces dead overlay modes, centralizes subtitle visibility behavior, and documents new defaults/constraints.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-71 - Anki-integration-add-local-AnkiConnect-proxy-transport-for-push-based-auto-enrichment.md

@@ -1,58 +0,0 @@
----
-id: TASK-71
-title: >-
-  Anki integration: add local AnkiConnect proxy transport for push-based
-  auto-enrichment
-status: Done
-assignee: []
-created_date: '2026-02-28 02:38'
-updated_date: '2026-03-04 13:55'
-labels: []
-dependencies: []
-references:
-  - src/anki-integration/anki-connect-proxy.ts
-  - src/anki-integration/anki-connect-proxy.test.ts
-  - src/anki-integration.ts
-  - src/config/resolve/anki-connect.ts
-  - src/core/services/tokenizer/yomitan-parser-runtime.ts
-  - src/core/services/tokenizer/yomitan-parser-runtime.test.ts
-  - docs/anki-integration.md
-  - config.example.jsonc
-priority: medium
-ordinal: 2000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Scope: Current unmerged working-tree changes implement an optional local AnkiConnect-compatible proxy and transport switching for card enrichment.
-
-Delivered behavior:
-
-- Added proxy server that forwards AnkiConnect requests and enqueues addNote/addNotes note IDs for post-create enrichment, with de-duplication and loop-configuration protection.
-- Added follow-up response-shape compatibility handling so proxy enqueue works for both envelope (`{result,error}`) and bare JSON payloads, including `multi` variants.
-- Added config schema/defaults/resolution for ankiConnect.proxy (enabled, host, port, upstreamUrl) with validation warnings and fallback behavior.
-- Runtime now supports transport switching (polling vs proxy) and restarts transport when runtime config patches change transport keys.
-- Added Yomitan default-profile server sync helper to keep bundled parser profile aligned with configured Anki endpoint.
-- Updated user docs/config examples for proxy mode setup, troubleshooting, and mining workflow behavior.
-
-Risk/impact context:
-
-- New network surface on local host/port; correctness depends on safe proxy upstream configuration and robust response handling.
-- Tests added for proxy queue behavior, config resolution, and parser sync routines.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Completed implementation in branch working tree; ready to merge once local changes are committed and test gate passes.
-
-Follow-up fix (2026-03-04):
-
-- Updated bundled Yomitan server-sync behavior to target `profileCurrent` instead of hardcoded `profiles[0]`.
-- Added proxy-mode force override so bundled Yomitan always points at SubMiner proxy URL when `ankiConnect.proxy.enabled=true`; this ensures mined cards pass through proxy and trigger auto-enrichment.
-- Added regression tests for blocked existing-server case and force-override injection path.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-72 - macOS-config-validation-UX-show-full-warning-details-in-native-dialog.md

@@ -1,42 +0,0 @@
----
-id: TASK-72
-title: 'macOS config validation UX: show full warning details in native dialog'
-status: Done
-assignee: []
-created_date: '2026-02-28 02:38'
-updated_date: '2026-02-28 22:36'
-labels: []
-dependencies: []
-references:
-  - 'commit:cc2f9ef'
-  - src/main/config-validation.ts
-  - src/main/runtime/startup-config.ts
-  - docs/configuration.md
-priority: low
-ordinal: 3000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Scope: Commit cc2f9ef improves startup config-warning visibility on macOS by ensuring full details are surfaced in the native UI path and reflected in docs.
-
-Delivered behavior:
-
-- Config validation/runtime wiring updated so macOS users can access complete warning details instead of truncated notification-only text.
-- Added/updated tests around config validation and startup config warning flows.
-- Updated configuration docs to clarify platform-specific warning presentation behavior.
-
-Risk/impact context:
-
-- Low runtime risk; primarily user-facing diagnostics clarity improvement.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Completed small follow-up fix to reduce config-debug friction on macOS.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-73 - MPV-plugin-split-into-modules-and-optimize-startup-command-runtime.md

@@ -1,84 +0,0 @@
----
-id: TASK-73
-title: 'MPV plugin: split into modules and optimize startup/command runtime'
-status: Done
-assignee: []
-created_date: '2026-02-28 20:50'
-updated_date: '2026-02-28 22:36'
-labels: []
-dependencies: []
-references:
-  - plugin/subminer/main.lua
-  - plugin/subminer/bootstrap.lua
-  - plugin/subminer/process.lua
-  - plugin/subminer/aniskip.lua
-  - plugin/subminer/environment.lua
-  - plugin/subminer/lifecycle.lua
-  - plugin/subminer/messages.lua
-  - plugin/subminer/ui.lua
-  - plugin/subminer/hover.lua
-  - plugin/subminer/options.lua
-  - plugin/subminer/state.lua
-  - plugin/subminer.conf
-  - scripts/test-plugin-start-gate.lua
-  - scripts/test-plugin-process-start-retries.lua
-  - launcher/commands/playback-command.ts
-  - launcher/mpv.ts
-  - launcher/mpv.test.ts
-  - launcher/smoke.e2e.test.ts
-  - Makefile
-  - package.json
-  - docs/mpv-plugin.md
-  - docs/installation.md
-  - docs/architecture.md
-  - README.md
-priority: medium
-ordinal: 4000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Scope: Replace monolithic `plugin/subminer.lua` with modular plugin runtime; optimize command execution paths; align install/docs/tests; fix launcher smoke instability.
-
-Delivered behavior:
-
-- Full plugin cutover to `plugin/subminer/main.lua` + module directory (no runtime compatibility shim with old monolith file).
-- Process/control command path moved toward async subprocess usage for non-start actions (`stop`, `toggle`, `settings`, restart stop leg), reducing synchronous blocking in mpv script runtime.
-- AniSkip path guarded: lookup runs only in SubMiner context (launcher metadata, explicit script-message refresh, or detected running app), instead of every opened file.
-- AniSkip lookup pipeline moved to async subprocess calls (no sync `ps`/`curl` on `file-loaded`) with deferred fetch after auto-start and session-level MAL/title/payload caching.
-- Startup/runtime loading updated with lazy module initialization via bootstrap proxies.
-- Plugin install flow updated to copy `plugin/subminer/` directory and remove legacy `~/.config/mpv/scripts/subminer.lua` file.
-- Added plugin gate script wiring to package scripts (`test:plugin:src`) and launcher test flow.
-- Smoke tests stabilized across sandbox environments where UNIX socket bind can return `EPERM` while preserving normal-path assertions.
-- Playback command cleanup race fixed when mpv exits before exit-listener registration.
-
-Risk/impact context:
-
-- mpv plugin loading path changed from single-file to module directory; packaging/install paths must stay consistent with release assets.
-- Async control/AniSkip path changes reduce blocking but can surface timing differences; regression checks added for cold start, file-load gating, and explicit refresh behavior.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-AniSkip gate/async update delivered in plugin runtime:
-
-- `plugin/subminer/lifecycle.lua`: deferred AniSkip fetch and overlay-start trigger.
-- `plugin/subminer/aniskip.lua`: async lookup pipeline + context guard + session caches.
-- `plugin/subminer/environment.lua`: async app-running detection with short cache.
-- `plugin/subminer/messages.lua`: explicit script-message trigger wiring.
-
-Regression coverage updated:
-
-- `scripts/test-plugin-start-gate.lua` now verifies:
-  - no sync `ps`/`curl` on non-context file load
-  - no AniSkip network lookup on non-context file load
-  - script-message refresh forces async AniSkip lookup
-
-Validation run:
-
-- `bun run test:plugin:src` pass.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-74 - Startup-warmups-configurable-warmup-vs-defer-with-low-power-mode.md

@@ -1,76 +0,0 @@
----
-id: TASK-74
-title: 'Startup warmups: configurable warmup vs defer with low-power mode'
-status: Done
-assignee: []
-created_date: '2026-02-27 21:05'
-updated_date: '2026-03-01 04:14'
-labels: []
-dependencies: []
-references:
-  - src/types.ts
-  - src/config/definitions/defaults-core.ts
-  - src/config/definitions/options-core.ts
-  - src/config/definitions/template-sections.ts
-  - src/config/resolve/core-domains.ts
-  - src/main/runtime/startup-warmups.ts
-  - src/main/runtime/startup-warmups-main-deps.ts
-  - src/main/runtime/composers/mpv-runtime-composer.ts
-  - src/core/services/startup.ts
-  - src/main.ts
-  - src/config/config.test.ts
-  - src/main/runtime/startup-warmups.test.ts
-  - src/main/runtime/startup-warmups-main-deps.test.ts
-  - src/core/services/app-ready.test.ts
-priority: medium
-ordinal: 7000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add startup warmup controls to allow per-integration warmup or deferred first-use loading.
-
-Scope:
-
-- New config section `startupWarmups` with toggles for `mecab`, `yomitanExtension`, `subtitleDictionaries`, and `jellyfinRemoteSession`.
-- New `startupWarmups.lowPowerMode` policy: defer everything except Yomitan extension.
-- Keep default behavior as full warmup.
-- Ensure deferred integrations lazy-load on first real usage path.
-- Add test coverage for config parsing/defaults and warmup scheduling behavior.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented:
-
-- Added `startupWarmups` to config types/defaults/options/template/resolve.
-- Warmup scheduler now uses per-integration gating functions.
-- Low-power mode now defers MeCab, subtitle dictionaries, and Jellyfin remote session warmups while still warming Yomitan extension.
-- Tokenization path guarantees lazy first-use init for deferred dependencies (Yomitan extension, MeCab when missing, subtitle dictionaries).
-- Added/updated tests across config and runtime warmup modules.
-
-Validation:
-
-- `bun run test:config:src`
-- `bun run test:core:src`
-- `tsc --noEmit`
-
-Follow-up updates:
-
-- Startup now triggers warmups earlier in app-ready flow (right after config validation/log-level setup) instead of waiting for initial args/overlay actions. Goal: tokenization warmup is already done or mostly done by first visible-subs toggle.
-- Tokenization warmup scheduling consolidated as `subtitle-tokenization` stage; when enabled by toggles, it runs Yomitan extension first, then MeCab/dictionary warmups.
-- Added per-stage debug logs for warmup progress and skip reasons:
-  - `stage start/ready: yomitan-extension`
-  - `stage start/ready: mecab`
-  - `stage start/ready: subtitle-dictionaries`
-  - `stage start/ready: jellyfin-remote-session`
-  - `stage skipped: jellyfin-remote-session (disabled|auto-connect off)`
-- Added regression tests for stage-level logging and earlier startup ordering:
-  - `src/main/runtime/startup-warmups.test.ts`
-  - `src/main/runtime/startup-warmups-main-deps.test.ts`
-  - `src/core/services/app-ready.test.ts`
-  <!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-75 - Tokenizer-configurable-POS-exclusions-for-N1-and-frequency-annotations.md

@@ -1,41 +0,0 @@
----
-id: TASK-75
-title: 'Tokenizer: configurable POS exclusions for N+1 and frequency annotations'
-status: Done
-assignee: []
-created_date: '2026-03-01 01:23'
-updated_date: '2026-03-01 04:14'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 6000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-N+1 and frequency highlighting should ignore non-learning tokens (e.g., particles/auxiliary forms) based on MeCab POS1 tags, while remaining user-configurable.
-
-Problem example: for subtitle phrase containing になれば, the highlighted N+1 target should not be the non-useful inflection/token piece when POS indicates an excluded class.
-
-Implement configurable exclusion defaults with add/remove overrides so users can tune behavior without code changes.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Default exclusion set omits non-useful POS1 classes from both N+1 candidate selection and frequency highlighting.
-- [x] #2 Users can add extra POS1 exclusions and remove defaults via config.
-- [x] #3 Tokenizer/annotation tests cover default behavior and config add/remove overrides.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented configurable annotation POS exclusions with defaults+add/remove for both MeCab POS1 and POS2, wired to N+1 candidate selection and frequency highlighting. Added POS2 default exclusion (非自立), expanded POS1 defaults for function words, added Yomitan->MeCab enrichment to carry pos2/pos3 metadata, updated config docs/examples, and added regression tests including になれば case.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-76 - Tokenizer-remove-POS-exclusion-config-surface-and-keep-hardcoded-defaults.md

@@ -1,39 +0,0 @@
----
-id: TASK-76
-title: 'Tokenizer: remove POS exclusion config surface and keep hardcoded defaults'
-status: Done
-assignee: []
-created_date: '2026-03-01 02:45'
-updated_date: '2026-03-01 04:14'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 5000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Remove user-facing config keys for annotation POS exclusions. Keep N+1/frequency POS exclusion behavior as built-in defaults with no config required.
-
-Scope: remove config parsing/registry/docs/example for annotationFilters.pos1Exclusions/pos2Exclusions while preserving runtime filtering behavior.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 No user-facing config option exists for annotation POS exclusions.
-- [x] #2 Runtime N+1/frequency exclusion behavior remains active via built-in defaults.
-- [x] #3 Config/docs/example/tests updated accordingly.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Removed user-facing subtitleStyle.annotationFilters POS exclusion configuration (schema/resolver/options/docs/example). POS-based N+1/frequency filtering now always uses built-in defaults in runtime. Preserved robust exclusion behavior including merged-token overlap POS handling and N+1-only MeCab enrichment path.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-77 - Subtitle-hover-auto-pause-config-and-runtime-behavior.md

@@ -1,53 +0,0 @@
----
-id: TASK-77
-title: 'Subtitle hover: auto-pause playback with config toggle'
-status: Done
-assignee: []
-created_date: '2026-02-28 22:43'
-updated_date: '2026-03-04 12:07'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 8000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add a user-facing subtitle config option to pause mpv playback when the cursor hovers subtitle text and resume playback when the cursor leaves.
-
-Scope:
-
-- New config key: `subtitleStyle.autoPauseVideoOnHover`.
-- Default should be enabled.
-- Hover pause/resume must not unpause if playback was already paused before hover.
-- Docs/examples/tests updated.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 `subtitleStyle.autoPauseVideoOnHover` exists and defaults to `true`.
-- [x] #2 Overlay pauses playback on subtitle hover and resumes on leave only when hover-triggered pause occurred.
-- [x] #3 Main/renderer IPC exposes pause-state query for safe hover behavior.
-- [x] #4 Config docs/examples and user docs/readme mention the new behavior and toggle.
-- [x] #5 Regression tests cover config parsing/validation and hover behavior edge cases.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented `subtitleStyle.autoPauseVideoOnHover` with default `true`, wired through config defaults/resolution/types, renderer state/style, and mouse hover handlers. Added playback pause-state IPC (`getPlaybackPaused`) to avoid false resume when media was already paused. Added renderer hover behavior tests (including race/cancel case) and config/resolve tests. Updated config examples and docs (`README`, usage, shortcuts, mining workflow, configuration) to document default hover pause/resume behavior and disable path.
-
-Follow-up adjustments (2026-03-04):
-
-- Hover pause now resumes immediately when leaving subtitle text (no Yomitan-popup hover retention).
-- Added `subtitleStyle.autoPauseVideoOnYomitanPopup` (default `false`) to optionally keep playback paused while Yomitan popup is open, with auto-resume on close only when SubMiner initiated the popup pause.
-- Yomitan popup control keybinds added while popup is open: `J/K` scroll, `M` mine, `P` audio play, `[` previous audio variant, `]` next audio variant (within selected source).
-- Extension copy drift detection widened so popup runtime changes are reliably re-copied on launch (`popup.js`, `popup-main.js`, `display.js`, `display-audio.js`).
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-78 - Launcher-and-mpv-plugin-auto-start-pause-until-ready-and-single-start-guard.md

@@ -1,55 +0,0 @@
----
-id: TASK-78
-title: 'Launcher + mpv plugin: auto-start visible overlay pause-until-ready and single-start guard'
-status: Done
-assignee: []
-created_date: '2026-02-28 22:45'
-updated_date: '2026-02-28 22:45'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 9000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add startup gating behavior for wrapper + mpv plugin flow so playback starts paused when visible overlay auto-start is enabled, then auto-resumes only after subtitle tokenization is ready.
-
-Scope:
-
-- Plugin option `auto_start_pause_until_ready` (default `yes`).
-- Launcher reads plugin runtime config and starts mpv paused when `auto_start=yes`, `auto_start_visible_overlay=yes`, and `auto_start_pause_until_ready=yes`.
-- Main process signals readiness via mpv script message after tokenized subtitle delivery.
-- Prevent duplicate auto-start attempts from showing `SubMiner already running` OSD.
-- Keep startup/loading OSD messaging visible and update docs/tests.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Launcher reads `auto_start`, `auto_start_visible_overlay`, and `auto_start_pause_until_ready` from `subminer.conf` and starts mpv with `--pause=yes` when all are enabled.
-- [x] #2 Plugin pauses on eligible auto-start and resumes only on readiness signal or timeout fallback.
-- [x] #3 Main process emits `script-message subminer-autoplay-ready` after subtitle tokenization is ready.
-- [x] #4 Auto-start duplicate triggers are idempotent (no duplicate `--start` behavior and no spurious `Already running` OSD for auto-start path).
-- [x] #5 Docs and regression tests cover defaults, startup gating behavior, and duplicate-start suppression.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented startup pause gate across launcher/plugin/main runtime:
-
-- Added plugin runtime config parsing in launcher (`auto_start`, `auto_start_visible_overlay`, `auto_start_pause_until_ready`) and mpv start-paused behavior for eligible runs.
-- Added plugin auto-play gate state, timeout fallback, and readiness release via `subminer-autoplay-ready` script message.
-- Added main-process readiness signaling after tokenization delivery, including unpause fallback command path.
-- Split auto-start visibility control into separate control commands and added duplicate auto-start idempotency guard to suppress repeated auto-start `Already running` noise.
-- Updated plugin defaults to enabled (`auto_start=yes`, `auto_start_visible_overlay=yes`, `auto_start_pause_until_ready=yes`) and refreshed docs (`README`, usage, launcher, installation, plugin/config docs).
-- Added/updated regression coverage (`scripts/test-plugin-start-gate.lua`, launcher smoke/unit tests) validating paused startup, readiness resume, and duplicate-start suppression.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-79 - Jimaku-modal-auto-close-after-successful-subtitle-load.md

@@ -1,50 +0,0 @@
----
-id: TASK-79
-title: 'Jimaku modal: auto-close after successful subtitle load'
-status: Done
-assignee: []
-created_date: '2026-03-01 13:52'
-updated_date: '2026-03-01 14:06'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 10000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Fix Jimaku modal UX so selecting a subtitle file closes the modal automatically once subtitle download+load succeeds.
-
-Current behavior:
-
-- Subtitle file downloads and loads into mpv.
-- Jimaku modal remains open until manual close.
-
-Expected behavior:
-
-- On successful `jimakuDownloadFile` result, close modal immediately.
-- Keep error behavior unchanged (stay open + show error).
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Successful subtitle file selection/download in Jimaku closes modal automatically.
-- [x] #2 Existing error path keeps modal open and shows error.
-- [x] #3 Regression test covers success auto-close behavior.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Fixed renderer Jimaku success flow to close modal immediately after successful `jimakuDownloadFile` result. Added regression test (`src/renderer/modals/jimaku.test.ts`) that reproduces keyboard file-selection success path and asserts modal close state + `notifyOverlayModalClosed('jimaku')` emission. Kept failure path unchanged.
-
-Also wired new test into `test:core:src` and `test:core:dist` package scripts.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-80 - Jimaku-download-rename-subtitle-to-match-current-video.md

@@ -1,50 +0,0 @@
----
-id: TASK-80
-title: 'Jimaku download: rename subtitle to current video basename'
-status: Done
-assignee: []
-created_date: '2026-03-01 14:17'
-updated_date: '2026-03-01 14:19'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 11000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-When user selects a Jimaku subtitle, save subtitle with filename derived from currently playing media filename instead of Jimaku release filename.
-
-Example:
-
-- Current media: `anime.mkv`
-- Downloaded subtitle extension: `.srt`
-- Saved subtitle path: `anime.ja.srt`
-
-Scope:
-
-- Apply in Jimaku download IPC path before writing file.
-- Preserve collision-avoidance behavior (suffix with jimaku entry id/counter when target exists).
-- Keep mpv load flow unchanged except using renamed path.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Jimaku subtitle destination name uses current media basename plus `.ja` and subtitle extension.
-- [x] #2 Existing duplicate filename conflict handling still works.
-- [x] #3 Regression tests cover renamed destination path behavior.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Jimaku download path generation now derives subtitle filename from currently playing media basename and keeps subtitle extension from Jimaku file (`anime.mkv` + `.srt` => `anime.ja.srt`). Added pure helper `buildJimakuSubtitleFilenameFromMediaPath` and routed IPC download flow through it before existing duplicate-path conflict handling. Added regression tests for local path, missing extension fallback, and remote URL media paths.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-81 - Tokenization-performance-disable-yomitan-mecab-and-persistent-local-mecab.md

@@ -1,58 +0,0 @@
----
-id: TASK-81
-title: 'Tokenization performance: disable Yomitan MeCab parser, gate local MeCab init, and add persistent MeCab process'
-status: Done
-assignee: []
-created_date: '2026-03-02 07:44'
-updated_date: '2026-03-02 20:44'
-labels: []
-dependencies: []
-priority: high
-ordinal: 9001
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Reduce subtitle annotation latency by:
-
-- disabling Yomitan-side MeCab parser requests (`useMecabParser=false`);
-- initializing local MeCab only when POS-dependent annotations are enabled (N+1 / JLPT / frequency);
-- replacing per-line local MeCab process spawning with a persistent parser process that auto-shuts down after idle time and restarts on demand.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Yomitan parse requests disable MeCab parser path.
-- [x] #2 MeCab warmup/init is skipped when all POS-dependent annotation toggles are off.
-- [x] #3 Local MeCab tokenizer uses persistent process across subtitle lines.
-- [x] #4 Persistent MeCab process auto-shuts down after idle timeout and restarts on next tokenize activity.
-- [x] #5 Tests cover parser flag, warmup gating, and persistent MeCab lifecycle behavior.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented tokenizer latency optimizations:
-
-- switched Yomitan parse requests to `useMecabParser: false`;
-- added annotation-aware MeCab initialization gating in runtime warmup flow;
-- added persistent local MeCab process (default idle shutdown: 30s) with queued requests, retry-on-process-end, idle auto-shutdown, and automatic restart on new work;
-- added regression tests for Yomitan parse flag, MeCab warmup gating, and persistent/idle lifecycle behavior;
-- fixed tokenization warmup gate so first-use warmup completion is sticky (`tokenizationWarmupCompleted`) and sequential `tokenizeSubtitle` calls no longer re-run Yomitan/dictionary warmup path;
-- added regression coverage in `src/main/runtime/composers/mpv-runtime-composer.test.ts` for sequential tokenize calls (`warmup` side effects run once);
-- post-review critical fix: treat Yomitan default-profile Anki server sync `no-change` as successful check, so `lastSyncedYomitanAnkiServer` is cached and expensive sync checks do not repeat on every subtitle line;
-- added regression assertion in `src/core/services/tokenizer/yomitan-parser-runtime.test.ts` for `updated: false` path returning sync success;
-- post-review performance fix: refactored POS enrichment to pre-index MeCab tokens by surface plus character-position overlap index, replacing repeated active-candidate filtering/full-scan behavior with direct overlap candidate lookup per token;
-- added regression tests in `src/core/services/tokenizer/parser-enrichment-stage.test.ts` for repeated distant-token scan access and repeated active-candidate filter scans; both fail on scan-based behavior and pass with indexed lookup;
-- post-review startup fix: moved JLPT/frequency dictionary initialization from synchronous FS APIs to async `fs/promises` path inspection/read and cooperative chunked entry processing to reduce main-thread stall risk during cold start;
-- post-review first-line latency fix: decoupled tokenization warmup gating so first `tokenizeSubtitle` only waits on Yomitan extension readiness, while MeCab check + dictionary prewarm continue in parallel background warmups;
-- validated with targeted tests and `tsc --noEmit`.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-82 - Subtitle-frequency-highlighting-fixes-for-noisy-readings-and-known-token-color-priority.md

@@ -1,60 +0,0 @@
----
-id: TASK-82
-title: 'Subtitle frequency highlighting: fix noisy Yomitan readings and restore known/N+1 color priority'
-status: Done
-assignee: []
-created_date: '2026-03-02 20:10'
-updated_date: '2026-03-02 01:44'
-labels: []
-dependencies: []
-priority: high
-ordinal: 9002
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Address frequency-highlighting regressions:
-
-- tokens like `断じて` missed rank assignment when Yomitan merged-token reading was truncated/noisy;
-- known/N+1 tokens were incorrectly colored by frequency color instead of known/N+1 color.
-
-Expected behavior:
-
-- known/N+1 color always wins;
-- if token is frequent and within `topX`, frequency rank label can still appear on hover/metadata.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Frequency lookup succeeds for noisy/truncated merged-token readings via robust fallback behavior.
-- [x] #2 Merged-token reading normalization restores missing kana suffixes where safe (`headword === surface` path).
-- [x] #3 Known/N+1 tokens keep known/N+1 color classes; frequency color class does not override them.
-- [x] #4 Frequency rank hover label remains available for in-range frequent tokens, including known/N+1.
-- [x] #5 Regression tests added for tokenizer and renderer behavior.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented and validated:
-
-- tokenizer now normalizes selected Yomitan merged-token readings by appending missing trailing kana suffixes when safe (`headword === surface`);
-- frequency lookup now does lazy fallback: requests `{term, reading}` first, and only requests `{term, reading: null}` for misses;
-- this removes eager `(term, null)` payload inflation on medium-frequency lines and reduces extension RPC payload/load;
-- renderer restored known/N+1 color priority over frequency class coloring;
-- frequency rank label display remains available for frequent known/N+1 tokens;
-- added regression tests covering noisy-reading fallback, lazy fallback-query behavior, and renderer class/label precedence.
-
-Related commits:
-
-- `17a417e` (`fix(subtitle): improve frequency highlight reliability`)
-- `79f37f3` (`fix(subtitle): prioritize known and n+1 colors over frequency`)
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-83 - Jellyfin-subtitle-delay-shift-to-adjacent-cue-without-seek-jumps.md

@@ -1,53 +0,0 @@
----
-id: TASK-83
-title: 'Jellyfin subtitle delay: shift to adjacent cue without seek jumps'
-status: Done
-assignee: []
-created_date: '2026-03-02 00:06'
-updated_date: '2026-03-02 00:06'
-labels: []
-dependencies: []
-priority: high
-ordinal: 9003
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add keybinding-friendly special commands that shift `sub-delay` to align current subtitle start with next/previous cue start, without `sub-seek` probing (avoid playback jump).
-
-Scope:
-
-- add special commands for next/previous line alignment;
-- compute delta from active subtitle cue timeline (external subtitle file/URL, including Jellyfin-delivered URLs);
-- apply `add sub-delay <delta>` and show OSD value;
-- keep existing proxy OSD behavior for direct `sub-delay` keybinding commands.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 New special commands exist for subtitle-delay shift to next/previous cue boundary.
-- [x] #2 Shift logic parses active external subtitle source timings (SRT/VTT/ASS) and computes delta from current `sub-start`.
-- [x] #3 Runtime applies delay shift without `sub-seek` and shows OSD feedback.
-- [x] #4 Direct `sub-delay` proxy commands also show OSD current value.
-- [x] #5 Tests added for cue parsing/shift behavior and IPC dispatch wiring.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented no-jump subtitle-delay alignment commands:
-
-- added `__sub-delay-next-line` and `__sub-delay-prev-line` special commands;
-- added `createShiftSubtitleDelayToAdjacentCueHandler` to parse cue start times from active external subtitle source and apply `add sub-delay` delta from current `sub-start`;
-- wired command handling through IPC runtime deps into main runtime;
-- retained/extended OSD proxy feedback for `sub-delay` keybindings;
-- updated configuration docs and added regression tests for subtitle-delay shift and IPC command routing.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-84 - Docs-Plausible-endpoint-uses-api-event-path.md

@@ -1,37 +0,0 @@
----
-id: TASK-84
-title: 'Docs Plausible endpoint uses /api/event path'
-status: Done
-assignee: []
-created_date: '2026-03-03 00:00'
-updated_date: '2026-03-03 00:00'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 12000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Fix VitePress docs Plausible tracker config to post to hosted worker API event endpoint instead of worker root URL.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Docs theme Plausible `endpoint` points to `https://worker.subminer.moe/api/event`.
-- [x] #2 Plausible docs test asserts `/api/event` endpoint path.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Updated docs Plausible tracker endpoint to `https://worker.subminer.moe/api/event` and updated regression test expectation accordingly.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-84 - Migrate-AniSkip-metadatalookup-orchestration-to-launcher-Electron.md

@@ -1,70 +0,0 @@
----
-id: TASK-84
-title: Migrate AniSkip metadata+lookup orchestration to launcher/Electron
-status: Done
-assignee:
-  - Codex
-created_date: '2026-03-03 08:31'
-updated_date: '2026-03-03 08:35'
-labels:
-  - enhancement
-  - aniskip
-  - launcher
-  - mpv-plugin
-dependencies: []
-references:
-  - launcher/aniskip-metadata.ts
-  - launcher/mpv.ts
-  - plugin/subminer/aniskip.lua
-  - plugin/subminer/options.lua
-  - plugin/subminer/state.lua
-  - plugin/subminer/lifecycle.lua
-  - plugin/subminer/messages.lua
-  - plugin/subminer.conf
-  - launcher/aniskip-metadata.test.ts
-documentation:
-  - docs/mpv-plugin.md
-  - launcher/aniskip-metadata.ts
-  - plugin/subminer/aniskip.lua
-  - docs/architecture.md
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Move AniSkip MAL/title-to-MAL lookup and intro payload resolution from mpv Lua to launcher Electron flow, while keeping mpv-side intro skip UX and chapter/chapter prompt behavior in plugin. Launcher should infer/analyze file metadata, fetch AniSkip payload when launching files, and pass resolved skip window via script options; plugin should trust launcher payload and fall back only when absent.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Launcher infers AniSkip metadata for file targets using existing guessit/fallback logic and performs AniSkip MAL + payload resolution during mpv startup.
-- [x] #2 Launcher injects script options containing resolved MAL id and intro window fields (or explicit lookup-failure status) into mpv startup.
-- [x] #3 Lua plugin consumes launcher-provided AniSkip intro data and skips all network lookups when payload is present.
-- [x] #4 Standalone mpv/plugin usage without launcher payload continues to function using existing async in-plugin lookup path.
-- [x] #5 Docs and defaults are updated to document new script-option contract.
-- [x] #6 Launcher tests cover payload generation contract and fallback behavior where metadata is unavailable.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-1. Add launcher-side AniSkip payload resolution helpers in launcher/aniskip-metadata.ts (MAL prefix lookup + AniSkip payload fetch + result normalization).
-2. Wire launcher/mpv.ts + buildSubminerScriptOpts to pass resolved AniSkip fields/mode in --script-opts for file playback.
-3. Update plugin/subminer/aniskip.lua plus options/state to consume injected payload: if intro_start/end present, apply immediately and skip network lookup; otherwise retain existing async behavior.
-4. Ensure fallback for standalone mpv usage remains intact for no-launcher/manual refresh.
-5. Add/update tests/docs/config references for new script-opt contract and edge cases.
-<!-- SECTION:PLAN:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Executed end-to-end migration so launcher resolves AniSkip title/MAL/payload before mpv start and injects it via --script-opts. Plugin now parses and consumes launcher payload (JSON/url/base64), applies OP intro from payload, tracks payload metadata in state, and keeps legacy async lookup path for non-launcher/absent payload playback. Added launcher config key aniskip_payload and updated launcher/aniskip-metadata tests for resolve/payload behavior and contract validation.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-85 - Add-launcher-dictionary-subcommand-and-initial-AniList-character-dictionary-zip-generation.md

@@ -1,50 +0,0 @@
----
-id: TASK-85
-title: >-
-  Add launcher dictionary subcommand and initial AniList character dictionary
-  zip generation
-status: Done
-assignee: []
-created_date: '2026-03-03 08:47'
-updated_date: '2026-03-03 08:57'
-labels: []
-dependencies: []
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Implement initial character dictionary flow: launcher `dictionary` subcommand, app `--dictionary` command, AniList media resolution from current playback, Yomitan zip generation to local file, and local cache to avoid repeated API fetches for same AniList id. Manual Yomitan import path only in this phase.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Launcher supports `dictionary` (and alias) and forwards to app command path.
-- [x] #2 App CLI accepts `--dictionary` and dispatches to dictionary runtime command.
-- [x] #3 Dictionary command resolves current anime to AniList id, generates Yomitan-compatible zip, and logs output path for manual load.
-- [x] #4 Generated dictionaries are cached by AniList id so repeated commands reuse existing zip when available.
-- [x] #5 Backlog task is updated with implementation notes and completion summary for this phase.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-Implemented launcher `dictionary`/`dict` subcommand parsing and normalized args flow (`launcher/config/cli-parser-builder.ts`, `launcher/config/args-normalizer.ts`, `launcher/types.ts`).
-
-Added launcher command dispatch (`launcher/commands/dictionary-command.ts`) and wired `launcher/main.ts` to forward `--dictionary` (plus non-default `--log-level`) to app binary.
-
-Added app CLI flag `--dictionary` in parser/help and startup routing (`src/cli/args.ts`, `src/cli/help.ts`).
-
-Added dictionary runtime service (`src/main/character-dictionary-runtime.ts`) that resolves AniList media id from current playback guess, fetches AniList character edges, builds Yomitan-compatible banks/index, writes zip, and caches by AniList id in user data.
-
-Threaded dictionary generation dependency through CLI runtime/context builders and `src/main.ts` context composition so command executes from launcher/app entrypoints.
-
-Added/updated tests for parser, command modules, launcher main forwarding, CLI command dispatch, and context/deps wiring. Updated docs for launcher/usage command lists to include dictionary subcommand.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Initial phase shipped: `subminer dictionary` now routes to `SubMiner.AppImage --dictionary`, generates a Yomitan-importable character dictionary zip for the current anime (AniList-based), logs zip output path for manual import, and reuses cached zips by AniList id to avoid repeated API fetches.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-85 - Remove-docs-plausible-analytics-integration.md

@@ -1,38 +0,0 @@
----
-id: TASK-85
-title: 'Remove docs Plausible analytics integration'
-status: Done
-assignee: []
-created_date: '2026-03-03 00:00'
-updated_date: '2026-03-03 00:00'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 12001
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Remove Plausible analytics integration from docs theme and dependency graph. Keep docs build/runtime analytics-free.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Docs theme no longer imports or initializes Plausible tracker.
-- [x] #2 `@plausible-analytics/tracker` removed from dependencies and lockfile.
-- [x] #3 Docs analytics test reflects absence of Plausible wiring.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Deleted Plausible runtime wiring from VitePress theme, removed tracker package via `bun remove`, and updated docs test to assert no Plausible integration remains.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-85.1 - Address-PR-14-character-dictionary-review-follow-ups.md

@@ -1,64 +0,0 @@
----
-id: TASK-85.1
-title: 'Address PR #14 character dictionary review follow-ups'
-status: Done
-assignee:
-  - codex
-created_date: '2026-03-06 07:48'
-updated_date: '2026-03-06 07:56'
-labels: []
-dependencies: []
-references:
-  - >-
-    /home/sudacode/projects/japanese/SubMiner/launcher/commands/dictionary-command.ts
-  - >-
-    /home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
-  - /home/sudacode/projects/japanese/SubMiner/launcher/types.ts
-documentation:
-  - 'https://docs.anilist.co/guide/rate-limiting'
-parent_task_id: TASK-85
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Apply the accepted follow-up fixes from Claude's PR review for the AniList character dictionary work: remove dead launcher code, deduplicate video extension handling where practical, and add explicit pacing for AniList character-page requests / character image downloads so the integration stays within AniList rate-limiting expectations.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Launcher dictionary command no longer contains unreachable dead code after the app handoff.
-- [x] #2 Character dictionary runtime no longer maintains a separate ad hoc video extension list when existing shared extension data can be reused safely.
-- [x] #3 Character dictionary generation spaces outbound AniList-related requests with explicit named delays, and tests cover the pacing behavior and unchanged command forwarding behavior.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-1. Add failing tests for dictionary command handoff semantics and dictionary runtime request pacing.
-2. Remove unreachable boolean return path from the launcher dictionary command while preserving call sites.
-3. Reuse the shared launcher video extension set inside the character dictionary runtime with extname normalization, then add named AniList pacing constants for page fetches and character image downloads.
-4. Run targeted tests, then broader relevant test slices, and update acceptance criteria / notes with the validated result.
-<!-- SECTION:PLAN:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-Added a shared `src/shared/video-extensions.ts` source and rewired both launcher/runtime consumers to remove the duplicated runtime extension list.
-
-Replaced the hardcoded AniList page sleep with a per-generation AniList request pacer (2000ms between API requests) plus 250ms spacing between character image download attempts, including failed image fetches.
-
-Hardened `runDictionaryCommand` so an unexpected return from the `never`-typed app handoff throws immediately instead of silently falling through.
-
-Validated with targeted and adjacent test slices plus `bun run tsc --noEmit`.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Removed the dead post-handoff return from the launcher dictionary command and replaced it with an explicit invariant error if the `never`-typed app handoff ever returns unexpectedly. Extracted video extension data into `src/shared/video-extensions.ts` so the launcher and character dictionary runtime share one source of truth.
-
-Adjusted character dictionary generation to use a per-run AniList request pacer with a conservative 2000ms delay between AniList API calls, and added 250ms spacing between character image download attempts so repeated image fetches are not bursty even when an image URL fails. Added regression coverage for the pacing behavior and the launcher handoff invariant.
-
-Validation: `bun test src/main/character-dictionary-runtime.test.ts`, `bun test launcher/commands/command-modules.test.ts`, `bun test launcher/main.test.ts launcher/parse-args.test.ts src/cli/args.test.ts src/core/services/cli-command.test.ts src/main/runtime/character-dictionary-auto-sync.test.ts`, `bun run tsc --noEmit`.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-86 - Renderer-keyboard-driven-Yomitan-lookup-mode-and-popup-key-forwarding.md

@@ -1,68 +0,0 @@
----
-id: TASK-86
-title: 'Renderer: keyboard-driven Yomitan lookup mode and popup key forwarding'
-status: Done
-assignee:
-  - Codex
-created_date: '2026-03-04 13:40'
-updated_date: '2026-03-05 11:30'
-labels:
-  - enhancement
-  - renderer
-  - yomitan
-dependencies:
-  - TASK-77
-references:
-  - src/renderer/handlers/keyboard.ts
-  - src/renderer/handlers/mouse.ts
-  - src/renderer/renderer.ts
-  - src/renderer/state.ts
-  - src/renderer/yomitan-popup.ts
-  - src/core/services/overlay-window.ts
-  - src/preload.ts
-  - src/shared/ipc/contracts.ts
-  - src/types.ts
-  - vendor/yomitan/js/app/frontend.js
-  - vendor/yomitan/js/app/popup.js
-  - vendor/yomitan/js/display/display.js
-  - vendor/yomitan/js/display/popup-main.js
-  - vendor/yomitan/js/display/display-audio.js
-documentation:
-  - README.md
-  - docs/usage.md
-  - docs/shortcuts.md
-priority: medium
-ordinal: 13000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add true keyboard-driven token lookup flow in overlay:
-
-- Toggle keyboard token-selection mode and navigate tokens by keyboard (`Arrow` + `HJKL`).
-- Toggle Yomitan lookup window for selected token via fixed accelerator (`Ctrl/Cmd+Y`) without requiring mouse click.
-- Preserve keyboard-only workflow while popup is open by forwarding popup keys (`J/K`, `M`, `P`, `[`, `]`) and restoring overlay focus on popup close.
-- Ensure selection styling and hover metadata tooltips (frequency/JLPT) work for keyboard-selected token.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Keyboard mode toggle exists and shows visual selection outline for active token.
-- [x] #2 Navigation works via arrows and vim keys while keyboard mode is enabled.
-- [x] #3 Lookup window toggles from selected token with `Ctrl/Cmd+Y`; close path restores overlay keyboard focus.
-- [x] #4 Popup-local controls work via keyboard forwarding (`J/K`, `M`, `P`, `[`, `]`), including mine action.
-- [x] #5 Frequency/JLPT hover tags render for keyboard-selected token.
-- [x] #6 Renderer/runtime tests cover new visibility/selection behavior, and docs are updated.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented keyboard-driven Yomitan workflow end-to-end in renderer + bundled Yomitan runtime bridge. Added overlay-level keyboard mode state, token selection sync, lookup toggle routing, popup command forwarding, and focus recovery after popup close. Follow-up fixes kept lookup open while moving between tokens, made popup-local `J/K` and `ArrowUp/ArrowDown` scroll work from overlay-owned focus with key repeat, skipped keyboard/token annotation flow for parser groups that have no dictionary-backed headword, and preserved paused playback when token navigation jumps across subtitle lines. Updated user docs/README to document the final shortcut behavior.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-86 - Require-target-path-for-launcher-dictionary-command-and-forward-dictionary-target-to-app-runtime.md

@@ -1,54 +0,0 @@
----
-id: TASK-86
-title: >-
-  Require target path for launcher dictionary command and forward dictionary
-  target to app runtime
-status: Done
-assignee: []
-created_date: '2026-03-03 09:22'
-updated_date: '2026-03-03 09:53'
-labels: []
-dependencies: []
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Change dictionary flow so launcher uses `subminer dictionary <file-or-directory>` and forwards target to app without playback launch. Keep direct app `--dictionary` behavior for in-session/mpv-triggered use, adding optional `--dictionary-target` path override.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Launcher `dictionary`/`dict` requires a target path argument and parses optional log level.
-- [x] #2 Launcher forwards target to app as `--dictionary-target <path>` together with `--dictionary`.
-- [x] #3 App CLI parses optional `--dictionary-target` and dictionary command passes it into dictionary runtime.
-- [x] #4 Dictionary runtime resolves explicit file/directory target for AniList guess flow; falls back to current playback when target is absent.
-- [x] #5 Docs/tests are updated for new launcher invocation syntax.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-Launcher dictionary subcommand now requires a positional target path (`subminer dictionary <path>` / `dict <path>`) via commander argument wiring in `launcher/config/cli-parser-builder.ts`.
-
-Added `dictionaryTarget` flow in launcher normalization/types and path validation (must be existing local file or directory) in `launcher/config/args-normalizer.ts`.
-
-Launcher dictionary command now forwards `--dictionary --dictionary-target <resolved-path>` to app binary in `launcher/commands/dictionary-command.ts`.
-
-App CLI now parses optional `--dictionary-target` in `src/cli/args.ts`; dictionary handler passes target through to runtime in `src/core/services/cli-command.ts`.
-
-Dictionary runtime now resolves explicit target inputs in `src/main/character-dictionary-runtime.ts`: file target uses file path/title; directory target selects first video file recursively (fallback to directory name), and still falls back to current playback when target is absent.
-
-Updated context/dependency pass-through for dictionary target argument (`src/main.ts`, `src/main/runtime/cli-command-context-main-deps.ts`).
-
-Updated tests/docs for new syntax and forwarding behavior (`launcher/main.test.ts`, `launcher/parse-args.test.ts`, `launcher/commands/command-modules.test.ts`, `src/cli/args.test.ts`, `src/cli/help.test.ts`, `docs/usage.md`, `docs/launcher-script.md`).
-
-Follow-up noise reduction: dictionary commands now opt into lightweight startup path by extending `shouldSkipHeavyStartup` in `src/main.ts` to include `initialArgs.dictionary`. This skips heavy app-ready initialization (mpv client creation/background warmups/overlay bootstrap) for dictionary CLI runs.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Launcher dictionary flow now uses explicit targets: run `subminer dictionary <file-or-directory>`. It forwards target to app and performs dictionary generation without depending on currently playing media. Direct app `--dictionary` remains available for in-session/mpv-triggered workflows, with optional `--dictionary-target` override support.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-87 - Codebase-health-harden-verification-and-retire-dead-architecture-identified-in-the-March-2026-review.md

@@ -1,79 +0,0 @@
----
-id: TASK-87
-title: >-
-  Codebase health: harden verification and retire dead architecture identified
-  in the March 2026 review
-status: In Progress
-assignee: []
-created_date: '2026-03-06 03:19'
-updated_date: '2026-03-06 11:11'
-labels:
-  - tech-debt
-  - tests
-  - maintainability
-milestone: m-0
-dependencies: []
-references:
-  - package.json
-  - README.md
-  - src/main.ts
-  - src/anki-integration.ts
-  - src/core/services/immersion-tracker-service.test.ts
-- src/translators/index.ts
-- src/subsync/engines.ts
-- src/subtitle/pipeline.ts
-  - backlog/tasks/task-87.5 - Dead-architecture-cleanup-delete-unused-registry-and-pipeline-modules-that-are-off-the-live-path.md
-documentation:
-  - docs/reports/2026-02-22-task-100-dead-code-report.md
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Track the remediation work from the March 6, 2026 code review. The review found that the default test gate only exercises 53 of 241 test files, the dedicated subtitle test lane is a no-op, SQLite-backed immersion tracking tests are conditionally skipped in the standard Bun run, src/main.ts still contains a large dead-symbol backlog, several registry/pipeline modules appear unreferenced from live execution paths, and src/anki-integration.ts remains an oversized orchestration file. This parent task should coordinate a safe sequence: improve verification first, then remove dead code and continue decomposition with good test coverage in place.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Child tasks are created for each remediation workstream with explicit dependencies and enough context for an isolated agent to execute them.
-- [ ] #2 The parent task records the recommended sequencing and parallelization strategy so replacement agents can resume without conversation history.
-- [ ] #3 Completion of the parent task leaves the repository with a materially more trustworthy test gate, less dead architecture, and clearer ownership boundaries for the main runtime and Anki integration surfaces.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-Recommended sequencing:
-
-1. Run TASK-87.1, TASK-87.2, TASK-87.3, and TASK-87.7 first. These are the safety-net and tooling tasks and can largely proceed in parallel.
-2. Start TASK-87.4 once TASK-87.1 lands so src/main.ts cleanup happens under a more trustworthy test matrix.
-3. Start TASK-87.5 after TASK-87.1 and TASK-87.2 so dead subsync/pipeline cleanup happens with stronger subtitle and runtime verification.
-4. Start TASK-87.6 after TASK-87.1 so Anki refactors happen with broader default coverage in place.
-5. Keep PRs focused: do not combine verification work with architectural cleanup unless a narrow dependency requires it.
-
-Parallelization guidance:
-
-- Wave 1 parallel: TASK-87.1, TASK-87.2, TASK-87.3, TASK-87.7
-- Wave 2 parallel: TASK-87.4, TASK-87.5, TASK-87.6
-
-Shared review context to restate in child tasks:
-
-- Standard test scripts currently reference only 53 unique test files out of 241 discovered test and type-test files under src/ and launcher/.
-- test:subtitle is currently a placeholder echo even though subtitle sync is a user-facing feature.
-- SQLite-backed immersion tracker tests are conditionally skipped in the standard Bun run.
-- src/main.ts trips many noUnusedLocals/noUnusedParameters diagnostics.
-- src/translators/index.ts, src/subsync/engines.ts, src/subtitle/pipeline.ts, src/tokenizers/index.ts, and src/token-mergers/index.ts appeared unreferenced during review and must be re-verified before deletion.
-<!-- SECTION:PLAN:END -->
-
-## Progress Notes
-
-- `TASK-87.5` is complete. The isolated dead registry/pipeline modules were re-verified as off the maintained runtime path and removed.
-- Live subtitle tokenization now owns the zero-width separator normalization that previously only existed in the dead subtitle pipeline path, so the cleanup did not drop that behavior.
-- Verification completed for the cleanup slice with `bun test src/core/services/tokenizer.test.ts`, `bun test src/dead-architecture-cleanup.test.ts`, `bun test src/core/services/subsync.test.ts src/subsync/utils.test.ts`, `bun run tsc`, and `bun run test:src`.
-- Remaining parent-task scope still includes the broader verification hardening, `src/main.ts` dead-symbol cleanup, and `src/anki-integration.ts` decomposition work tracked by the other child tasks.

backlog/tasks/task-87.1 - Testing-workflow-make-standard-test-commands-reflect-the-maintained-test-surface.md

@@ -1,68 +0,0 @@
----
-id: TASK-87.1
-title: >-
-  Testing workflow: make standard test commands reflect the maintained test
-  surface
-status: Done
-assignee:
-  - OpenCode
-created_date: '2026-03-06 03:19'
-updated_date: '2026-03-06 08:52'
-labels:
-  - tests
-  - maintainability
-milestone: m-0
-dependencies: []
-references:
-  - package.json
-  - src/main-entry-runtime.test.ts
-  - src/anki-integration/anki-connect-proxy.test.ts
-  - src/main/runtime/jellyfin-remote-playback.test.ts
-  - src/main/runtime/registry.test.ts
-documentation:
-  - docs/reports/2026-02-22-task-100-dead-code-report.md
-parent_task_id: TASK-87
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-The current package scripts hand-enumerate a small subset of test files, which leaves the standard green signal misleading. A local audit found 241 test/type-test files under src/ and launcher/, but only 53 unique files referenced by the standard package.json test scripts. This task should redesign the runnable test matrix so maintained tests are either executed by the standard commands or intentionally excluded through a documented rule, instead of silently drifting out of coverage.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 The repository has a documented and reproducible test matrix for standard development commands, including which suites belong in the default lane versus slower or environment-specific lanes.
-- [x] #2 The standard test entrypoints stop relying on a brittle hand-maintained allowlist for the currently covered unit and integration suites, or an explicit documented mechanism exists that prevents silent omission of new tests.
-- [x] #3 Representative tests that were previously outside the standard lane from src/main/runtime, src/anki-integration, and entry/runtime surfaces are executed by an automated command and included in the documented matrix.
-- [x] #4 Documentation for contributors explains which command to run for fast verification, full verification, and environment-specific verification.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-1. Update `package.json` to replace the current file-by-file test allowlists with a documented lane matrix: keep `test`/`test:fast` as the quick default lane, add `test:full` for the maintained source test surface, and add `test:env` for slower or environment-specific checks.
-2. Use directory-based discovery for maintained suites so new tests under stable surfaces such as `src/main`, `src/anki-integration`, and `launcher` are not silently omitted by default script maintenance.
-3. Split environment-specific verification into explicit commands for checks such as launcher smoke/plugin coverage and sqlite-gated tests, instead of leaving them undocumented or mixed into the default signal.
-4. Update `README.md` with a contributor-facing testing matrix that explains fast, full, and environment-specific verification, including any prerequisites or expected skip behavior.
-5. Verify the matrix by running representative targeted tests plus the documented lane commands, demonstrating that previously omitted entry/runtime, Anki integration, and main runtime tests now belong to automated commands.
-<!-- SECTION:PLAN:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-Reviewed task context via Backlog MCP plus repo audit. Current package.json test scripts still rely on hand-maintained file allowlists and omit large maintained areas including src/main/runtime, src/anki-integration, and src/main-entry-runtime.test.ts. Preparing an implementation plan and contributor-facing test matrix update before code changes.
-
-Saved detailed implementation plan to docs/plans/2026-03-06-testing-workflow-test-matrix.md and recorded the approved direction in the Backlog task before implementation.
-
-Implemented a lane-based test matrix. Added `scripts/run-test-lane.mjs` so Bun-managed `src/**` and launcher unit lanes discover files automatically while excluding a small explicit Node-only set instead of relying on large hand-maintained allowlists. Added `test:node:compat` for `ipc`, `anki-jimaku-ipc`, `overlay-manager`, `config-validation`, `startup-config`, and `registry` suites, kept `test:env` for launcher smoke/plugin plus SQLite-backed immersion checks, and updated `README.md` with the contributor-facing matrix and exclusions.
-
-Validated the new matrix with `bun run test:fast`, `bun run test:full`, `bun run test:env`, `bun run test:src`, `bun run test:launcher:unit:src`, `bun run test:node:compat`, and targeted `bun test src/core/services/anilist/anilist-updater.test.ts`. Representative previously omitted surfaces now run through automated commands: `src/main-entry-runtime.test.ts` via `test:fast`, `src/anki-integration/anki-connect-proxy.test.ts` via `test:fast`/`test:src`, and `src/main/runtime/registry.test.ts` via `test:node:compat`/`test:full`.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Reworked the repository test matrix so standard commands reflect the maintained test surface without relying on brittle file allowlists. Added automated Bun discovery lanes for Bun-compatible `src/**` and launcher unit suites, a documented Node compatibility lane for Electron/sqlite-sensitive tests, and updated the contributor docs with fast/full/environment-specific guidance plus explicit exclusions. Verified with `bun run test:fast`, `bun run test:full`, and `bun run test:env`, along with the component lanes and targeted regression coverage for the updated AniList guessit test seam.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-87.2 - Subtitle-sync-verification-replace-the-no-op-subtitle-lane-with-real-automated-coverage.md

@@ -1,84 +0,0 @@
----
-id: TASK-87.2
-title: >-
-  Subtitle sync verification: replace the no-op subtitle lane with real
-  automated coverage
-status: Done
-assignee:
-  - Kyle Yasuda
-created_date: '2026-03-06 03:19'
-updated_date: '2026-03-06 08:06'
-labels:
-  - tests
-  - subsync
-milestone: m-0
-dependencies: []
-references:
-  - package.json
-  - README.md
-  - src/core/services/subsync.ts
-  - src/core/services/subsync.test.ts
-  - src/subsync/utils.ts
-documentation:
-  - docs/reports/2026-02-22-task-100-dead-code-report.md
-parent_task_id: TASK-87
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-SubMiner advertises subtitle syncing with alass and ffsubsync, but the dedicated test:subtitle command currently does not run any tests. There is already lower-level coverage in src/core/services/subsync.test.ts, but the test matrix and contributor-facing commands do not reflect that reality. This task should replace the no-op lane with real verification, align scripts with the existing subsync test surface, and make the user-facing docs honest about how subtitle sync is verified.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 The test:subtitle entrypoint runs real automated verification instead of echoing a placeholder message.
-- [x] #2 The subtitle verification lane covers both alass and ffsubsync behavior, including at least one non-happy-path scenario relevant to current functionality.
-- [x] #3 Contributor-facing documentation points to the real subtitle verification command and no longer implies a dedicated test lane exists when it does not.
-- [x] #4 The resulting verification strategy integrates cleanly with the repository-wide test matrix without duplicating or hiding existing subsync coverage.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-Plan of record:
-
-1. Replace the placeholder package-script lane with a real `test:subtitle:src` command that runs the maintained subtitle-sync tests directly (`src/core/services/subsync.test.ts` and `src/subsync/utils.test.ts`), and point `test:subtitle` at that lane instead of build+echo behavior.
-2. Add one focused ffsubsync non-happy-path test in `src/core/services/subsync.test.ts` so the dedicated lane explicitly covers both engines plus failure propagation relevant to current functionality.
-3. Update `README.md` contributor guidance to name `bun run test:subtitle` as the subtitle verification command and explain that it reuses the maintained subsync tests already included in broader core coverage.
-4. Verify the final strategy by running `bun run test:subtitle` and `bun run test:core:src` so the dedicated lane stays aligned with the repository-wide matrix instead of creating a divergent hidden suite.
-
-Detailed execution plan saved at `docs/plans/2026-03-06-subtitle-sync-verification.md`.
-<!-- SECTION:PLAN:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-Reviewed task references and current subtitle verification surface. Existing coverage already lives in `src/core/services/subsync.test.ts` and `src/subsync/utils.test.ts`; `test:subtitle` is still a placeholder build+echo wrapper. The referenced report `docs/reports/2026-02-22-task-100-dead-code-report.md` is not present in the workspace, so planning used the task body plus repository state instead.
-
-Implementation plan written and saved to `docs/plans/2026-03-06-subtitle-sync-verification.md`. Proceeding with execution per the task request.
-
-Replaced the placeholder subtitle lane with `test:subtitle:src` in `package.json`, pointing `test:subtitle` directly at `src/core/services/subsync.test.ts` and `src/subsync/utils.test.ts` instead of build+echo behavior.
-
-Added explicit ffsubsync failure-path coverage in `src/core/services/subsync.test.ts`, asserting non-zero command failures surface detailed `ffsubsync synchronization failed` messaging alongside existing alass coverage.
-
-Updated `README.md` verification guidance to point contributors at `bun run test:subtitle` and explain that the lane reuses the maintained subsync tests already included in `bun run test:core`.
-
-Verification: `bun run test:subtitle` passed (15 tests across 2 files). `bun run test:core:src` also passed (373 pass, 6 skip, 0 fail), confirming the dedicated subtitle lane stays aligned with the broader matrix.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Implemented a real subtitle verification lane by replacing the placeholder `test:subtitle` build+echo flow with a source-level `test:subtitle:src` command that runs the maintained subtitle-sync tests directly from `src/core/services/subsync.test.ts` and `src/subsync/utils.test.ts`. This keeps subtitle verification explicit for contributors while still reusing the same maintained test surface already covered by `test:core`.
-
-Expanded subtitle-sync coverage with an explicit ffsubsync failure-path test so the dedicated lane now exercises both engines plus a user-visible non-happy path. Updated `README.md` to document `bun run test:subtitle` as the contributor-facing subtitle verification command and to explain its relationship to the broader core suite.
-
-Verification run:
-- `bun run test:subtitle`
-- `bun run test:core:src`
-
-Notes:
-- The task reference `docs/reports/2026-02-22-task-100-dead-code-report.md` was not present in the workspace during execution, so implementation used the task body and live repository state as the source of truth.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-87.3 - Immersion-tracking-verification-make-SQLite-backed-persistence-tests-visible-and-reproducible.md

@@ -1,75 +0,0 @@
----
-id: TASK-87.3
-title: >-
-  Immersion tracking verification: make SQLite-backed persistence tests visible
-  and reproducible
-status: Done
-assignee:
-  - Kyle Yasuda
-created_date: '2026-03-06 03:19'
-updated_date: '2026-03-06 08:20'
-labels:
-  - tests
-  - immersion-tracking
-milestone: m-0
-dependencies: []
-references:
-  - src/core/services/immersion-tracker-service.test.ts
-  - src/core/services/immersion-tracker/storage-session.test.ts
-  - src/core/services/immersion-tracker-service.ts
-  - package.json
-documentation:
-  - docs/reports/2026-02-22-task-100-dead-code-report.md
-parent_task_id: TASK-87
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-The immersion tracker is persistence-heavy, but its SQLite-backed tests are conditionally skipped in the standard Bun run when node:sqlite support is unavailable. That creates a blind spot around session finalization, telemetry persistence, and retention behavior. This task should establish a reliable automated verification path for the database-backed cases and make the prerequisite/runtime behavior explicit to contributors and CI.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Database-backed immersion tracking tests run in at least one documented automated command that is practical for contributors or CI to execute.
-- [x] #2 If the current runtime cannot execute the SQLite-backed tests, the repository exposes that limitation clearly instead of silently reporting a misleading green result.
-- [x] #3 Contributor-facing documentation explains how to run the immersion tracker verification lane and any environment prerequisites it depends on.
-- [x] #4 The resulting verification covers session persistence or finalization behavior that is not exercised by the pure seam tests alone.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-Implementation plan recorded in `docs/plans/2026-03-06-immersion-sqlite-verification.md`.
-
-1. Update `src/core/services/immersion-tracker-service.test.ts` and `src/core/services/immersion-tracker/storage-session.test.ts` so unsupported `node:sqlite` runtimes emit an explicit skip reason instead of a silent top-level skip alias.
-2. Add a dedicated `package.json` SQLite verification lane that runs both immersion persistence suites together under a runtime with `node:sqlite` support, likely via built `dist/**` tests executed by Node.
-3. Wire that lane into `.github/workflows/ci.yml` and `.github/workflows/release.yml` so automated verification includes a real DB-backed persistence/finalization check.
-4. Document the new command, prerequisites, and coverage in `README.md`, including the distinction between Bun's default lane and the reproducible SQLite lane.
-5. Validate the final lane by running the dedicated command and confirming it exercises persistence/finalization behavior beyond the seam-only tests.
-
-Execution adjustment: the reproducible lane uses `node --experimental-sqlite --test ...` because Node 22 exposes `node:sqlite` behind the experimental flag. Running that lane also exposed placeholder-count mismatches in `src/core/services/immersion-tracker/storage.ts`, so the final implementation includes a small SQL placeholder fix required for the new cross-runtime verification path.
-<!-- SECTION:PLAN:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-Confirmed Bun 1.3.5 lacks `node:test` `t.skip()` support, so explicit unsupported-runtime messaging is surfaced with file-level warnings while the SQLite-backed tests remain conditionally skipped.
-
-Added `test:immersion:sqlite:src`, `test:immersion:sqlite:dist`, and `test:immersion:sqlite` scripts; the source lane now prints explicit warnings when `node:sqlite` is unavailable, and the dist lane runs both SQLite-backed immersion suites under Node with `--experimental-sqlite`.
-
-Wired the dist SQLite lane into `.github/workflows/ci.yml` and `.github/workflows/release.yml` after the bundle build, with explicit `actions/setup-node@v4` provisioning for Node 22.12.0.
-
-Fixed SQL prepared-statement placeholder counts in `src/core/services/immersion-tracker/storage.ts`, which the new Node-backed SQLite lane surfaced immediately.
-
-Verification: `bun run test:immersion:sqlite:src` -> pass with explicit unsupported-runtime warnings and 10 skips under Bun 1.3.5; `bun run test:immersion:sqlite` -> pass with 14/14 tests under Node 22.12.0 + `--experimental-sqlite`.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Added an explicit SQLite-backed immersion verification lane and documented it so persistence-heavy coverage is no longer hidden behind Bun-only skips. `package.json` now exposes source and dist SQLite scripts, the source test files print actionable warnings when `node:sqlite` is unavailable, and `README.md` explains the dedicated contributor command plus its Node 22 `--experimental-sqlite` prerequisite.
-
-Automated verification now includes the new dist lane in both `.github/workflows/ci.yml` and `.github/workflows/release.yml` after build output is available. While wiring the reproducible Node lane, it exposed placeholder-count mismatches in `src/core/services/immersion-tracker/storage.ts`; fixing those placeholders makes the SQLite-backed persistence/finalization tests pass cross-runtime, covering session finalization, telemetry persistence, and storage-session write paths.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-87.4 - Runtime-composition-root-remove-dead-symbols-and-tighten-module-boundaries-in-src-main.ts.md

@@ -1,63 +0,0 @@
----
-id: TASK-87.4
-title: >-
-  Runtime composition root: remove dead symbols and tighten module boundaries in
-  src/main.ts
-status: Done
-assignee: []
-created_date: '2026-03-06 03:19'
-updated_date: '2026-03-06 18:10'
-labels:
-  - tech-debt
-  - runtime
-  - maintainability
-milestone: m-0
-dependencies:
-  - TASK-87.1
-references:
-  - src/main.ts
-  - src/main/runtime
-  - package.json
-documentation:
-  - docs/reports/2026-02-22-task-100-dead-code-report.md
-parent_task_id: TASK-87
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-A noUnusedLocals/noUnusedParameters compile pass reports a large concentration of dead imports and dead locals in src/main.ts. The file is also far beyond the repo’s preferred size guideline, which makes the runtime composition root difficult to review and easy to break. This task should remove confirmed dead symbols, continue extracting coherent slices where that improves readability, and leave the entrypoint materially easier to understand without changing behavior.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 src/main.ts no longer emits dead-symbol diagnostics under a noUnusedLocals/noUnusedParameters compile pass for the areas touched by this cleanup.
-- [x] #2 Unused imports, destructured values, and stale locals identified in the current composition root are removed or relocated without behavior changes.
-- [x] #3 The resulting composition root has clearer ownership boundaries for at least one runtime slice that is currently buried in the monolith.
-- [x] #4 Relevant runtime and startup verification commands pass after the cleanup, and any command changes are documented if needed.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-1. Re-run the noUnusedLocals/noUnusedParameters compile pass and capture the src/main.ts diagnostics cluster before editing.
-2. Remove dead imports, destructured values, and stale locals in small reviewable slices; extract a coherent helper/module only where that materially reduces coupling.
-3. Keep changes behavior-preserving and avoid mixing unrelated cleanup outside src/main.ts unless required to compile.
-4. Verify with the updated runtime/startup test commands from TASK-87.1 plus a noUnused compile pass.
-<!-- SECTION:PLAN:END -->
-
-## Completion Notes
-
-- Removed the dead import/destructure backlog from `src/main.ts` and deleted stale wrapper seams that no longer owned runtime behavior after the composer/runtime extractions.
-- Tightened module boundaries so the composition root depends on the composed/public runtime surfaces it actually uses instead of retaining unused lower-level domain factory symbols.
-- Cleared the remaining strict `noUnusedLocals`/`noUnusedParameters` failures in nearby touched files required for a clean repo-wide pass: `launcher/commands/playback-command.ts`, `src/anki-integration.ts`, `src/anki-integration/field-grouping-workflow.ts`, `src/core/services/tokenizer/yomitan-parser-runtime.test.ts`, and `src/main/runtime/composers/composer-contracts.type-test.ts`.
-- Verification:
-  - `bunx tsc --noEmit -p tsconfig.typecheck.json --noUnusedLocals --noUnusedParameters --pretty false`
-  - `bun run test:fast`
-- Commit: `e659b5d` (`refactor(runtime): remove dead symbols from composition roots`)

backlog/tasks/task-87.5 - Dead-architecture-cleanup-delete-unused-registry-and-pipeline-modules-that-are-off-the-live-path.md

@@ -1,64 +0,0 @@
----
-id: TASK-87.5
-title: >-
-  Dead architecture cleanup: delete unused registry and pipeline modules that
-  are off the live path
-status: Done
-assignee: []
-created_date: '2026-03-06 03:20'
-updated_date: '2026-03-06 11:05'
-labels:
-  - tech-debt
-  - dead-code
-milestone: m-0
-dependencies:
-  - TASK-87.1
-  - TASK-87.2
-references:
-  - src/translators/index.ts
-  - src/subsync/engines.ts
-  - src/subtitle/pipeline.ts
-  - src/tokenizers/index.ts
-  - src/token-mergers/index.ts
-  - src/core/services/subsync.ts
-  - src/core/services/tokenizer.ts
-documentation:
-  - docs/reports/2026-02-22-task-100-dead-code-report.md
-parent_task_id: TASK-87
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-The review found several modules that appear self-contained but unused from the application’s live execution paths: src/translators/index.ts, src/subsync/engines.ts, src/subtitle/pipeline.ts, src/tokenizers/index.ts, and src/token-mergers/index.ts. At the same time, the real runtime behavior is implemented elsewhere. This task should verify those modules are truly unused, remove or consolidate them, and clean up any stale exports, docs, or tests so contributors are not misled by duplicate architecture.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Each candidate module identified in the review is either removed as dead code or justified and reconnected to a real supported execution path.
-- [x] #2 Any stale exports, imports, or tests associated with the removed or consolidated modules are cleaned up so the codebase has a single obvious path for the affected behavior.
-- [x] #3 The cleanup does not regress live tokenization or subtitle sync behavior and the relevant verification commands remain green.
-- [x] #4 Contributor-facing documentation or internal notes no longer imply that removed duplicate architecture is part of the current design.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-1. Re-verify each candidate module is off the live path by tracing imports from current runtime entrypoints before deleting anything.
-2. Remove or consolidate truly dead modules and clean associated exports/imports/tests so only the supported path remains obvious.
-3. Pay special attention to subtitle sync and tokenization surfaces, since duplicate architecture exists near active code.
-4. Verify the relevant tokenization and subsync commands/tests still pass and update any stale docs or notes.
-<!-- SECTION:PLAN:END -->
-
-## Implementation Notes
-
-- Traced imports from `src/main.ts`, `src/main/runtime/**`, `src/core/services/subsync-runner.ts`, and `src/core/services/tokenizer.ts`; confirmed the candidate registry/pipeline modules were isolated from the maintained runtime path.
-- Deleted dead modules: `src/translators/index.ts`, `src/subsync/engines.ts`, `src/subtitle/pipeline.ts`, `src/subtitle/stages/{merge,normalize,tokenize}.ts`, `src/subtitle/stages/normalize.test.ts`, `src/tokenizers/index.ts`, and `src/token-mergers/index.ts`.
-- Moved the useful zero-width separator normalization into the live tokenizer path in `src/core/services/tokenizer.ts` and added regression coverage plus a repository-level dead-architecture guard in `src/dead-architecture-cleanup.test.ts`.
-- Verified with `bun test src/core/services/tokenizer.test.ts`, `bun test src/dead-architecture-cleanup.test.ts`, `bun test src/core/services/subsync.test.ts src/subsync/utils.test.ts`, `bun run tsc`, and `bun run test:src`.

backlog/tasks/task-87.6 - Anki-integration-maintainability-continue-decomposing-the-oversized-orchestration-layer.md

@@ -1,57 +0,0 @@
----
-id: TASK-87.6
-title: >-
-  Anki integration maintainability: continue decomposing the oversized
-  orchestration layer
-status: Done
-assignee: []
-created_date: '2026-03-06 03:20'
-updated_date: '2026-03-06 09:23'
-labels:
-  - tech-debt
-  - anki
-  - maintainability
-milestone: m-0
-dependencies:
-  - TASK-87.1
-references:
-  - src/anki-integration.ts
-  - src/anki-integration/field-grouping-workflow.ts
-  - src/anki-integration/note-update-workflow.ts
-  - src/anki-integration/card-creation.ts
-  - src/anki-integration/anki-connect-proxy.ts
-  - src/anki-integration.test.ts
-documentation:
-  - docs/reports/2026-02-22-task-100-dead-code-report.md
-  - docs/anki-integration.md
-parent_task_id: TASK-87
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-src/anki-integration.ts remains an oversized orchestration file even after earlier extractions. It still mixes config normalization, polling setup, media generation, duplicate resolution, field grouping workflows, and user feedback coordination in one class. This task should continue the decomposition so the remaining orchestration surface is smaller and easier to reason about, while preserving existing Anki, proxy, field grouping, and note update behavior.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 The responsibilities currently concentrated in src/anki-integration.ts are split into clearer modules or services with narrow ownership boundaries.
-- [x] #2 The resulting orchestration surface is materially smaller and easier to review, with at least one mixed-responsibility cluster extracted behind a well-named interface.
-- [x] #3 Existing Anki integration behavior remains covered by automated verification, including note update, field grouping, and proxy-related flows that the refactor touches.
-- [x] #4 Any developer-facing docs or notes needed to understand the new structure are updated in the same task.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-1. Map the remaining responsibility clusters inside src/anki-integration.ts and choose one or more extraction seams that reduce mixed concerns without changing behavior.
-2. Move logic behind narrow interfaces/modules rather than creating another giant helper; keep orchestration readable.
-3. Preserve coverage for field grouping, note update, proxy, and card creation flows touched by the refactor.
-4. Update docs or internal notes if the new structure changes where contributors should look for a given behavior.
-<!-- SECTION:PLAN:END -->

backlog/tasks/task-88 - Fix-second-instance-start-handling-when-overlay-runtime-is-already-initialized.md

@@ -1,68 +0,0 @@
----
-id: TASK-88
-title: >-
-  Fix second-instance --start handling when overlay runtime is already
-  initialized
-status: Done
-assignee:
-  - codex
-created_date: '2026-03-06 07:30'
-updated_date: '2026-03-06 07:31'
-labels: []
-dependencies: []
-references:
-  - /home/sudacode/projects/japanese/SubMiner/src/core/services/cli-command.ts
-  - >-
-    /home/sudacode/projects/japanese/SubMiner/src/core/services/cli-command.test.ts
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Restore the CLI command guard so a second-instance `--start` request does not reconnect or reinitialize overlay work when the overlay runtime is already active, while preserving other second-instance commands.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Second-instance `--start` logs that the app is already running when the overlay runtime is initialized.
-- [x] #2 Second-instance `--start` does not reconnect the MPV client when the overlay runtime is already initialized.
-- [x] #3 Second-instance commands that include non-start actions still execute those actions.
-- [x] #4 Regression coverage documents the guarded second-instance behavior.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-1. Reproduce the failing `handleCliCommand` second-instance `--start` regression in `src/core/services/cli-command.test.ts`.
-2. Update `src/core/services/cli-command.ts` so second-instance `--start` is ignored when the overlay runtime is already initialized, while still allowing non-start actions in the same invocation.
-3. Run focused CLI command tests, then rerun the core test target if practical, and record acceptance criteria/results.
-<!-- SECTION:PLAN:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-Reproduced the failing second-instance `--start` regression in `src/core/services/cli-command.test.ts` before editing.
-
-Restored a guard in `src/core/services/cli-command.ts` that ignores second-instance `--start` when the overlay runtime is already initialized, but still allows other flags in the same invocation to run.
-
-Verification: `bun test src/core/services/cli-command.test.ts`, `bun run test:core:src`, and `bun run test` all pass; the six immersion tracker tests remain skipped as before.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Restored the missing second-instance `--start` guard in `src/core/services/cli-command.ts`.
-
-- Added an `ignoreSecondInstanceStart` check so `handleCliCommand` logs `Ignoring --start because SubMiner is already running.` when a second-instance `--start` arrives after the overlay runtime is already initialized.
-- Updated start gating so pure duplicate `--start` requests no longer reconnect the MPV client, while combined commands such as `--start --toggle-visible-overlay` still execute their non-start behavior and can connect through those paths.
-- Verified the regression with existing CLI command coverage and reran the broader test targets.
-
-Tests run:
-- `bun test src/core/services/cli-command.test.ts`
-- `bun run test:core:src`
-- `bun run test`
-
-Notes:
-- The six skipped immersion tracker tests are unchanged from the pre-fix baseline.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-89 - Replace-per-anime-Yomitan-imports-with-merged-usage-based-character-dictionary.md

@@ -1,57 +0,0 @@
----
-id: TASK-89
-title: Replace per-anime Yomitan imports with merged usage-based character dictionary
-status: Done
-assignee:
-  - '@codex'
-created_date: '2026-03-06 07:59'
-updated_date: '2026-03-06 08:09'
-labels:
-  - character-dictionary
-  - yomitan
-  - anilist
-dependencies: []
-references:
-  - >-
-    /home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
-  - >-
-    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
-  - >-
-    /home/sudacode/projects/japanese/SubMiner/src/config/definitions/defaults-integrations.ts
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Replace TTL-based per-anime character dictionary imports with a single merged Yomitan dictionary built from locally stored per-media metadata snapshots. Retain only most-recently-used anime up to configured maxLoaded, rebuild merged import when retained set membership/order changes, and avoid rebuilding on revisits that do not change the retained set.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Character dictionary retention becomes usage-based rather than TTL-based.
-- [x] #2 Only one Yomitan character dictionary import is maintained and updated as a merged dictionary.
-- [x] #3 Local storage keeps only metadata/snapshots needed to rebuild the merged dictionary; per-anime source zip cache is removed.
-- [x] #4 Merged dictionary rebuild occurs when retained-set membership or order changes, not on unchanged revisits.
-- [x] #5 Tests cover merged rebuild, MRU eviction, and no-op revisits.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-Replaced per-media auto-sync imports with one merged Yomitan dictionary. Added snapshot persistence in `src/main/character-dictionary-runtime.ts` so auto-sync stores normalized per-media term/image metadata locally under `character-dictionaries/snapshots/` and rebuilds `merged.zip` from the MRU retained media ids.
-
-Updated `src/main/runtime/character-dictionary-auto-sync.ts` to keep only MRU `activeMediaIds` plus merged revision/title state, rebuild/import the merged dictionary only when retained-set membership/order changes or the merged import is missing/stale, and skip rebuild on unchanged revisits.
-
-Kept manual `generateForCurrentMedia` support by generating a one-off per-media zip from the stored snapshot, but removed the old per-media zip cache path from auto-sync state.
-
-Updated config/help text to describe usage-based merged retention and mark legacy TTL/eviction knobs as ignored.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Implemented MRU-based merged character dictionary sync. Auto-sync now stores per-media normalized snapshots locally, rebuilds a single merged Yomitan dictionary when the retained anime set/order changes, and keeps `maxLoaded` as the cap on most-recently-used anime included in that merged import. Unchanged revisits no longer rebuild/import the dictionary.
-
-Validation: `bun test src/main/runtime/character-dictionary-auto-sync.test.ts src/main/character-dictionary-runtime.test.ts`, `bun run tsc --noEmit`.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-90 - Expand-TypeScript-typecheck-coverage-beyond-src.md

@@ -1,38 +0,0 @@
----
-id: TASK-90
-title: Expand TypeScript typecheck coverage beyond src
-status: Done
-assignee: []
-created_date: '2026-03-06 08:18'
-updated_date: '2026-03-06 08:23'
-labels:
-  - tooling
-  - typescript
-dependencies: []
-references:
-  - /home/sudacode/projects/japanese/SubMiner/tsconfig.json
-  - /home/sudacode/projects/japanese/SubMiner/package.json
-  - /home/sudacode/projects/japanese/SubMiner/launcher
-  - /home/sudacode/projects/japanese/SubMiner/scripts
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Bring all repository TypeScript entrypoints outside src/ into the enforced typecheck gate so CI and local checks cover launcher/ and script files, then resolve any surfaced diagnostics.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 TypeScript typecheck covers repository TypeScript entrypoints outside src/ that should be maintained in this repo, including launcher/ and script files.
-- [x] #2 The enforced typecheck command used by CI and local development passes with the expanded coverage.
-- [x] #3 Any diagnostics surfaced by the expanded coverage are fixed without weakening existing strictness for src/.
-- [x] #4 Relevant documentation or command wiring is updated if the typecheck entrypoint changes.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Added a dedicated repo-wide typecheck config at tsconfig.typecheck.json and wired package.json/CI to use `bun run typecheck` for launcher and scripts coverage without changing the existing src build config. Fixed the strict-null/indexing diagnostics surfaced in launcher/* and scripts/*, keeping src strictness intact. Verified with `bun run typecheck`, `bun run tsc --noEmit`, and `bun run test:launcher:src` (47 passing, plugin start gate OK).
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-91 - Keep-unsupported-subtitle-characters-visible-while-excluding-them-from-token-hover.md

@@ -1,35 +0,0 @@
----
-id: TASK-91
-title: >-
-  Keep unsupported subtitle characters visible while excluding them from token
-  hover
-status: Done
-assignee: []
-created_date: '2026-03-06 08:29'
-updated_date: '2026-03-06 08:32'
-labels:
-  - bug
-  - tokenizer
-  - renderer
-dependencies: []
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Tokenizer/rendering bug: symbols and other unsupported characters with no lookup result are removed from the rendered subtitle line after tokenization, causing the displayed line to diverge from the source subtitle text. Update rendering so unsupported spans remain visible as plain text but are not tokenized/hoverable, and add regression coverage.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Subtitle rendering preserves unsupported symbols and special characters from the original line.
-- [x] #2 Unsupported symbols and special characters do not create interactive token hover targets.
-- [x] #3 Regression tests cover a mixed line containing tokenizable text plus unsupported characters.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Updated tokenized subtitle rendering to preserve unsupported punctuation and symbol spans as plain text while keeping only matched tokens interactive. Added renderer and alignment regression coverage for mixed lines so hover offsets stay correct after non-tokenizable characters remain visible.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-92 - Fix-merged-Yomitan-headword-selection-for-katakana-subtitle-tokens.md

@@ -1,34 +0,0 @@
----
-id: TASK-92
-title: Fix merged Yomitan headword selection for katakana subtitle tokens
-status: Done
-assignee: []
-created_date: '2026-03-06 08:43'
-updated_date: '2026-03-06 08:43'
-labels:
-  - bug
-  - tokenizer
-  - yomitan
-dependencies: []
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Tokenizer/parser-selection bug: when a scanning-parser line is merged from multiple segments, the merged token currently keeps the first segment headword even if a later segment provides the full dictionary-backed term. This truncates katakana names such as バニール to バニ in the lookup payload and prevents correct dictionary matching. Also align kana classification so the prolonged sound mark is treated as kana in tokenizer heuristics.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Merged scanning-parser tokens prefer a full cross-segment headword when one segment expands to the full term.
-- [x] #2 Standalone later segment headwords do not override the primary token headword in normal content-word + auxiliary merges.
-- [x] #3 Katakana prolonged sound mark is treated as kana in tokenizer heuristics.
-- [x] #4 Regression tests cover the merged katakana headword case.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Adjusted merged scanning-parser headword selection so later segments only override the first headword when they provide an expanded cross-segment dictionary term, which fixes truncated katakana lookups like バニール -> バニ. Also updated kana classification to include the katakana prolonged sound mark and added regression coverage for both the expanded-headword case and the normal content-word-plus-auxiliary case.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-93 - Replace-subtitle-tokenizer-with-left-to-right-Yomitan-scanning-parser.md

@@ -1,34 +0,0 @@
----
-id: TASK-93
-title: Replace subtitle tokenizer with left-to-right Yomitan scanning parser
-status: Done
-assignee: []
-created_date: '2026-03-06 09:02'
-updated_date: '2026-03-06 09:14'
-labels:
-  - tokenizer
-  - yomitan
-  - refactor
-dependencies: []
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Replace the current parseText candidate-selection tokenizer with a GSM-style left-to-right Yomitan scanning tokenizer for all subtitles. Preserve downstream token contracts for rendering, JLPT/frequency/N+1 annotation, and MeCab enrichment while improving full-term matching for names and katakana compounds.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Subtitle tokenization uses a left-to-right Yomitan scanning strategy instead of parseText candidate selection.
-- [x] #2 Token surfaces, readings, headwords, and offsets remain compatible with existing renderer and annotation stages.
-- [x] #3 Known problematic name cases such as カズマ and バニール resolve to full-token dictionary matches when Yomitan can match them.
-- [x] #4 Regression tests cover left-to-right exact-match scanning, unmatched text handling, and downstream tokenizeSubtitle integration.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Replaced the live subtitle tokenization path with a left-to-right Yomitan `termsFind` scanner that greedily advances through the normalized subtitle text, preserving downstream `MergedToken` contracts for renderer, MeCab enrichment, JLPT, frequency, and N+1 annotation. Added runtime and integration coverage for exact-match scanning plus name cases like カズマ and kept compatibility fallback handling for older mocked parseText-style test payloads.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-94 - Add-kana-aliases-for-AniList-character-dictionary-entries.md

@@ -1,40 +0,0 @@
----
-id: TASK-94
-title: Add kana aliases for AniList character dictionary entries
-status: Done
-assignee: []
-created_date: '2026-03-06 09:20'
-updated_date: '2026-03-06 09:23'
-labels:
-  - dictionary
-  - tokenizer
-  - anilist
-dependencies: []
-references:
-  - >-
-    /home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
-  - >-
-    /home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.test.ts
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Generate katakana/hiragana-friendly aliases from AniList romanized character names so subtitle katakana names like カズマ match character dictionary entries even when AniList native name is kanji.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 AniList character dictionary generation adds kana aliases for romanized names when native name is not already kana-only
-- [x] #2 Generated dictionary entries allow katakana subtitle names like カズマ to resolve against a kanji-native AniList character entry
-- [x] #3 Regression tests cover alias generation and resulting term bank output
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Added katakana aliases synthesized from AniList romanized character names during character dictionary generation, so kanji-native entries such as 佐藤和真 / Satou Kazuma now also emit terms like カズマ and サトウカズマ with hiragana readings. Added regression coverage verifying generated term-bank output for the Konosuba case.
-
-Verified with `bun test src/main/character-dictionary-runtime.test.ts` and `bun run tsc --noEmit`.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-95 - Invalidate-old-character-dictionary-snapshots-after-kana-alias-schema-change.md

@@ -1,39 +0,0 @@
----
-id: TASK-95
-title: Invalidate old character dictionary snapshots after kana alias schema change
-status: Done
-assignee: []
-created_date: '2026-03-06 09:25'
-updated_date: '2026-03-06 09:28'
-labels:
-  - dictionary
-  - cache
-dependencies: []
-references:
-  - >-
-    /home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
-  - >-
-    /home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.test.ts
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Bump character dictionary snapshot format/version so cached AniList snapshots created before kana alias generation are rebuilt automatically on next auto-sync or generation run.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Old cached character dictionary snapshots are treated as invalid after the schema/version bump
-- [x] #2 Current snapshot generation tests cover rebuild behavior across version mismatch
-- [x] #3 No manual cache deletion is required for users to pick up kana alias term generation
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Bumped the character dictionary snapshot format version so cached AniList snapshots created before kana alias generation are automatically treated as stale and rebuilt. Added regression coverage that seeds an older-format snapshot and verifies `getOrCreateCurrentSnapshot` fetches fresh data and overwrites the stale cache.
-
-Verified with `bun test src/main/character-dictionary-runtime.test.ts` and `bun run tsc --noEmit`.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-96 - Add-launcher-app-log-progress-for-anime-dictionary-generate-update-flow.md

@@ -1,47 +0,0 @@
----
-id: TASK-96
-title: Add launcher/app log progress for anime dictionary generate/update flow
-status: Done
-assignee: []
-created_date: '2026-03-06 09:30'
-updated_date: '2026-03-06 09:33'
-labels:
-  - logging
-  - dictionary
-  - launcher
-dependencies: []
-references:
-  - >-
-    /home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
-  - /home/sudacode/projects/japanese/SubMiner/src/core/services/cli-command.ts
-  - >-
-    /home/sudacode/projects/japanese/SubMiner/launcher/commands/playback-command.ts
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Surface user-visible log progress while the anime character dictionary is being generated or refreshed so launcher/app output no longer appears hung before mpv launches.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Dictionary generation logs a start/progress message before the first AniList/network/cache work begins.
-- [x] #2 Dictionary refresh/update path logs progress messages during the wait before completion.
-- [x] #3 Regression coverage verifies the new progress logging behavior.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-Added progress logging to character dictionary generation at anime resolution, AniList match, snapshot miss, character-page fetch, image download start, and ZIP build stages.
-
-Added auto-sync progress logging at snapshot sync start, active AniList set selection, merged rebuild, Yomitan import, and settings application stages.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Character dictionary generation/update no longer appears hung before mpv resumes. Added runtime progress logs for anime resolution, AniList lookup, snapshot rebuild, image-download phase, ZIP build, and auto-sync merged-dictionary import/settings stages. Added regression coverage in the runtime and auto-sync test suites and verified with focused Bun tests.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-97 - Add-configurable-character-name-token-highlighting.md

@@ -1,39 +0,0 @@
----
-id: TASK-97
-title: Add configurable character-name token highlighting
-status: Done
-assignee: []
-created_date: '2026-03-06 10:15'
-updated_date: '2026-03-06 10:15'
-labels:
-  - subtitle
-  - dictionary
-  - renderer
-dependencies: []
-references:
-  - /home/sudacode/projects/japanese/SubMiner/src/core/services/tokenizer.ts
-  - >-
-    /home/sudacode/projects/japanese/SubMiner/src/core/services/tokenizer/yomitan-parser-runtime.ts
-  - /home/sudacode/projects/japanese/SubMiner/src/renderer/subtitle-render.ts
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Color subtitle tokens that match entries from the SubMiner character dictionary, with a configurable default color and a config toggle that disables both rendering and name-match detection work.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Tokens matched from the SubMiner character dictionary receive dedicated renderer styling.
-- [x] #2 `subtitleStyle.nameMatchEnabled` disables name-match detection work when false.
-- [x] #3 `subtitleStyle.nameMatchColor` overrides the default `#f5bde6`.
-- [x] #4 Regression coverage verifies config parsing, tokenizer propagation, scanner gating, and renderer class/CSS behavior.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Added configurable character-name token highlighting with default color `#f5bde6` and config gate `subtitleStyle.nameMatchEnabled`. When enabled, left-to-right Yomitan scanning tags tokens whose winning dictionary entry comes from the SubMiner character dictionary; when disabled, the tokenizer skips that metadata work and the renderer suppresses name-match styling. Added focused regression tests for config parsing, main-deps wiring, Yomitan scan gating, token propagation, renderer classes, and CSS behavior.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-98 - Gate-subtitle-character-name-highlighting-on-character-dictionary-enablement.md

@@ -1,60 +0,0 @@
----
-id: TASK-98
-title: Gate subtitle character-name highlighting on character dictionary enablement
-status: Done
-assignee:
-  - codex
-created_date: '2026-03-07 00:54'
-updated_date: '2026-03-07 00:56'
-labels:
-  - subtitle
-  - character-dictionary
-dependencies: []
-references:
-  - /Users/sudacode/projects/japanese/SubMiner/src/main.ts
-  - /Users/sudacode/projects/japanese/SubMiner/src/core/services/tokenizer.ts
-  - >-
-    /Users/sudacode/projects/japanese/SubMiner/src/config/definitions/defaults-subtitle.ts
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Ensure subtitle tokenization and other annotations continue to work, but character-name lookup/highlighting is disabled whenever the AniList character dictionary feature is disabled. This avoids unnecessary name-match processing when the backing dictionary is unavailable.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 When anilist.characterDictionary.enabled is false, subtitle tokenization does not request character-name match metadata or highlight character names.
-- [x] #2 When anilist.characterDictionary.enabled is true and subtitleStyle.nameMatchEnabled is true, existing character-name matching behavior remains enabled.
-- [x] #3 Subtitle tokenization, JLPT, frequency, and other non-name annotation behavior remain unchanged when character dictionaries are disabled.
-- [x] #4 Automated tests cover the runtime gating behavior.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-1. Add a failing test in `src/main/runtime/subtitle-tokenization-main-deps.test.ts` proving name-match enablement resolves to false when `anilist.characterDictionary.enabled` is false even if `subtitleStyle.nameMatchEnabled` is true.
-2. Update `src/main/runtime/subtitle-tokenization-main-deps.ts` and `src/main.ts` so subtitle tokenization only enables name matching when both the subtitle setting and the character dictionary setting are enabled.
-3. Run focused Bun tests for the updated runtime deps and subtitle processing seams.
-4. If verification stays green, check off acceptance criteria and record the result.
-
-Implementation plan saved in `docs/plans/2026-03-06-character-name-gating.md`.
-<!-- SECTION:PLAN:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-Created plan doc `docs/plans/2026-03-06-character-name-gating.md` after user approved the narrow runtime-gating approach. Proceeding with TDD from the subtitle tokenization main-deps seam.
-
-Implemented the gate at the subtitle tokenization runtime-deps boundary so `getNameMatchEnabled` is false unless both `subtitleStyle.nameMatchEnabled` and `anilist.characterDictionary.enabled` are true.
-
-Verification: `bun test src/main/runtime/subtitle-tokenization-main-deps.test.ts`, `bun test src/core/services/subtitle-processing-controller.test.ts`, `bun run typecheck`.
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Character-name lookup/highlighting is now suppressed when the AniList character dictionary is disabled, while subtitle tokenization and other annotation paths remain active. Added focused runtime-deps coverage and wired the main runtime to pass the character-dictionary enabled flag into subtitle tokenization.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-99 - Add-configurable-character-dictionary-collapsible-section-open-states.md

@@ -1,38 +0,0 @@
----
-id: TASK-99
-title: Add configurable character dictionary collapsible section open states
-status: Done
-assignee: []
-created_date: '2026-03-07 00:00'
-updated_date: '2026-03-07 00:00'
-labels:
-  - dictionary
-  - config
-references:
-  - /home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
-  - /home/sudacode/projects/japanese/SubMiner/src/config/resolve/integrations.ts
-  - /home/sudacode/projects/japanese/SubMiner/src/config/definitions/defaults-integrations.ts
-priority: medium
-dependencies: []
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Add per-section config for character dictionary collapsible glossary sections so Description, Character Information, and Voiced by can each default open or closed independently. Default all sections closed.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Config supports `anilist.characterDictionary.collapsibleSections.description`.
-- [x] #2 Config supports `anilist.characterDictionary.collapsibleSections.characterInformation`.
-- [x] #3 Config supports `anilist.characterDictionary.collapsibleSections.voicedBy`.
-- [x] #4 Default config keeps all generated character dictionary collapsible sections closed.
-- [x] #5 Regression coverage verifies config parsing/warnings and generated glossary `details.open` behavior.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Added per-section open-state config under `anilist.characterDictionary.collapsibleSections` for `description`, `characterInformation`, and `voicedBy`, all defaulting to `false`. Wired the glossary generator to read those settings so generated `details.open` matches config, and added regression coverage for defaults, parsing/warnings, registry exposure, and runtime glossary output.
-<!-- SECTION:FINAL_SUMMARY:END -->

build/installer.nsh

@@ -0,0 +1,153 @@
+!include "MUI2.nsh"
+!include "nsDialogs.nsh"
+
+Var WindowsMpvShortcutStartMenuPath
+Var WindowsMpvShortcutDesktopPath
+
+!macro ResolveWindowsMpvShortcutPaths
+  !ifdef MENU_FILENAME
+    StrCpy $WindowsMpvShortcutStartMenuPath "$SMPROGRAMS\${MENU_FILENAME}\SubMiner mpv.lnk"
+  !else
+    StrCpy $WindowsMpvShortcutStartMenuPath "$SMPROGRAMS\SubMiner mpv.lnk"
+  !endif
+  StrCpy $WindowsMpvShortcutDesktopPath "$DESKTOP\SubMiner mpv.lnk"
+!macroend
+
+!ifndef BUILD_UNINSTALLER
+Var WindowsMpvShortcutStartMenuCheckbox
+Var WindowsMpvShortcutDesktopCheckbox
+Var WindowsMpvShortcutStartMenuEnabled
+Var WindowsMpvShortcutDesktopEnabled
+Var WindowsMpvShortcutDefaultsInitialized
+
+!macro customInit
+  StrCpy $WindowsMpvShortcutStartMenuEnabled "1"
+  StrCpy $WindowsMpvShortcutDesktopEnabled "1"
+  StrCpy $WindowsMpvShortcutDefaultsInitialized "0"
+!macroend
+
+!macro customPageAfterChangeDir
+  PageEx custom
+    PageCallbacks WindowsMpvShortcutPageCreate WindowsMpvShortcutPageLeave
+    Caption " "
+  PageExEnd
+!macroend
+
+Function HasExistingInstallation
+  ReadRegStr $0 SHELL_CONTEXT "Software\${APP_GUID}" InstallLocation
+  ${if} $0 == ""
+    Push "0"
+  ${else}
+    Push "1"
+  ${endif}
+FunctionEnd
+
+Function InitializeWindowsMpvShortcutDefaults
+  ${if} $WindowsMpvShortcutDefaultsInitialized == "1"
+    Return
+  ${endif}
+
+  !insertmacro ResolveWindowsMpvShortcutPaths
+  Call HasExistingInstallation
+  Pop $0
+
+  ${if} $0 == "1"
+    ${if} ${FileExists} "$WindowsMpvShortcutStartMenuPath"
+      StrCpy $WindowsMpvShortcutStartMenuEnabled "1"
+    ${else}
+      StrCpy $WindowsMpvShortcutStartMenuEnabled "0"
+    ${endif}
+
+    ${if} ${FileExists} "$WindowsMpvShortcutDesktopPath"
+      StrCpy $WindowsMpvShortcutDesktopEnabled "1"
+    ${else}
+      StrCpy $WindowsMpvShortcutDesktopEnabled "0"
+    ${endif}
+  ${else}
+    StrCpy $WindowsMpvShortcutStartMenuEnabled "1"
+    StrCpy $WindowsMpvShortcutDesktopEnabled "1"
+  ${endif}
+
+  StrCpy $WindowsMpvShortcutDefaultsInitialized "1"
+FunctionEnd
+
+Function WindowsMpvShortcutPageCreate
+  Call InitializeWindowsMpvShortcutDefaults
+
+  !insertmacro MUI_HEADER_TEXT "Windows mpv launcher" "Choose where to create the optional SubMiner mpv shortcuts."
+
+  nsDialogs::Create 1018
+  Pop $0
+
+  ${NSD_CreateLabel} 0u 0u 300u 30u "SubMiner mpv launches SubMiner.exe --launch-mpv so people can open mpv with the SubMiner profile from a separate Windows shortcut."
+  Pop $0
+
+  ${NSD_CreateCheckbox} 0u 44u 280u 12u "Create Start Menu shortcut"
+  Pop $WindowsMpvShortcutStartMenuCheckbox
+  ${if} $WindowsMpvShortcutStartMenuEnabled == "1"
+    ${NSD_Check} $WindowsMpvShortcutStartMenuCheckbox
+  ${endif}
+
+  ${NSD_CreateCheckbox} 0u 64u 280u 12u "Create Desktop shortcut"
+  Pop $WindowsMpvShortcutDesktopCheckbox
+  ${if} $WindowsMpvShortcutDesktopEnabled == "1"
+    ${NSD_Check} $WindowsMpvShortcutDesktopCheckbox
+  ${endif}
+
+  ${NSD_CreateLabel} 0u 90u 300u 24u "Upgrades preserve the current SubMiner mpv shortcut locations instead of recreating shortcuts you already removed."
+  Pop $0
+
+  nsDialogs::Show
+FunctionEnd
+
+Function WindowsMpvShortcutPageLeave
+  ${NSD_GetState} $WindowsMpvShortcutStartMenuCheckbox $0
+  ${if} $0 == ${BST_CHECKED}
+    StrCpy $WindowsMpvShortcutStartMenuEnabled "1"
+  ${else}
+    StrCpy $WindowsMpvShortcutStartMenuEnabled "0"
+  ${endif}
+
+  ${NSD_GetState} $WindowsMpvShortcutDesktopCheckbox $0
+  ${if} $0 == ${BST_CHECKED}
+    StrCpy $WindowsMpvShortcutDesktopEnabled "1"
+  ${else}
+    StrCpy $WindowsMpvShortcutDesktopEnabled "0"
+  ${endif}
+FunctionEnd
+
+!macro customInstall
+  Call InitializeWindowsMpvShortcutDefaults
+  !insertmacro ResolveWindowsMpvShortcutPaths
+
+  ${if} $WindowsMpvShortcutStartMenuEnabled == "1"
+    !ifdef MENU_FILENAME
+      CreateDirectory "$SMPROGRAMS\${MENU_FILENAME}"
+    !endif
+    CreateShortCut "$WindowsMpvShortcutStartMenuPath" "$appExe" "--launch-mpv" "$appExe" 0 "" "" "Launch mpv with the SubMiner profile"
+    # electron-builder's upstream NSIS templates use the same WinShell call for AppUserModelID wiring.
+    # WinShell.dll comes from electron-builder's cached nsis-resources bundle, so bun run build:win needs no extra repo-local setup.
+    ClearErrors
+    WinShell::SetLnkAUMI "$WindowsMpvShortcutStartMenuPath" "${APP_ID}"
+  ${else}
+    Delete "$WindowsMpvShortcutStartMenuPath"
+  ${endif}
+
+  ${if} $WindowsMpvShortcutDesktopEnabled == "1"
+    CreateShortCut "$WindowsMpvShortcutDesktopPath" "$appExe" "--launch-mpv" "$appExe" 0 "" "" "Launch mpv with the SubMiner profile"
+    # ClearErrors keeps the optional AUMI assignment non-fatal if the packaging environment is missing WinShell.
+    ClearErrors
+    WinShell::SetLnkAUMI "$WindowsMpvShortcutDesktopPath" "${APP_ID}"
+  ${else}
+    Delete "$WindowsMpvShortcutDesktopPath"
+  ${endif}
+
+  System::Call 'Shell32::SHChangeNotify(i 0x8000000, i 0, i 0, i 0)'
+!macroend
+!endif
+
+!macro customUnInstall
+  !insertmacro ResolveWindowsMpvShortcutPaths
+  Delete "$WindowsMpvShortcutStartMenuPath"
+  Delete "$WindowsMpvShortcutDesktopPath"
+!macroend

build/signpath-windows-artifact-config.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="utf-8"?>
+<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
+  <zip-file>
+    <pe-file path="SubMiner-*.exe" max-matches="unbounded">
+      <authenticode-sign />
+    </pe-file>
+    <zip-file path="SubMiner-*.zip" max-matches="unbounded">
+      <directory path="*">
+        <pe-file path="*.exe" max-matches="unbounded">
+          <authenticode-sign />
+        </pe-file>
+        <pe-file path="*.dll" max-matches="unbounded">
+          <authenticode-sign />
+        </pe-file>
+        <pe-file path="*.node" max-matches="unbounded">
+          <authenticode-sign />
+        </pe-file>
+      </directory>
+    </zip-file>
+  </zip-file>
+</artifact-configuration>

changes/README.md

@@ -0,0 +1,44 @@
+# Changelog Fragments
+
+Add one `.md` file per user-visible PR in this directory.
+
+Use this format:
+
+```md
+type: added
+area: overlay
+
+- Added keyboard navigation for Yomitan popups.
+- Added auto-pause toggle when opening the popup.
+```
+
+For breaking changes, add `breaking: true`:
+
+```md
+type: changed
+area: config
+breaking: true
+
+- Renamed `foo.bar` to `foo.baz`.
+```
+
+Rules:
+
+- `type` required: `added`, `changed`, `fixed`, `docs`, or `internal`
+- `area` required: short product area like `overlay`, `launcher`, `release`
+- `breaking` optional: set to `true` to flag as a breaking change
+- each non-empty body line becomes a bullet
+- `README.md` is ignored by the generator
+- if a PR should not produce release notes, apply the `skip-changelog` label instead of adding a fragment
+
+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.
+- `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`
+- prerelease note generation does not consume fragments and does not update `CHANGELOG.md` or `docs-site/changelog.md`
+- the final stable release is the point where `bun run changelog:build` consumes fragments into the stable changelog and release notes

config.example.jsonc

@@ -2,7 +2,7 @@
  * SubMiner Example Configuration File
  *
  * This file is auto-generated from src/config/definitions.ts.
- * Copy to $XDG_CONFIG_HOME/SubMiner/config.jsonc (or ~/.config/SubMiner/config.jsonc) and edit as needed.
+ * Copy to %APPDATA%/SubMiner/config.jsonc on Windows, or $XDG_CONFIG_HOME/SubMiner/config.jsonc (or ~/.config/SubMiner/config.jsonc) on Linux/macOS.
  */
 {
 
@@ -17,8 +17,8 @@
   // Configure texthooker startup launch and browser opening behavior.
   // ==========================================
   "texthooker": {
-    "launchAtStartup": true, // Launch texthooker server automatically when SubMiner starts. Values: true | false
-    "openBrowser": true // Open browser setting. Values: true | false
+    "launchAtStartup": false, // Launch texthooker server automatically when SubMiner starts. Values: true | false
+    "openBrowser": false // Open browser setting. Values: true | false
   }, // Configure texthooker startup launch and browser opening behavior.
 
   // ==========================================
@@ -27,7 +27,7 @@
   // Auto mode disables built-in server if mpv_websocket is detected.
   // ==========================================
   "websocket": {
-    "enabled": "auto", // Built-in subtitle websocket server mode. Values: auto | true | false
+    "enabled": false, // Built-in subtitle websocket server mode. Values: auto | true | false
     "port": 6677 // Built-in subtitle websocket server port.
   }, // Built-in WebSocket server broadcasts subtitle text to connected clients.
 
@@ -37,7 +37,7 @@
   // Independent from websocket.auto and defaults to port 6678.
   // ==========================================
   "annotationWebsocket": {
-    "enabled": true, // Annotated subtitle websocket server enabled state. Values: true | false
+    "enabled": false, // Annotated subtitle websocket server enabled state. Values: true | false
     "port": 6678 // Annotated subtitle websocket server port.
   }, // Dedicated annotated subtitle websocket for bundled texthooker and token-aware clients.
 
@@ -50,6 +50,97 @@
     "level": "info" // Minimum log level for runtime logging. Values: debug | info | warn | error
   }, // Controls logging verbosity.
 
+  // ==========================================
+  // Controller Support
+  // Gamepad support for the visible overlay while keyboard-only mode is active.
+  // Use Alt+C to pick a preferred controller and remap actions inline with learn mode.
+  // Trigger input mode can be auto, digital-only, or analog-thresholded depending on the controller.
+  // Override controller.buttonIndices when your pad reports non-standard raw button numbers.
+  // ==========================================
+  "controller": {
+    "enabled": false, // Enable overlay controller support through the Chrome Gamepad API. Values: true | false
+    "preferredGamepadId": "", // Preferred controller id saved from the controller config modal.
+    "preferredGamepadLabel": "", // Preferred controller display label saved for diagnostics.
+    "smoothScroll": true, // Use smooth scrolling for controller-driven popup scroll input. Values: true | false
+    "scrollPixelsPerSecond": 900, // Base popup scroll speed for controller stick input.
+    "horizontalJumpPixels": 160, // Popup page-jump distance for controller jump input.
+    "stickDeadzone": 0.2, // Deadzone applied to controller stick axes.
+    "triggerInputMode": "auto", // How controller triggers are interpreted: auto, pressed-only, or thresholded analog. Values: auto | digital | analog
+    "triggerDeadzone": 0.5, // Minimum analog trigger value required when trigger input uses auto or analog mode.
+    "repeatDelayMs": 320, // Delay before repeating held controller actions.
+    "repeatIntervalMs": 120, // Repeat interval for held controller actions.
+    "buttonIndices": {
+      "select": 6, // Raw button index used for the controller select/minus/back button.
+      "buttonSouth": 0, // Raw button index used for controller south/A button input.
+      "buttonEast": 1, // Raw button index used for controller east/B button input.
+      "buttonWest": 2, // Raw button index used for controller west/X button input.
+      "buttonNorth": 3, // Raw button index used for controller north/Y button input.
+      "leftShoulder": 4, // Raw button index used for controller left shoulder input.
+      "rightShoulder": 5, // Raw button index used for controller right shoulder input.
+      "leftStickPress": 9, // Raw button index used for controller L3 input.
+      "rightStickPress": 10, // Raw button index used for controller R3 input.
+      "leftTrigger": 6, // Raw button index used for controller L2 input.
+      "rightTrigger": 7 // Raw button index used for controller R2 input.
+    }, // Semantic button-name reference mapping used for legacy configs and debug output. Updating it does not rewrite existing raw binding descriptors.
+    "bindings": {
+      "toggleLookup": {
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+        "buttonIndex": 0 // Raw button index captured for this discrete controller action.
+      }, // Controller binding descriptor for toggling lookup. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "closeLookup": {
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+        "buttonIndex": 1 // Raw button index captured for this discrete controller action.
+      }, // Controller binding descriptor for closing lookup. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "toggleKeyboardOnlyMode": {
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+        "buttonIndex": 3 // Raw button index captured for this discrete controller action.
+      }, // Controller binding descriptor for toggling keyboard-only mode. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "mineCard": {
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+        "buttonIndex": 2 // Raw button index captured for this discrete controller action.
+      }, // Controller binding descriptor for mining the active card. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "quitMpv": {
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+        "buttonIndex": 6 // Raw button index captured for this discrete controller action.
+      }, // Controller binding descriptor for quitting mpv. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "previousAudio": {
+        "kind": "none" // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+      }, // Controller binding descriptor for previous Yomitan audio. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "nextAudio": {
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+        "buttonIndex": 5 // Raw button index captured for this discrete controller action.
+      }, // Controller binding descriptor for next Yomitan audio. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "playCurrentAudio": {
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+        "buttonIndex": 4 // Raw button index captured for this discrete controller action.
+      }, // Controller binding descriptor for playing the current Yomitan audio. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "toggleMpvPause": {
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+        "buttonIndex": 9 // Raw button index captured for this discrete controller action.
+      }, // Controller binding descriptor for toggling mpv play/pause. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "leftStickHorizontal": {
+        "kind": "axis", // Analog binding input source kind. Values: none | axis
+        "axisIndex": 0, // Raw axis index captured for this analog controller action.
+        "dpadFallback": "horizontal" // Optional D-pad fallback used when this analog controller action should also read D-pad input. Values: none | horizontal | vertical
+      }, // Axis binding descriptor used for left/right token selection. Use Alt+C learn mode or set a raw axis descriptor manually.
+      "leftStickVertical": {
+        "kind": "axis", // Analog binding input source kind. Values: none | axis
+        "axisIndex": 1, // Raw axis index captured for this analog controller action.
+        "dpadFallback": "vertical" // Optional D-pad fallback used when this analog controller action should also read D-pad input. Values: none | horizontal | vertical
+      }, // Axis binding descriptor used for primary popup scrolling. Use Alt+C learn mode or set a raw axis descriptor manually.
+      "rightStickHorizontal": {
+        "kind": "axis", // Analog binding input source kind. Values: none | axis
+        "axisIndex": 3, // Raw axis index captured for this analog controller action.
+        "dpadFallback": "none" // Optional D-pad fallback used when this analog controller action should also read D-pad input. Values: none | horizontal | vertical
+      }, // Axis binding descriptor reserved for alternate right-stick mappings. Use Alt+C learn mode or set a raw axis descriptor manually.
+      "rightStickVertical": {
+        "kind": "axis", // Analog binding input source kind. Values: none | axis
+        "axisIndex": 4, // Raw axis index captured for this analog controller action.
+        "dpadFallback": "none" // Optional D-pad fallback used when this analog controller action should also read D-pad input. Values: none | horizontal | vertical
+      } // Axis binding descriptor used for popup page jumps. Use Alt+C learn mode or set a raw axis descriptor manually.
+    } // Raw controller binding descriptors saved by Alt+C learn mode. For discrete axis bindings, kind "axis" requires axisIndex and direction.
+  }, // Gamepad support for the visible overlay while keyboard-only mode is active.
+
   // ==========================================
   // Startup Warmups
   // Background warmup controls for MeCab, Yomitan, dictionaries, and Jellyfin session.
@@ -81,22 +172,146 @@
     "multiCopyTimeoutMs": 3000, // Timeout for multi-copy/mine modes.
     "toggleSecondarySub": "CommandOrControl+Shift+V", // Toggle secondary sub setting.
     "markAudioCard": "CommandOrControl+Shift+A", // Mark audio card setting.
+    "openCharacterDictionary": "CommandOrControl+Alt+A", // Open character dictionary setting.
     "openRuntimeOptions": "CommandOrControl+Shift+O", // Open runtime options setting.
-    "openJimaku": "Ctrl+Shift+J" // Open jimaku setting.
+    "openJimaku": "Ctrl+Shift+J", // Open jimaku setting.
+    "openSessionHelp": "CommandOrControl+Slash", // Open session help setting.
+    "openControllerSelect": "Alt+C", // Open controller select setting.
+    "openControllerDebug": "Alt+Shift+C", // Open controller debug setting.
+    "toggleSubtitleSidebar": "Backslash" // Toggle subtitle sidebar setting.
   }, // Overlay keyboard shortcuts. Set a shortcut to null to disable.
 
   // ==========================================
   // Keybindings (MPV Commands)
-  // Extra keybindings that are merged with built-in defaults.
+  // Default and custom keybindings that are merged with built-in defaults.
   // Set command to null to disable a default keybinding.
   // Hot-reload: keybinding changes apply live and update the session help modal on reopen.
   // ==========================================
-  "keybindings": [], // Extra keybindings that are merged with built-in defaults.
+  "keybindings": [
+    {
+      "key": "Space", // Key setting.
+      "command": [
+        "cycle",
+        "pause"
+      ] // Command setting.
+    },
+    {
+      "key": "KeyF", // Key setting.
+      "command": [
+        "cycle",
+        "fullscreen"
+      ] // Command setting.
+    },
+    {
+      "key": "KeyJ", // Key setting.
+      "command": [
+        "cycle",
+        "sid"
+      ] // Command setting.
+    },
+    {
+      "key": "Shift+KeyJ", // Key setting.
+      "command": [
+        "cycle",
+        "secondary-sid"
+      ] // Command setting.
+    },
+    {
+      "key": "ArrowRight", // Key setting.
+      "command": [
+        "seek",
+        5
+      ] // Command setting.
+    },
+    {
+      "key": "ArrowLeft", // Key setting.
+      "command": [
+        "seek",
+        -5
+      ] // Command setting.
+    },
+    {
+      "key": "ArrowUp", // Key setting.
+      "command": [
+        "seek",
+        60
+      ] // Command setting.
+    },
+    {
+      "key": "ArrowDown", // Key setting.
+      "command": [
+        "seek",
+        -60
+      ] // Command setting.
+    },
+    {
+      "key": "Shift+KeyH", // Key setting.
+      "command": [
+        "sub-seek",
+        -1
+      ] // Command setting.
+    },
+    {
+      "key": "Shift+KeyL", // Key setting.
+      "command": [
+        "sub-seek",
+        1
+      ] // Command setting.
+    },
+    {
+      "key": "Shift+BracketRight", // Key setting.
+      "command": [
+        "__sub-delay-next-line"
+      ] // Command setting.
+    },
+    {
+      "key": "Shift+BracketLeft", // Key setting.
+      "command": [
+        "__sub-delay-prev-line"
+      ] // Command setting.
+    },
+    {
+      "key": "Ctrl+Alt+KeyC", // Key setting.
+      "command": [
+        "__youtube-picker-open"
+      ] // Command setting.
+    },
+    {
+      "key": "Ctrl+Alt+KeyP", // Key setting.
+      "command": [
+        "__playlist-browser-open"
+      ] // Command setting.
+    },
+    {
+      "key": "Ctrl+Shift+KeyH", // Key setting.
+      "command": [
+        "__replay-subtitle"
+      ] // Command setting.
+    },
+    {
+      "key": "Ctrl+Shift+KeyL", // Key setting.
+      "command": [
+        "__play-next-subtitle"
+      ] // Command setting.
+    },
+    {
+      "key": "KeyQ", // Key setting.
+      "command": [
+        "quit"
+      ] // Command setting.
+    },
+    {
+      "key": "Ctrl+KeyW", // Key setting.
+      "command": [
+        "quit"
+      ] // Command setting.
+    }
+  ], // Default and custom keybindings that are merged with built-in defaults.
 
   // ==========================================
   // Secondary Subtitles
   // Dual subtitle track options.
-  // Used by subminer YouTube subtitle generation as secondary language preferences.
+  // Used by managed subtitle loading as secondary language preferences for local and YouTube playback.
   // Hot-reload: defaultMode updates live while SubMiner is running.
   // ==========================================
   "secondarySub": {
@@ -131,15 +346,16 @@
   // Hot-reload: subtitle style changes apply live without restarting SubMiner.
   // ==========================================
   "subtitleStyle": {
+    "primaryDefaultMode": "visible", // Default primary subtitle bar visibility mode. hidden hides it, visible shows it, hover reveals it on hover. Values: hidden | visible | hover
     "enableJlpt": false, // Enable JLPT vocabulary level underlines. When disabled, JLPT tagging lookup and underlines are skipped. Values: true | false
     "preserveLineBreaks": false, // Preserve line breaks in visible overlay subtitle rendering. When false, line breaks are flattened to spaces for a single-line flow. Values: true | false
     "autoPauseVideoOnHover": true, // Automatically pause mpv playback while hovering subtitle text, then resume on leave. Values: true | false
-    "autoPauseVideoOnYomitanPopup": false, // Automatically pause mpv playback while Yomitan popup is open, then resume when popup closes. Values: true | false
+    "autoPauseVideoOnYomitanPopup": true, // Automatically pause mpv playback while Yomitan popup is open, then resume when popup closes. Values: true | false
     "hoverTokenColor": "#f4dbd6", // Hex color used for hovered subtitle token highlight in mpv.
     "hoverTokenBackgroundColor": "rgba(54, 58, 79, 0.84)", // CSS color used for hovered subtitle token background highlight in mpv.
     "nameMatchEnabled": true, // Enable subtitle token coloring for matches from the SubMiner character dictionary. Values: true | false
     "nameMatchColor": "#f5bde6", // Hex color used when a subtitle token matches an entry from the SubMiner character dictionary.
-    "fontFamily": "M PLUS 1 Medium, Source Han Sans JP, Noto Sans CJK JP", // Font family setting.
+    "fontFamily": "Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP", // Font family setting.
     "fontSize": 35, // Font size setting.
     "fontColor": "#cad3f5", // Font color setting.
     "fontWeight": "600", // Font weight setting.
@@ -148,9 +364,9 @@
     "wordSpacing": 0, // Word spacing setting.
     "fontKerning": "normal", // Font kerning setting.
     "textRendering": "geometricPrecision", // Text rendering setting.
-    "textShadow": "0 3px 10px rgba(0,0,0,0.69)", // Text shadow setting.
+    "textShadow": "0 2px 6px rgba(0,0,0,0.9), 0 0 12px rgba(0,0,0,0.55)", // Text shadow setting.
     "fontStyle": "normal", // Font style setting.
-    "backgroundColor": "rgb(30, 32, 48, 0.88)", // Background color setting.
+    "backgroundColor": "transparent", // Background color setting.
     "backdropFilter": "blur(6px)", // Backdrop filter setting.
     "nPlusOneColor": "#c6a0f6", // N plus one color setting.
     "knownWordColor": "#a6da95", // Known word color setting.
@@ -158,7 +374,7 @@
       "N1": "#ed8796", // N1 setting.
       "N2": "#f5a97f", // N2 setting.
       "N3": "#f9e2af", // N3 setting.
-      "N4": "#a6e3a1", // N4 setting.
+      "N4": "#8bd5ca", // N4 setting.
       "N5": "#8aadf4" // N5 setting.
     }, // Jlpt colors setting.
     "frequencyDictionary": {
@@ -185,22 +401,61 @@
       "wordSpacing": 0, // Word spacing setting.
       "fontKerning": "normal", // Font kerning setting.
       "textRendering": "geometricPrecision", // Text rendering setting.
-      "textShadow": "0 3px 10px rgba(0,0,0,0.69)", // Text shadow setting.
+      "textShadow": "0 2px 6px rgba(0,0,0,0.9), 0 0 12px rgba(0,0,0,0.55)", // Text shadow setting.
       "backgroundColor": "transparent", // Background color setting.
       "backdropFilter": "blur(6px)", // Backdrop filter setting.
-      "fontWeight": "normal", // Font weight setting.
+      "fontWeight": "600", // Font weight setting.
       "fontStyle": "normal" // Font style setting.
     } // Secondary setting.
   }, // Primary and secondary subtitle styling.
 
+  // ==========================================
+  // Subtitle Sidebar
+  // Parsed-subtitle sidebar cue list styling, behavior, and toggle key.
+  // Hot-reload: subtitle sidebar changes apply live without restarting SubMiner.
+  // ==========================================
+  "subtitleSidebar": {
+    "enabled": true, // Enable the subtitle sidebar feature for parsed subtitle sources. Values: true | false
+    "autoOpen": false, // Automatically open the subtitle sidebar once during overlay startup. Values: true | false
+    "layout": "overlay", // Render the subtitle sidebar as a floating overlay or reserve space inside mpv. Values: overlay | embedded
+    "toggleKey": "Backslash", // KeyboardEvent.code used to toggle the subtitle sidebar open and closed.
+    "pauseVideoOnHover": false, // Pause mpv while hovering the subtitle sidebar, then resume on leave. Values: true | false
+    "autoScroll": true, // Auto-scroll the active subtitle cue into view while playback advances. Values: true | false
+    "maxWidth": 420, // Maximum sidebar width in CSS pixels.
+    "opacity": 0.95, // Base opacity applied to the sidebar shell.
+    "backgroundColor": "rgba(73, 77, 100, 0.9)", // Background color for the subtitle sidebar shell.
+    "textColor": "#cad3f5", // Default cue text color in the subtitle sidebar.
+    "fontFamily": "\"M PLUS 1\", \"Noto Sans CJK JP\", sans-serif", // Font family used for subtitle sidebar cue text.
+    "fontSize": 16, // Base font size for subtitle sidebar cue text in CSS pixels.
+    "timestampColor": "#a5adcb", // Timestamp color in the subtitle sidebar.
+    "activeLineColor": "#f5bde6", // Text color for the active subtitle cue.
+    "activeLineBackgroundColor": "rgba(138, 173, 244, 0.22)", // Background color for the active subtitle cue.
+    "hoverLineBackgroundColor": "rgba(54, 58, 79, 0.84)" // Background color for hovered subtitle cues.
+  }, // Parsed-subtitle sidebar cue list styling, behavior, and toggle key.
+
+  // ==========================================
+  // Shared AI Provider
+  // Canonical OpenAI-compatible provider transport settings shared by Anki and YouTube subtitle fixing.
+  // ==========================================
+  "ai": {
+    "enabled": false, // Enable shared OpenAI-compatible AI provider features. Values: true | false
+    "apiKey": "", // Static API key for the shared OpenAI-compatible AI provider.
+    "apiKeyCommand": "", // Shell command used to resolve the shared AI provider API key.
+    "model": "openai/gpt-4o-mini", // Model setting.
+    "baseUrl": "https://openrouter.ai/api", // Base URL for the shared OpenAI-compatible AI provider.
+    "systemPrompt": "You are a translation engine. Return only the translated text with no explanations.", // System prompt setting.
+    "requestTimeoutMs": 15000 // Timeout in milliseconds for shared AI provider requests.
+  }, // Canonical OpenAI-compatible provider transport settings shared by Anki and YouTube subtitle fixing.
+
   // ==========================================
   // AnkiConnect Integration
   // Automatic Anki updates and media generation options.
-  // Hot-reload: AI translation settings update live while SubMiner is running.
+  // Hot-reload: ankiConnect.ai.enabled updates 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.
   // ==========================================
   "ankiConnect": {
-    "enabled": false, // Enable AnkiConnect integration. Values: true | false
+    "enabled": true, // Enable AnkiConnect integration. Values: true | false
     "url": "http://127.0.0.1:8765", // Url setting.
     "pollingRate": 3000, // Polling interval in milliseconds.
     "proxy": {
@@ -213,6 +468,7 @@
       "SubMiner"
     ], // Tags to add to cards mined or updated by SubMiner. Provide an empty array to disable automatic tagging.
     "fields": {
+      "word": "Expression", // Card field for the mined word or expression text.
       "audio": "ExpressionAudio", // Audio setting.
       "image": "Picture", // Image setting.
       "sentence": "Sentence", // Sentence setting.
@@ -220,13 +476,9 @@
       "translation": "SelectionText" // Translation setting.
     }, // Fields setting.
     "ai": {
-      "enabled": false, // Enabled setting. Values: true | false
-      "alwaysUseAiTranslation": false, // Always use ai translation setting. Values: true | false
-      "apiKey": "", // Api key setting.
-      "model": "openai/gpt-4o-mini", // Model setting.
-      "baseUrl": "https://openrouter.ai/api", // Base url setting.
-      "targetLanguage": "English", // Target language setting.
-      "systemPrompt": "You are a translation engine. Return only the translated text with no explanations." // System prompt setting.
+      "enabled": false, // Enable AI provider usage for Anki translation/enrichment flows. Values: true | false
+      "model": "", // Optional model override for Anki AI translation/enrichment flows.
+      "systemPrompt": "" // Optional system prompt override for Anki AI translation/enrichment flows.
     }, // Ai setting.
     "media": {
       "generateAudio": true, // Generate audio setting. Values: true | false
@@ -237,10 +489,19 @@
       "animatedFps": 10, // Animated fps setting.
       "animatedMaxWidth": 640, // Animated max width setting.
       "animatedCrf": 35, // Animated crf setting.
+      "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
       "audioPadding": 0.5, // Audio padding setting.
       "fallbackDuration": 3, // Fallback duration setting.
       "maxMediaDuration": 30 // Max media duration setting.
     }, // Media setting.
+    "knownWords": {
+      "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
+      "refreshMinutes": 1440, // Minutes between known-word cache refreshes.
+      "addMinedWordsImmediately": true, // Immediately append newly mined card words into the known-word cache. Values: true | false
+      "matchMode": "headword", // Known-word matching strategy for subtitle annotations. Values: headword | surface
+      "decks": {}, // Decks and fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word", "Word Reading"] }.
+      "color": "#a6da95" // Color used for known-word highlights.
+    }, // Known words setting.
     "behavior": {
       "overwriteAudio": true, // Overwrite audio setting. Values: true | false
       "overwriteImage": true, // Overwrite image setting. Values: true | false
@@ -250,13 +511,8 @@
       "autoUpdateNewCards": true // Automatically update newly added cards. Values: true | false
     }, // Behavior setting.
     "nPlusOne": {
-      "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
-      "refreshMinutes": 1440, // Minutes between known-word cache refreshes.
-      "matchMode": "headword", // Known-word matching strategy for N+1 highlighting. Values: headword | surface
-      "decks": [], // Decks used for N+1 known-word cache scope. Supports one or more deck names.
       "minSentenceWords": 3, // Minimum sentence word count required for N+1 targeting (default: 3).
-      "nPlusOne": "#c6a0f6", // Color used for the single N+1 target token highlight.
-      "knownWord": "#a6da95" // Color used for legacy known-word highlights.
+      "nPlusOne": "#c6a0f6" // Color used for the single N+1 target token highlight.
     }, // N plus one setting.
     "metadata": {
       "pattern": "[SubMiner] %f (%t)" // Pattern setting.
@@ -283,18 +539,15 @@
   }, // Jimaku API configuration and defaults.
 
   // ==========================================
-  // YouTube Subtitle Generation
-  // Defaults for subminer YouTube subtitle extraction/transcription mode.
+  // YouTube Playback Settings
+  // Defaults for managed subtitle language preferences and YouTube subtitle loading.
   // ==========================================
-  "youtubeSubgen": {
-    "mode": "automatic", // YouTube subtitle generation mode for the launcher script. Values: automatic | preprocess | off
-    "whisperBin": "", // Path to whisper.cpp CLI used as fallback transcription engine.
-    "whisperModel": "", // Path to whisper model used for fallback transcription.
+  "youtube": {
     "primarySubLanguages": [
       "ja",
       "jpn"
-    ] // Comma-separated primary subtitle language priority used by the launcher.
-  }, // Defaults for subminer YouTube subtitle extraction/transcription mode.
+    ] // Comma-separated primary subtitle language priority for managed subtitle auto-selection.
+  }, // Defaults for managed subtitle language preferences and YouTube subtitle loading.
 
   // ==========================================
   // Anilist
@@ -319,6 +572,28 @@
     } // Character dictionary setting.
   }, // Anilist API credentials and update behavior.
 
+  // ==========================================
+  // Yomitan
+  // Optional external Yomitan profile integration.
+  // Setting yomitan.externalProfilePath switches SubMiner to read-only external-profile mode.
+  // For GameSentenceMiner on Linux, the default overlay profile is usually ~/.config/gsm_overlay.
+  // In external-profile mode SubMiner will not import, delete, or modify Yomitan dictionaries/settings.
+  // ==========================================
+  "yomitan": {
+    "externalProfilePath": "" // Optional external Yomitan Electron profile path to use in read-only mode for shared dictionaries/settings. Example: ~/.config/gsm_overlay
+  }, // Optional external Yomitan profile integration.
+
+  // ==========================================
+  // MPV Launcher
+  // Optional mpv.exe override for Windows playback entry points.
+  // Set mpv.launchMode to choose normal, maximized, or fullscreen SubMiner-managed mpv playback.
+  // Leave mpv.executablePath blank to auto-discover mpv.exe from SUBMINER_MPV_PATH or PATH.
+  // ==========================================
+  "mpv": {
+    "executablePath": "", // Optional absolute path to mpv.exe for Windows launch flows. Leave empty to auto-discover from SUBMINER_MPV_PATH or PATH.
+    "launchMode": "normal" // Default window state for SubMiner-managed mpv launches. Values: normal | maximized | fullscreen
+  }, // Optional mpv.exe override for Windows playback entry points.
+
   // ==========================================
   // Jellyfin
   // Optional Jellyfin integration for auth, browsing, and playback launch.
@@ -328,6 +603,7 @@
   "jellyfin": {
     "enabled": false, // Enable optional Jellyfin integration and CLI control commands. Values: true | false
     "serverUrl": "", // Base Jellyfin server URL (for example: http://localhost:8096).
+    "recentServers": [], // Recently authenticated Jellyfin server URLs shown in setup.
     "username": "", // Default Jellyfin username used during CLI login.
     "deviceId": "subminer", // Device id setting.
     "clientName": "SubMiner", // Client name setting.
@@ -358,7 +634,8 @@
   // Uses official SubMiner Discord app assets for polished card visuals.
   // ==========================================
   "discordPresence": {
-    "enabled": false, // Enable optional Discord Rich Presence updates. Values: true | false
+    "enabled": true, // Enable optional Discord Rich Presence updates. Values: true | false
+    "presenceStyle": "default", // Presence card text preset: "default" (clean bilingual), "meme" (Mining and crafting), "japanese" (fully JP), or "minimal".
     "updateIntervalMs": 3000, // Minimum interval between presence payload updates.
     "debounceMs": 750 // Debounce delay used to collapse bursty presence updates.
   }, // Optional Discord Rich Presence activity card updates for current playback/study session.
@@ -377,12 +654,33 @@
     "queueCap": 1000, // In-memory write queue cap before overflow policy applies.
     "payloadCapBytes": 256, // Max JSON payload size per event before truncation.
     "maintenanceIntervalMs": 86400000, // Maintenance cadence (prune + rollup + vacuum checks).
+    "retentionMode": "preset", // Retention mode (`preset` uses preset values, `advanced` uses explicit values). Values: preset | advanced
+    "retentionPreset": "balanced", // Retention preset when `retentionMode` is `preset`. Values: minimal | balanced | deep-history
     "retention": {
-      "eventsDays": 7, // Raw event retention window in days.
-      "telemetryDays": 30, // Telemetry retention window in days.
-      "dailyRollupsDays": 365, // Daily rollup retention window in days.
-      "monthlyRollupsDays": 1825, // Monthly rollup retention window in days.
-      "vacuumIntervalDays": 7 // Minimum days between VACUUM runs.
-    } // Retention setting.
-  } // Enable/disable immersion tracking.
+      "eventsDays": 0, // Raw event retention window in days. Use 0 to keep all.
+      "telemetryDays": 0, // Telemetry retention window in days. Use 0 to keep all.
+      "sessionsDays": 0, // Session retention window in days. Use 0 to keep all.
+      "dailyRollupsDays": 0, // Daily rollup retention window in days. Use 0 to keep all.
+      "monthlyRollupsDays": 0, // Monthly rollup retention window in days. Use 0 to keep all.
+      "vacuumIntervalDays": 0 // Minimum days between VACUUM runs. Use 0 to disable.
+    }, // Retention setting.
+    "lifetimeSummaries": {
+      "global": true, // Maintain global lifetime stats rows. Values: true | false
+      "anime": true, // Maintain per-anime lifetime stats rows. Values: true | false
+      "media": true // Maintain per-media lifetime stats rows. Values: true | false
+    } // Lifetime summaries setting.
+  }, // Enable/disable immersion tracking.
+
+  // ==========================================
+  // Stats Dashboard
+  // Local immersion stats dashboard served on localhost and available as an in-app overlay.
+  // Uses the immersion tracking database for overview, trends, sessions, and vocabulary views.
+  // ==========================================
+  "stats": {
+    "toggleKey": "Backquote", // Key code to toggle the stats overlay.
+    "markWatchedKey": "KeyW", // Key code to mark the current video as watched and advance to the next playlist entry.
+    "serverPort": 6969, // Port for the stats HTTP server.
+    "autoStartServer": true, // Automatically start the stats server on launch. Values: true | false
+    "autoOpenBrowser": false // Automatically open the stats dashboard in a browser when the server starts. Values: true | false
+  } // Local immersion stats dashboard served on localhost and available as an in-app overlay.
 }

docs-site/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+.vitepress/cache/
+.vitepress/dist/
+.DS_Store
+.codex/
+.agents/
+**/CLAUDE.md
+.claude/*

docs-site/.vitepress/config.ts

@@ -0,0 +1,145 @@
+const DOCS_HOSTNAME = 'https://docs.subminer.moe';
+
+function pageToCanonicalHref(page: string): string | null {
+  if (page === '404.md') return null;
+
+  const route = page
+    .replace(/(^|\/)index\.md$/, '')
+    .replace(/\.md$/, '')
+    .replace(/\/$/, '');
+  return route ? `${DOCS_HOSTNAME}/${route}` : `${DOCS_HOSTNAME}/`;
+}
+
+export default {
+  title: 'SubMiner Docs',
+  description:
+    'SubMiner: an MPV immersion-mining overlay with Yomitan and AnkiConnect integration.',
+  head: [
+    ['link', { rel: 'icon', href: '/favicon.ico', sizes: 'any' }],
+    [
+      'link',
+      {
+        rel: 'icon',
+        type: 'image/png',
+        href: '/favicon-32x32.png',
+        sizes: '32x32',
+      },
+    ],
+    [
+      'link',
+      {
+        rel: 'icon',
+        type: 'image/png',
+        href: '/favicon-16x16.png',
+        sizes: '16x16',
+      },
+    ],
+    [
+      'link',
+      {
+        rel: 'apple-touch-icon',
+        href: '/apple-touch-icon.png',
+        sizes: '180x180',
+      },
+    ],
+  ],
+  appearance: 'dark',
+  cleanUrls: true,
+  metaChunk: true,
+  sitemap: {
+    hostname: DOCS_HOSTNAME,
+    transformItems(items) {
+      return items.filter(
+        (item) => item.url !== 'README' && item.url !== `${DOCS_HOSTNAME}/README`,
+      );
+    },
+  },
+  transformHead({ page }) {
+    const href = pageToCanonicalHref(page);
+    return href ? [['link', { rel: 'canonical', href }]] : [];
+  },
+  lastUpdated: true,
+  srcExclude: ['subagents/**'],
+  markdown: {
+    theme: {
+      light: 'catppuccin-latte',
+      dark: 'catppuccin-macchiato',
+    },
+  },
+  themeConfig: {
+    logo: {
+      light: '/assets/SubMiner.png',
+      dark: '/assets/SubMiner.png',
+    },
+    siteTitle: 'SubMiner Docs',
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Get Started', link: '/installation' },
+      { text: 'Mining', link: '/mining-workflow' },
+      { text: 'Configuration', link: '/configuration' },
+      { text: 'Changelog', link: '/changelog' },
+      { text: 'Troubleshooting', link: '/troubleshooting' },
+    ],
+    sidebar: [
+      {
+        text: 'Getting Started',
+        items: [
+          { text: 'Overview', link: '/' },
+          { text: 'Installation', link: '/installation' },
+          { text: 'Usage', link: '/usage' },
+          { text: 'Mining Workflow', link: '/mining-workflow' },
+          { text: 'Launcher Script', link: '/launcher-script' },
+        ],
+      },
+      {
+        text: 'Reference',
+        items: [
+          { text: 'Configuration', link: '/configuration' },
+          { text: 'Keyboard Shortcuts', link: '/shortcuts' },
+          { text: 'Subtitle Annotations', link: '/subtitle-annotations' },
+          { text: 'Subtitle Sidebar', link: '/subtitle-sidebar' },
+          { text: 'Immersion Tracking', link: '/immersion-tracking' },
+          { text: 'Troubleshooting', link: '/troubleshooting' },
+        ],
+      },
+      {
+        text: 'Integrations',
+        items: [
+          { text: 'MPV Plugin', link: '/mpv-plugin' },
+          { text: 'Anki', link: '/anki-integration' },
+          { text: 'Jellyfin', link: '/jellyfin-integration' },
+          { text: 'YouTube', link: '/youtube-integration' },
+          { text: 'Jimaku', link: '/jimaku-integration' },
+          { text: 'AniList', link: '/anilist-integration' },
+          { text: 'Character Dictionary', link: '/character-dictionary' },
+        ],
+      },
+      {
+        text: 'Development',
+        items: [
+          { text: 'Building & Testing', link: '/development' },
+          { text: 'Architecture', link: '/architecture' },
+          { text: 'IPC + Runtime Contracts', link: '/ipc-contracts' },
+          { text: 'WebSocket + Texthooker API', link: '/websocket-texthooker-api' },
+          { text: 'Changelog', link: '/changelog' },
+        ],
+      },
+    ],
+    search: {
+      provider: 'local',
+    },
+    footer: {
+      message: 'Released under the GPL-3.0 License.',
+      copyright: 'Copyright © 2026-present sudacode',
+    },
+    editLink: {
+      pattern: 'https://github.com/ksyasuda/SubMiner/edit/main/docs-site/:path',
+      text: 'Edit this page on GitHub',
+    },
+    outline: { level: [2, 3], label: 'On this page' },
+    externalLinkIcon: true,
+    docFooter: { prev: 'Previous', next: 'Next' },
+    returnToTopLabel: 'Back to top',
+    socialLinks: [{ icon: 'github', link: 'https://github.com/ksyasuda/SubMiner' }],
+  },
+};

docs-site/.vitepress/theme/TuiLayout.vue

@@ -0,0 +1,18 @@
+<script setup>
+import DefaultTheme from 'vitepress/theme';
+import StatusLine from './components/StatusLine.vue';
+import BlinkingCursor from './components/BlinkingCursor.vue';
+
+const { Layout } = DefaultTheme;
+</script>
+
+<template>
+  <Layout>
+    <template #home-hero-info-after>
+      <BlinkingCursor />
+    </template>
+    <template #layout-bottom>
+      <StatusLine />
+    </template>
+  </Layout>
+</template>

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

@@ -0,0 +1,3 @@
+<template>
+  <span class="tui-cursor" aria-hidden="true">█</span>
+</template>

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

@@ -0,0 +1,48 @@
+<script setup>
+import { useRoute, useData } from 'vitepress';
+import { computed } from 'vue';
+
+const route = useRoute();
+const { page, frontmatter } = useData();
+
+const mode = computed(() => {
+  const layout = frontmatter.value.layout;
+  if (layout === 'home') return 'HOME';
+  return 'NORMAL';
+});
+
+const filePath = computed(() => {
+  const path = route.path;
+  return path === '/' ? 'index.md' : `${path.replace(/^\//, '')}.md`;
+});
+
+const section = computed(() => {
+  const path = route.path;
+  if (path === '/') return 'root';
+  const parts = path.split('/').filter(Boolean);
+  return parts[0] || 'root';
+});
+
+const lastUpdated = computed(() => {
+  if (!page.value.lastUpdated) return '';
+  const date = new Date(page.value.lastUpdated);
+  return date.toISOString().slice(0, 10);
+});
+</script>
+
+<template>
+  <footer class="tui-statusline" aria-label="Page info">
+    <div class="tui-statusline__left">
+      <span class="tui-statusline__mode" :data-mode="mode">{{ mode }}</span>
+      <span class="tui-statusline__sep"></span>
+      <span class="tui-statusline__file">{{ filePath }}</span>
+    </div>
+    <div class="tui-statusline__right">
+      <span class="tui-statusline__section">{{ section }}</span>
+      <span class="tui-statusline__sep"></span>
+      <span v-if="lastUpdated" class="tui-statusline__date">{{ lastUpdated }}</span>
+      <span v-if="lastUpdated" class="tui-statusline__sep"></span>
+      <span class="tui-statusline__branch">GPL-3.0</span>
+    </div>
+  </footer>
+</template>

docs-site/.vitepress/theme/index.ts

@@ -0,0 +1,232 @@
+import DefaultTheme from 'vitepress/theme';
+import { useRoute } from 'vitepress';
+import { nextTick, onMounted, watch } from 'vue';
+import '@catppuccin/vitepress/theme/macchiato/mauve.css';
+import './tui-theme.css';
+import './mermaid-modal.css';
+import TuiLayout from './TuiLayout.vue';
+
+let mermaidLoader: Promise<any> | null = null;
+let plausibleTrackerInitialized = false;
+const MERMAID_MODAL_ID = 'mermaid-diagram-modal';
+const PLAUSIBLE_DOMAIN = 'subminer.moe';
+const PLAUSIBLE_ENABLED_HOSTNAMES = new Set(['docs.subminer.moe']);
+const PLAUSIBLE_ENDPOINT = 'https://worker.subminer.moe/api/capture';
+
+async function initPlausibleTracker() {
+  if (typeof window === 'undefined' || plausibleTrackerInitialized) {
+    return;
+  }
+
+  if (!PLAUSIBLE_ENABLED_HOSTNAMES.has(window.location.hostname)) {
+    return;
+  }
+
+  const { init } = await import('@plausible-analytics/tracker');
+  init({
+    domain: PLAUSIBLE_DOMAIN,
+    endpoint: PLAUSIBLE_ENDPOINT,
+    outboundLinks: true,
+    fileDownloads: true,
+    formSubmissions: true,
+    captureOnLocalhost: false,
+  });
+  plausibleTrackerInitialized = true;
+}
+
+function closeMermaidModal() {
+  if (typeof document === 'undefined') {
+    return;
+  }
+
+  const modal = document.getElementById(MERMAID_MODAL_ID);
+  if (!modal) {
+    return;
+  }
+
+  modal.classList.remove('is-open');
+  document.body.classList.remove('mermaid-modal-open');
+}
+
+function ensureMermaidModal(): HTMLDivElement {
+  const existing = document.getElementById(MERMAID_MODAL_ID);
+  if (existing) {
+    return existing as HTMLDivElement;
+  }
+
+  const modal = document.createElement('div');
+  modal.id = MERMAID_MODAL_ID;
+  modal.className = 'mermaid-modal';
+  modal.innerHTML = `
+    <div class="mermaid-modal__backdrop" data-mermaid-close="true"></div>
+    <div class="mermaid-modal__dialog" role="dialog" aria-modal="true" aria-label="Expanded Mermaid diagram">
+      <button class="mermaid-modal__close" type="button" aria-label="Close Mermaid diagram">Close</button>
+      <div class="mermaid-modal__content"></div>
+    </div>
+  `;
+
+  modal.addEventListener('click', (event) => {
+    const target = event.target as HTMLElement | null;
+    if (!target) {
+      return;
+    }
+
+    if (target.closest('[data-mermaid-close="true"]') || target.closest('.mermaid-modal__close')) {
+      closeMermaidModal();
+    }
+  });
+
+  document.addEventListener('keydown', (event) => {
+    if (event.key === 'Escape' && modal.classList.contains('is-open')) {
+      closeMermaidModal();
+    }
+  });
+
+  document.body.appendChild(modal);
+  return modal;
+}
+
+function openMermaidModal(sourceNode: HTMLElement) {
+  if (typeof document === 'undefined') {
+    return;
+  }
+
+  const modal = ensureMermaidModal();
+  const content = modal.querySelector<HTMLDivElement>('.mermaid-modal__content');
+  if (!content) {
+    return;
+  }
+
+  content.replaceChildren(sourceNode.cloneNode(true));
+  modal.classList.add('is-open');
+  document.body.classList.add('mermaid-modal-open');
+}
+
+function attachMermaidInteractions(nodes: HTMLElement[]) {
+  for (const node of nodes) {
+    if (node.dataset.mermaidInteractive === 'true') {
+      continue;
+    }
+
+    const svg = node.querySelector<HTMLElement>('svg');
+    if (!svg) {
+      continue;
+    }
+
+    node.classList.add('mermaid-interactive');
+    node.setAttribute('role', 'button');
+    node.setAttribute('tabindex', '0');
+    node.setAttribute('aria-label', 'Open Mermaid diagram in full view');
+
+    const open = () => openMermaidModal(svg);
+    node.addEventListener('click', open);
+    node.addEventListener('keydown', (event) => {
+      if (event.key === 'Enter' || event.key === ' ') {
+        event.preventDefault();
+        open();
+      }
+    });
+
+    node.dataset.mermaidInteractive = 'true';
+  }
+}
+
+async function getMermaid() {
+  if (!mermaidLoader) {
+    mermaidLoader = import('mermaid').then((module) => {
+      const mermaid = module.default;
+      mermaid.initialize({
+        startOnLoad: false,
+        securityLevel: 'loose',
+        theme: 'base',
+        flowchart: {
+          padding: 16,
+          nodeSpacing: 30,
+          rankSpacing: 40,
+        },
+        themeVariables: {
+          background: '#24273a',
+          primaryColor: '#363a4f',
+          primaryTextColor: '#cad3f5',
+          primaryBorderColor: '#c6a0f6',
+          secondaryColor: '#494d64',
+          secondaryTextColor: '#cad3f5',
+          secondaryBorderColor: '#b7bdf8',
+          tertiaryColor: '#5b6078',
+          tertiaryTextColor: '#cad3f5',
+          tertiaryBorderColor: '#8aadf4',
+          lineColor: '#939ab7',
+          textColor: '#cad3f5',
+          mainBkg: '#363a4f',
+          nodeBorder: '#c6a0f6',
+          clusterBkg: '#1e2030',
+          clusterBorder: '#494d64',
+          edgeLabelBackground: '#24273a',
+          labelTextColor: '#cad3f5',
+        },
+      });
+      return mermaid;
+    });
+  }
+  return mermaidLoader;
+}
+
+async function renderMermaidBlocks() {
+  if (typeof document === 'undefined') {
+    return;
+  }
+  const blocks = Array.from(document.querySelectorAll<HTMLElement>('div.language-mermaid'));
+  if (blocks.length === 0) {
+    return;
+  }
+
+  const mermaid = await getMermaid();
+  const nodes: HTMLElement[] = [];
+
+  for (const block of blocks) {
+    if (block.dataset.mermaidRendered === 'true') {
+      continue;
+    }
+    const code = block.querySelector('pre code');
+    const source = code?.textContent?.trim();
+    if (!source) {
+      continue;
+    }
+
+    const mount = document.createElement('div');
+    mount.className = 'mermaid';
+    mount.textContent = source;
+
+    block.replaceChildren(mount);
+    block.dataset.mermaidRendered = 'true';
+    nodes.push(mount);
+  }
+
+  if (nodes.length > 0) {
+    await mermaid.run({ nodes });
+    attachMermaidInteractions(nodes);
+  }
+}
+
+export default {
+  Layout: TuiLayout,
+  extends: DefaultTheme,
+  setup() {
+    const route = useRoute();
+    const render = () => {
+      nextTick(() => {
+        renderMermaidBlocks().catch((error) => {
+          console.error('Failed to render Mermaid diagram:', error);
+        });
+      });
+    };
+
+    onMounted(() => {
+      initPlausibleTracker().catch((error) => {
+        console.error('Failed to initialize Plausible tracker:', error);
+      });
+      render();
+    });
+    watch(() => route.path, render);
+  },
+};

docs-site/.vitepress/theme/mermaid-modal.css

@@ -0,0 +1,88 @@
+.mermaid-interactive {
+  cursor: zoom-in;
+  transition: outline-color 180ms ease;
+  overflow-x: auto;
+  overflow-y: hidden;
+  text-align: center;
+}
+
+.mermaid-interactive svg {
+  display: inline-block;
+  min-width: 0;
+}
+
+.mermaid-interactive:focus-visible {
+  outline: 2px solid var(--vp-c-brand-1);
+  outline-offset: 4px;
+  border-radius: 0;
+}
+
+.mermaid-modal {
+  position: fixed;
+  inset: 0;
+  z-index: 200;
+  display: none;
+}
+
+.mermaid-modal.is-open {
+  display: block;
+}
+
+.mermaid-modal__backdrop {
+  position: absolute;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.72);
+  backdrop-filter: blur(4px);
+  -webkit-backdrop-filter: blur(4px);
+}
+
+.mermaid-modal__dialog {
+  position: relative;
+  z-index: 1;
+  margin: 4vh auto;
+  width: min(96vw, 1800px);
+  max-height: 92vh;
+  border: 1px solid var(--vp-c-border);
+  border-radius: 0;
+  background: var(--vp-c-bg);
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3), 0 24px 64px rgba(0, 0, 0, 0.2);
+  overflow: hidden;
+}
+
+.mermaid-modal__close {
+  display: block;
+  margin-left: auto;
+  margin-right: 16px;
+  margin-top: 12px;
+  border: 1px solid var(--vp-c-border);
+  border-radius: 0;
+  padding: 4px 10px;
+  background: var(--vp-c-bg-soft);
+  color: var(--vp-c-text-1);
+  font-family: var(--tui-font-mono);
+  font-size: 12px;
+  cursor: pointer;
+  transition: border-color 180ms ease, color 180ms ease;
+}
+
+.mermaid-modal__close:hover {
+  border-color: var(--vp-c-brand-1);
+  color: var(--vp-c-brand-1);
+}
+
+.mermaid-modal__content {
+  overflow: auto;
+  max-height: calc(92vh - 56px);
+  padding: 8px 16px 16px;
+}
+
+.mermaid-modal__content svg {
+  max-width: none;
+  width: max-content;
+  height: auto;
+  min-width: 100%;
+}
+
+body.mermaid-modal-open {
+  overflow: hidden;
+}

docs-site/.vitepress/theme/tui-theme.css

@@ -0,0 +1,689 @@
+@import '@fontsource/jetbrains-mono/400.css';
+@import '@fontsource/jetbrains-mono/500.css';
+@import '@fontsource/jetbrains-mono/600.css';
+@import '@fontsource/jetbrains-mono/700.css';
+
+@font-face {
+  font-family: 'M PLUS 1';
+  src: url('/assets/fonts/Mplus1-Medium.ttf') format('truetype');
+  font-weight: 500;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'Manrope Default';
+  src: url('/assets/fonts/manrope-latin-600-normal.ttf') format('truetype');
+  font-weight: 600;
+  font-style: normal;
+  font-display: swap;
+}
+
+:root {
+  --tui-font-mono: 'JetBrains Mono', 'Cascadia Code', 'Fira Code', monospace;
+  --tui-font-body:
+    'Manrope Default',
+    'M PLUS 1',
+    'Manrope',
+    'Noto Sans CJK JP',
+    'Noto Sans JP',
+    'Hiragino Kaku Gothic ProN',
+    'Meiryo',
+    'Yu Gothic',
+    'Hiragino Sans',
+    system-ui,
+    sans-serif;
+  --tui-transition: 180ms ease;
+
+  /* Theme-specific values — overridden in .dark below */
+  --tui-nav-bg: color-mix(in srgb, var(--vp-c-bg-alt) 88%, transparent);
+  --tui-table-hover-bg: color-mix(in srgb, var(--vp-c-bg-soft) 80%, transparent);
+  --tui-link-underline: color-mix(in srgb, var(--vp-c-brand-1) 40%, transparent);
+  --tui-selection-bg: hsla(267, 83%, 45%, 0.14);
+  --tui-hero-glow: hsla(267, 83%, 45%, 0.05);
+  --tui-step-hover-bg: var(--vp-c-bg-alt);
+  --tui-step-hover-glow: color-mix(in srgb, var(--vp-c-brand-1) 30%, transparent);
+}
+
+.dark {
+  --tui-nav-bg: hsla(232, 23%, 18%, 0.82);
+  --tui-table-hover-bg: hsla(232, 23%, 18%, 0.4);
+  --tui-link-underline: hsla(267, 83%, 80%, 0.3);
+  --tui-selection-bg: hsla(267, 83%, 80%, 0.22);
+  --tui-hero-glow: hsla(267, 83%, 80%, 0.06);
+  --tui-step-hover-bg: hsla(232, 23%, 18%, 0.6);
+  --tui-step-hover-glow: hsla(267, 83%, 80%, 0.3);
+}
+
+:root {
+  --vp-font-family-base: var(--tui-font-body);
+  --vp-font-family-heading: var(--tui-font-body);
+  --vp-font-family-mono: var(--tui-font-mono);
+}
+
+.vp-doc {
+  font-family: var(--vp-font-family-base);
+}
+
+/* === Selection === */
+::selection {
+  background: var(--tui-selection-bg);
+  color: var(--vp-c-text-1);
+}
+
+/* === Scrollbar === */
+::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: var(--vp-c-divider);
+  border-radius: 0;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: var(--vp-c-text-3);
+}
+
+/* === Global transitions === */
+a,
+button,
+.VPFeature,
+.VPNavBarMenuLink,
+.VPSidebarItem .text {
+  transition: color var(--tui-transition), background var(--tui-transition),
+    border-color var(--tui-transition), opacity var(--tui-transition);
+}
+
+/* === Nav bar === */
+.VPNav .VPNavBarTitle .title {
+  font-family: var(--tui-font-mono);
+  font-weight: 600;
+  font-size: 14px;
+  letter-spacing: -0.02em;
+}
+
+.VPNav .VPNavBarMenuLink {
+  font-family: var(--tui-font-mono);
+  font-size: 13px;
+  font-weight: 500;
+}
+
+.VPNav .VPNavBar {
+  border-bottom: 1px solid var(--vp-c-divider);
+  backdrop-filter: blur(12px) saturate(1.2);
+  -webkit-backdrop-filter: blur(12px) saturate(1.2);
+}
+
+.VPNav .VPNavBar:not(.has-sidebar) {
+  background: var(--tui-nav-bg);
+}
+
+.VPNav .VPNavBar.has-sidebar .content {
+  backdrop-filter: blur(12px) saturate(1.2);
+  -webkit-backdrop-filter: blur(12px) saturate(1.2);
+}
+
+/* === Sidebar === */
+.VPSidebar .VPSidebarItem .text {
+  font-family: var(--tui-font-mono);
+  font-size: 13px;
+}
+
+.VPSidebar .VPSidebarItem.is-active.is-link > .item .text::before {
+  content: '> ';
+  color: var(--vp-c-brand-1);
+}
+
+.VPSidebar .VPSidebarItem.is-link:not(.is-active) > .item .text::before {
+  content: '  ';
+  opacity: 0.4;
+}
+
+.VPSidebar .VPSidebarItem.is-link:not(.is-active) > .item:hover .text::before {
+  content: '> ';
+  color: var(--vp-c-text-3);
+  opacity: 0.6;
+}
+
+.VPSidebar .VPSidebarItem.is-link:not(.is-active) > .item:hover .text {
+  color: var(--vp-c-text-1) !important;
+}
+
+.VPSidebar .VPSidebarItem.level-0 > .item .text {
+  font-weight: 700;
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+
+.VPSidebar .VPSidebarItem.level-0 > .item .text::before {
+  content: '# ';
+  color: var(--vp-c-text-3);
+}
+
+.VPSidebar .VPSidebarItem.level-0 .items {
+  border-left: 1px solid var(--vp-c-divider);
+  margin-left: 6px;
+  padding-left: 12px;
+}
+
+/* === Headings === */
+.vp-doc h1,
+.vp-doc h2,
+.vp-doc h3,
+.vp-doc h4 {
+  font-family: var(--vp-font-family-heading);
+}
+
+.vp-doc h1 {
+  letter-spacing: -0.02em;
+}
+
+.vp-doc h1::before {
+  content: '> ';
+  color: var(--vp-c-brand-1);
+  font-weight: 400;
+}
+
+.vp-doc h2 {
+  border-bottom: none;
+  padding-bottom: 4px;
+}
+
+.vp-doc h2::after {
+  content: '';
+  display: block;
+  margin-top: 6px;
+  height: 1px;
+  background: repeating-linear-gradient(
+    to right,
+    var(--vp-c-divider) 0,
+    var(--vp-c-divider) 1ch,
+    transparent 1ch,
+    transparent 1.5ch
+  );
+}
+
+/* === Inline code === */
+.vp-doc :not(pre) > code {
+  border-radius: 0;
+  padding: 2px 6px;
+  font-size: 0.88em;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  color: var(--vp-c-brand-1);
+  font-family: var(--tui-font-mono), 'M PLUS 1', 'Noto Sans CJK JP', 'Noto Sans JP',
+    monospace;
+  font-variant-ligatures: none;
+}
+
+/* === Code blocks === */
+.vp-doc div[class*='language-'] {
+  border-radius: 0;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-alt) !important;
+  font-family: var(--tui-font-mono), 'M PLUS 1', 'Noto Sans CJK JP', 'Noto Sans JP',
+    monospace;
+  font-variant-ligatures: none;
+}
+
+.vp-doc div[class*='language-']::before {
+  font-family: var(--tui-font-mono);
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  color: var(--vp-c-text-3);
+}
+
+.vp-doc div[class*='language-'] > button.copy {
+  border-radius: 0;
+}
+
+/* === Tables === */
+.vp-doc table {
+  border-collapse: collapse;
+  border: 1px solid var(--vp-c-divider);
+}
+
+.vp-doc table th {
+  font-family: var(--tui-font-mono);
+  font-size: 12px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  background: var(--vp-c-bg-soft);
+}
+
+.vp-doc table td,
+.vp-doc table th {
+  border: 1px solid var(--vp-c-divider);
+}
+
+.vp-doc table tr:hover td {
+  background: var(--tui-table-hover-bg);
+}
+
+/* === Links === */
+.vp-doc a {
+  text-decoration: none;
+  border-bottom: 1px solid var(--tui-link-underline);
+  transition: border-color var(--tui-transition), color var(--tui-transition);
+}
+
+.vp-doc a:hover {
+  border-bottom-color: var(--vp-c-brand-1);
+}
+
+/* === Custom containers === */
+.vp-doc .custom-block {
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 0;
+  padding: 16px 20px;
+  margin: 16px 0;
+  position: relative;
+  background: var(--vp-c-bg-soft);
+}
+
+.vp-doc .custom-block::before {
+  font-family: var(--tui-font-mono);
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  position: absolute;
+  top: -1px;
+  left: 12px;
+  transform: translateY(-50%);
+  padding: 0 6px;
+  background: var(--vp-c-bg);
+}
+
+.vp-doc .custom-block.tip,
+.vp-doc .custom-block.info,
+.vp-doc .custom-block.warning,
+.vp-doc .custom-block.danger,
+.vp-doc .custom-block.details {
+  border-left-width: 1px;
+}
+
+.vp-doc .custom-block.tip { border-color: var(--vp-c-brand-1); }
+.vp-doc .custom-block.tip::before { content: '-- tip'; color: var(--vp-c-brand-1); }
+
+.vp-doc .custom-block.info { border-color: var(--vp-c-brand-2); }
+.vp-doc .custom-block.info::before { content: '-- info'; color: var(--vp-c-brand-2); }
+
+.vp-doc .custom-block.warning { border-color: var(--vp-c-warning-1); }
+.vp-doc .custom-block.warning::before { content: '-- warning'; color: var(--vp-c-warning-1); }
+
+.vp-doc .custom-block.danger { border-color: var(--vp-c-danger-1); }
+.vp-doc .custom-block.danger::before { content: '-- danger'; color: var(--vp-c-danger-1); }
+
+.vp-doc .custom-block.details { border-color: var(--vp-c-divider); }
+.vp-doc .custom-block.details::before { content: '-- details'; color: var(--vp-c-text-2); }
+
+.vp-doc .custom-block .custom-block-title {
+  font-family: var(--tui-font-mono);
+  font-size: 13px;
+  font-weight: 600;
+}
+
+/* === Blockquotes === */
+.vp-doc blockquote {
+  border-left: 2px solid var(--vp-c-divider);
+  padding: 4px 0 4px 16px;
+  margin: 16px 0;
+  color: var(--vp-c-text-2);
+  font-style: normal;
+  position: relative;
+}
+
+.vp-doc blockquote::before {
+  content: '│';
+  position: absolute;
+  left: -2px;
+  top: 4px;
+  color: var(--vp-c-brand-1);
+  font-family: var(--tui-font-mono);
+  font-size: 14px;
+  line-height: 1;
+  opacity: 0;
+}
+
+/* === Horizontal rules === */
+.vp-doc hr {
+  border: none;
+  height: 1px;
+  margin: 24px 0;
+  background: repeating-linear-gradient(
+    to right,
+    var(--vp-c-divider) 0,
+    var(--vp-c-divider) 1ch,
+    transparent 1ch,
+    transparent 1.5ch
+  );
+}
+
+/* === Lists === */
+.vp-doc ul > li::marker {
+  color: var(--vp-c-text-3);
+}
+
+.vp-doc ol > li::marker {
+  font-family: var(--tui-font-mono);
+  font-size: 0.85em;
+  color: var(--vp-c-text-3);
+}
+
+/* === Focus-visible === */
+:focus-visible {
+  outline: 2px solid var(--vp-c-brand-1);
+  outline-offset: 2px;
+}
+
+.vp-doc a:focus-visible {
+  outline-offset: 3px;
+  border-bottom-color: transparent;
+}
+
+/* === Feature icon hover === */
+.VPFeatures .VPFeature .icon {
+  transition: transform 280ms ease;
+}
+
+.VPFeatures .VPFeature:hover .icon {
+  transform: translateY(-2px);
+}
+
+/* === Blinking cursor === */
+.tui-cursor {
+  display: inline-block;
+  color: var(--vp-c-brand-1);
+  animation: tui-blink 1s step-end infinite;
+  font-family: var(--tui-font-mono);
+  font-size: 0.9em;
+  vertical-align: baseline;
+  margin-left: 2px;
+  line-height: 1;
+}
+
+@keyframes tui-blink {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0; }
+}
+
+
+/* === Statusline === */
+.tui-statusline {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  z-index: 50;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  height: 28px;
+  padding: 0 12px;
+  font-family: var(--tui-font-mono);
+  font-size: 12px;
+  font-weight: 500;
+  background: var(--vp-c-bg-soft);
+  border-top: 1px solid var(--vp-c-divider);
+  color: var(--vp-c-text-2);
+  user-select: none;
+}
+
+.tui-statusline__left,
+.tui-statusline__right {
+  display: flex;
+  align-items: center;
+  gap: 0;
+}
+
+.tui-statusline__mode {
+  padding: 0 10px;
+  font-weight: 700;
+  font-size: 11px;
+  letter-spacing: 0.04em;
+  color: var(--vp-c-bg);
+  background: var(--vp-c-brand-1);
+  line-height: 28px;
+  margin-left: -12px;
+}
+
+.tui-statusline__mode[data-mode="HOME"] {
+  background: var(--vp-c-brand-2);
+}
+
+.tui-statusline__sep {
+  display: inline-block;
+  margin: 0 2px;
+  color: var(--vp-c-divider);
+}
+
+.tui-statusline__sep::after {
+  content: '|';
+}
+
+.tui-statusline__file {
+  padding: 0 8px;
+  color: var(--vp-c-text-1);
+}
+
+.tui-statusline__section {
+  padding: 0 8px;
+  color: var(--vp-c-text-2);
+}
+
+.tui-statusline__date {
+  padding: 0 8px;
+  color: var(--vp-c-text-3);
+}
+
+.tui-statusline__branch {
+  padding: 0 10px;
+  font-weight: 600;
+  color: var(--vp-c-bg);
+  background: var(--vp-c-brand-3, var(--vp-c-brand-1));
+  line-height: 28px;
+  margin-right: -12px;
+}
+
+body {
+  padding-bottom: 28px;
+}
+
+@media (max-width: 640px) {
+  .tui-statusline__section,
+  .tui-statusline__date {
+    display: none;
+  }
+
+  .VPHome .VPHero::before {
+    display: none;
+  }
+}
+
+/* === Hero === */
+.VPHero .name {
+  font-family: var(--tui-font-mono) !important;
+}
+
+.VPHero .clip {
+  -webkit-text-fill-color: var(--vp-c-brand-1) !important;
+}
+
+.VPHero .text {
+  font-family: var(--tui-font-mono) !important;
+  font-size: 2rem !important;
+}
+
+.VPHero .tagline {
+  font-family: var(--tui-font-body);
+  color: var(--vp-c-text-2);
+}
+
+.VPHero .actions .action .VPButton {
+  font-family: var(--tui-font-mono);
+  font-size: 13px;
+  border-radius: 8px;
+  text-transform: lowercase;
+  transition: all var(--tui-transition);
+}
+
+.VPHero .actions .action .VPButton:hover {
+  transform: translateY(-1px);
+}
+
+.VPHero .actions .action .VPButton::before {
+  content: '[';
+  opacity: 0.5;
+  margin-right: 2px;
+}
+
+.VPHero .actions .action .VPButton::after {
+  content: ']';
+  opacity: 0.5;
+  margin-left: 2px;
+}
+
+.VPHero .image-container .image-bg {
+  opacity: 0.6;
+}
+
+/* === Features === */
+.VPFeatures .VPFeature {
+  border-radius: 8px !important;
+  border: 1px solid var(--vp-c-divider) !important;
+  transition: border-color var(--tui-transition), background var(--tui-transition),
+    transform var(--tui-transition);
+  position: relative;
+  overflow: hidden;
+}
+
+.VPFeatures .VPFeature::after {
+  content: '';
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  width: 0;
+  height: 2px;
+  background: var(--vp-c-brand-1);
+  transition: width 280ms ease;
+}
+
+.VPFeatures .VPFeature:hover {
+  border-color: var(--vp-c-brand-1) !important;
+  transform: translateY(-2px);
+}
+
+.VPFeatures .VPFeature:hover::after {
+  width: 100%;
+}
+
+.VPFeatures .VPFeature .title {
+  font-family: var(--tui-font-mono);
+  font-size: 14px;
+}
+
+.VPFeatures .VPFeature .details {
+  font-family: var(--tui-font-body);
+}
+
+/* === Outline === */
+.VPDocAsideOutline .outline-title {
+  font-family: var(--tui-font-mono);
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.VPDocAsideOutline .outline-link {
+  font-family: var(--tui-font-mono);
+  font-size: 12px;
+  transition: color var(--tui-transition);
+}
+
+.VPDocAsideOutline .outline-link.active {
+  color: var(--vp-c-brand-1);
+}
+
+.VPDocAsideOutline .outline-link.active::before {
+  content: '> ';
+}
+
+/* === Doc footer === */
+.VPDocFooter .edit-link-button,
+.VPDocFooter .last-updated-text {
+  font-family: var(--tui-font-mono);
+  font-size: 12px;
+}
+
+.VPDocFooter .pager-link {
+  border-radius: 0;
+  transition: border-color var(--tui-transition);
+}
+
+.VPDocFooter .pager-link:hover {
+  border-color: var(--vp-c-brand-1);
+}
+
+.VPDocFooter .pager-link .title {
+  font-family: var(--tui-font-mono);
+}
+
+.VPDocFooter .pager-link .desc {
+  font-family: var(--tui-font-mono);
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+/* === Search === */
+.VPLocalSearchBox .search-input {
+  font-family: var(--tui-font-mono);
+}
+
+/* === Background texture === */
+.VPDoc,
+.VPHome {
+  background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 200 200' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='0.015'/%3E%3C/svg%3E");
+  background-repeat: repeat;
+  background-size: 200px 200px;
+}
+
+/* === Hero glow === */
+.VPHome .VPHero {
+  position: relative;
+  overflow: hidden;
+}
+
+.VPHome .VPHero::before {
+  content: '';
+  position: absolute;
+  top: -120px;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 600px;
+  height: 400px;
+  background: radial-gradient(
+    ellipse at center,
+    var(--tui-hero-glow) 0%,
+    transparent 70%
+  );
+  pointer-events: none;
+  z-index: -1;
+}
+
+/* === Footer === */
+.VPFooter {
+  font-family: var(--tui-font-mono);
+  font-size: 12px;
+  border-top: 1px solid var(--vp-c-divider);
+}

docs-site/README.md

@@ -0,0 +1,38 @@
+# SubMiner Docs
+
+In-repo VitePress documentation source for SubMiner.
+
+Internal architecture/workflow source of truth lives in `docs/README.md` at the repo root. Keep `docs-site/` user-facing.
+
+## Local development
+
+```bash
+bun --cwd docs-site install
+bun run docs:dev
+```
+
+Build and preview:
+
+```bash
+bun run docs:build
+bun run docs:preview
+bun run docs:test
+```
+
+Direct package commands still work from `docs-site/` if you prefer:
+
+```bash
+cd docs-site
+bun install
+bun run docs:dev
+```
+
+## Cloudflare Pages
+
+- Git repo: `ksyasuda/SubMiner`
+- Root directory: `docs-site`
+- Build command: `bun run docs:build`
+- Build output directory: `.vitepress/dist`
+- Build watch paths: `docs-site/*`
+
+Cloudflare Pages watch paths use a single `*` wildcard for monorepo subdirectories. `docs-site/*` matches nested files under the docs site; `docs-site/**` can cause docs-only pushes to be skipped.