docs: add requirements log entry for overseas limit order fix (#149 )

fix: use current_price for overseas limit orders (KIS VTS rejects market orders) (#149 )
KIS VTS (paper trading) rejects overseas market orders with: "모의투자 주문처리가 안되었습니다(지정가만 가능한 상품입니다)" Root cause: send_overseas_order() was called with price=0.0 (market order) in both trading_cycle() and run_daily_session(), even though current_price was already computed correctly by Fix #147 (exchange code mapping). Fix: pass current_price as the limit order price in both call sites. Domestic broker send_order() keeps price=0 (market orders are fine on KRX). Adds regression test TestOverseasBalanceParsing::test_overseas_buy_order_uses_limit_price verifying price=182.5 is passed, not 0.0. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-02-18 23:54:18 +09:00 · 2026-02-18 23:53:15 +09:00 · 2026-02-18 23:48:14 +09:00 · 2026-02-18 22:23:57 +09:00 · 2026-02-18 02:05:50 +09:00 · 2026-02-18 02:02:13 +09:00
32 changed files with 3811 additions and 575 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -15,6 +15,9 @@ pytest -v --cov=src

 # Run (paper trading)
 python -m src.main --mode=paper
+
+# Run with dashboard
+python -m src.main --mode=paper --dashboard
 ```

 ## Telegram Notifications (Optional)
@@ -43,6 +46,10 @@ Get real-time alerts for trades, circuit breakers, and system events via Telegra
 - ℹ️ Market open/close notifications
 - 📝 System startup/shutdown status

+### Interactive Commands
+
+With `TELEGRAM_COMMANDS_ENABLED=true` (default), the bot supports 9 bidirectional commands: `/help`, `/status`, `/positions`, `/report`, `/scenarios`, `/review`, `/dashboard`, `/stop`, `/resume`.
+
 **Fail-safe**: Notifications never crash the trading system. Missing credentials or API errors are logged but trading continues normally.

 ## Smart Volatility Scanner (Optional)
@@ -109,17 +116,23 @@ User requirements and feedback are tracked in [docs/requirements-log.md](docs/re
 ```
 src/
 ├── analysis/        # Technical analysis (RSI, volatility, smart scanner)
+├── backup/          # Disaster recovery (scheduler, cloud storage, health)
+├── brain/           # Gemini AI decision engine (prompt optimizer, context selector)
 ├── broker/          # KIS API client (domestic + overseas)
-├── brain/           # Gemini AI decision engine
+├── context/         # L1-L7 hierarchical memory system
 ├── core/            # Risk manager (READ-ONLY)
-├── evolution/       # Self-improvement optimizer
+├── dashboard/       # FastAPI read-only monitoring (8 API endpoints)
+├── data/            # External data integration (news, market data, calendar)
+├── evolution/       # Self-improvement (optimizer, daily review, scorecard)
+├── logging/         # Decision logger (audit trail)
 ├── markets/         # Market schedules and timezone handling
-├── notifications/   # Telegram real-time alerts
+├── notifications/   # Telegram alerts + bidirectional commands (9 commands)
+├── strategy/        # Pre-market planner, scenario engine, playbook store
 ├── db.py            # SQLite trade logging
 ├── main.py          # Trading loop orchestrator
 └── config.py        # Settings (from .env)

-tests/               # 343 tests across 14 files
+tests/               # 551 tests across 25 files
 docs/                # Extended documentation
 ```

@@ -131,6 +144,7 @@ ruff check src/ tests/           # Lint
 mypy src/ --strict               # Type check

 python -m src.main --mode=paper  # Paper trading
+python -m src.main --mode=paper --dashboard  # With dashboard
 python -m src.main --mode=live   # Live trading (⚠️ real money)

 # Gitea workflow (requires tea CLI)
--- a/README.md
+++ b/README.md
@@ -10,28 +10,41 @@ KIS(한국투자증권) API로 매매하고, Google Gemini로 판단하며, 자
 │  (매매 실행) │     │ (거래 루프)  │     │  (의사결정)  │
 └─────────────┘     └──────┬──────┘     └─────────────┘
                           │
-                    ┌──────┴──────┐
-                    │Risk Manager │
-                    │  (안전장치)  │
-                    └──────┬──────┘
-                           │
-                    ┌──────┴──────┐
-                    │  Evolution  │
-                    │ (전략 진화)  │
-                    └─────────────┘
+              ┌────────────┼────────────┐
+              │            │            │
+       ┌──────┴──────┐ ┌──┴───┐ ┌──────┴──────┐
+       │Risk Manager │ │  DB  │ │  Telegram   │
+       │  (안전장치)  │ │      │ │ (알림+명령)  │
+       └──────┬──────┘ └──────┘ └─────────────┘
+              │
+     ┌────────┼────────┐
+     │        │        │
+┌────┴────┐┌──┴──┐┌────┴─────┐
+│Strategy ││Ctx  ││Evolution │
+│(플레이북)││(메모리)││ (진화)   │
+└─────────┘└─────┘└──────────┘
 ```

+**v2 핵심**: "Plan Once, Execute Locally" — 장 시작 전 AI가 시나리오 플레이북을 1회 생성하고, 거래 시간에는 로컬 시나리오 매칭만 수행하여 API 비용과 지연 시간을 대폭 절감.
+
 ## 핵심 모듈

-| 모듈 | 파일 | 설명 |
+| 모듈 | 위치 | 설명 |
 |------|------|------|
-| 설정 | `src/config.py` | Pydantic 기반 환경변수 로딩 및 타입 검증 |
-| 브로커 | `src/broker/kis_api.py` | KIS API 비동기 래퍼 (토큰 갱신, 레이트 리미터, 해시키) |
-| 두뇌 | `src/brain/gemini_client.py` | Gemini 프롬프트 구성 및 JSON 응답 파싱 |
-| 방패 | `src/core/risk_manager.py` | 서킷 브레이커 + 팻 핑거 체크 |
-| 알림 | `src/notifications/telegram_client.py` | 텔레그램 실시간 거래 알림 (선택사항) |
-| 진화 | `src/evolution/optimizer.py` | 실패 패턴 분석 → 새 전략 생성 → 테스트 → PR |
-| DB | `src/db.py` | SQLite 거래 로그 기록 |
+| 설정 | `src/config.py` | Pydantic 기반 환경변수 로딩 및 타입 검증 (35+ 변수) |
+| 브로커 | `src/broker/` | KIS API 비동기 래퍼 (국내 + 해외 9개 시장) |
+| 두뇌 | `src/brain/` | Gemini 프롬프트 구성, JSON 파싱, 토큰 최적화 |
+| 방패 | `src/core/risk_manager.py` | 서킷 브레이커 + 팻 핑거 체크 (READ-ONLY) |
+| 전략 | `src/strategy/` | Pre-Market Planner, Scenario Engine, Playbook Store |
+| 컨텍스트 | `src/context/` | L1-L7 계층형 메모리 시스템 |
+| 분석 | `src/analysis/` | RSI, ATR, Smart Volatility Scanner |
+| 알림 | `src/notifications/` | 텔레그램 양방향 (알림 + 9개 명령어) |
+| 대시보드 | `src/dashboard/` | FastAPI 읽기 전용 모니터링 (8개 API) |
+| 진화 | `src/evolution/` | 전략 진화 + Daily Review + Scorecard |
+| 의사결정 로그 | `src/logging/` | 전체 거래 결정 감사 추적 |
+| 데이터 | `src/data/` | 뉴스, 시장 데이터, 경제 캘린더 연동 |
+| 백업 | `src/backup/` | 자동 백업, S3 클라우드, 무결성 검증 |
+| DB | `src/db.py` | SQLite 거래 로그 (5개 테이블) |

 ## 안전장치

@@ -42,6 +55,7 @@ KIS(한국투자증권) API로 매매하고, Google Gemini로 판단하며, 자
 | 신뢰도 임계값 | Gemini 신뢰도 80 미만이면 강제 HOLD |
 | 레이트 리미터 | Leaky Bucket 알고리즘으로 API 호출 제한 |
 | 토큰 자동 갱신 | 만료 1분 전 자동으로 Access Token 재발급 |
+| 손절 모니터링 | 플레이북 시나리오 기반 실시간 포지션 보호 |

 ## 빠른 시작

@@ -67,7 +81,11 @@ pytest -v --cov=src --cov-report=term-missing
 ### 4. 실행 (모의투자)

 ```bash
+# 기본 실행
 python -m src.main --mode=paper
+
+# 대시보드 활성화
+python -m src.main --mode=paper --dashboard
 ```

 ### 5. Docker 실행
@@ -76,7 +94,20 @@ python -m src.main --mode=paper
 docker compose up -d ouroboros
 ```

-## 텔레그램 알림 (선택사항)
+## 지원 시장
+
+| 국가 | 거래소 | 코드 |
+|------|--------|------|
+| 🇰🇷 한국 | KRX | KR |
+| 🇺🇸 미국 | NASDAQ, NYSE, AMEX | US_NASDAQ, US_NYSE, US_AMEX |
+| 🇯🇵 일본 | TSE | JP |
+| 🇭🇰 홍콩 | SEHK | HK |
+| 🇨🇳 중국 | 상하이, 선전 | CN_SHA, CN_SZA |
+| 🇻🇳 베트남 | 하노이, 호치민 | VN_HNX, VN_HSX |
+
+`ENABLED_MARKETS` 환경변수로 활성 시장 선택 (기본: `KR,US`).
+
+## 텔레그램 (선택사항)

 거래 실행, 서킷 브레이커 발동, 시스템 상태 등을 텔레그램으로 실시간 알림 받을 수 있습니다.

@@ -102,25 +133,51 @@ docker compose up -d ouroboros
 - ℹ️ 장 시작/종료 알림
 - 📝 시스템 시작/종료 상태

-**안전장치**: 알림 실패해도 거래는 계속 진행됩니다. 텔레그램 API 오류나 설정 누락이 있어도 거래 시스템은 정상 작동합니다.
+### 양방향 명령어
+
+`TELEGRAM_COMMANDS_ENABLED=true` (기본값) 설정 시 9개 대화형 명령어 지원:
+
+| 명령어 | 설명 |
+|--------|------|
+| `/help` | 사용 가능한 명령어 목록 |
+| `/status` | 거래 상태 (모드, 시장, P&L) |
+| `/positions` | 계좌 요약 (잔고, 현금, P&L) |
+| `/report` | 일일 요약 (거래 수, P&L, 승률) |
+| `/scenarios` | 오늘의 플레이북 시나리오 |
+| `/review` | 최근 스코어카드 (L6_DAILY) |
+| `/dashboard` | 대시보드 URL 표시 |
+| `/stop` | 거래 일시 정지 |
+| `/resume` | 거래 재개 |
+
+**안전장치**: 알림 실패해도 거래는 계속 진행됩니다.

 ## 테스트

-35개 테스트가 TDD 방식으로 구현 전에 먼저 작성되었습니다.
+551개 테스트가 25개 파일에 걸쳐 구현되어 있습니다. 최소 커버리지 80%.

 ```
-tests/test_risk.py   — 서킷 브레이커, 팻 핑거, 통합 검증 (11개)
-tests/test_broker.py — 토큰 관리, 타임아웃, HTTP 에러, 해시키 (6개)
-tests/test_brain.py  — JSON 파싱, 신뢰도 임계값, 비정상 응답 처리 (15개)
+tests/test_scenario_engine.py    — 시나리오 매칭 (44개)
+tests/test_data_integration.py   — 외부 데이터 연동 (38개)
+tests/test_pre_market_planner.py — 플레이북 생성 (37개)
+tests/test_main.py               — 거래 루프 통합 (37개)
+tests/test_token_efficiency.py   — 토큰 최적화 (34개)
+tests/test_strategy_models.py    — 전략 모델 검증 (33개)
+tests/test_telegram_commands.py  — 텔레그램 명령어 (31개)
+tests/test_latency_control.py    — 지연시간 제어 (30개)
+tests/test_telegram.py           — 텔레그램 알림 (25개)
+... 외 16개 파일
 ```

+**상세**: [docs/testing.md](docs/testing.md)
+
 ## 기술 스택

 - **언어**: Python 3.11+ (asyncio 기반)
- **브로커**: KIS Open API (REST)
+- **브로커**: KIS Open API (REST, 국내+해외)
 - **AI**: Google Gemini Pro
- **DB**: SQLite
- **검증**: pytest + coverage
+- **DB**: SQLite (5개 테이블: trades, contexts, decision_logs, playbooks, context_metadata)
+- **대시보드**: FastAPI + uvicorn
+- **검증**: pytest + coverage (551 tests)
 - **CI/CD**: GitHub Actions
 - **배포**: Docker + Docker Compose

@@ -128,27 +185,50 @@ tests/test_brain.py  — JSON 파싱, 신뢰도 임계값, 비정상 응답 처

 ```
 The-Ouroboros/
-├── .github/workflows/ci.yml     # CI 파이프라인
 ├── docs/
-│   ├── agents.md                # AI 에이전트 페르소나 정의
-│   └── skills.md                # 사용 가능한 도구 목록
+│   ├── architecture.md          # 시스템 아키텍처
+│   ├── testing.md               # 테스트 가이드
+│   ├── commands.md              # 명령어 레퍼런스
+│   ├── context-tree.md          # L1-L7 메모리 시스템
+│   ├── workflow.md              # Git 워크플로우
+│   ├── agents.md                # 에이전트 정책
+│   ├── skills.md                # 도구 목록
+│   ├── disaster_recovery.md     # 백업/복구
+│   └── requirements-log.md      # 요구사항 기록
 ├── src/
-│   ├── config.py                      # Pydantic 설정
-│   ├── logging_config.py              # JSON 구조화 로깅
-│   ├── db.py                          # SQLite 거래 기록
-│   ├── main.py                        # 비동기 거래 루프
-│   ├── broker/kis_api.py              # KIS API 클라이언트
-│   ├── brain/gemini_client.py         # Gemini 의사결정 엔진
-│   ├── core/risk_manager.py           # 리스크 관리
-│   ├── notifications/telegram_client.py # 텔레그램 알림
-│   ├── evolution/optimizer.py         # 전략 진화 엔진
-│   └── strategies/base.py             # 전략 베이스 클래스
-├── tests/                       # TDD 테스트 스위트
+│   ├── analysis/                # 기술적 분석 (RSI, ATR, Smart Scanner)
+│   ├── backup/                  # 백업 (스케줄러, S3, 무결성 검증)
+│   ├── brain/                   # Gemini 의사결정 (프롬프트 최적화, 컨텍스트 선택)
+│   ├── broker/                  # KIS API (국내 + 해외)
+│   ├── context/                 # L1-L7 계층 메모리
+│   ├── core/                    # 리스크 관리 (READ-ONLY)
+│   ├── dashboard/               # FastAPI 모니터링 대시보드
+│   ├── data/                    # 외부 데이터 연동
+│   ├── evolution/               # 전략 진화 + Daily Review
+│   ├── logging/                 # 의사결정 감사 추적
+│   ├── markets/                 # 시장 스케줄 + 타임존
+│   ├── notifications/           # 텔레그램 알림 + 명령어
+│   ├── strategy/                # 플레이북 (Planner, Scenario Engine)
+│   ├── config.py                # Pydantic 설정
+│   ├── db.py                    # SQLite 데이터베이스
+│   └── main.py                  # 비동기 거래 루프
+├── tests/                       # 551개 테스트 (25개 파일)
 ├── Dockerfile                   # 멀티스테이지 빌드
 ├── docker-compose.yml           # 서비스 오케스트레이션
 └── pyproject.toml               # 의존성 및 도구 설정
 ```

+## 문서
+
+- **[아키텍처](docs/architecture.md)** — 시스템 설계, 컴포넌트, 데이터 흐름
+- **[테스트](docs/testing.md)** — 테스트 구조, 커버리지, 작성 가이드
+- **[명령어](docs/commands.md)** — CLI, Dashboard, Telegram 명령어
+- **[컨텍스트 트리](docs/context-tree.md)** — L1-L7 계층 메모리
+- **[워크플로우](docs/workflow.md)** — Git 워크플로우 정책
+- **[에이전트 정책](docs/agents.md)** — 안전 제약, 금지 행위
+- **[백업/복구](docs/disaster_recovery.md)** — 재해 복구 절차
+- **[요구사항](docs/requirements-log.md)** — 사용자 요구사항 추적
+
 ## 라이선스

 이 프로젝트의 라이선스는 [LICENSE](LICENSE) 파일을 참조하세요.
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -2,7 +2,9 @@

 ## Overview

-Self-evolving AI trading agent for global stock markets via KIS (Korea Investment & Securities) API. The main loop in `src/main.py` orchestrates four components across multiple markets with two trading modes: daily (batch API calls) or realtime (per-stock decisions).
+Self-evolving AI trading agent for global stock markets via KIS (Korea Investment & Securities) API. The main loop in `src/main.py` orchestrates components across multiple markets with two trading modes: daily (batch API calls) or realtime (per-stock decisions).
+
+**v2 Proactive Playbook Architecture**: The system uses a "plan once, execute locally" approach. Pre-market, the AI generates a playbook of scenarios (one Gemini API call per market per day). During trading hours, a local scenario engine matches live market data against these pre-computed scenarios — no additional AI calls needed. This dramatically reduces API costs and latency.

 ## Trading Modes

@@ -46,9 +48,11 @@ High-frequency trading with individual stock analysis:
 **KISBroker** (`kis_api.py`) — Async KIS API client for domestic Korean market

 - Automatic OAuth token refresh (valid for 24 hours)
- Leaky-bucket rate limiter (10 requests per second)
+- Leaky-bucket rate limiter (configurable RPS, default 2.0)
 - POST body hash-key signing for order authentication
 - Custom SSL context with disabled hostname verification for VTS (virtual trading) endpoint due to known certificate mismatch
+- `fetch_market_rankings()` — Fetch volume surge rankings from KIS API
+- `get_daily_prices()` — Fetch OHLCV history for technical analysis

 **OverseasBroker** (`overseas.py`) — KIS overseas stock API wrapper

@@ -63,10 +67,11 @@ High-frequency trading with individual stock analysis:
 - `is_market_open()` checks weekends, trading hours, lunch breaks
 - `get_open_markets()` returns currently active markets
 - `get_next_market_open()` finds next market to open and when
+- 10 global markets defined (KR, US_NASDAQ, US_NYSE, US_AMEX, JP, HK, CN_SHA, CN_SZA, VN_HNX, VN_HSX)

-**New API Methods** (added in v0.9.0):
- `fetch_market_rankings()` — Fetch volume surge rankings from KIS API
- `get_daily_prices()` — Fetch OHLCV history for technical analysis
+**Overseas Ranking API Methods** (added in v0.10.x):
+- `fetch_overseas_rankings()` — Fetch overseas ranking universe (fluctuation / volume)
+- Ranking endpoint paths and TR_IDs are configurable via environment variables

 ### 2. Analysis (`src/analysis/`)

@@ -81,24 +86,28 @@ High-frequency trading with individual stock analysis:

 **SmartVolatilityScanner** (`smart_scanner.py`) — Python-first filtering pipeline

- **Step 1**: Fetch volume rankings from KIS API (top 30 stocks)
- **Step 2**: Calculate RSI and volume ratio for each stock
- **Step 3**: Apply filters:
-  - Volume ratio >= `VOL_MULTIPLIER` (default 2.0x previous day)
-  - RSI < `RSI_OVERSOLD_THRESHOLD` (30) OR RSI > `RSI_MOMENTUM_THRESHOLD` (70)
- **Step 4**: Score candidates by RSI extremity (60%) + volume surge (40%)
- **Step 5**: Return top N candidates (default 3) for AI analysis
- **Fallback**: Uses static watchlist if ranking API unavailable
+- **Domestic (KR)**:
+  - **Step 1**: Fetch domestic fluctuation ranking as primary universe
+  - **Step 2**: Fetch domestic volume ranking for liquidity bonus
+  - **Step 3**: Compute volatility-first score (max of daily change% and intraday range%)
+  - **Step 4**: Apply liquidity bonus and return top N candidates
+- **Overseas (US/JP/HK/CN/VN)**:
+  - **Step 1**: Fetch overseas ranking universe (fluctuation rank + volume rank bonus)
+  - **Step 2**: Compute volatility-first score (max of daily change% and intraday range%)
+  - **Step 3**: Apply liquidity bonus from volume ranking
+  - **Step 4**: Return top N candidates (default 3)
+- **Fallback (overseas only)**: If ranking API is unavailable, uses dynamic universe
+  from runtime active symbols + recent traded symbols + current holdings (no static watchlist)
 - **Realtime mode only**: Daily mode uses batch processing for API efficiency

 **Benefits:**
 - Reduces Gemini API calls from 20-30 stocks to 1-3 qualified candidates
 - Fast Python-based filtering before expensive AI judgment
- Logs selection context (RSI, volume_ratio, signal, score) for Evolution system
+- Logs selection context (RSI-compatible proxy, volume_ratio, signal, score) for Evolution system

-### 3. Brain (`src/brain/gemini_client.py`)
+### 3. Brain (`src/brain/`)

-**GeminiClient** — AI decision engine powered by Google Gemini
+**GeminiClient** (`gemini_client.py`) — AI decision engine powered by Google Gemini

 - Constructs structured prompts from market data
 - Parses JSON responses into `TradeDecision` objects (`action`, `confidence`, `rationale`)
@@ -106,11 +115,20 @@ High-frequency trading with individual stock analysis:
 - Falls back to safe HOLD on any parse/API error
 - Handles markdown-wrapped JSON, malformed responses, invalid actions

+**PromptOptimizer** (`prompt_optimizer.py`) — Token efficiency optimization
+
+- Reduces prompt size while preserving decision quality
+- Caches optimized prompts
+
+**ContextSelector** (`context_selector.py`) — Relevant context selection for prompts
+
+- Selects appropriate context layers for current market conditions
+
 ### 4. Risk Manager (`src/core/risk_manager.py`)

 **RiskManager** — Safety circuit breaker and order validation

-⚠️ **READ-ONLY by policy** (see [`docs/agents.md`](./agents.md))
+> **READ-ONLY by policy** (see [`docs/agents.md`](./agents.md))

 - **Circuit Breaker**: Halts all trading via `SystemExit` when daily P&L drops below -3.0%
  - Threshold may only be made stricter, never relaxed
@@ -118,7 +136,79 @@ High-frequency trading with individual stock analysis:
 - **Fat-Finger Protection**: Rejects orders exceeding 30% of available cash
  - Must always be enforced, cannot be disabled

-### 5. Notifications (`src/notifications/telegram_client.py`)
+### 5. Strategy (`src/strategy/`)
+
+**Pre-Market Planner** (`pre_market_planner.py`) — AI playbook generation
+
+- Runs before market open (configurable `PRE_MARKET_MINUTES`, default 30)
+- Generates scenario-based playbooks via single Gemini API call per market
+- Handles timeout (`PLANNER_TIMEOUT_SECONDS`, default 60) with defensive playbook fallback
+- Persists playbooks to database for audit trail
+
+**Scenario Engine** (`scenario_engine.py`) — Local scenario matching
+
+- Matches live market data against pre-computed playbook scenarios
+- No AI calls during trading hours — pure Python matching logic
+- Returns matched scenarios with confidence scores
+- Configurable `MAX_SCENARIOS_PER_STOCK` (default 5)
+- Periodic rescan at `RESCAN_INTERVAL_SECONDS` (default 300)
+
+**Playbook Store** (`playbook_store.py`) — Playbook persistence
+
+- SQLite-backed storage for daily playbooks
+- Date and market-based retrieval
+- Status tracking (generated, active, expired)
+
+**Models** (`models.py`) — Pydantic data models
+
+- Scenario, Playbook, MatchResult, and related type definitions
+
+### 6. Context System (`src/context/`)
+
+**Context Store** (`store.py`) — L1-L7 hierarchical memory
+
+- 7-layer context system (see [docs/context-tree.md](./context-tree.md)):
+  - L1: Tick-level (real-time price)
+  - L2: Intraday (session summary)
+  - L3: Daily (end-of-day)
+  - L4: Weekly (trend analysis)
+  - L5: Monthly (strategy review)
+  - L6: Daily Review (scorecard)
+  - L7: Evolution (long-term learning)
+- Key-value storage with timeframe tagging
+- SQLite persistence in `contexts` table
+
+**Context Scheduler** (`scheduler.py`) — Periodic aggregation
+
+- Scheduled summarization from lower to higher layers
+- Configurable aggregation intervals
+
+**Context Summarizer** (`summarizer.py`) — Layer summarization
+
+- Aggregates lower-layer data into higher-layer summaries
+
+### 7. Dashboard (`src/dashboard/`)
+
+**FastAPI App** (`app.py`) — Read-only monitoring dashboard
+
+- Runs as daemon thread when enabled (`--dashboard` CLI flag or `DASHBOARD_ENABLED=true`)
+- Configurable host/port (`DASHBOARD_HOST`, `DASHBOARD_PORT`, default `127.0.0.1:8080`)
+- Serves static HTML frontend
+
+**8 API Endpoints:**
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` | GET | Static HTML dashboard |
+| `/api/status` | GET | Daily trading status by market |
+| `/api/playbook/{date}` | GET | Playbook for specific date and market |
+| `/api/scorecard/{date}` | GET | Daily scorecard from L6_DAILY context |
+| `/api/performance` | GET | Trading performance metrics (by market + combined) |
+| `/api/context/{layer}` | GET | Query context by layer (L1-L7) |
+| `/api/decisions` | GET | Decision log entries with outcomes |
+| `/api/scenarios/active` | GET | Today's matched scenarios |
+
+### 8. Notifications (`src/notifications/telegram_client.py`)

 **TelegramClient** — Real-time event notifications via Telegram Bot API

@@ -126,7 +216,13 @@ High-frequency trading with individual stock analysis:
 - Non-blocking: failures are logged but never crash trading
 - Rate-limited: 1 message/second default to respect Telegram API limits
 - Auto-disabled when credentials missing
- Gracefully handles API errors, network timeouts, invalid tokens
+
+**TelegramCommandHandler** — Bidirectional command interface
+
+- Long polling from Telegram API (configurable `TELEGRAM_POLLING_INTERVAL`)
+- 9 interactive commands: `/help`, `/status`, `/positions`, `/report`, `/scenarios`, `/review`, `/dashboard`, `/stop`, `/resume`
+- Authorization filtering by `TELEGRAM_CHAT_ID`
+- Enable/disable via `TELEGRAM_COMMANDS_ENABLED` (default: true)

 **Notification Types:**
 - Trade execution (BUY/SELL with confidence)
@@ -134,12 +230,12 @@ High-frequency trading with individual stock analysis:
 - Fat-finger protection triggers (order rejection)
 - Market open/close events
 - System startup/shutdown status
+- Playbook generation results
+- Stop-loss monitoring alerts

-**Setup:** See [src/notifications/README.md](../src/notifications/README.md) for bot creation and configuration.
+### 9. Evolution (`src/evolution/`)

-### 6. Evolution (`src/evolution/optimizer.py`)
-
-**StrategyOptimizer** — Self-improvement loop
+**StrategyOptimizer** (`optimizer.py`) — Self-improvement loop

 - Analyzes high-confidence losing trades from SQLite
 - Asks Gemini to generate new `BaseStrategy` subclasses
@@ -147,99 +243,198 @@ High-frequency trading with individual stock analysis:
 - Simulates PR creation for human review
 - Only activates strategies that pass all tests

+**DailyReview** (`daily_review.py`) — End-of-day review
+
+- Generates comprehensive trade performance summary
+- Stores results in L6_DAILY context layer
+- Tracks win rate, P&L, confidence accuracy
+
+**DailyScorecard** (`scorecard.py`) — Performance scoring
+
+- Calculates daily metrics (trades, P&L, win rate, avg confidence)
+- Enables trend tracking across days
+
+**Stop-Loss Monitoring** — Real-time position protection
+
+- Monitors positions against stop-loss levels from playbook scenarios
+- Sends Telegram alerts when thresholds approached or breached
+
+### 10. Decision Logger (`src/logging/decision_logger.py`)
+
+**DecisionLogger** — Comprehensive audit trail
+
+- Logs every trading decision with full context snapshot
+- Captures input data, rationale, confidence, and outcomes
+- Supports outcome tracking (P&L, accuracy) for post-analysis
+- Stored in `decision_logs` table with indexed queries
+- Review workflow support (reviewed flag, review notes)
+
+### 11. Data Integration (`src/data/`)
+
+**External Data Sources** (optional):
+
+- `news_api.py` — News sentiment data
+- `market_data.py` — Extended market data
+- `economic_calendar.py` — Economic event calendar
+
+### 12. Backup (`src/backup/`)
+
+**Disaster Recovery** (see [docs/disaster_recovery.md](./disaster_recovery.md)):
+
+- `scheduler.py` — Automated backup scheduling
+- `exporter.py` — Data export to various formats
+- `cloud_storage.py` — S3-compatible cloud backup
+- `health_monitor.py` — Backup integrity verification
+
 ## Data Flow

+### Playbook Mode (Daily — Primary v2 Flow)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Pre-Market Phase (before market open)                       │
+└─────────────────────────────────────────────────────────────┘
+                           │
+                           ▼
+        ┌──────────────────────────────────┐
+        │ Pre-Market Planner               │
+        │ - 1 Gemini API call per market   │
+        │ - Generate scenario playbook     │
+        │ - Store in playbooks table       │
+        └──────────────────┬───────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Trading Hours (market open → close)                         │
+└─────────────────────────────────────────────────────────────┘
+                           │
+                           ▼
+        ┌──────────────────────────────────┐
+        │ Market Schedule Check            │
+        │ - Get open markets               │
+        │ - Filter by enabled markets      │
+        └──────────────────┬───────────────┘
+                           │
+                           ▼
+        ┌──────────────────────────────────┐
+        │ Scenario Engine (local)          │
+        │ - Match live data vs playbook    │
+        │ - No AI calls needed             │
+        │ - Return matched scenarios       │
+        └──────────────────┬───────────────┘
+                           │
+                           ▼
+        ┌──────────────────────────────────┐
+        │ Risk Manager: Validate Order     │
+        │ - Check circuit breaker          │
+        │ - Check fat-finger limit         │
+        └──────────────────┬───────────────┘
+                           │
+                           ▼
+        ┌──────────────────────────────────┐
+        │ Broker: Execute Order            │
+        │ - Domestic: send_order()         │
+        │ - Overseas: send_overseas_order()│
+        └──────────────────┬───────────────┘
+                           │
+                           ▼
+        ┌──────────────────────────────────┐
+        │ Decision Logger + DB             │
+        │ - Full audit trail               │
+        │ - Context snapshot               │
+        │ - Telegram notification          │
+        └──────────────────┬───────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Post-Market Phase                                           │
+└─────────────────────────────────────────────────────────────┘
+                           │
+                           ▼
+        ┌──────────────────────────────────┐
+        │ Daily Review + Scorecard         │
+        │ - Performance summary            │
+        │ - Store in L6_DAILY context      │
+        │ - Evolution learning             │
+        └──────────────────────────────────┘
+```
+
 ### Realtime Mode (with Smart Scanner)

 ```
 ┌─────────────────────────────────────────────────────────────┐
-│ Main Loop (60s cycle per market)                           │
+│ Main Loop (60s cycle per market)                            │
 └─────────────────────────────────────────────────────────────┘
                           │
                           ▼
        ┌──────────────────────────────────┐
-        │ Market Schedule Check             │
-        │ - Get open markets                │
-        │ - Filter by enabled markets       │
-        │ - Wait if all closed              │
-        └──────────────────┬────────────────┘
+        │ Market Schedule Check            │
+        │ - Get open markets               │
+        │ - Filter by enabled markets      │
+        │ - Wait if all closed             │
+        └──────────────────┬───────────────┘
                           │
                           ▼
        ┌──────────────────────────────────┐
        │ Smart Scanner (Python-first)      │
-        │ - Fetch volume rankings (KIS)    │
-        │ - Get 20d price history per stock│
-        │ - Calculate RSI(14) + vol ratio  │
-        │ - Filter: vol>2x AND RSI extreme │
+        │ - Domestic: fluctuation rank     │
+        │   + volume rank bonus            │
+        │   + volatility-first scoring     │
+        │ - Overseas: ranking universe     │
+        │   + volatility-first scoring     │
+        │ - Fallback: dynamic universe     │
        │ - Return top 3 qualified stocks  │
-        └──────────────────┬────────────────┘
+        └──────────────────┬───────────────┘
                           │
                           ▼
        ┌──────────────────────────────────┐
-        │ For Each Qualified Candidate      │
-        └──────────────────┬────────────────┘
+        │ For Each Qualified Candidate     │
+        └──────────────────┬───────────────┘
                           │
                           ▼
        ┌──────────────────────────────────┐
        │ Broker: Fetch Market Data        │
        │ - Domestic: orderbook + balance  │
        │ - Overseas: price + balance      │
-        └──────────────────┬────────────────┘
+        └──────────────────┬───────────────┘
                           │
                           ▼
        ┌──────────────────────────────────┐
-        │ Calculate P&L                     │
-        │ pnl_pct = (eval - cost) / cost   │
-        └──────────────────┬────────────────┘
+        │ Brain: Get Decision (AI)         │
+        │ - Build prompt with market data  │
+        │ - Call Gemini API                │
+        │ - Parse JSON response            │
+        │ - Return TradeDecision           │
+        └──────────────────┬───────────────┘
                           │
                           ▼
        ┌──────────────────────────────────┐
-        │ Brain: Get Decision (AI)          │
-        │ - Build prompt with market data   │
-        │ - Call Gemini API                 │
-        │ - Parse JSON response             │
-        │ - Return TradeDecision            │
-        └──────────────────┬────────────────┘
+        │ Risk Manager: Validate Order     │
+        │ - Check circuit breaker          │
+        │ - Check fat-finger limit         │
+        └──────────────────┬───────────────┘
                           │
                           ▼
        ┌──────────────────────────────────┐
-        │ Risk Manager: Validate Order      │
-        │ - Check circuit breaker           │
-        │ - Check fat-finger limit          │
-        │ - Raise if validation fails       │
-        └──────────────────┬────────────────┘
+        │ Broker: Execute Order            │
+        │ - Domestic: send_order()         │
+        │ - Overseas: send_overseas_order()│
+        └──────────────────┬───────────────┘
                           │
                           ▼
        ┌──────────────────────────────────┐
-        │ Broker: Execute Order             │
-        │ - Domestic: send_order()          │
-        │ - Overseas: send_overseas_order() │
-        └──────────────────┬────────────────┘
-                           │
-                           ▼
-        ┌──────────────────────────────────┐
-        │ Notifications: Send Alert         │
-        │ - Trade execution notification    │
-        │ - Non-blocking (errors logged)    │
-        │ - Rate-limited to 1/sec           │
-        └──────────────────┬────────────────┘
-                           │
-                           ▼
-        ┌──────────────────────────────────┐
-        │ Database: Log Trade               │
-        │ - SQLite (data/trades.db)         │
-        │ - Track: action, confidence,      │
-        │   rationale, market, exchange     │
-        │ - NEW: selection_context (JSON)   │
-        │   - RSI, volume_ratio, signal     │
-        │   - For Evolution optimization    │
-        └───────────────────────────────────┘
+        │ Decision Logger + Notifications  │
+        │ - Log trade to SQLite            │
+        │ - selection_context (JSON)       │
+        │ - Telegram notification          │
+        └──────────────────────────────────┘
 ```

 ## Database Schema

-**SQLite** (`src/db.py`)
+**SQLite** (`src/db.py`) — Database: `data/trades.db`

+### trades
 ```sql
 CREATE TABLE trades (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -251,25 +446,73 @@ CREATE TABLE trades (
    quantity INTEGER,
    price REAL,
    pnl REAL DEFAULT 0.0,
-    market TEXT DEFAULT 'KR',       -- KR | US_NASDAQ | JP | etc.
-    exchange_code TEXT DEFAULT 'KRX', -- KRX | NASD | NYSE | etc.
-    selection_context TEXT          -- JSON: {rsi, volume_ratio, signal, score}
+    market TEXT DEFAULT 'KR',
+    exchange_code TEXT DEFAULT 'KRX',
+    selection_context TEXT,        -- JSON: {rsi, volume_ratio, signal, score}
+    decision_id TEXT              -- Links to decision_logs
 );
 ```

-**Selection Context** (new in v0.9.0): Stores scanner selection criteria as JSON:
-```json
-{
-  "rsi": 28.5,
-  "volume_ratio": 2.7,
-  "signal": "oversold",
-  "score": 85.2
-}
+### contexts
+```sql
+CREATE TABLE contexts (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    layer TEXT NOT NULL,           -- L1 through L7
+    timeframe TEXT,
+    key TEXT NOT NULL,
+    value TEXT NOT NULL,           -- JSON data
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+-- Indices: idx_contexts_layer, idx_contexts_timeframe, idx_contexts_updated
 ```

-Enables Evolution system to analyze correlation between selection criteria and trade outcomes.
+### decision_logs
+```sql
+CREATE TABLE decision_logs (
+    decision_id TEXT PRIMARY KEY,
+    timestamp TEXT NOT NULL,
+    stock_code TEXT,
+    market TEXT,
+    exchange_code TEXT,
+    action TEXT,
+    confidence INTEGER,
+    rationale TEXT,
+    context_snapshot TEXT,         -- JSON: full context at decision time
+    input_data TEXT,              -- JSON: market data used
+    outcome_pnl REAL,
+    outcome_accuracy REAL,
+    reviewed INTEGER DEFAULT 0,
+    review_notes TEXT
+);
+-- Indices: idx_decision_logs_timestamp, idx_decision_logs_reviewed, idx_decision_logs_confidence
+```

-Auto-migration: Adds `market`, `exchange_code`, and `selection_context` columns if missing for backward compatibility.
+### playbooks
+```sql
+CREATE TABLE playbooks (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    date TEXT NOT NULL,
+    market TEXT NOT NULL,
+    status TEXT DEFAULT 'generated',
+    playbook_json TEXT NOT NULL,   -- Full playbook with scenarios
+    generated_at TEXT NOT NULL,
+    token_count INTEGER,
+    scenario_count INTEGER,
+    match_count INTEGER DEFAULT 0
+);
+-- Indices: idx_playbooks_date, idx_playbooks_market
+```
+
+### context_metadata
+```sql
+CREATE TABLE context_metadata (
+    layer TEXT PRIMARY KEY,
+    description TEXT,
+    retention_days INTEGER,
+    aggregation_source TEXT
+);
+```

 ## Configuration

@@ -284,29 +527,81 @@ KIS_APP_SECRET=your_app_secret
 KIS_ACCOUNT_NO=XXXXXXXX-XX
 GEMINI_API_KEY=your_gemini_key

-# Optional
+# Optional — Trading Mode
 MODE=paper                    # paper | live
-DB_PATH=data/trades.db
-CONFIDENCE_THRESHOLD=80
-MAX_LOSS_PCT=3.0
-MAX_ORDER_PCT=30.0
-ENABLED_MARKETS=KR,US_NASDAQ  # Comma-separated market codes
-
-# Trading Mode (API efficiency)
 TRADE_MODE=daily              # daily | realtime
 DAILY_SESSIONS=4              # Sessions per day (daily mode only)
 SESSION_INTERVAL_HOURS=6      # Hours between sessions (daily mode only)

-# Telegram Notifications (optional)
+# Optional — Database
+DB_PATH=data/trades.db
+
+# Optional — Risk
+CONFIDENCE_THRESHOLD=80
+MAX_LOSS_PCT=3.0
+MAX_ORDER_PCT=30.0
+
+# Optional — Markets
+ENABLED_MARKETS=KR,US         # Comma-separated market codes
+RATE_LIMIT_RPS=2.0            # KIS API requests per second
+
+# Optional — Pre-Market Planner (v2)
+PRE_MARKET_MINUTES=30         # Minutes before market open to generate playbook
+MAX_SCENARIOS_PER_STOCK=5     # Max scenarios per stock in playbook
+PLANNER_TIMEOUT_SECONDS=60    # Timeout for playbook generation
+DEFENSIVE_PLAYBOOK_ON_FAILURE=true  # Fallback on AI failure
+RESCAN_INTERVAL_SECONDS=300   # Scenario rescan interval during trading
+
+# Optional — Smart Scanner (realtime mode only)
+RSI_OVERSOLD_THRESHOLD=30     # 0-50, oversold threshold
+RSI_MOMENTUM_THRESHOLD=70     # 50-100, momentum threshold
+VOL_MULTIPLIER=2.0            # Minimum volume ratio (2.0 = 200%)
+SCANNER_TOP_N=3               # Max qualified candidates per scan
+
+# Optional — Dashboard
+DASHBOARD_ENABLED=false       # Enable FastAPI dashboard
+DASHBOARD_HOST=127.0.0.1      # Dashboard bind address
+DASHBOARD_PORT=8080           # Dashboard port (1-65535)
+
+# Optional — Telegram
 TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
 TELEGRAM_CHAT_ID=123456789
 TELEGRAM_ENABLED=true
+TELEGRAM_COMMANDS_ENABLED=true   # Enable bidirectional commands
+TELEGRAM_POLLING_INTERVAL=1.0    # Command polling interval (seconds)

-# Smart Scanner (optional, realtime mode only)
-RSI_OVERSOLD_THRESHOLD=30    # 0-50, oversold threshold
-RSI_MOMENTUM_THRESHOLD=70    # 50-100, momentum threshold
-VOL_MULTIPLIER=2.0           # Minimum volume ratio (2.0 = 200%)
-SCANNER_TOP_N=3              # Max qualified candidates per scan
+# Optional — Backup
+BACKUP_ENABLED=false
+BACKUP_DIR=data/backups
+S3_ENDPOINT_URL=...
+S3_ACCESS_KEY=...
+S3_SECRET_KEY=...
+S3_BUCKET_NAME=...
+S3_REGION=...
+
+# Optional — External Data
+NEWS_API_KEY=...
+NEWS_API_PROVIDER=...
+MARKET_DATA_API_KEY=...
+
+# Position Sizing (optional)
+POSITION_SIZING_ENABLED=true
+POSITION_BASE_ALLOCATION_PCT=5.0
+POSITION_MIN_ALLOCATION_PCT=1.0
+POSITION_MAX_ALLOCATION_PCT=10.0
+POSITION_VOLATILITY_TARGET_SCORE=50.0
+
+# Legacy/compat scanner thresholds (kept for backward compatibility)
+RSI_OVERSOLD_THRESHOLD=30
+RSI_MOMENTUM_THRESHOLD=70
+VOL_MULTIPLIER=2.0
+
+# Overseas Ranking API (optional override; account-dependent)
+OVERSEAS_RANKING_ENABLED=true
+OVERSEAS_RANKING_FLUCT_TR_ID=HHDFS76200100
+OVERSEAS_RANKING_VOLUME_TR_ID=HHDFS76200200
+OVERSEAS_RANKING_FLUCT_PATH=/uapi/overseas-price/v1/quotations/inquire-updown-rank
+OVERSEAS_RANKING_VOLUME_PATH=/uapi/overseas-price/v1/quotations/inquire-volume-rank
 ```

 Tests use in-memory SQLite (`DB_PATH=":memory:"`) and dummy credentials via `tests/conftest.py`.
@@ -340,4 +635,9 @@ Tests use in-memory SQLite (`DB_PATH=":memory:"`) and dummy credentials via `tes
 - Invalid token → log error, trading unaffected
 - Rate limit exceeded → queued via rate limiter

-**Guarantee**: Notification failures never interrupt trading operations.
+### Playbook Generation Failure
+- Timeout → fall back to defensive playbook (`DEFENSIVE_PLAYBOOK_ON_FAILURE`)
+- API error → use previous day's playbook if available
+- No playbook → skip pre-market phase, fall back to direct AI calls
+
+**Guarantee**: Notification and dashboard failures never interrupt trading operations.
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -119,7 +119,7 @@ No decorator needed for async tests.
 # Install all dependencies (production + dev)
 pip install -e ".[dev]"

-# Run full test suite with coverage
+# Run full test suite with coverage (551 tests across 25 files)
 pytest -v --cov=src --cov-report=term-missing

 # Run a single test file
@@ -137,11 +137,61 @@ mypy src/ --strict
 # Run the trading agent
 python -m src.main --mode=paper

+# Run with dashboard enabled
+python -m src.main --mode=paper --dashboard
+
 # Docker
 docker compose up -d ouroboros          # Run agent
 docker compose --profile test up test   # Run tests in container
 ```

+## Dashboard
+
+The FastAPI dashboard provides read-only monitoring of the trading system.
+
+### Starting the Dashboard
+
+```bash
+# Via CLI flag
+python -m src.main --mode=paper --dashboard
+
+# Via environment variable
+DASHBOARD_ENABLED=true python -m src.main --mode=paper
+```
+
+Dashboard runs as a daemon thread on `DASHBOARD_HOST:DASHBOARD_PORT` (default: `127.0.0.1:8080`).
+
+### API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /` | HTML dashboard UI |
+| `GET /api/status` | Daily trading status by market |
+| `GET /api/playbook/{date}` | Playbook for specific date (query: `market`) |
+| `GET /api/scorecard/{date}` | Daily scorecard from L6_DAILY context |
+| `GET /api/performance` | Performance metrics by market and combined |
+| `GET /api/context/{layer}` | Context data by layer L1-L7 (query: `timeframe`) |
+| `GET /api/decisions` | Decision log entries (query: `limit`, `market`) |
+| `GET /api/scenarios/active` | Today's matched scenarios |
+
+## Telegram Commands
+
+When `TELEGRAM_COMMANDS_ENABLED=true` (default), the bot accepts these interactive commands:
+
+| Command | Description |
+|---------|-------------|
+| `/help` | List available commands |
+| `/status` | Show trading status (mode, markets, P&L) |
+| `/positions` | Display account summary (balance, cash, P&L) |
+| `/report` | Daily summary metrics (trades, P&L, win rate) |
+| `/scenarios` | Show today's playbook scenarios |
+| `/review` | Display recent scorecards (L6_DAILY layer) |
+| `/dashboard` | Show dashboard URL if enabled |
+| `/stop` | Pause trading |
+| `/resume` | Resume trading |
+
+Commands are only processed from the authorized `TELEGRAM_CHAT_ID`.
+
 ## Environment Setup

 ```bash
--- a/docs/requirements-log.md
+++ b/docs/requirements-log.md
@@ -86,3 +86,183 @@
  - Plan Consistency (필수), Safety & Constraints, Quality, Workflow 4개 카테고리

 **이슈/PR:** #114
+
+---
+
+## 2026-02-16
+
+### 문서 v2 동기화 (전체 문서 현행화)
+
+**배경:**
+- v2 기능 구현 완료 후 문서가 실제 코드 상태와 크게 괴리
+- 문서에는 54 tests / 4 files로 기록되었으나 실제로는 551 tests / 25 files
+- v2 핵심 기능(Playbook, Scenario Engine, Dashboard, Telegram Commands, Daily Review, Context System, Backup) 문서화 누락
+
+**요구사항:**
+1. `docs/testing.md` — 551 tests / 25 files 반영, 전체 테스트 파일 설명
+2. `docs/architecture.md` — v2 컴포넌트(Strategy, Context, Dashboard, Decision Logger 등) 추가, Playbook Mode 데이터 플로우, DB 스키마 5개 테이블, v2 환경변수
+3. `docs/commands.md` — Dashboard 실행 명령어, Telegram 명령어 9종 레퍼런스
+4. `CLAUDE.md` — Project Structure 트리 확장, 테스트 수 업데이트, `--dashboard` 플래그
+5. `docs/skills.md` — DB 파일명 `trades.db`로 통일, Dashboard 명령어 추가
+6. 기존에 유효한 트러블슈팅, 코드 예제 등은 유지
+
+**구현 결과:**
+- 6개 문서 파일 업데이트
+- 이전 시도(2개 커밋)는 기존 내용을 과도하게 삭제하여 폐기, main 기준으로 재작업
+
+**이슈/PR:** #131, PR #134
+
+### 해외 스캐너 개선: 랭킹 연동 + 변동성 우선 선별
+
+**배경:**
+- `run_overnight` 실운영에서 미국장 동안 거래가 0건 지속
+- 원인: 해외 시장에서도 국내 랭킹/일봉 API 경로를 사용하던 구조적 불일치
+
+**요구사항:**
+1. 해외 시장도 랭킹 API 기반 유니버스 탐색 지원
+2. 단순 상승률/거래대금 상위가 아니라, **변동성이 큰 종목**을 우선 선별
+3. 고정 티커 fallback 금지
+
+**구현 결과:**
+- `src/broker/overseas.py`
+  - `fetch_overseas_rankings()` 추가 (fluctuation / volume)
+  - 해외 랭킹 API 경로/TR_ID를 설정값으로 오버라이드 가능하게 구현
+- `src/analysis/smart_scanner.py`
+  - market-aware 스캔(국내/해외 분리)
+  - 해외: 랭킹 API 유니버스 + 변동성 우선 점수(일변동률 vs 장중 고저폭)
+  - 거래대금/거래량 랭킹은 유동성 보정 점수로 활용
+  - 랭킹 실패 시에는 동적 유니버스(active/recent/holdings)만 사용
+- `src/config.py`
+  - `OVERSEAS_RANKING_*` 설정 추가
+
+**효과:**
+- 해외 시장에서 스캐너 후보 0개로 정지되는 상황 완화
+- 종목 선정 기준이 단순 상승률 중심에서 변동성 중심으로 개선
+- 고정 티커 없이도 시장 주도 변동 종목 탐지 가능
+
+### 국내 스캐너/주문수량 정렬: 변동성 우선 + 리스크 타기팅
+
+**배경:**
+- 해외만 변동성 우선으로 동작하고, 국내는 RSI/거래량 필터 중심으로 동작해 시장 간 전략 일관성이 낮았음
+- 매수 수량이 고정 1주라서 변동성 구간별 익스포저 관리가 어려웠음
+
+**요구사항:**
+1. 국내 스캐너도 변동성 우선 선별로 해외와 통일
+2. 고변동 종목일수록 포지션 크기를 줄이는 수량 산식 적용
+
+**구현 결과:**
+- `src/analysis/smart_scanner.py`
+  - 국내: `fluctuation ranking + volume ranking bonus` 기반 점수화로 전환
+  - 점수는 `max(abs(change_rate), intraday_range_pct)` 중심으로 계산
+  - 국내 랭킹 응답 스키마 키(`price`, `change_rate`, `volume`) 파싱 보강
+- `src/main.py`
+  - `_determine_order_quantity()` 추가
+  - BUY 시 변동성 점수 기반 동적 수량 산정 적용
+  - `trading_cycle`, `run_daily_session` 경로 모두 동일 수량 로직 사용
+- `src/config.py`
+  - `POSITION_SIZING_*` 설정 추가
+
+**효과:**
+- 국내/해외 스캐너 기준이 변동성 중심으로 일관화
+- 고변동 구간에서 자동 익스포저 축소, 저변동 구간에서 과소진입 완화
+
+## 2026-02-18
+
+### KIS 해외 랭킹 API 404 에러 수정
+
+**배경:**
+- KIS 해외주식 랭킹 API(`fetch_overseas_rankings`)가 모든 거래소에서 HTTP 404를 반환
+- Smart Scanner가 해외 시장 후보 종목을 찾지 못해 거래가 전혀 실행되지 않음
+
+**근본 원인:**
+- TR_ID, API 경로, 거래소 코드가 모두 KIS 공식 문서와 불일치
+
+**구현 결과:**
+- `src/config.py`: TR_ID/Path 기본값을 KIS 공식 스펙으로 수정
+- `src/broker/overseas.py`: 랭킹 API 전용 거래소 코드 매핑 추가 (NASD→NAS, NYSE→NYS, AMEX→AMS), 올바른 API 파라미터 사용
+- `tests/test_overseas_broker.py`: 19개 단위 테스트 추가
+
+**효과:**
+- 해외 시장 랭킹 스캔이 정상 동작하여 Smart Scanner가 후보 종목 탐지 가능
+
+### Gemini prompt_override 미적용 버그 수정
+
+**배경:**
+- `run_overnight` 실행 시 모든 시장에서 Playbook 생성 실패 (`JSONDecodeError`)
+- defensive playbook으로 폴백되어 모든 종목이 HOLD 처리
+
+**근본 원인:**
+- `pre_market_planner.py`가 `market_data["prompt_override"]`에 Playbook 전용 프롬프트를 넣어 `gemini.decide()` 호출
+- `gemini_client.py`의 `decide()` 메서드가 `prompt_override` 키를 전혀 확인하지 않고 항상 일반 트레이드 결정 프롬프트 생성
+- Gemini가 Playbook JSON 대신 일반 트레이드 결정을 반환하여 파싱 실패
+
+**구현 결과:**
+- `src/brain/gemini_client.py`: `decide()` 메서드에서 `prompt_override` 우선 사용 로직 추가
+- `tests/test_brain.py`: 3개 테스트 추가 (override 전달, optimization 우회, 미지정 시 기존 동작 유지)
+
+**이슈/PR:** #143
+
+### 미국장 거래 미실행 근본 원인 분석 및 수정 (자율 실행 세션)
+
+**배경:**
+- 사용자 요청: "미국장 열면 프로그램 돌려서 거래 한 번도 못 한 거 꼭 원인 찾아서 해결해줘"
+- 프로그램을 미국장 개장(9:30 AM EST) 전부터 실행하여 실시간 로그를 분석
+
+**발견된 근본 원인 #1: Defensive Playbook — BUY 조건 없음**
+
+- Gemini free tier (20 RPD) 소진 → `generate_playbook()` 실패 → `_defensive_playbook()` 폴백
+- Defensive playbook은 `price_change_pct_below: -3.0 → SELL` 조건만 존재, BUY 조건 없음
+- ScenarioEngine이 항상 HOLD 반환 → 거래 0건
+
+**수정 #1 (PR #146, Issue #145):**
+- `src/strategy/pre_market_planner.py`: `_smart_fallback_playbook()` 메서드 추가
+  - 스캐너 signal 기반 BUY 조건 생성: `momentum → volume_ratio_above`, `oversold → rsi_below`
+  - 기존 defensive stop-loss SELL 조건 유지
+- Gemini 실패 시 defensive → smart fallback으로 전환
+- 테스트 10개 추가
+
+**발견된 근본 원인 #2: 가격 API 거래소 코드 불일치 + VTS 잔고 API 오류**
+
+실제 로그:
+```
+Scenario matched for MRNX: BUY (confidence=80)  ✓
+Decision for EWUS (NYSE American): BUY (confidence=80)  ✓
+Skip BUY APLZ (NYSE American): no affordable quantity (cash=0.00, price=0.00)  ✗
+```
+
+- `get_overseas_price()`: `NASD`/`NYSE`/`AMEX` 전송 → API가 `NAS`/`NYS`/`AMS` 기대 → 빈 응답 → `price=0`
+- `VTTS3012R` 잔고 API: "ERROR : INPUT INVALID_CHECK_ACNO" → `total_cash=0`
+- 결과: `_determine_order_quantity()` 가 0 반환 → 주문 건너뜀
+
+**수정 #2 (PR #148, Issue #147):**
+- `src/broker/overseas.py`: `_PRICE_EXCHANGE_MAP = _RANKING_EXCHANGE_MAP` 추가, 가격 API에 매핑 적용
+- `src/config.py`: `PAPER_OVERSEAS_CASH: float = Field(default=50000.0)` — paper 모드 시뮬레이션 잔고
+- `src/main.py`: 잔고 0일 때 PAPER_OVERSEAS_CASH 폴백, 가격 0일 때 candidate.price 폴백
+- 테스트 8개 추가
+
+**효과:**
+- BUY 결정 → 실제 주문 전송까지의 파이프라인이 완전히 동작
+- Paper 모드에서 KIS VTS 해외 잔고 API 오류에 관계없이 시뮬레이션 거래 가능
+
+**이슈/PR:** #145, #146, #147, #148
+
+### 해외주식 시장가 주문 거부 수정 (Fix #3, 연속 발견)
+
+**배경:**
+- Fix #147 적용 후 주문 전송 시작 → KIS VTS가 거부: "지정가만 가능한 상품입니다"
+
+**근본 원인:**
+- `trading_cycle()`, `run_daily_session()` 양쪽에서 `send_overseas_order(price=0.0)` 하드코딩
+- `price=0` → `ORD_DVSN="01"` (시장가) 전송 → KIS VTS 거부
+- Fix #147에서 이미 `current_price`를 올바르게 계산했으나 주문 시 미사용
+
+**구현 결과:**
+- `src/main.py`: 두 곳에서 `price=0.0` → `price=current_price`/`price=stock_data["current_price"]`
+- `tests/test_main.py`: 회귀 테스트 `test_overseas_buy_order_uses_limit_price` 추가
+
+**최종 확인 로그:**
+```
+Order result: 모의투자 매수주문이 완료 되었습니다.  ✓
+```
+
+**이슈/PR:** #149, #150
--- a/docs/skills.md
+++ b/docs/skills.md
@@ -34,6 +34,12 @@ python -m src.main --mode=paper
 ```
 Runs the agent in paper-trading mode (no real orders).

+### Start Trading Agent with Dashboard
+```bash
+python -m src.main --mode=paper --dashboard
+```
+Runs the agent with FastAPI dashboard on `127.0.0.1:8080` (configurable via `DASHBOARD_HOST`/`DASHBOARD_PORT`).
+
 ### Start Trading Agent (Production)
 ```bash
 docker compose up -d ouroboros
@@ -59,7 +65,7 @@ Analyze the last 30 days of trade logs and generate performance metrics.
 python -m src.evolution.optimizer --evolve
 ```
 Triggers the evolution engine to:
-1. Analyze `trade_logs.db` for failing patterns
+1. Analyze `trades.db` for failing patterns
 2. Ask Gemini to generate a new strategy
 3. Run tests on the new strategy
 4. Create a PR if tests pass
@@ -91,12 +97,12 @@ curl http://localhost:8080/health

 ### View Trade Logs
 ```bash
-sqlite3 data/trade_logs.db "SELECT * FROM trades ORDER BY timestamp DESC LIMIT 20;"
+sqlite3 data/trades.db "SELECT * FROM trades ORDER BY timestamp DESC LIMIT 20;"
 ```

 ### Export Trade History
 ```bash
-sqlite3 -header -csv data/trade_logs.db "SELECT * FROM trades;" > trades_export.csv
+sqlite3 -header -csv data/trades.db "SELECT * FROM trades;" > trades_export.csv
 ```

 ## Safety Checklist (Pre-Deploy)
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -2,51 +2,29 @@

 ## Test Structure

-**54 tests** across four files. `asyncio_mode = "auto"` in pyproject.toml — async tests need no special decorator.
+**551 tests** across **25 files**. `asyncio_mode = "auto"` in pyproject.toml — async tests need no special decorator.

 The `settings` fixture in `conftest.py` provides safe defaults with test credentials and in-memory DB.

 ### Test Files

-#### `tests/test_risk.py` (11 tests)
- Circuit breaker boundaries
- Fat-finger edge cases
+#### Core Components
+
+##### `tests/test_risk.py` (14 tests)
+- Circuit breaker boundaries and exact threshold triggers
+- Fat-finger edge cases and percentage validation
 - P&L calculation edge cases
 - Order validation logic

-**Example:**
-```python
-def test_circuit_breaker_exact_threshold(risk_manager):
-    """Circuit breaker should trip at exactly -3.0%."""
-    with pytest.raises(CircuitBreakerTripped):
-        risk_manager.validate_order(
-            current_pnl_pct=-3.0,
-            order_amount=1000,
-            total_cash=10000
-        )
-```
-
-#### `tests/test_broker.py` (6 tests)
+##### `tests/test_broker.py` (11 tests)
 - OAuth token lifecycle
 - Rate limiting enforcement
 - Hash key generation
 - Network error handling
 - SSL context configuration

-**Example:**
-```python
-async def test_rate_limiter(broker):
-    """Rate limiter should delay requests to stay under 10 RPS."""
-    start = time.monotonic()
-    for _ in range(15):  # 15 requests
-        await broker._rate_limiter.acquire()
-    elapsed = time.monotonic() - start
-    assert elapsed >= 1.0  # Should take at least 1 second
-```
-
-#### `tests/test_brain.py` (18 tests)
- Valid JSON parsing
- Markdown-wrapped JSON handling
+##### `tests/test_brain.py` (24 tests)
+- Valid JSON parsing and markdown-wrapped JSON handling
 - Malformed JSON fallback
 - Missing fields handling
 - Invalid action validation
@@ -54,33 +32,143 @@ async def test_rate_limiter(broker):
 - Empty response handling
 - Prompt construction for different markets

-**Example:**
-```python
-async def test_confidence_below_threshold_forces_hold(brain):
-    """Decisions below confidence threshold should force HOLD."""
-    decision = brain.parse_response('{"action":"BUY","confidence":70,"rationale":"test"}')
-    assert decision.action == "HOLD"
-    assert decision.confidence == 70
-```
-
-#### `tests/test_market_schedule.py` (19 tests)
+##### `tests/test_market_schedule.py` (24 tests)
 - Market open/close logic
 - Timezone handling (UTC, Asia/Seoul, America/New_York, etc.)
 - DST (Daylight Saving Time) transitions
- Weekend handling
- Lunch break logic
+- Weekend handling and lunch break logic
 - Multiple market filtering
 - Next market open calculation

-**Example:**
-```python
-def test_is_market_open_during_trading_hours():
-    """Market should be open during regular trading hours."""
-    # KRX: 9:00-15:30 KST, no lunch break
-    market = MARKETS["KR"]
-    trading_time = datetime(2026, 2, 3, 10, 0, tzinfo=ZoneInfo("Asia/Seoul"))  # Monday 10:00
-    assert is_market_open(market, trading_time) is True
-```
+##### `tests/test_db.py` (3 tests)
+- Database initialization and table creation
+- Trade logging with all fields (market, exchange_code, decision_id)
+- Query and retrieval operations
+
+##### `tests/test_main.py` (37 tests)
+- Trading loop orchestration
+- Market iteration and stock processing
+- Dashboard integration (`--dashboard` flag)
+- Telegram command handler wiring
+- Error handling and graceful shutdown
+
+#### Strategy & Playbook (v2)
+
+##### `tests/test_pre_market_planner.py` (37 tests)
+- Pre-market playbook generation
+- Gemini API integration for scenario creation
+- Timeout handling and defensive playbook fallback
+- Multi-market playbook generation
+
+##### `tests/test_scenario_engine.py` (44 tests)
+- Scenario matching against live market data
+- Confidence scoring and threshold filtering
+- Multiple scenario type handling
+- Edge cases (no match, partial match, expired scenarios)
+
+##### `tests/test_playbook_store.py` (23 tests)
+- Playbook persistence to SQLite
+- Date-based retrieval and market filtering
+- Playbook status management (generated, active, expired)
+- JSON serialization/deserialization
+
+##### `tests/test_strategy_models.py` (33 tests)
+- Pydantic model validation for scenarios, playbooks, decisions
+- Field constraints and default values
+- Serialization round-trips
+
+#### Analysis & Scanning
+
+##### `tests/test_volatility.py` (24 tests)
+- ATR and RSI calculation accuracy
+- Volume surge ratio computation
+- Momentum scoring
+- Breakout/breakdown pattern detection
+- Market scanner watchlist management
+
+##### `tests/test_smart_scanner.py` (13 tests)
+- Python-first filtering pipeline
+- RSI and volume ratio filter logic
+- Candidate scoring and ranking
+- Fallback to static watchlist
+
+#### Context & Memory
+
+##### `tests/test_context.py` (18 tests)
+- L1-L7 layer storage and retrieval
+- Context key-value CRUD operations
+- Timeframe-based queries
+- Layer metadata management
+
+##### `tests/test_context_scheduler.py` (5 tests)
+- Periodic context aggregation scheduling
+- Layer summarization triggers
+
+#### Evolution & Review
+
+##### `tests/test_evolution.py` (24 tests)
+- Strategy optimization loop
+- High-confidence losing trade analysis
+- Generated strategy validation
+
+##### `tests/test_daily_review.py` (10 tests)
+- End-of-day review generation
+- Trade performance summarization
+- Context layer (L6_DAILY) integration
+
+##### `tests/test_scorecard.py` (3 tests)
+- Daily scorecard metrics calculation
+- Win rate, P&L, confidence tracking
+
+#### Notifications & Commands
+
+##### `tests/test_telegram.py` (25 tests)
+- Message sending and formatting
+- Rate limiting (leaky bucket)
+- Error handling (network timeout, invalid token)
+- Auto-disable on missing credentials
+- Notification types (trade, circuit breaker, fat-finger, market events)
+
+##### `tests/test_telegram_commands.py` (31 tests)
+- 9 command handlers (/help, /status, /positions, /report, /scenarios, /review, /dashboard, /stop, /resume)
+- Long polling and command dispatch
+- Authorization filtering by chat_id
+- Command response formatting
+
+#### Dashboard
+
+##### `tests/test_dashboard.py` (14 tests)
+- FastAPI endpoint responses (8 API routes)
+- Status, playbook, scorecard, performance, context, decisions, scenarios
+- Query parameter handling (market, date, limit)
+
+#### Performance & Quality
+
+##### `tests/test_token_efficiency.py` (34 tests)
+- Gemini token usage optimization
+- Prompt size reduction verification
+- Cache effectiveness
+
+##### `tests/test_latency_control.py` (30 tests)
+- API call latency measurement
+- Rate limiter timing accuracy
+- Async operation overhead
+
+##### `tests/test_decision_logger.py` (9 tests)
+- Decision audit trail completeness
+- Context snapshot capture
+- Outcome tracking (P&L, accuracy)
+
+##### `tests/test_data_integration.py` (38 tests)
+- External data source integration
+- News API, market data, economic calendar
+- Error handling for API failures
+
+##### `tests/test_backup.py` (23 tests)
+- Backup scheduler and execution
+- Cloud storage (S3) upload
+- Health monitoring
+- Data export functionality

 ## Coverage Requirements

@@ -91,20 +179,6 @@ Check coverage:
 pytest -v --cov=src --cov-report=term-missing
 ```

-Expected output:
-```
-Name                          Stmts   Miss  Cover   Missing
-----------------------------------------------------------
-src/brain/gemini_client.py       85      5    94%   165-169
-src/broker/kis_api.py           120     12    90%   ...
-src/core/risk_manager.py         35      2    94%   ...
-src/db.py                        25      1    96%   ...
-src/main.py                     150     80    47%   (excluded from CI)
-src/markets/schedule.py          95      3    97%   ...
-----------------------------------------------------------
-TOTAL                           510     103   80%
-```
-
 **Note:** `main.py` has lower coverage as it contains the main loop which is tested via integration/manual testing.

 ## Test Configuration
--- a/scripts/morning_report.sh
+++ b/scripts/morning_report.sh
@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Morning summary for overnight run logs.
+
+set -euo pipefail
+
+LOG_DIR="${LOG_DIR:-data/overnight}"
+
+if [ ! -d "$LOG_DIR" ]; then
+    echo "로그 디렉터리가 없습니다: $LOG_DIR"
+    exit 1
+fi
+
+latest_run="$(ls -1t "$LOG_DIR"/run_*.log 2>/dev/null | head -n 1 || true)"
+latest_watchdog="$(ls -1t "$LOG_DIR"/watchdog_*.log 2>/dev/null | head -n 1 || true)"
+
+if [ -z "$latest_run" ]; then
+    echo "run 로그가 없습니다: $LOG_DIR/run_*.log"
+    exit 1
+fi
+
+echo "Overnight report"
+echo "- run log: $latest_run"
+if [ -n "$latest_watchdog" ]; then
+    echo "- watchdog log: $latest_watchdog"
+fi
+
+start_line="$(head -n 1 "$latest_run" || true)"
+end_line="$(tail -n 1 "$latest_run" || true)"
+
+info_count="$(rg -c '"level": "INFO"' "$latest_run" || true)"
+warn_count="$(rg -c '"level": "WARNING"' "$latest_run" || true)"
+error_count="$(rg -c '"level": "ERROR"' "$latest_run" || true)"
+critical_count="$(rg -c '"level": "CRITICAL"' "$latest_run" || true)"
+traceback_count="$(rg -c 'Traceback' "$latest_run" || true)"
+
+echo "- start: ${start_line:-N/A}"
+echo "- end:   ${end_line:-N/A}"
+echo "- INFO: ${info_count:-0}"
+echo "- WARNING: ${warn_count:-0}"
+echo "- ERROR: ${error_count:-0}"
+echo "- CRITICAL: ${critical_count:-0}"
+echo "- Traceback: ${traceback_count:-0}"
+
+if [ -n "$latest_watchdog" ]; then
+    watchdog_errors="$(rg -c '\[ERROR\]' "$latest_watchdog" || true)"
+    echo "- watchdog ERROR: ${watchdog_errors:-0}"
+    echo ""
+    echo "최근 watchdog 로그:"
+    tail -n 5 "$latest_watchdog" || true
+fi
+
+echo ""
+echo "최근 앱 로그:"
+tail -n 20 "$latest_run" || true
--- a/scripts/run_overnight.sh
+++ b/scripts/run_overnight.sh
@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# Start The Ouroboros overnight with logs and watchdog.
+
+set -euo pipefail
+
+LOG_DIR="${LOG_DIR:-data/overnight}"
+CHECK_INTERVAL="${CHECK_INTERVAL:-30}"
+TMUX_AUTO="${TMUX_AUTO:-true}"
+TMUX_ATTACH="${TMUX_ATTACH:-true}"
+TMUX_SESSION_PREFIX="${TMUX_SESSION_PREFIX:-ouroboros_overnight}"
+
+if [ -z "${APP_CMD:-}" ]; then
+    if [ -x ".venv/bin/python" ]; then
+        PYTHON_BIN=".venv/bin/python"
+    elif command -v python3 >/dev/null 2>&1; then
+        PYTHON_BIN="python3"
+    elif command -v python >/dev/null 2>&1; then
+        PYTHON_BIN="python"
+    else
+        echo ".venv/bin/python 또는 python3/python 실행 파일을 찾을 수 없습니다."
+        exit 1
+    fi
+
+    dashboard_port="${DASHBOARD_PORT:-8080}"
+
+    APP_CMD="DASHBOARD_PORT=$dashboard_port $PYTHON_BIN -m src.main --mode=paper --dashboard"
+fi
+
+mkdir -p "$LOG_DIR"
+
+timestamp="$(date +"%Y%m%d_%H%M%S")"
+RUN_LOG="$LOG_DIR/run_${timestamp}.log"
+WATCHDOG_LOG="$LOG_DIR/watchdog_${timestamp}.log"
+PID_FILE="$LOG_DIR/app.pid"
+WATCHDOG_PID_FILE="$LOG_DIR/watchdog.pid"
+
+if [ -f "$PID_FILE" ]; then
+    old_pid="$(cat "$PID_FILE" || true)"
+    if [ -n "$old_pid" ] && kill -0 "$old_pid" 2>/dev/null; then
+        echo "앱이 이미 실행 중입니다. pid=$old_pid"
+        exit 1
+    fi
+fi
+
+echo "[$(date -u +"%Y-%m-%dT%H:%M:%SZ")] starting: $APP_CMD" | tee -a "$RUN_LOG"
+nohup bash -lc "$APP_CMD" >>"$RUN_LOG" 2>&1 &
+app_pid=$!
+echo "$app_pid" > "$PID_FILE"
+
+echo "[$(date -u +"%Y-%m-%dT%H:%M:%SZ")] app pid=$app_pid" | tee -a "$RUN_LOG"
+
+nohup env PID_FILE="$PID_FILE" LOG_FILE="$WATCHDOG_LOG" CHECK_INTERVAL="$CHECK_INTERVAL" \
+    bash scripts/watchdog.sh >/dev/null 2>&1 &
+watchdog_pid=$!
+echo "$watchdog_pid" > "$WATCHDOG_PID_FILE"
+
+cat <<EOF
+시작 완료
+- app pid: $app_pid
+- watchdog pid: $watchdog_pid
+- app log: $RUN_LOG
+- watchdog log: $WATCHDOG_LOG
+
+실시간 확인:
+tail -f "$RUN_LOG"
+tail -f "$WATCHDOG_LOG"
+EOF
+
+if [ "$TMUX_AUTO" = "true" ]; then
+    if ! command -v tmux >/dev/null 2>&1; then
+        echo "tmux를 찾지 못해 자동 세션 생성은 건너뜁니다."
+        exit 0
+    fi
+
+    session_name="${TMUX_SESSION_PREFIX}_${timestamp}"
+    window_name="overnight"
+    tmux new-session -d -s "$session_name" -n "$window_name" "tail -f '$RUN_LOG'"
+    tmux split-window -t "${session_name}:${window_name}" -v "tail -f '$WATCHDOG_LOG'"
+    tmux select-layout -t "${session_name}:${window_name}" even-vertical
+
+    echo "tmux session 생성: $session_name"
+    echo "수동 접속: tmux attach -t $session_name"
+
+    if [ -z "${TMUX:-}" ] && [ "$TMUX_ATTACH" = "true" ]; then
+        tmux attach -t "$session_name"
+    fi
+fi
--- a/scripts/stop_overnight.sh
+++ b/scripts/stop_overnight.sh
@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Stop The Ouroboros overnight app/watchdog/tmux session.
+
+set -euo pipefail
+
+LOG_DIR="${LOG_DIR:-data/overnight}"
+PID_FILE="$LOG_DIR/app.pid"
+WATCHDOG_PID_FILE="$LOG_DIR/watchdog.pid"
+TMUX_SESSION_PREFIX="${TMUX_SESSION_PREFIX:-ouroboros_overnight}"
+KILL_TIMEOUT="${KILL_TIMEOUT:-5}"
+
+stop_pid() {
+    local name="$1"
+    local pid="$2"
+
+    if [ -z "$pid" ]; then
+        echo "$name PID가 비어 있습니다."
+        return 1
+    fi
+
+    if ! kill -0 "$pid" 2>/dev/null; then
+        echo "$name 프로세스가 이미 종료됨 (pid=$pid)"
+        return 0
+    fi
+
+    kill "$pid" 2>/dev/null || true
+    for _ in $(seq 1 "$KILL_TIMEOUT"); do
+        if ! kill -0 "$pid" 2>/dev/null; then
+            echo "$name 종료됨 (pid=$pid)"
+            return 0
+        fi
+        sleep 1
+    done
+
+    kill -9 "$pid" 2>/dev/null || true
+    if ! kill -0 "$pid" 2>/dev/null; then
+        echo "$name 강제 종료됨 (pid=$pid)"
+        return 0
+    fi
+
+    echo "$name 종료 실패 (pid=$pid)"
+    return 1
+}
+
+status=0
+
+if [ -f "$WATCHDOG_PID_FILE" ]; then
+    watchdog_pid="$(cat "$WATCHDOG_PID_FILE" || true)"
+    stop_pid "watchdog" "$watchdog_pid" || status=1
+    rm -f "$WATCHDOG_PID_FILE"
+else
+    echo "watchdog pid 파일 없음: $WATCHDOG_PID_FILE"
+fi
+
+if [ -f "$PID_FILE" ]; then
+    app_pid="$(cat "$PID_FILE" || true)"
+    stop_pid "app" "$app_pid" || status=1
+    rm -f "$PID_FILE"
+else
+    echo "app pid 파일 없음: $PID_FILE"
+fi
+
+if command -v tmux >/dev/null 2>&1; then
+    sessions="$(tmux ls 2>/dev/null | awk -F: -v p="$TMUX_SESSION_PREFIX" '$1 ~ "^" p "_" {print $1}')"
+    if [ -n "$sessions" ]; then
+        while IFS= read -r s; do
+            [ -z "$s" ] && continue
+            tmux kill-session -t "$s" 2>/dev/null || true
+            echo "tmux 세션 종료: $s"
+        done <<< "$sessions"
+    else
+        echo "종료할 tmux 세션 없음 (prefix=${TMUX_SESSION_PREFIX}_)"
+    fi
+fi
+
+exit "$status"
--- a/scripts/watchdog.sh
+++ b/scripts/watchdog.sh
@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Simple watchdog for The Ouroboros process.
+
+set -euo pipefail
+
+PID_FILE="${PID_FILE:-data/overnight/app.pid}"
+LOG_FILE="${LOG_FILE:-data/overnight/watchdog.log}"
+CHECK_INTERVAL="${CHECK_INTERVAL:-30}"
+STATUS_EVERY="${STATUS_EVERY:-10}"
+
+mkdir -p "$(dirname "$LOG_FILE")"
+
+log() {
+    printf '%s %s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$1" | tee -a "$LOG_FILE"
+}
+
+if [ ! -f "$PID_FILE" ]; then
+    log "[ERROR] pid file not found: $PID_FILE"
+    exit 1
+fi
+
+PID="$(cat "$PID_FILE")"
+if [ -z "$PID" ]; then
+    log "[ERROR] pid file is empty: $PID_FILE"
+    exit 1
+fi
+
+log "[INFO] watchdog started (pid=$PID, interval=${CHECK_INTERVAL}s)"
+
+count=0
+while true; do
+    if kill -0 "$PID" 2>/dev/null; then
+        count=$((count + 1))
+        if [ $((count % STATUS_EVERY)) -eq 0 ]; then
+            log "[INFO] process alive (pid=$PID)"
+        fi
+    else
+        log "[ERROR] process stopped (pid=$PID)"
+        exit 1
+    fi
+    sleep "$CHECK_INTERVAL"
+done
--- a/src/analysis/smart_scanner.py
+++ b/src/analysis/smart_scanner.py
@@ -1,8 +1,4 @@
-"""Smart Volatility Scanner with RSI and volume filters.
-
-Fetches market rankings from KIS API and applies technical filters
-to identify high-probability trading candidates.
-"""
+"""Smart Volatility Scanner with volatility-first market ranking logic."""

 from __future__ import annotations

@@ -12,7 +8,9 @@ from typing import Any

 from src.analysis.volatility import VolatilityAnalyzer
 from src.broker.kis_api import KISBroker
+from src.broker.overseas import OverseasBroker
 from src.config import Settings
+from src.markets.schedule import MarketInfo

 logger = logging.getLogger(__name__)

@@ -32,19 +30,19 @@ class ScanCandidate:


 class SmartVolatilityScanner:
-    """Scans market rankings and applies RSI/volume filters.
+    """Scans market rankings and applies volatility-first filters.

    Flow:
-    1. Fetch volume rankings from KIS API
-    2. For each ranked stock, fetch daily prices
-    3. Calculate RSI and volume ratio
-    4. Apply filters: volume > VOL_MULTIPLIER AND (RSI < 30 OR RSI > 70)
-    5. Return top N qualified candidates
+    1. Fetch fluctuation rankings as primary universe
+    2. Fetch volume rankings for liquidity bonus
+    3. Score by volatility first, liquidity second
+    4. Return top N qualified candidates
    """

    def __init__(
        self,
        broker: KISBroker,
+        overseas_broker: OverseasBroker | None,
        volatility_analyzer: VolatilityAnalyzer,
        settings: Settings,
    ) -> None:
@@ -56,6 +54,7 @@ class SmartVolatilityScanner:
            settings: Application settings
        """
        self.broker = broker
+        self.overseas_broker = overseas_broker
        self.analyzer = volatility_analyzer
        self.settings = settings

@@ -67,107 +66,129 @@ class SmartVolatilityScanner:

    async def scan(
        self,
+        market: MarketInfo | None = None,
        fallback_stocks: list[str] | None = None,
    ) -> list[ScanCandidate]:
        """Execute smart scan and return qualified candidates.

        Args:
+            market: Target market info (domestic vs overseas behavior)
            fallback_stocks: Stock codes to use if ranking API fails

        Returns:
            List of ScanCandidate, sorted by score, up to top_n items
        """
-        # Step 1: Fetch rankings
+        if market and not market.is_domestic:
+            return await self._scan_overseas(market, fallback_stocks)
+
+        return await self._scan_domestic(fallback_stocks)
+
+    async def _scan_domestic(
+        self,
+        fallback_stocks: list[str] | None = None,
+    ) -> list[ScanCandidate]:
+        """Scan domestic market using volatility-first ranking + liquidity bonus."""
+        # 1) Primary universe from fluctuation ranking.
        try:
-            rankings = await self.broker.fetch_market_rankings(
-                ranking_type="volume",
-                limit=30,  # Fetch more than needed for filtering
+            fluct_rows = await self.broker.fetch_market_rankings(
+                ranking_type="fluctuation",
+                limit=50,
            )
-            logger.info("Fetched %d stocks from volume rankings", len(rankings))
        except ConnectionError as exc:
-            logger.warning("Ranking API failed, using fallback: %s", exc)
-            if fallback_stocks:
-                # Create minimal ranking data for fallback
-                rankings = [
-                    {
-                        "stock_code": code,
-                        "name": code,
-                        "price": 0,
-                        "volume": 0,
-                        "change_rate": 0,
-                        "volume_increase_rate": 0,
-                    }
-                    for code in fallback_stocks
-                ]
-            else:
-                return []
+            logger.warning("Domestic fluctuation ranking failed: %s", exc)
+            fluct_rows = []
+
+        # 2) Liquidity bonus from volume ranking.
+        try:
+            volume_rows = await self.broker.fetch_market_rankings(
+                ranking_type="volume",
+                limit=50,
+            )
+        except ConnectionError as exc:
+            logger.warning("Domestic volume ranking failed: %s", exc)
+            volume_rows = []
+
+        if not fluct_rows and fallback_stocks:
+            logger.info(
+                "Domestic ranking unavailable; using fallback symbols (%d)",
+                len(fallback_stocks),
+            )
+            fluct_rows = [
+                {
+                    "stock_code": code,
+                    "name": code,
+                    "price": 0.0,
+                    "volume": 0.0,
+                    "change_rate": 0.0,
+                    "volume_increase_rate": 0.0,
+                }
+                for code in fallback_stocks
+            ]
+
+        if not fluct_rows:
+            return []
+
+        volume_rank_bonus: dict[str, float] = {}
+        for idx, row in enumerate(volume_rows):
+            code = _extract_stock_code(row)
+            if not code:
+                continue
+            volume_rank_bonus[code] = max(0.0, 15.0 - idx * 0.3)

-        # Step 2: Analyze each stock
        candidates: list[ScanCandidate] = []
-
-        for stock in rankings:
-            stock_code = stock["stock_code"]
+        for stock in fluct_rows:
+            stock_code = _extract_stock_code(stock)
            if not stock_code:
                continue

            try:
-                # Fetch daily prices for RSI calculation
-                daily_prices = await self.broker.get_daily_prices(stock_code, days=20)
+                price = _extract_last_price(stock)
+                change_rate = _extract_change_rate_pct(stock)
+                volume = _extract_volume(stock)

-                if len(daily_prices) < 15:  # Need at least 14+1 for RSI
-                    logger.debug("Insufficient price history for %s", stock_code)
+                intraday_range_pct = 0.0
+                volume_ratio = _safe_float(stock.get("volume_increase_rate"), 0.0) / 100.0 + 1.0
+
+                # Use daily chart to refine range/volume when available.
+                daily_prices = await self.broker.get_daily_prices(stock_code, days=2)
+                if daily_prices:
+                    latest = daily_prices[-1]
+                    latest_close = _safe_float(latest.get("close"), default=price)
+                    if price <= 0:
+                        price = latest_close
+                    latest_high = _safe_float(latest.get("high"))
+                    latest_low = _safe_float(latest.get("low"))
+                    if latest_close > 0 and latest_high > 0 and latest_low > 0 and latest_high >= latest_low:
+                        intraday_range_pct = (latest_high - latest_low) / latest_close * 100.0
+                    if volume <= 0:
+                        volume = _safe_float(latest.get("volume"))
+                    if len(daily_prices) >= 2:
+                        prev_day_volume = _safe_float(daily_prices[-2].get("volume"))
+                        if prev_day_volume > 0:
+                            volume_ratio = max(volume_ratio, volume / prev_day_volume)
+
+                volatility_pct = max(abs(change_rate), intraday_range_pct)
+                if price <= 0 or volatility_pct < 0.8:
                    continue

-                # Calculate RSI
-                close_prices = [p["close"] for p in daily_prices]
-                rsi = self.analyzer.calculate_rsi(close_prices, period=14)
+                volatility_score = min(volatility_pct / 10.0, 1.0) * 85.0
+                liquidity_score = volume_rank_bonus.get(stock_code, 0.0)
+                score = min(100.0, volatility_score + liquidity_score)
+                signal = "momentum" if change_rate >= 0 else "oversold"
+                implied_rsi = max(0.0, min(100.0, 50.0 + (change_rate * 4.0)))

-                # Calculate volume ratio (today vs previous day avg)
-                if len(daily_prices) >= 2:
-                    prev_day_volume = daily_prices[-2]["volume"]
-                    current_volume = stock.get("volume", 0) or daily_prices[-1]["volume"]
-                    volume_ratio = (
-                        current_volume / prev_day_volume if prev_day_volume > 0 else 1.0
-                    )
-                else:
-                    volume_ratio = stock.get("volume_increase_rate", 0) / 100 + 1  # Fallback
-
-                # Apply filters
-                volume_qualified = volume_ratio >= self.vol_multiplier
-                rsi_oversold = rsi < self.rsi_oversold
-                rsi_momentum = rsi > self.rsi_momentum
-
-                if volume_qualified and (rsi_oversold or rsi_momentum):
-                    signal = "oversold" if rsi_oversold else "momentum"
-
-                    # Calculate composite score
-                    # Higher score for: extreme RSI + high volume
-                    rsi_extremity = abs(rsi - 50) / 50  # 0-1 scale
-                    volume_score = min(volume_ratio / 5, 1.0)  # Cap at 5x
-                    score = (rsi_extremity * 0.6 + volume_score * 0.4) * 100
-
-                    candidates.append(
-                        ScanCandidate(
-                            stock_code=stock_code,
-                            name=stock.get("name", stock_code),
-                            price=stock.get("price", daily_prices[-1]["close"]),
-                            volume=current_volume,
-                            volume_ratio=volume_ratio,
-                            rsi=rsi,
-                            signal=signal,
-                            score=score,
-                        )
-                    )
-
-                    logger.info(
-                        "Qualified: %s (%s) RSI=%.1f vol=%.1fx signal=%s score=%.1f",
-                        stock_code,
-                        stock.get("name", ""),
-                        rsi,
-                        volume_ratio,
-                        signal,
-                        score,
+                candidates.append(
+                    ScanCandidate(
+                        stock_code=stock_code,
+                        name=stock.get("name", stock_code),
+                        price=price,
+                        volume=volume,
+                        volume_ratio=max(1.0, volume_ratio, volatility_pct / 2.0),
+                        rsi=implied_rsi,
+                        signal=signal,
+                        score=score,
                    )
+                )

            except ConnectionError as exc:
                logger.warning("Failed to analyze %s: %s", stock_code, exc)
@@ -176,10 +197,171 @@ class SmartVolatilityScanner:
                logger.error("Unexpected error analyzing %s: %s", stock_code, exc)
                continue

-        # Sort by score and return top N
+        logger.info("Domestic ranking scan found %d candidates", len(candidates))
        candidates.sort(key=lambda c: c.score, reverse=True)
        return candidates[: self.top_n]

+    async def _scan_overseas(
+        self,
+        market: MarketInfo,
+        fallback_stocks: list[str] | None = None,
+    ) -> list[ScanCandidate]:
+        """Scan overseas symbols using ranking API first, then fallback universe."""
+        if self.overseas_broker is None:
+            logger.warning(
+                "Overseas scanner unavailable for %s: overseas broker not configured",
+                market.name,
+            )
+            return []
+
+        candidates = await self._scan_overseas_from_rankings(market)
+        if not candidates:
+            candidates = await self._scan_overseas_from_symbols(market, fallback_stocks)
+
+        candidates.sort(key=lambda c: c.score, reverse=True)
+        return candidates[: self.top_n]
+
+    async def _scan_overseas_from_rankings(
+        self,
+        market: MarketInfo,
+    ) -> list[ScanCandidate]:
+        """Build overseas candidates from ranking APIs using volatility-first scoring."""
+        assert self.overseas_broker is not None
+        try:
+            fluct_rows = await self.overseas_broker.fetch_overseas_rankings(
+                exchange_code=market.exchange_code,
+                ranking_type="fluctuation",
+                limit=50,
+            )
+        except Exception as exc:
+            logger.warning(
+                "Overseas fluctuation ranking failed for %s: %s", market.code, exc
+            )
+            fluct_rows = []
+
+        if not fluct_rows:
+            return []
+
+        volume_rank_bonus: dict[str, float] = {}
+        try:
+            volume_rows = await self.overseas_broker.fetch_overseas_rankings(
+                exchange_code=market.exchange_code,
+                ranking_type="volume",
+                limit=50,
+            )
+        except Exception as exc:
+            logger.warning(
+                "Overseas volume ranking failed for %s: %s", market.code, exc
+            )
+            volume_rows = []
+
+        for idx, row in enumerate(volume_rows):
+            code = _extract_stock_code(row)
+            if not code:
+                continue
+            # Top-ranked by traded value/volume gets higher liquidity bonus.
+            volume_rank_bonus[code] = max(0.0, 15.0 - idx * 0.3)
+
+        candidates: list[ScanCandidate] = []
+        for row in fluct_rows:
+            stock_code = _extract_stock_code(row)
+            if not stock_code:
+                continue
+
+            price = _extract_last_price(row)
+            change_rate = _extract_change_rate_pct(row)
+            volume = _extract_volume(row)
+            intraday_range_pct = _extract_intraday_range_pct(row, price)
+            volatility_pct = max(abs(change_rate), intraday_range_pct)
+
+            # Volatility-first filter (not simple gainers/value ranking).
+            if price <= 0 or volatility_pct < 0.8:
+                continue
+
+            volatility_score = min(volatility_pct / 10.0, 1.0) * 85.0
+            liquidity_score = volume_rank_bonus.get(stock_code, 0.0)
+            score = min(100.0, volatility_score + liquidity_score)
+            signal = "momentum" if change_rate >= 0 else "oversold"
+            implied_rsi = max(0.0, min(100.0, 50.0 + (change_rate * 4.0)))
+            candidates.append(
+                ScanCandidate(
+                    stock_code=stock_code,
+                    name=str(row.get("name") or row.get("ovrs_item_name") or stock_code),
+                    price=price,
+                    volume=volume,
+                    volume_ratio=max(1.0, volatility_pct / 2.0),
+                    rsi=implied_rsi,
+                    signal=signal,
+                    score=score,
+                )
+            )
+
+        if candidates:
+            logger.info(
+                "Overseas ranking scan found %d candidates for %s",
+                len(candidates),
+                market.name,
+            )
+        return candidates
+
+    async def _scan_overseas_from_symbols(
+        self,
+        market: MarketInfo,
+        symbols: list[str] | None,
+    ) -> list[ScanCandidate]:
+        """Fallback overseas scan from dynamic symbol universe."""
+        assert self.overseas_broker is not None
+        if not symbols:
+            logger.info("Overseas scanner: no symbol universe for %s", market.name)
+            return []
+
+        logger.info(
+            "Overseas scanner: scanning %d fallback symbols for %s",
+            len(symbols),
+            market.name,
+        )
+        candidates: list[ScanCandidate] = []
+        for stock_code in symbols:
+            try:
+                price_data = await self.overseas_broker.get_overseas_price(
+                    market.exchange_code, stock_code
+                )
+                output = price_data.get("output", {})
+                price = _extract_last_price(output)
+                change_rate = _extract_change_rate_pct(output)
+                volume = _extract_volume(output)
+                intraday_range_pct = _extract_intraday_range_pct(output, price)
+                volatility_pct = max(abs(change_rate), intraday_range_pct)
+
+                if price <= 0 or volatility_pct < 0.8:
+                    continue
+
+                score = min(volatility_pct / 10.0, 1.0) * 100.0
+                signal = "momentum" if change_rate >= 0 else "oversold"
+                implied_rsi = max(0.0, min(100.0, 50.0 + (change_rate * 4.0)))
+                candidates.append(
+                    ScanCandidate(
+                        stock_code=stock_code,
+                        name=stock_code,
+                        price=price,
+                        volume=volume,
+                        volume_ratio=max(1.0, volatility_pct / 2.0),
+                        rsi=implied_rsi,
+                        signal=signal,
+                        score=score,
+                    )
+                )
+            except ConnectionError as exc:
+                logger.warning("Failed to analyze overseas %s: %s", stock_code, exc)
+            except Exception as exc:
+                logger.error("Unexpected error analyzing overseas %s: %s", stock_code, exc)
+        logger.info(
+            "Overseas symbol fallback scan found %d candidates for %s",
+            len(candidates),
+            market.name,
+        )
+        return candidates
+
    def get_stock_codes(self, candidates: list[ScanCandidate]) -> list[str]:
        """Extract stock codes from candidates for watchlist update.

@@ -190,3 +372,78 @@ class SmartVolatilityScanner:
            List of stock codes
        """
        return [c.stock_code for c in candidates]
+
+
+def _safe_float(value: Any, default: float = 0.0) -> float:
+    """Convert arbitrary values to float safely."""
+    if value in (None, ""):
+        return default
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _extract_stock_code(row: dict[str, Any]) -> str:
+    """Extract normalized stock code from various API schemas."""
+    return (
+        str(
+            row.get("symb")
+            or row.get("ovrs_pdno")
+            or row.get("stock_code")
+            or row.get("pdno")
+            or ""
+        )
+        .strip()
+        .upper()
+    )
+
+
+def _extract_last_price(row: dict[str, Any]) -> float:
+    """Extract last/close-like price from API schema variants."""
+    return _safe_float(
+        row.get("last")
+        or row.get("ovrs_nmix_prpr")
+        or row.get("stck_prpr")
+        or row.get("price")
+        or row.get("close")
+    )
+
+
+def _extract_change_rate_pct(row: dict[str, Any]) -> float:
+    """Extract daily change rate (%) from API schema variants."""
+    return _safe_float(
+        row.get("rate")
+        or row.get("change_rate")
+        or row.get("prdy_ctrt")
+        or row.get("evlu_pfls_rt")
+        or row.get("chg_rt")
+    )
+
+
+def _extract_volume(row: dict[str, Any]) -> float:
+    """Extract volume/traded-amount proxy from schema variants."""
+    return _safe_float(
+        row.get("tvol") or row.get("acml_vol") or row.get("vol") or row.get("volume")
+    )
+
+
+def _extract_intraday_range_pct(row: dict[str, Any], price: float) -> float:
+    """Estimate intraday range percentage from high/low fields."""
+    if price <= 0:
+        return 0.0
+    high = _safe_float(
+        row.get("high")
+        or row.get("ovrs_hgpr")
+        or row.get("stck_hgpr")
+        or row.get("day_hgpr")
+    )
+    low = _safe_float(
+        row.get("low")
+        or row.get("ovrs_lwpr")
+        or row.get("stck_lwpr")
+        or row.get("day_lwpr")
+    )
+    if high <= 0 or low <= 0 or high < low:
+        return 0.0
+    return (high - low) / price * 100.0
--- a/src/brain/gemini_client.py
+++ b/src/brain/gemini_client.py
@@ -410,8 +410,10 @@ class GeminiClient:
                    cached=True,
                )

-        # Build optimized prompt
-        if self._enable_optimization:
+        # Build prompt (prompt_override takes priority for callers like pre_market_planner)
+        if "prompt_override" in market_data:
+            prompt = market_data["prompt_override"]
+        elif self._enable_optimization:
            prompt = self._optimizer.build_compressed_prompt(market_data)
        else:
            prompt = await self.build_prompt(market_data, news_sentiment)
--- a/src/broker/kis_api.py
+++ b/src/broker/kis_api.py
@@ -104,12 +104,14 @@ class KISBroker:
            time_since_last_attempt = now - self._last_refresh_attempt
            if time_since_last_attempt < self._refresh_cooldown:
                remaining = self._refresh_cooldown - time_since_last_attempt
-                error_msg = (
-                    f"Token refresh on cooldown. "
-                    f"Retry in {remaining:.1f}s (KIS allows 1/minute)"
+                # Do not fail fast here. If token is unavailable, upstream calls
+                # will all fail for up to a minute and scanning returns no trades.
+                logger.warning(
+                    "Token refresh on cooldown. Waiting %.1fs before retry (KIS allows 1/minute)",
+                    remaining,
                )
-                logger.warning(error_msg)
-                raise ConnectionError(error_msg)
+                await asyncio.sleep(remaining)
+                now = asyncio.get_event_loop().time()

            logger.info("Refreshing KIS access token")
            self._last_refresh_attempt = now
--- a/src/broker/overseas.py
+++ b/src/broker/overseas.py
@@ -12,6 +12,24 @@ from src.broker.kis_api import KISBroker
 logger = logging.getLogger(__name__)


+# Ranking API uses different exchange codes than order/quote APIs.
+_RANKING_EXCHANGE_MAP: dict[str, str] = {
+    "NASD": "NAS",
+    "NYSE": "NYS",
+    "AMEX": "AMS",
+    "SEHK": "HKS",
+    "SHAA": "SHS",
+    "SZAA": "SZS",
+    "HSX": "HSX",
+    "HNX": "HNX",
+    "TSE": "TSE",
+}
+
+# Price inquiry API (HHDFS00000300) uses the same short exchange codes as rankings.
+# NASD → NAS, NYSE → NYS, AMEX → AMS (confirmed: AMEX returns empty, AMS returns price).
+_PRICE_EXCHANGE_MAP: dict[str, str] = _RANKING_EXCHANGE_MAP
+
+
 class OverseasBroker:
    """KIS Overseas Stock API wrapper that reuses KISBroker infrastructure."""

@@ -44,9 +62,11 @@ class OverseasBroker:
        session = self._broker._get_session()

        headers = await self._broker._auth_headers("HHDFS00000300")
+        # Map internal exchange codes to the short form expected by the price API.
+        price_excd = _PRICE_EXCHANGE_MAP.get(exchange_code, exchange_code)
        params = {
            "AUTH": "",
-            "EXCD": exchange_code,
+            "EXCD": price_excd,
            "SYMB": stock_code,
        }
        url = f"{self._broker._base_url}/uapi/overseas-price/v1/quotations/price"
@@ -64,6 +84,81 @@ class OverseasBroker:
                f"Network error fetching overseas price: {exc}"
            ) from exc

+    async def fetch_overseas_rankings(
+        self,
+        exchange_code: str,
+        ranking_type: str = "fluctuation",
+        limit: int = 30,
+    ) -> list[dict[str, Any]]:
+        """Fetch overseas rankings (price change or volume surge).
+
+        Ranking API specs may differ by account/product. Endpoint paths and
+        TR_IDs are configurable via settings and can be overridden in .env.
+        """
+        if not self._broker._settings.OVERSEAS_RANKING_ENABLED:
+            return []
+
+        await self._broker._rate_limiter.acquire()
+        session = self._broker._get_session()
+
+        ranking_excd = _RANKING_EXCHANGE_MAP.get(exchange_code, exchange_code)
+
+        if ranking_type == "volume":
+            tr_id = self._broker._settings.OVERSEAS_RANKING_VOLUME_TR_ID
+            path = self._broker._settings.OVERSEAS_RANKING_VOLUME_PATH
+            params: dict[str, str] = {
+                "AUTH": "",
+                "EXCD": ranking_excd,
+                "MIXN": "0",
+                "VOL_RANG": "0",
+            }
+        else:
+            tr_id = self._broker._settings.OVERSEAS_RANKING_FLUCT_TR_ID
+            path = self._broker._settings.OVERSEAS_RANKING_FLUCT_PATH
+            params = {
+                "AUTH": "",
+                "EXCD": ranking_excd,
+                "NDAY": "0",
+                "GUBN": "1",
+                "VOL_RANG": "0",
+            }
+
+        headers = await self._broker._auth_headers(tr_id)
+        url = f"{self._broker._base_url}{path}"
+
+        try:
+            async with session.get(url, headers=headers, params=params) as resp:
+                if resp.status != 200:
+                    text = await resp.text()
+                    if resp.status == 404:
+                        logger.warning(
+                            "Overseas ranking endpoint unavailable (404) for %s/%s; "
+                            "using symbol fallback scan",
+                            exchange_code,
+                            ranking_type,
+                        )
+                        return []
+                    raise ConnectionError(
+                        f"fetch_overseas_rankings failed ({resp.status}): {text}"
+                    )
+
+                data = await resp.json()
+                rows = self._extract_ranking_rows(data)
+                if rows:
+                    return rows[:limit]
+
+                logger.debug(
+                    "Overseas ranking returned empty for %s/%s (keys=%s)",
+                    exchange_code,
+                    ranking_type,
+                    list(data.keys()),
+                )
+                return []
+        except (TimeoutError, aiohttp.ClientError) as exc:
+            raise ConnectionError(
+                f"Network error fetching overseas rankings: {exc}"
+            ) from exc
+
    async def get_overseas_balance(self, exchange_code: str) -> dict[str, Any]:
        """
        Fetch overseas account balance.
@@ -198,3 +293,11 @@ class OverseasBroker:
            "HSX": "VND",
        }
        return currency_map.get(exchange_code, "USD")
+
+    def _extract_ranking_rows(self, data: dict[str, Any]) -> list[dict[str, Any]]:
+        """Extract list rows from ranking response across schema variants."""
+        candidates = [data.get("output"), data.get("output1"), data.get("output2")]
+        for value in candidates:
+            if isinstance(value, list):
+                return [row for row in value if isinstance(row, dict)]
+        return []
--- a/src/config.py
+++ b/src/config.py
@@ -38,6 +38,11 @@ class Settings(BaseSettings):
    RSI_MOMENTUM_THRESHOLD: int = Field(default=70, ge=50, le=100)
    VOL_MULTIPLIER: float = Field(default=2.0, gt=1.0, le=10.0)
    SCANNER_TOP_N: int = Field(default=3, ge=1, le=10)
+    POSITION_SIZING_ENABLED: bool = True
+    POSITION_BASE_ALLOCATION_PCT: float = Field(default=5.0, gt=0.0, le=30.0)
+    POSITION_MIN_ALLOCATION_PCT: float = Field(default=1.0, gt=0.0, le=20.0)
+    POSITION_MAX_ALLOCATION_PCT: float = Field(default=10.0, gt=0.0, le=50.0)
+    POSITION_VOLATILITY_TARGET_SCORE: float = Field(default=50.0, gt=0.0, le=100.0)

    # Database
    DB_PATH: str = "data/trade_logs.db"
@@ -50,6 +55,11 @@ class Settings(BaseSettings):
    # Trading mode
    MODE: str = Field(default="paper", pattern="^(paper|live)$")

+    # Simulated USD cash for VTS (paper) overseas trading.
+    # KIS VTS overseas balance API returns errors for most accounts.
+    # This value is used as a fallback when the balance API returns 0 in paper mode.
+    PAPER_OVERSEAS_CASH: float = Field(default=50000.0, ge=0.0)
+
    # Trading frequency mode (daily = batch API calls, realtime = per-stock calls)
    TRADE_MODE: str = Field(default="daily", pattern="^(daily|realtime)$")
    DAILY_SESSIONS: int = Field(default=4, ge=1, le=10)
@@ -83,6 +93,18 @@ class Settings(BaseSettings):
    TELEGRAM_COMMANDS_ENABLED: bool = True
    TELEGRAM_POLLING_INTERVAL: float = 1.0  # seconds

+    # Overseas ranking API (KIS endpoint/TR_ID may vary by account/product)
+    # Override these from .env if your account uses different specs.
+    OVERSEAS_RANKING_ENABLED: bool = True
+    OVERSEAS_RANKING_FLUCT_TR_ID: str = "HHDFS76290000"
+    OVERSEAS_RANKING_VOLUME_TR_ID: str = "HHDFS76270000"
+    OVERSEAS_RANKING_FLUCT_PATH: str = (
+        "/uapi/overseas-stock/v1/ranking/updown-rate"
+    )
+    OVERSEAS_RANKING_VOLUME_PATH: str = (
+        "/uapi/overseas-stock/v1/ranking/volume-surge"
+    )
+
    # Dashboard (optional)
    DASHBOARD_ENABLED: bool = False
    DASHBOARD_HOST: str = "127.0.0.1"
@@ -101,4 +123,7 @@ class Settings(BaseSettings):
    @property
    def enabled_market_list(self) -> list[str]:
        """Parse ENABLED_MARKETS into list of market codes."""
-        return [m.strip() for m in self.ENABLED_MARKETS.split(",") if m.strip()]
+        from src.markets.schedule import expand_market_codes
+
+        raw = [m.strip() for m in self.ENABLED_MARKETS.split(",") if m.strip()]
+        return expand_market_codes(raw)
--- a/src/dashboard/app.py
+++ b/src/dashboard/app.py
@@ -26,7 +26,19 @@ def create_dashboard_app(db_path: str) -> FastAPI:
    def get_status() -> dict[str, Any]:
        today = datetime.now(UTC).date().isoformat()
        with _connect(db_path) as conn:
-            markets = ["KR", "US"]
+            market_rows = conn.execute(
+                """
+                SELECT DISTINCT market FROM (
+                    SELECT market FROM trades WHERE DATE(timestamp) = ?
+                    UNION
+                    SELECT market FROM decision_logs WHERE DATE(timestamp) = ?
+                    UNION
+                    SELECT market FROM playbooks WHERE date = ?
+                ) ORDER BY market
+                """,
+                (today, today, today),
+            ).fetchall()
+            markets = [row[0] for row in market_rows] if market_rows else []
            market_status: dict[str, Any] = {}
            total_trades = 0
            total_pnl = 0.0
--- a/src/db.py
+++ b/src/db.py
@@ -214,3 +214,42 @@ def get_latest_buy_trade(
    if not row:
        return None
    return {"decision_id": row[0], "price": row[1], "quantity": row[2]}
+
+
+def get_open_position(
+    conn: sqlite3.Connection, stock_code: str, market: str
+) -> dict[str, Any] | None:
+    """Return open position if latest trade is BUY, else None."""
+    cursor = conn.execute(
+        """
+        SELECT action, decision_id, price, quantity
+        FROM trades
+        WHERE stock_code = ?
+          AND market = ?
+        ORDER BY timestamp DESC
+        LIMIT 1
+        """,
+        (stock_code, market),
+    )
+    row = cursor.fetchone()
+    if not row or row[0] != "BUY":
+        return None
+    return {"decision_id": row[1], "price": row[2], "quantity": row[3]}
+
+
+def get_recent_symbols(
+    conn: sqlite3.Connection, market: str, limit: int = 30
+) -> list[str]:
+    """Return recent unique symbols for a market, newest first."""
+    cursor = conn.execute(
+        """
+        SELECT stock_code, MAX(timestamp) AS last_ts
+        FROM trades
+        WHERE market = ?
+        GROUP BY stock_code
+        ORDER BY last_ts DESC
+        LIMIT ?
+        """,
+        (market, limit),
+    )
+    return [row[0] for row in cursor.fetchall() if row and row[0]]
--- a/src/main.py
+++ b/src/main.py
@@ -8,6 +8,7 @@ from __future__ import annotations

 import argparse
 import asyncio
+import json
 import logging
 import signal
 import threading
@@ -28,7 +29,13 @@ from src.context.store import ContextStore
 from src.core.criticality import CriticalityAssessor
 from src.core.priority_queue import PriorityTaskQueue
 from src.core.risk_manager import CircuitBreakerTripped, FatFingerRejected, RiskManager
-from src.db import get_latest_buy_trade, init_db, log_trade
+from src.db import (
+    get_latest_buy_trade,
+    get_open_position,
+    get_recent_symbols,
+    init_db,
+    log_trade,
+)
 from src.evolution.daily_review import DailyReviewer
 from src.evolution.optimizer import EvolutionOptimizer
 from src.logging.decision_logger import DecisionLogger
@@ -80,6 +87,102 @@ DAILY_TRADE_SESSIONS = 4  # Number of trading sessions per day
 TRADE_SESSION_INTERVAL_HOURS = 6  # Hours between sessions


+def _extract_symbol_from_holding(item: dict[str, Any]) -> str:
+    """Extract symbol from overseas holding payload variants."""
+    for key in (
+        "ovrs_pdno",
+        "pdno",
+        "ovrs_item_name",
+        "prdt_name",
+        "symb",
+        "symbol",
+        "stock_code",
+    ):
+        value = item.get(key)
+        if isinstance(value, str):
+            symbol = value.strip().upper()
+            if symbol and symbol.replace(".", "").replace("-", "").isalnum():
+                return symbol
+    return ""
+
+
+def _determine_order_quantity(
+    *,
+    action: str,
+    current_price: float,
+    total_cash: float,
+    candidate: ScanCandidate | None,
+    settings: Settings | None,
+) -> int:
+    """Determine order quantity using volatility-aware position sizing."""
+    if action != "BUY":
+        return 1
+    if current_price <= 0 or total_cash <= 0:
+        return 0
+
+    if settings is None or not settings.POSITION_SIZING_ENABLED:
+        return 1
+
+    target_score = max(1.0, settings.POSITION_VOLATILITY_TARGET_SCORE)
+    observed_score = candidate.score if candidate else target_score
+    observed_score = max(1.0, min(100.0, observed_score))
+
+    # Higher observed volatility score => smaller allocation.
+    scaled_pct = settings.POSITION_BASE_ALLOCATION_PCT * (target_score / observed_score)
+    allocation_pct = min(
+        settings.POSITION_MAX_ALLOCATION_PCT,
+        max(settings.POSITION_MIN_ALLOCATION_PCT, scaled_pct),
+    )
+
+    budget = total_cash * (allocation_pct / 100.0)
+    quantity = int(budget // current_price)
+    if quantity <= 0:
+        return 0
+    return quantity
+
+
+async def build_overseas_symbol_universe(
+    db_conn: Any,
+    overseas_broker: OverseasBroker,
+    market: MarketInfo,
+    active_stocks: dict[str, list[str]],
+) -> list[str]:
+    """Build dynamic overseas symbol universe from runtime, DB, and holdings."""
+    symbols: list[str] = []
+
+    # 1) Keep current active stocks first to avoid sudden churn between cycles.
+    symbols.extend(active_stocks.get(market.code, []))
+
+    # 2) Add recent symbols from own trading history (no fixed list).
+    symbols.extend(get_recent_symbols(db_conn, market.code, limit=30))
+
+    # 3) Add current overseas holdings from broker balance if available.
+    try:
+        balance_data = await overseas_broker.get_overseas_balance(market.exchange_code)
+        output1 = balance_data.get("output1", [])
+        if isinstance(output1, dict):
+            output1 = [output1]
+        if isinstance(output1, list):
+            for row in output1:
+                if not isinstance(row, dict):
+                    continue
+                symbol = _extract_symbol_from_holding(row)
+                if symbol:
+                    symbols.append(symbol)
+    except Exception as exc:
+        logger.warning("Failed to build overseas holdings universe for %s: %s", market.code, exc)
+
+    seen: set[str] = set()
+    ordered_unique: list[str] = []
+    for symbol in symbols:
+        normalized = symbol.strip().upper()
+        if not normalized or normalized in seen:
+            continue
+        seen.add(normalized)
+        ordered_unique.append(normalized)
+    return ordered_unique
+
+
 async def trading_cycle(
    broker: KISBroker,
    overseas_broker: OverseasBroker,
@@ -94,6 +197,7 @@ async def trading_cycle(
    market: MarketInfo,
    stock_code: str,
    scan_candidates: dict[str, dict[str, ScanCandidate]],
+    settings: Settings | None = None,
 ) -> None:
    """Execute one trading cycle for a single stock."""
    cycle_start_time = asyncio.get_event_loop().time()
@@ -114,6 +218,7 @@ async def trading_cycle(

        current_price = safe_float(orderbook.get("output1", {}).get("stck_prpr", "0"))
        foreigner_net = safe_float(orderbook.get("output1", {}).get("frgn_ntby_qty", "0"))
+        price_change_pct = safe_float(orderbook.get("output1", {}).get("prdy_ctrt", "0"))
    else:
        # Overseas market
        price_data = await overseas_broker.get_overseas_price(
@@ -134,8 +239,32 @@ async def trading_cycle(
        total_cash = safe_float(balance_info.get("frcr_dncl_amt_2", "0") or "0")
        purchase_total = safe_float(balance_info.get("frcr_buy_amt_smtl", "0") or "0")

+        # VTS (paper trading) overseas balance API often returns 0 or errors.
+        # Fall back to configured paper cash so BUY orders can be sized.
+        if total_cash <= 0 and settings and settings.PAPER_OVERSEAS_CASH > 0:
+            logger.debug(
+                "Overseas cash balance is 0 for %s; using paper fallback %.2f",
+                stock_code,
+                settings.PAPER_OVERSEAS_CASH,
+            )
+            total_cash = settings.PAPER_OVERSEAS_CASH
+
        current_price = safe_float(price_data.get("output", {}).get("last", "0"))
        foreigner_net = 0.0  # Not available for overseas
+        price_change_pct = safe_float(price_data.get("output", {}).get("rate", "0"))
+
+        # Price API may return 0/empty for certain VTS exchange codes.
+        # Fall back to the scanner candidate's price so order sizing still works.
+        if current_price <= 0:
+            market_candidates_lookup = scan_candidates.get(market.code, {})
+            cand_lookup = market_candidates_lookup.get(stock_code)
+            if cand_lookup and cand_lookup.price > 0:
+                current_price = cand_lookup.price
+                logger.debug(
+                    "Price API returned 0 for %s; using scanner price %.4f",
+                    stock_code,
+                    current_price,
+                )

    # Calculate daily P&L %
    pnl_pct = (
@@ -149,6 +278,7 @@ async def trading_cycle(
        "market_name": market.name,
        "current_price": current_price,
        "foreigner_net": foreigner_net,
+        "price_change_pct": price_change_pct,
    }

    # Enrich market_data with scanner metrics for scenario engine
@@ -240,6 +370,34 @@ async def trading_cycle(
        confidence=match.confidence,
        rationale=match.rationale,
    )
+    stock_playbook = playbook.get_stock_playbook(stock_code)
+
+    if decision.action == "HOLD":
+        open_position = get_open_position(db_conn, stock_code, market.code)
+        if open_position:
+            entry_price = safe_float(open_position.get("price"), 0.0)
+            if entry_price > 0:
+                loss_pct = (current_price - entry_price) / entry_price * 100
+                stop_loss_threshold = -2.0
+                if stock_playbook and stock_playbook.scenarios:
+                    stop_loss_threshold = stock_playbook.scenarios[0].stop_loss_pct
+
+                if loss_pct <= stop_loss_threshold:
+                    decision = TradeDecision(
+                        action="SELL",
+                        confidence=95,
+                        rationale=(
+                            f"Stop-loss triggered ({loss_pct:.2f}% <= "
+                            f"{stop_loss_threshold:.2f}%)"
+                        ),
+                    )
+                    logger.info(
+                        "Stop-loss override for %s (%s): %.2f%% <= %.2f%%",
+                        stock_code,
+                        market.name,
+                        loss_pct,
+                        stop_loss_threshold,
+                    )
    logger.info(
        "Decision for %s (%s): %s (confidence=%d)",
        stock_code,
@@ -278,6 +436,7 @@ async def trading_cycle(
    input_data = {
        "current_price": current_price,
        "foreigner_net": foreigner_net,
+        "price_change_pct": price_change_pct,
        "total_eval": total_eval,
        "total_cash": total_cash,
        "pnl_pct": pnl_pct,
@@ -299,8 +458,23 @@ async def trading_cycle(
    trade_price = current_price
    trade_pnl = 0.0
    if decision.action in ("BUY", "SELL"):
-        # Determine order size (simplified: 1 lot)
-        quantity = 1
+        quantity = _determine_order_quantity(
+            action=decision.action,
+            current_price=current_price,
+            total_cash=total_cash,
+            candidate=candidate,
+            settings=settings,
+        )
+        if quantity <= 0:
+            logger.info(
+                "Skip %s %s (%s): no affordable quantity (cash=%.2f, price=%.2f)",
+                decision.action,
+                stock_code,
+                market.name,
+                total_cash,
+                current_price,
+            )
+            return
        order_amount = current_price * quantity

        # 4. Risk check BEFORE order
@@ -336,7 +510,7 @@ async def trading_cycle(
                stock_code=stock_code,
                order_type=decision.action,
                quantity=quantity,
-                price=0.0,  # market order
+                price=current_price,  # limit order — KIS VTS rejects market orders
            )
        logger.info("Order result: %s", result.get("msg1", "OK"))

@@ -449,8 +623,28 @@ async def run_daily_session(

        # Dynamic stock discovery via scanner (no static watchlists)
        candidates_list: list[ScanCandidate] = []
+        fallback_stocks: list[str] | None = None
+        if not market.is_domestic:
+            fallback_stocks = await build_overseas_symbol_universe(
+                db_conn=db_conn,
+                overseas_broker=overseas_broker,
+                market=market,
+                active_stocks={},
+            )
+            if not fallback_stocks:
+                logger.warning(
+                    "No dynamic overseas symbol universe for %s; scanner cannot run",
+                    market.code,
+                )
        try:
-            candidates_list = await smart_scanner.scan() if smart_scanner else []
+            candidates_list = (
+                await smart_scanner.scan(
+                    market=market,
+                    fallback_stocks=fallback_stocks,
+                )
+                if smart_scanner
+                else []
+            )
        except Exception as exc:
            logger.error("Smart Scanner failed for %s: %s", market.name, exc)

@@ -507,6 +701,9 @@ async def run_daily_session(
                    foreigner_net = safe_float(
                        orderbook.get("output1", {}).get("frgn_ntby_qty", "0")
                    )
+                    price_change_pct = safe_float(
+                        orderbook.get("output1", {}).get("prdy_ctrt", "0")
+                    )
                else:
                    price_data = await overseas_broker.get_overseas_price(
                        market.exchange_code, stock_code
@@ -515,12 +712,26 @@ async def run_daily_session(
                        price_data.get("output", {}).get("last", "0")
                    )
                    foreigner_net = 0.0
+                    price_change_pct = safe_float(
+                        price_data.get("output", {}).get("rate", "0")
+                    )
+                    # Fall back to scanner candidate price if API returns 0.
+                    if current_price <= 0:
+                        cand_lookup = candidate_map.get(stock_code)
+                        if cand_lookup and cand_lookup.price > 0:
+                            current_price = cand_lookup.price
+                            logger.debug(
+                                "Price API returned 0 for %s; using scanner price %.4f",
+                                stock_code,
+                                current_price,
+                            )

                stock_data: dict[str, Any] = {
                    "stock_code": stock_code,
                    "market_name": market.name,
                    "current_price": current_price,
                    "foreigner_net": foreigner_net,
+                    "price_change_pct": price_change_pct,
                }
                # Enrich with scanner metrics
                cand = candidate_map.get(stock_code)
@@ -565,6 +776,10 @@ async def run_daily_session(
                balance_info.get("frcr_buy_amt_smtl", "0") or "0"
            )

+            # VTS overseas balance API often returns 0; use paper fallback.
+            if total_cash <= 0 and settings.PAPER_OVERSEAS_CASH > 0:
+                total_cash = settings.PAPER_OVERSEAS_CASH
+
        # Calculate daily P&L %
        pnl_pct = (
            ((total_eval - purchase_total) / purchase_total * 100)
@@ -639,7 +854,23 @@ async def run_daily_session(
            trade_price = stock_data["current_price"]
            trade_pnl = 0.0
            if decision.action in ("BUY", "SELL"):
-                quantity = 1
+                quantity = _determine_order_quantity(
+                    action=decision.action,
+                    current_price=stock_data["current_price"],
+                    total_cash=total_cash,
+                    candidate=candidate_map.get(stock_code),
+                    settings=settings,
+                )
+                if quantity <= 0:
+                    logger.info(
+                        "Skip %s %s (%s): no affordable quantity (cash=%.2f, price=%.2f)",
+                        decision.action,
+                        stock_code,
+                        market.name,
+                        total_cash,
+                        stock_data["current_price"],
+                    )
+                    continue
                order_amount = stock_data["current_price"] * quantity

                # Risk check
@@ -688,7 +919,7 @@ async def run_daily_session(
                            stock_code=stock_code,
                            order_type=decision.action,
                            quantity=quantity,
-                            price=0.0,  # market order
+                            price=stock_data["current_price"],  # limit order — KIS VTS rejects market orders
                        )
                    logger.info("Order result: %s", result.get("msg1", "OK"))

@@ -820,7 +1051,7 @@ async def _run_evolution_loop(
    market_date: str,
 ) -> None:
    """Run evolution loop once at US close (end of trading day)."""
-    if market_code != "US":
+    if not market_code.startswith("US"):
        return

    try:
@@ -936,6 +1167,10 @@ async def run(settings: Settings) -> None:
            "/help - Show available commands\n"
            "/status - Trading status (mode, markets, P&L)\n"
            "/positions - Current holdings\n"
+            "/report - Daily summary report\n"
+            "/scenarios - Today's playbook scenarios\n"
+            "/review - Recent scorecards\n"
+            "/dashboard - Dashboard URL/status\n"
            "/stop - Pause trading\n"
            "/resume - Resume trading"
        )
@@ -1055,17 +1290,171 @@ async def run(settings: Settings) -> None:
                "<b>⚠️ Error</b>\n\nFailed to retrieve positions."
            )

+    async def handle_report() -> None:
+        """Handle /report command - show daily summary metrics."""
+        try:
+            today = datetime.now(UTC).date().isoformat()
+            trade_row = db_conn.execute(
+                """
+                SELECT COUNT(*) AS trade_count,
+                       COALESCE(SUM(pnl), 0.0) AS total_pnl,
+                       SUM(CASE WHEN pnl > 0 THEN 1 ELSE 0 END) AS wins
+                FROM trades
+                WHERE DATE(timestamp) = ?
+                """,
+                (today,),
+            ).fetchone()
+            decision_row = db_conn.execute(
+                """
+                SELECT COUNT(*) AS decision_count,
+                       COALESCE(AVG(confidence), 0.0) AS avg_confidence
+                FROM decision_logs
+                WHERE DATE(timestamp) = ?
+                """,
+                (today,),
+            ).fetchone()
+
+            trade_count = int(trade_row[0] if trade_row else 0)
+            total_pnl = float(trade_row[1] if trade_row else 0.0)
+            wins = int(trade_row[2] if trade_row and trade_row[2] is not None else 0)
+            decision_count = int(decision_row[0] if decision_row else 0)
+            avg_confidence = float(decision_row[1] if decision_row else 0.0)
+            win_rate = (wins / trade_count * 100.0) if trade_count > 0 else 0.0
+
+            await telegram.send_message(
+                "<b>📈 Daily Report</b>\n\n"
+                f"<b>Date:</b> {today}\n"
+                f"<b>Trades:</b> {trade_count}\n"
+                f"<b>Total P&L:</b> {total_pnl:+.2f}\n"
+                f"<b>Win Rate:</b> {win_rate:.2f}%\n"
+                f"<b>Decisions:</b> {decision_count}\n"
+                f"<b>Avg Confidence:</b> {avg_confidence:.2f}"
+            )
+        except Exception as exc:
+            logger.error("Error in /report handler: %s", exc)
+            await telegram.send_message(
+                "<b>⚠️ Error</b>\n\nFailed to generate daily report."
+            )
+
+    async def handle_scenarios() -> None:
+        """Handle /scenarios command - show today's playbook scenarios."""
+        try:
+            today = datetime.now(UTC).date().isoformat()
+            rows = db_conn.execute(
+                """
+                SELECT market, playbook_json
+                FROM playbooks
+                WHERE date = ?
+                ORDER BY market
+                """,
+                (today,),
+            ).fetchall()
+
+            if not rows:
+                await telegram.send_message(
+                    "<b>🧠 Today's Scenarios</b>\n\nNo playbooks found for today."
+                )
+                return
+
+            lines = ["<b>🧠 Today's Scenarios</b>", ""]
+            for market, playbook_json in rows:
+                lines.append(f"<b>{market}</b>")
+                playbook_data = {}
+                try:
+                    playbook_data = json.loads(playbook_json)
+                except Exception:
+                    playbook_data = {}
+
+                stock_playbooks = playbook_data.get("stock_playbooks", [])
+                if not stock_playbooks:
+                    lines.append("- No scenarios")
+                    lines.append("")
+                    continue
+
+                for stock_pb in stock_playbooks:
+                    stock_code = stock_pb.get("stock_code", "N/A")
+                    scenarios = stock_pb.get("scenarios", [])
+                    for sc in scenarios:
+                        action = sc.get("action", "HOLD")
+                        confidence = sc.get("confidence", 0)
+                        lines.append(f"- {stock_code}: {action} ({confidence})")
+                lines.append("")
+
+            await telegram.send_message("\n".join(lines).strip())
+        except Exception as exc:
+            logger.error("Error in /scenarios handler: %s", exc)
+            await telegram.send_message(
+                "<b>⚠️ Error</b>\n\nFailed to retrieve scenarios."
+            )
+
+    async def handle_review() -> None:
+        """Handle /review command - show recent scorecards."""
+        try:
+            rows = db_conn.execute(
+                """
+                SELECT timeframe, key, value
+                FROM contexts
+                WHERE layer = 'L6_DAILY' AND key LIKE 'scorecard_%'
+                ORDER BY updated_at DESC
+                LIMIT 5
+                """
+            ).fetchall()
+
+            if not rows:
+                await telegram.send_message(
+                    "<b>📝 Recent Reviews</b>\n\nNo scorecards available."
+                )
+                return
+
+            lines = ["<b>📝 Recent Reviews</b>", ""]
+            for timeframe, key, value in rows:
+                scorecard = json.loads(value)
+                market = key.replace("scorecard_", "")
+                total_pnl = float(scorecard.get("total_pnl", 0.0))
+                win_rate = float(scorecard.get("win_rate", 0.0))
+                decisions = int(scorecard.get("total_decisions", 0))
+                lines.append(
+                    f"- {timeframe} {market}: P&L {total_pnl:+.2f}, "
+                    f"Win {win_rate:.2f}%, Decisions {decisions}"
+                )
+
+            await telegram.send_message("\n".join(lines))
+        except Exception as exc:
+            logger.error("Error in /review handler: %s", exc)
+            await telegram.send_message(
+                "<b>⚠️ Error</b>\n\nFailed to retrieve reviews."
+            )
+
+    async def handle_dashboard() -> None:
+        """Handle /dashboard command - show dashboard URL if enabled."""
+        if not settings.DASHBOARD_ENABLED:
+            await telegram.send_message(
+                "<b>🖥️ Dashboard</b>\n\nDashboard is not enabled."
+            )
+            return
+
+        url = f"http://{settings.DASHBOARD_HOST}:{settings.DASHBOARD_PORT}"
+        await telegram.send_message(
+            "<b>🖥️ Dashboard</b>\n\n"
+            f"<b>URL:</b> {url}"
+        )
+
    command_handler.register_command("help", handle_help)
    command_handler.register_command("stop", handle_stop)
    command_handler.register_command("resume", handle_resume)
    command_handler.register_command("status", handle_status)
    command_handler.register_command("positions", handle_positions)
+    command_handler.register_command("report", handle_report)
+    command_handler.register_command("scenarios", handle_scenarios)
+    command_handler.register_command("review", handle_review)
+    command_handler.register_command("dashboard", handle_dashboard)

    # Initialize volatility hunter
    volatility_analyzer = VolatilityAnalyzer(min_volume_surge=2.0, min_price_change=1.0)
    # Initialize smart scanner (Python-first, AI-last pipeline)
    smart_scanner = SmartVolatilityScanner(
        broker=broker,
+        overseas_broker=overseas_broker,
        volatility_analyzer=volatility_analyzer,
        settings=settings,
    )
@@ -1245,7 +1634,25 @@ async def run(settings: Settings) -> None:
                        try:
                            logger.info("Smart Scanner: Scanning %s market", market.name)

-                            candidates = await smart_scanner.scan()
+                            fallback_stocks: list[str] | None = None
+                            if not market.is_domestic:
+                                fallback_stocks = await build_overseas_symbol_universe(
+                                    db_conn=db_conn,
+                                    overseas_broker=overseas_broker,
+                                    market=market,
+                                    active_stocks=active_stocks,
+                                )
+                                if not fallback_stocks:
+                                    logger.warning(
+                                        "No dynamic overseas symbol universe for %s;"
+                                        " scanner cannot run",
+                                        market.code,
+                                    )
+
+                            candidates = await smart_scanner.scan(
+                                market=market,
+                                fallback_stocks=fallback_stocks,
+                            )

                            if candidates:
                                # Use scanner results directly as trading candidates
@@ -1369,6 +1776,7 @@ async def run(settings: Settings) -> None:
                                    market,
                                    stock_code,
                                    scan_candidates,
+                                    settings,
                                )
                                break  # Success — exit retry loop
                            except CircuitBreakerTripped as exc:
--- a/src/markets/schedule.py
+++ b/src/markets/schedule.py
@@ -123,6 +123,23 @@ MARKETS: dict[str, MarketInfo] = {
    ),
 }

+MARKET_SHORTHAND: dict[str, list[str]] = {
+    "US": ["US_NASDAQ", "US_NYSE", "US_AMEX"],
+    "CN": ["CN_SHA", "CN_SZA"],
+    "VN": ["VN_HAN", "VN_HCM"],
+}
+
+
+def expand_market_codes(codes: list[str]) -> list[str]:
+    """Expand shorthand market codes into concrete exchange market codes."""
+    expanded: list[str] = []
+    for code in codes:
+        if code in MARKET_SHORTHAND:
+            expanded.extend(MARKET_SHORTHAND[code])
+        else:
+            expanded.append(code)
+    return expanded
+

 def is_market_open(market: MarketInfo, now: datetime | None = None) -> bool:
    """
--- a/src/strategy/pre_market_planner.py
+++ b/src/strategy/pre_market_planner.py
@@ -1,7 +1,8 @@
 """Pre-market planner — generates DayPlaybook via Gemini before market open.

 One Gemini API call per market per day. Candidates come from SmartVolatilityScanner.
-On failure, returns a defensive playbook (all HOLD, no trades).
+On failure, returns a smart rule-based fallback playbook that uses scanner signals
+(momentum/oversold) to generate BUY conditions, avoiding the all-HOLD problem.
 """

 from __future__ import annotations
@@ -134,7 +135,7 @@ class PreMarketPlanner:
        except Exception:
            logger.exception("Playbook generation failed for %s", market)
            if self._settings.DEFENSIVE_PLAYBOOK_ON_FAILURE:
-                return self._defensive_playbook(today, market, candidates)
+                return self._smart_fallback_playbook(today, market, candidates, self._settings)
            return self._empty_playbook(today, market)

    def build_cross_market_context(
@@ -470,3 +471,99 @@ class PreMarketPlanner:
                ),
            ],
        )
+
+    @staticmethod
+    def _smart_fallback_playbook(
+        today: date,
+        market: str,
+        candidates: list[ScanCandidate],
+        settings: Settings,
+    ) -> DayPlaybook:
+        """Rule-based fallback playbook when Gemini is unavailable.
+
+        Uses scanner signals (RSI, volume_ratio) to generate meaningful BUY
+        conditions instead of the all-SELL defensive playbook.  Candidates are
+        already pre-qualified by SmartVolatilityScanner, so we trust their
+        signals and build actionable scenarios from them.
+
+        Scenario logic per candidate:
+        - momentum signal: BUY when volume_ratio exceeds scanner threshold
+        - oversold signal: BUY when RSI is below oversold threshold
+        - always: SELL stop-loss at -3.0% as guard
+        """
+        stock_playbooks = []
+        for c in candidates:
+            scenarios: list[StockScenario] = []
+
+            if c.signal == "momentum":
+                scenarios.append(
+                    StockScenario(
+                        condition=StockCondition(
+                            volume_ratio_above=settings.VOL_MULTIPLIER,
+                        ),
+                        action=ScenarioAction.BUY,
+                        confidence=80,
+                        allocation_pct=10.0,
+                        stop_loss_pct=-3.0,
+                        take_profit_pct=5.0,
+                        rationale=(
+                            f"Rule-based BUY: momentum signal, "
+                            f"volume={c.volume_ratio:.1f}x (fallback planner)"
+                        ),
+                    )
+                )
+            elif c.signal == "oversold":
+                scenarios.append(
+                    StockScenario(
+                        condition=StockCondition(
+                            rsi_below=settings.RSI_OVERSOLD_THRESHOLD,
+                        ),
+                        action=ScenarioAction.BUY,
+                        confidence=80,
+                        allocation_pct=10.0,
+                        stop_loss_pct=-3.0,
+                        take_profit_pct=5.0,
+                        rationale=(
+                            f"Rule-based BUY: oversold signal, "
+                            f"RSI={c.rsi:.0f} (fallback planner)"
+                        ),
+                    )
+                )
+
+            # Always add stop-loss guard
+            scenarios.append(
+                StockScenario(
+                    condition=StockCondition(price_change_pct_below=-3.0),
+                    action=ScenarioAction.SELL,
+                    confidence=90,
+                    stop_loss_pct=-3.0,
+                    rationale="Rule-based stop-loss (fallback planner)",
+                )
+            )
+
+            stock_playbooks.append(
+                StockPlaybook(
+                    stock_code=c.stock_code,
+                    scenarios=scenarios,
+                )
+            )
+
+        logger.info(
+            "Smart fallback playbook for %s: %d stocks with rule-based BUY/SELL conditions",
+            market,
+            len(stock_playbooks),
+        )
+        return DayPlaybook(
+            date=today,
+            market=market,
+            market_outlook=MarketOutlook.NEUTRAL,
+            default_action=ScenarioAction.HOLD,
+            stock_playbooks=stock_playbooks,
+            global_rules=[
+                GlobalRule(
+                    condition="portfolio_pnl_pct < -2.0",
+                    action=ScenarioAction.REDUCE_ALL,
+                    rationale="Defensive: reduce on loss threshold",
+                ),
+            ],
+        )
--- a/tests/test_brain.py
+++ b/tests/test_brain.py
@@ -2,6 +2,10 @@

 from __future__ import annotations

+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
 from src.brain.gemini_client import GeminiClient

 # ---------------------------------------------------------------------------
@@ -270,3 +274,97 @@ class TestBatchDecisionParsing:

        assert decisions["AAPL"].action == "HOLD"
        assert decisions["AAPL"].confidence == 0
+
+
+# ---------------------------------------------------------------------------
+# Prompt Override (used by pre_market_planner)
+# ---------------------------------------------------------------------------
+
+
+class TestPromptOverride:
+    """decide() must use prompt_override when present in market_data."""
+
+    @pytest.mark.asyncio
+    async def test_prompt_override_is_sent_to_gemini(self, settings):
+        """When prompt_override is in market_data, it should be used as the prompt."""
+        client = GeminiClient(settings)
+
+        custom_prompt = "You are a playbook generator. Return JSON with scenarios."
+
+        mock_response = MagicMock()
+        mock_response.text = '{"action": "HOLD", "confidence": 50, "rationale": "test"}'
+
+        with patch.object(
+            client._client.aio.models,
+            "generate_content",
+            new_callable=AsyncMock,
+            return_value=mock_response,
+        ) as mock_generate:
+            market_data = {
+                "stock_code": "PLANNER",
+                "current_price": 0,
+                "prompt_override": custom_prompt,
+            }
+            await client.decide(market_data)
+
+            # Verify the custom prompt was sent, not a built prompt
+            mock_generate.assert_called_once()
+            actual_prompt = mock_generate.call_args[1].get(
+                "contents", mock_generate.call_args[0][1] if len(mock_generate.call_args[0]) > 1 else None
+            )
+            assert actual_prompt == custom_prompt
+
+    @pytest.mark.asyncio
+    async def test_prompt_override_skips_optimization(self, settings):
+        """prompt_override should bypass prompt optimization."""
+        client = GeminiClient(settings)
+        client._enable_optimization = True
+
+        custom_prompt = "Custom playbook prompt"
+
+        mock_response = MagicMock()
+        mock_response.text = '{"action": "HOLD", "confidence": 50, "rationale": "ok"}'
+
+        with patch.object(
+            client._client.aio.models,
+            "generate_content",
+            new_callable=AsyncMock,
+            return_value=mock_response,
+        ) as mock_generate:
+            market_data = {
+                "stock_code": "PLANNER",
+                "current_price": 0,
+                "prompt_override": custom_prompt,
+            }
+            await client.decide(market_data)
+
+            actual_prompt = mock_generate.call_args[1].get(
+                "contents", mock_generate.call_args[0][1] if len(mock_generate.call_args[0]) > 1 else None
+            )
+            assert actual_prompt == custom_prompt
+
+    @pytest.mark.asyncio
+    async def test_without_prompt_override_uses_build_prompt(self, settings):
+        """Without prompt_override, decide() should use build_prompt as before."""
+        client = GeminiClient(settings)
+
+        mock_response = MagicMock()
+        mock_response.text = '{"action": "HOLD", "confidence": 50, "rationale": "ok"}'
+
+        with patch.object(
+            client._client.aio.models,
+            "generate_content",
+            new_callable=AsyncMock,
+            return_value=mock_response,
+        ) as mock_generate:
+            market_data = {
+                "stock_code": "005930",
+                "current_price": 72000,
+            }
+            await client.decide(market_data)
+
+            actual_prompt = mock_generate.call_args[1].get(
+                "contents", mock_generate.call_args[0][1] if len(mock_generate.call_args[0]) > 1 else None
+            )
+            # Should contain stock code from build_prompt, not be a custom override
+            assert "005930" in actual_prompt
--- a/tests/test_broker.py
+++ b/tests/test_broker.py
@@ -90,12 +90,12 @@ class TestTokenManagement:
        await broker.close()

    @pytest.mark.asyncio
-    async def test_token_refresh_cooldown_prevents_rapid_retries(self, settings):
-        """Token refresh should enforce cooldown after failure (issue #54)."""
+    async def test_token_refresh_cooldown_waits_then_retries(self, settings):
+        """Token refresh should wait out cooldown then retry (issue #54)."""
        broker = KISBroker(settings)
-        broker._refresh_cooldown = 2.0  # Short cooldown for testing
+        broker._refresh_cooldown = 0.1  # Short cooldown for testing

-        # First refresh attempt fails with 403 (EGW00133)
+        # All attempts fail with 403 (EGW00133)
        mock_resp_403 = AsyncMock()
        mock_resp_403.status = 403
        mock_resp_403.text = AsyncMock(
@@ -109,8 +109,8 @@ class TestTokenManagement:
            with pytest.raises(ConnectionError, match="Token refresh failed"):
                await broker._ensure_token()

-            # Second attempt within cooldown should fail with cooldown error
-            with pytest.raises(ConnectionError, match="Token refresh on cooldown"):
+            # Second attempt within cooldown should wait then retry (and still get 403)
+            with pytest.raises(ConnectionError, match="Token refresh failed"):
                await broker._ensure_token()

        await broker.close()
--- a/tests/test_daily_review.py
+++ b/tests/test_daily_review.py
@@ -16,6 +16,10 @@ from src.evolution.daily_review import DailyReviewer
 from src.evolution.scorecard import DailyScorecard
 from src.logging.decision_logger import DecisionLogger

+from datetime import UTC, datetime
+
+TODAY = datetime.now(UTC).strftime("%Y-%m-%d")
+

@pytest.fixture
 def db_conn() -> sqlite3.Connection:
@@ -116,7 +120,7 @@ def test_generate_scorecard_market_scoped(
        exchange_code="NASDAQ",
    )

-    scorecard = reviewer.generate_scorecard("2026-02-14", "KR")
+    scorecard = reviewer.generate_scorecard(TODAY, "KR")

    assert scorecard.market == "KR"
    assert scorecard.total_decisions == 2
@@ -158,7 +162,7 @@ def test_generate_scorecard_top_winners_and_losers(
            decision_id=decision_id,
        )

-    scorecard = reviewer.generate_scorecard("2026-02-14", "KR")
+    scorecard = reviewer.generate_scorecard(TODAY, "KR")
    assert scorecard.top_winners == ["005930", "000660"]
    assert scorecard.top_losers == ["035420", "051910"]

@@ -167,7 +171,7 @@ def test_generate_scorecard_empty_day(
    db_conn: sqlite3.Connection, context_store: ContextStore,
 ) -> None:
    reviewer = DailyReviewer(db_conn, context_store)
-    scorecard = reviewer.generate_scorecard("2026-02-14", "KR")
+    scorecard = reviewer.generate_scorecard(TODAY, "KR")

    assert scorecard.total_decisions == 0
    assert scorecard.total_pnl == 0.0
--- a/tests/test_dashboard.py
+++ b/tests/test_dashboard.py
@@ -1,21 +1,25 @@
-"""Tests for FastAPI dashboard endpoints."""
+"""Tests for dashboard endpoint handlers."""

 from __future__ import annotations

 import json
 import sqlite3
+from collections.abc import Callable
+from datetime import UTC, datetime
 from pathlib import Path
+from typing import Any

 import pytest
-
-pytest.importorskip("fastapi")
-from fastapi.testclient import TestClient
+from fastapi import HTTPException
+from fastapi.responses import FileResponse

 from src.dashboard.app import create_dashboard_app
 from src.db import init_db


 def _seed_db(conn: sqlite3.Connection) -> None:
+    today = datetime.now(UTC).date().isoformat()
+
    conn.execute(
        """
        INSERT INTO playbooks (
@@ -34,6 +38,24 @@ def _seed_db(conn: sqlite3.Connection) -> None:
            1,
        ),
    )
+    conn.execute(
+        """
+        INSERT INTO playbooks (
+            date, market, status, playbook_json, generated_at,
+            token_count, scenario_count, match_count
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            today,
+            "US_NASDAQ",
+            "ready",
+            json.dumps({"market": "US_NASDAQ", "stock_playbooks": []}),
+            f"{today}T08:30:00+00:00",
+            100,
+            1,
+            0,
+        ),
+    )
    conn.execute(
        """
        INSERT INTO contexts (layer, timeframe, key, value, created_at, updated_at)
@@ -71,7 +93,7 @@ def _seed_db(conn: sqlite3.Connection) -> None:
        """,
        (
            "d-kr-1",
-            "2026-02-14T09:10:00+00:00",
+            f"{today}T09:10:00+00:00",
            "005930",
            "KR",
            "KRX",
@@ -91,9 +113,9 @@ def _seed_db(conn: sqlite3.Connection) -> None:
        """,
        (
            "d-us-1",
-            "2026-02-14T21:10:00+00:00",
+            f"{today}T21:10:00+00:00",
            "AAPL",
-            "US",
+            "US_NASDAQ",
            "NASDAQ",
            "SELL",
            80,
@@ -110,7 +132,7 @@ def _seed_db(conn: sqlite3.Connection) -> None:
        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        """,
        (
-            "2026-02-14T09:11:00+00:00",
+            f"{today}T09:11:00+00:00",
            "005930",
            "BUY",
            85,
@@ -132,7 +154,7 @@ def _seed_db(conn: sqlite3.Connection) -> None:
        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        """,
        (
-            "2026-02-14T21:11:00+00:00",
+            f"{today}T21:11:00+00:00",
            "AAPL",
            "SELL",
            80,
@@ -140,7 +162,7 @@ def _seed_db(conn: sqlite3.Connection) -> None:
            1,
            200,
            -1.0,
-            "US",
+            "US_NASDAQ",
            "NASDAQ",
            None,
            "d-us-1",
@@ -149,122 +171,128 @@ def _seed_db(conn: sqlite3.Connection) -> None:
    conn.commit()


-def _client(tmp_path: Path) -> TestClient:
+def _app(tmp_path: Path) -> Any:
    db_path = tmp_path / "dashboard_test.db"
    conn = init_db(str(db_path))
    _seed_db(conn)
    conn.close()
-    app = create_dashboard_app(str(db_path))
-    return TestClient(app)
+    return create_dashboard_app(str(db_path))
+
+
+def _endpoint(app: Any, path: str) -> Callable[..., Any]:
+    for route in app.routes:
+        if getattr(route, "path", None) == path:
+            return route.endpoint
+    raise AssertionError(f"route not found: {path}")


 def test_index_serves_html(tmp_path: Path) -> None:
-    client = _client(tmp_path)
-    resp = client.get("/")
-    assert resp.status_code == 200
-    assert "The Ouroboros Dashboard API" in resp.text
+    app = _app(tmp_path)
+    index = _endpoint(app, "/")
+    resp = index()
+    assert isinstance(resp, FileResponse)
+    assert "index.html" in str(resp.path)


 def test_status_endpoint(tmp_path: Path) -> None:
-    client = _client(tmp_path)
-    resp = client.get("/api/status")
-    assert resp.status_code == 200
-    body = resp.json()
+    app = _app(tmp_path)
+    get_status = _endpoint(app, "/api/status")
+    body = get_status()
    assert "KR" in body["markets"]
-    assert "US" in body["markets"]
+    assert "US_NASDAQ" in body["markets"]
    assert "totals" in body


 def test_playbook_found(tmp_path: Path) -> None:
-    client = _client(tmp_path)
-    resp = client.get("/api/playbook/2026-02-14?market=KR")
-    assert resp.status_code == 200
-    assert resp.json()["market"] == "KR"
+    app = _app(tmp_path)
+    get_playbook = _endpoint(app, "/api/playbook/{date_str}")
+    body = get_playbook("2026-02-14", market="KR")
+    assert body["market"] == "KR"


 def test_playbook_not_found(tmp_path: Path) -> None:
-    client = _client(tmp_path)
-    resp = client.get("/api/playbook/2026-02-15?market=KR")
-    assert resp.status_code == 404
+    app = _app(tmp_path)
+    get_playbook = _endpoint(app, "/api/playbook/{date_str}")
+    with pytest.raises(HTTPException, match="playbook not found"):
+        get_playbook("2026-02-15", market="KR")


 def test_scorecard_found(tmp_path: Path) -> None:
-    client = _client(tmp_path)
-    resp = client.get("/api/scorecard/2026-02-14?market=KR")
-    assert resp.status_code == 200
-    assert resp.json()["scorecard"]["total_pnl"] == 1.5
+    app = _app(tmp_path)
+    get_scorecard = _endpoint(app, "/api/scorecard/{date_str}")
+    body = get_scorecard("2026-02-14", market="KR")
+    assert body["scorecard"]["total_pnl"] == 1.5


 def test_scorecard_not_found(tmp_path: Path) -> None:
-    client = _client(tmp_path)
-    resp = client.get("/api/scorecard/2026-02-15?market=KR")
-    assert resp.status_code == 404
+    app = _app(tmp_path)
+    get_scorecard = _endpoint(app, "/api/scorecard/{date_str}")
+    with pytest.raises(HTTPException, match="scorecard not found"):
+        get_scorecard("2026-02-15", market="KR")


 def test_performance_all(tmp_path: Path) -> None:
-    client = _client(tmp_path)
-    resp = client.get("/api/performance?market=all")
-    assert resp.status_code == 200
-    body = resp.json()
+    app = _app(tmp_path)
+    get_performance = _endpoint(app, "/api/performance")
+    body = get_performance(market="all")
    assert body["market"] == "all"
    assert body["combined"]["total_trades"] == 2
    assert len(body["by_market"]) == 2


 def test_performance_market_filter(tmp_path: Path) -> None:
-    client = _client(tmp_path)
-    resp = client.get("/api/performance?market=KR")
-    assert resp.status_code == 200
-    body = resp.json()
+    app = _app(tmp_path)
+    get_performance = _endpoint(app, "/api/performance")
+    body = get_performance(market="KR")
    assert body["market"] == "KR"
    assert body["metrics"]["total_trades"] == 1


 def test_performance_empty_market(tmp_path: Path) -> None:
-    client = _client(tmp_path)
-    resp = client.get("/api/performance?market=JP")
-    assert resp.status_code == 200
-    assert resp.json()["metrics"]["total_trades"] == 0
+    app = _app(tmp_path)
+    get_performance = _endpoint(app, "/api/performance")
+    body = get_performance(market="JP")
+    assert body["metrics"]["total_trades"] == 0


 def test_context_layer_all(tmp_path: Path) -> None:
-    client = _client(tmp_path)
-    resp = client.get("/api/context/L7_REALTIME")
-    assert resp.status_code == 200
-    body = resp.json()
+    app = _app(tmp_path)
+    get_context_layer = _endpoint(app, "/api/context/{layer}")
+    body = get_context_layer("L7_REALTIME", timeframe=None, limit=100)
    assert body["layer"] == "L7_REALTIME"
    assert body["count"] == 1


 def test_context_layer_timeframe_filter(tmp_path: Path) -> None:
-    client = _client(tmp_path)
-    resp = client.get("/api/context/L6_DAILY?timeframe=2026-02-14")
-    assert resp.status_code == 200
-    body = resp.json()
+    app = _app(tmp_path)
+    get_context_layer = _endpoint(app, "/api/context/{layer}")
+    body = get_context_layer("L6_DAILY", timeframe="2026-02-14", limit=100)
    assert body["count"] == 1
    assert body["entries"][0]["key"] == "scorecard_KR"


 def test_decisions_endpoint(tmp_path: Path) -> None:
-    client = _client(tmp_path)
-    resp = client.get("/api/decisions?market=KR")
-    assert resp.status_code == 200
-    body = resp.json()
+    app = _app(tmp_path)
+    get_decisions = _endpoint(app, "/api/decisions")
+    body = get_decisions(market="KR", limit=50)
    assert body["count"] == 1
    assert body["decisions"][0]["decision_id"] == "d-kr-1"


 def test_scenarios_active_filters_non_matched(tmp_path: Path) -> None:
-    client = _client(tmp_path)
-    resp = client.get("/api/scenarios/active?market=KR&date_str=2026-02-14")
-    assert resp.status_code == 200
-    body = resp.json()
+    app = _app(tmp_path)
+    get_active_scenarios = _endpoint(app, "/api/scenarios/active")
+    body = get_active_scenarios(
+        market="KR",
+        date_str=datetime.now(UTC).date().isoformat(),
+        limit=50,
+    )
    assert body["count"] == 1
    assert body["matches"][0]["stock_code"] == "005930"


 def test_scenarios_active_empty_when_no_matches(tmp_path: Path) -> None:
-    client = _client(tmp_path)
-    resp = client.get("/api/scenarios/active?market=US&date_str=2026-02-14")
-    assert resp.status_code == 200
-    assert resp.json()["count"] == 0
+    app = _app(tmp_path)
+    get_active_scenarios = _endpoint(app, "/api/scenarios/active")
+    body = get_active_scenarios(market="US", date_str="2026-02-14", limit=50)
+    assert body["count"] == 0
--- a/tests/test_db.py
+++ b/tests/test_db.py
@@ -0,0 +1,60 @@
+"""Tests for database helper functions."""
+
+from src.db import get_open_position, init_db, log_trade
+
+
+def test_get_open_position_returns_latest_buy() -> None:
+    conn = init_db(":memory:")
+    log_trade(
+        conn=conn,
+        stock_code="005930",
+        action="BUY",
+        confidence=90,
+        rationale="entry",
+        quantity=2,
+        price=70000.0,
+        market="KR",
+        exchange_code="KRX",
+        decision_id="d-buy-1",
+    )
+
+    position = get_open_position(conn, "005930", "KR")
+    assert position is not None
+    assert position["decision_id"] == "d-buy-1"
+    assert position["price"] == 70000.0
+    assert position["quantity"] == 2
+
+
+def test_get_open_position_returns_none_when_latest_is_sell() -> None:
+    conn = init_db(":memory:")
+    log_trade(
+        conn=conn,
+        stock_code="005930",
+        action="BUY",
+        confidence=90,
+        rationale="entry",
+        quantity=1,
+        price=70000.0,
+        market="KR",
+        exchange_code="KRX",
+        decision_id="d-buy-1",
+    )
+    log_trade(
+        conn=conn,
+        stock_code="005930",
+        action="SELL",
+        confidence=95,
+        rationale="exit",
+        quantity=1,
+        price=71000.0,
+        market="KR",
+        exchange_code="KRX",
+        decision_id="d-sell-1",
+    )
+
+    assert get_open_position(conn, "005930", "KR") is None
+
+
+def test_get_open_position_returns_none_when_no_trades() -> None:
+    conn = init_db(":memory:")
+    assert get_open_position(conn, "AAPL", "US_NASDAQ") is None
--- a/tests/test_main.py
+++ b/tests/test_main.py
@@ -116,6 +116,7 @@ class TestTradingCycleTelegramIntegration:
                "output1": {
                    "stck_prpr": "50000",
                    "frgn_ntby_qty": "100",
+                    "prdy_ctrt": "1.23",
                }
            }
        )
@@ -737,6 +738,82 @@ class TestOverseasBalanceParsing:
        # Verify price API was called
        mock_overseas_broker_with_empty_price.get_overseas_price.assert_called_once()

+    @pytest.fixture
+    def mock_overseas_broker_with_buy_scenario(self) -> MagicMock:
+        """Create mock overseas broker that returns a valid price for BUY orders."""
+        broker = MagicMock()
+        broker.get_overseas_price = AsyncMock(
+            return_value={"output": {"last": "182.50"}}
+        )
+        broker.get_overseas_balance = AsyncMock(
+            return_value={
+                "output2": [
+                    {
+                        "frcr_evlu_tota": "100000.00",
+                        "frcr_dncl_amt_2": "50000.00",
+                        "frcr_buy_amt_smtl": "50000.00",
+                    }
+                ]
+            }
+        )
+        broker.send_overseas_order = AsyncMock(return_value={"msg1": "주문접수"})
+        return broker
+
+    @pytest.fixture
+    def mock_scenario_engine_buy(self) -> MagicMock:
+        """Create mock scenario engine that returns BUY."""
+        engine = MagicMock(spec=ScenarioEngine)
+        engine.evaluate = MagicMock(return_value=_make_buy_match("AAPL"))
+        return engine
+
+    @pytest.mark.asyncio
+    async def test_overseas_buy_order_uses_limit_price(
+        self,
+        mock_domestic_broker: MagicMock,
+        mock_overseas_broker_with_buy_scenario: MagicMock,
+        mock_scenario_engine_buy: MagicMock,
+        mock_playbook: DayPlaybook,
+        mock_risk: MagicMock,
+        mock_db: MagicMock,
+        mock_decision_logger: MagicMock,
+        mock_context_store: MagicMock,
+        mock_criticality_assessor: MagicMock,
+        mock_telegram: MagicMock,
+        mock_overseas_market: MagicMock,
+    ) -> None:
+        """Overseas BUY order must use current_price (limit), not 0 (market).
+
+        KIS VTS rejects market orders for overseas paper trading.
+        Regression test for issue #149.
+        """
+        mock_telegram.notify_trade_execution = AsyncMock()
+
+        with patch("src.main.log_trade"):
+            await trading_cycle(
+                broker=mock_domestic_broker,
+                overseas_broker=mock_overseas_broker_with_buy_scenario,
+                scenario_engine=mock_scenario_engine_buy,
+                playbook=mock_playbook,
+                risk=mock_risk,
+                db_conn=mock_db,
+                decision_logger=mock_decision_logger,
+                context_store=mock_context_store,
+                criticality_assessor=mock_criticality_assessor,
+                telegram=mock_telegram,
+                market=mock_overseas_market,
+                stock_code="AAPL",
+                scan_candidates={},
+            )
+
+        # Verify limit order was sent with actual price, not 0.0
+        mock_overseas_broker_with_buy_scenario.send_overseas_order.assert_called_once()
+        call_kwargs = mock_overseas_broker_with_buy_scenario.send_overseas_order.call_args
+        sent_price = call_kwargs[1].get("price") or call_kwargs[0][4]
+        assert sent_price == 182.5, (
+            f"Expected limit price 182.5 but got {sent_price}. "
+            "KIS VTS only accepts limit orders for overseas paper trading."
+        )
+

 class TestScenarioEngineIntegration:
    """Test scenario engine integration in trading_cycle."""
@@ -747,7 +824,7 @@ class TestScenarioEngineIntegration:
        broker = MagicMock()
        broker.get_orderbook = AsyncMock(
            return_value={
-                "output1": {"stck_prpr": "50000", "frgn_ntby_qty": "100"}
+                "output1": {"stck_prpr": "50000", "frgn_ntby_qty": "100", "prdy_ctrt": "2.50"}
            }
        )
        broker.get_balance = AsyncMock(
@@ -830,6 +907,7 @@ class TestScenarioEngineIntegration:
        assert market_data["rsi"] == 25.0
        assert market_data["volume_ratio"] == 3.5
        assert market_data["current_price"] == 50000.0
+        assert market_data["price_change_pct"] == 2.5

        # Portfolio data should include pnl
        assert "portfolio_pnl_pct" in portfolio_data
@@ -1232,6 +1310,107 @@ async def test_sell_updates_original_buy_decision_outcome() -> None:
    assert updated_buy.outcome_accuracy == 1


+@pytest.mark.asyncio
+async def test_hold_overridden_to_sell_when_stop_loss_triggered() -> None:
+    """HOLD decision should be overridden to SELL when stop-loss threshold is breached."""
+    db_conn = init_db(":memory:")
+    decision_logger = DecisionLogger(db_conn)
+
+    buy_decision_id = decision_logger.log_decision(
+        stock_code="005930",
+        market="KR",
+        exchange_code="KRX",
+        action="BUY",
+        confidence=90,
+        rationale="entry",
+        context_snapshot={},
+        input_data={},
+    )
+    log_trade(
+        conn=db_conn,
+        stock_code="005930",
+        action="BUY",
+        confidence=90,
+        rationale="entry",
+        quantity=1,
+        price=100.0,
+        market="KR",
+        exchange_code="KRX",
+        decision_id=buy_decision_id,
+    )
+
+    broker = MagicMock()
+    broker.get_orderbook = AsyncMock(
+        return_value={"output1": {"stck_prpr": "95", "frgn_ntby_qty": "0", "prdy_ctrt": "-5.0"}}
+    )
+    broker.get_balance = AsyncMock(
+        return_value={
+            "output2": [
+                {
+                    "tot_evlu_amt": "100000",
+                    "dnca_tot_amt": "10000",
+                    "pchs_amt_smtl_amt": "90000",
+                }
+            ]
+        }
+    )
+    broker.send_order = AsyncMock(return_value={"msg1": "OK"})
+
+    scenario = StockScenario(
+        condition=StockCondition(rsi_below=30),
+        action=ScenarioAction.BUY,
+        confidence=88,
+        stop_loss_pct=-2.0,
+        rationale="stop loss policy",
+    )
+    playbook = DayPlaybook(
+        date=date(2026, 2, 8),
+        market="KR",
+        stock_playbooks=[
+            {"stock_code": "005930", "stock_name": "Samsung", "scenarios": [scenario]}
+        ],
+    )
+    engine = MagicMock(spec=ScenarioEngine)
+    engine.evaluate = MagicMock(return_value=_make_hold_match())
+
+    market = MagicMock()
+    market.name = "Korea"
+    market.code = "KR"
+    market.exchange_code = "KRX"
+    market.is_domestic = True
+
+    telegram = MagicMock()
+    telegram.notify_trade_execution = AsyncMock()
+    telegram.notify_fat_finger = AsyncMock()
+    telegram.notify_circuit_breaker = AsyncMock()
+    telegram.notify_scenario_matched = AsyncMock()
+
+    await trading_cycle(
+        broker=broker,
+        overseas_broker=MagicMock(),
+        scenario_engine=engine,
+        playbook=playbook,
+        risk=MagicMock(),
+        db_conn=db_conn,
+        decision_logger=decision_logger,
+        context_store=MagicMock(
+            get_latest_timeframe=MagicMock(return_value=None),
+            set_context=MagicMock(),
+        ),
+        criticality_assessor=MagicMock(
+            assess_market_conditions=MagicMock(return_value=MagicMock(value="NORMAL")),
+            get_timeout=MagicMock(return_value=5.0),
+        ),
+        telegram=telegram,
+        market=market,
+        stock_code="005930",
+        scan_candidates={},
+    )
+
+    broker.send_order.assert_called_once()
+    assert broker.send_order.call_args.kwargs["order_type"] == "SELL"
+
+
@pytest.mark.asyncio
 async def test_handle_market_close_runs_daily_review_flow() -> None:
    """Market close should aggregate, create scorecard, lessons, and notify."""
@@ -1427,7 +1606,7 @@ async def test_run_evolution_loop_notifies_when_pr_generated() -> None:
    await _run_evolution_loop(
        evolution_optimizer=optimizer,
        telegram=telegram,
-        market_code="US",
+        market_code="US_NASDAQ",
        market_date="2026-02-14",
    )

@@ -1451,7 +1630,7 @@ async def test_run_evolution_loop_notification_error_is_ignored() -> None:
    await _run_evolution_loop(
        evolution_optimizer=optimizer,
        telegram=telegram,
-        market_code="US",
+        market_code="US_NYSE",
        market_date="2026-02-14",
    )

--- a/tests/test_market_schedule.py
+++ b/tests/test_market_schedule.py
@@ -7,6 +7,7 @@ import pytest

 from src.markets.schedule import (
    MARKETS,
+    expand_market_codes,
    get_next_market_open,
    get_open_markets,
    is_market_open,
@@ -199,3 +200,28 @@ class TestGetNextMarketOpen:
            enabled_markets=["INVALID", "KR"], now=test_time
        )
        assert market.code == "KR"
+
+
+class TestExpandMarketCodes:
+    """Test shorthand market expansion."""
+
+    def test_expand_us_shorthand(self) -> None:
+        assert expand_market_codes(["US"]) == ["US_NASDAQ", "US_NYSE", "US_AMEX"]
+
+    def test_expand_cn_shorthand(self) -> None:
+        assert expand_market_codes(["CN"]) == ["CN_SHA", "CN_SZA"]
+
+    def test_expand_vn_shorthand(self) -> None:
+        assert expand_market_codes(["VN"]) == ["VN_HAN", "VN_HCM"]
+
+    def test_expand_mixed_codes(self) -> None:
+        assert expand_market_codes(["KR", "US", "JP"]) == [
+            "KR",
+            "US_NASDAQ",
+            "US_NYSE",
+            "US_AMEX",
+            "JP",
+        ]
+
+    def test_expand_preserves_unknown_code(self) -> None:
+        assert expand_market_codes(["KR", "UNKNOWN"]) == ["KR", "UNKNOWN"]
--- a/tests/test_overseas_broker.py
+++ b/tests/test_overseas_broker.py
@@ -0,0 +1,617 @@
+"""Tests for OverseasBroker — rankings, price, balance, order, and helpers."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+import aiohttp
+import pytest
+
+from src.broker.kis_api import KISBroker
+from src.broker.overseas import OverseasBroker, _PRICE_EXCHANGE_MAP, _RANKING_EXCHANGE_MAP
+from src.config import Settings
+
+
+def _make_async_cm(mock_resp: AsyncMock) -> MagicMock:
+    """Create an async context manager that returns mock_resp on __aenter__."""
+    cm = MagicMock()
+    cm.__aenter__ = AsyncMock(return_value=mock_resp)
+    cm.__aexit__ = AsyncMock(return_value=False)
+    return cm
+
+
+@pytest.fixture
+def mock_settings() -> Settings:
+    """Provide mock settings with correct default TR_IDs/paths."""
+    return Settings(
+        KIS_APP_KEY="test_key",
+        KIS_APP_SECRET="test_secret",
+        KIS_ACCOUNT_NO="12345678-01",
+        GEMINI_API_KEY="test_gemini_key",
+    )
+
+
+@pytest.fixture
+def mock_broker(mock_settings: Settings) -> KISBroker:
+    """Provide a mock KIS broker."""
+    broker = KISBroker(mock_settings)
+    broker.get_orderbook = AsyncMock()  # type: ignore[method-assign]
+    return broker
+
+
+@pytest.fixture
+def overseas_broker(mock_broker: KISBroker) -> OverseasBroker:
+    """Provide an OverseasBroker wrapping a mock KISBroker."""
+    return OverseasBroker(mock_broker)
+
+
+def _setup_broker_mocks(overseas_broker: OverseasBroker, mock_session: MagicMock) -> None:
+    """Wire up common broker mocks."""
+    overseas_broker._broker._rate_limiter.acquire = AsyncMock()
+    overseas_broker._broker._get_session = MagicMock(return_value=mock_session)
+    overseas_broker._broker._auth_headers = AsyncMock(return_value={})
+
+
+class TestRankingExchangeMap:
+    """Test exchange code mapping for ranking API."""
+
+    def test_nasd_maps_to_nas(self) -> None:
+        assert _RANKING_EXCHANGE_MAP["NASD"] == "NAS"
+
+    def test_nyse_maps_to_nys(self) -> None:
+        assert _RANKING_EXCHANGE_MAP["NYSE"] == "NYS"
+
+    def test_amex_maps_to_ams(self) -> None:
+        assert _RANKING_EXCHANGE_MAP["AMEX"] == "AMS"
+
+    def test_sehk_maps_to_hks(self) -> None:
+        assert _RANKING_EXCHANGE_MAP["SEHK"] == "HKS"
+
+    def test_unmapped_exchange_passes_through(self) -> None:
+        assert _RANKING_EXCHANGE_MAP.get("UNKNOWN", "UNKNOWN") == "UNKNOWN"
+
+    def test_tse_unchanged(self) -> None:
+        assert _RANKING_EXCHANGE_MAP["TSE"] == "TSE"
+
+
+class TestConfigDefaults:
+    """Test that config defaults match KIS official API specs."""
+
+    def test_fluct_tr_id(self, mock_settings: Settings) -> None:
+        assert mock_settings.OVERSEAS_RANKING_FLUCT_TR_ID == "HHDFS76290000"
+
+    def test_volume_tr_id(self, mock_settings: Settings) -> None:
+        assert mock_settings.OVERSEAS_RANKING_VOLUME_TR_ID == "HHDFS76270000"
+
+    def test_fluct_path(self, mock_settings: Settings) -> None:
+        assert mock_settings.OVERSEAS_RANKING_FLUCT_PATH == "/uapi/overseas-stock/v1/ranking/updown-rate"
+
+    def test_volume_path(self, mock_settings: Settings) -> None:
+        assert mock_settings.OVERSEAS_RANKING_VOLUME_PATH == "/uapi/overseas-stock/v1/ranking/volume-surge"
+
+
+class TestFetchOverseasRankings:
+    """Test fetch_overseas_rankings method."""
+
+    @pytest.mark.asyncio
+    async def test_fluctuation_uses_correct_params(
+        self, overseas_broker: OverseasBroker
+    ) -> None:
+        """Fluctuation ranking should use HHDFS76290000, updown-rate path, and correct params."""
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(
+            return_value={"output": [{"symb": "AAPL", "name": "Apple"}]}
+        )
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=_make_async_cm(mock_resp))
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+        overseas_broker._broker._auth_headers = AsyncMock(
+            return_value={"authorization": "Bearer test"}
+        )
+
+        result = await overseas_broker.fetch_overseas_rankings("NASD", "fluctuation")
+
+        assert len(result) == 1
+        assert result[0]["symb"] == "AAPL"
+
+        call_args = mock_session.get.call_args
+        url = call_args[0][0]
+        params = call_args[1]["params"]
+
+        assert "/uapi/overseas-stock/v1/ranking/updown-rate" in url
+        assert params["EXCD"] == "NAS"
+        assert params["NDAY"] == "0"
+        assert params["GUBN"] == "1"
+        assert params["VOL_RANG"] == "0"
+
+        overseas_broker._broker._auth_headers.assert_called_with("HHDFS76290000")
+
+    @pytest.mark.asyncio
+    async def test_volume_uses_correct_params(
+        self, overseas_broker: OverseasBroker
+    ) -> None:
+        """Volume ranking should use HHDFS76270000, volume-surge path, and correct params."""
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(
+            return_value={"output": [{"symb": "TSLA", "name": "Tesla"}]}
+        )
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=_make_async_cm(mock_resp))
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+        overseas_broker._broker._auth_headers = AsyncMock(
+            return_value={"authorization": "Bearer test"}
+        )
+
+        result = await overseas_broker.fetch_overseas_rankings("NYSE", "volume")
+
+        assert len(result) == 1
+
+        call_args = mock_session.get.call_args
+        url = call_args[0][0]
+        params = call_args[1]["params"]
+
+        assert "/uapi/overseas-stock/v1/ranking/volume-surge" in url
+        assert params["EXCD"] == "NYS"
+        assert params["MIXN"] == "0"
+        assert params["VOL_RANG"] == "0"
+        assert "NDAY" not in params
+        assert "GUBN" not in params
+
+        overseas_broker._broker._auth_headers.assert_called_with("HHDFS76270000")
+
+    @pytest.mark.asyncio
+    async def test_404_returns_empty_list(
+        self, overseas_broker: OverseasBroker
+    ) -> None:
+        """HTTP 404 should return empty list (fallback) instead of raising."""
+        mock_resp = AsyncMock()
+        mock_resp.status = 404
+        mock_resp.text = AsyncMock(return_value="Not Found")
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=_make_async_cm(mock_resp))
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+
+        result = await overseas_broker.fetch_overseas_rankings("AMEX", "fluctuation")
+        assert result == []
+
+    @pytest.mark.asyncio
+    async def test_non_404_error_raises(
+        self, overseas_broker: OverseasBroker
+    ) -> None:
+        """Non-404 HTTP errors should raise ConnectionError."""
+        mock_resp = AsyncMock()
+        mock_resp.status = 500
+        mock_resp.text = AsyncMock(return_value="Internal Server Error")
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=_make_async_cm(mock_resp))
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+
+        with pytest.raises(ConnectionError, match="500"):
+            await overseas_broker.fetch_overseas_rankings("NASD")
+
+    @pytest.mark.asyncio
+    async def test_empty_response_returns_empty(
+        self, overseas_broker: OverseasBroker
+    ) -> None:
+        """Empty output in response should return empty list."""
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"output": []})
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=_make_async_cm(mock_resp))
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+
+        result = await overseas_broker.fetch_overseas_rankings("NASD")
+        assert result == []
+
+    @pytest.mark.asyncio
+    async def test_ranking_disabled_returns_empty(
+        self, overseas_broker: OverseasBroker
+    ) -> None:
+        """When OVERSEAS_RANKING_ENABLED=False, should return empty immediately."""
+        overseas_broker._broker._settings.OVERSEAS_RANKING_ENABLED = False
+        result = await overseas_broker.fetch_overseas_rankings("NASD")
+        assert result == []
+
+    @pytest.mark.asyncio
+    async def test_limit_truncates_results(
+        self, overseas_broker: OverseasBroker
+    ) -> None:
+        """Results should be truncated to the specified limit."""
+        rows = [{"symb": f"SYM{i}"} for i in range(20)]
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"output": rows})
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=_make_async_cm(mock_resp))
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+
+        result = await overseas_broker.fetch_overseas_rankings("NASD", limit=5)
+        assert len(result) == 5
+
+    @pytest.mark.asyncio
+    async def test_network_error_raises(
+        self, overseas_broker: OverseasBroker
+    ) -> None:
+        """Network errors should raise ConnectionError."""
+        cm = MagicMock()
+        cm.__aenter__ = AsyncMock(side_effect=aiohttp.ClientError("timeout"))
+        cm.__aexit__ = AsyncMock(return_value=False)
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=cm)
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+
+        with pytest.raises(ConnectionError, match="Network error"):
+            await overseas_broker.fetch_overseas_rankings("NASD")
+
+    @pytest.mark.asyncio
+    async def test_exchange_code_mapping_applied(
+        self, overseas_broker: OverseasBroker
+    ) -> None:
+        """All major exchanges should use mapped codes in API params."""
+        for original, mapped in [("NASD", "NAS"), ("NYSE", "NYS"), ("AMEX", "AMS")]:
+            mock_resp = AsyncMock()
+            mock_resp.status = 200
+            mock_resp.json = AsyncMock(return_value={"output": [{"symb": "X"}]})
+
+            mock_session = MagicMock()
+            mock_session.get = MagicMock(return_value=_make_async_cm(mock_resp))
+
+            _setup_broker_mocks(overseas_broker, mock_session)
+
+            await overseas_broker.fetch_overseas_rankings(original)
+
+            call_params = mock_session.get.call_args[1]["params"]
+            assert call_params["EXCD"] == mapped, f"{original} should map to {mapped}"
+
+
+class TestGetOverseasPrice:
+    """Test get_overseas_price method."""
+
+    @pytest.mark.asyncio
+    async def test_success(self, overseas_broker: OverseasBroker) -> None:
+        """Successful price fetch returns JSON data."""
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"output": {"last": "150.00"}})
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=_make_async_cm(mock_resp))
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+        overseas_broker._broker._auth_headers = AsyncMock(return_value={"authorization": "Bearer t"})
+
+        result = await overseas_broker.get_overseas_price("NASD", "AAPL")
+        assert result["output"]["last"] == "150.00"
+
+        call_args = mock_session.get.call_args
+        params = call_args[1]["params"]
+        # NASD is mapped to NAS for the price inquiry API (same as ranking API).
+        assert params["EXCD"] == "NAS"
+        assert params["SYMB"] == "AAPL"
+
+    @pytest.mark.asyncio
+    async def test_http_error_raises(self, overseas_broker: OverseasBroker) -> None:
+        """Non-200 response should raise ConnectionError."""
+        mock_resp = AsyncMock()
+        mock_resp.status = 400
+        mock_resp.text = AsyncMock(return_value="Bad Request")
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=_make_async_cm(mock_resp))
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+
+        with pytest.raises(ConnectionError, match="get_overseas_price failed"):
+            await overseas_broker.get_overseas_price("NASD", "AAPL")
+
+    @pytest.mark.asyncio
+    async def test_network_error_raises(self, overseas_broker: OverseasBroker) -> None:
+        """Network error should raise ConnectionError."""
+        cm = MagicMock()
+        cm.__aenter__ = AsyncMock(side_effect=aiohttp.ClientError("conn refused"))
+        cm.__aexit__ = AsyncMock(return_value=False)
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=cm)
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+
+        with pytest.raises(ConnectionError, match="Network error"):
+            await overseas_broker.get_overseas_price("NASD", "AAPL")
+
+
+class TestGetOverseasBalance:
+    """Test get_overseas_balance method."""
+
+    @pytest.mark.asyncio
+    async def test_success(self, overseas_broker: OverseasBroker) -> None:
+        """Successful balance fetch returns JSON data."""
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"output1": [{"pdno": "AAPL"}]})
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=_make_async_cm(mock_resp))
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+
+        result = await overseas_broker.get_overseas_balance("NASD")
+        assert result["output1"][0]["pdno"] == "AAPL"
+
+    @pytest.mark.asyncio
+    async def test_http_error_raises(self, overseas_broker: OverseasBroker) -> None:
+        """Non-200 should raise ConnectionError."""
+        mock_resp = AsyncMock()
+        mock_resp.status = 500
+        mock_resp.text = AsyncMock(return_value="Server Error")
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=_make_async_cm(mock_resp))
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+
+        with pytest.raises(ConnectionError, match="get_overseas_balance failed"):
+            await overseas_broker.get_overseas_balance("NASD")
+
+    @pytest.mark.asyncio
+    async def test_network_error_raises(self, overseas_broker: OverseasBroker) -> None:
+        """Network error should raise ConnectionError."""
+        cm = MagicMock()
+        cm.__aenter__ = AsyncMock(side_effect=TimeoutError("timeout"))
+        cm.__aexit__ = AsyncMock(return_value=False)
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=cm)
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+
+        with pytest.raises(ConnectionError, match="Network error"):
+            await overseas_broker.get_overseas_balance("NYSE")
+
+
+class TestSendOverseasOrder:
+    """Test send_overseas_order method."""
+
+    @pytest.mark.asyncio
+    async def test_buy_market_order(self, overseas_broker: OverseasBroker) -> None:
+        """Market buy order should use VTTT1002U and ORD_DVSN=01."""
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"rt_cd": "0"})
+
+        mock_session = MagicMock()
+        mock_session.post = MagicMock(return_value=_make_async_cm(mock_resp))
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+        overseas_broker._broker._get_hash_key = AsyncMock(return_value="hashval")
+
+        result = await overseas_broker.send_overseas_order("NASD", "AAPL", "BUY", 10)
+        assert result["rt_cd"] == "0"
+
+        # Verify BUY TR_ID
+        overseas_broker._broker._auth_headers.assert_called_with("VTTT1002U")
+
+        call_args = mock_session.post.call_args
+        body = call_args[1]["json"]
+        assert body["ORD_DVSN"] == "01"  # market order
+        assert body["OVRS_ORD_UNPR"] == "0"
+
+    @pytest.mark.asyncio
+    async def test_sell_limit_order(self, overseas_broker: OverseasBroker) -> None:
+        """Limit sell order should use VTTT1006U and ORD_DVSN=00."""
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"rt_cd": "0"})
+
+        mock_session = MagicMock()
+        mock_session.post = MagicMock(return_value=_make_async_cm(mock_resp))
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+        overseas_broker._broker._get_hash_key = AsyncMock(return_value="hashval")
+
+        result = await overseas_broker.send_overseas_order("NYSE", "MSFT", "SELL", 5, price=350.0)
+        assert result["rt_cd"] == "0"
+
+        overseas_broker._broker._auth_headers.assert_called_with("VTTT1006U")
+
+        call_args = mock_session.post.call_args
+        body = call_args[1]["json"]
+        assert body["ORD_DVSN"] == "00"  # limit order
+        assert body["OVRS_ORD_UNPR"] == "350.0"
+
+    @pytest.mark.asyncio
+    async def test_order_http_error_raises(self, overseas_broker: OverseasBroker) -> None:
+        """Non-200 should raise ConnectionError."""
+        mock_resp = AsyncMock()
+        mock_resp.status = 400
+        mock_resp.text = AsyncMock(return_value="Bad Request")
+
+        mock_session = MagicMock()
+        mock_session.post = MagicMock(return_value=_make_async_cm(mock_resp))
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+        overseas_broker._broker._get_hash_key = AsyncMock(return_value="hashval")
+
+        with pytest.raises(ConnectionError, match="send_overseas_order failed"):
+            await overseas_broker.send_overseas_order("NASD", "AAPL", "BUY", 1)
+
+    @pytest.mark.asyncio
+    async def test_order_network_error_raises(self, overseas_broker: OverseasBroker) -> None:
+        """Network error should raise ConnectionError."""
+        cm = MagicMock()
+        cm.__aenter__ = AsyncMock(side_effect=aiohttp.ClientError("conn reset"))
+        cm.__aexit__ = AsyncMock(return_value=False)
+
+        mock_session = MagicMock()
+        mock_session.post = MagicMock(return_value=cm)
+
+        _setup_broker_mocks(overseas_broker, mock_session)
+        overseas_broker._broker._get_hash_key = AsyncMock(return_value="hashval")
+
+        with pytest.raises(ConnectionError, match="Network error"):
+            await overseas_broker.send_overseas_order("NASD", "TSLA", "SELL", 2)
+
+
+class TestGetCurrencyCode:
+    """Test _get_currency_code mapping."""
+
+    def test_us_exchanges(self, overseas_broker: OverseasBroker) -> None:
+        assert overseas_broker._get_currency_code("NASD") == "USD"
+        assert overseas_broker._get_currency_code("NYSE") == "USD"
+        assert overseas_broker._get_currency_code("AMEX") == "USD"
+
+    def test_japan(self, overseas_broker: OverseasBroker) -> None:
+        assert overseas_broker._get_currency_code("TSE") == "JPY"
+
+    def test_hong_kong(self, overseas_broker: OverseasBroker) -> None:
+        assert overseas_broker._get_currency_code("SEHK") == "HKD"
+
+    def test_china(self, overseas_broker: OverseasBroker) -> None:
+        assert overseas_broker._get_currency_code("SHAA") == "CNY"
+        assert overseas_broker._get_currency_code("SZAA") == "CNY"
+
+    def test_vietnam(self, overseas_broker: OverseasBroker) -> None:
+        assert overseas_broker._get_currency_code("HNX") == "VND"
+        assert overseas_broker._get_currency_code("HSX") == "VND"
+
+    def test_unknown_defaults_usd(self, overseas_broker: OverseasBroker) -> None:
+        assert overseas_broker._get_currency_code("UNKNOWN") == "USD"
+
+
+class TestExtractRankingRows:
+    """Test _extract_ranking_rows helper."""
+
+    def test_output_key(self, overseas_broker: OverseasBroker) -> None:
+        data = {"output": [{"a": 1}, {"b": 2}]}
+        assert overseas_broker._extract_ranking_rows(data) == [{"a": 1}, {"b": 2}]
+
+    def test_output1_key(self, overseas_broker: OverseasBroker) -> None:
+        data = {"output1": [{"c": 3}]}
+        assert overseas_broker._extract_ranking_rows(data) == [{"c": 3}]
+
+    def test_output2_key(self, overseas_broker: OverseasBroker) -> None:
+        data = {"output2": [{"d": 4}]}
+        assert overseas_broker._extract_ranking_rows(data) == [{"d": 4}]
+
+    def test_no_list_returns_empty(self, overseas_broker: OverseasBroker) -> None:
+        data = {"output": "not a list"}
+        assert overseas_broker._extract_ranking_rows(data) == []
+
+    def test_empty_data(self, overseas_broker: OverseasBroker) -> None:
+        assert overseas_broker._extract_ranking_rows({}) == []
+
+    def test_filters_non_dict_rows(self, overseas_broker: OverseasBroker) -> None:
+        data = {"output": [{"a": 1}, "invalid", {"b": 2}]}
+        assert overseas_broker._extract_ranking_rows(data) == [{"a": 1}, {"b": 2}]
+
+
+# ---------------------------------------------------------------------------
+# Price exchange code mapping
+# ---------------------------------------------------------------------------
+
+
+class TestPriceExchangeMap:
+    """Test that get_overseas_price uses the short exchange codes."""
+
+    def test_price_map_equals_ranking_map(self) -> None:
+        assert _PRICE_EXCHANGE_MAP is _RANKING_EXCHANGE_MAP
+
+    def test_nasd_maps_to_nas(self) -> None:
+        assert _PRICE_EXCHANGE_MAP["NASD"] == "NAS"
+
+    def test_amex_maps_to_ams(self) -> None:
+        assert _PRICE_EXCHANGE_MAP["AMEX"] == "AMS"
+
+    def test_nyse_maps_to_nys(self) -> None:
+        assert _PRICE_EXCHANGE_MAP["NYSE"] == "NYS"
+
+    @pytest.mark.asyncio
+    async def test_get_overseas_price_uses_mapped_excd(
+        self, overseas_broker: OverseasBroker
+    ) -> None:
+        """AMEX should be sent as AMS to the price API."""
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"output": {"last": "44.30"}})
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=_make_async_cm(mock_resp))
+        _setup_broker_mocks(overseas_broker, mock_session)
+        overseas_broker._broker._auth_headers = AsyncMock(return_value={})
+
+        await overseas_broker.get_overseas_price("AMEX", "EWUS")
+
+        params = mock_session.get.call_args[1]["params"]
+        assert params["EXCD"] == "AMS"  # mapped, not raw "AMEX"
+        assert params["SYMB"] == "EWUS"
+
+    @pytest.mark.asyncio
+    async def test_get_overseas_price_nasd_uses_nas(
+        self, overseas_broker: OverseasBroker
+    ) -> None:
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"output": {"last": "220.00"}})
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=_make_async_cm(mock_resp))
+        _setup_broker_mocks(overseas_broker, mock_session)
+        overseas_broker._broker._auth_headers = AsyncMock(return_value={})
+
+        await overseas_broker.get_overseas_price("NASD", "AAPL")
+
+        params = mock_session.get.call_args[1]["params"]
+        assert params["EXCD"] == "NAS"
+
+
+# ---------------------------------------------------------------------------
+# PAPER_OVERSEAS_CASH config default
+# ---------------------------------------------------------------------------
+
+
+class TestPaperOverseasCash:
+    def test_default_value(self) -> None:
+        settings = Settings(
+            KIS_APP_KEY="x",
+            KIS_APP_SECRET="x",
+            KIS_ACCOUNT_NO="12345678-01",
+            GEMINI_API_KEY="x",
+        )
+        assert settings.PAPER_OVERSEAS_CASH == 50000.0
+
+    def test_can_be_set_via_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("PAPER_OVERSEAS_CASH", "100000.0")
+        settings = Settings(
+            KIS_APP_KEY="x",
+            KIS_APP_SECRET="x",
+            KIS_ACCOUNT_NO="12345678-01",
+            GEMINI_API_KEY="x",
+        )
+        assert settings.PAPER_OVERSEAS_CASH == 100000.0
+
+    def test_zero_disables_fallback(self) -> None:
+        settings = Settings(
+            KIS_APP_KEY="x",
+            KIS_APP_SECRET="x",
+            KIS_ACCOUNT_NO="12345678-01",
+            GEMINI_API_KEY="x",
+            PAPER_OVERSEAS_CASH=0.0,
+        )
+        assert settings.PAPER_OVERSEAS_CASH == 0.0
--- a/tests/test_pre_market_planner.py
+++ b/tests/test_pre_market_planner.py
@@ -164,18 +164,23 @@ class TestGeneratePlaybook:
        assert pb.market_outlook == MarketOutlook.NEUTRAL

    @pytest.mark.asyncio
-    async def test_gemini_failure_returns_defensive(self) -> None:
+    async def test_gemini_failure_returns_smart_fallback(self) -> None:
        planner = _make_planner()
        planner._gemini.decide = AsyncMock(side_effect=RuntimeError("API timeout"))
+        # oversold candidate (signal="oversold", rsi=28.5)
        candidates = [_candidate()]

        pb = await planner.generate_playbook("KR", candidates, today=date(2026, 2, 8))

        assert pb.default_action == ScenarioAction.HOLD
-        assert pb.market_outlook == MarketOutlook.NEUTRAL_TO_BEARISH
+        # Smart fallback uses NEUTRAL outlook (not NEUTRAL_TO_BEARISH)
+        assert pb.market_outlook == MarketOutlook.NEUTRAL
        assert pb.stock_count == 1
-        # Defensive playbook has stop-loss scenarios
-        assert pb.stock_playbooks[0].scenarios[0].action == ScenarioAction.SELL
+        # Oversold candidate → first scenario is BUY, second is SELL stop-loss
+        scenarios = pb.stock_playbooks[0].scenarios
+        assert scenarios[0].action == ScenarioAction.BUY
+        assert scenarios[0].condition.rsi_below == 30
+        assert scenarios[1].action == ScenarioAction.SELL

    @pytest.mark.asyncio
    async def test_gemini_failure_empty_when_defensive_disabled(self) -> None:
@@ -657,3 +662,171 @@ class TestDefensivePlaybook:
        assert pb.stock_count == 0
        assert pb.market == "US"
        assert pb.market_outlook == MarketOutlook.NEUTRAL
+
+
+# ---------------------------------------------------------------------------
+# Smart fallback playbook
+# ---------------------------------------------------------------------------
+
+
+class TestSmartFallbackPlaybook:
+    """Tests for _smart_fallback_playbook — rule-based BUY/SELL on Gemini failure."""
+
+    def _make_settings(self) -> Settings:
+        return Settings(
+            KIS_APP_KEY="test",
+            KIS_APP_SECRET="test",
+            KIS_ACCOUNT_NO="12345678-01",
+            GEMINI_API_KEY="test",
+            RSI_OVERSOLD_THRESHOLD=30,
+            VOL_MULTIPLIER=2.0,
+        )
+
+    def test_momentum_candidate_gets_buy_on_volume(self) -> None:
+        candidates = [
+            _candidate(code="CHOW", signal="momentum", volume_ratio=13.64, rsi=100.0)
+        ]
+        settings = self._make_settings()
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "US_AMEX", candidates, settings
+        )
+
+        assert pb.stock_count == 1
+        sp = pb.stock_playbooks[0]
+        assert sp.stock_code == "CHOW"
+        # First scenario: BUY with volume_ratio_above
+        buy_sc = sp.scenarios[0]
+        assert buy_sc.action == ScenarioAction.BUY
+        assert buy_sc.condition.volume_ratio_above == 2.0
+        assert buy_sc.condition.rsi_below is None
+        assert buy_sc.confidence == 80
+        # Second scenario: stop-loss SELL
+        sell_sc = sp.scenarios[1]
+        assert sell_sc.action == ScenarioAction.SELL
+        assert sell_sc.condition.price_change_pct_below == -3.0
+
+    def test_oversold_candidate_gets_buy_on_rsi(self) -> None:
+        candidates = [
+            _candidate(code="005930", signal="oversold", rsi=22.0, volume_ratio=3.5)
+        ]
+        settings = self._make_settings()
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "KR", candidates, settings
+        )
+
+        sp = pb.stock_playbooks[0]
+        buy_sc = sp.scenarios[0]
+        assert buy_sc.action == ScenarioAction.BUY
+        assert buy_sc.condition.rsi_below == 30
+        assert buy_sc.condition.volume_ratio_above is None
+
+    def test_all_candidates_have_stop_loss_sell(self) -> None:
+        candidates = [
+            _candidate(code="AAA", signal="momentum", volume_ratio=5.0),
+            _candidate(code="BBB", signal="oversold", rsi=25.0),
+        ]
+        settings = self._make_settings()
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "US_NASDAQ", candidates, settings
+        )
+
+        assert pb.stock_count == 2
+        for sp in pb.stock_playbooks:
+            sell_scenarios = [s for s in sp.scenarios if s.action == ScenarioAction.SELL]
+            assert len(sell_scenarios) == 1
+            assert sell_scenarios[0].condition.price_change_pct_below == -3.0
+            assert sell_scenarios[0].condition.price_change_pct_below == -3.0
+
+    def test_market_outlook_is_neutral(self) -> None:
+        candidates = [_candidate(signal="momentum", volume_ratio=5.0)]
+        settings = self._make_settings()
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "US_AMEX", candidates, settings
+        )
+
+        assert pb.market_outlook == MarketOutlook.NEUTRAL
+
+    def test_default_action_is_hold(self) -> None:
+        candidates = [_candidate(signal="momentum", volume_ratio=5.0)]
+        settings = self._make_settings()
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "US_AMEX", candidates, settings
+        )
+
+        assert pb.default_action == ScenarioAction.HOLD
+
+    def test_has_global_reduce_all_rule(self) -> None:
+        candidates = [_candidate(signal="momentum", volume_ratio=5.0)]
+        settings = self._make_settings()
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "US_AMEX", candidates, settings
+        )
+
+        assert len(pb.global_rules) == 1
+        rule = pb.global_rules[0]
+        assert rule.action == ScenarioAction.REDUCE_ALL
+        assert "portfolio_pnl_pct" in rule.condition
+
+    def test_empty_candidates_returns_empty_playbook(self) -> None:
+        settings = self._make_settings()
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "US_AMEX", [], settings
+        )
+
+        assert pb.stock_count == 0
+
+    def test_vol_multiplier_applied_from_settings(self) -> None:
+        """VOL_MULTIPLIER=3.0 should set volume_ratio_above=3.0 for momentum."""
+        candidates = [_candidate(signal="momentum", volume_ratio=5.0)]
+        settings = self._make_settings()
+        settings = settings.model_copy(update={"VOL_MULTIPLIER": 3.0})
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "US_AMEX", candidates, settings
+        )
+
+        buy_sc = pb.stock_playbooks[0].scenarios[0]
+        assert buy_sc.condition.volume_ratio_above == 3.0
+
+    def test_rsi_oversold_threshold_applied_from_settings(self) -> None:
+        """RSI_OVERSOLD_THRESHOLD=25 should set rsi_below=25 for oversold."""
+        candidates = [_candidate(signal="oversold", rsi=22.0)]
+        settings = self._make_settings()
+        settings = settings.model_copy(update={"RSI_OVERSOLD_THRESHOLD": 25})
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "KR", candidates, settings
+        )
+
+        buy_sc = pb.stock_playbooks[0].scenarios[0]
+        assert buy_sc.condition.rsi_below == 25
+
+    @pytest.mark.asyncio
+    async def test_generate_playbook_uses_smart_fallback_on_gemini_error(self) -> None:
+        """generate_playbook() should use smart fallback (not defensive) on API failure."""
+        planner = _make_planner()
+        planner._gemini.decide = AsyncMock(side_effect=ConnectionError("429 quota exceeded"))
+        # momentum candidate
+        candidates = [
+            _candidate(code="CHOW", signal="momentum", volume_ratio=13.64, rsi=100.0)
+        ]
+
+        pb = await planner.generate_playbook(
+            "US_AMEX", candidates, today=date(2026, 2, 18)
+        )
+
+        # Should NOT be all-SELL defensive; should have BUY for momentum
+        assert pb.stock_count == 1
+        buy_scenarios = [
+            s for s in pb.stock_playbooks[0].scenarios
+            if s.action == ScenarioAction.BUY
+        ]
+        assert len(buy_scenarios) == 1
+        assert buy_scenarios[0].condition.volume_ratio_above == 2.0  # VOL_MULTIPLIER default
--- a/tests/test_smart_scanner.py
+++ b/tests/test_smart_scanner.py
@@ -8,6 +8,7 @@ from unittest.mock import AsyncMock, MagicMock
 from src.analysis.smart_scanner import ScanCandidate, SmartVolatilityScanner
 from src.analysis.volatility import VolatilityAnalyzer
 from src.broker.kis_api import KISBroker
+from src.broker.overseas import OverseasBroker
 from src.config import Settings


@@ -43,61 +44,70 @@ def scanner(mock_broker: MagicMock, mock_settings: Settings) -> SmartVolatilityS
    analyzer = VolatilityAnalyzer()
    return SmartVolatilityScanner(
        broker=mock_broker,
+        overseas_broker=None,
        volatility_analyzer=analyzer,
        settings=mock_settings,
    )


+@pytest.fixture
+def mock_overseas_broker() -> MagicMock:
+    """Create mock overseas broker."""
+    broker = MagicMock(spec=OverseasBroker)
+    broker.get_overseas_price = AsyncMock()
+    broker.fetch_overseas_rankings = AsyncMock(return_value=[])
+    return broker
+
+
 class TestSmartVolatilityScanner:
    """Test suite for SmartVolatilityScanner."""

    @pytest.mark.asyncio
-    async def test_scan_finds_oversold_candidates(
+    async def test_scan_domestic_prefers_volatility_with_liquidity_bonus(
        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
    ) -> None:
-        """Test that scanner identifies oversold stocks with high volume."""
-        # Mock rankings
-        mock_broker.fetch_market_rankings.return_value = [
+        """Domestic scan should score by volatility first and volume rank second."""
+        fluctuation_rows = [
            {
                "stock_code": "005930",
                "name": "Samsung",
                "price": 70000,
                "volume": 5000000,
-                "change_rate": -3.5,
+                "change_rate": -5.0,
                "volume_increase_rate": 250,
            },
+            {
+                "stock_code": "035420",
+                "name": "NAVER",
+                "price": 250000,
+                "volume": 3000000,
+                "change_rate": 3.0,
+                "volume_increase_rate": 200,
+            },
+        ]
+        volume_rows = [
+            {"stock_code": "035420", "name": "NAVER", "price": 250000, "volume": 3000000},
+            {"stock_code": "005930", "name": "Samsung", "price": 70000, "volume": 5000000},
+        ]
+        mock_broker.fetch_market_rankings.side_effect = [fluctuation_rows, volume_rows]
+        mock_broker.get_daily_prices.return_value = [
+            {"open": 1, "high": 1, "low": 1, "close": 1, "volume": 1000000},
+            {"open": 1, "high": 1, "low": 1, "close": 1, "volume": 1000000},
        ]
-
-        # Mock daily prices - trending down (oversold)
-        prices = []
-        for i in range(20):
-            prices.append({
-                "date": f"2026020{i:02d}",
-                "open": 75000 - i * 200,
-                "high": 75500 - i * 200,
-                "low": 74500 - i * 200,
-                "close": 75000 - i * 250,  # Steady decline
-                "volume": 2000000,
-            })
-        mock_broker.get_daily_prices.return_value = prices

        candidates = await scanner.scan()

-        # Should find at least one candidate (depending on exact RSI calculation)
-        mock_broker.fetch_market_rankings.assert_called_once()
-        mock_broker.get_daily_prices.assert_called_once_with("005930", days=20)
-
-        # If qualified, should have oversold signal
-        if candidates:
-            assert candidates[0].signal in ["oversold", "momentum"]
-            assert candidates[0].volume_ratio >= scanner.vol_multiplier
+        assert len(candidates) >= 1
+        # Samsung has higher absolute move, so it should lead despite lower volume rank bonus.
+        assert candidates[0].stock_code == "005930"
+        assert candidates[0].signal == "oversold"

    @pytest.mark.asyncio
-    async def test_scan_finds_momentum_candidates(
+    async def test_scan_domestic_finds_momentum_candidate(
        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
    ) -> None:
-        """Test that scanner identifies momentum stocks with high volume."""
-        mock_broker.fetch_market_rankings.return_value = [
+        """Positive change should be represented as momentum signal."""
+        fluctuation_rows = [
            {
                "stock_code": "035420",
                "name": "NAVER",
@@ -107,124 +117,67 @@ class TestSmartVolatilityScanner:
                "volume_increase_rate": 300,
            },
        ]
-
-        # Mock daily prices - trending up (momentum)
-        prices = []
-        for i in range(20):
-            prices.append({
-                "date": f"2026020{i:02d}",
-                "open": 230000 + i * 500,
-                "high": 231000 + i * 500,
-                "low": 229000 + i * 500,
-                "close": 230500 + i * 500,  # Steady rise
-                "volume": 1000000,
-            })
-        mock_broker.get_daily_prices.return_value = prices
+        mock_broker.fetch_market_rankings.side_effect = [fluctuation_rows, fluctuation_rows]
+        mock_broker.get_daily_prices.return_value = [
+            {"open": 1, "high": 1, "low": 1, "close": 1, "volume": 1000000},
+            {"open": 1, "high": 1, "low": 1, "close": 1, "volume": 1000000},
+        ]

        candidates = await scanner.scan()

-        mock_broker.fetch_market_rankings.assert_called_once()
+        assert [c.stock_code for c in candidates] == ["035420"]
+        assert candidates[0].signal == "momentum"

    @pytest.mark.asyncio
-    async def test_scan_filters_low_volume(
+    async def test_scan_domestic_filters_low_volatility(
        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
    ) -> None:
-        """Test that stocks with low volume ratio are filtered out."""
-        mock_broker.fetch_market_rankings.return_value = [
+        """Domestic scan should drop symbols below volatility threshold."""
+        fluctuation_rows = [
            {
                "stock_code": "000660",
                "name": "SK Hynix",
                "price": 150000,
                "volume": 500000,
-                "change_rate": -5.0,
-                "volume_increase_rate": 50,  # Only 50% increase (< 200%)
+                "change_rate": 0.2,
+                "volume_increase_rate": 50,
            },
        ]
-
-        # Low volume
-        prices = []
-        for i in range(20):
-            prices.append({
-                "date": f"2026020{i:02d}",
-                "open": 150000 - i * 100,
-                "high": 151000 - i * 100,
-                "low": 149000 - i * 100,
-                "close": 150000 - i * 150,  # Declining (would be oversold)
-                "volume": 1000000,  # Current 500k < 2x prev day 1M
-            })
-        mock_broker.get_daily_prices.return_value = prices
+        mock_broker.fetch_market_rankings.side_effect = [fluctuation_rows, fluctuation_rows]
+        mock_broker.get_daily_prices.return_value = [
+            {"open": 1, "high": 150100, "low": 149900, "close": 150000, "volume": 1000000},
+            {"open": 1, "high": 150100, "low": 149900, "close": 150000, "volume": 1000000},
+        ]

        candidates = await scanner.scan()

-        # Should be filtered out due to low volume ratio
-        assert len(candidates) == 0
-
-    @pytest.mark.asyncio
-    async def test_scan_filters_neutral_rsi(
-        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
-    ) -> None:
-        """Test that stocks with neutral RSI are filtered out."""
-        mock_broker.fetch_market_rankings.return_value = [
-            {
-                "stock_code": "051910",
-                "name": "LG Chem",
-                "price": 500000,
-                "volume": 3000000,
-                "change_rate": 0.5,
-                "volume_increase_rate": 300,  # High volume
-            },
-        ]
-
-        # Flat prices (neutral RSI ~50)
-        prices = []
-        for i in range(20):
-            prices.append({
-                "date": f"2026020{i:02d}",
-                "open": 500000 + (i % 2) * 100,  # Small oscillation
-                "high": 500500,
-                "low": 499500,
-                "close": 500000 + (i % 2) * 50,
-                "volume": 1000000,
-            })
-        mock_broker.get_daily_prices.return_value = prices
-
-        candidates = await scanner.scan()
-
-        # Should be filtered out (RSI ~50, not < 30 or > 70)
        assert len(candidates) == 0

    @pytest.mark.asyncio
    async def test_scan_uses_fallback_on_api_error(
        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
    ) -> None:
-        """Test fallback to static list when ranking API fails."""
-        mock_broker.fetch_market_rankings.side_effect = ConnectionError("API unavailable")
-
-        # Fallback stocks should still be analyzed
-        prices = []
-        for i in range(20):
-            prices.append({
-                "date": f"2026020{i:02d}",
-                "open": 50000 - i * 50,
-                "high": 51000 - i * 50,
-                "low": 49000 - i * 50,
-                "close": 50000 - i * 75,  # Declining
-                "volume": 1000000,
-            })
-        mock_broker.get_daily_prices.return_value = prices
+        """Domestic scan should remain operational using fallback symbols."""
+        mock_broker.fetch_market_rankings.side_effect = [
+            ConnectionError("API unavailable"),
+            ConnectionError("API unavailable"),
+        ]
+        mock_broker.get_daily_prices.return_value = [
+            {"open": 1, "high": 103, "low": 97, "close": 100, "volume": 1000000},
+            {"open": 1, "high": 103, "low": 97, "close": 100, "volume": 800000},
+        ]

        candidates = await scanner.scan(fallback_stocks=["005930", "000660"])

-        # Should not crash
        assert isinstance(candidates, list)
+        assert len(candidates) >= 1

    @pytest.mark.asyncio
    async def test_scan_returns_top_n_only(
        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
    ) -> None:
        """Test that scan returns at most top_n candidates."""
-        # Return many stocks
-        mock_broker.fetch_market_rankings.return_value = [
+        fluctuation_rows = [
            {
                "stock_code": f"00{i}000",
                "name": f"Stock{i}",
@@ -235,62 +188,17 @@ class TestSmartVolatilityScanner:
            }
            for i in range(1, 10)
        ]
-
-        # All oversold with high volume
-        def make_prices(code: str) -> list[dict]:
-            prices = []
-            for i in range(20):
-                prices.append({
-                    "date": f"2026020{i:02d}",
-                    "open": 10000 - i * 100,
-                    "high": 10500 - i * 100,
-                    "low": 9500 - i * 100,
-                    "close": 10000 - i * 150,
-                    "volume": 1000000,
-                })
-            return prices
-
-        mock_broker.get_daily_prices.side_effect = make_prices
+        mock_broker.fetch_market_rankings.side_effect = [fluctuation_rows, fluctuation_rows]
+        mock_broker.get_daily_prices.return_value = [
+            {"open": 1, "high": 105, "low": 95, "close": 100, "volume": 1000000},
+            {"open": 1, "high": 105, "low": 95, "close": 100, "volume": 900000},
+        ]

        candidates = await scanner.scan()

        # Should respect top_n limit (3)
        assert len(candidates) <= scanner.top_n

-    @pytest.mark.asyncio
-    async def test_scan_skips_insufficient_price_history(
-        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
-    ) -> None:
-        """Test that stocks with insufficient history are skipped."""
-        mock_broker.fetch_market_rankings.return_value = [
-            {
-                "stock_code": "005930",
-                "name": "Samsung",
-                "price": 70000,
-                "volume": 5000000,
-                "change_rate": -5.0,
-                "volume_increase_rate": 300,
-            },
-        ]
-
-        # Only 5 days of data (need 15+ for RSI)
-        mock_broker.get_daily_prices.return_value = [
-            {
-                "date": f"2026020{i:02d}",
-                "open": 70000,
-                "high": 71000,
-                "low": 69000,
-                "close": 70000,
-                "volume": 2000000,
-            }
-            for i in range(5)
-        ]
-
-        candidates = await scanner.scan()
-
-        # Should skip due to insufficient data
-        assert len(candidates) == 0
-
    @pytest.mark.asyncio
    async def test_get_stock_codes(
        self, scanner: SmartVolatilityScanner
@@ -323,6 +231,124 @@ class TestSmartVolatilityScanner:

        assert codes == ["005930", "035420"]

+    @pytest.mark.asyncio
+    async def test_scan_overseas_uses_dynamic_symbols(
+        self, mock_broker: MagicMock, mock_overseas_broker: MagicMock, mock_settings: Settings
+    ) -> None:
+        """Overseas scan should use provided dynamic universe symbols."""
+        analyzer = VolatilityAnalyzer()
+        scanner = SmartVolatilityScanner(
+            broker=mock_broker,
+            overseas_broker=mock_overseas_broker,
+            volatility_analyzer=analyzer,
+            settings=mock_settings,
+        )
+
+        market = MagicMock()
+        market.name = "NASDAQ"
+        market.code = "US_NASDAQ"
+        market.exchange_code = "NASD"
+        market.is_domestic = False
+
+        mock_overseas_broker.get_overseas_price.side_effect = [
+            {"output": {"last": "210.5", "rate": "1.6", "tvol": "1500000"}},
+            {"output": {"last": "330.1", "rate": "0.2", "tvol": "900000"}},
+        ]
+
+        candidates = await scanner.scan(
+            market=market,
+            fallback_stocks=["AAPL", "MSFT"],
+        )
+
+        assert [c.stock_code for c in candidates] == ["AAPL"]
+        assert candidates[0].signal == "momentum"
+        assert candidates[0].price == 210.5
+
+    @pytest.mark.asyncio
+    async def test_scan_overseas_uses_ranking_api_first(
+        self, mock_broker: MagicMock, mock_overseas_broker: MagicMock, mock_settings: Settings
+    ) -> None:
+        """Overseas scan should prioritize ranking API when available."""
+        analyzer = VolatilityAnalyzer()
+        scanner = SmartVolatilityScanner(
+            broker=mock_broker,
+            overseas_broker=mock_overseas_broker,
+            volatility_analyzer=analyzer,
+            settings=mock_settings,
+        )
+        market = MagicMock()
+        market.name = "NASDAQ"
+        market.code = "US_NASDAQ"
+        market.exchange_code = "NASD"
+        market.is_domestic = False
+
+        mock_overseas_broker.fetch_overseas_rankings.return_value = [
+            {"symb": "NVDA", "last": "780.2", "rate": "2.4", "tvol": "1200000"},
+            {"symb": "MSFT", "last": "420.0", "rate": "0.3", "tvol": "900000"},
+        ]
+
+        candidates = await scanner.scan(market=market, fallback_stocks=["AAPL", "TSLA"])
+
+        assert mock_overseas_broker.fetch_overseas_rankings.call_count >= 1
+        mock_overseas_broker.get_overseas_price.assert_not_called()
+        assert [c.stock_code for c in candidates] == ["NVDA"]
+
+    @pytest.mark.asyncio
+    async def test_scan_overseas_without_symbols_returns_empty(
+        self, mock_broker: MagicMock, mock_overseas_broker: MagicMock, mock_settings: Settings
+    ) -> None:
+        """Overseas scan should return empty list when no symbol universe exists."""
+        analyzer = VolatilityAnalyzer()
+        scanner = SmartVolatilityScanner(
+            broker=mock_broker,
+            overseas_broker=mock_overseas_broker,
+            volatility_analyzer=analyzer,
+            settings=mock_settings,
+        )
+        market = MagicMock()
+        market.name = "NASDAQ"
+        market.code = "US_NASDAQ"
+        market.exchange_code = "NASD"
+        market.is_domestic = False
+
+        candidates = await scanner.scan(market=market, fallback_stocks=[])
+
+        assert candidates == []
+
+    @pytest.mark.asyncio
+    async def test_scan_overseas_picks_high_intraday_range_even_with_low_change(
+        self, mock_broker: MagicMock, mock_overseas_broker: MagicMock, mock_settings: Settings
+    ) -> None:
+        """Volatility selection should consider intraday range, not only change rate."""
+        analyzer = VolatilityAnalyzer()
+        scanner = SmartVolatilityScanner(
+            broker=mock_broker,
+            overseas_broker=mock_overseas_broker,
+            volatility_analyzer=analyzer,
+            settings=mock_settings,
+        )
+        market = MagicMock()
+        market.name = "NASDAQ"
+        market.code = "US_NASDAQ"
+        market.exchange_code = "NASD"
+        market.is_domestic = False
+
+        # change rate is tiny, but high-low range is large (15%).
+        mock_overseas_broker.fetch_overseas_rankings.return_value = [
+            {
+                "symb": "ABCD",
+                "last": "100",
+                "rate": "0.2",
+                "high": "110",
+                "low": "95",
+                "tvol": "800000",
+            }
+        ]
+
+        candidates = await scanner.scan(market=market, fallback_stocks=[])
+
+        assert [c.stock_code for c in candidates] == ["ABCD"]
+

 class TestRSICalculation:
    """Test RSI calculation in VolatilityAnalyzer."""
--- a/tests/test_telegram_commands.py
+++ b/tests/test_telegram_commands.py
@@ -682,6 +682,10 @@ class TestBasicCommands:
                "/help - Show available commands\n"
                "/status - Trading status (mode, markets, P&L)\n"
                "/positions - Current holdings\n"
+                "/report - Daily summary report\n"
+                "/scenarios - Today's playbook scenarios\n"
+                "/review - Recent scorecards\n"
+                "/dashboard - Dashboard URL/status\n"
                "/stop - Pause trading\n"
                "/resume - Resume trading"
            )
@@ -707,10 +711,106 @@ class TestBasicCommands:
            assert "/help" in payload["text"]
            assert "/status" in payload["text"]
            assert "/positions" in payload["text"]
+            assert "/report" in payload["text"]
+            assert "/scenarios" in payload["text"]
+            assert "/review" in payload["text"]
+            assert "/dashboard" in payload["text"]
            assert "/stop" in payload["text"]
            assert "/resume" in payload["text"]


+class TestExtendedCommands:
+    """Test additional bot commands."""
+
+    @pytest.mark.asyncio
+    async def test_report_command(self) -> None:
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        async def mock_report() -> None:
+            await client.send_message("<b>📈 Daily Report</b>\n\nTrades: 1")
+
+        handler.register_command("report", mock_report)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            await handler._handle_update(
+                {"update_id": 1, "message": {"chat": {"id": 456}, "text": "/report"}}
+            )
+            payload = mock_post.call_args.kwargs["json"]
+            assert "Daily Report" in payload["text"]
+
+    @pytest.mark.asyncio
+    async def test_scenarios_command(self) -> None:
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        async def mock_scenarios() -> None:
+            await client.send_message("<b>🧠 Today's Scenarios</b>\n\n- AAPL: BUY (85)")
+
+        handler.register_command("scenarios", mock_scenarios)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            await handler._handle_update(
+                {"update_id": 1, "message": {"chat": {"id": 456}, "text": "/scenarios"}}
+            )
+            payload = mock_post.call_args.kwargs["json"]
+            assert "Today's Scenarios" in payload["text"]
+
+    @pytest.mark.asyncio
+    async def test_review_command(self) -> None:
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        async def mock_review() -> None:
+            await client.send_message("<b>📝 Recent Reviews</b>\n\n- 2026-02-14 KR")
+
+        handler.register_command("review", mock_review)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            await handler._handle_update(
+                {"update_id": 1, "message": {"chat": {"id": 456}, "text": "/review"}}
+            )
+            payload = mock_post.call_args.kwargs["json"]
+            assert "Recent Reviews" in payload["text"]
+
+    @pytest.mark.asyncio
+    async def test_dashboard_command(self) -> None:
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        async def mock_dashboard() -> None:
+            await client.send_message("<b>🖥️ Dashboard</b>\n\nURL: http://127.0.0.1:8080")
+
+        handler.register_command("dashboard", mock_dashboard)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            await handler._handle_update(
+                {"update_id": 1, "message": {"chat": {"id": 456}, "text": "/dashboard"}}
+            )
+            payload = mock_post.call_args.kwargs["json"]
+            assert "Dashboard" in payload["text"]
+
+
 class TestGetUpdates:
    """Test getUpdates API interaction."""
Author	SHA1	Message	Date
agentson	3952a5337b	docs: add requirements log entry for overseas limit order fix (#149 ) Some checks failed CI / test (pull_request) Has been cancelled Details	2026-02-18 23:54:18 +09:00
agentson	ccc97ebaa9	fix: use current_price for overseas limit orders (KIS VTS rejects market orders) (#149 ) Some checks failed CI / test (pull_request) Has been cancelled Details KIS VTS (paper trading) rejects overseas market orders with: "모의투자 주문처리가 안되었습니다(지정가만 가능한 상품입니다)" Root cause: send_overseas_order() was called with price=0.0 (market order) in both trading_cycle() and run_daily_session(), even though current_price was already computed correctly by Fix #147 (exchange code mapping). Fix: pass current_price as the limit order price in both call sites. Domestic broker send_order() keeps price=0 (market orders are fine on KRX). Adds regression test TestOverseasBalanceParsing::test_overseas_buy_order_uses_limit_price verifying price=182.5 is passed, not 0.0. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-02-18 23:53:15 +09:00
agentson	3a54db8948	fix: price API exchange code mapping and VTS overseas balance fallback (#147 ) Some checks failed CI / test (pull_request) Has been cancelled Details - Apply _PRICE_EXCHANGE_MAP in get_overseas_price() to send short codes (NASD→NAS, NYSE→NYS, AMEX→AMS) required by HHDFS00000300 price API - Add PAPER_OVERSEAS_CASH config setting (default $50,000) for simulated USD balance when VTS overseas balance API returns 0 in paper mode - Fall back to scan candidate price when live price API returns 0 - Both fixes together resolve "no affordable quantity (cash=0, price=0)" which was preventing all overseas trade execution Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-02-18 23:48:14 +09:00
agentson	96e2ad4f1f	fix: use smart rule-based fallback playbook when Gemini fails (issue #145 ) Some checks failed CI / test (pull_request) Has been cancelled Details When gemini-2.5-flash quota is exhausted (20 RPD free tier), generate_playbook() fell back to _defensive_playbook() which only had price_change_pct_below: -3.0 SELL conditions — no BUY conditions — causing zero trades on US market despite scanner finding strong momentum/oversold candidates. Changes: - Add _smart_fallback_playbook() that uses scanner signals to build BUY conditions: - momentum signal: BUY when volume_ratio_above=VOL_MULTIPLIER - oversold signal: BUY when rsi_below=RSI_OVERSOLD_THRESHOLD - always: SELL stop-loss at price_change_pct_below=-3.0 - Use _smart_fallback_playbook() instead of _defensive_playbook() on Gemini failure - Add 10 new tests for _smart_fallback_playbook() covering momentum/oversold/empty cases - Update existing test_gemini_failure_returns_defensive to match new behavior Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-02-18 22:23:57 +09:00
jihoson	c5a8982122	Merge pull request 'Fix: gemini_client.decide() ignores prompt_override (#143 )' (#144 ) from feature/issue-143-fix-prompt-override into main Some checks failed CI / test (push) Has been cancelled Details Reviewed-on: #144	2026-02-18 02:05:50 +09:00
agentson	f7289606fc	fix: use prompt_override in gemini_client.decide() for playbook generation Some checks failed CI / test (pull_request) Has been cancelled Details decide() ignored market_data["prompt_override"], always building a generic trade-decision prompt. This caused pre_market_planner playbook generation to fail with JSONDecodeError on every market, falling back to defensive playbooks. Now prompt_override takes priority over both optimization and standard prompt building. Closes #143 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-18 02:02:13 +09:00
jihoson	0c5c90201f	Merge pull request 'fix: correct KIS overseas ranking API TR_IDs, paths, and exchange codes' (#142 ) from feature/issue-141-fix-overseas-ranking-api into main Some checks failed CI / test (push) Has been cancelled Details Reviewed-on: #142	2026-02-18 01:13:07 +09:00
agentson	b484f0daff	fix: align cooldown test with wait-and-retry behavior + boost overseas coverage Some checks failed CI / test (pull_request) Has been cancelled Details - test_token_refresh_cooldown: updated to match the wait-then-retry behavior introduced in `aeed881` (was expecting fail-fast ConnectionError) - Added 22 tests for OverseasBroker: get_overseas_price, get_overseas_balance, send_overseas_order, _get_currency_code, _extract_ranking_rows - src/broker/overseas.py coverage: 52% → 100% - All 594 tests pass Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-18 01:12:09 +09:00
agentson	1288181e39	docs: add requirements log entry for overseas ranking API fix Some checks failed CI / test (pull_request) Has been cancelled Details Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-18 01:04:42 +09:00
agentson	b625f41621	fix: correct KIS overseas ranking API TR_IDs, paths, and exchange codes Some checks failed CI / test (pull_request) Has been cancelled Details The overseas ranking API was returning 404 for all exchanges because the TR_IDs, API paths, and exchange codes were all incorrect. Updated to match KIS official API documentation: - TR_ID: HHDFS76290000 (updown-rate), HHDFS76270000 (volume-surge) - Path: /uapi/overseas-stock/v1/ranking/{updown-rate,volume-surge} - Exchange codes: NASD→NAS, NYSE→NYS, AMEX→AMS via ranking-specific mapping Fixes #141 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-18 01:02:52 +09:00
jihoson	77d3ba967c	Merge pull request 'Fix overnight runner stability and token cooldown handling' (#139 ) from agentson/fix/137-run-overnight-python-tmux into main Some checks failed CI / test (push) Has been cancelled Details Reviewed-on: #139	2026-02-18 00:05:44 +09:00
agentson	aeed881d85	fix: wait on token refresh cooldown instead of failing fast Some checks failed CI / test (pull_request) Has been cancelled Details	2026-02-18 00:03:42 +09:00
agentson	d0bbdb5dc1	fix: harden overseas ranking fallback and scanner visibility	2026-02-17 23:39:20 +09:00
jihoson	44339c52d7	Merge pull request 'Fix overnight runner Python selection and tmux window targeting' (#138 ) from agentson/fix/137-run-overnight-python-tmux into main Some checks failed CI / test (push) Has been cancelled Details Reviewed-on: #138	2026-02-17 23:25:11 +09:00
agentson	22ffdafacc	chore: add overnight helper scripts Some checks failed CI / test (pull_request) Has been cancelled Details - add morning report launcher\n- add overnight stop script\n- add watchdog health monitor script\n\nRefs #137	2026-02-17 23:24:15 +09:00
agentson	c49765e951	fix: make overnight runner use venv python and tmux-safe window target Some checks failed CI / test (pull_request) Has been cancelled Details - prefer .venv/bin/python when APP_CMD is unset\n- pass DASHBOARD_PORT into launch command (default 8080)\n- target tmux window by name instead of fixed index\n\nRefs #137	2026-02-17 23:21:04 +09:00
jihoson	64000b9967	Merge pull request 'feat: unify domestic scanner and sizing; update docs' (#136 ) from feat/overseas-ranking-current-state into main Some checks failed CI / test (push) Has been cancelled Details Reviewed-on: #136	2026-02-17 06:35:43 +09:00
agentson	733e6b36e9	feat: unify domestic scanner and sizing; update docs Some checks failed CI / test (pull_request) Has been cancelled Details	2026-02-17 06:29:36 +09:00
agentson	0659cc0aca	docs: reflect overseas ranking integration and volatility-first selection	2026-02-17 06:29:16 +09:00
agentson	748b9b848e	feat: prioritize overseas volatility scoring over raw rankings	2026-02-17 06:25:45 +09:00
agentson	6a1ad230ee	feat: add overseas ranking integration with dynamic fallback	2026-02-17 06:25:45 +09:00
jihoson	90bbc78867	Merge pull request 'docs: sync V2 status and process docs (#131 )' (#134 ) from feature/issue-131-docs-v2-status-sync into main Some checks failed CI / test (push) Has been cancelled Details Reviewed-on: #134 Reviewed-by: jihoson <kiparang7th@gmail.com>	2026-02-16 21:50:49 +09:00
agentson	1ef5dcb2b3	docs: README.md v2 현행화 (#131 ) Some checks failed CI / test (pull_request) Has been cancelled Details - 아키텍처 다이어그램에 v2 컴포넌트 (Strategy, Context, Evolution) 추가 - 핵심 모듈 테이블: 6개 → 14개 모듈 반영 - 테스트: 35개/3파일 → 551개/25파일 - 지원 시장 10개 거래소 테이블 추가 - 텔레그램 양방향 명령어 9종 레퍼런스 - 프로젝트 구조 트리 전면 갱신 - 문서 링크 섹션 추가 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-16 21:48:49 +09:00
agentson	d105a3ff5e	docs: v2 상태 반영 - 전체 문서 현행화 (#131 ) Some checks failed CI / test (pull_request) Has been cancelled Details - testing.md: 54 tests/4 files → 551 tests/25 files 반영, 전체 테스트 파일 설명 - architecture.md: v2 컴포넌트 추가 (Strategy, Context, Dashboard, Decision Logger 등), Playbook Mode 데이터 플로우, DB 스키마 5개 테이블, v2 환경변수 - commands.md: Dashboard 실행, Telegram 명령어 9종 레퍼런스 - CLAUDE.md: Project Structure 확장, 테스트 수 업데이트, --dashboard 플래그 - skills.md: DB 파일명 trades.db로 통일, Dashboard 명령어 추가 - requirements-log.md: 2026-02-16 문서 v2 동기화 요구사항 기록 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-16 21:44:59 +09:00
jihoson	0424c78f6c	Merge pull request 'feat: US market code 정합성, Telegram 명령 4종, 손절 모니터링 (#132 )' (#135 ) from feature/issue-132-us-market-telegram-gaps into main Some checks failed CI / test (push) Has been cancelled Details Reviewed-on: #135	2026-02-16 20:25:43 +09:00
agentson	3fdb7a29d4	feat: US market code 정합성, Telegram 명령 4종, 손절 모니터링 (#132 ) Some checks failed CI / test (pull_request) Has been cancelled Details - MARKET_SHORTHAND + expand_market_codes()로 config "US" → schedule "US_NASDAQ/NYSE/AMEX" 자동 확장 - /report, /scenarios, /review, /dashboard 텔레그램 명령 추가 - price_change_pct를 trading_cycle과 run_daily_session에 주입 - HOLD시 get_open_position 기반 손절 모니터링 및 자동 SELL 오버라이드 - 대시보드 /api/status 동적 market 조회로 변경 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-16 20:24:01 +09:00
jihoson	31b4d0bf1e	Merge pull request 'fix: daily_review 테스트 날짜 불일치 수정 (#129 )' (#130 ) from feature/issue-129-fix-daily-review-test-date into main Some checks failed CI / test (push) Has been cancelled Details CI / test (pull_request) Has been cancelled Details Reviewed-on: #130	2026-02-16 11:30:20 +09:00
agentson	e2275a23b1	fix: daily_review 테스트에서 날짜 불일치로 인한 실패 수정 (#129 ) Some checks failed CI / test (pull_request) Has been cancelled Details DecisionLogger와 log_trade가 datetime.now(UTC)로 현재 날짜를 저장하는데, 테스트에서 하드코딩된 '2026-02-14'로 조회하여 0건이 반환되던 문제 수정. generate_scorecard 호출 시 TODAY 변수를 사용하도록 변경. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-16 10:05:17 +09:00
jihoson	7522bb7e66	Merge pull request 'feat: 대시보드 실행 통합 - CLI + 환경변수 (issue #97 )' (#128 ) from feature/issue-97-dashboard-integration into main Some checks failed CI / test (push) Has been cancelled Details Reviewed-on: #128	2026-02-15 00:01:57 +09:00