@thanh01.pmt/curriculum-kit 1.4.41 → 1.4.43

package/dist/templates/HANDOUT_template.md

@@ -0,0 +1,61 @@
+---
+id: "{{ID}}"
+title: "{{TITLE}}"
+type: "HANDOUT"
+created_by: "Curriculum OS Builder"
+phase: "{{PHASE}}"
+deliverable: "P3-T6"
+version: "{{VERSION}}"
+date: "{{DATE}}"
+template_contract: "artifact-template-v1"
+template_required_sections:
+  - "Core Concepts"
+  - "Core Syntax & Mechanism Cheat Sheet"
+  - "Visual Mental Model / Architecture Diagram"
+  - "Step-by-Step Practical Quick-Start Guide"
+  - "Self-Check Diagnostic Checklist"
+---
+
+# HANDOUT: [LESSON TITLE]
+_Student Reference Notes — keep beside you during the lesson._
+
+## [REQUIRED] 📖 Core Concepts
+> Key terms and student-friendly definitions. Source term definitions from the
+> canonical knowledge context (KX Key Terms) — align, don't re-invent.
+
+| Term | Definition (student-friendly) | Example |
+|---|---|---|
+| [Term 1] | [Plain-language explanation] | [Micro example] |
+
+## [REQUIRED] Core Syntax & Mechanism Cheat Sheet
+> Quick-scan reference table for the exact syntax/mechanics this lesson uses.
+
+| Pattern | Syntax | When to Use | Common Trap |
+|---|---|---|---|
+| [Pattern] | `[exact syntax]` | [Situation] | [Pitfall from KX] |
+
+## [REQUIRED] Visual Mental Model / Architecture Diagram
+> One Mermaid or ASCII diagram of the core mechanism, annotated.
+
+```mermaid
+graph LR
+  A[[Component 1]] --> B[[Component 2]]
+  B --> C[[Component 3]]
+```
+
+- **How to read it:** [One-paragraph walkthrough of the diagram]
+
+## [REQUIRED] Step-by-Step Practical Quick-Start Guide
+> Minimum path to a first working result, numbered, with checkpoints.
+
+1. [Step 1 — concrete action]
+   - ✅ Checkpoint: [What you should see]
+2. [Step 2]
+   - ✅ Checkpoint: [What you should see]
+
+## [REQUIRED] Self-Check Diagnostic Checklist
+> Can-do statements for self-assessment, mirroring LESSON LO evidence.
+
+- [ ] I can [can-do statement tied to LO1]
+- [ ] I can [can-do statement tied to LO2]
+- [ ] I can [can-do statement tied to LO3]

package/dist/templates/HANDOVER_DOCUMENT_template.md

@@ -0,0 +1,69 @@
+---
+id: "{{ID}}"
+title: "{{TITLE}}"
+type: "HANDOVER_DOCUMENT"
+created_by: "Curriculum OS Builder"
+phase: "{{PHASE}}"
+deliverable: "{{DELIVERABLE_CODE}}"
+version: "{{VERSION}}"
+date: "{{DATE}}"
+---
+
+# CURRICULUM HANDOVER DOCUMENT
+_Handover Date: [YYYY-MM-DD] | Version: v[X.X]_
+
+## 1. Handover Information
+- **Receiving Entity (Client):** [School / Center Name]
+- **Course Name:** [Full Course Title]
+- **Project ID:** [PRJ-CODE]
+- **Target Audience:** [Age Group, Grade]
+
+---
+
+## 2. Deliverables Inventory
+_The curriculum suite is packaged into 4 modules (Packages) tailored for different stakeholders:_
+
+| Package | Content Description | File Qty | Format |
+|---|---|:---:|:---:|
+| **1. Teacher Package** | Detailed Lesson Plans, Activity Guides, Answer Keys, Assessment Rubrics, Pedagogical Notes. | [X] | PDF / DOCX |
+| **2. Student Package** | Learning Workbook, Step-by-step assembly/coding guides, Cheat sheets. | [X] | PDF |
+| **3. Parent Package** | Course goal summary, sample progress reports, home engagement guides. | [X] | PDF |
+| **4. Client/Manager Package** | Syllabus/Framework, Standards Alignment Reports, Hardware/Inventory list. | [X] | PDF / DOCX |
+
+---
+
+## 3. Commitment vs. Reality Check
+| Commitment Item | Actual Delivery | Status |
+|---|---|---|
+| Total Lessons: [X] | Delivered [X] lessons | ✅ Met |
+| Duration: [Y] mins/lesson | Designed [Y] mins/lesson | ✅ Met |
+| Standards Alignment | Meets [Z/W] criteria | See Standards Report |
+
+---
+
+## 4. Scope Exclusions
+_This handover **DOES NOT** include the following items unless specified in a separate agreement:_
+- Provision of hardware equipment, components, or software licenses.
+- Direct Train-The-Trainer (TTT) sessions.
+- Physical printing of materials.
+- Integration into the school's LMS (Learning Management System).
+
+---
+
+## 5. Getting Started Guide
+To implement the curriculum effectively, please follow this sequence:
+1. **Academic Manager:** Review the *Syllabus (Client Package)* to schedule classes and procure hardware.
+2. **Classroom Teacher:** Read the *Lesson Plans (Teacher Package)* from start to finish. Print a sample *Workbook (Student Package)* for reference.
+3. **Pre-launch:** Send the *Course Summary (Parent Package)* to parents.
+
+---
+
+## 6. Post-Handover Support Policy
+- **Support Period:** 30 days from the date of this handover (Until: [YYYY-MM-DD]).
+- **Support Scope:** Clarification on lesson content, fixing technical errors in documents (typos, diagram errors, source code bugs).
+- **Contact Channel:** [Email / Support Phone Number]
+- **Committed Response Time (SLA):** Within [X] working hours.
+
+_Handover Confirmation:_
+**REPRESENTING PROVIDER**                   **REPRESENTING CLIENT**
+(Signature & Full Name)                      (Signature & Full Name)

package/dist/templates/KNOWLEDGE_EXPOSITION_template.md

@@ -0,0 +1,56 @@
+# KNOWLEDGE_EXPOSITION: {{lesson_code}} — {{session_title}}
+
+---
+type: "KNOWLEDGE_EXPOSITION"
+lesson_code: "{{lesson_code}}"
+plan_hash: "{{plan_hash}}"
+generated_at: "{{generated_at}}"
+template_contract: "knowledge-exposition-v1"
+---
+
+_Self-study reference for session {{lesson_code}}. Read this before the activities.
+Scope: exactly the knowledge planned for this session — no more, no less._
+
+## [REQUIRED] Session Scope
+
+- **Objective:** {{prose_objective}}
+- **New keywords:** {{new_keywords}}
+- **Assumed known:** {{prerequisite_keywords}}
+- **Depth targets:** {{depth_targets}}
+- **You can demonstrate, after this session:** {{exit_evidence}}
+
+## [REQUIRED] Key Terms
+
+<!-- One block per term in glossary scope. Definitions MUST match GLOSSARY.json. -->
+
+{{key_terms}}
+
+## [REQUIRED] Concept Narratives
+
+<!-- One subsection per concept node in session scope, sized to its depth assignment:
+     - ulo: WHAT + WHY (technology-independent, what it is and why it exists)
+     - cio: HOW (the mechanism, how it works step by step)
+     - sio: SPECIFIC (concrete implementations, real keyword usage in this project)
+     Written for the STUDENT (self-study, no teacher). No teacher-only instructions. -->
+
+{{concept_narratives}}
+
+## [REQUIRED] Worked Micro-Examples
+
+<!-- Minimal examples traceable to references from the domain graph. -->
+
+{{worked_examples}}
+
+## [REQUIRED] Common Mistakes
+
+{{common_mistakes}}
+
+## [REQUIRED] Self-Check Questions
+
+<!-- 3-5 questions mapped to exit evidence. Answers at the very end. -->
+
+{{self_check}}
+
+---
+- **Plan reference:** {{plan_hash}}
+- **Last Updated:** {{generated_at}}

package/dist/templates/LEARNER_PROFILE_template.md

@@ -0,0 +1,51 @@
+---
+id: "{{ID}}"
+title: "{{TITLE}}"
+type: "LEARNER_PROFILE"
+created_by: "Curriculum OS Builder"
+phase: "{{PHASE}}"
+deliverable: "P1-T1"
+version: "{{VERSION}}"
+date: "{{DATE}}"
+template_contract: "artifact-template-v1"
+template_required_sections:
+  - "Foundational Info"
+  - "Entry Level"
+  - "Learning Context"
+  - "Client Objectives"
+---
+
+# LEARNER PROFILE
+
+
+## [REQUIRED] Foundational Info
+- **Age Group:** [Specific age range, e.g., 11–13 years old]
+- **Grade Level:** [E.g., Middle School / High School]
+- **Typical Class Size:** [Number of students]
+- **Learning Context:** [E.g., Public School / Coding Center / Workshop]
+
+## [REQUIRED] Entry Level
+- **Coding Experience:** [None / Basic / Intermediate / Advanced]
+- **Hardware Experience:** [None / Basic / Intermediate / Advanced]
+- **Related Prior Courses:** [List specific courses or "None"]
+
+## [REQUIRED] Learning Context
+- **Session Duration:** [Minutes]
+- **Total Sessions:** [Number]
+- **Frequency:** [E.g., 2 sessions/week]
+- **Student Equipment:** [E.g., Personal Laptop / Lab PC / Tablet]
+- **Internet Connectivity:** [Stable / Unstable / None]
+
+## [REQUIRED] Client Objectives
+- **Core Goal:** [What the client wants students to achieve - max 3 points]
+- **Standard Alignment:** [E.g., CSTA / K12 CS Framework / Local Standards]
+
+## [OPTIONAL] Student Characteristics
+- **Motivation:** [Brief description]
+- **Potential Barriers:** [Brief description]
+- **Strengths to Leverage:** [Brief description]
+
+## [OPTIONAL] Special Constraints
+- **Hardware Budget:** [Budget per student or "None"]
+- **Language Requirements:** [E.g., Bilingual English-Vietnamese]
+- **Other Client Requests:** [Description or "None"]

package/dist/templates/LESSONS_LEARNED_template.md

@@ -0,0 +1,49 @@
+---
+id: "{{ID}}"
+title: "{{TITLE}}"
+type: "LESSONS_LEARNED"
+created_by: "Curriculum OS Builder"
+phase: "{{PHASE}}"
+deliverable: "{{DELIVERABLE_CODE}}"
+version: "{{VERSION}}"
+date: "{{DATE}}"
+---
+
+# PROJECT LESSONS LEARNED
+
+_Rule: This file MUST be uploaded to NotebookLM NB-4 (Institutional Memory) after the Handover._
+
+## 1. Project Metadata
+- **Course Name:** [Name]
+- **Client / Audience:** [Client Name / Student Age]
+- **Deployment Period:** [Start Date] ➔ [End Date]
+- **Key Performance Metrics:**
+  - Total Lessons: [X]
+  - Average Revision Count (ARC) per lesson: [Y] (Target < 1.5)
+  - Severe Errors (Escalations): [Z]
+
+---
+
+## 2. What Worked Well (Successes)
+_Record formats, examples, or workflows that were highly effective for future reuse. MUST be specific._
+- [E.g., Using the 5E model for Circuitry helped Grade 5 students discover LED connections more intuitively than a theory-first lecture.]
+- [E.g., Batching Metered Execution into 2-lesson sets allowed for early tone correction, saving 40% of revision time.]
+
+## 3. What Didn't Work (Failures/Bottlenecks)
+_Record bottlenecks and reasons for failure. Avoid vague statements._
+- [E.g., The RUBRIC template was too complex for Elementary students; they couldn't use it for self-assessment.]
+- [E.g., @activity frequently proposed components not available in the Learner Profile due to lack of cross-checking.]
+
+## 4. Key Design Decisions (Architecture Log)
+_Record the "WHY" behind critical architecture choices to prevent future questioning of established patterns._
+- [E.g., Chose Arduino Uno over micro:bit because the client's budget was strictly $5/kit, despite micro:bit being easier to teach.]
+- [E.g., Moved the Python Programming module to the end of the course because students needed to master logic via Scratch drag-and-drop first.]
+
+## 5. Actionable Improvements for Future Projects
+_SPECIFIC actions to update the Curriculum OS._
+- **Template Updates:** [E.g., Need to simplify `RUBRIC_template.md` for Elementary audiences.]
+- **Rule Updates:** [E.g., Add a rule forcing `@activity` to re-read the component list in `CONTENT_CONTINUITY` before starting a new lesson.]
+
+## 6. Open Questions / Post-Deployment Monitoring
+_Uncertainties requiring follow-up after a few months of client operation._
+- [E.g., Is the 90-minute duration too long for Grade 3 attention spans? Need to check with teachers after 2 months.]

package/dist/templates/LESSON_5E_template.md

@@ -0,0 +1,127 @@
+---
+id: "{{ID}}"
+title: "{{TITLE}}"
+type: "LESSON_5E"
+created_by: "Curriculum OS Builder"
+phase: "{{PHASE}}"
+deliverable: "P3-T1"
+version: "{{VERSION}}"
+date: "{{DATE}}"
+prerequisite: []
+template_contract: "lesson-plan-v2"
+template_required_sections:
+  - "A. Lesson Design Plan"
+  - "Learning Objectives & Evidence"
+  - "Activity Sequence"
+  - "Resource Map"
+  - "Assessment Map"
+  - "Artifact Contract"
+  - "B. Lesson Flow"
+  - "Artifact Linkage"
+---
+<!-- INJECT_BODY -->
+
+# LESSON [XX]: [LESSON TITLE] (5E Model)
+
+## [REQUIRED] A. Lesson Design Plan
+
+> OWNERSHIP: Each fact lives in exactly ONE section. The Artifact Contract
+> column (row 11) of the Activity Sequence is the single owner of which
+> satellite produces what. Resource Map lists ONLY physical/logistical
+> resources (hardware, accounts, printed material) — do not re-list satellite
+> artifacts there. Artifact Contract (§5) and Artifact Linkage name satellites
+> by filename + one-line role, no repeated descriptions. Lesson Flow
+> references activities by Seq number — never embed question banks or
+> self-check text owned by KX/QUIZ.
+
+### 1. Learning Objectives & Evidence
+- **Estimated Duration:** [X minutes]
+- **Materials & Equipment:** [List hardware and software]
+- **Keywords / Core Concepts:** [Keyword 1], [Keyword 2]
+
+| LO | Objective (Bloom's) | Student Evidence | Success Criteria |
+|---|---|---|---|
+| LO1 | **[Bloom Verb]** [Content] | [Observable output/action] | [Measurable condition] |
+| LO2 | **[Bloom Verb]** [Content] | [Observable output/action] | [Measurable condition] |
+
+### 2. Activity Sequence
+> This is the canonical activity contract. Satellite artifacts must expand this sequence and must not invent a different one.
+
+| Seq | 5E Phase | Activity Type | Actor | Purpose | Student Action | Teacher Move | Output/Evidence | LO | Time | Artifact Contract |
+|---|---|---|---|---|---|---|---|---|---|---|
+| 1 | Engage | Hook / Discussion | Teacher + Students | [Why this opens the lesson] | [What students do] | [Prompt/facilitation move] | [Evidence/checkpoint] | LO1 | [X mins] | SLIDE/HANDOUT |
+| 2 | Explore | Exploration / Demo | Students | [What students discover] | [What students try/observe] | [How teacher guides without overexplaining] | [Evidence/checkpoint] | LO1 | [X mins] | ACT/WKS |
+| 3 | Explain | Mini Lesson | Teacher + Students | [Concept to formalize] | [What students annotate/answer] | [Explanation/demo] | [Evidence/checkpoint] | LO1, LO2 | [X mins] | SLIDE/HANDOUT |
+| 4 | Elaborate | Practice / Lab | Students | [Main application] | [What students build/solve] | [Coaching/debugging] | [Main evidence] | LO2 | [X mins] | ACT/CODE_LAB/WKS |
+| 5 | Evaluate | Reflection / Check | Students | [Mastery check] | [Exit response/demo] | [Debrief] | [Assessment evidence] | LO1, LO2 | [X mins] | QUIZ |
+
+### 3. Resource Map
+| Resource | Used In Activity | Purpose | Owner Artifact |
+|---|---|---|---|
+| [Slide / handout / code template / hardware] | [Seq #] | [Why needed] | [SLIDE/HANDOUT/ACT/CODE_LAB/BOM] |
+
+### 4. Assessment Map
+| Evidence | Assessed By | Criteria | Follow-up If Missing |
+|---|---|---|---|
+| [Student output] | [Exit ticket / rubric / quiz item] | [Criteria] | [Reteach/retry action] |
+
+### 5. Artifact Contract
+- **ACT must expand:** [Seq numbers and details to operationalize]
+- **GUIDE must support:** [Teacher moves and facilitation risks from the activity sequence]
+- **SLIDE must visualize:** [Key concepts, checkpoints, and transitions]
+- **HANDOUT must provide:** [Student-facing reference needed during activities]
+- **WKS must practice:** [Skills/evidence from the sequence]
+- **QUIZ must assess:** [LO evidence and success criteria]
+- **EXT must extend:** [Main evidence target without changing core LO]
+
+---
+
+## [REQUIRED] B. Lesson Flow
+
+### 1. ENGAGE — [X mins]
+- **Hook Scenario:** [Provide a detailed real-world situation or story to grab attention. E.g., "Roleplay as a server room engineer at 3 AM."]
+- **Open Question:** [Explicitly state the question the teacher will ask the class.]
+- **Transition:** [How the teacher summarizes to move to the Explore phase.]
+
+### 2. EXPLORE — [X mins]
+- **Activity Reference:** [Summarize the planned activity from the Activity Sequence. Detailed operation belongs in ACT, but the design decision lives here.]
+- **Student Discovery:** [What students should notice before formal explanation.]
+
+### 3. EXPLAIN — [X mins]
+- **Definitions:** [Explain the core concepts.]
+- **Visual Illustration (REQUIRED):** [MUST include a specific example of data, code, JSON payload, or a Mermaid diagram to visualize the concept. No abstract-only explanations.]
+
+### 4. ELABORATE — [X mins]
+- **Tiered Scaffolding:**
+  - 🥉 **Bronze:** [Overview of the foundational task]
+  - 🥈 **Silver:** [Overview of the application task]
+  - 🥇 **Gold:** [Overview of the extension task]
+
+> **ACT Contract**: Detailed operational instructions must expand the Activity Sequence above and must not change the planned evidence target.
+
+### 5. EVALUATE — [X mins]
+- **Exit Ticket:** [Provide 1-2 specific questions to quickly check mastery of the success criteria.]
+- **Closing:** [Final remarks and wrap-up notes.]
+
+> **QUIZ Contract**: Detailed assessment criteria and rubrics must assess the evidence and success criteria defined in the Lesson Design Plan.
+
+---
+
+## [OPTIONAL] Teacher Notes
+- **Common Pitfalls:** [Where students often struggle.]
+- **Troubleshooting:** [Fast fixes for common errors.]
+
+---
+
+## [REQUIRED] Artifact Linkage (Master Index)
+> List all satellite files used in this lesson.
+
+| Artifact File | Role in the Classroom | When to Use |
+|---|---|---|
+| `GUIDE_...` | Detailed Teaching Script | Teacher preparation |
+| `SLIDE_...` | Presentation Content | Throughout the session |
+| `HANDOUT_...` | Theory Summary for Students | During EXPLAIN phase |
+| `ACT_...` | Detailed Learning Activity Operations | During EXPLORE / ELABORATE / checkpoint phases |
+| `WKS_...` | Individual Worksheet | Wrap-up or Homework |
+| `QUIZ_...` | Assessment Rubric | During EVALUATE phase |
+| `EXT_...` | Enrichment Materials | For "Gold" students |

package/dist/templates/LESSON_EDP_template.md

@@ -0,0 +1,104 @@
+---
+id: "{{ID}}"
+title: "{{TITLE}}"
+type: "LESSON_EDP"
+created_by: "Curriculum OS Builder"
+phase: "{{PHASE}}"
+deliverable: "P3-T1"
+version: "{{VERSION}}"
+date: "{{DATE}}"
+prerequisite: []
+template_contract: "lesson-plan-v2"
+template_required_sections:
+  - "A. Lesson Design Plan"
+  - "Learning Objectives & Evidence"
+  - "Activity Sequence"
+  - "Resource Map"
+  - "Assessment Map"
+  - "Artifact Contract"
+  - "B. Lesson Flow"
+  - "Artifact Linkage"
+---
+
+# LESSON [XX]: [PROJECT TITLE] (EDP Model - Engineering Design Process)
+
+## [REQUIRED] A. Lesson Design Plan
+
+> OWNERSHIP: Each fact lives in exactly ONE section. The Artifact Contract
+> column of the Activity Sequence is the single owner of which satellite
+> produces what. Resource Map lists ONLY physical/logistical resources — do
+> not re-list satellite artifacts there. Lesson Flow references activities by
+> Seq number — never embed question banks or self-check text owned by KX/QUIZ.
+
+### 1. Learning Objectives & Evidence
+- **Estimated Duration:** [X minutes / X sessions]
+- **Project Objective:** [Describe the final product students will build]
+- **Materials & Equipment:** [Complete list of components]
+
+| LO | Objective (Bloom's / EDP) | Student Evidence | Success Criteria |
+|---|---|---|---|
+| LO1 | [Define / Imagine / Plan / Create / Test / Share] [Specific Content] | [Observable project artifact/action] | [Measurable condition] |
+| LO2 | [Define / Imagine / Plan / Create / Test / Share] [Specific Content] | [Observable project artifact/action] | [Measurable condition] |
+
+### 2. Activity Sequence
+> This is the canonical activity contract. Satellite artifacts must expand this sequence and must not invent a different one.
+
+| Seq | EDP Phase | Activity Type | Actor | Purpose | Student Action | Teacher Move | Output/Evidence | LO | Time | Artifact Contract |
+|---|---|---|---|---|---|---|---|---|---|---|
+| 1 | Ask | Problem Framing | Teacher + Students | [Clarify challenge] | [Students restate constraints] | [Present scenario/constraints] | [Problem statement] | LO1 | [X mins] | SLIDE/HANDOUT |
+| 2 | Imagine | Ideation | Students | [Generate options] | [Brainstorm/sketch] | [Facilitate comparisons] | [Idea list/sketches] | LO1 | [X mins] | WKS |
+| 3 | Plan | Design | Students | [Select solution path] | [Diagram/pseudocode/material plan] | [Review feasibility] | [Plan artifact] | LO1, LO2 | [X mins] | ACT/WKS |
+| 4 | Create | Build / Code | Students | [Build product] | [Assemble/code/test] | [Coach/debug] | [Working prototype] | LO2 | [X mins] | ACT/CODE_LAB/BOM |
+| 5 | Test & Improve | Iteration | Students | [Improve product] | [Record bugs/improvements] | [Prompt evidence-based fixes] | [Iteration log] | LO2 | [X mins] | WKS/QUIZ |
+| 6 | Share & Evaluate | Demo / Reflection | Students | [Communicate learning] | [Demo/explain] | [Debrief] | [Presentation/evaluation] | LO1, LO2 | [X mins] | QUIZ/EXT |
+
+### 3. Resource Map
+| Resource | Used In Activity | Purpose | Owner Artifact |
+|---|---|---|---|
+| [Slide / handout / code template / hardware] | [Seq #] | [Why needed] | [SLIDE/HANDOUT/ACT/CODE_LAB/BOM] |
+
+### 4. Assessment Map
+| Evidence | Assessed By | Criteria | Follow-up If Missing |
+|---|---|---|---|
+| [Student output] | [Rubric / demo / quiz item] | [Criteria] | [Reteach/retry action] |
+
+### 5. Artifact Contract
+- **ACT must expand:** [Seq numbers and details to operationalize]
+- **GUIDE must support:** [Teacher moves and facilitation risks from the activity sequence]
+- **SLIDE must visualize:** [Project challenge, constraints, checkpoints, and transitions]
+- **HANDOUT must provide:** [Student-facing reference needed during activities]
+- **WKS must practice/record:** [Planning, testing, or reflection evidence]
+- **QUIZ must assess:** [Project evidence and success criteria]
+- **EXT must extend:** [Main project evidence without changing core LO]
+
+---
+
+## [REQUIRED] B. Lesson Flow
+
+### 1. ASK (Define the Problem) — [X mins]
+[Set the context/story. What are the project requirements and constraints? (E.g., Build an obstacle-avoiding robot, budget under $10, use max 2 sensors).]
+
+### 2. IMAGINE (Ideate) — [X mins]
+[Students brainstorm possible solutions. Teacher suggests different approaches.]
+
+### 3. PLAN (Design) — [X mins]
+[Students draw circuit diagrams, create flowcharts, or write pseudocode before physical assembly.]
+
+### 4. CREATE (Build & Code) — [X mins]
+[Students start hardware assembly and typing code based on their design.]
+
+> **ACT Contract**: Detailed operational instructions must expand the Activity Sequence above and must not change the planned evidence target.
+
+### 5. TEST & IMPROVE (Iterate) — [X mins]
+[Students test their product, record bugs, and proceed with debugging/iteration.]
+
+### 6. SHARE & EVALUATE (Present) — [X mins]
+[Students demo their product, explain how it works, and highlight improvements made.]
+
+> **QUIZ Contract**: Detailed project rubrics must assess the evidence and success criteria defined in the Lesson Design Plan.
+
+---
+
+## [OPTIONAL] C. Teacher Facilitation Notes
+- **Project Bottlenecks:** [Where are students likely to get frustrated?]
+- **Extension for Fast Learners:** [Suggestions for upgrading features.]

package/dist/templates/LESSON_GENERAL_template.md

@@ -0,0 +1,117 @@
+---
+id: "{{ID}}"
+title: "{{TITLE}}"
+type: "LESSON_GENERAL"
+created_by: "Curriculum OS Builder"
+phase: "{{PHASE}}"
+deliverable: "P3-T1"
+version: "{{VERSION}}"
+date: "{{DATE}}"
+prerequisite: []
+template_contract: "lesson-plan-v2"
+template_required_sections:
+  - "A. Lesson Design Plan"
+  - "Learning Objectives & Evidence"
+  - "Activity Sequence"
+  - "Resource Map"
+  - "Assessment Map"
+  - "Artifact Contract"
+  - "B. Lesson Flow"
+  - "Artifact Linkage"
+---
+<!-- INJECT_BODY -->
+
+# LESSON [XX]: [LESSON TITLE]
+
+## [REQUIRED] A. Lesson Design Plan
+
+> OWNERSHIP: Each fact lives in exactly ONE section. The Artifact Contract
+> column of the Activity Sequence is the single owner of which satellite
+> produces what. Resource Map lists ONLY physical/logistical resources — do
+> not re-list satellite artifacts there. Lesson Flow references activities by
+> Seq number — never embed question banks or self-check text owned by KX/QUIZ.
+
+### 1. Learning Objectives & Evidence
+- **Estimated Duration:** [X minutes]
+- **Materials & Equipment:** [List hardware, software, and instructional materials]
+- **Keywords / Core Concepts:** [Keyword 1], [Keyword 2]
+
+| LO | Objective (Bloom's) | Student Evidence | Success Criteria |
+|---|---|---|---|
+| LO1 | By the end of this lesson, students will be able to [Bloom Verb] [Specific Content]. | [Observable output/action] | [Measurable condition] |
+| LO2 | By the end of this lesson, students will be able to [Bloom Verb] [Specific Content]. | [Observable output/action] | [Measurable condition] |
+
+### 2. Activity Sequence
+> This is the canonical activity contract. Satellite artifacts must expand this sequence and must not invent a different one.
+
+| Seq | Lesson Stage | Activity Type | Actor | Purpose | Student Action | Teacher Move | Output/Evidence | LO | Time | Artifact Contract |
+|---|---|---|---|---|---|---|---|---|---|---|
+| 1 | Warm-up | Hook / Discussion | Teacher + Students | [Why this opens the lesson] | [What students do] | [Prompt/facilitation move] | [Evidence/checkpoint] | LO1 | [X mins] | SLIDE |
+| 2 | Core Concepts | Mini Lesson / Media Study | Teacher + Students | [Concept to establish] | [What students read/watch/annotate] | [Explanation/demo] | [Evidence/checkpoint] | LO1 | [X mins] | SLIDE/HANDOUT |
+| 3 | Guided Practice | Guided Demo / Practice | Teacher + Students | [Skill to model] | [What students attempt] | [Model/coaching move] | [Evidence/checkpoint] | LO2 | [X mins] | ACT/WKS |
+| 4 | Independent Practice | Practice / Lab | Students | [Main application] | [What students build/solve] | [Debug/coaching] | [Main evidence] | LO2 | [X mins] | ACT/CODE_LAB/WKS |
+| 5 | Wrap-up | Reflection / Check | Students | [Mastery check] | [Exit response/demo] | [Debrief] | [Assessment evidence] | LO1, LO2 | [X mins] | QUIZ |
+
+### 3. Resource Map
+| Resource | Used In Activity | Purpose | Owner Artifact |
+|---|---|---|---|
+| [Slide / handout / code template / hardware] | [Seq #] | [Why needed] | [SLIDE/HANDOUT/ACT/CODE_LAB/BOM] |
+
+### 4. Assessment Map
+| Evidence | Assessed By | Criteria | Follow-up If Missing |
+|---|---|---|---|
+| [Student output] | [Exit ticket / rubric / quiz item] | [Criteria] | [Reteach/retry action] |
+
+### 5. Artifact Contract
+- **ACT must expand:** [Seq numbers and details to operationalize]
+- **GUIDE must support:** [Teacher moves and facilitation risks from the activity sequence]
+- **SLIDE must visualize:** [Key concepts, checkpoints, and transitions]
+- **HANDOUT must provide:** [Student-facing reference needed during activities]
+- **WKS must practice:** [Skills/evidence from the sequence]
+- **QUIZ must assess:** [LO evidence and success criteria]
+- **EXT must extend:** [Main evidence target without changing core LO]
+
+---
+
+## [REQUIRED] B. Lesson Flow
+
+### 1. Warm-up / Hook — [X mins]
+[Inquiry-based question, short game, or story to grab attention, connecting to prior knowledge or real-world applications.]
+
+---
+
+### 2. Core Concepts — [X mins]
+
+### Concept 1: [Concept Name]
+[Explain theory in age-appropriate language. Use real-world analogies. Max 3 paragraphs.]
+- **Illustrative Example:** [Specific example]
+
+### Concept 2: [Concept Name] (if applicable)
+[Theory explanation]
+- **Illustrative Example:** [Specific example]
+
+---
+
+### 3. Guided Practice — [X mins]
+[Teacher demos or guides students step-by-step according to the Activity Sequence. Include code snippets, Mermaid diagrams, or basic wiring schematics.]
+
+---
+
+### 4. Independent Practice — [X mins]
+[Students solve a problem or challenge based on the planned evidence target.]
+
+> **ACT Contract**: Detailed operational instructions must expand the Activity Sequence above and must not change the planned evidence target.
+
+---
+
+### 5. Wrap-up & Checkpoint — [X mins]
+[Summarize the 2-3 most important points. Provide 2-3 quick check questions to ensure understanding before class ends.]
+
+> **QUIZ Contract**: Detailed assessment criteria and rubrics must assess the evidence and success criteria defined in the Lesson Design Plan.
+
+---
+
+## [OPTIONAL] C. Teacher Notes
+- **Common Pitfalls:** [Where do students usually go wrong?]
+- **Troubleshooting:** [Fastest way to fix common circuit/code errors?]
+- **Extension Tasks:** [Enrichment questions or extra challenges for fast learners.]

package/dist/templates/OUTPUT_CONSTRAINTS_template.md

@@ -0,0 +1,38 @@
+---
+id: "{{ID}}"
+title: "{{TITLE}}"
+type: "OUTPUT_CONSTRAINTS"
+created_by: "Curriculum OS Builder"
+phase: "{{PHASE}}"
+deliverable: "{{DELIVERABLE_CODE}}"
+version: "{{VERSION}}"
+date: "{{DATE}}"
+---
+
+# CONTENT GENERATION CONSTRAINTS
+
+_Strict rules for @content, @activity, and @assessor to ensure pedagogical quality._
+
+## 1. Structural Constraints
+- **Header Hierarchy:** Must strictly follow Markdown nesting (h1 ➔ h2 ➔ h3).
+- **Required Sections:** Every Lesson MUST have: Overview, Warm-up, Core Concepts, Guided Practice, Independent Practice, Wrap-up.
+- **Link Integrity:** All internal links to `ACT`, `QUIZ`, or `SLIDE` must use the standardized U-M-L pathing: `[Link text](file:///.../_content/UXX/LXX/TYPE_UXX_MXX_LXX.md)`.
+
+## 2. Quantitative Constraints
+- **Word Count:** Lesson Plan (800 - 1500 words), Student Handout (max 500 words).
+- **Paragraph Length:** Max 3 sentences per paragraph for readability.
+- **Bullet Points:** Use lists for sequences or feature sets; avoid "walls of text."
+
+## 3. Pedagogical Constraints
+- **Bloom's Alignment:** Objectives must use strong verbs (Identify, Describe, Build, Debug).
+- **Inquiry-First:** Activities should start with a "Why" or a "Problem" before the "How-to."
+- **Analogy Rule:** Every abstract concept (e.g., Cloud, API) MUST have at least one real-world analogy.
+
+## 4. Code & Technical Constraints
+- **Executable Code:** All code blocks must be self-contained or explicitly state dependencies.
+- **Comments:** Minimum 30% code-to-comment ratio for student examples.
+- **Circuit Safety:** Explicitly mention safety warnings (e.g., common grounds, polarity) for hardware projects.
+## 5. Language Constraints
+- **Structure (Headers):** All major section headings MUST be in English (e.g., `## [REQUIRED] 1. Overview`).
+- **Body Content:** All pedagogical explanations, instructions, and feedback MUST be authored in English by default (Plan C — English-canonical). The `language` parameter controls the localized output language; see /localize-course for translation.
+- **Bilingual Support:** Technical terms are written in English with the localized translation added during the localization step (e.g., `Sensor (<translation>)` — the translation column is produced by /localize-course, never authored).