python-hwpx-automation 6.0.4__tar.gz → 6.2.1__tar.gz

{python_hwpx_automation-6.0.4/src/python_hwpx_automation.egg-info → python_hwpx_automation-6.2.1}/PKG-INFO

@@ -1,21 +1,26 @@
 Metadata-Version: 2.4
 Name: python-hwpx-automation
-Version: 6.0.4
+Version: 6.2.1
 Summary: Task-oriented HWPX document automation for Python, with an optional MCP adapter.
 Author: Kohkyuhyun
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/airmang/python-hwpx-automation
 Project-URL: Issues, https://github.com/airmang/python-hwpx-automation/issues
 Keywords: hwpx,hancom,document-automation,workflow,mcp,ai-agent
+Classifier: Intended Audience :: Developers
 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: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: python-hwpx<6,>=5.0.0
+Requires-Dist: python-hwpx<6,>=5.2.0
 Requires-Dist: pydantic<3,>=2.11
 Requires-Dist: cryptography>=42.0
 Requires-Dist: anyio>=4.0
@@ -68,41 +73,30 @@ Dynamic: license-file
 </p>
 
 <!-- release-state: release-approved -->
-> [!WARNING]
-> **릴리스 상태 — `release-approved`: 6.0.4 train 발행이 승인되어 진행
-> 중입니다(2026-07-28).** 이 checkout은
-> `python-hwpx 5.0.1 → python-hwpx-automation 6.0.4 → hwpx-plugin 1.0.0`
-> train과 계약 해시 `0ce938371f0b55a6`을 설명하지만, **원격 truth는 아직
-> 관찰 전**입니다. 마지막으로 plugin 설치까지 함께 검증한 완전한 공개
-> 트레인은 여전히
-> `python-hwpx 4.2.0 → hwpx-mcp-server 5.1.0 → hwpx-plugin 0.8.0`,
-> 계약 해시 `429cb6706323e762`입니다. 아래 canonical 설치 명령은 발행
-> readback이 끝나기 전에는 공개 설치로 간주하지 마세요.
-> 상태 승격은 `unreleased-candidate → release-approved → released` 세 단계이며,
-> `released`와 current-public 좌표는 core·canonical·compatibility와 plugin GitHub
-> Release·marketplace·실제 marketplace 설치까지 3스택 전체 원격 정본을 관찰한 뒤
-> 후속 commit에서만 바꿉니다. 절차는
-> [릴리스 상태 runbook](docs/release-runbook.md)에 있습니다.
-
-[python-hwpx](https://github.com/airmang/python-hwpx)의 format/object-model 위에서
-저작·양식 채움·시험지 조판·평가계획·안전한 에이전트 워크플로를 제공합니다.
-기본 설치는 MCP SDK 없이 Python API와 `hwpx` CLI를 사용할 수 있습니다.
-[모델 컨텍스트 프로토콜(MCP)](https://modelcontextprotocol.io)은 `[mcp]` extra로
-추가하는 선택 어댑터입니다.
-
-한컴오피스도 Windows도 필요하지 않으므로 **ChatGPT 채팅 환경에서도 HWPX
-문서를 다룰 수 있습니다.** 파이썬이 도는 곳이면 저작·양식 채움 워크플로가
-그대로 동작합니다.
-
-| 계층 | 저장소 | 정본 책임 |
+> [!NOTE]
+> 이 저장소의 main은 아직 공개되지 않은 6.2.1 후보 — release-approved 상태의 후보(수식 저작 `add_equation`,
+> 계약 `342cf672f29cd183`, 129 도구)입니다. 현재 공개 트레인은
+> `python-hwpx 5.1.1 → python-hwpx-automation 6.1.3 → hwpx-plugin 1.1.0`
+> (계약 `ac1a422376b5ac84`, 2026-07-31 released)입니다. 공개 트레인은
+> core·automation PyPI와 plugin GitHub
+> Release·marketplace·실제 marketplace 설치까지 확인한 뒤 승격했으며, 기존
+> 5.x 설치는 별도 발행된 `hwpx-mcp-server 5.1.1`이 보호합니다. 절차와 상태
+> 머신: [릴리스 runbook](docs/release-runbook.md)
+
+[python-hwpx](https://github.com/airmang/python-hwpx) 엔진 위에서 문서 저작·
+양식 채움·시험지 조판·안전한 에이전트 워크플로를 제공하는 응용 계층입니다.
+기본 설치는 MCP 없이 Python API와 `hwpx` CLI로 쓰고,
+[모델 컨텍스트 프로토콜(MCP)](https://modelcontextprotocol.io) 서버는 필요할 때
+`[mcp]` extra로 더합니다. 한컴오피스도 Windows도 필요 없으므로 **파이썬이 도는
+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 가이드 |
+| 📦 | [`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) | 에이전트가 알맞은 도구를 고르도록 돕는 플러그인/스킬 번들 |
 
-이 저장소는 위 표의 Automation 정본입니다.
-
-## Python 자동화 시작하기 (6.0 후보)
+## Python 자동화 시작하기
 
 ```bash
 pip install python-hwpx-automation
@@ -123,17 +117,13 @@ document.save_to_path("meeting-result.hwpx")
 
 `python -m hwpx_automation --help`와 `hwpx help`는 같은 task CLI를 실행합니다.
 
-## MCP 어댑터 시작하기 (6.0 후보)
+## MCP 어댑터 시작하기
 
 ```bash
 pip install "python-hwpx-automation[mcp]"
 hwpx-automation-mcp
 ```
 
-6.x 호환 기간에는 `pip install hwpx-mcp-server`와 `hwpx-mcp-server`도
-동작합니다. 옛 distribution/import/console 제거는 7.0 이전에는 하지 않으며,
-최소 90일 공개 관찰과 별도 오너 승인이 필요합니다.
-
 MCP 클라이언트 설정 파일에 아래 블록 하나면 `hwpx` 서버를 잡습니다 — Claude Desktop은
 `claude_desktop_config.json`, VS Code는 `.vscode/mcp.json`(키가 `mcpServers` 대신 `servers`),
 Gemini CLI는 `~/.gemini/settings.json`, Cursor·Windsurf는 각 에디터의 MCP 설정 파일입니다.
@@ -145,7 +135,7 @@ Gemini CLI는 `~/.gemini/settings.json`, Cursor·Windsurf는 각 에디터의 MC
       "command": "uvx",
       "args": [
         "--from",
-        "python-hwpx-automation[mcp]==6.0.4",
+        "python-hwpx-automation[mcp]==6.1.3",
         "hwpx-automation-mcp"
       ],
       "env": {
@@ -156,16 +146,18 @@ Gemini CLI는 `~/.gemini/settings.json`, Cursor·Windsurf는 각 에디터의 MC
 }
 ```
 
-`HWPX_AUTOMATION_WORKSPACE_ROOTS`에는 문서가 있는 폴더(절대경로 또는 `~`)를 지정하세요. Windows는
-`"[\"C:\\\\hwpx\"]"`처럼 씁니다. 값을 비워 두면 서버는 실행 위치(cwd)를 root로 쓰려 하지만,
-Claude Desktop 같은 GUI 클라이언트는 서버를 시스템 디렉터리(Windows `C:\Windows\System32`,
-macOS `/`)에서 띄우므로 이런 degenerate cwd는 거부되고 모든 문서 경로가 막힙니다. 그래서 처음부터
-이 값을 설정하는 것을 권장합니다. 나머지 옵션은 [환경 변수](#환경-변수) 표를 참고하세요.
+`HWPX_AUTOMATION_WORKSPACE_ROOTS`에는 문서가 있는 폴더(절대경로 또는 `~`)를
+지정하세요. Windows는 `"[\"C:\\\\hwpx\"]"`처럼 씁니다. 값을 비워 두면 GUI
+클라이언트는 서버를 시스템 디렉터리에서 띄우기 때문에 모든 문서 경로가
+막힙니다 — 처음부터 지정하는 것을 권장합니다. 나머지 옵션은
+[환경 변수](#환경-변수) 표를 참고하세요.
 
 > 비-HWPX 문서(PDF/DOCX/XLSX/HTML/TXT)를 `document_to_markdown`으로 읽으려면
-> `pip install "python-hwpx-automation[ingest]"`(또는 옛 이름 `"hwpx-mcp-server[ingest]"`)로
-> MarkItDown adapter를 함께 설치합니다.
-> 요구 사항: `Python >= 3.10` · `python-hwpx >= 5.0.0`.
+> `pip install "python-hwpx-automation[ingest]"`로 MarkItDown adapter를 함께
+> 설치합니다. 요구 사항: `Python >= 3.10` · `python-hwpx >= 5.0.0`.
+
+기존 `hwpx-mcp-server` 배포·import·콘솔·설정 키도 6.x 동안 그대로 동작합니다 —
+전체 목록과 유지 규칙: [6.x 호환 표면](docs/compatibility-6x.md)
 
 ## 무엇을 하나
 
@@ -180,34 +172,22 @@ macOS `/`)에서 띄우므로 이런 degenerate cwd는 거부되고 모든 문
 
 자세한 내용: [사용 사례](docs/use-cases.md) · [스킬 우선 워크플로](docs/skill-first-workflows.md)
 
-### 하나의 흐름부터
-
-처음부터 모든 도구를 외울 필요는 없습니다. 보통 아래 하나로 시작합니다.
+## 안전하게 쓰는 법
 
-1. **읽기** — `get_document_info` → `get_document_outline`/`get_document_text` → `find_text`, `get_table_map`으로 필요한 부분만. (저장하지 않음)
-2. **안전 수정** — `copy_document`로 사본 생성 → 읽기 도구로 대상 확인 → `search_and_replace`, `set_table_cell_text` 같은 전문 도구나 `apply_document_commands`로 가장 작은 변경 → 다시 읽어 확인 → 검토가 끝난 복사본을 handoff.
+처음부터 모든 도구를 외울 필요는 없습니다. 보통 이렇게 흘러갑니다.
 
-핵심은 **copy first · smallest edit · re-read after edits**입니다.
+1. **읽기** — `get_document_info` → `get_document_outline`/`get_document_text` → `find_text`, `get_table_map`으로 필요한 부분만 파악합니다. (저장하지 않음)
+2. **안전 수정** — `copy_document`로 사본을 만들고, 가장 작은 변경(`search_and_replace`, `set_table_cell_text`, `apply_document_commands`)을 적용한 뒤 다시 읽어 확인하고, 검토가 끝난 사본을 전달합니다.
 
-## 안전과 품질 게이트
+핵심은 **copy first · smallest edit · re-read after edits**입니다. 수정 도구는
+호출 즉시 저장되므로 검토용 작업은 반드시 사본에서 하세요.
 
-- **read first** — 먼저 읽기 도구로 문서를 파악합니다.
-- **copy before risky edits** — 결과물을 보존해야 하면 `copy_document`를 먼저 호출합니다.
-- **mutating tools persist immediately** — 수정 도구는 호출 즉시 저장되므로 검토용은 복사본에서 작업합니다.
-- **explicit handoff uses the reviewed copy** — 납품·handoff는 검토가 끝난 복사본 파일 기준입니다.
-
-모델은 operation/plan만 보내고 raw XML을 직접 편집하지 않습니다. 일반 저장 경로는 python-hwpx의
-단일 `SavePipeline` 게이트를 통과해 무결성·XML·OPC/ID·열림안전을 검사하고, `quality`에 따라
-`visualComplete` 블록(`ok`·`status`·`errorCodes`)을 응답에 실으며, 게이트가 실패하면 아무것도 쓰지 않고
-소유 후보만 원복합니다. capability handshake가 core/automation/plugin
-버전+해시 skew를 fail-closed로 차단합니다. 6.x 응답의 `versions.mcp`와
-`minMcpVersion`은 기존 소비자를 위한 alias로만 유지됩니다.
-같은 이유로 `MIN_MCP_VERSION`, 공개 오류 schema `hwpx.mcp-error/v1`,
-동결된 architecture receipt ID `hwpx-mcp.*`, parity receipt 필드
-`mcpRuntimeMembers`도 6.x에서 정확히 보존합니다. canonical 표기는
-`versions.automation`·`minAutomationVersion`·`MIN_AUTOMATION_VERSION`이며,
-보존된 MCP 철자는 제품 소유권이 아니라 wire/receipt 호환 식별자입니다.
-보안 상세는 [하드닝 가이드](docs/hardening_guide_ko.md)에 있습니다.
+모델은 operation/plan만 보내고 raw XML을 직접 편집하지 않습니다. 일반 저장
+경로는 python-hwpx의 단일 `SavePipeline` 게이트를 통과해 무결성·XML·OPC/ID·
+열림안전을 검사하고, 게이트가 실패하면 아무것도 쓰지 않습니다. capability
+handshake는 core/automation/plugin 버전+해시 skew를 fail-closed로 차단합니다.
+보안 상세: [하드닝 가이드](docs/hardening_guide_ko.md) · 옛 이름과의 호환
+식별자: [6.x 호환 표면](docs/compatibility-6x.md)
 
 > **위치 계약** — `paragraph_index`는 본문 직속 문단의 0-based 인덱스입니다. 표 안 문단은 여기 섞지 않고
 > `{"kind":"table_cell_paragraph","table_index":0,"row":0,"col":1,"cell_paragraph_index":0}` 같은 `location`
@@ -228,23 +208,10 @@ macOS `/`)에서 띄우므로 이런 degenerate cwd는 거부되고 모든 문
 | `HWPX_AUTOMATION_WORKFLOW_STORE` | durable workflow SQLite 경로. 기존 `HWPX_WORKFLOW_STORE`보다 우선 | 기존 6.x 상태 경로 |
 | `LOG_LEVEL` | 로그 레벨 | `INFO` |
 
-동일 suffix의 기존 `HWPX_MCP_*` 키는 6.x 동안 fallback으로 유지됩니다.
-두 키가 함께 있으면 `HWPX_AUTOMATION_*`이 우선합니다. workflow DB의 기존
-`.../hwpx-mcp-server/workflows.sqlite3` 기본 경로도 6.x에서는 데이터 유실을
-막기 위해 그대로 사용합니다.
-
-제품-neutral integration/capability 키는 옛 MCP 제품명을 담지 않으므로 이름을
-바꾸지 않습니다.
-
-| 분류 | 보존하는 정확한 키 |
-|---|---|
-| render integration | `HWPX_RENDER_QUEUE_ROOT`, `HWPX_RENDER_QUEUE_URL`, `HWPX_RENDER_QUEUE_SECRET`, `HWPX_RENDER_TRANSPORT_AUTH`, `HWPX_RENDER_CA_FILE`, `HWPX_RENDER_CLIENT_CERT_FILE`, `HWPX_RENDER_CLIENT_KEY_FILE` |
-| workflow security | `HWPX_WORKFLOW_ENCRYPTION_KEY` |
-| oracle capability | `HWPX_ORACLE_STRUCTURAL_ONLY`, `HWPX_ORACLE_BUDGET_SECONDS` |
-| plugin integration | `HWPX_SKILL_VERSION`, `HWPX_PLUGIN_ROOT` |
-
-이 키들은 `integration-preserved` 또는 `capability-preserved` 정본이며
-`HWPX_AUTOMATION_*` alias를 새로 만들지 않습니다.
+동일 suffix의 기존 `HWPX_MCP_*` 키는 6.x 동안 fallback으로 유지되며, 두 키가
+함께 있으면 `HWPX_AUTOMATION_*`이 우선합니다. render·workflow·oracle·plugin
+연동용 보존 키 전체 목록과 workflow DB 경로 규칙은
+[6.x 호환 표면](docs/compatibility-6x.md)에 있습니다.
 
 경로는 기본적으로 workspace 밖 traversal과 symlink escape를 거부하고, URL 입력은 HTTPS·공개 IP만
 허용합니다. 원자 rename을 제공하지 않는 호스트의 동시성 주의사항은 [하드닝 가이드](docs/hardening_guide_ko.md)를 보세요.
@@ -262,8 +229,6 @@ python -m pip install -e ".[test]"   # 테스트 의존성
 python -m pytest -q                   # 전체 테스트
 python scripts/run_conformance.py run \
   --tier structural --check tests/conformance/golden/structural.json
-# 공개 합성 코퍼스를 다시 만들 때만:
-python scripts/conformance_corpus_build.py
 ```
 
 ## 감사의 말

{python_hwpx_automation-6.0.4 → python_hwpx_automation-6.2.1}/README.md

@@ -13,41 +13,30 @@
 </p>
 
 <!-- release-state: release-approved -->
-> [!WARNING]
-> **릴리스 상태 — `release-approved`: 6.0.4 train 발행이 승인되어 진행
-> 중입니다(2026-07-28).** 이 checkout은
-> `python-hwpx 5.0.1 → python-hwpx-automation 6.0.4 → hwpx-plugin 1.0.0`
-> train과 계약 해시 `0ce938371f0b55a6`을 설명하지만, **원격 truth는 아직
-> 관찰 전**입니다. 마지막으로 plugin 설치까지 함께 검증한 완전한 공개
-> 트레인은 여전히
-> `python-hwpx 4.2.0 → hwpx-mcp-server 5.1.0 → hwpx-plugin 0.8.0`,
-> 계약 해시 `429cb6706323e762`입니다. 아래 canonical 설치 명령은 발행
-> readback이 끝나기 전에는 공개 설치로 간주하지 마세요.
-> 상태 승격은 `unreleased-candidate → release-approved → released` 세 단계이며,
-> `released`와 current-public 좌표는 core·canonical·compatibility와 plugin GitHub
-> Release·marketplace·실제 marketplace 설치까지 3스택 전체 원격 정본을 관찰한 뒤
-> 후속 commit에서만 바꿉니다. 절차는
-> [릴리스 상태 runbook](docs/release-runbook.md)에 있습니다.
-
-[python-hwpx](https://github.com/airmang/python-hwpx)의 format/object-model 위에서
-저작·양식 채움·시험지 조판·평가계획·안전한 에이전트 워크플로를 제공합니다.
-기본 설치는 MCP SDK 없이 Python API와 `hwpx` CLI를 사용할 수 있습니다.
-[모델 컨텍스트 프로토콜(MCP)](https://modelcontextprotocol.io)은 `[mcp]` extra로
-추가하는 선택 어댑터입니다.
-
-한컴오피스도 Windows도 필요하지 않으므로 **ChatGPT 채팅 환경에서도 HWPX
-문서를 다룰 수 있습니다.** 파이썬이 도는 곳이면 저작·양식 채움 워크플로가
-그대로 동작합니다.
-
-| 계층 | 저장소 | 정본 책임 |
+> [!NOTE]
+> 이 저장소의 main은 아직 공개되지 않은 6.2.1 후보 — release-approved 상태의 후보(수식 저작 `add_equation`,
+> 계약 `342cf672f29cd183`, 129 도구)입니다. 현재 공개 트레인은
+> `python-hwpx 5.1.1 → python-hwpx-automation 6.1.3 → hwpx-plugin 1.1.0`
+> (계약 `ac1a422376b5ac84`, 2026-07-31 released)입니다. 공개 트레인은
+> core·automation PyPI와 plugin GitHub
+> Release·marketplace·실제 marketplace 설치까지 확인한 뒤 승격했으며, 기존
+> 5.x 설치는 별도 발행된 `hwpx-mcp-server 5.1.1`이 보호합니다. 절차와 상태
+> 머신: [릴리스 runbook](docs/release-runbook.md)
+
+[python-hwpx](https://github.com/airmang/python-hwpx) 엔진 위에서 문서 저작·
+양식 채움·시험지 조판·안전한 에이전트 워크플로를 제공하는 응용 계층입니다.
+기본 설치는 MCP 없이 Python API와 `hwpx` CLI로 쓰고,
+[모델 컨텍스트 프로토콜(MCP)](https://modelcontextprotocol.io) 서버는 필요할 때
+`[mcp]` extra로 더합니다. 한컴오피스도 Windows도 필요 없으므로 **파이썬이 도는
+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 가이드 |
+| 📦 | [`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) | 에이전트가 알맞은 도구를 고르도록 돕는 플러그인/스킬 번들 |
 
-이 저장소는 위 표의 Automation 정본입니다.
-
-## Python 자동화 시작하기 (6.0 후보)
+## Python 자동화 시작하기
 
 ```bash
 pip install python-hwpx-automation
@@ -68,17 +57,13 @@ document.save_to_path("meeting-result.hwpx")
 
 `python -m hwpx_automation --help`와 `hwpx help`는 같은 task CLI를 실행합니다.
 
-## MCP 어댑터 시작하기 (6.0 후보)
+## MCP 어댑터 시작하기
 
 ```bash
 pip install "python-hwpx-automation[mcp]"
 hwpx-automation-mcp
 ```
 
-6.x 호환 기간에는 `pip install hwpx-mcp-server`와 `hwpx-mcp-server`도
-동작합니다. 옛 distribution/import/console 제거는 7.0 이전에는 하지 않으며,
-최소 90일 공개 관찰과 별도 오너 승인이 필요합니다.
-
 MCP 클라이언트 설정 파일에 아래 블록 하나면 `hwpx` 서버를 잡습니다 — Claude Desktop은
 `claude_desktop_config.json`, VS Code는 `.vscode/mcp.json`(키가 `mcpServers` 대신 `servers`),
 Gemini CLI는 `~/.gemini/settings.json`, Cursor·Windsurf는 각 에디터의 MCP 설정 파일입니다.
@@ -90,7 +75,7 @@ Gemini CLI는 `~/.gemini/settings.json`, Cursor·Windsurf는 각 에디터의 MC
       "command": "uvx",
       "args": [
         "--from",
-        "python-hwpx-automation[mcp]==6.0.4",
+        "python-hwpx-automation[mcp]==6.1.3",
         "hwpx-automation-mcp"
       ],
       "env": {
@@ -101,16 +86,18 @@ Gemini CLI는 `~/.gemini/settings.json`, Cursor·Windsurf는 각 에디터의 MC
 }
 ```
 
-`HWPX_AUTOMATION_WORKSPACE_ROOTS`에는 문서가 있는 폴더(절대경로 또는 `~`)를 지정하세요. Windows는
-`"[\"C:\\\\hwpx\"]"`처럼 씁니다. 값을 비워 두면 서버는 실행 위치(cwd)를 root로 쓰려 하지만,
-Claude Desktop 같은 GUI 클라이언트는 서버를 시스템 디렉터리(Windows `C:\Windows\System32`,
-macOS `/`)에서 띄우므로 이런 degenerate cwd는 거부되고 모든 문서 경로가 막힙니다. 그래서 처음부터
-이 값을 설정하는 것을 권장합니다. 나머지 옵션은 [환경 변수](#환경-변수) 표를 참고하세요.
+`HWPX_AUTOMATION_WORKSPACE_ROOTS`에는 문서가 있는 폴더(절대경로 또는 `~`)를
+지정하세요. Windows는 `"[\"C:\\\\hwpx\"]"`처럼 씁니다. 값을 비워 두면 GUI
+클라이언트는 서버를 시스템 디렉터리에서 띄우기 때문에 모든 문서 경로가
+막힙니다 — 처음부터 지정하는 것을 권장합니다. 나머지 옵션은
+[환경 변수](#환경-변수) 표를 참고하세요.
 
 > 비-HWPX 문서(PDF/DOCX/XLSX/HTML/TXT)를 `document_to_markdown`으로 읽으려면
-> `pip install "python-hwpx-automation[ingest]"`(또는 옛 이름 `"hwpx-mcp-server[ingest]"`)로
-> MarkItDown adapter를 함께 설치합니다.
-> 요구 사항: `Python >= 3.10` · `python-hwpx >= 5.0.0`.
+> `pip install "python-hwpx-automation[ingest]"`로 MarkItDown adapter를 함께
+> 설치합니다. 요구 사항: `Python >= 3.10` · `python-hwpx >= 5.0.0`.
+
+기존 `hwpx-mcp-server` 배포·import·콘솔·설정 키도 6.x 동안 그대로 동작합니다 —
+전체 목록과 유지 규칙: [6.x 호환 표면](docs/compatibility-6x.md)
 
 ## 무엇을 하나
 
@@ -125,34 +112,22 @@ macOS `/`)에서 띄우므로 이런 degenerate cwd는 거부되고 모든 문
 
 자세한 내용: [사용 사례](docs/use-cases.md) · [스킬 우선 워크플로](docs/skill-first-workflows.md)
 
-### 하나의 흐름부터
-
-처음부터 모든 도구를 외울 필요는 없습니다. 보통 아래 하나로 시작합니다.
+## 안전하게 쓰는 법
 
-1. **읽기** — `get_document_info` → `get_document_outline`/`get_document_text` → `find_text`, `get_table_map`으로 필요한 부분만. (저장하지 않음)
-2. **안전 수정** — `copy_document`로 사본 생성 → 읽기 도구로 대상 확인 → `search_and_replace`, `set_table_cell_text` 같은 전문 도구나 `apply_document_commands`로 가장 작은 변경 → 다시 읽어 확인 → 검토가 끝난 복사본을 handoff.
+처음부터 모든 도구를 외울 필요는 없습니다. 보통 이렇게 흘러갑니다.
 
-핵심은 **copy first · smallest edit · re-read after edits**입니다.
+1. **읽기** — `get_document_info` → `get_document_outline`/`get_document_text` → `find_text`, `get_table_map`으로 필요한 부분만 파악합니다. (저장하지 않음)
+2. **안전 수정** — `copy_document`로 사본을 만들고, 가장 작은 변경(`search_and_replace`, `set_table_cell_text`, `apply_document_commands`)을 적용한 뒤 다시 읽어 확인하고, 검토가 끝난 사본을 전달합니다.
 
-## 안전과 품질 게이트
+핵심은 **copy first · smallest edit · re-read after edits**입니다. 수정 도구는
+호출 즉시 저장되므로 검토용 작업은 반드시 사본에서 하세요.
 
-- **read first** — 먼저 읽기 도구로 문서를 파악합니다.
-- **copy before risky edits** — 결과물을 보존해야 하면 `copy_document`를 먼저 호출합니다.
-- **mutating tools persist immediately** — 수정 도구는 호출 즉시 저장되므로 검토용은 복사본에서 작업합니다.
-- **explicit handoff uses the reviewed copy** — 납품·handoff는 검토가 끝난 복사본 파일 기준입니다.
-
-모델은 operation/plan만 보내고 raw XML을 직접 편집하지 않습니다. 일반 저장 경로는 python-hwpx의
-단일 `SavePipeline` 게이트를 통과해 무결성·XML·OPC/ID·열림안전을 검사하고, `quality`에 따라
-`visualComplete` 블록(`ok`·`status`·`errorCodes`)을 응답에 실으며, 게이트가 실패하면 아무것도 쓰지 않고
-소유 후보만 원복합니다. capability handshake가 core/automation/plugin
-버전+해시 skew를 fail-closed로 차단합니다. 6.x 응답의 `versions.mcp`와
-`minMcpVersion`은 기존 소비자를 위한 alias로만 유지됩니다.
-같은 이유로 `MIN_MCP_VERSION`, 공개 오류 schema `hwpx.mcp-error/v1`,
-동결된 architecture receipt ID `hwpx-mcp.*`, parity receipt 필드
-`mcpRuntimeMembers`도 6.x에서 정확히 보존합니다. canonical 표기는
-`versions.automation`·`minAutomationVersion`·`MIN_AUTOMATION_VERSION`이며,
-보존된 MCP 철자는 제품 소유권이 아니라 wire/receipt 호환 식별자입니다.
-보안 상세는 [하드닝 가이드](docs/hardening_guide_ko.md)에 있습니다.
+모델은 operation/plan만 보내고 raw XML을 직접 편집하지 않습니다. 일반 저장
+경로는 python-hwpx의 단일 `SavePipeline` 게이트를 통과해 무결성·XML·OPC/ID·
+열림안전을 검사하고, 게이트가 실패하면 아무것도 쓰지 않습니다. capability
+handshake는 core/automation/plugin 버전+해시 skew를 fail-closed로 차단합니다.
+보안 상세: [하드닝 가이드](docs/hardening_guide_ko.md) · 옛 이름과의 호환
+식별자: [6.x 호환 표면](docs/compatibility-6x.md)
 
 > **위치 계약** — `paragraph_index`는 본문 직속 문단의 0-based 인덱스입니다. 표 안 문단은 여기 섞지 않고
 > `{"kind":"table_cell_paragraph","table_index":0,"row":0,"col":1,"cell_paragraph_index":0}` 같은 `location`
@@ -173,23 +148,10 @@ macOS `/`)에서 띄우므로 이런 degenerate cwd는 거부되고 모든 문
 | `HWPX_AUTOMATION_WORKFLOW_STORE` | durable workflow SQLite 경로. 기존 `HWPX_WORKFLOW_STORE`보다 우선 | 기존 6.x 상태 경로 |
 | `LOG_LEVEL` | 로그 레벨 | `INFO` |
 
-동일 suffix의 기존 `HWPX_MCP_*` 키는 6.x 동안 fallback으로 유지됩니다.
-두 키가 함께 있으면 `HWPX_AUTOMATION_*`이 우선합니다. workflow DB의 기존
-`.../hwpx-mcp-server/workflows.sqlite3` 기본 경로도 6.x에서는 데이터 유실을
-막기 위해 그대로 사용합니다.
-
-제품-neutral integration/capability 키는 옛 MCP 제품명을 담지 않으므로 이름을
-바꾸지 않습니다.
-
-| 분류 | 보존하는 정확한 키 |
-|---|---|
-| render integration | `HWPX_RENDER_QUEUE_ROOT`, `HWPX_RENDER_QUEUE_URL`, `HWPX_RENDER_QUEUE_SECRET`, `HWPX_RENDER_TRANSPORT_AUTH`, `HWPX_RENDER_CA_FILE`, `HWPX_RENDER_CLIENT_CERT_FILE`, `HWPX_RENDER_CLIENT_KEY_FILE` |
-| workflow security | `HWPX_WORKFLOW_ENCRYPTION_KEY` |
-| oracle capability | `HWPX_ORACLE_STRUCTURAL_ONLY`, `HWPX_ORACLE_BUDGET_SECONDS` |
-| plugin integration | `HWPX_SKILL_VERSION`, `HWPX_PLUGIN_ROOT` |
-
-이 키들은 `integration-preserved` 또는 `capability-preserved` 정본이며
-`HWPX_AUTOMATION_*` alias를 새로 만들지 않습니다.
+동일 suffix의 기존 `HWPX_MCP_*` 키는 6.x 동안 fallback으로 유지되며, 두 키가
+함께 있으면 `HWPX_AUTOMATION_*`이 우선합니다. render·workflow·oracle·plugin
+연동용 보존 키 전체 목록과 workflow DB 경로 규칙은
+[6.x 호환 표면](docs/compatibility-6x.md)에 있습니다.
 
 경로는 기본적으로 workspace 밖 traversal과 symlink escape를 거부하고, URL 입력은 HTTPS·공개 IP만
 허용합니다. 원자 rename을 제공하지 않는 호스트의 동시성 주의사항은 [하드닝 가이드](docs/hardening_guide_ko.md)를 보세요.
@@ -207,8 +169,6 @@ python -m pip install -e ".[test]"   # 테스트 의존성
 python -m pytest -q                   # 전체 테스트
 python scripts/run_conformance.py run \
   --tier structural --check tests/conformance/golden/structural.json
-# 공개 합성 코퍼스를 다시 만들 때만:
-python scripts/conformance_corpus_build.py
 ```
 
 ## 감사의 말

{python_hwpx_automation-6.0.4 → python_hwpx_automation-6.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx-automation"
-version = "6.0.4"
+version = "6.2.1"
 description = "Task-oriented HWPX document automation for Python, with an optional MCP adapter."
 readme = "README.md"
 authors = [{ name = "Kohkyuhyun" }]
@@ -13,10 +13,15 @@ license-files = ["LICENSE", "NOTICE"]
 requires-python = ">=3.10"
 keywords = ["hwpx", "hancom", "document-automation", "workflow", "mcp", "ai-agent"]
 classifiers = [
+    "Intended Audience :: Developers",
     "Programming Language :: Python :: 3",
     "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",
+    "Typing :: Typed",
 ]
 dependencies = [
     # 5.0 is the floor, not a preference: this package declares the `hwpx` console
@@ -24,7 +29,7 @@ dependencies = [
     # the bounded major here is what makes "no valid install has two declarers"
     # true rather than hopeful, and prevents the next core major from silently
     # breaking an already-published automation line.
-    "python-hwpx>=5.0.0,<6", # HWPX object model, OXML/OPC, format-native primitives
+    "python-hwpx>=5.2.0,<6", # HWPX object model, OXML/OPC, format-native primitives
 
     "pydantic>=2.11,<3",
     "cryptography>=42.0",

{python_hwpx_automation-6.0.4 → python_hwpx_automation-6.2.1}/src/hwpx_automation/handlers/content_edit.py

@@ -42,6 +42,7 @@ from ._shared import (
     _normalize_fill_mappings,
     _revision_guard,
     _save_doc_verification,
+    _with_document_state,
     _with_dry_run_verification,
     _with_save_verification,
 )
@@ -679,6 +680,41 @@ def add_page_break(
     return _with_save_verification({"success": True}, verification)
 
 
+def add_equation(
+    filename: str,
+    latex: str = None,
+    script: str = None,
+    paragraph_index: int = None,
+    table_index: int = None,
+    row: int = None,
+    col: int = None,
+    base_unit: int = 1100,
+    dry_run: bool = False,
+    expected_revision: str = None,
+) -> dict:
+    """네이티브 수식(<hp:equation>)을 삽입합니다. latex(권장) 또는 EqEdit script 중
+    하나만 지정 — LaTeX는 렌더 검증된 토큰셋만 EqEdit로 변환하고, 밖이면
+    EQUATION_LATEX_UNSUPPORTED로 거부합니다(무음 근사 없음). 산출 수식은 실한컴이
+    조판하고 기존 리더(eqedit_to_latex)가 되읽습니다(응답 readerLatex).
+    배치: 기본=문서 끝 새 문단, paragraph_index=기존 문단, tableIndex+row+col=표 셀."""
+    path = resolve_path(filename)
+    guard = _revision_guard(path, expected_revision)
+    if guard is not None:
+        return guard
+    result = RUNTIME_SERVICES.ops.add_equation(
+        path,
+        latex=latex,
+        script=script,
+        paragraph_index=paragraph_index,
+        table_index=table_index,
+        row=row,
+        col=col,
+        base_unit=base_unit,
+        dry_run=dry_run,
+    )
+    return _with_document_state(result, path)
+
+
 def insert_picture(
     filename: str,
     image_base64: str,
@@ -1060,6 +1096,7 @@ __all__ = [
     "insert_paragraph",
     "delete_paragraph",
     "add_page_break",
+    "add_equation",
     "apply_edits",
     "undo_last_edit",
     "replace_by_anchor",

{python_hwpx_automation-6.0.4 → python_hwpx_automation-6.2.1}/src/hwpx_automation/handlers/form_fill.py

@@ -381,6 +381,39 @@ def list_form_fields(filename: str) -> dict:
     return _with_document_state(RUNTIME_SERVICES.ops.list_form_fields(path), path)
 
 
+def add_form_field(
+    filename: str,
+    name: str,
+    prompt: str = "",
+    memo: str = "",
+    paragraph_index: int = None,
+    table_index: int = None,
+    row: int = None,
+    col: int = None,
+    dry_run: bool = False,
+    expected_revision: str = None,
+) -> dict:
+    """누름틀(click-here) 필드를 생성합니다. 실한컴 CLICKHERE 형상 그대로 방출되어
+    기존 list/fill/한컴이 특수분기 없이 소비합니다. prompt(안내문)는 화면 전용(미인쇄).
+    배치: 기본=문서 끝 새 문단, paragraph_index=기존 문단, tableIndex+row+col=표 셀."""
+    path = resolve_path(filename)
+    guard = _revision_guard(path, expected_revision)
+    if guard is not None:
+        return guard
+    result = RUNTIME_SERVICES.ops.add_form_field(
+        path,
+        name=name,
+        prompt=prompt,
+        memo=memo,
+        paragraph_index=paragraph_index,
+        table_index=table_index,
+        row=row,
+        col=col,
+        dry_run=dry_run,
+    )
+    return _with_document_state(result, path)
+
+
 def fill_form_field(
     filename: str,
     value: str,
@@ -589,6 +622,7 @@ apply_form_fill.__hwpx_input_schema_extra__ = {  # type: ignore[attr-defined]
 
 
 __all__ = [
+    "add_form_field",
     "analyze_form_fill",
     "analyze_template_formfit",
     "apply_body_ops",