/update-tutorial quickstart        # Single tutorial by name
/update-tutorial sync mcp          # Multiple tutorials
/update-tutorial --all             # All tutorials with manifests
/update-tutorial --list            # Show available tutorials
/update-tutorial --scaffold        # Create structure without recording

- tutorial-updates:discovery
- tutorial-updates:validation
- tutorial-updates:rebuild
- tutorial-updates:recording
- tutorial-updates:generation
- tutorial-updates:integration

# Find manifest files
find . -name "*.manifest.yaml" -type f 2>/dev/null | head -20

# Find tape files
find . -name "*.tape" -type f 2>/dev/null | head -20

# Find browser specs
find . -name "*.spec.ts" -path "*/browser/*" -type f 2>/dev/null | head -20

Available tutorials:
  quickstart     assets/tapes/quickstart.tape
  sync           assets/tapes/sync.tape (manifest)
  mcp            assets/tapes/mcp.manifest.yaml (terminal + browser)
  skill-debug    assets/tapes/skill-debug.tape

# Required: Output directive exists
grep -q '^Output ' "$tape_file" || echo "ERROR: Missing Output directive"

# Check for balanced quotes in Type directives
grep '^Type ' "$tape_file" | while read -r line; do
  quote_count=$(echo "$line" | tr -cd '"' | wc -c)
  if [ $((quote_count % 2)) -ne 0 ]; then
    echo "ERROR: Unbalanced quotes: $line"
  fi
done

# Extract commands from Type directives
grep '^Type ' "$tape_file" | sed 's/^Type "//' | sed 's/"$//' | while read -r cmd; do
  # Skip comments, clear, and echo commands
  [[ "$cmd" =~ ^# ]] && continue
  [[ "$cmd" == "clear" ]] && continue

  # For skrills commands, validate flags exist
  if [[ "$cmd" =~ ^skrills ]]; then
    base_cmd=$(echo "$cmd" | awk '{print $1, $2}')
    flags=$(echo "$cmd" | grep -oE '\-\-[a-zA-Z0-9-]+' || true)

    for flag in $flags; do
      if ! $base_cmd --help 2>&1 | grep -q -- "$flag"; then
        echo "ERROR: Invalid flag '$flag' in command: $cmd"
      fi
    done
  fi
done

# Check SKRILLS_SKILL_DIR if set
skill_dir=$(grep '^Env SKRILLS_SKILL_DIR' "$tape_file" | sed 's/.*"\(.*\)"/\1/')
if [ -n "$skill_dir" ]; then
  if [ ! -d "$skill_dir" ]; then
    echo "ERROR: Demo skill directory missing: $skill_dir"
  else
    skill_count=$(find "$skill_dir" -name "SKILL.md" 2>/dev/null | wc -l)
    if [ "$skill_count" -eq 0 ]; then
      echo "ERROR: No skills in demo directory: $skill_dir"
    else
      echo "OK: Found $skill_count demo skills in $skill_dir"
    fi
  fi
fi

# For each command in the tape, do a quick sanity check
# This catches issues like:
# - Commands that exit with non-zero status
# - Commands that produce no output (won't show anything in GIF)
# - Commands that require user input (will hang VHS)

for cmd in $(extract_commands "$tape_file"); do
  # Run with timeout to catch hanging commands
  if ! timeout 5s bash -c "$cmd" &>/dev/null; then
    echo "WARNING: Command may fail or hang: $cmd"
  fi
done

# Check for Cargo (Rust)
if [ -f "Cargo.toml" ]; then
  BUILD_SYSTEM="cargo"
  BINARY_NAME=$(grep '^name = ' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
  echo "Detected Cargo project: $BINARY_NAME"
# Check for Makefile
elif [ -f "Makefile" ]; then
  BUILD_SYSTEM="make"
  echo "Detected Make project"
# Unknown
else
  echo "WARNING: Unknown build system, skipping binary check"
  BUILD_SYSTEM="unknown"
fi

check_binary_freshness() {
  local binary_name="$1"

  # Locate binary (check cargo install location first, then PATH)
  local binary_path=$(which "$binary_name" 2>/dev/null)

  if [ -z "$binary_path" ]; then
    echo "WARNING: Binary '$binary_name' not found in PATH"
    return 1
  fi

  # Get binary modification time (Linux/macOS compatible)
  local binary_mtime
  if command -v stat >/dev/null 2>&1; then
    # Linux
    binary_mtime=$(stat -c %Y "$binary_path" 2>/dev/null || \
    # macOS
    stat -f %m "$binary_path" 2>/dev/null)
  else
    echo "WARNING: stat command not available, skipping freshness check"
    return 2
  fi

  # Get Git HEAD commit time
  local git_head_time=$(git log -1 --format=%ct 2>/dev/null)

  if [ -z "$git_head_time" ]; then
    echo "WARNING: Not a git repository, skipping freshness check"
    return 2
  fi

  # Compare timestamps
  if [ "$binary_mtime" -lt "$git_head_time" ]; then
    echo "STALE: Binary is older than Git HEAD"
    echo "  Binary: $(date -d @$binary_mtime 2>/dev/null || date -r $binary_mtime)"
    echo "  HEAD:   $(date -d @$git_head_time 2>/dev/null || date -r $git_head_time)"
    return 1
  else
    echo "OK: Binary is up-to-date"
    return 0
  fi
}

rebuild_binary() {
  local build_system="$1"
  local binary_name="$2"

  case "$build_system" in
    cargo)
      echo "Rebuilding with Cargo..."
      # Use cargo install for CLI binaries
      if [ -d "crates/cli" ]; then
        cargo install --path crates/cli --locked --quiet
      else
        cargo install --path . --locked --quiet
      fi
      ;;
    make)
      echo "Rebuilding with Make..."
      make build --quiet
      ;;
    *)
      echo "ERROR: Cannot rebuild, unknown build system"
      return 1
      ;;
  esac

  echo "Build complete: $binary_name"
}

verify_binary() {
  local binary_name="$1"

  if ! command -v "$binary_name" >/dev/null 2>&1; then
    echo "ERROR: Binary '$binary_name' not found after rebuild"
    echo "  Check PATH includes: $HOME/.cargo/bin"
    return 1
  fi

  # Test binary can execute
  if ! "$binary_name" --version >/dev/null 2>&1; then
    echo "WARNING: Binary exists but --version failed"
  else
    echo "OK: Binary is accessible and functional"
    "$binary_name" --version
  fi
}

# @step Install skrills
# @docs-brief Install via cargo
# @book-detail The recommended installation method uses cargo...
Type "cargo install skrills"

## Demos

### Quickstart
![Quickstart demo](assets/gifs/quickstart.gif)
*Install, validate, analyze, and serve in under a minute. [Full tutorial](docs/tutorials/quickstart.md)*

# Check GIF files
for gif in assets/gifs/*.gif; do
  if [[ -f "$gif" ]]; then
    echo "OK: $gif ($(du -h "$gif" | cut -f1))"
  else
    echo "MISSING: $gif"
  fi
done

# Check markdown files
ls -la docs/tutorials/*.md 2>/dev/null
ls -la book/src/tutorials/*.md 2>/dev/null

- [Tutorials](./tutorials/README.md)
  - [Quickstart](./tutorials/quickstart.md)
  - [Sync Workflow](./tutorials/sync.md)
  - [MCP Integration](./tutorials/mcp.md)
  - [Skill Debugging](./tutorials/skill-debug.md)

Tutorial Update Complete
========================
Tutorials processed: 4
GIFs generated: 5
  - quickstart.gif (1.2MB)
  - sync.gif (980KB)
  - mcp-terminal.gif (1.5MB)
  - mcp-browser.gif (2.1MB)
  - skill-debug.gif (890KB)

Markdown generated:
  - docs/tutorials/ (4 files)
  - book/src/tutorials/ (4 files)

README demo section updated

# @title: Tutorial Name
# @description: Brief description of the tutorial

Output assets/gifs/tutorial-name.gif
Set FontSize 14
Set Width 1200
Set Height 600
Set Theme "Catppuccin Mocha"

# @step Step 1 Title
# @docs-brief Brief docs text
# @book-detail Extended book text with more context and explanation
Type "command here"
Enter
Sleep 2s