[codex] Enable sample-matched HWPX proposal quality

docs/api_reference.md

@@ -640,3 +640,22 @@ OWPML 스키마에서 반복적으로 사용되는 네임스페이스 URI와 Cla
 
 - `hwpx.tools.text_extractor` 모듈의 `DEFAULT_NAMESPACES`, `ParagraphInfo`, `SectionInfo`, `TextExtractor`
 - `hwpx.tools.object_finder` 모듈의 `FoundElement`, `ObjectFinder`
+
+## Proposal presets
+
+Public import path:
+
+```python
+from hwpx.presets import (
+    ProposalSpec,
+    ProposalSection,
+    ProposalStylePreset,
+    create_proposal_document,
+    inspect_proposal_quality,
+    normalize_proposal_spec,
+)
+```
+
+- `create_proposal_document(spec, *, preset="clean_korean_proposal") -> HwpxDocument`: builds an unsaved proposal/planning document from a dict-like `ProposalSpec`.
+- `inspect_proposal_quality(source) -> dict`: returns a deterministic `proposal-quality-v2` report for required sections, tables, asset weight, validation, rubric scores, sample-derived proxy dimensions under `sample_match`, and visual-review gap status.
+- `ProposalStylePreset.ensure_tokens(document) -> dict[str, str]`: creates semantic run-style tokens through public `HwpxDocument.ensure_run_style()`.

docs/usage.md

@@ -1090,3 +1090,34 @@ with open("result.hwpx", "wb") as fp:
 ```
 
 패키지 수준에서 바로 작업하고 싶다면 `HwpxPackage.set_part()`/`save()`를 사용해 XML 조각을 교체할 수도 있습니다. 다만 고수준 API(`HwpxDocument`)를 통해 편집한 경우에는 `save_to_path()`를 호출해 내부 캐시 상태를 깨끗하게 유지하는 것이 좋습니다.
+
+## Agent-first proposal preset
+
+`hwpx.presets` provides an additive, public preset surface for generating Korean proposal/planning HWPX documents from structured agent intent. It uses public `HwpxDocument` methods and semantic style tokens instead of direct XML editing.
+
+```python
+from hwpx.presets import create_proposal_document, inspect_proposal_quality
+
+proposal_spec = {
+    "title": "AI 융합형 교육실 구축 제안서",
+    "executive_summary": "AI 융합형 교육실을 구축해 학생 맞춤형 학습 환경을 조성합니다.",
+    "sections": [
+        {"title": "추진 배경 및 문제 정의", "paragraphs": ["현황과 문제를 설명합니다."]},
+        {"title": "제안 내용", "bullets": ["AI 실습 존 구성", "교원 연수 운영"]},
+        {"title": "구축 및 운영 계획", "paragraphs": ["준비-구축-운영-평가 단계로 추진합니다."]},
+    ],
+    "budget_items": [{"item": "기자재", "amount": "5,000,000원", "note": "노트북"}],
+    "expected_outcomes": ["수업 참여도 향상"],
+    "closing": "검토 후 승인 요청드립니다.",
+}
+
+doc = create_proposal_document(proposal_spec)
+doc.save_to_path("proposal.hwpx")
+doc.close()
+
+report = inspect_proposal_quality("proposal.hwpx")
+assert report["report_version"] == "proposal-quality-v2"
+assert report["sample_match"]["pass"] is True
+```
+
+First-pass quality targets are rubric average `>= 4.0`, sample-match average `>= 4.0`, no failing sample-match dimension, no critical validation errors, and package payload under 5MB unless justified. The report is still proxy-based: `visual_review_required=True` means rendered visual parity is not claimed without a separate renderer/human review gate.

src/hwpx/presets/__init__.py

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Opinionated document presets built on public ``python-hwpx`` APIs."""
+
+from .proposal import (
+    DEFAULT_PROPOSAL_SECTIONS,
+    ProposalSection,
+    ProposalSpec,
+    ProposalStylePreset,
+    create_proposal_document,
+    inspect_proposal_quality,
+    normalize_proposal_spec,
+)
+
+__all__ = [
+    "DEFAULT_PROPOSAL_SECTIONS",
+    "ProposalSection",
+    "ProposalSpec",
+    "ProposalStylePreset",
+    "create_proposal_document",
+    "inspect_proposal_quality",
+    "normalize_proposal_spec",
+]