@datajaddah/course 0.0.2

package/scaffold/.agents/skills/course-repo-contract/references/repo-contract.md

@@ -0,0 +1,169 @@
+# Repository Contract
+
+## Top-Level Shape
+
+```text
+.agents/
+  rules/
+    general.md
+  skills/
+    course-platform-overview/
+    course-repo-contract/
+    course-slides-v2/
+    course-video-lessons/
+    course-quizzes/
+    course-coding-exercises/
+    course-spreadsheet-labs/
+course.md
+chapters/
+  01-intro/
+    chapter.md
+    lessons/
+      01-welcome/
+        lesson.md
+        slides/
+          01-cover.md
+assets/
+```
+
+## Naming Rules
+
+- Ordered folders and files must use `NN-slug` names.
+- Ordering must be contiguous inside each folder.
+- Examples:
+  - `01-intro`
+  - `02-data-cleaning`
+  - `01-cover.md`
+  - `03-checkpoint-quiz`
+
+## Root Files
+
+### `course.md`
+
+Required frontmatter:
+
+- `schema_version: 1`
+- `title`
+
+Optional frontmatter:
+
+- `duration`
+- `tags`
+- `thumbnail`
+
+Body:
+
+- course overview markdown
+
+### `.agents/rules/general.md`
+
+- repository-local guidance for the AI working in this course repo
+
+### `.agents/skills/*`
+
+- detailed skill docs for resource-specific authoring
+
+## Chapter Contract
+
+Each chapter folder must contain:
+
+- `chapter.md`
+- `lessons/`
+
+`chapter.md` supports:
+
+- optional `title` frontmatter
+- markdown body for chapter summary
+
+## Lesson Contract
+
+Each lesson folder must contain:
+
+- `lesson.md`
+- exactly one resource location matching `lesson.md` frontmatter `kind`
+
+Allowed lesson kinds:
+
+- `slides`
+- `video`
+- `quiz`
+- `coding_exercise`
+- `spreadsheet_lab`
+
+`lesson.md` supports:
+
+- required `kind`
+- optional `title`
+- markdown body for lesson summary
+
+## Resource Locations
+
+### Slides
+
+- `slides/NN-slug.md`
+
+### Video
+
+- `video.md`
+- Use this only for standalone external videos with a real `video_url`.
+- Placeholder URLs such as `example.com` or `replace-me` are invalid.
+
+### Quiz
+
+- `quiz/quiz.md`
+- `quiz/questions/NN-slug.md`
+
+### Coding Exercise
+
+- `exercise/exercise.md`
+- exactly one `starter.*`
+- exactly one `solution.*`
+- `exercise.md` must contain `## Context` followed by `## Instructions`
+- coding exercise `language` must be `python` or `r`
+
+### Spreadsheet Lab
+
+- `spreadsheet/exercise.md`
+- `spreadsheet/workbook.json`
+- `spreadsheet/solution.json`
+- `spreadsheet/checks.json`
+- `exercise.md` must contain `## Context` followed by `## Instructions`
+- `engine` is optional (defaults to `univer`)
+
+## Validation Rules That Commonly Fail
+
+- missing required files
+- non-contiguous ordering
+- unsupported lesson `kind`
+- invalid frontmatter types
+- malformed quiz `@choice` blocks
+- quiz with no correct choice
+- slide with broken `@script` block
+- coding exercise missing `starter.*` or `solution.*`
+- coding exercise missing `## Context` or `## Instructions`
+- coding exercise language and file extension mismatch
+- spreadsheet lab missing `workbook.json`, `solution.json`, or `checks.json`
+- spreadsheet checks with invalid type or missing required fields
+- spreadsheet `exercise.md` missing `## Context` or `## Instructions`
+
+## Safe Editing Patterns
+
+- Rename or reorder only when the user explicitly asks.
+- When adding a new chapter or lesson, insert it with the next contiguous number.
+- Prefer updating existing files over creating alternative parallel files.
+- Keep learner content in markdown bodies, not in extra metadata fields.
+- Treat repository contract examples as authoring mechanics only. Keep learner-facing content on the requested course topic unless the user explicitly asks for repository-authoring instruction.
+
+## Final Check
+
+Run:
+
+```bash
+npx @datajaddah/course validate .
+```
+
+If the change affects learner-facing rendering, also run:
+
+```bash
+npx @datajaddah/course preview .
+```

package/scaffold/.agents/skills/course-slides-v2/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: course-slides-v2
+description: Author Datajaddah slides v2 lessons in a GitHub course repository. Use this skill when creating or editing slide lessons, slide decks, slide markdown, or narration scripts. This skill assumes the markdown-first repo contract and only the slides v2 model, not legacy slides v1 layouts.
+---
+
+# Course Slides V2
+
+Use this skill when the request is specifically about slide lessons, or when the lesson should later become a platform-rendered explainer video based on slides and narration.
+
+## Workflow
+
+1. Read `references/slides-v2.md`.
+2. Read `references/fit-guidance.md` when drafting or revising slide density.
+3. Ensure `lesson.md` declares `kind: slides`.
+4. Edit ordered slide markdown files inside `slides/`.
+5. Use the slide DSL for layout, image slots, and reveal steps when it improves the lesson.
+6. Keep visible slide content in markdown and narration in one optional `@script` block.
+7. Validate with `npx @datajaddah/course validate .`.
+
+## Boundaries
+
+- Author only slides v2 content.
+- Do not add legacy slides v1 fields such as `parts`, `layout`, or `hideTitle`.
+- Do not try to author audio blobs, timing metadata, or generated videos from the repo.
+- When no real external video URL exists yet, prefer slides plus `@script` over a standalone `video.md`.
+- Most slides should be concise, visual, and reveal-driven. Do not dump full narration into visible slide text.
+- Use `slot:` image references for planned visuals when the real uploaded asset does not exist yet.
+- Use block attrs like `{delay=2}` or `{highlight=2}` for full elements, and `==inline phrase=={highlight=2}` when only part of a sentence should reveal-highlight.

package/scaffold/.agents/skills/course-slides-v2/references/fit-guidance.md

@@ -0,0 +1,31 @@
+# Slide Fit Guidance
+
+Use this reference when drafting or revising slides.
+
+## Default Workflow
+
+1. Draft the slide around one teaching move, not the full narration.
+2. Use `@script` for explanation and transitions.
+3. Use reveal steps before adding more visible text:
+   - `delay` for staged appearance
+   - `highlight` for the active block
+4. Run validation and preview.
+5. If a slide still feels dense, split it into two slides instead of shrinking the idea into unreadable text.
+
+## Conservative Heuristics
+
+- Aim for one heading plus a short paragraph, or one heading plus 3 to 5 concise bullets.
+- In column layouts, keep each column lighter than a normal single-column slide.
+- Prefer one image plus one short text block over image + paragraph + long list in the same frame.
+- Code blocks should be short enough to read at presentation size; move explanation into `@script`.
+- If the slide needs several reveals, the final revealed state still has to fit in one 16:9 frame.
+
+## Split Triggers
+
+Split the slide when any of these are true:
+
+- the visible text reads like a script paragraph instead of slide copy
+- both columns need multiple paragraphs to make the point
+- the image would be too small to stay legible beside the text
+- the slide needs more than one code block or table
+- the slide would still feel crowded after adding reveal steps

package/scaffold/.agents/skills/course-slides-v2/references/slides-v2.md

@@ -0,0 +1,138 @@
+# Slides V2
+
+## Files
+
+Inside a slides lesson:
+
+```text
+lesson.md
+slides/
+  01-cover.md
+  02-overview.md
+  03-example.md
+```
+
+`lesson.md` must contain:
+
+```md
+---
+kind: slides
+title: "Lesson Title"
+---
+Optional lesson summary.
+```
+
+## Slide File Shape
+
+Each slide file is markdown with optional frontmatter:
+
+```md
+---
+title: "Slide Title"
+---
+# Visible slide content
+
+Optional markdown body.
+
+@script
+Optional Text for the narration for the presenter voiceover, this is what the presenter will say when they are presenting the slide.
+@endscript
+```
+
+## Slide DSL
+
+Use these directives only when they improve the slide:
+
+```md
+@layout: two-column
+
+@column: 1
+## Concept
+- Short point {delay=1}
+- Another point {delay=2 highlight=2}
+
+Use ==print()=={highlight=3} to call the function.
+
+@column: 2
+![Python logo](slot:python-logo "Add the official logo"){width=40% align=center}
+```
+
+- `@layout:` supports `default`, `two-column`, `sidebar-left`, and `sidebar-right`.
+- Non-default layouts must include exactly one `@column: 1` section and one `@column: 2` section.
+- Trailing `{delay=N highlight=N}` can be added to headings, paragraphs, list items, and standalone image lines.
+- Inline phrase highlights use `==selected text=={highlight=N}` and map to the slide viewer's inline reveal highlight.
+- Images can use a real URL or a planned image slot such as `slot:python-logo`.
+- Image attribute blocks can include `width=...`, `height=...`, and `align=left|center|right`.
+
+## What The Platform Does
+
+- The markdown body becomes slides v2 HTML content.
+- The optional `@script` block becomes narration text.
+- Slide content plus narration is the authorable input for the platform's slide-based video rendering flow.
+- Slide title comes from frontmatter or falls back to the filename slug.
+
+## What Not To Author In The Repo
+
+- `parts`
+- `layout`
+- `hideTitle`
+- `audioRef`
+- `audioData`
+- `stepMarkers`
+- generated video metadata
+
+Those are not part of the markdown repo contract.
+
+## Writing Guidance
+
+- One core idea per slide.
+- Prefer short headings and concise bullet lists.
+- Use examples, comparisons, and diagrams only when they sharpen the teaching point.
+- Keep on-slide text lighter than the spoken script.
+- Use the script to explain, transition, and add nuance instead of repeating the visible text verbatim.
+- If the lesson is meant to feel like an explainer video, put the spoken teaching detail in `@script` and keep the slide body concise.
+- Prefer this slides-plus-script pattern over `video.md` unless the user already has a real external video URL.
+- Prefer reveal steps over overcrowding: let `delay` and `highlight` stage the explanation instead of stacking every detail on screen at once.
+- Use block highlight for whole bullets or paragraphs, and inline highlight only for the exact term or phrase that should light up.
+- Use `slot:` image references only for planned visuals. Do not invent uploaded URLs.
+
+## Good Patterns
+
+- opener slide: topic, promise, why it matters
+- concept slide: definition plus one example
+- walkthrough slide: numbered steps
+- comparison slide: two options with tradeoffs
+- checkpoint slide: short recap or reflection prompt
+
+## Constraints
+
+- Exactly one optional `@script` block per slide file.
+- The slide body outside `@script` must remain valid markdown.
+- Keep slide filenames ordered and contiguous.
+- Keep non-default layouts one slide wide: do not mix freeform blocks above or below `@column` sections in the same slide file.
+
+## Example
+
+```md
+---
+title: "Event Loop Mental Model"
+---
+## Event Loop
+
+- Call stack runs synchronous work first
+- Queues hold deferred work
+- The loop keeps pulling the next runnable task
+
+@script
+Use this slide to replace vague intuition with a simple execution model. Emphasize that the event loop is about ordering work, not making JavaScript multithreaded.
+@endscript
+```
+
+## Validation Reminder
+
+After editing slides:
+
+```bash
+npx @datajaddah/course validate .
+npx @datajaddah/course preview .
+```

package/scaffold/.agents/skills/course-spreadsheet-labs/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: course-spreadsheet-labs
+description: Author Datajaddah spreadsheet lab lessons in a GitHub course repository. Use this skill when creating or editing spreadsheet exercises, workbook data, solution data, or check rules.
+---
+
+# Course Spreadsheet Labs
+
+Use this skill when the request is about hands-on spreadsheet lab exercises in the GitHub course repo.
+
+## Workflow
+
+1. Read `references/spreadsheet-labs.md`.
+2. Ensure `lesson.md` declares `kind: spreadsheet_lab`.
+3. Keep the prompt in `spreadsheet/exercise.md` with explicit `## Context` and `## Instructions` sections.
+4. Author starter data in `spreadsheet/workbook.json` and the expected answer in `spreadsheet/solution.json`.
+5. Define requirement checks in `spreadsheet/checks.json`.
+6. Validate with `npx @datajaddah/course validate .`.
+
+## Boundaries
+
+- Do not add application code or Univerjs configuration to the repo; the platform owns the spreadsheet runtime.
+- Keep the learner prompt in markdown and data in JSON files.
+- Keep exercises aligned with the requested lesson topic, not repository mechanics or platform workflows.

package/scaffold/.agents/skills/course-spreadsheet-labs/references/spreadsheet-labs.md

@@ -0,0 +1,239 @@
+# Spreadsheet Labs
+
+## Files
+
+Inside a spreadsheet lab lesson:
+
+```text
+lesson.md
+spreadsheet/
+  exercise.md
+  workbook.json
+  solution.json
+  checks.json
+```
+
+`lesson.md` must contain:
+
+```md
+---
+kind: spreadsheet_lab
+title: "Lesson Title"
+---
+Optional lesson summary.
+```
+
+`spreadsheet/exercise.md` must contain:
+
+```md
+---
+title: "Exercise Title"
+engine: "univer"
+---
+## Context
+
+Brief problem setup in markdown.
+
+## Instructions
+
+Exact task in markdown.
+```
+
+## Required Constraints
+
+- `exercise.md` must contain `## Context` followed by `## Instructions`.
+- `engine` is optional and defaults to `univer`.
+- All four files (`exercise.md`, `workbook.json`, `solution.json`, `checks.json`) are required.
+
+## Workbook and Solution Format
+
+Both `workbook.json` and `solution.json` use the same structure:
+
+```json
+{
+  "sheets": {
+    "SheetName": {
+      "name": "SheetName",
+      "cellData": {
+        "0": {
+          "0": { "v": "Header A" },
+          "1": { "v": "Header B" }
+        },
+        "1": {
+          "0": { "v": 100 },
+          "1": { "v": 200 }
+        }
+      }
+    }
+  }
+}
+```
+
+- `cellData` keys are zero-based row indexes, and nested keys are zero-based column indexes.
+- Each cell object may contain `v` (value), `f` (formula), `s` (style reference), or `t` (type).
+- `workbook.json` is the starter state the learner sees.
+- `solution.json` is the expected completed state.
+
+## Checks Format
+
+`checks.json` is a JSON array of check objects:
+
+```json
+[
+  {
+    "id": "total-revenue",
+    "label": "Total revenue is correct",
+    "type": "value_equals",
+    "cell": "D2",
+    "value": 42
+  }
+]
+```
+
+### Required Fields
+
+- `id` — unique string identifier for this check
+- `label` — human-readable description shown to the learner
+- `type` — one of the supported check types below
+- `cell` — cell reference like `A1`, `D2`, `B10`
+
+### Optional Fields
+
+- `sheet_name` — which sheet to check (defaults to the first sheet)
+- `formula` — expected formula string (for formula-based checks)
+- `details` — additional explanation shown on failure
+- `value` — expected value (for value-based checks)
+- `values` — array of acceptable values (for `one_of` checks)
+- `tolerance` — numeric tolerance (for `value_with_tolerance` checks)
+
+### Supported Check Types
+
+| Type | Purpose | Key Fields |
+|------|---------|------------|
+| `value_equals` | Cell value must equal expected value | `value` |
+| `text_equals` | Cell text must equal expected string | `value` |
+| `has_formula` | Cell must contain any formula | — |
+| `formula_equals` | Cell formula must match exactly | `formula` |
+| `one_of` | Cell value must be one of several options | `values` |
+| `value_with_tolerance` | Numeric value within tolerance | `value`, `tolerance` |
+
+## Platform Behavior
+
+- The platform renders spreadsheet labs using a Univerjs-powered spreadsheet component.
+- The learner sees `workbook.json` as the starting state and edits it in the browser.
+- Checks are evaluated against the learner's current spreadsheet state.
+- Requirements are displayed as a checklist the learner works through.
+- The solution workbook is available to the learner after submission or as a hint.
+
+## Writing Guidance
+
+- State the task in concrete, verifiable terms.
+- Pre-fill headers and static data in `workbook.json` so the learner focuses on the analytical task.
+- Keep checks focused on the learning objective, not formatting or cosmetics.
+- Make each check independently verifiable when possible.
+- Use `details` to give the learner a hint about what went wrong.
+- Keep the exercise on the requested lesson topic.
+
+## Example
+
+```md
+---
+title: "Revenue Summary"
+---
+## Context
+
+You have a spreadsheet with monthly revenue data for Q1.
+
+## Instructions
+
+- In cell `D2`, enter a SUM formula to calculate the total revenue for January through March.
+- Ensure the result equals `4500`.
+```
+
+Workbook example (`workbook.json`):
+
+```json
+{
+  "sheets": {
+    "Revenue": {
+      "name": "Revenue",
+      "cellData": {
+        "0": {
+          "0": { "v": "Month" },
+          "1": { "v": "Revenue" }
+        },
+        "1": {
+          "0": { "v": "January" },
+          "1": { "v": 1200 }
+        },
+        "2": {
+          "0": { "v": "February" },
+          "1": { "v": 1500 }
+        },
+        "3": {
+          "0": { "v": "March" },
+          "1": { "v": 1800 }
+        },
+        "4": {
+          "0": { "v": "Total" },
+          "1": {}
+        }
+      }
+    }
+  }
+}
+```
+
+Solution example (`solution.json`):
+
+```json
+{
+  "sheets": {
+    "Revenue": {
+      "name": "Revenue",
+      "cellData": {
+        "0": {
+          "0": { "v": "Month" },
+          "1": { "v": "Revenue" }
+        },
+        "1": {
+          "0": { "v": "January" },
+          "1": { "v": 1200 }
+        },
+        "2": {
+          "0": { "v": "February" },
+          "1": { "v": 1500 }
+        },
+        "3": {
+          "0": { "v": "March" },
+          "1": { "v": 1800 }
+        },
+        "4": {
+          "0": { "v": "Total" },
+          "1": { "v": 4500, "f": "=SUM(B2:B4)" }
+        }
+      }
+    }
+  }
+}
+```
+
+Checks example (`checks.json`):
+
+```json
+[
+  {
+    "id": "total-formula",
+    "label": "Total cell uses a SUM formula",
+    "type": "has_formula",
+    "cell": "B5"
+  },
+  {
+    "id": "total-value",
+    "label": "Total equals 4500",
+    "type": "value_equals",
+    "cell": "B5",
+    "value": 4500
+  }
+]
+```

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

@@ -0,0 +1,22 @@
+---
+name: course-video-lessons
+description: Author Datajaddah video lessons in a GitHub course repository. Use this skill when creating or editing lessons whose primary resource is a standalone externally hosted video with a real URL, including lesson summaries, video titles, URLs, and follow-up notes.
+---
+
+# Course Video Lessons
+
+Use this skill only when the lesson resource is a standalone external video that already exists or was explicitly requested.
+
+## Workflow
+
+1. Read `references/video-lessons.md`.
+2. If no real external video URL exists yet, use the slides skill instead and author `@script` for the platform video flow.
+3. Ensure `lesson.md` declares `kind: video`.
+4. Edit `video.md` for the video title, URL, and learner notes.
+5. Validate with `npx @datajaddah/course validate .`.
+
+## Boundaries
+
+- This skill is for lesson videos represented by `video.md`.
+- Generated videos attached to slide decks are platform-managed and are not authored here.
+- Do not invent placeholder URLs or create `video.md` just to stand in for a future slide-rendered video.