Allow first-run setup completion with external Yomitan profile

- Treat `yomitan.externalProfilePath` as satisfying dictionary setup in launcher and app first-run flow
- Reopen setup if an externally-completed setup later runs without external profile and no internal dictionaries
- Bump setup state to v3 with `yomitanSetupMode` migration and update setup UI/docs/tests

launcher/commands/playback-command.ts

@@ -21,6 +21,7 @@ import {
   getSetupStatePath,
   readSetupState,
 } from '../../src/shared/setup-state.js';
+import { hasLauncherExternalYomitanProfileConfig } from '../config.js';
 
 const SETUP_WAIT_TIMEOUT_MS = 10 * 60 * 1000;
 const SETUP_POLL_INTERVAL_MS = 500;
@@ -101,6 +102,7 @@ async function ensurePlaybackSetupReady(context: LauncherCommandContext): Promis
   const statePath = getSetupStatePath(configDir);
   const ready = await ensureLauncherSetupReady({
     readSetupState: () => readSetupState(statePath),
+    isExternalYomitanConfigured: () => hasLauncherExternalYomitanProfileConfig(),
     launchSetupApp: () => {
       const setupArgs = ['--background', '--setup'];
       if (args.logLevel) {

launcher/config-domain-parsers.test.ts

@@ -2,6 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { parseLauncherYoutubeSubgenConfig } from './config/youtube-subgen-config.js';
 import { parseLauncherJellyfinConfig } from './config/jellyfin-config.js';
+import { readExternalYomitanProfilePath } from './config.js';
 import {
   getPluginConfigCandidates,
   parsePluginRuntimeConfigContent,
@@ -116,3 +117,36 @@ test('getPluginConfigCandidates resolves Windows mpv script-opts path', () => {
 test('getDefaultSocketPath returns Windows named pipe default', () => {
   assert.equal(getDefaultSocketPath('win32'), '\\\\.\\pipe\\subminer-socket');
 });
+
+test('readExternalYomitanProfilePath detects configured external profile paths', () => {
+  assert.equal(
+    readExternalYomitanProfilePath({
+      yomitan: {
+        externalProfilePath: '  ~/.config/gsm_overlay  ',
+      },
+    }),
+    '~/.config/gsm_overlay',
+  );
+  assert.equal(
+    readExternalYomitanProfilePath({
+      yomitan: {
+        externalProfilePath: '   ',
+      },
+    }),
+    null,
+  );
+  assert.equal(
+    readExternalYomitanProfilePath({
+      yomitan: null,
+    }),
+    null,
+  );
+  assert.equal(
+    readExternalYomitanProfilePath({
+      yomitan: {
+        externalProfilePath: 123,
+      },
+    } as never),
+    null,
+  );
+});

launcher/config.ts

@@ -17,6 +17,19 @@ import { readPluginRuntimeConfig as readPluginRuntimeConfigValue } from './confi
 import { readLauncherMainConfigObject } from './config/shared-config-reader.js';
 import { parseLauncherYoutubeSubgenConfig } from './config/youtube-subgen-config.js';
 
+export function readExternalYomitanProfilePath(root: Record<string, unknown> | null): string | null {
+  const yomitan =
+    root?.yomitan && typeof root.yomitan === 'object' && !Array.isArray(root.yomitan)
+      ? (root.yomitan as Record<string, unknown>)
+      : null;
+  const externalProfilePath = yomitan?.externalProfilePath;
+  if (typeof externalProfilePath !== 'string') {
+    return null;
+  }
+  const trimmed = externalProfilePath.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
 export function loadLauncherYoutubeSubgenConfig(): LauncherYoutubeSubgenConfig {
   const root = readLauncherMainConfigObject();
   if (!root) return {};
@@ -29,6 +42,10 @@ export function loadLauncherJellyfinConfig(): LauncherJellyfinConfig {
   return parseLauncherJellyfinConfig(root);
 }
 
+export function hasLauncherExternalYomitanProfileConfig(): boolean {
+  return readExternalYomitanProfilePath(readLauncherMainConfigObject()) !== null;
+}
+
 export function readPluginRuntimeConfig(logLevel: LogLevel): PluginRuntimeConfig {
   return readPluginRuntimeConfigValue(logLevel);
 }

launcher/setup-gate.test.ts

@@ -7,10 +7,11 @@ test('waitForSetupCompletion resolves completed and cancelled states', async ()
   const sequence: Array<SetupState | null> = [
     null,
     {
-      version: 2,
+      version: 3,
       status: 'in_progress',
       completedAt: null,
       completionSource: null,
+      yomitanSetupMode: null,
       lastSeenYomitanDictionaryCount: 0,
       pluginInstallStatus: 'unknown',
       pluginInstallPathSummary: null,
@@ -18,10 +19,11 @@ test('waitForSetupCompletion resolves completed and cancelled states', async ()
       windowsMpvShortcutLastStatus: 'unknown',
     },
     {
-      version: 2,
+      version: 3,
       status: 'completed',
       completedAt: '2026-03-07T00:00:00.000Z',
       completionSource: 'user',
+      yomitanSetupMode: 'internal',
       lastSeenYomitanDictionaryCount: 1,
       pluginInstallStatus: 'skipped',
       pluginInstallPathSummary: null,
@@ -54,10 +56,11 @@ test('ensureLauncherSetupReady launches setup app and resumes only after complet
       if (reads === 1) return null;
       if (reads === 2) {
         return {
-          version: 2,
+          version: 3,
           status: 'in_progress',
           completedAt: null,
           completionSource: null,
+          yomitanSetupMode: null,
           lastSeenYomitanDictionaryCount: 0,
           pluginInstallStatus: 'unknown',
           pluginInstallPathSummary: null,
@@ -66,10 +69,11 @@ test('ensureLauncherSetupReady launches setup app and resumes only after complet
         };
       }
       return {
-        version: 2,
+        version: 3,
         status: 'completed',
         completedAt: '2026-03-07T00:00:00.000Z',
         completionSource: 'user',
+        yomitanSetupMode: 'internal',
         lastSeenYomitanDictionaryCount: 1,
         pluginInstallStatus: 'installed',
         pluginInstallPathSummary: '/tmp/mpv',
@@ -93,13 +97,33 @@ test('ensureLauncherSetupReady launches setup app and resumes only after complet
   assert.deepEqual(calls, ['launch']);
 });
 
+test('ensureLauncherSetupReady bypasses setup gate when external yomitan is configured', async () => {
+  const calls: string[] = [];
+
+  const ready = await ensureLauncherSetupReady({
+    readSetupState: () => null,
+    isExternalYomitanConfigured: () => true,
+    launchSetupApp: () => {
+      calls.push('launch');
+    },
+    sleep: async () => undefined,
+    now: () => 0,
+    timeoutMs: 5_000,
+    pollIntervalMs: 100,
+  });
+
+  assert.equal(ready, true);
+  assert.deepEqual(calls, []);
+});
+
 test('ensureLauncherSetupReady fails on timeout/cancelled state', async () => {
   const result = await ensureLauncherSetupReady({
     readSetupState: () => ({
-      version: 2,
+      version: 3,
       status: 'cancelled',
       completedAt: null,
       completionSource: null,
+      yomitanSetupMode: null,
       lastSeenYomitanDictionaryCount: 0,
       pluginInstallStatus: 'unknown',
       pluginInstallPathSummary: null,

launcher/setup-gate.ts

@@ -25,12 +25,16 @@ export async function waitForSetupCompletion(deps: {
 
 export async function ensureLauncherSetupReady(deps: {
   readSetupState: () => SetupState | null;
+  isExternalYomitanConfigured?: () => boolean;
   launchSetupApp: () => void;
   sleep: (ms: number) => Promise<void>;
   now: () => number;
   timeoutMs: number;
   pollIntervalMs: number;
 }): Promise<boolean> {
+  if (deps.isExternalYomitanConfigured?.()) {
+    return true;
+  }
   if (isSetupCompleted(deps.readSetupState())) {
     return true;
   }