From 325dde803df567469da7e20037b6c949eada5a7b Mon Sep 17 00:00:00 2001
From: hyungi <hyungi@Hyungiui-Macmini.local>
Date: Wed, 13 Aug 2025 07:26:13 +0900
Subject: [PATCH] docs: add repo/data policy, ops workflow, and API overview;
 standardize port >=26000 guidance

---
 README.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/README.md b/README.md
index 582c6ce..70ddd74 100644
--- a/README.md
+++ b/README.md
@@ -100,6 +100,39 @@ TIP: 긴 문서를 다루려면 `num_ctx`(컨텍스트 길이)와 `num_thread`
 
 개발 서버 실행 스크립트(`scripts/dev_server.sh`)는 위 정책을 따릅니다.
 
+## 레포지토리/데이터 정책
+
+- **커밋 제외**: 문서 원본(PDF 등)과 런타임 산출물(추출 텍스트/인덱스)은 저장소에 커밋하지 않습니다.
+  - `.gitignore`: `data/`, `*.pdf` 적용됨
+- **재현 방법(로컬에서 데이터 생성)**:
+  - PDF → 텍스트/토큰 산출: `scripts/venv_setup.sh` → `source .venv/bin/activate` → `python scripts/pdf_stats.py`
+  - 텍스트 임베딩/인덱스 생성: Ollama 실행 후 `python scripts/embed_ollama.py`
+  - 서버 기동: `scripts/dev_server.sh` (기본 포트 26000)
+
+## 운영 워크플로(요약)
+
+- **모델 정책(24/7 + 부스팅)**
+  - 기본 상시: `BASE_MODEL`(권장: `qwen2.5:7b-instruct` 또는 `llama3.1:8b-instruct`)
+  - 필요 시 부스팅: `BOOST_MODEL`(권장: `qwen2.5:14b-instruct`)으로 자동/강제 전환
+  - 장문은 32k 컨텍스트 + RAG(인덱스 Top-k 주입)로 처리
+
+- **Paperless 연동**
+  - 문서 처리 완료 시(웹훅/잡) → 본문 텍스트 추출 → `/index/upsert`로 인덱스 갱신
+  - 선택적으로 `/paperless/hook`에 문서 ID를 통지 후 서버가 Paperless API로 조회하도록 확장 가능
+
+- **시놀로지 메일/오피스 연동**
+  - 본문/첨부 텍스트를 `/index/upsert`로 누적(사전 색인)
+  - 사용자 질의는 `/chat` 호출(`use_rag=true`, 필요 시 `force_boost=true`)
+
+## API 개요(요약)
+
+- 헬스: `GET /health`
+- 검색: `POST /search` `{ query, top_k }`
+- 챗: `POST /chat` `{ messages, use_rag, top_k, force_boost, options }`
+- 인덱스 업서트: `POST /index/upsert` `{ rows:[{id,text,source}], embed }`
+- 인덱스 리로드: `POST /index/reload`
+- Paperless 훅 자리표시자: `POST /paperless/hook`
+
 ## API 개요 (Paperless/시놀로지 연동)
 
 - 기본 베이스 모델(24/7): `BASE_MODEL` (기본: `qwen2.5:7b-instruct`)