@vibeuniv/mcp-server 0.3.0 → 0.3.2

package/dist/tools/generate-curriculum.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { scanTeachingCriticalFiles } from "../lib/file-scanner.js";
 export const generateCurriculumSchema = {
     project_id: z.string().describe("The VibeUniv project ID"),
     difficulty: z
@@ -10,33 +11,53 @@ export const generateCurriculumSchema = {
 function formatTechStack(t) {
     return `- **${t.name}**${t.version ? ` v${t.version}` : ""} (${t.category})`;
 }
-function formatKBHints(kbHints) {
+function formatKBHints(kbHints, locale) {
     const sections = [];
     for (const [techName, hints] of Object.entries(kbHints)) {
         if (hints.length === 0)
             continue;
-        const conceptLines = hints.map((h) => `#### ${h.concept_name} (\`${h.concept_key}\`)
+        const conceptLines = locale === "en"
+            ? hints.map((h) => `#### ${h.concept_name} (\`${h.concept_key}\`)
+- **Key Points:**
+${h.key_points.map((p) => `  - ${p}`).join("\n")}
+- **Good Quiz Topics:** ${h.common_quiz_topics.join(", ")}
+- **Prerequisites:** ${h.prerequisite_concepts.length > 0 ? h.prerequisite_concepts.join(", ") : "(none)"}`).join("\n\n")
+            : hints.map((h) => `#### ${h.concept_name} (\`${h.concept_key}\`)
 - **핵심 포인트:**
 ${h.key_points.map((p) => `  - ${p}`).join("\n")}
 - **좋은 퀴즈 주제:** ${h.common_quiz_topics.join(", ")}
 - **선행 개념:** ${h.prerequisite_concepts.length > 0 ? h.prerequisite_concepts.join(", ") : "(없음)"}`).join("\n\n");
-        sections.push(`### ${techName} 핵심 개념 가이드\n\n${conceptLines}`);
+        const heading = locale === "en"
+            ? `### ${techName} Core Concept Guide`
+            : `### ${techName} 핵심 개념 가이드`;
+        sections.push(`${heading}\n\n${conceptLines}`);
     }
-    return sections.length > 0
-        ? `## 교육 핵심 포인트 (Knowledge Base)
+    if (sections.length === 0)
+        return "";
+    const header = locale === "en"
+        ? `## Educational Key Points (Knowledge Base)
+
+Below are **core educational key points** for each technology.
+Include these points in the curriculum, reference quiz topics, and follow prerequisite ordering.`
+        : `## 교육 핵심 포인트 (Knowledge Base)
 
 아래는 각 기술의 **핵심 교육 포인트**입니다.
 커리큘럼에 반드시 이 포인트들을 포함하고, 퀴즈 주제를 참고하세요.
-선행 개념 순서에 맞게 모듈을 배치하세요.
-
-${sections.join("\n\n")}`
-        : "";
+선행 개념 순서에 맞게 모듈을 배치하세요.`;
+    return `${header}\n\n${sections.join("\n\n")}`;
 }
-function formatEducationalAnalysis(analysis, difficulty) {
+function formatEducationalAnalysis(analysis, difficulty, locale) {
     const sections = [];
+    const en = locale === "en";
     // Project Overview
     const ov = analysis.project_overview;
-    sections.push(`### 프로젝트 개요 (AI 분석 결과)
+    sections.push(en
+        ? `### Project Overview (AI Analysis)
+- **App Description:** ${ov.one_liner}
+- **App Type:** ${ov.app_type}
+- **Target Users:** ${ov.target_users}
+- **Core Features:** ${ov.core_features.join(", ")}`
+        : `### 프로젝트 개요 (AI 분석 결과)
 - **앱 설명:** ${ov.one_liner}
 - **앱 유형:** ${ov.app_type}
 - **대상 사용자:** ${ov.target_users}
@@ -47,16 +68,24 @@ function formatEducationalAnalysis(analysis, difficulty) {
             const steps = f.steps
                 .map((s) => `    - ${s.description} (\`${s.file}\`:${s.line_range})`)
                 .join("\n");
-            return `- **${f.name}** (난이도: ${f.difficulty})\n  트리거: ${f.trigger}\n${steps}`;
+            return en
+                ? `- **${f.name}** (difficulty: ${f.difficulty})\n  Trigger: ${f.trigger}\n${steps}`
+                : `- **${f.name}** (난이도: ${f.difficulty})\n  트리거: ${f.trigger}\n${steps}`;
         });
-        sections.push(`### 사용자 흐름 (User Flows)\n\n각 흐름을 커리큘럼에서 다뤄야 합니다:\n\n${flowLines.join("\n\n")}`);
+        sections.push(en
+            ? `### User Flows\n\nEach flow should be covered in the curriculum:\n\n${flowLines.join("\n\n")}`
+            : `### 사용자 흐름 (User Flows)\n\n각 흐름을 커리큘럼에서 다뤄야 합니다:\n\n${flowLines.join("\n\n")}`);
     }
     // File Difficulty Map
     if (analysis.file_analysis.length > 0) {
         const fileLines = analysis.file_analysis
             .sort((a, b) => a.complexity - b.complexity)
-            .map((f) => `- \`${f.path}\` — ${f.role} (복잡도: ${f.complexity}/5, ${f.difficulty})`);
-        sections.push(`### 파일 난이도 맵\n\n쉬운 파일부터 어려운 파일 순서로 정렬했습니다. 모듈 순서를 결정할 때 참고하세요:\n\n${fileLines.join("\n")}`);
+            .map((f) => en
+            ? `- \`${f.path}\` — ${f.role} (complexity: ${f.complexity}/5, ${f.difficulty})`
+            : `- \`${f.path}\` — ${f.role} (복잡도: ${f.complexity}/5, ${f.difficulty})`);
+        sections.push(en
+            ? `### File Difficulty Map\n\nSorted from easiest to hardest. Use this to determine module order:\n\n${fileLines.join("\n")}`
+            : `### 파일 난이도 맵\n\n쉬운 파일부터 어려운 파일 순서로 정렬했습니다. 모듈 순서를 결정할 때 참고하세요:\n\n${fileLines.join("\n")}`);
     }
     // Learning Priorities
     const priorities = analysis.learning_priorities;
@@ -65,82 +94,152 @@ function formatEducationalAnalysis(analysis, difficulty) {
         : difficulty === "intermediate"
             ? priorities.intermediate
             : priorities.advanced;
-    const priorityLines = [
-        `- **시작:** ${lp.start_with.join(", ")}`,
-        `- **집중:** ${lp.focus_on.join(", ")}`,
-    ];
+    const priorityLines = en
+        ? [
+            `- **Start with:** ${lp.start_with.join(", ")}`,
+            `- **Focus on:** ${lp.focus_on.join(", ")}`,
+        ]
+        : [
+            `- **시작:** ${lp.start_with.join(", ")}`,
+            `- **집중:** ${lp.focus_on.join(", ")}`,
+        ];
     if ("skip_for_now" in lp) {
-        priorityLines.push(`- **나중에:** ${lp.skip_for_now.join(", ")}`);
+        priorityLines.push(en
+            ? `- **Skip for now:** ${lp.skip_for_now.join(", ")}`
+            : `- **나중에:** ${lp.skip_for_now.join(", ")}`);
     }
     if ("deep_dive" in lp) {
-        priorityLines.push(`- **심화:** ${lp.deep_dive.join(", ")}`);
+        priorityLines.push(en
+            ? `- **Deep dive:** ${lp.deep_dive.join(", ")}`
+            : `- **심화:** ${lp.deep_dive.join(", ")}`);
     }
     if ("challenge_topics" in lp) {
-        priorityLines.push(`- **도전:** ${lp.challenge_topics.join(", ")}`);
+        priorityLines.push(en
+            ? `- **Challenge:** ${lp.challenge_topics.join(", ")}`
+            : `- **도전:** ${lp.challenge_topics.join(", ")}`);
     }
-    sections.push(`### ${difficulty} 난이도 학습 우선순위\n\n${priorityLines.join("\n")}`);
+    sections.push(en
+        ? `### ${difficulty} Level Learning Priorities\n\n${priorityLines.join("\n")}`
+        : `### ${difficulty} 난이도 학습 우선순위\n\n${priorityLines.join("\n")}`);
     // Repeated Patterns
     if (analysis.repeated_patterns.length > 0) {
-        const patternLines = analysis.repeated_patterns.map((p) => `- **${p.name}**: ${p.description} (${p.occurrences.length}회 발견) — 교육 가치: ${p.teaching_value}`);
-        sections.push(`### 반복 패턴\n\n프로젝트에서 반복적으로 사용되는 패턴입니다. 이 패턴들을 커리큘럼에 포함하면 학습 효과가 높아집니다:\n\n${patternLines.join("\n")}`);
+        const patternLines = analysis.repeated_patterns.map((p) => en
+            ? `- **${p.name}**: ${p.description} (found ${p.occurrences.length} times) — teaching value: ${p.teaching_value}`
+            : `- **${p.name}**: ${p.description} (${p.occurrences.length}회 발견) — 교육 가치: ${p.teaching_value}`);
+        sections.push(en
+            ? `### Repeated Patterns\n\nThese patterns are used repeatedly in the project. Including them in the curriculum enhances learning:\n\n${patternLines.join("\n")}`
+            : `### 반복 패턴\n\n프로젝트에서 반복적으로 사용되는 패턴입니다. 이 패턴들을 커리큘럼에 포함하면 학습 효과가 높아집니다:\n\n${patternLines.join("\n")}`);
     }
     // Code Quality
     const cq = analysis.code_quality;
     if (cq.good_practices.length > 0 || cq.improvement_areas.length > 0) {
         const lines = [];
         if (cq.good_practices.length > 0) {
-            lines.push("**좋은 사례 (교육 포인트):**");
+            lines.push(en ? "**Good Practices (Teaching Points):**" : "**좋은 사례 (교육 포인트):**");
             for (const gp of cq.good_practices) {
-                lines.push(`- ${gp.description} → 관련 개념: ${gp.concept}`);
+                lines.push(en
+                    ? `- ${gp.description} → Related concept: ${gp.concept}`
+                    : `- ${gp.description} → 관련 개념: ${gp.concept}`);
             }
         }
         if (cq.improvement_areas.length > 0) {
-            lines.push("\n**개선 기회 (학습 기회):**");
+            lines.push(en ? "\n**Improvement Opportunities (Learning Opportunities):**" : "\n**개선 기회 (학습 기회):**");
             for (const ia of cq.improvement_areas) {
-                lines.push(`- [${ia.severity}] ${ia.description} → 교육: ${ia.teaching_opportunity}`);
+                lines.push(en
+                    ? `- [${ia.severity}] ${ia.description} → Teaching: ${ia.teaching_opportunity}`
+                    : `- [${ia.severity}] ${ia.description} → 교육: ${ia.teaching_opportunity}`);
             }
         }
-        sections.push(`### 코드 품질 관찰\n\n${lines.join("\n")}`);
+        sections.push(en
+            ? `### Code Quality Observations\n\n${lines.join("\n")}`
+            : `### 코드 품질 관찰\n\n${lines.join("\n")}`);
     }
     // Tech Stack Metaphors (beginner only)
     if (difficulty === "beginner" && ov.tech_stack_metaphors.length > 0) {
         const metaphorLines = ov.tech_stack_metaphors.map((m) => `- **${m.tech_name}** → ${m.metaphor}`);
-        sections.push(`### 기술 스택 비유 (초보자용)\n\n이 비유들을 커리큘럼에서 적극 활용하세요:\n\n${metaphorLines.join("\n")}`);
+        sections.push(en
+            ? `### Tech Stack Metaphors (Beginner)\n\nUse these metaphors actively in the curriculum:\n\n${metaphorLines.join("\n")}`
+            : `### 기술 스택 비유 (초보자용)\n\n이 비유들을 커리큘럼에서 적극 활용하세요:\n\n${metaphorLines.join("\n")}`);
     }
-    return `## 프로젝트 교육 분석 (Educational Analysis)
+    const header = en
+        ? `## Project Educational Analysis
 
-아래는 AI가 프로젝트를 분석한 교육용 메타데이터입니다.
-이 정보를 활용해 더 구체적이고 맞춤화된 커리큘럼을 만드세요.
+Below is AI-analyzed educational metadata for the project.
+Use this information to create a more specific and personalized curriculum.`
+        : `## 프로젝트 교육 분석 (Educational Analysis)
 
-${sections.join("\n\n")}`;
+아래는 AI가 프로젝트를 분석한 교육용 메타데이터입니다.
+이 정보를 활용해 더 구체적이고 맞춤화된 커리큘럼을 만드세요.`;
+    return `${header}\n\n${sections.join("\n\n")}`;
 }
-function buildLevelGuidance(difficulty) {
+function buildLevelGuidance(difficulty, locale) {
+    const en = locale === "en";
     if (difficulty === "beginner") {
-        return `- "X가 뭔가요?"부터 시작 — 기술이 왜 존재하는지, 없으면 어떤 문제가 생기는지부터 설명
-   - 전문 용어를 쓸 때는 반드시 바로 뒤에 쉬운 말로 풀어서 설명 (예: "미들웨어(middleware)란, 요청이 들어올 때마다 자동으로 실행되는 '검문소' 같은 코드예요")
-   - 일상생활 비유를 적극 활용 (예: "컴포넌트는 레고 블록", "API는 식당 주문 창구", "데이터베이스는 엑셀 스프레드시트")
-   - concept과 quiz 모듈을 많이, practical은 아주 쉬운 것만
-   - 한 번에 하나의 개념만 — 여러 개념을 한꺼번에 설명하지 않기`;
+        return en
+            ? `**[Core Principle] Explain as if to a 5-6 year old. Assume they know nothing.**
+   - 3-step concept breakdown: ①Analogy (food/LEGO/school/play) → ②One-sentence definition → ③Code connection
+   - "What if this didn't exist?" before/after comparison (e.g., "No middleware? → Anyone can access secret pages 😱")
+   - Translate key code lines into plain English (e.g., \`const x = 5\` → "Put the number 5 in a box called x 📦")
+   - Give friendly nicknames to technical terms: useState→"memory box", props→"delivery package", middleware→"security checkpoint"
+   - concept 40%+, quiz 20%+, practical 15%↓(very easy only)
+   - explanation 400+ chars, 5-7 sections per module
+   - Use emojis actively: 🎯summary, 💡tip, ⚠️warning, 👏praise
+   - Tone: like reading a picture book, short sentences, lots of encouragement
+   - estimated_minutes: 20-35 min`
+            : `**[대원칙] 5~6세 아이에게 설명하듯. 아무것도 모른다고 가정.**
+   - 개념 3단계 쪼개기: ①비유(음식/레고/학교/놀이) → ②한 문장 정의 → ③코드 연결
+   - "이게 없으면?" before/after 비교 (예: "미들웨어 없으면? → 아무나 비밀 페이지 접근 😱")
+   - 주요 코드 라인에 "우리말 번역" (예: \`const x = 5\` → "x 상자에 숫자 5를 넣어요 📦")
+   - 기술 용어에 한국어 별명: useState→"기억 상자", props→"택배 상자", middleware→"보안 검문소"
+   - concept 40%↑, quiz 20%↑, practical 15%↓(아주 쉬운 것만)
+   - explanation 400자↑, 모듈당 5-7섹션
+   - 이모지 적극 활용: 🎯한줄정리, 💡팁, ⚠️주의, 👏칭찬
+   - 톤: 그림책 읽어주듯, 짧은 문장, 격려·칭찬 대폭
+   - estimated_minutes: 20-35분`;
     }
     if (difficulty === "intermediate") {
-        return `- 기본 프로그래밍 지식은 안다고 가정
+        return en
+            ? `- Assume basic programming knowledge
+   - Focus on "how" and "why" — not just usage but how things work and design decisions
+   - Increase practical and project_walkthrough module ratio
+   - Cover common patterns, best practices, common mistakes`
+            : `- 기본 프로그래밍 지식은 안다고 가정
    - "어떻게"와 "왜"에 집중 — 단순 사용법이 아니라 동작 원리와 설계 이유
    - practical과 project_walkthrough 모듈 비중 높이기
    - 일반적인 패턴, 베스트 프랙티스, 흔한 실수 다루기`;
     }
-    return `- 탄탄한 프로그래밍 지식 전제
+    return en
+        ? `- Assume solid programming knowledge
+   - Focus on advanced patterns, performance optimization, architecture design
+   - Maximize practical and project_walkthrough ratio
+   - Cover edge cases, internals, optimization strategies`
+        : `- 탄탄한 프로그래밍 지식 전제
    - 고급 패턴, 성능 최적화, 아키텍처 설계에 집중
    - practical과 project_walkthrough 비중 극대화
    - 엣지 케이스, 내부 동작 원리, 최적화 전략 다루기`;
 }
 // ─── Tool registration ──────────────────────────────────────────────
 export function registerGenerateCurriculum(server, client) {
-    server.tool("vibeuniv_generate_curriculum", "Generate a learning curriculum for the project. Returns tech stack info and a JSON schema — you create the curriculum JSON, then submit it with vibeuniv_submit_curriculum.", generateCurriculumSchema, { readOnlyHint: true, openWorldHint: true }, async ({ project_id, difficulty }) => {
+    server.tool("vibeuniv_generate_curriculum", "Generate a learning curriculum for the project. IMPORTANT: Before calling this tool, you MUST ask the user which difficulty level they prefer — beginner (초급), intermediate (중급), or advanced (고급). Do NOT default to beginner without asking. Returns tech stack info and a JSON schema — you create the curriculum JSON, then submit it with vibeuniv_submit_curriculum.", generateCurriculumSchema, { readOnlyHint: true, openWorldHint: true }, async ({ project_id, difficulty }) => {
         try {
             console.error(`[vibeuniv] Generating curriculum instructions for project ${project_id}...`);
             // Fetch all curriculum context in a single API call
             const curriculumContext = await client.getCurriculumContext(project_id);
+            // Read teaching-critical files from local disk (avoids server roundtrip for file decryption)
+            let localFiles = [];
+            try {
+                localFiles = await scanTeachingCriticalFiles(process.cwd());
+            }
+            catch (err) {
+                console.error(`[vibeuniv] Local file scan failed (non-fatal): ${err instanceof Error ? err.message : err}`);
+            }
+            // Prefer local files; fall back to server files if local scan yields nothing
+            const curriculumFiles = localFiles.length > 0
+                ? localFiles
+                : (curriculumContext.files ?? []);
             const techStacks = curriculumContext.techStacks;
+            const locale = curriculumContext.locale ?? "ko";
+            const en = locale === "en";
             if (techStacks.length === 0) {
                 return {
                     content: [
@@ -162,18 +261,18 @@ export function registerGenerateCurriculum(server, client) {
             const coreList = coreStacks.map(formatTechStack).join("\n");
             const supportingList = supportingStacks.length > 0
                 ? supportingStacks.map(formatTechStack).join("\n")
-                : "(없음)";
-            const levelGuidance = buildLevelGuidance(difficulty);
+                : en ? "(none)" : "(없음)";
+            const levelGuidance = buildLevelGuidance(difficulty, locale);
             // Build KB hints section
             const kbSection = kbResult && Object.keys(kbResult.techs).length > 0
-                ? `\n${formatKBHints(kbResult.techs)}\n`
+                ? `\n${formatKBHints(kbResult.techs, locale)}\n`
                 : "";
             // Build educational analysis section (with defensive try/catch for LLM-generated data)
             let eduSection = "";
             let hasEduAnalysis = false;
             if (educationalAnalysis) {
                 try {
-                    eduSection = `\n${formatEducationalAnalysis(educationalAnalysis, difficulty)}\n`;
+                    eduSection = `\n${formatEducationalAnalysis(educationalAnalysis, difficulty, locale)}\n`;
                     hasEduAnalysis = true;
                 }
                 catch (err) {
@@ -182,146 +281,263 @@ export function registerGenerateCurriculum(server, client) {
             }
             // Build educational analysis instruction
             const eduInstruction = hasEduAnalysis
-                ? `
-### 10. 교육 분석 데이터 활용
-- **프로젝트 개요**의 핵심 기능과 앱 유형을 커리큘럼 소개에 반영
-- **사용자 흐름(User Flows)** 을 project_walkthrough 모듈의 기반으로 활용
-- **파일 난이도 맵**을 참고해 모듈 순서와 예상 시간을 설정
-- **학습 우선순위**에 따라 모듈 배치를 최적화
-- **반복 패턴**을 별도 모듈이나 퀴즈로 다뤄 학습 효과 극대화
-- **코드 품질 관찰**의 좋은 사례를 교육 포인트로, 개선 기회를 챌린지로 활용
-- 초보자 난이도일 경우 **기술 스택 비유**를 explanation 섹션에 적극 활용`
+                ? en
+                    ? `\n**Educational Analysis Usage:** Project overview→intro, User Flows→walkthrough, File difficulty→module order, Learning priorities→arrangement, Repeated patterns→quizzes, Code quality→teaching points${difficulty === "beginner" ? ", Metaphors→explanations" : ""}`
+                    : `\n**교육 분석 활용:** 프로젝트 개요→소개, User Flows→walkthrough, 파일 난이도→모듈 순서, 학습 우선순위→배치, 반복 패턴→퀴즈, 코드 품질→교육 포인트${difficulty === "beginner" ? ", 비유→explanation" : ""}`
                 : "";
             // Build KB instruction
             const kbInstruction = kbResult && Object.keys(kbResult.techs).length > 0
-                ? `
-### ${educationalAnalysis ? "11" : "10"}. Knowledge Base 활용
-- **핵심 포인트**를 반드시 커리큘럼에 포함 — 빠뜨리지 마세요
-- **퀴즈 주제**를 quiz_question 섹션의 주제로 활용
-- **선행 개념** 순서에 맞게 모듈을 배치 (선행 개념이 먼저 나와야 함)`
+                ? en
+                    ? `\n**KB Usage:** Include key points, use quiz topics, follow prerequisite ordering.`
+                    : `\n**KB 활용:** 핵심 포인트 필수 포함, 퀴즈 주제 활용, 선행 개념 순서 준수.`
                 : "";
-            const instructions = `이 프로젝트의 학습 커리큘럼을 생성해주세요. 아래 지시를 꼼꼼히 따라주세요.
+            // Build project source code section (local files preferred, server fallback)
+            const filesSection = curriculumFiles.length > 0
+                ? en
+                    ? `\n## Project Source Code
+
+Below are the student's actual project files.
+You MUST directly quote this code in code_example and walkthrough sections.
+Do NOT make up code.
+
+${curriculumFiles.map((f) => `#### ${f.file_path}\n\`\`\`\n${f.content}\n\`\`\``).join("\n\n")}\n`
+                    : `\n## 프로젝트 소스 코드
+
+아래는 학생의 실제 프로젝트 파일입니다.
+커리큘럼의 code_example, walkthrough 섹션에서 반드시 이 코드를 직접 인용하세요.
+코드를 창작하지 마세요.
+
+${curriculumFiles.map((f) => `#### ${f.file_path}\n\`\`\`\n${f.content}\n\`\`\``).join("\n\n")}\n`
+                : "";
+            const learnMoreLabel = en ? "📚 Learn More" : "📚 더 알아보기";
+            const minBodyChars = difficulty === "beginner" ? "400" : "200";
+            const sectionsPerModule = difficulty === "beginner" ? "5-7" : "3-5";
+            const minSections = difficulty === "beginner" ? "5" : "3";
+            const paragraphs = difficulty === "beginner" ? "6-8" : "4-6";
+            const instructions = en
+                ? `Please generate a learning curriculum for this project.
+
+## Target: Vibe Coder (${difficulty})
+
+Someone who built an app using AI coding tools but wants to understand **why it works**. Project-based learning, no abstract theory.
+
+## Tech Stack
+
+**Core (Required):**
+${coreList}
+
+**Supporting (Optional):**
+${supportingList}
+${filesSection}${eduSection}${kbSection}
+## Design Principles
+
+**Module Count (Required — server will reject if below minimum):**
+- Minimum 10 modules total (aim for 10-15)
+- Core technologies: at least 2 modules each
+- Supporting technologies: at least 1 module each
+
+**Module Design — Focus on project features:**
+Design modules around the project's actual features/files, not generic tech modules ("React Basics").
+
+Good examples:
+- "Dashboard Layout Analysis — Authentication with Server Components" (app/(dashboard)/layout.tsx)
+- "API Routes and Middleware — Auth Checks and Rate Limiting" (middleware.ts, app/api/...)
+- "Supabase Connection — Server vs Browser Client Differences" (lib/supabase/server.ts, client.ts)
+
+Bad examples:
+- "React Basics" (too generic)
+- "TypeScript Introduction" (unrelated to project)
+
+**Module Order:** Start from project entry points (page.tsx, layout.tsx) → core features → advanced patterns
+**Each module must center around at least one project file**
+
+**Module Types:** concept (concept+analogy), practical (code practice), quiz (code-based quiz), project_walkthrough (line-by-line file reading)
+**Difficulty:**
+${levelGuidance}
+
+**Section Design (${sectionsPerModule} per module, minimum ${minSections}):**
+- explanation: Markdown ${paragraphs} paragraphs. Must cite project file paths.
+  End with "${learnMoreLabel}" links 2-3 (React→react.dev, Next.js→nextjs.org/docs,
+  TypeScript→typescriptlang.org, Supabase→supabase.com/docs, Tailwind→tailwindcss.com/docs)
+- code_example: Copy actual project code + line-by-line comments.
+  Below the code block, explain with numbered list "What this code does:"
+- quiz_question: 4-choice based on project code. quiz_explanation with correct/incorrect reasoning
+- challenge: ___BLANK___ fill-in-the-blank. Both starter_code and answer_code required
+- reflection: "Open the X folder in your project. Look for Y." format
+
+**Required Placement Rules:**
+- Start each module with explanation
+- Maximum 2 consecutive explanations, 3rd must be quiz/reflection
+- At least 1 code_example per module required
+- At least 1 quiz_question per module required
+
+**Tone (Critical — key to learning content quality):**
+- Use casual, friendly "you" language
+- Address the student as "you" or "we"
+- Short sentences, one idea per sentence
+- Keep technical terms in English + follow with a plain explanation in parentheses
+- Start with questions: "Have you ever wondered about this code?", "Why does it work this way?"
+- Encourage: "If you've followed along this far, you already understand half of it!", "It can be confusing at first — don't worry"
+- Use analogies: everyday analogies for new concepts (API→restaurant order window, component→LEGO blocks)
+- Transition phrases: "Alright, now let's...", "Wait a moment!", "Let's check the actual code, shall we?"
+- Forbidden: dry academic tone, filler phrases like "Great question!", emotionless listing
+- Do NOT make up code — only quote actual project code
+
+**walkthrough:** Explain a file from import→logic→export order + connections to other files.
+${eduInstruction}${kbInstruction}
+
+## JSON Schema
 
-## 학생 프로필
+Follow the structure below exactly. All string values in English. Output ONLY JSON (no code fences/explanations).
 
-이 커리큘럼은 **"바이브 코더(Vibe Coder)"** 를 위한 것입니다.
-바이브 코더란, AI 코딩 도구(Claude Code, Cursor, Bolt 등)로 동작하는 앱을 이미 만든 사람입니다.
-코드가 돌아가게는 했지만, **왜 이렇게 작동하는지** 이해하고 싶어하는 사람이에요.
+{
+  "title": "string (required) — Curriculum title",
+  "description": "string (required) — Curriculum description",
+  "difficulty": "${difficulty}",
+  "estimated_hours": number (optional),
+  "modules": [
+    {
+      "title": "string (required) — Module title",
+      "description": "string (required) — Module description",
+      "module_type": "concept | practical | quiz | project_walkthrough",
+      "estimated_minutes": number (15-45),
+      "tech_name": "string (required) — Must exactly match a name from the tech stack list above",
+      "content": {
+        "sections": [
+          {
+            "type": "explanation | code_example | quiz_question | challenge | reflection",
+            "title": "string (required) — Section title",
+            "body": "string (required) — Markdown body. explanation minimum ${minBodyChars} chars",
 
-- **난이도:** ${difficulty}
-- **학습 스타일:** 이미 완성된 프로젝트 기반으로 학습 (추상적 이론 X)
-- **목표:** 자기 프로젝트의 기술 스택을 이해해서, 혼자서도 디버깅하고 기능을 추가할 수 있게 되는 것
+            "code": "string (required for code_example) — Actual project code + line-by-line comments",
 
-## 감지된 기술 스택
+            "quiz_options": ["string", "string", "string", "string"] (required for quiz_question, exactly 4),
+            "quiz_answer": number (required for quiz_question, 0-3),
+            "quiz_explanation": "string (required for quiz_question) — Correct/incorrect reasoning",
 
-### 핵심 기술 (Core) — 반드시 다뤄야 함
+            "challenge_starter_code": "string (required for challenge) — Contains ___BLANK___",
+            "challenge_answer_code": "string (required for challenge) — Completed code"
+          }
+        ]
+      }
+    }
+  ]
+}
+
+**Required Rules:**
+- At least 1 code_example + 1 quiz_question per module
+- Minimum 10 modules, minimum ${minSections} sections per module
+- explanation body must be at least ${minBodyChars} characters${difficulty === "beginner" ? `
+
+**[Beginner-only Additional Rules — Must Follow]:**
+- Every concept must have "What if this didn't exist?" before/after comparison
+- Every line of code in code_example must have a plain-English translation
+- Challenges must have only 1-2 blanks with very specific hints
+- All technical terms must have friendly nicknames` : ""}
+
+After generating: vibeuniv_submit_curriculum({ project_id: "${project_id}", curriculum: <JSON> })`
+                : `이 프로젝트의 학습 커리큘럼을 생성해주세요.
+
+## 대상: 바이브 코더 (${difficulty})
+
+AI 코딩 도구로 앱을 만들었지만 **왜 작동하는지** 이해하고 싶은 사람. 프로젝트 기반 학습, 추상적 이론 X.
+
+## 기술 스택
+
+**Core (필수):**
 ${coreList}
 
-### 보조 기술 (Supporting) — 선택적으로 다루기
+**Supporting (선택):**
 ${supportingList}
-${eduSection}${kbSection}
-## 사전 준비: 프로젝트 파일 분석
+${filesSection}${eduSection}${kbSection}
+## 설계 원칙
 
-**중요:** 커리큘럼 생성 전에 반드시 이 프로젝트의 소스 코드를 읽어주세요.
-특히 다음 파일들을 확인하세요:
-- 진입점 파일 (예: index.ts, app.tsx, main.py, layout.tsx 등)
-- 설정 파일 (예: package.json, tsconfig.json, next.config.ts 등)
-- 핵심 비즈니스 로직 파일 (가장 많이 수정된 파일들)
-- API 라우트, 데이터베이스 접근 코드
+**모듈 수량 (필수 — 미달 시 서버에서 거부됨):**
+- 전체 최소 10개 모듈 (10-15개 권장)
+- Core 기술: 각 최소 2개 모듈
+- Supporting 기술: 각 최소 1개 모듈
 
-이 파일들의 실제 코드를 커리큘럼에 직접 인용해야 합니다.
+**모듈 구성 — 프로젝트 기능 중심으로 설계:**
+기술별 일반 모듈("React 기초")이 아닌, 프로젝트의 실제 기능/파일을 중심으로 설계하세요.
 
-## 커리큘럼 설계 원칙
+좋은 예:
+- "대시보드 레이아웃 분석 — Server Component로 인증 처리하기" (app/(dashboard)/layout.tsx)
+- "API 라우트와 미들웨어 — 인증 체크와 속도 제한" (middleware.ts, app/api/...)
+- "Supabase 연결 — 서버 vs 브라우저 클라이언트 차이" (lib/supabase/server.ts, client.ts)
 
-### 1. 모듈 순서 — 의존성 기반
-- **가장 중요한 핵심 기술부터** 시작 (core framework → language → supporting tools)
-- **선행 지식 → 후행 지식** 순서 (예: JavaScript 기초 → React → Next.js)
-- 각 기술당 3-7개 모듈 (중요도와 복잡도에 따라 조절)
+나쁜 예:
+- "React 기초" (너무 일반적)
+- "TypeScript 입문" (프로젝트와 무관)
 
-### 2. 모듈 유형 믹스
-- \`concept\` — 핵심 개념을 비유와 예시로 설명
-- \`practical\` — 학생의 실제 코드를 수정하는 실습
-- \`quiz\` — 학생의 실제 코드 기반 퀴즈로 이해도 확인
-- \`project_walkthrough\` — 학생의 실제 파일을 위에서 아래로 한 줄씩 읽어보기
+**모듈 순서:** 프로젝트의 진입점(page.tsx, layout.tsx)부터 → 핵심 기능 → 고급 패턴
+**각 모듈은 반드시 1개 이상의 프로젝트 파일을 중심으로 설명**
 
-### 3. 난이도별 접근법
+**모듈 유형:** concept(개념+비유), practical(코드 실습), quiz(코드 기반 퀴즈), project_walkthrough(파일 라인별 읽기)
+**난이도:**
 ${levelGuidance}
 
-### 4. 각 모듈의 섹션 구성 (5-8개)
-섹션 유형과 순서 배치 규칙:
-- \`explanation\` — 마크다운으로 개념 설명. **반드시 학생의 실제 파일 경로와 코드를 인용**
-- \`code_example\` — 학생의 프로젝트에서 **실제 코드를 복사**해서 한국어 주석으로 설명
-- \`quiz_question\` — 학생의 실제 코드 기반 4지선다 퀴즈
-- \`challenge\` — 학생의 실제 프로젝트에서 수정해볼 수 있는 구체적 과제
-- \`reflection\` — "생각해보기" (1-3문장, 학생이 스스로 고민해보도록)
-
-**배치 규칙:** explanation이나 code_example 1-2개 후에 반드시 quiz_question 또는 reflection을 배치.
-explanation만 연속 3개 이상 나오면 안 됩니다.
-
-### 5. 콘텐츠 작성 톤
-- **모든 콘텐츠는 한국어** (기술 용어는 영어 유지하되 괄호 안에 한국어 설명 병기)
-- **짧은 문장**, **짧은 문단** — 한 단락에 3문장 이하
-- **글머리 기호** 적극 사용 — 장문 대신 핵심만
-- **질문으로 시작** — "왜 이렇게 할까요?", "이 코드 없이도 동작할까요?"
-- **마이크로러닝 느낌** — 각 섹션이 짧은 카드처럼, 강의처럼 느껴지면 안 됨
-
-### 6. 코드 인용 규칙
-- explanation: "여러분의 \`middleware.ts\` 파일 5번째 줄을 보면..." 형태로 구체적 파일 + 라인 참조
-- code_example: 학생 프로젝트의 **실제 코드를 그대로** 복사하고, 각 줄에 한국어 주석 추가
-  예시:
-  \`\`\`
-  // app/layout.tsx에서 가져온 코드
-  export default function RootLayout({ children }) {  // 모든 페이지를 감싸는 최상위 레이아웃
-    return <html lang="ko">  // 한국어 페이지라는 것을 브라우저에 알려줌
-  \`\`\`
-- quiz_question: "여러분의 \`app/page.tsx\`에서 \`export default\`를 쓰는 이유는?"처럼 학생 코드 기반
-- challenge: 수정할 파일, 추가할 내용, 기대 결과를 구체적으로 명시
-- **코드를 창작하지 마세요** — 반드시 프로젝트에 실재하는 코드를 인용
-
-### 7. 퀴즈 규칙
-- 선택지 정확히 4개, 정답은 0-indexed
-- \`quiz_explanation\`에 정답 이유 + 오답 이유를 2-4문장으로 설명
-- 학생의 실제 코드와 연결된 퀴즈 출제 (추상적 이론 퀴즈 X)
-
-### 8. 챌린지 규칙
-- 어떤 파일을 수정할지, 무엇을 추가/변경할지, 결과가 어떻게 바뀌는지 구체적으로
-- \`challenge_starter_code\`: TODO 주석이 있는 뼈대 코드
-- \`challenge_answer_code\`: 완성된 정답 코드
-
-### 9. project_walkthrough 규칙
-- 학생의 실제 파일 하나를 위에서 아래로 읽기
-- import 구문 → 핵심 로직 → export 순서로 설명
-- 이 파일이 프로젝트의 다른 파일들과 어떻게 연결되는지 설명
+**섹션 구성 (모듈당 ${sectionsPerModule}개, 최소 ${minSections}개):**
+- explanation: 마크다운 ${paragraphs} 문단. 반드시 프로젝트 파일 경로 인용.
+  끝에 "${learnMoreLabel}" 링크 2-3개 (React→react.dev, Next.js→nextjs.org/docs,
+  TypeScript→typescriptlang.org, Supabase→supabase.com/docs, Tailwind→tailwindcss.com/docs)
+- code_example: 프로젝트 실제 코드 복사 + 라인별 한국어 주석.
+  코드 블록 아래에 "이 코드가 하는 일:" 번호 목록으로 설명
+- quiz_question: 프로젝트 코드 기반 4지선다. quiz_explanation에 정답/오답 이유
+- challenge: ___BLANK___ 빈칸 채우기. starter_code + answer_code 모두 필수
+- reflection: "여러분의 프로젝트에서 X 폴더를 열어보세요. Y를 찾아보세요." 형태
+
+**필수 배치 규칙:**
+- 모듈 시작은 explanation으로
+- explanation 연속 2개까지만, 3번째는 반드시 quiz/reflection
+- 모듈당 code_example 최소 1개 필수
+- 모듈당 quiz_question 최소 1개 필수
+
+**톤 (매우 중요 — 학습 콘텐츠 품질의 핵심):**
+- 해요체 사용 (~이에요, ~거든요, ~잖아요, ~해볼까요?)
+- 학생을 "여러분" 또는 "우리"로 지칭
+- 짧은 문장 위주, 한 문장에 하나의 아이디어
+- 기술 용어는 영어 유지 + 바로 뒤에 괄호로 쉬운 설명
+- 질문으로 시작: "혹시 이 코드 보면서 궁금하셨죠?", "왜 이렇게 할까요?"
+- 격려 필수: "여기까지 따라오셨으면 벌써 절반은 이해하신 거예요!", "처음엔 헷갈릴 수 있는데 걱정 마세요"
+- 비유 필수: 새 개념마다 일상생활 비유 (API→식당 주문 창구, 컴포넌트→레고 블록)
+- 전환 어구: "자, 그러면 이제...", "여기서 잠깐!", "실제 코드에서 확인해볼까요?"
+- 금지: 교과서체(~이다, ~하라), 감정 없는 나열, 영어 직역투
+- 코드 창작 금지 — 프로젝트 실제 코드만 인용
+
+**walkthrough:** 파일 하나를 import→로직→export 순서로 설명 + 다른 파일과의 연결.
 ${eduInstruction}${kbInstruction}
 
 ## JSON 스키마
 
-아래 스키마에 맞는 JSON을 생성하세요.
+아래 구조를 정확히 따르세요. 모든 string 값은 한국어. JSON만 출력 (코드 펜스/설명 없이).
 
 {
-  "title": "string (학습 경로 제목, 한국어)",
-  "description": "string (2-3문장, 이 커리큘럼을 마치면 무엇을 할 수 있는지)",
+  "title": "string (필수) — 커리큘럼 제목",
+  "description": "string (필수) — 커리큘럼 설명",
   "difficulty": "${difficulty}",
-  "estimated_hours": number,
+  "estimated_hours": number (선택),
   "modules": [
     {
-      "title": "string (모듈 제목, 한국어)",
-      "description": "string (1-2문장 모듈 설명, 한국어)",
+      "title": "string (필수) — 모듈 제목",
+      "description": "string (필수) — 모듈 설명",
       "module_type": "concept | practical | quiz | project_walkthrough",
       "estimated_minutes": number (15-45),
-      "tech_name": "string (위 기술 스택 목록의 정확한 이름)",
+      "tech_name": "string (필수) — 위 기술 스택 목록의 이름과 정확히 일치",
       "content": {
         "sections": [
           {
             "type": "explanation | code_example | quiz_question | challenge | reflection",
-            "title": "string (섹션 제목, 한국어)",
-            "body": "string (마크다운 콘텐츠, 한국어)",
-            "code": "string (code_example일 때만, 학생의 실제 코드 + 한국어 주석)",
-            "quiz_options": ["string", "string", "string", "string"] (quiz_question일 때만),
-            "quiz_answer": number (0-3, quiz_question일 때만),
-            "quiz_explanation": "string (정답/오답 이유, quiz_question일 때만)",
-            "challenge_starter_code": "string (TODO 포함 뼈대, challenge일 때만)",
-            "challenge_answer_code": "string (완성 정답, challenge일 때만)"
+            "title": "string (필수) — 섹션 제목",
+            "body": "string (필수) — 마크다운 본문. explanation은 최소 ${minBodyChars}자",
+
+            "code": "string (code_example일 때 필수) — 프로젝트 실제 코드 + 라인별 주석",
+
+            "quiz_options": ["string", "string", "string", "string"] (quiz_question일 때 필수, 정확히 4개),
+            "quiz_answer": number (quiz_question일 때 필수, 0-3),
+            "quiz_explanation": "string (quiz_question일 때 필수) — 정답/오답 이유",
+
+            "challenge_starter_code": "string (challenge일 때 필수) — ___BLANK___ 포함",
+            "challenge_answer_code": "string (challenge일 때 필수) — 완성 코드"
           }
         ]
       }
@@ -329,14 +545,18 @@ ${eduInstruction}${kbInstruction}
   ]
 }
 
-## 중요
+**필수 규칙:**
+- 모듈당 code_example 최소 1개 + quiz_question 최소 1개
+- 최소 10개 모듈, 모듈당 최소 ${minSections}개 섹션
+- explanation body는 ${minBodyChars}자 이상${difficulty === "beginner" ? `
 
-- JSON만 출력하세요. 코드 펜스(\`\`\`), 설명문, 앞뒤 텍스트 없이 순수 JSON만.
-- \`tech_name\`은 위 기술 스택 목록의 이름과 **정확히 일치**해야 합니다.
-- 각 모듈당 **5-8개 섹션** 필수.
+**[초급 전용 추가 규칙 — 반드시 준수]:**
+- 모든 개념에 "이게 없으면?" before/after 비교 필수
+- code_example 모든 코드 라인에 "우리말 번역" 필수
+- challenge 빈칸 1-2개만, 힌트 매우 구체적
+- 기술 용어에 한국어 별명 필수` : ""}
 
-생성 완료 후 아래 도구로 제출:
-vibeuniv_submit_curriculum({ project_id: "${project_id}", curriculum: <생성된 JSON> })`;
+생성 후: vibeuniv_submit_curriculum({ project_id: "${project_id}", curriculum: <JSON> })`;
             return {
                 content: [
                     {