/tutorial-updates

name: tutorial-updates
description: Generates or updates tutorials from VHS tapes and Playwright specs with dual-tone markdown and GIF recording. Use when tutorial assets need refreshing.
alwaysApply: false
category: artifact-generation
tags:
- tutorial
- gif
- vhs
- playwright
- documentation
- demo
tools: []
complexity: high
model_hint: deep
estimated_tokens: 1100
progressive_loading: true
modules:
- modules/manifest-parsing.md
- modules/markdown-generation.md
- modules/tape-validation.md
dependencies:
- sanctum:git-workspace-review
- scry:vhs-recording
- scry:browser-recording
- scry:gif-generation
- scry:media-composition

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

/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:

# 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 (layou