From f56b353c8bf3aceed9dbd2e3a3575a5131d90c64 Mon Sep 17 00:00:00 2001
From: I Luk Kim <yirugi@gmail.com>
Date: Fri, 27 Mar 2026 04:07:36 -0700
Subject: [PATCH] Update README: paper trading operations and Phase 6
 reconciliation docs

- Add full paper trading CLI reference (create, list, run, positions, trades, close)
- Document reconciliation safety system (orphaned/ghost detection, stale orders, fill verify)
- Document kill switch (25% drawdown threshold, manual reset required)
- Expand paper backtest section with --overlay and --rank options

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 62 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 57eaffb..2705dd0 100644
--- a/README.md
+++ b/README.md
@@ -738,6 +738,9 @@ fithia2 paper backtest \
 # 리더보드 top 5 전략 비교
 fithia2 paper backtest --top 5 --year 2025
 
+# 리더보드 rank 범위 지정 (20~40위)
+fithia2 paper backtest --rank 20-40 --year 2025
+
 # 날짜 범위 직접 지정 (YYYY-MM-DD 또는 YYYY)
 fithia2 paper backtest --top 3 --start 2025-06-01 --end 2026-03-23
 
@@ -747,19 +750,76 @@ fithia2 paper backtest \
   --config configs/experiments/return_max_long_v6.92.json \
   --capital 10000 --year 2025 \
   --no-trades --output ./bt_results/
+
+# Overlay 전략 backtest (명시적 지정 필요)
+fithia2 paper backtest \
+  --overlay configs/overlays/return_book_overlay_v3.json \
+  --year 2025 --no-trades
 ```
 
 | 옵션 | 설명 |
 |------|------|
 | `--config, -c` | 전략 config 경로 (반복 가능) |
+| `--overlay` | Overlay config 경로 (반복 가능) |
 | `--top, -t N` | 리더보드 SQS 상위 N개 자동 선택 |
+| `--rank START-END` | 리더보드 rank 범위 선택 (예: `20-40`, `5`) |
 | `--capital, -k` | 전략별 초기 자본 (기본: $10,000) |
 | `--year, -y` | 연도 지정 (= --start YYYY --end YYYY) |
-| `--start` | 시작일 (YYYY-MM-DD 또는 YYYY) |
-| `--end` | 종료일 (YYYY-MM-DD 또는 YYYY, 올해면 어제까지) |
+| `--start` | 시작일 (YYYY-MM-DD, YYYY-MM, YYYY) |
+| `--end` | 종료일 (YYYY-MM-DD, YYYY-MM, YYYY; 올해면 어제까지) |
 | `--no-trades` | Trade log 출력 생략 (Summary만) |
 | `--output, -o` | CSV 저장 디렉토리 |
 
+### Paper Trading (실시간 운영)
+
+Alpaca Paper Trading 계좌를 통한 실시간 전략 실행. 환경변수 `ALPACA_API_KEY` / `ALPACA_SECRET_KEY` 필요.
+
+```bash
+# 세션 생성 (전략 config + 초기 자본 지정)
+fithia2 paper create \
+  --name my_session \
+  --config configs/experiments/return_max_long_v6new.9.json \
+  --capital 10000
+
+# 세션 목록 및 상태 확인
+fithia2 paper list
+fithia2 paper status                 # 전체 세션 요약
+fithia2 paper status --session my_session
+
+# 당일 처리 실행 (종일 단일 실행 방식)
+fithia2 paper run --session my_session
+
+# 분리 실행 방식 (3:40 PM, 9:30 AM 두 번 실행)
+fithia2 paper run-close --session my_session   # 장 마감 전: same-day MOC 진입
+fithia2 paper run-open  --session my_session   # 장 시작 후: 전날 exit + after-close 진입
+
+# 포지션 및 거래 내역 확인
+fithia2 paper positions              # 전체 세션 오픈 포지션
+fithia2 paper trades                 # 최근 거래 내역
+fithia2 paper equity                 # 세션별 수익 곡선
+
+# 세션 종료
+fithia2 paper close --session my_session
+```
+
+#### Reconciliation (자동 불일치 감지)
+
+`run` / `run-open` 실행 시 매일 자동으로 Alpaca ↔ 로컬 DB 정합성 검증:
+
+| 상황 | 감지 방식 | 처리 |
+|------|-----------|------|
+| **Orphaned position** | Alpaca에 있지만 로컬 DB에 없음 (주문 체결 후 DB 저장 실패 등) | WARNING 로그, 수동 확인 필요 |
+| **Ghost position** | 로컬 DB에 있지만 Alpaca에 없음 (수동 청산, 주문 미체결 등) | 자동으로 로컬 상태 닫고 `RECONCILED` 거래 기록 |
+| **Stale orders** | 전일 미체결 주문 | 자동 취소 |
+| **Order fill verify** | 시장가 주문 체결 여부 확인 (2초 polling) | 미체결 시 로컬 상태 저장 skip |
+
+#### Kill Switch
+
+drawdown이 초기 자본 대비 **25% 이상** 떨어지면 자동 발동:
+- 당일 부터 모든 신규 진입 차단
+- `fithia2 paper status`에서 `Kill Switch: ON` 표시
+- 수동으로만 해제 가능
+
 ### 실험 결과 기록
 
 ```bash