opencode-smart-voice-notify 1.2.4 → 1.3.0

package/util/config.js

@@ -1,249 +1,330 @@
-import fs from 'fs';
-import path from 'path';
-import os from 'os';
-import { fileURLToPath } from 'url';
-
-/**
- * Debug logging to file (no console output).
- * Logs are written to ~/.config/opencode/logs/smart-voice-notify-debug.log
- * @param {string} message - Message to log
- * @param {string} configDir - Config directory path
- */
-const debugLogToFile = (message, configDir) => {
-  try {
-    const logsDir = path.join(configDir, 'logs');
-    if (!fs.existsSync(logsDir)) {
-      fs.mkdirSync(logsDir, { recursive: true });
-    }
-    const logFile = path.join(logsDir, 'smart-voice-notify-debug.log');
-    const timestamp = new Date().toISOString();
-    fs.appendFileSync(logFile, `[${timestamp}] [config] ${message}\n`);
-  } catch (e) {
-    // Silently fail - logging should never break the plugin
-  }
-};
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
 
 /**
- * Basic JSONC parser that strips single-line and multi-line comments.
+ * Debug logging to file (no console output).
+ * Logs are written to ~/.config/opencode/logs/smart-voice-notify-debug.log
+ * @param {string} message - Message to log
+ * @param {string} configDir - Config directory path
+ */
+const debugLogToFile = (message, configDir) => {
+  try {
+    const logsDir = path.join(configDir, 'logs');
+    if (!fs.existsSync(logsDir)) {
+      fs.mkdirSync(logsDir, { recursive: true });
+    }
+    const logFile = path.join(logsDir, 'smart-voice-notify-debug.log');
+    const timestamp = new Date().toISOString();
+    fs.appendFileSync(logFile, `[${timestamp}] [config] ${message}\n`);
+  } catch (e) {
+    // Silently fail - logging should never break the plugin
+  }
+};
+
+/**
+ * Basic JSONC parser that strips single-line and multi-line comments,
+ * and handles trailing commas (which Prettier often adds).
  * @param {string} jsonc 
  * @returns {any}
  */
-const parseJSONC = (jsonc) => {
-  const stripped = jsonc.replace(/\\"|"(?:\\"|[^"])*"|(\/\/.*|\/\*[\s\S]*?\*\/)/g, (m, g) => g ? "" : m);
+export const parseJSONC = (jsonc) => {
+  // Step 1: Strip comments while preserving strings
+  // This regex matches strings (handling escaped quotes) or comments
+  // If it's a comment, we replace it with empty string
+  let stripped = jsonc.replace(/\\"|"(?:\\"|[^"])*"|(\/\/.*|\/\*[\s\S]*?\*\/)/g, (m, g) => g ? "" : m);
+  
+  // Step 2: Strip trailing commas (e.g. [1, 2,] or {"a":1,})
+  // This helps when formatters like Prettier are used
+  stripped = stripped.replace(/,(\s*[\]}])/g, '$1');
+  
+  // Step 3: Handle literal control characters that might be present
+  // JSON.parse fails on literal control characters (U+0000 to U+001F).
+  // Some are allowed as whitespace (space, tab, newline, cr), but literal 
+  // tabs or newlines INSIDE strings are strictly forbidden.
+  // We'll strip most of them, but preserve allowed whitespace outside strings.
+  // A safer approach for user-edited files is to remove characters that 
+  // definitely shouldn't be there.
+  stripped = stripped.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '');
+
   return JSON.parse(stripped);
 };
 
-/**
- * Helper to format JSON values for the template.
- * @param {any} val 
- * @param {number} indent 
- * @returns {string}
- */
-const formatJSON = (val, indent = 0) => {
-  const json = JSON.stringify(val, null, 4);
-  return indent > 0 ? json.replace(/\n/g, '\n' + ' '.repeat(indent)) : json;
-};
-
-/**
- * Deep merge two objects. User values take precedence over defaults.
- * - For objects: recursively merge, adding new keys from defaults
- * - For arrays: user's array completely replaces default (no merge)
- * - For primitives: user's value takes precedence if it exists
- * 
- * @param {object} defaults - The default configuration object
- * @param {object} user - The user's existing configuration object
- * @returns {object} Merged configuration with user values preserved
- */
-const deepMerge = (defaults, user) => {
-  // If user value doesn't exist, use default
-  if (user === undefined || user === null) {
-    return defaults;
-  }
-  
-  // If either is not an object (or is array), user value wins
-  if (typeof defaults !== 'object' || defaults === null || Array.isArray(defaults)) {
-    return user;
-  }
-  if (typeof user !== 'object' || user === null || Array.isArray(user)) {
-    return user;
-  }
-  
-  // Both are objects - merge them
-  const result = { ...user };
-  
-  for (const key of Object.keys(defaults)) {
-    if (!(key in user)) {
-      // Key doesn't exist in user config - add it from defaults
-      result[key] = defaults[key];
-    } else if (typeof defaults[key] === 'object' && defaults[key] !== null && !Array.isArray(defaults[key])) {
-      // Both have this key and it's an object - recurse
-      result[key] = deepMerge(defaults[key], user[key]);
-    }
-    // else: user has this key and it's not an object to merge - keep user's value
-  }
-  
-  return result;
-};
-
-/**
- * Get the default configuration object.
- * This is the source of truth for all default values.
- * @returns {object} Default configuration object
- */
-const getDefaultConfigObject = () => ({
-  _configVersion: null, // Will be set by caller
-  enabled: true,
-  notificationMode: 'sound-first',
-  enableTTSReminder: true,
-  ttsReminderDelaySeconds: 30,
-  idleReminderDelaySeconds: 30,
-  permissionReminderDelaySeconds: 20,
-  enableFollowUpReminders: true,
-  maxFollowUpReminders: 3,
-  reminderBackoffMultiplier: 1.5,
-  ttsEngine: 'elevenlabs',
-  enableTTS: true,
-  // elevenLabsApiKey is intentionally omitted - users must set it
-  elevenLabsVoiceId: 'cgSgspJ2msm6clMCkdW9',
-  elevenLabsModel: 'eleven_turbo_v2_5',
-  elevenLabsStability: 0.5,
-  elevenLabsSimilarity: 0.75,
-  elevenLabsStyle: 0.5,
-  edgeVoice: 'en-US-JennyNeural',
-  edgePitch: '+0Hz',
-  edgeRate: '+10%',
-  sapiVoice: 'Microsoft Zira Desktop',
-  sapiRate: -1,
-  sapiPitch: 'medium',
-  sapiVolume: 'loud',
-  idleTTSMessages: [
-    "All done! Your task has been completed successfully.",
-    "Hey there! I finished working on your request.",
-    "Task complete! Ready for your review whenever you are.",
-    "Good news! Everything is done and ready for you.",
-    "Finished! Let me know if you need anything else."
-  ],
-  permissionTTSMessages: [
-    "Attention please! I need your permission to continue.",
-    "Hey! Quick approval needed to proceed with the task.",
-    "Heads up! There is a permission request waiting for you.",
-    "Excuse me! I need your authorization before I can continue.",
-    "Permission required! Please review and approve when ready."
-  ],
-  permissionTTSMessagesMultiple: [
-    "Attention please! There are {count} permission requests waiting for your approval.",
-    "Hey! {count} permissions need your approval to continue.",
-    "Heads up! You have {count} pending permission requests.",
-    "Excuse me! I need your authorization for {count} different actions.",
-    "{count} permissions required! Please review and approve when ready."
-  ],
-  idleReminderTTSMessages: [
-    "Hey, are you still there? Your task has been waiting for review.",
-    "Just a gentle reminder - I finished your request a while ago!",
-    "Hello? I completed your task. Please take a look when you can.",
-    "Still waiting for you! The work is done and ready for review.",
-    "Knock knock! Your completed task is patiently waiting for you."
-  ],
-  permissionReminderTTSMessages: [
-    "Hey! I still need your permission to continue. Please respond!",
-    "Reminder: There is a pending permission request. I cannot proceed without you.",
-    "Hello? I am waiting for your approval. This is getting urgent!",
-    "Please check your screen! I really need your permission to move forward.",
-    "Still waiting for authorization! The task is on hold until you respond."
-  ],
-  permissionReminderTTSMessagesMultiple: [
-    "Hey! I still need your approval for {count} permissions. Please respond!",
-    "Reminder: There are {count} pending permission requests. I cannot proceed without you.",
-    "Hello? I am waiting for your approval on {count} items. This is getting urgent!",
-    "Please check your screen! {count} permissions are waiting for your response.",
-    "Still waiting for authorization on {count} requests! The task is on hold."
-  ],
-  permissionBatchWindowMs: 800,
-  questionTTSMessages: [
-    "Hey! I have a question for you. Please check your screen.",
-    "Attention! I need your input to continue.",
-    "Quick question! Please take a look when you have a moment.",
-    "I need some clarification. Could you please respond?",
-    "Question time! Your input is needed to proceed."
-  ],
-  questionTTSMessagesMultiple: [
-    "Hey! I have {count} questions for you. Please check your screen.",
-    "Attention! I need your input on {count} items to continue.",
-    "{count} questions need your attention. Please take a look!",
-    "I need some clarifications. There are {count} questions waiting for you.",
-    "Question time! {count} questions need your response to proceed."
-  ],
-  questionReminderTTSMessages: [
-    "Hey! I am still waiting for your answer. Please check the questions!",
-    "Reminder: There is a question waiting for your response.",
-    "Hello? I need your input to continue. Please respond when you can.",
-    "Still waiting for your answer! The task is on hold.",
-    "Your input is needed! Please check the pending question."
-  ],
-  questionReminderTTSMessagesMultiple: [
-    "Hey! I am still waiting for answers to {count} questions. Please respond!",
-    "Reminder: There are {count} questions waiting for your response.",
-    "Hello? I need your input on {count} items. Please respond when you can.",
-    "Still waiting for your answers on {count} questions! The task is on hold.",
-    "Your input is needed! {count} questions are pending your response."
-  ],
-  questionReminderDelaySeconds: 25,
-  questionBatchWindowMs: 800,
-  enableAIMessages: false,
-  aiEndpoint: 'http://localhost:11434/v1',
-  aiModel: 'llama3',
-  aiApiKey: '',
-  aiTimeout: 15000,
-  aiFallbackToStatic: true,
-  aiPrompts: {
-    idle: "Generate a single brief, friendly notification sentence (max 15 words) saying a coding task is complete. Be encouraging and warm. Output only the message, no quotes.",
-    permission: "Generate a single brief, urgent but friendly notification sentence (max 15 words) asking the user to approve a permission request. Output only the message, no quotes.",
-    question: "Generate a single brief, polite notification sentence (max 15 words) saying the assistant has a question and needs user input. Output only the message, no quotes.",
-    idleReminder: "Generate a single brief, gentle reminder sentence (max 15 words) that a completed task is waiting for review. Be slightly more insistent. Output only the message, no quotes.",
-    permissionReminder: "Generate a single brief, urgent reminder sentence (max 15 words) that permission approval is still needed. Convey importance. Output only the message, no quotes.",
-    questionReminder: "Generate a single brief, polite but persistent reminder sentence (max 15 words) that a question is still waiting for an answer. Output only the message, no quotes."
-  },
-  idleSound: 'assets/Soft-high-tech-notification-sound-effect.mp3',
-  permissionSound: 'assets/Machine-alert-beep-sound-effect.mp3',
-  questionSound: 'assets/Machine-alert-beep-sound-effect.mp3',
-  wakeMonitor: true,
-  forceVolume: true,
-  volumeThreshold: 50,
-  enableToast: true,
-  enableSound: true,
-  idleThresholdSeconds: 60,
-  debugLog: false
-});
-
-/**
- * Find new fields that exist in defaults but not in user config.
- * Used for logging what was added during migration.
- * @param {object} defaults 
- * @param {object} user 
- * @param {string} prefix 
- * @returns {string[]} Array of field paths that were added
- */
-const findNewFields = (defaults, user, prefix = '') => {
-  const newFields = [];
-  
-  if (typeof defaults !== 'object' || defaults === null || Array.isArray(defaults)) {
-    return newFields;
-  }
-  
-  for (const key of Object.keys(defaults)) {
-    const fieldPath = prefix ? `${prefix}.${key}` : key;
-    
-    if (!(key in user)) {
-      newFields.push(fieldPath);
-    } else if (typeof defaults[key] === 'object' && defaults[key] !== null && !Array.isArray(defaults[key])) {
-      if (typeof user[key] === 'object' && user[key] !== null && !Array.isArray(user[key])) {
-        newFields.push(...findNewFields(defaults[key], user[key], fieldPath));
-      }
-    }
-  }
-  
-  return newFields;
-};
+/**
+ * Helper to format JSON values for the template.
+ * @param {any} val 
+ * @param {number} indent 
+ * @returns {string}
+ */
+export const formatJSON = (val, indent = 0) => {
+  const json = JSON.stringify(val, null, 4);
+  return indent > 0 ? json.replace(/\n/g, '\n' + ' '.repeat(indent)) : json;
+};
+
+/**
+ * Deep merge two objects. User values take precedence over defaults.
+ * - For objects: recursively merge, adding new keys from defaults
+ * - For arrays: user's array completely replaces default (no merge)
+ * - For primitives: user's value takes precedence if it exists
+ * 
+ * @param {object} defaults - The default configuration object
+ * @param {object} user - The user's existing configuration object
+ * @returns {object} Merged configuration with user values preserved
+ */
+export const deepMerge = (defaults, user) => {
+  // If user value doesn't exist, use default
+  if (user === undefined || user === null) {
+    return defaults;
+  }
+  
+  // If either is not an object (or is array), user value wins
+  if (typeof defaults !== 'object' || defaults === null || Array.isArray(defaults)) {
+    return user;
+  }
+  if (typeof user !== 'object' || user === null || Array.isArray(user)) {
+    return user;
+  }
+  
+  // Both are objects - merge them
+  const result = { ...user };
+  
+  for (const key of Object.keys(defaults)) {
+    if (!(key in user)) {
+      // Key doesn't exist in user config - add it from defaults
+      result[key] = defaults[key];
+    } else if (typeof defaults[key] === 'object' && defaults[key] !== null && !Array.isArray(defaults[key])) {
+      // Both have this key and it's an object - recurse
+      result[key] = deepMerge(defaults[key], user[key]);
+    }
+    // else: user has this key and it's not an object to merge - keep user's value
+  }
+  
+  return result;
+};
+
+/**
+ * Get the default configuration object.
+ * This is the source of truth for all default values.
+ * @returns {object} Default configuration object
+ */
+export const getDefaultConfigObject = () => ({
+
+  _configVersion: null, // Will be set by caller
+  enabled: true,
+  notificationMode: 'sound-first',
+  enableTTSReminder: true,
+  enableIdleNotification: true,
+  enablePermissionNotification: true,
+  enableQuestionNotification: true,
+  enableErrorNotification: false,
+  enableIdleReminder: true,
+  enablePermissionReminder: true,
+  enableQuestionReminder: true,
+  enableErrorReminder: false,
+  ttsReminderDelaySeconds: 30,
+  idleReminderDelaySeconds: 30,
+  permissionReminderDelaySeconds: 20,
+  enableFollowUpReminders: true,
+  maxFollowUpReminders: 3,
+  reminderBackoffMultiplier: 1.5,
+  ttsEngine: 'elevenlabs',
+  enableTTS: true,
+  // elevenLabsApiKey is intentionally omitted - users must set it
+  elevenLabsVoiceId: 'cgSgspJ2msm6clMCkdW9',
+  elevenLabsModel: 'eleven_turbo_v2_5',
+  elevenLabsStability: 0.5,
+  elevenLabsSimilarity: 0.75,
+  elevenLabsStyle: 0.5,
+  edgeVoice: 'en-US-JennyNeural',
+  edgePitch: '+0Hz',
+  edgeRate: '+10%',
+  sapiVoice: 'Microsoft Zira Desktop',
+  sapiRate: -1,
+  sapiPitch: 'medium',
+  sapiVolume: 'loud',
+  openaiTtsEndpoint: '',
+  openaiTtsApiKey: '',
+  openaiTtsModel: 'tts-1',
+  openaiTtsVoice: 'alloy',
+  openaiTtsFormat: 'mp3',
+  openaiTtsSpeed: 1.0,
+  idleTTSMessages: [
+    "All done! Your task has been completed successfully.",
+    "Hey there! I finished working on your request.",
+    "Task complete! Ready for your review whenever you are.",
+    "Good news! Everything is done and ready for you.",
+    "Finished! Let me know if you need anything else."
+  ],
+  permissionTTSMessages: [
+    "Attention please! I need your permission to continue.",
+    "Hey! Quick approval needed to proceed with the task.",
+    "Heads up! There is a permission request waiting for you.",
+    "Excuse me! I need your authorization before I can continue.",
+    "Permission required! Please review and approve when ready."
+  ],
+  permissionTTSMessagesMultiple: [
+    "Attention please! There are {count} permission requests waiting for your approval.",
+    "Hey! {count} permissions need your approval to continue.",
+    "Heads up! You have {count} pending permission requests.",
+    "Excuse me! I need your authorization for {count} different actions.",
+    "{count} permissions required! Please review and approve when ready."
+  ],
+  idleReminderTTSMessages: [
+    "Hey, are you still there? Your task has been waiting for review.",
+    "Just a gentle reminder - I finished your request a while ago!",
+    "Hello? I completed your task. Please take a look when you can.",
+    "Still waiting for you! The work is done and ready for review.",
+    "Knock knock! Your completed task is patiently waiting for you."
+  ],
+  permissionReminderTTSMessages: [
+    "Hey! I still need your permission to continue. Please respond!",
+    "Reminder: There is a pending permission request. I cannot proceed without you.",
+    "Hello? I am waiting for your approval. This is getting urgent!",
+    "Please check your screen! I really need your permission to move forward.",
+    "Still waiting for authorization! The task is on hold until you respond."
+  ],
+  permissionReminderTTSMessagesMultiple: [
+    "Hey! I still need your approval for {count} permissions. Please respond!",
+    "Reminder: There are {count} pending permission requests. I cannot proceed without you.",
+    "Hello? I am waiting for your approval on {count} items. This is getting urgent!",
+    "Please check your screen! {count} permissions are waiting for your response.",
+    "Still waiting for authorization on {count} requests! The task is on hold."
+  ],
+  permissionBatchWindowMs: 800,
+  questionTTSMessages: [
+    "Hey! I have a question for you. Please check your screen.",
+    "Attention! I need your input to continue.",
+    "Quick question! Please take a look when you have a moment.",
+    "I need some clarification. Could you please respond?",
+    "Question time! Your input is needed to proceed."
+  ],
+  questionTTSMessagesMultiple: [
+    "Hey! I have {count} questions for you. Please check your screen.",
+    "Attention! I need your input on {count} items to continue.",
+    "{count} questions need your attention. Please take a look!",
+    "I need some clarifications. There are {count} questions waiting for you.",
+    "Question time! {count} questions need your response to proceed."
+  ],
+  questionReminderTTSMessages: [
+    "Hey! I am still waiting for your answer. Please check the questions!",
+    "Reminder: There is a question waiting for your response.",
+    "Hello? I need your input to continue. Please respond when you can.",
+    "Still waiting for your answer! The task is on hold.",
+    "Your input is needed! Please check the pending question."
+  ],
+  questionReminderTTSMessagesMultiple: [
+    "Hey! I am still waiting for answers to {count} questions. Please respond!",
+    "Reminder: There are {count} questions waiting for your response.",
+    "Hello? I need your input on {count} items. Please respond when you can.",
+    "Still waiting for your answers on {count} questions! The task is on hold.",
+    "Your input is needed! {count} questions are pending your response."
+  ],
+  questionReminderDelaySeconds: 25,
+  questionBatchWindowMs: 800,
+  errorTTSMessages: [
+    "Oops! Something went wrong. Please check for errors.",
+    "Alert! The agent encountered an error and needs your attention.",
+    "Error detected! Please review the issue when you can.",
+    "Houston, we have a problem! An error occurred during the task.",
+    "Heads up! There was an error that requires your attention."
+  ],
+  errorTTSMessagesMultiple: [
+    "Oops! There are {count} errors that need your attention.",
+    "Alert! The agent encountered {count} errors. Please review.",
+    "{count} errors detected! Please check when you can.",
+    "Houston, we have {count} problems! Multiple errors occurred.",
+    "Heads up! {count} errors require your attention."
+  ],
+  errorReminderTTSMessages: [
+    "Hey! There's still an error waiting for your attention.",
+    "Reminder: An error occurred and hasn't been addressed yet.",
+    "The agent is stuck! Please check the error when you can.",
+    "Still waiting! That error needs your attention.",
+    "Don't forget! There's an unresolved error in your session."
+  ],
+  errorReminderTTSMessagesMultiple: [
+    "Hey! There are still {count} errors waiting for your attention.",
+    "Reminder: {count} errors occurred and haven't been addressed yet.",
+    "The agent is stuck! Please check the {count} errors when you can.",
+    "Still waiting! {count} errors need your attention.",
+    "Don't forget! There are {count} unresolved errors in your session."
+  ],
+  errorReminderDelaySeconds: 20,
+  enableAIMessages: false,
+  aiEndpoint: 'http://localhost:11434/v1',
+  aiModel: 'llama3',
+  aiApiKey: '',
+  aiTimeout: 15000,
+  aiFallbackToStatic: true,
+  enableContextAwareAI: false,
+  aiPrompts: {
+    idle: "Generate a single brief, friendly notification sentence (max 15 words) saying a coding task is complete. Be encouraging and warm. Output only the message, no quotes.",
+    permission: "Generate a single brief, urgent but friendly notification sentence (max 15 words) asking the user to approve a permission request. Output only the message, no quotes.",
+    question: "Generate a single brief, polite notification sentence (max 15 words) saying the assistant has a question and needs user input. Output only the message, no quotes.",
+    error: "Generate a single brief, concerned but calm notification sentence (max 15 words) saying an error occurred and needs attention. Output only the message, no quotes.",
+    idleReminder: "Generate a single brief, gentle reminder sentence (max 15 words) that a completed task is waiting for review. Be slightly more insistent. Output only the message, no quotes.",
+    permissionReminder: "Generate a single brief, urgent reminder sentence (max 15 words) that permission approval is still needed. Convey importance. Output only the message, no quotes.",
+    questionReminder: "Generate a single brief, polite but persistent reminder sentence (max 15 words) that a question is still waiting for an answer. Output only the message, no quotes.",
+    errorReminder: "Generate a single brief, urgent reminder sentence (max 15 words) that an error still needs attention. Convey urgency. Output only the message, no quotes."
+  },
+  idleSound: 'assets/Soft-high-tech-notification-sound-effect.mp3',
+  permissionSound: 'assets/Machine-alert-beep-sound-effect.mp3',
+  questionSound: 'assets/Machine-alert-beep-sound-effect.mp3',
+  errorSound: 'assets/Machine-alert-beep-sound-effect.mp3',
+  wakeMonitor: true,
+  forceVolume: false,
+  volumeThreshold: 50,
+  enableToast: true,
+  enableSound: true,
+  enableDesktopNotification: true,
+  desktopNotificationTimeout: 5,
+  showProjectInNotification: true,
+  suppressWhenFocused: true,
+  alwaysNotify: false,
+  enableWebhook: false,
+  webhookUrl: "",
+  webhookUsername: "OpenCode Notify",
+  webhookEvents: ["idle", "permission", "error", "question"],
+  webhookMentionOnPermission: false,
+  soundThemeDir: "",
+  randomizeSoundFromTheme: true,
+  perProjectSounds: false,
+  projectSoundSeed: 0,
+  idleThresholdSeconds: 60,
+  debugLog: false
+});
+
+/**
+ * Find new fields that exist in defaults but not in user config.
+ * Used for logging what was added during migration.
+ * @param {object} defaults 
+ * @param {object} user 
+ * @param {string} prefix 
+ * @returns {string[]} Array of field paths that were added
+ */
+export const findNewFields = (defaults, user, prefix = '') => {
+
+  const newFields = [];
+  
+  if (typeof defaults !== 'object' || defaults === null || Array.isArray(defaults)) {
+    return newFields;
+  }
+  
+  for (const key of Object.keys(defaults)) {
+    const fieldPath = prefix ? `${prefix}.${key}` : key;
+    
+    if (!(key in user)) {
+      newFields.push(fieldPath);
+    } else if (typeof defaults[key] === 'object' && defaults[key] !== null && !Array.isArray(defaults[key])) {
+      if (typeof user[key] === 'object' && user[key] !== null && !Array.isArray(user[key])) {
+        newFields.push(...findNewFields(defaults[key], user[key], fieldPath));
+      }
+    }
+  }
+  
+  return newFields;
+};
 
 /**
  * Get the directory where this plugin is installed.
@@ -287,6 +368,25 @@ const generateDefaultConfig = (overrides = {}, version = '1.0.0') => {
     // Set to false to disable all notifications without uninstalling.
     "enabled": ${overrides.enabled !== undefined ? overrides.enabled : true},
 
+    // ============================================================
+    // GRANULAR NOTIFICATION CONTROL
+    // ============================================================
+    // Enable or disable notifications for specific event types.
+    // If disabled, no sound, TTS, desktop, or webhook notifications
+    // will be sent for that specific category.
+    "enableIdleNotification": ${overrides.enableIdleNotification !== undefined ? overrides.enableIdleNotification : true},       // Agent finished work
+    "enablePermissionNotification": ${overrides.enablePermissionNotification !== undefined ? overrides.enablePermissionNotification : true}, // Agent needs permission
+    "enableQuestionNotification": ${overrides.enableQuestionNotification !== undefined ? overrides.enableQuestionNotification : true},     // Agent asks a question
+    "enableErrorNotification": ${overrides.enableErrorNotification !== undefined ? overrides.enableErrorNotification : false},       // Agent encountered an error
+
+    // Enable or disable reminders for specific event types.
+    // If disabled, the initial notification will still fire, but no
+    // follow-up TTS reminders will be scheduled.
+    "enableIdleReminder": ${overrides.enableIdleReminder !== undefined ? overrides.enableIdleReminder : true},
+    "enablePermissionReminder": ${overrides.enablePermissionReminder !== undefined ? overrides.enablePermissionReminder : true},
+    "enableQuestionReminder": ${overrides.enableQuestionReminder !== undefined ? overrides.enableQuestionReminder : true},
+    "enableErrorReminder": ${overrides.enableErrorReminder !== undefined ? overrides.enableErrorReminder : false},
+
     // ============================================================
     // NOTIFICATION MODE SETTINGS (Smart Notification System)
     // ============================================================
@@ -318,6 +418,7 @@ const generateDefaultConfig = (overrides = {}, version = '1.0.0') => {
     // ============================================================
     // TTS ENGINE SELECTION
     // ============================================================
+    // 'openai'     - OpenAI-compatible TTS (Self-hosted/Cloud, e.g. Kokoro, LocalAI)
     // 'elevenlabs' - Best quality, anime-like voices (requires API key, free tier: 10k chars/month)
     // 'edge'       - Good quality neural voices (free, requires: pip install edge-tts)
     // 'sapi'       - Windows built-in voices (free, offline, robotic)
@@ -395,6 +496,37 @@ const generateDefaultConfig = (overrides = {}, version = '1.0.0') => {
     // Volume: 'silent', 'x-soft', 'soft', 'medium', 'loud', 'x-loud'
     "sapiVolume": "${overrides.sapiVolume || 'loud'}",
     
+    // ============================================================
+    // OPENAI-COMPATIBLE TTS SETTINGS (Kokoro, LocalAI, OpenAI, etc.)
+    // ============================================================
+    // Any OpenAI-compatible /v1/audio/speech endpoint.
+    // Examples: Kokoro, OpenAI, LocalAI, Coqui, AllTalk, etc.
+    //
+    // To use OpenAI-compatible TTS:
+    // 1. Set ttsEngine above to "openai"
+    // 2. Set openaiTtsEndpoint to your server URL (without /v1/audio/speech)
+    // 3. Configure voice and model for your server
+    
+    // Base URL for your TTS server (e.g., "http://192.168.86.43:8880")
+    "openaiTtsEndpoint": "${overrides.openaiTtsEndpoint || ''}",
+    
+    // API key (leave empty if your server doesn't require auth)
+    "openaiTtsApiKey": "${overrides.openaiTtsApiKey || ''}",
+    
+    // Model name (server-dependent, e.g., "tts-1", "kokoro", "xtts")
+    "openaiTtsModel": "${overrides.openaiTtsModel || 'tts-1'}",
+    
+    // Voice name (server-dependent)
+    // Kokoro voices: "af_heart", "af_bella", "am_adam", etc.
+    // OpenAI voices: "alloy", "echo", "fable", "onyx", "nova", "shimmer"
+    "openaiTtsVoice": "${overrides.openaiTtsVoice || 'alloy'}",
+    
+    // Audio format: "mp3", "opus", "aac", "flac", "wav", "pcm"
+    "openaiTtsFormat": "${overrides.openaiTtsFormat || 'mp3'}",
+    
+    // Speech speed: 0.25 to 4.0 (1.0 = normal)
+    "openaiTtsSpeed": ${overrides.openaiTtsSpeed !== undefined ? overrides.openaiTtsSpeed : 1.0},
+    
     // ============================================================
     // INITIAL TTS MESSAGES (Used immediately or after sound)
     // These are randomly selected each time for variety
@@ -518,6 +650,51 @@ const generateDefaultConfig = (overrides = {}, version = '1.0.0') => {
     // Question batch window (ms) - how long to wait for more questions before notifying
     "questionBatchWindowMs": ${overrides.questionBatchWindowMs !== undefined ? overrides.questionBatchWindowMs : 800},
     
+    // ============================================================
+    // ERROR NOTIFICATION SETTINGS (Session Errors)
+    // ============================================================
+    // Notify users when the agent encounters an error during execution.
+    // Error notifications use more urgent messaging to get user attention.
+    
+    // Messages when agent encounters an error
+    "errorTTSMessages": ${formatJSON(overrides.errorTTSMessages || [
+        "Oops! Something went wrong. Please check for errors.",
+        "Alert! The agent encountered an error and needs your attention.",
+        "Error detected! Please review the issue when you can.",
+        "Houston, we have a problem! An error occurred during the task.",
+        "Heads up! There was an error that requires your attention."
+    ], 4)},
+    
+    // Messages for MULTIPLE errors (use {count} placeholder)
+    "errorTTSMessagesMultiple": ${formatJSON(overrides.errorTTSMessagesMultiple || [
+        "Oops! There are {count} errors that need your attention.",
+        "Alert! The agent encountered {count} errors. Please review.",
+        "{count} errors detected! Please check when you can.",
+        "Houston, we have {count} problems! Multiple errors occurred.",
+        "Heads up! {count} errors require your attention."
+    ], 4)},
+    
+    // Reminder messages for errors (more urgent - used after delay)
+    "errorReminderTTSMessages": ${formatJSON(overrides.errorReminderTTSMessages || [
+        "Hey! There's still an error waiting for your attention.",
+        "Reminder: An error occurred and hasn't been addressed yet.",
+        "The agent is stuck! Please check the error when you can.",
+        "Still waiting! That error needs your attention.",
+        "Don't forget! There's an unresolved error in your session."
+    ], 4)},
+    
+    // Reminder messages for MULTIPLE errors (use {count} placeholder)
+    "errorReminderTTSMessagesMultiple": ${formatJSON(overrides.errorReminderTTSMessagesMultiple || [
+        "Hey! There are still {count} errors waiting for your attention.",
+        "Reminder: {count} errors occurred and haven't been addressed yet.",
+        "The agent is stuck! Please check the {count} errors when you can.",
+        "Still waiting! {count} errors need your attention.",
+        "Don't forget! There are {count} unresolved errors in your session."
+    ], 4)},
+    
+    // Delay (in seconds) before error reminder fires (shorter than idle for urgency)
+    "errorReminderDelaySeconds": ${overrides.errorReminderDelaySeconds !== undefined ? overrides.errorReminderDelaySeconds : 20},
+    
     // ============================================================
     // AI MESSAGE GENERATION (OpenAI-Compatible Endpoints)
     // ============================================================
@@ -554,6 +731,14 @@ const generateDefaultConfig = (overrides = {}, version = '1.0.0') => {
     // Fallback to static preset messages if AI generation fails
     "aiFallbackToStatic": ${overrides.aiFallbackToStatic !== undefined ? overrides.aiFallbackToStatic : true},
     
+    // Enable context-aware AI messages (includes project name, task title, and change summary)
+    // When enabled, AI-generated notifications will include relevant context like:
+    // - Project name (e.g., "Your work on MyProject is complete!")
+    // - Task/session title if available
+    // - Change summary (files modified, lines added/deleted)
+    // Disabled by default - enable this for more personalized notifications
+    "enableContextAwareAI": ${overrides.enableContextAwareAI !== undefined ? overrides.enableContextAwareAI : false},
+    
     // Custom prompts for each notification type
     // The AI will generate a short message based on these prompts
     // Keep prompts concise - they're sent with each notification
@@ -561,9 +746,11 @@ const generateDefaultConfig = (overrides = {}, version = '1.0.0') => {
         "idle": "Generate a single brief, friendly notification sentence (max 15 words) saying a coding task is complete. Be encouraging and warm. Output only the message, no quotes.",
         "permission": "Generate a single brief, urgent but friendly notification sentence (max 15 words) asking the user to approve a permission request. Output only the message, no quotes.",
         "question": "Generate a single brief, polite notification sentence (max 15 words) saying the assistant has a question and needs user input. Output only the message, no quotes.",
+        "error": "Generate a single brief, concerned but calm notification sentence (max 15 words) saying an error occurred and needs attention. Output only the message, no quotes.",
         "idleReminder": "Generate a single brief, gentle reminder sentence (max 15 words) that a completed task is waiting for review. Be slightly more insistent. Output only the message, no quotes.",
         "permissionReminder": "Generate a single brief, urgent reminder sentence (max 15 words) that permission approval is still needed. Convey importance. Output only the message, no quotes.",
-        "questionReminder": "Generate a single brief, polite but persistent reminder sentence (max 15 words) that a question is still waiting for an answer. Output only the message, no quotes."
+        "questionReminder": "Generate a single brief, polite but persistent reminder sentence (max 15 words) that a question is still waiting for an answer. Output only the message, no quotes.",
+        "errorReminder": "Generate a single brief, urgent reminder sentence (max 15 words) that an error still needs attention. Convey urgency. Output only the message, no quotes."
     }, 4)},
     
     // ============================================================
@@ -577,6 +764,7 @@ const generateDefaultConfig = (overrides = {}, version = '1.0.0') => {
     "idleSound": "${overrides.idleSound || 'assets/Soft-high-tech-notification-sound-effect.mp3'}",
     "permissionSound": "${overrides.permissionSound || 'assets/Machine-alert-beep-sound-effect.mp3'}",
     "questionSound": "${overrides.questionSound || 'assets/Machine-alert-beep-sound-effect.mp3'}",
+    "errorSound": "${overrides.errorSound || 'assets/Machine-alert-beep-sound-effect.mp3'}",
     
     // ============================================================
     // GENERAL SETTINGS
@@ -586,7 +774,7 @@ const generateDefaultConfig = (overrides = {}, version = '1.0.0') => {
     "wakeMonitor": ${overrides.wakeMonitor !== undefined ? overrides.wakeMonitor : true},
     
     // Force system volume up if below threshold
-    "forceVolume": ${overrides.forceVolume !== undefined ? overrides.forceVolume : true},
+    "forceVolume": ${overrides.forceVolume !== undefined ? overrides.forceVolume : false},
     
     // Volume threshold (0-100): force volume if current level is below this
     "volumeThreshold": ${overrides.volumeThreshold !== undefined ? overrides.volumeThreshold : 50},
@@ -597,6 +785,109 @@ const generateDefaultConfig = (overrides = {}, version = '1.0.0') => {
     // Enable audio notifications (sound files and TTS)
     "enableSound": ${overrides.enableSound !== undefined ? overrides.enableSound : true},
     
+    // ============================================================
+    // DESKTOP NOTIFICATION SETTINGS
+    // ============================================================
+    // Native desktop notifications (Windows Toast, macOS Notification Center, Linux notify-send)
+    // These appear as system notifications alongside sound and TTS.
+    //
+    // Note: On Linux, you may need to install libnotify-bin:
+    //   Ubuntu/Debian: sudo apt install libnotify-bin
+    //   Fedora: sudo dnf install libnotify
+    //   Arch: sudo pacman -S libnotify
+    
+    // Enable native desktop notifications
+    "enableDesktopNotification": ${overrides.enableDesktopNotification !== undefined ? overrides.enableDesktopNotification : true},
+    
+    // How long the notification stays on screen (in seconds)
+    // Note: Some platforms may ignore this (especially Windows 10+)
+    "desktopNotificationTimeout": ${overrides.desktopNotificationTimeout !== undefined ? overrides.desktopNotificationTimeout : 5},
+    
+    // Include the project name in notification titles for easier identification
+    // Example: "OpenCode - MyProject" instead of just "OpenCode"
+    "showProjectInNotification": ${overrides.showProjectInNotification !== undefined ? overrides.showProjectInNotification : true},
+    
+    // ============================================================
+    // FOCUS DETECTION SETTINGS
+    // ============================================================
+    // Suppress notifications when you're actively looking at the terminal.
+    // This prevents notifications from interrupting you when you're already
+    // paying attention to the OpenCode terminal.
+    //
+    // PLATFORM SUPPORT:
+    //   macOS:   Full support - Uses AppleScript to detect frontmost application
+    //   Windows: Not supported - No reliable API available
+    //   Linux:   Not supported - Varies by desktop environment
+    //
+    // When focus detection is not supported on your platform, notifications
+    // will always be sent (fail-open behavior).
+    
+    // Suppress sound and desktop notifications when terminal is focused
+    // TTS reminders are still allowed (user might step away after task completes)
+    "suppressWhenFocused": ${overrides.suppressWhenFocused !== undefined ? overrides.suppressWhenFocused : true},
+    
+    // Override focus detection: always send notifications even when terminal is focused
+    // Set to true to disable focus-based suppression entirely
+    "alwaysNotify": ${overrides.alwaysNotify !== undefined ? overrides.alwaysNotify : false},
+    
+    // ============================================================
+    // WEBHOOK NOTIFICATION SETTINGS (Discord/Generic)
+    // ============================================================
+    // Send notifications to a Discord webhook or any compatible endpoint.
+    // This allows you to receive notifications on your phone or other devices.
+    
+    // Enable webhook notifications
+    "enableWebhook": ${overrides.enableWebhook !== undefined ? overrides.enableWebhook : false},
+    
+    // Webhook URL (e.g., https://discord.com/api/webhooks/...)
+    "webhookUrl": "${overrides.webhookUrl || ''}",
+    
+    // Username to show in the webhook message
+    "webhookUsername": "${overrides.webhookUsername || 'OpenCode Notify'}",
+    
+    // Events that should trigger a webhook notification
+    // Options: "idle", "permission", "error", "question"
+    "webhookEvents": ${formatJSON(overrides.webhookEvents || ["idle", "permission", "error", "question"], 4)},
+    
+    // Mention @everyone on permission requests (Discord only)
+    "webhookMentionOnPermission": ${overrides.webhookMentionOnPermission !== undefined ? overrides.webhookMentionOnPermission : false},
+    
+    // ============================================================
+    // SOUND THEME SETTINGS (Themed Sound Packs)
+    // ============================================================
+    // Configure a directory containing custom sound files for notifications.
+    // This allows you to use themed sound packs (e.g., Warcraft, StarCraft, etc.)
+    //
+    // Directory structure should contain:
+    //   /path/to/theme/idle/       - Sounds for task completion
+    //   /path/to/theme/permission/ - Sounds for permission requests
+    //   /path/to/theme/error/      - Sounds for agent errors
+    //   /path/to/theme/question/   - Sounds for agent questions
+    //
+    // If a specific event folder is missing, it falls back to default sounds.
+    
+    // Path to your custom sound theme directory (absolute path recommended)
+    "soundThemeDir": "${overrides.soundThemeDir || ''}",
+    
+    // Pick a random sound from the appropriate theme folder for each notification
+    "randomizeSoundFromTheme": ${overrides.randomizeSoundFromTheme !== undefined ? overrides.randomizeSoundFromTheme : true},
+    
+    // ============================================================
+    // PER-PROJECT SOUND SETTINGS
+    // ============================================================
+    // Assign a unique notification sound to each project based on its path.
+    // This helps you distinguish which project is notifying you when working
+    // on multiple tasks simultaneously.
+    //
+    // Note: Requires sounds named 'ding1.mp3' through 'ding6.mp3' in your 
+    // assets/ folder. If disabled, default sound files are used.
+    
+    // Enable unique sounds per project
+    "perProjectSounds": ${overrides.perProjectSounds !== undefined ? overrides.perProjectSounds : false},
+    
+    // Seed value to change sound assignments (0-999)
+    "projectSoundSeed": ${overrides.projectSoundSeed !== undefined ? overrides.projectSoundSeed : 0},
+    
     // Consider monitor asleep after this many seconds of inactivity (Windows only)
     "idleThresholdSeconds": ${overrides.idleThresholdSeconds !== undefined ? overrides.idleThresholdSeconds : 60},
     
@@ -643,98 +934,125 @@ const copyBundledAssets = (configDir) => {
   }
 };
 
-/**
- * Loads a configuration file from the OpenCode config directory.
- * If the file doesn't exist, creates a default config file with full documentation.
- * If the file exists, performs smart merging to add new fields without overwriting user values.
- * 
- * IMPORTANT: User values are NEVER overwritten. Only new fields from plugin updates are added.
- * 
- * @param {string} name - Name of the config file (without .jsonc extension)
- * @param {object} defaults - Default values if file doesn't exist or is invalid
- * @returns {object}
- */
-export const loadConfig = (name, defaults = {}) => {
-  const configDir = process.env.OPENCODE_CONFIG_DIR || path.join(os.homedir(), '.config', 'opencode');
-  const filePath = path.join(configDir, `${name}.jsonc`);
-
-  // Get current version from package.json
-  const pluginDir = getPluginDir();
-  const pkg = JSON.parse(fs.readFileSync(path.join(pluginDir, 'package.json'), 'utf-8'));
-  const currentVersion = pkg.version;
-
-  // Always ensure bundled assets are present
-  copyBundledAssets(configDir);
-
-  // Try to load existing config
-  let existingConfig = null;
-  if (fs.existsSync(filePath)) {
-    try {
-      const content = fs.readFileSync(filePath, 'utf-8');
-      existingConfig = parseJSONC(content);
-    } catch (error) {
-      // If file is invalid JSONC, we'll create a fresh one
-      debugLogToFile(`Config file was invalid (${error.message}), creating fresh config`, configDir);
-    }
-  }
-
-  // Get default config object with current version
-  const defaultConfig = getDefaultConfigObject();
-  defaultConfig._configVersion = currentVersion;
-
-  // CASE 1: No existing config - create new file with full documentation
-  if (!existingConfig) {
-    try {
-      // Ensure config directory exists
-      if (!fs.existsSync(configDir)) {
-        fs.mkdirSync(configDir, { recursive: true });
-      }
-
-      // Generate new config file with all documentation comments
-      const newConfigContent = generateDefaultConfig({}, currentVersion);
-      fs.writeFileSync(filePath, newConfigContent, 'utf-8');
-
-      debugLogToFile(`Initialized default config at ${filePath}`, configDir);
-
-      // Return the default config merged with any passed defaults
-      return { ...defaults, ...defaultConfig };
-    } catch (error) {
-      // If creation fails, return defaults
-      return { ...defaults, ...defaultConfig };
-    }
-  }
-
-  // CASE 2: Existing config - smart merge to add new fields only
-  // Find what new fields need to be added (for logging)
-  const newFields = findNewFields(defaultConfig, existingConfig);
-  
-  // Deep merge: user values preserved, only new fields added from defaults
-  const mergedConfig = deepMerge(defaultConfig, existingConfig);
-  
-  // Update version in merged config
-  mergedConfig._configVersion = currentVersion;
-
-  // Only write back if there are new fields to add OR version changed
-  const versionChanged = existingConfig._configVersion !== currentVersion;
-  
-  if (newFields.length > 0 || versionChanged) {
-    try {
-      // Regenerate the config file with full documentation comments
-      // Pass the merged config so user values are preserved in the output
-      const newConfigContent = generateDefaultConfig(mergedConfig, currentVersion);
-      fs.writeFileSync(filePath, newConfigContent, 'utf-8');
-
-      if (newFields.length > 0) {
-        debugLogToFile(`Added ${newFields.length} new config field(s): ${newFields.join(', ')}`, configDir);
-      }
-      if (versionChanged) {
-        debugLogToFile(`Config version updated to ${currentVersion}`, configDir);
-      }
-    } catch (error) {
-      // If write fails, still return the merged config (just won't persist new fields)
-      debugLogToFile(`Warning: Could not update config file: ${error.message}`, configDir);
-    }
-  }
-
-  return { ...defaults, ...mergedConfig };
-};
+/**
+ * Loads a configuration file from the OpenCode config directory.
+ * If the file doesn't exist, creates a default config file with full documentation.
+ * If the file exists, performs smart merging to add new fields without overwriting user values.
+ * 
+ * IMPORTANT: User values are NEVER overwritten. Only new fields from plugin updates are added.
+ * 
+ * @param {string} name - Name of the config file (without .jsonc extension)
+ * @param {object} defaults - Default values if file doesn't exist or is invalid
+ * @returns {object}
+ */
+export const loadConfig = (name, defaults = {}) => {
+  const configDir = process.env.OPENCODE_CONFIG_DIR || path.join(os.homedir(), '.config', 'opencode');
+  const filePath = path.join(configDir, `${name}.jsonc`);
+
+  // Get current version from package.json
+  const pluginDir = getPluginDir();
+  const pkg = JSON.parse(fs.readFileSync(path.join(pluginDir, 'package.json'), 'utf-8'));
+  const currentVersion = pkg.version;
+
+  // Get default config object with current version early so it can be used for peeking
+  const defaultConfig = getDefaultConfigObject();
+  defaultConfig._configVersion = currentVersion;
+
+  // Always ensure bundled assets are present
+  copyBundledAssets(configDir);
+
+  // Try to load existing config
+  let existingConfig = null;
+  if (fs.existsSync(filePath)) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      existingConfig = parseJSONC(content);
+    } catch (error) {
+      // If file is invalid JSONC, we'll use defaults for this run but NOT overwrite the user's file
+      // This prevents accidental loss of configuration due to a simple syntax error
+      debugLogToFile(`Warning: Config file at ${filePath} is invalid (${error.message}). Using default values for now. Please check your config for syntax errors.`, configDir);
+      existingConfig = null; // Forces CASE 1 logic but we'll modify it to avoid writing
+
+      // SMART PEEK: Even if parsing fails, try to see if "enabled" field is set to false/disabled
+      // to respect the user's intent to disable the plugin even with syntax errors.
+      try {
+        const rawContent = fs.readFileSync(filePath, 'utf-8');
+        // Match both boolean and string values for "enabled"
+        const enabledMatch = rawContent.match(/"enabled"\s*:\s*(false|true|"disabled"|"enabled"|'disabled'|'enabled')/i);
+        if (enabledMatch) {
+          const val = enabledMatch[1].replace(/["']/g, '').toLowerCase();
+          const isActuallyEnabled = (val === 'true' || val === 'enabled');
+          
+          // Inject into defaults and defaultConfig so it's picked up
+          defaults.enabled = isActuallyEnabled;
+          defaultConfig.enabled = isActuallyEnabled;
+          debugLogToFile(`Detected 'enabled: ${isActuallyEnabled}' via emergency regex peek (syntax error in file)`, configDir);
+        }
+      } catch (e) {
+        // Peek failed, just proceed with CASE 1
+      }
+    }
+
+  }
+
+  // CASE 1: No existing config (missing or invalid)
+  if (!existingConfig) {
+
+    try {
+      // Ensure config directory exists
+      if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+      }
+
+      // ONLY write a fresh config file if it doesn't exist at all.
+      // If it exists but was invalid, we already logged a warning and we'll just return defaults.
+      if (!fs.existsSync(filePath)) {
+        // Generate new config file with all documentation comments
+        const newConfigContent = generateDefaultConfig({}, currentVersion);
+        fs.writeFileSync(filePath, newConfigContent, 'utf-8');
+        debugLogToFile(`Initialized default config at ${filePath}`, configDir);
+      }
+
+      // Return the default config merged with any passed defaults
+      return { ...defaults, ...defaultConfig };
+    } catch (error) {
+      // If creation fails, return defaults
+      return { ...defaults, ...defaultConfig };
+    }
+  }
+
+
+  // CASE 2: Existing config - smart merge to add new fields only
+  // Find what new fields need to be added (for logging)
+  const newFields = findNewFields(defaultConfig, existingConfig);
+  
+  // Deep merge: user values preserved, only new fields added from defaults
+  const mergedConfig = deepMerge(defaultConfig, existingConfig);
+  
+  // Update version in merged config
+  mergedConfig._configVersion = currentVersion;
+
+  // Only write back if there are new fields to add OR version changed
+  const versionChanged = existingConfig._configVersion !== currentVersion;
+  
+  if (newFields.length > 0 || versionChanged) {
+    try {
+      // Regenerate the config file with full documentation comments
+      // Pass the merged config so user values are preserved in the output
+      const newConfigContent = generateDefaultConfig(mergedConfig, currentVersion);
+      fs.writeFileSync(filePath, newConfigContent, 'utf-8');
+
+      if (newFields.length > 0) {
+        debugLogToFile(`Added ${newFields.length} new config field(s): ${newFields.join(', ')}`, configDir);
+      }
+      if (versionChanged) {
+        debugLogToFile(`Config version updated to ${currentVersion}`, configDir);
+      }
+    } catch (error) {
+      // If write fails, still return the merged config (just won't persist new fields)
+      debugLogToFile(`Warning: Could not update config file: ${error.message}`, configDir);
+    }
+  }
+
+  return { ...defaults, ...mergedConfig };
+};