fix: address latest coderabbit feedback

- Thread `openPlaylistBrowser` action into `IpcRuntimeBootstrapInput`
- Pass `playlistBrowserMainDeps` through bootstrap into `createIpcRuntime`
- Add playlist-browser mock deps to ipc-runtime tests
- Bump subminer-yomitan submodule

.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, docs, and backlog history.
+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
@@ -26,20 +27,50 @@ jobs:
           path: |
             ~/.bun/install/cache
             node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
+            stats/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
           restore-keys: |
             ${{ runner.os }}-bun-
 
       - name: Install dependencies
-        run: bun install --frozen-lockfile
+        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 tsc --noEmit
+        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
 
@@ -54,12 +85,12 @@ jobs:
       - name: Build (bundle)
         run: bun run build
 
+      - name: Immersion SQLite verification
+        run: bun run test:immersion:sqlite:dist
+
       - name: Dist smoke suite
         run: bun run test:smoke:dist
 
-      - name: Build docs
-        run: bun run docs:build
-
       - name: Security audit
         run: bun audit --audit-level high
         continue-on-error: true

.github/workflows/release.yml

@@ -9,9 +9,6 @@ concurrency:
   group: release-${{ github.ref }}
   cancel-in-progress: false
 
-permissions:
-  contents: write
-
 jobs:
   quality-gate:
     runs-on: ubuntu-latest
@@ -32,16 +29,36 @@ jobs:
           path: |
             ~/.bun/install/cache
             node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
+            stats/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
           restore-keys: |
             ${{ runner.os }}-bun-
 
       - name: Install dependencies
-        run: bun install --frozen-lockfile
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Lint stats (formatting)
+        run: bun run lint:stats
+
+      - name: Build (TypeScript check)
+        run: bun run typecheck
 
       - name: Test suite (source)
         run: bun run test:fast
 
+      - name: Coverage suite (maintained source lane)
+        run: bun run test:coverage:src
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-test-src
+          path: coverage/test-src/lcov.info
+          if-no-files-found: error
+
       - name: Launcher smoke suite (source)
         run: bun run test:launcher:smoke:src
 
@@ -56,6 +73,9 @@ jobs:
       - 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
 
@@ -79,13 +99,17 @@ jobs:
           path: |
             ~/.bun/install/cache
             node_modules
+            stats/node_modules
             vendor/texthooker-ui/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/texthooker-ui/package.json') }}
+            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
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
 
       - name: Build texthooker-ui
         run: |
@@ -95,8 +119,17 @@ jobs:
 
       - name: Build AppImage
         run: bun run build:appimage
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - 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
@@ -124,8 +157,10 @@ jobs:
           path: |
             ~/.bun/install/cache
             node_modules
+            stats/node_modules
             vendor/texthooker-ui/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/texthooker-ui/package.json') }}
+            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-
 
@@ -150,7 +185,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: |
@@ -161,7 +198,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 }}
@@ -176,9 +212,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
@@ -197,11 +286,30 @@ 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:
           bun-version: 1.3.5
 
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
       - name: Build Bun subminer wrapper
         run: make build-launcher
 
@@ -211,19 +319,21 @@ 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: |
-          VERSION="${GITHUB_REF#refs/tags/}"
-          tar -czf "release/subminer-assets-${VERSION}.tar.gz" \
+          tar -czf "release/subminer-assets.tar.gz" \
             config.example.jsonc \
-            plugin/subminer.lua \
+            plugin/subminer \
             plugin/subminer.conf \
             assets/themes/subminer.rasi
 
       - 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
@@ -232,65 +342,183 @@ jobs:
 
       - 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: Build changelog artifacts for release
         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)
+          if find changes -maxdepth 1 -name '*.md' -not -name README.md -print -quit | grep -q .; then
+            bun run changelog:build --version "${{ steps.version.outputs.VERSION }}"
           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
+            echo "No pending changelog fragments found."
           fi
-          echo "CHANGES<<EOF" >> $GITHUB_OUTPUT
-          echo "$CHANGES" >> $GITHUB_OUTPUT
-          echo "EOF" >> $GITHUB_OUTPUT
 
-      - name: Create Release
-        uses: softprops/action-gh-release@v2
-        with:
-          name: ${{ steps.version.outputs.VERSION }}
-          body: |
-            ## Changes
-            ${{ steps.changelog.outputs.CHANGES }}
+      - name: Verify changelog is ready for tagged release
+        run: bun run changelog:check --version "${{ steps.version.outputs.VERSION }}"
 
-            ## Installation
+      - name: Generate release notes from changelog
+        run: bun run changelog:release-notes --version "${{ steps.version.outputs.VERSION }}"
 
-            ### AppImage (Recommended)
-            1. Download the AppImage below
-            2. Make it executable: `chmod +x SubMiner-*.AppImage`
-            3. Run: `./SubMiner-*.AppImage`
+      - name: Publish Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
 
-            ### 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
+          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/release-notes.md
+          else
+            gh release create "${{ steps.version.outputs.VERSION }}" \
+              --title "${{ steps.version.outputs.VERSION }}" \
+              --notes-file release/release-notes.md
+          fi
 
-            ### 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.lua` 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`.
-          files: |
+          shopt -s nullglob
+          artifacts=(
             release/*.AppImage
             release/*.dmg
+            release/*.exe
             release/*.zip
             release/*.tar.gz
             release/SHA256SUMS.txt
             dist/launcher/subminer
-          draft: false
-          prerelease: false
+          )
+
+          if [ "${#artifacts[@]}" -eq 0 ]; then
+            echo "No release artifacts found for upload."
+            exit 1
+          fi
+
+          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,13 +1,18 @@
 # Dependencies
 node_modules/
 
+# Superpowers brainstorming
+.superpowers/
+
 # Electron build output
 out/
 dist/
 release/
+build/yomitan/
+coverage/
 
 # Launcher build artifact (produced by make build-launcher)
-subminer
+/subminer
 
 # Logs
 *.log
@@ -21,9 +26,7 @@ Thumbs.db
 .idea/
 *.swp
 *.swo
-**/CLAUDE.md
 environment.toml
-**/CLAUDE.md
 .env
 .vscode/*
 
@@ -34,5 +37,21 @@ docs/.vitepress/cache/
 docs/.vitepress/dist/
 tests/*
 .worktrees/
+.tmp/
 .codex/*
 .agents/*
+!.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

.gitmodules

@@ -5,3 +5,6 @@
 [submodule "vendor/yomitan-jlpt-vocab"]
 	path = vendor/yomitan-jlpt-vocab
 	url = https://github.com/stephenmk/yomitan-jlpt-vocab
+[submodule "vendor/subminer-yomitan"]
+	path = vendor/subminer-yomitan
+	url = https://github.com/ksyasuda/subminer-yomitan

AGENTS.md

@@ -1,3 +1,69 @@
+# AGENTS.MD
+
+## Internal Docs
+
+Start here, then leave this file.
+
+- 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)
+
+`docs-site/` is user-facing. Do not treat it as the canonical internal source of truth.
+
+## Quick Start
+
+- 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`
+
+## Build / Test
+
+- 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`
+
+## Change-Specific Checks
+
+- 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`
+
+## 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
 
 <!-- BACKLOG.MD MCP GUIDELINES START -->
 

Backlog.md

@@ -0,0 +1,266 @@
+# Backlog
+
+Purpose: lightweight repo-local task board. Seeded with current testing / coverage work.
+
+Status keys:
+
+- `todo`: not started
+- `doing`: in progress
+- `blocked`: waiting
+- `done`: shipped
+
+Priority keys:
+
+- `P0`: urgent / release-risk
+- `P1`: high value
+- `P2`: useful cleanup
+- `P3`: nice-to-have
+
+## Active
+
+| ID     | Pri | Status | Area           | Title                                               |
+| ------ | --- | ------ | -------------- | --------------------------------------------------- |
+| SM-013 | P1  | done   | review-followup | Address PR #36 CodeRabbit action items              |
+
+## Ready
+
+| ID     | Pri | Status | Area              | Title                                                            |
+| ------ | --- | ------ | ----------------- | ---------------------------------------------------------------- |
+| SM-001 | P1  | todo   | launcher          | Add tests for CLI parser and args normalizer                     |
+| SM-002 | P1  | todo   | immersion-tracker | Backfill tests for uncovered query exports                       |
+| SM-003 | P1  | todo   | anki              | Add focused field-grouping service + merge edge-case tests       |
+| SM-004 | P2  | todo   | tests             | Extract shared test utils for deps factories and polling helpers |
+| SM-005 | P2  | todo   | tests             | Strengthen weak assertions in app-ready and IPC tests            |
+| SM-006 | P2  | todo   | tests             | Break up monolithic youtube-flow and subtitle-sidebar tests      |
+| SM-007 | P2  | todo   | anilist           | Add tests for AniList rate limiter                               |
+| SM-008 | P3  | todo   | subtitles         | Add core subtitle-position persistence/path tests                |
+| SM-009 | P3  | todo   | tokenizer         | Add tests for JLPT token filter                                  |
+| SM-010 | P1  | todo   | immersion-tracker | Refactor storage + immersion-tracker service into focused modules    |
+| SM-011 | P1  | done   | tests             | Add coverage reporting for maintained test lanes                 |
+| SM-012 | P2  | done   | config/runtime    | Replace JSON serialize-clone helpers with structured cloning     |
+
+## Icebox
+
+None.
+
+## Ticket Details
+
+### SM-001
+
+Title: Add tests for CLI parser and args normalizer
+Priority: P1
+Status: done
+Scope:
+
+- `launcher/config/cli-parser-builder.ts`
+- `launcher/config/args-normalizer.ts`
+  Acceptance:
+- root options parsing covered
+- subcommand routing covered
+- invalid action / invalid log level / invalid backend cases covered
+- target classification covered: file, directory, URL, invalid
+
+### SM-002
+
+Title: Backfill tests for uncovered query exports
+Priority: P1
+Status: todo
+Scope:
+
+- `src/core/services/immersion-tracker/query-*.ts`
+  Targets:
+- headword helpers
+- anime/media detail helpers not covered by existing wrapper tests
+- lexical detail / appearance helpers
+- maintenance helpers beyond `deleteSession` and `upsertCoverArt`
+  Acceptance:
+- every exported query helper either directly tested or explicitly justified as covered elsewhere
+- at least one focused regression per complex SQL branch / aggregation branch
+
+### SM-003
+
+Title: Add focused field-grouping service + merge edge-case tests
+Priority: P1
+Status: todo
+Scope:
+
+- `src/anki-integration/field-grouping.ts`
+- `src/anki-integration/field-grouping-merge.ts`
+  Acceptance:
+- auto/manual/disabled flow branches covered
+- duplicate-card preview failure path covered
+- merge edge cases covered: empty fields, generated media fallback, strict grouped spans, audio synchronization
+
+### SM-004
+
+Title: Extract shared test utils for deps factories and polling helpers
+Priority: P2
+Status: todo
+Scope:
+
+- common `makeDeps` / `createDeps` helpers
+- common `waitForCondition`
+  Acceptance:
+- shared helper module added
+- at least 3 duplicated polling helpers removed
+- at least 5 duplicated deps factories consolidated or clearly prepared for follow-up migration
+
+### SM-005
+
+Title: Strengthen weak assertions in app-ready and IPC tests
+Priority: P2
+Status: todo
+Scope:
+
+- `src/core/services/app-ready.test.ts`
+- `src/core/services/ipc.test.ts`
+  Acceptance:
+- replace broad `assert.ok(...)` presence checks with exact value / order assertions where expected value known
+- handler registration tests assert channel-specific behavior, not only existence
+
+### SM-006
+
+Title: Break up monolithic youtube-flow and subtitle-sidebar tests
+Priority: P2
+Status: todo
+Scope:
+
+- `src/main/runtime/youtube-flow.test.ts`
+- `src/renderer/modals/subtitle-sidebar.test.ts`
+  Acceptance:
+- reduce single-test breadth
+- split largest tests into focused cases by behavior
+- keep semantics unchanged
+
+### SM-007
+
+Title: Add tests for AniList rate limiter
+Priority: P2
+Status: todo
+Scope:
+
+- `src/core/services/anilist/rate-limiter.ts`
+  Acceptance:
+- capacity-window wait behavior covered
+- `x-ratelimit-remaining` + reset handling covered
+- `retry-after` handling covered
+
+### SM-008
+
+Title: Add core subtitle-position persistence/path tests
+Priority: P3
+Status: todo
+Scope:
+
+- `src/core/services/subtitle-position.ts`
+  Acceptance:
+- save/load persistence covered
+- fallback behavior covered
+- path normalization behavior covered for URL vs local target
+
+### SM-009
+
+Title: Add tests for JLPT token filter
+Priority: P3
+Status: todo
+Scope:
+
+- `src/core/services/jlpt-token-filter.ts`
+  Acceptance:
+- excluded term membership covered
+- ignored POS1 membership covered
+- exported list / entry consistency covered
+
+### SM-010
+
+Title: Refactor storage + immersion-tracker service into focused layers without API changes
+Priority: P1
+Status: todo
+Scope:
+
+- `src/core/database/storage/storage.ts`
+- `src/core/database/storage/schema.ts`
+- `src/core/database/storage/cover-blob.ts`
+- `src/core/database/storage/records.ts`
+- `src/core/database/storage/write-path.ts`
+- `src/core/services/immersion-tracker/youtube.ts`
+- `src/core/services/immersion-tracker/youtube-manager.ts`
+- `src/core/services/immersion-tracker/write-queue.ts`
+- `src/core/services/immersion-tracker/immersion-tracker-service.ts`
+
+Acceptance:
+
+- behavior and public API remain unchanged for all callers
+- `storage.ts` responsibilities split into DDL/migrations, cover blob helpers, record CRUD, and write-path execution
+- `immersion-tracker-service.ts` reduces to session state, media change orchestration, query proxies, and lifecycle
+- YouTube code split into pure utilities, a stateful manager (`YouTubeManager`), and a dedicated write queue (`WriteQueue`)
+- removed `storage.ts` is replaced with focused modules and updated imports
+- no API or migration regressions; existing tests for trackers/storage coverage remain green or receive focused updates
+
+### SM-011
+
+Title: Add coverage reporting for maintained test lanes
+Priority: P1
+Status: done
+Scope:
+
+- `package.json`
+- CI workflow files under `.github/`
+- `docs/workflow/verification.md`
+  Acceptance:
+- at least one maintained test lane emits machine-readable coverage output
+- CI surfaces coverage as an artifact, summary, or check output
+- local contributor path for coverage is documented
+- chosen coverage path works with Bun/TypeScript lanes already maintained by the repo
+Implementation note:
+- Added `bun run test:coverage:src` for the maintained source lane via a sharded coverage runner, with merged LCOV output at `coverage/test-src/lcov.info` and CI/release artifact upload as `coverage-test-src`.
+
+### SM-012
+
+Title: Replace JSON serialize-clone helpers with structured cloning
+Priority: P2
+Status: todo
+Scope:
+
+- `src/runtime-options.ts`
+- `src/config/definitions.ts`
+- `src/config/service.ts`
+- `src/main/controller-config-update.ts`
+  Acceptance:
+- runtime/config clone helpers stop using `JSON.parse(JSON.stringify(...))`
+- replacement preserves current behavior for plain config/runtime objects
+- focused tests cover clone/merge behavior that could regress during the swap
+- no new clone helper is introduced in these paths without a documented reason
+
+Done:
+
+- replaced JSON serialize-clone call sites in runtime/config/controller update paths with `structuredClone`
+- updated focused tests and fixtures to cover detached clone behavior and guard against regressions
+
+### SM-013
+
+Title: Address PR #36 CodeRabbit action items
+Priority: P1
+Status: done
+Scope:
+
+- `plugins/subminer-workflow/skills/subminer-change-verification/scripts/verify_subminer_change.sh`
+- `scripts/subminer-change-verification.test.ts`
+- `src/core/services/immersion-tracker/query-sessions.ts`
+- `src/core/services/immersion-tracker/query-trends.ts`
+- `src/core/services/immersion-tracker/maintenance.ts`
+- `src/main/boot/services.ts`
+- `src/main/character-dictionary-runtime/zip.test.ts`
+Acceptance:
+- fix valid open CodeRabbit findings on PR #36
+- add focused regression coverage for behavior changes where practical
+- verify touched tests plus typecheck stay green
+
+Done:
+
+- hardened `--artifact-dir` validation in the verification script
+- fixed trend aggregation rounding and monthly ratio bucketing
+- preserved unwatched anime episodes in episode queries
+- restored seconds-based aggregate timestamps in shared maintenance
+- fixed the startup refactor compile break by making the predicates local at the call site
+- verified with `bun test src/core/services/immersion-tracker/__tests__/query.test.ts src/core/services/immersion-tracker/__tests__/query-split-modules.test.ts` and `bun run typecheck`

CHANGELOG.md

@@ -0,0 +1,316 @@
+# Changelog
+
+## Unreleased
+
+### Fixed
+- AniList: Stopped post-watch tracking from sending a second progress update when the current episode was already satisfied by a ready retry item in the same watch-completion pass.
+
+## 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 docs-dev docs docs-preview dev-start dev-start-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 install-plugin 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_LUA := plugin/subminer.lua
 PLUGIN_CONF := plugin/subminer.conf
 
 # Default install prefix for the wrapper script.
@@ -21,11 +20,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))
@@ -42,6 +36,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:" \
@@ -53,21 +58,23 @@ help:
 		"  clean            Remove build artifacts (dist/, release/, AppImage, binary)" \
 		"  dev-start        Build and launch local Electron app" \
 		"  dev-start-macos  Build and launch local Electron app with macOS tracker backend" \
+		"  dev-watch        Start fast watch loop (tsc + renderer + Electron dev app)" \
+		"  dev-watch-macos  Start watch loop with forced macOS tracker backend" \
 		"  dev-toggle       Toggle overlay in a running local Electron app" \
 		"  dev-stop         Stop a running local Electron app" \
-		"  docs-dev         Run VitePress docs dev server" \
-		"  docs            Build VitePress static docs" \
-		"  docs-preview     Preview built VitePress docs" \
 		"  install-linux    Install Linux wrapper/theme/app artifacts" \
 		"  install-macos    Install macOS wrapper/theme/app artifacts" \
+		"  install-windows  Install Windows mpv plugin artifacts" \
 		"  install-plugin   Install mpv Lua plugin and plugin config" \
 		"  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)" \
@@ -76,7 +83,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' \
@@ -87,6 +94,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)"
@@ -94,19 +105,25 @@ 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:
 	@command -v bun >/dev/null 2>&1 || { printf '%s\n' "[ERROR] bun not found"; exit 1; }
 
 pretty: ensure-bun
-	@bun run format
+	@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
 
@@ -115,6 +132,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
 
@@ -153,18 +171,8 @@ generate-config: ensure-bun
 	@bun run electron . --generate-config
 
 generate-example-config: ensure-bun
-	@bun run build
 	@bun run generate:config-example
 
-docs-dev: ensure-bun
-	@bun run docs:dev
-
-docs: ensure-bun
-	@bun run docs:build
-
-docs-preview: ensure-bun
-	@bun run docs:preview
-
 dev-start: ensure-bun
 	@bun run build
 	@bun run electron . --start
@@ -173,6 +181,12 @@ dev-start-macos: ensure-bun
 	@bun run build
 	@bun run electron . --start --backend macos
 
+dev-watch: ensure-bun
+	@bash scripts/dev-watch.sh
+
+dev-watch-macos: ensure-bun
+	@bash scripts/dev-watch.sh --start --dev --backend macos
+
 dev-toggle: ensure-bun
 	@bun run electron . --toggle
 
@@ -215,16 +229,31 @@ install-macos: build-launcher
 	fi
 	@printf '%s\n' "Installed to:" "  $(BINDIR)/subminer" "  $(MACOS_DATA_DIR)/themes/$(THEME_FILE)" "  $(MACOS_APP_DEST)"
 
+install-windows:
+	@printf '%s\n' "[INFO] Installing Windows mpv plugin artifacts"
+	@$(MAKE) --no-print-directory install-plugin
+
 install-plugin:
 	@printf '%s\n' "[INFO] Installing mpv plugin artifacts"
 	@install -d "$(MPV_SCRIPTS_DIR)"
+	@rm -f "$(MPV_SCRIPTS_DIR)/subminer.lua" "$(MPV_SCRIPTS_DIR)/subminer-loader.lua"
+	@install -d "$(MPV_SCRIPTS_DIR)/subminer"
 	@install -d "$(MPV_SCRIPT_OPTS_DIR)"
-	@install -m 0644 "./$(PLUGIN_LUA)" "$(MPV_SCRIPTS_DIR)/subminer.lua"
+	@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.lua" "  $(MPV_SCRIPT_OPTS_DIR)/subminer.conf"
+	@if [ "$(PLATFORM)" = "windows" ]; then \
+		bun ./scripts/configure-plugin-binary-path.mjs "$(MPV_SCRIPT_OPTS_DIR)/subminer.conf" "$(CURDIR)" win32; \
+	fi
+	@printf '%s\n' "Installed to:" "  $(MPV_SCRIPTS_DIR)/subminer/main.lua" "  $(MPV_SCRIPTS_DIR)/subminer/" "  $(MPV_SCRIPT_OPTS_DIR)/subminer.conf"
 
-# 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"
@@ -236,3 +265,8 @@ uninstall-macos:
 	@rm -f "$(MACOS_DATA_DIR)/themes/$(THEME_FILE)"
 	@rm -rf "$(MACOS_APP_DEST)"
 	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(MACOS_DATA_DIR)/themes/$(THEME_FILE)" "  $(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,95 +1,262 @@
 <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
+
+## Turn mpv into a sentence-mining workstation.
+
+Look up words with Yomitan, export to Anki in one key, track your immersion — all without leaving mpv.
+
+[![License: GPL v3](https://img.shields.io/badge/license-GPLv3-1a1a2e?style=flat-square)](https://www.gnu.org/licenses/gpl-3.0)
+[![Platform](https://img.shields.io/badge/platform-Linux%20·%20macOS%20·%20Windows-1a1a2e?style=flat-square)](https://github.com/ksyasuda/SubMiner)
+[![Docs](https://img.shields.io/badge/docs-docs.subminer.moe-e6a817?style=flat-square)](https://docs.subminer.moe)
+[![AUR](https://img.shields.io/aur/version/subminer-bin?style=flat-square&color=1a1a2e)](https://aur.archlinux.org/packages/subminer-bin)
+
+[![SubMiner demo](./assets/minecard.webp)](./assets/minecard.mp4)
 
 </div>
 
-<br />
+## How It Works
+
+SubMiner runs as an invisible Electron overlay on top of mpv. Subtitles render as an interactive layer. Move your cursor over any word and trigger a [Yomitan](https://github.com/yomidevs/yomitan) lookup. Press one key to snapshot the sentence, audio, and screenshot into Anki via AnkiConnect.
+
+## 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 (GIF preview)](./assets/minecard.gif)](./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
-- **One-key mining** — Creates Anki cards with sentence, audio, screenshot, and translation
-- **N+1 highlighting** — Marks known words from your Anki deck so unknown ones jump out
-- **Subtitle tools** — Download from Jimaku, sync with alass/ffsubsync, all in-player
-- **Immersion tracking** — SQLite-powered stats on your watch time and mining activity
-- **Texthooker page built in** — WebSocket streaming to external tools, no extra setup
+<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.
+
+<br>
+
+### Integrations
+
+<table>
+  <tr>
+    <td><b>YouTube</b></td>
+    <td>Auto-loaded yt-dlp subtitle tracks at startup with a manual overlay picker on demand (<code>Ctrl+Alt+C</code>)</td>
+  </tr>
+  <tr>
+    <td><b>AniList</b></td>
+    <td>Automatic episode tracking and progress sync</td>
+  </tr>
+  <tr>
+    <td><b>Jellyfin</b></td>
+    <td>Browse and launch media from your Jellyfin server</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                                | Optional                                                   |
+| -------------- | --------------------------------------- | ---------------------------------------------------------- |
+| **Player**     | [`mpv`](https://mpv.io) with IPC socket | —                                                          |
+| **Processing** | `ffmpeg`, `mecab` + `mecab-ipadic`      | `guessit` (AniSkip), `alass` / `ffsubsync` (subtitle sync) |
+| **Media**      | —                                       | `yt-dlp`, `chafa`, `ffmpegthumbnailer`                     |
+| **Selection**  | —                                       | `fzf` / `rofi`                                             |
+
+> [!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       |
+| ----------------------------------- | ------------------------ | ------------- |
+| `hyprctl` or `xdotool` + `xwininfo` | Accessibility permission | No extra deps |
+
+<details>
+<summary><b>Arch Linux</b></summary>
+
+```bash
+paru -S --needed mpv ffmpeg mecab-git mecab-ipadic
+# Optional
+paru -S --needed 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
+paru -S --needed xdotool xorg-xwininfo
+```
+
+</details>
+
+<details>
+<summary><b>macOS</b></summary>
+
+```bash
+brew install mpv ffmpeg mecab mecab-ipadic
+# Optional
+brew install 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`.
+
+For MeCab, install [MeCab for Windows](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary.
+
+</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-0.1.0.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** — see the [installation guide](https://docs.subminer.moe/installation#from-source).
+</details>
 
-### 2. Install the mpv plugin and configuration file
+<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`.
+
+</details>
+
+<details>
+<summary><b>Windows</b></summary>
+
+Download the latest installer or portable `.zip` from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). Make sure `mpv` is on your `PATH`.
+
+</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
+
+Run the app. On first launch SubMiner starts in the system tray, creates a default config, and opens a setup popup to install the mpv plugin and configure Yomitan dictionaries.
+
+### 3. Mine
 
 ```bash
-wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets-0.1.0.tar.gz -O /tmp/subminer-assets.tar.gz
-tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
-cp /tmp/plugin/subminer.lua ~/.config/mpv/scripts/
-cp /tmp/plugin/subminer.conf ~/.config/mpv/script-opts/
-mkdir -p ~/.config/SubMiner && cp /tmp/config.example.jsonc ~/.config/SubMiner/config.jsonc
+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
 ```
 
-### 3. Set up Yomitan Dictionaries
-
-```bash
-subminer app --start --yomitan
-```
-
-### 4. Mine
-
-```bash
-subminer app --start --background
-subminer video.mkv
-```
-
-## Requirements
-
-| Required                                   | Optional                                           |
-| ------------------------------------------ | -------------------------------------------------- |
-| `bun`                                      |                                                    |
-| `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            |                                                    |
-
 ## 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)**
+
+---
 
 ## Acknowledgments
 
-Built on the shoulders of [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner), [mpvacious](https://github.com/Ajatt-Tools/mpvacious), [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script), and [autosubsync-mpv](https://github.com/joaquintorres/autosubsync-mpv). 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/milestones/m-0 - codebase-clarity-&-composability.md

@@ -1,8 +0,0 @@
----
-id: m-0
-title: 'Codebase Clarity & Composability'
----
-
-## Description
-
-Improvements to code clarity, simplicity, and composability identified during the Feb 2026 codebase review. Focus on reducing monolithic files, eliminating duplication, and improving architectural boundaries.

backlog/archive/tasks/task-175 - Address-latest-PR-19-review-comments.md

@@ -0,0 +1,33 @@
+---
+id: TASK-175
+title: Address latest PR 19 review comments
+status: In Progress
+assignee: []
+created_date: '2026-03-15 10:25'
+labels:
+  - pr-review
+  - stats-dashboard
+dependencies: []
+references:
+  - src/core/services/ipc.ts
+  - src/core/services/stats-server.ts
+  - src/core/services/immersion-tracker/__tests__/query.test.ts
+  - src/core/services/stats-window-runtime.ts
+  - src/core/services/stats-window.test.ts
+  - src/shared/ipc/contracts.ts
+  - src/main.ts
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Validate the latest automated review comments on PR #19 against the current branch, implement the technically valid fixes, and document any items intentionally left unchanged.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 Validated the latest PR #19 review comments against current branch behavior and existing architecture
+- [ ] #2 Implemented the accepted fixes with regression coverage where it fits
+- [ ] #3 Documented which latest review items were intentionally not changed because they were already addressed or not technically warranted
+<!-- AC:END -->

backlog/archive/tasks/task-19 - Enable-overlay-keybinds-whenever-app-runtime-is-active.md

@@ -1,49 +0,0 @@
----
-id: TASK-19
-title: Enable overlay keybinds whenever app runtime is active
-status: To Do
-assignee: []
-created_date: '2026-02-12 08:47'
-updated_date: '2026-02-12 09:40'
-labels: []
-dependencies: []
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Restored task after accidental cleanup. Ensure keybindings are available whenever the Electron runtime is active, while respecting focused overlay/input contexts that require local key handling.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Started implementation: tracing overlay shortcut registration lifecycle and runtime activation gating.
-
-Root cause: overlay shortcut sync executes during overlay runtime initialization before overlayRuntimeInitialized is set true, so registration could be skipped until a later visibility toggle.
-
-Implemented fix in initializeOverlayRuntime: after setting overlayRuntimeInitialized = true, immediately call syncOverlayShortcuts() to register overlay keybinds for active runtime state.
-
-Follow-up from repro: startup path with --start did not initialize overlay runtime (commandNeedsOverlayRuntime excluded start), so overlay keybinds stayed unavailable until first overlay visibility command.
-
-Updated CLI runtime gating so --start initializes overlay runtime, which activates overlay shortcut registration immediately.
-
-User clarified MPV-only workflow requirement. Added MPV plugin keybindings and script messages for mining/runtime actions (copy/mine/multi/mode/field-grouping/subsync/audio-card/runtime-options) so these actions are available from mpv chord bindings without relying on overlay global shortcuts.
-
-Per user direction, reverted all shortcut/runtime/plugin changes from this implementation cycle. Desired behavior is to keep keybindings working only when overlay is active.
-
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Ensured overlay shortcuts are available as soon as overlay runtime becomes active by resyncing after activation flag is set. This prevents startup states where shortcuts remained inactive until a later overlay visibility change.
-
-Follow-up fix: included --start in overlay-runtime-required commands so keybinds are active right after startup, even before toggling visible/invisible overlays.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/archive/tasks/task-20 - Implement-content-bounded-overlay-windows-and-decoupled-secondary-top-bar.md

@@ -1,30 +0,0 @@
----
-id: TASK-20
-title: Implement content-bounded overlay windows and decoupled secondary top bar
-status: To Do
-assignee: []
-created_date: '2026-02-12 08:47'
-updated_date: '2026-02-12 09:42'
-labels: []
-dependencies: []
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Implement the overlay sizing redesign documented in `overlay_window.md`: move visible/invisible overlays from fullscreen bounds to content-bounded sizing, and decouple secondary subtitle rendering into an independent top bar window/lifecycle.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Per-layer bounds ownership is implemented for overlay windows (no shared full-bounds setter for all layers).
-- [ ] #2 Renderer-to-main IPC contract exists for measured overlay content bounds with layer identity and safe validation.
-- [ ] #3 Visible and invisible overlays use content-bounded sizing with padding/clamp/jitter protections and full-bounds fallback when measurements are unavailable.
-- [ ] #4 Secondary subtitle top bar is decoupled from primary overlay visibility and follows mode-specific behavior.
-- [ ] #5 Automated tests and manual validation matrix cover wrapping, style changes, monitor moves, tracker churn, and simultaneous overlay states.
-<!-- AC:END -->

backlog/archive/tasks/task-20.3 - Implement-content-bounded-sizing-algorithm-for-visible-and-invisible-overlay-windows.md

@@ -1,32 +0,0 @@
----
-id: TASK-20.3
-title: >-
-  Implement content-bounded sizing algorithm for visible and invisible overlay
-  windows
-status: To Do
-assignee: []
-created_date: '2026-02-12 08:47'
-updated_date: '2026-02-12 09:42'
-labels: []
-dependencies: []
-parent_task_id: TASK-20
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Implement content-bounded sizing for visible/invisible windows using measured rects plus tracker origin, with robust clamping and jitter resistance.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Bounds algorithm applies configurable padding, minimum size, display-workarea clamp, and integer snap.
-- [ ] #2 Main-process bounds updates are thresholded/debounced to reduce jitter and unnecessary `setBounds` churn.
-- [ ] #3 When no valid measurement exists, layer falls back to safe tracker/display bounds without breaking interaction.
-- [ ] #4 Visible+invisible overlays can coexist without full-window overlap/input conflicts caused by shared fullscreen bounds.
-<!-- AC:END -->

backlog/archive/tasks/task-20.4 - Implement-dedicated-secondary-top-bar-overlay-window.md

@@ -1,30 +0,0 @@
----
-id: TASK-20.4
-title: Implement dedicated secondary top-bar overlay window
-status: To Do
-assignee: []
-created_date: '2026-02-12 09:43'
-labels: []
-dependencies: []
-parent_task_id: TASK-20
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Create and integrate a dedicated secondary subtitle overlay window with independent lifecycle, z-order, bounds, and pointer policy, decoupled from primary visible/invisible overlay windows.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 A third overlay window dedicated to secondary subtitles is created and managed alongside existing visible/invisible windows.
-- [ ] #2 Secondary window visibility follows secondary mode semantics (`hidden`/`visible`/`hover`) independent of primary overlay visibility.
-- [ ] #3 Secondary subtitle text/mode/style updates are routed directly to the secondary window renderer path.
-- [ ] #4 Pointer passthrough/interaction behavior for secondary window is explicit and does not regress existing hover/selection interactions.
-- [ ] #5 Window cleanup/lifecycle (create, close, restore) integrates with existing overlay runtime lifecycle.
-<!-- AC:END -->

backlog/archive/tasks/task-20.5 - Add-rollout-guards-tests-and-validation-matrix-for-content-bounded-overlays.md

@@ -1,30 +0,0 @@
----
-id: TASK-20.5
-title: 'Add rollout guards, tests, and validation matrix for content-bounded overlays'
-status: To Do
-assignee: []
-created_date: '2026-02-12 09:43'
-labels: []
-dependencies: []
-parent_task_id: TASK-20
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add safety controls and verification coverage for the new content-bounded overlay architecture and secondary top-bar window.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Feature flag or equivalent rollout guard exists for switching to new sizing/window behavior.
-- [ ] #2 Service-level/unit tests cover bounds clamping, jitter thresholding, invalid measurement fallback, and per-layer updates.
-- [ ] #3 Manual validation checklist documents and verifies wrap/no-wrap, style changes, monitor moves, tracker churn, modal interactions, and simultaneous overlay states.
-- [ ] #4 Regression checks confirm existing single-layer and startup/shutdown behavior remain stable.
-- [ ] #5 Task includes explicit pass/fail notes from validation run(s).
-<!-- AC:END -->

backlog/archive/tasks/task-22 - Make-secondary-subtitles-hover-revealed-but-non-lookupable-in-Yomitan-sessions.md

@@ -1,36 +0,0 @@
----
-id: TASK-22
-title: Make secondary subtitles hover-revealed but non-lookupable in Yomitan sessions
-status: To Do
-assignee: []
-created_date: '2026-02-13 16:40'
-labels: []
-dependencies: []
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Investigate and implement a UX where secondary subtitles (e.g., English text in our current sessions) become visible when hovered, while explicitly preventing user interactions that allow text lookup (including Yomitan integration) on those subtitles. This should allow readability-on-hover without exposing the secondary overlay text to selection/lookup workflows.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Secondary subtitles become visible only while hovered (or via equivalent hover-triggered mechanism), and return to default hidden/low-visibility state when not hovered.
-- [ ] #2 When hovered, secondary subtitles do not trigger Yomitan lookup behavior in sessions where Yomitan is enabled.
-- [ ] #3 Secondary subtitles remain non-interactive for lookup paths (for example, text selection or lookup event propagation) while hover-visibility still works as intended.
-- [ ] #4 Primary subtitles remain functional and are not regressed by the secondary-subtitle interaction changes.
-- [ ] #5 If complete prevention of Yomitan lookup on secondary subtitles is not technically possible, the task includes the known limitations and a documented fallback behavior.
-<!-- AC:END -->
-
-## Definition of Done
-
-<!-- DOD:BEGIN -->
-
-- [ ] #1 Acceptance criteria are reviewed and covered by explicit manual/automated test coverage for hover reveal and lookup suppression behavior.
-<!-- DOD:END -->

backlog/archive/tasks/task-30 - Enable-anime-streaming-via-extension-repos-with-configurable-mpv-playback-flow.md

@@ -1,55 +0,0 @@
----
-id: TASK-30
-title: Enable anime streaming via extension repos with configurable mpv playback flow
-status: To Do
-assignee: []
-created_date: '2026-02-13 18:32'
-updated_date: '2026-02-13 18:34'
-labels: []
-dependencies: []
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add a feature to query configured extension repositories for anime titles/episodes from SubMiner, let users select a streamable source, and play it through mpv with minimal friction. The result should be interactive from Electron (and triggered from mpv via existing command bridge), and fully configurable in app config.
-
-The implementation should provide a modular backend resolver and a clear UI flow that mirrors existing modal interaction patterns, while keeping mpv playback unchanged (use loadfile with resolved URL and optional headers/referrer metadata).
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Create a stable config schema for one or more extension source backends (repos/endpoints/flags) and persist in user config + default template.
-- [ ] #2 Resolve an anime search term to candidate series from configured sources.
-- [ ] #3 Resolve an episode selection to at least one playable stream URL candidate with playback metadata when available.
-- [ ] #4 Provide an interactive user flow in the app to search/select episode and choose stream source.
-- [ ] #5 Play the selected stream by invoking the existing mpv command path.
-- [ ] #6 Support launching the flow from mpv interactions (keyboard/menu) by forwarding a command/event into the renderer modal flow.
-- [ ] #7 Add error states for empty results, no playable source, and repository failures, with clear user messages.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Execution sequence for implementation: 1) TASK-30.1 (config/model), 2) TASK-30.2 (resolver), 3) TASK-30.3 (IPC), 4) TASK-30.4 (UI modal), 5) TASK-30.5 (mpv trigger), 6) TASK-30.6 (validation/rollout checklist).
-
-Rollout recommendation: complete TASK-30.6 only after TASK-30.1-30.5 are done and can be verified in combination.
-
-<!-- SECTION:NOTES:END -->
-
-## Definition of Done
-
-<!-- DOD:BEGIN -->
-
-- [ ] #1 Config schema validated in app startup (bad config surfaces clear error).
-- [ ] #2 No hardcoded source/resolver URLs in UI layer; resolver details are backend-driven.
-- [ ] #3 Play command path uses existing mpv IPC/runtime helpers.
-- [ ] #4 Documentation includes how to configure extension repos and optional auth/headers.
-- [ ] #5 Feature is gated behind a config flag and can be disabled cleanly.
-<!-- DOD:END -->

backlog/archive/tasks/task-30.1 - Design-extension-source-config-model-and-defaults.md

@@ -1,48 +0,0 @@
----
-id: TASK-30.1
-title: Design extension source config model and defaults
-status: To Do
-assignee: []
-created_date: '2026-02-13 18:32'
-updated_date: '2026-02-13 18:34'
-labels: []
-dependencies: []
-parent_task_id: TASK-30
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Define a backend-agnostic configuration contract for extension repository streaming, including resolver endpoints/process mode, query/auth headers, timeouts, enable flags, and source preference. Wire schema through Config/ResolvedConfig and generated template/defaults so users can manage repos entirely through config.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Add new config sections for extension source providers in Config and ResolvedConfig types.
-- [ ] #2 Add validation defaults and env-compatible parsing for provider list, auth, header overrides, and feature flags.
-- [ ] #3 Update config template and docs text so defaults are discoverable and editable.
-- [ ] #4 Invalid/missing config should fail fast with a clear message path.
-- [ ] #5 Existing config readers do not regress when no providers are configured.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Phase 1 — Foundation: config contract + validation + defaults
-
-<!-- SECTION:NOTES:END -->
-
-## Definition of Done
-
-<!-- DOD:BEGIN -->
-
-- [ ] #1 Config examples in template/docs include at least one provider entry shape.
-- [ ] #2 Defaults remain backward-compatible when key is absent.
-- [ ] #3 Feature can be disabled without touching unrelated settings.
-<!-- DOD:END -->

backlog/archive/tasks/task-30.2 - Implement-extension-resolver-service-search-episode-stream-resolution.md

@@ -1,50 +0,0 @@
----
-id: TASK-30.2
-title: Implement extension resolver service (search + episode + stream resolution)
-status: To Do
-assignee: []
-created_date: '2026-02-13 18:32'
-updated_date: '2026-02-13 18:34'
-labels: []
-dependencies:
-  - TASK-30.1
-parent_task_id: TASK-30
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Build a dedicated service in main process that queries configured extension repos and normalizes results into a unified internal model, including optional playback metadata. Keep transport abstracted so future backends (local process, remote API, Manatán-compatible source) can be swapped without changing renderer contracts.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Create a typed internal model for source, series, episode, and playable candidate with fields for quality/audio/headers/referrer/userAgent.
-- [ ] #2 Implement provider abstraction with pluggable fetch/execution strategy from config.
-- [ ] #3 Add services for searchAnime, listEpisodes, resolveStream (or equivalent) with cancellation/error boundaries.
-- [ ] #4 Normalize all provider responses into deterministic field names and stable IDs.
-- [ ] #5 Include resilient handling for empty/no-result/no-URL cases and network faults with explicit error categories.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Phase 2 — Core service: provider integration and stream resolution
-
-<!-- SECTION:NOTES:END -->
-
-## Definition of Done
-
-<!-- DOD:BEGIN -->
-
-- [ ] #1 Resolver never leaks raw provider payload to renderer.
-- [ ] #2 Streaming URL output includes reason for failure when unavailable.
-- [ ] #3 Service boundaries allow unit-level validation of request/response mapping logic.
-- [ ] #4 No blocking calls on Electron UI/main thread; all I/O is async and cancellable.
-<!-- DOD:END -->

backlog/archive/tasks/task-30.3 - Expose-resolver-operations-via-Electron-IPC-to-renderer.md

@@ -1,50 +0,0 @@
----
-id: TASK-30.3
-title: Expose resolver operations via Electron IPC to renderer
-status: To Do
-assignee: []
-created_date: '2026-02-13 18:32'
-updated_date: '2026-02-13 18:34'
-labels: []
-dependencies:
-  - TASK-30.2
-parent_task_id: TASK-30
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add a typed preload and main-IPC contract for streaming queries and playback resolution so the renderer can initiate search/list/resolve without embedding network/provider logic in UI code.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Define IPC handlers in main with input/output schema validation and timeouts.
-- [ ] #2 Expose corresponding functions in preload `window.electronAPI` and ElectronAPI types.
-- [ ] #3 Reuse existing mpv command channel for playback and add a dedicated request/response flow for resolver actions.
-- [ ] #4 Implement safe serialization and error marshalling for resolver-specific failures.
-- [ ] #5 Add runtime wiring and lifetime management in app startup/shutdown.
-- [ ] #6 Document event/callback behavior for loading/error states.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Phase 3 — API surface: IPC/preload contract for resolver operations
-
-<!-- SECTION:NOTES:END -->
-
-## Definition of Done
-
-<!-- DOD:BEGIN -->
-
-- [ ] #1 Renderer code can query providers without importing Node-only modules.
-- [ ] #2 IPC paths have clear names and consistent response shapes across all calls.
-- [ ] #3 Error paths return explicit machine-readable codes mapped to user-visible messages.
-<!-- DOD:END -->

backlog/archive/tasks/task-30.4 - Add-interactive-streaming-modal-search-episode-list-source-selection-play.md

@@ -1,50 +0,0 @@
----
-id: TASK-30.4
-title: 'Add interactive streaming modal (search, episode list, source selection, play)'
-status: To Do
-assignee: []
-created_date: '2026-02-13 18:32'
-updated_date: '2026-02-13 18:34'
-labels: []
-dependencies:
-  - TASK-30.3
-parent_task_id: TASK-30
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Implement a renderer flow to query configured providers, display results, let user choose series and episode, and trigger playback for a selected stream. The UI should support keyboard interactions and surface backend errors clearly.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Create modal UI/state model for query, results list, selected item, episode list, candidate qualities, and loading/error status.
-- [ ] #2 Wire renderer actions to new IPC methods for search/episode/resolve.
-- [ ] #3 Render one-click or enter-to-play action that calls existing mpv playback pathway.
-- [ ] #4 Persist minimal user preference (last provider/quality where possible) for faster repeat use.
-- [ ] #5 Provide empty/error states and accessibility-friendly focus/keyboard navigation for lists.
-- [ ] #6 Add a no-network mode fallback message when resolver calls fail.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Phase 4 — UX: interactive modal flow and playback callout
-
-<!-- SECTION:NOTES:END -->
-
-## Definition of Done
-
-<!-- DOD:BEGIN -->
-
-- [ ] #1 Modal state is isolated and unsubscribes listeners on close.
-- [ ] #2 No direct network logic in renderer beyond IPC calls.
-- [ ] #3 Visual style and behavior are consistent with existing modal patterns.
-<!-- DOD:END -->

backlog/archive/tasks/task-30.5 - Wire-mpv-script-message-shortcut-trigger-into-streaming-modal-and-playback-path.md

@@ -1,53 +0,0 @@
----
-id: TASK-30.5
-title: >-
-  Wire mpv script-message/shortcut trigger into streaming modal and playback
-  path
-status: To Do
-assignee: []
-created_date: '2026-02-13 18:33'
-updated_date: '2026-02-13 18:34'
-labels: []
-dependencies:
-  - TASK-30.3
-  - TASK-30.4
-parent_task_id: TASK-30
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Allow users to open streaming selection from within mpv via keybind/menu and route that intent into renderer modal and playback flow without requiring separate window focus changes.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Add/extend mpv Lua plugin or existing command registry to emit a custom action for opening the streaming picker.
-- [ ] #2 Handle this action in main IPC/mpv-command pipeline and forward to renderer modal state.
-- [ ] #3 Add at least one default keybinding/menu entry documented in config/plugin notes.
-- [ ] #4 Ensure playback launched from the in-player flow uses the same command path and error messages as renderer-initiated flow.
-- [ ] #5 Add graceful handling when feature is disabled or no providers are configured.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Phase 5 — In-player entry: mpv trigger/menu integration
-
-<!-- SECTION:NOTES:END -->
-
-## Definition of Done
-
-<!-- DOD:BEGIN -->
-
-- [ ] #1 No duplicate mpv command parsing between picker and legacy commands.
-- [ ] #2 Feature can be used in overlay and mpv-only mode where applicable.
-- [ ] #3 No dependency on modal open state when launched by mpv trigger.
-- [ ] #4 Manual and keybind invocations behave consistently.
-<!-- DOD:END -->

backlog/archive/tasks/task-30.6 - Add-integration-validation-plan-and-rollout-checklist-for-anime-streaming-feature.md

@@ -1,53 +0,0 @@
----
-id: TASK-30.6
-title: >-
-  Add integration validation plan and rollout checklist for anime streaming
-  feature
-status: To Do
-assignee: []
-created_date: '2026-02-13 18:34'
-updated_date: '2026-02-13 18:34'
-labels: []
-dependencies: []
-parent_task_id: TASK-30
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Create a concrete validation task that defines end-to-end acceptance checks for config loading, resolver behavior, IPC contract correctness, UI flow, and mpv-triggered launch. The checklist should be actionable and align with existing project conventions so completion can be verified without guesswork.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Define test scenarios for config success/failure cases, including invalid provider config and feature disabled mode.
-- [ ] #2 Define search/list/resolve API contract tests and error-code assertions (empty, timeout, auth error, no playable URL).
-- [ ] #3 Define renderer UX checks for modal state transitions, loading indicators, empty results, selection, and play invocation.
-- [ ] #4 Define in-mpv trigger checks for command/message pathway and fallback behavior when modal disabled/unavailable.
-- [ ] #5 Define manual smoke steps for end-to-end play from query to mpv playback using at least one configured source.
-- [ ] #6 Document expected logs/telemetry markers for troubleshooting and rollback.
-- [ ] #7 Define rollback criteria and what constitutes safe partial completion.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Phase 6 — Validation: rollout, smoke tests, and release readiness checklist
-
-<!-- SECTION:NOTES:END -->
-
-## Definition of Done
-
-<!-- DOD:BEGIN -->
-
-- [ ] #1 Checklist covers happy-path and failure-path for each task dependency.
-- [ ] #2 Verification steps are executable without external tooling assumptions.
-- [ ] #3 No task can be marked done without explicit evidence fields filled in.
-- [ ] #4 Rollout and fallback behavior are documented per deployment/release phase.
-<!-- DOD:END -->

backlog/archive/tasks/task-30.7 - Add-English-source-preference-hard-sub-stripping-workflow-in-Aniyomi-streaming-path.md

@@ -1,38 +0,0 @@
----
-id: TASK-30.7
-title: >-
-  Add English-source preference + hard-sub stripping workflow in Aniyomi
-  streaming path
-status: To Do
-assignee: []
-created_date: '2026-02-13 18:41'
-labels: []
-dependencies:
-  - TASK-30.2
-  - TASK-30.5
-parent_task_id: TASK-30
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Improve the Aniyomi/anime extension streaming flow to prefer English-capable sources with soft subtitles, and automatically recover when only hard-subbed streams are available by stripping embedded subtitles with ffmpeg and attaching external Jimaku subtitle files into mpv.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 During source scoring/selection, prefer providers/sources that declare or expose soft subtitles for English audio or subtitle tracks over hard-subbed alternatives.
-- [ ] #2 Add a config option for preferred language targets (default English) and fallback policy (favor soft subtitles, then hard-sub fallback).
-- [ ] #3 Detect when a resolved stream is hard-sub-only and a soft-sub source is unavailable for the same episode.
-- [ ] #4 When hard subs are used, attempt to generate a subtitle-less playback stream path using ffmpeg and feed an external subtitle file (including Jimaku-provided `.ass/.srt`) into the mpv playback path.
-- [ ] #5 Preserve stream selection metadata (language tags, subtitle type, availability state) for UI decisions and error messaging.
-- [ ] #6 If ffmpeg conversion is not possible/disabled or fails, surface a clear status that explains fallback behavior instead of silent failure.
-- [ ] #7 Integrate subtitle source preferences with Jimaku so user-fetched or resolved subtitles are preferred for burn-in removal cases where supported.
-- [ ] #8 Add handling for unsupported codecs/containers and provider limitations so direct passthrough is still used when hard-sub stripping is unsafe.
-- [ ] #9 Document new behavior in feature docs/FAQ: how sources are ranked, what hard-sub stripping does, and known compatibility limitations.
-<!-- AC:END -->

backlog/archive/tasks/task-30.8 - Add-observability-and-tuning-metrics-for-Aniyomi-subtitle-source-fallback-decisions.md

@@ -1,35 +0,0 @@
----
-id: TASK-30.8
-title: >-
-  Add observability and tuning metrics for Aniyomi subtitle-source fallback
-  decisions
-status: To Do
-assignee: []
-created_date: '2026-02-13 18:41'
-labels: []
-dependencies:
-  - TASK-30.7
-parent_task_id: TASK-30
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add lightweight telemetry/analytics hooks (local logs + optional structured counters) to measure how Aniyomi/anime streaming source selection behaves, including soft-sub preference, hard-sub fallback usage, and ffmpeg+Jimaku post-processing outcomes, to support source ranking tuning.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Track per-playback decision metadata including chosen source, language match score, subtitle mode (soft/hard), and reason for source preference ordering.
-- [ ] #2 Emit success/failure counters for hard-sub stripping attempts (started/succeeded/failed/unsupported codec) with reason codes.
-- [ ] #3 Log whether Jimaku subtitle attachment was available and successfully loaded for ffmpeg-assisted flows.
-- [ ] #4 Capture user-visible fallback reasons when preferred English/soft-sub sources are absent and hard-sub path is used.
-- [ ] #5 Add a debug/report view or log artifact with counters that can be reviewed in-app or via config/log files.
-- [ ] #6 Document metrics definitions so developers can tune source scorer and fallback policy without code changes.
-- [ ] #7 Ensure instrumentation has low overhead and is opt-out-safe with existing config flags.
-<!-- AC:END -->

backlog/archive/tasks/task-30.9 - Expose-subtitle-preference-and-ffmpeg-fallback-tuning-controls-in-settings-UI.md

@@ -1,34 +0,0 @@
----
-id: TASK-30.9
-title: Expose subtitle preference and ffmpeg fallback tuning controls in settings UI
-status: To Do
-assignee: []
-created_date: '2026-02-13 18:42'
-labels: []
-dependencies:
-  - TASK-30.7
-  - TASK-30.8
-parent_task_id: TASK-30
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add user-configurable controls for Aniyomi streaming subtitle behavior, including preferred language profile, soft-vs-hard source preference, ffmpeg-assisted hard-sub removal behavior, and policy toggles so quality and fallback behavior can be tuned without code changes.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Add settings UI fields to define preferred subtitle/audiotrack language order (e.g., en, ja) and enable/disable hard-sub fallback mode.
-- [ ] #2 Add explicit toggle for enabling hard-sub stripping via ffmpeg and configurable timeout/quality limits to avoid long waits.
-- [ ] #3 Expose source ranking preferences for soft-sub vs hard-sub sources and optional fallback to native/transcoded source when preferred modes are unavailable.
-- [ ] #4 Persist settings in existing config schema with migration-safe defaults and include clear validation for invalid/unsupported values.
-- [ ] #5 Show current effective policy in streaming UI (for debugging): source selected + reason + whether subtitles are soft/hard and if ffmpeg path is active.
-- [ ] #6 Add user-facing explanatory text and warnings for ffmpeg dependency, expected CPU/cpu cost, and compatibility limits.
-- [ ] #7 Log and display when user-adjusted policy changes alter a previously preferred source choice during runtime.
-<!-- AC:END -->

backlog/archive/tasks/task-34 - Add-in-app-episode-browser-CtrlE-for-local-files-and-Jellyfin-ready-metadata.md

@@ -1,51 +0,0 @@
----
-id: TASK-34
-title: >-
-  Add in-app episode browser (Ctrl+E) for local files and Jellyfin-ready
-  metadata
-status: To Do
-assignee: []
-created_date: '2026-02-13 22:12'
-updated_date: '2026-02-13 22:13'
-labels: []
-dependencies: []
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Implement an in-app episode browser invoked by Ctrl+E when mpv is open and connected to the Electron UI. The viewer should use the currently supplied directory (if app was launched with one) or fallback to the parent directory of the currently playing video. It should enumerate all available video files in target directory and sort them deterministically, then display them in a polished list/gallery with thumbnails in the Electron UI. Thumbnail behavior should prioritize existing matching images in the directory; otherwise generate thumbnails asynchronously in the background and update the modal as they become available. The same menu infrastructure should be shared with the planned Jellyfin integration and designed so it can display additional Jellyfin-sourced metadata without UI rewrites. It should also support launching/using an alternate picker mode compatible with external launcher UX patterns (e.g., via fzf/rofi), showing the same episode list/metadata in those contexts.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Pressing Ctrl+E in connected mode opens an episode viewer modal and closes/overlays correctly in the Electron app.
-- [ ] #2 Episode browser source directory is resolved from CLI-provided path when present, else from currently playing video's parent directory.
-- [ ] #3 Browser enumerates all supported video files in target directory and sorts them deterministically (e.g., natural/season-episode aware when possible).
-- [ ] #4 Episode list/gallery renders a consistent, usable layout with title, position/index, and thumbnail placeholders.
-- [ ] #5 If a thumbnail image file with matching name exists in the directory, it is used without background generation.
-- [ ] #6 For files without matching thumbnails, background thumbnail generation runs and updates entries as images become available in the modal.
-- [ ] #7 Thumbnail generation is cancellable/abortable and does not block UI interaction.
-- [ ] #8 The same episode viewer component/path can be reused by Jellyfin integration and can accept extended metadata payloads (e.g., show title, season/episode, runtime, description).
-- [ ] #9 `fzf`/`rofi`-compatible episode picker mode is available so the same episode set can be browsed outside the Electron modal using either backend output format.
-- [ ] #10 Episode item ordering, labels, and metadata shown in fzf/rofi mode match the in-app sorting and identity scheme.
-- [ ] #11 Both picker modes (Electron modal and fzf/rofi) resolve source directory using the same CLI/parent-of-current-video precedence rules.
-- [ ] #12 When invoked through fzf/rofi, the selected episode can be played and returns focus/flow safely to the Electron-mpv workflow.
-<!-- AC:END -->
-
-## Definition of Done
-
-<!-- DOD:BEGIN -->
-
-- [ ] #1 Feature supports Ctrl+E invocation from connected mpv session.
-- [ ] #2 Directory fallback behavior is implemented and validated with both passed-in and default paths.
-- [ ] #3 Video listing excludes unsupported formats and is correctly sorted.
-- [ ] #4 Existing local thumbnail matching works for common image/video naming patterns.
-- [ ] #5 Background thumbnail generation works asynchronously and updates UI in-place.
-- [ ] #6 UI is ready for Jellyfin metadata fields and does not require structural rewrite for server-provided data.
-- [ ] #7 No regressions in existing mpv-Electron controls for standard playback.
-<!-- DOD:END -->

backlog/archive/tasks/task-43 - Add-community-subtitle-timing-database-for-shared-sync-corrections.md

@@ -1,58 +0,0 @@
----
-id: TASK-43
-title: Add community subtitle timing database for shared sync corrections
-status: To Do
-assignee: []
-created_date: '2026-02-14 02:13'
-labels:
-  - feature
-  - community
-  - subtitles
-  - sync
-dependencies: []
-priority: low
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Allow users to share their subtitle timing corrections to a community database, so other users watching the same video file get pre-synced subtitles automatically.
-
-## Motivation
-
-Subtitle synchronization (alass/ffsubsync) is one of the most friction-heavy steps in the mining workflow. Users spend time syncing subtitles that someone else has already synced for the exact same video. A shared database of timing corrections keyed by video file hash would eliminate redundant work.
-
-## Design
-
-1. **Video identification**: Use a partial file hash (first + last N bytes, or a media fingerprint) to identify video files without uploading content
-2. **Timing data**: Store the timing offset/warp parameters produced by alass/ffsubsync, not the full subtitle file
-3. **Upload flow**: After a successful sync, offer to share the timing correction (opt-in)
-4. **Download flow**: Before syncing, check the community database for existing corrections for the current video hash
-5. **Trust model**: Simple upvote/downvote on corrections; show number of users who confirmed a correction works
-
-## Technical considerations
-
-- Backend could be a simple REST API with a lightweight database (or even a GitHub-hosted JSON/SQLite file for v1)
-- Privacy: only file hashes and timing parameters are shared, never video content or personal data
-- Subtitle source (jimaku entry ID) can serve as an additional matching key
-- Rate limiting and abuse prevention needed for public API
-- Could integrate with existing jimaku modal flow
-
-## Phasing
-
-- v1: Local export/import of timing corrections (share as files)
-- v2: Optional cloud sync with community database
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Video files are identified by content hash without uploading video data.
-- [ ] #2 Timing corrections (offset/warp parameters) can be exported and shared.
-- [ ] #3 Before syncing, the app checks for existing community corrections for the current video.
-- [ ] #4 Upload of timing data is opt-in with clear privacy disclosure.
-- [ ] #5 Downloaded corrections are applied automatically or with one-click confirmation.
-- [ ] #6 Trust signal (confirmation count) is shown for community corrections.
-<!-- AC:END -->

backlog/archive/tasks/task-48 - Add-streaming-mode-integration-in-subminer-using-ani-cli-stream-source.md

@@ -1,53 +0,0 @@
----
-id: TASK-48
-title: Add streaming mode integration in subminer using ani-cli stream source
-status: To Do
-assignee: []
-created_date: '2026-02-14 06:01'
-updated_date: '2026-02-14 08:19'
-labels:
-  - stream
-  - ani-cli
-  - jimaku
-dependencies: []
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Implement a new streaming mode so SubMiner can resolve and play episodes via ani-cli stream sources instead of existing file/download flow. The mode is enabled with a CLI flag (`-s` / `--stream`) and, when active, should prefer streamed playback and subtitle handling that keeps Japanese (or configured primary) subtitles as the main track. If a stream lacks Japanese subtitle tracks, fetch and inject subtitles from Jimaku and set them as primary subtitles according to SubMiner config.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Add a command-line option `-s`/`--stream` that enables streaming mode and is documented in help/config UX.
-- [ ] #2 When streaming mode is enabled, resolve episode/video URLs using existing ani-cli stream selection logic (ported into SubMiner) and route playback to the resolved stream source.
-- [ ] #3 If stream metadata contains a Japanese subtitle track, preserve that track as the primary subtitle stream path per current primary-subtitle selection behavior.
-- [ ] #4 If no Japanese subtitle track is present in the stream metadata, fetch matching subtitles from Jimaku and load them into playback.
-- [ ] #5 When loading Jimaku subtitles, replace/overwrite existing non-Japanese primary subtitle track behavior so the language configured as primary in SubMiner config is used instead.
-- [ ] #6 Non-streaming mode continues to follow current behavior when `-s`/`--stream` is not set.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Superseded by TASK-51. Streaming via ani-cli in subminer was removed due Cloudflare 403/unreliable source metadata; re-evaluate later if reintroduced behind a feature flag and redesigned resolver/metadata pipeline.
-
-<!-- SECTION:NOTES:END -->
-
-## Definition of Done
-
-<!-- DOD:BEGIN -->
-
-- [ ] #1 CLI accepts both `-s` and `--stream` and enables streaming-specific behavior.
-- [ ] #2 Streaming mode resolves streams through migrated ani-cli logic.
-- [ ] #3 Japanese subs are preferred from stream metadata when available; Jimaku fallback is used only when absent.
-- [ ] #4 Primary subtitle language in config determines which language is treated as default stream subtitle track after fallback.
-- [ ] #5 Behavior is verified via test or manual checklist and documented in task notes.
-<!-- DOD:END -->

backlog/archive/tasks/task-48.1 - Add-streaming-CLI-flag-plumbing-and-option-wiring.md

@@ -1,39 +0,0 @@
----
-id: TASK-48.1
-title: Add streaming CLI flag plumbing and option wiring
-status: To Do
-assignee: []
-created_date: '2026-02-14 06:03'
-updated_date: '2026-02-14 08:19'
-labels:
-  - stream
-  - cli
-dependencies: []
-parent_task_id: TASK-48
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add the `-s`/`--stream` option end-to-end in SubMiner CLI and configuration handling, including defaults, help text, parsing/validation, and explicit routing so streaming mode is only enabled when requested.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Introduce `-s` short option and `--stream` long option in CLI parsing without breaking existing flags.
-- [ ] #2 When set, the resulting config state reflects streaming mode enabled and is propagated to playback/session startup.
-- [ ] #3 When unset, behavior remains identical to current non-streaming flows.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Superseded by TASK-51. CLI stream mode work deferred until streaming architecture is revisited.
-
-<!-- SECTION:NOTES:END -->

backlog/archive/tasks/task-48.2 - Port-ani-cli-stream-resolution-logic-into-SubMiner.md

@@ -1,39 +0,0 @@
----
-id: TASK-48.2
-title: Port ani-cli stream-resolution logic into SubMiner
-status: To Do
-assignee: []
-created_date: '2026-02-14 06:03'
-updated_date: '2026-02-14 08:19'
-labels:
-  - stream
-  - ani-cli
-dependencies: []
-parent_task_id: TASK-48
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Implement stream URL resolution by porting ani-cli logic for selecting providers/episodes and obtaining playable stream URLs so SubMiner can consume stream sources directly.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Encapsulate stream search/provider selection logic in a dedicated module in SubMiner.
-- [ ] #2 Resolve episode query input into a canonical playable stream URL in streaming mode.
-- [ ] #3 Preserve existing behavior for non-streaming flow and expose errors when stream resolution fails.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Superseded by TASK-51. Stream URL resolution via ani-cli postponed; previous attempt exposed anti-bot/403 fragility and poor title-source reliability.
-
-<!-- SECTION:NOTES:END -->

backlog/archive/tasks/task-48.3 - Implement-stream-subtitle-selection-and-primary-language-precedence.md

@@ -1,39 +0,0 @@
----
-id: TASK-48.3
-title: Implement stream subtitle selection and primary-language precedence
-status: To Do
-assignee: []
-created_date: '2026-02-14 06:03'
-updated_date: '2026-02-14 08:19'
-labels:
-  - stream
-  - subtitles
-dependencies: []
-parent_task_id: TASK-48
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Handle subtitle track selection for stream playback so Japanese (or configured primary language) subtitle behavior is correctly applied when stream metadata includes or omits JP tracks.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Use stream metadata to choose and mark the configured primary language subtitle as active when available.
-- [ ] #2 If no matching primary language track exists in stream metadata, keep previous fallback behavior only for non-streaming mode.
-- [ ] #3 When no Japanese track exists and config primary is different, explicitly set configured primary as primary track for streaming flow.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Superseded by TASK-51. Stream subtitle language precedence in streaming mode deferred with full design revisit.
-
-<!-- SECTION:NOTES:END -->

backlog/archive/tasks/task-48.4 - Add-Jimaku-subtitle-fallback-for-stream-mode.md

@@ -1,40 +0,0 @@
----
-id: TASK-48.4
-title: Add Jimaku subtitle fallback for stream mode
-status: To Do
-assignee: []
-created_date: '2026-02-14 06:03'
-updated_date: '2026-02-14 08:19'
-labels:
-  - stream
-  - jimaku
-  - subtitles
-dependencies: []
-parent_task_id: TASK-48
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-When a resolved stream lacks JP/primary-language tracks, fetch subtitles from Jimaku and inject them for playback, overriding non-primary subtitle defaults in streaming mode according to config.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Detect missing primary subtitle from stream metadata and trigger Jimaku lookup for matching episode.
-- [ ] #2 Load fetched Jimaku subtitles into playback pipeline and mark them as the primary subtitle track.
-- [ ] #3 Fallback is only used in streaming mode and should not alter subtitle behavior outside streaming.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Superseded by TASK-51. Jimaku fallback for streams deferred along with entire streaming flow.
-
-<!-- SECTION:NOTES:END -->

backlog/archive/tasks/task-48.5 - Add-verification-plan-tests-for-streaming-mode-behavior.md

@@ -1,39 +0,0 @@
----
-id: TASK-48.5
-title: Add verification plan/tests for streaming mode behavior
-status: To Do
-assignee: []
-created_date: '2026-02-14 06:03'
-updated_date: '2026-02-14 08:19'
-labels:
-  - stream
-  - qa
-dependencies: []
-parent_task_id: TASK-48
-priority: low
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Create a validation plan or tests for CLI flag behavior, stream resolution, and subtitle precedence/fallback rules so streaming mode changes are measurable and regressions are caught.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Document/manual checklist covers `-s` and `--stream` invocation and streaming-only behavior.
-- [ ] #2 Include cases for (a) stream with JP subtitles, (b) no JP subtitles with Jimaku fallback, (c) primary-language not Japanese.
-- [ ] #3 Run or provide reproducible checks to confirm non-streaming behavior unchanged.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Superseded by TASK-51. Verification plan moved to deferred reimplementation context.
-
-<!-- SECTION:NOTES:END -->

backlog/archive/tasks/task-48.6 - Wire-s-stream-mode-to-Ani-cli-and-Jimaku-subtitle-fallback.md

@@ -1,57 +0,0 @@
----
-id: TASK-48.6
-title: Wire -s/--stream mode to Ani-cli and Jimaku subtitle fallback
-status: To Do
-assignee: []
-created_date: '2026-02-14 06:06'
-updated_date: '2026-02-14 08:19'
-labels: []
-dependencies: []
-references:
-  - ani-cli/ani-cli
-  - src/jimaku/utils.ts
-  - src/core/services/anki-jimaku-service.ts
-documentation:
-  - ani-cli/README.md
-  - subminer
-  - src/cli/help.ts
-parent_task_id: TASK-48
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Implement SubMiner streaming mode end-to-end behind a `-s`/`--stream` flag. In stream mode, use the vendored ani-cli resolution flow to get playable stream URLs instead of local file/YouTube URL handling. If resolved streams do not expose Japanese subtitles, fetch matching subtitles from Jimaku and load them into mpv as the active primary subtitle track, overwriting the current non-primary/non-Japanese default according to subminer primary-subtitle configuration.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 When `subminer -s` is used, resolution should pass a search/query through ani-cli stream logic and play the resolved stream source.
-- [ ] #2 If the stream includes a Japanese subtitle track, preserve and select the configured primary subtitle language behavior without Jimaku injection.
-- [ ] #3 If no Japanese (or configured primary language) subtitle exists in stream metadata, fetch and inject Jimaku subtitles before playback starts.
-- [ ] #4 Loaded Jimaku subtitles should become the selected primary subtitle track, replacing any existing default non-primary subtitle in that context.
-- [ ] #5 When `-s` is not passed, non-streaming behavior remains unchanged.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Superseded by TASK-51. End-to-end stream wiring to ani-cli is deferred.
-
-<!-- SECTION:NOTES:END -->
-
-## Definition of Done
-
-<!-- DOD:BEGIN -->
-
-- [ ] #1 CLI exposes both `-s` and `--stream` in help/config and validation.
-- [ ] #2 Implementation includes a clear fallback path when stream subtitles are absent and Jimaku search/download fails gracefully.
-- [ ] #3 Subtitles loading path avoids temp-file leaks; temporary media/subtitle artifacts are cleaned up on exit.
-- [ ] #4 At least one verification step (manual or test) confirms stream mode path works for an episode with and without Japanese stream subtitles.
-<!-- DOD:END -->

backlog/archive/tasks/task-51 - Revisit-Ani-cli-stream-mode-integration-later.md

@@ -1,33 +0,0 @@
----
-id: TASK-51
-title: Revisit Ani-cli stream mode integration later
-status: To Do
-assignee: []
-created_date: '2026-02-14 08:19'
-labels:
-  - someday
-  - streaming
-  - ani-cli
-  - feature-flag
-dependencies: []
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Current codebase has removed ani-cli integration and stream-mode from subminer temporarily. Keep a deferred design task to reintroduce streaming mode in a future cycle.
-
-Findings from prior attempts:
-
-- `subminer -s <query>` path relied on `ani-cli` resolving stream URLs, but returned stream URLs that are Cloudflare-protected (`tools.fast4speed.rsvp`) and often returned 403 from mpv/ytdl-hook (generic anti-bot/Forbidden).
-- Even after passing `ytdl` extractor args, stream playback via subminer still failed because URL/anti-bot handling differed from direct ani-cli execution context.
-- We also observed stream title resolution issues: selected titles from ani-cli menu were unreliable/random and broke downstream Jimaku matching behavior.
-- ffsubsync failures were difficult to debug initially due to OSD-only error visibility; logging was added to mpv log path.
-- Based on these findings and instability, stream mode should be explicitly deferred rather than partially reintroduced.
-
-Proposal:
-
-- Reintroduce behind a feature flag / future milestone only.
-- Re-design around a dedicated stream source resolver with robust URL acquisition and source metadata preservation (query/episode/title) before subtitle sync flows.
-<!-- SECTION:DESCRIPTION:END -->

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

@@ -0,0 +1,51 @@
+---
+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/completed/task-10 - Consolidate-service-naming-conventions-and-barrel-exports.md

@@ -1,62 +0,0 @@
----
-id: TASK-10
-title: Consolidate service naming conventions and barrel exports
-status: Done
-assignee: []
-created_date: '2026-02-11 08:21'
-updated_date: '2026-02-15 07:00'
-labels:
-  - refactor
-  - services
-  - naming
-milestone: Codebase Clarity & Composability
-dependencies: []
-references:
-  - src/core/services/index.ts
-priority: low
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-The service layer has inconsistent naming:
-
-- Some functions end in `Service`: `handleCliCommandService`, `loadSubtitlePositionService`
-- Some end in `RuntimeService`: `replayCurrentSubtitleRuntimeService`, `sendMpvCommandRuntimeService`
-- Some are plain: `shortcutMatchesInputForLocalFallback`
-- Factory functions mix `create*DepsRuntimeService` with `create*Service`
-
-The barrel export (src/core/services/index.ts) re-exports 79 symbols from 28 files through a single surface, which obscures dependency boundaries. Consumers import everything from `./core/services` and can't tell which service file they actually depend on.
-
-Establish consistent naming:
-
-- Exported service functions: `verbNounService` (e.g., `handleCliCommand`)
-- Deps factory functions: `create*Deps`
-- Consider whether the barrel re-export is still the right pattern vs direct imports from individual files.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 All service functions follow a consistent naming convention
-- [ ] #2 Decision documented on barrel export vs direct imports
-- [ ] #3 No functional changes
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Naming convention consolidation should be addressed as part of TASK-27.2 (split main.ts) and TASK-27.3 (anki-integration split). As modules are extracted and given clear boundaries, naming will be standardized at each boundary. No need to do a standalone naming pass — it's wasted effort if the module structure is about to change.
-
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Subsumed by TASK-27.2 and TASK-27.3. Naming conventions were standardized at module boundaries during extraction. A standalone global naming pass would be churn with no structural benefit now that modules have clear ownership boundaries.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

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

@@ -0,0 +1,42 @@
+---
+id: TASK-100
+title: Add configurable texthooker startup launch
+status: Done
+assignee: []
+created_date: '2026-03-06 23:30'
+updated_date: '2026-03-16 05:13'
+labels: []
+dependencies: []
+priority: medium
+ordinal: 11010
+---
+
+## 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/completed/task-101 - Index-AniList-character-alternative-names-in-the-character-dictionary.md

@@ -0,0 +1,40 @@
+---
+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-16 05:13'
+labels:
+  - dictionary
+  - anilist
+dependencies: []
+references:
+  - src/main/character-dictionary-runtime.ts
+  - src/main/character-dictionary-runtime.test.ts
+priority: high
+ordinal: 71500
+---
+
+## 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/completed/task-102 - Quiet-default-AppImage-startup-and-implicit-background-launch.md

@@ -0,0 +1,65 @@
+---
+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-16 05:13'
+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
+ordinal: 77500
+---
+
+## 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/completed/task-103 - Add-dedicated-annotation-websocket-for-texthooker.md

@@ -0,0 +1,38 @@
+---
+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-16 05:13'
+labels:
+  - texthooker
+  - websocket
+  - subtitle
+dependencies: []
+priority: medium
+ordinal: 73500
+---
+
+## 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/completed/task-104 - Mirror-overlay-annotation-hover-behavior-in-vendored-texthooker.md

@@ -0,0 +1,45 @@
+---
+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-16 05:13'
+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
+ordinal: 76500
+---
+
+## 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/completed/task-105 - Stop-local-docs-artifact-writes-after-docs-repo-split.md

@@ -0,0 +1,40 @@
+---
+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-16 05:13'
+labels: []
+dependencies: []
+priority: medium
+ordinal: 12010
+---
+
+## 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/completed/task-106 - Add-first-run-setup-gate-and-auto-install-flow.md

@@ -0,0 +1,71 @@
+---
+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-16 05:13'
+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: 13010
+---
+
+## 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/completed/task-107 - Fix-Yomitan-scan-token-fallback-fragmentation.md

@@ -0,0 +1,42 @@
+---
+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/completed/task-108 - Exclude-single-kana-tokens-from-frequency-highlighting.md

@@ -0,0 +1,43 @@
+---
+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/completed/task-11 - Break-up-the-applyInvisibleSubtitleLayoutFromMpvMetrics-mega-function.md

@@ -1,63 +0,0 @@
----
-id: TASK-11
-title: Break up the applyInvisibleSubtitleLayoutFromMpvMetrics mega function
-status: Done
-assignee: []
-created_date: '2026-02-11 08:21'
-updated_date: '2026-02-16 01:34'
-labels:
-  - refactor
-  - renderer
-  - complexity
-milestone: Codebase Clarity & Composability
-dependencies:
-  - TASK-27.5
-references:
-  - src/renderer/renderer.ts
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-In renderer.ts (around lines 865-1075), `applyInvisibleSubtitleLayoutFromMpvMetrics` is a 211-line function with up to 5 levels of nesting. It handles OSD scaling calculations, platform-specific font compensation (macOS vs Linux), DPR calculations, ASS alignment tag interpretation (\an tags), baseline compensation, line-height fixes, font property application, and transform origin — all interleaved.
-
-Extract into focused helpers:
-
-- `calculateOsdScale(metrics, renderAreaHeight)` — pure scaling math
-- `calculateSubtitlePosition(metrics, scale, alignment)` — ASS \an tag interpretation + positioning
-- `applyPlatformFontCompensation(style, platform)` — macOS kerning/size adjustments
-- `applySubtitleStyle(element, computedStyle)` — DOM style application
-
-This can be done independently of or as part of TASK-6 (renderer split).
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 No single function exceeds ~50 lines in the positioning logic
-- [x] #2 Helper functions are pure where possible (take inputs, return outputs)
-- [x] #3 Platform-specific branches isolated into dedicated helpers
-- [x] #4 Invisible overlay positioning still works correctly on Linux and macOS
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Helpers were split so positioning math, base layout, and typography/vertical handling are no longer in one monolith; see `src/renderer/positioning/invisible-layout.ts` and peer files.
-
-Applied as part of TASK-27.5 with helper extraction: moved mpv subtitle layout orchestration to `invisible-layout.ts` and extracted metric/base/style helpers into `invisible-layout-metrics.ts` and `invisible-layout-helpers.ts`.
-
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Decomposition of `applyInvisibleSubtitleLayoutFromMpvMetrics` completed as part of TASK-27.5: function body split into metric/layout/typography helpers and small coordinator preserved. Manual validation completed by user; behavior remains stable.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-110 - Replace-vendored-Yomitan-with-submodule-built-Chrome-artifact-workflow.md

@@ -0,0 +1,44 @@
+---
+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-16 05:13'
+labels:
+  - yomitan
+  - build
+  - release
+dependencies: []
+priority: high
+ordinal: 10010
+---
+
+## 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/completed/task-111 - Fix-subtitle-cycle-OSD-labels-for-J-keybindings.md

@@ -0,0 +1,72 @@
+---
+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-16 05:13'
+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
+ordinal: 72500
+---
+
+## 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/completed/task-112 - Address-Claude-review-items-on-PR-15.md

@@ -0,0 +1,62 @@
+---
+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-16 05:13'
+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
+ordinal: 70500
+---
+
+## 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/completed/task-113 - Scope-make-pretty-to-maintained-source-files.md

@@ -0,0 +1,60 @@
+---
+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-16 05:13'
+labels:
+  - tooling
+  - formatting
+dependencies: []
+references:
+  - Makefile
+  - package.json
+priority: medium
+ordinal: 69500
+---
+
+## 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/completed/task-114 - Fix-failing-CI-checks-on-PR-15.md

@@ -0,0 +1,63 @@
+---
+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-16 05:13'
+labels:
+  - ci
+  - test
+dependencies: []
+references:
+  - src/renderer/subtitle-render.test.ts
+  - src/renderer/style.css
+  - .github/workflows/ci.yml
+priority: high
+ordinal: 68500
+---
+
+## 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/completed/task-115 - Refresh-subminer-docs-contributor-docs-for-current-repo-workflow.md

@@ -0,0 +1,60 @@
+---
+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-16 05:13'
+labels:
+  - docs
+dependencies: []
+references:
+  - ../subminer-docs/development.md
+  - ../subminer-docs/README.md
+  - Makefile
+  - package.json
+priority: medium
+ordinal: 67500
+---
+
+## 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/completed/task-116 - Audit-branch-commits-for-remaining-subminer-docs-updates.md

@@ -0,0 +1,54 @@
+---
+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-16 05:13'
+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
+ordinal: 66500
+---
+
+## 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/completed/task-117 - Prepare-initial-Windows-release-docs-and-version-bump.md

@@ -0,0 +1,60 @@
+---
+id: TASK-117
+title: Prepare initial Windows release docs and version bump
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-08 15:17'
+updated_date: '2026-03-16 05:13'
+labels:
+  - release
+  - docs
+  - windows
+dependencies: []
+references:
+  - package.json
+  - README.md
+  - ../subminer-docs/installation.md
+  - ../subminer-docs/usage.md
+  - ../subminer-docs/changelog.md
+priority: medium
+ordinal: 53500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Prepare the initial packaged Windows release by bumping the app version and refreshing the release-facing README/backlog/docs surfaces so install and direct-command guidance no longer reads Linux-only.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 App version is bumped for the Windows release cut
+- [x] #2 README and sibling docs describe Windows packaged installation alongside Linux/macOS guidance
+- [x] #3 Backlog records the release-doc/version update with the modified references
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Bump the package version for the release cut.
+2. Update the root README install/start guidance to mention Windows packaged builds.
+3. Patch the sibling docs repo installation, usage, and changelog pages for the Windows release.
+4. Record the work in Backlog and run targeted verification on the touched surfaces.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+The public README still advertised Linux/macOS only, while the sibling docs had Windows-specific runtime notes but no actual Windows install section and several direct-command examples still assumed `SubMiner.AppImage`.
+
+Bumped `package.json` to `0.5.0`, expanded the README platform/install copy to include Windows, added a Windows install section to `../subminer-docs/installation.md`, clarified in `../subminer-docs/usage.md` that direct packaged-app examples use `SubMiner.exe` on Windows, and added a `v0.5.0` changelog entry covering the initial Windows release plus the latest overlay behavior polish.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Prepared the initial Windows release documentation pass and version bump. `package.json` now reports `0.5.0`. The root `README.md` now advertises Linux, macOS, and Windows support, includes Windows packaged-install guidance, and clarifies first-launch behavior across platforms. In the sibling docs repo, `installation.md` now includes a dedicated Windows install section, `usage.md` explains that direct packaged-app examples use `SubMiner.exe` on Windows, and `changelog.md` now includes the `v0.5.0` release notes for the initial Windows build and recent overlay behavior changes.
+
+Verification: targeted `bun run tsc --noEmit -p tsconfig.typecheck.json` in the app repo and `bun run docs:build` in `../subminer-docs`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-117 - Replace-YouTube-subtitle-generation-with-pure-TypeScript-pipeline-and-shared-AI-config.md

@@ -0,0 +1,75 @@
+---
+id: TASK-117
+title: >-
+  Replace YouTube subtitle generation with pure TypeScript pipeline and shared
+  AI config
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-08 03:16'
+updated_date: '2026-03-08 03:35'
+labels: []
+dependencies: []
+references:
+  - /Users/sudacode/projects/japanese/SubMiner/launcher/youtube.ts
+  - /Users/sudacode/projects/japanese/SubMiner/src/anki-integration/ai.ts
+  - /Users/sudacode/projects/japanese/SubMiner/src/types.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/config/definitions/defaults-integrations.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/config/resolve/subtitle-domains.ts
+  - /Users/sudacode/projects/japanese/SubMiner/config.example.jsonc
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+
+Replace the launcher YouTube subtitle generation flow with a pure TypeScript pipeline that prefers real downloadable YouTube subtitles, never uses YouTube auto-generated subtitles, locally generates missing tracks with whisper.cpp, and can optionally fix generated subtitles via a shared OpenAI-compatible AI provider config. This feature also introduces a breaking config cleanup: move provider settings to a new top-level ai section and reduce ankiConnect.ai to a boolean feature toggle.
+
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+
+<!-- AC:BEGIN -->
+
+- [x] #1 Launcher YouTube subtitle generation prefers downloadable manual YouTube subtitles, never uses YouTube auto-generated subtitles, and locally generates only missing tracks with whisper.cpp.
+- [x] #2 Generated whisper subtitle tracks can optionally be post-processed with an OpenAI-compatible AI provider using shared top-level ai config, with validation and fallback to raw whisper output on failure.
+- [x] #3 Configuration is updated so top-level ai is canonical shared provider config, ankiConnect.ai is boolean-only, and youtubeSubgen includes whisperVadModel, whisperThreads, and fixWithAi.
+- [x] #4 Launcher CLI/config parsing, config example, and docs reflect the new breaking config shape with no migration layer.
+- [x] #5 Automated tests cover the new YouTube generation behavior, AI-fix fallback/validation behavior, shared AI config usage, and breaking config validation.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+
+1. Introduce canonical top-level ai config plus youtubeSubgen runtime knobs (whisperVadModel, whisperThreads, fixWithAi) and convert ankiConnect.ai to a boolean-only toggle across types, defaults, validation, option registries, launcher config parsing, and config example/docs.
+2. Extract shared OpenAI-compatible AI client helpers from the current Anki translation code, including base URL normalization, API key / apiKeyCommand resolution, timeout handling, and response text extraction.
+3. Update Anki translation flow and hot-reload/runtime plumbing to consume global ai config while treating ankiConnect.ai as a feature gate only.
+4. Replace launcher/youtube.ts with a modular launcher/youtube pipeline that fetches only manual YouTube subtitles, generates missing tracks locally with ffmpeg + whisper.cpp + optional VAD/thread controls, and preserves preprocess/automatic playback behavior.
+5. Add optional AI subtitle-fix processing for whisper-generated tracks using the shared ai client, with strict SRT batching/validation and fallback to raw whisper output on provider or format failure.
+6. Expand automated coverage for config validation, shared AI usage, launcher config parsing, and YouTube subtitle generation behavior including removal of yt-dlp auto-subs and AI-fix fallback rules.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+
+Implemented pure TypeScript launcher/youtube pipeline modules for manual subtitle fetch, audio extraction, whisper runs, SRT utilities, and optional AI subtitle fixing. Removed yt-dlp auto-subtitle usage from the generation path.
+
+Added shared top-level ai config plus shared AI client helpers; converted ankiConnect.ai to a boolean feature gate and updated Anki runtime wiring to consume global ai config.
+
+Updated launcher config parsing, config template sections, and config.example.jsonc for the breaking config shape including youtubeSubgen.whisperVadModel, youtubeSubgen.whisperThreads, and youtubeSubgen.fixWithAi.
+
+Verification: bun run test:config:src passed; targeted AI/Anki/runtime tests passed; bun run typecheck passed. bun run test:launcher:unit:src reported one unrelated existing failure in launcher/aniskip-metadata.test.ts (resolveAniSkipMetadataForFile resolves MAL id and intro payload).
+
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+
+Replaced the launcher YouTube subtitle flow with a modular TypeScript pipeline that prefers manual YouTube subtitles, transcribes only missing tracks with whisper.cpp, and can optionally post-fix whisper output through a shared OpenAI-compatible AI client with strict SRT validation/fallback. Introduced canonical top-level ai config, reduced ankiConnect.ai to a boolean feature gate, updated launcher/config parsing and checked-in config artifacts, and added coverage for YouTube orchestration, whisper args, SRT validation, AI fix behavior, and breaking config validation.
+
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-117.1 - Harden-AI-subtitle-fix-against-non-SRT-model-responses.md

@@ -0,0 +1,57 @@
+---
+id: TASK-117.1
+title: Harden AI subtitle fix against non-SRT model responses
+status: Done
+assignee:
+  - '@codex'
+created_date: '2026-03-08 08:22'
+updated_date: '2026-03-16 05:13'
+labels: []
+dependencies: []
+references:
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/subtitle-fix-ai.ts
+  - /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/srt.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/subtitle-fix-ai.test.ts
+parent_task_id: TASK-117
+ordinal: 59500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Prevent optional YouTube AI subtitle post-processing from bailing out whenever the model returns usable cue text in a non-SRT wrapper or text-only format. The launcher should recover safe cases, preserve original timing, and fall back cleanly when the response cannot be mapped back to the source cues.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 AI subtitle fixing accepts safe AI responses that omit SRT framing but still provide one corrected text payload per original cue while preserving original cue timing.
+- [x] #2 AI subtitle fixing still rejects responses that cannot be mapped back to the original cue batch without guessing and falls back to the raw subtitle file with a warning.
+- [x] #3 Automated tests cover wrapped-SRT and text-only AI responses plus an unrecoverable invalid response case.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add failing tests in launcher/youtube/subtitle-fix-ai.test.ts for three cases: wrapped valid SRT, text-only one-block-per-cue output, and unrecoverable invalid output.
+2. Extend launcher/youtube/subtitle-fix-ai.ts with a small response-normalization path that first strips markdown/code-fence wrappers, then accepts deterministic text-only cue batches only when they map 1:1 to the original cues without changing timestamps.
+3. Keep existing safety rules: preserve cue count and timing, log a warning, and fall back to the raw subtitle file when normalization cannot recover a trustworthy batch.
+4. Run focused launcher unit tests for subtitle-fix-ai and SRT parsing; expand only if the change affects adjacent behavior.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented deterministic AI subtitle-response recovery for fenced SRT, embedded SRT payloads, and text-only 1:1 cue batches while preserving original timing and existing fallback behavior.
+
+Verification: bun test launcher/youtube/_.test.ts passed; bun run typecheck passed; repo-wide format check still reports unrelated pre-existing warnings in launcher/youtube/orchestrator.ts and scripts/build-changelog_.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Hardened the launcher AI subtitle-fix path so it can recover deterministic non-SRT model responses instead of immediately falling back. Added `parseAiSubtitleFixResponse` in `launcher/youtube/subtitle-fix-ai.ts` to normalize markdown-fenced or embedded SRT payloads first, then accept text-only responses only when they map 1:1 onto the original cue batch and preserve source timings. Added regression coverage in `launcher/youtube/subtitle-fix-ai.test.ts` for fenced SRT, text-only cue batches, and unrecoverable invalid output, plus a changelog fragment in `changes/task-117.1.md`.
+
+Verification: `bun test launcher/youtube/*.test.ts`, `bun run typecheck`, `bunx prettier --check launcher/youtube/subtitle-fix-ai.ts launcher/youtube/subtitle-fix-ai.test.ts`, and `bun run changelog:lint` passed. Repo-wide `bun run format:check:src` still reports unrelated pre-existing warnings in `launcher/youtube/orchestrator.ts` and `scripts/build-changelog*`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-118 - Add-Windows-release-build-and-SignPath-signing.md

@@ -0,0 +1,65 @@
+---
+id: TASK-118
+title: Add Windows release build and SignPath signing
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-08 15:17'
+updated_date: '2026-03-16 05:13'
+labels:
+  - release
+  - windows
+  - signing
+dependencies: []
+references:
+  - .github/workflows/release.yml
+  - build/installer.nsh
+  - build/signpath-windows-artifact-config.xml
+  - package.json
+priority: high
+ordinal: 54500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Extend the tag-driven release workflow so Windows artifacts are built on GitHub-hosted runners and submitted to SignPath for free open-source Authenticode signing, while preserving the existing macOS notarization path.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Release workflow builds Windows installer and ZIP artifacts on `windows-latest`
+- [x] #2 Workflow submits unsigned Windows artifacts to SignPath and uploads the signed outputs for release publication
+- [x] #3 Repository includes a checked-in SignPath artifact-configuration source of truth for the Windows release files
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Inspect the existing release workflow and current Windows packaging configuration.
+2. Add a Windows release job that builds unsigned artifacts, uploads them as a workflow artifact, and submits them to SignPath.
+3. Update the release aggregation job to publish signed Windows assets and mention Windows install steps in the generated release notes.
+4. Check in the Windows SignPath artifact configuration XML used to define what gets signed.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+The repository already had Windows packaging configuration (`build:win`, NSIS include script, Windows helper asset packaging), but the release workflow still built Linux and macOS only.
+
+Added a `build-windows` job to `.github/workflows/release.yml` that runs on `windows-latest`, validates required SignPath secrets, builds unsigned Windows artifacts, uploads them with `actions/upload-artifact@v4`, and then calls the official `signpath/github-action-submit-signing-request@v2` action to retrieve signed outputs.
+
+Checked in `build/signpath-windows-artifact-config.xml` as the source-of-truth artifact configuration for SignPath. It signs the top-level NSIS installer EXE and deep-signs `.exe` and `.dll` files inside the portable ZIP artifact.
+
+Updated the release aggregation job to download the signed Windows artifacts and added a Windows install section to the generated GitHub release body.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Windows release publishing is now wired into the tag-driven workflow. `.github/workflows/release.yml` builds Windows artifacts on `windows-latest`, submits them to SignPath using the official GitHub action, and publishes the signed `.exe` and `.zip` outputs alongside the Linux and macOS artifacts. The workflow now requests the additional `actions: read` permission required by the SignPath GitHub integration, and the generated release notes now include Windows installation steps.
+
+The checked-in `build/signpath-windows-artifact-config.xml` file defines the SignPath artifact structure expected by the workflow artifact ZIP: sign the top-level `SubMiner-*.exe` installer and deep-sign `.exe` and `.dll` files inside `SubMiner-*.zip`.
+
+Verification: workflow/static changes were checked with `git diff --check` on the touched files. Actual signing requires configured SignPath secrets and a matching artifact configuration in your SignPath project.
+<!-- SECTION:FINAL_SUMMARY:END -->

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

@@ -0,0 +1,73 @@
+---
+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/completed/task-12 - Add-renderer-module-bundling-for-multi-file-renderer-support.md

@@ -1,65 +0,0 @@
----
-id: TASK-12
-title: Add renderer module bundling for multi-file renderer support
-status: Done
-assignee: []
-created_date: '2026-02-11 08:21'
-updated_date: '2026-02-16 02:14'
-labels:
-  - infrastructure
-  - renderer
-  - build
-milestone: Codebase Clarity & Composability
-dependencies:
-  - TASK-5
-references:
-  - src/renderer/renderer.ts
-  - src/renderer/index.html
-  - package.json
-  - tsconfig.json
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Currently renderer.ts is a single file loaded directly by Electron's renderer process via a script tag in index.html. To split it into modules (TASK-6), we need a bundling step since Electron renderer's default context doesn't support bare ES module imports without additional configuration.
-
-Options:
-
-1. **esbuild** — fast, minimal config, already used in many Electron projects
-2. **Electron's native ESM support** — requires `"type": "module"` and sandbox configuration
-3. **TypeScript compiler output** — if targeting a single concatenated bundle
-
-The build pipeline already compiles TypeScript and copies renderer assets. Adding a bundling step for the renderer would slot into the existing `npm run build` script.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Renderer code can be split across multiple .ts files with imports
-- [x] #2 Build pipeline bundles renderer modules into a single output for Electron
-- [x] #3 Existing `make build` still works end-to-end
-- [x] #4 No runtime errors in renderer process
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Updated root npm build pipeline to use an explicit renderer bundle step via esbuild. Added `build:renderer` script to emit a single `dist/renderer/renderer.js` from `src/renderer/renderer.ts`; `build` now runs `pnpm run build:renderer` and preserves existing index/style copy and macOS helper step. Added `esbuild` to devDependencies.
-
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented renderer bundling step and wired `build` to use it. This adds `pnpm run build:renderer` which bundles `src/renderer/renderer.ts` into a single `dist/renderer/renderer.js` for Electron to load. Also added `esbuild` as a dev dependency and aligned `pnpm-lock.yaml` importer metadata for dependency consistency. Kept `index.html`/`style.css` copy path unchanged, so renderer asset layout remains stable.
-
-Implemented additional test-layer type fix after build breakage by correcting `makeDepsFromMecabTokenizer` and related `tokenizeWithMecab` mocks to match expected `Token` vs `MergedToken` shapes, keeping runtime behavior unchanged while satisfying TS checks.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-120 - Replace-node-sqlite-with-libsql-and-remove-Yomitan-Node-wrapper.md

@@ -0,0 +1,36 @@
+---
+id: TASK-120
+title: 'Replace node:sqlite with libsql and remove Yomitan Node wrapper'
+status: Done
+assignee: []
+created_date: '2026-03-08 04:14'
+updated_date: '2026-03-16 05:13'
+labels:
+  - runtime
+  - bun
+  - sqlite
+  - tech-debt
+dependencies: []
+priority: medium
+ordinal: 65500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Remove the remaining root Node requirement caused by immersion tracking SQLite usage and the old Yomitan build wrapper by migrating the local SQLite layer off node:sqlite, running the SQLite-backed verification lanes under Bun, and switching the vendored Yomitan build flow to Bun-native scripts.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Immersion tracker runtime no longer imports or requires node:sqlite
+- [x] #2 SQLite-backed immersion tracker tests run under Bun without Node --experimental-sqlite
+- [x] #3 Root build/test scripts no longer require the Yomitan Node wrapper or Node-based SQLite verification lanes
+- [x] #4 README requirements/testing docs reflect the Bun-native workflow
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Replaced the immersion tracker SQLite dependency with a local libsql-backed wrapper, updated Bun/runtime compatibility tests to avoid process.exitCode side effects, switched Yomitan builds to run directly inside the vendored Bun-native project, deleted scripts/build-yomitan.mjs, and verified typecheck plus Bun build/test lanes (`build:yomitan`, `test:immersion:sqlite`, `test:runtime:compat`, `test:fast`).
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-121 - Fix-YouTube-manual-subtitle-selection-regression-when-downloadable-tracks-exist.md

@@ -0,0 +1,53 @@
+---
+id: TASK-121
+title: >-
+  Fix YouTube manual subtitle selection regression when downloadable tracks
+  exist
+status: Done
+assignee:
+  - '@codex'
+created_date: '2026-03-08 05:37'
+updated_date: '2026-03-16 05:13'
+labels:
+  - bug
+  - youtube
+  - subtitles
+dependencies: []
+references:
+  - /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/manual-subs.ts
+  - /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/orchestrator.ts
+  - 'https://www.youtube.com/watch?v=MXzQRLmN9hE'
+priority: high
+ordinal: 64500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Ensure launcher YouTube subtitle generation reuses downloadable manual subtitle tracks when the video already has requested languages available, instead of falling back to whisper generation. Reproduce against videos like MXzQRLmN9hE that expose manual en/ja subtitles via yt-dlp.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 When requested primary/secondary manual YouTube subtitle tracks exist, planning selects them and schedules no whisper generation for those tracks.
+- [x] #2 Filename normalization handles manual subtitle outputs produced by yt-dlp for language-tagged downloads.
+- [x] #3 Automated tests cover the reproduced manual en/ja selection case.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Reproduced against https://www.youtube.com/watch?v=MXzQRLmN9hE with yt-dlp --list-subs: manual zh/en/ja/ko subtitle tracks are available from YouTube.
+
+Adjusted launcher YouTube orchestration so detected manual subtitle tracks suppress whisper generation but are no longer materialized as external subtitle files. SubMiner now relies on the native YouTube/mpv subtitle tracks for those languages.
+
+Added orchestration tests covering the manual-track reuse plan and ran a direct runtime probe against MXzQRLmN9hE. Probe result: primary/secondary native tracks detected, no external subtitle aliases emitted, output directory remained empty.
+
+Verification: bun test launcher/youtube/orchestrator.test.ts launcher/config-domain-parsers.test.ts launcher/mpv.test.ts passed; bun run typecheck passed.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Fixed the YouTube subtitle regression where videos with real downloadable subtitle tracks still ended up with duplicate external subtitle files. Manual subtitle availability now suppresses whisper generation and external subtitle publication, so videos like MXzQRLmN9hE use the native YouTube/mpv subtitle tracks directly. Launcher preprocess logging was also updated to report native subtitle availability instead of misleading missing statuses.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-122 - Harden-changelog-workflow-and-CI-enforcement.md

@@ -0,0 +1,72 @@
+---
+id: TASK-122
+title: Harden changelog workflow and CI enforcement
+status: Done
+assignee:
+  - Codex
+created_date: '2026-03-08 06:13'
+updated_date: '2026-03-16 05:13'
+labels:
+  - release
+  - changelog
+  - ci
+dependencies: []
+references:
+  - /Users/sudacode/projects/japanese/SubMiner/scripts/build-changelog.ts
+  - /Users/sudacode/projects/japanese/SubMiner/scripts/build-changelog.test.ts
+  - /Users/sudacode/projects/japanese/SubMiner/.github/workflows/ci.yml
+  - /Users/sudacode/projects/japanese/SubMiner/.github/workflows/release.yml
+  - /Users/sudacode/projects/japanese/SubMiner/docs/RELEASING.md
+  - /Users/sudacode/projects/japanese/SubMiner/changes/README.md
+priority: medium
+ordinal: 63500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Improve the release changelog workflow so changelog fragments are reliable, release output is more readable, and pull requests get early feedback when changelog metadata is missing or malformed.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 `scripts/build-changelog.ts` ignores non-fragment files in `changes/` and validates fragment structure before generating changelog output.
+- [x] #2 Generated `CHANGELOG.md` and `release/release-notes.md` group public changes into readable sections instead of a flat bullet list.
+- [x] #3 CI enforces changelog validation on pull requests and provides an explicit opt-out path for changes that should not produce release notes.
+- [x] #4 Contributor docs explain the fragment format and the PR/release workflow for changelog generation.
+- [x] #5 Automated tests cover fragment parsing/building behavior and workflow enforcement expectations.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add failing tests for changelog fragment discovery, structured fragment parsing/rendering, release-note output, and CI workflow expectations.
+2. Update scripts/build-changelog.ts to ignore non-fragment files, parse fragment metadata, group generated output by change type, add lint/PR-check commands, and simplify output paths to repo-local artifacts.
+3. Update CI and PR workflow files to run changelog validation on pull requests with an explicit skip path, and keep release workflow using committed changelog output.
+4. Refresh changes/README.md, docs/RELEASING.md, and any PR template text so contributors know how to write fragments and when opt-out is allowed.
+5. Run targeted tests and changelog commands, then record results and finalize the task.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented structured changelog fragments with required `type` and `area` metadata; `changes/README.md` is now ignored by the generator and verified by regression tests.
+
+Added `changelog:lint` and `changelog:pr-check`, plus PR CI enforcement with `skip-changelog` opt-out. PR check now reads git name-status output so deleted fragment files do not satisfy the requirement.
+
+Changed generated changelog/release notes output to grouped sections (`Added`, `Changed`, `Fixed`, etc.) and simplified release notes to highlights + install/assets pointers.
+
+Kept changelog output repo-local. This aligns with existing repo direction where docs updates happen in the sibling docs repo explicitly rather than implicit local writes from app-repo generators.
+
+Verification: `bun test scripts/build-changelog.test.ts src/ci-workflow.test.ts src/release-workflow.test.ts` passed; `bun run typecheck` passed; `bun run changelog:lint` passed. `bun run test:fast` still fails in unrelated existing `src/core/services/subsync.test.ts` cases (`runSubsyncManual keeps internal alass source file alive until sync finishes`, `runSubsyncManual resolves string sid values from mpv stream properties`).
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Hardened the changelog workflow end-to-end. `scripts/build-changelog.ts` now ignores helper files like `changes/README.md`, requires structured fragment metadata (`type` + `area`), groups generated release sections by change type, and emits shorter release notes focused on highlights plus install/assets pointers. Added explicit `changelog:lint` and `changelog:pr-check` commands, with PR validation based on git name-status so deleted fragment files do not satisfy the fragment requirement.
+
+Updated contributor-facing workflow docs in `changes/README.md`, `docs/RELEASING.md`, and a new PR template so authors know to add a fragment or apply the `skip-changelog` label. CI now runs fragment linting on every run and enforces fragment presence on pull requests. Added regression coverage in `scripts/build-changelog.test.ts` and a new `src/ci-workflow.test.ts` to lock the workflow contract.
+
+Verification completed: `bun test scripts/build-changelog.test.ts src/ci-workflow.test.ts src/release-workflow.test.ts`, `bun run typecheck`, and `bun run changelog:lint` all passed. A broader `bun run test:fast` run still fails in unrelated existing `src/core/services/subsync.test.ts` cases outside the changelog/workflow scope.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-123 - Add-progress-logging-for-YouTube-subtitle-generation-phases.md

@@ -0,0 +1,53 @@
+---
+id: TASK-123
+title: Add progress logging for YouTube subtitle generation phases
+status: Done
+assignee:
+  - '@codex'
+created_date: '2026-03-08 07:07'
+updated_date: '2026-03-16 05:13'
+labels:
+  - ux
+  - logging
+  - youtube
+  - subtitles
+dependencies: []
+references:
+  - /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/orchestrator.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/audio-extraction.ts
+  - /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/whisper.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/subtitle-fix-ai.ts
+priority: medium
+ordinal: 62500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Improve launcher YouTube subtitle generation observability so users can tell that work is happening and roughly how long each phase is taking. Cover manual subtitle probe, audio extraction, ffmpeg prep, whisper generation, and optional AI subtitle fix phases without flooding normal logs.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Users see clear info-level phase logs for YouTube subtitle generation work including subtitle probe, fallback audio extraction, whisper, and optional AI fix phases.
+- [x] #2 Long-running phases surface elapsed-time progress or explicit start/finish timing so it is obvious the process is still active.
+- [x] #3 Automated tests cover the new logging/progress helper behavior where practical.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented a shared timed YouTube phase logger in launcher/youtube/progress.ts with info-level start/finish messages and warn-level failure messages that include elapsed time.
+
+Wired phase logging into YouTube metadata probe, manual subtitle probe, fallback audio extraction, ffmpeg whisper prep, whisper primary/secondary generation, and optional AI subtitle fix phases.
+
+Verification: bun test launcher/youtube/progress.test.ts launcher/youtube/orchestrator.test.ts passed; bun run typecheck passed.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added clear phase-level observability for YouTube subtitle generation without noisy tool output. Users now see start/finish logs with elapsed time for subtitle probe, fallback audio extraction, ffmpeg prep, whisper generation, and optional AI subtitle-fix phases, making it obvious when generation is active and roughly how long each step took.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-124 - Remove-YouTube-subtitle-generation-modes-and-make-YouTube-playback-always-generate-load-subtitles.md

@@ -0,0 +1,77 @@
+---
+id: TASK-124
+title: >-
+  Remove YouTube subtitle generation modes and make YouTube playback always
+  generate/load subtitles
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-08 07:18'
+updated_date: '2026-03-16 05:13'
+labels:
+  - launcher
+  - youtube
+  - subtitles
+dependencies: []
+references:
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/launcher/commands/playback-command.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/launcher/config/args-normalizer.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/launcher/config/youtube-subgen-config.ts
+  - /Users/sudacode/projects/japanese/SubMiner/launcher/types.ts
+  - /Users/sudacode/projects/japanese/SubMiner/config.example.jsonc
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/config/definitions/options-integrations.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/config/resolve/subtitle-domains.ts
+priority: high
+ordinal: 61500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Simplify launcher YouTube playback by removing the configurable subtitle generation mode. For YouTube targets, the launcher should treat subtitle generation/loading as the canonical behavior instead of supporting off/preprocess/automatic branches. This change should remove the unreliable automatic/background path and the mode concept from config/CLI/env/docs, while preserving the core YouTube subtitle generation pipeline and mpv loading flow.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Launcher playback no longer supports or branches on a YouTube subtitle generation mode; YouTube URLs follow a single generation-and-load flow.
+- [x] #2 Configuration, CLI parsing, and environment handling no longer expose a YouTube subtitle generation mode option, and stale automatic/preprocess/off values are not part of the supported interface.
+- [x] #3 Tests cover the new single-flow behavior and the removal of mode parsing/branching.
+- [x] #4 User-facing config/docs/examples are updated to reflect the removed mode concept.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Remove the YouTube subtitle generation mode concept from launcher/shared types, config parsing, CLI options, and environment normalization so no supported interface accepts automatic/preprocess/off.
+2. Update playback orchestration so YouTube targets always run subtitle generation/loading before mpv startup and delete the background automatic path.
+3. Adjust mpv YouTube URL argument construction to no longer branch on mode while preserving subtitle/audio language behavior and preloaded subtitle file injection.
+4. Add/modify tests first to cover removed mode parsing and the single YouTube preload flow, then update config/docs/examples to match the simplified interface.
+5. Run focused launcher/config tests plus typecheck, then summarize any remaining gaps.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Removed launcher/shared youtubeSubgen.mode handling and collapsed YouTube playback onto a single preload-before-mpv subtitle generation flow.
+
+Added launcher integration coverage proving YouTube subtitle generation runs before mpv startup and that the removed --mode flag now errors.
+
+Verification: bun test launcher/config-domain-parsers.test.ts launcher/parse-args.test.ts launcher/mpv.test.ts launcher/main.test.ts src/config/config.test.ts; bun run test:config:src; bun run typecheck.
+
+Broader repo checks still show pre-existing issues outside this change: bun run test:launcher:unit:src fails in launcher/aniskip-metadata.test.ts (MAL id assertion), and format scope check reports unrelated existing files launcher/youtube/orchestrator.ts, scripts/build-changelog.test.ts, scripts/build-changelog.ts.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Removed the launcher YouTube subtitle generation mode surface so YouTube playback now always runs the subtitle generation pipeline before starting mpv. The launcher no longer accepts youtubeSubgen.mode from shared config, CLI, or env normalization, and the old automatic/background loading path has been deleted from playback.
+
+Updated mpv YouTube startup options to keep manual subtitle discovery enabled without requesting auto subtitles, and refreshed user-facing config/docs to describe a single YouTube subtitle generation flow. Added regression coverage for mode removal, config/template cleanup, and launcher ordering so YouTube subtitle work is confirmed to happen before mpv launch.
+
+Verification: bun test launcher/config-domain-parsers.test.ts launcher/parse-args.test.ts launcher/mpv.test.ts launcher/main.test.ts src/config/config.test.ts; bun run test:config:src; bun run typecheck. Broader unrelated repo issues remain in launcher/aniskip-metadata.test.ts and existing formatting drift in launcher/youtube/orchestrator.ts plus scripts/build-changelog files.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-126 - Improve-secondary-subtitle-readability-with-hover-only-background-and-stronger-text-separation.md

@@ -0,0 +1,44 @@
+---
+id: TASK-126
+title: >-
+  Improve secondary subtitle readability with hover-only background and stronger
+  text separation
+status: Done
+assignee: []
+created_date: '2026-03-08 07:35'
+updated_date: '2026-03-16 05:13'
+labels:
+  - overlay
+  - subtitles
+  - ui
+dependencies: []
+priority: medium
+ordinal: 60500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Adjust overlay secondary subtitle styling so translation text stays readable on bright video backgrounds. Keep the dark background hidden by default in hover mode and show it only while hovered. Increase secondary subtitle weight to 600 and strengthen edge separation without changing primary subtitle styling.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Secondary subtitles render with stronger edge separation than today.
+- [x] #2 Secondary subtitle font weight defaults to 600.
+- [x] #3 When secondary subtitle mode is hover, the secondary background appears only while hovered.
+- [x] #4 Primary subtitle styling behavior remains unchanged.
+- [x] #5 Renderer tests cover the new secondary hover background behavior and default secondary style values.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Adjusted secondary subtitle defaults to use stronger shadowing, 600 font weight, and a translucent dark background. Routed secondary background/backdrop styling through CSS custom properties so hover mode can keep the background hidden until the secondary subtitle is actually hovered. Added renderer and config tests covering default values and hover-only background behavior.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Improved secondary subtitle readability by strengthening default text separation, increasing the default secondary weight to 600, and making the configured dark background appear only while hovered in secondary hover mode. Added config and renderer coverage for the new defaults and hover-aware style routing.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-127 - Skip-AniSkip-lookup-for-YouTube-and-URL-playback-targets.md

@@ -0,0 +1,84 @@
+---
+id: TASK-127
+title: Skip AniSkip lookup for YouTube and URL playback targets
+status: Done
+assignee:
+  - '@codex'
+created_date: '2026-03-08 08:24'
+updated_date: '2026-03-16 05:13'
+labels:
+  - bug
+  - launcher
+  - youtube
+dependencies: []
+references:
+  - /Users/sudacode/projects/japanese/SubMiner/launcher/mpv.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/launcher/commands/playback-command.ts
+  - /Users/sudacode/projects/japanese/SubMiner/launcher/mpv.test.ts
+ordinal: 56500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Prevent launcher playback from attempting AniSkip metadata resolution when the user is playing a YouTube target or any URL target. AniSkip only works for local anime files, so URL-driven playback and YouTube subtitle-generation flows should bypass it entirely.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Launcher playback skips AniSkip metadata resolution for explicit URL targets, including YouTube URLs.
+- [x] #2 YouTube subtitle-generation playback does not invoke AniSkip lookup before mpv launch.
+- [x] #3 Automated launcher tests cover the URL/YouTube skip behavior.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a launcher mpv unit test that intercepts AniSkip resolution and proves URL/YouTube playback does not call it before spawning mpv.
+2. Run the focused launcher mpv test to confirm the new case fails or exposes the current gap.
+3. Patch launcher playback/AniSkip gating so URL and YouTube subtitle-generation paths always bypass AniSkip lookup.
+4. Re-run focused launcher tests and record the verification results in task notes.
+
+5. Add a Lua plugin regression test covering overlay-start on URL playback so AniSkip never runs after auto-start.
+
+6. Patch plugin/subminer/aniskip.lua to short-circuit all AniSkip lookup triggers for remote URL media paths.
+
+7. Re-run plugin regression plus touched launcher checks and update the task summary with the plugin-side fix.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added explicit AniSkip gating in launcher/mpv.ts via shouldResolveAniSkipMetadata(target, targetKind, preloadedSubtitles).
+
+URL targets now always bypass AniSkip. File targets with preloaded subtitles also bypass AniSkip, covering YouTube subtitle-preload playback.
+
+Added launcher/mpv.test.ts coverage for local-file vs URL vs preloaded-subtitle AniSkip gating.
+
+Verification: bun test launcher/mpv.test.ts passed.
+
+Verification: bun run typecheck passed.
+
+Verification: bunx prettier --check launcher/mpv.ts launcher/mpv.test.ts passed.
+
+Verification: bun run changelog:lint passed.
+
+Verification: bun run test:launcher:unit:src remains blocked by unrelated existing failure in launcher/aniskip-metadata.test.ts (`resolveAniSkipMetadataForFile resolves MAL id and intro payload`: expected malId 1234, got null).
+
+Added plugin regression in scripts/test-plugin-start-gate.lua for URL playback with auto-start/overlay-start; it now asserts no MAL or AniSkip curl requests occur.
+
+Patched plugin/subminer/aniskip.lua to short-circuit AniSkip lookup for remote media paths (`scheme://...`), which covers YouTube URL playback inside the mpv plugin lifecycle.
+
+Verification: lua scripts/test-plugin-start-gate.lua passed.
+
+Verification: bun run test:plugin:src passed.
+
+Verification: bun test launcher/mpv.test.ts passed after plugin-side fix.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Fixed AniSkip suppression end-to-end for URL playback. The launcher now skips AniSkip before mpv launch, and the mpv plugin now also refuses AniSkip lookups for remote URL media during file-loaded, overlay-start, or later refresh triggers. Added regression coverage in both launcher/mpv.test.ts and scripts/test-plugin-start-gate.lua, plus a changelog fragment. Wider `bun run test:launcher:unit:src` is still blocked by the unrelated existing launcher/aniskip-metadata.test.ts MAL-id failure.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-128 - Prevent-AI-subtitle-fix-from-translating-primary-YouTube-subtitles-into-the-wrong-language.md

@@ -0,0 +1,36 @@
+---
+id: TASK-128
+title: >-
+  Prevent AI subtitle fix from translating primary YouTube subtitles into the
+  wrong language
+status: Done
+assignee: []
+created_date: '2026-03-08 09:02'
+updated_date: '2026-03-16 05:13'
+labels:
+  - bug
+  - youtube-subgen
+  - ai
+dependencies: []
+priority: high
+ordinal: 58500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+AI subtitle cleanup can preserve cue structure while changing subtitle language, causing primary Japanese subtitle files to come back in English. Add guards so AI-fixed subtitles preserve expected language and fall back to raw Whisper output when language drifts.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Primary AI subtitle fix rejects output that drifts away from the expected source language.
+- [x] #2 Rejected AI fixes fall back to the raw Whisper subtitle without corrupting published subtitle language.
+- [x] #3 Regression tests cover a primary Japanese subtitle batch being translated into English by the AI fixer.
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added a primary-language guard to AI subtitle fixing so Japanese source subtitles are rejected if the AI rewrites them into English while preserving SRT structure. The fixer now receives the expected source language from the YouTube orchestrator, and regression coverage verifies that language drift falls back to the raw Whisper subtitle path.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-129 - Split-AI-model-and-system-prompt-config-between-Anki-and-YouTube-subtitle-generation.md

@@ -0,0 +1,38 @@
+---
+id: TASK-129
+title: >-
+  Split AI model and system prompt config between Anki and YouTube subtitle
+  generation
+status: Done
+assignee: []
+created_date: '2026-03-08 09:40'
+updated_date: '2026-03-16 05:13'
+labels:
+  - config
+  - ai
+  - anki
+  - youtube-subgen
+dependencies: []
+priority: high
+ordinal: 57500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+The current top-level shared AI config forces Anki translation and YouTube subtitle fixing to share the same model and system prompt, which caused subtitle-fix requests to inherit a translation prompt and translate Japanese primary subtitles into English. Refactor config so provider credentials stay shared while model and system prompt can be configured per feature.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Anki integration can use its own AI model and system prompt independently of YouTube subtitle generation.
+- [x] #2 YouTube subtitle generation can use its own AI model and system prompt independently of Anki integration.
+- [x] #3 Existing shared provider credentials remain reusable without duplicating API key/base URL config.
+- [x] #4 Config example, defaults, validation, and regression tests cover the new per-feature override shape.
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added per-feature AI model/systemPrompt overrides for Anki and YouTube subtitle generation while keeping shared provider transport settings reusable. Anki now accepts `ankiConnect.ai` object config with `enabled`, `model`, and `systemPrompt`; YouTube subtitle generation accepts `youtubeSubgen.ai` overrides and merges them over the shared AI provider config. Updated config resolution, launcher parsing, runtime wiring, hot-reload handling, example config, and regression coverage.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-130 - Keep-background-SubMiner-alive-after-launcher-managed-mpv-exits.md

@@ -0,0 +1,78 @@
+---
+id: TASK-130
+title: Keep background SubMiner alive after launcher-managed mpv exits
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-08 10:08'
+updated_date: '2026-03-16 05:13'
+labels:
+  - bug
+  - launcher
+  - mpv
+  - overlay
+dependencies: []
+priority: high
+ordinal: 55500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+The launcher currently tears down the running SubMiner background process when a launcher-managed mpv session exits. Background SubMiner should remain alive so a later mpv instance can reconnect and request the overlay without restarting the app.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Closing a launcher-managed mpv session does not send `--stop` to the running SubMiner background process.
+- [x] #2 Closing a launcher-managed mpv session does not SIGTERM the tracked SubMiner process just because mpv exited.
+- [x] #3 Launcher cleanup still terminates mpv and launcher-owned helper children without regressing existing overlay start behavior.
+- [x] #4 Automated tests cover the no-stop-on-mpv-exit behavior.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a launcher regression test that proves mpv exit no longer triggers SubMiner `--stop` or launcher SIGTERM of the tracked overlay process.
+2. Update launcher teardown so normal mpv-session cleanup only stops mpv/helper children and preserves the background SubMiner process for future reconnects.
+3. Run the focused launcher tests and smoke coverage for the affected behavior, then record results in the task.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Split launcher cleanup so normal mpv-session shutdown no longer sends `--stop` to SubMiner or SIGTERM to the tracked overlay process. Added `cleanupPlaybackSession()` for mpv/helper-child cleanup only, and switched playback finalization to use it.
+
+Updated launcher smoke coverage to assert the background app stays alive after mpv exits, and added a focused unit regression for the new cleanup path.
+
+Validation: `bun test launcher/mpv.test.ts launcher/smoke.e2e.test.ts` passed; `bun run typecheck` passed. `bun run test:launcher:unit:src` still reports an unrelated pre-existing failure in `launcher/aniskip-metadata.test.ts`.
+
+Added changelog fragment `changes/task-130.md` for the launcher fix and verified it with `bun run changelog:lint`.
+
+User verified the bug still reproduces when closing playback with `q`. Root cause narrowed further: the mpv plugin `plugin/subminer/lifecycle.lua` calls `process.stop_overlay()` on mpv `shutdown`, which still sends SubMiner `--stop` even after launcher cleanup was fixed.
+
+Patched the remaining stop path in `plugin/subminer/lifecycle.lua`: mpv `shutdown` no longer calls `process.stop_overlay()`. Pressing mpv `q` should now preserve the background app and only tear down the mpv session.
+
+Validation update: `lua scripts/test-plugin-start-gate.lua` passed after adding a shutdown regression, and `bun test launcher/mpv.test.ts launcher/smoke.e2e.test.ts` still passed.
+
+Fixed a second-instance reconnect bug in `src/core/services/cli-command.ts`: `--start` on an already-initialized running instance now still updates the MPV socket path and reconnects the MPV client instead of treating the command as a no-op. This keeps the already-warmed background app reusable for later mpv launches.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Kept the background SubMiner process reusable across both mpv shutdown and later reconnects. The first fix separated launcher playback cleanup from full app shutdown. The second fix removed the mpv plugin `shutdown` stop call so default mpv `q` no longer sends SubMiner `--stop`. The third fix corrected second-instance CLI handling so `--start` on an already-running, already-initialized instance still reconnects MPV instead of being ignored.
+
+Net effect: background SubMiner can stay alive, keep its warm state, and reconnect to later mpv instances without rerunning startup/warmup work in a fresh app instance.
+
+Coverage now includes: launcher playback cleanup (`launcher/mpv.test.ts`), launcher smoke reconnect/keep-alive flow (`launcher/smoke.e2e.test.ts`), mpv plugin shutdown preservation (`scripts/test-plugin-start-gate.lua`), and second-instance start/reconnect behavior (`src/core/services/cli-command.test.ts`).
+
+Tests run:
+
+- `bun test src/core/services/cli-command.test.ts launcher/mpv.test.ts launcher/smoke.e2e.test.ts`
+- `lua scripts/test-plugin-start-gate.lua`
+- `bun run typecheck`
+- `bun run changelog:lint`
+
+Note: the broader `bun run test:launcher:unit:src` lane still has an unrelated pre-existing failure in `launcher/aniskip-metadata.test.ts`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-131 - Make-default-overlay-fullscreen-and-AniSkip-end-jump-keybindings-easier-to-reach.md

@@ -0,0 +1,75 @@
+---
+id: TASK-131
+title: >-
+  Make default overlay fullscreen and AniSkip end-jump keybindings easier to
+  reach
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-09 00:00'
+updated_date: '2026-03-18 05:28'
+labels:
+  - enhancement
+  - overlay
+  - mpv
+  - aniskip
+dependencies: []
+ordinal: 43500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Make two default keyboard actions easier to hit during playback: add `f` as the built-in overlay fullscreen toggle, and make AniSkip's default intro-end jump use `Tab`.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Default overlay keybindings include `KeyF` mapped to mpv fullscreen toggle.
+- [x] #2 Default AniSkip hint/button key defaults to `Tab` and the plugin registers that binding.
+- [x] #3 Automated regression coverage exists for both default bindings.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a failing TypeScript regression proving default overlay keybindings include fullscreen on `KeyF`.
+2. Add a failing Lua/plugin regression proving AniSkip defaults to `Tab`, updates the OSD hint text, and registers the expected keybinding.
+3. Patch the default keybinding/config values with minimal behavior changes and keep fallback binding behavior intentional.
+4. Run focused tests plus touched verification commands, then record results and a short changelog fragment.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added `KeyF -> ['cycle', 'fullscreen']` to the built-in overlay keybindings in `src/config/definitions/shared.ts`.
+
+Changed the mpv plugin AniSkip default button key from `y-k` to `TAB` in both the runtime default options and the shipped `plugin/subminer.conf`. The AniSkip OSD hint now also falls back to `TAB` when no explicit key is configured.
+
+Adjusted `plugin/subminer/ui.lua` fallback registration so the legacy `y-k` binding is only added for custom non-default AniSkip bindings, instead of always shadowing the new default.
+
+Extended regression coverage:
+
+- `src/config/definitions/domain-registry.test.ts` now asserts the default fullscreen binding on `KeyF`.
+- `scripts/test-plugin-start-gate.lua` now isolates plugin runs correctly, records keybinding/observer registration, and asserts the default AniSkip keybinding/prompt behavior for `TAB`.
+
+Verification:
+
+- `bun test src/config/definitions/domain-registry.test.ts`
+- `bun run test:config:src`
+- `lua scripts/test-plugin-start-gate.lua`
+- `bun run changelog:lint`
+- `bun run typecheck`
+
+Known unrelated verification gap:
+
+- `bun run test:plugin:src` still fails in `scripts/test-plugin-binary-windows.lua` on this Linux host (`windows env override should resolve .exe suffix`), outside the keybinding changes in this task.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Default overlay playback now has an easier fullscreen toggle on `f`, and AniSkip's default intro-end jump now uses `Tab`. The mpv plugin hint text and registration logic were updated to match the new default, while keeping legacy `y-k` fallback behavior limited to custom non-default bindings.
+
+Regression coverage was added for both defaults, and the plugin test harness now resets plugin bootstrap state between scenarios so keybinding assertions can run reliably.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-132 - Gate-macOS-overlay-shortcuts-to-the-focused-mpv-window.md

@@ -0,0 +1,70 @@
+---
+id: TASK-132
+title: Gate macOS overlay shortcuts to the focused mpv window
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-08 18:24'
+updated_date: '2026-03-18 05:28'
+labels:
+  - bug
+  - macos
+  - shortcuts
+dependencies: []
+references:
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/core/services/overlay-shortcut.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/window-trackers/macos-tracker.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/scripts/get-mpv-window-macos.swift
+priority: high
+ordinal: 53500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Fix the macOS shortcut handling so SubMiner overlay keybinds do not intercept system or other-app shortcuts while SubMiner is in the background. Overlay shortcuts should only be active while the tracked mpv window is present and focused, and should stop grabbing keyboard input when mpv is not the frontmost window.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 On macOS, overlay shortcuts do not trigger while mpv is not the focused/frontmost window.
+- [x] #2 On macOS, overlay shortcuts remain available while the tracked mpv window is open and focused.
+- [x] #3 Existing non-macOS shortcut behavior is unchanged.
+- [x] #4 Automated tests cover the macOS focus-gating behavior and guard against background shortcut interception.
+- [x] #5 Any user-facing docs/config notes affected by the behavior change are updated in the same task if needed.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a failing macOS-focused shortcut lifecycle test that proves overlay shortcuts stay inactive when the tracked mpv window exists but is not frontmost, and activate when that tracked window becomes frontmost.
+2. Add a failing tracker/helper test that covers the focused/frontmost signal parsed from the macOS helper output.
+3. Extend the macOS helper/tracker contract to surface both geometry and focused/frontmost state for the tracked mpv window.
+4. Wire overlay shortcut activation to require both overlay runtime initialization and tracked-mpv focus on macOS, while leaving non-macOS behavior unchanged.
+5. Re-run the targeted shortcut/tracker tests, then the broader related shortcut/runtime suite, and update task notes/acceptance criteria based on results.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added a macOS-specific shortcut activation predicate so global overlay shortcuts now require both overlay runtime readiness and a focused tracked mpv window; non-macOS behavior still keys off runtime readiness only.
+
+Extended the base window tracker with optional focus-state callbacks/getters and wired initializeOverlayRuntime to re-sync overlay shortcuts whenever tracker focus changes.
+
+Updated the macOS helper/tracker contract to return geometry plus frontmost/focused state for the tracked mpv process and added parser coverage for focused and unfocused output.
+
+Verified with `bun x tsc -p tsconfig.json --noEmit`, targeted shortcut/tracker tests, and `bun run test:core:src` (439 passing).
+
+No user-facing config or documentation surface changed, so no docs update was required for this fix.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Fixed the macOS background shortcut interception bug by gating SubMiner's global overlay shortcuts on tracked mpv focus instead of overlay-runtime initialization alone. The macOS window helper now reports whether the tracked mpv process is frontmost, the tracker exposes focus change callbacks, and overlay shortcut synchronization re-runs when that focus state flips so `Ctrl+C`/`Ctrl+V` and similar shortcuts are no longer captured while mpv is in the background.
+
+The change keeps existing non-macOS shortcut behavior unchanged. Added regression coverage for the activation decision, tracker focus-change re-sync, and macOS helper output parsing. Verification: `bun x tsc -p tsconfig.json --noEmit`, targeted shortcut/tracker tests, and `bun run test:core:src` (439 passing).
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-134 - Harden-Windows-release-signing-against-transient-SignPath-failures.md

@@ -0,0 +1,67 @@
+---
+id: TASK-134
+title: Harden Windows release signing against transient SignPath failures
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-09 00:00'
+updated_date: '2026-03-18 05:28'
+labels:
+  - ci
+  - release
+  - windows
+  - signing
+dependencies: []
+references:
+  - .github/workflows/release.yml
+  - package.json
+  - src/release-workflow.test.ts
+  - 'https://github.com/ksyasuda/SubMiner/actions/runs/22836585479'
+priority: high
+ordinal: 52500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+The tag-driven Release workflow currently fails the Windows lane if the SignPath connector returns transient 502 errors during submission, and the tagged build scripts also allow electron-builder to implicitly publish unsigned artifacts before the final release job runs. Harden the workflow so transient SignPath outages get bounded retries and release packaging never auto-publishes unsigned assets.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 Windows release signing retries transient SignPath submission failures within the release workflow before failing the job.
+- [ ] #2 Release packaging scripts disable electron-builder implicit publish so build jobs do not upload unsigned assets on tag builds.
+- [ ] #3 Regression coverage fails if SignPath retry scaffolding or publish suppression is removed.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a regression test for the release workflow/package script shape covering SignPath retries and `--publish never`.
+2. Patch the Windows release job to retry SignPath submission a bounded number of times and still fail hard if every attempt fails.
+3. Update tagged package build scripts to disable implicit electron-builder publishing during release builds.
+4. Run targeted release-workflow verification and capture any remaining manual release cleanup needed for `v0.5.0`.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+The failed Windows signing step in GitHub Actions run `22836585479` was not caused by missing secrets or an artifact-shape mismatch. The SignPath GitHub action retried repeated `502` responses from the SignPath connector for several minutes and then failed the job.
+
+Hardened `.github/workflows/release.yml` by replacing the single SignPath submission with three bounded attempts. The second and third submissions only run if the previous attempt failed, and the job now fails with an explicit rerun message only after all three attempts fail. Signed-artifact upload is keyed to the successful attempt so the release job still consumes the normal `windows` artifact name.
+
+Also fixed a separate release regression exposed by the same run: `electron-builder` was implicitly publishing unsigned release assets during tag builds because the packaging scripts did not set `--publish never` and the workflow injected `GH_TOKEN` into build jobs. Updated the relevant package scripts to pass `--publish never`, removed `GH_TOKEN` from the packaging jobs, and made the final publish step force `--draft=false` when editing an existing tag release so previously-created draft releases get published.
+
+Verification: `bun test src/release-workflow.test.ts`, `bun run typecheck`, and `bun run test:fast` all passed locally after restoring the missing local `libsql` install with `bun install --frozen-lockfile`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Windows release signing is now resilient to transient SignPath connector outages. The release workflow retries the SignPath submission up to three times before failing, and only uploads the signed Windows artifact from the attempt that succeeded.
+
+Release packaging also no longer auto-publishes unsigned assets on tag builds. The `electron-builder` scripts now force `--publish never`, the build jobs no longer pass `GH_TOKEN` into packaging steps, and the final GitHub release publish step explicitly clears draft state when updating an existing tag release.
+
+Validation: `bun test src/release-workflow.test.ts`, `bun run typecheck`, `bun run test:fast`.
+Manual follow-up for the failed `v0.5.0` release: rerun the `Release` workflow after merging/pushing this fix, then clean up the stray draft/untagged release assets created by the failed run if they remain.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-135 - Cut-patch-release-v0.5.1-for-Windows-signing-fix.md

@@ -0,0 +1,58 @@
+---
+id: TASK-135
+title: Cut patch release v0.5.1 for Windows signing fix
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-08 20:24'
+updated_date: '2026-03-18 05:28'
+labels:
+  - release
+  - patch
+dependencies:
+  - TASK-134
+references:
+  - package.json
+  - CHANGELOG.md
+  - release/release-notes.md
+priority: high
+ordinal: 51500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Publish a patch release from the workflow-signing fix on `main` by bumping the app version, generating the committed changelog artifacts for the new version, and pushing a new `v0.5.1` tag instead of rewriting the failed `v0.5.0` tag.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 Repository version metadata is updated to `0.5.1`.
+- [ ] #2 `CHANGELOG.md` and `release/release-notes.md` contain the committed `v0.5.1` section and released fragments are removed.
+- [ ] #3 New `v0.5.1` commit and tag are pushed to `origin`.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Bump the package version to `0.5.1`.
+2. Run the changelog builder so `CHANGELOG.md`/`release-notes.md` match the release workflow contract.
+3. Run the relevant verification commands.
+4. Commit the release-prep changes, create `v0.5.1`, and push both commit and tag.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Bumped `package.json` from `0.5.0` to `0.5.1`, then ran `bun run changelog:build` so the committed release artifacts match the release workflow contract. That prepended the `v0.5.1` section to `CHANGELOG.md`, regenerated `release/release-notes.md`, and removed the consumed changelog fragments from `changes/`.
+
+Verification before tagging: `bun run changelog:lint`, `bun run changelog:check --version 0.5.1`, `bun run typecheck`, and `bun run test:fast`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Prepared patch release `v0.5.1` from the signing-workflow fix on `main` instead of rewriting the failed `v0.5.0` tag. Repository version metadata, changelog, and committed release notes are all aligned with the new release tag, and the consumed changelog fragments were removed.
+
+Validation: `bun run changelog:lint`, `bun run changelog:check --version 0.5.1`, `bun run typecheck`, `bun run test:fast`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-136 - Pin-SignPath-artifact-configuration-in-release-workflow.md

@@ -0,0 +1,62 @@
+---
+id: TASK-136
+title: Pin SignPath artifact configuration in release workflow
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-08 20:41'
+updated_date: '2026-03-18 05:28'
+labels:
+  - ci
+  - release
+  - windows
+  - signing
+dependencies:
+  - TASK-134
+references:
+  - .github/workflows/release.yml
+  - build/signpath-windows-artifact-config.xml
+  - src/release-workflow.test.ts
+priority: high
+ordinal: 49500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+The Windows release workflow currently relies on the default SignPath artifact configuration configured in the SignPath UI. Pin the workflow to an explicit artifact-configuration slug so the checked-in signing configuration and CI behavior stay deterministic across future SignPath project changes.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 The Windows release workflow validates a dedicated SignPath artifact-configuration secret/input.
+- [ ] #2 Every SignPath submission attempt passes `artifact-configuration-slug`.
+- [ ] #3 Regression coverage fails if the explicit SignPath artifact-configuration binding is removed.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a failing workflow regression test for the explicit SignPath artifact-configuration slug.
+2. Patch the Windows signing secret validation and SignPath action inputs to require the slug.
+3. Run targeted release-workflow verification plus the standard fast lane.
+4. Cut a new patch release so the tag-triggered release workflow runs with the pinned SignPath configuration.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added regression coverage in `src/release-workflow.test.ts` for an explicit SignPath artifact-configuration slug so the release workflow test now fails if the slug validation or action input is removed.
+
+Patched `.github/workflows/release.yml` so Windows signing now requires `SIGNPATH_ARTIFACT_CONFIGURATION_SLUG` during secret validation and passes `artifact-configuration-slug: ${{ secrets.SIGNPATH_ARTIFACT_CONFIGURATION_SLUG }}` on every SignPath submission attempt.
+
+Verification: `bun test src/release-workflow.test.ts`, `bun run typecheck`, `bun run test:fast`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+The release workflow is now pinned to an explicit SignPath artifact configuration instead of relying on whichever SignPath artifact config is marked default in the UI. Windows signing secret validation fails fast if `SIGNPATH_ARTIFACT_CONFIGURATION_SLUG` is missing, and every SignPath submission attempt now includes the pinned slug.
+
+Validation: `bun test src/release-workflow.test.ts`, `bun run typecheck`, `bun run test:fast`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-137 - Cut-patch-release-v0.5.2-for-SignPath-artifact-config-pinning.md

@@ -0,0 +1,58 @@
+---
+id: TASK-137
+title: Cut patch release v0.5.2 for SignPath artifact config pinning
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-08 20:44'
+updated_date: '2026-03-18 05:28'
+labels:
+  - release
+  - patch
+dependencies:
+  - TASK-136
+references:
+  - package.json
+  - CHANGELOG.md
+  - release/release-notes.md
+priority: high
+ordinal: 50500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Publish a patch release from the SignPath artifact-configuration pinning change by bumping the app version, generating the committed changelog artifacts for the new version, and pushing a new `v0.5.2` tag.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 Repository version metadata is updated to `0.5.2`.
+- [ ] #2 `CHANGELOG.md` and `release/release-notes.md` contain the committed `v0.5.2` section and consumed fragments are removed.
+- [ ] #3 New `v0.5.2` commit and tag are pushed to `origin`.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add the release fragment for the SignPath configuration pinning change.
+2. Bump `package.json` to `0.5.2` and run the changelog builder.
+3. Run changelog/typecheck/test verification.
+4. Commit the release-prep change set, create `v0.5.2`, and push commit plus tag.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Bumped `package.json` from `0.5.1` to `0.5.2`, ran `bun run changelog:build`, and committed the generated release artifacts. That prepended the `v0.5.2` section to `CHANGELOG.md`, regenerated `release/release-notes.md`, and removed the consumed `changes/signpath-artifact-config-pin.md` fragment.
+
+Verification before tagging: `bun run changelog:lint`, `bun run changelog:check --version 0.5.2`, `bun run typecheck`, and `bun run test:fast`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Prepared patch release `v0.5.2` so the explicit SignPath artifact-configuration pin ships on a fresh release tag. Version metadata, committed changelog artifacts, and release notes are aligned with the new patch version.
+
+Validation: `bun run changelog:lint`, `bun run changelog:check --version 0.5.2`, `bun run typecheck`, `bun run test:fast`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-138 - Publish-unsigned-Windows-release-artifacts-and-add-local-unsigned-build-script.md

@@ -0,0 +1,64 @@
+---
+id: TASK-138
+title: Publish unsigned Windows release artifacts and add local unsigned build script
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-09 00:00'
+updated_date: '2026-03-18 05:28'
+labels:
+  - release
+  - windows
+dependencies: []
+references:
+  - .github/workflows/release.yml
+  - package.json
+  - src/release-workflow.test.ts
+priority: high
+ordinal: 45500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Stop the tag-driven release workflow from depending on SignPath and publish unsigned Windows `.exe` and `.zip` artifacts directly. Add an explicit local `build:win:unsigned` script without changing the existing `build:win` command.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Windows release CI builds unsigned artifacts without requiring SignPath secrets.
+- [x] #2 The Windows release job uploads `release/*.exe` and `release/*.zip` directly as the `windows` artifact.
+- [x] #3 The repo exposes a local `build:win:unsigned` script for explicit unsigned Windows packaging.
+- [x] #4 Regression coverage fails if the workflow reintroduces SignPath submission or drops the unsigned script.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Update workflow regression tests to assert unsigned Windows release behavior and the new local script.
+2. Patch `package.json` to add `build:win:unsigned`.
+3. Patch `.github/workflows/release.yml` to build unsigned Windows artifacts and upload them directly.
+4. Add the release changelog fragment and run focused verification.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Removed the Windows SignPath secret validation and submission steps from `.github/workflows/release.yml`. The Windows release job now runs `bun run build:win:unsigned` and uploads `release/*.exe` and `release/*.zip` directly as the `windows` artifact consumed by the release job.
+
+Added `scripts/build-win-unsigned.mjs` plus the `build:win:unsigned` package script. The wrapper clears Windows code-signing environment variables and disables identity auto-discovery before invoking `electron-builder`, so release CI stays unsigned even if signing credentials are configured elsewhere.
+
+Updated `src/release-workflow.test.ts` to assert the unsigned workflow contract and added the release changelog fragment in `changes/unsigned-windows-release-builds.md`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Windows release CI now publishes unsigned artifacts directly and no longer depends on SignPath. Local developers also have an explicit `bun run build:win:unsigned` path for unsigned packaging without changing the existing `build:win` command.
+
+Verification:
+
+- `bun test src/release-workflow.test.ts`
+- `bun run typecheck`
+- `node --check scripts/build-win-unsigned.mjs`
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-139 - Cut-patch-release-v0.5.3-for-unsigned-Windows-release-builds.md

@@ -0,0 +1,58 @@
+---
+id: TASK-139
+title: Cut patch release v0.5.3 for unsigned Windows release builds
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-09 00:00'
+updated_date: '2026-03-18 05:28'
+labels:
+  - release
+  - patch
+dependencies:
+  - TASK-138
+references:
+  - package.json
+  - CHANGELOG.md
+  - release/release-notes.md
+priority: high
+ordinal: 46500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Publish a patch release from the unsigned Windows release-build change by bumping the app version, generating committed changelog artifacts for `v0.5.3`, and pushing the release-prep commit.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Repository version metadata is updated to `0.5.3`.
+- [x] #2 `CHANGELOG.md` and `release/release-notes.md` contain the committed `v0.5.3` section and consumed fragments are removed.
+- [x] #3 New `v0.5.3` release-prep commit is pushed to `origin/main`.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Bump `package.json` from `0.5.2` to `0.5.3`.
+2. Run `bun run changelog:build` so committed changelog artifacts match the new patch version.
+3. Run changelog/typecheck/test verification.
+4. Commit the release-prep change set and push `main`.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Bumped `package.json` from `0.5.2` to `0.5.3`, ran `bun run changelog:build`, and committed the generated release artifacts. That prepended the `v0.5.3` section to `CHANGELOG.md`, regenerated `release/release-notes.md`, and removed the consumed `changes/unsigned-windows-release-builds.md` fragment.
+
+Verification before push: `bun run changelog:lint`, `bun run changelog:check --version 0.5.3`, `bun run typecheck`, and `bun run test:fast`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Prepared patch release `v0.5.3` so the unsigned Windows release-build change is captured in committed release metadata on `main`. Version metadata, changelog output, and release notes are aligned with the new patch version.
+
+Validation: `bun run changelog:lint`, `bun run changelog:check --version 0.5.3`, `bun run typecheck`, `bun run test:fast`.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-140 - Fix-guessit-title-parsing-for-character-dictionary-sync.md

@@ -0,0 +1,41 @@
+---
+id: TASK-140
+title: Fix guessit title parsing for character dictionary sync
+status: Done
+assignee: []
+created_date: '2026-03-09 00:00'
+updated_date: '2026-03-18 05:28'
+labels:
+  - dictionary
+  - anilist
+  - bug
+  - guessit
+dependencies: []
+references:
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/core/services/anilist/anilist-updater.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/core/services/anilist/anilist-updater.test.ts
+priority: high
+ordinal: 44500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Fix AniList character dictionary auto-sync for filenames where `guessit` misparses the full path and our title extraction keeps only the first array segment, causing AniList resolution to match the wrong anime and abort merged dictionary refresh.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 AniList media guessing passes basename-only targets to `guessit` so parent folder names do not corrupt series title detection.
+- [x] #2 Guessit title arrays are combined into one usable title instead of truncating to the first segment.
+- [x] #3 Regression coverage includes the Bunny Girl Senpai filename shape that previously resolved to the wrong AniList entry.
+- [x] #4 Verification confirms the targeted AniList guessing tests pass.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Root repro: `guessit` parsed the Bunny Girl Senpai full path as `title: ["Rascal", "Does-not-Dream-of-Bunny-Girl-Senapi"]`, and our `firstString` helper kept only `Rascal`, which resolved to AniList 3490 (`rayca`) and produced zero character results. Fixed by sending basename-only input to `guessit` and joining multi-part guessit title arrays.
+<!-- SECTION:NOTES:END -->

backlog/completed/task-141 - Refresh-current-subtitle-after-character-dictionary-sync-completes.md

@@ -0,0 +1,38 @@
+---
+id: TASK-141
+title: Refresh current subtitle after character dictionary sync completes
+status: Done
+assignee: []
+created_date: '2026-03-09 00:00'
+updated_date: '2026-03-18 05:28'
+labels:
+  - dictionary
+  - overlay
+  - bug
+dependencies: []
+references:
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
+  - /home/sudacode/projects/japanese/SubMiner/src/main.ts
+priority: high
+ordinal: 42500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+When character dictionary auto-sync finishes after startup tokenization, invalidate cached subtitle tokenization and refresh the current subtitle so character-name highlighting catches up without waiting for the next subtitle line.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Successful character dictionary sync exposes a completion hook for main runtime follow-up.
+- [x] #2 Main runtime clears Yomitan parser caches and refreshes the current subtitle after sync completion.
+- [x] #3 Regression coverage verifies the sync completion callback fires on successful sync.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Observed on Bunny Girl Senpai startup: autoplay/tokenization became ready around 8s, but snapshot/import/state write completed roughly 31s after launch, leaving the current subtitle tokenized without the newly imported character dictionary. Fixed by adding an auto-sync completion hook that clears parser caches and refreshes the current subtitle.
+<!-- SECTION:NOTES:END -->

backlog/completed/task-142 - Show-character-dictionary-auto-sync-progress-on-OSD.md

@@ -0,0 +1,40 @@
+---
+id: TASK-142
+title: Show character dictionary auto-sync progress on OSD
+status: Done
+assignee: []
+created_date: '2026-03-09 01:10'
+updated_date: '2026-03-18 05:28'
+labels:
+  - dictionary
+  - overlay
+  - ux
+dependencies: []
+references:
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync-notifications.ts
+  - /home/sudacode/projects/japanese/SubMiner/src/main.ts
+priority: medium
+ordinal: 41500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+When character dictionary auto-sync runs for a newly opened anime, surface progress so users know why character-name lookup/highlighting is temporarily unavailable via the mpv OSD without desktop notification popups.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Character dictionary auto-sync emits progress events for syncing, importing, ready, and failure states.
+- [x] #2 Main runtime routes those progress events through OSD notifications without desktop notifications.
+- [x] #3 Regression coverage verifies progress events and notification routing behavior.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+OSD now shows auto-sync phase changes while the dictionary updates. Desktop notifications were removed for this path to avoid startup popup spam.
+<!-- SECTION:NOTES:END -->

backlog/completed/task-143 - Keep-character-dictionary-auto-sync-non-blocking-during-startup.md

@@ -0,0 +1,53 @@
+---
+id: TASK-143
+title: Keep character dictionary auto-sync non-blocking during startup
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-09 01:45'
+updated_date: '2026-03-23 03:22'
+labels:
+  - dictionary
+  - startup
+  - performance
+dependencies: []
+references:
+  - /home/sudacode/projects/japanese/SubMiner/src/main.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/current-media-tokenization-gate.ts
+priority: high
+ordinal: 144500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Keep character dictionary auto-sync running in parallel during startup without delaying playback. Only tokenization readiness should gate playback; character dictionary import/settings updates should wait until tokenization is already ready and then refresh annotations afterward.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Character dictionary snapshot/build work can run immediately during startup.
+- [x] #2 Yomitan dictionary mutation work waits until current-media tokenization is ready.
+- [x] #3 Regression coverage verifies auto-sync builds before the gate and only mutates Yomitan after the gate resolves.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a regression test for startup autoplay release surviving delayed mpv readiness or late subtitle refresh after dictionary sync.
+2. Harden the autoplay-ready release path so paused startup keeps retrying until mpv is actually released or media changes, without resuming user-paused playback later.
+3. Keep the existing character-dictionary revisit fixes and paused-startup OSD fixes aligned with the autoplay change, then run targeted runtime tests and typecheck.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added a small current-media tokenization gate in main runtime. Media changes reset the gate, the first tokenization-ready event marks it ready, and auto-sync now waits on that gate only before Yomitan dictionary inspection/import/settings updates. Snapshot generation and merged ZIP build still run immediately in parallel.
+
+2026-03-20: User reports startup remains paused after annotations/tokenization are visible and only resumes after character-dictionary generation/import finishes. Investigating autoplay-ready release regression vs dictionary sync completion refresh.
+
+2026-03-20: Added startup autoplay retry-budget helper so paused startup retries cover the full plugin gate window instead of only ~2.8s. Verification: bun test src/main/runtime/startup-autoplay-release-policy.test.ts src/main/runtime/character-dictionary-auto-sync.test.ts src/main/runtime/startup-osd-sequencer.test.ts src/main/runtime/character-dictionary-auto-sync-completion.test.ts; bun run typecheck; bun run test:fast; bun run test:env; bun run build; bun run test:smoke:dist; runtime-compat verifier passed at .tmp/skill-verification/subminer-verify-20260320-022106-nM28Nk. Pending real installed-app/mpv validation.
+<!-- SECTION:NOTES:END -->