Switch known-word cache to incremental sync and doctor refresh

- Load persisted known-word cache on startup; reconcile adds/deletes/edits on timed sync
- Add `knownWords.addMinedWordsImmediately` (default `true`) for immediate mined-word updates
- Route full rebuild to explicit `subminer doctor --refresh-known-words` and expand tests/docs

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

@@ -539,8 +539,21 @@ test('handleCliCommand runs refresh-known-words command', () => {
   assert.ok(calls.includes('refreshKnownWords'));
 });
 
+test('handleCliCommand stops app after headless initial refresh-known-words completes', async () => {
+  const { deps, calls } = createDeps({
+    hasMainWindow: () => false,
+  });
+
+  handleCliCommand(makeArgs({ refreshKnownWords: true }), 'initial', deps);
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.ok(calls.includes('refreshKnownWords'));
+  assert.ok(calls.includes('stopApp'));
+});
+
 test('handleCliCommand reports async refresh-known-words errors to OSD', async () => {
   const { deps, calls, osd } = createDeps({
+    hasMainWindow: () => false,
     refreshKnownWords: async () => {
       throw new Error('refresh boom');
     },
@@ -551,4 +564,5 @@ test('handleCliCommand reports async refresh-known-words errors to OSD', async (
 
   assert.ok(calls.some((value) => value.startsWith('error:refreshKnownWords failed:')));
   assert.ok(osd.some((value) => value.includes('Refresh known words failed: refresh boom')));
+  assert.ok(calls.includes('stopApp'));
 });

src/core/services/cli-command.ts

@@ -334,12 +334,18 @@ export function handleCliCommand(
       'Update failed',
     );
   } else if (args.refreshKnownWords) {
-    runAsyncWithOsd(
-      () => deps.refreshKnownWords(),
-      deps,
-      'refreshKnownWords',
-      'Refresh known words failed',
-    );
+    const shouldStopAfterRun = source === 'initial' && !deps.hasMainWindow();
+    deps
+      .refreshKnownWords()
+      .catch((err) => {
+        deps.error('refreshKnownWords failed:', err);
+        deps.showMpvOsd(`Refresh known words failed: ${(err as Error).message}`);
+      })
+      .finally(() => {
+        if (shouldStopAfterRun) {
+          deps.stopApp();
+        }
+      });
   } else if (args.toggleSecondarySub) {
     deps.cycleSecondarySubMode();
   } else if (args.triggerFieldGrouping) {

src/core/services/overlay-runtime-init.test.ts

@@ -109,6 +109,60 @@ test('initializeOverlayRuntime starts Anki integration when ankiConnect.enabled
   assert.equal(setIntegrationCalls, 1);
 });
 
+test('initializeOverlayRuntime can skip starting Anki integration transport', () => {
+  let createdIntegrations = 0;
+  let startedIntegrations = 0;
+  let setIntegrationCalls = 0;
+
+  initializeOverlayRuntime({
+    backendOverride: null,
+    createMainWindow: () => {},
+    registerGlobalShortcuts: () => {},
+    updateVisibleOverlayBounds: () => {},
+    isVisibleOverlayVisible: () => false,
+    updateVisibleOverlayVisibility: () => {},
+    getOverlayWindows: () => [],
+    syncOverlayShortcuts: () => {},
+    setWindowTracker: () => {},
+    getMpvSocketPath: () => '/tmp/mpv.sock',
+    createWindowTracker: () => null,
+    getResolvedConfig: () => ({
+      ankiConnect: { enabled: true } as never,
+    }),
+    getSubtitleTimingTracker: () => ({}),
+    getMpvClient: () => ({
+      send: () => {},
+    }),
+    getRuntimeOptionsManager: () => ({
+      getEffectiveAnkiConnectConfig: (config) => config as never,
+    }),
+    createAnkiIntegration: () => {
+      createdIntegrations += 1;
+      return {
+        start: () => {
+          startedIntegrations += 1;
+        },
+      };
+    },
+    setAnkiIntegration: () => {
+      setIntegrationCalls += 1;
+    },
+    showDesktopNotification: () => {},
+    createFieldGroupingCallback: () => async () => ({
+      keepNoteId: 7,
+      deleteNoteId: 8,
+      deleteDuplicate: false,
+      cancelled: false,
+    }),
+    getKnownWordCacheStatePath: () => '/tmp/known-words-cache.json',
+    shouldStartAnkiIntegration: () => false,
+  });
+
+  assert.equal(createdIntegrations, 1);
+  assert.equal(startedIntegrations, 0);
+  assert.equal(setIntegrationCalls, 1);
+});
+
 test('initializeOverlayRuntime merges shared ai config with Anki overrides', () => {
   initializeOverlayRuntime({
     backendOverride: null,

src/core/services/overlay-runtime-init.ts

@@ -75,6 +75,7 @@ export function initializeOverlayRuntime(options: {
     data: KikuFieldGroupingRequestData,
   ) => Promise<KikuFieldGroupingChoice>;
   getKnownWordCacheStatePath: () => string;
+  shouldStartAnkiIntegration?: () => boolean;
   createAnkiIntegration?: (args: CreateAnkiIntegrationArgs) => AnkiIntegrationLike;
 }): void {
   options.createMainWindow();
@@ -135,7 +136,9 @@ export function initializeOverlayRuntime(options: {
       createFieldGroupingCallback: options.createFieldGroupingCallback,
       knownWordCacheStatePath: options.getKnownWordCacheStatePath(),
     });
-    integration.start();
+    if (options.shouldStartAnkiIntegration?.() !== false) {
+      integration.start();
+    }
     options.setAnkiIntegration(integration);
   }
 

src/core/services/startup.test.ts

@@ -93,3 +93,104 @@ test('runAppReadyRuntime minimal startup skips Yomitan and first-run setup while
 
   assert.deepEqual(calls, ['bootstrap', 'reload-config', 'handle-initial-args']);
 });
+
+test('runAppReadyRuntime headless refresh bootstraps Anki runtime without UI startup', async () => {
+  const calls: string[] = [];
+
+  await runAppReadyRuntime({
+    ensureDefaultConfigBootstrap: () => {
+      calls.push('bootstrap');
+    },
+    loadSubtitlePosition: () => {
+      calls.push('load-subtitle-position');
+    },
+    resolveKeybindings: () => {
+      calls.push('resolve-keybindings');
+    },
+    createMpvClient: () => {
+      calls.push('create-mpv');
+    },
+    reloadConfig: () => {
+      calls.push('reload-config');
+    },
+    getResolvedConfig: () => ({}),
+    getConfigWarnings: () => [],
+    logConfigWarning: () => {
+      calls.push('config-warning');
+    },
+    setLogLevel: () => {
+      calls.push('set-log-level');
+    },
+    initRuntimeOptionsManager: () => {
+      calls.push('init-runtime-options');
+    },
+    setSecondarySubMode: () => {
+      calls.push('set-secondary-sub-mode');
+    },
+    defaultSecondarySubMode: 'hover',
+    defaultWebsocketPort: 0,
+    defaultAnnotationWebsocketPort: 0,
+    defaultTexthookerPort: 0,
+    hasMpvWebsocketPlugin: () => false,
+    startSubtitleWebsocket: () => {
+      calls.push('subtitle-ws');
+    },
+    startAnnotationWebsocket: () => {
+      calls.push('annotation-ws');
+    },
+    startTexthooker: () => {
+      calls.push('texthooker');
+    },
+    log: () => {
+      calls.push('log');
+    },
+    createMecabTokenizerAndCheck: async () => {
+      calls.push('mecab');
+    },
+    createSubtitleTimingTracker: () => {
+      calls.push('subtitle-timing');
+    },
+    createImmersionTracker: () => {
+      calls.push('immersion');
+    },
+    startJellyfinRemoteSession: async () => {
+      calls.push('jellyfin');
+    },
+    loadYomitanExtension: async () => {
+      calls.push('load-yomitan');
+    },
+    handleFirstRunSetup: async () => {
+      calls.push('first-run');
+    },
+    prewarmSubtitleDictionaries: async () => {
+      calls.push('prewarm');
+    },
+    startBackgroundWarmups: () => {
+      calls.push('warmups');
+    },
+    texthookerOnlyMode: false,
+    shouldAutoInitializeOverlayRuntimeFromConfig: () => false,
+    setVisibleOverlayVisible: () => {
+      calls.push('visible-overlay');
+    },
+    initializeOverlayRuntime: () => {
+      calls.push('init-overlay');
+    },
+    runHeadlessInitialCommand: async () => {
+      calls.push('run-headless-command');
+    },
+    handleInitialArgs: () => {
+      calls.push('handle-initial-args');
+    },
+    shouldRunHeadlessInitialCommand: () => true,
+    shouldUseMinimalStartup: () => false,
+    shouldSkipHeavyStartup: () => false,
+  });
+
+  assert.deepEqual(calls, [
+    'bootstrap',
+    'reload-config',
+    'init-runtime-options',
+    'run-headless-command',
+  ]);
+});

src/core/services/startup.ts

@@ -131,10 +131,12 @@ export interface AppReadyRuntimeDeps {
   shouldAutoInitializeOverlayRuntimeFromConfig: () => boolean;
   setVisibleOverlayVisible: (visible: boolean) => void;
   initializeOverlayRuntime: () => void;
+  runHeadlessInitialCommand?: () => Promise<void>;
   handleInitialArgs: () => void;
   logDebug?: (message: string) => void;
   onCriticalConfigErrors?: (errors: string[]) => void;
   now?: () => number;
+  shouldRunHeadlessInitialCommand?: () => boolean;
   shouldUseMinimalStartup?: () => boolean;
   shouldSkipHeavyStartup?: () => boolean;
 }
@@ -184,6 +186,20 @@ export async function runAppReadyRuntime(deps: AppReadyRuntimeDeps): Promise<voi
   const now = deps.now ?? (() => Date.now());
   const startupStartedAtMs = now();
   deps.ensureDefaultConfigBootstrap();
+  if (deps.shouldRunHeadlessInitialCommand?.()) {
+    deps.reloadConfig();
+    deps.initRuntimeOptionsManager();
+    if (deps.runHeadlessInitialCommand) {
+      await deps.runHeadlessInitialCommand();
+    } else {
+      deps.createMpvClient();
+      deps.createSubtitleTimingTracker();
+      deps.initializeOverlayRuntime();
+      deps.handleInitialArgs();
+    }
+    return;
+  }
+
   if (deps.shouldUseMinimalStartup?.()) {
     deps.reloadConfig();
     deps.handleInitialArgs();

src/core/services/stats-server.ts

@@ -68,7 +68,9 @@ function loadKnownWordsSet(cachePath: string | undefined): Set<string> | null {
       version?: number;
       words?: string[];
     };
-    if (raw.version === 1 && Array.isArray(raw.words)) return new Set(raw.words);
+    if ((raw.version === 1 || raw.version === 2) && Array.isArray(raw.words)) {
+      return new Set(raw.words);
+    }
   } catch {
     /* ignore */
   }