Document	Description
CONCEPT.md	Philosophy, ideas, and design rationale
USAGE.md	Practical usage guide with examples
ARCHITECTURE.md	Technical implementation details
HOT_SCANNER.md	🔥 Viral trend detection (NEW)

Quick Links

For Users

Start with USAGE.md — it has practical examples for:

Basic stock analysis
Comparing stocks
Crypto analysis
Dividend investing
Portfolio management
Watchlist & alerts

For Understanding

Read CONCEPT.md to understand:

Why 8 dimensions?
How scoring works
Contrarian signals
Risk detection philosophy
Limitations we acknowledge

For Developers

Check ARCHITECTURE.md for:

System overview diagram
Data flow
Caching strategy
File structure
Performance optimization

Quick Start

# Analyze a stock
uv run scripts/analyze_stock.py AAPL

# Fast mode (2-3 seconds)
uv run scripts/analyze_stock.py AAPL --fast

# Dividend analysis
uv run scripts/dividends.py JNJ

# Watchlist
uv run scripts/watchlist.py add AAPL --target 200
uv run scripts/watchlist.py check

Key Concepts

The 8 Dimensions

Earnings Surprise (30%) — Did they beat expectations?
Fundamentals (20%) — P/E, margins, growth, debt
Analyst Sentiment (20%) — Professional consensus
Historical Patterns (10%) — Past earnings reactions
Market Context (10%) — VIX, SPY/QQQ trends
Sector Performance (15%) — Relative strength
Momentum (15%) — RSI, 52-week range
Sentiment (10%) — Fear/Greed, shorts, insiders

Signal Thresholds

Score	Recommendation
> +0.33	BUY
-0.33 to +0.33	HOLD
< -0.33	SELL

Risk Flags

⚠️ Pre-earnings (< 14 days)
⚠️ Post-spike (> 15% in 5 days)
⚠️ Overbought (RSI > 70 + near 52w high)
⚠️ Risk-off mode (GLD/TLT/UUP rising)
⚠️ Geopolitical keywords
⚠️ Breaking news alerts

Disclaimer

⚠️ NOT FINANCIAL ADVICE. For informational purposes only. Always do your own research and consult a licensed financial advisor.

README.md

Documentation

Stock Analysis v6.1

Contents