docs: just run dev 명령어 및 index 엔드포인트 문서 추가

- README/API_DOCUMENTATION에 `just run dev` 개발 서버 실행 방법 추가
- `GET /stocks/index/{index_name}` 엔드포인트 문서화 (sp500/nasdaq100)
- justfile을 프로젝트 파일로 문서에 포함

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

API_DOCUMENTATION.md

@@ -8,6 +8,16 @@ Stock Oracle provides comprehensive financial, price, news, and social media dat
 
 ## 🚀 Quick Start
 
+### Running the API
+
+```bash
+# Start all services (first time)
+docker-compose up -d
+
+# Restart API after code changes
+just run dev
+```
+
 ### Base URL
 ```
 http://localhost:18001/api/v1
@@ -335,6 +345,50 @@ Download and ingest FINRA short volume file(s) for a specific date or date range
 
 ### Stock Market Data 🆕
 
+#### `GET /stocks/index/{index_name}`
+S&P 500 또는 Nasdaq 100 구성 종목을 Wikipedia에서 조회합니다.
+
+**Path Parameters:**
+- `index_name`: `sp500` 또는 `nasdaq100`
+
+**Query Parameters:**
+- `force_refresh`: `true`/`false` (default: `false`) — 캐시 무시하고 재조회
+
+**Caching:**
+- TTL: 24시간 (`Cache-Control: public, max-age=86400`)
+- `X-Cache: HIT` / `MISS`, `ETag` 헤더 포함
+
+**Response:**
+```json
+{
+  "success": true,
+  "index": "sp500",
+  "count": 503,
+  "constituents": [
+    {
+      "symbol": "AAPL",
+      "name": "Apple Inc.",
+      "sector": "Information Technology",
+      "industry": "Technology Hardware, Storage & Peripherals"
+    }
+  ]
+}
+```
+
+**Examples:**
+```
+GET /stocks/index/sp500        → S&P 500 구성 종목 (~503개)
+GET /stocks/index/nasdaq100    → Nasdaq 100 구성 종목 (~101개)
+GET /stocks/index/sp500?force_refresh=true  → 캐시 무시하고 재조회
+GET /stocks/index/foo          → 400 Bad Request
+```
+
+**Error Codes:**
+- `400`: 지원하지 않는 `index_name`
+- `504`: Wikipedia 응답 30초 초과
+
+---
+
 #### `GET /stocks/most-active`
 Most actively traded stocks from Yahoo Finance.
 

README.md

@@ -16,6 +16,7 @@ Stock Oracle is a comprehensive investment analysis API that leverages SEC EDGAR
 ### Market Data Intelligence (NEW! 🆕)
 - **Most Active Stocks**: Real-time ~170 most actively traded stocks (sub-5s response)
 - **52-Week Gainers**: 1,350+ top gaining stocks with intelligent rate limiting (5-90s)
+- **Index Constituents**: S&P 500 / Nasdaq 100 구성 종목 조회 — Wikipedia 파싱, 24시간 캐시
 - **FRED Economic Data**: Federal Reserve economic indicators with smart caching (1000/day limit)
 - **Advanced Web Scraping**: curl_cffi + Chrome impersonation bypasses rate limits
 - **Smart Pagination**: Configurable page limits (1-10 pages) for performance tuning
@@ -94,10 +95,15 @@ pip install -r requirements-api.txt
 cp .env.example .env
 # Edit .env with your settings
 
-# Run the API
+# Start all services (first time)
-python -m uvicorn app.main:app --host 0.0.0.0 --port 18000 --reload
+docker-compose up -d
+
+# Restart API after code changes (code is volume-mounted, no rebuild needed)
+just run dev
 ```
 
+> **Note**: Always use `just run dev` to restart the API. The `app/` directory is volume-mounted into the container, so code changes take effect on restart without rebuilding the image.
+
 ## ⚡ Quick Examples
 
 ### Get Market Overview
@@ -733,6 +739,7 @@ curl "http://localhost:18001/api/v1/news/NVDA/social-only?days_back=3&max_social
 - `GET /api/v1/stocks/trending` - **Trending stocks combining most active + 52-week gainers** (🚀 Recommended)
 - `GET /api/v1/stocks/most-active` - Most actively traded stocks (optional limit parameter)
 - `GET /api/v1/stocks/52-week-gainers` - 52-week top gaining stocks with intelligent rate limiting
+- `GET /api/v1/stocks/index/{index_name}` - S&P 500 / Nasdaq 100 constituents from Wikipedia (24h cache)
 
 #### Alpaca Market Data (NEW! 🆕)
 - `GET /api/v1/alpaca/status` - Alpaca connection status and API key validation

justfile

@@ -0,0 +1,6 @@
+# Stock Oracle dev commands
+
+# Restart API container (code is volume-mounted, so this picks up changes immediately)
+run dev:
+    docker restart stock_oracle_api
+    docker logs -f stock_oracle_api