chore(vendor): bump subminer-yomitan

Update configuration, immersion tracking, and mining workflow docs.
Add backlog tasks for upcoming work items and change notes for recent
features and fixes.

.agents/plugins/marketplace.json

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

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

@@ -1,22 +1,127 @@
 ---
-name: 'subminer-change-verification'
-description: 'Compatibility shim. Canonical SubMiner change verification workflow now lives in the repo-local subminer-workflow plugin.'
+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."
 ---
 
-# Compatibility Shim
+# SubMiner Change Verification
 
-Canonical source:
+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.
 
-- `plugins/subminer-workflow/skills/subminer-change-verification/SKILL.md`
+## Scripts
 
-Canonical helper 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.
 
-- `plugins/subminer-workflow/skills/subminer-change-verification/scripts/classify_subminer_diff.sh`
-- `plugins/subminer-workflow/skills/subminer-change-verification/scripts/verify_subminer_change.sh`
+If you need an explicit installed path, use the directory that contains this `SKILL.md`. The helper scripts live under:
 
-When this shim is invoked:
+```bash
+export SUBMINER_VERIFY_SKILL="<path-to-skill>"
+```
 
-1. Read the canonical plugin-owned skill.
-2. Follow the plugin-owned skill as the source of truth.
-3. Use the wrapper scripts in this shim directory only for compatibility with existing commands, docs, and backlog history.
-4. Do not duplicate workflow changes here; update the plugin-owned skill and scripts instead.
+## 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

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

@@ -1,13 +1,566 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
-REPO_ROOT=$(cd "$SCRIPT_DIR/../../../.." && pwd)
-TARGET="$REPO_ROOT/plugins/subminer-workflow/skills/subminer-change-verification/scripts/verify_subminer_change.sh"
+usage() {
+  cat <<'EOF'
+Usage: verify_subminer_change.sh [options] [path ...]
 
-if [[ ! -x "$TARGET" ]]; then
-  echo "Missing canonical script: $TARGET" >&2
-  exit 1
+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
 
-exec "$TARGET" "$@"
+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

@@ -1,18 +1,146 @@
 ---
-name: 'subminer-scrum-master'
-description: 'Compatibility shim. Canonical SubMiner scrum-master workflow now lives in the repo-local subminer-workflow plugin.'
+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."
 ---
 
-# Compatibility Shim
+# SubMiner Scrum Master
 
-Canonical source:
+Own workflow, not code by default.
 
-- `plugins/subminer-workflow/skills/subminer-scrum-master/SKILL.md`
+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.
 
-When this shim is invoked:
+## Core Rules
 
-1. Read the canonical plugin-owned skill.
-2. Follow the plugin-owned skill as the source of truth.
-3. Do not duplicate workflow changes here; update the plugin-owned skill instead.
+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.
 
-This shim exists so existing repo references and prompts keep resolving during the migration to the repo-local plugin workflow.
+## 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

@@ -61,16 +61,6 @@ jobs:
       - name: Test suite (source)
         run: bun run test:fast
 
-      - name: Coverage suite (maintained source lane)
-        run: bun run test:coverage:src
-
-      - name: Upload coverage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-test-src
-          path: coverage/test-src/lcov.info
-          if-no-files-found: error
-
       - name: Launcher smoke suite (source)
         run: bun run test:launcher:smoke:src
 

.github/workflows/release.yml

@@ -49,16 +49,6 @@ jobs:
       - name: Test suite (source)
         run: bun run test:fast
 
-      - name: Coverage suite (maintained source lane)
-        run: bun run test:coverage:src
-
-      - name: Upload coverage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-test-src
-          path: coverage/test-src/lcov.info
-          if-no-files-found: error
-
       - name: Launcher smoke suite (source)
         run: bun run test:launcher:smoke:src
 
@@ -99,17 +89,14 @@ 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', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
           restore-keys: |
             ${{ runner.os }}-bun-
 
       - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
+        run: bun install --frozen-lockfile
 
       - name: Build texthooker-ui
         run: |
@@ -157,10 +144,9 @@ 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', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
           restore-keys: |
             ${{ runner.os }}-bun-
 
@@ -185,9 +171,7 @@ jobs:
           APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
 
       - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
+        run: bun install --frozen-lockfile
 
       - name: Build texthooker-ui
         run: |
@@ -232,17 +216,14 @@ 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', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
           restore-keys: |
             ${{ runner.os }}-bun-
 
       - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
+        run: bun install --frozen-lockfile
 
       - name: Build texthooker-ui
         shell: powershell
@@ -344,14 +325,6 @@ jobs:
         id: version
         run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
 
-      - name: Build changelog artifacts for release
-        run: |
-          if find changes -maxdepth 1 -name '*.md' -not -name README.md -print -quit | grep -q .; then
-            bun run changelog:build --version "${{ steps.version.outputs.VERSION }}"
-          else
-            echo "No pending changelog fragments found."
-          fi
-
       - name: Verify changelog is ready for tagged release
         run: bun run changelog:check --version "${{ steps.version.outputs.VERSION }}"
 

.gitignore

@@ -1,15 +1,11 @@
 # Dependencies
 node_modules/
 
-# Superpowers brainstorming
-.superpowers/
-
 # Electron build output
 out/
 dist/
 release/
 build/yomitan/
-coverage/
 
 # Launcher build artifact (produced by make build-launcher)
 /subminer
@@ -26,7 +22,9 @@ Thumbs.db
 .idea/
 *.swp
 *.swo
+**/CLAUDE.md
 environment.toml
+**/CLAUDE.md
 .env
 .vscode/*
 

AGENTS.md

@@ -83,6 +83,7 @@ This project uses Backlog.md MCP for all task and project management activities.
 - **When to read it**: BEFORE creating tasks, or when you're unsure whether to track work
 
 These guides cover:
+
 - Decision framework for when to create tasks
 - Search-first workflow to avoid duplicates
 - Links to detailed guides for task creation, execution, and finalization

Backlog.md

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

CHANGELOG.md

@@ -1,163 +1,5 @@
 # Changelog
 
-## v0.10.0 (2026-03-29)
-
-### Changed
-- Integrations: Replaced the deprecated Discord Rich Presence wrapper with the maintained `@xhayper/discord-rpc` package.
-
-### Fixed
-- Stats: Fixed stats startup so the immersion tracker can run when `Bun.serve` is unavailable.
-- Stats: Stats server now falls back to a Node `http` listener in Electron/runtime paths that do not expose Bun.
-- Overlay: Fixed the macOS visible-overlay toggle path so manual hides stay hidden and the plugin uses the explicit visible-overlay toggle command.
-- Subtitle Sidebar: Restored macOS mpv passthrough while the overlay subtitle sidebar is open so clicks outside the sidebar can refocus mpv and keep native keybindings working.
-
-### Internal
-- Release: Added a maintained source coverage lane that shards Bun coverage one test file at a time and merges LCOV output into `coverage/test-src/lcov.info`.
-- Release: CI and release quality-gate now upload the merged source-lane LCOV artifact for inspection.
-- Runtime: Extracted remaining inline runtime logic from `src/main.ts` into dedicated runtime modules and composer helpers.
-- Runtime: Added focused regression tests for the extracted runtime/composer boundaries.
-- Runtime: Updated task tracking notes to mark TASK-238.6 complete and confirm follow-on boot-phase split can be deferred.
-- Runtime: Split `src/main.ts` boot wiring into dedicated `src/main/boot/services.ts`, `src/main/boot/runtimes.ts`, and `src/main/boot/handlers.ts` modules.
-- Runtime: Added focused tests for the new boot-phase seams and kept the startup/typecheck/build verification lanes green.
-- Runtime: Updated internal architecture/task docs to record the boot-phase split and new ownership boundary.
-
-## v0.9.3 (2026-03-25)
-
-### Changed
-- Launcher: Moved YouTube primary subtitle language defaults to `youtube.primarySubLanguages`.
-- Launcher: Removed the placeholder YouTube subtitle retime step and now uses downloaded primary subtitle tracks directly, so there is no fake path rewrite before playback/sidebar loading.
-- YouTube: Removed the `src/core/services/youtube/retime` helper and its tests after retiring the internal retime strategy.
-- Docs: Clarified optional `alass` / `ffsubsync` subtitle-sync requirements and setup steps, including fallback behavior when sync tools are absent.
-- Launcher: Removed the old `youtubeSubgen.primarySubLanguages` config path from the generated config and docs.
-
-## v0.9.2 (2026-03-25)
-
-### Fixed
-- Overlay: Fixed overlay pointer tracking so Windows click-through toggles immediately when the cursor enters or leaves subtitle regions, without waiting for a later hover resync.
-- Overlay: Fixed Windows overlay window tracking on scaled displays by converting native tracked window bounds to Electron DIP coordinates before applying overlay bounds.
-- Launcher: Fixed Windows direct `--youtube-play` startup so MPV boots reliably, stays paused until the app-owned subtitle flow is ready, and reuses an already-running SubMiner instance when available.
-- Launcher: Fixed standalone Windows `--youtube-play` sessions so closing MPV fully exits SubMiner instead of leaving hidden overlay windows or a background process behind.
-- Overlay: Fixed `subminer <youtube-url>` on Linux so the YouTube playback flow waits for Yomitan to load before creating the overlay window, avoiding the broken lookup popup state that previously required a manual overlay refresh.
-
-## v0.9.1 (2026-03-24)
-
-### Changed
-- Release: Reduced packaged release size by excluding duplicate `extraResources` payload and pruning docs, tests, sourcemaps, and other source-only files from Electron bundles.
-
-### Fixed
-- Overlay: Restored controller navigation and lookup/mining controls while the subtitle sidebar is open, while keeping true modal dialogs blocking controller actions.
-- Tokenizer: Fixed subtitle annotation clearing so explanatory contrast endings like `んですけど` are excluded consistently across the shared tokenizer filter and annotation stage.
-
-## v0.9.0 (2026-03-23)
-
-### Added
-- Docs: Added a new WebSocket / Texthooker API and integration guide covering WebSocket payloads, custom client patterns, mpv plugin automation, and webhook-style relay examples. Linked from configuration and mining workflow docs for easier discovery.
-
-### Changed
-- Launcher: Added an app-owned YouTube subtitle flow that pauses mpv, uses absPlayer-style YouTube timedtext parsing/conversion to download subtitle tracks, and injects them as external files before playback resumes.
-- Launcher: Changed YouTube subtitle startup to auto-load the best-available primary and secondary subtitle tracks at launch instead of forcing the picker modal first. Secondary subtitle failures no longer block playback resume.
-- Launcher: Added `Ctrl+Alt+C` as the default keybinding to manually open the YouTube subtitle picker during active YouTube playback.
-- Launcher: Added yt-dlp metadata probing so YouTube playback and immersion tracking record canonical video title and channel metadata.
-- Launcher: Stopped forcing `--ytdl-raw-options=` before user-provided mpv options so existing YouTube cookie integrations in user `--args` are no longer clobbered.
-- Launcher: Disabled mpv native YouTube subtitle auto-loading for the app-owned flow so injected external subtitle files remain authoritative.
-- Launcher: Added OSD status messages for YouTube playback startup, subtitle acquisition, and subtitle loading so the flow stays visible before and during the picker.
-- Subtitle Sidebar: Added startup-auto-open controls and resume positioning improvements so the sidebar jumps directly to the first resolved active cue.
-- Subtitle Sidebar: Improved subtitle prefetch and embedded overlay passthrough sync so sidebar and overlay subtitle states stay consistent across media transitions.
-- Subtitle Sidebar: Updated scroll handling, embedded layout styling, and active-cue visual behavior.
-- Stats: Stats Library tab now displays YouTube video title, channel name, and channel thumbnail for YouTube media entries, with retry logic to fill in metadata that arrives after initial load.
-
-### Fixed
-- Launcher: Fixed Anki media mining for mpv YouTube streams by unwrapping the stream URL so audio and screenshot capture work correctly for YouTube playback sessions.
-- Immersion: Fixed YouTube media path handling in the immersion runtime and tracking so YouTube sessions record correct media references, AniList guessing skips YouTube URLs, and post-watch state transitions do not fire for YouTube media.
-- Launcher: Fixed startup-launched YouTube playback so primary subtitle overlay updates continue after auto-load completes.
-- Launcher: Fixed auto-loaded YouTube primary subtitles so parsed cues appear in the subtitle sidebar without needing a manual picker retry.
-- Launcher: Fixed the YouTube picker to guard against duplicate subtitle submissions and tightened YouTube URL detection so follow-up runtime flows only treat real YouTube hosts as YouTube playback.
-- Launcher: Fixed primary subtitle failure notifications being shown while app-owned YouTube subtitle probing and downloads are still in flight.
-- Launcher: Preserved existing authoritative YouTube subtitle tracks when available; downloaded tracks are used only to fill missing sides, and native mpv secondary subtitle rendering is hidden so the overlay remains the sole secondary display.
-
-## v0.8.0 (2026-03-22)
-
-### Added
-- Overlay: Added the subtitle sidebar feature with a new `subtitleSidebar` configuration surface and rendered sidebar modal with cue list rendering, click-to-seek, active-cue highlighting, and embedded layout support.
-- IPC: Added sidebar snapshot plumbing between renderer and main process for overlay/sidebar synchronization.
-
-### Changed
-- Config: Added hot-reloadable sidebar options for enablement, layout, visibility, typography, opacity, sizing, and interaction behavior (`autoOpen`, `pauseOnHover`, `autoScroll`, toggle key).
-- Docs: Added full `subtitleSidebar` documentation coverage, including sample config, option table, and toggle shortcut notes.
-- Runtime: Improved subtitle prefetch/rendering flow so sidebar and overlay subtitle states stay in sync across media transitions.
-
-### Fixed
-- Overlay: Kept sidebar cue tracking stable across playback transitions and timing edge cases.
-- Overlay: Improved sidebar resume/start behavior to jump directly to the first resolved active cue.
-- Overlay: Stopped stale subtitle refreshes from regressing active-cue and text state.
-
-## v0.7.0 (2026-03-19)
-
-### Added
-- Immersion: Added Mine Word, Mine Sentence, and Mine Audio buttons to word detail example lines in the stats dashboard.
-- Immersion: Mine Word creates a full Yomitan card (definition, reading, pitch accent) via the hidden search page bridge, then enriches with sentence audio, screenshot, and metadata extracted from the source video.
-- Immersion: Mine Sentence and Mine Audio create cards directly with appropriate Lapis/Kiku flags, sentence highlighting, and media from the source file.
-- Immersion: Media generation (audio + image/AVIF) runs in parallel and respects all AnkiConnect config options.
-- Immersion: Added word exclusion list to the Vocabulary tab with localStorage persistence and a management modal.
-- Immersion: Fixed truncated readings in the frequency rank table (e.g. お前 now shows おまえ instead of まえ).
-- Immersion: Clicking a bar in the Top Repeated Words chart now opens the word detail panel.
-- Immersion: Secondary subtitle text is now stored alongside primary subtitle lines for use as translation when mining cards from the stats page.
-- Stats: Added `subminer stats -b` to start or reuse a dedicated background stats server without blocking normal SubMiner instances.
-- Stats: Added `subminer stats -s` to stop the dedicated background stats server without closing browser tabs.
-- Stats: Stats server startup now reuses a running background stats daemon instead of trying to bind a second local server in another SubMiner instance.
-- Launcher: Added launcher passthrough for `-a/--args` so mpv receives raw extra launch flags (`--fs`, `--ytdl-format`, custom audio/video settings, etc.) from the `subminer` command.
-- Launcher: Added `subminer stats` to launch the local stats dashboard, force-start the stats server on demand, and open the dashboard in your browser.
-- Launcher: Added `subminer stats cleanup` to backfill vocabulary metadata and prune stale or excluded immersion rows on demand.
-- Launcher: Added `stats.autoOpenBrowser` so browser launch after `subminer stats` can be enabled or disabled explicitly.
-- Immersion: Added a local stats dashboard for immersion tracking with Overview, Anime, Trends, Vocabulary, and Sessions views.
-- Immersion: Added anime progress, episode completion, Anki card links, and occurrence drill-down across the stats dashboard.
-- Immersion: Added richer session timelines with new-word activity, cumulative totals, and pause/seek/card event markers.
-- Immersion: Added completed-episodes and completed-anime totals to the Overview tracking snapshot.
-
-### Changed
-- Anki: Changed known-word cache settings to live under `ankiConnect.knownWords` instead of mixing them into `ankiConnect.nPlusOne`.
-- Anki: Kept legacy `ankiConnect.nPlusOne` known-word keys and older `ankiConnect.behavior.nPlusOne*` keys as deprecated compatibility fallbacks.
-- Stats: Added session deletion to the Sessions tab with the same confirmation prompt used by anime episode/session deletes, and removed all associated session rows from the stats database.
-- Immersion: Kept immersion tracking history by default while preserving daily/monthly rollup maintenance.
-- Immersion: Added exact lifetime summary reads for overview/anime/media stats so dashboard totals no longer depend on rescanning raw telemetry.
-- Immersion: Reduced tracker storage overhead by removing duplicated subtitle text from subtitle-line event payloads.
-- Immersion: Deduplicated episode cover-art blobs through a shared blob store and updated cover-art reads/writes to resolve shared images correctly.
-- Immersion: Added indexes for large-history session, telemetry, vocabulary, kanji, and cover-art queries to keep dashboard reads fast as the SQLite database grows.
-- Immersion: Renamed the stats dashboard's Anime tab to Library so the media browser label matches non-anime sources like YouTube and other yt-dlp-backed content.
-- Anilist: Standardized episode completion threshold by introducing `DEFAULT_MIN_WATCH_RATIO` and using it for both local watched state transitions and AniList post-watch progress updates.
-- Anilist: Episode auto-marking now uses the same threshold as AniList (`85%`), removing divergent completion behavior.
-- Overlay: Excluded interjections and sound-effect tokens from subtitle annotation styling so they no longer inherit misleading lexical highlight treatment while still remaining visible and hoverable as plain subtitle tokens.
-- Overlay: Expanded subtitle annotation noise filtering to also strip annotation metadata from standalone grammar-only helper tokens such as particles, auxiliaries, adnominals, common explanatory endings like `んです` / `のだ`, and merged trailing quote-particle forms like `...って` while keeping them tokenized for hover lookup.
-
-### Fixed
-- Launcher: Fixed mpv Lua plugin binary auto-detection on Linux to also search `/usr/bin/subminer` and `/usr/local/bin/subminer` (lowercase), matching the conventional Unix wrapper name used by packaged installs such as the AUR package.
-- Stats: Fixed the in-app stats overlay so it connects to the configured `stats.serverPort` instead of falling back to the default port.
-- Overlay: Fixed subtitle frequency tagging for merged lookup-backed tokens like `陰に` by falling back to exact surface-form Yomitan frequencies when the normalized headword lookup misses.
-- Overlay: Fixed MeCab merged-token position mapping across line breaks so merged content-plus-particle tokens like `陰に` keep their matched Yomitan frequency instead of inheriting shifted POS tags.
-- Overlay: Fixed grouped frequency parsing in both Yomitan and fallback frequency-dictionary lookups so display values like `118,121` use the leading rank instead of collapsing the rank and occurrence count into `118121`.
-- Overlay: Fixed frequency-rank ingestion to ignore Yomitan dictionaries explicitly marked `occurrence-based`, so raw occurrence counts are no longer treated as subtitle rank values.
-- Overlay: Fixed inflected headword frequency tagging to prefer ranks from the selected Yomitan `termsFind` popup entry itself, ordered by configured dictionary priority, so forms like `潜み` use primary-dictionary ranks like `4073` before falling back to lower-priority raw lemma metadata such as `CC100`.
-- Overlay: Fixed annotation-stage frequency filtering so exact kanji noun tokens like `者` keep their matched rank even when MeCab labels them `名詞/非自立`, instead of dropping the highlight after scan-time frequency lookup succeeds.
-- Anki: Fixed repeated character-dictionary startup work by scheduling auto-sync only from mpv media-path changes instead of also re-triggering it from connection and media-title events for the same title.
-- Overlay: Fixed macOS fullscreen overlay stability by keeping the passive visible overlay from stealing focus, re-raising the overlay window when reasserting its macOS topmost level, and tolerating one transient macOS tracker/helper miss before hiding the overlay.
-- Overlay: Kept subtitle tokenization warmup one-shot for the lifetime of the app so later fullscreen/media churn on macOS does not replay the startup warmup gate after the first file is ready.
-- Overlay: Added a bounded macOS tracker loss-grace window so fullscreen enter/leave transitions do not immediately hide and reload the overlay when the helper briefly loses the mpv window.
-- Overlay: Skipped subtitle/tokenization refresh invalidation on character-dictionary auto-sync completion when the dictionary was already current, preventing startup flash/reload loops on unchanged media.
-- Stats: Fixed session stats so known-word counts track real known-word occurrences without collapsing subtitle-line gaps.
-- Stats: Fixed session word totals in session-facing stats views to prefer token counts when available, preventing known words from exceeding total words in the session chart.
-- Stats: Fixed the stats Vocabulary tab blank-screen regression caused by a hook-order crash after vocabulary data finished loading.
-- Anki: Fixed card-mine OSD feedback so the final mine result stops the Anki spinner first, then shows a single-line `✓`/`x` status without being overwritten by a later spinner tick.
-- Stats: Removed the misleading `New words` series from expanded session charts; session detail now shows only the real total-word and known-word lines.
-- Stats: Restored the cross-anime word table behavior in stats vocabulary surfaces so shared vocabulary entries no longer disappear or merge incorrectly across related media.
-- Stats: `subminer stats -b` now runs as a standalone background stats daemon instead of reusing the main SubMiner app process, so the overlay app can still be launched separately for normal video watching.
-- Stats: Dashboard word mining still works against the background daemon by using a short-lived hidden helper for the Yomitan add-note flow.
-- Stats: Load full session timelines by default in stats session detail views so long sessions preserve complete telemetry history instead of being truncated by a fixed sample limit.
-- Stats: Replaced heuristic stats word counts with Yomitan token counts, so session, media, anime, and trend subtitle totals now come directly from parsed subtitle tokens.
-- Stats: Updated stats UI labels and lookup-rate copy to refer to tokens instead of words where those counts are shown.
-- Overlay: Reduced repeated `Overlay loading...` popups on macOS when fullscreen tracker flaps briefly hide and recover the visible overlay.
-- Stats: Scaled expanded session-detail known-word charts to the session's actual percentage range so small changes no longer render as a nearly flat line.
-- Jlpt: Reduced JLPT dictionary startup log noise by summarizing duplicate surface-form collisions instead of logging one line per duplicate entry.
-
 ## v0.6.5 (2026-03-15)
 
 ### Internal

CLAUDE.md

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

README.md

@@ -1,171 +1,44 @@
 <div align="center">
+  <img src="assets/SubMiner.png" width="169" alt="SubMiner logo">
+  <h1>SubMiner</h1>
+  <strong>Look up words, mine to Anki, and enrich cards with context — without leaving mpv.</strong>
+  <br /><br />
 
-<img src="assets/SubMiner.png" width="160" alt="SubMiner logo">
-
-# SubMiner
-
-## Turn mpv into a sentence-mining workstation.
-
-Look up words with Yomitan, export to Anki in one key, track your immersion — all without leaving mpv.
-
-[![License: GPL v3](https://img.shields.io/badge/license-GPLv3-1a1a2e?style=flat-square)](https://www.gnu.org/licenses/gpl-3.0)
-[![Platform](https://img.shields.io/badge/platform-Linux%20·%20macOS%20·%20Windows-1a1a2e?style=flat-square)](https://github.com/ksyasuda/SubMiner)
-[![Docs](https://img.shields.io/badge/docs-docs.subminer.moe-e6a817?style=flat-square)](https://docs.subminer.moe)
-[![AUR](https://img.shields.io/aur/version/subminer-bin?style=flat-square&color=1a1a2e)](https://aur.archlinux.org/packages/subminer-bin)
-
-[![SubMiner demo](./assets/minecard.webp)](./assets/minecard.mp4)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Linux](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-informational)]()
+[![Docs](https://img.shields.io/badge/docs-docs.subminer.moe-blueviolet)](https://docs.subminer.moe)
 
 </div>
 
-## How It Works
-
-SubMiner runs as an invisible Electron overlay on top of mpv. Subtitles render as an interactive layer. Move your cursor over any word and trigger a [Yomitan](https://github.com/yomidevs/yomitan) lookup. Press one key to snapshot the sentence, audio, and screenshot into Anki via AnkiConnect.
-
-## Features
-
-### Dictionary Lookups
-
-Yomitan runs inside the overlay. Trigger a lookup on any word for full dictionary popups — definitions, pitch accent, frequency data — without ever leaving mpv.
+<br />
 
 <div align="center">
-  <img src="docs-site/public/screenshots/yomitan-lookup.png" width="800" alt="Yomitan dictionary popup over annotated subtitles in mpv">
+
+[![SubMiner demo (Animated preview)](./assets/minecard.webp)](./assets/minecard.mp4)
+
 </div>
 
-<br>
+<br />
 
-### Instant Anki Mining
+## What it does
 
-Create an Anki card with the sentence, audio clip, screenshot, and machine translation from the exact playback moment with one key press, click, or controller input.
+SubMiner is an Electron overlay that sits on top of mpv. It turns your video player into a full sentence-mining workstation:
 
-<div align="center">
-  <img src="docs-site/public/screenshots/one-key-mining.png" width="800" alt="Anki card created from SubMiner with sentence, audio, and screenshot">
-</div>
+- **Look up words as you watch** — Yomitan dictionary popups on hover or keyboard-driven token-by-token navigation
+- **One-key Anki mining** — Creates cards with sentence, audio, screenshot, and translation; optional local AnkiConnect proxy auto-enriches Yomitan cards instantly
+- **Reading annotations** — N+1 targeting, frequency-dictionary highlighting, JLPT underlining, and character name dictionary for anime/manga proper nouns
+- **Immersion stats** — Optional local dashboard and overlay for watch time, anime progress, session drill-down, vocabulary growth, mining throughput, and card mining directly from example sentences; exact lifetime totals are kept locally in SQLite by default
+- **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
 
-<br>
-
-### Reading Annotations
-
-Real-time subtitle annotations with frequency highlighting, JLPT tags, N+1 targeting, and a character name dictionary. Known words fade back; new words stand out. Grammar-only tokens render as plain text so you focus on what matters.
-
-<div align="center">
-  <img src="docs-site/public/screenshots/annotations.png" width="800" alt="Annotated subtitles with frequency coloring, JLPT underlines, and N+1 targets">
-</div>
-
-<br>
-
-### Immersion Dashboard
-
-Local stats dashboard — watch time, anime library, vocabulary growth, mining throughput, session history, and trends. All stored locally, no third-party tracking.
-
-<div align="center">
-  <img src="docs-site/public/screenshots/stats-overview.png" width="800" alt="Stats dashboard showing watch time, cards mined, streaks, and tracking data">
-</div>
-
-<br>
-
-### Integrations
-
-<table>
-  <tr>
-    <td><b>YouTube</b></td>
-    <td>Auto-loaded yt-dlp subtitle tracks at startup with a manual overlay picker on demand (<code>Ctrl+Alt+C</code>)</td>
-  </tr>
-  <tr>
-    <td><b>AniList</b></td>
-    <td>Automatic episode tracking and progress sync</td>
-  </tr>
-  <tr>
-    <td><b>Jellyfin</b></td>
-    <td>Browse and launch media from your Jellyfin server</td>
-  </tr>
-  <tr>
-    <td><b>Jimaku</b></td>
-    <td>Search and download Japanese subtitles</td>
-  </tr>
-  <tr>
-    <td><b>alass / ffsubsync</b></td>
-    <td>Automatic subtitle retiming — requires <code>alass</code> or <code>ffsubsync</code> on your <code>PATH</code> (optional; subtitle syncing is disabled without them)</td>
-  </tr>
-  <tr>
-    <td><b>WebSocket</b></td>
-    <td>Annotated subtitle feed for external clients (texthooker pages, custom tools)</td>
-  </tr>
-</table>
-
-<div align="center">
-  <img src="docs-site/public/screenshots/texthooker.png" width="800" alt="Texthooker page receiving annotated subtitle lines via WebSocket">
-</div>
-
-<br>
-
----
-
-## Requirements
-
-|                | Required                                | Optional                               |
-| -------------- | --------------------------------------- | -------------------------------------- |
-| **Player**     | [`mpv`](https://mpv.io) with IPC socket | —                                      |
-| **Processing** | `ffmpeg`, `mecab` + `mecab-ipadic`      | `guessit` (AniSkip), `alass` / `ffsubsync` (subtitle sync) |
-| **Media**      | —                                       | `yt-dlp`, `chafa`, `ffmpegthumbnailer` |
-| **Selection**  | —                                       | `fzf` / `rofi`                         |
-
-> [!NOTE]
-> [`bun`](https://bun.sh) is required if building from source or using the CLI wrapper: `subminer`. Pre-built releases (AppImage, DMG, installer) do not require it.
-
-**Platform-specific:**
-
-| Linux                               | macOS                    | Windows       |
-| ----------------------------------- | ------------------------ | ------------- |
-| `hyprctl` or `xdotool` + `xwininfo` | Accessibility permission | No extra deps |
-
-<details>
-<summary><b>Arch Linux</b></summary>
-
-```bash
-paru -S --needed mpv ffmpeg mecab-git mecab-ipadic
-# Optional
-paru -S --needed yt-dlp fzf rofi chafa ffmpegthumbnailer xdotool xorg-xwininfo
-# Optional: subtitle sync (install at least one for subtitle syncing to work)
-paru -S --needed alass python-ffsubsync
-# X11 / XWAYLAND
-paru -S --needed xdotool xorg-xwininfo
-```
-
-</details>
-
-<details>
-<summary><b>macOS</b></summary>
-
-```bash
-brew install mpv ffmpeg mecab mecab-ipadic
-# Optional
-brew install yt-dlp fzf rofi chafa ffmpegthumbnailer
-# Optional: subtitle sync (install at least one for subtitle syncing to work)
-brew install alass
-pip install ffsubsync
-```
-
-Grant Accessibility permission to SubMiner in **System Settings > Privacy & Security > Accessibility**.
-
-</details>
-
-<details>
-<summary><b>Windows</b></summary>
-
-Install [`mpv`](https://mpv.io/installation/) and [`ffmpeg`](https://ffmpeg.org/download.html) and ensure both are on your `PATH`.
-
-For MeCab, install [MeCab for Windows](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary.
-
-</details>
-
----
-
-## Quick Start
+## Quick start
 
 ### 1. Install
 
-<details>
-<summary><b>Arch Linux (AUR)</b></summary>
+**Arch Linux (AUR):**
+
+Install [`subminer-bin`](https://aur.archlinux.org/packages/subminer-bin) from the AUR. It installs the packaged AppImage plus the `subminer` wrapper:
 
 ```bash
 paru -S subminer-bin
@@ -174,85 +47,84 @@ paru -S subminer-bin
 Or manually:
 
 ```bash
-git clone https://aur.archlinux.org/subminer-bin.git && cd subminer-bin && makepkg -si
+git clone https://aur.archlinux.org/subminer-bin.git
+cd subminer-bin
+makepkg -si
 ```
 
-</details>
-
-<details>
-<summary><b>Linux (AppImage)</b></summary>
+**Linux (AppImage):**
 
 ```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
+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`.
 
-</details>
+**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>
-<summary><b>macOS</b></summary>
+**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`.
 
-Download the latest DMG or ZIP from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest) and drag `SubMiner.app` into `/Applications`.
+**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).
 
-</details>
-
-<details>
-<summary><b>Windows</b></summary>
-
-Download the latest installer or portable `.zip` from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). Make sure `mpv` is on your `PATH`.
-
-</details>
-
-<details>
-<summary><b>From source</b></summary>
-
-See the [build-from-source guide](https://docs.subminer.moe/installation#from-source).
-
-</details>
-
-### 2. First Launch
-
-Run the app. On first launch SubMiner starts in the system tray, creates a default config, and opens a setup popup to install the mpv plugin and configure Yomitan dictionaries.
-
-### 3. Mine
+### 2. Launch the app once
 
 ```bash
-subminer video.mkv          # play video with overlay
-subminer --start video.mkv  # explicit overlay start
-subminer stats              # open immersion dashboard
-subminer stats -b           # stats daemon in background
-subminer stats -s           # stop background stats daemon
+# Linux
+SubMiner.AppImage
 ```
 
----
+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
+subminer stats # open the local stats dashboard in your browser
+```
+
+## Requirements
+
+| Required                                   | Optional                                           |
+| ------------------------------------------ | -------------------------------------------------- |
+| `bun` (source builds, Linux `subminer`)    |                                                    |
+| `mpv` with IPC socket                      | `yt-dlp`                                           |
+| `ffmpeg`                                   | `guessit` (better AniSkip title/episode detection) |
+| `mecab` + `mecab-ipadic`                   | `fzf` / `rofi`                                     |
+| Linux: `hyprctl` or `xdotool` + `xwininfo` | `chafa`, `ffmpegthumbnailer`                       |
+| macOS: Accessibility permission            |                                                    |
+
+Windows builds use native window tracking and do not require the Linux compositor helper tools.
 
 ## Documentation
 
-Full guides on configuration, Anki setup, Jellyfin, immersion tracking, and more: **[docs.subminer.moe](https://docs.subminer.moe)**
-
----
+For full guides on configuration, Anki, Jellyfin, immersion tracking/stats, and more, see [docs.subminer.moe](https://docs.subminer.moe). The VitePress source for that site lives in [`docs-site/`](./docs-site/).
 
 ## Acknowledgments
 
-SubMiner builds on the work of these open-source projects:
-
-| Project                                                                                     | Role                                                                    |
-| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script)                          | Inspiration for the mining workflow                                     |
-| [asbplayer](https://github.com/killergerbah/asbplayer)                                      | Inspiration for subtitle sidebar and logic for YouTube subtitle parsing |
-| [Bee's Character Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary) | Character name recognition in subtitles                                 |
-| [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner)                          | Inspiration for Electron overlay with Yomitan integration               |
-| [jellyfin-mpv-shim](https://github.com/jellyfin/jellyfin-mpv-shim)                          | Jellyfin integration                                                    |
-| [Jimaku.cc](https://jimaku.cc)                                                              | Japanese subtitle search and downloads                                  |
-| [Renji's Texthooker Page](https://github.com/Renji-XD/texthooker-ui)                        | Base for the WebSocket texthooker integration                           |
-| [Yomitan](https://github.com/yomidevs/yomitan)                                              | Dictionary engine powering all lookups and the morphological parser     |
-| [yomitan-jlpt-vocab](https://github.com/stephenmk/yomitan-jlpt-vocab)                       | JLPT level tags for vocabulary                                          |
+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).
 
 ## License
 

backlog/completed/task-189 - Replace-stats-word-counts-with-Yomitan-token-counts.md

@@ -1,56 +0,0 @@
----
-id: TASK-189
-title: Replace stats word counts with Yomitan token counts
-status: Done
-assignee:
-  - codex
-created_date: '2026-03-18 01:35'
-updated_date: '2026-03-18 05:28'
-labels:
-  - stats
-  - tokenizer
-  - bug
-milestone: m-1
-dependencies: []
-references:
-  - src/core/services/immersion-tracker-service.ts
-  - src/core/services/immersion-tracker/reducer.ts
-  - src/core/services/immersion-tracker/storage.ts
-  - src/core/services/immersion-tracker/query.ts
-  - src/core/services/immersion-tracker/lifetime.ts
-  - stats/src/components
-  - stats/src/lib/yomitan-lookup.ts
-priority: medium
-ordinal: 100500
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Replace heuristic immersion stats word counting with Yomitan token counts. Session/media/anime stats should use the exact merged Yomitan token stream as the denominator and display metric, with no whitespace/CJK-character fallback and no active `wordsSeen` concept in the runtime, storage, API, or stats UI.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 `recordSubtitleLine` derives session count deltas from Yomitan token arrays instead of `calculateTextMetrics`.
-- [x] #2 Active immersion tracking/storage/query code no longer depends on `wordsSeen` / `totalWordsSeen` fields for stats behavior.
-- [x] #3 Stats UI labels and lookup-rate copy refer to tokens instead of words where those counts are shown to users.
-- [x] #4 Regression tests cover token-count sourcing, zero-count behavior when tokenization payload is absent, and updated stats copy.
-- [x] #5 A changelog fragment documents the user-visible stats denominator change.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-1. Add failing tracker tests proving subtitle count metrics come from Yomitan token arrays and stay zero when tokenization is absent.
-2. Add failing stats UI tests for token-based copy and token-count display helpers.
-3. Remove `wordsSeen` from active tracker/session/query/type paths and use `tokensSeen` as the single stats count field.
-4. Update stats UI labels and lookup-rate copy from words to tokens.
-5. Run targeted verification, then add the changelog fragment and any needed docs update.
-<!-- SECTION:PLAN:END -->
-
-## Outcome
-
-<!-- SECTION:OUTCOME:BEGIN -->
-Completed. Stats subtitle counts now come directly from Yomitan merged-token counts, `wordsSeen` is removed from the active tracker/storage/query/UI path, token-facing copy is updated, and focused regression coverage plus `bun run typecheck` are green.
-<!-- SECTION:OUTCOME:END -->

backlog/completed/task-190 - Add-hover-popups-for-session-chart-events.md

@@ -1,54 +0,0 @@
----
-id: TASK-190
-title: Add hover popups for session chart events
-status: Done
-assignee:
-  - Codex
-created_date: '2026-03-17 22:20'
-updated_date: '2026-03-18 05:28'
-labels:
-  - stats
-  - ui
-  - bug
-milestone: m-1
-dependencies: []
-references:
-  - stats/src/components/sessions/SessionDetail.tsx
-  - stats/src/lib/session-events.ts
-  - stats/src/hooks/useSessions.ts
-  - stats/src/lib/api-client.ts
-  - docs/plans/2026-03-17-session-event-hover-popups-design.md
-priority: medium
-ordinal: 105500
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Add hover/focus popups to session chart event markers so pauses, seeks, lookups, and card-mine events explain themselves inline. Card-mine events should lazy-load available Anki note info and present it in a richer popup with browse affordances.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [x] #1 Hovering or focusing a session-chart marker opens an event-specific popup.
-- [x] #2 Pause, seek, and lookup popups show concise event copy derived from marker metadata.
-- [x] #3 Card-mine popups lazily fetch and cache Anki note info by note id.
-- [x] #4 Card-mine popups show a formatted fallback when note info is missing or still loading.
-- [x] #5 Regression tests cover event payload shaping and popup rendering behavior.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-1. Add failing tests for event metadata shaping and popup content selection.
-2. Extend session-event shaping to parse payload JSON into typed marker metadata.
-3. Add lazy note-info fetch/cache state for card-mine markers.
-4. Render interactive marker overlay + custom popup in the session detail chart.
-5. Run targeted stats/core verification and update this task with the result.
-<!-- SECTION:PLAN:END -->
-
-## Outcome
-
-<!-- SECTION:OUTCOME:BEGIN -->
-Completed. Session-chart event markers now open event-specific hover/focus popups, including lazy-loaded Anki note info for card-mine events with browse affordances. Verification passed via targeted stats tests, `bun run typecheck`, and the core verification lane in `.tmp/skill-verification/subminer-verify-20260317-222545-CQzyqK`.
-<!-- SECTION:OUTCOME:END -->

backlog/completed/task-193 - Fix-session-chart-event-popup-position-drift.md

@@ -1,62 +0,0 @@
----
-id: TASK-193
-title: Fix session chart event popup position drift
-status: Done
-assignee:
-  - Codex
-created_date: '2026-03-17 23:55'
-updated_date: '2026-03-17 23:59'
-labels:
-  - stats
-  - ui
-  - bug
-milestone: m-1
-dependencies: []
-references:
-  - stats/src/components/sessions/SessionDetail.tsx
-  - stats/src/components/sessions/SessionEventOverlay.tsx
-  - stats/src/lib/session-events.ts
-priority: medium
-ordinal: 105600
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Fix the session timeline event popup trigger positions so hover markers stay aligned with the underlying chart event lines across the full visible time range.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Event popup triggers stay horizontally aligned with chart event lines from session start through session end.
-- [x] #2 Alignment logic uses the rendered chart plot area rather than guessed container percentages.
-- [x] #3 Regression coverage locks the marker-position projection math.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-1. Add a failing regression test for marker-position projection with chart offsets.
-2. Capture the rendered plot box from Recharts and pass it into the overlay.
-3. Position overlay markers in plot-area pixels, rerun targeted stats verification, then record the result.
-<!-- SECTION:PLAN:END -->
-
-## Outcome
-
-<!-- SECTION:OUTCOME:BEGIN -->
-
-Completed. Session event hover markers now read the actual Recharts plot-area offset and width, then project marker X positions into plot-area pixels instead of full-container percentages. That keeps popup triggers aligned with the underlying reference lines across long session timelines.
-
-Verification:
-
-- `bun test stats/src/lib/session-events.test.ts stats/src/lib/session-detail.test.tsx stats/src/components/sessions/SessionEventPopover.test.tsx`
-- `cd stats && bun run build`
-- `bun x prettier --check 'stats/src/components/sessions/SessionDetail.tsx' 'stats/src/components/sessions/SessionEventOverlay.tsx' 'stats/src/lib/session-events.ts' 'stats/src/lib/session-events.test.ts' 'backlog/tasks/task-193 - Fix-session-chart-event-popup-position-drift.md'`
-- `bun run typecheck:stats` still fails on pre-existing unrelated errors in `src/components/anime/AnilistSelector.tsx`, `src/components/library/LibraryTab.tsx`, `src/lib/reading-utils.test.ts`, `src/lib/reading-utils.ts`, `src/lib/vocabulary-tab.test.ts`, and `src/lib/yomitan-lookup.test.tsx`
-
-<!-- SECTION:OUTCOME:END -->

backlog/completed/task-195 - Keep-final-card-mine-OSD-result-from-being-overwritten-by-progress-spinner.md

@@ -1,64 +0,0 @@
----
-id: TASK-195
-title: Keep final card-mine OSD result from being overwritten by progress spinner
-status: Done
-assignee:
-  - Codex
-created_date: '2026-03-18 19:40'
-updated_date: '2026-03-18 19:49'
-labels:
-  - anki
-  - ui
-  - bug
-milestone: m-1
-dependencies: []
-references:
-  - src/anki-integration/ui-feedback.ts
-  - src/anki-integration.ts
-  - src/anki-integration/card-creation.ts
-priority: medium
-ordinal: 105610
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-When a card mine finishes, the mpv OSD currently tries to show the final status text but the in-flight Anki progress spinner can immediately overwrite it on the next tick. Stop the spinner first, then show a single-line final result with a success/failure marker and the mined-word notification.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Successful mine/update OSD results render after the spinner is stopped and do not get overwritten by a later spinner tick.
-- [x] #2 Failure results that replace the spinner show an `x` marker and stay visible on the same OSD line.
-- [x] #3 Regression coverage locks the spinner teardown/result-notification ordering.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-1. Add a focused failing regression test around the Anki UI-feedback spinner/result helper.
-2. Add a helper that stops progress before emitting the final OSD result line with `✓`/`x`.
-3. Route mine/update result notifications through that helper, then run targeted verification.
-<!-- SECTION:PLAN:END -->
-
-## Outcome
-
-<!-- SECTION:OUTCOME:BEGIN -->
-
-Added a dedicated Anki UI-feedback result helper that force-clears the in-flight spinner state before emitting the final OSD result line. Successful card-update notifications now render as `✓ Updated card: ...`, and sentence-card creation failures now render as `x Sentence card failed: ...` without a later spinner tick reclaiming the line.
-
-Verification:
-
-- `bun test src/anki-integration/ui-feedback.test.ts`
-- `bun test src/anki-integration/ui-feedback.test.ts src/anki-integration/note-update-workflow.test.ts src/anki-integration.test.ts src/core/services/mining.test.ts src/main/runtime/mining-actions.test.ts`
-- `bun x prettier --check src/anki-integration/ui-feedback.ts src/anki-integration/ui-feedback.test.ts src/anki-integration.ts src/anki-integration/card-creation.ts "backlog/tasks/task-195 - Keep-final-card-mine-OSD-result-from-being-overwritten-by-progress-spinner.md" changes/2026-03-18-mine-osd-spinner-result.md`
-- `bun run changelog:lint`
-- `bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane core src/anki-integration/ui-feedback.ts src/anki-integration/ui-feedback.test.ts src/anki-integration.ts src/anki-integration/card-creation.ts changes/2026-03-18-mine-osd-spinner-result.md`
-- Verifier artifacts: `.tmp/skill-verification/subminer-verify-20260318-194614-uZMrAx/`
-
-<!-- SECTION:OUTCOME:END -->

backlog/completed/task-243 - Assess-and-address-PR-36-latest-CodeRabbit-review-round.md

@@ -1,35 +0,0 @@
----
-id: TASK-243
-title: 'Assess and address PR #36 latest CodeRabbit review round'
-status: Done
-assignee: []
-created_date: '2026-03-29 07:39'
-updated_date: '2026-03-29 07:41'
-labels:
-  - code-review
-  - pr-36
-dependencies: []
-references:
-  - 'https://github.com/ksyasuda/SubMiner/pull/36'
-priority: high
-ordinal: 3600
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Inspect the latest CodeRabbit review round on PR #36, verify each actionable comment against the current branch, implement the confirmed fixes, and verify the touched paths.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [ ] #1 Confirmed review comments are implemented or explicitly deferred with rationale.
-- [ ] #2 Touched paths are verified with the smallest sufficient test/build lane.
-- [ ] #3 Current PR feedback is reduced to resolved or intentionally deferred suggestions.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Addressed the confirmed latest CodeRabbit review items on PR #36. `scripts/run-coverage-lane.ts` now uses the Bun-style `import.meta.main` entrypoint check with a local ts-ignore to preserve the repo's CommonJS typecheck settings. `src/core/services/immersion-tracker/maintenance.ts` no longer shadows the imported `nowMs` helper in retention functions. `src/main.ts` now centralizes the startup-mode predicates behind a shared helper and releases `resolvedSource.cleanup` on the cached-subtitle fast path so materialized sources do not leak.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-244 - Assess-and-address-PR-36-latest-CodeRabbit-review-round-2.md

@@ -1,35 +0,0 @@
----
-id: TASK-244
-title: 'Assess and address PR #36 latest CodeRabbit review round 2'
-status: Done
-assignee: []
-created_date: '2026-03-29 08:09'
-updated_date: '2026-03-29 08:10'
-labels:
-  - code-review
-  - pr-36
-dependencies: []
-references:
-  - 'https://github.com/ksyasuda/SubMiner/pull/36'
-priority: high
-ordinal: 3610
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-Inspect the newest CodeRabbit review round on PR #36, verify the actionable comment against the current branch, implement the confirmed fix, and verify the touched path.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-<!-- AC:BEGIN -->
-- [ ] #1 The actionable review comment is implemented or explicitly deferred with rationale.
-- [ ] #2 Touched path is verified with the smallest sufficient test lane.
-- [ ] #3 Current PR feedback is reduced to resolved or intentionally deferred suggestions.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-Addressed the actionable latest CodeRabbit comment on PR #36. `src/core/services/immersion-tracker/maintenance.ts` now skips retention deletions when a window is disabled with `Infinity`, so `toDbMs(...)` is only called for finite retention values. Added a regression test in `maintenance.test.ts` that verifies disabled retention windows preserve session events, telemetry, and sessions while returning zero deletions.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/config.yml

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

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

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

backlog/milestones/m-2 - mining-workflow-upgrades.md

@@ -1,8 +0,0 @@
----
-id: m-2
-title: 'Mining Workflow Upgrades'
----
-
-## Description
-
-Future user-facing workflow improvements that directly improve discoverability, previewability, and mining control without depending on speculative platform integrations like OCR, marketplace infrastructure, or cloud sync.

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

@@ -4,7 +4,6 @@ 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
@@ -20,17 +19,20 @@ 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-125 - Add-native-AI-API-key-secret-storage.md

@@ -4,7 +4,6 @@ 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
@@ -18,17 +17,20 @@ 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-131 - Make-default-overlay-fullscreen-and-AniSkip-end-jump-keybindings-easier-to-reach.md

@@ -7,14 +7,14 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-09 00:00'
-updated_date: '2026-03-18 05:28'
+updated_date: '2026-03-16 05:13'
 labels:
   - enhancement
   - overlay
   - mpv
   - aniskip
 dependencies: []
-ordinal: 43500
+ordinal: 42500
 ---
 
 ## Description

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-18 05:28'
+updated_date: '2026-03-16 05:13'
 labels:
   - bug
   - macos
@@ -19,7 +19,7 @@ references:
   - >-
     /Users/sudacode/projects/japanese/SubMiner/scripts/get-mpv-window-macos.swift
 priority: high
-ordinal: 53500
+ordinal: 52500
 ---
 
 ## Description

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: To Do
+status: In Progress
 assignee:
   - OpenCode
 created_date: '2026-03-08 21:06'
-updated_date: '2026-03-18 05:27'
+updated_date: '2026-03-10 06:18'
 labels:
   - dictionary
   - anilist
@@ -24,7 +24,6 @@ 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-18 05:28'
+updated_date: '2026-03-16 05:13'
 labels:
   - ci
   - release
@@ -18,7 +18,7 @@ references:
   - src/release-workflow.test.ts
   - 'https://github.com/ksyasuda/SubMiner/actions/runs/22836585479'
 priority: high
-ordinal: 52500
+ordinal: 51500
 ---
 
 ## Description

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-18 05:28'
+updated_date: '2026-03-16 05:13'
 labels:
   - release
   - patch
@@ -16,7 +16,7 @@ references:
   - CHANGELOG.md
   - release/release-notes.md
 priority: high
-ordinal: 51500
+ordinal: 50500
 ---
 
 ## Description

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-18 05:28'
+updated_date: '2026-03-16 05:13'
 labels:
   - ci
   - release
@@ -18,7 +18,7 @@ references:
   - build/signpath-windows-artifact-config.xml
   - src/release-workflow.test.ts
 priority: high
-ordinal: 49500
+ordinal: 48500
 ---
 
 ## Description

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-18 05:28'
+updated_date: '2026-03-16 05:13'
 labels:
   - release
   - patch
@@ -16,7 +16,7 @@ references:
   - CHANGELOG.md
   - release/release-notes.md
 priority: high
-ordinal: 50500
+ordinal: 49500
 ---
 
 ## Description

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-18 05:28'
+updated_date: '2026-03-16 05:13'
 labels:
   - release
   - windows
@@ -15,7 +15,7 @@ references:
   - package.json
   - src/release-workflow.test.ts
 priority: high
-ordinal: 45500
+ordinal: 44500
 ---
 
 ## Description

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-18 05:28'
+updated_date: '2026-03-16 05:13'
 labels:
   - release
   - patch
@@ -16,7 +16,7 @@ references:
   - CHANGELOG.md
   - release/release-notes.md
 priority: high
-ordinal: 46500
+ordinal: 45500
 ---
 
 ## Description

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-18 05:28'
+updated_date: '2026-03-16 05:13'
 labels:
   - dictionary
   - anilist
@@ -17,7 +17,7 @@ references:
   - >-
     /home/sudacode/projects/japanese/SubMiner/src/core/services/anilist/anilist-updater.test.ts
 priority: high
-ordinal: 44500
+ordinal: 43500
 ---
 
 ## Description

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

@@ -4,7 +4,7 @@ title: Refresh current subtitle after character dictionary sync completes
 status: Done
 assignee: []
 created_date: '2026-03-09 00:00'
-updated_date: '2026-03-18 05:28'
+updated_date: '2026-03-16 05:13'
 labels:
   - dictionary
   - overlay
@@ -15,7 +15,7 @@ references:
     /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync.ts
   - /home/sudacode/projects/japanese/SubMiner/src/main.ts
 priority: high
-ordinal: 42500
+ordinal: 41500
 ---
 
 ## Description

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

@@ -4,7 +4,7 @@ title: Show character dictionary auto-sync progress on OSD
 status: Done
 assignee: []
 created_date: '2026-03-09 01:10'
-updated_date: '2026-03-18 05:28'
+updated_date: '2026-03-16 05:13'
 labels:
   - dictionary
   - overlay
@@ -17,7 +17,7 @@ references:
     /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
+ordinal: 40500
 ---
 
 ## Description

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

@@ -2,10 +2,9 @@
 id: TASK-143
 title: Keep character dictionary auto-sync non-blocking during startup
 status: Done
-assignee:
-  - codex
+assignee: []
 created_date: '2026-03-09 01:45'
-updated_date: '2026-03-23 03:22'
+updated_date: '2026-03-16 05:13'
 labels:
   - dictionary
   - startup
@@ -18,7 +17,7 @@ references:
   - >-
     /home/sudacode/projects/japanese/SubMiner/src/main/runtime/current-media-tokenization-gate.ts
 priority: high
-ordinal: 144500
+ordinal: 37500
 ---
 
 ## Description
@@ -34,20 +33,8 @@ Keep character dictionary auto-sync running in parallel during startup without d
 - [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

@@ -6,7 +6,7 @@ title: >-
 status: Done
 assignee: []
 created_date: '2026-03-09 10:40'
-updated_date: '2026-03-18 05:28'
+updated_date: '2026-03-16 05:13'
 labels:
   - startup
   - overlay
@@ -21,7 +21,7 @@ references:
   - >-
     /home/sudacode/projects/japanese/SubMiner/src/main/runtime/character-dictionary-auto-sync-notifications.ts
 priority: medium
-ordinal: 37500
+ordinal: 36500
 ---
 
 ## Description

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

@@ -5,14 +5,14 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-09 00:00'
-updated_date: '2026-03-18 05:28'
+updated_date: '2026-03-16 05:13'
 labels:
   - bug
   - overlay
   - aniskip
   - linux
 dependencies: []
-ordinal: 47500
+ordinal: 46500
 ---
 
 ## Description

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

@@ -5,14 +5,14 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-09 00:00'
-updated_date: '2026-03-18 05:28'
+updated_date: '2026-03-16 05:13'
 labels:
   - windows
   - plugin
   - regression
 dependencies: []
 priority: medium
-ordinal: 48500
+ordinal: 47500
 ---
 
 ## Description

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-18 05:28'
+updated_date: '2026-03-16 05:13'
 labels:
   - release
   - patch
@@ -25,7 +25,7 @@ references:
   - scripts/build-changelog.test.ts
   - docs/RELEASING.md
 priority: high
-ordinal: 39500
+ordinal: 38500
 ---
 
 ## Description

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-18 05:28'
+updated_date: '2026-03-16 05:13'
 labels:
   - tooling
   - formatting
@@ -20,7 +20,7 @@ references:
   - scripts/build-win-unsigned.mjs
   - src
 priority: medium
-ordinal: 40500
+ordinal: 39500
 ---
 
 ## Description

backlog/tasks/task-162 - Normalize-packaged-Linux-paths-to-canonical-SubMiner-directories.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-11 08:28'
-updated_date: '2026-03-18 05:28'
+updated_date: '2026-03-16 06:25'
 labels:
   - linux
   - packaging
@@ -20,7 +20,6 @@ references:
   - docs-site/launcher-script.md
   - README.md
 priority: medium
-ordinal: 116500
 ---
 
 ## Description

backlog/tasks/task-166 - Harden-SubMiner-change-verification-for-authoritative-agentic-runtime-checks.md

@@ -0,0 +1,65 @@
+---
+id: TASK-166
+title: Harden SubMiner change verification for authoritative agentic runtime checks
+status: Done
+assignee: []
+created_date: '2026-03-13 05:19'
+updated_date: '2026-03-16 05:13'
+labels:
+  - testing
+  - agents
+  - verification
+dependencies: []
+references:
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/.agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/.agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh
+  - >-
+    /home/sudacode/projects/japanese/SubMiner/.agents/skills/subminer-change-verification/SKILL.md
+documentation:
+  - /home/sudacode/projects/japanese/SubMiner/testing-plan.md
+  - /home/sudacode/projects/japanese/SubMiner/docs-site/development.md
+ordinal: 22500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Tighten the SubMiner change-verification classifier and verifier so the implementation matches the approved agentic verification plan: authoritative runtime verification must fail closed when unavailable, lane naming should use real-runtime semantics, session and artifact identities must be unique, and the verifier must be safer for parallel agent use.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 The verifier uses `real-runtime` terminology instead of `real-gui` for authoritative runtime verification
+- [x] #2 Requested authoritative runtime verification fails closed with a non-green outcome when it cannot run, and unknown lanes do not pass open
+- [x] #3 The verifier allocates a unique session identifier and artifact root that does not rely on second-level timestamp uniqueness alone
+- [x] #4 The verifier summary/report output includes explicit top-level status and session metadata needed for agent aggregation
+- [x] #5 The classifier and verifier better reflect runtime-escalation cases for launcher/plugin/socket/runtime-sensitive changes
+- [x] #6 Regression tests cover the new verifier/classifier behavior
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add regression tests for classifier/verifier behavior before changing the scripts.
+2. Harden `verify_subminer_change.sh` to use `real-runtime` terminology, fail closed for blocked/unknown authoritative verification, and emit unique session metadata in summaries.
+3. Update `classify_subminer_diff.sh` and the skill doc to use `real-runtime` escalation language and better flag launcher/plugin/runtime-sensitive paths.
+4. Run targeted regression tests plus a focused dry-run verifier check, then record outcomes and blockers in the task.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Added `scripts/subminer-change-verification.test.ts` to regression-test classifier/verifier behavior around `real-runtime` naming, fail-closed authoritative verification, unknown lanes, and unique session metadata.
+
+Reworked `verify_subminer_change.sh` to normalize `real-gui` to `real-runtime`, emit unique session IDs and richer summary metadata, block authoritative runtime verification when unavailable, and fail closed for unknown lanes.
+
+Updated `classify_subminer_diff.sh` to emit `real-runtime-candidate` for launcher/plugin/runtime-sensitive paths, and updated the active skill doc wording to match the new lane terminology.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Hardened the SubMiner change-verification tooling to match the approved agentic verification plan. The verifier now uses `real-runtime` terminology for authoritative runtime verification, preserves compatibility with the deprecated `real-gui` alias, fails closed for unknown lanes, and returns a blocked non-green outcome when requested authoritative runtime verification cannot run. It now allocates a unique session ID and artifact root by default, writes richer session metadata and top-level status into `summary.json`/`summary.txt` plus `reports/summary.*`, and records path selection mode, blockers, and session-local env roots for agent aggregation. The classifier now emits `real-runtime-candidate` for launcher/plugin/runtime-sensitive paths, and the active skill doc uses the same terminology. Verification ran via `bun test scripts/subminer-change-verification.test.ts`, direct dry-run smoke checks for blocked `real-runtime` and failed unknown-lane execution, and a targeted classifier invocation for launcher/plugin paths.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-166 - Prevent-AUR-upgrade-cache-collisions-for-unversioned-release-assets.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - Codex
 created_date: '2026-03-17 18:10'
-updated_date: '2026-03-18 05:28'
+updated_date: '2026-03-17 18:14'
 labels:
   - release
   - packaging
@@ -16,12 +16,9 @@ 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
+  - /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

backlog/tasks/task-169 - Add-anime-level-immersion-metadata-and-link-videos.md

@@ -11,7 +11,6 @@ labels:
   - stats
   - database
   - anilist
-milestone: m-1
 dependencies: []
 references:
   - >-

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

@@ -1,80 +0,0 @@
----
-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

@@ -1,12 +1,11 @@
 ---
 id: TASK-170
-title: Fix imm_words POS filtering and add stats cleanup maintenance command
+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'
+updated_date: '2026-03-14 18:31'
 labels: []
-milestone: m-1
 dependencies: []
 priority: high
 ordinal: 9010
@@ -15,19 +14,25 @@ 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:
@@ -36,4 +41,5 @@ Verification:
 - `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

@@ -10,7 +10,6 @@ labels:
   - immersion
   - stats
   - database
-milestone: m-1
 dependencies: []
 references:
   - >-

backlog/tasks/task-172 - Stabilize-macOS-fullscreen-overlay-layering-and-tracker-flaps.md

@@ -5,24 +5,20 @@ status: Done
 assignee:
   - '@codex'
 created_date: '2026-03-16 10:45'
-updated_date: '2026-03-18 05:28'
+updated_date: '2026-03-16 23:04'
 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/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
+ordinal: 53000
 ---
 
 ## Description

backlog/tasks/task-172 - Wire-immersion-occurrence-drilldown-into-stats-API-and-vocabulary-drawer.md

@@ -0,0 +1,64 @@
+---
+id: TASK-172
+title: Wire immersion occurrence drilldown into stats API and vocabulary drawer
+status: Done
+assignee:
+  - codex
+created_date: '2026-03-14 12:05'
+updated_date: '2026-03-16 05:13'
+labels:
+  - immersion
+  - stats
+  - ui
+dependencies:
+  - TASK-171
+ordinal: 18500
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Expose the new immersion word/kanji occurrence queries through the stats server and add a right-side Vocabulary drawer that shows recent occurrence rows with paging when a word or kanji is clicked.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Stats server exposes word and kanji occurrence endpoints with bounded recent-first paging.
+- [x] #2 Stats client/types support loading occurrence pages for a selected word or kanji.
+- [x] #3 Vocabulary tab opens a right drawer for the selected word/kanji, shows recent occurrences, and supports loading more.
+- [x] #4 Focused regression coverage exists for the server endpoint contract, and the stats UI still typechecks/builds.
+- [x] #5 Verification covers the cheapest sufficient backend and stats-UI lanes.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+2026-03-14: Design approved in-thread. Chosen UX: click a word chip or kanji glyph to open a right-side drawer with recent-first occurrences, initial cap 50, plus “Load more”.
+2026-03-14: Implemented `/api/stats/vocabulary/occurrences` and `/api/stats/kanji/occurrences` with `limit` + `offset` paging. The drawer uses direct stats HTTP client calls and keeps existing aggregate vocabulary data flow intact.
+2026-03-14: Verification commands run:
+  - `bun test src/core/services/__tests__/stats-server.test.ts`
+  - `bun run typecheck`
+  - `cd stats && bun run build`
+  - `bun run docs:test`
+  - `bun run docs:build`
+  - `cd stats && bunx tsc --noEmit`
+  - `bash .agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh --lane core src/core/services/stats-server.ts src/core/services/__tests__/stats-server.test.ts`
+2026-03-14: Verification results:
+  - stats server endpoint tests: passed
+  - root typecheck: passed
+  - stats UI production build: passed
+  - docs-site test/build: passed
+  - `cd stats && bunx tsc --noEmit`: passed after removing stale `hasCoverArt` prop usage in the library stats UI
+  - verifier result: passed (`typecheck`, `test:fast`)
+  - verifier artifacts: `.tmp/skill-verification/subminer-verify-20260314-120900-J0VvB0/`
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Wired occurrence drilldown into the stats server and Vocabulary tab. Words and kanji now open a right-side drawer that loads recent occurrence rows 50 at a time and supports “Load more”.
+
+Added bounded recent-first occurrence endpoints to the stats HTTP API, extended the stats client/type surface, and made word chips plus kanji glyphs selectable with active-state styling.
+
+Updated the immersion-tracking docs to mention vocabulary occurrence drilldown. Verified with focused stats-server tests, root typecheck, stats UI production build, docs-site test/build, the repo verifier core lane, and a direct `stats` package typecheck after removing the stale `MediaHeader` prop mismatch.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-173 - Remove-Avg-Frequency-metric-from-Vocabulary-tab-summary-cards.md

@@ -8,7 +8,6 @@ updated_date: '2026-03-16 05:13'
 labels:
   - stats
   - ui
-milestone: m-1
 dependencies: []
 priority: low
 ordinal: 17500

backlog/tasks/task-174 - Fix-missing-frequency-highlights-for-merged-tokenizer-tokens.md

@@ -5,7 +5,7 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-15 10:18'
-updated_date: '2026-03-18 05:28'
+updated_date: '2026-03-16 06:46'
 labels:
   - bug
   - tokenizer
@@ -20,7 +20,6 @@ references:
   - /Users/sudacode/projects/japanese/SubMiner/scripts/get_frequency.ts
   - /Users/sudacode/projects/japanese/SubMiner/scripts/test-yomitan-parser.ts
 priority: high
-ordinal: 115500
 ---
 
 ## Description

backlog/tasks/task-177 - Track-intentional-Yomitan-lookups-in-stats.md

@@ -5,12 +5,11 @@ status: Done
 assignee:
   - codex
 created_date: '2026-03-17 09:15'
-updated_date: '2026-03-18 05:28'
+updated_date: '2026-03-17 09:41'
 labels:
   - stats
   - immersion-tracking
   - yomitan
-milestone: m-1
 dependencies: []
 references:
   - vendor/subminer-yomitan/ext/js/app/frontend.js
@@ -24,7 +23,6 @@ references:
 documentation:
   - docs/plans/2026-03-17-yomitan-lookup-stats-design.md
 priority: medium
-ordinal: 114500
 ---
 
 ## Description