agentvibes 5.7.0 → 5.7.3

package/.claude/hooks/migrate-to-agentvibes.sh

@@ -46,22 +46,25 @@ echo -e "${BLUE}🔍 Checking for BMAD files in .claude/plugins/...${NC}"
 
 if [[ -f ".claude/plugins/bmad-voices-enabled.flag" ]]; then
     echo -e "${YELLOW}  Found: bmad-voices-enabled.flag${NC}"
-    mv .claude/plugins/bmad-voices-enabled.flag .agentvibes/bmad/
-    echo -e "${GREEN}  ✓ Moved to .agentvibes/bmad/${NC}"
+    mv -n .claude/plugins/bmad-voices-enabled.flag .agentvibes/bmad/ && \
+        echo -e "${GREEN}  ✓ Moved to .agentvibes/bmad/${NC}" || \
+        echo -e "${YELLOW}  ⚠ Already exists in .agentvibes/bmad/ — skipped${NC}"
     MIGRATED=true
 fi
 
 if [[ -f ".claude/plugins/bmad-party-mode-disabled.flag" ]]; then
     echo -e "${YELLOW}  Found: bmad-party-mode-disabled.flag${NC}"
-    mv .claude/plugins/bmad-party-mode-disabled.flag .agentvibes/bmad/
-    echo -e "${GREEN}  ✓ Moved to .agentvibes/bmad/${NC}"
+    mv -n .claude/plugins/bmad-party-mode-disabled.flag .agentvibes/bmad/ && \
+        echo -e "${GREEN}  ✓ Moved to .agentvibes/bmad/${NC}" || \
+        echo -e "${YELLOW}  ⚠ Already exists in .agentvibes/bmad/ — skipped${NC}"
     MIGRATED=true
 fi
 
 if [[ -f ".claude/plugins/.bmad-previous-settings" ]]; then
     echo -e "${YELLOW}  Found: .bmad-previous-settings${NC}"
-    mv .claude/plugins/.bmad-previous-settings .agentvibes/bmad/
-    echo -e "${GREEN}  ✓ Moved to .agentvibes/bmad/${NC}"
+    mv -n .claude/plugins/.bmad-previous-settings .agentvibes/bmad/ && \
+        echo -e "${GREEN}  ✓ Moved to .agentvibes/bmad/${NC}" || \
+        echo -e "${YELLOW}  ⚠ Already exists in .agentvibes/bmad/ — skipped${NC}"
     MIGRATED=true
 fi
 
@@ -72,8 +75,9 @@ echo -e "${BLUE}🔍 Checking for BMAD files in .claude/config/...${NC}"
 
 if [[ -f ".claude/config/bmad-voices.md" ]]; then
     echo -e "${YELLOW}  Found: bmad-voices.md${NC}"
-    mv .claude/config/bmad-voices.md .agentvibes/bmad/
-    echo -e "${GREEN}  ✓ Moved to .agentvibes/bmad/${NC}"
+    mv -n .claude/config/bmad-voices.md .agentvibes/bmad/ && \
+        echo -e "${GREEN}  ✓ Moved to .agentvibes/bmad/${NC}" || \
+        echo -e "${YELLOW}  ⚠ Already exists in .agentvibes/bmad/ — skipped${NC}"
     MIGRATED=true
 fi
 
@@ -97,29 +101,33 @@ echo -e "${BLUE}🔍 Checking for AgentVibes config in .claude/config/...${NC}"
 
 if [[ -f ".claude/config/agentvibes.json" ]]; then
     echo -e "${YELLOW}  Found: agentvibes.json${NC}"
-    mv .claude/config/agentvibes.json .agentvibes/config/
-    echo -e "${GREEN}  ✓ Moved to .agentvibes/config/${NC}"
+    mv -n .claude/config/agentvibes.json .agentvibes/config/ && \
+        echo -e "${GREEN}  ✓ Moved to .agentvibes/config/${NC}" || \
+        echo -e "${YELLOW}  ⚠ Already exists in .agentvibes/config/ — skipped${NC}"
     MIGRATED=true
 fi
 
 if [[ -f ".claude/config/personality-voice-defaults.default.json" ]]; then
     echo -e "${YELLOW}  Found: personality-voice-defaults.default.json${NC}"
-    mv .claude/config/personality-voice-defaults.default.json .agentvibes/config/
-    echo -e "${GREEN}  ✓ Moved to .agentvibes/config/${NC}"
+    mv -n .claude/config/personality-voice-defaults.default.json .agentvibes/config/ && \
+        echo -e "${GREEN}  ✓ Moved to .agentvibes/config/${NC}" || \
+        echo -e "${YELLOW}  ⚠ Already exists in .agentvibes/config/ — skipped${NC}"
     MIGRATED=true
 fi
 
 if [[ -f ".claude/config/personality-voice-defaults.json" ]]; then
     echo -e "${YELLOW}  Found: personality-voice-defaults.json${NC}"
-    mv .claude/config/personality-voice-defaults.json .agentvibes/config/
-    echo -e "${GREEN}  ✓ Moved to .agentvibes/config/${NC}"
+    mv -n .claude/config/personality-voice-defaults.json .agentvibes/config/ && \
+        echo -e "${GREEN}  ✓ Moved to .agentvibes/config/${NC}" || \
+        echo -e "${YELLOW}  ⚠ Already exists in .agentvibes/config/ — skipped${NC}"
     MIGRATED=true
 fi
 
 if [[ -f ".claude/config/README-personality-defaults.md" ]]; then
     echo -e "${YELLOW}  Found: README-personality-defaults.md${NC}"
-    mv .claude/config/README-personality-defaults.md .agentvibes/config/
-    echo -e "${GREEN}  ✓ Moved to .agentvibes/config/${NC}"
+    mv -n .claude/config/README-personality-defaults.md .agentvibes/config/ && \
+        echo -e "${GREEN}  ✓ Moved to .agentvibes/config/${NC}" || \
+        echo -e "${YELLOW}  ⚠ Already exists in .agentvibes/config/ — skipped${NC}"
     MIGRATED=true
 fi
 

package/.claude/hooks/personality-manager.sh

@@ -276,6 +276,13 @@ case "$1" in
       exit 1
     fi
 
+    # Validate name: alphanumeric, hyphens, underscores only — no path traversal
+    if [[ ! "$NAME" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+      echo "❌ Invalid personality name '$NAME'"
+      echo "   Name must contain only letters, numbers, hyphens, and underscores"
+      exit 1
+    fi
+
     FILE="$PERSONALITIES_DIR/${NAME}.md"
     if [[ -f "$FILE" ]]; then
       echo "❌ Personality '$NAME' already exists"
@@ -306,8 +313,8 @@ Describe how the AI should generate messages for this personality.
 - "Example response 2"
 EOF
 
-    # Replace NAME with actual name
-    sed -i "s/NAME/$NAME/g" "$FILE"
+    # Replace NAME placeholder — use | as delimiter to avoid issues with / in paths
+    sed -i "s|NAME|${NAME}|g" "$FILE"
 
     echo "✅ Created new personality: $NAME"
     echo "📝 Edit the file: $FILE"
@@ -327,6 +334,12 @@ EOF
       exit 1
     fi
 
+    if [[ ! "$NAME" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+      echo "❌ Invalid personality name '$NAME'"
+      echo "   Name must contain only letters, numbers, hyphens, and underscores"
+      exit 1
+    fi
+
     FILE="$PERSONALITIES_DIR/${NAME}.md"
     if [[ ! -f "$FILE" ]]; then
       echo "❌ Personality '$NAME' not found"

package/.claude/hooks/play-tts.sh

@@ -335,6 +335,12 @@ if [[ -n "$VOICE_OVERRIDE" ]]; then
   esac
 fi
 
+# Emit resolved voice and provider in verbose mode (used by tests and diagnostics)
+if [[ "${AGENTVIBES_VERBOSE:-0}" == "1" ]]; then
+  [[ -n "${VOICE_OVERRIDE:-}" ]] && echo "voice=${VOICE_OVERRIDE}" >&2
+  echo "provider=${ACTIVE_PROVIDER}" >&2
+fi
+
 # @function speak_text
 # @intent Route text to appropriate TTS provider
 # @why Reusable function for speaking, used by both single and learning modes

package/README.md

@@ -11,7 +11,7 @@
 [![Publish](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml/badge.svg)](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.7.0
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.7.3
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "agentvibes",
-  "version": "5.7.0",
+  "version": "5.7.3",
   "description": "Now your AI Agents can finally talk back! Professional TTS voice for Claude Code, Claude Desktop (via MCP), and Clawdbot with multi-provider support.",
   "homepage": "https://agentvibes.org",
   "keywords": [

package/src/console/audio-env.js

@@ -109,6 +109,29 @@ function _detect(players, env) {
   return null;
 }
 
+/**
+ * Detect the first LLM configured with remote transport in
+ * ~/.agentvibes/transport-config.json.
+ *
+ * Returns the LLM key (e.g. "claude-code") whose `mode` is "remote", or
+ * null if no such entry exists or the file is absent/invalid.
+ * Used by TUI voice-preview functions to route audio through the correct
+ * SSH transport rather than playing locally.
+ *
+ * @returns {string|null}
+ */
+export function detectRemoteLlm() {
+  const cfgPath = path.join(os.homedir(), '.agentvibes', 'transport-config.json');
+  if (!fs.existsSync(cfgPath)) return null;
+  try {
+    const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+    for (const [llm, opts] of Object.entries(cfg)) {
+      if (opts && opts.mode === 'remote') return llm;
+    }
+  } catch {}
+  return null;
+}
+
 /**
  * Detect the best available MP3 player.
  * On Windows, falls back to ffplay/mpv if installed, otherwise null.

package/src/console/tabs/agents-tab.js

@@ -18,7 +18,7 @@ import {
   PIPER_VOICES_DIR, SAMPLE_PHRASES,
   parseMultiSpeaker, scanInstalledVoices, getVoiceMeta, genderIconTag,
 } from './voices-tab.js';
-import { buildAudioEnv, detectWavPlayer } from '../audio-env.js';
+import { buildAudioEnv, detectWavPlayer, detectRemoteLlm } from '../audio-env.js';
 import { destroyList } from '../widgets/destroy-list.js';
 import { BRAND_PINK } from '../brand-colors.js';
 import { t } from '../../i18n/strings.js';
@@ -1031,64 +1031,35 @@ ${_tl('bmadDesc')}
       if (_previewVoiceId === voiceId) { _killVP(); vpPreviewLine.setContent(''); screen.render(); return; }
       _killVP();
 
-      const _isWin = process.platform === 'win32' && !process.env.WSL_DISTRO_NAME;
-
-      const _ms = parseMultiSpeaker(voiceId);
-      const voicePath = path.resolve(PIPER_VOICES_DIR, _ms.model + '.onnx');
-      const safeBase = path.resolve(PIPER_VOICES_DIR);
-      if (!voicePath.startsWith(safeBase + path.sep) && voicePath !== safeBase) return;
-
-      const tempWav = _secureTempWav('vp');
       const phrase = SAMPLE_PHRASES[Math.floor(Math.random() * SAMPLE_PHRASES.length)];
+      const playTtsScript = path.join(_projectRoot, '.claude', 'hooks', 'play-tts.sh');
+      if (!fs.existsSync(playTtsScript)) return;
 
-      // Resolve piper binary (on Windows, find piper.exe)
-      let _piperBin = 'piper';
-      if (_isWin) {
-        const _lad = process.env.LOCALAPPDATA ||
-          (process.env.USERPROFILE ? path.join(process.env.USERPROFILE, 'AppData', 'Local') : null);
-        if (_lad) {
-          const _ep = path.join(_lad, 'Programs', 'Piper', 'piper.exe');
-          if (fs.existsSync(_ep)) _piperBin = _ep;
-        }
-      }
+      const remoteLlm = detectRemoteLlm();
+      const args = [playTtsScript, phrase, voiceId];
+      if (remoteLlm) args.push('--llm', remoteLlm);
 
-      const args = ['--model', voicePath, '--output_file', tempWav];
-      if (_ms.speakerId != null) args.push('--speaker', String(_ms.speakerId));
-      const piper = spawn(_piperBin, args, {
-        stdio: ['pipe', 'ignore', 'ignore'],
-        detached: !_isWin,
-        windowsHide: true,
+      _previewProc = spawn('bash', args, {
+        stdio: 'ignore',
+        detached: true,
         env: _spawnEnv,
+        cwd: _projectRoot,
       });
-      piper.stdin.write(phrase + '\n');
-      piper.stdin.end();
-      _previewProc = piper;
       _previewVoiceId = voiceId;
 
       if (!_vpClosed) {
-        vpPreviewLine.setContent(`{bright-cyan-fg}♪ Synthesizing: ${voiceId}...{/bright-cyan-fg}`);
+        vpPreviewLine.setContent(`{bright-cyan-fg}♪ Playing: ${voiceId}...{/bright-cyan-fg}`);
         screen.render();
       }
 
-      piper.on('exit', (code) => {
-        if (_previewVoiceId !== voiceId) { try { fs.unlinkSync(tempWav); } catch {} return; }
-        if (code !== 0) { _previewProc = null; _previewVoiceId = null; try { fs.unlinkSync(tempWav); } catch {} return; }
-        const wp = detectWavPlayer(_spawnEnv);
-        if (!wp) return;
-        const pp = spawn(wp.bin, wp.args(tempWav), {
-          stdio: 'ignore',
-          detached: !_isWin,
-          windowsHide: true,
-          env: _spawnEnv,
-        });
-        _previewProc = pp;
-        if (!_vpClosed) { vpPreviewLine.setContent(`{bright-cyan-fg}♪ Playing: ${voiceId}{/bright-cyan-fg}`); screen.render(); }
-        pp.on('exit', () => {
-          if (_previewVoiceId === voiceId) { _previewVoiceId = null; _previewProc = null; if (!_vpClosed) { vpPreviewLine.setContent(''); screen.render(); } }
-          try { fs.unlinkSync(tempWav); } catch {}
-        });
+      _previewProc.on('exit', () => {
+        if (_previewVoiceId === voiceId) {
+          _previewVoiceId = null;
+          _previewProc = null;
+          if (!_vpClosed) { vpPreviewLine.setContent(''); screen.render(); }
+        }
       });
-      piper.on('error', () => { _previewProc = null; _previewVoiceId = null; });
+      _previewProc.on('error', () => { _previewProc = null; _previewVoiceId = null; });
     }
 
     vpList.key(['enter'], () => {
@@ -1220,8 +1191,10 @@ ${_tl('bmadDesc')}
       const _spawnEnv = buildAudioEnv();
       const scriptDir = path.join(_projectRoot, '.claude', 'hooks');
       const plainScript = path.join(scriptDir, 'play-tts.sh');
+      const remoteLlm = detectRemoteLlm();
       const args = [plainScript, phrase];
       if (voiceId) args.push(voiceId);
+      if (remoteLlm) args.push('--llm', remoteLlm);
 
       const proc = spawn('bash', args, {
         stdio: ['ignore', 'ignore', 'ignore'],

package/src/console/tabs/settings-tab.js

@@ -24,7 +24,7 @@ import {
 } from './voices-tab.js';
 import { LanguageService } from '../../services/language-service.js';
 import { SUPPORTED_LANGUAGES, t } from '../../i18n/strings.js';
-import { buildAudioEnv, detectWavPlayer } from '../audio-env.js';
+import { buildAudioEnv, detectWavPlayer, detectRemoteLlm } from '../audio-env.js';
 import { destroyList } from '../widgets/destroy-list.js';
 import { openReverbPicker } from '../widgets/reverb-picker.js';
 import { openPersonalityPicker } from '../widgets/personality-picker.js';
@@ -633,61 +633,35 @@ export function createSettingsTab(screen, services) {
       if (_previewVoiceId === voiceId) { _killVP(); vpPreviewLine.setContent(''); _refreshVP(); return; }
       _killVP();
 
-      const _ms = parseMultiSpeaker(voiceId);
-      const voicePath = path.resolve(PIPER_VOICES_DIR, _ms.model + '.onnx');
-      const safeBase = path.resolve(PIPER_VOICES_DIR);
-      if (!voicePath.startsWith(safeBase + path.sep) && voicePath !== safeBase) return;
-
-      const tempWav = _secureTempWav('vp');
       const phrase = SAMPLE_PHRASES[Math.floor(Math.random() * SAMPLE_PHRASES.length)];
+      const playTtsScript = path.join(_projectRoot, '.claude', 'hooks', 'play-tts.sh');
+      if (!fs.existsSync(playTtsScript)) return;
 
-      let _piperBin = 'piper';
-      if (_isWin) {
-        const _lad = process.env.LOCALAPPDATA ||
-          (process.env.USERPROFILE ? path.join(process.env.USERPROFILE, 'AppData', 'Local') : null);
-        if (_lad) {
-          const _ep = path.join(_lad, 'Programs', 'Piper', 'piper.exe');
-          if (fs.existsSync(_ep)) _piperBin = _ep;
-        }
-      }
+      const remoteLlm = detectRemoteLlm();
+      const args = [playTtsScript, phrase, voiceId];
+      if (remoteLlm) args.push('--llm', remoteLlm);
 
-      const args = ['--model', voicePath, '--output_file', tempWav];
-      if (_ms.speakerId != null) args.push('--speaker', String(_ms.speakerId));
-      const piper = spawn(_piperBin, args, {
-        stdio: ['pipe', 'ignore', 'ignore'],
-        detached: !_isWin,
-        windowsHide: true,
+      _previewProc = spawn('bash', args, {
+        stdio: 'ignore',
+        detached: true,
         env: _spawnEnv,
+        cwd: _projectRoot,
       });
-      piper.stdin.write(phrase + '\n');
-      piper.stdin.end();
-      _previewProc = piper;
       _previewVoiceId = voiceId;
 
       if (!_vpClosed) {
-        vpPreviewLine.setContent(`{cyan-fg}♪ Synthesizing: ${voiceId}...{/cyan-fg}`);
+        vpPreviewLine.setContent(`{cyan-fg}♪ Playing: ${voiceId}...{/cyan-fg}`);
         _refreshVP();
       }
 
-      piper.on('exit', (code) => {
-        if (_previewVoiceId !== voiceId) { try { fs.unlinkSync(tempWav); } catch {} return; }
-        if (code !== 0) { _previewProc = null; _previewVoiceId = null; try { fs.unlinkSync(tempWav); } catch {} return; }
-        const wp = detectWavPlayer(_spawnEnv);
-        if (!wp) return;
-        const pp = spawn(wp.bin, wp.args(tempWav), {
-          stdio: 'ignore',
-          detached: !_isWin,
-          windowsHide: true,
-          env: _spawnEnv,
-        });
-        _previewProc = pp;
-        if (!_vpClosed) { vpPreviewLine.setContent(`{cyan-fg}♪ Playing: ${voiceId}{/cyan-fg}`); screen.render(); }
-        pp.on('exit', () => {
-          if (_previewVoiceId === voiceId) { _previewVoiceId = null; _previewProc = null; if (!_vpClosed) { vpPreviewLine.setContent(''); _refreshVP(); } }
-          try { fs.unlinkSync(tempWav); } catch {}
-        });
+      _previewProc.on('exit', () => {
+        if (_previewVoiceId === voiceId) {
+          _previewVoiceId = null;
+          _previewProc = null;
+          if (!_vpClosed) { vpPreviewLine.setContent(''); _refreshVP(); }
+        }
       });
-      piper.on('error', () => { _previewProc = null; _previewVoiceId = null; });
+      _previewProc.on('error', () => { _previewProc = null; _previewVoiceId = null; });
     }
 
     vpList.key(['enter'], () => {

package/src/console/widgets/personality-picker.js

@@ -10,7 +10,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import { spawn } from 'node:child_process';
 import { destroyList } from './destroy-list.js';
-import { buildAudioEnv } from '../audio-env.js';
+import { buildAudioEnv, detectRemoteLlm } from '../audio-env.js';
 import { BRAND_PINK } from '../brand-colors.js';
 import { PERSONALITY_EMOJIS, PERSONALITIES } from '../constants/personalities.js';
 
@@ -138,7 +138,10 @@ export function openPersonalityPicker(screen, currentPersonality, onSelect, onCl
       });
     } else {
       const ttsScript = path.join(process.cwd(), '.claude', 'hooks', 'play-tts.sh');
-      _pickerTtsProc = spawn('bash', [ttsScript, phrase], {
+      const remoteLlm = detectRemoteLlm();
+      const ttsArgs = [ttsScript, phrase];
+      if (remoteLlm) ttsArgs.push('--llm', remoteLlm);
+      _pickerTtsProc = spawn('bash', ttsArgs, {
         stdio: 'ignore',
         detached: true,
         env: _env,

package/src/installer.js

@@ -84,6 +84,105 @@ const packageJson = JSON.parse(
 );
 const VERSION = packageJson.version;
 
+// ── Install manifest utilities ──────────────────────────────────────────────
+// The manifest records the SHA-256 hash of every file AgentVibes installs,
+// so update() can detect user modifications before overwriting.  Files whose
+// hash has changed since the last install are skipped (a .user.bak copy is
+// saved), preventing silent destruction of user customisations.
+
+const MANIFEST_FILENAME = 'install-manifest.json';
+
+function getProjectManifestPath(targetDir) {
+  return path.join(targetDir, '.agentvibes', MANIFEST_FILENAME);
+}
+
+function getGlobalManifestPath(homeDir) {
+  return path.join(homeDir || os.homedir(), '.agentvibes', MANIFEST_FILENAME);
+}
+
+async function computeFileHash(filePath) {
+  try {
+    const buf = await fs.readFile(filePath);
+    return crypto.createHash('sha256').update(buf).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+async function loadManifest(manifestPath) {
+  try {
+    const data = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+    return data.files ?? {};
+  } catch {
+    return {};
+  }
+}
+
+async function saveManifest(manifestPath, files) {
+  await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+  const tmp = manifestPath + '.tmp.' + process.pid;
+  try {
+    await fs.writeFile(
+      tmp,
+      JSON.stringify({ version: 1, updatedAt: new Date().toISOString(), files }, null, 2),
+      { mode: 0o600 }
+    );
+    await fs.rename(tmp, manifestPath);
+  } catch (err) {
+    try { await fs.unlink(tmp); } catch { /* cleanup */ }
+    throw err;
+  }
+}
+
+// Copies srcPath → destPath only when safe:
+//   • dest missing                     → copy  (action: 'new')
+//   • dest == src (already current)    → skip  (action: 'unchanged')
+//   • dest hash == manifest hash       → copy  (action: 'updated')
+//   • dest hash != manifest hash       → skip  (action: 'skipped', .user.bak saved)
+//   • no manifest entry yet            → copy  (action: 'updated')
+async function manifestSafeCopy(srcPath, destPath, manifest) {
+  const srcHash = await computeFileHash(srcPath);
+  if (!srcHash) return { action: 'skipped', hash: null }; // src missing
+
+  const destHash = await computeFileHash(destPath);
+
+  if (!destHash) {
+    await fs.copyFile(srcPath, destPath);
+    return { action: 'new', hash: srcHash };
+  }
+
+  if (destHash === srcHash) {
+    return { action: 'unchanged', hash: srcHash };
+  }
+
+  const manifestHash = manifest[destPath]?.hash;
+  if (manifestHash && destHash !== manifestHash) {
+    // User modified the file since we last installed it — preserve it
+    try { await fs.copyFile(destPath, destPath + '.user.bak'); } catch { /* best effort */ }
+    return { action: 'skipped', hash: destHash };
+  }
+
+  // Stock file (or no manifest entry yet) — safe to overwrite
+  await fs.copyFile(srcPath, destPath);
+  return { action: 'updated', hash: srcHash };
+}
+
+// Delete only the files listed in manifest that reside under baseDir.
+// Then attempt (non-recursively) to prune any resulting empty directories.
+async function removeManifestFiles(manifest, baseDir, dirsToTryPrune = []) {
+  const base = path.resolve(baseDir);
+  let count = 0;
+  for (const filePath of Object.keys(manifest)) {
+    const resolved = path.resolve(filePath);
+    if (!resolved.startsWith(base + path.sep)) continue;
+    try { await fs.unlink(filePath); count++; } catch { /* already gone */ }
+  }
+  for (const dir of dirsToTryPrune) {
+    try { await fs.rmdir(dir); } catch { /* not empty or already gone — leave it */ }
+  }
+  return count;
+}
+
 // Personality emoji mapping for quick visual recognition
 const personalityEmojis = {
   'angry': '😠',
@@ -3387,19 +3486,30 @@ async function copyCommandFiles(targetDir, spinner) {
     let failedCommands = [];
     let successCount = 0;
 
+    const manifestPath = getProjectManifestPath(targetDir);
+    const manifest = await loadManifest(manifestPath);
+    const manifestUpdates = {};
+
     for (const file of commandFiles) {
       const srcPath = path.join(srcCommandsDir, file);
       const destPath = path.join(agentVibesCommandsDir, file);
       try {
-        await fs.copyFile(srcPath, destPath);
-        installedCommands.push(file);
-        successCount++;
+        const result = await manifestSafeCopy(srcPath, destPath, manifest);
+        if (result.action !== 'skipped') {
+          installedCommands.push(file);
+          successCount++;
+          if (result.hash) manifestUpdates[destPath] = { hash: result.hash, installedAt: new Date().toISOString() };
+        }
       } catch (err) {
         failedCommands.push({ file, error: err.message });
         // Continue with other files
       }
     }
 
+    if (Object.keys(manifestUpdates).length > 0) {
+      await saveManifest(manifestPath, { ...manifest, ...manifestUpdates }).catch(() => { /* best effort */ });
+    }
+
     if (successCount === commandFiles.length) {
       spinner.succeed(chalk.green(`Installed ${successCount} slash commands!\n`));
     } else {
@@ -3515,16 +3625,17 @@ async function filterHookFiles(srcHooksDir, allFiles) {
  * @param {string} filename - Name of the file
  * @returns {Promise<Object>} Result object with success/error info
  */
-async function copyHookFile(srcPath, destPath, filename) {
+async function copyHookFile(srcPath, destPath, filename, manifest = {}) {
   try {
-    await fs.copyFile(srcPath, destPath);
-
-    if (filename.endsWith('.sh')) {
+    const result = await manifestSafeCopy(srcPath, destPath, manifest);
+    if (result.action === 'skipped' && result.hash !== null) {
+      // User-modified file preserved — do not chmod or report as installed
+      return { success: true, name: filename, executable: false, userModified: true, hash: null };
+    }
+    if (filename.endsWith('.sh') && result.action !== 'skipped') {
       await fs.chmod(destPath, 0o750);
-      return { success: true, name: filename, executable: true };
     }
-
-    return { success: true, name: filename, executable: false };
+    return { success: true, name: filename, executable: filename.endsWith('.sh'), hash: result.hash };
   } catch (err) {
     return { success: false, name: filename, error: err.message };
   }
@@ -3600,21 +3711,33 @@ async function copyHookFiles(targetDir, spinner) {
 
     spinner.start(`Installing ${hookFiles.length} TTS scripts...`);
 
+    const manifestPath = getProjectManifestPath(targetDir);
+    const manifest = await loadManifest(manifestPath);
+    const manifestUpdates = {};
+
     const installedFiles = [];
     const failedFiles = [];
 
     for (const file of hookFiles) {
       const srcPath = path.join(srcHooksDir, file);
       const destPath = path.join(hooksDir, file);
-      const result = await copyHookFile(srcPath, destPath, file);
+      const result = await copyHookFile(srcPath, destPath, file, manifest);
 
       if (result.success) {
-        installedFiles.push({ name: result.name, executable: result.executable });
+        if (!result.userModified) {
+          installedFiles.push({ name: result.name, executable: result.executable });
+          if (result.hash) manifestUpdates[destPath] = { hash: result.hash, installedAt: new Date().toISOString() };
+        }
+        // userModified files are silently skipped (their .user.bak is already saved)
       } else {
         failedFiles.push({ name: result.name, error: result.error });
       }
     }
 
+    if (Object.keys(manifestUpdates).length > 0) {
+      await saveManifest(manifestPath, { ...manifest, ...manifestUpdates }).catch(() => { /* best effort */ });
+    }
+
     const successCount = installedFiles.length;
 
     if (successCount === hookFiles.length) {
@@ -3663,11 +3786,22 @@ async function copyPersonalityFiles(targetDir, spinner) {
   spinner.start(`Installing ${personalityMdFiles.length} personality templates...`);
   let installedPersonalities = [];
 
+  const personalityManifestPath = getProjectManifestPath(targetDir);
+  const personalityManifest = await loadManifest(personalityManifestPath);
+  const personalityManifestUpdates = {};
+
   for (const file of personalityMdFiles) {
     const srcPath = path.join(srcPersonalitiesDir, file);
     const destPath = path.join(destPersonalitiesDir, file);
-    await fs.copyFile(srcPath, destPath);
-    installedPersonalities.push(file);
+    const result = await manifestSafeCopy(srcPath, destPath, personalityManifest);
+    if (result.action !== 'skipped') {
+      installedPersonalities.push(file);
+      if (result.hash) personalityManifestUpdates[destPath] = { hash: result.hash, installedAt: new Date().toISOString() };
+    }
+  }
+
+  if (Object.keys(personalityManifestUpdates).length > 0) {
+    await saveManifest(personalityManifestPath, { ...personalityManifest, ...personalityManifestUpdates }).catch(() => { /* best effort */ });
   }
 
   spinner.succeed(chalk.green('Installed personality templates!\n'));
@@ -4982,6 +5116,10 @@ async function updatePersonalityFiles(targetDir, srcPersonalitiesDir) {
   let newPersonalities = 0;
   let updatedPersonalities = 0;
 
+  const manifestPath = getProjectManifestPath(targetDir);
+  const manifest = await loadManifest(manifestPath);
+  const manifestUpdates = {};
+
   for (const file of allPersonalityFiles) {
     const srcPath = path.join(srcPersonalitiesDir, file);
     const stat = await fs.stat(srcPath);
@@ -4991,17 +5129,24 @@ async function updatePersonalityFiles(targetDir, srcPersonalitiesDir) {
     }
 
     const destPath = path.join(destPersonalitiesDir, file);
+    const result = await manifestSafeCopy(srcPath, destPath, manifest);
 
-    try {
-      await fs.access(destPath);
-      await fs.copyFile(srcPath, destPath);
-      updatedPersonalities++;
-    } catch {
-      await fs.copyFile(srcPath, destPath);
+    if (result.action === 'new') {
       newPersonalities++;
+    } else if (result.action === 'updated' || result.action === 'unchanged') {
+      updatedPersonalities++;
+    }
+    // 'skipped' = user modified — leave it alone, .user.bak already saved
+
+    if (result.hash && result.action !== 'skipped') {
+      manifestUpdates[destPath] = { hash: result.hash, installedAt: new Date().toISOString() };
     }
   }
 
+  if (Object.keys(manifestUpdates).length > 0) {
+    await saveManifest(manifestPath, { ...manifest, ...manifestUpdates }).catch(() => { /* best effort */ });
+  }
+
   return { new: newPersonalities, updated: updatedPersonalities };
 }
 
@@ -5033,10 +5178,21 @@ async function updateCommandFiles(targetDir, spinner) {
   const srcCommandsDir = path.join(__dirname, '..', '.claude', 'commands', 'agent-vibes');
   const commandFiles = await fs.readdir(srcCommandsDir);
 
+  const manifestPath = getProjectManifestPath(targetDir);
+  const manifest = await loadManifest(manifestPath);
+  const manifestUpdates = {};
+
   for (const file of commandFiles) {
     const srcPath = path.join(srcCommandsDir, file);
     const destPath = path.join(commandsDir, file);
-    await fs.copyFile(srcPath, destPath);
+    const result = await manifestSafeCopy(srcPath, destPath, manifest);
+    if (result.hash && result.action !== 'skipped') {
+      manifestUpdates[destPath] = { hash: result.hash, installedAt: new Date().toISOString() };
+    }
+  }
+
+  if (Object.keys(manifestUpdates).length > 0) {
+    await saveManifest(manifestPath, { ...manifest, ...manifestUpdates }).catch(() => { /* best effort */ });
   }
 
   return commandFiles.length;
@@ -5066,13 +5222,20 @@ async function updateGlobalHooks(srcHooksDir, homeDirOverride) {
   // Always ensure the global hooks dir exists so registered $HOME hooks resolve.
   await fs.mkdir(globalHooksDir, { recursive: true });
 
+  const manifestPath = getGlobalManifestPath(homeDir);
+  const manifest = await loadManifest(manifestPath);
+  const manifestUpdates = { ...manifest };
+
   for (const hook of CRITICAL_HOOKS) {
     const destPath = path.join(globalHooksDir, hook);
     const srcPath = path.join(srcHooksDir, hook);
     try {
-      await fs.copyFile(srcPath, destPath);
-      await fs.chmod(destPath, 0o750);
-      updated++;
+      const result = await manifestSafeCopy(srcPath, destPath, manifest);
+      if (result.action !== 'skipped') {
+        if (result.action !== 'unchanged') await fs.chmod(destPath, 0o750);
+        if (result.hash) manifestUpdates[destPath] = { hash: result.hash, installedAt: new Date().toISOString() };
+        updated++;
+      }
     } catch {
       // src missing — skip silently
     }
@@ -5086,13 +5249,18 @@ async function updateGlobalHooks(srcHooksDir, homeDirOverride) {
     const destPath = path.join(globalHooksWindowsDir, hook);
     const srcPath = path.join(srcHooksWindowsDir, hook);
     try {
-      await fs.copyFile(srcPath, destPath);
-      updated++;
+      const result = await manifestSafeCopy(srcPath, destPath, manifest);
+      if (result.action !== 'skipped') {
+        if (result.hash) manifestUpdates[destPath] = { hash: result.hash, installedAt: new Date().toISOString() };
+        updated++;
+      }
     } catch {
       // src missing — skip silently
     }
   }
 
+  await saveManifest(manifestPath, manifestUpdates).catch(() => { /* best effort */ });
+
   return updated;
 }
 
@@ -5406,7 +5574,7 @@ async function install(options = {}) {
     await installPluginManifest(targetDir, silentSpinner);
     await ensureGitRepo(targetDir, silentSpinner);
 
-    // Save provider configuration
+    // Save provider configuration (always written — provider was explicitly chosen in wizard)
     const providerConfigPath = path.join(claudeDir, 'tts-provider.txt');
     await fs.writeFile(providerConfigPath, selectedProvider);
 
@@ -5520,7 +5688,8 @@ Troubleshooting:
         default:               defaultVoice = 'Samantha'; break;
       }
     }
-    await fs.writeFile(voiceConfigPath, defaultVoice);
+    // Only write voice on first install — preserve user's current voice selection on reinstall
+    try { await fs.access(voiceConfigPath); } catch { await fs.writeFile(voiceConfigPath, defaultVoice); }
 
     // Sync voice + provider to global .agentvibes/config.json so TUI finds them
     // regardless of which directory it's launched from
@@ -5579,16 +5748,18 @@ Troubleshooting:
       await fs.writeFile(translateFile, 'auto', { mode: 0o600 });
     }
 
-    // Apply verbosity, personality, pretext
-    await fs.writeFile(path.join(claudeDir, 'tts-verbosity.txt'), userConfig.verbosity);
+    // Apply verbosity and personality — only write on first install to preserve user customisation.
+    // To reset these, delete the files manually or use the MCP tools.
+    const verbosityPath = path.join(claudeDir, 'tts-verbosity.txt');
+    try { await fs.access(verbosityPath); } catch { await fs.writeFile(verbosityPath, userConfig.verbosity); }
     if (userConfig.personality && userConfig.personality !== 'none') {
-      await fs.writeFile(path.join(claudeDir, 'tts-personality.txt'), userConfig.personality);
+      const personalityPath = path.join(claudeDir, 'tts-personality.txt');
+      try { await fs.access(personalityPath); } catch { await fs.writeFile(personalityPath, userConfig.personality); }
     }
     if (userConfig.pretext && userConfig.pretext.trim()) {
       await fs.writeFile(path.join(configDir, 'tts-pretext.txt'), userConfig.pretext, { mode: 0o600 });
-    } else {
-      try { await fs.unlink(path.join(configDir, 'tts-pretext.txt')); } catch { /* ok */ }
     }
+    // Do NOT unlink tts-pretext.txt when blank — user may have set it via MCP or manually.
 
     // Apply reverb setting
     const selectedReverb = userConfig.reverb;
@@ -6008,23 +6179,40 @@ program
     try {
       let removedCount = 0;
 
-      // Remove project-level files
-      const projectPaths = [
+      // Remove project-level files.
+      // AgentVibes-exclusive directories are safe to rm -r.
+      // Shared directories (.claude/hooks, .claude/personalities, etc.) are
+      // cleaned up via the install manifest so user-added files are preserved.
+      const exclusiveDirs = [
         path.join(targetDir, '.claude', 'commands', 'agent-vibes'),
+        path.join(targetDir, '.agentvibes'),
+      ];
+      for (const dirPath of exclusiveDirs) {
+        try { await fs.rm(dirPath, { recursive: true, force: true }); removedCount++; } catch { /* not present */ }
+      }
+
+      // Manifest-based removal for shared directories
+      const projectManifest = await loadManifest(getProjectManifestPath(targetDir));
+      const sharedDirsToTryPrune = [
         path.join(targetDir, '.claude', 'hooks'),
         path.join(targetDir, '.claude', 'hooks-windows'),
         path.join(targetDir, '.claude', 'personalities'),
         path.join(targetDir, '.claude', 'output-styles'),
         path.join(targetDir, '.claude', 'audio'),
-        path.join(targetDir, '.agentvibes'),
       ];
-
-      for (const dirPath of projectPaths) {
-        try {
-          await fs.rm(dirPath, { recursive: true, force: true });
-          removedCount++;
-        } catch (err) {
-          // Ignore if directory doesn't exist
+      if (Object.keys(projectManifest).length > 0) {
+        removedCount += await removeManifestFiles(projectManifest, targetDir, sharedDirsToTryPrune);
+      } else {
+        // No manifest (pre-manifest install) — fall back to named-file removal for safety
+        const knownProjectFiles = [
+          ...CRITICAL_HOOKS.map(h => path.join(targetDir, '.claude', 'hooks', h)),
+          ...CRITICAL_HOOKS_WINDOWS.map(h => path.join(targetDir, '.claude', 'hooks-windows', h)),
+        ];
+        for (const f of knownProjectFiles) {
+          try { await fs.unlink(f); removedCount++; } catch { /* not present */ }
+        }
+        for (const dir of sharedDirsToTryPrune) {
+          try { await fs.rmdir(dir); } catch { /* not empty or gone */ }
         }
       }
 
@@ -6065,33 +6253,44 @@ program
           removedCount++;
         } catch (_) { /* not present */ }
 
-        // Inside ~/.claude/, remove only the subdirs/files AgentVibes installed
+        // Inside ~/.claude/, remove only the files AgentVibes installed.
+        // Use the global manifest so user-added hooks/personalities are preserved.
+        // AgentVibes-exclusive subdir is removed via rm -r; shared dirs via manifest.
         const claudeDir = path.join(homedir, '.claude');
-        const agentVibesOwnedInClaude = [
+        try { await fs.rm(path.join(claudeDir, 'commands', 'agent-vibes'), { recursive: true, force: true }); removedCount++; } catch { /* not present */ }
+
+        const globalManifest = await loadManifest(getGlobalManifestPath(homedir));
+        const globalSharedDirs = [
           path.join(claudeDir, 'hooks'),
           path.join(claudeDir, 'hooks-windows'),
-          path.join(claudeDir, 'commands', 'agent-vibes'),
           path.join(claudeDir, 'personalities'),
           path.join(claudeDir, 'output-styles'),
           path.join(claudeDir, 'audio'),
         ];
+        if (Object.keys(globalManifest).length > 0) {
+          removedCount += await removeManifestFiles(globalManifest, homedir, globalSharedDirs);
+        } else {
+          // No manifest — remove only known AgentVibes hook files by name
+          const knownGlobalFiles = [
+            ...CRITICAL_HOOKS.map(h => path.join(claudeDir, 'hooks', h)),
+            ...CRITICAL_HOOKS_WINDOWS.map(h => path.join(claudeDir, 'hooks-windows', h)),
+          ];
+          for (const f of knownGlobalFiles) {
+            try { await fs.unlink(f); removedCount++; } catch { /* not present */ }
+          }
+          for (const dir of globalSharedDirs) {
+            try { await fs.rmdir(dir); } catch { /* not empty or gone */ }
+          }
+        }
+
         const agentVibesConfigFiles = [
           'tts-voice.txt', 'tts-provider.txt', 'tts-personality.txt',
           'tts-verbosity.txt', 'tts-translate.txt', 'tts-target-voice.txt',
           'tts-target-language.txt', 'tts-language.txt', 'personalities.json',
           'github-star-reminder.txt', 'piper-voices-dir.txt', 'verbosity.txt',
         ];
-
-        for (const dirPath of agentVibesOwnedInClaude) {
-          try {
-            await fs.rm(dirPath, { recursive: true, force: true });
-            removedCount++;
-          } catch (_) { /* not present */ }
-        }
         for (const fileName of agentVibesConfigFiles) {
-          try {
-            await fs.unlink(path.join(claudeDir, fileName));
-          } catch (_) { /* not present */ }
+          try { await fs.unlink(path.join(claudeDir, fileName)); } catch { /* not present */ }
         }
       }
 
@@ -6503,5 +6702,9 @@ export {
   copyPluginFiles, copyBmadConfigFiles, copyBackgroundMusicFiles,
   copyConfigFiles, copyCodexFiles, configureSessionStartHook, configurePartyModeHook, ensureGitRepo,
   installPluginManifest, checkAndInstallPiper,
-  updateGlobalHooks, CRITICAL_HOOKS, CRITICAL_HOOKS_WINDOWS,
+  updateGlobalHooks, updateCommandFiles, updatePersonalityFiles,
+  CRITICAL_HOOKS, CRITICAL_HOOKS_WINDOWS,
+  // Manifest utilities (used by tests and external tooling)
+  getProjectManifestPath, getGlobalManifestPath,
+  loadManifest, saveManifest, computeFileHash, manifestSafeCopy, removeManifestFiles,
 };

package/src/services/llm-provider-service.js

@@ -481,19 +481,54 @@ export async function removeCopilotMcp(targetDir) {
   }
 }
 
+const AGENTVIBES_MARKER_START = '<!-- BEGIN AGENTVIBES -->';
+const AGENTVIBES_MARKER_END = '<!-- END AGENTVIBES -->';
+
+function wrapWithMarkers(content) {
+  return `${AGENTVIBES_MARKER_START}\n${content.trim()}\n${AGENTVIBES_MARKER_END}\n`;
+}
+
+function injectMarkerBlock(existing, newBlock) {
+  const start = existing.indexOf(AGENTVIBES_MARKER_START);
+  const end = existing.indexOf(AGENTVIBES_MARKER_END);
+  if (start !== -1 && end !== -1) {
+    return existing.substring(0, start) + newBlock + existing.substring(end + AGENTVIBES_MARKER_END.length + 1);
+  }
+  return existing.trimEnd() + (existing.trim() ? '\n\n' : '') + newBlock;
+}
+
+function removeMarkerBlock(existing) {
+  const start = existing.indexOf(AGENTVIBES_MARKER_START);
+  const end = existing.indexOf(AGENTVIBES_MARKER_END);
+  if (start === -1 || end === -1) return existing;
+  const before = existing.substring(0, start).trimEnd();
+  const after = existing.substring(end + AGENTVIBES_MARKER_END.length).replace(/^\n+/, '\n');
+  return (before + after).trimEnd() + '\n';
+}
+
 export async function installCopilotInstructions(targetDir, packageDir) {
   const destPath = path.join(targetDir, '.github', 'copilot-instructions.md');
   const srcPath = path.join(packageDir, '.github', 'copilot-instructions.md');
   try {
     await fs.mkdir(path.join(targetDir, '.github'), { recursive: true });
-    const content = await fs.readFile(srcPath, 'utf8');
-    await fs.writeFile(destPath, content);
+    const srcContent = await fs.readFile(srcPath, 'utf8');
+    let existing = '';
+    try { existing = await fs.readFile(destPath, 'utf8'); } catch { /* new file */ }
+    const block = wrapWithMarkers(srcContent);
+    await fs.writeFile(destPath, injectMarkerBlock(existing, block));
   } catch { /* best effort */ }
 }
 
 export async function removeCopilotInstructions(targetDir) {
+  const destPath = path.join(targetDir, '.github', 'copilot-instructions.md');
   try {
-    await fs.unlink(path.join(targetDir, '.github', 'copilot-instructions.md'));
+    const existing = await fs.readFile(destPath, 'utf8');
+    const updated = removeMarkerBlock(existing);
+    if (updated.trim()) {
+      await fs.writeFile(destPath, updated);
+    } else {
+      await fs.unlink(destPath);
+    }
   } catch { /* already gone */ }
 }
 
@@ -582,10 +617,15 @@ export function buildCodexToml(existingContent = '') {
 export async function installCodexInstructions(targetDir, packageDir) {
   const srcPath = path.join(packageDir, '.codex', 'AGENTS.md');
   try {
-    const content = await fs.readFile(srcPath, 'utf8');
+    const srcContent = await fs.readFile(srcPath, 'utf8');
+    const block = wrapWithMarkers(srcContent);
     await fs.mkdir(path.join(targetDir, '.codex'), { recursive: true });
-    await fs.writeFile(path.join(targetDir, '.codex', 'AGENTS.md'), content);
-    await fs.writeFile(path.join(targetDir, 'AGENTS.md'), content);
+
+    for (const dest of [path.join(targetDir, '.codex', 'AGENTS.md'), path.join(targetDir, 'AGENTS.md')]) {
+      let existing = '';
+      try { existing = await fs.readFile(dest, 'utf8'); } catch { /* new file */ }
+      await fs.writeFile(dest, injectMarkerBlock(existing, block));
+    }
   } catch { /* best effort */ }
 }
 
@@ -604,12 +644,17 @@ export async function installCodexHooks(targetDir, packageDir) {
 }
 
 export async function removeCodexInstructions(targetDir) {
-  try {
-    await fs.unlink(path.join(targetDir, '.codex', 'AGENTS.md'));
-  } catch { /* already gone */ }
-  try {
-    await fs.unlink(path.join(targetDir, 'AGENTS.md'));
-  } catch { /* already gone */ }
+  for (const dest of [path.join(targetDir, '.codex', 'AGENTS.md'), path.join(targetDir, 'AGENTS.md')]) {
+    try {
+      const existing = await fs.readFile(dest, 'utf8');
+      const updated = removeMarkerBlock(existing);
+      if (updated.trim()) {
+        await fs.writeFile(dest, updated);
+      } else {
+        await fs.unlink(dest);
+      }
+    } catch { /* already gone */ }
+  }
 }
 
 export async function removeCodexHooks(targetDir) {