feat(promo): 자동 캡처(Playwright) + 시연 시뮬레이터 + PNG 6장

A+C 옵션: 공개 페이지 자동 캡처 + 설치 흐름 자동 시연 스크립트.

Added:
- docs/promo/automation/capture_pages.py: Playwright 로 공개 페이지 6종 PNG 자동 캡처
  * GitHub repo / Release / PyPI / 법제처 / OC 가이드 / 설치 ZIP 위치
  * 격리 venv (.venv-pw, gitignore) 로 메인 의존성과 분리
- docs/promo/automation/demo-install-flow.ps1: setup-for-novice.ps1 의 화면 출력만
  시뮬레이션. 실제 설치 X. ScreenToGif/OBS 로 GIF/MP4 녹화용. UTF-8 BOM.
- docs/promo/automation/README.md: 두 도구 사용법 + 트러블슈팅 + v0.9.0 갱신 절차
- docs/promo/images/01~06.png: 위 스크립트로 생성한 첫 캡처 (총 5MB)
- docs/promo/images/README.md: 이미지 인덱스 (자동 생성 6 + 수동 캡처 6 자리)

Modified:
- .gitignore: docs/promo/**/*.png|jpg|gif 예외 (README 노출용 자료는 추적),
  docs/promo/automation/.venv-pw/ 추가

향후 v0.9.0 등 업데이트 시 capture_pages.py 재실행만으로 6장 자동 갱신.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: lapiogga

.gitignore

@@ -83,9 +83,17 @@ logs/
 *.png
 *.jpg
 *.jpeg
+# 단, docs/promo/ 아래 자료 이미지·GIF·동영상은 README 노출용이므로 추적
+!docs/promo/**/*.png
+!docs/promo/**/*.jpg
+!docs/promo/**/*.jpeg
+!docs/promo/**/*.gif
 
 # 외부 가이드 원본 (저작권 불명확)
 reference/
 
 # 내부 계획 폴더 (작업 메모)
 .planning/
+
+# Playwright 자동화용 격리 venv
+docs/promo/automation/.venv-pw/

docs/promo/automation/README.md

@@ -0,0 +1,136 @@
+# 자동화 도구 (promo/automation)
+
+본 폴더의 스크립트를 사용하면 홍보 자료(스크린샷·GIF) 의 상당 부분을 자동 생성할 수 있다. 향후 v0.9.0 등 업데이트 시 재실행만으로 자료 갱신 가능.
+
+## 두 가지 자동화
+
+| 도구 | 역할 | 자동화 수준 |
+|---|---|---|
+| `capture_pages.py` | 공개 웹 페이지 6장 PNG 캡처 (Playwright) | **완전 자동** |
+| `demo-install-flow.ps1` | 설치 흐름 시연 (실제 설치 X, 화면 출력만 시뮬레이션) | **반자동** (녹화는 사용자가 ScreenToGif 로) |
+
+자동화 불가능 (사용자 본인 PC 에서 수동 캡처 필요):
+- Claude Desktop 채팅 화면 (Anthropic 계정 로그인)
+- 법제처 회원가입·활용신청 화면 (캡차·이메일 인증)
+- Windows SmartScreen 경고창
+
+---
+
+## 1. 공개 페이지 자동 캡처 (capture_pages.py)
+
+### 무엇을 캡처하나?
+
+| Slug | URL | 용도 |
+|---|---|---|
+| `01-github-repo` | github.com/lapiogga/caseLaw | 메인 페이지 |
+| `02-github-release` | releases/tag/v0.8.0 | Release 첨부 자산 안내 |
+| `03-pypi-package` | pypi.org/project/caselaw-mcp | PyPI 페이지 |
+| `04-bopjecheo-openapi` | open.law.go.kr 첫 화면 | OC 발급 진입점 |
+| `05-oc-baalgup-guide` | docs/OC발급_가이드.md (렌더링) | 가이드 자체 |
+| `06-installer-zip-download` | Release ZIP 다운로드 위치 | 다운로드 흐름 |
+
+### 실행 방법 (Windows)
+
+```powershell
+cd docs\promo\automation
+
+# 1. 격리 venv 생성 (한 번만)
+uv venv .venv-pw
+uv pip install --python .\.venv-pw\Scripts\python.exe playwright
+
+# 2. Chromium 다운로드 (한 번만, 약 200MB)
+.\.venv-pw\Scripts\python.exe -m playwright install chromium
+
+# 3. 캡처 실행 (매번)
+.\.venv-pw\Scripts\python.exe capture_pages.py
+```
+
+결과는 `docs/promo/images/` 에 PNG 6장. 약 20-30초 소요.
+
+### 새 페이지 추가
+
+`capture_pages.py` 의 `PAGES` 리스트에 튜플 추가:
+
+```python
+("07-new-page", "https://example.com", 1280, 800, True, "css.selector"),
+```
+
+- 5번째 인자 `full_page=True` 면 전체 페이지 (긴 README 등), `False` 면 viewport 한 화면만
+- 6번째 인자는 캡처 전 대기할 CSS selector (lazy-load 방지)
+
+---
+
+## 2. 설치 흐름 시연 (demo-install-flow.ps1)
+
+### 무엇이 자동인가?
+
+`setup-for-novice.ps1` 의 진짜 인터랙티브 입력(`Read-Host`) 부분을 모두 자동으로 진행한다 — 사용자 키보드 입력 없이 처음부터 끝까지 약 25초 안에 완주.
+
+진짜 설치는 하지 않고 화면 출력만 시뮬레이션하므로 시스템에 영향 없다.
+
+### 실행 방법
+
+#### 옵션 A — ScreenToGif 로 GIF 만들기 (권장)
+
+1. <https://www.screentogif.com> 에서 ScreenToGif 다운로드·실행
+2. '레코더' 모드 선택
+3. PowerShell 창을 열고, 녹화 영역을 PowerShell 창 크기로 지정
+4. ScreenToGif 녹화 시작
+5. PowerShell 에서 본 스크립트 실행:
+   ```powershell
+   powershell -ExecutionPolicy Bypass -File docs\promo\automation\demo-install-flow.ps1
+   ```
+6. 시연 종료 후 ScreenToGif 녹화 멈춤 → '편집' → 불필요한 프레임 잘라내기 → '저장' → GIF
+7. 결과를 `docs/promo/images/07-install-demo.gif` 로 저장
+
+#### 옵션 B — OBS Studio 로 MP4
+
+1. OBS 의 '윈도우 캡처' 소스로 PowerShell 창 추가
+2. 녹화 시작 → 본 스크립트 실행 → 녹화 멈춤
+3. MP4 결과를 FFmpeg 로 GIF 변환:
+   ```powershell
+   ffmpeg -i input.mp4 -vf "fps=10,scale=720:-1:flags=lanczos" -loop 0 install-demo.gif
+   ```
+
+### 자동 녹화도 가능 (사용자 PC 에서, 본 환경 X)
+
+PowerShell 의 Add-Type 으로 화면 캡처를 직접 코드로 할 수 있지만, 의존성·복잡도가 ScreenToGif 가 훨씬 낮으므로 추천하지 않는다.
+
+---
+
+## 3. 추천 워크플로 (총 30-40분)
+
+```
+1. capture_pages.py 실행 (자동)            -> images/01~06.png 생성
+2. ScreenToGif 로 demo-install-flow 녹화    -> images/07-install-demo.gif
+3. 본인 PC 에서 직접 캡처:
+   - Claude Desktop 첫 채팅 결과 (ping)     -> images/08-ping-result.png
+   - 실제 사용 예시 (음주운전 검색)          -> images/09-precedent-search.gif
+4. images/README.md 의 인덱스에 새 자료 추가
+5. 변경사항 commit + push
+```
+
+---
+
+## 4. 정기 갱신 (v0.9.0 등 새 버전 배포 시)
+
+GitHub Release 버전 번호가 바뀌면 `capture_pages.py` 의 PAGES 리스트의 `releases/tag/v0.8.0` 부분만 새 버전으로 변경 후 재실행.
+
+PyPI 캡처는 자동으로 최신 버전을 보여주므로 수정 불필요.
+
+---
+
+## 5. 트러블슈팅
+
+| 증상 | 원인 / 해결 |
+|---|---|
+| `playwright install` 200MB 다운로드 너무 느림 | 한 번만 받으면 됨. 또는 `playwright install --with-deps chromium` 으로 시스템 deps 도 자동 |
+| 캡처에 한글이 깨짐 | viewport `locale="ko-KR"` 가 이미 설정됨. 그래도 깨지면 시스템 한글 폰트 확인 |
+| 일부 페이지가 빈 화면 | networkidle 타임아웃. `capture_pages.py` 가 자동으로 domcontentloaded 로 fallback |
+| Playwright 가 차단됨 (403) | User-Agent 추가 필요. `ctx = await pw.chromium.launch(... user_agent="Mozilla/5.0 ...")` |
+
+---
+
+## 격리 환경
+
+본 폴더 안에서 만드는 `.venv-pw/` 는 .gitignore 로 추적 제외됨. 본 레포의 메인 `pyproject.toml` 의존성과 분리.

docs/promo/automation/capture_pages.py

@@ -0,0 +1,117 @@
+"""공개 웹 페이지 자동 스크린샷 (Playwright).
+
+사용:
+    cd docs/promo/automation
+    uv pip install playwright
+    uv run python -m playwright install chromium
+    uv run python capture_pages.py
+
+결과:
+    docs/promo/images/ 에 PNG 자동 생성
+
+캡처 대상은 모두 공개 페이지로 로그인 없이 접근 가능.
+법제처 회원가입·Claude Desktop 화면 등 인증 필요 화면은 제외 (사용자 본인 캡처 필요).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from playwright.async_api import async_playwright
+
+OUT_DIR = Path(__file__).resolve().parent.parent / "images"
+OUT_DIR.mkdir(parents=True, exist_ok=True)
+
+# (slug, url, viewport_width, viewport_height, full_page, wait_selector)
+PAGES = [
+    (
+        "01-github-repo",
+        "https://github.com/lapiogga/caseLaw",
+        1280, 800, True, "article",
+    ),
+    (
+        "02-github-release",
+        "https://github.com/lapiogga/caseLaw/releases/tag/v0.8.0",
+        1280, 800, True, "h1",
+    ),
+    (
+        "03-pypi-package",
+        "https://pypi.org/project/caselaw-mcp/",
+        1280, 800, True, "h1.package-header__name",
+    ),
+    (
+        "04-bopjecheo-openapi",
+        "https://open.law.go.kr/LSO/openApi/cuAskList.do",
+        1280, 900, True, "body",
+    ),
+    (
+        "05-oc-baalgup-guide",
+        "https://github.com/lapiogga/caseLaw/blob/main/docs/OC%EB%B0%9C%EA%B8%89_%EA%B0%80%EC%9D%B4%EB%93%9C.md",
+        1280, 900, True, "article",
+    ),
+    (
+        "06-installer-zip-download",
+        "https://github.com/lapiogga/caseLaw/releases/tag/v0.8.0",
+        1280, 800, False, "details summary",
+    ),
+]
+
+
+async def capture_one(
+    pw,
+    slug: str,
+    url: str,
+    width: int,
+    height: int,
+    full_page: bool,
+    wait_selector: str,
+) -> Path:
+    """단일 페이지 캡처."""
+    browser = await pw.chromium.launch(headless=True)
+    ctx = await browser.new_context(
+        viewport={"width": width, "height": height},
+        locale="ko-KR",
+        device_scale_factor=2,  # 레티나 품질
+    )
+    page = await ctx.new_page()
+    print(f"  -> {url}")
+    try:
+        await page.goto(url, wait_until="networkidle", timeout=30000)
+    except Exception as e:
+        print(f"     networkidle timeout ({e.__class__.__name__}), fallback to domcontentloaded")
+        await page.goto(url, wait_until="domcontentloaded", timeout=30000)
+
+    try:
+        await page.wait_for_selector(wait_selector, timeout=10000)
+    except Exception:
+        print(f"     selector '{wait_selector}' not found, capture anyway")
+
+    # 추가 1초 대기 (lazy-load 이미지)
+    await page.wait_for_timeout(1500)
+
+    out = OUT_DIR / f"{slug}.png"
+    await page.screenshot(path=str(out), full_page=full_page)
+    await browser.close()
+    print(f"     saved: {out.name}  ({out.stat().st_size // 1024} KB)")
+    return out
+
+
+async def main() -> None:
+    print(f"Output: {OUT_DIR}")
+    print(f"Targets: {len(PAGES)} pages\n")
+
+    async with async_playwright() as pw:
+        for i, args in enumerate(PAGES, 1):
+            print(f"[{i}/{len(PAGES)}] {args[0]}")
+            try:
+                await capture_one(pw, *args)
+            except Exception as e:
+                print(f"     [FAIL] {e}")
+            print()
+
+    print("Done. See docs/promo/images/")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/promo/automation/demo-install-flow.ps1

@@ -0,0 +1,115 @@
+# =============================================================
+# 설치 흐름 시연 스크립트 (실제 설치 안 함)
+#
+# 본 스크립트는 setup-for-novice.ps1 의 화면 출력을 그대로 재현하지만
+# 실제 winget 설치·config 작성은 하지 않는다. 화면 녹화용.
+#
+# 사용:
+#   ScreenToGif (https://www.screentogif.com) 또는 OBS Studio 실행
+#   -> 녹화 영역을 PowerShell 창 크기로 지정
+#   -> 본 스크립트 실행 (powershell -ExecutionPolicy Bypass -File demo-install-flow.ps1)
+#   -> 녹화 멈춤 -> GIF 또는 MP4 저장
+#
+# 자동 시연 모드:
+#   매 단계가 자동으로 진행되어 사용자 입력 대기 없음 (총 약 25초)
+# =============================================================
+
+$ErrorActionPreference = 'Stop'
+$OutputEncoding = [System.Text.Encoding]::UTF8
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+
+function Write-Step { param($m); Write-Host ''; Write-Host '--------------------------------------------------------' -ForegroundColor Cyan; Write-Host "  $m" -ForegroundColor Cyan; Write-Host '--------------------------------------------------------' -ForegroundColor Cyan }
+function Write-Ok   { param($m); Write-Host "  [OK] $m" -ForegroundColor Green }
+function Write-Warn { param($m); Write-Host "  [!]  $m" -ForegroundColor Yellow }
+
+function Demo-Pause { param([int]$Ms = 600); Start-Sleep -Milliseconds $Ms }
+function Demo-Type {
+    param([string]$Text, [int]$DelayMs = 35)
+    foreach ($ch in $Text.ToCharArray()) {
+        Write-Host -NoNewline $ch
+        Start-Sleep -Milliseconds $DelayMs
+    }
+}
+
+# 0. 환영
+Clear-Host
+Write-Host ''
+Write-Host '  ============================================================' -ForegroundColor Magenta
+Write-Host '   CaseLaw MCP 자동 설치 도구 (한국 판례·법령 검색)' -ForegroundColor Magenta
+Write-Host '  ============================================================' -ForegroundColor Magenta
+Write-Host ''
+Write-Host '   이 도구는 Claude Desktop 에서 한국 판례·법령을 자연어로'
+Write-Host '   검색·인용·요약할 수 있게 해줍니다.'
+Write-Host ''
+Write-Host '   소요 시간: 3-7분 (인터넷 속도에 따라)'
+Write-Host ''
+Write-Host -NoNewline '   계속하려면 Enter 를 누르세요: '
+Demo-Pause 1500
+Write-Host ''
+
+# 1. OC 키
+Write-Step '1단계: 법제처 OC 키 확인'
+Write-Host ''
+Write-Host '   OC 키는 법제처 OPEN API 사이트에서 무료로 발급받습니다.'
+Write-Host ''
+Write-Host -NoNewline '   이미 OC 키가 있습니까? (Y/N): '
+Demo-Pause 1000
+Demo-Type 'Y'
+Write-Host ''
+Write-Host ''
+Write-Host -NoNewline '   OC 키를 붙여넣으세요: '
+Demo-Pause 800
+Demo-Type 'gildong' 60
+Write-Host ''
+Write-Ok 'OC 키 등록: gil*****'
+
+# 2. 도구 점검
+Write-Step '2단계: 필수 도구 점검 및 자동 설치'
+Demo-Pause 400
+Write-Ok 'winget 사용 가능'
+Demo-Pause 400
+Write-Host ''
+Write-Host '   uv (Python 도구) 가 없습니다. 자동 설치합니다 (1-2분)...'
+Demo-Pause 800
+Write-Host -NoNewline '   '
+1..30 | ForEach-Object { Write-Host -NoNewline '#' -ForegroundColor DarkGray; Start-Sleep -Milliseconds 60 }
+Write-Host ''
+Write-Ok 'uv 설치 완료'
+Demo-Pause 400
+Write-Ok 'Claude Desktop 이미 설치됨'
+Demo-Pause 300
+Write-Ok 'Claude Desktop config 폴더: C:\Users\...\Roaming\Claude'
+
+# 3. 패키지
+Write-Step '3단계: caselaw-mcp 패키지 다운로드 (PyPI)'
+Demo-Pause 400
+Write-Host '   uvx 로 caselaw-mcp 미리 받습니다 (30-60초)...'
+Demo-Pause 600
+Write-Host -NoNewline '   '
+1..20 | ForEach-Object { Write-Host -NoNewline '#' -ForegroundColor DarkGray; Start-Sleep -Milliseconds 60 }
+Write-Host ''
+Write-Ok 'caselaw-mcp 설치 완료'
+
+# 4. config
+Write-Step '4단계: Claude Desktop 설정 자동 작성'
+Demo-Pause 400
+Write-Ok '기존 설정 백업: claude_desktop_config.json.backup-20260505-153012'
+Demo-Pause 300
+Write-Ok '설정 파일 작성 완료'
+
+# 5. 완료
+Write-Step '5단계: 설치 완료'
+Write-Host ''
+Write-Host '   모든 설정이 끝났습니다!' -ForegroundColor Green
+Write-Host ''
+Write-Host '   다음 절차로 사용하세요:'
+Write-Host ''
+Write-Host '   1) 트레이의 Claude Desktop 아이콘 -> Quit'
+Write-Host '   2) 시작 메뉴에서 Claude Desktop 다시 실행'
+Write-Host '   3) 채팅창에 입력해보세요:'
+Write-Host ''
+Write-Host '         caselaw 로 ping 해줘' -ForegroundColor Yellow
+Write-Host ''
+Write-Host '   문제 발생 시: https://github.com/lapiogga/caseLaw/issues'
+Write-Host ''
+Demo-Pause 2500