python-hwpx 5.0.1__tar.gz → 5.0.2__tar.gz

{python_hwpx-5.0.1/src/python_hwpx.egg-info → python_hwpx-5.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 5.0.1
+Version: 5.0.2
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -14,8 +14,11 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Text Processing :: Markup :: XML
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -63,26 +66,33 @@ Dynamic: license-file
 
 <p align="center">한국어 | <a href="README_EN.md">English</a></p>
 
-기존 문서는 손댄 곳만 고치고(미수정 영역은 바이트 그대로), 새 문서는 실제
-한컴오피스가 받아들이는 형태로 만듭니다. HWPX는 ZIP+XML(OWPML/OPC) 구조라
-Windows·macOS·Linux·CI 어디서든 순수 파이썬으로 동작합니다. 한컴오피스도
-Windows도 필요하지 않으므로 **ChatGPT 채팅 환경에서도 HWPX 문서를 만들고
-고칠 수 있습니다** — 파이썬이 도는 곳이면 됩니다.
+한컴오피스가 없어도 됩니다. HWPX는 ZIP+XML(OWPML) 포맷이라 순수 파이썬만으로
+읽고, 고치고, 새로 만들 수 있습니다 — Windows·macOS·Linux·CI, 그리고
+**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다. 기존 문서는 손댄
+곳만 바뀌고 나머지는 바이트 그대로 유지되며, 새 문서는 실제 한컴오피스가 여는
+형태로 만들어집니다.
 
-| 계층 | 저장소 | 정본 책임 |
-|---|---|---|
-| Core | [`python-hwpx`](https://github.com/airmang/python-hwpx) | HWPX package/object model·OPC/OXML·직렬화·재사용 primitive |
-| Automation | [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation) | Python 자동화·워크플로·profile/policy·렌더·선택형 MCP adapter |
-| Judgment | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) | 에이전트 intent/genre 판단·ambiguity 처리·plugin/skill 가이드 |
+<p align="center">
+  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/assets/chatgpt-formfill.png" width="760" alt="일반 ChatGPT 대화에 hwpx 양식을 올려 지도안 작성을 부탁하고, 양식이 유지된 채 채워진 문서를 돌려받는 화면">
+</p>
+<p align="center"><sub>일반 ChatGPT 대화 — 양식 <code>.hwpx</code>를 올리고 말로 부탁하면, 서식을 유지한 채 채워진 문서가 돌아옵니다.</sub></p>
 
-이 저장소는 위 표의 Core 정본입니다. 5.0의 모듈 소유권, 삭제 경로 재등장
-방지, 의존성 허용 범위는
-[제품 경계 문서](docs/architecture/product-boundary.md)에 고정돼 있습니다.
+**ChatGPT에서 그대로 따라 하기** — 문서를 올리면서 이렇게 부탁하면 됩니다:
 
-> **Python 블록 판정:** 이 current manual의 모든 Python 블록은
-> [실행 분류 ledger](docs/python-example-ledger.json)에 exact source digest와 함께
-> 동결돼 있습니다. **독립 실행 예제** 표시가 없는 블록은 기존 입력 파일이나 앞
-> 문맥을 요구하는 조각이며, 그대로 실행할 수 있는 예제로 간주하지 않습니다.
+```text
+이 .hwpx 파일을 python-hwpx 라이브러리로 열어서 작업해줘.
+(pip install python-hwpx 로 설치하면 돼)
+양식과 서식은 그대로 두고, ○○만 바꿔서 새 파일로 돌려줘.
+```
+
+설치부터 결과 파일까지 대화 안에서 끝납니다 — 내 컴퓨터에 파이썬이 없어도 됩니다.
+AI 도구가 정확한 API를 배우도록 [llms.txt](https://airmang.github.io/python-hwpx/llms.txt)도 제공합니다.
+
+| | 저장소 | 역할 |
+|---|---|---|
+| 📦 | [`python-hwpx`](https://github.com/airmang/python-hwpx) | HWPX 문서를 읽고·고치고·만드는 순수 파이썬 엔진 |
+| 🔌 | [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation) | 저작·양식 채움 워크플로, `hwpx` CLI, 선택형 MCP 서버 |
+| 🎯 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) | 에이전트가 알맞은 도구를 고르도록 돕는 플러그인/스킬 번들 |
 
 ## 시작하기
 
@@ -90,11 +100,6 @@ Windows도 필요하지 않으므로 **ChatGPT 채팅 환경에서도 HWPX 문
 pip install python-hwpx      # Python 3.10+
 ```
 
-> **5.x 호환 extra:** `pip install "python-hwpx[visual]"`은 기존 설치 명령을
-> 깨뜨리지 않기 위해 계속 허용되지만, `visual` extra는 비어 있어 PDF·이미지
-> 렌더링 의존성을 설치하지 않습니다. 렌더·PDF 이미징 실행은
-> `python-hwpx-automation[oracle]`이 소유합니다.
-
 ```python
 from hwpx import HwpxDocument
 
@@ -103,23 +108,24 @@ doc.add_paragraph("자동화로 추가한 문단입니다.")
 doc.save_to_path("보고서-수정.hwpx")
 ```
 
-백지에서 새 문서를 만들 때는 `HwpxDocument.new()`로 시작해 같은 API로
-문단·표·머리말을 채우고 `save_to_path()`로 저장합니다.
-
-문서 저작·양식 채움·시험지 조판 같은 상위 워크플로가 필요하면
+백지에서 시작할 때는 `HwpxDocument.new()`로 만들어 같은 API로 문단·표·머리말을
+채우면 됩니다. 문서 저작·양식 채움·시험지 조판 같은 상위 워크플로가 필요하면
 [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)을
-함께 설치하세요. MCP SDK 없이 같은 환경에서 그대로 동작합니다.
+함께 설치하세요.
+
+> 기존 설치 명령 호환을 위해 `pip install "python-hwpx[visual]"`도 계속
+> 동작합니다. 다만 이 extra는 비어 있어 렌더·PDF 의존성을 설치하지 않습니다 —
+> 그 역할은 `python-hwpx-automation[oracle]`이 맡습니다.
 
 ## 무엇을 하나
 
-- **읽기·추출** — 텍스트/HTML/rich Markdown 내보내기(서식·중첩 표·각주 보존), XPath 객체 탐색
-- **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 등 서식
-- **양식 채우기** — 라벨·경로 기반 셀 채움, 바이트 보존 구조 편집(행·열·오토핏·shrink-to-fit)
-- **생성·일괄 처리** — 문단·표·이미지·목차·상호참조 저작, 명시적 sanitizer 기반 mail merge, 텍스트 diff
-- **변경추적·목차** — redline 저작, 네이티브 목차·상호참조
-- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 모든 쓰기에 영수증(`MutationReport`) — 번들 XSD는 느슨한 구조 스키마이며 OWPML 전체 검증은 아닙니다
+- **읽기·추출** — 텍스트/HTML/Markdown 내보내기 (서식·중첩 표·각주 보존)
+- **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 같은 서식
+- **양식 채우기** — 라벨로 셀을 찾아 값만 채우기, 행·열 조정 같은 구조 편집도 바이트 보존으로
+- **생성·일괄 처리** — 새 문서 저작, 목차·상호참조, mail merge, 텍스트 diff, 변경추적(redline)
+- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 모든 저장에 영수증(`MutationReport`)
 
-자세한 내용: [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [안정 API 표면](docs/stable-api.md) · [예제](docs/examples.md)
+자세한 내용: [5분 퀵스타트](docs/quickstart.md) · [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [예제](docs/examples.md)
 
 ### 양식 채우기 — 서식은 그대로, 값만
 
@@ -144,22 +150,31 @@ print(report.preservation.untouched_part_payloads.to_dict())
 ```
 
 요청한 보존 등급을 지킬 수 없으면 아무것도 쓰지 않고 실패합니다(fail-closed).
-전체 규칙은 [안전한 쓰기 계약](docs/safe-write-contract.md)에 있습니다.
+전체 규칙: [안전한 쓰기 계약](docs/safe-write-contract.md).
+
+*예제 중 **독립 실행 예제** 표시가 없는 블록은 여러분의 기존 문서를 입력으로
+쓰는 조각입니다. 예제별 Python 블록 판정은
+[실행 ledger](docs/python-example-ledger.json)에 동결돼 있습니다.*
 
 ## 실측으로 말합니다
 
-산출물 전수를 실제 한컴오피스로 측정해 그대로 공개합니다(동결 코퍼스 N=497):
+만든 파일이 실제 한컴오피스에서 열리는지, 동결 코퍼스 전수(N=497)를 재서
+그대로 공개합니다:
 
-- **한컴 오픈 476/476 all-pass** — 우리가 만든 파일을 실한컴이 전부 엽니다
-- **미수정 영역 바이트 보존 497/497** · 개인정보 0-leak
-- **렌더 검증 416/476** + 정직 버킷 43 — 한컴 자체가 PDF export를 거부한 케이스도 숨기지 않고 집계
-- 낮은 숫자도 그대로 발행합니다 — 전체 수치·주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html)
+- **한컴 열림 476/476** — 우리가 만든 파일을 실한컴이 전부 엽니다
+- **미수정 영역 바이트 보존 497/497** · 개인정보 유출 0
+- **렌더 검증 416/476** — 한컴 자체가 PDF 내보내기를 거부한 43건도 숨기지 않고 집계
+- 전체 수치와 주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html) · 기능별 등급: [지원 매트릭스](docs/support-matrix.md)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/assets/hancom-open-generated.png" width="760" alt="ChatGPT 실행 환경에서 python-hwpx로 생성한 HWPX 문서를 실제 한컴오피스에서 연 모습">
+</p>
+<p align="center"><sub>ChatGPT 실행 환경에서 생성한 문서를 실제 한컴오피스로 연 모습.</sub></p>
 
-기능별로 되는 것과 안 되는 것은 [지원 매트릭스](docs/support-matrix.md)에 등급으로
-명시되어 있습니다. 현재 개발 상태는 Alpha입니다 — API는 바뀔 수 있습니다.
+현재 개발 상태는 Alpha입니다 — API는 바뀔 수 있습니다.
 
-> 위 수치는 *생성물 수용률* 축입니다(만든 파일을 실한컴이 받는가). 문서 *파싱 recall*과는
-> 다른 축이므로 파서 프로젝트 수치와 병치 비교하지 마세요.
+> 위 수치는 "만든 파일을 실한컴이 받아주는가"라는 축입니다. 문서 파싱 성능과는
+> 다른 축이므로 파서 프로젝트 수치와 직접 비교하지 마세요.
 
 ## 어디서 쓰나
 
@@ -172,11 +187,10 @@ print(report.preservation.untouched_part_payloads.to_dict())
 | Codex 마켓플레이스 플러그인 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) 설치 |
 | Claude Code · Hermes · OpenClaw | 같은 MCP 서버를 각 클라이언트에 등록 ([`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)) |
 
-실측: 일반 ChatGPT 대화에 `.hwpx`를 올리고 python-hwpx 설치를 요청했을 때 PyPI
-설치가 성공했고, 문서를 편집해 되받았습니다. 다만 파이썬 실행과 네트워크 허용
-범위는 플랜·설정에 따라 다르므로 모든 계정에서 보장되는 경로는 아닙니다.
-네트워크가 막힌 실행 환경에서는 wheel 파일을 함께 업로드하면 오프라인 설치로
-같은 여정이 됩니다.
+실제로 일반 ChatGPT 대화에 `.hwpx`를 올리고 설치를 부탁했을 때 PyPI 설치와
+편집·되받기까지 동작하는 것을 확인했습니다. 파이썬 실행과 네트워크 허용 범위는
+플랜·설정에 따라 다르며, 네트워크가 막힌 환경에서는 wheel 파일을 함께 올리면
+오프라인 설치로 같은 여정이 됩니다.
 
 ## 비교
 
@@ -192,11 +206,10 @@ print(report.preservation.untouched_part_payloads.to_dict())
 
 ## 알려진 제약
 
-- `add_shape()` / `add_control()`은 한/글이 요구하는 모든 하위 요소를 생성하지 않는
-  저수준 탈출구입니다. 그대로 저장한 문서는 한/글이 열지 못하며, 신호는 호출 시점의
-  경고 하나뿐입니다(저장도 패키지 검증도 막지 않습니다). 도형은 `add_line()` /
+- `add_shape()` / `add_control()`은 저수준 탈출구라, 그대로 저장하면 한/글이
+  열지 못하는 파일이 됩니다(호출 시 경고만 나옵니다). 도형은 `add_line()` /
   `add_rectangle()` / `add_ellipse()`를 쓰세요.
-- 그림은 단순 개체 생성까지 지원하며, 그룹·효과 같은 복잡 개체 생성은 미지원입니다.
+- 그림은 단순 개체 생성까지 지원합니다 (그룹·효과 미지원).
 - 암호화된 HWPX는 지원하지 않습니다.
 
 ## 기여하기
@@ -204,11 +217,12 @@ print(report.preservation.untouched_part_payloads.to_dict())
 [help wanted](https://github.com/airmang/python-hwpx/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) ·
 [로드맵](https://github.com/airmang/python-hwpx/milestones) ·
 [Discussions](https://github.com/airmang/python-hwpx/discussions) ·
-[내부 실전 가이드](docs/internals/) ·
 [CONTRIBUTING](CONTRIBUTING.md)
 
 HWPX 내부 구조가 처음이라면 [내부 실전 가이드](docs/internals/)부터 — 실제 한/글
 동작에서 확인된 조판 캐시·목차 필드·OPC 재패킹 같은 실전 지식을 정리해 두었습니다.
+공개 API의 안정 범위는 [안정 API 표면](docs/stable-api.md), 계층 간 소유권은
+[제품 경계 문서](docs/architecture/product-boundary.md)에 있습니다.
 
 ## 감사의 말
 

{python_hwpx-5.0.1 → python_hwpx-5.0.2}/README.md

@@ -15,26 +15,33 @@
 
 <p align="center">한국어 | <a href="README_EN.md">English</a></p>
 
-기존 문서는 손댄 곳만 고치고(미수정 영역은 바이트 그대로), 새 문서는 실제
-한컴오피스가 받아들이는 형태로 만듭니다. HWPX는 ZIP+XML(OWPML/OPC) 구조라
-Windows·macOS·Linux·CI 어디서든 순수 파이썬으로 동작합니다. 한컴오피스도
-Windows도 필요하지 않으므로 **ChatGPT 채팅 환경에서도 HWPX 문서를 만들고
-고칠 수 있습니다** — 파이썬이 도는 곳이면 됩니다.
+한컴오피스가 없어도 됩니다. HWPX는 ZIP+XML(OWPML) 포맷이라 순수 파이썬만으로
+읽고, 고치고, 새로 만들 수 있습니다 — Windows·macOS·Linux·CI, 그리고
+**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다. 기존 문서는 손댄
+곳만 바뀌고 나머지는 바이트 그대로 유지되며, 새 문서는 실제 한컴오피스가 여는
+형태로 만들어집니다.
 
-| 계층 | 저장소 | 정본 책임 |
-|---|---|---|
-| Core | [`python-hwpx`](https://github.com/airmang/python-hwpx) | HWPX package/object model·OPC/OXML·직렬화·재사용 primitive |
-| Automation | [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation) | Python 자동화·워크플로·profile/policy·렌더·선택형 MCP adapter |
-| Judgment | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) | 에이전트 intent/genre 판단·ambiguity 처리·plugin/skill 가이드 |
+<p align="center">
+  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/assets/chatgpt-formfill.png" width="760" alt="일반 ChatGPT 대화에 hwpx 양식을 올려 지도안 작성을 부탁하고, 양식이 유지된 채 채워진 문서를 돌려받는 화면">
+</p>
+<p align="center"><sub>일반 ChatGPT 대화 — 양식 <code>.hwpx</code>를 올리고 말로 부탁하면, 서식을 유지한 채 채워진 문서가 돌아옵니다.</sub></p>
 
-이 저장소는 위 표의 Core 정본입니다. 5.0의 모듈 소유권, 삭제 경로 재등장
-방지, 의존성 허용 범위는
-[제품 경계 문서](docs/architecture/product-boundary.md)에 고정돼 있습니다.
+**ChatGPT에서 그대로 따라 하기** — 문서를 올리면서 이렇게 부탁하면 됩니다:
 
-> **Python 블록 판정:** 이 current manual의 모든 Python 블록은
-> [실행 분류 ledger](docs/python-example-ledger.json)에 exact source digest와 함께
-> 동결돼 있습니다. **독립 실행 예제** 표시가 없는 블록은 기존 입력 파일이나 앞
-> 문맥을 요구하는 조각이며, 그대로 실행할 수 있는 예제로 간주하지 않습니다.
+```text
+이 .hwpx 파일을 python-hwpx 라이브러리로 열어서 작업해줘.
+(pip install python-hwpx 로 설치하면 돼)
+양식과 서식은 그대로 두고, ○○만 바꿔서 새 파일로 돌려줘.
+```
+
+설치부터 결과 파일까지 대화 안에서 끝납니다 — 내 컴퓨터에 파이썬이 없어도 됩니다.
+AI 도구가 정확한 API를 배우도록 [llms.txt](https://airmang.github.io/python-hwpx/llms.txt)도 제공합니다.
+
+| | 저장소 | 역할 |
+|---|---|---|
+| 📦 | [`python-hwpx`](https://github.com/airmang/python-hwpx) | HWPX 문서를 읽고·고치고·만드는 순수 파이썬 엔진 |
+| 🔌 | [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation) | 저작·양식 채움 워크플로, `hwpx` CLI, 선택형 MCP 서버 |
+| 🎯 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) | 에이전트가 알맞은 도구를 고르도록 돕는 플러그인/스킬 번들 |
 
 ## 시작하기
 
@@ -42,11 +49,6 @@ Windows도 필요하지 않으므로 **ChatGPT 채팅 환경에서도 HWPX 문
 pip install python-hwpx      # Python 3.10+
 ```
 
-> **5.x 호환 extra:** `pip install "python-hwpx[visual]"`은 기존 설치 명령을
-> 깨뜨리지 않기 위해 계속 허용되지만, `visual` extra는 비어 있어 PDF·이미지
-> 렌더링 의존성을 설치하지 않습니다. 렌더·PDF 이미징 실행은
-> `python-hwpx-automation[oracle]`이 소유합니다.
-
 ```python
 from hwpx import HwpxDocument
 
@@ -55,23 +57,24 @@ doc.add_paragraph("자동화로 추가한 문단입니다.")
 doc.save_to_path("보고서-수정.hwpx")
 ```
 
-백지에서 새 문서를 만들 때는 `HwpxDocument.new()`로 시작해 같은 API로
-문단·표·머리말을 채우고 `save_to_path()`로 저장합니다.
-
-문서 저작·양식 채움·시험지 조판 같은 상위 워크플로가 필요하면
+백지에서 시작할 때는 `HwpxDocument.new()`로 만들어 같은 API로 문단·표·머리말을
+채우면 됩니다. 문서 저작·양식 채움·시험지 조판 같은 상위 워크플로가 필요하면
 [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)을
-함께 설치하세요. MCP SDK 없이 같은 환경에서 그대로 동작합니다.
+함께 설치하세요.
+
+> 기존 설치 명령 호환을 위해 `pip install "python-hwpx[visual]"`도 계속
+> 동작합니다. 다만 이 extra는 비어 있어 렌더·PDF 의존성을 설치하지 않습니다 —
+> 그 역할은 `python-hwpx-automation[oracle]`이 맡습니다.
 
 ## 무엇을 하나
 
-- **읽기·추출** — 텍스트/HTML/rich Markdown 내보내기(서식·중첩 표·각주 보존), XPath 객체 탐색
-- **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 등 서식
-- **양식 채우기** — 라벨·경로 기반 셀 채움, 바이트 보존 구조 편집(행·열·오토핏·shrink-to-fit)
-- **생성·일괄 처리** — 문단·표·이미지·목차·상호참조 저작, 명시적 sanitizer 기반 mail merge, 텍스트 diff
-- **변경추적·목차** — redline 저작, 네이티브 목차·상호참조
-- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 모든 쓰기에 영수증(`MutationReport`) — 번들 XSD는 느슨한 구조 스키마이며 OWPML 전체 검증은 아닙니다
+- **읽기·추출** — 텍스트/HTML/Markdown 내보내기 (서식·중첩 표·각주 보존)
+- **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 같은 서식
+- **양식 채우기** — 라벨로 셀을 찾아 값만 채우기, 행·열 조정 같은 구조 편집도 바이트 보존으로
+- **생성·일괄 처리** — 새 문서 저작, 목차·상호참조, mail merge, 텍스트 diff, 변경추적(redline)
+- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 모든 저장에 영수증(`MutationReport`)
 
-자세한 내용: [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [안정 API 표면](docs/stable-api.md) · [예제](docs/examples.md)
+자세한 내용: [5분 퀵스타트](docs/quickstart.md) · [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [예제](docs/examples.md)
 
 ### 양식 채우기 — 서식은 그대로, 값만
 
@@ -96,22 +99,31 @@ print(report.preservation.untouched_part_payloads.to_dict())
 ```
 
 요청한 보존 등급을 지킬 수 없으면 아무것도 쓰지 않고 실패합니다(fail-closed).
-전체 규칙은 [안전한 쓰기 계약](docs/safe-write-contract.md)에 있습니다.
+전체 규칙: [안전한 쓰기 계약](docs/safe-write-contract.md).
+
+*예제 중 **독립 실행 예제** 표시가 없는 블록은 여러분의 기존 문서를 입력으로
+쓰는 조각입니다. 예제별 Python 블록 판정은
+[실행 ledger](docs/python-example-ledger.json)에 동결돼 있습니다.*
 
 ## 실측으로 말합니다
 
-산출물 전수를 실제 한컴오피스로 측정해 그대로 공개합니다(동결 코퍼스 N=497):
+만든 파일이 실제 한컴오피스에서 열리는지, 동결 코퍼스 전수(N=497)를 재서
+그대로 공개합니다:
 
-- **한컴 오픈 476/476 all-pass** — 우리가 만든 파일을 실한컴이 전부 엽니다
-- **미수정 영역 바이트 보존 497/497** · 개인정보 0-leak
-- **렌더 검증 416/476** + 정직 버킷 43 — 한컴 자체가 PDF export를 거부한 케이스도 숨기지 않고 집계
-- 낮은 숫자도 그대로 발행합니다 — 전체 수치·주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html)
+- **한컴 열림 476/476** — 우리가 만든 파일을 실한컴이 전부 엽니다
+- **미수정 영역 바이트 보존 497/497** · 개인정보 유출 0
+- **렌더 검증 416/476** — 한컴 자체가 PDF 내보내기를 거부한 43건도 숨기지 않고 집계
+- 전체 수치와 주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html) · 기능별 등급: [지원 매트릭스](docs/support-matrix.md)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/assets/hancom-open-generated.png" width="760" alt="ChatGPT 실행 환경에서 python-hwpx로 생성한 HWPX 문서를 실제 한컴오피스에서 연 모습">
+</p>
+<p align="center"><sub>ChatGPT 실행 환경에서 생성한 문서를 실제 한컴오피스로 연 모습.</sub></p>
 
-기능별로 되는 것과 안 되는 것은 [지원 매트릭스](docs/support-matrix.md)에 등급으로
-명시되어 있습니다. 현재 개발 상태는 Alpha입니다 — API는 바뀔 수 있습니다.
+현재 개발 상태는 Alpha입니다 — API는 바뀔 수 있습니다.
 
-> 위 수치는 *생성물 수용률* 축입니다(만든 파일을 실한컴이 받는가). 문서 *파싱 recall*과는
-> 다른 축이므로 파서 프로젝트 수치와 병치 비교하지 마세요.
+> 위 수치는 "만든 파일을 실한컴이 받아주는가"라는 축입니다. 문서 파싱 성능과는
+> 다른 축이므로 파서 프로젝트 수치와 직접 비교하지 마세요.
 
 ## 어디서 쓰나
 
@@ -124,11 +136,10 @@ print(report.preservation.untouched_part_payloads.to_dict())
 | Codex 마켓플레이스 플러그인 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) 설치 |
 | Claude Code · Hermes · OpenClaw | 같은 MCP 서버를 각 클라이언트에 등록 ([`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)) |
 
-실측: 일반 ChatGPT 대화에 `.hwpx`를 올리고 python-hwpx 설치를 요청했을 때 PyPI
-설치가 성공했고, 문서를 편집해 되받았습니다. 다만 파이썬 실행과 네트워크 허용
-범위는 플랜·설정에 따라 다르므로 모든 계정에서 보장되는 경로는 아닙니다.
-네트워크가 막힌 실행 환경에서는 wheel 파일을 함께 업로드하면 오프라인 설치로
-같은 여정이 됩니다.
+실제로 일반 ChatGPT 대화에 `.hwpx`를 올리고 설치를 부탁했을 때 PyPI 설치와
+편집·되받기까지 동작하는 것을 확인했습니다. 파이썬 실행과 네트워크 허용 범위는
+플랜·설정에 따라 다르며, 네트워크가 막힌 환경에서는 wheel 파일을 함께 올리면
+오프라인 설치로 같은 여정이 됩니다.
 
 ## 비교
 
@@ -144,11 +155,10 @@ print(report.preservation.untouched_part_payloads.to_dict())
 
 ## 알려진 제약
 
-- `add_shape()` / `add_control()`은 한/글이 요구하는 모든 하위 요소를 생성하지 않는
-  저수준 탈출구입니다. 그대로 저장한 문서는 한/글이 열지 못하며, 신호는 호출 시점의
-  경고 하나뿐입니다(저장도 패키지 검증도 막지 않습니다). 도형은 `add_line()` /
+- `add_shape()` / `add_control()`은 저수준 탈출구라, 그대로 저장하면 한/글이
+  열지 못하는 파일이 됩니다(호출 시 경고만 나옵니다). 도형은 `add_line()` /
   `add_rectangle()` / `add_ellipse()`를 쓰세요.
-- 그림은 단순 개체 생성까지 지원하며, 그룹·효과 같은 복잡 개체 생성은 미지원입니다.
+- 그림은 단순 개체 생성까지 지원합니다 (그룹·효과 미지원).
 - 암호화된 HWPX는 지원하지 않습니다.
 
 ## 기여하기
@@ -156,11 +166,12 @@ print(report.preservation.untouched_part_payloads.to_dict())
 [help wanted](https://github.com/airmang/python-hwpx/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) ·
 [로드맵](https://github.com/airmang/python-hwpx/milestones) ·
 [Discussions](https://github.com/airmang/python-hwpx/discussions) ·
-[내부 실전 가이드](docs/internals/) ·
 [CONTRIBUTING](CONTRIBUTING.md)
 
 HWPX 내부 구조가 처음이라면 [내부 실전 가이드](docs/internals/)부터 — 실제 한/글
 동작에서 확인된 조판 캐시·목차 필드·OPC 재패킹 같은 실전 지식을 정리해 두었습니다.
+공개 API의 안정 범위는 [안정 API 표면](docs/stable-api.md), 계층 간 소유권은
+[제품 경계 문서](docs/architecture/product-boundary.md)에 있습니다.
 
 ## 감사의 말
 

{python_hwpx-5.0.1 → python_hwpx-5.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "5.0.1"
+version = "5.0.2"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
@@ -21,8 +21,11 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries",
     "Topic :: Text Processing :: Markup :: XML",
+    "Typing :: Typed",
 ]
 dependencies = [
     "lxml>=4.9,<7",

{python_hwpx-5.0.1 → python_hwpx-5.0.2}/src/hwpx/opc/package.py

@@ -664,13 +664,18 @@ class HwpxPackage:
                 ).master_page_paths
             )
             if not paths:
-                logger.warning("manifest에서 masterPage를 찾지 못해 파일명 탐색 fallback을 사용합니다.")
                 paths = [
                     name
                     for name in self._files.keys()
                     if "master" in PurePosixPath(name).name.lower()
                     and "page" in PurePosixPath(name).name.lower()
                 ]
+                # masterPage가 아예 없는 문서가 정상이므로, manifest가 실재
+                # 파일을 놓친 경우에만 경고한다.
+                if paths:
+                    logger.warning(
+                        "manifest에서 masterPage를 찾지 못해 파일명 탐색 fallback을 사용합니다."
+                    )
             self._master_page_paths_cache = paths
         return list(self._master_page_paths_cache)
 
@@ -684,12 +689,17 @@ class HwpxPackage:
                 ).history_paths
             )
             if not paths:
-                logger.warning("manifest에서 history를 찾지 못해 파일명 탐색 fallback을 사용합니다.")
                 paths = [
                     name
                     for name in self._files.keys()
                     if "history" in PurePosixPath(name).name.lower()
                 ]
+                # history가 없는 문서가 정상이므로, manifest가 실재 파일을
+                # 놓친 경우에만 경고한다.
+                if paths:
+                    logger.warning(
+                        "manifest에서 history를 찾지 못해 파일명 탐색 fallback을 사용합니다."
+                    )
             self._history_paths_cache = paths
         return list(self._history_paths_cache)
 
@@ -701,8 +711,11 @@ class HwpxPackage:
                 known_parts=self._files.keys(),
             ).version_path
             if path is None and self.has_part(self.VERSION_PATH):
-                logger.warning(
-                    "manifest에서 version 파트를 찾지 못해 기본 경로 fallback을 사용합니다: %s",
+                # 실제 한컴 산출물은 version.xml을 manifest에 선언하지 않고
+                # 고정 경로로 둔다(gold fixtures 실측). 정상 경로이므로 경고
+                # 대신 debug로 남긴다.
+                logger.debug(
+                    "manifest에 version 항목이 없어 고정 경로를 사용합니다: %s",
                     self.VERSION_PATH,
                 )
                 path = self.VERSION_PATH