feat: MD 파일 병합 및 이미지 경로 통합 스크립트 추가 (#1)

- merge_markdown.py: 96개 페이지별 MD를 단일 파일로 병합
  - 이미지를 output/images/ 폴더로 통합, p{NN}_ prefix로 파일명 충돌 방지
  - file_range 파라미터로 부분 테스트 가능
- docs/tutorial.md: merge 명령어 및 사용법 문서화
- docs/history: 작업 이력 파일 추가

소요 시간: 10분 | Context: input 18k / output 2k tokens

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/history/2026-03-31_GPU설정및전체MD변환시작.md

@@ -0,0 +1,33 @@
+**이슈**: #1
+**소요 시간**: 90분
+**Context 사용량**: input 80k / output 10k tokens
+
+## 작업 내용
+- torch CPU 버전(2.9.1)을 GPU 버전(2.7.0+cu126)으로 교체하여 RTX 3060 GPU OCR 활성화
+- MSEW3.0 매뉴얼 96페이지 중 01~12 MD 변환 완료
+- 01~12 변환된 MD 파일의 이미지 참조 아래에 파라미터 설명 삽입 완료
+- 나머지 13~96은 PowerShell 명령어로 야간 자동 변환 예정
+
+## 변경 파일
+- `.venv` : torch 2.9.1+cpu → 2.7.0+cu126 교체
+- `output/MSWE3.0 Manual-01~12.md` : 생성 완료
+- `output/MSWE3.0 Manual-03,04,09,10,11,12.md` : 이미지 파라미터 설명 삽입
+
+## 주요 결정사항
+- torch pip 설치 시 `.venv/Scripts/python.exe -m pip` 사용해야 올바른 venv에 설치됨 (단순 pip 명령은 다른 venv에 설치됨)
+- 병렬 변환(2개 동시)은 GPU 과부하 위험 → 1개씩 순차 처리로 변경
+- 야간 변환: 완료 파일 자동 건너뜀 로직 포함 PowerShell 스크립트 사용
+
+## 추출된 파라미터 (03~12 추가분)
+- Available Connection Strength: Confining Stress Sigma [kPa], CRu-1, CRs-1, GEOGRID 타입(1.4T~5.15T)
+- Project Identification: Project Title(필수), Designer(필수), Date/Time, Company/Firm, Project No.
+- Program Manager 메인화면: AASHTO(ASD/LRFD)/NCMA 설계모드 선택
+- Reinforcement Layout: LAYER#, Geogrid Height [m], Geogrid Type#, Vertical distance [m]
+- FACIA(Blocks): Depth Wu [m]=0.3, Height Hu [m]=0.2, Unit weight γ [kN/m³]=24, Gu [m]=0.15
+- Reduction factors at connection: RF d(내구성), RF c(크리프), BREAK Overall Fs=1.5, PULLOUT Overall Fs=1.5, 지진시 Tc-pullout 감소율=80%
+- Results 화면: Final Values for Design, 층별 강도/연결부 체크 결과
+
+## 문제 및 해결
+- `pip install` 이 docuConverter01 venv에 설치되는 문제 → `python -m pip install` 로 해결
+- torch 2.6.0: marker-pdf 호환 안됨(>=2.7.0 필요) → 2.7.0+cu126 사용
+- 병렬 실행 과부하 → 순차 처리로 변경

docs/history/2026-03-31_MSEW매뉴얼31-47이미지읽기시도중단.md

@@ -0,0 +1,25 @@
+**이슈**: #1
+**소요 시간**: 약 30분 (추정)
+**Context 사용량**: input 약 180k / output 약 3k tokens (추정 — 컨텍스트 초과로 정확한 수치 기록 불가)
+
+## 작업 내용
+MSEW3.0 Manual 31~47번 이미지 파라미터 분석 시도.
+이미지 Read 툴로 31~33번 일부 이미지를 읽던 중 컨텍스트 한도 초과로 강제 종료.
+MD 파일에 실제 삽입(Edit)은 한 건도 이루어지지 않음 — 다음 세션에서 전체 재처리됨.
+
+## 변경 파일
+- 없음 (컨텍스트 초과로 Edit 도달 전 종료)
+
+## 읽은 이미지 목록 (삽입 미완료)
+- `output/MSWE3.0 Manual-31_images/` : Figure_1, Figure_3, Picture_5, Picture_13 (4개)
+- `output/MSWE3.0 Manual-32_images/` : Figure_1, Figure_8, Picture_22 (3개)
+- `output/MSWE3.0 Manual-33_images/` : Figure_2 (1개)
+- 합계 8개 이미지 읽기 완료, 나머지 55개 미처리
+
+## 주요 결정사항
+- 이미지 Read 시 각 이미지당 약 15~20k 입력 토큰 소비 → 8개만 읽어도 컨텍스트 급증
+- 다음 세션에서 전체 31~47 이미지 일괄 재처리 전략으로 변경
+
+## 문제 및 해결
+- 이미지 멀티모달 분석이 컨텍스트를 매우 빠르게 소비함
+- 다음 세션(`2026-03-31_MSEW매뉴얼31-47파라미터삽입.md`)에서 31~47 전체 완료

docs/history/2026-03-31_MSEW매뉴얼31-47파라미터삽입.md

@@ -0,0 +1,34 @@
+**이슈**: #1
+**소요 시간**: 40분
+**Context 사용량**: input 120k / output 8k tokens
+
+## 작업 내용
+MSEW3.0 Manual MD 파일 31~47번에 이미지 파라미터 설명 삽입 (이전 세션에서 컨텍스트 초과로 중단된 작업 재개)
+
+## 변경 파일
+- `output/MSWE3.0 Manual-31.md` : Figure_1 (내적K선택), Figure_3 (Coulomb δ), Picture_5 (외적K δ설명), Picture_13 (Wrap-around 수직간격)
+- `output/MSWE3.0 Manual-32.md` : Figure_1 (MetalStrip Program Manager), Figure_8 (Simple Geometry), Picture_22 (근입깊이)
+- `output/MSWE3.0 Manual-33.md` : Figure_2 (Complex Structures), Figure_9 (Foundation Soil Properties), Figure_12 (Metal Strip Design 메인)
+- `output/MSWE3.0 Manual-34.md` : Figure_6 (균등간격), Figure_7 (계산진행), Figure_9 (부식두께 NOTE), Figure_11 (수평간격범위)
+- `output/MSWE3.0 Manual-35.md` : Figure_2 (보강재종류수), Figure_4 (두종류보강재데이터), Figure_6 (배치테이블), Figure_9 (Metal Strip Data), Figure_10 (상호작용파라미터)
+- `output/MSWE3.0 Manual-36.md` : Figure_9 (토압계수변화), Picture_11 (Fw배치), Picture_13 (외적K선택)
+- `output/MSWE3.0 Manual-37.md` : Figure_0 (패널물성), Figure_5 (연결부강도관계), Figure_7 (연결부감소계수)
+- `output/MSWE3.0 Manual-38.md` : Figure_1 (동적하중설계), Figure_6 (지층기본설정)
+- `output/MSWE3.0 Manual-39.md` : Figure_0 (첫번째지층), Figure_2 (두번째지층), Picture_8 (결과확인화면), Picture_12 (복합안정성아이콘)
+- `output/MSWE3.0 Manual-40.md` : Figure_0 (복합안정성초기값), Figure_7 (해석기준선택), Figure_13 (SearchGrid), Figure_18 (Bishop진행)
+- `output/MSWE3.0 Manual-41.md` : Figure_0 (저부파괴여부), Figure_2 (저부파괴탐색), Picture_13 (중간결과아이콘), Figure_18 (외적/내적중간결과)
+- `output/MSWE3.0 Manual-42.md` : Figure_6 (지지력정적), Figure_14 (지지력동적), Figure_17 (활동정적)
+- `output/MSWE3.0 Manual-43.md` : Figure_1 (활동동적1), Figure_2 (활동동적2), Figure_4 (활동상세다이어그램), Figure_6 (활동최소길이)
+- `output/MSWE3.0 Manual-44.md` : Figure_0 (편심정적), Figure_2 (편심동적), Figure_4 (편심상세다이어그램), Figure_6 (편심최소길이)
+- `output/MSWE3.0 Manual-45.md` : Picture_2 (Geotextile중간결과아이콘), Figure_3 (내적강도결과테이블), Figure_15 (동적강도결과), Figure_17 (Tmax분포)
+- `output/MSWE3.0 Manual-46.md` : Figure_1 (Tmax수평응력분포), Figure_4 (연결부정적), Picture_9 (연결부안전율상세), Figure_11 (연결부동적)
+- `output/MSWE3.0 Manual-47.md` : Figure_0 (인발정적), Figure_7 (인발동적1), Figure_8 (인발동적2), Figure_11 (최종설계결과)
+
+## 주요 결정사항
+- 총 63개 이미지를 Read 툴로 멀티모달 분석 후 각 MD 파일에 삽입
+- 31-47 범위의 내용은 Metal Strip 설계(31-38), 전체안정해석(38-41), 결과확인(41-47)
+- 결과 확인 화면(42-47)은 입력 파라미터보다 출력 결과 컬럼명을 설명하는 방식으로 기술
+
+## 문제 및 해결
+- 이전 세션에서 Manual-31 이미지 4개와 Manual-33 Figure_2 이미지를 이미 읽었으나 컨텍스트 초과로 삽입 전 중단
+- 이번 세션에서 나머지 이미지(33 Figure_9~47 전체)를 병렬 Read로 한꺼번에 분석 후 순차 삽입

docs/history/2026-03-31_MSEW매뉴얼60-83파라미터삽입.md

@@ -0,0 +1,42 @@
+**이슈**: #1
+**소요 시간**: 약 90분
+**Context 사용량**: input 약 220k / output 약 15k tokens
+
+## 작업 내용
+MSEW3.0 Manual MD 파일 60~83번에 이미지 파라미터 설명 삽입.
+컨텍스트 초과로 종료된 이전 세션에서 이어받아, 사용자 요청으로 60번부터 진행.
+이전 세션의 누락된 히스토리(`2026-03-31_MSEW매뉴얼31-47이미지읽기시도중단.md`)도 추정 작성.
+
+## 변경 파일
+- `output/MSWE3.0 Manual-60.md` : Figure_0 (외부안정분석), Figure_6 (내적안정테이블), Figure_15 (Tmax분포)
+- `output/MSWE3.0 Manual-61.md` : Figure_0 (Tmax상세), Figure_2 (이상값버튼), Figure_3 (목표Fs입력), Figure_4 (이상값테이블), Figure_7 (연결부분석)
+- `output/MSWE3.0 Manual-62.md` : Figure_5 (인발저항테이블), Figure_8 (인발상세), Picture_14 (GlobalStability버튼)
+- `output/MSWE3.0 Manual-63.md` : Figure_0 (복합안정초기값), Picture_7 (해석방법선택), Figure_11 (탐색격자), Picture_16 (Bishop시작확인), Picture_18 (저부파괴여부)
+- `output/MSWE3.0 Manual-64.md` : Figure_1 (저부파괴탐색격자), Figure_7 (복합결과테이블), Picture_12 (컨투어분포), Figure_14 (3D분포)
+- `output/MSWE3.0 Manual-65.md` : Figure_1 (파괴원다이어그램), Figure_3 (보강재기여), Figure_5 (인장력분포), Picture_9 (저부컨투어), Figure_11 (저부3D)
+- `output/MSWE3.0 Manual-66.md` : Figure_0 (저부파괴원), Figure_2 (저부보강재기여), Figure_4 (인장력분포), Figure_7 (지진결과), Picture_9 (임계원지진)
+- `output/MSWE3.0 Manual-67.md` : Figure_20 (전면블록데이터)
+- `output/MSWE3.0 Manual-68.md` : Figure_3 (연결부감소계수), Figure_8 (연결부강도입력), Figure_12 (전단저항입력)
+- `output/MSWE3.0 Manual-69.md` : Figure_0 (지오그리드분석메뉴), Picture_4 (보강재종류수), Picture_6 (보강재데이터), Figure_8 (층별배치입력)
+- `output/MSWE3.0 Manual-70.md` : Picture_6 (내적토압계수안내), Figure_8 (외적토압계수안내), Figure_11 (결과메인화면), Figure_19 (지지력결과)
+- `output/MSWE3.0 Manual-71.md` : Figure_8 (지지력지진), Figure_11 (활동결과테이블), Figure_20 (활동정적상세), Figure_22 (활동지진상세)
+- `output/MSWE3.0 Manual-72.md` : Figure_2 (편심결과테이블), Figure_5 (편심정적상세), Figure_7 (편심지진상세), Figure_13 (내적안정결과)
+- `output/MSWE3.0 Manual-73.md` : Figure_0 (Tmax분포1), Figure_2 (Tmax분포2), Figure_5 (이상값버튼), Figure_6 (목표Fs입력), Figure_7 (이상값테이블)
+- `output/MSWE3.0 Manual-74.md` : Figure_0 (연결부결과테이블), Picture_7 (연결부Fs요약), Figure_9 (Bulging테이블), Figure_11 (힌지높이)
+- `output/MSWE3.0 Manual-75.md` : Figure_1 (최대비보강높이), Figure_5 (인발결과테이블), Figure_8 (인발상세테이블)
+- `output/MSWE3.0 Manual-76.md` : Picture_0 (결과메인), Figure_1 (텍스트저장버튼), Picture_5 (PrintPreview1), Picture_6 (PrintPreview2), Figure_11 (비트맵저장)
+- `output/MSWE3.0 Manual-80.md` : Figure_5 (연결력비율테이블), Figure_6 (연결력그래프)
+- `output/MSWE3.0 Manual-81.md` : Picture_8 (보강재배치도)
+- `output/MSWE3.0 Manual-83.md` : Picture_5 (경사배면배치도)
+- `docs/history/2026-03-31_MSEW매뉴얼31-47이미지읽기시도중단.md` : 누락 히스토리 추정 작성
+
+## 주요 결정사항
+- 77~79, 82, 84~86번은 _images 폴더 없어 건너뜀
+- 결과 화면(분석 결과 테이블, 다이어그램)은 출력 컬럼명과 의미 위주로 기술
+- 입력 다이얼로그는 파라미터명·단위·샘플값 위주로 기술
+- 60~76번: NCMA 방식 Geogrid/Geotextile 결과 확인 화면이 주를 이룸
+- 80~83번: 텍스트 출력 결과 파일 관련 배치도 및 집계 그래프
+
+## 문제 및 해결
+- Manual-65 Picture_9/Figure_11 삽입 시 공백 라인 차이로 첫 시도 실패 → 파일 재읽기 후 정확한 문자열로 수정 성공
+- 파일 86번까지만 존재(사용자가 98번까지라고 했으나 실제 변환 파일은 86번이 마지막)

docs/history/2026-03-31_MSEW매뉴얼이미지파라미터추출.md

@@ -0,0 +1,31 @@
+**이슈**: #1
+**소요 시간**: 30분
+**Context 사용량**: input 45k / output 6k tokens
+
+## 작업 내용
+MSEW3.0 매뉴얼 샘플 PDF 3페이지(06, 07, 08)에서 추출된 이미지를 Claude Code의 Read 툴(멀티모달)로 직접 분석하여, MD 파일의 이미지 참조 바로 아래에 파라미터명과 샘플값을 삽입.
+API 키 없이 Claude Code 구독으로 처리하는 워크플로우 검증 완료.
+
+## 변경 파일
+- `output/MSWE3.0 Manual-06.md` : 이미지 3개 아래 파라미터 설명 삽입
+- `output/MSWE3.0 Manual-07.md` : 이미지 1개 아래 파라미터 설명 삽입
+- `output/MSWE3.0 Manual-08.md` : 이미지 3개 아래 파라미터 설명 삽입
+
+## 주요 결정사항
+- Python 스크립트 대신 Claude Code가 직접 Read(이미지) → Edit(MD) 수행
+- API 키 불필요 — Claude Code 구독으로 이미지 분석 가능
+- 삽입 형식: `> **[화면명]** \n> - \`파라미터명\`: 샘플값`
+- 세션당 약 15~20페이지 처리 가능 (컨텍스트 한계)
+
+## 추출된 파라미터 목록
+- 메인 메뉴: General Information, Geometry and Surcharge, Soil Data, Reinforcement (Geogrid), FACIA (Blocks), Seismic Parameters, Strata for Global Stability Analysis, Target Performance Criteria
+- Wall Embedment: Type in front of wall, Embedded depth E [m]
+- Geometry/Surcharge: Height H [m], BackSlope [deg], Batter, BackSlope ris [m]
+- Geogrid Design: Le [m], L/Hd, L [m], 보강재 길이 옵션(Uniform/Minimum), 강도·간격 옵션, Internal/External Stability K
+- Reinforcement Types: Number of reinforcement types
+- Geogrid DB: Product Name, Ultimate Tensile Strength [kN/m], Strength Reduction factors
+- Reinforcement Layout: From/To [m], Geogrid Type #, T-allowable [kN/m]
+
+## 문제 및 해결
+- pdftoppm 미설치로 Read 툴로 PDF 직접 읽기 불가 → PyMuPDF로 텍스트 추출 후 OCR(marker-pdf)로 보완
+- 온라인 공식 매뉴얼 없음 (MSEW 3.0은 2020년 지원 종료) → 로컬 샘플 PDF 활용

docs/history/2026-03-31_이미지분석코드정리및마무리.md

@@ -0,0 +1,18 @@
+**이슈**: #1
+**소요 시간**: 15분
+**Context 사용량**: input 28k / output 4k tokens
+
+## 작업 내용
+convert_with_cropped_images.py에 이미지 분석 기능(analyze_image_with_claude, insert_image_descriptions)을 추가했다가, 이후 요청에 따라 삭제하여 PDF→MD 변환 + 이미지 추출까지만 담당하도록 정리.
+이미지 분석은 별도 파일로 특화 개발 예정.
+
+## 변경 파일
+- `convert_with_cropped_images.py` : 이미지 분석 관련 함수 2개(analyze_image_with_claude, insert_image_descriptions) 및 호출 코드 제거. base64/dotenv import 제거.
+
+## 주요 결정사항
+- convert_with_cropped_images.py는 PDF→MD 변환 + 이미지 파일 추출까지만 담당
+- 이미지 분석(멀티모달 AI)은 이 파일을 복제한 별도 스크립트에서 특화 구현 예정
+- 분리 이유: 매뉴얼 이미지는 범용 분석이 아닌 특화된 프롬프트/로직이 필요
+
+## 문제 및 해결
+없음

docs/history/2026-03-31_훅설정및PDF2단변환기능추가.md

@@ -0,0 +1,28 @@
+**이슈**: #1
+**소요 시간**: 40분
+**Context 사용량**: input 35k / output 8k tokens
+
+## 작업 내용
+1. common/.claude/hooks 훅을 프로젝트에 적용
+2. convert_with_cropped_images.py에 2단(다단) → 1단 변환 기능 추가
+3. 샘플 PDF(MSWE3.0 Manual-06.pdf) 변환 테스트
+4. 히스토리 훅 미작동 원인 분석 및 수정
+
+## 변경 파일
+- `.claude/settings.json` : 신규 생성 — UserPromptSubmit/PostToolUse/Stop 훅 등록
+- `.claude/hooks/` : common에서 훅 파일 4개 복사 (session-context.sh, guard-history-fields.sh/.py, guard-history-reminder.sh)
+- `.claude/hooks/session-context.sh` : 히스토리 기록 지시 문구 추가 (stdout으로 Claude에게 전달)
+- `convert_with_cropped_images.py` : `is_scanned_pdf()`, `reorder_text_by_columns()` 함수 추가 — 스캔/텍스트 PDF 자동 판별 후 2단→1단 처리
+- `CLAUDE.md` : 신규 생성 — 히스토리 작성 규칙 및 템플릿 정의
+- `docs/history/.gitkeep` : 신규 생성
+
+## 주요 결정사항
+- 스캔 PDF → marker-pdf surya 레이아웃 모델이 자동으로 2단 컬럼 검출+재정렬
+- 텍스트 PDF → PyMuPDF 블록 좌표 기반: 페이지 폭 절반 ±30px 기준으로 좌/우 컬럼 분리 후 좌→우 순 합산
+- 스캔 판정 기준: 샘플 3페이지에서 텍스트 50자 미만이면 스캔 PDF로 처리
+- 훅 실행 인터프리터: `.venv/Scripts/python.exe` 사용 (python/python3 명령은 다른 Python 환경을 가리킴)
+
+## 문제 및 해결
+- **훅 미작동 원인**: CLAUDE.md 없음 + session-context.sh에 작성 지시 없음 + guard-history-reminder.sh가 stderr 출력으로 Claude에게 전달 안 됨 → session-context.sh stdout에 지시 문구 추가 + CLAUDE.md 생성으로 해결
+- **ModuleNotFoundError(marker)**: python/python3 명령이 marker 미설치 Python 가리킴 → .venv/Scripts/python.exe 직접 지정으로 해결
+- **샘플 PDF 1페이지, 이미지 기반**: PyMuPDF 텍스트 블록 0개 확인 → marker-pdf OCR 경로로 처리, 정상 변환 완료

docs/history/2026-04-01_MD파일병합및이미지경로통합.md

@@ -0,0 +1,19 @@
+**소요 시간**: 10분
+**Context 사용량**: input 18k / output 2k tokens
+
+## 작업 내용
+96개 MD 파일을 하나로 병합하는 방법 설계 및 테스트 (06~08 페이지 3개).
+이미지 파일명 충돌 문제를 해결하기 위해 페이지 번호 prefix를 붙여 단일 폴더로 통합하는 방식 채택.
+
+## 변경 파일
+- `merge_markdown.py` : 전면 재작성 — 이미지 통합 폴더 생성, 파일명 rename, MD 내 경로 치환, file_range 파라미터 지원
+
+## 주요 결정사항
+- 이미지 rename 규칙: `{stem}_images/_page_0_Figure_3.jpeg` → `images/p006_Figure_3.jpeg`
+  - `_page_0_` 접두사 제거, 페이지 번호(zero-padded)를 prefix로
+- 병합 파일은 `output/` 안에 저장 → 상대경로 `images/` 그대로 유효
+- `file_range` 파라미터로 테스트 범위 지정 가능
+
+## 문제 및 해결
+- 문제: 모든 MD가 단일 페이지이므로 `_page_0_Figure_X` 이름이 96개 파일에서 중복
+- 해결: 이미지를 단일 `images/` 폴더로 복사할 때 `p{pagenum}_` 접두사 추가하여 고유명 보장

docs/tutorial.md

@@ -0,0 +1,39 @@
+# documan 사용법
+
+## MD 파일 병합 (merge_markdown.py)
+
+PDF에서 변환된 페이지별 MD 파일들을 하나의 파일로 합친다.
+이미지도 `output/images/` 폴더로 통합되고, MD 내 경로가 자동으로 업데이트된다.
+
+### 전체 병합
+
+```bash
+python merge_markdown.py
+```
+
+- 입력: `output/MSWE3.0 Manual-01.md` ~ `output/MSWE3.0 Manual-96.md`
+- 출력: `output/merged_all.md`
+- 이미지: `output/images/p01_Figure_0.jpeg` 형식으로 통합
+
+### 일부 페이지만 테스트
+
+`merge_markdown.py` 하단의 `__main__` 블록에서 `file_range` 지정:
+
+```python
+merge_markdown_files(
+    input_dir="output",
+    output_file="merged_test.md",
+    images_subdir="images",
+    file_range=(6, 8),   # 06~08 페이지만
+)
+```
+
+### 이미지 이름 규칙
+
+| 원본 | 변환 후 |
+|------|---------|
+| `MSWE3.0 Manual-06_images/_page_0_Figure_0.jpeg` | `images/p06_Figure_0.jpeg` |
+| `MSWE3.0 Manual-15_images/_page_0_Picture_12.jpeg` | `images/p15_Picture_12.jpeg` |
+
+- `_page_0_` 접두사 제거
+- 페이지 번호를 `p{NN}_` 형식으로 앞에 붙여 파일명 충돌 방지