docs: v0.4.0 GA 후속 — README view 섹션 + roadmap narrative 정리

DanMeon · claude · DanMeon · commit 76f7abe25a5b · 2026-05-05T15:30:39.000+09:00
변경사항:
- README.md Document IR 섹션에 View 변환 (v0.4.0+) sub-block 추가 — to_markdown() / to_html(include_css) 사용 예 + 표 / 각주 / 이미지 / 헤더 처리 요약
- docs/roadmap/README.md 미착수 narrative 에서 v0.4.0 항목 제거 (GA 완료, spec/ADR/migration 가 SSOT) — 헤딩을 v0.5.0 ~ v0.6.0 으로 좁힘 + GA 완료 인용 블록 추가

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -126,6 +126,24 @@ docs = HwpLoader("report.hwp", mode="ir-blocks").load()
 **JSON Schema** — `rhwp.ir.schema.export_schema()` / `load_schema()`. 공개 `$id`:
 `https://danmeon.github.io/rhwp-python/schema/hwp_ir/v1/schema.json` (불변 경로).
 
+**View 변환 (v0.4.0+)** — `HwpDocument.to_markdown()` / `to_html(include_css=False)`
+인스턴스 메서드로 IR 을 외부 view 포맷으로 직접 변환:
+
+```python
+ir = rhwp.parse("report.hwp").to_ir()
+
+md = ir.to_markdown()                 # GFM (표 / 각주 / 수식 / 이미지 placeholder)
+html = ir.to_html(include_css=True)   # 완전 HTML5 문서, <head> 안 단일 <style> 동봉
+```
+
+표는 모든 셀 `span == 1` 일 때 GFM `|...|`, 병합 셀 (rowspan/colspan > 1) 은
+`TableBlock.html` 그대로 inline. 각주/미주는 본문 paragraph 안 `[^N]` reference +
+끝 정의 (Markdown) / `<aside id="fn-N">` 정의 (HTML). 이미지는 `picture.image.uri`
+(`bin://N`) pass-through — raw bytes 가 필요하면 `Document.bytes_for_image(picture)`
+를 별도 호출 (embedded 모드 미지원). 머리글/꼬리말은 출력 미포함 (페이지 단위 장식).
+
+호출은 IR 인스턴스를 변경하지 않아 (`frozen=True`) 동일 IR 에 대한 재호출은 byte-equal.
+
 ## rhwp-py CLI
 
 ```bash
diff --git a/docs/roadmap/README.md b/docs/roadmap/README.md
@@ -33,30 +33,11 @@ rhwp-python 의 버전별 로드맵 + **활성 spec 인덱스 SSOT**. 모든 spe
 
 본 섹션은 결정 미정 narrative — `vX.Y.Z` 디렉토리가 아직 없는 minor 들의 의도/스코프. 작업 시점이 가까워지면 `/new-spec <version> <topic>` 으로 정식 spec 으로 promote.
 
-### v0.4.0 ~ v0.6.0 — view 렌더러 + RAG 프레임워크 통합
+### v0.5.0 ~ v0.6.0 — RAG 프레임워크 통합
 
-선행 조건: v0.3.0 IR 확장 안정.
+선행 조건: v0.4.0 view 렌더러 GA. v0.2.0/v0.3.0 IR + v0.4.0 view 표면 이 안정화된 후 LangChain 외 RAG 프레임워크 (LlamaIndex / Haystack) 와 통합한다.
 
-v0.2.0/v0.3.0 에서 확정된 IR 을 다른 포맷으로 렌더링 (view) 하고, LangChain 외의 RAG 프레임워크와 통합한다. HtmlRAG (WWW 2025, arXiv:2411.02959) 등 최근 연구는 LLM 에 문서를 제공할 때 **구조를 보존하는 HTML** 이 평문화 대비 우수함을 보고하므로, view 변환 품질이 RAG 체감 성능과 직결된다.
-
-**v0.4.0 — view 렌더러**
-
-- `HwpDocument.to_markdown()` — IR → CommonMark + GFM 확장
-  - 표는 GFM `|a|b|` 형태. `rowspan`/`colspan` 이 있는 셀은 GFM 으로 표현 불가 → HTML 인라인으로 폴백
-  - 머리글·꼬리말은 YAML frontmatter (선택) 또는 주석 블록
-  - 각주/미주는 CommonMark footnote 확장
-  - 수식은 `$$ ... $$` (KaTeX 호환) — `FormulaBlock.tex` 가 있을 때만
-- `HwpDocument.to_html()` — IR → HTML5
-  - `<article>`, `<section>`, `<table>` 등 시맨틱 태그
-  - 접근성: `<caption>`, `<th scope>`, `aria-*` 기본 포함
-  - CSS 는 기본 미동봉, 별도 `to_html(include_css=True)` 옵션
-  - 이미지 처리: `Picture.ref_mode` 를 따름 (`placeholder` → `<img alt>`, `embedded` → base64 `src=`, `external` → 외부 파일 + 경로 반환)
-
-HTML 은 `TableBlock.html` 과 별개 — TableBlock 수준 HTML 은 표 하나의 HTML 조각 (RAG 주입용), 문서 전체 `to_html()` 은 완전한 HTML5 문서 (브라우저 표시용).
-
-미확정 이슈:
-- **Markdown 방언** — CommonMark / GFM / Pandoc Markdown / MyST. 기본값 GFM (표·각주 지원). Pandoc-compatible 플래그는 별도 옵션
-- **HTML 출력의 CSS 동봉 여부** — 기본 미동봉, `include_css: bool` 또는 별도 `style_bundle()` 함수
+> v0.4.0 view 렌더러 (Markdown / HTML) 은 GA 완료 — [v0.4.0/view-renderer.md](v0.4.0/view-renderer.md) 가 SSOT. 본 섹션은 후속 minor 들의 미착수 narrative.
 
 **v0.5.0 — LlamaIndex 통합**
 
