AFS Slide Builder setup instructions for Claude Code

CAMERAN_SLIDE_BUILDER_SETUP.md

AFS Slide Builder — Claude Code Setup Instructions

Cameran: paste this entire file into Claude Code and say "Run this setup." Claude will handle the rest.

---

For the Claude Code agent reading this:

You are setting up this machine to build AFS (AI Flight School) presentation decks. This involves installing several tools that work together: PresentationKit (slide builder CLI), claude-speak (local TTS audio engine), and Nano Banana (AI image generation via Google Gemini).

How to approach this setup

Be adaptive, not scripted. The steps below describe the target state, not a rigid script. This machine may differ from the reference environment. Before running any install step:

1. Probe first. Check what's already installed (which node, which python3, brew list, ls ~/Projects, etc.). Skip steps that are already satisfied. Don't reinstall things that are already present and working.
2. Adapt paths. The reference paths use ~/Projects/leegonzales/ but the user may prefer a different directory structure. Ask where they want repos cloned if the default doesn't exist yet.
3. Handle version differences. Node 18+ and Python 3.10+ are the minimum requirements. If the user has newer versions, that's fine. If they have older versions, help them upgrade.
4. Ask questions when uncertain. If something is ambiguous, blocked, or requires a choice, ask the user. Don't guess. Examples: "You have Python 3.9 installed. Should I install 3.11 alongside it or upgrade?" or "Homebrew isn't installed. Want me to install it?"
5. Diagnose failures. If a command fails, read the error, investigate, and fix it. Don't just retry. Common issues: permission problems, port conflicts, missing Xcode CLI tools, corporate proxy settings.
6. Report progress. After each major step, briefly confirm what succeeded and what's next.

Steps

Step 1: System Dependencies

First check what's already installed: which brew, which node, which python3, which ffmpeg, which espeak-ng. Only install what's missing.

If Homebrew is not installed, ask the user: "Homebrew (the macOS package manager) isn't installed. May I install it?" Then run /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)".

Install only the missing packages from this list:

brew install node python@3.11 ffmpeg imagemagick espeak-ng ghostscript fontconfig librsvg font-fira-code

Verify: node --version (must be 18+), python3 --version (must be 3.10+), ffmpeg -version, espeak-ng --help. If any version is below minimum, ask the user before upgrading.

Step 2: Clone Repos

ASK THE USER: "Where would you like me to clone the tool repos? The default is ~/Projects/leegonzales/. Is that okay, or do you prefer a different location?"

Use whatever path they choose. The three public repos to clone:

https://github.com/leegonzales/AISkills.git     → Contains PresentationKit + Nano Banana skill
https://github.com/leegonzales/claude-speak.git  → Local TTS audio engine
https://github.com/leegonzales/MCPServers.git    → Nano Banana MCP server

Check if any are already cloned at the target location. If so, git pull to update instead of re-cloning. Adjust all subsequent path references to match the actual clone location.

Step 3: Install PresentationKit

cd ~/Projects/leegonzales/AISkills/PresentationKit
npm install
npm run build
npm link

Verify: pk --version should return 0.1.0.

Step 4: Install Claude-Speak (Kokoro TTS)

IMPORTANT: This requires Apple Silicon (M1/M2/M3/M4) because the MLX audio framework only runs natively on ARM Macs. If the user is on Intel, stop and ask — we'll need to use ElevenLabs cloud TTS as an alternative (requires an ElevenLabs API key instead).

Check architecture first: uname -m (should return arm64).

cd {claude-speak-clone-path}
./install.sh

This creates a Python virtual environment, installs dependencies (including mlx-audio for Apple Silicon), and sets up the TTS daemon. If install.sh fails, read its error output — common issues are missing Xcode CLI tools (xcode-select --install) or Python version mismatches.

After install completes, start the daemon:

claude-speak-daemon start

Verify: claude-speak-client "Hello, this is a test" should generate and play audio. The first run downloads the Kokoro-82M model (~160MB from Hugging Face), so allow time for that. Tell the user it's downloading the model if it takes a while.

Step 5: Build Nano Banana MCP

cd ~/Projects/leegonzales/MCPServers/nanobanana-mcp
npm install
npm run build

Step 6: Install Nano Banana Skill

mkdir -p ~/.claude/commands
cp -r ~/Projects/leegonzales/AISkills/NanoBananaSkill/nano-banana ~/.claude/commands/

Step 7: Configure Nano Banana MCP in Claude Code Settings

ASK THE USER: "I need a Google Gemini API key to enable AI image generation. Do you already have one? If not, go to https://ai.google.dev/, sign in, click 'Get API key' → 'Create API key', and paste the key here."

Once you have the key, read ~/.claude/settings.json. Add (or merge into) the mcpServers object:

"nanobanana": {
  "command": "node",
  "args": ["FULL_PATH_TO/MCPServers/nanobanana-mcp/dist/index.js"],
  "env": {
    "GEMINI_API_KEY": "THE_KEY_FROM_USER"
  }
}

Replace FULL_PATH_TO with the actual absolute path to where the MCPServers repo was cloned in Step 2. Resolve via echo $HOME — never hardcode a username.

IMPORTANT: Do not overwrite existing settings. Read the file first, merge in the new mcpServers entry, and write back. Preserve all existing MCP servers, hooks, permissions, and other settings.

Step 8: Verify Full Stack

Run these checks and report results:

pk --version                        # Should return 0.1.0
claude-speak-client "Verification"  # Should play audio
node --version                      # Must be 18+
python3 --version                   # Must be 3.10+
ffmpeg -version                     # Must be installed
espeak-ng --help                    # Must be installed

After verification, tell the user: "Claude Code needs to be restarted for the Nano Banana MCP to become available. After restart, the gemini_generate_image tool will be accessible."

Step 9: Inform User of Capabilities

After setup is complete, tell the user:

"Setup complete. Your Claude Code can now:

1. Generate slide images — Use the nano-banana skill or gemini_generate_image tool to create LEGO-branded (or any style) slide images via Google Gemini.

2. Build presentations — Use pk build talk-track.md --output html to generate audio narration and HTML from a PresentationKit v5 talk track.

3. Create standalone decks — Use pk html talk-track.md --standalone --mp3-bitrate 96k to package everything (images + audio) into a single portable HTML file.

Available TTS voices: bf_emma (British female, our default), af_heart (American female), bm_george (British male), am_adam (American male).

The AFS style guide and slide templates are in the aitx-ai-flight-school repo under AFS_STYLE_GUIDE.md and templates/TEMPLATES.md."

---

Troubleshooting Reference

If pk is not found after install: run npm link again from ~/Projects/leegonzales/AISkills/PresentationKit.

If audio generation hangs: check claude-speak-daemon status, restart with claude-speak-daemon start.

If espeak-ng errors during TTS: run brew install espeak-ng.

If Kokoro model download fails: check internet connection. Model is ~160MB from Hugging Face.

If Nano Banana MCP is not available after restart: verify the path in ~/.claude/settings.json matches the actual install location and that npm run build completed without errors in the nanobanana-mcp directory.