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/main/runtime/initial-args-handler.test.ts

@@ -8,6 +8,7 @@ test('initial args handler no-ops without initial args', () => {
     getInitialArgs: () => null,
     isBackgroundMode: () => false,
     shouldEnsureTrayOnStartup: () => false,
+    shouldRunHeadlessInitialCommand: () => false,
     ensureTray: () => {},
     isTexthookerOnlyMode: () => false,
     hasImmersionTracker: () => false,
@@ -28,6 +29,7 @@ test('initial args handler ensures tray in background mode', () => {
     getInitialArgs: () => ({ start: true }) as never,
     isBackgroundMode: () => true,
     shouldEnsureTrayOnStartup: () => false,
+    shouldRunHeadlessInitialCommand: () => false,
     ensureTray: () => {
       ensuredTray = true;
     },
@@ -49,6 +51,7 @@ test('initial args handler auto-connects mpv when needed', () => {
     getInitialArgs: () => ({ start: true }) as never,
     isBackgroundMode: () => false,
     shouldEnsureTrayOnStartup: () => false,
+    shouldRunHeadlessInitialCommand: () => false,
     ensureTray: () => {},
     isTexthookerOnlyMode: () => false,
     hasImmersionTracker: () => true,
@@ -75,6 +78,7 @@ test('initial args handler forwards args to cli handler', () => {
     getInitialArgs: () => ({ start: true }) as never,
     isBackgroundMode: () => false,
     shouldEnsureTrayOnStartup: () => false,
+    shouldRunHeadlessInitialCommand: () => false,
     ensureTray: () => {},
     isTexthookerOnlyMode: () => false,
     hasImmersionTracker: () => false,
@@ -95,6 +99,7 @@ test('initial args handler can ensure tray outside background mode when requeste
     getInitialArgs: () => ({ start: true }) as never,
     isBackgroundMode: () => false,
     shouldEnsureTrayOnStartup: () => true,
+    shouldRunHeadlessInitialCommand: () => false,
     ensureTray: () => {
       ensuredTray = true;
     },
@@ -108,3 +113,31 @@ test('initial args handler can ensure tray outside background mode when requeste
   handleInitialArgs();
   assert.equal(ensuredTray, true);
 });
+
+test('initial args handler skips tray and mpv auto-connect for headless refresh', () => {
+  let ensuredTray = false;
+  let connectCalls = 0;
+  const handleInitialArgs = createHandleInitialArgsHandler({
+    getInitialArgs: () => ({ refreshKnownWords: true }) as never,
+    isBackgroundMode: () => true,
+    shouldEnsureTrayOnStartup: () => true,
+    shouldRunHeadlessInitialCommand: () => true,
+    ensureTray: () => {
+      ensuredTray = true;
+    },
+    isTexthookerOnlyMode: () => false,
+    hasImmersionTracker: () => true,
+    getMpvClient: () => ({
+      connected: false,
+      connect: () => {
+        connectCalls += 1;
+      },
+    }),
+    logInfo: () => {},
+    handleCliCommand: () => {},
+  });
+
+  handleInitialArgs();
+  assert.equal(ensuredTray, false);
+  assert.equal(connectCalls, 0);
+});