python-hwpx-automation 6.0.3__tar.gz

python_hwpx_automation-6.0.3/LICENSE

@@ -0,0 +1,178 @@
+Copyright 2025-2026 airmang (Dr. Wily)
+
+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

python_hwpx_automation-6.0.3/MANIFEST.in

@@ -0,0 +1,2 @@
+# Repository QA is exercised before release; it is not part of the runtime sdist.
+prune tests

python_hwpx_automation-6.0.3/NOTICE

@@ -0,0 +1,14 @@
+python-hwpx-automation
+Copyright 2025-2026 airmang
+
+This product includes software developed by airmang.
+Licensed under the Apache License, Version 2.0.
+
+────────────────────────────────────────
+DISCLAIMER — HWPX Format
+
+"HWPX" is the document format specified and trademarked by
+Hancom Inc. (한글과컴퓨터). This project is an independent,
+unofficial implementation and is not affiliated with, endorsed by,
+or sponsored by Hancom Inc.
+────────────────────────────────────────

python_hwpx_automation-6.0.3/PKG-INFO

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: python-hwpx-automation
+Version: 6.0.3
+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: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+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: pydantic<3,>=2.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: anyio>=4.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: mcp
+Requires-Dist: mcp==1.28.1; extra == "mcp"
+Provides-Extra: hwp
+Requires-Dist: olefile>=0.47; extra == "hwp"
+Provides-Extra: http
+Requires-Dist: uvicorn>=0.30; extra == "http"
+Provides-Extra: ingest
+Requires-Dist: markitdown[docx,pdf,xlsx]<0.2,>=0.1.6; extra == "ingest"
+Provides-Extra: oracle
+Requires-Dist: pymupdf>=1.24; extra == "oracle"
+Requires-Dist: pillow>=10.0; extra == "oracle"
+Requires-Dist: numpy>=1.26; extra == "oracle"
+Provides-Extra: vision
+Requires-Dist: pymupdf>=1.24; extra == "vision"
+Requires-Dist: pillow>=10.0; extra == "vision"
+Requires-Dist: numpy>=1.26; extra == "vision"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: build>=1.2; extra == "test"
+Requires-Dist: packaging>=23.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Requires-Dist: jsonschema>=4.22; extra == "test"
+Requires-Dist: pyyaml>=6.0; extra == "test"
+Requires-Dist: olefile>=0.47; extra == "test"
+Requires-Dist: uvicorn>=0.30; extra == "test"
+Requires-Dist: numpy>=1.26; extra == "test"
+Requires-Dist: pillow>=10.0; extra == "test"
+Requires-Dist: ruff>=0.12; extra == "test"
+Provides-Extra: typecheck
+Requires-Dist: mypy<3,>=1.10; extra == "typecheck"
+Requires-Dist: pyright<2,>=1.1.390; extra == "typecheck"
+Dynamic: license-file
+
+<p align="center">
+  <h1 align="center">python-hwpx-automation</h1>
+  <p align="center">
+    <strong>HWPX 저작·양식 채움·업무 워크플로를 위한 Python 자동화 계층</strong>
+  </p>
+  <p align="center">
+    <a href="https://pypi.org/project/python-hwpx-automation/"><img src="https://img.shields.io/pypi/v/python-hwpx-automation?color=blue&label=PyPI" alt="PyPI"></a>
+    <a href="https://pepy.tech/project/python-hwpx-automation"><img src="https://static.pepy.tech/badge/python-hwpx-automation/month" alt="Downloads"></a>
+    <a href="https://pypi.org/project/python-hwpx-automation/"><img src="https://img.shields.io/pypi/pyversions/python-hwpx-automation" alt="Python"></a>
+    <a href="https://github.com/airmang/python-hwpx-automation/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/airmang/python-hwpx-automation/tests.yml?branch=main&label=tests" alt="Tests"></a>
+    <a href="https://github.com/airmang/python-hwpx-automation/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
+  </p>
+</p>
+
+<!-- release-state: release-approved -->
+> [!WARNING]
+> **릴리스 상태 — `release-approved`: 6.0.3 train 발행이 승인되어 진행
+> 중입니다(2026-07-28).** 이 checkout은
+> `python-hwpx 5.0.1 → python-hwpx-automation 6.0.3 → 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
+문서를 다룰 수 있습니다.** 파이썬이 도는 곳이면 저작·양식 채움 워크플로가
+그대로 동작합니다.
+
+| 계층 | 저장소 | 정본 책임 |
+|---|---|---|
+| 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 가이드 |
+
+이 저장소는 위 표의 Automation 정본입니다.
+
+## Python 자동화 시작하기 (6.0 후보)
+
+```bash
+pip install python-hwpx-automation
+```
+
+```python
+from hwpx_automation import create_document_from_plan
+
+document = create_document_from_plan(
+    {
+        "schemaVersion": "hwpx.document_plan.v1",
+        "title": "회의 결과",
+        "blocks": [{"type": "paragraph", "text": "결정 사항"}],
+    }
+)
+document.save_to_path("meeting-result.hwpx")
+```
+
+`python -m hwpx_automation --help`와 `hwpx help`는 같은 task CLI를 실행합니다.
+
+## MCP 어댑터 시작하기 (6.0 후보)
+
+```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 설정 파일입니다.
+
+```json
+{
+  "mcpServers": {
+    "hwpx": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "python-hwpx-automation[mcp]==6.0.3",
+        "hwpx-automation-mcp"
+      ],
+      "env": {
+        "HWPX_AUTOMATION_WORKSPACE_ROOTS": "[\"~/Documents\"]"
+      }
+    }
+  }
+}
+```
+
+`HWPX_AUTOMATION_WORKSPACE_ROOTS`에는 문서가 있는 폴더(절대경로 또는 `~`)를 지정하세요. Windows는
+`"[\"C:\\\\hwpx\"]"`처럼 씁니다. 값을 비워 두면 서버는 실행 위치(cwd)를 root로 쓰려 하지만,
+Claude Desktop 같은 GUI 클라이언트는 서버를 시스템 디렉터리(Windows `C:\Windows\System32`,
+macOS `/`)에서 띄우므로 이런 degenerate cwd는 거부되고 모든 문서 경로가 막힙니다. 그래서 처음부터
+이 값을 설정하는 것을 권장합니다. 나머지 옵션은 [환경 변수](#환경-변수) 표를 참고하세요.
+
+> 비-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`.
+
+## 무엇을 하나
+
+기본 모드에서 다수의 HWPX 도구를 제공하며, 고급 모드(`HWPX_AUTOMATION_ADVANCED=1`)에서 점검·검증용 도구가 추가됩니다.
+
+- **읽기·탐색** — `get_document_info`, `get_document_map`(아웃라인·표 지도·앵커를 한 호출로), `find_text` (저장하지 않음)
+- **검색·치환·편집** — `search_and_replace`, `apply_document_commands`(이종 편집 원자 적용·dry-run·롤백·멱등키), `add_tracked_edit`(변경 추적)
+- **표·양식 채움** — `analyze_form_fill` → `apply_form_fill` → `verify_form_fill` 바이트 보존 트랜잭션, `table_compute`(합계·소계)
+- **문서 생성·공문** — 선언형 `create_document_from_plan`, `inspect_official_document_style`(행정 규정 lint), `mail_merge`
+- **서식·그림·생성기** — `set_paragraph_format`·`set_page_setup`, `insert_picture`, 사진대지·명패·조직도
+- **프리뷰·추출·복구·진단** — `render_preview`(HTML/PNG 자기검증), `hwpx_to_markdown`, `repair_hwpx`, `mcp_server_health`
+
+자세한 내용: [사용 사례](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**입니다.
+
+## 안전과 품질 게이트
+
+- **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)에 있습니다.
+
+> **위치 계약** — `paragraph_index`는 본문 직속 문단의 0-based 인덱스입니다. 표 안 문단은 여기 섞지 않고
+> `{"kind":"table_cell_paragraph","table_index":0,"row":0,"col":1,"cell_paragraph_index":0}` 같은 `location`
+> 객체로 지정하며, `get_table_map`/`find_text`가 반환한 값을 그대로 넘길 수 있습니다.
+
+## 환경 변수
+
+| 변수 | 설명 | 기본값 |
+|---|---|---|
+| `HWPX_AUTOMATION_WORKSPACE_ROOTS` | 허용할 workspace 절대경로의 JSON 배열(복수 root 지원). 상대경로는 첫 root 기준 | unset → 프로세스 cwd. degenerate cwd는 `WORKSPACE_ROOT_INVALID`로 거부 |
+| `HWPX_AUTOMATION_MAX_CHARS` | 텍스트 반환 도구 기본 최대 길이 | `10000` |
+| `HWPX_AUTOMATION_AUTOBACKUP` | `1`이면 저장 전 `.bak` 백업 생성 | `1` |
+| `HWPX_AUTOMATION_ADVANCED` | `1`이면 고급 도구 활성화 | `0` |
+| `HWPX_AUTOMATION_FETCH_TIMEOUT_SECONDS` | URL 기반 HWPX fetch timeout | `20.0` |
+| `HWPX_AUTOMATION_ALLOW_PRIVATE_NETWORK` | `1`이면 신뢰된 사설/루프백 HTTPS 대상 허용. 링크로컬·metadata·예약 주소는 계속 차단 | `0` |
+| `HWPX_AUTOMATION_QUALITY` | 전역 기본 저장 게이트 정책(`transparent`/`strict`). 도구별 `quality`가 우선 | `transparent` |
+| `HWPX_AUTOMATION_REQUIRE_CAPABILITY` | `0`이면 capability skew fail-closed를 끔(진단/전문가용) | `1` |
+| `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를 새로 만들지 않습니다.
+
+경로는 기본적으로 workspace 밖 traversal과 symlink escape를 거부하고, URL 입력은 HTTPS·공개 IP만
+허용합니다. 원자 rename을 제공하지 않는 호스트의 동시성 주의사항은 [하드닝 가이드](docs/hardening_guide_ko.md)를 보세요.
+
+## 기여하기
+
+[good first issue](https://github.com/airmang/python-hwpx-automation/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) ·
+[마일스톤](https://github.com/airmang/python-hwpx-automation/milestones) ·
+[Discussions](https://github.com/airmang/python-hwpx-automation/discussions) ·
+[CONTRIBUTING](CONTRIBUTING.md) ·
+[CHANGELOG](CHANGELOG.md)
+
+```bash
+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](https://github.com/airmang/python-hwpx) 위에서 동작하며, 아래 공개 표준·프로젝트에 빚지고 있습니다.
+
+- **[OWPML — 개방형 워드프로세서 마크업 언어 (KS X 6101)](https://www.kssn.net/search/stddetail.do?itemNo=K001010119985)** — HWPX가 기반하는 한국 산업 표준
+- **[hancom-io/hwpx-owpml-model](https://github.com/hancom-io/hwpx-owpml-model)** — OWPML 요소 구조 참조 모델 · **[neolord0/hwpxlib](https://github.com/neolord0/hwpxlib)** — 오라클 샘플 코퍼스
+- **[edwardkim/rhwp](https://github.com/edwardkim/rhwp)** — 멱등성·검증 게이트 설계 영감
+
+## License · Maintainer
+
+Apache-2.0 ([LICENSE](LICENSE) · [NOTICE](NOTICE)) — **Kohkyuhyun** [@airmang](https://github.com/airmang) · [kokyuhyun@hotmail.com](mailto:kokyuhyun@hotmail.com)