Fix startup autoplay and dictionary progress sequencing

- keep paused startup release retries aligned with the full gate window
- restore dictionary sync progress and reuse merged zips on unchanged revisits
- surface later dictionary OSD updates once tokenization is ready

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

.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

.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

.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

.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
 

.github/workflows/release.yml

@@ -9,9 +9,6 @@ concurrency:
   group: release-${{ github.ref }}
   cancel-in-progress: false
 
-permissions:
-  contents: write
-
 jobs:
   quality-gate:
     runs-on: ubuntu-latest
@@ -32,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
@@ -86,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: |
@@ -141,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-
 
@@ -168,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: |
@@ -213,14 +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: Install dependencies
-        run: bun install --frozen-lockfile
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
 
       - name: Build texthooker-ui
         shell: powershell
@@ -244,6 +256,8 @@ jobs:
   release:
     needs: [build-linux, build-macos, build-windows]
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -295,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" \
@@ -315,7 +332,7 @@ 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: Verify changelog is ready for tagged release
         run: bun run changelog:check --version "${{ steps.version.outputs.VERSION }}"
@@ -360,3 +377,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

.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,6 +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

AGENTS.md

@@ -1,68 +1,69 @@
 # AGENTS.MD
 
-## PR Feedback
+## Internal Docs
 
-- Active PR: `gh pr view --json number,title,url --jq '"PR #\\(.number): \\(.title)\\n\\(.url)"'`.
+Start here, then leave this file.
-- 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`.
 
-## 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`.
+`docs-site/` is user-facing. Do not treat it as the canonical internal source of truth.
-- 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
+## Quick Start
 
-- The documentation for this project lives in a separate sister directory: [`../subminer-docs/`](https://github.com/ksyasuda/subminer-docs)
+- Init workspace: `git submodule update --init --recursive`
-- Read the [`../subminer-docs/development.md`](https://github.com/ksyasuda/subminer-docs/blob/main/development.md) and [`../subminer-docs/architecture.md`](https://github.com/ksyasuda/subminer-docs/blob/main/architecture.md) before making changes and follow the guidelines unless there is a specific reason to deviate
+- Install deps: `make deps` or `bun install` plus `(cd vendor/texthooker-ui && bun install --frozen-lockfile)`
-- Make sure the changelog [`../subminer-docs/changelog.md`](https://github.com/ksyasuda/subminer-docs/blob/main/changelog.md) is updated on each release
+- Fast dev loop: `make dev-watch`
-- Ensure the docs are kept up to date if any new or breaking changes are introduced
+- Full local run: `bun run dev`
-- If the sister repo does not exist at `../subminer-docs`, then do not attempt
+- Verbose Electron debug: `electron . --start --dev --log-level debug`
-  to update the docs and reference the files from GitHub if needed
-
-## Flow & Runtime
-
-- Use repo’s package manager/runtime; no swaps w/o approval.
-- Use Codex background for long jobs; tmux only for interactive/persistent (debugger/server).
 
 ## Build / Test
 
-- Before handoff: run full gate (lint/typecheck/tests/docs).
+- Runtime/package manager: Bun (`packageManager: bun@1.3.5`)
-- CI red: `gh run list/view`, rerun, fix, push, repeat til green.
+- Default handoff gate:
-- Keep it observable (logs, panes, tails, MCP/browser tools).
+  `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.
+- Config/schema/defaults: `bun run test:config`; if template/defaults changed, `bun run generate:config-example`
-- `git checkout` ok for PR review / explicit request.
+- Launcher/plugin: `bun run test:launcher` or `bun run test:env`
-- Branch changes require user consent.
+- Runtime-compat / dist-sensitive: `bun run test:runtime:compat`
-- Destructive ops forbidden unless explicit (`reset --hard`, `clean`, `restore`, `rm`, …).
+- Docs-only: `bun run docs:test`, then `bun run docs:build`
-- 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.
 
-## Language/Stack Notes
+## Sensitive Files
 
-- Swift: use workspace helper/daemon; validate `swift build` + tests; keep concurrency attrs right.
+- Launcher source of truth: `launcher/*.ts`
-- TypeScript: use repo PM; keep files small; follow existing patterns.
+- 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 -->
 

CHANGELOG.md

@@ -1,5 +1,115 @@
 # Changelog
 
+## 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

CLAUDE.md

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

Makefile

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

README.md

@@ -1,16 +1,20 @@
 <div align="center">
-  <img src="assets/SubMiner.png" width="169" alt="SubMiner logo">
+  <img src="assets/SubMiner.png" width="140" alt="SubMiner logo">
-  <h1>SubMiner</h1>
+
-  <strong>Look up words, mine to Anki, and enrich cards with context — without leaving mpv.</strong>
+# SubMiner
-  <br /><br />
+
+**Sentence-mine from mpv — look up words, one-key Anki export, immersion tracking.**
 
 [![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)]()
+[![Linux](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-informational)](https://github.com/ksyasuda/SubMiner)
 [![Docs](https://img.shields.io/badge/docs-docs.subminer.moe-blueviolet)](https://docs.subminer.moe)
+[![AUR](https://img.shields.io/aur/version/subminer-bin)](https://aur.archlinux.org/packages/subminer-bin)
 
 </div>
 
-<br />
+---
+
+SubMiner is an Electron overlay for [mpv](https://mpv.io) that turns video into a sentence-mining workstation. Look up any word with [Yomitan](https://github.com/yomidevs/yomitan), mine it to Anki with one key, and track your immersion over time.
 
 <div align="center">
 
@@ -18,95 +22,119 @@
 
 </div>
 
-<br />
+## Features
 
-## What it does
+**Dictionary lookups** — Yomitan runs inside the overlay. Hover or navigate to any word for full dictionary popups without leaving mpv.
 
-SubMiner is an Electron overlay that sits on top of mpv. It turns your video player into a full sentence-mining workstation:
+**One-key Anki mining** — Press one key to create a card with the sentence, audio clip, screenshot, and machine translation from the exact playback moment.
 
-- **Look up words as you watch** — Yomitan dictionary popups on hover or keyboard-driven token-by-token navigation
+<div align="center">
-- **One-key Anki mining** — Creates cards with sentence, audio, screenshot, and translation; optional local AnkiConnect proxy auto-enriches Yomitan cards instantly
+  <img src="docs-site/public/screenshots/yomitan-lookup.png" width="800" alt="Yomitan popup with dictionary entry and mine button over annotated subtitles in mpv">
-- **Reading annotations** — N+1 targeting, frequency-dictionary highlighting, JLPT underlining, and character name dictionary for anime/manga proper nouns
+</div>
-- **Subtitle tools** — Download from Jimaku, sync with alass/ffsubsync
-- **Jellyfin & AniList integration** — Remote playback, cast device mode, and automatic episode progress tracking
-- **Texthooker & API** — Built-in texthooker page and annotated websocket feed for external clients
 
-## Quick start
+**Reading annotations** — Real-time subtitle annotations with N+1 targeting, frequency highlighting, JLPT tags, and a character name dictionary. Grammar-only tokens render as plain text.
 
-### 1. Install
+<div align="center">
+  <img src="docs-site/public/screenshots/annotations.png" width="800" alt="Annotated subtitles with frequency highlighting, JLPT underlines, known words, and N+1 targets">
+</div>
 
-**Linux (AppImage):**
+**Immersion dashboard** — Local stats dashboard with watch time, anime progress, vocabulary growth, mining throughput, and session history.
+
+<div align="center">
+  <img src="docs-site/public/screenshots/stats-overview.png" width="800" alt="Stats dashboard with watch time, cards mined, streaks, and tracking snapshot">
+</div>
+
+**Integrations** — AniList episode tracking, Jellyfin remote playback, Jimaku subtitle downloads, alass/ffsubsync, and an annotated websocket feed for external clients.
+
+<div align="center">
+  <img src="docs-site/public/screenshots/texthooker.png" width="800" alt="Texthooker page with annotated subtitle lines and frequency highlighting">
+</div>
+
+---
+
+## Quick Start
+
+### Install
+
+<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
+paru -S subminer-bin
-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
 
+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 / Windows / From source</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).
+**macOS** — Download the latest DMG/ZIP from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest) and drag `SubMiner.app` into `/Applications`.
 
-### 2. Launch the app once
+**Windows** — Download the latest installer or portable `.zip` from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). Keep `mpv` on `PATH`.
+
+**From source** — See [docs.subminer.moe/installation#from-source](https://docs.subminer.moe/installation#from-source).
+
+</details>
+
+### First Launch
+
+Run `SubMiner.AppImage` (Linux), `SubMiner.app` (macOS), or `SubMiner.exe` (Windows). On first launch, SubMiner starts in the tray, creates a default config, and opens a setup popup where you can install the mpv plugin and configure Yomitan dictionaries.
+
+### Mine
 
 ```bash
-# Linux
+subminer video.mkv          # auto-starts overlay + resumes playback
-SubMiner.AppImage
+subminer --start video.mkv  # explicit overlay start (if plugin auto_start=no)
+subminer stats              # open the immersion dashboard
+subminer stats -b           # keep the stats daemon running in background
+subminer stats -s           # stop the dedicated stats daemon
+subminer stats cleanup      # repair/prune stored stats vocabulary rows
 ```
 
-On macOS, launch `SubMiner.app`. On Windows, launch `SubMiner.exe` from the Start menu or install directory.
+---
-
-On first launch, SubMiner:
-
-- 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
-
-### 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                                           |
+| Required                                               | Optional                      |
-| ------------------------------------------ | -------------------------------------------------- |
+| ------------------------------------------------------ | ----------------------------- |
-| `bun` (source builds, Linux `subminer`)    |                                                    |
+| [`mpv`](https://mpv.io) with IPC socket                | `yt-dlp`                      |
-| `mpv` with IPC socket                      | `yt-dlp`                                           |
+| `ffmpeg`                                               | `guessit` (AniSkip detection) |
-| `ffmpeg`                                   | `guessit` (better AniSkip title/episode detection) |
+| `mecab` + `mecab-ipadic`                               | `fzf` / `rofi`                |
-| `mecab` + `mecab-ipadic`                   | `fzf` / `rofi`                                     |
+| [`bun`](https://bun.sh) (source builds, Linux wrapper) | `chafa`, `ffmpegthumbnailer`  |
-| Linux: `hyprctl` or `xdotool` + `xwininfo` | `chafa`, `ffmpegthumbnailer`                       |
+| Linux: `hyprctl` or `xdotool` + `xwininfo`             |                               |
-| macOS: Accessibility permission            |                                                    |
+| macOS: Accessibility permission                        |                               |
 
-Windows builds use native window tracking and do not require the Linux compositor helper tools.
+Windows uses native window tracking and does not need the Linux compositor tools.
 
 ## Documentation
 
-For full guides on configuration, Anki, Jellyfin, and more, see [docs.subminer.moe](https://docs.subminer.moe).
+Full guides on configuration, Anki, Jellyfin, immersion tracking, and more at **[docs.subminer.moe](https://docs.subminer.moe)**.
 
 ## Acknowledgments
 
-Built on the shoulders of [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner), [Renji's Texthooker Page](https://github.com/Renji-XD/texthooker-ui), [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), and JLPT tags from [yomitan-jlpt-vocab](https://github.com/stephenmk/yomitan-jlpt-vocab).
+Built on [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner), [Renji's Texthooker Page](https://github.com/Renji-XD/texthooker-ui), [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script), and [Bee's Character Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary). Subtitles from [Jimaku.cc](https://jimaku.cc). Lookups via [Yomitan](https://github.com/yomidevs/yomitan). JLPT tags from [yomitan-jlpt-vocab](https://github.com/stephenmk/yomitan-jlpt-vocab).
 
 ## License
 

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

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

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

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

backlog/completed/task-155 - 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 -->

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

@@ -6,24 +6,21 @@ title: >-
 status: Done
 assignee: []
 created_date: '2026-03-03 08:47'
-updated_date: '2026-03-03 08:57'
+updated_date: '2026-03-16 05:13'
 labels: []
 dependencies: []
 priority: high
+ordinal: 96500
 ---
 
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Implement initial character dictionary flow: launcher `dictionary` subcommand, app `--dictionary` command, AniList media resolution from current playback, Yomitan zip generation to local file, and local cache to avoid repeated API fetches for same AniList id. Manual Yomitan import path only in this phase.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [x] #1 Launcher supports `dictionary` (and alias) and forwards to app command path.
 - [x] #2 App CLI accepts `--dictionary` and dispatches to dictionary runtime command.
 - [x] #3 Dictionary command resolves current anime to AniList id, generates Yomitan-compatible zip, and logs output path for manual load.
@@ -34,7 +31,6 @@ Implement initial character dictionary flow: launcher `dictionary` subcommand, a
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Implemented launcher `dictionary`/`dict` subcommand parsing and normalized args flow (`launcher/config/cli-parser-builder.ts`, `launcher/config/args-normalizer.ts`, `launcher/types.ts`).
 
 Added launcher command dispatch (`launcher/commands/dictionary-command.ts`) and wired `launcher/main.ts` to forward `--dictionary` (plus non-default `--log-level`) to app binary.
@@ -46,13 +42,10 @@ Added dictionary runtime service (`src/main/character-dictionary-runtime.ts`) th
 Threaded dictionary generation dependency through CLI runtime/context builders and `src/main.ts` context composition so command executes from launcher/app entrypoints.
 
 Added/updated tests for parser, command modules, launcher main forwarding, CLI command dispatch, and context/deps wiring. Updated docs for launcher/usage command lists to include dictionary subcommand.
-
 <!-- SECTION:NOTES:END -->
 
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Initial phase shipped: `subminer dictionary` now routes to `SubMiner.AppImage --dictionary`, generates a Yomitan-importable character dictionary zip for the current anime (AniList-based), logs zip output path for manual import, and reuses cached zips by AniList id to avoid repeated API fetches.
-
 <!-- SECTION:FINAL_SUMMARY:END -->

backlog/milestones/m-1 - stats-dashboard.md

@@ -0,0 +1,8 @@
+---
+id: m-1
+title: "Stats Dashboard"
+---
+
+## Description
+
+Milestone: Stats Dashboard

backlog/tasks/task-100 - 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 -->

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

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

@@ -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,12 +13,12 @@ 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
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Make the packaged Linux no-arg launch path behave like a quiet background start instead of surfacing startup-only noise.
 
 Scope:
@@ -30,9 +30,7 @@ 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.
 - [x] #3 Entry/background launch sanitization suppresses the observed `ExperimentalWarning: SQLite...` and `lsfg-vk ... unsupported configuration version` startup noise.
@@ -42,7 +40,6 @@ Scope:
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Normalized no-arg/password-store-only entry launches to append implicit `--start --background`, and upgraded `--background`-only entry launches to include `--start`.
 
 Applied shared entry env sanitization before loading the main process so default startup strips the `lsfg-vk` Vulkan layer and sets `NODE_NO_WARNINGS=1`; background children keep the same sanitized env.
@@ -55,13 +52,11 @@ Verification:
 - `bun run test:fast`
 
 Note: the final `node --experimental-sqlite --test dist/main/runtime/registry.test.js` step in `bun run test:fast` still prints Node's own experimental SQLite warning because that test command explicitly enables the feature flag outside the app entrypoint.
-
 <!-- SECTION:NOTES:END -->
 
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Default packaged startup is now quiet and behaves like an implicit `--start --background` launch.
 
 - No-arg AppImage entry launches now append `--start --background`, and `--background`-only launches append the missing `--start`.

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

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

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

@@ -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,24 +14,23 @@ 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
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Bring bundled texthooker annotation rendering closer to the visible overlay. Keep the lightweight texthooker UX, but preserve token metadata for hover, match overlay color-precedence rules across known/N+1/name/frequency/JLPT, expose name-match highlighting as a toggle, and emit a structured annotation payload on the dedicated websocket so non-SubMiner clients can treat it as an API.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [x] #1 Annotation websocket payload includes both rendered `sentence` HTML and structured token metadata for generic clients.
 - [x] #2 Vendored texthooker preserves annotation metadata attrs needed for hover labels and uses overlay-matching color precedence rules.
 - [x] #3 Vendored texthooker supports character-name highlighting with a user-facing toggle and standalone-web note.
@@ -42,7 +41,5 @@ Bring bundled texthooker annotation rendering closer to the visible overlay. Kee
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Extended the dedicated annotation websocket payload to ship `version`, plain `text`, rendered `sentence`, and structured `tokens` metadata while keeping backward-compatible `sentence` consumers working. Updated the vendored texthooker to preserve hover metadata attrs, follow overlay color precedence for known/N+1/name/frequency/JLPT annotations, add a character-name highlight toggle plus standalone-web dictionary note, and render lightweight hover labels for frequency/JLPT metadata. Added focused regression coverage and rebuilt both the vendored texthooker bundle and SubMiner.
-
 <!-- SECTION:FINAL_SUMMARY:END -->

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

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

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

@@ -5,23 +5,25 @@ 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/src/main/runtime/first-run-setup-service.ts
-  - /home/sudacode/projects/japanese/SubMiner/launcher/commands/playback-command.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
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Replace the current manual install flow with a first-run setup gate:
 
 - bootstrap the default config dir/config file automatically
@@ -32,9 +34,7 @@ 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.
 - [x] #3 Incomplete installs get a first-run setup popup with mpv plugin install, Yomitan settings, refresh, skip, and finish actions.
@@ -45,7 +45,6 @@ Replace the current manual install flow with a first-run setup gate:
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Added shared setup-state/config/mpv path helpers so Electron and launcher read the same onboarding state file.
 
 Introduced a first-run setup service plus compact BrowserWindow popup using Catppuccin Macchiato styling. The popup supports optional mpv plugin install, opening Yomitan settings, status refresh, skip-plugin, and gated finish once at least one Yomitan dictionary is installed.
@@ -63,7 +62,6 @@ Verification:
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 SubMiner now supports a download-and-launch install flow.
 
 - First launch auto-creates config and opens setup only when needed.

backlog/tasks/task-110 - 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 -->

backlog/tasks/task-111 - 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,20 +15,17 @@ 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
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 When cycling subtitle tracks with the default J/Shift+J keybindings, the mpv OSD currently shows raw template text like `${sid}` instead of a resolved subtitle label. Update the keybinding OSD behavior so users see the active subtitle selection clearly when cycling tracks, and ensure placeholder-based OSD messages sent through the mpv client API render correctly.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [x] #1 Pressing the primary subtitle cycle keybinding shows a resolved subtitle label on the OSD instead of a raw `${sid}` placeholder.
 - [x] #2 Pressing the secondary subtitle cycle keybinding shows a resolved subtitle label on the OSD instead of a raw `${secondary-sid}` placeholder.
 - [x] #3 Proxy OSD messages that rely on mpv property expansion render resolved values when sent through the mpv client API.
@@ -38,7 +35,6 @@ When cycling subtitle tracks with the default J/Shift+J keybindings, the mpv OSD
 ## Implementation Plan
 
 <!-- SECTION:PLAN:BEGIN -->
-
 1. Add focused failing tests for subtitle-cycle OSD labels and mpv placeholder-expansion behavior.
 2. Update the IPC mpv command handler to resolve primary and secondary subtitle track labels from mpv `track-list` data after cycling subtitle tracks.
 3. Update the mpv OSD runtime path so placeholder-based `show-text` messages sent through the client API opt into property expansion.
@@ -48,7 +44,6 @@ When cycling subtitle tracks with the default J/Shift+J keybindings, the mpv OSD
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Initial triage: `ipc-command.ts` emits raw `${sid}`/`${secondary-sid}` placeholder strings, and `showMpvOsdRuntime` sends `show-text` via mpv client API without enabling property expansion.
 
 User approved implementation plan on 2026-03-07.
@@ -64,17 +59,14 @@ Testing: `bun x tsc --noEmit` passed.
 Testing: `bun run test:core:src` passed (423 pass, 6 skip, 0 fail).
 
 Docs: no update required because no checked-in docs or help text describe the J/Shift+J OSD output behavior.
-
 <!-- SECTION:NOTES:END -->
 
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Fixed subtitle-cycle OSD handling for the default J/Shift+J keybindings. The IPC mpv command path now supports resolving proxy OSD text asynchronously, and the main-runtime resolver reads mpv `track-list` state so primary and secondary subtitle cycling show human-readable track labels instead of raw `${sid}` / `${secondary-sid}` placeholders.
 
 Also fixed the lower-level mpv OSD transport so placeholder-based `show-text` messages sent through the client API opt into `expand-properties`. That preserves existing template-based OSD messages like subtitle delay and subtitle position without leaking the raw `${...}` syntax.
 
 Added regression coverage for the async proxy OSD path, the placeholder-expansion `showMpvOsdRuntime` path, and the runtime subtitle-track label resolver. Verification run: `bun x tsc --noEmit`; focused mpv/IPC tests; and the maintained `bun run test:core:src` lane (423 pass, 6 skip, 0 fail).
-
 <!-- SECTION:FINAL_SUMMARY:END -->

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

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

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

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

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

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

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

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

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

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

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

backlog/tasks/task-119 - Add-Jellyfin-remote-session-subtitle-streaming-to-texthooker.md

@@ -4,6 +4,7 @@ title: Add Jellyfin remote-session subtitle streaming to texthooker
 status: To Do
 assignee: []
 created_date: '2026-03-08 03:46'
+updated_date: '2026-03-18 05:27'
 labels:
   - jellyfin
   - texthooker
@@ -19,20 +20,17 @@ references:
 documentation:
   - 'https://api.jellyfin.org/'
 priority: medium
+ordinal: 1000
 ---
 
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Allow SubMiner to follow subtitles from a separate Jellyfin client session, such as a TV app, without requiring local mpv playback. The feature should fetch the active subtitle stream from Jellyfin, map the remote playback position to subtitle cues, and feed the existing subtitle tokenization plus annotated texthooker websocket pipeline so texthooker-only mode can be used while watching on another device.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [ ] #1 User can target a remote Jellyfin session and stream its current subtitle cue into SubMiner's existing subtitle-processing pipeline without launching local Jellyfin playback in mpv.
 - [ ] #2 Texthooker-only mode can display subtitle updates from the tracked remote Jellyfin session through the existing annotation websocket feed.
 - [ ] #3 Remote session changes are handled safely: item changes, subtitle-track changes, pause/seek/stop, and session disconnects clear or refresh subtitle state without crashing.

backlog/tasks/task-120 - 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,20 +12,17 @@ labels:
   - tech-debt
 dependencies: []
 priority: medium
+ordinal: 65500
 ---
 
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Remove the remaining root Node requirement caused by immersion tracking SQLite usage and the old Yomitan build wrapper by migrating the local SQLite layer off node:sqlite, running the SQLite-backed verification lanes under Bun, and switching the vendored Yomitan build flow to Bun-native scripts.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [x] #1 Immersion tracker runtime no longer imports or requires node:sqlite
 - [x] #2 SQLite-backed immersion tracker tests run under Bun without Node --experimental-sqlite
 - [x] #3 Root build/test scripts no longer require the Yomitan Node wrapper or Node-based SQLite verification lanes
@@ -35,7 +32,5 @@ Remove the remaining root Node requirement caused by immersion tracking SQLite u
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Replaced the immersion tracker SQLite dependency with a local libsql-backed wrapper, updated Bun/runtime compatibility tests to avoid process.exitCode side effects, switched Yomitan builds to run directly inside the vendored Bun-native project, deleted scripts/build-yomitan.mjs, and verified typecheck plus Bun build/test lanes (`build:yomitan`, `test:immersion:sqlite`, `test:runtime:compat`, `test:fast`).
-
 <!-- SECTION:FINAL_SUMMARY:END -->

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

backlog/tasks/task-122 - 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,20 +19,17 @@ references:
   - /Users/sudacode/projects/japanese/SubMiner/docs/RELEASING.md
   - /Users/sudacode/projects/japanese/SubMiner/changes/README.md
 priority: medium
+ordinal: 63500
 ---
 
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Improve the release changelog workflow so changelog fragments are reliable, release output is more readable, and pull requests get early feedback when changelog metadata is missing or malformed.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [x] #1 `scripts/build-changelog.ts` ignores non-fragment files in `changes/` and validates fragment structure before generating changelog output.
 - [x] #2 Generated `CHANGELOG.md` and `release/release-notes.md` group public changes into readable sections instead of a flat bullet list.
 - [x] #3 CI enforces changelog validation on pull requests and provides an explicit opt-out path for changes that should not produce release notes.
@@ -43,7 +40,6 @@ Improve the release changelog workflow so changelog fragments are reliable, rele
 ## Implementation Plan
 
 <!-- SECTION:PLAN:BEGIN -->
-
 1. Add failing tests for changelog fragment discovery, structured fragment parsing/rendering, release-note output, and CI workflow expectations.
 2. Update scripts/build-changelog.ts to ignore non-fragment files, parse fragment metadata, group generated output by change type, add lint/PR-check commands, and simplify output paths to repo-local artifacts.
 3. Update CI and PR workflow files to run changelog validation on pull requests with an explicit skip path, and keep release workflow using committed changelog output.
@@ -54,7 +50,6 @@ Improve the release changelog workflow so changelog fragments are reliable, rele
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Implemented structured changelog fragments with required `type` and `area` metadata; `changes/README.md` is now ignored by the generator and verified by regression tests.
 
 Added `changelog:lint` and `changelog:pr-check`, plus PR CI enforcement with `skip-changelog` opt-out. PR check now reads git name-status output so deleted fragment files do not satisfy the requirement.
@@ -64,17 +59,14 @@ Changed generated changelog/release notes output to grouped sections (`Added`, `
 Kept changelog output repo-local. This aligns with existing repo direction where docs updates happen in the sibling docs repo explicitly rather than implicit local writes from app-repo generators.
 
 Verification: `bun test scripts/build-changelog.test.ts src/ci-workflow.test.ts src/release-workflow.test.ts` passed; `bun run typecheck` passed; `bun run changelog:lint` passed. `bun run test:fast` still fails in unrelated existing `src/core/services/subsync.test.ts` cases (`runSubsyncManual keeps internal alass source file alive until sync finishes`, `runSubsyncManual resolves string sid values from mpv stream properties`).
-
 <!-- SECTION:NOTES:END -->
 
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Hardened the changelog workflow end-to-end. `scripts/build-changelog.ts` now ignores helper files like `changes/README.md`, requires structured fragment metadata (`type` + `area`), groups generated release sections by change type, and emits shorter release notes focused on highlights plus install/assets pointers. Added explicit `changelog:lint` and `changelog:pr-check` commands, with PR validation based on git name-status so deleted fragment files do not satisfy the fragment requirement.
 
 Updated contributor-facing workflow docs in `changes/README.md`, `docs/RELEASING.md`, and a new PR template so authors know to add a fragment or apply the `skip-changelog` label. CI now runs fragment linting on every run and enforces fragment presence on pull requests. Added regression coverage in `scripts/build-changelog.test.ts` and a new `src/ci-workflow.test.ts` to lock the workflow contract.
 
 Verification completed: `bun test scripts/build-changelog.test.ts src/ci-workflow.test.ts src/release-workflow.test.ts`, `bun run typecheck`, and `bun run changelog:lint` all passed. A broader `bun run test:fast` run still fails in unrelated existing `src/core/services/subsync.test.ts` cases outside the changelog/workflow scope.
-
 <!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-123 - 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,20 +20,17 @@ references:
   - >-
     /Users/sudacode/projects/japanese/SubMiner/launcher/youtube/subtitle-fix-ai.ts
 priority: medium
+ordinal: 62500
 ---
 
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Improve launcher YouTube subtitle generation observability so users can tell that work is happening and roughly how long each phase is taking. Cover manual subtitle probe, audio extraction, ffmpeg prep, whisper generation, and optional AI subtitle fix phases without flooding normal logs.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [x] #1 Users see clear info-level phase logs for YouTube subtitle generation work including subtitle probe, fallback audio extraction, whisper, and optional AI fix phases.
 - [x] #2 Long-running phases surface elapsed-time progress or explicit start/finish timing so it is obvious the process is still active.
 - [x] #3 Automated tests cover the new logging/progress helper behavior where practical.
@@ -42,19 +39,15 @@ Improve launcher YouTube subtitle generation observability so users can tell tha
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Implemented a shared timed YouTube phase logger in launcher/youtube/progress.ts with info-level start/finish messages and warn-level failure messages that include elapsed time.
 
 Wired phase logging into YouTube metadata probe, manual subtitle probe, fallback audio extraction, ffmpeg whisper prep, whisper primary/secondary generation, and optional AI subtitle fix phases.
 
 Verification: bun test launcher/youtube/progress.test.ts launcher/youtube/orchestrator.test.ts passed; bun run typecheck passed.
-
 <!-- SECTION:NOTES:END -->
 
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Added clear phase-level observability for YouTube subtitle generation without noisy tool output. Users now see start/finish logs with elapsed time for subtitle probe, fallback audio extraction, ffmpeg prep, whisper generation, and optional AI subtitle-fix phases, making it obvious when generation is active and roughly how long each step took.
-
 <!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-124 - 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,20 +27,17 @@ references:
   - >-
     /Users/sudacode/projects/japanese/SubMiner/src/config/resolve/subtitle-domains.ts
 priority: high
+ordinal: 61500
 ---
 
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Simplify launcher YouTube playback by removing the configurable subtitle generation mode. For YouTube targets, the launcher should treat subtitle generation/loading as the canonical behavior instead of supporting off/preprocess/automatic branches. This change should remove the unreliable automatic/background path and the mode concept from config/CLI/env/docs, while preserving the core YouTube subtitle generation pipeline and mpv loading flow.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [x] #1 Launcher playback no longer supports or branches on a YouTube subtitle generation mode; YouTube URLs follow a single generation-and-load flow.
 - [x] #2 Configuration, CLI parsing, and environment handling no longer expose a YouTube subtitle generation mode option, and stale automatic/preprocess/off values are not part of the supported interface.
 - [x] #3 Tests cover the new single-flow behavior and the removal of mode parsing/branching.
@@ -50,7 +47,6 @@ Simplify launcher YouTube playback by removing the configurable subtitle generat
 ## Implementation Plan
 
 <!-- SECTION:PLAN:BEGIN -->
-
 1. Remove the YouTube subtitle generation mode concept from launcher/shared types, config parsing, CLI options, and environment normalization so no supported interface accepts automatic/preprocess/off.
 2. Update playback orchestration so YouTube targets always run subtitle generation/loading before mpv startup and delete the background automatic path.
 3. Adjust mpv YouTube URL argument construction to no longer branch on mode while preserving subtitle/audio language behavior and preloaded subtitle file injection.
@@ -61,7 +57,6 @@ Simplify launcher YouTube playback by removing the configurable subtitle generat
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Removed launcher/shared youtubeSubgen.mode handling and collapsed YouTube playback onto a single preload-before-mpv subtitle generation flow.
 
 Added launcher integration coverage proving YouTube subtitle generation runs before mpv startup and that the removed --mode flag now errors.
@@ -69,17 +64,14 @@ Added launcher integration coverage proving YouTube subtitle generation runs bef
 Verification: bun test launcher/config-domain-parsers.test.ts launcher/parse-args.test.ts launcher/mpv.test.ts launcher/main.test.ts src/config/config.test.ts; bun run test:config:src; bun run typecheck.
 
 Broader repo checks still show pre-existing issues outside this change: bun run test:launcher:unit:src fails in launcher/aniskip-metadata.test.ts (MAL id assertion), and format scope check reports unrelated existing files launcher/youtube/orchestrator.ts, scripts/build-changelog.test.ts, scripts/build-changelog.ts.
-
 <!-- SECTION:NOTES:END -->
 
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Removed the launcher YouTube subtitle generation mode surface so YouTube playback now always runs the subtitle generation pipeline before starting mpv. The launcher no longer accepts youtubeSubgen.mode from shared config, CLI, or env normalization, and the old automatic/background loading path has been deleted from playback.
 
 Updated mpv YouTube startup options to keep manual subtitle discovery enabled without requesting auto subtitles, and refreshed user-facing config/docs to describe a single YouTube subtitle generation flow. Added regression coverage for mode removal, config/template cleanup, and launcher ordering so YouTube subtitle work is confirmed to happen before mpv launch.
 
 Verification: bun test launcher/config-domain-parsers.test.ts launcher/parse-args.test.ts launcher/mpv.test.ts launcher/main.test.ts src/config/config.test.ts; bun run test:config:src; bun run typecheck. Broader unrelated repo issues remain in launcher/aniskip-metadata.test.ts and existing formatting drift in launcher/youtube/orchestrator.ts plus scripts/build-changelog files.
-
 <!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-125 - Add-native-AI-API-key-secret-storage.md

@@ -4,6 +4,7 @@ title: Add native AI API key secret storage
 status: To Do
 assignee: []
 created_date: '2026-03-08 07:25'
+updated_date: '2026-03-18 05:27'
 labels:
   - ai
   - config
@@ -17,20 +18,17 @@ references:
     /Users/sudacode/projects/japanese/SubMiner/src/core/services/jellyfin-token-store.ts
   - /Users/sudacode/projects/japanese/SubMiner/src/main.ts
 priority: medium
+ordinal: 2000
 ---
 
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Store the shared AI provider API key using the app's native secret-storage pattern so users do not need to keep the OpenRouter key in config files or shell commands.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [ ] #1 Users can configure the shared AI provider without storing the API key in config.jsonc.
 - [ ] #2 The app persists and reloads the shared AI API key using encrypted native secret storage when available.
 - [ ] #3 Behavior is defined for existing ai.apiKey and ai.apiKeyCommand configs, including compatibility during migration.

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

@@ -6,27 +6,24 @@ 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
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Adjust overlay secondary subtitle styling so translation text stays readable on bright video backgrounds. Keep the dark background hidden by default in hover mode and show it only while hovered. Increase secondary subtitle weight to 600 and strengthen edge separation without changing primary subtitle styling.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [x] #1 Secondary subtitles render with stronger edge separation than today.
 - [x] #2 Secondary subtitle font weight defaults to 600.
 - [x] #3 When secondary subtitle mode is hover, the secondary background appears only while hovered.
@@ -37,15 +34,11 @@ Adjust overlay secondary subtitle styling so translation text stays readable on
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Adjusted secondary subtitle defaults to use stronger shadowing, 600 font weight, and a translucent dark background. Routed secondary background/backdrop styling through CSS custom properties so hover mode can keep the background hidden until the secondary subtitle is actually hovered. Added renderer and config tests covering default values and hover-only background behavior.
-
 <!-- SECTION:NOTES:END -->
 
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Improved secondary subtitle readability by strengthening default text separation, increasing the default secondary weight to 600, and making the configured dark background appear only while hovered in secondary hover mode. Added config and renderer coverage for the new defaults and hover-aware style routing.
-
 <!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-127 - 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,20 +16,17 @@ references:
   - >-
     /Users/sudacode/projects/japanese/SubMiner/launcher/commands/playback-command.ts
   - /Users/sudacode/projects/japanese/SubMiner/launcher/mpv.test.ts
+ordinal: 56500
 ---
 
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Prevent launcher playback from attempting AniSkip metadata resolution when the user is playing a YouTube target or any URL target. AniSkip only works for local anime files, so URL-driven playback and YouTube subtitle-generation flows should bypass it entirely.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [x] #1 Launcher playback skips AniSkip metadata resolution for explicit URL targets, including YouTube URLs.
 - [x] #2 YouTube subtitle-generation playback does not invoke AniSkip lookup before mpv launch.
 - [x] #3 Automated launcher tests cover the URL/YouTube skip behavior.
@@ -38,7 +35,6 @@ Prevent launcher playback from attempting AniSkip metadata resolution when the u
 ## Implementation Plan
 
 <!-- SECTION:PLAN:BEGIN -->
-
 1. Add a launcher mpv unit test that intercepts AniSkip resolution and proves URL/YouTube playback does not call it before spawning mpv.
 2. Run the focused launcher mpv test to confirm the new case fails or exposes the current gap.
 3. Patch launcher playback/AniSkip gating so URL and YouTube subtitle-generation paths always bypass AniSkip lookup.
@@ -54,7 +50,6 @@ Prevent launcher playback from attempting AniSkip metadata resolution when the u
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Added explicit AniSkip gating in launcher/mpv.ts via shouldResolveAniSkipMetadata(target, targetKind, preloadedSubtitles).
 
 URL targets now always bypass AniSkip. File targets with preloaded subtitles also bypass AniSkip, covering YouTube subtitle-preload playback.
@@ -80,13 +75,10 @@ Verification: lua scripts/test-plugin-start-gate.lua passed.
 Verification: bun run test:plugin:src passed.
 
 Verification: bun test launcher/mpv.test.ts passed after plugin-side fix.
-
 <!-- SECTION:NOTES:END -->
 
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Fixed AniSkip suppression end-to-end for URL playback. The launcher now skips AniSkip before mpv launch, and the mpv plugin now also refuses AniSkip lookups for remote URL media during file-loaded, overlay-start, or later refresh triggers. Added regression coverage in both launcher/mpv.test.ts and scripts/test-plugin-start-gate.lua, plus a changelog fragment. Wider `bun run test:launcher:unit:src` is still blocked by the unrelated existing launcher/aniskip-metadata.test.ts MAL-id failure.
-
 <!-- SECTION:FINAL_SUMMARY:END -->

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

@@ -6,27 +6,24 @@ 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
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 AI subtitle cleanup can preserve cue structure while changing subtitle language, causing primary Japanese subtitle files to come back in English. Add guards so AI-fixed subtitles preserve expected language and fall back to raw Whisper output when language drifts.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [x] #1 Primary AI subtitle fix rejects output that drifts away from the expected source language.
 - [x] #2 Rejected AI fixes fall back to the raw Whisper subtitle without corrupting published subtitle language.
 - [x] #3 Regression tests cover a primary Japanese subtitle batch being translated into English by the AI fixer.
@@ -35,7 +32,5 @@ AI subtitle cleanup can preserve cue structure while changing subtitle language,
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Added a primary-language guard to AI subtitle fixing so Japanese source subtitles are rejected if the AI rewrites them into English while preserving SRT structure. The fixer now receives the expected source language from the YouTube orchestrator, and regression coverage verifies that language drift falls back to the raw Whisper subtitle path.
-
 <!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-129 - 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,20 +14,17 @@ labels:
   - youtube-subgen
 dependencies: []
 priority: high
+ordinal: 57500
 ---
 
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 The current top-level shared AI config forces Anki translation and YouTube subtitle fixing to share the same model and system prompt, which caused subtitle-fix requests to inherit a translation prompt and translate Japanese primary subtitles into English. Refactor config so provider credentials stay shared while model and system prompt can be configured per feature.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [x] #1 Anki integration can use its own AI model and system prompt independently of YouTube subtitle generation.
 - [x] #2 YouTube subtitle generation can use its own AI model and system prompt independently of Anki integration.
 - [x] #3 Existing shared provider credentials remain reusable without duplicating API key/base URL config.
@@ -37,7 +34,5 @@ The current top-level shared AI config forces Anki translation and YouTube subti
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Added per-feature AI model/systemPrompt overrides for Anki and YouTube subtitle generation while keeping shared provider transport settings reusable. Anki now accepts `ankiConnect.ai` object config with `enabled`, `model`, and `systemPrompt`; YouTube subtitle generation accepts `youtubeSubgen.ai` overrides and merges them over the shared AI provider config. Updated config resolution, launcher parsing, runtime wiring, hot-reload handling, example config, and regression coverage.
-
 <!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-130 - 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,20 +13,17 @@ labels:
   - overlay
 dependencies: []
 priority: high
+ordinal: 55500
 ---
 
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 The launcher currently tears down the running SubMiner background process when a launcher-managed mpv session exits. Background SubMiner should remain alive so a later mpv instance can reconnect and request the overlay without restarting the app.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [x] #1 Closing a launcher-managed mpv session does not send `--stop` to the running SubMiner background process.
 - [x] #2 Closing a launcher-managed mpv session does not SIGTERM the tracked SubMiner process just because mpv exited.
 - [x] #3 Launcher cleanup still terminates mpv and launcher-owned helper children without regressing existing overlay start behavior.
@@ -36,7 +33,6 @@ The launcher currently tears down the running SubMiner background process when a
 ## Implementation Plan
 
 <!-- SECTION:PLAN:BEGIN -->
-
 1. Add a launcher regression test that proves mpv exit no longer triggers SubMiner `--stop` or launcher SIGTERM of the tracked overlay process.
 2. Update launcher teardown so normal mpv-session cleanup only stops mpv/helper children and preserves the background SubMiner process for future reconnects.
 3. Run the focused launcher tests and smoke coverage for the affected behavior, then record results in the task.
@@ -45,7 +41,6 @@ The launcher currently tears down the running SubMiner background process when a
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Split launcher cleanup so normal mpv-session shutdown no longer sends `--stop` to SubMiner or SIGTERM to the tracked overlay process. Added `cleanupPlaybackSession()` for mpv/helper-child cleanup only, and switched playback finalization to use it.
 
 Updated launcher smoke coverage to assert the background app stays alive after mpv exits, and added a focused unit regression for the new cleanup path.
@@ -61,13 +56,11 @@ Patched the remaining stop path in `plugin/subminer/lifecycle.lua`: mpv `shutdow
 Validation update: `lua scripts/test-plugin-start-gate.lua` passed after adding a shutdown regression, and `bun test launcher/mpv.test.ts launcher/smoke.e2e.test.ts` still passed.
 
 Fixed a second-instance reconnect bug in `src/core/services/cli-command.ts`: `--start` on an already-initialized running instance now still updates the MPV socket path and reconnects the MPV client instead of treating the command as a no-op. This keeps the already-warmed background app reusable for later mpv launches.
-
 <!-- SECTION:NOTES:END -->
 
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Kept the background SubMiner process reusable across both mpv shutdown and later reconnects. The first fix separated launcher playback cleanup from full app shutdown. The second fix removed the mpv plugin `shutdown` stop call so default mpv `q` no longer sends SubMiner `--stop`. The third fix corrected second-instance CLI handling so `--start` on an already-running, already-initialized instance still reconnects MPV instead of being ignored.
 
 Net effect: background SubMiner can stay alive, keep its warm state, and reconnect to later mpv instances without rerunning startup/warmup work in a fresh app instance.
@@ -82,5 +75,4 @@ Tests run:
 - `bun run changelog:lint`
 
 Note: the broader `bun run test:launcher:unit:src` lane still has an unrelated pre-existing failure in `launcher/aniskip-metadata.test.ts`.
-
 <!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-131 - Avoid-duplicate-tokenization-warmup-after-background-startup.md

@@ -1,72 +0,0 @@
----
-id: TASK-131
-title: Avoid duplicate tokenization warmup after background startup
-status: Done
-assignee:
-  - codex
-created_date: '2026-03-08 10:12'
-updated_date: '2026-03-08 12:00'
-labels:
-  - bug
-dependencies: []
-references:
-  - >-
-    /Users/sudacode/projects/japanese/SubMiner/src/main/runtime/composers/mpv-runtime-composer.ts
-  - >-
-    /Users/sudacode/projects/japanese/SubMiner/src/main/runtime/startup-warmups.ts
-  - >-
-    /Users/sudacode/projects/japanese/SubMiner/src/main/runtime/composers/mpv-runtime-composer.test.ts
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-When SubMiner is already running in the background and mpv is launched from the launcher or mpv plugin, the live app should reuse startup tokenization warmup state instead of re-entering the Yomitan/tokenization/annotation warmup path on first overlay use.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Background startup tokenization warmup is recorded in the runtime state used by later mpv/tokenization flows.
-- [x] #2 Launching mpv from the launcher or plugin against an already-running background app does not re-run duplicate Yomitan/tokenization annotation warmup work in the live process.
-- [x] #3 Regression tests cover the warmed-background path and protect against re-entering duplicate warmup work.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-1. Add a regression test covering the case where background startup warmups already completed and a later tokenize call must not re-enter Yomitan/MeCab/dictionary warmups.
-2. Update mpv tokenization warmup composition so startup background warmups and on-demand tokenization share the same completion state.
-3. Run the focused composer/runtime tests and update acceptance criteria/notes with results.
-<!-- SECTION:PLAN:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Root-cause hypothesis: startup background warmups and on-demand tokenization warmups use separate state, so later mpv launch can re-enter warmup bookkeeping even though background startup already warmed dependencies.
-
-Implemented shared warmup state between startup background warmups and on-demand tokenization warmups by forwarding scheduled Yomitan/tokenization promises into the mpv runtime composer. Added regression coverage for the warmed-background path. Verified with `bun run test:fast` plus focused composer/startup warmup tests.
-
-Follow-up root cause from live retest: second mpv open could still pause on the startup gate because the runtime only treated full background tokenization warmup completion as reusable readiness. In practice, first-file tokenization could already be ready while slower dictionary prewarm work was still finishing, so reopening a video waited on duplicate warmup completion even though annotations were already usable.
-
-Adjusted `src/main/runtime/composers/mpv-runtime-composer.ts` so autoplay reuse keys off a separate playback-ready latch. The latch flips true either when background warmups fully cover tokenization or when `onTokenizationReady` fires for a real subtitle line. `src/main.ts` already uses `isTokenizationWarmupReady()` to fast-signal `subminer-autoplay-ready` on a fresh media-path change, so reopened videos can now resume immediately once tokenization has succeeded once in the persistent app.
-
-Validation update: `bun test src/core/services/cli-command.test.ts src/main/runtime/mpv-main-event-actions.test.ts src/main/runtime/composers/mpv-runtime-composer.test.ts launcher/mpv.test.ts launcher/smoke.e2e.test.ts` passed, `lua scripts/test-plugin-start-gate.lua` passed, and `bun run typecheck` passed.
-
-<!-- SECTION:NOTES:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Background startup tokenization warmups now feed the same in-memory warmup state used by later mpv tokenization. When the app is already running and warmed in the background, launcher/plugin-driven mpv startup reuses that state instead of re-entering Yomitan/tokenization annotation warmups. Added a regression test for the warmed-background path and verified with `bun run test:fast`.
-
-A later follow-up fixed the remaining second-open delay: autoplay reuse no longer waits for the entire background dictionary warmup pipeline to finish. After the persistent app has produced one tokenization-ready event, later mpv reconnects reuse that readiness immediately, so reopening the same or another video does not pause again on duplicate warmup bookkeeping.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

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

@@ -1,31 +1,30 @@
 ---
 id: TASK-131
-title: Make default overlay fullscreen and AniSkip end-jump keybindings easier to reach
+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-09 00:30'
+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.
@@ -34,7 +33,6 @@ Make two default keyboard actions easier to hit during playback: add `f` as the
 ## 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.
@@ -44,7 +42,6 @@ Make two default keyboard actions easier to hit during playback: add `f` as the
 ## 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.
@@ -72,9 +69,7 @@ Known unrelated verification gap:
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Default overlay playback now has an easier fullscreen toggle on `f`, and AniSkip's default intro-end jump now uses `Tab`. The mpv plugin hint text and registration logic were updated to match the new default, while keeping legacy `y-k` fallback behavior limited to custom non-default bindings.
 
 Regression coverage was added for both defaults, and the plugin test harness now resets plugin bootstrap state between scenarios so keybinding assertions can run reliably.
-
 <!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-132 - 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,20 +19,17 @@ references:
   - >-
     /Users/sudacode/projects/japanese/SubMiner/scripts/get-mpv-window-macos.swift
 priority: high
+ordinal: 53500
 ---
 
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Fix the macOS shortcut handling so SubMiner overlay keybinds do not intercept system or other-app shortcuts while SubMiner is in the background. Overlay shortcuts should only be active while the tracked mpv window is present and focused, and should stop grabbing keyboard input when mpv is not the frontmost window.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [x] #1 On macOS, overlay shortcuts do not trigger while mpv is not the focused/frontmost window.
 - [x] #2 On macOS, overlay shortcuts remain available while the tracked mpv window is open and focused.
 - [x] #3 Existing non-macOS shortcut behavior is unchanged.
@@ -43,7 +40,6 @@ Fix the macOS shortcut handling so SubMiner overlay keybinds do not intercept sy
 ## Implementation Plan
 
 <!-- SECTION:PLAN:BEGIN -->
-
 1. Add a failing macOS-focused shortcut lifecycle test that proves overlay shortcuts stay inactive when the tracked mpv window exists but is not frontmost, and activate when that tracked window becomes frontmost.
 2. Add a failing tracker/helper test that covers the focused/frontmost signal parsed from the macOS helper output.
 3. Extend the macOS helper/tracker contract to surface both geometry and focused/frontmost state for the tracked mpv window.
@@ -54,7 +50,6 @@ Fix the macOS shortcut handling so SubMiner overlay keybinds do not intercept sy
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Added a macOS-specific shortcut activation predicate so global overlay shortcuts now require both overlay runtime readiness and a focused tracked mpv window; non-macOS behavior still keys off runtime readiness only.
 
 Extended the base window tracker with optional focus-state callbacks/getters and wired initializeOverlayRuntime to re-sync overlay shortcuts whenever tracker focus changes.
@@ -64,15 +59,12 @@ Updated the macOS helper/tracker contract to return geometry plus frontmost/focu
 Verified with `bun x tsc -p tsconfig.json --noEmit`, targeted shortcut/tracker tests, and `bun run test:core:src` (439 passing).
 
 No user-facing config or documentation surface changed, so no docs update was required for this fix.
-
 <!-- SECTION:NOTES:END -->
 
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Fixed the macOS background shortcut interception bug by gating SubMiner's global overlay shortcuts on tracked mpv focus instead of overlay-runtime initialization alone. The macOS window helper now reports whether the tracked mpv process is frontmost, the tracker exposes focus change callbacks, and overlay shortcut synchronization re-runs when that focus state flips so `Ctrl+C`/`Ctrl+V` and similar shortcuts are no longer captured while mpv is in the background.
 
 The change keeps existing non-macOS shortcut behavior unchanged. Added regression coverage for the activation decision, tracker focus-change re-sync, and macOS helper output parsing. Verification: `bun x tsc -p tsconfig.json --noEmit`, targeted shortcut/tracker tests, and `bun run test:core:src` (439 passing).
-
 <!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-133 - Improve-AniList-character-dictionary-parity-with-upstream-guide.md

@@ -1,11 +1,11 @@
 ---
 id: TASK-133
 title: Improve AniList character dictionary parity with upstream guide
-status: In Progress
+status: To Do
 assignee:
   - OpenCode
 created_date: '2026-03-08 21:06'
-updated_date: '2026-03-10 06:18'
+updated_date: '2026-03-18 05:27'
 labels:
   - dictionary
   - anilist
@@ -24,6 +24,7 @@ documentation:
   - >-
     /Users/sudacode/projects/japanese/SubMiner/docs/plans/2026-03-08-anilist-character-dictionary-parity.md
 priority: high
+ordinal: 3000
 ---
 
 ## Description

backlog/tasks/task-134 - 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,22 +16,19 @@ 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
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 The tag-driven Release workflow currently fails the Windows lane if the SignPath connector returns transient 502 errors during submission, and the tagged build scripts also allow electron-builder to implicitly publish unsigned artifacts before the final release job runs. Harden the workflow so transient SignPath outages get bounded retries and release packaging never auto-publishes unsigned assets.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [ ] #1 Windows release signing retries transient SignPath submission failures within the release workflow before failing the job.
 - [ ] #2 Release packaging scripts disable electron-builder implicit publish so build jobs do not upload unsigned assets on tag builds.
 - [ ] #3 Regression coverage fails if SignPath retry scaffolding or publish suppression is removed.
@@ -40,7 +37,6 @@ The tag-driven Release workflow currently fails the Windows lane if the SignPath
 ## Implementation Plan
 
 <!-- SECTION:PLAN:BEGIN -->
-
 1. Add a regression test for the release workflow/package script shape covering SignPath retries and `--publish never`.
 2. Patch the Windows release job to retry SignPath submission a bounded number of times and still fail hard if every attempt fails.
 3. Update tagged package build scripts to disable implicit electron-builder publishing during release builds.
@@ -50,7 +46,6 @@ The tag-driven Release workflow currently fails the Windows lane if the SignPath
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 The failed Windows signing step in GitHub Actions run `22836585479` was not caused by missing secrets or an artifact-shape mismatch. The SignPath GitHub action retried repeated `502` responses from the SignPath connector for several minutes and then failed the job.
 
 Hardened `.github/workflows/release.yml` by replacing the single SignPath submission with three bounded attempts. The second and third submissions only run if the previous attempt failed, and the job now fails with an explicit rerun message only after all three attempts fail. Signed-artifact upload is keyed to the successful attempt so the release job still consumes the normal `windows` artifact name.
@@ -58,18 +53,15 @@ Hardened `.github/workflows/release.yml` by replacing the single SignPath submis
 Also fixed a separate release regression exposed by the same run: `electron-builder` was implicitly publishing unsigned release assets during tag builds because the packaging scripts did not set `--publish never` and the workflow injected `GH_TOKEN` into build jobs. Updated the relevant package scripts to pass `--publish never`, removed `GH_TOKEN` from the packaging jobs, and made the final publish step force `--draft=false` when editing an existing tag release so previously-created draft releases get published.
 
 Verification: `bun test src/release-workflow.test.ts`, `bun run typecheck`, and `bun run test:fast` all passed locally after restoring the missing local `libsql` install with `bun install --frozen-lockfile`.
-
 <!-- SECTION:NOTES:END -->
 
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Windows release signing is now resilient to transient SignPath connector outages. The release workflow retries the SignPath submission up to three times before failing, and only uploads the signed Windows artifact from the attempt that succeeded.
 
 Release packaging also no longer auto-publishes unsigned assets on tag builds. The `electron-builder` scripts now force `--publish never`, the build jobs no longer pass `GH_TOKEN` into packaging steps, and the final GitHub release publish step explicitly clears draft state when updating an existing tag release.
 
 Validation: `bun test src/release-workflow.test.ts`, `bun run typecheck`, `bun run test:fast`.
 Manual follow-up for the failed `v0.5.0` release: rerun the `Release` workflow after merging/pushing this fix, then clean up the stray draft/untagged release assets created by the failed run if they remain.
-
 <!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-135 - 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,20 +16,17 @@ references:
   - CHANGELOG.md
   - release/release-notes.md
 priority: high
+ordinal: 51500
 ---
 
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Publish a patch release from the workflow-signing fix on `main` by bumping the app version, generating the committed changelog artifacts for the new version, and pushing a new `v0.5.1` tag instead of rewriting the failed `v0.5.0` tag.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [ ] #1 Repository version metadata is updated to `0.5.1`.
 - [ ] #2 `CHANGELOG.md` and `release/release-notes.md` contain the committed `v0.5.1` section and released fragments are removed.
 - [ ] #3 New `v0.5.1` commit and tag are pushed to `origin`.
@@ -38,7 +35,6 @@ Publish a patch release from the workflow-signing fix on `main` by bumping the a
 ## Implementation Plan
 
 <!-- SECTION:PLAN:BEGIN -->
-
 1. Bump the package version to `0.5.1`.
 2. Run the changelog builder so `CHANGELOG.md`/`release-notes.md` match the release workflow contract.
 3. Run the relevant verification commands.
@@ -48,19 +44,15 @@ Publish a patch release from the workflow-signing fix on `main` by bumping the a
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Bumped `package.json` from `0.5.0` to `0.5.1`, then ran `bun run changelog:build` so the committed release artifacts match the release workflow contract. That prepended the `v0.5.1` section to `CHANGELOG.md`, regenerated `release/release-notes.md`, and removed the consumed changelog fragments from `changes/`.
 
 Verification before tagging: `bun run changelog:lint`, `bun run changelog:check --version 0.5.1`, `bun run typecheck`, and `bun run test:fast`.
-
 <!-- SECTION:NOTES:END -->
 
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Prepared patch release `v0.5.1` from the signing-workflow fix on `main` instead of rewriting the failed `v0.5.0` tag. Repository version metadata, changelog, and committed release notes are all aligned with the new release tag, and the consumed changelog fragments were removed.
 
 Validation: `bun run changelog:lint`, `bun run changelog:check --version 0.5.1`, `bun run typecheck`, `bun run test:fast`.
-
 <!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-136 - 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,20 +18,17 @@ references:
   - build/signpath-windows-artifact-config.xml
   - src/release-workflow.test.ts
 priority: high
+ordinal: 49500
 ---
 
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 The Windows release workflow currently relies on the default SignPath artifact configuration configured in the SignPath UI. Pin the workflow to an explicit artifact-configuration slug so the checked-in signing configuration and CI behavior stay deterministic across future SignPath project changes.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [ ] #1 The Windows release workflow validates a dedicated SignPath artifact-configuration secret/input.
 - [ ] #2 Every SignPath submission attempt passes `artifact-configuration-slug`.
 - [ ] #3 Regression coverage fails if the explicit SignPath artifact-configuration binding is removed.
@@ -40,7 +37,6 @@ The Windows release workflow currently relies on the default SignPath artifact c
 ## Implementation Plan
 
 <!-- SECTION:PLAN:BEGIN -->
-
 1. Add a failing workflow regression test for the explicit SignPath artifact-configuration slug.
 2. Patch the Windows signing secret validation and SignPath action inputs to require the slug.
 3. Run targeted release-workflow verification plus the standard fast lane.
@@ -50,21 +46,17 @@ The Windows release workflow currently relies on the default SignPath artifact c
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Added regression coverage in `src/release-workflow.test.ts` for an explicit SignPath artifact-configuration slug so the release workflow test now fails if the slug validation or action input is removed.
 
 Patched `.github/workflows/release.yml` so Windows signing now requires `SIGNPATH_ARTIFACT_CONFIGURATION_SLUG` during secret validation and passes `artifact-configuration-slug: ${{ secrets.SIGNPATH_ARTIFACT_CONFIGURATION_SLUG }}` on every SignPath submission attempt.
 
 Verification: `bun test src/release-workflow.test.ts`, `bun run typecheck`, `bun run test:fast`.
-
 <!-- SECTION:NOTES:END -->
 
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 The release workflow is now pinned to an explicit SignPath artifact configuration instead of relying on whichever SignPath artifact config is marked default in the UI. Windows signing secret validation fails fast if `SIGNPATH_ARTIFACT_CONFIGURATION_SLUG` is missing, and every SignPath submission attempt now includes the pinned slug.
 
 Validation: `bun test src/release-workflow.test.ts`, `bun run typecheck`, `bun run test:fast`.
-
 <!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-137 - 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,20 +16,17 @@ references:
   - CHANGELOG.md
   - release/release-notes.md
 priority: high
+ordinal: 50500
 ---
 
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 Publish a patch release from the SignPath artifact-configuration pinning change by bumping the app version, generating the committed changelog artifacts for the new version, and pushing a new `v0.5.2` tag.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
 - [ ] #1 Repository version metadata is updated to `0.5.2`.
 - [ ] #2 `CHANGELOG.md` and `release/release-notes.md` contain the committed `v0.5.2` section and consumed fragments are removed.
 - [ ] #3 New `v0.5.2` commit and tag are pushed to `origin`.
@@ -38,7 +35,6 @@ Publish a patch release from the SignPath artifact-configuration pinning change
 ## Implementation Plan
 
 <!-- SECTION:PLAN:BEGIN -->
-
 1. Add the release fragment for the SignPath configuration pinning change.
 2. Bump `package.json` to `0.5.2` and run the changelog builder.
 3. Run changelog/typecheck/test verification.
@@ -48,19 +44,15 @@ Publish a patch release from the SignPath artifact-configuration pinning change
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Bumped `package.json` from `0.5.1` to `0.5.2`, ran `bun run changelog:build`, and committed the generated release artifacts. That prepended the `v0.5.2` section to `CHANGELOG.md`, regenerated `release/release-notes.md`, and removed the consumed `changes/signpath-artifact-config-pin.md` fragment.
 
 Verification before tagging: `bun run changelog:lint`, `bun run changelog:check --version 0.5.2`, `bun run typecheck`, and `bun run test:fast`.
-
 <!-- SECTION:NOTES:END -->
 
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Prepared patch release `v0.5.2` so the explicit SignPath artifact-configuration pin ships on a fresh release tag. Version metadata, committed changelog artifacts, and release notes are aligned with the new patch version.
 
 Validation: `bun run changelog:lint`, `bun run changelog:check --version 0.5.2`, `bun run typecheck`, `bun run test:fast`.
-
 <!-- SECTION:FINAL_SUMMARY:END -->

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

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-09 00:00'
-updated_date: '2026-03-09 00:00'
+updated_date: '2026-03-18 05:28'
 labels:
   - release
   - windows
@@ -15,20 +15,17 @@ references:
   - 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.
@@ -38,7 +35,6 @@ Stop the tag-driven release workflow from depending on SignPath and publish unsi
 ## 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.
@@ -48,19 +44,16 @@ Stop the tag-driven release workflow from depending on SignPath and publish unsi
 ## 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:

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

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-09 00:00'
-updated_date: '2026-03-09 00:00'
+updated_date: '2026-03-18 05:28'
 labels:
   - release
   - patch
@@ -16,20 +16,17 @@ references:
   - 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`.
@@ -38,7 +35,6 @@ Publish a patch release from the unsigned Windows release-build change by bumpin
 ## 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.
@@ -48,19 +44,15 @@ Publish a patch release from the unsigned Windows release-build change by bumpin
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Bumped `package.json` from `0.5.2` to `0.5.3`, ran `bun run changelog:build`, and committed the generated release artifacts. That prepended the `v0.5.3` section to `CHANGELOG.md`, regenerated `release/release-notes.md`, and removed the consumed `changes/unsigned-windows-release-builds.md` fragment.
 
 Verification before push: `bun run changelog:lint`, `bun run changelog:check --version 0.5.3`, `bun run typecheck`, and `bun run test:fast`.
-
 <!-- SECTION:NOTES:END -->
 
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
 Prepared patch release `v0.5.3` so the unsigned Windows release-build change is captured in committed release metadata on `main`. Version metadata, changelog output, and release notes are aligned with the new patch version.
 
 Validation: `bun run changelog:lint`, `bun run changelog:check --version 0.5.3`, `bun run typecheck`, `bun run test:fast`.
-
 <!-- SECTION:FINAL_SUMMARY:END -->

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

@@ -4,7 +4,7 @@ title: Fix guessit title parsing for character dictionary sync
 status: Done
 assignee: []
 created_date: '2026-03-09 00:00'
-updated_date: '2026-03-09 00:25'
+updated_date: '2026-03-18 05:28'
 labels:
   - dictionary
   - anilist
@@ -12,23 +12,22 @@ labels:
   - 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
+    /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.
@@ -38,7 +37,5 @@ Fix AniList character dictionary auto-sync for filenames where `guessit` mispars
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Root repro: `guessit` parsed the Bunny Girl Senpai full path as `title: ["Rascal", "Does-not-Dream-of-Bunny-Girl-Senapi"]`, and our `firstString` helper kept only `Rascal`, which resolved to AniList 3490 (`rayca`) and produced zero character results. Fixed by sending basename-only input to `guessit` and joining multi-part guessit title arrays.
-
 <!-- SECTION:NOTES:END -->

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

@@ -4,30 +4,28 @@ title: Refresh current subtitle after character dictionary sync completes
 status: Done
 assignee: []
 created_date: '2026-03-09 00:00'
-updated_date: '2026-03-09 00:55'
+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/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.
@@ -36,7 +34,5 @@ When character dictionary auto-sync finishes after startup tokenization, invalid
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 Observed on Bunny Girl Senpai startup: autoplay/tokenization became ready around 8s, but snapshot/import/state write completed roughly 31s after launch, leaving the current subtitle tokenized without the newly imported character dictionary. Fixed by adding an auto-sync completion hook that clears parser caches and refreshes the current subtitle.
-
 <!-- SECTION:NOTES:END -->

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

@@ -4,31 +4,30 @@ title: Show character dictionary auto-sync progress on OSD
 status: Done
 assignee: []
 created_date: '2026-03-09 01:10'
-updated_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/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.
@@ -37,7 +36,5 @@ When character dictionary auto-sync runs for a newly opened anime, surface progr
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
-
 OSD now shows auto-sync phase changes while the dictionary updates. Desktop notifications were removed for this path to avoid startup popup spam.
-
 <!-- SECTION:NOTES:END -->

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

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

backlog/tasks/task-144 - Sequence-startup-OSD-notifications-for-tokenization-annotations-and-character-dictionary-sync.md

@@ -1,10 +1,12 @@
 ---
 id: TASK-144
-title: Sequence startup OSD notifications for tokenization, annotations, and character dictionary sync
+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-09 10:40'
+updated_date: '2026-03-18 05:28'
 labels:
   - startup
   - overlay
@@ -12,24 +14,24 @@ labels:
 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/startup-osd-sequencer.ts
-  - /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync-notifications.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.
@@ -38,7 +40,5 @@ Keep startup OSD progress ordered. While tokenization is still pending, only sho
 ## 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 -->

backlog/tasks/task-145 - Show-character-dictionary-build-progress-on-startup-OSD-before-import.md

@@ -1,43 +0,0 @@
----
-id: TASK-145
-title: Show character dictionary build progress on startup OSD before import
-status: Done
-assignee: []
-created_date: '2026-03-09 11:20'
-updated_date: '2026-03-09 11:20'
-labels:
-  - startup
-  - dictionary
-  - ux
-dependencies: []
-references:
-  - /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/runtime/character-dictionary-auto-sync.test.ts
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Surface an explicit character-dictionary build phase on startup OSD so there is visible progress between subtitle annotation loading and the later import/upload step when merged dictionary generation is still running.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Auto-sync emits a dedicated in-flight status while merged dictionary generation is running.
-- [x] #2 Startup OSD sequencing treats that build phase as progress and can surface it after annotation loading clears.
-- [x] #3 Regression coverage verifies the build phase is emitted before import begins.
-<!-- AC:END -->
-
-## Implementation Notes
-
-<!-- SECTION:NOTES:BEGIN -->
-
-Added a `building` progress phase before `buildMergedDictionary(...)` and included it in the startup OSD sequencer's buffered progress set. This gives startup a visible dictionary-progress step even when snapshot checking/generation finished too early to still be relevant by the time annotation loading completes.
-
-<!-- SECTION:NOTES:END -->

backlog/tasks/task-145 - Show-checking-and-generation-OSD-for-character-dictionary-auto-sync.md

@@ -4,7 +4,7 @@ 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-09 11:20'
+updated_date: '2026-03-16 05:13'
 labels:
   - dictionary
   - overlay
@@ -12,24 +12,24 @@ labels:
 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/runtime/character-dictionary-auto-sync.ts
-  - /home/sudacode/projects/japanese/SubMiner/src/main/character-dictionary-runtime.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.
@@ -38,9 +38,7 @@ Surface an immediate startup OSD that the character dictionary is being checked,
 ## 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 -->

backlog/tasks/task-146 - Forward-overlay-Tab-to-mpv-for-AniSkip.md

@@ -5,27 +5,24 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-09 00:00'
-updated_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.
@@ -34,7 +31,6 @@ Fix visible-overlay keyboard handling so bare `Tab` is forwarded to mpv instead
 ## 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`.
@@ -44,7 +40,6 @@ Fix visible-overlay keyboard handling so bare `Tab` is forwarded to mpv instead
 ## 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.
@@ -58,9 +53,7 @@ Verification:
 ## 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 -->

backlog/tasks/task-148 - Fix-Windows-plugin-env-binary-override-resolution.md

@@ -5,41 +5,35 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-09 00:00'
-updated_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 -->

backlog/tasks/task-149 - Cut-patch-release-v0.5.5-for-character-dictionary-updates-and-release-guarding.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-09 01:10'
-updated_date: '2026-03-09 01:14'
+updated_date: '2026-03-18 05:28'
 labels:
   - release
   - patch
@@ -25,20 +25,17 @@ references:
   - 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`.
@@ -49,7 +46,6 @@ Prepare and publish patch release `v0.5.5` after the failed `v0.5.4` tag by alig
 ## 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.
@@ -60,21 +56,17 @@ Prepare and publish patch release `v0.5.5` after the failed `v0.5.4` tag by alig
 ## 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 -->

backlog/tasks/task-150 - Restore-repo-wide-Prettier-cleanliness-after-release-prep.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-09 01:11'
-updated_date: '2026-03-09 01:11'
+updated_date: '2026-03-18 05:28'
 labels:
   - tooling
   - formatting
@@ -20,20 +20,17 @@ references:
   - 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.
@@ -42,7 +39,6 @@ Bring `bun run format:check` back to green after the `v0.5.5` release-prep work
 ## 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.
@@ -52,17 +48,13 @@ Bring `bun run format:check` back to green after the `v0.5.5` release-prep work
 ## 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 -->

backlog/tasks/task-151 - Keep-JLPT-underline-color-stable-during-Yomitan-text-selection.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - OpenCode
 created_date: '2026-03-10 06:42'
-updated_date: '2026-03-10 07:54'
+updated_date: '2026-03-16 05:13'
 labels: []
 dependencies: []
 references:
@@ -15,6 +15,7 @@ documentation:
   - ../subminer-docs/development.md
   - ../subminer-docs/architecture.md
 priority: medium
+ordinal: 33500
 ---
 
 ## Description

backlog/tasks/task-152 - Fix-early-Electron-userData-path-casing-to-stay-under-SubMiner-config-dir.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-10 06:46'
-updated_date: '2026-03-10 06:51'
+updated_date: '2026-03-16 05:13'
 labels:
   - bug
   - config
@@ -19,6 +19,7 @@ documentation:
   - /home/sudacode/projects/japanese/subminer-docs/development.md
   - /home/sudacode/projects/japanese/subminer-docs/architecture.md
 priority: high
+ordinal: 34500
 ---
 
 ## Description

backlog/tasks/task-153 - Fix-character-dictionary-MRU-eviction-after-revisits.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - '@codex'
 created_date: '2026-03-10 07:56'
-updated_date: '2026-03-10 08:48'
+updated_date: '2026-03-16 05:13'
 labels:
   - character-dictionary
   - yomitan
@@ -22,6 +22,7 @@ documentation:
   - /home/sudacode/projects/japanese/subminer-docs/development.md
   - /home/sudacode/projects/japanese/subminer-docs/architecture.md
 priority: high
+ordinal: 32500
 ---
 
 ## Description

backlog/tasks/task-154 - Avoid-merged-dictionary-rebuilds-on-MRU-reorder-only-revisits.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - '@codex'
 created_date: '2026-03-10 09:16'
-updated_date: '2026-03-10 09:22'
+updated_date: '2026-03-16 05:13'
 labels:
   - character-dictionary
   - yomitan
@@ -24,6 +24,7 @@ documentation:
   - /home/sudacode/projects/japanese/subminer-docs/development.md
   - /home/sudacode/projects/japanese/subminer-docs/architecture.md
 priority: high
+ordinal: 31500
 ---
 
 ## Description

backlog/tasks/task-156 - 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 -->

backlog/tasks/task-157 - 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 -->

backlog/tasks/task-158 - 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 -->

backlog/tasks/task-159 - 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 -->

backlog/tasks/task-160 - 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 -->

backlog/tasks/task-161 - 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 -->

backlog/tasks/task-162 - 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 -->

backlog/tasks/task-163 - 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 -->

backlog/tasks/task-164 - 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 -->

backlog/tasks/task-165 - 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 -->

backlog/tasks/task-165 - Rewrite-SubMiner-agentic-testing-automation-plan.md

@@ -0,0 +1,65 @@
+---
+id: TASK-165
+title: Rewrite SubMiner agentic testing automation plan
+status: Done
+assignee: []
+created_date: '2026-03-13 04:45'
+updated_date: '2026-03-16 05:13'
+labels:
+  - planning
+  - testing
+  - agents
+dependencies: []
+references:
+  - /home/sudacode/projects/japanese/SubMiner/testing-plan.md
+  - >-
+    /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/docs-site/development.md
+  - /home/sudacode/projects/japanese/SubMiner/docs-site/architecture.md
+ordinal: 23500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Replace the current generic Electron/mpv testing plan with a SubMiner-specific plan that uses the existing skills as the source of truth, treats real launcher/plugin/mpv runtime verification as primary, and defines a non-interference contract for parallel agent work.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 `testing-plan.md` is rewritten for SubMiner rather than a generic Electron+mpv app
+- [x] #2 The plan keeps `subminer-scrum-master` and `subminer-change-verification` as the primary orchestration and verification entrypoints
+- [x] #3 The plan defines real launcher/plugin/mpv runtime verification as the authoritative lane for runtime bug claims
+- [x] #4 The plan defines explicit session isolation and non-interference rules for parallel agent work
+- [x] #5 The plan defines artifact/reporting expectations and phased rollout, with synthetic/headless verification clearly secondary to real-runtime verification
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Review the existing testing plan and compare it against current SubMiner architecture, verification lanes, and skills.
+2. Replace the generic Electron/mpv harness framing with a SubMiner-specific control plane centered on existing skills.
+3. Define the authoritative real-runtime lane, session isolation rules, concurrency classes, and reporting contract.
+4. Sanity-check the rewritten document against current repo docs and skill contracts before handoff.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Rewrote `testing-plan.md` around existing `subminer-scrum-master` and `subminer-change-verification` responsibilities instead of proposing a competing new top-level testing skill.
+
+Set real launcher/plugin/mpv/runtime verification as the authoritative lane for runtime bug claims and made synthetic/headless verification explicitly secondary.
+
+Defined session-scoped paths, unique mutable resources, concurrency classes, and an exclusive lease for conflicting real-runtime verification to prevent parallel interference.
+
+Sanity-checked the final document by inspecting the rewritten file content and diff.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Rewrote `testing-plan.md` into a SubMiner-specific agentic verification plan. The new document keeps `subminer-scrum-master` and `subminer-change-verification` as the primary orchestration and verification entrypoints, treats the real launcher/plugin/mpv/runtime path as authoritative for runtime bug claims, and defines a hard non-interference contract for parallel work through session isolation and an exclusive real-runtime lease. The plan now also includes an explicit reporting schema, capture policy, phased rollout, and a clear statement that true parallel full-app instances are not a phase-1 requirement. Verification for this task was a document sanity pass against the current repo docs, skills, and the resulting file diff.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-166 - 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 -->

backlog/tasks/task-167 - 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 -->

backlog/tasks/task-168 - 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 -->

backlog/tasks/task-169 - 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 -->

backlog/tasks/task-169 - Cut-minor-release-v0.7.0-for-stats-and-runtime-polish.md

@@ -0,0 +1,80 @@
+---
+id: TASK-169
+title: Cut minor release v0.7.0 for stats and runtime polish
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-19 17:20'
+updated_date: '2026-03-19 17:31'
+labels:
+  - release
+  - docs
+  - minor
+dependencies:
+  - TASK-168
+references:
+  - package.json
+  - README.md
+  - docs/RELEASING.md
+  - docs-site/changelog.md
+  - CHANGELOG.md
+  - release/release-notes.md
+priority: high
+ordinal: 108000
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Prepare the next release cut as `v0.7.0`, keeping 0-ver semantics by rolling the accumulated stats/dashboard, launcher, overlay, and stability work into the next minor line instead of a `1.0.0` release.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Repository version metadata is updated to `0.7.0`.
+- [x] #2 Root release-facing docs are refreshed for the `0.7.0` release cut.
+- [x] #3 `CHANGELOG.md` and `release/release-notes.md` contain the committed `v0.7.0` section and consumed fragments are removed.
+- [x] #4 Public changelog/docs surfaces reflect the new release.
+- [x] #5 Release-prep verification is recorded.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Bump `package.json` to `0.7.0`.
+2. Refresh release-facing docs: root `README.md`, release guide versioning note, and public docs changelog summary.
+3. Run `bun run changelog:build --version 0.7.0` to commit release artifacts and consume pending fragments.
+4. Run release-prep verification (`changelog`, typecheck, tests, docs build if docs-site changed).
+5. Update this task with notes, verification, and final summary.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Bumped `package.json` from `0.6.5` to `0.7.0` and refreshed the root release-facing copy in `README.md` so the release prep explicitly calls out the new stats/dashboard line plus the background stats daemon commands. Updated `docs/RELEASING.md` with the repo's 0-ver versioning policy and an explicit `--date` reminder after the changelog generator initially stamped `2026-03-20` from UTC instead of the intended local release date `2026-03-19`.
+
+Ran `bun run changelog:build --version 0.7.0`, which generated `CHANGELOG.md` and `release/release-notes.md` and removed the queued `changes/*.md` fragments for the accumulated stats, launcher, overlay, JLPT, and stability work. Added a curated `v0.7.0` summary to `docs-site/changelog.md` so the public docs changelog stays aligned with the committed root changelog while remaining user-facing.
+
+Verification:
+- `bash .agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh`
+- `bun run changelog:lint`
+- `bun run changelog:check --version 0.7.0`
+- `bun run verify:config-example`
+- `bun run typecheck`
+- `bun run test:fast`
+- `bun run test:env`
+- `bun run build`
+- `bun run docs:test`
+- `bun run docs:build`
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Prepared minor release `v0.7.0` as the next 0-ver major line. Version metadata, root changelog, generated release notes, README release copy, release-guide policy, and the public docs changelog are now aligned for the release cut.
+
+Docs update required: yes. Completed in `README.md`, `docs/RELEASING.md`, and `docs-site/changelog.md`.
+Changelog fragment required: no new fragment for this task. Existing pending release fragments were consumed into the committed `v0.7.0` changelog section and `release/release-notes.md`.
+
+Release-prep verification passed across changelog validation, config-example verification, typecheck, fast/env tests, full build, and docs-site test/build.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-170 - 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 -->

backlog/tasks/task-171 - 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 -->

backlog/tasks/task-172 - 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 -->

backlog/tasks/task-173 - 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 -->

backlog/tasks/task-173 - 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 -->

backlog/tasks/task-174 - 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 -->

backlog/tasks/task-176 - 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 -->