tutorial-updates

What this skill does

## Table of Contents

- [Overview](#overview)
- [Command Options](#command-options)
- [Required TodoWrite Items](#required-todowrite-items)
- [Phase 1: Discovery (`tutorial-updates:discovery`)](#phase-1:-discovery-(tutorial-updates:discovery))
- [Step 1.1: Locate Tutorial Assets](#step-11:-locate-tutorial-assets)
- [Step 1.2: Parse Manifests](#step-12:-parse-manifests)
- [Step 1.3: Handle Options](#step-13:-handle-options)
- [Phase 1.5: Validation (`tutorial-updates:validation`)](#phase-15:-validation-(tutorial-updates:validation))
- [Step 1.5.1: VHS Syntax Validation](#step-151:-vhs-syntax-validation)
- [Step 1.5.2: Extract and Validate CLI Commands](#step-152:-extract-and-validate-cli-commands)
- [Step 1.5.3: Verify Demo Data Exists](#step-153:-verify-demo-data-exists)
- [Step 1.5.4: Test Commands Locally](#step-154:-test-commands-locally)
- [Validation Flags](#validation-flags)
- [Validation Exit Criteria](#validation-exit-criteria)
- [Phase 1.6: Binary Rebuild (`tutorial-updates:rebuild`)](#phase-16:-binary-rebuild-(tutorial-updates:rebuild))
- [Step 1.6.1: Detect Build System](#step-161:-detect-build-system)
- [Step 1.6.2: Check Binary Freshness](#step-162:-check-binary-freshness)
- [Step 1.6.3: Rebuild Binary](#step-163:-rebuild-binary)
- [Step 1.6.4: Verify Binary Accessibility](#step-164:-verify-binary-accessibility)
- [Rebuild Flags](#rebuild-flags)
- [Rebuild Exit Criteria](#rebuild-exit-criteria)
- [Phase 2: Recording (`tutorial-updates:recording`)](#phase-2:-recording-(tutorial-updates:recording))
- [Step 2.1: Process Tape Components](#step-21:-process-tape-components)
- [Step 2.2: Process Browser Components](#step-22:-process-browser-components)
- [Step 2.3: Handle Multi-Component Tutorials](#step-23:-handle-multi-component-tutorials)
- [Phase 3: Generation (`tutorial-updates:generation`)](#phase-3:-generation-(tutorial-updates:generation))
- [Step 3.1: Parse Tape Annotations](#step-31:-parse-tape-annotations)
- [Step 3.2: Generate Dual-Tone Markdown](#step-32:-generate-dual-tone-markdown)
- [Step 3.3: Generate README Demo Section](#step-33:-generate-readme-demo-section)
- [Demos](#demos)
- [Quickstart](#quickstart)
- [Phase 4: Integration (`tutorial-updates:integration`)](#phase-4:-integration-(tutorial-updates:integration))
- [Step 4.1: Verify All Outputs](#step-41:-verify-all-outputs)
- [Step 4.2: Update SUMMARY.md (Book)](#step-42:-update-summarymd-(book))
- [Step 4.3: Report Results](#step-43:-report-results)
- [Exit Criteria](#exit-criteria)
- [Error Handling](#error-handling)
- [Scaffold Mode](#scaffold-mode)


# Tutorial Updates Skill

Orchestrate tutorial generation with GIF recordings from VHS tape files and Playwright browser specs.


## When To Use

- Generating or updating user-facing tutorials
- Creating VHS and Playwright tutorial recordings

## When NOT To Use

- Internal documentation without user-facing tutorials
- API reference docs - use scribe:doc-generator instead

## Overview

This skill coordinates the complete tutorial generation pipeline:

1. Discover tape files and manifests in the project
2. Validate tape commands and check binary freshness
3. Rebuild binaries if stale so demos reflect latest code
4. Record terminal sessions using VHS (scry:vhs-recording)
5. Record browser sessions using Playwright (scry:browser-recording)
6. Generate optimized GIFs (scry:gif-generation)
7. Compose multi-component tutorials (scry:media-composition)
8. Generate dual-tone markdown for docs/ and book/

## Command Options

```bash
/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
```
**Verification:** Run the command with `--help` flag to verify availability.

## Required TodoWrite Items

Create todos with these prefixes for progress tracking:

```
**Verification:** Run the command with `--help` flag to verify availability.
- tutorial-updates:discovery
- tutorial-updates:validation
- tutorial-updates:rebuild
- tutorial-updates:recording
- tutorial-updates:generation
- tutorial-updates:integration
```
**Verification:** Run the command with `--help` flag to verify availability.

## Phase 1: Discovery (`tutorial-updates:discovery`)

### Step 1.1: Locate Tutorial Assets

Find tape files and manifests in the project:

```bash
# Find manifest files
find . -name "*.manifest.yaml" -type f \
  -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
  -not -path "*/node_modules/*" -not -path "*/.git/*" \
  2>/dev/null | head -20

# Find tape files
find . -name "*.tape" -type f \
  -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
  -not -path "*/node_modules/*" -not -path "*/.git/*" \
  2>/dev/null | head -20

# Find browser specs
find . -name "*.spec.ts" -path "*/browser/*" -type f \
  -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
  -not -path "*/node_modules/*" -not -path "*/.git/*" \
  2>/dev/null | head -20
```
**Verification:** Run the command with `--help` flag to verify availability.

### Step 1.2: Parse Manifests

For each manifest file, extract:
- Tutorial name and title
- Component list (tape files, playwright specs)
- Output paths for GIFs
- Composition rules (layout, combine options)

See `modules/manifest-parsing.md` for manifest schema details.

### Step 1.3: Handle Options

| Option | Behavior |
|--------|----------|
| `--list` | Display discovered tutorials and exit |
| `--all` | Process all discovered manifests |
| `--scaffold` | Create directory structure and empty files without recording |
| `<names>` | Process only specified tutorials |

When `--list` is specified:
```
**Verification:** Run the command with `--help` flag to verify availability.
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
```
**Verification:** Run the command with `--help` flag to verify availability.

## Phase 1.5: Validation (`tutorial-updates:validation`)

**CRITICAL**: Validate tape commands BEFORE running VHS to avoid expensive regeneration cycles.

See `modules/tape-validation.md` for detailed validation logic.

### Step 1.5.1: VHS Syntax Validation

Check each tape file for valid VHS syntax:

```bash
# 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
```
**Verification:** Run the command with `--help` flag to verify availability.

### Step 1.5.2: Extract and Validate CLI Commands

For each `Type` directive, extract the command and validate flags:

```bash
# 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
```
**Verification:** Run the command with `--help` flag to verify availability.

### Step 1.5.3: Verify Demo Data Exists

If the tape uses demo data, verify it exists and is populated:

```bash
# Check SKRILLS_SKILL_DIR if set
skill_dir=$(grep '^Env SKRILLS_SKILL_DIR' "$tape_file" | sed 's/.*"\(.*\)"/\1/')
if [ -n "$skill_dir" ]; the