@simplysm/sd-claude 13.0.69 → 13.0.71

package/claude/refs/sd-angular.md

@@ -1,26 +1,26 @@
 # Angular Guidelines (v12 only)
 
-> v13에는 Angular 없음 (SolidJS로 대체됨). 아래 규칙은 v12 전용.
+> v13 has no Angular (replaced by SolidJS). Rules below are v12 only.
 
 ## Core Rules
 
-- **Signal 기반**: 상태에 RxJS 사용 금지. `$signal`, `$computed`, `$effect` 사용
-- **Standalone only**: 모든 컴포넌트 `standalone: true`
-- **OnPush + None**: `ChangeDetectionStrategy.OnPush`, `ViewEncapsulation.None` 필수
-- **input()/output()**: `@Input()`, `@Output()` 데코레이터 사용 금지 → `input()`, `output()`, `model()` 사용
-- **Control flow**: `@if`, `@for`, `@switch` 사용 (`*ngIf`, `*ngFor` 금지)
-- **DI**: `inject()` 사용 (생성자 파라미터 주입 금지)
-- **아이콘**: `@ng-icons/tabler-icons` 사용 (FontAwesome 아님)
-- **패키지 import**: `@simplysm/sd-angular` 루트에서만 import (서브폴더 접근 금지)
+- **Signal-based**: Do not use RxJS for state. Use `$signal`, `$computed`, `$effect`
+- **Standalone only**: All components must have `standalone: true`
+- **OnPush + None**: `ChangeDetectionStrategy.OnPush` and `ViewEncapsulation.None` are mandatory
+- **input()/output()**: Do not use `@Input()`, `@Output()` decorators → use `input()`, `output()`, `model()` instead
+- **Control flow**: Use `@if`, `@for`, `@switch` (no `*ngIf`, `*ngFor`)
+- **DI**: Use `inject()` (no constructor parameter injection)
+- **Icons**: Use `@ng-icons/tabler-icons` (not FontAwesome)
+- **Package imports**: Import `@simplysm/sd-angular` only from root (no subfolders)
 
 ## Signal Utilities
 
-- `$signal<T>(value?)` — writable signal (`$mark()`로 dirty 표시 가능)
-- `$computed(fn)` — 동기 computed. 비동기: `$computed([deps], asyncFn, { initialValue })`
-- `$effect(fn)` — 조건 추적 가능: `$effect([() => dep1()], () => { ... })`
-- `$arr(signal)` — 배열 조작 (`.insert()`, `.remove()`, `.toggle()`, `.diffs()`)
-- `$obj(signal)` — 객체 조작 (`.updateField()`, `.snapshot()`, `.changed()`)
-- `$set(signal)` — Set 조작 (`.add()`, `.toggle()`)
+- `$signal<T>(value?)` — writable signal (can mark dirty with `$mark()`)
+- `$computed(fn)` — synchronous computed. Async: `$computed([deps], asyncFn, { initialValue })`
+- `$effect(fn)` — dependency tracking: `$effect([() => dep1()], () => { ... })`
+- `$arr(signal)` — array operations (`.insert()`, `.remove()`, `.toggle()`, `.diffs()`)
+- `$obj(signal)` — object operations (`.updateField()`, `.snapshot()`, `.changed()`)
+- `$set(signal)` — Set operations (`.add()`, `.toggle()`)
 
 ## Component Pattern
 
@@ -66,7 +66,7 @@ sdHmrBootstrapAsync(AppPage, {
 
 ## Modal
 
-`ISdModal<T>` 인터페이스 구현:
+Implement `ISdModal<T>` interface:
 
 ```typescript
 export class MyModal implements ISdModal<TResult> {
@@ -74,22 +74,22 @@ export class MyModal implements ISdModal<TResult> {
   close = output<TResult>();
 }
 
-// 호출
+// Usage
 await this.#sdModal.showAsync({
   type: MyModal,
-  title: "제목",
+  title: "Title",
   inputs: { param: "value" },
 });
 ```
 
 ## Data Sheet
 
-CRUD 테이블은 `AbsSdDataSheet<TFilter, TItem, TKey>` 확장:
+CRUD tables extend `AbsSdDataSheet<TFilter, TItem, TKey>`:
 
-- `search()` — 데이터 조회
-- `submit()` — 변경사항 저장
-- `downloadExcel()` / `uploadExcel()` — 엑셀 연동
-- `$mark()` — 셀 수정 시 dirty 표시 필수
+- `search()` — query data
+- `submit()` — save changes
+- `downloadExcel()` / `uploadExcel()` — Excel integration
+- `$mark()` — mark dirty when cell is modified (mandatory)
 
 ## Busy / Error Handling
 
@@ -106,9 +106,9 @@ try {
 
 ## Theming
 
-- CSS 변수 사용: `--theme-primary-default`, `--gap-sm`, `--border-radius-default` 등
-- 하드코딩 색상 금지
-- 테마: `"compact"` | `"mobile"` | `"kiosk"` + dark mode
+- Use CSS variables: `--theme-primary-default`, `--gap-sm`, `--border-radius-default`, etc.
+- Do not hardcode colors
+- Themes: `"compact"` | `"mobile"` | `"kiosk"` + dark mode
 
 ## Permissions
 

package/claude/refs/sd-orm-v12.md

@@ -1,40 +1,40 @@
 # ORM Guidelines (v12)
 
-## Table Definition — Decorator 기반
+## Table Definition — Decorator-based
 
 ```typescript
-@Table({ description: "사용자", database: "mydb" })
+@Table({ description: "Users", database: "mydb" })
 export class User {
   @Column({ primaryKey: 1, autoIncrement: true, description: "ID" })
   id!: number;
 
-  @Column({ dataType: { type: "STRING", length: 100 }, description: "이름" })
+  @Column({ dataType: { type: "STRING", length: 100 }, description: "Name" })
   name!: string;
 
-  @Column({ nullable: true, description: "이메일" })
+  @Column({ nullable: true, description: "Email" })
   email?: string;
 
-  @ForeignKey(["departmentId"], () => Department, "부서")
+  @ForeignKey(["departmentId"], () => Department, "Department")
   department?: Department;
 
-  @ForeignKeyTarget(() => Order, "user", "주문 목록")
+  @ForeignKeyTarget(() => Order, "user", "Orders")
   orders?: Order[];
 }
 ```
 
 ### Decorators
 
-- `@Table({ description, database?, schema?, name?, view?, procedure? })` — 테이블/뷰/프로시저 정의
-- `@Column({ description, name?, dataType?, nullable?, autoIncrement?, primaryKey? })` — 컬럼 정의
-- `@ForeignKey(columnNames, targetTypeFwd, description)` — FK 관계
-- `@ForeignKeyTarget(sourceTypeFwd, fkPropertyKey, description, multiplicity?)` — FK 역방향
-- `@ReferenceKey(columnNames, targetTypeFwd, description)` — 참조 관계
-- `@ReferenceKeyTarget(sourceTypeFwd, refKeyPropertyKey, description, multiplicity?)` — 참조 역방향
-- `@Index({ name?, order?, orderBy?, unique? })` — 인덱스
+- `@Table({ description, database?, schema?, name?, view?, procedure? })` — define table/view/procedure
+- `@Column({ description, name?, dataType?, nullable?, autoIncrement?, primaryKey? })` — define column
+- `@ForeignKey(columnNames, targetTypeFwd, description)` — FK relationship
+- `@ForeignKeyTarget(sourceTypeFwd, fkPropertyKey, description, multiplicity?)` — FK reverse relationship
+- `@ReferenceKey(columnNames, targetTypeFwd, description)` — reference relationship
+- `@ReferenceKeyTarget(sourceTypeFwd, refKeyPropertyKey, description, multiplicity?)` — reference reverse relationship
+- `@Index({ name?, order?, orderBy?, unique? })` — index
 
-### 요구사항
+### Requirements
 
-- `tsconfig`에 `experimentalDecorators: true`, `emitDecoratorMetadata: true` 필요
+- `tsconfig` requires `experimentalDecorators: true` and `emitDecoratorMetadata: true`
 
 ## DbContext
 
@@ -59,11 +59,11 @@ const users = await db.user
   .resultAsync();
 
 // Insert
-await db.user.insertAsync([{ name: "홍길동" }]);
+await db.user.insertAsync([{ name: "John Doe" }]);
 
 // Connect with transaction
 await db.connectAsync(async () => {
-  await db.user.insertAsync([{ name: "홍길동" }]);
+  await db.user.insertAsync([{ name: "John Doe" }]);
 });
 ```
 

package/claude/rules/sd-refs-linker.md

@@ -4,7 +4,7 @@ Before starting work, **Read** the relevant reference files from `.claude/refs/`
 
 ## Version Detection
 
-`package.json`의 `version` 필드로 메이저 버전을 판별한다.
+Determine the major version by the `version` field in `package.json`.
 
 - `12.x.x` → **v12** (< 13)
 - `13.x.x` → **v13** (>= 13)
@@ -17,32 +17,32 @@ Before starting work, **Read** the relevant reference files from `.claude/refs/`
 | Working with `.cache/` or Playwright screenshots | `.claude/refs/sd-directories.md`      |
 | Using `@simplysm/*` package APIs                 | `.claude/refs/sd-simplysm-docs.md`    |
 | Debugging, problem-solving, or planning approach | `.claude/refs/sd-workflow.md`         |
-| @simplysm/service-\* 사용 시                     | `.claude/refs/sd-service.md`          |
+| Using `@simplysm/service-*` packages            | `.claude/refs/sd-service.md`          |
 | Migrating/porting code from another codebase     | `.claude/refs/sd-migration.md`        |
 
 ## v12 only (< 13)
 
 | When                                   | Read this file               |
 | -------------------------------------- | ---------------------------- |
-| Angular / @simplysm/sd-angular 작업 시 | `.claude/refs/sd-angular.md` |
-| @simplysm/sd-orm-\* 사용 시            | `.claude/refs/sd-orm-v12.md` |
+| Working on Angular / @simplysm/sd-angular | `.claude/refs/sd-angular.md` |
+| Using `@simplysm/sd-orm-*` packages    | `.claude/refs/sd-orm-v12.md` |
 
-- v12는 **Angular** 기반 (SolidJS 없음)
-- ORM은 **데코레이터** 패턴 (`@Table`, `@Column`)
-- 패키지명: `sd-` prefix 사용 (`sd-core-common`, `sd-orm-common` 등)
-- 패키지 매니저: **yarn**
+- v12 is **Angular** based (no SolidJS)
+- ORM uses **decorator** pattern (`@Table`, `@Column`)
+- Package names: use `sd-` prefix (`sd-core-common`, `sd-orm-common`, etc.)
+- Package manager: **yarn**
 
 ## v13 only (>= 13)
 
 | When                                         | Read this file             |
 | -------------------------------------------- | -------------------------- |
-| SolidJS / @simplysm/solid / Tailwind 작업 시 | `.claude/refs/sd-solid.md` |
-| @simplysm/orm-\* 사용 시                     | `.claude/refs/sd-orm.md`   |
+| Working on SolidJS / @simplysm/solid / Tailwind | `.claude/refs/sd-solid.md` |
+| Using `@simplysm/orm-*` packages             | `.claude/refs/sd-orm.md`   |
 
-- v13는 **SolidJS** 기반 (Angular 없음)
-- ORM은 **함수형 빌더** 패턴 (`Table().columns().primaryKey()`)
-- 패키지명: prefix 없음 (`core-common`, `orm-common` 등)
-- 패키지 매니저: **pnpm**
+- v13 is **SolidJS** based (no Angular)
+- ORM uses **functional builder** pattern (`Table().columns().primaryKey()`)
+- Package names: no prefix (`core-common`, `orm-common`, etc.)
+- Package manager: **pnpm**
 
 ## Rules
 

package/claude/sd-statusline.js

@@ -63,7 +63,7 @@ function getOAuthToken() {
     const credentials = JSON.parse(content);
     const oauth = credentials.claudeAiOauth;
 
-    // 토큰 만료 체크
+    // Check token expiration
     if (oauth?.expiresAt != null && Date.now() > oauth.expiresAt) {
       return undefined;
     }
@@ -75,12 +75,12 @@ function getOAuthToken() {
 }
 
 /**
- * OAuth 토큰을 사용하여 Anthropic API 사용량 정보를 조회한다.
- * @param {string} token - OAuth 액세스 토큰
+ * Fetch Anthropic API usage information using OAuth token.
+ * @param {string} token - OAuth access token
  * @returns {Promise<{
- *   seven_day?: {utilization?: number, resets_at?: string},  // 7일 사용량
- *   daily?: {utilization?: number, resets_at?: string},       // 일일 사용량
- *   five_hour?: {utilization?: number, resets_at?: string},   // 5시간 사용량
+ *   seven_day?: {utilization?: number, resets_at?: string},  // 7-day usage
+ *   daily?: {utilization?: number, resets_at?: string},       // daily usage
+ *   five_hour?: {utilization?: number, resets_at?: string},   // 5-hour usage
  *   extra_usage?: {is_enabled?: boolean, monthly_limit?: number | null, used_credits?: number}  // extra usage
  * } | undefined>}
  */
@@ -105,7 +105,7 @@ async function fetchUsage(token) {
 
     const data = await response.json();
 
-    // 응답 구조 검증
+    // Validate response structure
     if (data == null || typeof data !== "object") {
       return undefined;
     }
@@ -167,17 +167,17 @@ function formatTimeRemaining(isoDate) {
 //#region Main
 
 /**
- * stdin으로 입력받은 JSON 정보
+ * JSON information received from stdin
  * @typedef {object} StdinInput
- * @property {{display_name?: string}} [model] - 모델 정보
- * @property {{context_window_size?: number, remaining_context_tokens?: number, current_usage?: {input_tokens?: number, output_tokens?: number, cache_creation_input_tokens?: number, cache_read_input_tokens?: number}}} [context_window] - 컨텍스트 윈도우 정보
- * @property {{tokens_used?: number, tokens_limit?: number}} [weekly_token_usage] - 주간 토큰 사용량 (fallback용)
+ * @property {{display_name?: string}} [model] - Model information
+ * @property {{context_window_size?: number, remaining_context_tokens?: number, current_usage?: {input_tokens?: number, output_tokens?: number, cache_creation_input_tokens?: number, cache_read_input_tokens?: number}}} [context_window] - Context window information
+ * @property {{tokens_used?: number, tokens_limit?: number}} [weekly_token_usage] - Weekly token usage (fallback)
  */
 
 /**
- * Claude Code 상태 표시줄 정보를 출력한다.
- * stdin으로 입력받은 JSON과 OAuth API 응답을 조합하여
- * 모델명, 컨텍스트 사용량, 일일/주간 사용량을 출력한다.
+ * Output Claude Code status bar information.
+ * Combine JSON received from stdin with OAuth API response to output
+ * model name, context usage, and daily/weekly usage.
  */
 async function main() {
   const inputStr = await readStdin();
@@ -188,11 +188,11 @@ async function main() {
     try {
       input = JSON.parse(inputStr);
     } catch {
-      // JSON 파싱 실패 시 빈 객체 사용
+      // Use empty object if JSON parsing fails
     }
   }
 
-  // 기본 정보
+  // Basic information
   const modelName = input.model?.display_name ?? "Unknown";
   const contextSize = input.context_window?.context_window_size ?? 0;
   const usage = input.context_window?.current_usage;
@@ -203,7 +203,7 @@ async function main() {
     (usage?.cache_read_input_tokens ?? 0);
   const contextPercent = contextSize > 0 ? Math.round((contextUsed / contextSize) * 100) : 0;
 
-  // OAuth 토큰으로 사용량 조회 시도
+  // Try fetching usage with OAuth token
   const token = getOAuthToken();
   let dailyPercent = "?";
   let dailyResetTime = "";
@@ -214,21 +214,21 @@ async function main() {
   if (token != null) {
     const usageResponse = await fetchUsage(token);
     if (usageResponse != null) {
-      // daily 또는 five_hour 사용
+      // Use daily or five_hour
       const dailyData = usageResponse.daily ?? usageResponse.five_hour;
       dailyPercent = formatPercent(dailyData?.utilization);
       dailyResetTime = formatTimeRemaining(dailyData?.resets_at);
       weekPercent = formatPercent(usageResponse.seven_day?.utilization);
       weekResetDay = formatTimeRemaining(usageResponse.seven_day?.resets_at);
 
-      // extra usage
+      // Extra usage
       if (usageResponse.extra_usage?.is_enabled && usageResponse.extra_usage.used_credits != null) {
         extraUsage = `$${(usageResponse.extra_usage.used_credits / 100).toFixed(2)}`;
       }
     }
   }
 
-  // fallback: weekly_token_usage
+  // Fallback: weekly_token_usage
   if (weekPercent === "?" && input.weekly_token_usage != null) {
     const used = input.weekly_token_usage.tokens_used ?? 0;
     const limit = input.weekly_token_usage.tokens_limit ?? 0;
@@ -237,7 +237,7 @@ async function main() {
     }
   }
 
-  // 폴더명 + git 브랜치
+  // Folder name + git branch
   const cwd = input.cwd ?? process.cwd();
   const folderName = path.basename(cwd);
 

package/claude/skills/sd-api-name-review/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: sd-api-name-review
-description: Public API naming consistency and industry standard alignment review
-disable-model-invocation: true
+description: "Public API naming review (explicit invocation only)"
 model: sonnet
 ---
 

package/claude/skills/sd-brainstorm/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: sd-brainstorm
-description: Collaborative design exploration through Q&A before implementation
-disable-model-invocation: true
-model: opus
+description: "Design exploration before implementation (explicit invocation only)"
 ---
 
 # Brainstorming Ideas Into Designs
@@ -119,13 +117,14 @@ You can start from any step or skip steps as needed.
 ```
 
 - The last `⚠️` line is only shown when uncommitted changes exist. Omit it when working tree is clean.
+- If the design does NOT involve code modifications, omit the `/sd-check` step from both paths.
 
 - After presenting both paths, **recommend one** based on the design's scope:
    - Path A recommended: new features, multi-file changes, architectural changes, anything that benefits from isolation
    - Path B recommended: small bug fixes, single-file changes, config tweaks, minor adjustments
    - Briefly explain why (1 sentence)
 - Do NOT auto-proceed to any step. Present the overview with recommendation and wait for the user's choice.
-- **Yolo mode**: If the user responds with "Path A: yolo" or "Path B: yolo" (or similar intent like "A yolo", "B 자동"), execute all steps of the chosen path sequentially without stopping between steps.
+- **Yolo mode**: If the user responds with "Path A: yolo" or "Path B: yolo" (or similar intent like "A yolo", "B auto"), execute all steps of the chosen path sequentially without stopping between steps.
 - **Yolo sd-check — include dependents**: NEVER check only modified packages. Also check all packages that depend on them:
    1. Identify modified packages from `git diff --name-only`
    2. Trace reverse dependencies (packages that import from modified packages) using `package.json` or project dependency graph

package/claude/skills/sd-check/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: sd-check
-description: Code quality verification via typecheck, lint, and tests
-disable-model-invocation: true
+description: "Typecheck, lint, test verification (explicit invocation only)"
 allowed-tools: Bash(npm run check), Bash(npm run typecheck), Bash(npm run lint --fix), Bash(npm run vitest)
 ---
 

package/claude/skills/sd-commit/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: sd-commit
-description: Git commit with conventional commit messages
-disable-model-invocation: true
+description: "Git commit with conventional messages (explicit invocation only)"
 argument-hint: "[all]"
 allowed-tools: Bash(git status:*), Bash(git add:*), Bash(git commit:*)
 model: haiku
@@ -51,7 +50,7 @@ type(scope): short description
 | ------------- | ---------------------------------------------------------------------------- |
 | `type`        | `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `build`, `style`, `perf` |
 | `scope`       | package name or area (e.g., `solid`, `core-common`, `orm-node`)              |
-| `description` | imperative, lowercase, no period at end                                      |
+| `description` | written in the system's configured language, imperative, lowercase, no period at end |
 
 Examples:
 

package/claude/skills/sd-debug/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: sd-debug
-description: Systematic root-cause debugging methodology
-disable-model-invocation: true
+description: "Use when the user reports a bug, error, or unexpected behavior and asks to fix or debug it. Triggers: error messages, stack traces, test failures, build failures, 'why is this broken', 'fix this', 'debug this', unexpected behavior investigation."
 ---
 
 # Systematic Debugging

package/claude/skills/sd-discuss/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: sd-discuss
-description: Evidence-based technical discussion with industry research
-disable-model-invocation: true
-model: opus
+description: "Technical discussion with industry research (explicit invocation only)"
 ---
 
 # Standards-Based Technical Discussion

package/claude/skills/sd-document/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: sd-document
+description: "Use when the user's request involves .docx, .xlsx, .pptx, or .pdf files. Triggers: document reading/analysis, file content extraction, DOCX/XLSX creation, client document review, data export."
+---
+
+# Document Processing
+
+## Overview
+
+Read and write document files (.docx/.xlsx/.pptx/.pdf).
+Python scripts extract text and images with location information by format, save images to files, and analyze them with Claude Read.
+
+## Quick Reference
+
+| Format | Read | Write | Library |
+|--------|------|-------|---------|
+| DOCX | Yes | Yes | `python-docx` |
+| XLSX | Yes | Yes | `openpyxl`, `pandas` |
+| PPTX | Yes | No | `python-pptx` |
+| PDF  | Yes | No | `pdfplumber`, `pypdf` |
+
+Missing packages are auto-installed on first script run.
+
+## Reading (Document Analysis)
+
+Run extraction scripts by format:
+
+```bash
+python .claude/skills/sd-document/extract_docx.py <filepath>
+python .claude/skills/sd-document/extract_xlsx.py <filepath>
+python .claude/skills/sd-document/extract_pptx.py <filepath>
+python .claude/skills/sd-document/extract_pdf.py  <filepath>
+```
+
+### Output
+- **stdout**: Text and location information (Markdown format)
+- **Image files**: Saved to `<filename>_files/` directory
+
+### Location Information
+
+| Format | Location Representation |
+|--------|-------------------------|
+| DOCX | Paragraph flow order (text-image inline) |
+| XLSX | Cell position (A1, B2, etc.) |
+| PPTX | Shape left/top coordinates (inches) + slide number |
+| PDF  | Page number |
+
+### Image Analysis
+Open extracted image files with Claude **Read** tool for visual analysis.
+
+### Scanned PDF (OCR)
+If text extraction is empty, the script outputs OCR instructions.
+Tesseract OCR requires OS-level installation (not auto-installable via pip).
+
+## Writing
+
+### DOCX (`python-docx`)
+
+For mail templates and simple reports.
+
+```python
+from docx import Document
+
+doc = Document()                          # New document
+# doc = Document("existing.docx")         # Edit existing document
+doc.add_heading("Title", level=1)
+doc.add_paragraph("Body content")
+table = doc.add_table(rows=2, cols=3)
+table.cell(0, 0).text = "Item"
+doc.save("output.docx")
+```
+
+Edit existing document: open with `Document("existing.docx")`, replace `paragraph.text`, modify `table.cell().text`.
+
+### XLSX (`openpyxl`)
+
+Focuses on data and formulas. Formatting (colors, borders) not required.
+
+```python
+from openpyxl import Workbook
+
+wb = Workbook()
+ws = wb.active
+ws["A1"] = "Item"
+ws["B1"] = "Quantity"
+ws.append(["Apple", 10])
+ws.append(["Pear", 20])
+ws["B4"] = "=SUM(B2:B3)"
+wb.save("output.xlsx")
+```
+
+Edit existing file: open with `load_workbook("existing.xlsx")` and modify.
+Export pandas DataFrame: `df.to_excel("output.xlsx", index=False)`
+
+## Common Mistakes
+
+- **Character encoding**: Scripts have built-in UTF-8 handling; always extract through scripts
+- **Missing images**: After extraction, remember to read images in `_files/` directory
+- **XLSX data_only**: `load_workbook(data_only=True)` removes formulas — use `data_only=False` to preserve them

package/claude/skills/sd-document/extract_docx.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""DOCX 파일에서 텍스트와 이미지를 문단 흐름 순서로 추출한다."""
+
+import sys
+import io
+import os
+import subprocess
+from pathlib import Path
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")
+
+
+def ensure_packages():
+    packages = {"python-docx": "docx"}
+    for pip_name, import_name in packages.items():
+        try:
+            __import__(import_name)
+        except ImportError:
+            print(f"패키지 설치 중: {pip_name}...", file=sys.stderr)
+            subprocess.check_call([sys.executable, "-m", "pip", "install", pip_name],
+                                  stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+
+
+def extract(file_path):
+    from docx import Document
+    from docx.oxml.ns import qn
+
+    doc = Document(file_path)
+    stem = Path(file_path).stem
+    out_dir = Path(file_path).parent / f"{stem}_files"
+    img_idx = 0
+
+    print(f"# {Path(file_path).name}\n")
+
+    for i, para in enumerate(doc.paragraphs):
+        has_image = False
+        for run in para.runs:
+            drawings = run._element.findall(f".//{qn('wp:inline')}") + run._element.findall(f".//{qn('wp:anchor')}")
+            for drawing in drawings:
+                blip = drawing.find(f".//{qn('a:blip')}")
+                if blip is not None:
+                    embed = blip.get(qn("r:embed"))
+                    if embed:
+                        rel = doc.part.rels.get(embed)
+                        if rel:
+                            img_idx += 1
+                            blob = rel.target_part.blob
+                            content_type = rel.target_part.content_type
+                            ext = content_type.split("/")[-1].replace("jpeg", "jpg")
+                            out_dir.mkdir(parents=True, exist_ok=True)
+                            img_path = out_dir / f"img_{img_idx:03d}.{ext}"
+                            img_path.write_bytes(blob)
+                            print(f"[IMG] {img_path}")
+                            has_image = True
+
+        text = para.text.strip()
+        if text:
+            style = para.style.name if para.style else ""
+            prefix = ""
+            if "Heading" in style:
+                level = style.replace("Heading ", "").replace("Heading", "1")
+                try:
+                    prefix = "#" * int(level) + " "
+                except ValueError:
+                    prefix = "## "
+            print(f"{prefix}{text}")
+
+        if has_image or text:
+            pass  # already printed
+        elif not has_image and not text:
+            continue
+
+    # 표 추출
+    for t_idx, table in enumerate(doc.tables):
+        print(f"\n### Table {t_idx + 1}\n")
+        for row in table.rows:
+            cells = [cell.text.strip().replace("\n", " ") for cell in row.cells]
+            print("| " + " | ".join(cells) + " |")
+
+    if img_idx > 0:
+        print(f"\n---\n이미지 {img_idx}개 저장: {out_dir}")
+    else:
+        print("\n---\n이미지 없음")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python extract_docx.py <file.docx>", file=sys.stderr)
+        sys.exit(1)
+    ensure_packages()
+    extract(sys.argv[1])