# doc2md

바이너리 문서(PDF/HWP/HWPX/HML/HTML)를 Markdown으로 변환하는 도구.
AI 에이전트(Claude Code)가 ParaWiki ingest-raw에서 호출한다.

## 필수 읽기

**사용법은 [AGENT_GUIDE.md](AGENT_GUIDE.md) 를 먼저 읽어라.**

## 프로젝트 구조

```
doc2md/
├── convert.py          # 통합 CLI 진입점 (에이전트가 직접 호출)
├── converters/
│   ├── pdf.py          # PDF → MD (페이지별 분류 + 라우팅)
│   ├── hwp.py          # HWP → MD (COM + pyhwp fallback)
│   ├── hwpx.py         # HWPX → MD (ZIP+XML 파싱)
│   ├── hml.py          # HML → MD (XML 파싱)
│   └── html.py         # HTML → MD (html2text)
├── AGENT_GUIDE.md      # AI 에이전트 사용 가이드 (핵심 문서)
└── requirements.txt
```

## 핵심 원칙

1. **비대화형**: 절대 사용자 입력 대기하지 않음
2. **JSON 출력**: `--json` 플래그 시 파싱 가능한 JSON만 stdout 출력
3. **멱등성**: 이미 변환된 파일은 건너뜀 (기본 동작)
4. **다이어그램 플래그**: PDF에 다이어그램 페이지 존재 시 `has_diagrams: true` 반환

## 개발 시 주의사항

- `convert.py` CLI 인터페이스는 AGENT_GUIDE.md 스펙과 항상 일치해야 함
- JSON 출력 구조 변경 시 AGENT_GUIDE.md 동시 업데이트 필수
- `converters/` 각 파일은 단독 임포트 가능해야 함 (순환 의존 금지)