hwpx-kit-cli 0.1.1__tar.gz

hwpx_kit_cli-0.1.1/.claude-plugin/marketplace.json

@@ -0,0 +1,11 @@
+{
+  "name": "hwpx-kit-market",
+  "owner": { "name": "6aneffy", "email": "tkdgus990809@gmail.com" },
+  "plugins": [
+    {
+      "name": "hwpx-kit",
+      "source": "./",
+      "description": "한글(HWPX/HWP) 문서 자동화 스킬 모음"
+    }
+  ]
+}

hwpx_kit_cli-0.1.1/.claude-plugin/plugin.json

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

hwpx_kit_cli-0.1.1/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+*.hwpx
+!tests/fixtures/**/*.hwpx
+!templates/*.hwpx
+uv.lock
+demo-*.svg
+demo-*.hwpx
+private/
+incoming/
+node_modules/
+mcp/

hwpx_kit_cli-0.1.1/CLAUDE.md

@@ -0,0 +1,77 @@
+# hwpx-kit — 개발 컨텍스트
+
+한글(HWPX/HWP) 문서 자동화 — Claude Code 플러그인(스킬 모음) + CLI.
+"이 양식에 채워줘" 한마디로 서식 무손상 hwpx가 나오는 것이 목표.
+
+> 내부 작업 노트(전략·검증 이력·백로그)는 `private/PROJECT-NOTES.md` (gitignore 구역).
+> 세션 시작 시 그 파일을 먼저 읽을 것.
+
+## 🔴 보안 — 최우선 규칙
+
+**사용자(기관)가 제공한 문서 파일은 .env급 비밀이다.**
+
+- `incoming/`, `private/` = 기밀 구역 (gitignore 됨). 이 안의 파일과 **모든 파생물**(render SVG, fill 결과, read 추출 텍스트)은 절대 git 커밋·외부 업로드 금지
+- 코드·테스트에 사용자 문서 속 문장 하드코딩 금지 — 파일에서 동적 추출할 것 (`tests/test_real_forms.py` 참고)
+- 레포 픽스처(`tests/fixtures/real/`)에는 **공개 출처 서식만** (현재: 서울시 정보소통광장 공개 서식 + 합성 legacy-sample.hwp)
+
+## 아키텍처
+
+```
+skills/*/SKILL.md → Claude Code 플러그인 스킬들 (.claude-plugin/plugin.json이 컨테이너)
+ ├─ hwpx-form        → 양식 채우기 코어 워크플로
+ ├─ doc-create       → 백지 시작 라우터 (양식 유무 확인)
+ ├─ format-convert   → 금액한글화·날짜요일·만나이 (CLI fmt 호출 — 암산 금지 원칙)
+ ├─ gongmun-format   → 행안부 공문 규약 (지식 스킬)
+ ├─ table-calc       → 표 증감·비율·합계 (지식 + fill 착지)
+ └─ 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-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)
+         ├─ office_readers.py → PDF·DOCX·XLSX 읽기 (pypdf/python-docx/openpyxl, Node 불필요)
+         ├─ kordoc_engine.py → kordoc 3.18.0 고정 — 조건부 옵션: 한글 없는 환경의 구형 .hwp 읽기 + render + generate (Node 필요)
+         └─ (convert.py·export.py) → pyhwpx/한글 COM (.hwp→.hwpx / .hwpx→docx, Windows+한글 필요)
+```
+
+- 배포: 레포 루트가 자기-마켓플레이스 (`.claude-plugin/marketplace.json`). 로컬 개발 반영은 `claude plugin update hwpx-kit@hwpx-kit-market`. 오프라인 zip은 `scripts/build_skill_package.py`
+- MCP 서버(`mcp/`)는 공개 레포에서 제외(gitignore) — 로컬에만 유지, GUI 단계 대비. 환경변수: `HWPX_KIT_CLI` / `HWPX_KIT_CLI_ARGS` / `HWPX_KIT_CWD`. 테스트: `cd mcp && npm test`
+- kordoc는 MIT, 보험 포크: github.com/6aneffy/kordoc (업스트림 소멸 대비)
+- python-hwpx는 어댑터로 격리 — 문제 시 엔진 교체 가능하게 유지
+
+## fill_key 계약 (analyze가 주고 fill이 소비)
+
+| 키 | 대상 | 비고 |
+|---|---|---|
+| `clickhere:<이름>` | 누름틀 | 실서식으로 검증됨 |
+| `marker:<키>` | `{{키}}` 마커 | 자체 정규식(한글 키 지원) — 엔진 것은 ASCII 전용이라 쓰면 안 됨 |
+| `table:<라벨>` | 라벨 오른쪽 셀 | `#N`으로 중복 라벨 N번째 출현 지정, `> right > right` 방향 체인 가능. prefilled(기본값 찬 칸)도 덮어씀. 라벨은 공백 정규화(개행 든 병합 라벨 OK) |
+| `text:<원문>` | 예시 텍스트 교체 | 런 단위 → 실패 시 문단 전체 일치 폴백. 서식 보존 |
+| `delete:<문단원문>` | 양식 지시블록 삭제 | "(예시)", "←해당시" 류. blank-first 후 remove |
+| `bold:<원문>` / `underline:<원문>` | 글자 서식 적용 (값 "") | 런 단위 — 원문을 품은 런 전체에 적용. 부분 강조는 원문이 런 경계와 일치해야 정밀 |
+
+## 절대 규칙 (설계 불변)
+
+1. **fill은 원본 절대 수정 금지** — `--out` 사본만. 원본 경로로 저장 시 ValueError
+2. **`--json` 모드 stdout = JSON 한 줄만** — python-hwpx가 stdout에 print하므로 모든 엔진 호출은 `quiet_engine()`으로 감쌀 것. CLI는 stdout/stderr를 UTF-8로 강제(Windows cp949 문제)
+3. **lxml 요소 프록시에 `id()` 쓰지 말 것** — GC 후 id 재사용으로 비결정 버그 남 (`test_press_form_title_text_replacement_roundtrip`이 재발 감지)
+4. `skills/*/SKILL.md`(또는 templates/) 수정하면 **plugin.json 버전 범프 → 커밋·push → `claude plugin marketplace update hwpx-kit-market` → `claude plugin update hwpx-kit@hwpx-kit-market`** (버전 동일하면 업데이트 스킵됨, marketplace update 없이는 새 버전을 못 봄) — 마켓플레이스가 GitHub(6aneffy/hwpx-kit) 기준이라 push가 곧 배포다. git 추적 파일만 설치되므로 기밀 유출 불가. 🔴 레포 루트를 **로컬 경로**로 마켓플레이스 등록 금지 — 로컬 경로 설치는 gitignore 무시 통째 복사라 기밀까지 캐시에 복제된다 (실사고 1회). 구 단일 스킬 폴더(`~/.claude/skills/hwpx-kit/`)가 다시 생기면 이중 트리거되니 지울 것
+
+## 엔진 특성 (알아두면 삽질 안 함)
+
+- 표 채우기는 어댑터 자체 구현(`fill_at_label`) — 엔진 `fill_by_path`는 라벨 속 `>`(예: `<총괄>`)를 경로 구분자로 오파싱해서 안 씀. 엔진 내부 열거(`_find_label_candidates`)를 직접 사용하니 엔진 교체 시 재구현 지점
+- 표 셀 문단의 `p.remove()`는 예외 없이 무효될 수 있음 → 삭제는 blank-first
+- kordoc render는 한컴 저장본(조판 캐시)만 정밀 — 우리가 만든 파일은 `--reflow` 합성 렌더로 자동 폴백되는데 **겹침 등 부정확. 대략 확인용일 뿐, 정확한 검증은 한글로 여는 것**
+- 한글 COM(convert/export) 함정 3가지: ① SaveAs의 워드 형식 문자열은 `"OOXML"` — "DOCX"/"MSWORD"는 False 반환하며 조용히 실패 ② visible=False에서 경고 팝업 뜨면 무한대기 — `set_message_box_mode(AUTO_ANSWER_MODE)` 필수 (convert.py 상수) ③ **좀비 Hwp 프로세스가 남아 있으면 다음 COM 세션이 그냥 멈춤** — hang 시 `Stop-Process -Name Hwp -Force` 먼저
+- python-hwpx에는 표 행 추가/삭제 API 없음 (`add_table`/`merge_table_cells`뿐) — 행 개수 변경은 사용자가 한글에서, 높이 정돈은 `row-height`, 내용 비우기는 `table-clear`, 좌표 기입은 `table-set`
+- **셀 비우기는 서식을 잃지 않는다** (실험 확인): `set_cell_text('')`가 텍스트만 지우고 빈 런의 글자모양(charPr) 참조는 유지 → 재기입 시 원래 서식 물려받음. table-clear가 안전한 근거
+- 병합 셀은 엔진 표 맵에서 같은 텍스트가 격자 전체에 복제되어 보임 — 어댑터 table_map()이 셀별 `is_anchor`를 덧붙이고, 라벨 후보·#N 열거는 anchor만 센다 (복제를 세면 #N 오염 + 같은 논리 셀 이중 기입으로 값 유실)
+- analyze의 마커 탐지는 본문 문단만 훑음 — 표 셀 안 {{마커}}는 못 잡음 (fill은 됨) ← 개선 후보
+
+## 개발 환경
+
+- Python 3.11 venv (`.venv`), `uv sync` / `uv run pytest`
+- 실행: `uv run hwpx-kit <명령>` 또는 전역 `hwpx-kit`
+- 작업 방식: feature 브랜치 → 테스트 통과 → main 머지. TDD
+- 커밋 게이트로 쓰는 테스트 명령은 파이프로 자르지 말 것 (종료코드 삼킴). 한글 COM 왕복 테스트는 간헐 플레이크 — 실패 시 한 번 재실행으로 판별

hwpx_kit_cli-0.1.1/LICENSE

@@ -0,0 +1,209 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+---
+
+Copyright 2026 6aneffy (tkdgus990809@gmail.com)
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.

hwpx_kit_cli-0.1.1/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: hwpx-kit-cli
+Version: 0.1.1
+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
+Project-URL: Issues, https://github.com/6aneffy/hwpx-kit/issues
+Author-email: 6aneffy <tkdgus990809@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: claude-code,document-automation,hangul,hwp,hwpx,korean
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Office Suites
+Requires-Python: >=3.10
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pypdf>=6.14.2
+Requires-Dist: python-docx>=1.2.0
+Requires-Dist: python-hwpx<3,>=2.24
+Provides-Extra: convert
+Requires-Dist: pyhwpx; (sys_platform == 'win32') and extra == 'convert'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# hwpx-kit
+
+**한글(HWPX) 문서 자동화 — Claude Code 플러그인 & CLI**
+
+*"이 양식에 채워줘" 한마디로, 서식 무손상 한글 문서가 나옵니다.*
+
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![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-145%20passing-brightgreen.svg)](tests/)
+
+</div>
+
+---
+
+## 무엇이 되나
+
+한글(HWP/HWPX)은 한국 공공·기업 문서의 표준이지만, AI가 다룰 수 있는 도구가 사실상 없었습니다.
+hwpx-kit은 **AI 에이전트가 한글 문서를 읽고, 채우고, 고치고, 새로 만들 수 있게** 하는 도구 모음입니다.
+
+```
+👤 "이 양식에 채워줘"                    → 서식(폰트·표·조판) 무손상으로 값만 채운 사본
+👤 "이 기획서를 ○○사업용으로 바꿔줘"      → 기존 문서를 양식 삼아 내용 전면 교체
+👤 "한글로 새 기획서 만들어줘"            → 내장 템플릿으로 표지·장·표 갖춘 문서 생성
+👤 "예산 앞에 장 하나 추가하고 표 넣어줘"   → 장 헤더 복제·새 표 생성·쪽나눔까지
+👤 "금액 한글로 병기해줘"                → 금12,340원(금일만이천삼백사십원) — 계산 착오 0
+👤 "이거 워드로도 줘" / "PPT로 만들어줘"   → docx 변환 / 발표자료 재구성
+```
+
+모든 채우기는 **원본을 절대 수정하지 않고** 사본에만 씁니다. 실제 공공기관 서식
+(보도자료·신청서·계획서·회의록·공고문)으로 왕복 검증했습니다.
+
+| | hwpx-kit 없이 | hwpx-kit으로 |
+|---|---|---|
+| 양식 채우기 | 한글 열고 칸마다 복붙, 서식 깨지면 수작업 복구 | 파일 주고 한마디 — 서식 무손상 사본 |
+| 새 기획서 | 백지에서 표지·표·조판 직접 | 내장 템플릿에 내용만 — 몇 분 완주 |
+| 금액 병기 | 손으로 한글 표기 (오타 위험) | 결정론 계산 — `금12,340원(금일만이천삼백사십원)` |
+| AI에게 한글 파일 | 못 읽음 · PDF 변환 우회 | hwpx·hwp 직접 읽기/쓰기 |
+
+**이런 분들을 위해 만들었습니다**: 공공기관·학교의 서식 담당자, 사업계획서를 반복 작성하는
+창업자·연구자, 한글 문서를 AI 워크플로에 넣고 싶은 개발자.
+
+## 30초 설치
+
+Claude Code에서:
+
+```
+/plugin marketplace add 6aneffy/hwpx-kit
+/plugin install hwpx-kit@hwpx-kit-market
+```
+
+이게 전부입니다. CLI 런타임은 첫 사용 때 스킬이 알아서 설치를 진행합니다
+(PC에 Python 3.10+만 있으면 됩니다).
+
+<details>
+<summary>수동 설치</summary>
+
+```bash
+pip install git+https://github.com/6aneffy/hwpx-kit.git
+```
+
+```powershell
+# Windows 일괄 (CLI + 플러그인 등록)
+irm https://raw.githubusercontent.com/6aneffy/hwpx-kit/main/install.ps1 | iex
+```
+</details>
+
+## 스킬 (Claude Code 플러그인)
+
+| 스킬 | 트리거 | 역할 |
+|------|--------|------|
+| **hwpx-form** | "이 양식에 채워줘" | 분석→채우기→검증 코어 워크플로. 표 조작·강조·워드 출력 포함 |
+| **doc-create** | "기획서 만들어줘" (파일 없이) | 백지 생성 라우터 — 내장 템플릿(표지·장 헤더·표 골격) 기반 |
+| **format-convert** | "금액 한글로", "요일 붙여줘" | 금액 병기·날짜 요일·만나이 — 결정론 계산 (LLM 암산 금지) |
+| **gongmun-format** | "공문 형식으로" | 행안부 공문 규약 — 글머리 위계(□○-※\*), 표기, 텍스트 정리 |
+| **table-calc** | "증감 채워줘" | 보고서 표 증감(△·%p)·비율·합계 계산과 관습 표기 |
+| **office-export** | "워드로", "PPT로" | docx 변환(한글 COM) / pptx·xlsx 재구성 |
+
+스킬은 사용자에게 **필수 정보를 먼저 묻고**(선택지 UI), 초안을 확정받은 뒤 작업합니다.
+말하지 않은 값을 지어내지 않습니다.
+
+## CLI
+
+모든 명령은 `--json`으로 한 줄 JSON 봉투(`ok`/`data`/`warnings`/`error`)를 반환합니다.
+종료 코드: `0` 성공 · `1` 오류 · `2` 부분 성공.
+
+```bash
+# 읽기·분석
+hwpx-kit analyze 양식.hwpx --json            # 채울 수 있는 필드 탐지 (fill_key 반환)
+hwpx-kit read 문서 --format md               # 본문 추출 — hwpx·PDF·DOCX·XLSX 내장 지원
+hwpx-kit outline 문서.hwpx --json            # 문단·표 배치 지도 (삽입 앵커 탐색)
+hwpx-kit table-map 문서.hwpx --table 3 --json # 표 셀 좌표·병합 상태
+hwpx-kit validate 문서.hwpx --json           # 구조 검증
+
+# 채우기·편집 (원본 불변 — 항상 --out 사본)
+hwpx-kit fill 양식.hwpx --data 값.json --out 결과.hwpx
+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 # 표 통째 복제 (서식·병합 유지)
+hwpx-kit table-new 문서.hwpx --rows 6 --cols 4 --like-table 3 --after-text "앵커" --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 fmt --amount 12340 --json           # 금12,340원(금일만이천삼백사십원)
+hwpx-kit fmt --date 20260101 --json          # 2026.1.1.(목)
+hwpx-kit convert 문서.hwp --json             # .hwp → .hwpx (Windows + 한글)
+hwpx-kit export 문서.hwpx --to docx --json   # 워드로 내보내기 (Windows + 한글)
+hwpx-kit generate 초안.md --out 새문서.hwpx   # Markdown → 공문서 (kordoc)
+hwpx-kit render 문서.hwpx --out p.svg        # SVG 미리보기 (kordoc)
+```
+
+## fill_key 계약
+
+`analyze`가 주는 키를 그대로 데이터 JSON의 키로 씁니다.
+
+| 키 | 대상 | 예시 |
+|----|------|------|
+| `clickhere:<이름>` | 누름틀 필드 | `"clickhere:신청자": "김철수"` |
+| `marker:<키>` | `{{키}}` 마커 | `"marker:출장기간": "7/14~7/16"` |
+| `table:<라벨>` | 라벨 오른쪽 셀 | `"table:성명": "김철수"` |
+| `table:<라벨>#N` | 같은 라벨 N번째 | `"table:담당 부서#2": "운영과"` |
+| `table:<라벨> > <방향>` | 방향 체인 | `"table:과 장 > right > right": "010-…"` |
+| `text:<원문>` | 문장 교체 (서식 보존) | `"text:○○○ 사업": "청년 AI교육 사업"` |
+| `delete:<문단원문>` | 안내문 삭제 | `"delete:(예시입니다)": ""` |
+| `bold:` / `underline:<원문>` | 굵게·밑줄 | `"bold:핵심 성과": ""` |
+
+## 요구 사항
+
+| 기능 | 필요한 것 |
+|------|-----------|
+| 분석·채우기·검증·표 조작·표기 변환·PDF/DOCX/XLSX 읽기 | **Python 3.10+ 만** (순수 파이썬) |
+| `.hwp` 변환, 워드(docx) 내보내기 | Windows + 한글(한컴오피스) |
+| 한글 없는 환경(Mac 등)의 구형 `.hwp` 읽기, MD→HWPX, SVG | [kordoc](https://github.com/chrisryugj/kordoc) (Node 18+, 선택) |
+
+## 아키텍처
+
+```
+Claude Code 스킬 6종 ──→  hwpx-kit CLI (19 명령, JSON 봉투)
+                              └─ adapter/  ← 엔진 격리 계층
+                                  ├─ python-hwpx    hwpx 분석·채우기·표 조작
+                                  ├─ pypdf·python-docx·openpyxl   타 포맷 읽기
+                                  ├─ pyhwpx(COM)    .hwp 변환·docx 내보내기
+                                  └─ kordoc         구형 .hwp·생성·렌더 (선택)
+templates/ 기본 계획서 템플릿 (표지·장 헤더·표 골격, 마커 내장)
+```
+
+설계 불변 원칙: **① 원본 절대 수정 금지 ② `--json` stdout은 봉투 한 줄만
+③ 서식은 항상 보존** (셀을 비워도 글자모양이 유지되어 재기입 시 원래 서식을 물려받음).
+
+> 🚧 같은 코어를 MCP 서버로 노출하는 버전도 제작 중입니다 (Claude Desktop 등 MCP 클라이언트용).
+
+## 검증
+
+- 자동 테스트 145개 (pytest)
+- 실서식 수렴 테스트: 보도자료·신청서·계획서·회의록·공고문 5계열,
+  실제 공공기관 문서 30여 종으로 analyze→fill→validate 왕복
+- 실사용 시나리오 테스트 3회 (백지 생성 12분 완주, 장·표 동적 추가, 보도자료 변환)
+
+## 라이선스
+
+[Apache-2.0](LICENSE) · © 2026 [6aneffy](https://github.com/6aneffy)
+
+이슈·PR 환영합니다. 특히 실제 기관 양식에서의 analyze/fill 실패 사례 제보가 가장 값집니다
+(단, **기관 내부 문서를 이슈에 첨부하지 마세요** — 재현 가능한 합성 예시로 부탁드립니다).