@datajaddah/course 0.0.2

package/scaffold/.agents/skills/course-video-lessons/references/video-lessons.md

@@ -0,0 +1,83 @@
+# Video Lessons
+
+## Files
+
+Inside a video lesson:
+
+```text
+lesson.md
+video.md
+```
+
+`lesson.md` must contain:
+
+```md
+---
+kind: video
+title: "Lesson Title"
+---
+Optional lesson summary.
+```
+
+`video.md` must contain:
+
+```md
+---
+title: "Video Title"
+video_url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+---
+Optional learner notes, references, or follow-up prompts.
+```
+
+## Decision Rule
+
+- Use `video.md` only when the user already has a real external video URL or explicitly wants a standalone linked video lesson.
+- If the lesson is primarily an explanation of slides, author it as `slides` with `@script` instead.
+- Do not invent placeholder URLs. Validation rejects obvious placeholders such as `example.com` and `replace-me`.
+
+## Required Data
+
+- `video_url` is required.
+
+## Optional Data
+
+- `title`
+- markdown notes in the body
+
+## Platform Behavior
+
+- The platform stores one external `video_url` for the lesson resource.
+- The student app renders that URL directly as the video source.
+- Local preview can embed common YouTube URLs and can fall back to a plain video or link view depending on the URL.
+- This is the exception path for externally hosted videos. Most course explainer videos are created later on the platform from slide content plus narration audio.
+
+## Practical Guidance
+
+- Use stable, shareable URLs.
+- Use a real URL that already points to the intended video.
+- Keep notes learner-facing: what to watch for, what to do after the video, what to review.
+- Do not dump a transcript into `video.md` unless the user explicitly asks for that.
+- Prefer summaries, checkpoints, or references over repeating the entire video content.
+
+## Out Of Scope
+
+- uploaded binary video assets
+- platform rendering jobs
+- slide narration video generation
+- timing metadata
+
+## Example
+
+```md
+---
+title: "Build And Run The API"
+video_url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+---
+Watch this video before attempting the exercise.
+
+Focus on:
+
+- the environment variables that must exist
+- the order of the startup commands
+- the most common local setup failures
+```