elanous 0.2.9 → 0.2.11

package/skills/lecture-note-digitizer/references/convert_to_pdf.py

@@ -0,0 +1,30 @@
+"""Convert integrated lecture notes HTML to PDF using Playwright."""
+import sys
+from pathlib import Path
+
+def main():
+    html_path = Path(sys.argv[1]) if len(sys.argv) > 1 else None
+    if not html_path or not html_path.exists():
+        print(f"Usage: python convert_to_pdf.py <html_file>")
+        sys.exit(1)
+
+    pdf_path = html_path.with_suffix(".pdf")
+
+    from playwright.sync_api import sync_playwright
+    with sync_playwright() as p:
+        browser = p.chromium.launch()
+        page = browser.new_page()
+        page.goto(f"file://{html_path.resolve()}")
+        page.wait_for_timeout(2000)
+        page.pdf(
+            path=str(pdf_path),
+            format="A4",
+            margin={"top": "15mm", "bottom": "15mm",
+                    "left": "15mm", "right": "15mm"},
+            print_background=True,
+        )
+        browser.close()
+    print(pdf_path)
+
+if __name__ == "__main__":
+    main()

package/skills/lecture-note-digitizer/references/extract_slide_diagram.py

@@ -0,0 +1,73 @@
+"""Extract specific slides from PDF as high-quality PNG images.
+
+Usage:
+    python extract_slide_diagram.py input.pdf --page 11
+    python extract_slide_diagram.py input.pdf --page 11 --output diagram.png
+    python extract_slide_diagram.py input.pdf --page 11 --crop "5,15,90,70"
+    python extract_slide_diagram.py input.pdf --pages 9,11,19,20
+
+Crop: percentage coordinates "left,top,width,height" (0-100).
+DPI: default 300 for high quality. Use --dpi 450 for extra sharp.
+"""
+import argparse
+import sys
+from pathlib import Path
+
+
+def extract_page(pdf_path: Path, page_num: int, output_path: Path,
+                 crop: str | None = None, dpi: int = 300):
+    import fitz  # PyMuPDF
+
+    doc = fitz.open(str(pdf_path))
+    if page_num < 1 or page_num > len(doc):
+        print(f"Page {page_num} out of range (1-{len(doc)})")
+        return None
+
+    page = doc[page_num - 1]  # 0-indexed
+    mat = fitz.Matrix(dpi / 72, dpi / 72)
+
+    clip = None
+    if crop:
+        parts = [float(x) for x in crop.split(",")]
+        r = page.rect
+        clip = fitz.Rect(
+            r.x0 + parts[0] / 100 * r.width,
+            r.y0 + parts[1] / 100 * r.height,
+            r.x0 + (parts[0] + parts[2]) / 100 * r.width,
+            r.y0 + (parts[1] + parts[3]) / 100 * r.height,
+        )
+
+    pix = page.get_pixmap(matrix=mat, clip=clip)
+
+    pix.save(str(output_path))
+    doc.close()
+    print(f"✅ Page {page_num} → {output_path} ({pix.width}x{pix.height}px)")
+    return output_path
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="PDF 슬라이드에서 다이어그램 추출")
+    parser.add_argument("input", type=Path, help="PDF 파일 경로")
+    parser.add_argument("--page", "-p", type=int, default=None, help="추출할 페이지 번호")
+    parser.add_argument("--pages", type=str, default=None, help="여러 페이지 (쉼표 구분: 9,11,19)")
+    parser.add_argument("--output", "-o", type=Path, default=None, help="출력 PNG 경로")
+    parser.add_argument("--crop", "-c", type=str, default=None,
+                        help="크롭 영역 (%%): left,top,width,height")
+    parser.add_argument("--dpi", type=int, default=300, help="렌더링 DPI (기본: 300)")
+    args = parser.parse_args()
+
+    if not args.input.exists():
+        print(f"파일 없음: {args.input}")
+        sys.exit(1)
+
+    if args.pages:
+        page_nums = [int(p.strip()) for p in args.pages.split(",")]
+        for pn in page_nums:
+            out = args.input.with_name(f"{args.input.stem}_page{pn}.png")
+            extract_page(args.input, pn, out, args.crop, args.dpi)
+    elif args.page:
+        out = args.output or args.input.with_name(f"{args.input.stem}_page{args.page}.png")
+        extract_page(args.input, args.page, out, args.crop, args.dpi)
+    else:
+        print("--page 또는 --pages 옵션을 지정해주세요")
+        sys.exit(1)

package/skills/lecture-note-digitizer/references/html-template.md

@@ -0,0 +1,167 @@
+# HTML 템플릿 — 학습노트 PDF용 (v2, 2026-04-06)
+
+그라데이션 커버 + 카드 TOC + 섹션 래퍼 스타일. eco_lecture/scm_lecture 공통 템플릿.
+
+## 표준 HTML 구조
+
+```html
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+  <meta charset="UTF-8">
+  <title>{과목코드} {과목명} {N}주차 학습 노트</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css">
+  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js"></script>
+  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js"
+    onload="renderMathInElement(document.body,{delimiters:[
+      {left:'$$',right:'$$',display:true},
+      {left:'\\(',right:'\\)',display:false},
+      {left:'\\[',right:'\\]',display:true}
+    ]});"></script>
+  <style>{CSS}</style>
+</head>
+<body>
+
+<!-- COVER PAGE: 그라데이션 배경, 흰색 텍스트 -->
+<div class="cover">
+  <h1>{과목코드} {과목명} {N}주차 학습 노트</h1>
+  <h2>{부제: 주차 핵심 주제}</h2>
+  <div class="meta">
+    <p><strong>과목명:</strong> {영문명}</p>
+    <p><strong>프로그램:</strong> {프로그램}</p>
+    <p><strong>교수:</strong> {교수명}</p>
+    <p><strong>일시:</strong> {날짜}</p>
+  </div>
+  <div class="badge">핵심 키워드: {키워드}</div>
+</div>
+
+<!-- TOC: 카드 스타일, 자동 생성 -->
+<div class="toc">
+  <h2>목차</h2>
+  {build_toc()으로 자동 생성된 <ol>}
+</div>
+
+<!-- CONTENT -->
+<div class="section">
+  {html_body}
+</div>
+</body>
+</html>
+```
+
+## CSS
+
+```css
+* { margin: 0; padding: 0; box-sizing: border-box; }
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Noto Sans KR', sans-serif;
+  font-size: 16px; line-height: 1.8; color: #1a1a2e; background: #f8f9fc;
+}
+
+.section {
+  background: #fff; border-radius: 12px; padding: 40px;
+  max-width: 900px; margin: 24px auto;
+  box-shadow: 0 4px 24px rgba(0,0,0,0.06);
+}
+
+/* Cover — 그라데이션 */
+.cover {
+  min-height: 100vh; display: flex; flex-direction: column;
+  justify-content: center; align-items: center; text-align: center;
+  background: linear-gradient(135deg, #1e3a5f 0%, #3b82f6 50%, #8b5cf6 100%);
+  color: #fff; padding: 60px 40px; page-break-after: always;
+}
+.cover h1 { font-size: 2.6em; font-weight: 800; margin-bottom: 16px; border-bottom: none; letter-spacing: -0.02em; }
+/* 주의: text-shadow 사용 금지 — Playwright PDF에서 한국어 대형 텍스트에 회색 박스 아티팩트 발생 */
+/* 제목이 길면 <br><span style="font-size:0.75em;font-weight:400;">부제</span>로 2줄 분리 */
+.cover h2 { font-size: 1.4em; font-weight: 400; opacity: 0.9; margin-bottom: 40px; }
+.cover .meta { font-size: 1em; opacity: 0.8; line-height: 2; }
+.cover .meta strong { opacity: 1; }
+.cover .badge {
+  display: inline-block; background: rgba(255,255,255,0.2);
+  border: 1px solid rgba(255,255,255,0.3); border-radius: 20px;
+  padding: 6px 20px; margin-top: 30px; font-size: 0.9em;
+}
+
+/* TOC — 카드 */
+.toc {
+  background: #fff; border-radius: 12px; padding: 40px;
+  margin: 40px auto; max-width: 900px;
+  box-shadow: 0 2px 12px rgba(0,0,0,0.06); page-break-after: always;
+}
+.toc h2 { font-size: 1.6em; color: #1e3a5f; margin-bottom: 24px; border-bottom: 3px solid #3b82f6; }
+.toc ol { list-style: none; counter-reset: toc-counter; }
+.toc > ol > li { counter-increment: toc-counter; margin-bottom: 8px; }
+.toc > ol > li > a {
+  display: block; padding: 10px 16px; color: #1e3a5f;
+  text-decoration: none; font-weight: 600; border-radius: 8px;
+}
+.toc > ol > li > a::before { content: counter(toc-counter) ". "; color: #3b82f6; font-weight: 700; }
+.toc ol ol { margin-left: 24px; margin-top: 4px; }
+.toc ol ol li a { display: block; padding: 5px 12px; color: #475569; font-size: 0.95em; border-radius: 6px; }
+
+/* Typography */
+h1 { font-size: 2em; color: #1e3a5f; margin: 32px 0 20px; border-bottom: 3px solid #3b82f6; page-break-before: always; }
+.section h1:first-child { page-break-before: avoid; }
+h2 { font-size: 1.5em; color: #1e3a5f; margin: 28px 0 16px; border-bottom: 2px solid #e2e8f0; }
+h3 { font-size: 1.2em; color: #334155; margin: 20px 0 12px; }
+
+/* Tables — 그라데이션 헤더 */
+table { width: 100%; border-collapse: collapse; margin: 20px 0; border-radius: 8px; overflow: hidden; box-shadow: 0 1px 4px rgba(0,0,0,0.08); }
+thead th { background: linear-gradient(135deg, #1e3a5f, #3b82f6); color: #fff; padding: 12px 16px; }
+tbody td { padding: 10px 16px; border-bottom: 1px solid #e2e8f0; }
+tbody tr:nth-child(even) { background: #f8fafc; }
+
+/* Blockquotes — 3종 */
+blockquote { background: linear-gradient(135deg, #eef2ff, #f0f4ff); border-left: 4px solid #3b82f6; padding: 16px 20px; margin: 16px 0; border-radius: 0 8px 8px 0; }
+.formula-box { background: linear-gradient(135deg, #fefce8, #fef9c3); border-left: 4px solid #f59e0b; border-radius: 10px; }
+.case-box { background: linear-gradient(135deg, #ecfdf5, #d1fae5); border-left: 4px solid #10b981; }
+
+/* Diagrams */
+.diagram-container { text-align: center; margin: 24px 0; padding: 16px; background: #fafbff; border-radius: 10px; border: 1px solid #e2e8f0; page-break-inside: avoid; }
+.diagram-container img { max-width: 100%; max-height: 500px; height: auto; object-fit: contain; border-radius: 8px; }
+.diagram-caption { margin-top: 10px; font-size: 0.88em; color: #64748b; font-style: italic; }
+
+/* HR */
+hr { border: none; height: 2px; background: linear-gradient(90deg, #3b82f6, #8b5cf6); margin: 32px 0; }
+
+/* Print */
+@media print {
+  body { background: #fff; font-size: 14px; }
+  .section { box-shadow: none; margin: 0; padding: 24px 0; }
+  .cover { min-height: auto; -webkit-print-color-adjust: exact; print-color-adjust: exact; }
+  .cover h1 { page-break-before: avoid; border-bottom: none; }
+  thead th { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
+  .diagram-container img { max-height: 400px; }
+  table, .diagram-container, blockquote, .formula-box { page-break-inside: avoid; }
+  h2, h3 { page-break-after: avoid; }
+}
+```
+
+## Python 필수 함수 (convert_to_pdf.py에 포함)
+
+### LaTeX 보호/복원 (markdown 라이브러리가 `\(` backslash 제거 방지)
+```python
+text = text.replace(r"\(", "LATEX_INLINE_OPEN")  # 변환 전
+html = html.replace("LATEX_INLINE_OPEN", r"\(")  # 변환 후
+```
+
+### heading ID + TOC 자동 생성
+```python
+def add_ids_to_headings(html):
+    counter = [0]
+    def replacer(m):
+        counter[0] += 1
+        return f'<{m.group(1)} id="sec-{counter[0]}">{m.group(2)}</{m.group(1)}>'
+    return re.sub(r'<(h[12])>(.*?)</\1>', replacer, html)
+
+def build_toc(html_body):
+    headings = re.findall(r'<(h[12])[^>]*id="([^"]*)"[^>]*>(.*?)</\1>', html_body)
+    # h1 → 1레벨, h2 → 2레벨 nested <ol> 생성
+```
+
+### Blockquote 분류
+- `Big Picture|핵심|가치 함수|확장된` → `.formula-box`
+- `사례|Case|Figure` → `.case-box`
+- 그 외 → `.insight-box` (기본 blockquote 스타일)

package/skills/lecture-note-digitizer/references/katex-style-guide.md

@@ -0,0 +1,165 @@
+# KaTeX 수식 스타일 가이드 — 강의노트/가이드 공통
+
+> 이 파일은 마크다운 작성 시 수식을 KaTeX LaTeX로 감싸는 패턴 레퍼런스.
+> 가이드 v2 (148개 인라인 수식)에서 추출한 모범 패턴 모음.
+
+## 원칙
+
+1. **변수명 2개 이상 포함된 표현은 예외 없이 `\(...\)` 감싸기.**
+2. **`$$` 블록 수식 사용 금지** — Typora에서 렌더링 깨짐. 대신 `> \(...\)` (blockquote + 인라인) 패턴 사용.
+3. Python `markdown` 라이브러리가 `\(` → `(` 로 먹으므로, HTML 변환 시 플레이스홀더 보호 필수.
+
+## 패턴별 예시 (Good vs Bad)
+
+### 1. 본문 서술 속 짧은 수식 참조
+
+```
+❌ 이것이 MB = MC의 변형입니다
+✅ 이것이 \( MB = MC \)의 변형입니다
+
+❌ 최적 선택 조건(MRS = Px/Py)을 이해하는 데
+✅ 최적 선택 조건(\( MRS = \frac{P_x}{P_y} \))을 이해하는 데
+
+❌ P > AC이면 초과이윤
+✅ \( P > AC \)이면 초과이윤
+```
+
+### 2. 볼드/강조 안 수식
+
+```
+❌ **MU > 0** — 다다익선
+✅ \( MU > 0 \) — 다다익선
+
+❌ **MRS = Px/Py**
+✅ \( MRS = \frac{P_x}{P_y} \)
+```
+
+### 3. 테이블 셀
+
+```
+❌ | MB (한계편익) | X재 소비의 주관적 가치 = **MRS** |
+✅ | \( MB \) (한계편익) | X재 소비의 주관적 가치 = \( MRS \) |
+
+❌ | MR = P |
+✅ | \( MR = P \) |
+```
+
+### 4. 제목/소제목
+
+```
+❌ ### MB = MC 해석
+✅ ### \( MB = MC \) 해석
+
+❌ ## 5.3 소득주도성장과 한계소비성향 (MPC)
+✅ ## 5.3 소득주도성장과 한계소비성향 (\( MPC \))
+```
+
+### 5. 괄호 안 수식 참조
+
+```
+❌ 가정 1(MU > 0)
+✅ 가정 1(\( MU > 0 \))
+
+❌ 가정 2(MU 체감)
+✅ 가정 2(\( MU \) 체감)
+```
+
+### 6. 블록인용 공식 — "직관 먼저, 공식 나중" 패턴
+
+가이드 v2 스타일: 한 줄 설명 + blockquote 수식 + 부가 설명
+
+```markdown
+**14. 노동자를 한 명 더 뽑으면?**
+추가로 1명을 고용했을 때 늘어나는 생산량이 한계생산입니다.
+> \( MPL = \frac{\Delta Q}{\Delta L} \) (한계생산)
+```
+
+### 7. 첨자 변수는 단독이어도 감싸기
+
+```
+❌ X재의 한계효용 MU_x는
+✅ X재의 한계효용 \( MU_x \)는
+
+❌ 가격 P_x가 하락하면
+✅ 가격 \( P_x \)가 하락하면
+
+❌ MPC가 낮은 고소득층
+✅ \( MPC \)가 낮은 고소득층
+```
+
+### 8. 단계별 풀이 (Step-by-Step)
+
+```markdown
+\( U(x, y) = x^{0.5} \cdot y^{0.5} \)일 때 한계효용:
+
+**Step 1**: \( MU_x = 0.5 \cdot x^{-0.5} \cdot y^{0.5} \)
+**Step 2**: \( MU_y = 0.5 \cdot x^{0.5} \cdot y^{-0.5} \)
+**Step 3**: \( x \)가 커질수록 \( MU_x \)는 감소 → 한계효용 체감 확인
+```
+
+## 자주 쓰는 수식 변환 테이블
+
+| Plain text | LaTeX |
+|-----------|-------|
+| `MU_x` | `\( MU_x \)` |
+| `MRS = MU_x / MU_y` | `\( MRS = \frac{MU_x}{MU_y} \)` |
+| `Px * x + Py * y <= I` | `\( P_x \cdot x + P_y \cdot y \leq I \)` |
+| `MRS = Px/Py` | `\( MRS = \frac{P_x}{P_y} \)` |
+| `MU_x / P_x = MU_y / P_y` | `\( \frac{MU_x}{P_x} = \frac{MU_y}{P_y} \)` |
+| `MB = MC` | `\( MB = MC \)` |
+| `P = MC` | `\( P = MC \)` |
+| `MR < P` | `\( MR < P \)` |
+| `P > AC` | `\( P > AC \)` |
+| `SW = CS + PS` | `\( SW = CS + PS \)` |
+| `epsilon_P` | `\( \varepsilon_P \)` |
+| `dU/dx` | `\( \frac{dU}{dx} \)` |
+| `partial U / partial x` | `\( \frac{\partial U}{\partial x} \)` |
+| `x^0.5` | `\( x^{0.5} \)` |
+| `sqrt(x)` | `\( \sqrt{x} \)` |
+
+### 9. `\text{}` 안에 괄호 금지 — delimiter 충돌
+
+KaTeX auto-render가 `\(` delimiter를 사용하므로, `\text{}` 안에 `(`가 들어가면 수식 파싱이 깨진다.
+
+```
+❌ \( \text{Value} = \frac{\text{Utility (고객의 지불 의사)}}{\text{Cost (생산·전달 비용)}} \)
+❌ \( \text{Value} = \frac{\text{Utility}\;\text{(고객의 지불 의사)}}{\text{Cost}\;\text{(생산·전달 비용)}} \)  ← \;\text{( 도 충돌
+✅ \( \text{Value} = \dfrac{\text{Utility — 고객의 지불 의사}}{\text{Cost — 생산·전달 비용}} \)
+```
+
+**규칙**: `\text{}` 안에서 괄호 `()` 를 사용하지 않는다. 괄호 대신 **em dash(—)** 로 대체. `\;\text{(` 분리 방식도 KaTeX delimiter `\(`와 충돌하므로 불충분.
+
+## 체크리스트 (작성 완료 후)
+
+마크다운 작성 후 아래 grep으로 누락 검사:
+
+```bash
+# Plain text 수식 후보 찾기 (LaTeX 밖에 있는 것)
+grep -nE '(MU_[xXyY]|MRS|MB =|MC |P_x|P_y|MPC|MR =|AC |SW =)' file.md | grep -v '\\\\('
+```
+
+결과가 0이면 통과. Mermaid `%%` 주석, 노드 텍스트는 예외.
+
+---
+
+## 실전 함정 2건 (2026-09, BIZ503 3주차에서 물림)
+
+### 1. `$$` 를 정규식으로 짝짓지 말 것 — 한 줄짜리 하나에 전부 밀린다
+`> $$x$$` 처럼 **한 줄에 여는/닫는 `$$` 가 같이 있는** 블록이 하나라도 있으면,
+`\$\$\n(.*?)\n\$\$` 류의 정규식은 그 다음부터 **여는 것과 닫는 것을 반대로 짝지어**
+본문 문단이 통째로 수식(`\[ … \]`)이 되고 KaTeX 가 문단 전체를 에러로 뱉는다.
+
+→ 정규식 대신 **`md.split('$$')` 후 홀/짝 인덱스로 페어링**한다. 구분자 개수만
+짝수면 절대 밀리지 않는다. (`note_pipeline.normalize_math`)
+
+### 2. 구분자만 보호하면 markdown 이 수식 '내용' 을 먹는다
+`\(`/`\)` 만 플레이스홀더로 치환하는 것으로는 부족하다.
+`\underbrace{i}_{(-)}, \underbrace{Y}_{(+)}` 는 `_..._` 가 `<em>` 으로 변환되며
+**언더스코어가 사라진다**. `*`, `_`, 백틱이 모두 수식에 등장하므로
+**수식 span 통째로** 플레이스홀더로 빼둔 뒤 HTML 변환 후 복원해야 한다.
+(`note_pipeline.stash_math_spans` / `restore_math_spans`)
+
+### 3. 금액 가드(`$` 뒤 숫자 제외)는 진짜 수식도 같이 막는다
+`$1.05 \times 1.02 = 1.071$` 은 `$` 뒤가 숫자라 인라인 수식 변환에서 제외된다.
+→ 1차 변환 후 **내용에 백슬래시(LaTeX 명령)가 있는 경우만** 2차로 구제한다.
+`$700bn`, `$1,200` 은 백슬래시가 없으므로 안전하게 그대로 남는다.

package/skills/omni-crawl/SKILL.md

@@ -2,7 +2,7 @@
 name: omni-crawl
 description: >
   통합 «문서» 검색/크롤링 스킬 (2026-09-02 재편 — 여론 축은 social-pulse 로 분리).
-  일반 웹/뉴스 검색은 Tavily 1순위(대표 2026-09-10 기본 ON · DuckDuckGo 는 **폴백 전용**으로 강등),
+  일반 웹/뉴스 검색은 Tavily 1순위(공식 결정 2026-09-10 기본 ON · DuckDuckGo 는 **폴백 전용**으로 강등),
   크롤/스크랩/추출은 Firecrawl REST v2(풀본문·maxAge 캐시), 개발 아티팩트(README·문서·이슈·PR)는
   Firecrawl Developer Index(`--engine fc-dev` — 매칭 패시지를 직접 반환해 스크랩 콜 절감).
   --mode deep 딥리서치 (다각도 검색 + 풀스크랩 + 커뮤니티 합성 · 기술 주제면 fc-dev 자동 가세 —
@@ -32,7 +32,7 @@ requires: []
 
 | 역할 | 1순위 (유료·기본) | 폴백 | 근거 (실측) |
 |------|-------|------|-------------|
-| **일반 웹 검색** | **tavily** | firecrawl → 🆓 ddg | 대표 2026-09-10 기본 ON. ⚙️ `OMNI_CRAWL_TAVILY=0` 이면 ddg 1순위로 역전 |
+| **일반 웹 검색** | **tavily** | firecrawl → 🆓 ddg | 공식 결정 2026-09-10 기본 ON. ⚙️ `OMNI_CRAWL_TAVILY=0` 이면 ddg 1순위로 역전 |
 | **뉴스** | tavily-news + fc-news(qdr 필터) | 🆓 ddg | ⚙️ 스위치 OFF 면 fc-news 단독 |
 | **크롤/스크랩/PDF/추출** | firecrawl REST v2 | **jina 무료** | 풀본문·maxAge 캐시(기본 2일·500% 가속) |
 | **개발 아티팩트(문서·이슈·PR)** | **fc-dev** (Developer Index) | ddg | 패시지 직반환 — 블로그보다 «정의한» 원문이 강한 답 |
@@ -44,7 +44,7 @@ requires: []
 ### 💸 비용 원칙 (2026-07-10 무료 티어 추가)
 
 > **품질 동일 시 무료, 아니면 유료 우선.** 유료(firecrawl/grok/apify)가 **1순위·기본**.
-> ⚙️ **tavily 가 1순위** — 대표 2026-09-10: 2026-08-06 엔 고정비 때문에 ddg 를 1순위로 뒀는데,
+> ⚙️ **tavily 가 1순위** — 공식 결정 2026-09-10: 2026-08-06 엔 고정비 때문에 ddg 를 1순위로 뒀는데,
 > **DDG HTML 이 차단되면 웹 검색 축이 통째로 0건**이 되고 폴백조차 안 걸리는 구멍이 있었다(실측).
 > 무료는 «돈 떨어졌을 때의 안전망»이지 1순위가 아니다 — 기본 ON, `OMNI_CRAWL_TAVILY=0` 으로 역전 가능.
 > ⛔ ***「콜당 싸다」와 「늘 켜 둔다」는 다른 축이다.*** `--engine tavily` 명시 호출은 스위치와 무관하게 돈다.
@@ -52,6 +52,14 @@ requires: []
 > ④ deep 스크랩 실패분 보충** 일 때만 자동 강등. "돈 떨어지면 죽는" 구조를 메우는 안전망.
 > deer-flow(무료 DDG+Jina 기본, 유료 선택) 아키텍처에서 이식 — omni-crawl은 유료 우선으로 반전.
 
+## 무료로 쓰는 길 (키 없이)
+
+이 스킬 폴더에서 `npx tsx scripts/main.ts "<검색어>" --free --print`로 DDG 검색을 사용합니다. URL 본문은 키 없는 Jina Reader 또는 로컬 HTML 추출을 사용할 수 있습니다. `--free`는 유료 엔진을 피하려는 명시적 선택이며, 검색 서비스 접속이 막히면 결과가 없을 수 있습니다.
+
+## 내 키로 쓰는 길
+
+유료 검색·스크랩은 자신의 `TAVILY_KEY`(Tavily)와 `FIRECRAWL_API_KEY`(Firecrawl)를 실행 환경에 설정합니다. 선택 엔진은 `XAI_API_KEY`(Grok), `APIFY_TOKEN`(Apify)를 사용합니다. 설정할 때 값이나 자격 파일은 이 스킬 문서·사본에 넣지 않습니다.
+
 ## 엔진
 
 | 엔진 | 소스 | 내용 |
@@ -82,8 +90,10 @@ requires: []
 
 ## 실행
 
+이 스킬 폴더에서 실행합니다.
+
 ```bash
-npx tsx ~/.claude/skills/omni-crawl/scripts/main.ts "<검색어>" [OPTIONS]
+npx tsx scripts/main.ts "<검색어>" [OPTIONS]
 ```
 
 ### 예시
@@ -144,10 +154,10 @@ npx tsx scripts/main.ts "https://news.samsung.com" --engine fc-crawl --print
 - **무료 티어** (`src/free.ts`, 2026-07-10): DDG HTML 검색 + Jina Reader(keyless) 마크다운 +
   로컬 readability 폴백 (dep-free = 순수 fetch+regex). 유료 공백/키없음/`--free`/deep 실패분에만 발동.
 - **web_capture** (`src/capture.ts`, 2026-07-10): headless Chrome `--screenshot` 셸아웃 →
-  Dia CDP(9222) 폴백. PNG 아티팩트를 `~/.omni-crawl/captures` 에 저장.
+  Dia CDP(9222) 폴백. PNG 아티팩트는 로컬 캡처 디렉토리에 저장.
 - **REST 직결** (2026-07-06): firecrawl CLI shell-out 제거 — 크론/데몬 최소 PATH 즉사,
   launchctl 키 증발, 콜당 146ms 스폰, execSync 이벤트루프 블로킹(병렬성 파괴)이
-  간헐 고장의 근본원인이었음(실측). 키는 스킬 `.env` 자립. fc-agent만 CLI 잔존(대화형 전용).
+  간헐 고장의 근본원인이었음(실측). 키는 실행 환경에서 전달. fc-agent만 CLI 잔존(대화형 전용).
 - **Developer Index** (`fc-dev`, 2026-09-02 배선): `POST /v2/search/developer`. 다른 v2
   엔드포인트와 **봉투가 다르다** — 파라미터는 `limit` 이 아니라 **`k`**(`limit` 보내면 400),
   응답은 `data` 가 아니라 **`results`** (실측 2026-08-31). `id` 접두사가 곧 종류
@@ -161,7 +171,7 @@ npx tsx scripts/main.ts "https://news.samsung.com" --engine fc-crawl --print
   떼어낼 덩어리가 아니었고, `--mode deep` 이 ddg+firecrawl+grok 을 한 파이프라인에서 합성하므로
   프로세스 경계를 넣으면 위 «REST 직결» 항목이 기록한 고장을 재현한다. `--engine grok-*` 호출 계약은 불변.
 - **폴백 체인**: tavily ↔ firecrawl → (최후) 🆓 ddg · scrape 실패 → waitFor 재시도 → 🆓 jina.
-  대표 2026-09-10: `wantedWeb` 에 ddg 를 포함시켜 **ddg 1순위였을 때 0건이면 유료로 «승격» 보충**되게 했다
+  공식 결정 2026-09-10: `wantedWeb` 에 ddg 를 포함시켜 **ddg 1순위였을 때 0건이면 유료로 «승격» 보충**되게 했다
   (종전엔 ddg 가 축 계산에서 빠져 보충이 아예 안 걸렸다).
 - **URL dedup**: 엔진 간 중복 제거. deep 모드는 풀본문 우선 생존.
 - **비용 가시성**: 결과에 `비용: firecrawl ~5cr` 표시. `--health`가 잔량 보고.
@@ -216,18 +226,18 @@ omni-digest --content "<크롤결과>" --format rich-cards --print
 
 ## 환경변수
 
-`.env` 하나로 관리 (스킬 자립 — 셸/launchctl 비의존). grok/omni-digest `.env` 자동 상속.
+실행 환경의 변수 이름을 아래 표에서 확인합니다. 자격 파일은 이 팩에 포함하지 않습니다.
 
 | 변수 | 용도 | 필수 |
 |------|------|------|
 | `TAVILY_KEY` | Tavily 검색/추출 | tavily 사용 시 |
-| `OMNI_CRAWL_TAVILY` | ⚙️ **tavily 상시사용 스위치**(`1` 이면 ON · **기본 OFF** · 대표 2026-08-06 고정비) | 선택 |
-| `FIRECRAWL_API_KEY` | Firecrawl REST (2026-07-06부터 .env 자립) | firecrawl 사용 시 |
+| `OMNI_CRAWL_TAVILY` | ⚙️ tavily 상시사용 스위치 (기본 ON · `0` 이면 OFF, ddg 우선) | 선택 |
+| `FIRECRAWL_API_KEY` | Firecrawl REST | firecrawl 사용 시 |
 | `XAI_API_KEY` | Grok 검색 | Grok 사용 시 |
 | `APIFY_TOKEN` | Apify tweet-scraper | Apify 사용 시 |
 | `JINA_API_KEY` | Jina Reader rate-limit 상향 (무료 티어는 키 없이도 동작) | 선택 |
 | `OMNI_CRAWL_CHROME` | headless Chrome 바이너리 경로 (기본 자동 탐지) | 선택 |
-| `OMNI_CRAWL_CAPTURE_DIR` | 스크린샷 저장 경로 (기본 `~/.omni-crawl/captures`) | 선택 |
+| `OMNI_CRAWL_CAPTURE_DIR` | 스크린샷 저장 디렉토리 (기본 자동 선택) | 선택 |
 | `OMNI_CRAWL_CDP_PORT` | Dia/Chrome CDP 폴백 포트 (기본 9222) | 선택 |
 | `OBSIDIAN_VAULT_ROOT` | Obsidian 볼트 경로 (자동 저장 대상) | 저장 시 |
 | `OMNI_CRAWL_SAVE_SUBDIR` | 볼트 내 저장 서브디렉토리 (기본: `00. Inbox/05. Crawl`) | 선택 |

package/skills/omni-crawl/scripts/main.ts

@@ -14,11 +14,11 @@ import { chromeAvailable } from '../src/capture.js';
 import { runRegisteredEngine, type EngineCtx } from '../src/registry.js';
 import { renderMarkdown, saveMarkdown, renderSourcesSection } from '../src/render.js';
 import type { CrawlResult, CrawlItem, SearchEngine } from '../src/types.js';
-import { writeStdoutJson } from '../../../src/cli/stdout-json.ts';
+import { writeStdoutJson } from '../../../src/cli/stdout-json.js';
 
 initEnv();
 
-/** ⛔⭐ tavily 를 **상시 경로**에 쓸 것인가 (대표 2026-09-10 · **기본 ON**).
+/** ⛔⭐ tavily 를 **상시 경로**에 쓸 것인가 (공식 결정 2026-09-10 · **기본 ON**).
  *
  *  이력: 2026-08-06 엔 비용(deep 1회당 advanced ×3 ≈ 6cr 고정비) 때문에 기본 OFF 로 두고
  *  무료 ddg 를 1순위로 삼았다. 그러나 **DDG HTML 차단 시 웹 검색 축이 통째로 0건**이 되고,
@@ -173,7 +173,7 @@ async function runDeep(query: string): Promise<CrawlResult[]> {
   const results: CrawlResult[] = [];
 
   // 1) 다각도 검색 + grok-community 동시 발사
-  // ⛔⭐ 2026-08-06 (대표) — tavily 각도 검색은 **기본 OFF**(deep 1회당 advanced ×3 ≈ 6cr 고정비).
+  // ⛔⭐ 2026-08-06 (공식 결정) — tavily 각도 검색은 **기본 OFF**(deep 1회당 advanced ×3 ≈ 6cr 고정비).
   //    켜기: `.env` 또는 셸에 `OMNI_CRAWL_TAVILY=1`. 끄면 아래 `!gotTavily` 분기가 **이미 있는**
   //    ddg 무료 각도 검색을 대신 돌린다(별도 배선 불필요).
   const searchTasks: Array<Promise<CrawlResult | null>> = [
@@ -259,7 +259,7 @@ async function runDeep(query: string): Promise<CrawlResult[]> {
 // 원칙: 유료(tavily/firecrawl)가 1순위·기본. 유료가 공백/미가용일 때만 무료(ddg)로 강등.
 // "품질 동일 시 무료, 아니면 유료 우선" — 무료는 돈 떨어졌을 때의 안전망.
 async function applyWebFallback(engines: SearchEngine[], results: CrawlResult[], query: string): Promise<CrawlResult[]> {
-  // ⛔ ddg 도 «웹 검색 축»으로 센다(대표 2026-09-10). 종전엔 ddg 가 빠져 있어서
+  // ⛔ ddg 도 «웹 검색 축»으로 센다(공식 결정 2026-09-10). 종전엔 ddg 가 빠져 있어서
   //    ddg 1순위로 돌던 시절 DDG 가 0건이면 **보충이 아예 안 걸렸다** — 그 구멍을 막는다.
   const wantedWeb = engines.some(e => e === 'tavily' || e === 'tavily-news' || e === 'firecrawl' || e === 'fc-news' || e === 'ddg');
   if (!wantedWeb) return results;
@@ -393,7 +393,7 @@ async function runHealth(): Promise<boolean> {
       },
     },
     {
-      // 대표 2026-09-10: ddg 는 **폴백 전용**(1순위 아님)이므로 실패해도 전체 판정을 깨지 않는다.
+      // 공식 결정 2026-09-10: ddg 는 **폴백 전용**(1순위 아님)이므로 실패해도 전체 판정을 깨지 않는다.
       //   DDG HTML 차단은 상시 발생하는 정상 상태 — 유료 축이 살아 있으면 검색은 계속 돈다.
       name: 'ddg-free', tier: 'fallback', run: async () => {
         const t0 = Date.now();
@@ -439,7 +439,7 @@ function runSelfTest() {
   console.log('=== omni-crawl self-test ===\n');
   let passed = 0, failed = 0;
 
-  // ⛔ 기대값은 **tavily 스위치를 따라간다**(대표 2026-08-06 기본 OFF). 스위치를 뒤집고도
+  // ⛔ 기대값은 **tavily 스위치를 따라간다**(공식 결정 2026-08-06 기본 OFF). 스위치를 뒤집고도
   //    자기테스트를 안 고쳐 3건이 상시 FAIL 로 남아 있었다 — 신호가 죽어 있던 자리다.
   const WEB = (process.env.OMNI_CRAWL_TAVILY ?? '').trim() !== '0' ? 'tavily' : 'ddg';
   const NEWS = WEB === 'tavily' ? ['tavily-news', 'fc-news'] : ['fc-news'];

package/skills/omni-crawl/src/router.ts

@@ -1,6 +1,6 @@
 import type { SearchEngine, CrawlDecision, RunMode } from './types.js';
 
-/** tavily 상시 사용 스위치(대표 2026-09-10 **기본 ON** · `OMNI_CRAWL_TAVILY=0` 으로 끈다).
+/** tavily 상시 사용 스위치(공식 결정 2026-09-10 **기본 ON** · `OMNI_CRAWL_TAVILY=0` 으로 끈다).
  *
  *  ⛔ 2026-08-06 엔 비용 때문에 기본 OFF(= ddg 1순위)였는데, **DDG HTML 이 차단되면
  *  웹 검색 축이 통째로 0건**이 된다(폴백 체인의 `wantedWeb` 이 ddg 를 세지 않아 보충도 안 걸림).
@@ -24,7 +24,7 @@ export interface RouterInput {
 /**
  * 역할기반 라우팅 (2026-07-06 재편 — 구독 3종 역할 분담):
  *
- *   일반 웹 검색  → tavily        (대표 2026-09-10 기본 ON · ddg 는 폴백 전용 · OMNI_CRAWL_TAVILY=0 로 역전)
+ *   일반 웹 검색  → tavily        (공식 결정 2026-09-10 기본 ON · ddg 는 폴백 전용 · OMNI_CRAWL_TAVILY=0 로 역전)
  *   뉴스          → firecrawl(sources:news)
  *   크롤/스크랩   → firecrawl     (Standard 100k·풀본문·maxAge 캐시)
  *   커뮤니티/여론 → grok          (X/레딧 유일 커버 — 여기만 사용)
@@ -82,7 +82,7 @@ export function decideCrawl(input: RouterInput): CrawlDecision {
       if (/반응|여론|실시간/i.test(text) && engines.length === 0) { engines.push('grok-community'); reasons.push('커뮤니티 검색(grok)'); }
     }
 
-    // ⛔⭐ 기본 웹 검색 엔진은 **스위치가 정한다**(대표 2026-08-06 · 기본 OFF = 무료 ddg).
+    // ⛔⭐ 기본 웹 검색 엔진은 **스위치가 정한다**(공식 결정 2026-08-06 · 기본 OFF = 무료 ddg).
     //   ⚠️ 레지스트리에서 지우지 않았으므로 `--engine tavily` 명시 호출은 스위치와 무관하게 돈다
     //   (asset-attractiveness · research-bridge 의 CLI 계약 보존).
     if (engines.length === 0) { engines = [webEngine()]; reasons.push(`기본: ${webEngine()}`); }