fix(docs): correct versioned nav links and local dev version routing (#74)

- Exits early with `SubMiner <version>` output, no app binary required
- Maps `-v` at root level without conflicting with `stats cleanup -v`
- Adds `version: boolean` to `Args` type and default args
- Documents flag in docs-site and adds changelog fragment

.github/workflows/docs-pages.yml

@@ -0,0 +1,76 @@
+name: Docs Pages
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+    paths:
+      - 'docs-site/**'
+      - 'scripts/docs-versioning.ts'
+      - 'scripts/build-versioned-docs.ts'
+      - '.github/workflows/docs-pages.yml'
+      - 'package.json'
+      - 'bun.lock'
+
+concurrency:
+  group: docs-pages-production
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    if: ${{ github.ref_type != 'tag' || !contains(github.ref_name, '-') }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Guard stable docs tag shape
+        id: tag_guard
+        if: github.ref_type == 'tag'
+        run: |
+          if [[ ! "${{ github.ref_name }}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::notice::Skipping non-stable docs tag ${{ github.ref_name }}"
+            echo "stable_tag=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "stable_tag=true" >> "$GITHUB_OUTPUT"
+
+      - name: Setup Bun
+        if: steps.tag_guard.outputs.stable_tag != 'false'
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Install dependencies
+        if: steps.tag_guard.outputs.stable_tag != 'false'
+        run: |
+          bun install --frozen-lockfile
+          cd docs-site && bun install --frozen-lockfile
+
+      - name: Cache versioned docs archives
+        if: steps.tag_guard.outputs.stable_tag != 'false'
+        uses: actions/cache@v4
+        with:
+          path: .tmp/docs-versioned-archive-cache
+          key: docs-versioned-archives-${{ runner.os }}-${{ hashFiles('docs-site/.vitepress/**', 'docs-site/public/assets/fonts/**', 'docs-site/package.json', 'docs-site/bun.lock', 'scripts/build-versioned-docs.ts', 'scripts/docs-versioning.ts') }}
+
+      - name: Test docs
+        if: steps.tag_guard.outputs.stable_tag != 'false'
+        run: bun run docs:test
+
+      - name: Build versioned docs
+        if: steps.tag_guard.outputs.stable_tag != 'false'
+        run: bun run docs:build:versioned
+
+      - name: Deploy docs to Cloudflare Pages
+        if: steps.tag_guard.outputs.stable_tag != 'false'
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy .tmp/docs-versioned-site --project-name "${{ vars.CLOUDFLARE_PAGES_PROJECT_NAME }}" --branch main

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help deps build build-launcher install build-linux build-macos build-macos-unsigned clean install-linux install-macos install-windows uninstall uninstall-linux uninstall-macos uninstall-windows print-dirs pretty lint ensure-bun generate-config generate-example-config dev-start dev-start-macos dev-watch dev-watch-macos dev-toggle dev-stop
+.PHONY: help deps build build-launcher install build-linux build-macos build-macos-unsigned clean install-linux install-macos install-windows uninstall uninstall-linux uninstall-macos uninstall-windows print-dirs pretty lint ensure-bun generate-config generate-example-config dev-start dev-start-macos dev-watch dev-watch-macos dev-toggle dev-stop docs-test docs-build docs-build-versioned docs-dev
 
 APP_NAME := subminer
 THEME_SOURCE := assets/themes/subminer.rasi
@@ -62,6 +62,10 @@ help:
 		"  dev-watch-macos  Start watch loop with forced macOS tracker backend" \
 		"  dev-toggle       Toggle overlay in a running local Electron app" \
 		"  dev-stop         Stop a running local Electron app" \
+		"  docs-test        Run docs tests" \
+		"  docs-build       Build the docs site" \
+		"  docs-build-versioned Build production versioned docs site" \
+		"  docs-dev         Start the docs dev server" \
 		"  install-linux    Install Linux wrapper/theme/app artifacts" \
 		"  install-macos    Install macOS wrapper/theme/app artifacts" \
 		"  install-windows  Print Windows packaging/install guidance" \
@@ -200,6 +204,18 @@ dev-toggle: ensure-bun
 dev-stop: ensure-bun
 	@bun run electron . --stop
 
+docs-test: ensure-bun
+	@bun run docs:test
+
+docs-build: ensure-bun
+	@bun run docs:build
+
+docs-build-versioned: ensure-bun
+	@bun run docs:build:versioned
+
+docs-dev: ensure-bun
+	@bun run docs:dev
+
 
 install-linux: build-launcher
 	@printf '%s\n' "[INFO] Installing Linux wrapper/theme artifacts"

app-updater.js

@@ -0,0 +1,193 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveMacAppBundlePath = resolveMacAppBundlePath;
+exports.isMacApplicationsFolderBundle = isMacApplicationsFolderBundle;
+exports.isKnownLinuxPackageManagedAppImage = isKnownLinuxPackageManagedAppImage;
+exports.isNativeUpdaterSupported = isNativeUpdaterSupported;
+exports.configureAutoUpdater = configureAutoUpdater;
+exports.createElectronAppUpdater = createElectronAppUpdater;
+const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_util_1 = require("node:util");
+const electron_updater_1 = require("electron-updater");
+const release_assets_1 = require("./release-assets");
+const updaterErrorListeners = new WeakMap();
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+function resolveMacAppBundlePath(execPath) {
+    const marker = '.app/Contents/MacOS/';
+    const markerIndex = execPath.indexOf(marker);
+    if (markerIndex < 0)
+        return null;
+    return execPath.slice(0, markerIndex + '.app'.length);
+}
+async function readMacCodeSignature(appBundlePath) {
+    try {
+        const result = await execFileAsync('/usr/bin/codesign', ['-dv', '--verbose=4', appBundlePath], {
+            encoding: 'utf8',
+        });
+        return `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
+    }
+    catch {
+        return null;
+    }
+}
+function realpathOrOriginal(filePath) {
+    try {
+        return (0, node_fs_1.realpathSync)(filePath);
+    }
+    catch {
+        return filePath;
+    }
+}
+function isSameOrInsideDirectory(parentPath, candidatePath) {
+    const relative = node_path_1.default.relative(parentPath, candidatePath);
+    return (relative === '' ||
+        (relative.length > 0 && !relative.startsWith('..') && !node_path_1.default.isAbsolute(relative)));
+}
+function isMacApplicationsFolderBundle(appBundlePath, homeDir = node_os_1.default.homedir()) {
+    const resolvedBundlePath = node_path_1.default.resolve(appBundlePath);
+    return (isSameOrInsideDirectory('/Applications', resolvedBundlePath) ||
+        isSameOrInsideDirectory(node_path_1.default.join(homeDir, 'Applications'), resolvedBundlePath));
+}
+function isKnownLinuxPackageManagedAppImage(appImagePath) {
+    return realpathOrOriginal(appImagePath) === '/opt/SubMiner/SubMiner.AppImage';
+}
+async function isNativeUpdaterSupported(options) {
+    if (!options.isPackaged) {
+        options.log?.('Skipping native updater because this build is not packaged.');
+        return false;
+    }
+    if (options.platform === 'linux') {
+        options.log?.('Skipping native Linux updater because Linux tray checks use GitHub release assets.');
+        return false;
+    }
+    if (options.platform !== 'darwin') {
+        options.log?.('Skipping native updater because this platform uses GitHub metadata checks.');
+        return false;
+    }
+    const appBundlePath = resolveMacAppBundlePath(options.execPath);
+    if (!appBundlePath) {
+        options.log?.('Skipping native macOS updater because the app bundle path could not be resolved.');
+        return false;
+    }
+    if (!isMacApplicationsFolderBundle(appBundlePath, options.homeDir)) {
+        options.log?.('Skipping native macOS updater because the app is not installed in an Applications folder.');
+        return false;
+    }
+    const signature = await (options.readCodeSignature ?? readMacCodeSignature)(appBundlePath);
+    if (!signature) {
+        options.log?.('Skipping native macOS updater because the app code signature could not be read.');
+        return false;
+    }
+    if (/Signature=adhoc\b/.test(signature) || /TeamIdentifier=not set\b/.test(signature)) {
+        options.log?.('Skipping native macOS updater because this build is ad-hoc signed.');
+        return false;
+    }
+    return true;
+}
+function configureAutoUpdater(updater, log = () => { }, channel = 'stable') {
+    updater.autoDownload = false;
+    // On macOS this avoids invoking Squirrel until the explicit restart/install step.
+    updater.autoInstallOnAppQuit = false;
+    updater.allowPrerelease = channel === 'prerelease';
+    updater.allowDowngrade = false;
+    updater.logger = {
+        info: () => { },
+        debug: () => { },
+        warn: (message) => log(message),
+        error: (message) => log(message),
+    };
+    const previousErrorListener = updaterErrorListeners.get(updater);
+    if (previousErrorListener) {
+        if (updater.off) {
+            updater.off('error', previousErrorListener);
+        }
+        else {
+            updater.removeListener?.('error', previousErrorListener);
+        }
+    }
+    if (updater.on) {
+        const errorListener = (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            log(`Updater error event: ${message}`);
+        };
+        updater.on('error', errorListener);
+        updaterErrorListeners.set(updater, errorListener);
+    }
+    return updater;
+}
+function createElectronAppUpdater(options) {
+    const getChannel = options.getChannel ?? (() => 'stable');
+    const updater = configureAutoUpdater(options.updater ?? electron_updater_1.autoUpdater, options.log, getChannel());
+    if (options.configureHttpExecutor) {
+        // electron-updater has no public executor hook; keep the macOS cURL override localized.
+        updater.httpExecutor = options.configureHttpExecutor();
+    }
+    if (options.disableDifferentialDownload !== undefined) {
+        updater.disableDifferentialDownload = options.disableDifferentialDownload;
+    }
+    let nativeUpdaterSupported = null;
+    async function getNativeUpdaterSupported() {
+        if (!options.isNativeUpdaterSupported)
+            return true;
+        if (nativeUpdaterSupported === null) {
+            nativeUpdaterSupported = Promise.resolve(options.isNativeUpdaterSupported());
+        }
+        return nativeUpdaterSupported;
+    }
+    return {
+        async checkForUpdates(channel) {
+            if (!options.isPackaged) {
+                return {
+                    available: false,
+                    version: options.currentVersion,
+                    canUpdate: false,
+                };
+            }
+            if (!(await getNativeUpdaterSupported())) {
+                options.log('Skipping native app update check because native updater is unsupported.');
+                return {
+                    available: false,
+                    version: options.currentVersion,
+                    canUpdate: false,
+                };
+            }
+            configureAutoUpdater(updater, options.log, channel ?? getChannel());
+            const result = await updater.checkForUpdates();
+            const version = result?.updateInfo?.version ?? options.currentVersion;
+            return {
+                available: (0, release_assets_1.compareSemverLike)(version, options.currentVersion) > 0,
+                version,
+                canUpdate: true,
+            };
+        },
+        async downloadUpdate() {
+            if (!options.isPackaged) {
+                options.log('Skipping app update download because this build is not packaged.');
+                return;
+            }
+            if (!(await getNativeUpdaterSupported())) {
+                options.log('Skipping app update download because native updater is unsupported.');
+                return;
+            }
+            await updater.downloadUpdate();
+        },
+        async quitAndInstall() {
+            if (!options.isPackaged) {
+                options.log('Skipping app update install because this build is not packaged.');
+                return;
+            }
+            if (!(await getNativeUpdaterSupported())) {
+                options.log('Skipping app update install because native updater is unsupported.');
+                return;
+            }
+            updater.quitAndInstall(false, true);
+        },
+    };
+}
+//# sourceMappingURL=app-updater.js.map

bun.lock

@@ -15,6 +15,7 @@
         "jsonc-parser": "^3.3.1",
         "koffi": "^2.15.6",
         "libsql": "^0.5.22",
+        "vscode-json-languageservice": "^5.7.2",
         "ws": "^8.19.0",
       },
       "devDependencies": {
@@ -188,6 +189,8 @@
 
     "@vladfrangu/async_event_emitter": ["@vladfrangu/async_event_emitter@2.4.7", "", {}, "sha512-Xfe6rpCTxSxfbswi/W/Pz7zp1WWSNn4A0eW4mLkQUewCrXXtMj31lCg+iQyTkh/CkusZSq9eDflu7tjEDXUY6g=="],
 
+    "@vscode/l10n": ["@vscode/l10n@0.0.18", "", {}, "sha512-KYSIHVmslkaCDyw013pphY+d7x1qV8IZupYfeIfzNA+nsaWHbn5uPuQRvdRFsa9zFzGeudPuoGoZ1Op4jrJXIQ=="],
+
     "@xhayper/discord-rpc": ["@xhayper/discord-rpc@1.3.3", "", { "dependencies": { "@discordjs/rest": "^2.6.1", "@vladfrangu/async_event_emitter": "^2.4.7", "discord-api-types": "^0.38.42", "ws": "^8.20.0" } }, "sha512-Ih48GHiua7TtZgKO+f0uZPhCeQqb84fY2qUys/oMh8UbUfiUkUJLVCmd/v2AK0/pV33euh0aqSXo7+9LiPSwGw=="],
 
     "@xmldom/xmldom": ["@xmldom/xmldom@0.8.12", "", {}, "sha512-9k/gHF6n/pAi/9tqr3m3aqkuiNosYTurLLUtc7xQ9sxB/wm7WPygCv8GYa6mS0fLJEHhqMC1ATYhz++U/lRHqg=="],
@@ -722,6 +725,14 @@
 
     "verror": ["verror@1.10.1", "", { "dependencies": { "assert-plus": "^1.0.0", "core-util-is": "1.0.2", "extsprintf": "^1.2.0" } }, "sha512-veufcmxri4e3XSrT0xwfUR7kguIkaxBeosDg00yDWhk49wdwkSUrvvsm7nc75e1PUyvIeZj6nS8VQRYz2/S4Xg=="],
 
+    "vscode-json-languageservice": ["vscode-json-languageservice@5.7.2", "", { "dependencies": { "@vscode/l10n": "^0.0.18", "jsonc-parser": "^3.3.1", "vscode-languageserver-textdocument": "^1.0.12", "vscode-languageserver-types": "^3.17.5", "vscode-uri": "^3.1.0" } }, "sha512-WtKRDtJfFEmLrgtu+ODexOHm/6/krRF0k6t+uvkKIKW1Jh9ZIyxZQwJJwB3qhrEgvAxa37zbUg+vn+UyUK/U2w=="],
+
+    "vscode-languageserver-textdocument": ["vscode-languageserver-textdocument@1.0.12", "", {}, "sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA=="],
+
+    "vscode-languageserver-types": ["vscode-languageserver-types@3.17.5", "", {}, "sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg=="],
+
+    "vscode-uri": ["vscode-uri@3.1.0", "", {}, "sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ=="],
+
     "wcwidth": ["wcwidth@1.0.1", "", { "dependencies": { "defaults": "^1.0.3" } }, "sha512-XHPEwS0q6TaxcvG85+8EYkbiCux2XtWG2mkc47Ng2A77BQu9+DqIOJldST4HgPkuea7dvKSj5VgX3P1d4rW8Tg=="],
 
     "which": ["which@5.0.0", "", { "dependencies": { "isexe": "^3.1.1" }, "bin": { "node-which": "bin/which.js" } }, "sha512-JEdGzHwwkrbWoGOlIHqQ5gtprKGOenpDHpxE9zVR1bWbOtYRyPPHMe9FaP6x61CmNaTThSkb0DAJte5jD+DmzQ=="],

changes/config-settings-window.md

@@ -0,0 +1,6 @@
+type: added
+area: config
+
+- Added a dedicated Configuration window with launcher entry points via `subminer --config` and `subminer config`.
+- Fixed the Configuration window preload so launcher-opened windows can initialize even when Electron sandboxing is active.
+- Kept config-window startup lightweight by skipping AniList token refresh and automatic update polling.

changes/docs-versioning.md

@@ -0,0 +1,4 @@
+type: docs
+area: docs
+
+- Published stable docs at the site root with current development docs under `/main/`.

changes/fix-versioned-doc-links.md

@@ -0,0 +1,4 @@
+type: fixed
+area: docs
+
+- Fixed versioned docs navigation so archived pages keep local links under the selected version, the version switcher no longer nests targets under the current archive path, local dev version routes serve warmed archive files instead of redirecting to production or falling through to VitePress 404s, and internal README files do not break archived builds.

changes/launcher-version-flag.md

@@ -0,0 +1,4 @@
+type: added
+area: launcher
+
+- Added `subminer --version` and `subminer -v` to print the installed SubMiner app version.

changes/native-updater-crash.md

@@ -1,4 +1,6 @@
 type: fixed
 area: updates
 
-- Kept signed macOS app updates on the native updater path while preventing eager Squirrel install checks before the user confirms restart.
+- Restored the standard macOS `electron-updater`/Squirrel update path and routed supplemental GitHub updater requests through Electron networking instead of Node fetch.
+- macOS update checks now skip local build-output apps outside Applications before touching Squirrel, and macOS tray checks no longer perform the supplemental GitHub asset lookup.
+- macOS `electron-updater` metadata and full ZIP downloads now use `/usr/bin/curl` under the hood to avoid the Electron network crash seen during tray update checks while preserving Squirrel installation.

config.example.jsonc

@@ -10,7 +10,7 @@
   // Overlay Auto-Start
   // When overlay connects to mpv, automatically show overlay and hide mpv subtitles.
   // ==========================================
-  "auto_start_overlay": false, // When overlay connects to mpv, automatically show overlay and hide mpv subtitles. Values: true | false
+  "auto_start_overlay": false, // Auto-start the subtitle overlay window when SubMiner launches. Values: true | false
 
   // ==========================================
   // Texthooker Server
@@ -18,7 +18,7 @@
   // ==========================================
   "texthooker": {
     "launchAtStartup": false, // Launch texthooker server automatically when SubMiner starts. Values: true | false
-    "openBrowser": false // Open browser setting. Values: true | false
+    "openBrowser": false // Open the texthooker page in the default browser when the server starts. Values: true | false
   }, // Configure texthooker startup launch and browser opening behavior.
 
   // ==========================================
@@ -174,24 +174,24 @@
   // Hot-reload: shortcut changes apply live and update the session help modal on reopen.
   // ==========================================
   "shortcuts": {
-    "toggleVisibleOverlayGlobal": "Alt+Shift+O", // Toggle visible overlay global setting.
-    "copySubtitle": "CommandOrControl+C", // Copy subtitle setting.
-    "copySubtitleMultiple": "CommandOrControl+Shift+C", // Copy subtitle multiple setting.
-    "updateLastCardFromClipboard": "CommandOrControl+V", // Update last card from clipboard setting.
-    "triggerFieldGrouping": "CommandOrControl+G", // Trigger field grouping setting.
-    "triggerSubsync": "Ctrl+Alt+S", // Trigger subsync setting.
-    "mineSentence": "CommandOrControl+S", // Mine sentence setting.
-    "mineSentenceMultiple": "CommandOrControl+Shift+S", // Mine sentence multiple setting.
+    "toggleVisibleOverlayGlobal": "Alt+Shift+O", // Global accelerator that toggles overlay visibility from anywhere on the system. Use null to disable.
+    "copySubtitle": "CommandOrControl+C", // Accelerator that copies the current subtitle line to the clipboard.
+    "copySubtitleMultiple": "CommandOrControl+Shift+C", // Accelerator that copies consecutive subtitle lines while the multi-copy window stays open.
+    "updateLastCardFromClipboard": "CommandOrControl+V", // Accelerator that updates the last mined Anki card using the current clipboard contents.
+    "triggerFieldGrouping": "CommandOrControl+G", // Accelerator that triggers Kiku field grouping on duplicate cards.
+    "triggerSubsync": "Ctrl+Alt+S", // Accelerator that triggers subsync against the active subtitle file.
+    "mineSentence": "CommandOrControl+S", // Accelerator that mines the current sentence as a new Anki card.
+    "mineSentenceMultiple": "CommandOrControl+Shift+S", // Accelerator that mines consecutive sentences while the multi-mine window stays open.
     "multiCopyTimeoutMs": 3000, // Timeout for multi-copy/mine modes.
-    "toggleSecondarySub": "CommandOrControl+Shift+V", // Toggle secondary sub setting.
-    "markAudioCard": "CommandOrControl+Shift+A", // Mark audio card setting.
-    "openCharacterDictionary": "CommandOrControl+Alt+A", // Open character dictionary setting.
-    "openRuntimeOptions": "CommandOrControl+Shift+O", // Open runtime options setting.
-    "openJimaku": "Ctrl+Shift+J", // Open jimaku setting.
-    "openSessionHelp": "CommandOrControl+Slash", // Open session help setting.
-    "openControllerSelect": "Alt+C", // Open controller select setting.
-    "openControllerDebug": "Alt+Shift+C", // Open controller debug setting.
-    "toggleSubtitleSidebar": "Backslash" // Toggle subtitle sidebar setting.
+    "toggleSecondarySub": "CommandOrControl+Shift+V", // Accelerator that toggles the secondary subtitle bar visibility.
+    "markAudioCard": "CommandOrControl+Shift+A", // Accelerator that marks the last mined card as an audio card.
+    "openCharacterDictionary": "CommandOrControl+Alt+A", // Accelerator that opens the character dictionary modal.
+    "openRuntimeOptions": "CommandOrControl+Shift+O", // Accelerator that opens the runtime options modal.
+    "openJimaku": "Ctrl+Shift+J", // Accelerator that opens the Jimaku subtitle search modal.
+    "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
+    "openControllerSelect": "Alt+C", // Accelerator that opens the controller selection and learn-mode modal.
+    "openControllerDebug": "Alt+Shift+C", // Accelerator that opens the controller debug modal with live axis/button readouts.
+    "toggleSubtitleSidebar": "Backslash" // Accelerator that toggles the subtitle sidebar visibility.
   }, // Overlay keyboard shortcuts. Set a shortcut to null to disable.
 
   // ==========================================
@@ -328,9 +328,9 @@
   // Hot-reload: defaultMode updates live while SubMiner is running.
   // ==========================================
   "secondarySub": {
-    "secondarySubLanguages": [], // Secondary sub languages setting.
-    "autoLoadSecondarySub": false, // Auto load secondary sub setting. Values: true | false
-    "defaultMode": "hover" // Default mode setting.
+    "secondarySubLanguages": [], // Language code priority list used to auto-select a secondary subtitle track when available.
+    "autoLoadSecondarySub": false, // Automatically load a matching secondary subtitle when the primary subtitle loads. Values: true | false
+    "defaultMode": "hover" // Default visibility mode for the secondary subtitle bar. Values: hidden | visible | hover
   }, // Dual subtitle track options.
 
   // ==========================================
@@ -339,9 +339,9 @@
   // ==========================================
   "subsync": {
     "defaultMode": "auto", // Subsync default mode. Values: auto | manual
-    "alass_path": "", // Alass path setting.
-    "ffsubsync_path": "", // Ffsubsync path setting.
-    "ffmpeg_path": "", // Ffmpeg path setting.
+    "alass_path": "", // Optional absolute path to the alass binary used by subsync. Leave empty to auto-discover from PATH.
+    "ffsubsync_path": "", // Optional absolute path to the ffsubsync binary used by subsync. Leave empty to auto-discover from PATH.
+    "ffmpeg_path": "", // Optional absolute path to the ffmpeg binary used by subsync. Leave empty to auto-discover from PATH.
     "replace": true // Replace the active subtitle file when sync completes. Values: true | false
   }, // Subsync engine and executable paths.
 
@@ -350,7 +350,7 @@
   // Initial vertical subtitle position from the bottom.
   // ==========================================
   "subtitlePosition": {
-    "yPercent": 10 // Y percent setting.
+    "yPercent": 10 // Vertical position of the subtitle overlay expressed as a percentage from the bottom of the screen.
   }, // Initial vertical subtitle position from the bottom.
 
   // ==========================================
@@ -454,9 +454,9 @@
     "enabled": false, // Enable shared OpenAI-compatible AI provider features. Values: true | false
     "apiKey": "", // Static API key for the shared OpenAI-compatible AI provider.
     "apiKeyCommand": "", // Shell command used to resolve the shared AI provider API key.
-    "model": "openai/gpt-4o-mini", // Model setting.
+    "model": "openai/gpt-4o-mini", // Default model identifier requested from the shared AI provider.
     "baseUrl": "https://openrouter.ai/api", // Base URL for the shared OpenAI-compatible AI provider.
-    "systemPrompt": "You are a translation engine. Return only the translated text with no explanations.", // System prompt setting.
+    "systemPrompt": "You are a translation engine. Return only the translated text with no explanations.", // Default system prompt sent with shared AI provider requests.
     "requestTimeoutMs": 15000 // Timeout in milliseconds for shared AI provider requests.
   }, // Canonical OpenAI-compatible provider transport settings shared by Anki and YouTube subtitle fixing.
 
@@ -469,7 +469,7 @@
   // ==========================================
   "ankiConnect": {
     "enabled": true, // Enable AnkiConnect integration. Values: true | false
-    "url": "http://127.0.0.1:8765", // Url setting.
+    "url": "http://127.0.0.1:8765", // Base URL of the AnkiConnect HTTP server.
     "pollingRate": 3000, // Polling interval in milliseconds.
     "proxy": {
       "enabled": true, // Enable local AnkiConnect-compatible proxy for push-based auto-enrichment. Values: true | false
@@ -482,11 +482,11 @@
     ], // Tags to add to cards mined or updated by SubMiner. Provide an empty array to disable automatic tagging.
     "fields": {
       "word": "Expression", // Card field for the mined word or expression text.
-      "audio": "ExpressionAudio", // Audio setting.
-      "image": "Picture", // Image setting.
-      "sentence": "Sentence", // Sentence setting.
-      "miscInfo": "MiscInfo", // Misc info setting.
-      "translation": "SelectionText" // Translation setting.
+      "audio": "ExpressionAudio", // Card field that receives generated sentence audio.
+      "image": "Picture", // Card field that receives the captured screenshot or animated image.
+      "sentence": "Sentence", // Card field that receives the source sentence text.
+      "miscInfo": "MiscInfo", // Card field that receives the miscellaneous info pattern (see ankiConnect.metadata.pattern).
+      "translation": "SelectionText" // Card field that receives the current selection or translated text.
     }, // Fields setting.
     "ai": {
       "enabled": false, // Enable AI provider usage for Anki translation/enrichment flows. Values: true | false
@@ -494,18 +494,18 @@
       "systemPrompt": "" // Optional system prompt override for Anki AI translation/enrichment flows.
     }, // Ai setting.
     "media": {
-      "generateAudio": true, // Generate audio setting. Values: true | false
-      "generateImage": true, // Generate image setting. Values: true | false
-      "imageType": "static", // Image type setting.
-      "imageFormat": "jpg", // Image format setting.
-      "imageQuality": 92, // Image quality setting.
-      "animatedFps": 10, // Animated fps setting.
-      "animatedMaxWidth": 640, // Animated max width setting.
-      "animatedCrf": 35, // Animated crf setting.
+      "generateAudio": true, // Generate sentence audio for mined cards. Values: true | false
+      "generateImage": true, // Generate screenshot or animated image for mined cards. Values: true | false
+      "imageType": "static", // Image capture type: "static" for a single still frame, "avif" for an animated AVIF. Values: static | avif
+      "imageFormat": "jpg", // Encoding format used when imageType is "static". Values: jpg | png | webp
+      "imageQuality": 92, // Quality (0-100) used for lossy static image encoders.
+      "animatedFps": 10, // Target frame rate for animated AVIF captures.
+      "animatedMaxWidth": 640, // Maximum width applied to animated AVIF captures.
+      "animatedCrf": 35, // Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.
       "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
-      "audioPadding": 0.5, // Audio padding setting.
-      "fallbackDuration": 3, // Fallback duration setting.
-      "maxMediaDuration": 30 // Max media duration setting.
+      "audioPadding": 0.5, // Seconds of padding appended to both ends of generated sentence audio.
+      "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
+      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.
     }, // Media setting.
     "knownWords": {
       "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
@@ -516,11 +516,11 @@
       "color": "#a6da95" // Color used for known-word highlights.
     }, // Known words setting.
     "behavior": {
-      "overwriteAudio": true, // Overwrite audio setting. Values: true | false
-      "overwriteImage": true, // Overwrite image setting. Values: true | false
-      "mediaInsertMode": "append", // Media insert mode setting.
-      "highlightWord": true, // Highlight word setting. Values: true | false
-      "notificationType": "osd", // Notification type setting.
+      "overwriteAudio": true, // When updating an existing card, overwrite the audio field instead of skipping it. Values: true | false
+      "overwriteImage": true, // When updating an existing card, overwrite the image field instead of skipping it. Values: true | false
+      "mediaInsertMode": "append", // Whether new media is appended after or prepended before existing field contents on update. Values: append | prepend
+      "highlightWord": true, // Bold the mined word inside the sentence field on the saved Anki card. Values: true | false
+      "notificationType": "osd", // Notification surface used to announce mining and update outcomes. Values: osd | system | both | none
       "autoUpdateNewCards": true // Automatically update newly added cards. Values: true | false
     }, // Behavior setting.
     "nPlusOne": {
@@ -528,16 +528,16 @@
       "nPlusOne": "#c6a0f6" // Color used for the single N+1 target token highlight.
     }, // N plus one setting.
     "metadata": {
-      "pattern": "[SubMiner] %f (%t)" // Pattern setting.
+      "pattern": "[SubMiner] %f (%t)" // Template used to render the miscInfo field. Placeholders include %f (filename) and %t (timestamp).
     }, // Metadata setting.
     "isLapis": {
-      "enabled": false, // Enabled setting. Values: true | false
-      "sentenceCardModel": "Japanese sentences" // Sentence card model setting.
+      "enabled": false, // Enable Lapis-specific mining behaviors and sentence card model targeting. Values: true | false
+      "sentenceCardModel": "Japanese sentences" // Note type name used by Lapis sentence cards.
     }, // Is lapis setting.
     "isKiku": {
-      "enabled": false, // Enabled setting. Values: true | false
+      "enabled": false, // Enable Kiku-specific mining behaviors (duplicate handling, field grouping). Values: true | false
       "fieldGrouping": "disabled", // Kiku duplicate-card field grouping mode. Values: auto | manual | disabled
-      "deleteDuplicateInAuto": true // Delete duplicate in auto setting. Values: true | false
+      "deleteDuplicateInAuto": true // When Kiku field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
     } // Is kiku setting.
   }, // Automatic Anki updates and media generation options.
 
@@ -546,7 +546,7 @@
   // Jimaku API configuration and defaults.
   // ==========================================
   "jimaku": {
-    "apiBaseUrl": "https://jimaku.cc", // Api base url setting.
+    "apiBaseUrl": "https://jimaku.cc", // Base URL of the Jimaku subtitle search API.
     "languagePreference": "ja", // Preferred language used in Jimaku search. Values: ja | en | none
     "maxEntryResults": 10 // Maximum Jimaku search results returned.
   }, // Jimaku API configuration and defaults.
@@ -618,9 +618,9 @@
     "serverUrl": "", // Base Jellyfin server URL (for example: http://localhost:8096).
     "recentServers": [], // Recently authenticated Jellyfin server URLs shown in setup.
     "username": "", // Default Jellyfin username used during CLI login.
-    "deviceId": "subminer", // Device id setting.
-    "clientName": "SubMiner", // Client name setting.
-    "clientVersion": "0.1.0", // Client version setting.
+    "deviceId": "subminer", // Stable device identifier sent on the Jellyfin authentication handshake; primarily internal.
+    "clientName": "SubMiner", // Client name sent on the Jellyfin authentication handshake; primarily internal.
+    "clientVersion": "0.1.0", // Client version sent on the Jellyfin authentication handshake; primarily internal.
     "defaultLibraryId": "", // Optional default Jellyfin library ID for item listing.
     "remoteControlEnabled": true, // Enable Jellyfin remote cast control mode. Values: true | false
     "remoteControlAutoConnect": true, // Auto-connect to the configured remote control target. Values: true | false

docs-site/.vitepress/config.ts

@@ -1,3 +1,7 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { extname, join, posix, resolve, sep } from 'node:path';
+import type { DefaultTheme, HeadConfig, TransformContext, UserConfig } from 'vitepress';
+
 const DOCS_HOSTNAME = 'https://docs.subminer.moe';
 const PLAUSIBLE_PROXY_HOSTNAME = 'https://worker.sudacode.com';
 const PLAUSIBLE_SITE_SCRIPT_PATH = '/js/pa-h28Pn9ppgTJRmiSJlyPT6.js';
@@ -7,20 +11,358 @@ const PLAUSIBLE_INIT_SCRIPT = [
   `plausible.init({ endpoint: '${PLAUSIBLE_ENDPOINT}' });`,
 ].join('\n');
 
-function pageToCanonicalHref(page: string): string | null {
+type DocsChannel = 'stable-root' | 'stable-archive' | 'main';
+
+type VersionManifest = {
+  latestStable: string;
+  channels: Array<{ label: string; path: string }>;
+  versions: Array<{ version: string; path: string }>;
+};
+
+const base = normalizeBase(process.env.SUBMINER_DOCS_BASE ?? '/');
+const outDir = process.env.SUBMINER_DOCS_OUT_DIR;
+const docsSourceDir = process.env.SUBMINER_DOCS_SOURCE_DIR ?? process.cwd();
+const localArchiveDir = resolve(
+  process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR ??
+    join(docsSourceDir, '..', '.tmp/docs-versioned-site'),
+);
+const channel = normalizeChannel(process.env.SUBMINER_DOCS_CHANNEL);
+const docsVersion = process.env.SUBMINER_DOCS_VERSION;
+const latestStable = process.env.SUBMINER_DOCS_LATEST_STABLE ?? 'v0.14.0';
+const versionManifest = parseVersionManifest(process.env.SUBMINER_DOCS_VERSION_MANIFEST);
+const versionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN ?? 'production';
+
+function normalizeBase(value: string): string {
+  if (!value || value === '/') return '/';
+  return `/${value.replace(/^\/+|\/+$/g, '')}/`;
+}
+
+function normalizeChannel(value: string | undefined): DocsChannel {
+  if (value === 'main' || value === 'stable-archive') return value;
+  return 'stable-root';
+}
+
+function parseVersionManifest(value: string | undefined): VersionManifest {
+  if (!value) {
+    return {
+      latestStable,
+      channels: [
+        { label: 'Latest stable', path: '/' },
+        { label: 'main', path: '/main/' },
+      ],
+      versions: [{ version: latestStable, path: `/v/${latestStable.replace(/^v/, '')}/` }],
+    };
+  }
+
+  return JSON.parse(value) as VersionManifest;
+}
+
+function withDocsBase(path: string): string {
+  if (/^[a-z]+:\/\//i.test(path)) return path;
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  if (base === '/') return normalizedPath;
+  return `${base.replace(/\/$/, '')}${normalizedPath}`;
+}
+
+function pageToRoute(page: string): string | null {
   if (page === '404.md') return null;
 
   const route = page
     .replace(/(^|\/)index\.md$/, '')
     .replace(/\.md$/, '')
     .replace(/\/$/, '');
-  return route ? `${DOCS_HOSTNAME}/${route}` : `${DOCS_HOSTNAME}/`;
+  return route ? `/${route}` : '/';
 }
 
-export default {
+function pageToCanonicalHref(page: string): string | null {
+  const route = pageToRoute(page);
+  if (!route) return null;
+
+  if (channel === 'main') {
+    return `${DOCS_HOSTNAME}${canonicalRouteWithBase(route)}`;
+  }
+
+  if (channel === 'stable-archive' && docsVersion !== latestStable) {
+    return `${DOCS_HOSTNAME}${canonicalRouteWithBase(route)}`;
+  }
+
+  return route === '/' ? `${DOCS_HOSTNAME}/` : `${DOCS_HOSTNAME}${route}`;
+}
+
+function canonicalRouteWithBase(route: string): string {
+  const routeWithBase = withDocsBase(route);
+  return route === '/' ? routeWithBase : routeWithBase.replace(/\/$/, '');
+}
+
+function transformPageHead({ page }: TransformContext): HeadConfig[] {
+  const href = pageToCanonicalHref(page);
+  const head: HeadConfig[] = href ? [['link', { rel: 'canonical', href }]] : [];
+
+  if (channel === 'main') {
+    head.push(['meta', { name: 'robots', content: 'noindex,follow' }]);
+  }
+
+  return head;
+}
+
+function linkToPagePath(link: string): string | null {
+  if (!link.startsWith('/') || link.startsWith('/v/') || link.startsWith('/main/')) {
+    return null;
+  }
+
+  const withoutHash = link.split('#')[0] ?? '/';
+  const withoutQuery = withoutHash.split('?')[0] ?? '/';
+  const route = withoutQuery.replace(/^\/+|\/+$/g, '');
+  return route ? `${route}.md` : 'index.md';
+}
+
+function hasPageForLink(link: string): boolean {
+  const pagePath = linkToPagePath(link);
+  if (!pagePath) return true;
+  return existsSync(join(docsSourceDir, pagePath));
+}
+
+function filterNav(items: DefaultTheme.NavItem[]): DefaultTheme.NavItem[] {
+  return items
+    .map((item) => {
+      if ('items' in item && item.items) {
+        return { ...item, items: filterNav(item.items as DefaultTheme.NavItem[]) };
+      }
+      if ('link' in item && item.link && !hasPageForLink(item.link)) {
+        return null;
+      }
+      return item;
+    })
+    .filter((item): item is DefaultTheme.NavItem => Boolean(item));
+}
+
+function filterSidebar(items: DefaultTheme.SidebarItem[]): DefaultTheme.SidebarItem[] {
+  return items
+    .map((item) => {
+      const filteredChildren = item.items ? filterSidebar(item.items) : undefined;
+      if (item.link && !hasPageForLink(item.link)) return null;
+      if (item.items && filteredChildren?.length === 0 && !item.link) return null;
+      return { ...item, items: filteredChildren };
+    })
+    .filter((item): item is DefaultTheme.SidebarItem => Boolean(item));
+}
+
+function versionSwitchLink(path: string): string {
+  if (/^[a-z]+:\/\//i.test(path)) return path;
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  if (versionLinkOrigin === 'local') return localVersionSwitchLink(normalizedPath);
+  return `${DOCS_HOSTNAME}${normalizedPath}`;
+}
+
+function localVersionSwitchLink(path: string): string {
+  if (base === '/') return path;
+
+  const basePath = base.replace(/\/$/, '');
+  const targetPath = path === '/' ? '/' : path.replace(/\/$/, '');
+  const relativePath = posix.relative(basePath, targetPath) || '.';
+
+  return path.endsWith('/') ? `${relativePath}/` : relativePath;
+}
+
+function shouldHandleLocalVersionRoute(pathname: string): boolean {
+  if (base !== '/' || channel !== 'stable-root') return false;
+  return /^\/main(?:\/|$)/.test(pathname) || /^\/v\/[^/]+(?:\/|$)/.test(pathname);
+}
+
+function contentTypeForPath(path: string): string {
+  switch (extname(path)) {
+    case '.css':
+      return 'text/css; charset=utf-8';
+    case '.gif':
+      return 'image/gif';
+    case '.ico':
+      return 'image/x-icon';
+    case '.jpg':
+    case '.jpeg':
+      return 'image/jpeg';
+    case '.js':
+    case '.mjs':
+      return 'text/javascript; charset=utf-8';
+    case '.json':
+    case '.jsonc':
+      return 'application/json; charset=utf-8';
+    case '.mp4':
+      return 'video/mp4';
+    case '.png':
+      return 'image/png';
+    case '.svg':
+      return 'image/svg+xml';
+    case '.ttf':
+      return 'font/ttf';
+    case '.webm':
+      return 'video/webm';
+    case '.woff':
+      return 'font/woff';
+    case '.woff2':
+      return 'font/woff2';
+    case '.xml':
+      return 'application/xml; charset=utf-8';
+    default:
+      return 'text/html; charset=utf-8';
+  }
+}
+
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function archiveFileForPathname(pathname: string): string | null {
+  if (!shouldHandleLocalVersionRoute(pathname)) return null;
+
+  const routePath = decodeURIComponent(pathname).replace(/^\/+/, '');
+  const filePath = resolve(localArchiveDir, routePath);
+  if (filePath !== localArchiveDir && !filePath.startsWith(`${localArchiveDir}${sep}`)) {
+    return null;
+  }
+
+  const candidates = pathname.endsWith('/')
+    ? [join(filePath, 'index.html')]
+    : extname(filePath)
+      ? [filePath]
+      : [`${filePath}.html`, join(filePath, 'index.html')];
+
+  return candidates.find(isFile) ?? null;
+}
+
+function serveLocalArchiveRoute(pathname: string, response: DevServerResponse): boolean {
+  if (versionLinkOrigin !== 'local') return false;
+
+  const filePath = archiveFileForPathname(pathname);
+  if (!filePath) return false;
+
+  response.statusCode = 200;
+  response.setHeader('Content-Type', contentTypeForPath(filePath));
+  response.end(readFileSync(filePath));
+  return true;
+}
+
+type DevServerResponse = {
+  statusCode: number;
+  setHeader(name: string, value: string): void;
+  end(chunk?: string | Uint8Array): void;
+};
+
+const versionItems = [
+  {
+    text: `Latest stable (${versionManifest.latestStable})`,
+    link: versionSwitchLink('/'),
+    target: '_self',
+    noIcon: true,
+  },
+  ...versionManifest.channels
+    .filter((entry) => entry.label !== 'Latest stable')
+    .map((entry) => ({
+      text: entry.label,
+      link: versionSwitchLink(entry.path),
+      target: '_self',
+      noIcon: true,
+    })),
+  ...versionManifest.versions.map((entry) => ({
+    text: entry.version,
+    link: versionSwitchLink(entry.path),
+    target: '_self',
+    noIcon: true,
+  })),
+];
+
+const nav: DefaultTheme.NavItem[] = [
+  { text: 'Home', link: '/' },
+  { text: 'Get Started', link: '/installation' },
+  { text: 'Mining', link: '/mining-workflow' },
+  { text: 'Configuration', link: '/configuration' },
+  { text: 'Changelog', link: '/changelog' },
+  { text: 'Troubleshooting', link: '/troubleshooting' },
+  { text: docsVersion ?? (channel === 'main' ? 'main' : latestStable), items: versionItems },
+];
+
+const sidebar: DefaultTheme.SidebarItem[] = [
+  {
+    text: 'Getting Started',
+    items: [
+      { text: 'Overview', link: '/' },
+      { text: 'Installation', link: '/installation' },
+      { text: 'Usage', link: '/usage' },
+      { text: 'Mining Workflow', link: '/mining-workflow' },
+      { text: 'Launcher Script', link: '/launcher-script' },
+    ],
+  },
+  {
+    text: 'Reference',
+    items: [
+      { text: 'Configuration', link: '/configuration' },
+      { text: 'Keyboard Shortcuts', link: '/shortcuts' },
+      { text: 'Subtitle Annotations', link: '/subtitle-annotations' },
+      { text: 'Subtitle Sidebar', link: '/subtitle-sidebar' },
+      { text: 'Immersion Tracking', link: '/immersion-tracking' },
+      { text: 'Troubleshooting', link: '/troubleshooting' },
+    ],
+  },
+  {
+    text: 'Integrations',
+    items: [
+      { text: 'MPV Plugin', link: '/mpv-plugin' },
+      { text: 'Anki', link: '/anki-integration' },
+      { text: 'Jellyfin', link: '/jellyfin-integration' },
+      { text: 'YouTube', link: '/youtube-integration' },
+      { text: 'Jimaku', link: '/jimaku-integration' },
+      { text: 'AniList', link: '/anilist-integration' },
+      { text: 'Character Dictionary', link: '/character-dictionary' },
+    ],
+  },
+  {
+    text: 'Development',
+    items: [
+      { text: 'Building & Testing', link: '/development' },
+      { text: 'Architecture', link: '/architecture' },
+      { text: 'IPC + Runtime Contracts', link: '/ipc-contracts' },
+      { text: 'WebSocket + Texthooker API', link: '/websocket-texthooker-api' },
+      { text: 'Changelog', link: '/changelog' },
+    ],
+  },
+];
+
+const config: UserConfig = {
   title: 'SubMiner Docs',
   description:
     'SubMiner: an MPV immersion-mining overlay with Yomitan and AnkiConnect integration.',
+  base,
+  ...(outDir ? { outDir } : {}),
+  vite: {
+    plugins: [
+      {
+        name: 'subminer-docs-local-version-redirects',
+        configureServer(server) {
+          server.middlewares.use((request, response, next) => {
+            const requestUrl = new URL(request.url ?? '/', 'http://localhost');
+            if (serveLocalArchiveRoute(requestUrl.pathname, response)) {
+              return;
+            }
+
+            if (!shouldHandleLocalVersionRoute(requestUrl.pathname)) {
+              next();
+              return;
+            }
+
+            response.statusCode = 302;
+            response.setHeader(
+              'Location',
+              `${DOCS_HOSTNAME}${requestUrl.pathname}${requestUrl.search}`,
+            );
+            response.end();
+          });
+        },
+      },
+    ],
+  },
   head: [
     ['link', { rel: 'preconnect', href: PLAUSIBLE_PROXY_HOSTNAME }],
     [
@@ -31,13 +373,13 @@ export default {
       },
     ],
     ['script', {}, PLAUSIBLE_INIT_SCRIPT],
-    ['link', { rel: 'icon', href: '/favicon.ico', sizes: 'any' }],
+    ['link', { rel: 'icon', href: withDocsBase('/favicon.ico'), sizes: 'any' }],
     [
       'link',
       {
         rel: 'icon',
         type: 'image/png',
-        href: '/favicon-32x32.png',
+        href: withDocsBase('/favicon-32x32.png'),
         sizes: '32x32',
       },
     ],
@@ -46,7 +388,7 @@ export default {
       {
         rel: 'icon',
         type: 'image/png',
-        href: '/favicon-16x16.png',
+        href: withDocsBase('/favicon-16x16.png'),
         sizes: '16x16',
       },
     ],
@@ -54,7 +396,7 @@ export default {
       'link',
       {
         rel: 'apple-touch-icon',
-        href: '/apple-touch-icon.png',
+        href: withDocsBase('/apple-touch-icon.png'),
         sizes: '180x180',
       },
     ],
@@ -70,12 +412,9 @@ export default {
       );
     },
   },
-  transformHead({ page }) {
-    const href = pageToCanonicalHref(page);
-    return href ? [['link', { rel: 'canonical', href }]] : [];
-  },
+  transformHead: transformPageHead,
   lastUpdated: true,
-  srcExclude: ['subagents/**'],
+  srcExclude: ['subagents/**', 'README.md'],
   markdown: {
     theme: {
       light: 'catppuccin-latte',
@@ -88,59 +427,8 @@ export default {
       dark: '/assets/SubMiner.png',
     },
     siteTitle: 'SubMiner Docs',
-    nav: [
-      { text: 'Home', link: '/' },
-      { text: 'Get Started', link: '/installation' },
-      { text: 'Mining', link: '/mining-workflow' },
-      { text: 'Configuration', link: '/configuration' },
-      { text: 'Changelog', link: '/changelog' },
-      { text: 'Troubleshooting', link: '/troubleshooting' },
-    ],
-    sidebar: [
-      {
-        text: 'Getting Started',
-        items: [
-          { text: 'Overview', link: '/' },
-          { text: 'Installation', link: '/installation' },
-          { text: 'Usage', link: '/usage' },
-          { text: 'Mining Workflow', link: '/mining-workflow' },
-          { text: 'Launcher Script', link: '/launcher-script' },
-        ],
-      },
-      {
-        text: 'Reference',
-        items: [
-          { text: 'Configuration', link: '/configuration' },
-          { text: 'Keyboard Shortcuts', link: '/shortcuts' },
-          { text: 'Subtitle Annotations', link: '/subtitle-annotations' },
-          { text: 'Subtitle Sidebar', link: '/subtitle-sidebar' },
-          { text: 'Immersion Tracking', link: '/immersion-tracking' },
-          { text: 'Troubleshooting', link: '/troubleshooting' },
-        ],
-      },
-      {
-        text: 'Integrations',
-        items: [
-          { text: 'MPV Plugin', link: '/mpv-plugin' },
-          { text: 'Anki', link: '/anki-integration' },
-          { text: 'Jellyfin', link: '/jellyfin-integration' },
-          { text: 'YouTube', link: '/youtube-integration' },
-          { text: 'Jimaku', link: '/jimaku-integration' },
-          { text: 'AniList', link: '/anilist-integration' },
-          { text: 'Character Dictionary', link: '/character-dictionary' },
-        ],
-      },
-      {
-        text: 'Development',
-        items: [
-          { text: 'Building & Testing', link: '/development' },
-          { text: 'Architecture', link: '/architecture' },
-          { text: 'IPC + Runtime Contracts', link: '/ipc-contracts' },
-          { text: 'WebSocket + Texthooker API', link: '/websocket-texthooker-api' },
-          { text: 'Changelog', link: '/changelog' },
-        ],
-      },
-    ],
+    nav: filterNav(nav),
+    sidebar: filterSidebar(sidebar),
     search: {
       provider: 'local',
     },
@@ -159,3 +447,5 @@ export default {
     socialLinks: [{ icon: 'github', link: 'https://github.com/ksyasuda/SubMiner' }],
   },
 };
+
+export default config;

docs-site/.vitepress/theme/components/StatusLine.vue

@@ -1,6 +1,7 @@
 <script setup>
 import { useRoute, useData } from 'vitepress';
 import { computed } from 'vue';
+import { formatStatusLineFilePath } from '../status-line';
 
 const route = useRoute();
 const { page, frontmatter } = useData();
@@ -12,8 +13,7 @@ const mode = computed(() => {
 });
 
 const filePath = computed(() => {
-  const path = route.path;
-  return path === '/' ? 'index.md' : `${path.replace(/^\//, '')}.md`;
+  return formatStatusLineFilePath(route.path);
 });
 
 const section = computed(() => {

docs-site/.vitepress/theme/status-line.test.ts

@@ -0,0 +1,16 @@
+import { expect, test } from 'bun:test';
+import { formatStatusLineFilePath } from './status-line';
+
+test('status line file path formats root home as index markdown', () => {
+  expect(formatStatusLineFilePath('/')).toBe('index.md');
+});
+
+test('status line file path formats version archive home without trailing slash', () => {
+  expect(formatStatusLineFilePath('/v/0.12.0/')).toBe('v/0.12.0.md');
+});
+
+test('status line file path keeps normal docs routes as markdown files', () => {
+  expect(formatStatusLineFilePath('/v/0.12.0/configuration')).toBe(
+    'v/0.12.0/configuration.md',
+  );
+});

docs-site/.vitepress/theme/status-line.ts

@@ -0,0 +1,4 @@
+export function formatStatusLineFilePath(routePath: string): string {
+  if (routePath === '/') return 'index.md';
+  return `${routePath.replace(/^\/|\/$/g, '')}.md`;
+}

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

@@ -5,7 +5,7 @@
 
 @font-face {
   font-family: 'M PLUS 1';
-  src: url('/assets/fonts/Mplus1-Medium.ttf') format('truetype');
+  src: url('../../public/assets/fonts/Mplus1-Medium.ttf') format('truetype');
   font-weight: 500;
   font-style: normal;
   font-display: swap;
@@ -13,7 +13,7 @@
 
 @font-face {
   font-family: 'Manrope Default';
-  src: url('/assets/fonts/manrope-latin-600-normal.ttf') format('truetype');
+  src: url('../../public/assets/fonts/manrope-latin-600-normal.ttf') format('truetype');
   font-weight: 600;
   font-style: normal;
   font-display: swap;

docs-site/README.md

@@ -30,9 +30,16 @@ bun run docs:dev
 ## Cloudflare Pages
 
 - Git repo: `ksyasuda/SubMiner`
-- Root directory: `docs-site`
-- Build command: `bun run docs:build`
-- Build output directory: `.vitepress/dist`
-- Build watch paths: `docs-site/*`
+- Production branch: `main`
+- Automatic production and preview deployments: disabled
+- Custom domain: `docs.subminer.moe` attached to Production
+- Deployment path: GitHub Actions direct upload with Wrangler
 
-Cloudflare Pages watch paths use a single `*` wildcard for monorepo subdirectories. `docs-site/*` matches nested files under the docs site; `docs-site/**` can cause docs-only pushes to be skipped.
+The public docs root is stable-only:
+
+- `/` serves the latest stable release docs.
+- `/main/` serves development docs from `main` and is marked `noindex,follow`.
+- `/v/<version>/` serves stable release archives.
+- Prerelease tags do not update the docs site.
+
+Keep Cloudflare Git auto-deploy disabled. The production deploy is `.github/workflows/docs-pages.yml`, which uploads `.tmp/docs-versioned-site` with `--branch main` so tag-triggered runs update Production instead of creating preview deployments.

docs-site/configuration.md

@@ -4,6 +4,10 @@ outline: [2, 3]
 
 # Configuration
 
+<script setup>
+import { withBase } from 'vitepress';
+</script>
+
 Settings are stored in `$XDG_CONFIG_HOME/SubMiner/config.jsonc` (or `~/.config/SubMiner/config.jsonc` when `XDG_CONFIG_HOME` is unset).
 On Windows, the default path is `%APPDATA%\SubMiner\config.jsonc`.
 When both files exist, SubMiner prefers `config.jsonc` over `config.json`.
@@ -59,6 +63,28 @@ For valid JSON/JSONC with invalid option values, SubMiner uses warn-and-fallback
 
 On macOS, these validation warnings also open a native dialog with full details (desktop notification banners can truncate long messages).
 
+### Configuration Window
+
+SubMiner also includes a dedicated **Configuration** window from the tray menu, the app `--config` flag, or launcher commands such as `subminer --config` and `subminer config`. It groups settings by workflow instead of mirroring the raw config-file shape:
+
+- Viewing
+- Mining & Anki
+- Playback & Sources
+- Input
+- Integrations
+- Tracking & App
+- Advanced
+
+Each field still writes to its current `config.jsonc` path. For example, subtitle hover pause appears under **Viewing** / playback behavior, but saves to `subtitleStyle.autoPauseVideoOnHover`.
+
+The settings window preserves existing JSONC comments, trailing commas, unrelated keys, and unsupported legacy options. Resetting a field removes the explicit config path so the built-in default applies.
+
+Secret fields do not display stored values. They show whether a value is configured; entering a new value writes it, and reset clears the explicit path. Prefer command-based secret options such as `ai.apiKeyCommand` when available.
+
+Some compatibility-only or ignored legacy keys are intentionally hidden from the normal field list, including legacy top-level Anki migration fields, old N+1 aliases, the removed YouTube subtitle-generation primary-language key, `anilist.characterDictionary.refreshTtlHours`, `anilist.characterDictionary.evictionPolicy`, `jellyfin.accessToken`, `jellyfin.userId`, and normal editing for `controller.buttonIndices`. Advanced/raw JSON editing remains the escape hatch for unsupported or legacy keys.
+
+Saving validates the candidate config before writing. Live-reloadable changes are applied immediately; other changes return a restart-required banner in the window.
+
 ### Hot-Reload Behavior
 
 SubMiner watches the active config file (`config.jsonc` or `config.json`) while running and applies supported updates automatically.
@@ -1022,12 +1048,12 @@ To refresh roughly once per day, set:
 `deleteDuplicateInAuto` controls whether `auto` mode deletes the duplicate after merge (default: `true`). In `manual` mode, the popup asks each time whether to delete the duplicate.
 When the manual merge popup opens, SubMiner pauses playback and closes any open Yomitan popup first so the merge flow can take focus.
 
-<video controls playsinline preload="metadata" poster="/assets/kiku-integration-poster.jpg" style="width: 100%; max-width: 960px;">
-  <source :src="'/assets/kiku-integration.webm'" type="video/webm" />
+<video controls playsinline preload="metadata" :poster="withBase('/assets/kiku-integration-poster.jpg')" style="width: 100%; max-width: 960px;">
+  <source :src="withBase('/assets/kiku-integration.webm')" type="video/webm" />
   Your browser does not support the video tag.
 </video>
 
-<a :href="'/assets/kiku-integration.webm'" target="_blank" rel="noreferrer">Open demo in a new tab</a>
+<a :href="withBase('/assets/kiku-integration.webm')" target="_blank" rel="noreferrer">Open demo in a new tab</a>
 
 ## External Integrations
 
@@ -1229,7 +1255,7 @@ Jellyfin integration is optional and disabled by default. When enabled, SubMiner
 | `directPlayContainers`     | string[]        | Container allowlist for direct play decisions                                                                |
 | `transcodeVideoCodec`      | string          | Preferred transcode video codec fallback (default: `h264`)                                                   |
 
-Jellyfin auth session (`accessToken` + `userId`) is stored in local encrypted storage after login/setup.
+Jellyfin auth session (`accessToken` + `userId`) is stored in local encrypted storage after login/setup. The legacy `jellyfin.accessToken` and `jellyfin.userId` config keys are not resolver-backed settings in the current runtime and are hidden from the configuration window.
 
 - On Linux, token storage defaults to `gnome-libsecret` for `safeStorage`. Override with `--password-store=<backend>` on launcher/app invocations when needed.
 

docs-site/demos.md

@@ -3,6 +3,8 @@
 Short recordings of SubMiner's key features and integrations from real playback sessions.
 
 <script setup>
+import { withBase } from 'vitepress';
+
 const v = '20260301-1';
 </script>
 
@@ -10,11 +12,11 @@ const v = '20260301-1';
 
 Mine vocabulary cards from Yomitan or directly from subtitle lines. SubMiner automatically attaches the sentence, a timing-accurate audio clip, a screenshot, and a translation.
 
-<video controls playsinline preload="metadata" :poster="`/assets/minecard-poster.jpg?v=${demoAssetVersion}`">
-  <source :src="`/assets/minecard.webm?v=${demoAssetVersion}`" type="video/webm" />
-  <source :src="`/assets/minecard.mp4?v=${demoAssetVersion}`" type="video/mp4" />
-  <a :href="`/assets/minecard.webm?v=${demoAssetVersion}`" target="_blank" rel="noreferrer">
-    <img :src="`/assets/minecard.webp?v=${demoAssetVersion}`" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />
+<video controls playsinline preload="metadata" :poster="withBase(`/assets/minecard-poster.jpg?v=${v}`)">
+  <source :src="withBase(`/assets/minecard.webm?v=${v}`)" type="video/webm" />
+  <source :src="withBase(`/assets/minecard.mp4?v=${v}`)" type="video/mp4" />
+  <a :href="withBase(`/assets/minecard.webm?v=${v}`)" target="_blank" rel="noreferrer">
+    <img :src="withBase(`/assets/minecard.webp?v=${v}`)" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />
   </a>
 </video>
 
@@ -25,9 +27,9 @@ Mine vocabulary cards from Yomitan or directly from subtitle lines. SubMiner aut
 
 Search and download subtitles from Jimaku, then automatically synchronize them with alass or ffsubsync — all from within SubMiner.
 
-<!-- <video controls playsinline preload="metadata" :poster="`/assets/demos/subtitle-sync-poster.jpg?v=${v}`">
-  <source :src="`/assets/demos/subtitle-sync.webm?v=${v}`" type="video/webm" />
-  <source :src="`/assets/demos/subtitle-sync.mp4?v=${v}`" type="video/mp4" />
+<!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/subtitle-sync-poster.jpg?v=${v}`)">
+  <source :src="withBase(`/assets/demos/subtitle-sync.webm?v=${v}`)" type="video/webm" />
+  <source :src="withBase(`/assets/demos/subtitle-sync.mp4?v=${v}`)" type="video/mp4" />
 </video> -->
 
 ::: info VIDEO COMING SOON
@@ -37,9 +39,9 @@ Search and download subtitles from Jimaku, then automatically synchronize them w
 
 Browse your Jellyfin library, cast to devices, and launch playback directly from SubMiner. Watch progress syncs back to your Jellyfin server.
 
-<!-- <video controls playsinline preload="metadata" :poster="`/assets/demos/jellyfin-poster.jpg?v=${v}`">
-  <source :src="`/assets/demos/jellyfin.webm?v=${v}`" type="video/webm" />
-  <source :src="`/assets/demos/jellyfin.mp4?v=${v}`" type="video/mp4" />
+<!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/jellyfin-poster.jpg?v=${v}`)">
+  <source :src="withBase(`/assets/demos/jellyfin.webm?v=${v}`)" type="video/webm" />
+  <source :src="withBase(`/assets/demos/jellyfin.mp4?v=${v}`)" type="video/mp4" />
 </video> -->
 
 ::: info VIDEO COMING SOON
@@ -49,9 +51,9 @@ Browse your Jellyfin library, cast to devices, and launch playback directly from
 
 Open subtitles in an external texthooker page for use with browser-based tools and extensions alongside the overlay.
 
-<!-- <video controls playsinline preload="metadata" :poster="`/assets/demos/texthooker-poster.jpg?v=${v}`">
-  <source :src="`/assets/demos/texthooker.webm?v=${v}`" type="video/webm" />
-  <source :src="`/assets/demos/texthooker.mp4?v=${v}`" type="video/mp4" />
+<!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/texthooker-poster.jpg?v=${v}`)">
+  <source :src="withBase(`/assets/demos/texthooker.webm?v=${v}`)" type="video/webm" />
+  <source :src="withBase(`/assets/demos/texthooker.mp4?v=${v}`)" type="video/mp4" />
 </video> -->
 
 ::: info VIDEO COMING SOON

docs-site/development.md

@@ -113,6 +113,14 @@ bun run docs:test
 bun run docs:build
 ```
 
+For production docs routing, run the versioned build:
+
+```bash
+bun run docs:build:versioned
+```
+
+The versioned build writes `.tmp/docs-versioned-site` with latest stable docs at `/`, development docs at `/main/`, and stable archives under `/v/<version>/`. Prerelease tags are skipped. Public assets from `docs-site/public/assets` are shared from root `/assets/` so large demo media is not duplicated into every version archive; generated VitePress CSS and JS assets stay under each version route. Stale `.tmp/docs-versioned-archive-cache` generations are pruned after a successful build, and intermediate `.tmp/docs-versioned-build` workspaces are removed.
+
 Focused commands:
 
 ```bash
@@ -154,6 +162,7 @@ bun run format:check:src
 - `make pretty` runs the maintained Prettier allowlist only (`format:src`).
 - `bun run format:check:src` checks the same scoped set without writing changes.
 - `bun run format` remains the broad repo-wide Prettier command; use it intentionally.
+
 ## Config Generation
 
 ```bash
@@ -197,17 +206,17 @@ Use Cloudflare's single `*` wildcard syntax for watch paths. `docs-site/*` cover
 
 Run `make help` for a full list of targets. Key ones:
 
-| Target                 | Description                                                      |
-| ---------------------- | ---------------------------------------------------------------- |
-| `make build`           | Build platform package for detected OS                           |
-| `make build-launcher`  | Generate Bun launcher wrapper at `dist/launcher/subminer`        |
-| `make install`         | Install platform artifacts (wrapper, theme, AppImage/app bundle) |
-| `make deps`            | Install JS dependencies (root + stats + texthooker-ui)           |
-| `make pretty`          | Run scoped Prettier formatting for maintained source/config files |
-| `make generate-config` | Generate default config from centralized registry                |
-| `make build-linux`     | Convenience wrapper for Linux packaging                          |
-| `make build-macos`     | Convenience wrapper for signed macOS packaging                   |
-| `make build-macos-unsigned` | Convenience wrapper for unsigned macOS packaging            |
+| Target                      | Description                                                       |
+| --------------------------- | ----------------------------------------------------------------- |
+| `make build`                | Build platform package for detected OS                            |
+| `make build-launcher`       | Generate Bun launcher wrapper at `dist/launcher/subminer`         |
+| `make install`              | Install platform artifacts (wrapper, theme, AppImage/app bundle)  |
+| `make deps`                 | Install JS dependencies (root + stats + texthooker-ui)            |
+| `make pretty`               | Run scoped Prettier formatting for maintained source/config files |
+| `make generate-config`      | Generate default config from centralized registry                 |
+| `make build-linux`          | Convenience wrapper for Linux packaging                           |
+| `make build-macos`          | Convenience wrapper for signed macOS packaging                    |
+| `make build-macos-unsigned` | Convenience wrapper for unsigned macOS packaging                  |
 
 ## Contributor Notes
 

docs-site/docs-sync.test.ts

@@ -8,6 +8,7 @@ const installationContents = readFileSync(new URL('./installation.md', import.me
 const mpvPluginContents = readFileSync(new URL('./mpv-plugin.md', import.meta.url), 'utf8');
 const developmentContents = readFileSync(new URL('./development.md', import.meta.url), 'utf8');
 const changelogContents = readFileSync(new URL('./changelog.md', import.meta.url), 'utf8');
+const docsPackageContents = readFileSync(new URL('./package.json', import.meta.url), 'utf8');
 const ankiIntegrationContents = readFileSync(
   new URL('./anki-integration.md', import.meta.url),
   'utf8',
@@ -37,13 +38,13 @@ test('docs reflect current launcher and release surfaces', () => {
 
   expect(mpvPluginContents).toContain('\\\\.\\pipe\\subminer-socket');
 
-  expect(readmeContents).toContain('Root directory: `docs-site`');
-  expect(readmeContents).toContain('Build output directory: `.vitepress/dist`');
-  expect(readmeContents).toContain('Build watch paths: `docs-site/*`');
+  expect(readmeContents).toContain('Automatic production and preview deployments: disabled');
+  expect(readmeContents).toContain('/main/');
+  expect(readmeContents).toContain('GitHub Actions direct upload with Wrangler');
   expect(developmentContents).not.toContain('../subminer-docs');
   expect(developmentContents).toContain('bun run docs:build');
   expect(developmentContents).toContain('bun run docs:test');
-  expect(developmentContents).toContain('Build watch paths: `docs-site/*`');
+  expect(developmentContents).toContain('bun run docs:build:versioned');
   expect(developmentContents).not.toContain('test:subtitle:dist');
   expect(developmentContents).toContain('bun run build:win');
 
@@ -57,6 +58,15 @@ test('docs reflect current launcher and release surfaces', () => {
   expect(changelogContents).toContain('v0.5.1 (2026-03-09)');
 });
 
+test('docs dev server links version navigation to local dev routes', () => {
+  expect(docsPackageContents).toContain('scripts/build-versioned-docs.ts');
+  expect(docsPackageContents).toContain(
+    'SUBMINER_DOCS_VERSION_LINK_ORIGIN=local bun run ../scripts/build-versioned-docs.ts',
+  );
+  expect(docsPackageContents).toContain('SUBMINER_DOCS_VERSION_LINK_ORIGIN=local');
+  expect(docsPackageContents).toContain('SUBMINER_DOCS_VERSION_MANIFEST');
+});
+
 test('docs changelog keeps the current minor release headings aligned with the root changelog', () => {
   const docsHeadings = extractCurrentMinorHeadings(changelogContents);
   expect(docsHeadings.length).toBeGreaterThan(0);

docs-site/index.assets.test.ts

@@ -7,18 +7,18 @@ const docsIndexContents = readFileSync(docsIndexPath, 'utf8');
 test('docs demo media uses shared cache-busting asset version token', () => {
   expect(docsIndexContents).toMatch(/const demoAssetVersion = ['"][^'"]+['"]/);
   expect(docsIndexContents).toContain(
-    ':poster="`/assets/minecard-poster.jpg?v=${demoAssetVersion}`"',
+    ':poster="withBase(`/assets/minecard-poster.jpg?v=${demoAssetVersion}`)"',
   );
   expect(docsIndexContents).toContain(
-    '<source :src="`/assets/minecard.webm?v=${demoAssetVersion}`" type="video/webm" />',
+    '<source :src="withBase(`/assets/minecard.webm?v=${demoAssetVersion}`)" type="video/webm" />',
   );
   expect(docsIndexContents).toContain(
-    '<source :src="`/assets/minecard.mp4?v=${demoAssetVersion}`" type="video/mp4" />',
+    '<source :src="withBase(`/assets/minecard.mp4?v=${demoAssetVersion}`)" type="video/mp4" />',
   );
   expect(docsIndexContents).toContain(
-    '<a :href="`/assets/minecard.webm?v=${demoAssetVersion}`" target="_blank" rel="noreferrer">',
+    '<a :href="withBase(`/assets/minecard.webm?v=${demoAssetVersion}`)" target="_blank" rel="noreferrer">',
   );
   expect(docsIndexContents).toContain(
-    '<img :src="`/assets/minecard.webp?v=${demoAssetVersion}`" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />',
+    '<img :src="withBase(`/assets/minecard.webp?v=${demoAssetVersion}`)" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />',
   );
 });

docs-site/index.md

@@ -86,6 +86,8 @@ features:
 ---
 
 <script setup>
+import { withBase } from 'vitepress';
+
 const demoAssetVersion = '20260223-2';
 </script>
 
@@ -135,11 +137,11 @@ const demoAssetVersion = '20260223-2';
         <span class="demo-window__dot"></span>
         <span class="demo-window__title">subminer -- playback</span>
       </div>
-      <video controls playsinline preload="metadata" :poster="`/assets/minecard-poster.jpg?v=${demoAssetVersion}`">
-        <source :src="`/assets/minecard.webm?v=${demoAssetVersion}`" type="video/webm" />
-        <source :src="`/assets/minecard.mp4?v=${demoAssetVersion}`" type="video/mp4" />
-        <a :href="`/assets/minecard.webm?v=${demoAssetVersion}`" target="_blank" rel="noreferrer">
-          <img :src="`/assets/minecard.webp?v=${demoAssetVersion}`" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />
+      <video controls playsinline preload="metadata" :poster="withBase(`/assets/minecard-poster.jpg?v=${demoAssetVersion}`)">
+        <source :src="withBase(`/assets/minecard.webm?v=${demoAssetVersion}`)" type="video/webm" />
+        <source :src="withBase(`/assets/minecard.mp4?v=${demoAssetVersion}`)" type="video/mp4" />
+        <a :href="withBase(`/assets/minecard.webm?v=${demoAssetVersion}`)" target="_blank" rel="noreferrer">
+          <img :src="withBase(`/assets/minecard.webp?v=${demoAssetVersion}`)" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />
         </a>
       </video>
     </div>

docs-site/installation.md

@@ -174,9 +174,9 @@ subminer -u
 subminer --update
 ```
 
-SubMiner verifies launcher and Linux rofi theme downloads against `SHA256SUMS.txt`. If the launcher is installed in a protected path such as `/usr/local/bin/subminer`, SubMiner does not elevate itself; it shows the exact `sudo curl ... && sudo chmod +x ...` command to run instead.
+SubMiner verifies AppImage, launcher, and Linux rofi theme downloads against `SHA256SUMS.txt`. If the AppImage or launcher is installed in a protected path, SubMiner does not elevate itself; it shows the exact sudo command to run instead.
 
-On Linux, `subminer -u` performs this update from the launcher process, so it does not need to start or IPC into the tray app.
+On Linux, `subminer -u` performs the AppImage update from the launcher process, so it does not need to start or IPC into the tray app.
 
 ### From Source
 
@@ -206,6 +206,8 @@ Download the **DMG** artifact from [GitHub Releases](https://github.com/ksyasuda
 
 A **ZIP** artifact is also available as a fallback — unzip and drag `SubMiner.app` into `/Applications`.
 
+After the first updater-enabled install, tray update checks can update the macOS app automatically through Electron's standard macOS updater. The updater uses the release ZIP as its payload even when the DMG remains the normal first-install artifact.
+
 Install dependencies using Homebrew:
 
 ```bash

docs-site/launcher-script.md

@@ -99,6 +99,7 @@ Use `subminer <subcommand> -h` for command-specific help.
 | `-r, --recursive`     | Search directories recursively                                       |
 | `-R, --rofi`          | Use rofi instead of fzf                                              |
 | `--setup`             | Open first-run setup popup manually                                  |
+| `-v, --version`       | Print installed SubMiner version                                     |
 | `-u, --update`        | Check for SubMiner updates and update the app/launcher when possible |
 | `--start`             | Explicitly start overlay after mpv launches                          |
 | `-S, --start-overlay` | Explicitly start overlay after mpv launches                          |

docs-site/package.json

@@ -5,10 +5,10 @@
   "description": "In-repo VitePress documentation site for SubMiner",
   "packageManager": "bun@1.3.5",
   "scripts": {
-    "docs:dev": "VITE_EXTRA_EXTENSIONS=jsonc vitepress dev --host 0.0.0.0 --port 5173 --strictPort",
+    "docs:dev": "SUBMINER_DOCS_VERSION_LINK_ORIGIN=local bun run ../scripts/build-versioned-docs.ts && SUBMINER_DOCS_VERSION_LINK_ORIGIN=local SUBMINER_DOCS_VERSION_MANIFEST=\"$(bun run ../scripts/print-docs-version-manifest.ts)\" VITE_EXTRA_EXTENSIONS=jsonc vitepress dev --host 0.0.0.0 --port 5173 --strictPort",
     "docs:build": "VITE_EXTRA_EXTENSIONS=jsonc vitepress build",
     "docs:preview": "VITE_EXTRA_EXTENSIONS=jsonc vitepress preview --host 0.0.0.0 --port 4173 --strictPort",
-    "test": "bun test plausible.test.ts index.assets.test.ts docs-sync.test.ts seo.test.ts"
+    "test": "bun test plausible.test.ts index.assets.test.ts docs-sync.test.ts seo.test.ts .vitepress/theme/status-line.test.ts ../scripts/docs-versioning.test.ts"
   },
   "dependencies": {
     "@catppuccin/vitepress": "^0.1.2",

docs-site/plausible.test.ts

@@ -4,9 +4,11 @@ import { readFileSync } from 'node:fs';
 const docsConfigPath = new URL('./.vitepress/config.ts', import.meta.url);
 const docsThemePath = new URL('./.vitepress/theme/index.ts', import.meta.url);
 const docsPackagePath = new URL('./package.json', import.meta.url);
+const versionedBuildPath = new URL('../scripts/build-versioned-docs.ts', import.meta.url);
 const docsConfigContents = readFileSync(docsConfigPath, 'utf8');
 const docsThemeContents = readFileSync(docsThemePath, 'utf8');
 const docsPackageContents = readFileSync(docsPackagePath, 'utf8');
+const versionedBuildContents = readFileSync(versionedBuildPath, 'utf8');
 
 test('docs site loads the docs.subminer.moe Plausible script through the analytics proxy', () => {
   expect(docsConfigContents).toContain("const DOCS_HOSTNAME = 'https://docs.subminer.moe'");
@@ -34,3 +36,33 @@ test('docs site loads the docs.subminer.moe Plausible script through the analyti
   expect(docsThemeContents).not.toContain('initPlausibleTracker');
   expect(docsPackageContents).not.toContain('@plausible-analytics/tracker');
 });
+
+test('versioned docs reuse current VitePress internals for old page snapshots', () => {
+  expect(versionedBuildContents).toContain("cpSync(join(currentDocsSite, '.vitepress')");
+  expect(versionedBuildContents).toContain('overlayCurrentVitePress(snapshotDocsSite)');
+});
+
+test('versioned docs build reports archive cache hits and rebuilds', () => {
+  expect(versionedBuildContents).toContain(
+    'console.info(`[docs] archive cache key ${archiveCacheKey.slice(0, 12)}`)',
+  );
+  expect(versionedBuildContents).toContain('console.info(`[docs] cache hit ${version}`)');
+  expect(versionedBuildContents).toContain('console.info(`[docs] rebuilding archive ${version}`)');
+});
+
+test('versioned docs build deduplicates public assets and prunes stale workspaces', () => {
+  expect(versionedBuildContents).toContain('dedupeVersionedPublicAssets({');
+  expect(versionedBuildContents).toContain('pruneArchiveCacheGenerations({');
+  expect(versionedBuildContents).toContain('rmSync(buildRoot, { recursive: true, force: true });');
+});
+
+test('versioned docs archive cache key ignores generated and test-only files', () => {
+  expect(versionedBuildContents).toContain('isSharedInternalsHashIgnoredPath(path)');
+  expect(versionedBuildContents).toContain('|| /\\.test\\.[cm]?[jt]s$/.test(path)');
+  expect(versionedBuildContents).toContain('process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN');
+  expect(versionedBuildContents).not.toContain('hash.update(String(stat.mode))');
+});
+
+test('docs builds exclude the internal README from VitePress page entries', () => {
+  expect(docsConfigContents).toContain("srcExclude: ['subagents/**', 'README.md']");
+});

docs-site/public/config.example.jsonc

@@ -10,7 +10,7 @@
   // Overlay Auto-Start
   // When overlay connects to mpv, automatically show overlay and hide mpv subtitles.
   // ==========================================
-  "auto_start_overlay": false, // When overlay connects to mpv, automatically show overlay and hide mpv subtitles. Values: true | false
+  "auto_start_overlay": false, // Auto-start the subtitle overlay window when SubMiner launches. Values: true | false
 
   // ==========================================
   // Texthooker Server
@@ -18,7 +18,7 @@
   // ==========================================
   "texthooker": {
     "launchAtStartup": false, // Launch texthooker server automatically when SubMiner starts. Values: true | false
-    "openBrowser": false // Open browser setting. Values: true | false
+    "openBrowser": false // Open the texthooker page in the default browser when the server starts. Values: true | false
   }, // Configure texthooker startup launch and browser opening behavior.
 
   // ==========================================
@@ -174,24 +174,24 @@
   // Hot-reload: shortcut changes apply live and update the session help modal on reopen.
   // ==========================================
   "shortcuts": {
-    "toggleVisibleOverlayGlobal": "Alt+Shift+O", // Toggle visible overlay global setting.
-    "copySubtitle": "CommandOrControl+C", // Copy subtitle setting.
-    "copySubtitleMultiple": "CommandOrControl+Shift+C", // Copy subtitle multiple setting.
-    "updateLastCardFromClipboard": "CommandOrControl+V", // Update last card from clipboard setting.
-    "triggerFieldGrouping": "CommandOrControl+G", // Trigger field grouping setting.
-    "triggerSubsync": "Ctrl+Alt+S", // Trigger subsync setting.
-    "mineSentence": "CommandOrControl+S", // Mine sentence setting.
-    "mineSentenceMultiple": "CommandOrControl+Shift+S", // Mine sentence multiple setting.
+    "toggleVisibleOverlayGlobal": "Alt+Shift+O", // Global accelerator that toggles overlay visibility from anywhere on the system. Use null to disable.
+    "copySubtitle": "CommandOrControl+C", // Accelerator that copies the current subtitle line to the clipboard.
+    "copySubtitleMultiple": "CommandOrControl+Shift+C", // Accelerator that copies consecutive subtitle lines while the multi-copy window stays open.
+    "updateLastCardFromClipboard": "CommandOrControl+V", // Accelerator that updates the last mined Anki card using the current clipboard contents.
+    "triggerFieldGrouping": "CommandOrControl+G", // Accelerator that triggers Kiku field grouping on duplicate cards.
+    "triggerSubsync": "Ctrl+Alt+S", // Accelerator that triggers subsync against the active subtitle file.
+    "mineSentence": "CommandOrControl+S", // Accelerator that mines the current sentence as a new Anki card.
+    "mineSentenceMultiple": "CommandOrControl+Shift+S", // Accelerator that mines consecutive sentences while the multi-mine window stays open.
     "multiCopyTimeoutMs": 3000, // Timeout for multi-copy/mine modes.
-    "toggleSecondarySub": "CommandOrControl+Shift+V", // Toggle secondary sub setting.
-    "markAudioCard": "CommandOrControl+Shift+A", // Mark audio card setting.
-    "openCharacterDictionary": "CommandOrControl+Alt+A", // Open character dictionary setting.
-    "openRuntimeOptions": "CommandOrControl+Shift+O", // Open runtime options setting.
-    "openJimaku": "Ctrl+Shift+J", // Open jimaku setting.
-    "openSessionHelp": "CommandOrControl+Slash", // Open session help setting.
-    "openControllerSelect": "Alt+C", // Open controller select setting.
-    "openControllerDebug": "Alt+Shift+C", // Open controller debug setting.
-    "toggleSubtitleSidebar": "Backslash" // Toggle subtitle sidebar setting.
+    "toggleSecondarySub": "CommandOrControl+Shift+V", // Accelerator that toggles the secondary subtitle bar visibility.
+    "markAudioCard": "CommandOrControl+Shift+A", // Accelerator that marks the last mined card as an audio card.
+    "openCharacterDictionary": "CommandOrControl+Alt+A", // Accelerator that opens the character dictionary modal.
+    "openRuntimeOptions": "CommandOrControl+Shift+O", // Accelerator that opens the runtime options modal.
+    "openJimaku": "Ctrl+Shift+J", // Accelerator that opens the Jimaku subtitle search modal.
+    "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
+    "openControllerSelect": "Alt+C", // Accelerator that opens the controller selection and learn-mode modal.
+    "openControllerDebug": "Alt+Shift+C", // Accelerator that opens the controller debug modal with live axis/button readouts.
+    "toggleSubtitleSidebar": "Backslash" // Accelerator that toggles the subtitle sidebar visibility.
   }, // Overlay keyboard shortcuts. Set a shortcut to null to disable.
 
   // ==========================================
@@ -328,9 +328,9 @@
   // Hot-reload: defaultMode updates live while SubMiner is running.
   // ==========================================
   "secondarySub": {
-    "secondarySubLanguages": [], // Secondary sub languages setting.
-    "autoLoadSecondarySub": false, // Auto load secondary sub setting. Values: true | false
-    "defaultMode": "hover" // Default mode setting.
+    "secondarySubLanguages": [], // Language code priority list used to auto-select a secondary subtitle track when available.
+    "autoLoadSecondarySub": false, // Automatically load a matching secondary subtitle when the primary subtitle loads. Values: true | false
+    "defaultMode": "hover" // Default visibility mode for the secondary subtitle bar. Values: hidden | visible | hover
   }, // Dual subtitle track options.
 
   // ==========================================
@@ -339,9 +339,9 @@
   // ==========================================
   "subsync": {
     "defaultMode": "auto", // Subsync default mode. Values: auto | manual
-    "alass_path": "", // Alass path setting.
-    "ffsubsync_path": "", // Ffsubsync path setting.
-    "ffmpeg_path": "", // Ffmpeg path setting.
+    "alass_path": "", // Optional absolute path to the alass binary used by subsync. Leave empty to auto-discover from PATH.
+    "ffsubsync_path": "", // Optional absolute path to the ffsubsync binary used by subsync. Leave empty to auto-discover from PATH.
+    "ffmpeg_path": "", // Optional absolute path to the ffmpeg binary used by subsync. Leave empty to auto-discover from PATH.
     "replace": true // Replace the active subtitle file when sync completes. Values: true | false
   }, // Subsync engine and executable paths.
 
@@ -350,7 +350,7 @@
   // Initial vertical subtitle position from the bottom.
   // ==========================================
   "subtitlePosition": {
-    "yPercent": 10 // Y percent setting.
+    "yPercent": 10 // Vertical position of the subtitle overlay expressed as a percentage from the bottom of the screen.
   }, // Initial vertical subtitle position from the bottom.
 
   // ==========================================
@@ -454,9 +454,9 @@
     "enabled": false, // Enable shared OpenAI-compatible AI provider features. Values: true | false
     "apiKey": "", // Static API key for the shared OpenAI-compatible AI provider.
     "apiKeyCommand": "", // Shell command used to resolve the shared AI provider API key.
-    "model": "openai/gpt-4o-mini", // Model setting.
+    "model": "openai/gpt-4o-mini", // Default model identifier requested from the shared AI provider.
     "baseUrl": "https://openrouter.ai/api", // Base URL for the shared OpenAI-compatible AI provider.
-    "systemPrompt": "You are a translation engine. Return only the translated text with no explanations.", // System prompt setting.
+    "systemPrompt": "You are a translation engine. Return only the translated text with no explanations.", // Default system prompt sent with shared AI provider requests.
     "requestTimeoutMs": 15000 // Timeout in milliseconds for shared AI provider requests.
   }, // Canonical OpenAI-compatible provider transport settings shared by Anki and YouTube subtitle fixing.
 
@@ -469,7 +469,7 @@
   // ==========================================
   "ankiConnect": {
     "enabled": true, // Enable AnkiConnect integration. Values: true | false
-    "url": "http://127.0.0.1:8765", // Url setting.
+    "url": "http://127.0.0.1:8765", // Base URL of the AnkiConnect HTTP server.
     "pollingRate": 3000, // Polling interval in milliseconds.
     "proxy": {
       "enabled": true, // Enable local AnkiConnect-compatible proxy for push-based auto-enrichment. Values: true | false
@@ -482,11 +482,11 @@
     ], // Tags to add to cards mined or updated by SubMiner. Provide an empty array to disable automatic tagging.
     "fields": {
       "word": "Expression", // Card field for the mined word or expression text.
-      "audio": "ExpressionAudio", // Audio setting.
-      "image": "Picture", // Image setting.
-      "sentence": "Sentence", // Sentence setting.
-      "miscInfo": "MiscInfo", // Misc info setting.
-      "translation": "SelectionText" // Translation setting.
+      "audio": "ExpressionAudio", // Card field that receives generated sentence audio.
+      "image": "Picture", // Card field that receives the captured screenshot or animated image.
+      "sentence": "Sentence", // Card field that receives the source sentence text.
+      "miscInfo": "MiscInfo", // Card field that receives the miscellaneous info pattern (see ankiConnect.metadata.pattern).
+      "translation": "SelectionText" // Card field that receives the current selection or translated text.
     }, // Fields setting.
     "ai": {
       "enabled": false, // Enable AI provider usage for Anki translation/enrichment flows. Values: true | false
@@ -494,18 +494,18 @@
       "systemPrompt": "" // Optional system prompt override for Anki AI translation/enrichment flows.
     }, // Ai setting.
     "media": {
-      "generateAudio": true, // Generate audio setting. Values: true | false
-      "generateImage": true, // Generate image setting. Values: true | false
-      "imageType": "static", // Image type setting.
-      "imageFormat": "jpg", // Image format setting.
-      "imageQuality": 92, // Image quality setting.
-      "animatedFps": 10, // Animated fps setting.
-      "animatedMaxWidth": 640, // Animated max width setting.
-      "animatedCrf": 35, // Animated crf setting.
+      "generateAudio": true, // Generate sentence audio for mined cards. Values: true | false
+      "generateImage": true, // Generate screenshot or animated image for mined cards. Values: true | false
+      "imageType": "static", // Image capture type: "static" for a single still frame, "avif" for an animated AVIF. Values: static | avif
+      "imageFormat": "jpg", // Encoding format used when imageType is "static". Values: jpg | png | webp
+      "imageQuality": 92, // Quality (0-100) used for lossy static image encoders.
+      "animatedFps": 10, // Target frame rate for animated AVIF captures.
+      "animatedMaxWidth": 640, // Maximum width applied to animated AVIF captures.
+      "animatedCrf": 35, // Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.
       "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
-      "audioPadding": 0.5, // Audio padding setting.
-      "fallbackDuration": 3, // Fallback duration setting.
-      "maxMediaDuration": 30 // Max media duration setting.
+      "audioPadding": 0.5, // Seconds of padding appended to both ends of generated sentence audio.
+      "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
+      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.
     }, // Media setting.
     "knownWords": {
       "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
@@ -516,11 +516,11 @@
       "color": "#a6da95" // Color used for known-word highlights.
     }, // Known words setting.
     "behavior": {
-      "overwriteAudio": true, // Overwrite audio setting. Values: true | false
-      "overwriteImage": true, // Overwrite image setting. Values: true | false
-      "mediaInsertMode": "append", // Media insert mode setting.
-      "highlightWord": true, // Highlight word setting. Values: true | false
-      "notificationType": "osd", // Notification type setting.
+      "overwriteAudio": true, // When updating an existing card, overwrite the audio field instead of skipping it. Values: true | false
+      "overwriteImage": true, // When updating an existing card, overwrite the image field instead of skipping it. Values: true | false
+      "mediaInsertMode": "append", // Whether new media is appended after or prepended before existing field contents on update. Values: append | prepend
+      "highlightWord": true, // Bold the mined word inside the sentence field on the saved Anki card. Values: true | false
+      "notificationType": "osd", // Notification surface used to announce mining and update outcomes. Values: osd | system | both | none
       "autoUpdateNewCards": true // Automatically update newly added cards. Values: true | false
     }, // Behavior setting.
     "nPlusOne": {
@@ -528,16 +528,16 @@
       "nPlusOne": "#c6a0f6" // Color used for the single N+1 target token highlight.
     }, // N plus one setting.
     "metadata": {
-      "pattern": "[SubMiner] %f (%t)" // Pattern setting.
+      "pattern": "[SubMiner] %f (%t)" // Template used to render the miscInfo field. Placeholders include %f (filename) and %t (timestamp).
     }, // Metadata setting.
     "isLapis": {
-      "enabled": false, // Enabled setting. Values: true | false
-      "sentenceCardModel": "Japanese sentences" // Sentence card model setting.
+      "enabled": false, // Enable Lapis-specific mining behaviors and sentence card model targeting. Values: true | false
+      "sentenceCardModel": "Japanese sentences" // Note type name used by Lapis sentence cards.
     }, // Is lapis setting.
     "isKiku": {
-      "enabled": false, // Enabled setting. Values: true | false
+      "enabled": false, // Enable Kiku-specific mining behaviors (duplicate handling, field grouping). Values: true | false
       "fieldGrouping": "disabled", // Kiku duplicate-card field grouping mode. Values: auto | manual | disabled
-      "deleteDuplicateInAuto": true // Delete duplicate in auto setting. Values: true | false
+      "deleteDuplicateInAuto": true // When Kiku field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
     } // Is kiku setting.
   }, // Automatic Anki updates and media generation options.
 
@@ -546,7 +546,7 @@
   // Jimaku API configuration and defaults.
   // ==========================================
   "jimaku": {
-    "apiBaseUrl": "https://jimaku.cc", // Api base url setting.
+    "apiBaseUrl": "https://jimaku.cc", // Base URL of the Jimaku subtitle search API.
     "languagePreference": "ja", // Preferred language used in Jimaku search. Values: ja | en | none
     "maxEntryResults": 10 // Maximum Jimaku search results returned.
   }, // Jimaku API configuration and defaults.
@@ -618,9 +618,9 @@
     "serverUrl": "", // Base Jellyfin server URL (for example: http://localhost:8096).
     "recentServers": [], // Recently authenticated Jellyfin server URLs shown in setup.
     "username": "", // Default Jellyfin username used during CLI login.
-    "deviceId": "subminer", // Device id setting.
-    "clientName": "SubMiner", // Client name setting.
-    "clientVersion": "0.1.0", // Client version setting.
+    "deviceId": "subminer", // Stable device identifier sent on the Jellyfin authentication handshake; primarily internal.
+    "clientName": "SubMiner", // Client name sent on the Jellyfin authentication handshake; primarily internal.
+    "clientVersion": "0.1.0", // Client version sent on the Jellyfin authentication handshake; primarily internal.
     "defaultLibraryId": "", // Optional default Jellyfin library ID for item listing.
     "remoteControlEnabled": true, // Enable Jellyfin remote cast control mode. Values: true | false
     "remoteControlAutoConnect": true, // Auto-connect to the configured remote control target. Values: true | false

docs-site/seo.test.ts

@@ -1,7 +1,13 @@
 import { expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import type { TransformContext } from 'vitepress';
 import docsConfig from './.vitepress/config';
 
+const docsSiteDir = fileURLToPath(new URL('.', import.meta.url));
+
 function makeTransformContext(page: string): TransformContext {
   return {
     page,
@@ -31,6 +37,391 @@ test('docs pages emit stable self-referential canonical URLs', async () => {
   expect(JSON.stringify(rootHead).toLowerCase()).not.toContain('noindex');
 });
 
+test('main docs canonical uses /main/ and emits noindex', async () => {
+  const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
+  const previousBase = process.env.SUBMINER_DOCS_BASE;
+  process.env.SUBMINER_DOCS_CHANNEL = 'main';
+  process.env.SUBMINER_DOCS_BASE = '/main/';
+  const { default: mainDocsConfig } = await import('./.vitepress/config?main-docs');
+
+  const head = await mainDocsConfig.transformHead?.(makeTransformContext('usage.md'));
+  const rootHead = await mainDocsConfig.transformHead?.(makeTransformContext('index.md'));
+
+  expect(head).toContainEqual([
+    'link',
+    { rel: 'canonical', href: 'https://docs.subminer.moe/main/usage' },
+  ]);
+  expect(rootHead).toContainEqual([
+    'link',
+    { rel: 'canonical', href: 'https://docs.subminer.moe/main/' },
+  ]);
+  expect(head).toContainEqual(['meta', { name: 'robots', content: 'noindex,follow' }]);
+
+  process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
+  process.env.SUBMINER_DOCS_BASE = previousBase;
+});
+
+test('latest stable archive canonical points to root equivalent', async () => {
+  const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
+  const previousBase = process.env.SUBMINER_DOCS_BASE;
+  const previousVersion = process.env.SUBMINER_DOCS_VERSION;
+  const previousLatest = process.env.SUBMINER_DOCS_LATEST_STABLE;
+  process.env.SUBMINER_DOCS_CHANNEL = 'stable-archive';
+  process.env.SUBMINER_DOCS_BASE = '/v/0.14.0/';
+  process.env.SUBMINER_DOCS_VERSION = 'v0.14.0';
+  process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
+  const { default: latestArchiveConfig } = await import('./.vitepress/config?latest-archive');
+
+  const head = await latestArchiveConfig.transformHead?.(makeTransformContext('usage.md'));
+
+  expect(head).toContainEqual([
+    'link',
+    { rel: 'canonical', href: 'https://docs.subminer.moe/usage' },
+  ]);
+
+  process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
+  process.env.SUBMINER_DOCS_BASE = previousBase;
+  process.env.SUBMINER_DOCS_VERSION = previousVersion;
+  process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
+});
+
+test('stable archive theme links stay on the selected version', async () => {
+  const previousCwd = process.cwd();
+  const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
+  const previousBase = process.env.SUBMINER_DOCS_BASE;
+  const previousVersion = process.env.SUBMINER_DOCS_VERSION;
+  const previousLatest = process.env.SUBMINER_DOCS_LATEST_STABLE;
+  const previousManifest = process.env.SUBMINER_DOCS_VERSION_MANIFEST;
+  const previousVersionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN;
+  process.chdir(docsSiteDir);
+  process.env.SUBMINER_DOCS_CHANNEL = 'stable-archive';
+  process.env.SUBMINER_DOCS_BASE = '/v/0.12.0/';
+  process.env.SUBMINER_DOCS_VERSION = 'v0.12.0';
+  process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
+  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'production';
+  process.env.SUBMINER_DOCS_VERSION_MANIFEST = JSON.stringify({
+    latestStable: 'v0.14.0',
+    channels: [
+      { label: 'Latest stable', path: '/' },
+      { label: 'main', path: '/main/' },
+    ],
+    versions: [
+      { version: 'v0.14.0', path: '/v/0.14.0/' },
+      { version: 'v0.12.0', path: '/v/0.12.0/' },
+    ],
+  });
+  try {
+    const { default: archiveConfig } = await import('./.vitepress/config?stable-archive-links');
+
+    const nav = archiveConfig.themeConfig?.nav as Array<{
+      text: string;
+      link?: string;
+      items?: Array<{ text: string; link: string }>;
+    }>;
+    const sidebar = archiveConfig.themeConfig?.sidebar as Array<{
+      text: string;
+      items?: Array<{ text: string; link: string }>;
+    }>;
+    const configurationNav = nav.find((item) => item.text === 'Configuration');
+    const versionNav = nav.find((item) => item.text === 'v0.12.0');
+    const referenceSidebar = sidebar.find((item) => item.text === 'Reference');
+    const configurationSidebar = referenceSidebar?.items?.find(
+      (item) => item.text === 'Configuration',
+    );
+
+    expect(configurationNav?.link).toBe('/configuration');
+    expect(configurationSidebar?.link).toBe('/configuration');
+    expect(versionNav?.items).toContainEqual({
+      text: 'Latest stable (v0.14.0)',
+      link: 'https://docs.subminer.moe/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items).toContainEqual({
+      text: 'main',
+      link: 'https://docs.subminer.moe/main/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items).toContainEqual({
+      text: 'v0.14.0',
+      link: 'https://docs.subminer.moe/v/0.14.0/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items).toContainEqual({
+      text: 'v0.12.0',
+      link: 'https://docs.subminer.moe/v/0.12.0/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(archiveConfig.themeConfig?.logo).toEqual({
+      light: '/assets/SubMiner.png',
+      dark: '/assets/SubMiner.png',
+    });
+  } finally {
+    process.chdir(previousCwd);
+    process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
+    process.env.SUBMINER_DOCS_BASE = previousBase;
+    process.env.SUBMINER_DOCS_VERSION = previousVersion;
+    process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
+    process.env.SUBMINER_DOCS_VERSION_MANIFEST = previousManifest;
+    process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = previousVersionLinkOrigin;
+  }
+});
+
+test('local stable archive version links stay on the dev server', async () => {
+  const previousCwd = process.cwd();
+  const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
+  const previousBase = process.env.SUBMINER_DOCS_BASE;
+  const previousVersion = process.env.SUBMINER_DOCS_VERSION;
+  const previousLatest = process.env.SUBMINER_DOCS_LATEST_STABLE;
+  const previousManifest = process.env.SUBMINER_DOCS_VERSION_MANIFEST;
+  const previousVersionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN;
+  process.chdir(docsSiteDir);
+  process.env.SUBMINER_DOCS_CHANNEL = 'stable-archive';
+  process.env.SUBMINER_DOCS_BASE = '/v/0.10.0/';
+  process.env.SUBMINER_DOCS_VERSION = 'v0.10.0';
+  process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
+  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'local';
+  process.env.SUBMINER_DOCS_VERSION_MANIFEST = JSON.stringify({
+    latestStable: 'v0.14.0',
+    channels: [
+      { label: 'Latest stable', path: '/' },
+      { label: 'main', path: '/main/' },
+    ],
+    versions: [
+      { version: 'v0.14.0', path: '/v/0.14.0/' },
+      { version: 'v0.10.0', path: '/v/0.10.0/' },
+    ],
+  });
+  try {
+    const { default: archiveConfig } = await import('./.vitepress/config?local-archive-links');
+
+    const nav = archiveConfig.themeConfig?.nav as Array<{
+      text: string;
+      items?: Array<{ text: string; link: string }>;
+    }>;
+    const versionNav = nav.find((item) => item.text === 'v0.10.0');
+
+    expect(versionNav?.items).toContainEqual({
+      text: 'Latest stable (v0.14.0)',
+      link: '../../',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items).toContainEqual({
+      text: 'main',
+      link: '../../main/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items).toContainEqual({
+      text: 'v0.14.0',
+      link: '../0.14.0/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items).toContainEqual({
+      text: 'v0.10.0',
+      link: './',
+      target: '_self',
+      noIcon: true,
+    });
+  } finally {
+    process.chdir(previousCwd);
+    process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
+    process.env.SUBMINER_DOCS_BASE = previousBase;
+    process.env.SUBMINER_DOCS_VERSION = previousVersion;
+    process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
+    process.env.SUBMINER_DOCS_VERSION_MANIFEST = previousManifest;
+    process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = previousVersionLinkOrigin;
+  }
+});
+
+test('dev docs version links use local targets for version route testing', async () => {
+  const previousCwd = process.cwd();
+  const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
+  const previousBase = process.env.SUBMINER_DOCS_BASE;
+  const previousVersion = process.env.SUBMINER_DOCS_VERSION;
+  const previousLatest = process.env.SUBMINER_DOCS_LATEST_STABLE;
+  const previousManifest = process.env.SUBMINER_DOCS_VERSION_MANIFEST;
+  const previousVersionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN;
+  process.chdir(docsSiteDir);
+  delete process.env.SUBMINER_DOCS_CHANNEL;
+  delete process.env.SUBMINER_DOCS_BASE;
+  delete process.env.SUBMINER_DOCS_VERSION;
+  delete process.env.SUBMINER_DOCS_LATEST_STABLE;
+  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'local';
+  process.env.SUBMINER_DOCS_VERSION_MANIFEST = JSON.stringify({
+    latestStable: 'v0.14.0',
+    channels: [
+      { label: 'Latest stable', path: '/' },
+      { label: 'main', path: '/main/' },
+    ],
+    versions: [
+      { version: 'v0.14.0', path: '/v/0.14.0/' },
+      { version: 'v0.12.0', path: '/v/0.12.0/' },
+      { version: 'v0.11.2', path: '/v/0.11.2/' },
+    ],
+  });
+  try {
+    const { default: devConfig } = await import('./.vitepress/config?dev-version-links');
+
+    const nav = devConfig.themeConfig?.nav as Array<{
+      text: string;
+      items?: Array<{ text: string; link: string }>;
+    }>;
+    const versionNav = nav.find((item) => item.text === 'v0.14.0');
+
+    expect(versionNav?.items).toContainEqual({
+      text: 'Latest stable (v0.14.0)',
+      link: '/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items).toContainEqual({
+      text: 'main',
+      link: '/main/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items).toContainEqual({
+      text: 'v0.12.0',
+      link: '/v/0.12.0/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items?.map((item) => item.text)).toEqual([
+      'Latest stable (v0.14.0)',
+      'main',
+      'v0.14.0',
+      'v0.12.0',
+      'v0.11.2',
+    ]);
+  } finally {
+    process.chdir(previousCwd);
+    process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
+    process.env.SUBMINER_DOCS_BASE = previousBase;
+    process.env.SUBMINER_DOCS_VERSION = previousVersion;
+    process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
+    process.env.SUBMINER_DOCS_VERSION_MANIFEST = previousManifest;
+    process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = previousVersionLinkOrigin;
+  }
+});
+
+test('dev server redirects unserved version routes to production docs', () => {
+  let routeHandler:
+    | ((req: { url?: string }, res: DevRedirectResponse, next: () => void) => void)
+    | undefined;
+  const fakeServer = {
+    middlewares: {
+      use(handler: typeof routeHandler) {
+        routeHandler = handler;
+      },
+    },
+  };
+  const plugins = Array.isArray(docsConfig.vite?.plugins)
+    ? docsConfig.vite.plugins
+    : [docsConfig.vite?.plugins].filter(Boolean);
+  const redirectPlugin = plugins.find(
+    (plugin): plugin is { name: string; configureServer: (server: never) => void } =>
+      Boolean(plugin) &&
+      typeof plugin === 'object' &&
+      'name' in plugin &&
+      plugin.name === 'subminer-docs-local-version-redirects' &&
+      'configureServer' in plugin,
+  );
+  expect(redirectPlugin).toBeDefined();
+  redirectPlugin?.configureServer(fakeServer as never);
+
+  const response = new DevRedirectResponse();
+  let nextCalled = false;
+  routeHandler?.({ url: '/v/0.14.0/?from=dev' }, response, () => {
+    nextCalled = true;
+  });
+
+  expect(nextCalled).toBe(false);
+  expect(response.statusCode).toBe(302);
+  expect(response.headers.location).toBe('https://docs.subminer.moe/v/0.14.0/?from=dev');
+
+  const rootResponse = new DevRedirectResponse();
+  routeHandler?.({ url: '/configuration' }, rootResponse, () => {
+    nextCalled = true;
+  });
+  expect(rootResponse.ended).toBe(false);
+  expect(nextCalled).toBe(true);
+});
+
+test('dev server serves local archive files for local version links', async () => {
+  const previousVersionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN;
+  const previousArchiveDir = process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR;
+  const archiveDir = mkdtempSync(join(tmpdir(), 'subminer-docs-archive-'));
+  mkdirSync(join(archiveDir, 'v/0.14.0'), { recursive: true });
+  writeFileSync(join(archiveDir, 'v/0.14.0/index.html'), '<h1>local archive</h1>');
+  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'local';
+  process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR = archiveDir;
+  try {
+    const { default: localDevConfig } = await import('./.vitepress/config?local-dev-redirects');
+    let routeHandler:
+      | ((req: { url?: string }, res: DevRedirectResponse, next: () => void) => void)
+      | undefined;
+    const fakeServer = {
+      middlewares: {
+        use(handler: typeof routeHandler) {
+          routeHandler = handler;
+        },
+      },
+    };
+    const plugins = Array.isArray(localDevConfig.vite?.plugins)
+      ? localDevConfig.vite.plugins
+      : [localDevConfig.vite?.plugins].filter(Boolean);
+    const redirectPlugin = plugins.find(
+      (plugin): plugin is { name: string; configureServer: (server: never) => void } =>
+        Boolean(plugin) &&
+        typeof plugin === 'object' &&
+        'name' in plugin &&
+        plugin.name === 'subminer-docs-local-version-redirects' &&
+        'configureServer' in plugin,
+    );
+    redirectPlugin?.configureServer(fakeServer as never);
+
+    const response = new DevRedirectResponse();
+    let nextCalled = false;
+    routeHandler?.({ url: '/v/0.14.0/?from=dev' }, response, () => {
+      nextCalled = true;
+    });
+
+    expect(nextCalled).toBe(false);
+    expect(response.statusCode).toBe(200);
+    expect(response.headers['content-type']).toBe('text/html; charset=utf-8');
+    expect(response.headers.location).toBeUndefined();
+    expect(response.body).toBe('<h1>local archive</h1>');
+  } finally {
+    process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = previousVersionLinkOrigin;
+    process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR = previousArchiveDir;
+    rmSync(archiveDir, { recursive: true, force: true });
+  }
+});
+
+class DevRedirectResponse {
+  statusCode = 200;
+  headers: Record<string, string> = {};
+  ended = false;
+  body = '';
+
+  setHeader(name: string, value: string) {
+    this.headers[name.toLowerCase()] = value;
+  }
+
+  end(chunk?: string | Uint8Array) {
+    if (chunk) {
+      this.body = typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk);
+    }
+    this.ended = true;
+  }
+}
+
 test('docs sitemap excludes duplicate README page from indexable URLs', async () => {
   const items = [{ url: '' }, { url: 'README' }, { url: 'usage' }];
 

docs-site/usage.md

@@ -78,6 +78,8 @@ subminer -S video.mkv             # Same as above via --start-overlay
 subminer https://youtu.be/...     # Play a YouTube URL
 subminer ytsearch:"jp news"       # Play first YouTube search result
 subminer --setup                  # Open first-run setup popup
+subminer --version                # Print installed SubMiner version
+subminer -v                       # Same as above
 subminer --log-level debug video.mkv # Enable verbose logs for launch/debugging
 subminer --log-level warn video.mkv  # Set logging level explicitly
 subminer --args '--fs=opengl-hq --ytdl-format=bestvideo*+bestaudio/best' video.mkv  # Pass extra mpv args

docs/RELEASING.md

@@ -37,6 +37,7 @@
 8. If `docs-site/` changed, also run:
    `bun run docs:test`
    `bun run docs:build`
+   `bun run docs:build:versioned`
 9. Commit release prep.
 10. Tag the commit: `git tag v<version>`.
 11. Push commit + tag.
@@ -66,6 +67,7 @@
 7. Push commit + tag.
 
 Prerelease tags publish a GitHub prerelease only. They do not update `CHANGELOG.md`, `docs-site/changelog.md`, or the AUR package, and they do not consume `changes/*.md` fragments. The final stable release is still the point where `bun run changelog:build` consumes fragments into `CHANGELOG.md` and regenerates stable release notes.
+Prerelease tags also do not update `https://docs.subminer.moe/`.
 
 Notes:
 
@@ -81,8 +83,13 @@ Notes:
 - If you need to repair a published release body (for example, a prior version’s section was omitted), regenerate notes from `CHANGELOG.md` and re-edit the release with `gh release edit --notes-file`.
 - Prerelease tags are handled by `.github/workflows/prerelease.yml`, which always publishes a GitHub prerelease with all current release platforms and never runs the AUR sync job.
 - Tagged release workflow now also attempts to update `subminer-bin` on the AUR after GitHub Release publication.
+- Stable release tags update `https://docs.subminer.moe/` and `https://docs.subminer.moe/v/<version>/` through `.github/workflows/docs-pages.yml`; `/main/` continues to show development docs from `main`.
+- Keep Cloudflare Pages Git auto-deploy disabled for `docs.subminer.moe`. Production docs are direct-uploaded by Wrangler from GitHub Actions with `--branch main`.
 - AUR publish is best-effort: the workflow retries transient SSH clone/push failures, then warns and leaves the GitHub Release green if AUR still fails. Follow up with a manual `git push aur master` from the AUR checkout when needed.
 - Required GitHub Actions secret: `AUR_SSH_PRIVATE_KEY`. Add the matching public key to your AUR account before relying on the automation.
 - Release and prerelease workflows upload updater metadata (`*.yml`) and blockmaps (`*.blockmap`) alongside platform artifacts. Do not remove those files while `electron-updater` is enabled.
+- macOS tray app updates use the standard `electron-updater`/Squirrel path. Keep `latest-mac.yml`, the macOS ZIP, and ZIP blockmap published; Squirrel uses the ZIP payload even when the DMG remains the user-facing installer.
+- macOS update metadata and full ZIP downloads are routed through `/usr/bin/curl` before Squirrel installation to avoid Electron main-process network crashes on update checks.
+- Local macOS build-output apps outside `/Applications` or `~/Applications` skip native update checks. To validate auto-update end to end, install the signed and notarized app bundle into one of those Applications folders and point it at a published updater feed.
 - The first updater-enabled release cannot update older installs automatically. Users need one manual install to get the updater code.
 - Stable auto-update checks ignore beta/RC prereleases by default. Set `updates.channel` to `"prerelease"` on a test install when validating beta/RC updater behavior.

docs/plans/config-settings-window.md

@@ -0,0 +1,70 @@
+# Config Settings Window
+
+read_when: changing config UI, config save behavior, or config docs
+
+## Intent
+
+Add a dedicated Electron settings window for editing canonical config values without exposing the historical layout mistakes in `config.jsonc`.
+
+The UI groups options by workflow:
+
+- Viewing
+- Mining & Anki
+- Playback & Sources
+- Input
+- Integrations
+- Tracking & App
+- Advanced
+
+Each field maps back to its current raw config path. The presentation layer must stay separate from generated config-template sections.
+
+## Sources
+
+- Canonical defaults: `DEFAULT_CONFIG`
+- Existing option descriptions/enums: `CONFIG_OPTION_REGISTRY`
+- UI registry: `src/config/settings/registry.ts`
+- JSONC save path: `src/config/settings/jsonc-edit.ts`
+- Window runtime: `src/main/runtime/config-settings-window.ts`
+
+## Save Contract
+
+Settings writes use `jsonc-parser.modify`, not `JSON.stringify`.
+
+Required behavior:
+
+- Preserve comments, trailing commas, unrelated keys, and hidden legacy keys.
+- Reset removes the explicit path so defaults resolve normally.
+- Validate the candidate config before writing.
+- Reject warnings caused by modified fields.
+- Preserve unrelated existing warnings and return them in the snapshot.
+- Write atomically, reload `ConfigService`, classify with existing hot-reload logic, and apply live changes where supported.
+- Never return secret values to the renderer; snapshots only expose configured/not-configured state.
+
+## Hidden Compatibility Keys
+
+Do not expose these as first-class controls:
+
+- `ankiConnect.deck`
+- Legacy top-level Anki migration fields such as `wordField`, `audioField`, media-generation aliases, and behavior aliases
+- Legacy `ankiConnect.nPlusOne.*` aliases except canonical `nPlusOne.nPlusOne` and `nPlusOne.minSentenceWords`
+- Deprecated Lapis sentence-card fields
+- `youtubeSubgen.primarySubLanguages`
+- `anilist.characterDictionary.refreshTtlHours`
+- `anilist.characterDictionary.evictionPolicy`
+- `jellyfin.accessToken`
+- `jellyfin.userId`
+- `controller.buttonIndices` as a normal editable field
+
+## Verification
+
+Minimum targeted checks:
+
+- `bun test src/config/settings/registry.test.ts src/config/settings/jsonc-edit.test.ts src/settings/settings-model.test.ts src/main/runtime/config-settings-window.test.ts`
+- `bun run test:config`
+- `bun run typecheck`
+- `bun run build`
+
+If docs changed:
+
+- `bun run docs:test`
+- `bun run docs:build`

launcher/commands/app-command.ts

@@ -3,7 +3,14 @@ import type { LauncherCommandContext } from './context.js';
 
 export function runAppPassthroughCommand(context: LauncherCommandContext): boolean {
   const { args, appPath } = context;
-  if (!args.appPassthrough || !appPath) {
+  if (!appPath) {
+    return false;
+  }
+  if (args.configSettings) {
+    runAppCommandWithInherit(appPath, ['--config']);
+    return true;
+  }
+  if (!args.appPassthrough) {
     return false;
   }
   runAppCommandWithInherit(appPath, args.appArgs);

launcher/commands/playback-command.test.ts

@@ -52,6 +52,8 @@ function createContext(): LauncherCommandContext {
       stats: false,
       doctor: false,
       doctorRefreshKnownWords: false,
+      version: false,
+      configSettings: false,
       configPath: false,
       configShow: false,
       mpvIdle: false,

launcher/config/args-normalizer.test.ts

@@ -159,6 +159,41 @@ test('applyInvocationsToArgs maps config and jellyfin invocation state', () => {
   assert.equal(parsed.logLevel, 'warn');
 });
 
+test('applyInvocationsToArgs maps bare config invocation to settings window', () => {
+  const parsed = createDefaultArgs({});
+
+  applyInvocationsToArgs(parsed, {
+    jellyfinInvocation: null,
+    configInvocation: {
+      action: undefined,
+    },
+    mpvInvocation: null,
+    appInvocation: null,
+    dictionaryTriggered: false,
+    dictionaryTarget: null,
+    dictionaryLogLevel: null,
+    dictionaryCandidates: false,
+    dictionarySelect: false,
+    dictionaryAnilistId: null,
+    statsTriggered: false,
+    statsBackground: false,
+    statsStop: false,
+    statsCleanup: false,
+    statsCleanupVocab: false,
+    statsCleanupLifetime: false,
+    statsLogLevel: null,
+    doctorTriggered: false,
+    doctorLogLevel: null,
+    doctorRefreshKnownWords: false,
+    texthookerTriggered: false,
+    texthookerLogLevel: null,
+    texthookerOpenBrowser: false,
+  });
+
+  assert.equal(parsed.configSettings, true);
+  assert.equal(parsed.configPath, false);
+});
+
 test('applyInvocationsToArgs maps texthooker browser-open request', () => {
   const parsed = createDefaultArgs({});
 

launcher/config/args-normalizer.ts

@@ -156,7 +156,9 @@ export function createDefaultArgs(
     statsCleanupLifetime: false,
     doctor: false,
     doctorRefreshKnownWords: false,
+    version: false,
     update: false,
+    configSettings: false,
     configPath: false,
     configShow: false,
     mpvIdle: false,
@@ -219,6 +221,8 @@ export function applyRootOptionsToArgs(
   if (typeof options.passwordStore === 'string') parsed.passwordStore = options.passwordStore;
   if (options.rofi === true) parsed.useRofi = true;
   if (options.update === true) parsed.update = true;
+  if (options.version === true) parsed.version = true;
+  if (options.config === true) parsed.configSettings = true;
   if (options.startOverlay === true) parsed.autoStartOverlay = true;
   if (options.texthooker === false) parsed.useTexthooker = false;
   if (typeof options.args === 'string') parsed.mpvArgs = options.args;
@@ -306,8 +310,9 @@ export function applyInvocationsToArgs(parsed: Args, invocations: CliInvocations
     if (invocations.configInvocation.logLevel) {
       parsed.logLevel = parseLogLevel(invocations.configInvocation.logLevel);
     }
-    const action = (invocations.configInvocation.action || 'path').toLowerCase();
-    if (action === 'path') parsed.configPath = true;
+    const action = (invocations.configInvocation.action || '').toLowerCase();
+    if (!action) parsed.configSettings = true;
+    else if (action === 'path') parsed.configPath = true;
     else if (action === 'show') parsed.configShow = true;
     else fail(`Unknown config action: ${invocations.configInvocation.action}`);
   }

launcher/config/cli-parser-builder.ts

@@ -15,7 +15,7 @@ export interface JellyfinInvocation {
 }
 
 export interface CommandActionInvocation {
-  action: string;
+  action?: string;
   logLevel?: string;
 }
 
@@ -57,6 +57,8 @@ function applyRootOptions(program: Command): void {
     .option('-p, --profile <profile>', 'MPV profile')
     .option('--start', 'Explicitly start overlay')
     .option('--log-level <level>', 'Log level')
+    .option('-v, --version', 'Show SubMiner version')
+    .option('--config', 'Open configuration window')
     .option('-u, --update', 'Check for updates')
     .option('-R, --rofi', 'Use rofi picker')
     .option('-S, --start-overlay', 'Auto-start overlay')
@@ -292,9 +294,9 @@ export function parseCliPrograms(
   commandProgram
     .command('config')
     .description('Config helpers')
-    .argument('[action]', 'path|show', 'path')
+    .argument('[action]', 'path|show')
     .option('--log-level <level>', 'Log level')
-    .action((action: string, options: Record<string, unknown>) => {
+    .action((action: string | undefined, options: Record<string, unknown>) => {
       configInvocation = {
         action,
         logLevel: typeof options.logLevel === 'string' ? options.logLevel : undefined,

launcher/main.test.ts

@@ -99,6 +99,30 @@ test('config discovery ignores lowercase subminer candidate', () => {
   assert.equal(resolved, expected);
 });
 
+test('version flag prints installed app version without requiring app binary', () => {
+  withTempDir((root) => {
+    const homeDir = path.join(root, 'home');
+    const xdgConfigHome = path.join(root, 'xdg');
+    const result = runLauncher(['--version'], makeTestEnv(homeDir, xdgConfigHome));
+
+    assert.equal(result.status, 0);
+    assert.match(result.stdout.trim(), /^SubMiner \d+\.\d+\.\d+/);
+    assert.equal(result.stderr, '');
+  });
+});
+
+test('short version flag prints installed app version without requiring app binary', () => {
+  withTempDir((root) => {
+    const homeDir = path.join(root, 'home');
+    const xdgConfigHome = path.join(root, 'xdg');
+    const result = runLauncher(['-v'], makeTestEnv(homeDir, xdgConfigHome));
+
+    assert.equal(result.status, 0);
+    assert.match(result.stdout.trim(), /^SubMiner \d+\.\d+\.\d+/);
+    assert.equal(result.stderr, '');
+  });
+});
+
 test('config path prefers jsonc over json for same directory', () => {
   withTempDir((root) => {
     const homeDir = path.join(root, 'home');
@@ -208,6 +232,54 @@ test('doctor refresh-known-words forwards app refresh command without requiring
   });
 });
 
+test('launcher config option forwards app configuration window command', () => {
+  withTempDir((root) => {
+    const homeDir = path.join(root, 'home');
+    const xdgConfigHome = path.join(root, 'xdg');
+    const appPath = path.join(root, 'fake-subminer.sh');
+    const capturePath = path.join(root, 'captured-args.txt');
+    fs.writeFileSync(
+      appPath,
+      '#!/bin/sh\nif [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n',
+    );
+    fs.chmodSync(appPath, 0o755);
+
+    const env = {
+      ...makeTestEnv(homeDir, xdgConfigHome),
+      SUBMINER_APPIMAGE_PATH: appPath,
+      SUBMINER_TEST_CAPTURE: capturePath,
+    };
+    const result = runLauncher(['--config'], env);
+
+    assert.equal(result.status, 0);
+    assert.equal(fs.readFileSync(capturePath, 'utf8'), '--config\n');
+  });
+});
+
+test('launcher config command forwards app configuration window command', () => {
+  withTempDir((root) => {
+    const homeDir = path.join(root, 'home');
+    const xdgConfigHome = path.join(root, 'xdg');
+    const appPath = path.join(root, 'fake-subminer.sh');
+    const capturePath = path.join(root, 'captured-args.txt');
+    fs.writeFileSync(
+      appPath,
+      '#!/bin/sh\nif [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n',
+    );
+    fs.chmodSync(appPath, 0o755);
+
+    const env = {
+      ...makeTestEnv(homeDir, xdgConfigHome),
+      SUBMINER_APPIMAGE_PATH: appPath,
+      SUBMINER_TEST_CAPTURE: capturePath,
+    };
+    const result = runLauncher(['config'], env);
+
+    assert.equal(result.status, 0);
+    assert.equal(fs.readFileSync(capturePath, 'utf8'), '--config\n');
+  });
+});
+
 test('launcher forwards --args to mpv as parsed tokens', { timeout: 15000 }, () => {
   withTempDir((root) => {
     const homeDir = path.join(root, 'home');

launcher/main.ts

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import packageJson from '../package.json';
 import {
   loadLauncherJellyfinConfig,
   loadLauncherMpvConfig,
@@ -20,6 +21,11 @@ import { runJellyfinCommand } from './commands/jellyfin-command.js';
 import { runPlaybackCommand } from './commands/playback-command.js';
 import { runUpdateCommand } from './commands/update-command.js';
 
+const APP_VERSION =
+  typeof packageJson.version === 'string' && packageJson.version.trim()
+    ? packageJson.version
+    : 'unknown';
+
 function createCommandContext(
   args: ReturnType<typeof parseArgs>,
   scriptPath: string,
@@ -56,6 +62,12 @@ async function main(): Promise<void> {
   const launcherConfig = loadLauncherYoutubeSubgenConfig();
   const launcherMpvConfig = loadLauncherMpvConfig();
   const args = parseArgs(process.argv.slice(2), scriptName, launcherConfig, launcherMpvConfig);
+
+  if (args.version) {
+    console.log(`SubMiner ${APP_VERSION}`);
+    return;
+  }
+
   const pluginRuntimeConfig = readPluginRuntimeConfig(args.logLevel);
   const appPath = findAppBinary(scriptPath);
 

launcher/mpv.test.ts

@@ -529,6 +529,8 @@ function makeArgs(overrides: Partial<Args> = {}): Args {
     stats: false,
     doctor: false,
     doctorRefreshKnownWords: false,
+    version: false,
+    configSettings: false,
     configPath: false,
     configShow: false,
     mpvIdle: false,

launcher/parse-args.test.ts

@@ -57,6 +57,12 @@ test('parseArgs captures mpv args string', () => {
   assert.equal(parsed.mpvArgs, '--pause=yes --title="movie night"');
 });
 
+test('parseArgs maps root config window option', () => {
+  const parsed = parseArgs(['--config'], 'subminer', {});
+
+  assert.equal(parsed.configSettings, true);
+});
+
 test('parseArgs maps root update flags without conflicting with jellyfin username', () => {
   const shortParsed = parseArgs(['-u'], 'subminer', {});
   const longParsed = parseArgs(['--update'], 'subminer', {});
@@ -69,6 +75,17 @@ test('parseArgs maps root update flags without conflicting with jellyfin usernam
   assert.equal(jellyfinParsed.jellyfinUsername, 'kyle');
 });
 
+test('parseArgs maps root version flags without conflicting with stats vocab flag', () => {
+  const shortParsed = parseArgs(['-v'], 'subminer', {});
+  const longParsed = parseArgs(['--version'], 'subminer', {});
+  const statsParsed = parseArgs(['stats', 'cleanup', '-v'], 'subminer', {});
+
+  assert.equal(shortParsed.version, true);
+  assert.equal(longParsed.version, true);
+  assert.equal(statsParsed.version, false);
+  assert.equal(statsParsed.statsCleanupVocab, true);
+});
+
 test('parseArgs maps jellyfin play action and log-level override', () => {
   const parsed = parseArgs(['jellyfin', 'play', '--log-level', 'debug'], 'subminer', {});
 
@@ -90,6 +107,33 @@ test('parseArgs maps config show action', () => {
   assert.equal(parsed.configPath, false);
 });
 
+test('parseArgs maps bare config command to settings window', () => {
+  const parsed = parseArgs(['config'], 'subminer', {});
+
+  assert.equal(parsed.configSettings, true);
+  assert.equal(parsed.configPath, false);
+  assert.equal(parsed.configShow, false);
+});
+
+test('parseArgs maps config path action to config path output', () => {
+  const parsed = parseArgs(['config', 'path'], 'subminer', {});
+
+  assert.equal(parsed.configPath, true);
+  assert.equal(parsed.configSettings, false);
+});
+
+test('parseArgs rejects removed config open and launch actions', () => {
+  const openExit = withProcessExitIntercept(() => {
+    parseArgs(['config', 'open'], 'subminer', {});
+  });
+  const exit = withProcessExitIntercept(() => {
+    parseArgs(['config', 'launch'], 'subminer', {});
+  });
+
+  assert.equal(openExit.code, 1);
+  assert.equal(exit.code, 1);
+});
+
 test('parseArgs maps mpv idle action', () => {
   const parsed = parseArgs(['mpv', 'idle'], 'subminer', {});
 

launcher/types.ts

@@ -134,7 +134,9 @@ export interface Args {
   dictionaryTarget?: string;
   doctor: boolean;
   doctorRefreshKnownWords: boolean;
+  version: boolean;
   update?: boolean;
+  configSettings: boolean;
   configPath: boolean;
   configShow: boolean;
   mpvIdle: boolean;

package.json

@@ -18,8 +18,9 @@
     "build:launcher": "bun build ./launcher/main.ts --target=bun --packages=bundle --banner='#!/usr/bin/env bun' --outfile=dist/launcher/subminer",
     "build:stats": "cd stats && bun run build",
     "dev:stats": "cd stats && bun run dev",
-    "build": "bun run build:yomitan && bun run build:stats && tsc -p tsconfig.json && bun run build:renderer && bun run build:launcher && bun run build:assets",
+    "build": "bun run build:yomitan && bun run build:stats && tsc -p tsconfig.json && bun run build:renderer && bun run build:settings && bun run build:launcher && bun run build:assets",
     "build:renderer": "esbuild src/renderer/renderer.ts --bundle --platform=browser --format=esm --target=es2022 --outfile=dist/renderer/renderer.js --sourcemap",
+    "build:settings": "esbuild src/settings/settings.ts --bundle --platform=browser --format=esm --target=es2022 --outfile=dist/settings/settings.js --sourcemap",
     "changelog:build": "bun run scripts/build-changelog.ts build-release",
     "changelog:check": "bun run scripts/build-changelog.ts check",
     "changelog:docs": "bun run scripts/build-changelog.ts docs",
@@ -39,6 +40,7 @@
     "lint": "bun run lint:stats",
     "docs:dev": "bun run --cwd docs-site docs:dev",
     "docs:build": "bun run --cwd docs-site docs:build",
+    "docs:build:versioned": "bun run scripts/build-versioned-docs.ts",
     "docs:preview": "bun run --cwd docs-site docs:preview",
     "docs:test": "bun run --cwd docs-site test",
     "test:docs:kb": "bun test scripts/docs-knowledge-base.test.ts",
@@ -48,7 +50,7 @@
     "test:plugin:src": "lua scripts/test-plugin-lua-compat.lua && lua scripts/test-plugin-start-gate.lua && lua scripts/test-plugin-session-bindings.lua && lua scripts/test-plugin-binary-windows.lua",
     "test:launcher:smoke:src": "bun test launcher/smoke.e2e.test.ts",
     "test:launcher:src": "bun test launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/mpv.test.ts launcher/picker.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/commands/update-command.test.ts launcher/smoke.e2e.test.ts && bun run test:plugin:src",
-    "test:core:src": "bun test src/cli/args.test.ts src/cli/help.test.ts src/shared/setup-state.test.ts src/core/services/cli-command.test.ts src/core/services/field-grouping-overlay.test.ts src/core/services/numeric-shortcut-session.test.ts src/core/services/secondary-subtitle.test.ts src/core/services/mpv-render-metrics.test.ts src/core/services/overlay-content-measurement.test.ts src/core/services/mpv-control.test.ts src/core/services/mpv.test.ts src/core/services/runtime-options-ipc.test.ts src/core/services/runtime-config.test.ts src/core/services/yomitan-extension-paths.test.ts src/core/services/yomitan-extension-loader.test.ts src/core/services/yomitan-settings.test.ts src/core/services/config-hot-reload.test.ts src/core/services/discord-presence.test.ts src/core/services/tokenizer.test.ts src/core/services/tokenizer/annotation-stage.test.ts src/core/services/tokenizer/parser-selection-stage.test.ts src/core/services/tokenizer/parser-enrichment-stage.test.ts src/core/services/subsync.test.ts src/core/services/overlay-bridge.test.ts src/core/services/overlay-shortcut-handler.test.ts src/core/services/stats-window.test.ts src/core/services/__tests__/stats-server.test.ts src/main/runtime/stats-server-routing.test.ts src/core/services/mining.test.ts src/core/services/anki-jimaku.test.ts src/core/services/jimaku-download-path.test.ts src/core/services/jellyfin.test.ts src/core/services/jellyfin-remote.test.ts src/core/services/immersion-tracker-service.test.ts src/core/services/overlay-runtime-init.test.ts src/core/services/app-ready.test.ts src/core/services/startup-bootstrap.test.ts src/core/services/subtitle-processing-controller.test.ts src/core/services/anilist/anilist-update-queue.test.ts src/core/services/anilist/rate-limiter.test.ts src/core/services/jlpt-token-filter.test.ts src/core/services/subtitle-position.test.ts src/core/utils/shortcut-config.test.ts src/main/runtime/first-run-setup-plugin.test.ts src/main/runtime/first-run-setup-service.test.ts src/main/runtime/first-run-setup-window.test.ts src/main/runtime/command-line-launcher.test.ts src/main/runtime/tray-runtime.test.ts src/main/runtime/tray-main-actions.test.ts src/main/runtime/tray-main-deps.test.ts src/main/runtime/tray-runtime-handlers.test.ts src/main/runtime/cli-command-context-main-deps.test.ts src/main/runtime/app-ready-main-deps.test.ts src/main/runtime/update/appimage-updater.test.ts src/main/runtime/update/update-dialogs.test.ts src/main/runtime/update/support-assets.test.ts src/renderer/error-recovery.test.ts src/renderer/subtitle-render.test.ts src/renderer/handlers/mouse.test.ts src/renderer/handlers/keyboard.test.ts src/renderer/modals/jimaku.test.ts src/subsync/utils.test.ts src/main/anilist-url-guard.test.ts src/window-trackers/hyprland-tracker.test.ts src/window-trackers/x11-tracker.test.ts src/window-trackers/windows-helper.test.ts src/window-trackers/windows-tracker.test.ts launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/commands/update-command.test.ts launcher/setup-gate.test.ts stats/src/lib/api-client.test.ts stats/src/hooks/useExcludedWords.test.ts stats/src/styles/globals.test.ts",
+    "test:core:src": "bun test src/preload-settings.test.ts src/cli/args.test.ts src/cli/help.test.ts src/shared/setup-state.test.ts src/core/services/cli-command.test.ts src/core/services/field-grouping-overlay.test.ts src/core/services/numeric-shortcut-session.test.ts src/core/services/secondary-subtitle.test.ts src/core/services/mpv-render-metrics.test.ts src/core/services/overlay-content-measurement.test.ts src/core/services/mpv-control.test.ts src/core/services/mpv.test.ts src/core/services/runtime-options-ipc.test.ts src/core/services/runtime-config.test.ts src/core/services/yomitan-extension-paths.test.ts src/core/services/yomitan-extension-loader.test.ts src/core/services/yomitan-settings.test.ts src/core/services/config-hot-reload.test.ts src/core/services/discord-presence.test.ts src/core/services/tokenizer.test.ts src/core/services/tokenizer/annotation-stage.test.ts src/core/services/tokenizer/parser-selection-stage.test.ts src/core/services/tokenizer/parser-enrichment-stage.test.ts src/core/services/subsync.test.ts src/core/services/overlay-bridge.test.ts src/core/services/overlay-shortcut-handler.test.ts src/core/services/stats-window.test.ts src/core/services/__tests__/stats-server.test.ts src/main/runtime/stats-server-routing.test.ts src/core/services/mining.test.ts src/core/services/anki-jimaku.test.ts src/core/services/jimaku-download-path.test.ts src/core/services/jellyfin.test.ts src/core/services/jellyfin-remote.test.ts src/core/services/immersion-tracker-service.test.ts src/core/services/overlay-runtime-init.test.ts src/core/services/app-ready.test.ts src/core/services/startup-bootstrap.test.ts src/core/services/subtitle-processing-controller.test.ts src/core/services/anilist/anilist-update-queue.test.ts src/core/services/anilist/rate-limiter.test.ts src/core/services/jlpt-token-filter.test.ts src/core/services/subtitle-position.test.ts src/core/utils/shortcut-config.test.ts src/main/runtime/startup-mode-flags.test.ts src/main/runtime/first-run-setup-plugin.test.ts src/main/runtime/first-run-setup-service.test.ts src/main/runtime/first-run-setup-window.test.ts src/main/runtime/command-line-launcher.test.ts src/main/runtime/tray-runtime.test.ts src/main/runtime/tray-main-actions.test.ts src/main/runtime/tray-main-deps.test.ts src/main/runtime/tray-runtime-handlers.test.ts src/main/runtime/cli-command-context-main-deps.test.ts src/main/runtime/app-ready-main-deps.test.ts src/main/runtime/update/appimage-updater.test.ts src/main/runtime/update/fetch-adapter.test.ts src/main/runtime/update/release-metadata-policy.test.ts src/main/runtime/update/update-dialogs.test.ts src/main/runtime/update/support-assets.test.ts src/renderer/error-recovery.test.ts src/renderer/subtitle-render.test.ts src/renderer/handlers/mouse.test.ts src/renderer/handlers/keyboard.test.ts src/renderer/modals/jimaku.test.ts src/subsync/utils.test.ts src/main/anilist-url-guard.test.ts src/window-trackers/hyprland-tracker.test.ts src/window-trackers/x11-tracker.test.ts src/window-trackers/windows-helper.test.ts src/window-trackers/windows-tracker.test.ts launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/commands/update-command.test.ts launcher/setup-gate.test.ts stats/src/lib/api-client.test.ts stats/src/hooks/useExcludedWords.test.ts",
     "test:core:dist": "bun test dist/cli/args.test.js dist/cli/help.test.js dist/core/services/cli-command.test.js dist/core/services/ipc.test.js dist/core/services/anki-jimaku-ipc.test.js dist/core/services/field-grouping-overlay.test.js dist/core/services/numeric-shortcut-session.test.js dist/core/services/secondary-subtitle.test.js dist/core/services/mpv-render-metrics.test.js dist/core/services/overlay-content-measurement.test.js dist/core/services/mpv-control.test.js dist/core/services/mpv.test.js dist/core/services/runtime-options-ipc.test.js dist/core/services/runtime-config.test.js dist/core/services/yomitan-extension-paths.test.js dist/core/services/config-hot-reload.test.js dist/core/services/discord-presence.test.js dist/core/services/tokenizer.test.js dist/core/services/tokenizer/annotation-stage.test.js dist/core/services/tokenizer/parser-selection-stage.test.js dist/core/services/tokenizer/parser-enrichment-stage.test.js dist/core/services/subsync.test.js dist/core/services/overlay-bridge.test.js dist/core/services/overlay-manager.test.js dist/core/services/overlay-shortcut-handler.test.js dist/core/services/mining.test.js dist/core/services/anki-jimaku.test.js dist/core/services/jimaku-download-path.test.js dist/core/services/jellyfin.test.js dist/core/services/jellyfin-remote.test.js dist/core/services/immersion-tracker-service.test.js dist/core/services/overlay-runtime-init.test.js dist/core/services/app-ready.test.js dist/core/services/startup-bootstrap.test.js dist/core/services/subtitle-processing-controller.test.js dist/core/services/anilist/anilist-token-store.test.js dist/core/services/anilist/anilist-update-queue.test.js dist/core/services/anilist/rate-limiter.test.js dist/core/services/jlpt-token-filter.test.js dist/core/services/subtitle-position.test.js dist/renderer/error-recovery.test.js dist/renderer/subtitle-render.test.js dist/renderer/handlers/mouse.test.js dist/renderer/handlers/keyboard.test.js dist/renderer/modals/jimaku.test.js dist/subsync/utils.test.js dist/main/anilist-url-guard.test.js dist/window-trackers/hyprland-tracker.test.js dist/window-trackers/x11-tracker.test.js dist/window-trackers/windows-helper.test.js dist/window-trackers/windows-tracker.test.js",
     "test:core:smoke:dist": "bun test dist/cli/help.test.js dist/core/services/runtime-config.test.js dist/core/services/ipc.test.js dist/core/services/overlay-manager.test.js dist/core/services/anilist/anilist-token-store.test.js dist/core/services/startup-bootstrap.test.js dist/renderer/error-recovery.test.js dist/main/anilist-url-guard.test.js dist/window-trackers/x11-tracker.test.js",
     "test:smoke:dist": "bun run test:config:smoke:dist && bun run test:core:smoke:dist",
@@ -70,7 +72,7 @@
     "test:launcher": "bun run test:launcher:src",
     "test:core": "bun run test:core:src",
     "test:subtitle": "bun run test:subtitle:src",
-    "test:fast": "bun run test:config:src && bun run test:core:src && bun run test:docs:kb && bun test src/main-entry-runtime.test.ts src/anki-integration.test.ts src/anki-integration/card-creation-manual-update.test.ts src/anki-integration/anki-connect-proxy.test.ts src/anki-integration/field-grouping-workflow.test.ts src/anki-integration/field-grouping.test.ts src/anki-integration/field-grouping-merge.test.ts src/release-workflow.test.ts src/prerelease-workflow.test.ts src/ci-workflow.test.ts scripts/build-changelog.test.ts scripts/electron-builder-after-pack.test.ts scripts/get-mpv-window-macos.test.ts scripts/mkv-to-readme-video.test.ts scripts/run-coverage-lane.test.ts scripts/update-aur-package.test.ts && bun test src/core/services/immersion-tracker/__tests__/query.test.ts src/core/services/immersion-tracker/__tests__/query-split-modules.test.ts && bun run tsc && bun test dist/main/runtime/registry.test.js",
+    "test:fast": "bun run test:config:src && bun run test:core:src && bun run test:docs:kb && bun test src/main-entry-runtime.test.ts src/anki-integration.test.ts src/anki-integration/card-creation-manual-update.test.ts src/anki-integration/anki-connect-proxy.test.ts src/anki-integration/field-grouping-workflow.test.ts src/anki-integration/field-grouping.test.ts src/anki-integration/field-grouping-merge.test.ts src/release-workflow.test.ts src/prerelease-workflow.test.ts src/ci-workflow.test.ts scripts/docs-versioning.test.ts scripts/docs-versioned-assets.test.ts scripts/build-changelog.test.ts scripts/electron-builder-after-pack.test.ts scripts/get-mpv-window-macos.test.ts scripts/mkv-to-readme-video.test.ts scripts/run-coverage-lane.test.ts scripts/update-aur-package.test.ts && bun test src/core/services/immersion-tracker/__tests__/query.test.ts src/core/services/immersion-tracker/__tests__/query-split-modules.test.ts && bun run tsc && bun test dist/main/runtime/registry.test.js",
     "generate:config-example": "bun run src/generate-config-example.ts",
     "verify:config-example": "bun run src/verify-config-example.ts",
     "start": "bun run build && electron . --start",
@@ -116,6 +118,7 @@
     "jsonc-parser": "^3.3.1",
     "koffi": "^2.15.6",
     "libsql": "^0.5.22",
+    "vscode-json-languageservice": "^5.7.2",
     "ws": "^8.19.0"
   },
   "devDependencies": {

release/prerelease-notes.md

@@ -3,33 +3,33 @@
 ## Highlights
 ### Added
 
-**Auto-Updater:** SubMiner can now check for and apply updates from the system tray or by running `subminer -u`. Checks include checksum verification, configurable notifications, and an opt-in channel for prerelease builds. The `subminer` launcher and Linux rofi theme are also updated automatically.
+- **Auto-Updater:** SubMiner can now check for and apply updates from the system tray or by running `subminer -u`. Checks include checksum verification, configurable notifications, and an opt-in channel for prerelease builds. The `subminer` launcher and Linux rofi theme are also updated automatically.
 
-**First-Run Setup:** A new optional setup flow installs Bun and the `subminer` command-line launcher on Linux, macOS, and Windows. Windows users get a `subminer.cmd` PATH shim so `subminer` works in any terminal without manually adding `SubMiner.exe` to PATH.
+- **First-Run Setup:** A new optional setup flow installs Bun and the `subminer` command-line launcher on Linux, macOS, and Windows. Windows users get a `subminer.cmd` PATH shim so `subminer` works in any terminal without manually adding `SubMiner.exe` to PATH.
 
 ### Fixed
 
-**macOS Overlay:** Significantly improved overlay focus and stability — the overlay now hides when mpv loses focus or is minimized, stays stable through transient window-tracking misses, remains correctly layered during stats mouse passthrough, and opens over fullscreen mpv without switching Spaces. Passthrough is also fixed so mpv controls stay clickable before hovering a subtitle bar. Background tracking overhead is reduced while mpv is stably focused.
+- **macOS Overlay:** Significantly improved overlay focus and stability: the overlay now hides when mpv loses focus or is minimized, stays stable through transient window-tracking misses, remains correctly layered during stats mouse passthrough, and opens over fullscreen mpv without switching Spaces. Passthrough is also fixed so mpv controls stay clickable before hovering a subtitle bar. Background tracking overhead is reduced while mpv is stably focused.
 
-**Subtitle Sync Modal:** Fixed a macOS issue where opening the subtitle sync modal would flash and disappear on the first attempt, or leave stale state after syncing.
+- **Subtitle Sync Modal:** Fixed a macOS issue where opening the subtitle sync modal would flash and disappear on the first attempt, or leave stale state after syncing.
 
-**Controller:** Controller config and debug shortcuts now stay closed while controller support is disabled, with a notice to enable `controller.enabled`. Learn mode can be entered from the edit pencil or binding badge, remaps are saved per controller profile, and individual bindings can be reset to their defaults.
+- **Controller:** Controller config and debug shortcuts now stay closed while controller support is disabled, with a notice to enable `controller.enabled`. Learn mode can be entered from the edit pencil or binding badge, remaps are saved per controller profile, and individual bindings can be reset to their defaults.
 
-**AniList Progress:** Progress threshold checks now use fresh playback position data, so updates fire correctly when playback reaches or skips past the watched threshold. Season-specific results are preferred for multi-season files, and a clear message is shown when the matched season is not in Planning or Watching status.
+- **AniList Progress:** Progress threshold checks now use fresh playback position data, so updates fire correctly when playback reaches or skips past the watched threshold. Season-specific results are preferred for multi-season files, and a clear message is shown when the matched season is not in Planning or Watching status.
 
-**Character Dictionary:** Cached media matches are reused when loading a title with an existing snapshot, avoiding redundant AniList search requests on repeat visits.
+- **Character Dictionary:** Cached media matches are reused when loading a title with an existing snapshot, avoiding redundant AniList search requests on repeat visits.
 
-**Updater — Linux:** The tray app now uses GitHub release metadata for update checks instead of the native Electron updater, preventing crashes. `subminer -u` performs updates independently of any running tray instance and correctly reports "up to date" without downloading assets when no newer release exists.
+- **Updater - Linux:** The tray app now uses GitHub release metadata for update checks instead of the native Electron updater, preventing crashes. `subminer -u` performs updates independently of any running tray instance and correctly reports "up to date" without downloading assets when no newer release exists.
 
-**Updater — macOS:** Update dialogs now come to the front when launched from `subminer --update`. Builds that cannot install native updates show a manual-install message instead of an inapplicable restart prompt. Signed macOS builds remain on the native updater path without triggering premature Squirrel install checks.
+- **Updater - macOS:** Update dialogs now come to the front when launched from `subminer --update`. Builds that cannot install native updates show a manual-install message instead of an inapplicable restart prompt. Signed macOS builds remain on the native updater path without triggering premature Squirrel install checks.
 
-**Setup — macOS:** First-run setup now recognizes existing `subminer` launcher installs in Homebrew or user PATH directories, and manual setup avoids writing into Homebrew-owned paths. `subminer app --setup` opens the setup flow even when SubMiner is already running in the background. The standalone setup app quits after completing first-run setup, returning control to the terminal.
+- **Setup - macOS:** First-run setup now recognizes existing `subminer` launcher installs in Homebrew or user PATH directories, and manual setup avoids writing into Homebrew-owned paths. `subminer app --setup` opens the setup flow even when SubMiner is already running in the background. The standalone setup app quits after completing first-run setup, returning control to the terminal.
 
-**Launcher — Linux:** First-run launcher installs are now built with a valid Bun shebang, fixing installs that previously failed silently.
+- **Launcher - Linux:** First-run launcher installs are now built with a valid Bun shebang, fixing installs that previously failed silently.
 
-**Tray App:** Fixed several lifecycle issues with tray-launched Yomitan settings: the tray stays running when settings are closed; settings loading no longer blocks other tray actions; the settings window uses a close-only menu to prevent accidentally quitting the tray app; an in-page close button is provided on Hyprland where native window controls are unavailable; the embedded popup preview is disabled to prevent renderer hangs during sidebar navigation; extension refreshes at startup are serialized to prevent race conditions; and the session help modal can now close correctly without mpv running.
+- **Tray App:** Fixed several lifecycle issues with tray-launched Yomitan settings: the tray stays running when settings are closed; settings loading no longer blocks other tray actions; the settings window uses a close-only menu to prevent accidentally quitting the tray app; an in-page close button is provided on Hyprland where native window controls are unavailable; the embedded popup preview is disabled to prevent renderer hangs during sidebar navigation; extension refreshes at startup are serialized to prevent race conditions; and the session help modal can now close correctly without mpv running.
 
-**Build — Linux Install:** Fixed one-shot `make clean build install` flows so the install step correctly picks up the AppImage produced earlier in the same make invocation.
+- **Build - Linux Install:** Fixed one-shot `make clean build install` flows so the install step correctly picks up the AppImage produced earlier in the same make invocation.
 
 ## Installation
 

scripts/build-versioned-docs.ts

@@ -0,0 +1,392 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  readlinkSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import {
+  collectSharedAssetPaths,
+  dedupeVersionedPublicAssets,
+  pruneArchiveCacheGenerations,
+} from './docs-versioned-assets';
+import {
+  buildVersionManifest,
+  stableTagsWithDocs,
+  versionArchiveCacheKey,
+  versionArchiveCacheName,
+  versionOutputPath,
+  versionPath,
+} from './docs-versioning';
+
+const repoRoot = resolve(__dirname, '..');
+const currentDocsSite = join(repoRoot, 'docs-site');
+const buildRoot = join(repoRoot, '.tmp/docs-versioned-build');
+const aggregateOutDir = join(repoRoot, '.tmp/docs-versioned-site');
+const archiveCacheRoot = join(repoRoot, '.tmp/docs-versioned-archive-cache');
+const maxCloudflareFiles = 20_000;
+const maxCloudflareFileBytes = 25 * 1024 * 1024;
+
+function run(
+  command: string,
+  args: string[],
+  options: { cwd?: string; env?: NodeJS.ProcessEnv } = {},
+) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd ?? repoRoot,
+    env: options.env ?? process.env,
+    stdio: 'inherit',
+  });
+
+  if (result.status !== 0) {
+    throw new Error(`Command failed: ${command} ${args.join(' ')}`);
+  }
+}
+
+function capture(command: string, args: string[]): string {
+  const result = spawnSync(command, args, {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+
+  if (result.status !== 0) {
+    throw new Error(result.stderr || `Command failed: ${command} ${args.join(' ')}`);
+  }
+
+  return result.stdout;
+}
+
+function archiveDocsSite(ref: string, targetDir: string) {
+  mkdirSync(targetDir, { recursive: true });
+  const archive = spawnSync('git', ['archive', '--format=tar', ref, 'docs-site'], {
+    cwd: repoRoot,
+    encoding: 'buffer',
+    maxBuffer: 1024 * 1024 * 1024,
+  });
+
+  if (archive.status !== 0 || !archive.stdout) {
+    throw new Error(`Unable to archive docs-site from ${ref}`);
+  }
+
+  const extract = spawnSync('tar', ['-x', '-C', targetDir], {
+    input: archive.stdout,
+    stdio: ['pipe', 'inherit', 'inherit'],
+  });
+
+  if (extract.status !== 0) {
+    throw new Error(`Unable to extract docs-site archive from ${ref}`);
+  }
+}
+
+function copyCurrentDocsSite(targetDir: string) {
+  mkdirSync(targetDir, { recursive: true });
+  cpSync(currentDocsSite, join(targetDir, 'docs-site'), {
+    recursive: true,
+    dereference: false,
+    filter: (source) =>
+      !/[\\/]node_modules([\\/]|$)/.test(source) &&
+      !/[\\/]\\.vitepress[\\/]dist([\\/]|$)/.test(source),
+  });
+}
+
+function overlayCurrentVitePress(snapshotDocsSite: string) {
+  const targetVitePress = join(snapshotDocsSite, '.vitepress');
+  rmSync(targetVitePress, { recursive: true, force: true });
+  cpSync(join(currentDocsSite, '.vitepress'), targetVitePress, {
+    recursive: true,
+    filter: (source) => !isGeneratedVitePressPath(source),
+  });
+
+  const currentThemeFonts = join(currentDocsSite, 'public/assets/fonts');
+  if (existsSync(currentThemeFonts)) {
+    cpSync(currentThemeFonts, join(snapshotDocsSite, 'public/assets/fonts'), {
+      recursive: true,
+      force: true,
+    });
+  }
+}
+
+function linkDocsDependencies(snapshotDocsSite: string) {
+  const currentNodeModules = join(currentDocsSite, 'node_modules');
+  const targetNodeModules = join(snapshotDocsSite, 'node_modules');
+
+  if (!existsSync(currentNodeModules) || existsSync(targetNodeModules)) {
+    return;
+  }
+
+  symlinkSync(currentNodeModules, targetNodeModules, 'dir');
+}
+
+function prepareSnapshot(name: string, ref?: string): string {
+  const snapshotRoot = join(buildRoot, name);
+  rmSync(snapshotRoot, { recursive: true, force: true });
+
+  if (ref) {
+    archiveDocsSite(ref, snapshotRoot);
+  } else {
+    copyCurrentDocsSite(snapshotRoot);
+  }
+
+  const snapshotDocsSite = join(snapshotRoot, 'docs-site');
+  overlayCurrentVitePress(snapshotDocsSite);
+  linkDocsDependencies(snapshotDocsSite);
+  return snapshotDocsSite;
+}
+
+function tagHasDocsSite(tag: string): boolean {
+  const result = spawnSync('git', ['cat-file', '-e', `${tag}:docs-site/package.json`], {
+    cwd: repoRoot,
+  });
+  return result.status === 0;
+}
+
+function getStableVersions(): string[] {
+  const tags = capture('git', ['tag', '--list', 'v*'])
+    .split('\n')
+    .map((tag) => tag.trim())
+    .filter(Boolean);
+  return stableTagsWithDocs(tags, tagHasDocsSite);
+}
+
+function buildDocs(options: {
+  snapshotDocsSite: string;
+  base: string;
+  outDir: string;
+  channel: string;
+  version?: string;
+  latestStable: string;
+  manifestJson: string;
+}) {
+  console.info(`[docs] building ${options.version ?? options.channel} -> ${options.base}`);
+  run('bun', ['run', '--cwd', currentDocsSite, 'vitepress', 'build', options.snapshotDocsSite], {
+    cwd: repoRoot,
+    env: {
+      ...process.env,
+      SUBMINER_DOCS_BASE: options.base,
+      SUBMINER_DOCS_OUT_DIR: options.outDir,
+      SUBMINER_DOCS_SOURCE_DIR: options.snapshotDocsSite,
+      SUBMINER_DOCS_CHANNEL: options.channel,
+      SUBMINER_DOCS_VERSION: options.version ?? '',
+      SUBMINER_DOCS_LATEST_STABLE: options.latestStable,
+      SUBMINER_DOCS_VERSION_MANIFEST: options.manifestJson,
+      VITE_EXTRA_EXTENSIONS: 'jsonc',
+    },
+  });
+}
+
+function updateHashWithPath(hash: ReturnType<typeof createHash>, path: string) {
+  if (isSharedInternalsHashIgnoredPath(path)) {
+    return;
+  }
+
+  const stat = lstatSync(path);
+  const relativePath = path.replace(repoRoot, '');
+
+  if (stat.isSymbolicLink()) {
+    hash.update(`symlink:${relativePath}`);
+    hash.update(readlinkSync(path));
+    return;
+  }
+
+  if (stat.isDirectory()) {
+    hash.update(`dir:${relativePath}`);
+    for (const entry of readdirSync(path).sort()) {
+      updateHashWithPath(hash, join(path, entry));
+    }
+    return;
+  }
+
+  hash.update(`file:${relativePath}`);
+  hash.update(readFileSync(path));
+}
+
+function isGeneratedVitePressPath(path: string): boolean {
+  return /[\\/]\\.vitepress[\\/](cache|dist)([\\/]|$)/.test(path);
+}
+
+function isSharedInternalsHashIgnoredPath(path: string): boolean {
+  return isGeneratedVitePressPath(path) || /\.test\.[cm]?[jt]s$/.test(path);
+}
+
+function computeSharedInternalsHash(): string {
+  const hash = createHash('sha256');
+  hash.update(
+    `version-link-origin:${process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN === 'local' ? 'local' : 'production'}`,
+  );
+  const paths = [
+    join(currentDocsSite, '.vitepress'),
+    join(currentDocsSite, 'public/assets/fonts'),
+    join(currentDocsSite, 'package.json'),
+    join(currentDocsSite, 'bun.lock'),
+    join(repoRoot, 'scripts/build-versioned-docs.ts'),
+    join(repoRoot, 'scripts/docs-versioning.ts'),
+  ];
+
+  for (const path of paths) {
+    if (existsSync(path)) {
+      updateHashWithPath(hash, path);
+    }
+  }
+
+  return hash.digest('hex');
+}
+
+function archiveCachePath(version: string, sharedInternalsHash: string): string {
+  return join(archiveCacheRoot, versionArchiveCacheName(version, sharedInternalsHash));
+}
+
+function restoreCachedArchive(version: string, sharedInternalsHash: string): boolean {
+  const cachedArchive = archiveCachePath(version, sharedInternalsHash);
+  if (!existsSync(cachedArchive)) {
+    return false;
+  }
+
+  console.info(`[docs] cache hit ${version}`);
+  cpSync(cachedArchive, join(aggregateOutDir, versionOutputPath(version)), {
+    recursive: true,
+    force: true,
+  });
+  return true;
+}
+
+function saveArchiveCache(version: string, sharedInternalsHash: string) {
+  const outputPath = join(aggregateOutDir, versionOutputPath(version));
+  if (!existsSync(outputPath)) {
+    return;
+  }
+
+  const cachedArchive = archiveCachePath(version, sharedInternalsHash);
+  rmSync(cachedArchive, { recursive: true, force: true });
+  mkdirSync(archiveCacheRoot, { recursive: true });
+  cpSync(outputPath, cachedArchive, { recursive: true, force: true });
+}
+
+function assertCloudflarePagesLimits(root: string) {
+  let fileCount = 0;
+  const oversizedFiles: string[] = [];
+
+  function walk(dir: string) {
+    for (const entry of readdirSync(dir)) {
+      const path = join(dir, entry);
+      const stat = lstatSync(path);
+      if (stat.isSymbolicLink()) {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        walk(path);
+        continue;
+      }
+
+      fileCount += 1;
+      if (stat.size > maxCloudflareFileBytes) {
+        oversizedFiles.push(path);
+      }
+    }
+  }
+
+  walk(root);
+
+  if (fileCount > maxCloudflareFiles) {
+    throw new Error(
+      `Versioned docs output has ${fileCount} files; Cloudflare Pages free plan limit is ${maxCloudflareFiles}.`,
+    );
+  }
+
+  if (oversizedFiles.length > 0) {
+    throw new Error(`Versioned docs output has files over 25 MiB:\n${oversizedFiles.join('\n')}`);
+  }
+}
+
+function main() {
+  const stableVersions = getStableVersions();
+  const latestStable = stableVersions[0];
+
+  if (!latestStable) {
+    throw new Error('No stable release tags with docs-site/package.json found.');
+  }
+
+  const manifest = buildVersionManifest({ latestStable, stableVersions });
+  const manifestJson = JSON.stringify(manifest);
+  const sharedInternalsHash = computeSharedInternalsHash();
+  const archiveCacheKey = versionArchiveCacheKey({ sharedInternalsHash, manifestJson });
+  const sharedAssetPaths = collectSharedAssetPaths(join(currentDocsSite, 'public/assets'));
+  console.info(`[docs] archive cache key ${archiveCacheKey.slice(0, 12)}`);
+
+  rmSync(buildRoot, { recursive: true, force: true });
+  rmSync(aggregateOutDir, { recursive: true, force: true });
+  mkdirSync(buildRoot, { recursive: true });
+  mkdirSync(aggregateOutDir, { recursive: true });
+
+  const latestStableSnapshot = prepareSnapshot(latestStable, latestStable);
+  buildDocs({
+    snapshotDocsSite: latestStableSnapshot,
+    base: '/',
+    outDir: aggregateOutDir,
+    channel: 'stable-root',
+    version: latestStable,
+    latestStable,
+    manifestJson,
+  });
+
+  for (const version of stableVersions) {
+    if (restoreCachedArchive(version, archiveCacheKey)) {
+      continue;
+    }
+
+    console.info(`[docs] rebuilding archive ${version}`);
+    const snapshot =
+      version === latestStable ? latestStableSnapshot : prepareSnapshot(version, version);
+    buildDocs({
+      snapshotDocsSite: snapshot,
+      base: versionPath(version),
+      outDir: join(aggregateOutDir, versionOutputPath(version)),
+      channel: 'stable-archive',
+      version,
+      latestStable,
+      manifestJson,
+    });
+    dedupeVersionedPublicAssets({
+      outDir: join(aggregateOutDir, versionOutputPath(version)),
+      base: versionPath(version),
+      sharedAssetPaths,
+    });
+    saveArchiveCache(version, archiveCacheKey);
+  }
+
+  const mainSnapshot = prepareSnapshot('main');
+  buildDocs({
+    snapshotDocsSite: mainSnapshot,
+    base: '/main/',
+    outDir: join(aggregateOutDir, 'main'),
+    channel: 'main',
+    version: 'main',
+    latestStable,
+    manifestJson,
+  });
+  dedupeVersionedPublicAssets({
+    outDir: join(aggregateOutDir, 'main'),
+    base: '/main/',
+    sharedAssetPaths,
+  });
+
+  writeFileSync(join(aggregateOutDir, 'versions.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+  assertCloudflarePagesLimits(aggregateOutDir);
+  const prunedArchives = pruneArchiveCacheGenerations({
+    cacheRoot: archiveCacheRoot,
+    activeCacheKey: archiveCacheKey,
+  });
+  if (prunedArchives.length > 0) {
+    console.info(`[docs] pruned ${prunedArchives.length} stale archive cache directories`);
+  }
+  rmSync(buildRoot, { recursive: true, force: true });
+}
+
+main();

scripts/docs-versioned-assets.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, test } from 'bun:test';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  dedupeVersionedPublicAssets,
+  pruneArchiveCacheGenerations,
+  rewriteSharedAssetReferences,
+} from './docs-versioned-assets';
+
+function tempDir() {
+  return mkdtempSync(join(tmpdir(), 'subminer-docs-versioned-assets-'));
+}
+
+describe('docs versioned asset dedupe', () => {
+  test('rewrites version-scoped public asset references to shared root assets', () => {
+    const html =
+      '<link href="/v/0.14.0/assets/style.hash.css"><source src="/v/0.14.0/assets/minecard.webm">';
+    const expected =
+      '<link href="/v/0.14.0/assets/style.hash.css"><source src="/assets/minecard.webm">';
+
+    expect(rewriteSharedAssetReferences(html, '/v/0.14.0/', new Set(['minecard.webm']))).toBe(
+      expected,
+    );
+    expect(rewriteSharedAssetReferences(html, '/v/0.14.0', new Set(['minecard.webm']))).toBe(
+      expected,
+    );
+  });
+
+  test('does not rewrite longer asset paths with a shared asset prefix', () => {
+    expect(
+      rewriteSharedAssetReferences(
+        [
+          '<script src="/v/0.14.0/assets/foo.js"></script>',
+          '<script src="/v/0.14.0/assets/foo.js?v=1"></script>',
+          '<script src="/v/0.14.0/assets/foo.js.map"></script>',
+        ].join(''),
+        '/v/0.14.0/',
+        new Set(['foo.js']),
+      ),
+    ).toBe(
+      [
+        '<script src="/assets/foo.js"></script>',
+        '<script src="/assets/foo.js?v=1"></script>',
+        '<script src="/v/0.14.0/assets/foo.js.map"></script>',
+      ].join(''),
+    );
+  });
+
+  test('removes duplicated version public assets while preserving generated VitePress assets', async () => {
+    const dir = tempDir();
+    try {
+      mkdirSync(join(dir, 'assets/chunks'), { recursive: true });
+      writeFileSync(join(dir, 'assets/style.hash.css'), 'body{}');
+      writeFileSync(join(dir, 'assets/chunks/theme.hash.js'), 'export {};');
+      writeFileSync(join(dir, 'assets/minecard.webm'), 'large video');
+      writeFileSync(
+        join(dir, 'index.html'),
+        '<link href="/v/0.14.0/assets/style.hash.css"><source src="/v/0.14.0/assets/minecard.webm">',
+      );
+
+      const result = dedupeVersionedPublicAssets({
+        outDir: dir,
+        base: '/v/0.14.0',
+        sharedAssetPaths: new Set(['minecard.webm']),
+      });
+
+      expect(result.rewrittenFiles).toEqual([join(dir, 'index.html')]);
+      expect(existsSync(join(dir, 'assets/style.hash.css'))).toBe(true);
+      expect(existsSync(join(dir, 'assets/chunks/theme.hash.js'))).toBe(true);
+      expect(existsSync(join(dir, 'assets/minecard.webm'))).toBe(false);
+      expect(readFileSync(join(dir, 'index.html'), 'utf8')).toBe(
+        '<link href="/v/0.14.0/assets/style.hash.css"><source src="/assets/minecard.webm">',
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('keeps root public assets because they are the shared copy', async () => {
+    const dir = tempDir();
+    try {
+      mkdirSync(join(dir, 'assets'), { recursive: true });
+      writeFileSync(join(dir, 'assets/minecard.webm'), 'large video');
+
+      const result = dedupeVersionedPublicAssets({
+        outDir: dir,
+        base: '/',
+        sharedAssetPaths: new Set(['minecard.webm']),
+      });
+
+      expect(result.removedAssetsDir).toBe(false);
+      expect(existsSync(join(dir, 'assets'))).toBe(true);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('docs archive cache pruning', () => {
+  test('removes stale cache generations while keeping the active generation', async () => {
+    const dir = tempDir();
+    try {
+      mkdirSync(join(dir, 'active123456-v0.14.0'), { recursive: true });
+      mkdirSync(join(dir, 'stale654321-v0.14.0'), { recursive: true });
+      mkdirSync(join(dir, 'stale654321-v0.13.0'), { recursive: true });
+
+      const removed = pruneArchiveCacheGenerations({
+        cacheRoot: dir,
+        activeCacheKey: 'active123456abcdef',
+      });
+
+      expect(removed.sort()).toEqual([
+        join(dir, 'stale654321-v0.13.0'),
+        join(dir, 'stale654321-v0.14.0'),
+      ]);
+      expect(existsSync(join(dir, 'active123456-v0.14.0'))).toBe(true);
+      expect(existsSync(join(dir, 'stale654321-v0.14.0'))).toBe(false);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

scripts/docs-versioned-assets.ts

@@ -0,0 +1,148 @@
+import { existsSync, lstatSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const textOutputPattern = /\.(?:css|html|js|json|map|mjs|txt|xml)$/;
+
+function normalizeBase(base: string): string {
+  return base === '/' ? '/' : `${base.replace(/\/+$/, '')}/`;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function collectSharedAssetPaths(publicAssetsDir: string): Set<string> {
+  if (!existsSync(publicAssetsDir)) {
+    return new Set();
+  }
+
+  return new Set(
+    walkFiles(publicAssetsDir).map((file) => relative(publicAssetsDir, file).split('\\').join('/')),
+  );
+}
+
+export function rewriteSharedAssetReferences(
+  content: string,
+  base: string,
+  sharedAssetPaths: Set<string>,
+): string {
+  const normalizedBase = normalizeBase(base);
+  if (normalizedBase === '/') {
+    return content;
+  }
+
+  let rewritten = content;
+  const escapedBase = escapeRegExp(normalizedBase);
+  for (const assetPath of sharedAssetPaths) {
+    const escapedAssetPath = escapeRegExp(assetPath);
+    rewritten = rewritten.replace(
+      new RegExp(`${escapedBase}assets/${escapedAssetPath}(?=$|[?#"'()\\s<])`, 'g'),
+      `/assets/${assetPath}`,
+    );
+  }
+  return rewritten;
+}
+
+function walkFiles(root: string): string[] {
+  const files: string[] = [];
+
+  function walk(dir: string) {
+    for (const entry of readdirSync(dir)) {
+      const path = join(dir, entry);
+      const stat = lstatSync(path);
+      if (stat.isSymbolicLink()) {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        walk(path);
+        continue;
+      }
+      files.push(path);
+    }
+  }
+
+  walk(root);
+  return files;
+}
+
+export function dedupeVersionedPublicAssets(options: {
+  outDir: string;
+  base: string;
+  sharedAssetPaths: Set<string>;
+}): {
+  removedAssetsDir: boolean;
+  rewrittenFiles: string[];
+} {
+  const normalizedBase = normalizeBase(options.base);
+  const rewrittenFiles: string[] = [];
+
+  for (const file of walkFiles(options.outDir)) {
+    if (!textOutputPattern.test(file)) {
+      continue;
+    }
+
+    const before = readFileSync(file, 'utf8');
+    const after = rewriteSharedAssetReferences(before, normalizedBase, options.sharedAssetPaths);
+    if (after === before) {
+      continue;
+    }
+
+    writeFileSync(file, after);
+    rewrittenFiles.push(file);
+  }
+
+  const assetsDir = join(options.outDir, 'assets');
+  if (normalizedBase !== '/') {
+    for (const assetPath of options.sharedAssetPaths) {
+      rmSync(join(assetsDir, assetPath), { force: true });
+    }
+    removeEmptyDirectories(assetsDir);
+  }
+
+  const removedAssetsDir = !existsSync(assetsDir);
+  return { removedAssetsDir, rewrittenFiles };
+}
+
+function removeEmptyDirectories(root: string) {
+  if (!existsSync(root) || !lstatSync(root).isDirectory()) {
+    return;
+  }
+
+  for (const entry of readdirSync(root)) {
+    const path = join(root, entry);
+    if (lstatSync(path).isDirectory()) {
+      removeEmptyDirectories(path);
+    }
+  }
+
+  if (readdirSync(root).length === 0) {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+export function pruneArchiveCacheGenerations(options: {
+  cacheRoot: string;
+  activeCacheKey: string;
+}): string[] {
+  if (!existsSync(options.cacheRoot)) {
+    return [];
+  }
+
+  const activePrefix = options.activeCacheKey.slice(0, 12);
+  const removed: string[] = [];
+
+  for (const entry of readdirSync(options.cacheRoot)) {
+    const path = join(options.cacheRoot, entry);
+    if (!lstatSync(path).isDirectory()) {
+      continue;
+    }
+    if (entry.startsWith(`${activePrefix}-`)) {
+      continue;
+    }
+
+    rmSync(path, { recursive: true, force: true });
+    removed.push(path);
+  }
+
+  return removed;
+}

scripts/docs-versioning.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  buildVersionManifest,
+  compareStableVersionsDesc,
+  versionArchiveCacheKey,
+  isStableReleaseTag,
+  stableTagsWithDocs,
+  versionArchiveCacheName,
+  versionOutputPath,
+  versionPath,
+} from './docs-versioning';
+
+describe('docs versioning helpers', () => {
+  test('stable tag filtering excludes beta and rc tags', () => {
+    expect(isStableReleaseTag('v0.14.0')).toBe(true);
+    expect(isStableReleaseTag('v0.15.0-beta.3')).toBe(false);
+    expect(isStableReleaseTag('v0.15.0-rc.1')).toBe(false);
+  });
+
+  test('latest stable resolves to v0.14.0 when beta tags are present', () => {
+    const tags = ['v0.13.0', 'v0.15.0-beta.3', 'v0.14.0'].sort(compareStableVersionsDesc);
+
+    expect(tags[0]).toBe('v0.14.0');
+  });
+
+  test('tags before docs-site are skipped', () => {
+    const tags = ['v0.12.0', 'v0.13.0', 'v0.14.0'];
+    const hasDocsSite = (tag: string) => tag !== 'v0.12.0';
+
+    expect(stableTagsWithDocs(tags, hasDocsSite)).toEqual(['v0.14.0', 'v0.13.0']);
+  });
+
+  test('version manifest paths are normalized', () => {
+    expect(versionPath('v0.14.0')).toBe('/v/0.14.0/');
+    expect(
+      buildVersionManifest({
+        latestStable: 'v0.14.0',
+        stableVersions: ['v0.14.0'],
+      }),
+    ).toEqual({
+      latestStable: 'v0.14.0',
+      channels: [
+        { label: 'Latest stable', path: '/' },
+        { label: 'main', path: '/main/' },
+      ],
+      versions: [{ version: 'v0.14.0', path: '/v/0.14.0/' }],
+    });
+  });
+
+  test('archive cache names are normalized by version and shared internals hash', () => {
+    expect(versionArchiveCacheName('v0.14.0', 'abcdef1234567890')).toBe('abcdef123456-v0.14.0');
+  });
+
+  test('archive cache keys change when manifest contents change', () => {
+    const firstKey = versionArchiveCacheKey({
+      sharedInternalsHash: 'abcdef1234567890',
+      manifestJson: '{"latestStable":"v0.14.0"}',
+    });
+    const secondKey = versionArchiveCacheKey({
+      sharedInternalsHash: 'abcdef1234567890',
+      manifestJson: '{"latestStable":"v0.15.0"}',
+    });
+
+    expect(firstKey).not.toBe(secondKey);
+  });
+
+  test('archive output paths stay relative for filesystem joins', () => {
+    expect(versionOutputPath('v0.14.0')).toBe('v/0.14.0');
+  });
+});

scripts/docs-versioning.ts

@@ -0,0 +1,96 @@
+import { createHash } from 'node:crypto';
+
+export type DocsVersionEntry = {
+  version: string;
+  path: string;
+};
+
+export type DocsChannelEntry = {
+  label: string;
+  path: string;
+};
+
+export type DocsVersionManifest = {
+  latestStable: string;
+  channels: DocsChannelEntry[];
+  versions: DocsVersionEntry[];
+};
+
+const STABLE_TAG_PATTERN = /^v\d+\.\d+\.\d+$/;
+
+export function isStableReleaseTag(tag: string): boolean {
+  return STABLE_TAG_PATTERN.test(tag);
+}
+
+function parseStableVersion(tag: string): [number, number, number] {
+  const match = /^v(\d+)\.(\d+)\.(\d+)$/.exec(tag);
+  if (!match) {
+    throw new Error(`Invalid stable SubMiner version tag: ${tag}`);
+  }
+
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+export function compareStableVersionsDesc(a: string, b: string): number {
+  if (!isStableReleaseTag(a) && !isStableReleaseTag(b)) return a.localeCompare(b);
+  if (!isStableReleaseTag(a)) return 1;
+  if (!isStableReleaseTag(b)) return -1;
+
+  const parsedA = parseStableVersion(a);
+  const parsedB = parseStableVersion(b);
+
+  for (let index = 0; index < parsedA.length; index += 1) {
+    const difference = parsedB[index]! - parsedA[index]!;
+    if (difference !== 0) return difference;
+  }
+
+  return 0;
+}
+
+export function versionPath(version: string): string {
+  return `/v/${version.replace(/^v/, '')}/`;
+}
+
+export function versionOutputPath(version: string): string {
+  return `v/${version.replace(/^v/, '')}`;
+}
+
+export function versionArchiveCacheName(version: string, sharedInternalsHash: string): string {
+  return `${sharedInternalsHash.slice(0, 12)}-${version}`;
+}
+
+export function versionArchiveCacheKey(options: {
+  sharedInternalsHash: string;
+  manifestJson: string;
+}): string {
+  const hash = createHash('sha256');
+  hash.update('shared-internals:');
+  hash.update(options.sharedInternalsHash);
+  hash.update('\nmanifest:');
+  hash.update(options.manifestJson);
+  return hash.digest('hex');
+}
+
+export function stableTagsWithDocs(
+  tags: string[],
+  hasDocsSite: (tag: string) => boolean,
+): string[] {
+  return tags.filter(isStableReleaseTag).filter(hasDocsSite).sort(compareStableVersionsDesc);
+}
+
+export function buildVersionManifest(options: {
+  latestStable: string;
+  stableVersions: string[];
+}): DocsVersionManifest {
+  return {
+    latestStable: options.latestStable,
+    channels: [
+      { label: 'Latest stable', path: '/' },
+      { label: 'main', path: '/main/' },
+    ],
+    versions: options.stableVersions.map((version) => ({
+      version,
+      path: versionPath(version),
+    })),
+  };
+}

scripts/prepare-build-assets.mjs

@@ -7,6 +7,8 @@ const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(scriptDir, '..');
 const rendererSourceDir = path.join(repoRoot, 'src', 'renderer');
 const rendererOutputDir = path.join(repoRoot, 'dist', 'renderer');
+const settingsSourceDir = path.join(repoRoot, 'src', 'settings');
+const settingsOutputDir = path.join(repoRoot, 'dist', 'settings');
 const scriptsOutputDir = path.join(repoRoot, 'dist', 'scripts');
 const macosHelperSourcePath = path.join(scriptDir, 'get-mpv-window-macos.swift');
 const macosHelperBinaryPath = path.join(scriptsOutputDir, 'get-mpv-window-macos');
@@ -21,14 +23,22 @@ function copyFile(sourcePath, outputPath) {
   fs.copyFileSync(sourcePath, outputPath);
 }
 
-function copyRendererAssets() {
-  copyFile(path.join(rendererSourceDir, 'index.html'), path.join(rendererOutputDir, 'index.html'));
-  copyFile(path.join(rendererSourceDir, 'style.css'), path.join(rendererOutputDir, 'style.css'));
-  fs.cpSync(path.join(rendererSourceDir, 'fonts'), path.join(rendererOutputDir, 'fonts'), {
+function copyAssets(sourceDir, outputDir, label) {
+  copyFile(path.join(sourceDir, 'index.html'), path.join(outputDir, 'index.html'));
+  copyFile(path.join(sourceDir, 'style.css'), path.join(outputDir, 'style.css'));
+  fs.cpSync(path.join(rendererSourceDir, 'fonts'), path.join(outputDir, 'fonts'), {
     recursive: true,
     force: true,
   });
-  process.stdout.write(`Staged renderer assets in ${rendererOutputDir}\n`);
+  process.stdout.write(`Staged ${label} assets in ${outputDir}\n`);
+}
+
+function copyRendererAssets() {
+  copyAssets(rendererSourceDir, rendererOutputDir, 'renderer');
+}
+
+function copySettingsAssets() {
+  copyAssets(settingsSourceDir, settingsOutputDir, 'settings');
 }
 
 function fallbackToMacosSource() {
@@ -70,6 +80,7 @@ function buildMacosHelper() {
 
 function main() {
   copyRendererAssets();
+  copySettingsAssets();
   buildMacosHelper();
 }
 

scripts/print-docs-version-manifest.ts

@@ -0,0 +1,41 @@
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { buildVersionManifest, stableTagsWithDocs } from './docs-versioning';
+
+const repoRoot = resolve(__dirname, '..');
+
+function capture(command: string, args: string[]): string {
+  const result = spawnSync(command, args, {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+
+  if (result.status !== 0) {
+    throw new Error(result.stderr || `Command failed: ${command} ${args.join(' ')}`);
+  }
+
+  return result.stdout;
+}
+
+function tagHasDocsSite(tag: string): boolean {
+  const result = spawnSync('git', ['cat-file', '-e', `${tag}:docs-site/package.json`], {
+    cwd: repoRoot,
+  });
+  return result.status === 0;
+}
+
+const stableVersions = stableTagsWithDocs(
+  capture('git', ['tag', '--list', 'v*'])
+    .split('\n')
+    .map((tag) => tag.trim())
+    .filter(Boolean),
+  tagHasDocsSite,
+);
+
+const latestStable = stableVersions[0];
+
+if (!latestStable) {
+  throw new Error('No stable release tags with docs-site/package.json found.');
+}
+
+process.stdout.write(JSON.stringify(buildVersionManifest({ latestStable, stableVersions })));

src/ci-workflow.test.ts

@@ -5,6 +5,8 @@ import { resolve } from 'node:path';
 
 const ciWorkflowPath = resolve(__dirname, '../.github/workflows/ci.yml');
 const ciWorkflow = readFileSync(ciWorkflowPath, 'utf8');
+const docsPagesWorkflowPath = resolve(__dirname, '../.github/workflows/docs-pages.yml');
+const docsPagesWorkflow = readFileSync(docsPagesWorkflowPath, 'utf8');
 const packageJsonPath = resolve(__dirname, '../package.json');
 const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
   scripts: Record<string, string>;
@@ -36,3 +38,28 @@ test('ci workflow runs the maintained source coverage lane and uploads lcov outp
   assert.match(ciWorkflow, /name: Upload coverage artifact/);
   assert.match(ciWorkflow, /path: coverage\/test-src\/lcov\.info/);
 });
+
+test('main docs deploy exists, serializes deploys, and uses Cloudflare credentials', () => {
+  assert.match(docsPagesWorkflow, /name: Docs Pages/);
+  assert.match(docsPagesWorkflow, /branches:\s*\n\s*-\s*main/);
+  assert.match(docsPagesWorkflow, /group:\s*docs-pages-production/);
+  assert.match(docsPagesWorkflow, /CLOUDFLARE_API_TOKEN/);
+  assert.match(docsPagesWorkflow, /CLOUDFLARE_ACCOUNT_ID/);
+  assert.match(docsPagesWorkflow, /CLOUDFLARE_PAGES_PROJECT_NAME/);
+  assert.match(docsPagesWorkflow, /pages deploy \.tmp\/docs-versioned-site/);
+  assert.match(docsPagesWorkflow, /--branch main/);
+});
+
+test('docs deploy caches stable archive builds between runs', () => {
+  assert.match(docsPagesWorkflow, /actions\/cache@v4/);
+  assert.match(docsPagesWorkflow, /\.tmp\/docs-versioned-archive-cache/);
+  assert.match(docsPagesWorkflow, /docs-versioned-archives-/);
+  assert.match(docsPagesWorkflow, /docs-site\/\.vitepress\/\*\*/);
+});
+
+test('docs deploy skips invalid release tags without failing the workflow', () => {
+  assert.match(docsPagesWorkflow, /id:\s*tag_guard/);
+  assert.match(docsPagesWorkflow, /stable_tag=false/);
+  assert.doesNotMatch(docsPagesWorkflow, /exit 78/);
+  assert.match(docsPagesWorkflow, /if:\s*steps\.tag_guard\.outputs\.stable_tag != 'false'/);
+});

src/cli/args.test.ts

@@ -212,6 +212,14 @@ test('hasExplicitCommand and shouldStartApp preserve command intent', () => {
   assert.equal(shouldStartApp(settings), true);
   assert.equal(shouldRunSettingsOnlyStartup(settings), true);
 
+  const configSettings = parseArgs(['--config']);
+  assert.equal(configSettings.configSettings, true);
+  assert.equal(hasExplicitCommand(configSettings), true);
+  assert.equal(shouldStartApp(configSettings), true);
+  assert.equal(shouldRunSettingsOnlyStartup(configSettings), false);
+  assert.equal(commandNeedsOverlayRuntime(configSettings), false);
+  assert.equal(commandNeedsOverlayStartupPrereqs(configSettings), false);
+
   const settingsWithOverlay = parseArgs(['--settings', '--toggle-visible-overlay']);
   assert.equal(settingsWithOverlay.settings, true);
   assert.equal(settingsWithOverlay.toggleVisibleOverlay, true);

src/cli/args.ts

@@ -11,6 +11,7 @@ export interface CliArgs {
   toggleVisibleOverlay: boolean;
   togglePrimarySubtitleBar: boolean;
   settings: boolean;
+  configSettings: boolean;
   setup: boolean;
   show: boolean;
   hide: boolean;
@@ -115,6 +116,7 @@ export function parseArgs(argv: string[]): CliArgs {
     toggleVisibleOverlay: false,
     togglePrimarySubtitleBar: false,
     settings: false,
+    configSettings: false,
     setup: false,
     show: false,
     hide: false,
@@ -234,6 +236,7 @@ export function parseArgs(argv: string[]): CliArgs {
     else if (arg === '--toggle-visible-overlay') args.toggleVisibleOverlay = true;
     else if (arg === '--toggle-primary-subtitle-bar') args.togglePrimarySubtitleBar = true;
     else if (arg === '--settings' || arg === '--yomitan') args.settings = true;
+    else if (arg === '--config') args.configSettings = true;
     else if (arg === '--setup') args.setup = true;
     else if (arg === '--show') args.show = true;
     else if (arg === '--hide') args.hide = true;
@@ -486,6 +489,7 @@ export function hasExplicitCommand(args: CliArgs): boolean {
     args.toggleVisibleOverlay ||
     args.togglePrimarySubtitleBar ||
     args.settings ||
+    args.configSettings ||
     args.setup ||
     args.show ||
     args.hide ||
@@ -558,6 +562,7 @@ export function isStandaloneTexthookerCommand(args: CliArgs): boolean {
     !args.toggleVisibleOverlay &&
     !args.togglePrimarySubtitleBar &&
     !args.settings &&
+    !args.configSettings &&
     !args.setup &&
     !args.show &&
     !args.hide &&
@@ -625,6 +630,7 @@ export function shouldStartApp(args: CliArgs): boolean {
     args.toggleVisibleOverlay ||
     args.togglePrimarySubtitleBar ||
     args.settings ||
+    args.configSettings ||
     args.setup ||
     args.copySubtitle ||
     args.copySubtitleMultiple ||
@@ -679,6 +685,7 @@ export function shouldRunSettingsOnlyStartup(args: CliArgs): boolean {
     !args.toggle &&
     !args.toggleVisibleOverlay &&
     !args.togglePrimarySubtitleBar &&
+    !args.configSettings &&
     !args.show &&
     !args.hide &&
     !args.setup &&

src/cli/help.test.ts

@@ -22,6 +22,7 @@ test('printHelp includes configured texthooker port', () => {
   assert.match(output, /--open-browser\s+Open texthooker in your default browser/);
   assert.doesNotMatch(output, /--refresh-known-words/);
   assert.match(output, /--setup\s+Open first-run setup window/);
+  assert.match(output, /--config\s+Open configuration window/);
   assert.match(output, /--anilist-status/);
   assert.match(output, /--anilist-retry-queue/);
   assert.match(output, /--dictionary/);

src/cli/help.ts

@@ -25,6 +25,7 @@ ${B}Overlay${R}
   --show-visible-overlay         Show subtitle overlay
   --hide-visible-overlay         Hide subtitle overlay
   --settings                     Open Yomitan settings window
+  --config                       Open configuration window
   --setup                        Open first-run setup window
   --auto-start-overlay           Auto-hide mpv subs, show overlay on connect
 

src/config/config.test.ts

@@ -2324,7 +2324,10 @@ test('template generator includes known keys', () => {
     /"dpadFallback": "horizontal",? \/\/ Optional D-pad fallback used when this analog controller action should also read D-pad input\. Values: none \| horizontal \| vertical/,
   );
   assert.match(output, /"port": 6678,? \/\/ Annotated subtitle websocket server port\./);
-  assert.match(output, /"openBrowser": false,? \/\/ Open browser setting\. Values: true \| false/);
+  assert.match(
+    output,
+    /"openBrowser": false,? \/\/ Open the texthooker page in the default browser when the server starts\. Values: true \| false/,
+  );
   assert.match(
     output,
     /"enabled": false,? \/\/ Enable overlay controller support through the Chrome Gamepad API\. Values: true \| false/,

src/config/definitions/domain-registry.test.ts

@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 
+import { ResolvedConfig } from '../../types/config';
 import {
   CONFIG_OPTION_REGISTRY,
   CONFIG_TEMPLATE_SECTIONS,
@@ -13,6 +14,77 @@ import { buildImmersionConfigOptionRegistry } from './options-immersion';
 import { buildIntegrationConfigOptionRegistry } from './options-integrations';
 import { buildSubtitleConfigOptionRegistry } from './options-subtitle';
 
+function collectConfigLeafPaths(config: ResolvedConfig): string[] {
+  const leaves: string[] = [];
+  const visit = (value: unknown, prefix: string): void => {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+      leaves.push(prefix);
+      return;
+    }
+    const entries = Object.entries(value as Record<string, unknown>);
+    if (entries.length === 0) {
+      leaves.push(prefix);
+      return;
+    }
+    for (const [key, child] of entries) {
+      visit(child, prefix ? `${prefix}.${key}` : key);
+    }
+  };
+  visit(config, '');
+  return leaves;
+}
+
+// DEFAULT_CONFIG leaves that intentionally do not have a curated
+// CONFIG_OPTION_REGISTRY entry. The generated config.example.jsonc still
+// includes these paths, but their inline comments fall back to an auto-
+// humanized key name instead of a written description.
+//
+// Current intentional gaps:
+//   - subtitleStyle.*: thin wrappers around standard CSS properties; the
+//     CSS reference is the canonical documentation surface.
+//   - keybindings: an array of {key, command} objects, documented at the
+//     section level via CONFIG_TEMPLATE_SECTIONS rather than per-leaf.
+//
+// New leaves added to DEFAULT_CONFIG should prefer a registry entry over
+// an allowlist entry. Only allowlist a path when the registry is genuinely
+// the wrong surface for it.
+const UNDOCUMENTED_LEAVES: ReadonlySet<string> = new Set([
+  'keybindings',
+  'subtitleStyle.backdropFilter',
+  'subtitleStyle.backgroundColor',
+  'subtitleStyle.fontColor',
+  'subtitleStyle.fontFamily',
+  'subtitleStyle.fontKerning',
+  'subtitleStyle.fontSize',
+  'subtitleStyle.fontStyle',
+  'subtitleStyle.fontWeight',
+  'subtitleStyle.jlptColors.N1',
+  'subtitleStyle.jlptColors.N2',
+  'subtitleStyle.jlptColors.N3',
+  'subtitleStyle.jlptColors.N4',
+  'subtitleStyle.jlptColors.N5',
+  'subtitleStyle.knownWordColor',
+  'subtitleStyle.letterSpacing',
+  'subtitleStyle.lineHeight',
+  'subtitleStyle.nPlusOneColor',
+  'subtitleStyle.secondary.backdropFilter',
+  'subtitleStyle.secondary.backgroundColor',
+  'subtitleStyle.secondary.fontColor',
+  'subtitleStyle.secondary.fontFamily',
+  'subtitleStyle.secondary.fontKerning',
+  'subtitleStyle.secondary.fontSize',
+  'subtitleStyle.secondary.fontStyle',
+  'subtitleStyle.secondary.fontWeight',
+  'subtitleStyle.secondary.letterSpacing',
+  'subtitleStyle.secondary.lineHeight',
+  'subtitleStyle.secondary.textRendering',
+  'subtitleStyle.secondary.textShadow',
+  'subtitleStyle.secondary.wordSpacing',
+  'subtitleStyle.textRendering',
+  'subtitleStyle.textShadow',
+  'subtitleStyle.wordSpacing',
+]);
+
 test('config option registry includes critical paths and has unique entries', () => {
   const paths = CONFIG_OPTION_REGISTRY.map((entry) => entry.path);
 
@@ -40,6 +112,35 @@ test('config option registry includes critical paths and has unique entries', ()
   assert.equal(new Set(paths).size, paths.length);
 });
 
+test('every DEFAULT_CONFIG leaf is in CONFIG_OPTION_REGISTRY or UNDOCUMENTED_LEAVES', () => {
+  const registryPaths = new Set(CONFIG_OPTION_REGISTRY.map((entry) => entry.path));
+  const leaves = collectConfigLeafPaths(DEFAULT_CONFIG);
+
+  const missing = leaves
+    .filter((path) => !registryPaths.has(path) && !UNDOCUMENTED_LEAVES.has(path))
+    .sort();
+  assert.deepEqual(
+    missing,
+    [],
+    `Add CONFIG_OPTION_REGISTRY entries (preferred) or add to UNDOCUMENTED_LEAVES allowlist: ${missing.join(', ')}`,
+  );
+
+  const stale = [...UNDOCUMENTED_LEAVES].filter((path) => registryPaths.has(path)).sort();
+  assert.deepEqual(
+    stale,
+    [],
+    `Remove from UNDOCUMENTED_LEAVES (now covered by CONFIG_OPTION_REGISTRY): ${stale.join(', ')}`,
+  );
+
+  const leafSet = new Set(leaves);
+  const orphaned = [...UNDOCUMENTED_LEAVES].filter((path) => !leafSet.has(path)).sort();
+  assert.deepEqual(
+    orphaned,
+    [],
+    `Remove from UNDOCUMENTED_LEAVES (no longer a DEFAULT_CONFIG leaf): ${orphaned.join(', ')}`,
+  );
+});
+
 test('config template sections include expected domains and unique keys', () => {
   const keys = CONFIG_TEMPLATE_SECTIONS.map((section) => section.key);
   const requiredKeys: (typeof keys)[number][] = [

src/config/definitions/options-core.ts

@@ -322,6 +322,46 @@ export function buildCoreConfigOptionRegistry(
       defaultValue: defaultConfig.texthooker.launchAtStartup,
       description: 'Launch texthooker server automatically when SubMiner starts.',
     },
+    {
+      path: 'texthooker.openBrowser',
+      kind: 'boolean',
+      defaultValue: defaultConfig.texthooker.openBrowser,
+      description: 'Open the texthooker page in the default browser when the server starts.',
+    },
+    {
+      path: 'subtitlePosition.yPercent',
+      kind: 'number',
+      defaultValue: defaultConfig.subtitlePosition.yPercent,
+      description:
+        'Vertical position of the subtitle overlay expressed as a percentage from the bottom of the screen.',
+    },
+    {
+      path: 'auto_start_overlay',
+      kind: 'boolean',
+      defaultValue: defaultConfig.auto_start_overlay,
+      description: 'Auto-start the subtitle overlay window when SubMiner launches.',
+    },
+    {
+      path: 'secondarySub.secondarySubLanguages',
+      kind: 'array',
+      defaultValue: defaultConfig.secondarySub.secondarySubLanguages,
+      description:
+        'Language code priority list used to auto-select a secondary subtitle track when available.',
+    },
+    {
+      path: 'secondarySub.autoLoadSecondarySub',
+      kind: 'boolean',
+      defaultValue: defaultConfig.secondarySub.autoLoadSecondarySub,
+      description:
+        'Automatically load a matching secondary subtitle when the primary subtitle loads.',
+    },
+    {
+      path: 'secondarySub.defaultMode',
+      kind: 'enum',
+      enumValues: ['hidden', 'visible', 'hover'],
+      defaultValue: defaultConfig.secondarySub.defaultMode,
+      description: 'Default visibility mode for the secondary subtitle bar.',
+    },
     {
       path: 'websocket.enabled',
       kind: 'enum',
@@ -360,6 +400,27 @@ export function buildCoreConfigOptionRegistry(
       defaultValue: defaultConfig.subsync.replace,
       description: 'Replace the active subtitle file when sync completes.',
     },
+    {
+      path: 'subsync.alass_path',
+      kind: 'string',
+      defaultValue: defaultConfig.subsync.alass_path,
+      description:
+        'Optional absolute path to the alass binary used by subsync. Leave empty to auto-discover from PATH.',
+    },
+    {
+      path: 'subsync.ffsubsync_path',
+      kind: 'string',
+      defaultValue: defaultConfig.subsync.ffsubsync_path,
+      description:
+        'Optional absolute path to the ffsubsync binary used by subsync. Leave empty to auto-discover from PATH.',
+    },
+    {
+      path: 'subsync.ffmpeg_path',
+      kind: 'string',
+      defaultValue: defaultConfig.subsync.ffmpeg_path,
+      description:
+        'Optional absolute path to the ffmpeg binary used by subsync. Leave empty to auto-discover from PATH.',
+    },
     {
       path: 'startupWarmups.lowPowerMode',
       kind: 'boolean',
@@ -422,5 +483,112 @@ export function buildCoreConfigOptionRegistry(
       defaultValue: defaultConfig.shortcuts.multiCopyTimeoutMs,
       description: 'Timeout for multi-copy/mine modes.',
     },
+    {
+      path: 'shortcuts.toggleVisibleOverlayGlobal',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.toggleVisibleOverlayGlobal,
+      description:
+        'Global accelerator that toggles overlay visibility from anywhere on the system. Use null to disable.',
+    },
+    {
+      path: 'shortcuts.copySubtitle',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.copySubtitle,
+      description: 'Accelerator that copies the current subtitle line to the clipboard.',
+    },
+    {
+      path: 'shortcuts.copySubtitleMultiple',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.copySubtitleMultiple,
+      description:
+        'Accelerator that copies consecutive subtitle lines while the multi-copy window stays open.',
+    },
+    {
+      path: 'shortcuts.updateLastCardFromClipboard',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.updateLastCardFromClipboard,
+      description:
+        'Accelerator that updates the last mined Anki card using the current clipboard contents.',
+    },
+    {
+      path: 'shortcuts.triggerFieldGrouping',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.triggerFieldGrouping,
+      description: 'Accelerator that triggers Kiku field grouping on duplicate cards.',
+    },
+    {
+      path: 'shortcuts.triggerSubsync',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.triggerSubsync,
+      description: 'Accelerator that triggers subsync against the active subtitle file.',
+    },
+    {
+      path: 'shortcuts.mineSentence',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.mineSentence,
+      description: 'Accelerator that mines the current sentence as a new Anki card.',
+    },
+    {
+      path: 'shortcuts.mineSentenceMultiple',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.mineSentenceMultiple,
+      description:
+        'Accelerator that mines consecutive sentences while the multi-mine window stays open.',
+    },
+    {
+      path: 'shortcuts.toggleSecondarySub',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.toggleSecondarySub,
+      description: 'Accelerator that toggles the secondary subtitle bar visibility.',
+    },
+    {
+      path: 'shortcuts.markAudioCard',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.markAudioCard,
+      description: 'Accelerator that marks the last mined card as an audio card.',
+    },
+    {
+      path: 'shortcuts.openCharacterDictionary',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.openCharacterDictionary,
+      description: 'Accelerator that opens the character dictionary modal.',
+    },
+    {
+      path: 'shortcuts.openRuntimeOptions',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.openRuntimeOptions,
+      description: 'Accelerator that opens the runtime options modal.',
+    },
+    {
+      path: 'shortcuts.openJimaku',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.openJimaku,
+      description: 'Accelerator that opens the Jimaku subtitle search modal.',
+    },
+    {
+      path: 'shortcuts.openSessionHelp',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.openSessionHelp,
+      description: 'Accelerator that opens the session help / keybinding cheatsheet.',
+    },
+    {
+      path: 'shortcuts.openControllerSelect',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.openControllerSelect,
+      description: 'Accelerator that opens the controller selection and learn-mode modal.',
+    },
+    {
+      path: 'shortcuts.openControllerDebug',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.openControllerDebug,
+      description:
+        'Accelerator that opens the controller debug modal with live axis/button readouts.',
+    },
+    {
+      path: 'shortcuts.toggleSubtitleSidebar',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.toggleSubtitleSidebar,
+      description: 'Accelerator that toggles the subtitle sidebar visibility.',
+    },
   ];
 }

src/config/definitions/options-integrations.ts

@@ -15,6 +15,12 @@ export function buildIntegrationConfigOptionRegistry(
       defaultValue: defaultConfig.ankiConnect.enabled,
       description: 'Enable AnkiConnect integration.',
     },
+    {
+      path: 'ankiConnect.url',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.url,
+      description: 'Base URL of the AnkiConnect HTTP server.',
+    },
     {
       path: 'ankiConnect.pollingRate',
       kind: 'number',
@@ -58,6 +64,37 @@ export function buildIntegrationConfigOptionRegistry(
       defaultValue: defaultConfig.ankiConnect.fields.word,
       description: 'Card field for the mined word or expression text.',
     },
+    {
+      path: 'ankiConnect.fields.audio',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.fields.audio,
+      description: 'Card field that receives generated sentence audio.',
+    },
+    {
+      path: 'ankiConnect.fields.image',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.fields.image,
+      description: 'Card field that receives the captured screenshot or animated image.',
+    },
+    {
+      path: 'ankiConnect.fields.sentence',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.fields.sentence,
+      description: 'Card field that receives the source sentence text.',
+    },
+    {
+      path: 'ankiConnect.fields.miscInfo',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.fields.miscInfo,
+      description:
+        'Card field that receives the miscellaneous info pattern (see ankiConnect.metadata.pattern).',
+    },
+    {
+      path: 'ankiConnect.fields.translation',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.fields.translation,
+      description: 'Card field that receives the current selection or translated text.',
+    },
     {
       path: 'ankiConnect.ai.enabled',
       kind: 'boolean',
@@ -83,6 +120,41 @@ export function buildIntegrationConfigOptionRegistry(
       description: 'Automatically update newly added cards.',
       runtime: runtimeOptionById.get('anki.autoUpdateNewCards'),
     },
+    {
+      path: 'ankiConnect.behavior.overwriteAudio',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.behavior.overwriteAudio,
+      description:
+        'When updating an existing card, overwrite the audio field instead of skipping it.',
+    },
+    {
+      path: 'ankiConnect.behavior.overwriteImage',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.behavior.overwriteImage,
+      description:
+        'When updating an existing card, overwrite the image field instead of skipping it.',
+    },
+    {
+      path: 'ankiConnect.behavior.mediaInsertMode',
+      kind: 'enum',
+      enumValues: ['append', 'prepend'],
+      defaultValue: defaultConfig.ankiConnect.behavior.mediaInsertMode,
+      description:
+        'Whether new media is appended after or prepended before existing field contents on update.',
+    },
+    {
+      path: 'ankiConnect.behavior.highlightWord',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.behavior.highlightWord,
+      description: 'Bold the mined word inside the sentence field on the saved Anki card.',
+    },
+    {
+      path: 'ankiConnect.behavior.notificationType',
+      kind: 'enum',
+      enumValues: ['osd', 'system', 'both', 'none'],
+      defaultValue: defaultConfig.ankiConnect.behavior.notificationType,
+      description: 'Notification surface used to announce mining and update outcomes.',
+    },
     {
       path: 'ankiConnect.media.syncAnimatedImageToWordAudio',
       kind: 'boolean',
@@ -90,6 +162,97 @@ export function buildIntegrationConfigOptionRegistry(
       description:
         'For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio.',
     },
+    {
+      path: 'ankiConnect.media.generateAudio',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.media.generateAudio,
+      description: 'Generate sentence audio for mined cards.',
+    },
+    {
+      path: 'ankiConnect.media.generateImage',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.media.generateImage,
+      description: 'Generate screenshot or animated image for mined cards.',
+    },
+    {
+      path: 'ankiConnect.media.imageType',
+      kind: 'enum',
+      enumValues: ['static', 'avif'],
+      defaultValue: defaultConfig.ankiConnect.media.imageType,
+      description:
+        'Image capture type: "static" for a single still frame, "avif" for an animated AVIF.',
+    },
+    {
+      path: 'ankiConnect.media.imageFormat',
+      kind: 'enum',
+      enumValues: ['jpg', 'png', 'webp'],
+      defaultValue: defaultConfig.ankiConnect.media.imageFormat,
+      description: 'Encoding format used when imageType is "static".',
+    },
+    {
+      path: 'ankiConnect.media.imageQuality',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.imageQuality,
+      description: 'Quality (0-100) used for lossy static image encoders.',
+    },
+    {
+      path: 'ankiConnect.media.imageMaxWidth',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.imageMaxWidth,
+      description:
+        'Optional maximum width for static images. Leave unset to preserve the source resolution.',
+    },
+    {
+      path: 'ankiConnect.media.imageMaxHeight',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.imageMaxHeight,
+      description:
+        'Optional maximum height for static images. Leave unset to preserve the source resolution.',
+    },
+    {
+      path: 'ankiConnect.media.animatedFps',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.animatedFps,
+      description: 'Target frame rate for animated AVIF captures.',
+    },
+    {
+      path: 'ankiConnect.media.animatedMaxWidth',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.animatedMaxWidth,
+      description: 'Maximum width applied to animated AVIF captures.',
+    },
+    {
+      path: 'ankiConnect.media.animatedMaxHeight',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.animatedMaxHeight,
+      description:
+        'Optional maximum height for animated AVIF captures. Leave unset to preserve aspect ratio.',
+    },
+    {
+      path: 'ankiConnect.media.animatedCrf',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.animatedCrf,
+      description:
+        'Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.',
+    },
+    {
+      path: 'ankiConnect.media.audioPadding',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.audioPadding,
+      description: 'Seconds of padding appended to both ends of generated sentence audio.',
+    },
+    {
+      path: 'ankiConnect.media.fallbackDuration',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.fallbackDuration,
+      description: 'Fallback clip duration in seconds when subtitle timing data is unavailable.',
+    },
+    {
+      path: 'ankiConnect.media.maxMediaDuration',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.maxMediaDuration,
+      description: 'Maximum allowed media clip duration in seconds.',
+    },
     {
       path: 'ankiConnect.knownWords.matchMode',
       kind: 'enum',
@@ -148,6 +311,44 @@ export function buildIntegrationConfigOptionRegistry(
       description: 'Kiku duplicate-card field grouping mode.',
       runtime: runtimeOptionById.get('anki.kikuFieldGrouping'),
     },
+    {
+      path: 'ankiConnect.isKiku.enabled',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.isKiku.enabled,
+      description: 'Enable Kiku-specific mining behaviors (duplicate handling, field grouping).',
+    },
+    {
+      path: 'ankiConnect.isKiku.deleteDuplicateInAuto',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.isKiku.deleteDuplicateInAuto,
+      description:
+        'When Kiku field grouping is "auto", delete the duplicate source card after grouping completes.',
+    },
+    {
+      path: 'ankiConnect.isLapis.enabled',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.isLapis.enabled,
+      description: 'Enable Lapis-specific mining behaviors and sentence card model targeting.',
+    },
+    {
+      path: 'ankiConnect.isLapis.sentenceCardModel',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.isLapis.sentenceCardModel,
+      description: 'Note type name used by Lapis sentence cards.',
+    },
+    {
+      path: 'ankiConnect.metadata.pattern',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.metadata.pattern,
+      description:
+        'Template used to render the miscInfo field. Placeholders include %f (filename) and %t (timestamp).',
+    },
+    {
+      path: 'jimaku.apiBaseUrl',
+      kind: 'string',
+      defaultValue: defaultConfig.jimaku.apiBaseUrl,
+      description: 'Base URL of the Jimaku subtitle search API.',
+    },
     {
       path: 'jimaku.languagePreference',
       kind: 'enum',
@@ -277,6 +478,26 @@ export function buildIntegrationConfigOptionRegistry(
       defaultValue: defaultConfig.jellyfin.username,
       description: 'Default Jellyfin username used during CLI login.',
     },
+    {
+      path: 'jellyfin.deviceId',
+      kind: 'string',
+      defaultValue: defaultConfig.jellyfin.deviceId,
+      description:
+        'Stable device identifier sent on the Jellyfin authentication handshake; primarily internal.',
+    },
+    {
+      path: 'jellyfin.clientName',
+      kind: 'string',
+      defaultValue: defaultConfig.jellyfin.clientName,
+      description: 'Client name sent on the Jellyfin authentication handshake; primarily internal.',
+    },
+    {
+      path: 'jellyfin.clientVersion',
+      kind: 'string',
+      defaultValue: defaultConfig.jellyfin.clientVersion,
+      description:
+        'Client version sent on the Jellyfin authentication handshake; primarily internal.',
+    },
     {
       path: 'jellyfin.defaultLibraryId',
       kind: 'string',
@@ -387,6 +608,18 @@ export function buildIntegrationConfigOptionRegistry(
       defaultValue: defaultConfig.ai.baseUrl,
       description: 'Base URL for the shared OpenAI-compatible AI provider.',
     },
+    {
+      path: 'ai.model',
+      kind: 'string',
+      defaultValue: defaultConfig.ai.model,
+      description: 'Default model identifier requested from the shared AI provider.',
+    },
+    {
+      path: 'ai.systemPrompt',
+      kind: 'string',
+      defaultValue: defaultConfig.ai.systemPrompt,
+      description: 'Default system prompt sent with shared AI provider requests.',
+    },
     {
       path: 'ai.requestTimeoutMs',
       kind: 'number',

src/config/settings/jsonc-edit.test.ts

@@ -0,0 +1,94 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { parse } from 'jsonc-parser';
+import { DEFAULT_CONFIG } from '../definitions';
+import { applyConfigSettingsPatchToContent, buildConfigSettingsSnapshot } from './jsonc-edit';
+import { buildConfigSettingsRegistry } from './registry';
+
+test('applyConfigSettingsPatchToContent preserves JSONC comments while setting nested values', () => {
+  const input = `{
+  // keep this comment
+  "subtitleStyle": {
+    "fontSize": 35,
+  },
+}`;
+
+  const result = applyConfigSettingsPatchToContent({
+    content: input,
+    operations: [
+      {
+        op: 'set',
+        path: 'subtitleStyle.autoPauseVideoOnHover',
+        value: false,
+      },
+    ],
+    previousWarnings: [],
+  });
+
+  assert.equal(result.ok, true);
+  assert.match(result.content, /keep this comment/);
+  const parsed = parse(result.content);
+  assert.equal(parsed.subtitleStyle.autoPauseVideoOnHover, false);
+  assert.equal(parsed.subtitleStyle.fontSize, 35);
+});
+
+test('applyConfigSettingsPatchToContent reset removes explicit path', () => {
+  const input = `{
+  "subtitleStyle": {
+    "fontSize": 41,
+    "autoPauseVideoOnHover": false
+  }
+}`;
+
+  const result = applyConfigSettingsPatchToContent({
+    content: input,
+    operations: [{ op: 'reset', path: 'subtitleStyle.autoPauseVideoOnHover' }],
+    previousWarnings: [],
+  });
+
+  assert.equal(result.ok, true);
+  const parsed = parse(result.content);
+  assert.equal(Object.hasOwn(parsed.subtitleStyle, 'autoPauseVideoOnHover'), false);
+  assert.equal(parsed.subtitleStyle.fontSize, 41);
+});
+
+test('applyConfigSettingsPatchToContent rejects warnings caused by modified fields', () => {
+  const result = applyConfigSettingsPatchToContent({
+    content: '{}',
+    operations: [
+      {
+        op: 'set',
+        path: 'subtitleStyle.autoPauseVideoOnHover',
+        value: 'bad',
+      },
+    ],
+    previousWarnings: [],
+  });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.warnings[0]?.path, 'subtitleStyle.autoPauseVideoOnHover');
+});
+
+test('buildConfigSettingsSnapshot masks configured secret values', () => {
+  const fields = buildConfigSettingsRegistry(DEFAULT_CONFIG);
+  const snapshot = buildConfigSettingsSnapshot({
+    configPath: '/tmp/config.jsonc',
+    rawConfig: {
+      ai: {
+        apiKey: 'secret-key',
+      },
+    },
+    resolvedConfig: {
+      ...DEFAULT_CONFIG,
+      ai: {
+        ...DEFAULT_CONFIG.ai,
+        apiKey: 'secret-key',
+      },
+    },
+    warnings: [],
+    fields,
+  });
+
+  const apiKey = snapshot.values['ai.apiKey'];
+  assert.deepEqual(apiKey, { configured: true });
+});

src/config/settings/jsonc-edit.ts

@@ -0,0 +1,200 @@
+import {
+  applyEdits,
+  modify,
+  parse as parseJsonc,
+  type FormattingOptions,
+  type ParseError,
+} from 'jsonc-parser';
+import type { ConfigValidationWarning, RawConfig, ResolvedConfig } from '../../types/config';
+import type {
+  ConfigSettingsField,
+  ConfigSettingsPatchOperation,
+  ConfigSettingsSnapshot,
+} from '../../types/settings';
+import { resolveConfig } from '../resolve';
+import { getConfigValueAtPath } from './registry';
+
+const JSONC_FORMATTING_OPTIONS: FormattingOptions = {
+  insertSpaces: true,
+  tabSize: 2,
+  eol: '\n',
+};
+
+export type ConfigSettingsPatchApplyResult =
+  | {
+      ok: true;
+      content: string;
+      rawConfig: RawConfig;
+      resolvedConfig: ResolvedConfig;
+      warnings: ConfigValidationWarning[];
+    }
+  | {
+      ok: false;
+      content: string;
+      warnings: ConfigValidationWarning[];
+      error: string;
+    };
+
+interface ApplyConfigSettingsPatchOptions {
+  content: string;
+  operations: ConfigSettingsPatchOperation[];
+  previousWarnings: ConfigValidationWarning[];
+}
+
+interface BuildConfigSettingsSnapshotOptions {
+  configPath: string;
+  rawConfig: RawConfig;
+  resolvedConfig: ResolvedConfig;
+  warnings: ConfigValidationWarning[];
+  fields: ConfigSettingsField[];
+}
+
+function pathToSegments(path: string): string[] {
+  return path.split('.').filter(Boolean);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function pathStartsWith(path: string, prefix: string): boolean {
+  return path === prefix || path.startsWith(`${prefix}.`);
+}
+
+function warningBelongsToModifiedPath(
+  warning: ConfigValidationWarning,
+  operation: ConfigSettingsPatchOperation,
+): boolean {
+  return (
+    pathStartsWith(warning.path, operation.path) || pathStartsWith(operation.path, warning.path)
+  );
+}
+
+function warningIdentity(warning: ConfigValidationWarning): string {
+  return `${warning.path}\n${JSON.stringify(warning.value)}\n${warning.message}`;
+}
+
+function parseRawConfig(content: string): RawConfig {
+  const errors: ParseError[] = [];
+  const parsed = parseJsonc(content || '{}', errors, {
+    allowTrailingComma: true,
+    disallowComments: false,
+  });
+  if (errors.length > 0) {
+    throw new Error(`Invalid JSONC (${errors[0]?.error ?? 'unknown'})`);
+  }
+  return isRecord(parsed) ? (parsed as RawConfig) : {};
+}
+
+function normalizeContent(content: string): string {
+  return content.trim().length > 0 ? content : '{}\n';
+}
+
+function applySingleOperation(content: string, operation: ConfigSettingsPatchOperation): string {
+  const edits = modify(
+    content,
+    pathToSegments(operation.path),
+    operation.op === 'reset' ? undefined : operation.value,
+    {
+      formattingOptions: JSONC_FORMATTING_OPTIONS,
+      getInsertionIndex: (properties) => properties.length,
+    },
+  );
+  return applyEdits(content, edits);
+}
+
+function collectModifiedWarnings(
+  warnings: ConfigValidationWarning[],
+  operations: ConfigSettingsPatchOperation[],
+  previousWarnings: ConfigValidationWarning[],
+): ConfigValidationWarning[] {
+  const previous = new Set(previousWarnings.map(warningIdentity));
+  return warnings.filter((warning) => {
+    if (!operations.some((operation) => warningBelongsToModifiedPath(warning, operation))) {
+      return false;
+    }
+    return !previous.has(warningIdentity(warning));
+  });
+}
+
+export function applyConfigSettingsPatchToContent(
+  options: ApplyConfigSettingsPatchOptions,
+): ConfigSettingsPatchApplyResult {
+  let content = normalizeContent(options.content);
+
+  try {
+    parseRawConfig(content);
+  } catch (error) {
+    return {
+      ok: false,
+      content,
+      warnings: [],
+      error: error instanceof Error ? error.message : 'Invalid JSONC.',
+    };
+  }
+
+  try {
+    for (const operation of options.operations) {
+      content = applySingleOperation(content, operation);
+    }
+
+    const rawConfig = parseRawConfig(content);
+    const { resolved, warnings } = resolveConfig(rawConfig);
+    const modifiedWarnings = collectModifiedWarnings(
+      warnings,
+      options.operations,
+      options.previousWarnings,
+    );
+    if (modifiedWarnings.length > 0) {
+      return {
+        ok: false,
+        content,
+        warnings: modifiedWarnings,
+        error: 'One or more modified settings failed validation.',
+      };
+    }
+
+    return {
+      ok: true,
+      content,
+      rawConfig,
+      resolvedConfig: resolved,
+      warnings,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      content,
+      warnings: [],
+      error: error instanceof Error ? error.message : 'Failed to update config content.',
+    };
+  }
+}
+
+export function buildConfigSettingsSnapshot(
+  options: BuildConfigSettingsSnapshotOptions,
+): ConfigSettingsSnapshot {
+  const values: Record<string, unknown> = {};
+
+  for (const field of options.fields) {
+    const rawValue = getConfigValueAtPath(options.rawConfig, field.configPath);
+    const resolvedValue = getConfigValueAtPath(options.resolvedConfig, field.configPath);
+    if (field.secret) {
+      values[field.configPath] = {
+        configured:
+          (typeof rawValue === 'string' && rawValue.length > 0) ||
+          (typeof resolvedValue === 'string' && resolvedValue.length > 0),
+      };
+      continue;
+    }
+
+    values[field.configPath] = structuredClone(rawValue !== undefined ? rawValue : resolvedValue);
+  }
+
+  return {
+    configPath: options.configPath,
+    fields: options.fields,
+    values,
+    warnings: options.warnings,
+  };
+}

src/config/settings/registry.test.ts

@@ -0,0 +1,39 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { DEFAULT_CONFIG } from '../definitions';
+import {
+  buildConfigSettingsRegistry,
+  getConfigSettingsCoverage,
+  LEGACY_HIDDEN_CONFIG_PATHS,
+} from './registry';
+
+test('config settings registry places hover pause under viewing playback behavior', () => {
+  const fields = buildConfigSettingsRegistry(DEFAULT_CONFIG);
+  const hoverPause = fields.find(
+    (field) => field.configPath === 'subtitleStyle.autoPauseVideoOnHover',
+  );
+
+  assert.ok(hoverPause);
+  assert.equal(hoverPause.category, 'viewing');
+  assert.equal(hoverPause.section, 'Playback pause behavior');
+  assert.equal(hoverPause.control, 'boolean');
+});
+
+test('config settings registry hides legacy and ignored paths from normal fields', () => {
+  const fields = buildConfigSettingsRegistry(DEFAULT_CONFIG);
+  const visiblePaths = new Set(
+    fields.filter((field) => !field.legacyHidden).map((field) => field.configPath),
+  );
+
+  for (const path of LEGACY_HIDDEN_CONFIG_PATHS) {
+    assert.equal(visiblePaths.has(path), false, path);
+  }
+  assert.equal(visiblePaths.has('controller.buttonIndices'), false);
+});
+
+test('config settings registry covers canonical defaults or marks explicit raw-only gaps', () => {
+  const fields = buildConfigSettingsRegistry(DEFAULT_CONFIG);
+  const coverage = getConfigSettingsCoverage(DEFAULT_CONFIG, fields);
+
+  assert.deepEqual(coverage.uncoveredDefaultPaths, []);
+});

src/config/settings/registry.ts

@@ -0,0 +1,346 @@
+import type { ResolvedConfig } from '../../types/config';
+import type {
+  ConfigSettingsCategory,
+  ConfigSettingsControl,
+  ConfigSettingsField,
+  ConfigSettingsRestartBehavior,
+} from '../../types/settings';
+import { CONFIG_OPTION_REGISTRY, DEFAULT_CONFIG } from '../definitions';
+
+type Leaf = {
+  path: string;
+  value: unknown;
+};
+
+export const LEGACY_HIDDEN_CONFIG_PATHS = [
+  'ankiConnect.deck',
+  'ankiConnect.wordField',
+  'ankiConnect.audioField',
+  'ankiConnect.imageField',
+  'ankiConnect.sentenceField',
+  'ankiConnect.miscInfoField',
+  'ankiConnect.miscInfoPattern',
+  'ankiConnect.generateAudio',
+  'ankiConnect.generateImage',
+  'ankiConnect.imageType',
+  'ankiConnect.imageFormat',
+  'ankiConnect.imageQuality',
+  'ankiConnect.imageMaxWidth',
+  'ankiConnect.imageMaxHeight',
+  'ankiConnect.animatedFps',
+  'ankiConnect.animatedMaxWidth',
+  'ankiConnect.animatedMaxHeight',
+  'ankiConnect.animatedCrf',
+  'ankiConnect.syncAnimatedImageToWordAudio',
+  'ankiConnect.audioPadding',
+  'ankiConnect.fallbackDuration',
+  'ankiConnect.maxMediaDuration',
+  'ankiConnect.overwriteAudio',
+  'ankiConnect.overwriteImage',
+  'ankiConnect.mediaInsertMode',
+  'ankiConnect.highlightWord',
+  'ankiConnect.notificationType',
+  'ankiConnect.autoUpdateNewCards',
+  'ankiConnect.nPlusOne.highlightEnabled',
+  'ankiConnect.nPlusOne.refreshMinutes',
+  'ankiConnect.nPlusOne.matchMode',
+  'ankiConnect.nPlusOne.decks',
+  'ankiConnect.nPlusOne.knownWord',
+  'ankiConnect.behavior.nPlusOneHighlightEnabled',
+  'ankiConnect.behavior.nPlusOneRefreshMinutes',
+  'ankiConnect.behavior.nPlusOneMatchMode',
+  'ankiConnect.isLapis.sentenceCardSentenceField',
+  'ankiConnect.isLapis.sentenceCardAudioField',
+  'youtubeSubgen.primarySubLanguages',
+  'anilist.characterDictionary.refreshTtlHours',
+  'anilist.characterDictionary.evictionPolicy',
+  'jellyfin.accessToken',
+  'jellyfin.userId',
+  'controller.buttonIndices',
+] as const;
+
+const EXCLUDED_PREFIXES = ['controller.buttonIndices'] as const;
+
+const JSON_OBJECT_FIELDS = new Set([
+  'keybindings',
+  'controller.bindings',
+  'controller.profiles',
+  'ankiConnect.knownWords.decks',
+]);
+
+const SECRET_PATHS = new Set(['ai.apiKey', 'jimaku.apiKey', 'anilist.accessToken']);
+
+const COLOR_SUFFIXES = new Set([
+  'Color',
+  'color',
+  'backgroundColor',
+  'singleColor',
+  'knownWordColor',
+  'nPlusOne',
+]);
+
+const OPTION_BY_PATH = new Map(CONFIG_OPTION_REGISTRY.map((entry) => [entry.path, entry]));
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function pathStartsWith(path: string, prefix: string): boolean {
+  return path === prefix || path.startsWith(`${prefix}.`);
+}
+
+function isLegacyHidden(path: string): boolean {
+  return (
+    LEGACY_HIDDEN_CONFIG_PATHS.some((hiddenPath) => pathStartsWith(path, hiddenPath)) ||
+    EXCLUDED_PREFIXES.some((prefix) => pathStartsWith(path, prefix))
+  );
+}
+
+function flattenConfigLeaves(value: unknown, prefix = ''): Leaf[] {
+  if (JSON_OBJECT_FIELDS.has(prefix)) {
+    return [{ path: prefix, value }];
+  }
+
+  if (Array.isArray(value)) {
+    return [{ path: prefix, value }];
+  }
+
+  if (isRecord(value)) {
+    const entries = Object.entries(value).filter(([, child]) => child !== undefined);
+    if (entries.length === 0) {
+      return [{ path: prefix, value }];
+    }
+    return entries.flatMap(([key, child]) =>
+      flattenConfigLeaves(child, prefix ? `${prefix}.${key}` : key),
+    );
+  }
+
+  return prefix ? [{ path: prefix, value }] : [];
+}
+
+function humanizePath(path: string): string {
+  const key = path.split('.').at(-1) ?? path;
+  const spaced = key
+    .replace(/_/g, ' ')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/\bai\b/i, 'AI')
+    .replace(/\bmpv\b/i, 'mpv')
+    .replace(/\byomitan\b/i, 'Yomitan')
+    .replace(/\bjimaku\b/i, 'Jimaku')
+    .replace(/\banilist\b/i, 'AniList')
+    .replace(/\banki\b/i, 'Anki');
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+function categoryAndSection(path: string): { category: ConfigSettingsCategory; section: string } {
+  if (
+    path === 'subtitleStyle.autoPauseVideoOnHover' ||
+    path === 'subtitleStyle.autoPauseVideoOnYomitanPopup' ||
+    path === 'subtitleSidebar.pauseVideoOnHover'
+  ) {
+    return { category: 'viewing', section: 'Playback pause behavior' };
+  }
+  if (
+    path.startsWith('ankiConnect.knownWords.') ||
+    path.startsWith('ankiConnect.nPlusOne.') ||
+    path.startsWith('subtitleStyle.frequencyDictionary.') ||
+    path.startsWith('subtitleStyle.jlptColors.') ||
+    path === 'subtitleStyle.enableJlpt' ||
+    path === 'subtitleStyle.nameMatchEnabled' ||
+    path === 'subtitleStyle.nameMatchColor'
+  ) {
+    return { category: 'viewing', section: 'Annotation display' };
+  }
+  if (path.startsWith('subtitleStyle.secondary.')) {
+    return { category: 'viewing', section: 'Secondary subtitle appearance' };
+  }
+  if (path.startsWith('subtitleStyle.')) {
+    return { category: 'viewing', section: 'Primary subtitle appearance' };
+  }
+  if (path.startsWith('subtitleSidebar.')) {
+    return { category: 'viewing', section: 'Subtitle sidebar' };
+  }
+  if (path.startsWith('subtitlePosition.') || path.startsWith('secondarySub.')) {
+    return { category: 'viewing', section: 'Subtitle behavior' };
+  }
+  if (path.startsWith('ankiConnect.fields.')) {
+    return { category: 'mining-anki', section: 'Note fields' };
+  }
+  if (path.startsWith('ankiConnect.media.')) {
+    return { category: 'mining-anki', section: 'Media capture' };
+  }
+  if (path.startsWith('ankiConnect.isKiku.') || path.startsWith('ankiConnect.isLapis.')) {
+    return { category: 'mining-anki', section: 'Kiku and Lapis' };
+  }
+  if (path.startsWith('ankiConnect.ai.')) {
+    return { category: 'mining-anki', section: 'Anki AI' };
+  }
+  if (path.startsWith('ankiConnect.proxy.')) {
+    return { category: 'mining-anki', section: 'AnkiConnect proxy' };
+  }
+  if (path.startsWith('ankiConnect.')) {
+    return { category: 'mining-anki', section: 'AnkiConnect' };
+  }
+  if (
+    path.startsWith('mpv.') ||
+    path.startsWith('youtube.') ||
+    path.startsWith('youtubeSubgen.') ||
+    path.startsWith('jimaku.') ||
+    path.startsWith('subsync.')
+  ) {
+    return { category: 'playback-sources', section: topSection(path) };
+  }
+  if (path.startsWith('shortcuts.')) {
+    return { category: 'input', section: 'Overlay shortcuts' };
+  }
+  if (path === 'keybindings') {
+    return { category: 'input', section: 'MPV keybindings' };
+  }
+  if (path.startsWith('controller.')) {
+    return { category: 'input', section: 'Controller' };
+  }
+  if (
+    path.startsWith('ai.') ||
+    path.startsWith('anilist.') ||
+    path.startsWith('yomitan.') ||
+    path.startsWith('jellyfin.') ||
+    path.startsWith('discordPresence.') ||
+    path.startsWith('websocket.') ||
+    path.startsWith('annotationWebsocket.') ||
+    path.startsWith('texthooker.')
+  ) {
+    return { category: 'integrations', section: topSection(path) };
+  }
+  if (
+    path.startsWith('immersionTracking.') ||
+    path.startsWith('stats.') ||
+    path.startsWith('updates.') ||
+    path.startsWith('startupWarmups.') ||
+    path.startsWith('logging.') ||
+    path === 'auto_start_overlay'
+  ) {
+    return { category: 'tracking-app', section: topSection(path) };
+  }
+  return { category: 'advanced', section: 'Advanced' };
+}
+
+function topSection(path: string): string {
+  const top = path.split('.')[0] ?? path;
+  const labels: Record<string, string> = {
+    ai: 'Shared AI provider',
+    anilist: 'AniList',
+    annotationWebsocket: 'Annotation WebSocket',
+    discordPresence: 'Discord Rich Presence',
+    immersionTracking: 'Immersion tracking',
+    jimaku: 'Jimaku',
+    jellyfin: 'Jellyfin',
+    logging: 'Logging',
+    mpv: 'mpv launcher',
+    stats: 'Stats dashboard',
+    startupWarmups: 'Startup warmups',
+    subsync: 'Auto subtitle sync',
+    texthooker: 'Texthooker',
+    updates: 'Updates',
+    websocket: 'WebSocket server',
+    yomitan: 'Yomitan',
+    youtube: 'YouTube playback',
+    youtubeSubgen: 'YouTube subtitle generation',
+    auto_start_overlay: 'Overlay startup',
+  };
+  return labels[top] ?? humanizePath(top);
+}
+
+function controlForPath(path: string, value: unknown): ConfigSettingsControl {
+  if (SECRET_PATHS.has(path)) return 'secret';
+  if (OPTION_BY_PATH.get(path)?.enumValues?.length) return 'select';
+  if (JSON_OBJECT_FIELDS.has(path)) return 'json';
+  if (Array.isArray(value)) return 'string-list';
+  if (typeof value === 'boolean') return 'boolean';
+  if (typeof value === 'number') return 'number';
+  if (typeof value === 'string') {
+    const leaf = path.split('.').at(-1) ?? path;
+    if ([...COLOR_SUFFIXES].some((suffix) => leaf.endsWith(suffix))) return 'color';
+    if (leaf.toLowerCase().includes('prompt')) return 'textarea';
+    return 'text';
+  }
+  return 'json';
+}
+
+function restartBehaviorForPath(path: string): ConfigSettingsRestartBehavior {
+  if (
+    path === 'keybindings' ||
+    pathStartsWith(path, 'shortcuts') ||
+    pathStartsWith(path, 'subtitleStyle') ||
+    pathStartsWith(path, 'subtitleSidebar') ||
+    path === 'secondarySub.defaultMode' ||
+    pathStartsWith(path, 'ankiConnect.ai')
+  ) {
+    return 'hot-reload';
+  }
+  return 'restart';
+}
+
+function fieldForLeaf(leaf: Leaf): ConfigSettingsField {
+  const option = OPTION_BY_PATH.get(leaf.path);
+  const { category, section } = categoryAndSection(leaf.path);
+  return {
+    id: leaf.path,
+    label: option?.path === leaf.path ? humanizePath(leaf.path) : humanizePath(leaf.path),
+    description: option?.description ?? `${humanizePath(leaf.path)} setting.`,
+    configPath: leaf.path,
+    category,
+    section,
+    control: controlForPath(leaf.path, leaf.value),
+    defaultValue: leaf.value,
+    ...(option?.enumValues ? { enumValues: option.enumValues } : {}),
+    restartBehavior: restartBehaviorForPath(leaf.path),
+    advanced:
+      leaf.path.startsWith('controller.') ||
+      leaf.path.startsWith('immersionTracking.retention.') ||
+      leaf.path.startsWith('youtubeSubgen.'),
+    secret: SECRET_PATHS.has(leaf.path),
+  };
+}
+
+export function buildConfigSettingsRegistry(
+  defaultConfig: ResolvedConfig = DEFAULT_CONFIG,
+): ConfigSettingsField[] {
+  const leaves = flattenConfigLeaves(defaultConfig).filter((leaf) => !isLegacyHidden(leaf.path));
+  return leaves.map(fieldForLeaf).sort((a, b) => {
+    const category = a.category.localeCompare(b.category);
+    if (category !== 0) return category;
+    const section = a.section.localeCompare(b.section);
+    if (section !== 0) return section;
+    return a.configPath.localeCompare(b.configPath);
+  });
+}
+
+export function getConfigSettingsCoverage(
+  defaultConfig: ResolvedConfig,
+  fields: ConfigSettingsField[],
+): { uncoveredDefaultPaths: string[] } {
+  const visibleFields = fields.filter((field) => !field.legacyHidden);
+  const uncoveredDefaultPaths = flattenConfigLeaves(defaultConfig)
+    .map((leaf) => leaf.path)
+    .filter((path) => !isLegacyHidden(path))
+    .filter(
+      (path) =>
+        !visibleFields.some(
+          (field) =>
+            field.configPath === path ||
+            (field.control === 'json' && pathStartsWith(path, field.configPath)),
+        ),
+    )
+    .sort();
+
+  return { uncoveredDefaultPaths };
+}
+
+export function getConfigValueAtPath(root: unknown, path: string): unknown {
+  let current = root;
+  for (const segment of path.split('.')) {
+    if (!isRecord(current)) return undefined;
+    current = current[segment];
+  }
+  return current;
+}

src/core/services/app-lifecycle.test.ts

@@ -15,6 +15,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
     toggleVisibleOverlay: false,
     togglePrimarySubtitleBar: false,
     settings: false,
+    configSettings: false,
     setup: false,
     show: false,
     hide: false,

src/core/services/cli-command.test.ts

@@ -16,6 +16,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
     toggle: false,
     toggleVisibleOverlay: false,
     settings: false,
+    configSettings: false,
     setup: false,
     show: false,
     hide: false,
@@ -130,6 +131,9 @@ function createDeps(overrides: Partial<CliCommandServiceDeps> = {}) {
     openYomitanSettingsDelayed: (delayMs) => {
       calls.push(`openYomitanSettingsDelayed:${delayMs}`);
     },
+    openConfigSettingsWindow: () => {
+      calls.push('openConfigSettingsWindow');
+    },
     openFirstRunSetup: (force?: boolean) => {
       calls.push(`openFirstRunSetup:${force === true ? 'force' : 'default'}`);
     },
@@ -582,6 +586,7 @@ test('handleCliCommand handles visibility and utility command dispatches', () =>
     expected: string;
   }> = [
     { args: { settings: true }, expected: 'openYomitanSettingsDelayed:1000' },
+    { args: { configSettings: true }, expected: 'openConfigSettingsWindow' },
     {
       args: { showVisibleOverlay: true },
       expected: 'setVisibleOverlayVisible:true',

src/core/services/cli-command.ts

@@ -43,6 +43,7 @@ export interface CliCommandServiceDeps {
   togglePrimarySubtitleBar: () => void;
   openFirstRunSetup: (force?: boolean) => void;
   openYomitanSettingsDelayed: (delayMs: number) => void;
+  openConfigSettingsWindow: () => void;
   setVisibleOverlayVisible: (visible: boolean) => void;
   copyCurrentSubtitle: () => void;
   startPendingMultiCopy: (timeoutMs: number) => void;
@@ -160,6 +161,7 @@ interface MiningCliRuntime {
 interface UiCliRuntime {
   openFirstRunSetup: (force?: boolean) => void;
   openYomitanSettings: () => void;
+  openConfigSettingsWindow: () => void;
   cycleSecondarySubMode: () => void;
   openRuntimeOptionsPalette: () => void;
   printHelp: () => void;
@@ -257,6 +259,7 @@ export function createCliCommandDepsRuntime(
         options.ui.openYomitanSettings();
       }, delayMs);
     },
+    openConfigSettingsWindow: options.ui.openConfigSettingsWindow,
     setVisibleOverlayVisible: options.overlay.setVisible,
     copyCurrentSubtitle: options.mining.copyCurrentSubtitle,
     startPendingMultiCopy: options.mining.startPendingMultiCopy,
@@ -385,6 +388,8 @@ export function handleCliCommand(
     deps.logDebug('Opened first-run setup flow.');
   } else if (args.settings) {
     deps.openYomitanSettingsDelayed(1000);
+  } else if (args.configSettings) {
+    deps.openConfigSettingsWindow();
   } else if (args.show || args.showVisibleOverlay) {
     deps.setVisibleOverlayVisible(true);
   } else if (args.hide || args.hideVisibleOverlay) {

src/core/services/startup-bootstrap.test.ts

@@ -15,6 +15,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
     toggleVisibleOverlay: false,
     togglePrimarySubtitleBar: false,
     settings: false,
+    configSettings: false,
     setup: false,
     show: false,
     hide: false,

src/core/services/yomitan-extension-copy.ts

@@ -142,10 +142,7 @@ export function shouldCopyYomitanExtension(sourceDir: string, targetDir: string)
   return sourceHash === null || targetHash === null || sourceHash !== targetHash;
 }
 
-export function ensureExtensionCopy(
-  sourceDir: string,
-  userDataPath: string,
-): ExtensionCopyResult {
+export function ensureExtensionCopy(sourceDir: string, userDataPath: string): ExtensionCopyResult {
   if (process.platform === 'win32') {
     return { targetDir: sourceDir, copied: false };
   }

src/core/services/yomitan-settings.test.ts

@@ -15,21 +15,24 @@ import {
 test('yomitan settings window uses a close-only menu without app quit', () => {
   const calls: string[] = [];
 
-  configureYomitanSettingsWindowChrome({
-    isDestroyed: () => false,
-    close: () => calls.push('close'),
-    setAutoHideMenuBar: (hide: boolean) => calls.push(`auto-hide:${hide}`),
-    setMenu: (menu: unknown) => calls.push(`menu:${menu === null ? 'null' : 'custom'}`),
-  } as never, (template) => {
-    calls.push(`menu-label:${template[0]?.label ?? ''}`);
-    const submenu = template[0]?.submenu;
-    assert.ok(Array.isArray(submenu));
-    const closeItem = submenu[0];
-    assert.equal(closeItem?.label, 'Close');
-    assert.notEqual(closeItem?.role, 'quit');
-    closeItem?.click?.({} as never, {} as never, {} as never);
-    return { id: 'settings-menu' } as never;
-  });
+  configureYomitanSettingsWindowChrome(
+    {
+      isDestroyed: () => false,
+      close: () => calls.push('close'),
+      setAutoHideMenuBar: (hide: boolean) => calls.push(`auto-hide:${hide}`),
+      setMenu: (menu: unknown) => calls.push(`menu:${menu === null ? 'null' : 'custom'}`),
+    } as never,
+    (template) => {
+      calls.push(`menu-label:${template[0]?.label ?? ''}`);
+      const submenu = template[0]?.submenu;
+      assert.ok(Array.isArray(submenu));
+      const closeItem = submenu[0];
+      assert.equal(closeItem?.label, 'Close');
+      assert.notEqual(closeItem?.role, 'quit');
+      closeItem?.click?.({} as never, {} as never, {} as never);
+      return { id: 'settings-menu' } as never;
+    },
+  );
 
   assert.deepEqual(calls, ['auto-hide:false', 'menu-label:File', 'close', 'menu:custom']);
 });

src/main.ts

@@ -20,6 +20,8 @@ import {
   BrowserWindow,
   clipboard,
   globalShortcut,
+  ipcMain,
+  net,
   shell,
   protocol,
   Extension,
@@ -75,28 +77,6 @@ function getDefaultPasswordStore(): string {
   return 'gnome-libsecret';
 }
 
-function getStartupModeFlags(initialArgs: CliArgs | null | undefined): {
-  shouldUseMinimalStartup: boolean;
-  shouldSkipHeavyStartup: boolean;
-} {
-  return {
-    shouldUseMinimalStartup: Boolean(
-      (initialArgs && isStandaloneTexthookerCommand(initialArgs)) ||
-      initialArgs?.update ||
-      (initialArgs?.stats &&
-        (initialArgs.statsCleanup || initialArgs.statsBackground || initialArgs.statsStop)),
-    ),
-    shouldSkipHeavyStartup: Boolean(
-      initialArgs &&
-      (shouldRunSettingsOnlyStartup(initialArgs) ||
-        initialArgs.stats ||
-        initialArgs.dictionary ||
-        initialArgs.update ||
-        initialArgs.setup),
-    ),
-  };
-}
-
 protocol.registerSchemesAsPrivileged([
   {
     scheme: 'chrome-extension',
@@ -152,15 +132,18 @@ import {
   commandNeedsOverlayStartupPrereqs,
   commandNeedsOverlayRuntime,
   isHeadlessInitialCommand,
-  isStandaloneTexthookerCommand,
   parseArgs,
-  shouldRunSettingsOnlyStartup,
   shouldStartApp,
   type CliArgs,
   type CliCommandSource,
 } from './cli/args';
 import { printHelp } from './cli/help';
 import { IPC_CHANNELS, type OverlayHostedModal } from './shared/ipc/contracts';
+import {
+  getStartupModeFlags,
+  shouldRefreshAnilistOnConfigReload,
+  shouldStartAutomaticUpdateChecks,
+} from './main/runtime/startup-mode-flags';
 import {
   buildConfigParseErrorDetails,
   buildConfigWarningDialogDetails,
@@ -515,6 +498,8 @@ import {
   createElectronAppUpdater,
   isNativeUpdaterSupported,
 } from './main/runtime/update/app-updater';
+import { createElectronNetFetch } from './main/runtime/update/fetch-adapter';
+import { createCurlHttpExecutor } from './main/runtime/update/curl-http-executor';
 import {
   fetchLatestStableRelease,
   fetchReleaseAssetBuffer,
@@ -523,6 +508,7 @@ import {
   parseSha256Sums,
   type GitHubRelease,
 } from './main/runtime/update/release-assets';
+import { shouldFetchReleaseMetadataForPlatform } from './main/runtime/update/release-metadata-policy';
 import { updateLauncherFromRelease } from './main/runtime/update/launcher-updater';
 import { notifyUpdateAvailable } from './main/runtime/update/update-notifications';
 import { createUpdateDialogPresenter } from './main/runtime/update/update-dialogs';
@@ -541,9 +527,11 @@ import {
 } from './main/runtime/subtitle-prefetch-runtime';
 import {
   createCreateAnilistSetupWindowHandler,
+  createCreateConfigSettingsWindowHandler,
   createCreateFirstRunSetupWindowHandler,
   createCreateJellyfinSetupWindowHandler,
 } from './main/runtime/setup-window-factory';
+import { createConfigSettingsRuntime } from './main/runtime/config-settings-runtime';
 import { isYoutubePlaybackActive } from './main/runtime/youtube-playback';
 import { createYomitanProfilePolicy } from './main/runtime/yomitan-profile-policy';
 import { formatSkippedYomitanWriteAction } from './main/runtime/yomitan-read-only-log';
@@ -577,6 +565,7 @@ import {
   generateConfigTemplate,
 } from './config';
 import { resolveConfigDir } from './config/path-resolution';
+import { buildConfigSettingsRegistry } from './config/settings/registry';
 import { parseSubtitleCues } from './core/services/subtitle-cue-parser';
 import {
   createSubtitlePrefetchService,
@@ -835,6 +824,7 @@ const {
   appState,
   appLifecycleApp,
 } = bootServices;
+const configSettingsFields = buildConfigSettingsRegistry(DEFAULT_CONFIG);
 notifyAnilistTokenStoreWarning = (message: string) => {
   logger.warn(`[AniList] ${message}`);
   try {
@@ -1777,6 +1767,9 @@ const buildConfigHotReloadAppliedMainDepsHandler = createBuildConfigHotReloadApp
     },
   },
 );
+const applyConfigHotReloadDiff = createConfigHotReloadAppliedHandler(
+  buildConfigHotReloadAppliedMainDepsHandler(),
+);
 const buildConfigHotReloadRuntimeMainDepsHandler = createBuildConfigHotReloadRuntimeMainDepsHandler(
   {
     getCurrentConfig: () => getResolvedConfig(),
@@ -1785,9 +1778,7 @@ const buildConfigHotReloadRuntimeMainDepsHandler = createBuildConfigHotReloadRun
     setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
     clearTimeout: (timeout) => clearTimeout(timeout),
     debounceMs: 250,
-    onHotReloadApplied: createConfigHotReloadAppliedHandler(
-      buildConfigHotReloadAppliedMainDepsHandler(),
-    ),
+    onHotReloadApplied: applyConfigHotReloadDiff,
     onRestartRequired: (fields) =>
       notifyConfigHotReloadMessage(buildRestartRequiredConfigMessage(fields)),
     onInvalidConfig: notifyConfigHotReloadMessage,
@@ -1808,6 +1799,32 @@ const configHotReloadRuntime = createConfigHotReloadRuntime(
   buildConfigHotReloadRuntimeMainDepsHandler(),
 );
 
+const configSettingsRuntime = createConfigSettingsRuntime({
+  fields: configSettingsFields,
+  getConfigPath: () => configService.getConfigPath(),
+  getRawConfig: () => configService.getRawConfig(),
+  getConfig: () => configService.getConfig(),
+  getWarnings: () => configService.getWarnings(),
+  reloadConfigStrict: () => configService.reloadConfigStrict(),
+  applyHotReload: (diff, config) => applyConfigHotReloadDiff(diff, config),
+  getSettingsWindow: () => appState.configSettingsWindow,
+  setSettingsWindow: (window) => {
+    appState.configSettingsWindow = window as BrowserWindow | null;
+  },
+  createSettingsWindow: createCreateConfigSettingsWindowHandler({
+    createBrowserWindow: (options) => new BrowserWindow(options),
+    preloadPath: path.join(__dirname, 'preload-settings.js'),
+  }),
+  settingsHtmlPath: path.join(__dirname, 'settings', 'index.html'),
+  openPath: (targetPath) => shell.openPath(targetPath),
+  ipcMain,
+  ipcChannels: IPC_CHANNELS.request,
+  log: (message) => logger.error(message),
+});
+
+configSettingsRuntime.registerHandlers();
+const openConfigSettingsWindow = () => configSettingsRuntime.openWindow();
+
 const buildDictionaryRootsHandler = createBuildDictionaryRootsMainHandler({
   platform: process.platform,
   dirname: __dirname,
@@ -3759,7 +3776,7 @@ const { appReadyRuntimeRunner } = composeAppReadyRuntime({
     showDesktopNotification: (title, options) => showDesktopNotification(title, options),
     startConfigHotReload: () => configHotReloadRuntime.start(),
     shouldRefreshAnilistClientSecretState: () =>
-      !(appState.initialArgs && isHeadlessInitialCommand(appState.initialArgs)),
+      shouldRefreshAnilistOnConfigReload(appState.initialArgs),
     refreshAnilistClientSecretState: (options) => refreshAnilistClientSecretStateIfEnabled(options),
     failHandlers: {
       logError: (details) => logger.error(details),
@@ -4636,9 +4653,12 @@ flushPendingMpvLogWrites = () => {
 
 const updateStateStore = createFileUpdateStateStore(path.join(USER_DATA_PATH, 'update-state.json'));
 let updateService: ReturnType<typeof createUpdateService> | null = null;
+const electronNetFetch = createElectronNetFetch({
+  fetch: (url, init) => net.fetch(url, init as RequestInit),
+});
 
 function getFetchForUpdater() {
-  return globalThis.fetch.bind(globalThis);
+  return electronNetFetch;
 }
 
 async function updateLauncherFromSelectedRelease(
@@ -4685,6 +4705,9 @@ function getUpdateService() {
     isPackaged: app.isPackaged,
     log: (message) => logger.info(message),
     getChannel: () => getResolvedConfig().updates.channel,
+    configureHttpExecutor:
+      process.platform === 'darwin' ? () => createCurlHttpExecutor() : undefined,
+    disableDifferentialDownload: process.platform === 'darwin',
     isNativeUpdaterSupported: () =>
       isNativeUpdaterSupported({
         platform: process.platform,
@@ -4706,6 +4729,8 @@ function getUpdateService() {
     readState: () => updateStateStore.readState(),
     writeState: (state) => updateStateStore.writeState(state),
     checkAppUpdate: (channel) => appUpdater.checkForUpdates(channel),
+    shouldFetchReleaseMetadata: ({ appUpdate }) =>
+      shouldFetchReleaseMetadataForPlatform(process.platform, appUpdate),
     fetchLatestStableRelease: (channel) =>
       fetchLatestStableRelease({ fetch: getFetchForUpdater(), channel }),
     updateLauncher: (launcherPath, channel, release) =>
@@ -5412,6 +5437,7 @@ const { handleCliCommand, handleInitialArgs } = composeCliStartupHandlers({
     },
     runYoutubePlaybackFlow: (request) => youtubePlaybackRuntime.runYoutubePlaybackFlow(request),
     openYomitanSettings: () => openYomitanSettings(),
+    openConfigSettingsWindow: () => openConfigSettingsWindow(),
     cycleSecondarySubMode: () => handleCycleSecondarySubMode(),
     openRuntimeOptionsPalette: () => openRuntimeOptionsPalette(),
     printHelp: () => printHelp(DEFAULT_TEXTHOOKER_PORT),
@@ -5526,7 +5552,7 @@ const { runAndApplyStartupState } = composeHeadlessStartupHandlers<
 
 runAndApplyStartupState();
 void app.whenReady().then(() => {
-  if (appState.initialArgs && isHeadlessInitialCommand(appState.initialArgs)) {
+  if (!shouldStartAutomaticUpdateChecks(appState.initialArgs)) {
     return;
   }
   getUpdateService().startAutomaticChecks();
@@ -5621,6 +5647,7 @@ const { ensureTray: ensureTrayHandler, destroyTray: destroyTrayHandler } =
       showWindowsMpvLauncherSetup: () => process.platform === 'win32',
       openYomitanSettings: () => openYomitanSettings(),
       openRuntimeOptionsPalette: () => openRuntimeOptionsPalette(),
+      openConfigSettingsWindow: () => openConfigSettingsWindow(),
       openJellyfinSetupWindow: () => openJellyfinSetupWindow(),
       isJellyfinConfigured: () =>
         isJellyfinConfiguredForTrayRuntime(getJellyfinTrayDiscoveryDeps()),

src/main/cli-runtime.ts

@@ -46,6 +46,7 @@ export interface CliCommandRuntimeServiceContext {
   runUpdateCommand: CliCommandRuntimeServiceDepsParams['app']['runUpdateCommand'];
   runYoutubePlaybackFlow: CliCommandRuntimeServiceDepsParams['app']['runYoutubePlaybackFlow'];
   openYomitanSettings: () => void;
+  openConfigSettingsWindow: () => void;
   cycleSecondarySubMode: () => void;
   openRuntimeOptionsPalette: () => void;
   printHelp: () => void;
@@ -127,6 +128,7 @@ function createCliCommandDepsFromContext(
     ui: {
       openFirstRunSetup: context.openFirstRunSetup,
       openYomitanSettings: context.openYomitanSettings,
+      openConfigSettingsWindow: context.openConfigSettingsWindow,
       cycleSecondarySubMode: context.cycleSecondarySubMode,
       openRuntimeOptionsPalette: context.openRuntimeOptionsPalette,
       printHelp: context.printHelp,

src/main/dependencies.ts

@@ -192,6 +192,7 @@ export interface CliCommandRuntimeServiceDepsParams {
   ui: {
     openFirstRunSetup: CliCommandDepsRuntimeOptions['ui']['openFirstRunSetup'];
     openYomitanSettings: CliCommandDepsRuntimeOptions['ui']['openYomitanSettings'];
+    openConfigSettingsWindow: CliCommandDepsRuntimeOptions['ui']['openConfigSettingsWindow'];
     cycleSecondarySubMode: CliCommandDepsRuntimeOptions['ui']['cycleSecondarySubMode'];
     openRuntimeOptionsPalette: CliCommandDepsRuntimeOptions['ui']['openRuntimeOptionsPalette'];
     printHelp: CliCommandDepsRuntimeOptions['ui']['printHelp'];
@@ -373,6 +374,7 @@ export function createCliCommandRuntimeServiceDeps(
     ui: {
       openFirstRunSetup: params.ui.openFirstRunSetup,
       openYomitanSettings: params.ui.openYomitanSettings,
+      openConfigSettingsWindow: params.ui.openConfigSettingsWindow,
       cycleSecondarySubMode: params.ui.cycleSecondarySubMode,
       openRuntimeOptionsPalette: params.ui.openRuntimeOptionsPalette,
       printHelp: params.ui.printHelp,

src/main/runtime/app-runtime-main-deps.ts

@@ -84,8 +84,7 @@ export function createBuildOpenYomitanSettingsMainDepsHandler<TYomitanExt, TWind
       : {}),
     ...(deps.getYomitanExtensionLoadInFlight
       ? {
-          getYomitanExtensionLoadInFlight: () =>
-            deps.getYomitanExtensionLoadInFlight?.() ?? null,
+          getYomitanExtensionLoadInFlight: () => deps.getYomitanExtensionLoadInFlight?.() ?? null,
         }
       : {}),
     openYomitanSettingsWindow: (params: {

src/main/runtime/cli-command-context-deps.test.ts

@@ -70,6 +70,7 @@ test('build cli command context deps maps handlers and values', () => {
       calls.push('run-youtube-playback');
     },
     openYomitanSettings: () => calls.push('yomitan'),
+    openConfigSettingsWindow: () => calls.push('config-settings'),
     cycleSecondarySubMode: () => calls.push('cycle-secondary'),
     openRuntimeOptionsPalette: () => calls.push('runtime-options'),
     printHelp: () => calls.push('help'),

src/main/runtime/cli-command-context-deps.ts

@@ -44,6 +44,7 @@ export function createBuildCliCommandContextDepsHandler(deps: {
   runUpdateCommand: CliCommandContextFactoryDeps['runUpdateCommand'];
   runYoutubePlaybackFlow: CliCommandContextFactoryDeps['runYoutubePlaybackFlow'];
   openYomitanSettings: () => void;
+  openConfigSettingsWindow: () => void;
   cycleSecondarySubMode: () => void;
   openRuntimeOptionsPalette: () => void;
   printHelp: () => void;
@@ -99,6 +100,7 @@ export function createBuildCliCommandContextDepsHandler(deps: {
     runUpdateCommand: deps.runUpdateCommand,
     runYoutubePlaybackFlow: deps.runYoutubePlaybackFlow,
     openYomitanSettings: deps.openYomitanSettings,
+    openConfigSettingsWindow: deps.openConfigSettingsWindow,
     cycleSecondarySubMode: deps.cycleSecondarySubMode,
     openRuntimeOptionsPalette: deps.openRuntimeOptionsPalette,
     printHelp: deps.printHelp,

src/main/runtime/cli-command-context-factory.test.ts

@@ -74,6 +74,7 @@ test('cli command context factory composes main deps and context handlers', () =
     runUpdateCommand: async () => {},
     runYoutubePlaybackFlow: async () => {},
     openYomitanSettings: () => {},
+    openConfigSettingsWindow: () => {},
     cycleSecondarySubMode: () => {},
     openRuntimeOptionsPalette: () => {},
     printHelp: () => {},

src/main/runtime/cli-command-context-main-deps.test.ts

@@ -100,6 +100,7 @@ test('cli command context main deps builder maps state and callbacks', async ()
       calls.push('run-youtube-playback');
     },
     openYomitanSettings: () => calls.push('open-yomitan'),
+    openConfigSettingsWindow: () => calls.push('open-config-settings'),
     cycleSecondarySubMode: () => calls.push('cycle-secondary'),
     openRuntimeOptionsPalette: () => calls.push('open-runtime-options'),
     printHelp: () => calls.push('help'),
@@ -129,6 +130,7 @@ test('cli command context main deps builder maps state and callbacks', async ()
   deps.initializeOverlay();
   deps.openFirstRunSetup(true);
   deps.setVisibleOverlay(true);
+  deps.openConfigSettingsWindow();
   deps.printHelp();
   await deps.runUpdateCommand({ update: true } as never, 'initial');
 
@@ -137,6 +139,7 @@ test('cli command context main deps builder maps state and callbacks', async ()
     'init-overlay',
     'open-setup:force',
     'set-visible:true',
+    'open-config-settings',
     'help',
     'run-update',
   ]);

src/main/runtime/cli-command-context-main-deps.ts

@@ -57,6 +57,7 @@ export function createBuildCliCommandContextMainDepsHandler(deps: {
   runYoutubePlaybackFlow: CliCommandContextFactoryDeps['runYoutubePlaybackFlow'];
 
   openYomitanSettings: () => void;
+  openConfigSettingsWindow: () => void;
   cycleSecondarySubMode: () => void;
   openRuntimeOptionsPalette: () => void;
   printHelp: () => void;
@@ -127,6 +128,7 @@ export function createBuildCliCommandContextMainDepsHandler(deps: {
       deps.runUpdateCommand(args, source),
     runYoutubePlaybackFlow: (request) => deps.runYoutubePlaybackFlow(request),
     openYomitanSettings: () => deps.openYomitanSettings(),
+    openConfigSettingsWindow: () => deps.openConfigSettingsWindow(),
     cycleSecondarySubMode: () => deps.cycleSecondarySubMode(),
     openRuntimeOptionsPalette: () => deps.openRuntimeOptionsPalette(),
     printHelp: () => deps.printHelp(),

src/main/runtime/cli-command-context.test.ts

@@ -56,6 +56,7 @@ function createDeps() {
       runUpdateCommand: async () => {},
       runYoutubePlaybackFlow: async () => {},
       openYomitanSettings: () => {},
+      openConfigSettingsWindow: () => {},
       cycleSecondarySubMode: () => {},
       openRuntimeOptionsPalette: () => {},
       printHelp: () => {},

src/main/runtime/cli-command-context.ts

@@ -49,6 +49,7 @@ export type CliCommandContextFactoryDeps = {
   runUpdateCommand: CliCommandRuntimeServiceContext['runUpdateCommand'];
   runYoutubePlaybackFlow: CliCommandRuntimeServiceContext['runYoutubePlaybackFlow'];
   openYomitanSettings: () => void;
+  openConfigSettingsWindow: () => void;
   cycleSecondarySubMode: () => void;
   openRuntimeOptionsPalette: () => void;
   printHelp: () => void;
@@ -126,6 +127,7 @@ export function createCliCommandContext(
     runUpdateCommand: deps.runUpdateCommand,
     runYoutubePlaybackFlow: deps.runYoutubePlaybackFlow,
     openYomitanSettings: deps.openYomitanSettings,
+    openConfigSettingsWindow: deps.openConfigSettingsWindow,
     cycleSecondarySubMode: deps.cycleSecondarySubMode,
     openRuntimeOptionsPalette: deps.openRuntimeOptionsPalette,
     printHelp: deps.printHelp,

src/main/runtime/command-line-launcher-windows.ts

@@ -47,10 +47,7 @@ export function getUserPath(options: CommonOptions & WindowsPathOptions): string
   return options.getUserPath?.() ?? envOf(options).Path ?? envOf(options).PATH ?? '';
 }
 
-async function setWindowsUserPath(
-  options: CommonOptions & WindowsPathOptions,
-  nextPath: string,
-) {
+async function setWindowsUserPath(options: CommonOptions & WindowsPathOptions, nextPath: string) {
   if (options.setUserPath) {
     await options.setUserPath(nextPath);
     return;
@@ -96,6 +93,7 @@ export async function appendWindowsUserPathDir(
 }
 
 export function defaultBunRepairPath(options: CommonOptions & WindowsPathOptions): string {
-  const userProfile = options.userProfile ?? envOf(options).USERPROFILE ?? options.homeDir ?? os.homedir();
+  const userProfile =
+    options.userProfile ?? envOf(options).USERPROFILE ?? options.homeDir ?? os.homedir();
   return path.win32.join(userProfile, '.bun', 'bin');
 }

src/main/runtime/composers/cli-startup-composer.test.ts

@@ -50,6 +50,7 @@ test('composeCliStartupHandlers returns callable CLI startup handlers', () => {
       runUpdateCommand: async () => {},
       runYoutubePlaybackFlow: async () => {},
       openYomitanSettings: () => {},
+      openConfigSettingsWindow: () => {},
       cycleSecondarySubMode: () => {},
       openRuntimeOptionsPalette: () => {},
       printHelp: () => {},

src/main/runtime/config-settings-ipc.test.ts

@@ -0,0 +1,66 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { isConfigSettingsPatch } from './config-settings-ipc';
+import type { ConfigSettingsField } from '../../types/settings';
+
+const fields: ConfigSettingsField[] = [
+  {
+    id: 'mpv.launchMode',
+    label: 'Launch mode',
+    description: 'Launch mode setting.',
+    configPath: 'mpv.launchMode',
+    category: 'playback-sources',
+    section: 'mpv launcher',
+    control: 'select',
+    defaultValue: 'windowed',
+    restartBehavior: 'restart',
+  },
+];
+
+test('isConfigSettingsPatch rejects set operations without a value property', () => {
+  assert.equal(
+    isConfigSettingsPatch(
+      {
+        operations: [{ op: 'set', path: 'mpv.launchMode' }],
+      },
+      fields,
+    ),
+    false,
+  );
+});
+
+test('isConfigSettingsPatch accepts set operations with an explicit value', () => {
+  assert.equal(
+    isConfigSettingsPatch(
+      {
+        operations: [{ op: 'set', path: 'mpv.launchMode', value: 'fullscreen' }],
+      },
+      fields,
+    ),
+    true,
+  );
+});
+
+test('isConfigSettingsPatch accepts reset operations without a value', () => {
+  assert.equal(
+    isConfigSettingsPatch(
+      {
+        operations: [{ op: 'reset', path: 'mpv.launchMode' }],
+      },
+      fields,
+    ),
+    true,
+  );
+});
+
+test('isConfigSettingsPatch rejects unknown config paths', () => {
+  assert.equal(
+    isConfigSettingsPatch(
+      {
+        operations: [{ op: 'reset', path: 'unknown.path' }],
+      },
+      fields,
+    ),
+    false,
+  );
+});

src/main/runtime/config-settings-ipc.ts

@@ -0,0 +1,30 @@
+import type { ConfigSettingsField, ConfigSettingsPatch } from '../../types/settings';
+
+export function isConfigSettingsPatch(
+  value: unknown,
+  fields: readonly ConfigSettingsField[],
+): value is ConfigSettingsPatch {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  const operations = (value as { operations?: unknown }).operations;
+  return (
+    Array.isArray(operations) &&
+    operations.every((operation) => {
+      if (!operation || typeof operation !== 'object') {
+        return false;
+      }
+      const candidate = operation as { op?: unknown; path?: unknown; value?: unknown };
+      const knownPath =
+        typeof candidate.path === 'string' &&
+        fields.some((field) => field.configPath === candidate.path);
+      if (!knownPath) {
+        return false;
+      }
+      if (candidate.op === 'set') {
+        return 'value' in candidate;
+      }
+      return candidate.op === 'reset';
+    })
+  );
+}

src/main/runtime/config-settings-runtime.ts

@@ -0,0 +1,166 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildConfigSettingsSnapshot } from '../../config/settings/jsonc-edit';
+import type { ConfigValidationWarning, RawConfig, ResolvedConfig } from '../../types/config';
+import type {
+  ConfigSettingsField,
+  ConfigSettingsSaveResult,
+  ConfigSettingsSnapshot,
+} from '../../types/settings';
+import type { ReloadConfigStrictResult } from '../../config';
+import {
+  classifyConfigHotReloadDiff,
+  type ConfigHotReloadDiff,
+} from '../../core/services/config-hot-reload';
+import { createSaveConfigSettingsPatchHandler } from './config-settings-save';
+import {
+  createOpenConfigSettingsWindowHandler,
+  type ConfigSettingsWindowLike,
+} from './config-settings-window';
+import { isConfigSettingsPatch } from './config-settings-ipc';
+
+export interface ConfigSettingsIpcMainLike {
+  handle(channel: string, listener: (event: unknown, ...args: unknown[]) => unknown): unknown;
+}
+
+export interface ConfigSettingsIpcChannels {
+  getConfigSettingsSnapshot: string;
+  saveConfigSettingsPatch: string;
+  openConfigSettingsFile: string;
+  openConfigSettingsWindow: string;
+}
+
+export interface ConfigSettingsRuntimeDeps<TWindow extends ConfigSettingsWindowLike> {
+  fields: ConfigSettingsField[];
+  getConfigPath(): string;
+  getRawConfig(): RawConfig;
+  getConfig(): ResolvedConfig;
+  getWarnings(): ConfigValidationWarning[];
+  reloadConfigStrict(): ReloadConfigStrictResult;
+  applyHotReload(diff: ConfigHotReloadDiff, config: ResolvedConfig): void;
+  getSettingsWindow(): TWindow | null;
+  setSettingsWindow(window: TWindow | null): void;
+  createSettingsWindow(): TWindow;
+  settingsHtmlPath: string;
+  openPath(path: string): Promise<string>;
+  ipcMain: ConfigSettingsIpcMainLike;
+  ipcChannels: ConfigSettingsIpcChannels;
+  log?: (message: string) => void;
+}
+
+export function writeTextFileAtomically(targetPath: string, content: string): void {
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  const tempPath = path.join(
+    path.dirname(targetPath),
+    `.${path.basename(targetPath)}.${process.pid}.${Date.now()}.tmp`,
+  );
+  try {
+    fs.writeFileSync(tempPath, content, 'utf-8');
+    fs.renameSync(tempPath, targetPath);
+  } catch (error) {
+    try {
+      fs.rmSync(tempPath, { force: true });
+    } catch {
+      // Best effort cleanup after a failed atomic write.
+    }
+    throw error;
+  }
+}
+
+function getRestartRequiredSettingsSections(
+  fields: readonly ConfigSettingsField[],
+  restartRequiredFields: string[],
+): string[] {
+  const sections = new Set<string>();
+  for (const field of fields) {
+    if (
+      restartRequiredFields.some(
+        (restartField) =>
+          field.configPath === restartField ||
+          field.configPath.startsWith(`${restartField}.`) ||
+          restartField.startsWith(`${field.configPath}.`),
+      )
+    ) {
+      sections.add(field.section);
+    }
+  }
+  return [...sections].sort();
+}
+
+export function createConfigSettingsRuntime<TWindow extends ConfigSettingsWindowLike>(
+  deps: ConfigSettingsRuntimeDeps<TWindow>,
+) {
+  function getSnapshot(): ConfigSettingsSnapshot {
+    return buildConfigSettingsSnapshot({
+      configPath: deps.getConfigPath(),
+      rawConfig: deps.getRawConfig(),
+      resolvedConfig: deps.getConfig(),
+      warnings: deps.getWarnings(),
+      fields: deps.fields,
+    });
+  }
+
+  const savePatch = createSaveConfigSettingsPatchHandler({
+    getConfigPath: () => deps.getConfigPath(),
+    getCurrentConfig: () => deps.getConfig(),
+    getWarnings: () => deps.getWarnings(),
+    getSnapshot,
+    fileExists: (targetPath) => fs.existsSync(targetPath),
+    readText: (targetPath) => fs.readFileSync(targetPath, 'utf-8'),
+    writeTextAtomically: (targetPath, content) => writeTextFileAtomically(targetPath, content),
+    deleteFile: (targetPath) => fs.rmSync(targetPath, { force: true }),
+    reloadConfigStrict: () => deps.reloadConfigStrict(),
+    classifyDiff: (previous, next) => classifyConfigHotReloadDiff(previous, next),
+    applyHotReload: (diff, config) => deps.applyHotReload(diff, config),
+    getRestartRequiredSections: (fields) => getRestartRequiredSettingsSections(deps.fields, fields),
+  });
+
+  function ensureConfigFileExists(): string {
+    const configPath = deps.getConfigPath();
+    if (!fs.existsSync(configPath)) {
+      writeTextFileAtomically(configPath, '{}\n');
+    }
+    return configPath;
+  }
+
+  const openWindow = createOpenConfigSettingsWindowHandler({
+    getSettingsWindow: deps.getSettingsWindow,
+    setSettingsWindow: deps.setSettingsWindow,
+    createSettingsWindow: deps.createSettingsWindow,
+    settingsHtmlPath: deps.settingsHtmlPath,
+    log: deps.log,
+  });
+
+  function invalidPatchResult(): ConfigSettingsSaveResult {
+    return {
+      ok: false,
+      warnings: [],
+      error: 'Invalid config settings patch.',
+      hotReloadFields: [],
+      restartRequiredFields: [],
+      restartRequiredSections: [],
+    };
+  }
+
+  function registerHandlers(): void {
+    deps.ipcMain.handle(deps.ipcChannels.getConfigSettingsSnapshot, () => getSnapshot());
+    deps.ipcMain.handle(deps.ipcChannels.saveConfigSettingsPatch, (_event, patch: unknown) => {
+      if (!isConfigSettingsPatch(patch, deps.fields)) {
+        return invalidPatchResult();
+      }
+      return savePatch(patch);
+    });
+    deps.ipcMain.handle(deps.ipcChannels.openConfigSettingsFile, async () => {
+      const openError = await deps.openPath(ensureConfigFileExists());
+      return openError.length === 0;
+    });
+    deps.ipcMain.handle(deps.ipcChannels.openConfigSettingsWindow, () => openWindow());
+  }
+
+  return {
+    getSnapshot,
+    savePatch,
+    openWindow,
+    registerHandlers,
+  };
+}

src/main/runtime/config-settings-save.test.ts

@@ -0,0 +1,148 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { DEFAULT_CONFIG, type ReloadConfigStrictResult } from '../../config';
+import type { ResolvedConfig } from '../../types/config';
+import type { ConfigSettingsSnapshot } from '../../types/settings';
+import { createSaveConfigSettingsPatchHandler } from './config-settings-save';
+
+function snapshot(): ConfigSettingsSnapshot {
+  return {
+    configPath: '/tmp/config.jsonc',
+    fields: [],
+    values: {},
+    warnings: [],
+  };
+}
+
+test('config settings save applies hot-reloadable diff live', () => {
+  const calls: string[] = [];
+  const previous = DEFAULT_CONFIG;
+  const next: ResolvedConfig = {
+    ...DEFAULT_CONFIG,
+    subtitleStyle: {
+      ...DEFAULT_CONFIG.subtitleStyle,
+      autoPauseVideoOnHover: false,
+    },
+  };
+  let written = '';
+  const save = createSaveConfigSettingsPatchHandler({
+    getConfigPath: () => '/tmp/config.jsonc',
+    getCurrentConfig: () => previous,
+    getWarnings: () => [],
+    getSnapshot: () => snapshot(),
+    fileExists: () => true,
+    readText: () => '{}',
+    writeTextAtomically: (_path, content) => {
+      written = content;
+      calls.push('write');
+    },
+    reloadConfigStrict: (): ReloadConfigStrictResult => ({
+      ok: true,
+      config: next,
+      warnings: [],
+      path: '/tmp/config.jsonc',
+    }),
+    classifyDiff: () => ({
+      hotReloadFields: ['subtitleStyle'],
+      restartRequiredFields: [],
+    }),
+    applyHotReload: (diff) => calls.push(`hot:${diff.hotReloadFields.join(',')}`),
+    getRestartRequiredSections: () => [],
+  });
+
+  const result = save({
+    operations: [
+      {
+        op: 'set',
+        path: 'subtitleStyle.autoPauseVideoOnHover',
+        value: false,
+      },
+    ],
+  });
+
+  assert.equal(result.ok, true);
+  assert.match(written, /autoPauseVideoOnHover/);
+  assert.deepEqual(calls, ['write', 'hot:subtitleStyle']);
+  assert.deepEqual(result.hotReloadFields, ['subtitleStyle']);
+  assert.deepEqual(result.restartRequiredFields, []);
+});
+
+test('config settings save returns restart-required sections without applying hot reload', () => {
+  const calls: string[] = [];
+  const previous = DEFAULT_CONFIG;
+  const next: ResolvedConfig = {
+    ...DEFAULT_CONFIG,
+    mpv: {
+      ...DEFAULT_CONFIG.mpv,
+      launchMode: 'fullscreen',
+    },
+  };
+  const save = createSaveConfigSettingsPatchHandler({
+    getConfigPath: () => '/tmp/config.jsonc',
+    getCurrentConfig: () => previous,
+    getWarnings: () => [],
+    getSnapshot: () => snapshot(),
+    fileExists: () => true,
+    readText: () => '{}',
+    writeTextAtomically: () => calls.push('write'),
+    reloadConfigStrict: (): ReloadConfigStrictResult => ({
+      ok: true,
+      config: next,
+      warnings: [],
+      path: '/tmp/config.jsonc',
+    }),
+    classifyDiff: () => ({
+      hotReloadFields: [],
+      restartRequiredFields: ['mpv'],
+    }),
+    applyHotReload: () => calls.push('hot'),
+    getRestartRequiredSections: () => ['mpv launcher'],
+  });
+
+  const result = save({
+    operations: [{ op: 'set', path: 'mpv.launchMode', value: 'fullscreen' }],
+  });
+
+  assert.equal(result.ok, true);
+  assert.deepEqual(calls, ['write']);
+  assert.deepEqual(result.hotReloadFields, []);
+  assert.deepEqual(result.restartRequiredFields, ['mpv']);
+  assert.deepEqual(result.restartRequiredSections, ['mpv launcher']);
+});
+
+test('config settings save restores previous file content when strict reload fails', () => {
+  const writes: string[] = [];
+  const save = createSaveConfigSettingsPatchHandler({
+    getConfigPath: () => '/tmp/config.jsonc',
+    getCurrentConfig: () => DEFAULT_CONFIG,
+    getWarnings: () => [],
+    getSnapshot: () => snapshot(),
+    fileExists: () => true,
+    readText: () => '{"mpv":{"launchMode":"normal"}}\n',
+    writeTextAtomically: (_path, content) => {
+      writes.push(content);
+    },
+    reloadConfigStrict: (): ReloadConfigStrictResult => ({
+      ok: false,
+      error: 'invalid config',
+      path: '/tmp/config.jsonc',
+    }),
+    classifyDiff: () => {
+      throw new Error('Should not classify invalid config.');
+    },
+    applyHotReload: () => {
+      throw new Error('Should not hot reload invalid config.');
+    },
+    getRestartRequiredSections: () => [],
+  });
+
+  const result = save({
+    operations: [{ op: 'set', path: 'mpv.launchMode', value: 'fullscreen' }],
+  });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.error, 'invalid config');
+  assert.equal(writes.length, 2);
+  assert.match(writes[0] ?? '', /fullscreen/);
+  assert.equal(writes[1], '{"mpv":{"launchMode":"normal"}}\n');
+});

src/main/runtime/config-settings-save.ts

@@ -0,0 +1,98 @@
+import type { ReloadConfigStrictResult } from '../../config';
+import { applyConfigSettingsPatchToContent } from '../../config/settings/jsonc-edit';
+import type { ConfigValidationWarning, ResolvedConfig } from '../../types/config';
+import type {
+  ConfigSettingsPatch,
+  ConfigSettingsSaveResult,
+  ConfigSettingsSnapshot,
+} from '../../types/settings';
+
+export interface ConfigSettingsHotReloadDiff {
+  hotReloadFields: string[];
+  restartRequiredFields: string[];
+}
+
+export interface ConfigSettingsSaveDeps {
+  getConfigPath(): string;
+  getCurrentConfig(): ResolvedConfig;
+  getWarnings(): ConfigValidationWarning[];
+  getSnapshot(): ConfigSettingsSnapshot;
+  fileExists(path: string): boolean;
+  readText(path: string): string;
+  writeTextAtomically(path: string, content: string): void;
+  deleteFile?(path: string): void;
+  reloadConfigStrict(): ReloadConfigStrictResult;
+  classifyDiff(prev: ResolvedConfig, next: ResolvedConfig): ConfigSettingsHotReloadDiff;
+  applyHotReload(diff: ConfigSettingsHotReloadDiff, config: ResolvedConfig): void;
+  getRestartRequiredSections(restartRequiredFields: string[]): string[];
+}
+
+export function createSaveConfigSettingsPatchHandler(deps: ConfigSettingsSaveDeps) {
+  return (patch: ConfigSettingsPatch): ConfigSettingsSaveResult => {
+    if (patch.operations.length === 0) {
+      return {
+        ok: true,
+        snapshot: deps.getSnapshot(),
+        hotReloadFields: [],
+        restartRequiredFields: [],
+        restartRequiredSections: [],
+      };
+    }
+
+    const configPath = deps.getConfigPath();
+    const previousConfig = deps.getCurrentConfig();
+    const previousWarnings = deps.getWarnings();
+    const hadExistingConfig = deps.fileExists(configPath);
+    const content = hadExistingConfig ? deps.readText(configPath) : '{}\n';
+    const candidate = applyConfigSettingsPatchToContent({
+      content,
+      operations: patch.operations,
+      previousWarnings,
+    });
+
+    if (!candidate.ok) {
+      return {
+        ok: false,
+        warnings: candidate.warnings,
+        error: candidate.error,
+        hotReloadFields: [],
+        restartRequiredFields: [],
+        restartRequiredSections: [],
+      };
+    }
+
+    deps.writeTextAtomically(configPath, candidate.content);
+    const reloadResult = deps.reloadConfigStrict();
+    if (!reloadResult.ok) {
+      if (hadExistingConfig) {
+        deps.writeTextAtomically(configPath, content);
+      } else if (deps.deleteFile) {
+        deps.deleteFile(configPath);
+      } else {
+        deps.writeTextAtomically(configPath, content);
+      }
+      return {
+        ok: false,
+        warnings: [],
+        error: reloadResult.error,
+        hotReloadFields: [],
+        restartRequiredFields: [],
+        restartRequiredSections: [],
+      };
+    }
+
+    const diff = deps.classifyDiff(previousConfig, reloadResult.config);
+    if (diff.hotReloadFields.length > 0) {
+      deps.applyHotReload(diff, reloadResult.config);
+    }
+
+    return {
+      ok: true,
+      snapshot: deps.getSnapshot(),
+      warnings: reloadResult.warnings,
+      hotReloadFields: diff.hotReloadFields,
+      restartRequiredFields: diff.restartRequiredFields,
+      restartRequiredSections: deps.getRestartRequiredSections(diff.restartRequiredFields),
+    };
+  };
+}

src/main/runtime/config-settings-window.test.ts

@@ -0,0 +1,83 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createOpenConfigSettingsWindowHandler } from './config-settings-window';
+
+test('createOpenConfigSettingsWindowHandler focuses existing settings window', () => {
+  const calls: string[] = [];
+  const existing = {
+    isDestroyed: () => false,
+    focus: () => calls.push('focus'),
+    loadFile: () => calls.push('load'),
+    on: () => {},
+  };
+
+  const open = createOpenConfigSettingsWindowHandler({
+    getSettingsWindow: () => existing,
+    setSettingsWindow: () => calls.push('set'),
+    createSettingsWindow: () => {
+      throw new Error('Should not create a second window.');
+    },
+    settingsHtmlPath: '/tmp/settings.html',
+  });
+
+  assert.equal(open(), true);
+  assert.deepEqual(calls, ['focus']);
+});
+
+test('createOpenConfigSettingsWindowHandler creates window and clears closed state', () => {
+  const calls: string[] = [];
+  const handlers: { closed?: () => void } = {};
+  const created = {
+    isDestroyed: () => false,
+    focus: () => calls.push('focus'),
+    loadFile: (path: string) => calls.push(`load:${path}`),
+    on: (event: string, handler: () => void) => {
+      if (event === 'closed') handlers.closed = handler;
+    },
+  };
+
+  const open = createOpenConfigSettingsWindowHandler({
+    getSettingsWindow: () => null,
+    setSettingsWindow: (window) => calls.push(window ? 'set:window' : 'set:null'),
+    createSettingsWindow: () => created,
+    settingsHtmlPath: '/tmp/settings.html',
+  });
+
+  assert.equal(open(), true);
+  assert.deepEqual(calls, ['load:/tmp/settings.html', 'set:window', 'focus']);
+  assert.ok(handlers.closed);
+  handlers.closed();
+  assert.equal(calls.at(-1), 'set:null');
+});
+
+test('createOpenConfigSettingsWindowHandler clears failed load window state', async () => {
+  const calls: string[] = [];
+  const created = {
+    isDestroyed: () => false,
+    focus: () => calls.push('focus'),
+    loadFile: (path: string) => {
+      calls.push(`load:${path}`);
+      return Promise.reject(new Error('missing settings html'));
+    },
+    on: () => {},
+    destroy: () => calls.push('destroy'),
+  };
+
+  const open = createOpenConfigSettingsWindowHandler({
+    getSettingsWindow: () => null,
+    setSettingsWindow: (window) => calls.push(window ? 'set:window' : 'set:null'),
+    createSettingsWindow: () => created,
+    settingsHtmlPath: '/tmp/missing-settings.html',
+  });
+
+  assert.equal(open(), true);
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  assert.deepEqual(calls, [
+    'load:/tmp/missing-settings.html',
+    'set:window',
+    'focus',
+    'set:null',
+    'destroy',
+  ]);
+});

src/main/runtime/config-settings-window.ts

@@ -0,0 +1,41 @@
+export interface ConfigSettingsWindowLike {
+  isDestroyed(): boolean;
+  focus(): void;
+  loadFile(path: string): unknown;
+  on(event: 'closed', handler: () => void): unknown;
+  destroy?(): unknown;
+}
+
+export interface OpenConfigSettingsWindowDeps<TWindow extends ConfigSettingsWindowLike> {
+  getSettingsWindow(): TWindow | null;
+  setSettingsWindow(window: TWindow | null): void;
+  createSettingsWindow(): TWindow;
+  settingsHtmlPath: string;
+  log?: (message: string) => void;
+}
+
+export function createOpenConfigSettingsWindowHandler<TWindow extends ConfigSettingsWindowLike>(
+  deps: OpenConfigSettingsWindowDeps<TWindow>,
+): () => boolean {
+  return () => {
+    const existing = deps.getSettingsWindow();
+    if (existing && !existing.isDestroyed()) {
+      existing.focus();
+      return true;
+    }
+
+    const window = deps.createSettingsWindow();
+    void Promise.resolve(window.loadFile(deps.settingsHtmlPath)).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      deps.log?.(`Failed to load configuration settings window: ${message}`);
+      deps.setSettingsWindow(null);
+      window.destroy?.();
+    });
+    deps.setSettingsWindow(window);
+    window.on('closed', () => {
+      deps.setSettingsWindow(null);
+    });
+    window.focus();
+    return true;
+  };
+}

src/main/runtime/first-run-setup-service.test.ts

@@ -30,6 +30,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
     toggleVisibleOverlay: false,
     togglePrimarySubtitleBar: false,
     settings: false,
+    configSettings: false,
     setup: false,
     show: false,
     hide: false,
@@ -120,6 +121,7 @@ function createCommandLineLauncherSnapshot(
 test('shouldAutoOpenFirstRunSetup only for startup/setup intents', () => {
   assert.equal(shouldAutoOpenFirstRunSetup(makeArgs({ start: true, background: true })), true);
   assert.equal(shouldAutoOpenFirstRunSetup(makeArgs({ background: true, setup: true })), true);
+  assert.equal(shouldAutoOpenFirstRunSetup(makeArgs({ start: true, configSettings: true })), false);
   assert.equal(
     shouldAutoOpenFirstRunSetup(makeArgs({ background: true, jellyfinRemoteAnnounce: true })),
     false,

src/main/runtime/first-run-setup-service.ts

@@ -72,6 +72,7 @@ function hasAnyStartupCommandBeyondSetup(args: CliArgs): boolean {
     args.togglePrimarySubtitleBar ||
     args.launchMpv ||
     args.settings ||
+    args.configSettings ||
     args.show ||
     args.hide ||
     args.showVisibleOverlay ||

src/main/runtime/setup-window-factory.test.ts

@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 import {
   createCreateAnilistSetupWindowHandler,
+  createCreateConfigSettingsWindowHandler,
   createCreateFirstRunSetupWindowHandler,
   createCreateJellyfinSetupWindowHandler,
 } from './setup-window-factory';
@@ -77,3 +78,31 @@ test('createCreateAnilistSetupWindowHandler builds anilist setup window', () =>
     },
   });
 });
+
+test('createCreateConfigSettingsWindowHandler builds configuration settings window', () => {
+  let options: Electron.BrowserWindowConstructorOptions | null = null;
+  const createSettingsWindow = createCreateConfigSettingsWindowHandler({
+    preloadPath: '/tmp/preload-settings.js',
+    createBrowserWindow: (nextOptions) => {
+      options = nextOptions;
+      return { id: 'config-settings' } as never;
+    },
+  });
+
+  assert.deepEqual(createSettingsWindow(), { id: 'config-settings' });
+  assert.deepEqual(options, {
+    width: 1040,
+    height: 760,
+    title: 'SubMiner Configuration',
+    show: true,
+    autoHideMenuBar: true,
+    resizable: true,
+    backgroundColor: '#24273a',
+    webPreferences: {
+      nodeIntegration: false,
+      contextIsolation: true,
+      sandbox: false,
+      preload: '/tmp/preload-settings.js',
+    },
+  });
+});

src/main/runtime/setup-window-factory.ts

@@ -5,6 +5,9 @@ interface SetupWindowConfig {
   resizable?: boolean;
   minimizable?: boolean;
   maximizable?: boolean;
+  preloadPath?: string;
+  sandbox?: boolean;
+  backgroundColor?: string;
 }
 
 function createSetupWindowHandler<TWindow>(
@@ -21,9 +24,12 @@ function createSetupWindowHandler<TWindow>(
       ...(config.resizable === undefined ? {} : { resizable: config.resizable }),
       ...(config.minimizable === undefined ? {} : { minimizable: config.minimizable }),
       ...(config.maximizable === undefined ? {} : { maximizable: config.maximizable }),
+      ...(config.backgroundColor === undefined ? {} : { backgroundColor: config.backgroundColor }),
       webPreferences: {
         nodeIntegration: false,
         contextIsolation: true,
+        ...(config.sandbox === undefined ? {} : { sandbox: config.sandbox }),
+        ...(config.preloadPath ? { preload: config.preloadPath } : {}),
       },
     });
 }
@@ -60,3 +66,18 @@ export function createCreateAnilistSetupWindowHandler<TWindow>(deps: {
     title: 'Anilist Setup',
   });
 }
+
+export function createCreateConfigSettingsWindowHandler<TWindow>(deps: {
+  createBrowserWindow: (options: Electron.BrowserWindowConstructorOptions) => TWindow;
+  preloadPath: string;
+}) {
+  return createSetupWindowHandler(deps, {
+    width: 1040,
+    height: 760,
+    title: 'SubMiner Configuration',
+    resizable: true,
+    preloadPath: deps.preloadPath,
+    sandbox: false,
+    backgroundColor: '#24273a',
+  });
+}

src/main/runtime/startup-mode-flags.test.ts

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { parseArgs } from '../../cli/args';
+import {
+  getStartupModeFlags,
+  shouldRefreshAnilistOnConfigReload,
+  shouldStartAutomaticUpdateChecks,
+} from './startup-mode-flags';
+
+test('config settings startup uses minimal startup and skips background integrations', () => {
+  const args = parseArgs(['--config']);
+  const flags = getStartupModeFlags(args);
+
+  assert.equal(flags.shouldUseMinimalStartup, true);
+  assert.equal(flags.shouldSkipHeavyStartup, true);
+  assert.equal(shouldRefreshAnilistOnConfigReload(args), false);
+  assert.equal(shouldStartAutomaticUpdateChecks(args), false);
+});
+
+test('normal startup still allows background integrations', () => {
+  const flags = getStartupModeFlags(null);
+
+  assert.equal(flags.shouldUseMinimalStartup, false);
+  assert.equal(flags.shouldSkipHeavyStartup, false);
+  assert.equal(shouldRefreshAnilistOnConfigReload(null), true);
+  assert.equal(shouldStartAutomaticUpdateChecks(null), true);
+});

src/main/runtime/startup-mode-flags.ts

@@ -0,0 +1,40 @@
+import type { CliArgs } from '../../cli/args';
+import {
+  isHeadlessInitialCommand,
+  isStandaloneTexthookerCommand,
+  shouldRunSettingsOnlyStartup,
+} from '../../cli/args';
+
+export function getStartupModeFlags(initialArgs: CliArgs | null | undefined): {
+  shouldUseMinimalStartup: boolean;
+  shouldSkipHeavyStartup: boolean;
+} {
+  return {
+    shouldUseMinimalStartup: Boolean(
+      (initialArgs && isStandaloneTexthookerCommand(initialArgs)) ||
+      initialArgs?.configSettings ||
+      initialArgs?.update ||
+      (initialArgs?.stats &&
+        (initialArgs.statsCleanup || initialArgs.statsBackground || initialArgs.statsStop)),
+    ),
+    shouldSkipHeavyStartup: Boolean(
+      initialArgs &&
+      (shouldRunSettingsOnlyStartup(initialArgs) ||
+        initialArgs.configSettings ||
+        initialArgs.stats ||
+        initialArgs.dictionary ||
+        initialArgs.update ||
+        initialArgs.setup),
+    ),
+  };
+}
+
+export function shouldRefreshAnilistOnConfigReload(
+  initialArgs: CliArgs | null | undefined,
+): boolean {
+  return !(initialArgs && (isHeadlessInitialCommand(initialArgs) || initialArgs.configSettings));
+}
+
+export function shouldStartAutomaticUpdateChecks(initialArgs: CliArgs | null | undefined): boolean {
+  return !(initialArgs && (isHeadlessInitialCommand(initialArgs) || initialArgs.configSettings));
+}

src/main/runtime/tray-main-actions.test.ts

@@ -48,6 +48,7 @@ test('build tray template handler wires actions and init guards', () => {
       handlers.openWindowsMpvLauncherSetup();
       handlers.openYomitanSettings();
       handlers.openRuntimeOptions();
+      handlers.openConfigSettings();
       handlers.openJellyfinSetup();
       handlers.toggleJellyfinDiscovery();
       handlers.openAnilistSetup();
@@ -68,6 +69,7 @@ test('build tray template handler wires actions and init guards', () => {
     showWindowsMpvLauncherSetup: () => true,
     openYomitanSettings: () => calls.push('yomitan'),
     openRuntimeOptionsPalette: () => calls.push('runtime-options'),
+    openConfigSettingsWindow: () => calls.push('configuration'),
     openJellyfinSetupWindow: () => calls.push('jellyfin'),
     isJellyfinConfigured: () => true,
     isJellyfinDiscoveryActive: () => false,
@@ -90,6 +92,7 @@ test('build tray template handler wires actions and init guards', () => {
     'setup',
     'yomitan',
     'runtime-options',
+    'configuration',
     'jellyfin',
     'jellyfin-discovery',
     'anilist',

src/main/runtime/tray-main-actions.ts

@@ -37,6 +37,7 @@ export function createBuildTrayMenuTemplateHandler<TMenuItem>(deps: {
     showWindowsMpvLauncherSetup: boolean;
     openYomitanSettings: () => void;
     openRuntimeOptions: () => void;
+    openConfigSettings: () => void;
     openJellyfinSetup: () => void;
     showJellyfinDiscovery: boolean;
     jellyfinDiscoveryActive: boolean;
@@ -55,6 +56,7 @@ export function createBuildTrayMenuTemplateHandler<TMenuItem>(deps: {
   showWindowsMpvLauncherSetup: () => boolean;
   openYomitanSettings: () => void;
   openRuntimeOptionsPalette: () => void;
+  openConfigSettingsWindow: () => void;
   openJellyfinSetupWindow: () => void;
   isJellyfinConfigured: () => boolean;
   isJellyfinDiscoveryActive: () => boolean;
@@ -92,6 +94,9 @@ export function createBuildTrayMenuTemplateHandler<TMenuItem>(deps: {
         }
         deps.openRuntimeOptionsPalette();
       },
+      openConfigSettings: () => {
+        deps.openConfigSettingsWindow();
+      },
       openJellyfinSetup: () => {
         deps.openJellyfinSetupWindow();
       },

src/main/runtime/tray-main-deps.test.ts

@@ -32,6 +32,7 @@ test('tray main deps builders return mapped handlers', () => {
     showWindowsMpvLauncherSetup: () => true,
     openYomitanSettings: () => calls.push('yomitan'),
     openRuntimeOptionsPalette: () => calls.push('runtime-options'),
+    openConfigSettingsWindow: () => calls.push('configuration'),
     openJellyfinSetupWindow: () => calls.push('jellyfin'),
     isJellyfinConfigured: () => true,
     isJellyfinDiscoveryActive: () => false,
@@ -53,6 +54,7 @@ test('tray main deps builders return mapped handlers', () => {
     showWindowsMpvLauncherSetup: true,
     openYomitanSettings: () => calls.push('open-yomitan'),
     openRuntimeOptions: () => calls.push('open-runtime-options'),
+    openConfigSettings: () => calls.push('open-configuration'),
     openJellyfinSetup: () => calls.push('open-jellyfin'),
     showJellyfinDiscovery: true,
     jellyfinDiscoveryActive: false,