/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
estimated_tokens: 1100
progressive_loading: true
modules:
- modules/manifest-parsing.md
- modules/markdown-generation.md
- modules/tape-validation.md
- modules/binary-rebuild.md
dependencies:
- sanctum:git-workspace-review
- scry:vhs-recording
- scry:browser-recording
- scry:gif-generation
- scry:media-composition

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 Progress 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 (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.

Four checks run per tape: VHS syntax (an `Output` directive and balanced quotes), CLI flags in each `Type` command checked against `--help`, demo data present and populated, and each command run locally under a timeout to catch failures, empty output and hangs. The scripts and the validation exit criteria are in `modules/tape-validation.md`.

Validation Flags

| Flag | Behavior | |------|----------| | `--validate-only` | Run validation without generating GIF | | `--skip-validation` | Bypass validation for rapid regeneration |

**If validation fails**: Stop immediately, report errors, and do NOT proceed to VHS recording.

Phase 1.6: Binary Rebuild (`tutorial-updates:rebuild`)

**CRITICAL**: Ensure the binary being tested in tapes matches the latest source code. Stale binaries produce misleading demos.

Detect the build system (Cargo or Make), compare the binary's mtime with Git HEAD, rebuild when stale, then confirm the binary is on `PATH` and runs `--version`. The scripts, flags and rebuild exit criteria are in `modules/binary-rebuild.md`.

**If rebuild fails**: Stop immediately, report build errors, and do NOT proceed to tape validation or VHS recording.

Phase 2: Recording (`tutorial-updates:recording`)

Step 2.1: Process Tape Components

For each tape file component:

1. Parse tape file for metadata annotations (@step, @docs-brief, @book-detail) 2. Validate Output directive exists 3. Invoke `Skill(scry:vhs-recording)` with tape file path 4. Verify GIF output was created

Step 2.2: Process Browser Components

For each playwright spec component:

1. Ch