Merge Complete Module 1 ROS2 Foundations pull request #3 from mjunaidca/003-module-1-chapters

feat(content): Complete Module 1 ROS2 Foundations - 7 Chapters, 25 Lessons

Author: mjunaidca

.claude/agents/authoring/content-implementer.md

@@ -171,6 +171,60 @@ educational-validator runs 4 constitutional checks
 
 **Prevention**: This mandatory check ensures constitutional compliance BEFORE generation, not after.
 
+### Learning from Module 1 ROS 2 Implementation (2025-11-29)
+
+**Why this section exists**: Module 1 implementation required 8 file extension fixes, 10 mermaid removals, 3 MDX syntax corrections, and metadata standardization across 25 lessons.
+
+**Platform-Specific Failures Identified**:
+- 25 files used `.mdx` extension instead of `.md`
+- 8 files used `index.md` instead of `README.md`
+- 10 files contained Mermaid diagrams (plugin not installed)
+- 3 files had `<` characters in prose (MDX parsing errors)
+- 8 files used `cefr_level` instead of `proficiency_level`
+- 8 files used `duration` instead of `duration_minutes`
+- 12 files missing `id`, `sidebar_label`, or `description`
+
+**Root cause**: Agents generated content without following platform-specific Docusaurus conventions.
+
+**Prevention**: See Step 5 below - Docusaurus Platform Check.
+
+### Step 5: Docusaurus Platform Check (MANDATORY for RoboLearn)
+
+**Before creating ANY file**, verify:
+
+#### 5.1 File Naming
+- [ ] Extension is `.md` (NOT `.mdx`)
+- [ ] Index files named `README.md` (NOT `index.md`)
+- [ ] Lesson files use `NN-descriptive-name.md` pattern
+
+#### 5.2 MDX Syntax Safety
+- [ ] No `<` characters in prose (use "less than", "under")
+- [ ] No `>` characters in prose (use "more than", "over")
+- [ ] Comparison operators only inside code blocks
+
+#### 5.3 Diagram Constraints
+- [ ] NO Mermaid diagrams (plugin not configured)
+- [ ] Use ASCII text for simple diagrams
+- [ ] Use images for complex diagrams
+
+#### 5.4 Metadata Fields
+- [ ] `proficiency_level` (NOT `cefr_level`)
+- [ ] `duration_minutes` (NOT `duration` or `estimated_time`)
+- [ ] `id` unique and follows `lesson-{chapter}-{lesson}-{slug}` pattern
+- [ ] `sidebar_label` short and follows `"{C}.{L} {Title}"` pattern
+- [ ] `description` one-line for SEO
+- [ ] `skills` array populated
+- [ ] `hardware_tier` specified (1-4)
+
+#### 5.5 Internal Links
+- [ ] Use `.md` extension (NOT `.mdx`)
+- [ ] Use `README.md` (NOT `index.md`)
+- [ ] Relative paths from current file
+
+**Reference**: See `.claude/skills/authoring/docusaurus-conventions/SKILL.md` for complete guidelines.
+
+**Self-check**: Run `npm run build` after creating files. Expected: `[SUCCESS] Generated static files`
+
 ---
 
 ## II. Persona: Think Like Master Teacher + Curriculum Designer

.claude/skills/authoring/docusaurus-conventions/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: docusaurus-conventions
+description: Docusaurus file naming, syntax, and structure conventions for RoboLearn platform
+domain: authoring
+version: 1.0.0
+created: 2025-11-29
+triggers:
+  - Creating lesson files
+  - Creating module/chapter structure
+  - Writing MDX content
+  - Fixing Docusaurus build errors
+learned_from:
+  - Module 1 ROS 2 implementation (2025-11-29)
+  - 8 file extension fixes, 10 mermaid removals, 3 MDX syntax errors
+---
+
+# Docusaurus Conventions Skill
+
+## Persona
+
+Think like a Docusaurus expert who ensures all content builds successfully on the first attempt. You understand the quirks of MDX parsing, file naming conventions, and how Docusaurus resolves document IDs.
+
+---
+
+## Pre-Flight Questions
+
+Before creating or modifying any Docusaurus content, ask yourself:
+
+### 1. File Naming
+- **Q**: What file extension should I use?
+  - **A**: Always `.md` (NOT `.mdx`)
+  - **Why**: The project doesn't use MDX components; `.mdx` causes unnecessary complexity
+
+- **Q**: What should chapter/module index files be named?
+  - **A**: Always `README.md` (NOT `index.md`)
+  - **Why**: Docusaurus resolves `README.md` as the index; `index.md` can cause duplicate ID errors
+
+- **Q**: What naming pattern for lesson files?
+  - **A**: `NN-descriptive-name.md` (e.g., `01-digital-to-physical.md`)
+  - **Why**: Numeric prefix ensures correct ordering; descriptive name aids navigation
+
+### 2. MDX Syntax Safety
+- **Q**: Does my content contain `<` characters outside of code blocks?
+  - **A**: Replace with spelled-out alternatives
+  - **Examples**:
+    - `<2 seconds` → `less than 2 seconds`
+    - `<10 hours` → `under 10 hours`
+    - `[<10 hrs` → `[under 10 hrs`
+  - **Why**: MDX parser interprets `<` as JSX tag start, causing build errors
+
+- **Q**: Am I using comparison operators in prose?
+  - **A**: Use words instead of symbols
+  - **Examples**:
+    - `latency < 100ms` → `latency under 100ms` or use inline code: `latency < 100ms`
+    - `if (x < 5)` in code block is fine (code blocks are not parsed as MDX)
+
+### 3. Diagrams
+- **Q**: Am I using Mermaid diagrams?
+  - **A**: NO - Mermaid plugin is not configured
+  - **Alternatives**:
+    - ASCII text diagrams for simple flows
+    - Image files for complex diagrams
+    - Code blocks showing structure
+  - **Example replacement**:
+    ```
+    # Instead of mermaid:
+    ```mermaid
+    graph TD
+      A --> B
+    ```
+
+    # Use ASCII:
+    ```
+    A → B → C
+    └── D
+    ```
+    ```
+
+### 4. Internal Links
+- **Q**: How should I link to other lessons?
+  - **A**: Use relative paths with `.md` extension
+  - **Examples**:
+    - Same chapter: `[Next](./02-next-lesson.md)`
+    - Different chapter: `[Overview](../chapter-2-topic/README.md)`
+    - Module root: `[Module](../README.md)`
+  - **Never use**: `.mdx` extension or `index.md`
+
+---
+
+## Principles
+
+### Principle 1: Build-First Validation
+**Before committing any content, verify it builds.**
+
+```bash
+npm run build 2>&1 | tail -30
+```
+
+Expected: `[SUCCESS] Generated static files in "build"`
+
+If errors:
+1. Check for duplicate doc IDs (two files with same `id` frontmatter)
+2. Check for MDX syntax errors (unexpected character errors)
+3. Check for broken links (file not found warnings)
+
+### Principle 2: Consistent File Structure
+
+**Module structure:**
+```
+docs/module-N-name/
+├── README.md                    # Module overview (NOT index.md)
+├── chapter-1-topic/
+│   ├── README.md                # Chapter overview
+│   ├── 01-first-lesson.md
+│   ├── 02-second-lesson.md
+│   └── ...
+├── chapter-2-topic/
+│   └── ...
+└── ...
+```
+
+### Principle 3: Frontmatter ID Uniqueness
+
+**Every lesson must have unique `id`:**
+```yaml
+---
+id: lesson-1-1-digital-to-physical   # Unique across entire docs folder
+title: "Lesson 1.1: From ChatGPT to Walking Robots"
+---
+```
+
+**ID pattern**: `lesson-{chapter}-{lesson}-{slug}`
+- `lesson-1-1-digital-to-physical`
+- `lesson-3-2-turtlesim-action`
+- `custom-messages` (for standalone topics)
+
+### Principle 4: Safe Text Patterns
+
+**Avoid these patterns in prose (outside code blocks):**
+
+| Pattern | Problem | Solution |
+|---------|---------|----------|
+| `<N` | JSX parsing | `less than N`, `under N` |
+| `>N` | JSX parsing | `more than N`, `over N` |
+| `{var}` | JSX interpolation | Use code: `` `{var}` `` |
+| `<Component>` | JSX component | Use code or escape |
+
+**Safe in code blocks:**
+```python
+if x < 5:  # This is fine - inside code block
+    pass
+```
+
+---
+
+## Checklist (Use Before Every Lesson Creation)
+
+- [ ] File extension is `.md` (not `.mdx`)
+- [ ] Index files named `README.md` (not `index.md`)
+- [ ] Unique `id` in frontmatter
+- [ ] No `<` or `>` in prose outside code blocks
+- [ ] No Mermaid diagrams (use ASCII or images)
+- [ ] Internal links use `.md` extension
+- [ ] Internal links use `README.md` not `index.md`
+- [ ] Build passes: `npm run build`
+
+---
+
+## Recovery Patterns
+
+### Fix: Duplicate Doc ID Error
+```
+Error: The docs plugin found docs sharing the same id
+```
+**Solution**:
+1. Delete one of the duplicate files
+2. Or change the `id` in frontmatter to be unique
+
+### Fix: MDX Syntax Error
+```
+Unexpected character 'N' (U+004E) before name
+```
+**Solution**:
+1. Find the `<` character in prose
+2. Replace with word equivalent (`less than`, `under`)
+3. Or wrap in inline code
+
+### Fix: Mermaid Not Rendering
+**Solution**:
+1. Replace mermaid block with ASCII text diagram
+2. Or create image and reference it
+
+---
+
+## Version History
+
+| Version | Date | Change |
+|---------|------|--------|
+| 1.0.0 | 2025-11-29 | Initial skill from Module 1 lessons learned |