hwpx-kit-cli 0.2.1__tar.gz → 0.4.0__tar.gz

{hwpx_kit_cli-0.2.1 → hwpx_kit_cli-0.4.0}/.claude-plugin/plugin.json

@@ -1,9 +1,9 @@
-{
-  "name": "hwpx-kit",
-  "description": "한글(HWPX/HWP) 문서 자동화 스킬 모음 — 양식 분석·채우기·백지 생성·표기 변환·공문 규약·표 계산·오피스 출력. CLI는 첫 사용 시 스킬이 설치를 안내 (Python 3.10+ 필요).",
-  "version": "0.2.1",
-  "author": {
-    "name": "6aneffy",
-    "email": "tkdgus990809@gmail.com"
-  }
+{
+  "name": "hwpx-kit",
+  "description": "한글(HWPX/HWP) 문서 자동화 스킬 모음 — 양식 분석·채우기·백지 생성·표기 변환·공문 규약·표 계산·오피스 출력. CLI는 첫 사용 시 스킬이 설치를 안내 (Python 3.10+ 필요).",
+  "version": "0.4.0",
+  "author": {
+    "name": "6aneffy",
+    "email": "tkdgus990809@gmail.com"
+  }
 }

{hwpx_kit_cli-0.2.1 → hwpx_kit_cli-0.4.0}/.gitignore

@@ -13,3 +13,4 @@ private/
 incoming/
 node_modules/
 mcp/
+.playwright-mcp/

{hwpx_kit_cli-0.2.1 → hwpx_kit_cli-0.4.0}/CLAUDE.md

@@ -26,7 +26,7 @@ skills/*/SKILL.md → Claude Code 플러그인 스킬들 (.claude-plugin/plugin.
  └─ office-export    → hwpx→docx(변환)·pptx/xlsx(재구성, officecli 선택 의존)
 
 CLI (cli.py) — JSON 봉투, 종료코드 0/1/2
- └─ commands/ (analyze·fill·read·validate·convert·export·render·generate·fmt·row-add·row-del·row-height·table-clear·table-set·table-copy·table-map·table-new·page-break·outline)
+ └─ commands/ (analyze·fill·fill-batch·inspect·image-add·header-footer·read·validate·convert·export·render·generate·fmt·row-add·row-del·row-height·table-clear·table-set·table-copy·table-map·table-new·page-break·outline)
      ├─ format.py ← 순수함수 (금액한글화·요일·만나이) — 엔진 임포트 금지, fmt는 파일 인수 없음(FILE_NOT_FOUND 가드 우회)
      └─ adapter/ ← 명령 계층은 어댑터 인터페이스만 사용 (엔진 직접 import 금지)
          ├─ hwpx_engine.py   → python-hwpx (hwpx 분석·채우기·검증·표 조작, 순수 Python)

{hwpx_kit_cli-0.2.1 → hwpx_kit_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hwpx-kit-cli
-Version: 0.2.1
+Version: 0.4.0
 Summary: 한글(HWPX) 문서 자동화 CLI — Korean HWPX document automation for AI agents: analyze, fill, read, validate, table ops
 Project-URL: Homepage, https://github.com/6aneffy/hwpx-kit
 Project-URL: Repository, https://github.com/6aneffy/hwpx-kit
@@ -33,7 +33,7 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/v/hwpx-kit-cli.svg)](https://pypi.org/project/hwpx-kit-cli/)
 [![Python](https://img.shields.io/badge/python-3.10%2B-3776AB.svg)](https://www.python.org/)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-d97757.svg)](https://claude.com/claude-code)
-[![Tests](https://img.shields.io/badge/tests-160%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-186%20passing-brightgreen.svg)](tests/)
 
 </div>
 
@@ -66,6 +66,30 @@ hwpx-kit은 **AI 에이전트가 한글 문서를 읽고, 채우고, 고치고,
 **이런 분들을 위해 만들었습니다**: 공공기관·학교의 서식 담당자, 사업계획서를 반복 작성하는
 창업자·연구자, 한글 문서를 AI 워크플로에 넣고 싶은 개발자.
 
+## 데모 — 한마디로 기획서 한 부
+
+> "hwpx로 새로운 사업기획서 작성해줘. 서울광역시에서 진행하는 Claude Code 해커톤"
+
+**① 시작점 — 내장 템플릿** (양식 파일이 없을 때 기준. 갖고 있는 양식이 있으면 그 양식을 그대로 씁니다)
+
+![내장 템플릿](docs/images/Before.png)
+
+**② 작업 과정** — 필수 정보(일시·대상·주최·예산)를 먼저 묻고, 답을 받아 진행합니다
+
+![작업 과정](docs/images/Tasking.png)
+
+**③ 결과물** — 표지·5개 장·일정표·예산표까지 채워진 완성본. 서식은 템플릿 그대로
+
+![완성본](docs/images/After.png)
+
+이 데모에서 실제로 일어난 일들:
+
+- **아는 것만 쓰고, 모르는 건 묻습니다** — 장소가 미정이라고 하자 "서울 시내 행사장(추후 확정)"으로 표기하고 확정되면 수정하겠다고 알림. 말하지 않은 정원·시상금을 지어내지 않음
+- **내용을 주면 그대로, 안 주면 Claude가 초안** — 시상금 구성은 사용자가 준 숫자 그대로, 추진배경·목적은 "필요하다고 생각하는 것들 다 써줘"라는 요청에 Claude가 작성. **상세하게 말할수록 상세하게 반영됩니다**
+- **표 계산은 결정론** — 예산표 합계 7,000 + 30,000 = 총계 37,000천원, 수기 계산 착오 없음
+- **구조도 바꿉니다** — 장 추가/복제, 표 행 추가·삭제(서식 승계), 쪽나눔까지. "5장 뒤에 강사진 장 추가해줘"가 통합니다
+- **기존 양식 재활용** — 작성 완료된 옛 기획서를 주고 "○○사업용으로 바꿔줘"라고 하면 그 문서를 양식 삼아 내용만 전면 교체 (서식 무손상)
+
 ## 30초 설치
 
 Claude Code에서:
@@ -120,6 +144,8 @@ hwpx-kit validate 문서.hwpx --json           # 구조 검증
 
 # 채우기·편집 (원본 불변 — 항상 --out 사본)
 hwpx-kit fill 양식.hwpx --data 값.json --out 결과.hwpx
+hwpx-kit fill-batch 양식.hwpx --rows 명단.xlsx --template 값틀.json --out-dir 결과/ --name "{성명}_위촉장.hwpx"  # 메일머지
+hwpx-kit inspect 결과.hwpx --json            # 제출 전 검수 — 잔여 마커·공문 표기·개인정보
 hwpx-kit table-set 문서.hwpx --table 3 --data 셀.json --out 결과.hwpx   # 좌표 셀 쓰기
 hwpx-kit table-clear 문서.hwpx --table 3 --rows 1-20 --out 결과.hwpx    # 셀 내용 비우기
 hwpx-kit table-copy 문서.hwpx --table 1 --after-table 4 --out 결과.hwpx # 표 통째 복제 (서식·병합 유지)
@@ -128,6 +154,8 @@ hwpx-kit row-add 문서.hwpx --table 3 --like 2 --count 3 --out 결과.hwpx
 hwpx-kit row-del 문서.hwpx --table 3 --rows 5-7 --out 결과.hwpx              # 행 삭제
 hwpx-kit row-height 문서.hwpx --table 3 --like 1 --rows 2-5 --out 결과.hwpx  # 행 높이 정돈
 hwpx-kit page-break 문서.hwpx --table 5 --out 결과.hwpx                 # 쪽나눔 (새 장 시작)
+hwpx-kit image-add 문서.hwpx --image 도장.png --at-text "(인)" --width-mm 20 --out 결과.hwpx  # 직인·사진
+hwpx-kit header-footer 문서.hwpx --footer "대외비" --page-number center --out 결과.hwpx
 
 # 변환·생성
 hwpx-kit fmt --amount 12340 --json           # 금12,340원(금일만이천삼백사십원)
@@ -164,7 +192,7 @@ hwpx-kit render 문서.hwpx --out p.svg        # SVG 미리보기 (kordoc)
 ## 아키텍처
 
 ```
-Claude Code 스킬 6종 ──→  hwpx-kit CLI (21 명령, JSON 봉투)
+Claude Code 스킬 6종 ──→  hwpx-kit CLI (25 명령, JSON 봉투)
                               └─ adapter/  ← 엔진 격리 계층
                                   ├─ python-hwpx    hwpx 분석·채우기·표 조작
                                   ├─ pypdf·python-docx·openpyxl   타 포맷 읽기
@@ -180,7 +208,7 @@ templates/ 기본 계획서 템플릿 (표지·장 헤더·표 골격, 마커
 
 ## 검증
 
-- 자동 테스트 160개 (pytest)
+- 자동 테스트 186개 (pytest)
 - 실서식 수렴 테스트: 보도자료·신청서·계획서·회의록·공고문 5계열,
   실제 공공기관 문서 30여 종으로 analyze→fill→validate 왕복
 - 실사용 시나리오 테스트 3회 (백지 생성 12분 완주, 장·표 동적 추가, 보도자료 변환)

{hwpx_kit_cli-0.2.1 → hwpx_kit_cli-0.4.0}/README.md

@@ -10,7 +10,7 @@
 [![PyPI](https://img.shields.io/pypi/v/hwpx-kit-cli.svg)](https://pypi.org/project/hwpx-kit-cli/)
 [![Python](https://img.shields.io/badge/python-3.10%2B-3776AB.svg)](https://www.python.org/)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-d97757.svg)](https://claude.com/claude-code)
-[![Tests](https://img.shields.io/badge/tests-160%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-186%20passing-brightgreen.svg)](tests/)
 
 </div>
 
@@ -43,6 +43,30 @@ hwpx-kit은 **AI 에이전트가 한글 문서를 읽고, 채우고, 고치고,
 **이런 분들을 위해 만들었습니다**: 공공기관·학교의 서식 담당자, 사업계획서를 반복 작성하는
 창업자·연구자, 한글 문서를 AI 워크플로에 넣고 싶은 개발자.
 
+## 데모 — 한마디로 기획서 한 부
+
+> "hwpx로 새로운 사업기획서 작성해줘. 서울광역시에서 진행하는 Claude Code 해커톤"
+
+**① 시작점 — 내장 템플릿** (양식 파일이 없을 때 기준. 갖고 있는 양식이 있으면 그 양식을 그대로 씁니다)
+
+![내장 템플릿](docs/images/Before.png)
+
+**② 작업 과정** — 필수 정보(일시·대상·주최·예산)를 먼저 묻고, 답을 받아 진행합니다
+
+![작업 과정](docs/images/Tasking.png)
+
+**③ 결과물** — 표지·5개 장·일정표·예산표까지 채워진 완성본. 서식은 템플릿 그대로
+
+![완성본](docs/images/After.png)
+
+이 데모에서 실제로 일어난 일들:
+
+- **아는 것만 쓰고, 모르는 건 묻습니다** — 장소가 미정이라고 하자 "서울 시내 행사장(추후 확정)"으로 표기하고 확정되면 수정하겠다고 알림. 말하지 않은 정원·시상금을 지어내지 않음
+- **내용을 주면 그대로, 안 주면 Claude가 초안** — 시상금 구성은 사용자가 준 숫자 그대로, 추진배경·목적은 "필요하다고 생각하는 것들 다 써줘"라는 요청에 Claude가 작성. **상세하게 말할수록 상세하게 반영됩니다**
+- **표 계산은 결정론** — 예산표 합계 7,000 + 30,000 = 총계 37,000천원, 수기 계산 착오 없음
+- **구조도 바꿉니다** — 장 추가/복제, 표 행 추가·삭제(서식 승계), 쪽나눔까지. "5장 뒤에 강사진 장 추가해줘"가 통합니다
+- **기존 양식 재활용** — 작성 완료된 옛 기획서를 주고 "○○사업용으로 바꿔줘"라고 하면 그 문서를 양식 삼아 내용만 전면 교체 (서식 무손상)
+
 ## 30초 설치
 
 Claude Code에서:
@@ -97,6 +121,8 @@ hwpx-kit validate 문서.hwpx --json           # 구조 검증
 
 # 채우기·편집 (원본 불변 — 항상 --out 사본)
 hwpx-kit fill 양식.hwpx --data 값.json --out 결과.hwpx
+hwpx-kit fill-batch 양식.hwpx --rows 명단.xlsx --template 값틀.json --out-dir 결과/ --name "{성명}_위촉장.hwpx"  # 메일머지
+hwpx-kit inspect 결과.hwpx --json            # 제출 전 검수 — 잔여 마커·공문 표기·개인정보
 hwpx-kit table-set 문서.hwpx --table 3 --data 셀.json --out 결과.hwpx   # 좌표 셀 쓰기
 hwpx-kit table-clear 문서.hwpx --table 3 --rows 1-20 --out 결과.hwpx    # 셀 내용 비우기
 hwpx-kit table-copy 문서.hwpx --table 1 --after-table 4 --out 결과.hwpx # 표 통째 복제 (서식·병합 유지)
@@ -105,6 +131,8 @@ hwpx-kit row-add 문서.hwpx --table 3 --like 2 --count 3 --out 결과.hwpx
 hwpx-kit row-del 문서.hwpx --table 3 --rows 5-7 --out 결과.hwpx              # 행 삭제
 hwpx-kit row-height 문서.hwpx --table 3 --like 1 --rows 2-5 --out 결과.hwpx  # 행 높이 정돈
 hwpx-kit page-break 문서.hwpx --table 5 --out 결과.hwpx                 # 쪽나눔 (새 장 시작)
+hwpx-kit image-add 문서.hwpx --image 도장.png --at-text "(인)" --width-mm 20 --out 결과.hwpx  # 직인·사진
+hwpx-kit header-footer 문서.hwpx --footer "대외비" --page-number center --out 결과.hwpx
 
 # 변환·생성
 hwpx-kit fmt --amount 12340 --json           # 금12,340원(금일만이천삼백사십원)
@@ -141,7 +169,7 @@ hwpx-kit render 문서.hwpx --out p.svg        # SVG 미리보기 (kordoc)
 ## 아키텍처
 
 ```
-Claude Code 스킬 6종 ──→  hwpx-kit CLI (21 명령, JSON 봉투)
+Claude Code 스킬 6종 ──→  hwpx-kit CLI (25 명령, JSON 봉투)
                               └─ adapter/  ← 엔진 격리 계층
                                   ├─ python-hwpx    hwpx 분석·채우기·표 조작
                                   ├─ pypdf·python-docx·openpyxl   타 포맷 읽기
@@ -157,7 +185,7 @@ templates/ 기본 계획서 템플릿 (표지·장 헤더·표 골격, 마커
 
 ## 검증
 
-- 자동 테스트 160개 (pytest)
+- 자동 테스트 186개 (pytest)
 - 실서식 수렴 테스트: 보도자료·신청서·계획서·회의록·공고문 5계열,
   실제 공공기관 문서 30여 종으로 analyze→fill→validate 왕복
 - 실사용 시나리오 테스트 3회 (백지 생성 12분 완주, 장·표 동적 추가, 보도자료 변환)

{hwpx_kit_cli-0.2.1 → hwpx_kit_cli-0.4.0}/commands/hwpx.md

@@ -1,8 +1,11 @@
 ---
-description: hwpx-kit 도움말 — 스킬 6종과 사용 예시 안내
+description: hwpx-kit 도움말 — 스킬 6종과 사용 예시 안내 (사용자가 /hwpx를 직접 입력했을 때 전용)
+disable-model-invocation: true
 ---
 
 아래 카탈로그를 그대로 사용자에게 출력하라. 다른 도구를 호출하지 말 것.
+(이 카탈로그는 사용자가 /hwpx를 직접 쳤을 때만 보여주는 것 — 문서 작업
+요청이 들어온 상황이라면 카탈로그 출력 없이 해당 스킬로 바로 진행하라.)
 
 ```
 📄 hwpx-kit — 한글(HWPX) 문서 자동화

{hwpx_kit_cli-0.2.1 → hwpx_kit_cli-0.4.0}/pyproject.toml

@@ -1,44 +1,44 @@
-[project]
-name = "hwpx-kit-cli"
-version = "0.2.1"
-description = "한글(HWPX) 문서 자동화 CLI — Korean HWPX document automation for AI agents: analyze, fill, read, validate, table ops"
-readme = "README.md"
-requires-python = ">=3.10"
-license = "Apache-2.0"
-authors = [{ name = "6aneffy", email = "tkdgus990809@gmail.com" }]
-keywords = ["hwpx", "hwp", "hangul", "korean", "document-automation", "claude-code"]
-classifiers = [
-    "Programming Language :: Python :: 3",
-    "Operating System :: OS Independent",
-    "Topic :: Office/Business :: Office Suites",
-]
-dependencies = [
-    "openpyxl>=3.1.5",
-    "pypdf>=6.14.2",
-    "python-docx>=1.2.0",
-    "python-hwpx>=2.24,<3",
-]
-
-[project.optional-dependencies]
-convert = ["pyhwpx; sys_platform == 'win32'"]
-
-[project.urls]
-Homepage = "https://github.com/6aneffy/hwpx-kit"
-Repository = "https://github.com/6aneffy/hwpx-kit"
-Issues = "https://github.com/6aneffy/hwpx-kit/issues"
-
-[project.scripts]
-hwpx-kit = "hwpx_kit.cli:main"
-
-[dependency-groups]
-dev = ["pytest>=8"]
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/hwpx_kit"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
+[project]
+name = "hwpx-kit-cli"
+version = "0.4.0"
+description = "한글(HWPX) 문서 자동화 CLI — Korean HWPX document automation for AI agents: analyze, fill, read, validate, table ops"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "6aneffy", email = "tkdgus990809@gmail.com" }]
+keywords = ["hwpx", "hwp", "hangul", "korean", "document-automation", "claude-code"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Office/Business :: Office Suites",
+]
+dependencies = [
+    "openpyxl>=3.1.5",
+    "pypdf>=6.14.2",
+    "python-docx>=1.2.0",
+    "python-hwpx>=2.24,<3",
+]
+
+[project.optional-dependencies]
+convert = ["pyhwpx; sys_platform == 'win32'"]
+
+[project.urls]
+Homepage = "https://github.com/6aneffy/hwpx-kit"
+Repository = "https://github.com/6aneffy/hwpx-kit"
+Issues = "https://github.com/6aneffy/hwpx-kit/issues"
+
+[project.scripts]
+hwpx-kit = "hwpx_kit.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hwpx_kit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

{hwpx_kit_cli-0.2.1 → hwpx_kit_cli-0.4.0}/skills/gongmun-format/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gongmun-format
-description: 행안부 공문서 작성 규약 — 글머리 위계(□○-※*), 날짜·금액 표기, 홑낫표, 어절정리, 복붙 깨짐 복구. 공문·보도자료·계획안 초안 작성이나 "공문 형식으로", "공문서 규정대로", "보고서 양식 맞춰줘" 요청 시 사용. Triggers: Korean government document style, gongmun formatting.
+description: 행안부 공문서 작성 규약 — 글머리 위계(□○-※*), 날짜·금액 표기, 홑낫표, 어절정리, 복붙 깨짐 복구, 제출 전 기계 검수(inspect). 공문·보도자료·계획안 초안 작성이나 "공문 형식으로", "공문서 규정대로", "보고서 양식 맞춰줘", "제출 전에 검토해줘" 요청 시 사용. Triggers: Korean government document style, gongmun formatting, review before submission.
 ---
 
 # gongmun-format: 행안부 공문 작성 규약
@@ -34,6 +34,17 @@ description: 행안부 공문서 작성 규약 — 글머리 위계(□○-※*)
 - **법령·문서명**: 홑낫표 `「」` 로 감싼다 — `「행정 효율과 협업 촉진에 관한 규정」`
 - **증감·비율**: table-calc 스킬의 표기 관습(△·%p 등) 따름
 
+## 제출 전 검수 — "검토해줘" (기계 검사 먼저, 판단은 그 위에)
+
+`hwpx-kit inspect <문서.hwpx> --json` — 결정론 검사 3종 (fmt와 같은 "암산 금지" 원칙):
+- **residue**: 채우다 만 {{마커}}·○○○ 자리표시·"(예시)" 안내문 잔존
+- **gongmun**: 날짜 하이픈 표기(2026-07-10 → `2026. 7. 10.`), 오전/오후 시각(→ 24시각제)
+- **pii**: 주민번호·휴대전화·이메일 잔존 (공개 배포 문서면 특히)
+
+종료코드 2 = 위반 있음. `issues[]`의 code·context를 **사람 말로 요약**해 보여주고,
+수정할 항목을 확정받아 fill(text:/delete:)로 고친 뒤 재검사. 기계 검사가 못 보는
+것(위계 건너뜀, 어색한 문장, 내용 누락)은 read 출력을 직접 읽고 이 스킬 규약으로 판단.
+
 ## 텍스트 정리 (재작성 계열 — 우리가 범피스보다 잘하는 것)
 
 한글 문서에서 read로 뽑은 텍스트나 사용자가 붙여넣은 텍스트가 깨져 있으면:

{hwpx_kit_cli-0.2.1 → hwpx_kit_cli-0.4.0}/skills/hwpx-form/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hwpx-kit
-description: HWPX 양식 자동화 — 한글(HWPX/HWP) 양식 분석, 내용 채우기, 본문 추출, 구조 검증, .hwp→.hwpx 변환. 사용자가 hwpx/hwp 파일을 주며 "이 양식에 채워줘", "여기에 써줘", "이 문서 읽어줘/요약해줘", "hwp 변환해줘" 할 때 사용. Triggers: fill this Korean form, read this hwp/hwpx file, Hangul document automation.
+description: HWPX 양식 자동화 — 한글(HWPX/HWP) 양식 분석, 내용 채우기, 본문 추출, 구조 검증, .hwp→.hwpx 변환. 사용자가 hwpx/hwp 파일을 주며 "이 양식에 채워줘", "여기에 써줘", "이 명단으로 30명분 만들어줘"(일괄 생성), "이 엑셀 표 넣어줘", "도장 찍어줘/사진 붙여줘", "쪽번호 넣어줘", "이 문서 읽어줘/요약해줘", "hwp 변환해줘" 할 때 사용. Triggers: fill this Korean form, mail merge certificates, read this hwp/hwpx file, Hangul document automation.
 ---
 
 # hwpx-kit: HWPX 양식 자동화
@@ -21,6 +21,11 @@ CLI `hwpx-kit`으로 hwpx 문서를 다룬다. 항상 `--json`을 붙여 실행
    (실패 시 폴백: `pip install --user git+https://github.com/6aneffy/hwpx-kit.git`)
    → `python -m hwpx_kit.cli --version` 확인 후 원래 작업 계속
 
+**구버전 업그레이드도 같은 이름**: 설치돼 있는데 필요한 명령(row-add 등)이
+없으면 `pip install -U hwpx-kit-cli`. 🔴 **PyPI 배포명은 `hwpx-kit-cli`다**
+— `hwpx-kit`은 PyPI에 없는 이름이니 (플러그인·명령어 이름일 뿐) 그걸로
+검색/설치 시도하지 말 것
+
 기존 문서(계획안·보고서 작성본)를 양식 삼아 **다른 사업 문서를 새로 쓰는** 요청도
 같은 흐름이다 — 내용(사업명·배경·커리큘럼 등)은 네가 초안을 짜서 사용자와 확정하고,
 문서화는 read → text:/table: 교체로 한다. 서식은 원본 그대로 유지된다.
@@ -129,9 +134,56 @@ CLI `hwpx-kit`으로 hwpx 문서를 다룬다. 항상 `--json`을 붙여 실행
    `hwpx-kit fill <양식.hwpx> --data <값.json> --out <결과.hwpx> --json`
    - 원본은 절대 수정되지 않는다. `--out`은 원본과 다른 경로여야 한다
    - 종료 코드 2면 `data.unmatched[]`의 사유를 사용자에게 보여주고 값이나 키를 수정해 재시도
-4. **검증**: `hwpx-kit validate <결과.hwpx> --json` — `valid: true` 확인
+4. **검증**: `hwpx-kit validate <결과.hwpx> --json` (구조) →
+   `hwpx-kit inspect <결과.hwpx> --json` (내용 — 잔여 {{마커}}·○○○ 자리표시·
+   공문 표기 위반·개인정보 잔존을 기계 검사. 종료코드 2면 issues[]를 사람 말로
+   요약해 보여주고 수정 여부 확인)
 5. **안내**: 결과 파일 경로를 알려주고, 최종 서식은 한글(한컴오피스)에서 열어 확인하도록 권한다
 
+## 일괄 생성 (메일머지) — "이 명단으로 30명분 만들어줘"
+
+위촉장·수료증·통지서처럼 **같은 양식 × 명단 N명**은 fill을 N번 돌리지 말고
+`fill-batch` 하나로:
+
+1. 명단 파일 확보 — xlsx(1행이 헤더)·csv·json 배열 모두 됨. 명단이 대화로만
+   왔으면 json으로 저장
+2. analyze로 fill_key 파악 → **템플릿 JSON** 작성: 값 속에 `{열이름}` 자리표시
+   ```json
+   {"marker:성명": "{성명}", "marker:과정명": "{과정} 과정"}
+   ```
+3. **첫 1부를 먼저 뽑아 사용자 승인** (fill로 1건) — 승인 후 전체:
+   `hwpx-kit fill-batch <양식.hwpx> --rows <명단.xlsx> --template <템플릿.json> --out-dir <폴더> --name "{성명}_위촉장.hwpx" --json`
+4. 종료코드 2면 `rows[]`에서 실패 행만 추려 보고. 파일명 충돌은 자동 `_2` 접미,
+   금지문자는 `_` 치환. 원본 불변은 fill과 동일
+5. 개인정보 든 명단 파일은 사용자 문서와 동일한 기밀 취급 — 커밋·업로드 금지
+
+## 사진·직인 넣기 — "여기 도장 찍어줘", "사진 붙여줘"
+
+`hwpx-kit image-add <문서.hwpx> --image <파일.png> ... --out <결과.hwpx>`
+- **직인/서명**: 대상 문단 원문으로 — `--at-text "서명: (인)" --width-mm 20`
+  (원문은 read 출력에서 복사. 이미지 파일은 사용자에게 받는다 — 도장을 그려주지 않는다)
+- **사진 첨부 칸**(표 안): `--table N --cell R,C --width-mm 35 --height-mm 45`
+  (증명사진 규격 예시. 좌표는 table-map으로 확인)
+- 글자처럼취급으로 들어가므로 셀 크기가 이미지에 맞을수록 깔끔 — 크게 넣으면
+  행이 부푼다. 삽입 후 validate + 한글 육안 확인 안내
+- 사용자 제공 사진·도장 이미지도 문서와 동일한 기밀 취급
+
+## 머리말·꼬리말·쪽번호 — "쪽번호 넣어줘"
+
+`hwpx-kit header-footer <문서.hwpx> [--header "텍스트"] [--footer "텍스트"] [--page-number center] --out <결과.hwpx>`
+— 쪽번호 위치는 left/center/right. 문서관리번호·대외비 표기 등에 사용.
+
+## 엑셀 표를 한글 문서에 넣기 — "이 엑셀 표 문서에 넣어줘"
+
+복붙(서식 깨짐) 대신 도구 조합으로:
+1. `hwpx-kit read <파일.xlsx> --format md` — 표 데이터 확보
+2. `outline`으로 삽입 위치(앵커 문단/표) 확인, 애매하면 사용자에게
+3. `table-new --rows R --cols C --like-table <이웃 표> --after-text "<앵커>"` —
+   문서 기존 표 서식을 차용해 새 표 생성 (이웃 표 없으면 --like-table 생략)
+4. `table-set --data <셀.json>`으로 값 기입 — 숫자는 세 자리 콤마 등 표기는
+   table-calc 스킬 관습, 헤더 행은 (0,c) 좌표
+5. validate → 경로 안내
+
 ## 예시 텍스트 교체 (보도자료 등 "예시 문구가 든 양식")
 
 누름틀/빈칸이 아니라 예시 문장이 채워진 양식(보도자료 제목·본문 등)은 `text:` 키 사용:

{hwpx_kit_cli-0.2.1 → hwpx_kit_cli-0.4.0}/src/hwpx_kit/adapter/hwpx_engine.py

@@ -671,6 +671,71 @@ class HwpxEngineAdapter:
             self._mark_sections_dirty()
         return len(targets)
 
+    _HWPUNIT_PER_MM = 7200 / 25.4  # 1mm ≈ 283.46 hwpunit
+
+    def insert_image(self, image_path: str, *, at_text: str | None = None,
+                     table_index: int | None = None, cell: tuple[int, int] | None = None,
+                     width_mm: float = 20.0, height_mm: float | None = None) -> dict:
+        """이미지를 문단(원문 앵커) 또는 표 셀에 글자처럼취급으로 삽입.
+
+        엔진 2단계: add_image(바이너리 등록) → paragraph.add_picture(배치).
+        height_mm 생략 시 정사각(width와 동일) — 비율 유지가 필요하면 호출자가 지정.
+        """
+        import os as _os
+
+        ext = _os.path.splitext(image_path)[1].lower().lstrip(".")
+        if ext == "jpeg":
+            ext = "jpg"
+        if ext not in ("png", "jpg", "bmp", "gif"):
+            raise ValueError(f"지원하지 않는 이미지 형식: .{ext} (png/jpg/bmp/gif)")
+        with open(image_path, "rb") as f:
+            image_data = f.read()
+
+        width = int(width_mm * self._HWPUNIT_PER_MM)
+        height = int((height_mm if height_mm is not None else width_mm) * self._HWPUNIT_PER_MM)
+
+        with quiet_engine():
+            if cell is not None:
+                if table_index is None:
+                    raise ValueError("--cell은 --table과 함께 지정하세요.")
+                from hwpx.tools import table_navigation as tn
+
+                tables = tn._collect_document_tables(self._doc)
+                if not 0 <= table_index < len(tables):
+                    raise ValueError(f"표 인덱스 범위 밖: {table_index} (표 {len(tables)}개)")
+                r, c = cell
+                paragraphs = tables[table_index].table.cell(r, c).paragraphs
+                target = list(paragraphs)[0]
+            else:
+                target = self._find_anchor_paragraph(anchor_text=at_text,
+                                                     after_table=table_index)
+            item_id = self._doc.add_image(image_data, ext)
+            target.add_picture(item_id, width=width, height=height, treat_as_char=True)
+        return {"binary_item_id": item_id, "width": width, "height": height}
+
+    def set_header_footer(self, *, header: str | None = None,
+                          footer: str | None = None,
+                          page_number: str | None = None) -> list[str]:
+        """머리말/꼬리말 텍스트·쪽번호 설정. 적용 항목 이름 목록 반환."""
+        applied: list[str] = []
+        align_map = {"left": "LEFT", "center": "CENTER", "right": "RIGHT"}
+        with quiet_engine():
+            if header is not None:
+                self._doc.set_header_text(header)
+                applied.append("header")
+            if footer is not None:
+                self._doc.set_footer_text(footer)
+                applied.append("footer")
+            if page_number is not None:
+                align = align_map.get(page_number.lower())
+                if align is None:
+                    raise ValueError(f"쪽번호 위치는 left/center/right 중 하나: {page_number}")
+                self._doc.set_page_number(align=align)
+                applied.append("page_number")
+        if not applied:
+            raise ValueError("--header/--footer/--page-number 중 하나는 지정하세요.")
+        return applied
+
     def save_copy(self, out_path: str) -> str:
         out_abs = os.path.abspath(out_path)
         if out_abs == self._source_path:

{hwpx_kit_cli-0.2.1 → hwpx_kit_cli-0.4.0}/src/hwpx_kit/cli.py

@@ -91,6 +91,38 @@ def _build_parser() -> argparse.ArgumentParser:
     ph.add_argument("--out", required=True, help="출력 hwpx 경로 (원본 불변)")
     ph.add_argument("--json", action="store_true")
 
+    pfb = sub.add_parser("fill-batch", help="명단 × 양식 일괄 생성 (메일머지) — 위촉장·수료증·통지서 N부")
+    pfb.add_argument("file", help="양식 hwpx")
+    pfb.add_argument("--rows", required=True, help="명단 파일 (xlsx: 1행 헤더 / csv / json 객체 배열)")
+    pfb.add_argument("--template", required=True, help="fill 데이터 JSON — 값 속 {열이름}이 행마다 치환됨")
+    pfb.add_argument("--out-dir", required=True, help="출력 폴더 (없으면 생성)")
+    pfb.add_argument("--name", required=True, help='파일명 패턴, 예: "{성명}_위촉장.hwpx" (충돌 시 _2 접미)')
+    pfb.add_argument("--json", action="store_true")
+
+    pin = sub.add_parser("inspect", help="제출 전 기계 검수 — 잔여물({{마커}}·○○○)·공문 표기(날짜·시각)·개인정보. 위반 시 종료코드 2")
+    pin.add_argument("file")
+    pin.add_argument("--checks", help="쉼표 구분: residue,gongmun,pii (생략 시 전부)")
+    pin.add_argument("--json", action="store_true")
+
+    pim = sub.add_parser("image-add", help="이미지(사진·직인) 삽입 — 문단 앵커 또는 표 셀에 글자처럼취급")
+    pim.add_argument("file")
+    pim.add_argument("--image", required=True, help="이미지 파일 (png/jpg/bmp/gif)")
+    pim.add_argument("--at-text", help="이 원문 문단에 삽입 (공백 정규화 전체 일치)")
+    pim.add_argument("--table", type=int, help="표 인덱스 (--cell과 함께)")
+    pim.add_argument("--cell", help="셀 좌표 'R,C' (0-기준)")
+    pim.add_argument("--width-mm", type=float, default=20.0, help="가로 크기 mm (기본 20)")
+    pim.add_argument("--height-mm", type=float, help="세로 크기 mm (생략 시 가로와 동일)")
+    pim.add_argument("--out", required=True, help="출력 hwpx 경로 (원본 불변)")
+    pim.add_argument("--json", action="store_true")
+
+    phf = sub.add_parser("header-footer", help="머리말/꼬리말 텍스트·쪽번호 설정")
+    phf.add_argument("file")
+    phf.add_argument("--header", help="머리말 텍스트")
+    phf.add_argument("--footer", help="꼬리말 텍스트")
+    phf.add_argument("--page-number", help="쪽번호 위치: left/center/right")
+    phf.add_argument("--out", required=True, help="출력 hwpx 경로 (원본 불변)")
+    phf.add_argument("--json", action="store_true")
+
     pra = sub.add_parser("row-add", help="표 행 추가 — 기준 행 서식·높이 승계, 내용은 비움 (세로 병합 걸리면 거부)")
     pra.add_argument("file")
     pra.add_argument("--table", type=int, required=True, help="표 인덱스 (0-기준)")
@@ -214,6 +246,40 @@ def main(argv: list[str] | None = None) -> int:
                 args.file, table=args.table, like=args.like,
                 rows=parse_rows_spec(args.rows), out_path=args.out,
             )
+        elif args.command == "fill-batch":
+            from hwpx_kit.commands.fill_batch import run_fill_batch
+
+            data = run_fill_batch(
+                args.file, rows_path=args.rows, template_path=args.template,
+                out_dir=args.out_dir, name_pattern=args.name,
+            )
+            if not data["all_ok"]:
+                exit_code = 2
+        elif args.command == "inspect":
+            from hwpx_kit.commands.inspect_doc import run_inspect
+
+            data = run_inspect(
+                args.file,
+                checks=[c.strip() for c in args.checks.split(",")] if args.checks else None,
+            )
+            if not data["clean"]:
+                exit_code = 2
+        elif args.command == "image-add":
+            from hwpx_kit.commands.image_add import run_image_add
+
+            data = run_image_add(
+                args.file, image_path=args.image, at_text=args.at_text,
+                table=args.table, cell=args.cell,
+                width_mm=args.width_mm, height_mm=args.height_mm,
+                out_path=args.out,
+            )
+        elif args.command == "header-footer":
+            from hwpx_kit.commands.header_footer import run_header_footer
+
+            data = run_header_footer(
+                args.file, header=args.header, footer=args.footer,
+                page_number=args.page_number, out_path=args.out,
+            )
         elif args.command == "row-add":
             from hwpx_kit.commands.table_rows import run_row_add