From 93e31cf66717b36fe6dbc1146f5010b7d1953393 Mon Sep 17 00:00:00 2001
From: agentson <agentson@localhost>
Date: Mon, 16 Feb 2026 12:29:54 +0900
Subject: [PATCH] docs: restore onboarding context and clarify runtime-impact
 gaps

---
 README.md                | 32 +++++++++++++++++++++++++++++++-
 docs/architecture.md     | 34 ++++++++++++++++++++++++++++++++--
 docs/requirements-log.md | 12 ++++++++++++
 docs/testing.md          |  7 +++++++
 4 files changed, 82 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index a92d960..b51db0b 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,35 @@ KIS API 기반 자동매매 + Gemini 기반 장전 전략 생성 + 장중 로컬
 - `src/dashboard/app.py`: FastAPI 관측 API
 - `src/notifications/telegram_client.py`: 알림 및 명령 핸들러
 
+## Quick Start
+
+### 1. 환경 설정
+
+```bash
+cp .env.example .env
+```
+
+필수 값:
+
+- `KIS_APP_KEY`
+- `KIS_APP_SECRET`
+- `KIS_ACCOUNT_NO`
+- `GEMINI_API_KEY`
+
+### 2. 의존성 설치
+
+```bash
+pip install -e ".[dev]"
+```
+
+### 3. 테스트
+
+```bash
+pytest -v --cov=src
+ruff check src/ tests/
+mypy src/ --strict
+```
+
 ## 실행
 
 ### 기본 실행
@@ -64,11 +93,12 @@ DASHBOARD_PORT=8080
 - `Issue 4-1` 미구현: `/report`, `/scenarios`, `/review`, `/dashboard` Telegram 명령 미등록
 - `Issue 1-7` 일부 미완:
 - `price_change_pct` 정규화 어댑터 명시 구현 없음
+- 영향: `price_change_pct_above/below` 조건을 사용하는 시나리오는 사실상 매칭 불가(dead path)
 - HOLD 시 별도 손절 모니터링 플래그 처리 분리 미흡
 - 시장 코드 정합성 이슈:
 - 설정 기본값은 `ENABLED_MARKETS="KR,US"`
 - 스케줄 정의는 `US_NASDAQ`, `US_NYSE` 중심
-- 완전 통합 전 추가 정리 필요
+- 영향: `get_open_markets(["KR", "US"])`에서 `US` 미정의로 US 시장이 누락될 수 있음(런타임 영향)
 
 ## 테스트
 
diff --git a/docs/architecture.md b/docs/architecture.md
index ba94f50..556dfcc 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -16,15 +16,20 @@ The Ouroboros V2는 `Proactive` 구조를 중심으로 동작합니다.
 - `DailyReviewer` / `EvolutionOptimizer`
 - `TelegramClient` / `TelegramCommandHandler`
 
+안전/운영 컴포넌트도 핵심입니다.
+
+- `RiskManager`: circuit breaker, fat-finger 검증
+- `PriorityTaskQueue` + `CriticalityAssessor`: 우선순위/지연 제어
+
 ## Market Scope
 
 V2 기본 설정은 `ENABLED_MARKETS="KR,US"` 입니다.
 
-현재 코드 기준 주의점:
+현재 코드 기준 주의점(런타임 영향):
 
 - 설정은 `KR,US`를 기본값으로 사용
 - 스케줄 레이어(`src/markets/schedule.py`)는 `US_NASDAQ`, `US_NYSE` 구조를 아직 유지
-- 완전한 `US` 단일 코드 통합은 추가 정리 필요
+- `US` 코드가 스케줄에 직접 정의되지 않아 US 시장 누락 가능성이 있음
 
 ## Decision Flow
 
@@ -50,6 +55,30 @@ V2 기본 설정은 `ENABLED_MARKETS="KR,US"` 입니다.
 4. `generate_lessons()`로 장후 교훈 생성
 5. (US 종료 시) `EvolutionOptimizer.evolve()` 실행
 
+## Risk Policy
+
+- `RiskManager`는 주문 전 검증을 강제합니다.
+- circuit breaker: 손실 임계치 하회 시 거래 중단
+- fat-finger: 주문 금액 과대 시 주문 차단
+- 실패 시 알림은 보내되, 예외 처리로 루프 안정성 유지
+
+## Error Handling Strategy
+
+- API 호출 실패: 재시도(지수 백오프) 후 종목/사이클 스킵
+- 시나리오/플래너 실패: empty 또는 defensive playbook으로 안전 폴백
+- Telegram 실패: warning 로깅 후 거래 루프 지속
+- 대시보드 스레드 실패: warning 로깅 후 메인 트레이딩 루프와 분리 유지
+
+## Configuration Reference
+
+상세 설정은 `src/config.py`를 기준으로 합니다.
+
+- 거래 모드: `TRADE_MODE`, `DAILY_SESSIONS`, `SESSION_INTERVAL_HOURS`
+- 전략: `PRE_MARKET_MINUTES`, `MAX_SCENARIOS_PER_STOCK`, `RESCAN_INTERVAL_SECONDS`
+- 시장: `ENABLED_MARKETS`
+- 대시보드: `DASHBOARD_ENABLED`, `DASHBOARD_HOST`, `DASHBOARD_PORT`
+- 알림: `TELEGRAM_*`
+
 ## Context Tree
 
 레이어 전략:
@@ -107,5 +136,6 @@ V2 기본 설정은 `ENABLED_MARKETS="KR,US"` 입니다.
 - `Issue 4-1` Telegram 확장 명령 미구현 (`/report`, `/scenarios`, `/review`, `/dashboard`)
 - `Issue 1-7` 일부 미완:
 - `price_change_pct` 정규화 계층 명시 미흡
+- 영향: `price_change_pct` 기반 조건은 현재 사실상 매칭되지 않음
 - HOLD 시 별도 손절 모니터링 플래그 처리 미완
 - US 스캐닝 확장(`fetch_overseas_rankings`) 미구현
diff --git a/docs/requirements-log.md b/docs/requirements-log.md
index 74f5a63..730bacd 100644
--- a/docs/requirements-log.md
+++ b/docs/requirements-log.md
@@ -119,3 +119,15 @@
 **이슈/브랜치:**
 - Issue: #131
 - Branch(worktree): `feature/issue-131-docs-v2-status-sync`
+
+### 문서 보강 2차 (리뷰 반영)
+
+**리뷰 피드백 반영:**
+- README에 Quick Start(환경설정/설치/검증) 복원
+- architecture에 RiskManager/에러 처리/설정 레퍼런스 복원
+- testing 문서에 기존 핵심 테스트 파일 설명 복원
+- 시장 코드 불일치(`KR,US` vs `US_NASDAQ/US_NYSE`)를 "런타임 영향"으로 격상 명시
+- `price_change_pct` 누락 영향(조건 dead path)을 명시
+
+**의도:**
+- V2 상태 반영과 기존 온보딩/운영 문서 가치를 동시에 유지
diff --git a/docs/testing.md b/docs/testing.md
index ee6a414..84f4f9b 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -21,6 +21,13 @@ V2 핵심 영역 테스트가 포함되어 있습니다.
 - `tests/test_dashboard.py`
 - `tests/test_main.py`
 
+기존 핵심 영역 테스트도 유지됩니다.
+
+- `tests/test_risk.py`: circuit breaker/fat-finger 안전장치 검증
+- `tests/test_broker.py`: KIS API 호출/에러 처리/인증 흐름 검증
+- `tests/test_brain.py`: Gemini 응답 파싱/신뢰도 게이트 검증
+- `tests/test_market_schedule.py`: 시장 오픈/클로즈/타임존 로직 검증
+
 ## Required Checks
 
 ```bash