build: switch Yomitan to submodule-built artifact

- Add `texthooker.launchAtStartup` (default `true`) and wire startup behavior
- Add dedicated `annotationWebsocket` config/service path (default port `6678`) for texthooker annotations
- Regenerate config example/tests and update Yomitan patching/vendor assets

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

@@ -1,46 +0,0 @@
----
-name: subminer-change-verification
-description: Verify SubMiner changes with repo-native cheap-first test lanes. Use after code, config, launcher, plugin, runtime, stats, documentation, or workflow changes; do not use for read-only questions.
----
-
-# SubMiner Change Verification
-
-Verify the behavior claimed by a change without running unrelated expensive checks by default.
-
-## Workflow
-
-1. Inspect the requested scope and changed paths with `git status --short` and `git diff`.
-2. Read `docs/workflow/verification.md` as the source of truth for maintained lanes.
-3. Run the cheapest lane or lanes that cover the changed behavior.
-4. Escalate to the full handoff gate only for substantial or cross-boundary changes.
-5. Report exact commands, results, skipped checks, blockers, and remaining risk.
-
-Do not use hidden wrapper commands. Verification commands are owned by `package.json` and the workflow documentation.
-
-## Lane Selection
-
-- Internal docs, `AGENTS.md`, or `.agents/skills/**`: `bun run test:docs:kb`
-- User-facing `docs-site/**`: `bun run docs:test`, then `bun run docs:build`
-- Config/schema/defaults: `bun run test:config`
-  - If defaults or templates changed, also run `bun run generate:config-example` and `bun run verify:config-example`.
-- General TypeScript source: `bun run typecheck`, then `bun run test:fast`
-- Launcher or mpv plugin: `bun run test:launcher` or `bun run test:env`, based on the behavior changed
-- Runtime compatibility or dist-sensitive wiring: `bun run test:runtime:compat`
-- Stats dashboard: `bun run test:stats`
-- Overlay, renderer, mpv, or mining behavior in the running app: `bun run build`, then `bun run test:e2e`
-- Build/release scripts: `bun run test:scripts`
-
-For substantial changes, use the full gate documented in `AGENTS.md` and `docs/workflow/verification.md`.
-
-## Runtime Escalation
-
-Real runtime checks are required when the claim depends on actual Electron, mpv, overlay, focus, window tracking, launch, or socket behavior. Run the relevant application flow when the environment supports it. Otherwise, report the missing runtime dependency and do not present cheaper checks as authoritative runtime validation.
-
-## Pre-Handoff Checks
-
-Before handoff, reconcile both questions:
-
-1. Do behavior, defaults, flags, shortcuts, ports, APIs, architecture, or workflow changes require documentation updates?
-2. Does the change require a current-outcome fragment under `changes/` according to `changes/README.md`?
-
-Complete required updates before handoff or report the blocker.

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

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

.github/FUNDING.yml

@@ -1,15 +0,0 @@
-# These are supported funding model platforms
-
-github: [ksyasuda]
-patreon: # Replace with a single Patreon username
-open_collective: # Replace with a single Open Collective username
-ko_fi: sudacode
-tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
-community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
-liberapay: # Replace with a single Liberapay username
-issuehunt: # Replace with a single IssueHunt username
-lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
-polar: # Replace with a single Polar username
-buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
-thanks_dev: # Replace with a single thanks.dev username
-custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,105 +0,0 @@
-name: Bug Report
-description: Report something that is broken or behaving incorrectly
-title: '[Bug]: '
-labels: ['bug']
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Thanks for taking the time to file a bug report! Please search [existing issues](https://github.com/ksyasuda/SubMiner/issues?q=is%3Aissue) first to avoid duplicates.
-
-  - type: textarea
-    id: what-happened
-    attributes:
-      label: What happened?
-      description: A clear description of the bug, including what you expected to happen instead.
-      placeholder: When I open the Yomitan popup, the overlay freezes...
-    validations:
-      required: true
-
-  - type: textarea
-    id: reproduction
-    attributes:
-      label: Steps to reproduce
-      description: Minimal, ordered steps that reliably trigger the bug.
-      placeholder: |
-        1. Launch `subminer`
-        2. Play a video in MPV
-        3. Hover a word and press ...
-        4. See error
-    validations:
-      required: true
-
-  - type: dropdown
-    id: area
-    attributes:
-      label: Affected area
-      description: Which part of SubMiner is affected?
-      options:
-        - Overlay / Yomitan popup
-        - Anki mining
-        - Subtitle annotations
-        - Subtitle sidebar
-        - Immersion tracking / stats
-        - Launcher / CLI
-        - MPV plugin
-        - Jellyfin integration
-        - Jimaku integration
-        - AniList integration
-        - YouTube integration
-        - Character dictionary
-        - WebSocket / texthooker API
-        - Configuration
-        - Documentation
-        - Other / not sure
-    validations:
-      required: true
-
-  - type: dropdown
-    id: os
-    attributes:
-      label: Operating system
-      options:
-        - Linux
-        - macOS
-        - Windows
-    validations:
-      required: true
-
-  - type: input
-    id: version
-    attributes:
-      label: SubMiner version
-      description: Output of `subminer --version`, or the release tag / commit you are running.
-      placeholder: v0.15.0
-    validations:
-      required: true
-
-  - type: input
-    id: compositor
-    attributes:
-      label: Compositor (Linux only)
-      description: SubMiner's overlay supports Hyprland and sway. Name yours (and version if known). Leave blank on macOS / Windows.
-      placeholder: Hyprland 0.55
-    validations:
-      required: false
-
-  - type: input
-    id: mpv-version
-    attributes:
-      label: MPV version
-      description: Output of `mpv --version` (first line).
-      placeholder: mpv 0.38.0
-    validations:
-      required: false
-
-  - type: textarea
-    id: logs
-    attributes:
-      label: Logs / console output
-      description: |
-        Relevant logs. For verbose output, run `electron . --dev --log-level debug`.
-        This will be rendered as code automatically — no backticks needed.
-      render: shell
-    validations:
-      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +0,0 @@
-blank_issues_enabled: false
-contact_links:
-  - name: Documentation
-    url: https://docs.subminer.moe
-    about: Setup, configuration, and feature docs — check here before filing an issue.
-  - name: Troubleshooting guide
-    url: https://docs.subminer.moe/troubleshooting
-    about: Common problems and fixes (Hyprland rules, MPV detection, Anki connection, etc.).

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,59 +0,0 @@
-name: Feature Request
-description: Suggest a new feature or an improvement to an existing one
-title: '[Feature]: '
-labels: ['enhancement']
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Thanks for the idea! Please search [existing issues](https://github.com/ksyasuda/SubMiner/issues?q=is%3Aissue) first to avoid duplicates.
-
-  - type: textarea
-    id: problem
-    attributes:
-      label: Problem / motivation
-      description: What problem are you trying to solve? What is missing or frustrating today?
-      placeholder: When mining a card I have to manually switch to Anki because...
-    validations:
-      required: true
-
-  - type: textarea
-    id: proposal
-    attributes:
-      label: Proposed solution
-      description: Describe the feature or change you'd like to see.
-    validations:
-      required: true
-
-  - type: dropdown
-    id: area
-    attributes:
-      label: Related area
-      description: Which part of SubMiner does this relate to?
-      options:
-        - Overlay / Yomitan popup
-        - Anki mining
-        - Subtitle annotations
-        - Subtitle sidebar
-        - Immersion tracking / stats
-        - Launcher / CLI
-        - MPV plugin
-        - Jellyfin integration
-        - Jimaku integration
-        - AniList integration
-        - YouTube integration
-        - Character dictionary
-        - WebSocket / texthooker API
-        - Configuration
-        - Documentation
-        - Other / new area
-    validations:
-      required: true
-
-  - type: textarea
-    id: alternatives
-    attributes:
-      label: Alternatives considered
-      description: Any workarounds you currently use or other approaches you've thought about.
-    validations:
-      required: false

.github/pull_request_template.md

@@ -1,36 +0,0 @@
-<!--
-Thanks for contributing to SubMiner! Fill out the sections below.
-Keep it short — a couple of sentences per section is fine.
--->
-
-## Summary
-
-<!-- What does this PR do and why? -->
-
-## Type of change
-
-<!-- Check all that apply. -->
-
-- [ ] Bug fix
-- [ ] New feature
-- [ ] Refactor / internal
-- [ ] Documentation
-- [ ] Other
-
-## Related issues
-
-<!-- e.g. "Closes #123". Delete if none. -->
-
-## How was this tested?
-
-<!--
-Describe verification. The default handoff gate is:
-  bun run typecheck && bun run test:fast && bun run test:env && bun run build && bun run test:smoke:dist
-If docs-site/ changed, also: bun run docs:test && bun run docs:build
--->
-
-## Checklist
-
-- [ ] Reconciled current-outcome changelog fragment(s), or this PR is labeled `skip-changelog` (see [`changes/README.md`](../changes/README.md))
-- [ ] Docs updated in the same PR if behavior, defaults, flags, shortcuts, ports, or APIs changed
-- [ ] Relevant checks pass locally (typecheck, tests, build)

.github/workflows/ci.yml

@@ -8,89 +8,73 @@ on:
 
 jobs:
   build-test-audit:
-    uses: ./.github/workflows/quality-gate.yml
-
-  # Boots the built app with a real mpv on each platform. Kept outside the
-  # reusable quality gate so releases do not depend on it while the lane is new.
-  e2e:
-    name: E2E (${{ matrix.os }})
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 30
-    permissions:
-      contents: read
-    defaults:
-      run:
-        shell: bash
-    env:
-      SUBMINER_E2E_KEEP: '1'
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
         with:
           submodules: true
-          persist-credentials: false
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
           bun-version: 1.3.5
 
-      - name: Point temp files at an uploadable directory
-        run: |
-          # os.tmpdir() follows these, so the kept session logs land under runner.temp.
-          dir="$RUNNER_TEMP/e2e"
-          mkdir -p "$dir"
-          { echo "TMPDIR=$dir"; echo "TEMP=$dir"; echo "TMP=$dir"; } >> "$GITHUB_ENV"
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.12.0
 
-      - name: Install mpv and ffmpeg (Linux)
-        if: runner.os == 'Linux'
-        run: |
-          # Only Ubuntu sources are needed; unrelated runner repositories can be unavailable.
-          apt_sources=(-o Dir::Etc::sourcelist=sources.list.d/ubuntu.sources -o Dir::Etc::sourceparts=-)
-          sudo apt-get "${apt_sources[@]}" update
-          sudo apt-get "${apt_sources[@]}" install -y mpv ffmpeg xvfb
-
-      - name: Install mpv and ffmpeg (macOS)
-        if: runner.os == 'macOS'
-        run: |
-          # Runner images bake in different Homebrew metadata, so without an update the
-          # installed mpv build depends on which image the job lands on.
-          brew update
-          brew install mpv ffmpeg
-          mpv --version
-
-      - name: Install mpv and ffmpeg (Windows)
-        if: runner.os == 'Windows'
-        run: |
-          choco install mpv ffmpeg -y --no-progress
-          # The mpv package adds no shim, so put its directory on PATH for later steps.
-          mpv_exe="$(find /c/ProgramData/chocolatey/lib /c/ProgramData/chocolatey/bin "/c/Program Files" /c/tools -maxdepth 6 -iname mpv.exe 2>/dev/null | head -n 1)"
-          test -n "$mpv_exe"
-          cygpath -w "$(dirname "$mpv_exe")" >> "$GITHUB_PATH"
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
 
       - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
+        run: bun install --frozen-lockfile
 
-      - name: Build
-        run: bun run build
+      - name: Build (TypeScript check)
+        # Keep explicit typecheck for fast fail before full build/bundle.
+        run: bun run typecheck
 
-      - name: End-to-end suite
-        run: bun run test:e2e
+      - name: Test suite (source)
+        run: bun run test:fast
 
-      - name: Dictionary backend windows (Linux)
-        if: runner.os == 'Linux'
-        run: xvfb-run -a bun run test:dictionary:electron
+      - name: Launcher smoke suite (source)
+        run: bun run test:launcher:smoke:src
 
-      - name: Upload session logs (on failure)
+      - name: Upload launcher smoke artifacts (on failure)
         if: failure()
         uses: actions/upload-artifact@v4
         with:
-          name: e2e-logs-${{ matrix.os }}
-          path: ${{ runner.temp }}/e2e/subminer-e2e-*/*.log
+          name: launcher-smoke
+          path: .tmp/launcher-smoke/**
           if-no-files-found: ignore
+
+      - name: Build (bundle)
+        run: bun run build
+
+      - name: Immersion SQLite verification
+        run: bun run test:immersion:sqlite:dist
+
+      - name: Dist smoke suite
+        run: bun run test:smoke:dist
+
+      - name: Security audit
+        run: bun audit --audit-level high
+        continue-on-error: true
+
+      - name: Build Bun subminer wrapper
+        run: make build-launcher
+
+      - name: Verify Bun subminer wrapper
+        run: dist/launcher/subminer --help >/dev/null
+
+      - name: Enforce generated launcher workflow
+        run: bash scripts/verify-generated-launcher.sh

.github/workflows/claude.yml

@@ -0,0 +1,49 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'

.github/workflows/docs-pages.yml

@@ -1,88 +0,0 @@
-name: Docs Pages
-
-on:
-  workflow_dispatch:
-    inputs:
-      rebuild_archives:
-        description: 'Stable tags to rebuild in R2 (comma-separated, or "all"); archives are otherwise built once'
-        required: false
-        default: ''
-  push:
-    branches:
-      - main
-    tags:
-      - 'v*'
-    paths:
-      - 'docs-site/**'
-      - 'scripts/docs-versioning.ts'
-      - 'scripts/docs-versioned-assets.ts'
-      - 'scripts/docs-archive-store.ts'
-      - 'scripts/build-versioned-docs.ts'
-      - '.github/workflows/docs-pages.yml'
-      - 'package.json'
-      - 'bun.lock'
-
-concurrency:
-  group: docs-pages-production
-  cancel-in-progress: false
-
-jobs:
-  deploy:
-    if: ${{ github.ref_type != 'tag' || !contains(github.ref_name, '-') }}
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Guard stable docs tag shape
-        id: tag_guard
-        if: github.ref_type == 'tag'
-        env:
-          TAG_NAME: ${{ github.ref_name }}
-        run: |
-          if [[ ! "$TAG_NAME" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            echo "::notice::Skipping non-stable docs tag $TAG_NAME"
-            echo "stable_tag=false" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-          echo "stable_tag=true" >> "$GITHUB_OUTPUT"
-
-      - name: Setup Bun
-        if: steps.tag_guard.outputs.stable_tag != 'false'
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Install dependencies
-        if: steps.tag_guard.outputs.stable_tag != 'false'
-        run: |
-          bun install --frozen-lockfile
-          cd docs-site && bun install --frozen-lockfile
-
-      - name: Test docs
-        if: steps.tag_guard.outputs.stable_tag != 'false'
-        run: bun run docs:test
-
-      # Builds only archives missing from R2 (plus any requested rebuilds), then the
-      # root and /main/ builds that make up the Pages deployment.
-      - name: Build versioned docs
-        if: steps.tag_guard.outputs.stable_tag != 'false'
-        env:
-          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          DOCS_ARCHIVE_R2_ACCESS_KEY_ID: ${{ secrets.DOCS_ARCHIVE_R2_ACCESS_KEY_ID }}
-          DOCS_ARCHIVE_R2_SECRET_ACCESS_KEY: ${{ secrets.DOCS_ARCHIVE_R2_SECRET_ACCESS_KEY }}
-          DOCS_ARCHIVE_R2_BUCKET: ${{ vars.DOCS_ARCHIVE_R2_BUCKET }}
-          REBUILD_ARCHIVES: ${{ inputs.rebuild_archives }}
-        run: bun run scripts/build-versioned-docs.ts --require-archives "--rebuild-archives=${REBUILD_ARCHIVES}"
-
-      - name: Deploy docs to Cloudflare Pages
-        if: steps.tag_guard.outputs.stable_tag != 'false'
-        uses: cloudflare/wrangler-action@v3
-        with:
-          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          # Run from docs-site so Wrangler bundles docs-site/functions (the /v/* archive server).
-          workingDirectory: docs-site
-          command: pages deploy ../.tmp/docs-versioned-site --project-name "${{ vars.CLOUDFLARE_PAGES_PROJECT_NAME }}" --branch main

.github/workflows/package-release.yml

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

.github/workflows/prerelease.yml

@@ -1,188 +0,0 @@
-name: Prerelease
-
-on:
-  push:
-    tags:
-      - 'v*-beta.*'
-      - 'v*-rc.*'
-
-concurrency:
-  group: prerelease-${{ github.ref }}
-  cancel-in-progress: false
-
-jobs:
-  quality-gate:
-    permissions:
-      contents: read
-    uses: ./.github/workflows/quality-gate.yml
-
-  package:
-    needs: [quality-gate]
-    permissions:
-      contents: read
-    uses: ./.github/workflows/package-release.yml
-    secrets:
-      CSC_LINK: ${{ secrets.CSC_LINK }}
-      CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
-      APPLE_ID: ${{ secrets.APPLE_ID }}
-      APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
-      APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-      SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
-
-  release:
-    needs: [package]
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Download AppImage
-        uses: actions/download-artifact@v4
-        with:
-          name: appimage
-          path: dist/release
-
-      - name: Download macOS artifacts
-        uses: actions/download-artifact@v4
-        with:
-          name: macos
-          path: dist/release
-
-      - name: Download Windows artifacts
-        uses: actions/download-artifact@v4
-        with:
-          name: windows
-          path: dist/release
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-${{ runner.arch }}-bun-
-
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
-
-      - name: Build launcher runtime artifacts
-        run: make build-launcher
-
-      - name: Smoke launcher bundle
-        run: bun dist/launcher/subminer.js --help >/dev/null
-
-      - name: Enforce generated launcher workflow
-        run: bash scripts/verify-generated-launcher.sh
-
-      - name: Verify generated config examples
-        run: bun run verify:config-example
-
-      - name: Package optional assets bundle
-        run: |
-          # Keep the archive layout stable for the AUR PKGBUILD.
-          tar -czf "dist/release/subminer-assets.tar.gz" \
-            --transform 's,^packaging/bun/licenses,resources/bun/licenses,' \
-            config.example.jsonc \
-            plugin/subminer \
-            plugin/subminer.conf \
-            assets/themes/subminer.rasi \
-            assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer \
-            packaging/bun/licenses
-
-      - name: Package Bun corresponding source
-        run: bun scripts/package-bun-source.mjs
-
-      - name: Generate checksums
-        run: |
-          shopt -s nullglob
-          files=(dist/release/*.AppImage dist/release/*.dmg dist/release/*.exe dist/release/*.zip dist/release/*.tar.gz dist/release/latest*.yml dist/release/*.blockmap dist/launcher/subminer dist/launcher/subminer.cmd)
-          if [ "${#files[@]}" -eq 0 ]; then
-            echo "No release artifacts found for checksum generation."
-            exit 1
-          fi
-          : > dist/release/SHA256SUMS.txt
-          for file in "${files[@]}"; do
-            printf '%s  %s\n' \
-              "$(sha256sum "$file" | awk '{print $1}')" \
-              "${file##*/}" >> dist/release/SHA256SUMS.txt
-          done
-
-      - name: Get version from tag
-        id: version
-        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
-
-      - name: Verify committed prerelease notes
-        env:
-          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
-        run: |
-          if [ ! -s packaging/release-notes/prerelease-notes.md ]; then
-            echo "::error::packaging/release-notes/prerelease-notes.md is missing or empty. Run 'bun run changelog:prerelease-notes --version <version>' locally and commit the file before tagging."
-            exit 1
-          fi
-          if ! bun run changelog:check-prerelease-notes --version "$RELEASE_VERSION"; then
-            echo "::error::packaging/release-notes/prerelease-notes.md was not generated for $RELEASE_VERSION. Rerun 'bun run changelog:prerelease-notes --version $RELEASE_VERSION' locally, commit, and retag."
-            exit 1
-          fi
-
-      - name: Publish Prerelease
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
-        run: |
-          set -euo pipefail
-
-          shopt -s nullglob
-          artifacts=(
-            dist/release/*.AppImage
-            dist/release/*.dmg
-            dist/release/*.exe
-            dist/release/*.zip
-            dist/release/*.tar.gz
-            dist/release/*.tar.gz.sha256
-            dist/release/latest*.yml
-            dist/release/*.blockmap
-            dist/release/SHA256SUMS.txt
-            dist/launcher/subminer
-            dist/launcher/subminer.cmd
-          )
-
-          if [ "${#artifacts[@]}" -eq 0 ]; then
-            echo "No release artifacts found for upload."
-            exit 1
-          fi
-
-          if gh release view "$RELEASE_VERSION" >/dev/null 2>&1; then
-            gh release edit "$RELEASE_VERSION" \
-              --draft \
-              --prerelease \
-              --title "$RELEASE_VERSION" \
-              --notes-file packaging/release-notes/prerelease-notes.md
-          else
-            gh release create "$RELEASE_VERSION" \
-              --draft \
-              --latest=false \
-              --prerelease \
-              --title "$RELEASE_VERSION" \
-              --notes-file packaging/release-notes/prerelease-notes.md
-          fi
-
-          for asset in "${artifacts[@]}"; do
-            gh release upload "$RELEASE_VERSION" "$asset" --clobber
-          done
-
-          gh release edit "$RELEASE_VERSION" \
-            --draft=false \
-            --prerelease \
-            --title "$RELEASE_VERSION" \
-            --notes-file packaging/release-notes/prerelease-notes.md

.github/workflows/quality-gate.yml

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

.github/workflows/release.yml

@@ -4,37 +4,216 @@ on:
   push:
     tags:
       - 'v*'
-      - '!v*-beta.*'
-      - '!v*-rc.*'
 
 concurrency:
   group: release-${{ github.ref }}
   cancel-in-progress: false
 
+permissions:
+  contents: write
+
 jobs:
   quality-gate:
-    permissions:
-      contents: read
-    uses: ./.github/workflows/quality-gate.yml
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
 
-  package:
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.12.0
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Test suite (source)
+        run: bun run test:fast
+
+      - name: Launcher smoke suite (source)
+        run: bun run test:launcher:smoke:src
+
+      - name: Upload launcher smoke artifacts (on failure)
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: launcher-smoke
+          path: .tmp/launcher-smoke/**
+          if-no-files-found: ignore
+
+      - name: Build (bundle)
+        run: bun run build
+
+      - name: Immersion SQLite verification
+        run: bun run test:immersion:sqlite:dist
+
+      - name: Dist smoke suite
+        run: bun run test:smoke:dist
+
+  build-linux:
     needs: [quality-gate]
-    permissions:
-      contents: read
-    uses: ./.github/workflows/package-release.yml
-    secrets:
-      CSC_LINK: ${{ secrets.CSC_LINK }}
-      CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
-      APPLE_ID: ${{ secrets.APPLE_ID }}
-      APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
-      APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-      SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.12.0
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            vendor/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build texthooker-ui
+        run: |
+          cd vendor/texthooker-ui
+          bun install
+          bun run build
+
+      - name: Build AppImage
+        run: bun run build:appimage
+        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
+        with:
+          name: appimage
+          path: release/*.AppImage
+
+  build-macos:
+    needs: [quality-gate]
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.12.0
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            vendor/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
+
+      - name: Validate macOS signing/notarization secrets
+        run: |
+          missing=0
+          for name in CSC_LINK CSC_KEY_PASSWORD APPLE_ID APPLE_APP_SPECIFIC_PASSWORD APPLE_TEAM_ID; do
+            if [ -z "${!name}" ]; then
+              echo "Missing required secret: $name"
+              missing=1
+            fi
+          done
+          if [ "$missing" -ne 0 ]; then
+            echo "Set all required macOS signing/notarization secrets and rerun."
+            exit 1
+          fi
+        env:
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build texthooker-ui
+        run: |
+          cd vendor/texthooker-ui
+          bun install
+          bun run build
+
+      - name: Build signed + notarized macOS artifacts
+        run: bun run build:mac
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Upload macOS artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos
+          path: |
+            release/*.dmg
+            release/*.zip
 
   release:
-    needs: [package]
+    needs: [build-linux, build-macos]
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -45,19 +224,13 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           name: appimage
-          path: dist/release
+          path: release
 
       - name: Download macOS artifacts
         uses: actions/download-artifact@v4
         with:
           name: macos
-          path: dist/release
-
-      - name: Download Windows artifacts
-        uses: actions/download-artifact@v4
-        with:
-          name: windows
-          path: dist/release
+          path: release
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
@@ -77,103 +250,112 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
-      - name: Build launcher runtime artifacts
+      - name: Build Bun subminer wrapper
         run: make build-launcher
 
-      - name: Smoke launcher bundle
-        run: bun dist/launcher/subminer.js --help >/dev/null
+      - name: Verify Bun subminer wrapper
+        run: dist/launcher/subminer --help >/dev/null
 
       - name: Enforce generated launcher workflow
         run: bash scripts/verify-generated-launcher.sh
 
-      - name: Verify generated config examples
-        run: bun run verify:config-example
-
       - name: Package optional assets bundle
         run: |
-          # Keep the archive layout stable for the AUR PKGBUILD.
-          tar -czf "dist/release/subminer-assets.tar.gz" \
-            --transform 's,^packaging/bun/licenses,resources/bun/licenses,' \
+          tar -czf "release/subminer-assets.tar.gz" \
             config.example.jsonc \
             plugin/subminer \
             plugin/subminer.conf \
-            assets/themes/subminer.rasi \
-            assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer \
-            packaging/bun/licenses
-
-      - name: Package Bun corresponding source
-        run: bun scripts/package-bun-source.mjs
+            assets/themes/subminer.rasi
 
       - name: Generate checksums
         run: |
           shopt -s nullglob
-          files=(dist/release/*.AppImage dist/release/*.dmg dist/release/*.exe dist/release/*.zip dist/release/*.tar.gz dist/release/latest*.yml dist/release/*.blockmap dist/launcher/subminer dist/launcher/subminer.cmd)
+          files=(release/*.AppImage release/*.dmg release/*.zip release/*.tar.gz dist/launcher/subminer)
           if [ "${#files[@]}" -eq 0 ]; then
             echo "No release artifacts found for checksum generation."
             exit 1
           fi
-          : > dist/release/SHA256SUMS.txt
-          for file in "${files[@]}"; do
-            printf '%s  %s\n' \
-              "$(sha256sum "$file" | awk '{print $1}')" \
-              "${file##*/}" >> dist/release/SHA256SUMS.txt
-          done
+          sha256sum "${files[@]}" > release/SHA256SUMS.txt
 
       - 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: Guard against pending changelog fragments
-        env:
-          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
+      - name: Generate changelog
+        id: changelog
         run: |
-          if find changes -maxdepth 1 -name '*.md' -not -name README.md -print -quit | grep -q .; then
-            echo "::error::Pending changelog fragments detected. Run 'bun run changelog:build --version $RELEASE_VERSION' locally and commit the polished CHANGELOG.md before tagging. CI no longer auto-builds the changelog because the polish step requires the local 'claude' CLI."
-            exit 1
+          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+          if [ -n "$PREV_TAG" ]; then
+            CHANGES=$(git log --pretty=format:"- %s" ${PREV_TAG}..HEAD)
+          else
+            COMMIT_COUNT=$(git rev-list --count HEAD)
+            if [ "$COMMIT_COUNT" -gt 10 ]; then
+              CHANGES=$(git log --pretty=format:"- %s" HEAD~10..HEAD)
+            else
+              CHANGES=$(git log --pretty=format:"- %s")
+            fi
           fi
-
-      - name: Verify changelog is ready for tagged release
-        env:
-          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
-        run: bun run changelog:check --version "$RELEASE_VERSION"
-
-      - name: Generate release notes from changelog
-        env:
-          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
-        run: bun run changelog:release-notes --version "$RELEASE_VERSION"
+          echo "CHANGES<<EOF" >> $GITHUB_OUTPUT
+          echo "$CHANGES" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
 
       - name: Publish Release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
           set -euo pipefail
 
-          if gh release view "$RELEASE_VERSION" >/dev/null 2>&1; then
-            # Do not pass the prerelease flag here; gh defaults to a normal release.
-            gh release edit "$RELEASE_VERSION" \
-              --draft=false \
-              --title "$RELEASE_VERSION" \
-              --notes-file packaging/release-notes/release-notes.md
+          cat > release-body.md <<'EOF'
+          ## Changes
+          ${{ steps.changelog.outputs.CHANGES }}
+
+          ## Installation
+
+          ### AppImage (Recommended)
+          1. Download the AppImage below
+          2. Make it executable: `chmod +x SubMiner.AppImage`
+          3. Run: `./SubMiner.AppImage`
+
+          ### macOS
+          1. Download `subminer-*.dmg`
+          2. Open the DMG and drag `SubMiner.app` into `/Applications`
+          3. If needed, use the ZIP artifact as an alternative
+
+          ### Manual Installation
+          See the [README](https://github.com/${{ github.repository }}#installation) for manual installation instructions.
+
+          ### Optional Assets (config example + mpv plugin + rofi theme)
+          1. Download `subminer-assets.tar.gz`
+          2. Extract and copy `config.example.jsonc` to `~/.config/SubMiner/config.jsonc`
+          3. Copy `plugin/subminer/` directory contents to `~/.config/mpv/scripts/`
+          4. Copy `plugin/subminer.conf` to `~/.config/mpv/script-opts/`
+          5. Copy `assets/themes/subminer.rasi` to:
+             - Linux: `~/.local/share/SubMiner/themes/subminer.rasi`
+             - macOS: `~/Library/Application Support/SubMiner/themes/subminer.rasi`
+
+          Note: the `subminer` wrapper script uses Bun (`#!/usr/bin/env bun`), so `bun` must be installed and on `PATH`.
+          EOF
+
+          if gh release view "${{ steps.version.outputs.VERSION }}" >/dev/null 2>&1; then
+            gh release edit "${{ steps.version.outputs.VERSION }}" \
+              --title "${{ steps.version.outputs.VERSION }}" \
+              --notes-file release-body.md \
+              --prerelease false
           else
-            gh release create "$RELEASE_VERSION" \
-              --title "$RELEASE_VERSION" \
-              --notes-file packaging/release-notes/release-notes.md
+            gh release create "${{ steps.version.outputs.VERSION }}" \
+              --title "${{ steps.version.outputs.VERSION }}" \
+              --notes-file release-body.md \
+              --prerelease false
           fi
 
           shopt -s nullglob
           artifacts=(
-            dist/release/*.AppImage
-            dist/release/*.dmg
-            dist/release/*.exe
-            dist/release/*.zip
-            dist/release/*.tar.gz
-            dist/release/*.tar.gz.sha256
-            dist/release/latest*.yml
-            dist/release/*.blockmap
-            dist/release/SHA256SUMS.txt
+            release/*.AppImage
+            release/*.dmg
+            release/*.zip
+            release/*.tar.gz
+            release/SHA256SUMS.txt
             dist/launcher/subminer
-            dist/launcher/subminer.cmd
           )
 
           if [ "${#artifacts[@]}" -eq 0 ]; then
@@ -182,145 +364,5 @@ jobs:
           fi
 
           for asset in "${artifacts[@]}"; do
-            gh release upload "$RELEASE_VERSION" "$asset" --clobber
+            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
-        id: aur_assets
-        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
-        env:
-          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
-        run: |
-          set -euo pipefail
-          version="$RELEASE_VERSION"
-          install -dm755 .tmp/aur-release-assets
-          for asset in "SubMiner-${version#v}.AppImage" subminer subminer-assets.tar.gz; do
-            destination=".tmp/aur-release-assets/$asset"
-            if ! curl --fail --silent --show-error --location \
-              --retry 3 --retry-delay 1 --retry-all-errors \
-              --connect-timeout 30 --max-time 600 \
-              --output "$destination.partial" \
-              "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/releases/download/$version/$asset"; then
-              echo "::warning::Unable to download $asset after retries; skipping automated AUR publish."
-              echo "skip=true" >> "$GITHUB_OUTPUT"
-              exit 0
-            fi
-            mv "$destination.partial" "$destination"
-          done
-          echo "skip=false" >> "$GITHUB_OUTPUT"
-
-      - name: Update AUR packaging metadata
-        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true' && steps.aur_assets.outputs.skip != 'true'
-        env:
-          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
-        run: |
-          set -euo pipefail
-          version_no_v="$RELEASE_VERSION"
-          version_no_v="${version_no_v#v}"
-          cp packaging/aur/subminer-bin/PKGBUILD aur-subminer-bin/PKGBUILD
-          cp packaging/aur/subminer-bin/.SRCINFO aur-subminer-bin/.SRCINFO
-          bash scripts/update-aur-package.sh \
-            --pkg-dir aur-subminer-bin \
-            --version "$RELEASE_VERSION" \
-            --appimage ".tmp/aur-release-assets/SubMiner-${version_no_v}.AppImage" \
-            --wrapper ".tmp/aur-release-assets/subminer" \
-            --assets ".tmp/aur-release-assets/subminer-assets.tar.gz"
-
-      - name: Commit and push AUR update
-        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true' && steps.aur_assets.outputs.skip != 'true'
-        working-directory: aur-subminer-bin
-        env:
-          GIT_SSH_COMMAND: ssh -i ~/.ssh/aur -o IdentitiesOnly=yes
-          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
-        run: |
-          set -euo pipefail
-          if git diff --quiet -- PKGBUILD .SRCINFO; then
-            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 $RELEASE_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,19 +1,14 @@
 # Dependencies
 node_modules/
-/package-lock.json
-
-# Superpowers brainstorming
-.superpowers/
 
 # Electron build output
 out/
 dist/
-coverage/
+release/
+build/yomitan/
 
 # Launcher build artifact (produced by make build-launcher)
 /subminer
-/main-entry.js
-/main-entry.js.map
 
 # Logs
 *.log
@@ -27,7 +22,9 @@ Thumbs.db
 .idea/
 *.swp
 *.swo
+**/CLAUDE.md
 environment.toml
+**/CLAUDE.md
 .env
 .vscode/*
 
@@ -36,30 +33,7 @@ environment.toml
 .vitepress/dist/
 docs/.vitepress/cache/
 docs/.vitepress/dist/
-# Local test media and scripts
 tests/*
 .worktrees/
-.tmp/
 .codex/*
 .agents/*
-!.agents/skills/
-.agents/skills/*
-!.agents/skills/subminer-change-verification/
-!.agents/skills/subminer-release/
-!.agents/skills/subminer-scrum-master/
-.agents/skills/subminer-change-verification/*
-!.agents/skills/subminer-change-verification/SKILL.md
-!.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-release/*
-!.agents/skills/subminer-release/SKILL.md
-.agents/skills/subminer-scrum-master/*
-!.agents/skills/subminer-scrum-master/SKILL.md
-favicon.png
-.claude/*
-!stats/public/favicon.png
-
-# Browser-automation session artifacts (page snapshots, console logs, downloads)
-.playwright-mcp/

.gitmodules

@@ -5,10 +5,9 @@
 [submodule "vendor/yomitan-jlpt-vocab"]
 	path = vendor/yomitan-jlpt-vocab
 	url = https://github.com/stephenmk/yomitan-jlpt-vocab
+[submodule "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
-[submodule "vendor/hachidori"]
-	path = vendor/hachidori
-	url = https://github.com/ksyasuda/hachidori.git
-	branch = subminer

.prettierignore

@@ -1,9 +1,6 @@
 node_modules
 dist
+release
 coverage
 vendor
 *.log
-src/core/services/tokenizer/__fixtures__/golden/*.json
-# Reviewed release text and vendored license texts; never reformat
-packaging/release-notes
-packaging/bun/licenses

.prettierrc.json

@@ -0,0 +1,5 @@
+{
+  "printWidth": 100,
+  "singleQuote": true,
+  "trailingComma": "all"
+}

AGENTS.md

@@ -1,85 +1,29 @@
-# AGENTS.md
 
-## Internal Docs
+<!-- BACKLOG.MD MCP GUIDELINES START -->
 
-Start here, then leave this file.
+<CRITICAL_INSTRUCTION>
 
-- 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)
-- Testing guidelines: [`docs/workflow/testing.md`](./docs/workflow/testing.md)
-- Knowledge-base rules: [`docs/knowledge-base/README.md`](./docs/knowledge-base/README.md)
-- Release guide: [`docs/RELEASING.md`](./docs/RELEASING.md)
+## BACKLOG WORKFLOW INSTRUCTIONS
 
-`docs-site/` is user-facing. Do not treat it as the canonical internal source of truth.
+This project uses Backlog.md MCP for all task and project management activities.
 
-`CLAUDE.md` is a symlink to this file; there is one project instruction file, not two.
+**CRITICAL GUIDANCE**
 
-## Quick Start
+- If your client supports MCP resources, read `backlog://workflow/overview` to understand when and how to use Backlog for this project.
+- If your client only supports tools or the above request fails, call `backlog.get_workflow_overview()` tool to load the tool-oriented overview (it lists the matching guide tools).
 
-- Init workspace: `git submodule update --init --recursive`
-- Install deps: `make deps` or `bun install` plus `(cd vendor/texthooker-ui && bun install --frozen-lockfile)`
-- Fast dev loop: `make dev-watch`
-- Full local run: `bun run dev`
-- Verbose Electron debug: `electron . --start --dev --log-level debug`
+- **First time working here?** Read the overview resource IMMEDIATELY to learn the workflow
+- **Already familiar?** You should have the overview cached ("## Backlog.md Overview (MCP)")
+- **When to read it**: BEFORE creating tasks, or when you're unsure whether to track work
 
-## Build / Test
+These guides cover:
+- Decision framework for when to create tasks
+- Search-first workflow to avoid duplicates
+- Links to detailed guides for task creation, execution, and finalization
+- MCP tools reference
 
-- Runtime/package manager: Bun; use the version pinned by `package.json`.
-- Follow [`docs/workflow/verification.md`](./docs/workflow/verification.md) and start with the cheapest sufficient lane.
-- Full handoff gate for substantial changes:
-  `bun run typecheck`
-  `bun run test:fast`
-  `bun run test:env`
-  `bun run build`
-  `bun run test:smoke:dist`
-- If `docs-site/` changed, also run:
-  `bun run docs:test`
-  `bun run docs:build`
-- Prefer `make pretty` and `bun run format:check:src`
+You MUST read the overview resource to understand the complete workflow. The information is NOT summarized here.
 
-## Change-Specific Checks
+</CRITICAL_INSTRUCTION>
 
-- Config/schema/defaults: `bun run test:config`; if template/defaults changed, `bun run generate:config-example`
-- Launcher/plugin: `bun run test:launcher` or `bun run test:env`
-- Runtime-compat / dist-sensitive: `bun run test:runtime:compat`
-- Stats dashboard UI (`stats/`): `bun run test:stats`
-- Overlay / renderer / mpv / mining behavior in the running app: `bun run build`, then `bun run test:e2e` (headless, sandboxed; `bun run e2e start` for exploratory checks)
-- Build/release scripts (`scripts/**`): `bun run test:scripts`
-- Internal docs, `AGENTS.md`, or repo skills: `bun run test:docs:kb`
-- User-facing `docs-site/`: `bun run docs:test`, then `bun run docs:build`
-- macOS Swift helpers (`scripts/get-mpv-window-macos.swift`, `scripts/macos-controller-watch.swift`): compile them on macOS with `bun run build`
-- Test lanes are directory-discovered via `scripts/test-lanes.ts`; never hand-list test files in `package.json`
-
-## Docs Upkeep
-
-- Docs ship with the change, not after. If a change alters behavior, defaults, flags, shortcuts, ports, or APIs, update the matching docs in the same PR. Touching code without reconciling its docs is an incomplete change.
-- Source of truth for config defaults is the generated `config.example.jsonc`. Never write a default value into prose you didn't read from it, and don't restate the same default across multiple docs; cite/link to one place so there's a single thing to update.
-- Trigger map (touch left → update right):
-  - `src/config/definitions/**` (schema/defaults/template) → `bun run generate:config-example`, then reconcile `docs-site/configuration.md` + any feature doc that cites that default
-  - shortcuts/keybindings (`shortcuts.*`, `keybindings`, `stats.*Key`, `subtitleSidebar.toggleKey`, controller bindings) → `docs-site/shortcuts.md`
-  - CLI flags/subcommands (`src/cli/args.ts`, `launcher/**`) → `docs-site/usage.md` + relevant integration doc
-  - feature behavior (anki / jellyfin / jimaku / anilist / youtube / immersion / stats / websocket / sidebar / character-dictionary / annotations) → matching `docs-site/<feature>.md`
-  - architecture / IPC / workflow / internal process → internal `docs/` (system of record)
-  - feature set / requirements / install flow → `README.md`
-- Removing or renaming a config key: grep `docs-site/` and `docs/` for the old key and any value it documented; legacy/hidden keys (`LEGACY_HIDDEN_CONFIG_PATHS`) should not appear in user docs as current settings.
-- Verify after doc edits: `bun run verify:config-example` (if config touched), `bun run docs:test`, `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 reconciled current-outcome fragment(s) in `changes/*.md`. Format and rules live in [`changes/README.md`](./changes/README.md) (`type` + `area` keys required; inspect existing same-PR fragments, then update/remove stale bullets or add only genuinely separate outcomes; apply the `skip-changelog` label to opt out).
-- User-visible docs changes get a `type: docs` fragment
-- CI enforces `bun run changelog:lint` and `bun run changelog:pr-check`
-- PR review helpers:
-  - `gh pr view --json number,title --jq '"PR #\\(.number): \\(.title)"'`
-  - `gh api repos/:owner/:repo/pulls/<num>/comments --paginate`
-- For CI debugging, inspect runs with `gh run list/view`; rerun or fix only within the requested scope.
+<!-- BACKLOG.MD MCP GUIDELINES END -->

Makefile

@@ -1,11 +1,10 @@
-.PHONY: help submodules deps build build-launcher install build-linux build-macos build-macos-unsigned clean install-linux install-macos install-windows uninstall uninstall-linux uninstall-macos uninstall-windows print-dirs pretty lint ensure-bun generate-config generate-example-config dev-start dev-start-macos dev-watch dev-watch-macos dev-toggle dev-stop docs-test docs-build docs-build-versioned docs-dev
+.PHONY: help deps build build-launcher install build-linux build-macos build-macos-unsigned clean install-linux install-macos install-plugin uninstall uninstall-linux uninstall-macos print-dirs pretty ensure-bun generate-config generate-example-config dev-start dev-start-macos dev-watch dev-watch-macos dev-toggle dev-stop
 
 APP_NAME := subminer
 THEME_SOURCE := assets/themes/subminer.rasi
-THUMBNAILER_SOURCE := assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer
 LAUNCHER_OUT := dist/launcher/$(APP_NAME)
 THEME_FILE := subminer.rasi
-THUMBNAILER_FILE := subminer-ffmpegthumbnailer.thumbnailer
+PLUGIN_CONF := plugin/subminer.conf
 
 # Default install prefix for the wrapper script.
 PREFIX ?= $(HOME)/.local
@@ -21,10 +20,15 @@ MACOS_DATA_DIR ?= $(HOME)/Library/Application Support/SubMiner
 MACOS_APP_DIR ?= $(HOME)/Applications
 MACOS_APP_DEST ?= $(MACOS_APP_DIR)/SubMiner.app
 
-# If building from source, the AppImage will typically land in dist/release/.
-APPIMAGE_SRC = $(firstword $(wildcard dist/release/SubMiner-*.AppImage))
-MACOS_APP_SRC = $(firstword $(wildcard dist/release/*.app dist/release/*/*.app))
-MACOS_ZIP_SRC = $(firstword $(wildcard dist/release/SubMiner-*.zip))
+# 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))
+MACOS_ZIP_SRC := $(firstword $(wildcard release/SubMiner-*.zip))
 
 UNAME_S := $(shell uname -s 2>/dev/null || echo Unknown)
 ifeq ($(OS),Windows_NT)
@@ -37,17 +41,6 @@ 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:" \
@@ -56,30 +49,23 @@ help:
 		"  build-linux      Build Linux AppImage" \
 		"  build-macos      Build macOS DMG/ZIP (signed if configured)" \
 		"  build-macos-unsigned Build macOS DMG/ZIP without signing/notarization" \
-		"  clean            Remove build artifacts (dist/, AppImage, binary)" \
+		"  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-test        Run docs tests" \
-		"  docs-build       Build the docs site" \
-		"  docs-build-versioned Build production versioned docs site" \
-		"  docs-dev         Start the docs dev server" \
 		"  install-linux    Install Linux wrapper/theme/app artifacts" \
 		"  install-macos    Install macOS wrapper/theme/app artifacts" \
-		"  install-windows  Print Windows packaging/install guidance" \
+		"  install-plugin   Install mpv Lua plugin and plugin config" \
 		"  generate-config  Generate ~/.config/SubMiner/config.jsonc from centralized defaults" \
 		"" \
 		"Other targets:" \
-		"  submodules       Initialize/update git submodules" \
-		"  deps             Initialize submodules and install JS dependencies (root + stats + texthooker-ui)" \
+		"  deps             Install JS dependencies (root + 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)" \
@@ -88,7 +74,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 or %APPDATA%/mpv on Windows)"
+		"  MPV_CONFIG_DIR=... Override mpv config dir (default: $$HOME/.config/mpv)"
 
 print-dirs:
 	@printf '%s\n' \
@@ -99,38 +85,26 @@ 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)"
 
-submodules:
-	@git submodule update --init --recursive
-
-deps: submodules ensure-bun
+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:src
-	@bun run format:stats
-
-lint: ensure-bun
-	@bun run lint:stats
+	@bun run format
 
 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
 
@@ -139,7 +113,6 @@ 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
 
@@ -159,12 +132,18 @@ build-macos-unsigned: deps
 	@bun run build:mac:unsigned
 
 build-launcher:
-	@printf '%s\n' "[INFO] Building launcher runtime artifacts"
-	@bun run build:launcher
+	@printf '%s\n' "[INFO] Bundling launcher script"
+	@install -d "$(dir $(LAUNCHER_OUT))"
+	@bun build ./launcher/main.ts --target=bun --packages=bundle --outfile="$(LAUNCHER_OUT)"
+	@if ! head -1 "$(LAUNCHER_OUT)" | grep -q '^#!/usr/bin/env bun'; then \
+		{ printf '#!/usr/bin/env bun\n'; cat "$(LAUNCHER_OUT)"; } > "$(LAUNCHER_OUT).tmp" && mv "$(LAUNCHER_OUT).tmp" "$(LAUNCHER_OUT)"; \
+	fi
+	@chmod +x "$(LAUNCHER_OUT)"
+	@printf '%s\n' "[INFO] Launcher artifact: $(LAUNCHER_OUT)"
 
 clean:
 	@printf '%s\n' "[INFO] Removing build artifacts"
-	@rm -rf dist
+	@rm -rf dist release
 	@rm -f "$(BINDIR)/subminer" "$(BINDIR)/SubMiner.AppImage"
 
 generate-config: ensure-bun
@@ -172,6 +151,7 @@ generate-config: ensure-bun
 	@bun run electron . --generate-config
 
 generate-example-config: ensure-bun
+	@bun run build
 	@bun run generate:config-example
 
 dev-start: ensure-bun
@@ -194,36 +174,20 @@ dev-toggle: ensure-bun
 dev-stop: ensure-bun
 	@bun run electron . --stop
 
-docs-test: ensure-bun
-	@bun run docs:test
-
-docs-build: ensure-bun
-	@bun run docs:build
-
-docs-build-versioned: ensure-bun
-	@bun run docs:build:versioned
-
-docs-dev: ensure-bun
-	@bun run docs:dev
-
 
 install-linux: build-launcher
-	@printf '%s\n' "[INFO] Installing Linux wrapper/support artifacts"
+	@printf '%s\n' "[INFO] Installing Linux wrapper/theme artifacts"
 	@install -d "$(BINDIR)"
 	@install -m 0755 "$(LAUNCHER_OUT)" "$(BINDIR)/$(APP_NAME)"
 	@install -d "$(LINUX_DATA_DIR)/themes"
 	@install -m 0644 "./$(THEME_SOURCE)" "$(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
-	@install -d "$(LINUX_DATA_DIR)/thumbnailers"
-	@install -m 0644 "./$(THUMBNAILER_SOURCE)" "$(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
-	@install -d "$(LINUX_DATA_DIR)/plugin/subminer"
-	@cp -R ./plugin/subminer/. "$(LINUX_DATA_DIR)/plugin/subminer/"
 	@if [ -n "$(APPIMAGE_SRC)" ]; then \
 		install -m 0755 "$(APPIMAGE_SRC)" "$(BINDIR)/SubMiner.AppImage"; \
 	else \
-		printf '%s\n' "[WARN] No dist/release/SubMiner-*.AppImage found; skipping AppImage install"; \
+		printf '%s\n' "[WARN] No release/SubMiner-*.AppImage found; skipping AppImage install"; \
 		printf '%s\n' "       Build one with: make build"; \
 	fi
-	@printf '%s\n' "Installed to:" "  $(BINDIR)/subminer" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)" "  $(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
+	@printf '%s\n' "Installed to:" "  $(BINDIR)/subminer" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
 
 install-macos: build-launcher
 	@printf '%s\n' "[INFO] Installing macOS wrapper/theme/app artifacts"
@@ -231,8 +195,6 @@ install-macos: build-launcher
 	@install -m 0755 "$(LAUNCHER_OUT)" "$(BINDIR)/$(APP_NAME)"
 	@install -d "$(MACOS_DATA_DIR)/themes"
 	@install -m 0644 "./$(THEME_SOURCE)" "$(MACOS_DATA_DIR)/themes/$(THEME_FILE)"
-	@install -d "$(MACOS_DATA_DIR)/plugin/subminer"
-	@cp -R ./plugin/subminer/. "$(MACOS_DATA_DIR)/plugin/subminer/"
 	@install -d "$(MACOS_APP_DIR)"
 	@if [ -n "$(MACOS_APP_SRC)" ]; then \
 		rm -rf "$(MACOS_APP_DEST)"; \
@@ -243,39 +205,31 @@ install-macos: build-launcher
 		ditto -x -k "$(MACOS_ZIP_SRC)" "$(MACOS_APP_DIR)"; \
 		printf '%s\n' "[INFO] Installed app bundle from $(MACOS_ZIP_SRC)"; \
 	else \
-		printf '%s\n' "[WARN] No macOS app bundle or zip found in dist/release/; skipping app install"; \
+		printf '%s\n' "[WARN] No macOS app bundle or zip found in release/; skipping app install"; \
 		printf '%s\n' "       Build one with: make build"; \
 	fi
 	@printf '%s\n' "Installed to:" "  $(BINDIR)/subminer" "  $(MACOS_DATA_DIR)/themes/$(THEME_FILE)" "  $(MACOS_APP_DEST)"
 
-install-windows:
-	@printf '%s\n' "[INFO] Windows builds run via: bun run build:win"
-	@printf '%s\n' "[INFO] SubMiner-managed mpv launches inject the bundled runtime plugin; no global mpv plugin install is needed."
+install-plugin:
+	@printf '%s\n' "[INFO] Installing mpv plugin artifacts"
+	@install -d "$(MPV_SCRIPTS_DIR)"
+	@rm -f "$(MPV_SCRIPTS_DIR)/subminer.lua"
+	@install -d "$(MPV_SCRIPTS_DIR)/subminer"
+	@install -d "$(MPV_SCRIPT_OPTS_DIR)"
+	@cp -R ./plugin/subminer/. "$(MPV_SCRIPTS_DIR)/subminer/"
+	@install -m 0644 "./$(PLUGIN_CONF)" "$(MPV_SCRIPT_OPTS_DIR)/subminer.conf"
+	@printf '%s\n' "Installed to:" "  $(MPV_SCRIPTS_DIR)/subminer/main.lua" "  $(MPV_SCRIPTS_DIR)/subminer/" "  $(MPV_SCRIPT_OPTS_DIR)/subminer.conf"
 
-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 behavior kept unchanged by default.
+uninstall: uninstall-linux
 
 uninstall-linux:
 	@rm -f "$(BINDIR)/subminer" "$(BINDIR)/SubMiner.AppImage"
 	@rm -f "$(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
-	@rm -f "$(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
-	@rm -rf "$(LINUX_DATA_DIR)/plugin/subminer"
-	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(BINDIR)/SubMiner.AppImage" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)" "  $(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)" "  $(LINUX_DATA_DIR)/plugin/subminer"
+	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(BINDIR)/SubMiner.AppImage" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
 
 uninstall-macos:
 	@rm -f "$(BINDIR)/subminer"
 	@rm -f "$(MACOS_DATA_DIR)/themes/$(THEME_FILE)"
-	@rm -rf "$(MACOS_DATA_DIR)/plugin/subminer"
 	@rm -rf "$(MACOS_APP_DEST)"
-	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(MACOS_DATA_DIR)/themes/$(THEME_FILE)" "  $(MACOS_DATA_DIR)/plugin/subminer" "  $(MACOS_APP_DEST)"
-
-uninstall-windows:
-	@rm -rf "$(MPV_SCRIPTS_DIR)/subminer"
-	@rm -f "$(MPV_SCRIPTS_DIR)/subminer.lua" "$(MPV_SCRIPTS_DIR)/subminer-loader.lua" "$(MPV_SCRIPT_OPTS_DIR)/subminer.conf"
-	@printf '%s\n' "Removed:" "  $(MPV_SCRIPTS_DIR)/subminer" "  $(MPV_SCRIPT_OPTS_DIR)/subminer.conf"
+	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(MACOS_DATA_DIR)/themes/$(THEME_FILE)" "  $(MACOS_APP_DEST)"

README.md

@@ -1,282 +1,123 @@
 <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 />
 
-<img src="assets/SubMiner.png" width="160" alt="SubMiner logo">
-
-# SubMiner
-
-Look up words with Yomitan or Hachidori, mine them to Anki, and track your immersion without leaving mpv
-
-[Installation](#quick-start) · [Requirements](#requirements) · [Usage](https://docs.subminer.moe/usage) · [Documentation](https://docs.subminer.moe)
-
-[![Downloads](https://img.shields.io/github/downloads/ksyasuda/SubMiner/total?style=flat-square&color=1a1a2e)](https://github.com/ksyasuda/SubMiner/releases)
-[![Release](https://img.shields.io/github/v/release/ksyasuda/SubMiner?style=flat-square&color=1a1a2e)](https://github.com/ksyasuda/SubMiner/releases/latest)
-[![AUR](https://img.shields.io/aur/version/subminer-bin?style=flat-square&color=1a1a2e)](https://aur.archlinux.org/packages/subminer-bin)
-[![Platform](https://img.shields.io/badge/platform-Linux%20·%20macOS%20·%20Windows-1a1a2e?style=flat-square)](https://github.com/ksyasuda/SubMiner)
-[![License](https://img.shields.io/github/license/ksyasuda/SubMiner?style=flat-square&color=1a1a2e)](https://www.gnu.org/licenses/gpl-3.0)
-[![TypeScript](https://img.shields.io/badge/TypeScript-1a1a2e?style=flat-square&logo=typescript&logoColor=3178c6)](https://www.typescriptlang.org)
-
-[![SubMiner demo](./assets/minecard.webp)](https://github.com/user-attachments/assets/7abab8a9-4e4e-4f06-9f3c-9783e15a3807)
+[![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)
 
 </div>
 
-## Features
-
-### Dictionary Lookups
-
-Hover over any word in the subtitles to open the full Yomitan popup with definitions, pitch accent, and frequency data. SubMiner bundles its own Yomitan, separate from any browser install.
-
-Yomitan remains the default. Select the bundled [Hachidori](https://github.com/bee-san/hachidori) backend with `dictionaryBackend: "hachidori"` and restart SubMiner. The tray opens the selected backend's settings. See [dictionary setup](https://docs.subminer.moe/usage#hachidori-setup) for importing dictionaries, linking an external Hachidori host, and configuring Anki.
+<br />
 
 <div align="center">
-  <img src="docs-site/public/screenshots/yomitan-lookup.png" width="800" alt="Yomitan dictionary popup over annotated subtitles in mpv">
+
+[![SubMiner demo (Animated preview)](./assets/minecard.webp)](./assets/minecard.mp4)
+
 </div>
 
-<br>
+<br />
 
-### Instant Anki Mining
+## What it does
 
-Create an Anki card from the exact playback moment with one key press, click, or controller input. SubMiner fills in the sentence, an audio clip, and a screenshot or animated image.
+SubMiner is an Electron overlay that sits on top of mpv. It turns your video player into a full sentence-mining workstation:
 
-<div align="center">
-  <img src="docs-site/public/screenshots/one-key-mining.png" width="800" alt="Yomitan lookup over an anime scene with Anki mining controls">
-</div>
+- **Hover to look up** — Yomitan dictionary popups directly on subtitles
+- **Keyboard-driven lookup mode** — Navigate token-by-token, keep lookup open across tokens, and control popup scrolling/audio/mining without leaving the overlay
+- **One-key mining** — Creates Anki cards with sentence, audio, screenshot, and translation
+- **Instant auto-enrichment** — Optional local AnkiConnect proxy enriches new Yomitan cards immediately
+- **Reading annotations** — Combines N+1 targeting, frequency-dictionary highlighting, and JLPT underlining while you read
+- **Hover-aware playback** — By default, hovering subtitle text pauses mpv and resumes on mouse leave (`subtitleStyle.autoPauseVideoOnHover`)
+- **Subtitle tools** — Download from Jimaku, sync with alass/ffsubsync
+- **Immersion tracking** — SQLite-powered stats on your watch time and mining activity
+- **Custom texthooker page** — Built-in custom texthooker page and websocket, no extra setup
+- **Annotated websocket API** — Dedicated annotation feed can serve bundled texthooker or external clients with rendered `sentence` HTML plus structured `tokens`
+- **Jellyfin integration** — Remote playback setup, cast device mode, and direct playback launch
+- **AniList progress** — Track episode completion and push watching progress automatically
 
-<br>
+## Quick start
 
-### Reading Annotations
+### 1. Install
 
-Subtitles are annotated as they play with frequency highlighting, JLPT tags, N+1 targeting, and character names from a generated dictionary. Particles and grammar-only tokens stay plain so the words worth learning stand out.
+**Linux (AppImage):**
 
-<div align="center">
-  <img src="docs-site/public/screenshots/annotations.png" width="800" alt="Annotated subtitles with frequency colors, character portraits, and JLPT underlines">
-</div>
+```bash
+wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppImage -O ~/.local/bin/SubMiner.AppImage
+chmod +x ~/.local/bin/SubMiner.AppImage
+wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer
+chmod +x ~/.local/bin/subminer
 
-<br>
+```
 
-### Immersion Dashboard
+> [!NOTE]
+> The `subminer` wrapper uses a [Bun](https://bun.sh) shebang. Make sure `bun` is on your `PATH`.
 
-A stats dashboard tracks watch time, vocabulary growth, mining throughput, session history, and trends. Everything stays on your machine, with no third-party tracking.
+**From source** or **macOS** — initialize submodules first (`git submodule update --init --recursive`). Source builds now also require Node.js 22 + npm because bundled Yomitan is built from the `vendor/subminer-yomitan` submodule into `build/yomitan` during `bun run build`. Full install guide: [docs.subminer.moe/installation#from-source](https://docs.subminer.moe/installation#from-source).
 
-<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>
+### 2. Launch the app once
 
-<br>
+```bash
+SubMiner.AppImage
+```
 
-### Integrations
+On first launch, SubMiner now:
 
-<table>
-  <tr>
-    <td><b>YouTube</b></td>
-    <td>Play YouTube URLs with subtitle tracks picked by your language priorities, or choose tracks yourself in the overlay picker (<code>Ctrl+Alt+C</code>). Requires <code>yt-dlp</code></td>
-  </tr>
-  <tr>
-    <td><b>AniList</b></td>
-    <td>Automatic episode tracking and progress sync</td>
-  </tr>
-  <tr>
-    <td><b>Jellyfin</b></td>
-    <td>Browse your Jellyfin library, or cast to SubMiner from any Jellyfin client. Setup and discovery live in the tray menu</td>
-  </tr>
-  <tr>
-    <td><b>Jimaku</b></td>
-    <td>Search and download Japanese subtitles. Requires a free Jimaku API key</td>
-  </tr>
-  <tr>
-    <td><b>TsukiHime</b></td>
-    <td>Search and download subtitles extracted from anime releases, with Japanese and secondary-language tabs (<code>Ctrl+Shift+T</code>). Requires <code>xz</code> on your <code>PATH</code></td>
-  </tr>
-  <tr>
-    <td><b>Subtitle generation</b></td>
-    <td>Transcribe a video's audio into Japanese subtitles locally from the generation modal (<code>Ctrl+Shift+G</code>), the subtitle sidebar, or the launcher. SubMiner can download models for you; optional Silero speech detection helps focus on dialogue. Requires whisper.cpp and FFmpeg. <a href="https://docs.subminer.moe/subtitle-generation">Setup guide</a></td>
-  </tr>
-  <tr>
-    <td><b>AniSkip</b></td>
-    <td>Automatic intro detection with chapter markers and a one-key skip (<code>TAB</code> by default)</td>
-  </tr>
-  <tr>
-    <td><b>alass / ffsubsync</b></td>
-    <td>Retime a subtitle against the audio or another subtitle track (<code>Ctrl+Alt+S</code>). Requires <code>alass</code> or <code>ffsubsync</code>; set <code>subsync.alass_path</code> or <code>subsync.ffsubsync_path</code> if they are not in <code>/usr/bin</code></td>
-  </tr>
-  <tr>
-    <td><b>WebSocket</b></td>
-    <td>Plain subtitle feed plus a dedicated annotated feed for texthooker pages and custom tools</td>
-  </tr>
-  <tr>
-    <td><b>Plugins</b></td>
-    <td>Load your own JavaScript at startup to react to playback, run timers, add key-bound actions, and show results in an overlay panel. Bundled examples explain the current line with Codex, sync Anki to AnkiWeb, and tag mined cards by episode. <a href="https://docs.subminer.moe/plugins">Plugin guide</a></td>
-  </tr>
-</table>
+- starts in the tray/background
+- creates the default config directory and `config.jsonc`
+- opens a compact setup popup
+- can install the mpv plugin to the default mpv scripts location for you
+- links directly to Yomitan settings so you can install dictionaries before finishing setup
 
-<br>
+Existing installs that already have a valid config plus at least one Yomitan dictionary are auto-detected as complete and will not be re-prompted.
 
----
+### 3. Finish setup
+
+- click `Install mpv plugin` if you want the default plugin auto-start flow
+- click `Open Yomitan Settings` and install at least one dictionary
+- click `Refresh status`
+- click `Finish setup`
+
+The mpv plugin step is optional. Yomitan must report at least one installed dictionary before setup can be completed.
+
+### 4. Mine
+
+```bash
+subminer video.mkv # default plugin config auto-starts visible overlay + resumes playback when ready
+subminer --start video.mkv # optional explicit overlay start when plugin auto_start=no
+```
 
 ## Requirements
 
-SubMiner runs on Linux, macOS 11+, and Windows 10+. Only **mpv** is required to run it (plus `fuse2` for the Linux AppImage). Mining cards also needs Anki with the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) add-on. Everything else is optional.
-
-| Dependency               | Status           | What it does                                                         |
-| ------------------------ | ---------------- | -------------------------------------------------------------------- |
-| mpv                      | Required         | The video player SubMiner draws over                                 |
-| fuse2                    | Required (Linux) | Running the AppImage                                                 |
-| Anki + AnkiConnect       | Required to mine | Card creation from the Yomitan popup                                 |
-| ffmpeg                   | Recommended      | Audio clips and screenshots on cards                                 |
-| MeCab + mecab-ipadic     | Recommended      | More accurate N+1, JLPT, and frequency highlighting                  |
-| xdotool + xwininfo       | Required (X11)   | Window tracking on desktops other than Hyprland or Sway              |
-| yt-dlp                   | Optional         | YouTube playback                                                     |
-| xz                       | Optional         | TsukiHime subtitle downloads (most Linux distros already have it)    |
-| alass / ffsubsync        | Optional         | Subtitle sync                                                        |
-| whisper.cpp              | Optional         | [Subtitle generation](https://docs.subminer.moe/subtitle-generation) |
-| guessit                  | Optional         | Better title, season, and episode detection for AniSkip and AniList  |
-| fzf / rofi               | Optional         | Video picker in the `subminer` launcher (rofi is Linux only)         |
-| chafa, ffmpegthumbnailer | Optional         | Thumbnail previews in the launcher pickers                           |
-
-<details>
-<summary><b>Platform-specific install commands</b></summary>
-
-**Arch Linux:**
-
-```bash
-sudo pacman -S --needed mpv ffmpeg
-paru -S --needed mecab-git mecab-ipadic   # MeCab is only in the AUR
-```
-
-On desktops other than Hyprland or Sway, also install `xdotool` and `xorg-xwininfo`.
-
-**macOS:**
-
-```bash
-brew install mpv ffmpeg mecab mecab-ipadic
-```
-
-**Windows:**
-
-```powershell
-winget install shinchiro.mpv
-winget install Gyan.FFmpeg
-```
-
-Then reopen your terminal and check `mpv --version` and `ffmpeg -version`. ffmpeg must be on `PATH`; mpv does not have to be. If `mpv` is not found, either add its folder (usually `%LOCALAPPDATA%\Programs\mpv`) to `PATH` or enter the full path to `mpv.exe` during first-run setup.
-
-[Scoop](https://scoop.sh) is the alternative if you want one package manager for everything. It is the only one that also carries `xz`:
-
-```powershell
-scoop bucket add extras
-scoop install extras/mpv main/ffmpeg main/yt-dlp main/xz
-```
-
-See the [installation guide](https://docs.subminer.moe/installation#_1-install-requirements) for Ubuntu, Debian, and Fedora commands and the full optional package lists.
-
-</details>
-
----
-
-## Quick Start
-
-### 1. Install SubMiner
-
-<details>
-<summary><b>Arch Linux (AUR)</b></summary>
-
-```bash
-paru -S subminer-bin
-```
-
-Includes the AppImage and the `subminer` command.
-
-</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
-```
-
-The AppImage is all you need. First-run setup can install the optional `subminer` command, which runs on a copy of Bun bundled with the app, so you do not need Bun installed.
-
-</details>
-
-<details>
-<summary><b>macOS (DMG)</b></summary>
-
-Download the latest DMG from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest) and drag `SubMiner.app` into `/Applications`.
-
-Then enable SubMiner under **System Settings > Privacy & Security > Accessibility** (named **Device Control and Data Access** on macOS 27) so the overlay can track the mpv window. Without it, SubMiner falls back to a basic window lookup that cannot tell when mpv is minimized. If macOS blocks the first launch, right-click the app and choose **Open**.
-
-</details>
-
-<details>
-<summary><b>Windows</b></summary>
-
-Download and run the latest installer (`SubMiner-<version>.exe`) from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). A portable `.zip` is also available.
-
-</details>
-
-<details>
-<summary><b>From source</b></summary>
-
-See the [build-from-source guide](https://docs.subminer.moe/installation#from-source).
-
-</details>
-
-### 2. Launch & Set Up
-
-Start SubMiner and the setup window opens on first launch. It creates your config file, imports Yomitan dictionaries (you need at least one for lookups), and can install the `subminer` command. On Windows it also creates a **SubMiner mpv** shortcut.
-
-```bash
-subminer app --setup                     # AUR
-~/.local/bin/SubMiner.AppImage --setup   # AppImage
-```
-
-On **macOS**, open `SubMiner.app` from `/Applications`. On **Windows**, run SubMiner from the Start menu. To reopen setup later, run `subminer app --setup`.
-
-For card creation, keep Anki open with AnkiConnect installed. SubMiner connects to it at its default address with no extra setup.
-
-### 3. Mine
-
-```bash
-subminer video.mkv          # play a video with SubMiner
-subminer /path/to/dir       # pick a file with fzf
-subminer -R /path/to/dir    # pick a file with rofi (Linux only)
-subminer -H                 # watch history: replay, next, or previous episode
-subminer doctor             # check your setup
-```
-
-On **Windows**, double-click the **SubMiner mpv** shortcut or drag a video file onto it.
-
-Starting mpv some other way? See [Launching mpv yourself](https://docs.subminer.moe/installation#launching-mpv-yourself) for the IPC socket option the overlay needs.
+| Required                                   | Optional                                           |
+| ------------------------------------------ | -------------------------------------------------- |
+| `bun`, `node` 22, `npm`                    |                                                    |
+| `mpv` with IPC socket                      | `yt-dlp`                                           |
+| `ffmpeg`                                   | `guessit` (better AniSkip title/episode detection) |
+| `mecab` + `mecab-ipadic`                   | `fzf` / `rofi`                                     |
+| Linux: `hyprctl` or `xdotool` + `xwininfo` | `chafa`, `ffmpegthumbnailer`                       |
+| macOS: Accessibility permission            |                                                    |
 
 ## Documentation
 
-Full guides on configuration, Anki setup, Jellyfin, immersion tracking, and more: **[docs.subminer.moe](https://docs.subminer.moe)**
+For full guides on configuration, Anki, Jellyfin, and more, see [docs.subminer.moe](https://docs.subminer.moe).
 
----
+## Testing
+
+- Run `bun run test` or `bun run test:fast` for the default fast lane: config/core coverage plus representative entry/runtime, Anki integration, and main runtime checks.
+- Run `bun run test:full` for the maintained test surface: Bun-compatible `src/**` coverage, Bun-compatible launcher unit coverage, and a Node compatibility lane for suites that depend on Electron named exports or `node:sqlite` behavior.
+- Run `bun run test:node:compat` directly when you only need the Node-backed compatibility slice: `ipc`, `anki-jimaku-ipc`, `overlay-manager`, `config-validation`, `startup-config`, and runtime registry coverage.
+- Run `bun run test:env` for environment-specific verification: launcher smoke/plugin checks plus the SQLite-backed immersion tracker lane.
+- Run `bun run test:immersion:sqlite` when you specifically need real SQLite persistence coverage under Node with `--experimental-sqlite`.
+- Run `bun run test:subtitle` for the maintained `alass`/`ffsubsync` subtitle surface.
+
+The Bun-managed discovery lanes intentionally exclude a small set of suites that are currently Node-only because of Bun runtime/tooling gaps rather than product behavior: Electron named-export tests in `src/core/services/ipc.test.ts`, `src/core/services/anki-jimaku-ipc.test.ts`, and `src/core/services/overlay-manager.test.ts`, plus runtime/config tests in `src/main/config-validation.test.ts`, `src/main/runtime/startup-config.test.ts`, and `src/main/runtime/registry.test.ts`. `bun run test:node:compat` keeps those suites in the standard workflow instead of leaving them untracked.
 
 ## Acknowledgments
 
-SubMiner builds on the work of these open-source projects:
-
-| Project                                                                                     | Role                                                                    |
-| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| [ani-skip](https://github.com/synacktraa/ani-skip)                                          | AniSkip API client for anime intro/outro skip timestamps                |
-| [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script)                          | Inspiration for the mining workflow                                     |
-| [asbplayer](https://github.com/killergerbah/asbplayer)                                      | Inspiration for subtitle sidebar and logic for YouTube subtitle parsing |
-| [Bee's Character Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary) | Character name recognition in subtitles                                 |
-| [Bun](https://github.com/oven-sh/bun)                                                       | Bundled runtime for the `subminer` command-line launcher                |
-| [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner)                          | Inspiration for Electron overlay with Yomitan integration               |
-| [jellyfin-mpv-shim](https://github.com/jellyfin/jellyfin-mpv-shim)                          | Jellyfin integration                                                    |
-| [Jimaku.cc](https://jimaku.cc)                                                              | Japanese subtitle search and downloads                                  |
-| [Renji's Texthooker Page](https://github.com/Renji-XD/texthooker-ui)                        | Base for the WebSocket texthooker integration                           |
-| [Yomitan](https://github.com/yomidevs/yomitan)                                              | Default dictionary engine and morphological parser                      |
-| [Hachidori](https://github.com/bee-san/hachidori)                                           | Alternative dictionary backend, powered by HoshiDicts                   |
-| [yomitan-jlpt-vocab](https://github.com/stephenmk/yomitan-jlpt-vocab)                       | JLPT level tags for vocabulary                                          |
+Built on the shoulders of [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner), [Renji's Texthooker Page](https://github.com/Renji-XD/texthooker-ui), [mpvacious](https://github.com/Ajatt-Tools/mpvacious), [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script), and [Bee's Character Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary). Subtitles powered by [Jimaku.cc](https://jimaku.cc). Dictionary lookups via [Yomitan](https://github.com/yomidevs/yomitan).
 
 ## License
 
-SubMiner is released under the [GNU General Public License v3.0](LICENSE).
-
-Release packages also bundle an unmodified copy of [Bun](https://github.com/oven-sh/bun), which is MIT licensed and statically links JavaScriptCore (LGPL 2.0) and TinyCC (LGPL 2.1). Its license texts and third-party notices ship inside the app under `resources/bun/licenses`, and each release publishes `bun-v1.3.5-source.tar.gz` with the corresponding source. See [Bundled Bun runtime](https://docs.subminer.moe/installation#bundled-bun-runtime).
+[GNU General Public License v3.0](LICENSE)

assets/plugins/ai-explain/main.js

@@ -1,134 +0,0 @@
-// Sends the current subtitle line, with a few lines of context, to `codex exec` and shows the
-// answer in the SubMiner plugin panel. Registers two actions: `explain` and `translate`.
-const { mkdtemp, readFile, rm } = require('node:fs/promises');
-const os = require('node:os');
-const path = require('node:path');
-
-const DEFAULT_SETTINGS = {
-  codexPath: 'codex',
-  model: '',
-  // Passed as -c model_reasoning_effort; low keeps answers to a few seconds. Empty uses your Codex config.
-  reasoningEffort: 'low',
-  before: 2,
-  after: 1,
-  timeoutMs: 120_000,
-  pause: true,
-  prompts: {},
-};
-
-const ACTIONS = {
-  explain: {
-    title: 'Grammar',
-    prompt:
-      'You are a Japanese tutor. Explain the line marked >>> for an intermediate learner. ' +
-      'Use the other lines only as context. Reply in English markdown: a natural translation, ' +
-      'then a bullet list of the grammar points and notable vocabulary. Be concise.',
-  },
-  translate: {
-    title: 'Translation',
-    prompt:
-      'Translate the line marked >>> into natural English. Use the other lines only as context. ' +
-      'Reply with the translation, then one short note only if the line is ambiguous.',
-  },
-};
-
-function activate(ctx) {
-  const settings = { ...DEFAULT_SETTINGS, ...ctx.settings };
-  for (const [name, action] of Object.entries(ACTIONS)) {
-    const prompt = settings.prompts?.[name] ?? action.prompt;
-    ctx.actions.register(name, () => ask(ctx, settings, action.title, prompt));
-  }
-}
-
-function quote(text) {
-  return text
-    .split('\n')
-    .map((line) => `> ${line}`)
-    .join('\n');
-}
-
-// Subtitles wrap across lines; flatten each cue so the >>> marker covers all of it.
-function oneLine(text) {
-  return text
-    .split('\n')
-    .map((part) => part.trim())
-    .filter(Boolean)
-    .join(' ');
-}
-
-function tail(text, lineCount) {
-  return text.trim().split('\n').slice(-lineCount).join('\n');
-}
-
-async function ask(ctx, settings, title, instructions) {
-  const { before, current, after } = ctx.subtitles.context({
-    before: settings.before,
-    after: settings.after,
-  });
-  if (!current) {
-    ctx.notify('No subtitle line to send.', { variant: 'warning' });
-    return;
-  }
-  if (settings.pause) ctx.mpv.command(['set', 'pause', 'yes']);
-
-  const header = quote(current.text);
-  const panel = ctx.ui.panel({ title, markdown: `${header}\n\n_Asking Codex..._` });
-  const prompt = [
-    instructions,
-    '',
-    'Subtitles:',
-    ...before.map((line) => oneLine(line.text)),
-    `>>> ${oneLine(current.text)}`,
-    ...after.map((line) => oneLine(line.text)),
-  ].join('\n');
-
-  // Codex runs in an empty read-only directory so any command it tries cannot touch real files.
-  const workDir = await mkdtemp(path.join(os.tmpdir(), 'subminer-ai-explain-'));
-  const answerPath = path.join(workDir, 'answer.md');
-  const args = [
-    'exec',
-    '--ephemeral',
-    '--skip-git-repo-check',
-    '--sandbox',
-    'read-only',
-    '--color',
-    'never',
-    '-C',
-    workDir,
-    '-o',
-    answerPath,
-  ];
-  if (settings.model) args.push('-m', settings.model);
-  if (settings.reasoningEffort) {
-    args.push('-c', `model_reasoning_effort=${JSON.stringify(settings.reasoningEffort)}`);
-  }
-  args.push('-');
-
-  try {
-    const result = await ctx.exec(settings.codexPath, args, {
-      stdin: prompt,
-      timeoutMs: settings.timeoutMs,
-      signal: panel.signal,
-    });
-    if (result.exitCode !== 0) {
-      throw new Error(tail(result.stderr, 6) || `codex exited with code ${result.exitCode}`);
-    }
-    const answer = (await readFile(answerPath, 'utf8')).trim();
-    panel.update({ markdown: `${header}\n\n${answer || '_Codex returned an empty answer._'}` });
-  } catch (error) {
-    // Closing the panel aborts the request; there is nobody left to show the error to.
-    if (panel.signal.aborted) return;
-    const message =
-      error?.code === 'ENOENT'
-        ? `Cannot find \`${settings.codexPath}\`. Set \`plugins.ai-explain.settings.codexPath\` to its full path.`
-        : String(error?.message ?? error);
-    ctx.log.warn(`Codex request failed: ${message}`);
-    panel.update({
-      markdown: `${header}\n\n**Codex request failed.**\n\n\`\`\`\n${message}\n\`\`\``,
-    });
-  } finally {
-    await rm(workDir, { recursive: true, force: true });
-  }
-}
-
-module.exports = { activate };

assets/plugins/ai-explain/plugin.json

@@ -1,6 +0,0 @@
-{
-  "name": "AI Explain",
-  "version": "1.0.0",
-  "apiVersion": 1,
-  "main": "main.js"
-}

assets/plugins/anki-sync/main.js

@@ -1,61 +0,0 @@
-// Runs AnkiConnect's `sync` (AnkiWeb) after you mine cards. A burst of mining becomes one sync:
-// it waits until no card has been mined for `delayMs`, and syncs right away when playback ends.
-// Also registers a `sync` action for a manual sync.
-
-const DEFAULT_SETTINGS = {
-  delayMs: 30_000,
-  syncOnEnd: true,
-  timeoutMs: 60_000,
-  notify: true,
-};
-
-const END_REASONS = new Set(['eof', 'stop', 'quit']);
-
-function activate(ctx) {
-  const settings = { ...DEFAULT_SETTINGS, ...ctx.settings };
-  // Cards mined since the last sync started.
-  let dirty = false;
-  let syncing = false;
-  let cancelTimer = null;
-
-  function schedule() {
-    cancelTimer?.();
-    cancelTimer = ctx.after(settings.delayMs, flush);
-  }
-
-  async function flush() {
-    cancelTimer?.();
-    cancelTimer = null;
-    // A sync already running picks up new cards when it finishes.
-    if (!dirty || syncing) return;
-    dirty = false;
-    syncing = true;
-    try {
-      await ctx.anki.invoke('sync', {}, { timeoutMs: settings.timeoutMs });
-      ctx.log.info('Synced Anki.');
-      if (settings.notify) ctx.notify('Anki synced');
-    } catch (error) {
-      ctx.log.warn(`Anki sync failed: ${error.message}`);
-      ctx.notify(`Anki sync failed: ${error.message}`, { variant: 'error' });
-    } finally {
-      syncing = false;
-      if (dirty) schedule();
-    }
-  }
-
-  ctx.anki.on('card-mined', () => {
-    dirty = true;
-    schedule();
-  });
-
-  ctx.mpv.on('end-file', ({ reason }) => {
-    if (settings.syncOnEnd && END_REASONS.has(reason)) return flush();
-  });
-
-  ctx.actions.register('sync', () => {
-    dirty = true;
-    return flush();
-  });
-}
-
-module.exports = { activate };

assets/plugins/anki-sync/plugin.json

@@ -1,6 +0,0 @@
-{
-  "name": "Anki Sync",
-  "version": "1.0.0",
-  "apiVersion": 1,
-  "main": "main.js"
-}

assets/plugins/episode-tags/main.js

@@ -1,110 +0,0 @@
-// Tags each mined card with the show and episode it came from, e.g. `show::Frieren::S01E07`.
-// The show and episode are parsed from the file name, or from mpv's media title for streams.
-const path = require('node:path');
-
-const DEFAULT_SETTINGS = {
-  // Placeholders: {show}, {season}, {episode}, and {ep} (S01E07, or E07 without a season).
-  // A tag stops before the first `::` level whose placeholder has no value.
-  tags: ['show::{show}::{ep}'],
-  notify: false,
-};
-
-// Tried in order; the first match wins. Runs on names with brackets and dots already removed.
-const EPISODE_PATTERNS = [
-  /^(?<show>.*?)\s*S(?<season>\d{1,2})\s?E(?<episode>\d{1,4})\b/i,
-  /^(?<show>.*?)\s*(?:Season\s?(?<season>\d{1,2})\s*)?(?:Episode|Ep)\s?(?<episode>\d{1,4})\b/i,
-  /^(?<show>.*?)\s+-\s+(?<episode>\d{1,4})(?:v\d)?\b/,
-  /^(?<show>.*?)\s+(?<episode>\d{1,4})(?:v\d)?$/,
-  /^(?<show>.*?)\s*第(?<episode>\d{1,4})話/,
-];
-
-// `[Group] Show Name - 07 (1080p).mkv` -> { show: 'Show Name', season: null, episode: '07' }
-function parseMediaName(name) {
-  const cleaned = name
-    .replace(/\.[a-z0-9]{2,4}$/i, '')
-    .replace(/\[[^\]]*\]|\([^)]*\)|【[^】]*】/g, ' ')
-    .replace(/[._]/g, ' ')
-    .replace(/\s+/g, ' ')
-    .trim();
-  for (const pattern of EPISODE_PATTERNS) {
-    const groups = cleaned.match(pattern)?.groups;
-    const show = groups?.show.replace(/[\s-]+$/, '');
-    if (!show) continue;
-    return { show, season: pad(groups.season), episode: pad(groups.episode) };
-  }
-  return { show: cleaned || null, season: null, episode: null };
-}
-
-function pad(number) {
-  return number ? String(Number(number)).padStart(2, '0') : null;
-}
-
-// Anki tags can't hold spaces, and a `::` in a value would add a hierarchy level.
-function tagValue(value) {
-  return value.replace(/::?/g, ' ').trim().replace(/\s+/g, '_').replace(/"/g, '');
-}
-
-function renderTag(template, values) {
-  const levels = [];
-  for (const level of template.split('::')) {
-    let missing = false;
-    const rendered = level.replace(/\{(\w+)\}/g, (_, key) => {
-      const value = values[key];
-      if (!value) missing = true;
-      return value ? tagValue(value) : '';
-    });
-    if (missing) break;
-    levels.push(rendered);
-  }
-  return levels.join('::');
-}
-
-function mediaName(mediaPath, title) {
-  // A stream URL's last segment is usually an id, so streams use the title mpv shows.
-  if (typeof mediaPath === 'string' && mediaPath && !/^[a-z]+:\/\//i.test(mediaPath)) {
-    return path.basename(mediaPath);
-  }
-  return typeof title === 'string' && title ? title : null;
-}
-
-function renderTags(templates, name) {
-  const { show, season, episode } = parseMediaName(name);
-  const ep = episode ? `${season ? `S${season}` : ''}E${episode}` : null;
-  const values = { show, season, episode, ep };
-  return [...new Set(templates.map((template) => renderTag(template, values)))].filter(Boolean);
-}
-
-function activate(ctx) {
-  const settings = { ...DEFAULT_SETTINGS, ...ctx.settings };
-  ctx.anki.on('card-mined', async ({ notes }) => {
-    // Notes from the same file share one addTags call.
-    const notesByName = new Map();
-    for (const { noteId, provenance } of notes) {
-      const name = mediaName(provenance?.media?.path, provenance?.media?.title);
-      if (!name) {
-        ctx.log.debug(`Note ${noteId} has no known media source; not tagging it.`);
-        continue;
-      }
-      if (!notesByName.has(name)) notesByName.set(name, new Set());
-      notesByName.get(name).add(noteId);
-    }
-
-    for (const [name, notes] of notesByName) {
-      const tags = renderTags(settings.tags, name);
-      if (tags.length === 0) {
-        ctx.log.debug(`No tags for "${name}".`);
-        continue;
-      }
-      try {
-        await ctx.anki.invoke('addTags', { notes: [...notes], tags: tags.join(' ') });
-        ctx.log.info(`Tagged ${notes.size} note(s): ${tags.join(' ')}`);
-        if (settings.notify) ctx.notify(`Tagged ${tags.join(' ')}`);
-      } catch (error) {
-        ctx.log.warn(`Tagging failed: ${error.message}`);
-        ctx.notify(`Episode tagging failed: ${error.message}`, { variant: 'error' });
-      }
-    }
-  });
-}
-
-module.exports = { activate };

assets/plugins/episode-tags/plugin.json

@@ -1,6 +0,0 @@
-{
-  "name": "Episode Tags",
-  "version": "1.0.0",
-  "apiVersion": 1,
-  "main": "main.js"
-}

assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer

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

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/config.yml

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -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/tasks/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/tasks/task-110 - Replace-vendored-Yomitan-with-submodule-built-chrome-artifact-workflow.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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