Component Version Upgrade

Component Version Upgrade

Upgrade individual components of the TTS + Telegram bot stack without rebuilding the entire system.

Platform: macOS (Apple Silicon)

---

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

• User wants to upgrade Kokoro TTS engine, Python dependencies, or the model
• User wants to update bot dependencies (Bun packages)
• User wants to refresh tts_generate.py from the plugin bundle
• User wants to bump the Bun runtime version

---

Requirements

• uv installed (brew install uv)
• mise installed and configured
• Internet connectivity for package downloads
• Existing installation (run full-stack-bootstrap first if not installed)

---

Upgradeable Components

---

Workflow Phases

Phase 1: Component Selection

Ask the user which component to upgrade using AskUserQuestion. Present the four options above.

Phase 2: Pre-Upgrade Health Check

# Run health check to establish baseline
~/.local/share/kokoro/../../eon/cc-skills/plugins/tts-tg-sync/scripts/kokoro-install.sh --health

# Record current versions
cat ~/.local/share/kokoro/version.json

Phase 3: Execute Upgrade

Run the appropriate upgrade command for the selected component.

Phase 4: Post-Upgrade Verification

# Health check again
kokoro-install.sh --health

# Generate test audio to verify TTS still works
~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_generate.py \
  --text "Upgrade verification test" --voice af_heart --lang en-us --speed 1.0 \
  --output /tmp/kokoro-tts-upgrade-test.wav

Phase 5: Bot Restart (if needed)

If bot dependencies or Bun runtime were upgraded, restart the bot:

pkill -f 'bun.*src/main.ts' || true
cd ~/.claude/automation/claude-telegram-sync && bun --watch run src/main.ts

---

TodoWrite Task Templates

1. [Identify] Present upgradeable components via AskUserQuestion
2. [Preflight] Run health check on target component
3. [Backup] Note current versions (version.json, package.json)
4. [Upgrade] Execute upgrade command
5. [Verify] Run post-upgrade health check
6. [Test] Generate test audio to verify TTS still works
7. [Restart] Restart bot if needed
8. [Report] Show before/after versions

---

Post-Change Checklist

• [ ] Health check passes (all 6 checks OK)
• [ ] version.json updated with new versions
• [ ] Test audio generates and plays correctly
• [ ] Bot is running if it was restarted

Troubleshooting

---

Reference Documentation

• Upgrade Procedures -- Step-by-step upgrade instructions with rollback for each component
• Evolution Log -- Change history for this skill

Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. Locate yourself. — Find this SKILL.md's canonical path (Glob for this skill's name) before editing. All corrections target THIS file and its sibling references/ — never other documentation. 1. What failed? — Fix the instruction that caused it. If it could recur, add it as an anti-pattern. 2. What worked better than expected? — Promote it to recommended practice. Document why. 3. What drifted? — Any script, reference, or external dependency that no longer matches reality gets fixed now. 4. Log it. — Every change gets an evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.

---

---

component-version-upgrade Evolution Log

Upgrade Procedures

Detailed upgrade steps for each component of the TTS + Telegram bot stack.

---

Kokoro TTS Engine

The primary upgrade path. Updates Python dependencies, re-downloads the model, and writes a new version.json.

Upgrade Steps

# 1. Record current state
cat ~/.local/share/kokoro/version.json

# 2. Run health check (baseline)
~/.claude/eon/cc-skills/plugins/tts-tg-sync/scripts/kokoro-install.sh --health

# 3. Execute upgrade
~/.claude/eon/cc-skills/plugins/tts-tg-sync/scripts/kokoro-install.sh --upgrade

# 4. Verify
~/.claude/eon/cc-skills/plugins/tts-tg-sync/scripts/kokoro-install.sh --health
cat ~/.local/share/kokoro/version.json

What Gets Updated

• Python packages: mlx-audio, soundfile, numpy
• Model weights: re-downloaded from mlx-community/Kokoro-82M-bf16 (uses HuggingFace cache)
• kokoro_common.py and tts_generate.py: re-copied from plugin bundle to ~/.local/share/kokoro/
• version.json: rewritten with new versions and timestamp

Rollback

# If upgrade breaks TTS, do a clean reinstall:
~/.claude/eon/cc-skills/plugins/tts-tg-sync/scripts/kokoro-install.sh --uninstall
~/.claude/eon/cc-skills/plugins/tts-tg-sync/scripts/kokoro-install.sh --install

The model cache at ~/.cache/huggingface/hub/models--mlx-community--Kokoro-82M-bf16 is preserved across uninstall, so reinstall reuses the cached model.

---

Bot Dependencies (Bun Packages)

Updates the Telegram bot's npm dependencies.

Upgrade Steps

# 1. Record current state
cd ~/.claude/automation/claude-telegram-sync
cat package.json | grep -A 20 '"dependencies"'

# 2. Update packages
bun update

# 3. Verify lock file updated
git diff bun.lock

# 4. Restart bot
pkill -f 'bun.*src/main.ts' || true
bun --watch run src/main.ts

Rollback

# Restore previous lock file
cd ~/.claude/automation/claude-telegram-sync
git checkout bun.lock
bun install

---

tts_generate.py Script

Updates the TTS generation script from the plugin bundle without touching the venv.

Upgrade Steps

# 1. Compare current vs bundle
diff ~/.local/share/kokoro/tts_generate.py \
     ~/eon/cc-skills/plugins/tts-tg-sync/scripts/tts_generate.py

# 2. Copy from bundle
cp ~/eon/cc-skills/plugins/tts-tg-sync/scripts/tts_generate.py \
   ~/.local/share/kokoro/tts_generate.py

# 3. Verify
~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_generate.py \
  --text "Script update test" --voice af_heart --lang en-us --speed 1.0 \
  --output /tmp/kokoro-tts-test.wav && echo "OK" || echo "FAIL"

Rollback

The previous version is not automatically backed up. If the new script fails, use kokoro-install.sh --upgrade to re-copy from the bundle, or check git history in the cc-skills repo.

---

Bun Runtime

Updates the Bun version managed by mise.

Upgrade Steps

# 1. Check current version
bun --version

# 2. Update via mise
cd ~/.claude/automation/claude-telegram-sync
mise use bun@latest

# 3. Verify
bun --version

# 4. Reinstall deps with new Bun
bun install

# 5. Restart bot
pkill -f 'bun.*src/main.ts' || true
bun --watch run src/main.ts

Rollback

# Pin back to previous version (e.g., 1.3)
cd ~/.claude/automation/claude-telegram-sync
mise use bun@1.3
bun install

---

Version Tracking

After any upgrade, version.json at ~/.local/share/kokoro/ should reflect current state:

{
  "mlx_audio": "0.3.x",
  "backend": "mlx",
  "python": "3.14",
  "model": "mlx-community/Kokoro-82M-bf16",
  "upgraded_at": "2026-02-28T00:00:00Z",
  "source": "kokoro-install.sh --upgrade",
  "venv_path": "~/.local/share/kokoro/.venv"
}

For bot dependencies, the source of truth is ~/.claude/automation/claude-telegram-sync/package.json and bun.lock.