cline_rag/
├── src/                       # 소스
│   ├── rag_core.py            # 임베딩(Ollama/OpenAI) + Chroma 벡터 저장소
│   │                          # + RecursiveCharacterTextSplitter + BM25 + LangGraph 검색
│   ├── ingest.py              # 문서 -> 청크 -> 임베딩 -> Chroma 색인 CLI
│   ├── ask.py                 # 터미널에서 바로 질의응답하는 CLI (MCP 몰라도 됨)
│   └── rag_server.py          # MCP stdio 서버 (도구 4개)
├── tests/                     # pytest 테스트
│   ├── conftest.py            # 공용 픽스처 (외부 서비스 불필요, 가짜 Embeddings)
│   ├── test_rag_core.py       # 코어 단위 테스트
│   ├── test_hybrid_search.py  # 토크나이저/BM25/RRF/검색 모드 테스트
│   ├── test_mcp_server.py     # MCP 프로토콜/도구 테스트
│   └── test_ask_cli.py        # ask.py CLI 테스트
├── docs/                      # 색인할 문서
├── CMakeLists.txt             # 테스트 패킹 유틸 (pytest -> CTest 래핑)
├── CMakePresets.json          # default / ninja / ci 프리셋
├── pytest.ini                 # pytest 설정
├── config.json                # 임베딩 제공자 / Chroma 저장소 / 청킹 설정
├── smoke_mcp.py               # 서버를 자식 프로세스로 띄우는 스모크 검사
├── setup.ps1                  # venv + 의존성 + 색인 + 테스트 (원클릭)
├── ask.ps1 / ask.cmd          # .venv 를 자동으로 찾아 src\ask.py 를 실행하는 런처
├── requirements.txt           # 런타임 의존성 (LangChain/LangGraph/Chroma)
├── requirements-dev.txt       # 테스트 의존성 (pytest)
├── requirements-optional.txt  # 선택 확장 (pypdf)
├── requirements.lock.txt      # pip freeze 기록
├── GETTING_STARTED.md         # 처음 사용자용 매뉴얼
└── ARCHITECTURE.md            # MCP 관점 구조(Host/Server 관계) 정리

cd C:\path\to\cline_rag
powershell -ExecutionPolicy Bypass -File .\setup.ps1

cd C:\path\to\cline_rag

python -m venv .venv                              # 1) 가상환경
.\.venv\Scripts\Activate.ps1                       # 2) 활성화
python -m pip install --upgrade pip                # 3) pip 최신화
python -m pip install -r requirements.txt          # 4) 런타임 의존성 (LangChain/LangGraph/Chroma)
python -m pip install -r requirements-dev.txt      # 5) pytest

ollama pull nomic-embed-text                       # 6) 임베딩 모델 (최초 1회)
python src\ingest.py --reset                       # 7) 인
python smoke_mcp.py                                # 8) MCP 스모크 검사
python -m pytest tests -q                          # 9) 테스트

# 프리셋으로
cmake --preset default        # 격리된 build/test-venv 생성 + pytest 설치
ctest --preset default        # 전체 테스트 팩
ctest --preset unit           # 단위 테스트만
ctest --preset mcp            # MCP 테스트만

# 프리셋 없이
cmake -S . -B build
ctest --test-dir build -C Debug --output-on-failure
ctest --test-dir build -C Debug -L mcp        # 라벨 필터
ctest --test-dir build -C Debug --show-only   # 등록된 테스트 목록

# 한 번에 (빌드 타깃)
cmake --build build --config Debug --target test-pack

cmake -S . -B build-ninja -G Ninja -DCMAKE_BUILD_TYPE=Debug `
  -DCLINE_RAG_SETUP_TEST_ENV=OFF `
  -DPython3_EXECUTABLE="$PWD\.venv\Scripts\python.exe"
ctest --test-dir build-ninja --output-on-failure

langchain-core, langchain-text-splitters, langchain-chroma, chromadb,
langchain-ollama, langchain-openai, langchain-community, rank_bm25, langgraph

python -m pip install -r requirements-optional.txt   # pypdf

.\ask.ps1 --mcp-print --mcp-target opencode    # OpenCode 등록용 JSON 조각 출력
.\ask.ps1 --mcp-status --mcp-target opencode   # 등록 여부/경로 일치 확인
.\ask.ps1 --mcp-install --mcp-target opencode  # 설정 파일에 자동 등록 (기존 값이 있으면 --force)

{
  "mcp": {
    "cline-rag": {
      "type": "local",
      "command": [
        "C:\\path\\to\\cline_rag\\.venv\\Scripts\\python.exe",
        "C:\\path\\to\\cline_rag\\src\\rag_server.py"
      ],
      "enabled": true
    }
  }
}

.\ask.ps1 "질문"                                    # PowerShell (권장)
ask.cmd "질문"                                      # cmd.exe
.\.venv\Scripts\python.exe src\ask.py "질문"        # 직접 실행

.\ask.ps1 "반차 3회는 연차로 며칠인가?"                    # hybrid, top-3
.\ask.ps1 "청크 크기" --top-k 1                           # top-1만
.\ask.ps1 "임베딩 모델" --mode vector --min-score 0.3     # 의미 검색 + 임계값
.\ask.ps1 "Ollama" --mode keyword                         # 정확 용어(임베딩 호출 없음)
.\ask.ps1 "질문" --sources docs\sample.md                 # 특정 파일만
.\ask.ps1 "질문" --json > result.json                     # JSON 출력 저장

.\ask.ps1 --mcp-print --mcp-target opencode    # OpenCode 등록용 JSON 출력
.\ask.ps1 --mcp-install --mcp-target opencode  # OpenCode 자동 등록
.\ask.ps1 --mcp-status --mcp-target opencode   # 등록 확인
.\ask.ps1 --mcp-install --force                # 기본(cline) 덮어쓰기

# 색인
python src\ingest.py                 # 증분 색인
python src\ingest.py --reset         # 전체 재색인
python src\ingest.py --prune         # 삭삭제된 파일 청크 제거
python src\ingest.py --stats         # 현황
python src\ingest.py --list          # 색색인된 파일 목록

# 질의응답/등록: 위 "## ask CLI 매뉴얼" 참조

# 테스트
python smoke_mcp.py                  # MCP 스모크 (자식 프로세스)
python -m pytest tests -q            # pytest 전체
cmake --preset default ; ctest --preset default   # CMake/CTest 테스트 팩

# 브랜치 -> 커밋 -> PR -> CI -> 병합
git switch -c feat/hybrid-search
git commit -m "feat: add BM25 hybrid search"
git push -u origin feat/hybrid-search
gh pr create --base main --fill
gh pr checks --watch
gh pr merge --squash --delete-branch

git switch -c release/v1.1.0
# SERVER_VERSION 과 CHANGELOG 갱신
python -m pytest tests -q
git commit -m "chore(release): v1.1.0"
git push -u origin release/v1.1.0
gh pr create --base main --title "chore(release): v1.1.0" --fill
gh pr merge --merge --delete-branch

git switch main; git pull --ff-only
git tag -a v1.1.0 -m "v1.1.0"
git push origin main --follow-tags
gh release create v1.1.0 --title "v1.1.0" --generate-notes