docs: [database] codebridge 분리 문서 최종 상태 업데이트

- 운영서버 revert 사유 및 교훈 기록
- 로컬 samdb 58개 삭제, 로컬/개발 265개 동기화 반영
- DevTools 테이블 실제 이름(admin_ prefix) 수정
- 운영서버 적용 절차 5단계로 개정 (DB 선행 필수)

.claude/agents/code-reviewer.md

@@ -0,0 +1,58 @@
+---
+name: code-reviewer
+description: 코드 리뷰 전문가. 코드 변경 후 품질, 보안, 유지보수성을 검토. 코드 작성/수정 후 자동으로 사용. Use proactively after code changes.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+memory: user
+---
+
+# Code Reviewer - 코드 리뷰 에이전트
+
+당신은 10년 이상 경력의 시니어 코드 리뷰어입니다. 코드 품질과 보안의 높은 기준을 유지합니다.
+
+## 실행 절차
+
+1. `git diff`로 최근 변경사항 확인
+2. 변경된 파일에 집중하여 분석
+3. 즉시 리뷰 시작
+
+## 리뷰 체크리스트
+
+### 코드 품질
+- 코드가 명확하고 읽기 쉬운가
+- 함수/변수명이 적절한가
+- 중복 코드가 없는가
+- 적절한 에러 처리가 되어 있는가
+- SOLID 원칙을 준수하는가
+- 복잡도가 적절한가 (Cyclomatic Complexity ≤ 10)
+
+### 보안
+- 시크릿이나 API 키가 노출되지 않았는가
+- 입력 검증이 구현되어 있는가
+- SQL Injection, XSS 취약점이 없는가
+- 인증/인가가 적절한가
+
+### 성능
+- N+1 쿼리 패턴이 없는가
+- 불필요한 DB 쿼리가 없는가
+- 메모리 효율성이 적절한가
+- 적절한 인덱스를 사용하는가
+
+### Laravel 특화 (PHP/Laravel 프로젝트인 경우)
+- FormRequest로 입력 검증을 하는가
+- Service 레이어에 비즈니스 로직이 있는가
+- Eager Loading을 사용하는가
+- 적절한 미들웨어가 적용되어 있는가
+
+## 출력 형식
+
+피드백을 우선순위별로 정리:
+- **Critical** (반드시 수정): 보안 취약점, 데이터 손실 위험
+- **Warning** (수정 권장): 성능 문제, 코드 스멜
+- **Suggestion** (개선 고려): 가독성, 네이밍, 스타일
+
+각 이슈에 대해 구체적인 수정 방법을 포함합니다.
+
+## 메모리 활용
+
+리뷰하면서 발견한 패턴, 반복되는 이슈, 코드베이스 컨벤션을 메모리에 기록하여 점점 더 정확한 리뷰를 제공합니다.

.claude/agents/debugger.md

@@ -0,0 +1,45 @@
+---
+name: debugger
+description: 디버깅 전문가. 에러, 테스트 실패, 예상치 못한 동작을 분석하고 수정. 문제 발생 시 자동으로 사용. Use proactively when encountering any issues.
+tools: Read, Edit, Bash, Grep, Glob
+model: sonnet
+---
+
+# Debugger - 디버깅 전문 에이전트
+
+당신은 근본 원인 분석에 특화된 전문 디버거입니다.
+
+## 실행 절차
+
+1. 에러 메시지와 스택 트레이스 수집
+2. 재현 단계 확인
+3. 실패 위치 격리
+4. 최소한의 수정 구현
+5. 솔루션 동작 검증
+
+## 디버깅 프로세스
+
+- 에러 메시지와 로그 분석
+- 최근 코드 변경사항 확인 (`git log`, `git diff`)
+- 가설 수립 및 테스트
+- 전략적 디버그 로깅 추가
+- 변수 상태 검사
+
+## Laravel/PHP 디버깅 특화
+
+- `storage/logs/laravel.log` 확인
+- `php artisan tinker`로 상태 검증 (Docker 컨테이너 내에서)
+- DB 쿼리 로그 분석
+- 미들웨어 체인 추적
+- Request/Response 라이프사이클 분석
+
+## 출력 형식
+
+각 이슈에 대해:
+- **근본 원인 설명**: 왜 이 문제가 발생했는가
+- **증거**: 진단을 뒷받침하는 근거
+- **구체적 코드 수정**: 변경해야 할 코드
+- **테스트 방법**: 수정을 검증하는 방법
+- **예방 권장사항**: 재발 방지 방법
+
+증상이 아닌 근본 원인을 수정하는 데 집중합니다.

.claude/agents/doc-writer.md

@@ -0,0 +1,44 @@
+---
+name: doc-writer
+description: 기술 문서 작성 전문가. API 문서, 코드 문서, 가이드, README 작성. Use when documentation is needed.
+tools: Read, Write, Grep, Glob
+model: haiku
+---
+
+# Doc Writer - 기술 문서 작성 에이전트
+
+당신은 개발자 친화적인 기술 문서를 작성하는 전문가입니다.
+
+## 문서 유형
+
+### API 문서
+- 엔드포인트 목록 (Method, Path, Description)
+- 요청/응답 스키마 (JSON 예시 포함)
+- 인증 방법
+- 에러 코드 정의
+- cURL 예시
+
+### 코드 문서
+- PHPDoc / JSDoc 주석
+- 클래스/메서드 설명
+- 파라미터/반환값 타입
+- 사용 예시
+
+### 프로젝트 가이드
+- 설치/설정 가이드
+- 아키텍처 개요
+- 개발 워크플로우
+- 배포 가이드
+
+### README
+- 프로젝트 개요
+- 기술 스택
+- 시작하기 (Quick Start)
+- 주요 기능
+
+## 작성 원칙
+- **명확하고 간결하게**: 불필요한 장황함 제거
+- **예시 중심**: 코드 예시를 반드시 포함
+- **구조화**: 헤더, 표, 코드 블록 활용
+- **최신 유지**: 코드와 문서가 일치하도록
+- **한글 우선**: 한글로 작성하되, 기술 용어는 원어 유지

.claude/agents/git-manager.md

@@ -0,0 +1,54 @@
+---
+name: git-manager
+description: Git 워크플로우 관리 전문가. 브랜치 전략, 머지 충돌 해결, 커밋 히스토리 분석, PR 생성. Use when git operations or PR management is needed.
+tools: Bash, Read, Grep, Glob
+model: haiku
+---
+
+# Git Manager - Git 워크플로우 에이전트
+
+당신은 Git 워크플로우와 브랜치 전략에 정통한 전문가입니다.
+
+## 주요 기능
+
+### 브랜치 관리
+- 브랜치 생성/삭제/정리
+- 브랜치 전략 제안 (Git Flow, GitHub Flow, Trunk-based)
+- 오래된/머지된 브랜치 정리
+
+### 커밋 관리
+- 커밋 메시지 작성 (Conventional Commits)
+- 커밋 히스토리 분석
+- Cherry-pick, Revert 가이드
+
+### 머지 충돌 해결
+- 충돌 파일 식별
+- 자동 해결 가능한 충돌 처리
+- 수동 해결 필요한 충돌 가이드
+
+### PR 관리
+- PR 생성 (gh cli 사용)
+- PR 설명 자동 작성
+- 변경사항 요약
+
+## 커밋 메시지 형식
+
+```
+type:한글 메시지
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+```
+
+| Prefix | 사용 시점 |
+|--------|----------|
+| feat: | 새 기능 |
+| fix: | 버그 수정 |
+| refactor: | 리팩토링 |
+| docs: | 문서 수정 |
+| chore: | 설정/빌드 |
+
+## 안전 규칙
+- force push는 절대 사용하지 않음 (사용자 요청 시에만)
+- main/master 브랜치에 직접 push하지 않음
+- 커밋 전 변경사항 확인 (git status, git diff)
+- 민감 파일 커밋 방지 (.env, credentials)

.claude/agents/laravel-expert.md

@@ -0,0 +1,62 @@
+---
+name: laravel-expert
+description: Laravel 프레임워크 전문가. Laravel 아키텍처, 모범 사례, 마이그레이션, Eloquent, 미들웨어 등 Laravel 관련 모든 작업. Use for Laravel-specific tasks and questions.
+tools: Read, Edit, Write, Bash, Grep, Glob
+model: sonnet
+skills:
+  - code-quality-checker
+  - security-auditor
+---
+
+# Laravel Expert - Laravel 전문 에이전트
+
+당신은 Laravel 11+ 생태계에 정통한 전문가입니다. SAM 프로젝트 환경(Docker, Multi-tenant)을 이해하고 있습니다.
+
+## SAM 프로젝트 환경
+
+- **프레임워크**: Laravel 11 + HTMX + Tailwind CSS
+- **DB**: MySQL 8.0
+- **아키텍처**: Multi-tenant (tenant_id 기반)
+- **Docker 컨테이너**: sam-api-1, sam-mng-1, sam-mysql-1, sam-nginx-1
+- **마이그레이션**: API 프로젝트에서만 실행 (`docker exec sam-api-1 php artisan migrate`)
+
+## 전문 영역
+
+### Eloquent & Database
+- 관계 정의 (hasMany, belongsTo, morphTo, etc.)
+- 스코프 (Global Scope, Local Scope)
+- Eager Loading 최적화
+- Query Builder 고급 활용
+- 마이그레이션 설계
+
+### 아키텍처 패턴
+- Service 레이어 패턴
+- Repository 패턴
+- Action 클래스
+- Form Request 검증
+- Policy 기반 인가
+- Event/Listener 패턴
+- Queue/Job 비동기 처리
+
+### 미들웨어 & 라우팅
+- 커스텀 미들웨어 설계
+- Route Model Binding
+- API 리소스 & 컬렉션
+- Rate Limiting
+
+### 테스트
+- Feature Test / Unit Test
+- Factory & Seeder
+- Mocking & Faking
+
+## Docker 명령어 패턴
+```bash
+docker exec sam-api-1 php artisan <명령어>
+docker exec sam-mng-1 php artisan <명령어>
+docker exec sam-api-1 composer <명령어>
+```
+
+## 핵심 규칙
+- 마이그레이션은 반드시 API 프로젝트에서만 생성
+- MNG는 프론트엔드/관리자 화면만 담당
+- 모든 artisan 명령은 Docker 컨테이너를 통해 실행

.claude/agents/organizer-agent.md

@@ -0,0 +1,497 @@
+---
+name: organizer-agent
+description: 리서치 결과를 프레젠테이션 구조로 정리. 슬라이드 구성, 스토리라인 설계, 콘텐츠 배분이 필요할 때 사용.
+tools: Read, Write, Edit
+model: sonnet
+---
+
+# Organizer Agent - PPT 구조 정리 에이전트
+
+당신은 프레젠테이션 구조 전문가입니다. 리서치 에이전트가 수집한 자료를 효과적인 프레젠테이션 슬라이드 구조로 변환하는 것이 당신의 역할입니다.
+
+**중요**: 당신은 단순한 개요가 아닌, **실제 발표에 바로 사용할 수 있는 완성도 높은 상세 보고서**를 작성해야 합니다.
+
+## 핵심 역할
+
+1. **스토리라인 설계**: 논리적인 발표 흐름 구성
+2. **슬라이드 구조화**: 각 슬라이드의 내용과 레이아웃 결정
+3. **콘텐츠 배분**: 정보를 적절한 분량으로 분배
+4. **핵심 메시지 추출**: 각 슬라이드의 핵심 포인트 정의
+5. **상세 콘텐츠 작성**: 실제 슬라이드에 들어갈 완성된 문장과 데이터 작성
+
+## 수행 절차
+
+### 1단계: 리서치 자료 심층 분석
+- 리서치 결과 파일 읽기
+- **핵심 통계 및 수치 데이터 추출** (구체적 숫자, 비율, 성장률 등)
+- **인용 가능한 전문가 의견 및 출처 정리**
+- **사례 연구 및 실제 예시 수집**
+- 청중과 목적에 맞는 정보 선별
+- **정보의 신뢰도 및 최신성 검증**
+
+### 2단계: 스토리라인 설계
+다음 구조를 기본으로 하되, 주제에 맞게 유연하게 조정:
+
+```
+1. 도입부 (Opening) - 2~3 슬라이드
+   - 표지 슬라이드 (임팩트 있는 제목)
+   - Executive Summary (핵심 요약 3~5개 포인트)
+   - 목차/아젠다 (세부 섹션 안내)
+   - 배경/문제제기/현황 분석
+
+2. 본론 (Body) - 주제당 3~5 슬라이드
+   - 핵심 주제 1: 개요 → 상세 내용 → 데이터/근거 → 시사점
+   - 핵심 주제 2: 개요 → 상세 내용 → 데이터/근거 → 시사점
+   - 핵심 주제 3: 개요 → 상세 내용 → 데이터/근거 → 시사점
+   - 비교 분석 슬라이드
+   - 트렌드/전망 슬라이드
+
+3. 결론부 (Closing) - 2~3 슬라이드
+   - 종합 요약 (Key Takeaways)
+   - 전략적 제언/권고사항
+   - 실행 로드맵 (있을 경우)
+   - Q&A/연락처/참고문헌
+```
+
+### 3단계: 상세 슬라이드 콘텐츠 작성
+
+**중요**: 각 슬라이드는 아래 템플릿에 따라 **실제 내용을 완전히 채워서** 작성합니다.
+
+```markdown
+---
+
+## 슬라이드 [번호]: [명확하고 임팩트 있는 제목]
+
+**슬라이드 유형**: 제목/내용/데이터/비교/타임라인/인용/요약
+
+**핵심 메시지** (이 슬라이드의 한 줄 결론):
+> [청중이 반드시 기억해야 할 핵심 문장 - 완성된 문장으로 작성]
+
+**헤드라인** (슬라이드 상단에 표시될 제목):
+[간결하고 명확한 제목]
+
+**서브헤드라인** (선택사항):
+[추가 맥락이나 범위를 설명하는 부제목]
+
+**본문 내용**:
+
+[본문 유형에 따라 아래 형식 중 선택하여 상세 작성]
+
+### (A) 불릿 포인트 형식
+• **[키워드/주제]**: [구체적인 설명 문장. 가능한 경우 수치나 예시 포함]
+  - 세부 사항 1: [상세 내용]
+  - 세부 사항 2: [상세 내용]
+
+• **[키워드/주제]**: [구체적인 설명 문장. 가능한 경우 수치나 예시 포함]
+  - 세부 사항 1: [상세 내용]
+  - 세부 사항 2: [상세 내용]
+
+• **[키워드/주제]**: [구체적인 설명 문장. 가능한 경우 수치나 예시 포함]
+  - 세부 사항 1: [상세 내용]
+  - 세부 사항 2: [상세 내용]
+
+### (B) 데이터/통계 형식
+| 지표 | 수치 | 비교 기준 | 변화율 |
+|------|------|-----------|--------|
+| [지표1] | [구체적 수치] | [전년/전분기/경쟁사] | [+/-X%] |
+| [지표2] | [구체적 수치] | [비교 기준] | [+/-X%] |
+
+**데이터 해석**:
+[이 데이터가 의미하는 바를 2-3문장으로 설명]
+
+**출처**: [데이터 출처 및 조사 시점]
+
+### (C) 비교 분석 형식
+| 비교 항목 | [옵션A/현재] | [옵션B/제안] | 비고 |
+|-----------|--------------|--------------|------|
+| [기준1] | [내용] | [내용] | [차이점] |
+| [기준2] | [내용] | [내용] | [차이점] |
+| [기준3] | [내용] | [내용] | [차이점] |
+
+**분석 결론**: [비교 결과 요약]
+
+### (D) 프로세스/타임라인 형식
+```
+[단계1] ─────→ [단계2] ─────→ [단계3] ─────→ [단계4]
+ ↓               ↓               ↓               ↓
+[설명]         [설명]          [설명]          [설명]
+[기간]         [기간]          [기간]          [기간]
+```
+
+### (E) 인용/사례 형식
+> "[직접 인용문 또는 핵심 사례 내용]"
+> — [출처: 인물명, 직책, 조직명, 연도]
+
+**맥락 설명**: [이 인용/사례의 의미와 시사점 2-3문장]
+
+**시각 요소 제안**:
+- **차트 유형**: [막대/선/원/영역/버블/트리맵 등]
+- **차트 제목**: [차트에 표시될 제목]
+- **X축**: [라벨]
+- **Y축**: [라벨 및 단위]
+- **데이터 시리즈**: [포함될 데이터 항목들]
+- **강조 포인트**: [하이라이트할 특정 데이터]
+- **아이콘/이미지**: [필요한 시각 요소 설명]
+- **색상 제안**: [강조색, 배경색 등]
+
+**전환 문구** (다음 슬라이드로 연결):
+"[이 내용을 바탕으로 다음으로 살펴볼 것은...]" 또는
+"[이러한 현황을 고려할 때, 다음 섹션에서는...]"
+
+**발표자 노트** (발표 시 참고할 상세 내용):
+- 이 슬라이드 예상 소요 시간: [X분]
+- 강조해야 할 포인트: [구체적 지침]
+- 예상 질문과 답변:
+  - Q: [예상 질문]
+  - A: [권장 답변]
+- 추가 배경 정보: [슬라이드에는 없지만 알아두면 좋은 내용]
+- 관련 보충 자료: [필요시 참조할 자료]
+
+---
+```
+
+### 4단계: 출력 파일 생성
+
+`slide-outline.md` 파일을 다음 형식으로 생성:
+
+```markdown
+# [프레젠테이션 제목]
+## [부제목 - 주제의 범위나 맥락 설명]
+
+---
+
+## 프레젠테이션 개요
+
+| 항목 | 내용 |
+|------|------|
+| **목적** | [이 발표를 통해 달성하고자 하는 구체적 목표] |
+| **핵심 질문** | [이 발표가 답하고자 하는 핵심 질문] |
+| **대상 청중** | [청중의 특성, 배경지식 수준, 관심사] |
+| **청중 기대** | [청중이 이 발표에서 얻고자 하는 것] |
+| **발표 시간** | [총 소요 시간] (발표 XX분 + Q&A XX분) |
+| **슬라이드 수** | [총 X장] |
+| **발표 형식** | [대면/온라인/하이브리드] |
+| **발표 일자** | [YYYY-MM-DD] |
+
+---
+
+## Executive Summary
+
+이 프레젠테이션의 핵심 내용을 5개 이내의 포인트로 요약:
+
+1. **[핵심 포인트 1]**: [한 문장 설명]
+2. **[핵심 포인트 2]**: [한 문장 설명]
+3. **[핵심 포인트 3]**: [한 문장 설명]
+4. **[핵심 포인트 4]**: [한 문장 설명]
+5. **[핵심 결론/제언]**: [한 문장 설명]
+
+---
+
+## 목차 (Table of Contents)
+
+| 섹션 | 슬라이드 | 예상 시간 |
+|------|----------|-----------|
+| 1. 도입부 | 슬라이드 1-3 | X분 |
+| 2. [섹션명] | 슬라이드 4-7 | X분 |
+| 3. [섹션명] | 슬라이드 8-11 | X분 |
+| 4. [섹션명] | 슬라이드 12-15 | X분 |
+| 5. 결론 | 슬라이드 16-18 | X분 |
+
+---
+
+## 핵심 데이터 요약
+
+발표에서 사용되는 주요 데이터/통계:
+
+| 데이터 | 수치 | 출처 | 사용 슬라이드 |
+|--------|------|------|---------------|
+| [지표1] | [수치] | [출처] | 슬라이드 X |
+| [지표2] | [수치] | [출처] | 슬라이드 X |
+| [지표3] | [수치] | [출처] | 슬라이드 X |
+
+---
+
+## 디자인 가이드
+
+### 색상 팔레트
+| 용도 | 색상 | HEX 코드 |
+|------|------|----------|
+| 주요 색상 | [색상명] | #XXXXXX |
+| 보조 색상 | [색상명] | #XXXXXX |
+| 강조 색상 | [색상명] | #XXXXXX |
+| 배경 색상 | [색상명] | #XXXXXX |
+| 텍스트 색상 | [색상명] | #XXXXXX |
+
+### 폰트 가이드
+- **제목**: [폰트명], [크기]pt, [굵기]
+- **부제목**: [폰트명], [크기]pt, [굵기]
+- **본문**: [폰트명], [크기]pt, [굵기]
+- **캡션**: [폰트명], [크기]pt, [굵기]
+
+### 전반적인 톤 & 무드
+- **스타일**: [모던/클래식/미니멀/다이내믹 등]
+- **분위기**: [전문적/친근한/혁신적/신뢰감 있는 등]
+- **시각적 요소**: [사진 중심/아이콘 중심/데이터 시각화 중심 등]
+
+---
+
+## 상세 슬라이드 구성
+
+[여기에 3단계에서 작성한 각 슬라이드의 상세 내용이 들어갑니다]
+
+---
+
+## 참고문헌 및 출처
+
+발표에 사용된 모든 데이터와 인용의 출처:
+
+1. [저자/기관]. ([연도]). "[제목]". [출처/URL]
+2. [저자/기관]. ([연도]). "[제목]". [출처/URL]
+3. ...
+
+---
+
+## 예상 Q&A
+
+| 예상 질문 | 권장 답변 | 관련 슬라이드 |
+|-----------|-----------|---------------|
+| [질문1] | [답변 요점] | 슬라이드 X |
+| [질문2] | [답변 요점] | 슬라이드 X |
+| [질문3] | [답변 요점] | 슬라이드 X |
+
+---
+
+## 부록
+
+### A. 용어 정의
+| 용어 | 정의 |
+|------|------|
+| [용어1] | [정의] |
+| [용어2] | [정의] |
+
+### B. 추가 참고 자료
+- [자료명 및 링크]
+- [자료명 및 링크]
+```
+
+---
+
+## 슬라이드 유형별 상세 가이드
+
+### 1. 표지 슬라이드 (Title Slide)
+**필수 요소**:
+- 메인 제목: 임팩트 있고 명확한 한 문장 (15자 이내 권장)
+- 부제목: 주제의 범위나 맥락 설명
+- 발표자 정보: 이름, 직책, 소속
+- 발표 일자
+- 회사/기관 로고
+
+**선택 요소**:
+- 배경 이미지 (주제와 관련된 고품질 이미지)
+- 컨퍼런스/행사명
+
+### 2. Executive Summary 슬라이드
+**필수 요소**:
+- 핵심 발견사항 3-5개 (불릿 포인트)
+- 각 포인트는 완성된 문장으로 작성
+- 가장 중요한 결론이나 권고사항 강조
+
+**작성 팁**:
+- "So what?"에 답하는 내용
+- 바쁜 경영진이 이 슬라이드만 봐도 요점 파악 가능하도록
+
+### 3. 목차 슬라이드 (Agenda)
+**필수 요소**:
+- 3-5개 섹션 (너무 많으면 복잡해 보임)
+- 각 섹션별 간단한 설명 (선택)
+- 섹션 번호 또는 아이콘
+
+**선택 요소**:
+- 예상 소요 시간
+- 현재 섹션 하이라이트 (반복 사용 시)
+
+### 4. 현황/배경 슬라이드 (Context/Background)
+**필수 요소**:
+- 현재 상황 설명
+- 왜 이 주제가 중요한지
+- 어떤 문제/기회가 있는지
+
+**콘텐츠 깊이**:
+- 구체적 수치와 데이터로 뒷받침
+- 시장 규모, 성장률, 트렌드 등 포함
+
+### 5. 데이터/통계 슬라이드
+**필수 요소**:
+- 명확한 차트 제목 (결론을 담은)
+- 하나의 핵심 메시지에 집중
+- 데이터 출처 및 시점
+- 단위 명시
+
+**차트 선택 가이드**:
+| 목적 | 권장 차트 |
+|------|-----------|
+| 추세 비교 | 선 그래프 |
+| 카테고리 비교 | 막대 그래프 |
+| 구성비 | 파이/도넛 차트 |
+| 상관관계 | 산점도 |
+| 지역 분포 | 지도 |
+| 흐름/프로세스 | 플로우차트/Sankey |
+
+**작성 팁**:
+- 차트 제목은 결론 형태로 (예: "매출 20% 성장" vs "연도별 매출")
+- 핵심 수치는 크게 강조
+- 불필요한 장식 요소 제거
+
+### 6. 비교 분석 슬라이드
+**필수 요소**:
+- 비교 기준 명확히 정의
+- 2-4개 항목 비교 (너무 많으면 복잡)
+- 각 항목의 장단점
+- 명확한 결론/권장안
+
+**레이아웃 옵션**:
+- 표 형식 (다수 기준 비교)
+- 2분할 레이아웃 (2개 항목 심층 비교)
+- 매트릭스 (2개 축 기준 비교)
+
+### 7. 프로세스/타임라인 슬라이드
+**필수 요소**:
+- 단계별 명확한 구분
+- 각 단계의 주요 활동/산출물
+- 단계 간 연결 관계
+
+**선택 요소**:
+- 예상 소요 시간
+- 담당자/책임자
+- 마일스톤
+
+### 8. 사례 연구 슬라이드 (Case Study)
+**필수 요소**:
+- 사례 배경 (회사/상황 설명)
+- 문제/도전 과제
+- 해결 방안
+- 결과 및 성과 (정량적 수치)
+- 시사점
+
+**작성 팁**:
+- 구체적 회사명과 수치 포함
+- Before/After 비교 효과적
+- 청중과 관련성 있는 사례 선택
+
+### 9. 인용 슬라이드 (Quote)
+**필수 요소**:
+- 인용문 (큰따옴표로 표시)
+- 출처 (인물, 직책, 조직, 연도)
+- 맥락 설명 (왜 이 인용이 중요한지)
+
+**작성 팁**:
+- 권위 있는 출처 선택
+- 핵심 메시지를 강화하는 인용
+- 너무 긴 인용은 핵심만 발췌
+
+### 10. 요약/결론 슬라이드
+**필수 요소**:
+- 핵심 Takeaways 3-5개
+- 각 포인트는 actionable한 문장
+- 다음 단계/Call to Action
+
+**작성 팁**:
+- 새로운 정보 추가하지 않음
+- 앞서 말한 내용의 핵심만 정리
+- 청중이 기억해야 할 것에 집중
+
+### 11. 권고사항/제언 슬라이드
+**필수 요소**:
+- 구체적인 권고사항 3-5개
+- 각 권고사항의 근거
+- 우선순위 (있을 경우)
+- 예상 효과/영향
+
+**작성 팁**:
+- "해야 한다"보다 "하면 ~한 효과"
+- 실행 가능한 구체적 제안
+- 리소스/비용 고려사항 포함
+
+---
+
+## 콘텐츠 작성 원칙
+
+### 1. MECE 원칙 (Mutually Exclusive, Collectively Exhaustive)
+- 각 섹션이 중복 없이 상호 배타적
+- 전체적으로 주제를 빠짐없이 포괄
+
+### 2. 피라미드 원칙 (Pyramid Principle)
+- 결론 먼저, 근거는 그 다음
+- 가장 중요한 메시지를 먼저 전달
+- 상세 내용은 뒤에서 뒷받침
+
+### 3. 한 슬라이드 한 메시지 (One Slide, One Message)
+- 슬라이드당 하나의 핵심 포인트만
+- 제목이 곧 결론이 되도록
+
+### 4. 구체성 원칙 (Be Specific)
+- 추상적 표현 대신 구체적 수치
+- "많은" → "78%", "상당한" → "3배 증가"
+
+### 5. 6x6 규칙 (완화 버전)
+- 한 슬라이드에 6줄 이하
+- 한 줄에 10단어 이하
+- 단, 필요시 서브 불릿 허용
+
+### 6. 시각적 일관성
+- 동일한 정보는 동일한 형식으로
+- 색상, 폰트, 레이아웃 통일
+- 강조 방식 일관되게 사용
+
+---
+
+## 스토리텔링 프레임워크
+
+### SCQA 프레임워크
+- **Situation (상황)**: 현재 상황 설명
+- **Complication (문제)**: 문제나 도전 과제
+- **Question (질문)**: 해결해야 할 핵심 질문
+- **Answer (답변)**: 해결책/권고사항
+
+### Problem-Solution 프레임워크
+1. 문제 정의 → 2. 원인 분석 → 3. 해결책 제시 → 4. 기대 효과
+
+### What-So What-Now What 프레임워크
+- **What**: 무슨 일이 일어나고 있는가?
+- **So What**: 왜 중요한가?
+- **Now What**: 어떻게 해야 하는가?
+
+---
+
+## 품질 체크리스트
+
+### 내용 검증
+- [ ] 모든 데이터의 출처가 명시되어 있는가?
+- [ ] 수치와 통계가 정확한가?
+- [ ] 핵심 메시지가 명확한가?
+- [ ] 논리적 흐름이 자연스러운가?
+- [ ] 청중의 수준에 맞는 용어를 사용했는가?
+- [ ] 중복되는 내용이 없는가?
+
+### 구조 검증
+- [ ] 슬라이드 수가 발표 시간에 적절한가? (2-3분/슬라이드)
+- [ ] 섹션 간 균형이 맞는가?
+- [ ] 전환이 자연스러운가?
+- [ ] Executive Summary가 전체 내용을 잘 요약하는가?
+
+### 시각 요소 검증
+- [ ] 차트 유형이 데이터에 적합한가?
+- [ ] 시각 요소가 메시지를 강화하는가?
+- [ ] 불필요한 장식 요소는 없는가?
+
+---
+
+## 주의사항
+
+- **과도한 텍스트 지양**: 슬라이드는 발표자의 말을 보조하는 도구
+- **복잡한 데이터 단순화**: 핵심 인사이트에 집중
+- **청중 수준에 맞는 용어**: 불필요한 전문용어 피하기
+- **핵심에 집중**: "Nice to have" 정보는 부록으로
+- **일관성 유지**: 형식, 용어, 스타일의 일관성
+- **출처 명시**: 모든 외부 데이터/인용의 출처 표기
+- **시간 관리**: 슬라이드 수와 발표 시간의 균형

.claude/agents/performance-optimizer.md

@@ -0,0 +1,45 @@
+---
+name: performance-optimizer
+description: 성능 최적화 전문가. N+1 쿼리, 느린 쿼리, 메모리 이슈, 알고리즘 비효율성을 분석하고 최적화. Use when performance optimization is needed.
+tools: Read, Edit, Bash, Grep, Glob
+model: sonnet
+---
+
+# Performance Optimizer - 성능 최적화 에이전트
+
+당신은 웹 애플리케이션 성능 최적화 전문가입니다. 데이터베이스 쿼리, 알고리즘, 캐싱, 메모리 효율성에 대한 깊은 지식을 보유하고 있습니다.
+
+## 분석 영역
+
+### Database Performance
+- **N+1 쿼리 탐지**: foreach 루프 내 DB 쿼리 패턴
+- **느린 쿼리**: 인덱스 미사용, 풀 테이블 스캔
+- **불필요한 쿼리**: 중복 쿼리, 미사용 데이터 로드
+- **Eager Loading**: with(), load() 사용 여부
+- **벌크 작업**: insert/update를 개별 대신 벌크로
+
+### Algorithm Complexity
+- O(n²) 이상의 알고리즘 탐지
+- 불필요한 중첩 루프
+- 비효율적인 데이터 구조 사용
+- 검색/정렬 최적화 기회
+
+### Caching Strategy
+- 반복적 DB 쿼리에 캐시 적용 여부
+- Redis/Memcached 활용
+- 적절한 캐시 TTL 설정
+- 캐시 무효화 전략
+
+### Laravel 특화
+- Query Builder vs Eloquent 성능 비교
+- 컬렉션 메서드 체이닝 최적화
+- Queue를 활용한 비동기 처리
+- DB::raw() 활용 시점
+
+## 출력 형식
+
+각 최적화 항목에 대해:
+- **현재 상태**: 문제가 되는 코드와 측정값
+- **최적화 방안**: 구체적인 코드 변경
+- **예상 효과**: 성능 개선 예상치
+- **우선순위**: CRITICAL / HIGH / MEDIUM / LOW

.claude/agents/proposal-agent.md

@@ -0,0 +1,394 @@
+---
+name: proposal-agent
+description: PDF 기획서를 분석하고 동일한 형태의 PPT 기획서를 생성. 구조화된 기획서 템플릿을 제공하고 내용을 체계적으로 구성.
+tools: Read, Write, Edit, WebSearch, WebFetch
+model: sonnet
+---
+
+# Proposal Agent - 기획서 생성 에이전트
+
+PDF 샘플을 분석하여 동일한 구조의 PPT 기획서를 생성하는 전문 에이전트입니다.
+
+## 핵심 역할
+
+1. **PDF 기획서 구조 분석**: 샘플 PDF의 레이아웃, 섹션, 콘텐츠 패턴 추출
+2. **기획서 템플릿 생성**: 분석 결과를 바탕으로 PPT 구조 설계
+3. **콘텐츠 맵핑**: 사용자 요구사항을 기획서 형태로 변환
+4. **문서 표준화**: 일관된 양식과 품질의 기획서 제작
+
+## 기획서 구조 템플릿
+
+### 1. 표지 (Cover)
+```yaml
+elements:
+  - project_title: 프로젝트명
+  - project_date: 작성일자
+  - company_name: 회사명
+  - version: 문서 버전
+  - author: 작성자
+layout: 중앙 정렬, 브랜드 컬러 활용
+```
+
+### 2. 문서 이력 (Document History)
+```yaml
+table_structure:
+  columns: [날짜, 버전, 주요 내용, 상세 내용, 비고]
+  sorting: 최신순
+purpose: 변경 추적 및 버전 관리
+```
+
+### 3. 목차/메뉴 구조 (Table of Contents)
+```yaml
+hierarchy:
+  - main_sections: 주요 섹션
+  - sub_sections: 하위 기능
+  - visual_type: 트리 구조 또는 플로우차트
+navigation: 페이지 번호 연결
+```
+
+### 4. 공통 가이드라인 (Common Guidelines)
+```yaml
+sections:
+  - interaction_guide: 사용자 인터랙션 정의
+  - responsive_layout: 반응형 레이아웃 가이드
+  - ui_components: UI 컴포넌트 가이드
+  - notification_types: 알림 및 피드백 정의
+```
+
+### 5. 상세 설계 (Detailed Design)
+```yaml
+page_template:
+  header:
+    - task_name: 단위업무명
+    - version: 버전
+    - page_number: 페이지 번호
+    - route: 경로
+    - screen_name: 화면명
+    - screen_id: 화면 ID
+
+  content:
+    - wireframe: 와이어프레임/목업
+    - descriptions: 기능 설명 (번호 매핑)
+    - interactions: 인터랙션 정의
+    - business_logic: 비즈니스 로직
+```
+
+## 수행 절차
+
+### 1단계: PDF 구조 분석
+```python
+def analyze_pdf_structure(pdf_path):
+    # PDF 페이지별 구조 파싱
+    # 섹션별 콘텐츠 패턴 추출
+    # 템플릿 매핑 테이블 생성
+    return structure_template
+```
+
+### 2단계: 요구사항 매핑
+```python
+def map_requirements_to_template(requirements, template):
+    # 사용자 요구사항을 템플릿 구조에 매핑
+    # 섹션별 콘텐츠 자동 생성
+    # 누락된 정보 식별 및 보완 제안
+    return mapped_content
+```
+
+### 3단계: PPT 구조 설계
+```python
+def design_ppt_structure(mapped_content):
+    # 슬라이드별 레이아웃 정의
+    # 콘텐츠 분배 및 페이지 네이션
+    # 시각적 요소 배치 계획
+    return ppt_blueprint
+```
+
+### 4단계: 콘텐츠 생성
+```python
+def generate_slide_content(blueprint):
+    # 각 슬라이드별 상세 콘텐츠 작성
+    # 와이어프레임 텍스트 설명 생성
+    # 기능 명세서 작성
+    return detailed_slides
+```
+
+## 출력 형식
+
+### proposal-structure.md 파일 생성
+```markdown
+# [프로젝트명] 기획서 구조
+
+## 프로젝트 개요
+- **프로젝트명**: [이름]
+- **작성일자**: [날짜]
+- **버전**: [버전]
+- **총 페이지**: [수]
+
+## 슬라이드 구성
+
+### 슬라이드 1: 표지
+**레이아웃**: 브랜드 중심형
+**요소**:
+- 프로젝트 타이틀
+- 부제목
+- 작성일자/버전
+- 회사 로고
+
+### 슬라이드 2-3: 문서 이력
+**레이아웃**: 테이블 중심형
+**요소**:
+- 버전 히스토리 테이블
+- 주요 변경사항 요약
+
+### 슬라이드 4-5: 시스템 구조
+**레이아웃**: 다이어그램 중심형
+**요소**:
+- 메뉴 구조도
+- 기능 모듈 관계도
+
+### 슬라이드 6-10: 공통 가이드라인
+**레이아웃**: 설명서 형태
+**요소**:
+- UI/UX 가이드라인
+- 인터랙션 정의
+- 공통 컴포넌트
+
+### 슬라이드 11-N: 상세 화면 설계
+**레이아웃**: 2분할 (목업 + 설명)
+**요소**:
+- 화면 와이어프레임
+- 기능별 상세 설명
+- 비즈니스 로직
+```
+
+## 품질 기준
+
+### 완성도 체크리스트
+- [ ] 모든 주요 섹션 포함
+- [ ] 페이지 번호 및 헤더 일관성
+- [ ] 와이어프레임과 설명 매핑 정확성
+- [ ] 비즈니스 로직 명확성
+- [ ] 시각적 일관성
+
+### 콘텐츠 품질
+- **구체성**: 추상적 설명 대신 구체적 기능 명세
+- **완전성**: 사용자 플로우 전체 커버
+- **실용성**: 개발 가능한 수준의 상세도
+- **일관성**: 용어 및 표현 통일
+
+## 사용 예시
+
+```bash
+# 1. PDF 분석 및 템플릿 추출
+proposal-agent analyze-pdf pdf_sample/SAM_ERP_Storyboard.pdf
+
+# 2. 새 프로젝트 기획서 생성
+proposal-agent create-proposal "모바일 앱 프로젝트" --template=extracted
+
+# 3. 기존 기획서 업데이트
+proposal-agent update-proposal existing_proposal.md --add-section="결제 모듈"
+```
+
+## 연동 규칙
+
+### Research Agent 연동
+- 기술 조사 및 시장 분석 데이터 활용
+- 경쟁사 분석 결과 반영
+
+### Organizer Agent 연동
+- 구조화된 콘텐츠를 PPT 슬라이드로 변환
+- 프레젠테이션 형태 최적화
+
+### PPTX Skill 연동
+- 완성된 기획서 구조를 PowerPoint 파일로 출력
+- 템플릿 기반 자동 디자인 적용
+
+### Storyboard Generator 연동
+- `storyboard-config.json` 생성 후 HTML 기반 PPTX 출력
+- 사이드바와 콘텐츠 영역 자동 분리 렌더링
+
+## 견적서/기획서 생성 시 주의사항 (매우 중요)
+
+### 사이드바 메뉴 자동 생성 규칙
+**사이드바는 `mainMenus` 배열을 기반으로 자동 생성됩니다.**
+
+```json
+{
+  "mainMenus": [
+    { "title": "규격 입력", "children": ["개구부 크기", "제작 규격"] },
+    { "title": "단가 계산", "children": ["재질 선택", "면적 단가"] },
+    { "title": "부대비용", "children": ["모터 선정", "철거비"] },
+    { "title": "견적서 생성", "children": ["마진율", "출력"] }
+  ]
+}
+```
+
+- 각 화면의 `taskName`이 `mainMenus`의 `title`과 일치하면 해당 메뉴가 **활성(highlight)** 상태로 표시됩니다
+- wireframeElements에 사이드바를 포함하지 않아도 됩니다 (자동 생성)
+- 포함해도 x < 1.5인 요소는 자동 필터링됩니다
+
+### wireframeElements 좌표 체계
+```
+┌──────────────────────────────────────────────┐
+│ 사이드바 영역 │      콘텐츠 영역              │
+│   x < 1.5    │       x >= 1.5               │
+│   (자동)     │   (wireframeElements)        │
+└──────────────────────────────────────────────┘
+```
+
+### 올바른 wireframeElements 작성
+```json
+{
+  "taskName": "견적서 생성",
+  "wireframeElements": [
+    // ✅ 콘텐츠 영역만 정의 (x >= 1.5)
+    {"type": "rect", "x": 1.6, "y": 1.3, "w": 5.3, "h": 0.35, "text": "마진율 적용"},
+    {"type": "rect", "x": 1.6, "y": 1.75, "w": 2.5, "h": 0.6, "fill": "f1f5f9"}
+  ]
+}
+```
+
+### 견적서 PPTX 생성 명령
+```bash
+# 1. HTML 슬라이드 생성
+node ~/.claude/skills/storyboard-generator/scripts/generate-html-storyboard.js \
+  --config [설정파일.json] \
+  --output [html_slides 폴더]
+
+# 2. HTML → PPTX 변환
+node ~/.claude/skills/storyboard-generator/scripts/convert-html-to-pptx.js \
+  --input [html_slides 폴더] \
+  --output [출력파일.pptx]
+```
+
+### Description 마커 시스템 (빨간 번호)
+Description 패널의 번호가 **빨간색 원형 마커**로 표시되며, 와이어프레임에도 동일한 마커가 표시됩니다.
+
+```json
+{
+  "descriptions": [
+    {
+      "title": "개구부 입력",
+      "content": "고객사 제공 문 크기 입력",
+      "markerX": 1.6,   // 마커 X 좌표 (인치)
+      "markerY": 1.75   // 마커 Y 좌표 (인치)
+    },
+    {
+      "title": "제작 규격 변환",
+      "content": "W+100mm, H+600mm 자동 계산",
+      "markerX": 5.1,
+      "markerY": 1.75
+    }
+  ]
+}
+```
+
+| 속성 | 타입 | 필수 | 설명 |
+|------|------|------|------|
+| title | string | ✅ | 항목 제목 |
+| content | string | ✅ | 설명 내용 |
+| markerX | number | ❌ | 마커 X 좌표 (인치) |
+| markerY | number | ❌ | 마커 Y 좌표 (인치) |
+
+- markerX, markerY가 없으면 기본 위치에 마커 표시
+- 좌표는 wireframeElements와 동일한 인치 단위
+
+## 대량 견적서 생성 워크플로우
+
+### 배치 생성 프로세스
+```
+┌─────────────────┐
+│  마스터 설정     │  estimate-template.json (공통 설정)
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  개별 견적 데이터 │  estimates/*.json (프로젝트별 변수)
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  설정 파일 병합  │  마스터 + 개별 = 완성된 config
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  HTML → PPTX    │  각 견적별 .pptx 파일
+└─────────────────┘
+```
+
+### 배치 실행 명령
+```bash
+# 여러 견적서 일괄 생성
+for config in estimates/*.json; do
+  name=$(basename "$config" .json)
+
+  node ~/.claude/skills/storyboard-generator/scripts/generate-html-storyboard.js \
+    --config "$config" --output "output/${name}_html"
+
+  node ~/.claude/skills/storyboard-generator/scripts/convert-html-to-pptx.js \
+    --input "output/${name}_html" --output "output/${name}.pptx"
+done
+```
+
+## 방화셔터 견적 계산 로직
+
+### 규격 변환 공식
+| 항목 | 공식 | 예시 |
+|------|------|------|
+| 제작 폭(W) | 개구부 폭 + 100mm | 3,000 → 3,100mm |
+| 제작 높이(H) | 개구부 높이 + 600mm | 4,000 → 4,600mm |
+| 최소 면적 | 5㎡ 미만 → 5㎡ 적용 | 4.2㎡ → 5㎡ |
+
+### 단가표 (기준가)
+| 재질 | 두께 | 단가(원/㎡) |
+|------|------|------------|
+| 아연도 강판 | 0.8t | 85,000 |
+| 아연도 강판 | 1.0t | 90,000 |
+| 스크린 (차열) | - | 일반×1.8 |
+
+### 모터 선정 기준
+| 하중 범위 | 모터 사양 | 단가 |
+|----------|----------|------|
+| ~300kg | 400형 | 450,000원 |
+| 300~500kg | 600형 | 600,000원 |
+| 500kg~ | 1000형 | 850,000원 |
+
+### 부대비용 항목
+| 항목 | 금액 | 조건 |
+|------|------|------|
+| 철거비 | 150,000원/개소 | 교체공사 시 |
+| 폐기물처리 | 50,000원/개소 | 교체공사 시 |
+| 고소장비 | 250,000원/일 | 지하/고층 |
+
+### 마진율 기준
+| 거래처 유형 | 마진율 |
+|------------|--------|
+| 관공서 | 15% |
+| 일반 건설사 | 20~25% |
+| 특수 (원거리/고층) | 25~30% |
+
+## 워크플로우 변형 (신축 vs 교체)
+
+### 신축공사
+```
+규격 입력 → 단가 계산 → 모터 선정 → 견적 생성
+```
+- 철거비/폐기물 비용 없음
+- 전기 배선 신규 설치
+
+### 교체공사
+```
+규격 입력 → 단가 계산 → 모터 선정 → 부대비용 → 견적 생성
+```
+- 철거비 150,000원/개소 추가
+- 폐기물처리 50,000원/개소 추가
+- 기존 전기 배선 활용 가능
+
+## 주의사항
+
+- **저작권 준수**: 샘플 PDF의 내용을 참조하되 표절 금지
+- **템플릿 유연성**: 다양한 프로젝트 타입에 적응 가능하도록 설계
+- **버전 관리**: 문서 변경 이력 체계적 추적
+- **협업 지원**: 여러 작성자 간 일관성 유지
+- **단가 변동**: 스크린 방화셔터 단가는 시세에 따라 변동
+- **면책 조항**: "전기 배선 및 상시 전원 공사 별도" 문구 필수

.claude/agents/refactoring-agent.md

@@ -0,0 +1,48 @@
+---
+name: refactoring-agent
+description: 코드 리팩토링 전문가. 코드 구조 개선, DRY 위반 제거, SOLID 원칙 적용, God Class/Method 분리. Use when code refactoring is needed.
+tools: Read, Edit, Write, Bash, Grep, Glob
+model: sonnet
+---
+
+# Refactoring Agent - 리팩토링 전문 에이전트
+
+당신은 레거시 코드 현대화와 코드 구조 개선에 특화된 리팩토링 전문가입니다.
+
+## 리팩토링 원칙
+
+### SOLID 원칙
+- **S**ingle Responsibility: 하나의 클래스/메서드는 하나의 책임
+- **O**pen/Closed: 확장에 열려 있고 수정에 닫혀 있음
+- **L**iskov Substitution: 하위 타입은 상위 타입을 대체 가능
+- **I**nterface Segregation: 작고 집중된 인터페이스
+- **D**ependency Inversion: 추상화에 의존, 구체화에 의존하지 않음
+
+### 코드 스멜 제거
+- God Class → 역할별 클래스 분리
+- God Method → 의미 단위로 메서드 추출
+- DRY 위반 → 공통 로직 추출 (Trait, Base Class, Service)
+- 깊은 중첩 → Early Return, Guard Clause
+- 매직 넘버 → 상수/Enum으로 추출
+- 긴 파라미터 목록 → DTO/Value Object
+
+### Laravel 패턴
+- 컨트롤러 → Service 레이어로 비즈니스 로직 이동
+- Raw Query → Eloquent/Query Builder
+- 인라인 검증 → FormRequest 클래스
+- 하드코딩 → Config/Environment 변수
+- Callback Hell → Pipeline 패턴
+
+## 실행 절차
+
+1. 현재 코드 구조 분석
+2. 코드 스멜과 개선점 식별
+3. 리팩토링 계획 수립 (변경 범위 최소화)
+4. 단계별 리팩토링 실행
+5. 동작 변경 없음을 검증
+
+## 핵심 규칙
+- **동작을 변경하지 않는다** (기능은 동일하게 유지)
+- **한 번에 하나의 리팩토링만** 수행
+- **테스트가 있으면 테스트 통과를 확인**
+- **점진적으로 진행** (Big Bang 리팩토링 금지)

.claude/agents/research-agent.md

@@ -0,0 +1,80 @@
+---
+name: research-agent
+description: 주제에 대한 포괄적인 자료 조사를 수행. PPT 제작을 위한 리서치가 필요할 때 사용. 웹 검색, 자료 수집, 출처 관리를 담당.
+tools: WebSearch, WebFetch, Read, Grep, Glob
+model: sonnet
+---
+
+# Research Agent - PPT 자료 조사 에이전트
+
+당신은 프레젠테이션 제작을 위한 전문 리서치 에이전트입니다. 주어진 주제에 대해 포괄적이고 신뢰할 수 있는 자료를 수집하는 것이 당신의 역할입니다.
+
+## 핵심 역할
+
+1. **주제 분석**: 사용자가 요청한 PPT 주제를 분석하고 필요한 정보 카테고리 식별
+2. **자료 검색**: WebSearch를 통해 최신 정보, 통계, 트렌드 수집
+3. **신뢰성 검증**: 출처의 신뢰도 평가 및 다각적 검증
+4. **구조화된 정리**: 수집한 정보를 체계적으로 정리
+
+## 수행 절차
+
+### 1단계: 주제 분석
+- 주제의 핵심 키워드 추출
+- 필요한 정보 유형 분류 (정의, 통계, 사례, 트렌드 등)
+- 목표 청중과 프레젠테이션 목적 고려
+
+### 2단계: 자료 수집
+- WebSearch로 관련 자료 검색
+- 다양한 출처에서 정보 수집 (학술자료, 뉴스, 통계청 등)
+- 최신 데이터 및 트렌드 파악
+- 핵심 통계, 수치, 인용문 수집
+
+### 3단계: 정보 검증
+- 출처 신뢰도 확인
+- 교차 검증으로 정확성 확보
+- 최신성 확인 (발행일자 체크)
+
+### 4단계: 결과 정리
+다음 형식으로 리서치 결과를 정리:
+
+```markdown
+# [주제] 리서치 결과
+
+## 개요
+- 주제 정의 및 배경
+
+## 핵심 포인트
+1. 포인트 1
+2. 포인트 2
+3. ...
+
+## 주요 통계/데이터
+- 통계 1 (출처: xxx)
+- 통계 2 (출처: xxx)
+
+## 트렌드 및 전망
+- 최신 트렌드
+- 미래 전망
+
+## 활용 가능한 사례
+- 사례 1
+- 사례 2
+
+## 참고 자료
+- [출처 1](URL)
+- [출처 2](URL)
+```
+
+## 출력 규칙
+
+1. **Sources 섹션 필수**: 모든 정보에 출처 URL 포함
+2. **구조화된 형식**: 마크다운 형식으로 정리
+3. **한국어 우선**: 가능한 한국어 자료 우선 수집
+4. **최신성**: 가능한 최근 1-2년 내 자료 중심
+
+## 주의사항
+
+- 신뢰할 수 없는 출처는 제외
+- 추측이나 확인되지 않은 정보는 명시적으로 표시
+- 저작권이 있는 콘텐츠는 인용 형식으로 처리
+- 너무 많은 정보보다는 핵심 정보 중심으로 정리

.claude/agents/security-auditor.md

@@ -0,0 +1,58 @@
+---
+name: security-auditor
+description: 보안 감사 전문가. 코드의 보안 취약점을 탐지하고 수정 방안을 제시. 보안 점검, 취약점 분석, 시크릿 노출 확인 시 사용. Use when security review is needed.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+# Security Auditor - 보안 감사 에이전트
+
+당신은 OWASP Top 10과 보안 모범 사례에 정통한 보안 감사 전문가입니다.
+
+## 검사 항목
+
+### OWASP Top 10
+1. **Injection**: SQL Injection, Command Injection, LDAP Injection
+2. **Broken Authentication**: 약한 비밀번호 정책, 세션 관리 결함
+3. **Sensitive Data Exposure**: 시크릿 하드코딩, 암호화 미적용
+4. **XXE**: XML External Entity 공격
+5. **Broken Access Control**: 권한 우회, IDOR
+6. **Security Misconfiguration**: 디버그 모드, 기본 설정
+7. **XSS**: Reflected, Stored, DOM-based XSS
+8. **Insecure Deserialization**: 안전하지 않은 역직렬화
+9. **Using Components with Known Vulnerabilities**: 취약한 의존성
+10. **Insufficient Logging**: 부적절한 로깅/모니터링
+
+### 코드 스캔 패턴
+- `eval()`, `exec()`, `system()` 사용
+- 하드코딩된 자격증명 (password, secret, token, api_key)
+- SSL 검증 비활성화 (verify_peer => false)
+- 위험한 PHP 함수 (unserialize, extract, $$variable)
+- SQL 직접 조합 (DB::raw, whereRaw + 변수)
+- 인증 미적용 라우트
+- CSRF 보호 미적용
+- .env 파일 노출
+
+### Laravel 특화 보안
+- Mass Assignment 취약점 ($guarded, $fillable)
+- 미들웨어 적용 확인 (auth, throttle, verified)
+- 입력 검증 (FormRequest 사용 여부)
+- 파일 업로드 검증
+- Rate Limiting 적용
+
+## 출력 형식
+
+```yaml
+severity: CRITICAL | HIGH | MEDIUM | LOW | INFO
+finding: 발견된 취약점 설명
+file: 파일 경로:라인번호
+evidence: 문제가 되는 코드
+impact: 악용 시 영향
+remediation: 구체적 수정 방법
+reference: OWASP/CWE 참조
+```
+
+## 원칙
+- 오탐(false positive)을 최소화하되, 놓치지 않는 것이 우선
+- 구체적이고 실행 가능한 수정 방안 제시
+- 심각도를 정확하게 분류

.claude/agents/test-runner.md

@@ -0,0 +1,45 @@
+---
+name: test-runner
+description: 테스트 실행 및 분석 전문가. 코드 작성 후 테스트를 실행하고 실패한 테스트를 분석. Use proactively after writing code to run tests.
+tools: Read, Bash, Grep, Glob
+model: haiku
+---
+
+# Test Runner - 테스트 실행 에이전트
+
+당신은 테스트 실행 및 결과 분석 전문가입니다. 테스트를 실행하고 결과를 간결하게 요약합니다.
+
+## 실행 절차
+
+1. 프로젝트 유형 확인 (Laravel, Node.js, etc.)
+2. 적절한 테스트 명령 실행
+3. 결과 분석 및 요약
+4. 실패한 테스트에 대한 원인 분석
+
+## 테스트 명령어
+
+### Laravel (Docker 환경)
+```bash
+# Unit Tests
+docker exec sam-api-1 php artisan test
+docker exec sam-mng-1 php artisan test
+
+# 특정 테스트
+docker exec sam-api-1 php artisan test --filter=TestClassName
+```
+
+### Node.js
+```bash
+npm test
+npx jest
+npx vitest
+```
+
+## 출력 형식
+
+- **통과**: X개 테스트 통과
+- **실패**: 실패한 테스트 목록 + 에러 메시지
+- **원인 분석**: 각 실패에 대한 간단한 원인 분석
+- **권장 조치**: 수정을 위한 구체적 제안
+
+큰 테스트 출력은 요약하여 핵심만 전달합니다.

.claude/skills/app-comprehensive-test-generator/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: app-comprehensive-test-generator
+description: 사용자 흐름 및 엣지 케이스 테스트 시나리오를 생성하고 실행하여 QA 리포트를 작성합니다. 테스트 생성, QA, 테스트 케이스 작성 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# App Comprehensive Test Generator
+
+애플리케이션의 종합적인 테스트 시나리오를 생성하고 QA 리포트를 작성하는 스킬입니다.
+
+## 기능
+
+### 테스트 유형
+- **유닛 테스트**: 개별 함수/메서드 테스트
+- **통합 테스트**: 모듈 간 상호작용 테스트
+- **E2E 테스트**: 사용자 시나리오 기반 전체 흐름 테스트
+- **엣지 케이스 테스트**: 경계값, 예외 상황 테스트
+
+### 분석 항목
+- 코드 구조 분석
+- 함수 시그니처 추출
+- 의존성 파악
+- 비즈니스 로직 이해
+
+### 생성 테스트 케이스
+- Happy Path (정상 흐름)
+- Error Cases (오류 상황)
+- Boundary Values (경계값)
+- Null/Empty Inputs (빈 입력)
+- Concurrent Operations (동시성)
+- Performance Scenarios (성능)
+
+## 워크플로우
+
+1. 코드베이스 스캔 및 분석
+2. 테스트 대상 식별
+3. 테스트 시나리오 설계
+4. 테스트 코드 생성
+5. 테스트 실행
+6. QA 리포트 작성
+
+## 테스트 템플릿
+
+### Jest (JavaScript/TypeScript)
+```javascript
+describe('ModuleName', () => {
+  describe('functionName', () => {
+    // Happy Path
+    test('should return expected result with valid input', () => {
+      const result = functionName(validInput);
+      expect(result).toEqual(expectedOutput);
+    });
+
+    // Edge Cases
+    test('should handle empty input', () => {
+      expect(() => functionName('')).toThrow();
+    });
+
+    test('should handle null input', () => {
+      expect(() => functionName(null)).toThrow();
+    });
+
+    // Boundary Values
+    test('should handle minimum value', () => {
+      const result = functionName(MIN_VALUE);
+      expect(result).toBeDefined();
+    });
+
+    test('should handle maximum value', () => {
+      const result = functionName(MAX_VALUE);
+      expect(result).toBeDefined();
+    });
+  });
+});
+```
+
+### pytest (Python)
+```python
+import pytest
+from module import function_name
+
+class TestFunctionName:
+    def test_valid_input(self):
+        """Happy path with valid input"""
+        result = function_name(valid_input)
+        assert result == expected_output
+
+    def test_empty_input(self):
+        """Should raise error for empty input"""
+        with pytest.raises(ValueError):
+            function_name('')
+
+    def test_none_input(self):
+        """Should raise error for None input"""
+        with pytest.raises(TypeError):
+            function_name(None)
+
+    @pytest.mark.parametrize("input,expected", [
+        (MIN_VALUE, expected_min),
+        (MAX_VALUE, expected_max),
+    ])
+    def test_boundary_values(self, input, expected):
+        """Boundary value tests"""
+        assert function_name(input) == expected
+```
+
+## QA 리포트 구조
+
+```markdown
+# QA 테스트 리포트
+
+## 요약
+- 총 테스트 케이스: N개
+- 통과: N개 (%)
+- 실패: N개 (%)
+- 스킵: N개 (%)
+
+## 테스트 범위
+| 모듈 | 테스트 수 | 통과 | 실패 | 커버리지 |
+|------|----------|------|------|----------|
+| auth | 15 | 14 | 1 | 85% |
+| api | 23 | 23 | 0 | 92% |
+
+## 실패한 테스트
+### auth.test.js - loginUser
+- **시나리오**: 만료된 토큰으로 로그인
+- **예상**: UnauthorizedError
+- **실제**: TimeoutError
+- **원인 분석**: 토큰 검증 로직 누락
+
+## 권장 조치
+1. auth 모듈 토큰 검증 로직 추가
+2. 타임아웃 처리 개선
+```
+
+## 사용 예시
+
+```
+이 프로젝트의 테스트 케이스를 생성해줘
+user 모듈의 종합 테스트를 만들어줘
+엣지 케이스 테스트를 추가해줘
+```
+
+## 출처
+Original skill from skills.cokac.com

.claude/skills/async-await-keyword-fixer/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: async-await-keyword-fixer
+description: JavaScript/TypeScript 코드에서 누락된 async/await 키워드를 찾아 수정합니다. 비동기 오류, Promise 문제, await 누락 수정 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Async/Await Keyword Fixer
+
+JavaScript 및 TypeScript 코드에서 async/await 관련 문제를 탐지하고 수정하는 스킬입니다.
+
+## 기능
+
+### 탐지 대상
+- **누락된 await**: Promise를 반환하는 함수 호출에 await 누락
+- **불필요한 await**: 동기 함수나 non-Promise에 await 사용
+- **누락된 async**: await를 사용하지만 async 선언 누락
+- **Promise 체이닝 문제**: then/catch와 async/await 혼용
+- **병렬 처리 최적화**: 순차 await를 Promise.all로 개선 가능한 경우
+
+### 분석 패턴
+```javascript
+// ❌ 누락된 await
+async function fetchData() {
+    const response = fetch('/api/data'); // await 누락
+    return response.json();
+}
+
+// ✅ 수정
+async function fetchData() {
+    const response = await fetch('/api/data');
+    return response.json();
+}
+```
+
+```javascript
+// ❌ 누락된 async
+function processData() {
+    const data = await fetchData(); // async 누락
+    return data;
+}
+
+// ✅ 수정
+async function processData() {
+    const data = await fetchData();
+    return data;
+}
+```
+
+```javascript
+// ❌ 비효율적 순차 처리
+async function loadAll() {
+    const a = await fetchA();
+    const b = await fetchB();
+    const c = await fetchC();
+}
+
+// ✅ 병렬 처리로 최적화
+async function loadAll() {
+    const [a, b, c] = await Promise.all([
+        fetchA(),
+        fetchB(),
+        fetchC()
+    ]);
+}
+```
+
+## 분석 프로세스
+
+1. JavaScript/TypeScript 파일 스캔
+2. 함수 및 메서드 식별
+3. async/await 사용 패턴 분석
+4. Promise 반환 함수 추적
+5. 문제점 탐지 및 분류
+6. 최소 침습적 수정 제안
+
+## 리포트 구조
+
+```markdown
+# Async/Await 분석 리포트
+
+## 요약
+- 분석 파일: N개
+- 발견된 이슈: N개
+- 자동 수정 가능: N개
+
+## 발견된 이슈
+
+### 🔴 Critical: 누락된 await
+| 파일 | 라인 | 함수 | 문제 |
+|------|------|------|------|
+| api.js | 23 | fetchUser | await 누락 |
+| db.js | 45 | saveData | await 누락 |
+
+### 🟡 Warning: 누락된 async
+| 파일 | 라인 | 함수 | 문제 |
+|------|------|------|------|
+| utils.js | 12 | processItem | async 누락 |
+
+### 💡 최적화 제안
+| 파일 | 라인 | 제안 |
+|------|------|------|
+| loader.js | 30-35 | Promise.all 사용 권장 |
+
+## 수정 패치
+
+### api.js
+```diff
+- const response = fetch('/api/user');
++ const response = await fetch('/api/user');
+```
+```
+
+## 사용 예시
+
+```
+async/await 문제를 찾아서 수정해줘
+이 파일에서 await 누락된 곳을 찾아줘
+비동기 코드 문제를 분석해줘
+```
+
+## 출처
+Original skill from skills.cokac.com

.claude/skills/build-auditor/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: ln-622-build-auditor
+description: Build health audit worker (L3). Checks compiler/linter errors, deprecation warnings, type errors, failed tests, build configuration issues. Returns findings with severity (Critical/High/Medium/Low), location, effort, and recommendations.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Build Health Auditor (L3 Worker)
+
+Specialized worker auditing build health and code quality tooling.
+
+## Purpose & Scope
+
+- **Worker in ln-620 coordinator pipeline** - invoked by ln-620-codebase-auditor
+- Audit codebase for **build health issues** (Category 2: Critical Priority)
+- Check compiler/linter errors, deprecation warnings, type errors, failed tests, build config
+- Return structured findings to coordinator with severity, location, effort, recommendations
+- Calculate compliance score (X/10) for Build Health category
+
+## Inputs (from Coordinator)
+
+**MANDATORY READ:** Load `shared/references/task_delegation_pattern.md#audit-coordinator--worker-contract` for contextStore structure.
+
+Receives `contextStore` with: `tech_stack` (including build_tool, test_framework), `best_practices`, `principles`, `codebase_root`.
+
+## Workflow
+
+1) **Parse Context:** Extract tech stack, build tools, test framework from contextStore
+2) **Run Build Checks:** Execute compiler, linter, type checker, tests (see Audit Rules below)
+3) **Collect Findings:** Record each violation with severity, location, effort, recommendation
+4) **Calculate Score:** Count violations by severity, calculate compliance score (X/10)
+5) **Return Results:** Return JSON with category, score, findings to coordinator
+
+## Audit Rules (Priority: CRITICAL)
+
+### 1. Compiler/Linter Errors
+**What:** Syntax errors, compilation failures, linter rule violations
+
+**Detection by Stack:**
+
+| Stack | Command | Error Detection |
+|-------|---------|-----------------|
+| Node.js/TypeScript | `npm run build` or `tsc --noEmit` | Check exit code, parse stderr for errors |
+| Python | `python -m py_compile *.py` | Check exit code, parse stderr |
+| Go | `go build ./...` | Check exit code, parse stderr |
+| Rust | `cargo build` | Check exit code, parse stderr |
+| Java | `mvn compile` | Check exit code, parse build log |
+
+**Linters:**
+- ESLint (JS/TS): `npx eslint . --format json` → parse JSON for errors
+- Pylint (Python): `pylint **/*.py --output-format=json`
+- RuboCop (Ruby): `rubocop --format json`
+- golangci-lint (Go): `golangci-lint run --out-format json`
+
+**Severity:**
+- **CRITICAL:** Compilation fails, cannot build project
+- **HIGH:** Linter errors (not warnings)
+- **MEDIUM:** Linter warnings
+- **LOW:** Stylistic linter warnings (formatting)
+
+**Recommendation:** Fix errors before proceeding, configure linter rules, add pre-commit hooks
+
+**Effort:** S-M (fix syntax error vs refactor code structure)
+
+### 2. Deprecation Warnings
+**What:** Usage of deprecated APIs, libraries, or language features
+
+**Detection:**
+- Compiler warnings: `DeprecationWarning`, `@deprecated` in stack trace
+- Dependency warnings: `npm outdated`, `pip list --outdated`
+- Static analysis: Grep for `@deprecated` annotations
+
+**Severity:**
+- **CRITICAL:** Deprecated API removed in next major version (imminent breakage)
+- **HIGH:** Deprecated with migration path available
+- **MEDIUM:** Deprecated but still supported for 1+ year
+- **LOW:** Soft deprecation (no removal timeline)
+
+**Recommendation:** Migrate to recommended API, update dependencies, refactor code
+
+**Effort:** M-L (depends on API complexity and usage frequency)
+
+### 3. Type Errors
+**What:** Type mismatches, missing type annotations, type checker failures
+
+**Detection by Stack:**
+
+| Stack | Tool | Command |
+|-------|------|---------|
+| TypeScript | tsc | `tsc --noEmit --strict` |
+| Python | mypy | `mypy . --strict` |
+| Python | pyright | `pyright --warnings` |
+| Go | go vet | `go vet ./...` |
+| Rust | cargo | `cargo check` (type checks only) |
+
+**Severity:**
+- **CRITICAL:** Type error prevents compilation (`tsc` fails, `cargo check` fails)
+- **HIGH:** Runtime type error likely (implicit `any`, missing type guards)
+- **MEDIUM:** Missing type annotations (code works but untyped)
+- **LOW:** Overly permissive types (`any`, `unknown` without narrowing)
+
+**Recommendation:** Add type annotations, enable strict mode, use type guards
+
+**Effort:** S-M (add types to single file vs refactor entire module)
+
+### 4. Failed or Skipped Tests
+**What:** Test suite failures, skipped tests, missing test coverage
+
+**Detection by Stack:**
+
+| Stack | Framework | Command |
+|-------|-----------|---------|
+| Node.js | Jest | `npm test -- --json --outputFile=test-results.json` |
+| Node.js | Mocha | `mocha --reporter json > test-results.json` |
+| Python | Pytest | `pytest --json-report --json-report-file=test-results.json` |
+| Go | go test | `go test ./... -json` |
+| Rust | cargo test | `cargo test --no-fail-fast` |
+
+**Severity:**
+- **CRITICAL:** Test failures in CI/production code
+- **HIGH:** Skipped tests for critical features (payment, auth)
+- **MEDIUM:** Skipped tests for non-critical features
+- **LOW:** Skipped tests with "TODO" comment (acknowledged debt)
+
+**Recommendation:** Fix failing tests, remove skip markers, add missing tests
+
+**Effort:** S-M (update test assertion vs redesign test strategy)
+
+### 5. Build Configuration Issues
+**What:** Misconfigured build tools, missing scripts, incorrect paths
+
+**Detection:**
+- Missing build scripts in `package.json`, `Makefile`, `build.gradle`
+- Incorrect paths in `tsconfig.json`, `webpack.config.js`, `Cargo.toml`
+- Missing environment-specific configs (dev, staging, prod)
+- Unused or conflicting build dependencies
+
+**Severity:**
+- **CRITICAL:** Build fails due to misconfiguration
+- **HIGH:** Build succeeds but outputs incorrect artifacts (wrong target, missing assets)
+- **MEDIUM:** Suboptimal config (no minification, missing source maps)
+- **LOW:** Unused config options
+
+**Recommendation:** Fix config paths, add missing build scripts, optimize build settings
+
+**Effort:** S-M (update config file vs redesign build pipeline)
+
+## Scoring Algorithm
+
+See `shared/references/audit_scoring.md` for unified formula and score interpretation.
+
+## Output Format
+
+**MANDATORY READ:** Load `shared/references/audit_output_schema.md` for JSON structure.
+
+Return JSON with `category: "Build Health"` and checks: compilation_errors, linter_warnings, type_errors, test_failures, build_config.
+
+## Critical Rules
+
+- **Do not auto-fix:** Report violations only; coordinator creates task for user to fix
+- **Tech stack aware:** Use contextStore to run appropriate build commands (npm vs cargo vs gradle)
+- **Exit code checking:** Always check exit code (0 = success, non-zero = failure)
+- **Timeout handling:** Set timeout for build/test commands (default 5 minutes)
+- **Environment aware:** Run in CI mode if detected (no interactive prompts)
+
+## Definition of Done
+
+- contextStore parsed successfully
+- All 5 build checks completed (compiler, linter, type checker, tests, config)
+- Findings collected with severity, location, effort, recommendation
+- Score calculated using penalty algorithm
+- JSON result returned to coordinator
+
+## Reference Files
+
+- **Audit scoring formula:** `shared/references/audit_scoring.md`
+- **Audit output schema:** `shared/references/audit_output_schema.md`
+- Build audit rules: [references/build_rules.md](references/build_rules.md)
+
+---
+**Version:** 3.0.0
+**Last Updated:** 2025-12-23

.claude/skills/code-bug-finder/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: code-bug-finder
+description: 다양한 프로그래밍 언어에서 버그를 자동으로 탐지하고 보고서를 생성합니다. 버그 찾기, 코드 검사, 결함 분석 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Code Bug Finder
+
+코드에서 잠재적 버그와 문제점을 자동으로 탐지하는 스킬입니다.
+
+## 기능
+
+### 탐지 대상
+- **논리 오류**: 조건문 오류, 무한 루프, off-by-one 에러
+- **널 참조**: null/undefined 체크 누락
+- **리소스 누수**: 파일/연결 미해제, 메모리 누수
+- **타입 오류**: 암시적 형변환, 타입 불일치
+- **보안 취약점**: SQL 인젝션, XSS, 하드코딩된 자격증명
+- **동시성 문제**: 레이스 컨디션, 데드락 가능성
+- **예외 처리**: 빈 catch 블록, 광범위한 예외 포착
+
+### 지원 언어
+- JavaScript/TypeScript
+- Python
+- Java/Kotlin
+- PHP
+- Go
+- C/C++
+
+### 출력 형식
+- 심각도별 분류 (Critical, High, Medium, Low)
+- 파일 위치 및 라인 번호
+- 문제 설명 및 수정 제안
+- HTML 또는 마크다운 리포트
+
+## 분석 프로세스
+
+1. 코드베이스 스캔 및 파일 수집
+2. 언어별 패턴 매칭 적용
+3. 정적 분석 수행
+4. 발견된 이슈 분류 및 우선순위 지정
+5. 수정 제안 생성
+6. 종합 리포트 작성
+
+## 리포트 구조
+
+```markdown
+# 버그 분석 리포트
+
+## 요약
+- 총 검사 파일: N개
+- 발견된 이슈: N개
+- Critical: N개 | High: N개 | Medium: N개 | Low: N개
+
+## Critical Issues
+### [파일명:라인] 이슈 제목
+- **설명**: 문제에 대한 상세 설명
+- **영향**: 이 버그가 미치는 영향
+- **수정 제안**: 권장 수정 방법
+- **코드**:
+  ```
+  // 문제 코드
+  ```
+
+## High Priority Issues
+...
+
+## Medium Priority Issues
+...
+
+## Low Priority Issues
+...
+
+## 권장 사항
+- 즉시 조치 필요 항목
+- 점진적 개선 항목
+```
+
+## 사용 예시
+
+```
+이 프로젝트에서 버그를 찾아줘
+src 폴더의 코드를 검사하고 문제점을 알려줘
+보안 취약점이 있는지 분석해줘
+```
+
+## 출처
+Original skill from skills.cokac.com

.claude/skills/code-commenter/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: code-commenter
+description: 프로그램 소스 코드에 이해하기 쉬운 주석을 추가합니다. 코드 주석 추가, 코드 설명, 문서화 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Code Commenter
+
+소스 코드에 초보자도 이해할 수 있는 설명적인 주석을 추가하는 스킬입니다.
+
+## 기능
+
+### 주석 유형
+- **파일 헤더**: 파일 목적 및 개요
+- **함수/메서드 문서**: 입력, 출력, 동작 설명
+- **인라인 주석**: 복잡한 로직 설명
+- **TODO/FIXME**: 개선 필요 영역 표시
+- **섹션 구분**: 코드 영역 구분
+
+### 지원 언어
+- JavaScript/TypeScript (JSDoc)
+- Python (docstring)
+- Java/Kotlin (JavaDoc)
+- PHP (PHPDoc)
+- Go
+- C/C++
+- 기타 언어
+
+### 주석 스타일
+
+#### JavaScript/TypeScript (JSDoc)
+```javascript
+/**
+ * 사용자 인증을 처리하고 JWT 토큰을 반환합니다.
+ *
+ * @param {string} email - 사용자 이메일 주소
+ * @param {string} password - 사용자 비밀번호 (평문)
+ * @returns {Promise<{token: string, user: Object}>} 인증 토큰과 사용자 정보
+ * @throws {AuthenticationError} 이메일 또는 비밀번호가 잘못된 경우
+ *
+ * @example
+ * const result = await authenticateUser('user@example.com', 'password123');
+ * console.log(result.token); // 'eyJhbGc...'
+ */
+async function authenticateUser(email, password) {
+  // 데이터베이스에서 사용자 조회
+  const user = await User.findByEmail(email);
+
+  // 비밀번호 해시 비교로 인증 검증
+  const isValid = await bcrypt.compare(password, user.passwordHash);
+
+  if (!isValid) {
+    throw new AuthenticationError('Invalid credentials');
+  }
+
+  // JWT 토큰 생성 (24시간 유효)
+  const token = jwt.sign({ userId: user.id }, SECRET_KEY, { expiresIn: '24h' });
+
+  return { token, user };
+}
+```
+
+#### Python (docstring)
+```python
+def calculate_tax(income: float, deductions: list[float] = None) -> float:
+    """
+    소득에 대한 세금을 계산합니다.
+
+    누진세율을 적용하여 과세표준에 따른 세금을 계산합니다.
+    공제 항목이 있으면 소득에서 차감한 후 계산합니다.
+
+    Args:
+        income: 연간 총 소득 (원)
+        deductions: 공제 항목 목록 (선택사항)
+
+    Returns:
+        계산된 세금 (원)
+
+    Raises:
+        ValueError: 소득이 음수인 경우
+
+    Example:
+        >>> calculate_tax(50000000, [5000000, 2000000])
+        4320000.0
+    """
+    # 입력값 검증
+    if income < 0:
+        raise ValueError("소득은 음수가 될 수 없습니다")
+
+    # 공제 적용
+    taxable_income = income - sum(deductions or [])
+
+    # 누진세율 적용 (간소화된 예시)
+    if taxable_income <= 12000000:
+        return taxable_income * 0.06
+    elif taxable_income <= 46000000:
+        return 720000 + (taxable_income - 12000000) * 0.15
+    else:
+        return 5820000 + (taxable_income - 46000000) * 0.24
+```
+
+#### Java (JavaDoc)
+```java
+/**
+ * 주문 처리 서비스
+ *
+ * <p>고객의 주문을 생성, 수정, 취소하는 기능을 제공합니다.
+ * 재고 확인 및 결제 처리와 연동됩니다.</p>
+ *
+ * @author 개발팀
+ * @version 1.0
+ * @since 2024-01-01
+ */
+public class OrderService {
+
+    /**
+     * 새로운 주문을 생성합니다.
+     *
+     * <p>장바구니의 상품들을 주문으로 변환하고,
+     * 재고를 확인한 후 결제를 진행합니다.</p>
+     *
+     * @param customerId 고객 ID
+     * @param cartItems 장바구니 상품 목록
+     * @param paymentMethod 결제 수단
+     * @return 생성된 주문 객체
+     * @throws InsufficientStockException 재고가 부족한 경우
+     * @throws PaymentFailedException 결제가 실패한 경우
+     */
+    public Order createOrder(Long customerId, List<CartItem> cartItems, PaymentMethod paymentMethod) {
+        // 재고 확인
+        validateStock(cartItems);
+
+        // 주문 생성
+        Order order = new Order(customerId, cartItems);
+
+        // 결제 처리
+        processPayment(order, paymentMethod);
+
+        return orderRepository.save(order);
+    }
+}
+```
+
+## 주석 가이드라인
+
+### DO (권장)
+- 복잡한 비즈니스 로직 설명
+- 알고리즘의 의도 설명
+- 비직관적인 결정의 이유 설명
+- 외부 의존성 및 부작용 문서화
+- 매개변수 제약조건 명시
+
+### DON'T (피해야 할 것)
+- 코드를 그대로 반복하는 주석
+- 너무 명백한 내용 설명
+- 오래된/부정확한 주석 방치
+- 주석으로 코드 숨기기
+- 과도한 주석으로 가독성 저해
+
+## 사용 예시
+
+```
+이 코드에 설명 주석을 추가해줘
+함수들에 JSDoc 주석을 작성해줘
+초보자도 이해할 수 있게 코드를 문서화해줘
+```
+
+## 출처
+Original skill from skills.cokac.com

.claude/skills/code-flow-web-doc-generator/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: code-flow-web-doc-generator
+description: 소스 코드를 분석하여 호출 흐름과 데이터 흐름 다이어그램이 포함된 자체 완결형 HTML 문서를 생성합니다. 코드 흐름 문서화, 시퀀스 다이어그램 생성, 코드 이해를 위한 시각화 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Code Flow Web Document Generator
+
+소스 코드를 분석하여 시각적 다이어그램과 설명이 포함된 자체 완결형 HTML 문서를 생성하는 스킬입니다.
+
+## 주요 기능
+
+프로그램 동작과 구조를 이해하는 데 도움이 되는 호출 흐름 및 데이터 흐름 다이어그램과 간결한 노드 수준 설명이 포함된 웹 문서를 생성합니다.
+
+## 워크플로우
+
+1. 코드 입력 수신 (단일 파일, 다중 파일, 저장소, 또는 코드 스니펫)
+2. 함수, 클래스, import, 호출 관계 추출
+3. 컴포넌트 간 데이터 흐름 식별
+4. Mermaid 형식으로 모듈 및 시퀀스 다이어그램 생성
+5. 요약, 다이어그램, 상세 노드 설명 섹션이 포함된 구조화된 HTML 생성
+
+## 기능 상세
+
+### 다이어그램 유형
+- 고수준 모듈 다이어그램
+- 호출 시퀀스 흐름
+
+### 출력 형식
+- 인라인 CSS 및 스크립트가 포함된 단일 자체 완결형 HTML 파일
+
+### 코드 분석
+- 함수 역할, 입력, 출력, 부작용 추출
+
+### 문서화
+- 코드 발췌 (3-12줄)
+- 핫스팟 분석
+- 재생성 지침 포함
+
+## 사용 사례
+
+- 단일 파일 스크립트 분석
+- 다중 모듈 웹 서비스 문서화
+- 이벤트 기반 코드 설명
+- 코드 리뷰 준비 및 온보딩
+
+## HTML 출력 템플릿
+
+```html
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+    <meta charset="UTF-8">
+    <title>코드 흐름 문서</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+    <style>
+        * { font-family: 'Noto Sans KR', sans-serif; }
+        .mermaid { background: #f8fafc; padding: 1rem; border-radius: 0.5rem; }
+    </style>
+</head>
+<body class="bg-gray-100 min-h-screen">
+    <header class="bg-white shadow-sm sticky top-0 z-50">
+        <!-- 네비게이션 -->
+    </header>
+
+    <main class="max-w-6xl mx-auto px-4 py-8">
+        <!-- 1. 프로젝트 요약 -->
+        <section id="summary">
+            <h2>프로젝트 요약</h2>
+            <!-- 목적, 주요 기능, 기술 스택 -->
+        </section>
+
+        <!-- 2. 모듈 다이어그램 -->
+        <section id="module-diagram">
+            <h2>모듈 구조</h2>
+            <div class="mermaid">
+                graph TD
+                    A[Entry Point] --> B[Module A]
+                    A --> C[Module B]
+            </div>
+        </section>
+
+        <!-- 3. 호출 흐름 -->
+        <section id="call-flow">
+            <h2>호출 흐름</h2>
+            <div class="mermaid">
+                sequenceDiagram
+                    participant User
+                    participant API
+                    participant DB
+            </div>
+        </section>
+
+        <!-- 4. 함수별 상세 설명 -->
+        <section id="function-details">
+            <h2>함수 상세</h2>
+            <!-- 각 함수의 역할, 입력, 출력, 코드 발췌 -->
+        </section>
+
+        <!-- 5. 데이터 흐름 -->
+        <section id="data-flow">
+            <h2>데이터 흐름</h2>
+            <!-- 데이터가 어떻게 변환되고 전달되는지 -->
+        </section>
+    </main>
+
+    <script>
+        mermaid.initialize({ startOnLoad: true, theme: 'default' });
+    </script>
+</body>
+</html>
+```
+
+## 사용 예시
+
+```
+이 파일의 코드 흐름을 다이어그램으로 문서화해줘
+src 폴더의 호출 관계를 시퀀스 다이어그램으로 만들어줘
+이 함수들의 데이터 흐름을 HTML 문서로 생성해줘
+```
+
+## 출처
+Original skill from skills.cokac.com

.claude/skills/code-flow-web-report/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: code-flow-web-report
+description: 웹 애플리케이션의 런타임 흐름을 시각화하는 인터랙티브 리포트를 생성합니다. 라우트, 컨트롤러, 서비스 흐름 분석 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Code Flow Web Report
+
+웹 애플리케이션의 요청 처리 흐름을 시각화하는 인터랙티브 HTML 리포트를 생성하는 스킬입니다.
+
+## 기능
+
+### 분석 대상
+- **라우트 (Routes)**: URL 엔드포인트 매핑
+- **컨트롤러 (Controllers)**: 요청 처리 로직
+- **서비스 (Services)**: 비즈니스 로직
+- **미들웨어 (Middleware)**: 전처리/후처리
+- **모델/리포지토리**: 데이터 접근
+
+### 시각화 요소
+- 요청 흐름 시퀀스 다이어그램
+- 레이어 간 의존성 그래프
+- 컴포넌트 상호작용 맵
+- API 엔드포인트 목록
+
+### 지원 프레임워크
+- Express.js / Koa.js
+- NestJS
+- Django / Flask
+- Laravel / Symfony
+- Spring Boot
+
+## 분석 프로세스
+
+1. 라우트 정의 파일 스캔
+2. 컨트롤러/핸들러 매핑 추출
+3. 서비스 의존성 분석
+4. 미들웨어 체인 파악
+5. 데이터 흐름 추적
+6. 인터랙티브 HTML 생성
+
+## HTML 템플릿
+
+```html
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+    <meta charset="UTF-8">
+    <title>코드 흐름 리포트</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@300;400;500;700&display=swap" rel="stylesheet">
+    <style>
+        * { font-family: 'Noto Sans KR', sans-serif; }
+        .mermaid { background: #f8fafc; padding: 1rem; border-radius: 0.5rem; }
+        .endpoint-card:hover { transform: translateY(-2px); box-shadow: 0 4px 12px rgba(0,0,0,0.1); }
+    </style>
+</head>
+<body class="bg-gray-100 min-h-screen">
+    <header class="bg-white shadow-sm sticky top-0 z-50">
+        <div class="max-w-6xl mx-auto px-4 py-4">
+            <h1 class="text-xl font-bold text-slate-800">🔄 코드 흐름 리포트</h1>
+        </div>
+    </header>
+
+    <main class="max-w-6xl mx-auto px-4 py-8">
+        <!-- 요약 -->
+        <section class="bg-white rounded-xl shadow-sm p-6 mb-6">
+            <h2 class="text-lg font-bold text-slate-700 mb-4">📊 요약</h2>
+            <div class="grid grid-cols-2 md:grid-cols-4 gap-4">
+                <div class="bg-teal-50 rounded-lg p-4 text-center">
+                    <div class="text-2xl font-bold text-teal-600">24</div>
+                    <div class="text-sm text-slate-600">API 엔드포인트</div>
+                </div>
+                <div class="bg-blue-50 rounded-lg p-4 text-center">
+                    <div class="text-2xl font-bold text-blue-600">8</div>
+                    <div class="text-sm text-slate-600">컨트롤러</div>
+                </div>
+                <div class="bg-purple-50 rounded-lg p-4 text-center">
+                    <div class="text-2xl font-bold text-purple-600">12</div>
+                    <div class="text-sm text-slate-600">서비스</div>
+                </div>
+                <div class="bg-amber-50 rounded-lg p-4 text-center">
+                    <div class="text-2xl font-bold text-amber-600">5</div>
+                    <div class="text-sm text-slate-600">미들웨어</div>
+                </div>
+            </div>
+        </section>
+
+        <!-- 아키텍처 다이어그램 -->
+        <section class="bg-white rounded-xl shadow-sm p-6 mb-6">
+            <h2 class="text-lg font-bold text-slate-700 mb-4">🏗️ 아키텍처</h2>
+            <div class="mermaid">
+                graph TD
+                    Client[클라이언트] --> Router[라우터]
+                    Router --> MW[미들웨어]
+                    MW --> Controller[컨트롤러]
+                    Controller --> Service[서비스]
+                    Service --> Repository[리포지토리]
+                    Repository --> DB[(데이터베이스)]
+            </div>
+        </section>
+
+        <!-- 요청 흐름 -->
+        <section class="bg-white rounded-xl shadow-sm p-6 mb-6">
+            <h2 class="text-lg font-bold text-slate-700 mb-4">🔄 요청 흐름 예시</h2>
+            <div class="mermaid">
+                sequenceDiagram
+                    participant C as Client
+                    participant R as Router
+                    participant M as Middleware
+                    participant CT as Controller
+                    participant S as Service
+                    participant DB as Database
+
+                    C->>R: POST /api/users
+                    R->>M: authMiddleware()
+                    M->>CT: UserController.create()
+                    CT->>S: UserService.createUser()
+                    S->>DB: INSERT INTO users
+                    DB-->>S: user record
+                    S-->>CT: User object
+                    CT-->>C: 201 Created
+            </div>
+        </section>
+
+        <!-- API 엔드포인트 목록 -->
+        <section class="bg-white rounded-xl shadow-sm p-6 mb-6">
+            <h2 class="text-lg font-bold text-slate-700 mb-4">📡 API 엔드포인트</h2>
+            <div class="space-y-3">
+                <div class="endpoint-card border rounded-lg p-4 transition-all cursor-pointer">
+                    <div class="flex items-center gap-3">
+                        <span class="px-2 py-1 bg-green-100 text-green-700 text-xs font-bold rounded">GET</span>
+                        <code class="text-slate-700">/api/users</code>
+                        <span class="text-slate-400 text-sm ml-auto">UserController.list</span>
+                    </div>
+                </div>
+                <div class="endpoint-card border rounded-lg p-4 transition-all cursor-pointer">
+                    <div class="flex items-center gap-3">
+                        <span class="px-2 py-1 bg-blue-100 text-blue-700 text-xs font-bold rounded">POST</span>
+                        <code class="text-slate-700">/api/users</code>
+                        <span class="text-slate-400 text-sm ml-auto">UserController.create</span>
+                    </div>
+                </div>
+                <div class="endpoint-card border rounded-lg p-4 transition-all cursor-pointer">
+                    <div class="flex items-center gap-3">
+                        <span class="px-2 py-1 bg-amber-100 text-amber-700 text-xs font-bold rounded">PUT</span>
+                        <code class="text-slate-700">/api/users/:id</code>
+                        <span class="text-slate-400 text-sm ml-auto">UserController.update</span>
+                    </div>
+                </div>
+                <div class="endpoint-card border rounded-lg p-4 transition-all cursor-pointer">
+                    <div class="flex items-center gap-3">
+                        <span class="px-2 py-1 bg-red-100 text-red-700 text-xs font-bold rounded">DELETE</span>
+                        <code class="text-slate-700">/api/users/:id</code>
+                        <span class="text-slate-400 text-sm ml-auto">UserController.delete</span>
+                    </div>
+                </div>
+            </div>
+        </section>
+    </main>
+
+    <script>
+        mermaid.initialize({ startOnLoad: true, theme: 'default' });
+    </script>
+</body>
+</html>
+```
+
+## 사용 예시
+
+```
+이 웹앱의 코드 흐름을 분석해서 리포트로 만들어줘
+API 요청이 어떻게 처리되는지 시각화해줘
+라우트에서 DB까지의 흐름을 다이어그램으로 보여줘
+```
+
+## 출처
+Original skill from skills.cokac.com

.claude/skills/code-principles-auditor/SKILL.md

@@ -0,0 +1,422 @@
+---
+name: ln-623-code-principles-auditor
+description: Code principles audit worker (L3). Checks DRY (7 types), KISS/YAGNI, TODOs, error handling, DI patterns. Returns findings with severity, location, effort, recommendations.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Code Principles Auditor (L3 Worker)
+
+Specialized worker auditing code principles (DRY, KISS, YAGNI) and design patterns.
+
+## Purpose & Scope
+
+- **Worker in ln-620 coordinator pipeline** - invoked by ln-620-codebase-auditor
+- Audit **code principles** (DRY/KISS/YAGNI, error handling, DI)
+- Check DRY/KISS/YAGNI violations, TODO/FIXME, workarounds, error handling
+- Return structured findings with severity, location, effort, recommendations
+- Calculate compliance score (X/10) for Code Principles category
+
+## Inputs (from Coordinator)
+
+**MANDATORY READ:** Load `shared/references/task_delegation_pattern.md#audit-coordinator--worker-contract` for contextStore structure.
+
+Receives `contextStore` with: `tech_stack`, `best_practices`, `principles`, `codebase_root`.
+
+**Domain-aware:** Supports `domain_mode` + `current_domain` (see `audit_output_schema.md#domain-aware-worker-output`).
+
+## Workflow
+
+1) **Parse context** — extract fields, determine `scan_path` (domain-aware if specified)
+2) **Scan codebase for violations**
+   - All Grep/Glob patterns use `scan_path` (not codebase_root)
+   - Example: `Grep(pattern="TODO", path=scan_path)`
+
+3) **Collect findings with severity, location, effort, recommendation**
+   - Tag each finding with `domain: domain_name` (if domain-aware)
+
+4) **Calculate score using penalty algorithm**
+
+5) **Return JSON result to coordinator**
+   - Include `domain` and `scan_path` fields (if domain-aware)
+
+## Audit Rules (Priority: HIGH)
+
+### 1. DRY Violations (Don't Repeat Yourself)
+**What:** Duplicated logic, constants, or code blocks across files
+
+**Detection Categories:**
+
+#### 1.1. Identical Code Duplication
+- Search for identical functions (use AST comparison or text similarity)
+- Find repeated constants: same value defined in multiple files
+- Detect copy-pasted code blocks (>10 lines identical)
+
+**Severity:**
+- **HIGH:** Critical business logic duplicated (payment, auth)
+- **MEDIUM:** Utility functions duplicated
+- **LOW:** Simple constants duplicated (<5 occurrences)
+
+#### 1.2. Duplicated Validation Logic
+**What:** Same validation patterns repeated across validators/controllers
+
+**Detection:**
+- Email validation: `/@.*\./` regex patterns in multiple files
+- Password validation: `/.{8,}/`, strength checks repeated
+- Phone validation: phone number regex duplicated
+- Common patterns: `isValid*`, `validate*`, `check*` functions with similar logic
+
+**Severity:**
+- **HIGH:** Auth/payment validation duplicated (inconsistency risk)
+- **MEDIUM:** User input validation duplicated (3+ occurrences)
+- **LOW:** Simple format checks duplicated (<3 occurrences)
+
+**Recommendation:** Extract to shared validators module (`validators/common.ts`)
+
+**Effort:** M (extract validators, update imports)
+
+#### 1.3. Repeated Error Messages
+**What:** Hardcoded error messages instead of centralized error catalog
+
+**Detection:**
+- Grep for hardcoded strings in `throw new Error("...")`, `res.status(400).json({ error: "..." })`
+- Find repeated messages: "User not found", "Invalid credentials", "Unauthorized access"
+- Check for missing error constants file: `errors.ts`, `error-messages.ts`, `constants/errors.ts`
+
+**Severity:**
+- **MEDIUM:** Critical error messages hardcoded (auth, payment) - inconsistency risk
+- **MEDIUM:** No centralized error messages file
+- **LOW:** Same error message in <3 places
+
+**Recommendation:**
+- Create central error messages file (`constants/error-messages.ts`)
+- Define error catalog: `const ERRORS = { USER_NOT_FOUND: "User not found", ... }`
+- Replace hardcoded strings with constants: `throw new Error(ERRORS.USER_NOT_FOUND)`
+
+**Effort:** M (create error catalog, replace hardcoded strings)
+
+#### 1.4. Similar Code Patterns (>80% Similarity)
+**What:** Code with similar logic but different variable names/structure
+
+**Detection:**
+- Use fuzzy matching/similarity algorithms (Levenshtein distance, Jaccard similarity)
+- Compare function bodies ignoring variable names
+- Threshold: >80% similarity = potential duplication
+
+**Example:**
+```typescript
+// File 1
+function processUser(user) { return user.name.toUpperCase(); }
+
+// File 2
+function formatUserName(u) { return u.name.toUpperCase(); }
+// ✅ Same logic, different names - DETECTED
+```
+
+**Severity:**
+- **MEDIUM:** Similar business logic (>80% similarity) in critical paths
+- **LOW:** Similar utility functions (<3 occurrences)
+
+**Recommendation:** Extract common logic, create shared helper function
+
+**Effort:** M (refactor to shared module)
+
+#### 1.5. Duplicated SQL Queries
+**What:** Same SQL queries/ORM calls in different controllers/services
+
+**Detection:**
+- Find repeated raw SQL strings: `SELECT * FROM users WHERE id = ?`
+- ORM duplicates: `User.findOne({ where: { email } })` in multiple files
+- Grep for common patterns: `SELECT`, `INSERT`, `UPDATE`, `DELETE` with similar structure
+
+**Severity:**
+- **HIGH:** Critical queries duplicated (payment, auth)
+- **MEDIUM:** Common queries duplicated (3+ occurrences)
+- **LOW:** Simple queries duplicated (<3 occurrences)
+
+**Recommendation:** Extract to Repository layer, create query methods
+
+**Effort:** M (create repository methods, update callers)
+
+#### 1.6. Copy-Pasted Tests
+**What:** Test files with identical structure (arrange-act-assert duplicated)
+
+**Detection:**
+- Find tests with >80% similar setup/teardown
+- Repeated test data: same fixtures defined in multiple test files
+- Pattern: `beforeEach`, `afterEach` with identical code
+
+**Severity:**
+- **MEDIUM:** Test setup duplicated in 5+ files
+- **LOW:** Similar test utilities duplicated (<5 files)
+
+**Recommendation:** Extract to test helpers (`tests/helpers/*`), use shared fixtures
+
+**Effort:** M (create test utilities, refactor tests)
+
+#### 1.7. Repeated API Response Structures
+**What:** Duplicated response objects instead of shared DTOs
+
+**Detection:**
+- Find repeated object structures in API responses:
+  ```typescript
+  return { id: user.id, name: user.name, email: user.email }
+  ```
+- Check for missing DTOs folder: `dtos/`, `responses/`, `models/`
+- Grep for common patterns: `return { ... }` in controllers
+
+**Severity:**
+- **MEDIUM:** Response structures duplicated in 5+ endpoints (inconsistency risk)
+- **LOW:** Simple response objects duplicated (<5 endpoints)
+
+**Recommendation:** Create DTOs/Response classes, use serializers
+
+**Effort:** M (create DTOs, update endpoints)
+
+---
+
+**Overall Recommendation for DRY:**
+Extract to shared module, create utility function, centralize constants/messages/validators/DTOs
+
+**Overall Effort:** M (refactor + update imports, typically 1-4 hours per duplication type)
+
+### 2. KISS Violations (Keep It Simple, Stupid)
+**What:** Over-engineered abstractions, unnecessary complexity
+
+**Detection:**
+- Abstract classes with single implementation
+- Factory patterns for 2 objects
+- Deep inheritance (>3 levels)
+- Generic types with excessive constraints
+
+**Severity:**
+- **HIGH:** Abstraction prevents understanding core logic
+- **MEDIUM:** Unnecessary pattern (factory for 2 types)
+- **LOW:** Over-generic types (acceptable tradeoff)
+
+**Recommendation:** Remove abstraction, inline implementation, flatten hierarchy
+
+**Effort:** L (requires careful refactoring)
+
+### 3. YAGNI Violations (You Aren't Gonna Need It)
+**What:** Unused extensibility, dead feature flags, premature optimization
+
+**Detection:**
+- Feature flags that are always true/false
+- Abstract methods never overridden
+- Config options never used
+- Interfaces with single implementation (no plans for more)
+
+**Severity:**
+- **MEDIUM:** Unused extensibility points adding complexity
+- **LOW:** Dead feature flags (cleanup needed)
+
+**Recommendation:** Remove unused code, simplify interfaces
+
+**Effort:** M (verify no future use, then delete)
+
+### 4. TODO/FIXME/HACK Comments
+**What:** Unfinished work, temporary solutions
+
+**Detection:**
+- Grep for `TODO`, `FIXME`, `HACK`, `XXX`, `OPTIMIZE`
+- Check age (git blame) - old TODOs are higher severity
+
+**Severity:**
+- **HIGH:** TODO in critical path (auth, payment) >6 months old
+- **MEDIUM:** FIXME/HACK with explanation
+- **LOW:** Recent TODO (<1 month) with plan
+
+**Recommendation:** Complete TODO, remove HACK, refactor workaround
+
+**Effort:** Varies (S for simple TODO, L for architectural HACK)
+
+### 5. Missing Error Handling
+**What:** Critical paths without try-catch, error propagation
+
+**Detection:**
+- Find async functions without error handling
+- Check API routes without error middleware
+- Verify database calls have error handling
+
+**Severity:**
+- **CRITICAL:** Payment/auth without error handling
+- **HIGH:** User-facing operations without error handling
+- **MEDIUM:** Internal operations without error handling
+
+**Recommendation:** Add try-catch, implement error middleware, propagate errors properly
+
+**Effort:** M (add error handling logic)
+
+### 6. Centralized Error Handling
+**What:** Errors handled inconsistently across different contexts (web requests, cron jobs, background tasks)
+
+**Detection:**
+- Search for centralized error handler class/module: `ErrorHandler`, `errorHandler`, `error-handler.ts/js/py`
+- Check if error middleware delegates to handler: `errorHandler.handleError(err)` or similar
+- Verify all async routes use promises or async/await (Express 5+ auto-catches rejections)
+- Check for error transformation (sanitize stack traces for users in production)
+- **Anti-pattern check:** Look for `process.on("uncaughtException")` usage (BAD PRACTICE per Express docs)
+
+**Severity:**
+- **HIGH:** No centralized error handler (errors handled inconsistently in multiple places)
+- **HIGH:** Using `uncaughtException` listener instead of proper error propagation (Express anti-pattern)
+- **MEDIUM:** Error middleware handles errors directly (doesn't delegate to central handler)
+- **MEDIUM:** Async routes without proper error handling (not using promises/async-await)
+- **LOW:** Stack traces exposed in production responses (security/UX issue)
+
+**Recommendation:**
+- Create single ErrorHandler class/module for ALL error contexts
+- Middleware should only catch and forward to ErrorHandler (delegate pattern)
+- Use async/await for async routes (framework auto-forwards errors)
+- Transform errors for users: hide sensitive details (stack traces, internal paths) in production
+- **DO NOT use uncaughtException listeners** - use process managers (PM2, systemd) for restart instead
+- For unhandled rejections: log and restart process (use supervisor, not inline handler)
+
+**Effort:** M-L (create error handler, refactor existing middleware)
+
+### 7. Dependency Injection / Centralized Init
+**What:** Direct imports/instantiation instead of dependency injection, scattered initialization
+
+**Detection:**
+- Check for DI container usage:
+  - Node.js: `inversify`, `awilix`, `tsyringe`, `typedi` packages
+  - Python: `dependency_injector`, `injector` packages
+  - Java: Spring `@Autowired`, `@Inject` annotations
+  - .NET: Built-in DI in ASP.NET Core, `IServiceCollection`
+- Grep for direct instantiations in business logic: `new SomeService()`, `new SomeRepository()`
+- Check for centralized Init/Bootstrap module: `bootstrap.ts`, `init.py`, `Startup.cs`, `app.module.ts`
+- Verify controllers/services receive dependencies via constructor/parameters, not direct imports
+
+**Severity:**
+- **MEDIUM:** No DI container (hard to test, tight coupling, difficult to swap implementations)
+- **MEDIUM:** Direct instantiation in business logic (`new Service()` in controllers/services)
+- **LOW:** Mixed DI and direct imports (inconsistent pattern)
+
+**Recommendation:**
+- Use DI container for dependency management (Inversify, Awilix, Spring, built-in .NET DI)
+- Centralize initialization in Init/Bootstrap module
+- Inject dependencies via constructor/parameters (dependency injection pattern)
+- Never use direct instantiation for business logic classes (only for DTOs, value objects)
+
+**Effort:** L (refactor to DI pattern, add container, update all instantiations)
+
+### 8. Missing Best Practices Guide
+**What:** No architecture/design best practices documentation for developers
+
+**Detection:**
+- Check for architecture guide files:
+  - `docs/architecture.md`, `docs/best-practices.md`, `docs/design-patterns.md`
+  - `ARCHITECTURE.md`, `CONTRIBUTING.md` (architecture section)
+- Verify content includes: layering rules, error handling patterns, DI usage, coding conventions
+
+**Severity:**
+- **LOW:** No architecture guide (harder for new developers to understand patterns and conventions)
+
+**Recommendation:**
+- Create `docs/architecture.md` with project-specific patterns:
+  - Document layering: Controller→Service→Repository→DB
+  - Error handling: centralized ErrorHandler pattern
+  - Dependency Injection: how to add new services/repositories
+  - Coding conventions: naming, file organization, imports
+- Include examples from existing codebase
+- Keep framework-agnostic (principles, not specific implementations)
+
+**Effort:** S (create markdown file, ~1-2 hours documentation)
+
+## Scoring Algorithm
+
+See `shared/references/audit_scoring.md` for unified formula and score interpretation.
+
+## Output Format
+
+Return JSON to coordinator:
+
+**Global mode output:**
+```json
+{
+  "category": "Architecture & Design",
+  "score": 6,
+  "total_issues": 12,
+  "critical": 2,
+  "high": 4,
+  "medium": 4,
+  "low": 2,
+  "checks": [
+    {"id": "dry_violations", "name": "DRY Violations", "status": "failed", "details": "4 duplications found"},
+    {"id": "kiss_violations", "name": "KISS Violations", "status": "warning", "details": "1 over-engineered abstraction"},
+    {"id": "yagni_violations", "name": "YAGNI Violations", "status": "passed", "details": "No unused code"},
+    {"id": "solid_violations", "name": "SOLID Violations", "status": "failed", "details": "2 SRP violations"}
+  ],
+  "findings": [...]
+}
+```
+
+**Domain-aware mode output (NEW):**
+```json
+{
+  "category": "Architecture & Design",
+  "score": 6,
+  "domain": "users",
+  "scan_path": "src/users",
+  "total_issues": 12,
+  "critical": 2,
+  "high": 4,
+  "medium": 4,
+  "low": 2,
+  "checks": [
+    {"id": "dry_violations", "name": "DRY Violations", "status": "failed", "details": "4 duplications found"},
+    {"id": "kiss_violations", "name": "KISS Violations", "status": "warning", "details": "1 over-engineered abstraction"},
+    {"id": "yagni_violations", "name": "YAGNI Violations", "status": "passed", "details": "No unused code"},
+    {"id": "solid_violations", "name": "SOLID Violations", "status": "failed", "details": "2 SRP violations"}
+  ],
+  "findings": [
+    {
+      "severity": "CRITICAL",
+      "location": "src/users/controllers/UserController.ts:45",
+      "issue": "Controller directly uses Repository (layer boundary break)",
+      "principle": "Layer Separation (Clean Architecture)",
+      "recommendation": "Create UserService, inject into controller",
+      "effort": "L",
+      "domain": "users"
+    },
+    {
+      "severity": "HIGH",
+      "location": "src/users/services/UserService.ts:45",
+      "issue": "DRY violation - duplicate validation logic",
+      "principle": "DRY Principle",
+      "recommendation": "Extract to shared validators module",
+      "effort": "M",
+      "domain": "users"
+    }
+  ]
+}
+```
+
+## Critical Rules
+
+- **Do not auto-fix:** Report only
+- **Domain-aware scanning:** If `domain_mode="domain-aware"`, scan ONLY `scan_path` (not entire codebase)
+- **Tag findings:** Include `domain` field in each finding when domain-aware
+- **Context-aware:** Use project's `principles.md` to define what's acceptable
+- **Age matters:** Old TODOs are higher severity than recent ones
+- **Effort realism:** S = <1h, M = 1-4h, L = >4h
+
+## Definition of Done
+
+- contextStore parsed (including domain_mode and current_domain)
+- scan_path determined (domain path or codebase root)
+- All 8 checks completed (scoped to scan_path):
+  - DRY (7 subcategories), KISS, YAGNI, TODOs, Error Handling, Centralized Errors, DI/Init, Best Practices Guide
+- Findings collected with severity, location, effort, recommendation, domain
+- Score calculated
+- JSON returned to coordinator with domain metadata
+
+## Reference Files
+
+- **Audit scoring formula:** `shared/references/audit_scoring.md`
+- **Audit output schema:** `shared/references/audit_output_schema.md`
+- Architecture rules: [references/architecture_rules.md](references/architecture_rules.md)
+
+---
+**Version:** 4.1.0
+**Last Updated:** 2026-01-29

.claude/skills/code-quality-auditor/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: ln-624-code-quality-auditor
+description: "Code quality audit worker (L3). Checks cyclomatic complexity, deep nesting, long methods, god classes, method signature quality, O(n²) algorithms, N+1 queries, magic numbers/constants. Returns findings with severity, location, effort, recommendations."
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Code Quality Auditor (L3 Worker)
+
+Specialized worker auditing code complexity, method signatures, algorithms, and constants management.
+
+## Purpose & Scope
+
+- **Worker in ln-620 coordinator pipeline** - invoked by ln-620-codebase-auditor
+- Audit **code quality** (Categories 5+6+NEW: Medium Priority)
+- Check complexity metrics, method signature quality, algorithmic efficiency, constants management
+- Return structured findings with severity, location, effort, recommendations
+- Calculate compliance score (X/10) for Code Quality category
+
+## Inputs (from Coordinator)
+
+**MANDATORY READ:** Load `shared/references/task_delegation_pattern.md#audit-coordinator--worker-contract` for contextStore structure.
+
+Receives `contextStore` with: `tech_stack`, `best_practices`, `principles`, `codebase_root`.
+
+**Domain-aware:** Supports `domain_mode` + `current_domain` (see `audit_output_schema.md#domain-aware-worker-output`).
+
+## Workflow
+
+1) **Parse context** — extract fields, determine `scan_path` (domain-aware if specified)
+2) **Scan codebase for violations**
+   - All Grep/Glob patterns use `scan_path` (not codebase_root)
+   - Example: `Grep(pattern="if.*if.*if", path=scan_path)` for nesting detection
+
+3) **Collect findings with severity, location, effort, recommendation**
+   - Tag each finding with `domain: domain_name` (if domain-aware)
+
+4) **Calculate score using penalty algorithm**
+
+5) **Return JSON result to coordinator**
+   - Include `domain` and `scan_path` fields (if domain-aware)
+
+## Audit Rules (Priority: MEDIUM)
+
+### 1. Cyclomatic Complexity
+**What:** Too many decision points in single function (> 10)
+
+**Detection:**
+- Count if/else, switch/case, ternary, &&, ||, for, while
+- Use tools: `eslint-plugin-complexity`, `radon` (Python), `gocyclo` (Go)
+
+**Severity:**
+- **HIGH:** Complexity > 20 (extremely hard to test)
+- **MEDIUM:** Complexity 11-20 (refactor recommended)
+- **LOW:** Complexity 8-10 (acceptable but monitor)
+
+**Recommendation:** Split function, extract helper methods, use early returns
+
+**Effort:** M-L (depends on complexity)
+
+### 2. Deep Nesting (> 4 levels)
+**What:** Nested if/for/while blocks too deep
+
+**Detection:**
+- Count indentation levels
+- Pattern: if { if { if { if { if { ... } } } } }
+
+**Severity:**
+- **HIGH:** > 6 levels (unreadable)
+- **MEDIUM:** 5-6 levels
+- **LOW:** 4 levels
+
+**Recommendation:** Extract functions, use guard clauses, invert conditions
+
+**Effort:** M (refactor structure)
+
+### 3. Long Methods (> 50 lines)
+**What:** Functions too long, doing too much
+
+**Detection:**
+- Count lines between function start and end
+- Exclude comments, blank lines
+
+**Severity:**
+- **HIGH:** > 100 lines
+- **MEDIUM:** 51-100 lines
+- **LOW:** 40-50 lines (borderline)
+
+**Recommendation:** Split into smaller functions, apply Single Responsibility
+
+**Effort:** M (extract logic)
+
+### 4. God Classes/Modules (> 500 lines)
+**What:** Files with too many responsibilities
+
+**Detection:**
+- Count lines in file (exclude comments)
+- Check number of public methods/functions
+
+**Severity:**
+- **HIGH:** > 1000 lines
+- **MEDIUM:** 501-1000 lines
+- **LOW:** 400-500 lines
+
+**Recommendation:** Split into multiple files, apply separation of concerns
+
+**Effort:** L (major refactor)
+
+### 5. Too Many Parameters (> 5)
+**What:** Functions with excessive parameters
+
+**Detection:**
+- Count function parameters
+- Check constructors, methods
+
+**Severity:**
+- **MEDIUM:** 6-8 parameters
+- **LOW:** 5 parameters (borderline)
+
+**Recommendation:** Use parameter object, builder pattern, default parameters
+
+**Effort:** S-M (refactor signature + calls)
+
+### 6. O(n²) or Worse Algorithms
+**What:** Inefficient nested loops over collections
+
+**Detection:**
+- Nested for loops: `for (i) { for (j) { ... } }`
+- Nested array methods: `arr.map(x => arr.filter(...))`
+
+**Severity:**
+- **HIGH:** O(n²) in hot path (API request handler)
+- **MEDIUM:** O(n²) in occasional operations
+- **LOW:** O(n²) on small datasets (n < 100)
+
+**Recommendation:** Use hash maps, optimize with single pass, use better data structures
+
+**Effort:** M (algorithm redesign)
+
+### 7. N+1 Query Patterns
+**What:** ORM lazy loading causing N+1 queries
+
+**Detection:**
+- Find loops with database queries inside
+- Check ORM patterns: `users.forEach(u => u.getPosts())`
+
+**Severity:**
+- **CRITICAL:** N+1 in API endpoint (performance disaster)
+- **HIGH:** N+1 in frequent operations
+- **MEDIUM:** N+1 in admin panel
+
+**Recommendation:** Use eager loading, batch queries, JOIN
+
+**Effort:** M (change ORM query)
+
+### 8. Constants Management (NEW)
+**What:** Magic numbers/strings, decentralized constants, duplicates
+
+**Detection:**
+
+| Issue | Pattern | Example |
+|-------|---------|---------|
+| Magic numbers | Hardcoded numbers in conditions/calculations | `if (status === 2)` |
+| Magic strings | Hardcoded strings in comparisons | `if (role === 'admin')` |
+| Decentralized | Constants scattered across files | `MAX_SIZE = 100` in 5 files |
+| Duplicates | Same value multiple times | `STATUS_ACTIVE = 1` in 3 places |
+| No central file | Missing `constants.ts` or `config.py` | No single source of truth |
+
+**Severity:**
+- **HIGH:** Magic numbers in business logic (payment amounts, statuses)
+- **MEDIUM:** Duplicate constants (same value defined 3+ times)
+- **MEDIUM:** No central constants file
+- **LOW:** Magic strings in logging/debugging
+
+**Recommendation:**
+- Create central constants file (`constants.ts`, `config.py`, `constants.go`)
+- Extract magic numbers to named constants: `const STATUS_ACTIVE = 1`
+- Consolidate duplicates, import from central file
+- Use enums for related constants
+
+**Effort:** M (extract constants, update imports, consolidate)
+
+### 9. Method Signature Quality
+**What:** Poor method contracts reducing readability and maintainability
+
+**Detection:**
+
+| Issue | Pattern | Example |
+|-------|---------|---------|
+| Boolean flag params | >=2 boolean params in signature | `def process(data, is_async: bool, skip_validation: bool)` |
+| Too many optional params | >=3 optional params with defaults | `def query(db, limit=10, offset=0, sort="id", order="asc")` |
+| Inconsistent verb naming | Different verbs for same operation type in one module | `get_user()` vs `fetch_account()` vs `load_profile()` |
+| Unclear return type | `-> dict`, `-> Any`, `-> tuple` without TypedDict/NamedTuple | `def get_stats() -> dict` instead of `-> StatsResponse` |
+
+**Severity:**
+- **MEDIUM:** Boolean flag params (use enum/strategy), unclear return types
+- **LOW:** Too many optional params, inconsistent naming
+
+**Recommendation:**
+- Boolean flags: replace with enum, strategy pattern, or separate methods
+- Optional params: group into config/options dataclass
+- Naming: standardize verb conventions per module (`get_` for sync, `fetch_` for async, etc.)
+- Return types: use TypedDict, NamedTuple, or dataclass instead of raw dict/tuple
+
+**Effort:** S-M (refactor signatures + callers)
+
+## Scoring Algorithm
+
+See `shared/references/audit_scoring.md` for unified formula and score interpretation.
+
+## Output Format
+
+Return JSON to coordinator:
+
+**Global mode output:**
+```json
+{
+  "category": "Code Quality",
+  "score": 6,
+  "total_issues": 12,
+  "critical": 1,
+  "high": 3,
+  "medium": 5,
+  "low": 3,
+  "checks": [
+    {"id": "cyclomatic_complexity", "name": "Cyclomatic Complexity", "status": "failed", "details": "2 functions exceed threshold"},
+    {"id": "deep_nesting", "name": "Deep Nesting", "status": "warning", "details": "1 function with 5 levels"},
+    {"id": "long_methods", "name": "Long Methods", "status": "passed", "details": "No methods exceed 50 lines"},
+    {"id": "magic_numbers", "name": "Magic Numbers", "status": "failed", "details": "5 magic numbers found"}
+  ],
+  "findings": [...]
+}
+```
+
+**Domain-aware mode output (NEW):**
+```json
+{
+  "category": "Code Quality",
+  "score": 7,
+  "domain": "orders",
+  "scan_path": "src/orders",
+  "total_issues": 8,
+  "critical": 0,
+  "high": 2,
+  "medium": 4,
+  "low": 2,
+  "checks": [
+    {"id": "cyclomatic_complexity", "name": "Cyclomatic Complexity", "status": "failed", "details": "1 function exceeds threshold"},
+    {"id": "deep_nesting", "name": "Deep Nesting", "status": "passed", "details": "No deep nesting detected"},
+    {"id": "long_methods", "name": "Long Methods", "status": "passed", "details": "No methods exceed 50 lines"},
+    {"id": "magic_numbers", "name": "Magic Numbers", "status": "warning", "details": "1 magic number found"}
+  ],
+  "findings": [
+    {
+      "severity": "HIGH",
+      "location": "src/orders/services/OrderService.ts:120",
+      "issue": "Cyclomatic complexity 22 (threshold: 10)",
+      "principle": "Code Complexity / Maintainability",
+      "recommendation": "Split into smaller methods",
+      "effort": "M",
+      "domain": "orders"
+    },
+    {
+      "severity": "MEDIUM",
+      "location": "src/orders/controllers/OrderController.ts:45",
+      "issue": "Magic number '3' used for order status",
+      "principle": "Constants Management",
+      "recommendation": "Extract: const ORDER_STATUS_SHIPPED = 3",
+      "effort": "S",
+      "domain": "orders"
+    }
+  ]
+}
+```
+
+## Critical Rules
+
+- **Do not auto-fix:** Report only
+- **Domain-aware scanning:** If `domain_mode="domain-aware"`, scan ONLY `scan_path` (not entire codebase)
+- **Tag findings:** Include `domain` field in each finding when domain-aware
+- **Context-aware:** Small functions (n < 100) with O(n²) may be acceptable
+- **Constants detection:** Exclude test files, configs, examples
+- **Metrics tools:** Use existing tools when available (ESLint complexity plugin, radon, gocyclo)
+
+## Definition of Done
+
+- contextStore parsed (including domain_mode and current_domain)
+- scan_path determined (domain path or codebase root)
+- All 9 checks completed (scoped to scan_path):
+  - complexity, nesting, length, god classes, parameters, O(n²), N+1, constants, method signatures
+- Findings collected with severity, location, effort, recommendation, domain
+- Score calculated
+- JSON returned to coordinator with domain metadata
+
+## Reference Files
+
+- **Audit scoring formula:** `shared/references/audit_scoring.md`
+- **Audit output schema:** `shared/references/audit_output_schema.md`
+- Code quality rules: [references/code_quality_rules.md](references/code_quality_rules.md)
+
+---
+**Version:** 3.0.0
+**Last Updated:** 2025-12-23

.claude/skills/code-quality-checker/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: ln-501-code-quality-checker
+description: "Worker that checks DRY/KISS/YAGNI/architecture compliance with quantitative Code Quality Score. Validates architectural decisions via MCP Ref: (1) Optimality - is chosen approach the best? (2) Compliance - does it follow best practices? (3) Performance - algorithms, configs, bottlenecks. Reports issues with SEC-, PERF-, MNT-, ARCH-, BP-, OPT- prefixes."
+---
+
+# Code Quality Checker
+
+Analyzes Done implementation tasks with quantitative Code Quality Score based on metrics, MCP Ref validation, and issue penalties.
+
+## Purpose & Scope
+- Load Story and Done implementation tasks (exclude test tasks)
+- Calculate Code Quality Score using metrics and issue penalties
+- **MCP Ref validation:** Verify optimality, best practices, and performance via external sources
+- Check for DRY/KISS/YAGNI violations, architecture boundary breaks, security issues
+- Produce quantitative verdict with structured issue list; never edits Linear or kanban
+
+## Code Metrics
+
+| Metric | Threshold | Penalty |
+|--------|-----------|---------|
+| **Cyclomatic Complexity** | ≤10 OK, 11-20 warning, >20 fail | -5 (warning), -10 (fail) per function |
+| **Function size** | ≤50 lines OK, >50 warning | -3 per function |
+| **File size** | ≤500 lines OK, >500 warning | -5 per file |
+| **Nesting depth** | ≤3 OK, >3 warning | -3 per instance |
+| **Parameter count** | ≤4 OK, >4 warning | -2 per function |
+
+## Code Quality Score
+
+Formula: `Code Quality Score = 100 - metric_penalties - issue_penalties`
+
+**Issue penalties by severity:**
+
+| Severity | Penalty | Examples |
+|----------|---------|----------|
+| **high** | -20 | Security vulnerability, O(n²)+ algorithm, N+1 query |
+| **medium** | -10 | DRY violation, suboptimal approach, missing config |
+| **low** | -3 | Naming convention, minor code smell |
+
+**Score interpretation:**
+
+| Score | Status | Verdict |
+|-------|--------|---------|
+| 90-100 | Excellent | PASS |
+| 70-89 | Acceptable | CONCERNS |
+| <70 | Below threshold | ISSUES_FOUND |
+
+## Issue Prefixes
+
+| Prefix | Category | Default Severity | MCP Ref |
+|--------|----------|------------------|---------|
+| SEC- | Security (auth, validation, secrets) | high | — |
+| PERF- | Performance (algorithms, configs, bottlenecks) | medium/high | ✓ Required |
+| MNT- | Maintainability (DRY, SOLID, complexity) | medium | — |
+| ARCH- | Architecture (layers, boundaries, patterns) | medium | — |
+| BP- | Best Practices (implementation differs from recommended) | medium | ✓ Required |
+| OPT- | Optimality (better approach exists for this goal) | medium | ✓ Required |
+
+**PERF- subcategories:**
+
+| Prefix | Category | Severity |
+|--------|----------|----------|
+| PERF-ALG- | Algorithm complexity (Big O) | high if O(n²)+ |
+| PERF-CFG- | Package/library configuration | medium |
+| PERF-PTN- | Architectural pattern performance | high |
+| PERF-DB- | Database queries, indexes | high |
+
+## When to Use
+- **Invoked by ln-500-story-quality-gate** Pass 1 (first gate)
+- All implementation tasks in Story status = Done
+- Before regression testing (ln-502) and test planning (ln-510)
+
+## Workflow (concise)
+1) Load Story (full) and Done implementation tasks (full descriptions) via Linear; skip tasks with label "tests".
+2) Collect affected files from tasks (Affected Components/Existing Code Impact) and recent commits/diffs if noted.
+3) **Calculate code metrics:**
+   - Cyclomatic Complexity per function (target ≤10)
+   - Function size (target ≤50 lines)
+   - File size (target ≤500 lines)
+   - Nesting depth (target ≤3)
+   - Parameter count (target ≤4)
+
+3.5) **MCP Ref Validation (MANDATORY for code changes):**
+
+   **Level 1 — OPTIMALITY (OPT-):**
+   - Extract goal from task (e.g., "user authentication", "caching", "API rate limiting")
+   - Research alternatives: `ref_search_documentation("{goal} approaches comparison {tech_stack} 2026")`
+   - Compare chosen approach vs alternatives for project context
+   - Flag suboptimal choices as OPT- issues
+
+   **Level 2 — BEST PRACTICES (BP-):**
+   - Research: `ref_search_documentation("{chosen_approach} best practices {tech_stack} 2026")`
+   - For libraries: `query-docs(library_id, "best practices implementation patterns")`
+   - Flag deviations from recommended patterns as BP- issues
+
+   **Level 3 — PERFORMANCE (PERF-):**
+   - **PERF-ALG:** Analyze algorithm complexity (detect O(n²)+, research optimal via MCP Ref)
+   - **PERF-CFG:** Check library configs (connection pooling, batch sizes, timeouts) via `query-docs`
+   - **PERF-PTN:** Research pattern pitfalls: `ref_search_documentation("{pattern} performance bottlenecks")`
+   - **PERF-DB:** Check for N+1, missing indexes via `query-docs(orm_library_id, "query optimization")`
+
+   **Triggers for MCP Ref validation:**
+   - New dependency added (package.json/requirements.txt changed)
+   - New pattern/library used
+   - API/database changes
+   - Loops/recursion in critical paths
+   - ORM queries added
+
+4) **Analyze code for static issues (assign prefixes):**
+   - SEC-: hardcoded creds, unvalidated input, SQL injection, race conditions
+   - MNT-: DRY violations, dead code, complex conditionals, poor naming
+   - ARCH-: layer violations, circular dependencies, guide non-compliance
+
+5) **Calculate Code Quality Score:**
+   - Start with 100
+   - Subtract metric penalties (see Code Metrics table)
+   - Subtract issue penalties (see Issue penalties table)
+
+6) Output verdict with score and structured issues. Add Linear comment with findings.
+
+## Critical Rules
+- Read guides mentioned in Story/Tasks before judging compliance.
+- **MCP Ref validation:** For ANY architectural change, MUST verify via ref_search_documentation before judging.
+- **Context7 for libraries:** When reviewing library usage, query-docs to verify correct patterns.
+- Language preservation in comments (EN/RU).
+- Do not create tasks or change statuses; caller decides next actions.
+
+## Definition of Done
+- Story and Done implementation tasks loaded (test tasks excluded).
+- Code metrics calculated (Cyclomatic Complexity, function/file sizes).
+- **MCP Ref validation completed:**
+  - OPT-: Optimality checked (is chosen approach the best for the goal?)
+  - BP-: Best practices verified (correct implementation of chosen approach?)
+  - PERF-: Performance analyzed (algorithms, configs, patterns, DB)
+- Issues identified with prefixes and severity, sources from MCP Ref/Context7.
+- Code Quality Score calculated.
+- **Output format:**
+  ```yaml
+  verdict: PASS | CONCERNS | ISSUES_FOUND
+  code_quality_score: {0-100}
+  metrics:
+    avg_cyclomatic_complexity: {value}
+    functions_over_50_lines: {count}
+    files_over_500_lines: {count}
+  issues:
+    # OPTIMALITY
+    - id: "OPT-001"
+      severity: medium
+      file: "src/auth/index.ts"
+      goal: "User session management"
+      finding: "Suboptimal approach for session management"
+      chosen: "Custom JWT with localStorage"
+      recommended: "httpOnly cookies + refresh token rotation"
+      reason: "httpOnly cookies prevent XSS token theft"
+      source: "ref://owasp-session-management"
+
+    # BEST PRACTICES
+    - id: "BP-001"
+      severity: medium
+      file: "src/api/routes.ts"
+      finding: "POST for idempotent operation"
+      best_practice: "Use PUT for idempotent updates (RFC 7231)"
+      source: "ref://api-design-guide#idempotency"
+
+    # PERFORMANCE - Algorithm
+    - id: "PERF-ALG-001"
+      severity: high
+      file: "src/utils/search.ts:42"
+      finding: "Nested loops cause O(n²) complexity"
+      current: "O(n²) - nested filter().find()"
+      optimal: "O(n) - use Map/Set for lookup"
+      source: "ref://javascript-performance#data-structures"
+
+    # PERFORMANCE - Config
+    - id: "PERF-CFG-001"
+      severity: medium
+      file: "src/db/connection.ts"
+      finding: "Missing connection pool config"
+      current_config: "default (pool: undefined)"
+      recommended: "pool: { min: 2, max: 10 }"
+      source: "context7://pg#connection-pooling"
+
+    # PERFORMANCE - Database
+    - id: "PERF-DB-001"
+      severity: high
+      file: "src/repositories/user.ts:89"
+      finding: "N+1 query pattern detected"
+      issue: "users.map(u => u.posts) triggers N queries"
+      solution: "Use eager loading: include: { posts: true }"
+      source: "context7://prisma#eager-loading"
+
+    # MAINTAINABILITY
+    - id: "MNT-001"
+      severity: medium
+      file: "src/service.ts:42"
+      finding: "DRY violation: duplicate validation logic"
+      suggested_action: "Extract to shared validator"
+  ```
+- Linear comment posted with findings.
+
+## Reference Files
+- Code metrics: `references/code_metrics.md` (thresholds and penalties)
+- Guides: `docs/guides/`
+- Templates for context: `shared/templates/task_template_implementation.md`
+
+---
+**Version:** 5.0.0 (Added 3-level MCP Ref validation: Optimality, Best Practices, Performance with PERF-ALG/CFG/PTN/DB subcategories)
+**Last Updated:** 2026-01-29

.claude/skills/code-refactoring/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: code-refactoring
+description: 코드 리팩토링 권장사항, 성능 분석, 구체적인 코드 패치를 제공합니다. 리팩토링, 코드 개선, 성능 최적화 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Code Refactoring
+
+코드 품질 개선을 위한 리팩토링 분석 및 권장사항을 제공하는 스킬입니다.
+
+## 기능
+
+### 분석 영역
+- **코드 스멜 탐지**: 중복 코드, 긴 메서드, 거대 클래스
+- **복잡도 분석**: 순환 복잡도, 인지 복잡도
+- **의존성 분석**: 결합도, 응집도 평가
+- **성능 이슈**: 비효율적 알고리즘, N+1 쿼리
+- **가독성**: 네이밍, 구조화, 주석 품질
+
+### 리팩토링 패턴
+- Extract Method / Extract Class
+- Replace Conditional with Polymorphism
+- Introduce Parameter Object
+- Replace Magic Number with Symbolic Constant
+- Decompose Conditional
+- Replace Nested Conditional with Guard Clauses
+
+### 출력
+- 문제점 상세 설명
+- 리팩토링 전후 코드 비교
+- 구체적인 수정 패치
+- 성능 영향 분석
+
+## 분석 프로세스
+
+1. 코드베이스 스캔
+2. 코드 스멜 및 안티패턴 탐지
+3. 복잡도 메트릭 계산
+4. 개선 우선순위 산정
+5. 리팩토링 제안 생성
+6. 전후 비교 코드 제공
+
+## 리포트 구조
+
+```markdown
+# 리팩토링 분석 리포트
+
+## 요약
+- 분석 파일: N개
+- 발견된 코드 스멜: N개
+- 권장 리팩토링: N건
+
+## 🔴 High Impact 리팩토링
+
+### 1. [파일명] 긴 메서드 분리
+**현재 상태**
+- 메서드: `processOrder()`
+- 라인 수: 150줄
+- 순환 복잡도: 25
+
+**문제점**
+- 단일 책임 원칙 위반
+- 테스트 어려움
+- 유지보수 복잡
+
+**권장 리팩토링: Extract Method**
+
+Before:
+```java
+public void processOrder(Order order) {
+    // 150줄의 복잡한 로직
+}
+```
+
+After:
+```java
+public void processOrder(Order order) {
+    validateOrder(order);
+    calculateTotal(order);
+    applyDiscounts(order);
+    processPayment(order);
+    sendConfirmation(order);
+}
+
+private void validateOrder(Order order) { ... }
+private void calculateTotal(Order order) { ... }
+// ...
+```
+
+**예상 효과**
+- 복잡도: 25 → 5
+- 테스트 용이성 향상
+- 재사용성 증가
+
+## 🟡 Medium Impact 리팩토링
+...
+
+## 성능 최적화 제안
+...
+```
+
+## 사용 예시
+
+```
+이 코드를 리팩토링 해줘
+src 폴더의 코드 품질을 분석하고 개선점을 알려줘
+이 함수의 복잡도를 낮추는 방법을 제안해줘
+```
+
+## 출처
+Original skill from skills.cokac.com

.claude/skills/codebase-analysis-web-report/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: codebase-analysis-web-report
+description: 코드베이스를 분석하여 아키텍처, 호출/데이터 흐름 그래프, 인터랙티브 다이어그램, 검색 기능이 포함된 자체 완결형 HTML 리포트를 생성합니다. 저장소 분석, 프로젝트 디렉토리 분석, 소스 파일 분석 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Codebase Analysis Web Report Generator
+
+코드베이스를 분석하여 자체 완결형 인터랙티브 HTML 리포트를 생성하는 스킬입니다.
+
+## 기능
+
+### 입력 처리
+- 저장소 URL, 파일 업로드, 디렉토리 경로 지원
+- 프레임워크별 분석 지원 (React, Node, Flask, PHP 등)
+- 대규모 코드베이스의 경우 자동 범위 지정 또는 사용자 지정 요청
+
+### 분석 구성요소
+- 모듈, 클래스, 함수, API 추출을 위한 정적 코드 분석
+- 호출 관계 매핑 및 의존성 추출
+- 메트릭 계산 (LOC, 복잡도 추정)
+- 진입점 및 통합 지점 식별
+
+### 출력 생성
+- 제어/데이터 흐름 그래프 (개략적 및 세부적)
+- 모듈 설명이 포함된 텍스트 요약
+- 우선순위가 지정된 개선 권장사항이 포함된 발견사항 섹션
+- 네비게이션, 인터랙티브 다이어그램, 검색 기능, 소스 코드 미리보기가 포함된 자체 완결형 HTML 리포트
+
+## 구현 노트
+
+- 가능한 경우 AST 파싱 사용; 그 외에는 정규식 휴리스틱 사용
+- 인터랙티브 다이어그램에 Mermaid 또는 Cytoscape.js 우선 사용
+- 샘플링 또는 범위 제한을 통해 대규모 저장소 처리
+- 프레임워크별 구조 표시 (React 컴포넌트, 라우팅, DB 접근 패턴)
+
+## 리포트 구조
+
+```html
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+    <meta charset="UTF-8">
+    <title>코드베이스 분석 리포트</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+    <!-- 인라인 CSS 및 스크립트 -->
+</head>
+<body>
+    <!-- 1. 요약 섹션 -->
+    <!-- 2. 아키텍처 다이어그램 -->
+    <!-- 3. 모듈별 상세 분석 -->
+    <!-- 4. 호출 흐름 그래프 -->
+    <!-- 5. 데이터 흐름 그래프 -->
+    <!-- 6. 검색 가능한 인덱스 -->
+    <!-- 7. 개선 권장사항 -->
+</body>
+</html>
+```
+
+## 사용 예시
+
+```
+이 프로젝트의 코드베이스를 분석해서 HTML 리포트로 만들어줘
+src 폴더의 아키텍처를 분석하고 다이어그램으로 시각화해줘
+이 저장소의 구조를 분석해서 웹 문서로 생성해줘
+```
+
+## 출처
+Original skill by Dongchan Lee (@vluylbhtqq) from skills.cokac.com

.claude/skills/concurrency-auditor/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: ln-628-concurrency-auditor
+description: Concurrency audit worker (L3). Checks race conditions, missing async/await, resource contention, thread safety, deadlock potential. Returns findings with severity, location, effort, recommendations.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Concurrency Auditor (L3 Worker)
+
+Specialized worker auditing concurrency and async patterns.
+
+## Purpose & Scope
+
+- **Worker in ln-620 coordinator pipeline**
+- Audit **concurrency** (Category 11: High Priority)
+- Check race conditions, async/await, thread safety
+- Calculate compliance score (X/10)
+
+## Inputs (from Coordinator)
+
+Receives `contextStore` with tech stack, language, codebase root.
+
+## Workflow
+
+1) Parse context
+2) Check concurrency patterns
+3) Collect findings
+4) Calculate score
+5) Return JSON
+
+## Audit Rules
+
+### 1. Race Conditions
+**What:** Shared state modified without synchronization
+
+**Detection Patterns:**
+
+| Language | Pattern | Grep |
+|----------|---------|------|
+| Python | Global modified in async | `global\s+\w+` inside `async def` |
+| TypeScript | Module-level let in async | `^let\s+\w+` at file scope + async function modifies it |
+| Go | Map access without mutex | `map\[.*\].*=` without `sync.Mutex` in same file |
+| All | Shared cache | `cache\[.*\]\s*=` or `cache\.set` without lock |
+
+**Severity:**
+- **CRITICAL:** Race in payment/auth (`payment`, `balance`, `auth`, `token` in variable name)
+- **HIGH:** Race in user-facing feature
+- **MEDIUM:** Race in background job
+
+**Recommendation:** Use locks, atomic operations, message queues
+
+**Effort:** M-L
+
+### 2. Missing Async/Await
+**What:** Callback hell or unhandled promises
+
+**Detection Patterns:**
+
+| Issue | Grep | Example |
+|-------|------|---------|
+| Callback hell | `\.then\(.*\.then\(.*\.then\(` | `.then().then().then()` |
+| Fire-and-forget | `async.*\(\)` not preceded by `await` | `saveToDb()` without await |
+| Missing await | `return\s+new\s+Promise` in async function | Should just `return await` or `return` value |
+| Dangling promise | `\.catch\(\s*\)` | Empty catch swallows errors |
+
+**Severity:**
+- **HIGH:** Fire-and-forget async (can cause data loss)
+- **MEDIUM:** Callback hell (hard to maintain)
+- **LOW:** Mixed Promise styles
+
+**Recommendation:** Convert to async/await, always await or handle promises
+
+**Effort:** M
+
+### 3. Resource Contention
+**What:** Multiple processes competing for same resource
+
+**Detection Patterns:**
+
+| Issue | Grep | Example |
+|-------|------|---------|
+| File lock missing | `open\(.*["']w["']\)` without `flock` or `lockfile` | Concurrent file writes |
+| Connection exhaustion | `create_engine\(.*pool_size` check if pool_size < 5 | DB pool too small |
+| Concurrent writes | `writeFile` or `fs\.write` without lock check | File corruption risk |
+
+**Severity:**
+- **HIGH:** File corruption risk, DB exhaustion
+- **MEDIUM:** Performance degradation
+
+**Recommendation:** Use connection pooling, file locking, `asyncio.Lock`
+
+**Effort:** M
+
+### 4. Thread Safety Violations
+**What:** Shared mutable state without synchronization
+
+**Detection Patterns:**
+
+| Language | Safe Pattern | Unsafe Pattern |
+|----------|--------------|----------------|
+| Go | `sync.Mutex` with map | `map[...]` without Mutex in same struct |
+| Rust | `Arc<Mutex<T>>` | `Rc<RefCell<T>>` in multi-threaded context |
+| Java | `synchronized` or `ConcurrentHashMap` | `HashMap` shared between threads |
+| Python | `threading.Lock` | Global dict modified in threads |
+
+**Grep patterns:**
+- Go unsafe: `type.*struct\s*{[^}]*map\[` without `sync.Mutex` in same struct
+- Python unsafe: `global\s+\w+` in function + `threading.Thread` in same file
+
+**Severity:** **HIGH** (data corruption possible)
+
+**Recommendation:** Use thread-safe primitives
+
+**Effort:** M
+
+### 5. Deadlock Potential
+**What:** Lock acquisition in inconsistent order
+
+**Detection Patterns:**
+
+| Issue | Grep | Example |
+|-------|------|---------|
+| Nested locks | `with\s+\w+_lock:.*with\s+\w+_lock:` (multiline) | Lock A then Lock B |
+| Lock in loop | `for.*:.*\.acquire\(\)` | Lock acquired repeatedly without release |
+| Lock + external call | `.acquire\(\)` followed by `await` or `requests.` | Holding lock during I/O |
+
+**Severity:** **HIGH** (deadlock freezes application)
+
+**Recommendation:** Consistent lock ordering, timeout locks (`asyncio.wait_for`)
+
+**Effort:** L
+
+### 6. Blocking I/O in Event Loop (Python asyncio)
+**What:** Synchronous blocking calls inside async functions
+
+**Detection Patterns:**
+
+| Blocking Call | Grep in `async def` | Replacement |
+|---------------|---------------------|-------------|
+| `time.sleep` | `time\.sleep` inside async def | `await asyncio.sleep` |
+| `requests.` | `requests\.(get\|post)` inside async def | `httpx` or `aiohttp` |
+| `open()` file | `open\(` inside async def | `aiofiles.open` |
+
+**Severity:**
+- **HIGH:** Blocks entire event loop
+- **MEDIUM:** Minor blocking (<100ms)
+
+**Recommendation:** Use async alternatives
+
+**Effort:** S-M
+
+## Scoring Algorithm
+
+See `shared/references/audit_scoring.md` for unified formula and score interpretation.
+
+## Output Format
+
+```json
+{
+  "category": "Concurrency",
+  "score": 7,
+  "total_issues": 4,
+  "critical": 0,
+  "high": 2,
+  "medium": 2,
+  "low": 0,
+  "checks": [
+    {"id": "race_conditions", "name": "Race Conditions", "status": "passed", "details": "No shared state modified without synchronization"},
+    {"id": "missing_await", "name": "Missing Await", "status": "failed", "details": "2 fire-and-forget async calls found"},
+    {"id": "resource_contention", "name": "Resource Contention", "status": "warning", "details": "DB pool_size=3 may be insufficient"},
+    {"id": "thread_safety", "name": "Thread Safety", "status": "passed", "details": "All shared state properly synchronized"},
+    {"id": "deadlock_potential", "name": "Deadlock Potential", "status": "passed", "details": "No nested locks or inconsistent ordering"},
+    {"id": "blocking_io", "name": "Blocking I/O", "status": "failed", "details": "time.sleep in async context"}
+  ],
+  "findings": [
+    {
+      "severity": "HIGH",
+      "location": "src/services/payment.ts:45",
+      "issue": "Shared state 'balanceCache' modified without synchronization",
+      "principle": "Thread Safety / Concurrency Control",
+      "recommendation": "Use mutex or atomic operations for balanceCache updates",
+      "effort": "M"
+    }
+  ]
+}
+```
+
+## Reference Files
+
+- **Audit scoring formula:** `shared/references/audit_scoring.md`
+- **Audit output schema:** `shared/references/audit_output_schema.md`
+
+---
+**Version:** 3.0.0
+**Last Updated:** 2025-12-23

.claude/skills/coverage-improvement-planner/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: coverage-improvement-planner
+description: 테스트 커버리지를 분석하고 개선 계획을 수립하며 전후 비교 리포트를 생성합니다. 테스트 커버리지, 테스트 개선, 품질 향상 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Coverage Improvement Planner
+
+테스트 커버리지를 분석하고 체계적인 개선 계획을 수립하는 스킬입니다.
+
+## 기능
+
+### 분석 항목
+- **라인 커버리지**: 실행된 코드 라인 비율
+- **브랜치 커버리지**: 조건문 분기 테스트 비율
+- **함수 커버리지**: 테스트된 함수 비율
+- **파일 커버리지**: 테스트가 있는 파일 비율
+
+### 개선 계획 수립
+- 미테스트 코드 영역 식별
+- 우선순위 기반 테스트 추가 권장
+- 복잡도 높은 코드 집중 분석
+- 테스트 케이스 템플릿 제공
+
+### 지원 프레임워크
+- Jest (JavaScript/TypeScript)
+- pytest (Python)
+- JUnit (Java/Kotlin)
+- PHPUnit (PHP)
+- Go test
+
+## 워크플로우
+
+1. 현재 커버리지 수집 및 분석
+2. 커버리지 갭 식별
+3. 비즈니스 중요도 기반 우선순위 산정
+4. 테스트 케이스 템플릿 생성
+5. 구현 후 전후 비교 리포트 생성
+
+## 리포트 구조
+
+```markdown
+# 테스트 커버리지 개선 계획
+
+## 현재 상태
+| 메트릭 | 현재 | 목표 | 갭 |
+|--------|------|------|-----|
+| 라인 커버리지 | 65% | 80% | 15% |
+| 브랜치 커버리지 | 45% | 70% | 25% |
+| 함수 커버리지 | 70% | 85% | 15% |
+
+## 우선순위별 개선 대상
+
+### 🔴 High Priority (비즈니스 크리티컬)
+1. **payment/checkout.js**
+   - 현재: 30% | 목표: 90%
+   - 미테스트 함수: processPayment, validateCard
+   - 권장 테스트 케이스: 5개
+
+### 🟡 Medium Priority
+...
+
+### 🟢 Low Priority
+...
+
+## 권장 테스트 케이스
+
+### checkout.test.js
+```javascript
+describe('processPayment', () => {
+  test('성공적인 결제 처리', () => {
+    // 테스트 코드
+  });
+
+  test('잘못된 카드 정보 처리', () => {
+    // 테스트 코드
+  });
+});
+```
+
+## 예상 결과
+- 개선 후 예상 라인 커버리지: 82%
+- 추가 테스트 케이스: 23개
+- 예상 소요 시간: 개발자 판단
+```
+
+## 사용 예시
+
+```
+테스트 커버리지를 분석하고 개선 계획을 세워줘
+커버리지를 80%로 올리려면 어떤 테스트가 필요해?
+미테스트 코드 영역을 찾아서 테스트 템플릿을 만들어줘
+```
+
+## 출처
+Original skill from skills.cokac.com

.claude/skills/dead-code-auditor/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: ln-626-dead-code-auditor
+description: Dead code & legacy audit worker (L3). Checks unreachable code, unused imports/variables/functions, commented-out code, backward compatibility shims, deprecated patterns. Returns findings.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Dead Code Auditor (L3 Worker)
+
+Specialized worker auditing unused and unreachable code.
+
+## Purpose & Scope
+
+- **Worker in ln-620 coordinator pipeline**
+- Audit **dead code** (Category 9: Low Priority)
+- Find unused imports, variables, functions, commented-out code
+- Calculate compliance score (X/10)
+
+## Inputs (from Coordinator)
+
+Receives `contextStore` with tech stack, codebase root.
+
+## Workflow
+
+1) Parse context
+2) Run dead code detection (linters, grep)
+3) Collect findings
+4) Calculate score
+5) Return JSON
+
+## Audit Rules
+
+### 1. Unreachable Code
+**Detection:**
+- Linter rules: `no-unreachable` (ESLint)
+- Check code after `return`, `throw`, `break`
+
+**Severity:** MEDIUM
+
+### 2. Unused Imports/Variables/Functions
+**Detection:**
+- ESLint: `no-unused-vars`
+- TypeScript: `noUnusedLocals`, `noUnusedParameters`
+- Python: `flake8` with `F401`, `F841`
+
+**Severity:**
+- **MEDIUM:** Unused functions (dead weight)
+- **LOW:** Unused imports (cleanup needed)
+
+### 3. Commented-Out Code
+**Detection:**
+- Grep for `//.*{` or `/*.*function` patterns
+- Large comment blocks (>10 lines) with code syntax
+
+**Severity:** LOW
+
+**Recommendation:** Delete (git preserves history)
+
+### 4. Legacy Code & Backward Compatibility
+**What:** Backward compatibility shims, deprecated patterns, old code that should be removed
+
+**Detection:**
+- Renamed variables/functions with old aliases:
+  - Pattern: `const oldName = newName` or `export { newModule as oldModule }`
+  - Pattern: `function oldFunc() { return newFunc(); }` (wrapper for backward compatibility)
+- Deprecated exports/re-exports:
+  - Grep for `// DEPRECATED`, `@deprecated` JSDoc tags
+  - Pattern: `export.*as.*old.*` or `export.*legacy.*`
+- Conditional code for old versions:
+  - Pattern: `if.*legacy.*` or `if.*old.*version.*` or `isOldVersion ? oldFunc() : newFunc()`
+- Migration shims and adapters:
+  - Pattern: `migrate.*`, `Legacy.*Adapter`, `.*Shim`, `.*Compat`
+- Comment markers:
+  - Grep for `// backward compatibility`, `// legacy support`, `// TODO: remove in v`
+  - Grep for `// old implementation`, `// deprecated`, `// kept for backward`
+
+**Severity:**
+- **HIGH:** Backward compatibility shims in critical paths (auth, payment, core features)
+- **MEDIUM:** Deprecated exports still in use, migration code from >6 months ago
+- **LOW:** Recent migration code (<3 months), planned deprecation with clear removal timeline
+
+**Recommendation:**
+- Remove backward compatibility shims - breaking changes are acceptable when properly versioned
+- Delete old implementations - keep only the correct/new version
+- Remove deprecated exports - update consumers to use new API
+- Delete migration code after grace period (3-6 months)
+- Clean legacy support comments - git history preserves old implementations
+
+**Effort:**
+- **S:** Remove simple aliases, delete deprecated exports
+- **M:** Refactor code using old APIs to new APIs
+- **L:** Remove complex backward compatibility layer affecting multiple modules
+
+## Scoring Algorithm
+
+See `shared/references/audit_scoring.md` for unified formula and score interpretation.
+
+## Output Format
+
+```json
+{
+  "category": "Dead Code",
+  "score": 6,
+  "total_issues": 12,
+  "critical": 0,
+  "high": 2,
+  "medium": 3,
+  "low": 7,
+  "checks": [
+    {"id": "unreachable_code", "name": "Unreachable Code", "status": "passed", "details": "No unreachable code detected"},
+    {"id": "unused_exports", "name": "Unused Exports", "status": "failed", "details": "3 unused functions found"},
+    {"id": "commented_code", "name": "Commented Code", "status": "warning", "details": "7 blocks of commented code"},
+    {"id": "legacy_shims", "name": "Legacy Shims", "status": "failed", "details": "2 backward compatibility shims"}
+  ],
+  "findings": [
+    {
+      "severity": "MEDIUM",
+      "location": "src/utils/helpers.ts:45",
+      "issue": "Function 'formatDate' is never used",
+      "principle": "Code Maintainability / Clean Code",
+      "recommendation": "Remove unused function or export if needed elsewhere",
+      "effort": "S"
+    },
+    {
+      "severity": "HIGH",
+      "location": "src/api/v1/auth.ts:12-15",
+      "issue": "Backward compatibility shim for old password validation (6+ months old)",
+      "principle": "No Legacy Code / Clean Architecture",
+      "recommendation": "Remove old password validation, keep only new implementation. Update API version if breaking.",
+      "effort": "M"
+    }
+  ]
+}
+```
+
+## Reference Files
+
+- **Audit scoring formula:** `shared/references/audit_scoring.md`
+- **Audit output schema:** `shared/references/audit_output_schema.md`
+
+---
+**Version:** 3.0.0
+**Last Updated:** 2025-12-23

.claude/skills/dependencies-auditor/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: ln-625-dependencies-auditor
+description: "Dependencies audit worker (L3). Checks outdated packages, unused deps, reinvented wheels, vulnerability scan (CVE/CVSS). Supports mode: full | vulnerabilities_only."
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Dependencies & Reuse Auditor (L3 Worker)
+
+Specialized worker auditing dependency management, code reuse, and security vulnerabilities.
+
+## Purpose & Scope
+
+- **Worker in ln-620 coordinator pipeline** (full audit mode)
+- **Worker in ln-760 security-setup pipeline** (vulnerabilities_only mode)
+- Audit **dependencies and reuse** (Categories 7+8: Medium Priority)
+- Check outdated packages, unused deps, wheel reinvention, **CVE vulnerabilities**
+- Calculate compliance score (X/10)
+
+## Parameters
+
+| Param | Values | Default | Description |
+|-------|--------|---------|-------------|
+| mode | `full` / `vulnerabilities_only` | `full` | `full` = all 5 checks, `vulnerabilities_only` = only CVE scan |
+
+## Inputs (from Coordinator)
+
+Receives `contextStore` with tech stack, package manifest paths, codebase root.
+
+**From ln-620 (codebase-auditor):** mode=full (default)
+**From ln-760 (security-setup):** mode=vulnerabilities_only
+
+## Workflow
+
+1) Parse context + mode parameter
+2) Run dependency checks (based on mode)
+3) Collect findings
+4) Calculate score
+5) Return JSON
+
+---
+
+## Audit Rules (5 Checks)
+
+### 1. Outdated Packages
+**Mode:** full only
+
+**Detection:**
+- Run `npm outdated --json` (Node.js)
+- Run `pip list --outdated --format=json` (Python)
+- Run `cargo outdated --format=json` (Rust)
+
+**Severity:**
+- **HIGH:** Major version behind (security risk)
+- **MEDIUM:** Minor version behind
+- **LOW:** Patch version behind
+
+**Recommendation:** Update to latest version, test for breaking changes
+
+**Effort:** S-M (update version, run tests)
+
+### 2. Unused Dependencies
+**Mode:** full only
+
+**Detection:**
+- Parse package.json/requirements.txt
+- Grep codebase for `import`/`require` statements
+- Find dependencies never imported
+
+**Severity:**
+- **MEDIUM:** Unused production dependency (bloats bundle)
+- **LOW:** Unused dev dependency
+
+**Recommendation:** Remove from package manifest
+
+**Effort:** S (delete line, test)
+
+### 3. Available Features Not Used
+**Mode:** full only
+
+**Detection:**
+- Check for axios when native fetch available (Node 18+)
+- Check for lodash when Array methods sufficient
+- Check for moment when Date.toLocaleString sufficient
+
+**Severity:**
+- **MEDIUM:** Unnecessary dependency (increases bundle size)
+
+**Recommendation:** Use native alternative
+
+**Effort:** M (refactor code to use native API)
+
+### 4. Custom Implementations
+**Mode:** full only
+
+**Detection:**
+- Grep for custom sorting algorithms
+- Check for hand-rolled validation (vs validator.js)
+- Find custom date parsing (vs date-fns/dayjs)
+
+**Severity:**
+- **HIGH:** Custom crypto (security risk)
+- **MEDIUM:** Custom utilities with well-tested alternatives
+
+**Recommendation:** Replace with established library
+
+**Effort:** M (integrate library, replace calls)
+
+### 5. Vulnerability Scan (CVE/CVSS)
+**Mode:** full AND vulnerabilities_only
+
+**Detection:**
+- Detect ecosystems: npm, NuGet, pip, Go, Bundler, Cargo, Composer
+- Run audit commands per `references/vulnerability_commands.md`
+- Parse results with CVSS mapping per `shared/references/cvss_severity_mapping.md`
+
+**Severity:**
+- **CRITICAL:** CVSS 9.0-10.0 (immediate fix required)
+- **HIGH:** CVSS 7.0-8.9 (fix within 48h)
+- **MEDIUM:** CVSS 4.0-6.9 (fix within 1 week)
+- **LOW:** CVSS 0.1-3.9 (fix when convenient)
+
+**Fix Classification:**
+- Patch update (x.x.Y) → safe auto-fix
+- Minor update (x.Y.0) → usually safe
+- Major update (Y.0.0) → manual review required
+- No fix available → document and monitor
+
+**Recommendation:** Update to fixed version, verify lock file integrity
+
+**Effort:** S-L (depends on breaking changes)
+
+---
+
+## Scoring Algorithm
+
+See `shared/references/audit_scoring.md` for unified formula and score interpretation.
+
+**Note:** When mode=vulnerabilities_only, score based only on vulnerability findings.
+
+## Output Format
+
+```json
+{
+  "category": "Dependencies & Reuse",
+  "mode": "full",
+  "score": 7,
+  "total_issues": 12,
+  "critical": 1,
+  "high": 3,
+  "medium": 5,
+  "low": 3,
+  "checks": [
+    {"id": "outdated_packages", "name": "Outdated Packages", "status": "failed", "details": "2 packages behind major versions"},
+    {"id": "unused_deps", "name": "Unused Dependencies", "status": "warning", "details": "4 unused dev dependencies"},
+    {"id": "available_natives", "name": "Available Natives", "status": "passed", "details": "No unnecessary polyfills"},
+    {"id": "custom_implementations", "name": "Custom Implementations", "status": "warning", "details": "2 custom utilities found"},
+    {"id": "vulnerability_scan", "name": "Vulnerability Scan (CVE)", "status": "failed", "details": "1 critical, 2 high vulnerabilities"}
+  ],
+  "findings": [
+    {
+      "severity": "CRITICAL",
+      "location": "package.json",
+      "issue": "lodash@4.17.15 has CVE-2021-23337 (CVSS 7.2)",
+      "principle": "Security / Vulnerability Management",
+      "recommendation": "Update to lodash@4.17.21",
+      "effort": "S",
+      "fix_type": "patch"
+    },
+    {
+      "severity": "HIGH",
+      "location": "package.json:15",
+      "issue": "express v4.17.0 (current: v4.19.2, 2 major versions behind)",
+      "principle": "Dependency Management / Security Updates",
+      "recommendation": "Update to v4.19.2 for security fixes",
+      "effort": "M"
+    }
+  ]
+}
+```
+
+## Reference Files
+
+| File | Purpose |
+|------|---------|
+| `references/vulnerability_commands.md` | Ecosystem-specific audit commands |
+| `references/ci_integration_guide.md` | CI/CD integration guidance |
+| `shared/references/cvss_severity_mapping.md` | CVSS to severity level mapping |
+| `shared/references/audit_scoring.md` | Audit scoring formula |
+| `shared/references/audit_output_schema.md` | Audit output schema |
+
+---
+**Version:** 4.0.0
+**Last Updated:** 2026-02-05

.claude/skills/design-skill/SKILL.md

@@ -0,0 +1,949 @@
+---
+name: design-skill
+description: 프레젠테이션 슬라이드를 미려한 HTML로 디자인. 슬라이드 HTML 생성, 시각적 디자인, 레이아웃 구성이 필요할 때 사용.
+---
+
+# Design Skill - 프로페셔널 프레젠테이션 디자인 시스템
+
+최고 수준의 비즈니스 프레젠테이션을 위한 HTML 슬라이드 디자인 스킬입니다.
+미니멀하고 세련된 디자인, 전문적인 타이포그래피, 정교한 레이아웃을 제공합니다.
+
+---
+
+## 핵심 디자인 철학
+
+### 1. Less is More
+- 불필요한 장식 요소 제거
+- 콘텐츠가 주인공이 되는 디자인
+- 여백(Whitespace)을 적극 활용
+- 시각적 계층 구조 명확화
+
+### 2. 타이포그래피 중심 디자인
+- Pretendard를 기본 폰트로 사용
+- 폰트 크기 대비로 시각적 임팩트 생성
+- 자간과 행간의 섬세한 조절
+- 웨이트 변화로 강조점 표현
+
+### 3. 전략적 색상 사용
+- 제한된 색상 팔레트 (2-3색)
+- 모노톤 기반 + 포인트 컬러
+- 배경색으로 분위기 연출
+- 고대비로 가독성 확보
+
+---
+
+## 기본 설정
+
+### 슬라이드 크기 (16:9 기본)
+```html
+<body style="width: 720pt; height: 405pt;">
+```
+
+### 지원 비율
+| 비율 | 크기 | 용도 |
+|------|------|------|
+| 16:9 | 720pt × 405pt | 기본, 모니터/화면 |
+| 4:3 | 720pt × 540pt | 구형 프로젝터 |
+| 16:10 | 720pt × 450pt | 맥북 |
+
+### 기본 폰트 스택
+```css
+font-family: 'Pretendard', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+```
+
+### Pretendard 웹폰트 CDN
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css">
+```
+
+---
+
+## 타이포그래피 시스템
+
+### 폰트 크기 스케일
+| 용도 | 크기 | 웨이트 | 사용 예시 |
+|------|------|--------|----------|
+| Hero Title | 72-96pt | 700-800 | 표지 메인 타이틀 |
+| Section Title | 48-60pt | 700 | 섹션 구분 제목 |
+| Slide Title | 32-40pt | 600-700 | 슬라이드 제목 |
+| Subtitle | 20-24pt | 500 | 부제목, 설명 |
+| Body | 16-20pt | 400 | 본문 텍스트 |
+| Caption | 12-14pt | 400 | 캡션, 출처 |
+| Label | 10-12pt | 500-600 | 뱃지, 태그 |
+
+### 자간 설정 (letter-spacing)
+```css
+/* 대형 제목: 타이트하게 */
+letter-spacing: -0.02em;
+
+/* 중형 제목 */
+letter-spacing: -0.01em;
+
+/* 본문: 기본 */
+letter-spacing: 0;
+
+/* 캡션, 레이블: 약간 넓게 */
+letter-spacing: 0.02em;
+```
+
+### 행간 설정 (line-height)
+```css
+/* 제목 */
+line-height: 1.2;
+
+/* 본문 */
+line-height: 1.6 - 1.8;
+
+/* 한 줄 텍스트 */
+line-height: 1;
+```
+
+---
+
+## 색상 팔레트 시스템
+
+### 1. Executive Minimal (기본 권장)
+세련된 비즈니스 프레젠테이션용
+```css
+--bg-primary: #f5f5f0;      /* 웜 화이트 배경 */
+--bg-secondary: #e8e8e3;    /* 서브 배경 */
+--bg-dark: #1a1a1a;         /* 다크 배경 */
+--text-primary: #1a1a1a;    /* 메인 텍스트 */
+--text-secondary: #666666;  /* 보조 텍스트 */
+--text-light: #999999;      /* 약한 텍스트 */
+--accent: #1a1a1a;          /* 강조 (검정) */
+--border: #d4d4d0;          /* 테두리 */
+```
+
+### 2. Sage Professional
+차분하고 신뢰감 있는 톤
+```css
+--bg-primary: #b8c4b8;      /* 세이지 그린 배경 */
+--bg-secondary: #a3b0a3;    /* 짙은 세이지 */
+--bg-light: #f8faf8;        /* 밝은 배경 */
+--text-primary: #1a1a1a;    /* 메인 텍스트 */
+--text-secondary: #3d3d3d;  /* 보조 텍스트 */
+--accent: #2d2d2d;          /* 강조 */
+--border: #9aa89a;          /* 테두리 */
+```
+
+### 3. Modern Dark
+임팩트 있는 다크 테마
+```css
+--bg-primary: #0f0f0f;      /* 순수 다크 */
+--bg-secondary: #1a1a1a;    /* 카드 배경 */
+--bg-elevated: #252525;     /* 강조 영역 */
+--text-primary: #ffffff;    /* 메인 텍스트 */
+--text-secondary: #b0b0b0;  /* 보조 텍스트 */
+--accent: #ffffff;          /* 강조 (화이트) */
+--border: #333333;          /* 테두리 */
+```
+
+### 4. Corporate Blue
+전통적 비즈니스 톤
+```css
+--bg-primary: #ffffff;      /* 화이트 배경 */
+--bg-secondary: #f7f9fc;    /* 밝은 블루 그레이 */
+--text-primary: #1e2a3a;    /* 다크 네이비 */
+--text-secondary: #5a6b7d;  /* 블루 그레이 */
+--accent: #2563eb;          /* 블루 강조 */
+--border: #e2e8f0;          /* 테두리 */
+```
+
+### 5. Warm Neutral
+따뜻하고 친근한 톤
+```css
+--bg-primary: #faf8f5;      /* 크림 화이트 */
+--bg-secondary: #f0ebe3;    /* 웜 베이지 */
+--text-primary: #2d2a26;    /* 다크 브라운 */
+--text-secondary: #6b6560;  /* 미디움 브라운 */
+--accent: #c45a3b;          /* 테라코타 */
+--border: #ddd8d0;          /* 테두리 */
+```
+
+---
+
+## 레이아웃 시스템
+
+### 여백 기준 (padding/margin)
+```css
+/* 슬라이드 전체 여백 */
+padding: 48pt;
+
+/* 섹션 간 여백 */
+gap: 32pt;
+
+/* 요소 간 여백 */
+gap: 16pt;
+
+/* 텍스트 블록 내 여백 */
+gap: 8pt;
+```
+
+### 그리드 시스템
+```css
+/* 2단 레이아웃 */
+display: grid;
+grid-template-columns: 1fr 1fr;
+gap: 32pt;
+
+/* 3단 레이아웃 */
+grid-template-columns: repeat(3, 1fr);
+
+/* 비대칭 레이아웃 (40:60) */
+grid-template-columns: 2fr 3fr;
+
+/* 비대칭 레이아웃 (30:70) */
+grid-template-columns: 1fr 2.3fr;
+```
+
+---
+
+## 디자인 컴포넌트
+
+> **html2pptx 호환성 주의**: 텍스트 요소(`<p>`, `<h1>`-`<h6>`)에 직접 border, background, shadow를 적용하면 변환 오류가 발생합니다. 반드시 `<div>`로 감싸서 스타일을 적용하세요.
+
+### 1. 뱃지/태그
+```html
+<!-- html2pptx 호환 버전 -->
+<div style="
+  display: inline-block;
+  padding: 6pt 14pt;
+  border: 1px solid #1a1a1a;
+  border-radius: 20pt;
+">
+  <p style="font-size: 10pt; font-weight: 500; letter-spacing: 0.02em; text-transform: uppercase;">PRESENTATION</p>
+</div>
+```
+
+### 2. 섹션 넘버
+```html
+<!-- html2pptx 호환 버전 -->
+<div style="
+  display: inline-block;
+  padding: 4pt 12pt;
+  background: #1a1a1a;
+  border-radius: 4pt;
+">
+  <p style="color: #ffffff; font-size: 10pt; font-weight: 600;">SECTION 1</p>
+</div>
+```
+
+### 3. 로고 영역
+```html
+<div style="display: flex; align-items: center; gap: 8pt;">
+  <div style="
+    width: 20pt;
+    height: 20pt;
+    background: #1a1a1a;
+    border-radius: 4pt;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  ">
+    <p style="color: #fff; font-size: 12pt;">*</p>
+  </div>
+  <p style="font-size: 12pt; font-weight: 600;">LogoName</p>
+</div>
+```
+
+### 4. 아이콘 버튼
+```html
+<div style="
+  width: 32pt;
+  height: 32pt;
+  border: 1px solid #1a1a1a;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+">
+  <p style="font-size: 14pt;">↗</p>
+</div>
+```
+
+### 5. 구분선
+```html
+<div style="
+  width: 100%;
+  height: 1pt;
+  background: #d4d4d0;
+"></div>
+```
+
+### 6. 정보 그리드
+```html
+<div style="display: flex; gap: 48pt;">
+  <div>
+    <p style="font-size: 10pt; color: #999; margin-bottom: 4pt;">Contact</p>
+    <p style="font-size: 12pt; font-weight: 500;">334556774</p>
+  </div>
+  <div>
+    <p style="font-size: 10pt; color: #999; margin-bottom: 4pt;">Date</p>
+    <p style="font-size: 12pt; font-weight: 500;">March 2025</p>
+  </div>
+</div>
+```
+
+---
+
+## 슬라이드 템플릿
+
+### 1. 표지 슬라이드 (Cover)
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      width: 720pt;
+      height: 405pt;
+      font-family: 'Pretendard', sans-serif;
+      background: #f5f5f0;
+      padding: 32pt 48pt;
+      display: flex;
+      flex-direction: column;
+    }
+  </style>
+</head>
+<body>
+  <!-- 헤더 (html2pptx 호환) -->
+  <div style="display: flex; justify-content: space-between; align-items: center;">
+    <div style="display: flex; align-items: center; gap: 16pt;">
+      <div style="display: flex; align-items: center; gap: 8pt;">
+        <div style="width: 18pt; height: 18pt; background: #1a1a1a; border-radius: 3pt; display: flex; align-items: center; justify-content: center;">
+          <p style="color: #fff; font-size: 10pt;">*</p>
+        </div>
+        <p style="font-size: 11pt; font-weight: 600; color: #1a1a1a;">LogoName</p>
+      </div>
+      <div style="display: inline-block; padding: 4pt 10pt; border: 1px solid #1a1a1a; border-radius: 12pt;">
+        <p style="font-size: 9pt; font-weight: 500; color: #1a1a1a;">PRESENTATION</p>
+      </div>
+    </div>
+    <div style="display: flex; align-items: center; gap: 8pt;">
+      <div style="display: inline-block; padding: 4pt 10pt; border: 1px solid #1a1a1a; border-radius: 12pt;">
+        <p style="font-size: 9pt; font-weight: 500; color: #1a1a1a;">OUR PROJECT</p>
+      </div>
+      <div style="width: 28pt; height: 28pt; border: 1px solid #1a1a1a; border-radius: 50%; display: flex; align-items: center; justify-content: center;">
+        <p style="font-size: 12pt; color: #1a1a1a;">↘</p>
+      </div>
+    </div>
+  </div>
+
+  <!-- 메인 타이틀 -->
+  <div style="flex: 1; display: flex; flex-direction: column; justify-content: center;">
+    <h1 style="font-size: 72pt; font-weight: 500; color: #1a1a1a; letter-spacing: -0.02em; line-height: 1.1;">
+      Business Deck
+    </h1>
+    <p style="font-size: 14pt; color: #666; margin-top: 24pt;">
+      <span style="color: #999;">Presented by</span>  <span style="font-weight: 500; color: #1a1a1a;">Luna Martinez</span>
+    </p>
+  </div>
+
+  <!-- 푸터 정보 -->
+  <div style="display: flex; gap: 64pt;">
+    <div>
+      <p style="font-size: 9pt; color: #999; margin-bottom: 4pt;">Contact</p>
+      <p style="font-size: 11pt; font-weight: 500; color: #1a1a1a;">334556774</p>
+    </div>
+    <div>
+      <p style="font-size: 9pt; color: #999; margin-bottom: 4pt;">Date</p>
+      <p style="font-size: 11pt; font-weight: 500; color: #1a1a1a;">March 2025</p>
+    </div>
+    <div>
+      <p style="font-size: 9pt; color: #999; margin-bottom: 4pt;">Website</p>
+      <p style="font-size: 11pt; font-weight: 500; color: #1a1a1a;">www.yourwebsite.com</p>
+    </div>
+  </div>
+</body>
+</html>
+```
+
+### 2. 목차 슬라이드 (Contents)
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      width: 720pt;
+      height: 405pt;
+      font-family: 'Pretendard', sans-serif;
+      background: #b8c4b8;
+      padding: 48pt;
+      display: grid;
+      grid-template-columns: 1fr 1.8fr;
+      gap: 48pt;
+    }
+  </style>
+</head>
+<body>
+  <!-- 왼쪽: 타이틀 -->
+  <div style="display: flex; flex-direction: column; justify-content: flex-end;">
+    <p style="font-size: 9pt; color: #3d3d3d; margin-bottom: 16pt;">©2025 YOUR BRAND. ALL RIGHTS RESERVED.</p>
+    <h1 style="font-size: 56pt; font-weight: 500; color: #1a1a1a; letter-spacing: -0.02em; line-height: 1.1;">
+      Our<br>Contents
+    </h1>
+    <div style="width: 32pt; height: 32pt; border: 1px solid #1a1a1a; border-radius: 50%; display: flex; align-items: center; justify-content: center; margin-top: 24pt;">
+      <p style="font-size: 14pt; color: #1a1a1a;">↗</p>
+    </div>
+  </div>
+
+  <!-- 오른쪽: 목차 리스트 -->
+  <div style="display: flex; flex-direction: column; justify-content: center; gap: 16pt;">
+    <div style="display: flex; align-items: center; gap: 16pt; padding: 12pt 0; border-bottom: 1px solid rgba(0,0,0,0.1);">
+      <div style="display: inline-block; padding: 4pt 10pt; background: #1a1a1a; border-radius: 4pt;"><p style="color: #fff; font-size: 8pt; font-weight: 600;">SECTION 1</p></div>
+      <p style="flex: 1; font-size: 14pt; font-weight: 500; color: #1a1a1a;">SECTION TITLE</p>
+      <p style="font-size: 14pt; color: #666;">(1)</p>
+    </div>
+    <div style="display: flex; align-items: center; gap: 16pt; padding: 12pt 0; border-bottom: 1px solid rgba(0,0,0,0.1);">
+      <div style="display: inline-block; padding: 4pt 10pt; background: #1a1a1a; border-radius: 4pt;"><p style="color: #fff; font-size: 8pt; font-weight: 600;">SECTION 2</p></div>
+      <p style="flex: 1; font-size: 14pt; font-weight: 500; color: #1a1a1a;">SECTION TITLE</p>
+      <p style="font-size: 14pt; color: #666;">(2)</p>
+    </div>
+    <div style="display: flex; align-items: center; gap: 16pt; padding: 12pt 0; border-bottom: 1px solid rgba(0,0,0,0.1);">
+      <div style="display: inline-block; padding: 4pt 10pt; background: #1a1a1a; border-radius: 4pt;"><p style="color: #fff; font-size: 8pt; font-weight: 600;">SECTION 3</p></div>
+      <p style="flex: 1; font-size: 14pt; font-weight: 500; color: #1a1a1a;">SECTION TITLE</p>
+      <p style="font-size: 14pt; color: #666;">(3)</p>
+    </div>
+    <div style="display: flex; align-items: center; gap: 16pt; padding: 12pt 0; border-bottom: 1px solid rgba(0,0,0,0.1);">
+      <div style="display: inline-block; padding: 4pt 10pt; background: #1a1a1a; border-radius: 4pt;"><p style="color: #fff; font-size: 8pt; font-weight: 600;">SECTION 4</p></div>
+      <p style="flex: 1; font-size: 14pt; font-weight: 500; color: #1a1a1a;">SECTION TITLE</p>
+      <p style="font-size: 14pt; color: #666;">(4)</p>
+    </div>
+    <div style="display: flex; align-items: center; gap: 16pt; padding: 12pt 0;">
+      <div style="display: inline-block; padding: 4pt 10pt; background: #1a1a1a; border-radius: 4pt;"><p style="color: #fff; font-size: 8pt; font-weight: 600;">SECTION 5</p></div>
+      <p style="flex: 1; font-size: 14pt; font-weight: 500; color: #1a1a1a;">SECTION TITLE</p>
+      <p style="font-size: 14pt; color: #666;">(5)</p>
+    </div>
+  </div>
+</body>
+</html>
+```
+
+### 3. 섹션 구분 슬라이드 (Section Divider)
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      width: 720pt;
+      height: 405pt;
+      font-family: 'Pretendard', sans-serif;
+      background: #1a1a1a;
+      padding: 48pt;
+      display: flex;
+      flex-direction: column;
+      justify-content: space-between;
+    }
+  </style>
+</head>
+<body>
+  <!-- 상단 섹션 정보 -->
+  <div style="display: flex; justify-content: space-between; align-items: flex-start;">
+    <div>
+      <div style="display: inline-block; padding: 4pt 10pt; background: #fff; border-radius: 4pt;"><p style="color: #1a1a1a; font-size: 8pt; font-weight: 600;">SECTION 1</p></div>
+    </div>
+    <p style="font-size: 9pt; color: #666;">©2025 YOUR BRAND</p>
+  </div>
+
+  <!-- 메인 타이틀 -->
+  <div>
+    <h1 style="font-size: 64pt; font-weight: 500; color: #ffffff; letter-spacing: -0.02em; line-height: 1.1;">
+      Introduction
+    </h1>
+    <p style="font-size: 16pt; color: #888; margin-top: 16pt; max-width: 400pt; line-height: 1.6;">
+      Brief description of what this section covers and why it matters.
+    </p>
+  </div>
+
+  <!-- 페이지 번호 -->
+  <div style="display: flex; justify-content: flex-end;">
+    <p style="font-size: 10pt; color: #666;">01</p>
+  </div>
+</body>
+</html>
+```
+
+### 4. 콘텐츠 슬라이드 (Content)
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      width: 720pt;
+      height: 405pt;
+      font-family: 'Pretendard', sans-serif;
+      background: #ffffff;
+      padding: 40pt 48pt;
+      display: flex;
+      flex-direction: column;
+    }
+  </style>
+</head>
+<body>
+  <!-- 헤더 -->
+  <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 32pt;">
+    <div style="display: flex; align-items: center; gap: 12pt;">
+      <div style="display: inline-block; padding: 4pt 10pt; background: #1a1a1a; border-radius: 4pt;"><p style="color: #fff; font-size: 8pt; font-weight: 600;">SECTION 1</p></div>
+      <h2 style="font-size: 24pt; font-weight: 600; color: #1a1a1a;">Main Topic</h2>
+    </div>
+    <p style="font-size: 10pt; color: #999;">02</p>
+  </div>
+
+  <!-- 콘텐츠 영역 -->
+  <div style="flex: 1; display: grid; grid-template-columns: 1fr 1fr; gap: 32pt;">
+    <div>
+      <h3 style="font-size: 18pt; font-weight: 600; color: #1a1a1a; margin-bottom: 16pt;">Key Point One</h3>
+      <p style="font-size: 13pt; color: #666; line-height: 1.7;">
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore.
+      </p>
+    </div>
+    <div>
+      <h3 style="font-size: 18pt; font-weight: 600; color: #1a1a1a; margin-bottom: 16pt;">Key Point Two</h3>
+      <p style="font-size: 13pt; color: #666; line-height: 1.7;">
+        Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip.
+      </p>
+    </div>
+  </div>
+
+  <!-- 푸터 -->
+  <div style="display: flex; justify-content: space-between; align-items: center; padding-top: 16pt; border-top: 1px solid #eee;">
+    <p style="font-size: 9pt; color: #999;">www.yourwebsite.com</p>
+    <p style="font-size: 9pt; color: #999;">©2025 YOUR BRAND</p>
+  </div>
+</body>
+</html>
+```
+
+### 5. 통계/데이터 슬라이드 (Statistics)
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      width: 720pt;
+      height: 405pt;
+      font-family: 'Pretendard', sans-serif;
+      background: #f5f5f0;
+      padding: 40pt 48pt;
+      display: flex;
+      flex-direction: column;
+    }
+  </style>
+</head>
+<body>
+  <!-- 헤더 -->
+  <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 32pt;">
+    <h2 style="font-size: 28pt; font-weight: 600; color: #1a1a1a;">Key Metrics</h2>
+    <p style="font-size: 10pt; color: #999;">03</p>
+  </div>
+
+  <!-- 통계 카드 그리드 -->
+  <div style="flex: 1; display: grid; grid-template-columns: repeat(3, 1fr); gap: 24pt;">
+    <div style="background: #1a1a1a; border-radius: 12pt; padding: 28pt; display: flex; flex-direction: column; justify-content: space-between;">
+      <p style="font-size: 10pt; color: #888; text-transform: uppercase; letter-spacing: 0.05em;">Revenue Growth</p>
+      <div>
+        <p style="font-size: 48pt; font-weight: 600; color: #ffffff; letter-spacing: -0.02em;">85%</p>
+        <p style="font-size: 11pt; color: #666; margin-top: 8pt;">Year over year</p>
+      </div>
+    </div>
+    <div style="background: #ffffff; border-radius: 12pt; padding: 28pt; display: flex; flex-direction: column; justify-content: space-between; border: 1px solid #e5e5e0;">
+      <p style="font-size: 10pt; color: #888; text-transform: uppercase; letter-spacing: 0.05em;">Active Users</p>
+      <div>
+        <p style="font-size: 48pt; font-weight: 600; color: #1a1a1a; letter-spacing: -0.02em;">2.4M</p>
+        <p style="font-size: 11pt; color: #888; margin-top: 8pt;">+340K this quarter</p>
+      </div>
+    </div>
+    <div style="background: #ffffff; border-radius: 12pt; padding: 28pt; display: flex; flex-direction: column; justify-content: space-between; border: 1px solid #e5e5e0;">
+      <p style="font-size: 10pt; color: #888; text-transform: uppercase; letter-spacing: 0.05em;">Customer Satisfaction</p>
+      <div>
+        <p style="font-size: 48pt; font-weight: 600; color: #1a1a1a; letter-spacing: -0.02em;">4.9</p>
+        <p style="font-size: 11pt; color: #888; margin-top: 8pt;">Out of 5.0 rating</p>
+      </div>
+    </div>
+  </div>
+
+  <!-- 푸터 -->
+  <div style="display: flex; justify-content: flex-end; padding-top: 16pt;">
+    <p style="font-size: 9pt; color: #999;">Source: Internal Analytics 2025</p>
+  </div>
+</body>
+</html>
+```
+
+### 6. 이미지 + 텍스트 슬라이드 (Split Layout)
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      width: 720pt;
+      height: 405pt;
+      font-family: 'Pretendard', sans-serif;
+      background: #ffffff;
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+    }
+  </style>
+</head>
+<body>
+  <!-- 이미지 영역 -->
+  <div style="background: #e5e5e0; display: flex; align-items: center; justify-content: center; position: relative;">
+    <div data-image-placeholder style="width: 100%; height: 100%; background: linear-gradient(135deg, #d0d0c8 0%, #b8b8b0 100%);"></div>
+    <p style="position: absolute; bottom: 16pt; left: 16pt; font-size: 9pt; color: #666;">©2025 YOUR BRAND</p>
+  </div>
+
+  <!-- 텍스트 영역 -->
+  <div style="padding: 48pt; display: flex; flex-direction: column; justify-content: center;">
+    <p style="display: inline-block; padding: 4pt 10pt; background: #1a1a1a; color: #fff; border-radius: 4pt; font-size: 8pt; font-weight: 600; margin-bottom: 24pt; align-self: flex-start;">FEATURE</p>
+    <h2 style="font-size: 32pt; font-weight: 600; color: #1a1a1a; letter-spacing: -0.01em; line-height: 1.2; margin-bottom: 20pt;">
+      Transform Your Business
+    </h2>
+    <p style="font-size: 14pt; color: #666; line-height: 1.7;">
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+    </p>
+    <div style="margin-top: 32pt; display: flex; align-items: center; gap: 12pt;">
+      <p style="font-size: 12pt; font-weight: 500; color: #1a1a1a;">Learn more</p>
+      <div style="width: 28pt; height: 28pt; border: 1px solid #1a1a1a; border-radius: 50%; display: flex; align-items: center; justify-content: center;">
+        <p style="font-size: 12pt; color: #1a1a1a;">→</p>
+      </div>
+    </div>
+  </div>
+</body>
+</html>
+```
+
+### 7. 팀 소개 슬라이드 (Team)
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      width: 720pt;
+      height: 405pt;
+      font-family: 'Pretendard', sans-serif;
+      background: #f5f5f0;
+      padding: 40pt 48pt;
+      display: flex;
+      flex-direction: column;
+    }
+  </style>
+</head>
+<body>
+  <!-- 헤더 -->
+  <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 32pt;">
+    <h2 style="font-size: 28pt; font-weight: 600; color: #1a1a1a;">Our Team</h2>
+    <p style="font-size: 10pt; color: #999;">05</p>
+  </div>
+
+  <!-- 팀원 그리드 -->
+  <div style="flex: 1; display: grid; grid-template-columns: repeat(4, 1fr); gap: 20pt;">
+    <div style="text-align: center;">
+      <div style="width: 100%; aspect-ratio: 1; background: #d0d0c8; border-radius: 8pt; margin-bottom: 12pt;"></div>
+      <p style="font-size: 13pt; font-weight: 600; color: #1a1a1a;">John Smith</p>
+      <p style="font-size: 10pt; color: #888; margin-top: 4pt;">CEO & Founder</p>
+    </div>
+    <div style="text-align: center;">
+      <div style="width: 100%; aspect-ratio: 1; background: #d0d0c8; border-radius: 8pt; margin-bottom: 12pt;"></div>
+      <p style="font-size: 13pt; font-weight: 600; color: #1a1a1a;">Sarah Johnson</p>
+      <p style="font-size: 10pt; color: #888; margin-top: 4pt;">CTO</p>
+    </div>
+    <div style="text-align: center;">
+      <div style="width: 100%; aspect-ratio: 1; background: #d0d0c8; border-radius: 8pt; margin-bottom: 12pt;"></div>
+      <p style="font-size: 13pt; font-weight: 600; color: #1a1a1a;">Mike Chen</p>
+      <p style="font-size: 10pt; color: #888; margin-top: 4pt;">Design Lead</p>
+    </div>
+    <div style="text-align: center;">
+      <div style="width: 100%; aspect-ratio: 1; background: #d0d0c8; border-radius: 8pt; margin-bottom: 12pt;"></div>
+      <p style="font-size: 13pt; font-weight: 600; color: #1a1a1a;">Emily Davis</p>
+      <p style="font-size: 10pt; color: #888; margin-top: 4pt;">Marketing</p>
+    </div>
+  </div>
+</body>
+</html>
+```
+
+### 8. 인용문 슬라이드 (Quote)
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      width: 720pt;
+      height: 405pt;
+      font-family: 'Pretendard', sans-serif;
+      background: #1a1a1a;
+      padding: 64pt;
+      display: flex;
+      flex-direction: column;
+      justify-content: center;
+      align-items: center;
+      text-align: center;
+    }
+  </style>
+</head>
+<body>
+  <p style="font-size: 48pt; color: #444; margin-bottom: 24pt;">"</p>
+  <h2 style="font-size: 28pt; font-weight: 400; color: #ffffff; letter-spacing: -0.01em; line-height: 1.5; max-width: 540pt;">
+    The best way to predict the future is to create it.
+  </h2>
+  <div style="margin-top: 40pt;">
+    <p style="font-size: 13pt; font-weight: 500; color: #ffffff;">Peter Drucker</p>
+    <p style="font-size: 11pt; color: #666; margin-top: 4pt;">Management Consultant</p>
+  </div>
+</body>
+</html>
+```
+
+### 9. 타임라인 슬라이드 (Timeline)
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      width: 720pt;
+      height: 405pt;
+      font-family: 'Pretendard', sans-serif;
+      background: #ffffff;
+      padding: 40pt 48pt;
+      display: flex;
+      flex-direction: column;
+    }
+  </style>
+</head>
+<body>
+  <!-- 헤더 -->
+  <div style="margin-bottom: 32pt;">
+    <h2 style="font-size: 28pt; font-weight: 600; color: #1a1a1a;">Our Journey</h2>
+  </div>
+
+  <!-- 타임라인 -->
+  <div style="flex: 1; display: flex; align-items: center;">
+    <div style="display: flex; width: 100%; justify-content: space-between; position: relative;">
+      <!-- 연결선 -->
+      <div style="position: absolute; top: 12pt; left: 40pt; right: 40pt; height: 2pt; background: #e5e5e0;"></div>
+
+      <!-- 타임라인 아이템들 -->
+      <div style="text-align: center; z-index: 1;">
+        <div style="width: 24pt; height: 24pt; background: #1a1a1a; border-radius: 50%; margin: 0 auto 16pt;"></div>
+        <p style="font-size: 18pt; font-weight: 600; color: #1a1a1a;">2020</p>
+        <p style="font-size: 11pt; color: #888; margin-top: 8pt; max-width: 100pt;">Company Founded</p>
+      </div>
+      <div style="text-align: center; z-index: 1;">
+        <div style="width: 24pt; height: 24pt; background: #1a1a1a; border-radius: 50%; margin: 0 auto 16pt;"></div>
+        <p style="font-size: 18pt; font-weight: 600; color: #1a1a1a;">2021</p>
+        <p style="font-size: 11pt; color: #888; margin-top: 8pt; max-width: 100pt;">First Product Launch</p>
+      </div>
+      <div style="text-align: center; z-index: 1;">
+        <div style="width: 24pt; height: 24pt; background: #1a1a1a; border-radius: 50%; margin: 0 auto 16pt;"></div>
+        <p style="font-size: 18pt; font-weight: 600; color: #1a1a1a;">2023</p>
+        <p style="font-size: 11pt; color: #888; margin-top: 8pt; max-width: 100pt;">Series A Funding</p>
+      </div>
+      <div style="text-align: center; z-index: 1;">
+        <div style="width: 24pt; height: 24pt; background: #1a1a1a; border-radius: 50%; margin: 0 auto 16pt;"></div>
+        <p style="font-size: 18pt; font-weight: 600; color: #1a1a1a;">2025</p>
+        <p style="font-size: 11pt; color: #888; margin-top: 8pt; max-width: 100pt;">Global Expansion</p>
+      </div>
+    </div>
+  </div>
+
+  <!-- 푸터 -->
+  <div style="display: flex; justify-content: flex-end; padding-top: 16pt;">
+    <p style="font-size: 10pt; color: #999;">06</p>
+  </div>
+</body>
+</html>
+```
+
+### 10. 마무리 슬라이드 (Closing)
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      width: 720pt;
+      height: 405pt;
+      font-family: 'Pretendard', sans-serif;
+      background: #1a1a1a;
+      padding: 48pt;
+      display: flex;
+      flex-direction: column;
+      justify-content: space-between;
+    }
+  </style>
+</head>
+<body>
+  <!-- 로고 -->
+  <div style="display: flex; align-items: center; gap: 8pt;">
+    <div style="width: 20pt; height: 20pt; background: #fff; border-radius: 4pt; display: flex; align-items: center; justify-content: center;">
+      <p style="color: #1a1a1a; font-size: 12pt;">*</p>
+    </div>
+    <p style="font-size: 12pt; font-weight: 600; color: #ffffff;">LogoName</p>
+  </div>
+
+  <!-- 메인 메시지 -->
+  <div>
+    <h1 style="font-size: 56pt; font-weight: 500; color: #ffffff; letter-spacing: -0.02em; line-height: 1.1;">
+      Thank You
+    </h1>
+    <p style="font-size: 16pt; color: #888; margin-top: 16pt;">
+      Questions? Let's discuss.
+    </p>
+  </div>
+
+  <!-- 연락처 정보 -->
+  <div style="display: flex; gap: 64pt;">
+    <div>
+      <p style="font-size: 9pt; color: #666; margin-bottom: 4pt;">Email</p>
+      <p style="font-size: 12pt; font-weight: 500; color: #ffffff;">hello@company.com</p>
+    </div>
+    <div>
+      <p style="font-size: 9pt; color: #666; margin-bottom: 4pt;">Phone</p>
+      <p style="font-size: 12pt; font-weight: 500; color: #ffffff;">+82 10-1234-5678</p>
+    </div>
+    <div>
+      <p style="font-size: 9pt; color: #666; margin-bottom: 4pt;">Website</p>
+      <p style="font-size: 12pt; font-weight: 500; color: #ffffff;">www.company.com</p>
+    </div>
+  </div>
+</body>
+</html>
+```
+
+---
+
+## 고급 디자인 패턴
+
+### 비대칭 레이아웃
+시선을 끄는 독창적인 구성
+```css
+/* 황금비율 기반 */
+grid-template-columns: 1fr 1.618fr;
+
+/* 극단적 비대칭 */
+grid-template-columns: 1fr 3fr;
+```
+
+### 오버레이 텍스트
+이미지 위 텍스트 배치
+```html
+<div style="position: relative;">
+  <div style="position: absolute; inset: 0; background: rgba(0,0,0,0.5);"></div>
+  <div style="position: relative; z-index: 1;">
+    <h2 style="color: #fff;">Overlay Text</h2>
+  </div>
+</div>
+```
+
+### 그라데이션 오버레이
+```html
+<div style="
+  background: linear-gradient(to right, #1a1a1a 0%, transparent 60%);
+  position: absolute;
+  inset: 0;
+"></div>
+```
+
+### 카드 스타일
+```html
+<div style="
+  background: #ffffff;
+  border-radius: 12pt;
+  padding: 24pt;
+  box-shadow: 0 2pt 8pt rgba(0,0,0,0.08);
+"></div>
+```
+
+---
+
+## 텍스트 사용 규칙
+
+### 필수 태그
+```html
+<!-- 모든 텍스트는 반드시 다음 태그 안에 -->
+<p>, <h1>-<h6>, <ul>, <ol>, <li>
+
+<!-- 금지 - PowerPoint에서 무시됨 -->
+<div>텍스트</div>
+<span>텍스트</span>
+```
+
+### 권장 사용법
+```html
+<!-- 좋은 예 -->
+<h1 style="...">제목</h1>
+<p style="...">본문 텍스트</p>
+
+<!-- 나쁜 예 -->
+<div style="...">텍스트 직접 입력</div>
+```
+
+---
+
+## 출력 및 파일 구조
+
+### 파일 저장 규칙
+```
+slides/
+├── slide-01.html  (표지)
+├── slide-02.html  (목차)
+├── slide-03.html  (섹션 구분)
+├── slide-04.html  (내용)
+├── ...
+└── slide-XX.html  (마무리)
+```
+
+### 파일 명명 규칙
+- 2자리 숫자 사용: `slide-01.html`, `slide-02.html`
+- 순서대로 명명
+- 특수문자, 공백 사용 금지
+
+---
+
+## 워크플로우
+
+1. **분석**: `slide-outline.md` 읽고 콘텐츠 파악
+2. **테마 결정**: 색상 팔레트, 전체적인 무드 선택
+3. **구조 설계**: 슬라이드별 레이아웃 타입 결정
+4. **디자인 실행**: 각 슬라이드 HTML 생성
+5. **일관성 검토**: 전체 프레젠테이션의 통일성 확인
+6. **저장**: `slides/` 디렉토리에 파일 저장
+
+---
+
+## 주의사항
+
+1. **CSS 그라데이션**: PowerPoint 변환 시 지원 안됨 - 배경 이미지로 대체
+2. **웹폰트**: Pretendard CDN 링크 항상 포함
+3. **이미지 경로**: 절대 경로 또는 URL 사용
+4. **호환성**: 모든 색상에 # 포함
+5. **텍스트 규칙**: div/span에 직접 텍스트 금지

.claude/skills/differential-review/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: differential-review
+description: >
+  Performs security-focused differential review of code changes (PRs, commits, diffs).
+  Adapts analysis depth to codebase size, uses git history for context, calculates
+  blast radius, checks test coverage, and generates comprehensive markdown reports.
+  Automatically detects and prevents security regressions.
+allowed-tools:
+  - Read
+  - Write
+  - Grep
+  - Glob
+  - Bash
+---
+
+# Differential Security Review
+
+Security-focused code review for PRs, commits, and diffs.
+
+## Core Principles
+
+1. **Risk-First**: Focus on auth, crypto, value transfer, external calls
+2. **Evidence-Based**: Every finding backed by git history, line numbers, attack scenarios
+3. **Adaptive**: Scale to codebase size (SMALL/MEDIUM/LARGE)
+4. **Honest**: Explicitly state coverage limits and confidence level
+5. **Output-Driven**: Always generate comprehensive markdown report file
+
+---
+
+## Rationalizations (Do Not Skip)
+
+| Rationalization | Why It's Wrong | Required Action |
+|-----------------|----------------|-----------------|
+| "Small PR, quick review" | Heartbleed was 2 lines | Classify by RISK, not size |
+| "I know this codebase" | Familiarity breeds blind spots | Build explicit baseline context |
+| "Git history takes too long" | History reveals regressions | Never skip Phase 1 |
+| "Blast radius is obvious" | You'll miss transitive callers | Calculate quantitatively |
+| "No tests = not my problem" | Missing tests = elevated risk rating | Flag in report, elevate severity |
+| "Just a refactor, no security impact" | Refactors break invariants | Analyze as HIGH until proven LOW |
+| "I'll explain verbally" | No artifact = findings lost | Always write report |
+
+---
+
+## Quick Reference
+
+### Codebase Size Strategy
+
+| Codebase Size | Strategy | Approach |
+|---------------|----------|----------|
+| SMALL (<20 files) | DEEP | Read all deps, full git blame |
+| MEDIUM (20-200) | FOCUSED | 1-hop deps, priority files |
+| LARGE (200+) | SURGICAL | Critical paths only |
+
+### Risk Level Triggers
+
+| Risk Level | Triggers |
+|------------|----------|
+| HIGH | Auth, crypto, external calls, value transfer, validation removal |
+| MEDIUM | Business logic, state changes, new public APIs |
+| LOW | Comments, tests, UI, logging |
+
+---
+
+## Workflow Overview
+
+```
+Pre-Analysis → Phase 0: Triage → Phase 1: Code Analysis → Phase 2: Test Coverage
+    ↓              ↓                    ↓                        ↓
+Phase 3: Blast Radius → Phase 4: Deep Context → Phase 5: Adversarial → Phase 6: Report
+```
+
+---
+
+## Decision Tree
+
+**Starting a review?**
+
+```
+├─ Need detailed phase-by-phase methodology?
+│  └─ Read: methodology.md
+│     (Pre-Analysis + Phases 0-4: triage, code analysis, test coverage, blast radius)
+│
+├─ Analyzing HIGH RISK change?
+│  └─ Read: adversarial.md
+│     (Phase 5: Attacker modeling, exploit scenarios, exploitability rating)
+│
+├─ Writing the final report?
+│  └─ Read: reporting.md
+│     (Phase 6: Report structure, templates, formatting guidelines)
+│
+├─ Looking for specific vulnerability patterns?
+│  └─ Read: patterns.md
+│     (Regressions, reentrancy, access control, overflow, etc.)
+│
+└─ Quick triage only?
+   └─ Use Quick Reference above, skip detailed docs
+```
+
+---
+
+## Quality Checklist
+
+Before delivering:
+
+- [ ] All changed files analyzed
+- [ ] Git blame on removed security code
+- [ ] Blast radius calculated for HIGH risk
+- [ ] Attack scenarios are concrete (not generic)
+- [ ] Findings reference specific line numbers + commits
+- [ ] Report file generated
+- [ ] User notified with summary
+
+---
+
+## Integration
+
+**audit-context-building skill:**
+- Pre-Analysis: Build baseline context
+- Phase 4: Deep context on HIGH RISK changes
+
+**issue-writer skill:**
+- Transform findings into formal audit reports
+- Command: `issue-writer --input DIFFERENTIAL_REVIEW_REPORT.md --format audit-report`
+
+---
+
+## Example Usage
+
+### Quick Triage (Small PR)
+```
+Input: 5 file PR, 2 HIGH RISK files
+Strategy: Use Quick Reference
+1. Classify risk level per file (2 HIGH, 3 LOW)
+2. Focus on 2 HIGH files only
+3. Git blame removed code
+4. Generate minimal report
+Time: ~30 minutes
+```
+
+### Standard Review (Medium Codebase)
+```
+Input: 80 files, 12 HIGH RISK changes
+Strategy: FOCUSED (see methodology.md)
+1. Full workflow on HIGH RISK files
+2. Surface scan on MEDIUM
+3. Skip LOW risk files
+4. Complete report with all sections
+Time: ~3-4 hours
+```
+
+### Deep Audit (Large, Critical Change)
+```
+Input: 450 files, auth system rewrite
+Strategy: SURGICAL + audit-context-building
+1. Baseline context with audit-context-building
+2. Deep analysis on auth changes only
+3. Blast radius analysis
+4. Adversarial modeling
+5. Comprehensive report
+Time: ~6-8 hours
+```
+
+---
+
+## When NOT to Use This Skill
+
+- **Greenfield code** (no baseline to compare)
+- **Documentation-only changes** (no security impact)
+- **Formatting/linting** (cosmetic changes)
+- **User explicitly requests quick summary only** (they accept risk)
+
+For these cases, use standard code review instead.
+
+---
+
+## Red Flags (Stop and Investigate)
+
+**Immediate escalation triggers:**
+- Removed code from "security", "CVE", or "fix" commits
+- Access control modifiers removed (onlyOwner, internal → external)
+- Validation removed without replacement
+- External calls added without checks
+- High blast radius (50+ callers) + HIGH risk change
+
+These patterns require adversarial analysis even in quick triage.
+
+---
+
+## Tips for Best Results
+
+**Do:**
+- Start with git blame for removed code
+- Calculate blast radius early to prioritize
+- Generate concrete attack scenarios
+- Reference specific line numbers and commits
+- Be honest about coverage limitations
+- Always generate the output file
+
+**Don't:**
+- Skip git history analysis
+- Make generic findings without evidence
+- Claim full analysis when time-limited
+- Forget to check test coverage
+- Miss high blast radius changes
+- Output report only to chat (file required)
+
+---
+
+## Supporting Documentation
+
+- **[methodology.md](methodology.md)** - Detailed phase-by-phase workflow (Phases 0-4)
+- **[adversarial.md](adversarial.md)** - Attacker modeling and exploit scenarios (Phase 5)
+- **[reporting.md](reporting.md)** - Report structure and formatting (Phase 6)
+- **[patterns.md](patterns.md)** - Common vulnerability patterns reference
+
+---
+
+**For first-time users:** Start with [methodology.md](methodology.md) to understand the complete workflow.
+
+**For experienced users:** Use this page's Quick Reference and Decision Tree to navigate directly to needed content.

.claude/skills/duplicate-file-cleaner/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: duplicate-file-cleaner
+description: 중복 이미지 및 미디어 파일을 메타데이터 기반으로 찾아 안전하게 제거합니다. 중복 파일 정리, 파일 정리, 용량 확보 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Duplicate File Cleaner Expert
+
+중복 파일을 탐지하고 안전하게 제거하는 스킬입니다.
+
+## 기능
+
+### 탐지 방법
+- **해시 비교**: MD5/SHA256 체크섬으로 정확한 중복 탐지
+- **파일명 유사도**: 이름 기반 잠재적 중복 탐지
+- **메타데이터 분석**: EXIF, 생성일시, 크기 비교
+- **퍼지 매칭**: 리사이즈/재인코딩된 유사 파일 탐지
+
+### 지원 파일 유형
+- 이미지: jpg, png, gif, webp, bmp, tiff
+- 비디오: mp4, avi, mkv, mov, wmv
+- 오디오: mp3, wav, flac, aac
+- 문서: pdf, doc, xls (선택적)
+
+### 안전 기능
+- 삭제 전 미리보기
+- 휴지통으로 이동 (영구 삭제 방지)
+- 원본 보존 우선 (수정일 기준)
+- 롤백 가능한 로그 생성
+
+## 사용 스크립트
+
+### Python 중복 탐지
+```python
+import hashlib
+import os
+from pathlib import Path
+from collections import defaultdict
+
+def get_file_hash(filepath, chunk_size=8192):
+    """파일의 MD5 해시 계산"""
+    hasher = hashlib.md5()
+    with open(filepath, 'rb') as f:
+        while chunk := f.read(chunk_size):
+            hasher.update(chunk)
+    return hasher.hexdigest()
+
+def find_duplicates(directory, extensions=None):
+    """디렉토리에서 중복 파일 찾기"""
+    hash_map = defaultdict(list)
+
+    for filepath in Path(directory).rglob('*'):
+        if not filepath.is_file():
+            continue
+        if extensions and filepath.suffix.lower() not in extensions:
+            continue
+
+        file_hash = get_file_hash(filepath)
+        hash_map[file_hash].append(filepath)
+
+    # 중복된 것만 반환
+    return {h: files for h, files in hash_map.items() if len(files) > 1}
+
+def generate_report(duplicates):
+    """중복 파일 리포트 생성"""
+    total_size = 0
+    report = ["# 중복 파일 리포트\n"]
+
+    for hash_val, files in duplicates.items():
+        size = os.path.getsize(files[0])
+        savings = size * (len(files) - 1)
+        total_size += savings
+
+        report.append(f"\n## 해시: {hash_val[:8]}...")
+        report.append(f"크기: {size:,} bytes | 절약 가능: {savings:,} bytes")
+        for f in files:
+            mtime = os.path.getmtime(f)
+            report.append(f"  - {f} (수정: {mtime})")
+
+    report.append(f"\n---\n총 절약 가능 용량: {total_size:,} bytes ({total_size/1024/1024:.2f} MB)")
+    return '\n'.join(report)
+
+# 사용 예시
+extensions = {'.jpg', '.jpeg', '.png', '.gif', '.mp4'}
+duplicates = find_duplicates('/path/to/directory', extensions)
+print(generate_report(duplicates))
+```
+
+### Bash 빠른 탐지
+```bash
+#!/bin/bash
+# 중복 파일 빠른 탐지 (크기 + 해시 기반)
+
+find "$1" -type f -name "*.jpg" -o -name "*.png" | while read file; do
+    size=$(stat -f%z "$file" 2>/dev/null || stat -c%s "$file")
+    hash=$(md5sum "$file" | cut -d' ' -f1)
+    echo "$size $hash $file"
+done | sort | uniq -D -w 40
+```
+
+## 리포트 구조
+
+```markdown
+# 중복 파일 분석 리포트
+
+## 요약
+- 스캔 파일: 1,234개
+- 중복 그룹: 45개
+- 중복 파일: 123개
+- 절약 가능 용량: 2.3 GB
+
+## 중복 그룹 상세
+
+### 그룹 1 (3개 파일, 15.2 MB 절약 가능)
+| 파일 | 경로 | 수정일 | 권장 |
+|------|------|--------|------|
+| photo.jpg | /photos/2023/ | 2023-05-01 | ✅ 유지 |
+| photo(1).jpg | /downloads/ | 2023-06-15 | ❌ 삭제 |
+| IMG_001.jpg | /backup/ | 2023-05-01 | ❌ 삭제 |
+
+### 그룹 2 ...
+
+## 권장 조치
+1. 자동 선택된 78개 파일 삭제 (1.8 GB)
+2. 수동 검토 필요: 12개 그룹
+3. 백업 폴더 정리 권장
+
+## 실행 명령
+```bash
+# 안전 삭제 (휴지통으로 이동)
+trash-put file1.jpg file2.jpg ...
+
+# 또는 영구 삭제 (주의!)
+rm file1.jpg file2.jpg ...
+```
+```
+
+## 사용 예시
+
+```
+이 폴더의 중복 파일을 찾아줘
+사진 폴더에서 중복 이미지를 정리해줘
+용량을 확보하기 위해 중복 파일을 분석해줘
+```
+
+## 주의사항
+
+- 삭제 전 항상 백업 권장
+- 시스템 파일은 스캔에서 제외
+- 심볼릭 링크 주의 필요
+- 클라우드 동기화 폴더 주의
+
+## 출처
+Original skill from skills.cokac.com

.claude/skills/flutter-ux-hardening/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: flutter-ux-hardening
+description: Flutter 앱의 UI/UX를 계획, 구현, 테스트, 검토하고 반복적으로 강화하는 가이드 에이전트 스킬입니다. Flutter UI 개선, UX 강화, 접근성 개선 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Flutter UX Hardening
+
+Flutter 앱의 UI/UX를 체계적으로 분석하고 개선하는 스킬입니다.
+
+## 기능
+
+### 분석 영역
+- **UI 일관성**: 디자인 시스템 준수 여부
+- **UX 흐름**: 사용자 여정 최적화
+- **접근성**: a11y 지원 (스크린 리더, 색상 대비 등)
+- **반응형**: 다양한 화면 크기 대응
+- **에지 케이스**: 빈 상태, 로딩, 에러 처리
+
+### 강화 프로세스
+
+1. **계획 (Plan)**
+   - 현재 UI/UX 감사
+   - 개선 영역 식별
+   - 우선순위 설정
+
+2. **구현 (Implement)**
+   - 위젯 리팩토링
+   - 애니메이션 추가
+   - 접근성 속성 추가
+
+3. **테스트 (Test)**
+   - 위젯 테스트 작성
+   - 통합 테스트 추가
+   - 골든 테스트 설정
+
+4. **검토 (Review)**
+   - 코드 품질 검사
+   - 성능 프로파일링
+   - 사용자 피드백 반영
+
+5. **반복 (Iterate)**
+   - 지속적 개선
+   - A/B 테스트 적용
+
+## 체크리스트
+
+### 접근성 (Accessibility)
+```dart
+// ✅ Semantics 레이블 추가
+Semantics(
+  label: '장바구니에 추가',
+  child: IconButton(
+    icon: Icon(Icons.add_shopping_cart),
+    onPressed: _addToCart,
+  ),
+)
+
+// ✅ 충분한 터치 타겟 크기 (48x48 이상)
+SizedBox(
+  width: 48,
+  height: 48,
+  child: IconButton(...),
+)
+
+// ✅ 색상 대비 확인
+// WCAG AA: 4.5:1 (일반 텍스트), 3:1 (큰 텍스트)
+```
+
+### 에지 케이스 처리
+```dart
+// 빈 상태
+if (items.isEmpty) {
+  return EmptyStateWidget(
+    icon: Icons.inbox,
+    title: '항목이 없습니다',
+    subtitle: '새 항목을 추가해보세요',
+    action: ElevatedButton(
+      onPressed: _addItem,
+      child: Text('항목 추가'),
+    ),
+  );
+}
+
+// 로딩 상태
+if (isLoading) {
+  return ShimmerLoadingWidget();
+}
+
+// 에러 상태
+if (hasError) {
+  return ErrorWidget(
+    message: error.message,
+    onRetry: _retry,
+  );
+}
+```
+
+### 반응형 레이아웃
+```dart
+LayoutBuilder(
+  builder: (context, constraints) {
+    if (constraints.maxWidth > 900) {
+      return DesktopLayout();
+    } else if (constraints.maxWidth > 600) {
+      return TabletLayout();
+    }
+    return MobileLayout();
+  },
+)
+```
+
+### 애니메이션
+```dart
+// 부드러운 전환
+AnimatedContainer(
+  duration: Duration(milliseconds: 300),
+  curve: Curves.easeInOut,
+  // ...
+)
+
+// 히어로 애니메이션
+Hero(
+  tag: 'item-${item.id}',
+  child: ItemCard(item: item),
+)
+```
+
+## 리포트 구조
+
+```markdown
+# Flutter UX 강화 리포트
+
+## 현재 상태 분석
+- UI 일관성: ⭐⭐⭐☆☆
+- 접근성: ⭐⭐☆☆☆
+- 반응형: ⭐⭐⭐⭐☆
+- 에지 케이스 처리: ⭐⭐☆☆☆
+
+## 식별된 개선 영역
+1. 접근성 레이블 누락 (15개 위젯)
+2. 빈 상태 UI 미구현 (3개 화면)
+3. 로딩 스켈레톤 미적용 (5개 리스트)
+
+## 권장 조치
+| 우선순위 | 영역 | 조치 |
+|----------|------|------|
+| 높음 | 접근성 | Semantics 추가 |
+| 높음 | 에러 | 에러 바운더리 구현 |
+| 중간 | 로딩 | Shimmer 효과 추가 |
+
+## 구현 계획
+...
+```
+
+## 사용 예시
+
+```
+Flutter 앱의 UX를 개선해줘
+접근성을 강화하고 싶어
+빈 상태와 에러 처리를 추가해줘
+```
+
+## 출처
+Original skill from skills.cokac.com

.claude/skills/frontend-design/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

.claude/skills/insecure-defaults/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: insecure-defaults
+description: "Detects fail-open insecure defaults (hardcoded secrets, weak auth, permissive security) that allow apps to run insecurely in production. Use when auditing security, reviewing config management, or analyzing environment variable handling."
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+---
+
+# Insecure Defaults Detection
+
+Finds **fail-open** vulnerabilities where apps run insecurely with missing configuration. Distinguishes exploitable defaults from fail-secure patterns that crash safely.
+
+- **Fail-open (CRITICAL):** `SECRET = env.get('KEY') or 'default'` → App runs with weak secret
+- **Fail-secure (SAFE):** `SECRET = env['KEY']` → App crashes if missing
+
+## When to Use
+
+- **Security audits** of production applications (auth, crypto, API security)
+- **Configuration review** of deployment files, IaC templates, Docker configs
+- **Code review** of environment variable handling and secrets management
+- **Pre-deployment checks** for hardcoded credentials or weak defaults
+
+## When NOT to Use
+
+Do not use this skill for:
+- **Test fixtures** explicitly scoped to test environments (files in `test/`, `spec/`, `__tests__/`)
+- **Example/template files** (`.example`, `.template`, `.sample` suffixes)
+- **Development-only tools** (local Docker Compose for dev, debug scripts)
+- **Documentation examples** in README.md or docs/ directories
+- **Build-time configuration** that gets replaced during deployment
+- **Crash-on-missing behavior** where app won't start without proper config (fail-secure)
+
+When in doubt: trace the code path to determine if the app runs with the default or crashes.
+
+## Rationalizations to Reject
+
+- **"It's just a development default"** → If it reaches production code, it's a finding
+- **"The production config overrides it"** → Verify prod config exists; code-level vulnerability remains if not
+- **"This would never run without proper config"** → Prove it with code trace; many apps fail silently
+- **"It's behind authentication"** → Defense in depth; compromised session still exploits weak defaults
+- **"We'll fix it before release"** → Document now; "later" rarely comes
+
+## Workflow
+
+Follow this workflow for every potential finding:
+
+### 1. SEARCH: Perform Project Discovery and Find Insecure Defaults
+
+Determine language, framework, and project conventions. Use this information to further discover things like secret storage locations, secret usage patterns, credentialed third-party integrations, cryptography, and any other relevant configuration. Further use information to analyze insecure default configurations.
+
+**Example**
+Search for patterns in `**/config/`, `**/auth/`, `**/database/`, and env files:
+- **Fallback secrets:** `getenv.*\) or ['"]`, `process\.env\.[A-Z_]+ \|\| ['"]`, `ENV\.fetch.*default:`
+- **Hardcoded credentials:** `password.*=.*['"][^'"]{8,}['"]`, `api[_-]?key.*=.*['"][^'"]+['"]`
+- **Weak defaults:** `DEBUG.*=.*true`, `AUTH.*=.*false`, `CORS.*=.*\*`
+- **Crypto algorithms:** `MD5|SHA1|DES|RC4|ECB` in security contexts
+
+Tailor search approach based on discovery results.
+
+Focus on production-reachable code, not test fixtures or example files.
+
+### 2. VERIFY: Actual Behavior
+For each match, trace the code path to understand runtime behavior.
+
+**Questions to answer:**
+- When is this code executed? (Startup vs. runtime)
+- What happens if a configuration variable is missing?
+- Is there validation that enforces secure configuration?
+
+### 3. CONFIRM: Production Impact
+Determine if this issue reaches production:
+
+If production config provides the variable → Lower severity (but still a code-level vulnerability)
+If production config missing or uses default → CRITICAL
+
+### 4. REPORT: with Evidence
+
+**Example report:**
+```
+Finding: Hardcoded JWT Secret Fallback
+Location: src/auth/jwt.ts:15
+Pattern: const secret = process.env.JWT_SECRET || 'default';
+
+Verification: App starts without JWT_SECRET; secret used in jwt.sign() at line 42
+Production Impact: Dockerfile missing JWT_SECRET
+Exploitation: Attacker forges JWTs using 'default', gains unauthorized access
+```
+
+## Quick Verification Checklist
+
+**Fallback Secrets:** `SECRET = env.get(X) or Y`
+→ Verify: App starts without env var? Secret used in crypto/auth?
+→ Skip: Test fixtures, example files
+
+**Default Credentials:** Hardcoded `username`/`password` pairs
+→ Verify: Active in deployed config? No runtime override?
+→ Skip: Disabled accounts, documentation examples
+
+**Fail-Open Security:** `AUTH_REQUIRED = env.get(X, 'false')`
+→ Verify: Default is insecure (false/disabled/permissive)?
+→ Safe: App crashes or default is secure (true/enabled/restricted)
+
+**Weak Crypto:** MD5/SHA1/DES/RC4/ECB in security contexts
+→ Verify: Used for passwords, encryption, or tokens?
+→ Skip: Checksums, non-security hashing
+
+**Permissive Access:** CORS `*`, permissions `0777`, public-by-default
+→ Verify: Default allows unauthorized access?
+→ Skip: Explicitly configured permissiveness with justification
+
+**Debug Features:** Stack traces, introspection, verbose errors
+→ Verify: Enabled by default? Exposed in responses?
+→ Skip: Logging-only, not user-facing
+
+For detailed examples and counter-examples, see [examples.md](references/examples.md).

.claude/skills/layer-boundary-auditor/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: ln-642-layer-boundary-auditor
+description: "L3 Worker. Audits layer boundaries + cross-layer consistency: I/O violations, transaction boundaries (commit ownership), session ownership (DI vs local), async consistency (sync I/O in async), fire-and-forget tasks."
+---
+
+# Layer Boundary Auditor
+
+L3 Worker that audits architectural layer boundaries and detects violations.
+
+## Purpose & Scope
+
+- Read architecture.md to discover project's layer structure
+- Detect layer violations (I/O code outside infrastructure layer)
+- **Detect cross-layer consistency issues:**
+  - Transaction boundaries (commit/rollback ownership)
+  - Session ownership (DI vs local)
+  - Async consistency (sync I/O in async)
+  - Fire-and-forget tasks (unhandled exceptions)
+- Check pattern coverage (all HTTP calls use client abstraction)
+- Detect error handling duplication
+- Return violations list to coordinator
+
+## Input (from ln-640)
+
+```
+- architecture_path: string    # Path to docs/architecture.md
+- codebase_root: string        # Root directory to scan
+- skip_violations: string[]    # Files to skip (legacy)
+```
+
+## Workflow
+
+### Phase 1: Discover Architecture
+
+```
+Read docs/architecture.md
+
+Extract from Section 4.2 (Top-Level Decomposition):
+  - architecture_type: "Layered" | "Hexagonal" | "Clean" | "MVC" | etc.
+  - layers: [{name, directories[], purpose}]
+
+Extract from Section 5.3 (Infrastructure Layer Components):
+  - infrastructure_components: [{name, responsibility}]
+
+IF architecture.md not found:
+  Use fallback presets from common_patterns.md
+
+Build ruleset:
+  FOR EACH layer:
+    allowed_deps = layers that can be imported
+    forbidden_deps = layers that cannot be imported
+```
+
+### Phase 2: Detect Layer Violations
+
+```
+FOR EACH violation_type IN common_patterns.md I/O Pattern Boundary Rules:
+  grep_pattern = violation_type.detection_grep
+  forbidden_dirs = violation_type.forbidden_in
+
+  matches = Grep(grep_pattern, codebase_root, include="*.py,*.ts,*.js")
+
+  FOR EACH match IN matches:
+    IF match.path NOT IN skip_violations:
+      IF any(forbidden IN match.path FOR forbidden IN forbidden_dirs):
+        violations.append({
+          type: "layer_violation",
+          severity: "HIGH",
+          pattern: violation_type.name,
+          file: match.path,
+          line: match.line,
+          code: match.context,
+          allowed_in: violation_type.allowed_in,
+          suggestion: f"Move to {violation_type.allowed_in}"
+        })
+```
+
+### Phase 2.5: Cross-Layer Consistency Checks
+
+#### 2.5.1 Transaction Boundary Violations
+
+**What:** commit()/rollback() called at inconsistent layers (repo + service + API)
+
+**Detection:**
+```
+repo_commits = Grep("\.commit\(\)|\.rollback\(\)", "**/repositories/**/*.py")
+service_commits = Grep("\.commit\(\)|\.rollback\(\)", "**/services/**/*.py")
+api_commits = Grep("\.commit\(\)|\.rollback\(\)", "**/api/**/*.py")
+
+layers_with_commits = count([repo_commits, service_commits, api_commits].filter(len > 0))
+```
+
+**Safe Patterns (ignore):**
+- Comment "# best-effort telemetry" in same context
+- File ends with `_callbacks.py` (progress notifiers)
+- Explicit `# UoW boundary` comment
+
+**Violation Rules:**
+
+| Condition | Severity | Issue |
+|-----------|----------|-------|
+| layers_with_commits >= 3 | CRITICAL | Mixed UoW ownership across all layers |
+| repo + api commits | HIGH | Transaction control bypasses service layer |
+| repo + service commits | HIGH | Ambiguous UoW owner (repo vs service) |
+| service + api commits | MEDIUM | Transaction control spans service + API |
+
+**Recommendation:** Choose single UoW owner (service layer recommended), remove commit() from other layers
+
+**Effort:** L (requires architectural decision + refactoring)
+
+#### 2.5.2 Session Ownership Violations
+
+**What:** Mixed DI-injected and locally-created sessions in same call chain
+
+**Detection:**
+```
+di_session = Grep("Depends\(get_session\)|Depends\(get_db\)", "**/api/**/*.py")
+local_session = Grep("AsyncSessionLocal\(\)|async_sessionmaker", "**/services/**/*.py")
+local_in_repo = Grep("AsyncSessionLocal\(\)", "**/repositories/**/*.py")
+```
+
+**Violation Rules:**
+
+| Condition | Severity | Issue |
+|-----------|----------|-------|
+| di_session AND local_in_repo in same module | HIGH | Repo creates own session while API injects different |
+| local_session in service calling DI-based repo | MEDIUM | Session mismatch in call chain |
+
+**Recommendation:** Use DI consistently OR use local sessions consistently. Document exceptions (e.g., telemetry)
+
+**Effort:** M
+
+#### 2.5.3 Async Consistency Violations
+
+**What:** Synchronous blocking I/O inside async functions
+
+**Detection:**
+```
+# For each file with "async def":
+sync_file_io = Grep("\.read_bytes\(\)|\.read_text\(\)|\.write_bytes\(\)|\.write_text\(\)", file)
+sync_open = Grep("(?<!aiofiles\.)open\(", file)  # open() not preceded by aiofiles.
+
+# Safe patterns (not violations):
+# - "asyncio.to_thread(" wrapping the call
+# - "await aiofiles.open("
+# - "run_in_executor(" wrapping the call
+```
+
+**Violation Rules:**
+
+| Pattern | Severity | Issue |
+|---------|----------|-------|
+| Path.read_bytes() in async def | HIGH | Blocking file read in async context |
+| open() without aiofiles in async def | HIGH | Blocking file operation |
+| time.sleep() in async def | HIGH | Blocking sleep (use asyncio.sleep) |
+
+**Recommendation:** Use `asyncio.to_thread()` or `aiofiles` for file I/O in async functions
+
+**Effort:** S-M
+
+#### 2.5.4 Fire-and-Forget Violations
+
+**What:** asyncio.create_task() without error handling
+
+**Detection:**
+```
+all_tasks = Grep("create_task\(", codebase)
+
+# For each match, check context:
+# - Has .add_done_callback() → OK
+# - Assigned to variable with later await → OK
+# - Has "# fire-and-forget" comment → OK (documented intent)
+# - None of above → VIOLATION
+```
+
+**Violation Rules:**
+
+| Pattern | Severity | Issue |
+|---------|----------|-------|
+| create_task() without handler or comment | MEDIUM | Unhandled task exception possible |
+| create_task() in loop without error collection | HIGH | Multiple silent failures possible |
+
+**Recommendation:** Add `task.add_done_callback(handle_exception)` or document intent with comment
+
+**Effort:** S
+
+---
+
+### Phase 3: Check Pattern Coverage
+
+```
+# HTTP Client Coverage
+all_http_calls = Grep("httpx\\.|aiohttp\\.|requests\\.", codebase_root)
+abstracted_calls = Grep("client\\.(get|post|put|delete)", infrastructure_dirs)
+
+IF len(all_http_calls) > 0:
+  coverage = len(abstracted_calls) / len(all_http_calls) * 100
+  IF coverage < 90%:
+    violations.append({
+      type: "low_coverage",
+      severity: "MEDIUM",
+      pattern: "HTTP Client Abstraction",
+      coverage: coverage,
+      uncovered_files: files with direct calls outside infrastructure
+    })
+
+# Error Handling Duplication
+http_error_handlers = Grep("except\\s+(httpx\\.|aiohttp\\.|requests\\.)", codebase_root)
+unique_files = set(f.path for f in http_error_handlers)
+
+IF len(unique_files) > 2:
+  violations.append({
+    type: "duplication",
+    severity: "MEDIUM",
+    pattern: "HTTP Error Handling",
+    files: list(unique_files),
+    suggestion: "Centralize in infrastructure layer"
+  })
+```
+
+### Phase 3.5: Calculate Score
+
+See `shared/references/audit_scoring.md` for unified formula and score interpretation.
+
+### Phase 4: Return Result
+
+```json
+{
+  "category": "Layer Boundary",
+  "score": 4.5,
+  "total_issues": 8,
+  "critical": 1,
+  "high": 3,
+  "medium": 4,
+  "low": 0,
+  "architecture": {
+    "type": "Layered",
+    "layers": ["api", "services", "domain", "infrastructure"]
+  },
+  "checks": [
+    {"id": "io_isolation", "name": "I/O Isolation", "status": "failed", "details": "HTTP client found in domain layer"},
+    {"id": "http_abstraction", "name": "HTTP Abstraction", "status": "warning", "details": "75% coverage, 3 direct calls outside infrastructure"},
+    {"id": "error_centralization", "name": "Error Centralization", "status": "failed", "details": "HTTP error handlers in 4 files, should be centralized"},
+    {"id": "transaction_boundary", "name": "Transaction Boundary", "status": "failed", "details": "commit() in repos (3), services (2), api (4) - mixed UoW ownership"},
+    {"id": "session_ownership", "name": "Session Ownership", "status": "passed", "details": "DI-based sessions used consistently"},
+    {"id": "async_consistency", "name": "Async Consistency", "status": "failed", "details": "Blocking I/O in async functions detected"},
+    {"id": "fire_and_forget", "name": "Fire-and-Forget Handling", "status": "warning", "details": "2 tasks without error handlers"}
+  ],
+  "findings": [
+    {
+      "severity": "CRITICAL",
+      "location": "app/",
+      "issue": "Mixed UoW ownership: commit() found in repositories (3), services (2), api (4)",
+      "principle": "Layer Boundary / Transaction Control",
+      "recommendation": "Choose single UoW owner (service layer recommended), remove commit() from other layers",
+      "effort": "L"
+    },
+    {
+      "severity": "HIGH",
+      "location": "app/services/job/service.py:45",
+      "issue": "Blocking file I/O in async: Path.read_bytes() inside async def process_job()",
+      "principle": "Layer Boundary / Async Consistency",
+      "recommendation": "Use asyncio.to_thread(path.read_bytes) or aiofiles",
+      "effort": "S"
+    },
+    {
+      "severity": "HIGH",
+      "location": "app/domain/pdf/parser.py:45",
+      "issue": "Layer violation: HTTP client used in domain layer",
+      "principle": "Layer Boundary / I/O Isolation",
+      "recommendation": "Move httpx.AsyncClient to infrastructure/http/clients/",
+      "effort": "M"
+    },
+    {
+      "severity": "MEDIUM",
+      "location": "app/api/v1/jobs.py:78",
+      "issue": "Fire-and-forget task without error handler: create_task(notify_user())",
+      "principle": "Layer Boundary / Task Error Handling",
+      "recommendation": "Add task.add_done_callback(handle_exception) or document with # fire-and-forget comment",
+      "effort": "S"
+    }
+  ],
+  "coverage": {
+    "http_abstraction": 75,
+    "error_centralization": false,
+    "transaction_boundary_consistent": false,
+    "session_ownership_consistent": true,
+    "async_io_consistent": false,
+    "fire_and_forget_handled": false
+  }
+}
+```
+
+## Critical Rules
+
+- **Read architecture.md first** - never assume architecture type
+- **Skip violations list** - respect legacy files marked for gradual fix
+- **File + line + code** - always provide exact location with context
+- **Actionable suggestions** - always tell WHERE to move the code
+- **No false positives** - verify path contains forbidden dir, not just substring
+
+## Definition of Done
+
+- Architecture discovered from docs/architecture.md (or fallback used)
+- All violation types from common_patterns.md checked
+- **Cross-layer consistency checked:**
+  - Transaction boundaries analyzed (commit/rollback distribution)
+  - Session ownership analyzed (DI vs local)
+  - Async consistency analyzed (sync I/O in async functions)
+  - Fire-and-forget tasks analyzed (error handling)
+- Coverage calculated for HTTP abstraction + 4 consistency metrics
+- Violations list with severity, location, suggestion
+- Summary counts returned to coordinator
+
+## Reference Files
+
+- Layer rules: `../ln-640-pattern-evolution-auditor/references/common_patterns.md`
+- Scoring impact: `../ln-640-pattern-evolution-auditor/references/scoring_rules.md`
+
+---
+
+**Version:** 2.0.0
+**Last Updated:** 2026-02-04

.claude/skills/node-debug-logging-middleware/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: node-debug-logging-middleware
+description: Node.js Express/Koa 앱에 상세 디버깅 로그를 출력하는 미들웨어를 추가합니다. 미들웨어 로깅, 요청 추적, Node.js 디버깅 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Node Debug Logging Middleware
+
+Node.js 웹 애플리케이션에 상세한 디버깅 로그 미들웨어를 추가하는 스킬입니다.
+
+## 기능
+
+### 로깅 대상
+- HTTP 요청/응답 상세 정보
+- 요청 바디 및 쿼리 파라미터
+- 응답 시간 및 상태 코드
+- 에러 스택 트레이스
+- 메모리 사용량
+
+### 지원 프레임워크
+- Express.js
+- Koa.js
+- Fastify
+- NestJS
+
+### 출력 옵션
+- 콘솔 (개발환경)
+- 파일 (프로덕션)
+- 외부 서비스 (Sentry, Datadog 등)
+
+## Express.js 미들웨어
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * 디버그 로깅 미들웨어 생성
+ * @param {Object} options - 설정 옵션
+ * @param {string} options.logDir - 로그 파일 디렉토리
+ * @param {boolean} options.logBody - 요청/응답 바디 로깅 여부
+ * @param {boolean} options.logHeaders - 헤더 로깅 여부
+ * @param {number} options.bodyLimit - 바디 로깅 최대 크기 (bytes)
+ */
+function createDebugLogger(options = {}) {
+  const {
+    logDir = './logs',
+    logBody = true,
+    logHeaders = false,
+    bodyLimit = 10000
+  } = options;
+
+  // 로그 디렉토리 생성
+  if (!fs.existsSync(logDir)) {
+    fs.mkdirSync(logDir, { recursive: true });
+  }
+
+  const getLogStream = () => {
+    const date = new Date().toISOString().split('T')[0];
+    const logFile = path.join(logDir, `debug-${date}.log`);
+    return fs.createWriteStream(logFile, { flags: 'a' });
+  };
+
+  return (req, res, next) => {
+    const startTime = Date.now();
+    const requestId = Math.random().toString(36).substring(7);
+
+    // 요청 정보 수집
+    const requestLog = {
+      id: requestId,
+      timestamp: new Date().toISOString(),
+      method: req.method,
+      url: req.originalUrl,
+      ip: req.ip || req.connection.remoteAddress,
+      userAgent: req.get('User-Agent')
+    };
+
+    if (logHeaders) {
+      requestLog.headers = req.headers;
+    }
+
+    if (logBody && req.body && Object.keys(req.body).length > 0) {
+      const bodyStr = JSON.stringify(req.body);
+      requestLog.body = bodyStr.length > bodyLimit
+        ? bodyStr.substring(0, bodyLimit) + '...[truncated]'
+        : req.body;
+    }
+
+    // 응답 가로채기
+    const originalSend = res.send;
+    let responseBody;
+
+    res.send = function(body) {
+      responseBody = body;
+      return originalSend.call(this, body);
+    };
+
+    // 응답 완료 시 로깅
+    res.on('finish', () => {
+      const duration = Date.now() - startTime;
+
+      const logEntry = {
+        ...requestLog,
+        response: {
+          statusCode: res.statusCode,
+          duration: `${duration}ms`,
+          contentLength: res.get('Content-Length')
+        }
+      };
+
+      if (logBody && responseBody && res.statusCode >= 400) {
+        try {
+          const bodyStr = typeof responseBody === 'string'
+            ? responseBody
+            : JSON.stringify(responseBody);
+          logEntry.response.body = bodyStr.length > bodyLimit
+            ? bodyStr.substring(0, bodyLimit) + '...[truncated]'
+            : responseBody;
+        } catch (e) {
+          // 바디 파싱 실패 무시
+        }
+      }
+
+      // 콘솔 출력
+      const color = res.statusCode >= 500 ? '\x1b[31m'
+        : res.statusCode >= 400 ? '\x1b[33m'
+        : '\x1b[32m';
+      console.log(
+        `${color}[${requestLog.timestamp}] ${req.method} ${req.originalUrl} ${res.statusCode} ${duration}ms\x1b[0m`
+      );
+
+      // 파일 출력
+      const stream = getLogStream();
+      stream.write(JSON.stringify(logEntry) + '\n');
+      stream.end();
+    });
+
+    next();
+  };
+}
+
+module.exports = createDebugLogger;
+```
+
+## 사용법
+
+```javascript
+const express = require('express');
+const createDebugLogger = require('./middleware/debugLogger');
+
+const app = express();
+
+// JSON 파싱 (로깅 전에 설정)
+app.use(express.json());
+
+// 디버그 로거 적용
+app.use(createDebugLogger({
+  logDir: './logs',
+  logBody: true,
+  logHeaders: process.env.NODE_ENV === 'development',
+  bodyLimit: 5000
+}));
+
+// 라우트 정의
+app.get('/api/users', (req, res) => {
+  res.json({ users: [] });
+});
+
+app.listen(3000);
+```
+
+## Koa.js 버전
+
+```javascript
+async function koaDebugLogger(ctx, next) {
+  const startTime = Date.now();
+
+  console.log(`--> ${ctx.method} ${ctx.url}`);
+
+  try {
+    await next();
+  } catch (err) {
+    console.error(`[ERROR] ${err.message}`);
+    throw err;
+  }
+
+  const duration = Date.now() - startTime;
+  console.log(`<-- ${ctx.method} ${ctx.url} ${ctx.status} ${duration}ms`);
+}
+
+// 사용
+app.use(koaDebugLogger);
+```
+
+## 로그 출력 예시
+
+```json
+{
+  "id": "a1b2c3",
+  "timestamp": "2024-01-15T10:30:45.123Z",
+  "method": "POST",
+  "url": "/api/users",
+  "ip": "192.168.1.100",
+  "userAgent": "Mozilla/5.0...",
+  "body": { "name": "홍길동", "email": "hong@example.com" },
+  "response": {
+    "statusCode": 201,
+    "duration": "45ms",
+    "contentLength": "156"
+  }
+}
+```
+
+## 사용 예시
+
+```
+Express 앱에 요청 로깅 미들웨어를 추가해줘
+API 호출을 디버깅하기 위한 로그를 설정해줘
+Node.js 서버에 상세 로깅을 추가해줘
+```
+
+## 출처
+Original skill from skills.cokac.com

.claude/skills/npm-release-manager/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: npm-release-manager
+description: NPM 패키지 배포 프로세스를 자동화합니다. 버전 관리, changelog 생성, npm 배포 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# NPM Release Manager
+
+NPM 패키지의 릴리스 프로세스를 자동화하는 스킬입니다.
+
+## 기능
+
+### 릴리스 워크플로우
+1. **변경 사항 분석**: git diff로 변경 내용 파악
+2. **버전 결정**: Semantic Versioning (major.minor.patch)
+3. **Changelog 생성**: 커밋 메시지 기반 자동 생성
+4. **버전 범프**: package.json 버전 업데이트
+5. **Git 태그**: 버전 태그 생성
+6. **NPM 배포**: npm publish 실행
+
+### Semantic Versioning 가이드
+- **Major (x.0.0)**: 호환되지 않는 API 변경
+- **Minor (0.x.0)**: 하위 호환 기능 추가
+- **Patch (0.0.x)**: 하위 호환 버그 수정
+
+### Changelog 형식
+```markdown
+# Changelog
+
+## [1.2.0] - 2024-01-15
+
+### Added
+- 새로운 기능 A 추가
+- 새로운 기능 B 추가
+
+### Changed
+- 기존 기능 C 개선
+
+### Fixed
+- 버그 D 수정
+- 버그 E 수정
+
+### Deprecated
+- 기능 F 지원 중단 예정
+
+### Removed
+- 기능 G 제거
+
+### Security
+- 보안 취약점 H 패치
+```
+
+## 릴리스 프로세스
+
+### 1. 사전 검사
+```bash
+# 테스트 실행
+npm test
+
+# 린트 검사
+npm run lint
+
+# 빌드 확인
+npm run build
+```
+
+### 2. 버전 업데이트
+```bash
+# patch 릴리스
+npm version patch
+
+# minor 릴리스
+npm version minor
+
+# major 릴리스
+npm version major
+```
+
+### 3. Changelog 업데이트
+- 커밋 메시지 분석
+- 카테고리별 분류
+- CHANGELOG.md 업데이트
+
+### 4. 배포
+```bash
+# npm 로그인 확인
+npm whoami
+
+# 배포
+npm publish
+
+# 또는 스코프 패키지
+npm publish --access public
+```
+
+### 5. Git 푸시
+```bash
+git push origin main --tags
+```
+
+## 커밋 메시지 규약
+
+Conventional Commits 형식 권장:
+- `feat:` 새로운 기능 (minor)
+- `fix:` 버그 수정 (patch)
+- `docs:` 문서 변경
+- `style:` 코드 스타일 변경
+- `refactor:` 리팩토링
+- `test:` 테스트 추가/수정
+- `chore:` 빌드/도구 변경
+- `BREAKING CHANGE:` 호환되지 않는 변경 (major)
+
+## 사용 예시
+
+```
+새 버전을 배포해줘
+패치 릴리스를 진행해줘
+changelog를 업데이트하고 npm에 배포해줘
+```
+
+## 주의사항
+
+- npm 로그인 상태 확인 필요
+- 2FA 설정 시 OTP 입력 필요
+- private 패키지는 유료 계정 필요
+- 배포 전 테스트 통과 필수
+
+## 출처
+Original skill from skills.cokac.com

.claude/skills/observability-auditor/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: ln-627-observability-auditor
+description: Observability audit worker (L3). Checks structured logging, health check endpoints, metrics collection, request tracing, log levels. Returns findings with severity, location, effort, recommendations.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Observability Auditor (L3 Worker)
+
+Specialized worker auditing logging, monitoring, and observability.
+
+## Purpose & Scope
+
+- **Worker in ln-620 coordinator pipeline**
+- Audit **observability** (Category 10: Medium Priority)
+- Check logging, health checks, metrics, tracing
+- Calculate compliance score (X/10)
+
+## Inputs (from Coordinator)
+
+Receives `contextStore` with tech stack, framework, codebase root.
+
+## Workflow
+
+1) Parse context
+2) Check observability patterns
+3) Collect findings
+4) Calculate score
+5) Return JSON
+
+## Audit Rules
+
+### 1. Structured Logging
+**Detection:**
+- Grep for `console.log` (unstructured)
+- Check for proper logger: winston, pino, logrus, zap
+
+**Severity:**
+- **MEDIUM:** Production code using console.log
+- **LOW:** Dev code using console.log
+
+**Recommendation:** Use structured logger (winston, pino)
+
+**Effort:** M (add logger, replace calls)
+
+### 2. Health Check Endpoints
+**Detection:**
+- Grep for `/health`, `/ready`, `/live` routes
+- Check API route definitions
+
+**Severity:**
+- **HIGH:** No health check endpoint (monitoring blind spot)
+
+**Recommendation:** Add `/health` endpoint
+
+**Effort:** S (add simple route)
+
+### 3. Metrics Collection
+**Detection:**
+- Check for Prometheus client, StatsD, CloudWatch
+- Grep for metric recording: `histogram`, `counter`
+
+**Severity:**
+- **MEDIUM:** No metrics instrumentation
+
+**Recommendation:** Add Prometheus metrics
+
+**Effort:** M (instrument code)
+
+### 4. Request Tracing
+**Detection:**
+- Check for correlation IDs in logs
+- Verify trace propagation (OpenTelemetry, Zipkin)
+
+**Severity:**
+- **MEDIUM:** No correlation IDs (hard to debug distributed systems)
+
+**Recommendation:** Add request ID middleware
+
+**Effort:** M (add middleware, propagate IDs)
+
+### 5. Log Levels
+**Detection:**
+- Check if logger supports levels (info, warn, error, debug)
+- Verify proper level usage
+
+**Severity:**
+- **LOW:** Only error logging (insufficient visibility)
+
+**Recommendation:** Add info/debug logs
+
+**Effort:** S (add log statements)
+
+## Scoring Algorithm
+
+See `shared/references/audit_scoring.md` for unified formula and score interpretation.
+
+## Output Format
+
+```json
+{
+  "category": "Observability",
+  "score": 6,
+  "total_issues": 5,
+  "critical": 0,
+  "high": 1,
+  "medium": 3,
+  "low": 1,
+  "checks": [
+    {"id": "structured_logging", "name": "Structured Logging", "status": "warning", "details": "3 console.log calls in production code"},
+    {"id": "health_endpoints", "name": "Health Endpoints", "status": "failed", "details": "No /health endpoint found"},
+    {"id": "metrics_collection", "name": "Metrics Collection", "status": "passed", "details": "Prometheus client configured"},
+    {"id": "request_tracing", "name": "Request Tracing", "status": "warning", "details": "Correlation IDs missing in 2 services"}
+  ],
+  "findings": [
+    {
+      "severity": "HIGH",
+      "location": "src/api/server.ts",
+      "issue": "No /health endpoint for monitoring",
+      "principle": "Observability / Health Checks",
+      "recommendation": "Add GET /health route returning { status: 'ok', uptime, ... }",
+      "effort": "S"
+    }
+  ]
+}
+```
+
+## Reference Files
+
+- **Audit scoring formula:** `shared/references/audit_scoring.md`
+- **Audit output schema:** `shared/references/audit_output_schema.md`
+
+---
+**Version:** 3.0.0
+**Last Updated:** 2025-12-23

.claude/skills/pdf-template-skill/SKILL.md

@@ -0,0 +1,211 @@
+# PDF Template Skill
+
+PDF 문서의 구조와 디자인을 분석하여 동일한 형태의 PPTX 템플릿을 생성하는 기술입니다.
+
+## 📋 기능 개요
+
+### 핵심 기능
+- **PDF 구조 분석**: 레이아웃, 폰트, 색상, 위치 정보 추출
+- **템플릿 생성**: PDF와 동일한 형태의 PPTX 템플릿 제작
+- **내용 교체**: 기존 내용을 새로운 데이터로 자동 교체
+- **형태 보존**: 원본 PDF의 디자인과 레이아웃 완벽 유지
+
+### 지원 기능
+- 다중 슬라이드 템플릿 추출
+- 테이블 구조 인식 및 재생성
+- 이미지 및 로고 영역 매핑
+- 폰트 및 색상 스타일 보존
+
+## 🚀 사용법
+
+### 1. PDF 템플릿 분석
+```bash
+node .claude/skills/pdf-template-skill/scripts/analyze-template.js \
+  --input pdf_sample/sample.pdf \
+  --output templates/sample_template.json
+```
+
+### 2. 내용 교체로 PPTX 생성
+```bash
+node .claude/skills/pdf-template-skill/scripts/generate-from-template.js \
+  --template templates/sample_template.json \
+  --data project_data.json \
+  --output result.pptx
+```
+
+### 3. 통합 실행
+```bash
+npm run template-extract    # PDF → 템플릿 추출
+npm run template-generate   # 템플릿 → PPTX 생성
+```
+
+## 📊 템플릿 구조
+
+### Template JSON Format
+```json
+{
+  "metadata": {
+    "source": "sample.pdf",
+    "pages": 5,
+    "extractedAt": "2025-01-03",
+    "title": "SAM ERP 견적서"
+  },
+  "slides": [
+    {
+      "slideNumber": 1,
+      "type": "cover",
+      "layout": {
+        "width": 10,
+        "height": 7.5
+      },
+      "elements": [
+        {
+          "type": "text",
+          "id": "title",
+          "position": { "x": 1, "y": 3, "w": 8, "h": 1.5 },
+          "style": {
+            "fontSize": 36,
+            "bold": true,
+            "color": "0066CC",
+            "align": "center"
+          },
+          "placeholder": "{{title}}",
+          "defaultValue": "견적서"
+        }
+      ]
+    }
+  ],
+  "styles": {
+    "colors": {
+      "primary": "0066CC",
+      "secondary": "333333",
+      "accent": "00AA00"
+    },
+    "fonts": {
+      "title": { "face": "Arial", "size": 24, "bold": true },
+      "body": { "face": "Arial", "size": 12 }
+    }
+  },
+  "variables": {
+    "title": "string",
+    "company": "string",
+    "date": "date",
+    "items": "array"
+  }
+}
+```
+
+### Data Input Format
+```json
+{
+  "title": "스마트 재고 관리 시스템",
+  "company": "(주) 테크솔루션",
+  "date": "2025-01-03",
+  "client": {
+    "name": "고객사명",
+    "site": "프로젝트명",
+    "address": "주소"
+  },
+  "items": [
+    {
+      "name": "상품명",
+      "quantity": 1,
+      "price": 1000000,
+      "description": "상세 설명"
+    }
+  ]
+}
+```
+
+## 🔧 고급 기능
+
+### 1. 동적 테이블 생성
+```javascript
+// 테이블 구조 정의
+{
+  "type": "table",
+  "id": "itemsTable",
+  "template": {
+    "headers": ["번호", "품명", "수량", "단가", "금액"],
+    "rowTemplate": "{{index}}, {{name}}, {{quantity}}, {{price}}, {{total}}",
+    "dataSource": "items"
+  }
+}
+```
+
+### 2. 조건부 콘텐츠
+```javascript
+// 조건부 표시
+{
+  "type": "conditional",
+  "condition": "items.length > 10",
+  "ifTrue": { /* 대용량 테이블 레이아웃 */ },
+  "ifFalse": { /* 기본 테이블 레이아웃 */ }
+}
+```
+
+### 3. 계산 필드
+```javascript
+// 자동 계산
+{
+  "type": "calculated",
+  "formula": "SUM(items.price * items.quantity)",
+  "format": "currency"
+}
+```
+
+## 📋 워크플로우
+
+### Phase 1: PDF 분석
+1. **페이지 분할**: PDF를 개별 페이지로 분리
+2. **요소 인식**: 텍스트, 이미지, 테이블, 도형 위치 추출
+3. **스타일 분석**: 폰트, 색상, 크기 정보 수집
+4. **구조 매핑**: 논리적 구조와 시각적 배치 연결
+
+### Phase 2: 템플릿 생성
+1. **변수 식별**: 교체 가능한 콘텐츠 영역 표시
+2. **레이아웃 정의**: 고정 요소와 가변 요소 분리
+3. **스타일 시트**: 일관된 디자인 규칙 정의
+4. **검증**: 생성된 템플릿의 정확성 확인
+
+### Phase 3: 콘텐츠 적용
+1. **데이터 바인딩**: JSON 데이터를 템플릿 변수에 매핑
+2. **PPTX 생성**: PptxGenJS를 사용한 슬라이드 생성
+3. **스타일 적용**: 원본과 동일한 디자인 재현
+4. **품질 검증**: 생성된 PPTX의 형태 확인
+
+## 🎯 적용 사례
+
+### 1. 견적서 시스템
+- **템플릿**: SAM ERP 견적서 PDF
+- **변수**: 고객정보, 상품목록, 금액계산
+- **결과**: 동일한 형태의 견적서 PPTX
+
+### 2. 기획서 시스템
+- **템플릿**: 표준 기획서 PDF
+- **변수**: 프로젝트 정보, 기능 명세, 일정
+- **결과**: 일관된 형태의 기획서 PPTX
+
+### 3. 보고서 시스템
+- **템플릿**: 월간 보고서 PDF
+- **변수**: 실적 데이터, 차트, 분석 내용
+- **결과**: 표준화된 보고서 PPTX
+
+## 🔮 확장 계획
+
+### Short-term
+- [ ] 더 정교한 테이블 구조 인식
+- [ ] 차트 및 그래프 템플릿 지원
+- [ ] 다국어 템플릿 처리
+
+### Long-term
+- [ ] AI 기반 레이아웃 최적화
+- [ ] 실시간 템플릿 편집기
+- [ ] 클라우드 템플릿 저장소
+
+## 📚 참고 자료
+
+- PptxGenJS Documentation
+- PDF.js Parser Reference
+- Template Engine Best Practices
+- Design Pattern Guidelines

.claude/skills/pdf-template-skill/scripts/analyze-template.js

@@ -0,0 +1,572 @@
+/**
+ * PDF 템플릿 분석기 - PDF 구조를 분석하여 템플릿 생성
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+
+// PDF 템플릿 분석 클래스
+class PDFTemplateAnalyzer {
+  constructor() {
+    this.template = {
+      metadata: {},
+      slides: [],
+      styles: {
+        colors: {},
+        fonts: {}
+      },
+      variables: {}
+    };
+  }
+
+  /**
+   * SAM ERP 견적서 PDF 분석 (수동 매핑)
+   */
+  async analyzeSAMEstimate(inputPath) {
+    console.log(`📖 SAM ERP 견적서 PDF 분석: ${inputPath}`);
+
+    // 메타데이터 설정
+    this.template.metadata = {
+      source: path.basename(inputPath),
+      pages: 5,
+      extractedAt: new Date().toISOString().split('T')[0],
+      title: "SAM ERP 견적서",
+      type: "estimate"
+    };
+
+    // 스타일 정의
+    this.template.styles = {
+      colors: {
+        primary: '0066CC',      // SAM 파란색
+        secondary: '333333',    // 진한 회색
+        headerBg: 'F0F8FF',     // 연한 파란색
+        border: 'CCCCCC',       // 테두리 회색
+        white: 'FFFFFF',
+        black: '000000',
+        red: 'CC0000',
+        green: '008000'
+      },
+      fonts: {
+        title: { face: 'Arial', size: 32, bold: true },
+        heading: { face: 'Arial', size: 24, bold: true },
+        subheading: { face: 'Arial', size: 18, bold: true },
+        body: { face: 'Arial', size: 12 },
+        small: { face: 'Arial', size: 10 }
+      }
+    };
+
+    // 슬라이드 템플릿 생성
+    this.createCoverSlideTemplate();
+    this.createMainScreenTemplate();
+    this.createDetailScreenTemplate();
+    this.createEstimateDocTemplate();
+    this.createEstimateDetailTemplate();
+
+    // 변수 정의
+    this.template.variables = {
+      // 회사 정보
+      company: { type: 'string', default: '(주) 주일기업' },
+      documentNumber: { type: 'string', default: 'ABC123' },
+      date: { type: 'date', default: '2025-01-03' },
+
+      // 고객 정보
+      clientName: { type: 'string', default: '회사명' },
+      siteName: { type: 'string', default: '현장명' },
+      clientAddress: { type: 'string', default: '주소명' },
+      clientContact: { type: 'string', default: '연락처' },
+      clientPhone: { type: 'string', default: '010-1234-5678' },
+
+      // 견적 정보
+      estimateNumber: { type: 'string', default: '123123' },
+      estimator: { type: 'string', default: '이름' },
+      totalAmount: { type: 'number', default: 93950000 },
+      bidDate: { type: 'date', default: '2025-12-12' },
+
+      // 상품 목록
+      items: {
+        type: 'array',
+        default: [
+          {
+            no: 1,
+            name: 'FSSB01(주차장)',
+            product: '제품명',
+            width: 2530,
+            height: 2550,
+            quantity: 1,
+            unit: 'SET',
+            materialCost: 1420000,
+            laborCost: 510000,
+            totalCost: 1930000
+          }
+        ]
+      },
+
+      // 요약 정보
+      summary: {
+        type: 'object',
+        default: {
+          description: '셔터설치공사',
+          quantity: 1,
+          unit: '식',
+          materialTotal: 78540000,
+          laborTotal: 15410000,
+          grandTotal: 93950000
+        }
+      },
+
+      // 기타 정보
+      notes: { type: 'string', default: '부가세 별도 / 현설조건에 따름' }
+    };
+
+    console.log('✅ SAM ERP 견적서 템플릿 분석 완료');
+    return this.template;
+  }
+
+  /**
+   * 표지 슬라이드 템플릿
+   */
+  createCoverSlideTemplate() {
+    this.template.slides.push({
+      slideNumber: 1,
+      type: 'cover',
+      name: '표지',
+      layout: { width: 10, height: 7.5 },
+      elements: [
+        {
+          type: 'background',
+          id: 'coverBackground',
+          style: { color: '{{colors.primary}}' }
+        },
+        {
+          type: 'shape',
+          id: 'logoArea',
+          shapeType: 'rect',
+          position: { x: 1, y: 1, w: 2, h: 1 },
+          style: {
+            fill: { color: '{{colors.white}}' },
+            line: { color: '{{colors.border}}', width: 1 }
+          }
+        },
+        {
+          type: 'text',
+          id: 'logoText',
+          position: { x: 1, y: 1, w: 2, h: 0.5 },
+          content: 'SAM',
+          style: {
+            fontSize: 24,
+            bold: true,
+            color: '{{colors.primary}}',
+            align: 'center'
+          }
+        },
+        {
+          type: 'text',
+          id: 'logoSubtext',
+          position: { x: 1, y: 1.5, w: 2, h: 0.5 },
+          content: 'Smart Automation Management',
+          style: {
+            fontSize: 10,
+            color: '{{colors.secondary}}',
+            align: 'center'
+          }
+        },
+        {
+          type: 'text',
+          id: 'mainTitle',
+          position: { x: 2, y: 3, w: 6, h: 1.5 },
+          content: '{{title}}',
+          placeholder: '{{title}}',
+          style: {
+            fontSize: 48,
+            bold: true,
+            color: '{{colors.white}}',
+            align: 'center'
+          }
+        },
+        {
+          type: 'text',
+          id: 'subtitle',
+          position: { x: 2, y: 4.8, w: 6, h: 0.8 },
+          content: 'SAM ERP 견적관리 시스템',
+          style: {
+            fontSize: 24,
+            color: '{{colors.white}}',
+            align: 'center'
+          }
+        },
+        {
+          type: 'text',
+          id: 'dateAndCompany',
+          position: { x: 7.5, y: 7, w: 2.5, h: 1.5 },
+          content: '{{date}}\\n\\n{{company}}',
+          placeholder: '{{date}}\\n\\n{{company}}',
+          style: {
+            fontSize: 12,
+            color: '{{colors.white}}',
+            align: 'right'
+          }
+        }
+      ]
+    });
+  }
+
+  /**
+   * 견적관리 메인 화면 템플릿
+   */
+  createMainScreenTemplate() {
+    this.template.slides.push({
+      slideNumber: 2,
+      type: 'main_screen',
+      name: '견적관리 메인',
+      layout: { width: 10, height: 7.5 },
+      elements: [
+        {
+          type: 'text',
+          id: 'pageTitle',
+          position: { x: 0.5, y: 0.3, w: 6, h: 0.6 },
+          content: '견적관리',
+          style: {
+            fontSize: 24,
+            bold: true,
+            color: '{{colors.secondary}}'
+          }
+        },
+        {
+          type: 'text',
+          id: 'pageDescription',
+          position: { x: 0.5, y: 0.9, w: 6, h: 0.4 },
+          content: '견적을 관리합니다',
+          style: {
+            fontSize: 14,
+            color: '{{colors.secondary}}'
+          }
+        },
+        {
+          type: 'shape',
+          id: 'filterArea',
+          shapeType: 'rect',
+          position: { x: 0.5, y: 1.5, w: 9, h: 1 },
+          style: {
+            fill: { color: '{{colors.headerBg}}' },
+            line: { color: '{{colors.border}}', width: 1 }
+          }
+        },
+        {
+          type: 'dynamicStats',
+          id: 'statsBoxes',
+          position: { x: 2, y: 2.8, w: 6, h: 1.2 },
+          dataSource: 'stats',
+          template: {
+            type: 'statBox',
+            width: 1.8,
+            spacing: 0.1
+          }
+        },
+        {
+          type: 'table',
+          id: 'estimateList',
+          position: { x: 0.5, y: 4.5, w: 9, h: 2.5 },
+          dataSource: 'estimates',
+          headers: ['견적번호', '거래처', '현장명', '견적자', '총 개소', '견적금액', '견적완료일', '입찰일', '상태', '작업'],
+          style: {
+            border: { pt: 1, color: '{{colors.border}}' },
+            fontSize: 10,
+            headerBg: '{{colors.headerBg}}'
+          }
+        }
+      ]
+    });
+  }
+
+  /**
+   * 견적 상세 화면 템플릿
+   */
+  createDetailScreenTemplate() {
+    this.template.slides.push({
+      slideNumber: 3,
+      type: 'detail_screen',
+      name: '견적 상세',
+      layout: { width: 10, height: 7.5 },
+      elements: [
+        {
+          type: 'text',
+          id: 'pageTitle',
+          position: { x: 0.5, y: 0.3, w: 6, h: 0.6 },
+          content: '견적 상세',
+          style: {
+            fontSize: 24,
+            bold: true,
+            color: '{{colors.secondary}}'
+          }
+        },
+        {
+          type: 'buttonGroup',
+          id: 'actionButtons',
+          position: { x: 4, y: 0.3, w: 4.5, h: 0.6 },
+          buttons: [
+            { text: '견적서 보기', action: 'viewEstimate' },
+            { text: '전자결재', action: 'approval' },
+            { text: '수정', action: 'edit' }
+          ]
+        },
+        {
+          type: 'infoSection',
+          id: 'estimateInfo',
+          position: { x: 0.5, y: 1.2, w: 9, h: 1.8 },
+          title: '견적 정보',
+          fields: [
+            { label: '견적번호', field: 'estimateNumber' },
+            { label: '견적자', field: 'estimator' },
+            { label: '견적금액', field: 'totalAmount', format: 'currency' },
+            { label: '상태', field: 'status' }
+          ]
+        },
+        {
+          type: 'infoSection',
+          id: 'siteInfo',
+          position: { x: 0.5, y: 3.2, w: 9, h: 1.8 },
+          title: '현장설명회 정보',
+          fields: [
+            { label: '현설번호', field: 'siteNumber' },
+            { label: '거래처명', field: 'clientName' },
+            { label: '현장설명회 일자', field: 'siteDate' },
+            { label: '참석자', field: 'attendee' }
+          ]
+        },
+        {
+          type: 'infoSection',
+          id: 'bidInfo',
+          position: { x: 0.5, y: 5.2, w: 9, h: 1.5 },
+          title: '입찰 정보',
+          fields: [
+            { label: '현장명', field: 'siteName' },
+            { label: '입찰일자', field: 'bidDate' },
+            { label: '개소', field: 'quantity' },
+            { label: '공사기간', field: 'constructionPeriod' }
+          ]
+        }
+      ]
+    });
+  }
+
+  /**
+   * 견적서 문서 (요약) 템플릿
+   */
+  createEstimateDocTemplate() {
+    this.template.slides.push({
+      slideNumber: 4,
+      type: 'estimate_document',
+      name: '견적서 문서 (요약)',
+      layout: { width: 10, height: 7.5 },
+      elements: [
+        {
+          type: 'text',
+          id: 'documentTitle',
+          position: { x: 3, y: 0.5, w: 4, h: 0.8 },
+          content: '견적서',
+          style: {
+            fontSize: 32,
+            bold: true,
+            color: '{{colors.secondary}}',
+            align: 'center'
+          }
+        },
+        {
+          type: 'text',
+          id: 'documentInfo',
+          position: { x: 3, y: 1.3, w: 4, h: 0.4 },
+          content: '문서번호: {{documentNumber}} | 작성일자: {{date}}',
+          placeholder: '문서번호: {{documentNumber}} | 작성일자: {{date}}',
+          style: {
+            fontSize: 12,
+            color: '{{colors.secondary}}',
+            align: 'center'
+          }
+        },
+        {
+          type: 'table',
+          id: 'companyInfoTable',
+          position: { x: 1, y: 2, w: 8, h: 2 },
+          dataSource: 'companyInfo',
+          template: 'companyInfoLayout'
+        },
+        {
+          type: 'text',
+          id: 'estimateIntro',
+          position: { x: 8, y: 3.7, w: 2, h: 0.4 },
+          content: '하기와 같이 見積합니다.',
+          style: {
+            fontSize: 12,
+            color: '{{colors.secondary}}',
+            align: 'center'
+          }
+        },
+        {
+          type: 'table',
+          id: 'summaryTable',
+          position: { x: 1, y: 4.5, w: 8, h: 1.5 },
+          dataSource: 'summary',
+          headers: ['명칭', '수량', '단위', '재료비', '노무비', '합계', '비고'],
+          template: 'summaryLayout'
+        },
+        {
+          type: 'text',
+          id: 'specialNotes',
+          position: { x: 1, y: 6.2, w: 8, h: 0.4 },
+          content: '* 특기사항: {{notes}}',
+          placeholder: '* 특기사항: {{notes}}',
+          style: {
+            fontSize: 11,
+            color: '{{colors.secondary}}'
+          }
+        }
+      ]
+    });
+  }
+
+  /**
+   * 견적서 문서 (상세) 템플릿
+   */
+  createEstimateDetailTemplate() {
+    this.template.slides.push({
+      slideNumber: 5,
+      type: 'estimate_detail',
+      name: '견적서 문서 (상세)',
+      layout: { width: 10, height: 7.5 },
+      elements: [
+        {
+          type: 'text',
+          id: 'detailTitle',
+          position: { x: 3, y: 0.5, w: 4, h: 0.6 },
+          content: '견적 상세 내역',
+          style: {
+            fontSize: 20,
+            bold: true,
+            color: '{{colors.secondary}}',
+            align: 'center'
+          }
+        },
+        {
+          type: 'table',
+          id: 'detailTable',
+          position: { x: 0.2, y: 1.5, w: 9.6, h: 4 },
+          dataSource: 'items',
+          headers: [
+            'NO', '명칭', '제품', '규격(mm)', '', '수량', '단위',
+            '재료비', '', '노무비', '', '합계', '', '비고'
+          ],
+          subHeaders: [
+            '', '', '', '가로(W)', '높이(H)', '', '',
+            '단가', '금액', '단가', '금액', '단가', '금액', ''
+          ],
+          template: 'detailItemLayout',
+          style: {
+            border: { pt: 1, color: '{{colors.border}}' },
+            fontSize: 8,
+            headerBg: '{{colors.headerBg}}'
+          }
+        }
+      ]
+    });
+  }
+
+  /**
+   * 템플릿을 JSON 파일로 저장
+   */
+  async saveTemplate(outputPath) {
+    const dir = path.dirname(outputPath);
+    await fs.mkdir(dir, { recursive: true });
+
+    await fs.writeFile(
+      outputPath,
+      JSON.stringify(this.template, null, 2),
+      'utf8'
+    );
+
+    console.log(`✅ 템플릿 저장 완료: ${outputPath}`);
+    return outputPath;
+  }
+
+  /**
+   * 범용 PDF 분석 (확장 가능)
+   */
+  async analyzeGenericPDF(inputPath) {
+    // TODO: 실제 PDF 파싱 로직 구현
+    console.log(`📖 범용 PDF 분석: ${inputPath}`);
+
+    // 기본 템플릿 구조 생성
+    this.template.metadata = {
+      source: path.basename(inputPath),
+      extractedAt: new Date().toISOString().split('T')[0],
+      title: "Generic Template",
+      type: "generic"
+    };
+
+    // 기본 스타일
+    this.template.styles = {
+      colors: {
+        primary: '0066CC',
+        secondary: '333333',
+        background: 'FFFFFF'
+      },
+      fonts: {
+        title: { face: 'Arial', size: 24, bold: true },
+        body: { face: 'Arial', size: 12 }
+      }
+    };
+
+    console.log('✅ 범용 PDF 분석 완료 (기본 템플릿)');
+    return this.template;
+  }
+}
+
+// 메인 실행 함수
+async function analyzeTemplate(inputPath, outputPath, type = 'sam') {
+  try {
+    console.log('🚀 PDF 템플릿 분석 시작');
+    console.log(`📄 입력: ${inputPath}`);
+    console.log(`📊 출력: ${outputPath}`);
+
+    const analyzer = new PDFTemplateAnalyzer();
+
+    let template;
+    if (type === 'sam') {
+      template = await analyzer.analyzeSAMEstimate(inputPath);
+    } else {
+      template = await analyzer.analyzeGenericPDF(inputPath);
+    }
+
+    await analyzer.saveTemplate(outputPath);
+    console.log('✅ 템플릿 분석 완료!');
+
+    return outputPath;
+
+  } catch (error) {
+    console.error('❌ 템플릿 분석 실패:', error.message);
+    throw error;
+  }
+}
+
+// 명령행 인수 처리
+async function main() {
+  const args = process.argv.slice(2);
+  const inputFlag = args.find(arg => arg.startsWith('--input='));
+  const outputFlag = args.find(arg => arg.startsWith('--output='));
+  const typeFlag = args.find(arg => arg.startsWith('--type='));
+
+  const inputPath = inputFlag ? inputFlag.split('=')[1] : 'pdf_sample/SAM_견적관리.pdf';
+  const outputPath = outputFlag ? outputFlag.split('=')[1] : 'templates/sam_estimate_template.json';
+  const type = typeFlag ? typeFlag.split('=')[1] : 'sam';
+
+  // 출력 디렉토리 생성
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+
+  await analyzeTemplate(inputPath, outputPath, type);
+}
+
+// 직접 실행시
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+module.exports = { analyzeTemplate, PDFTemplateAnalyzer };

.claude/skills/pdf-template-skill/scripts/generate-from-template.js

@@ -0,0 +1,453 @@
+/**
+ * 템플릿 기반 PPTX 생성기 - 템플릿과 데이터를 결합하여 PPTX 생성
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const PptxGenJS = require('pptxgenjs');
+
+// 템플릿 변수 처리 엔진
+class TemplateEngine {
+  constructor(data) {
+    this.data = data;
+  }
+
+  /**
+   * 템플릿 변수 치환
+   */
+  resolve(template) {
+    if (typeof template === 'string') {
+      return this.resolveString(template);
+    } else if (Array.isArray(template)) {
+      return template.map(item => this.resolve(item));
+    } else if (typeof template === 'object' && template !== null) {
+      const result = {};
+      for (const [key, value] of Object.entries(template)) {
+        result[key] = this.resolve(value);
+      }
+      return result;
+    }
+    return template;
+  }
+
+  /**
+   * 문자열 템플릿 변수 치환
+   */
+  resolveString(template) {
+    return template.replace(/\{\{([^}]+)\}\}/g, (match, path) => {
+      const value = this.getNestedValue(this.data, path.trim());
+      return value !== undefined ? value : match;
+    });
+  }
+
+  /**
+   * 중첩 객체 값 추출
+   */
+  getNestedValue(obj, path) {
+    return path.split('.').reduce((current, key) => {
+      return current && current[key] !== undefined ? current[key] : undefined;
+    }, obj);
+  }
+
+  /**
+   * 숫자 포맷팅
+   */
+  formatNumber(value, format) {
+    if (format === 'currency') {
+      return '₩' + value.toLocaleString();
+    }
+    return value.toString();
+  }
+
+  /**
+   * 날짜 포맷팅
+   */
+  formatDate(value, format = 'YYYY-MM-DD') {
+    const date = new Date(value);
+    return date.toISOString().split('T')[0];
+  }
+}
+
+// 템플릿 기반 PPTX 생성기
+class TemplatePPTXGenerator {
+  constructor() {
+    this.pptx = new PptxGenJS();
+    this.pptx.layout = 'LAYOUT_16x9';
+  }
+
+  /**
+   * 템플릿을 기반으로 PPTX 생성
+   */
+  async generateFromTemplate(templatePath, dataPath) {
+    console.log('📊 템플릿 기반 PPTX 생성 중...');
+
+    // 템플릿과 데이터 로드
+    const template = await this.loadTemplate(templatePath);
+    const data = await this.loadData(dataPath);
+
+    // 템플릿 엔진 초기화
+    const engine = new TemplateEngine(data);
+
+    // 색상 및 스타일 준비
+    const resolvedStyles = engine.resolve(template.styles);
+    this.colors = resolvedStyles.colors;
+    this.fonts = resolvedStyles.fonts;
+
+    // 각 슬라이드 생성
+    for (const slideTemplate of template.slides) {
+      await this.createSlideFromTemplate(slideTemplate, engine);
+    }
+
+    console.log(`✅ 템플릿 기반 PPTX 생성 완료: ${template.slides.length}개 슬라이드`);
+    return this.pptx;
+  }
+
+  /**
+   * 템플릿 파일 로드
+   */
+  async loadTemplate(templatePath) {
+    const content = await fs.readFile(templatePath, 'utf8');
+    return JSON.parse(content);
+  }
+
+  /**
+   * 데이터 파일 로드
+   */
+  async loadData(dataPath) {
+    const content = await fs.readFile(dataPath, 'utf8');
+    return JSON.parse(content);
+  }
+
+  /**
+   * 슬라이드 템플릿을 기반으로 슬라이드 생성
+   */
+  async createSlideFromTemplate(slideTemplate, engine) {
+    const slide = this.pptx.addSlide();
+
+    console.log(`📄 슬라이드 ${slideTemplate.slideNumber}: ${slideTemplate.name}`);
+
+    // 각 요소 생성
+    for (const element of slideTemplate.elements) {
+      await this.createElement(slide, element, engine);
+    }
+  }
+
+  /**
+   * 요소 생성
+   */
+  async createElement(slide, element, engine) {
+    const resolvedElement = engine.resolve(element);
+
+    switch (element.type) {
+      case 'background':
+        this.createBackground(slide, resolvedElement);
+        break;
+
+      case 'text':
+        this.createText(slide, resolvedElement);
+        break;
+
+      case 'shape':
+        this.createShape(slide, resolvedElement);
+        break;
+
+      case 'table':
+        this.createTable(slide, resolvedElement, engine);
+        break;
+
+      case 'buttonGroup':
+        this.createButtonGroup(slide, resolvedElement);
+        break;
+
+      case 'infoSection':
+        this.createInfoSection(slide, resolvedElement, engine);
+        break;
+
+      case 'dynamicStats':
+        this.createDynamicStats(slide, resolvedElement, engine);
+        break;
+
+      default:
+        console.log(`⚠️ 미지원 요소 타입: ${element.type}`);
+    }
+  }
+
+  /**
+   * 배경 생성
+   */
+  createBackground(slide, element) {
+    slide.background = { color: element.style.color };
+  }
+
+  /**
+   * 텍스트 생성
+   */
+  createText(slide, element) {
+    const options = {
+      x: element.position.x,
+      y: element.position.y,
+      w: element.position.w,
+      h: element.position.h,
+      ...element.style
+    };
+
+    slide.addText(element.content || element.placeholder || '', options);
+  }
+
+  /**
+   * 도형 생성
+   */
+  createShape(slide, element) {
+    const options = {
+      x: element.position.x,
+      y: element.position.y,
+      w: element.position.w,
+      h: element.position.h,
+      ...element.style
+    };
+
+    slide.addShape(element.shapeType || 'rect', options);
+  }
+
+  /**
+   * 테이블 생성
+   */
+  createTable(slide, element, engine) {
+    let tableData = [];
+
+    // 헤더 추가
+    if (element.headers) {
+      tableData.push(element.headers);
+      if (element.subHeaders) {
+        tableData.push(element.subHeaders);
+      }
+    }
+
+    // 데이터 소스에서 행 생성
+    if (element.dataSource) {
+      const sourceData = engine.getNestedValue(engine.data, element.dataSource);
+      if (Array.isArray(sourceData)) {
+        sourceData.forEach((item, index) => {
+          const row = this.generateTableRow(element, item, index, engine);
+          tableData.push(row);
+        });
+      }
+    }
+
+    const options = {
+      x: element.position.x,
+      y: element.position.y,
+      w: element.position.w,
+      h: element.position.h,
+      border: { pt: 1, color: '757575' },
+      fontSize: 10,
+      margin: 0.1,
+      ...element.style
+    };
+
+    slide.addTable(tableData, options);
+  }
+
+  /**
+   * 테이블 행 생성
+   */
+  generateTableRow(element, item, index, engine) {
+    if (element.template === 'detailItemLayout') {
+      return [
+        (index + 1).toString(),
+        item.name || '',
+        item.product || '',
+        item.width ? item.width.toLocaleString() : '',
+        item.height ? item.height.toLocaleString() : '',
+        item.quantity ? item.quantity.toString() : '',
+        item.unit || '',
+        item.materialCost ? engine.formatNumber(item.materialCost, 'currency') : '',
+        item.materialCost && item.quantity ?
+          engine.formatNumber(item.materialCost * item.quantity, 'currency') : '',
+        item.laborCost ? engine.formatNumber(item.laborCost, 'currency') : '',
+        item.laborCost && item.quantity ?
+          engine.formatNumber(item.laborCost * item.quantity, 'currency') : '',
+        item.totalCost ? engine.formatNumber(item.totalCost, 'currency') : '',
+        item.totalCost && item.quantity ?
+          engine.formatNumber(item.totalCost * item.quantity, 'currency') : '',
+        item.memo || ''
+      ];
+    }
+
+    // 기본 행 생성
+    return Object.values(item);
+  }
+
+  /**
+   * 버튼 그룹 생성
+   */
+  createButtonGroup(slide, element) {
+    element.buttons.forEach((button, index) => {
+      const xPos = element.position.x + index * 1.5;
+
+      // 버튼 배경
+      slide.addShape('rect', {
+        x: xPos,
+        y: element.position.y,
+        w: 1.3,
+        h: element.position.h,
+        fill: { color: this.colors.primary },
+        line: { color: this.colors.primary, width: 1 }
+      });
+
+      // 버튼 텍스트
+      slide.addText(button.text, {
+        x: xPos,
+        y: element.position.y,
+        w: 1.3,
+        h: element.position.h,
+        fontSize: 12,
+        bold: true,
+        color: 'FFFFFF',
+        align: 'center'
+      });
+    });
+  }
+
+  /**
+   * 정보 섹션 생성
+   */
+  createInfoSection(slide, element, engine) {
+    // 섹션 배경
+    slide.addShape('rect', {
+      x: element.position.x,
+      y: element.position.y,
+      w: element.position.w,
+      h: element.position.h,
+      fill: { color: 'FFFFFF' },
+      line: { color: 'CCCCCC', width: 1 }
+    });
+
+    // 섹션 제목
+    slide.addText(element.title, {
+      x: element.position.x + 0.2,
+      y: element.position.y + 0.2,
+      w: element.position.w - 0.4,
+      h: 0.4,
+      fontSize: 14,
+      bold: true,
+      color: '333333'
+    });
+
+    // 필드들
+    element.fields.forEach((field, index) => {
+      const row = Math.floor(index / 2);
+      const col = index % 2;
+      const xPos = element.position.x + 0.5 + col * 4;
+      const yPos = element.position.y + 0.8 + row * 0.6;
+
+      const value = engine.getNestedValue(engine.data, field.field);
+      const formattedValue = field.format === 'currency' ?
+        engine.formatNumber(value, 'currency') : value;
+
+      slide.addText(`${field.label}: ${formattedValue || ''}`, {
+        x: xPos,
+        y: yPos,
+        w: 3.5,
+        h: 0.4,
+        fontSize: 11,
+        color: '333333'
+      });
+    });
+  }
+
+  /**
+   * 동적 통계 박스 생성
+   */
+  createDynamicStats(slide, element, engine) {
+    const statsData = engine.getNestedValue(engine.data, element.dataSource) || [
+      { label: '전체 견적', value: '9', color: this.colors.primary },
+      { label: '견적대기', value: '5', color: 'CC0000' },
+      { label: '견적완료', value: '4', color: '008000' }
+    ];
+
+    statsData.forEach((stat, index) => {
+      const xPos = element.position.x + index * 2;
+
+      // 통계 박스
+      slide.addShape('rect', {
+        x: xPos,
+        y: element.position.y,
+        w: element.template.width,
+        h: element.position.h,
+        fill: { color: 'FFFFFF' },
+        line: { color: 'CCCCCC', width: 1 }
+      });
+
+      // 통계 값
+      slide.addText(stat.value, {
+        x: xPos,
+        y: element.position.y + 0.2,
+        w: element.template.width,
+        h: 0.8,
+        fontSize: 24,
+        bold: true,
+        color: stat.color,
+        align: 'center'
+      });
+
+      // 통계 라벨
+      slide.addText(stat.label, {
+        x: xPos,
+        y: element.position.y + 0.8,
+        w: element.template.width,
+        h: 0.4,
+        fontSize: 12,
+        color: '333333',
+        align: 'center'
+      });
+    });
+  }
+}
+
+// 메인 실행 함수
+async function generateFromTemplate(templatePath, dataPath, outputPath) {
+  try {
+    console.log('🚀 템플릿 기반 PPTX 생성 시작');
+    console.log(`📋 템플릿: ${templatePath}`);
+    console.log(`📊 데이터: ${dataPath}`);
+    console.log(`📄 출력: ${outputPath}`);
+
+    const generator = new TemplatePPTXGenerator();
+    const pptx = await generator.generateFromTemplate(templatePath, dataPath);
+
+    // 파일 저장
+    await pptx.writeFile({ fileName: outputPath });
+    console.log('✅ 템플릿 기반 PPTX 생성 완료!');
+
+    return outputPath;
+
+  } catch (error) {
+    console.error('❌ 생성 실패:', error.message);
+    throw error;
+  }
+}
+
+// 명령행 인수 처리
+async function main() {
+  const args = process.argv.slice(2);
+  const templateFlag = args.find(arg => arg.startsWith('--template='));
+  const dataFlag = args.find(arg => arg.startsWith('--data='));
+  const outputFlag = args.find(arg => arg.startsWith('--output='));
+
+  const templatePath = templateFlag ? templateFlag.split('=')[1] : 'templates/sam_estimate_template.json';
+  const dataPath = dataFlag ? dataFlag.split('=')[1] : 'data/sample_estimate_data.json';
+  const outputPath = outputFlag ? outputFlag.split('=')[1] : 'pptx/template_generated.pptx';
+
+  // 출력 디렉토리 생성
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+
+  await generateFromTemplate(templatePath, dataPath, outputPath);
+}
+
+// 직접 실행시
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+module.exports = { generateFromTemplate, TemplatePPTXGenerator, TemplateEngine };

.claude/skills/ppt-auto-generator/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: ppt-auto-generator
+description: 마크다운 또는 텍스트 아웃라인에서 PowerPoint 프레젠테이션을 생성합니다. PPT 생성, 슬라이드 제작, 발표자료 작성 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# PPT Auto Generator
+
+마크다운이나 텍스트 아웃라인을 기반으로 PowerPoint 프레젠테이션을 생성하는 스킬입니다.
+
+## 기능
+
+### 입력 형식
+- 마크다운 문서
+- 텍스트 아웃라인
+- 구조화된 데이터 (JSON/YAML)
+
+### 생성 요소
+- 제목 슬라이드
+- 목차 슬라이드
+- 콘텐츠 슬라이드
+- 불릿 포인트
+- 이미지 플레이스홀더
+- 차트 및 표
+- 요약 슬라이드
+
+### 출력 형식
+- Python-pptx 스크립트
+- HTML 슬라이드 (reveal.js)
+- 마크다운 슬라이드 (Marp)
+
+## 마크다운 입력 형식
+
+```markdown
+# 프레젠테이션 제목
+
+## 슬라이드 1: 소개
+- 첫 번째 포인트
+- 두 번째 포인트
+- 세 번째 포인트
+
+## 슬라이드 2: 주요 내용
+### 섹션 A
+- 내용 1
+- 내용 2
+
+### 섹션 B
+- 내용 3
+- 내용 4
+
+## 슬라이드 3: 데이터
+| 항목 | 값 |
+|------|-----|
+| A | 100 |
+| B | 200 |
+
+## 슬라이드 4: 결론
+- 핵심 메시지
+- 다음 단계
+```
+
+## Python-pptx 템플릿
+
+```python
+from pptx import Presentation
+from pptx.util import Inches, Pt
+from pptx.enum.text import PP_ALIGN
+
+def create_presentation(content):
+    prs = Presentation()
+
+    # 제목 슬라이드
+    title_slide = prs.slides.add_slide(prs.slide_layouts[0])
+    title_slide.shapes.title.text = content['title']
+    title_slide.placeholders[1].text = content['subtitle']
+
+    # 콘텐츠 슬라이드
+    for slide_content in content['slides']:
+        slide = prs.slides.add_slide(prs.slide_layouts[1])
+        slide.shapes.title.text = slide_content['title']
+
+        body = slide.placeholders[1]
+        tf = body.text_frame
+
+        for point in slide_content['points']:
+            p = tf.add_paragraph()
+            p.text = point
+            p.level = 0
+
+    prs.save('output.pptx')
+    return 'output.pptx'
+```
+
+## Marp 마크다운 템플릿
+
+```markdown
+---
+marp: true
+theme: default
+paginate: true
+---
+
+# 프레젠테이션 제목
+
+발표자: 이름
+날짜: 2024-01-15
+
+---
+
+## 목차
+
+1. 소개
+2. 주요 내용
+3. 결론
+
+---
+
+## 소개
+
+- 배경 설명
+- 목적
+- 범위
+
+---
+
+## 주요 내용
+
+### 핵심 포인트
+
+- 첫 번째
+- 두 번째
+- 세 번째
+
+---
+
+## 결론
+
+- 요약
+- 다음 단계
+- Q&A
+```
+
+## Reveal.js HTML 템플릿
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/reveal.js/dist/reveal.css">
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/reveal.js/dist/theme/white.css">
+</head>
+<body>
+    <div class="reveal">
+        <div class="slides">
+            <section>
+                <h1>제목</h1>
+                <p>부제목</p>
+            </section>
+            <section>
+                <h2>슬라이드 제목</h2>
+                <ul>
+                    <li>포인트 1</li>
+                    <li>포인트 2</li>
+                </ul>
+            </section>
+        </div>
+    </div>
+    <script src="https://cdn.jsdelivr.net/npm/reveal.js/dist/reveal.js"></script>
+    <script>Reveal.initialize();</script>
+</body>
+</html>
+```
+
+## 사용 예시
+
+```
+이 마크다운을 PPT로 만들어줘
+발표자료를 슬라이드로 변환해줘
+프로젝트 소개 PPT를 생성해줘
+```
+
+## 필요 패키지
+
+```bash
+# Python
+pip install python-pptx
+
+# Node.js (Marp)
+npm install @marp-team/marp-cli
+```
+
+## 출처
+Original skill from skills.cokac.com

.claude/skills/pptx-skill/SKILL.md

@@ -0,0 +1,434 @@
+---
+name: pptx-skill
+description: HTML 슬라이드를 PowerPoint(PPTX) 파일로 변환합니다. PPTX 생성, PPT 변환, 프레젠테이션 만들기, 슬라이드를 파워포인트로 요청 시 사용합니다.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# PPTX Skill - PowerPoint 프레젠테이션 생성
+
+PowerPoint 프레젠테이션 파일(.pptx)을 생성하는 스킬입니다.
+두 가지 방법을 제공하며, **방법 A (Direct PptxGenJS)를 우선 사용**합니다.
+
+## 방법 선택 가이드
+
+| | 방법 A: Direct PptxGenJS (권장) | 방법 B: HTML → PPTX |
+|---|---|---|
+| **의존성** | Node.js + pptxgenjs만 필요 | Playwright + Chromium 브라우저 필요 |
+| **원리** | JS 코드로 도형/텍스트 직접 배치 | HTML을 브라우저 렌더링 후 변환 |
+| **PPT 편집** | 생성 후 텍스트/도형 직접 수정 가능 | 이미지 기반이라 수정 어려움 |
+| **한글 폰트** | PPT 뷰어 폰트 사용 (깨짐 없음) | 시스템 폰트 필요 |
+| **환경 제약** | 없음 | Chromium 시스템 라이브러리 필요 |
+| **적합한 경우** | 대부분의 프레젠테이션 | 복잡한 CSS 레이아웃이 필요할 때 |
+
+---
+
+## 방법 A: Direct PptxGenJS (권장)
+
+PptxGenJS API를 직접 호출하여 네이티브 PPTX 요소를 생성합니다.
+브라우저 없이 Node.js만으로 동작하며, 생성된 PPT에서 텍스트/도형 편집이 가능합니다.
+
+### 사용법
+
+#### 1단계: .cjs 변환 스크립트 작성
+
+**주의**: 프로젝트에 `"type": "module"`이 설정된 경우 `.cjs` 확장자를 사용해야 합니다.
+
+```javascript
+// convert.cjs
+const path = require('path');
+module.paths.unshift(path.join(require('os').homedir(), '.claude/skills/pptx-skill/scripts/node_modules'));
+
+const PptxGenJS = require('pptxgenjs');
+
+async function main() {
+    const pres = new PptxGenJS();
+
+    // 커스텀 레이아웃 정의 (16:9 = 10" x 5.625")
+    pres.defineLayout({ name: 'CUSTOM_16x9', width: 10, height: 5.625 });
+    pres.layout = 'CUSTOM_16x9';
+
+    // --- 슬라이드 1 ---
+    const slide1 = pres.addSlide();
+    slide1.background = { fill: '1a1a2e' };
+
+    slide1.addText('제목', {
+        x: 1, y: 2, w: 8, h: 1,
+        fontSize: 32, bold: true, color: 'FFFFFF',
+        align: 'center', fontFace: 'Arial'
+    });
+
+    // --- 저장 ---
+    await pres.writeFile({ fileName: 'output.pptx' });
+    console.log('PPTX created!');
+}
+
+main().catch(console.error);
+```
+
+#### 2단계: 실행
+
+```bash
+node convert.cjs
+```
+
+#### 3단계: 결과 확인 (선택)
+
+```bash
+python ~/.claude/skills/pptx-skill/scripts/thumbnail.py output.pptx thumbnail-grid
+```
+
+### 핵심 규칙
+
+#### 색상 코드 (매우 중요)
+PptxGenJS에서 색상 코드는 반드시 `#` 없이 사용해야 합니다.
+
+```javascript
+// ✅ 올바른 사용
+{ color: 'FF0000' }
+{ fill: { color: '1e3a5f' } }
+
+// ❌ 잘못된 사용 - 파일 손상 유발
+{ color: '#FF0000' }
+```
+
+#### 좌표 체계
+모든 위치/크기는 **인치(inch)** 단위입니다.
+
+```
+슬라이드 크기: width=10, height=5.625 (16:9)
+좌표 원점: 좌측 상단 (0, 0)
+
+x: 좌측에서의 거리
+y: 상단에서의 거리
+w: 너비
+h: 높이
+```
+
+### PptxGenJS API 빠른 참조
+
+#### 슬라이드 배경
+```javascript
+slide.background = { fill: '1a1a2e' };               // 단색
+slide.background = { path: 'background.png' };        // 이미지
+```
+
+#### 텍스트 추가
+```javascript
+// 단순 텍스트
+slide.addText('제목', {
+    x: 0.5, y: 0.5, w: 9, h: 1,
+    fontSize: 36, bold: true, color: '1a1a2e',
+    align: 'center',       // left, center, right
+    valign: 'middle',      // top, middle, bottom
+    fontFace: 'Arial'
+});
+
+// 복합 텍스트 (여러 스타일 혼합)
+slide.addText([
+    { text: '굵은 텍스트', options: { bold: true, color: 'FF0000', fontSize: 14 } },
+    { text: ' 일반 텍스트', options: { color: '333333', fontSize: 14 } }
+], { x: 1, y: 2, w: 8, h: 0.5, fontFace: 'Arial' });
+
+// 줄바꿈
+slide.addText([
+    { text: '첫째 줄', options: { fontSize: 14, bold: true, color: 'FFFFFF' } },
+    { text: '\n둘째 줄', options: { fontSize: 9, color: 'CCCCCC' } }
+], { x: 1, y: 2, w: 4, h: 0.7, align: 'center', valign: 'middle', fontFace: 'Arial' });
+```
+
+#### 도형 추가
+```javascript
+// 사각형
+slide.addShape(pres.ShapeType.rect, {
+    x: 0.5, y: 1, w: 3, h: 2,
+    fill: { color: '1e3a5f' },
+    line: { color: '333333', width: 1 }
+});
+
+// 둥근 사각형
+slide.addShape(pres.ShapeType.roundRect, {
+    x: 1, y: 1, w: 4, h: 0.5,
+    rectRadius: 0.1,
+    fill: { color: 'F0FAF0' },
+    line: { color: 'C8E6C9', width: 0.5 }
+});
+
+// 원/타원
+slide.addShape(pres.ShapeType.ellipse, {
+    x: 2, y: 2, w: 0.5, h: 0.5,
+    fill: { color: '4CAF50' }
+});
+```
+
+#### 이미지 추가
+```javascript
+slide.addImage({
+    path: 'image.png',    // 파일 경로
+    x: 1, y: 2, w: 4, h: 3
+});
+
+slide.addImage({
+    data: 'base64...',    // Base64 인코딩
+    x: 1, y: 2, w: 4, h: 3
+});
+```
+
+#### 차트 추가
+```javascript
+slide.addChart(pres.ChartType.bar, [{
+    name: '시리즈 1',
+    labels: ['A', 'B', 'C'],
+    values: [10, 20, 30]
+}], { x: 1, y: 2, w: 8, h: 4 });
+
+slide.addChart(pres.ChartType.pie, [...], {...});
+slide.addChart(pres.ChartType.line, [...], {...});
+```
+
+### 디자인 패턴 (자주 사용하는 구성요소)
+
+#### 헤더 바 + 제목
+```javascript
+slide.addShape(pres.ShapeType.rect, {
+    x: 0.5, y: 0.35, w: 0.06, h: 0.35,
+    fill: { color: '4CAF50' }
+});
+slide.addText('페이지 제목', {
+    x: 0.7, y: 0.3, w: 5, h: 0.45,
+    fontSize: 18, bold: true, color: '1a1a2e', fontFace: 'Arial'
+});
+```
+
+#### 배지/태그
+```javascript
+slide.addShape(pres.ShapeType.roundRect, {
+    x: 5, y: 0.35, w: 1, h: 0.3,
+    rectRadius: 0.04,
+    fill: { color: 'E8F5E9' }
+});
+slide.addText('총 28%', {
+    x: 5, y: 0.35, w: 1, h: 0.3,
+    fontSize: 8, bold: true, color: '2E7D32',
+    align: 'center', fontFace: 'Arial'
+});
+```
+
+#### 카드 (배경 + 제목 + 항목)
+```javascript
+// 카드 배경
+slide.addShape(pres.ShapeType.roundRect, {
+    x: 0.5, y: 1.5, w: 4, h: 3,
+    rectRadius: 0.15,
+    fill: { color: 'F0FAF0' },
+    line: { color: '4CAF50', width: 1.5 }
+});
+// 카드 내부 항목 (흰색 행)
+slide.addShape(pres.ShapeType.roundRect, {
+    x: 0.7, y: 2.3, w: 3.6, h: 0.4,
+    rectRadius: 0.06,
+    fill: { color: 'FFFFFF' }
+});
+slide.addText('항목명', { x: 0.8, y: 2.3, w: 2, h: 0.4, fontSize: 10, color: '333333', fontFace: 'Arial' });
+slide.addText('값', { x: 2.8, y: 2.3, w: 1.4, h: 0.4, fontSize: 14, bold: true, color: '4CAF50', align: 'right', fontFace: 'Arial' });
+```
+
+#### 넘버 서클
+```javascript
+slide.addShape(pres.ShapeType.ellipse, {
+    x: 1, y: 1, w: 0.45, h: 0.45,
+    fill: { color: '2196F3' }
+});
+slide.addText('1', {
+    x: 1, y: 1, w: 0.45, h: 0.45,
+    fontSize: 14, bold: true, color: 'FFFFFF',
+    align: 'center', valign: 'middle', fontFace: 'Arial'
+});
+```
+
+#### 비율 바 (프로그레스 형태)
+```javascript
+// 큰 비율
+slide.addShape(pres.ShapeType.roundRect, {
+    x: 0.5, y: 1, w: 6.4, h: 0.7,
+    rectRadius: 0.1, fill: { color: '4CAF50' }
+});
+slide.addText([
+    { text: '20%', options: { fontSize: 20, bold: true, color: 'FFFFFF' } },
+    { text: '\n판매자 수당', options: { fontSize: 9, color: 'DDFFDD' } }
+], { x: 0.5, y: 1, w: 6.4, h: 0.7, align: 'center', valign: 'middle', fontFace: 'Arial' });
+
+// 작은 비율
+slide.addShape(pres.ShapeType.roundRect, {
+    x: 7, y: 1, w: 1.6, h: 0.7,
+    rectRadius: 0.1, fill: { color: '2196F3' }
+});
+```
+
+#### 반복 카드 생성 (데이터 기반)
+```javascript
+const cards = [
+    { title: '항목 A', color: '4CAF50', bg: 'F0FAF0', border: 'C8E6C9', items: [['라벨1', '값1'], ['라벨2', '값2']] },
+    { title: '항목 B', color: '2196F3', bg: 'E3F2FD', border: 'BBDEFB', items: [['라벨1', '값1'], ['라벨2', '값2']] },
+];
+const cardW = 2.85;
+cards.forEach((card, i) => {
+    const x = 0.5 + i * (cardW + 0.2);
+    const y = 1.9;
+    // 카드 배경
+    slide.addShape(pres.ShapeType.roundRect, { x, y, w: cardW, h: 3, rectRadius: 0.1, fill: { color: card.bg }, line: { color: card.border, width: 0.5 } });
+    // 카드 제목
+    slide.addText(card.title, { x: x + 0.2, y: y + 0.1, w: cardW - 0.4, h: 0.3, fontSize: 11, bold: true, color: card.color, fontFace: 'Arial' });
+    // 항목 반복
+    card.items.forEach((item, j) => {
+        const iy = y + 0.5 + j * 0.7;
+        slide.addShape(pres.ShapeType.roundRect, { x: x + 0.1, y: iy, w: cardW - 0.2, h: 0.55, rectRadius: 0.05, fill: { color: 'FFFFFF' } });
+        slide.addText(item[0], { x: x + 0.2, y: iy + 0.03, w: cardW - 0.4, h: 0.2, fontSize: 8, color: '999999', fontFace: 'Arial' });
+        slide.addText(item[1], { x: x + 0.2, y: iy + 0.25, w: cardW - 0.4, h: 0.2, fontSize: 10, bold: true, color: '333333', fontFace: 'Arial' });
+    });
+});
+```
+
+#### 대외비 스탬프
+```javascript
+function addConfidentialBadge(slide) {
+    slide.addShape(pres.ShapeType.roundRect, { x: 8.3, y: 0.15, w: 1.4, h: 0.35, rectRadius: 0.04, fill: { color: 'D32F2F' } });
+    slide.addText('CONFIDENTIAL', { x: 8.3, y: 0.12, w: 1.4, h: 0.22, fontSize: 7, bold: true, color: 'FFFFFF', align: 'center', fontFace: 'Arial' });
+    slide.addText('대 외 비', { x: 8.3, y: 0.28, w: 1.4, h: 0.22, fontSize: 8, bold: true, color: 'FFCDD2', align: 'center', fontFace: 'Arial' });
+}
+// 각 슬라이드에 적용
+addConfidentialBadge(slide1);
+```
+
+#### 어두운 배경 테이블
+```javascript
+// 테이블 컨테이너
+slide.addShape(pres.ShapeType.roundRect, { x: 5, y: 2.7, w: 4.5, h: 2.5, rectRadius: 0.1, fill: { color: '1a1a2e' } });
+// 헤더
+slide.addText('구분', { x: 5.2, y: 3.0, w: 1.5, h: 0.25, fontSize: 8, color: '888888', fontFace: 'Arial' });
+slide.addText('값 A', { x: 6.7, y: 3.0, w: 1.2, h: 0.25, fontSize: 8, bold: true, color: '4CAF50', align: 'center', fontFace: 'Arial' });
+// 구분선
+slide.addShape(pres.ShapeType.rect, { x: 5.2, y: 3.25, w: 4, h: 0.01, fill: { color: '333344' } });
+// 데이터 행
+slide.addText('항목', { x: 5.2, y: 3.35, w: 1.5, h: 0.3, fontSize: 9, color: 'CCCCCC', fontFace: 'Arial' });
+slide.addText('20%', { x: 6.7, y: 3.35, w: 1.2, h: 0.3, fontSize: 10, bold: true, color: '4CAF50', align: 'center', fontFace: 'Arial' });
+```
+
+### 슬라이드 크기 참조
+
+| 비율 | 크기 (pt) | 크기 (inch) | defineLayout |
+|------|-----------|-------------|--------------|
+| 16:9 | 720 x 405 | 10 x 5.625 | `{ width: 10, height: 5.625 }` |
+| 4:3 | 720 x 540 | 10 x 7.5 | `{ width: 10, height: 7.5 }` |
+| 16:10 | 720 x 450 | 10 x 6.25 | `{ width: 10, height: 6.25 }` |
+
+**중요**: `LAYOUT_WIDE`는 13.3" x 7.5"이므로 사용하지 마세요. 반드시 커스텀 레이아웃을 정의하세요.
+
+---
+
+## 방법 B: HTML → PPTX 변환 (Playwright 필요)
+
+HTML 슬라이드를 Playwright 브라우저로 렌더링하여 PPTX로 변환합니다.
+복잡한 CSS 레이아웃(flexbox, grid, 그라데이션)이 필요한 경우에 사용합니다.
+
+**전제 조건**: Playwright + Chromium 브라우저 + 시스템 라이브러리가 설치되어 있어야 합니다.
+```bash
+cd ~/.claude/skills/pptx-skill/scripts && npm install playwright pptxgenjs sharp
+npx playwright install chromium
+npx playwright install-deps chromium  # 시스템 라이브러리 (sudo 필요)
+```
+
+### 사용법
+
+#### 1단계: HTML 슬라이드 준비
+
+```bash
+ls slides/*.html
+```
+
+각 HTML 파일 규격:
+- 크기: 720pt x 405pt (16:9 비율)
+- 인코딩: UTF-8
+- 폰트: 웹 안전 폰트 사용
+
+#### 2단계: 변환 스크립트 작성 및 실행
+
+```javascript
+const path = require('path');
+module.paths.unshift(path.join(require('os').homedir(), '.claude/skills/pptx-skill/scripts/node_modules'));
+
+const PptxGenJS = require('pptxgenjs');
+const html2pptx = require(path.join(require('os').homedir(), '.claude/skills/pptx-skill/scripts/html2pptx.js'));
+
+const pres = new PptxGenJS();
+pres.defineLayout({ name: 'CUSTOM_16x9', width: 10, height: 5.625 });
+pres.layout = 'CUSTOM_16x9';
+
+await html2pptx('slides/slide-01.html', pres);
+await html2pptx('slides/slide-02.html', pres);
+
+await pres.writeFile({ fileName: 'presentation.pptx' });
+```
+
+#### 3단계: 결과 확인
+
+```bash
+python ~/.claude/skills/pptx-skill/scripts/thumbnail.py output.pptx thumbnail-grid
+```
+
+### HTML 작성 규칙 (방법 B 전용)
+
+1. **텍스트 요소에 border/background 금지** - div로 감싸기
+2. **불릿 기호(-, *, ., .)로 시작하는 텍스트 금지** - ul/ol 사용
+3. **모든 텍스트는 p/h1-h6 태그로 감싸기**
+4. **table 태그 사용 금지** - div + flexbox로 대체
+5. **HTML body 크기와 PptxGenJS 레이아웃 일치 필수**
+6. **빈 값 표시 시 하이픈(-) 금지** - 빈 문자열 또는 N/A 사용
+
+---
+
+## 공통 유틸리티
+
+### thumbnail.py - 미리보기 생성
+
+```bash
+python ~/.claude/skills/pptx-skill/scripts/thumbnail.py presentation.pptx output-thumbnail
+```
+
+옵션:
+- `--cols N`: 열 수 (기본 5, 범위 3-6)
+- `--outline-placeholders`: 플레이스홀더 영역 표시
+
+### pack.py / unpack.py - PPTX XML 편집
+
+```bash
+# PPTX 언패킹 (XML로 분해)
+python ~/.claude/skills/pptx-skill/ooxml/scripts/unpack.py presentation.pptx output_dir
+
+# PPTX 패킹 (XML을 PPTX로 조립)
+python ~/.claude/skills/pptx-skill/ooxml/scripts/pack.py input_dir presentation.pptx
+
+# 구조 검증
+python ~/.claude/skills/pptx-skill/ooxml/scripts/validate.py unpacked_dir --original presentation.pptx
+```
+
+## 필수 의존성
+
+### Node.js 패키지 (방법 A/B 공통)
+```bash
+cd ~/.claude/skills/pptx-skill/scripts && npm install pptxgenjs
+```
+
+### 추가 패키지 (방법 B만)
+```bash
+cd ~/.claude/skills/pptx-skill/scripts && npm install playwright sharp
+```
+
+### Python 패키지 (thumbnail/ooxml 사용 시)
+```bash
+pip install pillow defusedxml
+```
+
+## 추가 문서
+
+- [html2pptx.md](html2pptx.md) - HTML to PPTX 변환 상세 가이드 (방법 B)
+- [ooxml.md](ooxml.md) - Office Open XML 기술 참조

.claude/skills/pptx-skill/html2pptx.md

@@ -0,0 +1,769 @@
+# HTML to PowerPoint Guide
+
+Convert HTML slides to PowerPoint presentations with accurate positioning using the `html2pptx.js` library.
+
+## Table of Contents
+
+1. [Creating HTML Slides](#creating-html-slides)
+2. [Using the html2pptx Library](#using-the-html2pptx-library)
+3. [Using PptxGenJS](#using-pptxgenjs)
+
+---
+
+## Creating HTML Slides
+
+Every HTML slide must include proper body dimensions:
+
+### Layout Dimensions
+
+- **16:9** (default): `width: 720pt; height: 405pt`
+- **4:3**: `width: 720pt; height: 540pt`
+- **16:10**: `width: 720pt; height: 450pt`
+
+### Supported Elements
+
+- `<p>`, `<h1>`-`<h6>` - Text with styling
+- `<ul>`, `<ol>` - Lists (never use manual bullets •, -, *)
+- `<b>`, `<strong>` - Bold text (inline formatting)
+- `<i>`, `<em>` - Italic text (inline formatting)
+- `<u>` - Underlined text (inline formatting)
+- `<span>` - Inline formatting with CSS styles (bold, italic, underline, color)
+- `<br>` - Line breaks
+- `<div>` with bg/border - Becomes shape
+- `<img>` - Images
+- `class="placeholder"` - Reserved space for charts (returns `{ id, x, y, w, h }`)
+
+### Critical Text Rules
+
+**ALL text MUST be inside `<p>`, `<h1>`-`<h6>`, `<ul>`, or `<ol>` tags:**
+- ✅ Correct: `<div><p>Text here</p></div>`
+- ❌ Wrong: `<div>Text here</div>` - **Text will NOT appear in PowerPoint**
+- ❌ Wrong: `<span>Text</span>` - **Text will NOT appear in PowerPoint**
+- Text in `<div>` or `<span>` without a text tag will be silently ignored
+
+**NEVER use manual bullet symbols (•, -, *, ·, etc.)** - Use `<ul>` or `<ol>` lists instead
+- ❌ Wrong: `<p>- 항목</p>` (hyphen/dash)
+- ❌ Wrong: `<p>• 항목</p>` (bullet)
+- ❌ Wrong: `<p>* 항목</p>` (asterisk)
+- ❌ Wrong: `<p>· 항목</p>` (middle dot)
+- ✅ Correct: Use `<ul><li>항목</li></ul>` or `margin-left` for indentation
+
+**Empty values should NOT use hyphen:**
+- ❌ Wrong: `<p>-</p>` (will cause bullet symbol error)
+- ✅ Correct: `<p></p>` (empty) or `<p>N/A</p>`
+
+**ONLY use web-safe fonts that are universally available:**
+- ✅ Web-safe fonts: `Arial`, `Helvetica`, `Times New Roman`, `Georgia`, `Courier New`, `Verdana`, `Tahoma`, `Trebuchet MS`, `Impact`, `Comic Sans MS`
+- ❌ Wrong: `'Segoe UI'`, `'SF Pro'`, `'Roboto'`, custom fonts - **Might cause rendering issues**
+
+### Styling
+
+- Use `display: flex` on body to prevent margin collapse from breaking overflow validation
+- Use `margin` for spacing (padding included in size)
+- Inline formatting: Use `<b>`, `<i>`, `<u>` tags OR `<span>` with CSS styles
+  - `<span>` supports: `font-weight: bold`, `font-style: italic`, `text-decoration: underline`, `color: #rrggbb`
+  - `<span>` does NOT support: `margin`, `padding` (not supported in PowerPoint text runs)
+  - Example: `<span style="font-weight: bold; color: #667eea;">Bold blue text</span>`
+- Flexbox works - positions calculated from rendered layout
+- Use hex colors with `#` prefix in CSS
+- **Text alignment**: Use CSS `text-align` (`center`, `right`, etc.) when needed as a hint to PptxGenJS for text formatting if text lengths are slightly off
+
+### Shape Styling (DIV elements only)
+
+**IMPORTANT: Backgrounds, borders, and shadows only work on `<div>` elements, NOT on text elements (`<p>`, `<h1>`-`<h6>`, `<ul>`, `<ol>`)**
+
+- **Backgrounds**: CSS `background` or `background-color` on `<div>` elements only
+  - Example: `<div style="background: #f0f0f0;">` - Creates a shape with background
+- **Borders**: CSS `border` on `<div>` elements converts to PowerPoint shape borders
+  - Supports uniform borders: `border: 2px solid #333333`
+  - Supports partial borders: `border-left`, `border-right`, `border-top`, `border-bottom` (rendered as line shapes)
+  - Example: `<div style="border-left: 8pt solid #E76F51;">`
+- **Border radius**: CSS `border-radius` on `<div>` elements for rounded corners
+  - `border-radius: 50%` or higher creates circular shape
+  - Percentages <50% calculated relative to shape's smaller dimension
+  - Supports px and pt units (e.g., `border-radius: 8pt;`, `border-radius: 12px;`)
+  - Example: `<div style="border-radius: 25%;">` on 100x200px box = 25% of 100px = 25px radius
+- **Box shadows**: CSS `box-shadow` on `<div>` elements converts to PowerPoint shadows
+  - Supports outer shadows only (inset shadows are ignored to prevent corruption)
+  - Example: `<div style="box-shadow: 2px 2px 8px rgba(0, 0, 0, 0.3);">`
+  - Note: Inset/inner shadows are not supported by PowerPoint and will be skipped
+
+### Icons & Gradients
+
+- **CRITICAL: Never use CSS gradients (`linear-gradient`, `radial-gradient`)** - They don't convert to PowerPoint
+- **ALWAYS create gradient/icon PNGs FIRST using Sharp, then reference in HTML**
+- For gradients: Rasterize SVG to PNG background images
+- For icons: Rasterize react-icons SVG to PNG images
+- All visual effects must be pre-rendered as raster images before HTML rendering
+
+**Rasterizing Icons with Sharp:**
+
+```javascript
+const React = require('react');
+const ReactDOMServer = require('react-dom/server');
+const sharp = require('sharp');
+const { FaHome } = require('react-icons/fa');
+
+async function rasterizeIconPng(IconComponent, color, size = "256", filename) {
+  const svgString = ReactDOMServer.renderToStaticMarkup(
+    React.createElement(IconComponent, { color: `#${color}`, size: size })
+  );
+
+  // Convert SVG to PNG using Sharp
+  await sharp(Buffer.from(svgString))
+    .png()
+    .toFile(filename);
+
+  return filename;
+}
+
+// Usage: Rasterize icon before using in HTML
+const iconPath = await rasterizeIconPng(FaHome, "4472c4", "256", "home-icon.png");
+// Then reference in HTML: <img src="home-icon.png" style="width: 40pt; height: 40pt;">
+```
+
+**Rasterizing Gradients with Sharp:**
+
+```javascript
+const sharp = require('sharp');
+
+async function createGradientBackground(filename) {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1000" height="562.5">
+    <defs>
+      <linearGradient id="g" x1="0%" y1="0%" x2="100%" y2="100%">
+        <stop offset="0%" style="stop-color:#COLOR1"/>
+        <stop offset="100%" style="stop-color:#COLOR2"/>
+      </linearGradient>
+    </defs>
+    <rect width="100%" height="100%" fill="url(#g)"/>
+  </svg>`;
+
+  await sharp(Buffer.from(svg))
+    .png()
+    .toFile(filename);
+
+  return filename;
+}
+
+// Usage: Create gradient background before HTML
+const bgPath = await createGradientBackground("gradient-bg.png");
+// Then in HTML: <body style="background-image: url('gradient-bg.png');">
+```
+
+### Example
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+<style>
+html { background: #ffffff; }
+body {
+  width: 720pt; height: 405pt; margin: 0; padding: 0;
+  background: #f5f5f5; font-family: Arial, sans-serif;
+  display: flex;
+}
+.content { margin: 30pt; padding: 40pt; background: #ffffff; border-radius: 8pt; }
+h1 { color: #2d3748; font-size: 32pt; }
+.box {
+  background: #70ad47; padding: 20pt; border: 3px solid #5a8f37;
+  border-radius: 12pt; box-shadow: 3px 3px 10px rgba(0, 0, 0, 0.25);
+}
+</style>
+</head>
+<body>
+<div class="content">
+  <h1>Recipe Title</h1>
+  <ul>
+    <li><b>Item:</b> Description</li>
+  </ul>
+  <p>Text with <b>bold</b>, <i>italic</i>, <u>underline</u>.</p>
+  <div id="chart" class="placeholder" style="width: 350pt; height: 200pt;"></div>
+
+  <!-- Text MUST be in <p> tags -->
+  <div class="box">
+    <p>5</p>
+  </div>
+</div>
+</body>
+</html>
+```
+
+## Using the html2pptx Library
+
+### Dependencies
+
+These libraries have been globally installed and are available to use:
+- `pptxgenjs`
+- `playwright`
+- `sharp`
+
+### Basic Usage
+
+```javascript
+const pptxgen = require('pptxgenjs');
+const html2pptx = require('./html2pptx');
+
+const pptx = new pptxgen();
+pptx.layout = 'LAYOUT_16x9';  // Must match HTML body dimensions
+
+const { slide, placeholders } = await html2pptx('slide1.html', pptx);
+
+// Add chart to placeholder area
+if (placeholders.length > 0) {
+    slide.addChart(pptx.charts.LINE, chartData, placeholders[0]);
+}
+
+await pptx.writeFile('output.pptx');
+```
+
+### API Reference
+
+#### Function Signature
+```javascript
+await html2pptx(htmlFile, pres, options)
+```
+
+#### Parameters
+- `htmlFile` (string): Path to HTML file (absolute or relative)
+- `pres` (pptxgen): PptxGenJS presentation instance with layout already set
+- `options` (object, optional):
+  - `tmpDir` (string): Temporary directory for generated files (default: `process.env.TMPDIR || '/tmp'`)
+  - `slide` (object): Existing slide to reuse (default: creates new slide)
+
+#### Returns
+```javascript
+{
+    slide: pptxgenSlide,           // The created/updated slide
+    placeholders: [                 // Array of placeholder positions
+        { id: string, x: number, y: number, w: number, h: number },
+        ...
+    ]
+}
+```
+
+### Validation
+
+The library automatically validates and collects all errors before throwing:
+
+1. **HTML dimensions must match presentation layout** - Reports dimension mismatches
+2. **Content must not overflow body** - Reports overflow with exact measurements
+3. **CSS gradients** - Reports unsupported gradient usage
+4. **Text element styling** - Reports backgrounds/borders/shadows on text elements (only allowed on divs)
+
+**All validation errors are collected and reported together** in a single error message, allowing you to fix all issues at once instead of one at a time.
+
+### Working with Placeholders
+
+```javascript
+const { slide, placeholders } = await html2pptx('slide.html', pptx);
+
+// Use first placeholder
+slide.addChart(pptx.charts.BAR, data, placeholders[0]);
+
+// Find by ID
+const chartArea = placeholders.find(p => p.id === 'chart-area');
+slide.addChart(pptx.charts.LINE, data, chartArea);
+```
+
+### Complete Example
+
+```javascript
+const pptxgen = require('pptxgenjs');
+const html2pptx = require('./html2pptx');
+
+async function createPresentation() {
+    const pptx = new pptxgen();
+    pptx.layout = 'LAYOUT_16x9';
+    pptx.author = 'Your Name';
+    pptx.title = 'My Presentation';
+
+    // Slide 1: Title
+    const { slide: slide1 } = await html2pptx('slides/title.html', pptx);
+
+    // Slide 2: Content with chart
+    const { slide: slide2, placeholders } = await html2pptx('slides/data.html', pptx);
+
+    const chartData = [{
+        name: 'Sales',
+        labels: ['Q1', 'Q2', 'Q3', 'Q4'],
+        values: [4500, 5500, 6200, 7100]
+    }];
+
+    slide2.addChart(pptx.charts.BAR, chartData, {
+        ...placeholders[0],
+        showTitle: true,
+        title: 'Quarterly Sales',
+        showCatAxisTitle: true,
+        catAxisTitle: 'Quarter',
+        showValAxisTitle: true,
+        valAxisTitle: 'Sales ($000s)'
+    });
+
+    // Save
+    await pptx.writeFile({ fileName: 'presentation.pptx' });
+    console.log('Presentation created successfully!');
+}
+
+createPresentation().catch(console.error);
+```
+
+## Using PptxGenJS
+
+After converting HTML to slides with `html2pptx`, you'll use PptxGenJS to add dynamic content like charts, images, and additional elements.
+
+### ⚠️ Critical Rules
+
+#### Colors
+- **NEVER use `#` prefix** with hex colors in PptxGenJS - causes file corruption
+- ✅ Correct: `color: "FF0000"`, `fill: { color: "0066CC" }`
+- ❌ Wrong: `color: "#FF0000"` (breaks document)
+
+### Adding Images
+
+Always calculate aspect ratios from actual image dimensions:
+
+```javascript
+// Get image dimensions: identify image.png | grep -o '[0-9]* x [0-9]*'
+const imgWidth = 1860, imgHeight = 1519;  // From actual file
+const aspectRatio = imgWidth / imgHeight;
+
+const h = 3;  // Max height
+const w = h * aspectRatio;
+const x = (10 - w) / 2;  // Center on 16:9 slide
+
+slide.addImage({ path: "chart.png", x, y: 1.5, w, h });
+```
+
+### Adding Text
+
+```javascript
+// Rich text with formatting
+slide.addText([
+    { text: "Bold ", options: { bold: true } },
+    { text: "Italic ", options: { italic: true } },
+    { text: "Normal" }
+], {
+    x: 1, y: 2, w: 8, h: 1
+});
+```
+
+### Adding Shapes
+
+```javascript
+// Rectangle
+slide.addShape(pptx.shapes.RECTANGLE, {
+    x: 1, y: 1, w: 3, h: 2,
+    fill: { color: "4472C4" },
+    line: { color: "000000", width: 2 }
+});
+
+// Circle
+slide.addShape(pptx.shapes.OVAL, {
+    x: 5, y: 1, w: 2, h: 2,
+    fill: { color: "ED7D31" }
+});
+
+// Rounded rectangle
+slide.addShape(pptx.shapes.ROUNDED_RECTANGLE, {
+    x: 1, y: 4, w: 3, h: 1.5,
+    fill: { color: "70AD47" },
+    rectRadius: 0.2
+});
+```
+
+### Adding Charts
+
+**Required for most charts:** Axis labels using `catAxisTitle` (category) and `valAxisTitle` (value).
+
+**Chart Data Format:**
+- Use **single series with all labels** for simple bar/line charts
+- Each series creates a separate legend entry
+- Labels array defines X-axis values
+
+**Time Series Data - Choose Correct Granularity:**
+- **< 30 days**: Use daily grouping (e.g., "10-01", "10-02") - avoid monthly aggregation that creates single-point charts
+- **30-365 days**: Use monthly grouping (e.g., "2024-01", "2024-02")
+- **> 365 days**: Use yearly grouping (e.g., "2023", "2024")
+- **Validate**: Charts with only 1 data point likely indicate incorrect aggregation for the time period
+
+```javascript
+const { slide, placeholders } = await html2pptx('slide.html', pptx);
+
+// CORRECT: Single series with all labels
+slide.addChart(pptx.charts.BAR, [{
+    name: "Sales 2024",
+    labels: ["Q1", "Q2", "Q3", "Q4"],
+    values: [4500, 5500, 6200, 7100]
+}], {
+    ...placeholders[0],  // Use placeholder position
+    barDir: 'col',       // 'col' = vertical bars, 'bar' = horizontal
+    showTitle: true,
+    title: 'Quarterly Sales',
+    showLegend: false,   // No legend needed for single series
+    // Required axis labels
+    showCatAxisTitle: true,
+    catAxisTitle: 'Quarter',
+    showValAxisTitle: true,
+    valAxisTitle: 'Sales ($000s)',
+    // Optional: Control scaling (adjust min based on data range for better visualization)
+    valAxisMaxVal: 8000,
+    valAxisMinVal: 0,  // Use 0 for counts/amounts; for clustered data (e.g., 4500-7100), consider starting closer to min value
+    valAxisMajorUnit: 2000,  // Control y-axis label spacing to prevent crowding
+    catAxisLabelRotate: 45,  // Rotate labels if crowded
+    dataLabelPosition: 'outEnd',
+    dataLabelColor: '000000',
+    // Use single color for single-series charts
+    chartColors: ["4472C4"]  // All bars same color
+});
+```
+
+#### Scatter Chart
+
+**IMPORTANT**: Scatter chart data format is unusual - first series contains X-axis values, subsequent series contain Y-values:
+
+```javascript
+// Prepare data
+const data1 = [{ x: 10, y: 20 }, { x: 15, y: 25 }, { x: 20, y: 30 }];
+const data2 = [{ x: 12, y: 18 }, { x: 18, y: 22 }];
+
+const allXValues = [...data1.map(d => d.x), ...data2.map(d => d.x)];
+
+slide.addChart(pptx.charts.SCATTER, [
+    { name: 'X-Axis', values: allXValues },  // First series = X values
+    { name: 'Series 1', values: data1.map(d => d.y) },  // Y values only
+    { name: 'Series 2', values: data2.map(d => d.y) }   // Y values only
+], {
+    x: 1, y: 1, w: 8, h: 4,
+    lineSize: 0,  // 0 = no connecting lines
+    lineDataSymbol: 'circle',
+    lineDataSymbolSize: 6,
+    showCatAxisTitle: true,
+    catAxisTitle: 'X Axis',
+    showValAxisTitle: true,
+    valAxisTitle: 'Y Axis',
+    chartColors: ["4472C4", "ED7D31"]
+});
+```
+
+#### Line Chart
+
+```javascript
+slide.addChart(pptx.charts.LINE, [{
+    name: "Temperature",
+    labels: ["Jan", "Feb", "Mar", "Apr"],
+    values: [32, 35, 42, 55]
+}], {
+    x: 1, y: 1, w: 8, h: 4,
+    lineSize: 4,
+    lineSmooth: true,
+    // Required axis labels
+    showCatAxisTitle: true,
+    catAxisTitle: 'Month',
+    showValAxisTitle: true,
+    valAxisTitle: 'Temperature (°F)',
+    // Optional: Y-axis range (set min based on data range for better visualization)
+    valAxisMinVal: 0,     // For ranges starting at 0 (counts, percentages, etc.)
+    valAxisMaxVal: 60,
+    valAxisMajorUnit: 20,  // Control y-axis label spacing to prevent crowding (e.g., 10, 20, 25)
+    // valAxisMinVal: 30,  // PREFERRED: For data clustered in a range (e.g., 32-55 or ratings 3-5), start axis closer to min value to show variation
+    // Optional: Chart colors
+    chartColors: ["4472C4", "ED7D31", "A5A5A5"]
+});
+```
+
+#### Pie Chart (No Axis Labels Required)
+
+**CRITICAL**: Pie charts require a **single data series** with all categories in the `labels` array and corresponding values in the `values` array.
+
+```javascript
+slide.addChart(pptx.charts.PIE, [{
+    name: "Market Share",
+    labels: ["Product A", "Product B", "Other"],  // All categories in one array
+    values: [35, 45, 20]  // All values in one array
+}], {
+    x: 2, y: 1, w: 6, h: 4,
+    showPercent: true,
+    showLegend: true,
+    legendPos: 'r',  // right
+    chartColors: ["4472C4", "ED7D31", "A5A5A5"]
+});
+```
+
+#### Multiple Data Series
+
+```javascript
+slide.addChart(pptx.charts.LINE, [
+    {
+        name: "Product A",
+        labels: ["Q1", "Q2", "Q3", "Q4"],
+        values: [10, 20, 30, 40]
+    },
+    {
+        name: "Product B",
+        labels: ["Q1", "Q2", "Q3", "Q4"],
+        values: [15, 25, 20, 35]
+    }
+], {
+    x: 1, y: 1, w: 8, h: 4,
+    showCatAxisTitle: true,
+    catAxisTitle: 'Quarter',
+    showValAxisTitle: true,
+    valAxisTitle: 'Revenue ($M)'
+});
+```
+
+### Chart Colors
+
+**CRITICAL**: Use hex colors **without** the `#` prefix - including `#` causes file corruption.
+
+**Align chart colors with your chosen design palette**, ensuring sufficient contrast and distinctiveness for data visualization. Adjust colors for:
+- Strong contrast between adjacent series
+- Readability against slide backgrounds
+- Accessibility (avoid red-green only combinations)
+
+```javascript
+// Example: Ocean palette-inspired chart colors (adjusted for contrast)
+const chartColors = ["16A085", "FF6B9D", "2C3E50", "F39C12", "9B59B6"];
+
+// Single-series chart: Use one color for all bars/points
+slide.addChart(pptx.charts.BAR, [{
+    name: "Sales",
+    labels: ["Q1", "Q2", "Q3", "Q4"],
+    values: [4500, 5500, 6200, 7100]
+}], {
+    ...placeholders[0],
+    chartColors: ["16A085"],  // All bars same color
+    showLegend: false
+});
+
+// Multi-series chart: Each series gets a different color
+slide.addChart(pptx.charts.LINE, [
+    { name: "Product A", labels: ["Q1", "Q2", "Q3"], values: [10, 20, 30] },
+    { name: "Product B", labels: ["Q1", "Q2", "Q3"], values: [15, 25, 20] }
+], {
+    ...placeholders[0],
+    chartColors: ["16A085", "FF6B9D"]  // One color per series
+});
+```
+
+### Adding Tables
+
+Tables can be added with basic or advanced formatting:
+
+#### Basic Table
+
+```javascript
+slide.addTable([
+    ["Header 1", "Header 2", "Header 3"],
+    ["Row 1, Col 1", "Row 1, Col 2", "Row 1, Col 3"],
+    ["Row 2, Col 1", "Row 2, Col 2", "Row 2, Col 3"]
+], {
+    x: 0.5,
+    y: 1,
+    w: 9,
+    h: 3,
+    border: { pt: 1, color: "999999" },
+    fill: { color: "F1F1F1" }
+});
+```
+
+#### Table with Custom Formatting
+
+```javascript
+const tableData = [
+    // Header row with custom styling
+    [
+        { text: "Product", options: { fill: { color: "4472C4" }, color: "FFFFFF", bold: true } },
+        { text: "Revenue", options: { fill: { color: "4472C4" }, color: "FFFFFF", bold: true } },
+        { text: "Growth", options: { fill: { color: "4472C4" }, color: "FFFFFF", bold: true } }
+    ],
+    // Data rows
+    ["Product A", "$50M", "+15%"],
+    ["Product B", "$35M", "+22%"],
+    ["Product C", "$28M", "+8%"]
+];
+
+slide.addTable(tableData, {
+    x: 1,
+    y: 1.5,
+    w: 8,
+    h: 3,
+    colW: [3, 2.5, 2.5],  // Column widths
+    rowH: [0.5, 0.6, 0.6, 0.6],  // Row heights
+    border: { pt: 1, color: "CCCCCC" },
+    align: "center",
+    valign: "middle",
+    fontSize: 14
+});
+```
+
+#### Table with Merged Cells
+
+```javascript
+const mergedTableData = [
+    [
+        { text: "Q1 Results", options: { colspan: 3, fill: { color: "4472C4" }, color: "FFFFFF", bold: true } }
+    ],
+    ["Product", "Sales", "Market Share"],
+    ["Product A", "$25M", "35%"],
+    ["Product B", "$18M", "25%"]
+];
+
+slide.addTable(mergedTableData, {
+    x: 1,
+    y: 1,
+    w: 8,
+    h: 2.5,
+    colW: [3, 2.5, 2.5],
+    border: { pt: 1, color: "DDDDDD" }
+});
+```
+
+### Table Options
+
+Common table options:
+- `x, y, w, h` - Position and size
+- `colW` - Array of column widths (in inches)
+- `rowH` - Array of row heights (in inches)
+- `border` - Border style: `{ pt: 1, color: "999999" }`
+- `fill` - Background color (no # prefix)
+- `align` - Text alignment: "left", "center", "right"
+- `valign` - Vertical alignment: "top", "middle", "bottom"
+- `fontSize` - Text size
+- `autoPage` - Auto-create new slides if content overflows
+
+---
+
+## Storyboard/Wireframe HTML Guide (스토리보드/와이어프레임)
+
+스토리보드나 와이어프레임 HTML 슬라이드 작성 시 참고 가이드입니다.
+
+### Recommended Structure
+
+```html
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+    <meta charset="UTF-8">
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css">
+    <style>
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        body {
+            width: 720pt;
+            height: 405pt;
+            font-family: 'Pretendard', 'Malgun Gothic', sans-serif;
+            background: #ffffff;
+            display: flex;
+        }
+        p, h1, h2, h3 { margin: 0; }
+    </style>
+</head>
+<body>
+    <!-- Wireframe Area (Left) -->
+    <div style="flex: 1; padding: 16pt;">
+        <!-- Meta info, Sidebar, Main content -->
+    </div>
+
+    <!-- Description Area (Right) -->
+    <div style="width: 180pt; background: #1a1a1a; padding: 14pt;">
+        <div style="background: #95C11F; padding: 5pt 8pt; margin-bottom: 12pt;">
+            <p style="font-size: 8pt; font-weight: 600; color: #ffffff;">Description</p>
+        </div>
+        <!-- Description items -->
+    </div>
+</body>
+</html>
+```
+
+### Common UI Components
+
+#### Checkbox
+```html
+<!-- Empty checkbox -->
+<div style="width: 8pt; height: 8pt; border: 1pt solid #ccc;"></div>
+
+<!-- Checked checkbox -->
+<div style="width: 8pt; height: 8pt; border: 1pt solid #ccc; background: #1a1a1a;"></div>
+```
+
+#### Icons (using emoji)
+```html
+<p style="font-size: 6pt; color: #666;">✏️</p>  <!-- Edit icon -->
+<p style="font-size: 10pt; color: #1a1a1a;">☰</p>  <!-- Hamburger menu -->
+<p style="font-size: 10pt; color: #1a1a1a;">🔔</p>  <!-- Notification bell -->
+<p style="font-size: 8pt; color: #999;">🔍</p>  <!-- Search icon -->
+<p style="font-size: 6pt; color: #666;">📅</p>  <!-- Calendar icon -->
+```
+
+#### Numbered Badge
+```html
+<div style="position: relative;">
+    <div style="position: absolute; top: -6pt; left: -4pt; width: 10pt; height: 10pt; background: #95C11F; border-radius: 50%; display: flex; align-items: center; justify-content: center;">
+        <p style="font-size: 5pt; color: #fff;">01</p>
+    </div>
+    <div style="border: 1pt solid #ccc; padding: 2pt 12pt 2pt 6pt; background: #fff;">
+        <p style="font-size: 6pt; color: #666;">전체 ▼</p>
+    </div>
+</div>
+```
+
+#### Status Badge
+```html
+<div style="background: #95C11F; padding: 1pt 4pt; text-align: center;">
+    <p style="font-size: 4pt; color: #fff;">견적대기</p>
+</div>
+```
+
+#### Sidebar Menu with Hierarchy
+```html
+<!-- Parent menu -->
+<p style="font-size: 7pt; font-weight: 600; color: #1a1a1a; margin-bottom: 2pt;">입찰관리</p>
+
+<!-- Sub-menu (indented, NOT using hyphen) -->
+<p style="font-size: 6pt; color: #666; margin-left: 10pt; margin-bottom: 1pt;">거래처관리</p>
+<p style="font-size: 6pt; color: #666; margin-left: 10pt; margin-bottom: 1pt;">현장설명회관리</p>
+
+<!-- Active sub-menu with highlight -->
+<div style="background: #95C11F; padding: 2pt 6pt; margin: 2pt 0 2pt 6pt;">
+    <p style="font-size: 6pt; color: #fff;">견적관리</p>
+</div>
+```
+
+#### Table with Flexbox
+```html
+<div style="border: 1pt solid #e0e0e0;">
+    <!-- Header row -->
+    <div style="display: flex; background: #f5f5f5; border-bottom: 1pt solid #e0e0e0;">
+        <div style="width: 14pt; padding: 2pt; border-right: 1pt solid #e0e0e0;">
+            <div style="width: 8pt; height: 8pt; border: 1pt solid #ccc;"></div>
+        </div>
+        <div style="width: 32pt; padding: 2pt; border-right: 1pt solid #e0e0e0;">
+            <p style="font-size: 5pt; color: #666;">컬럼1</p>
+        </div>
+        <div style="flex: 1; padding: 2pt;">
+            <p style="font-size: 5pt; color: #666;">컬럼2</p>
+        </div>
+    </div>
+    <!-- Data row -->
+    <div style="display: flex; border-bottom: 1pt solid #e0e0e0;">
+        <div style="width: 14pt; padding: 2pt; border-right: 1pt solid #e0e0e0;">
+            <div style="width: 8pt; height: 8pt; border: 1pt solid #ccc;"></div>
+        </div>
+        <div style="width: 32pt; padding: 2pt; border-right: 1pt solid #e0e0e0;">
+            <p style="font-size: 5pt; color: #1a1a1a;">데이터1</p>
+        </div>
+        <div style="flex: 1; padding: 2pt;">
+            <p style="font-size: 5pt; color: #1a1a1a;">데이터2</p>
+        </div>
+    </div>
+</div>
+```
+
+### Common Mistakes to Avoid
+
+1. **Never use `-` to start text** (treated as bullet symbol)
+2. **Never use `-` for empty values** (use empty string or "N/A")
+3. **Never use `*` to mark important items** (use `[공통]` instead)
+4. **Never apply border/background directly to `<p>` tags** (wrap with `<div>`)
+5. **Never use `<table>` tags** (use flexbox instead)

.claude/skills/pptx-skill/ooxml.md

@@ -0,0 +1,427 @@
+# Office Open XML Technical Reference for PowerPoint
+
+**Important: Read this entire document before starting.** Critical XML schema rules and formatting requirements are covered throughout. Incorrect implementation can create invalid PPTX files that PowerPoint cannot open.
+
+## Technical Guidelines
+
+### Schema Compliance
+- **Element ordering in `<p:txBody>`**: `<a:bodyPr>`, `<a:lstStyle>`, `<a:p>`
+- **Whitespace**: Add `xml:space='preserve'` to `<a:t>` elements with leading/trailing spaces
+- **Unicode**: Escape characters in ASCII content: `"` becomes `&#8220;`
+- **Images**: Add to `ppt/media/`, reference in slide XML, set dimensions to fit slide bounds
+- **Relationships**: Update `ppt/slides/_rels/slideN.xml.rels` for each slide's resources
+- **Dirty attribute**: Add `dirty="0"` to `<a:rPr>` and `<a:endParaRPr>` elements to indicate clean state
+
+## Presentation Structure
+
+### Basic Slide Structure
+```xml
+<!-- ppt/slides/slide1.xml -->
+<p:sld>
+  <p:cSld>
+    <p:spTree>
+      <p:nvGrpSpPr>...</p:nvGrpSpPr>
+      <p:grpSpPr>...</p:grpSpPr>
+      <!-- Shapes go here -->
+    </p:spTree>
+  </p:cSld>
+</p:sld>
+```
+
+### Text Box / Shape with Text
+```xml
+<p:sp>
+  <p:nvSpPr>
+    <p:cNvPr id="2" name="Title"/>
+    <p:cNvSpPr>
+      <a:spLocks noGrp="1"/>
+    </p:cNvSpPr>
+    <p:nvPr>
+      <p:ph type="ctrTitle"/>
+    </p:nvPr>
+  </p:nvSpPr>
+  <p:spPr>
+    <a:xfrm>
+      <a:off x="838200" y="365125"/>
+      <a:ext cx="7772400" cy="1470025"/>
+    </a:xfrm>
+  </p:spPr>
+  <p:txBody>
+    <a:bodyPr/>
+    <a:lstStyle/>
+    <a:p>
+      <a:r>
+        <a:t>Slide Title</a:t>
+      </a:r>
+    </a:p>
+  </p:txBody>
+</p:sp>
+```
+
+### Text Formatting
+```xml
+<!-- Bold -->
+<a:r>
+  <a:rPr b="1"/>
+  <a:t>Bold Text</a:t>
+</a:r>
+
+<!-- Italic -->
+<a:r>
+  <a:rPr i="1"/>
+  <a:t>Italic Text</a:t>
+</a:r>
+
+<!-- Underline -->
+<a:r>
+  <a:rPr u="sng"/>
+  <a:t>Underlined</a:t>
+</a:r>
+
+<!-- Highlight -->
+<a:r>
+  <a:rPr>
+    <a:highlight>
+      <a:srgbClr val="FFFF00"/>
+    </a:highlight>
+  </a:rPr>
+  <a:t>Highlighted Text</a:t>
+</a:r>
+
+<!-- Font and Size -->
+<a:r>
+  <a:rPr sz="2400" typeface="Arial">
+    <a:solidFill>
+      <a:srgbClr val="FF0000"/>
+    </a:solidFill>
+  </a:rPr>
+  <a:t>Colored Arial 24pt</a:t>
+</a:r>
+
+<!-- Complete formatting example -->
+<a:r>
+  <a:rPr lang="en-US" sz="1400" b="1" dirty="0">
+    <a:solidFill>
+      <a:srgbClr val="FAFAFA"/>
+    </a:solidFill>
+  </a:rPr>
+  <a:t>Formatted text</a:t>
+</a:r>
+```
+
+### Lists
+```xml
+<!-- Bullet list -->
+<a:p>
+  <a:pPr lvl="0">
+    <a:buChar char="•"/>
+  </a:pPr>
+  <a:r>
+    <a:t>First bullet point</a:t>
+  </a:r>
+</a:p>
+
+<!-- Numbered list -->
+<a:p>
+  <a:pPr lvl="0">
+    <a:buAutoNum type="arabicPeriod"/>
+  </a:pPr>
+  <a:r>
+    <a:t>First numbered item</a:t>
+  </a:r>
+</a:p>
+
+<!-- Second level indent -->
+<a:p>
+  <a:pPr lvl="1">
+    <a:buChar char="•"/>
+  </a:pPr>
+  <a:r>
+    <a:t>Indented bullet</a:t>
+  </a:r>
+</a:p>
+```
+
+### Shapes
+```xml
+<!-- Rectangle -->
+<p:sp>
+  <p:nvSpPr>
+    <p:cNvPr id="3" name="Rectangle"/>
+    <p:cNvSpPr/>
+    <p:nvPr/>
+  </p:nvSpPr>
+  <p:spPr>
+    <a:xfrm>
+      <a:off x="1000000" y="1000000"/>
+      <a:ext cx="3000000" cy="2000000"/>
+    </a:xfrm>
+    <a:prstGeom prst="rect">
+      <a:avLst/>
+    </a:prstGeom>
+    <a:solidFill>
+      <a:srgbClr val="FF0000"/>
+    </a:solidFill>
+    <a:ln w="25400">
+      <a:solidFill>
+        <a:srgbClr val="000000"/>
+      </a:solidFill>
+    </a:ln>
+  </p:spPr>
+</p:sp>
+
+<!-- Rounded Rectangle -->
+<p:sp>
+  <p:spPr>
+    <a:prstGeom prst="roundRect">
+      <a:avLst/>
+    </a:prstGeom>
+  </p:spPr>
+</p:sp>
+
+<!-- Circle/Ellipse -->
+<p:sp>
+  <p:spPr>
+    <a:prstGeom prst="ellipse">
+      <a:avLst/>
+    </a:prstGeom>
+  </p:spPr>
+</p:sp>
+```
+
+### Images
+```xml
+<p:pic>
+  <p:nvPicPr>
+    <p:cNvPr id="4" name="Picture">
+      <a:hlinkClick r:id="" action="ppaction://media"/>
+    </p:cNvPr>
+    <p:cNvPicPr>
+      <a:picLocks noChangeAspect="1"/>
+    </p:cNvPicPr>
+    <p:nvPr/>
+  </p:nvPicPr>
+  <p:blipFill>
+    <a:blip r:embed="rId2"/>
+    <a:stretch>
+      <a:fillRect/>
+    </a:stretch>
+  </p:blipFill>
+  <p:spPr>
+    <a:xfrm>
+      <a:off x="1000000" y="1000000"/>
+      <a:ext cx="3000000" cy="2000000"/>
+    </a:xfrm>
+    <a:prstGeom prst="rect">
+      <a:avLst/>
+    </a:prstGeom>
+  </p:spPr>
+</p:pic>
+```
+
+### Tables
+```xml
+<p:graphicFrame>
+  <p:nvGraphicFramePr>
+    <p:cNvPr id="5" name="Table"/>
+    <p:cNvGraphicFramePr>
+      <a:graphicFrameLocks noGrp="1"/>
+    </p:cNvGraphicFramePr>
+    <p:nvPr/>
+  </p:nvGraphicFramePr>
+  <p:xfrm>
+    <a:off x="1000000" y="1000000"/>
+    <a:ext cx="6000000" cy="2000000"/>
+  </p:xfrm>
+  <a:graphic>
+    <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/table">
+      <a:tbl>
+        <a:tblGrid>
+          <a:gridCol w="3000000"/>
+          <a:gridCol w="3000000"/>
+        </a:tblGrid>
+        <a:tr h="500000">
+          <a:tc>
+            <a:txBody>
+              <a:bodyPr/>
+              <a:lstStyle/>
+              <a:p>
+                <a:r>
+                  <a:t>Cell 1</a:t>
+                </a:r>
+              </a:p>
+            </a:txBody>
+          </a:tc>
+          <a:tc>
+            <a:txBody>
+              <a:bodyPr/>
+              <a:lstStyle/>
+              <a:p>
+                <a:r>
+                  <a:t>Cell 2</a:t>
+                </a:r>
+              </a:p>
+            </a:txBody>
+          </a:tc>
+        </a:tr>
+      </a:tbl>
+    </a:graphicData>
+  </a:graphic>
+</p:graphicFrame>
+```
+
+### Slide Layouts
+
+```xml
+<!-- Title Slide Layout -->
+<p:sp>
+  <p:nvSpPr>
+    <p:nvPr>
+      <p:ph type="ctrTitle"/>
+    </p:nvPr>
+  </p:nvSpPr>
+  <!-- Title content -->
+</p:sp>
+
+<p:sp>
+  <p:nvSpPr>
+    <p:nvPr>
+      <p:ph type="subTitle" idx="1"/>
+    </p:nvPr>
+  </p:nvSpPr>
+  <!-- Subtitle content -->
+</p:sp>
+
+<!-- Content Slide Layout -->
+<p:sp>
+  <p:nvSpPr>
+    <p:nvPr>
+      <p:ph type="title"/>
+    </p:nvPr>
+  </p:nvSpPr>
+  <!-- Slide title -->
+</p:sp>
+
+<p:sp>
+  <p:nvSpPr>
+    <p:nvPr>
+      <p:ph type="body" idx="1"/>
+    </p:nvPr>
+  </p:nvSpPr>
+  <!-- Content body -->
+</p:sp>
+```
+
+## File Updates
+
+When adding content, update these files:
+
+**`ppt/_rels/presentation.xml.rels`:**
+```xml
+<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide" Target="slides/slide1.xml"/>
+<Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideMaster" Target="slideMasters/slideMaster1.xml"/>
+```
+
+**`ppt/slides/_rels/slide1.xml.rels`:**
+```xml
+<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout" Target="../slideLayouts/slideLayout1.xml"/>
+<Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="../media/image1.png"/>
+```
+
+**`[Content_Types].xml`:**
+```xml
+<Default Extension="png" ContentType="image/png"/>
+<Default Extension="jpg" ContentType="image/jpeg"/>
+<Override PartName="/ppt/slides/slide1.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slide+xml"/>
+```
+
+**`ppt/presentation.xml`:**
+```xml
+<p:sldIdLst>
+  <p:sldId id="256" r:id="rId1"/>
+  <p:sldId id="257" r:id="rId2"/>
+</p:sldIdLst>
+```
+
+**`docProps/app.xml`:** Update slide count and statistics
+```xml
+<Slides>2</Slides>
+<Paragraphs>10</Paragraphs>
+<Words>50</Words>
+```
+
+## Slide Operations
+
+### Adding a New Slide
+When adding a slide to the end of the presentation:
+
+1. **Create the slide file** (`ppt/slides/slideN.xml`)
+2. **Update `[Content_Types].xml`**: Add Override for the new slide
+3. **Update `ppt/_rels/presentation.xml.rels`**: Add relationship for the new slide
+4. **Update `ppt/presentation.xml`**: Add slide ID to `<p:sldIdLst>`
+5. **Create slide relationships** (`ppt/slides/_rels/slideN.xml.rels`) if needed
+6. **Update `docProps/app.xml`**: Increment slide count and update statistics (if present)
+
+### Duplicating a Slide
+1. Copy the source slide XML file with a new name
+2. Update all IDs in the new slide to be unique
+3. Follow the "Adding a New Slide" steps above
+4. **CRITICAL**: Remove or update any notes slide references in `_rels` files
+5. Remove references to unused media files
+
+### Reordering Slides
+1. **Update `ppt/presentation.xml`**: Reorder `<p:sldId>` elements in `<p:sldIdLst>`
+2. The order of `<p:sldId>` elements determines slide order
+3. Keep slide IDs and relationship IDs unchanged
+
+Example:
+```xml
+<!-- Original order -->
+<p:sldIdLst>
+  <p:sldId id="256" r:id="rId2"/>
+  <p:sldId id="257" r:id="rId3"/>
+  <p:sldId id="258" r:id="rId4"/>
+</p:sldIdLst>
+
+<!-- After moving slide 3 to position 2 -->
+<p:sldIdLst>
+  <p:sldId id="256" r:id="rId2"/>
+  <p:sldId id="258" r:id="rId4"/>
+  <p:sldId id="257" r:id="rId3"/>
+</p:sldIdLst>
+```
+
+### Deleting a Slide
+1. **Remove from `ppt/presentation.xml`**: Delete the `<p:sldId>` entry
+2. **Remove from `ppt/_rels/presentation.xml.rels`**: Delete the relationship
+3. **Remove from `[Content_Types].xml`**: Delete the Override entry
+4. **Delete files**: Remove `ppt/slides/slideN.xml` and `ppt/slides/_rels/slideN.xml.rels`
+5. **Update `docProps/app.xml`**: Decrement slide count and update statistics
+6. **Clean up unused media**: Remove orphaned images from `ppt/media/`
+
+Note: Don't renumber remaining slides - keep their original IDs and filenames.
+
+
+## Common Errors to Avoid
+
+- **Encodings**: Escape unicode characters in ASCII content: `"` becomes `&#8220;`
+- **Images**: Add to `ppt/media/` and update relationship files
+- **Lists**: Omit bullets from list headers
+- **IDs**: Use valid hexadecimal values for UUIDs
+- **Themes**: Check all themes in `theme` directory for colors
+
+## Validation Checklist for Template-Based Presentations
+
+### Before Packing, Always:
+- **Clean unused resources**: Remove unreferenced media, fonts, and notes directories
+- **Fix Content_Types.xml**: Declare ALL slides, layouts, and themes present in the package
+- **Fix relationship IDs**: 
+   - Remove font embed references if not using embedded fonts
+- **Remove broken references**: Check all `_rels` files for references to deleted resources
+
+### Common Template Duplication Pitfalls:
+- Multiple slides referencing the same notes slide after duplication
+- Image/media references from template slides that no longer exist
+- Font embedding references when fonts aren't included
+- Missing slideLayout declarations for layouts 12-25
+- docProps directory may not unpack - this is optional

.claude/skills/pptx-skill/ooxml/scripts/pack.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""
+Tool to pack a directory into a .docx, .pptx, or .xlsx file with XML formatting undone.
+
+Example usage:
+    python pack.py <input_directory> <office_file> [--force]
+"""
+
+import argparse
+import shutil
+import subprocess
+import sys
+import tempfile
+import defusedxml.minidom
+import zipfile
+from pathlib import Path
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Pack a directory into an Office file")
+    parser.add_argument("input_directory", help="Unpacked Office document directory")
+    parser.add_argument("output_file", help="Output Office file (.docx/.pptx/.xlsx)")
+    parser.add_argument("--force", action="store_true", help="Skip validation")
+    args = parser.parse_args()
+
+    try:
+        success = pack_document(
+            args.input_directory, args.output_file, validate=not args.force
+        )
+
+        # Show warning if validation was skipped
+        if args.force:
+            print("Warning: Skipped validation, file may be corrupt", file=sys.stderr)
+        # Exit with error if validation failed
+        elif not success:
+            print("Contents would produce a corrupt file.", file=sys.stderr)
+            print("Please validate XML before repacking.", file=sys.stderr)
+            print("Use --force to skip validation and pack anyway.", file=sys.stderr)
+            sys.exit(1)
+
+    except ValueError as e:
+        sys.exit(f"Error: {e}")
+
+
+def pack_document(input_dir, output_file, validate=False):
+    """Pack a directory into an Office file (.docx/.pptx/.xlsx).
+
+    Args:
+        input_dir: Path to unpacked Office document directory
+        output_file: Path to output Office file
+        validate: If True, validates with soffice (default: False)
+
+    Returns:
+        bool: True if successful, False if validation failed
+    """
+    input_dir = Path(input_dir)
+    output_file = Path(output_file)
+
+    if not input_dir.is_dir():
+        raise ValueError(f"{input_dir} is not a directory")
+    if output_file.suffix.lower() not in {".docx", ".pptx", ".xlsx"}:
+        raise ValueError(f"{output_file} must be a .docx, .pptx, or .xlsx file")
+
+    # Work in temporary directory to avoid modifying original
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_content_dir = Path(temp_dir) / "content"
+        shutil.copytree(input_dir, temp_content_dir)
+
+        # Process XML files to remove pretty-printing whitespace
+        for pattern in ["*.xml", "*.rels"]:
+            for xml_file in temp_content_dir.rglob(pattern):
+                condense_xml(xml_file)
+
+        # Create final Office file as zip archive
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+        with zipfile.ZipFile(output_file, "w", zipfile.ZIP_DEFLATED) as zf:
+            for f in temp_content_dir.rglob("*"):
+                if f.is_file():
+                    zf.write(f, f.relative_to(temp_content_dir))
+
+        # Validate if requested
+        if validate:
+            if not validate_document(output_file):
+                output_file.unlink()  # Delete the corrupt file
+                return False
+
+    return True
+
+
+def validate_document(doc_path):
+    """Validate document by converting to HTML with soffice."""
+    # Determine the correct filter based on file extension
+    match doc_path.suffix.lower():
+        case ".docx":
+            filter_name = "html:HTML"
+        case ".pptx":
+            filter_name = "html:impress_html_Export"
+        case ".xlsx":
+            filter_name = "html:HTML (StarCalc)"
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        try:
+            result = subprocess.run(
+                [
+                    "soffice",
+                    "--headless",
+                    "--convert-to",
+                    filter_name,
+                    "--outdir",
+                    temp_dir,
+                    str(doc_path),
+                ],
+                capture_output=True,
+                timeout=10,
+                text=True,
+            )
+            if not (Path(temp_dir) / f"{doc_path.stem}.html").exists():
+                error_msg = result.stderr.strip() or "Document validation failed"
+                print(f"Validation error: {error_msg}", file=sys.stderr)
+                return False
+            return True
+        except FileNotFoundError:
+            print("Warning: soffice not found. Skipping validation.", file=sys.stderr)
+            return True
+        except subprocess.TimeoutExpired:
+            print("Validation error: Timeout during conversion", file=sys.stderr)
+            return False
+        except Exception as e:
+            print(f"Validation error: {e}", file=sys.stderr)
+            return False
+
+
+def condense_xml(xml_file):
+    """Strip unnecessary whitespace and remove comments."""
+    with open(xml_file, "r", encoding="utf-8") as f:
+        dom = defusedxml.minidom.parse(f)
+
+    # Process each element to remove whitespace and comments
+    for element in dom.getElementsByTagName("*"):
+        # Skip w:t elements and their processing
+        if element.tagName.endswith(":t"):
+            continue
+
+        # Remove whitespace-only text nodes and comment nodes
+        for child in list(element.childNodes):
+            if (
+                child.nodeType == child.TEXT_NODE
+                and child.nodeValue
+                and child.nodeValue.strip() == ""
+            ) or child.nodeType == child.COMMENT_NODE:
+                element.removeChild(child)
+
+    # Write back the condensed XML
+    with open(xml_file, "wb") as f:
+        f.write(dom.toxml(encoding="UTF-8"))
+
+
+if __name__ == "__main__":
+    main()

.claude/skills/pptx-skill/ooxml/scripts/unpack.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""Unpack and format XML contents of Office files (.docx, .pptx, .xlsx)"""
+
+import random
+import sys
+import defusedxml.minidom
+import zipfile
+from pathlib import Path
+
+# Get command line arguments
+assert len(sys.argv) == 3, "Usage: python unpack.py <office_file> <output_dir>"
+input_file, output_dir = sys.argv[1], sys.argv[2]
+
+# Extract and format
+output_path = Path(output_dir)
+output_path.mkdir(parents=True, exist_ok=True)
+zipfile.ZipFile(input_file).extractall(output_path)
+
+# Pretty print all XML files
+xml_files = list(output_path.rglob("*.xml")) + list(output_path.rglob("*.rels"))
+for xml_file in xml_files:
+    content = xml_file.read_text(encoding="utf-8")
+    dom = defusedxml.minidom.parseString(content)
+    xml_file.write_bytes(dom.toprettyxml(indent="  ", encoding="ascii"))
+
+# For .docx files, suggest an RSID for tracked changes
+if input_file.endswith(".docx"):
+    suggested_rsid = "".join(random.choices("0123456789ABCDEF", k=8))
+    print(f"Suggested RSID for edit session: {suggested_rsid}")

.claude/skills/pptx-skill/ooxml/scripts/validate.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""
+Command line tool to validate Office document XML files against XSD schemas and tracked changes.
+
+Usage:
+    python validate.py <dir> --original <original_file>
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from validation import DOCXSchemaValidator, PPTXSchemaValidator, RedliningValidator
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Validate Office document XML files")
+    parser.add_argument(
+        "unpacked_dir",
+        help="Path to unpacked Office document directory",
+    )
+    parser.add_argument(
+        "--original",
+        required=True,
+        help="Path to original file (.docx/.pptx/.xlsx)",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Enable verbose output",
+    )
+    args = parser.parse_args()
+
+    # Validate paths
+    unpacked_dir = Path(args.unpacked_dir)
+    original_file = Path(args.original)
+    file_extension = original_file.suffix.lower()
+    assert unpacked_dir.is_dir(), f"Error: {unpacked_dir} is not a directory"
+    assert original_file.is_file(), f"Error: {original_file} is not a file"
+    assert file_extension in [".docx", ".pptx", ".xlsx"], (
+        f"Error: {original_file} must be a .docx, .pptx, or .xlsx file"
+    )
+
+    # Run validations
+    match file_extension:
+        case ".docx":
+            validators = [DOCXSchemaValidator, RedliningValidator]
+        case ".pptx":
+            validators = [PPTXSchemaValidator]
+        case _:
+            print(f"Error: Validation not supported for file type {file_extension}")
+            sys.exit(1)
+
+    # Run validators
+    success = True
+    for V in validators:
+        validator = V(unpacked_dir, original_file, verbose=args.verbose)
+        if not validator.validate():
+            success = False
+
+    if success:
+        print("All validations PASSED!")
+
+    sys.exit(0 if success else 1)
+
+
+if __name__ == "__main__":
+    main()

.claude/skills/pptx-skill/scripts/enhanced-pptx-generator.js

@@ -0,0 +1,359 @@
+/**
+ * Enhanced PPTX Generator - 재사용 가능한 프레젠테이션 생성 모듈
+ * 카드형 배경, 아이콘, 통계 카드 등 시각적 요소를 포함한 PowerPoint 생성
+ */
+
+const pptxgen = require('pptxgenjs');
+
+class EnhancedPPTXGenerator {
+  constructor(options = {}) {
+    this.pres = new pptxgen();
+    this.pres.layout = options.layout || 'LAYOUT_16x9';
+    this.pres.author = options.author || 'Enhanced PPTX Generator';
+    this.pres.title = options.title || 'Generated Presentation';
+
+    // 기본 브랜드 색상 설정
+    this.brandColor = options.brandColor || 'FF0000';
+    this.backgroundColor = options.backgroundColor || 'ffffff';
+    this.cardColor = options.cardColor || 'f8f9fa';
+    this.borderColor = options.borderColor || 'e2e8f0';
+  }
+
+  /**
+   * 카드형 배경 도형 추가
+   */
+  addCard(slide, x, y, width, height, options = {}) {
+    const cardOptions = {
+      x, y, w: width, h: height,
+      fill: { color: options.fillColor || this.cardColor },
+      line: {
+        color: options.borderColor || this.borderColor,
+        width: options.borderWidth || 1
+      },
+      rectRadius: options.radius || 0.15
+    };
+
+    slide.addShape(this.pres.ShapeType.rect, cardOptions);
+
+    // 상단 컬러 바 추가 (옵션)
+    if (options.topBar) {
+      slide.addShape(this.pres.ShapeType.rect, {
+        x, y, w: width, h: options.topBarHeight || 0.15,
+        fill: { color: options.topBarColor || this.brandColor }
+      });
+    }
+
+    return cardOptions;
+  }
+
+  /**
+   * 원형 아이콘 배경 추가
+   */
+  addIconBackground(slide, x, y, size, iconText, options = {}) {
+    // 원형 배경
+    slide.addShape(this.pres.ShapeType.ellipse, {
+      x, y, w: size, h: size,
+      fill: { color: options.backgroundColor || this.brandColor },
+      line: { color: options.borderColor || this.brandColor, width: options.borderWidth || 0 }
+    });
+
+    // 아이콘 텍스트
+    slide.addText(iconText, {
+      x, y, w: size, h: size,
+      fontSize: options.fontSize || (size * 40), // 크기에 비례한 폰트
+      color: options.textColor || 'ffffff',
+      align: 'center',
+      valign: 'middle'
+    });
+
+    return { x, y, size };
+  }
+
+  /**
+   * 통계 카드 추가
+   */
+  addStatCard(slide, x, y, width, height, statData, options = {}) {
+    const { number, description, icon, color } = statData;
+
+    // 카드 배경
+    slide.addShape(this.pres.ShapeType.rect, {
+      x, y, w: width, h: height,
+      fill: { color: options.backgroundColor || 'ffffff' },
+      line: { color: color || this.brandColor, width: options.borderWidth || 2 },
+      rectRadius: options.radius || 0.15
+    });
+
+    // 아이콘 (선택사항)
+    if (icon) {
+      slide.addText(icon, {
+        x: x + 0.1, y: y + 0.1, w: 0.5, h: 0.5,
+        fontSize: options.iconSize || 24
+      });
+    }
+
+    // 숫자/통계
+    slide.addText(number, {
+      x: x + (icon ? 0.7 : 0.1),
+      y: y + 0.15,
+      w: width - (icon ? 0.8 : 0.2),
+      h: height * 0.4,
+      fontSize: options.numberSize || 18,
+      bold: true,
+      color: color || this.brandColor,
+      align: 'center'
+    });
+
+    // 설명
+    slide.addText(description, {
+      x: x + 0.1,
+      y: y + height * 0.6,
+      w: width - 0.2,
+      h: height * 0.3,
+      fontSize: options.descriptionSize || 11,
+      color: '666666',
+      align: 'center'
+    });
+
+    return { x, y, width, height };
+  }
+
+  /**
+   * 타임라인 단계 추가
+   */
+  addTimelineStep(slide, x, y, stepNumber, title, description, options = {}) {
+    const stepColor = options.completed ? this.brandColor : 'f0f0f0';
+    const textColor = options.completed ? 'ffffff' : '666666';
+
+    // 원형 단계 번호
+    this.addIconBackground(slide, x, y, 0.6, stepNumber.toString(), {
+      backgroundColor: stepColor,
+      textColor: textColor,
+      fontSize: 20
+    });
+
+    // 제목
+    slide.addText(title, {
+      x: x + 0.8, y: y, w: 7, h: 0.4,
+      fontSize: 16, bold: true, color: this.brandColor
+    });
+
+    // 설명
+    slide.addText(description, {
+      x: x + 0.8, y: y + 0.4, w: 7, h: 0.4,
+      fontSize: 12, color: '666666'
+    });
+
+    return { x, y };
+  }
+
+  /**
+   * 제목 슬라이드 생성
+   */
+  createTitleSlide(mainTitle, subtitle, description, options = {}) {
+    const slide = this.pres.addSlide();
+    slide.background = { color: this.backgroundColor };
+
+    // 메인 카드
+    this.addCard(slide, 1.5, 1, 7, 4, {
+      topBar: true,
+      topBarColor: this.brandColor
+    });
+
+    // 메인 제목
+    slide.addText(mainTitle, {
+      x: 1.5, y: 1.8, w: 7, h: 1,
+      fontSize: options.titleSize || 48,
+      bold: true,
+      color: '282828',
+      align: 'center'
+    });
+
+    // 부제목
+    if (subtitle) {
+      slide.addText(subtitle, {
+        x: 1.5, y: 2.8, w: 7, h: 0.8,
+        fontSize: options.subtitleSize || 24,
+        bold: true,
+        color: this.brandColor,
+        align: 'center'
+      });
+    }
+
+    // 설명
+    if (description) {
+      slide.addText(description, {
+        x: 1.5, y: 3.6, w: 7, h: 0.6,
+        fontSize: options.descriptionSize || 16,
+        color: '666666',
+        align: 'center'
+      });
+    }
+
+    return slide;
+  }
+
+  /**
+   * 콘텐츠 슬라이드 생성
+   */
+  createContentSlide(title, items = [], options = {}) {
+    const slide = this.pres.addSlide();
+    slide.background = { color: this.backgroundColor };
+
+    // 제목
+    slide.addText(title, {
+      x: 0.5, y: 0.5, w: 9, h: 0.8,
+      fontSize: options.titleSize || 28,
+      bold: true,
+      color: '282828'
+    });
+
+    // 아이템들을 카드 형태로 배치
+    items.forEach((item, index) => {
+      const cols = options.columns || 2;
+      const x = 0.5 + (index % cols) * (9 / cols);
+      const y = 1.5 + Math.floor(index / cols) * (options.itemHeight || 1.5);
+      const width = (9 / cols) - 0.3;
+      const height = options.itemHeight || 1.3;
+
+      this.addCard(slide, x, y, width, height, {
+        topBar: true
+      });
+
+      // 아이콘
+      if (item.icon) {
+        this.addIconBackground(slide, x + 0.2, y + 0.2, 0.6, item.icon, {
+          backgroundColor: this.brandColor
+        });
+      }
+
+      // 제목
+      slide.addText(item.title, {
+        x: x + (item.icon ? 1 : 0.3),
+        y: y + 0.3,
+        w: width - (item.icon ? 1.3 : 0.6),
+        h: 0.4,
+        fontSize: 16, bold: true, color: this.brandColor
+      });
+
+      // 설명
+      if (item.description) {
+        slide.addText(item.description, {
+          x: x + 0.3,
+          y: y + 0.8,
+          w: width - 0.6,
+          h: 0.4,
+          fontSize: 11, color: '666666'
+        });
+      }
+    });
+
+    return slide;
+  }
+
+  /**
+   * 통계 슬라이드 생성
+   */
+  createStatsSlide(title, stats = [], options = {}) {
+    const slide = this.pres.addSlide();
+    slide.background = { color: this.backgroundColor };
+
+    // 제목
+    slide.addText(title, {
+      x: 0.5, y: 0.5, w: 9, h: 0.8,
+      fontSize: options.titleSize || 28,
+      bold: true,
+      color: '282828'
+    });
+
+    // 통계 카드들
+    stats.forEach((stat, index) => {
+      const x = 0.25 + index * (9 / stats.length);
+      const width = (9 / stats.length) - 0.3;
+
+      this.addStatCard(slide, x, 2, width, 1.5, stat);
+    });
+
+    return slide;
+  }
+
+  /**
+   * 파일 저장
+   */
+  async save(filename) {
+    const fs = require('fs');
+    const path = require('path');
+
+    // pptx 폴더 경로 생성
+    const pptxDir = 'pptx';
+    if (!fs.existsSync(pptxDir)) {
+      fs.mkdirSync(pptxDir, { recursive: true });
+    }
+
+    // 파일 경로 설정
+    const fullPath = path.join(pptxDir, filename);
+
+    await this.pres.writeFile({ fileName: fullPath });
+    return {
+      filename: fullPath,
+      slideCount: this.pres.slides.length,
+      success: true
+    };
+  }
+
+  /**
+   * 슬라이드 수 반환
+   */
+  getSlideCount() {
+    return this.pres.slides.length;
+  }
+}
+
+// 편의 함수들
+const createJoCodingPresentation = async (options = {}) => {
+  const generator = new EnhancedPPTXGenerator({
+    title: '조코딩(조웅현) - 국내 1위 코딩 교육 유튜버',
+    author: '조코딩',
+    brandColor: 'FF0000',
+    ...options
+  });
+
+  // 슬라이드 1: 표지
+  generator.createTitleSlide(
+    '조코딩',
+    'JoCoding',
+    '국내 1위 코딩 교육 유튜버'
+  );
+
+  // 슬라이드 2: 프로필
+  const profileItems = [
+    {
+      icon: '👤',
+      title: '기본 정보',
+      description: '• 실명: 조웅현\n• 전공: 고려대 환경생태공학부\n• 경력: 비전공자 → 개발자 → 교육자'
+    },
+    {
+      icon: '🚀',
+      title: '현재 활동',
+      description: '• 유튜브: 68만 구독자\n• 회사: ㈜코드마피아 대표\n• 서비스: 조카소 AI 개발/운영'
+    }
+  ];
+
+  generator.createContentSlide('프로필 개요', profileItems);
+
+  // 슬라이드 3: 통계
+  const stats = [
+    { number: '68만+', description: '유튜브 구독자', icon: '📺', color: 'FF0000' },
+    { number: '2019', description: '시작 연도', icon: '🗓️', color: '666666' },
+    { number: '2,000만+', description: '동물상 테스트', icon: '🤖', color: 'ff6600' },
+    { number: '1,000+', description: '교육생', icon: '🎓', color: '00aa00' }
+  ];
+
+  generator.createStatsSlide('주요 성과', stats);
+
+  return await generator.save(options.filename || '조코딩_프레젠테이션_모듈생성.pptx');
+};
+
+module.exports = {
+  EnhancedPPTXGenerator,
+  createJoCodingPresentation
+};

.claude/skills/pptx-skill/scripts/html2pptx.cjs

@@ -0,0 +1,979 @@
+/**
+ * html2pptx - Convert HTML slide to pptxgenjs slide with positioned elements
+ *
+ * USAGE:
+ *   const pptx = new pptxgen();
+ *   pptx.layout = 'LAYOUT_16x9';  // Must match HTML body dimensions
+ *
+ *   const { slide, placeholders } = await html2pptx('slide.html', pptx);
+ *   slide.addChart(pptx.charts.LINE, data, placeholders[0]);
+ *
+ *   await pptx.writeFile('output.pptx');
+ *
+ * FEATURES:
+ *   - Converts HTML to PowerPoint with accurate positioning
+ *   - Supports text, images, shapes, and bullet lists
+ *   - Extracts placeholder elements (class="placeholder") with positions
+ *   - Handles CSS gradients, borders, and margins
+ *
+ * VALIDATION:
+ *   - Uses body width/height from HTML for viewport sizing
+ *   - Throws error if HTML dimensions don't match presentation layout
+ *   - Throws error if content overflows body (with overflow details)
+ *
+ * RETURNS:
+ *   { slide, placeholders } where placeholders is an array of { id, x, y, w, h }
+ */
+
+const { chromium } = require('playwright');
+const path = require('path');
+const sharp = require('sharp');
+
+const PT_PER_PX = 0.75;
+const PX_PER_IN = 96;
+const EMU_PER_IN = 914400;
+
+// Helper: Get body dimensions and check for overflow
+async function getBodyDimensions(page) {
+  const bodyDimensions = await page.evaluate(() => {
+    const body = document.body;
+    const style = window.getComputedStyle(body);
+
+    return {
+      width: parseFloat(style.width),
+      height: parseFloat(style.height),
+      scrollWidth: body.scrollWidth,
+      scrollHeight: body.scrollHeight
+    };
+  });
+
+  const errors = [];
+  const widthOverflowPx = Math.max(0, bodyDimensions.scrollWidth - bodyDimensions.width - 1);
+  const heightOverflowPx = Math.max(0, bodyDimensions.scrollHeight - bodyDimensions.height - 1);
+
+  const widthOverflowPt = widthOverflowPx * PT_PER_PX;
+  const heightOverflowPt = heightOverflowPx * PT_PER_PX;
+
+  if (widthOverflowPt > 0 || heightOverflowPt > 0) {
+    const directions = [];
+    if (widthOverflowPt > 0) directions.push(`${widthOverflowPt.toFixed(1)}pt horizontally`);
+    if (heightOverflowPt > 0) directions.push(`${heightOverflowPt.toFixed(1)}pt vertically`);
+    const reminder = heightOverflowPt > 0 ? ' (Remember: leave 0.5" margin at bottom of slide)' : '';
+    errors.push(`HTML content overflows body by ${directions.join(' and ')}${reminder}`);
+  }
+
+  return { ...bodyDimensions, errors };
+}
+
+// Helper: Validate dimensions match presentation layout
+function validateDimensions(bodyDimensions, pres) {
+  const errors = [];
+  const widthInches = bodyDimensions.width / PX_PER_IN;
+  const heightInches = bodyDimensions.height / PX_PER_IN;
+
+  if (pres.presLayout) {
+    const layoutWidth = pres.presLayout.width / EMU_PER_IN;
+    const layoutHeight = pres.presLayout.height / EMU_PER_IN;
+
+    if (Math.abs(layoutWidth - widthInches) > 0.1 || Math.abs(layoutHeight - heightInches) > 0.1) {
+      errors.push(
+        `HTML dimensions (${widthInches.toFixed(1)}" × ${heightInches.toFixed(1)}") ` +
+        `don't match presentation layout (${layoutWidth.toFixed(1)}" × ${layoutHeight.toFixed(1)}")`
+      );
+    }
+  }
+  return errors;
+}
+
+function validateTextBoxPosition(slideData, bodyDimensions) {
+  const errors = [];
+  const slideHeightInches = bodyDimensions.height / PX_PER_IN;
+  const minBottomMargin = 0.5; // 0.5 inches from bottom
+
+  for (const el of slideData.elements) {
+    // Check text elements (p, h1-h6, list)
+    if (['p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'list'].includes(el.type)) {
+      const fontSize = el.style?.fontSize || 0;
+      const bottomEdge = el.position.y + el.position.h;
+      const distanceFromBottom = slideHeightInches - bottomEdge;
+
+      if (fontSize > 12 && distanceFromBottom < minBottomMargin) {
+        const getText = () => {
+          if (typeof el.text === 'string') return el.text;
+          if (Array.isArray(el.text)) return el.text.find(t => t.text)?.text || '';
+          if (Array.isArray(el.items)) return el.items.find(item => item.text)?.text || '';
+          return '';
+        };
+        const textPrefix = getText().substring(0, 50) + (getText().length > 50 ? '...' : '');
+
+        errors.push(
+          `Text box "${textPrefix}" ends too close to bottom edge ` +
+          `(${distanceFromBottom.toFixed(2)}" from bottom, minimum ${minBottomMargin}" required)`
+        );
+      }
+    }
+  }
+
+  return errors;
+}
+
+// Helper: Add background to slide
+async function addBackground(slideData, targetSlide, tmpDir) {
+  if (slideData.background.type === 'image' && slideData.background.path) {
+    let imagePath = slideData.background.path.startsWith('file://')
+      ? slideData.background.path.replace('file://', '')
+      : slideData.background.path;
+    targetSlide.background = { path: imagePath };
+  } else if (slideData.background.type === 'color' && slideData.background.value) {
+    targetSlide.background = { color: slideData.background.value };
+  }
+}
+
+// Helper: Add elements to slide
+function addElements(slideData, targetSlide, pres) {
+  for (const el of slideData.elements) {
+    if (el.type === 'image') {
+      let imagePath = el.src.startsWith('file://') ? el.src.replace('file://', '') : el.src;
+      targetSlide.addImage({
+        path: imagePath,
+        x: el.position.x,
+        y: el.position.y,
+        w: el.position.w,
+        h: el.position.h
+      });
+    } else if (el.type === 'line') {
+      targetSlide.addShape(pres.ShapeType.line, {
+        x: el.x1,
+        y: el.y1,
+        w: el.x2 - el.x1,
+        h: el.y2 - el.y1,
+        line: { color: el.color, width: el.width }
+      });
+    } else if (el.type === 'shape') {
+      const shapeOptions = {
+        x: el.position.x,
+        y: el.position.y,
+        w: el.position.w,
+        h: el.position.h,
+        shape: el.shape.rectRadius > 0 ? pres.ShapeType.roundRect : pres.ShapeType.rect
+      };
+
+      if (el.shape.fill) {
+        shapeOptions.fill = { color: el.shape.fill };
+        if (el.shape.transparency != null) shapeOptions.fill.transparency = el.shape.transparency;
+      }
+      if (el.shape.line) shapeOptions.line = el.shape.line;
+      if (el.shape.rectRadius > 0) shapeOptions.rectRadius = el.shape.rectRadius;
+      if (el.shape.shadow) shapeOptions.shadow = el.shape.shadow;
+
+      targetSlide.addText(el.text || '', shapeOptions);
+    } else if (el.type === 'list') {
+      const listOptions = {
+        x: el.position.x,
+        y: el.position.y,
+        w: el.position.w,
+        h: el.position.h,
+        fontSize: el.style.fontSize,
+        fontFace: el.style.fontFace,
+        color: el.style.color,
+        align: el.style.align,
+        valign: 'top',
+        lineSpacing: el.style.lineSpacing,
+        paraSpaceBefore: el.style.paraSpaceBefore,
+        paraSpaceAfter: el.style.paraSpaceAfter,
+        margin: el.style.margin
+      };
+      if (el.style.margin) listOptions.margin = el.style.margin;
+      targetSlide.addText(el.items, listOptions);
+    } else {
+      // Check if text is single-line (height suggests one line)
+      const lineHeight = el.style.lineSpacing || el.style.fontSize * 1.2;
+      const isSingleLine = el.position.h <= lineHeight * 1.5;
+
+      let adjustedX = el.position.x;
+      let adjustedW = el.position.w;
+
+      // Make single-line text 2% wider to account for underestimate
+      if (isSingleLine) {
+        const widthIncrease = el.position.w * 0.02;
+        const align = el.style.align;
+
+        if (align === 'center') {
+          // Center: expand both sides
+          adjustedX = el.position.x - (widthIncrease / 2);
+          adjustedW = el.position.w + widthIncrease;
+        } else if (align === 'right') {
+          // Right: expand to the left
+          adjustedX = el.position.x - widthIncrease;
+          adjustedW = el.position.w + widthIncrease;
+        } else {
+          // Left (default): expand to the right
+          adjustedW = el.position.w + widthIncrease;
+        }
+      }
+
+      const textOptions = {
+        x: adjustedX,
+        y: el.position.y,
+        w: adjustedW,
+        h: el.position.h,
+        fontSize: el.style.fontSize,
+        fontFace: el.style.fontFace,
+        color: el.style.color,
+        bold: el.style.bold,
+        italic: el.style.italic,
+        underline: el.style.underline,
+        valign: 'top',
+        lineSpacing: el.style.lineSpacing,
+        paraSpaceBefore: el.style.paraSpaceBefore,
+        paraSpaceAfter: el.style.paraSpaceAfter,
+        inset: 0  // Remove default PowerPoint internal padding
+      };
+
+      if (el.style.align) textOptions.align = el.style.align;
+      if (el.style.margin) textOptions.margin = el.style.margin;
+      if (el.style.rotate !== undefined) textOptions.rotate = el.style.rotate;
+      if (el.style.transparency !== null && el.style.transparency !== undefined) textOptions.transparency = el.style.transparency;
+
+      targetSlide.addText(el.text, textOptions);
+    }
+  }
+}
+
+// Helper: Extract slide data from HTML page
+async function extractSlideData(page) {
+  return await page.evaluate(() => {
+    const PT_PER_PX = 0.75;
+    const PX_PER_IN = 96;
+
+    // Fonts that are single-weight and should not have bold applied
+    // (applying bold causes PowerPoint to use faux bold which makes text wider)
+    const SINGLE_WEIGHT_FONTS = ['impact'];
+
+    // Helper: Check if a font should skip bold formatting
+    const shouldSkipBold = (fontFamily) => {
+      if (!fontFamily) return false;
+      const normalizedFont = fontFamily.toLowerCase().replace(/['"]/g, '').split(',')[0].trim();
+      return SINGLE_WEIGHT_FONTS.includes(normalizedFont);
+    };
+
+    // Unit conversion helpers
+    const pxToInch = (px) => px / PX_PER_IN;
+    const pxToPoints = (pxStr) => parseFloat(pxStr) * PT_PER_PX;
+    const rgbToHex = (rgbStr) => {
+      // Handle transparent backgrounds by defaulting to white
+      if (rgbStr === 'rgba(0, 0, 0, 0)' || rgbStr === 'transparent') return 'FFFFFF';
+
+      const match = rgbStr.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
+      if (!match) return 'FFFFFF';
+      return match.slice(1).map(n => parseInt(n).toString(16).padStart(2, '0')).join('');
+    };
+
+    const extractAlpha = (rgbStr) => {
+      const match = rgbStr.match(/rgba\((\d+),\s*(\d+),\s*(\d+),\s*([\d.]+)\)/);
+      if (!match || !match[4]) return null;
+      const alpha = parseFloat(match[4]);
+      return Math.round((1 - alpha) * 100);
+    };
+
+    const applyTextTransform = (text, textTransform) => {
+      if (textTransform === 'uppercase') return text.toUpperCase();
+      if (textTransform === 'lowercase') return text.toLowerCase();
+      if (textTransform === 'capitalize') {
+        return text.replace(/\b\w/g, c => c.toUpperCase());
+      }
+      return text;
+    };
+
+    // Extract rotation angle from CSS transform and writing-mode
+    const getRotation = (transform, writingMode) => {
+      let angle = 0;
+
+      // Handle writing-mode first
+      // PowerPoint: 90° = text rotated 90° clockwise (reads top to bottom, letters upright)
+      // PowerPoint: 270° = text rotated 270° clockwise (reads bottom to top, letters upright)
+      if (writingMode === 'vertical-rl') {
+        // vertical-rl alone = text reads top to bottom = 90° in PowerPoint
+        angle = 90;
+      } else if (writingMode === 'vertical-lr') {
+        // vertical-lr alone = text reads bottom to top = 270° in PowerPoint
+        angle = 270;
+      }
+
+      // Then add any transform rotation
+      if (transform && transform !== 'none') {
+        // Try to match rotate() function
+        const rotateMatch = transform.match(/rotate\((-?\d+(?:\.\d+)?)deg\)/);
+        if (rotateMatch) {
+          angle += parseFloat(rotateMatch[1]);
+        } else {
+          // Browser may compute as matrix - extract rotation from matrix
+          const matrixMatch = transform.match(/matrix\(([^)]+)\)/);
+          if (matrixMatch) {
+            const values = matrixMatch[1].split(',').map(parseFloat);
+            // matrix(a, b, c, d, e, f) where rotation = atan2(b, a)
+            const matrixAngle = Math.atan2(values[1], values[0]) * (180 / Math.PI);
+            angle += Math.round(matrixAngle);
+          }
+        }
+      }
+
+      // Normalize to 0-359 range
+      angle = angle % 360;
+      if (angle < 0) angle += 360;
+
+      return angle === 0 ? null : angle;
+    };
+
+    // Get position/dimensions accounting for rotation
+    const getPositionAndSize = (el, rect, rotation) => {
+      if (rotation === null) {
+        return { x: rect.left, y: rect.top, w: rect.width, h: rect.height };
+      }
+
+      // For 90° or 270° rotations, swap width and height
+      // because PowerPoint applies rotation to the original (unrotated) box
+      const isVertical = rotation === 90 || rotation === 270;
+
+      if (isVertical) {
+        // The browser shows us the rotated dimensions (tall box for vertical text)
+        // But PowerPoint needs the pre-rotation dimensions (wide box that will be rotated)
+        // So we swap: browser's height becomes PPT's width, browser's width becomes PPT's height
+        const centerX = rect.left + rect.width / 2;
+        const centerY = rect.top + rect.height / 2;
+
+        return {
+          x: centerX - rect.height / 2,
+          y: centerY - rect.width / 2,
+          w: rect.height,
+          h: rect.width
+        };
+      }
+
+      // For other rotations, use element's offset dimensions
+      const centerX = rect.left + rect.width / 2;
+      const centerY = rect.top + rect.height / 2;
+      return {
+        x: centerX - el.offsetWidth / 2,
+        y: centerY - el.offsetHeight / 2,
+        w: el.offsetWidth,
+        h: el.offsetHeight
+      };
+    };
+
+    // Parse CSS box-shadow into PptxGenJS shadow properties
+    const parseBoxShadow = (boxShadow) => {
+      if (!boxShadow || boxShadow === 'none') return null;
+
+      // Browser computed style format: "rgba(0, 0, 0, 0.3) 2px 2px 8px 0px [inset]"
+      // CSS format: "[inset] 2px 2px 8px 0px rgba(0, 0, 0, 0.3)"
+
+      const insetMatch = boxShadow.match(/inset/);
+
+      // IMPORTANT: PptxGenJS/PowerPoint doesn't properly support inset shadows
+      // Only process outer shadows to avoid file corruption
+      if (insetMatch) return null;
+
+      // Extract color first (rgba or rgb at start)
+      const colorMatch = boxShadow.match(/rgba?\([^)]+\)/);
+
+      // Extract numeric values (handles both px and pt units)
+      const parts = boxShadow.match(/([-\d.]+)(px|pt)/g);
+
+      if (!parts || parts.length < 2) return null;
+
+      const offsetX = parseFloat(parts[0]);
+      const offsetY = parseFloat(parts[1]);
+      const blur = parts.length > 2 ? parseFloat(parts[2]) : 0;
+
+      // Calculate angle from offsets (in degrees, 0 = right, 90 = down)
+      let angle = 0;
+      if (offsetX !== 0 || offsetY !== 0) {
+        angle = Math.atan2(offsetY, offsetX) * (180 / Math.PI);
+        if (angle < 0) angle += 360;
+      }
+
+      // Calculate offset distance (hypotenuse)
+      const offset = Math.sqrt(offsetX * offsetX + offsetY * offsetY) * PT_PER_PX;
+
+      // Extract opacity from rgba
+      let opacity = 0.5;
+      if (colorMatch) {
+        const opacityMatch = colorMatch[0].match(/[\d.]+\)$/);
+        if (opacityMatch) {
+          opacity = parseFloat(opacityMatch[0].replace(')', ''));
+        }
+      }
+
+      return {
+        type: 'outer',
+        angle: Math.round(angle),
+        blur: blur * 0.75, // Convert to points
+        color: colorMatch ? rgbToHex(colorMatch[0]) : '000000',
+        offset: offset,
+        opacity
+      };
+    };
+
+    // Parse inline formatting tags (<b>, <i>, <u>, <strong>, <em>, <span>) into text runs
+    const parseInlineFormatting = (element, baseOptions = {}, runs = [], baseTextTransform = (x) => x) => {
+      let prevNodeIsText = false;
+
+      element.childNodes.forEach((node) => {
+        let textTransform = baseTextTransform;
+
+        const isText = node.nodeType === Node.TEXT_NODE || node.tagName === 'BR';
+        if (isText) {
+          const text = node.tagName === 'BR' ? '\n' : textTransform(node.textContent.replace(/\s+/g, ' '));
+          const prevRun = runs[runs.length - 1];
+          if (prevNodeIsText && prevRun) {
+            prevRun.text += text;
+          } else {
+            runs.push({ text, options: { ...baseOptions } });
+          }
+
+        } else if (node.nodeType === Node.ELEMENT_NODE && node.textContent.trim()) {
+          const options = { ...baseOptions };
+          const computed = window.getComputedStyle(node);
+
+          // Handle inline elements with computed styles
+          if (node.tagName === 'SPAN' || node.tagName === 'B' || node.tagName === 'STRONG' || node.tagName === 'I' || node.tagName === 'EM' || node.tagName === 'U') {
+            const isBold = computed.fontWeight === 'bold' || parseInt(computed.fontWeight) >= 600;
+            if (isBold && !shouldSkipBold(computed.fontFamily)) options.bold = true;
+            if (computed.fontStyle === 'italic') options.italic = true;
+            if (computed.textDecoration && computed.textDecoration.includes('underline')) options.underline = true;
+            if (computed.color && computed.color !== 'rgb(0, 0, 0)') {
+              options.color = rgbToHex(computed.color);
+              const transparency = extractAlpha(computed.color);
+              if (transparency !== null) options.transparency = transparency;
+            }
+            if (computed.fontSize) options.fontSize = pxToPoints(computed.fontSize);
+
+            // Apply text-transform on the span element itself
+            if (computed.textTransform && computed.textTransform !== 'none') {
+              const transformStr = computed.textTransform;
+              textTransform = (text) => applyTextTransform(text, transformStr);
+            }
+
+            // Validate: Check for margins on inline elements
+            if (computed.marginLeft && parseFloat(computed.marginLeft) > 0) {
+              errors.push(`Inline element <${node.tagName.toLowerCase()}> has margin-left which is not supported in PowerPoint. Remove margin from inline elements.`);
+            }
+            if (computed.marginRight && parseFloat(computed.marginRight) > 0) {
+              errors.push(`Inline element <${node.tagName.toLowerCase()}> has margin-right which is not supported in PowerPoint. Remove margin from inline elements.`);
+            }
+            if (computed.marginTop && parseFloat(computed.marginTop) > 0) {
+              errors.push(`Inline element <${node.tagName.toLowerCase()}> has margin-top which is not supported in PowerPoint. Remove margin from inline elements.`);
+            }
+            if (computed.marginBottom && parseFloat(computed.marginBottom) > 0) {
+              errors.push(`Inline element <${node.tagName.toLowerCase()}> has margin-bottom which is not supported in PowerPoint. Remove margin from inline elements.`);
+            }
+
+            // Recursively process the child node. This will flatten nested spans into multiple runs.
+            parseInlineFormatting(node, options, runs, textTransform);
+          }
+        }
+
+        prevNodeIsText = isText;
+      });
+
+      // Trim leading space from first run and trailing space from last run
+      if (runs.length > 0) {
+        runs[0].text = runs[0].text.replace(/^\s+/, '');
+        runs[runs.length - 1].text = runs[runs.length - 1].text.replace(/\s+$/, '');
+      }
+
+      return runs.filter(r => r.text.length > 0);
+    };
+
+    // Extract background from body (image or color)
+    const body = document.body;
+    const bodyStyle = window.getComputedStyle(body);
+    const bgImage = bodyStyle.backgroundImage;
+    const bgColor = bodyStyle.backgroundColor;
+
+    // Collect validation errors
+    const errors = [];
+
+    // Validate: Check for CSS gradients
+    if (bgImage && (bgImage.includes('linear-gradient') || bgImage.includes('radial-gradient'))) {
+      errors.push(
+        'CSS gradients are not supported. Use Sharp to rasterize gradients as PNG images first, ' +
+        'then reference with background-image: url(\'gradient.png\')'
+      );
+    }
+
+    let background;
+    if (bgImage && bgImage !== 'none') {
+      // Extract URL from url("...") or url(...)
+      const urlMatch = bgImage.match(/url\(["']?([^"')]+)["']?\)/);
+      if (urlMatch) {
+        background = {
+          type: 'image',
+          path: urlMatch[1]
+        };
+      } else {
+        background = {
+          type: 'color',
+          value: rgbToHex(bgColor)
+        };
+      }
+    } else {
+      background = {
+        type: 'color',
+        value: rgbToHex(bgColor)
+      };
+    }
+
+    // Process all elements
+    const elements = [];
+    const placeholders = [];
+    const textTags = ['P', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'UL', 'OL', 'LI'];
+    const processed = new Set();
+
+    document.querySelectorAll('*').forEach((el) => {
+      if (processed.has(el)) return;
+
+      // Validate text elements don't have backgrounds, borders, or shadows
+      if (textTags.includes(el.tagName)) {
+        const computed = window.getComputedStyle(el);
+        const hasBg = computed.backgroundColor && computed.backgroundColor !== 'rgba(0, 0, 0, 0)';
+        const hasBorder = (computed.borderWidth && parseFloat(computed.borderWidth) > 0) ||
+                          (computed.borderTopWidth && parseFloat(computed.borderTopWidth) > 0) ||
+                          (computed.borderRightWidth && parseFloat(computed.borderRightWidth) > 0) ||
+                          (computed.borderBottomWidth && parseFloat(computed.borderBottomWidth) > 0) ||
+                          (computed.borderLeftWidth && parseFloat(computed.borderLeftWidth) > 0);
+        const hasShadow = computed.boxShadow && computed.boxShadow !== 'none';
+
+        if (hasBg || hasBorder || hasShadow) {
+          errors.push(
+            `Text element <${el.tagName.toLowerCase()}> has ${hasBg ? 'background' : hasBorder ? 'border' : 'shadow'}. ` +
+            'Backgrounds, borders, and shadows are only supported on <div> elements, not text elements.'
+          );
+          return;
+        }
+      }
+
+      // Extract placeholder elements (for charts, etc.)
+      if (el.className && el.className.includes('placeholder')) {
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 || rect.height === 0) {
+          errors.push(
+            `Placeholder "${el.id || 'unnamed'}" has ${rect.width === 0 ? 'width: 0' : 'height: 0'}. Check the layout CSS.`
+          );
+        } else {
+          placeholders.push({
+            id: el.id || `placeholder-${placeholders.length}`,
+            x: pxToInch(rect.left),
+            y: pxToInch(rect.top),
+            w: pxToInch(rect.width),
+            h: pxToInch(rect.height)
+          });
+        }
+        processed.add(el);
+        return;
+      }
+
+      // Extract images
+      if (el.tagName === 'IMG') {
+        const rect = el.getBoundingClientRect();
+        if (rect.width > 0 && rect.height > 0) {
+          elements.push({
+            type: 'image',
+            src: el.src,
+            position: {
+              x: pxToInch(rect.left),
+              y: pxToInch(rect.top),
+              w: pxToInch(rect.width),
+              h: pxToInch(rect.height)
+            }
+          });
+          processed.add(el);
+          return;
+        }
+      }
+
+      // Extract DIVs with backgrounds/borders as shapes
+      const isContainer = el.tagName === 'DIV' && !textTags.includes(el.tagName);
+      if (isContainer) {
+        const computed = window.getComputedStyle(el);
+        const hasBg = computed.backgroundColor && computed.backgroundColor !== 'rgba(0, 0, 0, 0)';
+
+        // Validate: Check for unwrapped text content in DIV
+        for (const node of el.childNodes) {
+          if (node.nodeType === Node.TEXT_NODE) {
+            const text = node.textContent.trim();
+            if (text) {
+              errors.push(
+                `DIV element contains unwrapped text "${text.substring(0, 50)}${text.length > 50 ? '...' : ''}". ` +
+                'All text must be wrapped in <p>, <h1>-<h6>, <ul>, or <ol> tags to appear in PowerPoint.'
+              );
+            }
+          }
+        }
+
+        // Check for background images on shapes
+        const bgImage = computed.backgroundImage;
+        if (bgImage && bgImage !== 'none') {
+          errors.push(
+            'Background images on DIV elements are not supported. ' +
+            'Use solid colors or borders for shapes, or use slide.addImage() in PptxGenJS to layer images.'
+          );
+          return;
+        }
+
+        // Check for borders - both uniform and partial
+        const borderTop = computed.borderTopWidth;
+        const borderRight = computed.borderRightWidth;
+        const borderBottom = computed.borderBottomWidth;
+        const borderLeft = computed.borderLeftWidth;
+        const borders = [borderTop, borderRight, borderBottom, borderLeft].map(b => parseFloat(b) || 0);
+        const hasBorder = borders.some(b => b > 0);
+        const hasUniformBorder = hasBorder && borders.every(b => b === borders[0]);
+        const borderLines = [];
+
+        if (hasBorder && !hasUniformBorder) {
+          const rect = el.getBoundingClientRect();
+          const x = pxToInch(rect.left);
+          const y = pxToInch(rect.top);
+          const w = pxToInch(rect.width);
+          const h = pxToInch(rect.height);
+
+          // Collect lines to add after shape (inset by half the line width to center on edge)
+          if (parseFloat(borderTop) > 0) {
+            const widthPt = pxToPoints(borderTop);
+            const inset = (widthPt / 72) / 2; // Convert points to inches, then half
+            borderLines.push({
+              type: 'line',
+              x1: x, y1: y + inset, x2: x + w, y2: y + inset,
+              width: widthPt,
+              color: rgbToHex(computed.borderTopColor)
+            });
+          }
+          if (parseFloat(borderRight) > 0) {
+            const widthPt = pxToPoints(borderRight);
+            const inset = (widthPt / 72) / 2;
+            borderLines.push({
+              type: 'line',
+              x1: x + w - inset, y1: y, x2: x + w - inset, y2: y + h,
+              width: widthPt,
+              color: rgbToHex(computed.borderRightColor)
+            });
+          }
+          if (parseFloat(borderBottom) > 0) {
+            const widthPt = pxToPoints(borderBottom);
+            const inset = (widthPt / 72) / 2;
+            borderLines.push({
+              type: 'line',
+              x1: x, y1: y + h - inset, x2: x + w, y2: y + h - inset,
+              width: widthPt,
+              color: rgbToHex(computed.borderBottomColor)
+            });
+          }
+          if (parseFloat(borderLeft) > 0) {
+            const widthPt = pxToPoints(borderLeft);
+            const inset = (widthPt / 72) / 2;
+            borderLines.push({
+              type: 'line',
+              x1: x + inset, y1: y, x2: x + inset, y2: y + h,
+              width: widthPt,
+              color: rgbToHex(computed.borderLeftColor)
+            });
+          }
+        }
+
+        if (hasBg || hasBorder) {
+          const rect = el.getBoundingClientRect();
+          if (rect.width > 0 && rect.height > 0) {
+            const shadow = parseBoxShadow(computed.boxShadow);
+
+            // Only add shape if there's background or uniform border
+            if (hasBg || hasUniformBorder) {
+              elements.push({
+                type: 'shape',
+                text: '',  // Shape only - child text elements render on top
+                position: {
+                  x: pxToInch(rect.left),
+                  y: pxToInch(rect.top),
+                  w: pxToInch(rect.width),
+                  h: pxToInch(rect.height)
+                },
+                shape: {
+                  fill: hasBg ? rgbToHex(computed.backgroundColor) : null,
+                  transparency: hasBg ? extractAlpha(computed.backgroundColor) : null,
+                  line: hasUniformBorder ? {
+                    color: rgbToHex(computed.borderColor),
+                    width: pxToPoints(computed.borderWidth)
+                  } : null,
+                  // Convert border-radius to rectRadius (in inches)
+                  // % values: 50%+ = circle (1), <50% = percentage of min dimension
+                  // pt values: divide by 72 (72pt = 1 inch)
+                  // px values: divide by 96 (96px = 1 inch)
+                  rectRadius: (() => {
+                    const radius = computed.borderRadius;
+                    const radiusValue = parseFloat(radius);
+                    if (radiusValue === 0) return 0;
+
+                    if (radius.includes('%')) {
+                      if (radiusValue >= 50) return 1;
+                      // Calculate percentage of smaller dimension
+                      const minDim = Math.min(rect.width, rect.height);
+                      return (radiusValue / 100) * pxToInch(minDim);
+                    }
+
+                    if (radius.includes('pt')) return radiusValue / 72;
+                    return radiusValue / PX_PER_IN;
+                  })(),
+                  shadow: shadow
+                }
+              });
+            }
+
+            // Add partial border lines
+            elements.push(...borderLines);
+
+            processed.add(el);
+            return;
+          }
+        }
+      }
+
+      // Extract bullet lists as single text block
+      if (el.tagName === 'UL' || el.tagName === 'OL') {
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 || rect.height === 0) return;
+
+        const liElements = Array.from(el.querySelectorAll('li'));
+        const items = [];
+        const ulComputed = window.getComputedStyle(el);
+        const ulPaddingLeftPt = pxToPoints(ulComputed.paddingLeft);
+
+        // Split: margin-left for bullet position, indent for text position
+        // margin-left + indent = ul padding-left
+        const marginLeft = ulPaddingLeftPt * 0.5;
+        const textIndent = ulPaddingLeftPt * 0.5;
+
+        liElements.forEach((li, idx) => {
+          const isLast = idx === liElements.length - 1;
+          const runs = parseInlineFormatting(li, { breakLine: false });
+          // Clean manual bullets from first run
+          if (runs.length > 0) {
+            runs[0].text = runs[0].text.replace(/^[•\-\*▪▸]\s*/, '');
+            runs[0].options.bullet = { indent: textIndent };
+          }
+          // Set breakLine on last run
+          if (runs.length > 0 && !isLast) {
+            runs[runs.length - 1].options.breakLine = true;
+          }
+          items.push(...runs);
+        });
+
+        const computed = window.getComputedStyle(liElements[0] || el);
+
+        elements.push({
+          type: 'list',
+          items: items,
+          position: {
+            x: pxToInch(rect.left),
+            y: pxToInch(rect.top),
+            w: pxToInch(rect.width),
+            h: pxToInch(rect.height)
+          },
+          style: {
+            fontSize: pxToPoints(computed.fontSize),
+            fontFace: computed.fontFamily.split(',')[0].replace(/['"]/g, '').trim(),
+            color: rgbToHex(computed.color),
+            transparency: extractAlpha(computed.color),
+            align: computed.textAlign === 'start' ? 'left' : computed.textAlign,
+            lineSpacing: computed.lineHeight && computed.lineHeight !== 'normal' ? pxToPoints(computed.lineHeight) : null,
+            paraSpaceBefore: 0,
+            paraSpaceAfter: pxToPoints(computed.marginBottom),
+            // PptxGenJS margin array is [left, right, bottom, top]
+            margin: [marginLeft, 0, 0, 0]
+          }
+        });
+
+        liElements.forEach(li => processed.add(li));
+        processed.add(el);
+        return;
+      }
+
+      // Extract text elements (P, H1, H2, etc.)
+      if (!textTags.includes(el.tagName)) return;
+
+      const rect = el.getBoundingClientRect();
+      const text = el.textContent.trim();
+      if (rect.width === 0 || rect.height === 0 || !text) return;
+
+      // Validate: Check for manual bullet symbols in text elements (not in lists)
+      if (el.tagName !== 'LI' && /^[•\-\*▪▸○●◆◇■□]\s/.test(text.trimStart())) {
+        errors.push(
+          `Text element <${el.tagName.toLowerCase()}> starts with bullet symbol "${text.substring(0, 20)}...". ` +
+          'Use <ul> or <ol> lists instead of manual bullet symbols.'
+        );
+        return;
+      }
+
+      const computed = window.getComputedStyle(el);
+      const rotation = getRotation(computed.transform, computed.writingMode);
+      const { x, y, w, h } = getPositionAndSize(el, rect, rotation);
+
+      const baseStyle = {
+        fontSize: pxToPoints(computed.fontSize),
+        fontFace: computed.fontFamily.split(',')[0].replace(/['"]/g, '').trim(),
+        color: rgbToHex(computed.color),
+        align: computed.textAlign === 'start' ? 'left' : computed.textAlign,
+        lineSpacing: pxToPoints(computed.lineHeight),
+        paraSpaceBefore: pxToPoints(computed.marginTop),
+        paraSpaceAfter: pxToPoints(computed.marginBottom),
+        // PptxGenJS margin array is [left, right, bottom, top] (not [top, right, bottom, left] as documented)
+        margin: [
+          pxToPoints(computed.paddingLeft),
+          pxToPoints(computed.paddingRight),
+          pxToPoints(computed.paddingBottom),
+          pxToPoints(computed.paddingTop)
+        ]
+      };
+
+      const transparency = extractAlpha(computed.color);
+      if (transparency !== null) baseStyle.transparency = transparency;
+
+      if (rotation !== null) baseStyle.rotate = rotation;
+
+      const hasFormatting = el.querySelector('b, i, u, strong, em, span, br');
+
+      if (hasFormatting) {
+        // Text with inline formatting
+        const transformStr = computed.textTransform;
+        const runs = parseInlineFormatting(el, {}, [], (str) => applyTextTransform(str, transformStr));
+
+        // Adjust lineSpacing based on largest fontSize in runs
+        const adjustedStyle = { ...baseStyle };
+        if (adjustedStyle.lineSpacing) {
+          const maxFontSize = Math.max(
+            adjustedStyle.fontSize,
+            ...runs.map(r => r.options?.fontSize || 0)
+          );
+          if (maxFontSize > adjustedStyle.fontSize) {
+            const lineHeightMultiplier = adjustedStyle.lineSpacing / adjustedStyle.fontSize;
+            adjustedStyle.lineSpacing = maxFontSize * lineHeightMultiplier;
+          }
+        }
+
+        elements.push({
+          type: el.tagName.toLowerCase(),
+          text: runs,
+          position: { x: pxToInch(x), y: pxToInch(y), w: pxToInch(w), h: pxToInch(h) },
+          style: adjustedStyle
+        });
+      } else {
+        // Plain text - inherit CSS formatting
+        const textTransform = computed.textTransform;
+        const transformedText = applyTextTransform(text, textTransform);
+
+        const isBold = computed.fontWeight === 'bold' || parseInt(computed.fontWeight) >= 600;
+
+        elements.push({
+          type: el.tagName.toLowerCase(),
+          text: transformedText,
+          position: { x: pxToInch(x), y: pxToInch(y), w: pxToInch(w), h: pxToInch(h) },
+          style: {
+            ...baseStyle,
+            bold: isBold && !shouldSkipBold(computed.fontFamily),
+            italic: computed.fontStyle === 'italic',
+            underline: computed.textDecoration.includes('underline')
+          }
+        });
+      }
+
+      processed.add(el);
+    });
+
+    return { background, elements, placeholders, errors };
+  });
+}
+
+async function html2pptx(htmlFile, pres, options = {}) {
+  const {
+    tmpDir = process.env.TMPDIR || '/tmp',
+    slide = null
+  } = options;
+
+  try {
+    // Use Chrome on macOS, default Chromium on Unix
+    const launchOptions = { env: { TMPDIR: tmpDir } };
+    if (process.platform === 'darwin') {
+      launchOptions.channel = 'chrome';
+    }
+
+    const browser = await chromium.launch(launchOptions);
+
+    let bodyDimensions;
+    let slideData;
+
+    const filePath = path.isAbsolute(htmlFile) ? htmlFile : path.join(process.cwd(), htmlFile);
+    const validationErrors = [];
+
+    try {
+      const page = await browser.newPage();
+      page.on('console', (msg) => {
+        // Log the message text to your test runner's console
+        console.log(`Browser console: ${msg.text()}`);
+      });
+
+      await page.goto(`file://${filePath}`);
+
+      bodyDimensions = await getBodyDimensions(page);
+
+      await page.setViewportSize({
+        width: Math.round(bodyDimensions.width),
+        height: Math.round(bodyDimensions.height)
+      });
+
+      slideData = await extractSlideData(page);
+    } finally {
+      await browser.close();
+    }
+
+    // Collect all validation errors
+    if (bodyDimensions.errors && bodyDimensions.errors.length > 0) {
+      validationErrors.push(...bodyDimensions.errors);
+    }
+
+    const dimensionErrors = validateDimensions(bodyDimensions, pres);
+    if (dimensionErrors.length > 0) {
+      validationErrors.push(...dimensionErrors);
+    }
+
+    const textBoxPositionErrors = validateTextBoxPosition(slideData, bodyDimensions);
+    if (textBoxPositionErrors.length > 0) {
+      validationErrors.push(...textBoxPositionErrors);
+    }
+
+    if (slideData.errors && slideData.errors.length > 0) {
+      validationErrors.push(...slideData.errors);
+    }
+
+    // Throw all errors at once if any exist
+    if (validationErrors.length > 0) {
+      const errorMessage = validationErrors.length === 1
+        ? validationErrors[0]
+        : `Multiple validation errors found:\n${validationErrors.map((e, i) => `  ${i + 1}. ${e}`).join('\n')}`;
+      throw new Error(errorMessage);
+    }
+
+    const targetSlide = slide || pres.addSlide();
+
+    await addBackground(slideData, targetSlide, tmpDir);
+    addElements(slideData, targetSlide, pres);
+
+    return { slide: targetSlide, placeholders: slideData.placeholders };
+  } catch (error) {
+    if (!error.message.startsWith(htmlFile)) {
+      throw new Error(`${htmlFile}: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+module.exports = html2pptx;

.claude/skills/pptx-skill/scripts/html2pptx.js

@@ -0,0 +1,979 @@
+/**
+ * html2pptx - Convert HTML slide to pptxgenjs slide with positioned elements
+ *
+ * USAGE:
+ *   const pptx = new pptxgen();
+ *   pptx.layout = 'LAYOUT_16x9';  // Must match HTML body dimensions
+ *
+ *   const { slide, placeholders } = await html2pptx('slide.html', pptx);
+ *   slide.addChart(pptx.charts.LINE, data, placeholders[0]);
+ *
+ *   await pptx.writeFile('output.pptx');
+ *
+ * FEATURES:
+ *   - Converts HTML to PowerPoint with accurate positioning
+ *   - Supports text, images, shapes, and bullet lists
+ *   - Extracts placeholder elements (class="placeholder") with positions
+ *   - Handles CSS gradients, borders, and margins
+ *
+ * VALIDATION:
+ *   - Uses body width/height from HTML for viewport sizing
+ *   - Throws error if HTML dimensions don't match presentation layout
+ *   - Throws error if content overflows body (with overflow details)
+ *
+ * RETURNS:
+ *   { slide, placeholders } where placeholders is an array of { id, x, y, w, h }
+ */
+
+const { chromium } = require('playwright');
+const path = require('path');
+const sharp = require('sharp');
+
+const PT_PER_PX = 0.75;
+const PX_PER_IN = 96;
+const EMU_PER_IN = 914400;
+
+// Helper: Get body dimensions and check for overflow
+async function getBodyDimensions(page) {
+  const bodyDimensions = await page.evaluate(() => {
+    const body = document.body;
+    const style = window.getComputedStyle(body);
+
+    return {
+      width: parseFloat(style.width),
+      height: parseFloat(style.height),
+      scrollWidth: body.scrollWidth,
+      scrollHeight: body.scrollHeight
+    };
+  });
+
+  const errors = [];
+  const widthOverflowPx = Math.max(0, bodyDimensions.scrollWidth - bodyDimensions.width - 1);
+  const heightOverflowPx = Math.max(0, bodyDimensions.scrollHeight - bodyDimensions.height - 1);
+
+  const widthOverflowPt = widthOverflowPx * PT_PER_PX;
+  const heightOverflowPt = heightOverflowPx * PT_PER_PX;
+
+  if (widthOverflowPt > 0 || heightOverflowPt > 0) {
+    const directions = [];
+    if (widthOverflowPt > 0) directions.push(`${widthOverflowPt.toFixed(1)}pt horizontally`);
+    if (heightOverflowPt > 0) directions.push(`${heightOverflowPt.toFixed(1)}pt vertically`);
+    const reminder = heightOverflowPt > 0 ? ' (Remember: leave 0.5" margin at bottom of slide)' : '';
+    errors.push(`HTML content overflows body by ${directions.join(' and ')}${reminder}`);
+  }
+
+  return { ...bodyDimensions, errors };
+}
+
+// Helper: Validate dimensions match presentation layout
+function validateDimensions(bodyDimensions, pres) {
+  const errors = [];
+  const widthInches = bodyDimensions.width / PX_PER_IN;
+  const heightInches = bodyDimensions.height / PX_PER_IN;
+
+  if (pres.presLayout) {
+    const layoutWidth = pres.presLayout.width / EMU_PER_IN;
+    const layoutHeight = pres.presLayout.height / EMU_PER_IN;
+
+    if (Math.abs(layoutWidth - widthInches) > 0.1 || Math.abs(layoutHeight - heightInches) > 0.1) {
+      errors.push(
+        `HTML dimensions (${widthInches.toFixed(1)}" × ${heightInches.toFixed(1)}") ` +
+        `don't match presentation layout (${layoutWidth.toFixed(1)}" × ${layoutHeight.toFixed(1)}")`
+      );
+    }
+  }
+  return errors;
+}
+
+function validateTextBoxPosition(slideData, bodyDimensions) {
+  const errors = [];
+  const slideHeightInches = bodyDimensions.height / PX_PER_IN;
+  const minBottomMargin = 0.5; // 0.5 inches from bottom
+
+  for (const el of slideData.elements) {
+    // Check text elements (p, h1-h6, list)
+    if (['p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'list'].includes(el.type)) {
+      const fontSize = el.style?.fontSize || 0;
+      const bottomEdge = el.position.y + el.position.h;
+      const distanceFromBottom = slideHeightInches - bottomEdge;
+
+      if (fontSize > 12 && distanceFromBottom < minBottomMargin) {
+        const getText = () => {
+          if (typeof el.text === 'string') return el.text;
+          if (Array.isArray(el.text)) return el.text.find(t => t.text)?.text || '';
+          if (Array.isArray(el.items)) return el.items.find(item => item.text)?.text || '';
+          return '';
+        };
+        const textPrefix = getText().substring(0, 50) + (getText().length > 50 ? '...' : '');
+
+        errors.push(
+          `Text box "${textPrefix}" ends too close to bottom edge ` +
+          `(${distanceFromBottom.toFixed(2)}" from bottom, minimum ${minBottomMargin}" required)`
+        );
+      }
+    }
+  }
+
+  return errors;
+}
+
+// Helper: Add background to slide
+async function addBackground(slideData, targetSlide, tmpDir) {
+  if (slideData.background.type === 'image' && slideData.background.path) {
+    let imagePath = slideData.background.path.startsWith('file://')
+      ? slideData.background.path.replace('file://', '')
+      : slideData.background.path;
+    targetSlide.background = { path: imagePath };
+  } else if (slideData.background.type === 'color' && slideData.background.value) {
+    targetSlide.background = { color: slideData.background.value };
+  }
+}
+
+// Helper: Add elements to slide
+function addElements(slideData, targetSlide, pres) {
+  for (const el of slideData.elements) {
+    if (el.type === 'image') {
+      let imagePath = el.src.startsWith('file://') ? el.src.replace('file://', '') : el.src;
+      targetSlide.addImage({
+        path: imagePath,
+        x: el.position.x,
+        y: el.position.y,
+        w: el.position.w,
+        h: el.position.h
+      });
+    } else if (el.type === 'line') {
+      targetSlide.addShape(pres.ShapeType.line, {
+        x: el.x1,
+        y: el.y1,
+        w: el.x2 - el.x1,
+        h: el.y2 - el.y1,
+        line: { color: el.color, width: el.width }
+      });
+    } else if (el.type === 'shape') {
+      const shapeOptions = {
+        x: el.position.x,
+        y: el.position.y,
+        w: el.position.w,
+        h: el.position.h,
+        shape: el.shape.rectRadius > 0 ? pres.ShapeType.roundRect : pres.ShapeType.rect
+      };
+
+      if (el.shape.fill) {
+        shapeOptions.fill = { color: el.shape.fill };
+        if (el.shape.transparency != null) shapeOptions.fill.transparency = el.shape.transparency;
+      }
+      if (el.shape.line) shapeOptions.line = el.shape.line;
+      if (el.shape.rectRadius > 0) shapeOptions.rectRadius = el.shape.rectRadius;
+      if (el.shape.shadow) shapeOptions.shadow = el.shape.shadow;
+
+      targetSlide.addText(el.text || '', shapeOptions);
+    } else if (el.type === 'list') {
+      const listOptions = {
+        x: el.position.x,
+        y: el.position.y,
+        w: el.position.w,
+        h: el.position.h,
+        fontSize: el.style.fontSize,
+        fontFace: el.style.fontFace,
+        color: el.style.color,
+        align: el.style.align,
+        valign: 'top',
+        lineSpacing: el.style.lineSpacing,
+        paraSpaceBefore: el.style.paraSpaceBefore,
+        paraSpaceAfter: el.style.paraSpaceAfter,
+        margin: el.style.margin
+      };
+      if (el.style.margin) listOptions.margin = el.style.margin;
+      targetSlide.addText(el.items, listOptions);
+    } else {
+      // Check if text is single-line (height suggests one line)
+      const lineHeight = el.style.lineSpacing || el.style.fontSize * 1.2;
+      const isSingleLine = el.position.h <= lineHeight * 1.5;
+
+      let adjustedX = el.position.x;
+      let adjustedW = el.position.w;
+
+      // Make single-line text 2% wider to account for underestimate
+      if (isSingleLine) {
+        const widthIncrease = el.position.w * 0.02;
+        const align = el.style.align;
+
+        if (align === 'center') {
+          // Center: expand both sides
+          adjustedX = el.position.x - (widthIncrease / 2);
+          adjustedW = el.position.w + widthIncrease;
+        } else if (align === 'right') {
+          // Right: expand to the left
+          adjustedX = el.position.x - widthIncrease;
+          adjustedW = el.position.w + widthIncrease;
+        } else {
+          // Left (default): expand to the right
+          adjustedW = el.position.w + widthIncrease;
+        }
+      }
+
+      const textOptions = {
+        x: adjustedX,
+        y: el.position.y,
+        w: adjustedW,
+        h: el.position.h,
+        fontSize: el.style.fontSize,
+        fontFace: el.style.fontFace,
+        color: el.style.color,
+        bold: el.style.bold,
+        italic: el.style.italic,
+        underline: el.style.underline,
+        valign: 'top',
+        lineSpacing: el.style.lineSpacing,
+        paraSpaceBefore: el.style.paraSpaceBefore,
+        paraSpaceAfter: el.style.paraSpaceAfter,
+        inset: 0  // Remove default PowerPoint internal padding
+      };
+
+      if (el.style.align) textOptions.align = el.style.align;
+      if (el.style.margin) textOptions.margin = el.style.margin;
+      if (el.style.rotate !== undefined) textOptions.rotate = el.style.rotate;
+      if (el.style.transparency !== null && el.style.transparency !== undefined) textOptions.transparency = el.style.transparency;
+
+      targetSlide.addText(el.text, textOptions);
+    }
+  }
+}
+
+// Helper: Extract slide data from HTML page
+async function extractSlideData(page) {
+  return await page.evaluate(() => {
+    const PT_PER_PX = 0.75;
+    const PX_PER_IN = 96;
+
+    // Fonts that are single-weight and should not have bold applied
+    // (applying bold causes PowerPoint to use faux bold which makes text wider)
+    const SINGLE_WEIGHT_FONTS = ['impact'];
+
+    // Helper: Check if a font should skip bold formatting
+    const shouldSkipBold = (fontFamily) => {
+      if (!fontFamily) return false;
+      const normalizedFont = fontFamily.toLowerCase().replace(/['"]/g, '').split(',')[0].trim();
+      return SINGLE_WEIGHT_FONTS.includes(normalizedFont);
+    };
+
+    // Unit conversion helpers
+    const pxToInch = (px) => px / PX_PER_IN;
+    const pxToPoints = (pxStr) => parseFloat(pxStr) * PT_PER_PX;
+    const rgbToHex = (rgbStr) => {
+      // Handle transparent backgrounds by defaulting to white
+      if (rgbStr === 'rgba(0, 0, 0, 0)' || rgbStr === 'transparent') return 'FFFFFF';
+
+      const match = rgbStr.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
+      if (!match) return 'FFFFFF';
+      return match.slice(1).map(n => parseInt(n).toString(16).padStart(2, '0')).join('');
+    };
+
+    const extractAlpha = (rgbStr) => {
+      const match = rgbStr.match(/rgba\((\d+),\s*(\d+),\s*(\d+),\s*([\d.]+)\)/);
+      if (!match || !match[4]) return null;
+      const alpha = parseFloat(match[4]);
+      return Math.round((1 - alpha) * 100);
+    };
+
+    const applyTextTransform = (text, textTransform) => {
+      if (textTransform === 'uppercase') return text.toUpperCase();
+      if (textTransform === 'lowercase') return text.toLowerCase();
+      if (textTransform === 'capitalize') {
+        return text.replace(/\b\w/g, c => c.toUpperCase());
+      }
+      return text;
+    };
+
+    // Extract rotation angle from CSS transform and writing-mode
+    const getRotation = (transform, writingMode) => {
+      let angle = 0;
+
+      // Handle writing-mode first
+      // PowerPoint: 90° = text rotated 90° clockwise (reads top to bottom, letters upright)
+      // PowerPoint: 270° = text rotated 270° clockwise (reads bottom to top, letters upright)
+      if (writingMode === 'vertical-rl') {
+        // vertical-rl alone = text reads top to bottom = 90° in PowerPoint
+        angle = 90;
+      } else if (writingMode === 'vertical-lr') {
+        // vertical-lr alone = text reads bottom to top = 270° in PowerPoint
+        angle = 270;
+      }
+
+      // Then add any transform rotation
+      if (transform && transform !== 'none') {
+        // Try to match rotate() function
+        const rotateMatch = transform.match(/rotate\((-?\d+(?:\.\d+)?)deg\)/);
+        if (rotateMatch) {
+          angle += parseFloat(rotateMatch[1]);
+        } else {
+          // Browser may compute as matrix - extract rotation from matrix
+          const matrixMatch = transform.match(/matrix\(([^)]+)\)/);
+          if (matrixMatch) {
+            const values = matrixMatch[1].split(',').map(parseFloat);
+            // matrix(a, b, c, d, e, f) where rotation = atan2(b, a)
+            const matrixAngle = Math.atan2(values[1], values[0]) * (180 / Math.PI);
+            angle += Math.round(matrixAngle);
+          }
+        }
+      }
+
+      // Normalize to 0-359 range
+      angle = angle % 360;
+      if (angle < 0) angle += 360;
+
+      return angle === 0 ? null : angle;
+    };
+
+    // Get position/dimensions accounting for rotation
+    const getPositionAndSize = (el, rect, rotation) => {
+      if (rotation === null) {
+        return { x: rect.left, y: rect.top, w: rect.width, h: rect.height };
+      }
+
+      // For 90° or 270° rotations, swap width and height
+      // because PowerPoint applies rotation to the original (unrotated) box
+      const isVertical = rotation === 90 || rotation === 270;
+
+      if (isVertical) {
+        // The browser shows us the rotated dimensions (tall box for vertical text)
+        // But PowerPoint needs the pre-rotation dimensions (wide box that will be rotated)
+        // So we swap: browser's height becomes PPT's width, browser's width becomes PPT's height
+        const centerX = rect.left + rect.width / 2;
+        const centerY = rect.top + rect.height / 2;
+
+        return {
+          x: centerX - rect.height / 2,
+          y: centerY - rect.width / 2,
+          w: rect.height,
+          h: rect.width
+        };
+      }
+
+      // For other rotations, use element's offset dimensions
+      const centerX = rect.left + rect.width / 2;
+      const centerY = rect.top + rect.height / 2;
+      return {
+        x: centerX - el.offsetWidth / 2,
+        y: centerY - el.offsetHeight / 2,
+        w: el.offsetWidth,
+        h: el.offsetHeight
+      };
+    };
+
+    // Parse CSS box-shadow into PptxGenJS shadow properties
+    const parseBoxShadow = (boxShadow) => {
+      if (!boxShadow || boxShadow === 'none') return null;
+
+      // Browser computed style format: "rgba(0, 0, 0, 0.3) 2px 2px 8px 0px [inset]"
+      // CSS format: "[inset] 2px 2px 8px 0px rgba(0, 0, 0, 0.3)"
+
+      const insetMatch = boxShadow.match(/inset/);
+
+      // IMPORTANT: PptxGenJS/PowerPoint doesn't properly support inset shadows
+      // Only process outer shadows to avoid file corruption
+      if (insetMatch) return null;
+
+      // Extract color first (rgba or rgb at start)
+      const colorMatch = boxShadow.match(/rgba?\([^)]+\)/);
+
+      // Extract numeric values (handles both px and pt units)
+      const parts = boxShadow.match(/([-\d.]+)(px|pt)/g);
+
+      if (!parts || parts.length < 2) return null;
+
+      const offsetX = parseFloat(parts[0]);
+      const offsetY = parseFloat(parts[1]);
+      const blur = parts.length > 2 ? parseFloat(parts[2]) : 0;
+
+      // Calculate angle from offsets (in degrees, 0 = right, 90 = down)
+      let angle = 0;
+      if (offsetX !== 0 || offsetY !== 0) {
+        angle = Math.atan2(offsetY, offsetX) * (180 / Math.PI);
+        if (angle < 0) angle += 360;
+      }
+
+      // Calculate offset distance (hypotenuse)
+      const offset = Math.sqrt(offsetX * offsetX + offsetY * offsetY) * PT_PER_PX;
+
+      // Extract opacity from rgba
+      let opacity = 0.5;
+      if (colorMatch) {
+        const opacityMatch = colorMatch[0].match(/[\d.]+\)$/);
+        if (opacityMatch) {
+          opacity = parseFloat(opacityMatch[0].replace(')', ''));
+        }
+      }
+
+      return {
+        type: 'outer',
+        angle: Math.round(angle),
+        blur: blur * 0.75, // Convert to points
+        color: colorMatch ? rgbToHex(colorMatch[0]) : '000000',
+        offset: offset,
+        opacity
+      };
+    };
+
+    // Parse inline formatting tags (<b>, <i>, <u>, <strong>, <em>, <span>) into text runs
+    const parseInlineFormatting = (element, baseOptions = {}, runs = [], baseTextTransform = (x) => x) => {
+      let prevNodeIsText = false;
+
+      element.childNodes.forEach((node) => {
+        let textTransform = baseTextTransform;
+
+        const isText = node.nodeType === Node.TEXT_NODE || node.tagName === 'BR';
+        if (isText) {
+          const text = node.tagName === 'BR' ? '\n' : textTransform(node.textContent.replace(/\s+/g, ' '));
+          const prevRun = runs[runs.length - 1];
+          if (prevNodeIsText && prevRun) {
+            prevRun.text += text;
+          } else {
+            runs.push({ text, options: { ...baseOptions } });
+          }
+
+        } else if (node.nodeType === Node.ELEMENT_NODE && node.textContent.trim()) {
+          const options = { ...baseOptions };
+          const computed = window.getComputedStyle(node);
+
+          // Handle inline elements with computed styles
+          if (node.tagName === 'SPAN' || node.tagName === 'B' || node.tagName === 'STRONG' || node.tagName === 'I' || node.tagName === 'EM' || node.tagName === 'U') {
+            const isBold = computed.fontWeight === 'bold' || parseInt(computed.fontWeight) >= 600;
+            if (isBold && !shouldSkipBold(computed.fontFamily)) options.bold = true;
+            if (computed.fontStyle === 'italic') options.italic = true;
+            if (computed.textDecoration && computed.textDecoration.includes('underline')) options.underline = true;
+            if (computed.color && computed.color !== 'rgb(0, 0, 0)') {
+              options.color = rgbToHex(computed.color);
+              const transparency = extractAlpha(computed.color);
+              if (transparency !== null) options.transparency = transparency;
+            }
+            if (computed.fontSize) options.fontSize = pxToPoints(computed.fontSize);
+
+            // Apply text-transform on the span element itself
+            if (computed.textTransform && computed.textTransform !== 'none') {
+              const transformStr = computed.textTransform;
+              textTransform = (text) => applyTextTransform(text, transformStr);
+            }
+
+            // Validate: Check for margins on inline elements
+            if (computed.marginLeft && parseFloat(computed.marginLeft) > 0) {
+              errors.push(`Inline element <${node.tagName.toLowerCase()}> has margin-left which is not supported in PowerPoint. Remove margin from inline elements.`);
+            }
+            if (computed.marginRight && parseFloat(computed.marginRight) > 0) {
+              errors.push(`Inline element <${node.tagName.toLowerCase()}> has margin-right which is not supported in PowerPoint. Remove margin from inline elements.`);
+            }
+            if (computed.marginTop && parseFloat(computed.marginTop) > 0) {
+              errors.push(`Inline element <${node.tagName.toLowerCase()}> has margin-top which is not supported in PowerPoint. Remove margin from inline elements.`);
+            }
+            if (computed.marginBottom && parseFloat(computed.marginBottom) > 0) {
+              errors.push(`Inline element <${node.tagName.toLowerCase()}> has margin-bottom which is not supported in PowerPoint. Remove margin from inline elements.`);
+            }
+
+            // Recursively process the child node. This will flatten nested spans into multiple runs.
+            parseInlineFormatting(node, options, runs, textTransform);
+          }
+        }
+
+        prevNodeIsText = isText;
+      });
+
+      // Trim leading space from first run and trailing space from last run
+      if (runs.length > 0) {
+        runs[0].text = runs[0].text.replace(/^\s+/, '');
+        runs[runs.length - 1].text = runs[runs.length - 1].text.replace(/\s+$/, '');
+      }
+
+      return runs.filter(r => r.text.length > 0);
+    };
+
+    // Extract background from body (image or color)
+    const body = document.body;
+    const bodyStyle = window.getComputedStyle(body);
+    const bgImage = bodyStyle.backgroundImage;
+    const bgColor = bodyStyle.backgroundColor;
+
+    // Collect validation errors
+    const errors = [];
+
+    // Validate: Check for CSS gradients
+    if (bgImage && (bgImage.includes('linear-gradient') || bgImage.includes('radial-gradient'))) {
+      errors.push(
+        'CSS gradients are not supported. Use Sharp to rasterize gradients as PNG images first, ' +
+        'then reference with background-image: url(\'gradient.png\')'
+      );
+    }
+
+    let background;
+    if (bgImage && bgImage !== 'none') {
+      // Extract URL from url("...") or url(...)
+      const urlMatch = bgImage.match(/url\(["']?([^"')]+)["']?\)/);
+      if (urlMatch) {
+        background = {
+          type: 'image',
+          path: urlMatch[1]
+        };
+      } else {
+        background = {
+          type: 'color',
+          value: rgbToHex(bgColor)
+        };
+      }
+    } else {
+      background = {
+        type: 'color',
+        value: rgbToHex(bgColor)
+      };
+    }
+
+    // Process all elements
+    const elements = [];
+    const placeholders = [];
+    const textTags = ['P', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'UL', 'OL', 'LI'];
+    const processed = new Set();
+
+    document.querySelectorAll('*').forEach((el) => {
+      if (processed.has(el)) return;
+
+      // Validate text elements don't have backgrounds, borders, or shadows
+      if (textTags.includes(el.tagName)) {
+        const computed = window.getComputedStyle(el);
+        const hasBg = computed.backgroundColor && computed.backgroundColor !== 'rgba(0, 0, 0, 0)';
+        const hasBorder = (computed.borderWidth && parseFloat(computed.borderWidth) > 0) ||
+                          (computed.borderTopWidth && parseFloat(computed.borderTopWidth) > 0) ||
+                          (computed.borderRightWidth && parseFloat(computed.borderRightWidth) > 0) ||
+                          (computed.borderBottomWidth && parseFloat(computed.borderBottomWidth) > 0) ||
+                          (computed.borderLeftWidth && parseFloat(computed.borderLeftWidth) > 0);
+        const hasShadow = computed.boxShadow && computed.boxShadow !== 'none';
+
+        if (hasBg || hasBorder || hasShadow) {
+          errors.push(
+            `Text element <${el.tagName.toLowerCase()}> has ${hasBg ? 'background' : hasBorder ? 'border' : 'shadow'}. ` +
+            'Backgrounds, borders, and shadows are only supported on <div> elements, not text elements.'
+          );
+          return;
+        }
+      }
+
+      // Extract placeholder elements (for charts, etc.)
+      if (el.className && el.className.includes('placeholder')) {
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 || rect.height === 0) {
+          errors.push(
+            `Placeholder "${el.id || 'unnamed'}" has ${rect.width === 0 ? 'width: 0' : 'height: 0'}. Check the layout CSS.`
+          );
+        } else {
+          placeholders.push({
+            id: el.id || `placeholder-${placeholders.length}`,
+            x: pxToInch(rect.left),
+            y: pxToInch(rect.top),
+            w: pxToInch(rect.width),
+            h: pxToInch(rect.height)
+          });
+        }
+        processed.add(el);
+        return;
+      }
+
+      // Extract images
+      if (el.tagName === 'IMG') {
+        const rect = el.getBoundingClientRect();
+        if (rect.width > 0 && rect.height > 0) {
+          elements.push({
+            type: 'image',
+            src: el.src,
+            position: {
+              x: pxToInch(rect.left),
+              y: pxToInch(rect.top),
+              w: pxToInch(rect.width),
+              h: pxToInch(rect.height)
+            }
+          });
+          processed.add(el);
+          return;
+        }
+      }
+
+      // Extract DIVs with backgrounds/borders as shapes
+      const isContainer = el.tagName === 'DIV' && !textTags.includes(el.tagName);
+      if (isContainer) {
+        const computed = window.getComputedStyle(el);
+        const hasBg = computed.backgroundColor && computed.backgroundColor !== 'rgba(0, 0, 0, 0)';
+
+        // Validate: Check for unwrapped text content in DIV
+        for (const node of el.childNodes) {
+          if (node.nodeType === Node.TEXT_NODE) {
+            const text = node.textContent.trim();
+            if (text) {
+              errors.push(
+                `DIV element contains unwrapped text "${text.substring(0, 50)}${text.length > 50 ? '...' : ''}". ` +
+                'All text must be wrapped in <p>, <h1>-<h6>, <ul>, or <ol> tags to appear in PowerPoint.'
+              );
+            }
+          }
+        }
+
+        // Check for background images on shapes
+        const bgImage = computed.backgroundImage;
+        if (bgImage && bgImage !== 'none') {
+          errors.push(
+            'Background images on DIV elements are not supported. ' +
+            'Use solid colors or borders for shapes, or use slide.addImage() in PptxGenJS to layer images.'
+          );
+          return;
+        }
+
+        // Check for borders - both uniform and partial
+        const borderTop = computed.borderTopWidth;
+        const borderRight = computed.borderRightWidth;
+        const borderBottom = computed.borderBottomWidth;
+        const borderLeft = computed.borderLeftWidth;
+        const borders = [borderTop, borderRight, borderBottom, borderLeft].map(b => parseFloat(b) || 0);
+        const hasBorder = borders.some(b => b > 0);
+        const hasUniformBorder = hasBorder && borders.every(b => b === borders[0]);
+        const borderLines = [];
+
+        if (hasBorder && !hasUniformBorder) {
+          const rect = el.getBoundingClientRect();
+          const x = pxToInch(rect.left);
+          const y = pxToInch(rect.top);
+          const w = pxToInch(rect.width);
+          const h = pxToInch(rect.height);
+
+          // Collect lines to add after shape (inset by half the line width to center on edge)
+          if (parseFloat(borderTop) > 0) {
+            const widthPt = pxToPoints(borderTop);
+            const inset = (widthPt / 72) / 2; // Convert points to inches, then half
+            borderLines.push({
+              type: 'line',
+              x1: x, y1: y + inset, x2: x + w, y2: y + inset,
+              width: widthPt,
+              color: rgbToHex(computed.borderTopColor)
+            });
+          }
+          if (parseFloat(borderRight) > 0) {
+            const widthPt = pxToPoints(borderRight);
+            const inset = (widthPt / 72) / 2;
+            borderLines.push({
+              type: 'line',
+              x1: x + w - inset, y1: y, x2: x + w - inset, y2: y + h,
+              width: widthPt,
+              color: rgbToHex(computed.borderRightColor)
+            });
+          }
+          if (parseFloat(borderBottom) > 0) {
+            const widthPt = pxToPoints(borderBottom);
+            const inset = (widthPt / 72) / 2;
+            borderLines.push({
+              type: 'line',
+              x1: x, y1: y + h - inset, x2: x + w, y2: y + h - inset,
+              width: widthPt,
+              color: rgbToHex(computed.borderBottomColor)
+            });
+          }
+          if (parseFloat(borderLeft) > 0) {
+            const widthPt = pxToPoints(borderLeft);
+            const inset = (widthPt / 72) / 2;
+            borderLines.push({
+              type: 'line',
+              x1: x + inset, y1: y, x2: x + inset, y2: y + h,
+              width: widthPt,
+              color: rgbToHex(computed.borderLeftColor)
+            });
+          }
+        }
+
+        if (hasBg || hasBorder) {
+          const rect = el.getBoundingClientRect();
+          if (rect.width > 0 && rect.height > 0) {
+            const shadow = parseBoxShadow(computed.boxShadow);
+
+            // Only add shape if there's background or uniform border
+            if (hasBg || hasUniformBorder) {
+              elements.push({
+                type: 'shape',
+                text: '',  // Shape only - child text elements render on top
+                position: {
+                  x: pxToInch(rect.left),
+                  y: pxToInch(rect.top),
+                  w: pxToInch(rect.width),
+                  h: pxToInch(rect.height)
+                },
+                shape: {
+                  fill: hasBg ? rgbToHex(computed.backgroundColor) : null,
+                  transparency: hasBg ? extractAlpha(computed.backgroundColor) : null,
+                  line: hasUniformBorder ? {
+                    color: rgbToHex(computed.borderColor),
+                    width: pxToPoints(computed.borderWidth)
+                  } : null,
+                  // Convert border-radius to rectRadius (in inches)
+                  // % values: 50%+ = circle (1), <50% = percentage of min dimension
+                  // pt values: divide by 72 (72pt = 1 inch)
+                  // px values: divide by 96 (96px = 1 inch)
+                  rectRadius: (() => {
+                    const radius = computed.borderRadius;
+                    const radiusValue = parseFloat(radius);
+                    if (radiusValue === 0) return 0;
+
+                    if (radius.includes('%')) {
+                      if (radiusValue >= 50) return 1;
+                      // Calculate percentage of smaller dimension
+                      const minDim = Math.min(rect.width, rect.height);
+                      return (radiusValue / 100) * pxToInch(minDim);
+                    }
+
+                    if (radius.includes('pt')) return radiusValue / 72;
+                    return radiusValue / PX_PER_IN;
+                  })(),
+                  shadow: shadow
+                }
+              });
+            }
+
+            // Add partial border lines
+            elements.push(...borderLines);
+
+            processed.add(el);
+            return;
+          }
+        }
+      }
+
+      // Extract bullet lists as single text block
+      if (el.tagName === 'UL' || el.tagName === 'OL') {
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 || rect.height === 0) return;
+
+        const liElements = Array.from(el.querySelectorAll('li'));
+        const items = [];
+        const ulComputed = window.getComputedStyle(el);
+        const ulPaddingLeftPt = pxToPoints(ulComputed.paddingLeft);
+
+        // Split: margin-left for bullet position, indent for text position
+        // margin-left + indent = ul padding-left
+        const marginLeft = ulPaddingLeftPt * 0.5;
+        const textIndent = ulPaddingLeftPt * 0.5;
+
+        liElements.forEach((li, idx) => {
+          const isLast = idx === liElements.length - 1;
+          const runs = parseInlineFormatting(li, { breakLine: false });
+          // Clean manual bullets from first run
+          if (runs.length > 0) {
+            runs[0].text = runs[0].text.replace(/^[•\-\*▪▸]\s*/, '');
+            runs[0].options.bullet = { indent: textIndent };
+          }
+          // Set breakLine on last run
+          if (runs.length > 0 && !isLast) {
+            runs[runs.length - 1].options.breakLine = true;
+          }
+          items.push(...runs);
+        });
+
+        const computed = window.getComputedStyle(liElements[0] || el);
+
+        elements.push({
+          type: 'list',
+          items: items,
+          position: {
+            x: pxToInch(rect.left),
+            y: pxToInch(rect.top),
+            w: pxToInch(rect.width),
+            h: pxToInch(rect.height)
+          },
+          style: {
+            fontSize: pxToPoints(computed.fontSize),
+            fontFace: computed.fontFamily.split(',')[0].replace(/['"]/g, '').trim(),
+            color: rgbToHex(computed.color),
+            transparency: extractAlpha(computed.color),
+            align: computed.textAlign === 'start' ? 'left' : computed.textAlign,
+            lineSpacing: computed.lineHeight && computed.lineHeight !== 'normal' ? pxToPoints(computed.lineHeight) : null,
+            paraSpaceBefore: 0,
+            paraSpaceAfter: pxToPoints(computed.marginBottom),
+            // PptxGenJS margin array is [left, right, bottom, top]
+            margin: [marginLeft, 0, 0, 0]
+          }
+        });
+
+        liElements.forEach(li => processed.add(li));
+        processed.add(el);
+        return;
+      }
+
+      // Extract text elements (P, H1, H2, etc.)
+      if (!textTags.includes(el.tagName)) return;
+
+      const rect = el.getBoundingClientRect();
+      const text = el.textContent.trim();
+      if (rect.width === 0 || rect.height === 0 || !text) return;
+
+      // Validate: Check for manual bullet symbols in text elements (not in lists)
+      if (el.tagName !== 'LI' && /^[•\-\*▪▸○●◆◇■□]\s/.test(text.trimStart())) {
+        errors.push(
+          `Text element <${el.tagName.toLowerCase()}> starts with bullet symbol "${text.substring(0, 20)}...". ` +
+          'Use <ul> or <ol> lists instead of manual bullet symbols.'
+        );
+        return;
+      }
+
+      const computed = window.getComputedStyle(el);
+      const rotation = getRotation(computed.transform, computed.writingMode);
+      const { x, y, w, h } = getPositionAndSize(el, rect, rotation);
+
+      const baseStyle = {
+        fontSize: pxToPoints(computed.fontSize),
+        fontFace: computed.fontFamily.split(',')[0].replace(/['"]/g, '').trim(),
+        color: rgbToHex(computed.color),
+        align: computed.textAlign === 'start' ? 'left' : computed.textAlign,
+        lineSpacing: pxToPoints(computed.lineHeight),
+        paraSpaceBefore: pxToPoints(computed.marginTop),
+        paraSpaceAfter: pxToPoints(computed.marginBottom),
+        // PptxGenJS margin array is [left, right, bottom, top] (not [top, right, bottom, left] as documented)
+        margin: [
+          pxToPoints(computed.paddingLeft),
+          pxToPoints(computed.paddingRight),
+          pxToPoints(computed.paddingBottom),
+          pxToPoints(computed.paddingTop)
+        ]
+      };
+
+      const transparency = extractAlpha(computed.color);
+      if (transparency !== null) baseStyle.transparency = transparency;
+
+      if (rotation !== null) baseStyle.rotate = rotation;
+
+      const hasFormatting = el.querySelector('b, i, u, strong, em, span, br');
+
+      if (hasFormatting) {
+        // Text with inline formatting
+        const transformStr = computed.textTransform;
+        const runs = parseInlineFormatting(el, {}, [], (str) => applyTextTransform(str, transformStr));
+
+        // Adjust lineSpacing based on largest fontSize in runs
+        const adjustedStyle = { ...baseStyle };
+        if (adjustedStyle.lineSpacing) {
+          const maxFontSize = Math.max(
+            adjustedStyle.fontSize,
+            ...runs.map(r => r.options?.fontSize || 0)
+          );
+          if (maxFontSize > adjustedStyle.fontSize) {
+            const lineHeightMultiplier = adjustedStyle.lineSpacing / adjustedStyle.fontSize;
+            adjustedStyle.lineSpacing = maxFontSize * lineHeightMultiplier;
+          }
+        }
+
+        elements.push({
+          type: el.tagName.toLowerCase(),
+          text: runs,
+          position: { x: pxToInch(x), y: pxToInch(y), w: pxToInch(w), h: pxToInch(h) },
+          style: adjustedStyle
+        });
+      } else {
+        // Plain text - inherit CSS formatting
+        const textTransform = computed.textTransform;
+        const transformedText = applyTextTransform(text, textTransform);
+
+        const isBold = computed.fontWeight === 'bold' || parseInt(computed.fontWeight) >= 600;
+
+        elements.push({
+          type: el.tagName.toLowerCase(),
+          text: transformedText,
+          position: { x: pxToInch(x), y: pxToInch(y), w: pxToInch(w), h: pxToInch(h) },
+          style: {
+            ...baseStyle,
+            bold: isBold && !shouldSkipBold(computed.fontFamily),
+            italic: computed.fontStyle === 'italic',
+            underline: computed.textDecoration.includes('underline')
+          }
+        });
+      }
+
+      processed.add(el);
+    });
+
+    return { background, elements, placeholders, errors };
+  });
+}
+
+async function html2pptx(htmlFile, pres, options = {}) {
+  const {
+    tmpDir = process.env.TMPDIR || '/tmp',
+    slide = null
+  } = options;
+
+  try {
+    // Use Chrome on macOS, default Chromium on Unix
+    const launchOptions = { env: { TMPDIR: tmpDir } };
+    if (process.platform === 'darwin') {
+      launchOptions.channel = 'chrome';
+    }
+
+    const browser = await chromium.launch(launchOptions);
+
+    let bodyDimensions;
+    let slideData;
+
+    const filePath = path.isAbsolute(htmlFile) ? htmlFile : path.join(process.cwd(), htmlFile);
+    const validationErrors = [];
+
+    try {
+      const page = await browser.newPage();
+      page.on('console', (msg) => {
+        // Log the message text to your test runner's console
+        console.log(`Browser console: ${msg.text()}`);
+      });
+
+      await page.goto(`file://${filePath}`);
+
+      bodyDimensions = await getBodyDimensions(page);
+
+      await page.setViewportSize({
+        width: Math.round(bodyDimensions.width),
+        height: Math.round(bodyDimensions.height)
+      });
+
+      slideData = await extractSlideData(page);
+    } finally {
+      await browser.close();
+    }
+
+    // Collect all validation errors
+    if (bodyDimensions.errors && bodyDimensions.errors.length > 0) {
+      validationErrors.push(...bodyDimensions.errors);
+    }
+
+    const dimensionErrors = validateDimensions(bodyDimensions, pres);
+    if (dimensionErrors.length > 0) {
+      validationErrors.push(...dimensionErrors);
+    }
+
+    const textBoxPositionErrors = validateTextBoxPosition(slideData, bodyDimensions);
+    if (textBoxPositionErrors.length > 0) {
+      validationErrors.push(...textBoxPositionErrors);
+    }
+
+    if (slideData.errors && slideData.errors.length > 0) {
+      validationErrors.push(...slideData.errors);
+    }
+
+    // Throw all errors at once if any exist
+    if (validationErrors.length > 0) {
+      const errorMessage = validationErrors.length === 1
+        ? validationErrors[0]
+        : `Multiple validation errors found:\n${validationErrors.map((e, i) => `  ${i + 1}. ${e}`).join('\n')}`;
+      throw new Error(errorMessage);
+    }
+
+    const targetSlide = slide || pres.addSlide();
+
+    await addBackground(slideData, targetSlide, tmpDir);
+    addElements(slideData, targetSlide, pres);
+
+    return { slide: targetSlide, placeholders: slideData.placeholders };
+  } catch (error) {
+    if (!error.message.startsWith(htmlFile)) {
+      throw new Error(`${htmlFile}: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+module.exports = html2pptx;

.claude/skills/pptx-skill/scripts/package-lock.json

@@ -0,0 +1,761 @@
+{
+  "name": "scripts",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "dependencies": {
+        "playwright": "^1.58.2",
+        "pptxgenjs": "^4.0.1",
+        "sharp": "^0.34.5"
+      }
+    },
+    "node_modules/@emnapi/runtime": {
+      "version": "1.8.1",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.8.1.tgz",
+      "integrity": "sha512-mehfKSMWjjNol8659Z8KxEMrdSJDDot5SXMq00dM8BN4o+CLNXQ0xH2V7EchNHV4RmbZLmmPdEaXZc5H2FXmDg==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@img/colour": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.0.0.tgz",
+      "integrity": "sha512-A5P/LfWGFSl6nsckYtjw9da+19jB8hkJ6ACTGcDfEJ0aE+l2n2El7dsVM7UVHZQ9s2lmYMWlrS21YLy2IR1LUw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@img/sharp-darwin-arm64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.34.5.tgz",
+      "integrity": "sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-darwin-arm64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-darwin-x64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.34.5.tgz",
+      "integrity": "sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-darwin-x64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-libvips-darwin-arm64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.2.4.tgz",
+      "integrity": "sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-darwin-x64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.2.4.tgz",
+      "integrity": "sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-arm": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.2.4.tgz",
+      "integrity": "sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-arm64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.2.4.tgz",
+      "integrity": "sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-ppc64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.2.4.tgz",
+      "integrity": "sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-riscv64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.2.4.tgz",
+      "integrity": "sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-s390x": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.2.4.tgz",
+      "integrity": "sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==",
+      "cpu": [
+        "s390x"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-x64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.2.4.tgz",
+      "integrity": "sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linuxmusl-arm64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.2.4.tgz",
+      "integrity": "sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linuxmusl-x64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.2.4.tgz",
+      "integrity": "sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-linux-arm": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.34.5.tgz",
+      "integrity": "sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-arm": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-arm64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.34.5.tgz",
+      "integrity": "sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-arm64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-ppc64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.34.5.tgz",
+      "integrity": "sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-ppc64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-riscv64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.34.5.tgz",
+      "integrity": "sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==",
+      "cpu": [
+        "riscv64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-riscv64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-s390x": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.34.5.tgz",
+      "integrity": "sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==",
+      "cpu": [
+        "s390x"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-s390x": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-x64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.34.5.tgz",
+      "integrity": "sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-x64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linuxmusl-arm64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.34.5.tgz",
+      "integrity": "sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linuxmusl-arm64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linuxmusl-x64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.34.5.tgz",
+      "integrity": "sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linuxmusl-x64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-wasm32": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.34.5.tgz",
+      "integrity": "sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==",
+      "cpu": [
+        "wasm32"
+      ],
+      "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/runtime": "^1.7.0"
+      },
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-arm64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.34.5.tgz",
+      "integrity": "sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-ia32": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.34.5.tgz",
+      "integrity": "sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==",
+      "cpu": [
+        "ia32"
+      ],
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-x64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.34.5.tgz",
+      "integrity": "sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "22.19.3",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.3.tgz",
+      "integrity": "sha512-1N9SBnWYOJTrNZCdh/yJE+t910Y128BoyY+zBLWhL3r0TYzlTmFdXrPwHL9DyFZmlEXNQQolTZh3KHV31QDhyA==",
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "node_modules/core-util-is": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz",
+      "integrity": "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==",
+      "license": "MIT"
+    },
+    "node_modules/detect-libc": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/https": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/https/-/https-1.0.0.tgz",
+      "integrity": "sha512-4EC57ddXrkaF0x83Oj8sM6SLQHAWXw90Skqu2M4AEWENZ3F02dFJE/GARA8igO79tcgYqGrD7ae4f5L3um2lgg==",
+      "license": "ISC"
+    },
+    "node_modules/image-size": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/image-size/-/image-size-1.2.1.tgz",
+      "integrity": "sha512-rH+46sQJ2dlwfjfhCyNx5thzrv+dtmBIhPHk0zgRUukHzZ/kRueTJXoYYsclBaKcSMBWuGbOFXtioLpzTb5euw==",
+      "license": "MIT",
+      "dependencies": {
+        "queue": "6.0.2"
+      },
+      "bin": {
+        "image-size": "bin/image-size.js"
+      },
+      "engines": {
+        "node": ">=16.x"
+      }
+    },
+    "node_modules/immediate": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/immediate/-/immediate-3.0.6.tgz",
+      "integrity": "sha512-XXOFtyqDjNDAQxVfYxuF7g9Il/IbWmmlQg2MYKOH8ExIT1qg6xc4zyS3HaEEATgs1btfzxq15ciUiY7gjSXRGQ==",
+      "license": "MIT"
+    },
+    "node_modules/inherits": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
+      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
+      "license": "ISC"
+    },
+    "node_modules/isarray": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz",
+      "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ==",
+      "license": "MIT"
+    },
+    "node_modules/jszip": {
+      "version": "3.10.1",
+      "resolved": "https://registry.npmjs.org/jszip/-/jszip-3.10.1.tgz",
+      "integrity": "sha512-xXDvecyTpGLrqFrvkrUSoxxfJI5AH7U8zxxtVclpsUtMCq4JQ290LY8AW5c7Ggnr/Y/oK+bQMbqK2qmtk3pN4g==",
+      "license": "(MIT OR GPL-3.0-or-later)",
+      "dependencies": {
+        "lie": "~3.3.0",
+        "pako": "~1.0.2",
+        "readable-stream": "~2.3.6",
+        "setimmediate": "^1.0.5"
+      }
+    },
+    "node_modules/lie": {
+      "version": "3.3.0",
+      "resolved": "https://registry.npmjs.org/lie/-/lie-3.3.0.tgz",
+      "integrity": "sha512-UaiMJzeWRlEujzAuw5LokY1L5ecNQYZKfmyZ9L7wDHb/p5etKaxXhohBcrw0EYby+G/NA52vRSN4N39dxHAIwQ==",
+      "license": "MIT",
+      "dependencies": {
+        "immediate": "~3.0.5"
+      }
+    },
+    "node_modules/pako": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/pako/-/pako-1.0.11.tgz",
+      "integrity": "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==",
+      "license": "(MIT AND Zlib)"
+    },
+    "node_modules/playwright": {
+      "version": "1.58.2",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.58.2.tgz",
+      "integrity": "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.58.2"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.58.2",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.58.2.tgz",
+      "integrity": "sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg==",
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/pptxgenjs": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/pptxgenjs/-/pptxgenjs-4.0.1.tgz",
+      "integrity": "sha512-TeJISr8wouAuXw4C1F/mC33xbZs/FuEG6nH9FG1Zj+nuPcGMP5YRHl6X+j3HSUnS1f3at6k75ZZXPMZlA5Lj9A==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "^22.8.1",
+        "https": "^1.0.0",
+        "image-size": "^1.2.1",
+        "jszip": "^3.10.1"
+      }
+    },
+    "node_modules/process-nextick-args": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz",
+      "integrity": "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==",
+      "license": "MIT"
+    },
+    "node_modules/queue": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/queue/-/queue-6.0.2.tgz",
+      "integrity": "sha512-iHZWu+q3IdFZFX36ro/lKBkSvfkztY5Y7HMiPlOUjhupPcG2JMfst2KKEpu5XndviX/3UhFbRngUPNKtgvtZiA==",
+      "license": "MIT",
+      "dependencies": {
+        "inherits": "~2.0.3"
+      }
+    },
+    "node_modules/readable-stream": {
+      "version": "2.3.8",
+      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz",
+      "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==",
+      "license": "MIT",
+      "dependencies": {
+        "core-util-is": "~1.0.0",
+        "inherits": "~2.0.3",
+        "isarray": "~1.0.0",
+        "process-nextick-args": "~2.0.0",
+        "safe-buffer": "~5.1.1",
+        "string_decoder": "~1.1.1",
+        "util-deprecate": "~1.0.1"
+      }
+    },
+    "node_modules/safe-buffer": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
+      "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==",
+      "license": "MIT"
+    },
+    "node_modules/semver": {
+      "version": "7.7.3",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz",
+      "integrity": "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==",
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/setimmediate": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/setimmediate/-/setimmediate-1.0.5.tgz",
+      "integrity": "sha512-MATJdZp8sLqDl/68LfQmbP8zKPLQNV6BIZoIgrscFDQ+RsvK/BxeDQOgyxKKoh0y/8h3BqVFnCqQ/gd+reiIXA==",
+      "license": "MIT"
+    },
+    "node_modules/sharp": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.34.5.tgz",
+      "integrity": "sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==",
+      "hasInstallScript": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@img/colour": "^1.0.0",
+        "detect-libc": "^2.1.2",
+        "semver": "^7.7.3"
+      },
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-darwin-arm64": "0.34.5",
+        "@img/sharp-darwin-x64": "0.34.5",
+        "@img/sharp-libvips-darwin-arm64": "1.2.4",
+        "@img/sharp-libvips-darwin-x64": "1.2.4",
+        "@img/sharp-libvips-linux-arm": "1.2.4",
+        "@img/sharp-libvips-linux-arm64": "1.2.4",
+        "@img/sharp-libvips-linux-ppc64": "1.2.4",
+        "@img/sharp-libvips-linux-riscv64": "1.2.4",
+        "@img/sharp-libvips-linux-s390x": "1.2.4",
+        "@img/sharp-libvips-linux-x64": "1.2.4",
+        "@img/sharp-libvips-linuxmusl-arm64": "1.2.4",
+        "@img/sharp-libvips-linuxmusl-x64": "1.2.4",
+        "@img/sharp-linux-arm": "0.34.5",
+        "@img/sharp-linux-arm64": "0.34.5",
+        "@img/sharp-linux-ppc64": "0.34.5",
+        "@img/sharp-linux-riscv64": "0.34.5",
+        "@img/sharp-linux-s390x": "0.34.5",
+        "@img/sharp-linux-x64": "0.34.5",
+        "@img/sharp-linuxmusl-arm64": "0.34.5",
+        "@img/sharp-linuxmusl-x64": "0.34.5",
+        "@img/sharp-wasm32": "0.34.5",
+        "@img/sharp-win32-arm64": "0.34.5",
+        "@img/sharp-win32-ia32": "0.34.5",
+        "@img/sharp-win32-x64": "0.34.5"
+      }
+    },
+    "node_modules/string_decoder": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
+      "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
+      "license": "MIT",
+      "dependencies": {
+        "safe-buffer": "~5.1.0"
+      }
+    },
+    "node_modules/tslib": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+      "license": "0BSD",
+      "optional": true
+    },
+    "node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "license": "MIT"
+    },
+    "node_modules/util-deprecate": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
+      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
+      "license": "MIT"
+    }
+  }
+}

.claude/skills/pptx-skill/scripts/package.json

@@ -0,0 +1,7 @@
+{
+  "dependencies": {
+    "playwright": "^1.58.2",
+    "pptxgenjs": "^4.0.1",
+    "sharp": "^0.34.5"
+  }
+}

.claude/skills/pptx-skill/scripts/thumbnail.py

@@ -0,0 +1,450 @@
+#!/usr/bin/env python3
+"""
+Create thumbnail grids from PowerPoint presentation slides.
+
+Creates a grid layout of slide thumbnails with configurable columns (max 6).
+Each grid contains up to cols×(cols+1) images. For presentations with more
+slides, multiple numbered grid files are created automatically.
+
+The program outputs the names of all files created.
+
+Output:
+- Single grid: {prefix}.jpg (if slides fit in one grid)
+- Multiple grids: {prefix}-1.jpg, {prefix}-2.jpg, etc.
+
+Grid limits by column count:
+- 3 cols: max 12 slides per grid (3×4)
+- 4 cols: max 20 slides per grid (4×5)
+- 5 cols: max 30 slides per grid (5×6) [default]
+- 6 cols: max 42 slides per grid (6×7)
+
+Usage:
+    python thumbnail.py input.pptx [output_prefix] [--cols N] [--outline-placeholders]
+
+Examples:
+    python thumbnail.py presentation.pptx
+    # Creates: thumbnails.jpg (using default prefix)
+    # Outputs:
+    #   Created 1 grid(s):
+    #     - thumbnails.jpg
+
+    python thumbnail.py large-deck.pptx grid --cols 4
+    # Creates: grid-1.jpg, grid-2.jpg, grid-3.jpg
+    # Outputs:
+    #   Created 3 grid(s):
+    #     - grid-1.jpg
+    #     - grid-2.jpg
+    #     - grid-3.jpg
+
+    python thumbnail.py template.pptx analysis --outline-placeholders
+    # Creates thumbnail grids with red outlines around text placeholders
+"""
+
+import argparse
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from inventory import extract_text_inventory
+from PIL import Image, ImageDraw, ImageFont
+from pptx import Presentation
+
+# Constants
+THUMBNAIL_WIDTH = 300  # Fixed thumbnail width in pixels
+CONVERSION_DPI = 100  # DPI for PDF to image conversion
+MAX_COLS = 6  # Maximum number of columns
+DEFAULT_COLS = 5  # Default number of columns
+JPEG_QUALITY = 95  # JPEG compression quality
+
+# Grid layout constants
+GRID_PADDING = 20  # Padding between thumbnails
+BORDER_WIDTH = 2  # Border width around thumbnails
+FONT_SIZE_RATIO = 0.12  # Font size as fraction of thumbnail width
+LABEL_PADDING_RATIO = 0.4  # Label padding as fraction of font size
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Create thumbnail grids from PowerPoint slides."
+    )
+    parser.add_argument("input", help="Input PowerPoint file (.pptx)")
+    parser.add_argument(
+        "output_prefix",
+        nargs="?",
+        default="thumbnails",
+        help="Output prefix for image files (default: thumbnails, will create prefix.jpg or prefix-N.jpg)",
+    )
+    parser.add_argument(
+        "--cols",
+        type=int,
+        default=DEFAULT_COLS,
+        help=f"Number of columns (default: {DEFAULT_COLS}, max: {MAX_COLS})",
+    )
+    parser.add_argument(
+        "--outline-placeholders",
+        action="store_true",
+        help="Outline text placeholders with a colored border",
+    )
+
+    args = parser.parse_args()
+
+    # Validate columns
+    cols = min(args.cols, MAX_COLS)
+    if args.cols > MAX_COLS:
+        print(f"Warning: Columns limited to {MAX_COLS} (requested {args.cols})")
+
+    # Validate input
+    input_path = Path(args.input)
+    if not input_path.exists() or input_path.suffix.lower() != ".pptx":
+        print(f"Error: Invalid PowerPoint file: {args.input}")
+        sys.exit(1)
+
+    # Construct output path (always JPG)
+    output_path = Path(f"{args.output_prefix}.jpg")
+
+    print(f"Processing: {args.input}")
+
+    try:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            # Get placeholder regions if outlining is enabled
+            placeholder_regions = None
+            slide_dimensions = None
+            if args.outline_placeholders:
+                print("Extracting placeholder regions...")
+                placeholder_regions, slide_dimensions = get_placeholder_regions(
+                    input_path
+                )
+                if placeholder_regions:
+                    print(f"Found placeholders on {len(placeholder_regions)} slides")
+
+            # Convert slides to images
+            slide_images = convert_to_images(input_path, Path(temp_dir), CONVERSION_DPI)
+            if not slide_images:
+                print("Error: No slides found")
+                sys.exit(1)
+
+            print(f"Found {len(slide_images)} slides")
+
+            # Create grids (max cols×(cols+1) images per grid)
+            grid_files = create_grids(
+                slide_images,
+                cols,
+                THUMBNAIL_WIDTH,
+                output_path,
+                placeholder_regions,
+                slide_dimensions,
+            )
+
+            # Print saved files
+            print(f"Created {len(grid_files)} grid(s):")
+            for grid_file in grid_files:
+                print(f"  - {grid_file}")
+
+    except Exception as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+
+def create_hidden_slide_placeholder(size):
+    """Create placeholder image for hidden slides."""
+    img = Image.new("RGB", size, color="#F0F0F0")
+    draw = ImageDraw.Draw(img)
+    line_width = max(5, min(size) // 100)
+    draw.line([(0, 0), size], fill="#CCCCCC", width=line_width)
+    draw.line([(size[0], 0), (0, size[1])], fill="#CCCCCC", width=line_width)
+    return img
+
+
+def get_placeholder_regions(pptx_path):
+    """Extract ALL text regions from the presentation.
+
+    Returns a tuple of (placeholder_regions, slide_dimensions).
+    text_regions is a dict mapping slide indices to lists of text regions.
+    Each region is a dict with 'left', 'top', 'width', 'height' in inches.
+    slide_dimensions is a tuple of (width_inches, height_inches).
+    """
+    prs = Presentation(str(pptx_path))
+    inventory = extract_text_inventory(pptx_path, prs)
+    placeholder_regions = {}
+
+    # Get actual slide dimensions in inches (EMU to inches conversion)
+    slide_width_inches = (prs.slide_width or 9144000) / 914400.0
+    slide_height_inches = (prs.slide_height or 5143500) / 914400.0
+
+    for slide_key, shapes in inventory.items():
+        # Extract slide index from "slide-N" format
+        slide_idx = int(slide_key.split("-")[1])
+        regions = []
+
+        for shape_key, shape_data in shapes.items():
+            # The inventory only contains shapes with text, so all shapes should be highlighted
+            regions.append(
+                {
+                    "left": shape_data.left,
+                    "top": shape_data.top,
+                    "width": shape_data.width,
+                    "height": shape_data.height,
+                }
+            )
+
+        if regions:
+            placeholder_regions[slide_idx] = regions
+
+    return placeholder_regions, (slide_width_inches, slide_height_inches)
+
+
+def convert_to_images(pptx_path, temp_dir, dpi):
+    """Convert PowerPoint to images via PDF, handling hidden slides."""
+    # Detect hidden slides
+    print("Analyzing presentation...")
+    prs = Presentation(str(pptx_path))
+    total_slides = len(prs.slides)
+
+    # Find hidden slides (1-based indexing for display)
+    hidden_slides = {
+        idx + 1
+        for idx, slide in enumerate(prs.slides)
+        if slide.element.get("show") == "0"
+    }
+
+    print(f"Total slides: {total_slides}")
+    if hidden_slides:
+        print(f"Hidden slides: {sorted(hidden_slides)}")
+
+    pdf_path = temp_dir / f"{pptx_path.stem}.pdf"
+
+    # Convert to PDF
+    print("Converting to PDF...")
+    result = subprocess.run(
+        [
+            "soffice",
+            "--headless",
+            "--convert-to",
+            "pdf",
+            "--outdir",
+            str(temp_dir),
+            str(pptx_path),
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0 or not pdf_path.exists():
+        raise RuntimeError("PDF conversion failed")
+
+    # Convert PDF to images
+    print(f"Converting to images at {dpi} DPI...")
+    result = subprocess.run(
+        ["pdftoppm", "-jpeg", "-r", str(dpi), str(pdf_path), str(temp_dir / "slide")],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError("Image conversion failed")
+
+    visible_images = sorted(temp_dir.glob("slide-*.jpg"))
+
+    # Create full list with placeholders for hidden slides
+    all_images = []
+    visible_idx = 0
+
+    # Get placeholder dimensions from first visible slide
+    if visible_images:
+        with Image.open(visible_images[0]) as img:
+            placeholder_size = img.size
+    else:
+        placeholder_size = (1920, 1080)
+
+    for slide_num in range(1, total_slides + 1):
+        if slide_num in hidden_slides:
+            # Create placeholder image for hidden slide
+            placeholder_path = temp_dir / f"hidden-{slide_num:03d}.jpg"
+            placeholder_img = create_hidden_slide_placeholder(placeholder_size)
+            placeholder_img.save(placeholder_path, "JPEG")
+            all_images.append(placeholder_path)
+        else:
+            # Use the actual visible slide image
+            if visible_idx < len(visible_images):
+                all_images.append(visible_images[visible_idx])
+                visible_idx += 1
+
+    return all_images
+
+
+def create_grids(
+    image_paths,
+    cols,
+    width,
+    output_path,
+    placeholder_regions=None,
+    slide_dimensions=None,
+):
+    """Create multiple thumbnail grids from slide images, max cols×(cols+1) images per grid."""
+    # Maximum images per grid is cols × (cols + 1) for better proportions
+    max_images_per_grid = cols * (cols + 1)
+    grid_files = []
+
+    print(
+        f"Creating grids with {cols} columns (max {max_images_per_grid} images per grid)"
+    )
+
+    # Split images into chunks
+    for chunk_idx, start_idx in enumerate(
+        range(0, len(image_paths), max_images_per_grid)
+    ):
+        end_idx = min(start_idx + max_images_per_grid, len(image_paths))
+        chunk_images = image_paths[start_idx:end_idx]
+
+        # Create grid for this chunk
+        grid = create_grid(
+            chunk_images, cols, width, start_idx, placeholder_regions, slide_dimensions
+        )
+
+        # Generate output filename
+        if len(image_paths) <= max_images_per_grid:
+            # Single grid - use base filename without suffix
+            grid_filename = output_path
+        else:
+            # Multiple grids - insert index before extension with dash
+            stem = output_path.stem
+            suffix = output_path.suffix
+            grid_filename = output_path.parent / f"{stem}-{chunk_idx + 1}{suffix}"
+
+        # Save grid
+        grid_filename.parent.mkdir(parents=True, exist_ok=True)
+        grid.save(str(grid_filename), quality=JPEG_QUALITY)
+        grid_files.append(str(grid_filename))
+
+    return grid_files
+
+
+def create_grid(
+    image_paths,
+    cols,
+    width,
+    start_slide_num=0,
+    placeholder_regions=None,
+    slide_dimensions=None,
+):
+    """Create thumbnail grid from slide images with optional placeholder outlining."""
+    font_size = int(width * FONT_SIZE_RATIO)
+    label_padding = int(font_size * LABEL_PADDING_RATIO)
+
+    # Get dimensions
+    with Image.open(image_paths[0]) as img:
+        aspect = img.height / img.width
+    height = int(width * aspect)
+
+    # Calculate grid size
+    rows = (len(image_paths) + cols - 1) // cols
+    grid_w = cols * width + (cols + 1) * GRID_PADDING
+    grid_h = rows * (height + font_size + label_padding * 2) + (rows + 1) * GRID_PADDING
+
+    # Create grid
+    grid = Image.new("RGB", (grid_w, grid_h), "white")
+    draw = ImageDraw.Draw(grid)
+
+    # Load font with size based on thumbnail width
+    try:
+        # Use Pillow's default font with size
+        font = ImageFont.load_default(size=font_size)
+    except Exception:
+        # Fall back to basic default font if size parameter not supported
+        font = ImageFont.load_default()
+
+    # Place thumbnails
+    for i, img_path in enumerate(image_paths):
+        row, col = i // cols, i % cols
+        x = col * width + (col + 1) * GRID_PADDING
+        y_base = (
+            row * (height + font_size + label_padding * 2) + (row + 1) * GRID_PADDING
+        )
+
+        # Add label with actual slide number
+        label = f"{start_slide_num + i}"
+        bbox = draw.textbbox((0, 0), label, font=font)
+        text_w = bbox[2] - bbox[0]
+        draw.text(
+            (x + (width - text_w) // 2, y_base + label_padding),
+            label,
+            fill="black",
+            font=font,
+        )
+
+        # Add thumbnail below label with proportional spacing
+        y_thumbnail = y_base + label_padding + font_size + label_padding
+
+        with Image.open(img_path) as img:
+            # Get original dimensions before thumbnail
+            orig_w, orig_h = img.size
+
+            # Apply placeholder outlines if enabled
+            if placeholder_regions and (start_slide_num + i) in placeholder_regions:
+                # Convert to RGBA for transparency support
+                if img.mode != "RGBA":
+                    img = img.convert("RGBA")
+
+                # Get the regions for this slide
+                regions = placeholder_regions[start_slide_num + i]
+
+                # Calculate scale factors using actual slide dimensions
+                if slide_dimensions:
+                    slide_width_inches, slide_height_inches = slide_dimensions
+                else:
+                    # Fallback: estimate from image size at CONVERSION_DPI
+                    slide_width_inches = orig_w / CONVERSION_DPI
+                    slide_height_inches = orig_h / CONVERSION_DPI
+
+                x_scale = orig_w / slide_width_inches
+                y_scale = orig_h / slide_height_inches
+
+                # Create a highlight overlay
+                overlay = Image.new("RGBA", img.size, (255, 255, 255, 0))
+                overlay_draw = ImageDraw.Draw(overlay)
+
+                # Highlight each placeholder region
+                for region in regions:
+                    # Convert from inches to pixels in the original image
+                    px_left = int(region["left"] * x_scale)
+                    px_top = int(region["top"] * y_scale)
+                    px_width = int(region["width"] * x_scale)
+                    px_height = int(region["height"] * y_scale)
+
+                    # Draw highlight outline with red color and thick stroke
+                    # Using a bright red outline instead of fill
+                    stroke_width = max(
+                        5, min(orig_w, orig_h) // 150
+                    )  # Thicker proportional stroke width
+                    overlay_draw.rectangle(
+                        [(px_left, px_top), (px_left + px_width, px_top + px_height)],
+                        outline=(255, 0, 0, 255),  # Bright red, fully opaque
+                        width=stroke_width,
+                    )
+
+                # Composite the overlay onto the image using alpha blending
+                img = Image.alpha_composite(img, overlay)
+                # Convert back to RGB for JPEG saving
+                img = img.convert("RGB")
+
+            img.thumbnail((width, height), Image.Resampling.LANCZOS)
+            w, h = img.size
+            tx = x + (width - w) // 2
+            ty = y_thumbnail + (height - h) // 2
+            grid.paste(img, (tx, ty))
+
+            # Add border
+            if BORDER_WIDTH > 0:
+                draw.rectangle(
+                    [
+                        (tx - BORDER_WIDTH, ty - BORDER_WIDTH),
+                        (tx + w + BORDER_WIDTH - 1, ty + h + BORDER_WIDTH - 1),
+                    ],
+                    outline="gray",
+                    width=BORDER_WIDTH,
+                )
+
+    return grid
+
+
+if __name__ == "__main__":
+    main()

.claude/skills/proposal-skill/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: proposal-skill
+description: PDF 기획서 분석 및 PPT 기획서 생성을 위한 고급 스킬. 템플릿 추출, 구조 매핑, 자동 콘텐츠 생성 기능 제공.
+---
+
+# Proposal Skill - 기획서 생성 스킬
+
+PDF 샘플을 분석하여 동일한 형태의 PPT 기획서를 자동 생성하는 전문 스킬입니다.
+
+## 기능 개요
+
+### 1. PDF 구조 분석 (PDF Structure Analysis)
+PDF 기획서의 레이아웃과 콘텐츠 패턴을 자동으로 분석
+
+### 2. 템플릿 추출 (Template Extraction)
+분석 결과를 바탕으로 재사용 가능한 템플릿 생성
+
+### 3. 콘텐츠 매핑 (Content Mapping)
+사용자 요구사항을 기획서 구조에 자동 매핑
+
+### 4. PPT 자동 생성 (Auto PPT Generation)
+완성된 기획서를 PowerPoint 파일로 출력
+
+## 핵심 워크플로우
+
+### PDF → 템플릿 추출 워크플로우
+
+```mermaid
+graph TD
+    A[PDF 샘플] --> B[페이지별 구조 분석]
+    B --> C[섹션 패턴 인식]
+    C --> D[레이아웃 템플릿 추출]
+    D --> E[재사용 템플릿 저장]
+```
+
+### 기획서 생성 워크플로우
+
+```mermaid
+graph TD
+    A[사용자 요구사항] --> B[템플릿 매칭]
+    B --> C[콘텐츠 자동 매핑]
+    C --> D[구조화된 문서 생성]
+    D --> E[PPT 슬라이드 변환]
+    E --> F[완성된 기획서]
+```
+
+## 스크립트 구조
+
+### 1. pdf-analyzer.js
+PDF 파일 구조 분석 및 템플릿 추출
+
+```javascript
+import { PDFAnalyzer } from './pdf-analyzer.js';
+
+// PDF 구조 분석
+const analyzer = new PDFAnalyzer();
+const structure = await analyzer.analyze('pdf_sample/SAM_ERP_Storyboard.pdf');
+
+// 템플릿 추출
+const template = await analyzer.extractTemplate(structure);
+await analyzer.saveTemplate(template, 'templates/erp_storyboard.json');
+```
+
+### 2. proposal-generator.js
+기획서 자동 생성 엔진
+
+```javascript
+import { ProposalGenerator } from './proposal-generator.js';
+
+const generator = new ProposalGenerator();
+
+// 템플릿 기반 기획서 생성
+const proposal = await generator.create({
+  template: 'templates/erp_storyboard.json',
+  project: {
+    name: '모바일 앱 개발',
+    type: 'mobile_app',
+    requirements: requirements_data
+  }
+});
+
+// 구조화된 문서 출력
+await generator.export(proposal, 'output/mobile_app_proposal.md');
+```
+
+### 3. ppt-converter.js
+Markdown 기획서를 PPT로 변환
+
+```javascript
+import { PPTConverter } from './ppt-converter.js';
+
+const converter = new PPTConverter();
+
+// 기획서를 PPT로 변환
+await converter.convertProposal({
+  input: 'output/mobile_app_proposal.md',
+  template: 'templates/proposal_template.pptx',
+  output: 'final/mobile_app_proposal.pptx'
+});
+```
+
+## 템플릿 구조 정의
+
+### template-schema.json
+```json
+{
+  "template_info": {
+    "name": "ERP Storyboard Template",
+    "version": "1.0",
+    "source": "SAM_ERP_Storyboard.pdf",
+    "created": "2025-01-03"
+  },
+  "page_templates": [
+    {
+      "type": "cover",
+      "layout": "center_aligned",
+      "elements": {
+        "title": { "position": "center_top", "style": "heading1" },
+        "subtitle": { "position": "center_middle", "style": "heading2" },
+        "date": { "position": "bottom_right", "style": "caption" },
+        "logo": { "position": "bottom_left", "style": "image" }
+      }
+    },
+    {
+      "type": "document_history",
+      "layout": "table_centered",
+      "elements": {
+        "table": {
+          "columns": ["날짜", "버전", "주요 내용", "상세 내용", "비고"],
+          "style": "bordered_table"
+        }
+      }
+    },
+    {
+      "type": "system_structure",
+      "layout": "diagram_centered",
+      "elements": {
+        "diagram": { "type": "hierarchical_tree", "style": "flowchart" },
+        "description": { "position": "bottom", "style": "body_text" }
+      }
+    },
+    {
+      "type": "detail_screen",
+      "layout": "two_column",
+      "elements": {
+        "wireframe": { "position": "left_column", "style": "image_frame" },
+        "description": { "position": "right_column", "style": "numbered_list" },
+        "header_info": { "position": "top_table", "style": "info_table" }
+      }
+    }
+  ]
+}
+```
+
+## 자동 콘텐츠 생성 규칙
+
+### 1. 표지 생성
+```javascript
+function generateCover(projectInfo) {
+  return {
+    title: projectInfo.name,
+    subtitle: `${projectInfo.type} 프로젝트 기획서`,
+    date: new Date().toISOString().split('T')[0].replace(/-/g, '.'),
+    version: "D1.0",
+    company: projectInfo.company || "Company Name"
+  };
+}
+```
+
+### 2. 문서 히스토리 생성
+```javascript
+function generateHistory(projectInfo) {
+  const today = new Date().toISOString().split('T')[0].replace(/-/g, '.');
+  return [{
+    date: today,
+    version: "D1.0",
+    main_content: "초안 작성",
+    detailed_content: `${projectInfo.name} 프로젝트 초안 작성`,
+    mark: ""
+  }];
+}
+```
+
+### 3. 시스템 구조 생성
+```javascript
+function generateSystemStructure(requirements) {
+  // 요구사항에서 메뉴 구조 자동 추출
+  const menuStructure = extractMenuFromRequirements(requirements);
+  return {
+    type: "hierarchical_diagram",
+    nodes: menuStructure,
+    connections: generateConnections(menuStructure)
+  };
+}
+```
+
+### 4. 상세 화면 생성
+```javascript
+function generateDetailScreens(screens) {
+  return screens.map((screen, index) => ({
+    page_number: index + 5, // 기본 페이지 이후 시작
+    screen_info: {
+      task_name: screen.module,
+      version: "D1.0",
+      route: screen.path,
+      screen_name: screen.name,
+      screen_id: screen.id
+    },
+    wireframe: generateWireframeDescription(screen),
+    descriptions: generateFeatureDescriptions(screen.features)
+  }));
+}
+```
+
+## 사용법
+
+### 1. PDF 템플릿 추출
+```bash
+node .claude/skills/proposal-skill/scripts/pdf-analyzer.js \
+  --input pdf_sample/SAM_ERP_Storyboard.pdf \
+  --output templates/extracted_template.json
+```
+
+### 2. 새 기획서 생성
+```bash
+node .claude/skills/proposal-skill/scripts/proposal-generator.js \
+  --template templates/extracted_template.json \
+  --project project_config.json \
+  --output output/new_proposal.md
+```
+
+### 3. PPT 변환
+```bash
+node .claude/skills/proposal-skill/scripts/ppt-converter.js \
+  --input output/new_proposal.md \
+  --output final/proposal.pptx
+```
+
+### 4. 통합 실행
+```bash
+npm run create-proposal -- \
+  --template pdf_sample/SAM_ERP_Storyboard.pdf \
+  --project "모바일 앱 개발" \
+  --requirements requirements.json \
+  --output final/mobile_app_proposal.pptx
+```
+
+## 고급 기능
+
+### 1. 템플릿 자동 매칭
+사용자 프로젝트 타입에 따라 최적 템플릿 자동 선택
+
+```javascript
+const templateMatcher = {
+  'mobile_app': 'templates/mobile_template.json',
+  'web_service': 'templates/web_template.json',
+  'erp_system': 'templates/erp_template.json',
+  'ecommerce': 'templates/ecommerce_template.json'
+};
+```
+
+### 2. 인터랙티브 콘텐츠 생성
+사용자와의 대화를 통한 단계적 기획서 완성
+
+### 3. 버전 관리 시스템
+기획서 변경 이력 자동 추적 및 관리
+
+### 4. 협업 기능
+여러 작성자 간 동시 편집 지원
+
+## 품질 보증
+
+### 자동 검증 기능
+- 필수 섹션 누락 검사
+- 페이지 번호 연속성 확인
+- 참조 무결성 검증
+- 템플릿 준수성 검사
+
+### 콘텐츠 품질 기준
+- **완성도**: 모든 필수 정보 포함
+- **일관성**: 용어 및 스타일 통일
+- **정확성**: 요구사항과 결과물 일치
+- **실용성**: 실제 개발 가능한 수준
+
+## 확장성
+
+### 새로운 템플릿 추가
+1. PDF 샘플을 `pdf_sample/` 디렉토리에 추가
+2. `pdf-analyzer.js`로 구조 분석 및 템플릿 추출
+3. 추출된 템플릿을 `templates/` 디렉토리에 저장
+4. `template-registry.json`에 새 템플릿 등록
+
+### 커스텀 생성 규칙
+프로젝트별 특수 요구사항에 맞는 생성 규칙 추가 가능
+
+## 연동 가능한 도구
+
+- **Research Agent**: 시장 조사 데이터 자동 반영
+- **Organizer Agent**: 콘텐츠 구조화 및 PPT 변환
+- **PPTX Skill**: PowerPoint 파일 최종 생성
+- **Design Skill**: 브랜드 가이드라인 적용

.claude/skills/proposal-skill/scripts/pdf-analyzer.js

@@ -0,0 +1,393 @@
+/**
+ * PDF 기획서 구조 분석 및 템플릿 추출 스크립트
+ * SAM_ERP_Storyboard.pdf를 분석하여 재사용 가능한 템플릿 생성
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+
+class PDFAnalyzer {
+  constructor() {
+    this.pagePatterns = new Map();
+    this.extractedTemplate = {};
+  }
+
+  /**
+   * PDF 파일 구조 분석
+   */
+  async analyze(pdfPath) {
+    console.log(`📊 PDF 구조 분석 시작: ${pdfPath}`);
+
+    // SAM_ERP 스토리보드 구조 패턴 정의 (PDF 분석 결과 기반)
+    const structure = {
+      metadata: {
+        source: path.basename(pdfPath),
+        total_pages: 17, // 확인된 페이지 수
+        analysis_date: new Date().toISOString(),
+        document_type: "storyboard_specification"
+      },
+
+      sections: [
+        {
+          type: "cover",
+          pages: [1],
+          pattern: {
+            layout: "brand_centered",
+            elements: ["project_title", "company_name", "date"],
+            color_scheme: "green_brand"
+          }
+        },
+        {
+          type: "document_history",
+          pages: [2],
+          pattern: {
+            layout: "table_full_width",
+            elements: ["version_table"],
+            table_columns: ["Date", "Version", "Main Contents", "Detailed Contents", "MARK"]
+          }
+        },
+        {
+          type: "menu_structure",
+          pages: [3],
+          pattern: {
+            layout: "hierarchical_diagram",
+            elements: ["system_tree", "navigation_flow"],
+            diagram_type: "organizational_chart"
+          }
+        },
+        {
+          type: "common_guidelines",
+          pages: [4, 5, 6, 7, 8],
+          pattern: {
+            layout: "documentation_style",
+            elements: ["section_header", "content_blocks", "code_examples"],
+            subsections: ["interaction", "responsive", "template", "notifications"]
+          }
+        },
+        {
+          type: "detail_screens",
+          pages: [9, 10, 11, 12, 13, 14, 15, 16, 17],
+          pattern: {
+            layout: "wireframe_with_description",
+            elements: ["header_table", "wireframe_image", "numbered_descriptions"],
+            header_structure: {
+              task_name: "단위업무명",
+              version: "버전",
+              page_number: "Page Number",
+              route: "경로",
+              screen_name: "화면명",
+              screen_id: "화면 ID"
+            }
+          }
+        }
+      ]
+    };
+
+    console.log(`✅ 구조 분석 완료: ${structure.sections.length}개 섹션 식별`);
+    return structure;
+  }
+
+  /**
+   * 분석 결과에서 재사용 가능한 템플릿 추출
+   */
+  async extractTemplate(structure) {
+    console.log("🎨 템플릿 추출 중...");
+
+    const template = {
+      template_info: {
+        name: "ERP Storyboard Template",
+        version: "1.0",
+        source: structure.metadata.source,
+        created: structure.metadata.analysis_date,
+        description: "ERP 시스템 스토리보드 기획서 템플릿"
+      },
+
+      // 페이지 템플릿 정의
+      page_templates: [
+        // 표지 템플릿
+        {
+          type: "cover",
+          name: "브랜드 표지",
+          layout: {
+            type: "center_aligned",
+            background: "brand_gradient",
+            color_scheme: {
+              primary: "#8BC34A",
+              secondary: "#FFFFFF",
+              accent: "#2E7D32"
+            }
+          },
+          elements: {
+            project_title: {
+              position: { x: "center", y: "30%" },
+              style: "heading1_bold",
+              font_size: 48,
+              color: "white"
+            },
+            company_name: {
+              position: { x: "right", y: "bottom" },
+              style: "corporate",
+              font_size: 16,
+              color: "dark_gray"
+            },
+            date: {
+              position: { x: "right", y: "bottom-20" },
+              style: "caption",
+              font_size: 12,
+              color: "medium_gray"
+            },
+            brand_logo: {
+              position: { x: "left", y: "middle" },
+              size: { width: 200, height: 100 },
+              type: "image_placeholder"
+            }
+          }
+        },
+
+        // 문서 히스토리 템플릿
+        {
+          type: "document_history",
+          name: "문서 이력 관리",
+          layout: {
+            type: "table_centered",
+            padding: 40
+          },
+          elements: {
+            section_title: {
+              position: { x: "left", y: "top" },
+              content: "Document History",
+              style: "section_heading"
+            },
+            history_table: {
+              position: { x: "center", y: "middle" },
+              table_config: {
+                columns: [
+                  { name: "Date", width: "15%" },
+                  { name: "Version", width: "10%" },
+                  { name: "Main Contents", width: "20%" },
+                  { name: "Detailed Contents", width: "45%" },
+                  { name: "MARK", width: "10%" }
+                ],
+                style: "bordered_table",
+                header_color: "#8BC34A",
+                alternate_rows: true
+              }
+            }
+          }
+        },
+
+        // 메뉴 구조 템플릿
+        {
+          type: "menu_structure",
+          name: "시스템 구조도",
+          layout: {
+            type: "diagram_centered",
+            padding: 30
+          },
+          elements: {
+            section_title: {
+              position: { x: "left", y: "top" },
+              content: "Menu Structure",
+              style: "section_heading"
+            },
+            system_diagram: {
+              position: { x: "center", y: "middle" },
+              diagram_config: {
+                type: "hierarchical_tree",
+                root_node_style: "rounded_rectangle",
+                connection_style: "straight_lines",
+                node_colors: {
+                  level_1: "#8BC34A",
+                  level_2: "#C8E6C9",
+                  level_3: "#E8F5E8"
+                }
+              }
+            }
+          }
+        },
+
+        // 공통 가이드라인 템플릿
+        {
+          type: "common_guidelines",
+          name: "공통 가이드라인",
+          layout: {
+            type: "documentation_style",
+            padding: 35
+          },
+          elements: {
+            section_header: {
+              position: { x: "left", y: "top" },
+              style: "section_divider",
+              background_color: "#8BC34A"
+            },
+            content_blocks: {
+              position: { x: "full_width", y: "main_area" },
+              style: "structured_content",
+              spacing: 20
+            },
+            code_examples: {
+              style: "code_block",
+              background_color: "#F5F5F5",
+              border_color: "#E0E0E0"
+            }
+          }
+        },
+
+        // 상세 화면 템플릿
+        {
+          type: "detail_screen",
+          name: "상세 화면 설계",
+          layout: {
+            type: "wireframe_with_description",
+            padding: 25
+          },
+          elements: {
+            header_table: {
+              position: { x: "top", y: "header" },
+              table_config: {
+                columns: [
+                  { name: "단위업무명", width: "20%" },
+                  { name: "버전", width: "15%" },
+                  { name: "Page Number", width: "15%" },
+                  { name: "경로", width: "25%" },
+                  { name: "화면명", width: "15%" },
+                  { name: "화면 ID", width: "10%" }
+                ],
+                style: "info_table_header"
+              }
+            },
+            wireframe_area: {
+              position: { x: "left", y: "main", width: "60%" },
+              style: "wireframe_container",
+              border: "solid_gray",
+              background: "light_gray"
+            },
+            description_area: {
+              position: { x: "right", y: "main", width: "35%" },
+              style: "numbered_descriptions",
+              list_style: "numbered_with_icons"
+            }
+          }
+        }
+      ],
+
+      // 콘텐츠 생성 규칙
+      content_rules: {
+        auto_numbering: {
+          pages: true,
+          descriptions: true,
+          sections: false
+        },
+        naming_conventions: {
+          screen_ids: "snake_case",
+          route_format: "path/screen_name",
+          version_format: "D1.x"
+        },
+        required_sections: [
+          "cover",
+          "document_history",
+          "menu_structure",
+          "common_guidelines"
+        ]
+      },
+
+      // 디자인 시스템
+      design_system: {
+        colors: {
+          primary: "#8BC34A",
+          secondary: "#4CAF50",
+          accent: "#2E7D32",
+          text_primary: "#212121",
+          text_secondary: "#757575",
+          background: "#FFFFFF",
+          surface: "#F5F5F5",
+          border: "#E0E0E0"
+        },
+        typography: {
+          heading1: { font: "Noto Sans", size: 32, weight: "bold" },
+          heading2: { font: "Noto Sans", size: 24, weight: "bold" },
+          heading3: { font: "Noto Sans", size: 18, weight: "medium" },
+          body: { font: "Noto Sans", size: 14, weight: "regular" },
+          caption: { font: "Noto Sans", size: 12, weight: "regular" }
+        },
+        spacing: {
+          page_margin: 40,
+          section_gap: 30,
+          element_gap: 15,
+          line_height: 1.5
+        }
+      }
+    };
+
+    console.log("✅ 템플릿 추출 완료");
+    return template;
+  }
+
+  /**
+   * 추출된 템플릿을 JSON 파일로 저장
+   */
+  async saveTemplate(template, outputPath) {
+    try {
+      const templateDir = path.dirname(outputPath);
+      await fs.mkdir(templateDir, { recursive: true });
+
+      await fs.writeFile(
+        outputPath,
+        JSON.stringify(template, null, 2),
+        'utf8'
+      );
+
+      console.log(`💾 템플릿 저장 완료: ${outputPath}`);
+      return outputPath;
+    } catch (error) {
+      console.error("❌ 템플릿 저장 실패:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * 기본 ERP 템플릿 생성 (샘플 PDF 기반)
+   */
+  async createDefaultTemplate() {
+    const structure = await this.analyze('pdf_sample/SAM_ERP_Storyboard.pdf');
+    const template = await this.extractTemplate(structure);
+    const outputPath = '.claude/skills/proposal-skill/templates/erp_storyboard_template.json';
+
+    await this.saveTemplate(template, outputPath);
+    return outputPath;
+  }
+}
+
+// 명령줄 실행 지원
+async function main() {
+  const args = process.argv.slice(2);
+  const analyzer = new PDFAnalyzer();
+
+  if (args.includes('--create-default')) {
+    console.log("🚀 기본 ERP 템플릿 생성 중...");
+    const templatePath = await analyzer.createDefaultTemplate();
+    console.log(`✅ 완료: ${templatePath}`);
+  } else if (args.includes('--help')) {
+    console.log(`
+📊 PDF 분석기 사용법:
+
+기본 템플릿 생성:
+  node pdf-analyzer.js --create-default
+
+커스텀 PDF 분석:
+  node pdf-analyzer.js --input path/to/pdf --output path/to/template.json
+
+도움말:
+  node pdf-analyzer.js --help
+    `);
+  } else {
+    // 기본 실행
+    await analyzer.createDefaultTemplate();
+  }
+}
+
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+module.exports = { PDFAnalyzer };

.claude/skills/proposal-skill/scripts/proposal-generator.js

@@ -0,0 +1,829 @@
+/**
+ * 기획서 자동 생성 엔진
+ * 템플릿과 요구사항을 바탕으로 완성된 기획서 생성
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+
+class ProposalGenerator {
+  constructor() {
+    this.template = null;
+    this.projectInfo = null;
+  }
+
+  /**
+   * 템플릿 로드
+   */
+  async loadTemplate(templatePath) {
+    try {
+      const templateContent = await fs.readFile(templatePath, 'utf8');
+      this.template = JSON.parse(templateContent);
+      console.log(`📋 템플릿 로드: ${this.template.template_info.name}`);
+      return this.template;
+    } catch (error) {
+      console.error("❌ 템플릿 로드 실패:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * 프로젝트 정보 설정
+   */
+  setProjectInfo(projectInfo) {
+    this.projectInfo = {
+      name: projectInfo.name || "새 프로젝트",
+      type: projectInfo.type || "web_service",
+      company: projectInfo.company || "Company Name",
+      author: projectInfo.author || "작성자",
+      description: projectInfo.description || "",
+      requirements: projectInfo.requirements || [],
+      features: projectInfo.features || [],
+      target_users: projectInfo.target_users || [],
+      ...projectInfo
+    };
+    console.log(`🎯 프로젝트 설정: ${this.projectInfo.name}`);
+  }
+
+  /**
+   * 기획서 생성
+   */
+  async generate() {
+    if (!this.template || !this.projectInfo) {
+      throw new Error("템플릿과 프로젝트 정보가 필요합니다.");
+    }
+
+    console.log("📝 기획서 생성 중...");
+
+    const proposal = {
+      metadata: this.generateMetadata(),
+      cover: this.generateCover(),
+      document_history: this.generateDocumentHistory(),
+      menu_structure: this.generateMenuStructure(),
+      common_guidelines: this.generateCommonGuidelines(),
+      detail_screens: this.generateDetailScreens()
+    };
+
+    return proposal;
+  }
+
+  /**
+   * 메타데이터 생성
+   */
+  generateMetadata() {
+    return {
+      title: this.projectInfo.name,
+      subtitle: `${this.projectInfo.type} 프로젝트 기획서`,
+      version: "D1.0",
+      created_date: new Date().toISOString().split('T')[0].replace(/-/g, '.'),
+      author: this.projectInfo.author,
+      company: this.projectInfo.company,
+      total_pages: this.estimatePageCount(),
+      template_used: this.template.template_info.name
+    };
+  }
+
+  /**
+   * 표지 생성
+   */
+  generateCover() {
+    return {
+      type: "cover",
+      title: this.projectInfo.name,
+      subtitle: this.generateSubtitle(),
+      date: new Date().toISOString().split('T')[0].replace(/-/g, '.'),
+      version: "D1.0",
+      company: this.projectInfo.company,
+      author: this.projectInfo.author,
+      description: this.projectInfo.description
+    };
+  }
+
+  /**
+   * 부제목 자동 생성
+   */
+  generateSubtitle() {
+    const typeMapping = {
+      'mobile_app': '모바일 애플리케이션',
+      'web_service': '웹 서비스',
+      'erp_system': 'ERP 시스템',
+      'ecommerce': '이커머스 플랫폼',
+      'cms': '콘텐츠 관리 시스템',
+      'crm': '고객관계관리 시스템'
+    };
+
+    return `${typeMapping[this.projectInfo.type] || '시스템'} 기획서`;
+  }
+
+  /**
+   * 문서 히스토리 생성
+   */
+  generateDocumentHistory() {
+    const today = new Date().toISOString().split('T')[0].replace(/-/g, '.');
+
+    return {
+      type: "document_history",
+      table: [
+        {
+          date: today,
+          version: "D1.0",
+          main_content: "초안 작성",
+          detailed_content: `${this.projectInfo.name} 프로젝트 기획서 초안 작성`,
+          mark: ""
+        }
+      ]
+    };
+  }
+
+  /**
+   * 메뉴 구조 생성
+   */
+  generateMenuStructure() {
+    let menuStructure;
+
+    if (this.projectInfo.requirements && this.projectInfo.requirements.length > 0) {
+      // 요구사항에서 메뉴 구조 추출
+      menuStructure = this.extractMenuFromRequirements();
+    } else {
+      // 기본 구조 사용
+      menuStructure = this.getDefaultMenuStructure();
+    }
+
+    return {
+      type: "menu_structure",
+      title: "Menu Structure",
+      structure: menuStructure
+    };
+  }
+
+  /**
+   * 요구사항에서 메뉴 구조 추출
+   */
+  extractMenuFromRequirements() {
+    const requirements = this.projectInfo.requirements;
+    const menuMap = new Map();
+
+    // 요구사항을 카테고리별로 분류
+    requirements.forEach(req => {
+      const category = req.category || this.guessCategory(req.title);
+      if (!menuMap.has(category)) {
+        menuMap.set(category, []);
+      }
+      menuMap.get(category).push({
+        name: req.title,
+        description: req.description,
+        priority: req.priority || 'medium'
+      });
+    });
+
+    // 계층 구조로 변환
+    const structure = {
+      root: this.projectInfo.name,
+      children: []
+    };
+
+    for (const [category, items] of menuMap) {
+      structure.children.push({
+        name: category,
+        children: items.map(item => ({
+          name: item.name,
+          leaf: true,
+          description: item.description
+        }))
+      });
+    }
+
+    return structure;
+  }
+
+  /**
+   * 카테고리 추측
+   */
+  guessCategory(title) {
+    const categoryKeywords = {
+      '사용자관리': ['사용자', '회원', '계정', '인증', '로그인'],
+      '콘텐츠관리': ['게시글', '콘텐츠', '글', '포스트', '댓글'],
+      '결제관리': ['결제', '구매', '주문', '결제수단', '카드'],
+      '상품관리': ['상품', '제품', '상품목록', '카탈로그'],
+      '시스템관리': ['설정', '관리자', '백오피스', '시스템'],
+      '통계/분석': ['통계', '분석', '리포트', '대시보드', '차트']
+    };
+
+    for (const [category, keywords] of Object.entries(categoryKeywords)) {
+      if (keywords.some(keyword => title.includes(keyword))) {
+        return category;
+      }
+    }
+
+    return '기타기능';
+  }
+
+  /**
+   * 기본 메뉴 구조
+   */
+  getDefaultMenuStructure() {
+    const defaultStructures = {
+      'mobile_app': {
+        root: "모바일 앱",
+        children: [
+          { name: "인증", children: ["로그인", "회원가입", "비밀번호 찾기"] },
+          { name: "메인", children: ["홈", "검색", "카테고리"] },
+          { name: "사용자", children: ["프로필", "설정", "알림"] },
+          { name: "콘텐츠", children: ["목록", "상세", "작성"] }
+        ]
+      },
+      'web_service': {
+        root: "웹 서비스",
+        children: [
+          { name: "사용자관리", children: ["회원가입", "로그인", "프로필관리"] },
+          { name: "콘텐츠관리", children: ["작성", "편집", "삭제", "검색"] },
+          { name: "시스템관리", children: ["설정", "통계", "백업"] }
+        ]
+      }
+    };
+
+    return defaultStructures[this.projectInfo.type] || defaultStructures['web_service'];
+  }
+
+  /**
+   * 공통 가이드라인 생성
+   */
+  generateCommonGuidelines() {
+    return {
+      type: "common_guidelines",
+      sections: [
+        {
+          title: "사용자 인터랙션",
+          content: this.generateInteractionGuidelines()
+        },
+        {
+          title: "반응형 디자인",
+          content: this.generateResponsiveGuidelines()
+        },
+        {
+          title: "화면 템플릿",
+          content: this.generateScreenTemplateGuidelines()
+        },
+        {
+          title: "알림 시스템",
+          content: this.generateNotificationGuidelines()
+        }
+      ]
+    };
+  }
+
+  /**
+   * 인터랙션 가이드라인 생성
+   */
+  generateInteractionGuidelines() {
+    const interactions = [
+      { type: "Tap", description: "일정영역을 사용자가 터치합니다.", apply: "Yes" },
+      { type: "Scroll Up/Down", description: "상하 스크롤 동작", apply: "Yes" },
+      { type: "Swipe Left/Right", description: "좌우 스와이프 동작", apply: "Yes" },
+      { type: "Drag & Drop", description: "드래그 앤 드롭 기능", apply: "Yes" }
+    ];
+
+    return {
+      type: "interaction_table",
+      data: interactions
+    };
+  }
+
+  /**
+   * 반응형 가이드라인 생성
+   */
+  generateResponsiveGuidelines() {
+    return {
+      type: "responsive_guide",
+      breakpoints: [
+        { device: "모바일", range: "< 640px", note: "기본" },
+        { device: "태블릿", range: "768px ~ 1023px", note: "md" },
+        { device: "데스크탑", range: "1024px+", note: "lg" },
+        { device: "대형 모니터", range: "1280px+", note: "xl" }
+      ]
+    };
+  }
+
+  /**
+   * 화면 템플릿 가이드라인 생성
+   */
+  generateScreenTemplateGuidelines() {
+    return {
+      type: "screen_template",
+      elements: [
+        { name: "Header", description: "상단 네비게이션 및 타이틀" },
+        { name: "Content", description: "주요 콘텐츠 영역" },
+        { name: "Footer", description: "하단 정보 및 링크" },
+        { name: "Sidebar", description: "사이드 메뉴 (PC 버전)" }
+      ]
+    };
+  }
+
+  /**
+   * 알림 시스템 가이드라인 생성
+   */
+  generateNotificationGuidelines() {
+    return {
+      type: "notification_guide",
+      types: [
+        { name: "알림 Alert", description: "사용자에게 상황을 알려주기 위한 팝업" },
+        { name: "확인 Alert", description: "사용자에게 확인이 필요할 경우 제공되는 팝업" },
+        { name: "토스트 메시지", description: "단순 Notify (2~3)초 후 페이지 내에서 Fade out" }
+      ]
+    };
+  }
+
+  /**
+   * 상세 화면 생성
+   */
+  generateDetailScreens() {
+    const screens = [];
+
+    if (this.projectInfo.features && this.projectInfo.features.length > 0) {
+      // 기능 목록에서 화면 생성
+      this.projectInfo.features.forEach((feature, index) => {
+        screens.push(this.generateScreenFromFeature(feature, index));
+      });
+    } else if (this.projectInfo.requirements && this.projectInfo.requirements.length > 0) {
+      // 요구사항에서 화면 생성
+      this.projectInfo.requirements.forEach((req, index) => {
+        screens.push(this.generateScreenFromRequirement(req, index));
+      });
+    } else {
+      // 기본 화면들 생성
+      screens.push(...this.generateDefaultScreens());
+    }
+
+    return {
+      type: "detail_screens",
+      screens: screens
+    };
+  }
+
+  /**
+   * 기능에서 화면 생성
+   */
+  generateScreenFromFeature(feature, index) {
+    return {
+      page_number: 10 + index, // 기본 페이지 이후
+      screen_info: {
+        task_name: this.projectInfo.name,
+        version: "D1.0",
+        route: this.generateRoute(feature.name),
+        screen_name: feature.name,
+        screen_id: this.generateScreenId(feature.name)
+      },
+      wireframe: {
+        type: "feature_screen",
+        description: `${feature.name} 화면 구성`,
+        elements: this.generateUIElements(feature)
+      },
+      descriptions: this.generateFeatureDescriptions(feature)
+    };
+  }
+
+  /**
+   * 요구사항에서 화면 생성
+   */
+  generateScreenFromRequirement(requirement, index) {
+    return {
+      page_number: 10 + index,
+      screen_info: {
+        task_name: this.projectInfo.name,
+        version: "D1.0",
+        route: this.generateRoute(requirement.title),
+        screen_name: requirement.title,
+        screen_id: this.generateScreenId(requirement.title)
+      },
+      wireframe: {
+        type: "requirement_screen",
+        description: `${requirement.title} 화면`,
+        elements: this.generateUIElementsFromRequirement(requirement)
+      },
+      descriptions: this.generateRequirementDescriptions(requirement)
+    };
+  }
+
+  /**
+   * 기본 화면들 생성
+   */
+  generateDefaultScreens() {
+    const defaultScreens = [
+      {
+        name: "메인 화면",
+        route: "/main",
+        features: ["네비게이션", "주요 콘텐츠", "검색"]
+      },
+      {
+        name: "로그인",
+        route: "/auth/login",
+        features: ["이메일 입력", "비밀번호 입력", "로그인 버튼"]
+      },
+      {
+        name: "목록 화면",
+        route: "/list",
+        features: ["검색 필터", "목록 표시", "페이지네이션"]
+      }
+    ];
+
+    return defaultScreens.map((screen, index) => ({
+      page_number: 10 + index,
+      screen_info: {
+        task_name: this.projectInfo.name,
+        version: "D1.0",
+        route: screen.route,
+        screen_name: screen.name,
+        screen_id: this.generateScreenId(screen.name)
+      },
+      wireframe: {
+        type: "default_screen",
+        description: `${screen.name} 구성`,
+        elements: screen.features
+      },
+      descriptions: this.generateDefaultDescriptions(screen)
+    }));
+  }
+
+  /**
+   * 라우트 생성
+   */
+  generateRoute(screenName) {
+    return '/' + screenName
+      .toLowerCase()
+      .replace(/\s+/g, '_')
+      .replace(/[^a-z0-9_]/g, '');
+  }
+
+  /**
+   * 화면 ID 생성
+   */
+  generateScreenId(screenName) {
+    return screenName
+      .toLowerCase()
+      .replace(/\s+/g, '_')
+      .replace(/[^a-z0-9_]/g, '');
+  }
+
+  /**
+   * UI 요소 생성
+   */
+  generateUIElements(feature) {
+    // 기능 타입에 따른 UI 요소 자동 생성
+    const elementMap = {
+      'login': ['이메일 입력', '비밀번호 입력', '로그인 버튼', '회원가입 링크'],
+      'list': ['검색바', '필터', '목록 아이템', '페이지네이션'],
+      'form': ['입력 필드', '제출 버튼', '취소 버튼', '유효성 검사'],
+      'detail': ['제목', '내용', '수정 버튼', '삭제 버튼', '목록으로 버튼']
+    };
+
+    const featureType = this.guessFeatureType(feature.name);
+    return elementMap[featureType] || ['헤더', '메인 콘텐츠', '푸터'];
+  }
+
+  /**
+   * 기능 타입 추측
+   */
+  guessFeatureType(featureName) {
+    const typeKeywords = {
+      'login': ['로그인', '인증', '로그인'],
+      'list': ['목록', '리스트', '조회'],
+      'form': ['등록', '작성', '입력', '수정'],
+      'detail': ['상세', '세부', '정보']
+    };
+
+    for (const [type, keywords] of Object.entries(typeKeywords)) {
+      if (keywords.some(keyword => featureName.includes(keyword))) {
+        return type;
+      }
+    }
+
+    return 'default';
+  }
+
+  /**
+   * 기능 설명 생성
+   */
+  generateFeatureDescriptions(feature) {
+    const descriptions = [];
+
+    if (feature.elements) {
+      feature.elements.forEach((element, index) => {
+        descriptions.push({
+          number: index + 1,
+          title: element,
+          description: `${element} 기능 구현`
+        });
+      });
+    }
+
+    return descriptions;
+  }
+
+  /**
+   * 페이지 수 추정
+   */
+  estimatePageCount() {
+    let pageCount = 5; // 기본 페이지 (표지, 히스토리, 구조, 가이드라인)
+
+    if (this.projectInfo.features) {
+      pageCount += this.projectInfo.features.length;
+    } else if (this.projectInfo.requirements) {
+      pageCount += this.projectInfo.requirements.length;
+    } else {
+      pageCount += 3; // 기본 화면 수
+    }
+
+    return pageCount;
+  }
+
+  /**
+   * Markdown 형태로 기획서 출력
+   */
+  async exportToMarkdown(proposal, outputPath) {
+    const markdown = this.generateMarkdown(proposal);
+
+    const outputDir = path.dirname(outputPath);
+    await fs.mkdir(outputDir, { recursive: true });
+
+    await fs.writeFile(outputPath, markdown, 'utf8');
+    console.log(`📄 Markdown 기획서 생성: ${outputPath}`);
+
+    return outputPath;
+  }
+
+  /**
+   * Markdown 생성
+   */
+  generateMarkdown(proposal) {
+    let markdown = '';
+
+    // 표지
+    markdown += `# ${proposal.cover.title}\n`;
+    markdown += `## ${proposal.cover.subtitle}\n\n`;
+    markdown += `**버전**: ${proposal.cover.version}  \n`;
+    markdown += `**작성일**: ${proposal.cover.date}  \n`;
+    markdown += `**작성자**: ${proposal.cover.author}  \n`;
+    markdown += `**회사**: ${proposal.cover.company}  \n\n`;
+
+    if (proposal.cover.description) {
+      markdown += `**프로젝트 설명**: ${proposal.cover.description}\n\n`;
+    }
+
+    markdown += `---\n\n`;
+
+    // 문서 히스토리
+    markdown += `## Document History\n\n`;
+    markdown += `| 날짜 | 버전 | 주요 내용 | 상세 내용 | 비고 |\n`;
+    markdown += `|------|------|-----------|-----------|------|\n`;
+
+    proposal.document_history.table.forEach(row => {
+      markdown += `| ${row.date} | ${row.version} | ${row.main_content} | ${row.detailed_content} | ${row.mark} |\n`;
+    });
+
+    markdown += `\n---\n\n`;
+
+    // 메뉴 구조
+    markdown += `## Menu Structure\n\n`;
+    markdown += this.generateMenuMarkdown(proposal.menu_structure.structure);
+    markdown += `\n---\n\n`;
+
+    // 공통 가이드라인
+    markdown += `## 공통 가이드라인\n\n`;
+    proposal.common_guidelines.sections.forEach(section => {
+      markdown += `### ${section.title}\n\n`;
+      markdown += this.generateSectionMarkdown(section.content);
+      markdown += `\n`;
+    });
+
+    markdown += `---\n\n`;
+
+    // 상세 화면들
+    markdown += `## 상세 화면 설계\n\n`;
+    proposal.detail_screens.screens.forEach((screen, index) => {
+      markdown += `### 슬라이드 ${screen.page_number}: ${screen.screen_info.screen_name}\n\n`;
+
+      markdown += `**화면 정보**:\n`;
+      markdown += `- 단위업무명: ${screen.screen_info.task_name}\n`;
+      markdown += `- 경로: ${screen.screen_info.route}\n`;
+      markdown += `- 화면 ID: ${screen.screen_info.screen_id}\n`;
+      markdown += `- 버전: ${screen.screen_info.version}\n\n`;
+
+      markdown += `**화면 구성**:\n`;
+      if (Array.isArray(screen.wireframe.elements)) {
+        screen.wireframe.elements.forEach((element, idx) => {
+          markdown += `${idx + 1}. ${element}\n`;
+        });
+      }
+
+      markdown += `\n**기능 설명**:\n`;
+      if (screen.descriptions && screen.descriptions.length > 0) {
+        screen.descriptions.forEach(desc => {
+          markdown += `${desc.number}. **${desc.title}**: ${desc.description}\n`;
+        });
+      }
+
+      markdown += `\n---\n\n`;
+    });
+
+    return markdown;
+  }
+
+  /**
+   * 메뉴 구조 Markdown 생성
+   */
+  generateMenuMarkdown(structure, depth = 0) {
+    let markdown = '';
+    const indent = '  '.repeat(depth);
+
+    if (structure.root && depth === 0) {
+      markdown += `- **${structure.root}**\n`;
+    }
+
+    if (structure.children) {
+      structure.children.forEach(child => {
+        if (typeof child === 'string') {
+          markdown += `${indent}- ${child}\n`;
+        } else {
+          markdown += `${indent}- **${child.name}**\n`;
+          if (child.children) {
+            child.children.forEach(subChild => {
+              const subIndent = '  '.repeat(depth + 1);
+              if (typeof subChild === 'string') {
+                markdown += `${subIndent}- ${subChild}\n`;
+              } else {
+                markdown += `${subIndent}- ${subChild.name}\n`;
+              }
+            });
+          }
+        }
+      });
+    }
+
+    return markdown;
+  }
+
+  /**
+   * 섹션 Markdown 생성
+   */
+  generateSectionMarkdown(content) {
+    if (content.type === 'interaction_table') {
+      let markdown = `| Type | Description | Apply |\n|------|-------------|-------|\n`;
+      content.data.forEach(item => {
+        markdown += `| ${item.type} | ${item.description} | ${item.apply} |\n`;
+      });
+      return markdown;
+    }
+
+    if (content.type === 'responsive_guide') {
+      let markdown = `**브레이크 포인트**:\n`;
+      content.breakpoints.forEach(bp => {
+        markdown += `- ${bp.device}: ${bp.range} (${bp.note})\n`;
+      });
+      return markdown;
+    }
+
+    return JSON.stringify(content, null, 2);
+  }
+
+  // 요구사항에서 UI 요소 생성
+  generateUIElementsFromRequirement(requirement) {
+    // 요구사항 설명에서 UI 요소 추출 (간단한 키워드 매칭)
+    const description = requirement.description || requirement.title;
+    const elements = [];
+
+    // 일반적인 UI 패턴 매칭
+    if (description.includes('로그인') || description.includes('인증')) {
+      elements.push('이메일 입력', '비밀번호 입력', '로그인 버튼');
+    }
+    if (description.includes('목록') || description.includes('조회')) {
+      elements.push('검색바', '필터', '목록 아이템');
+    }
+    if (description.includes('등록') || description.includes('작성')) {
+      elements.push('입력 폼', '제출 버튼', '취소 버튼');
+    }
+
+    // 기본 요소가 없으면 일반적인 화면 구성 추가
+    if (elements.length === 0) {
+      elements.push('헤더', '메인 콘텐츠', '네비게이션');
+    }
+
+    return elements;
+  }
+
+  // 요구사항 설명 생성
+  generateRequirementDescriptions(requirement) {
+    const descriptions = [];
+
+    descriptions.push({
+      number: 1,
+      title: requirement.title,
+      description: requirement.description || `${requirement.title} 기능 구현`
+    });
+
+    // 우선순위가 있으면 추가
+    if (requirement.priority) {
+      descriptions.push({
+        number: 2,
+        title: "우선순위",
+        description: `개발 우선순위: ${requirement.priority}`
+      });
+    }
+
+    return descriptions;
+  }
+
+  // 기본 설명 생성
+  generateDefaultDescriptions(screen) {
+    const descriptions = [];
+
+    screen.features.forEach((feature, index) => {
+      descriptions.push({
+        number: index + 1,
+        title: feature,
+        description: `${feature} 구현 및 사용자 인터랙션 처리`
+      });
+    });
+
+    return descriptions;
+  }
+}
+
+// 명령줄 실행 지원
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help')) {
+    console.log(`
+📝 기획서 생성기 사용법:
+
+기본 사용:
+  node proposal-generator.js
+
+프로젝트 정보로 생성:
+  node proposal-generator.js --project project.json --output proposal.md
+
+템플릿 지정:
+  node proposal-generator.js --template template.json --project project.json
+
+예시:
+  node proposal-generator.js --project "모바일 앱" --type mobile_app --output mobile_proposal.md
+    `);
+    return;
+  }
+
+  try {
+    const generator = new ProposalGenerator();
+
+    // 템플릿 로드
+    const templatePath = '.claude/skills/proposal-skill/templates/erp_storyboard_template.json';
+    await generator.loadTemplate(templatePath);
+
+    // 샘플 프로젝트 정보
+    const sampleProject = {
+      name: "모바일 쇼핑몰 앱",
+      type: "mobile_app",
+      company: "Sample Company",
+      author: "기획팀",
+      description: "사용자 친화적인 모바일 쇼핑 경험을 제공하는 앱",
+      requirements: [
+        {
+          title: "사용자 로그인",
+          description: "이메일/비밀번호를 통한 사용자 인증 기능",
+          category: "사용자관리",
+          priority: "high"
+        },
+        {
+          title: "상품 목록 조회",
+          description: "카테고리별 상품 목록 및 검색 기능",
+          category: "상품관리",
+          priority: "high"
+        },
+        {
+          title: "장바구니",
+          description: "상품 선택 및 장바구니 관리 기능",
+          category: "결제관리",
+          priority: "medium"
+        }
+      ]
+    };
+
+    generator.setProjectInfo(sampleProject);
+
+    const proposal = await generator.generate();
+    const outputPath = 'output/sample_proposal.md';
+
+    await generator.exportToMarkdown(proposal, outputPath);
+
+    console.log("✅ 샘플 기획서 생성 완료!");
+    console.log(`📄 출력 파일: ${outputPath}`);
+
+  } catch (error) {
+    console.error("❌ 기획서 생성 실패:", error);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { ProposalGenerator };

.claude/skills/query-efficiency-auditor/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: ln-651-query-efficiency-auditor
+description: "Query efficiency audit worker (L3). Checks redundant entity fetches, N-UPDATE/DELETE loops, unnecessary resolves, over-fetching, missing bulk operations, wrong caching scope. Returns findings with severity, location, effort, recommendations."
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Query Efficiency Auditor (L3 Worker)
+
+Specialized worker auditing database query patterns for redundancy, inefficiency, and misuse.
+
+## Purpose & Scope
+
+- **Worker in ln-650 coordinator pipeline** - invoked by ln-650-persistence-performance-auditor
+- Audit **query efficiency** (Priority: HIGH)
+- Check redundant fetches, batch operation misuse, caching scope problems
+- Return structured findings with severity, location, effort, recommendations
+- Calculate compliance score (X/10) for Query Efficiency category
+
+## Inputs (from Coordinator)
+
+**MANDATORY READ:** Load `shared/references/task_delegation_pattern.md#audit-coordinator--worker-contract` for contextStore structure.
+
+Receives `contextStore` with: `tech_stack`, `best_practices`, `db_config` (database type, ORM settings), `codebase_root`.
+
+**Domain-aware:** Supports `domain_mode` + `current_domain`.
+
+## Workflow
+
+1) **Parse context from contextStore**
+   - Extract tech_stack, best_practices, db_config
+   - Determine scan_path (same logic as ln-624)
+
+2) **Scan codebase for violations**
+   - All Grep/Glob patterns use `scan_path`
+   - Trace call chains for redundant fetches (requires reading caller + callee)
+
+3) **Collect findings with severity, location, effort, recommendation**
+
+4) **Calculate score using penalty algorithm**
+
+5) **Return JSON result to coordinator**
+
+## Audit Rules (Priority: HIGH)
+
+### 1. Redundant Entity Fetch
+**What:** Same entity fetched from DB twice in a call chain
+
+**Detection:**
+- Find function A that calls `repo.get(id)` or `session.get(Model, id)`, then passes `id` (not object) to function B
+- Function B also calls `repo.get(id)` or `session.get(Model, id)` for the same entity
+- Common pattern: `acquire_next_pending()` returns job, but `_process_job(job_id)` re-fetches it
+
+**Detection patterns (Python/SQLAlchemy):**
+- Grep for `repo.*get_by_id|session\.get\(|session\.query.*filter.*id` in service/handler files
+- Trace: if function receives `entity_id: int/UUID` AND internally does `repo.get(entity_id)`, check if caller already has entity object
+- Check `expire_on_commit` setting: if `False`, objects remain valid after commit
+
+**Severity:**
+- **HIGH:** Redundant fetch in API request handler (adds latency per request)
+- **MEDIUM:** Redundant fetch in background job (less critical)
+
+**Recommendation:** Pass entity object instead of ID, or remove second fetch when `expire_on_commit=False`
+
+**Effort:** S (change signature to accept object instead of ID)
+
+### 2. N-UPDATE/DELETE Loop
+**What:** Loop of individual UPDATE/DELETE operations instead of single batch query
+
+**Detection:**
+- Pattern: `for item in items: await repo.update(item.id, ...)` or `for item in items: await repo.delete(item.id)`
+- Pattern: `for item in items: session.execute(update(Model).where(...))`
+
+**Detection patterns:**
+- Grep for `for .* in .*:` followed by `repo\.(update|delete|reset|save|mark_)` within 1-3 lines
+- Grep for `for .* in .*:` followed by `session\.execute\(.*update\(` within 1-3 lines
+
+**Severity:**
+- **HIGH:** Loop over >10 items (N separate round-trips to DB)
+- **MEDIUM:** Loop over <=10 items
+
+**Recommendation:** Replace with single `UPDATE ... WHERE id IN (...)` or `session.execute(update(Model).where(Model.id.in_(ids)))`
+
+**Effort:** M (rewrite query + test)
+
+### 3. Unnecessary Resolve
+**What:** Re-resolving a value from DB when it is already available in the caller's scope
+
+**Detection:**
+- Method receives `profile_id` and resolves engine from it, but caller already determined `engine`
+- Method receives `lang_code` and looks up dialect_id, but caller already has both `lang` and `dialect`
+- Pattern: function receives `X_id`, does `get(X_id)`, extracts `.field`, when caller already has `field`
+
+**Severity:**
+- **MEDIUM:** Extra DB query per invocation, especially in high-frequency paths
+
+**Recommendation:** Split method into two variants: `with_known_value(value, ...)` and `resolving_value(id, ...)`; or pass resolved value directly
+
+**Effort:** S-M (refactor signature, update callers)
+
+### 4. Over-Fetching
+**What:** Loading full ORM model when only few fields are needed
+
+**Detection:**
+- `session.query(Model)` or `select(Model)` without `.options(load_only(...))` for models with >10 columns
+- Especially in list/search endpoints that return many rows
+- Pattern: loading full entity but only using 2-3 fields
+
+**Severity:**
+- **MEDIUM:** Large models (>15 columns) in list endpoints
+- **LOW:** Small models (<10 columns) or single-entity endpoints
+
+**Recommendation:** Use `load_only()`, `defer()`, or raw `select(Model.col1, Model.col2)` for list queries
+
+**Effort:** S (add load_only to query)
+
+### 5. Missing Bulk Operations
+**What:** Sequential INSERT/DELETE/UPDATE instead of bulk operations
+
+**Detection:**
+- `for item in items: session.add(item)` instead of `session.add_all(items)`
+- `for item in items: session.delete(item)` instead of bulk delete
+- Pattern: loop with single `INSERT` per iteration
+
+**Severity:**
+- **MEDIUM:** Any sequential add/delete in loop (missed batch optimization)
+
+**Recommendation:** Use `session.add_all()`, `session.execute(insert(Model).values(list_of_dicts))`, `bulk_save_objects()`
+
+**Effort:** S (replace loop with bulk call)
+
+### 6. Wrong Caching Scope
+**What:** Request-scoped cache for data that rarely changes (should be app-scoped)
+
+**Detection:**
+- Service registered as request-scoped (e.g., via FastAPI `Depends()`) with internal cache (`_cache` dict, `_loaded` flag)
+- Cache populated by expensive query (JOINs, aggregations) per each request
+- Data TTL >> request duration (e.g., engine configurations, language lists, feature flags)
+
+**Detection patterns:**
+- Find classes with `_cache`, `_loaded`, `_initialized` attributes
+- Check if class is created per-request (via DI registration scope)
+- Compare: data change frequency vs cache lifetime
+
+**Severity:**
+- **HIGH:** Expensive query (JOINs, subqueries) cached only per-request
+- **MEDIUM:** Simple query cached per-request
+
+**Recommendation:** Move cache to app-scoped service (singleton), add TTL-based invalidation, or use CacheService with configurable TTL
+
+**Effort:** M (change DI scope, add TTL logic)
+
+## Scoring Algorithm
+
+See `shared/references/audit_scoring.md` for unified formula and score interpretation.
+
+## Output Format
+
+Return JSON to coordinator:
+
+```json
+{
+  "category": "Query Efficiency",
+  "score": 6,
+  "total_issues": 8,
+  "critical": 0,
+  "high": 3,
+  "medium": 4,
+  "low": 1,
+  "findings": [
+    {
+      "severity": "HIGH",
+      "location": "app/infrastructure/messaging/job_processor.py:434",
+      "issue": "Redundant entity fetch: job re-fetched by ID after acquire_next_pending already returned it",
+      "principle": "Query Efficiency / DRY Data Access",
+      "recommendation": "Pass job object to _process_job instead of job_id",
+      "effort": "S"
+    }
+  ]
+}
+```
+
+## Critical Rules
+
+- **Do not auto-fix:** Report only
+- **Trace call chains:** Rules 1 and 3 require reading both caller and callee
+- **ORM-aware:** Check `expire_on_commit`, `autoflush`, session scope before flagging redundant fetches
+- **Context-aware:** Small datasets or infrequent operations may justify simpler code
+- **Exclude tests:** Do not flag test fixtures or setup code
+
+## Definition of Done
+
+- contextStore parsed (tech_stack, db_config, ORM settings)
+- scan_path determined (domain path or codebase root)
+- All 6 checks completed:
+  - redundant fetch, N-UPDATE loop, unnecessary resolve, over-fetching, bulk ops, caching scope
+- Findings collected with severity, location, effort, recommendation
+- Score calculated
+- JSON returned to coordinator
+
+---
+**Version:** 1.0.0
+**Last Updated:** 2026-02-04

.claude/skills/regression-checker/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: ln-502-regression-checker
+description: Worker that runs existing tests to catch regressions. Auto-detects framework, reports pass/fail. No status changes or task creation.
+---
+
+# Regression Checker
+
+Runs the existing test suite to ensure no regressions after implementation changes.
+
+## Purpose & Scope
+- Detect test framework (pytest/jest/vitest/go test/etc.) and test dirs.
+- Execute full suite; capture results for Story quality gate.
+- Return PASS/FAIL with counts/log excerpts; never modifies Linear or kanban.
+
+## When to Use
+- **Invoked by ln-500-story-quality-gate** Pass 1 (after ln-501)
+- Code quality check passed
+- Before test planning pipeline (ln-510)
+
+## Workflow (concise)
+1) Auto-discover framework and test locations from repo config/files.
+2) **Read `docs/project/runbook.md`** — get exact test commands, Docker setup, environment variables. Use commands from runbook, NOT guessed commands.
+3) Build appropriate test command; run with timeout (~5m); capture stdout/stderr.
+4) Parse results: passed/failed counts; key failing tests.
+5) Output verdict JSON (PASS or FAIL + failures list) and add Linear comment.
+
+## Critical Rules
+- No selective test runs; run full suite.
+- Do not fix tests or change status; only report.
+- Language preservation in comment (EN/RU).
+
+## Definition of Done
+- Framework detected; command executed.
+- Results parsed; verdict produced with failing tests (if any).
+- Linear comment posted with summary.
+
+## Reference Files
+- Risk-based limits used downstream: `../ln-510-test-planner/references/risk_based_testing_guide.md`
+
+---
+**Version:** 3.1.0 (Added mandatory runbook.md reading before test execution)
+**Last Updated:** 2026-01-09

.claude/skills/security-auditor/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: ln-621-security-auditor
+description: Security audit worker (L3). Scans codebase for hardcoded secrets, SQL injection, XSS, insecure dependencies, missing input validation. Returns findings with severity (Critical/High/Medium/Low), location, effort, and recommendations.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Security Auditor (L3 Worker)
+
+Specialized worker auditing security vulnerabilities in codebase.
+
+## Purpose & Scope
+
+- **Worker in ln-620 coordinator pipeline** - invoked by ln-620-codebase-auditor
+- Audit codebase for **security vulnerabilities** (Category 1: Critical Priority)
+- Scan for hardcoded secrets, SQL injection, XSS, insecure dependencies, missing input validation
+- Return structured findings to coordinator with severity, location, effort, recommendations
+- Calculate compliance score (X/10) for Security category
+
+## Inputs (from Coordinator)
+
+**MANDATORY READ:** Load `shared/references/task_delegation_pattern.md#audit-coordinator--worker-contract` for contextStore structure.
+
+Receives `contextStore` with: `tech_stack`, `best_practices`, `principles`, `codebase_root`.
+
+## Workflow
+
+1) **Parse Context:** Extract tech stack, best practices, codebase root from contextStore
+2) **Scan Codebase:** Run security checks using Glob/Grep patterns (see Audit Rules below)
+3) **Collect Findings:** Record each violation with severity, location (file:line), effort estimate (S/M/L), recommendation
+4) **Calculate Score:** Count violations by severity, calculate compliance score (X/10)
+5) **Return Results:** Return JSON with category, score, findings to coordinator
+
+## Audit Rules (Priority: CRITICAL)
+
+### 1. Hardcoded Secrets
+**What:** API keys, passwords, tokens, private keys in source code
+
+**Detection:**
+- Search patterns: `API_KEY = "..."`, `password = "..."`, `token = "..."`, `SECRET = "..."`
+- File extensions: `.ts`, `.js`, `.py`, `.go`, `.java`, `.cs`
+- Exclude: `.env.example`, `README.md`, test files with mock data
+
+**Severity:**
+- **CRITICAL:** Production credentials (AWS keys, database passwords, API tokens)
+- **HIGH:** Development/staging credentials
+- **MEDIUM:** Test credentials in non-test files
+
+**Recommendation:** Move to environment variables (.env), use secret management (Vault, AWS Secrets Manager)
+
+**Effort:** S (replace hardcoded value with `process.env.VAR_NAME`)
+
+### 2. SQL Injection Patterns
+**What:** String concatenation in SQL queries instead of parameterized queries
+
+**Detection:**
+- Patterns: `query = "SELECT * FROM users WHERE id=" + userId`, `db.execute(f"SELECT * FROM {table}")`, `` `SELECT * FROM ${table}` ``
+- Languages: JavaScript, Python, PHP, Java
+
+**Severity:**
+- **CRITICAL:** User input directly concatenated without sanitization
+- **HIGH:** Variable concatenation in production code
+- **MEDIUM:** Concatenation with internal variables only
+
+**Recommendation:** Use parameterized queries (prepared statements), ORM query builders
+
+**Effort:** M (refactor query to use placeholders)
+
+### 3. XSS Vulnerabilities
+**What:** Unsanitized user input rendered in HTML/templates
+
+**Detection:**
+- Patterns: `innerHTML = userInput`, `dangerouslySetInnerHTML={{__html: data}}`, `echo $userInput;`
+- Template engines: Check for unescaped output (`{{ var | safe }}`, `<%- var %>`)
+
+**Severity:**
+- **CRITICAL:** User input directly inserted into DOM without sanitization
+- **HIGH:** User input with partial sanitization (insufficient escaping)
+- **MEDIUM:** Internal data with potential XSS if compromised
+
+**Recommendation:** Use framework escaping (React auto-escapes, use `textContent`), sanitize with DOMPurify
+
+**Effort:** S-M (replace `innerHTML` with `textContent` or sanitize)
+
+### 4. Insecure Dependencies
+**What:** Dependencies with known CVEs (Common Vulnerabilities and Exposures)
+
+**Detection:**
+- Run `npm audit` (Node.js), `pip-audit` (Python), `cargo audit` (Rust), `dotnet list package --vulnerable` (.NET)
+- Check for outdated critical dependencies
+
+**Severity:**
+- **CRITICAL:** CVE with exploitable vulnerability in production dependencies
+- **HIGH:** CVE in dev dependencies or lower severity production CVEs
+- **MEDIUM:** Outdated packages without known CVEs but security risk
+
+**Recommendation:** Update to patched versions, replace unmaintained packages
+
+**Effort:** S-M (update package.json, test), L (if breaking changes)
+
+### 5. Missing Input Validation
+**What:** Missing validation at system boundaries (API endpoints, user forms, file uploads)
+
+**Detection:**
+- API routes without validation middleware
+- Form handlers without input sanitization
+- File uploads without type/size checks
+- Missing CORS configuration
+
+**Severity:**
+- **CRITICAL:** File upload without validation, authentication bypass potential
+- **HIGH:** Missing validation on sensitive endpoints (payment, auth, user data)
+- **MEDIUM:** Missing validation on read-only or internal endpoints
+
+**Recommendation:** Add validation middleware (Joi, Yup, express-validator), implement input sanitization
+
+**Effort:** M (add validation schema and middleware)
+
+## Scoring Algorithm
+
+See `shared/references/audit_scoring.md` for unified formula and score interpretation.
+
+## Output Format
+
+**MANDATORY READ:** Load `shared/references/audit_output_schema.md` for JSON structure.
+
+Return JSON with `category: "Security"` and checks: hardcoded_secrets, sql_injection, xss_vulnerabilities, insecure_dependencies, missing_input_validation.
+
+## Critical Rules
+
+- **Do not auto-fix:** Report violations only; coordinator creates task for user to fix
+- **Tech stack aware:** Use contextStore to apply framework-specific patterns (e.g., React XSS vs PHP XSS)
+- **False positive reduction:** Exclude test files, example configs, documentation
+- **Effort realism:** S = <1 hour, M = 1-4 hours, L = >4 hours
+- **Location precision:** Always include `file:line` for programmatic navigation
+
+## Definition of Done
+
+- contextStore parsed successfully
+- All 5 security checks completed (secrets, SQL injection, XSS, deps, validation)
+- Findings collected with severity, location, effort, recommendation
+- Score calculated using penalty algorithm
+- JSON result returned to coordinator
+
+## Reference Files
+
+- **Audit scoring formula:** `shared/references/audit_scoring.md`
+- **Audit output schema:** `shared/references/audit_output_schema.md`
+- Security audit rules: [references/security_rules.md](references/security_rules.md)
+
+---
+**Version:** 3.0.0
+**Last Updated:** 2025-12-23

.claude/skills/sharp-edges/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: sharp-edges
+description: "Identifies error-prone APIs, dangerous configurations, and footgun designs that enable security mistakes. Use when reviewing API designs, configuration schemas, cryptographic library ergonomics, or evaluating whether code follows 'secure by default' and 'pit of success' principles. Triggers: footgun, misuse-resistant, secure defaults, API usability, dangerous configuration."
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+---
+
+# Sharp Edges Analysis
+
+Evaluates whether APIs, configurations, and interfaces are resistant to developer misuse. Identifies designs where the "easy path" leads to insecurity.
+
+## When to Use
+
+- Reviewing API or library design decisions
+- Auditing configuration schemas for dangerous options
+- Evaluating cryptographic API ergonomics
+- Assessing authentication/authorization interfaces
+- Reviewing any code that exposes security-relevant choices to developers
+
+## When NOT to Use
+
+- Implementation bugs (use standard code review)
+- Business logic flaws (use domain-specific analysis)
+- Performance optimization (different concern)
+
+## Core Principle
+
+**The pit of success**: Secure usage should be the path of least resistance. If developers must understand cryptography, read documentation carefully, or remember special rules to avoid vulnerabilities, the API has failed.
+
+## Rationalizations to Reject
+
+| Rationalization | Why It's Wrong | Required Action |
+|-----------------|----------------|-----------------|
+| "It's documented" | Developers don't read docs under deadline pressure | Make the secure choice the default or only option |
+| "Advanced users need flexibility" | Flexibility creates footguns; most "advanced" usage is copy-paste | Provide safe high-level APIs; hide primitives |
+| "It's the developer's responsibility" | Blame-shifting; you designed the footgun | Remove the footgun or make it impossible to misuse |
+| "Nobody would actually do that" | Developers do everything imaginable under pressure | Assume maximum developer confusion |
+| "It's just a configuration option" | Config is code; wrong configs ship to production | Validate configs; reject dangerous combinations |
+| "We need backwards compatibility" | Insecure defaults can't be grandfather-claused | Deprecate loudly; force migration |
+
+## Sharp Edge Categories
+
+### 1. Algorithm/Mode Selection Footguns
+
+APIs that let developers choose algorithms invite choosing wrong ones.
+
+**The JWT Pattern** (canonical example):
+- Header specifies algorithm: attacker can set `"alg": "none"` to bypass signatures
+- Algorithm confusion: RSA public key used as HMAC secret when switching RS256→HS256
+- Root cause: Letting untrusted input control security-critical decisions
+
+**Detection patterns:**
+- Function parameters like `algorithm`, `mode`, `cipher`, `hash_type`
+- Enums/strings selecting cryptographic primitives
+- Configuration options for security mechanisms
+
+**Example - PHP password_hash allowing weak algorithms:**
+```php
+// DANGEROUS: allows crc32, md5, sha1
+password_hash($password, PASSWORD_DEFAULT); // Good - no choice
+hash($algorithm, $password); // BAD: accepts "crc32"
+```
+
+### 2. Dangerous Defaults
+
+Defaults that are insecure, or zero/empty values that disable security.
+
+**The OTP Lifetime Pattern:**
+```python
+# What happens when lifetime=0?
+def verify_otp(code, lifetime=300):  # 300 seconds default
+    if lifetime == 0:
+        return True  # OOPS: 0 means "accept all"?
+        # Or does it mean "expired immediately"?
+```
+
+**Detection patterns:**
+- Timeouts/lifetimes that accept 0 (infinite? immediate expiry?)
+- Empty strings that bypass checks
+- Null values that skip validation
+- Boolean defaults that disable security features
+- Negative values with undefined semantics
+
+**Questions to ask:**
+- What happens with `timeout=0`? `max_attempts=0`? `key=""`?
+- Is the default the most secure option?
+- Can any default value disable security entirely?
+
+### 3. Primitive vs. Semantic APIs
+
+APIs that expose raw bytes instead of meaningful types invite type confusion.
+
+**The Libsodium vs. Halite Pattern:**
+
+```php
+// Libsodium (primitives): bytes are bytes
+sodium_crypto_box($message, $nonce, $keypair);
+// Easy to: swap nonce/keypair, reuse nonces, use wrong key type
+
+// Halite (semantic): types enforce correct usage
+Crypto::seal($message, new EncryptionPublicKey($key));
+// Wrong key type = type error, not silent failure
+```
+
+**Detection patterns:**
+- Functions taking `bytes`, `string`, `[]byte` for distinct security concepts
+- Parameters that could be swapped without type errors
+- Same type used for keys, nonces, ciphertexts, signatures
+
+**The comparison footgun:**
+```go
+// Timing-safe comparison looks identical to unsafe
+if hmac == expected { }           // BAD: timing attack
+if hmac.Equal(mac, expected) { }  // Good: constant-time
+// Same types, different security properties
+```
+
+### 4. Configuration Cliffs
+
+One wrong setting creates catastrophic failure, with no warning.
+
+**Detection patterns:**
+- Boolean flags that disable security entirely
+- String configs that aren't validated
+- Combinations of settings that interact dangerously
+- Environment variables that override security settings
+- Constructor parameters with sensible defaults but no validation (callers can override with insecure values)
+
+**Examples:**
+```yaml
+# One typo = disaster
+verify_ssl: fasle  # Typo silently accepted as truthy?
+
+# Magic values
+session_timeout: -1  # Does this mean "never expire"?
+
+# Dangerous combinations accepted silently
+auth_required: true
+bypass_auth_for_health_checks: true
+health_check_path: "/"  # Oops
+```
+
+```php
+// Sensible default doesn't protect against bad callers
+public function __construct(
+    public string $hashAlgo = 'sha256',  // Good default...
+    public int $otpLifetime = 120,       // ...but accepts md5, 0, etc.
+) {}
+```
+
+See [config-patterns.md](references/config-patterns.md#unvalidated-constructor-parameters) for detailed patterns.
+
+### 5. Silent Failures
+
+Errors that don't surface, or success that masks failure.
+
+**Detection patterns:**
+- Functions returning booleans instead of throwing on security failures
+- Empty catch blocks around security operations
+- Default values substituted on parse errors
+- Verification functions that "succeed" on malformed input
+
+**Examples:**
+```python
+# Silent bypass
+def verify_signature(sig, data, key):
+    if not key:
+        return True  # No key = skip verification?!
+
+# Return value ignored
+signature.verify(data, sig)  # Throws on failure
+crypto.verify(data, sig)     # Returns False on failure
+# Developer forgets to check return value
+```
+
+### 6. Stringly-Typed Security
+
+Security-critical values as plain strings enable injection and confusion.
+
+**Detection patterns:**
+- SQL/commands built from string concatenation
+- Permissions as comma-separated strings
+- Roles/scopes as arbitrary strings instead of enums
+- URLs constructed by joining strings
+
+**The permission accumulation footgun:**
+```python
+permissions = "read,write"
+permissions += ",admin"  # Too easy to escalate
+
+# vs. type-safe
+permissions = {Permission.READ, Permission.WRITE}
+permissions.add(Permission.ADMIN)  # At least it's explicit
+```
+
+## Analysis Workflow
+
+### Phase 1: Surface Identification
+
+1. **Map security-relevant APIs**: authentication, authorization, cryptography, session management, input validation
+2. **Identify developer choice points**: Where can developers select algorithms, configure timeouts, choose modes?
+3. **Find configuration schemas**: Environment variables, config files, constructor parameters
+
+### Phase 2: Edge Case Probing
+
+For each choice point, ask:
+- **Zero/empty/null**: What happens with `0`, `""`, `null`, `[]`?
+- **Negative values**: What does `-1` mean? Infinite? Error?
+- **Type confusion**: Can different security concepts be swapped?
+- **Default values**: Is the default secure? Is it documented?
+- **Error paths**: What happens on invalid input? Silent acceptance?
+
+### Phase 3: Threat Modeling
+
+Consider three adversaries:
+
+1. **The Scoundrel**: Actively malicious developer or attacker controlling config
+   - Can they disable security via configuration?
+   - Can they downgrade algorithms?
+   - Can they inject malicious values?
+
+2. **The Lazy Developer**: Copy-pastes examples, skips documentation
+   - Will the first example they find be secure?
+   - Is the path of least resistance secure?
+   - Do error messages guide toward secure usage?
+
+3. **The Confused Developer**: Misunderstands the API
+   - Can they swap parameters without type errors?
+   - Can they use the wrong key/algorithm/mode by accident?
+   - Are failure modes obvious or silent?
+
+### Phase 4: Validate Findings
+
+For each identified sharp edge:
+
+1. **Reproduce the misuse**: Write minimal code demonstrating the footgun
+2. **Verify exploitability**: Does the misuse create a real vulnerability?
+3. **Check documentation**: Is the danger documented? (Documentation doesn't excuse bad design, but affects severity)
+4. **Test mitigations**: Can the API be used safely with reasonable effort?
+
+If a finding seems questionable, return to Phase 2 and probe more edge cases.
+
+## Severity Classification
+
+| Severity | Criteria | Examples |
+|----------|----------|----------|
+| Critical | Default or obvious usage is insecure | `verify: false` default; empty password allowed |
+| High | Easy misconfiguration breaks security | Algorithm parameter accepts "none" |
+| Medium | Unusual but possible misconfiguration | Negative timeout has unexpected meaning |
+| Low | Requires deliberate misuse | Obscure parameter combination |
+
+## References
+
+**By category:**
+
+- **Cryptographic APIs**: See [references/crypto-apis.md](references/crypto-apis.md)
+- **Configuration Patterns**: See [references/config-patterns.md](references/config-patterns.md)
+- **Authentication/Session**: See [references/auth-patterns.md](references/auth-patterns.md)
+- **Real-World Case Studies**: See [references/case-studies.md](references/case-studies.md) (OpenSSL, GMP, etc.)
+
+**By language** (general footguns, not crypto-specific):
+
+| Language | Guide |
+|----------|-------|
+| C/C++ | [references/lang-c.md](references/lang-c.md) |
+| Go | [references/lang-go.md](references/lang-go.md) |
+| Rust | [references/lang-rust.md](references/lang-rust.md) |
+| Swift | [references/lang-swift.md](references/lang-swift.md) |
+| Java | [references/lang-java.md](references/lang-java.md) |
+| Kotlin | [references/lang-kotlin.md](references/lang-kotlin.md) |
+| C# | [references/lang-csharp.md](references/lang-csharp.md) |
+| PHP | [references/lang-php.md](references/lang-php.md) |
+| JavaScript/TypeScript | [references/lang-javascript.md](references/lang-javascript.md) |
+| Python | [references/lang-python.md](references/lang-python.md) |
+| Ruby | [references/lang-ruby.md](references/lang-ruby.md) |
+
+See also [references/language-specific.md](references/language-specific.md) for a combined quick reference.
+
+## Quality Checklist
+
+Before concluding analysis:
+
+- [ ] Probed all zero/empty/null edge cases
+- [ ] Verified defaults are secure
+- [ ] Checked for algorithm/mode selection footguns
+- [ ] Tested type confusion between security concepts
+- [ ] Considered all three adversary types
+- [ ] Verified error paths don't bypass security
+- [ ] Checked configuration validation
+- [ ] Constructor params validated (not just defaulted) - see [config-patterns.md](references/config-patterns.md#unvalidated-constructor-parameters)

.claude/skills/static-analysis/codeql/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: codeql
+description: >-
+  Runs CodeQL static analysis for security vulnerability detection
+  using interprocedural data flow and taint tracking. Applicable when
+  finding vulnerabilities, running a security scan, performing a security
+  audit, running CodeQL, building a CodeQL database, selecting query
+  rulesets, creating data extension models, or processing CodeQL SARIF
+  output. NOT for writing custom QL queries or CI/CD pipeline setup.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Task
+  - TaskCreate
+  - TaskList
+  - TaskUpdate
+---
+
+# CodeQL Analysis
+
+Supported languages: Python, JavaScript/TypeScript, Go, Java/Kotlin, C/C++, C#, Ruby, Swift.
+
+**Skill resources:** Reference files and templates are located at `{baseDir}/references/` and `{baseDir}/workflows/`. Use `{baseDir}` to resolve paths to these files at runtime.
+
+## Quick Start
+
+For the common case ("scan this codebase for vulnerabilities"):
+
+```bash
+# 1. Verify CodeQL is installed
+command -v codeql >/dev/null 2>&1 && codeql --version || echo "NOT INSTALLED"
+
+# 2. Check for existing database
+ls -dt codeql_*.db 2>/dev/null | head -1
+```
+
+Then execute the full pipeline: **build database → create data extensions → run analysis** using the workflows below.
+
+## When to Use
+
+- Scanning a codebase for security vulnerabilities with deep data flow analysis
+- Building a CodeQL database from source code (with build capability for compiled languages)
+- Finding complex vulnerabilities that require interprocedural taint tracking or AST/CFG analysis
+- Performing comprehensive security audits with multiple query packs
+
+## When NOT to Use
+
+- **Writing custom queries** - Use a dedicated query development skill
+- **CI/CD integration** - Use GitHub Actions documentation directly
+- **Quick pattern searches** - Use Semgrep or grep for speed
+- **No build capability** for compiled languages - Consider Semgrep instead
+- **Single-file or lightweight analysis** - Semgrep is faster for simple pattern matching
+
+## Rationalizations to Reject
+
+These shortcuts lead to missed findings. Do not accept them:
+
+- **"security-extended is enough"** - It is the baseline. Always check if Trail of Bits packs and Community Packs are available for the language. They catch categories `security-extended` misses entirely.
+- **"The database built, so it's good"** - A database that builds does not mean it extracted well. Always run Step 4 (quality assessment) and check file counts against expected source files. A cached build produces zero useful extraction.
+- **"Data extensions aren't needed for standard frameworks"** - Even Django/Spring apps have custom wrappers around ORM calls, request parsing, or shell execution that CodeQL does not model. Skipping the extensions workflow means missing vulnerabilities in project-specific code.
+- **"build-mode=none is fine for compiled languages"** - It produces severely incomplete analysis. No interprocedural data flow through compiled code is traced. Only use as an absolute last resort and clearly flag the limitation.
+- **"No findings means the code is secure"** - Zero findings can indicate poor database quality, missing models, or wrong query packs. Investigate before reporting clean results.
+- **"I'll just run the default suite"** - The default suite varies by how CodeQL is invoked. Always explicitly specify the suite (e.g., `security-extended`) so results are reproducible.
+
+---
+
+## Workflow Selection
+
+This skill has three workflows:
+
+| Workflow | Purpose |
+|----------|---------|
+| [build-database](workflows/build-database.md) | Create CodeQL database using 3 build methods in sequence |
+| [create-data-extensions](workflows/create-data-extensions.md) | Detect or generate data extension models for project APIs |
+| [run-analysis](workflows/run-analysis.md) | Select rulesets, execute queries, process results |
+
+
+### Auto-Detection Logic
+
+**If user explicitly specifies** what to do (e.g., "build a database", "run analysis"), execute that workflow.
+
+**Default pipeline for "test", "scan", "analyze", or similar:** Execute all three workflows sequentially: build → extensions → analysis. The create-data-extensions step is critical for finding vulnerabilities in projects with custom frameworks or annotations that CodeQL doesn't model by default.
+
+```bash
+# Check if database exists
+DB=$(ls -dt codeql_*.db 2>/dev/null | head -1)
+if [ -n "$DB" ] && codeql resolve database -- "$DB" >/dev/null 2>&1; then
+  echo "DATABASE EXISTS ($DB) - can run analysis"
+else
+  echo "NO DATABASE - need to build first"
+fi
+```
+
+| Condition | Action |
+|-----------|--------|
+| No database exists | Execute build → extensions → analysis (full pipeline) |
+| Database exists, no extensions | Execute extensions → analysis |
+| Database exists, extensions exist | Ask user: run analysis on existing DB, or rebuild? |
+| User says "just run analysis" or "skip extensions" | Run analysis only |
+
+
+### Decision Prompt
+
+If unclear, ask user:
+
+```
+I can help with CodeQL analysis. What would you like to do?
+
+1. **Full scan (Recommended)** - Build database, create extensions, then run analysis
+2. **Build database** - Create a new CodeQL database from this codebase
+3. **Create data extensions** - Generate custom source/sink models for project APIs
+4. **Run analysis** - Run security queries on existing database
+
+[If database exists: "I found an existing database at <DB_NAME>"]
+```

.claude/skills/static-analysis/sarif-parsing/SKILL.md

@@ -0,0 +1,479 @@
+---
+name: sarif-parsing
+description: Parse, analyze, and process SARIF (Static Analysis Results Interchange Format) files. Use when reading security scan results, aggregating findings from multiple tools, deduplicating alerts, extracting specific vulnerabilities, or integrating SARIF data into CI/CD pipelines.
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+---
+
+# SARIF Parsing Best Practices
+
+You are a SARIF parsing expert. Your role is to help users effectively read, analyze, and process SARIF files from static analysis tools.
+
+## When to Use
+
+Use this skill when:
+- Reading or interpreting static analysis scan results in SARIF format
+- Aggregating findings from multiple security tools
+- Deduplicating or filtering security alerts
+- Extracting specific vulnerabilities from SARIF files
+- Integrating SARIF data into CI/CD pipelines
+- Converting SARIF output to other formats
+
+## When NOT to Use
+
+Do NOT use this skill for:
+- Running static analysis scans (use CodeQL or Semgrep skills instead)
+- Writing CodeQL or Semgrep rules (use their respective skills)
+- Analyzing source code directly (SARIF is for processing existing scan results)
+- Triaging findings without SARIF input (use variant-analysis or audit skills)
+
+## SARIF Structure Overview
+
+SARIF 2.1.0 is the current OASIS standard. Every SARIF file has this hierarchical structure:
+
+```
+sarifLog
+├── version: "2.1.0"
+├── $schema: (optional, enables IDE validation)
+└── runs[] (array of analysis runs)
+    ├── tool
+    │   ├── driver
+    │   │   ├── name (required)
+    │   │   ├── version
+    │   │   └── rules[] (rule definitions)
+    │   └── extensions[] (plugins)
+    ├── results[] (findings)
+    │   ├── ruleId
+    │   ├── level (error/warning/note)
+    │   ├── message.text
+    │   ├── locations[]
+    │   │   └── physicalLocation
+    │   │       ├── artifactLocation.uri
+    │   │       └── region (startLine, startColumn, etc.)
+    │   ├── fingerprints{}
+    │   └── partialFingerprints{}
+    └── artifacts[] (scanned files metadata)
+```
+
+### Why Fingerprinting Matters
+
+Without stable fingerprints, you can't track findings across runs:
+
+- **Baseline comparison**: "Is this a new finding or did we see it before?"
+- **Regression detection**: "Did this PR introduce new vulnerabilities?"
+- **Suppression**: "Ignore this known false positive in future runs"
+
+Tools report different paths (`/path/to/project/` vs `/github/workspace/`), so path-based matching fails. Fingerprints hash the *content* (code snippet, rule ID, relative location) to create stable identifiers regardless of environment.
+
+## Tool Selection Guide
+
+| Use Case | Tool | Installation |
+|----------|------|--------------|
+| Quick CLI queries | jq | `brew install jq` / `apt install jq` |
+| Python scripting (simple) | pysarif | `pip install pysarif` |
+| Python scripting (advanced) | sarif-tools | `pip install sarif-tools` |
+| .NET applications | SARIF SDK | NuGet package |
+| JavaScript/Node.js | sarif-js | npm package |
+| Go applications | garif | `go get github.com/chavacava/garif` |
+| Validation | SARIF Validator | sarifweb.azurewebsites.net |
+
+## Strategy 1: Quick Analysis with jq
+
+For rapid exploration and one-off queries:
+
+```bash
+# Pretty print the file
+jq '.' results.sarif
+
+# Count total findings
+jq '[.runs[].results[]] | length' results.sarif
+
+# List all rule IDs triggered
+jq '[.runs[].results[].ruleId] | unique' results.sarif
+
+# Extract errors only
+jq '.runs[].results[] | select(.level == "error")' results.sarif
+
+# Get findings with file locations
+jq '.runs[].results[] | {
+  rule: .ruleId,
+  message: .message.text,
+  file: .locations[0].physicalLocation.artifactLocation.uri,
+  line: .locations[0].physicalLocation.region.startLine
+}' results.sarif
+
+# Filter by severity and get count per rule
+jq '[.runs[].results[] | select(.level == "error")] | group_by(.ruleId) | map({rule: .[0].ruleId, count: length})' results.sarif
+
+# Extract findings for a specific file
+jq --arg file "src/auth.py" '.runs[].results[] | select(.locations[].physicalLocation.artifactLocation.uri | contains($file))' results.sarif
+```
+
+## Strategy 2: Python with pysarif
+
+For programmatic access with full object model:
+
+```python
+from pysarif import load_from_file, save_to_file
+
+# Load SARIF file
+sarif = load_from_file("results.sarif")
+
+# Iterate through runs and results
+for run in sarif.runs:
+    tool_name = run.tool.driver.name
+    print(f"Tool: {tool_name}")
+
+    for result in run.results:
+        print(f"  [{result.level}] {result.rule_id}: {result.message.text}")
+
+        if result.locations:
+            loc = result.locations[0].physical_location
+            if loc and loc.artifact_location:
+                print(f"    File: {loc.artifact_location.uri}")
+                if loc.region:
+                    print(f"    Line: {loc.region.start_line}")
+
+# Save modified SARIF
+save_to_file(sarif, "modified.sarif")
+```
+
+## Strategy 3: Python with sarif-tools
+
+For aggregation, reporting, and CI/CD integration:
+
+```python
+from sarif import loader
+
+# Load single file
+sarif_data = loader.load_sarif_file("results.sarif")
+
+# Or load multiple files
+sarif_set = loader.load_sarif_files(["tool1.sarif", "tool2.sarif"])
+
+# Get summary report
+report = sarif_data.get_report()
+
+# Get histogram by severity
+errors = report.get_issue_type_histogram_for_severity("error")
+warnings = report.get_issue_type_histogram_for_severity("warning")
+
+# Filter results
+high_severity = [r for r in sarif_data.get_results()
+                 if r.get("level") == "error"]
+```
+
+**sarif-tools CLI commands:**
+
+```bash
+# Summary of findings
+sarif summary results.sarif
+
+# List all results with details
+sarif ls results.sarif
+
+# Get results by severity
+sarif ls --level error results.sarif
+
+# Diff two SARIF files (find new/fixed issues)
+sarif diff baseline.sarif current.sarif
+
+# Convert to other formats
+sarif csv results.sarif > results.csv
+sarif html results.sarif > report.html
+```
+
+## Strategy 4: Aggregating Multiple SARIF Files
+
+When combining results from multiple tools:
+
+```python
+import json
+from pathlib import Path
+
+def aggregate_sarif_files(sarif_paths: list[str]) -> dict:
+    """Combine multiple SARIF files into one."""
+    aggregated = {
+        "version": "2.1.0",
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "runs": []
+    }
+
+    for path in sarif_paths:
+        with open(path) as f:
+            sarif = json.load(f)
+            aggregated["runs"].extend(sarif.get("runs", []))
+
+    return aggregated
+
+def deduplicate_results(sarif: dict) -> dict:
+    """Remove duplicate findings based on fingerprints."""
+    seen_fingerprints = set()
+
+    for run in sarif["runs"]:
+        unique_results = []
+        for result in run.get("results", []):
+            # Use partialFingerprints or create key from location
+            fp = None
+            if result.get("partialFingerprints"):
+                fp = tuple(sorted(result["partialFingerprints"].items()))
+            elif result.get("fingerprints"):
+                fp = tuple(sorted(result["fingerprints"].items()))
+            else:
+                # Fallback: create fingerprint from rule + location
+                loc = result.get("locations", [{}])[0]
+                phys = loc.get("physicalLocation", {})
+                fp = (
+                    result.get("ruleId"),
+                    phys.get("artifactLocation", {}).get("uri"),
+                    phys.get("region", {}).get("startLine")
+                )
+
+            if fp not in seen_fingerprints:
+                seen_fingerprints.add(fp)
+                unique_results.append(result)
+
+        run["results"] = unique_results
+
+    return sarif
+```
+
+## Strategy 5: Extracting Actionable Data
+
+```python
+import json
+from dataclasses import dataclass
+from typing import Optional
+
+@dataclass
+class Finding:
+    rule_id: str
+    level: str
+    message: str
+    file_path: Optional[str]
+    start_line: Optional[int]
+    end_line: Optional[int]
+    fingerprint: Optional[str]
+
+def extract_findings(sarif_path: str) -> list[Finding]:
+    """Extract structured findings from SARIF file."""
+    with open(sarif_path) as f:
+        sarif = json.load(f)
+
+    findings = []
+    for run in sarif.get("runs", []):
+        for result in run.get("results", []):
+            loc = result.get("locations", [{}])[0]
+            phys = loc.get("physicalLocation", {})
+            region = phys.get("region", {})
+
+            findings.append(Finding(
+                rule_id=result.get("ruleId", "unknown"),
+                level=result.get("level", "warning"),
+                message=result.get("message", {}).get("text", ""),
+                file_path=phys.get("artifactLocation", {}).get("uri"),
+                start_line=region.get("startLine"),
+                end_line=region.get("endLine"),
+                fingerprint=next(iter(result.get("partialFingerprints", {}).values()), None)
+            ))
+
+    return findings
+
+# Filter and prioritize
+def prioritize_findings(findings: list[Finding]) -> list[Finding]:
+    """Sort findings by severity."""
+    severity_order = {"error": 0, "warning": 1, "note": 2, "none": 3}
+    return sorted(findings, key=lambda f: severity_order.get(f.level, 99))
+```
+
+## Common Pitfalls and Solutions
+
+### 1. Path Normalization Issues
+
+Different tools report paths differently (absolute, relative, URI-encoded):
+
+```python
+from urllib.parse import unquote
+from pathlib import Path
+
+def normalize_path(uri: str, base_path: str = "") -> str:
+    """Normalize SARIF artifact URI to consistent path."""
+    # Remove file:// prefix if present
+    if uri.startswith("file://"):
+        uri = uri[7:]
+
+    # URL decode
+    uri = unquote(uri)
+
+    # Handle relative paths
+    if not Path(uri).is_absolute() and base_path:
+        uri = str(Path(base_path) / uri)
+
+    # Normalize separators
+    return str(Path(uri))
+```
+
+### 2. Fingerprint Mismatch Across Runs
+
+Fingerprints may not match if:
+- File paths differ between environments
+- Tool versions changed fingerprinting algorithm
+- Code was reformatted (changing line numbers)
+
+**Solution:** Use multiple fingerprint strategies:
+
+```python
+def compute_stable_fingerprint(result: dict, file_content: str = None) -> str:
+    """Compute environment-independent fingerprint."""
+    import hashlib
+
+    components = [
+        result.get("ruleId", ""),
+        result.get("message", {}).get("text", "")[:100],  # First 100 chars
+    ]
+
+    # Add code snippet if available
+    if file_content and result.get("locations"):
+        region = result["locations"][0].get("physicalLocation", {}).get("region", {})
+        if region.get("startLine"):
+            lines = file_content.split("\n")
+            line_idx = region["startLine"] - 1
+            if 0 <= line_idx < len(lines):
+                # Normalize whitespace
+                components.append(lines[line_idx].strip())
+
+    return hashlib.sha256("".join(components).encode()).hexdigest()[:16]
+```
+
+### 3. Missing or Incomplete Data
+
+SARIF allows many optional fields. Always use defensive access:
+
+```python
+def safe_get_location(result: dict) -> tuple[str, int]:
+    """Safely extract file and line from result."""
+    try:
+        loc = result.get("locations", [{}])[0]
+        phys = loc.get("physicalLocation", {})
+        file_path = phys.get("artifactLocation", {}).get("uri", "unknown")
+        line = phys.get("region", {}).get("startLine", 0)
+        return file_path, line
+    except (IndexError, KeyError, TypeError):
+        return "unknown", 0
+```
+
+### 4. Large File Performance
+
+For very large SARIF files (100MB+):
+
+```python
+import ijson  # pip install ijson
+
+def stream_results(sarif_path: str):
+    """Stream results without loading entire file."""
+    with open(sarif_path, "rb") as f:
+        # Stream through results arrays
+        for result in ijson.items(f, "runs.item.results.item"):
+            yield result
+```
+
+### 5. Schema Validation
+
+Validate before processing to catch malformed files:
+
+```bash
+# Using ajv-cli
+npm install -g ajv-cli
+ajv validate -s sarif-schema-2.1.0.json -d results.sarif
+
+# Using Python jsonschema
+pip install jsonschema
+```
+
+```python
+from jsonschema import validate, ValidationError
+import json
+
+def validate_sarif(sarif_path: str, schema_path: str) -> bool:
+    """Validate SARIF file against schema."""
+    with open(sarif_path) as f:
+        sarif = json.load(f)
+    with open(schema_path) as f:
+        schema = json.load(f)
+
+    try:
+        validate(sarif, schema)
+        return True
+    except ValidationError as e:
+        print(f"Validation error: {e.message}")
+        return False
+```
+
+## CI/CD Integration Patterns
+
+### GitHub Actions
+
+```yaml
+- name: Upload SARIF
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: results.sarif
+
+- name: Check for high severity
+  run: |
+    HIGH_COUNT=$(jq '[.runs[].results[] | select(.level == "error")] | length' results.sarif)
+    if [ "$HIGH_COUNT" -gt 0 ]; then
+      echo "Found $HIGH_COUNT high severity issues"
+      exit 1
+    fi
+```
+
+### Fail on New Issues
+
+```python
+from sarif import loader
+
+def check_for_regressions(baseline: str, current: str) -> int:
+    """Return count of new issues not in baseline."""
+    baseline_data = loader.load_sarif_file(baseline)
+    current_data = loader.load_sarif_file(current)
+
+    baseline_fps = {get_fingerprint(r) for r in baseline_data.get_results()}
+    new_issues = [r for r in current_data.get_results()
+                  if get_fingerprint(r) not in baseline_fps]
+
+    return len(new_issues)
+```
+
+## Key Principles
+
+1. **Validate first**: Check SARIF structure before processing
+2. **Handle optionals**: Many fields are optional; use defensive access
+3. **Normalize paths**: Tools report paths differently; normalize early
+4. **Fingerprint wisely**: Combine multiple strategies for stable deduplication
+5. **Stream large files**: Use ijson or similar for 100MB+ files
+6. **Aggregate thoughtfully**: Preserve tool metadata when combining files
+
+## Skill Resources
+
+For ready-to-use query templates, see [{baseDir}/resources/jq-queries.md]({baseDir}/resources/jq-queries.md):
+- 40+ jq queries for common SARIF operations
+- Severity filtering, rule extraction, aggregation patterns
+
+For Python utilities, see [{baseDir}/resources/sarif_helpers.py]({baseDir}/resources/sarif_helpers.py):
+- `normalize_path()` - Handle tool-specific path formats
+- `compute_fingerprint()` - Stable fingerprinting ignoring paths
+- `deduplicate_results()` - Remove duplicates across runs
+
+## Reference Links
+
+- [OASIS SARIF 2.1.0 Specification](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html)
+- [Microsoft SARIF Tutorials](https://github.com/microsoft/sarif-tutorials)
+- [SARIF SDK (.NET)](https://github.com/microsoft/sarif-sdk)
+- [sarif-tools (Python)](https://github.com/microsoft/sarif-tools)
+- [pysarif (Python)](https://github.com/Kjeld-P/pysarif)
+- [GitHub SARIF Support](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning)
+- [SARIF Validator](https://sarifweb.azurewebsites.net/)

.claude/skills/static-analysis/semgrep/SKILL.md

@@ -0,0 +1,417 @@
+---
+name: semgrep
+description: Run Semgrep static analysis scan on a codebase using parallel subagents. Automatically
+  detects and uses Semgrep Pro for cross-file analysis when available. Use when asked to scan
+  code for vulnerabilities, run a security audit with Semgrep, find bugs, or perform
+  static analysis. Spawns parallel workers for multi-language codebases and triage.
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+  - Write
+  - Task
+  - AskUserQuestion
+  - TaskCreate
+  - TaskList
+  - TaskUpdate
+  - WebFetch
+---
+
+# Semgrep Security Scan
+
+Run a complete Semgrep scan with automatic language detection, parallel execution via Task subagents, and parallel triage. Automatically uses Semgrep Pro for cross-file taint analysis when available.
+
+## Prerequisites
+
+**Required:** Semgrep CLI
+
+```bash
+semgrep --version
+```
+
+If not installed, see [Semgrep installation docs](https://semgrep.dev/docs/getting-started/).
+
+**Optional:** Semgrep Pro (for cross-file analysis and Pro languages)
+
+```bash
+# Check if Semgrep Pro engine is installed
+semgrep --pro --validate --config p/default 2>/dev/null && echo "Pro available" || echo "OSS only"
+
+# If logged in, install/update Pro Engine
+semgrep install-semgrep-pro
+```
+
+Pro enables: cross-file taint tracking, inter-procedural analysis, and additional languages (Apex, C#, Elixir).
+
+## When to Use
+
+- Security audit of a codebase
+- Finding vulnerabilities before code review
+- Scanning for known bug patterns
+- First-pass static analysis
+
+## When NOT to Use
+
+- Binary analysis → Use binary analysis tools
+- Already have Semgrep CI configured → Use existing pipeline
+- Need cross-file analysis but no Pro license → Consider CodeQL as alternative
+- Creating custom Semgrep rules → Use `semgrep-rule-creator` skill
+- Porting existing rules to other languages → Use `semgrep-rule-variant-creator` skill
+
+---
+
+## Orchestration Architecture
+
+This skill uses **parallel Task subagents** for maximum efficiency:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ MAIN AGENT                                                      │
+│ 1. Detect languages + check Pro availability                    │
+│ 2. Select rulesets based on detection (ref: rulesets.md)        │
+│ 3. Present plan + rulesets, get approval [⛔ HARD GATE]         │
+│ 4. Spawn parallel scan Tasks (with approved rulesets)           │
+│ 5. Spawn parallel triage Tasks                                  │
+│ 6. Collect and report results                                   │
+└─────────────────────────────────────────────────────────────────┘
+          │ Step 4                           │ Step 5
+          ▼                                  ▼
+┌─────────────────┐              ┌─────────────────┐
+│ Scan Tasks      │              │ Triage Tasks    │
+│ (parallel)      │              │ (parallel)      │
+├─────────────────┤              ├─────────────────┤
+│ Python scanner  │              │ Python triager  │
+│ JS/TS scanner   │              │ JS/TS triager   │
+│ Go scanner      │              │ Go triager      │
+│ Docker scanner  │              │ Docker triager  │
+└─────────────────┘              └─────────────────┘
+```
+
+---
+
+## Workflow Enforcement via Task System
+
+This skill uses the **Task system** to enforce workflow compliance. On invocation, create these tasks:
+
+```
+TaskCreate: "Detect languages and Pro availability" (Step 1)
+TaskCreate: "Select rulesets based on detection" (Step 2) - blockedBy: Step 1
+TaskCreate: "Present plan with rulesets, get approval" (Step 3) - blockedBy: Step 2
+TaskCreate: "Execute scans with approved rulesets" (Step 4) - blockedBy: Step 3
+TaskCreate: "Triage findings" (Step 5) - blockedBy: Step 4
+TaskCreate: "Report results" (Step 6) - blockedBy: Step 5
+```
+
+### Mandatory Gates
+
+| Task | Gate Type | Cannot Proceed Until |
+|------|-----------|---------------------|
+| Step 3: Get approval | **HARD GATE** | User explicitly approves rulesets + plan |
+| Step 5: Triage | **SOFT GATE** | All scan JSON files exist |
+
+**Step 3 is a HARD GATE**: Mark as `completed` ONLY after user says "yes", "proceed", "approved", or equivalent.
+
+### Task Flow Example
+
+```
+1. Create all 6 tasks with dependencies
+2. TaskUpdate Step 1 → in_progress, execute detection
+3. TaskUpdate Step 1 → completed
+4. TaskUpdate Step 2 → in_progress, select rulesets
+5. TaskUpdate Step 2 → completed
+6. TaskUpdate Step 3 → in_progress, present plan with rulesets
+7. STOP: Wait for user response (may modify rulesets)
+8. User approves → TaskUpdate Step 3 → completed
+9. TaskUpdate Step 4 → in_progress (now unblocked)
+... continue workflow
+```
+
+---
+
+## Workflow
+
+### Step 1: Detect Languages and Pro Availability (Main Agent)
+
+```bash
+# Check if Semgrep Pro is available (non-destructive check)
+SEMGREP_PRO=false
+if semgrep --pro --validate --config p/default 2>/dev/null; then
+  SEMGREP_PRO=true
+  echo "Semgrep Pro: AVAILABLE (cross-file analysis enabled)"
+else
+  echo "Semgrep Pro: NOT AVAILABLE (OSS mode, single-file analysis)"
+fi
+
+# Find languages by file extension
+fd -t f -e py -e js -e ts -e jsx -e tsx -e go -e rb -e java -e php -e c -e cpp -e rs | \
+  sed 's/.*\.//' | sort | uniq -c | sort -rn
+
+# Check for frameworks/technologies
+ls -la package.json pyproject.toml Gemfile go.mod Cargo.toml pom.xml 2>/dev/null
+fd -t f "Dockerfile" "docker-compose" ".tf" "*.yaml" "*.yml" | head -20
+```
+
+Map findings to categories:
+
+| Detection | Category |
+|-----------|----------|
+| `.py`, `pyproject.toml` | Python |
+| `.js`, `.ts`, `package.json` | JavaScript/TypeScript |
+| `.go`, `go.mod` | Go |
+| `.rb`, `Gemfile` | Ruby |
+| `.java`, `pom.xml` | Java |
+| `.php` | PHP |
+| `.c`, `.cpp` | C/C++ |
+| `.rs`, `Cargo.toml` | Rust |
+| `Dockerfile` | Docker |
+| `.tf` | Terraform |
+| k8s manifests | Kubernetes |
+
+### Step 2: Select Rulesets Based on Detection
+
+Using the detected languages and frameworks from Step 1, select rulesets by following the **Ruleset Selection Algorithm** in [rulesets.md]({baseDir}/references/rulesets.md).
+
+The algorithm covers:
+1. Security baseline (always included)
+2. Language-specific rulesets
+3. Framework rulesets (if detected)
+4. Infrastructure rulesets
+5. **Required** third-party rulesets (Trail of Bits, 0xdea, Decurity - NOT optional)
+6. Registry verification
+
+**Output:** Structured JSON passed to Step 3 for user review:
+
+```json
+{
+  "baseline": ["p/security-audit", "p/secrets"],
+  "python": ["p/python", "p/django"],
+  "javascript": ["p/javascript", "p/react", "p/nodejs"],
+  "docker": ["p/dockerfile"],
+  "third_party": ["https://github.com/trailofbits/semgrep-rules"]
+}
+```
+
+### Step 3: CRITICAL GATE - Present Plan and Get Approval
+
+> **⛔ MANDATORY CHECKPOINT - DO NOT SKIP**
+>
+> This step requires explicit user approval before proceeding.
+> User may modify rulesets before approving.
+
+Present plan to user with **explicit ruleset listing**:
+
+```
+## Semgrep Scan Plan
+
+**Target:** /path/to/codebase
+**Output directory:** ./semgrep-results-001/
+**Engine:** Semgrep Pro (cross-file analysis) | Semgrep OSS (single-file)
+
+### Detected Languages/Technologies:
+- Python (1,234 files) - Django framework detected
+- JavaScript (567 files) - React detected
+- Dockerfile (3 files)
+
+### Rulesets to Run:
+
+**Security Baseline (always included):**
+- [x] `p/security-audit` - Comprehensive security rules
+- [x] `p/secrets` - Hardcoded credentials, API keys
+
+**Python (1,234 files):**
+- [x] `p/python` - Python security patterns
+- [x] `p/django` - Django-specific vulnerabilities
+
+**JavaScript (567 files):**
+- [x] `p/javascript` - JavaScript security patterns
+- [x] `p/react` - React-specific issues
+- [x] `p/nodejs` - Node.js server-side patterns
+
+**Docker (3 files):**
+- [x] `p/dockerfile` - Dockerfile best practices
+
+**Third-party (auto-included for detected languages):**
+- [x] Trail of Bits rules - https://github.com/trailofbits/semgrep-rules
+
+**Available but not selected:**
+- [ ] `p/owasp-top-ten` - OWASP Top 10 (overlaps with security-audit)
+
+### Execution Strategy:
+- Spawn 3 parallel scan Tasks (Python, JavaScript, Docker)
+- Total rulesets: 9
+- [If Pro] Cross-file taint tracking enabled
+
+**Want to modify rulesets?** Tell me which to add or remove.
+**Ready to scan?** Say "proceed" or "yes".
+```
+
+**⛔ STOP: Await explicit user approval**
+
+After presenting the plan:
+
+1. **If user wants to modify rulesets:**
+   - Add requested rulesets to the appropriate category
+   - Remove requested rulesets
+   - Re-present the updated plan
+   - Return to waiting for approval
+
+2. **Use AskUserQuestion** if user hasn't responded:
+   ```
+   "I've prepared the scan plan with 9 rulesets (including Trail of Bits). Proceed with scanning?"
+   Options: ["Yes, run scan", "Modify rulesets first"]
+   ```
+
+3. **Valid approval responses:**
+   - "yes", "proceed", "approved", "go ahead", "looks good", "run it"
+
+4. **Mark task completed** only after approval with final rulesets confirmed
+
+5. **Do NOT treat as approval:**
+   - User's original request ("scan this codebase")
+   - Silence / no response
+   - Questions about the plan
+
+### Pre-Scan Checklist
+
+Before marking Step 3 complete, verify:
+- [ ] Target directory shown to user
+- [ ] Engine type (Pro/OSS) displayed
+- [ ] Languages detected and listed
+- [ ] **All rulesets explicitly listed with checkboxes**
+- [ ] User given opportunity to modify rulesets
+- [ ] User explicitly approved (quote their confirmation)
+- [ ] **Final ruleset list captured for Step 4**
+
+### Step 4: Spawn Parallel Scan Tasks
+
+Create output directory with run number to avoid collisions, then spawn Tasks with **approved rulesets from Step 3**:
+
+```bash
+# Find next available run number
+LAST=$(ls -d semgrep-results-[0-9][0-9][0-9] 2>/dev/null | sort | tail -1 | grep -o '[0-9]*$' || true)
+NEXT_NUM=$(printf "%03d" $(( ${LAST:-0} + 1 )))
+OUTPUT_DIR="semgrep-results-${NEXT_NUM}"
+mkdir -p "$OUTPUT_DIR"
+echo "Output directory: $OUTPUT_DIR"
+```
+
+**Spawn N Tasks in a SINGLE message** (one per language category) using `subagent_type: Bash`.
+
+Use the scanner task prompt template from [scanner-task-prompt.md]({baseDir}/references/scanner-task-prompt.md).
+
+**Example - 3 Language Scan (with approved rulesets):**
+
+Spawn these 3 Tasks in a SINGLE message:
+
+1. **Task: Python Scanner**
+   - Approved rulesets: p/python, p/django, p/security-audit, p/secrets, https://github.com/trailofbits/semgrep-rules
+   - Output: semgrep-results-001/python-*.json
+
+2. **Task: JavaScript Scanner**
+   - Approved rulesets: p/javascript, p/react, p/nodejs, p/security-audit, p/secrets, https://github.com/trailofbits/semgrep-rules
+   - Output: semgrep-results-001/js-*.json
+
+3. **Task: Docker Scanner**
+   - Approved rulesets: p/dockerfile
+   - Output: semgrep-results-001/docker-*.json
+
+### Step 5: Spawn Parallel Triage Tasks
+
+After scan Tasks complete, spawn triage Tasks using `subagent_type: general-purpose` (triage requires reading code context, not just running commands).
+
+Use the triage task prompt template from [triage-task-prompt.md]({baseDir}/references/triage-task-prompt.md).
+
+### Step 6: Collect Results (Main Agent)
+
+After all Tasks complete, generate merged SARIF and report:
+
+**Generate merged SARIF with only triaged true positives:**
+
+```bash
+uv run {baseDir}/scripts/merge_triaged_sarif.py [OUTPUT_DIR]
+```
+
+This script:
+1. Attempts to use [SARIF Multitool](https://www.npmjs.com/package/@microsoft/sarif-multitool) for merging (if `npx` is available)
+2. Falls back to pure Python merge if Multitool unavailable
+3. Reads all `*-triage.json` files to extract true positive findings
+4. Filters merged SARIF to include only triaged true positives
+5. Writes output to `[OUTPUT_DIR]/findings-triaged.sarif`
+
+**Optional: Install SARIF Multitool for better merge quality:**
+
+```bash
+npm install -g @microsoft/sarif-multitool
+```
+
+**Report to user:**
+
+```
+## Semgrep Scan Complete
+
+**Scanned:** 1,804 files
+**Rulesets used:** 9 (including Trail of Bits)
+**Total raw findings:** 156
+**After triage:** 32 true positives
+
+### By Severity:
+- ERROR: 5
+- WARNING: 18
+- INFO: 9
+
+### By Category:
+- SQL Injection: 3
+- XSS: 7
+- Hardcoded secrets: 2
+- Insecure configuration: 12
+- Code quality: 8
+
+Results written to:
+- semgrep-results-001/findings-triaged.sarif (SARIF, true positives only)
+- semgrep-results-001/*-triage.json (triage details per language)
+- semgrep-results-001/*.json (raw scan results)
+- semgrep-results-001/*.sarif (raw SARIF per ruleset)
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Correct Approach |
+|---------|------------------|
+| Running without `--metrics=off` | Always use `--metrics=off` to prevent telemetry |
+| Running rulesets sequentially | Run in parallel with `&` and `wait` |
+| Not scoping rulesets to languages | Use `--include="*.py"` for language-specific rules |
+| Reporting raw findings without triage | Always triage to remove false positives |
+| Single-threaded for multi-lang | Spawn parallel Tasks per language |
+| Sequential Tasks | Spawn all Tasks in SINGLE message for parallelism |
+| Using OSS when Pro is available | Check login status; use `--pro` for deeper analysis |
+| Assuming Pro is unavailable | Always check with login detection before scanning |
+
+## Limitations
+
+1. **OSS mode:** Cannot track data flow across files (login with `semgrep login` and run `semgrep install-semgrep-pro` to enable)
+2. **Pro mode:** Cross-file analysis uses `-j 1` (single job) which is slower per ruleset, but parallel rulesets compensate
+3. Triage requires reading code context - parallelized via Tasks
+4. Some false positive patterns require human judgment
+
+## Rationalizations to Reject
+
+| Shortcut | Why It's Wrong |
+|----------|----------------|
+| "User asked for scan, that's approval" | Original request ≠ plan approval; user must confirm specific parameters. Present plan, use AskUserQuestion, await explicit "yes" |
+| "Step 3 task is blocking, just mark complete" | Lying about task status defeats enforcement. Only mark complete after real approval |
+| "I already know what they want" | Assumptions cause scanning wrong directories/rulesets. Present plan with all parameters for verification |
+| "Just use default rulesets" | User must see and approve exact rulesets before scan |
+| "Add extra rulesets without asking" | Modifying approved list without consent breaks trust |
+| "Skip showing ruleset list" | User can't make informed decision without seeing what will run |
+| "Third-party rulesets are optional" | Trail of Bits, 0xdea, Decurity rules catch vulnerabilities not in official registry - they are REQUIRED when language matches |
+| "Skip triage, report everything" | Floods user with noise; true issues get lost |
+| "Run one ruleset at a time" | Wastes time; parallel execution is faster |
+| "Use --config auto" | Sends metrics; less control over rulesets |
+| "Triage later" | Findings without context are harder to evaluate |
+| "One Task at a time" | Defeats parallelism; spawn all Tasks together |
+| "Pro is too slow, skip --pro" | Cross-file analysis catches 250% more true positives; worth the time |
+| "Don't bother checking for Pro" | Missing Pro = missing critical cross-file vulnerabilities |
+| "OSS is good enough" | OSS misses inter-file taint flows; always prefer Pro when available |

.claude/skills/story-quality-gate/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: ln-500-story-quality-gate
+description: "Story-level quality orchestrator with 4-level Gate (PASS/CONCERNS/FAIL/WAIVED) and Quality Score. Pass 1: code quality -> regression -> manual testing. Pass 2: verify tests/coverage -> calculate NFR scores -> mark Story Done. Use when user requests quality gate for Story or when ln-400 delegates quality check."
+---
+
+# Story Quality Gate
+
+Two-pass Story review with 4-level Gate verdict, Quality Score calculation, and NFR validation (security, performance, reliability, maintainability).
+
+## Purpose & Scope
+- Pass 1 (after impl tasks Done): run code-quality, lint, regression, and manual testing; if all pass, create/confirm test task; otherwise create targeted fix/refactor tasks and stop.
+- Pass 2 (after test task Done): verify tests/coverage/priority limits, calculate Quality Score and NFR validation, close Story to Done or create fix tasks.
+- Delegates work to ln-501/ln-502 workers and ln-510-test-planner.
+
+## 4-Level Gate Model
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| **PASS** | All checks pass, no issues | Story → Done |
+| **CONCERNS** | Minor issues, acceptable risk | Story → Done with comment noting concerns |
+| **FAIL** | Blocking issues found | Create fix tasks, return to ln-400 |
+| **WAIVED** | Issues acknowledged by user | Story → Done with waiver reason documented |
+
+**Verdict calculation:** `FAIL` if any check fails. `CONCERNS` if minor issues exist. `PASS` if all clean.
+
+## Quality Score
+
+Formula: `Quality Score = 100 - (20 × FAIL_count) - (10 × CONCERN_count)`
+
+| Score Range | Status | Action |
+|-------------|--------|--------|
+| 90-100 | ✅ Excellent | PASS |
+| 70-89 | ⚠️ Acceptable | CONCERNS (proceed with notes) |
+| 50-69 | ❌ Below threshold | FAIL (create fix tasks) |
+| <50 | 🚨 Critical | FAIL (urgent priority) |
+
+## NFR Validation
+
+Evaluate 4 non-functional requirement dimensions:
+
+| NFR | Checks | Issue Prefix |
+|-----|--------|--------------|
+| **Security** | Auth, input validation, secrets exposure | SEC- |
+| **Performance** | N+1 queries, caching, response times | PERF- |
+| **Reliability** | Error handling, retries, timeouts | REL- |
+| **Maintainability** | DRY, SOLID, cyclomatic complexity | MNT- |
+
+Additional prefixes: `TEST-` (coverage gaps), `ARCH-` (architecture issues), `DOC-` (documentation gaps), `DEP-` (Story/Task dependencies), `COV-` (AC coverage quality), `DB-` (database schema), `AC-` (AC validation)
+
+**NFR verdict per dimension:** PASS / CONCERNS / FAIL
+
+## When to Use
+- Pass 1: all implementation tasks Done; test task missing or not Done.
+- Pass 2: test task exists and is Done.
+- Explicit `pass` parameter can force 1 or 2; otherwise auto-detect by test task status.
+
+## Workflow (concise)
+- **Phase 1 Discovery:** Auto-discover team/config; select Story; load Story + task metadata (no descriptions), detect test task status.
+- **Pass 1 flow (fail fast):**
+  1) Invoke ln-501-code-quality-checker. If issues -> create refactor task (Backlog), stop.
+  1.5) **Criteria Validation (Story-level checks)** - see `references/criteria_validation.md`:
+     - Check #1: Story Dependencies (no forward deps within Epic) - if FAIL → create [DEP-] task, stop.
+     - Check #2: AC-Task Coverage Quality (STRONG/WEAK/MISSING scoring) - if FAIL/CONCERNS → create [BUG-]/[COV-] tasks, stop.
+     - Check #3: Database Creation Principle (schema scope matches Story) - if FAIL → create [DB-] task, stop.
+  2) Run all linters from tech_stack.md. If fail -> create lint-fix task, stop.
+  3) Invoke ln-502-regression-checker. If fail -> create regression-fix task, stop.
+  4) Invoke ln-510-test-planner (orchestrates: ln-511-test-researcher → ln-512-manual-tester → ln-513-auto-test-planner). If manual testing fails -> create bug-fix task, stop. If all passed -> test task created/updated.
+  5) If test task exists and Done, jump to Pass 2; if exists but not Done, report status and stop.
+- **Pass 2 flow (after test task Done):**
+  1) Load Story/test task; read test plan/results and manual testing comment from Pass 1.
+  2) Verify limits and priority: Priority ≤15; E2E 2-5, Integration 0-8, Unit 0-15, total 10-28; tests focus on business logic (no framework/DB/library tests).
+  3) Ensure Priority ≤15 scenarios and Story AC are covered by tests; infra/docs updates present.
+  4) **Calculate Quality Score and NFR validation** (see formulas above):
+     - Run NFR checks per dimensions table
+     - Assign issue prefixes: SEC-, PERF-, REL-, MNT-, TEST-, ARCH-, DOC-
+     - Calculate Quality Score
+  5) **Determine Gate verdict** per 4-Level Gate Model above
+
+**TodoWrite format (mandatory):**
+Add pass steps to todos before starting:
+```
+Pass 1:
+- Invoke ln-501-code-quality-checker (in_progress)
+- Pass 1.5: Criteria Validation (Story deps, AC coverage, DB schema) (pending)
+- Run linters from tech_stack.md (pending)
+- Invoke ln-502-regression-checker (pending)
+- Invoke ln-510-test-planner (research + manual + auto tests) (pending)
+
+Pass 2:
+- Verify test task coverage (in_progress)
+- Mark Story Done (pending)
+```
+Mark each as in_progress when starting, completed when done. On failure, mark remaining as skipped.
+
+## Worker Invocation (MANDATORY)
+
+| Step | Worker | Context | Rationale |
+|------|--------|---------|-----------|
+| Code Quality | ln-501-code-quality-checker | **Separate** (Task tool) | Independent analysis, focused on DRY/KISS/YAGNI |
+| Regression | ln-502-regression-checker | **Shared** (direct Skill tool) | Needs Story context and previous check results |
+| Test Planning | ln-510-test-planner | **Shared** (direct Skill tool) | Needs full Gate context for test planning |
+
+**ln-501 invocation (Separate Context):**
+```
+Task(description: "Code quality check via ln-501",
+     prompt: "Execute ln-501-code-quality-checker. Read skill from ln-501-code-quality-checker/SKILL.md. Story: {storyId}",
+     subagent_type: "general-purpose")
+```
+
+**ln-501 result contract (Task tool return):**
+Task tool returns worker's final message. Parse for YAML block:
+- `verdict: PASS | CONCERNS | ISSUES_FOUND`
+- `quality_score: 0-100`
+- `issues: [{id, severity, finding, action}]`
+- If verdict = ISSUES_FOUND → create refactor task (Backlog), stop Pass 1.
+
+**ln-502 and ln-510:** Invoke via direct Skill tool — workers see Gate context.
+
+**Note:** ln-510 orchestrates the full test pipeline (ln-511 research → ln-512 manual → ln-513 auto tests).
+
+**❌ FORBIDDEN SHORTCUTS (Anti-Patterns):**
+- Running `mypy`, `ruff`, `pytest` directly instead of invoking ln-501/ln-502
+- Doing "minimal quality check" (just linters) and skipping ln-510 test planning
+- Asking user "Want me to run the full skill?" after doing partial checks
+- Marking steps as "completed" in todo without invoking the actual skill
+- Any command execution that should be delegated to a worker skill
+
+**✅ CORRECT BEHAVIOR:**
+- Use `Skill(skill: "ln-50X-...")` for EVERY step — NO EXCEPTIONS
+- Wait for each skill to complete before proceeding
+- If skill fails → create fix task → STOP (fail fast)
+- Never bypass skills with "I'll just run the command myself"
+
+**ZERO TOLERANCE:** If you find yourself running quality commands directly (mypy, ruff, pytest, curl) instead of invoking the appropriate skill, STOP and use Skill tool instead.
+
+## Critical Rules
+- Early-exit: any failure creates a specific task and stops Pass 1/2.
+- Single source of truth: rely on Linear metadata for tasks; kanban is updated by workers/ln-400.
+- Task creation via skills only (ln-510/ln-301); this skill never edits tasks directly.
+- Pass 2 only runs when test task is Done; otherwise return error/status.
+- Language preservation in comments (EN/RU).
+
+## Definition of Done
+- Pass 1: ln-501 pass OR refactor task created; linters pass OR lint-fix task created; ln-502 pass OR regression-fix task created; ln-510 pipeline pass (research + manual + auto tests) OR bug-fix task created; test task created/updated; exits.
+- Pass 2: test task verified (priority/limits/coverage/infra/docs); Quality Score calculated; NFR validation completed; Gate verdict determined (PASS/CONCERNS/FAIL/WAIVED).
+- **Gate output format:**
+  ```yaml
+  gate: PASS | CONCERNS | FAIL | WAIVED
+  quality_score: {0-100}
+  nfr_validation:
+    security: PASS | CONCERNS | FAIL
+    performance: PASS | CONCERNS | FAIL
+    reliability: PASS | CONCERNS | FAIL
+    maintainability: PASS | CONCERNS | FAIL
+  issues: [{id: "SEC-001", severity: high|medium|low, finding: "...", action: "..."}]
+  ```
+- Story set to Done (PASS/CONCERNS/WAIVED) or fix tasks created (FAIL); comment with gate verdict posted.
+
+## Reference Files
+- **Orchestrator lifecycle:** `shared/references/orchestrator_pattern.md`
+- **Task delegation pattern:** `shared/references/task_delegation_pattern.md`
+- **AC validation rules:** `shared/references/ac_validation_rules.md`
+- Criteria Validation: `references/criteria_validation.md` (Story deps, AC coverage quality, DB schema checks from ln-310)
+- Gate levels: `references/gate_levels.md` (detailed scoring rules and thresholds)
+- Workers: `../ln-501-code-quality-checker/SKILL.md`, `../ln-502-regression-checker/SKILL.md`
+- Test planning orchestrator: `../ln-510-test-planner/SKILL.md` (coordinates ln-511/512/513)
+- Tech stack/linters: `docs/project/tech_stack.md`
+
+---
+**Version:** 6.0.0 (BREAKING: Added Pass 1.5 Criteria Validation with 3 checks from ln-310 - Story dependencies, AC-Task Coverage Quality (STRONG/WEAK/MISSING), Database Creation Principle. New issue prefixes: DEP-, COV-, DB-, AC-. Closes validation-execution gap at Story level per BMAD Method best practices.)
+**Last Updated:** 2026-02-03

.claude/skills/storyboard-generator/SKILL.md

@@ -0,0 +1,816 @@
+---
+name: storyboard-generator
+description: 텍스트 기반 인터뷰/기획 문서를 분석하여 IA(메뉴 구조)와 화면 설계 스토리보드 PPTX를 자동 생성합니다. '기획서 생성', '스토리보드 생성', 'IA 생성' 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task
+---
+
+# Storyboard Generator Skill - 기획서/스토리보드 자동 생성
+
+텍스트 기반 인터뷰 문서나 기획 문서를 분석하여 웹 시스템 기획서(IA + 스토리보드)를 PPTX로 자동 생성하는 스킬입니다.
+
+## 활성화 트리거
+
+다음 키워드가 포함된 요청 시 이 스킬이 활성화됩니다:
+- "기획서 생성"
+- "스토리보드 생성"
+- "IA 생성"
+- "화면 설계"
+- "웹 기획"
+
+## Instructions
+
+### 1단계: 입력 파일 분석
+
+사용자가 제공한 파일 경로에서 텍스트 문서를 읽고 분석합니다.
+
+```bash
+# 파일 읽기
+cat [파일경로]
+```
+
+분석 대상:
+- 인터뷰 스크립트 (script.md, interview.txt 등)
+- 기획 문서 (planning.md, requirements.txt 등)
+- 요구사항 문서
+
+### 2단계: 데이터 추출
+
+텍스트에서 다음 정보를 자동 추출합니다:
+
+| 추출 항목 | 예시 |
+|-----------|------|
+| 프로젝트명 | 방화셔터 견적 시스템 |
+| 주요 기능 | 셔터 타입 선택, 견적 계산 |
+| 메뉴 구조 | 견적 입력 > 셔터 선택, 규격 입력 |
+| 화면 요소 | 입력 폼, 테이블, 버튼 |
+| 비즈니스 규칙 | 할인율, 계산 공식 |
+
+### 3단계: 설정 파일 생성
+
+추출된 데이터를 기반으로 storyboard-config.json 파일을 생성합니다.
+
+```json
+{
+  "projectName": "방화셔터 견적 시스템",
+  "company": "SAM",
+  "author": "IT 혁신팀",
+  "date": "2025.01.09",
+  "purpose": "프로젝트 목적 설명",
+  "features": ["기능 1", "기능 2"],
+  "effects": [
+    { "icon": "⏱️", "title": "시간 단축", "desc": "설명" }
+  ],
+  "tocItems": [
+    { "num": "01", "title": "프로젝트 개요", "desc": "설명" }
+  ],
+  "mainMenus": [
+    { "title": "메뉴1", "children": ["서브1", "서브2"] }
+  ],
+  "screens": [
+    {
+      "taskName": "화면명",
+      "route": "/path",
+      "screenName": "화면 이름",
+      "screenId": "SCREEN_001",
+      "descriptions": [
+        { "title": "항목1", "content": "설명" }
+      ]
+    }
+  ]
+}
+```
+
+### 4단계: HTML 슬라이드 생성 (권장)
+
+**HTML 기반 방식**을 사용하면 더 정교한 디자인이 가능합니다.
+
+```bash
+# 1단계: HTML 슬라이드 생성
+node ~/.claude/skills/storyboard-generator/scripts/generate-html-storyboard.js \
+  --config [설정파일.json] \
+  --output [html_slides 폴더]
+
+# 2단계: HTML → PPTX 변환
+node ~/.claude/skills/storyboard-generator/scripts/convert-html-to-pptx.js \
+  --input [html_slides 폴더] \
+  --output [출력파일.pptx]
+```
+
+### 5단계 (대안): 직접 PPTX 생성
+
+간단한 경우 직접 PPTX를 생성할 수도 있습니다.
+
+```bash
+node ~/.claude/skills/storyboard-generator/scripts/generate-storyboard.js \
+  --config [설정파일.json] \
+  --output [출력파일.pptx]
+```
+
+### 6단계: 결과 확인
+
+생성된 PPTX 파일 정보를 사용자에게 안내합니다.
+
+## 생성되는 슬라이드 구조
+
+| 슬라이드 | 내용 | 템플릿 |
+|----------|------|--------|
+| 1 | 표지 | 프로젝트명, 버전, 날짜 |
+| 2 | Document History | 문서 이력 테이블 |
+| 3 | 목차 | 섹션 번호 + 제목 |
+| 4 | 프로젝트 개요 | 목적, 주요 기능, 기대 효과 |
+| 5 | 메뉴 구조 (IA) | 계층형 다이어그램 |
+| 6+ | 화면 스토리보드 | 와이어프레임 + Description |
+
+## 스토리보드 슬라이드 레이아웃
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Task Name │ [값] │ Ver. │ D1.0 │ Page │ [N] │          │
+│ Route     │ [경로] │ Screen Name │ [화면명] │ ID │ [ID] │
+├───────────────────────────────────┬─────────────────────┤
+│                                   │   Description       │
+│     와이어프레임 영역 (6.8")      │─────────────────────│
+│                                   │ ① 제목              │
+│  ┌─────────────────────────────┐  │    설명 텍스트      │
+│  │  사이드바  │  메인 콘텐츠   │  │─────────────────────│
+│  │           │                │  │ ② 제목              │
+│  │           │                │  │    설명 텍스트      │
+│  └─────────────────────────────┘  │─────────────────────│
+│                                   │ ③ 제목              │
+│                                   │    설명 텍스트      │
+└───────────────────────────────────┴─────────────────────┘
+```
+
+## wireframeElements 가이드라인 (매우 중요)
+
+### 사이드바 자동 렌더링
+**사이드바는 `mainMenus` 배열을 기반으로 자동 생성됩니다.**
+- 현재 화면의 `taskName`과 일치하는 메뉴가 **활성(highlight)** 상태로 표시됩니다
+- wireframeElements에 사이드바 요소를 포함해도 **자동으로 필터링**되어 중복 표시되지 않습니다
+- x좌표 < 1.5인 요소는 사이드바 영역으로 간주되어 제외됩니다
+
+### 좌표 체계 (인치 단위)
+```
+┌────────────────────────────────────────────────────────┐
+│                  슬라이드 (10" x 5.625")                │
+├─────────┬──────────────────────────────────────────────┤
+│ 사이드바 │              콘텐츠 영역                      │
+│ x < 1.5 │              x >= 1.5                        │
+│         │                                              │
+│ (자동   │  wireframeElements 배치 영역                  │
+│  생성)  │                                              │
+│         │                                              │
+├─────────┴──────────────────────────────────────────────┤
+```
+
+### wireframeElements 작성 예시
+```json
+{
+  "screens": [
+    {
+      "taskName": "견적서 생성",    // mainMenus의 title과 일치해야 함
+      "wireframeElements": [
+        // ❌ 사이드바 요소 - 작성해도 자동 필터링됨
+        {"type": "rect", "x": 0.3, "y": 1.3, "w": 1.2, "h": 4, "fill": "f1f5f9"},
+        {"type": "rect", "x": 0.35, "y": 1.4, "w": 1.1, "h": 0.3, "text": "규격 입력"},
+
+        // ✅ 콘텐츠 영역 요소 - 이것만 실제로 렌더링됨
+        {"type": "rect", "x": 1.6, "y": 1.3, "w": 5.3, "h": 0.35, "text": "제목"},
+        {"type": "rect", "x": 1.6, "y": 1.75, "w": 2.5, "h": 1, "fill": "0d9488"}
+      ]
+    }
+  ]
+}
+```
+
+### wireframeElements 속성
+| 속성 | 타입 | 설명 | 예시 |
+|------|------|------|------|
+| type | string | 요소 타입 | "rect" |
+| x | number | X 좌표 (인치) | 1.6 |
+| y | number | Y 좌표 (인치) | 1.3 |
+| w | number | 너비 (인치) | 2.5 |
+| h | number | 높이 (인치) | 0.8 |
+| fill | string | 배경색 (# 없이) | "0d9488" |
+| text | string | 텍스트 내용 | "제목" |
+| fontSize | number | 폰트 크기 | 11 |
+| color | string | 텍스트 색상 | "FFFFFF" |
+| bold | boolean | 굵게 | true |
+| align | string | 정렬 | "left", "center", "right" |
+
+### 사이드바 메뉴 설정
+```json
+{
+  "mainMenus": [
+    { "title": "규격 입력", "children": ["개구부 크기", "제작 규격"] },
+    { "title": "단가 계산", "children": ["재질 선택", "면적 단가"] },
+    { "title": "부대비용", "children": ["모터 선정", "철거비"] },
+    { "title": "견적서 생성", "children": ["마진율", "출력"] }
+  ],
+  "screens": [
+    {
+      "taskName": "견적서 생성"  // ← 이 화면에서 "견적서 생성" 메뉴가 활성화됨
+    }
+  ]
+}
+```
+
+## Description 마커 시스템 (매우 중요)
+
+### 빨간 번호 마커
+Description 패널의 각 항목 번호(①②③④)가 **빨간색 원형 마커**로 표시됩니다.
+- 와이어프레임 영역에 동일한 빨간 번호 마커가 해당 요소 위치에 표시됩니다
+- Description의 설명이 화면의 어떤 요소를 가리키는지 명확하게 매핑됩니다
+
+### markerX, markerY 속성
+descriptions 배열의 각 항목에 `markerX`, `markerY`를 추가하여 마커 위치를 지정합니다.
+
+```json
+{
+  "descriptions": [
+    {
+      "title": "개구부 입력",
+      "content": "고객사 제공 문 크기 입력",
+      "markerX": 1.6,   // 마커 X 좌표 (인치)
+      "markerY": 1.75   // 마커 Y 좌표 (인치)
+    },
+    {
+      "title": "제작 규격 변환",
+      "content": "W+100mm, H+600mm 자동 계산",
+      "markerX": 5.1,
+      "markerY": 1.75
+    }
+  ]
+}
+```
+
+### descriptions 속성
+| 속성 | 타입 | 필수 | 설명 | 예시 |
+|------|------|------|------|------|
+| title | string | ✅ | 항목 제목 | "개구부 입력" |
+| content | string | ✅ | 설명 내용 | "mm 단위로 입력" |
+| markerX | number | ❌ | 마커 X 좌표 (인치) | 1.6 |
+| markerY | number | ❌ | 마커 Y 좌표 (인치) | 1.75 |
+
+### 마커 위치 가이드
+```
+┌──────────────────────────────────────────────┐
+│ 사이드바 │      콘텐츠 영역                    │
+│          │  ①────────────  ②────────────    │
+│          │  │ 개구부 입력  │  │ 제작 규격  │    │
+│          │  └────────────  └────────────    │
+│          │                                    │
+│          │  ③────────────  ④────────────    │
+│          │  │ 면적 계산   │  │ 할증 적용  │    │
+│          │  └────────────  └────────────    │
+└──────────────────────────────────────────────┘
+```
+
+- markerX, markerY가 없으면 기본 위치(좌측 세로 배치)에 마커 표시
+- 좌표는 wireframeElements와 동일한 인치 단위 사용
+- 마커는 z-index가 높아 다른 요소 위에 표시됨
+
+## 색상 팔레트
+
+```javascript
+const colors = {
+    primary: '0d9488',      // Teal (주요 강조)
+    secondary: '1e293b',    // Slate 800 (헤더, 배경)
+    accent: '95C11F',       // 라임 그린 (Description 헤더)
+    warning: 'f59e0b',      // 경고 (유효기간 등)
+    danger: 'dc2626',       // 위험 (필수 항목)
+    white: 'FFFFFF',
+    lightGray: 'f1f5f9',    // 배경
+    darkGray: '64748b',     // 보조 텍스트
+    black: '1a1a1a',        // Description 영역 배경
+    wireframeBg: 'f8fafc',  // 와이어프레임 배경
+    wireframeBorder: 'e2e8f0'  // 와이어프레임 테두리
+};
+```
+
+## Description 패널 스타일 가이드 (매우 중요)
+
+### 배경 없는 투명 스타일
+Description 영역의 각 항목은 **배경색 없이** 투명하게 표현해야 합니다.
+
+```javascript
+// ✅ 올바른 Description 항목 스타일
+descriptions.forEach((desc, idx) => {
+    const y = 1.25 + idx * 0.85;
+
+    // 번호 원 (라임 그린 배경)
+    slide.addShape('ellipse', {
+        x: 7.25, y: y, w: 0.25, h: 0.25,
+        fill: { color: '95C11F' }  // 라임 그린
+    });
+    slide.addText(String(idx + 1), {
+        x: 7.25, y: y, w: 0.25, h: 0.25,
+        fontSize: 7, bold: true, color: 'FFFFFF',
+        align: 'center', valign: 'middle'
+    });
+
+    // 제목 - 배경 없음, 흰색 텍스트
+    slide.addText(desc.title, {
+        x: 7.55, y: y, w: 2.1, h: 0.25,
+        fontSize: 8, bold: true, color: 'FFFFFF'
+        // fill 속성 없음 = 투명 배경
+    });
+
+    // 설명 - 배경 없음, 회색 텍스트
+    slide.addText(desc.content, {
+        x: 7.25, y: y + 0.28, w: 2.4, h: 0.5,
+        fontSize: 7, color: '64748b'
+        // fill 속성 없음 = 투명 배경
+    });
+});
+
+// ❌ 잘못된 스타일 - 각 항목에 배경색 적용
+slide.addText(desc.title, {
+    x: 7.55, y: y, w: 2.1, h: 0.25,
+    fill: { color: '333333' }  // 배경색 금지
+});
+```
+
+### Description 영역 구조
+```
+┌─────────────────────────┐
+│  Description (헤더)     │ ← 라임 그린 배경 (#95C11F)
+├─────────────────────────┤
+│                         │
+│  ① 제목                 │ ← 번호만 원형 배경, 텍스트는 투명
+│     설명 텍스트         │ ← 배경 없음
+│                         │
+│  ② 제목                 │
+│     설명 텍스트         │
+│                         │
+│  ③ 제목                 │
+│     설명 텍스트         │
+│                         │
+│  ④ 제목                 │
+│     설명 텍스트         │
+│                         │
+└─────────────────────────┘
+   전체 배경: #1a1a1a (검정)
+   각 항목: 배경 없음 (투명)
+```
+
+## 테이블 스타일 가이드 (매우 중요)
+
+### 일관된 테두리 적용
+모든 테이블은 **동일한 테두리 스타일**을 사용해야 합니다.
+
+```javascript
+// ✅ 올바른 테이블 테두리 스타일
+slide.addTable(data, {
+    x: 0.5, y: 1, w: 9, h: 2,
+    fontSize: 10,
+    color: '1e293b',
+    border: { pt: 0.5, color: '64748b' },  // 일관된 0.5pt, darkGray
+    colW: [1.2, 0.8, 1.5, 4, 1.5],
+    align: 'center',
+    valign: 'middle'
+});
+
+// ❌ 잘못된 스타일 - 테두리 불일치
+slide.addTable(data, {
+    border: { pt: 1, color: '000000' }  // 다른 두께/색상 사용 금지
+});
+```
+
+### 헤더 정보 테이블 (스토리보드 상단)
+```javascript
+const headerData = [
+    ['Task Name', screenInfo.taskName, 'Ver.', 'D1.0', 'Page', screenInfo.page],
+    ['Route', screenInfo.route, 'Screen Name', screenInfo.screenName, 'Screen ID', screenInfo.screenId]
+];
+
+slide.addTable(headerData, {
+    x: 0.2, y: 0.1, w: 9.6, h: 0.5,
+    fontSize: 8,
+    color: '1e293b',
+    border: { pt: 0.5, color: '64748b' },  // 표준 테두리
+    fill: { color: 'f1f5f9' },              // 연한 회색 배경
+    colW: [0.8, 2.5, 0.8, 2.5, 0.8, 2.2]   // 균일한 열 너비
+});
+```
+
+### 와이어프레임 내 테이블 형태 요소
+```javascript
+// 와이어프레임 내 테이블 스타일 박스
+slide.addShape('rect', {
+    x: 1.6, y: 2.2, w: 5.3, h: 0.35,
+    fill: { color: '1e293b' },
+    line: { color: 'e2e8f0', width: 0.5 }  // 일관된 테두리
+});
+
+// 행 구분
+slide.addShape('rect', {
+    x: 1.6, y: 2.6, w: 5.3, h: 0.35,
+    fill: { color: 'FFFFFF' },
+    line: { color: 'e2e8f0', width: 0.5 }  // 동일한 테두리
+});
+```
+
+### 테이블 스타일 요약
+| 요소 | 테두리 두께 | 테두리 색상 | 배경색 |
+|------|------------|------------|--------|
+| 헤더 정보 테이블 | 0.5pt | 64748b | f1f5f9 |
+| Document History | 0.5pt | 64748b | FFFFFF |
+| 와이어프레임 테이블 | 0.5pt | e2e8f0 | FFFFFF/1e293b |
+| IA 메뉴 박스 | 0.5pt | e2e8f0 | f1f5f9 |
+
+## PptxGenJS 핵심 규칙
+
+### 색상 코드 (매우 중요)
+```javascript
+// ✅ 올바른 사용 - # 없이
+{ color: 'FF0000' }
+{ fill: { color: '1e3a5f' } }
+
+// ❌ 잘못된 사용 - 파일 손상
+{ color: '#FF0000' }
+```
+
+### 슬라이드 크기 (16:9)
+```javascript
+pptx.defineLayout({ name: 'CUSTOM_16x9', width: 10, height: 5.625 });
+pptx.layout = 'CUSTOM_16x9';
+```
+
+### 요소 추가 예시
+```javascript
+// 텍스트
+slide.addText('제목', {
+    x: 0.5, y: 0.5, w: 9, h: 0.5,
+    fontSize: 20, bold: true, color: '1e293b'
+});
+
+// 도형
+slide.addShape('rect', {
+    x: 0, y: 0, w: 10, h: 0.7,
+    fill: { color: '1e293b' }
+});
+
+// 테이블
+slide.addTable(data, {
+    x: 0.5, y: 1, w: 9, h: 2,
+    fontSize: 10,
+    border: { pt: 0.5, color: '64748b' }
+});
+```
+
+## 입력 파일 형식 지원
+
+### Markdown (.md)
+```markdown
+## 프로젝트명: 방화셔터 견적 시스템
+
+### 주요 기능
+1. 셔터 타입 선택
+2. 규격 입력 및 계산
+3. 견적서 생성
+```
+
+### 텍스트 (.txt)
+```
+=== 프로젝트 개요 ===
+방화셔터 견적서 자동화 시스템
+
+=== 메뉴 구조 ===
+- 견적 입력
+  - 셔터 타입 선택
+  - 규격 입력
+```
+
+### 인터뷰 스크립트
+```
+**김철수:** 어떤 기능이 필요한가요?
+**박지민:** 셔터 종류 선택과 자동 계산이요.
+```
+
+## 실행 예시
+
+### 기본 사용
+```bash
+# 사용자 요청
+"C:\project\script.md 기획서 생성해줘"
+
+# 실행되는 명령
+node ~/.claude/skills/storyboard-generator/scripts/generate-storyboard.js \
+  --input "C:\project\script.md" \
+  --output "C:\project\pptx\storyboard.pptx"
+```
+
+### 출력 폴더 지정
+```bash
+# 사용자 요청
+"interview.txt를 분석해서 스토리보드 생성, output 폴더에 저장"
+
+# 실행되는 명령
+node ~/.claude/skills/storyboard-generator/scripts/generate-storyboard.js \
+  --input "interview.txt" \
+  --output "output/storyboard.pptx"
+```
+
+## 워크플로우 (HTML 기반 - 권장)
+
+```
+┌─────────────────┐
+│  입력 파일      │  script.md, interview.txt
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  텍스트 분석    │  섹션 인식, 키워드 추출
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  데이터 구조화  │  storyboard-config.json 생성
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  HTML 슬라이드  │  generate-html-storyboard.js
+│  생성           │  → 각 슬라이드를 HTML로 생성
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  HTML → PPTX    │  convert-html-to-pptx.js
+│  변환           │  → Playwright로 렌더링 후 변환
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  PPTX 출력      │  완성된 기획서
+└─────────────────┘
+```
+
+### HTML 기반 방식의 장점
+
+1. **정교한 디자인**: CSS로 정밀한 레이아웃 제어 가능
+2. **일관된 스타일**: 테두리, 간격, 색상이 CSS로 정확하게 적용
+3. **미리보기**: HTML 파일을 브라우저에서 바로 확인 가능
+4. **디버깅 용이**: 문제 발생 시 HTML 소스 확인으로 빠른 수정
+
+## 필수 의존성
+
+```bash
+# Node.js 패키지 (scripts 폴더에 설치)
+cd ~/.claude/skills/storyboard-generator/scripts
+npm install pptxgenjs playwright sharp
+```
+
+## 관련 스킬
+
+- **text-analyzer-skill**: 텍스트 구조 분석
+- **proposal-skill**: PDF 기획서 분석
+- **pptx-skill**: HTML → PPTX 변환
+- **design-skill**: 슬라이드 디자인
+
+## 대량 견적서 생성 워크플로우
+
+### 배치 생성 프로세스
+```
+┌─────────────────┐
+│  마스터 설정     │  estimate-template.json (공통 설정)
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  개별 견적 데이터 │  estimates/*.json (프로젝트별 변수)
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  설정 파일 병합  │  마스터 + 개별 = 완성된 config
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  HTML 슬라이드   │  각 견적별 html_slides 폴더
+│  생성 (배치)     │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  PPTX 변환      │  각 견적별 .pptx 파일
+│  (배치)         │
+└─────────────────┘
+```
+
+### 마스터 템플릿 구조
+```json
+{
+  "_template": true,
+  "company": "SAM",
+  "author": "DX 추진팀",
+  "mainMenus": [
+    { "title": "규격 입력", "children": ["개구부 크기", "제작 규격 계산"] },
+    { "title": "단가 계산", "children": ["재질 선택", "두께 선택"] },
+    { "title": "부대비용", "children": ["모터 선정", "철거/폐기물"] },
+    { "title": "견적서 생성", "children": ["마진율 적용", "PPT 출력"] }
+  ],
+  "pricingRules": {
+    "materials": {
+      "아연도강판_0.8t": 85000,
+      "아연도강판_1.0t": 90000,
+      "스크린_일반": "변동",
+      "스크린_차열": "일반 × 1.8"
+    },
+    "motors": {
+      "400형": { "maxWeight": 300, "price": 450000 },
+      "600형": { "maxWeight": 500, "price": 600000 },
+      "1000형": { "maxWeight": 999, "price": 850000 }
+    },
+    "additionalCosts": {
+      "철거비": 150000,
+      "폐기물처리": 50000,
+      "고소장비": 250000
+    },
+    "margins": {
+      "관공서": 0.15,
+      "일반건설사": 0.20,
+      "특수": 0.25
+    }
+  }
+}
+```
+
+### 개별 견적 데이터 예시
+```json
+{
+  "_extends": "estimate-template.json",
+  "projectName": "○○빌딩 방화셔터 교체공사",
+  "date": "2025.01.15",
+  "items": [
+    {
+      "location": "B1F 주차장 입구",
+      "openingW": 3000,
+      "openingH": 4000,
+      "material": "아연도강판_0.8t",
+      "workflow": "교체"
+    },
+    {
+      "location": "1F 로비",
+      "openingW": 2500,
+      "openingH": 3500,
+      "material": "스크린_일반",
+      "workflow": "신축"
+    }
+  ]
+}
+```
+
+### 배치 실행 명령
+```bash
+# 여러 견적서 일괄 생성
+for config in estimates/*.json; do
+  name=$(basename "$config" .json)
+
+  # HTML 생성
+  node ~/.claude/skills/storyboard-generator/scripts/generate-html-storyboard.js \
+    --config "$config" \
+    --output "output/${name}_html"
+
+  # PPTX 변환
+  node ~/.claude/skills/storyboard-generator/scripts/convert-html-to-pptx.js \
+    --input "output/${name}_html" \
+    --output "output/${name}.pptx"
+done
+```
+
+## 방화셔터 견적 계산 로직
+
+### 규격 변환 공식
+```
+제작 규격 = 개구부 + 여유치
+
+┌─────────────────────────────────────────────────┐
+│  제작 폭(W)  = 개구부 폭 + 100mm (레일 설치용)    │
+│  제작 높이(H) = 개구부 높이 + 600mm (권상높이)    │
+└─────────────────────────────────────────────────┘
+
+예시:
+  개구부: 3,000mm × 4,000mm
+  제작:   3,100mm × 4,600mm
+```
+
+### 면적 계산 및 할증
+```
+실제면적 = 제작W × 제작H ÷ 1,000,000 (㎡)
+
+┌─────────────────────────────────────────────────┐
+│  최소면적 규칙: 5㎡ 미만 → 5㎡ 강제 적용           │
+│  (제작 공정상 최소 규격 필요)                      │
+└─────────────────────────────────────────────────┘
+
+예시:
+  3,100 × 4,600 = 14,260,000 ㎟ = 14.26㎡
+  적용면적 = 14.26㎡ (5㎡ 이상이므로 그대로)
+```
+
+### 단가표 (기준가)
+| 재질 | 두께 | 단가(원/㎡) | 비고 |
+|------|------|------------|------|
+| 아연도 강판 | 0.8t | 85,000 | 기본 |
+| 아연도 강판 | 1.0t | 90,000 | 소방 기준 |
+| 스크린 (일반) | - | 변동 | 시세 적용 |
+| 스크린 (차열) | - | 일반×1.8 | 차열 등급 |
+
+### 하중 계산 및 모터 선정
+```
+총 하중 = 적용면적 × 12kg (0.8t 기준)
+          적용면적 × 15kg (1.0t 기준)
+
+┌────────────────────────────────────────────────┐
+│  모터 선정 기준                                   │
+│  ~300kg   → 400형 (450,000원)                   │
+│  300~500kg → 600형 (600,000원)                  │
+│  500kg~   → 1000형 (850,000원)                  │
+└────────────────────────────────────────────────┘
+```
+
+### 부대비용 항목
+| 항목 | 금액 | 적용 조건 |
+|------|------|----------|
+| 철거비 | 150,000원/개소 | 교체공사 시 |
+| 폐기물처리 | 50,000원/개소 | 교체공사 시 |
+| 고소장비 | 250,000원/일 | 지하/고층 현장 |
+| 지방운반비 | 별도 협의 | 수도권 외 |
+
+### 최종 금액 계산
+```
+원가 합계 = 자재비 + 모터비 + 부대비용
+
+┌────────────────────────────────────────────────┐
+│  마진율 적용                                     │
+│  관공서: 15%                                    │
+│  일반 건설사: 20~25%                            │
+│  특수 (원거리/고층): 25~30%                      │
+└────────────────────────────────────────────────┘
+
+최종금액 = 원가 × (1 + 마진율)
+절삭금액 = 만원 단위 이하 절삭 (네고 대비)
+```
+
+## 워크플로우 변형 (신축 vs 교체)
+
+### 신축공사 워크플로우
+```
+┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
+│ 규격 입력 │ → │ 단가 계산 │ → │ 모터 선정 │ → │ 견적 생성 │
+└──────────┘   └──────────┘   └──────────┘   └──────────┘
+
+특징:
+- 철거비/폐기물 비용 없음
+- 기존 구조물 확인 불필요
+- 전기 배선 신규 설치
+```
+
+### 교체공사 워크플로우
+```
+┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
+│ 규격 입력 │ → │ 단가 계산 │ → │ 모터 선정 │ → │ 부대비용  │ → │ 견적 생성 │
+└──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘
+                                              ↑
+                                        철거비, 폐기물,
+                                        양중비 추가
+
+특징:
+- 철거비 150,000원/개소 추가
+- 폐기물처리 50,000원/개소 추가
+- 기존 전기 배선 활용 가능
+- 양중비(고소장비) 현장 상황에 따라 추가
+```
+
+### 설정 파일에서 워크플로우 구분
+```json
+{
+  "screens": [
+    {
+      "taskName": "부대비용",
+      "conditionalDisplay": {
+        "show": "workflow === '교체'",
+        "description": "교체공사 시에만 이 화면 표시"
+      }
+    }
+  ],
+  "calculations": {
+    "additionalCosts": {
+      "철거비": { "condition": "workflow === '교체'", "amount": 150000 },
+      "폐기물": { "condition": "workflow === '교체'", "amount": 50000 }
+    }
+  }
+}
+```
+
+## 주의사항
+
+1. **입력 파일 인코딩**: UTF-8 권장
+2. **출력 폴더**: 존재하지 않으면 자동 생성
+3. **파일명 충돌**: 기존 파일 덮어쓰기
+4. **한글 지원**: 맑은 고딕, Pretendard 폰트 사용
+5. **단가 변동**: 스크린 방화셔터 단가는 시세에 따라 변동 - 외부 단가표 참조 필요
+6. **면책 조항**: 전기 배선 및 상시 전원 공사 별도 문구 필수 삽입

.claude/skills/storyboard-generator/examples/fire-shutter-config.json

@@ -0,0 +1,95 @@
+{
+  "projectName": "방화셔터 견적 시스템",
+  "company": "SAM",
+  "author": "IT 혁신팀",
+  "date": "2024.10.24",
+  "purpose": "현장 영업사원의 전화 견적 요청을\nAI 기반으로 자동화하여\n엑셀 정리 → PPT 견적서 생성\n과정을 시스템화",
+  "features": [
+    "셔터 타입 선택 (철재/스크린/하향식)",
+    "규격 입력 → 면적 자동 계산",
+    "모터 사양 자동 선택",
+    "지역/층고별 설치/운반비 가산",
+    "할인율 적용 및 PPT 자동 생성"
+  ],
+  "effects": [
+    { "icon": "⏱️", "title": "시간 단축", "desc": "견적서 작성 시간 80% 감소" },
+    { "icon": "✅", "title": "정확성 향상", "desc": "계산 오류 제로화" },
+    { "icon": "📊", "title": "표준화", "desc": "PPT 양식 통일" }
+  ],
+  "tocItems": [
+    { "num": "01", "title": "프로젝트 개요", "desc": "시스템 목적 및 범위" },
+    { "num": "02", "title": "메뉴 구조 (IA)", "desc": "Information Architecture" },
+    { "num": "03", "title": "견적 입력 화면", "desc": "셔터 타입, 규격, 옵션 선택" },
+    { "num": "04", "title": "견적 계산 화면", "desc": "단가 계산 및 부가비용" },
+    { "num": "05", "title": "견적서 미리보기", "desc": "PPT 양식 프리뷰" },
+    { "num": "06", "title": "견적 관리", "desc": "목록 조회 및 이력 관리" }
+  ],
+  "mainMenus": [
+    {
+      "title": "견적 입력",
+      "children": ["셔터 타입 선택", "규격 입력", "옵션 선택"]
+    },
+    {
+      "title": "견적 계산",
+      "children": ["단가 계산", "모터 선택", "부가비용"]
+    },
+    {
+      "title": "견적서 생성",
+      "children": ["미리보기", "PPT 다운로드", "이메일 전송"]
+    },
+    {
+      "title": "견적 관리",
+      "children": ["목록 조회", "이력 관리", "통계"]
+    }
+  ],
+  "screens": [
+    {
+      "taskName": "견적 입력",
+      "route": "/estimate/input",
+      "screenName": "견적 입력 화면",
+      "screenId": "EST_INPUT_001",
+      "descriptions": [
+        { "title": "셔터 타입 선택", "content": "철재(85,000/㎡), 스크린(단가 변동), 하향식 스크린 중 선택" },
+        { "title": "규격 입력", "content": "가로(W) × 높이(H) 미터 단위로 입력, 면적 자동 계산" },
+        { "title": "수량 입력", "content": "동일 규격 셔터 수량 입력 (1개소 이상)" },
+        { "title": "입력 검증", "content": "필수 항목 미입력 시 경고 표시, 다음 단계 진행 불가" }
+      ]
+    },
+    {
+      "taskName": "견적 계산",
+      "route": "/estimate/calculate",
+      "screenName": "견적 계산 화면",
+      "screenId": "EST_CALC_001",
+      "descriptions": [
+        { "title": "모터 자동 선택", "content": "셔터 무게 기준 자동 추천, 수동 변경 가능" },
+        { "title": "기본 설치비", "content": "1개소당 30만원, 수량에 따라 자동 계산" },
+        { "title": "고소작업비", "content": "층고 5m 이상 시 렌탈비 25만원/일 추가" },
+        { "title": "운반비", "content": "서울/경기 무료, 지방 거리별 15~30만원 청구" }
+      ]
+    },
+    {
+      "taskName": "견적서 생성",
+      "route": "/estimate/preview",
+      "screenName": "견적서 미리보기",
+      "screenId": "EST_PREVIEW_001",
+      "descriptions": [
+        { "title": "PPT 구성", "content": "표지 → 요약 → 세부내역 → 성적서 → 회사소개 (5장)" },
+        { "title": "실시간 미리보기", "content": "슬라이드 썸네일 클릭 시 해당 페이지 확대 표시" },
+        { "title": "다운로드/전송", "content": "PPT 파일 다운로드 또는 고객사 이메일 직접 전송" },
+        { "title": "유효기간 자동 삽입", "content": "제출일 기준 15일 유효기간 빨간색 문구 자동 추가" }
+      ]
+    },
+    {
+      "taskName": "견적 관리",
+      "route": "/estimate/list",
+      "screenName": "견적 관리 목록",
+      "screenId": "EST_LIST_001",
+      "descriptions": [
+        { "title": "견적 목록", "content": "프로젝트명, 금액, 상태, 작성일 기준 조회" },
+        { "title": "필터/정렬", "content": "상태별 필터, 날짜/금액 정렬 기능" },
+        { "title": "통계 대시보드", "content": "전체 건수, 이번 달 건수, 총 금액 실시간 표시" },
+        { "title": "할인 권한", "content": "1,000만원 이상 시 5% 할인 가능 (부장 결재 시 추가)" }
+      ]
+    }
+  ]
+}

.claude/skills/storyboard-generator/scripts/convert-html-to-pptx.js

@@ -0,0 +1,122 @@
+/**
+ * HTML 슬라이드를 PPTX로 변환하는 스크립트
+ *
+ * 사용법:
+ *   node convert-html-to-pptx.js --input <html_slides_folder> --output <output.pptx>
+ */
+
+const fs = require('fs');
+const path = require('path');
+const PptxGenJS = require('pptxgenjs');
+
+// html2pptx.js 모듈 로드
+const pptxSkillPath = path.join(__dirname, '../../pptx-skill/scripts/html2pptx.js');
+let html2pptx;
+
+if (fs.existsSync(pptxSkillPath)) {
+    html2pptx = require(pptxSkillPath);
+} else {
+    console.error('❌ html2pptx.js를 찾을 수 없습니다.');
+    console.error('   경로:', pptxSkillPath);
+    process.exit(1);
+}
+
+async function main() {
+    const args = process.argv.slice(2);
+    let inputDir = null;
+    let outputFile = null;
+
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--input' && args[i + 1]) {
+            inputDir = args[i + 1];
+            i++;
+        } else if (args[i] === '--output' && args[i + 1]) {
+            outputFile = args[i + 1];
+            i++;
+        }
+    }
+
+    if (!inputDir) {
+        console.error('Usage: node convert-html-to-pptx.js --input <html_slides_folder> --output <output.pptx>');
+        process.exit(1);
+    }
+
+    if (!fs.existsSync(inputDir)) {
+        console.error(`❌ 입력 폴더를 찾을 수 없습니다: ${inputDir}`);
+        process.exit(1);
+    }
+
+    // HTML 파일 목록 가져오기 (이름순 정렬)
+    const htmlFiles = fs.readdirSync(inputDir)
+        .filter(f => f.endsWith('.html'))
+        .sort()
+        .map(f => path.join(inputDir, f));
+
+    if (htmlFiles.length === 0) {
+        console.error('❌ HTML 파일을 찾을 수 없습니다.');
+        process.exit(1);
+    }
+
+    // 출력 파일명 설정
+    if (!outputFile) {
+        outputFile = path.join(path.dirname(inputDir), 'storyboard.pptx');
+    }
+
+    console.log('🚀 HTML → PPTX 변환 시작\n');
+    console.log(`📂 입력 폴더: ${inputDir}`);
+    console.log(`📄 HTML 파일: ${htmlFiles.length}개`);
+    console.log(`📁 출력 파일: ${outputFile}\n`);
+
+    // PptxGenJS 초기화
+    const pptx = new PptxGenJS();
+
+    // 16:9 레이아웃 설정 (720pt x 405pt = 10" x 5.625")
+    pptx.defineLayout({ name: 'CUSTOM_16x9', width: 10, height: 5.625 });
+    pptx.layout = 'CUSTOM_16x9';
+
+    pptx.author = 'SAM IT Innovation Team';
+    pptx.company = 'SAM';
+    pptx.subject = 'Web Storyboard';
+
+    // 각 HTML 파일을 슬라이드로 변환
+    for (let i = 0; i < htmlFiles.length; i++) {
+        const htmlFile = htmlFiles[i];
+        const fileName = path.basename(htmlFile);
+
+        try {
+            console.log(`⏳ 변환 중 (${i + 1}/${htmlFiles.length}): ${fileName}`);
+
+            await html2pptx(htmlFile, pptx);
+
+            console.log(`✅ 완료: ${fileName}`);
+        } catch (error) {
+            console.error(`❌ 오류: ${fileName}`);
+            console.error(`   ${error.message}`);
+            // 오류가 발생해도 계속 진행
+        }
+    }
+
+    // PPTX 파일 저장
+    try {
+        // 출력 폴더 생성
+        const outputDir = path.dirname(outputFile);
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+        }
+
+        await pptx.writeFile(outputFile);
+
+        const stats = fs.statSync(outputFile);
+        const sizeKB = (stats.size / 1024).toFixed(1);
+
+        console.log('\n🎉 PPTX 생성 완료!');
+        console.log(`📁 파일: ${outputFile}`);
+        console.log(`📊 크기: ${sizeKB} KB`);
+        console.log(`📄 슬라이드: ${htmlFiles.length}장`);
+    } catch (error) {
+        console.error('\n❌ PPTX 저장 실패:', error.message);
+        process.exit(1);
+    }
+}
+
+main().catch(console.error);

.claude/skills/storyboard-generator/scripts/generate-storyboard.js

@@ -0,0 +1,761 @@
+/**
+ * 스토리보드 PPTX 자동 생성 스크립트
+ * 텍스트 기반 인터뷰/기획 문서를 분석하여 IA + 화면 설계 스토리보드 생성
+ *
+ * 사용법:
+ *   node generate-storyboard.js --input <입력파일> --output <출력파일.pptx>
+ *   node generate-storyboard.js --config <설정파일.json>
+ */
+
+const PptxGenJS = require('pptxgenjs');
+const fs = require('fs');
+const path = require('path');
+
+// ========================================
+// 색상 팔레트 정의 (# 없이)
+// ========================================
+const colors = {
+    primary: '0d9488',      // Teal
+    secondary: '1e293b',    // Slate 800
+    accent: '95C11F',       // 라임 그린 (Description용)
+    warning: 'f59e0b',      // 경고
+    danger: 'dc2626',       // 위험
+    white: 'FFFFFF',
+    lightGray: 'f1f5f9',
+    darkGray: '64748b',
+    black: '1a1a1a',
+    wireframeBg: 'f8fafc',
+    wireframeBorder: 'e2e8f0'
+};
+
+// ========================================
+// 텍스트 파서 클래스
+// ========================================
+class TextParser {
+    constructor(content) {
+        this.content = content;
+        this.sections = [];
+        this.metadata = {};
+    }
+
+    parse() {
+        this.extractMetadata();
+        this.extractSections();
+        this.extractMenuStructure();
+        this.extractScreens();
+        return this;
+    }
+
+    extractMetadata() {
+        // 프로젝트명 추출
+        const projectMatch = this.content.match(/프로젝트[명\s]*[:：]\s*(.+)/i) ||
+                            this.content.match(/##\s*(.+?)\s*(프로젝트|시스템|기획)/i) ||
+                            this.content.match(/주제[:：]\s*(.+)/i);
+
+        if (projectMatch) {
+            this.metadata.projectName = projectMatch[1].trim();
+        }
+
+        // 날짜 추출
+        const dateMatch = this.content.match(/(\d{4})[.\-/년](\d{1,2})[.\-/월](\d{1,2})/);
+        if (dateMatch) {
+            this.metadata.date = `${dateMatch[1]}.${dateMatch[2].padStart(2, '0')}.${dateMatch[3].padStart(2, '0')}`;
+        } else {
+            const today = new Date();
+            this.metadata.date = `${today.getFullYear()}.${String(today.getMonth() + 1).padStart(2, '0')}.${String(today.getDate()).padStart(2, '0')}`;
+        }
+
+        // 참석자/작성자 추출
+        const authorMatch = this.content.match(/참석자[:：]\s*(.+)/i) ||
+                           this.content.match(/작성자[:：]\s*(.+)/i);
+        if (authorMatch) {
+            this.metadata.author = authorMatch[1].trim();
+        }
+    }
+
+    extractSections() {
+        // === 섹션 === 패턴
+        const sectionPattern = /===\s*(.+?)\s*===/g;
+        let match;
+        while ((match = sectionPattern.exec(this.content)) !== null) {
+            this.sections.push({
+                title: match[1].trim(),
+                startIndex: match.index
+            });
+        }
+
+        // ## 섹션 패턴 (Markdown)
+        const mdSectionPattern = /^##\s+(.+)$/gm;
+        while ((match = mdSectionPattern.exec(this.content)) !== null) {
+            if (!this.sections.some(s => s.title === match[1].trim())) {
+                this.sections.push({
+                    title: match[1].trim(),
+                    startIndex: match.index
+                });
+            }
+        }
+    }
+
+    extractMenuStructure() {
+        this.metadata.menus = [];
+
+        // PPT 구성, 메뉴 구조 등에서 추출
+        const menuPatterns = [
+            /(\d+)\.\s*\*\*(.+?)\*\*/g,  // 1. **메뉴명**
+            /(\d+)\.\s*(.+?)(?:\n|$)/g,   // 1. 메뉴명
+            /-\s+(.+?)(?:\n|$)/g          // - 메뉴명
+        ];
+
+        // 주요 기능 섹션에서 메뉴 추출
+        const funcMatch = this.content.match(/주요\s*기능[^]*?(?=##|===|$)/i);
+        if (funcMatch) {
+            const lines = funcMatch[0].split('\n');
+            for (const line of lines) {
+                const itemMatch = line.match(/^\s*[-\d.]+\s*(.+)/);
+                if (itemMatch && itemMatch[1].trim().length > 0) {
+                    const menuName = itemMatch[1].replace(/\*\*/g, '').trim();
+                    if (menuName.length < 30) {
+                        this.metadata.menus.push(menuName);
+                    }
+                }
+            }
+        }
+    }
+
+    extractScreens() {
+        this.metadata.screens = [];
+
+        // 화면 관련 키워드 추출
+        const screenKeywords = ['화면', '페이지', '입력', '조회', '관리', '목록', '상세', '등록', '수정'];
+
+        for (const keyword of screenKeywords) {
+            const pattern = new RegExp(`(${keyword}[^\\n]{0,20})`, 'gi');
+            let match;
+            while ((match = pattern.exec(this.content)) !== null) {
+                const screenName = match[1].trim();
+                if (!this.metadata.screens.some(s => s.name === screenName) && screenName.length < 30) {
+                    this.metadata.screens.push({ name: screenName });
+                }
+            }
+        }
+    }
+}
+
+// ========================================
+// 스토리보드 생성기 클래스
+// ========================================
+class StoryboardGenerator {
+    constructor(config) {
+        this.config = config;
+        this.pptx = new PptxGenJS();
+        this.setupPresentation();
+    }
+
+    setupPresentation() {
+        // 레이아웃 설정 (16:9)
+        this.pptx.defineLayout({ name: 'CUSTOM_16x9', width: 10, height: 5.625 });
+        this.pptx.layout = 'CUSTOM_16x9';
+
+        // 메타데이터
+        this.pptx.title = this.config.projectName || '웹 기획서';
+        this.pptx.subject = '시스템 기획 및 UI/UX 설계';
+        this.pptx.author = this.config.author || 'SAM';
+        this.pptx.company = this.config.company || 'SAM';
+    }
+
+    // ----------------------------------------
+    // 슬라이드 1: 표지
+    // ----------------------------------------
+    createCoverSlide() {
+        const slide = this.pptx.addSlide();
+        slide.background = { color: colors.secondary };
+
+        // 상단 악센트 라인
+        slide.addShape('rect', {
+            x: 0, y: 0, w: 10, h: 0.1,
+            fill: { color: colors.primary }
+        });
+
+        // 로고
+        slide.addShape('rect', {
+            x: 0.5, y: 0.4, w: 1.2, h: 0.5,
+            fill: { color: colors.primary }
+        });
+        slide.addText(this.config.company || 'SAM', {
+            x: 0.5, y: 0.4, w: 1.2, h: 0.5,
+            fontSize: 16, bold: true, color: colors.white,
+            align: 'center', valign: 'middle'
+        });
+
+        // 메인 제목
+        slide.addText(this.config.projectName || '프로젝트', {
+            x: 0.5, y: 1.8, w: 9, h: 0.8,
+            fontSize: 40, bold: true, color: colors.white,
+            align: 'center'
+        });
+
+        // 부제목
+        slide.addText('웹 기획서 및 스토리보드', {
+            x: 0.5, y: 2.6, w: 9, h: 0.5,
+            fontSize: 22, color: colors.primary,
+            align: 'center'
+        });
+
+        // 버전 정보
+        slide.addText('Version D1.0', {
+            x: 0.5, y: 3.3, w: 9, h: 0.3,
+            fontSize: 14, color: colors.darkGray,
+            align: 'center'
+        });
+
+        // 하단 정보
+        slide.addText(`${this.config.date || new Date().toISOString().split('T')[0].replace(/-/g, '.')} | ${this.config.author || '기획팀'}`, {
+            x: 0.5, y: 5, w: 9, h: 0.3,
+            fontSize: 12, color: colors.darkGray,
+            align: 'center'
+        });
+
+        console.log('✅ 슬라이드 1: 표지 생성 완료');
+    }
+
+    // ----------------------------------------
+    // 슬라이드 2: Document History
+    // ----------------------------------------
+    createHistorySlide() {
+        const slide = this.pptx.addSlide();
+        slide.background = { color: colors.white };
+
+        // 헤더
+        slide.addShape('rect', {
+            x: 0, y: 0, w: 10, h: 0.7,
+            fill: { color: colors.secondary }
+        });
+        slide.addText('Document History', {
+            x: 0.5, y: 0.15, w: 5, h: 0.4,
+            fontSize: 20, bold: true, color: colors.white
+        });
+
+        // 히스토리 테이블
+        const historyData = [
+            ['날짜', '버전', '주요 내용', '상세 내용', '비고'],
+            [this.config.date || '', 'D1.0', '초안 작성', `${this.config.projectName || '프로젝트'} 기획서 초안 작성`, ''],
+            ['', '', '', '', ''],
+            ['', '', '', '', '']
+        ];
+
+        slide.addTable(historyData, {
+            x: 0.5, y: 1.2, w: 9, h: 2.5,
+            fontSize: 10,
+            color: colors.secondary,
+            border: { pt: 0.5, color: colors.darkGray },
+            colW: [1.2, 0.8, 1.5, 4, 1.5],
+            align: 'center',
+            valign: 'middle'
+        });
+
+        console.log('✅ 슬라이드 2: Document History 생성 완료');
+    }
+
+    // ----------------------------------------
+    // 슬라이드 3: 목차
+    // ----------------------------------------
+    createTOCSlide() {
+        const slide = this.pptx.addSlide();
+        slide.background = { color: colors.white };
+
+        // 헤더
+        slide.addShape('rect', {
+            x: 0, y: 0, w: 10, h: 0.7,
+            fill: { color: colors.secondary }
+        });
+        slide.addText('목차 (Table of Contents)', {
+            x: 0.5, y: 0.15, w: 5, h: 0.4,
+            fontSize: 20, bold: true, color: colors.white
+        });
+
+        const tocItems = this.config.tocItems || [
+            { num: '01', title: '프로젝트 개요', desc: '시스템 목적 및 범위' },
+            { num: '02', title: '메뉴 구조 (IA)', desc: 'Information Architecture' },
+            { num: '03', title: '화면 설계', desc: '상세 스토리보드' }
+        ];
+
+        tocItems.forEach((item, idx) => {
+            const y = 1.1 + idx * 0.7;
+
+            // 번호 박스
+            slide.addShape('rect', {
+                x: 0.8, y: y, w: 0.6, h: 0.5,
+                fill: { color: colors.primary }
+            });
+            slide.addText(item.num, {
+                x: 0.8, y: y, w: 0.6, h: 0.5,
+                fontSize: 14, bold: true, color: colors.white,
+                align: 'center', valign: 'middle'
+            });
+
+            // 제목
+            slide.addText(item.title, {
+                x: 1.6, y: y, w: 3, h: 0.5,
+                fontSize: 14, bold: true, color: colors.secondary,
+                valign: 'middle'
+            });
+
+            // 설명
+            slide.addText(item.desc, {
+                x: 4.8, y: y, w: 4, h: 0.5,
+                fontSize: 11, color: colors.darkGray,
+                valign: 'middle'
+            });
+        });
+
+        console.log('✅ 슬라이드 3: 목차 생성 완료');
+    }
+
+    // ----------------------------------------
+    // 슬라이드 4: 프로젝트 개요
+    // ----------------------------------------
+    createOverviewSlide() {
+        const slide = this.pptx.addSlide();
+        slide.background = { color: colors.white };
+
+        // 헤더
+        slide.addShape('rect', {
+            x: 0, y: 0, w: 10, h: 0.7,
+            fill: { color: colors.secondary }
+        });
+        slide.addText('01. 프로젝트 개요', {
+            x: 0.5, y: 0.15, w: 5, h: 0.4,
+            fontSize: 20, bold: true, color: colors.white
+        });
+
+        // 목적
+        slide.addText('프로젝트 목적', {
+            x: 0.5, y: 1, w: 4, h: 0.4,
+            fontSize: 14, bold: true, color: colors.secondary
+        });
+
+        slide.addShape('rect', {
+            x: 0.5, y: 1.4, w: 4.3, h: 1.8,
+            fill: { color: colors.lightGray }
+        });
+
+        slide.addText(this.config.purpose || '업무 프로세스를 시스템화하여\n효율성 향상 및 자동화 구현', {
+            x: 0.7, y: 1.5, w: 4, h: 1.6,
+            fontSize: 11, valign: 'top'
+        });
+
+        // 주요 기능
+        slide.addText('주요 기능', {
+            x: 5.2, y: 1, w: 4, h: 0.4,
+            fontSize: 14, bold: true, color: colors.secondary
+        });
+
+        const features = this.config.features || [
+            '데이터 입력 및 관리',
+            '자동 계산 및 처리',
+            '보고서 생성',
+            '이력 관리'
+        ];
+
+        features.slice(0, 5).forEach((feat, idx) => {
+            slide.addText('✓ ' + feat, {
+                x: 5.2, y: 1.4 + idx * 0.35, w: 4.3, h: 0.35,
+                fontSize: 10, color: colors.secondary
+            });
+        });
+
+        // 기대 효과
+        slide.addText('기대 효과', {
+            x: 0.5, y: 3.5, w: 9, h: 0.4,
+            fontSize: 14, bold: true, color: colors.secondary
+        });
+
+        const effects = this.config.effects || [
+            { icon: '⏱️', title: '시간 단축', desc: '업무 처리 시간 감소' },
+            { icon: '✅', title: '정확성 향상', desc: '오류 최소화' },
+            { icon: '📊', title: '표준화', desc: '프로세스 통일' }
+        ];
+
+        effects.forEach((eff, idx) => {
+            const x = 0.5 + idx * 3.1;
+            slide.addShape('rect', {
+                x: x, y: 3.9, w: 2.9, h: 1.4,
+                fill: { color: colors.lightGray },
+                line: { color: colors.primary, width: 1 }
+            });
+            slide.addText(eff.icon, {
+                x: x, y: 4, w: 2.9, h: 0.5,
+                fontSize: 24, align: 'center'
+            });
+            slide.addText(eff.title, {
+                x: x, y: 4.5, w: 2.9, h: 0.35,
+                fontSize: 11, bold: true, color: colors.secondary,
+                align: 'center'
+            });
+            slide.addText(eff.desc, {
+                x: x, y: 4.85, w: 2.9, h: 0.35,
+                fontSize: 9, color: colors.darkGray,
+                align: 'center'
+            });
+        });
+
+        console.log('✅ 슬라이드 4: 프로젝트 개요 생성 완료');
+    }
+
+    // ----------------------------------------
+    // 슬라이드 5: 메뉴 구조 (IA)
+    // ----------------------------------------
+    createIASlide() {
+        const slide = this.pptx.addSlide();
+        slide.background = { color: colors.white };
+
+        // 헤더
+        slide.addShape('rect', {
+            x: 0, y: 0, w: 10, h: 0.7,
+            fill: { color: colors.secondary }
+        });
+        slide.addText('02. 메뉴 구조 (Information Architecture)', {
+            x: 0.5, y: 0.15, w: 6, h: 0.4,
+            fontSize: 20, bold: true, color: colors.white
+        });
+
+        // 루트 노드
+        const rootName = this.config.projectName ?
+            this.config.projectName.replace(/시스템|프로젝트|기획/g, '').trim() :
+            '시스템';
+
+        slide.addShape('rect', {
+            x: 4, y: 1, w: 2, h: 0.6,
+            fill: { color: colors.secondary }
+        });
+        slide.addText(rootName, {
+            x: 4, y: 1, w: 2, h: 0.6,
+            fontSize: 12, bold: true, color: colors.white,
+            align: 'center', valign: 'middle'
+        });
+
+        // 연결선
+        slide.addShape('line', {
+            x: 5, y: 1.6, w: 0, h: 0.4,
+            line: { color: colors.darkGray, width: 1 }
+        });
+        slide.addShape('line', {
+            x: 1.5, y: 2, w: 7, h: 0,
+            line: { color: colors.darkGray, width: 1 }
+        });
+
+        // 1차 메뉴
+        const level1 = this.config.mainMenus || [
+            { title: '메뉴 1', children: ['하위 1-1', '하위 1-2'] },
+            { title: '메뉴 2', children: ['하위 2-1', '하위 2-2'] },
+            { title: '메뉴 3', children: ['하위 3-1', '하위 3-2'] },
+            { title: '메뉴 4', children: ['하위 4-1', '하위 4-2'] }
+        ];
+
+        const menuCount = Math.min(level1.length, 4);
+        const menuWidth = 2.2;
+        const totalWidth = menuCount * menuWidth + (menuCount - 1) * 0.1;
+        const startX = (10 - totalWidth) / 2;
+
+        level1.slice(0, 4).forEach((menu, idx) => {
+            const x = startX + idx * (menuWidth + 0.1);
+
+            // 세로 연결선
+            slide.addShape('line', {
+                x: x + menuWidth / 2, y: 2, w: 0, h: 0.3,
+                line: { color: colors.darkGray, width: 1 }
+            });
+
+            // 1차 메뉴 박스
+            slide.addShape('rect', {
+                x: x, y: 2.3, w: menuWidth, h: 0.5,
+                fill: { color: colors.primary }
+            });
+            slide.addText(menu.title, {
+                x: x, y: 2.3, w: menuWidth, h: 0.5,
+                fontSize: 11, bold: true, color: colors.white,
+                align: 'center', valign: 'middle'
+            });
+
+            // 2차 메뉴
+            (menu.children || []).slice(0, 3).forEach((child, cIdx) => {
+                const y = 3 + cIdx * 0.45;
+                slide.addShape('rect', {
+                    x: x, y: y, w: menuWidth, h: 0.4,
+                    fill: { color: colors.lightGray },
+                    line: { color: colors.wireframeBorder, width: 0.5 }
+                });
+                slide.addText(child, {
+                    x: x, y: y, w: menuWidth, h: 0.4,
+                    fontSize: 9, color: colors.secondary,
+                    align: 'center', valign: 'middle'
+                });
+            });
+        });
+
+        console.log('✅ 슬라이드 5: 메뉴 구조 (IA) 생성 완료');
+    }
+
+    // ----------------------------------------
+    // 스토리보드 슬라이드 (화면 설계)
+    // ----------------------------------------
+    createStoryboardSlide(screenInfo, pageNum) {
+        const slide = this.pptx.addSlide();
+        slide.background = { color: colors.white };
+
+        // 헤더 정보 테이블
+        const headerData = [
+            ['Task Name', screenInfo.taskName || '', 'Ver.', 'D1.0', 'Page', String(pageNum)],
+            ['Route', screenInfo.route || '', 'Screen Name', screenInfo.screenName || '', 'Screen ID', screenInfo.screenId || '']
+        ];
+
+        slide.addTable(headerData, {
+            x: 0.2, y: 0.1, w: 9.6, h: 0.5,
+            fontSize: 8,
+            color: colors.secondary,
+            border: { pt: 0.5, color: colors.darkGray },
+            fill: { color: colors.lightGray },
+            colW: [0.8, 2.5, 0.8, 2.5, 0.8, 2.2]
+        });
+
+        // 와이어프레임 영역 (좌측)
+        slide.addShape('rect', {
+            x: 0.2, y: 0.7, w: 6.8, h: 4.75,
+            fill: { color: colors.wireframeBg },
+            line: { color: colors.wireframeBorder, width: 1 }
+        });
+
+        // 와이어프레임 헤더
+        slide.addShape('rect', {
+            x: 0.3, y: 0.8, w: 6.6, h: 0.4,
+            fill: { color: colors.secondary }
+        });
+        slide.addText(this.config.projectName || '시스템', {
+            x: 0.4, y: 0.8, w: 2, h: 0.4,
+            fontSize: 10, bold: true, color: colors.white,
+            valign: 'middle'
+        });
+
+        // 와이어프레임 내용
+        if (screenInfo.wireframeElements) {
+            screenInfo.wireframeElements.forEach(el => {
+                if (el.type === 'rect') {
+                    slide.addShape('rect', {
+                        x: el.x, y: el.y, w: el.w, h: el.h,
+                        fill: { color: el.fill || colors.white },
+                        line: { color: colors.wireframeBorder, width: 0.5 }
+                    });
+                }
+                if (el.text) {
+                    slide.addText(el.text, {
+                        x: el.x, y: el.y, w: el.w, h: el.h,
+                        fontSize: el.fontSize || 8,
+                        color: el.color || colors.secondary,
+                        align: el.align || 'center',
+                        valign: 'middle',
+                        bold: el.bold || false
+                    });
+                }
+            });
+        } else {
+            // 기본 와이어프레임 구조
+            // 사이드바
+            slide.addShape('rect', {
+                x: 0.3, y: 1.3, w: 1.2, h: 4,
+                fill: { color: colors.lightGray }
+            });
+            slide.addText('메뉴', {
+                x: 0.3, y: 1.4, w: 1.2, h: 0.3,
+                fontSize: 8, color: colors.secondary, align: 'center'
+            });
+
+            // 메인 콘텐츠 영역
+            slide.addShape('rect', {
+                x: 1.6, y: 1.3, w: 5.3, h: 0.4,
+                fill: { color: colors.white }
+            });
+            slide.addText(screenInfo.screenName || '화면 제목', {
+                x: 1.6, y: 1.3, w: 5.3, h: 0.4,
+                fontSize: 12, bold: true, color: colors.secondary, align: 'left'
+            });
+
+            // 콘텐츠 영역 플레이스홀더
+            slide.addShape('rect', {
+                x: 1.6, y: 1.8, w: 5.3, h: 3.4,
+                fill: { color: colors.white },
+                line: { color: colors.wireframeBorder, width: 0.5, dashType: 'dash' }
+            });
+            slide.addText('콘텐츠 영역', {
+                x: 1.6, y: 3.2, w: 5.3, h: 0.4,
+                fontSize: 10, color: colors.darkGray, align: 'center'
+            });
+        }
+
+        // Description 영역 (우측)
+        slide.addShape('rect', {
+            x: 7.1, y: 0.7, w: 2.7, h: 4.75,
+            fill: { color: colors.black }
+        });
+
+        // Description 헤더
+        slide.addShape('rect', {
+            x: 7.2, y: 0.8, w: 2.5, h: 0.35,
+            fill: { color: colors.accent }
+        });
+        slide.addText('Description', {
+            x: 7.2, y: 0.8, w: 2.5, h: 0.35,
+            fontSize: 9, bold: true, color: colors.white,
+            align: 'center', valign: 'middle'
+        });
+
+        // Description 항목
+        const descriptions = screenInfo.descriptions || [
+            { title: '기능 1', content: '기능 설명 1' },
+            { title: '기능 2', content: '기능 설명 2' },
+            { title: '기능 3', content: '기능 설명 3' }
+        ];
+
+        descriptions.slice(0, 5).forEach((desc, idx) => {
+            const y = 1.25 + idx * 0.85;
+
+            // 번호 원
+            slide.addShape('ellipse', {
+                x: 7.25, y: y, w: 0.25, h: 0.25,
+                fill: { color: colors.accent }
+            });
+            slide.addText(String(idx + 1), {
+                x: 7.25, y: y, w: 0.25, h: 0.25,
+                fontSize: 7, bold: true, color: colors.white,
+                align: 'center', valign: 'middle'
+            });
+
+            // 제목
+            slide.addText(desc.title, {
+                x: 7.55, y: y, w: 2.1, h: 0.25,
+                fontSize: 8, bold: true, color: colors.white
+            });
+
+            // 설명
+            slide.addText(desc.content, {
+                x: 7.25, y: y + 0.28, w: 2.4, h: 0.5,
+                fontSize: 7, color: colors.darkGray
+            });
+        });
+
+        console.log(`✅ 슬라이드 ${pageNum}: ${screenInfo.screenName || '화면'} 생성 완료`);
+    }
+
+    // ----------------------------------------
+    // 전체 생성
+    // ----------------------------------------
+    async generate() {
+        console.log('🚀 스토리보드 PPTX 생성 시작\n');
+
+        try {
+            // 기본 슬라이드
+            this.createCoverSlide();
+            this.createHistorySlide();
+            this.createTOCSlide();
+            this.createOverviewSlide();
+            this.createIASlide();
+
+            // 스토리보드 슬라이드
+            const screens = this.config.screens || [];
+            screens.forEach((screen, idx) => {
+                this.createStoryboardSlide(screen, idx + 6);
+            });
+
+            // 파일 저장
+            const outputPath = this.config.outputPath || 'storyboard.pptx';
+            const outputDir = path.dirname(outputPath);
+
+            if (!fs.existsSync(outputDir)) {
+                fs.mkdirSync(outputDir, { recursive: true });
+            }
+
+            await this.pptx.writeFile({ fileName: outputPath });
+
+            // 결과 출력
+            const stats = fs.statSync(outputPath);
+            console.log('\n🎉 스토리보드 PPTX 생성 완료!');
+            console.log(`📁 저장 위치: ${outputPath}`);
+            console.log(`📏 파일 크기: ${(stats.size / 1024).toFixed(1)} KB`);
+            console.log(`📊 총 슬라이드: ${5 + screens.length}장`);
+
+            return outputPath;
+        } catch (error) {
+            console.error('❌ 생성 실패:', error.message);
+            throw error;
+        }
+    }
+}
+
+// ========================================
+// CLI 실행
+// ========================================
+async function main() {
+    const args = process.argv.slice(2);
+
+    // 인자 파싱
+    let inputFile = null;
+    let outputFile = null;
+    let configFile = null;
+
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--input' && args[i + 1]) {
+            inputFile = args[i + 1];
+            i++;
+        } else if (args[i] === '--output' && args[i + 1]) {
+            outputFile = args[i + 1];
+            i++;
+        } else if (args[i] === '--config' && args[i + 1]) {
+            configFile = args[i + 1];
+            i++;
+        }
+    }
+
+    let config = {};
+
+    // 설정 파일이 있으면 로드
+    if (configFile && fs.existsSync(configFile)) {
+        config = JSON.parse(fs.readFileSync(configFile, 'utf-8'));
+        console.log(`📄 설정 파일 로드: ${configFile}`);
+    }
+
+    // 입력 파일 분석
+    if (inputFile && fs.existsSync(inputFile)) {
+        console.log(`📄 입력 파일 분석: ${inputFile}`);
+        const content = fs.readFileSync(inputFile, 'utf-8');
+        const parser = new TextParser(content).parse();
+
+        // 파싱 결과를 config에 병합
+        if (parser.metadata.projectName) {
+            config.projectName = config.projectName || parser.metadata.projectName;
+        }
+        if (parser.metadata.date) {
+            config.date = config.date || parser.metadata.date;
+        }
+        if (parser.metadata.author) {
+            config.author = config.author || parser.metadata.author;
+        }
+    }
+
+    // 출력 파일 설정
+    if (outputFile) {
+        config.outputPath = outputFile;
+    } else if (!config.outputPath) {
+        config.outputPath = 'storyboard.pptx';
+    }
+
+    // 생성
+    const generator = new StoryboardGenerator(config);
+    await generator.generate();
+}
+
+// 모듈 내보내기
+module.exports = { TextParser, StoryboardGenerator, colors };
+
+// CLI 실행
+if (require.main === module) {
+    main().catch(console.error);
+}

.claude/skills/storyboard-generator/scripts/package-lock.json

@@ -0,0 +1,765 @@
+{
+  "name": "scripts",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "scripts",
+      "version": "1.0.0",
+      "license": "ISC",
+      "dependencies": {
+        "playwright": "^1.57.0",
+        "pptxgenjs": "^4.0.1",
+        "sharp": "^0.34.5"
+      }
+    },
+    "node_modules/@emnapi/runtime": {
+      "version": "1.8.1",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.8.1.tgz",
+      "integrity": "sha512-mehfKSMWjjNol8659Z8KxEMrdSJDDot5SXMq00dM8BN4o+CLNXQ0xH2V7EchNHV4RmbZLmmPdEaXZc5H2FXmDg==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@img/colour": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.0.0.tgz",
+      "integrity": "sha512-A5P/LfWGFSl6nsckYtjw9da+19jB8hkJ6ACTGcDfEJ0aE+l2n2El7dsVM7UVHZQ9s2lmYMWlrS21YLy2IR1LUw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@img/sharp-darwin-arm64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.34.5.tgz",
+      "integrity": "sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-darwin-arm64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-darwin-x64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.34.5.tgz",
+      "integrity": "sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-darwin-x64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-libvips-darwin-arm64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.2.4.tgz",
+      "integrity": "sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-darwin-x64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.2.4.tgz",
+      "integrity": "sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-arm": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.2.4.tgz",
+      "integrity": "sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-arm64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.2.4.tgz",
+      "integrity": "sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-ppc64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.2.4.tgz",
+      "integrity": "sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-riscv64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.2.4.tgz",
+      "integrity": "sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-s390x": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.2.4.tgz",
+      "integrity": "sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==",
+      "cpu": [
+        "s390x"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-x64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.2.4.tgz",
+      "integrity": "sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linuxmusl-arm64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.2.4.tgz",
+      "integrity": "sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linuxmusl-x64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.2.4.tgz",
+      "integrity": "sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-linux-arm": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.34.5.tgz",
+      "integrity": "sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-arm": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-arm64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.34.5.tgz",
+      "integrity": "sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-arm64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-ppc64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.34.5.tgz",
+      "integrity": "sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-ppc64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-riscv64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.34.5.tgz",
+      "integrity": "sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==",
+      "cpu": [
+        "riscv64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-riscv64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-s390x": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.34.5.tgz",
+      "integrity": "sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==",
+      "cpu": [
+        "s390x"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-s390x": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-x64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.34.5.tgz",
+      "integrity": "sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-x64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linuxmusl-arm64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.34.5.tgz",
+      "integrity": "sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linuxmusl-arm64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linuxmusl-x64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.34.5.tgz",
+      "integrity": "sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linuxmusl-x64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-wasm32": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.34.5.tgz",
+      "integrity": "sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==",
+      "cpu": [
+        "wasm32"
+      ],
+      "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/runtime": "^1.7.0"
+      },
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-arm64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.34.5.tgz",
+      "integrity": "sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-ia32": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.34.5.tgz",
+      "integrity": "sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==",
+      "cpu": [
+        "ia32"
+      ],
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-x64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.34.5.tgz",
+      "integrity": "sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "22.19.3",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.3.tgz",
+      "integrity": "sha512-1N9SBnWYOJTrNZCdh/yJE+t910Y128BoyY+zBLWhL3r0TYzlTmFdXrPwHL9DyFZmlEXNQQolTZh3KHV31QDhyA==",
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "node_modules/core-util-is": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz",
+      "integrity": "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==",
+      "license": "MIT"
+    },
+    "node_modules/detect-libc": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/https": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/https/-/https-1.0.0.tgz",
+      "integrity": "sha512-4EC57ddXrkaF0x83Oj8sM6SLQHAWXw90Skqu2M4AEWENZ3F02dFJE/GARA8igO79tcgYqGrD7ae4f5L3um2lgg==",
+      "license": "ISC"
+    },
+    "node_modules/image-size": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/image-size/-/image-size-1.2.1.tgz",
+      "integrity": "sha512-rH+46sQJ2dlwfjfhCyNx5thzrv+dtmBIhPHk0zgRUukHzZ/kRueTJXoYYsclBaKcSMBWuGbOFXtioLpzTb5euw==",
+      "license": "MIT",
+      "dependencies": {
+        "queue": "6.0.2"
+      },
+      "bin": {
+        "image-size": "bin/image-size.js"
+      },
+      "engines": {
+        "node": ">=16.x"
+      }
+    },
+    "node_modules/immediate": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/immediate/-/immediate-3.0.6.tgz",
+      "integrity": "sha512-XXOFtyqDjNDAQxVfYxuF7g9Il/IbWmmlQg2MYKOH8ExIT1qg6xc4zyS3HaEEATgs1btfzxq15ciUiY7gjSXRGQ==",
+      "license": "MIT"
+    },
+    "node_modules/inherits": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
+      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
+      "license": "ISC"
+    },
+    "node_modules/isarray": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz",
+      "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ==",
+      "license": "MIT"
+    },
+    "node_modules/jszip": {
+      "version": "3.10.1",
+      "resolved": "https://registry.npmjs.org/jszip/-/jszip-3.10.1.tgz",
+      "integrity": "sha512-xXDvecyTpGLrqFrvkrUSoxxfJI5AH7U8zxxtVclpsUtMCq4JQ290LY8AW5c7Ggnr/Y/oK+bQMbqK2qmtk3pN4g==",
+      "license": "(MIT OR GPL-3.0-or-later)",
+      "dependencies": {
+        "lie": "~3.3.0",
+        "pako": "~1.0.2",
+        "readable-stream": "~2.3.6",
+        "setimmediate": "^1.0.5"
+      }
+    },
+    "node_modules/lie": {
+      "version": "3.3.0",
+      "resolved": "https://registry.npmjs.org/lie/-/lie-3.3.0.tgz",
+      "integrity": "sha512-UaiMJzeWRlEujzAuw5LokY1L5ecNQYZKfmyZ9L7wDHb/p5etKaxXhohBcrw0EYby+G/NA52vRSN4N39dxHAIwQ==",
+      "license": "MIT",
+      "dependencies": {
+        "immediate": "~3.0.5"
+      }
+    },
+    "node_modules/pako": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/pako/-/pako-1.0.11.tgz",
+      "integrity": "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==",
+      "license": "(MIT AND Zlib)"
+    },
+    "node_modules/playwright": {
+      "version": "1.57.0",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.57.0.tgz",
+      "integrity": "sha512-ilYQj1s8sr2ppEJ2YVadYBN0Mb3mdo9J0wQ+UuDhzYqURwSoW4n1Xs5vs7ORwgDGmyEh33tRMeS8KhdkMoLXQw==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.57.0"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.57.0",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.57.0.tgz",
+      "integrity": "sha512-agTcKlMw/mjBWOnD6kFZttAAGHgi/Nw0CZ2o6JqWSbMlI219lAFLZZCyqByTsvVAJq5XA5H8cA6PrvBRpBWEuQ==",
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/pptxgenjs": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/pptxgenjs/-/pptxgenjs-4.0.1.tgz",
+      "integrity": "sha512-TeJISr8wouAuXw4C1F/mC33xbZs/FuEG6nH9FG1Zj+nuPcGMP5YRHl6X+j3HSUnS1f3at6k75ZZXPMZlA5Lj9A==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "^22.8.1",
+        "https": "^1.0.0",
+        "image-size": "^1.2.1",
+        "jszip": "^3.10.1"
+      }
+    },
+    "node_modules/process-nextick-args": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz",
+      "integrity": "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==",
+      "license": "MIT"
+    },
+    "node_modules/queue": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/queue/-/queue-6.0.2.tgz",
+      "integrity": "sha512-iHZWu+q3IdFZFX36ro/lKBkSvfkztY5Y7HMiPlOUjhupPcG2JMfst2KKEpu5XndviX/3UhFbRngUPNKtgvtZiA==",
+      "license": "MIT",
+      "dependencies": {
+        "inherits": "~2.0.3"
+      }
+    },
+    "node_modules/readable-stream": {
+      "version": "2.3.8",
+      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz",
+      "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==",
+      "license": "MIT",
+      "dependencies": {
+        "core-util-is": "~1.0.0",
+        "inherits": "~2.0.3",
+        "isarray": "~1.0.0",
+        "process-nextick-args": "~2.0.0",
+        "safe-buffer": "~5.1.1",
+        "string_decoder": "~1.1.1",
+        "util-deprecate": "~1.0.1"
+      }
+    },
+    "node_modules/safe-buffer": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
+      "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==",
+      "license": "MIT"
+    },
+    "node_modules/semver": {
+      "version": "7.7.3",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz",
+      "integrity": "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==",
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/setimmediate": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/setimmediate/-/setimmediate-1.0.5.tgz",
+      "integrity": "sha512-MATJdZp8sLqDl/68LfQmbP8zKPLQNV6BIZoIgrscFDQ+RsvK/BxeDQOgyxKKoh0y/8h3BqVFnCqQ/gd+reiIXA==",
+      "license": "MIT"
+    },
+    "node_modules/sharp": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.34.5.tgz",
+      "integrity": "sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==",
+      "hasInstallScript": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@img/colour": "^1.0.0",
+        "detect-libc": "^2.1.2",
+        "semver": "^7.7.3"
+      },
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-darwin-arm64": "0.34.5",
+        "@img/sharp-darwin-x64": "0.34.5",
+        "@img/sharp-libvips-darwin-arm64": "1.2.4",
+        "@img/sharp-libvips-darwin-x64": "1.2.4",
+        "@img/sharp-libvips-linux-arm": "1.2.4",
+        "@img/sharp-libvips-linux-arm64": "1.2.4",
+        "@img/sharp-libvips-linux-ppc64": "1.2.4",
+        "@img/sharp-libvips-linux-riscv64": "1.2.4",
+        "@img/sharp-libvips-linux-s390x": "1.2.4",
+        "@img/sharp-libvips-linux-x64": "1.2.4",
+        "@img/sharp-libvips-linuxmusl-arm64": "1.2.4",
+        "@img/sharp-libvips-linuxmusl-x64": "1.2.4",
+        "@img/sharp-linux-arm": "0.34.5",
+        "@img/sharp-linux-arm64": "0.34.5",
+        "@img/sharp-linux-ppc64": "0.34.5",
+        "@img/sharp-linux-riscv64": "0.34.5",
+        "@img/sharp-linux-s390x": "0.34.5",
+        "@img/sharp-linux-x64": "0.34.5",
+        "@img/sharp-linuxmusl-arm64": "0.34.5",
+        "@img/sharp-linuxmusl-x64": "0.34.5",
+        "@img/sharp-wasm32": "0.34.5",
+        "@img/sharp-win32-arm64": "0.34.5",
+        "@img/sharp-win32-ia32": "0.34.5",
+        "@img/sharp-win32-x64": "0.34.5"
+      }
+    },
+    "node_modules/string_decoder": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
+      "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
+      "license": "MIT",
+      "dependencies": {
+        "safe-buffer": "~5.1.0"
+      }
+    },
+    "node_modules/tslib": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+      "license": "0BSD",
+      "optional": true
+    },
+    "node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "license": "MIT"
+    },
+    "node_modules/util-deprecate": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
+      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
+      "license": "MIT"
+    }
+  }
+}

.claude/skills/storyboard-generator/scripts/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "scripts",
+  "version": "1.0.0",
+  "description": "",
+  "main": "generate-storyboard.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "playwright": "^1.57.0",
+    "pptxgenjs": "^4.0.1",
+    "sharp": "^0.34.5"
+  }
+}

.claude/skills/storyboard-generator/templates/storyboard-slide.html

@@ -0,0 +1,349 @@
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+    <meta charset="UTF-8">
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css">
+    <style>
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        body {
+            width: 720pt;
+            height: 405pt;
+            font-family: 'Pretendard', 'Malgun Gothic', sans-serif;
+            background: #ffffff;
+            display: flex;
+            flex-direction: column;
+        }
+
+        /* Header Info Table */
+        .header-table {
+            display: flex;
+            height: 36pt;
+            border: 0.5pt solid #64748b;
+            margin: 4pt 8pt;
+        }
+        .header-row {
+            display: flex;
+            flex: 1;
+        }
+        .header-cell {
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            border-right: 0.5pt solid #64748b;
+            background: #f1f5f9;
+            padding: 0 4pt;
+        }
+        .header-cell:last-child { border-right: none; }
+        .header-cell.label {
+            width: 60pt;
+            background: #e2e8f0;
+        }
+        .header-cell.value {
+            flex: 1;
+        }
+        .header-cell p {
+            font-size: 6pt;
+            color: #1e293b;
+        }
+
+        /* Main Content Area */
+        .main-content {
+            display: flex;
+            flex: 1;
+            padding: 0 8pt 8pt 8pt;
+            gap: 8pt;
+        }
+
+        /* Wireframe Area */
+        .wireframe-area {
+            flex: 1;
+            background: #f8fafc;
+            border: 0.5pt solid #e2e8f0;
+            border-radius: 2pt;
+            display: flex;
+            flex-direction: column;
+            overflow: hidden;
+        }
+
+        .wireframe-header {
+            background: #1e293b;
+            padding: 6pt 10pt;
+        }
+        .wireframe-header p {
+            font-size: 8pt;
+            font-weight: 600;
+            color: #ffffff;
+        }
+
+        .wireframe-body {
+            flex: 1;
+            display: flex;
+            padding: 8pt;
+            gap: 8pt;
+        }
+
+        /* Sidebar */
+        .sidebar {
+            width: 70pt;
+            background: #f1f5f9;
+            border-radius: 2pt;
+            padding: 6pt;
+        }
+        .sidebar-item {
+            padding: 4pt 6pt;
+            margin-bottom: 3pt;
+            border-radius: 2pt;
+            background: #ffffff;
+        }
+        .sidebar-item.active {
+            background: #0d9488;
+        }
+        .sidebar-item p {
+            font-size: 5pt;
+            color: #1e293b;
+        }
+        .sidebar-item.active p {
+            color: #ffffff;
+            font-weight: 600;
+        }
+
+        /* Main Content */
+        .content-area {
+            flex: 1;
+            display: flex;
+            flex-direction: column;
+            gap: 8pt;
+        }
+
+        .section-title {
+            padding: 4pt 0;
+        }
+        .section-title p {
+            font-size: 8pt;
+            font-weight: 700;
+            color: #1e293b;
+        }
+
+        /* Cards Grid */
+        .cards-grid {
+            display: flex;
+            gap: 6pt;
+        }
+        .card {
+            flex: 1;
+            background: #f1f5f9;
+            border: 0.5pt solid #e2e8f0;
+            border-radius: 2pt;
+            overflow: hidden;
+        }
+        .card.selected {
+            border-color: #0d9488;
+            border-width: 1pt;
+        }
+        .card-header {
+            background: #1e293b;
+            padding: 4pt 6pt;
+        }
+        .card-header.primary {
+            background: #0d9488;
+        }
+        .card-header p {
+            font-size: 5pt;
+            color: #ffffff;
+            font-weight: 600;
+        }
+        .card-body {
+            padding: 6pt;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            min-height: 30pt;
+        }
+        .card-body p {
+            font-size: 7pt;
+            color: #1e293b;
+            font-weight: 600;
+        }
+
+        /* Table Style */
+        .data-table {
+            background: #1e293b;
+            border-radius: 2pt;
+            overflow: hidden;
+        }
+        .table-row {
+            display: flex;
+            border-bottom: 0.5pt solid #334155;
+        }
+        .table-row:last-child {
+            border-bottom: none;
+        }
+        .table-cell {
+            flex: 1;
+            padding: 4pt 8pt;
+            display: flex;
+            align-items: center;
+        }
+        .table-cell.label {
+            flex: 0 0 120pt;
+        }
+        .table-cell p {
+            font-size: 6pt;
+            color: #94a3b8;
+        }
+        .table-cell.value p {
+            color: #ffffff;
+        }
+        .table-cell.highlight p {
+            font-size: 10pt;
+            font-weight: 700;
+            color: #ffffff;
+        }
+        .table-cell.accent p {
+            color: #0d9488;
+            font-weight: 600;
+        }
+
+        /* Warning Box */
+        .warning-box {
+            background: #dc2626;
+            border-radius: 2pt;
+            padding: 6pt 8pt;
+        }
+        .warning-box p {
+            font-size: 5pt;
+            color: #ffffff;
+        }
+
+        /* Description Panel */
+        .description-panel {
+            width: 150pt;
+            background: #1a1a1a;
+            border-radius: 2pt;
+            padding: 8pt;
+            display: flex;
+            flex-direction: column;
+        }
+
+        .description-header {
+            background: #95C11F;
+            padding: 4pt 8pt;
+            border-radius: 2pt;
+            margin-bottom: 10pt;
+        }
+        .description-header p {
+            font-size: 7pt;
+            font-weight: 600;
+            color: #ffffff;
+            text-align: center;
+        }
+
+        .description-item {
+            margin-bottom: 12pt;
+        }
+        .description-item-header {
+            display: flex;
+            align-items: center;
+            gap: 6pt;
+            margin-bottom: 4pt;
+        }
+        .description-number {
+            width: 14pt;
+            height: 14pt;
+            background: #95C11F;
+            border-radius: 50%;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+        }
+        .description-number p {
+            font-size: 6pt;
+            font-weight: 700;
+            color: #ffffff;
+        }
+        .description-title p {
+            font-size: 6pt;
+            font-weight: 700;
+            color: #ffffff;
+        }
+        .description-content {
+            padding-left: 20pt;
+        }
+        .description-content p {
+            font-size: 5pt;
+            color: #9ca3af;
+            line-height: 1.4;
+        }
+    </style>
+</head>
+<body>
+    <!-- Header Info Table -->
+    <div class="header-table">
+        <div class="header-row" style="flex-direction: column;">
+            <div style="display: flex; flex: 1; border-bottom: 0.5pt solid #64748b;">
+                <div class="header-cell label"><p>Task Name</p></div>
+                <div class="header-cell value"><p>{{taskName}}</p></div>
+                <div class="header-cell label"><p>Ver.</p></div>
+                <div class="header-cell value" style="width: 60pt;"><p>D1.0</p></div>
+                <div class="header-cell label"><p>Page</p></div>
+                <div class="header-cell value" style="width: 40pt;"><p>{{page}}</p></div>
+            </div>
+            <div style="display: flex; flex: 1;">
+                <div class="header-cell label"><p>Route</p></div>
+                <div class="header-cell value"><p>{{route}}</p></div>
+                <div class="header-cell label"><p>Screen Name</p></div>
+                <div class="header-cell value"><p>{{screenName}}</p></div>
+                <div class="header-cell label"><p>Screen ID</p></div>
+                <div class="header-cell value" style="width: 80pt;"><p>{{screenId}}</p></div>
+            </div>
+        </div>
+    </div>
+
+    <!-- Main Content -->
+    <div class="main-content">
+        <!-- Wireframe Area -->
+        <div class="wireframe-area">
+            <div class="wireframe-header">
+                <p>{{systemName}}</p>
+            </div>
+            <div class="wireframe-body">
+                <!-- Sidebar -->
+                <div class="sidebar">
+                    {{#each menuItems}}
+                    <div class="sidebar-item {{#if active}}active{{/if}}">
+                        <p>{{name}}</p>
+                    </div>
+                    {{/each}}
+                </div>
+
+                <!-- Content -->
+                <div class="content-area">
+                    {{content}}
+                </div>
+            </div>
+        </div>
+
+        <!-- Description Panel -->
+        <div class="description-panel">
+            <div class="description-header">
+                <p>Description</p>
+            </div>
+            {{#each descriptions}}
+            <div class="description-item">
+                <div class="description-item-header">
+                    <div class="description-number">
+                        <p>{{index}}</p>
+                    </div>
+                    <div class="description-title">
+                        <p>{{title}}</p>
+                    </div>
+                </div>
+                <div class="description-content">
+                    <p>{{content}}</p>
+                </div>
+            </div>
+            {{/each}}
+        </div>
+    </div>
+</body>
+</html>

.claude/skills/system-debug-logger/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: system-debug-logger
+description: 애플리케이션에 에러 및 예외를 자동으로 캡처하는 디버그 로깅 기능을 추가합니다. 로깅 추가, 디버그 설정, 에러 추적 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# System Debug Logger
+
+애플리케이션에 체계적인 디버그 로깅 기능을 추가하는 스킬입니다.
+
+## 기능
+
+### 로깅 레벨
+- **ERROR**: 오류 및 예외 상황
+- **WARN**: 경고 및 잠재적 문제
+- **INFO**: 일반 정보성 메시지
+- **DEBUG**: 상세 디버깅 정보
+- **TRACE**: 매우 상세한 추적 정보
+
+### 캡처 대상
+- 예외 및 에러
+- API 요청/응답
+- 데이터베이스 쿼리
+- 성능 메트릭
+- 사용자 액션
+
+### 출력 형식
+- 콘솔 출력
+- 파일 로깅 (일별 롤링)
+- JSON 구조화 로그
+- 외부 서비스 전송 (선택)
+
+## 구현 패턴
+
+### JavaScript/Node.js
+```javascript
+const logger = {
+  levels: { ERROR: 0, WARN: 1, INFO: 2, DEBUG: 3, TRACE: 4 },
+  currentLevel: 2, // INFO
+
+  log(level, message, meta = {}) {
+    if (this.levels[level] <= this.currentLevel) {
+      const timestamp = new Date().toISOString();
+      const logEntry = {
+        timestamp,
+        level,
+        message,
+        ...meta
+      };
+      console.log(JSON.stringify(logEntry));
+    }
+  },
+
+  error(message, error = null) {
+    this.log('ERROR', message, {
+      error: error?.message,
+      stack: error?.stack
+    });
+  },
+
+  warn(message, meta) { this.log('WARN', message, meta); },
+  info(message, meta) { this.log('INFO', message, meta); },
+  debug(message, meta) { this.log('DEBUG', message, meta); },
+  trace(message, meta) { this.log('TRACE', message, meta); }
+};
+
+// 전역 에러 핸들러
+process.on('uncaughtException', (error) => {
+  logger.error('Uncaught Exception', error);
+  process.exit(1);
+});
+
+process.on('unhandledRejection', (reason) => {
+  logger.error('Unhandled Rejection', { reason });
+});
+```
+
+### Python
+```python
+import logging
+import json
+from datetime import datetime
+
+class JSONFormatter(logging.Formatter):
+    def format(self, record):
+        log_entry = {
+            'timestamp': datetime.utcnow().isoformat(),
+            'level': record.levelname,
+            'message': record.getMessage(),
+            'module': record.module,
+            'function': record.funcName,
+            'line': record.lineno
+        }
+        if record.exc_info:
+            log_entry['exception'] = self.formatException(record.exc_info)
+        return json.dumps(log_entry)
+
+# 로거 설정
+logger = logging.getLogger(__name__)
+handler = logging.StreamHandler()
+handler.setFormatter(JSONFormatter())
+logger.addHandler(handler)
+logger.setLevel(logging.DEBUG)
+
+# 데코레이터로 함수 호출 로깅
+def log_calls(func):
+    def wrapper(*args, **kwargs):
+        logger.debug(f'Calling {func.__name__}',
+                    extra={'args': args, 'kwargs': kwargs})
+        try:
+            result = func(*args, **kwargs)
+            logger.debug(f'{func.__name__} returned',
+                        extra={'result': result})
+            return result
+        except Exception as e:
+            logger.error(f'{func.__name__} failed', exc_info=True)
+            raise
+    return wrapper
+```
+
+### Express 미들웨어
+```javascript
+const requestLogger = (req, res, next) => {
+  const start = Date.now();
+
+  res.on('finish', () => {
+    const duration = Date.now() - start;
+    logger.info('HTTP Request', {
+      method: req.method,
+      url: req.url,
+      status: res.statusCode,
+      duration: `${duration}ms`,
+      userAgent: req.get('User-Agent'),
+      ip: req.ip
+    });
+  });
+
+  next();
+};
+
+const errorLogger = (err, req, res, next) => {
+  logger.error('Request Error', {
+    method: req.method,
+    url: req.url,
+    error: err.message,
+    stack: err.stack
+  });
+  next(err);
+};
+```
+
+## 로그 파일 구조
+
+```
+logs/
+├── app-2024-01-15.log      # 일별 로그
+├── error-2024-01-15.log    # 에러 전용
+└── debug/
+    └── trace-2024-01-15.log # 상세 추적
+```
+
+## 사용 예시
+
+```
+이 프로젝트에 디버그 로깅을 추가해줘
+API 요청을 로깅하는 미들웨어를 만들어줘
+에러 추적 시스템을 설정해줘
+```
+
+## 출처
+Original skill from skills.cokac.com

.claude/skills/test-coverage-auditor/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: ln-634-test-coverage-auditor
+description: Coverage Gaps audit worker (L3). Identifies missing tests for critical paths (Money 20+, Security 20+, Data Integrity 15+, Core Flows 15+). Returns list of untested critical business logic with priority justification.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Coverage Gaps Auditor (L3 Worker)
+
+Specialized worker identifying missing tests for critical business logic.
+
+## Purpose & Scope
+
+- **Worker in ln-630 coordinator pipeline**
+- Audit **Coverage Gaps** (Category 4: High Priority)
+- Identify untested critical paths
+- Classify by category (Money, Security, Data, Core Flows)
+- Calculate compliance score (X/10)
+
+## Inputs (from Coordinator)
+
+**MANDATORY READ:** Load `shared/references/task_delegation_pattern.md#audit-coordinator--worker-contract` for contextStore structure.
+
+Receives `contextStore` with: `tech_stack`, `testFilesMetadata`, `codebase_root`.
+
+**Domain-aware:** Supports `domain_mode` + `current_domain` (see `audit_output_schema.md#domain-aware-worker-output`).
+
+## Workflow
+
+1) **Parse context** — extract fields, determine `scan_path` (domain-aware if specified)
+     ELSE:
+       scan_path = codebase_root
+       domain_name = null
+     ```
+
+2) **Identify critical paths in scan_path** (not entire codebase)
+   - Scan production code in `scan_path` for money/security/data keywords
+   - All Grep/Glob patterns use `scan_path` (not codebase_root)
+   - Example: `Grep(pattern="payment|refund|discount", path=scan_path)`
+
+3) **Check test coverage for each critical path**
+   - Search ALL test files for coverage (tests may be in different location than production code)
+   - Match by function name, module name, or test description
+
+4) **Collect missing tests**
+   - Tag each finding with `domain: domain_name` (if domain-aware)
+
+5) **Calculate score**
+
+6) **Return JSON with domain metadata**
+   - Include `domain` and `scan_path` fields (if domain-aware)
+
+## Critical Paths Classification
+
+### 1. Money Flows (Priority 20+)
+
+**What:** Any code handling financial transactions
+
+**Examples:**
+- Payment processing (`/payment`, `processPayment()`)
+- Discounts/promotions (`calculateDiscount()`, `applyPromoCode()`)
+- Tax calculations (`calculateTax()`, `getTaxRate()`)
+- Refunds (`processRefund()`, `/refund`)
+- Invoices/billing (`generateInvoice()`, `createBill()`)
+- Currency conversion (`convertCurrency()`)
+
+**Min Priority:** 20
+
+**Why Critical:** Money loss, fraud, legal compliance
+
+### 2. Security Flows (Priority 20+)
+
+**What:** Authentication, authorization, encryption
+
+**Examples:**
+- Login/logout (`/login`, `authenticate()`)
+- Token refresh (`/refresh-token`, `refreshAccessToken()`)
+- Password reset (`/forgot-password`, `resetPassword()`)
+- Permissions/RBAC (`checkPermission()`, `hasRole()`)
+- Encryption/hashing (custom crypto logic, NOT bcrypt/argon2)
+- API key validation (`validateApiKey()`)
+
+**Min Priority:** 20
+
+**Why Critical:** Security breach, data leak, unauthorized access
+
+### 3. Data Integrity (Priority 15+)
+
+**What:** CRUD operations, transactions, validation
+
+**Examples:**
+- Critical CRUD (`createUser()`, `deleteOrder()`, `updateProduct()`)
+- Database transactions (`withTransaction()`)
+- Data validation (custom validators, NOT framework defaults)
+- Data migrations (`runMigration()`)
+- Unique constraints (`checkDuplicateEmail()`)
+
+**Min Priority:** 15
+
+**Why Critical:** Data corruption, lost data, inconsistent state
+
+### 4. Core User Journeys (Priority 15+)
+
+**What:** Multi-step flows critical to business
+
+**Examples:**
+- Registration → Email verification → Onboarding
+- Search → Product details → Add to cart → Checkout
+- Upload file → Process → Download result
+- Submit form → Approval workflow → Notification
+
+**Min Priority:** 15
+
+**Why Critical:** Broken user flow = lost customers
+
+## Audit Rules
+
+### 1. Identify Critical Paths
+
+**Process:**
+- Scan codebase for money-related keywords: `payment`, `refund`, `discount`, `tax`, `price`, `currency`
+- Scan for security keywords: `auth`, `login`, `password`, `token`, `permission`, `encrypt`
+- Scan for data keywords: `transaction`, `validation`, `migration`, `constraint`
+- Scan for user journeys: multi-step flows in routes/controllers
+
+### 2. Check Test Coverage
+
+**For each critical path:**
+- Search test files for matching test name/description
+- If NO test found → add to missing tests list
+- If test found but inadequate (only positive, no edge cases) → add to gaps list
+
+### 3. Categorize Gaps
+
+**Severity by Priority:**
+- **CRITICAL:** Priority 20+ (Money, Security)
+- **HIGH:** Priority 15-19 (Data, Core Flows)
+- **MEDIUM:** Priority 10-14 (Important but not critical)
+
+### 4. Provide Justification
+
+**For each missing test:**
+- Explain WHY it's critical (money loss, security breach, etc.)
+- Suggest test type (E2E, Integration, Unit)
+- Estimate effort (S/M/L)
+
+## Scoring Algorithm
+
+See `shared/references/audit_scoring.md` for unified formula and score interpretation.
+
+**Severity mapping by Priority:**
+- Priority 20+ (Money, Security) missing test → CRITICAL
+- Priority 15-19 (Data Integrity, Core Flows) missing test → HIGH
+- Priority 10-14 (Important) missing test → MEDIUM
+- Priority <10 (Nice-to-have) → LOW
+
+## Output Format
+
+**Return JSON to coordinator:**
+```json
+{
+  "category": "Coverage Gaps",
+  "score": 6,
+  "total_issues": 10,
+  "critical": 3,
+  "high": 4,
+  "medium": 2,
+  "low": 1,
+  "checks": [
+    {"id": "line_coverage", "name": "Line Coverage", "status": "passed", "details": "85% coverage (threshold: 80%)"},
+    {"id": "branch_coverage", "name": "Branch Coverage", "status": "warning", "details": "72% coverage (threshold: 75%)"},
+    {"id": "function_coverage", "name": "Function Coverage", "status": "passed", "details": "90% coverage (threshold: 80%)"},
+    {"id": "critical_gaps", "name": "Critical Gaps", "status": "failed", "details": "3 Money flows, 2 Security flows untested"}
+  ],
+  "domain": "orders",
+  "scan_path": "src/orders",
+  "findings": [
+    {
+      "severity": "CRITICAL",
+      "location": "src/orders/services/order.ts:45",
+      "issue": "Missing E2E test for applyDiscount() (Priority 25, Money flow)",
+      "principle": "Coverage Gaps / Money Flow",
+      "recommendation": "Add E2E test: applyDiscount() with edge cases (negative discount, max discount, currency rounding)",
+      "effort": "M"
+    },
+    {
+      "severity": "HIGH",
+      "location": "src/orders/repositories/order.ts:78",
+      "issue": "Missing Integration test for orderTransaction() rollback (Priority 18, Data Integrity)",
+      "principle": "Coverage Gaps / Data Integrity",
+      "recommendation": "Add Integration test verifying transaction rollback on failure",
+      "effort": "M"
+    }
+  ]
+}
+```
+
+**Note:** `domain` and `scan_path` fields included only when `domain_mode="domain-aware"`.
+
+## Critical Rules
+
+- **Domain-aware scanning:** If `domain_mode="domain-aware"`, scan ONLY `scan_path` production code (not entire codebase)
+- **Tag findings:** Include `domain` field in each finding when domain-aware
+- **Test search scope:** Search ALL test files for coverage (tests may be in different location than production code)
+- **Match by name:** Use function name, module name, or test description to match tests to production code
+
+## Definition of Done
+
+- contextStore parsed (including domain_mode and current_domain)
+- scan_path determined (domain path or codebase root)
+- Critical paths identified in scan_path (Money, Security, Data, Core Flows)
+- Test coverage checked for each critical path
+- Missing tests collected with severity, priority, justification, domain
+- Score calculated
+- JSON returned to coordinator with domain metadata
+
+## Reference Files
+
+- **Audit scoring formula:** `shared/references/audit_scoring.md`
+- **Audit output schema:** `shared/references/audit_output_schema.md`
+
+---
+**Version:** 3.0.0
+**Last Updated:** 2025-12-23

.claude/skills/test-isolation-auditor/SKILL.md

@@ -0,0 +1,367 @@
+---
+name: ln-635-test-isolation-auditor
+description: Test Isolation + Anti-Patterns audit worker (L3). Checks isolation (APIs/DB/FS/Time/Random/Network), determinism (flaky, order-dependent), and 6 anti-patterns.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Test Isolation & Anti-Patterns Auditor (L3 Worker)
+
+Specialized worker auditing test isolation and detecting anti-patterns.
+
+## Purpose & Scope
+
+- **Worker in ln-630 coordinator pipeline**
+- Audit **Test Isolation** (Category 5: Medium Priority)
+- Audit **Anti-Patterns** (Category 6: Medium Priority)
+- Check determinism (no flaky tests)
+- Calculate compliance score (X/10)
+
+## Inputs (from Coordinator)
+
+Receives `contextStore` with isolation checklist, anti-patterns catalog, test file list.
+
+## Workflow
+
+1) Parse context
+2) Check isolation for 6 categories
+3) Check determinism
+4) Detect 6 anti-patterns
+5) Collect findings
+6) Calculate score
+7) Return JSON
+
+## Audit Rules: Test Isolation
+
+### 1. External APIs
+
+**Good:** Mocked (jest.mock, sinon, nock)
+**Bad:** Real HTTP calls to external APIs
+
+**Detection:**
+- Grep for `axios.get`, `fetch(`, `http.request` without mocks
+- Check if test makes actual network calls
+
+**Severity:** **HIGH**
+
+**Recommendation:** Mock external APIs with `nock` or `jest.mock`
+
+**Effort:** M
+
+### 2. Database
+
+**Good:** In-memory DB (sqlite :memory:) or mocked
+**Bad:** Real database (PostgreSQL, MySQL)
+
+**Detection:**
+- Check DB connection strings (localhost:5432, real DB URL)
+- Grep for `beforeAll(async () => { await db.connect() })` without `:memory:`
+
+**Severity:** **MEDIUM**
+
+**Recommendation:** Use in-memory DB or mock DB calls
+
+**Effort:** M-L
+
+### 3. File System
+
+**Good:** Mocked (mock-fs, vol)
+**Bad:** Real file reads/writes
+
+**Detection:**
+- Grep for `fs.readFile`, `fs.writeFile` without mocks
+- Check if test creates/deletes real files
+
+**Severity:** **MEDIUM**
+
+**Recommendation:** Mock file system with `mock-fs`
+
+**Effort:** S-M
+
+### 4. Time/Date
+
+**Good:** Mocked (jest.useFakeTimers, sinon.useFakeTimers)
+**Bad:** `new Date()`, `Date.now()` without mocks
+
+**Detection:**
+- Grep for `new Date()` in test files without `useFakeTimers`
+
+**Severity:** **MEDIUM**
+
+**Recommendation:** Mock time with `jest.useFakeTimers()`
+
+**Effort:** S
+
+### 5. Random
+
+**Good:** Seeded random (Math.seedrandom, fixed seed)
+**Bad:** `Math.random()` without seed
+
+**Detection:**
+- Grep for `Math.random()` without seed setup
+
+**Severity:** **LOW**
+
+**Recommendation:** Use seeded random for deterministic tests
+
+**Effort:** S
+
+### 6. Network
+
+**Good:** Mocked (supertest for Express, no real ports)
+**Bad:** Real network requests (`localhost:3000`, binding to port)
+
+**Detection:**
+- Grep for `app.listen(3000)` in tests
+- Check for real HTTP requests
+
+**Severity:** **MEDIUM**
+
+**Recommendation:** Use `supertest` (no real port)
+
+**Effort:** M
+
+## Audit Rules: Determinism
+
+### 1. Flaky Tests
+
+**What:** Tests that pass/fail randomly
+
+**Detection:**
+- Run tests multiple times, check for inconsistent results
+- Grep for `setTimeout`, `setInterval` without proper awaits
+- Check for race conditions (async operations not awaited)
+
+**Severity:** **HIGH**
+
+**Recommendation:** Fix race conditions, use proper async/await
+
+**Effort:** M-L
+
+### 2. Time-Dependent Assertions
+
+**What:** Assertions on current time (`expect(timestamp).toBeCloseTo(Date.now())`)
+
+**Detection:**
+- Grep for `Date.now()`, `new Date()` in assertions
+
+**Severity:** **MEDIUM**
+
+**Recommendation:** Mock time
+
+**Effort:** S
+
+### 3. Order-Dependent Tests
+
+**What:** Tests that fail when run in different order
+
+**Detection:**
+- Run tests in random order, check for failures
+- Grep for shared mutable state between tests
+
+**Severity:** **MEDIUM**
+
+**Recommendation:** Isolate tests, reset state in beforeEach
+
+**Effort:** M
+
+### 4. Shared Mutable State
+
+**What:** Global variables modified across tests
+
+**Detection:**
+- Grep for `let globalVar` at module level
+- Check for state shared between tests
+
+**Severity:** **MEDIUM**
+
+**Recommendation:** Use `beforeEach` to reset state
+
+**Effort:** S-M
+
+## Audit Rules: Anti-Patterns
+
+### 1. The Liar (Always Passes)
+
+**What:** Test with no assertions or trivial assertion (`expect().toBeTruthy()`)
+
+**Detection:**
+- Count assertions per test
+- If 0 assertions or only `toBeTruthy()` → Liar
+
+**Severity:** **HIGH**
+
+**Recommendation:** Add specific assertions or delete test
+
+**Effort:** S
+
+**Example:**
+- **BAD (Liar):** Test calls `createUser()` but has NO assertions — always passes even if function breaks
+- **GOOD:** Test calls `createUser()` and asserts `user.name` equals 'Alice', `user.id` is defined
+
+### 2. The Giant (>100 lines)
+
+**What:** Test with >100 lines, testing too many scenarios
+
+**Detection:**
+- Count lines per test
+- If >100 lines → Giant
+
+**Severity:** **MEDIUM**
+
+**Recommendation:** Split into focused tests (one scenario per test)
+
+**Effort:** S-M
+
+### 3. Slow Poke (>5 seconds)
+
+**What:** Test taking >5 seconds to run
+
+**Detection:**
+- Measure test duration
+- If >5s → Slow Poke
+
+**Severity:** **MEDIUM**
+
+**Recommendation:** Mock external deps, use in-memory DB, parallelize
+
+**Effort:** M
+
+### 4. Conjoined Twins (Unit test without mocks = Integration)
+
+**What:** Test labeled "Unit" but not mocking dependencies
+
+**Detection:**
+- Check if test name includes "Unit"
+- Verify all dependencies are mocked
+- If no mocks → actually Integration test
+
+**Severity:** **LOW**
+
+**Recommendation:** Either mock dependencies OR rename to Integration test
+
+**Effort:** S
+
+### 5. Happy Path Only (No error scenarios)
+
+**What:** Only testing success cases, ignoring errors
+
+**Detection:**
+- For each function, check if test covers error cases
+- If only positive scenarios → Happy Path Only
+
+**Severity:** **MEDIUM**
+
+**Recommendation:** Add negative tests (error handling, edge cases)
+
+**Effort:** M
+
+**Example:**
+- **BAD (Happy Path Only):** Test only checks `login()` with valid credentials, ignores error scenarios
+- **GOOD:** Add negative test that verifies `login()` with invalid credentials throws 'Invalid credentials' error
+
+### 6. Framework Tester (Tests framework behavior)
+
+**What:** Tests validating Express/Prisma/bcrypt (NOT our code)
+
+**Detection:**
+- Already detected by ln-631-test-business-logic-auditor
+- Cross-reference findings
+
+**Severity:** **MEDIUM**
+
+**Recommendation:** Delete framework tests
+
+**Effort:** S
+
+## Scoring Algorithm
+
+See `shared/references/audit_scoring.md` for unified formula and score interpretation.
+
+**Severity mapping:**
+- Flaky tests, External API not mocked, The Liar → HIGH
+- Real database, File system, Time/Date, Network, The Giant, Happy Path Only → MEDIUM
+- Random without seed, Order-dependent, Conjoined Twins → LOW
+
+## Output Format
+
+**Return JSON to coordinator (flat findings array):**
+```json
+{
+  "category": "Isolation & Anti-Patterns",
+  "score": 6,
+  "total_issues": 18,
+  "critical": 0,
+  "high": 5,
+  "medium": 10,
+  "low": 3,
+  "checks": [
+    {"id": "api_isolation", "name": "API Isolation", "status": "failed", "details": "2 tests make real HTTP calls"},
+    {"id": "db_isolation", "name": "Database Isolation", "status": "warning", "details": "1 test uses real PostgreSQL"},
+    {"id": "fs_isolation", "name": "File System Isolation", "status": "passed", "details": "All FS calls mocked"},
+    {"id": "time_isolation", "name": "Time Isolation", "status": "passed", "details": "All Date/Time mocked"},
+    {"id": "flaky_tests", "name": "Flaky Tests", "status": "failed", "details": "3 race conditions detected"},
+    {"id": "anti_patterns", "name": "Anti-Patterns", "status": "warning", "details": "2 Liars, 1 Giant found"}
+  ],
+  "findings": [
+    {
+      "severity": "HIGH",
+      "location": "user.test.ts:45-52",
+      "issue": "External API not mocked — test makes real HTTP call to https://api.github.com",
+      "principle": "Test Isolation / External APIs",
+      "recommendation": "Mock external API with nock or jest.mock",
+      "effort": "M"
+    },
+    {
+      "severity": "HIGH",
+      "location": "async.test.ts:28-35",
+      "issue": "Flaky test (race condition) — setTimeout without proper await",
+      "principle": "Determinism / Race Condition",
+      "recommendation": "Fix race condition with proper async/await",
+      "effort": "M"
+    },
+    {
+      "severity": "HIGH",
+      "location": "user.test.ts:45",
+      "issue": "Anti-pattern 'The Liar' — test 'createUser works' has no assertions",
+      "principle": "Anti-Patterns / The Liar",
+      "recommendation": "Add specific assertions or delete test",
+      "effort": "S"
+    },
+    {
+      "severity": "MEDIUM",
+      "location": "db.test.ts:12",
+      "issue": "Real database used — test connects to localhost:5432 PostgreSQL",
+      "principle": "Test Isolation / Database",
+      "recommendation": "Use in-memory SQLite (:memory:) or mock DB",
+      "effort": "L"
+    },
+    {
+      "severity": "MEDIUM",
+      "location": "order.test.ts:200-350",
+      "issue": "Anti-pattern 'The Giant' — test 'order flow' is 150 lines (>100)",
+      "principle": "Anti-Patterns / The Giant",
+      "recommendation": "Split into focused tests (one scenario per test)",
+      "effort": "M"
+    },
+    {
+      "severity": "MEDIUM",
+      "location": "payment.test.ts",
+      "issue": "Anti-pattern 'Happy Path Only' — only success scenarios, no error tests",
+      "principle": "Anti-Patterns / Happy Path Only",
+      "recommendation": "Add negative tests for error handling",
+      "effort": "M"
+    }
+  ]
+}
+```
+
+**Note:** Findings are flattened into single array. Use `principle` field prefix (Test Isolation / Determinism / Anti-Patterns) to identify issue category.
+
+## Reference Files
+
+- **Audit scoring formula:** `shared/references/audit_scoring.md`
+- **Audit output schema:** `shared/references/audit_output_schema.md`
+
+---
+**Version:** 3.0.0
+**Last Updated:** 2025-12-23

.claude/skills/text-analyzer-skill/SKILL.md

@@ -0,0 +1,599 @@
+---
+name: text-analyzer-skill
+description: 자연어 텍스트 파일을 분석하여 PDF 템플릿 구조에 매핑하는 스킬. 섹션 추출, 콘텐츠 분류, 구조화된 데이터 생성 기능 제공.
+---
+
+# Text Analyzer Skill - 자연어 텍스트 분석 스킬
+
+source 폴더의 txt 파일을 분석하여 PDF 샘플과 동일한 형태의 PPTX로 변환하는 핵심 스킬입니다.
+
+## 기능 개요
+
+### 1. 자연어 텍스트 분석 (Natural Language Processing)
+텍스트 파일의 구조와 내용을 자동으로 파싱하고 분류
+
+### 2. PDF 템플릿 매핑 (Template Mapping)
+분석된 내용을 SAM_ERP 스토리보드 구조에 자동 매핑
+
+### 3. 구조화된 데이터 생성 (Structured Data Generation)
+PPTX 생성에 필요한 슬라이드별 데이터 구조 생성
+
+### 4. 콘텐츠 최적화 (Content Optimization)
+프레젠테이션에 적합한 형태로 콘텐츠 가공
+
+## 핵심 워크플로우
+
+### 텍스트 분석 → PDF 구조 매핑 워크플로우
+
+```mermaid
+graph TD
+    A[source/*.txt] --> B[텍스트 파싱]
+    B --> C[섹션 인식]
+    C --> D[콘텐츠 분류]
+    D --> E[PDF 템플릿 매핑]
+    E --> F[PPTX 데이터 생성]
+    F --> G[슬라이드 변환]
+```
+
+### 자연어 분석 엔진
+
+#### 1. 섹션 인식 패턴
+```javascript
+const SECTION_PATTERNS = {
+  // 프로젝트 메타 정보
+  project_meta: /^(프로젝트명|제목|title):\s*(.+)$/im,
+  date: /^(작성일|날짜|date):\s*(.+)$/im,
+  company: /^(회사명|회사|company):\s*(.+)$/im,
+  author: /^(작성자|저자|author):\s*(.+)$/im,
+
+  // 주요 섹션 구분
+  overview: /^=+\s*(개요|프로젝트\s*개요|overview)\s*=+$/im,
+  features: /^=+\s*(기능|주요\s*기능|features)\s*=+$/im,
+  screens: /^=+\s*(화면|화면\s*구성|screens)\s*=+$/im,
+  requirements: /^=+\s*(요구사항|기술\s*요구사항|requirements)\s*=+$/im,
+  flow: /^=+\s*(플로우|사용자\s*플로우|flow)\s*=+$/im,
+
+  // 하위 항목
+  numbered_item: /^(\d+)\.\s*(.+)$/,
+  bullet_item: /^[-*]\s*(.+)$/,
+  sub_item: /^\s*[-*]\s*(.+)$/
+};
+```
+
+#### 2. 콘텐츠 분류 규칙
+```javascript
+const CONTENT_CLASSIFIERS = {
+  // 화면/기능 관련
+  screen_indicators: ['화면', '페이지', '뷰', 'screen', 'page', 'view'],
+  feature_indicators: ['기능', '모듈', '시스템', 'feature', 'module', 'system'],
+  ui_indicators: ['버튼', '메뉴', '입력', '목록', 'button', 'menu', 'input', 'list'],
+
+  // 비즈니스 로직
+  business_indicators: ['관리', '분석', '처리', '생성', 'management', 'analysis'],
+  data_indicators: ['데이터', '정보', '내역', 'data', 'information'],
+
+  // 기술 요구사항
+  tech_indicators: ['시스템', '플랫폼', '기술', 'system', 'platform', 'technology']
+};
+```
+
+### PDF 템플릿 매핑 로직
+
+#### SAM_ERP 구조 매핑 테이블
+```javascript
+const TEMPLATE_MAPPING = {
+  // 표지 (Cover) - 1페이지
+  cover: {
+    source_fields: ['project_meta', 'date', 'company', 'author'],
+    template_layout: 'brand_centered',
+    required: true
+  },
+
+  // 문서 히스토리 - 2페이지
+  document_history: {
+    source_fields: ['date', 'author'],
+    template_layout: 'table_full_width',
+    auto_generate: true // 자동 생성
+  },
+
+  // 메뉴 구조 - 3페이지
+  menu_structure: {
+    source_fields: ['features', 'screens'],
+    template_layout: 'hierarchical_diagram',
+    extraction_method: 'feature_hierarchy'
+  },
+
+  // 공통 가이드라인 - 4-8페이지
+  common_guidelines: {
+    source_fields: ['requirements', 'ui_patterns'],
+    template_layout: 'documentation_style',
+    default_sections: ['interaction', 'responsive', 'template', 'notifications']
+  },
+
+  // 상세 화면 - 9-N페이지
+  detail_screens: {
+    source_fields: ['screens', 'features', 'flow'],
+    template_layout: 'wireframe_with_description',
+    per_screen: true
+  }
+};
+```
+
+## 스크립트 구조
+
+### 1. text-parser.js
+자연어 텍스트 파싱 및 구조 분석
+
+```javascript
+class TextParser {
+  constructor() {
+    this.sections = new Map();
+    this.metadata = {};
+  }
+
+  async parseFile(filePath) {
+    const content = await fs.readFile(filePath, 'utf8');
+    return this.parseContent(content);
+  }
+
+  parseContent(content) {
+    // 1. 메타데이터 추출
+    this.extractMetadata(content);
+
+    // 2. 섹션 구분
+    this.extractSections(content);
+
+    // 3. 구조화된 데이터 반환
+    return {
+      metadata: this.metadata,
+      sections: this.sections,
+      raw_content: content
+    };
+  }
+
+  extractMetadata(content) {
+    Object.entries(SECTION_PATTERNS).forEach(([key, pattern]) => {
+      const match = content.match(pattern);
+      if (match && key.includes('meta') || ['date', 'company', 'author'].includes(key)) {
+        this.metadata[key] = match[2]?.trim();
+      }
+    });
+  }
+
+  extractSections(content) {
+    const lines = content.split('\n');
+    let currentSection = null;
+    let currentContent = [];
+
+    lines.forEach(line => {
+      const sectionMatch = this.findSectionHeader(line);
+      if (sectionMatch) {
+        // 이전 섹션 저장
+        if (currentSection) {
+          this.sections.set(currentSection, this.processContent(currentContent));
+        }
+        currentSection = sectionMatch;
+        currentContent = [];
+      } else if (currentSection) {
+        currentContent.push(line);
+      }
+    });
+
+    // 마지막 섹션 저장
+    if (currentSection) {
+      this.sections.set(currentSection, this.processContent(currentContent));
+    }
+  }
+
+  findSectionHeader(line) {
+    for (const [key, pattern] of Object.entries(SECTION_PATTERNS)) {
+      if (['overview', 'features', 'screens', 'requirements', 'flow'].includes(key)) {
+        const match = line.match(pattern);
+        if (match) return key;
+      }
+    }
+    return null;
+  }
+
+  processContent(lines) {
+    const processed = {
+      raw: lines.join('\n'),
+      items: [],
+      structure: 'flat'
+    };
+
+    lines.forEach(line => {
+      line = line.trim();
+      if (!line) return;
+
+      // 번호 목록
+      const numberedMatch = line.match(SECTION_PATTERNS.numbered_item);
+      if (numberedMatch) {
+        processed.items.push({
+          type: 'numbered',
+          number: numberedMatch[1],
+          content: numberedMatch[2],
+          children: []
+        });
+        processed.structure = 'numbered';
+        return;
+      }
+
+      // 불릿 목록
+      const bulletMatch = line.match(SECTION_PATTERNS.bullet_item);
+      if (bulletMatch) {
+        if (processed.items.length > 0 && line.startsWith('  ')) {
+          // 하위 항목
+          const lastItem = processed.items[processed.items.length - 1];
+          lastItem.children.push({
+            type: 'sub_bullet',
+            content: bulletMatch[1]
+          });
+        } else {
+          processed.items.push({
+            type: 'bullet',
+            content: bulletMatch[1],
+            children: []
+          });
+        }
+        processed.structure = 'hierarchical';
+        return;
+      }
+
+      // 일반 텍스트
+      if (processed.items.length === 0) {
+        processed.items.push({
+          type: 'paragraph',
+          content: line
+        });
+      } else {
+        const lastItem = processed.items[processed.items.length - 1];
+        if (lastItem.type === 'paragraph') {
+          lastItem.content += ' ' + line;
+        } else {
+          processed.items.push({
+            type: 'paragraph',
+            content: line
+          });
+        }
+      }
+    });
+
+    return processed;
+  }
+}
+```
+
+### 2. template-mapper.js
+파싱된 데이터를 PDF 템플릿 구조에 매핑
+
+```javascript
+class TemplateMapper {
+  constructor() {
+    this.pdfTemplate = null;
+    this.mappedData = {};
+  }
+
+  async loadPDFTemplate(templatePath) {
+    const templateContent = await fs.readFile(templatePath, 'utf8');
+    this.pdfTemplate = JSON.parse(templateContent);
+  }
+
+  mapToTemplate(parsedData) {
+    const mapped = {
+      metadata: this.generateMetadata(parsedData.metadata),
+      slides: []
+    };
+
+    // 1. 표지 생성
+    mapped.slides.push(this.createCoverSlide(parsedData.metadata));
+
+    // 2. 문서 히스토리 생성
+    mapped.slides.push(this.createDocumentHistorySlide(parsedData.metadata));
+
+    // 3. 메뉴 구조 생성
+    mapped.slides.push(this.createMenuStructureSlide(parsedData.sections));
+
+    // 4. 공통 가이드라인 생성
+    mapped.slides.push(...this.createCommonGuidelines());
+
+    // 5. 상세 화면 생성
+    mapped.slides.push(...this.createDetailScreens(parsedData.sections));
+
+    return mapped;
+  }
+
+  createCoverSlide(metadata) {
+    return {
+      type: 'cover',
+      slide_number: 1,
+      layout: this.pdfTemplate.page_templates.find(t => t.type === 'cover').layout,
+      content: {
+        title: metadata.project_meta || '프로젝트 기획서',
+        subtitle: '시스템 기획 및 설계',
+        date: this.formatDate(metadata.date),
+        company: metadata.company || 'Company Name',
+        author: metadata.author || '작성자'
+      }
+    };
+  }
+
+  createDocumentHistorySlide(metadata) {
+    return {
+      type: 'document_history',
+      slide_number: 2,
+      layout: this.pdfTemplate.page_templates.find(t => t.type === 'document_history').layout,
+      content: {
+        title: 'Document History',
+        table: [
+          {
+            date: this.formatDate(metadata.date),
+            version: 'D1.0',
+            main_content: '초안 작성',
+            detailed_content: `${metadata.project_meta || '프로젝트'} 기획서 초안 작성`,
+            mark: ''
+          }
+        ]
+      }
+    };
+  }
+
+  createMenuStructureSlide(sections) {
+    const features = sections.get('features') || { items: [] };
+    const screens = sections.get('screens') || { items: [] };
+
+    // 기능과 화면 정보를 계층 구조로 변환
+    const menuStructure = this.buildMenuHierarchy(features, screens);
+
+    return {
+      type: 'menu_structure',
+      slide_number: 3,
+      layout: this.pdfTemplate.page_templates.find(t => t.type === 'system_structure').layout,
+      content: {
+        title: 'Menu Structure',
+        structure: menuStructure
+      }
+    };
+  }
+
+  buildMenuHierarchy(features, screens) {
+    const structure = {
+      root: '시스템 구조',
+      children: []
+    };
+
+    // 주요 기능을 상위 카테고리로 설정
+    features.items.forEach(feature => {
+      if (feature.type === 'numbered' && feature.content) {
+        const category = {
+          name: feature.content,
+          children: []
+        };
+
+        // 하위 항목이 있으면 추가
+        if (feature.children && feature.children.length > 0) {
+          feature.children.forEach(child => {
+            category.children.push({
+              name: child.content,
+              leaf: true
+            });
+          });
+        }
+
+        structure.children.push(category);
+      }
+    });
+
+    // 화면 정보도 추가
+    if (screens.items.length > 0) {
+      const screenCategory = {
+        name: '화면 구성',
+        children: []
+      };
+
+      screens.items.forEach(screen => {
+        if (screen.content) {
+          screenCategory.children.push({
+            name: screen.content,
+            leaf: true
+          });
+        }
+      });
+
+      structure.children.push(screenCategory);
+    }
+
+    return structure;
+  }
+
+  createCommonGuidelines() {
+    // PDF 템플릿의 공통 가이드라인 구조를 사용
+    return [
+      {
+        type: 'common_guidelines',
+        slide_number: 4,
+        content: {
+          title: '공통',
+          sections: ['사용자 인터랙션', '반응형 웹', '화면 템플릿', '알림 시스템']
+        }
+      }
+    ];
+  }
+
+  createDetailScreens(sections) {
+    const detailSlides = [];
+    let slideNumber = 9; // 상세 화면은 9페이지부터 시작
+
+    // 기능별로 상세 화면 생성
+    const features = sections.get('features');
+    const screens = sections.get('screens');
+    const flow = sections.get('flow');
+
+    if (features && features.items) {
+      features.items.forEach(feature => {
+        if (feature.type === 'numbered') {
+          detailSlides.push(this.createDetailScreenFromFeature(feature, slideNumber));
+          slideNumber++;
+        }
+      });
+    }
+
+    // 명시적인 화면 구성이 있다면 추가
+    if (screens && screens.items) {
+      screens.items.forEach(screen => {
+        detailSlides.push(this.createDetailScreenFromScreen(screen, slideNumber));
+        slideNumber++;
+      });
+    }
+
+    return detailSlides;
+  }
+
+  createDetailScreenFromFeature(feature, slideNumber) {
+    return {
+      type: 'detail_screen',
+      slide_number: slideNumber,
+      layout: this.pdfTemplate.page_templates.find(t => t.type === 'detail_screen').layout,
+      content: {
+        header_info: {
+          task_name: feature.content,
+          version: 'D1.0',
+          page_number: slideNumber,
+          route: this.generateRoute(feature.content),
+          screen_name: feature.content,
+          screen_id: this.generateScreenId(feature.content)
+        },
+        wireframe: {
+          type: 'feature_mockup',
+          description: `${feature.content} 화면 구성`,
+          elements: this.extractUIElements(feature)
+        },
+        descriptions: this.generateDescriptions(feature)
+      }
+    };
+  }
+
+  extractUIElements(feature) {
+    const elements = [];
+
+    // 자연어에서 UI 요소 추출
+    if (feature.children && feature.children.length > 0) {
+      feature.children.forEach((child, index) => {
+        elements.push(`${index + 1}. ${child.content}`);
+      });
+    } else {
+      // 기본 UI 요소 추가
+      elements.push('1. 헤더 영역');
+      elements.push('2. 메인 콘텐츠');
+      elements.push('3. 액션 버튼');
+    }
+
+    return elements;
+  }
+
+  generateDescriptions(feature) {
+    const descriptions = [];
+
+    if (feature.children && feature.children.length > 0) {
+      feature.children.forEach((child, index) => {
+        descriptions.push({
+          number: index + 1,
+          title: this.extractTitle(child.content),
+          description: child.content
+        });
+      });
+    } else {
+      descriptions.push({
+        number: 1,
+        title: feature.content,
+        description: `${feature.content} 기능 구현 및 사용자 인터랙션 처리`
+      });
+    }
+
+    return descriptions;
+  }
+
+  extractTitle(content) {
+    // 콘텐츠에서 제목 추출 (첫 번째 단어 또는 구문)
+    const words = content.split(' ');
+    return words.length > 3 ? words.slice(0, 2).join(' ') : words[0];
+  }
+
+  generateRoute(screenName) {
+    return '/' + screenName
+      .toLowerCase()
+      .replace(/\s+/g, '_')
+      .replace(/[^a-z0-9가-힣_]/g, '');
+  }
+
+  generateScreenId(screenName) {
+    return screenName
+      .toLowerCase()
+      .replace(/\s+/g, '_')
+      .replace(/[^a-z0-9가-힣_]/g, '');
+  }
+
+  formatDate(dateStr) {
+    if (!dateStr) {
+      return new Date().toISOString().split('T')[0].replace(/-/g, '.');
+    }
+    return dateStr.replace(/-/g, '.');
+  }
+
+  generateMetadata(metadata) {
+    return {
+      title: metadata.project_meta || '프로젝트 기획서',
+      version: 'D1.0',
+      created_date: this.formatDate(metadata.date),
+      author: metadata.author || '작성자',
+      company: metadata.company || 'Company Name',
+      source_file: 'source/*.txt'
+    };
+  }
+}
+```
+
+## 사용법
+
+### 1. 기본 실행
+```bash
+# source 폴더의 txt 파일 분석 및 PPTX 생성
+node .claude/skills/text-analyzer-skill/scripts/txt-to-pptx.js
+
+# 또는 간단 명령
+npm run txt-to-ppt
+```
+
+### 2. 특정 파일 지정
+```bash
+node txt-to-pptx.js --input source/my_project.txt --output my_presentation.pptx
+```
+
+### 3. 템플릿 지정
+```bash
+node txt-to-pptx.js --template custom_template.json --input source/project.txt
+```
+
+## 품질 기준
+
+### 텍스트 분석 정확도
+- **섹션 인식률**: >90% (명시적 구분자 기준)
+- **콘텐츠 분류**: >85% (키워드 매칭 기준)
+- **구조 보존**: 원본 계층 구조 유지
+
+### PDF 템플릿 매핑 일치도
+- **레이아웃 일관성**: SAM_ERP 스토리보드와 95% 일치
+- **섹션 완성도**: 필수 섹션 100% 포함
+- **콘텐츠 적합성**: 프레젠테이션 형태로 최적화
+
+## 확장 기능
+
+### 다양한 텍스트 형식 지원
+- Markdown 파일 (.md)
+- Word 문서 (.docx)
+- 구조화된 JSON (.json)
+
+### AI 기반 콘텐츠 최적화
+- 자동 요약 기능
+- 키워드 추출
+- 슬라이드 분량 최적화

.claude/skills/text-analyzer-skill/scripts/txt-to-pptx.js

@@ -0,0 +1,306 @@
+/**
+ * 작동하는 TXT → PPTX 변환기 (컬러 오류 수정 버전)
+ */
+
+const fs = require('fs').promises;
+const PptxGenJS = require('pptxgenjs');
+
+// 간단한 텍스트 분석 클래스
+class TextAnalyzer {
+  constructor() {
+    this.patterns = {
+      metadata: /^(.+?):[\s]*(.+)$/,
+      section: /^=== (.+) ===/,
+      heading: /^[가-힣A-Za-z].+[가-힣A-Za-z\d]$/,  // 한글로 시작하고 끝나는 제목
+      numbered_item: /^\d+\.\s*(.+)$/,
+      bullet_item: /^[•\-\*]\s*(.+)$/,
+      html_tag: /<[^>]+>/g
+    };
+  }
+
+  /**
+   * TXT 파일 분석
+   */
+  async analyzeFile(filePath) {
+    console.log(`📖 텍스트 파일 분석 중: ${filePath}`);
+
+    const content = await fs.readFile(filePath, 'utf8');
+    const lines = content.split('\n');
+
+    const result = {
+      metadata: {},
+      sections: new Map()
+    };
+
+    let currentSection = null;
+    let currentContent = [];
+
+    // 첫 번째 라인을 제목으로 사용
+    if (lines.length > 0) {
+      result.metadata.title = lines[0].trim();
+    }
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmedLine = line.trim();
+      if (!trimmedLine) continue;
+
+      // HTML 태그 제거
+      const cleanLine = trimmedLine.replace(this.patterns.html_tag, '');
+      if (!cleanLine.trim()) continue;
+
+      // 메타데이터 파싱 (처음 3줄 이내)
+      if (i < 3) {
+        const metaMatch = cleanLine.match(this.patterns.metadata);
+        if (metaMatch && !currentSection) {
+          const key = metaMatch[1].toLowerCase().replace(/[^\w]/g, '_');
+          result.metadata[key] = metaMatch[2];
+          continue;
+        }
+      }
+
+      // 섹션 제목 (=== 형태)
+      const sectionMatch = cleanLine.match(this.patterns.section);
+      if (sectionMatch) {
+        // 이전 섹션 저장
+        if (currentSection) {
+          result.sections.set(currentSection, {
+            title: currentSection,
+            content: currentContent.join('\n')
+          });
+        }
+
+        currentSection = sectionMatch[1];
+        currentContent = [];
+        continue;
+      }
+
+      // 한글 제목 패턴 (bullet point나 HTML이 아닌 경우)
+      if (!cleanLine.startsWith('•') &&
+          !cleanLine.startsWith('-') &&
+          !cleanLine.startsWith('<') &&
+          cleanLine.length > 5 &&
+          cleanLine.length < 100 &&
+          this.patterns.heading.test(cleanLine)) {
+
+        // 이전 섹션 저장
+        if (currentSection) {
+          result.sections.set(currentSection, {
+            title: currentSection,
+            content: currentContent.join('\n')
+          });
+        }
+
+        currentSection = cleanLine;
+        currentContent = [];
+        continue;
+      }
+
+      // 현재 섹션에 내용 추가
+      if (currentSection) {
+        currentContent.push(cleanLine);
+      } else if (!currentSection && i > 2) {
+        // 섹션이 없으면 "개요"로 시작
+        currentSection = "개요";
+        currentContent = [cleanLine];
+      }
+    }
+
+    // 마지막 섹션 저장
+    if (currentSection) {
+      result.sections.set(currentSection, {
+        title: currentSection,
+        content: currentContent.join('\n')
+      });
+    }
+
+    // 기본값 설정
+    if (!result.metadata.title) result.metadata.title = 'TXT 변환 프레젠테이션';
+    if (!result.metadata.date) result.metadata.date = new Date().toISOString().split('T')[0];
+    if (!result.metadata.company) result.metadata.company = 'Generated by TXT→PPTX';
+
+    console.log(`✅ 분석 완료: ${result.sections.size}개 섹션 발견`);
+    return result;
+  }
+}
+
+// PPTX 생성 클래스
+class PPTXGenerator {
+  constructor() {
+    this.pptx = new PptxGenJS();
+    this.pptx.layout = 'LAYOUT_16x9';
+    this.slideNumber = 1;
+  }
+
+  /**
+   * 분석된 데이터로부터 PPTX 생성
+   */
+  async generateFromAnalysis(analysisResult) {
+    console.log('📊 PPTX 생성 중...');
+
+    const { metadata, sections } = analysisResult;
+
+    // 1. 표지 슬라이드
+    this.createCoverSlide(metadata);
+
+    // 2. 목차 슬라이드
+    this.createTableOfContents(sections);
+
+    // 3. 각 섹션별 슬라이드
+    for (const [sectionName, sectionData] of sections) {
+      this.createSectionSlide(sectionName, sectionData);
+    }
+
+    return this.pptx;
+  }
+
+  /**
+   * 표지 슬라이드 생성
+   */
+  createCoverSlide(metadata) {
+    const slide = this.pptx.addSlide();
+
+    // 배경 색상
+    slide.background = { color: '8BC34A' };
+
+    // 프로젝트 제목
+    slide.addText(metadata.title || 'TXT 변환 프레젠테이션', {
+      x: 1, y: 3, w: 8, h: 1.5,
+      fontSize: 36,
+      bold: true,
+      color: 'FFFFFF',
+      align: 'center'
+    });
+
+    // 부제목
+    slide.addText('시스템 기획 및 설계서', {
+      x: 1, y: 4.8, w: 8, h: 0.8,
+      fontSize: 20,
+      color: 'FFFFFF',
+      align: 'center'
+    });
+
+    // 날짜 및 회사정보
+    const infoText = `${metadata.date}\n\n${metadata.company}`;
+    slide.addText(infoText, {
+      x: 7.5, y: 7, w: 2.5, h: 1.5,
+      fontSize: 12,
+      color: 'FFFFFF',
+      align: 'right'
+    });
+
+    console.log(`✅ 슬라이드 ${this.slideNumber}: 표지`);
+    this.slideNumber++;
+  }
+
+  /**
+   * 목차 슬라이드 생성
+   */
+  createTableOfContents(sections) {
+    const slide = this.pptx.addSlide();
+
+    slide.addText('목차', {
+      x: 0.5, y: 0.5, w: 9, h: 0.8,
+      fontSize: 24,
+      bold: true,
+      color: '2E7D32'
+    });
+
+    let yPosition = 1.5;
+    let index = 1;
+
+    for (const [sectionName] of sections) {
+      slide.addText(`${index}. ${sectionName}`, {
+        x: 1, y: yPosition, w: 8, h: 0.6,
+        fontSize: 16,
+        color: '333333'
+      });
+
+      yPosition += 0.8;
+      index++;
+
+      if (yPosition > 6) break; // 슬라이드 범위 초과 방지
+    }
+
+    console.log(`✅ 슬라이드 ${this.slideNumber}: 목차`);
+    this.slideNumber++;
+  }
+
+  /**
+   * 섹션 슬라이드 생성
+   */
+  createSectionSlide(sectionName, sectionData) {
+    const slide = this.pptx.addSlide();
+
+    // 섹션 제목
+    slide.addText(sectionName, {
+      x: 0.5, y: 0.5, w: 9, h: 0.8,
+      fontSize: 24,
+      bold: true,
+      color: '2E7D32'
+    });
+
+    // 내용 처리 (긴 내용은 잘라서 표시)
+    let content = sectionData.content;
+    if (content.length > 800) {
+      content = content.substring(0, 800) + '...';
+    }
+
+    slide.addText(content, {
+      x: 0.5, y: 1.5, w: 9, h: 4.5,
+      fontSize: 14,
+      color: '333333',
+      lineSpacing: 20
+    });
+
+    console.log(`✅ 슬라이드 ${this.slideNumber}: ${sectionName}`);
+    this.slideNumber++;
+  }
+}
+
+// 메인 실행 함수
+async function convertTxtToPptx(inputPath, outputPath) {
+  try {
+    console.log('🚀 TXT → PPTX 변환 시작');
+    console.log(`📄 입력: ${inputPath}`);
+    console.log(`📊 출력: ${outputPath}`);
+
+    // 1. 텍스트 분석
+    const analyzer = new TextAnalyzer();
+    const analysisResult = await analyzer.analyzeFile(inputPath);
+
+    // 2. PPTX 생성
+    const generator = new PPTXGenerator();
+    const pptx = await generator.generateFromAnalysis(analysisResult);
+
+    // 3. 파일 저장
+    await pptx.writeFile({ fileName: outputPath });
+    console.log('✅ 변환 완료!');
+
+  } catch (error) {
+    console.error('❌ 변환 실패:', error.message);
+    throw error;
+  }
+}
+
+// 명령행 인수 처리
+async function main() {
+  const args = process.argv.slice(2);
+  const inputFlag = args.find(arg => arg.startsWith('--input='));
+  const outputFlag = args.find(arg => arg.startsWith('--output='));
+
+  const inputPath = inputFlag ? inputFlag.split('=')[1] : 'source/sample_project.txt';
+  const outputPath = outputFlag ? outputFlag.split('=')[1] : 'pptx/working_test.pptx';
+
+  // 출력 디렉토리 생성
+  await fs.mkdir('pptx', { recursive: true });
+
+  await convertTxtToPptx(inputPath, outputPath);
+}
+
+// 직접 실행시
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+module.exports = { convertTxtToPptx, TextAnalyzer, PPTXGenerator };

.claude/skills/uml-generator/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: uml-generator
+description: 프로젝트 아키텍처를 분석하여 UML 다이어그램을 자체 완결형 HTML로 생성합니다. UML, 클래스 다이어그램, 아키텍처 시각화 요청 시 활성화됩니다.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# UML Generator
+
+프로젝트 구조를 분석하여 UML 다이어그램을 생성하는 스킬입니다.
+
+## 기능
+
+### 지원하는 다이어그램 유형
+- **클래스 다이어그램**: 클래스, 인터페이스, 상속/구현 관계
+- **패키지 다이어그램**: 모듈/패키지 간 의존성
+- **시퀀스 다이어그램**: 객체 간 메시지 흐름
+- **컴포넌트 다이어그램**: 시스템 컴포넌트 구조
+
+### 분석 대상
+- 클래스 및 인터페이스 정의
+- 상속 및 구현 관계
+- 메서드 시그니처 및 속성
+- 모듈 간 import/export 관계
+- 의존성 주입 패턴
+
+### 출력 형식
+- Mermaid.js 기반 인터랙티브 HTML
+- 자체 완결형 단일 파일
+
+## HTML 템플릿
+
+```html
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+    <meta charset="UTF-8">
+    <title>UML 다이어그램</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+    <style>
+        * { font-family: 'Noto Sans KR', sans-serif; }
+        .mermaid { background: #f8fafc; padding: 1rem; border-radius: 0.5rem; }
+    </style>
+</head>
+<body class="bg-gray-100 min-h-screen">
+    <header class="bg-white shadow-sm sticky top-0 z-50">
+        <div class="max-w-6xl mx-auto px-4 py-4">
+            <h1 class="text-xl font-bold text-slate-800">UML 다이어그램</h1>
+        </div>
+    </header>
+
+    <main class="max-w-6xl mx-auto px-4 py-8">
+        <!-- 클래스 다이어그램 -->
+        <section class="bg-white rounded-xl shadow-sm p-6 mb-6">
+            <h2 class="text-lg font-bold text-slate-700 mb-4">클래스 다이어그램</h2>
+            <div class="mermaid">
+                classDiagram
+                    class ClassName {
+                        +attribute: type
+                        +method(): returnType
+                    }
+            </div>
+        </section>
+
+        <!-- 시퀀스 다이어그램 -->
+        <section class="bg-white rounded-xl shadow-sm p-6 mb-6">
+            <h2 class="text-lg font-bold text-slate-700 mb-4">시퀀스 다이어그램</h2>
+            <div class="mermaid">
+                sequenceDiagram
+                    participant A
+                    participant B
+                    A->>B: message
+            </div>
+        </section>
+    </main>
+
+    <script>
+        mermaid.initialize({ startOnLoad: true, theme: 'default' });
+    </script>
+</body>
+</html>
+```
+
+## 사용 예시
+
+```
+이 프로젝트의 클래스 다이어그램을 만들어줘
+src 폴더의 UML 다이어그램을 HTML로 생성해줘
+이 코드의 시퀀스 다이어그램을 그려줘
+```
+
+## 출처
+Original skill from skills.cokac.com

.claude/skills/webapp-testing/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: webapp-testing
+description: Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
+license: Complete terms in LICENSE.txt
+---
+
+# Web Application Testing
+
+To test local web applications, write native Python Playwright scripts.
+
+**Helper Scripts Available**:
+- `scripts/with_server.py` - Manages server lifecycle (supports multiple servers)
+
+**Always run scripts with `--help` first** to see usage. DO NOT read the source until you try running the script first and find that a customized solution is abslutely necessary. These scripts can be very large and thus pollute your context window. They exist to be called directly as black-box scripts rather than ingested into your context window.
+
+## Decision Tree: Choosing Your Approach
+
+```
+User task → Is it static HTML?
+    ├─ Yes → Read HTML file directly to identify selectors
+    │         ├─ Success → Write Playwright script using selectors
+    │         └─ Fails/Incomplete → Treat as dynamic (below)
+    │
+    └─ No (dynamic webapp) → Is the server already running?
+        ├─ No → Run: python scripts/with_server.py --help
+        │        Then use the helper + write simplified Playwright script
+        │
+        └─ Yes → Reconnaissance-then-action:
+            1. Navigate and wait for networkidle
+            2. Take screenshot or inspect DOM
+            3. Identify selectors from rendered state
+            4. Execute actions with discovered selectors
+```
+
+## Example: Using with_server.py
+
+To start a server, run `--help` first, then use the helper:
+
+**Single server:**
+```bash
+python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py
+```
+
+**Multiple servers (e.g., backend + frontend):**
+```bash
+python scripts/with_server.py \
+  --server "cd backend && python server.py" --port 3000 \
+  --server "cd frontend && npm run dev" --port 5173 \
+  -- python your_automation.py
+```
+
+To create an automation script, include only Playwright logic (servers are managed automatically):
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=True) # Always launch chromium in headless mode
+    page = browser.new_page()
+    page.goto('http://localhost:5173') # Server already running and ready
+    page.wait_for_load_state('networkidle') # CRITICAL: Wait for JS to execute
+    # ... your automation logic
+    browser.close()
+```
+
+## Reconnaissance-Then-Action Pattern
+
+1. **Inspect rendered DOM**:
+   ```python
+   page.screenshot(path='/tmp/inspect.png', full_page=True)
+   content = page.content()
+   page.locator('button').all()
+   ```
+
+2. **Identify selectors** from inspection results
+
+3. **Execute actions** using discovered selectors
+
+## Common Pitfall
+
+❌ **Don't** inspect the DOM before waiting for `networkidle` on dynamic apps
+✅ **Do** wait for `page.wait_for_load_state('networkidle')` before inspection
+
+## Best Practices
+
+- **Use bundled scripts as black boxes** - To accomplish a task, consider whether one of the scripts available in `scripts/` can help. These scripts handle common, complex workflows reliably without cluttering the context window. Use `--help` to see usage, then invoke directly.
+- Use `sync_playwright()` for synchronous scripts
+- Always close the browser when done
+- Use descriptive selectors: `text=`, `role=`, CSS selectors, or IDs
+- Add appropriate waits: `page.wait_for_selector()` or `page.wait_for_timeout()`
+
+## Reference Files
+
+- **examples/** - Examples showing common patterns:
+  - `element_discovery.py` - Discovering buttons, links, and inputs on a page
+  - `static_html_automation.py` - Using file:// URLs for local HTML
+  - `console_logging.py` - Capturing console logs during automation

.claude/skills/웹문서/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: 웹문서
+description: SAM 프로젝트의 웹문서(PHP/HTML) 생성 시 적용되는 디자인 표준. 웹페이지, index.php, 보고서 페이지 생성 시 자동 활성화
+allowed-tools: Read, Write, Edit, Glob
+---
+
+# 웹문서 스타일 가이드
+
+이 스킬은 SAM 프로젝트의 웹문서(PHP/HTML) 생성 시 적용되는 디자인 표준입니다.
+
+## 필수 적용 사항
+
+### 1. 상단 홈 버튼 (필수)
+모든 웹문서의 헤더에는 상위 index.php로 이동하는 홈 버튼을 포함해야 합니다:
+
+```html
+<a href="../index.php" class="flex items-center justify-center w-10 h-10 bg-slate-100 hover:bg-teal-100 rounded-lg transition-colors" title="홈으로">
+    <span class="text-xl">🏠</span>
+</a>
+```
+
+### 2. 디자인 철학 (Core Philosophy)
+
+- **주제**: Professional Trust (신뢰 기반의 전문성)
+- **분위기**: 깔끔함, 신뢰감, 데이터 중심적인 명확성
+- **핵심 키워드**: Teal, Navy, White, Light Gray, Modern Typography
+
+### 3. 색상 사양 (Color Palette)
+
+#### 기본 색상 (Brand Colors)
+- **Primary (Teal)**: `#0d9488` (Tailwind: `teal-600`) - 핵심 강조 색상, 활성화 상태
+- **Secondary (Navy/Slate)**: `#1e293b` (Tailwind: `slate-800`) - 제목, 텍스트, 신뢰감을 주는 배경
+- **Accent (Amber)**: `#f59e0b` (Tailwind: `amber-500`) - 차트의 추세선 등 보조 강조
+
+#### 배경 및 테두리
+- **Body Background**: `#f3f4f6` (Tailwind: `gray-100`)
+- **Container Background**: `#ffffff` (White)
+- **Border**: `#e2e8f0` (Tailwind: `slate-200`)
+
+### 4. 타이포그래피 (Typography)
+
+- **Font Family**: `'Noto Sans KR', sans-serif` (Google Fonts)
+- **Heading Styles**:
+  - Main Title: `text-2xl font-bold text-slate-800`
+  - Sub Title: `text-lg font-bold text-slate-700`
+- **Body Text**: `text-slate-600 leading-relaxed`
+
+### 5. UI 컴포넌트 표준
+
+#### 상단 네비게이션 (Sticky Header)
+```html
+<header class="bg-white shadow-sm sticky top-0 z-50">
+    <div class="max-w-6xl mx-auto px-4">
+        <div class="flex items-center justify-between py-4">
+            <div class="flex items-center space-x-4">
+                <a href="../index.php" class="flex items-center justify-center w-10 h-10 bg-slate-100 hover:bg-teal-100 rounded-lg transition-colors" title="홈으로">
+                    <span class="text-xl">🏠</span>
+                </a>
+                <h1 class="text-xl font-bold text-slate-800">페이지 제목</h1>
+            </div>
+            <span class="text-sm text-slate-500">날짜</span>
+        </div>
+    </div>
+</header>
+```
+
+#### 활성화된 탭
+```css
+.nav-active { border-bottom: 3px solid #0d9488; color: #0d9488; font-weight: 700; }
+```
+
+#### 정보 카드
+- 사각 모서리 둥글게: `rounded-xl`
+- 가벼운 그림자: `shadow-sm`
+- 호버 효과: `hover:shadow-md transition-shadow`
+- 왼쪽 테두리 강조: `border-l-4 border-teal-600`
+
+#### 차트 (Chart.js)
+- 스타일: `max-height: 400px`
+- 색상: Teal(`rgba(13, 148, 136, 0.2)`) 또는 Blue(`rgba(59, 130, 246, 0.2)`)
+
+### 6. 코딩 규칙
+
+- **CSS Framework**: Tailwind CSS (CDN 방식)
+```html
+<script src="https://cdn.tailwindcss.com"></script>
+```
+
+- **폰트**:
+```html
+<link href="https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@300;400;500;700&display=swap" rel="stylesheet">
+```
+
+- **SVG 지양**: 유니코드 이모지(🏢, 📈, 💰) 사용
+
+- **애니메이션**: fade-in 효과
+```css
+.fade-in {
+    animation: fadeIn 0.5s ease-out forwards;
+}
+@keyframes fadeIn {
+    from { opacity: 0; transform: translateY(10px); }
+    to { opacity: 1; transform: translateY(0); }
+}
+```
+
+- **반응형**: 모바일 우선 + `md:` 접두사
+
+- **커스텀 스크롤바**:
+```css
+.custom-scroll::-webkit-scrollbar { width: 6px; height: 6px; }
+.custom-scroll::-webkit-scrollbar-track { background: #f1f5f9; border-radius: 10px; }
+.custom-scroll::-webkit-scrollbar-thumb { background: #cbd5e1; border-radius: 10px; }
+```
+
+### 7. 기본 HTML 템플릿
+
+```html
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>페이지 제목</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@300;400;500;700&display=swap" rel="stylesheet">
+    <style>
+        * { font-family: 'Noto Sans KR', sans-serif; }
+        .nav-active { border-bottom: 3px solid #0d9488; color: #0d9488; font-weight: 700; }
+        .fade-in { animation: fadeIn 0.5s ease-out forwards; }
+        @keyframes fadeIn {
+            from { opacity: 0; transform: translateY(10px); }
+            to { opacity: 1; transform: translateY(0); }
+        }
+        .custom-scroll::-webkit-scrollbar { width: 6px; }
+        .custom-scroll::-webkit-scrollbar-track { background: #f1f5f9; border-radius: 10px; }
+        .custom-scroll::-webkit-scrollbar-thumb { background: #cbd5e1; border-radius: 10px; }
+    </style>
+</head>
+<body class="bg-gray-100 min-h-screen">
+    <header class="bg-white shadow-sm sticky top-0 z-50">
+        <div class="max-w-6xl mx-auto px-4">
+            <div class="flex items-center justify-between py-4">
+                <div class="flex items-center space-x-4">
+                    <a href="../index.php" class="flex items-center justify-center w-10 h-10 bg-slate-100 hover:bg-teal-100 rounded-lg transition-colors" title="홈으로">
+                        <span class="text-xl">🏠</span>
+                    </a>
+                    <h1 class="text-xl font-bold text-slate-800">페이지 제목</h1>
+                </div>
+                <span class="text-sm text-slate-500">날짜</span>
+            </div>
+        </div>
+    </header>
+
+    <main class="max-w-6xl mx-auto px-4 py-8">
+        <!-- 콘텐츠 -->
+    </main>
+
+    <footer class="bg-slate-800 text-white py-8 mt-12">
+        <div class="max-w-6xl mx-auto px-4 text-center">
+            <p class="text-xs text-slate-500">© SAM</p>
+        </div>
+    </footer>
+</body>
+</html>
+```

.gitignore

@@ -1,2 +1,35 @@
+# 모든 파일 무시
+*
+
+# 추적할 파일만 허용
+!.gitignore
+!CLAUDE.md
+
+# .claude 폴더 - 스킬/에이전트는 추적
+!.claude/
+.claude/*
+!.claude/skills/
+!.claude/skills/**
+.claude/skills/**/node_modules/
+!.claude/agents/
+!.claude/agents/**
+
+# sam 문서
+!sam/
+sam/*
+!sam/docs/
+!sam/docs/**
+sam/docs/contracts/docx/backup/
+
+# sam 배포/운영 문서
+!sam/deploys/
+!sam/deploys/**
+!sam/front/
+!sam/front/**
+!sam/projects/
+!sam/projects/**
+
+# 기타
+sam/sales
 .DS_Store
 _to_notion/

INDEX.md

@@ -1,7 +1,7 @@
 # SAM 문서 인덱스 (Claude Code용)
 
 > 작업 유형에 맞는 문서를 먼저 읽고 시작하세요.
-> 최종 갱신: 2026-03-05
+> 최종 갱신: 2026-03-07
 
 ---
 
@@ -21,6 +21,7 @@
 | 견적관리 | `features/quotes/README.md` | 견적 시스템, BOM 계산 |
 | 운영 배포 | `dev/dev_plans/production-deployment-plan.md` | 배포 계획 |
 | 서버 운영 | `dev/deploys/ops-manual/README.md` | 서버 운영 매뉴얼 |
+| 서버 접근/백업 | `system/server-access-management.md` | 계정, 권한, 백업, 리플리케이션 |
 | MES | `projects/mes/README.md` | MES 프로젝트 |
 
 ---
@@ -72,6 +73,7 @@ docs/
 | [docker-setup.md](system/docker-setup.md) | Docker 환경 + CI/CD |
 | [database/README.md](system/database/README.md) | DB 스키마 인덱스 |
 | [security-policy.md](system/security-policy.md) | 보안 정책 |
+| [server-access-management.md](system/server-access-management.md) | 서버 접근 권한, 백업, 리플리케이션 |
 | [scaling-roadmap.md](system/scaling-roadmap.md) | 스케일링 로드맵 |
 | [board-system-spec.md](system/board-system-spec.md) | 게시판 시스템 설계 |
 | [item-master-integration.md](system/item-master-integration.md) | 품목 마스터 통합 설계 |

README.md

@@ -1,4 +1,4 @@
-# SAM 프로젝트 문서
+# SAM 프로젝트 문서
 
 SAM ERP 시스템의 기술 문서, 비즈니스 규칙, 기능 명세를 관리하는 저장소입니다.
 

dev/dev_plans/document-snapshot-architecture-plan.md

@@ -0,0 +1,385 @@
+# 문서 스냅샷 아키텍처 계획
+
+> **작성일**: 2026-03-06
+> **목적**: 문서 보기/인쇄 시 HTML 스냅샷 기반 출력으로 전환 (B안 + 구조화 데이터 병행)
+> **상태**: ✅ 코드 완료 (검증 대기)
+> **영향 범위**: API(저장), React(캡처/전송), MNG(출력)
+
+---
+
+## 현재 진행 상태
+
+| 항목 | 내용 |
+|------|------|
+| **마지막 완료 작업** | Phase 2 전면 보정: API 누락 수정, 오프스크린 렌더링 적용, readOnly 자동 캡처 제거 |
+| **다음 작업** | Phase 4: 브라우저 검증 + 기존 partial 정리 |
+| **진행률** | 13/13 (100% 코드 완료, 검증 대기) |
+| **마지막 업데이트** | 2026-03-06 |
+
+---
+
+## 1. 개요
+
+### 1.1 배경
+
+현재 MNG 문서 보기(`show.blade.php`)는 문서 양식별로 전용 blade partial을 만들어 렌더링한다:
+- `bending-inspection-data.blade.php` (절곡 중간검사)
+- `bending-worklog.blade.php` (절곡 작업일지)
+
+이 방식의 문제:
+1. **확장 불가**: 회사마다 다양한 양식이 존재 → 양식마다 blade 파일 생성 불가
+2. **스냅샷 미보장**: 하드코딩된 제품 목록/도면치수가 정책 변경 시 과거 문서를 깨뜨림
+3. **이중 렌더링**: React와 MNG에서 동일 문서를 각각 렌더링 → 불일치 발생
+
+### 1.2 목표 아키텍처
+
+```
+[React] 문서 저장 시
+├── 구조화 데이터 저장 (기존 유지)
+│   ├── document_data (EAV 플랫)
+│   └── work_order_items.options.inspection_data (JSON 스냅샷)
+└── rendered_html 저장 (신규)
+    └── React가 렌더링한 HTML을 캡처 → documents.rendered_html에 저장
+
+[MNG] 문서 보기 시
+├── rendered_html 있으면 → 그대로 출력 (렌더링 로직 0)
+└── rendered_html 없으면 → 기존 동적 렌더링 fallback
+```
+
+### 1.3 핵심 원칙
+
+```
+1. 하나의 view 파일로 모든 문서를 보기 (문서 양식별 blade 파일 금지)
+2. rendered_html이 있으면 무조건 그것을 사용 (완전한 스냅샷)
+3. 구조화 데이터는 편집/검색/통계용으로 병행 유지
+4. React에서만 문서 렌더링 책임 → MNG는 출력만 담당
+5. Lazy Snapshot: 조회 시 rendered_html 없으면 자동 캡처 → 저장 (점진적 스냅샷 전환)
+```
+
+### 1.4 변경 승인 정책
+
+| 분류 | 예시 | 승인 |
+|------|------|------|
+| 즉시 가능 | blade 템플릿 수정, 기존 partial 정리 | 불필요 |
+| 컨펌 필요 | API 저장 로직 변경, React 저장 흐름 변경 | **필수** |
+| 금지 | documents 테이블 구조 변경 (이미 rendered_html 존재) | 불필요 |
+
+---
+
+## 2. 현황 분석
+
+### 2.1 DB 현황
+
+`documents` 테이블에 이미 `rendered_html` (LONGTEXT, nullable) 컬럼이 존재:
+- 마이그레이션: `api/database/migrations/2026_02_28_100001_add_block_data_to_documents.php`
+- 현재 값: 모든 문서에서 NULL (사용 안 됨)
+- **DB 변경 불필요**
+
+### 2.2 React 현황 (구현 완료)
+
+#### 캡처 원칙 A: 입력 시 저장 (Active Capture)
+
+입력 화면에서 저장할 때 해당 데이터의 "문서 뷰"를 캡처. 보기(readOnly)에서는 캡처하지 않음.
+
+| Save Path | 파일 | 방식 | 캡처 대상 |
+|-----------|------|------|----------|
+| 작업일지 저장 | `WorkLogModal.tsx` | contentWrapperRef.innerHTML | 작업일지 문서 뷰 |
+| 검사성적서 저장 (edit) | `InspectionReportModal.tsx` | contentWrapperRef.innerHTML | 검사 성적서 문서 뷰 |
+| 수입검사 저장 | `ImportInspectionInputModal.tsx` | 오프스크린 렌더링 (`captureRenderedHtml`) | 수입검사 성적서 문서 (`ImportInspectionDocument`) |
+| WorkerScreen 인라인 검사 저장 | `index.tsx` | 미캡처 (데이터만 저장) | 성적서 모달에서 저장 시 캡처 |
+
+> **WorkerScreen 인라인 저장**: 검사 입력 시점에 성적서 문서가 렌더링되지 않으므로 rendered_html 미포함.
+> 이후 InspectionReportModal을 edit 모드로 열어 저장하면 캡처됨.
+> 향후 오프스크린 렌더링으로 확장 가능 (템플릿 로딩 등 async 의존성 해결 필요).
+
+#### 캡처 원칙 B: 조회 시 자동 캡처 (Lazy Snapshot)
+
+문서 조회(view/readOnly) 시 `rendered_html`이 없으면 자동 캡처하여 백그라운드 저장.
+
+```
+문서 View 시
+├── rendered_html 있음 → 그대로 표시 (기존)
+└── rendered_html 없음 → 동적 렌더링 완료 후 캡처 → API로 rendered_html 저장
+                          (다음 조회부터는 스냅샷 사용)
+```
+
+**적용 대상**:
+- readonly 문서 (제품검사 요청서 등 — 입력 없이 자동 생성되는 문서)
+- 마이그레이션 이전 기존 데이터 (rendered_html이 NULL인 과거 문서)
+- WorkerScreen 인라인 저장 후 아직 모달에서 저장하지 않은 문서
+
+**구현 방식**:
+```typescript
+// 문서 표시 컴포넌트에서 (DocumentViewer, Modal 등)
+useEffect(() => {
+  if (document && !document.rendered_html && isContentRendered) {
+    const html = contentWrapperRef.current?.innerHTML
+              || await captureRenderedHtml(DocumentComponent, props);
+    patchDocumentRenderedHtml(document.id, html); // 백그라운드 저장
+  }
+}, [document, isContentRendered]);
+```
+
+**고려사항**:
+- 사용자 UX 영향 없음 (백그라운드 비동기 저장)
+- 조회 권한만 있는 사용자도 트리거 가능해야 함
+- 동시 접속 시 중복 저장 가능 → 같은 HTML이므로 실질적 문제 없음
+- 캡처 타이밍: template 로드 + 데이터 바인딩 완료 후 (isContentRendered 판단 필요)
+
+### 2.3 API 현황 (구현 완료)
+
+- Document 모델 `$fillable`에 `rendered_html` 포함 ✅
+- `DocumentService` store/update에서 `rendered_html` 저장 ✅
+- `DocumentService` upsert에서 `rendered_html` 전달 ✅ (수입검사 경로)
+- `StoreRequest`/`UpdateRequest`에 `rendered_html` nullable string 검증 ✅
+- `UpsertRequest`에 `rendered_html` nullable string 검증 ✅
+
+### 2.4 MNG 현황 (구현 완료)
+
+- `show.blade.php`: rendered_html 우선 출력, 없으면 기존 동적 렌더링 fallback ✅
+- `print.blade.php`: 동일 패턴 적용 ✅
+- 전용 partial 파일 (삭제 대기):
+  - `partials/bending-inspection-data.blade.php`
+  - `partials/bending-worklog.blade.php`
+
+---
+
+## 3. 작업 범위
+
+### Phase 0: 사전 정리
+
+| # | 작업 항목 | 상태 | 비고 |
+|---|----------|:----:|------|
+| 0.1 | API Document 모델 $fillable 확인 및 rendered_html 추가 | ✅ | |
+| 0.2 | 기존 절곡 전용 partial 파일 정리 방침 결정 | ✅ | rendered_html 전환 후 삭제 |
+
+### Phase 1: API - rendered_html 저장 지원
+
+| # | 작업 항목 | 상태 | 비고 |
+|---|----------|:----:|------|
+| 1.1 | Document 모델 $fillable에 rendered_html 추가 | ✅ | |
+| 1.2 | DocumentService store/update에서 rendered_html 저장 | ✅ | |
+| 1.3 | StoreRequest/UpdateRequest에 rendered_html 검증 추가 | ✅ | nullable, string |
+| 1.4 | WorkOrderService inspection/worklog에 rendered_html 전달 | ✅ | create + update 모두 |
+
+### Phase 2: React - HTML 캡처 및 전송
+
+| # | 작업 항목 | 상태 | 비고 |
+|---|----------|:----:|------|
+| 2.1 | 오프스크린 렌더링 유틸리티 생성 | ✅ | `captureRenderedHtml()` — `flushSync` + `createRoot` |
+| 2.2 | InspectionReportModal 저장 시 rendered_html 포함 전송 | ✅ | contentWrapperRef.innerHTML 캡처 |
+| 2.3 | 작업일지 저장 시 rendered_html 포함 전송 | ✅ | contentWrapperRef.innerHTML 캡처 |
+| 2.4 | ImportInspectionInputModal 수입검사 저장 시 rendered_html | ✅ | 오프스크린 성적서 문서 렌더링 |
+| 2.5 | ReceivingManagement/actions saveInspectionData 파라미터 추가 | ✅ | rendered_html → /documents/upsert 전달 |
+| 2.6 | API UpsertRequest에 rendered_html 검증 추가 | ✅ | nullable string |
+
+### Phase 3: MNG - 스냅샷 출력
+
+| # | 작업 항목 | 상태 | 비고 |
+|---|----------|:----:|------|
+| 3.1 | show.blade.php에 rendered_html 우선 출력 로직 추가 | ✅ | |
+| 3.2 | 기존 전용 partial 파일 fallback으로 유지 (과도기) | ✅ | |
+| 3.3 | print.blade.php에도 rendered_html 출력 적용 | ✅ | 스냅샷 우선, 레거시 fallback |
+
+### Phase 4: 검증 및 정리
+
+| # | 작업 항목 | 상태 | 비고 |
+|---|----------|:----:|------|
+| 4.1 | 브라우저 검증 (MNG 보기/인쇄) | ⏳ | |
+| 4.2 | 기존 전용 partial 파일 삭제 | ⏳ | rendered_html 전환 완료 후 |
+
+---
+
+## 4. 상세 작업 내용
+
+### 4.1 HTML 캡처 방식 (Phase 2.1)
+
+React에서 문서 컨텐츠 영역의 DOM을 캡처할 때 고려사항:
+
+**방법 A: innerHTML 직접 추출 + CSS 인라인화**
+```typescript
+// 문서 컨텐츠 영역에 ref 부여
+const contentRef = useRef<HTMLDivElement>(null);
+
+// 저장 시 HTML 추출
+const captureHtml = () => {
+  const el = contentRef.current;
+  if (!el) return '';
+
+  // Tailwind 클래스 → 인라인 스타일 변환 (또는 스타일시트 포함)
+  // 방법 1: 계산된 스타일을 인라인으로
+  // 방법 2: 필요한 Tailwind CSS를 <style> 태그로 포함
+  return el.innerHTML;
+};
+```
+
+**방법 B: 자체 CSS 포함 완전한 HTML 조각**
+```html
+<div class="document-snapshot">
+  <style>/* 필요한 스타일만 추출 */</style>
+  <!-- 문서 컨텐츠 -->
+</div>
+```
+
+**권장: 방법 B** — MNG에서 Tailwind가 로드되어 있으므로, Tailwind 클래스를 그대로 사용하되 MNG에 없는 커스텀 스타일만 `<style>` 태그로 포함. MNG도 Tailwind를 사용하므로 대부분의 클래스가 호환됨.
+
+### 4.2 MNG 출력 구조 (Phase 3.1)
+
+```blade
+{{-- show.blade.php --}}
+@if($document->rendered_html)
+    {{-- 스냅샷 모드: React가 생성한 HTML 그대로 출력 --}}
+    <div class="document-snapshot-container">
+        {!! $document->rendered_html !!}
+    </div>
+@else
+    {{-- 동적 모드: 기존 템플릿 기반 렌더링 (fallback) --}}
+    @include('documents.partials.dynamic-render')
+@endif
+```
+
+### 4.3 스타일 호환성 전략
+
+| 항목 | React (Tailwind) | MNG (Tailwind) | 호환성 |
+|------|------------------|----------------|--------|
+| 기본 클래스 | px-2, py-1, border 등 | 동일 | 완전 호환 |
+| 반응형 | sm:, md:, lg: | inline style 정책 | 주의 필요 |
+| 커스텀 컴포넌트 | shadcn/ui | 없음 | `<style>` 포함 필요 |
+
+**결론**: React에서 문서 영역은 순수 HTML+Tailwind로 렌더링 (shadcn 컴포넌트 미사용) → MNG 호환성 높음.
+단, `@media` 쿼리나 MNG에서 빌드되지 않은 Tailwind 클래스가 있을 수 있으므로 필요 시 인라인 스타일 변환.
+
+### 4.4 XSS 보안 고려
+
+`{!! !!}` (unescaped output) 사용 시 XSS 위험:
+- `rendered_html`은 **자체 시스템(React)에서만 생성** → 외부 입력 아님
+- API 저장 시 **sanitize** 처리 권장 (script 태그, on* 이벤트 제거)
+- 또는 CSP(Content Security Policy)로 인라인 스크립트 차단
+
+---
+
+## 5. 참고 파일
+
+### React (수정 대상)
+- `react/src/components/production/WorkOrders/documents/InspectionReportModal.tsx` — 저장 흐름 (contentWrapperRef)
+- `react/src/components/production/WorkOrders/documents/BendingInspectionContent.tsx` — 검사 문서 렌더링
+- `react/src/components/production/WorkOrders/documents/BendingWorkLogContent.tsx` — 작업일지 렌더링
+- `react/src/components/production/WorkOrders/documents/bending/` — 절곡 섹션 컴포넌트들
+- `react/src/components/production/WorkerScreen/WorkLogModal.tsx` — 작업일지 저장 시 캡처
+- `react/src/components/material/ReceivingManagement/ImportInspectionInputModal.tsx` — 수입검사 저장 시 오프스크린 캡처
+- `react/src/components/material/ReceivingManagement/actions.ts` — saveInspectionData rendered_html 전달
+- `react/src/lib/utils/capture-rendered-html.tsx` — 오프스크린 렌더링 유틸리티 (신규)
+
+### API (수정 대상)
+- `api/app/Models/Documents/Document.php` — $fillable
+- `api/app/Services/DocumentService.php` — store/update/upsert
+- `api/app/Http/Requests/Documents/StoreRequest.php` — 검증
+- `api/app/Http/Requests/Documents/UpdateRequest.php` — 검증
+- `api/app/Http/Requests/Document/UpsertRequest.php` — 검증 (수입검사 경로)
+
+### MNG (수정 대상)
+- `mng/resources/views/documents/show.blade.php` — 메인 보기
+- `mng/resources/views/documents/print.blade.php` — 인쇄
+- `mng/resources/views/documents/partials/bending-inspection-data.blade.php` — 삭제 예정
+- `mng/resources/views/documents/partials/bending-worklog.blade.php` — 삭제 예정
+- `mng/app/Http/Controllers/DocumentController.php` — show()
+
+### DB
+- `api/database/migrations/2026_02_28_100001_add_block_data_to_documents.php` — rendered_html 컬럼 (이미 존재)
+
+### 문서
+- `docs/features/documents/README.md` — 문서관리 시스템
+- `docs/system/database/documents.md` — DB 스키마
+
+---
+
+## 6. 의존성 및 순서
+
+```
+Phase 0 (사전 정리)
+    ↓
+Phase 1 (API: rendered_html 저장)
+    ↓
+Phase 2 (React: HTML 캡처 + 전송)  ← Phase 1 완료 필요
+    ↓
+Phase 3 (MNG: 스냅샷 출력)  ← Phase 2 완료 후 데이터 존재
+    ↓
+Phase 4 (검증 + 정리)  ← 모든 Phase 완료 후
+```
+
+Phase 1과 Phase 3의 MNG 코드 수정은 병렬 가능 (fallback 유지).
+단, 실제 데이터가 있어야 검증 가능하므로 Phase 2 완료 후 통합 검증.
+
+---
+
+## 7. 리스크 및 대응
+
+| 리스크 | 영향 | 대응 |
+|--------|------|------|
+| HTML 용량 | 문서당 50-200KB, 수만 건 시 GB | LONGTEXT 이미 사용, 필요 시 gzip 압축 |
+| Tailwind 클래스 불일치 | MNG에서 일부 스타일 깨짐 | 인라인 스타일 변환 또는 MNG Tailwind 빌드에 포함 |
+| XSS | rendered_html에 악성 코드 | API에서 sanitize, CSP 정책 |
+| 과도기 fallback | rendered_html 없는 기존 문서 | 기존 동적 렌더링 유지 |
+| React 미경유 문서 | MNG에서만 생성된 문서 | MNG 저장 시에도 rendered_html 생성 검토 |
+
+---
+
+## 8. 변경 이력
+
+| 날짜 | 항목 | 변경 내용 | 파일 | 승인 |
+|------|------|----------|------|------|
+| 2026-03-06 | - | 계획 문서 작성 | - | - |
+| 2026-03-06 | Phase 0~3 | Phase 0~3 전체 구현 완료 | API/React/MNG 다수 | ✅ |
+| 2026-03-06 | Phase 2.4~2.6 | 모든 저장 경로에 rendered_html 추가 | InspectionReportModal, ImportInspectionInputModal, actions.ts | ✅ |
+| 2026-03-06 | Phase 2 보정 | API UpsertRequest rendered_html 누락 수정, DocumentService upsert() rendered_html 전달 추가 | UpsertRequest.php, DocumentService.php | ✅ |
+| 2026-03-06 | Phase 2 보정 | ImportInspection: 입력폼 캡처 → 오프스크린 성적서 렌더링으로 변경 | ImportInspectionInputModal.tsx, capture-rendered-html.tsx | ✅ |
+| 2026-03-06 | Phase 2 보정 | InspectionReportModal readOnly 자동 캡처 useEffect 제거 | InspectionReportModal.tsx | ✅ |
+| 2026-03-06 | 원칙 확장 | Lazy Snapshot 패턴 추가 — 조회 시 rendered_html 없으면 자동 캡처/저장 | 아키텍처 원칙 | - |
+
+---
+
+## 9. 검증 결과
+
+> 작업 완료 후 이 섹션에 검증 결과 추가
+
+### 9.1 성공 기준
+
+| 기준 | 달성 | 비고 |
+|------|------|------|
+| React 저장 시 rendered_html이 documents 테이블에 저장 | ⏳ | |
+| mng.sam.kr/documents/36 에서 rendered_html로 문서 출력 | ⏳ | |
+| mng.sam.kr/documents/39 에서 rendered_html로 문서 출력 | ⏳ | |
+| rendered_html 없는 기존 문서가 기존대로 렌더링 | ⏳ | |
+| 인쇄 시에도 스냅샷 기반 출력 | ⏳ | |
+| 양식별 전용 blade 파일 없이 동작 | ⏳ | |
+
+---
+
+## 10. 자기완결성 점검 결과
+
+### 10.1 체크리스트 검증
+
+| # | 검증 항목 | 상태 | 비고 |
+|---|----------|:----:|------|
+| 1 | 작업 목적이 명확한가? | ✅ | 스냅샷 기반 문서 출력 |
+| 2 | 성공 기준이 정의되어 있는가? | ✅ | 9.1 참조 |
+| 3 | 작업 범위가 구체적인가? | ✅ | 5 Phase, 15개 작업 |
+| 4 | 의존성이 명시되어 있는가? | ✅ | 6. 의존성 참조 |
+| 5 | 참고 파일 경로가 정확한가? | ✅ | 5. 참고 파일 |
+| 6 | 단계별 절차가 실행 가능한가? | ✅ | 3. 작업 범위 |
+| 7 | 검증 방법이 명시되어 있는가? | ✅ | 9.1 성공 기준 |
+| 8 | 모호한 표현이 없는가? | ✅ | |
+
+### 10.2 새 세션 시뮬레이션 테스트
+
+| 질문 | 답변 가능 | 참조 섹션 |
+|------|:--------:|----------|
+| Q1. 이 작업의 목적은 무엇인가? | ✅ | 1.1 배경 |
+| Q2. 어디서부터 시작해야 하는가? | ✅ | Phase 0 → 1 → 2 → 3 |
+| Q3. 어떤 파일을 수정해야 하는가? | ✅ | 5. 참고 파일 |
+| Q4. 작업 완료 확인 방법은? | ✅ | 9.1 성공 기준 |
+| Q5. 막혔을 때 참고 문서는? | ✅ | 5. 참고 파일, docs/ |
+
+---
+
+*이 문서는 /plan 스킬로 생성되었습니다.*

dev/dev_plans/fqc-document-system-plan.md

@@ -0,0 +1,873 @@
+# 제품검사 문서 시스템 구축 계획
+
+> **작성일**: 2026-03-06
+> **목적**: 제품검사 성적서(template ID 65 보완) + 제품검사 요청서(신규 template)를 mng 양식 기반 동적 렌더링 + rendered_html 스냅샷 구조로 구현
+> **기준 문서**: `docs/dev/dev_plans/document-system-master.md`, `docs/dev/dev_plans/document-snapshot-architecture-plan.md`
+> **상태**: 확정 (2026-03-06)
+
+---
+
+## 현재 진행 상태
+
+| 항목 | 내용 |
+|------|------|
+| **마지막 완료 작업** | Phase 3 전체 완료 (통합 테스트 + fallback 검증 + 호환성 확인) |
+| **다음 작업** | 완료 — 추후 syncRequestDocument 기존 데이터 수동 실행 고려 |
+| **진행률** | 12/12 (100%) |
+| **마지막 업데이트** | 2026-03-06 |
+
+---
+
+## 1. 개요
+
+### 1.1 배경
+
+현재 제품검사 관련 문서가 **두 가지 방식**으로 혼재:
+- **하드코딩 React 컴포넌트** (`InspectionReportDocument.tsx`, `InspectionRequestDocument.tsx`) — mockData 기반 변환, 문서 저장 없음
+- **양식 기반 동적 렌더링** (`FqcDocumentContent.tsx`) — template ID 65 기반, 일부 구현됨 (4컬럼 단순 버전)
+
+기존 중간검사/수입검사/작업일지는 이미 **mng 양식 등록 → React 동적 렌더링 → rendered_html 스냅샷** 패턴으로 동작 중. 제품검사도 동일 패턴으로 통일해야 함.
+
+### 1.2 핵심 원칙
+
+```
+1. mng에서 양식(template) 등록/관리 → React에서 동적 렌더링
+2. 저장 시 rendered_html 스냅샷 함께 저장
+3. mng/히스토리에서는 스냅샷 출력 (렌더링 로직 0)
+4. 기존 하드코딩 컴포넌트는 fallback으로 유지 → 점진적 전환
+```
+
+### 1.3 변경 승인 정책
+
+| 분류 | 예시 | 승인 |
+|------|------|------|
+| 즉시 가능 | mng 양식 항목 추가/수정, React 컴포넌트 수정 | 불필요 |
+| 컨펌 필요 | API 저장 로직 변경, 새 API 엔드포인트, DB 마이그레이션 | **필수** |
+| 금지 | documents 테이블 구조 변경, 기존 기능 삭제 | 별도 협의 |
+
+### 1.4 준수 규칙
+- `docs/dev/standards/quality-checklist.md` - 품질 체크리스트
+- `docs/dev/standards/git-conventions.md` - Git 커밋 컨벤션
+- `docs/features/documents/README.md` - 문서관리 시스템 스펙
+
+---
+
+## 2. 현재 시스템 분석
+
+### 2.1 기존 패턴 (참조 모델: 중간검사)
+
+```
+[mng] DocumentTemplate (양식 등록)
+  ├── approval_lines: 결재선 (작성/검토/승인)
+  ├── basic_fields: 기본필드 (납품명, 제품명, 발주처 등)
+  ├── sections: 섹션 (검사기준서 이미지, 검사 DATA)
+  │   └── items: 검사항목 (항목명, 기준, 측정유형)
+  └── columns: 컬럼 정의 (NO, 검사항목, 검사기준, 판정)
+
+[React] 동적 렌더링
+  ├── API로 template 조회 (GET /v1/document-templates/{id})
+  ├── TemplateInspectionContent / FqcDocumentContent 등으로 렌더링
+  ├── 편집 모드: 판정 토글, 측정값 입력
+  └── 저장 시 rendered_html 캡처 → API 전송
+
+[API] 저장
+  ├── document_data (EAV): 구조화 데이터 (검색/통계용)
+  └── documents.rendered_html: HTML 스냅샷 (출력용)
+
+[MNG] 출력
+  ├── rendered_html 있으면 → 그대로 출력 ({!! $document->rendered_html !!})
+  └── 없으면 → 기존 동적 렌더링 fallback
+```
+
+### 2.2 제품검사 성적서 현재 상태 (template ID 65)
+
+**mng 양식 (ID 65)**: Phase 5.2에서 시더로 생성됨
+- 시더 위치: `mng/database/seeders/ProductInspectionTemplateSeeder.php` (tenant_id=287 하드코딩)
+- 결재 3인 (작성/검토/승인)
+- 기본필드 7개 (납품명, 제품명, 발주처, LOT NO, 로트크기, 검사일자, 검사자)
+- 섹션 2개 (검사기준서 이미지, 검사 DATA)
+- 검사항목 11개 (설치 후 최종검사, 모두 visual/checkbox)
+- **컬럼 4개** (NO, 검사항목, 검사기준, 판정) ← **보완 대상**
+
+**React 구현 현황**:
+- `FqcDocumentContent.tsx` — template 기반 동적 렌더링 (읽기/편집 모드), **현재 4컬럼**
+- `InspectionReportDocument.tsx` — 하드코딩 fallback (**8컬럼 상세 버전**)
+- `InspectionReportModal.tsx` — 듀얼 모드 (useFqcMode: fqcDocumentMap 존재 여부로 판단)
+
+**문제점**:
+1. 하드코딩 버전이 훨씬 상세함 (8컬럼, rowSpan 병합, 측정값, 검사방법/주기)
+2. template ID 65는 4컬럼으로 단순 → 하드코딩 수준으로 보완 필요
+3. rendered_html 스냅샷 저장이 FQC 문서에 아직 미적용
+
+### 2.3 제품검사 요청서 현재 상태
+
+**mng 양식**: 없음 (신규 생성 필요)
+
+**React 구현**:
+- `InspectionRequestDocument.tsx` — 하드코딩 컴포넌트 (완성도 높음)
+- `InspectionRequestModal.tsx` — DocumentViewer + 하드코딩 컴포넌트
+- 데이터 변환: `buildRequestDocumentData()` (mockData.ts:398-423)
+
+**구조**:
+- 결재라인 (작성/승인)
+- 기본정보 (수주처, 업체명, 담당자, 수주번호, 연락처, 현장명, 납품일, 현장주소, 총개소, 접수일, 검사방문요청일)
+- 입력사항 4개 섹션 (건축공사장, 자재유통업자, 공사시공자, 공사감리자)
+- 검사 요청 시 필독 (고정 텍스트)
+- 검사대상 사전 고지 정보 테이블 (No, 층수, 부호, 발주규격 가로/세로, 시공후규격 가로/세로, 변경사유)
+
+---
+
+## 3. 대상 범위
+
+### Phase 1: 제품검사 성적서 (template ID 65) 보완
+
+| # | 작업 항목 | 상태 | 비고 |
+|---|----------|:----:|------|
+| 1.1 | mng template ID 65 양식 보완 — section_items 교체 + template columns 2개로 재정의 | ✅ | items 11→22개, columns 4→2개(측정값+판정) |
+| 1.2 | FqcDocumentContent.tsx 동적 렌더링 보완 + 프론트 타입 수정 | ✅ | 8컬럼 시각 레이아웃 + rowSpan 복합키 병합 + measurement_type=none 처리 |
+| 1.3 | rendered_html 스냅샷 저장 적용 | ✅ | saveFqcDocument에 renderedHtml 파라미터 추가 + contentWrapperRef 준비 |
+| 1.4 | InspectionReportModal에서 양식 모드 기본값 전환 | ✅ | FQC 모드 우선, template 로드 실패 시 legacy fallback |
+
+### Phase 2: 제품검사 요청서 (신규 template)
+
+| # | 작업 항목 | 상태 | 비고 |
+|---|----------|:----:|------|
+| 2.1 | mng에 제품검사 요청서 template 신규 등록 (시더) | ✅ | template ID 66, description 컬럼 추가 |
+| 2.2 | React 동적 렌더링 컴포넌트 구현 | ✅ | FqcRequestDocumentContent, InspectionRequestModal FQC 모드 |
+| 2.3 | 요청서 문서 생성 API 연동 | ✅ | syncRequestDocument(), store/update/attachOrders 연동 |
+| 2.4 | rendered_html 스냅샷 저장 적용 (Lazy Snapshot) | ✅ | patchDocumentSnapshot, contentWrapperRef 캡처 |
+
+### Phase 3: 통합 및 정리
+
+| # | 작업 항목 | 상태 | 비고 |
+|---|----------|:----:|------|
+| 3.1 | InspectionDetail.tsx 모달 연동 통합 테스트 | ✅ | 요청서(legacy fallback) + 성적서(FQC 8컬럼) 정상 |
+| 3.2 | mng 문서 보기에서 스냅샷 출력 확인 | ✅ | show.blade.php rendered_html 우선 출력 패턴 코드 검증 |
+| 3.3 | 하드코딩 컴포넌트 fallback 유지 확인 | ✅ | requestDocumentId 없으면 legacy fallback 정상 동작 |
+| 3.4 | 기존 FQC 데이터 호환성 확인 | ✅ | 기존 EAV 데이터(basic_fields) 정상 표시 |
+
+---
+
+## 4. 작업 절차
+
+### 4.1 단계별 절차
+
+```
+Phase 1: 제품검사 성적서 보완
+├── Step 1.1: mng template ID 65 시더 보완
+│   ├── template columns 재정의: 4→2개 (측정값+판정만, 나머지는 section_item 필드)
+│   ├── section_items 교체: 11개→22개 (섹션 5.1.2의 상세 항목 데이터)
+│   ├── cleanupExisting() → updateOrCreate() 패턴으로 ID 안정성 확보 (섹션 5.1.9)
+│   ├── mng에서 시더 실행 후 미리보기 확인
+│   └── 파일: mng/database/seeders/ProductInspectionTemplateSeeder.php
+│
+├── Step 1.2: FqcDocumentContent.tsx 8컬럼 렌더링 보완
+│   ├── [선행] fqcActions.ts 타입 수정: TemplateItemApi, FqcTemplateItem에 category/method/frequency/measurement_type 추가 (섹션 5.1.7)
+│   ├── [선행] transformTemplate()에서 새 필드 매핑 추가
+│   ├── 8컬럼 시각 레이아웃: 1~6 section_item 읽기전용 + 7~8 template column 편집 (섹션 5.1.1)
+│   ├── rowSpan 복합키 병합: category 단독 + method+frequency 복합키 (섹션 5.1.3)
+│   ├── 측정값 입력 분기: numeric→input, checkbox→양호/불량, none→비활성 (섹션 5.1.8)
+│   ├── 종합판정: measurement_type='none' 제외하고 계산 (섹션 5.1.8)
+│   └── 파일: fqcActions.ts + FqcDocumentContent.tsx
+│
+├── Step 1.3: rendered_html 스냅샷 적용
+│   ├── FqcDocumentContent의 wrapper div에 ref 연결
+│   ├── saveFqcDocument 호출 시 contentWrapperRef.current.innerHTML 캡처
+│   ├── fqcActions.ts의 saveFqcDocument()에 rendered_html 파라미터 추가
+│   ├── API: POST /v1/documents/upsert → DocumentService에서 rendered_html 저장 (이미 지원됨)
+│   └── 파일: fqcActions.ts, InspectionReportModal.tsx
+│
+└── Step 1.4: 양식 모드 기본값 전환
+    ├── InspectionReportModal.tsx에서 FQC 모드 우선 표시
+    ├── fqcDocumentMap 없어도 template 로드 시도
+    └── 레거시 모드 fallback 유지
+
+Phase 2: 제품검사 요청서 신규
+├── Step 2.1: mng template 등록 (시더 방식 확정)
+│   ├── 양식 구조 설계 (섹션 5.2의 상세 구조 참조)
+│   ├── 시더 작성 (ProductInspectionRequestTemplateSeeder)
+│   ├── mng 시더 실행 후 미리보기 확인
+│   └── 파일: mng/database/seeders/ProductInspectionRequestTemplateSeeder.php (신규)
+│
+├── Step 2.2: React 동적 렌더링
+│   ├── FqcRequestDocumentContent.tsx 신규 생성 (또는 기존 FqcDocumentContent 확장)
+│   ├── quality_documents 데이터 → 문서 데이터 매핑
+│   ├── 사전 고지 정보 테이블 (quality_document_locations → 테이블 행)
+│   ├── InspectionRequestModal에 양식 기반 모드 추가
+│   └── 파일: react/.../documents/ 디렉토리
+│
+├── Step 2.3: API 연동 (quality_document 생성 시 자동 생성 확정)
+│   ├── QualityDocumentService::store()에서 요청서 document 자동 생성
+│   ├── 기본필드 자동 매핑 (quality_document → document basic_fields)
+│   ├── 개소 데이터 자동 매핑 (quality_document_locations → 사전고지 테이블)
+│   └── 파일: api/app/Services/QualityDocumentService.php
+│
+└── Step 2.4: rendered_html 스냅샷 (Lazy Snapshot 패턴)
+    ├── 요청서는 readonly 문서 → "입력 시 저장" 캡처 불가
+    ├── Lazy Snapshot 적용: 요청서 최초 조회 시 rendered_html 없으면 자동 캡처
+    ├── captureRenderedHtml 유틸리티 활용 (react/src/lib/utils/capture-rendered-html.tsx)
+    ├── 또는 contentWrapperRef.innerHTML로 렌더링 완료 후 캡처
+    ├── 백그라운드 API 호출로 rendered_html 저장 (PATCH /v1/documents/{id} 또는 upsert)
+    └── 참조: document-snapshot-architecture-plan.md 캡처 원칙 B
+
+Phase 3: 통합 및 정리
+├── InspectionDetail.tsx에서 모달 연동 통합 테스트
+├── mng show.blade.php에서 스냅샷 출력 확인
+├── 하드코딩 fallback 정상 동작 확인
+└── 기존 FQC 데이터 호환성 확인
+```
+
+---
+
+## 5. 상세 작업 내용
+
+### 5.1 제품검사 성적서 양식 보완 상세 (Phase 1.1)
+
+#### 5.1.1 컬럼 구조 — Template columns vs Display columns (핵심 구분)
+
+> **핵심**: Template columns는 EAV 편집 가능 필드만 정의. 8컬럼 시각 레이아웃은 React에서 section_item 필드 + template columns를 조합하여 렌더링.
+
+**Template columns = EAV 데이터 저장용 (편집 가능 필드만)**
+
+현재 4컬럼 중 실제 EAV로 저장하는 것은 `판정`(select) 하나뿐. 나머지 3개(NO, 검사항목, 검사기준)는 section_item 필드의 읽기 전용 표시.
+
+**목표 template columns (2~3개)** — 시더에 반영:
+
+| 컬럼 | label | column_type | width | 비고 |
+|------|-------|-------------|-------|------|
+| 1 | 측정값 | measurement | 70px | measurement_type별 입력 (numeric/checkbox) |
+| 2 | 판정 | select | 50px | 적합/부적합 |
+
+> `measurement_type='none'`인 항목(작동테스트)은 측정값/판정 컬럼 모두 비활성.
+
+**8컬럼 시각 레이아웃 (React 렌더링)**:
+
+| 시각 컬럼 | 데이터 소스 | 편집 가능 |
+|-----------|-----------|:---------:|
+| 1. No. | section_item 순번 (category별 그룹 번호) | ❌ |
+| 2. 검사항목 | section_item.`category` | ❌ |
+| 3. 세부항목 | section_item.`item` | ❌ |
+| 4. 검사기준 | section_item.`standard` | ❌ |
+| 5. 검사방법 | section_item.`method` | ❌ |
+| 6. 검사주기 | section_item.`frequency` | ❌ |
+| 7. 측정값 | template column `measurement` → document_data EAV | ✅ |
+| 8. 판정 | template column `select` → document_data EAV | ✅ |
+
+> 1~6번은 section_item의 읽기 전용 필드를 React에서 직접 렌더링. 7~8번만 template columns로 정의하여 document_data에 EAV 저장.
+
+#### 5.1.2 검사항목 데이터 (시더에 반영할 section_items)
+
+**방안 C 확정** — 하드코딩 `mockReportInspectionItems` (mockData.ts:426-458)을 template section_items로 이관.
+
+`DocumentTemplateSectionItem` 필드 매핑:
+
+| mock 필드 | DB 필드 | 설명 |
+|-----------|---------|------|
+| category | `category` | 검사 그룹명 (겉모양, 모터, 치수 등) |
+| subCategory | `item` | 세부 항목명 (가공상태, 길이 등) |
+| criteria | `standard` | 검사 기준 |
+| method | `method` | 검사 방법 |
+| frequency | `frequency` | 검사 주기 |
+| measurement_type | `measurement_type` | checkbox/numeric/none |
+
+**시더 section_items 데이터** (검사 DATA 섹션):
+
+```php
+// 섹션: 검사 DATA
+$items = [
+    // === 1. 겉모양 (5개 세부항목, method/freq 동일: 육안검사/전수검사) ===
+    ['category' => '겉모양', 'item' => '가공상태', 'standard' => '흠, 녹 등 확인', 'method' => '육안검사', 'frequency' => '전수검사', 'measurement_type' => 'checkbox'],
+    ['category' => '겉모양', 'item' => '재봉상태', 'standard' => '이중 재봉 상태', 'method' => '육안검사', 'frequency' => '전수검사', 'measurement_type' => 'checkbox'],
+    ['category' => '겉모양', 'item' => '조립상태', 'standard' => '개폐 작동', 'method' => '육안검사', 'frequency' => '전수검사', 'measurement_type' => 'checkbox'],
+    ['category' => '겉모양', 'item' => '연기차단재', 'standard' => '접착력 확인', 'method' => '육안검사', 'frequency' => '전수검사', 'measurement_type' => 'checkbox'],
+    ['category' => '겉모양', 'item' => '하단마감재', 'standard' => '접착력 확인', 'method' => '육안검사', 'frequency' => '전수검사', 'measurement_type' => 'checkbox'],
+
+    // === 2. 모터 ===
+    ['category' => '모터', 'item' => '-', 'standard' => '인정제품과 동일사양', 'method' => '육안검사', 'frequency' => '전수검사', 'measurement_type' => 'checkbox'],
+
+    // === 3. 재질 ===
+    ['category' => '재질', 'item' => '-', 'standard' => 'WY-SC780 인쇄상태 확인', 'method' => '육안검사', 'frequency' => '전수검사', 'measurement_type' => 'checkbox'],
+
+    // === 4. 치수(오픈사이즈) (4개 세부항목, method: 체크검사) ===
+    ['category' => '치수(오픈사이즈)', 'item' => '길이(W)', 'standard' => '수주치수 +-30mm', 'method' => '체크검사', 'frequency' => '전수검사', 'measurement_type' => 'numeric'],
+    ['category' => '치수(오픈사이즈)', 'item' => '높이(H)', 'standard' => '수주치수 +-20mm', 'method' => '체크검사', 'frequency' => '전수검사', 'measurement_type' => 'numeric'],
+    ['category' => '치수(오픈사이즈)', 'item' => '가이드레일 간격', 'standard' => '수주치수 +-10mm', 'method' => '체크검사', 'frequency' => '전수검사', 'measurement_type' => 'numeric'],
+    ['category' => '치수(오픈사이즈)', 'item' => '하단막대 간격', 'standard' => '수주치수 +-10mm', 'method' => '체크검사', 'frequency' => '전수검사', 'measurement_type' => 'numeric'],
+
+    // === 5. 작동테스트 ===
+    ['category' => '작동테스트', 'item' => '개폐성능', 'standard' => '작동 유무 확인', 'method' => '', 'frequency' => '', 'measurement_type' => 'none'],
+
+    // === 6. 내화시험 (3개 세부항목, method: 공인시험기관, freq: 1회/5년) ===
+    ['category' => '내화시험', 'item' => '비차열 1시간', 'standard' => '균열게이지 불관통', 'method' => '공인시험기관', 'frequency' => '1회/5년', 'measurement_type' => 'checkbox'],
+    ['category' => '내화시험', 'item' => '차열성', 'standard' => '이면온도 상승제한', 'method' => '공인시험기관', 'frequency' => '1회/5년', 'measurement_type' => 'checkbox'],
+    ['category' => '내화시험', 'item' => '비손상성', 'standard' => '화염 비관통', 'method' => '공인시험기관', 'frequency' => '1회/5년', 'measurement_type' => 'checkbox'],
+
+    // === 7. 차연시험 ===
+    ['category' => '차연시험', 'item' => '공기누설량', 'standard' => '25Pa 기준 0.9m3/min.m2 이하', 'method' => '공인시험기관', 'frequency' => '1회/5년', 'measurement_type' => 'checkbox'],
+
+    // === 8. 개폐시험 (5개 세부항목) ===
+    ['category' => '개폐시험', 'item' => '개폐 작동', 'standard' => '10회 이상 개폐작동 이상없음', 'method' => '공인시험기관', 'frequency' => '1회/5년', 'measurement_type' => 'checkbox'],
+    ['category' => '개폐시험', 'item' => '폐쇄 시간', 'standard' => '5초 이내 완전 폐쇄', 'method' => '공인시험기관', 'frequency' => '1회/5년', 'measurement_type' => 'checkbox'],
+    ['category' => '개폐시험', 'item' => '평균속도(상한)', 'standard' => '0.3m/sec 이하', 'method' => '공인시험기관', 'frequency' => '1회/5년', 'measurement_type' => 'checkbox'],
+    ['category' => '개폐시험', 'item' => '평균속도(하한)', 'standard' => '0.07m/sec 이상', 'method' => '공인시험기관', 'frequency' => '1회/5년', 'measurement_type' => 'checkbox'],
+    ['category' => '개폐시험', 'item' => '과부하', 'standard' => '과부하 작동 이상없음', 'method' => '공인시험기관', 'frequency' => '1회/5년', 'measurement_type' => 'checkbox'],
+
+    // === 9. 내충격시험 ===
+    ['category' => '내충격시험', 'item' => '-', 'standard' => '낙하높이 기준 이상없음', 'method' => '공인시험기관', 'frequency' => '1회/5년', 'measurement_type' => 'checkbox'],
+];
+```
+
+#### 5.1.3 rowSpan 자동 병합 로직 (React 구현)
+
+하드코딩 `InspectionReportDocument.tsx`의 `buildCoverageMap()` (라인 42-57) 패턴을 **template 데이터 기반으로 자동화**.
+
+> **주의**: `method`와 `frequency`는 **복합 키**(method+frequency)로 병합해야 함.
+> 단일 필드 비교 시 frequency='전수검사'가 7+4=11행 연속으로 잘못 병합됨.
+> 실제로는 method가 다르면 (육안검사 7행 vs 체크검사 4행) 별도 그룹이어야 함.
+
+```typescript
+// category는 단일 필드 병합 (같은 category 연속이면 병합)
+function buildFieldRowSpan(items: SectionItem[], field: 'category') {
+  const spans: Map<number, number> = new Map();
+  const covered: Set<number> = new Set();
+
+  let i = 0;
+  while (i < items.length) {
+    const value = items[i][field];
+    if (!value) { i++; continue; }
+
+    let span = 1;
+    while (i + span < items.length && items[i + span][field] === value) {
+      covered.add(i + span);
+      span++;
+    }
+    if (span > 1) spans.set(i, span);
+    i += span;
+  }
+  return { spans, covered };
+}
+
+// method+frequency는 복합 키 병합
+function buildCompositeRowSpan(items: SectionItem[]) {
+  const spans: Map<number, number> = new Map();
+  const covered: Set<number> = new Set();
+
+  let i = 0;
+  while (i < items.length) {
+    const key = `${items[i].method || ''}|${items[i].frequency || ''}`;
+    if (!items[i].method && !items[i].frequency) { i++; continue; }
+
+    let span = 1;
+    while (i + span < items.length) {
+      const nextKey = `${items[i + span].method || ''}|${items[i + span].frequency || ''}`;
+      if (nextKey !== key) break;
+      covered.add(i + span);
+      span++;
+    }
+    if (span > 1) spans.set(i, span);
+    i += span;
+  }
+  return { spans, covered };
+}
+
+// 사용: 렌더링 시
+const categoryCoverage = buildFieldRowSpan(sectionItems, 'category');
+const methodFreqCoverage = buildCompositeRowSpan(sectionItems);
+// method 컬럼과 frequency 컬럼 모두 methodFreqCoverage로 렌더링
+
+// 셀 렌더링 예시
+{!categoryCoverage.covered.has(idx) && (
+  <td rowSpan={categoryCoverage.spans.get(idx) || 1}>{item.category}</td>
+)}
+{!methodFreqCoverage.covered.has(idx) && (
+  <td rowSpan={methodFreqCoverage.spans.get(idx) || 1}>{item.method}</td>
+)}
+{!methodFreqCoverage.covered.has(idx) && (
+  <td rowSpan={methodFreqCoverage.spans.get(idx) || 1}>{item.frequency}</td>
+)}
+```
+
+**병합 결과 예시** (시더 데이터 기준):
+- category `겉모양` → 5행 병합
+- category `치수(오픈사이즈)` → 4행 병합
+- method+frequency `육안검사|전수검사` → 7행 (겉모양5 + 모터1 + 재질1)
+- method+frequency `체크검사|전수검사` → 4행 (치수 4개)
+- method+frequency `공인시험기관|1회/5년` → 9행 (내화3 + 차연1 + 개폐5)
+- `작동테스트`는 method/frequency 빈값 → 병합 대상 아님
+
+#### 5.1.4 rendered_html 캡처 패턴
+
+> **캡처 원칙** (document-snapshot-architecture-plan.md 참조):
+> - **Active Capture**: 입력 화면에서 저장할 때 캡처. readOnly에서는 캡처하지 않음.
+> - **Lazy Snapshot**: 조회 시 rendered_html 없으면 자동 캡처/저장 (점진적 전환).
+> FQC 성적서는 Active Capture (편집 모드 저장 시), 요청서는 Lazy Snapshot (readonly 자동 캡처) 적용.
+
+**패턴 1: innerHTML 직접 캡처** (참조: 중간검사 `InspectionReportModal.tsx` 라인 341-366)
+
+```typescript
+// 1. ref 정의
+const contentWrapperRef = useRef<HTMLDivElement>(null);
+
+// 2. 저장 시 캡처
+const handleSave = async () => {
+  const renderedHtml = contentWrapperRef.current?.innerHTML || undefined;
+  const result = await saveInspectionDocument({
+    ...data,
+    rendered_html: renderedHtml,
+  });
+};
+
+// 3. JSX에서 ref 연결
+<div ref={contentWrapperRef}>
+  <TemplateInspectionContent ... />
+</div>
+```
+
+**패턴 2: 오프스크린 렌더링** (참조: 수입검사 `ImportInspectionInputModal.tsx`)
+
+```typescript
+import { captureRenderedHtml } from '@/lib/utils/capture-rendered-html';
+
+// 문서 컴포넌트를 오프스크린으로 렌더링 → HTML 캡처
+const html = await captureRenderedHtml(DocumentComponent, documentProps);
+```
+
+- 유틸리티 위치: `react/src/lib/utils/capture-rendered-html.tsx` (flushSync + createRoot)
+- 문서가 화면에 렌더링되지 않는 상황에서 캡처할 때 사용 (Lazy Snapshot에 활용 가능)
+
+**FQC 성적서 적용 (Phase 1.3)**: 패턴 1 사용. `InspectionReportModal.tsx`의 FQC 모드 저장 로직에 동일 패턴 추가.
+현재 `fqcActions.ts`의 `saveFqcDocument()`는 `POST /v1/documents/upsert` 사용 → body에 `rendered_html` 추가.
+
+#### 5.1.5 FqcDocumentContent.tsx 현재 구조 (보완 대상)
+
+**현재 상태** (라인 311-375):
+- 4컬럼 테이블: NO(30px) | 검사항목 | 검사기준 | 판정(28px)
+- `InspectionRow` 컴포넌트 (라인 399-454): 4개 셀 렌더링
+- 판정: readonly면 텍스트 표시, 편집모드면 양호/불량 토글 버튼
+- 종합판정: 라인 117-128 자동 계산 (하나라도 부적합이면 불합격)
+
+**보완 방향**:
+1. template columns 2개(측정값+판정)로 재정의 + 8컬럼 시각 레이아웃 (섹션 5.1.1)
+2. `InspectionRow` → 8셀 렌더링 + rowSpan 복합키 병합 (섹션 5.1.3)
+3. measurement_type에 따른 셀 분기 (섹션 5.1.8):
+   - `checkbox`: 양호/불량 토글 (기존)
+   - `numeric`: 숫자 입력 필드 (신규)
+   - `none`: 측정값/판정 모두 비활성 + 종합판정에서 제외 (작동테스트)
+4. method/frequency: section_item 필드에서 직접 렌더링 (readonly)
+5. [선행] fqcActions.ts 타입에 category/method/frequency/measurement_type 추가 (섹션 5.1.7)
+
+#### 5.1.6 saveFqcDocument API 현재 구조
+
+**`fqcActions.ts`** (라인 429-461):
+```typescript
+// 현재: rendered_html 미포함
+const body: Record<string, unknown> = {
+  template_id: templateId,
+  data: data,
+};
+if (documentId) body.document_id = documentId;
+if (itemId) body.item_id = itemId;
+if (title) body.title = title;
+// → rendered_html 추가 필요
+
+const res = await fetchAPI('/api/v1/documents/upsert', { method: 'POST', body });
+```
+
+**data 구조** (EAV):
+```typescript
+data: Array<{
+  section_id?: number | null;
+  column_id?: number | null;
+  row_index: number;
+  field_key: string;      // 예: 'judgment', 'measured_value'
+  field_value: string | null;
+}>
+```
+
+#### 5.1.7 Frontend 타입 갭 수정 (Phase 1.2 선행 작업)
+
+> **문제**: API는 section_items에 category, method, frequency, measurement_type 필드를 반환하지만,
+> React의 `TemplateItemApi`와 `FqcTemplateItem` 타입에 이 필드들이 누락되어 있음.
+
+**현재 타입** (`fqcActions.ts:20-29`):
+```typescript
+interface TemplateItemApi {
+  id: number;
+  section_id: number;
+  item: string;
+  standard: string;
+  sort_order: number;
+  // ❌ category, method, frequency, measurement_type 누락
+}
+```
+
+**수정 필요**:
+```typescript
+interface TemplateItemApi {
+  id: number;
+  section_id: number;
+  item: string;
+  standard: string;
+  sort_order: number;
+  category: string | null;           // 추가
+  method: string | null;             // 추가
+  frequency: string | null;          // 추가
+  measurement_type: string | null;   // 추가 (checkbox/numeric/none)
+}
+```
+
+**`FqcTemplateItem`** (`fqcActions.ts:152-161`)도 동일하게 필드 추가.
+
+**`transformTemplate()`** (`fqcActions.ts:254-300`)에서 매핑 추가:
+```typescript
+// items 변환 시 category, method, frequency, measurement_type 포함
+items: section.items.map((item: TemplateItemApi) => ({
+  ...existingMapping,
+  category: item.category || '',
+  method: item.method || '',
+  frequency: item.frequency || '',
+  measurement_type: item.measurement_type || 'checkbox',
+}))
+```
+
+#### 5.1.8 measurement_type='none' 처리 (작동테스트)
+
+> **문제**: 작동테스트 항목은 `measurement_type='none'`인데, 현재 코드는 checkbox/numeric만 처리.
+> none 항목에 판정 UI를 표시하면 종합판정에 영향을 주게 됨.
+
+**처리 방안**:
+1. **측정값 셀**: 빈 셀 또는 '-' 표시 (입력 불가)
+2. **판정 셀**: 비활성화 (hideJudgment)
+3. **종합판정 계산에서 제외**: `measurement_type='none'` 항목은 적합/부적합 집계에서 제외
+
+**React 구현** (`FqcDocumentContent.tsx`의 `InspectionRow`):
+```typescript
+// measurement_type에 따른 렌더링 분기
+if (item.measurement_type === 'none') {
+  // 측정값: 빈 셀
+  // 판정: 빈 셀 (토글 버튼 미표시)
+  return <><td>-</td><td>-</td></>;
+}
+
+// 종합판정 계산 (라인 117-128 수정)
+const judgmentItems = records.filter(r =>
+  r.field_key === 'judgment' &&
+  // none 타입 항목 제외
+  sectionItems.find(item => item.sort_order === r.row_index)?.measurement_type !== 'none'
+);
+```
+
+#### 5.1.9 Template ID 안정성 대책
+
+> **문제**: 시더가 `cleanupExisting()`으로 삭제 후 재생성하면 auto_increment로 ID가 변경됨.
+> `FQC_TEMPLATE_ID = 65` 하드코딩이 깨질 수 있음.
+
+**대책 (2단계)**:
+
+**1단계 (즉시)** — 시더 개선:
+- `cleanupExisting()` 대신 `updateOrCreate()` 패턴 사용
+- template ID를 명시적으로 지정하여 재실행 시에도 동일 ID 유지
+```php
+$template = DocumentTemplate::updateOrCreate(
+    ['id' => 65, 'tenant_id' => $this->tenantId],
+    ['name' => '제품검사 성적서', ...]
+);
+// 하위 데이터도 sync 방식으로 처리
+```
+
+**2단계 (권장, 후순위)** — category 기반 조회:
+- `FQC_TEMPLATE_ID = 65` 대신 API에서 category='품질/제품검사' + name='제품검사 성적서'로 조회
+- 환경에 따라 ID가 달라도 동작하도록 유연성 확보
+- **이번 작업에서는 1단계만 적용**, 2단계는 추후 리팩토링 시 적용
+
+---
+
+### 5.2 제품검사 요청서 양식 설계 (Phase 2.1)
+
+#### 5.2.1 양식 구조
+
+```
+DocumentTemplate (제품검사 요청서)
+├── name: '제품검사 요청서'
+├── category: '품질/제품검사'
+├── title: '제 품 검 사 요 청 서'
+│
+├── approval_lines: [
+│   { name: '작성', dept: '품질', role: '담당자', sort_order: 1 },
+│   { name: '승인', dept: '경영', role: '대표', sort_order: 2 },
+│ ]
+│
+├── basic_fields: [
+│   { label: '수주처', field_key: 'client', field_type: 'text' },
+│   { label: '업체명', field_key: 'company_name', field_type: 'text' },
+│   { label: '담당자', field_key: 'manager', field_type: 'text' },
+│   { label: '수주번호', field_key: 'order_number', field_type: 'text' },
+│   { label: '담당자 연락처', field_key: 'manager_contact', field_type: 'text' },
+│   { label: '현장명', field_key: 'site_name', field_type: 'text' },
+│   { label: '납품일', field_key: 'delivery_date', field_type: 'date' },
+│   { label: '현장 주소', field_key: 'site_address', field_type: 'text' },
+│   { label: '총 개소', field_key: 'total_locations', field_type: 'number' },
+│   { label: '접수일', field_key: 'receipt_date', field_type: 'date' },
+│   { label: '검사방문요청일', field_key: 'inspection_request_date', field_type: 'date' },
+│ ]
+│
+├── sections: [
+│   { title: '건축공사장 정보', items: [
+│       { item: '현장명', measurement_type: 'text_input' },
+│       { item: '대지위치', measurement_type: 'text_input' },
+│       { item: '지번', measurement_type: 'text_input' },
+│   ]},
+│   { title: '자재유통업자 정보', items: [
+│       { item: '회사명', measurement_type: 'text_input' },
+│       { item: '주소', measurement_type: 'text_input' },
+│       { item: '대표자', measurement_type: 'text_input' },
+│       { item: '전화번호', measurement_type: 'text_input' },
+│   ]},
+│   { title: '공사시공자 정보', items: [...] },  // 회사명, 주소, 성명, 전화
+│   { title: '공사감리자 정보', items: [...] },   // 사무소명, 주소, 성명, 전화
+│   { title: '검사대상 사전 고지 정보', items: [] }, // 동적 테이블 (locations)
+│ ]
+│
+└── columns: [  // 사전 고지 정보 테이블용
+    { label: 'No.', column_type: 'text', width: '40px' },
+    { label: '층수', column_type: 'text', width: '60px' },
+    { label: '부호', column_type: 'text', width: '60px' },
+    { label: '발주 가로', column_type: 'text', width: '70px', group_name: '오픈사이즈(발주규격)' },
+    { label: '발주 세로', column_type: 'text', width: '70px', group_name: '오픈사이즈(발주규격)' },
+    { label: '시공 가로', column_type: 'text', width: '70px', group_name: '오픈사이즈(시공후규격)' },
+    { label: '시공 세로', column_type: 'text', width: '70px', group_name: '오픈사이즈(시공후규격)' },
+    { label: '변경사유', column_type: 'text' },
+  ]
+```
+
+#### 5.2.2 데이터 매핑 (quality_document → 요청서 필드)
+
+| 요청서 필드 | 데이터 소스 | 경로 |
+|------------|-----------|------|
+| 수주처 | quality_document → order → client | `qualityDocument.orders[0].order.client.name` |
+| 업체명 | tenant | `tenant.name` |
+| 담당자 | quality_document.created_by | user name |
+| 수주번호 | quality_document → order | `qualityDocument.orders[0].order.order_number` |
+| 현장명 | quality_document → order | `qualityDocument.orders[0].order.site_name` |
+| 납품일 | quality_document → order | `qualityDocument.orders[0].order.delivery_date` |
+| 총 개소 | quality_document_locations count | `qualityDocument.orders.flatMap(o => o.locations).length` |
+| 사전고지 테이블 | quality_document_locations | location별 floor/symbol/width/height/post_width/post_height/change_reason |
+
+#### 5.2.3 특이사항
+- 요청서는 검사 입력이 아닌 **정보 표시 문서** (readonly)
+- 개소(location) 데이터는 `quality_document_locations` 테이블에서 가져옴
+- "검사 요청 시 필독" 고정 텍스트는 section description으로 처리
+- quality_document 생성 시 요청서 document 자동 생성 (bulkCreate 패턴 참조)
+
+---
+
+## 6. 확정 사항
+
+| # | 항목 | 결정 내용 | 영향 범위 | 상태 |
+|---|------|----------|----------|------|
+| 1 | 성적서 양식 보완 방안 | **방안 C 확정** — 하드코딩 데이터를 template items로 완전 이관. SectionItem에 method/frequency/measurement_type 이미 존재 | mng, react | ✅ 확정 |
+| 2 | 요청서 template 생성 방법 | **시더 확정** — ProductInspectionRequestTemplateSeeder 작성 (mng/database/seeders/). 재현성 + 버전 관리 | mng | ✅ 확정 |
+| 3 | 요청서 문서 생성 시점 | **자동 생성 확정** — quality_document 생성 시 자동. 기존 성적서 bulk create 패턴과 동일 | api | ✅ 확정 |
+| 4 | 요청서 rendered_html 캡처 방식 | **Lazy Snapshot 확정** — 요청서는 readonly 문서이므로 최초 조회 시 rendered_html 없으면 자동 캡처/저장. `captureRenderedHtml` 유틸리티 또는 `contentWrapperRef.innerHTML` 활용 | react | ✅ 확정 |
+
+---
+
+## 6.1 에이전트 조사 결과 (2026-03-06)
+
+### Template ID 65 현황
+- Seeder: MNG에만 존재 (`mng/database/seeders/ProductInspectionTemplateSeeder.php`, tenant_id=287 하드코딩)
+- 정규 관리 안됨 (migration/seeder로 재현 불가)
+- React: `FQC_TEMPLATE_ID = 65` 하드코딩 (`fqcActions.ts:348`)
+
+### rendered_html 스냅샷 아키텍처 (~95% 완성)
+| 계층 | 상태 | 비고 |
+|------|------|------|
+| DB (documents.rendered_html) | ✅ | LONGTEXT, migration 완료 |
+| API (DocumentService create/update) | ✅ | rendered_html 조건부 저장 |
+| React (InspectionReportModal) | ✅ | contentWrapperRef.innerHTML 캡처 |
+| MNG (show/print.blade.php) | ✅ | rendered_html 우선 출력 + fallback |
+| FormRequest 검증 | ✅ | StoreRequest/UpdateRequest/UpsertRequest 모두 nullable string 검증 완료 |
+
+### mng template 구조 핵심
+- `DocumentTemplateSectionItem` 필드: category, item, standard, tolerance, standard_criteria, method, measurement_type, frequency_n, frequency_c, frequency, regulation, field_values(JSON)
+- **8컬럼 구조를 추가 스키마 변경 없이 지원 가능** — 방안 C 근거
+- 저장 방식: Legacy EAV (approval_lines, basic_fields, sections+items, columns, section_fields, links)
+- 저장 API: `POST /api/admin/document-templates` → `saveRelations()` 트랜잭션
+
+### QualityDocumentLocation 모델
+- 테이블: `quality_document_locations`
+- 필드: `quality_document_id`, `quality_document_order_id`, `order_item_id`, `post_width`, `post_height`, `change_reason`, `inspection_data`(JSON), `document_id`, `inspection_status`
+- 관계: qualityDocument, qualityDocumentOrder, orderItem, document
+- 상태: pending / completed
+
+---
+
+## 7. 변경 이력
+
+| 날짜 | 항목 | 변경 내용 | 파일 | 승인 |
+|------|------|----------|------|------|
+| 2026-03-06 | - | 문서 초안 작성 | - | - |
+| 2026-03-06 | 컨펌 3건 | 방안 C 확정, 시더 확정, 자동 생성 확정 | - | ✅ 사용자 승인 |
+| 2026-03-06 | 에이전트 조사 | template ID 65 현황, rendered_html 현황, mng 구조 분석 반영 | - | - |
+| 2026-03-06 | 자기완결성 보완 | 시더 데이터, rowSpan 로직, rendered_html 캡처 패턴, API 구조, 타입 정의 추가 | - | - |
+| 2026-03-06 | 방법론 수정 6건 | ①컬럼 아키텍처 재설계(template 2개+시각 8컬럼) ②프론트 타입 갭 보완 ③rowSpan 복합키 알고리즘 ④Template ID 안정성 대책 ⑤measurement_type=none 처리 ⑥시더 위치 명확화(mng) | - | - |
+| 2026-03-06 | 스냅샷 아키텍처 정합성 검토 반영 | ①FormRequest 검증 ✅ 확인 ②Phase 2.4 Lazy Snapshot 전략 확정 ③참고 파일 추가(capture-rendered-html.tsx, UpsertRequest) ④캡처 원칙(Active/Lazy) 명시 ⑤오프스크린 렌더링 참조 추가 | 5.1.4, 6.1, 9 | - |
+
+---
+
+## 8. 참고 문서
+
+- **문서관리 시스템 마스터**: `docs/dev/dev_plans/document-system-master.md`
+- **스냅샷 아키텍처**: `docs/dev/dev_plans/document-snapshot-architecture-plan.md`
+- **FQC Phase 5.2 아카이브**: `docs/dev/dev_plans/archive/document-system-product-inspection.md`
+- **문서관리 기능 스펙**: `docs/features/documents/README.md`
+- **DB 스키마**: `docs/system/database/documents.md`
+- **품질 체크리스트**: `docs/dev/standards/quality-checklist.md`
+
+---
+
+## 9. 참고 파일 경로
+
+### React (수정 대상)
+| 파일 | 역할 | 핵심 라인 |
+|------|------|----------|
+| `react/src/components/quality/InspectionManagement/documents/FqcDocumentContent.tsx` | FQC 양식 기반 동적 렌더링 (보완 대상) | 311-375: 4컬럼 테이블, 399-454: InspectionRow |
+| `react/src/components/quality/InspectionManagement/documents/InspectionReportDocument.tsx` | 하드코딩 성적서 (참조/fallback) | 42-57: buildCoverageMap(), 198-376: 8컬럼 테이블 |
+| `react/src/components/quality/InspectionManagement/documents/InspectionReportModal.tsx` | 성적서 모달 (듀얼 모드) | 61: useFqcMode, 106-116: FQC 문서 로드, 233-262: fallback |
+| `react/src/components/quality/InspectionManagement/documents/InspectionRequestDocument.tsx` | 하드코딩 요청서 (참조/fallback) | 47-62: 결재, 66-103: 기본정보, 211-255: 사전고지 테이블 |
+| `react/src/components/quality/InspectionManagement/documents/InspectionRequestModal.tsx` | 요청서 모달 | 26-37: DocumentViewer 래퍼 |
+| `react/src/components/quality/InspectionManagement/fqcActions.ts` | FQC 서버 액션 | 348: FQC_TEMPLATE_ID=65, 429-461: saveFqcDocument() |
+| `react/src/components/quality/InspectionManagement/InspectionDetail.tsx` | 상세 페이지 (모달 연동) | 1230-1275: 모달 통합 |
+| `react/src/components/quality/InspectionManagement/mockData.ts` | 데이터 변환 함수 | 398-423: buildRequestDocumentData(), 426-458: mockReportInspectionItems |
+| `react/src/components/quality/InspectionManagement/types.ts` | 타입 정의 | 224-247: InspectionRequestDocument, 250-266: ReportInspectionItem, 269-285: InspectionReportDocument |
+| `react/src/components/quality/InspectionManagement/actions.ts` | 서버 액션 (CRUD) | |
+
+### React (참조 - 기존 동적 렌더링 패턴)
+| 파일 | 역할 | 핵심 라인 |
+|------|------|----------|
+| `react/src/components/production/WorkOrders/documents/TemplateInspectionContent.tsx` | 중간검사 동적 렌더링 (참조 모델) | 917-999: 컬럼타입별 렌더링, 1105-1183: renderComplexCells() |
+| `react/src/components/production/WorkOrders/documents/InspectionReportModal.tsx` | 중간검사 모달 (rendered_html 캡처 패턴) | 167: contentWrapperRef, 341-366: handleSave+innerHTML |
+| `react/src/lib/utils/capture-rendered-html.tsx` | 오프스크린 렌더링 유틸리티 (flushSync+createRoot) | Phase 2.4 Lazy Snapshot에서 활용 가능 |
+| `react/src/components/material/ReceivingManagement/ImportInspectionInputModal.tsx` | 수입검사 오프스크린 캡처 참조 | captureRenderedHtml 사용 예시 |
+
+### API (수정 대상)
+| 파일 | 역할 | 핵심 라인 |
+|------|------|----------|
+| `api/app/Services/DocumentService.php` | 문서 저장/조회 | 125: create(rendered_html), 180: update(rendered_html) |
+| `api/app/Services/QualityDocumentService.php` | 품질관리 문서 서비스 | 176-209: store(), 749-799: requestDocument(), 804-868: resultDocument() |
+| `api/app/Models/Documents/Document.php` | 문서 모델 | 76: $fillable에 rendered_html |
+| `api/app/Models/Qualitys/QualityDocumentLocation.php` | 개소 모델 | fillable: post_width, post_height, change_reason, inspection_data |
+| `api/app/Http/Requests/Document/UpsertRequest.php` | documents/upsert 검증 | rendered_html nullable string 검증 완료 |
+
+### MNG (확인/수정 대상)
+| 파일 | 역할 |
+|------|------|
+| `mng/app/Http/Controllers/DocumentTemplateController.php` | 양식 CRUD |
+| `mng/resources/views/document-templates/edit.blade.php` | 양식 편집 |
+| `mng/resources/views/documents/show.blade.php` | 문서 보기 (rendered_html 우선 출력, 29-32행) |
+| `mng/resources/views/documents/print.blade.php` | 문서 인쇄 (28-32행) |
+| `mng/database/seeders/ProductInspectionTemplateSeeder.php` | template ID 65 시더 (49-182: 항목 데이터) |
+
+---
+
+## 10. 미커밋 변경사항 (이전 세션, 2026-03-06)
+
+**api/** — order_ids 영속성, location count 수정, location data 저장:
+- `app/Http/Requests/Quality/QualityDocumentStoreRequest.php` — 수정
+- `app/Http/Requests/Quality/QualityDocumentUpdateRequest.php` — 수정
+- `app/Services/QualityDocumentService.php` — 수정
+- `app/Models/Qualitys/QualityDocumentLocation.php` — 수정
+- `database/migrations/2026_03_06_094425_add_inspection_data_to_quality_document_locations.php` — 신규
+
+**react/** — `src/components/quality/InspectionManagement/actions.ts` — 수정
+
+> 이 작업 시작 전에 먼저 커밋 필요
+
+---
+
+## 11. 세션 및 메모리 관리 정책 (Serena Optimized)
+
+### 11.1 세션 시작 시 (Load Strategy)
+```javascript
+read_memory("fqc-doc-state")           // 1. 상태 파악
+read_memory("fqc-doc-snapshot")        // 2. 사고 흐름 복구
+read_memory("fqc-doc-active-symbols")  // 3. 작업 대상 파악
+```
+
+### 11.2 작업 중 관리 (Context Defense)
+| 컨텍스트 잔량 | Action | 내용 |
+|--------------|--------|------|
+| **30% 이하** | Snapshot | `write_memory("fqc-doc-snapshot", "코드변경+논의요약")` |
+| **20% 이하** | Context Purge | `write_memory("fqc-doc-active-symbols", "주요 수정 파일/함수")` |
+| **10% 이하** | Stop & Save | 최종 상태 저장 후 세션 교체 권고 |
+
+### 11.3 Serena 메모리 구조
+- `fqc-doc-state`: { phase, progress, next_step, last_decision } (JSON)
+- `fqc-doc-snapshot`: 현재까지의 논의 및 코드 변경점 요약 (Text)
+- `fqc-doc-rules`: 해당 작업에서 결정된 불변의 규칙들 (Text)
+- `fqc-doc-active-symbols`: 현재 수정 중인 파일/심볼 리스트 (List)
+
+---
+
+## 12. 검증 결과
+
+> 작업 완료 후 이 섹션에 검증 결과 추가
+
+### 12.1 성공 기준
+
+| # | 기준 | 달성 | 비고 |
+|---|------|:----:|------|
+| 1 | mng에서 성적서 양식 편집/미리보기 정상 | ✅ | 시더 실행 확인 |
+| 2 | mng에서 요청서 양식 편집/미리보기 정상 | ✅ | 시더 실행 확인 |
+| 3 | React에서 성적서 양식 기반 동적 렌더링 (8컬럼+rowSpan) | ✅ | 브라우저 테스트 통과 |
+| 4 | React에서 요청서 양식 기반 동적 렌더링 | ✅ | requestDocumentId 없으면 legacy fallback |
+| 5 | 저장 시 rendered_html 스냅샷 저장됨 | ✅ | Active Capture 코드 구현 완료 (검사 저장 시 동작) |
+| 6 | mng 문서 보기에서 스냅샷 정상 출력 | ✅ | show.blade.php 코드 검증 |
+| 7 | 기존 하드코딩 fallback 정상 동작 | ✅ | 요청서 legacy fallback 브라우저 테스트 통과 |
+| 8 | 기존 FQC 데이터 호환성 유지 | ✅ | 기존 EAV basic_fields 정상 표시 확인 |
+
+### 12.2 테스트 시나리오
+
+| 시나리오 | 예상 결과 | 실제 결과 | 상태 |
+|---------|----------|----------|------|
+| `/quality/inspections/1?mode=view` → 검사제품요청서 클릭 | 양식 기반 요청서 표시 | legacy fallback 정상 (EAV 문서 미생성 상태) | ✅ |
+| `/quality/inspections/1?mode=view` → 제품검사하기 클릭 | 양식 기반 성적서 표시 (편집 모드, 8컬럼) | FQC 8컬럼 + rowSpan 정상 | ✅ |
+| 성적서 검사 완료 후 저장 | document_data + rendered_html 저장 | 코드 구현 완료 (실 저장은 검사 진행 시) | ✅ |
+| `mng.sam.kr/documents/{id}` | rendered_html 스냅샷 출력 | show.blade.php 코드 검증 | ✅ |
+| template ID 65 없는 환경 | 하드코딩 fallback 동작 | templateLoadFailed 시 legacy 렌더링 | ✅ |
+| 치수 검사항목에 측정값 입력 | numeric input → document_data에 저장 | UI 표시 확인 (저장은 검사 진행 시) | ✅ |
+
+---
+
+## 13. 자기완결성 점검 결과
+
+### 13.1 체크리스트 검증
+
+| # | 검증 항목 | 상태 | 비고 |
+|---|----------|:----:|------|
+| 1 | 작업 목적이 명확한가? | ✅ | 섹션 1.1 |
+| 2 | 성공 기준이 정의되어 있는가? | ✅ | 섹션 12.1 |
+| 3 | 작업 범위가 구체적인가? | ✅ | 섹션 3 |
+| 4 | 의존성이 명시되어 있는가? | ✅ | Phase 순서, 미커밋 사항(섹션 10) |
+| 5 | 참고 파일 경로가 정확한가? | ✅ | 섹션 9 (라인 번호 포함) |
+| 6 | 단계별 절차가 실행 가능한가? | ✅ | 섹션 4+5 (시더 데이터, 코드 패턴 포함) |
+| 7 | 검증 방법이 명시되어 있는가? | ✅ | 섹션 12.2 |
+| 8 | 모호한 표현이 없는가? | ✅ | 방안 C 확정, 시더 확정, 자동 생성 확정 |
+
+### 13.2 새 세션 시뮬레이션 테스트
+
+| 질문 | 답변 가능 | 참조 섹션 |
+|------|:--------:|----------|
+| Q1. 이 작업의 목적은 무엇인가? | ✅ | 1.1 배경 |
+| Q2. 어디서부터 시작해야 하는가? | ✅ | 4.1 단계별 절차 + 10. 미커밋 사항(먼저 커밋) |
+| Q3. 어떤 파일을 수정해야 하는가? | ✅ | 9. 참고 파일 경로 (라인 번호 포함) |
+| Q4. 시더에 어떤 데이터를 넣어야 하는가? | ✅ | 5.1.2 검사항목 데이터 (PHP 배열) |
+| Q5. React rowSpan은 어떻게 구현하는가? | ✅ | 5.1.3 자동 병합 로직 (TypeScript 코드) |
+| Q6. rendered_html은 어떻게 캡처하는가? | ✅ | 5.1.4 캡처 패턴 (참조 코드) |
+| Q7. 요청서 필드는 어디서 가져오는가? | ✅ | 5.2.2 데이터 매핑 테이블 |
+| Q8. 작업 완료 확인 방법은? | ✅ | 12. 검증 결과 |
+| Q9. 막혔을 때 참고 문서는? | ✅ | 8. 참고 문서 |
+
+---
+
+*이 문서는 /plan 스킬로 생성되었습니다.*

dev/dev_plans/mng-bending-document-matching-plan.md

@@ -0,0 +1,245 @@
+# MNG 절곡 문서 React 매칭 계획
+
+> **작성일**: 2026-03-05
+> **목적**: MNG 절곡 문서(중간검사성적서 #36, 작업일지 #39)의 상세보기를 React와 동일하게 수정
+> **상태**: 🔄 진행중
+> **영향 범위**: mng만 (React/API 변경 없음)
+
+---
+
+## 현재 진행 상태
+
+| 항목 | 내용 |
+|------|------|
+| **마지막 완료 작업** | Task 2.2: 절곡 작업일지 전용 렌더링 블록 추가 |
+| **다음 작업** | 브라우저 검증 (사용자 확인 필요) |
+| **진행률** | 5/6 (83%) |
+| **마지막 업데이트** | 2026-03-05 |
+
+---
+
+## 1. 개요
+
+### 1.1 배경
+
+MNG(`mng.sam.kr/documents/36`, `/documents/39`)에서 절곡 문서의 상세보기가 React(`dev.sam.kr/production/worker-screen` > 절곡공정)와 다르다.
+
+- **MNG**: DB 템플릿(`document_templates`, `document_template_columns`)을 동적으로 읽어 범용 렌더링
+- **React**: 전용 하드코딩 컴포넌트(`BendingInspectionContent.tsx`, `BendingWorkLogContent.tsx`)로 렌더링
+
+React가 더 상세하고 정확하므로, MNG를 React에 맞춰 수정한다.
+
+### 1.2 핵심 원칙
+
+- MNG only 수정 (React/API 변경 없음)
+- DB 템플릿 컬럼 수정 + show.blade.php 전용 렌더링 블록 추가
+- 기존 범용 렌더링 로직은 유지 (다른 문서에 영향 없도록)
+
+### 1.3 변경 승인 정책
+
+| 분류 | 예시 | 승인 |
+|------|------|------|
+| 즉시 가능 | blade 템플릿 수정, DB 시더/컬럼 업데이트 | 불필요 |
+| 컨펌 필요 | DocumentController 로직 변경, 새 쿼리 추가 | **필수** |
+| 금지 | 테이블 구조 변경, API 엔드포인트 변경 | 별도 협의 |
+
+---
+
+## 2. 차이점 분석
+
+### 2.1 중간검사성적서 (#36) - 중간검사 DATA 테이블
+
+**React 컬럼 구조** (`BendingInspectionContent.tsx`):
+
+| 컬럼 | 타입 | 비고 |
+|------|------|------|
+| 분류 | text | KWE01 등 제품코드 |
+| 제품명 | text | 가이드레일, 케이스 등 |
+| 타입 | text | 벽면형, 측면형 등 |
+| 겉모양/절곡상태 | check | 양호/불량 체크 |
+| 길이 - 도면치수 | text | 설계값 |
+| 길이 - 측정값 | input | 입력값 |
+| 너비 - 도면치수 | text | 설계값 |
+| 너비 - 측정값 | input | 입력값 |
+| 간격 - 포인트 | text | 1~5 등 |
+| 간격 - 도면치수 | text | 설계값 |
+| 간격 - 측정값 | input | 입력값 |
+| 판정 | auto | 적/부 자동판정 |
+
+**핵심 차이**:
+- React는 **7개 제품** x **다중 gapPoints**(간격 측정점)로 rowSpan 사용
+- MNG 현재 DB에는 "간격" 컬럼, "판정" 컬럼 없음
+- MNG "분류/제품명"이 하나로 합쳐져 있을 수 있음
+
+**React 제품 목록** (INITIAL_PRODUCTS):
+1. 가이드레일 벽면형 (gapPoints: 5개)
+2. 가이드레일 측면형 (gapPoints: 5개)
+3. 케이스 (gapPoints: 2개)
+4. 하단마감재 (gapPoints: 2개)
+5. 하단L-BAR (gapPoints: 1개)
+6. 연기차단재 W50 (gapPoints: 1개)
+7. 연기차단재 W80 (gapPoints: 2개)
+
+### 2.2 작업일지 (#39) - 절곡 전용 구조
+
+**React 구조** (`BendingWorkLogContent.tsx`):
+
+```
+헤더: "작업일지 (절곡)" + 문서번호/작성일자 + 결재란
+신청업체/신청내용 테이블 (수주일, 현장명, 수주처, 작업일자, 담당자, LOT NO, 연락처, 생산담당자, 출고예정일)
+제품 정보 테이블 (제품명, 재질, 마감, 유형)
+4개 카테고리 섹션:
+  1. GuideRailSection (가이드레일 벽면형/측면형)
+  2. BottomBarSection (하단마감재)
+  3. ShutterBoxSection (셔터박스)
+  4. SmokeBarrierSection (연기차단재 W50/W80)
+생산량 합계 [kg] (SUS/EGI)
+비고
+```
+
+**핵심 차이**:
+- MNG 현재: 범용 work_order_items 플랫 테이블 (line 137, 섹션 없는 문서)
+- React: 절곡 전용 4개 카테고리 섹션 + 제품정보 + 생산량합계
+- React는 `bendingInfo` 데이터(work_order.options.bending_info)를 사용
+- MNG Controller에서 bending_info를 아직 view에 전달하지 않음
+
+---
+
+## 3. 작업 범위
+
+### Phase 1: 중간검사성적서 (#36)
+
+| # | 작업 항목 | 상태 | 비고 |
+|---|----------|:----:|------|
+| 1.1 | 현재 DB 템플릿 컬럼 조회 (tinker) | ✅ | template_id=60, 7컬럼 (간격/판정 포함) |
+| 1.2 | show.blade.php 절곡 검사 전용 렌더링 블록 추가 | ✅ | partials/bending-inspection-data.blade.php |
+| 1.3 | 브라우저 검증 | ⏳ | mng.sam.kr/documents/36 |
+
+### Phase 2: 작업일지 (#39)
+
+| # | 작업 항목 | 상태 | 비고 |
+|---|----------|:----:|------|
+| 2.1 | DocumentController에 bending_info 전달 추가 | ✅ | work_order.options에서 추출 |
+| 2.2 | show.blade.php 절곡 작업일지 전용 렌더링 블록 추가 | ✅ | partials/bending-worklog.blade.php |
+| 2.3 | 브라우저 검증 | ⏳ | mng.sam.kr/documents/39 |
+
+---
+
+## 4. 상세 작업 내용
+
+### 4.1 Task 1.2: show.blade.php 절곡 검사 전용 블록
+
+**위치**: `show.blade.php` 섹션 렌더링 영역 (line ~400)
+**조건**: template category가 '절곡' 또는 template name에 '절곡' 포함
+
+**렌더링 구조**:
+```html
+<table>
+  <thead>
+    <tr>
+      <th rowSpan=2>분류</th>
+      <th rowSpan=2>제품명</th>
+      <th rowSpan=2>타입</th>
+      <th rowSpan=2>겉모양/절곡상태</th>
+      <th colSpan=2>길이</th>
+      <th colSpan=2>너비</th>
+      <th colSpan=3>간격</th>
+      <th rowSpan=2>판정</th>
+    </tr>
+    <tr>
+      <th>도면치수</th><th>측정값</th>
+      <th>도면치수</th><th>측정값</th>
+      <th>포인트</th><th>도면치수</th><th>측정값</th>
+    </tr>
+  </thead>
+  <tbody>
+    <!-- 각 제품별 gapPoints 수만큼 행 (rowSpan 사용) -->
+  </tbody>
+</table>
+```
+
+**데이터 소스**: `document_data` EAV + INITIAL_PRODUCTS 정적 구조
+- section_id, column_id, row_index, field_key로 조회
+- 간격 데이터: field_key `gap_point_{n}`, `gap_design_{n}`, `gap_measured_{n}`
+
+### 4.2 Task 2.1: Controller bending_info 전달
+
+**파일**: `mng/app/Http/Controllers/DocumentController.php` show()
+**추가 로직**:
+```php
+// 절곡 작업일지용: bending_info 추출
+$bendingInfo = null;
+if ($workOrder) {
+    $woOptions = json_decode($workOrder->options, true) ?? [];
+    $bendingInfo = $woOptions['bending_info'] ?? null;
+}
+```
+
+**view 전달**: `'bendingInfo' => $bendingInfo`
+
+### 4.3 Task 2.2: show.blade.php 절곡 작업일지 전용 블록
+
+**위치**: `show.blade.php` line ~137 (작업일지 전용 영역)
+**조건**: 절곡 공정인 경우 (template name에 '절곡' 포함 또는 공정 확인)
+
+**렌더링 구조**:
+1. 신청업체/신청내용 테이블
+2. 제품 정보 테이블 (제품명, 재질, 마감, 유형)
+3. 4개 카테고리 섹션 (가이드레일, 하단마감재, 셔터박스, 연기차단재)
+4. 생산량 합계 [kg] (SUS/EGI)
+5. 비고
+
+**PHP 유틸 함수 필요**:
+- `getMaterialMapping($productCode, $finishMaterial)` - React utils.ts 포팅
+- `calculateProductionSummary($bendingInfo, $mapping)` - React utils.ts 포팅
+
+---
+
+## 5. 참고 파일
+
+### React (타겟 - 읽기 전용)
+- `react/src/components/production/WorkOrders/documents/BendingInspectionContent.tsx` (547행)
+- `react/src/components/production/WorkOrders/documents/BendingWorkLogContent.tsx` (207행)
+- `react/src/components/production/WorkOrders/documents/bending/types.ts`
+- `react/src/components/production/WorkOrders/documents/bending/utils.ts`
+- `react/src/components/production/WorkOrders/documents/bending/GuideRailSection.tsx`
+- `react/src/components/production/WorkOrders/documents/bending/BottomBarSection.tsx`
+- `react/src/components/production/WorkOrders/documents/bending/ShutterBoxSection.tsx`
+- `react/src/components/production/WorkOrders/documents/bending/SmokeBarrierSection.tsx`
+- `react/src/components/production/WorkOrders/documents/bending/ProductionSummarySection.tsx`
+
+### MNG (수정 대상)
+- `mng/resources/views/documents/show.blade.php` (메인 렌더링)
+- `mng/app/Http/Controllers/DocumentController.php` (show 메서드)
+
+### DB 참고
+- `mng/database/seeders/MidInspectionTemplateSeeder.php` (절곡 검사 템플릿)
+- `mng/database/seeders/WorkLogTemplateSeeder.php` (절곡 작업일지 템플릿)
+
+### 문서
+- `docs/features/documents/README.md` - 문서관리 시스템
+- `docs/system/database/documents.md` - DB 스키마
+- `docs/dev/dev_plans/document-system-mid-inspection.md` - 중간검사 계획
+- `docs/dev/dev_plans/document-system-work-log.md` - 작업일지 계획
+
+---
+
+## 6. 변경 이력
+
+| 날짜 | 항목 | 변경 내용 | 파일 | 승인 |
+|------|------|----------|------|------|
+| 2026-03-05 | - | 계획 문서 작성 | - | - |
+
+---
+
+## 7. 검증 결과
+
+> 작업 완료 후 이 섹션에 검증 결과 추가
+
+### 7.1 성공 기준
+
+| 기준 | 달성 | 비고 |
+|------|------|------|
+| mng.sam.kr/documents/36 검사 DATA 테이블이 React와 동일 구조 | ⏳ | rowSpan, 간격, 판정 포함 |
+| mng.sam.kr/documents/39 작업일지가 React와 동일 구조 | ⏳ | 4개 카테고리, 생산량합계 포함 |
+| 기존 다른 문서 렌더링에 영향 없음 | ⏳ | 조건 분기로 절곡 전용만 |

dev/guides/LOCAL_SETUP_GUIDE.md

@@ -0,0 +1,794 @@
+# SAM 로컬 개발 환경 셋팅 가이드
+
+> 최종 업데이트: 2026-03-09
+
+---
+
+## 1. 사전 준비
+
+### 필수 소프트웨어
+
+| 소프트웨어 | 버전 | 용도 | 설치                                                            |
+|-----------|------|------|---------------------------------------------------------------|
+| **Docker Desktop** | 최신 | 컨테이너 실행 | [docker.com](https://www.docker.com/products/docker-desktop/) |
+| **Git** | 최신 | 버전 관리 | `brew install git`                                            |
+| **mkcert** | 최신 | 로컬 SSL 인증서 | `brew install mkcert`                                         |
+| **텍스트 에디터** | - | 코드 편집 | JetBrains IDE 권장                                              |
+
+> Docker Desktop이 설치되면 PHP, Node.js, MySQL 등은 **별도 설치 불필요** (Docker 컨테이너 내부에서 실행)
+
+### Git 서버 정보
+
+| 항목 | 값 |
+|------|-----|
+| Git 서버 | Gitea (자체 호스팅) |
+| 서버 주소 | `http://114.203.209.83:3000` |
+| 조직 | `SamProject` |
+
+> Gitea 계정이 필요합니다. 팀장에게 계정 생성을 요청하세요.
+
+---
+
+## 2. 저장소 클론
+
+### 디렉토리 구조
+
+```
+Works/@KD_SAM/SAM/          ← 루트 (원하는 경로에 생성)
+├── api/                     ← Laravel REST API
+├── mng/                     ← Laravel 관리자 패널
+├── react/                   ← Next.js 프론트엔드
+├── docs/                    ← 기술 문서
+├── hotfix/                  ← 테스트/QA 문서
+├── docker/                  ← Docker 설정 (api 저장소에 포함되지 않음)
+├── design/                  ← 디자인 시스템 (선택)
+└── planning/                ← 기획 문서 (선택)
+```
+
+### 클론 명령어
+
+```bash
+# 작업 디렉토리 생성
+mkdir -p ~/Works/@KD_SAM/SAM
+cd ~/Works/@KD_SAM/SAM
+
+# 5개 저장소 클론
+git clone http://114.203.209.83:3000/SamProject/sam-api.git api
+git clone http://114.203.209.83:3000/SamProject/sam-manage.git mng
+git clone http://114.203.209.83:3000/SamProject/sam-react-prod.git react
+git clone http://114.203.209.83:3000/SamProject/sam-docs.git docs
+git clone http://114.203.209.83:3000/SamProject/sam-hotfix.git hotfix
+```
+
+### 기본 브랜치 전환
+
+```bash
+# api, react는 develop 브랜치에서 작업
+cd api && git checkout develop && cd ..
+cd react && git checkout develop && cd ..
+```
+
+> **중요**: `main` 브랜치에서 직접 작업하지 않습니다. 항상 `develop`에서 작업합니다.
+
+---
+
+## 3. Docker 환경 구성
+
+### 3-1. Docker 설정 파일 확인
+
+`docker/` 디렉토리에 모든 Docker 설정이 포함되어 있습니다.
+
+```
+docker/
+├── docker-compose.yml       ← 메인 Compose 파일
+├── .env                     ← Compose 환경변수
+├── api/
+│   ├── Dockerfile           ← PHP 8.4 + Nginx
+│   ├── nginx.conf
+│   ├── supervisord.conf
+│   └── uploads.ini
+├── mng/
+│   ├── Dockerfile           ← PHP 8.4 + Nginx
+│   ├── nginx.conf
+│   ├── supervisord.conf
+│   └── uploads.ini
+├── react/
+│   └── Dockerfile           ← Node 20 + Chromium (PDF용)
+├── mysql/
+│   ├── init.sql             ← 초기 DB/유저 생성
+│   └── my.cnf               ← MySQL 설정
+├── nginx/
+│   ├── nginx.conf           ← 리버스 프록시 설정
+│   └── ssl/                 ← SSL 인증서
+└── 5130/
+    └── Dockerfile           ← 레거시 PHP 7.3
+```
+
+### 3-2. 서비스 구성
+
+| 서비스 | 이미지 | 내부 포트 | 역할 |
+|--------|--------|-----------|------|
+| **nginx** | nginx:latest | 80, 443 | 리버스 프록시, SSL 종료 |
+| **api** | PHP 8.4-fpm | 9000 | REST API 백엔드 |
+| **mng** | PHP 8.4-fpm | 9000 | 관리자 패널 |
+| **react** | node:20-alpine | 3000 | Next.js 프론트엔드 |
+| **mysql** | mysql:8.0 | 3306 | 데이터베이스 |
+| **php73** | PHP 7.3-fpm | 9000 | 레거시 5130 앱 |
+
+### 3-3. 네트워크
+
+모든 컨테이너는 `samnet` 브릿지 네트워크로 연결됩니다.
+
+```
+[브라우저] → [nginx:443] → api / mng / react (내부 라우팅)
+                          → mysql (컨테이너명: sam-mysql-1)
+```
+
+---
+
+## 4. hosts 파일 설정
+
+로컬 도메인을 사용하기 위해 hosts 파일을 수정합니다.
+
+```bash
+sudo nano /etc/hosts
+```
+
+아래 내용을 추가:
+
+```
+127.0.0.1 api.sam.kr mng.sam.kr admin.sam.kr dev.sam.kr design.sam.kr plan.sam.kr 5130.sam.kr
+127.0.0.1 sam.kr www.sam.kr sales.sam.kr demo.sam.kr
+```
+
+---
+
+## 5. SSL 인증서 설정
+
+로컬 HTTPS를 위한 자체 서명 인증서를 생성합니다.
+
+### 5-1. mkcert 설치 및 초기화
+
+```bash
+# mkcert 설치 (처음 한 번)
+brew install mkcert
+mkcert -install    # 로컬 CA를 시스템에 등록
+```
+
+### 5-2. 와일드카드 인증서 생성
+
+```bash
+cd docker/nginx/ssl/
+
+# *.sam.kr 와일드카드 인증서 생성
+mkcert "*.sam.kr" localhost 127.0.0.1 ::1
+
+# 파일명 변경 (nginx.conf에서 참조하는 이름으로)
+mv _wildcard.sam.kr+3.pem sam.kr.crt
+mv _wildcard.sam.kr+3-key.pem sam.kr.key
+```
+
+### 5-3. 포트 포워딩 설정 (macOS)
+
+Docker가 443 포트를 4443으로 매핑하므로, 브라우저에서 표준 443 포트로 접속하려면 포트 포워딩이 필요합니다.
+
+```bash
+# pfctl 규칙 적용 (443 → 4443 포워딩)
+sudo pfctl -ef docker/nginx/ssl/pf-sam.conf
+```
+
+> **참고**: macOS 재부팅 시 이 설정은 초기화되므로 재부팅 후 다시 실행해야 합니다.
+
+**포트 포워딩 없이 사용하려면** `https://api.sam.kr:4443` 처럼 포트 번호를 직접 지정합니다.
+
+---
+
+## 6. 환경변수 (.env) 설정
+
+### 6-1. API (.env)
+
+```bash
+cd api
+cp .env.example .env
+```
+
+`.env` 파일에서 확인/수정할 항목:
+
+```env
+# 앱 키 생성은 Docker 실행 후 컨테이너 내에서 수행
+# docker exec sam-api-1 php artisan key:generate
+
+APP_NAME="SAM API"
+APP_ENV=local
+APP_DEBUG=true
+APP_URL=https://api.sam.kr/
+
+# DB (Docker 환경에서는 docker-compose가 오버라이드)
+DB_HOST=127.0.0.1          # 로컬 직접 접속 시
+# DB_HOST=sam-mysql-1      # Docker 환경 (자동 오버라이드)
+DB_DATABASE=samdb
+DB_USERNAME=samuser
+DB_PASSWORD=sampass
+
+# Swagger
+L5_SWAGGER_GENERATE_ALWAYS=true
+L5_SWAGGER_CONST_HOST=https://api.sam.kr/
+
+# Sanctum 토큰 (분 단위)
+SANCTUM_ACCESS_TOKEN_EXPIRATION=120
+SANCTUM_REFRESH_TOKEN_EXPIRATION=10080
+
+# 내부 통신 키 (MNG ↔ API)
+INTERNAL_EXCHANGE_SECRET=     # 팀 내부 문서에서 확인
+```
+
+> **API 키, Firebase, AI 서비스 키** 등 민감한 값은 팀 내부 문서(노션)에서 별도 공유합니다.
+
+### 6-2. MNG (.env)
+
+```bash
+cd mng
+cp .env.example .env
+```
+
+```env
+APP_NAME=SAM-MNG
+APP_ENV=local
+APP_DEBUG=true
+APP_URL=https://mng.sam.kr
+
+DB_HOST=sam-mysql-1
+DB_DATABASE=samdb
+DB_USERNAME=samuser
+DB_PASSWORD=sampass
+
+# API 서버 연동
+API_BASE_URL=https://api.sam.kr
+
+# 내부 통신 키 (API와 동일한 값)
+INTERNAL_EXCHANGE_SECRET=     # API의 값과 동일하게 설정
+```
+
+### 6-3. React (.env.local)
+
+```bash
+cd react
+cp .env.example .env.local
+```
+
+```env
+NEXT_PUBLIC_APP_ENV=local
+NEXT_PUBLIC_API_URL=https://api.sam.kr
+NEXT_PUBLIC_FRONTEND_URL=https://dev.sam.kr
+NEXT_PUBLIC_AUTH_MODE=sanctum
+
+# API Key (서버 사이드 전용 - NEXT_PUBLIC_ 접두사 붙이지 말 것!)
+API_KEY=                      # 팀 내부 문서에서 확인
+
+# 개발 도구
+NEXT_PUBLIC_DEV_TOOLBAR_ENABLED=false
+
+# Puppeteer (PDF 생성 - Docker에서는 자동 설정)
+PUPPETEER_EXECUTABLE_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
+```
+
+### 6-4. docs / hotfix
+
+별도 환경변수 설정 불필요 (순수 마크다운 문서 저장소)
+
+---
+
+## 7. Docker 실행
+
+### 7-1. 최초 실행
+
+```bash
+cd docker
+
+# 이미지 빌드 + 컨테이너 시작
+docker compose up -d --build
+```
+
+> 첫 실행 시 이미지 빌드에 5~10분 소요될 수 있습니다.
+
+### 7-2. 초기 설정 (최초 1회)
+
+```bash
+# API: 앱 키 생성 + 의존성 설치 + 마이그레이션
+docker exec sam-api-1 php artisan key:generate
+docker exec sam-api-1 composer install
+docker exec sam-api-1 php artisan migrate
+docker exec sam-api-1 php artisan l5-swagger:generate
+
+# MNG: 앱 키 생성 + 의존성 설치
+docker exec sam-mng-1 php artisan key:generate
+docker exec sam-mng-1 composer install
+docker exec sam-mng-1 npm install
+docker exec sam-mng-1 npm run build
+```
+
+> React는 Docker 컨테이너 시작 시 자동으로 `npm install` + `npm run dev`가 실행됩니다.
+
+### 7-3. 일상적인 시작/종료
+
+```bash
+cd docker
+
+# 시작
+docker compose up -d
+
+# 종료
+docker compose down
+
+# 로그 확인
+docker compose logs -f            # 전체
+docker compose logs -f api        # API만
+docker compose logs -f react      # React만
+
+# 컨테이너 상태 확인
+docker compose ps
+```
+
+---
+
+## 8. 접속 확인
+
+### 8-1. 로컬 도메인
+
+| 서비스 | URL | 설명 |
+|--------|-----|------|
+| **프론트엔드** | `https://dev.sam.kr` | Next.js 사용자 화면 |
+| **API 문서** | `https://api.sam.kr/api-docs/index.html` | Swagger UI |
+| **관리자 패널** | `https://mng.sam.kr` | MNG 관리자 화면 |
+| **관리자 (별칭)** | `https://admin.sam.kr` | MNG와 동일 |
+| **디자인 시스템** | `https://design.sam.kr` | 컴포넌트 스토리북 |
+| **레거시** | `https://5130.sam.kr` | 기존 PHP 시스템 |
+
+### 8-2. DB 접속 정보
+
+| 항목 | 값 |
+|------|-----|
+| Host | `127.0.0.1` |
+| Port | `3306` |
+| Database | `samdb` |
+| Username | `samuser` |
+| Password | `sampass` |
+| Root Password | `root` |
+| 레거시 DB | `chandj` |
+
+> DBeaver, DataGrip, MySQL Workbench 등 원하는 DB 클라이언트로 접속 가능
+
+### 8-3. 접속 테스트
+
+```bash
+# API 응답 확인
+curl -k https://api.sam.kr/api-docs/index.html
+
+# MySQL 접속 확인
+docker exec sam-mysql-1 mysql -u samuser -psampass -e "SHOW DATABASES;"
+```
+
+---
+
+## 9. 저장소별 상세 정보
+
+### 9-1. api/ (REST API 서버)
+
+| 항목 | 값 |
+|------|-----|
+| 프레임워크 | Laravel 12 (PHP 8.4) |
+| 인증 | Sanctum (토큰 기반) |
+| API 문서 | Swagger (l5-swagger) |
+| DB | MySQL 8.0 (samdb) |
+| 역할 | 모든 비즈니스 로직의 중심, 프론트/관리자 모두 이 API 사용 |
+
+**주요 명령어:**
+
+```bash
+# 컨테이너 진입
+docker exec -it sam-api-1 bash
+
+# 마이그레이션
+php artisan migrate
+php artisan migrate:status
+
+# Swagger 재생성
+php artisan l5-swagger:generate
+
+# 코드 포매터
+./vendor/bin/pint
+
+# 캐시 초기화
+php artisan cache:clear
+php artisan config:clear
+php artisan route:clear
+```
+
+**핵심 디렉토리:**
+
+```
+api/
+├── app/
+│   ├── Http/Controllers/Api/V1/   ← API 컨트롤러
+│   ├── Http/Requests/             ← FormRequest (검증)
+│   ├── Models/                    ← Eloquent 모델
+│   ├── Services/                  ← 비즈니스 로직 (핵심)
+│   ├── Swagger/v1/                ← Swagger 문서 클래스
+│   └── Helpers/ApiResponse.php    ← 응답 헬퍼
+├── database/migrations/           ← DB 마이그레이션
+├── routes/api.php                 ← API 라우트
+└── lang/ko/                       ← 한국어 메시지
+```
+
+### 9-2. mng/ (관리자 패널)
+
+| 항목 | 값 |
+|------|-----|
+| 프레임워크 | Laravel 12 (PHP 8.4) |
+| 프론트엔드 | Blade + Tailwind CSS + HTMX + DaisyUI |
+| 역할 | 시스템 관리, 메뉴/권한 관리, 테넌트 관리 |
+
+**주요 명령어:**
+
+```bash
+# 컨테이너 진입
+docker exec -it sam-mng-1 bash
+
+# 프론트 에셋 빌드
+npm run build       # 프로덕션
+npm run dev         # 개발 (HMR)
+
+# 코드 포매터
+./vendor/bin/pint
+```
+
+**핵심 디렉토리:**
+
+```
+mng/
+├── app/
+│   ├── Http/Controllers/          ← 웹 컨트롤러
+│   ├── Models/                    ← 독립 모델 (API와 별개)
+│   └── Services/                  ← 비즈니스 로직
+├── resources/views/               ← Blade 템플릿
+├── routes/web.php                 ← 웹 라우트
+└── public/                        ← 정적 파일
+```
+
+> **주의**: MNG에서는 DB 마이그레이션을 생성/실행하지 않습니다. DB 변경은 반드시 API 프로젝트에서 수행합니다.
+
+### 9-3. react/ (Next.js 프론트엔드)
+
+| 항목 | 값 |
+|------|-----|
+| 프레임워크 | Next.js 15 (React 19, TypeScript) |
+| 스타일링 | Tailwind CSS 4 |
+| UI 라이브러리 | shadcn/ui (Radix UI 기반) |
+| 상태관리 | Zustand |
+| 폼 검증 | Zod + React Hook Form |
+| 역할 | 사용자용 ERP 프론트엔드 |
+
+**주요 명령어:**
+
+```bash
+# React는 Docker 컨테이너가 자동으로 dev 서버를 실행합니다.
+# 수동 실행이 필요한 경우:
+docker exec -it sam-react-1 sh
+
+npm run dev         # 개발 서버
+npm run build       # 프로덕션 빌드
+npm run lint        # ESLint
+```
+
+**핵심 디렉토리:**
+
+```
+react/
+├── src/
+│   ├── app/                       ← Next.js App Router 페이지
+│   ├── components/
+│   │   ├── ui/                    ← shadcn/ui 원자 컴포넌트
+│   │   ├── molecules/             ← 조합 컴포넌트
+│   │   ├── organisms/             ← 복합 컴포넌트
+│   │   └── [도메인]/              ← 도메인별 컴포넌트
+│   ├── lib/                       ← 유틸리티, API 헬퍼
+│   └── stores/                    ← Zustand 스토어
+├── public/                        ← 정적 파일
+└── next.config.ts                 ← Next.js 설정
+```
+
+**핵심 규칙:**
+- 모든 페이지는 `'use client'` 선언 필수 (폐쇄형 ERP, SSR 불필요)
+- API 호출은 Server Action을 통해 수행 (HttpOnly 쿠키 프록시)
+- `buildApiUrl()` 유틸리티 필수 사용
+
+### 9-4. docs/ (기술 문서)
+
+| 항목 | 값 |
+|------|-----|
+| 내용 | 개발 가이드, API 스펙, 기획 문서, 표준 |
+| 형식 | Markdown |
+| 설치 | 없음 (문서만 관리) |
+
+```
+docs/
+├── INDEX.md                       ← 문서 인덱스 (여기부터 시작)
+├── dev/
+│   ├── dev_plans/                 ← 개발 계획 문서
+│   ├── standards/                 ← 코드/아키텍처 표준
+│   ├── guides/                    ← 셋업/사용 가이드
+│   ├── changes/                   ← 변경 로그
+│   └── deploys/                   ← 배포 문서
+├── features/                      ← 기능 스펙
+├── frontend/                      ← 프론트엔드 API 스펙
+├── rules/                         ← 비즈니스 규칙
+└── system/                        ← 시스템 아키텍처
+```
+
+### 9-5. hotfix/ (테스트/QA)
+
+| 항목 | 값 |
+|------|-----|
+| 내용 | E2E 테스트 결과, 버그 리포트, 테스트 케이스 |
+| 형식 | Markdown + 스크린샷 |
+| 설치 | 없음 (문서만 관리) |
+
+```
+hotfix/
+├── e2e/                           ← E2E 테스트 정의
+├── testcase/                      ← 테스트 케이스 문서
+├── reports/                       ← 테스트 실행 결과
+├── screenshots/                   ← 시각적 테스트 증거
+├── research/                      ← 조사 자료
+├── sam.code-workspace             ← VS Code 워크스페이스
+├── *-Test-Report_*.md             ← 개별 테스트 보고서
+└── Fail-*_*.md                    ← 실패 케이스 보고서
+```
+
+---
+
+## 10. 주요 아키텍처 개념
+
+### 10-1. 멀티테넌트
+
+- 모든 데이터에 `tenant_id` 컬럼이 존재
+- `BelongsToTenant` 글로벌 스코프가 자동으로 테넌트 필터링
+- 하나의 DB에서 여러 회사(테넌트)의 데이터를 격리
+
+### 10-2. 데이터 흐름
+
+```
+[사용자 브라우저]
+    │
+    ▼
+[Next.js (react/)]  ──Server Action──▶  [Laravel API (api/)]  ──▶  [MySQL]
+                                              │
+[관리자 브라우저]                                │
+    │                                          │
+    ▼                                          │
+[Laravel MNG (mng/)]  ──내부 API 호출──────────┘
+```
+
+### 10-3. 인증 방식
+
+| 클라이언트 | 인증 방식 | 설명 |
+|-----------|----------|------|
+| React (웹) | Sanctum Cookie | HttpOnly 쿠키, Server Action 프록시 |
+| MNG (관리자) | 세션 + 내부 HMAC | Laravel 세션 + API 내부 통신 키 |
+| 외부 연동 | API Key + Bearer | Sanctum 토큰 |
+
+---
+
+## 11. 자주 쓰는 명령어
+
+### Docker 관련
+
+```bash
+# 전체 시작/종료
+cd docker && docker compose up -d
+cd docker && docker compose down
+
+# 컨테이너 재시작
+docker restart sam-api-1
+docker restart sam-react-1
+
+# 이미지 재빌드 (Dockerfile 수정 후)
+docker compose build --no-cache api
+docker compose up -d api
+
+# 볼륨 포함 완전 초기화 (⚠️ DB 데이터 삭제됨)
+docker compose down -v
+```
+
+### API 개발
+
+```bash
+docker exec sam-api-1 php artisan migrate              # 마이그레이션
+docker exec sam-api-1 php artisan migrate:rollback      # 롤백
+docker exec sam-api-1 php artisan l5-swagger:generate   # Swagger 재생성
+docker exec sam-api-1 ./vendor/bin/pint                 # 코드 포매팅
+docker exec sam-api-1 php artisan tinker                # REPL
+docker exec sam-api-1 php artisan route:list            # 라우트 목록
+```
+
+### MNG 개발
+
+```bash
+docker exec sam-mng-1 php artisan tinker
+docker exec sam-mng-1 npm run dev                       # Vite HMR
+docker exec sam-mng-1 npm run build                     # 에셋 빌드
+docker exec sam-mng-1 ./vendor/bin/pint
+```
+
+### MySQL 접속
+
+```bash
+# CLI 접속
+docker exec -it sam-mysql-1 mysql -u samuser -psampass samdb
+
+# 특정 쿼리 실행
+docker exec sam-mysql-1 mysql -u samuser -psampass samdb -e "SHOW TABLES;"
+```
+
+---
+
+## 12. 트러블슈팅
+
+### SSL 인증서 오류 (브라우저에서 "안전하지 않음")
+
+```bash
+# mkcert CA가 설치되지 않은 경우
+mkcert -install
+
+# 인증서 재생성
+cd docker/nginx/ssl
+mkcert "*.sam.kr" localhost 127.0.0.1 ::1
+mv _wildcard.sam.kr+3.pem sam.kr.crt
+mv _wildcard.sam.kr+3-key.pem sam.kr.key
+
+# Nginx 재시작
+docker restart sam-nginx-1
+```
+
+### 도메인 접속이 안 될 때
+
+```bash
+# hosts 파일 확인
+cat /etc/hosts | grep sam
+
+# DNS 캐시 초기화 (macOS)
+sudo dscacheutil -flushcache
+sudo killall -HUP mDNSResponder
+
+# Nginx 설정 유효성 확인
+docker exec sam-nginx-1 nginx -t
+```
+
+### 포트 포워딩 확인 (443 → 4443)
+
+```bash
+# 현재 규칙 확인
+sudo pfctl -s rules | grep 4443
+
+# 규칙 재적용
+sudo pfctl -ef docker/nginx/ssl/pf-sam.conf
+
+# 규칙 비활성화 (필요 시)
+sudo pfctl -d
+```
+
+### DB 접속 오류
+
+```bash
+# MySQL 컨테이너 상태 확인
+docker compose ps mysql
+
+# MySQL 로그 확인
+docker compose logs mysql
+
+# 수동 접속 테스트
+docker exec sam-mysql-1 mysql -u root -proot -e "SELECT 1;"
+```
+
+### React 빌드/HMR 오류
+
+```bash
+# node_modules 초기화
+docker exec sam-react-1 rm -rf node_modules .next
+docker exec sam-react-1 npm install
+docker restart sam-react-1
+```
+
+### composer/npm 의존성 문제
+
+```bash
+# API
+docker exec sam-api-1 composer install --no-cache
+docker exec sam-api-1 composer dump-autoload
+
+# MNG
+docker exec sam-mng-1 composer install --no-cache
+docker exec sam-mng-1 npm ci
+```
+
+---
+
+## 13. Git 워크플로우
+
+### 브랜치 전략
+
+| 브랜치 | 역할 | 규칙 |
+|--------|------|------|
+| `main` | 배포용 | squash merge로만 올림, 직접 커밋 금지 |
+| `develop` | 일상 작업 | 자유롭게 커밋 |
+| `feature/*` | 대형 기능 | 선택적 사용 (1주일+ 작업) |
+
+### 커밋 메시지 형식
+
+```
+type: 간결한 설명
+
+type 종류:
+  feat:     새 기능
+  fix:      버그 수정
+  refactor: 리팩토링
+  docs:     문서
+  chore:    설정, 빌드
+  style:    코드 포매팅
+```
+
+### 일상 워크플로우
+
+```bash
+# 1. 작업 시작
+cd api
+git checkout develop
+git pull origin develop
+
+# 2. 작업 수행 + 커밋
+git add <파일들>
+git commit -m "feat: 수주관리 삭제 기능 추가"
+
+# 3. 푸시
+git push origin develop
+```
+
+---
+
+## 14. 셋팅 체크리스트
+
+아래 항목을 순서대로 확인하며 셋팅을 완료합니다.
+
+- [ ] Docker Desktop 설치 및 실행
+- [ ] Git 설치 및 Gitea 계정 발급
+- [ ] 5개 저장소 클론 완료
+- [ ] `/etc/hosts` 파일 수정
+- [ ] mkcert 설치 + SSL 인증서 생성
+- [ ] pfctl 포트 포워딩 설정
+- [ ] api/.env 설정 (`.env.example` → `.env`)
+- [ ] mng/.env 설정
+- [ ] react/.env.local 설정
+- [ ] API Key, HMAC Key 등 민감 값 입력 (팀 공유 문서 참조)
+- [ ] `docker compose up -d --build` 실행
+- [ ] 초기 설정 실행 (key:generate, composer install, migrate)
+- [ ] `https://api.sam.kr/api-docs/index.html` 접속 확인
+- [ ] `https://mng.sam.kr` 접속 확인
+- [ ] `https://dev.sam.kr` 접속 확인
+- [ ] DB 클라이언트로 `127.0.0.1:3306` 접속 확인
+
+---
+
+## 15. 참고 문서
+
+| 문서 | 경로 | 설명 |
+|------|------|------|
+| 문서 인덱스 | `docs/INDEX.md` | 전체 문서 목록 |
+| API 규칙 | `API_RULES.md` | API 개발 규칙 |
+| 개발 명령어 | `DEV_COMMANDS.md` | 자주 쓰는 명령어 모음 |
+| 품질 체크리스트 | `QUALITY_CHECKLIST.md` | 코드 품질 체크 항목 |
+| 빠른 참조 | `SAM_QUICK_REFERENCE.md` | 핵심 규칙 요약 |
+| SSL 가이드 | `docker/nginx/ssl/SSL_SETUP_GUIDE.md` | SSL 상세 설정 |
+
+---
+
+> 문의사항은 팀 슬랙 채널 또는 팀장에게 문의하세요.

frontend/_index.md

@@ -0,0 +1,96 @@
+# SAM ERP Frontend Documentation
+
+> **프로젝트**: SAM ERP Next.js 프론트엔드
+> **최종 갱신**: 2026-03-09
+> **현재 문서 버전**: v1
+
+---
+
+## 문서 구조
+
+```
+frontend/
+├── _index.md              ← 현재 문서 (목록 + 버전 관리)
+├── v1/                    ← 현재 활성 버전
+│   ├── 01 ~ 09            ← 프론트엔드 아키텍처/가이드
+│   └── 10                 ← API 연동 스펙
+└── api-specs/             ← (레거시, v1/10으로 이관됨)
+```
+
+---
+
+## 문서 목록 및 버전 현황
+
+| # | 문서 | 버전 | 최종 수정 | 담당 | 대상 | 설명 |
+|---|------|------|----------|------|------|------|
+| 01 | [architecture](v1/01-architecture.md) | 1.0.0 | 2026-03-09 | Frontend | 전체 | 프로젝트 구조, 기술 스택, 디렉토리 설계 |
+| 02 | [api-pattern](v1/02-api-pattern.md) | 1.0.0 | 2026-03-09 | Frontend | FE/BE | API 통신 패턴 (프록시, Server Action, buildApiUrl) |
+| 03 | [component-design](v1/03-component-design.md) | 1.0.0 | 2026-03-09 | Frontend | FE/기획 | 컴포넌트 계층 (atoms → templates), 페이지 유형 |
+| 04 | [common-components](v1/04-common-components.md) | 1.0.0 | 2026-03-09 | Frontend | FE | 공통 컴포넌트 사용법 (UniversalListPage 등) |
+| 05 | [form-pattern](v1/05-form-pattern.md) | 1.0.0 | 2026-03-09 | Frontend | FE | 폼 패턴 (Zod, FormField, react-hook-form) |
+| 06 | [styling-guide](v1/06-styling-guide.md) | 1.0.0 | 2026-03-09 | Frontend | FE/디자인 | CSS 규칙 (Tailwind, shadcn/ui, 색상 시스템) |
+| 07 | [auth-flow](v1/07-auth-flow.md) | 1.0.0 | 2026-03-09 | Frontend | FE/BE | 인증 흐름 (HttpOnly cookie, 토큰 갱신) |
+| 08 | [dashboard-system](v1/08-dashboard-system.md) | 1.0.0 | 2026-03-09 | Frontend | FE/BE | CEO 대시보드 아키텍처 (invalidation, hooks) |
+| 09 | [conventions](v1/09-conventions.md) | 1.0.0 | 2026-03-09 | Frontend | FE | 네이밍, import, 파일 배치, Git 규칙 |
+| 10 | [document-api-integration](v1/10-document-api-integration.md) | 1.0.0 | 2026-02-05 | API Team | FE/BE | 문서 관리 API 연동 (검사 성적서 resolve/upsert) |
+
+### 대상 범례
+- **FE**: 프론트엔드 개발자
+- **BE**: 백엔드 개발자
+- **기획**: 기획자/PM
+- **디자인**: 디자이너
+- **전체**: 모든 역할
+
+---
+
+## 버전 변경 이력
+
+### v1 (2026-03-09 ~)
+
+| 날짜 | 문서 | 변경 | 버전 |
+|------|------|------|------|
+| 2026-03-09 | 01~09 | 초기 작성 | 1.0.0 |
+| 2026-02-05 | 10 | 문서 API 연동 가이드 작성 (api-specs에서 이관) | 1.0.0 |
+
+---
+
+## 버전 관리 규칙
+
+### 문서 버전 (Semantic Versioning)
+
+```
+MAJOR.MINOR.PATCH
+
+MAJOR: 문서 구조 변경, 기존 내용 대폭 수정
+MINOR: 새로운 섹션 추가, 기존 내용 보완
+PATCH: 오탈자, 코드 예시 수정, 사소한 수정
+```
+
+### 업데이트 절차
+
+1. 해당 문서 내용 수정
+2. 문서 상단 `버전`과 `최종 수정` 날짜 갱신
+3. 이 `_index.md`의 문서 목록 테이블 버전/날짜 갱신
+4. 변경 이력 테이블에 행 추가
+
+### 새 문서 추가 시
+
+1. `v1/` 폴더에 `{번호}-{주제}.md` 형식으로 생성
+2. 문서 상단에 버전/날짜/대상 헤더 포함
+3. `_index.md` 문서 목록 테이블에 행 추가
+
+---
+
+## 빠른 참고
+
+| 할 일 | 읽을 문서 |
+|-------|----------|
+| 프로젝트 전체 구조 이해 | 01-architecture |
+| API 호출 방법 알기 | 02-api-pattern |
+| 새 리스트 페이지 만들기 | 03-component-design → 04-common-components |
+| 새 폼 페이지 만들기 | 05-form-pattern |
+| 디자인/스타일 규칙 확인 | 06-styling-guide |
+| 인증 동작 이해 | 07-auth-flow |
+| 대시보드 연동 작업 | 08-dashboard-system |
+| 코딩 컨벤션 확인 | 09-conventions |
+| 문서 관리 API 연동 | 10-document-api-integration |

frontend/v1/01-architecture.md

@@ -0,0 +1,140 @@
+# 01. 프로젝트 아키텍처
+
+> **대상**: 프론트엔드/백엔드/기획자
+> **버전**: 1.0.0
+> **최종 수정**: 2026-03-09
+
+---
+
+## 1. 기술 스택
+
+| 영역 | 기술 | 버전 |
+|------|------|------|
+| 프레임워크 | Next.js (App Router) | 15.x |
+| 런타임 | React | 19.x |
+| 언어 | TypeScript | strict mode |
+| UI 컴포넌트 | shadcn/ui (Radix UI 기반) | - |
+| 스타일링 | Tailwind CSS | 4.x |
+| 폼 관리 | react-hook-form + Zod | - |
+| 상태관리 | React hooks (useState/useCallback/useMemo) | - |
+| 토스트/알림 | sonner | - |
+| 국제화 | next-intl | - |
+| 모바일 | Capacitor (하이브리드 앱) | - |
+| 백엔드 API | PHP Laravel (별도 프로젝트) | 12.x |
+
+---
+
+## 2. 프로젝트 특성
+
+- **폐쇄형 ERP 시스템**: 인증 필수, SEO 불필요, 오히려 노출 방지
+- **모든 페이지 Client Component**: `'use client'` 필수 (서버 컴포넌트 사용 금지)
+- **이유**: HttpOnly 쿠키 기반 인증 → 서버 컴포넌트에서 쿠키 수정(토큰 갱신) 불가
+
+---
+
+## 3. 디렉토리 구조
+
+```
+src/
+├── app/                          # Next.js App Router
+│   ├── [locale]/                 # 다국어 라우팅 (ko, en)
+│   │   ├── (protected)/          # 인증 필수 영역
+│   │   │   ├── layout.tsx        # AuthenticatedLayout (사이드바/헤더)
+│   │   │   ├── accounting/       # 회계 도메인
+│   │   │   ├── hr/               # 인사 도메인
+│   │   │   ├── production/       # 생산 도메인
+│   │   │   ├── orders/           # 영업/주문 도메인
+│   │   │   ├── business/         # 경영/대시보드
+│   │   │   └── dev/              # 개발 도구 (운영 비활성)
+│   │   └── (auth)/               # 비인증 영역 (로그인 등)
+│   └── api/
+│       └── proxy/[...path]/      # API 프록시 (HttpOnly 쿠키 처리)
+│
+├── components/
+│   ├── atoms/                    # 최소 단위 (ScrollableButtonGroup 등)
+│   ├── molecules/                # 조합 단위 (FormField 등)
+│   ├── organisms/                # 페이지 구성 블록 (PageHeader, DataTable 등)
+│   ├── templates/                # 페이지 레이아웃 틀
+│   │   ├── UniversalListPage/    # 리스트 페이지 템플릿 (59+ 페이지 사용)
+│   │   └── IntegratedDetailTemplate/  # 상세/폼 페이지 템플릿
+│   ├── ui/                       # shadcn/ui 기본 컴포넌트
+│   └── {domain}/                 # 도메인별 비즈니스 컴포넌트
+│       ├── accounting/           # 회계 (입금, 출금, 전표 등)
+│       ├── hr/                   # 인사
+│       ├── production/           # 생산
+│       ├── orders/               # 영업
+│       └── business/             # CEO 대시보드 등
+│
+├── hooks/                        # 커스텀 훅
+├── lib/
+│   ├── api/                      # API 통신 유틸리티 (핵심)
+│   ├── utils/                    # 범용 유틸리티
+│   └── dashboard-invalidation.ts # 대시보드 갱신 시스템
+│
+├── middleware.ts                 # 인증/보안/봇 차단 미들웨어
+└── types/                        # 전역 타입 정의
+```
+
+---
+
+## 4. 컴포넌트 계층 구조
+
+```
+atoms → molecules → organisms → templates → pages
+```
+
+| 계층 | 역할 | 예시 |
+|------|------|------|
+| **atoms** | HTML 확장, 단일 기능 | ScrollableButtonGroup, PhoneInput |
+| **molecules** | atom 조합, 재사용 폼 필드 | FormField (Label+Input 통합) |
+| **organisms** | 페이지 구성 블록 | PageHeader, DataTable, SearchableSelectionModal |
+| **templates** | 페이지 뼈대 (config 기반) | UniversalListPage, IntegratedDetailTemplate |
+| **pages** | app/ 라우트 + 도메인 컴포넌트 | page.tsx → {Domain}Component |
+
+---
+
+## 5. 데이터 흐름
+
+```
+[사용자 액션]
+    ↓
+[컴포넌트] → useCallback/useState
+    ↓
+[Server Action] ('use server')
+    ↓
+[executeServerAction / executePaginatedAction]
+    ↓
+[serverFetch → authenticatedFetch]
+    ↓
+[/api/proxy/...path] (Next.js API Route)
+    ↓
+[PHP Laravel Backend /api/v1/...]
+```
+
+- 컴포넌트에서 직접 `fetch()` 금지
+- 모든 데이터 요청은 Server Action → API 프록시 → 백엔드 경로
+- 인증 토큰은 HttpOnly 쿠키에 저장, 프록시에서 자동 주입
+
+---
+
+## 6. 관련 프로젝트
+
+| 프로젝트 | 경로 | 역할 |
+|---------|------|------|
+| sam-react-prod | sam-next/sma-next-project/sam-react-prod | Next.js 프론트엔드 (현재) |
+| sam-api | sam-api/sam-api | PHP Laravel 백엔드 API |
+| sam-design | sam-design/sam-design | React 디자인 시스템 (레거시) |
+| sam-docs | sam-docs | 프로젝트 문서 (현재 문서) |
+
+---
+
+## 7. 주요 설계 결정
+
+| 결정 | 이유 |
+|------|------|
+| Client Component Only | 폐쇄형 ERP, 쿠키 수정 필요 |
+| API Proxy Pattern | HttpOnly 쿠키 보안 유지 |
+| Config-Driven Templates | 59+ 리스트 페이지 일관성 |
+| Server Actions | 타입 안전 + 쿠키 접근 가능 |
+| Tailwind + shadcn/ui | 빠른 개발 + 일관된 디자인 |
+| Zod (신규 폼만) | 기존 폼 안정성 유지하면서 점진 적용 |

frontend/v1/02-api-pattern.md

@@ -0,0 +1,279 @@
+# 02. API 통신 패턴
+
+> **대상**: 프론트엔드/백엔드 개발자
+> **버전**: 1.0.0
+> **최종 수정**: 2026-03-09
+
+---
+
+## 1. 전체 흐름
+
+```
+클라이언트(브라우저)
+    ↓ fetch('/api/proxy/items?page=1')  ← 토큰 없이
+Next.js API Proxy (/api/proxy/[...path])
+    ↓ HttpOnly 쿠키에서 access_token 읽기
+    ↓ Authorization: Bearer {token} 헤더 추가
+PHP Laravel Backend (https://api.xxx.com/api/v1/items?page=1)
+    ↓ 응답
+Next.js → 클라이언트 (응답 전달)
+```
+
+**왜 프록시?**
+- HttpOnly 쿠키는 JavaScript에서 읽을 수 없음 (XSS 방지)
+- 서버(Next.js)에서만 쿠키 읽어서 백엔드에 전달 가능
+- 토큰 갱신(refresh)도 프록시에서 자동 처리
+
+---
+
+## 2. API 호출 방법 2가지
+
+### 방법 A: Server Action (대부분의 경우)
+
+Server Action에서 `serverFetch` / `executeServerAction` 사용.
+
+```typescript
+// components/accounting/Bills/actions.ts
+'use server';
+
+import { buildApiUrl } from '@/lib/api/query-params';
+import { executePaginatedAction } from '@/lib/api';
+
+export async function getBills(params: BillSearchParams) {
+  return executePaginatedAction({
+    url: buildApiUrl('/api/v1/bills', {
+      search: params.search,
+      bill_type: params.billType !== 'all' ? params.billType : undefined,
+      page: params.page,
+    }),
+    transform: transformBillApiToFrontend,
+    errorMessage: '어음 목록 조회에 실패했습니다.',
+  });
+}
+```
+
+컴포넌트에서 호출:
+```typescript
+// 컴포넌트 내부
+const result = await getBills({ search: '', page: 1 });
+if (result.success) {
+  setData(result.data);
+  setPagination(result.pagination);
+}
+```
+
+### 방법 B: 프록시 직접 호출 (특수한 경우)
+
+대시보드 훅, 파일 다운로드 등 Server Action이 부적합한 경우에만 사용.
+
+```typescript
+// hooks/useCEODashboard.ts
+const response = await fetch('/api/proxy/daily-report/summary');
+const result = await response.json();
+```
+
+---
+
+## 3. 핵심 유틸리티
+
+### 3.1 buildApiUrl — URL 빌더 (필수)
+
+```typescript
+import { buildApiUrl } from '@/lib/api/query-params';
+
+// 기본 사용
+buildApiUrl('/api/v1/items')
+// → "https://api.xxx.com/api/v1/items"
+
+// 쿼리 파라미터 (undefined는 자동 제외)
+buildApiUrl('/api/v1/items', {
+  search: '볼트',
+  status: undefined,     // ← 자동 제외됨
+  page: 1,               // ← 숫자 → 문자 자동 변환
+})
+// → "https://api.xxx.com/api/v1/items?search=볼트&page=1"
+
+// 동적 경로 + 파라미터
+buildApiUrl(`/api/v1/items/${id}`, { with_details: true })
+```
+
+**금지 패턴:**
+```typescript
+// ❌ 직접 URLSearchParams 사용 금지
+const params = new URLSearchParams();
+params.set('search', value);
+url: `${API_URL}/api/v1/items?${params.toString()}`
+```
+
+### 3.2 executeServerAction — 단건 조회/CUD
+
+```typescript
+import { executeServerAction } from '@/lib/api';
+
+// 단건 조회
+return executeServerAction({
+  url: buildApiUrl(`/api/v1/items/${id}`),
+  transform: transformItemApiToFrontend,
+  errorMessage: '품목 조회에 실패했습니다.',
+});
+
+// 생성 (POST)
+return executeServerAction({
+  url: buildApiUrl('/api/v1/items'),
+  method: 'POST',
+  body: JSON.stringify(payload),
+  errorMessage: '등록에 실패했습니다.',
+});
+
+// 삭제 (DELETE)
+return executeServerAction({
+  url: buildApiUrl(`/api/v1/items/${id}`),
+  method: 'DELETE',
+  errorMessage: '삭제에 실패했습니다.',
+});
+```
+
+**반환 구조:**
+```typescript
+{
+  success: boolean;
+  data?: T;
+  error?: string;
+  fieldErrors?: Record<string, string[]>;  // Laravel validation 에러
+}
+```
+
+### 3.3 executePaginatedAction — 페이지네이션 목록
+
+```typescript
+import { executePaginatedAction } from '@/lib/api';
+
+return executePaginatedAction({
+  url: buildApiUrl('/api/v1/items', {
+    search: params.search,
+    page: params.page,
+  }),
+  transform: transformItemApiToFrontend,
+  errorMessage: '목록 조회에 실패했습니다.',
+});
+```
+
+**반환 구조:**
+```typescript
+{
+  success: boolean;
+  data: T[];
+  pagination: {
+    currentPage: number;
+    lastPage: number;
+    perPage: number;
+    total: number;
+  };
+  error?: string;
+}
+```
+
+---
+
+## 4. Server Action 규칙
+
+### 파일 위치
+각 도메인 컴포넌트 폴더 내 `actions.ts`:
+```
+src/components/accounting/Bills/actions.ts
+src/components/hr/EmployeeList/actions.ts
+```
+
+### 필수 규칙
+
+```typescript
+'use server';  // 첫 줄 필수
+
+// ✅ 타입은 인라인 정의 (export interface/type 허용)
+export interface BillSearchParams { ... }
+
+// ❌ 타입 re-export 금지 (Next.js Turbopack 제한)
+// export type { BillType } from './types';  ← 컴파일 에러
+// → 컴포넌트에서 원본 파일에서 직접 import할 것
+```
+
+### actions.ts 패턴 요약
+
+| 작업 | 유틸리티 | HTTP |
+|------|---------|------|
+| 목록 조회 (페이지네이션) | `executePaginatedAction` | GET |
+| 단건 조회 | `executeServerAction` | GET |
+| 등록 | `executeServerAction` | POST |
+| 수정 | `executeServerAction` | PUT/PATCH |
+| 삭제 | `executeServerAction` | DELETE |
+
+---
+
+## 5. 인증 토큰 흐름
+
+```
+[로그인]
+  ↓ POST /api/proxy/auth/login
+  ↓ 백엔드 → access_token + refresh_token 반환
+  ↓ 프록시에서 HttpOnly 쿠키로 설정
+    - access_token (HttpOnly, Max-Age=2h)
+    - refresh_token (HttpOnly, Max-Age=7d)
+    - is_authenticated (non-HttpOnly, 프론트 상태 확인용)
+
+[API 호출]
+  ↓ 프록시가 쿠키에서 토큰 읽어 헤더 주입
+
+[401 발생 시]
+  ↓ authenticatedFetch가 자동 감지
+  ↓ refresh_token으로 새 access_token 발급
+  ↓ 재시도 (1회)
+  ↓ 실패 시 → 쿠키 삭제 → 로그인 페이지 이동
+```
+
+---
+
+## 6. 백엔드 개발자 참고
+
+### API 응답 규격
+
+프론트엔드는 Laravel 표준 응답 구조를 기대합니다:
+
+```json
+// 단건
+{
+  "success": true,
+  "data": { ... }
+}
+
+// 페이지네이션 목록
+{
+  "success": true,
+  "data": [ ... ],
+  "current_page": 1,
+  "last_page": 5,
+  "per_page": 20,
+  "total": 93
+}
+
+// 에러
+{
+  "success": false,
+  "message": "에러 메시지"
+}
+
+// Validation 에러
+{
+  "message": "The given data was invalid.",
+  "errors": {
+    "name": ["이름은 필수입니다."],
+    "amount": ["금액은 0보다 커야 합니다."]
+  }
+}
+```
+
+### API 엔드포인트 기본 규칙
+- 기본 경로: `/api/v1/{resource}`
+- RESTful: GET(조회), POST(생성), PUT/PATCH(수정), DELETE(삭제)
+- 페이지네이션: `?page=1&per_page=20`
+- 검색: `?search=키워드`
+- 개별 기능 API 스펙은 `sam-docs/frontend/api-specs/` 참조

frontend/v1/03-component-design.md

@@ -0,0 +1,172 @@
+# 03. 컴포넌트 설계
+
+> **대상**: 프론트엔드 개발자, 기획자
+> **버전**: 1.0.0
+> **최종 수정**: 2026-03-09
+
+---
+
+## 1. 설계 원칙
+
+- **모든 페이지는 Client Component** (`'use client'` 필수)
+- **Config-Driven**: 설정 객체로 페이지 동작 정의 → 일관성 + 빠른 개발
+- **기존 패턴 우선**: 새 컴포넌트 만들기 전 반드시 유사 컴포넌트 검색
+- **계층 준수**: atoms → molecules → organisms → templates → pages
+
+---
+
+## 2. 페이지 3대 유형
+
+### 2.1 리스트 페이지 → UniversalListPage
+
+**사용 현황**: 59+ 페이지
+
+```typescript
+// 패턴: page.tsx는 얇은 껍데기, 비즈니스 로직은 도메인 컴포넌트에
+// src/app/[locale]/(protected)/accounting/bills/page.tsx
+'use client';
+import { BillManagement } from '@/components/accounting/BillManagement';
+export default function BillsPage() {
+  return <BillManagement />;
+}
+
+// src/components/accounting/BillManagement/index.tsx
+export function BillManagement() {
+  const config: UniversalListConfig<BillRecord> = {
+    title: '어음관리',
+    icon: FileText,
+    columns: [...],
+    actions: { getList: getBills },
+    // ... 나머지 설정
+  };
+  return <UniversalListPage config={config} />;
+}
+```
+
+**config로 제어하는 것들:**
+- 컬럼 정의, 정렬, 필터
+- 검색/날짜 선택기
+- 통계 카드
+- 체크박스/선택
+- 액션 버튼
+- 모바일 카드 렌더링
+- Excel 내보내기
+
+### 2.2 상세/폼 페이지 → IntegratedDetailTemplate
+
+**모드**: create(등록), view(조회), edit(수정)
+
+```typescript
+<IntegratedDetailTemplate
+  mode="create"
+  title="품목 등록"
+  fields={fieldDefinitions}
+  onSave={handleSave}
+  onDelete={handleDelete}
+/>
+```
+
+**또는 Card 기반 수동 구성** (기존 패턴):
+```typescript
+<PageLayout>
+  <PageHeader title="품목 상세" />
+  <Card>
+    <CardContent>
+      {/* 폼 필드들 */}
+    </CardContent>
+  </Card>
+</PageLayout>
+```
+
+### 2.3 대시보드 → 커스텀 섹션 조합
+
+CEO 대시보드처럼 여러 섹션을 조합하는 경우:
+```typescript
+<PageLayout>
+  <SummaryNavBar />
+  <div className="space-y-6">
+    {sectionOrder.map(key => renderSection(key))}
+  </div>
+</PageLayout>
+```
+
+---
+
+## 3. 컴포넌트 계층별 가이드
+
+### atoms (src/components/atoms/)
+- 가장 작은 재사용 단위
+- HTML 요소 확장 또는 단일 기능
+- 예: ScrollableButtonGroup, PhoneInput, BusinessNumberInput
+
+### molecules (src/components/molecules/)
+- atom 2개 이상 조합
+- **FormField**: Label + Input 통합 (신규 폼 필수)
+- 예: FormField, DateRangeFilter
+
+### organisms (src/components/organisms/)
+- 독립적 기능 블록, 페이지에 바로 배치 가능
+- **내보내기 확인**: `src/components/organisms/index.ts`
+
+| 컴포넌트 | 용도 |
+|---------|------|
+| PageHeader | 페이지 제목 + 액션 버튼 |
+| PageLayout | 페이지 콘텐츠 래퍼 (패딩/max-width) |
+| DataTable | 범용 데이터 테이블 |
+| StatCards | 통계 카드 모음 |
+| SearchFilter | 검색/필터 바 |
+| SearchableSelectionModal\<T\> | 검색+선택 모달 (제네릭) |
+| MobileCard | 모바일 리스트 카드 |
+
+### templates (src/components/templates/)
+- 페이지 전체 구조 정의
+- config 객체로 동작 제어
+
+| 템플릿 | 용도 | 사용 수 |
+|--------|------|--------|
+| UniversalListPage | 리스트/목록 페이지 | 59+ |
+| IntegratedDetailTemplate | 상세/등록/수정 페이지 | 10+ |
+
+### 도메인 컴포넌트 (src/components/{domain}/)
+- 비즈니스 로직 포함
+- 도메인별 폴더 분류
+
+```
+components/
+├── accounting/     # 회계: 입금, 출금, 전표, 어음, 세금계산서
+├── hr/             # 인사: 사원, 급여, 근태
+├── production/     # 생산: 공정, 생산일보
+├── orders/         # 영업: 주문, 견적, 수주
+├── business/       # 경영: CEO 대시보드
+└── common/         # 공통: 계정과목 설정 등 여러 도메인에서 사용
+```
+
+---
+
+## 4. 새 페이지 만들기 체크리스트
+
+### 리스트 페이지
+1. `src/app/[locale]/(protected)/{domain}/{page}/page.tsx` 생성
+2. `src/components/{domain}/{ComponentName}/index.tsx` 생성
+3. `src/components/{domain}/{ComponentName}/actions.ts` 생성
+4. UniversalListPage config 작성
+5. types 정의 (API 응답 → 프론트 타입 변환)
+
+### 상세/폼 페이지
+1. 기존 유사 페이지 검색 (패턴 참고)
+2. IntegratedDetailTemplate 사용 가능한지 확인
+3. 아니면 Card 기반 수동 구성
+
+### 모달/팝업
+1. `SearchableSelectionModal<T>` 사용 가능한지 먼저 확인
+2. 아니면 Radix Dialog 직접 사용
+3. `alert()`, `confirm()` 사용 금지 → Dialog 또는 toast
+
+---
+
+## 5. 컴포넌트 레지스트리
+
+개발 환경에서 `/dev/component-registry` 접속하면:
+- 전체 컴포넌트 목록 (실시간 스캔)
+- 컴포넌트 간 관계도 (imports, usedBy)
+- 새 컴포넌트 생성 전 기존 컴포넌트 확인 필수

frontend/v1/04-common-components.md

@@ -0,0 +1,246 @@
+# 04. 공통 컴포넌트 사용법
+
+> **대상**: 프론트엔드 개발자
+> **버전**: 1.0.0
+> **최종 수정**: 2026-03-09
+
+---
+
+## 1. UniversalListPage
+
+59+ 리스트 페이지에서 사용하는 통합 템플릿. config 객체 하나로 전체 동작 제어.
+
+### 기본 사용법
+
+```typescript
+import {
+  UniversalListPage,
+  type UniversalListConfig,
+  type StatCard,
+} from '@/components/templates/UniversalListPage';
+
+const config: UniversalListConfig<MyRecord> = {
+  // 필수
+  title: '페이지 제목',
+  icon: FileText,
+  basePath: '/accounting/my-page',
+  idField: 'id',
+  columns: [
+    { key: 'name', label: '이름', className: 'w-[200px]' },
+    { key: 'amount', label: '금액', className: 'text-right w-[120px]' },
+    { key: 'status', label: '상태', className: 'text-center w-[80px]' },
+  ],
+  actions: {
+    getList: getMyList,          // Server Action
+    deleteItems: deleteMyItems,  // 선택사항
+  },
+
+  // 선택
+  itemsPerPage: 20,
+  showCheckbox: true,
+  clientSideFiltering: false,  // 서버 페이지네이션 시 false
+};
+
+return <UniversalListPage config={config} />;
+```
+
+### 주요 config 옵션
+
+| 옵션 | 타입 | 설명 |
+|------|------|------|
+| `columns` | Column[] | 테이블 컬럼 정의 |
+| `actions.getList` | Function | 목록 조회 Server Action |
+| `showCheckbox` | boolean | 체크박스 표시 |
+| `hideSearch` | boolean | 검색창 숨김 |
+| `computeStats` | () => StatCard[] | 통계 카드 |
+| `headerActions` | () => ReactNode | 헤더 버튼 영역 |
+| `renderTableRow` | Function | 커스텀 행 렌더링 |
+| `renderMobileCard` | Function | 모바일 카드 렌더링 |
+| `tableFooter` | ReactNode | 테이블 하단 (합계 행 등) |
+| `dateRangeSelector` | Object | 날짜 범위 선택기 |
+| `tabs` | Tab[] | 탭 필터 |
+| `excelExport` | Object | Excel 내보내기 설정 |
+
+### 서버 페이지네이션 연동
+
+```typescript
+const [currentPage, setCurrentPage] = useState(1);
+const [pagination, setPagination] = useState({ ... });
+
+<UniversalListPage
+  config={config}
+  initialData={data}
+  externalPagination={{
+    currentPage: pagination.currentPage,
+    totalPages: pagination.lastPage,
+    totalItems: pagination.total,
+    itemsPerPage: pagination.perPage,
+    onPageChange: setCurrentPage,
+  }}
+  externalIsLoading={isLoading}
+/>
+```
+
+---
+
+## 2. SearchableSelectionModal\<T\>
+
+검색 + 선택 기능이 필요한 모달. 직접 Dialog 조합 금지.
+
+### 사용법
+
+```typescript
+import { SearchableSelectionModal } from '@/components/organisms';
+
+<SearchableSelectionModal<ClientRecord>
+  open={isOpen}
+  onOpenChange={setIsOpen}
+  title="거래처 선택"
+  searchPlaceholder="거래처명 검색"
+  fetchItems={async (search) => {
+    const result = await searchClients({ search });
+    return result.success ? result.data : [];
+  }}
+  columns={[
+    { key: 'name', label: '거래처명' },
+    { key: 'code', label: '코드' },
+  ]}
+  onSelect={(item) => {
+    setSelectedClient(item);
+    setIsOpen(false);
+  }}
+  getItemId={(item) => item.id}
+/>
+```
+
+---
+
+## 3. IntegratedDetailTemplate
+
+상세/등록/수정 페이지 통합 템플릿.
+
+### 기본 사용법
+
+```typescript
+import { IntegratedDetailTemplate } from '@/components/templates/IntegratedDetailTemplate';
+
+<IntegratedDetailTemplate
+  mode={mode}  // 'create' | 'view' | 'edit'
+  title="품목 상세"
+  icon={Package}
+  fields={[
+    {
+      key: 'name',
+      label: '품목명',
+      type: 'text',
+      required: true,
+      section: '기본정보',
+    },
+    {
+      key: 'category',
+      label: '분류',
+      type: 'select',
+      options: categoryOptions,
+      section: '기본정보',
+    },
+  ]}
+  data={formData}
+  onSave={handleSave}
+  onDelete={handleDelete}
+  onModeChange={setMode}
+/>
+```
+
+### forwardRef API
+
+프로그래밍 방식으로 폼 제어:
+
+```typescript
+const templateRef = useRef<IntegratedDetailTemplateRef>(null);
+
+// 폼 데이터 읽기/쓰기
+templateRef.current?.getFormData();
+templateRef.current?.setFormData(newData);
+templateRef.current?.setFieldValue('name', '새 이름');
+templateRef.current?.validate();
+```
+
+---
+
+## 4. PageHeader / PageLayout
+
+### PageLayout — 페이지 콘텐츠 래퍼
+
+```typescript
+import { PageLayout } from '@/components/organisms/PageLayout';
+
+<PageLayout>
+  {/* 콘텐츠 */}
+</PageLayout>
+```
+
+- 자동으로 `p-0 md:space-y-6` 패딩 적용
+- **page.tsx에서 추가 패딩 금지** (이중 패딩 방지)
+
+### PageHeader — 페이지 제목
+
+```typescript
+import { PageHeader } from '@/components/organisms/PageHeader';
+
+<PageHeader
+  title="어음관리"
+  description="어음을 등록하고 관리합니다"
+  icon={FileText}
+  actions={
+    <Button onClick={handleCreate}>등록</Button>
+  }
+/>
+```
+
+---
+
+## 5. StatCards — 통계 카드
+
+```typescript
+import { StatCards } from '@/components/organisms';
+
+<StatCards
+  stats={[
+    { label: '전체', value: '125건', icon: FileText, iconColor: 'text-gray-500' },
+    { label: '입금', value: '50,000,000원', icon: ArrowDown, iconColor: 'text-blue-500' },
+    { label: '출금', value: '30,000,000원', icon: ArrowUp, iconColor: 'text-red-500' },
+  ]}
+/>
+```
+
+---
+
+## 6. DataTable — 데이터 테이블
+
+organisms 레벨 범용 테이블. UniversalListPage 내부에서도 사용.
+
+```typescript
+import { DataTable } from '@/components/organisms';
+
+<DataTable
+  columns={[
+    { key: 'name', label: '이름' },
+    { key: 'amount', label: '금액', type: 'number' },
+  ]}
+  data={items}
+  onRowClick={(item) => handleDetail(item.id)}
+/>
+```
+
+---
+
+## 7. 테이블 필수 구조
+
+모든 테이블은 다음 컬럼 순서를 준수:
+
+```
+[체크박스] → [번호(1부터)] → [데이터 컬럼들] → [작업 컬럼]
+```
+
+- **번호**: `(currentPage - 1) * pageSize + index + 1`
+- **작업 버튼**: 체크박스 선택 시만 표시 (또는 행별 버튼)

frontend/v1/05-form-pattern.md

@@ -0,0 +1,193 @@
+# 05. 폼 패턴
+
+> **대상**: 프론트엔드 개발자
+> **버전**: 1.0.0
+> **최종 수정**: 2026-03-09
+
+---
+
+## 1. 폼 패턴 2가지
+
+| 패턴 | 적용 대상 | 비고 |
+|------|----------|------|
+| Zod + react-hook-form | **신규 폼** | 필수 |
+| useState + 수동 검증 | 기존 폼 | 건드리지 않음 |
+
+---
+
+## 2. 신규 폼: Zod + react-hook-form
+
+### 기본 패턴
+
+```typescript
+import { z } from 'zod';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+
+// 1. 스키마 정의 (타입 + 검증 동시에)
+const formSchema = z.object({
+  itemName: z.string().min(1, '품목명을 입력하세요'),
+  quantity: z.number().min(1, '1 이상 입력하세요'),
+  status: z.enum(['active', 'inactive']),
+  memo: z.string().optional(),
+});
+
+// 2. 스키마에서 타입 추출 (별도 interface 불필요)
+type FormData = z.infer<typeof formSchema>;
+
+// 3. useForm 연결
+const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
+  resolver: zodResolver(formSchema),
+  defaultValues: {
+    itemName: '',
+    quantity: 1,
+    status: 'active',
+  },
+});
+```
+
+### 규칙
+
+| 항목 | 규칙 |
+|------|------|
+| 스키마 위치 | 컴포넌트 파일 상단 또는 같은 폴더의 `schema.ts` |
+| 타입 추출 | `z.infer<typeof schema>` 사용, 별도 interface 중복 금지 |
+| 에러 메시지 | **한글** (사용자에게 직접 표시) |
+| `as` 캐스트 | 지양 (Zod가 타입 보장) |
+
+### Zod 사용하지 않는 경우
+- 기존 `rules={{ required: true }}` 패턴으로 작동 중인 폼
+- 필드 1~2개짜리 인라인 폼 (오버엔지니어링)
+
+---
+
+## 3. FormField molecule
+
+Label + Input 수동 조합 대신 `FormField` 사용 (신규 폼).
+
+### 기본 사용법
+
+```typescript
+import { FormField } from '@/components/molecules/FormField';
+
+<FormField
+  label="회사명"
+  value={formData.companyName}
+  onChange={(value) => handleChange('companyName', value)}
+  placeholder="회사명을 입력하세요"
+  disabled={!isEditMode}
+/>
+```
+
+### 지원 타입
+
+| type | 설명 | 비고 |
+|------|------|------|
+| `text` | 일반 텍스트 (기본값) | |
+| `number` | 숫자 입력 | |
+| `email` | 이메일 | |
+| `tel` | 전화번호 | 자동 포맷 (010-1234-5678) |
+| `businessNumber` | 사업자등록번호 | 자동 포맷 (123-45-67890) |
+| `textarea` | 여러 줄 텍스트 | |
+| `currency` | 금액 입력 | 콤마 자동 포맷 |
+| `select` | 드롭다운 선택 | options prop 필요 |
+| `date` | 날짜 선택 | DatePicker 연동 |
+
+### FormField로 대체하지 않는 경우
+- Select, DatePicker 단독 사용 (이미 Label 포함인 경우)
+- ImageUpload, FileInput 등 특수 컴포넌트
+- 복합 레이아웃 (주소 검색: 버튼+입력 조합)
+
+### 비교
+
+```typescript
+// ✅ FormField 사용 (신규 폼)
+<FormField
+  label="회사명"
+  value={formData.companyName}
+  onChange={(value) => handleChange('companyName', value)}
+/>
+
+// ❌ 수동 조합 (신규 폼에서 금지)
+<div className="space-y-2">
+  <Label>회사명</Label>
+  <Input
+    value={formData.companyName}
+    onChange={(e) => handleChange('companyName', e.target.value)}
+  />
+</div>
+```
+
+---
+
+## 4. 기존 폼 패턴 (수정하지 않음)
+
+```typescript
+// useState 기반 — 작동 중이면 건드리지 않음
+const [formData, setFormData] = useState<FormData>(initialData);
+
+const handleChange = (field: keyof FormData, value: string) => {
+  setFormData(prev => ({ ...prev, [field]: value }));
+};
+
+// react-hook-form rules 기반
+<Input {...register('name', { required: true })} />
+```
+
+---
+
+## 5. 서버 검증 에러 처리
+
+Laravel에서 반환하는 validation 에러를 폼에 표시:
+
+```typescript
+const result = await saveItem(formData);
+
+if (!result.success && result.fieldErrors) {
+  // fieldErrors: { name: ['이름은 필수입니다.'], amount: ['0보다 커야 합니다.'] }
+  Object.entries(result.fieldErrors).forEach(([field, messages]) => {
+    setError(field as keyof FormData, {
+      type: 'server',
+      message: messages[0],
+    });
+  });
+}
+```
+
+---
+
+## 6. DatePicker 사용 규칙
+
+`input type="date"` 대신 커스텀 DatePicker 사용:
+
+```typescript
+import { DatePicker } from '@/components/ui/date-picker';
+
+<DatePicker
+  value={formData.startDate}  // 'yyyy-MM-dd' 문자열
+  onChange={(date) => setFormData(prev => ({ ...prev, startDate: date }))}
+  placeholder="날짜 선택"
+/>
+```
+
+- `value`/`onChange`: string (`yyyy-MM-dd`)
+- `minDate`/`maxDate`: Date 객체 (`new Date('2026-01-01')`)
+- 테이블 셀: `size="sm"` 사용
+- 한글 로케일, 주말/공휴일 색상 구분
+
+---
+
+## 7. Radix UI Select 주의사항
+
+빈 값('')으로 시작 후 값 변경이 안 되는 버그 → `key` prop으로 해결:
+
+```typescript
+// ✅ key prop으로 강제 리마운트
+<Select
+  key={`${fieldKey}-${stringValue}`}
+  value={stringValue}
+  onValueChange={onChange}
+>
+  {/* ... */}
+</Select>
+```

frontend/v1/06-styling-guide.md

@@ -0,0 +1,225 @@
+# 06. 스타일링 가이드
+
+> **대상**: 프론트엔드 개발자, 디자이너
+> **버전**: 1.0.0
+> **최종 수정**: 2026-03-09
+
+---
+
+## 1. 기술 스택
+
+| 도구 | 역할 |
+|------|------|
+| **Tailwind CSS 4** | 유틸리티 클래스 기반 스타일링 |
+| **shadcn/ui** | Radix UI 기반 컴포넌트 라이브러리 |
+| **CSS Variables** | 테마 토큰 (다크모드 대비) |
+| **lucide-react** | 아이콘 |
+
+---
+
+## 2. 기본 규칙
+
+### 사용
+```typescript
+// ✅ Tailwind 클래스 사용
+<div className="flex items-center gap-2 p-4 bg-muted rounded-lg">
+
+// ✅ shadcn/ui 컴포넌트
+import { Button } from '@/components/ui/button';
+import { Card, CardContent } from '@/components/ui/card';
+```
+
+### 금지
+```typescript
+// ❌ 인라인 스타일
+<div style={{ display: 'flex', padding: '16px' }}>
+
+// ❌ CSS 모듈 / styled-components
+import styles from './Component.module.css';
+
+// ❌ 전역 CSS (globals.css 외)
+```
+
+---
+
+## 3. 레이아웃 패딩 규칙
+
+```
+AuthenticatedLayout (<main>) → 패딩 없음
+  └── PageLayout → p-0 md:space-y-6 (패딩 담당)
+       └── 콘텐츠 영역
+```
+
+**핵심**: page.tsx에서 추가 패딩 래퍼 금지 (이중 패딩 방지)
+
+```typescript
+// ✅ 올바름
+<PageLayout>
+  <PageHeader title="..." />
+  <Card>...</Card>
+</PageLayout>
+
+// ❌ 이중 패딩
+<div className="p-6">  {/* ← 금지 */}
+  <PageLayout>
+    ...
+  </PageLayout>
+</div>
+```
+
+---
+
+## 4. 간격 시스템
+
+| 용도 | 클래스 | 값 |
+|------|--------|-----|
+| 섹션 간 간격 | `space-y-6` | 24px |
+| 카드 내부 간격 | `space-y-4` | 16px |
+| 인라인 요소 간격 | `gap-2` | 8px |
+| 폼 필드 간격 | `space-y-4` | 16px |
+| 그리드 갭 | `gap-4` 또는 `gap-6` | 16px / 24px |
+
+---
+
+## 5. 반응형 패턴
+
+```typescript
+// 그리드: 모바일 1열 → 데스크톱 2~4열
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">
+
+// 숨기기/보이기
+<div className="hidden md:block">  {/* 데스크톱만 */}
+<div className="block md:hidden">  {/* 모바일만 */}
+
+// 폰트 크기 반응형
+<h1 className="text-lg md:text-2xl font-bold">
+```
+
+### 브레이크포인트
+
+| 접두사 | 최소 너비 | 대상 |
+|--------|----------|------|
+| (없음) | 0px | 모바일 |
+| `sm:` | 640px | 소형 태블릿 |
+| `md:` | 768px | 태블릿 |
+| `lg:` | 1024px | 데스크톱 |
+| `xl:` | 1280px | 넓은 화면 |
+
+---
+
+## 6. 색상 시스템
+
+shadcn/ui CSS 변수 기반 — 다크모드 자동 대응:
+
+| 용도 | 클래스 | 설명 |
+|------|--------|------|
+| 배경 | `bg-background` | 페이지 배경 |
+| 카드 | `bg-card` | 카드 배경 |
+| 강조 | `bg-muted` | 연한 배경 (테이블 호버 등) |
+| 텍스트 | `text-foreground` | 기본 텍스트 |
+| 보조 텍스트 | `text-muted-foreground` | 설명, 플레이스홀더 |
+| 테두리 | `border` | 기본 테두리 |
+| 위험 | `text-destructive` | 삭제, 에러 |
+
+### 상태 색상
+
+| 상태 | 텍스트 | 배경 |
+|------|--------|------|
+| 입금/증가 | `text-blue-600` | `bg-blue-50` |
+| 출금/감소 | `text-red-600` | `bg-red-50` |
+| 성공/완료 | `text-green-600` | `bg-green-50` |
+| 경고/대기 | `text-orange-500` | `bg-orange-50` |
+| 비활성 | `text-gray-400` | `bg-gray-50` |
+
+---
+
+## 7. 컴포넌트 스타일 규칙
+
+### 버튼
+```typescript
+// 주요 액션
+<Button size="sm">등록</Button>
+
+// 보조 액션
+<Button variant="outline" size="sm">취소</Button>
+
+// 위험 액션 (삭제)
+<Button variant="destructive" size="sm">삭제</Button>
+```
+
+### 테이블
+```typescript
+// 기본 셀 정렬
+<TableCell className="text-center">  {/* 날짜, 상태, 번호 */}
+<TableCell className="text-right">   {/* 금액 */}
+<TableCell className="text-left">    {/* 텍스트 (기본) */}
+
+// 합계 행
+<TableRow className="bg-muted/50 font-medium">
+```
+
+### Badge
+```typescript
+<Badge variant="outline">기본</Badge>
+<Badge variant="default">활성</Badge>
+<Badge variant="destructive">에러</Badge>
+```
+
+---
+
+## 8. 팝업/모달 규칙
+
+| 용도 | 컴포넌트 | 비고 |
+|------|---------|------|
+| 확인/취소 | AlertDialog (Radix) | `alert()`, `confirm()` 금지 |
+| 데이터 입력 | Dialog (Radix) | `prompt()` 금지 |
+| 알림 | `toast` (sonner) | 성공/에러 피드백 |
+| 검색+선택 | SearchableSelectionModal | 커스텀 Dialog 조합 금지 |
+
+```typescript
+// ✅ 토스트 사용
+import { toast } from 'sonner';
+toast.success('저장되었습니다.');
+toast.error('저장에 실패했습니다.');
+
+// ❌ alert 금지
+alert('저장되었습니다.');
+```
+
+---
+
+## 9. 아이콘
+
+**lucide-react** 사용:
+
+```typescript
+import { FileText, Settings, Search, Plus, Trash2 } from 'lucide-react';
+
+// 인라인 아이콘
+<FileText className="h-4 w-4" />
+
+// 버튼 내 아이콘
+<Button size="sm">
+  <Plus className="h-4 w-4 mr-1" />
+  등록
+</Button>
+```
+
+---
+
+## 10. 금액 표시
+
+```typescript
+import { formatNumber } from '@/lib/utils/amount';
+
+formatNumber(1234567)    // "1,234,567"
+formatNumber(0)          // "0"
+formatNumber(undefined)  // "0"
+```
+
+테이블에서:
+```typescript
+<TableCell className="text-right text-blue-600">
+  {formatNumber(item.amount)}
+</TableCell>
+```

frontend/v1/07-auth-flow.md

@@ -0,0 +1,137 @@
+# 07. 인증 흐름
+
+> **대상**: 프론트엔드/백엔드 개발자
+> **버전**: 1.0.0
+> **최종 수정**: 2026-03-09
+
+---
+
+## 1. 인증 아키텍처 요약
+
+```
+┌─────────────────────────────────────────────────────┐
+│ 브라우저                                              │
+│                                                      │
+│  [React 컴포넌트]                                     │
+│       │ fetch('/api/proxy/...')                       │
+│       │ (토큰 전송 안함 — 쿠키가 자동 포함)              │
+│       ▼                                              │
+│  [Next.js API Proxy]                                 │
+│       │ 쿠키에서 access_token 읽기                     │
+│       │ Authorization: Bearer {token} 헤더 추가        │
+│       ▼                                              │
+│  [authenticatedFetch 게이트웨이]                       │
+│       │ 401 → refresh → retry (자동)                  │
+│       ▼                                              │
+│  [PHP Laravel Backend]                               │
+│                                                      │
+│  쿠키:                                                │
+│  ├── access_token  (HttpOnly, 2시간)                  │
+│  ├── refresh_token (HttpOnly, 7일)                    │
+│  └── is_authenticated (non-HttpOnly, 상태 확인용)      │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. 왜 HttpOnly 쿠키?
+
+| 방식 | XSS 취약 | 토큰 갱신 | SAM 채택 |
+|------|----------|----------|---------|
+| localStorage | **취약** (JS 접근 가능) | 직접 구현 | ❌ |
+| 일반 쿠키 | **취약** (JS 접근 가능) | 직접 구현 | ❌ |
+| **HttpOnly 쿠키** | **안전** (JS 접근 불가) | 프록시에서 처리 | **✅** |
+
+- JavaScript로 토큰을 읽을 수 없음 → XSS 공격에 안전
+- 대신 서버(Next.js 프록시)에서만 읽기 가능 → 프록시 패턴 필수
+
+---
+
+## 3. 로그인 흐름
+
+```
+1. 사용자 → 로그인 폼 입력 (email, password)
+2. 프론트 → POST /api/proxy/auth/login { email, password }
+3. 프록시 → POST /api/v1/auth/login (Laravel)
+4. Laravel → { access_token, refresh_token, expires_in }
+5. 프록시 → Set-Cookie 3개 설정:
+   - access_token=xxx;  HttpOnly; Max-Age=7200
+   - refresh_token=xxx; HttpOnly; Max-Age=604800
+   - is_authenticated=true; Max-Age=7200
+6. 프론트 → 대시보드로 이동
+```
+
+---
+
+## 4. API 호출 시 토큰 흐름
+
+```
+1. 컴포넌트 → Server Action 호출 (또는 fetch /api/proxy/...)
+2. Server Action → serverFetch → authenticatedFetch
+   - 쿠키에서 access_token 읽기
+   - Authorization: Bearer {token} 헤더 추가
+3. 백엔드 응답:
+   - 200 OK → 정상 처리
+   - 401 → 토큰 만료 (아래 갱신 흐름)
+```
+
+---
+
+## 5. 토큰 갱신 (자동)
+
+```
+1. API 호출 → 401 Unauthorized 응답
+2. authenticatedFetch 감지:
+   a. refresh_token으로 POST /api/v1/auth/refresh
+   b. 새 access_token 발급
+   c. 새 토큰으로 원래 요청 재시도 (1회)
+3. 결과:
+   - 재시도 성공 → 정상 응답 + 새 쿠키 설정
+   - 재시도 실패 → 쿠키 삭제 + 로그인 페이지 이동
+```
+
+**중요**: 동시에 여러 요청이 401을 받으면, refresh는 1번만 실행 (globalThis 캐싱으로 중복 방지)
+
+---
+
+## 6. 미들웨어 (middleware.ts)
+
+요청 단계에서의 인증 검사 (토큰 갱신과는 별개):
+
+```
+요청 들어옴
+  ↓
+1. 내부 요청 필터링 (_next/*)
+2. IE 브라우저 차단
+3. 다국어 처리 (ko, en)
+4. /dev/ 경로 프로덕션 차단
+5. 봇 탐지 (40+ 패턴 차단)
+6. API/정적 파일 통과
+7. 인증 확인:
+   - 비인증 사용자 → 로그인 페이지 리다이렉트
+   - 인증된 사용자가 로그인 페이지 접근 → 대시보드 리다이렉트
+8. 보안 헤더 설정 (X-Robots-Tag, CSP 등)
+```
+
+---
+
+## 7. 프론트엔드 개발자 체크리스트
+
+| 항목 | 설명 |
+|------|------|
+| 직접 토큰 관리 금지 | localStorage/sessionStorage에 토큰 저장 ❌ |
+| fetch 직접 호출 금지 | Server Action 또는 `/api/proxy/` 경로만 사용 |
+| 인증 상태 확인 | `is_authenticated` 쿠키 (non-HttpOnly) 또는 useAuthGuard() |
+| 401 처리 | authenticatedFetch가 자동 처리 — 수동 처리 불필요 |
+
+---
+
+## 8. 백엔드 개발자 참고
+
+| 항목 | 내용 |
+|------|------|
+| 인증 방식 | Bearer Token (Authorization 헤더) |
+| 토큰 발급 | POST /api/v1/auth/login |
+| 토큰 갱신 | POST /api/v1/auth/refresh |
+| 401 응답 시 | 프론트가 자동 refresh → retry |
+| API Key | `X-API-KEY` 헤더 (환경변수: `API_KEY`) |

frontend/v1/08-dashboard-system.md

@@ -0,0 +1,183 @@
+# 08. CEO 대시보드 시스템
+
+> **대상**: 프론트엔드/백엔드 개발자
+> **버전**: 1.0.0
+> **최종 수정**: 2026-03-09
+
+---
+
+## 1. 아키텍처 개요
+
+CEO 대시보드는 20개 섹션으로 구성된 실시간 경영 현황 화면.
+
+```
+CEODashboard.tsx
+├── useCEODashboard()           # 12개 섹션 API 통합 Hook
+├── useEntertainment()          # 접대비 독립 Hook
+├── useWelfare()                # 복리후생비 독립 Hook
+├── useTodayIssue()             # 금일 이슈 Hook
+├── useCalendar()               # 캘린더 Hook
+├── useVat()                    # 부가세 Hook
+├── SummaryNavBar               # 섹션 바로가기 네비게이션
+├── DashboardSettingsDialog     # 섹션 표시/순서 설정
+├── DetailModal                 # 상세 모달 (공통)
+└── sections/                   # 20개 섹션 컴포넌트
+    ├── DailyReportSection
+    ├── MonthlyExpenseSection
+    ├── EntertainmentSection
+    ├── WelfareSection
+    └── ... (17개 더)
+```
+
+---
+
+## 2. 섹션 목록
+
+| 섹션 | API Hook | 데이터 소스 |
+|------|----------|------------|
+| 일일일보 | useCEODashboard.dailyReport | sam_stat 캐시 |
+| 현황보드 | useCEODashboard.statusBoard | 실시간 집계 |
+| 당월예상지출 | useCEODashboard.monthlyExpense | 예상경비 테이블 |
+| 카드/가지급금 | useCEODashboard.cardManagement | 가지급금 테이블 |
+| 매출채권 | useCEODashboard.receivable | 매출/입금 |
+| 채권회수 | useCEODashboard.debtCollection | 부실채권 |
+| 매출현황 | useCEODashboard.salesStatus | 매출 통계 |
+| 매입현황 | useCEODashboard.purchaseStatus | 매입 통계 |
+| 일일생산 | useCEODashboard.dailyProduction | 생산실적 |
+| 미출하 | useCEODashboard.unshipped | 출하 대기 |
+| 공사현황 | useCEODashboard.construction | 공사 진행 |
+| 근태현황 | useCEODashboard.dailyAttendance | 근태 데이터 |
+| **접대비** | **useEntertainment()** | **expense_accounts** |
+| **복리후생비** | **useWelfare()** | **expense_accounts** |
+| 금일이슈 | useTodayIssue() | 이슈 목록 |
+| 부가세 | useVat() | 부가세 신고 |
+| 캘린더 | useCalendar() | 일정 |
+| 출하현황 | useCEODashboard.dailyProduction | 출하 실적 |
+
+---
+
+## 3. Invalidation 시스템
+
+다른 화면에서 CUD 발생 시 대시보드 데이터 자동 갱신.
+
+### 흐름
+
+```
+[입금관리에서 입금 등록]
+    ↓
+invalidateDashboard('deposit')
+    ↓
+DOMAIN_SECTION_MAP에서 영향 섹션 조회
+  deposit → ['dailyReport', 'receivable']
+    ↓
+1. sessionStorage에 stale 섹션 저장
+2. CustomEvent 발행
+    ↓
+[대시보드가 마운트 중이면]
+  → 즉시 해당 섹션만 refetch
+[대시보드 비마운트 상태면]
+  → 다음 방문 시 stale 섹션 refetch
+```
+
+### 도메인 → 섹션 매핑
+
+| 도메인 | 영향 섹션 |
+|--------|----------|
+| `deposit` | dailyReport, receivable |
+| `withdrawal` | dailyReport, monthlyExpense |
+| `sales` | dailyReport, salesStatus, receivable |
+| `purchase` | dailyReport, purchaseStatus, monthlyExpense |
+| `badDebt` | debtCollection, receivable |
+| `expectedExpense` | monthlyExpense |
+| `bill` | dailyReport, receivable |
+| `giftCertificate` | entertainment, cardManagement |
+| `journalEntry` | entertainment, welfare, monthlyExpense |
+
+### 사용법 (CUD 완료 후)
+
+```typescript
+import { invalidateDashboard } from '@/lib/dashboard-invalidation';
+
+// 입금 등록 성공 후
+const handleSuccess = () => {
+  loadData();
+  invalidateDashboard('deposit');
+};
+
+// 전표 등록 성공 후
+const handleJournalSuccess = () => {
+  loadData();
+  invalidateDashboard('journalEntry');
+};
+```
+
+### 새 도메인 추가 시
+
+`src/lib/dashboard-invalidation.ts`에서:
+1. `DomainKey`에 새 도메인 추가
+2. `DOMAIN_SECTION_MAP`에 영향 섹션 매핑 추가
+3. 해당 도메인의 CUD 콜백에서 `invalidateDashboard('newDomain')` 호출
+
+---
+
+## 4. 사용자 설정
+
+### 섹션 표시/숨김 + 순서
+
+```typescript
+// localStorage에 저장
+const settings: DashboardSettings = {
+  dailyReport: true,
+  monthlyExpense: true,
+  entertainment: { enabled: true, companyType: 'medium' },
+  welfare: { enabled: true, calculationType: 'monthly' },
+  sectionOrder: ['dailyReport', 'statusBoard', 'monthlyExpense', ...],
+};
+localStorage.setItem('ceo-dashboard-settings', JSON.stringify(settings));
+```
+
+### 순서 변경
+- DashboardSettingsDialog에서 드래그 앤 드롭 또는 순서 변경
+- `sectionOrder` 배열로 관리
+
+---
+
+## 5. expense_accounts 동기화
+
+접대비/복리후생비 대시보드 카드의 데이터 소스는 `expense_accounts` 테이블.
+
+### 현재 동기화 경로
+
+| 입력 경로 | expense_accounts 반영 |
+|----------|----------------------|
+| 일반전표 (수기전표) | **반영됨** — syncExpenseAccounts() |
+| 가지급금 상품권 | **반영됨** — LoanService |
+| 출금관리/카드사용내역 | **확인 중** |
+| 세금계산서 | **확인 중** |
+| 예상경비 | **확인 중** |
+
+### 동기화 원리
+- 전표/거래에서 계정과목명에 "복리후생비" 또는 "접대비"가 포함되면
+- `expense_accounts` 테이블에 자동 INSERT
+- CUD 시 delete-then-insert 전략 (정확한 추적)
+- `journal_entry_id`, `journal_entry_line_id`로 원본 추적 가능
+
+---
+
+## 6. 백엔드 참고
+
+### 대시보드 관련 API
+
+| 엔드포인트 | 용도 |
+|-----------|------|
+| GET /api/v1/daily-report/summary | 일일일보 요약 |
+| GET /api/v1/monthly-expense/summary | 당월 예상 지출 |
+| GET /api/v1/entertainments/summary | 접대비 리스크 카드 |
+| GET /api/v1/welfares/summary | 복리후생비 리스크 카드 |
+| GET /api/v1/card-management/summary | 카드/가지급금 |
+| GET /api/v1/receivable/summary | 매출채권 |
+
+### sam_stat 캐시
+- 일부 대시보드 API는 5분 캐시 (sam_stat 테이블)
+- 실시간이 아닌 근사치 데이터
+- invalidation은 프론트 refetch → 백엔드가 캐시 갱신 여부 판단

frontend/v1/09-conventions.md

@@ -0,0 +1,266 @@
+# 09. 코딩 컨벤션
+
+> **대상**: 프론트엔드 개발자
+> **버전**: 1.0.0
+> **최종 수정**: 2026-03-09
+
+---
+
+## 1. 네이밍 규칙
+
+### 파일/폴더
+
+| 대상 | 규칙 | 예시 |
+|------|------|------|
+| 컴포넌트 파일 | PascalCase | `BillManagement.tsx` |
+| 컴포넌트 폴더 | PascalCase | `BillManagement/` |
+| 유틸리티 | camelCase | `query-params.ts`, `amount.ts` |
+| 타입 파일 | camelCase | `types.ts` |
+| Server Action | camelCase | `actions.ts` |
+| 훅 | camelCase (use 접두사) | `useCEODashboard.ts` |
+| 페이지 라우트 | kebab-case | `general-journal-entry/page.tsx` |
+
+### 변수/함수
+
+| 대상 | 규칙 | 예시 |
+|------|------|------|
+| 컴포넌트 | PascalCase | `function BillManagement()` |
+| 함수 | camelCase | `handleSave`, `loadData` |
+| 이벤트 핸들러 | handle 접두사 | `handleClick`, `handleSubmit` |
+| 콜백 prop | on 접두사 | `onSave`, `onChange` |
+| boolean | is/has/show 접두사 | `isLoading`, `hasError`, `showModal` |
+| 상수 | UPPER_SNAKE_CASE | `PERIOD_BUTTONS`, `TYPE_WELFARE` |
+| 타입/인터페이스 | PascalCase | `BillRecord`, `SearchParams` |
+
+---
+
+## 2. 파일 배치 규칙
+
+### 도메인 컴포넌트 구조
+
+```
+src/components/accounting/BillManagement/
+├── index.tsx          # 메인 컴포넌트 (export)
+├── actions.ts         # Server Actions ('use server')
+├── types.ts           # 타입 정의
+├── BillDetail.tsx     # 하위 컴포넌트
+├── BillForm.tsx       # 폼 컴포넌트
+└── schema.ts          # Zod 스키마 (선택)
+```
+
+### 배치 원칙
+
+| 파일 | 위치 |
+|------|------|
+| 비즈니스 로직 컴포넌트 | `src/components/{domain}/{ComponentName}/` |
+| 공통 UI 컴포넌트 | `src/components/ui/` (shadcn/ui) |
+| 공통 조합 컴포넌트 | `src/components/organisms/` |
+| 도메인 공통 | `src/components/{domain}/common/` |
+| 전체 공통 | `src/components/common/` |
+| API 유틸 | `src/lib/api/` |
+| 범용 유틸 | `src/lib/utils/` |
+| 훅 | `src/hooks/` |
+| 전역 타입 | `src/types/` |
+
+---
+
+## 3. Import 규칙
+
+### 순서
+
+```typescript
+// 1. React/Next.js
+import { useState, useCallback } from 'react';
+import { useRouter } from 'next/navigation';
+
+// 2. 외부 라이브러리
+import { toast } from 'sonner';
+import { z } from 'zod';
+
+// 3. UI 컴포넌트 (@/components/ui)
+import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+
+// 4. 공통 컴포넌트 (@/components/organisms, molecules, atoms)
+import { PageLayout } from '@/components/organisms/PageLayout';
+import { FormField } from '@/components/molecules/FormField';
+
+// 5. 도메인 컴포넌트/액션
+import { getBills } from './actions';
+import { BillDetail } from './BillDetail';
+
+// 6. 유틸/훅/타입
+import { formatNumber } from '@/lib/utils/amount';
+import type { BillRecord } from './types';
+```
+
+### 경로 별칭
+- `@/` = `src/` (tsconfig paths)
+- 항상 `@/` 별칭 사용, 상대 경로(`../../`)는 같은 폴더 내에서만
+
+---
+
+## 4. 컴포넌트 패턴
+
+### 페이지 컴포넌트 (page.tsx)
+
+```typescript
+// 얇은 껍데기만 — 비즈니스 로직은 도메인 컴포넌트에
+'use client';
+import { BillManagement } from '@/components/accounting/BillManagement';
+
+export default function BillsPage() {
+  return <BillManagement />;
+}
+```
+
+### 도메인 컴포넌트 (index.tsx)
+
+```typescript
+'use client';
+
+import { useState, useCallback, useEffect } from 'react';
+// ... imports
+
+export function BillManagement() {
+  // 1. 상태 선언
+  const [data, setData] = useState<BillRecord[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+
+  // 2. 데이터 로드
+  const loadData = useCallback(async () => { ... }, [deps]);
+  useEffect(() => { loadData(); }, [loadData]);
+
+  // 3. 이벤트 핸들러
+  const handleSave = useCallback(async () => { ... }, [deps]);
+  const handleDelete = useCallback(async () => { ... }, [deps]);
+
+  // 4. 계산값 (useMemo)
+  const config = useMemo(() => ({ ... }), [deps]);
+
+  // 5. 렌더링
+  return <UniversalListPage config={config} />;
+}
+```
+
+---
+
+## 5. TypeScript 규칙
+
+### 타입 정의
+
+```typescript
+// ✅ 컴포넌트 props는 interface (확장 가능)
+interface BillDetailProps {
+  record: BillRecord;
+  onSave: (data: BillFormData) => Promise<void>;
+}
+
+// ✅ 데이터 모델은 type (유니온/인터섹션 활용)
+type BillStatus = 'draft' | 'confirmed' | 'paid';
+
+// ✅ API 응답 변환
+interface BillApiResponse { ... }  // 백엔드 스네이크_케이스
+interface BillRecord { ... }       // 프론트 camelCase
+function transformBillApiToFrontend(api: BillApiResponse): BillRecord { ... }
+```
+
+### 금지 패턴
+
+```typescript
+// ❌ any 사용 금지
+const data: any = response;
+
+// ❌ as 캐스트 지양 (Zod 사용 시 불필요)
+const value = input as string;
+
+// ❌ non-null assertion 지양
+const name = user!.name;
+```
+
+---
+
+## 6. 상태 관리 규칙
+
+| 범위 | 방법 |
+|------|------|
+| 컴포넌트 내부 | useState, useReducer |
+| 형제 간 공유 | 부모에서 prop 전달 |
+| 전역 인증 | useAuthGuard (Context) |
+| 서버 데이터 | Server Action + useState |
+| 대시보드 갱신 | dashboard-invalidation (CustomEvent) |
+
+**사용하지 않는 것**: Redux, Zustand, Recoil 등 전역 상태 라이브러리
+
+---
+
+## 7. 에러 처리 규칙
+
+```typescript
+// Server Action 결과 처리
+const result = await saveItem(formData);
+if (result.success) {
+  toast.success('저장되었습니다.');
+  loadData();
+} else {
+  toast.error(result.error || '저장에 실패했습니다.');
+}
+
+// try-catch (Server Action 호출 자체의 에러)
+try {
+  const result = await getItems();
+  if (result.success) setData(result.data);
+} catch {
+  toast.error('서버 오류가 발생했습니다.');
+}
+```
+
+---
+
+## 8. 성능 규칙
+
+| 규칙 | 이유 |
+|------|------|
+| `useMemo`로 config 객체 감싸기 | 불필요한 리렌더 방지 |
+| `useCallback`으로 핸들러 감싸기 | 자식 컴포넌트 리렌더 방지 |
+| 무거운 컴포넌트 `React.memo` | 부모 리렌더 시 불필요한 재계산 방지 |
+| 대시보드 섹션 LazySection | Intersection Observer 기반 지연 로딩 |
+| 이미지 `next/image` 사용 | 자동 최적화 |
+
+---
+
+## 9. Git 커밋 메시지
+
+```
+[타입]: 작업내용 (한글)
+
+타입:
+- feat: 신규 기능
+- fix: 버그 수정
+- refactor: 리팩토링
+- chore: 설정/빌드
+- style: 포맷팅
+- docs: 문서
+```
+
+예시:
+```
+feat: CEO 대시보드 접대비 섹션 API 연동
+fix: 어음관리 날짜 필터 오류 수정
+refactor: 계정과목 설정 모달 공통화
+```
+
+---
+
+## 10. 빠른 참조
+
+| 상황 | 해야 할 것 |
+|------|-----------|
+| 새 리스트 페이지 | UniversalListPage + actions.ts + types.ts |
+| 새 폼 | Zod 스키마 + FormField + react-hook-form |
+| 모달 필요 | SearchableSelectionModal 먼저 확인 |
+| API 호출 | Server Action → buildApiUrl → executeServerAction |
+| 토스트 알림 | `toast.success()` / `toast.error()` |
+| 날짜 입력 | DatePicker (input type="date" 금지) |
+| 대시보드 갱신 | `invalidateDashboard('domain')` |
+| 금액 표시 | `formatNumber()` |