chore: prepare v0.9.3 release

refactor: move youtube primary subtitle config to youtube
docs: apply M PLUS 1 and Manrope font defaults for docs content
2026-03-26 12:11:26 -07:00 · 2026-03-25 23:58:31 -07:00 · 2026-03-25 23:53:56 -07:00 · 2026-03-25 23:52:29 -07:00 · 2026-03-25 22:42:21 -07:00 · 2026-03-25 22:37:59 -07:00
842 changed files with 89792 additions and 3224 deletions
--- a/.agents/skills/subminer-change-verification/SKILL.md
+++ b/.agents/skills/subminer-change-verification/SKILL.md
@@ -0,0 +1,127 @@
+---
+name: "subminer-change-verification"
+description: "Use when working in the SubMiner repo and you need to verify code changes actually work. Covers targeted regression checks during debugging and pre-handoff verification, with cheap-first lane selection for config, docs, launcher/plugin, runtime-compat, and optional real-runtime escalation."
+---
+
+# SubMiner Change Verification
+
+Use this skill for SubMiner code changes. Default to cheap, repo-native verification first. Escalate only when the changed behavior actually depends on Electron, mpv, overlay/window tracking, or other GUI-sensitive runtime behavior.
+
+## Scripts
+
+- `scripts/classify_subminer_diff.sh`
+  - Emits suggested lanes and flags from explicit paths or current git changes.
+- `scripts/verify_subminer_change.sh`
+  - Runs selected lanes, captures artifacts, and writes a compact summary.
+
+If you need an explicit installed path, use the directory that contains this `SKILL.md`. The helper scripts live under:
+
+```bash
+export SUBMINER_VERIFY_SKILL="<path-to-skill>"
+```
+
+## Default workflow
+
+1. Inspect the changed files or user-requested area.
+2. Run the classifier unless you already know the right lane.
+3. Run the verifier with the cheapest sufficient lane set.
+4. If the classifier emits `flag:real-runtime-candidate`, do not jump straight to runtime verification. First run the non-runtime lanes.
+5. Escalate to explicit `--lane real-runtime --allow-real-runtime` only when cheaper lanes cannot validate the behavior claim.
+6. Return:
+   - verification summary
+   - exact commands run
+   - artifact paths
+   - skipped lanes and blockers
+
+## Quick start
+
+Repo-source quick start:
+
+```bash
+bash .agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh
+```
+
+Installed-skill quick start:
+
+```bash
+bash "$SUBMINER_VERIFY_SKILL/scripts/classify_subminer_diff.sh"
+```
+
+Classify explicit files:
+
+```bash
+bash .agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh \
+  launcher/main.ts \
+  plugin/subminer/lifecycle.lua \
+  src/main/runtime/mpv-client-runtime-service.ts
+```
+
+Run automatic lane selection:
+
+```bash
+bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh
+```
+
+Installed-skill form:
+
+```bash
+bash "$SUBMINER_VERIFY_SKILL/scripts/verify_subminer_change.sh"
+```
+
+Run targeted lanes:
+
+```bash
+bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh \
+  --lane launcher-plugin \
+  --lane runtime-compat
+```
+
+Dry-run to inspect planned commands and artifact layout:
+
+```bash
+bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh \
+  --dry-run \
+  launcher/main.ts \
+  src/main.ts
+```
+
+## Lane guidance
+
+- `docs`
+  - For `docs-site/`, `docs/`, and doc-only edits.
+- `config`
+  - For `src/config/` and config-template-sensitive edits.
+- `core`
+  - For general source changes where `typecheck` + `test:fast` is the best cheap signal.
+- `launcher-plugin`
+  - For `launcher/`, `plugin/subminer/`, plugin gating scripts, and wrapper/mpv routing work.
+- `runtime-compat`
+  - For `src/main*`, runtime/composer wiring, mpv/overlay services, window trackers, and dist-sensitive behavior.
+- `real-runtime`
+  - Only after deliberate escalation.
+
+## Real Runtime Escalation
+
+Escalate only when the change claim depends on actual runtime behavior, for example:
+
+- overlay appears, hides, or tracks a real mpv window
+- mpv launch flags or pause-until-ready behavior
+- plugin/socket/auto-start handshake under a real player
+- macOS/window-tracker/focus-sensitive behavior
+
+If the environment cannot support authoritative runtime verification, report the blocker explicitly. Do not silently downgrade a runtime-required claim to a pass.
+
+## Artifact contract
+
+The verifier writes under `.tmp/skill-verification/<timestamp>/`:
+
+- `summary.json`
+- `summary.txt`
+- `classification.txt`
+- `env.txt`
+- `lanes.txt`
+- `steps.tsv`
+- `steps/*.stdout.log`
+- `steps/*.stderr.log`
+
+On failure, quote the exact failing command and point at the artifact directory.
--- a/.agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh
+++ b/.agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh
@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: classify_subminer_diff.sh [path ...]
+
+Emit suggested verification lanes for explicit paths or current local git changes.
+
+Output format:
+  lane:<name>
+  flag:<name>
+  reason:<text>
+EOF
+}
+
+has_item() {
+  local needle=$1
+  shift || true
+  local item
+  for item in "$@"; do
+    if [[ "$item" == "$needle" ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+add_lane() {
+  local lane=$1
+  if ! has_item "$lane" "${LANES[@]:-}"; then
+    LANES+=("$lane")
+  fi
+}
+
+add_flag() {
+  local flag=$1
+  if ! has_item "$flag" "${FLAGS[@]:-}"; then
+    FLAGS+=("$flag")
+  fi
+}
+
+add_reason() {
+  REASONS+=("$1")
+}
+
+collect_git_paths() {
+  local top_level
+  if ! top_level=$(git rev-parse --show-toplevel 2>/dev/null); then
+    return 0
+  fi
+
+  (
+    cd "$top_level"
+    if git rev-parse --verify HEAD >/dev/null 2>&1; then
+      git diff --name-only --relative HEAD --
+      git diff --name-only --relative --cached --
+    else
+      git diff --name-only --relative --
+      git diff --name-only --relative --cached --
+    fi
+    git ls-files --others --exclude-standard
+  ) | awk 'NF' | sort -u
+}
+
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  usage
+  exit 0
+fi
+
+declare -a PATHS=()
+declare -a LANES=()
+declare -a FLAGS=()
+declare -a REASONS=()
+
+if [[ $# -gt 0 ]]; then
+  while [[ $# -gt 0 ]]; do
+    PATHS+=("$1")
+    shift
+  done
+else
+  while IFS= read -r line; do
+    [[ -n "$line" ]] && PATHS+=("$line")
+  done < <(collect_git_paths)
+fi
+
+if [[ ${#PATHS[@]} -eq 0 ]]; then
+  add_lane "core"
+  add_reason "no changed paths detected -> default to core"
+fi
+
+for path in "${PATHS[@]}"; do
+  specialized=0
+
+  case "$path" in
+    docs-site/*|docs/*|changes/*|README.md)
+      add_lane "docs"
+      add_reason "$path -> docs"
+      specialized=1
+      ;;
+  esac
+
+  case "$path" in
+    src/config/*|src/generate-config-example.ts|src/verify-config-example.ts|docs-site/public/config.example.jsonc|config.example.jsonc)
+      add_lane "config"
+      add_reason "$path -> config"
+      specialized=1
+      ;;
+  esac
+
+  case "$path" in
+    launcher/*|plugin/subminer/*|plugin/subminer.conf|scripts/test-plugin-*|scripts/get-mpv-window-*|scripts/configure-plugin-binary-path.mjs)
+      add_lane "launcher-plugin"
+      add_reason "$path -> launcher-plugin"
+      add_flag "real-runtime-candidate"
+      add_reason "$path -> real-runtime-candidate"
+      specialized=1
+      ;;
+  esac
+
+  case "$path" in
+    src/main.ts|src/main-entry.ts|src/preload.ts|src/main/*|src/core/services/mpv*|src/core/services/overlay*|src/renderer/*|src/window-trackers/*|scripts/prepare-build-assets.mjs)
+      add_lane "runtime-compat"
+      add_reason "$path -> runtime-compat"
+      add_flag "real-runtime-candidate"
+      add_reason "$path -> real-runtime-candidate"
+      specialized=1
+      ;;
+  esac
+
+  if [[ "$specialized" == "0" ]]; then
+    case "$path" in
+      src/*|package.json|tsconfig*.json|scripts/*|Makefile)
+        add_lane "core"
+        add_reason "$path -> core"
+        ;;
+    esac
+  fi
+
+  case "$path" in
+    package.json|src/main.ts|src/main-entry.ts|src/preload.ts)
+      add_flag "broad-impact"
+      add_reason "$path -> broad-impact"
+      ;;
+  esac
+done
+
+if [[ ${#LANES[@]} -eq 0 ]]; then
+  add_lane "core"
+  add_reason "no lane-specific matches -> default to core"
+fi
+
+for lane in "${LANES[@]}"; do
+  printf 'lane:%s\n' "$lane"
+done
+
+for flag in "${FLAGS[@]}"; do
+  printf 'flag:%s\n' "$flag"
+done
+
+for reason in "${REASONS[@]}"; do
+  printf 'reason:%s\n' "$reason"
+done
--- a/.agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh
+++ b/.agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh
@@ -0,0 +1,566 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: verify_subminer_change.sh [options] [path ...]
+
+Options:
+  --lane <name>             Force a verification lane. Repeatable.
+  --artifact-dir <dir>      Use an explicit artifact directory.
+  --allow-real-runtime      Allow explicit real-runtime execution.
+  --allow-real-gui          Deprecated alias for --allow-real-runtime.
+  --dry-run                 Record planned steps without executing commands.
+  --help                    Show this help text.
+
+If no lanes are supplied, the script classifies the provided paths. If no paths are
+provided, it classifies the current local git changes.
+
+Authoritative real-runtime verification should be requested with explicit path
+arguments instead of relying on inferred local git changes.
+EOF
+}
+
+timestamp() {
+  date +%Y%m%d-%H%M%S
+}
+
+timestamp_iso() {
+  date -u +%Y-%m-%dT%H:%M:%SZ
+}
+
+generate_session_id() {
+  local tmp_dir
+  tmp_dir=$(mktemp -d "${TMPDIR:-/tmp}/subminer-verify-$(timestamp)-XXXXXX")
+  basename "$tmp_dir"
+  rmdir "$tmp_dir"
+}
+
+has_item() {
+  local needle=$1
+  shift || true
+  local item
+  for item in "$@"; do
+    if [[ "$item" == "$needle" ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+normalize_lane_name() {
+  case "$1" in
+    real-gui)
+      printf '%s' "real-runtime"
+      ;;
+    *)
+      printf '%s' "$1"
+      ;;
+  esac
+}
+
+add_lane() {
+  local lane
+  lane=$(normalize_lane_name "$1")
+  if ! has_item "$lane" "${SELECTED_LANES[@]:-}"; then
+    SELECTED_LANES+=("$lane")
+  fi
+}
+
+add_blocker() {
+  BLOCKERS+=("$1")
+  BLOCKED=1
+}
+
+append_step_record() {
+  printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
+    "$1" "$2" "$3" "$4" "$5" "$6" "$7" "$8" >>"$STEPS_TSV"
+}
+
+record_env() {
+  {
+    printf 'repo_root=%s\n' "$REPO_ROOT"
+    printf 'session_id=%s\n' "$SESSION_ID"
+    printf 'artifact_dir=%s\n' "$ARTIFACT_DIR"
+    printf 'path_selection_mode=%s\n' "$PATH_SELECTION_MODE"
+    printf 'dry_run=%s\n' "$DRY_RUN"
+    printf 'allow_real_runtime=%s\n' "$ALLOW_REAL_RUNTIME"
+    printf 'session_home=%s\n' "$SESSION_HOME"
+    printf 'session_xdg_config_home=%s\n' "$SESSION_XDG_CONFIG_HOME"
+    printf 'session_mpv_dir=%s\n' "$SESSION_MPV_DIR"
+    printf 'session_logs_dir=%s\n' "$SESSION_LOGS_DIR"
+    printf 'session_mpv_log=%s\n' "$SESSION_MPV_LOG"
+    printf 'pwd=%s\n' "$(pwd)"
+    git rev-parse --short HEAD 2>/dev/null | sed 's/^/git_head=/' || true
+    git status --short 2>/dev/null || true
+    if [[ ${#PATH_ARGS[@]} -gt 0 ]]; then
+      printf 'requested_paths=\n'
+      printf '  %s\n' "${PATH_ARGS[@]}"
+    fi
+  } >"$ARTIFACT_DIR/env.txt"
+}
+
+run_step() {
+  local lane=$1
+  local name=$2
+  local command=$3
+  local note=${4:-}
+  local slug=${name//[^a-zA-Z0-9_-]/-}
+  local stdout_rel="steps/${slug}.stdout.log"
+  local stderr_rel="steps/${slug}.stderr.log"
+  local stdout_path="$ARTIFACT_DIR/$stdout_rel"
+  local stderr_path="$ARTIFACT_DIR/$stderr_rel"
+  local status exit_code
+
+  COMMANDS_RUN+=("$command")
+  printf '%s\n' "$command" >"$ARTIFACT_DIR/steps/${slug}.command.txt"
+
+  if [[ "$DRY_RUN" == "1" ]]; then
+    printf '[dry-run] %s\n' "$command" >"$stdout_path"
+    : >"$stderr_path"
+    status="dry-run"
+    exit_code=0
+  else
+    if bash -lc "cd \"$REPO_ROOT\" && $command" >"$stdout_path" 2>"$stderr_path"; then
+      status="passed"
+      exit_code=0
+      EXECUTED_REAL_STEPS=1
+    else
+      exit_code=$?
+      status="failed"
+      FAILED=1
+    fi
+  fi
+
+  append_step_record "$lane" "$name" "$status" "$exit_code" "$command" "$stdout_rel" "$stderr_rel" "$note"
+  printf '%s\t%s\t%s\n' "$lane" "$name" "$status"
+
+  if [[ "$status" == "failed" ]]; then
+    FAILURE_STEP="$name"
+    FAILURE_COMMAND="$command"
+    FAILURE_STDOUT="$stdout_rel"
+    FAILURE_STDERR="$stderr_rel"
+    return "$exit_code"
+  fi
+}
+
+record_nonpassing_step() {
+  local lane=$1
+  local name=$2
+  local status=$3
+  local note=$4
+  local slug=${name//[^a-zA-Z0-9_-]/-}
+  local stdout_rel="steps/${slug}.stdout.log"
+  local stderr_rel="steps/${slug}.stderr.log"
+  printf '%s\n' "$note" >"$ARTIFACT_DIR/$stdout_rel"
+  : >"$ARTIFACT_DIR/$stderr_rel"
+  append_step_record "$lane" "$name" "$status" "0" "" "$stdout_rel" "$stderr_rel" "$note"
+  printf '%s\t%s\t%s\n' "$lane" "$name" "$status"
+}
+
+record_skipped_step() {
+  record_nonpassing_step "$1" "$2" "skipped" "$3"
+}
+
+record_blocked_step() {
+  add_blocker "$3"
+  record_nonpassing_step "$1" "$2" "blocked" "$3"
+}
+
+record_failed_step() {
+  FAILED=1
+  FAILURE_STEP=$2
+  FAILURE_COMMAND=${FAILURE_COMMAND:-"(validation)"}
+  FAILURE_STDOUT="steps/${2//[^a-zA-Z0-9_-]/-}.stdout.log"
+  FAILURE_STDERR="steps/${2//[^a-zA-Z0-9_-]/-}.stderr.log"
+  add_blocker "$3"
+  record_nonpassing_step "$1" "$2" "failed" "$3"
+}
+
+find_real_runtime_helper() {
+  local candidate
+  for candidate in \
+    "$SCRIPT_DIR/run_real_runtime_smoke.sh" \
+    "$SCRIPT_DIR/run_real_mpv_smoke.sh"; do
+    if [[ -x "$candidate" ]]; then
+      printf '%s' "$candidate"
+      return 0
+    fi
+  done
+  return 1
+}
+
+acquire_real_runtime_lease() {
+  local lease_root="$REPO_ROOT/.tmp/skill-verification/locks"
+  local lease_dir="$lease_root/exclusive-real-runtime"
+  mkdir -p "$lease_root"
+  if mkdir "$lease_dir" 2>/dev/null; then
+    REAL_RUNTIME_LEASE_DIR="$lease_dir"
+    printf '%s\n' "$SESSION_ID" >"$lease_dir/session_id"
+    return 0
+  fi
+
+  local owner=""
+  if [[ -f "$lease_dir/session_id" ]]; then
+    owner=$(cat "$lease_dir/session_id")
+  fi
+  add_blocker "real-runtime lease already held${owner:+ by $owner}"
+  return 1
+}
+
+release_real_runtime_lease() {
+  if [[ -n "$REAL_RUNTIME_LEASE_DIR" && -d "$REAL_RUNTIME_LEASE_DIR" ]]; then
+    if [[ -f "$REAL_RUNTIME_LEASE_DIR/session_id" ]]; then
+      local owner
+      owner=$(cat "$REAL_RUNTIME_LEASE_DIR/session_id")
+      if [[ "$owner" != "$SESSION_ID" ]]; then
+        return 0
+      fi
+    fi
+    rm -rf "$REAL_RUNTIME_LEASE_DIR"
+  fi
+}
+
+compute_final_status() {
+  if [[ "$FAILED" == "1" ]]; then
+    FINAL_STATUS="failed"
+  elif [[ "$BLOCKED" == "1" ]]; then
+    FINAL_STATUS="blocked"
+  elif [[ "$EXECUTED_REAL_STEPS" == "1" ]]; then
+    FINAL_STATUS="passed"
+  else
+    FINAL_STATUS="skipped"
+  fi
+}
+
+write_summary_files() {
+  local lane_lines
+  lane_lines=$(printf '%s\n' "${SELECTED_LANES[@]}")
+  printf '%s\n' "$lane_lines" >"$ARTIFACT_DIR/lanes.txt"
+  printf '%s\n' "${BLOCKERS[@]}" >"$ARTIFACT_DIR/blockers.txt"
+  printf '%s\n' "${PATH_ARGS[@]}" >"$ARTIFACT_DIR/requested-paths.txt"
+
+  ARTIFACT_DIR_ENV="$ARTIFACT_DIR" \
+  SESSION_ID_ENV="$SESSION_ID" \
+  FINAL_STATUS_ENV="$FINAL_STATUS" \
+  PATH_SELECTION_MODE_ENV="$PATH_SELECTION_MODE" \
+  ALLOW_REAL_RUNTIME_ENV="$ALLOW_REAL_RUNTIME" \
+  SESSION_HOME_ENV="$SESSION_HOME" \
+  SESSION_XDG_CONFIG_HOME_ENV="$SESSION_XDG_CONFIG_HOME" \
+  SESSION_MPV_DIR_ENV="$SESSION_MPV_DIR" \
+  SESSION_LOGS_DIR_ENV="$SESSION_LOGS_DIR" \
+  SESSION_MPV_LOG_ENV="$SESSION_MPV_LOG" \
+  STARTED_AT_ENV="$STARTED_AT" \
+  FINISHED_AT_ENV="$FINISHED_AT" \
+  FAILED_ENV="$FAILED" \
+  FAILURE_COMMAND_ENV="${FAILURE_COMMAND:-}" \
+  FAILURE_STDOUT_ENV="${FAILURE_STDOUT:-}" \
+  FAILURE_STDERR_ENV="${FAILURE_STDERR:-}" \
+  bun -e '
+    const fs = require("fs");
+    const path = require("path");
+
+    function readLines(filePath) {
+      if (!fs.existsSync(filePath)) return [];
+      return fs.readFileSync(filePath, "utf8").split(/\r?\n/).filter(Boolean);
+    }
+
+    const artifactDir = process.env.ARTIFACT_DIR_ENV;
+    const reportsDir = path.join(artifactDir, "reports");
+    const lanes = readLines(path.join(artifactDir, "lanes.txt"));
+    const blockers = readLines(path.join(artifactDir, "blockers.txt"));
+    const requestedPaths = readLines(path.join(artifactDir, "requested-paths.txt"));
+    const steps = readLines(path.join(artifactDir, "steps.tsv")).map((line) => {
+      const [lane, name, status, exitCode, command, stdout, stderr, note] = line.split("\t");
+      return {
+        lane,
+        name,
+        status,
+        exitCode: Number(exitCode || 0),
+        command,
+        stdout,
+        stderr,
+        note,
+      };
+    });
+    const summary = {
+      sessionId: process.env.SESSION_ID_ENV || "",
+      artifactDir,
+      reportsDir,
+      status: process.env.FINAL_STATUS_ENV || "failed",
+      selectedLanes: lanes,
+      failed: process.env.FAILED_ENV === "1",
+      failure:
+        process.env.FAILED_ENV === "1"
+          ? {
+              command: process.env.FAILURE_COMMAND_ENV || "",
+              stdout: process.env.FAILURE_STDOUT_ENV || "",
+              stderr: process.env.FAILURE_STDERR_ENV || "",
+            }
+          : null,
+      blockers,
+      pathSelectionMode: process.env.PATH_SELECTION_MODE_ENV || "git-inferred",
+      requestedPaths,
+      allowRealRuntime: process.env.ALLOW_REAL_RUNTIME_ENV === "1",
+      startedAt: process.env.STARTED_AT_ENV || "",
+      finishedAt: process.env.FINISHED_AT_ENV || "",
+      env: {
+        home: process.env.SESSION_HOME_ENV || "",
+        xdgConfigHome: process.env.SESSION_XDG_CONFIG_HOME_ENV || "",
+        mpvDir: process.env.SESSION_MPV_DIR_ENV || "",
+        logsDir: process.env.SESSION_LOGS_DIR_ENV || "",
+        mpvLog: process.env.SESSION_MPV_LOG_ENV || "",
+      },
+      steps,
+    };
+
+    const summaryJson = JSON.stringify(summary, null, 2) + "\n";
+    fs.writeFileSync(path.join(artifactDir, "summary.json"), summaryJson);
+    fs.writeFileSync(path.join(reportsDir, "summary.json"), summaryJson);
+
+    const lines = [];
+    lines.push(`session_id: ${summary.sessionId}`);
+    lines.push(`artifact_dir: ${artifactDir}`);
+    lines.push(`selected_lanes: ${lanes.join(", ") || "(none)"}`);
+    lines.push(`status: ${summary.status}`);
+    lines.push(`path_selection_mode: ${summary.pathSelectionMode}`);
+    if (requestedPaths.length > 0) {
+      lines.push(`requested_paths: ${requestedPaths.join(", ")}`);
+    }
+    if (blockers.length > 0) {
+      lines.push(`blockers: ${blockers.join(" | ")}`);
+    }
+    for (const step of steps) {
+      lines.push(`${step.lane}/${step.name}: ${step.status}`);
+      if (step.command) lines.push(`  command: ${step.command}`);
+      lines.push(`  stdout: ${step.stdout}`);
+      lines.push(`  stderr: ${step.stderr}`);
+      if (step.note) lines.push(`  note: ${step.note}`);
+    }
+    if (summary.failed) {
+      lines.push(`failure_command: ${process.env.FAILURE_COMMAND_ENV || ""}`);
+    }
+    const summaryText = lines.join("\n") + "\n";
+    fs.writeFileSync(path.join(artifactDir, "summary.txt"), summaryText);
+    fs.writeFileSync(path.join(reportsDir, "summary.txt"), summaryText);
+  '
+}
+
+cleanup() {
+  release_real_runtime_lease
+}
+
+CLASSIFIER_OUTPUT=""
+ARTIFACT_DIR=""
+ALLOW_REAL_RUNTIME=0
+DRY_RUN=0
+FAILED=0
+BLOCKED=0
+EXECUTED_REAL_STEPS=0
+FINAL_STATUS=""
+FAILURE_STEP=""
+FAILURE_COMMAND=""
+FAILURE_STDOUT=""
+FAILURE_STDERR=""
+REAL_RUNTIME_LEASE_DIR=""
+STARTED_AT=""
+FINISHED_AT=""
+
+declare -a EXPLICIT_LANES=()
+declare -a SELECTED_LANES=()
+declare -a PATH_ARGS=()
+declare -a COMMANDS_RUN=()
+declare -a BLOCKERS=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --lane)
+      EXPLICIT_LANES+=("$(normalize_lane_name "$2")")
+      shift 2
+      ;;
+    --artifact-dir)
+      ARTIFACT_DIR=$2
+      shift 2
+      ;;
+    --allow-real-runtime|--allow-real-gui)
+      ALLOW_REAL_RUNTIME=1
+      shift
+      ;;
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    --)
+      shift
+      while [[ $# -gt 0 ]]; do
+        PATH_ARGS+=("$1")
+        shift
+      done
+      ;;
+    *)
+      PATH_ARGS+=("$1")
+      shift
+      ;;
+  esac
+done
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+SESSION_ID=$(generate_session_id)
+PATH_SELECTION_MODE="git-inferred"
+if [[ ${#PATH_ARGS[@]} -gt 0 ]]; then
+  PATH_SELECTION_MODE="explicit"
+fi
+
+if [[ -z "$ARTIFACT_DIR" ]]; then
+  mkdir -p "$REPO_ROOT/.tmp/skill-verification"
+  ARTIFACT_DIR="$REPO_ROOT/.tmp/skill-verification/$SESSION_ID"
+fi
+
+SESSION_HOME="$ARTIFACT_DIR/home"
+SESSION_XDG_CONFIG_HOME="$ARTIFACT_DIR/xdg"
+SESSION_MPV_DIR="$ARTIFACT_DIR/mpv"
+SESSION_LOGS_DIR="$ARTIFACT_DIR/logs"
+SESSION_MPV_LOG="$SESSION_LOGS_DIR/mpv.log"
+
+mkdir -p "$ARTIFACT_DIR/steps" "$ARTIFACT_DIR/reports" "$SESSION_HOME" "$SESSION_XDG_CONFIG_HOME" "$SESSION_MPV_DIR" "$SESSION_LOGS_DIR"
+STEPS_TSV="$ARTIFACT_DIR/steps.tsv"
+: >"$STEPS_TSV"
+
+trap cleanup EXIT
+STARTED_AT=$(timestamp_iso)
+
+if [[ ${#EXPLICIT_LANES[@]} -gt 0 ]]; then
+  local_lane=""
+  for local_lane in "${EXPLICIT_LANES[@]}"; do
+    add_lane "$local_lane"
+  done
+  printf 'reason:explicit lanes supplied\n' >"$ARTIFACT_DIR/classification.txt"
+else
+  if [[ ${#PATH_ARGS[@]} -gt 0 ]]; then
+    CLASSIFIER_OUTPUT=$(bash "$SCRIPT_DIR/classify_subminer_diff.sh" "${PATH_ARGS[@]}")
+  else
+    CLASSIFIER_OUTPUT=$(bash "$SCRIPT_DIR/classify_subminer_diff.sh")
+  fi
+  printf '%s\n' "$CLASSIFIER_OUTPUT" >"$ARTIFACT_DIR/classification.txt"
+  while IFS= read -r line; do
+    case "$line" in
+      lane:*)
+        add_lane "${line#lane:}"
+        ;;
+    esac
+  done <<<"$CLASSIFIER_OUTPUT"
+fi
+
+record_env
+
+printf 'artifact_dir=%s\n' "$ARTIFACT_DIR"
+printf 'selected_lanes=%s\n' "$(IFS=,; echo "${SELECTED_LANES[*]}")"
+
+for lane in "${SELECTED_LANES[@]}"; do
+  case "$lane" in
+    docs)
+      run_step "$lane" "docs-test" "bun run docs:test" || break
+      [[ "$FAILED" == "1" ]] && break
+      run_step "$lane" "docs-build" "bun run docs:build" || break
+      ;;
+    config)
+      run_step "$lane" "test-config" "bun run test:config" || break
+      ;;
+    core)
+      run_step "$lane" "typecheck" "bun run typecheck" || break
+      [[ "$FAILED" == "1" ]] && break
+      run_step "$lane" "test-fast" "bun run test:fast" || break
+      ;;
+    launcher-plugin)
+      run_step "$lane" "launcher-smoke-src" "bun run test:launcher:smoke:src" || break
+      [[ "$FAILED" == "1" ]] && break
+      run_step "$lane" "plugin-src" "bun run test:plugin:src" || break
+      ;;
+    runtime-compat)
+      run_step "$lane" "build" "bun run build" || break
+      [[ "$FAILED" == "1" ]] && break
+      run_step "$lane" "test-runtime-compat" "bun run test:runtime:compat" || break
+      [[ "$FAILED" == "1" ]] && break
+      run_step "$lane" "test-smoke-dist" "bun run test:smoke:dist" || break
+      ;;
+    real-runtime)
+      if [[ "$PATH_SELECTION_MODE" != "explicit" ]]; then
+        record_blocked_step \
+          "$lane" \
+          "real-runtime-guard" \
+          "real-runtime lane requires explicit paths; inferred local git changes are non-authoritative"
+        break
+      fi
+
+      if [[ "$ALLOW_REAL_RUNTIME" != "1" ]]; then
+        record_blocked_step \
+          "$lane" \
+          "real-runtime-guard" \
+          "real-runtime lane requested but --allow-real-runtime was not supplied"
+        break
+      fi
+
+      if ! acquire_real_runtime_lease; then
+        record_blocked_step \
+          "$lane" \
+          "real-runtime-lease" \
+          "real-runtime lease already held; rerun after the active runtime verification finishes"
+        break
+      fi
+
+      if ! REAL_RUNTIME_HELPER=$(find_real_runtime_helper); then
+        record_blocked_step \
+          "$lane" \
+          "real-runtime-helper" \
+          "real-runtime helper not implemented yet"
+        break
+      fi
+
+      printf -v REAL_RUNTIME_COMMAND \
+        'SESSION_ID=%q HOME=%q XDG_CONFIG_HOME=%q SUBMINER_MPV_LOG=%q bash %q' \
+        "$SESSION_ID" \
+        "$SESSION_HOME" \
+        "$SESSION_XDG_CONFIG_HOME" \
+        "$SESSION_MPV_LOG" \
+        "$REAL_RUNTIME_HELPER"
+
+      run_step "$lane" "real-runtime-smoke" "$REAL_RUNTIME_COMMAND" || break
+      ;;
+    *)
+      record_failed_step "$lane" "lane-validation" "unknown lane: $lane"
+      break
+      ;;
+  esac
+
+  if [[ "$FAILED" == "1" || "$BLOCKED" == "1" ]]; then
+    break
+  fi
+done
+
+FINISHED_AT=$(timestamp_iso)
+compute_final_status
+write_summary_files
+
+printf 'status=%s\n' "$FINAL_STATUS"
+printf 'artifact_dir=%s\n' "$ARTIFACT_DIR"
+
+case "$FINAL_STATUS" in
+  failed)
+    printf 'result=failed\n'
+    printf 'failure_command=%s\n' "$FAILURE_COMMAND"
+    exit 1
+    ;;
+  blocked)
+    printf 'result=blocked\n'
+    exit 2
+    ;;
+  *)
+    printf 'result=ok\n'
+    exit 0
+    ;;
+esac
--- a/.agents/skills/subminer-scrum-master/SKILL.md
+++ b/.agents/skills/subminer-scrum-master/SKILL.md
@@ -0,0 +1,146 @@
+---
+name: "subminer-scrum-master"
+description: "Use in the SubMiner repo when a request should be turned into planned work and driven through execution. Assesses whether backlog tracking is warranted, creates or updates tasks when needed, records a plan, dispatches one or more subagents, and requires verification before handoff."
+---
+
+# SubMiner Scrum Master
+
+Own workflow, not code by default.
+
+Use this skill when the user gives a feature request, bug report, issue, refactor, or implementation ask and the agent should manage intake, planning, backlog hygiene, worker dispatch, and verification through completion.
+
+## Core Rules
+
+1. Decide first whether backlog tracking is warranted.
+2. If backlog is needed, search first. Update existing work when it clearly matches.
+3. If backlog is not needed, keep the process light. Do not invent ticket ceremony.
+4. Record a plan before dispatching coding work.
+5. Use parent + subtasks for multi-part work when backlog is used.
+6. Dispatch conservatively. Parallelize only disjoint write scopes.
+7. Require verification before handoff, typically via `subminer-change-verification`.
+8. Report backlog actions, dispatched workers, verification, blockers, and remaining risks.
+
+## Backlog Decision
+
+Skip backlog when the request is:
+- question only
+- obvious mechanical edit
+- tiny isolated change with no real planning
+
+Use backlog when the work:
+- needs planning or scope decisions
+- spans multiple phases or subsystems
+- is likely to need subagent dispatch
+- should remain traceable for handoff/resume
+
+If backlog is used:
+- search existing tasks first
+- create/update a standalone task for one focused deliverable
+- create/update a parent task plus subtasks for multi-part work
+- record the implementation plan in the task before implementation begins
+
+## Intake Workflow
+
+1. Parse the request.
+   Classify it as question, mechanical edit, bugfix, feature, refactor, investigation, or follow-up.
+2. Decide whether backlog is needed.
+3. If backlog is needed:
+   - search first
+   - update existing task if clearly relevant
+   - otherwise create the right structure
+   - write the implementation plan before dispatch
+4. If backlog is skipped:
+   - write a short working plan in-thread
+   - proceed without fake ticketing
+5. Choose execution mode:
+   - no subagents for trivial work
+   - one worker for focused work
+   - parallel workers only for disjoint scopes
+6. Run verification before handoff.
+
+## Dispatch Rules
+
+The scrum master orchestrates. Workers implement.
+
+- Do not become the default implementer unless delegation is unnecessary.
+- Do not parallelize overlapping files or tightly coupled runtime work.
+- Give every worker explicit ownership of files/modules.
+- Tell every worker other agents may be active and they must not revert unrelated edits.
+- Require each worker to report:
+  - changed files
+  - tests run
+  - blockers
+
+Use worker agents for implementation and explorer agents only for bounded codebase questions.
+
+## Verification
+
+Every nontrivial code task gets verification.
+
+Preferred flow:
+1. use `subminer-change-verification`
+2. start with the cheapest sufficient lane
+3. escalate only when needed
+4. if worker verification is sufficient, accept it or run one final consolidating pass
+
+Never hand off nontrivial work without stating what was verified and what was skipped.
+
+## Pre-Handoff Policy Checks (Required)
+
+Before handoff, always ask and answer both of these questions explicitly:
+
+1. **Docs update required?**
+2. **Changelog fragment required?**
+
+Rules:
+- Do not assume silence implies "no." Record an explicit yes/no decision for each item.
+- If the answer is yes, either complete the update or report the blocker before handoff.
+- Include the final answers in the handoff summary even when both answers are "no."
+
+## Failure / Scope Handling
+
+- If a worker hits ambiguity, pause and ask the user.
+- If verification fails, either:
+  - send the worker back with exact failure context, or
+  - fix it directly if it is tiny and clearly in scope
+- If new scope appears, revisit backlog structure before silently expanding work.
+
+## Representative Flows
+
+### Trivial no-ticket work
+
+- decide backlog is unnecessary
+- keep a short plan
+- implement directly or with one worker if helpful
+- run targeted verification
+- report outcome concisely
+
+### Single-task implementation
+
+- search/create/update one task
+- record plan
+- dispatch one worker
+- integrate
+- verify
+- update task and report outcome
+
+### Parent + subtasks execution
+
+- search/create/update parent task
+- create subtasks for distinct deliverables/phases
+- record sequencing in the plan
+- dispatch workers only where scopes are disjoint
+- integrate
+- run consolidated verification
+- update task state and report outcome
+
+## Output Expectations
+
+At the end, report:
+- whether backlog was used and what changed
+- which workers were dispatched and what they owned
+- what verification ran
+- explicit answers to:
+  - docs update required?
+  - changelog fragment required?
+- blockers, skips, and risks
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -27,17 +27,23 @@ jobs:
          path: |
            ~/.bun/install/cache
            node_modules
+            stats/node_modules
            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-bun-

      - name: Install dependencies
-        run: bun install --frozen-lockfile
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile

      - name: Lint changelog fragments
        run: bun run changelog:lint

+      - name: Lint stats (formatting)
+        run: bun run lint:stats
+
      - name: Enforce pull request changelog fragments (`skip-changelog` label bypass)
        if: github.event_name == 'pull_request'
        run: bun run changelog:pr-check --base-ref "origin/${{ github.base_ref }}" --head-ref "HEAD" --labels "${{ join(github.event.pull_request.labels.*.name, ',') }}"
@@ -46,6 +52,12 @@ jobs:
        # Keep explicit typecheck for fast fail before full build/bundle.
        run: bun run typecheck

+      - name: Verify generated config examples
+        run: bun run verify:config-example
+
+      - name: Internal docs knowledge-base checks
+        run: bun run test:docs:kb
+
      - name: Test suite (source)
        run: bun run test:fast

--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -9,10 +9,6 @@ concurrency:
  group: release-${{ github.ref }}
  cancel-in-progress: false

-permissions:
-  actions: read
-  contents: write
-
 jobs:
  quality-gate:
    runs-on: ubuntu-latest
@@ -33,13 +29,19 @@ jobs:
          path: |
            ~/.bun/install/cache
            node_modules
+            stats/node_modules
            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-bun-

      - name: Install dependencies
-        run: bun install --frozen-lockfile
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Lint stats (formatting)
+        run: bun run lint:stats

      - name: Build (TypeScript check)
        run: bun run typecheck
@@ -87,14 +89,17 @@ jobs:
          path: |
            ~/.bun/install/cache
            node_modules
+            stats/node_modules
            vendor/texthooker-ui/node_modules
            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-bun-

      - name: Install dependencies
-        run: bun install --frozen-lockfile
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile

      - name: Build texthooker-ui
        run: |
@@ -142,9 +147,10 @@ jobs:
          path: |
            ~/.bun/install/cache
            node_modules
+            stats/node_modules
            vendor/texthooker-ui/node_modules
            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-bun-

@@ -169,7 +175,9 @@ jobs:
          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}

      - name: Install dependencies
-        run: bun install --frozen-lockfile
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile

      - name: Build texthooker-ui
        run: |
@@ -214,35 +222,17 @@ jobs:
          path: |
            ~/.bun/install/cache
            node_modules
+            stats/node_modules
            vendor/texthooker-ui/node_modules
            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-bun-

-      - name: Validate Windows signing secrets
-        shell: bash
-        run: |
-          missing=0
-          for name in SIGNPATH_API_TOKEN SIGNPATH_ORGANIZATION_ID SIGNPATH_PROJECT_SLUG SIGNPATH_SIGNING_POLICY_SLUG SIGNPATH_ARTIFACT_CONFIGURATION_SLUG; do
-            if [ -z "${!name}" ]; then
-              echo "Missing required secret: $name"
-              missing=1
-            fi
-          done
-          if [ "$missing" -ne 0 ]; then
-            echo "Set the SignPath Windows signing secrets and rerun."
-            exit 1
-          fi
-        env:
-          SIGNPATH_API_TOKEN: ${{ secrets.SIGNPATH_API_TOKEN }}
-          SIGNPATH_ORGANIZATION_ID: ${{ secrets.SIGNPATH_ORGANIZATION_ID }}
-          SIGNPATH_PROJECT_SLUG: ${{ secrets.SIGNPATH_PROJECT_SLUG }}
-          SIGNPATH_SIGNING_POLICY_SLUG: ${{ secrets.SIGNPATH_SIGNING_POLICY_SLUG }}
-          SIGNPATH_ARTIFACT_CONFIGURATION_SLUG: ${{ secrets.SIGNPATH_ARTIFACT_CONFIGURATION_SLUG }}
-
      - name: Install dependencies
-        run: bun install --frozen-lockfile
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile

      - name: Build texthooker-ui
        shell: powershell
@@ -252,102 +242,22 @@ jobs:
          bun run build

      - name: Build unsigned Windows artifacts
-        run: bun run build:win
+        run: bun run build:win:unsigned

-      - name: Upload unsigned Windows artifact for SignPath
-        id: upload-unsigned-windows-artifact
+      - name: Upload Windows artifacts
        uses: actions/upload-artifact@v4
        with:
-          name: unsigned-windows
+          name: windows
          path: |
            release/*.exe
            release/*.zip
          if-no-files-found: error

-      - name: Submit Windows signing request (attempt 1)
-        id: signpath-sign-attempt-1
-        continue-on-error: true
-        uses: signpath/github-action-submit-signing-request@v2
-        with:
-          api-token: ${{ secrets.SIGNPATH_API_TOKEN }}
-          organization-id: ${{ secrets.SIGNPATH_ORGANIZATION_ID }}
-          project-slug: ${{ secrets.SIGNPATH_PROJECT_SLUG }}
-          signing-policy-slug: ${{ secrets.SIGNPATH_SIGNING_POLICY_SLUG }}
-          artifact-configuration-slug: ${{ secrets.SIGNPATH_ARTIFACT_CONFIGURATION_SLUG }}
-          github-artifact-id: ${{ steps.upload-unsigned-windows-artifact.outputs.artifact-id }}
-          wait-for-completion: true
-          output-artifact-directory: signed-windows-attempt-1
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Submit Windows signing request (attempt 2)
-        id: signpath-sign-attempt-2
-        if: steps.signpath-sign-attempt-1.outcome == 'failure'
-        continue-on-error: true
-        uses: signpath/github-action-submit-signing-request@v2
-        with:
-          api-token: ${{ secrets.SIGNPATH_API_TOKEN }}
-          organization-id: ${{ secrets.SIGNPATH_ORGANIZATION_ID }}
-          project-slug: ${{ secrets.SIGNPATH_PROJECT_SLUG }}
-          signing-policy-slug: ${{ secrets.SIGNPATH_SIGNING_POLICY_SLUG }}
-          artifact-configuration-slug: ${{ secrets.SIGNPATH_ARTIFACT_CONFIGURATION_SLUG }}
-          github-artifact-id: ${{ steps.upload-unsigned-windows-artifact.outputs.artifact-id }}
-          wait-for-completion: true
-          output-artifact-directory: signed-windows-attempt-2
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Submit Windows signing request (attempt 3)
-        id: signpath-sign-attempt-3
-        if: steps.signpath-sign-attempt-1.outcome == 'failure' && steps.signpath-sign-attempt-2.outcome == 'failure'
-        continue-on-error: true
-        uses: signpath/github-action-submit-signing-request@v2
-        with:
-          api-token: ${{ secrets.SIGNPATH_API_TOKEN }}
-          organization-id: ${{ secrets.SIGNPATH_ORGANIZATION_ID }}
-          project-slug: ${{ secrets.SIGNPATH_PROJECT_SLUG }}
-          signing-policy-slug: ${{ secrets.SIGNPATH_SIGNING_POLICY_SLUG }}
-          artifact-configuration-slug: ${{ secrets.SIGNPATH_ARTIFACT_CONFIGURATION_SLUG }}
-          github-artifact-id: ${{ steps.upload-unsigned-windows-artifact.outputs.artifact-id }}
-          wait-for-completion: true
-          output-artifact-directory: signed-windows-attempt-3
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Fail when all SignPath signing attempts fail
-        if: steps.signpath-sign-attempt-1.outcome == 'failure' && steps.signpath-sign-attempt-2.outcome == 'failure' && steps.signpath-sign-attempt-3.outcome == 'failure'
-        shell: bash
-        run: |
-          echo "All SignPath signing attempts failed; rerun the workflow when SignPath is healthy."
-          exit 1
-
-      - name: Upload signed Windows artifacts (attempt 1)
-        if: steps.signpath-sign-attempt-1.outcome == 'success'
-        uses: actions/upload-artifact@v4
-        with:
-          name: windows
-          path: |
-            signed-windows-attempt-1/*.exe
-            signed-windows-attempt-1/*.zip
-
-      - name: Upload signed Windows artifacts (attempt 2)
-        if: steps.signpath-sign-attempt-2.outcome == 'success'
-        uses: actions/upload-artifact@v4
-        with:
-          name: windows
-          path: |
-            signed-windows-attempt-2/*.exe
-            signed-windows-attempt-2/*.zip
-
-      - name: Upload signed Windows artifacts (attempt 3)
-        if: steps.signpath-sign-attempt-3.outcome == 'success'
-        uses: actions/upload-artifact@v4
-        with:
-          name: windows
-          path: |
-            signed-windows-attempt-3/*.exe
-            signed-windows-attempt-3/*.zip
-
  release:
    needs: [build-linux, build-macos, build-windows]
    runs-on: ubuntu-latest
+    permissions:
+      contents: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4
@@ -399,6 +309,9 @@ jobs:
      - name: Enforce generated launcher workflow
        run: bash scripts/verify-generated-launcher.sh

+      - name: Verify generated config examples
+        run: bun run verify:config-example
+
      - name: Package optional assets bundle
        run: |
          tar -czf "release/subminer-assets.tar.gz" \
@@ -419,7 +332,15 @@ jobs:

      - name: Get version from tag
        id: version
-        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+
+      - name: Build changelog artifacts for release
+        run: |
+          if find changes -maxdepth 1 -name '*.md' -not -name README.md -print -quit | grep -q .; then
+            bun run changelog:build --version "${{ steps.version.outputs.VERSION }}"
+          else
+            echo "No pending changelog fragments found."
+          fi

      - name: Verify changelog is ready for tagged release
        run: bun run changelog:check --version "${{ steps.version.outputs.VERSION }}"
@@ -464,3 +385,85 @@ jobs:
          for asset in "${artifacts[@]}"; do
            gh release upload "${{ steps.version.outputs.VERSION }}" "$asset" --clobber
          done
+
+  aur-publish:
+    needs: [release]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Get version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+
+      - name: Validate AUR SSH secret
+        env:
+          AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
+        run: |
+          set -euo pipefail
+          if [ -z "${AUR_SSH_PRIVATE_KEY}" ]; then
+            echo "Missing required secret: AUR_SSH_PRIVATE_KEY"
+            exit 1
+          fi
+
+      - name: Configure SSH for AUR
+        env:
+          AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
+        run: |
+          set -euo pipefail
+          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
+
+      - name: Clone AUR repo
+        env:
+          GIT_SSH_COMMAND: ssh -i ~/.ssh/aur -o IdentitiesOnly=yes
+        run: git clone ssh://aur@aur.archlinux.org/subminer-bin.git aur-subminer-bin
+
+      - name: Download release assets for AUR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          version="${{ steps.version.outputs.VERSION }}"
+          install -dm755 .tmp/aur-release-assets
+          gh release download "$version" \
+            --dir .tmp/aur-release-assets \
+            --pattern "SubMiner-${version#v}.AppImage" \
+            --pattern "subminer" \
+            --pattern "subminer-assets.tar.gz"
+
+      - name: Update AUR packaging metadata
+        run: |
+          set -euo pipefail
+          version_no_v="${{ steps.version.outputs.VERSION }}"
+          version_no_v="${version_no_v#v}"
+          cp packaging/aur/subminer-bin/PKGBUILD aur-subminer-bin/PKGBUILD
+          cp packaging/aur/subminer-bin/.SRCINFO aur-subminer-bin/.SRCINFO
+          bash scripts/update-aur-package.sh \
+            --pkg-dir aur-subminer-bin \
+            --version "${{ steps.version.outputs.VERSION }}" \
+            --appimage ".tmp/aur-release-assets/SubMiner-${version_no_v}.AppImage" \
+            --wrapper ".tmp/aur-release-assets/subminer" \
+            --assets ".tmp/aur-release-assets/subminer-assets.tar.gz"
+
+      - name: Commit and push AUR update
+        working-directory: aur-subminer-bin
+        env:
+          GIT_SSH_COMMAND: ssh -i ~/.ssh/aur -o IdentitiesOnly=yes
+        run: |
+          set -euo pipefail
+          if git diff --quiet -- PKGBUILD .SRCINFO; then
+            echo "AUR packaging already up to date."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add PKGBUILD .SRCINFO
+          git commit -m "Update to ${{ steps.version.outputs.VERSION }}"
+          git push origin HEAD:master
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,9 @@
 # Dependencies
 node_modules/

+# Superpowers brainstorming
+.superpowers/
+
 # Electron build output
 out/
 dist/
@@ -22,9 +25,7 @@ Thumbs.db
 .idea/
 *.swp
 *.swo
-**/CLAUDE.md
 environment.toml
-**/CLAUDE.md
 .env
 .vscode/*

@@ -35,5 +36,21 @@ docs/.vitepress/cache/
 docs/.vitepress/dist/
 tests/*
 .worktrees/
+.tmp/
 .codex/*
 .agents/*
+!.agents/skills/
+.agents/skills/*
+!.agents/skills/subminer-change-verification/
+!.agents/skills/subminer-scrum-master/
+.agents/skills/subminer-change-verification/*
+!.agents/skills/subminer-change-verification/SKILL.md
+!.agents/skills/subminer-change-verification/scripts/
+.agents/skills/subminer-change-verification/scripts/*
+!.agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh
+!.agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh
+.agents/skills/subminer-scrum-master/*
+!.agents/skills/subminer-scrum-master/SKILL.md
+favicon.png
+.claude/*
+!stats/public/favicon.png
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,60 +1,69 @@
 # AGENTS.MD

-## PR Feedback
+## Internal Docs

- Active PR: `gh pr view --json number,title,url --jq '"PR #\\(.number): \\(.title)\\n\\(.url)"'`.
- PR comments: `gh pr view …` + `gh api …/comments --paginate`.
- Replies: cite fix + file/line; resolve threads only after fix lands.
- When merging a PR: thank the contributor in `CHANGELOG.md`.
+Start here, then leave this file.

-## Changelog
+- Internal system of record: [`docs/README.md`](./docs/README.md)
+- Architecture map: [`docs/architecture/README.md`](./docs/architecture/README.md)
+- Workflow map: [`docs/workflow/README.md`](./docs/workflow/README.md)
+- Verification lanes: [`docs/workflow/verification.md`](./docs/workflow/verification.md)
+- Knowledge-base rules: [`docs/knowledge-base/README.md`](./docs/knowledge-base/README.md)
+- Release guide: [`docs/RELEASING.md`](./docs/RELEASING.md)

- User-visible PRs: add one fragment in `changes/*.md`.
- Fragment format:
-  `type: added|changed|fixed|docs|internal`
-  `area: <short-area>`
-  blank line
-  `- bullet`
- `changes/README.md`: instructions only; generator ignores it.
- No release-note entry wanted: use PR label `skip-changelog`.
- CI runs `bun run changelog:lint` + `bun run changelog:pr-check` on PRs.
- Release prep: `bun run changelog:build`, review `CHANGELOG.md` + `release/release-notes.md`, commit generated changelog + fragment deletions, then tag.
- Release CI expects committed changelog entry already present; do not rely on tag job to invent notes.
+`docs-site/` is user-facing. Do not treat it as the canonical internal source of truth.

-## Flow & Runtime
+## Quick Start

- Use repo’s package manager/runtime; no swaps w/o approval.
- Use Codex background for long jobs; tmux only for interactive/persistent (debugger/server).
+- Init workspace: `git submodule update --init --recursive`
+- Install deps: `make deps` or `bun install` plus `(cd vendor/texthooker-ui && bun install --frozen-lockfile)`
+- Fast dev loop: `make dev-watch`
+- Full local run: `bun run dev`
+- Verbose Electron debug: `electron . --start --dev --log-level debug`

 ## Build / Test

- Before handoff: run full gate (lint/typecheck/tests/docs).
- CI red: `gh run list/view`, rerun, fix, push, repeat til green.
- Keep it observable (logs, panes, tails, MCP/browser tools).
- Release: read `docs/RELEASING.md`
+- Runtime/package manager: Bun (`packageManager: bun@1.3.5`)
+- Default handoff gate:
+  `bun run typecheck`
+  `bun run test:fast`
+  `bun run test:env`
+  `bun run build`
+  `bun run test:smoke:dist`
+- If `docs-site/` changed, also run:
+  `bun run docs:test`
+  `bun run docs:build`
+- Prefer `make pretty` and `bun run format:check:src`

-## Git
+## Change-Specific Checks

- Safe by default: `git status/diff/log`. Push only when user asks.
- `git checkout` ok for PR review / explicit request.
- Branch changes require user consent.
- Destructive ops forbidden unless explicit (`reset --hard`, `clean`, `restore`, `rm`, …).
- Don’t delete/rename unexpected stuff; stop + ask.
- No repo-wide S/R scripts; keep edits small/reviewable.
- Avoid manual `git stash`; if Git auto-stashes during pull/rebase, that’s fine (hint, not hard guardrail).
- If user types a command (“pull and push”), that’s consent for that command.
- No amend unless asked.
- Big review: `git --no-pager diff --color=never`.
- Multi-agent: check `git status/diff` before edits; ship small commits.
+- Config/schema/defaults: `bun run test:config`; if template/defaults changed, `bun run generate:config-example`
+- Launcher/plugin: `bun run test:launcher` or `bun run test:env`
+- Runtime-compat / dist-sensitive: `bun run test:runtime:compat`
+- Docs-only: `bun run docs:test`, then `bun run docs:build`

-## Language/Stack Notes
+## Sensitive Files

- Swift: use workspace helper/daemon; validate `swift build` + tests; keep concurrency attrs right.
- TypeScript: use repo PM; keep files small; follow existing patterns.
+- 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

-## macOS Permissions / Signing (TCC)
+## Release / PR Notes

- Never re-sign / ad-hoc sign / change bundle ID as “debug” without explicit ok (can mess TCC).
+- User-visible PRs need one fragment in `changes/*.md`
+- CI enforces `bun run changelog:lint` and `bun run changelog:pr-check`
+- PR review helpers:
+  - `gh pr view --json number,title,url --jq '"PR #\\(.number): \\(.title)\\n\\(.url)"'`
+  - `gh api repos/:owner/:repo/pulls/<num>/comments --paginate`
+
+## Runtime Notes
+
+- Use Codex background for long jobs; tmux only when persistence/interaction is required
+- CI red: `gh run list/view`, rerun, fix, repeat until green
+- TypeScript: keep files small; follow existing patterns
+- Swift: use workspace helper/daemon; validate `swift build` + tests

 <!-- BACKLOG.MD MCP GUIDELINES START -->

--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,16 +1,232 @@
 # Changelog

+## v0.9.3 (2026-03-25)
+
+### Changed
+- Launcher: Moved YouTube primary subtitle language defaults to `youtube.primarySubLanguages`.
+- Launcher: Removed the placeholder YouTube subtitle retime step and now uses downloaded primary subtitle tracks directly, so there is no fake path rewrite before playback/sidebar loading.
+- YouTube: Removed the `src/core/services/youtube/retime` helper and its tests after retiring the internal retime strategy.
+- Docs: Clarified optional `alass` / `ffsubsync` subtitle-sync requirements and setup steps, including fallback behavior when sync tools are absent.
+- Launcher: Removed the old `youtubeSubgen.primarySubLanguages` config path from the generated config and docs.
+
+## v0.9.2 (2026-03-25)
+
+### Fixed
+- Overlay: Fixed overlay pointer tracking so Windows click-through toggles immediately when the cursor enters or leaves subtitle regions, without waiting for a later hover resync.
+- Overlay: Fixed Windows overlay window tracking on scaled displays by converting native tracked window bounds to Electron DIP coordinates before applying overlay bounds.
+- Launcher: Fixed Windows direct `--youtube-play` startup so MPV boots reliably, stays paused until the app-owned subtitle flow is ready, and reuses an already-running SubMiner instance when available.
+- Launcher: Fixed standalone Windows `--youtube-play` sessions so closing MPV fully exits SubMiner instead of leaving hidden overlay windows or a background process behind.
+- Overlay: Fixed `subminer <youtube-url>` on Linux so the YouTube playback flow waits for Yomitan to load before creating the overlay window, avoiding the broken lookup popup state that previously required a manual overlay refresh.
+
+## v0.9.1 (2026-03-24)
+
+### Changed
+- Release: Reduced packaged release size by excluding duplicate `extraResources` payload and pruning docs, tests, sourcemaps, and other source-only files from Electron bundles.
+
+### Fixed
+- Overlay: Restored controller navigation and lookup/mining controls while the subtitle sidebar is open, while keeping true modal dialogs blocking controller actions.
+- Tokenizer: Fixed subtitle annotation clearing so explanatory contrast endings like `んですけど` are excluded consistently across the shared tokenizer filter and annotation stage.
+
+## v0.9.0 (2026-03-23)
+
+### Added
+- Docs: Added a new WebSocket / Texthooker API and integration guide covering WebSocket payloads, custom client patterns, mpv plugin automation, and webhook-style relay examples. Linked from configuration and mining workflow docs for easier discovery.
+
+### Changed
+- Launcher: Added an app-owned YouTube subtitle flow that pauses mpv, uses absPlayer-style YouTube timedtext parsing/conversion to download subtitle tracks, and injects them as external files before playback resumes.
+- Launcher: Changed YouTube subtitle startup to auto-load the best-available primary and secondary subtitle tracks at launch instead of forcing the picker modal first. Secondary subtitle failures no longer block playback resume.
+- Launcher: Added `Ctrl+Alt+C` as the default keybinding to manually open the YouTube subtitle picker during active YouTube playback.
+- Launcher: Added yt-dlp metadata probing so YouTube playback and immersion tracking record canonical video title and channel metadata.
+- Launcher: Stopped forcing `--ytdl-raw-options=` before user-provided mpv options so existing YouTube cookie integrations in user `--args` are no longer clobbered.
+- Launcher: Disabled mpv native YouTube subtitle auto-loading for the app-owned flow so injected external subtitle files remain authoritative.
+- Launcher: Added OSD status messages for YouTube playback startup, subtitle acquisition, and subtitle loading so the flow stays visible before and during the picker.
+- Subtitle Sidebar: Added startup-auto-open controls and resume positioning improvements so the sidebar jumps directly to the first resolved active cue.
+- Subtitle Sidebar: Improved subtitle prefetch and embedded overlay passthrough sync so sidebar and overlay subtitle states stay consistent across media transitions.
+- Subtitle Sidebar: Updated scroll handling, embedded layout styling, and active-cue visual behavior.
+- Stats: Stats Library tab now displays YouTube video title, channel name, and channel thumbnail for YouTube media entries, with retry logic to fill in metadata that arrives after initial load.
+
+### Fixed
+- Launcher: Fixed Anki media mining for mpv YouTube streams by unwrapping the stream URL so audio and screenshot capture work correctly for YouTube playback sessions.
+- Immersion: Fixed YouTube media path handling in the immersion runtime and tracking so YouTube sessions record correct media references, AniList guessing skips YouTube URLs, and post-watch state transitions do not fire for YouTube media.
+- Launcher: Fixed startup-launched YouTube playback so primary subtitle overlay updates continue after auto-load completes.
+- Launcher: Fixed auto-loaded YouTube primary subtitles so parsed cues appear in the subtitle sidebar without needing a manual picker retry.
+- Launcher: Fixed the YouTube picker to guard against duplicate subtitle submissions and tightened YouTube URL detection so follow-up runtime flows only treat real YouTube hosts as YouTube playback.
+- Launcher: Fixed primary subtitle failure notifications being shown while app-owned YouTube subtitle probing and downloads are still in flight.
+- Launcher: Preserved existing authoritative YouTube subtitle tracks when available; downloaded tracks are used only to fill missing sides, and native mpv secondary subtitle rendering is hidden so the overlay remains the sole secondary display.
+
+## v0.8.0 (2026-03-22)
+
+### Added
+- Overlay: Added the subtitle sidebar feature with a new `subtitleSidebar` configuration surface and rendered sidebar modal with cue list rendering, click-to-seek, active-cue highlighting, and embedded layout support.
+- IPC: Added sidebar snapshot plumbing between renderer and main process for overlay/sidebar synchronization.
+
+### Changed
+- Config: Added hot-reloadable sidebar options for enablement, layout, visibility, typography, opacity, sizing, and interaction behavior (`autoOpen`, `pauseOnHover`, `autoScroll`, toggle key).
+- Docs: Added full `subtitleSidebar` documentation coverage, including sample config, option table, and toggle shortcut notes.
+- Runtime: Improved subtitle prefetch/rendering flow so sidebar and overlay subtitle states stay in sync across media transitions.
+
+### Fixed
+- Overlay: Kept sidebar cue tracking stable across playback transitions and timing edge cases.
+- Overlay: Improved sidebar resume/start behavior to jump directly to the first resolved active cue.
+- Overlay: Stopped stale subtitle refreshes from regressing active-cue and text state.
+
+## v0.7.0 (2026-03-19)
+
+### Added
+- Immersion: Added Mine Word, Mine Sentence, and Mine Audio buttons to word detail example lines in the stats dashboard.
+- Immersion: Mine Word creates a full Yomitan card (definition, reading, pitch accent) via the hidden search page bridge, then enriches with sentence audio, screenshot, and metadata extracted from the source video.
+- Immersion: Mine Sentence and Mine Audio create cards directly with appropriate Lapis/Kiku flags, sentence highlighting, and media from the source file.
+- Immersion: Media generation (audio + image/AVIF) runs in parallel and respects all AnkiConnect config options.
+- Immersion: Added word exclusion list to the Vocabulary tab with localStorage persistence and a management modal.
+- Immersion: Fixed truncated readings in the frequency rank table (e.g. お前 now shows おまえ instead of まえ).
+- Immersion: Clicking a bar in the Top Repeated Words chart now opens the word detail panel.
+- Immersion: Secondary subtitle text is now stored alongside primary subtitle lines for use as translation when mining cards from the stats page.
+- Stats: Added `subminer stats -b` to start or reuse a dedicated background stats server without blocking normal SubMiner instances.
+- Stats: Added `subminer stats -s` to stop the dedicated background stats server without closing browser tabs.
+- Stats: Stats server startup now reuses a running background stats daemon instead of trying to bind a second local server in another SubMiner instance.
+- Launcher: Added launcher passthrough for `-a/--args` so mpv receives raw extra launch flags (`--fs`, `--ytdl-format`, custom audio/video settings, etc.) from the `subminer` command.
+- Launcher: Added `subminer stats` to launch the local stats dashboard, force-start the stats server on demand, and open the dashboard in your browser.
+- Launcher: Added `subminer stats cleanup` to backfill vocabulary metadata and prune stale or excluded immersion rows on demand.
+- Launcher: Added `stats.autoOpenBrowser` so browser launch after `subminer stats` can be enabled or disabled explicitly.
+- Immersion: Added a local stats dashboard for immersion tracking with Overview, Anime, Trends, Vocabulary, and Sessions views.
+- Immersion: Added anime progress, episode completion, Anki card links, and occurrence drill-down across the stats dashboard.
+- Immersion: Added richer session timelines with new-word activity, cumulative totals, and pause/seek/card event markers.
+- Immersion: Added completed-episodes and completed-anime totals to the Overview tracking snapshot.
+
+### Changed
+- Anki: Changed known-word cache settings to live under `ankiConnect.knownWords` instead of mixing them into `ankiConnect.nPlusOne`.
+- Anki: Kept legacy `ankiConnect.nPlusOne` known-word keys and older `ankiConnect.behavior.nPlusOne*` keys as deprecated compatibility fallbacks.
+- Stats: Added session deletion to the Sessions tab with the same confirmation prompt used by anime episode/session deletes, and removed all associated session rows from the stats database.
+- Immersion: Kept immersion tracking history by default while preserving daily/monthly rollup maintenance.
+- Immersion: Added exact lifetime summary reads for overview/anime/media stats so dashboard totals no longer depend on rescanning raw telemetry.
+- Immersion: Reduced tracker storage overhead by removing duplicated subtitle text from subtitle-line event payloads.
+- Immersion: Deduplicated episode cover-art blobs through a shared blob store and updated cover-art reads/writes to resolve shared images correctly.
+- Immersion: Added indexes for large-history session, telemetry, vocabulary, kanji, and cover-art queries to keep dashboard reads fast as the SQLite database grows.
+- Immersion: Renamed the stats dashboard's Anime tab to Library so the media browser label matches non-anime sources like YouTube and other yt-dlp-backed content.
+- Anilist: Standardized episode completion threshold by introducing `DEFAULT_MIN_WATCH_RATIO` and using it for both local watched state transitions and AniList post-watch progress updates.
+- Anilist: Episode auto-marking now uses the same threshold as AniList (`85%`), removing divergent completion behavior.
+- Overlay: Excluded interjections and sound-effect tokens from subtitle annotation styling so they no longer inherit misleading lexical highlight treatment while still remaining visible and hoverable as plain subtitle tokens.
+- Overlay: Expanded subtitle annotation noise filtering to also strip annotation metadata from standalone grammar-only helper tokens such as particles, auxiliaries, adnominals, common explanatory endings like `んです` / `のだ`, and merged trailing quote-particle forms like `...って` while keeping them tokenized for hover lookup.
+
+### Fixed
+- Launcher: Fixed mpv Lua plugin binary auto-detection on Linux to also search `/usr/bin/subminer` and `/usr/local/bin/subminer` (lowercase), matching the conventional Unix wrapper name used by packaged installs such as the AUR package.
+- Stats: Fixed the in-app stats overlay so it connects to the configured `stats.serverPort` instead of falling back to the default port.
+- Overlay: Fixed subtitle frequency tagging for merged lookup-backed tokens like `陰に` by falling back to exact surface-form Yomitan frequencies when the normalized headword lookup misses.
+- Overlay: Fixed MeCab merged-token position mapping across line breaks so merged content-plus-particle tokens like `陰に` keep their matched Yomitan frequency instead of inheriting shifted POS tags.
+- Overlay: Fixed grouped frequency parsing in both Yomitan and fallback frequency-dictionary lookups so display values like `118,121` use the leading rank instead of collapsing the rank and occurrence count into `118121`.
+- Overlay: Fixed frequency-rank ingestion to ignore Yomitan dictionaries explicitly marked `occurrence-based`, so raw occurrence counts are no longer treated as subtitle rank values.
+- Overlay: Fixed inflected headword frequency tagging to prefer ranks from the selected Yomitan `termsFind` popup entry itself, ordered by configured dictionary priority, so forms like `潜み` use primary-dictionary ranks like `4073` before falling back to lower-priority raw lemma metadata such as `CC100`.
+- Overlay: Fixed annotation-stage frequency filtering so exact kanji noun tokens like `者` keep their matched rank even when MeCab labels them `名詞/非自立`, instead of dropping the highlight after scan-time frequency lookup succeeds.
+- Anki: Fixed repeated character-dictionary startup work by scheduling auto-sync only from mpv media-path changes instead of also re-triggering it from connection and media-title events for the same title.
+- Overlay: Fixed macOS fullscreen overlay stability by keeping the passive visible overlay from stealing focus, re-raising the overlay window when reasserting its macOS topmost level, and tolerating one transient macOS tracker/helper miss before hiding the overlay.
+- Overlay: Kept subtitle tokenization warmup one-shot for the lifetime of the app so later fullscreen/media churn on macOS does not replay the startup warmup gate after the first file is ready.
+- Overlay: Added a bounded macOS tracker loss-grace window so fullscreen enter/leave transitions do not immediately hide and reload the overlay when the helper briefly loses the mpv window.
+- Overlay: Skipped subtitle/tokenization refresh invalidation on character-dictionary auto-sync completion when the dictionary was already current, preventing startup flash/reload loops on unchanged media.
+- Stats: Fixed session stats so known-word counts track real known-word occurrences without collapsing subtitle-line gaps.
+- Stats: Fixed session word totals in session-facing stats views to prefer token counts when available, preventing known words from exceeding total words in the session chart.
+- Stats: Fixed the stats Vocabulary tab blank-screen regression caused by a hook-order crash after vocabulary data finished loading.
+- Anki: Fixed card-mine OSD feedback so the final mine result stops the Anki spinner first, then shows a single-line `✓`/`x` status without being overwritten by a later spinner tick.
+- Stats: Removed the misleading `New words` series from expanded session charts; session detail now shows only the real total-word and known-word lines.
+- Stats: Restored the cross-anime word table behavior in stats vocabulary surfaces so shared vocabulary entries no longer disappear or merge incorrectly across related media.
+- Stats: `subminer stats -b` now runs as a standalone background stats daemon instead of reusing the main SubMiner app process, so the overlay app can still be launched separately for normal video watching.
+- Stats: Dashboard word mining still works against the background daemon by using a short-lived hidden helper for the Yomitan add-note flow.
+- Stats: Load full session timelines by default in stats session detail views so long sessions preserve complete telemetry history instead of being truncated by a fixed sample limit.
+- Stats: Replaced heuristic stats word counts with Yomitan token counts, so session, media, anime, and trend subtitle totals now come directly from parsed subtitle tokens.
+- Stats: Updated stats UI labels and lookup-rate copy to refer to tokens instead of words where those counts are shown.
+- Overlay: Reduced repeated `Overlay loading...` popups on macOS when fullscreen tracker flaps briefly hide and recover the visible overlay.
+- Stats: Scaled expanded session-detail known-word charts to the session's actual percentage range so small changes no longer render as a nearly flat line.
+- Jlpt: Reduced JLPT dictionary startup log noise by summarizing duplicate surface-form collisions instead of logging one line per duplicate entry.
+
+## v0.6.5 (2026-03-15)
+
+### Internal
+- Release: Seed the AUR checkout with the repo `.SRCINFO` template before rewriting metadata so tagged releases do not depend on prior AUR state.
+
+## v0.6.4 (2026-03-15)
+
+### Internal
+- Release: Reworked AUR metadata generation to update `.SRCINFO` directly instead of depending on runner `makepkg`, fixing tagged release publishing for `subminer-bin`.
+
+## v0.6.3 (2026-03-15)
+
+### Changed
+- Overlay: Expanded the `Alt+C` controller modal into an inline config/remap flow with preferred-controller saving and per-action learn mode for buttons, triggers, and stick directions.
+
+### Internal
+- Workflow: Hardened the `subminer-scrum-master` skill to explicitly answer whether docs updates and changelog fragments are required before handoff.
+- Release: Automate `subminer-bin` AUR package updates from the tagged release workflow.
+
+## v0.6.2 (2026-03-12)
+
+### Changed
+- Config: Added `yomitan.externalProfilePath` to reuse another Electron app's Yomitan profile in read-only mode.
+- Config: SubMiner now reuses external Yomitan dictionaries/settings without writing back to that profile.
+- Config: Launcher-managed playback now respects `yomitan.externalProfilePath` and no longer forces first-run setup when external Yomitan is configured.
+- Config: SubMiner now seeds `config.jsonc` even when the default config directory already exists.
+- Config: First-run setup now allows zero internal dictionaries when `yomitan.externalProfilePath` is configured, and falls back to requiring at least one internal dictionary if that external profile is later removed.
+
+## v0.6.1 (2026-03-12)
+
+### Added
+- Overlay: Added Chrome Gamepad API controller support for keyboard-only overlay mode, including configurable logical bindings for lookup, mining, popup navigation, Yomitan audio, mpv pause, d-pad fallback navigation, and slower smooth popup scrolling.
+- Overlay: Added `Alt+C` controller selection and `Alt+Shift+C` controller debug modals, with preferred controller persistence and live raw input inspection.
+- Overlay: Added a transient in-overlay controller-detected indicator when a controller is first found.
+- Overlay: Fixed stale keyboard-only token highlight cleanup when keyboard-only mode turns off or the Yomitan popup closes.
+
+### Docs
+- Install: Added Arch Linux AUR install docs for `subminer-bin` in the README and installation guide.
+
+### Internal
+- Config: add an enforced `verify:config-example` gate so checked-in example config artifacts cannot drift silently
+- Release: Fixed the release workflow token permissions so tagged builds can download `oven-sh/setup-bun` and publish artifacts again.
+
+## v0.5.6 (2026-03-10)
+
+### Fixed
+
+- Dictionary: Persist merged character-dictionary MRU state as soon as a new retained set is built so revisits do not get dropped if later Yomitan import work fails, and skip merged dictionary rebuilds for reorder-only revisits when the retained anime set itself has not changed.
+- Startup: Fixed early Electron startup writing config and user data under a lowercase `~/.config/subminer` path instead of the canonical `~/.config/SubMiner` directory.
+- Overlay: Kept JLPT underline colors stable during Yomitan hover and selection states, even when tokens also use known, N+1, name-match, or frequency styling.
+
+## v0.5.5 (2026-03-09)
+
+### Changed
+
+- Overlay: Added `f` as the default overlay fullscreen toggle and changed the default AniSkip intro-jump key to `Tab`.
+- Dictionary: Aligned AniList character dictionary generation more closely with the upstream reference by preserving duplicate shared names across characters, skipping characters without native Japanese names, restoring richer character info fields, and using upstream-style role mapping plus hint-aware kanji readings.
+- Startup: Ordered startup OSD messages so tokenization loads first, annotation loading appears next if still pending, and character dictionary sync progress waits until annotation loading finishes.
+- Dictionary: Added a visible startup OSD step for merged character-dictionary building so long rebuilds show progress before the later import/upload phase.
+
+### Fixed
+
+- Dictionary: Fixed AniList media guessing for character dictionary auto-sync by using filename-only `guessit` input and preserving multi-part guessit titles instead of truncating them to the first segment.
+- Dictionary: Refresh the current subtitle after character dictionary auto-sync completes so newly imported character names highlight on the active line instead of waiting for the next subtitle change.
+- Dictionary: Show character dictionary auto-sync progress on the mpv OSD without sending desktop notifications.
+- Dictionary: Keep character dictionary auto-sync non-blocking during startup by letting snapshot/build work run in parallel and delaying only the Yomitan import/settings phase until current-media tokenization is already ready.
+- Overlay: Fixed visible overlay keyboard handling so pressing `Tab` still reaches mpv and triggers the default AniSkip skip-intro binding while the overlay has focus.
+- Plugin: Fix Windows mpv plugin binary override lookup so `SUBMINER_BINARY_PATH` still resolves to `SubMiner.exe` when no AppImage override is set.
+
+## v0.5.3 (2026-03-09)
+
+### Changed
+
+- Release: Publish unsigned Windows `.exe` and `.zip` artifacts directly from release CI instead of routing them through SignPath.
+- Release: Added `bun run build:win:unsigned` for explicit local unsigned Windows packaging.
+
 ## v0.5.2 (2026-03-09)

 ### Internal
+
 - Release: Pinned the Windows SignPath submission workflow to an explicit artifact-configuration slug instead of relying on the SignPath project's default configuration.

 ## v0.5.1 (2026-03-09)

 ### Changed
+
 - Launcher: Removed the YouTube subtitle generation mode switch so YouTube playback always preloads subtitles before mpv starts.

 ### Fixed
+
 - Launcher: Hardened YouTube AI subtitle fixing so fenced SRT output and text-only one-cue-per-block responses can still be applied without losing original cue timing.
 - Launcher: Skipped AniSkip lookup during URL playback and YouTube subtitle-preload playback, limiting AniSkip to local file targets where it can actually resolve anime metadata.
 - Launcher: Keep the background SubMiner process running after a launcher-managed mpv session exits so the next mpv instance can reconnect without restarting the app.
@@ -18,6 +234,7 @@
 - Windows: Acquire the app single-instance lock earlier so Windows overlay/video launches reuse the running background SubMiner process instead of booting a second full app and repeating startup warmups.

 ## v0.3.0 (2026-03-05)
+
 - Added keyboard-driven Yomitan navigation and popup controls, including optional auto-pause.
 - Added subtitle/jump keyboard handling fixes for smoother subtitle playback control.
 - Improved Anki/Yomitan reliability with stronger Yomitan proxy syncing and safer extension refresh logic.
@@ -28,6 +245,7 @@
 - Removed docs Plausible integration and cleaned associated tracker settings.

 ## v0.2.3 (2026-03-02)
+
 - Added performance and tokenization optimizations (faster warmup, persistent MeCab usage, reduced enrichment lookups).
 - Added subtitle controls for no-jump delay shifts.
 - Improved subtitle highlight logic with priority and reliability fixes.
@@ -36,30 +254,36 @@
 - Updated startup flow to load dictionaries asynchronously and unblock first tokenization sooner.

 ## v0.2.2 (2026-03-01)
+
 - Improved subtitle highlighting reliability for frequency modes.
 - Fixed Jellyfin misc info formatting cleanup.
 - Version bump maintenance for 0.2.2.

 ## v0.2.1 (2026-03-01)
+
 - Delivered Jellyfin and Subsync fixes from release patch cycle.
 - Version bump maintenance for 0.2.1.

 ## v0.2.0 (2026-03-01)
+
 - Added task-related release work for the overlay 2.0 cycle.
 - Introduced Overlay 2.0.
 - Improved release automation reliability.

 ## v0.1.2 (2026-02-24)
+
 - Added encrypted AniList token handling and default GNOME keyring support.
 - Added launcher passthrough for password-store flows (Jellyfin path).
 - Updated docs for auth and integration behavior.
 - Version bump maintenance for 0.1.2.

 ## v0.1.1 (2026-02-23)
+
 - Fixed overlay modal focus handling (`grab input`) behavior.
 - Version bump maintenance for 0.1.1.

 ## v0.1.0 (2026-02-23)
+
 - Bootstrapped Electron runtime, services, and composition model.
 - Added runtime asset packaging and dependency vendoring.
 - Added project docs baseline, setup guides, architecture notes, and submodule/runtime assets.
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
--- a/11
+++ b/11
@@ -1,4 +1,4 @@
-.PHONY: help deps build build-launcher install build-linux build-macos build-macos-unsigned clean install-linux install-macos install-windows install-plugin uninstall uninstall-linux uninstall-macos uninstall-windows print-dirs pretty ensure-bun generate-config generate-example-config dev-start dev-start-macos dev-watch dev-watch-macos dev-toggle dev-stop
+.PHONY: help deps build build-launcher install build-linux build-macos build-macos-unsigned clean install-linux install-macos install-windows install-plugin uninstall uninstall-linux uninstall-macos uninstall-windows print-dirs pretty lint ensure-bun generate-config generate-example-config dev-start dev-start-macos dev-watch dev-watch-macos dev-toggle dev-stop

 APP_NAME := subminer
 THEME_SOURCE := assets/themes/subminer.rasi
@@ -69,11 +69,12 @@ help:
 		"  generate-config  Generate ~/.config/SubMiner/config.jsonc from centralized defaults" \
 		"" \
 		"Other targets:" \
-		"  deps             Install JS dependencies (root + texthooker-ui)" \
+		"  deps             Install JS dependencies (root + stats + texthooker-ui)" \
 		"  uninstall-linux  Remove Linux install artifacts" \
 		"  uninstall-macos  Remove macOS install artifacts" \
 		"  uninstall-windows Remove Windows mpv plugin artifacts" \
 		"  print-dirs       Show resolved install locations" \
+		"  lint             Lint stats (format check)" \
 		"" \
 		"Variables:" \
 		"  PREFIX=...        Override wrapper install prefix (default: $$HOME/.local)" \
@@ -104,6 +105,7 @@ print-dirs:
 deps:
 	@$(MAKE) --no-print-directory ensure-bun
 	@bun install
+	@cd stats && bun install --frozen-lockfile
 	@cd vendor/texthooker-ui && bun install --frozen-lockfile

 ensure-bun:
@@ -111,6 +113,10 @@ ensure-bun:

 pretty: ensure-bun
 	@bun run format:src
+	@bun run format:stats
+
+lint: ensure-bun
+	@bun run lint:stats

 build:
 	@printf '%s\n' "[INFO] Detected platform: $(PLATFORM)"
@@ -165,7 +171,6 @@ generate-config: ensure-bun
 	@bun run electron . --generate-config

 generate-example-config: ensure-bun
-	@bun run build
 	@bun run generate:config-example

 dev-start: ensure-bun
--- a/README.md
+++ b/README.md
@@ -1,133 +1,258 @@
 <div align="center">
-  <img src="assets/SubMiner.png" width="169" alt="SubMiner logo">
-  <h1>SubMiner</h1>
-  <strong>Look up words, mine to Anki, and enrich cards with context — without leaving mpv.</strong>
-  <br /><br />

-[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
-[![Linux](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-informational)]()
-[![Docs](https://img.shields.io/badge/docs-docs.subminer.moe-blueviolet)](https://docs.subminer.moe)
+<img src="assets/SubMiner.png" width="160" alt="SubMiner logo">
+
+# SubMiner
+
+## Turn mpv into a sentence-mining workstation.
+
+Look up words with Yomitan, export to Anki in one key, track your immersion — all without leaving mpv.
+
+[![License: GPL v3](https://img.shields.io/badge/license-GPLv3-1a1a2e?style=flat-square)](https://www.gnu.org/licenses/gpl-3.0)
+[![Platform](https://img.shields.io/badge/platform-Linux%20·%20macOS%20·%20Windows-1a1a2e?style=flat-square)](https://github.com/ksyasuda/SubMiner)
+[![Docs](https://img.shields.io/badge/docs-docs.subminer.moe-e6a817?style=flat-square)](https://docs.subminer.moe)
+[![AUR](https://img.shields.io/aur/version/subminer-bin?style=flat-square&color=1a1a2e)](https://aur.archlinux.org/packages/subminer-bin)
+
+[![SubMiner demo](./assets/minecard.webp)](./assets/minecard.mp4)

 </div>

-<br />
+## How It Works
+
+SubMiner runs as an invisible Electron overlay on top of mpv. Subtitles render as an interactive layer. Move your cursor over any word and trigger a [Yomitan](https://github.com/yomidevs/yomitan) lookup. Press one key to snapshot the sentence, audio, and screenshot into Anki via AnkiConnect.
+
+## Features
+
+### Dictionary Lookups
+
+Yomitan runs inside the overlay. Trigger a lookup on any word for full dictionary popups — definitions, pitch accent, frequency data — without ever leaving mpv.

 <div align="center">
-
-[![SubMiner demo (Animated preview)](./assets/minecard.webp)](./assets/minecard.mp4)
-
+  <img src="docs-site/public/screenshots/yomitan-lookup.png" width="800" alt="Yomitan dictionary popup over annotated subtitles in mpv">
 </div>

-<br />
+<br>

-Initial packaged Windows support is now available alongside the existing Linux and macOS builds.
+### Instant Anki Mining

-## What it does
+Create an Anki card with the sentence, audio clip, screenshot, and machine translation from the exact playback moment with one key press, click, or controller input.

-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="Anki card created from SubMiner with sentence, audio, and screenshot">
+</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
+
+Real-time subtitle annotations with frequency highlighting, JLPT tags, N+1 targeting, and a character name dictionary. Known words fade back; new words stand out. Grammar-only tokens render as plain text so you focus on what matters.
+
+<div align="center">
+  <img src="docs-site/public/screenshots/annotations.png" width="800" alt="Annotated subtitles with frequency coloring, JLPT underlines, and N+1 targets">
+</div>
+
+<br>
+
+### Immersion Dashboard
+
+Local stats dashboard — watch time, anime library, vocabulary growth, mining throughput, session history, and trends. All stored locally, no third-party tracking.
+
+<div align="center">
+  <img src="docs-site/public/screenshots/stats-overview.png" width="800" alt="Stats dashboard showing watch time, cards mined, streaks, and tracking data">
+</div>
+
+<br>
+
+### Integrations
+
+<table>
+  <tr>
+    <td><b>YouTube</b></td>
+    <td>Auto-loaded yt-dlp subtitle tracks at startup with a manual overlay picker on demand (<code>Ctrl+Alt+C</code>)</td>
+  </tr>
+  <tr>
+    <td><b>AniList</b></td>
+    <td>Automatic episode tracking and progress sync</td>
+  </tr>
+  <tr>
+    <td><b>Jellyfin</b></td>
+    <td>Browse and launch media from your Jellyfin server</td>
+  </tr>
+  <tr>
+    <td><b>Jimaku</b></td>
+    <td>Search and download Japanese subtitles</td>
+  </tr>
+  <tr>
+    <td><b>alass / ffsubsync</b></td>
+    <td>Automatic subtitle retiming — requires <code>alass</code> or <code>ffsubsync</code> on your <code>PATH</code> (optional; subtitle syncing is disabled without them)</td>
+  </tr>
+  <tr>
+    <td><b>WebSocket</b></td>
+    <td>Annotated subtitle feed for external clients (texthooker pages, custom tools)</td>
+  </tr>
+</table>
+
+<div align="center">
+  <img src="docs-site/public/screenshots/texthooker.png" width="800" alt="Texthooker page receiving annotated subtitle lines via WebSocket">
+</div>
+
+<br>
+
+---
+
+## Requirements
+
+|                | Required                                | Optional                               |
+| -------------- | --------------------------------------- | -------------------------------------- |
+| **Player**     | [`mpv`](https://mpv.io) with IPC socket | —                                      |
+| **Processing** | `ffmpeg`, `mecab` + `mecab-ipadic`      | `guessit` (AniSkip), `alass` / `ffsubsync` (subtitle sync) |
+| **Media**      | —                                       | `yt-dlp`, `chafa`, `ffmpegthumbnailer` |
+| **Selection**  | —                                       | `fzf` / `rofi`                         |
+
+> [!NOTE]
+> [`bun`](https://bun.sh) is required if building from source or using the CLI wrapper: `subminer`. Pre-built releases (AppImage, DMG, installer) do not require it.
+
+**Platform-specific:**
+
+| Linux                               | macOS                    | Windows       |
+| ----------------------------------- | ------------------------ | ------------- |
+| `hyprctl` or `xdotool` + `xwininfo` | Accessibility permission | No extra deps |
+
+<details>
+<summary><b>Arch Linux</b></summary>
+
+```bash
+paru -S --needed mpv ffmpeg mecab-git mecab-ipadic
+# Optional
+paru -S --needed yt-dlp fzf rofi chafa ffmpegthumbnailer xdotool xorg-xwininfo
+# Optional: subtitle sync (install at least one for subtitle syncing to work)
+paru -S --needed alass python-ffsubsync
+# X11 / XWAYLAND
+paru -S --needed xdotool xorg-xwininfo
+```
+
+</details>
+
+<details>
+<summary><b>macOS</b></summary>
+
+```bash
+brew install mpv ffmpeg mecab mecab-ipadic
+# Optional
+brew install yt-dlp fzf rofi chafa ffmpegthumbnailer
+# Optional: subtitle sync (install at least one for subtitle syncing to work)
+brew install alass
+pip install ffsubsync
+```
+
+Grant Accessibility permission to SubMiner in **System Settings > Privacy & Security > Accessibility**.
+
+</details>
+
+<details>
+<summary><b>Windows</b></summary>
+
+Install [`mpv`](https://mpv.io/installation/) and [`ffmpeg`](https://ffmpeg.org/download.html) and ensure both are on your `PATH`.
+
+For MeCab, install [MeCab for Windows](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary.
+
+</details>
+
+---
+
+## Quick Start

 ### 1. Install

-**Linux (AppImage):**
+<details>
+<summary><b>Arch Linux (AUR)</b></summary>

 ```bash
-wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppImage -O ~/.local/bin/SubMiner.AppImage
-chmod +x ~/.local/bin/SubMiner.AppImage
-wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer
-chmod +x ~/.local/bin/subminer
+paru -S subminer-bin
+```

+Or manually:
+
+```bash
+git clone https://aur.archlinux.org/subminer-bin.git && cd subminer-bin && makepkg -si
+```
+
+</details>
+
+<details>
+<summary><b>Linux (AppImage)</b></summary>
+
+```bash
+mkdir -p ~/.local/bin
+wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppImage -O ~/.local/bin/SubMiner.AppImage \
+	&& chmod +x ~/.local/bin/SubMiner.AppImage
+wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer \
+	&& chmod +x ~/.local/bin/subminer
 ```

 > [!NOTE]
 > The `subminer` wrapper uses a [Bun](https://bun.sh) shebang. Make sure `bun` is on your `PATH`.

-**macOS (DMG/ZIP):** download the latest packaged build from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest) and drag `SubMiner.app` into `/Applications`.
+</details>

-**Windows (Installer/ZIP):** download the latest `SubMiner-<version>.exe` installer or portable `.zip` from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). Keep `mpv` installed and available on `PATH`.
+<details>
+<summary><b>macOS</b></summary>

-**From source** — initialize submodules first (`git submodule update --init --recursive`). Bundled Yomitan is built from the `vendor/subminer-yomitan` submodule into `build/yomitan` during `bun run build`, so source builds only need Bun for the JS toolchain. Packaged macOS and Windows installs do not require Bun. Windows installer builds go through `electron-builder`; its bundled `app-builder-lib` NSIS templates already use the third-party `WinShell` plugin for shortcut AppUserModelID assignment, and the `WinShell.dll` binary is supplied by electron-builder's cached `nsis-resources` bundle, so `bun run build:win` does not need a separate repo-local plugin install step. Full install guide: [docs.subminer.moe/installation#from-source](https://docs.subminer.moe/installation#from-source).
+Download the latest DMG or ZIP from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest) and drag `SubMiner.app` into `/Applications`.

-### 2. Launch the app once
+</details>
+
+<details>
+<summary><b>Windows</b></summary>
+
+Download the latest installer or portable `.zip` from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). Make sure `mpv` is on your `PATH`.
+
+</details>
+
+<details>
+<summary><b>From source</b></summary>
+
+See the [build-from-source guide](https://docs.subminer.moe/installation#from-source).
+
+</details>
+
+### 2. First Launch
+
+Run the app. On first launch SubMiner starts in the system tray, creates a default config, and opens a setup popup to install the mpv plugin and configure Yomitan dictionaries.
+
+### 3. Mine

 ```bash
-# Linux
-SubMiner.AppImage
+subminer video.mkv          # play video with overlay
+subminer --start video.mkv  # explicit overlay start
+subminer stats              # open immersion dashboard
+subminer stats -b           # stats daemon in background
+subminer stats -s           # stop background stats daemon
 ```

-On macOS, launch `SubMiner.app`. On Windows, launch `SubMiner.exe` from the Start menu or install directory.
-
-On first launch, SubMiner now:
-
- 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
-
-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
-
-| Required                                   | Optional                                           |
-| ------------------------------------------ | -------------------------------------------------- |
-| `bun` (source builds, Linux `subminer`)    |                                                    |
-| `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            |                                                    |
-
-Windows builds use native window tracking and do not require the Linux compositor helper tools.
+---

 ## Documentation

-For full guides on configuration, Anki, Jellyfin, and more, see [docs.subminer.moe](https://docs.subminer.moe).
+Full guides on configuration, Anki setup, Jellyfin, immersion tracking, and more: **[docs.subminer.moe](https://docs.subminer.moe)**

-## Testing
-
- Run `bun run test` or `bun run test:fast` for the default fast lane: config/core coverage plus representative entry/runtime, Anki integration, and main runtime checks.
- Run `bun run test:full` for the maintained test surface: Bun-compatible `src/**` coverage, Bun-compatible launcher unit coverage, and the maintained dist compatibility slice for `ipc`, `anki-jimaku-ipc`, `overlay-manager`, `config-validation`, `startup-config`, and runtime registry coverage.
- Run `bun run test:node:compat` directly when you only need that dist compatibility slice. The command name is legacy; it now runs under Bun.
- 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 the dist SQLite persistence coverage.
- Run `bun run test:subtitle` for the maintained `alass`/`ffsubsync` subtitle surface.
-
-The Bun-managed discovery lanes intentionally exclude a small set of suites from the source-file discovery pass and keep them in the maintained dist compatibility slice instead: Electron-focused tests in `src/core/services/ipc.test.ts`, `src/core/services/anki-jimaku-ipc.test.ts`, and `src/core/services/overlay-manager.test.ts`, plus runtime/config tests in `src/main/config-validation.test.ts`, `src/main/runtime/startup-config.test.ts`, and `src/main/runtime/registry.test.ts`. `bun run test:node:compat` keeps those suites in the standard workflow instead of leaving them untracked.
+---

 ## Acknowledgments

-Built on the shoulders of [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner), [Renji's Texthooker Page](https://github.com/Renji-XD/texthooker-ui), [mpvacious](https://github.com/Ajatt-Tools/mpvacious), [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script), and [Bee's Character Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary). Subtitles powered by [Jimaku.cc](https://jimaku.cc). Dictionary lookups via [Yomitan](https://github.com/yomidevs/yomitan).
+SubMiner builds on the work of these open-source projects:
+
+| Project                                                                                     | Role                                                                    |
+| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script)                          | Inspiration for the mining workflow                                     |
+| [asbplayer](https://github.com/killergerbah/asbplayer)                                      | Inspiration for subtitle sidebar and logic for YouTube subtitle parsing |
+| [Bee's Character Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary) | Character name recognition in subtitles                                 |
+| [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner)                          | Inspiration for Electron overlay with Yomitan integration               |
+| [jellyfin-mpv-shim](https://github.com/jellyfin/jellyfin-mpv-shim)                          | Jellyfin integration                                                    |
+| [Jimaku.cc](https://jimaku.cc)                                                              | Japanese subtitle search and downloads                                  |
+| [Renji's Texthooker Page](https://github.com/Renji-XD/texthooker-ui)                        | Base for the WebSocket texthooker integration                           |
+| [Yomitan](https://github.com/yomidevs/yomitan)                                              | Dictionary engine powering all lookups and the morphological parser     |
+| [yomitan-jlpt-vocab](https://github.com/stephenmk/yomitan-jlpt-vocab)                       | JLPT level tags for vocabulary                                          |

 ## License

--- a/assets/minecard-poster.jpg
+++ b/assets/minecard-poster.jpg
--- a/assets/minecard.mkv
+++ b/assets/minecard.mkv
--- a/assets/minecard.mp4
+++ b/assets/minecard.mp4
--- a/assets/minecard.webm
+++ b/assets/minecard.webm
--- a/assets/minecard.webp
+++ b/assets/minecard.webp
--- a/Address-latest-PR-19-review-comments.md
+++ b/Address-latest-PR-19-review-comments.md
@@ -0,0 +1,33 @@
+---
+id: TASK-175
+title: Address latest PR 19 review comments
+status: In Progress
+assignee: []
+created_date: '2026-03-15 10:25'
+labels:
+  - pr-review
+  - stats-dashboard
+dependencies: []
+references:
+  - src/core/services/ipc.ts
+  - src/core/services/stats-server.ts
+  - src/core/services/immersion-tracker/__tests__/query.test.ts
+  - src/core/services/stats-window-runtime.ts
+  - src/core/services/stats-window.test.ts
+  - src/shared/ipc/contracts.ts
+  - src/main.ts
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Validate the latest automated review comments on PR #19 against the current branch, implement the technically valid fixes, and document any items intentionally left unchanged.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 Validated the latest PR #19 review comments against current branch behavior and existing architecture
+- [ ] #2 Implemented the accepted fixes with regression coverage where it fits
+- [ ] #3 Documented which latest review items were intentionally not changed because they were already addressed or not technically warranted
+<!-- AC:END -->
--- a/Add-configurable-texthooker-startup-launch.md
+++ b/Add-configurable-texthooker-startup-launch.md
@@ -1,20 +1,19 @@
 ---
 id: TASK-100
-title: 'Add configurable texthooker startup launch'
+title: Add configurable texthooker startup launch
 status: Done
 assignee: []
 created_date: '2026-03-06 23:30'
-updated_date: '2026-03-07 01:59'
+updated_date: '2026-03-16 05:13'
 labels: []
 dependencies: []
 priority: medium
-ordinal: 10000
+ordinal: 11010
 ---

 ## Description

 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Add a config option under `texthooker` to launch the built-in texthooker server automatically when SubMiner starts.

 Scope:
@@ -24,26 +23,20 @@ Scope:
 - 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 -->
--- a/Index-AniList-character-alternative-names-in-the-character-dictionary.md
+++ b/Index-AniList-character-alternative-names-in-the-character-dictionary.md
@@ -4,7 +4,7 @@ title: Index AniList character alternative names in the character dictionary
 status: Done
 assignee: []
 created_date: '2026-03-07 00:00'
-updated_date: '2026-03-08 00:11'
+updated_date: '2026-03-16 05:13'
 labels:
  - dictionary
  - anilist
@@ -13,6 +13,7 @@ references:
  - src/main/character-dictionary-runtime.ts
  - src/main/character-dictionary-runtime.test.ts
 priority: high
+ordinal: 71500
 ---

 ## Description
--- a/Quiet-default-AppImage-startup-and-implicit-background-launch.md
+++ b/Quiet-default-AppImage-startup-and-implicit-background-launch.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-06 21:20'
-updated_date: '2026-03-06 21:33'
+updated_date: '2026-03-16 05:13'
 labels: []
 dependencies: []
 references:
@@ -13,6 +13,7 @@ references:
  - /home/sudacode/projects/japanese/SubMiner/src/core/services/cli-command.ts
  - /home/sudacode/projects/japanese/SubMiner/src/main.ts
 priority: medium
+ordinal: 77500
 ---

 ## Description
@@ -29,7 +30,6 @@ Scope:
 <!-- 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.
--- a/Add-dedicated-annotation-websocket-for-texthooker.md
+++ b/Add-dedicated-annotation-websocket-for-texthooker.md
@@ -5,13 +5,14 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-07 02:20'
-updated_date: '2026-03-07 02:20'
+updated_date: '2026-03-16 05:13'
 labels:
  - texthooker
  - websocket
  - subtitle
 dependencies: []
 priority: medium
+ordinal: 73500
 ---

 ## Description
@@ -21,7 +22,6 @@ Add a separate annotated subtitle websocket for bundled texthooker so token/JLPT
 <!-- 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`.
--- a/Mirror-overlay-annotation-hover-behavior-in-vendored-texthooker.md
+++ b/Mirror-overlay-annotation-hover-behavior-in-vendored-texthooker.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-06 21:45'
-updated_date: '2026-03-06 21:45'
+updated_date: '2026-03-16 05:13'
 labels:
  - texthooker
  - subtitle
@@ -14,10 +14,13 @@ 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/components/App.svelte
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/vendor/texthooker-ui/src/line-markup.ts
  - /home/sudacode/projects/japanese/SubMiner/vendor/texthooker-ui/src/app.css
 priority: medium
+ordinal: 76500
 ---

 ## Description
@@ -27,7 +30,6 @@ Bring bundled texthooker annotation rendering closer to the visible overlay. Kee
 <!-- 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.
--- a/Stop-local-docs-artifact-writes-after-docs-repo-split.md
+++ b/Stop-local-docs-artifact-writes-after-docs-repo-split.md
@@ -4,17 +4,16 @@ 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'
+updated_date: '2026-03-16 05:13'
 labels: []
 dependencies: []
 priority: medium
-ordinal: 10500
+ordinal: 12010
 ---

 ## Description

 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Now that user-facing docs live in `../subminer-docs`, first-party scripts in this repo should not keep writing generated artifacts into the local `docs/` tree.

 Scope:
@@ -23,25 +22,19 @@ Scope:
 - 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 -->
--- a/Add-first-run-setup-gate-and-auto-install-flow.md
+++ b/Add-first-run-setup-gate-and-auto-install-flow.md
@@ -5,17 +5,20 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-07 06:10'
-updated_date: '2026-03-07 06:20'
+updated_date: '2026-03-16 05:13'
 labels: []
 dependencies: []
 references:
  - /home/sudacode/projects/japanese/SubMiner/src/main.ts
  - /home/sudacode/projects/japanese/SubMiner/src/shared/setup-state.ts
-  - /home/sudacode/projects/japanese/SubMiner/src/main/runtime/first-run-setup-service.ts
-  - /home/sudacode/projects/japanese/SubMiner/src/main/runtime/first-run-setup-window.ts
-  - /home/sudacode/projects/japanese/SubMiner/launcher/commands/playback-command.ts
+  - >-
+    /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
+ordinal: 13010
 ---

 ## Description
@@ -31,7 +34,6 @@ Replace the current manual install flow with a first-run setup gate:
 <!-- 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.
--- a/Fix-Yomitan-scan-token-fallback-fragmentation.md
+++ b/Fix-Yomitan-scan-token-fallback-fragmentation.md
--- a/Exclude-single-kana-tokens-from-frequency-highlighting.md
+++ b/Exclude-single-kana-tokens-from-frequency-highlighting.md
--- a/Replace-vendored-Yomitan-with-submodule-built-Chrome-artifact-workflow.md
+++ b/Replace-vendored-Yomitan-with-submodule-built-Chrome-artifact-workflow.md
@@ -4,40 +4,34 @@ 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'
+updated_date: '2026-03-16 05:13'
 labels:
  - yomitan
  - build
  - release
 dependencies: []
 priority: high
-ordinal: 9010
+ordinal: 10010
 ---

 ## Description

 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Replace the checked-in `vendor/yomitan` release tree with a `subminer-yomitan` git submodule. Build Yomitan from source, extract the Chromium zip artifact into a stable local build directory, and make SubMiner dev/runtime/tests/release packaging load that extracted extension instead of the source tree or vendored files.
-
 <!-- SECTION:DESCRIPTION:END -->

 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [x] #1 Repo tracks Yomitan as a git submodule instead of committed extension files under `vendor/yomitan`.
 - [x] #2 SubMiner has a reproducible build/extract step that produces a local Chromium extension directory from `subminer-yomitan`.
 - [x] #3 Dev/runtime/tests resolve the extracted build output as the default Yomitan extension path.
 - [x] #4 Release packaging includes the extracted Chromium extension files instead of the old vendored tree.
 - [x] #5 Docs and verification commands reflect the new workflow.
-
 <!-- AC:END -->

 ## Final Summary

 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Replaced the checked-in `vendor/yomitan` extension tree with a `vendor/subminer-yomitan` git submodule and added a reproducible `bun run build:yomitan` workflow that builds `yomitan-chrome.zip`, extracts it into `build/yomitan`, and reuses a source-state stamp to skip redundant rebuilds. Runtime path resolution, helper CLIs, Yomitan integration tests, packaging, CI cache keys, and README source-build notes now all target that generated artifact instead of the old vendored files.

 Verification:
@@ -47,5 +41,4 @@ Verification:
 - `bun run typecheck`
 - `bun run build`
 - `bun run test:core:src`
-
 <!-- SECTION:FINAL_SUMMARY:END -->
--- a/Fix-subtitle-cycle-OSD-labels-for-J-keybindings.md
+++ b/Fix-subtitle-cycle-OSD-labels-for-J-keybindings.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - Codex
 created_date: '2026-03-07 23:45'
-updated_date: '2026-03-08 00:06'
+updated_date: '2026-03-16 05:13'
 labels: []
 dependencies: []
 references:
@@ -15,6 +15,7 @@ references:
    /Users/sudacode/projects/japanese/SubMiner/src/core/services/ipc-command.test.ts
  - >-
    /Users/sudacode/projects/japanese/SubMiner/src/core/services/mpv-control.test.ts
+ordinal: 72500
 ---

 ## Description
--- a/Address-Claude-review-items-on-PR-15.md
+++ b/Address-Claude-review-items-on-PR-15.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-08 00:11'
-updated_date: '2026-03-08 00:12'
+updated_date: '2026-03-16 05:13'
 labels:
  - pr-review
  - ci
@@ -18,6 +18,7 @@ references:
    backlog/tasks/task-101 -
    Index-AniList-character-alternative-names-in-the-character-dictionary.md
 priority: medium
+ordinal: 70500
 ---

 ## Description
--- a/Scope-make-pretty-to-maintained-source-files.md
+++ b/Scope-make-pretty-to-maintained-source-files.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-08 00:20'
-updated_date: '2026-03-08 00:22'
+updated_date: '2026-03-16 05:13'
 labels:
  - tooling
  - formatting
@@ -14,6 +14,7 @@ references:
  - Makefile
  - package.json
 priority: medium
+ordinal: 69500
 ---

 ## Description
--- a/Fix-failing-CI-checks-on-PR-15.md
+++ b/Fix-failing-CI-checks-on-PR-15.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-08 00:34'
-updated_date: '2026-03-08 00:37'
+updated_date: '2026-03-16 05:13'
 labels:
  - ci
  - test
@@ -15,6 +15,7 @@ references:
  - src/renderer/style.css
  - .github/workflows/ci.yml
 priority: high
+ordinal: 68500
 ---

 ## Description
--- a/Refresh-subminer-docs-contributor-docs-for-current-repo-workflow.md
+++ b/Refresh-subminer-docs-contributor-docs-for-current-repo-workflow.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-08 00:40'
-updated_date: '2026-03-08 00:42'
+updated_date: '2026-03-16 05:13'
 labels:
  - docs
 dependencies: []
@@ -15,6 +15,7 @@ references:
  - Makefile
  - package.json
 priority: medium
+ordinal: 67500
 ---

 ## Description
--- a/Audit-branch-commits-for-remaining-subminer-docs-updates.md
+++ b/Audit-branch-commits-for-remaining-subminer-docs-updates.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-08 00:46'
-updated_date: '2026-03-08 00:48'
+updated_date: '2026-03-16 05:13'
 labels:
  - docs
 dependencies: []
@@ -15,6 +15,7 @@ references:
  - src/core/services/yomitan-extension-paths.ts
  - scripts/build-yomitan.mjs
 priority: medium
+ordinal: 66500
 ---

 ## Description
--- a/Prepare-initial-Windows-release-docs-and-version-bump.md
+++ b/Prepare-initial-Windows-release-docs-and-version-bump.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-08 15:17'
-updated_date: '2026-03-08 15:17'
+updated_date: '2026-03-16 05:13'
 labels:
  - release
  - docs
@@ -18,6 +18,7 @@ references:
  - ../subminer-docs/usage.md
  - ../subminer-docs/changelog.md
 priority: medium
+ordinal: 53500
 ---

 ## Description
--- a/Replace-YouTube-subtitle-generation-with-pure-TypeScript-pipeline-and-shared-AI-config.md
+++ b/Replace-YouTube-subtitle-generation-with-pure-TypeScript-pipeline-and-shared-AI-config.md
@@ -24,11 +24,15 @@ references:
 ## Description

 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Replace the launcher YouTube subtitle generation flow with a pure TypeScript pipeline that prefers real downloadable YouTube subtitles, never uses YouTube auto-generated subtitles, locally generates missing tracks with whisper.cpp, and can optionally fix generated subtitles via a shared OpenAI-compatible AI provider config. This feature also introduces a breaking config cleanup: move provider settings to a new top-level ai section and reduce ankiConnect.ai to a boolean feature toggle.
+
 <!-- SECTION:DESCRIPTION:END -->

 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [x] #1 Launcher YouTube subtitle generation prefers downloadable manual YouTube subtitles, never uses YouTube auto-generated subtitles, and locally generates only missing tracks with whisper.cpp.
 - [x] #2 Generated whisper subtitle tracks can optionally be post-processed with an OpenAI-compatible AI provider using shared top-level ai config, with validation and fallback to raw whisper output on failure.
 - [x] #3 Configuration is updated so top-level ai is canonical shared provider config, ankiConnect.ai is boolean-only, and youtubeSubgen includes whisperVadModel, whisperThreads, and fixWithAi.
@@ -39,6 +43,7 @@ Replace the launcher YouTube subtitle generation flow with a pure TypeScript pip
 ## Implementation Plan

 <!-- SECTION:PLAN:BEGIN -->
+
 1. Introduce canonical top-level ai config plus youtubeSubgen runtime knobs (whisperVadModel, whisperThreads, fixWithAi) and convert ankiConnect.ai to a boolean-only toggle across types, defaults, validation, option registries, launcher config parsing, and config example/docs.
 2. Extract shared OpenAI-compatible AI client helpers from the current Anki translation code, including base URL normalization, API key / apiKeyCommand resolution, timeout handling, and response text extraction.
 3. Update Anki translation flow and hot-reload/runtime plumbing to consume global ai config while treating ankiConnect.ai as a feature gate only.
@@ -50,6 +55,7 @@ Replace the launcher YouTube subtitle generation flow with a pure TypeScript pip
 ## Implementation Notes

 <!-- SECTION:NOTES:BEGIN -->
+
 Implemented pure TypeScript launcher/youtube pipeline modules for manual subtitle fetch, audio extraction, whisper runs, SRT utilities, and optional AI subtitle fixing. Removed yt-dlp auto-subtitle usage from the generation path.

 Added shared top-level ai config plus shared AI client helpers; converted ankiConnect.ai to a boolean feature gate and updated Anki runtime wiring to consume global ai config.
@@ -57,10 +63,13 @@ Added shared top-level ai config plus shared AI client helpers; converted ankiCo
 Updated launcher config parsing, config template sections, and config.example.jsonc for the breaking config shape including youtubeSubgen.whisperVadModel, youtubeSubgen.whisperThreads, and youtubeSubgen.fixWithAi.

 Verification: bun run test:config:src passed; targeted AI/Anki/runtime tests passed; bun run typecheck passed. bun run test:launcher:unit:src reported one unrelated existing failure in launcher/aniskip-metadata.test.ts (resolveAniSkipMetadataForFile resolves MAL id and intro payload).
+
 <!-- SECTION:NOTES:END -->

 ## Final Summary

 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
+
 Replaced the launcher YouTube subtitle flow with a modular TypeScript pipeline that prefers manual YouTube subtitles, transcribes only missing tracks with whisper.cpp, and can optionally post-fix whisper output through a shared OpenAI-compatible AI client with strict SRT validation/fallback. Introduced canonical top-level ai config, reduced ankiConnect.ai to a boolean feature gate, updated launcher/config parsing and checked-in config artifacts, and added coverage for YouTube orchestration, whisper args, SRT validation, AI fix behavior, and breaking config validation.
+
 <!-- SECTION:FINAL_SUMMARY:END -->
--- a/Harden-AI-subtitle-fix-against-non-SRT-model-responses.md
+++ b/Harden-AI-subtitle-fix-against-non-SRT-model-responses.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - '@codex'
 created_date: '2026-03-08 08:22'
-updated_date: '2026-03-08 08:25'
+updated_date: '2026-03-16 05:13'
 labels: []
 dependencies: []
 references:
@@ -15,6 +15,7 @@ references:
  - >-
    /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/subtitle-fix-ai.test.ts
 parent_task_id: TASK-117
+ordinal: 59500
 ---

 ## Description
@@ -44,7 +45,7 @@ Prevent optional YouTube AI subtitle post-processing from bailing out whenever t
 <!-- SECTION:NOTES:BEGIN -->
 Implemented deterministic AI subtitle-response recovery for fenced SRT, embedded SRT payloads, and text-only 1:1 cue batches while preserving original timing and existing fallback behavior.

-Verification: bun test launcher/youtube/*.test.ts passed; bun run typecheck passed; repo-wide format check still reports unrelated pre-existing warnings in launcher/youtube/orchestrator.ts and scripts/build-changelog*.
+Verification: bun test launcher/youtube/_.test.ts passed; bun run typecheck passed; repo-wide format check still reports unrelated pre-existing warnings in launcher/youtube/orchestrator.ts and scripts/build-changelog_.
 <!-- SECTION:NOTES:END -->

 ## Final Summary
--- a/Add-Windows-release-build-and-SignPath-signing.md
+++ b/Add-Windows-release-build-and-SignPath-signing.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-08 15:17'
-updated_date: '2026-03-08 15:17'
+updated_date: '2026-03-16 05:13'
 labels:
  - release
  - windows
@@ -17,6 +17,7 @@ references:
  - build/signpath-windows-artifact-config.xml
  - package.json
 priority: high
+ordinal: 54500
 ---

 ## Description
--- a/Fix-GitHub-release-workflow-publish-step-failure.md
+++ b/Fix-GitHub-release-workflow-publish-step-failure.md
@@ -19,11 +19,15 @@ references:
 ## Description

 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 The GitHub Actions Release workflow fails during the Publish Release step for tag releases because the gh CLI invocation passes invalid arguments when creating or editing the GitHub release. Restore successful release publication for tagged builds without changing unrelated release packaging behavior.
+
 <!-- SECTION:DESCRIPTION:END -->

 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [x] #1 Tagged Release workflow completes the Publish Release step without gh CLI argument errors.
 - [x] #2 Release workflow still creates or updates the GitHub release as a non-prerelease for normal version tags.
 - [x] #3 A regression check covers the publish command shape or workflow behavior that caused this failure.
@@ -33,6 +37,7 @@ The GitHub Actions Release workflow fails during the Publish Release step for ta
 ## Implementation Plan

 <!-- SECTION:PLAN:BEGIN -->
+
 1. Add a targeted regression test for .github/workflows/release.yml that fails if the publish step passes an argument to the gh --prerelease boolean flag or otherwise omits explicit non-prerelease behavior.
 2. Run the targeted test to confirm the current workflow fails for the expected reason.
 3. Patch the Publish Release step in .github/workflows/release.yml to remove the invalid gh CLI usage while preserving non-prerelease release creation/update behavior.
@@ -42,6 +47,7 @@ The GitHub Actions Release workflow fails during the Publish Release step for ta
 ## Implementation Notes

 <!-- SECTION:NOTES:BEGIN -->
+
 Identified root cause from GitHub Actions run 22812335927: Publish Release failed with `accepts 1 arg(s), received 2` because the workflow passed a value to gh's boolean prerelease flag.

 Added a workflow comment clarifying that omitting the prerelease flag keeps normal releases as non-prerelease releases.
@@ -51,14 +57,17 @@ Added src/release-workflow.test.ts and wired it into `bun run test:fast` so CI c
 Verification: `bun test src/release-workflow.test.ts`, `bun run typecheck`, and `bun run test:fast` all passed locally.

 Code-review pass found no issues; remaining caveat is that prerelease tag semantics are still not modeled for tags like `v1.0.0-beta.1`, which is outside this fix scope.
+
 <!-- SECTION:NOTES:END -->

 ## Final Summary

 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
+
 Fixed the GitHub Actions release publish step so tagged releases no longer fail on invalid gh CLI usage. The workflow now omits the prerelease flag when creating or editing normal releases, which preserves existing non-prerelease behavior and avoids the `accepts 1 arg(s), received 2` failure seen in run 22812335927.

 Added a small regression test that reads `.github/workflows/release.yml` and asserts the publish step does not set the prerelease flag, then included that test in `bun run test:fast` so the main verification lane catches this class of workflow regression before the next release.

 Validation run locally: `bun test src/release-workflow.test.ts`, `bun run typecheck`, and `bun run test:fast`. Residual risk: prerelease-tag semantics remain unchanged for tags such as `v1.0.0-beta.1`; this fix is intentionally scoped to restoring normal tagged release publication.
+
 <!-- SECTION:FINAL_SUMMARY:END -->
--- a/Replace-node-sqlite-with-libsql-and-remove-Yomitan-Node-wrapper.md
+++ b/Replace-node-sqlite-with-libsql-and-remove-Yomitan-Node-wrapper.md
@@ -4,7 +4,7 @@ title: 'Replace node:sqlite with libsql and remove Yomitan Node wrapper'
 status: Done
 assignee: []
 created_date: '2026-03-08 04:14'
-updated_date: '2026-03-08 04:39'
+updated_date: '2026-03-16 05:13'
 labels:
  - runtime
  - bun
@@ -12,6 +12,7 @@ labels:
  - tech-debt
 dependencies: []
 priority: medium
+ordinal: 65500
 ---

 ## Description
--- a/Fix-YouTube-manual-subtitle-selection-regression-when-downloadable-tracks-exist.md
+++ b/Fix-YouTube-manual-subtitle-selection-regression-when-downloadable-tracks-exist.md
@@ -7,7 +7,7 @@ status: Done
 assignee:
  - '@codex'
 created_date: '2026-03-08 05:37'
-updated_date: '2026-03-08 05:42'
+updated_date: '2026-03-16 05:13'
 labels:
  - bug
  - youtube
@@ -18,6 +18,7 @@ references:
  - /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/orchestrator.ts
  - 'https://www.youtube.com/watch?v=MXzQRLmN9hE'
 priority: high
+ordinal: 64500
 ---

 ## Description
--- a/Harden-changelog-workflow-and-CI-enforcement.md
+++ b/Harden-changelog-workflow-and-CI-enforcement.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - Codex
 created_date: '2026-03-08 06:13'
-updated_date: '2026-03-08 06:28'
+updated_date: '2026-03-16 05:13'
 labels:
  - release
  - changelog
@@ -19,6 +19,7 @@ references:
  - /Users/sudacode/projects/japanese/SubMiner/docs/RELEASING.md
  - /Users/sudacode/projects/japanese/SubMiner/changes/README.md
 priority: medium
+ordinal: 63500
 ---

 ## Description
--- a/Add-progress-logging-for-YouTube-subtitle-generation-phases.md
+++ b/Add-progress-logging-for-YouTube-subtitle-generation-phases.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - '@codex'
 created_date: '2026-03-08 07:07'
-updated_date: '2026-03-08 07:15'
+updated_date: '2026-03-16 05:13'
 labels:
  - ux
  - logging
@@ -20,6 +20,7 @@ references:
  - >-
    /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/subtitle-fix-ai.ts
 priority: medium
+ordinal: 62500
 ---

 ## Description
--- a/Remove-YouTube-subtitle-generation-modes-and-make-YouTube-playback-always-generate-load-subtitles.md
+++ b/Remove-YouTube-subtitle-generation-modes-and-make-YouTube-playback-always-generate-load-subtitles.md
@@ -7,7 +7,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-08 07:18'
-updated_date: '2026-03-08 07:28'
+updated_date: '2026-03-16 05:13'
 labels:
  - launcher
  - youtube
@@ -27,6 +27,7 @@ references:
  - >-
    /Users/sudacode/projects/japanese/SubMiner/src/config/resolve/subtitle-domains.ts
 priority: high
+ordinal: 61500
 ---

 ## Description
--- a/Improve-secondary-subtitle-readability-with-hover-only-background-and-stronger-text-separation.md
+++ b/Improve-secondary-subtitle-readability-with-hover-only-background-and-stronger-text-separation.md
@@ -6,13 +6,14 @@ title: >-
 status: Done
 assignee: []
 created_date: '2026-03-08 07:35'
-updated_date: '2026-03-08 07:40'
+updated_date: '2026-03-16 05:13'
 labels:
  - overlay
  - subtitles
  - ui
 dependencies: []
 priority: medium
+ordinal: 60500
 ---

 ## Description
--- a/Skip-AniSkip-lookup-for-YouTube-and-URL-playback-targets.md
+++ b/Skip-AniSkip-lookup-for-YouTube-and-URL-playback-targets.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - '@codex'
 created_date: '2026-03-08 08:24'
-updated_date: '2026-03-08 10:12'
+updated_date: '2026-03-16 05:13'
 labels:
  - bug
  - launcher
@@ -16,6 +16,7 @@ references:
  - >-
    /Users/sudacode/projects/japanese/SubMiner/launcher/commands/playback-command.ts
  - /Users/sudacode/projects/japanese/SubMiner/launcher/mpv.test.ts
+ordinal: 56500
 ---

 ## Description
--- a/Prevent-AI-subtitle-fix-from-translating-primary-YouTube-subtitles-into-the-wrong-language.md
+++ b/Prevent-AI-subtitle-fix-from-translating-primary-YouTube-subtitles-into-the-wrong-language.md
@@ -6,13 +6,14 @@ title: >-
 status: Done
 assignee: []
 created_date: '2026-03-08 09:02'
-updated_date: '2026-03-08 09:17'
+updated_date: '2026-03-16 05:13'
 labels:
  - bug
  - youtube-subgen
  - ai
 dependencies: []
 priority: high
+ordinal: 58500
 ---

 ## Description
--- a/Split-AI-model-and-system-prompt-config-between-Anki-and-YouTube-subtitle-generation.md
+++ b/Split-AI-model-and-system-prompt-config-between-Anki-and-YouTube-subtitle-generation.md
@@ -6,7 +6,7 @@ title: >-
 status: Done
 assignee: []
 created_date: '2026-03-08 09:40'
-updated_date: '2026-03-08 09:57'
+updated_date: '2026-03-16 05:13'
 labels:
  - config
  - ai
@@ -14,6 +14,7 @@ labels:
  - youtube-subgen
 dependencies: []
 priority: high
+ordinal: 57500
 ---

 ## Description
--- a/Keep-background-SubMiner-alive-after-launcher-managed-mpv-exits.md
+++ b/Keep-background-SubMiner-alive-after-launcher-managed-mpv-exits.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-08 10:08'
-updated_date: '2026-03-08 11:00'
+updated_date: '2026-03-16 05:13'
 labels:
  - bug
  - launcher
@@ -13,6 +13,7 @@ labels:
  - overlay
 dependencies: []
 priority: high
+ordinal: 55500
 ---

 ## Description
@@ -67,6 +68,7 @@ Net effect: background SubMiner can stay alive, keep its warm state, and reconne
 Coverage now includes: launcher playback cleanup (`launcher/mpv.test.ts`), launcher smoke reconnect/keep-alive flow (`launcher/smoke.e2e.test.ts`), mpv plugin shutdown preservation (`scripts/test-plugin-start-gate.lua`), and second-instance start/reconnect behavior (`src/core/services/cli-command.test.ts`).

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

 ## Description
--- a/Harden-Windows-release-signing-against-transient-SignPath-failures.md
+++ b/Harden-Windows-release-signing-against-transient-SignPath-failures.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-09 00:00'
-updated_date: '2026-03-08 20:23'
+updated_date: '2026-03-18 05:28'
 labels:
  - ci
  - release
@@ -16,8 +16,9 @@ references:
  - .github/workflows/release.yml
  - package.json
  - src/release-workflow.test.ts
-  - https://github.com/ksyasuda/SubMiner/actions/runs/22836585479
+  - 'https://github.com/ksyasuda/SubMiner/actions/runs/22836585479'
 priority: high
+ordinal: 52500
 ---

 ## Description
--- a/Cut-patch-release-v0.5.1-for-Windows-signing-fix.md
+++ b/Cut-patch-release-v0.5.1-for-Windows-signing-fix.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-08 20:24'
-updated_date: '2026-03-08 20:28'
+updated_date: '2026-03-18 05:28'
 labels:
  - release
  - patch
@@ -16,6 +16,7 @@ references:
  - CHANGELOG.md
  - release/release-notes.md
 priority: high
+ordinal: 51500
 ---

 ## Description
--- a/Pin-SignPath-artifact-configuration-in-release-workflow.md
+++ b/Pin-SignPath-artifact-configuration-in-release-workflow.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-08 20:41'
-updated_date: '2026-03-08 20:58'
+updated_date: '2026-03-18 05:28'
 labels:
  - ci
  - release
@@ -18,6 +18,7 @@ references:
  - build/signpath-windows-artifact-config.xml
  - src/release-workflow.test.ts
 priority: high
+ordinal: 49500
 ---

 ## Description
--- a/Cut-patch-release-v0.5.2-for-SignPath-artifact-config-pinning.md
+++ b/Cut-patch-release-v0.5.2-for-SignPath-artifact-config-pinning.md
@@ -5,7 +5,7 @@ status: Done
 assignee:
  - codex
 created_date: '2026-03-08 20:44'
-updated_date: '2026-03-08 20:58'
+updated_date: '2026-03-18 05:28'
 labels:
  - release
  - patch
@@ -16,6 +16,7 @@ references:
  - CHANGELOG.md
  - release/release-notes.md
 priority: high
+ordinal: 50500
 ---

 ## Description
--- a/Publish-unsigned-Windows-release-artifacts-and-add-local-unsigned-build-script.md
+++ b/Publish-unsigned-Windows-release-artifacts-and-add-local-unsigned-build-script.md
@@ -0,0 +1,64 @@
+---
+id: TASK-138
+title: Publish unsigned Windows release artifacts and add local unsigned build script
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-09 00:00'
+updated_date: '2026-03-18 05:28'
+labels:
+  - release
+  - windows
+dependencies: []
+references:
+  - .github/workflows/release.yml
+  - package.json
+  - src/release-workflow.test.ts
+priority: high
+ordinal: 45500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Stop the tag-driven release workflow from depending on SignPath and publish unsigned Windows `.exe` and `.zip` artifacts directly. Add an explicit local `build:win:unsigned` script without changing the existing `build:win` command.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Windows release CI builds unsigned artifacts without requiring SignPath secrets.
+- [x] #2 The Windows release job uploads `release/*.exe` and `release/*.zip` directly as the `windows` artifact.
+- [x] #3 The repo exposes a local `build:win:unsigned` script for explicit unsigned Windows packaging.
+- [x] #4 Regression coverage fails if the workflow reintroduces SignPath submission or drops the unsigned script.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Update workflow regression tests to assert unsigned Windows release behavior and the new local script.
+2. Patch `package.json` to add `build:win:unsigned`.
+3. Patch `.github/workflows/release.yml` to build unsigned Windows artifacts and upload them directly.
+4. Add the release changelog fragment and run focused verification.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Removed the Windows SignPath secret validation and submission steps from `.github/workflows/release.yml`. The Windows release job now runs `bun run build:win:unsigned` and uploads `release/*.exe` and `release/*.zip` directly as the `windows` artifact consumed by the release job.
+
+Added `scripts/build-win-unsigned.mjs` plus the `build:win:unsigned` package script. The wrapper clears Windows code-signing environment variables and disables identity auto-discovery before invoking `electron-builder`, so release CI stays unsigned even if signing credentials are configured elsewhere.
+
+Updated `src/release-workflow.test.ts` to assert the unsigned workflow contract and added the release changelog fragment in `changes/unsigned-windows-release-builds.md`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Windows release CI now publishes unsigned artifacts directly and no longer depends on SignPath. Local developers also have an explicit `bun run build:win:unsigned` path for unsigned packaging without changing the existing `build:win` command.
+
+Verification:
+
+- `bun test src/release-workflow.test.ts`
+- `bun run typecheck`
+- `node --check scripts/build-win-unsigned.mjs`
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Cut-patch-release-v0.5.3-for-unsigned-Windows-release-builds.md
+++ b/Cut-patch-release-v0.5.3-for-unsigned-Windows-release-builds.md
@@ -0,0 +1,58 @@
+---
+id: TASK-139
+title: Cut patch release v0.5.3 for unsigned Windows release builds
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-09 00:00'
+updated_date: '2026-03-18 05:28'
+labels:
+  - release
+  - patch
+dependencies:
+  - TASK-138
+references:
+  - package.json
+  - CHANGELOG.md
+  - release/release-notes.md
+priority: high
+ordinal: 46500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Publish a patch release from the unsigned Windows release-build change by bumping the app version, generating committed changelog artifacts for `v0.5.3`, and pushing the release-prep commit.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Repository version metadata is updated to `0.5.3`.
+- [x] #2 `CHANGELOG.md` and `release/release-notes.md` contain the committed `v0.5.3` section and consumed fragments are removed.
+- [x] #3 New `v0.5.3` release-prep commit is pushed to `origin/main`.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Bump `package.json` from `0.5.2` to `0.5.3`.
+2. Run `bun run changelog:build` so committed changelog artifacts match the new patch version.
+3. Run changelog/typecheck/test verification.
+4. Commit the release-prep change set and push `main`.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Bumped `package.json` from `0.5.2` to `0.5.3`, ran `bun run changelog:build`, and committed the generated release artifacts. That prepended the `v0.5.3` section to `CHANGELOG.md`, regenerated `release/release-notes.md`, and removed the consumed `changes/unsigned-windows-release-builds.md` fragment.
+
+Verification before push: `bun run changelog:lint`, `bun run changelog:check --version 0.5.3`, `bun run typecheck`, and `bun run test:fast`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Prepared patch release `v0.5.3` so the unsigned Windows release-build change is captured in committed release metadata on `main`. Version metadata, changelog output, and release notes are aligned with the new patch version.
+
+Validation: `bun run changelog:lint`, `bun run changelog:check --version 0.5.3`, `bun run typecheck`, `bun run test:fast`.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Fix-guessit-title-parsing-for-character-dictionary-sync.md
+++ b/Fix-guessit-title-parsing-for-character-dictionary-sync.md
@@ -0,0 +1,41 @@
+---
+id: TASK-140
+title: Fix guessit title parsing for character dictionary sync
+status: Done
+assignee: []
+created_date: '2026-03-09 00:00'
+updated_date: '2026-03-18 05:28'
+labels:
+  - dictionary
+  - anilist
+  - bug
+  - guessit
+dependencies: []
+references:
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/core/services/anilist/anilist-updater.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/core/services/anilist/anilist-updater.test.ts
+priority: high
+ordinal: 44500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Fix AniList character dictionary auto-sync for filenames where `guessit` misparses the full path and our title extraction keeps only the first array segment, causing AniList resolution to match the wrong anime and abort merged dictionary refresh.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 AniList media guessing passes basename-only targets to `guessit` so parent folder names do not corrupt series title detection.
+- [x] #2 Guessit title arrays are combined into one usable title instead of truncating to the first segment.
+- [x] #3 Regression coverage includes the Bunny Girl Senpai filename shape that previously resolved to the wrong AniList entry.
+- [x] #4 Verification confirms the targeted AniList guessing tests pass.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Root repro: `guessit` parsed the Bunny Girl Senpai full path as `title: ["Rascal", "Does-not-Dream-of-Bunny-Girl-Senapi"]`, and our `firstString` helper kept only `Rascal`, which resolved to AniList 3490 (`rayca`) and produced zero character results. Fixed by sending basename-only input to `guessit` and joining multi-part guessit title arrays.
+<!-- SECTION:NOTES:END -->
--- a/Refresh-current-subtitle-after-character-dictionary-sync-completes.md
+++ b/Refresh-current-subtitle-after-character-dictionary-sync-completes.md
@@ -0,0 +1,38 @@
+---
+id: TASK-141
+title: Refresh current subtitle after character dictionary sync completes
+status: Done
+assignee: []
+created_date: '2026-03-09 00:00'
+updated_date: '2026-03-18 05:28'
+labels:
+  - dictionary
+  - overlay
+  - bug
+dependencies: []
+references:
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
+  - /home/sudacode/projects/japanese/SubMiner/src/main.ts
+priority: high
+ordinal: 42500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+When character dictionary auto-sync finishes after startup tokenization, invalidate cached subtitle tokenization and refresh the current subtitle so character-name highlighting catches up without waiting for the next subtitle line.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Successful character dictionary sync exposes a completion hook for main runtime follow-up.
+- [x] #2 Main runtime clears Yomitan parser caches and refreshes the current subtitle after sync completion.
+- [x] #3 Regression coverage verifies the sync completion callback fires on successful sync.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Observed on Bunny Girl Senpai startup: autoplay/tokenization became ready around 8s, but snapshot/import/state write completed roughly 31s after launch, leaving the current subtitle tokenized without the newly imported character dictionary. Fixed by adding an auto-sync completion hook that clears parser caches and refreshes the current subtitle.
+<!-- SECTION:NOTES:END -->
--- a/Show-character-dictionary-auto-sync-progress-on-OSD.md
+++ b/Show-character-dictionary-auto-sync-progress-on-OSD.md
@@ -0,0 +1,40 @@
+---
+id: TASK-142
+title: Show character dictionary auto-sync progress on OSD
+status: Done
+assignee: []
+created_date: '2026-03-09 01:10'
+updated_date: '2026-03-18 05:28'
+labels:
+  - dictionary
+  - overlay
+  - ux
+dependencies: []
+references:
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync-notifications.ts
+  - /home/sudacode/projects/japanese/SubMiner/src/main.ts
+priority: medium
+ordinal: 41500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+When character dictionary auto-sync runs for a newly opened anime, surface progress so users know why character-name lookup/highlighting is temporarily unavailable via the mpv OSD without desktop notification popups.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Character dictionary auto-sync emits progress events for syncing, importing, ready, and failure states.
+- [x] #2 Main runtime routes those progress events through OSD notifications without desktop notifications.
+- [x] #3 Regression coverage verifies progress events and notification routing behavior.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+OSD now shows auto-sync phase changes while the dictionary updates. Desktop notifications were removed for this path to avoid startup popup spam.
+<!-- SECTION:NOTES:END -->
--- a/Sequence-startup-OSD-notifications-for-tokenization-annotations-and-character-dictionary-sync.md
+++ b/Sequence-startup-OSD-notifications-for-tokenization-annotations-and-character-dictionary-sync.md
@@ -0,0 +1,44 @@
+---
+id: TASK-144
+title: >-
+  Sequence startup OSD notifications for tokenization, annotations, and
+  character dictionary sync
+status: Done
+assignee: []
+created_date: '2026-03-09 10:40'
+updated_date: '2026-03-18 05:28'
+labels:
+  - startup
+  - overlay
+  - ux
+dependencies: []
+references:
+  - /home/sudacode/projects/japanese/SubMiner/src/main.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/startup-osd-sequencer.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/subtitle-tokenization-main-deps.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync-notifications.ts
+priority: medium
+ordinal: 37500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Keep startup OSD progress ordered. While tokenization is still pending, only show the tokenization loading message. After tokenization becomes ready, show annotation loading if annotation warmup still remains. Only surface character dictionary auto-sync progress after annotation loading clears, and only if the dictionary work is still active.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Character dictionary progress stays hidden while tokenization startup loading is still active.
+- [x] #2 Annotation loading OSD appears after tokenization readiness and before any later character dictionary progress.
+- [x] #3 Regression coverage verifies buffered dictionary progress/failure ordering during startup.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added a small startup OSD sequencer in main runtime. Annotation warmup OSD now flows through that sequencer, and character dictionary sync notifications buffer until tokenization plus annotation loading clear. Buffered `ready` updates are dropped if dictionary progress finished before it ever became visible, while buffered failures still surface after annotation loading completes.
+<!-- SECTION:NOTES:END -->
--- a/Show-checking-and-generation-OSD-for-character-dictionary-auto-sync.md
+++ b/Show-checking-and-generation-OSD-for-character-dictionary-auto-sync.md
@@ -0,0 +1,44 @@
+---
+id: TASK-145
+title: Show checking and generation OSD for character dictionary auto-sync
+status: Done
+assignee: []
+created_date: '2026-03-09 11:20'
+updated_date: '2026-03-16 05:13'
+labels:
+  - dictionary
+  - overlay
+  - ux
+dependencies: []
+references:
+  - /home/sudacode/projects/japanese/SubMiner/src/main.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/startup-osd-sequencer.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
+priority: medium
+ordinal: 35500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Surface an immediate startup OSD that the character dictionary is being checked, and show a distinct generating message only when the current AniList media actually needs a fresh snapshot build instead of reusing a cached one.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Auto-sync emits a `checking` progress event before snapshot resolution completes.
+- [x] #2 Auto-sync emits `generating` only for snapshot cache misses and keeps `updating`/`importing` as later phases.
+- [x] #3 Startup OSD sequencing still prioritizes tokenization then annotation loading before buffered dictionary progress.
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Character dictionary auto-sync now emits `Checking character dictionary...` as soon as the AniList media is resolved, then emits `Generating character dictionary...` only when the snapshot layer misses and a real rebuild begins. Cached snapshots skip the generating phase and continue straight into the later update/import flow.
+
+Wired those progress callbacks through the character-dictionary runtime boundary, updated the startup OSD sequencer to treat checking/generating as dictionary-progress phases with the same tokenization and annotation precedence, and added regression coverage for cache-hit vs cache-miss behavior plus buffered startup ordering.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Forward-overlay-Tab-to-mpv-for-AniSkip.md
+++ b/Forward-overlay-Tab-to-mpv-for-AniSkip.md
@@ -0,0 +1,59 @@
+---
+id: TASK-146
+title: Forward overlay Tab to mpv for AniSkip
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-09 00:00'
+updated_date: '2026-03-18 05:28'
+labels:
+  - bug
+  - overlay
+  - aniskip
+  - linux
+dependencies: []
+ordinal: 47500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Fix visible-overlay keyboard handling so bare `Tab` is forwarded to mpv instead of being consumed by Electron focus navigation. This restores the default AniSkip `TAB` binding while the overlay has focus, especially on Linux.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Visible overlay forwards bare `Tab` to mpv as `keypress TAB`.
+- [x] #2 Modal overlays keep their existing local `Tab` behavior.
+- [x] #3 Automated regression coverage exists for the input handler and overlay factory wiring.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a failing regression around visible-overlay `before-input-event` handling for bare `Tab`.
+2. Add/extend overlay factory tests so the new mpv-forward callback is wired through runtime construction.
+3. Patch overlay input handling to intercept visible-overlay `Tab` and send mpv `keypress TAB`.
+4. Run focused overlay tests, typecheck, and changelog validation.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Extracted visible-overlay input handling into `src/core/services/overlay-window-input.ts` so the `Tab` forwarding decision can be unit tested without loading Electron window primitives.
+
+Visible overlay `before-input-event` now intercepts bare `Tab`, prevents the browser default, and forwards mpv `keypress TAB` through the existing mpv runtime command path. Modal overlays remain unchanged.
+
+Verification:
+
+- `bun test src/core/services/overlay-window.test.ts src/main/runtime/overlay-window-factory.test.ts src/main/runtime/overlay-window-factory-main-deps.test.ts src/main/runtime/overlay-window-runtime-handlers.test.ts`
+- `bun x tsc --noEmit`
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Visible overlay focus no longer blocks the default AniSkip `Tab` binding. Bare `Tab` is now forwarded straight to mpv while the visible overlay is active, and modal overlays still retain their own normal focus behavior.
+
+Added regression coverage for both the input-routing decision and the runtime plumbing that carries the new mpv forwarder into overlay window creation.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Fix-Windows-plugin-env-binary-override-resolution.md
+++ b/Fix-Windows-plugin-env-binary-override-resolution.md
@@ -0,0 +1,39 @@
+---
+id: TASK-148
+title: Fix Windows plugin env binary override resolution
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-09 00:00'
+updated_date: '2026-03-18 05:28'
+labels:
+  - windows
+  - plugin
+  - regression
+dependencies: []
+priority: medium
+ordinal: 48500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Fix the mpv plugin's Windows binary override lookup so `SUBMINER_BINARY_PATH` still resolves when `SUBMINER_APPIMAGE_PATH` is unset. The current Lua resolver builds an array with a leading `nil`, which causes `ipairs` iteration to stop before the later Windows override candidate.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 `scripts/test-plugin-binary-windows.lua` passes the env override regression that expects `.exe` suffix resolution from `SUBMINER_BINARY_PATH`.
+- [x] #2 Existing plugin start/binary test gate stays green after the fix.
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Updated `plugin/subminer/binary.lua` so env override lookup checks `SUBMINER_APPIMAGE_PATH` and `SUBMINER_BINARY_PATH` sequentially instead of via a Lua array literal that truncates at the first `nil`. This restores Windows `.exe` suffix resolution for `SUBMINER_BINARY_PATH` when the AppImage env var is unset.
+
+Verification:
+
+- `lua scripts/test-plugin-binary-windows.lua`
+- `bun run test:plugin:src`
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Cut-patch-release-v0.5.5-for-character-dictionary-updates-and-release-guarding.md
+++ b/Cut-patch-release-v0.5.5-for-character-dictionary-updates-and-release-guarding.md
@@ -0,0 +1,72 @@
+---
+id: TASK-149
+title: Cut patch release v0.5.5 for character dictionary updates and release guarding
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-09 01:10'
+updated_date: '2026-03-18 05:28'
+labels:
+  - release
+  - patch
+dependencies:
+  - TASK-140
+  - TASK-141
+  - TASK-142
+  - TASK-143
+  - TASK-144
+  - TASK-145
+  - TASK-146
+  - TASK-148
+references:
+  - package.json
+  - CHANGELOG.md
+  - scripts/build-changelog.ts
+  - scripts/build-changelog.test.ts
+  - docs/RELEASING.md
+priority: high
+ordinal: 39500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Prepare and publish patch release `v0.5.5` after the failed `v0.5.4` tag by aligning package version metadata, generating committed changelog output from the pending release fragments, and hardening release validation so a future tag cannot ship with a mismatched `package.json` version.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Repository version metadata is updated to `0.5.5`.
+- [x] #2 `CHANGELOG.md` contains the committed `v0.5.5` section and the consumed fragments are removed.
+- [x] #3 Release validation rejects a requested release version when it differs from `package.json`.
+- [x] #4 Release docs capture the required version/changelog prep before tagging.
+- [x] #5 New `v0.5.5` release-prep commit and tag are pushed to `origin/main`.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a regression test for tagged-release/package version mismatch.
+2. Update changelog validation to reject mismatched explicit release versions.
+3. Bump `package.json`, generate committed `v0.5.5` changelog output, and remove consumed fragments.
+4. Add a short `docs/RELEASING.md` checklist for the prep flow.
+5. Run release verification, commit, tag, and push.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added a regression test in `scripts/build-changelog.test.ts` that proves `changelog:check --version ...` rejects tag/package mismatches. Updated `scripts/build-changelog.ts` so tagged release validation now compares the explicit requested version against `package.json` before looking for pending fragments or the committed changelog section.
+
+Bumped `package.json` from `0.5.3` to `0.5.5`, ran `bun run changelog:build --version 0.5.5 --date 2026-03-09`, and committed the generated `CHANGELOG.md` output while removing the consumed task fragments. Added `docs/RELEASING.md` with the required release-prep checklist so version bump + changelog generation happen before tagging.
+
+Verification: `bun run changelog:lint`, `bun run changelog:check --version 0.5.5`, `bun run typecheck`, `bun run test:fast`, and `bun test scripts/build-changelog.test.ts src/release-workflow.test.ts`. `bun run format:check` still reports many unrelated pre-existing repo-wide Prettier warnings, so touched files were checked/formatted separately with `bunx prettier`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Prepared patch release `v0.5.5` after the failed `v0.5.4` release attempt. Release metadata now matches the upcoming tag, the pending character-dictionary/overlay/plugin fragments are committed into `CHANGELOG.md`, and release validation now blocks future tag/package mismatches before publish.
+
+Docs now include a short release checklist in `docs/RELEASING.md`. Validation passed for changelog lint/check, typecheck, targeted workflow tests, and the full fast test suite. Repo-wide Prettier remains noisy from unrelated existing files, but touched release files were formatted and verified.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Restore-repo-wide-Prettier-cleanliness-after-release-prep.md
+++ b/Restore-repo-wide-Prettier-cleanliness-after-release-prep.md
@@ -0,0 +1,60 @@
+---
+id: TASK-150
+title: Restore repo-wide Prettier cleanliness after release prep
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-09 01:11'
+updated_date: '2026-03-18 05:28'
+labels:
+  - tooling
+  - formatting
+dependencies: []
+references:
+  - backlog/config.yml
+  - backlog/tasks
+  - config.example.jsonc
+  - launcher/types.ts
+  - launcher/util.ts
+  - launcher/youtube/orchestrator.ts
+  - scripts/build-win-unsigned.mjs
+  - src
+priority: medium
+ordinal: 40500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Bring `bun run format:check` back to green after the `v0.5.5` release-prep work exposed repo-wide Prettier drift across backlog markdown, config files, and maintained TypeScript sources.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 `bun run format:check` passes.
+- [x] #2 `bun run changelog:lint` still passes.
+- [x] #3 Typecheck and fast tests stay green after the formatting-only rewrite.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Re-run format and lint checks to confirm failing files.
+2. Apply Prettier to the warned repo-managed files.
+3. Re-run formatting, lint, typecheck, and fast tests.
+4. Commit and push the formatting-only cleanup.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Ran `bunx prettier --write` across the repo-managed files reported by `bun run format:check`, covering backlog markdown/YAML, `config.example.jsonc`, selected launcher/scripts files, and maintained TypeScript sources under `src/`.
+
+Verification: `bun run format:check`, `bun run changelog:lint`, `bun run typecheck`, and `bun run test:fast`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Repo-wide Prettier drift is cleaned up, including backlog task markdown, config/example files, and the maintained code files that `format:check` was flagging. Formatting and lint checks are green again, and typecheck/fast tests stayed green after the formatting-only rewrite.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Keep-JLPT-underline-color-stable-during-Yomitan-text-selection.md
+++ b/Keep-JLPT-underline-color-stable-during-Yomitan-text-selection.md
@@ -0,0 +1,100 @@
+---
+id: TASK-151
+title: Keep JLPT underline color stable during Yomitan text selection
+status: Done
+assignee:
+  - OpenCode
+created_date: '2026-03-10 06:42'
+updated_date: '2026-03-16 05:13'
+labels: []
+dependencies: []
+references:
+  - src/renderer/style.css
+  - src/renderer/subtitle-render.test.ts
+documentation:
+  - ../subminer-docs/development.md
+  - ../subminer-docs/architecture.md
+priority: medium
+ordinal: 33500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Fix the subtitle overlay so JLPT underlines keep their JLPT color when Yomitan lookups trigger hover/selection styling on tokens that are also known, N+1, or frequency-highlighted.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 JLPT-tagged subtitle tokens keep their JLPT underline color during hover/selection states used by Yomitan lookup.
+- [x] #2 Tokens that combine JLPT with known, N+1, name-match, or frequency styling preserve their primary text color while keeping the JLPT underline color.
+- [x] #3 Renderer regression coverage verifies the JLPT underline color remains explicit in the stylesheet for combined styling states.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Revert the temporary box-shadow JLPT marker experiment and restore native JLPT underline styling in `src/renderer/style.css`.
+2. Add explicit JLPT hover/selection color rules with higher specificity so Yomitan lookup highlight states cannot repaint the underline to the token hover color.
+3. Update `src/renderer/subtitle-render.test.ts` to verify JLPT hover/selection rules keep the predefined JLPT underline color, then rerun focused and relevant verification commands.
+
+4. Add JLPT-specific `text-decoration-color` overrides directly on child `.c` spans and their hover/selection states, since Yomitan lookup likely paints the decorated child text runs rather than only the parent token span.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added a renderer regression test that asserts JLPT underline color stays explicit through hover and selection styling.
+
+Updated `src/renderer/style.css` to route JLPT underline color through `--subtitle-jlpt-underline-color` and re-apply it on word/character hover and selection states.
+
+Verification: `bun test src/renderer/subtitle-render.test.ts`, `bun run typecheck`, `bun run test:fast`, `bun run build`, `bun run changelog:lint`, `bunx prettier --check src/renderer/style.css src/renderer/subtitle-render.test.ts changes/jlpt-underline-yomitan.md`. `bun run format:check:src` still fails because of unrelated existing formatting issues in `src/main-entry-runtime.test.ts` and `src/main-entry-runtime.ts`.
+
+User verified the original CSS variable propagation fix did not resolve the live issue; continuing investigation and reopening the task.
+
+Confirmed Chromium was repainting native `text-decoration` underlines with the selected text color; reproduced it in a temporary browser repro and verified that switching the JLPT marker to an inset box-shadow keeps the JLPT color stable during selection.
+
+Replaced the previous native underline approach with a fragment-safe JLPT marker using `box-shadow` plus `box-decoration-break`, then updated stylesheet regression coverage to match the new implementation.
+
+Verification: `bun test src/renderer/subtitle-render.test.ts`, `bunx prettier --check src/renderer/style.css src/renderer/subtitle-render.test.ts`, `bun run typecheck`, `bun run test:fast`, `bun run build`.
+
+User requested reverting the box-shadow marker experiment. Narrowing the fix to preserve native JLPT underline color during Yomitan hover/selection instead of changing the underline rendering method.
+
+Reverted the box-shadow experiment per user request. Restored native JLPT underline styling and added explicit JLPT hover/selection rules so Yomitan lookup states keep the predefined JLPT underline color with `!important`.
+
+Verification after revert/fix: `bun test src/renderer/subtitle-render.test.ts`, `bunx prettier --check src/renderer/style.css src/renderer/subtitle-render.test.ts`, `bun run typecheck`, `bun run build`.
+
+Issue still reproduces specifically during Shift-held Yomitan lookup. Investigating decoration propagation onto child `.c` spans during lookup-triggered hover/selection states.
+
+Added JLPT-specific `text-decoration-color` overrides directly to child `.c` spans and their hover/selection states, in addition to the token span itself, so lookup-triggered decoration painting on child runs keeps the JLPT color.
+
+Verification: `bun test src/renderer/subtitle-render.test.ts`, `bunx prettier --check src/renderer/style.css src/renderer/subtitle-render.test.ts`, `bun run typecheck`, `bun run build`.
+
+Added a final high-specificity combined-state JLPT override after the annotation hover/selection rules. It targets tokens that are both JLPT-tagged and known/N+1/name-match/frequency-highlighted, forcing `text-decoration-color` back to the JLPT variable after the later annotation state blocks.
+
+Verification: `bun test src/renderer/subtitle-render.test.ts`, `bunx prettier --check src/renderer/style.css src/renderer/subtitle-render.test.ts`, `bun run build`.
+
+Switched the JLPT underline from native `text-decoration` to a separate painted underline layer using `background-image` on JLPT tokens. Also changed hover token highlight rules to use `background-color` so the JLPT underline layer survives Shift+Yomitan hover/lookup interactions.
+
+Verification: `bun test src/renderer/subtitle-render.test.ts`, `bunx prettier --check src/renderer/style.css src/renderer/subtitle-render.test.ts`, `bun run build`.
+
+User reports the latest background-image JLPT underline change introduced grey-looking token highlights. Investigating the interaction between the new underline layer and hover background styling.
+
+The background-image underline layer interacts poorly with hover fills and makes highlighted tokens look grey. Switching the separate JLPT underline layer to an inset box-shadow so hover background color and JLPT underline paint can coexist cleanly.
+
+Adjusted the separate JLPT underline layer from `background-image` to inset `box-shadow`. This keeps the underline decoupled from Yomitan hover color while avoiding the grey-looking underline artifact introduced by the background-image approach.
+
+User reports the separate underline layer still disappears/greys out during lookup. Switching strategy again: use a dedicated `border-bottom` JLPT marker instead of box-shadow/background so the underline stays independent from Yomitan hover paint without blending artifacts.
+
+Replaced the separate JLPT underline layer with `border-bottom` plus a small bottom padding. This keeps the underline visually separate from Yomitan hover paint and avoids the disappearing/grey artifact seen with background-image and box-shadow.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Switched the JLPT underline layer in `src/renderer/style.css` to `border-bottom` plus `padding-bottom`, keeping it independent from Yomitan hover/selection repainting while avoiding the disappearing or grey artifact seen with the background-image and box-shadow approaches.
+
+Updated `src/renderer/subtitle-render.test.ts` to assert the border-bottom-based JLPT underline layer.
+
+Verification: `bun test src/renderer/subtitle-render.test.ts`, `bunx prettier --check src/renderer/style.css src/renderer/subtitle-render.test.ts`, `bun run build`.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Fix-early-Electron-userData-path-casing-to-stay-under-SubMiner-config-dir.md
+++ b/Fix-early-Electron-userData-path-casing-to-stay-under-SubMiner-config-dir.md
@@ -0,0 +1,66 @@
+---
+id: TASK-152
+title: Fix early Electron userData path casing to stay under SubMiner config dir
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-10 06:46'
+updated_date: '2026-03-16 05:13'
+labels:
+  - bug
+  - config
+  - electron
+dependencies: []
+references:
+  - /home/sudacode/projects/japanese/SubMiner/src/main-entry.ts
+  - /home/sudacode/projects/japanese/SubMiner/src/main.ts
+  - /home/sudacode/projects/japanese/SubMiner/src/config/path-resolution.ts
+documentation:
+  - /home/sudacode/projects/japanese/subminer-docs/development.md
+  - /home/sudacode/projects/japanese/subminer-docs/architecture.md
+priority: high
+ordinal: 34500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Electron startup touches the app object before the main-process bootstrap overrides userData, which can create/write the default lowercase ~/.config/subminer directory on Linux/macOS. Ensure early startup pins the app identity and userData path to the canonical SubMiner config directory before any Electron APIs can materialize the default path, and keep regression coverage around the bootstrap path behavior.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Electron startup uses the canonical SubMiner config directory as userData before other Electron app calls can create the default lowercase directory.
+- [x] #2 Regression tests cover the early bootstrap path setup and fail if startup falls back to a lowercase subminer config path.
+- [x] #3 Existing config path resolution behavior for SubMiner casing remains intact.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add regression coverage for early Electron bootstrap path setup, including a case that would otherwise fall back to lowercase subminer.
+2. Extract a pure helper that computes and applies the canonical app name/userData path from config resolution.
+3. Call the helper from main-entry before any Electron app interactions that could materialize the default userData directory.
+4. Run focused tests for startup/config path behavior, then the relevant fast gate if green.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added early Electron bootstrap path setup in src/main-entry so app name and userData are pinned to the canonical SubMiner config dir before single-instance/whenReady handling.
+
+Added a regression test in src/main-entry-runtime.test.ts covering the lowercase subminer fallback case.
+
+Validation: bun test src/main-entry-runtime.test.ts src/config/path-resolution.test.ts; bun run typecheck. bun run test:fast still fails on an existing unrelated renderer JLPT CSS test in src/renderer/subtitle-render.test.ts.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Pinned Electron's app identity and userData path during entry bootstrap so startup uses the canonical SubMiner config directory before any other Electron app calls can materialize the default lowercase path. Added a regression test covering the lowercase subminer fallback case and kept existing config-path resolution coverage green.
+
+Validation:
+- bun test src/main-entry-runtime.test.ts src/config/path-resolution.test.ts
+- bun run typecheck
+- bun run test:fast (fails on existing unrelated JLPT CSS renderer test in src/renderer/subtitle-render.test.ts)
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Fix-character-dictionary-MRU-eviction-after-revisits.md
+++ b/Fix-character-dictionary-MRU-eviction-after-revisits.md
@@ -0,0 +1,69 @@
+---
+id: TASK-153
+title: Fix character dictionary MRU eviction after revisits
+status: Done
+assignee:
+  - '@codex'
+created_date: '2026-03-10 07:56'
+updated_date: '2026-03-16 05:13'
+labels:
+  - character-dictionary
+  - yomitan
+  - anilist
+dependencies: []
+references:
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.test.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
+documentation:
+  - /home/sudacode/projects/japanese/subminer-docs/development.md
+  - /home/sudacode/projects/japanese/subminer-docs/architecture.md
+priority: high
+ordinal: 32500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Keep merged character dictionary retention truly MRU-based when a currently retained anime is revisited before opening a new title, so the oldest retained title is evicted instead of the revisited one.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Revisiting an anime already retained in the merged character dictionary updates MRU ordering before the next new title is added.
+- [x] #2 When retention exceeds maxLoaded after that revisit-plus-new-title sequence, the least recently used retained anime is evicted rather than the revisited title.
+- [x] #3 Auto-sync rebuilds or reloads the merged dictionary so an evicted anime becomes available again when reopened.
+- [x] #4 Regression tests cover the revisit-before-eviction flow.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Reproduce the revisit-before-eviction scenario with a focused regression test in `src/main/runtime/character-dictionary-auto-sync.test.ts` using a retained set that revisits an existing anime before introducing a new anime.
+2. Run the focused test to confirm current behavior fails for the expected MRU ordering / eviction case.
+3. Adjust `src/main/runtime/character-dictionary-auto-sync.ts` so retained ordering stays MRU-correct across revisits and subsequent additions without regressing unchanged revisit behavior.
+4. Re-run the focused auto-sync suite, then run the relevant broader checks required for handoff.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added a focused regression in `src/main/runtime/character-dictionary-auto-sync.test.ts` for the `1,2,3,1,4,1` revisit-before-eviction flow. The current MRU auto-sync logic passed: merged builds were `[1]`, `[2,1]`, `[3,2,1]`, `[1,3,2]`, `[4,1,3]`, `[1,4,3]`, so I have not reproduced the reported eviction bug in the in-process auto-sync service yet.
+
+Inspected local cache under `~/.config/SubMiner/character-dictionaries/` and found Little Witch Academia snapshot `anilist-21858.json` already present, so the reported regeneration path was not a snapshot-cache miss. The on-disk `merged.zip` revision (`9251ae23e136`) also differed from `auto-sync-state.json` (`bc16c5b5af17`), indicating a rebuilt merged dictionary artifact could land without the MRU state being persisted.
+
+Fixed `src/main/runtime/character-dictionary-auto-sync.ts` to persist the rebuilt retained-set state immediately after a merged dictionary revision/title is known, before later Yomitan mutation steps. This keeps MRU eviction state aligned even if import/settings work fails after the rebuild artifact is written.
+
+Added regression coverage in `src/main/runtime/character-dictionary-auto-sync.test.ts` for the revisit-before-eviction sequence and for post-build import failure preserving the rebuilt MRU state. Verified with `bun test src/main/runtime/character-dictionary-auto-sync.test.ts src/main/character-dictionary-runtime.test.ts`, `bun run typecheck`, `bun run changelog:lint`, and `bun run test:fast`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Persisted merged character-dictionary MRU state as soon as a rebuilt retained set is known in `src/main/runtime/character-dictionary-auto-sync.ts`, so revisits are not lost if later Yomitan import/settings work fails after `merged.zip` has already been rewritten. Added regression coverage for revisit-before-eviction ordering and import-failure state preservation in `src/main/runtime/character-dictionary-auto-sync.test.ts`, plus a changelog fragment in `changes/character-dictionary-mru-state-recovery.md`.
+
+Validation: `bun test src/main/runtime/character-dictionary-auto-sync.test.ts src/main/character-dictionary-runtime.test.ts`, `bun run typecheck`, `bun run changelog:lint`, `bun run test:fast`.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Avoid-merged-dictionary-rebuilds-on-MRU-reorder-only-revisits.md
+++ b/Avoid-merged-dictionary-rebuilds-on-MRU-reorder-only-revisits.md
@@ -0,0 +1,69 @@
+---
+id: TASK-154
+title: Avoid merged dictionary rebuilds on MRU reorder-only revisits
+status: Done
+assignee:
+  - '@codex'
+created_date: '2026-03-10 09:16'
+updated_date: '2026-03-16 05:13'
+labels:
+  - character-dictionary
+  - yomitan
+  - anilist
+dependencies: []
+references:
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.test.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.test.ts
+documentation:
+  - /home/sudacode/projects/japanese/subminer-docs/development.md
+  - /home/sudacode/projects/japanese/subminer-docs/architecture.md
+priority: high
+ordinal: 31500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Keep per-title MRU retention ordering for eviction decisions, but do not rebuild or reimport the merged character dictionary when the retained set membership is unchanged and only the MRU order changes.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Revisiting an anime already inside the retained set updates MRU ordering used for later eviction decisions without rebuilding or reimporting the merged dictionary when retained membership is unchanged.
+- [x] #2 Merged dictionary revisions and contents are stable for the same retained membership regardless of MRU ordering.
+- [x] #3 Adding a new anime that changes retained membership still rebuilds and imports the merged dictionary with the correct eviction behavior.
+- [x] #4 Regression tests cover reorder-only revisits and stable merged revisions for equivalent retained sets.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a failing auto-sync regression showing that a revisit which only reorders MRU state should update `activeMediaIds` but skip merged rebuild/import.
+2. Add a runtime-level regression showing `buildMergedDictionary` produces a stable revision for equivalent retained memberships regardless of input order.
+3. Update merged-dictionary build normalization and auto-sync rebuild gating so rebuilds are driven by retained membership changes (or snapshot changes), not MRU reordering alone.
+4. Re-run focused dictionary tests plus the local verification lanes impacted by the change.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Changed `src/main/runtime/character-dictionary-auto-sync.ts` so MRU order still updates in `activeMediaIds`, but merged rebuild/import now keys off retained membership changes rather than order-only reordering. Order-only revisits no longer force a merged ZIP rewrite or Yomitan reimport.
+
+Changed `src/main/character-dictionary-runtime.ts` to canonicalize merged dictionary media ids before building, which makes merged revisions stable for equivalent retained memberships regardless of MRU ordering.
+
+Updated regression coverage in `src/main/runtime/character-dictionary-auto-sync.test.ts` for reorder-only revisits and membership-change rebuilds, and extended `src/main/character-dictionary-runtime.test.ts` to assert stable merged revisions for reordered inputs. Verified with `bun test src/main/runtime/character-dictionary-auto-sync.test.ts src/main/character-dictionary-runtime.test.ts`, `bun run typecheck`, `bun run changelog:lint`, and `bun run test:fast`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Updated merged character-dictionary syncing so MRU ordering is still tracked for eviction in `src/main/runtime/character-dictionary-auto-sync.ts`, but reorder-only revisits no longer rebuild or reimport the merged dictionary unless retained membership or snapshot data changes. Canonicalized merged build input ordering in `src/main/character-dictionary-runtime.ts` so revisions remain stable for the same retained set regardless of MRU order, and added regressions in `src/main/runtime/character-dictionary-auto-sync.test.ts` plus `src/main/character-dictionary-runtime.test.ts`. Also updated `changes/character-dictionary-mru-state-recovery.md` to cover the new behavior.
+
+Validation: `bun test src/main/runtime/character-dictionary-auto-sync.test.ts src/main/character-dictionary-runtime.test.ts`, `bun run typecheck`, `bun run changelog:lint`, `bun run test:fast`.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Move-user-docs-site-back-into-main-repo.md
+++ b/Move-user-docs-site-back-into-main-repo.md
@@ -0,0 +1,50 @@
+---
+id: TASK-155
+title: Move user docs site back into main repo
+status: Done
+assignee: []
+created_date: '2026-03-10 19:20'
+updated_date: '2026-03-10 19:38'
+labels: []
+dependencies: []
+priority: medium
+ordinal: 15500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+
+Move the standalone VitePress docs site from the sibling `../subminer-docs` checkout back into the main `SubMiner` repo so docs can be updated alongside code and local tooling can reference one repository.
+
+Scope:
+
+- import the tracked docs-site source into a dedicated in-repo subdirectory
+- update scripts/tests/docs instructions that assume a sibling `../subminer-docs` checkout
+- preserve Cloudflare Pages deployability from a repo subdirectory
+- verify the app repo and docs site both still build/test from the new layout
+
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+
+<!-- AC:BEGIN -->
+
+- [x] #1 The user-facing VitePress docs source lives inside the `SubMiner` repo in a dedicated subdirectory.
+- [x] #2 First-party scripts/tests/docs no longer require `../subminer-docs` for normal operation.
+- [x] #3 In-repo docs instructions include the Cloudflare Pages subdirectory deploy settings.
+- [x] #4 Verification covers the relocated docs site build/tests plus affected app-repo checks.
+
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+
+Imported the VitePress site into `docs-site/` inside the main repo and updated project instructions, docs contributor guidance, generator logic, and regression tests to treat that in-repo directory as the docs source of truth.
+
+Added root proxy scripts for `docs:dev`, `docs:build`, `docs:preview`, and `docs:test`, repointed config-example generation to `docs-site/public/config.example.jsonc`, switched docs edit links to the main `SubMiner` repo, and documented the Cloudflare Pages subdirectory settings (`docs-site` root, `.vitepress/dist` output, `docs-site/**` watch path).
+
+Verified with `bun run format:check:src`, `bun run typecheck`, `bun run docs:test`, `bun run docs:build`, `bun run test:config:src`, and `bun run test:fast`.
+
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Fix-docs-site-Plausible-geo-attribution-through-analytics-worker.md
+++ b/Fix-docs-site-Plausible-geo-attribution-through-analytics-worker.md
@@ -0,0 +1,37 @@
+---
+id: TASK-156
+title: Fix docs-site Plausible geo attribution through analytics worker
+status: Done
+assignee: []
+created_date: '2026-03-11 02:19'
+updated_date: '2026-03-16 05:13'
+labels:
+  - docs-site
+  - analytics
+dependencies: []
+priority: medium
+ordinal: 99500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Investigate and fix missing city/region data for docs.subminer.moe visits in Plausible. The docs site already proxies analytics events to worker.subminer.moe, so the remaining work is to verify and correct the worker-side forwarding contract Plausible needs for geolocation.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 The analytics worker forwards Plausible event requests in a way that preserves the original client IP information needed for location attribution.
+- [ ] #2 The docs-site analytics flow remains proxied through worker.subminer.moe after the fix.
+- [ ] #3 Coverage or documentation records the worker-side header/forwarding requirement for Plausible geo reporting.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Worker implementation lives in `/home/sudacode/projects/blog-proxy`, not in the SubMiner repo.
+
+Patched `worker.js` to forward client IP via `x-forwarded-for`/`x-real-ip` from `cf-connecting-ip` (fallbacks retained) and added `worker.test.js` regression coverage.
+
+Local verification in `blog-proxy`: `node --test worker.test.js` passes. Deployment not performed in this session.
+<!-- SECTION:NOTES:END -->
--- a/Fix-Cloudflare-Pages-watch-path-for-docs-site.md
+++ b/Fix-Cloudflare-Pages-watch-path-for-docs-site.md
@@ -0,0 +1,35 @@
+---
+id: TASK-157
+title: Fix Cloudflare Pages watch path for docs-site
+status: Done
+assignee: []
+created_date: '2026-03-10 20:15'
+updated_date: '2026-03-16 05:13'
+labels:
+  - docs-site
+  - cloudflare
+dependencies: []
+priority: medium
+ordinal: 98500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Cloudflare Pages skipped a docs-site deployment after the docs repo moved into the main `SubMiner` repository. The documented/configured watch path uses `docs-site/**`, but Pages monorepo watch paths use a single `*` wildcard pattern. Correct the documented setting and leave a regression test so future repo moves or docs rewrites do not reintroduce the bad pattern.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Docs contributor guidance points Cloudflare Pages watch paths at `docs-site/*`, not `docs-site/**`.
+- [x] #2 Regression coverage fails if the docs revert to the incorrect watch-path string.
+- [x] #3 Implementation notes record that the Cloudflare dashboard setting must be updated manually and the docs deploy retriggered.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added docs regression coverage in `docs-site/docs-sync.test.ts` for the Pages watch-path string, then corrected the Cloudflare Pages instructions in `docs-site/README.md` and `docs-site/development.md`.
+
+Manual follow-up still required outside git: update the Cloudflare Pages project include path from `docs-site/**` to `docs-site/*`, then trigger a fresh deployment against `main`.
+<!-- SECTION:NOTES:END -->
--- a/Enforce-generated-config-example-drift-checks.md
+++ b/Enforce-generated-config-example-drift-checks.md
@@ -0,0 +1,44 @@
+---
+id: TASK-158
+title: Enforce generated config example drift checks
+status: Done
+assignee: []
+created_date: '2026-03-10 20:35'
+updated_date: '2026-03-16 05:13'
+labels:
+  - config
+  - docs-site
+dependencies: []
+priority: medium
+ordinal: 30500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+The generated `config.example.jsonc` artifact is covered by generation-path tests, but there is no hard gate that fails when the checked-in example drifts from the canonical template. The in-repo docs-site copy can also drift silently.
+
+Scope:
+
+- add a first-party verification path that compares generated config-example content against committed artifacts
+- fail fast when repo-root `config.example.jsonc` is stale or missing
+- fail fast when `docs-site/public/config.example.jsonc` is stale or missing, when the docs site exists
+- wire the verification into the normal gate and release flow
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Automated verification fails when repo-root `config.example.jsonc` is missing or stale.
+- [x] #2 Automated verification fails when in-repo docs-site `public/config.example.jsonc` is missing or stale, when docs-site exists.
+- [x] #3 CI/release or equivalent project gates run the verification automatically.
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added `src/verify-config-example.ts`, which renders the canonical config template and compares it against the checked-in repo-root `config.example.jsonc` plus `docs-site/public/config.example.jsonc` when the docs site exists.
+
+Wired the new verification into `package.json` as `bun run verify:config-example`, added regression coverage for missing and stale artifacts, and enforced the new check in both CI and release workflows.
+
+Regenerated the checked-in config example artifacts so the new gate passes in the repo-local docs-site layout, and documented the release-step expectation in `docs/RELEASING.md`.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Create-SubMiner-automated-testing-skill-for-agents.md
+++ b/Create-SubMiner-automated-testing-skill-for-agents.md
@@ -0,0 +1,59 @@
+---
+id: TASK-159
+title: Create SubMiner automated testing skill for agents
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-11 05:55'
+updated_date: '2026-03-16 05:13'
+labels:
+  - tooling
+  - testing
+  - skills
+dependencies: []
+priority: medium
+ordinal: 29500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Design and implement a SubMiner-specific skill that agents can use to verify code changes with automated checks across launcher, mpv, overlay, and related workflows.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Define the skill trigger surface and intended use cases for SubMiner change verification.
+- [x] #2 Implement a SubMiner-specific skill package with concise workflow guidance and any required helper scripts or references.
+- [x] #3 Document how agents should run automated verification for common SubMiner change types, including launcher/mpv/overlay-sensitive changes.
+- [x] #4 Verify the skill itself is usable in this repo context.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a design doc at `docs/plans/2026-03-10-subminer-change-verification-design.md` capturing the approved skill contract, lane selection rules, helper script design, and trigger/workflow guidance.
+2. Create an in-repo source package for the new SubMiner-specific verification skill with `SKILL.md` plus helper shell scripts for diff classification and coordinated verification/artifact capture.
+3. Implement cheap-first verification logic: map changed paths to verification lanes, run repo-native commands, capture stdout/stderr and metadata under `.tmp/skill-verification/<timestamp>/`, and report pass/fail/skipped states with artifact paths.
+4. Encode repo-specific heuristics for docs/config, launcher/plugin, runtime/dist, and optional real-GUI escalation guidance without making GUI launch the default.
+5. Verify the skill locally by running the classifier/verifier against representative paths and confirming artifact generation and summaries.
+6. Optionally install the finished skill to `~/.codex/skills/subminer-change-verification/` after user approval because that target is outside the writable sandbox.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Planned outputs: SKILL.md plus small helper shell scripts for diff classification and coordinated verification/artifact capture. Default to repo-native commands; only escalate to real GUI/mpv verification when affected paths or requested behavior require it.
+
+2026-03-10: Brainstorming completed with user approval for a SubMiner-specific automated verification skill. Chosen shape: auto-triggering, cheap-first verification workflow with optional real GUI/mpv escalation and artifact capture.
+
+2026-03-10: Added design doc at docs/plans/2026-03-10-subminer-change-verification-design.md and created the in-repo skill source at tools/skills/subminer-change-verification/.
+
+2026-03-10: Verified classifier output with representative launcher/runtime/config/docs paths and ran the verifier in dry-run mode plus one real config lane (`bun run test:config`). Artifacts written under .tmp/skill-verification/20260310-231320 and .tmp/skill-verification/20260310-231326.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Implemented a SubMiner-specific change verification skill source with a concise SKILL.md, a diff classifier, and a cheap-first verifier that captures artifacts under `.tmp/skill-verification/`. Verified the flow with representative path classification, a dry-run multi-lane plan, and a passing real config verification run.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Create-repo-local-scrum-master-orchestration-skill.md
+++ b/Create-repo-local-scrum-master-orchestration-skill.md
@@ -0,0 +1,58 @@
+---
+id: TASK-160
+title: Create repo-local scrum master orchestration skill
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-11 06:32'
+updated_date: '2026-03-16 05:13'
+labels:
+  - skills
+  - workflow
+  - backlog
+  - subagents
+  - automation
+dependencies: []
+priority: high
+ordinal: 28500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Design and implement a repo-local skill that can turn incoming requests/issues into well-scoped Backlog tasks, then coordinate one or more subagents to implement and verify the resulting work using the repo's established skills and verification workflow.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Define the trigger surface, responsibilities, and limits of the scrum master skill for request intake, backlog updates, and execution orchestration.
+- [x] #2 Implement the skill package with concise guidance for intake, task search/create/update, planning, and subagent dispatch.
+- [x] #3 Specify how the skill coordinates with existing repo workflows, including Backlog.md requirements and SubMiner change verification.
+- [x] #4 Verify the skill is usable in this repo context for at least one representative request flow.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a design doc at `docs/plans/2026-03-10-subminer-scrum-master-design.md` capturing the approved contract, backlog decision rules, orchestration policy, and verification handoff.
+2. Create the repo-local skill at `.agents/skills/subminer-scrum-master/` with a concise `SKILL.md`.
+3. Keep v1 instruction-heavy: backlog-or-not decision first, search/create/update task structure when needed, require planning before dispatch, use parent + subtasks for multi-part work, dispatch conservatively with explicit ownership, and require `subminer-change-verification` before handoff.
+4. Include representative flows for trivial no-ticket work, single-task implementation, and multi-part parent+subtask execution.
+5. Verify the skill in-repo with one representative request flow and update `TASK-160` with results.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+V1 will be instruction-heavy rather than script-heavy. The skill will decide whether backlog is warranted, record plans before dispatch, create parent+subtasks when needed, dispatch conservatively with explicit ownership, and require `subminer-change-verification` before handoff.
+
+2026-03-10: Added design doc at docs/plans/2026-03-10-subminer-scrum-master-design.md and created the repo-local skill at .agents/skills/subminer-scrum-master/.
+
+2026-03-10: Verified the skill against a representative request flow ('Fix launcher auto-start pause bug and make sure it is verified') by checking that the instructions cover backlog decisioning, planning-before-dispatch, single-task execution, explicit worker ownership, and verification via subminer-change-verification.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Implemented a repo-local `subminer-scrum-master` skill that assesses whether backlog tracking is needed, manages task structure and planning when appropriate, dispatches subagents conservatively, and requires verification before handoff. Verified the skill in-repo against a representative launcher bug workflow.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Add-Arch-Linux-PKGBUILD-and-.SRCINFO-for-SubMiner-release-artifacts.md
+++ b/Add-Arch-Linux-PKGBUILD-and-.SRCINFO-for-SubMiner-release-artifacts.md
@@ -0,0 +1,69 @@
+---
+id: TASK-161
+title: Add Arch Linux PKGBUILD and .SRCINFO for SubMiner release artifacts
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-11 07:50'
+updated_date: '2026-03-16 05:13'
+labels:
+  - packaging
+  - linux
+  - docs
+dependencies: []
+references:
+  - package.json
+  - .github/workflows/release.yml
+  - README.md
+documentation:
+  - docs-site/development.md
+  - docs-site/installation.md
+  - docs/RELEASING.md
+priority: medium
+ordinal: 27500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Add repo-maintained Arch packaging metadata so Arch/AUR users can install the packaged SubMiner release artifacts without relying on npm. Cover the binary package flow that matches the current GitHub Releases distribution model and document the install path for Arch users.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 A dedicated Arch packaging directory exists with a PKGBUILD and matching .SRCINFO for the SubMiner binary release flow.
+- [x] #2 The package installs the shipped Linux release artifact and wrapper in paths consistent with current runtime auto-detection expectations.
+- [x] #3 Package metadata declares the required Arch runtime dependencies for the packaged workflow.
+- [x] #4 The packaging files remain isolated from the main app/release/docs surfaces so they can be moved to a separate repository later.
+- [x] #5 The packaging metadata is validated with an appropriate local Arch packaging check or an explicitly documented limitation if the tool is unavailable in this environment.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add isolated Arch packaging under packaging/arch/subminer-bin for the binary release flow that matches current GitHub Releases artifacts.
+2. Install the Linux AppImage to /opt/SubMiner/SubMiner.AppImage, add PATH symlinks for SubMiner.AppImage and subminer, and ship optional plugin/theme/config assets under /usr/share/subminer.
+3. Generate and commit matching .SRCINFO metadata in the same packaging directory.
+4. Validate the PKGBUILD metadata locally with shell parsing plus makepkg --printsrcinfo and namcap if available.
+5. Leave the new files isolated so they can be moved to a separate packaging repository later.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+User requested no commit and no broad repo integration; keep the Arch packaging files isolated in a dedicated directory for later extraction.
+
+Created isolated Arch packaging under packaging/arch/subminer-bin with PKGBUILD and generated .SRCINFO only; no docs or release workflow changes.
+
+Validation run: bash -n PKGBUILD, makepkg --printsrcinfo > .SRCINFO, namcap PKGBUILD.
+
+PKGBUILD uses current v0.5.6 GitHub release assets and recorded SHA-256 values for SubMiner-0.5.6.AppImage, subminer, and subminer-assets.tar.gz.
+
+Per user follow-up, moved packaging/arch/subminer-bin out of the repo to /home/sudacode/packages/maintaining/subminer-bin for separate maintenance. Repo docs/workflows were still left untouched.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added an isolated Arch Linux packaging directory at packaging/arch/subminer-bin containing a `subminer-bin` PKGBUILD and generated `.SRCINFO`. The package installs the current GitHub release AppImage to `/opt/SubMiner/SubMiner.AppImage`, adds PATH access for `SubMiner.AppImage` and `subminer`, and ships optional plugin/theme/config assets under `/usr/share/subminer`. Verified locally with `bash -n PKGBUILD`, `makepkg --printsrcinfo`, and `namcap PKGBUILD`.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Normalize-packaged-Linux-paths-to-canonical-SubMiner-directories.md
+++ b/Normalize-packaged-Linux-paths-to-canonical-SubMiner-directories.md
@@ -0,0 +1,66 @@
+---
+id: TASK-162
+title: Normalize packaged Linux paths to canonical SubMiner directories
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-11 08:28'
+updated_date: '2026-03-18 05:28'
+labels:
+  - linux
+  - packaging
+  - docs
+dependencies: []
+references:
+  - launcher/mpv.ts
+  - launcher/picker.ts
+  - plugin/subminer/binary.lua
+  - plugin/subminer.conf
+  - docs-site/installation.md
+  - docs-site/launcher-script.md
+  - README.md
+priority: medium
+ordinal: 116500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Align packaged Linux path conventions so system-installed assets use canonical `SubMiner` directories and match runtime auto-detection. Cover AppImage binary discovery, rofi theme discovery/docs, and related path references while preserving lowercase names only for the launcher wrapper, rofi theme filename, and mpv Lua plugin/conf.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Launcher/runtime path discovery prefers canonical packaged Linux locations that use `SubMiner` casing for shared data and config directories.
+- [x] #2 Tests cover the expected packaged Linux discovery paths for the AppImage and rofi theme search behavior.
+- [x] #3 User-facing docs reference the canonical packaged Linux locations consistently.
+- [x] #4 Lowercase names remain only where intentionally required for the launcher wrapper, rofi theme filename, and mpv Lua plugin/conf.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add failing launcher tests for canonical packaged Linux discovery paths: /usr/lib/subminer/SubMiner.AppImage via PATH symlink flow and /usr/share/SubMiner/themes/subminer.rasi for rofi theme lookup.
+2. Update launcher runtime path discovery to prefer canonical packaged Linux shared-data locations using SubMiner casing.
+3. Update plugin auto-detection comments and binary search defaults so packaged Linux paths stay consistent with launcher/runtime expectations.
+4. Update user-facing docs to reference canonical SubMiner-cased config/share paths while keeping lowercase names only for the launcher wrapper, rofi theme filename, and mpv Lua plugin/conf.
+5. Run targeted launcher tests plus docs checks.
+
+Remaining work (2026-03-15):
+- binary.lua: add lowercase fallback candidates /usr/bin/subminer and /usr/local/bin/subminer after existing title-case entries
+- launcher tests: add findAppBinary Linux candidates and findRofiTheme /usr/share + /usr/local/share tests
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+2026-03-15: Adding launcher tests for Linux packaged path discovery (findAppBinary + findRofiTheme). Implementing in mpv.test.ts and new picker.test.ts following node:test / assert/strict patterns from mpv.test.ts.
+
+2026-03-15: AC#2 complete. Added findAppBinary tests (3) to launcher/mpv.test.ts and findRofiTheme tests (4) to new launcher/picker.test.ts. All 76 launcher tests pass. Added picker.test.ts to test:launcher:src script.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+## Completed changes\n\n### `plugin/subminer/binary.lua`\nAdded lowercase fallback candidates after existing title-case entries in the non-Windows `find_binary()` search list:\n- `/usr/local/bin/subminer` (after `/usr/local/bin/SubMiner`)\n- `/usr/bin/subminer` (after `/usr/bin/SubMiner`)\n\n### `plugin/subminer.conf`\nUpdated the comment documenting the Linux binary search list to include the two new lowercase candidates.\n\n### `launcher/mpv.test.ts`\nAdded 3 new tests for `findAppBinary` Linux candidates:\n- Resolves `~/.local/bin/SubMiner.AppImage` when it exists\n- Resolves `/opt/SubMiner/SubMiner.AppImage` when `~/.local/bin` candidate absent\n- Finds `subminer` on PATH when AppImage candidates absent\n\n### `launcher/picker.test.ts` (new file)\nAdded 4 tests for `findRofiTheme` Linux packaged paths:\n- Resolves `/usr/local/share/SubMiner/themes/subminer.rasi`\n- Resolves `/usr/share/SubMiner/themes/subminer.rasi` when `/usr/local/share` absent\n- Resolves `$XDG_DATA_HOME/SubMiner/themes/subminer.rasi` when set\n- Resolves `~/.local/share/SubMiner/themes/subminer.rasi` when `XDG_DATA_HOME` unset\n\n### `package.json`\nAdded `launcher/picker.test.ts` to `test:launcher:src` file list.\n\n## Verification\n- `launcher-plugin` lane: passed (76 launcher tests, 524 fast tests — all green)\n\n## Policy checks\n- Docs update required? No — docs already reflected canonical paths.\n- Changelog fragment required? Yes — user-visible fix to plugin binary auto-detection. Fragment should be added under `changes/`.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Resolve-current-lint-format-and-style-check-failures.md
+++ b/Resolve-current-lint-format-and-style-check-failures.md
@@ -0,0 +1,74 @@
+---
+id: TASK-163
+title: 'Resolve current lint, format, and style check failures'
+status: Done
+assignee:
+  - Codex
+created_date: '2026-03-11 08:48'
+updated_date: '2026-03-16 05:13'
+labels:
+  - maintenance
+  - tooling
+dependencies: []
+references:
+  - /home/sudacode/projects/japanese/SubMiner/package.json
+  - /home/sudacode/projects/japanese/SubMiner/docs-site/development.md
+  - /home/sudacode/projects/japanese/SubMiner/docs-site/architecture.md
+ordinal: 26500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Run the repo's maintained static/style gates, fix any failures they report, and leave the working tree with those checks passing without disturbing unrelated in-progress work.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 The repo's maintained static/style commands for this cleanup are identified and recorded.
+- [x] #2 Any failures from those commands are fixed in-scope in the codebase.
+- [x] #3 The same static/style commands pass after the fixes.
+- [x] #4 Verification results and any skipped checks are documented before handoff.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Run the maintained static/style gates for this repo: `bun run typecheck` and `bun run format:check:src`.
+2. Inspect each failure and patch only the files implicated by the failing command, preserving unrelated user changes.
+3. Re-run the failing gate after each fix until both commands pass.
+4. Run one final consolidated verification pass, record exact commands/results, and note any intentionally skipped broader gates outside lint/style scope.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Identified maintained commands from repo docs/scripts: `bun run typecheck` and `bun run format:check:src`. `changelog:lint` exists but is release-fragment specific, not a general lint/style gate for this request.
+
+Ran `bun run typecheck` at 2026-03-11 01:48 PDT: passed.
+
+Ran `bun run format:check:src` at 2026-03-11 01:48 PDT: failed on `src/release-workflow.test.ts`.
+
+Applied a scoped Prettier rewrite with `./node_modules/.bin/prettier --write src/release-workflow.test.ts`.
+
+Re-ran `bun run format:check:src` at 2026-03-11 01:49 PDT: passed.
+
+Re-ran `bun run typecheck` at 2026-03-11 01:49 PDT: passed.
+
+Skipped broader test/build/docs gates because the user asked specifically for lint/format/style cleanup and the only required change was a formatting-only update in one test file.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Resolved the repo's current static/style failure by reformatting `src/release-workflow.test.ts` to match the maintained Prettier scope. The only code change was line wrapping in the `generate:config-example` assertion; behavior did not change.
+
+Verification run:
+- `bun run typecheck`
+- `bun run format:check:src`
+- `./node_modules/.bin/prettier --write src/release-workflow.test.ts`
+- `bun run format:check:src`
+- `bun run typecheck`
+
+Result: both maintained gates requested for this cleanup now pass. Broader build/test/docs lanes were intentionally not run because this task was limited to lint/format/style checks and required a formatting-only fix.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Run-maintained-test-gate-and-fix-failing-regressions.md
+++ b/Run-maintained-test-gate-and-fix-failing-regressions.md
@@ -0,0 +1,69 @@
+---
+id: TASK-164
+title: Run maintained test gate and fix failing regressions
+status: Done
+assignee:
+  - Codex
+created_date: '2026-03-11 08:52'
+updated_date: '2026-03-16 05:13'
+labels:
+  - maintenance
+  - testing
+dependencies: []
+references:
+  - /home/sudacode/projects/japanese/SubMiner/package.json
+  - /home/sudacode/projects/japanese/SubMiner/docs-site/development.md
+  - /home/sudacode/projects/japanese/SubMiner/docs-site/architecture.md
+ordinal: 25500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Execute the repo's maintained test verification flow, fix any regressions surfaced by those commands, and leave the requested test gate passing without disturbing unrelated in-progress work.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 The maintained test commands chosen for this pass are recorded in the task plan.
+- [x] #2 Any test failures encountered in that gate are fixed in-scope with appropriate regression coverage when needed.
+- [x] #3 The same maintained test gate passes after the fixes.
+- [x] #4 Verification results, skips, and remaining risks are documented before handoff.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Run the maintained verification gate documented for local handoff: `bun run test:fast`, `bun run test:env`, `bun run build`, and `bun run test:smoke:dist`.
+2. Stop at the first failing command, inspect the exact failure, and use a red/green loop with the smallest targeted failing test before writing any production-code fix.
+3. Re-run the targeted failing test, then the original failing command, and continue through the remaining gate.
+4. Record results, any skips, and residual risks before handoff.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Using the docs-site recommended local gate as the maintained test/build verification flow for this request.
+
+Ran `bun run test:fast` at 2026-03-11 01:52 PDT: passed.
+
+Ran `bun run test:env` at 2026-03-11 01:53 PDT: passed.
+
+Ran `bun run build` at 2026-03-11 01:53 PDT: passed.
+
+Ran `bun run test:smoke:dist` at 2026-03-11 01:53 PDT: passed.
+
+No failing tests surfaced in the maintained gate, so no production-code or test changes were required in this pass.
+
+Working tree still includes unrelated user edits plus the previously-applied formatting change in `src/release-workflow.test.ts`; this task did not add new source changes.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Executed the repo's maintained local verification gate from the development docs: `bun run test:fast`, `bun run test:env`, `bun run build`, and `bun run test:smoke:dist`.
+
+Result: every command passed. No failing tests surfaced, so no additional fixes or new regression tests were required for this task.
+
+Working tree note: existing unrelated user changes remain in place, along with the prior formatting-only change to `src/release-workflow.test.ts` from TASK-163. This task introduced no new code changes.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Make-controller-configuration-easier-with-inline-remapping-modal.md
+++ b/Make-controller-configuration-easier-with-inline-remapping-modal.md
@@ -0,0 +1,94 @@
+---
+id: TASK-165
+title: Make controller configuration easier with inline remapping modal
+status: To Do
+assignee:
+  - Codex
+created_date: '2026-03-13 00:10'
+updated_date: '2026-03-13 00:10'
+labels:
+  - enhancement
+  - renderer
+  - overlay
+  - input
+  - config
+dependencies:
+  - TASK-159
+references:
+  - src/renderer/modals/controller-select.ts
+  - src/renderer/modals/controller-debug.ts
+  - src/renderer/handlers/gamepad-controller.ts
+  - src/renderer/index.html
+  - src/renderer/style.css
+  - src/renderer/utils/dom.ts
+  - src/preload.ts
+  - src/core/services/ipc.ts
+  - src/main.ts
+  - src/types.ts
+  - src/config/definitions/defaults-core.ts
+  - src/config/definitions/options-core.ts
+  - config.example.jsonc
+  - docs/plans/2026-03-13-overlay-controller-config-remap-design.md
+  - docs/plans/2026-03-13-overlay-controller-config-remap.md
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Replace the current controller-selection-only modal with a denser controller configuration surface that keeps device selection and adds inline controller remapping. The new flow should feel like emulator configuration: pick an overlay action, arm capture, then press the matching controller button, trigger, d-pad direction, or stick direction to bind it. Keep the current overlay-local renderer architecture, preserve controller gating to keyboard-only mode, and retain the separate raw debug modal for troubleshooting.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+
+<!-- AC:BEGIN -->
+- [ ] #1 `Alt+C` opens a controller modal that includes both preferred-controller selection and controller-config editing in one surface.
+- [ ] #2 Controller device selection uses a compact dropdown or equivalent compact picker instead of the current full-height device list.
+- [ ] #3 Each remappable controller action shows its current binding and supports learn/capture, clear, and reset-to-default flows.
+- [ ] #4 Learn mode captures the next fresh controller input edge or stick/d-pad direction, not a held/stale input.
+- [ ] #5 Captured bindings can represent non-standard controllers without depending only on the browser's standard semantic button names.
+- [ ] #6 Updated bindings persist through the existing config pipeline and take effect in the renderer without restart unless a field explicitly requires reopen/reload.
+- [ ] #7 Existing controller behavior remains gated to keyboard-only mode except for the controller action that toggles keyboard-only mode itself.
+- [ ] #8 Renderer/config/IPC regression tests cover the new modal layout, capture flow, persistence, and runtime mapping behavior.
+- [ ] #9 Docs/config example explain the new controller-config flow and when to use the debug modal.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add the design doc and implementation plan for inline controller remapping, tied to a new backlog task instead of reopening the already-completed base controller-support task.
+2. Expand controller config types/defaults/template output so action bindings can store captured input descriptors, not only semantic button-name enums.
+3. Extend preload/main/IPC write paths from preferred-controller-only saves to full controller-config patching needed by the modal.
+4. Redesign the controller modal UI into a compact device picker plus action-binding editor with learn, clear, and reset affordances.
+5. Add renderer capture state and a learn-mode runtime that waits for neutral-to-active transitions before saving a binding.
+6. Update the gamepad runtime to resolve the new stored descriptors into actions while preserving current gating and repeat/deadzone behavior.
+7. Keep the raw debug modal as a separate advanced surface; optionally expose copyable input-descriptor text for troubleshooting.
+8. Add focused regression tests first, then run the maintained gate needed for docs/config/renderer/main changes.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Planning only in this pass.
+
+Current-state findings:
+
+- `src/renderer/modals/controller-select.ts` only persists `preferredGamepadId` / `preferredGamepadLabel`.
+- `src/preload.ts`, `src/core/services/ipc.ts`, and `src/main.ts` only expose a narrow save path for preferred controller, not general controller config writes.
+- `src/renderer/handlers/gamepad-controller.ts` currently resolves actions from semantic button bindings plus a few axis slots; this is fine for defaults but too narrow for emulator-style learn mode on non-standard controllers.
+- `src/renderer/modals/controller-debug.ts` already provides the raw input surface needed for troubleshooting and for validating capture behavior.
+
+Recommended direction:
+
+- keep `Alt+C` as the single controller-config entrypoint
+- keep `Alt+Shift+C` as raw debug
+- introduce stored input descriptors for discrete bindings so learn mode can capture buttons, triggers, d-pad directions, and stick directions directly
+- defer per-controller profiles; keep one global binding set plus preferred-controller selection for this pass
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Planned follow-up work to make controller configuration materially easier than the current “pick preferred device” modal. The proposed change keeps existing controller runtime/debug foundations, but upgrades the selection modal into a compact controller-config surface with inline learn-mode remapping and persistent binding storage.
+
+Main architectural change in scope: move from semantic-button-only binding storage toward captured input descriptors so the UI can reliably learn from buttons, triggers, d-pad directions, and stick directions on non-standard controllers.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Prevent-AUR-upgrade-cache-collisions-for-unversioned-release-assets.md
+++ b/Prevent-AUR-upgrade-cache-collisions-for-unversioned-release-assets.md
@@ -0,0 +1,76 @@
+---
+id: TASK-166
+title: Prevent AUR upgrade cache collisions for unversioned release assets
+status: Done
+assignee:
+  - Codex
+created_date: '2026-03-17 18:10'
+updated_date: '2026-03-18 05:28'
+labels:
+  - release
+  - packaging
+  - linux
+dependencies:
+  - TASK-165
+references:
+  - /home/sudacode/projects/japanese/SubMiner/.github/workflows/release.yml
+  - /home/sudacode/projects/japanese/SubMiner/scripts/update-aur-package.sh
+  - /home/sudacode/projects/japanese/SubMiner/scripts/update-aur-package.test.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/packaging/aur/subminer-bin/PKGBUILD
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/packaging/aur/subminer-bin/.SRCINFO
+priority: medium
+ordinal: 107500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Fix the AUR release metadata generated by the tagged-release workflow so end-user upgrades do not reuse stale cached downloads for unversioned `subminer` and `subminer-assets.tar.gz` source names.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 AUR packaging generated for a new `pkgver` uses versioned local source aliases for the non-versioned GitHub release assets.
+- [x] #2 The package install step references the versioned local launcher filename correctly.
+- [x] #3 Regression coverage fails if metadata generation reintroduces stable cache-colliding source aliases.
+- [x] #4 Targeted verification records the commands run and results.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a failing regression test around `scripts/update-aur-package.sh` output for versioned local source aliases.
+2. Update the repo AUR template and `.SRCINFO` rewrite logic to stamp versioned alias names for `subminer` and `subminer-assets`.
+3. Verify the generated metadata and targeted workflow/package tests, then record results here.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Root cause: the AUR package used stable local source aliases for the unversioned `subminer` and `subminer-assets.tar.gz` GitHub release assets. `makepkg`/AUR helpers can reuse those cached filenames across upgrades, so a stale cached download survives into a newer `pkgver` and then fails checksum validation.
+
+Patched the repo AUR template to version the local cache aliases:
+- `subminer-${pkgver}::.../subminer`
+- `subminer-assets-${pkgver}.tar.gz::.../subminer-assets.tar.gz`
+
+Updated `package()` to install the versioned local wrapper filename, and updated `scripts/update-aur-package.sh` so the generated `.SRCINFO` stamps matching concrete versioned aliases for release automation.
+
+Added regression assertions in `scripts/update-aur-package.test.ts` covering both versioned source aliases and the launcher install path, then watched that test fail before the patch and pass after it.
+
+Verification:
+- `bun test scripts/update-aur-package.test.ts`
+- `bash -n scripts/update-aur-package.sh && bash -n packaging/aur/subminer-bin/PKGBUILD`
+- `bun run typecheck`
+- `bun run test:fast`
+- `bun run test:env`
+- `bun run build`
+- `bun run test:smoke:dist`
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+The tagged-release AUR metadata path now emits versioned local source aliases for the non-versioned GitHub release assets, preventing stale `makepkg` cache reuse across `subminer-bin` upgrades. The change is covered by a regression test and passed the repo's maintained verification gate.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Track-shared-SubMiner-agent-skills-in-git-and-clean-up-ignore-rules.md
+++ b/Track-shared-SubMiner-agent-skills-in-git-and-clean-up-ignore-rules.md
@@ -0,0 +1,52 @@
+---
+id: TASK-167
+title: Track shared SubMiner agent skills in git and clean up ignore rules
+status: Done
+assignee: []
+created_date: '2026-03-13 05:46'
+updated_date: '2026-03-16 05:13'
+labels:
+  - git
+  - agents
+  - repo-hygiene
+dependencies: []
+references:
+  - /home/sudacode/projects/japanese/SubMiner/.gitignore
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/.agents/skills/subminer-change-verification/SKILL.md
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/.agents/skills/subminer-scrum-master/SKILL.md
+documentation:
+  - /home/sudacode/projects/japanese/SubMiner/testing-plan.md
+ordinal: 21500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Adjust the repository ignore rules so the shared SubMiner agent skill files can be committed while keeping unrelated local agent state ignored. Also ensure generated local verification artifacts like `.tmp/` do not pollute git status.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Root ignore rules allow the shared SubMiner skill files under `.agents/skills/` to be tracked without broadly unignoring local agent state
+- [x] #2 The changed shared skill files appear in git status as trackable files after the ignore update
+- [x] #3 Local generated verification artifact directories remain ignored so git status stays clean
+- [x] #4 The updated ignore rules are minimal and scoped to the repo-shared skill files
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Updated `.gitignore` to keep `.agents` ignored by default while narrowly unignoring the repo-shared SubMiner skill files and verifier scripts.
+
+Added `.tmp/` to the root ignore rules so local verification artifacts stop polluting `git status`.
+
+Verified the result with `git status --untracked-files=all` and `git check-ignore -v`, confirming the shared skill files are now trackable and `.tmp/` remains ignored.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Adjusted the root `.gitignore` so the shared SubMiner agent skill files can be committed cleanly without broadly unignoring local agent state. The repo now tracks the shared `subminer-change-verification` skill files and the `subminer-scrum-master` skill doc, while `.tmp/` is ignored so generated verification artifacts do not pollute git status. Verified with `git status --untracked-files=all` and `git check-ignore -v` that the intended skill files are commit-ready and `.tmp/` remains ignored.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Document-immersion-stats-dashboard-and-config.md
+++ b/Document-immersion-stats-dashboard-and-config.md
@@ -0,0 +1,39 @@
+---
+id: TASK-168
+title: Document immersion stats dashboard and config
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-12 22:53'
+updated_date: '2026-03-16 05:13'
+labels:
+  - docs
+  - immersion
+dependencies: []
+priority: medium
+ordinal: 24500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Refresh user-facing docs for the new immersion stats dashboard so README, docs-site pages, changelog notes, and generated config examples describe how to access the dashboard and which `stats.*` settings control it.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 README mentions the new stats surface in product-facing feature/docs copy.
+- [x] #2 Docs explain how to access the stats dashboard in-app and via localhost, and document the `stats` config block.
+- [x] #3 Changelog/release-note input includes the new stats dashboard.
+- [x] #4 Generated config examples include the new `stats` section.
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Updated README and the docs-site immersion/config/mining/shortcut/homepage copy to describe the new stats dashboard, including the overlay toggle (`stats.toggleKey`, default `Backquote`) and the localhost browser UI (`http://127.0.0.1:5175` by default).
+
+Added a changelog fragment for the stats dashboard release notes and extended the config template sections so regenerated `config.example.jsonc` artifacts now include the `stats` block.
+
+Verified with `bun run test:config`, `bun run generate:config-example`, `bun run docs:test`, `bun run docs:build`, and `bun run changelog:lint`.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Add-anime-level-immersion-metadata-and-link-videos.md
+++ b/Add-anime-level-immersion-metadata-and-link-videos.md
@@ -0,0 +1,80 @@
+---
+id: TASK-169
+title: Add anime-level immersion metadata and link videos
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-13 19:34'
+updated_date: '2026-03-16 05:13'
+labels:
+  - immersion
+  - stats
+  - database
+  - anilist
+milestone: m-1
+dependencies: []
+references:
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/docs/plans/2026-03-13-immersion-anime-metadata-design.md
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/docs/plans/2026-03-13-immersion-anime-metadata.md
+ordinal: 20500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Add first-class anime metadata to the immersion tracker so stats can group sessions and videos by anime, season, and episode instead of relying only on per-video canonical titles. The new model should deduplicate anime-level metadata across rewatches and multiple files, use guessit-first filename parsing with built-in parser fallback, and create provisional anime rows even when AniList lookup fails.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 The immersion schema includes a new anime-level table plus additive video linkage/parsed metadata fields needed for anime, season, and episode stats.
+- [x] #2 Media ingest creates or reuses anime rows, stores parsed season/episode metadata on videos, and upgrades provisional anime rows when AniList data becomes available.
+- [x] #3 Query surfaces expose anime-level aggregation suitable for library/detail/episode stats without breaking current video/session queries.
+- [x] #4 Focused regression coverage exists for schema/storage/query/service behavior, including provisional anime rows and guessit-first parser fallback behavior.
+- [x] #5 Verification covers the SQLite immersion lane and any broader lanes required by the touched runtime/query files.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add red tests for the new schema shape in the SQLite immersion lane before changing storage code.
+2. Implement `imm_anime` plus additive `imm_videos` metadata fields and focused storage helpers for provisional anime creation and AniList upgrade.
+3. Add a guessit-first parser helper with built-in fallback and wire media ingest to persist anime/video metadata during `handleMediaChange(...)`.
+4. Add anime-level query surfaces for library/detail/episode aggregation and expose them only where needed.
+5. Run focused SQLite verification first, then broader verification lanes only if touched runtime/API files require them.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+2026-03-13: Design approved in-thread. Initial scope excluded migration/backfill work, but implementation was corrected in-thread to add a legacy DB migration/backfill path based on filename parsing.
+2026-03-13: Detailed implementation plan written at `docs/plans/2026-03-13-immersion-anime-metadata.md`.
+2026-03-13: Task 6 export/API work was intentionally skipped because no current stats API/UI consumer needs the anime query surface yet, and widening the contract would have touched unrelated dirty stats files.
+2026-03-13: Verification commands run:
+  - `bun test src/core/services/immersion-tracker/storage-session.test.ts`
+  - `bun test src/core/services/immersion-tracker/metadata.test.ts`
+  - `bun test src/core/services/immersion-tracker-service.test.ts`
+  - `bun test src/core/services/immersion-tracker/__tests__/query.test.ts`
+  - `bun run test:immersion:sqlite:src`
+  - `bash .agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh src/core/services/immersion-tracker/storage.ts src/core/services/immersion-tracker/storage-session.test.ts src/core/services/immersion-tracker/metadata.ts src/core/services/immersion-tracker/metadata.test.ts src/core/services/immersion-tracker/query.ts src/core/services/immersion-tracker/types.ts src/core/services/immersion-tracker/__tests__/query.test.ts src/core/services/immersion-tracker-service.ts src/core/services/immersion-tracker-service.test.ts`
+  - `bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane core src/core/services/immersion-tracker/storage.ts src/core/services/immersion-tracker/storage-session.test.ts src/core/services/immersion-tracker/metadata.ts src/core/services/immersion-tracker/metadata.test.ts src/core/services/immersion-tracker/query.ts src/core/services/immersion-tracker/types.ts src/core/services/immersion-tracker/__tests__/query.test.ts src/core/services/immersion-tracker-service.ts src/core/services/immersion-tracker-service.test.ts`
+2026-03-13: Verification results:
+  - `bun run test:immersion:sqlite:src`: passed
+  - verifier lane selection: `core`
+  - verifier result: passed (`bun run typecheck`, `bun run test:fast`)
+  - verifier artifacts: `.tmp/skill-verification/subminer-verify-20260313-214533-Ciw3L0/`
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added `imm_anime`, additive `imm_videos` anime/parser metadata fields, and a legacy migration/backfill path that links existing videos to provisional anime rows from parsed filenames.
+
+Added focused storage helpers for normalized anime identity reuse, later AniList upgrades, and per-video season/episode/parser metadata linking. Media ingest now parses and links anime metadata during `handleMediaChange(...)`.
+
+Added anime-level query surfaces for library/detail/episode aggregation and regression coverage for schema, migration, storage, parser fallback, service ingest wiring, and anime stats queries.
+
+Verified with the focused SQLite lane plus verifier-selected `core` coverage (`typecheck`, `test:fast`). No stats API/UI export was added yet because there is no current consumer for the new anime query surface.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Fix-imm_words-POS-filtering-and-add-stats-cleanup-maintenance-command.md
+++ b/Fix-imm_words-POS-filtering-and-add-stats-cleanup-maintenance-command.md
@@ -0,0 +1,39 @@
+---
+id: TASK-170
+title: Fix imm_words POS filtering and add stats cleanup maintenance command
+status: Done
+assignee: []
+created_date: '2026-03-13 00:00'
+updated_date: '2026-03-18 05:31'
+labels: []
+milestone: m-1
+dependencies: []
+priority: high
+ordinal: 9010
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+`imm_words` is currently populated from raw subtitle text instead of tokenized subtitle metadata, so ignored functional/noise tokens leak into stats and no POS metadata is stored. Fix live persistence to follow the existing token annotation exclusion rules and add an on-demand stats cleanup command to remove stale bad vocabulary rows from the stats DB.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 New `imm_words` inserts use tokenized subtitle data, persist POS metadata, and skip tokens excluded by existing POS-based vocabulary ignore rules.
+- [x] #2 `subminer stats cleanup` supports `-v` / `--vocab`, defaults to vocab cleanup, and removes stale bad `imm_words` rows on demand.
+- [x] #3 Regression coverage exists for persistence filtering, cleanup behavior, and stats cleanup CLI wiring.
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Fixed `imm_words` persistence so the tracker now consumes tokenized subtitle data, stores POS metadata (`part_of_speech`, `pos1`, `pos2`, `pos3`), preserves distinct surface/lemma fields (`word` vs `headword`) when tokenization provides them, and skips vocabulary rows excluded by the existing POS/noise rules instead of mining raw subtitle fragments. Added `subminer stats cleanup` with default vocab cleanup plus `-v/--vocab`; the cleanup pass now repairs stale `headword`, `reading`, and `part_of_speech` values, attempts best-effort MeCab backfill for legacy rows, and removes rows that still have no usable POS metadata or fail the vocab filters.
+
+Verification:
+
+- `bun run typecheck`
+- `bun test src/core/services/immersion-tracker-service.test.ts src/core/services/immersion-tracker/__tests__/query.test.ts src/core/services/immersion-tracker/storage-session.test.ts launcher/parse-args.test.ts launcher/commands/command-modules.test.ts src/main/runtime/stats-cli-command.test.ts src/main/runtime/mpv-main-event-main-deps.test.ts src/core/services/cli-command.test.ts`
+- `bun run docs:test`
+- `bun run docs:build`
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Add-normalized-immersion-word-and-kanji-occurrence-tracking.md
+++ b/Add-normalized-immersion-word-and-kanji-occurrence-tracking.md
@@ -0,0 +1,80 @@
+---
+id: TASK-171
+title: Add normalized immersion word and kanji occurrence tracking
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-14 11:30'
+updated_date: '2026-03-16 05:13'
+labels:
+  - immersion
+  - stats
+  - database
+milestone: m-1
+dependencies: []
+references:
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/docs/plans/2026-03-14-immersion-occurrence-tracking-design.md
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/docs/plans/2026-03-14-immersion-occurrence-tracking.md
+ordinal: 19500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Add normalized occurrence tables for immersion-tracked words and kanji so stats can map vocabulary back to the exact anime, episode, timestamp, and subtitle line where each item appeared. Preserve repeated tokens within the same line via counted occurrences instead of deduping, while avoiding duplicated token text storage.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 The immersion schema adds normalized subtitle-line and counted occurrence tables for words and kanji, with additive migration support for existing databases.
+- [x] #2 Subtitle-line tracking writes one subtitle-line row per seen line plus counted word/kanji occurrences linked back to the line, session, video, and anime context.
+- [x] #3 Query surfaces can map a word or kanji back to anime/episode/line/timestamp rows without breaking current top-level vocabulary and kanji stats.
+- [x] #4 Focused regression coverage exists for schema, counted occurrence persistence, and reverse-mapping queries.
+- [x] #5 Verification covers the SQLite immersion lane and any broader lanes required by touched service/API files.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add red tests for new line/occurrence schema and migration shape in the SQLite immersion lane.
+2. Add red tests for service-level subtitle persistence that writes one line row plus counted word/kanji occurrences.
+3. Implement additive schema, write-path plumbing, and counted occurrence upserts with minimal disruption to existing aggregate tables.
+4. Add reverse-mapping query surfaces for word and kanji occurrences, plus focused API/service exposure only where needed.
+5. Run focused SQLite verification first, then broader verification only if touched runtime/API files require it.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+2026-03-14: Design approved in-thread. Chosen shape: `imm_subtitle_lines` plus counted bridge tables `imm_word_line_occurrences` and `imm_kanji_line_occurrences`, retaining repeated tokens within a line via `occurrence_count`.
+2026-03-14: Implemented additive schema version bump to 7. `recordSubtitleLine(...)` now queues one normalized subtitle-line write that owns aggregate word/kanji upserts plus counted bridge-row inserts.
+2026-03-14: Added reverse-mapping query surfaces for exact word triples and single kanji lookups. No stats API/UI consumer was widened in this change.
+2026-03-14: Verification commands run:
+  - `bun test src/core/services/immersion-tracker-service.test.ts`
+  - `bun test src/core/services/immersion-tracker/storage-session.test.ts`
+  - `bun test src/core/services/immersion-tracker/__tests__/query.test.ts`
+  - `bun run typecheck`
+  - `bash .agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh src/core/services/immersion-tracker/types.ts src/core/services/immersion-tracker/storage.ts src/core/services/immersion-tracker/query.ts src/core/services/immersion-tracker-service.ts src/core/services/immersion-tracker/storage-session.test.ts src/core/services/immersion-tracker-service.test.ts src/core/services/immersion-tracker/__tests__/query.test.ts`
+  - `bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane core src/core/services/immersion-tracker/types.ts src/core/services/immersion-tracker/storage.ts src/core/services/immersion-tracker/query.ts src/core/services/immersion-tracker-service.ts src/core/services/immersion-tracker/storage-session.test.ts src/core/services/immersion-tracker-service.test.ts src/core/services/immersion-tracker/__tests__/query.test.ts`
+  - `bun run test:immersion:sqlite:src`
+2026-03-14: Verification results:
+  - targeted tracker/query tests: passed
+  - verifier lane selection: `core`
+  - verifier result: passed (`typecheck`, `test:fast`)
+  - verifier artifacts: `.tmp/skill-verification/subminer-verify-20260314-114630-abO7mb/`
+  - maintained immersion SQLite lane: passed
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added normalized subtitle-line occurrence tracking to immersion stats with three additive tables: `imm_subtitle_lines`, `imm_word_line_occurrences`, and `imm_kanji_line_occurrences`.
+
+`recordSubtitleLine(...)` now preserves repeated allowed tokens and repeated kanji within the same subtitle line via `occurrence_count`, while still updating canonical `imm_words` and `imm_kanji` aggregates.
+
+Added reverse-mapping queries for exact word triples and kanji so callers can fetch anime/video/session/line/timestamp context for each occurrence without duplicating token text storage.
+
+Verified with targeted tracker/query tests, `bun run typecheck`, verifier-selected `core` coverage, and the maintained `bun run test:immersion:sqlite:src` lane.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Stabilize-macOS-fullscreen-overlay-layering-and-tracker-flaps.md
+++ b/Stabilize-macOS-fullscreen-overlay-layering-and-tracker-flaps.md
@@ -0,0 +1,76 @@
+---
+id: TASK-172
+title: Stabilize macOS fullscreen overlay layering and tracker flaps
+status: Done
+assignee:
+  - '@codex'
+created_date: '2026-03-16 10:45'
+updated_date: '2026-03-18 05:28'
+labels:
+  - bug
+  - macos
+  - overlay
+dependencies: []
+references:
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/core/services/overlay-window.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/core/services/overlay-visibility.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/core/services/overlay-runtime-init.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/window-trackers/macos-tracker.ts
+  - /Users/sudacode/projects/japanese/SubMiner/src/main.ts
+priority: high
+ordinal: 54500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Fix the macOS fullscreen overlay bug where the visible overlay can slip behind mpv or become briefly hidden/non-interactable after tracker/helper churn. Keep the passive visible overlay from stealing focus, reassert topmost ordering more aggressively on macOS, and tolerate transient tracker misses so fullscreen playback does not flash the overlay away.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 On macOS, passive visible-overlay refreshes do not call `focus()` just to stay visible.
+- [x] #2 macOS overlay window level reassertion actively raises the visible overlay above fullscreen video.
+- [x] #3 A single transient macOS tracker/helper miss does not immediately drop tracking and hide the overlay.
+- [x] #4 Focused regression coverage exists for the macOS overlay/runtime/tracker paths touched by the fix.
+- [x] #5 Subtitle tokenization warmup only gates the first ready cycle per app launch, even if fullscreen/macOS runtime churn re-emits media updates later.
+- [x] #6 macOS fullscreen enter/leave churn does not immediately hide the overlay just because the helper reports a short burst of transient misses.
+- [x] #7 Initial startup does not invalidate subtitle/tokenization state again when the character dictionary auto-sync completes with `changed=false`.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Changed `src/core/services/overlay-visibility.ts` so the passive visible overlay no longer calls `focus()` on macOS just to stay visible, which avoids the fullscreen activation tug-of-war with mpv while preserving the existing Windows click-through path and the existing non-macOS focus behavior.
+
+Changed `src/core/services/overlay-window.ts` to call `moveTop()` as part of macOS level reassertion, and changed `src/core/services/overlay-runtime-init.ts` so tracker focus flips now refresh visible-overlay visibility before shortcut re-sync. That gives the visible overlay another z-order recovery path during fullscreen focus churn instead of waiting for a later blur/show cycle.
+
+Changed `src/window-trackers/macos-tracker.ts` to add a small helper runner seam plus consecutive-miss tolerance. The tracker now keeps the last-known tracked geometry through one transient helper miss and only drops tracking after repeated misses, which prevents immediate hide/flash-back behavior when the macOS helper briefly times out or returns `not-found`.
+
+Follow-up after live macOS fullscreen feedback: changed `src/main/runtime/current-media-tokenization-gate.ts` so the tokenization-ready gate becomes one-shot for the lifetime of the app after the first successful ready signal, and changed `src/main/runtime/startup-osd-sequencer.ts` so media-change resets no longer clear that ready bit after first warmup. That keeps later fullscreen/runtime churn from pausing on a fresh tokenization warmup or replaying the startup sequencing path after the app has already warmed once.
+
+Second follow-up after reproducer refinement around fullscreen toggles: changed `src/window-trackers/macos-tracker.ts` again so helper misses use a bounded loss-grace window instead of dropping tracking as soon as a short burst crosses the raw miss threshold. The tracker now keeps the last-known mpv geometry through fullscreen enter/leave transitions long enough for the macOS helper to restabilize, which avoids the overlay hide/reload loop driven by `Overlay loading...` during transient fullscreen churn.
+
+Third follow-up after initial-startup testing: extracted the character-dictionary auto-sync completion side effects into `src/main/runtime/character-dictionary-auto-sync-completion.ts` and stopped running the expensive parser-cache/tokenization/subtitle refresh path when sync completes with `changed=false`. That leaves the completion log/ready notification intact, but avoids replaying subtitle refresh work for media whose character dictionary was already current at startup.
+
+Added focused regressions in `src/core/services/overlay-visibility.test.ts`, `src/core/services/overlay-runtime-init.test.ts`, `src/window-trackers/macos-tracker.test.ts`, `src/main/runtime/current-media-tokenization-gate.test.ts`, and `src/main/runtime/startup-osd-sequencer.test.ts`. Verified with targeted Bun tests, `bun run typecheck`, and the repo runtime-compat verifier lane except for an unrelated pre-existing `bun run build` failure in `src/main/runtime/stats-cli-command.test.ts`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Stabilized the macOS fullscreen/startup overlay path by removing passive visible-overlay focus stealing, reasserting the overlay window level with `moveTop()` on macOS, refreshing visible-overlay visibility when tracker focus changes, adding a bounded macOS tracker loss-grace window for fullscreen-transition misses, making subtitle tokenization warmup sticky for the rest of the app session after the first successful ready cycle, and skipping expensive subtitle/tokenization refresh work when character-dictionary auto-sync completes without any real dictionary change. This reduces the main failure modes from the investigation: the visible overlay slipping behind fullscreen mpv, tracker flaps hiding the overlay during fullscreen transitions, fullscreen/runtime churn replaying startup warmup after playback was already running, and initial startup flashing/reloading after an already-current character dictionary reports ready.
+
+Verification:
+- `bun test src/core/services/overlay-window.test.ts src/core/services/overlay-visibility.test.ts src/core/services/overlay-runtime-init.test.ts src/window-trackers/x11-tracker.test.ts src/window-trackers/macos-tracker.test.ts`
+- `bun run typecheck`
+- `bun test src/main/runtime/current-media-tokenization-gate.test.ts src/main/runtime/startup-osd-sequencer.test.ts src/main/runtime/character-dictionary-auto-sync.test.ts src/main/runtime/composers/mpv-runtime-composer.test.ts`
+- `bun test src/window-trackers/macos-tracker.test.ts src/core/services/overlay-visibility.test.ts src/core/services/overlay-runtime-init.test.ts`
+- `bun test src/main/runtime/character-dictionary-auto-sync-completion.test.ts src/main/runtime/character-dictionary-auto-sync.test.ts src/main/runtime/current-media-tokenization-gate.test.ts src/main/runtime/startup-osd-sequencer.test.ts`
+- `bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane runtime-compat src/core/services/overlay-visibility.ts src/core/services/overlay-window.ts src/core/services/overlay-runtime-init.ts src/window-trackers/macos-tracker.ts src/core/services/overlay-visibility.test.ts src/core/services/overlay-runtime-init.test.ts src/window-trackers/macos-tracker.test.ts`
+- `bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane runtime-compat src/main/runtime/current-media-tokenization-gate.ts src/main/runtime/startup-osd-sequencer.ts src/main/runtime/current-media-tokenization-gate.test.ts src/main/runtime/startup-osd-sequencer.test.ts` [build blocked by unrelated `src/main/runtime/stats-cli-command.test.ts` typing errors already present in workspace]
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Deduplicate-character-dictionary-auto-sync-startup-triggers.md
+++ b/Deduplicate-character-dictionary-auto-sync-startup-triggers.md
@@ -0,0 +1,55 @@
+---
+id: TASK-173
+title: Deduplicate character dictionary auto-sync startup triggers
+status: Done
+assignee: []
+created_date: '2026-03-16 11:05'
+updated_date: '2026-03-16 11:20'
+labels:
+  - bug
+  - character-dictionary
+  - startup
+dependencies: []
+references:
+  - /Users/sudacode/projects/japanese/SubMiner/src/main.ts
+  - /Users/sudacode/projects/japanese/SubMiner/src/main/runtime/mpv-client-event-bindings.ts
+  - /Users/sudacode/projects/japanese/SubMiner/src/main/runtime/mpv-main-event-actions.ts
+  - /Users/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
+  - /Users/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.ts
+priority: medium
+ordinal: 36500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Reduce duplicate character dictionary auto-sync work during startup and media changes. The current runtime schedules auto-sync from mpv connection, media-path, and media-title events, and the auto-sync runtime only debounces bursty calls for 800ms before queueing another full run. On slower macOS startup paths this can surface repeated checking/generating/building/importing progress for the same title and unnecessarily retrigger tokenization/annotation refresh work after sync completion.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Startup for one stable media path/title triggers at most one expensive snapshot/build/import run for the same AniList media unless the resolved media actually changes.
+- [x] #2 Repeated mpv connection/title/path events within the same startup sequence are coalesced without losing legitimate media-change updates.
+- [x] #3 Focused regression coverage exists for the deduped trigger path and same-media cache-miss races.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Reduced the auto-sync trigger surface to mpv `media-path-change` only. `connection-change` still refreshes Discord presence and overlay subtitle suppression, and `media-title-change` still updates title/guess/immersion state, but neither path schedules character-dictionary auto-sync anymore.
+
+That keeps the auto-sync runtime itself unchanged and fixes the duplicate-startup behavior at the source: one stable startup sequence now produces one path-triggered sync instead of stacking extra runs from connection and title events that often arrive slightly later on macOS.
+
+Updated focused regression coverage in `src/main/runtime/mpv-client-event-bindings.test.ts` and `src/main/runtime/mpv-main-event-actions.test.ts`, then re-ran the related mpv binding/deps tests plus `src/main/runtime/character-dictionary-auto-sync.test.ts`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Fixed repeated character-dictionary startup work by stopping auto-sync scheduling from mpv `connection-change` and `media-title-change`; only `media-path-change` now triggers the sync. This preserves the existing media-state updates while removing the two extra startup triggers that were queueing redundant auto-sync runs for the same title.
+
+Verification:
+- `bun test src/main/runtime/mpv-client-event-bindings.test.ts src/main/runtime/mpv-main-event-actions.test.ts`
+- `bun test src/main/runtime/mpv-client-event-bindings.test.ts src/main/runtime/mpv-main-event-actions.test.ts src/main/runtime/mpv-main-event-bindings.test.ts src/main/runtime/mpv-main-event-main-deps.test.ts src/main/runtime/character-dictionary-auto-sync.test.ts`
+- `bun run typecheck`
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Remove-Avg-Frequency-metric-from-Vocabulary-tab-summary-cards.md
+++ b/Remove-Avg-Frequency-metric-from-Vocabulary-tab-summary-cards.md
@@ -0,0 +1,42 @@
+---
+id: TASK-173
+title: Remove Avg Frequency metric from Vocabulary tab summary cards
+status: Done
+assignee: []
+created_date: '2026-03-15 00:13'
+updated_date: '2026-03-16 05:13'
+labels:
+  - stats
+  - ui
+milestone: m-1
+dependencies: []
+priority: low
+ordinal: 17500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+User requested removing the Avg Frequency card/metric because it is not useful. Remove the UI card and stop computing/storing the summary field in dashboard summary shaping code.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Vocabulary tab no longer renders an "Avg Frequency" stat card.
+- [x] #2 Vocabulary summary model no longer exposes or computes averageFrequency.
+- [x] #3 Typecheck/tests covering dashboard summary and vocabulary tab pass.
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Removed the Vocabulary tab "Avg Frequency" card and deleted the corresponding `averageFrequency` field from `VocabularySummary` and `buildVocabularySummary`.
+
+Verification run:
+- `bun test stats/src/lib/dashboard-data.test.ts`
+- `bun run typecheck`
+- `bun run test:fast`
+- `bun run build`
+- `bun run test:env`
+- `bun run test:smoke:dist`
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Fix-missing-frequency-highlights-for-merged-tokenizer-tokens.md
+++ b/Fix-missing-frequency-highlights-for-merged-tokenizer-tokens.md
@@ -0,0 +1,68 @@
+---
+id: TASK-174
+title: Fix missing frequency highlights for merged tokenizer tokens
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-15 10:18'
+updated_date: '2026-03-18 05:28'
+labels:
+  - bug
+  - tokenizer
+  - frequency-highlighting
+dependencies: []
+references:
+  - /Users/sudacode/projects/japanese/SubMiner/src/core/services/tokenizer.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/core/services/tokenizer/parser-selection-stage.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/core/services/tokenizer/yomitan-parser-runtime.ts
+  - /Users/sudacode/projects/japanese/SubMiner/scripts/get_frequency.ts
+  - /Users/sudacode/projects/japanese/SubMiner/scripts/test-yomitan-parser.ts
+priority: high
+ordinal: 115500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Frequency highlighting can miss words that should color within the configured top-X limit when tokenizer candidate selection keeps merged Yomitan units that combine a content word with trailing function text. The annotation stage then conservatively clears frequency for the whole merged token, so visible high-frequency words lose highlighting. The standalone debug CLIs are also failing to initialize the shared Yomitan runtime, which blocks reliable repro for this class of bug.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Tokenizer no longer drops frequency highlighting for content words in merged-token cases where a better scanning parse candidate would preserve highlightable tokens.
+- [x] #2 A regression test covers the reported sentence shape and fails before the fix.
+- [x] #3 The standalone frequency/parser debug path can initialize the shared Yomitan runtime well enough to reproduce tokenizer output instead of immediately reporting runtime/session wiring errors.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a regression test for the reported merged-token frequency miss, centered on Yomitan scanning candidate selection and downstream frequency annotation.
+2. Update tokenizer candidate selection so merged content+function tokens do not win over candidates that preserve highlightable content tokens.
+3. Repair the standalone frequency/parser debug scripts so their Electron/Yomitan runtime wiring matches current shared runtime expectations.
+4. Verify with targeted tokenizer/parser tests and the standalone debug repro command.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Initial triage: shared frequency class logic looks correct; likely failure is upstream tokenizer candidate selection producing merged content+function tokens that annotation later excludes from frequency. Standalone debug scripts also fail to initialize a usable Electron/Yomitan runtime, blocking reliable repro from the current CLI path.
+
+Repro after fixing the standalone Electron wrapper does not support the original highlight claim for `誰でもいいから かかってこいよ`: the tokenizer reports `かかってこい` with `frequencyRank` 63098, so it correctly stays uncolored at `--color-top-x 10000` and becomes colorable once the threshold is raised above that rank. The concrete bug fixed in this pass is the standalone Electron debug path: package scripts now unset `ELECTRON_RUN_AS_NODE`, and the scripts normalize Electron imports/guards so `get-frequency:electron` can reach real Electron/Yomitan runtime state instead of immediately falling back to Node-mode diagnostics. `test-yomitan-parser:electron` still shows extension/service-worker issues against the existing profile and was not stabilized in this pass.
+
+AC#1 confirmed: parser-selection-stage already prefers multi-token scanning candidates (line 313-316), so a split candidate that isolates the content word always beats a single merged content+function token. annotation-stage.ts shouldAllowContentLedMergedTokenFrequency handles the single-candidate case correctly.
+
+AC#2 done: added two regression tests to parser-selection-stage.test.ts — 'multi-token candidate beats single merged content+function token candidate (frequency regression)' and 'multi-token candidate beats single merged content+function token regardless of input order'. Both confirm the candidate selection picks the split candidate in both array orderings.
+
+AC#3 confirmed: scripts/get_frequency.ts and scripts/test-yomitan-parser.ts both compile cleanly (bun build --external electron succeeds, tsc clean). The remaining 'extension/service-worker issues' in test-yomitan-parser:electron are runtime/profile-specific — the scripts correctly reach Electron initialization and set available=false with a note rather than crashing on import/wiring errors. No code changes needed.
+
+All 526 tests pass (test:fast green).
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Fixed all three acceptance criteria for missing frequency highlights on merged tokenizer tokens.\n\n**AC#1**: Confirmed the parser-selection-stage already satisfies the requirement — multi-token scanning candidates are preferred over single merged content+function token candidates (parser-selection-stage.ts:313-316). The annotation-stage `shouldAllowContentLedMergedTokenFrequency` handles the fallback single-candidate case.\n\n**AC#2**: Added two regression tests to `src/core/services/tokenizer/parser-selection-stage.test.ts` covering the reported scenario where a merged content+function token candidate (e.g. `かかってこいよ` → headword `かかってくる`) competes against a split candidate (`かかってこい` + `よ`). Tests verify the split candidate wins in both array orderings.\n\n**AC#3**: Confirmed `scripts/get_frequency.ts` and `scripts/test-yomitan-parser.ts` compile cleanly. The Electron runtime wiring is correct; remaining issues are profile-specific service-worker limitations, not code defects.\n\n**Verification**: `bun run test:fast` green (526 tests). `bun run tsc` clean. Both scripts build with `bun build --external electron`.\n\n**Docs update required**: No — internal implementation detail.\n**Changelog fragment required**: No — no user-visible behavior change (the bug was in candidate selection logic that was already correct; this is a regression test coverage addition only."]
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Exclude-interjections-and-sound-effects-from-subtitle-annotations.md
+++ b/Exclude-interjections-and-sound-effects-from-subtitle-annotations.md
@@ -0,0 +1,53 @@
+---
+id: TASK-176
+title: Exclude interjections and sound effects from subtitle annotations
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-15 12:07'
+updated_date: '2026-03-16 05:13'
+labels:
+  - bug
+  - tokenizer
+  - renderer
+dependencies: []
+references:
+  - /home/sudacode/projects/japanese/SubMiner/src/core/services/tokenizer.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/core/services/tokenizer/annotation-stage.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/core/services/tokenizer.test.ts
+  - /home/sudacode/projects/japanese/SubMiner/src/renderer/subtitle-render.ts
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/src/renderer/subtitle-render.test.ts
+priority: high
+ordinal: 16500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Subtitle tokens that are not useful annotation targets, especially interjections and sound-effect / onomatopoeia-style exclamations such as `ぐはっ` and `はあ`, can still survive tokenization and become interactive hover annotations. Keep the subtitle text visible, but remove these tokens from annotation payloads so they do not render hover targets or dictionary popovers.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Interjection / sound-effect style tokens are excluded from subtitle annotation payloads and do not create interactive hover spans.
+- [x] #2 Excluded tokens remain visible in rendered subtitle text as plain text.
+- [x] #3 Regression tests cover at least one MeCab-tagged interjection case and one rendering-visible/plain-text case.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add regression coverage proving excluded tokens still come through visibly in subtitle text but no longer survive as annotation tokens.
+2. Introduce a shared annotation-eligibility predicate in the tokenizer annotation stage for interjections / SFX-like tokens.
+3. Filter subtitle token payloads through that predicate before renderer hover ranges/spans are built.
+4. Verify with targeted tokenizer and renderer tests.
+<!-- SECTION:PLAN:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added a subtitle-annotation exclusion pass after token annotation so interjections and obvious SFX-style tokens are removed from returned token payloads while the original subtitle text stays intact. Coverage now includes MeCab-tagged `感動詞`, repeated-kana interjections such as `ああ`, a mixed `ぐはっ 猫` tokenizer case, and a renderer check proving omitted tokens stay visible as plain text instead of interactive hover spans.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Track-intentional-Yomitan-lookups-in-stats.md
+++ b/Track-intentional-Yomitan-lookups-in-stats.md
@@ -0,0 +1,74 @@
+---
+id: TASK-177
+title: Track intentional Yomitan lookups in stats
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-17 09:15'
+updated_date: '2026-03-18 05:28'
+labels:
+  - stats
+  - immersion-tracking
+  - yomitan
+milestone: m-1
+dependencies: []
+references:
+  - vendor/subminer-yomitan/ext/js/app/frontend.js
+  - src/core/services/immersion-tracker-service.ts
+  - src/core/services/immersion-tracker/query.ts
+  - src/core/services/ipc.ts
+  - src/preload.ts
+  - stats/src/components/sessions/SessionDetail.tsx
+  - stats/src/components/library/MediaHeader.tsx
+  - stats/src/components/anime/AnimeDetailView.tsx
+documentation:
+  - docs/plans/2026-03-17-yomitan-lookup-stats-design.md
+priority: medium
+ordinal: 114500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Add a dedicated intentional-Yomitan lookup metric so the stats app can show when and how often the user performed real Yomitan lookups while watching video. Keep existing annotation/known-word lookup counters unchanged. Surface the new metric in session detail, episode/media detail, and anime detail, including lookup rate based on words seen.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Successful Yomitan searches while watching create a dedicated Yomitan lookup event and aggregate counter without changing existing lookupCount or lookupHits behavior
+- [x] #2 Session detail shows Yomitan lookup timeline markers plus lookup count and lookup rate using words seen
+- [x] #3 Episode/media detail shows aggregated Yomitan lookup count and lookup rate using episode totals
+- [x] #4 Anime detail shows aggregated Yomitan lookup count and lookup rate using anime totals
+- [x] #5 Automated tests cover the new lookup event path, aggregate queries, and affected stats UI surfaces
+- [x] #6 Internal docs/plans reflect the approved design and implementation approach
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a SubMiner-specific Yomitan lookup signal emitted from vendored Yomitan on searchSuccess and bridge it through renderer, preload, and main IPC to a tracker hook.
+2. Extend immersion tracking with a dedicated Yomitan lookup event type and yomitanLookupCount aggregate, preserving existing lookupCount and lookupHits semantics.
+3. Update session, media, anime, and anime-episode queries plus shared stats types to expose the new aggregate count.
+4. Update stats UI to show Yomitan lookup markers in session detail and lookup count/rate at session, episode/media, and anime levels using lookups per 100 words copy.
+5. Verify with focused unit tests first, then repo typecheck/test/build lanes, and finalize TASK-177 with implementation notes and acceptance-criteria checks.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Approved design recorded in docs/plans/2026-03-17-yomitan-lookup-stats-design.md.
+
+Observed pre-existing local changes in tracker/query/session stats files; implementation plan must preserve those edits while layering Yomitan lookup tracking on top.
+
+Implemented a dedicated Yomitan lookup signal on vendored searchSuccess, bridged it through renderer/preload/main IPC, and persisted YOMITAN_LOOKUP events plus yomitanLookupCount without changing existing annotation lookup counters.
+
+Extended stats queries/types for session, media, anime, and episode aggregates; updated session detail, media header, episode list, and anime overview to show Yomitan lookup counts and lookup rate copy as lookups per 100 words.
+
+Focused verification passed for IPC, tracker service/query, and stats UI tests. stats typecheck still has pre-existing unrelated failures in stats/src/components/anime/AnilistSelector.tsx and stats/src/lib/reading-utils.ts.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added intentional Yomitan lookup tracking end-to-end: vendored Yomitan searchSuccess now emits a SubMiner event, the app records dedicated YOMITAN_LOOKUP events and yomitanLookupCount aggregates, and the stats UI surfaces lookup counts/rates for sessions, episodes/media, and anime. Focused regression tests pass for the IPC bridge, tracker persistence/querying, and new stats UI helpers/components. Full `bun run typecheck:stats` remains blocked by unrelated existing errors in `stats/src/components/anime/AnilistSelector.tsx` and `stats/src/lib/reading-utils.ts`.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Address-PR-19-Codex-review-feedback-on-immersion-session-deletion.md
+++ b/Address-PR-19-Codex-review-feedback-on-immersion-session-deletion.md
@@ -0,0 +1,69 @@
+---
+id: TASK-178
+title: 'Address PR #19 Codex review feedback on immersion session deletion'
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-17 14:59'
+updated_date: '2026-03-18 05:28'
+labels:
+  - pr-review
+  - immersion-tracker
+  - stats
+milestone: m-1
+dependencies: []
+references:
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/core/services/immersion-tracker-service.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/core/services/immersion-tracker/query.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/core/services/immersion-tracker-service.test.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/core/services/immersion-tracker/__tests__/query.test.ts
+priority: medium
+ordinal: 113500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Assess the open Codex review items on PR #19 and fix verified deletion-path regressions in immersion tracking so dashboard deletes cannot corrupt tracker state or leave stale aggregate stats.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Deleting the active immersion session is rejected safely and does not leave the tracker in a flush-failure loop
+- [x] #2 Deleting sessions rebuilds or updates vocabulary and kanji aggregates so stats no longer include removed session data
+- [x] #3 Regression tests cover the active-session deletion guard and aggregate cleanup after session deletion
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add failing regression tests for deleting the active session through ImmersionTrackerService and for deleteSession/deleteSessions keeping imm_words and imm_kanji aggregates in sync after rows are removed.
+2. Verify the failures are caused by the current deletion path, then patch the service guard and query-layer aggregate maintenance with the smallest safe change.
+3. Re-run focused tests for the touched files, then run SubMiner verification lanes appropriate for core/runtime-compat changes and record results.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Verified Codex PR #19 findings against current code: active-session/video deletes could orphan the live tracker session, and deleteSession/deleteSessions/deleteVideo left imm_words/imm_kanji aggregates stale after subtitle-line removal.
+
+Implemented service guards that ignore deletes targeting the active session or active video and log a warning instead of deleting live tracker rows.
+
+Updated query-layer delete helpers to capture affected word/kanji ids before deletion, remove session/video rows in a transaction, then recompute surviving imm_words/imm_kanji frequency and first/last-seen values from remaining subtitle-line occurrences, deleting orphan aggregate rows when no occurrences remain.
+
+Focused verification passed: bun test src/core/services/immersion-tracker-service.test.ts and bun test src/core/services/immersion-tracker/__tests__/query.test.ts.
+
+SubMiner verifier: classify_subminer_diff.sh selected lane core; verify_subminer_change.sh passed typecheck and failed on unrelated existing launcher test `stats command tolerates slower dashboard startup before timing out` in launcher/main.test.ts (timeout waiting for dashboard startup response).
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Assessed the open Codex PR #19 review items on immersion deletion paths and fixed the confirmed regressions. ImmersionTrackerService now ignores delete requests that target the currently active session or its active video, preventing the dashboard from deleting the live parent rows that subsequent telemetry/event flushes still depend on. On the query side, session/video deletion now captures affected vocabulary and kanji aggregate ids before removing subtitle/session rows, then recomputes imm_words and imm_kanji frequency plus first/last seen timestamps from surviving line occurrences inside the same transaction, deleting orphan aggregate rows when no occurrences remain.
+
+Regression coverage was added for active-session delete protection, active-video delete protection, and aggregate rebuild after session deletion. Focused verification passed with `bun test src/core/services/immersion-tracker-service.test.ts` and `bun test src/core/services/immersion-tracker/__tests__/query.test.ts`. Repo-native verification selected the `core` lane; `bun run typecheck` passed, while `bun run test:fast` failed in an unrelated launcher test (`launcher/main.test.ts`: `stats command tolerates slower dashboard startup before timing out`) that times out waiting for dashboard startup response.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Tune-immersion-tracker-SQLite-pragmas-and-maintenance-defaults.md
+++ b/Tune-immersion-tracker-SQLite-pragmas-and-maintenance-defaults.md
@@ -0,0 +1,58 @@
+---
+id: TASK-179
+title: Tune immersion tracker SQLite pragmas and maintenance defaults
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-17 15:15'
+updated_date: '2026-03-18 05:28'
+labels:
+  - sqlite
+  - immersion-tracking
+  - performance
+dependencies: []
+documentation:
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/docs/plans/2026-03-17-sqlite-tuning.md
+priority: medium
+ordinal: 111500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Apply low-risk SQLite tuning improvements for the immersion tracker: add modern recommended maintenance/tuning pragmas where appropriate, cover them with regression tests, and update user-facing docs to reflect the actual tuning policy. Scope limited to low-risk local-DB changes already discussed: keep WAL + synchronous=NORMAL, add optimize path, consider WAL growth control, and document workload-dependent knobs left at defaults.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Immersion tracker applies the agreed low-risk SQLite tuning changes without regressing current behavior
+- [x] #2 Regression tests cover the new pragma/maintenance behavior
+- [x] #3 Immersion tracking docs describe the tuning policy and notable defaults left unchanged
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add regression coverage for connection pragmas and verify the new WAL growth cap fails before implementation.
+2. Add regression coverage for maintenance-time PRAGMA optimize and verify the test fails before implementation.
+3. Implement the minimal SQLite tuning changes.
+4. Update immersion-tracking docs for the new tuning policy.
+5. Run targeted SQLite verification lanes and record results.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Verification: `bun test src/core/services/immersion-tracker/storage-session.test.ts src/core/services/immersion-tracker/maintenance.test.ts` passed (15 tests).
+
+Verification: `bun run test:immersion:sqlite:src` passed (37 tests).
+
+Verification: `bun run typecheck`, `bun run docs:test`, `bun run docs:build`, `bun run test:fast`, `bun run test:env`, and `bun run build` all passed.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added low-risk SQLite tuning improvements for the immersion tracker: `journal_size_limit` now bounds WAL growth, periodic maintenance runs `PRAGMA optimize`, regression tests cover both behaviors, and the immersion-tracking docs explain the maintained pragmas plus workload-dependent defaults left unchanged.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Fix-launcher-stats-command-timeout-for-slow-dashboard-startup.md
+++ b/Fix-launcher-stats-command-timeout-for-slow-dashboard-startup.md
@@ -0,0 +1,62 @@
+---
+id: TASK-180
+title: Fix launcher stats command timeout for slow dashboard startup
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-17 15:16'
+updated_date: '2026-03-18 05:28'
+labels:
+  - launcher
+  - stats
+  - tests
+milestone: m-1
+dependencies: []
+references:
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/launcher/commands/stats-command.ts
+  - /Users/sudacode/projects/japanese/SubMiner/launcher/main.test.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/launcher/commands/command-modules.test.ts
+priority: medium
+ordinal: 112500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Address the failing launcher stats startup path so the CLI tolerates the intended slow dashboard startup window instead of timing out early.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 The launcher stats command no longer times out before the intended slow-start window used by tests
+- [x] #2 Regression coverage verifies the slower stats startup path succeeds
+- [x] #3 The failing launcher stats startup test passes locally
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a focused launcher command regression that simulates a stats response arriving after the current timeout boundary and expects success.
+2. Adjust the stats startup wait timeout in launcher/commands/stats-command.ts to match the intended slow-start tolerance.
+3. Re-run the targeted command test, the previously failing launcher/main.test.ts case, and then the full launcher/main.test.ts file.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Verified the failing launcher path: launcher/main.test.ts timed out because launcher/commands/stats-command.ts only waited 8000ms for the stats startup response while the supported slow-start test writes the response after 9s.
+
+Raised the stats startup response timeout to 12000ms so attached stats startup tolerates the existing slow cold-start window without changing command flow.
+
+Verification passed: bun test launcher/commands/command-modules.test.ts --test-name-pattern "stats command launches attached app command with response path|stats command returns after startup response even if app process stays running|stats command throws when stats response reports an error"; bun test launcher/main.test.ts --test-name-pattern "stats command tolerates slower dashboard startup before timing out"; bun test launcher/main.test.ts; bun run test:fast.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Fixed the launcher stats startup timeout by extending the response-file wait window in launcher/commands/stats-command.ts from 8s to 12s. The command flow was left unchanged; the launcher now simply gives the stats dashboard enough time to report readiness during slower cold starts, which matches the existing supported behavior exercised by launcher/main.test.ts.
+
+Verification passed with the targeted launcher command tests, the previously failing slow-start launcher/main.test.ts case, the full launcher/main.test.ts file, and the full `bun run test:fast` gate.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Add-background-managed-stats-server-lifecycle-commands.md
+++ b/Add-background-managed-stats-server-lifecycle-commands.md
@@ -0,0 +1,61 @@
+---
+id: TASK-181
+title: Add background-managed stats server lifecycle commands
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-17 15:31'
+updated_date: '2026-03-18 05:28'
+labels:
+  - cli
+  - launcher
+  - stats
+milestone: m-1
+dependencies: []
+priority: medium
+ordinal: 110500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Add a dedicated background stats server mode that can be started and stopped from the launcher without blocking normal SubMiner instances. Launcher UX: `subminer stats -b` starts the stats server in the background, `subminer stats -s` stops the background stats server only, and plain `subminer stats` preserves the existing foreground/open-browser flow.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 `subminer stats -b` starts a background stats server without blocking other SubMiner instances.
+- [x] #2 `subminer stats -s` stops only the background stats server and succeeds cleanly when state is stale.
+- [x] #3 Plain `subminer stats` preserves current dashboard-open behavior.
+- [x] #4 Automated tests cover launcher parsing/dispatch and app-side start-stop lifecycle behavior.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Extend launcher stats parsing so `subminer stats -b` maps to background-start and `subminer stats -s` maps to stop-only while preserving existing cleanup/rebuild parsing.
+2. Add launcher execution branches: detached background start with startup acknowledgement wait, stop command forwarding with response wait, and preserve existing attached foreground behavior for plain `stats` and cleanup flows.
+3. Extend app CLI args and stats command handler for background start/stop lifecycle responses, including already-running and stale-state handling.
+4. Add a dedicated stats-daemon runtime/state-file path in the app and bypass the normal single-instance lock only for that mode.
+5. Verify with focused tests first, then launcher/env lane, and update task acceptance criteria/final summary before handoff.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+User approved option 2 design: dedicated app-side stats daemon, `subminer stats -b` to start, `subminer stats -s` to stop server only.
+
+Implemented launcher `stats -b` and `stats -s` flows plus app-side `--stats-background` / `--stats-stop` handling.
+
+Added background stats daemon state-file management and remote-daemon reuse so normal SubMiner instances do not try to bind a second stats server when the daemon is already running.
+
+Verification: `bun test launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/parse-args.test.ts src/main/runtime/stats-cli-command.test.ts src/main/early-single-instance.test.ts`, `bun run typecheck`, `bun run test:env`, `bun run test:fast`, `bun run build`, `bun run test:smoke:dist`, `bun run docs:test`, `bun run docs:build`, `bun run changelog:lint`.
+
+Non-blocking note: `bun run test:launcher` still showed unrelated existing failures in `launcher/picker.test.ts` and an intermittent `launcher/smoke.e2e.test.ts` mpv-status check on this machine; the narrowed launcher suites covering the changed stats paths passed.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added a dedicated background stats-daemon lifecycle for the launcher and app runtime. `subminer stats -b` now starts or reuses a detached stats server and returns after startup acknowledgement, while `subminer stats -s` stops that daemon without touching browser tabs. On the app side, new stats background/stop CLI flags bypass the normal single-instance lock only for daemon helper processes, write/read a daemon state file under user data, and reuse an already-running daemon instead of attempting a second local stats bind when another SubMiner instance needs stats access. Updated docs-site stats docs, added a changelog fragment, and covered the new flows with launcher parse/dispatch tests, app stats CLI handler tests, and single-instance bypass tests. Verification run: `bun run typecheck`, `bun run test:env`, `bun run test:fast`, `bun run build`, `bun run test:smoke:dist`, `bun run docs:test`, `bun run docs:build`, `bun run changelog:lint`, plus narrowed changed-path launcher/app test bundles.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Fix-session-stats-chart-known-word-totals-exceeding-total-words.md
+++ b/Fix-session-stats-chart-known-word-totals-exceeding-total-words.md
@@ -0,0 +1,60 @@
+---
+id: TASK-182
+title: Fix session stats chart known-word totals exceeding total words
+status: Done
+milestone: m-1
+assignee:
+  - codex
+created_date: '2026-03-17 16:07'
+updated_date: '2026-03-18 05:28'
+labels: []
+dependencies: []
+references:
+  - /Users/sudacode/projects/japanese/SubMiner/src/core/services/stats-server.ts
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/stats/src/components/sessions/SessionDetail.tsx
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/src/core/services/__tests__/stats-server.test.ts
+  - /Users/sudacode/projects/japanese/SubMiner/stats/src/hooks/useSessions.ts
+ordinal: 109500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Fix the session detail stats display so the known-word series cannot exceed the total-word series for the same sample. Ground the fix in the actual immersion-tracker metrics used by the stats UI and cover the regression with automated tests.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Session detail data uses a consistent cumulative word metric so known-word counts do not exceed total words for a sample
+- [x] #2 Automated tests cover the session known-word timeline contract and reproduce the regression scenario
+- [x] #3 Session stats UI still renders the timeline and tooltip values correctly after the fix
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a regression test for `/api/stats/sessions/:id/known-words-timeline` covering a Japanese-style session where telemetry word counts can be lower than token-derived known-word counts.
+2. Update the stats known-word timeline contract/server implementation so the series is expressed in the same cumulative unit used for total words in the session detail view.
+3. Adjust the session detail UI/types to consume the corrected series and keep tooltip/legend copy coherent.
+4. Run targeted tests for stats server and stats UI transforms, then summarize any wider verification skipped.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented server-side known-word timeline fix to preserve stored line positions and accumulate known-word occurrences rather than compressed unique-headword counts.
+
+Updated session-facing stats views to prefer `tokensSeen` over `wordsSeen` when available so displayed session word totals align with the session chart and lookup-rate denominator.
+
+Verification: `bun test src/core/services/__tests__/stats-server.test.ts`, `bun test stats/src/lib/yomitan-lookup.test.tsx`, `bun test src/core/services/immersion-tracker/__tests__/query.test.ts`, `bun run typecheck` all passed.
+
+Verification skipped/blocker: `bun run typecheck:stats` still fails in pre-existing unrelated files `stats/src/components/anime/AnilistSelector.tsx`, `stats/src/lib/reading-utils.test.ts`, and `stats/src/lib/reading-utils.ts`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Fixed the session stats mismatch that let known words outrun total words. The stats server now preserves actual subtitle-line positions and accumulates known-word occurrences for the session timeline, while session-facing stats views prefer token-based word totals when available. Added regression coverage for the known-word timeline API and for session-row word-count rendering, plus a user-visible changelog fragment.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Remove-misleading-session-new-word-metric-from-session-detail-chart.md
+++ b/Remove-misleading-session-new-word-metric-from-session-detail-chart.md
@@ -0,0 +1,64 @@
+---
+id: TASK-182.1
+title: Remove misleading session new-word metric from session detail chart
+status: Done
+assignee:
+  - '@codex'
+created_date: '2026-03-18 01:41'
+updated_date: '2026-03-18 05:28'
+labels:
+  - bug
+  - stats
+  - ui
+milestone: m-1
+dependencies: []
+references:
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/stats/src/components/sessions/SessionDetail.tsx
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/stats/src/components/sessions/SessionsTab.tsx
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/stats/src/lib/media-session-list.test.tsx
+parent_task_id: TASK-182
+ordinal: 101500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Remove the misleading `New words` series from the session detail chart so the stats UI no longer presents a fabricated metric that mirrors total words. Keep the session chart focused on the real cumulative totals already backed by tracker data.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Expanded session detail chart no longer renders or labels a `New words` metric in the graph, tooltip, or legend
+- [x] #2 Session detail still renders total-word and known-word series correctly after the metric removal
+- [x] #3 Automated frontend coverage prevents the `New words` label from reappearing in expanded session detail
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a focused stats frontend regression test that renders expanded session detail and asserts the misleading `New words` label is absent while `Total words` remains.
+2. Remove the fabricated `New words` area series, tooltip mapping, legend chip, and now-unused left-axis chart plumbing from `stats/src/components/sessions/SessionDetail.tsx`.
+3. Add a user-visible changelog fragment describing the session chart cleanup.
+4. Run targeted frontend tests plus cheap verification and record any blockers.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added a focused server-render regression test for SessionDetail copy to ensure the misleading `New words` label stays removed.
+
+Removed the fabricated `New words` chart series and its legend/tooltip plumbing from the expanded session detail view.
+
+Verification: `bun test stats/src/lib/session-detail.test.tsx stats/src/lib/media-session-list.test.tsx` passed. `bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane core stats/src/components/sessions/SessionDetail.tsx stats/src/lib/session-detail.test.tsx changes/2026-03-18-remove-session-new-words-series.md` passed and wrote artifacts under `.tmp/skill-verification/subminer-verify-20260317-184440-1aMWkM`.
+
+Manual spot-check note: `bun test stats/src/lib/yomitan-lookup.test.tsx` is currently red on a pre-existing `AnimeOverviewStats` lookup-rate assertion unrelated to this session-detail change.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Removed the misleading `New words` metric from expanded session charts. Session detail now shows only the real total-word and known-word lines, backed by existing tracker data, with regression coverage that prevents the `New words` label from reappearing.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Fix-blank-stats-vocabulary-page-regression.md
+++ b/Fix-blank-stats-vocabulary-page-regression.md
@@ -0,0 +1,58 @@
+---
+id: TASK-183
+title: Fix blank stats vocabulary page regression
+status: Done
+milestone: m-1
+assignee:
+  - codex
+created_date: '2026-03-17 16:23'
+updated_date: '2026-03-18 05:28'
+labels: []
+dependencies: []
+references:
+  - >-
+    /Users/sudacode/projects/japanese/SubMiner/stats/src/components/vocabulary/VocabularyTab.tsx
+  - /Users/sudacode/projects/japanese/SubMiner/stats/src/App.tsx
+  - /Users/sudacode/projects/japanese/SubMiner/stats/src/lib/api-client.ts
+ordinal: 108500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Diagnose and fix the stats dashboard regression where the Vocabulary tab renders blank at runtime. Capture the frontend failure with browser debugging, add regression coverage, and restore the vocabulary view.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Vocabulary tab renders without a blank-screen failure in the stats dashboard
+- [x] #2 Automated test coverage reproduces the failing code path and passes with the fix
+- [x] #3 Targeted verification covers the affected stats UI/runtime path
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Reproduce the blank Vocabulary tab locally with a browser-visible stats UI instance and capture console/network failure details.
+2. Add a focused regression test for the failing Vocabulary tab code path before editing production code.
+3. Implement the minimal fix in the stats UI/runtime path.
+4. Re-run targeted browser and automated verification, then record any skipped broader checks.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Identified the runtime failure in the browser console: React reported a hook-order change in `VocabularyTab` after the tab moved from loading to loaded state (`Rendered more hooks than during the previous render`).
+
+Fixed `stats/src/components/vocabulary/VocabularyTab.tsx` by removing the late `useMemo` hook and computing `knownWordCount` as a plain derived value after the loading/error guards.
+
+Added regression coverage in `stats/src/lib/vocabulary-tab.test.ts` to assert that `VocabularyTab` declares all hooks before the loading/error early returns.
+
+Verification: `bun test stats/src/lib/vocabulary-tab.test.ts`, `bun test stats/src/lib/yomitan-lookup.test.tsx`, `bun run build:stats`, and a live Playwright check against the Vite app with stubbed stats API data all passed.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Fixed the blank Vocabulary tab regression in the stats UI. The root cause was a late `useMemo` hook declared after the loading/error early returns in `VocabularyTab`, which caused React to crash once vocabulary data finished loading. Removed that late hook, added a regression test guarding hook placement, verified the stats bundle builds, and confirmed in a live browser that the Vocabulary tab now renders loaded content instead of white-screening.
+<!-- SECTION:FINAL_SUMMARY:END -->
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
sudacode	4c95b57885	chore: prepare v0.9.3 release	2026-03-25 23:58:31 -07:00
sudacode	242402b253	refactor: move youtube primary subtitle config to youtube	2026-03-25 23:53:56 -07:00
sudacode	61d15f9431	docs: apply M PLUS 1 and Manrope font defaults for docs content	2026-03-25 23:52:29 -07:00
sudacode	508864bcbb	chore(backlog): complete backlog cleanup	2026-03-25 22:42:21 -07:00
sudacode	23c54bb01e	chore: prepare v0.9.2 release	2026-03-25 22:37:59 -07:00
sudacode	ec667c64e8	fix: cancel stale autoplay fallback retries	2026-03-25 22:18:26 -07:00
sudacode	39b2ccad8e	fix: address latest coderabbit review	2026-03-25 22:18:26 -07:00
sudacode	23815945bf	chore: remove stale release notes artifact	2026-03-25 22:18:26 -07:00
sudacode	9dca83acd9	fix: delay youtube overlay bootstrap until yomitan loads	2026-03-25 22:18:26 -07:00
Kyle	55300e2d8c	Refine YouTube playback launch preparation	2026-03-25 22:18:26 -07:00
Kyle	28afd15134	Tighten YouTube playback launch readiness	2026-03-25 22:18:26 -07:00
Kyle	58304757aa	Fix YouTube playback PR review issues	2026-03-25 22:18:26 -07:00
Kyle	c95518e94a	Fix Windows YouTube playback flow and overlay pointer tracking	2026-03-25 22:18:26 -07:00
sudacode	5ee4617607	Fix Windows overlay scaling bounds (#34 )	2026-03-25 16:30:11 -07:00
sudacode	842008b089	chore: prepare v0.9.1 release	2026-03-24 00:55:03 -07:00
sudacode	6f56a0bcf6	fix(renderer): keep controller input active with sidebar open	2026-03-24 00:23:00 -07:00
sudacode	5feed360ca	feat: add app-owned YouTube subtitle flow with absPlayer-style parsing (#31 ) * fix: harden preload argv parsing for popup windows * fix: align youtube playback with shared overlay startup * fix: unwrap mpv youtube streams for anki media mining * docs: update docs for youtube subtitle and mining flow * refactor: unify cli and runtime wiring for startup and youtube flow * feat: update subtitle sidebar overlay behavior * chore: add shared log-file source for diagnostics * fix(ci): add changelog fragment for immersion changes * fix: address CodeRabbit review feedback * fix: persist canonical title from youtube metadata * style: format stats library tab * fix: address latest review feedback * style: format stats library files * test: stub launcher youtube deps in CI * test: isolate launcher youtube flow deps * test: stub launcher youtube deps in failing case * test: force x11 backend in launcher ci harness * test: address latest review feedback * fix(launcher): preserve user YouTube ytdl raw options * docs(backlog): update task tracking notes * fix(immersion): special-case youtube media paths in runtime and tracking * feat(stats): improve YouTube media metadata and picker key handling * fix(ci): format stats media library hook * fix: address latest CodeRabbit review items * docs: update youtube release notes and docs * feat: auto-load youtube subtitles before manual picker * fix: restore app-owned youtube subtitle flow * docs: update youtube playback docs and config copy * refactor: remove legacy youtube launcher mode plumbing * fix: refine youtube subtitle startup binding * docs: clarify youtube subtitle startup behavior * fix: address PR #31 latest review follow-ups * fix: address PR #31 follow-up review comments * test: harden youtube picker test harness * udpate backlog * fix: add timeout to youtube metadata probe * docs: refresh youtube and stats docs * update backlog * update backlog * chore: release v0.9.0	2026-03-24 00:01:24 -07:00
sudacode	c17f0a4080	Fix tokenizer annotations for explanatory contrast ending (#33 )	2026-03-23 09:25:17 -07:00
sudacode	0317c7f011	docs: add WebSocket & Texthooker API integration guide (#30 )	2026-03-22 02:48:54 -07:00
sudacode	13797b5005	docs: align v0.8.0 release notes with subtitle sidebar changes	2026-03-22 00:07:05 -07:00
sudacode	b24d9d7487	fix(release): make changelog build idempotent for re-run tagged releases	2026-03-21 23:50:27 -07:00
sudacode	3a01cffc6b	feat(subtitle-sidebar): add sidebar config surface (#28 )	2026-03-21 23:37:42 -07:00
sudacode	eddf6f0456	docs: document release changelog recovery path	2026-03-20 03:15:05 -07:00
sudacode	f6c024d61e	fix: build changelog artifacts in release job	2026-03-20 03:00:40 -07:00
sudacode	6749ff843c	feat(stats): add v1 immersion stats dashboard (#19 )	2026-03-20 02:43:28 -07:00
sudacode	42abdd1268	fix(release): version AUR asset cache aliases	2026-03-17 18:15:23 -07:00
sudacode	5d914b1547	update vendored packages	2026-03-17 18:15:13 -07:00
sudacode	50b45cac0b	Summarize JLPT duplicate term conflicts into a single startup log (#26 )	2026-03-16 01:08:40 -07:00
sudacode	e35aac6ee0	chore: prepare v0.6.5 release	2026-03-15 21:05:58 -07:00
sudacode	fe2da22d29	chore: prepare v0.6.4 release	2026-03-15 20:43:50 -07:00
sudacode	2045ffbff8	chore: prepare v0.6.3 release	2026-03-15 20:16:36 -07:00
sudacode	478869ff28	feat(controller): add inline remap modal with descriptor-based bindings (#21 )	2026-03-15 15:55:45 -07:00
Kyle	9eed37420e	Automate AUR publish in tagged release workflow (#22 )	2026-03-14 19:49:46 -07:00
Kyle	99f4d2baaf	Harden subminer-scrum-master pre-handoff policy checks (#20 )	2026-03-13 01:40:48 -07:00
sudacode	f4e8c3feec	chore: make verifier script executable	2026-03-13 00:44:00 -07:00
sudacode	d0b308f340	test: harden agent verification workflow	2026-03-13 00:44:00 -07:00
Kyle	1b56360a24	feat(yomitan): add read-only external profile support for shared dictionaries (#18 )	2026-03-12 01:17:34 -07:00
sudacode	68833c76c4	Release v0.6.1 and scope workflow write permissions - Bump package version and changelog to v0.6.1 - Move `contents: write` permission to release job only - Remove consumed changelog fragment files	2026-03-11 20:53:52 -07:00
Kyle	4d7c80f2e4	Add overlay gamepad support for keyboard-only mode (#17 )	2026-03-11 20:34:46 -07:00
sudacode	2f17859b7b	Document AUR install flow and add backlog planning artifacts - Add Arch Linux `subminer-bin` install instructions to README and docs-site installation guide - Add Hyprland troubleshooting guidance for transparency and global shortcut passthrough - Add TASK-159..164 backlog records and skill design plans; include changelog fragment - Apply formatting-only update to `src/release-workflow.test.ts`	2026-03-11 02:08:59 -07:00
sudacode	9c7e02cbf0	Enforce config example drift checks in CI and release - add `verify:config-example` script with tests to fail on missing/stale generated config artifacts - run the verification in CI and release workflows, and document it in release/docs guidance - fix docs-site Cloudflare Pages watch path to `docs-site/*` with regression coverage	2026-03-10 20:06:41 -07:00
sudacode	5f320edab5	move docs back repo	2026-03-10 19:47:16 -07:00
sudacode	f7ce3371a1	chore: finalize v0.5.6 changelog fragments	2026-03-10 18:49:21 -07:00
sudacode	71805dccd7	chore: bump package version	2026-03-10 02:33:13 -07:00
sudacode	a13b7352d7	chore: make pretty	2026-03-10 02:32:53 -07:00
sudacode	ff5ecdaded	clean up and add new showcase videos	2026-03-10 02:32:27 -07:00
sudacode	b32c3cf58c	fix: avoid merged dictionary rebuilds on revisits	2026-03-10 02:26:07 -07:00
sudacode	b791262860	fix: keep jlpt underline stable during Yomitan lookup	2026-03-10 01:37:32 -07:00
sudacode	29b8c6e02a	update agents file and readme	2026-03-10 01:27:05 -07:00
sudacode	618727d8e8	fix: set canonical userData path during startup	2026-03-09 23:52:50 -07:00
sudacode	fed60c265d	style: restore repo formatting	2026-03-09 18:10:32 -07:00
sudacode	a34a7489db	chore: prep v0.5.5 release	2026-03-09 18:07:01 -07:00
sudacode	e59192bbe1	Improve startup dictionary progress and fix overlay/plugin input handlin - show a dedicated startup OSD "building" phase for character dictionary sync - forward bare `Tab` from visible overlay to mpv so AniSkip works while focused - fix Windows plugin env override resolution for `SUBMINER_BINARY_PATH`	2026-03-09 02:35:03 -07:00
sudacode	e0f82d28f0	Improve startup dictionary sync UX and default playback keybindings - Add default `f` fullscreen overlay binding and switch default AniSkip skip key to `Tab` - Make character-dictionary auto-sync non-blocking at startup with tokenization gating for Yomitan mutations - Add ordered startup OSD progress (checking/generating/updating/importing), refresh current subtitle on sync completion, and extend regression tests	2026-03-09 00:50:32 -07:00
sudacode	a0521aeeaf	fix(tracker): follow active hyprland and visible x11 windows	2026-03-08 23:03:55 -07:00
sudacode	2127f759ca	fix: correct guessit title parsing for character dictionary sync	2026-03-08 23:03:48 -07:00
sudacode	5e787183d0	cleanup docs	2026-03-08 23:03:08 -07:00
sudacode	81ca31b899	remove release notes	2026-03-08 22:15:21 -07:00
sudacode	e2a7597b4f	update README	2026-03-08 22:10:09 -07:00
sudacode	2e59c21078	chore: prep v0.5.3 release	2026-03-08 22:08:46 -07:00