opencode-sa-assistant 0.2.5 → 0.2.7

package/README.md

@@ -17,6 +17,9 @@ This plugin activates when you use the `wadd` keyword in your messages, transfor
 - `sa-researcher`: AWS service information via MCP tools
 - `sa-reviewer`: Well-Architected Framework reviews (6 pillars)
 
+**Orchestrator**:
+- `sa-orchestrator`: Master agent that coordinates Gurus and Specialists based on Guru_Mandate rules
+
 ## Features
 
 ✨ **WADD Mode Activation**: Type `wadd` to activate SA mode  
@@ -26,6 +29,33 @@ This plugin activates when you use the `wadd` keyword in your messages, transfor
 📚 **AWS MCP Tools**: Real-time AWS documentation access  
 🇰🇷 **Bilingual**: Korean prose + English technical terms  
 
+## Agents
+
+### Guru Agents (Philosophy & Strategy)
+
+| Agent | Core Principles | Use When | Avoid When |
+|-------|----------------|----------|------------|
+| **sa-bezos** | Customer Obsession, Day 1, Working Backwards | Customer value definition, Long-term vs short-term decisions, PR/FAQ writing | Pure technical implementation, Cost calculations |
+| **sa-vogels** | Everything Fails, Design for Failure, Loose Coupling | Distributed system design, Scalability/resilience patterns, Operational excellence | Business strategy, Cost ROI analysis |
+| **sa-naval** | Leverage, Asymmetric Outcomes, Compounding | Cost analysis, ROI, Leverage points identification, Complexity removal | Technical architecture details, Customer experience |
+| **sa-feynman** | Feynman Technique, First Principles, Simplicity | Complex concept simplification, Non-technical presentations, Learning materials | Detailed technical decisions, Cost analysis |
+
+### Specialist Agents (Execution)
+
+| Agent | Role | Output |
+|-------|------|--------|
+| **sa-explorer** | Architecture analysis | Component discovery, Dependency mapping, As-Is documentation |
+| **sa-researcher** | AWS information gathering | Service info, Pricing, Best practices with evidence |
+| **sa-reviewer** | Well-Architected review | 6 Pillars evaluation, Risk summary, Prioritized recommendations |
+
+### Orchestrator
+
+**sa-orchestrator** is the master agent that:
+- Classifies user intent (Architecture Review, Service Selection, Cost Analysis, etc.)
+- Invokes appropriate Gurus based on Guru_Mandate rules
+- Delegates tasks to Specialists
+- Enforces anti-patterns (no architecture decisions without Guru consultation)
+
 ## Installation
 
 Add the plugin to your `opencode.json`:
@@ -107,17 +137,18 @@ packages/opencode-sa-assistant/
 ├── src/
 │   ├── index.ts                     # Plugin entry point
 │   ├── hooks/wadd-mode.ts           # WADD keyword detection
-│   ├── prompts/
-│   │   ├── orchestrator.ts          # SA Orchestrator
-│   │   ├── gurus.ts                 # 4 Guru agents
-│   │   └── specialists.ts           # 3 Specialist agents
-│   ├── skills/
-│   │   ├── guru/SKILL.md
-│   │   ├── mcp/SKILL.md
-│   │   ├── docx/SKILL.md
-│   │   └── pptx/SKILL.md
-│   └── __tests__/
-│       └── *.test.ts                # 65 tests
+│   ├── agents/index.ts              # Agent/Skill installation
+│   │   ├── prompts/
+│   │   │   ├── orchestrator.ts          # SA Orchestrator
+│   │   │   ├── gurus.ts                 # 4 Guru agents
+│   │   │   └── specialists.ts           # 3 Specialist agents
+│   │   ├── skills/
+│   │   │   ├── guru/SKILL.md
+│   │   │   ├── mcp/SKILL.md
+│   │   │   ├── docx/SKILL.md
+│   │   │   └── pptx/SKILL.md
+│   │   └── __tests__/
+│   │       └── *.test.ts                # 80 tests
 ├── package.json
 ├── tsconfig.json
 └── bunfig.toml
@@ -151,7 +182,7 @@ The plugin integrates with AWS Documentation MCP for real-time information:
 
 ## License
 
-[Your License Here]
+MIT
 
 ## Author
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-sa-assistant",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "type": "module",
   "main": "src/index.ts",
   "description": "OpenCode plugin for AWS Solutions Architect assistant with multi-agent Guru system",

package/src/prompts/gurus.ts

@@ -331,6 +331,99 @@ Naval Ravikant Thinking Coach - 시스템적 사고 전문가
    - 예: "DynamoDB 튜토리얼 작성"
 </AvoidWhen>
 
+<AWS_Cost_Examples>
+## 📊 AWS 비용 분석 예시 (Naval 관점)
+
+### 1. Reserved Instance vs On-Demand 레버리지 분석
+
+**시나리오**: t3.large 인스턴스 24/7 운영
+\`\`\`
+On-Demand (서울 리전):
+  - $0.1088/시간 × 8,760시간/년 = $953/년
+
+1년 Reserved Instance (All Upfront):
+  - $563/년 (41% 절감)
+  - 레버리지: 선결제 $563 → 절감 $390/년
+  - ROI: 69% (첫 해)
+
+3년 Reserved Instance (All Upfront):
+  - $361/년 ($1,083 선결제)
+  - 레버리지: 선결제 $1,083 → 절감 $1,776 (3년 총)
+  - ROI: 164% (3년 누적)
+\`\`\`
+
+**Naval 원칙 적용**:
+- **레버리지**: 선결제는 시간을 돈으로 교환하는 레버리지
+- **복리 효과**: 3년 RI는 장기 복리 관점에서 최적
+- **리스크 분석**: 인스턴스 타입 변경 가능성 고려 필요
+
+### 2. Serverless vs Container 비용 크로스오버 분석
+
+**시나리오**: API 엔드포인트 비용 비교
+\`\`\`
+Lambda (128MB, 200ms 평균):
+  - 요청당 비용: $0.0000002 + ($0.0000000083 × 200ms) ≈ $0.0000019
+  - 월 100만 요청: $1.90
+  - 월 1억 요청: $190
+
+ECS Fargate (0.25 vCPU, 0.5GB):
+  - 시간당: $0.01234 + $0.00135 = $0.01369
+  - 월 비용: $0.01369 × 730시간 ≈ $10
+
+크로스오버 포인트:
+  - Lambda < Fargate: 약 530만 요청/월 미만
+  - Lambda > Fargate: 약 530만 요청/월 초과
+\`\`\`
+
+**Naval 원칙 적용**:
+- **비대칭 결과**: 트래픽이 불규칙하면 Lambda의 종량제가 유리
+- **레버리지**: 트래픽이 예측 가능하면 Container가 고정비용 레버리지
+- **숨은 비용**: Lambda는 Cold Start, Container는 운영 복잡성
+
+### 3. IaC 자동화 ROI 계산
+
+**시나리오**: 수동 인프라 관리 vs Terraform
+\`\`\`
+수동 관리 비용 (연간):
+  - 인프라 변경 작업: 2시간 × 50회/년 = 100시간
+  - 장애 복구: 4시간 × 10회/년 = 40시간
+  - 문서화/지식 이전: 20시간
+  - 총: 160시간 × $100/시간 = $16,000/년
+
+Terraform 도입 비용:
+  - 초기 구축: 80시간 × $100 = $8,000
+  - 연간 유지: 20시간 × $100 = $2,000
+
+ROI:
+  - 1년차: ($16,000 - $8,000 - $2,000) / $8,000 = 75%
+  - 2년차 이후: ($16,000 - $2,000) / $8,000 = 175%
+  - 복리 효과: 매년 $14,000 절감 (Time to Value 즉시 발생)
+\`\`\`
+
+**Naval 원칙 적용**:
+- **코드 레버리지**: 한 번 작성, 무한 재사용
+- **복리 효과**: 초기 투자 후 매년 비용 절감 누적
+- **시스템 사고**: 운영 효율성 + 장애 감소 + 지식 공유 효과
+
+### 4. 비용 분석 프레임워크
+
+비용 결정 시 다음 질문을 순서대로:
+
+1. **총 비용 vs 가시 비용**
+   - EC2 + EBS + 네트워크 + 데이터 전송 + 관리 시간
+   
+2. **고정비용 vs 변동비용**
+   - 예측 가능한 워크로드 → 고정비용 레버리지
+   - 변동성 높은 워크로드 → 변동비용 유연성
+
+3. **전환 비용 고려**
+   - Lock-in 위험 vs 최적화 이점
+   
+4. **2차 효과**
+   - 선택한 서비스가 팀 역량, 운영 복잡성에 미치는 영향
+
+</AWS_Cost_Examples>
+
 <Thinking Framework>
 ## 레버리지 유형
 - 코드: 한 번 작성, 무한 복제

package/src/prompts/orchestrator.ts

@@ -182,6 +182,86 @@ delegate_task(
 4. **종합 분석** → 모든 Specialist 순차 활용
 </Specialist_Agents>
 
+<Cross_Agent_Communication>
+## 🔄 Cross-Agent Communication Pattern
+
+### Guru 의견 충돌 처리
+
+여러 Guru에게 자문을 구할 때 의견이 충돌할 수 있습니다. 이때의 처리 방법:
+
+#### 1. 의견 충돌 유형
+
+| 충돌 유형 | 예시 | 해결 방법 |
+|----------|------|----------|
+| **관점 차이** | vogels: 확장성 우선 vs naval: 비용 우선 | 트레이드오프 명시 후 사용자 결정 |
+| **접근 방식 차이** | bezos: 고객 경험 vs vogels: 기술 안정성 | 두 관점 모두 존중, 통합 솔루션 제안 |
+| **우선순위 차이** | naval: 단기 ROI vs bezos: 장기 가치 | 시간 프레임별 분석 제공 |
+
+#### 2. 충돌 해결 프로세스
+
+\`\`\`
+Step 1: 각 Guru 의견 요약
+  - vogels: "[요약]"
+  - bezos: "[요약]"
+
+Step 2: 공통점 식별
+  - 두 Guru 모두 동의하는 부분
+
+Step 3: 차이점 명확화
+  - 의견이 다른 부분과 그 이유
+
+Step 4: 통합 권장안
+  - 양쪽 관점을 존중하는 솔루션
+  - 또는 트레이드오프 명시 후 사용자 선택 유도
+\`\`\`
+
+#### 3. 의견 통합 예시
+
+**시나리오**: ECS vs Lambda 선택
+\`\`\`
+vogels 의견: "Lambda는 Cold Start로 latency 변동성이 있다. 
+              일관된 성능이 필요하면 ECS를 추천한다."
+
+naval 의견: "Lambda는 종량제로 트래픽이 불규칙할 때 비용 효율적이다.
+             ECS는 고정비용이므로 지속적 트래픽에 적합하다."
+
+bezos 의견: "고객 경험 관점에서 response time 일관성이 중요하다면 
+             ECS가 맞다. 비용 절감이 고객에게 가치를 줄 수 있다면 Lambda도 고려."
+
+통합 권장안:
+"세 Guru의 관점을 종합하면:
+
+1. **트래픽 패턴이 예측 가능하고 일관된 latency가 중요하다면** → ECS
+   - vogels: 안정적 성능
+   - bezos: 고객 경험 일관성
+   - naval: 고정비용 레버리지
+
+2. **트래픽이 불규칙하고 비용 최적화가 우선이라면** → Lambda
+   - naval: 종량제 효율
+   - bezos: 비용 절감 → 고객 가치
+   - vogels: Provisioned Concurrency로 Cold Start 완화 가능
+
+사용자께서 워크로드 특성을 고려하여 선택해주세요."
+\`\`\`
+
+#### 4. 에스컬레이션 기준
+
+다음 경우 사용자에게 결정을 요청:
+- Guru 간 의견이 정반대이고 통합이 어려울 때
+- 트레이드오프가 명확하고 비즈니스 결정이 필요할 때
+- 추가 정보 없이는 판단이 어려울 때
+
+\`\`\`
+"Guru들의 의견이 다음과 같이 나뉩니다:
+- [옵션 A]: vogels, bezos 추천 - [이유]
+- [옵션 B]: naval 추천 - [이유]
+
+귀하의 비즈니스 맥락에서 어떤 것이 더 중요한지 알려주시면 
+최종 권장안을 드리겠습니다."
+\`\`\`
+
+</Cross_Agent_Communication>
+
 <MCP_Tool_Selection>
 ## 🔧 MCP Tool Selection Guide
 

package/src/prompts/specialists.ts

@@ -100,7 +100,38 @@ Architecture Explorer - 아키텍처 분석 전문가
 - 추측하지 말고 발견한 사실만 보고
 - 불확실한 부분은 명시적으로 표시
 - 간결하고 구조화된 출력
-</Rules>`,
+- **신뢰도 수준 반드시 명시** (아래 가이드 참조)
+</Rules>
+
+<Confidence_Levels>
+## 신뢰도 수준 가이드
+
+분석 결과의 각 항목에 신뢰도 수준을 명시하세요:
+
+| 수준 | 표시 | 기준 | 설명 |
+|-----|------|------|------|
+| **HIGH** | 🟢 | 코드/설정에서 직접 확인 | 파일에서 명시적으로 발견, 확실한 정보 |
+| **MEDIUM** | 🟡 | 추론 기반 (패턴, 명명규칙) | 컨벤션이나 구조에서 추론, 높은 확률 |
+| **LOW** | 🔴 | 간접 증거, 추측 | 부분적 정보, 확인 필요 |
+
+**예시**:
+\`\`\`
+## 발견한 구성요소
+
+- 🟢 Lambda: 3개 함수 발견 (lambda.tf에서 직접 확인)
+- 🟢 DynamoDB: Users 테이블 (dynamodb.tf에서 직접 확인)
+- 🟡 API Gateway: REST API 추정 (Lambda 트리거 설정에서 추론)
+- 🔴 VPC 설정: 미확인 (관련 파일 없음, 확인 필요)
+
+## 연결 관계
+
+- 🟢 Lambda → DynamoDB (IAM 정책에서 명시적 권한 확인)
+- 🟡 API Gateway → Lambda (Lambda 트리거 설정에서 추론)
+- 🔴 External → API Gateway (인그레스 설정 미확인)
+\`\`\`
+
+**원칙**: 불확실한 정보는 LOW로 표시하고 확인 필요 사항에 포함
+</Confidence_Levels>`,
 
   researcher: `<Role>
 AWS Researcher - AWS 정보 수집 전문가
@@ -366,5 +397,65 @@ Architecture Reviewer - Well-Architected 검토 전문가
 - 비판보다 개선 방향 제시
 - 우선순위를 명확히 제공
 - AWS 표준 및 모범 사례 기준
-</Rules>`,
+- **Pillar 간 트레이드오프 명시** (아래 가이드 참조)
+</Rules>
+
+<Pillar_Tradeoffs>
+## Pillar 간 트레이드오프 가이드
+
+Well-Architected 6개 Pillar는 서로 충돌할 수 있습니다. 검토 시 트레이드오프를 명시하세요:
+
+### 일반적인 트레이드오프 패턴
+
+| 충돌 | 상황 | 권장 접근 |
+|-----|------|----------|
+| **보안 vs 성능** | 암호화/인증 오버헤드 | 보안 우선, 성능은 캐싱으로 보완 |
+| **안정성 vs 비용** | 다중 AZ, 복제본 | 비즈니스 중요도에 따라 결정 |
+| **성능 vs 비용** | 오버 프로비저닝 | 오토스케일링으로 균형 |
+| **운영우수성 vs 비용** | 모니터링/로깅 비용 | 필수 메트릭만 선별, 단계적 확대 |
+| **지속가능성 vs 성능** | 리소스 최적화 | Graviton, 적정 사이징으로 양립 |
+
+### 트레이드오프 분석 예시
+
+\`\`\`
+## 발견된 트레이드오프
+
+### 1. 보안 ↔ 비용
+현재: API Gateway에 WAF 미적용
+- 보안 관점: 🔴 DDoS, SQL Injection 취약
+- 비용 관점: ✅ WAF 비용 절감 ($5/월 + 요청당)
+
+**권장**: WAF 적용 (보안 > 비용)
+  - 이유: 보안 사고 비용이 WAF 비용보다 큼
+  - 대안: AWS Shield Standard (무료) 활용
+
+### 2. 안정성 ↔ 비용  
+현재: 단일 AZ RDS 배포
+- 안정성 관점: 🔴 AZ 장애 시 서비스 중단
+- 비용 관점: ✅ Multi-AZ 대비 50% 절감
+
+**권장**: 비즈니스 중요도에 따라 결정
+  - 중요 서비스: Multi-AZ 필수
+  - 개발/테스트: 단일 AZ 허용
+  - 타협안: 읽기 복제본만 다른 AZ에 배치
+
+### 3. 성능 ↔ 비용
+현재: DynamoDB Provisioned 모드 (과다 프로비저닝)
+- 성능 관점: ✅ 일관된 latency, 용량 보장
+- 비용 관점: ⚠️ 사용량 대비 70% 초과 프로비저닝
+
+**권장**: On-Demand 또는 Auto Scaling 검토
+  - 워크로드 패턴 분석 후 결정
+  - 예측 가능: Provisioned + Auto Scaling
+  - 변동성 큼: On-Demand
+\`\`\`
+
+### 트레이드오프 의사결정 원칙
+
+1. **보안은 항상 최우선** - 다른 pillar와 충돌 시 보안 우선
+2. **비용은 마지막 고려** - 먼저 요구사항 충족, 이후 비용 최적화
+3. **비즈니스 맥락 고려** - 스타트업 vs 엔터프라이즈 기준 다름
+4. **타협안 제시** - 양자택일보다 균형점 찾기
+
+</Pillar_Tradeoffs>`,
 };

package/src/skills/docx/SKILL.md

@@ -272,6 +272,218 @@ new Paragraph({
 })
 ```
 
+### 이미지 비율 유지 삽입
+
+이미지 원본 비율을 유지하면서 삽입하려면 `image-size` 패키지를 사용합니다.
+
+```javascript
+const sizeOf = require('image-size');
+
+function createImageWithAspectRatio(imagePath, maxWidth = 500) {
+  const dimensions = sizeOf(imagePath);
+  const ratio = dimensions.height / dimensions.width;
+  const displayWidth = Math.min(maxWidth, dimensions.width);
+  const displayHeight = Math.round(displayWidth * ratio);
+  
+  return new Paragraph({
+    alignment: AlignmentType.CENTER,
+    children: [new ImageRun({
+      type: imagePath.endsWith('.png') ? 'png' : 'jpg',
+      data: fs.readFileSync(imagePath),
+      transformation: { width: displayWidth, height: displayHeight }
+    })]
+  });
+}
+
+// 사용 예시
+createImageWithAspectRatio('diagrams/architecture.png', 500)
+```
+
+## 다이어그램 삽입
+
+### Mermaid 다이어그램을 이미지로 변환
+
+Word 문서에서 Mermaid 다이어그램을 표시하려면 먼저 이미지로 변환해야 합니다.
+
+#### 1. Mermaid CLI 설치
+
+```bash
+npm install @mermaid-js/mermaid-cli
+```
+
+#### 2. .mmd 파일 작성
+
+```mermaid
+graph TB
+    Client[Client] --> ALB[Application Load Balancer]
+    ALB --> Lambda[AWS Lambda]
+    Lambda --> DynamoDB[(DynamoDB)]
+```
+
+#### 3. 이미지로 변환
+
+```bash
+npx mmdc -i diagram.mmd -o diagram.png -w 800 -b white
+```
+
+#### 4. 비율 유지하여 삽입
+
+```javascript
+const sizeOf = require('image-size');
+
+function insertMermaidDiagram(mmdPath, outputPngPath, maxWidth = 500) {
+  // 1. Mermaid → PNG 변환 (사전 실행 필요)
+  // npx mmdc -i ${mmdPath} -o ${outputPngPath} -w 800 -b white
+  
+  // 2. 이미지 크기 확인 및 비율 계산
+  const dimensions = sizeOf(outputPngPath);
+  const ratio = dimensions.height / dimensions.width;
+  const displayHeight = Math.round(maxWidth * ratio);
+  
+  return new Paragraph({
+    alignment: AlignmentType.CENTER,
+    children: [new ImageRun({
+      type: "png",
+      data: fs.readFileSync(outputPngPath),
+      transformation: { width: maxWidth, height: displayHeight }
+    })]
+  });
+}
+```
+
+## 코드 블록 (멀티라인)
+
+**중요**: Word에서는 `\n` 문자가 제대로 렌더링되지 않습니다. 각 줄을 별도 Paragraph로 분리해야 합니다.
+
+### 잘못된 방식 (동작 안함)
+
+```javascript
+// ❌ 이 방식은 줄바꿈이 무시됨
+new Paragraph({
+  children: [new TextRun({ text: "line1\nline2\nline3" })]
+})
+```
+
+### 올바른 방식
+
+```javascript
+// ✅ 각 줄을 별도 Paragraph로 분리
+function createCodeBlock(codeLines) {
+  const lines = Array.isArray(codeLines) ? codeLines : codeLines.split('\n');
+  return lines.map((line, index) => 
+    new Paragraph({
+      shading: { fill: "F5F5F5", type: ShadingType.CLEAR },
+      spacing: { 
+        before: index === 0 ? 120 : 0, 
+        after: index === lines.length - 1 ? 120 : 0 
+      },
+      indent: { left: 360 },
+      children: [new TextRun({ 
+        text: line || " ",  // 빈 줄은 공백으로
+        font: "Courier New", 
+        size: 18 
+      })]
+    })
+  );
+}
+
+// 사용 예시 - 배열로 전달
+...createCodeBlock([
+  "{",
+  "    \"key\": \"value\",",
+  "    \"nested\": {",
+  "        \"item\": 123",
+  "    }",
+  "}"
+])
+
+// 또는 문자열로 전달
+...createCodeBlock(`function hello() {
+    console.log("Hello, World!");
+}`)
+```
+
+## Pretty JSON 표현
+
+JSON 데이터를 가독성 좋게 표현하는 헬퍼 함수:
+
+```javascript
+function jsonToCodeBlock(jsonObject, indent = 4) {
+  const prettyJson = JSON.stringify(jsonObject, null, indent);
+  return createCodeBlock(prettyJson.split('\n'));
+}
+
+// 사용 예시
+const apiResponse = {
+  userId: "user_abc123",
+  metadata: {
+    model: "claude-3-haiku",
+    tokens: 150
+  }
+};
+
+// 문서에 추가
+...jsonToCodeBlock(apiResponse)
+```
+
+## 테이블 열 너비 조정
+
+### 퍼센트 기반 열 너비 지정
+
+```javascript
+function createTableWithWidths(headers, rows, widthPercents) {
+  const totalWidth = 9360; // DXA 단위 (약 6.5인치, 일반적인 본문 너비)
+  const colWidths = widthPercents.map(p => Math.floor(totalWidth * p / 100));
+  
+  const tableBorder = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
+  const cellBorders = { top: tableBorder, bottom: tableBorder, left: tableBorder, right: tableBorder };
+  
+  // 헤더 행 생성
+  const headerRow = new TableRow({
+    tableHeader: true,
+    children: headers.map((header, i) => 
+      new TableCell({
+        width: { size: colWidths[i], type: WidthType.DXA },
+        borders: cellBorders,
+        shading: { fill: "232F3E", type: ShadingType.CLEAR },
+        children: [new Paragraph({
+          children: [new TextRun({ text: header, bold: true, color: "FFFFFF" })]
+        })]
+      })
+    )
+  });
+  
+  // 데이터 행 생성
+  const dataRows = rows.map(row => 
+    new TableRow({
+      children: row.map((cell, i) => 
+        new TableCell({
+          width: { size: colWidths[i], type: WidthType.DXA },
+          borders: cellBorders,
+          children: [new Paragraph({ children: [new TextRun(cell)] })]
+        })
+      )
+    })
+  );
+  
+  return new Table({
+    columnWidths: colWidths,
+    rows: [headerRow, ...dataRows]
+  });
+}
+
+// 사용 예시: 합이 100%가 되도록 지정
+createTableWithWidths(
+  ["모델", "Input 비용", "Output 비용"],
+  [
+    ["Claude 3 Haiku", "$0.25/1M", "$1.25/1M"],
+    ["Claude 3 Sonnet", "$3.00/1M", "$15.00/1M"],
+    ["Claude 3 Opus", "$15.00/1M", "$75.00/1M"]
+  ],
+  [40, 30, 30]  // 40% + 30% + 30% = 100%
+)
+```
+
 ## AWS Blog 스타일 가이드
 
 ### 작성 원칙
@@ -305,3 +517,324 @@ new Paragraph({
 필수 의존성:
 - **docx**: `npm install docx` (문서 생성)
 - **sharp**: `npm install sharp` (이미지 처리)
+- **image-size**: `npm install image-size` (이미지 크기 확인)
+- **@mermaid-js/mermaid-cli**: `npm install @mermaid-js/mermaid-cli` (다이어그램 렌더링)
+
+---
+
+## Header/Footer 설정
+
+### 기본 Header 추가
+
+```javascript
+const { Document, Header, Footer, Paragraph, TextRun, AlignmentType, 
+        PageNumber, NumberFormat } = require('docx');
+
+const doc = new Document({
+  sections: [{
+    properties: {
+      page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } }
+    },
+    headers: {
+      default: new Header({
+        children: [
+          new Paragraph({
+            alignment: AlignmentType.RIGHT,
+            children: [
+              new TextRun({ 
+                text: "AWS Solutions Architecture Guide", 
+                size: 18, 
+                color: "545B64" 
+              })
+            ]
+          })
+        ]
+      })
+    },
+    children: [/* 본문 내용 */]
+  }]
+});
+```
+
+### Header with Logo
+
+```javascript
+const header = new Header({
+  children: [
+    new Paragraph({
+      alignment: AlignmentType.LEFT,
+      children: [
+        new ImageRun({
+          type: "png",
+          data: fs.readFileSync("aws-logo.png"),
+          transformation: { width: 80, height: 30 }
+        }),
+        new TextRun({ text: "    " }),  // 간격
+        new TextRun({ 
+          text: "Architecture Guide", 
+          size: 20, 
+          color: "232F3E" 
+        })
+      ]
+    })
+  ]
+});
+```
+
+### Footer with Page Numbers
+
+```javascript
+const footer = new Footer({
+  children: [
+    new Paragraph({
+      alignment: AlignmentType.CENTER,
+      children: [
+        new TextRun({ text: "Page ", size: 18 }),
+        new TextRun({ 
+          children: [PageNumber.CURRENT] 
+        }),
+        new TextRun({ text: " of ", size: 18 }),
+        new TextRun({ 
+          children: [PageNumber.TOTAL_PAGES] 
+        })
+      ]
+    })
+  ]
+});
+
+// 섹션에 적용
+const doc = new Document({
+  sections: [{
+    properties: {},
+    headers: { default: header },
+    footers: { default: footer },
+    children: [/* 본문 */]
+  }]
+});
+```
+
+### First Page Different Header
+
+```javascript
+const doc = new Document({
+  sections: [{
+    properties: {
+      titlePage: true  // 첫 페이지 다른 header/footer 사용
+    },
+    headers: {
+      first: new Header({  // 첫 페이지용
+        children: [new Paragraph({ children: [new TextRun("")] })]  // 비움
+      }),
+      default: new Header({  // 나머지 페이지용
+        children: [
+          new Paragraph({
+            alignment: AlignmentType.RIGHT,
+            children: [new TextRun({ text: "AWS Guide", size: 18 })]
+          })
+        ]
+      })
+    },
+    footers: {
+      first: new Footer({
+        children: [new Paragraph({ children: [new TextRun("")] })]
+      }),
+      default: new Footer({
+        children: [/* 페이지 번호 */]
+      })
+    },
+    children: [/* 본문 */]
+  }]
+});
+```
+
+---
+
+## Table of Contents (목차)
+
+### 자동 목차 생성
+
+docx-js에서 자동 목차(TOC)를 생성하려면 `TableOfContents` 클래스를 사용합니다.
+목차는 Heading 스타일이 적용된 텍스트를 자동으로 수집합니다.
+
+```javascript
+const { Document, TableOfContents, Paragraph, TextRun, 
+        HeadingLevel, StyleLevel } = require('docx');
+
+const doc = new Document({
+  features: {
+    updateFields: true  // Word에서 열 때 목차 자동 업데이트
+  },
+  sections: [{
+    children: [
+      // 목차 제목
+      new Paragraph({
+        heading: HeadingLevel.HEADING_1,
+        children: [new TextRun("목차")]
+      }),
+      
+      // 자동 목차
+      new TableOfContents("Table of Contents", {
+        hyperlink: true,
+        headingStyleRange: "1-3",  // Heading 1~3까지 포함
+        stylesWithLevels: [
+          new StyleLevel("Heading1", 1),
+          new StyleLevel("Heading2", 2),
+          new StyleLevel("Heading3", 3)
+        ]
+      }),
+      
+      // 페이지 나누기
+      new Paragraph({ pageBreakBefore: true }),
+      
+      // 본문 시작
+      new Paragraph({
+        heading: HeadingLevel.HEADING_1,
+        children: [new TextRun("1. 개요")]
+      }),
+      new Paragraph({
+        children: [new TextRun("이 문서는...")]
+      }),
+      
+      new Paragraph({
+        heading: HeadingLevel.HEADING_2,
+        children: [new TextRun("1.1 배경")]
+      }),
+      // ...
+    ]
+  }]
+});
+```
+
+### 목차 업데이트 안내
+
+**중요**: docx-js로 생성된 목차는 Word에서 문서를 열 때 업데이트됩니다.
+- `updateFields: true` 설정 시 Word가 자동으로 업데이트 여부 묻기
+- 수동 업데이트: Word에서 목차 선택 → 마우스 오른쪽 클릭 → "필드 업데이트"
+
+### 수동 목차 생성 (대안)
+
+자동 목차가 작동하지 않을 경우, 수동으로 목차를 생성할 수 있습니다:
+
+```javascript
+function createManualTOC(sections) {
+  // sections: [{ title: "1. 개요", level: 1 }, { title: "1.1 배경", level: 2 }]
+  return sections.map(section => {
+    const indent = (section.level - 1) * 360;  // 레벨별 들여쓰기
+    return new Paragraph({
+      indent: { left: indent },
+      children: [
+        new TextRun({
+          text: section.title,
+          size: section.level === 1 ? 24 : 22
+        })
+      ]
+    });
+  });
+}
+
+// 사용 예시
+const tocItems = [
+  { title: "1. 개요", level: 1 },
+  { title: "  1.1 배경", level: 2 },
+  { title: "  1.2 목적", level: 2 },
+  { title: "2. 아키텍처", level: 1 },
+  { title: "  2.1 구성요소", level: 2 }
+];
+
+const tocParagraphs = createManualTOC(tocItems);
+```
+
+---
+
+## 완전한 문서 템플릿 예시
+
+```javascript
+const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell,
+        Header, Footer, ImageRun, TableOfContents, StyleLevel,
+        HeadingLevel, AlignmentType, PageNumber, BorderStyle } = require('docx');
+const fs = require('fs');
+
+// AWS 스타일 문서 생성 함수
+function createAWSDocument(title, sections) {
+  return new Document({
+    features: { updateFields: true },
+    styles: {
+      paragraphStyles: [
+        {
+          id: "Title",
+          name: "Title",
+          run: { size: 56, bold: true, color: "232F3E" },
+          paragraph: { spacing: { after: 200 }, alignment: AlignmentType.CENTER }
+        }
+      ]
+    },
+    sections: [{
+      properties: { titlePage: true },
+      headers: {
+        first: new Header({ children: [new Paragraph("")] }),
+        default: new Header({
+          children: [
+            new Paragraph({
+              alignment: AlignmentType.RIGHT,
+              children: [new TextRun({ text: title, size: 18, color: "545B64" })]
+            })
+          ]
+        })
+      },
+      footers: {
+        first: new Footer({ children: [new Paragraph("")] }),
+        default: new Footer({
+          children: [
+            new Paragraph({
+              alignment: AlignmentType.CENTER,
+              children: [
+                new TextRun({ text: "Page " }),
+                new TextRun({ children: [PageNumber.CURRENT] }),
+                new TextRun({ text: " of " }),
+                new TextRun({ children: [PageNumber.TOTAL_PAGES] })
+              ]
+            })
+          ]
+        })
+      },
+      children: [
+        // 표지
+        new Paragraph({
+          style: "Title",
+          children: [new TextRun(title)]
+        }),
+        new Paragraph({ pageBreakBefore: true }),
+        
+        // 목차
+        new Paragraph({
+          heading: HeadingLevel.HEADING_1,
+          children: [new TextRun("목차")]
+        }),
+        new TableOfContents("TOC", {
+          hyperlink: true,
+          headingStyleRange: "1-3"
+        }),
+        new Paragraph({ pageBreakBefore: true }),
+        
+        // 본문 섹션들
+        ...sections
+      ]
+    }]
+  });
+}
+
+// 사용 예시
+const doc = createAWSDocument("AWS Lambda 아키텍처 가이드", [
+  new Paragraph({
+    heading: HeadingLevel.HEADING_1,
+    children: [new TextRun("1. 개요")]
+  }),
+  new Paragraph({
+    children: [new TextRun("이 문서는 AWS Lambda를 활용한 서버리스 아키텍처를 설명합니다.")]
+  })
+]);
+
+Packer.toBuffer(doc).then(buffer => {
+  fs.writeFileSync("aws-lambda-guide.docx", buffer);
+});
+```

package/src/skills/mcp/SKILL.md

@@ -34,6 +34,30 @@ AWS 문서를 검색합니다.
 **파라미터:**
 - `url`: 문서 URL (필수)
 
+#### recommend
+현재 문서와 관련된 AWS 문서를 추천합니다.
+
+**파라미터:**
+- `url`: 현재 조회 중인 문서 URL (필수)
+
+**반환:**
+- Highly Rated: 해당 서비스 내 인기 문서
+- New: 최근 추가된 문서 (새 기능 발견에 유용)
+- Similar: 유사 주제 문서
+- Journey: 다른 사용자들이 다음에 본 문서
+
+**사용 예시:**
+```
+// Lambda 문서를 읽은 후 관련 문서 추천
+aws-docs_recommend({
+  url: "https://docs.aws.amazon.com/lambda/latest/dg/welcome.html"
+})
+// → "Highly Rated": Lambda 모범 사례
+// → "New": 최근 추가된 Lambda 기능
+// → "Similar": Step Functions, EventBridge 문서
+// → "Journey": Lambda 권한, 배포 관련 문서
+```
+
 ### 사용 시점
 - 서비스 기능 및 제한사항 확인
 - Best Practice 및 권장사항 조회
@@ -168,3 +192,111 @@ AWS Well-Architected Framework 보안 관련 정보를 제공합니다.
 | Amazon ECS | AmazonECS |
 | Amazon VPC | AmazonVPC |
 | AWS Fargate | AWSFargate |
+
+---
+
+## 에러 핸들링 전략
+
+### 일반 에러 유형
+
+| 에러 유형 | 원인 | 해결 방법 |
+|----------|------|----------|
+| **Timeout** | 요청 시간 초과 | 재시도 또는 쿼리 단순화 |
+| **Rate Limit** | 요청 빈도 초과 | 지수 백오프 후 재시도 |
+| **Not Found** | 문서/서비스 없음 | 검색어 변경, 유사 서비스 탐색 |
+| **Access Denied** | 권한 부족 | 일반 지식으로 대체, 제한사항 명시 |
+| **Service Unavailable** | MCP 서버 다운 | 대체 도구 사용, 캐시된 정보 활용 |
+
+### Resilience 전략 (도구 실패 시)
+
+```
+1단계: 동일 도구 재시도 (1회)
+  └── 검색어/파라미터 조정하여 재시도
+
+2단계: 대체 도구 사용
+  └── search_documentation → read_documentation (URL 직접 접근)
+  └── get_pricing → search_documentation ("pricing" 검색)
+
+3단계: 일반 지식 활용
+  └── MCP 없이 기존 지식으로 답변
+  └── 반드시 출처 제한사항 명시
+
+4단계: 부분 성공 보고
+  └── 성공한 정보 + 실패한 부분 안내
+  └── 추가 확인 필요한 항목 목록
+```
+
+### 에러별 상세 대응
+
+#### search_documentation 실패
+
+```
+원인: 검색어가 너무 일반적이거나 구체적임
+
+대응 순서:
+1. 검색어 변형 (동의어, 약어 추가/제거)
+   - "Lambda pricing" → "AWS Lambda cost"
+   - "EC2 instance types" → "Amazon EC2 instance families"
+
+2. 범위 축소/확대
+   - "S3 security best practices" → "S3 bucket policy"
+   - "DynamoDB" → "Amazon DynamoDB capacity modes"
+
+3. read_documentation으로 대체 (알려진 URL 직접 접근)
+   - https://docs.aws.amazon.com/lambda/latest/dg/welcome.html
+   - https://aws.amazon.com/lambda/pricing/
+```
+
+#### get_pricing 실패
+
+```
+원인: 서비스 코드 오류, 리전 지원 안함
+
+대응 순서:
+1. 서비스 코드 확인 (위의 서비스 코드 참조 테이블)
+   - "Lambda" → "AWSLambda"
+   - "EC2" → "AmazonEC2"
+
+2. 리전 파라미터 제거 (기본 리전으로 조회)
+
+3. search_documentation으로 가격 페이지 검색
+   - "AWS Lambda pricing"
+   - "Amazon EC2 on-demand pricing"
+
+4. 공식 가격 페이지 URL 안내
+   - https://aws.amazon.com/lambda/pricing/
+   - https://aws.amazon.com/ec2/pricing/
+```
+
+#### Well-Architected Security MCP 실패
+
+```
+원인: 카테고리 미지원, 아키텍처 설명 불충분
+
+대응 순서:
+1. 카테고리 명시적 지정
+   - "identity", "detection", "infrastructure", "data", "incident"
+
+2. 아키텍처 설명 보강
+   - 서비스 목록, 데이터 흐름, 네트워크 구성 추가
+
+3. AWS Well-Architected Tool 문서 직접 참조
+   - search_documentation("Well-Architected security pillar")
+```
+
+### 사용자 커뮤니케이션
+
+MCP 도구 실패 시 사용자에게 알리는 방법:
+
+```
+✅ 좋은 예:
+"AWS Lambda 가격 정보를 MCP로 조회했으나 현재 서비스가 응답하지 않습니다.
+ 일반적인 가격 정보를 안내드리며, 정확한 최신 가격은 
+ https://aws.amazon.com/lambda/pricing/ 에서 확인해주세요."
+
+❌ 나쁜 예:
+"MCP 도구 에러가 발생했습니다."
+"가격 정보를 가져올 수 없습니다."
+```
+
+**원칙**: 에러 메시지보다 해결책과 대안을 제시하세요.

package/src/skills/pptx/SKILL.md

@@ -16,7 +16,6 @@ A user may ask you to create, edit, or analyze the contents of a .pptx file. A .
 If you just need to read the text contents of a presentation, you should convert the document to markdown:
 
 ```bash
-# Convert document to markdown
 python -m markitdown path-to-file.pptx
 ```
 
@@ -24,7 +23,9 @@ python -m markitdown path-to-file.pptx
 You need raw XML access for: comments, speaker notes, slide layouts, animations, design elements, and complex formatting. For any of these features, you'll need to unpack a presentation and read its raw XML contents.
 
 #### Unpacking a file
-`python ooxml/scripts/unpack.py <office_file> <output_dir>`
+```bash
+python scripts/ooxml/unpack.py <office_file> <output_dir>
+```
 
 #### Key file structures
 * `ppt/presentation.xml` - Main presentation metadata and slide references
@@ -40,6 +41,36 @@ You need raw XML access for: comments, speaker notes, slide layouts, animations,
 
 When creating a new PowerPoint presentation from scratch, use the **html2pptx** workflow to convert HTML slides to PowerPoint with accurate positioning.
 
+### Layout Initialization (MANDATORY)
+
+**CRITICAL**: Always define layout constants BEFORE creating slides. Different layouts have different dimensions:
+
+| Layout | Width | Height | Use Case |
+|--------|-------|--------|----------|
+| `LAYOUT_16x9` | 10" | 5.625" | Standard widescreen |
+| `LAYOUT_WIDE` | 13.33" | 7.5" | Extra wide presentations |
+| `LAYOUT_4x3` | 10" | 7.5" | Legacy/square displays |
+
+```javascript
+const LAYOUT_NAME = 'LAYOUT_WIDE';
+const SLIDE = { width: 13.33, height: 7.5 };
+const MARGIN = 0.5;
+const CONTENT = {
+  width: SLIDE.width - (2 * MARGIN),
+  height: SLIDE.height - (2 * MARGIN)
+};
+
+let pptx = new PptxGenJS();
+pptx.layout = LAYOUT_NAME;
+
+slide.addText('Title', {
+  x: MARGIN,
+  y: MARGIN,
+  w: CONTENT.width,
+  h: 0.8
+});
+```
+
 ### Design Principles
 
 **CRITICAL**: Before creating any presentation, analyze the content and choose appropriate design elements:
@@ -73,31 +104,62 @@ AWS 브랜드 색상 팔레트, 표준 슬라이드 구성, HTML 템플릿 예
 When editing slides in an existing PowerPoint presentation, you need to work with the raw Office Open XML (OOXML) format.
 
 ### Workflow
-1. Unpack the presentation: `python ooxml/scripts/unpack.py <office_file> <output_dir>`
+1. Unpack the presentation: `python scripts/ooxml/unpack.py <office_file> <output_dir>`
 2. Edit the XML files (primarily `ppt/slides/slide{N}.xml` and related files)
 3. **CRITICAL**: Validate immediately after each edit
-4. Pack the final presentation: `python ooxml/scripts/pack.py <input_directory> <office_file>`
+4. Pack the final presentation: `python scripts/ooxml/pack.py <input_directory> <office_file>`
 
 ## Creating a new PowerPoint presentation **using a template**
 
 When you need to create a presentation that follows an existing template's design:
 
+### Template Workflow Scripts
+
+All scripts are located in the `scripts/` directory of this skill.
+
+| Script | Command | Purpose |
+|--------|---------|---------|
+| `thumbnail.py` | `python scripts/thumbnail.py template.pptx` | Generate slide thumbnails for visual inspection |
+| `inventory.py` | `python scripts/inventory.py template.pptx -o inventory.json` | Extract all text elements with shape IDs |
+| `replace.py` | `python scripts/replace.py template.pptx mapping.json -o output.pptx` | Replace text using JSON mapping |
+| `rearrange.py` | `python scripts/rearrange.py template.pptx operations.json -o output.pptx` | Duplicate/delete/reorder slides |
+
 ### Workflow
+
 1. **Extract template text AND create visual thumbnail grid**:
-   * Extract text: `python -m markitdown template.pptx > template-content.md`
-   * Create thumbnail grids: `python scripts/thumbnail.py template.pptx`
+```bash
+python -m markitdown template.pptx > template-content.md
+python scripts/thumbnail.py template.pptx --output-dir ./thumbs
+```
 
-2. **Analyze template and save inventory to a file**
+2. **Extract text inventory** (get shape IDs and text content):
+```bash
+python scripts/inventory.py template.pptx -o inventory.json
+```
 
 3. **Create presentation outline based on template inventory**
 
-4. **Duplicate, reorder, and delete slides using `rearrange.py`**
-
-5. **Extract ALL text using the `inventory.py` script**
+4. **Duplicate, reorder, and delete slides**:
+```bash
+# Create operations.json:
+# {"operations": [{"action": "duplicate", "slide": 1, "count": 3}, {"action": "delete", "slides": [5, 6]}]}
+python scripts/rearrange.py template.pptx operations.json -o structured.pptx
+```
 
-6. **Generate replacement text and save the data to a JSON file**
+5. **Generate replacement mapping** and save to JSON:
+```json
+{
+  "replacements": [
+    {"from": "Template Title", "to": "My Presentation"},
+    {"from": "Placeholder Text", "to": "Actual Content"}
+  ]
+}
+```
 
-7. **Apply replacements using the `replace.py` script**
+6. **Apply replacements**:
+```bash
+python scripts/replace.py structured.pptx mapping.json -o final.pptx
+```
 
 ## Dependencies
 
@@ -106,5 +168,5 @@ Required dependencies:
 - **pptxgenjs**: `npm install -g pptxgenjs` (for creating presentations)
 - **playwright**: `npm install -g playwright` (for HTML rendering)
 - **sharp**: `npm install -g sharp` (for SVG rasterization)
-- **LibreOffice**: For PDF conversion
-- **Poppler**: For pdftoppm
+- **LibreOffice**: For PDF conversion (thumbnail generation)
+- **Poppler**: For pdftoppm (thumbnail generation)

package/src/skills/pptx/references/html2pptx.md

@@ -0,0 +1,191 @@
+# 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**
+
+**NEVER use manual bullet symbols (•, -, *, etc.)** - Use `<ul>` or `<ol>` lists instead
+
+**ONLY use web-safe fonts:**
+- ✅ Web-safe: `Arial`, `Helvetica`, `Times New Roman`, `Georgia`, `Courier New`, `Verdana`, `Tahoma`, `Trebuchet MS`, `Impact`
+- ❌ Wrong: `'Segoe UI'`, `'SF Pro'`, `'Roboto'`, custom fonts
+
+### Styling
+
+- Use `display: flex` on body to prevent margin collapse
+- Use `margin` for spacing (padding included in size)
+- Flexbox works - positions calculated from rendered layout
+- Use hex colors with `#` prefix in CSS
+
+### Shape Styling (DIV elements only)
+
+**IMPORTANT: Backgrounds, borders, and shadows only work on `<div>` elements, NOT on text elements**
+
+- **Backgrounds**: CSS `background` or `background-color` on `<div>` elements only
+- **Borders**: CSS `border` on `<div>` elements converts to PowerPoint shape borders
+- **Border radius**: CSS `border-radius` on `<div>` elements for rounded corners
+- **Box shadows**: CSS `box-shadow` on `<div>` elements (outer shadows only)
+
+### Icons & Gradients
+
+- **CRITICAL: Never use CSS gradients** - They don't convert to PowerPoint
+- **ALWAYS create gradient/icon PNGs FIRST using Sharp, then reference in HTML**
+
+**Rasterizing Icons with Sharp:**
+
+```javascript
+const sharp = require('sharp');
+const { FaHome } = require('react-icons/fa');
+
+async function rasterizeIconPng(IconComponent, color, size, filename) {
+  const svgString = ReactDOMServer.renderToStaticMarkup(
+    React.createElement(IconComponent, { color: `#${color}`, size: size })
+  );
+  await sharp(Buffer.from(svgString)).png().toFile(filename);
+  return filename;
+}
+```
+
+### Example HTML Slide
+
+```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; }
+</style>
+</head>
+<body>
+<div class="content">
+  <h1>Title</h1>
+  <ul>
+    <li><b>Item:</b> Description</li>
+  </ul>
+  <div id="chart" class="placeholder" style="width: 350pt; height: 200pt;"></div>
+</div>
+</body>
+</html>
+```
+
+## Using the html2pptx Library
+
+### Basic Usage
+
+```javascript
+const pptxgen = require('pptxgenjs');
+const html2pptx = require('./html2pptx');
+
+const pptx = new pptxgen();
+pptx.layout = 'LAYOUT_16x9';
+
+const { slide, placeholders } = await html2pptx('slide1.html', pptx);
+
+if (placeholders.length > 0) {
+    slide.addChart(pptx.charts.LINE, chartData, placeholders[0]);
+}
+
+await pptx.writeFile('output.pptx');
+```
+
+### API Reference
+
+```javascript
+await html2pptx(htmlFile, pres, options)
+// Returns: { slide, placeholders: [{ id, x, y, w, h }] }
+```
+
+## Using PptxGenJS
+
+### ⚠️ Critical Rules
+
+**Colors - NEVER use `#` prefix:**
+- ✅ Correct: `color: "FF0000"`, `fill: { color: "0066CC" }`
+- ❌ Wrong: `color: "#FF0000"` (breaks document)
+
+### Adding Charts
+
+```javascript
+slide.addChart(pptx.charts.BAR, [{
+    name: "Sales 2024",
+    labels: ["Q1", "Q2", "Q3", "Q4"],
+    values: [4500, 5500, 6200, 7100]
+}], {
+    ...placeholders[0],
+    barDir: 'col',
+    showTitle: true,
+    title: 'Quarterly Sales',
+    showCatAxisTitle: true,
+    catAxisTitle: 'Quarter',
+    showValAxisTitle: true,
+    valAxisTitle: 'Sales ($000s)',
+    chartColors: ["4472C4"]
+});
+```
+
+### Adding Tables
+
+```javascript
+slide.addTable([
+    ["Header 1", "Header 2", "Header 3"],
+    ["Row 1, Col 1", "Row 1, Col 2", "Row 1, Col 3"]
+], {
+    x: 0.5, y: 1, w: 9, h: 3,
+    border: { pt: 1, color: "999999" },
+    fill: { color: "F1F1F1" }
+});
+```
+
+### Adding Images
+
+```javascript
+const aspectRatio = imgWidth / imgHeight;
+const h = 3;
+const w = h * aspectRatio;
+const x = (10 - w) / 2;
+
+slide.addImage({ path: "chart.png", x, y: 1.5, w, h });
+```