@open330/kiwimu 0.7.1 → 0.8.0

package/README.md

@@ -8,6 +8,7 @@
 
 전공책, PDF, 웹 콘텐츠를 넣으면 — LLM이 챕터/개념별로 분석하여 상호 링크된 학습 위키를 자동 생성합니다.
 
+[![npm](https://img.shields.io/npm/v/@open330/kiwimu?style=flat-square&color=cb3837&logo=npm)](https://www.npmjs.com/package/@open330/kiwimu)
 [![Bun](https://img.shields.io/badge/Bun-1.0+-fbf0df?style=flat-square&logo=bun&logoColor=black)](https://bun.sh)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://typescriptlang.org)
 [![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
@@ -16,16 +17,28 @@
 
 ---
 
+## 30초 데모 체험
+
+API key 없이 바로 체험할 수 있습니다:
+
+```bash
+mkdir my-wiki && cd my-wiki
+bunx @open330/kiwimu init --demo
+# → 양자역학 샘플 위키 + 학습 퀴즈가 즉시 생성됩니다
+# → http://localhost:8000 에서 확인하세요
+```
+
+---
+
 ## Quickstart for Agents
 
 <div><img src="https://quickstart-for-agents.vercel.app/api/header.svg?theme=claude-code&logo=kiwimu&title=Set+up+a+learning+wiki+from+any+textbook+or+URL&lang=Agents&font=mono&mascot=hat" width="100%" /></div>
 
 ```
-git clone https://github.com/Open330/kiwimu.git && cd kiwimu && bun install
 mkdir my-wiki && cd my-wiki
-bunx kiwimu init
-bunx kiwimu add "<YOUR_URL_OR_PDF>"
-bunx kiwimu serve
+bunx @open330/kiwimu init
+bunx @open330/kiwimu add "<YOUR_URL_OR_PDF>"
+bunx @open330/kiwimu serve
 ```
 
 <div><img src="https://quickstart-for-agents.vercel.app/api/footer.svg?theme=claude-code&text=copy+this+prompt+%C2%B7+paste+into+your+agent+%C2%B7+get+a+learning+wiki&font=mono" width="100%" /></div>
@@ -40,10 +53,14 @@ Kiwi Mu는 LLM을 활용해 이 연결을 **자동으로** 만들어, 지식을
 - **LLM 기반 문서 분석** — 챕터/섹션 구조를 보존한 원본 페이지 + 핵심 개념별 자동 생성 페이지
 - **원본/개념 분리** — 📖 원본 문서와 📝 개념 문서를 시각적으로 구분
 - **자동 상호 링크** — 원본↔개념 간 유기적 cross-link + 외부 참고 자료 (Wikipedia 등)
+- **학습 퀴즈** — 개념 페이지 기반 빈칸 채우기 / OX / 단답형 퀴즈 자동 생성
 - **지식 그래프** — D3.js 인터랙티브 그래프 (원본: 파란색, 개념: 초록색)
+- **데모 모드** — API key 없이 `--demo`로 즉시 체험
+- **다양한 파일 지원** — URL, PDF, DOCX, PPTX, PPT, DOC, KEY, RTF
+- **4개 LLM 프로바이더** — Google Gemini, Azure OpenAI, OpenAI, Anthropic
+- **다크 모드** — 시스템 테마에 자동 대응
+- **모바일 지원** — 햄버거 메뉴 + 슬라이드 사이드바
 - **웹 UI** — 브라우저에서 문서 추가, 설정 변경, 빌드 실행
-- **다양한 파일 지원** — URL, PDF, DOCX, PPTX, PPT, DOC, KEY
-- **다중 LLM 프로바이더** — Google Gemini, Azure OpenAI, OpenAI, Anthropic
 - **토큰 사용량 추적** — API 호출 수, 토큰, 예상 비용을 웹에서 확인
 - **원클릭 배포** — GitHub Pages / Vercel
 
@@ -52,15 +69,32 @@ Kiwi Mu는 LLM을 활용해 이 연결을 **자동으로** 만들어, 지식을
 ### 설치
 
 ```bash
-git clone https://github.com/Open330/kiwimu.git
-cd kiwimu && bun install
+# npm/bunx로 바로 사용 (설치 불필요)
+bunx @open330/kiwimu init
+
+# 또는 글로벌 설치
+bun add -g @open330/kiwimu
+```
+
+### 데모 모드 (API key 불필요)
+
+```bash
+mkdir my-wiki && cd my-wiki
+bunx @open330/kiwimu init --demo
 ```
 
+양자역학 샘플 위키가 생성되어 바로 체험할 수 있습니다:
+- 📖 원본 문서 + 📝 개념 페이지
+- 🔗 자동 상호 링크
+- 📊 지식 그래프
+- 📝 학습 퀴즈
+- 🎲 임의 문서 탐험
+
 ### 프로젝트 생성 (Interactive CLI)
 
 ```bash
 mkdir my-wiki && cd my-wiki
-bunx kiwimu init
+bunx @open330/kiwimu init
 ```
 
 Interactive 프롬프트가 실행됩니다:
@@ -86,68 +120,68 @@ Interactive 프롬프트가 실행됩니다:
 🥝 'Radio Astronomy Wiki' 위키가 생성되었습니다!
 ```
 
-이름을 바로 지정할 수도 있습니다:
-
-```bash
-bunx kiwimu init "My Study Wiki"
-```
-
 ### 문서 추가
 
 ```bash
 # URL 추가
-bunx kiwimu add "https://www.cv.nrao.edu/~sransom/web/Ch1.html"
+bunx @open330/kiwimu add "https://www.cv.nrao.edu/~sransom/web/Ch1.html"
 
-# PDF 추가
-bunx kiwimu add textbook.pdf
+# 파일 추가 (PDF, DOCX, PPTX, DOC, PPT, KEY, RTF)
+bunx @open330/kiwimu add textbook.pdf
+bunx @open330/kiwimu add lecture.pptx
 ```
 
 LLM이 문서를 분석하여:
 1. 📖 **원본 페이지** — 원래 챕터/섹션 구조 보존
 2. 📝 **개념 페이지** — 핵심 용어·정의·법칙 자동 생성
 3. 🔗 **Cross-link** — 원본↔개념 간 유기적 연결
+4. 📝 **퀴즈** — 개념별 학습 퀴즈 자동 생성
+
+### 학습 퀴즈
+
+```bash
+# 터미널에서 퀴즈 풀기
+bunx @open330/kiwimu quiz
+
+# 문제 수 지정
+bunx @open330/kiwimu quiz -n 10
+```
+
+웹에서도 `http://localhost:8000/quiz.html`에서 카드 플립 방식으로 퀴즈를 풀 수 있습니다.
 
 ### 빌드 및 서버
 
 ```bash
 # 정적 사이트 빌드
-bunx kiwimu build
+bunx @open330/kiwimu build
 
 # 로컬 서버 실행 (웹에서 문서 추가 가능)
-bunx kiwimu serve
+bunx @open330/kiwimu serve
 # → http://localhost:8000
 
 # 포트 변경
-bunx kiwimu serve -p 3000
-
-# 네트워크에 공개 (0.0.0.0)
-bunx kiwimu serve --host 0.0.0.0
+bunx @open330/kiwimu serve -p 3000
 ```
 
-### 웹 UI에서 문서 추가
-
-`kiwimu serve` 실행 후 http://localhost:8000 에서:
-- **🔗 URL 탭** — URL 입력 후 추가
-- **📄 파일 업로드 탭** — PDF, DOCX, PPTX 등 드래그앤드롭 업로드
-- 진행 상태 실시간 표시, 완료 시 자동 새로고침
-
 ### 관리 페이지
 
-http://localhost:8000/admin 에서:
+`kiwimu serve` 실행 후 콘솔에 표시되는 admin URL로 접속:
 - 위키 이름 변경
 - LLM 프로바이더/모델/API Key 설정
 - 토큰 사용량 및 예상 비용 확인
-- 등록된 소스 목록
+- 파일 업로드 (PDF, DOCX, PPTX 등)
+- URL 추가
 - 수동 빌드 실행
+- 페르소나 관리
 
 ### 배포
 
 ```bash
 # GitHub Pages (기본)
-bunx kiwimu deploy
+bunx @open330/kiwimu deploy
 
 # Vercel
-bunx kiwimu deploy --target vercel
+bunx @open330/kiwimu deploy --target vercel
 ```
 
 ## Commands
@@ -155,10 +189,13 @@ bunx kiwimu deploy --target vercel
 | 명령 | 설명 |
 |------|------|
 | `kiwimu init [name]` | 새 위키 프로젝트 생성 (interactive CLI) |
-| `kiwimu add <source>` | URL 또는 파일 추가 (LLM 분석 + 링크 생성) |
+| `kiwimu init --demo` | 샘플 데이터로 즉시 체험 (API key 불필요) |
+| `kiwimu add <source>` | URL 또는 파일 추가 (PDF, DOCX, PPTX, DOC, PPT, KEY, RTF) |
 | `kiwimu build` | 정적 위키 사이트 빌드 |
-| `kiwimu serve [-p port] [--host host]` | 웹 서버 실행 (문서 추가/관리 가능) |
-| `kiwimu deploy` | GitHub Pages / Vercel에 배포 |
+| `kiwimu serve [-p port]` | 웹 서버 실행 (문서 추가/관리 가능) |
+| `kiwimu quiz [-n count]` | 터미널에서 학습 퀴즈 풀기 |
+| `kiwimu expand [--provider]` | LLM으로 문서 내용 확장 (선택) |
+| `kiwimu deploy [--target]` | GitHub Pages / Vercel에 배포 |
 | `kiwimu status` | 현재 위키 상태 표시 |
 
 ## Supported File Formats
@@ -178,36 +215,40 @@ bunx kiwimu deploy --target vercel
 |-----------|----------|------|
 | **Google Gemini** | `gemini-2.0-flash-lite` | [무료 API key](https://aistudio.google.com/) |
 | Azure OpenAI | `gpt-5-nano` | Azure 구독 필요 |
-| OpenAI | `gpt-4o-mini` | API key 필요 |
+| OpenAI | `gpt-4o` | API key 필요 |
 | Anthropic | `claude-sonnet-4-20250514` | API key 필요 |
 
 ## Architecture
 
 ```
-소스 (URL / PDF / DOCX / PPTX)
+소스 (URL / PDF / DOCX / PPTX / DOC / PPT / KEY / RTF)
     ↓
-[ Ingest ]    ── Cheerio / pdf-parse / mammoth / jszip
+[ Ingest ]      ── Cheerio / pdf-parse / mammoth / jszip / textutil
     ↓
-[ Phase 1 ]   ── LLM: 원본 구조 추출 (📖 원본 페이지)
+[ Phase 1 ]     ── LLM: 원본 구조 추출 (📖 원본 페이지) — 병렬 처리 (concurrency=3)
     ↓
-[ Phase 2 ]   ── LLM: 개념 추출 (📝 개념 페이지)
+[ Phase 2 ]     ── LLM: 개념 추출 (📝 개념 페이지)
     ↓
-[ Phase 3 ]   ── [[wiki link]] 해석 + 원본↔개념 cross-link
+[ Phase 2.5 ]   ── LLM: 학습 퀴즈 자동 생성 (📝 퀴즈) — 병렬 처리
     ↓
-[ Build ]     ── 정적 HTML 생성 (탭 사이드바, KaTeX, 지식 그래프)
+[ Phase 3 ]     ── [[wiki link]] 해석 + 원본↔개념 cross-link
     ↓
-[ Deploy ]    ── GitHub Pages / Vercel
+[ Build ]       ── 정적 HTML (사이드바, KaTeX, 지식 그래프, 퀴즈, 다크 모드)
+    ↓
+[ Deploy ]      ── GitHub Pages / Vercel
 ```
 
 ```
 project-dir/
 ├── kiwi.toml          # 프로젝트 + LLM 설정
-├── kiwi.db            # SQLite (문서, 링크, 사용량)
+├── kiwi.db            # SQLite (문서, 링크, 퀴즈, 사용량)
 ├── uploads/           # 업로드된 파일
 └── _site/             # 빌드 결과
-    ├── index.html     # 홈 (문서 추가 UI + 사용량 대시보드)
+    ├── index.html     # 홈 (문서 목록)
     ├── graph.html     # 지식 그래프
+    ├── quiz.html      # 학습 퀴즈
     ├── wiki/          # 각 문서 페이지
+    │   └── random.html  # 임의 문서
     ├── static/        # CSS, JS, 로고
     └── search-index.json
 ```
@@ -220,11 +261,19 @@ project-dir/
 - **Cheerio** — 웹 페이지 파싱
 - **Mammoth** — DOCX 파싱
 - **JSZip** — PPTX 파싱
-- **Marked** — Markdown → HTML
+- **Marked** + **sanitize-html** — Markdown → 안전한 HTML
 - **D3.js** — 지식 그래프
 - **KaTeX** — 수학 수식 렌더링
 - **gh-pages** — GitHub Pages 배포
 
+## Security
+
+- Bearer 토큰 인증 (serve 모드)
+- SSRF 방지 (프라이빗 IP 차단, 리다이렉트 재검증)
+- Path Traversal 방지 (resolve 검증)
+- XSS 방지 (sanitize-html, CSP 헤더, escapeHtml)
+- 파일 업로드 제한 (50MB)
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open330/kiwimu",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Turn textbooks, PDFs, and web content into your own interlinked learning wiki powered by LLM",
   "type": "module",
   "bin": {

package/src/build/renderer.ts

@@ -141,6 +141,7 @@ export async function buildSite(store: Store, config: KiwiConfig, projectRoot: s
         id: q.id,
         question: q.question,
         answer: q.answer,
+        explanation: q.explanation || "",
         quiz_type: q.quiz_type,
         page_title: q.page_title,
         page_slug: q.page_slug,

package/src/build/templates.ts

@@ -289,7 +289,7 @@ export function renderGraph(opts: {
 
 export function renderQuizPage(opts: {
   wikiName: string;
-  quizzes: Array<{ id: number; question: string; answer: string; quiz_type: string; page_title?: string; page_slug?: string }>;
+  quizzes: Array<{ id: number; question: string; answer: string; explanation?: string; quiz_type: string; page_title?: string; page_slug?: string }>;
   sourcePages: PageLink[];
   conceptPages: PageLink[];
 }): string {
@@ -327,6 +327,9 @@ export function renderQuizPage(opts: {
                         <div id="quiz-result-icon" class="quiz-result-icon"></div>
                         <p class="quiz-answer-label">정답</p>
                         <p class="quiz-answer-text" id="quiz-answer-text"></p>
+                        <div id="quiz-explanation" class="quiz-explanation" style="display:none;">
+                            <p id="quiz-explanation-text" class="explanation-text"></p>
+                        </div>
                         <p class="quiz-source" id="quiz-source"></p>
                         <button id="quiz-next-btn" class="quiz-btn primary">다음 문제 →</button>
                     </div>
@@ -343,6 +346,11 @@ export function renderQuizPage(opts: {
                     <div id="quiz-score-bar" class="quiz-score-bar"></div>
                 </div>
                 <p id="quiz-score-msg" class="quiz-score-msg"></p>
+                <div id="quiz-stats" class="quiz-stats" style="display:none;">
+                    <h3>📊 학습 통계</h3>
+                    <p id="quiz-stats-summary"></p>
+                    <p id="quiz-stats-weak" style="display:none;"></p>
+                </div>
                 <button id="quiz-restart-btn" class="quiz-btn primary">🔄 다시 풀기</button>
             </div>
         </div>
@@ -395,6 +403,11 @@ export function renderQuizPage(opts: {
     .quiz-score-bar-container { height: 8px; background: var(--border); border-radius: 4px; overflow: hidden; margin: 16px 0 20px; }
     .quiz-score-bar { height: 100%; background: var(--accent, #4caf50); border-radius: 4px; transition: width 0.5s ease; }
     .quiz-score-msg { font-size: 16px; color: var(--text-muted); margin-bottom: 24px; }
+    .quiz-explanation { background: var(--accent-light, #e8f5e9); border-radius: 8px; padding: 12px 16px; margin-bottom: 16px; text-align: left; }
+    .explanation-text { font-size: 14px; line-height: 1.6; color: var(--text, #333); margin: 0; }
+    .quiz-stats { background: var(--bg-alt, #f5f5f5); border: 1px solid var(--border); border-radius: 8px; padding: 16px; margin-bottom: 20px; text-align: left; }
+    .quiz-stats h3 { font-size: 15px; margin: 0 0 8px; }
+    .quiz-stats p { font-size: 14px; color: var(--text-muted); margin: 4px 0; }
 </style>
 <script>
 (function() {
@@ -469,15 +482,29 @@ export function renderQuizPage(opts: {
 
         if (isCorrect) score++;
 
+        // Record attempt in localStorage
+        var attempts = JSON.parse(localStorage.getItem('kiwimu-quiz-attempts') || '[]');
+        attempts.push({ quizId: q.id, isCorrect: isCorrect, timestamp: new Date().toISOString() });
+        localStorage.setItem('kiwimu-quiz-attempts', JSON.stringify(attempts));
+
         document.getElementById('quiz-result-icon').textContent = isCorrect ? '🎉' : '😅';
         document.getElementById('quiz-answer-text').innerHTML = esc(q.answer);
         document.getElementById('quiz-answer-text').style.color = isCorrect ? 'var(--accent, #4caf50)' : '#e53935';
 
+        // Show explanation if available
+        var explanationEl = document.getElementById('quiz-explanation');
+        if (q.explanation) {
+            document.getElementById('quiz-explanation-text').textContent = '💡 ' + q.explanation;
+            explanationEl.style.display = 'block';
+        } else {
+            explanationEl.style.display = 'none';
+        }
+
         const sourceEl = document.getElementById('quiz-source');
         if (q.page_slug) {
             const a = document.createElement('a');
             a.href = '/wiki/' + encodeURIComponent(q.page_slug) + '.html';
-            a.textContent = q.page_title || q.page_slug;
+            a.textContent = '📖 ' + (q.page_title || q.page_slug) + ' 보기';
             sourceEl.textContent = '출처: ';
             sourceEl.appendChild(a);
         } else {
@@ -509,6 +536,35 @@ export function renderQuizPage(opts: {
 
         const msgs = pct >= 90 ? '🏆 완벽에 가깝습니다!' : pct >= 70 ? '👏 잘 하셨습니다!' : pct >= 50 ? '📚 조금 더 복습해보세요!' : '💪 다시 도전해보세요!';
         document.getElementById('quiz-score-msg').textContent = msgs;
+
+        // Show cumulative stats from localStorage
+        var allAttempts = JSON.parse(localStorage.getItem('kiwimu-quiz-attempts') || '[]');
+        if (allAttempts.length > 0) {
+            var totalAttempts = allAttempts.length;
+            var correctAttempts = allAttempts.filter(function(a) { return a.isCorrect; }).length;
+            var overallPct = Math.round(correctAttempts / totalAttempts * 100);
+
+            var statsEl = document.getElementById('quiz-stats');
+            statsEl.style.display = 'block';
+            document.getElementById('quiz-stats-summary').textContent = '전체 시도: ' + totalAttempts + '회 | 정답률: ' + overallPct + '%';
+
+            // Find weak concepts (most wrong answers by page)
+            var wrongByPage = {};
+            allAttempts.forEach(function(a) {
+                if (!a.isCorrect) {
+                    var q = ALL_QUIZZES.find(function(quiz) { return quiz.id === a.quizId; });
+                    if (q && q.page_title) {
+                        wrongByPage[q.page_title] = (wrongByPage[q.page_title] || 0) + 1;
+                    }
+                }
+            });
+            var weakConcepts = Object.keys(wrongByPage).sort(function(a, b) { return wrongByPage[b] - wrongByPage[a]; }).slice(0, 3);
+            if (weakConcepts.length > 0) {
+                var weakEl = document.getElementById('quiz-stats-weak');
+                weakEl.style.display = 'block';
+                weakEl.textContent = '💪 약한 개념: ' + weakConcepts.join(', ');
+            }
+        }
     }
 
     // Event listeners

package/src/demo/sample-data.ts

@@ -46,14 +46,14 @@ export const DEMO_PAGES = [
 ];
 
 export const DEMO_QUIZZES = [
-  { page_slug: "하이젠베르크", question: "___은 위치와 운동량을 동시에 정확히 측정할 수 없다는 양자역학의 원리이다.", answer: "불확정성 원리", quiz_type: "fill_blank" },
-  { page_slug: "슈뢰딩거-방정식", question: "슈뢰딩거 방정식은 1926년에 발표되었다.", answer: "O", quiz_type: "ox" },
-  { page_slug: "양자-중첩", question: "양자 중첩에서 관측하면 어떤 현상이 일어나는가?", answer: "중첩이 붕괴하여 하나의 상태만 남는다", quiz_type: "short_answer" },
-  { page_slug: "양자-얽힘", question: "아인슈타인은 양자 얽힘을 '___한 원격 작용'이라 불렀다.", answer: "으스스", quiz_type: "fill_blank" },
-  { page_slug: "양자-중첩", question: "슈뢰딩거의 고양이 사고실험에서 고양이는 살아있는 상태와 죽어있는 상태의 ___에 놓인다.", answer: "중첩", quiz_type: "fill_blank" },
-  { page_slug: "양자-얽힘", question: "2022년 노벨 물리학상은 양자 얽힘의 벨 부등식 실험 검증과 관련이 있다.", answer: "O", quiz_type: "ox" },
-  { page_slug: "슈뢰딩거-방정식", question: "시간 독립 슈뢰딩거 방정식에서 E는 무엇을 나타내는가?", answer: "에너지 고유값", quiz_type: "short_answer" },
-  { page_slug: "하이젠베르크", question: "불확정성 원리에서 Δx·Δp ≥ ℏ/2 이다.", answer: "O", quiz_type: "ox" },
+  { page_slug: "하이젠베르크", question: "___은 위치와 운동량을 동시에 정확히 측정할 수 없다는 양자역학의 원리이다.", answer: "불확정성 원리", explanation: "하이젠베르크가 1927년에 제안한 이 원리는 양자역학의 근본적 한계를 보여줍니다. 위치를 정확히 측정하면 운동량의 불확정성이 커지고, 그 반대도 마찬가지입니다.", quiz_type: "fill_blank" },
+  { page_slug: "슈뢰딩거-방정식", question: "슈뢰딩거 방정식은 1926년에 발표되었다.", answer: "O", explanation: "에르빈 슈뢰딩거가 1926년에 발표한 이 방정식은 양자계의 시간 변화를 기술하는 기본 방정식입니다.", quiz_type: "ox" },
+  { page_slug: "양자-중첩", question: "양자 중첩에서 관측하면 어떤 현상이 일어나는가?", answer: "중첩이 붕괴하여 하나의 상태만 남는다", explanation: "관측 행위가 양자 시스템에 영향을 주어 여러 가능한 상태 중 하나로 '붕괴'됩니다. 이를 파동함수 붕괴라고 합니다.", quiz_type: "short_answer" },
+  { page_slug: "양자-얽힘", question: "아인슈타인은 양자 얽힘을 '___한 원격 작용'이라 불렀다.", answer: "으스스", explanation: "아인슈타인은 양자 얽힘이 국소적 실재론에 위배된다고 생각하여 'spooky action at a distance(으스스한 원격 작용)'이라 비판했습니다.", quiz_type: "fill_blank" },
+  { page_slug: "양자-중첩", question: "슈뢰딩거의 고양이 사고실험에서 고양이는 살아있는 상태와 죽어있는 상태의 ___에 놓인다.", answer: "중첩", explanation: "이 사고실험은 양자 중첩의 개념을 거시적 세계에 적용하여 양자역학의 해석 문제를 드러내기 위해 고안되었습니다.", quiz_type: "fill_blank" },
+  { page_slug: "양자-얽힘", question: "2022년 노벨 물리학상은 양자 얽힘의 벨 부등식 실험 검증과 관련이 있다.", answer: "O", explanation: "알랭 아스페, 존 클라우저, 안톤 차일링거가 벨 부등식 위반을 실험적으로 증명하여 양자 얽힘의 실재성을 확인한 공로로 수상했습니다.", quiz_type: "ox" },
+  { page_slug: "슈뢰딩거-방정식", question: "시간 독립 슈뢰딩거 방정식에서 E는 무엇을 나타내는가?", answer: "에너지 고유값", explanation: "시간 독립 슈뢰딩거 방정식 Hψ = Eψ에서 E는 시스템의 에너지 고유값으로, 허용된 에너지 준위를 나타냅니다.", quiz_type: "short_answer" },
+  { page_slug: "하이젠베르크", question: "불확정성 원리에서 Δx·Δp ≥ ℏ/2 이다.", answer: "O", explanation: "이 부등식은 위치의 불확정성(Δx)과 운동량의 불확정성(Δp)의 곱이 플랑크 상수의 절반 이상임을 나타냅니다.", quiz_type: "ox" },
 ];
 
 export const DEMO_LINKS = [

package/src/demo/setup.ts

@@ -25,7 +25,7 @@ export async function setupDemo(store: Store): Promise<void> {
   for (const quiz of DEMO_QUIZZES) {
     const page = store.getPage(quiz.page_slug);
     if (page) {
-      store.addQuiz(page.id, quiz.question, quiz.answer, quiz.quiz_type);
+      store.addQuiz(page.id, quiz.question, quiz.answer, quiz.quiz_type, (quiz as any).explanation || "");
     }
   }
 }

package/src/index.ts

@@ -8,7 +8,7 @@ import { Store } from "./store";
 const program = new Command()
   .name("kiwimu")
   .description("🥝 Kiwi Mu — 나만의 학습 위키를 만드세요")
-  .version("0.7.1");
+  .version("0.8.0");
 
 // --- init ---
 program
@@ -144,8 +144,15 @@ program
         const absPath = resolve(source);
         const file = Bun.file(absPath);
         if (!(await file.exists())) {
-          console.log(`\x1b[31m파일을 찾을 수 없습니다: ${source}\x1b[0m`);
-          return;
+          console.error(`\x1b[31m❌ 파일을 찾을 수 없습니다: ${source}\x1b[0m`);
+          process.exit(1);
+        }
+        const ext = source.split(".").pop()?.toLowerCase() || "";
+        const SUPPORTED_EXTENSIONS = ['pdf', 'docx', 'pptx', 'doc', 'ppt', 'key', 'rtf'];
+        if (!SUPPORTED_EXTENSIONS.includes(ext)) {
+          console.error(`\x1b[31m❌ 지원하지 않는 파일 형식입니다: .${ext}\x1b[0m`);
+          console.error(`   지원 형식: ${SUPPORTED_EXTENSIONS.join(', ')}`);
+          process.exit(1);
         }
         console.log(`\x1b[34m📥 파일 처리 중: ${source}\x1b[0m`);
         const { ingestFile } = await import("./services/ingest");
@@ -153,6 +160,10 @@ program
         console.log(`\x1b[32m✅ 📖 ${result.sourceCount}개 원본 + 📝 ${result.conceptCount}개 개념 문서 생성\x1b[0m`);
         console.log(`\x1b[34m📊 LLM: ${result.usage.totalCalls}회 호출, ~$${result.usage.estimatedCostUsd.toFixed(4)}\x1b[0m`);
       }
+    } catch (e: unknown) {
+      const message = e instanceof Error ? e.message : String(e);
+      console.error(`\x1b[31m❌ ${message}\x1b[0m`);
+      process.exit(1);
     } finally {
       store.close();
     }
@@ -198,7 +209,7 @@ program
           store.updatePageContent(page.id, newContent);
         } catch (e: unknown) {
           const message = e instanceof Error ? e.message : String(e);
-          console.log(`    \x1b[31m실패: ${message}\x1b[0m`);
+          console.error(`    \x1b[31m❌ 실패: ${message}\x1b[0m`);
         }
       }
 
@@ -270,7 +281,8 @@ program
       await deployVercel(siteDir);
       console.log("\x1b[32m✅ Vercel에 배포되었습니다!\x1b[0m");
     } else {
-      console.log(`\x1b[31m지원하지 않는 배포 대상: ${opts.target}\x1b[0m`);
+      console.error(`\x1b[31m❌ 지원하지 않는 배포 대상: ${opts.target}\x1b[0m`);
+      process.exit(1);
     }
   });
 
@@ -308,7 +320,7 @@ program
     try {
       store.initSchema(); // ensure quizzes table exists
       const count = parseInt(opts.count) || 5;
-      const quizzes = store.getRandomQuizzes(count);
+      const quizzes = store.getSmartQuizzes(count);
       if (quizzes.length === 0) {
         console.log("\x1b[33m퀴즈가 없습니다. 먼저 문서를 추가하세요.\x1b[0m");
         return;
@@ -350,16 +362,21 @@ program
           return;
         }
 
-        const correct = q.answer.trim().toLowerCase();
-        const user = (userAnswer as string).trim().toLowerCase();
-        const isCorrect = user === correct || (correct.includes(user) && user.length > 0);
+        const norm = (s: string) => s.trim().toLowerCase().replace(/\s+/g, ' ');
+        const isCorrect = norm(userAnswer as string) === norm(q.answer);
+
+        store.addQuizAttempt(q.id, isCorrect);
 
         if (isCorrect) {
           score++;
-          console.log(`  \x1b[32m✅ 정답!\x1b[0m\n`);
+          console.log(`  \x1b[32m✅ 정답!\x1b[0m`);
         } else {
-          console.log(`  \x1b[31m❌ 오답! 정답: ${q.answer}\x1b[0m\n`);
+          console.log(`  \x1b[31m❌ 오답! 정답: ${q.answer}\x1b[0m`);
+        }
+        if (q.explanation) {
+          console.log(`  \x1b[36m💡 ${q.explanation}\x1b[0m`);
         }
+        console.log();
       }
 
       const pct = Math.round((score / quizzes.length) * 100);
@@ -369,6 +386,15 @@ program
       else if (pct >= 50) console.log("  📚 조금 더 복습해보세요!");
       else console.log("  💪 다시 도전해보세요!");
 
+      const stats = store.getQuizStats();
+      if (stats.total > 0) {
+        const overallPct = Math.round(stats.correct / stats.total * 100);
+        console.log(`\n📊 전체 통계: ${stats.correct}/${stats.total} 정답 (${overallPct}%)`);
+        if (stats.unattempted > 0) {
+          console.log(`  📋 미시도 퀴즈: ${stats.unattempted}개`);
+        }
+      }
+
       p.outro("학습을 계속하세요! 🥝");
     } finally {
       store.close();

package/src/pipeline/llm-chunker.ts

@@ -233,9 +233,10 @@ export async function llmChunkDocument(
   if (persona) {
     console.log(`\x1b[35m🎭 페르소나: ${persona.name}\x1b[0m`);
   }
-  console.log(`\x1b[34m🧠 Phase 1: 원본 구조 추출 (${chunks.length}개 청크)...\x1b[0m`);
+  console.log(`\x1b[34m⏳ Phase 1: 원본 구조 추출 중... (${chunks.length}개 청크)\x1b[0m`);
 
   // ── Phase 1: Extract source pages (parallel LLM calls) ──
+  const phase1Start = performance.now();
   let completedCount = 0;
   const structureSystem = getStructureSystem(persona);
 
@@ -289,10 +290,12 @@ export async function llmChunkDocument(
   }
 
   const sourceCount = orderCounter;
-  console.log(`\x1b[32m  📖 ${sourceCount}개 원본 페이지 생성 완료\x1b[0m`);
+  const phase1Sec = ((performance.now() - phase1Start) / 1000).toFixed(1);
+  console.log(`\x1b[32m✅ Phase 1 완료 (${phase1Sec}초) — 📖 ${sourceCount}개 원본 페이지 생성\x1b[0m`);
 
   // ── Phase 2: Extract concept pages ──
-  console.log(`\x1b[34m🧠 Phase 2: 개념 페이지 추출...\x1b[0m`);
+  const phase2Start = performance.now();
+  console.log(`\x1b[34m⏳ Phase 2: 개념 추출 중...\x1b[0m`);
 
   // Process source pages in small batches for concept extraction
   const batchSize = 5;
@@ -340,21 +343,24 @@ export async function llmChunkDocument(
     }
   }
 
-  console.log(`\x1b[32m  📝 ${conceptCount}개 개념 페이지 생성 완료\x1b[0m`);
+  const phase2Sec = ((performance.now() - phase2Start) / 1000).toFixed(1);
+  console.log(`\x1b[32m✅ Phase 2 완료 (${phase2Sec}초) — 📝 ${conceptCount}개 개념 페이지 생성\x1b[0m`);
 
   // ── Phase 2.5: Generate quizzes from concept pages ──
   let quizCount = 0;
   try {
     const conceptPagesForQuiz = store.listConceptPages();
     if (conceptPagesForQuiz.length > 0) {
-      console.log(`\x1b[34m🧠 Phase 2.5: 퀴즈 생성 (${conceptPagesForQuiz.length}개 개념 페이지)...\x1b[0m`);
+      console.log(`\x1b[34m⏳ Phase 2.5: 퀴즈 생성 중... (${conceptPagesForQuiz.length}개 개념 페이지)\x1b[0m`);
 
-      const quizSystem = `You are a quiz generator for a study wiki. Generate quiz questions based on wiki content.
+      const quizSystem = `You are a quiz generator for a study wiki. Generate quiz questions that test UNDERSTANDING, not just memorization.
+Focus on higher-order thinking: "왜?", "어떻게?", "비교하라", "설명하라" style questions.
 Return valid JSON only. No markdown fences.`;
 
       await parallelMap(conceptPagesForQuiz, 3, async (page, i) => {
         try {
-          const quizPrompt = `Based on this wiki content, generate 2-3 quiz questions in JSON format.
+          const quizPrompt = `Based on this wiki content, generate 2-3 quiz questions that test UNDERSTANDING, not just memorization.
+Include questions that ask "왜?", "어떻게?", "비교하라" etc.
 Types: "fill_blank" (빈칸 채우기), "ox" (OX 퀴즈 - true/false), "short_answer" (단답형)
 
 Content title: ${page.title}
@@ -362,21 +368,22 @@ Content:
 ${page.content.slice(0, 3000)}
 
 Respond with a JSON array only:
-[{"question": "___은 양자역학에서 위치와 운동량을 동시에 측정할 수 없다는 원리이다.", "answer": "불확정성 원리", "type": "fill_blank"}]
+[{"question": "___은 양자역학에서 위치와 운동량을 동시에 측정할 수 없다는 원리이다.", "answer": "불확정성 원리", "explanation": "이 원리는 양자역학의 근본적 한계를 보여주며, 측정 행위 자체가 시스템에 영향을 주기 때문입니다.", "type": "fill_blank"}]
 
 Rules:
 - For fill_blank: use ___ to mark the blank in the question
 - For ox: question should be a statement, answer should be "O" or "X"
 - For short_answer: question should be answerable in 1-3 words
-- Questions should test understanding, not just recall
+- Include "explanation" field: a brief 1-2 sentence explanation of WHY the answer is correct
+- Questions should test understanding, application, or analysis — not just recall
 - Write questions in Korean when the content is in Korean`;
 
           const raw = await chat(quizSystem, quizPrompt, 2048);
-          const quizzes = parseJSON<Array<{ question: string; answer: string; type: string }>>(raw);
+          const quizzes = parseJSON<Array<{ question: string; answer: string; explanation?: string; type: string }>>(raw);
 
           for (const q of quizzes) {
             if (q.question && q.answer && q.type) {
-              store.addQuiz(page.id, q.question, q.answer, q.type);
+              store.addQuiz(page.id, q.question, q.answer, q.type, q.explanation || "");
               quizCount++;
             }
           }

package/src/server.ts

@@ -172,7 +172,7 @@ export function startServer(root: string, port: number, host: string): void {
             console.log("\x1b[32m✅ 설정 변경 후 사이트 리빌드 완료\x1b[0m");
           } catch (e: unknown) {
             const message = e instanceof Error ? e.message : String(e);
-            console.log(`\x1b[31m리빌드 실패: ${message}\x1b[0m`);
+            console.error(`\x1b[31m❌ 리빌드 실패: ${message}\x1b[0m`);
           } finally {
             store.close();
           }

package/src/services/ingest.ts

@@ -23,13 +23,13 @@ export async function ingestUrl(
   const { fetchPage } = await import("../ingest/web");
   const { llmChunkDocument, htmlToRawText } = await import("../pipeline/llm-chunker");
 
-  onProgress?.("URL 가져오는 중...");
+  onProgress?.("⏳ URL 가져오는 중...");
   const { title, html } = await fetchPage(url);
 
   const source = store.addSource(url, "web", title, html);
   const rawText = htmlToRawText(html);
 
-  onProgress?.("LLM 분석 중...");
+  onProgress?.("⏳ LLM 분석 시작...");
   const { sourceCount, conceptCount } = await llmChunkDocument(rawText, title, source.id, store, 0, persona, client);
 
   const u = client.getUsageStats();
@@ -65,26 +65,26 @@ export async function ingestFile(
 
   if (ext === "pdf") {
     const { extractTextFromPdf } = await import("../ingest/pdf");
-    onProgress?.("PDF 텍스트 추출 중...");
+    onProgress?.("⏳ PDF 텍스트 추출 중...");
     ({ title, text } = await extractTextFromPdf(filePath));
   } else if (ext === "docx") {
     const { extractTextFromDocx } = await import("../ingest/docx");
-    onProgress?.("DOCX 텍스트 추출 중...");
+    onProgress?.("⏳ DOCX 텍스트 추출 중...");
     ({ title, text } = await extractTextFromDocx(filePath));
   } else if (ext === "pptx") {
     const { extractTextFromPptx } = await import("../ingest/pptx");
-    onProgress?.("PPTX 텍스트 추출 중...");
+    onProgress?.("⏳ PPTX 텍스트 추출 중...");
     ({ title, text } = await extractTextFromPptx(filePath));
   } else {
     const { extractWithTextutil } = await import("../ingest/legacy");
-    onProgress?.(`${ext.toUpperCase()} 텍스트 추출 중...`);
+    onProgress?.(`⏳ ${ext.toUpperCase()} 텍스트 추출 중...`);
     ({ title, text } = await extractWithTextutil(filePath));
   }
 
   const source = store.addSource(filePath, ext, title, "(file)");
   store.deletePagesBySource(source.id);
 
-  onProgress?.("LLM 분석 중...");
+  onProgress?.("⏳ LLM 분석 시작...");
   const { sourceCount, conceptCount } = await llmChunkDocument(text, title, source.id, store, 0, persona, client);
 
   const u = client.getUsageStats();

package/src/store.ts

@@ -39,6 +39,7 @@ export interface Quiz {
   page_id: number;
   question: string;
   answer: string;
+  explanation: string;
   quiz_type: string; // 'fill_blank' | 'ox' | 'short_answer'
   created_at: string;
   page_title?: string;
@@ -87,11 +88,20 @@ CREATE TABLE IF NOT EXISTS quizzes (
   page_id INTEGER NOT NULL,
   question TEXT NOT NULL,
   answer TEXT NOT NULL,
+  explanation TEXT DEFAULT '',
   quiz_type TEXT NOT NULL DEFAULT 'fill_blank',
   created_at TEXT DEFAULT (datetime('now')),
   FOREIGN KEY (page_id) REFERENCES pages(id)
 );
+CREATE TABLE IF NOT EXISTS quiz_attempts (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  quiz_id INTEGER NOT NULL,
+  is_correct INTEGER NOT NULL DEFAULT 0,
+  attempted_at TEXT DEFAULT (datetime('now')),
+  FOREIGN KEY (quiz_id) REFERENCES quizzes(id)
+);
 CREATE INDEX IF NOT EXISTS idx_pages_source_id ON pages(source_id);
+CREATE INDEX IF NOT EXISTS idx_attempts_quiz_id ON quiz_attempts(quiz_id);
 CREATE INDEX IF NOT EXISTS idx_pages_page_type ON pages(page_type);
 CREATE INDEX IF NOT EXISTS idx_links_to_page ON links(to_page_id);
 CREATE INDEX IF NOT EXISTS idx_links_from_page ON links(from_page_id);
@@ -109,6 +119,12 @@ export class Store {
 
   initSchema(): void {
     this.db.exec(SCHEMA);
+    // Migrate: add explanation column if missing (for existing databases)
+    try {
+      this.db.exec("ALTER TABLE quizzes ADD COLUMN explanation TEXT DEFAULT ''");
+    } catch {
+      // Column already exists — ignore
+    }
   }
 
   close(): void {
@@ -184,7 +200,11 @@ export class Store {
   }
 
   deletePagesBySource(sourceId: number): void {
-    // Delete quizzes for these pages first
+    // Delete quiz attempts for quizzes on these pages first
+    this.db.prepare(
+      "DELETE FROM quiz_attempts WHERE quiz_id IN (SELECT id FROM quizzes WHERE page_id IN (SELECT id FROM pages WHERE source_id = ?))"
+    ).run(sourceId);
+    // Delete quizzes for these pages
     this.db.prepare(
       "DELETE FROM quizzes WHERE page_id IN (SELECT id FROM pages WHERE source_id = ?)"
     ).run(sourceId);
@@ -196,6 +216,7 @@ export class Store {
   }
 
   deleteAllPages(): void {
+    this.db.exec("DELETE FROM quiz_attempts");
     this.db.exec("DELETE FROM quizzes");
     this.db.exec("DELETE FROM links");
     this.db.exec("DELETE FROM pages");
@@ -252,10 +273,10 @@ export class Store {
 
   // --- Quizzes ---
 
-  addQuiz(pageId: number, question: string, answer: string, quizType: string): void {
+  addQuiz(pageId: number, question: string, answer: string, quizType: string, explanation: string = ""): void {
     this.db
-      .prepare("INSERT INTO quizzes (page_id, question, answer, quiz_type) VALUES (?, ?, ?, ?)")
-      .run(pageId, question, answer, quizType);
+      .prepare("INSERT INTO quizzes (page_id, question, answer, explanation, quiz_type) VALUES (?, ?, ?, ?, ?)")
+      .run(pageId, question, answer, explanation, quizType);
   }
 
   getQuizzesByPage(pageId: number): Quiz[] {
@@ -292,6 +313,89 @@ export class Store {
     this.db.prepare("DELETE FROM quizzes WHERE page_id = ?").run(pageId);
   }
 
+  getSmartQuizzes(count: number): Quiz[] {
+    return this.db.prepare(`
+      SELECT q.*, p.title as page_title, p.slug as page_slug,
+        COALESCE(a.last_attempt, '1970-01-01') as last_attempt,
+        COALESCE(a.correct_count, 0) as correct_count,
+        COALESCE(a.wrong_count, 0) as wrong_count
+      FROM quizzes q
+      JOIN pages p ON p.id = q.page_id
+      LEFT JOIN (
+        SELECT quiz_id,
+          MAX(attempted_at) as last_attempt,
+          SUM(CASE WHEN is_correct = 1 THEN 1 ELSE 0 END) as correct_count,
+          SUM(CASE WHEN is_correct = 0 THEN 1 ELSE 0 END) as wrong_count
+        FROM quiz_attempts
+        GROUP BY quiz_id
+      ) a ON a.quiz_id = q.id
+      ORDER BY
+        CASE WHEN a.last_attempt IS NULL THEN 0 ELSE 1 END,
+        CASE WHEN a.wrong_count > 0 THEN 0 ELSE 1 END,
+        a.last_attempt ASC
+      LIMIT ?
+    `).all(count) as Quiz[];
+  }
+
+  // --- Quiz Attempts ---
+
+  addQuizAttempt(quizId: number, isCorrect: boolean): void {
+    this.db
+      .prepare("INSERT INTO quiz_attempts (quiz_id, is_correct) VALUES (?, ?)")
+      .run(quizId, isCorrect ? 1 : 0);
+  }
+
+  getQuizStats(): { total: number; correct: number; incorrect: number; unattempted: number } {
+    const totalQuizzes = (this.db.prepare("SELECT COUNT(*) as cnt FROM quizzes").get() as { cnt: number }).cnt;
+    const attemptRow = this.db.prepare(`
+      SELECT COUNT(*) as total,
+        SUM(CASE WHEN is_correct = 1 THEN 1 ELSE 0 END) as correct,
+        SUM(CASE WHEN is_correct = 0 THEN 1 ELSE 0 END) as incorrect
+      FROM quiz_attempts
+    `).get() as { total: number; correct: number; incorrect: number };
+    const attemptedQuizzes = (this.db.prepare("SELECT COUNT(DISTINCT quiz_id) as cnt FROM quiz_attempts").get() as { cnt: number }).cnt;
+    return {
+      total: attemptRow.total,
+      correct: attemptRow.correct,
+      incorrect: attemptRow.incorrect,
+      unattempted: totalQuizzes - attemptedQuizzes,
+    };
+  }
+
+  getWeakQuizzes(limit: number): Quiz[] {
+    return this.db.prepare(`
+      SELECT q.*, p.title as page_title, p.slug as page_slug
+      FROM quizzes q
+      JOIN pages p ON p.id = q.page_id
+      LEFT JOIN (
+        SELECT quiz_id,
+          SUM(CASE WHEN is_correct = 0 THEN 1 ELSE 0 END) as wrong_count,
+          COUNT(*) as attempt_count
+        FROM quiz_attempts
+        GROUP BY quiz_id
+      ) a ON a.quiz_id = q.id
+      ORDER BY
+        CASE WHEN a.attempt_count IS NULL THEN 1 ELSE 0 END DESC,
+        COALESCE(a.wrong_count, 0) DESC
+      LIMIT ?
+    `).all(limit) as Quiz[];
+  }
+
+  getQuizHistory(limit: number): Array<{ quiz_id: number; question: string; is_correct: boolean; attempted_at: string }> {
+    return this.db.prepare(`
+      SELECT qa.quiz_id, q.question, qa.is_correct, qa.attempted_at
+      FROM quiz_attempts qa
+      JOIN quizzes q ON q.id = qa.quiz_id
+      ORDER BY qa.attempted_at DESC
+      LIMIT ?
+    `).all(limit).map((row: any) => ({
+      quiz_id: row.quiz_id,
+      question: row.question,
+      is_correct: row.is_correct === 1,
+      attempted_at: row.attempted_at,
+    }));
+  }
+
   // --- Usage ---
 
   addUsageLog(sourceId: number, calls: number, prompt: number, completion: number, total: number, cost: number): void {