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

Component	Required	Installation
Bun	Yes	brew install oven-sh/bun/bun
mise	Yes	brew install mise
uv	Yes	brew install uv
Python 3.14	Yes	uv python install 3.14
Homebrew	Yes	Already installed on macOS dev machines
Apple Silicon (M1+)	Yes	Required for MLX Metal acceleration

---

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

<!-- SSoT-OK: kokoro-install.sh is the SSoT for versions and deps -->

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

Issue	Cause	Solution
uv not found	Not installed	brew install uv
Python 3.14 not available	Not installed via uv	uv python install 3.14
Not Apple Silicon	Intel Mac or Linux	Requires M1 or newer Mac (MLX Metal)
Model download fails	Network issue or HuggingFace outage	Check internet connectivity, retry
BotFather token invalid	Typo or revoked token	Verify via curl https://api.telegram.org/bot<TOKEN>/getMe
kokoro-install.sh permission denied	Script not executable	chmod +x scripts/kokoro-install.sh
Venv already exists	Previous partial install	Run kokoro-install.sh --uninstall then --install
tts_generate.py not found	Bundle copy failed	Check scripts/tts_generate.py exists in plugin

---

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.

---

---