diff --git a/README.md b/README.md
new file mode 100644
index 0000000..987b0f9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,129 @@
+# stock-catalyst
+
+한국 주식 분석 플랫폼의 **카탈리스트 탐지 서비스**. 스크리닝된 종목의 공시와 뉴스를 분석하여 긍정적 촉매(카탈리스트)와 밸류 트랩 신호를 식별합니다.
+
+## 기능
+
+- **카탈리스트 탐지**: 키워드 패턴 매칭으로 공시에서 긍정적 이벤트 식별
+- **밸류 트랩 경고**: 저평가처럼 보이지만 위험한 종목 신호 감지
+- **공시 데이터 조회**: MongoDB에서 종목별 공시 이력 조회
+- **카테고리 분류**: 실적호전, 대규모계약, 주주환원, M&A, 규제긍정
+- **비동기 워커**: Redis Streams 기반 파이프라인 연동
+
+## 카탈리스트 카테고리
+
+| 카테고리 | 키워드 예시 |
+|---------|------------|
+| **실적 서프라이즈** | 어닝서프라이즈, 실적 호조, 영업이익 증가, 흑자전환, 사상최대 |
+| **대규모 계약** | 대규모 계약, 수주, 공급계약, 납품계약, 신규 수주 |
+| **주주 환원** | 배당, 자사주, 자기주식, 주주환원, 배당금 증가 |
+| **M&A** | 인수, 합병, M&A, 지분 취득, 경영권 |
+| **규제 긍정** | 규제 완화, 인허가, 승인, 보조금, 세제 혜택 |
+
+### 밸류 트랩 경고 키워드
+
+매출 감소, 영업손실, 적자 전환, 적자 지속, 구조조정, 감자, 상장폐지, 관리종목, 자본잠식
+
+## API 엔드포인트
+
+| 메서드 | 경로 | 설명 |
+|--------|------|------|
+| GET | `/health` | 서비스 상태 |
+| GET | `/streams` | Redis Stream 큐 길이 |
+| POST | `/detect` | 카탈리스트 탐지 트리거 |
+| GET | `/results/{stock_code}` | 종목별 공시/카탈리스트 조회 |
+
+### 요청 예시
+
+```bash
+# 카탈리스트 탐지 트리거
+curl -X POST http://localhost:8005/detect \
+  -H "Content-Type: application/json" \
+  -d '{"stock_code": "005930", "run_id": "abc-123", "composite_score": 85.3}'
+
+# 결과 조회
+curl http://localhost:8005/results/005930?limit=10
+```
+
+### 응답 예시
+
+```json
+// GET /results/{stock_code}
+{
+  "stock_code": "005930",
+  "disclosures": [
+    {
+      "_id": "...",
+      "stock_code": "005930",
+      "title": "삼성전자 사업보고서",
+      "dart_id": "20241220000001",
+      "disclosed_at": "2024-12-20T00:00:00"
+    }
+  ]
+}
+
+// 탐지 결과 (내부)
+{
+  "catalyst_score": 60,
+  "detected_catalysts": [
+    {"category": "earnings_surprise", "keyword": "영업이익 증가", "title": "..."}
+  ],
+  "value_trap_signals": [],
+  "is_value_trap": false
+}
+```
+
+## 점수 체계
+
+- **Catalyst Score**: 0~100점. 탐지된 카탈리스트 1개당 +20점
+- **밸류 트랩 감지**: 경고 신호 2개 이상 → `is_value_trap: true`, 점수 -40점
+- 뉴스 기반 탐지: 카탈리스트 1개당 +15점
+
+## 데이터 파이프라인
+
+```
+queue:screened (스크리닝 결과)
+     │
+     ▼
+  Worker (CatalystDetector)
+     │
+     ├── MongoDB에서 공시 데이터 조회
+     ├── 키워드 매칭으로 카탈리스트 탐지
+     │
+     ▼
+queue:catalysts  ──→  stock-llm-analyzer
+```
+
+## 프로젝트 구조
+
+```
+stock-catalyst/
+├── pyproject.toml
+├── Dockerfile
+├── .dockerignore
+└── src/stock_catalyst/
+    ├── __init__.py
+    ├── api.py          # FastAPI 엔드포인트
+    ├── detector.py     # CatalystDetector (키워드 패턴 매칭)
+    └── worker.py       # Redis Stream 소비자 + API 서버 실행
+```
+
+## 환경변수
+
+| 변수 | 설명 | 기본값 |
+|------|------|--------|
+| `REDIS_URL` | Redis 연결 URL | `redis://localhost:6379/0` |
+| `MONGODB_URI` | MongoDB 연결 URI | `mongodb://localhost:27017` |
+| `MONGODB_DB` | MongoDB 데이터베이스명 | `stock_analysis` |
+
+## 로컬 실행
+
+```bash
+pip install -e ../stock-common && pip install -e .
+python -m stock_catalyst.worker
+```
+
+## 의존성
+
+- `stock-common` - 공유 라이브러리
+- Python >= 3.12