docs: refresh README and docs site guidance

README.md

@@ -126,8 +126,11 @@ Browse sibling episode files and the active mpv queue in one overlay modal. Open
 **Platform-specific:**
 
 | Linux                                                        | macOS                    | Windows       |
-| ----------------------------------- | ------------------------ | ------------- |
+| ------------------------------------------------------------ | ------------------------ | ------------- |
-| `hyprctl` or `xdotool` + `xwininfo` | Accessibility permission | No extra deps |
+| Hyprland (`hyprctl`) · X11/Xwayland (`xdotool` + `xwininfo`) | Accessibility permission | No extra deps |
+
+> [!NOTE]
+> **Wayland support is compositor-specific.** Wayland has no universal API for window positioning and each compositor exposes its own IPC, so SubMiner needs a dedicated backend per compositor. Hyprland is the only native Wayland backend supported currenlty. All other Linux compositors require both mpv and SubMiner to run under X11 or Xwayland.
 
 <details>
 <summary><b>Arch Linux</b></summary>
@@ -138,7 +141,7 @@ paru -S --needed mpv ffmpeg
 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
+# X11 / Xwayland (required for non-Hyprland compositors)
 paru -S --needed xdotool xorg-xwininfo
 ```
 

docs-site/.vitepress/config.ts

@@ -76,7 +76,6 @@ export default {
           { text: 'Subtitle Annotations', link: '/subtitle-annotations' },
           { text: 'Subtitle Sidebar', link: '/subtitle-sidebar' },
           { text: 'Immersion Tracking', link: '/immersion-tracking' },
-          { text: 'JLPT Vocabulary Bundle', link: '/jlpt-vocab-bundle' },
           { text: 'Troubleshooting', link: '/troubleshooting' },
         ],
       },

docs-site/.vitepress/theme/tui-theme.css

@@ -220,6 +220,7 @@ button,
   color: var(--vp-c-brand-1);
   font-family: var(--tui-font-mono), 'M PLUS 1', 'Noto Sans CJK JP', 'Noto Sans JP',
     monospace;
+  font-variant-ligatures: none;
 }
 
 /* === Code blocks === */
@@ -229,6 +230,7 @@ button,
   background: var(--vp-c-bg-alt) !important;
   font-family: var(--tui-font-mono), 'M PLUS 1', 'Noto Sans CJK JP', 'Noto Sans JP',
     monospace;
+  font-variant-ligatures: none;
 }
 
 .vp-doc div[class*='language-']::before {

docs-site/anilist-integration.md

@@ -41,28 +41,6 @@ The update flow:
 3. **Progress check** -- SubMiner fetches your current list entry for the matched media. If your recorded progress already meets or exceeds the detected episode, the update is skipped.
 4. **Mutation** -- A `SaveMediaListEntry` mutation sets the new progress and marks the entry as `CURRENT`.
 
-```mermaid
-flowchart TB
-  classDef step fill:#c6a0f6,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef action fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef result fill:#a6da95,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef enrich fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef ext fill:#eed49f,stroke:#494d64,color:#24273a,stroke-width:1.5px
-
-  Play["Media Plays"]:::step
-  Detect["Episode Detected"]:::action
-  Queue["Update Queue"]:::action
-  Rate["Rate Limiter"]:::enrich
-  GQL["GraphQL Mutation"]:::ext
-  Done["Progress Updated"]:::result
-
-  Play --> Detect
-  Detect --> Queue
-  Queue --> Rate
-  Rate --> GQL
-  GQL --> Done
-```
-
 ## Update Queue and Retry
 
 Failed AniList updates are persisted to a retry queue on disk and retried with exponential backoff.

docs-site/anki-integration.md

@@ -250,6 +250,10 @@ The built-in translation request asks for English output by default. Customize t
 
 SubMiner can create standalone sentence cards (without a word/expression) using a separate note type. This is designed for use with [Lapis](https://github.com/donkuri/Lapis) and similar sentence-focused note types.
 
+::: warning Required config
+Sentence card creation and audio card marking both require `ankiConnect.isLapis.enabled: true` and a valid `sentenceCardModel` pointing to your Lapis/Kiku note type. Without this, the `Ctrl/Cmd+S` and `Ctrl/Cmd+Shift+A` shortcuts will not create cards.
+:::
+
 ```jsonc
 "ankiConnect": {
   "isLapis": {

docs-site/character-dictionary.md

@@ -4,23 +4,6 @@ SubMiner can build a Yomitan-compatible character dictionary from AniList metada
 
 The dictionary is generated per-media, merged across your recently-watched titles, and auto-imported into Yomitan. When a character name appears in a subtitle line, it gets highlighted and becomes available for hover-driven Yomitan profile lookup.
 
-## Stats Dashboard
-
-The character dictionary and stats dashboard both read from the same local immersion data.
-
-- Open the dashboard from overlay: press your configured `stats.toggleKey` (default: `` ` `` / `Backquote`).
-- Open from launcher/CLI: run `subminer stats`.
-- Open directly: visit `http://127.0.0.1:<stats.serverPort>` when the local server is running.
-
-Useful config keys:
-
-- `stats.autoStartServer` — start the local stats server automatically once immersion tracking starts.
-- `stats.serverPort` — local HTTP port for dashboard and API.
-- `stats.toggleKey` — key binding for overlay dashboard toggle.
-- `stats.autoOpenBrowser` — auto-open dashboard browser for `subminer stats`.
-
-The dashboard gives quick visibility into episode summaries, watch-time rollups, session timelines, and vocabulary/kanji drill-down from the same DB used by character matching.
-
 ## How It Works
 
 The feature has three stages: **snapshot**, **merge**, and **match**.
@@ -31,30 +14,6 @@ The feature has three stages: **snapshot**, **merge**, and **match**.
 
 3. **Match** — During subtitle rendering, Yomitan scans subtitle text against all loaded dictionaries including the character dictionary. Tokens that match a character entry are flagged with `isNameMatch` and highlighted in the overlay with a distinct color.
 
-```mermaid
-flowchart TB
-  classDef api fill:#a6da95,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef store fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef build fill:#b7bdf8,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef dict fill:#c6a0f6,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef render fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
-
-  AL["AniList API"]:::api
-  Snap["Snapshot JSON"]:::store
-  Merge["Merge"]:::build
-  ZIP["Yomitan ZIP"]:::dict
-  Yomi["Yomitan Import"]:::dict
-  Sub["Subtitle Scan"]:::render
-  HL["Name Highlight"]:::render
-
-  AL -->|"GraphQL"| Snap
-  Snap --> Merge
-  Merge --> ZIP
-  ZIP --> Yomi
-  Yomi --> Sub
-  Sub --> HL
-```
-
 ## Enabling the Feature
 
 Character dictionary sync is disabled by default. To turn it on:

docs-site/configuration.md

@@ -324,8 +324,6 @@ See `config.example.jsonc` for detailed configuration options.
 | `jlptColors`                       | object      | JLPT level underline colors object (`N1`..`N5`)                                                                            |
 | `secondary`                        | object      | Override any of the above for secondary subtitles (optional)                                                               |
 
-JLPT underlining is powered by offline term-meta bank files at runtime. See [`docs/jlpt-vocab-bundle.md`](jlpt-vocab-bundle.md) for required files, source/version refresh steps, and deterministic fallback behavior.
-
 Frequency dictionary highlighting uses the same dictionary file format as JLPT bundle lookups (`term_meta_bank_*.json` under discovered dictionary directories). A token is highlighted when it has a positive integer `frequencyRank` (lower is more common) and the rank is within `topX`.
 
 Lookup behavior:

docs-site/installation.md

@@ -28,11 +28,15 @@ The `subminer` launcher script handles step 1 automatically. If you launch mpv y
 
 ### Platform-Specific
 
-**Linux** — one of the following compositors:
+**Linux** — one of the following window backends:
 
-- Hyprland (uses `hyprctl`)
+- **Hyprland** — native Wayland support (uses `hyprctl`)
-- Sway (uses `swaymsg`)
+- **Sway** — native Wayland support (uses `swaymsg`)
-- X11 (uses `xdotool` and `xwininfo`)
+- **X11 / Xwayland** — for X11 sessions or any other Wayland compositor (uses `xdotool` and `xwininfo`)
+
+::: warning Wayland support is compositor-specific
+Wayland has no universal API for window positioning — each compositor exposes its own IPC, so SubMiner needs a dedicated backend per compositor. Only Hyprland and Sway have native Wayland backends. If you run a different Wayland compositor (GNOME, KDE Plasma, river, etc.), both mpv **and** SubMiner must run under X11 or Xwayland. The `subminer` launcher handles this automatically when `--backend x11` is set or the X11 backend is auto-detected.
+:::
 
 <details>
 <summary><b>Arch Linux</b></summary>
@@ -43,7 +47,7 @@ sudo pacman -S --needed mpv ffmpeg
 sudo pacman -S --needed mecab mecab-ipadic yt-dlp fzf rofi chafa ffmpegthumbnailer
 # Optional: subtitle sync (at least one needed for subtitle syncing)
 paru -S --needed alass python-ffsubsync
-# X11 / XWAYLAND
+# X11 / Xwayland (required for non-Hyprland/Sway compositors)
 sudo pacman -S --needed xdotool xorg-xwininfo
 ```
 
@@ -56,7 +60,7 @@ sudo pacman -S --needed xdotool xorg-xwininfo
 sudo apt install mpv ffmpeg
 # Optional
 sudo apt install mecab libmecab-dev mecab-ipadic-utf8 fzf rofi chafa ffmpegthumbnailer yt-dlp
-# X11
+# X11 / Xwayland (required for non-Hyprland/Sway compositors)
 sudo apt install xdotool x11-utils
 # Optional: subtitle sync
 pip install ffsubsync
@@ -72,7 +76,7 @@ pip install ffsubsync
 sudo dnf install mpv ffmpeg
 # Optional
 sudo dnf install mecab mecab-ipadic fzf rofi chafa ffmpegthumbnailer yt-dlp
-# X11
+# X11 / Xwayland (required for non-Hyprland/Sway compositors)
 sudo dnf install xdotool xorg-x11-utils
 # Optional: subtitle sync
 pip install ffsubsync
@@ -456,7 +460,7 @@ This checks for the app binary, mpv, ffmpeg, config file, and socket path. Fix a
 
 ### Rofi Theme (Linux Only)
 
-SubMiner ships a default rofi theme at `assets/themes/subminer.rasi`.
+SubMiner ships a custom rofi theme bundled in the release assets tarball.
 
 Install path (default auto-detected by `subminer`):
 
@@ -464,6 +468,8 @@ Install path (default auto-detected by `subminer`):
 - macOS: `~/Library/Application Support/SubMiner/themes/subminer.rasi`
 
 ```bash
+wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
+tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
 mkdir -p ~/.local/share/SubMiner/themes
 cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi
 ```

docs-site/jimaku-integration.md

@@ -26,31 +26,6 @@ If no files match the current episode filter, a "Show all files" button lets you
 | `Arrow Up` / `Arrow Down` | Navigate entries or files |
 | `Escape` | Close modal |
 
-### Flow
-
-```mermaid
-flowchart TD
-  classDef step fill:#c6a0f6,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef action fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef result fill:#a6da95,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef enrich fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
-
-  Open["Open Jimaku modal (Ctrl+Shift+J)"]:::step
-  Parse["Auto-fill title, season, episode from filename"]:::enrich
-  Search["Search Jimaku API"]:::action
-  Entries["Browse matching entries"]:::action
-  Files["Browse subtitle files"]:::action
-  Download["Download selected file"]:::action
-  Load["Load subtitle into mpv"]:::result
-
-  Open --> Parse
-  Parse --> Search
-  Search --> Entries
-  Entries --> Files
-  Files --> Download
-  Download --> Load
-```
-
 ## Configuration
 
 Add a `jimaku` section to your `config.jsonc`:

docs-site/jlpt-vocab-bundle.md

@@ -1,45 +0,0 @@
-# JLPT Vocabulary Bundle (Offline)
-
-## Bundle location
-
-SubMiner expects the JLPT term-meta bank files to be available locally at:
-
-- `vendor/yomitan-jlpt-vocab`
-
-At runtime, SubMiner also searches these derived locations:
-
-- `vendor/yomitan-jlpt-vocab`
-- `vendor/yomitan-jlpt-vocab/vendor/yomitan-jlpt-vocab`
-- `vendor/yomitan-jlpt-vocab/yomitan-jlpt-vocab`
-
-and user-data/config fallback paths (see `getJlptDictionarySearchPaths` in `src/main.ts`).
-
-## Required files
-
-The expected files are:
-
-- `term_meta_bank_1.json`
-- `term_meta_bank_2.json`
-- `term_meta_bank_3.json`
-- `term_meta_bank_4.json`
-- `term_meta_bank_5.json`
-
-Each bank maps terms to frequency metadata; only entries with a `frequency.displayValue` are considered for JLPT tagging.
-
-SubMiner also reuses the same `term_meta_bank_*.json` format for frequency-based subtitle highlighting, using installed/default `frequency-dictionary` locations or an explicit `subtitleStyle.frequencyDictionary.sourcePath`.
-
-## Source and update process
-
-For reproducible updates:
-
-1. Obtain the JLPT term-meta bank archive from the same upstream source that supplies the bundled Yomitan dictionary data.
-2. Extract the five `term_meta_bank_*.json` files.
-3. Place them into `vendor/yomitan-jlpt-vocab/`.
-4. Commit the update with the source URL/version in the task notes.
-
-This repository currently ships the folder path in `electron-builder` `extraResources` as:
-`vendor/yomitan-jlpt-vocab -> yomitan-jlpt-vocab`.
-
-## Fallback Behavior
-
-If bank files are missing, malformed, or lack expected metadata, SubMiner skips them gracefully. When no usable entries are found, JLPT underlining is silently disabled and subtitle rendering remains unchanged.

docs-site/launcher-script.md

@@ -31,11 +31,14 @@ fzf shows video files in a fuzzy-searchable list. If `chafa` is installed, you g
 subminer -R                            # rofi picker, current directory
 subminer -R -d ~/Videos                # rofi picker, specific directory
 subminer -R -r -d ~/Anime              # rofi picker, recursive
+subminer -R /directory                 # rofi picker, directory shortcut
 ```
 
-rofi shows a GUI menu with icon thumbnails when available. SubMiner ships a custom rofi theme that can be installed from the release assets:
+rofi shows a GUI menu with icon thumbnails when available. SubMiner ships a custom rofi theme bundled in the release assets tarball:
 
 ```bash
+wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
+tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
 mkdir -p ~/.local/share/SubMiner/themes
 cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi
 ```
@@ -58,14 +61,10 @@ SUBMINER_ROFI_THEME=/path/to/custom-theme.rasi subminer -R
 
 ```bash
 subminer video.mkv                      # play a specific file (default plugin config auto-starts visible overlay)
-subminer --start video.mkv      # optional explicit overlay start when plugin auto_start=no
-subminer -S video.mkv           # same as above via --start-overlay
 subminer https://youtu.be/...           # YouTube playback (requires yt-dlp)
-subminer ytsearch:"jp news"     # YouTube search
+subminer --backend x11 video.mkv        # Force x11 backend for a specific file
 subminer stats                          # open immersion dashboard
 subminer stats -b                       # start background stats daemon
-subminer stats -s               # stop background stats daemon
-subminer --setup                # Open first-run setup popup
 ```
 
 ## Subcommands
@@ -75,7 +74,6 @@ subminer --setup                # Open first-run setup popup
 | `subminer jellyfin` / `jf`   | Jellyfin workflows (`-d` discovery, `-p` play, `-l` login) |
 | `subminer stats`             | Start stats server and open immersion dashboard in browser |
 | `subminer stats -b`          | Start or reuse background stats daemon (non-blocking)      |
-| `subminer stats -s`          | Stop the background stats daemon                           |
 | `subminer stats cleanup`     | Backfill vocabulary metadata and prune stale rows          |
 | `subminer doctor`            | Dependency + config + socket diagnostics                   |
 | `subminer config path`       | Print active config file path                              |
@@ -100,7 +98,7 @@ Use `subminer <subcommand> -h` for command-specific help.
 | `--start`             | Explicitly start overlay after mpv launches         |
 | `-S, --start-overlay` | Explicitly start overlay after mpv launches         |
 | `-T, --no-texthooker` | Disable texthooker server                           |
-| `-p, --profile`       | mpv profile name (default: `subminer`)              |
+| `-p, --profile`       | mpv profile name (no default; omitted unless set)   |
 | `-a, --args`          | Pass additional mpv arguments as a quoted string      |
 | `-b, --backend`       | Force window backend (`hyprland`, `sway`, `x11`, `macos`, `windows`)    |
 | `--log-level`         | Logger verbosity (`debug`, `info`, `warn`, `error`) |

docs-site/mining-workflow.md

@@ -6,30 +6,6 @@ This guide walks through the sentence mining loop — from watching a video to c
 
 SubMiner runs as a transparent overlay on top of mpv. As subtitles play, the overlay displays them as interactive text. You hover a word, trigger Yomitan lookup with your configured lookup key/modifier, then create an Anki card with a single action. SubMiner automatically attaches the sentence, audio clip, and screenshot.
 
-```mermaid
-flowchart TB
-  classDef step fill:#c6a0f6,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef action fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef result fill:#a6da95,stroke:#494d64,color:#24273a,stroke-width:1.5px
-  classDef enrich fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
-
-  Watch["Watch Video"]:::step
-  Sub["Subtitle Appears"]:::step
-  Hover["Hover Word"]:::action
-  Lookup["Trigger Lookup"]:::action
-  Yomi["Yomitan Popup"]:::result
-  Add["Add to Anki"]:::result
-
-  Watch --> Sub --> Hover --> Lookup --> Yomi --> Add
-
-  Add --> Enrich["SubMiner Enriches"]:::enrich
-
-  Enrich --> S["Sentence"]:::enrich
-  Enrich --> A["Audio Clip"]:::enrich
-  Enrich --> I["Screenshot"]:::enrich
-  Enrich --> T["Translation"]:::enrich
-```
-
 ## Subtitle Delivery Path (Startup + Runtime)
 
 SubMiner prioritizes subtitle responsiveness over heavy initialization:
@@ -141,10 +117,18 @@ Create a standalone sentence card without going through Yomitan:
 
 The sentence card uses the note type configured in `isLapis.sentenceCardModel` and always maps sentence/audio to `Sentence` and `SentenceAudio`.
 
+::: warning Requires Lapis/Kiku note type
+Sentence card creation requires a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type and `ankiConnect.isLapis.enabled: true` in your config. See [Anki Integration — Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
+:::
+
 ### 4. Mark as Audio Card
 
 After adding a word via Yomitan, press the audio card shortcut to overwrite the audio with a longer clip spanning the full subtitle timing.
 
+::: warning Requires Lapis/Kiku note type
+Audio card marking requires a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type and `ankiConnect.isLapis.enabled: true` in your config. See [Anki Integration — Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
+:::
+
 ## Secondary Subtitles
 
 SubMiner can display a secondary subtitle track (typically English) alongside the primary Japanese subtitles. This is useful for:

docs-site/mpv-plugin.md

@@ -183,6 +183,10 @@ When `backend=auto`, the plugin detects the window manager:
 4. **X11** — detected via `XDG_SESSION_TYPE=x11` or `DISPLAY`.
 5. **Fallback** — defaults to X11 with a warning.
 
+::: tip Wayland is compositor-specific
+Native Wayland support is only available for Hyprland and Sway. If you use a different Wayland compositor, auto-detection will fall back to X11 — both mpv and SubMiner must be running under Xwayland, and `xdotool` and `xwininfo` must be installed.
+:::
+
 ## Script Messages
 
 The plugin can be controlled from other mpv scripts or the mpv command line using script messages:

docs-site/subtitle-annotations.md

@@ -113,10 +113,6 @@ All colors are customizable via the `subtitleStyle.jlptColors` object.
 | `subtitleStyle.enableJlpt` | `false` | Enable JLPT underline styling |
 | `subtitleStyle.jlptColors.N1`–`N5` | see above | Per-level underline colors |
 
-::: tip
-JLPT tagging requires the offline vocabulary bundle. See [JLPT Vocabulary Bundle](jlpt-vocab-bundle) for setup instructions and file locations.
-:::
-
 ## Runtime Toggles
 
 All annotation layers can be toggled at runtime via the mpv command menu without restarting:

docs-site/subtitle-sidebar.md

@@ -60,8 +60,6 @@ Enable and configure the sidebar under `subtitleSidebar` in your config file:
 | `activeLineBackgroundColor` | string  | —            | Active cue background color                                                                        |
 | `hoverLineBackgroundColor`  | string  | —            | Hovered cue background color                                                                       |
 
-Default colors use Catppuccin Macchiato with a semi-transparent shell so the panel stays readable without feeling like a solid overlay.
-
 ## Keyboard Shortcut
 
 | Key | Action                  | Config key                     |

docs-site/troubleshooting.md

@@ -136,7 +136,7 @@ Shown when SubMiner tries to update a card that no longer exists, or when AnkiCo
 **Overlay does not appear**
 
 - Confirm SubMiner is running: `SubMiner.AppImage --start` or check for the process.
-- On Linux, the overlay requires a compositor. Hyprland and Sway are supported natively; X11 requires `xdotool` and `xwininfo`.
+- On Linux, the overlay requires a supported window backend. Hyprland and Sway have native Wayland support; all other compositors require both mpv and SubMiner to run under X11 or Xwayland (`xdotool` and `xwininfo` must be installed).
 - On macOS, grant Accessibility permission to SubMiner in System Settings > Privacy & Security > Accessibility.
 
 **Overlay appears but clicks pass through / cannot interact**
@@ -232,7 +232,7 @@ Global shortcuts (`Alt+Shift+O`, `Alt+Shift+Y`) may conflict with other applicat
 
 - Check your DE/WM keybinding settings for conflicts.
 - Change the shortcut in your config under `shortcuts.toggleVisibleOverlayGlobal`.
-- On Wayland, global shortcut registration has limitations depending on the compositor.
+- On Wayland, global shortcut registration has limitations depending on the compositor. Only Hyprland and Sway are supported natively — see the [Hyprland](#hyprland) section below for shortcut passthrough rules. Other Wayland compositors require X11/Xwayland.
 
 **Overlay keybindings not working**
 
@@ -289,8 +289,8 @@ The Jimaku API has rate limits. If you see 429 errors, wait for the retry durati
 
 ### Linux
 
-- **Wayland (Hyprland/Sway)**: Window tracking uses compositor-specific commands. If `hyprctl` or `swaymsg` are not on `PATH`, tracking will fail silently.
+- **Wayland (Hyprland/Sway only)**: Native Wayland support is limited to Hyprland and Sway. Window tracking uses compositor-specific commands (`hyprctl` / `swaymsg`). If these are not on `PATH`, tracking will fail silently. Other Wayland compositors are not supported — both mpv and SubMiner must run under X11 or Xwayland instead.
-- **X11**: Requires `xdotool` and `xwininfo`. If missing, the overlay cannot track the mpv window position.
+- **X11 / Xwayland**: Requires `xdotool` and `xwininfo`. If missing, the overlay cannot track the mpv window position. This is the required backend for any Wayland compositor other than Hyprland or Sway — both mpv and SubMiner must be running under X11/Xwayland for window tracking to work.
 - **Mouse passthrough**: On Linux, Electron's mouse passthrough is unreliable. SubMiner keeps pointer events enabled, meaning you may need to toggle the overlay off to interact with mpv controls underneath.
 
 ### Hyprland
@@ -329,5 +329,4 @@ For more details, see the Hyprland docs on [global keybinds](https://wiki.hypr.l
 ### macOS
 
 - **Accessibility permission**: Required for window tracking. Grant it in System Settings > Privacy & Security > Accessibility.
-- **Font rendering**: macOS uses a 0.87x font compensation factor for subtitle alignment between mpv and the overlay. If text alignment looks off, adjust subtitle offset by right-click dragging subtitle text.
 - **Gatekeeper**: If macOS blocks SubMiner, right-click the app and select "Open" to bypass the warning, or remove the quarantine attribute: `xattr -d com.apple.quarantine /path/to/SubMiner.app`

docs-site/usage.md

@@ -37,7 +37,7 @@ Field names must match your Anki note type exactly (case-sensitive). See [Anki I
 There are several ways to use SubMiner:
 
 > [!TIP]
-> **New users: start with the `subminer` wrapper script** (or the **SubMiner mpv** shortcut on Windows). It handles mpv launch, IPC socket setup, and overlay lifecycle automatically so you don't need to configure anything in `mpv.conf`. You can add the mpv plugin later for in-player keybindings.
+> **New users: start with the `subminer` wrapper script** (or the **SubMiner mpv** shortcut on Windows). It handles mpv launch, IPC socket setup, and overlay lifecycle automatically so you don't need to configure anything in `mpv.conf`.
 
 | Approach                            | Use when                                                                                                                                            | How                                                                   |
 | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
@@ -85,8 +85,8 @@ subminer --args '--fs=opengl-hq --ytdl-format=bestvideo*+bestaudio/best' video.m
 # Options
 subminer -T video.mkv             # Disable texthooker server
 subminer -b x11 video.mkv         # Force X11 backend
-subminer video.mkv                # Uses mpv profile "subminer" by default
+subminer video.mkv                # No mpv profile passed by default
-subminer -p gpu-hq video.mkv      # Override mpv profile
+subminer -p gpu-hq video.mkv      # Use a specific mpv profile
 subminer jellyfin                 # Open Jellyfin setup window (subcommand form)
 subminer jellyfin -l --server http://127.0.0.1:8096 --username me --password 'secret'
 subminer jellyfin --logout        # Clear stored Jellyfin token/session data
@@ -157,7 +157,7 @@ You can use it three ways:
 & "C:\Program Files\SubMiner\SubMiner.exe" --launch-mpv "C:\Videos\episode 01.mkv"
 ```
 
-This flow requires `mpv.exe` to be discoverable. Leave `mpv.executablePath` blank to auto-discover from `PATH`, or set it to the full `mpv.exe` path if mpv is installed elsewhere. `SUBMINER_MPV_PATH` is still honored as a fallback. On Windows, `--launch-mpv` does not require an `mpv.conf` profile named `subminer`.
+This flow requires `mpv.exe` to be discoverable. Leave `mpv.executablePath` blank to auto-discover from `PATH`, or set it to the full `mpv.exe` path if mpv is installed elsewhere. `SUBMINER_MPV_PATH` is still honored as a fallback.
 
 ### Launcher Subcommands
 
@@ -172,7 +172,7 @@ This flow requires `mpv.exe` to be discoverable. Leave `mpv.executablePath` blan
 
 ### First-Run Setup
 
-SubMiner auto-opens the setup popup on fresh installs when launched with `--start` or `--background` and setup is incomplete.
+Setup popup appears on first launch, or when setup has not been completed.
 
 You can also open it manually:
 
@@ -262,7 +262,7 @@ Notes:
 - Secondary target languages come from `secondarySub.secondarySubLanguages` (defaults to English if unset).
 - Configure defaults in `$XDG_CONFIG_HOME/SubMiner/config.jsonc` (or `~/.config/SubMiner/config.jsonc`) under `youtube` and `secondarySub`.
 
-For local video files, SubMiner now uses those same config-driven language priorities after mpv finishes reporting subtitle tracks. That means mixed internal/external subtitle sets can correct an initial `sid=auto` guess and settle onto the expected primary and secondary tracks without manual cycling.
+For local video files, SubMiner uses the same config-driven language priorities to auto-select the primary and secondary subtitle tracks from internal and external subtitle sources.
 
 ## Controller Support