diff --git a/README.md b/README.md
index 68165a7..d23157e 100644
--- a/README.md
+++ b/README.md
@@ -1,88 +1,73 @@
-# 문서 정보 추출 및 비교 도구
+# OCR Macro: 정답셋 워크플로우
 
-이 프로젝트는 문서(이미지, PDF)에서 정보를 추출하고, 그 결과를 원본 문서와 나란히 비교할 수 있는 도구를 제공합니다.
+이 프로젝트는 여러 OCR 모델의 결과물을 효율적으로 비교하고 수정하여, 고품질의 정답셋(Ground Truth) 데이터셋을 구축하기 위한 일련의 도구와 워크플로우를 제공합니다.
 
-## 구성 요소
+## 프로젝트 개요
 
-1. **추출 스크립트 (`workspace/process_directory.py`)**: 지정된 디렉터리의 모든 파일에 대해 정보 추출 API를 호출하고 결과를 JSON 파일로 저장합니다.
-2. **비교 웹앱 (`workspace/app.py`)**: Streamlit 기반의 웹 애플리케이션으로, 원본 문서와 추출된 JSON 결과를 업로드하여 시각적으로 비교할 수 있습니다.
+프로젝트는 크게 두 가지 핵심 도구로 구성됩니다.
 
----
+1. **`run_ocr.py`**: 대량의 문서를 OCR API로 보내고 결과를 자동으로 저장하는 CLI 스크립트.
+2. **`app.py`**: OCR 결과물을 원본과 비교하며 수정하고, 정답셋을 생성하는 Streamlit 기반 웹 애플리케이션.
 
-## 1. 추출 스크립트 사용법 (`process_directory.py`)
+## 구성 요소 상세
 
-### 사전 준비
+### 1. `workspace/run_ocr.py`
 
-스크립트를 실행하기 위해서는 Python 3.6 이상이 필요합니다.
+대량의 문서에 대한 OCR을 자동화하는 커맨드 라인 인터페이스(CLI) 스크립트입니다.
 
-#### 1.1. 환경 변수 설정
+- **주요 기능**: 병렬 처리, 자동 재시도(Exponential Backoff), OCR 공급자 선택(`paddle`/`upstage`), 순차 처리 모드(API의 RPS 제한 대응).
+- **사용법**: `run_ocr_readme.md` 파일 참조.
 
-API 서버의 정보는 민감 정보이므로, `workspace` 디렉터리 안에 `.env` 파일을 생성하여 관리합니다.
+### 2. `workspace/app.py`
 
-`.env` 파일 예시 (`workspace/.env`):
+OCR 결과물을 시각적으로 비교하고 수정하여 정답셋을 생성하는 Streamlit 기반 웹 애플리케이션입니다.
 
-```env
-BASE_URL="http://172.0.0.1:8888"
-API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
-```
+- **주요 기능**: 세션 기반 협업, 3-Way 비교 뷰, 동적 레이아웃, 작업 완료 상태 추적, 정답셋 재수정, 결과물 zip 다운로드.
+- **사용법**: `workspace/app_readme.md` 파일 참조.
 
-**중요:** 이 `.env` 파일은 `.gitignore`에 의해 버전 관리에서 자동으로 제외됩니다.
+## 설치 및 실행
 
-#### 1.2. 의존성 설치
+### 설치
 
-프로젝트 루트 디렉터리에서 다음 명령어를 실행하여 필요한 라이브러리를 설치합니다.
+프로젝트의 루트 디렉토리에서 다음 명령어를 실행하여 필요한 라이브러리를 설치합니다.
 
 ```bash
 pip install -r requirements.txt
 ```
 
-### 실행 방법
+### 실행
 
-프로젝트 루트 디렉터리에서 다음 형식으로 스크립트를 실행합니다.
+#### OCR 자동화 스크립트
 
 ```bash
-python workspace/process_directory.py [입력_디렉터리] [옵션]
+# 예시: upstage 모델을 사용하여 3초 간격으로 순차 처리
+python workspace/run_ocr.py ./source_documents ./result_jsons/upstage --provider upstage --delay 3
 ```
 
-#### 인자 설명
+#### 정답셋 생성 웹 애플리케이션
 
-- `input_dir` (필수): 처리할 파일들이 들어있는 입력 디렉터리의 경로입니다.
-- `-o, --output_dir` (선택): 결과 JSON 파일들을 저장할 출력 디렉터리입니다. (기본값: `results`)
-- `--endpoint` (선택): 호출할 API 엔드포인트를 지정합니다. (`i18n` 또는 `d6c`, 기본값: `i18n`)
-- `--model` (선택): 사용할 특정 LLM 모델의 이름을 지정합니다.
-
-#### 실행 예시
-
-```bash
-# 'source_documents/data'에 있는 파일들을 'i18n' 엔드포인트로 처리
-python workspace/process_directory.py source_documents/data
-
-# 'd6c' 엔드포인트를 사용하여 처리하고 결과를 'my_results' 폴더에 저장
-python workspace/process_directory.py source_documents/data2 --endpoint d6c -o my_results
+```dockerfile
+docker compose up
 ```
 
----
+## 디렉토리 구조 (권장)
 
-## 2. 비교 웹앱 사용법 (`app.py`)
-
-이 웹앱을 사용하여 원본 문서와 `process_directory.py` 실행 결과로 생성된 JSON 파일을 시각적으로 비교할 수 있습니다.
-
-### 실행 방법
-
-프로젝트 루트 디렉터리에서 다음 명령어를 실행합니다.
-
-```bash
-streamlit run workspace/app.py
-or
-docker copmose up
 ```
-
-위 명령어를 실행하면 웹 브라우저에서 비교 도구가 열립니다.
-
-### 사용 절차
-
-1. 웹앱이 실행되면 사이드바에 파일 업로드 영역이 나타납니다.
-2. **"원본 문서 파일(들)을 업로드하세요."** 버튼을 클릭하여 하나 이상의 문서 파일(PDF, PNG, JPG 등)을 업로드합니다.
-3. **"결과 JSON 파일(들)을 업로드하세요."** 버튼을 클릭하여 해당 문서들의 추출 결과인 JSON 파일들을 업로드합니다.
-4. 파일들이 성공적으로 매칭되면, **"비교할 파일을 선택하세요."** 드롭다운 메뉴에 파일 목록이 나타납니다.
-5. 목록에서 파일을 선택하면, 왼쪽에는 원본 문서가, 오른쪽에는 JSON 데이터가 표시되어 내용을 비교할 수 있습니다.
+ocr_macro/
+├── source_documents/      # 원본 이미지/PDF 파일
+├── result_jsons/
+│   ├── paddle_ocr/        # paddle_ocr 결과 JSON 파일
+│   └── upstage/           # upstage 결과 JSON 파일
+├── workspace/
+│   ├── app.py             # 정답셋 생성 웹 앱
+│   ├── run_ocr.py         # OCR 자동화 스크립트
+│   ├── shared_sessions/   # app.py의 작업 세션 데이터 (자동 생성)
+│   │   └── {seed}/
+│   │       ├── docs/
+│   │       ├── jsons_paddle_ocr/
+│   │       ├── jsons_upstage/
+│   │       └── groundtruth/     # 최종 정답셋 (자동 생성)
+│   └── ...
+├── requirements.txt
+└── README.md              # 본 파일
+```
diff --git a/docs/app_readme.md b/docs/app_readme.md
new file mode 100644
index 0000000..454a1b0
--- /dev/null
+++ b/docs/app_readme.md
@@ -0,0 +1,49 @@
+# `app.py` - 정답셋 생성 및 비교 도구
+
+이 문서는 `workspace/app.py` Streamlit 애플리케이션의 기능, 설정 방법, 그리고 사용법을 상세히 설명합니다.
+
+
+## 1. 주요 기능
+
+- **세션 기반 협업**: 파일 업로드 시 고유한 URL(`seed`)이 생성되어, 이 링크를 공유하면 여러 명의 작업자가 동일한 환경에서 작업할 수 있습니다.
+- **3-Way 비교 뷰**: **원본 문서**, **참고용 모델 결과**, **정답셋 편집기**를 한 화면에 표시하여 직관적인 비교와 수정이 가능합니다.
+- **모델 선택 및 편집**: `paddle_ocr`와 `upstage` 모델 중 하나를 정답셋의 기반으로 선택하고, `parsed` 키의 내용을 직접 수정하여 정답셋을 생성합니다.
+- **작업 상태 추적**: 정답셋 생성이 완료된 파일은 목록에 `✅` 아이콘으로 표시되어 작업 중복을 방지합니다.
+- **정답셋 재수정**: 이미 완료된 정답셋도 언제든지 다시 불러와 수정할 수 있습니다.
+- **동적 레이아웃**: '참고용 영역 숨기기' 옵션을 통해 편집 공간을 넓게 확보할 수 있습니다.
+- **결과물 다운로드**: 현재 세션에서 생성된 모든 정답셋을 하나의 `.zip` 파일로 편리하게 다운로드할 수 있습니다.
+
+## 2. 설정 및 실행
+
+### 실행
+
+프로젝트의 루트 디렉토리에서 다음 명령어를 실행하여 필요한 라이브러리를 설치합니다.
+
+```dockerfile
+docker compose up
+```
+
+실행 후 웹 브라우저에서 지정된 로컬 주소(예: `http://localhost:8501`)로 접속합니다.
+
+## 3. 작업 흐름
+
+1. **애플리케이션 실행**: 위의 명령어로 앱을 시작합니다.
+2. **파일 업로드**:
+   - 사이드바의 '파일 업로드' 섹션에서 다음 세 종류의 파일을 모두 업로드합니다.
+     1. **원본 문서** (이미지/PDF)
+     2. **paddle_ocr JSON** 결과물
+     3. **upstage JSON** 결과물
+   - 파일 이름(확장자 제외)이 세 종류 모두 동일해야 목록에 정상적으로 표시됩니다.
+3. **세션 생성**: '업로드 및 세션 생성' 버튼을 누르면, 고유한 `seed`가 포함된 URL이 생성되며 작업 화면으로 전환됩니다.
+4. **세션 공유 (선택 사항)**: 생성된 URL을 다른 작업자와 공유하여 협업을 시작할 수 있습니다.
+5. **파일 선택 및 검수**:
+   - 사이드바의 '파일 탐색' 드롭다운 메뉴에서 검수할 파일을 선택합니다.
+   - 화면 상단의 `◀ 이전` / `다음 ▶` 버튼으로 파일을 이동할 수도 있습니다.
+6. **정답셋 생성**:
+   - 화면 우측 상단의 버튼을 통해 정답셋의 기반이 될 모델(`paddle_ocr` 또는 `upstage`)을 선택합니다.
+   - 오른쪽 '정답셋 편집' 영역에서 `parsed` 키의 텍스트를 정확하게 수정합니다.
+   - '✅ 정답셋으로 저장' 버튼을 눌러 작업을 완료합니다.
+7. **작업 반복**: 모든 파일에 대해 5~6번 과정을 반복합니다. 완료된 파일은 목록에 `✅` 아이콘이 표시됩니다.
+8. **정답셋 다운로드**:
+   - 모든 작업이 완료되면, 사이드바 하단의 '내보내기' 섹션에서 '정답셋 다운로드 (.zip)' 버튼을 눌러 결과물을 다운로드합니다.
+   - 다운로드된 파일은 현재 세션의 `groundtruth` 폴더에 저장된 모든 JSON 파일을 포함합니다.
diff --git a/docs/run_ocr1_readme.md b/docs/run_ocr1_readme.md
new file mode 100644
index 0000000..50fd5c3
--- /dev/null
+++ b/docs/run_ocr1_readme.md
@@ -0,0 +1,62 @@
+# 문서 정보 추출 및 비교 도구
+
+이 프로젝트는 문서(이미지, PDF)에서 정보를 추출하고, 그 결과를 원본 문서와 나란히 비교할 수 있는 도구를 제공합니다.
+
+## 구성 요소
+
+1. **추출 스크립트 (`workspace/process_directory.py`)**: 지정된 디렉터리의 모든 파일에 대해 정보 추출 API를 호출하고 결과를 JSON 파일로 저장합니다.
+2. **비교 웹앱 (`workspace/app.py`)**: Streamlit 기반의 웹 애플리케이션으로, 원본 문서와 추출된 JSON 결과를 업로드하여 시각적으로 비교할 수 있습니다.
+
+---
+
+## 1. 추출 스크립트 사용법 (`process_directory.py`)
+
+### 사전 준비
+
+스크립트를 실행하기 위해서는 Python 3.6 이상이 필요합니다.
+
+#### 1.1. 환경 변수 설정
+
+API 서버의 정보는 민감 정보이므로, `workspace` 디렉터리 안에 `.env` 파일을 생성하여 관리합니다.
+
+`.env` 파일 예시 (`workspace/.env`):
+
+```env
+BASE_URL="http://172.0.0.1:8888"
+API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
+```
+
+**중요:** 이 `.env` 파일은 `.gitignore`에 의해 버전 관리에서 자동으로 제외됩니다.
+
+#### 1.2. 의존성 설치
+
+프로젝트 루트 디렉터리에서 다음 명령어를 실행하여 필요한 라이브러리를 설치합니다.
+
+```bash
+pip install -r requirements.txt
+```
+
+### 실행 방법
+
+프로젝트 루트 디렉터리에서 다음 형식으로 스크립트를 실행합니다.
+
+```bash
+python workspace/process_directory.py [입력_디렉터리] [옵션]
+```
+
+#### 인자 설명
+
+- `input_dir` (필수): 처리할 파일들이 들어있는 입력 디렉터리의 경로입니다.
+- `-o, --output_dir` (선택): 결과 JSON 파일들을 저장할 출력 디렉터리입니다. (기본값: `results`)
+- `--endpoint` (선택): 호출할 API 엔드포인트를 지정합니다. (`i18n` 또는 `d6c`, 기본값: `i18n`)
+- `--model` (선택): 사용할 특정 LLM 모델의 이름을 지정합니다.
+
+#### 실행 예시
+
+```bash
+# 'source_documents/data'에 있는 파일들을 'i18n' 엔드포인트로 처리
+python workspace/process_directory.py source_documents/data
+
+# 'd6c' 엔드포인트를 사용하여 처리하고 결과를 'my_results' 폴더에 저장
+python workspace/process_directory.py source_documents/data2 --endpoint d6c -o my_results
+```
diff --git a/docs/run_ocr2_readme.md b/docs/run_ocr2_readme.md
new file mode 100644
index 0000000..e235725
--- /dev/null
+++ b/docs/run_ocr2_readme.md
@@ -0,0 +1,70 @@
+# `run_ocr.py` 스크립트 사용법
+
+이 문서는 `workspace/run_ocr.py` 스크립트를 사용하여 디렉토리 내의 여러 이미지 및 PDF 파일에 대해 OCR(광학 문자 인식)을 일괄 수행하는 방법을 설명합니다.
+
+## 개요
+
+`run_ocr.py`는 지정된 입력 폴더에 있는 모든 파일을 비동기 OCR API 서버로 전송하고, 처리 완료된 결과를 지정된 출력 폴더에 JSON 파일로 저장하는 커맨드 라인 도구입니다. **병렬 처리**와 **순차 처리** 두 가지 모드를 모두 지원합니다.
+
+## 주요 기능
+
+- **듀얼 모드 지원**:
+  - **병렬 처리 (기본)**: 여러 파일을 동시에 처리하여 작업 시간을 대폭 단축합니다.
+  - **순차 처리**: 초당 요청 수(RPS) 제한이 있는 API를 위해, 각 요청 사이에 지정된 시간만큼 대기하며 파일을 하나씩 처리합니다.
+- **OCR 공급자 선택**: `paddle`과 `upstage` 두 가지 OCR 엔진을 선택할 수 있습니다.
+- **자동 재시도**: 네트워크 오류나 서버의 일시적인 문제가 발생하면, "Exponential Backoff + Jitter" 방식으로 지능적으로 재시도하여 안정성을 높였습니다.
+- **진행 상황 및 결과 요약**: 전체 진행 상황과 최종 성공/실패/건너뜀 건수를 명확하게 보여줍니다.
+
+## 전제 조건
+
+스크립트를 실행하기 위해서는 Python과 `requests` 라이브러리가 필요합니다. 프로젝트의 `requirements.txt` 파일에 필요한 라이브러리가 명시되어 있습니다.
+
+```bash
+pip install -r requirements.txt
+```
+
+## 사용법
+
+스크립트는 프로젝트 루트 디렉토리에서 다음 형식의 명령어로 실행합니다.
+
+```bash
+python workspace/run_ocr.py [입력_디렉토리] [출력_디렉토리] [옵션...]
+```
+
+### 인자 설명
+
+- `입력_디렉토리` (필수): OCR을 수행할 원본 이미지/PDF 파일들이 들어있는 폴더의 경로입니다.
+- `출력_디렉토리` (필수): OCR 결과 JSON 파일이 저장될 폴더의 경로입니다. 폴더가 존재하지 않으면 자동으로 생성됩니다.
+- `--provider` (선택): 사용할 OCR 공급자를 지정합니다. (기본값: `paddle`)
+  - `paddle`: Paddle OCR 사용
+  - `upstage`: Upstage OCR 사용
+- `--workers` (선택): **병렬 처리 시** 동시에 처리할 파일의 개수(스레드 수)를 지정합니다. (기본값: 4)
+  - `--delay` 옵션이 활성화되면 이 값은 무시됩니다.
+- `--delay` (선택): **순차 처리 시** 각 요청 사이의 대기 시간(초)을 설정합니다. (기본값: 0)
+  - 이 값을 0보다 크게 설정하면, 스크립트는 `--workers` 설정을 무시하고 순차 처리 모드로 강제 실행됩니다.
+
+## 실행 예시
+
+### 예시 1: 병렬 처리 (기본)
+
+`source_documents` 폴더의 파일들을 **Paddle OCR**로, **4개씩 동시에** 처리하여 `result_jsons` 폴더에 저장합니다.
+
+```bash
+python workspace/run_ocr.py ./source_documents ./result_jsons
+```
+
+### 예시 2: 병렬 처리 (옵션 지정)
+
+`source_documents` 폴더의 파일들을 **Upstage OCR**로, **10개씩 동시에** 처리하여 `result_jsons_upstage` 폴더에 저장합니다.
+
+```bash
+python workspace/run_ocr.py ./source_documents ./result_jsons_upstage --provider upstage --workers 10
+```
+
+### 예시 3: 순차 처리 (RPS 제한 대응)
+
+`source_documents` 폴더의 파일들을 **Upstage OCR**로, **하나씩 순서대로** 분리하되 **각 요청 사이에 3초씩 대기**하여 `result_jsons_upstage` 폴더에 저장합니다.
+
+```bash
+python workspace/run_ocr.py ./source_documents ./result_jsons_upstage --provider upstage --delay 3
+```