Clarify install requirements and dependency checks

- Reclassify ffmpeg and MeCab as recommended or optional
- Add `subminer doctor` install verification step
- Refresh platform-specific install guidance and first-run tips

README.md

@@ -112,12 +112,15 @@ Managed local playback now reapplies your configured subtitle language prioritie
 
 ## Requirements
 
-|                | Required                                | Optional                                                   |
+|                | Required                                | Recommended                              | Optional                                                    |
-| -------------- | --------------------------------------- | ---------------------------------------------------------- |
+| -------------- | --------------------------------------- | ---------------------------------------- | ----------------------------------------------------------- |
-| **Player**     | [`mpv`](https://mpv.io) with IPC socket | —                                                          |
+| **Player**     | [`mpv`](https://mpv.io) with IPC socket | —                                        | —                                                           |
-| **Processing** | `ffmpeg`, `mecab` + `mecab-ipadic`      | `guessit` (AniSkip), `alass` / `ffsubsync` (subtitle sync) |
+| **Processing** | —                                       | `ffmpeg` (audio clips & screenshots)     | `mecab` + `mecab-ipadic` (annotation POS filtering), `guessit` (AniSkip), `alass` / `ffsubsync` (subtitle sync) |
-| **Media**      | —                                       | `yt-dlp`, `chafa`, `ffmpegthumbnailer`                     |
+| **Media**      | —                                       | —                                        | `yt-dlp`, `chafa`, `ffmpegthumbnailer`                      |
-| **Selection**  | —                                       | `fzf` / `rofi`                                             |
+| **Selection**  | —                                       | —                                        | `fzf` / `rofi`                                              |
+
+> [!TIP]
+> `ffmpeg` is not strictly required to run SubMiner, but without it audio clips and screenshots will not be attached to Anki cards. Most users will want it installed.
 
 > [!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.
@@ -132,9 +135,9 @@ Managed local playback now reapplies your configured subtitle language prioritie
 <summary><b>Arch Linux</b></summary>
 
 ```bash
-paru -S --needed mpv ffmpeg mecab-git mecab-ipadic
+paru -S --needed mpv ffmpeg
 # Optional
-paru -S --needed yt-dlp fzf rofi chafa ffmpegthumbnailer xdotool xorg-xwininfo
+paru -S --needed mecab-git mecab-ipadic 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
@@ -147,9 +150,9 @@ paru -S --needed xdotool xorg-xwininfo
 <summary><b>macOS</b></summary>
 
 ```bash
-brew install mpv ffmpeg mecab mecab-ipadic
+brew install mpv ffmpeg
 # Optional
-brew install yt-dlp fzf rofi chafa ffmpegthumbnailer
+brew install mecab mecab-ipadic yt-dlp fzf rofi chafa ffmpegthumbnailer
 # Optional: subtitle sync (install at least one for subtitle syncing to work)
 brew install alass
 pip install ffsubsync
@@ -164,7 +167,7 @@ Grant Accessibility permission to SubMiner in **System Settings > Privacy & Secu
 
 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.
+Optionally install [MeCab for Windows](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary for additional metadata enrichment.
 
 </details>
 
@@ -226,11 +229,17 @@ See the [build-from-source guide](https://docs.subminer.moe/installation#from-so
 
 </details>
 
-### 2. First Launch
+### 2. Check Dependencies
+
+```bash
+subminer doctor                 # verify mpv, ffmpeg, config, and socket
+```
+
+### 3. First Launch
 
 Run the app. On first launch SubMiner starts in the system tray, creates a default config, and opens a setup popup to finish config, install the mpv plugin, and configure Yomitan dictionaries.
 
-### 3. Mine
+### 4. Mine
 
 ```bash
 subminer video.mkv          # play video with overlay

docs-site/installation.md

@@ -5,11 +5,11 @@
 ### System Dependencies
 
 | Dependency           | Required    | Notes                                                    |
-| -------------------- | ---------- | -------------------------------------------------------- |
+| -------------------- | ----------- | -------------------------------------------------------- |
-| Bun                  | Yes        | Required for `subminer` wrapper and source workflows     |
 | mpv                  | Yes         | Must support IPC sockets (`--input-ipc-server`)          |
-| ffmpeg               | For media  | Audio extraction and screenshot generation               |
+| Bun                  | For wrapper | Required for `subminer` CLI wrapper and source builds. Pre-built releases (AppImage, DMG, installer) work without it — only the `subminer` wrapper script needs Bun on `PATH`. |
-| MeCab + mecab-ipadic | No         | Optional Japanese metadata enrichment (not the primary tokenizer) |
+| ffmpeg               | Recommended | Audio extraction and screenshot generation. Without it SubMiner still runs, but audio and image fields on Anki cards will be empty. |
+| MeCab + mecab-ipadic | No          | Adds part-of-speech data used to filter particles out of N+1, JLPT, and frequency annotations. Without it annotations still render, but POS-based filtering is less precise. |
 | fuse2                | Linux only  | Required for AppImage                                    |
 | yt-dlp               | No          | Recommended for YouTube playback and subtitle extraction |
 
@@ -70,7 +70,9 @@ chmod +x ~/.local/bin/subminer
 
 ```
 
-The `subminer` wrapper uses a Bun shebang (`#!/usr/bin/env bun`), so [Bun](https://bun.sh) must be installed and available on `PATH`.
+::: warning Bun required for the wrapper
+The `subminer` wrapper uses a Bun shebang (`#!/usr/bin/env bun`), so [Bun](https://bun.sh) must be installed and available on `PATH`. If you see `/usr/bin/env: 'bun': No such file or directory` when running `subminer`, install Bun first: `curl -fsSL https://bun.sh/install | bash`. The AppImage itself does **not** need Bun — only the `subminer` convenience wrapper does.
+:::
 
 ### From Source
 
@@ -103,7 +105,9 @@ A **ZIP** artifact is also available as a fallback — unzip and drag `SubMiner.
 Install dependencies using Homebrew:
 
 ```bash
-brew install mpv mecab mecab-ipadic
+brew install mpv ffmpeg
+# Optional but recommended if you use N+1, JLPT, or frequency annotations
+brew install mecab mecab-ipadic
 ```
 
 ### From Source (macOS)
@@ -123,13 +127,20 @@ For unsigned local builds:
 bun run build:mac:unsigned
 ```
 
+### Gatekeeper
+
+If macOS blocks SubMiner on first launch, right-click the app and select **Open** to bypass the warning. Alternatively, remove the quarantine attribute:
+
+```bash
+xattr -d com.apple.quarantine /Applications/SubMiner.app
+```
+
 ### Accessibility Permission
 
 After launching SubMiner for the first time, grant accessibility permission:
 
-1. Open **System Preferences** → **Security & Privacy** → **Privacy** tab
+1. Open **System Settings** → **Privacy & Security** → **Accessibility**
-2. Select **Accessibility** from the left sidebar
+2. Enable SubMiner in the list (add it if it does not appear)
-3. Add SubMiner to the list
 
 Without this permission, window tracking will not work and the overlay won't follow the mpv window.
 
@@ -167,7 +178,7 @@ Download the latest Windows installer from [GitHub Releases](https://github.com/
 - `SubMiner-<version>.exe` installs the app, Start menu shortcut, and default files under `Program Files`
 - `SubMiner-<version>.zip` is available as a portable fallback
 
-Install `mpv` separately and ensure `mpv.exe` is on `PATH`. `ffmpeg` is still required for media extraction, and MeCab remains optional.
+Install `mpv` separately and ensure `mpv.exe` is on `PATH`. `ffmpeg` is recommended for audio/screenshot extraction (without it, media fields on Anki cards will be empty). MeCab is optional.
 
 ### Windows Usage Notes
 
@@ -184,10 +195,14 @@ Install `mpv` separately and ensure `mpv.exe` is on `PATH`. `ffmpeg` is still re
 git clone https://github.com/ksyasuda/SubMiner.git
 cd SubMiner
 bun install
+
+# Windows requires building the texthooker-ui submodule manually before
+# the main build (Linux/macOS handle this automatically during `bun run build`).
 Set-Location vendor/texthooker-ui
 bun install --frozen-lockfile
 bun run build
 Set-Location ../..
+
 bun run build:win
 ```
 
@@ -240,7 +255,13 @@ See [MPV Plugin](/mpv-plugin) for the full configuration reference, keybindings,
 
 ## Verify Installation
 
-After installing, confirm SubMiner is working:
+After installing, run the built-in diagnostic to confirm dependencies are in place:
+
+```bash
+subminer doctor
+```
+
+This checks for the app binary, mpv, ffmpeg, config file, and socket path. Fix any failures before continuing.
 
 On Windows, replace `SubMiner.AppImage` with `SubMiner.exe` in the direct app commands below.
 

docs-site/usage.md

@@ -4,6 +4,26 @@
 > SubMiner requires the bundled Yomitan instance to have at least one dictionary imported for lookups to work.
 > See [Yomitan setup](#yomitan-setup) for details.
 
+::: tip Just finished first-run setup?
+If you want Anki card enrichment (sentence, audio, screenshot), the only config you need is `ankiConnect` with your deck name and field names. Here is a minimal working example:
+
+```jsonc
+{
+  "ankiConnect": {
+    "enabled": true,
+    "deck": "Mining",
+    "fields": {
+      "sentence": "Sentence",
+      "audio": "SentenceAudio",
+      "image": "Picture"
+    }
+  }
+}
+```
+
+Field names must match your Anki note type exactly (case-sensitive). See [Anki Integration](/anki-integration) for the full reference.
+:::
+
 ## How It Works
 
 1. SubMiner starts the overlay app in the background