Component Version Upgrade

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

Platform: macOS (Apple Silicon)

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

Component Command What It Does

Kokoro TTS engine kokoro-install.sh --upgrade

Upgrades Python deps, re-downloads model, updates version.json

Bot dependencies cd ~/.claude/automation/claude-telegram-sync && bun update

Updates Bun packages per package.json

tts_generate.py Re-copy from plugin scripts/ to ~/.local/share/kokoro/

Updates the TTS generation script

Bun runtime mise use bun@latest

Updates the Bun version in mise.toml

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-telegram-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

Problem Likely Cause Fix

Upgrade fails No internet or PyPI issue Check connectivity, retry

Model download slow First-time ~400MB, subsequent cached Wait for download to complete

Version mismatch Stale version.json Re-run kokoro-install.sh --health to check, --upgrade to fix

MLX-Audio import fails mlx-audio version incompatibility kokoro-install.sh --upgrade reinstalls mlx-audio

Bot won't start after upgrade Dependency conflict cd ~/.claude/automation/claude-telegram-sync && bun install

Reference Documentation

• Upgrade Procedures -- Step-by-step upgrade instructions with rollback for each component

• Evolution Log -- Change history for this skill