full-stack-bootstrap

Full Stack Bootstrap

One-time bootstrap of the entire TTS + Telegram bot stack: Kokoro TTS engine (MLX-Audio on Apple Silicon), Telegram bot via BotFather, secrets management, environment configuration, and shell symlinks.

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

• First-time setup of the tts-tg-sync plugin
• Reinstalling after a clean OS install or hardware migration
• Setting up a new machine with the full TTS + Telegram stack
• Recovering from a broken installation (run kokoro-install.sh --uninstall first)

Requirements

Workflow Phases

Phase 0: Preflight Check

Verify all prerequisites are installed and accessible:

command -v bun    # Bun runtime for TypeScript bot
command -v mise   # Environment manager
command -v uv     # Python package manager
uv python list | grep 3.14  # Python 3.14 available

If any tool is missing, install via Homebrew (brew install <tool>). Python 3.14 is installed via uv python install 3.14.

Phase 1: Kokoro TTS Engine Install

Run the bundled installer script:

bash scripts/kokoro-install.sh --install

This performs:

1. Requires Apple Silicon (fails fast on Intel/Linux)
2. Creates venv at ~/.local/share/kokoro/.venv with Python 3.14 via uv
3. Installs PyPI deps (mlx-audio, soundfile, numpy)
4. Copies kokoro_common.py and tts_generate.py from plugin bundle to ~/.local/share/kokoro/
5. Downloads Kokoro-82M-bf16 MLX model from HuggingFace (mlx-community/Kokoro-82M-bf16)
6. Writes version.json with mlx_audio version, backend, and model ID

Phase 2: BotFather Token Setup

Guide the user through Telegram BotFather to create a bot token:

1. Open Telegram, search for @BotFather
2. Send /newbot, follow prompts (name + username)
3. Copy the HTTP API token
4. Verify token: curl -s "https://api.telegram.org/bot<TOKEN>/getMe" | jq .ok
5. Get chat_id by sending a message to the bot, then: curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates" | jq '.result[0].message.chat.id'

If a token already exists at ~/.claude/.secrets/ccterrybot-telegram, verify it works and skip this phase.

Phase 3: Secrets Storage

Store the bot token securely:

mkdir -p ~/.claude/.secrets
chmod 700 ~/.claude/.secrets
echo "BOT_TOKEN=<token>" > ~/.claude/.secrets/ccterrybot-telegram
echo "CHAT_ID=<chat_id>" >> ~/.claude/.secrets/ccterrybot-telegram
chmod 600 ~/.claude/.secrets/ccterrybot-telegram

Create .mise.local.toml (gitignored) in the bot directory to load secrets:

# ~/.claude/automation/claude-telegram-sync/.mise.local.toml
[env]
_.file = "{{env.HOME}}/.claude/.secrets/ccterrybot-telegram"

Phase 4: Environment Configuration

Add Kokoro paths to mise.toml:

# In ~/.claude/automation/claude-telegram-sync/mise.toml [env] section
KOKORO_VENV = "{{env.HOME}}/.local/share/kokoro/.venv"
KOKORO_SCRIPT = "{{env.HOME}}/.local/share/kokoro/tts_generate.py"

Phase 5: Shell Symlinks

Create symlinks in ~/.local/bin/ pointing to plugin shell scripts:

mkdir -p ~/.local/bin
ln -sf <plugin>/scripts/tts_kokoro.sh ~/.local/bin/tts_kokoro.sh
ln -sf <plugin>/scripts/tts_read_clipboard.sh ~/.local/bin/tts_read_clipboard.sh
ln -sf <plugin>/scripts/tts_read_clipboard_wrapper.sh ~/.local/bin/tts_read_clipboard_wrapper.sh
ln -sf <plugin>/scripts/tts_speed_up.sh ~/.local/bin/tts_speed_up.sh
ln -sf <plugin>/scripts/tts_speed_down.sh ~/.local/bin/tts_speed_down.sh
ln -sf <plugin>/scripts/tts_speed_reset.sh ~/.local/bin/tts_speed_reset.sh

Phase 6: Verification

1. Generate a test WAV and play it:

~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_generate.py \
    --text "Hello, bootstrap complete." --voice af_heart --lang en-us --speed 1.0 --output /tmp/test-bootstrap.wav
afplay /tmp/test-bootstrap.wav
rm -f /tmp/test-bootstrap.wav

1. Verify bot responds to /status via Telegram API:

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/getMe" | jq .ok

TodoWrite Task Templates

Template: Full Stack Bootstrap

1. [Preflight] Verify Bun installed
2. [Preflight] Verify mise installed
3. [Preflight] Verify uv installed
4. [Preflight] Verify Python 3.14 available via uv
5. [Kokoro] Run kokoro-install.sh --install
6. [Kokoro] Verify MLX-Audio acceleration
7. [BotFather] Guide BotFather token creation (or verify existing)
8. [Secrets] Store token in ~/.claude/.secrets/ccterrybot-telegram
9. [Secrets] Create .mise.local.toml with _.file reference to secrets
10. [Environment] Add KOKORO_VENV and KOKORO_SCRIPT to mise.toml
11. [Symlinks] Create ~/.local/bin/ symlinks for all TTS shell scripts
12. [Verify] Generate test WAV with Kokoro and play with afplay
13. [Verify] Check bot responds to /status via Telegram API

Post-Change Checklist

After modifying this skill:

1. Verify kokoro-install.sh --health passes all 6 checks
2. Confirm .mise.local.toml is gitignored
3. Test symlinks resolve correctly (ls -la ~/.local/bin/tts_*.sh)
4. Verify bot token works via getMe API call
5. Run a full TTS round-trip: clipboard text to audio playback
6. Update references/evolution-log.md with change description

Troubleshooting

Reference Documentation

• Kokoro Bootstrap - Detailed venv setup, Python 3.14 via uv, MLX-Audio, model download
• BotFather Guide - Step-by-step Telegram bot creation and token management
• Upstream Fork - MLX-Audio Kokoro upstream and bundled script rationale
• 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.