{"id":"c238a230-65f7-46b9-af8e-db782f0aedf1","entityType":"agent","slug":"clawhub-udiedrichsen-stock-analysis-2","name":"Stock Analysis","canonicalUrl":"https://www.xpersona.co/agent/clawhub-udiedrichsen-stock-analysis-2","canonicalPath":"/agent/clawhub-udiedrichsen-stock-analysis-2","generatedAt":"2026-10-10T00:35:17.353Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-05-19T07:00:23.045Z","emptyReason":null},"description":"Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management, watchlists with alerts, dividend analysis, 8-dimension stock scoring, viral trend detection (Hot Scanner), and rumor/early signal detection. Use for stock analysis, portfolio tracking, earnings reactions, crypto monitoring, trending stocks, or finding rumors before they hit mainstream. Skill: Stock Analysis Owner: udiedrichsen Summary: Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management, watchlists with alerts, dividend analysis, 8-dimension stock scoring, viral trend detection (Hot Scanner), and rumor/early signal detection. Use for stock analysis, portfolio tracking, earnings reactions, crypto monitoring, trending stocks, or finding rumors before they hit m","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 50.2K downloads reported by the source. Last updated 5/19/2026.","installCommand":"clawhub skill install publishers:udiedrichsen:stock-analysis","sourceUrl":"https://clawhub.ai/udiedrichsen/stock-analysis","homepage":"https://clawhub.ai/udiedrichsen/stock-analysis","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/udiedrichsen/stock-analysis","kind":"source"}],"safetyScore":84,"overallRank":62,"popularityScore":94,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management, watchlists with alerts, dividend analysis, 8-dimension stock scorin"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-05-19T07:00:23.045Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-05-19T07:00:23.045Z","emptyReason":null},"stars":null,"forks":null,"downloads":50220,"packageName":null,"latestVersion":"6.2.0","tractionLabel":"50.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-05-19T07:00:22.962Z","emptyReason":null},"lastUpdatedAt":"2026-05-19T07:00:23.045Z","lastCrawledAt":"2026-05-19T07:00:22.962Z","lastIndexedAt":null,"nextCrawlAt":"2026-05-20T07:00:22.962Z","lastVerifiedAt":null,"highlights":[{"version":"6.2.0","createdAt":"2026-02-02T14:09:13.575Z","changelog":"🔮 Rumor Scanner: M&A rumors, insider activity, Twitter whispers, impact scoring","fileCount":17,"zipByteSize":79126},{"version":"6.1.0","createdAt":"2026-02-02T11:07:39.843Z","changelog":"**Major update: Viral trend detection (\"Hot Scanner\") and social media integration.** - Added Hot Scanner to detect trending stocks and crypto from CoinGecko, Yahoo Finance, Google News, and Twitter/X. - Introduced new /stock_hot command for finding viral assets. - Added Twitter/X integration for social sentiment in Hot Scanner (optional setup). - Expanded documentation: new concept, architecture, usage, and hot scanner docs. - Enhanced cron support for daily trend reports. - Existing features (analysis, alerts, dividend, portfolio) unchanged.","fileCount":16,"zipByteSize":74714},{"version":"6.0.0","createdAt":"2026-02-02T09:07:24.446Z","changelog":"Watchlist + Alerts, Dividend Analysis, Fast Mode, Tests","fileCount":10,"zipByteSize":50773},{"version":"5.0.0","createdAt":"2026-01-16T09:33:36.509Z","changelog":"Portfolio management, crypto analysis (Top 20), periodic reports (daily/weekly/monthly/quarterly/yearly)","fileCount":7,"zipByteSize":41538},{"version":"4.0.0","createdAt":"2026-01-15T07:11:12.536Z","changelog":"v4.0.0: Geopolitical Risk & News Sentiment Major new features: • Safe-haven indicators (GLD, TLT, UUP) with risk-off detection • Breaking news check (Google News RSS) for crisis keywords • Geopolitical sector risk mapping (Taiwan, China, Russia, Middle East, banking) • Automatic confidence penalties for affected tickers/sectors (15-30%) • Up to 5 caveats in output (was 3) Risk detection: • Flight to safety detection across gold, treasuries, USD • Crisis keyword scanning (war, recession, sanctions, disasters) • Sector-specific exposure warnings • 1-hour cache for breaking news and shared indicators","fileCount":4,"zipByteSize":25321},{"version":"3.5.0","createdAt":"2026-01-15T06:39:48.890Z","changelog":"Major performance upgrade: Async parallel fetching (6-10s → 3-5s per stock) + caching for shared indicators (Fear/Greed, VIX). Multi-stock analysis now ~3x faster. All 5 sentiment indicators fetch in parallel with 10s timeouts. Fear & Greed Index and VIX term structure cached for 1h.","fileCount":4,"zipByteSize":20870},{"version":"3.0.0","createdAt":"2026-01-15T06:10:37.779Z","changelog":"Add comprehensive sentiment analysis with 5 indicators: Fear & Greed Index, short interest, VIX term structure, insider trading, and put/call ratio. Sentiment adds 10% weight to overall recommendation. Runtime increased to 6-10s per stock.","fileCount":3,"zipByteSize":15312},{"version":"2.0.0","createdAt":"2026-01-14T16:31:21.094Z","changelog":"Major enhancement: Added market context (VIX, SPY/QQQ), sector performance comparison, earnings timing warnings (pre/post-earnings), and momentum analysis (RSI, 52w range). Now detects 'sell the news' scenarios, overbought conditions, and sector rotation. Helps avoid losses like the BAC scenario by warning about high-risk entry points. All 7 dimensions now analyzed with smart recommendation overrides.","fileCount":3,"zipByteSize":11767}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install publishers:udiedrichsen:stock-analysis","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis-2/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis-2/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis-2/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis-2/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis-2/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis-2/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T00:35:17.349Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis-2/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis-2/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis-2/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis-2/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-05-19T07:00:23.045Z","emptyReason":null},"readme":"Skill: Stock Analysis\n\nOwner: udiedrichsen\n\nSummary: Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management, watchlists with alerts, dividend analysis, 8-dimension stock scoring, viral trend detection (Hot Scanner), and rumor/early signal detection. Use for stock analysis, portfolio tracking, earnings reactions, crypto monitoring, trending stocks, or finding rumors before they hit mainstream.\n\nTags: latest:6.2.0\n\nVersion history:\n\nv6.2.0 | 2026-02-02T14:09:13.575Z | user\n\n🔮 Rumor Scanner: M&A rumors, insider activity, Twitter whispers, impact scoring\n\nv6.1.0 | 2026-02-02T11:07:39.843Z | auto\n\n**Major update: Viral trend detection (\"Hot Scanner\") and social media integration.**\n\n- Added Hot Scanner to detect trending stocks and crypto from CoinGecko, Yahoo Finance, Google News, and Twitter/X.\n- Introduced new /stock_hot command for finding viral assets.\n- Added Twitter/X integration for social sentiment in Hot Scanner (optional setup).\n- Expanded documentation: new concept, architecture, usage, and hot scanner docs.\n- Enhanced cron support for daily trend reports.\n- Existing features (analysis, alerts, dividend, portfolio) unchanged.\n\nv6.0.0 | 2026-02-02T09:07:24.446Z | user\n\nWatchlist + Alerts, Dividend Analysis, Fast Mode, Tests\n\nv5.0.0 | 2026-01-16T09:33:36.509Z | user\n\nPortfolio management, crypto analysis (Top 20), periodic reports (daily/weekly/monthly/quarterly/yearly)\n\nv4.0.0 | 2026-01-15T07:11:12.536Z | user\n\nv4.0.0: Geopolitical Risk & News Sentiment\n\nMajor new features:\n• Safe-haven indicators (GLD, TLT, UUP) with risk-off detection\n• Breaking news check (Google News RSS) for crisis keywords\n• Geopolitical sector risk mapping (Taiwan, China, Russia, Middle East, banking)\n• Automatic confidence penalties for affected tickers/sectors (15-30%)\n• Up to 5 caveats in output (was 3)\n\nRisk detection:\n• Flight to safety detection across gold, treasuries, USD\n• Crisis keyword scanning (war, recession, sanctions, disasters)\n• Sector-specific exposure warnings\n• 1-hour cache for breaking news and shared indicators\n\nv3.5.0 | 2026-01-15T06:39:48.890Z | user\n\nMajor performance upgrade: Async parallel fetching (6-10s → 3-5s per stock) + caching for shared indicators (Fear/Greed, VIX). Multi-stock analysis now ~3x faster. All 5 sentiment indicators fetch in parallel with 10s timeouts. Fear & Greed Index and VIX term structure cached for 1h.\n\nv3.0.0 | 2026-01-15T06:10:37.779Z | user\n\nAdd comprehensive sentiment analysis with 5 indicators: Fear & Greed Index, short interest, VIX term structure, insider trading, and put/call ratio. Sentiment adds 10% weight to overall recommendation. Runtime increased to 6-10s per stock.\n\nv2.0.0 | 2026-01-14T16:31:21.094Z | user\n\nMajor enhancement: Added market context (VIX, SPY/QQQ), sector performance comparison, earnings timing warnings (pre/post-earnings), and momentum analysis (RSI, 52w range). Now detects 'sell the news' scenarios, overbought conditions, and sector rotation. Helps avoid losses like the BAC scenario by warning about high-risk entry points. All 7 dimensions now analyzed with smart recommendation overrides.\n\nv1.0.1 | 2026-01-14T15:21:58.281Z | user\n\nFix: Add explicit instructions to prevent agent from adding extra text in command invocation\n\nv1.0.0 | 2026-01-14T09:46:15.214Z | user\n\nInitial release: Analyze US stocks during earnings season with buy/hold/sell signals based on earnings surprises, fundamentals (P/E, margins, growth, debt), analyst sentiment, and historical patterns. Uses Yahoo Finance data via yfinance library.\n\nArchive index:\n\nArchive v6.2.0: 17 files, 79126 bytes\n\nFiles: App-Plan.md (14708b), docs/ARCHITECTURE.md (16594b), docs/CONCEPT.md (9101b), docs/HOT_SCANNER.md (5865b), docs/README.md (2405b), docs/USAGE.md (8898b), README.md (6390b), scripts/analyze_stock.py (89930b), scripts/dividends.py (13130b), scripts/hot_scanner.py (24620b), scripts/portfolio.py (18897b), scripts/rumor_scanner.py (11578b), scripts/test_stock_analysis.py (11958b), scripts/watchlist.py (11542b), SKILL.md (8230b), TODO.md (12848b), _meta.json (133b)\n\nFile v6.2.0:SKILL.md\n\n---\nname: stock-analysis\ndescription: Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management, watchlists with alerts, dividend analysis, 8-dimension stock scoring, viral trend detection (Hot Scanner), and rumor/early signal detection. Use for stock analysis, portfolio tracking, earnings reactions, crypto monitoring, trending stocks, or finding rumors before they hit mainstream.\nversion: 6.2.0\nhomepage: https://finance.yahoo.com\ncommands:\n  - /stock - Analyze a stock or crypto (e.g., /stock AAPL)\n  - /stock_compare - Compare multiple tickers\n  - /stock_dividend - Analyze dividend metrics\n  - /stock_watch - Add/remove from watchlist\n  - /stock_alerts - Check triggered alerts\n  - /stock_hot - Find trending stocks & crypto (Hot Scanner)\n  - /stock_rumors - Find early signals, M&A rumors, insider activity (Rumor Scanner)\n  - /portfolio - Show portfolio summary\n  - /portfolio_add - Add asset to portfolio\nmetadata: {\"clawdbot\":{\"emoji\":\"📈\",\"requires\":{\"bins\":[\"uv\"],\"env\":[]},\"install\":[{\"id\":\"uv-brew\",\"kind\":\"brew\",\"formula\":\"uv\",\"bins\":[\"uv\"],\"label\":\"Install uv (brew)\"}]}}\n---\n\n# Stock Analysis v6.1\n\nAnalyze US stocks and cryptocurrencies with 8-dimension analysis, portfolio management, watchlists, alerts, dividend analysis, and **viral trend detection**.\n\n## What's New in v6.2\n\n- 🔮 **Rumor Scanner** — Early signals before mainstream news\n  - M&A rumors and takeover bids\n  - Insider buying/selling activity\n  - Analyst upgrades/downgrades\n  - Twitter/X \"hearing that...\", \"sources say...\" detection\n- 🎯 **Impact Scoring** — Rumors ranked by potential market impact\n\n## What's in v6.1\n\n- 🔥 **Hot Scanner** — Find viral stocks & crypto across multiple sources\n- 🐦 **Twitter/X Integration** — Social sentiment via bird CLI\n- 📰 **Multi-Source Aggregation** — CoinGecko, Google News, Yahoo Finance\n- ⏰ **Cron Support** — Daily trend reports\n\n## What's in v6.0\n\n- 🆕 **Watchlist + Alerts** — Price targets, stop losses, signal changes\n- 🆕 **Dividend Analysis** — Yield, payout ratio, growth, safety score\n- 🆕 **Fast Mode** — `--fast` skips slow analyses (insider, news)\n- 🆕 **Improved Performance** — `--no-insider` for faster runs\n\n## Quick Commands\n\n### Stock Analysis\n```bash\n# Basic analysis\nuv run {baseDir}/scripts/analyze_stock.py AAPL\n\n# Fast mode (skips insider trading & breaking news)\nuv run {baseDir}/scripts/analyze_stock.py AAPL --fast\n\n# Compare multiple\nuv run {baseDir}/scripts/analyze_stock.py AAPL MSFT GOOGL\n\n# Crypto\nuv run {baseDir}/scripts/analyze_stock.py BTC-USD ETH-USD\n```\n\n### Dividend Analysis (NEW v6.0)\n```bash\n# Analyze dividends\nuv run {baseDir}/scripts/dividends.py JNJ\n\n# Compare dividend stocks\nuv run {baseDir}/scripts/dividends.py JNJ PG KO MCD --output json\n```\n\n**Dividend Metrics:**\n- Dividend Yield & Annual Payout\n- Payout Ratio (safe/moderate/high/unsustainable)\n- 5-Year Dividend Growth (CAGR)\n- Consecutive Years of Increases\n- Safety Score (0-100)\n- Income Rating (excellent/good/moderate/poor)\n\n### Watchlist + Alerts (NEW v6.0)\n```bash\n# Add to watchlist\nuv run {baseDir}/scripts/watchlist.py add AAPL\n\n# With price target alert\nuv run {baseDir}/scripts/watchlist.py add AAPL --target 200\n\n# With stop loss alert\nuv run {baseDir}/scripts/watchlist.py add AAPL --stop 150\n\n# Alert on signal change (BUY→SELL)\nuv run {baseDir}/scripts/watchlist.py add AAPL --alert-on signal\n\n# View watchlist\nuv run {baseDir}/scripts/watchlist.py list\n\n# Check for triggered alerts\nuv run {baseDir}/scripts/watchlist.py check\nuv run {baseDir}/scripts/watchlist.py check --notify  # Telegram format\n\n# Remove from watchlist\nuv run {baseDir}/scripts/watchlist.py remove AAPL\n```\n\n**Alert Types:**\n- 🎯 **Target Hit** — Price >= target\n- 🛑 **Stop Hit** — Price <= stop\n- 📊 **Signal Change** — BUY/HOLD/SELL changed\n\n### Portfolio Management\n```bash\n# Create portfolio\nuv run {baseDir}/scripts/portfolio.py create \"Tech Portfolio\"\n\n# Add assets\nuv run {baseDir}/scripts/portfolio.py add AAPL --quantity 100 --cost 150\nuv run {baseDir}/scripts/portfolio.py add BTC-USD --quantity 0.5 --cost 40000\n\n# View portfolio\nuv run {baseDir}/scripts/portfolio.py show\n\n# Analyze with period returns\nuv run {baseDir}/scripts/analyze_stock.py --portfolio \"Tech Portfolio\" --period weekly\n```\n\n### 🔥 Hot Scanner (NEW v6.1)\n```bash\n# Full scan - find what's trending NOW\npython3 {baseDir}/scripts/hot_scanner.py\n\n# Fast scan (skip social media)\npython3 {baseDir}/scripts/hot_scanner.py --no-social\n\n# JSON output for automation\npython3 {baseDir}/scripts/hot_scanner.py --json\n```\n\n**Data Sources:**\n- 📊 CoinGecko Trending — Top 15 trending coins\n- 📈 CoinGecko Movers — Biggest gainers/losers\n- 📰 Google News — Finance & crypto headlines\n- 📉 Yahoo Finance — Gainers, losers, most active\n- 🐦 Twitter/X — Social sentiment (requires auth)\n\n**Output:**\n- Top trending by mention count\n- Crypto highlights with 24h changes\n- Stock movers by category\n- Breaking news with tickers\n\n**Twitter Setup (Optional):**\n1. Install bird: `npm install -g @steipete/bird`\n2. Login to x.com in Safari/Chrome\n3. Create `.env` with `AUTH_TOKEN` and `CT0`\n\n### 🔮 Rumor Scanner (NEW v6.2)\n```bash\n# Find early signals, M&A rumors, insider activity\npython3 {baseDir}/scripts/rumor_scanner.py\n```\n\n**What it finds:**\n- 🏢 **M&A Rumors** — Merger, acquisition, takeover bids\n- 👔 **Insider Activity** — CEO/Director buying/selling\n- 📊 **Analyst Actions** — Upgrades, downgrades, price target changes\n- 🐦 **Twitter Whispers** — \"hearing that...\", \"sources say...\", \"rumor\"\n- ⚖️ **SEC Activity** — Investigations, filings\n\n**Impact Scoring:**\n- Each rumor is scored by potential market impact (1-10)\n- M&A/Takeover: +5 points\n- Insider buying: +4 points\n- Upgrade/Downgrade: +3 points\n- \"Hearing\"/\"Sources say\": +2 points\n- High engagement: +2 bonus\n\n**Best Practice:** Run at 07:00 before US market open to catch pre-market signals.\n\n## Analysis Dimensions (8 for stocks, 3 for crypto)\n\n### Stocks\n| Dimension | Weight | Description |\n|-----------|--------|-------------|\n| Earnings Surprise | 30% | EPS beat/miss |\n| Fundamentals | 20% | P/E, margins, growth |\n| Analyst Sentiment | 20% | Ratings, price targets |\n| Historical | 10% | Past earnings reactions |\n| Market Context | 10% | VIX, SPY/QQQ trends |\n| Sector | 15% | Relative strength |\n| Momentum | 15% | RSI, 52-week range |\n| Sentiment | 10% | Fear/Greed, shorts, insiders |\n\n### Crypto\n- Market Cap & Category\n- BTC Correlation (30-day)\n- Momentum (RSI, range)\n\n## Sentiment Sub-Indicators\n\n| Indicator | Source | Signal |\n|-----------|--------|--------|\n| Fear & Greed | CNN | Contrarian (fear=buy) |\n| Short Interest | Yahoo | Squeeze potential |\n| VIX Structure | Futures | Stress detection |\n| Insider Trades | SEC EDGAR | Smart money |\n| Put/Call Ratio | Options | Sentiment extreme |\n\n## Risk Detection\n\n- ⚠️ **Pre-Earnings** — Warns if < 14 days to earnings\n- ⚠️ **Post-Spike** — Flags if up >15% in 5 days\n- ⚠️ **Overbought** — RSI >70 + near 52w high\n- ⚠️ **Risk-Off** — GLD/TLT/UUP rising together\n- ⚠️ **Geopolitical** — Taiwan, China, Russia, Middle East keywords\n- ⚠️ **Breaking News** — Crisis keywords in last 24h\n\n## Performance Options\n\n| Flag | Effect | Speed |\n|------|--------|-------|\n| (default) | Full analysis | 5-10s |\n| `--no-insider` | Skip SEC EDGAR | 3-5s |\n| `--fast` | Skip insider + news | 2-3s |\n\n## Supported Cryptos (Top 20)\n\nBTC, ETH, BNB, SOL, XRP, ADA, DOGE, AVAX, DOT, MATIC, LINK, ATOM, UNI, LTC, BCH, XLM, ALGO, VET, FIL, NEAR\n\n(Use `-USD` suffix: `BTC-USD`, `ETH-USD`)\n\n## Data Storage\n\n| File | Location |\n|------|----------|\n| Portfolios | `~/.clawdbot/skills/stock-analysis/portfolios.json` |\n| Watchlist | `~/.clawdbot/skills/stock-analysis/watchlist.json` |\n\n## Limitations\n\n- Yahoo Finance may lag 15-20 minutes\n- Short interest lags ~2 weeks (FINRA)\n- Insider trades lag 2-3 days (SEC filing)\n- US markets only (non-US incomplete)\n- Breaking news: 1h cache, keyword-based\n\n## Disclaimer\n\n⚠️ **NOT FINANCIAL ADVICE.** For informational purposes only. Consult a licensed financial advisor before making investment decisions.\n\nFile v6.2.0:docs/README.md\n\n# Documentation\n\n## Stock Analysis v6.1\n\nThis folder contains detailed documentation for the Stock Analysis skill.\n\n## Contents\n\n| Document | Description |\n|----------|-------------|\n| [CONCEPT.md](./CONCEPT.md) | Philosophy, ideas, and design rationale |\n| [USAGE.md](./USAGE.md) | Practical usage guide with examples |\n| [ARCHITECTURE.md](./ARCHITECTURE.md) | Technical implementation details |\n| [HOT_SCANNER.md](./HOT_SCANNER.md) | 🔥 Viral trend detection (NEW) |\n\n## Quick Links\n\n### For Users\n\nStart with **[USAGE.md](./USAGE.md)** — it has practical examples for:\n- Basic stock analysis\n- Comparing stocks\n- Crypto analysis\n- Dividend investing\n- Portfolio management\n- Watchlist & alerts\n\n### For Understanding\n\nRead **[CONCEPT.md](./CONCEPT.md)** to understand:\n- Why 8 dimensions?\n- How scoring works\n- Contrarian signals\n- Risk detection philosophy\n- Limitations we acknowledge\n\n### For Developers\n\nCheck **[ARCHITECTURE.md](./ARCHITECTURE.md)** for:\n- System overview diagram\n- Data flow\n- Caching strategy\n- File structure\n- Performance optimization\n\n## Quick Start\n\n```bash\n# Analyze a stock\nuv run scripts/analyze_stock.py AAPL\n\n# Fast mode (2-3 seconds)\nuv run scripts/analyze_stock.py AAPL --fast\n\n# Dividend analysis\nuv run scripts/dividends.py JNJ\n\n# Watchlist\nuv run scripts/watchlist.py add AAPL --target 200\nuv run scripts/watchlist.py check\n```\n\n## Key Concepts\n\n### The 8 Dimensions\n\n1. **Earnings Surprise** (30%) — Did they beat expectations?\n2. **Fundamentals** (20%) — P/E, margins, growth, debt\n3. **Analyst Sentiment** (20%) — Professional consensus\n4. **Historical Patterns** (10%) — Past earnings reactions\n5. **Market Context** (10%) — VIX, SPY/QQQ trends\n6. **Sector Performance** (15%) — Relative strength\n7. **Momentum** (15%) — RSI, 52-week range\n8. **Sentiment** (10%) — Fear/Greed, shorts, insiders\n\n### Signal Thresholds\n\n| Score | Recommendation |\n|-------|----------------|\n| > +0.33 | **BUY** |\n| -0.33 to +0.33 | **HOLD** |\n| < -0.33 | **SELL** |\n\n### Risk Flags\n\n- ⚠️ Pre-earnings (< 14 days)\n- ⚠️ Post-spike (> 15% in 5 days)\n- ⚠️ Overbought (RSI > 70 + near 52w high)\n- ⚠️ Risk-off mode (GLD/TLT/UUP rising)\n- ⚠️ Geopolitical keywords\n- ⚠️ Breaking news alerts\n\n## Disclaimer\n\n⚠️ **NOT FINANCIAL ADVICE.** For informational purposes only. Always do your own research and consult a licensed financial advisor.\n\nFile v6.2.0:README.md\n\n# 📈 Stock Analysis v6.1\n\n> AI-powered stock & crypto analysis with portfolio management, watchlists, dividend analysis, and **viral trend detection**.\n\n[![ClawHub Downloads](https://img.shields.io/badge/ClawHub-1500%2B%20downloads-blue)](https://clawhub.ai)\n[![OpenClaw Skill](https://img.shields.io/badge/OpenClaw-Skill-green)](https://openclaw.ai)\n\n## What's New in v6.1\n\n- 🔥 **Hot Scanner** — Find viral stocks & crypto across multiple sources\n- 🐦 **Twitter/X Integration** — Social sentiment via bird CLI\n- 📰 **Multi-Source Aggregation** — CoinGecko, Google News, Yahoo Finance\n- ⏰ **Cron Support** — Daily trend reports\n\n## What's New in v6.0\n\n- 🆕 **Watchlist + Alerts** — Price targets, stop losses, signal change notifications\n- 🆕 **Dividend Analysis** — Yield, payout ratio, growth rate, safety score\n- 🆕 **Fast Mode** — Skip slow analyses for quick checks\n- 🆕 **Improved Commands** — Better OpenClaw/Telegram integration\n- 🆕 **Test Suite** — Unit tests for core functionality\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **8-Dimension Analysis** | Earnings, fundamentals, analysts, momentum, sentiment, sector, market, history |\n| **Crypto Support** | Top 20 cryptos with market cap, BTC correlation, momentum |\n| **Portfolio Management** | Track holdings, P&L, concentration warnings |\n| **Watchlist + Alerts** | Price targets, stop losses, signal changes |\n| **Dividend Analysis** | Yield, payout, growth, safety score |\n| **Risk Detection** | Geopolitical, earnings timing, overbought, risk-off |\n| **Breaking News** | Crisis keyword scanning (last 24h) |\n\n## Quick Start\n\n### Analyze Stocks\n```bash\nuv run scripts/analyze_stock.py AAPL\nuv run scripts/analyze_stock.py AAPL MSFT GOOGL\nuv run scripts/analyze_stock.py AAPL --fast  # Skip slow analyses\n```\n\n### Analyze Crypto\n```bash\nuv run scripts/analyze_stock.py BTC-USD\nuv run scripts/analyze_stock.py ETH-USD SOL-USD\n```\n\n### Dividend Analysis\n```bash\nuv run scripts/dividends.py JNJ PG KO\n```\n\n### Watchlist\n```bash\nuv run scripts/watchlist.py add AAPL --target 200 --stop 150\nuv run scripts/watchlist.py list\nuv run scripts/watchlist.py check --notify\n```\n\n### Portfolio\n```bash\nuv run scripts/portfolio.py create \"My Portfolio\"\nuv run scripts/portfolio.py add AAPL --quantity 100 --cost 150\nuv run scripts/portfolio.py show\n```\n\n### 🔥 Hot Scanner (NEW)\n```bash\n# Full scan with all sources\npython3 scripts/hot_scanner.py\n\n# Fast scan (skip social media)\npython3 scripts/hot_scanner.py --no-social\n\n# JSON output for automation\npython3 scripts/hot_scanner.py --json\n```\n\n## Analysis Dimensions\n\n### Stocks (8 dimensions)\n1. **Earnings Surprise** (30%) — EPS beat/miss\n2. **Fundamentals** (20%) — P/E, margins, growth, debt\n3. **Analyst Sentiment** (20%) — Ratings, price targets\n4. **Historical Patterns** (10%) — Past earnings reactions\n5. **Market Context** (10%) — VIX, SPY/QQQ trends\n6. **Sector Performance** (15%) — Relative strength\n7. **Momentum** (15%) — RSI, 52-week range\n8. **Sentiment** (10%) — Fear/Greed, shorts, insiders\n\n### Crypto (3 dimensions)\n- Market Cap & Category\n- BTC Correlation (30-day)\n- Momentum (RSI, range)\n\n## Dividend Metrics\n\n| Metric | Description |\n|--------|-------------|\n| Yield | Annual dividend / price |\n| Payout Ratio | Dividend / EPS |\n| 5Y Growth | CAGR of dividend |\n| Consecutive Years | Years of increases |\n| Safety Score | 0-100 composite |\n| Income Rating | Excellent → Poor |\n\n## 🔥 Hot Scanner\n\nFind what's trending RIGHT NOW across stocks & crypto.\n\n### Data Sources\n\n| Source | What it finds |\n|--------|---------------|\n| **CoinGecko Trending** | Top 15 trending coins |\n| **CoinGecko Movers** | Biggest gainers/losers (>3%) |\n| **Google News** | Breaking finance & crypto news |\n| **Yahoo Finance** | Top gainers, losers, most active |\n| **Twitter/X** | Social sentiment (requires auth) |\n\n### Output\n\n```\n📊 TOP TRENDING (by buzz):\n   1. BTC      (6 pts) [CoinGecko, Google News] 📉 bearish (-2.5%)\n   2. ETH      (5 pts) [CoinGecko, Twitter] 📉 bearish (-7.2%)\n   3. NVDA     (3 pts) [Google News, Yahoo] 📰 Earnings beat...\n\n🪙 CRYPTO HIGHLIGHTS:\n   🚀 RIVER    River              +14.0%\n   📉 BTC      Bitcoin             -2.5%\n\n📈 STOCK MOVERS:\n   🟢 NVDA (gainers)\n   🔴 TSLA (losers)\n\n📰 BREAKING NEWS:\n   [BTC, ETH] Crypto crash: $2.5B liquidated...\n```\n\n### Twitter/X Setup (Optional)\n\n1. Install bird CLI: `npm install -g @steipete/bird`\n2. Login to x.com in Safari/Chrome\n3. Create `.env` file:\n```\nAUTH_TOKEN=your_auth_token\nCT0=your_ct0_token\n```\n\nGet tokens from browser DevTools → Application → Cookies → x.com\n\n### Automation\n\nSet up a daily cron job for morning reports:\n```bash\n# Run at 8 AM daily\n0 8 * * * python3 /path/to/hot_scanner.py --no-social >> /var/log/hot_scanner.log\n```\n\n## Risk Detection\n\n- ⚠️ Pre-earnings warning (< 14 days)\n- ⚠️ Post-earnings spike (> 15% in 5 days)\n- ⚠️ Overbought (RSI > 70 + near 52w high)\n- ⚠️ Risk-off mode (GLD/TLT/UUP rising)\n- ⚠️ Geopolitical keywords (Taiwan, China, etc.)\n- ⚠️ Breaking news alerts\n\n## Performance Options\n\n| Flag | Speed | Description |\n|------|-------|-------------|\n| (default) | 5-10s | Full analysis |\n| `--no-insider` | 3-5s | Skip SEC EDGAR |\n| `--fast` | 2-3s | Skip insider + news |\n\n## Data Sources\n\n- [Yahoo Finance](https://finance.yahoo.com) — Prices, fundamentals, movers\n- [CoinGecko](https://coingecko.com) — Crypto trending, market data\n- [CNN Fear & Greed](https://money.cnn.com/data/fear-and-greed/) — Sentiment\n- [SEC EDGAR](https://www.sec.gov/edgar) — Insider trading\n- [Google News RSS](https://news.google.com) — Breaking news\n- [Twitter/X](https://x.com) — Social sentiment (via bird CLI)\n\n## Storage\n\n| Data | Location |\n|------|----------|\n| Portfolios | `~/.clawdbot/skills/stock-analysis/portfolios.json` |\n| Watchlist | `~/.clawdbot/skills/stock-analysis/watchlist.json` |\n\n## Testing\n\n```bash\nuv run pytest scripts/test_stock_analysis.py -v\n```\n\n## Limitations\n\n- Yahoo Finance may lag 15-20 minutes\n- Short interest lags ~2 weeks (FINRA)\n- US markets only\n\n## Disclaimer\n\n⚠️ **NOT FINANCIAL ADVICE.** For informational purposes only. Consult a licensed financial advisor before making investment decisions.\n\n---\n\nBuilt for [OpenClaw](https://openclaw.ai) 🦞 | [ClawHub](https://clawhub.ai)\n\nFile v6.2.0:_meta.json\n\n{\n  \"ownerId\": \"kn77fv9851hjcqe52zqx0bhhbx7z680h\",\n  \"slug\": \"stock-analysis\",\n  \"version\": \"6.2.0\",\n  \"publishedAt\": 1770041353575\n}\n\nFile v6.2.0:App-Plan.md\n\n# StockPulse - Commercial Product Roadmap\n\n## Vision\n\nTransform the stock-analysis skill into **StockPulse**, a commercial mobile app for retail investors with AI-powered stock and crypto analysis, portfolio tracking, and personalized alerts.\n\n## Technical Decisions\n\n- **Mobile:** Flutter (iOS + Android cross-platform)\n- **Backend:** Python FastAPI on AWS (ECS/Lambda)\n- **Database:** PostgreSQL (RDS) + Redis (ElastiCache)\n- **Auth:** AWS Cognito or Firebase Auth\n- **Monetization:** Freemium + Subscription ($9.99/mo or $79.99/yr)\n\n---\n\n## Architecture Overview\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                      MOBILE APP (Flutter)                        │\n│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │\n│  │Dashboard │ │Portfolio │ │ Analysis │ │ Alerts   │           │\n│  └──────────┘ └──────────┘ └──────────┘ └──────────┘           │\n└─────────────────────────────────────────────────────────────────┘\n                              │ HTTPS/REST\n                              ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                      API GATEWAY (AWS)                           │\n│                   Rate Limiting, Auth, Caching                   │\n└─────────────────────────────────────────────────────────────────┘\n                              │\n                              ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                   BACKEND (FastAPI on ECS)                       │\n│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │\n│  │ Auth Service │ │ Analysis API │ │ Portfolio API│            │\n│  └──────────────┘ └──────────────┘ └──────────────┘            │\n│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │\n│  │ Alerts Svc   │ │ Subscription │ │ User Service │            │\n│  └──────────────┘ └──────────────┘ └──────────────┘            │\n└─────────────────────────────────────────────────────────────────┘\n                              │\n        ┌─────────────────────┼─────────────────────┐\n        ▼                     ▼                     ▼\n┌──────────────┐     ┌──────────────┐     ┌──────────────┐\n│  PostgreSQL  │     │    Redis     │     │     S3       │\n│   (RDS)      │     │ (ElastiCache)│     │  (Reports)   │\n└──────────────┘     └──────────────┘     └──────────────┘\n\n                    BACKGROUND WORKERS (Lambda/ECS)\n┌─────────────────────────────────────────────────────────────────┐\n│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │\n│  │Price Updater │ │Alert Checker │ │Daily Reports │            │\n│  │  (5 min)     │ │  (1 min)     │ │  (Daily)     │            │\n│  └──────────────┘ └──────────────┘ └──────────────┘            │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Feature Tiers\n\n### Free Tier\n- 1 portfolio (max 10 assets)\n- Basic stock/crypto analysis\n- Daily market summary\n- Limited to 5 analyses/day\n- Ads displayed\n\n### Premium ($9.99/mo)\n- Unlimited portfolios & assets\n- Full 8-dimension analysis\n- Real-time price alerts\n- Push notifications\n- Period reports (daily/weekly/monthly)\n- No ads\n- Priority support\n\n### Pro ($19.99/mo) - Future\n- API access\n- Custom watchlists\n- Advanced screeners\n- Export to CSV/PDF\n- Portfolio optimization suggestions\n\n---\n\n## Development Phases\n\n### Phase 1: Backend API\n\n**Goal:** Convert Python scripts to production REST API\n\n#### Tasks:\n1. **Project Setup**\n   - FastAPI project structure\n   - Docker containerization\n   - CI/CD pipeline (GitHub Actions)\n   - AWS infrastructure (Terraform)\n\n2. **Core API Endpoints**\n   ```\n   POST /auth/register\n   POST /auth/login\n   POST /auth/refresh\n\n   GET  /analysis/{ticker}\n   POST /analysis/batch\n\n   GET  /portfolios\n   POST /portfolios\n   PUT  /portfolios/{id}\n   DELETE /portfolios/{id}\n\n   GET  /portfolios/{id}/assets\n   POST /portfolios/{id}/assets\n   PUT  /portfolios/{id}/assets/{ticker}\n   DELETE /portfolios/{id}/assets/{ticker}\n\n   GET  /portfolios/{id}/performance?period=weekly\n   GET  /portfolios/{id}/summary\n\n   GET  /alerts\n   POST /alerts\n   DELETE /alerts/{id}\n\n   GET  /user/subscription\n   POST /user/subscription/upgrade\n   ```\n\n3. **Database Schema**\n   ```sql\n   users (id, email, password_hash, created_at, subscription_tier)\n   portfolios (id, user_id, name, created_at, updated_at)\n   assets (id, portfolio_id, ticker, asset_type, quantity, cost_basis)\n   alerts (id, user_id, ticker, condition, threshold, enabled)\n   analysis_cache (ticker, data, expires_at)\n   subscriptions (id, user_id, stripe_id, status, expires_at)\n   ```\n\n4. **Refactor Existing Code**\n   - Extract `analyze_stock.py` into modules:\n     - `analysis/earnings.py`\n     - `analysis/fundamentals.py`\n     - `analysis/sentiment.py`\n     - `analysis/crypto.py`\n     - `analysis/market_context.py`\n   - Add async support throughout\n   - Implement proper caching (Redis)\n   - Rate limiting per user tier\n\n#### Files to Create:\n```\nbackend/\n├── app/\n│   ├── main.py              # FastAPI app\n│   ├── config.py            # Settings\n│   ├── models/              # SQLAlchemy models\n│   ├── schemas/             # Pydantic schemas\n│   ├── routers/             # API routes\n│   │   ├── auth.py\n│   │   ├── analysis.py\n│   │   ├── portfolios.py\n│   │   └── alerts.py\n│   ├── services/            # Business logic\n│   │   ├── analysis/        # Refactored from analyze_stock.py\n│   │   ├── portfolio.py\n│   │   └── alerts.py\n│   └── workers/             # Background tasks\n├── tests/\n├── Dockerfile\n├── docker-compose.yml\n└── requirements.txt\n```\n\n---\n\n### Phase 2: Flutter Mobile App\n\n**Goal:** Build polished cross-platform mobile app\n\n#### Screens:\n1. **Onboarding** - Welcome, feature highlights, sign up/login\n2. **Dashboard** - Market overview, portfolio summary, alerts\n3. **Analysis** - Search ticker, view full analysis, save to portfolio\n4. **Portfolio** - List portfolios, asset breakdown, P&L chart\n5. **Alerts** - Manage price alerts, notification settings\n6. **Settings** - Account, subscription, preferences\n\n#### Key Flutter Packages:\n```yaml\ndependencies:\n  flutter_bloc: ^8.0.0      # State management\n  dio: ^5.0.0               # HTTP client\n  go_router: ^12.0.0        # Navigation\n  fl_chart: ^0.65.0         # Charts\n  firebase_messaging: ^14.0.0  # Push notifications\n  in_app_purchase: ^3.0.0   # Subscriptions\n  shared_preferences: ^2.0.0\n  flutter_secure_storage: ^9.0.0\n```\n\n#### App Structure:\n```\nlib/\n├── main.dart\n├── app/\n│   ├── routes.dart\n│   └── theme.dart\n├── features/\n│   ├── auth/\n│   │   ├── bloc/\n│   │   ├── screens/\n│   │   └── widgets/\n│   ├── dashboard/\n│   ├── analysis/\n│   ├── portfolio/\n│   ├── alerts/\n│   └── settings/\n├── core/\n│   ├── api/\n│   ├── models/\n│   └── utils/\n└── shared/\n    └── widgets/\n```\n\n---\n\n### Phase 3: Infrastructure & DevOps\n\n**Goal:** Production-ready cloud infrastructure\n\n#### AWS Services:\n- **ECS Fargate** - Backend containers\n- **RDS PostgreSQL** - Database\n- **ElastiCache Redis** - Caching\n- **S3** - Static assets, reports\n- **CloudFront** - CDN\n- **Cognito** - Authentication\n- **SES** - Email notifications\n- **SNS** - Push notifications\n- **CloudWatch** - Monitoring\n- **WAF** - Security\n\n#### Terraform Modules:\n```\ninfrastructure/\n├── main.tf\n├── variables.tf\n├── modules/\n│   ├── vpc/\n│   ├── ecs/\n│   ├── rds/\n│   ├── elasticache/\n│   └── cognito/\n└── environments/\n    ├── dev/\n    ├── staging/\n    └── prod/\n```\n\n#### Estimated Monthly Costs (Production):\n| Service | Est. Cost |\n|---------|-----------|\n| ECS Fargate (2 tasks) | $50-100 |\n| RDS (db.t3.small) | $30-50 |\n| ElastiCache (cache.t3.micro) | $15-25 |\n| S3 + CloudFront | $10-20 |\n| Other (Cognito, SES, etc.) | $20-30 |\n| **Total** | **$125-225/mo** |\n\n---\n\n### Phase 4: Payments & Subscriptions\n\n**Goal:** Integrate Stripe for subscriptions\n\n#### Implementation:\n1. Stripe subscription products (Free, Premium, Pro)\n2. In-app purchase for iOS/Android\n3. Webhook handlers for subscription events\n4. Grace period handling\n5. Receipt validation\n\n#### Stripe Integration:\n```python\n# Backend webhook handler\n@router.post(\"/webhooks/stripe\")\nasync def stripe_webhook(request: Request):\n    event = stripe.Webhook.construct_event(...)\n\n    if event.type == \"customer.subscription.updated\":\n        update_user_tier(event.data.object)\n    elif event.type == \"customer.subscription.deleted\":\n        downgrade_to_free(event.data.object)\n```\n\n---\n\n### Phase 5: Push Notifications & Alerts\n\n**Goal:** Real-time price alerts and notifications\n\n#### Alert Types:\n- Price above/below threshold\n- Percentage change (daily)\n- Earnings announcement\n- Breaking news (geopolitical)\n- Portfolio performance\n\n#### Implementation:\n- Firebase Cloud Messaging (FCM)\n- Background worker checks alerts every minute\n- Rate limit: max 10 alerts/day per free user\n\n---\n\n### Phase 6: Analytics & Monitoring\n\n**Goal:** Track usage, errors, business metrics\n\n#### Tools:\n- **Mixpanel/Amplitude** - Product analytics\n- **Sentry** - Error tracking\n- **CloudWatch** - Infrastructure metrics\n- **Custom dashboard** - Business KPIs\n\n#### Key Metrics:\n- DAU/MAU\n- Conversion rate (free → premium)\n- Churn rate\n- API response times\n- Analysis accuracy feedback\n\n---\n\n## Security Considerations\n\n1. **Authentication**\n   - JWT tokens with refresh rotation\n   - OAuth2 (Google, Apple Sign-In)\n   - 2FA optional for premium users\n\n2. **Data Protection**\n   - Encrypt PII at rest (RDS encryption)\n   - TLS 1.3 for all API traffic\n   - No plaintext passwords\n\n3. **API Security**\n   - Rate limiting per tier\n   - Input validation (Pydantic)\n   - SQL injection prevention (SQLAlchemy ORM)\n   - CORS configuration\n\n4. **Compliance**\n   - Privacy policy\n   - Terms of service\n   - GDPR data export/deletion\n   - Financial disclaimer (not investment advice)\n\n---\n\n## Risks & Mitigations\n\n| Risk | Impact | Mitigation |\n|------|--------|------------|\n| Yahoo Finance rate limits | High | Implement caching, use paid API fallback |\n| App store rejection | Medium | Follow guidelines, proper disclaimers |\n| Data accuracy issues | High | Clear disclaimers, data validation |\n| Security breach | Critical | Security audit, penetration testing |\n| Low conversion rate | Medium | A/B testing, feature gating |\n\n---\n\n## Success Metrics (Year 1)\n\n| Metric | Target |\n|--------|--------|\n| App downloads | 10,000+ |\n| DAU | 1,000+ |\n| Premium subscribers | 500+ |\n| Monthly revenue | $5,000+ |\n| App store rating | 4.5+ stars |\n| Churn rate | <5%/month |\n\n---\n\n## Next Steps (Immediate)\n\n1. **Validate idea** - User interviews, landing page\n2. **Design** - Figma mockups for key screens\n3. **Backend MVP** - Core API endpoints\n4. **Flutter prototype** - Basic app with analysis feature\n5. **Beta testing** - TestFlight/Google Play beta\n\n---\n\n## Repository Structure (Final)\n\n```\nstockpulse/\n├── backend/                 # FastAPI backend\n│   ├── app/\n│   ├── tests/\n│   ├── Dockerfile\n│   └── requirements.txt\n├── mobile/                  # Flutter app\n│   ├── lib/\n│   ├── test/\n│   ├── ios/\n│   ├── android/\n│   └── pubspec.yaml\n├── infrastructure/          # Terraform\n│   ├── modules/\n│   └── environments/\n├── docs/                    # Documentation\n│   ├── api/\n│   └── architecture/\n└── scripts/                 # Utility scripts\n```\n\n---\n\n## Timeline Summary (Planning Only)\n\n| Phase | Duration | Dependencies |\n|-------|----------|--------------|\n| 1. Backend API | 4-6 weeks | - |\n| 2. Flutter App | 6-8 weeks | Phase 1 |\n| 3. Infrastructure | 2-3 weeks | Phase 1 |\n| 4. Payments | 2 weeks | Phase 2, 3 |\n| 5. Notifications | 2 weeks | Phase 2, 3 |\n| 6. Analytics | 1 week | Phase 2 |\n| **Total** | **17-22 weeks** | |\n\nThis is a planning document. No fixed timeline - execute phases as resources allow.\n\n---\n\n**Disclaimer:** This tool is for informational purposes only and does NOT constitute financial advice.\n\nFile v6.2.0:docs/ARCHITECTURE.md\n\n# Technical Architecture\n\nHow Stock Analysis v6.0 works under the hood.\n\n## System Overview\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                        Stock Analysis v6.0                           │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                      │\n│  ┌──────────────────────────────────────────────────────────────┐   │\n│  │                    CLI Interface                              │   │\n│  │  analyze_stock.py | dividends.py | watchlist.py | portfolio.py│   │\n│  └────────────────────────────┬─────────────────────────────────┘   │\n│                               │                                      │\n│  ┌────────────────────────────▼─────────────────────────────────┐   │\n│  │                   Analysis Engine                             │   │\n│  │                                                               │   │\n│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐            │   │\n│  │  │Earnings │ │Fundmtls │ │Analysts │ │Historical│            │   │\n│  │  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘            │   │\n│  │       │           │           │           │                   │   │\n│  │  ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐            │   │\n│  │  │ Market  │ │ Sector  │ │Momentum │ │Sentiment│            │   │\n│  │  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘            │   │\n│  │       │           │           │           │                   │   │\n│  │       └───────────┴───────────┴───────────┘                   │   │\n│  │                          │                                    │   │\n│  │                    [Synthesizer]                              │   │\n│  │                          │                                    │   │\n│  │                    [Signal Output]                            │   │\n│  └──────────────────────────────────────────────────────────────┘   │\n│                               │                                      │\n│  ┌────────────────────────────▼─────────────────────────────────┐   │\n│  │                    Data Sources                               │   │\n│  │                                                               │   │\n│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐            │   │\n│  │  │ Yahoo   │ │  CNN    │ │   SEC   │ │ Google  │            │   │\n│  │  │ Finance │ │Fear/Grd │ │ EDGAR   │ │  News   │            │   │\n│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘            │   │\n│  └──────────────────────────────────────────────────────────────┘   │\n│                                                                      │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Core Components\n\n### 1. Data Fetching (`fetch_stock_data`)\n\n```python\ndef fetch_stock_data(ticker: str, verbose: bool = False) -> StockData | None:\n    \"\"\"Fetch stock data from Yahoo Finance with retry logic.\"\"\"\n```\n\n**Features:**\n- 3 retries with exponential backoff\n- Graceful handling of missing data\n- Asset type detection (stock vs crypto)\n\n**Returns:** `StockData` dataclass with:\n- `info`: Company fundamentals\n- `earnings_history`: Past earnings\n- `analyst_info`: Ratings and targets\n- `price_history`: 1-year OHLCV\n\n### 2. Analysis Modules\n\nEach dimension has its own analyzer:\n\n| Module | Function | Returns |\n|--------|----------|---------|\n| Earnings | `analyze_earnings_surprise()` | `EarningsSurprise` |\n| Fundamentals | `analyze_fundamentals()` | `Fundamentals` |\n| Analysts | `analyze_analyst_sentiment()` | `AnalystSentiment` |\n| Historical | `analyze_historical_patterns()` | `HistoricalPatterns` |\n| Market | `analyze_market_context()` | `MarketContext` |\n| Sector | `analyze_sector_performance()` | `SectorComparison` |\n| Momentum | `analyze_momentum()` | `MomentumAnalysis` |\n| Sentiment | `analyze_sentiment()` | `SentimentAnalysis` |\n\n### 3. Sentiment Sub-Analyzers\n\nSentiment runs 5 parallel async tasks:\n\n```python\nresults = await asyncio.gather(\n    get_fear_greed_index(),      # CNN Fear & Greed\n    get_short_interest(data),    # Yahoo Finance\n    get_vix_term_structure(),    # VIX Futures\n    get_insider_activity(),      # SEC EDGAR\n    get_put_call_ratio(data),    # Options Chain\n    return_exceptions=True\n)\n```\n\n**Timeout:** 10 seconds per indicator\n**Minimum:** 2 of 5 indicators required\n\n### 4. Signal Synthesis\n\n```python\ndef synthesize_signal(\n    ticker, company_name,\n    earnings, fundamentals, analysts, historical,\n    market_context, sector, earnings_timing,\n    momentum, sentiment,\n    breaking_news, geopolitical_risk_warning, geopolitical_risk_penalty\n) -> Signal:\n```\n\n**Scoring:**\n1. Collect available component scores\n2. Apply normalized weights\n3. Calculate weighted average → `final_score`\n4. Apply adjustments (timing, overbought, risk-off)\n5. Determine recommendation threshold\n\n**Thresholds:**\n```python\nif final_score > 0.33:\n    recommendation = \"BUY\"\nelif final_score < -0.33:\n    recommendation = \"SELL\"\nelse:\n    recommendation = \"HOLD\"\n```\n\n---\n\n## Caching Strategy\n\n### What's Cached\n\n| Data | TTL | Key |\n|------|-----|-----|\n| Market Context | 1 hour | `market_context` |\n| Fear & Greed | 1 hour | `fear_greed` |\n| VIX Structure | 1 hour | `vix_structure` |\n| Breaking News | 1 hour | `breaking_news` |\n\n### Cache Implementation\n\n```python\n_SENTIMENT_CACHE = {}\n_CACHE_TTL_SECONDS = 3600  # 1 hour\n\ndef _get_cached(key: str):\n    if key in _SENTIMENT_CACHE:\n        value, timestamp = _SENTIMENT_CACHE[key]\n        if time.time() - timestamp < _CACHE_TTL_SECONDS:\n            return value\n    return None\n\ndef _set_cache(key: str, value):\n    _SENTIMENT_CACHE[key] = (value, time.time())\n```\n\n### Why This Matters\n\n- First stock: ~8 seconds (full fetch)\n- Second stock: ~4 seconds (reuses market data)\n- Same stock again: ~4 seconds (no stock-level cache)\n\n---\n\n## Data Flow\n\n### Single Stock Analysis\n\n```\nUser Input: \"AAPL\"\n     │\n     ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 1. FETCH DATA (yfinance)                                    │\n│    - Stock info, earnings, price history                    │\n│    - ~2 seconds                                             │\n└────────────────────────┬────────────────────────────────────┘\n                         │\n                         ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 2. PARALLEL ANALYSIS                                        │\n│                                                             │\n│    ┌──────────┐ ┌──────────┐ ┌──────────┐                  │\n│    │ Earnings │ │Fundmtls  │ │ Analysts │  ... (sync)      │\n│    └──────────┘ └──────────┘ └──────────┘                  │\n│                                                             │\n│    ┌────────────────────────────────────┐                  │\n│    │ Market Context (cached or fetch)   │  ~1 second       │\n│    └────────────────────────────────────┘                  │\n│                                                             │\n│    ┌────────────────────────────────────┐                  │\n│    │ Sentiment (5 async tasks)          │  ~3-5 seconds    │\n│    │  - Fear/Greed (cached)             │                  │\n│    │  - Short Interest                  │                  │\n│    │  - VIX Structure (cached)          │                  │\n│    │  - Insider Trading (slow!)         │                  │\n│    │  - Put/Call Ratio                  │                  │\n│    └────────────────────────────────────┘                  │\n└────────────────────────┬────────────────────────────────────┘\n                         │\n                         ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 3. SYNTHESIZE SIGNAL                                        │\n│    - Combine scores with weights                            │\n│    - Apply adjustments                                      │\n│    - Generate caveats                                       │\n│    - ~10 ms                                                 │\n└────────────────────────┬────────────────────────────────────┘\n                         │\n                         ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 4. OUTPUT                                                   │\n│    - Text or JSON format                                    │\n│    - Include disclaimer                                     │\n└─────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Risk Detection\n\n### Geopolitical Risk\n\n```python\nGEOPOLITICAL_RISK_MAP = {\n    \"taiwan\": {\n        \"keywords\": [\"taiwan\", \"tsmc\", \"strait\"],\n        \"sectors\": [\"Technology\", \"Communication Services\"],\n        \"affected_tickers\": [\"NVDA\", \"AMD\", \"TSM\", ...],\n        \"impact\": \"Semiconductor supply chain disruption\",\n    },\n    # ... china, russia_ukraine, middle_east, banking_crisis\n}\n```\n\n**Process:**\n1. Check breaking news for keywords\n2. If keyword found, check if ticker in affected list\n3. Apply confidence penalty (30% direct, 15% sector)\n\n### Breaking News\n\n```python\ndef check_breaking_news(verbose: bool = False) -> list[str] | None:\n    \"\"\"Scan Google News RSS for crisis keywords (last 24h).\"\"\"\n```\n\n**Crisis Keywords:**\n```python\nCRISIS_KEYWORDS = {\n    \"war\": [\"war\", \"invasion\", \"military strike\", ...],\n    \"economic\": [\"recession\", \"crisis\", \"collapse\", ...],\n    \"regulatory\": [\"sanctions\", \"embargo\", \"ban\", ...],\n    \"disaster\": [\"earthquake\", \"hurricane\", \"pandemic\", ...],\n    \"financial\": [\"emergency rate\", \"bailout\", ...],\n}\n```\n\n---\n\n## File Structure\n\n```\nstock-analysis/\n├── scripts/\n│   ├── analyze_stock.py      # Main analysis engine (2500+ lines)\n│   ├── portfolio.py          # Portfolio management\n│   ├── dividends.py          # Dividend analysis\n│   ├── watchlist.py          # Watchlist + alerts\n│   └── test_stock_analysis.py # Unit tests\n├── docs/\n│   ├── CONCEPT.md            # Philosophy & ideas\n│   ├── USAGE.md              # Practical guide\n│   └── ARCHITECTURE.md       # This file\n├── SKILL.md                  # OpenClaw skill definition\n├── README.md                 # Project overview\n└── .clawdhub/                # ClawHub metadata\n```\n\n---\n\n## Data Storage\n\n### Portfolio (`portfolios.json`)\n\n```json\n{\n  \"portfolios\": [\n    {\n      \"name\": \"Retirement\",\n      \"created_at\": \"2024-01-01T00:00:00Z\",\n      \"assets\": [\n        {\n          \"ticker\": \"AAPL\",\n          \"quantity\": 100,\n          \"cost_basis\": 150.00,\n          \"type\": \"stock\",\n          \"added_at\": \"2024-01-01T00:00:00Z\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n### Watchlist (`watchlist.json`)\n\n```json\n[\n  {\n    \"ticker\": \"NVDA\",\n    \"added_at\": \"2024-01-15T10:30:00Z\",\n    \"price_at_add\": 700.00,\n    \"target_price\": 800.00,\n    \"stop_price\": 600.00,\n    \"alert_on_signal\": true,\n    \"last_signal\": \"BUY\",\n    \"last_check\": \"2024-01-20T08:00:00Z\"\n  }\n]\n```\n\n---\n\n## Dependencies\n\n```python\n# /// script\n# requires-python = \">=3.10\"\n# dependencies = [\n#     \"yfinance>=0.2.40\",      # Stock data\n#     \"pandas>=2.0.0\",         # Data manipulation\n#     \"fear-and-greed>=0.4\",   # CNN Fear & Greed\n#     \"edgartools>=2.0.0\",     # SEC EDGAR filings\n#     \"feedparser>=6.0.0\",     # RSS parsing\n# ]\n# ///\n```\n\n**Why These:**\n- `yfinance`: Most reliable free stock API\n- `pandas`: Industry standard for financial data\n- `fear-and-greed`: Simple CNN F&G wrapper\n- `edgartools`: Clean SEC EDGAR access\n- `feedparser`: Robust RSS parsing\n\n---\n\n## Performance Optimization\n\n### Current\n\n| Operation | Time |\n|-----------|------|\n| yfinance fetch | ~2s |\n| Market context | ~1s (cached after) |\n| Insider trading | ~3-5s (slowest!) |\n| Sentiment (parallel) | ~3-5s |\n| Synthesis | ~10ms |\n| **Total** | **5-10s** |\n\n### Fast Mode (`--fast`)\n\nSkips:\n- Insider trading (SEC EDGAR)\n- Breaking news scan\n\n**Result:** 2-3 seconds\n\n### Future Optimizations\n\n1. **Stock-level caching** — Cache fundamentals for 24h\n2. **Batch API calls** — yfinance supports multiple tickers\n3. **Background refresh** — Pre-fetch watchlist data\n4. **Local SEC data** — Avoid EDGAR API calls\n\n---\n\n## Error Handling\n\n### Retry Strategy\n\n```python\nmax_retries = 3\nfor attempt in range(max_retries):\n    try:\n        # fetch data\n    except Exception as e:\n        wait_time = 2 ** attempt  # Exponential backoff: 1, 2, 4 seconds\n        time.sleep(wait_time)\n```\n\n### Graceful Degradation\n\n- Missing earnings → Skip dimension, reweight\n- Missing analysts → Skip dimension, reweight\n- Missing sentiment → Skip dimension, reweight\n- API failure → Return None, continue with partial data\n\n### Minimum Requirements\n\n- At least 2 of 8 dimensions required\n- At least 2 of 5 sentiment indicators required\n- Otherwise → HOLD with low confidence\n\nFile v6.2.0:docs/CONCEPT.md\n\n# Concept & Philosophy\n\n## The Problem\n\nMaking investment decisions is hard. There's too much data, too many opinions, and too much noise. Most retail investors either:\n\n1. **Over-simplify** — Buy based on headlines or tips\n2. **Over-complicate** — Get lost in endless research\n3. **Freeze** — Analysis paralysis, never act\n\n## The Solution\n\nStock Analysis provides a **structured, multi-dimensional framework** that:\n\n- Aggregates data from multiple sources\n- Weighs different factors objectively\n- Produces a clear **BUY / HOLD / SELL** signal\n- Explains the reasoning with bullet points\n- Flags risks and caveats\n\nThink of it as a **second opinion** — not a replacement for your judgment, but a systematic check.\n\n---\n\n## Core Philosophy\n\n### 1. Multiple Perspectives Beat Single Metrics\n\nNo single metric tells the whole story:\n- A low P/E might mean \"cheap\" or \"dying business\"\n- High analyst ratings might mean \"priced in\" or \"genuine upside\"\n- Strong momentum might mean \"trend\" or \"overbought\"\n\nBy combining **8 dimensions**, we get a more complete picture.\n\n### 2. Contrarian Signals Matter\n\nSome of our best signals are **contrarian**:\n\n| Indicator | Crowd Says | We Interpret |\n|-----------|------------|--------------|\n| Extreme Fear (Fear & Greed < 25) | \"Sell everything!\" | Potential buy opportunity |\n| Extreme Greed (> 75) | \"Easy money!\" | Caution, reduce exposure |\n| High Short Interest + Days to Cover | \"Stock is doomed\" | Squeeze potential |\n| Insider Buying | (often ignored) | Smart money signal |\n\n### 3. Timing Matters\n\nA good stock at the wrong time is a bad trade:\n\n- **Pre-earnings** — Even strong stocks can gap down 10%+\n- **Post-spike** — Buying after a 20% run often means buying the top\n- **Overbought** — RSI > 70 + near 52-week high = high-risk entry\n\nWe detect these timing issues and adjust recommendations accordingly.\n\n### 4. Context Changes Everything\n\nThe same stock behaves differently in different market regimes:\n\n| Regime | Characteristics | Impact |\n|--------|-----------------|--------|\n| **Bull** | VIX < 20, SPY up | BUY signals more reliable |\n| **Bear** | VIX > 30, SPY down | Even good stocks fall |\n| **Risk-Off** | GLD/TLT/UUP rising | Flight to safety, reduce equity |\n| **Geopolitical** | Crisis keywords | Sector-specific penalties |\n\n### 5. Dividends Are Different\n\nIncome investors have different priorities than growth investors:\n\n| Growth Investor | Income Investor |\n|-----------------|-----------------|\n| Price appreciation | Dividend yield |\n| Revenue growth | Payout sustainability |\n| Market share | Dividend growth rate |\n| P/E ratio | Safety of payment |\n\nThat's why we have a **separate dividend analysis** module.\n\n---\n\n## The 8 Dimensions\n\n### Why These 8?\n\nEach dimension captures a different aspect of investment quality:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    FUNDAMENTAL VALUE                         │\n│  ┌─────────────────┐  ┌─────────────────┐                   │\n│  │    Earnings     │  │  Fundamentals   │                   │\n│  │    Surprise     │  │   (P/E, etc.)   │                   │\n│  │     (30%)       │  │     (20%)       │                   │\n│  └─────────────────┘  └─────────────────┘                   │\n├─────────────────────────────────────────────────────────────┤\n│                    EXTERNAL VALIDATION                       │\n│  ┌─────────────────┐  ┌─────────────────┐                   │\n│  │    Analyst      │  │   Historical    │                   │\n│  │   Sentiment     │  │    Patterns     │                   │\n│  │     (20%)       │  │     (10%)       │                   │\n│  └─────────────────┘  └─────────────────┘                   │\n├─────────────────────────────────────────────────────────────┤\n│                    MARKET ENVIRONMENT                        │\n│  ┌─────────────────┐  ┌─────────────────┐                   │\n│  │    Market       │  │     Sector      │                   │\n│  │    Context      │  │  Performance    │                   │\n│  │     (10%)       │  │     (15%)       │                   │\n│  └─────────────────┘  └─────────────────┘                   │\n├─────────────────────────────────────────────────────────────┤\n│                    TECHNICAL & SENTIMENT                     │\n│  ┌─────────────────┐  ┌─────────────────┐                   │\n│  │    Momentum     │  │   Sentiment     │                   │\n│  │  (RSI, range)   │  │ (Fear, shorts)  │                   │\n│  │     (15%)       │  │     (10%)       │                   │\n│  └─────────────────┘  └─────────────────┘                   │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Weight Rationale\n\n| Weight | Dimension | Rationale |\n|--------|-----------|-----------|\n| 30% | Earnings | Most direct measure of company performance |\n| 20% | Fundamentals | Long-term value indicators |\n| 20% | Analysts | Professional consensus (with skepticism) |\n| 15% | Sector | Relative performance matters |\n| 15% | Momentum | Trend is your friend (until it isn't) |\n| 10% | Market | Rising tide lifts all boats |\n| 10% | Sentiment | Contrarian edge |\n| 10% | Historical | Past behavior predicts future reactions |\n\n**Note:** Weights auto-normalize when data is missing.\n\n---\n\n## Risk Detection Philosophy\n\n### \"Don't Lose Money\"\n\nWarren Buffett's Rule #1. Our risk detection is designed to **prevent bad entries**:\n\n1. **Pre-Earnings Hold** — Don't buy right before a binary event\n2. **Post-Spike Caution** — Don't chase a run-up\n3. **Overbought Warning** — Technical exhaustion\n4. **Risk-Off Mode** — When even good stocks fall\n5. **Geopolitical Flags** — Sector-specific event risk\n\n### False Positive vs False Negative\n\nWe err on the side of **caution**:\n\n- Missing a 10% gain is annoying\n- Catching a 30% loss is devastating\n\nThat's why our caveats are prominent, and we downgrade BUY → HOLD liberally.\n\n---\n\n## Crypto Adaptation\n\nCrypto is fundamentally different from stocks:\n\n| Stocks | Crypto |\n|--------|--------|\n| Earnings | No earnings |\n| P/E Ratio | Market cap tiers |\n| Sector ETFs | BTC correlation |\n| Dividends | Staking yields (not tracked) |\n| SEC Filings | No filings |\n\nWe adapted the framework:\n- **3 dimensions** instead of 8\n- **BTC correlation** as a key metric\n- **Category classification** (L1, DeFi, etc.)\n- **No sentiment** (no insider data for crypto)\n\n---\n\n## Why Not Just Use [X]?\n\n### vs. Stock Screeners (Finviz, etc.)\n- Screeners show data, we provide **recommendations**\n- We combine fundamental + technical + sentiment\n- We flag timing and risk issues\n\n### vs. Analyst Reports\n- Analysts have conflicts of interest\n- Reports are often stale\n- We aggregate multiple signals\n\n### vs. Trading Bots\n- Bots execute, we advise\n- We explain reasoning\n- Human stays in control\n\n### vs. ChatGPT/AI Chat\n- We have **structured scoring**, not just conversation\n- Real-time data fetching\n- Consistent methodology\n\n---\n\n## Limitations We Acknowledge\n\n1. **Data Lag** — Yahoo Finance is 15-20 min delayed\n2. **US Focus** — International stocks have incomplete data\n3. **No Execution** — We advise, you decide and execute\n4. **Past ≠ Future** — All models have limits\n5. **Black Swans** — Can't predict unpredictable events\n\n**This is a tool, not a crystal ball.**\n\n---\n\n## The Bottom Line\n\nStock Analysis v6.0 is designed to be your **systematic second opinion**:\n\n- ✅ Multi-dimensional analysis\n- ✅ Clear recommendations\n- ✅ Risk detection\n- ✅ Explained reasoning\n- ✅ Fast and automated\n\n**NOT:**\n- ❌ Financial advice\n- ❌ Guaranteed returns\n- ❌ Replacement for research\n- ❌ Trading signals\n\nUse it wisely. 📈\n\nFile v6.2.0:docs/HOT_SCANNER.md\n\n# 🔥 Hot Scanner\n\nFind viral stocks & crypto trends in real-time by aggregating multiple data sources.\n\n## Overview\n\nThe Hot Scanner answers one question: **\"What's hot right now?\"**\n\nIt aggregates data from:\n- CoinGecko (trending coins, biggest movers)\n- Google News (finance & crypto headlines)\n- Yahoo Finance (gainers, losers, most active)\n- Twitter/X (social sentiment, optional)\n\n## Quick Start\n\n```bash\n# Full scan with all sources\npython3 scripts/hot_scanner.py\n\n# Skip social media (faster)\npython3 scripts/hot_scanner.py --no-social\n\n# JSON output for automation\npython3 scripts/hot_scanner.py --json\n```\n\n## Output Format\n\n### Console Output\n\n```\n============================================================\n🔥 HOT SCANNER v2 - What's Trending Right Now?\n📅 2026-02-02 10:45:30 UTC\n============================================================\n\n📊 TOP TRENDING (by buzz):\n   1. BTC      (6 pts) [CoinGecko, Google News] 📉 bearish (-2.5%)\n   2. ETH      (5 pts) [CoinGecko, Twitter] 📉 bearish (-7.2%)\n   3. NVDA     (3 pts) [Google News, Yahoo] 📰 Earnings beat...\n\n🪙 CRYPTO HIGHLIGHTS:\n   🚀 RIVER    River              +14.0%\n   📉 BTC      Bitcoin             -2.5%\n   📉 ETH      Ethereum            -7.2%\n\n📈 STOCK MOVERS:\n   🟢 NVDA (gainers)\n   🔴 TSLA (losers)\n   📊 AAPL (most active)\n\n🐦 SOCIAL BUZZ:\n   [twitter] Bitcoin to $100k prediction...\n   [reddit_wsb] GME yolo update...\n\n📰 BREAKING NEWS:\n   [BTC, ETH] Crypto crash: $2.5B liquidated...\n   [NVDA] Nvidia beats earnings expectations...\n```\n\n### JSON Output\n\n```json\n{\n  \"scan_time\": \"2026-02-02T10:45:30+00:00\",\n  \"top_trending\": [\n    {\n      \"symbol\": \"BTC\",\n      \"mentions\": 6,\n      \"sources\": [\"CoinGecko Trending\", \"Google News\"],\n      \"signals\": [\"📉 bearish (-2.5%)\"]\n    }\n  ],\n  \"crypto_highlights\": [...],\n  \"stock_highlights\": [...],\n  \"social_buzz\": [...],\n  \"breaking_news\": [...]\n}\n```\n\n## Data Sources\n\n### CoinGecko (No Auth Required)\n\n| Endpoint | Data |\n|----------|------|\n| `/search/trending` | Top 15 trending coins |\n| `/coins/markets` | Top 100 by market cap with 24h changes |\n\n**Scoring:** Trending coins get 2 points, movers with >3% change get 1 point.\n\n### Google News RSS (No Auth Required)\n\n| Feed | Content |\n|------|---------|\n| Business News | General finance headlines |\n| Crypto Search | Bitcoin, Ethereum, crypto keywords |\n\n**Ticker Extraction:** Uses regex patterns and company name mappings.\n\n### Yahoo Finance (No Auth Required)\n\n| Page | Data |\n|------|------|\n| `/gainers` | Top gaining stocks |\n| `/losers` | Top losing stocks |\n| `/most-active` | Highest volume stocks |\n\n**Note:** Requires gzip decompression.\n\n### Twitter/X (Auth Required)\n\nUses [bird CLI](https://github.com/steipete/bird) for Twitter search.\n\n**Searches:**\n- `stock OR $SPY OR $QQQ OR earnings`\n- `bitcoin OR ethereum OR crypto OR $BTC`\n\n## Twitter/X Setup\n\n### 1. Install bird CLI\n\n```bash\n# macOS\nbrew install steipete/tap/bird\n\n# npm\nnpm install -g @steipete/bird\n```\n\n### 2. Get Auth Tokens\n\n**Option A: Browser cookies (macOS)**\n1. Login to x.com in Safari/Chrome\n2. Grant Terminal \"Full Disk Access\" in System Settings\n3. Run `bird whoami` to verify\n\n**Option B: Manual extraction**\n1. Open x.com in Chrome\n2. DevTools (F12) → Application → Cookies → x.com\n3. Copy `auth_token` and `ct0` values\n\n### 3. Configure\n\nCreate `.env` file in the skill directory:\n\n```bash\n# /path/to/stock-analysis/.env\nAUTH_TOKEN=your_auth_token_here\nCT0=your_ct0_token_here\n```\n\nOr export as environment variables:\n\n```bash\nexport AUTH_TOKEN=\"...\"\nexport CT0=\"...\"\n```\n\n### 4. Verify\n\n```bash\nbird whoami\n# Should show: 🙋 @YourUsername\n```\n\n## Scoring System\n\nEach mention from a source adds points:\n\n| Source | Points |\n|--------|--------|\n| CoinGecko Trending | 2 |\n| CoinGecko Movers | 1 |\n| Google News | 1 |\n| Yahoo Finance | 1 |\n| Twitter/X | 1 |\n| Reddit (high score) | 2 |\n| Reddit (normal) | 1 |\n\nSymbols are ranked by total points across all sources.\n\n## Ticker Extraction\n\n### Patterns\n\n```python\n# Cashtag: $AAPL\nr'\\$([A-Z]{1,5})\\b'\n\n# Parentheses: (AAPL)\nr'\\(([A-Z]{2,5})\\)'\n\n# Stock mentions: AAPL stock, AAPL shares\nr'\\b([A-Z]{2,5})(?:\\'s|:|\\s+stock|\\s+shares)'\n```\n\n### Company Mappings\n\n```python\n{\n    \"Apple\": \"AAPL\",\n    \"Microsoft\": \"MSFT\",\n    \"Tesla\": \"TSLA\",\n    \"Nvidia\": \"NVDA\",\n    \"Bitcoin\": \"BTC\",\n    \"Ethereum\": \"ETH\",\n    # ... etc\n}\n```\n\n### Crypto Keywords\n\n```python\n{\n    \"bitcoin\": \"BTC\",\n    \"ethereum\": \"ETH\",\n    \"solana\": \"SOL\",\n    \"dogecoin\": \"DOGE\",\n    # ... etc\n}\n```\n\n## Automation\n\n### Cron Job\n\n```bash\n# Daily at 8 AM\n0 8 * * * cd /path/to/stock-analysis && python3 scripts/hot_scanner.py --json > cache/daily_scan.json\n```\n\n### OpenClaw Integration\n\n```yaml\n# Cron job config\nname: \"🔥 Daily Hot Scanner\"\nschedule:\n  kind: cron\n  expr: \"0 8 * * *\"\n  tz: \"Europe/Berlin\"\npayload:\n  kind: agentTurn\n  message: \"Run hot scanner and summarize results\"\n  deliver: true\nsessionTarget: isolated\n```\n\n## Caching\n\nResults are saved to:\n- `cache/hot_scan_latest.json` — Most recent scan\n\n## Limitations\n\n- **Reddit:** Blocked without OAuth (403). Requires API application.\n- **Twitter:** Requires auth tokens, may expire.\n- **Yahoo:** Sometimes rate-limited.\n- **Google News:** RSS URLs may change.\n\n## Future Enhancements\n\n- [ ] Reddit API integration (PRAW)\n- [ ] StockTwits integration\n- [ ] Google Trends\n- [ ] Historical trend tracking\n- [ ] Alert thresholds (notify when score > X)\n\n## Troubleshooting\n\n### Twitter not working\n\n```bash\n# Check auth\nbird whoami\n\n# Should see your username\n# If not, re-export tokens\n```\n\n### Yahoo 403 or gzip errors\n\nThe scanner handles gzip automatically. If issues persist, Yahoo may be rate-limiting.\n\n### No tickers found\n\nCheck that news headlines contain recognizable patterns. The scanner uses conservative extraction to avoid false positives.\n\nFile v6.2.0:docs/USAGE.md\n\n# Usage Guide\n\nPractical examples for using Stock Analysis v6.0 in real scenarios.\n\n## Table of Contents\n\n1. [Basic Stock Analysis](#basic-stock-analysis)\n2. [Comparing Stocks](#comparing-stocks)\n3. [Crypto Analysis](#crypto-analysis)\n4. [Dividend Investing](#dividend-investing)\n5. [Portfolio Management](#portfolio-management)\n6. [Watchlist & Alerts](#watchlist--alerts)\n7. [Performance Tips](#performance-tips)\n8. [Interpreting Results](#interpreting-results)\n\n---\n\n## Basic Stock Analysis\n\n### Single Stock\n\n```bash\nuv run scripts/analyze_stock.py AAPL\n```\n\n**Output:**\n```\n===========================================================================\nSTOCK ANALYSIS: AAPL (Apple Inc.)\nGenerated: 2024-02-01T10:30:00\n===========================================================================\n\nRECOMMENDATION: BUY (Confidence: 72%)\n\nSUPPORTING POINTS:\n• Beat by 8.2% - EPS $2.18 vs $2.01 expected\n• Strong margin: 24.1%\n• Analyst consensus: Buy with 12.3% upside (42 analysts)\n• Momentum: RSI 58 (neutral)\n• Sector: Technology uptrend (+5.2% 1m)\n\nCAVEATS:\n• Earnings in 12 days - high volatility expected\n• High market volatility (VIX 24)\n\n===========================================================================\nDISCLAIMER: NOT FINANCIAL ADVICE.\n===========================================================================\n```\n\n### JSON Output\n\nFor programmatic use:\n\n```bash\nuv run scripts/analyze_stock.py AAPL --output json | jq '.recommendation, .confidence'\n```\n\n### Verbose Mode\n\nSee what's happening under the hood:\n\n```bash\nuv run scripts/analyze_stock.py AAPL --verbose\n```\n\n---\n\n## Comparing Stocks\n\n### Side-by-Side Analysis\n\n```bash\nuv run scripts/analyze_stock.py AAPL MSFT GOOGL\n```\n\nEach stock gets a full analysis. Compare recommendations and confidence levels.\n\n### Sector Comparison\n\nCompare stocks in the same sector:\n\n```bash\n# Banks\nuv run scripts/analyze_stock.py JPM BAC WFC GS\n\n# Tech\nuv run scripts/analyze_stock.py AAPL MSFT GOOGL AMZN META\n```\n\n---\n\n## Crypto Analysis\n\n### Basic Crypto\n\n```bash\nuv run scripts/analyze_stock.py BTC-USD\n```\n\n**Crypto-Specific Output:**\n- Market cap classification (large/mid/small)\n- Category (Smart Contract L1, DeFi, etc.)\n- BTC correlation (30-day)\n- Momentum (RSI, price range)\n\n### Compare Cryptos\n\n```bash\nuv run scripts/analyze_stock.py BTC-USD ETH-USD SOL-USD\n```\n\n### Supported Cryptos\n\n```\nBTC, ETH, BNB, SOL, XRP, ADA, DOGE, AVAX, DOT, MATIC,\nLINK, ATOM, UNI, LTC, BCH, XLM, ALGO, VET, FIL, NEAR\n```\n\nUse `-USD` suffix: `BTC-USD`, `ETH-USD`, etc.\n\n---\n\n## Dividend Investing\n\n### Analyze Dividend Stock\n\n```bash\nuv run scripts/dividends.py JNJ\n```\n\n**Output:**\n```\n============================================================\nDIVIDEND ANALYSIS: JNJ (Johnson & Johnson)\n============================================================\n\nCurrent Price:    $160.50\nAnnual Dividend:  $4.76\nDividend Yield:   2.97%\nPayment Freq:     quarterly\nEx-Dividend:      2024-02-15\n\nPayout Ratio:     65.0% (moderate)\n5Y Div Growth:    +5.8%\nConsecutive Yrs:  62\n\nSAFETY SCORE:     78/100\nINCOME RATING:    GOOD\n\nSafety Factors:\n  • Moderate payout ratio (65%)\n  • Good dividend growth (+5.8% CAGR)\n  • Dividend Aristocrat (62+ years)\n\nDividend History:\n  2023: $4.52\n  2022: $4.36\n  2021: $4.24\n  2020: $4.04\n  2019: $3.80\n============================================================\n```\n\n### Compare Dividend Stocks\n\n```bash\nuv run scripts/dividends.py JNJ PG KO MCD VZ T\n```\n\n### Dividend Aristocrats Screen\n\nLook for stocks with:\n- Yield > 2%\n- Payout < 60%\n- Growth > 5%\n- Consecutive years > 25\n\n---\n\n## Portfolio Management\n\n### Create Portfolio\n\n```bash\nuv run scripts/portfolio.py create \"Retirement\"\n```\n\n### Add Holdings\n\n```bash\n# Stocks\nuv run scripts/portfolio.py add AAPL --quantity 100 --cost 150.00\n\n# Crypto\nuv run scripts/portfolio.py add BTC-USD --quantity 0.5 --cost 40000\n```\n\n### View Portfolio\n\n```bash\nuv run scripts/portfolio.py show\n```\n\n**Output:**\n```\nPortfolio: Retirement\n====================\n\nAssets:\n  AAPL     100 shares @ $150.00 = $15,000.00\n           Current: $185.00 = $18,500.00 (+23.3%)\n  \n  BTC-USD  0.5 @ $40,000 = $20,000.00\n           Current: $45,000 = $22,500.00 (+12.5%)\n\nTotal Cost:    $35,000.00\nCurrent Value: $41,000.00\nTotal P&L:     +$6,000.00 (+17.1%)\n```\n\n### Analyze Portfolio\n\n```bash\n# Full analysis of all holdings\nuv run scripts/analyze_stock.py --portfolio \"Retirement\"\n\n# With period returns\nuv run scripts/analyze_stock.py --portfolio \"Retirement\" --period monthly\n```\n\n### Rebalance Check\n\nThe analysis flags concentration warnings:\n```\n⚠️ CONCENTRATION WARNINGS:\n   • AAPL: 45.1% (>30% of portfolio)\n```\n\n---\n\n## Watchlist & Alerts\n\n### Add to Watchlist\n\n```bash\n# Basic watch\nuv run scripts/watchlist.py add NVDA\n\n# With price target\nuv run scripts/watchlist.py add NVDA --target 800\n\n# With stop loss\nuv run scripts/watchlist.py add NVDA --stop 600\n\n# Alert on signal change\nuv run scripts/watchlist.py add NVDA --alert-on signal\n\n# All options\nuv run scripts/watchlist.py add NVDA --target 800 --stop 600 --alert-on signal\n```\n\n### View Watchlist\n\n```bash\nuv run scripts/watchlist.py list\n```\n\n**Output:**\n```json\n{\n  \"success\": true,\n  \"items\": [\n    {\n      \"ticker\": \"NVDA\",\n      \"current_price\": 725.50,\n      \"price_at_add\": 700.00,\n      \"change_pct\": 3.64,\n      \"target_price\": 800.00,\n      \"to_target_pct\": 10.27,\n      \"stop_price\": 600.00,\n      \"to_stop_pct\": -17.30,\n      \"alert_on_signal\": true,\n      \"last_signal\": \"BUY\",\n      \"added_at\": \"2024-01-15\"\n    }\n  ],\n  \"count\": 1\n}\n```\n\n### Check Alerts\n\n```bash\n# Check for triggered alerts\nuv run scripts/watchlist.py check\n\n# Format for notification (Telegram)\nuv run scripts/watchlist.py check --notify\n```\n\n**Alert Example:**\n```\n📢 Stock Alerts\n\n🎯 NVDA hit target! $802.50 >= $800.00\n🛑 TSLA hit stop! $195.00 <= $200.00\n📊 AAPL signal changed: HOLD → BUY\n```\n\n### Remove from Watchlist\n\n```bash\nuv run scripts/watchlist.py remove NVDA\n```\n\n---\n\n## Performance Tips\n\n### Fast Mode\n\nSkip slow analyses for quick checks:\n\n```bash\n# Skip insider trading + breaking news\nuv run scripts/analyze_stock.py AAPL --fast\n```\n\n**Speed comparison:**\n| Mode | Time | What's Skipped |\n|------|------|----------------|\n| Default | 5-10s | Nothing |\n| `--no-insider` | 3-5s | SEC EDGAR |\n| `--fast` | 2-3s | Insider + News |\n\n### Batch Analysis\n\nAnalyze multiple stocks in one command:\n\n```bash\nuv run scripts/analyze_stock.py AAPL MSFT GOOGL AMZN META\n```\n\n### Caching\n\nMarket context is cached for 1 hour:\n- VIX, SPY, QQQ trends\n- Fear & Greed Index\n- VIX term structure\n- Breaking news\n\nSecond analysis of different stock reuses cached data.\n\n---\n\n## Interpreting Results\n\n### Recommendation Thresholds\n\n| Score | Recommendation |\n|-------|----------------|\n| > +0.33 | BUY |\n| -0.33 to +0.33 | HOLD |\n| < -0.33 | SELL |\n\n### Confidence Levels\n\n| Confidence | Meaning |\n|------------|---------|\n| > 80% | Strong conviction |\n| 60-80% | Moderate conviction |\n| 40-60% | Mixed signals |\n| < 40% | Low conviction |\n\n### Reading Caveats\n\n**Always read the caveats!** They often contain critical information:\n\n```\nCAVEATS:\n• Earnings in 5 days - high volatility expected    ← Timing risk\n• RSI 78 (overbought) + near 52w high              ← Technical risk\n• ⚠️ BREAKING NEWS: Fed emergency rate discussion  ← External risk\n• ⚠️ SECTOR RISK: China tensions affect tech       ← Geopolitical\n```\n\n### When to Ignore the Signal\n\n- **Pre-earnings:** Even BUY → wait until after\n- **Overbought:** Consider smaller position\n- **Risk-off:** Reduce overall exposure\n- **Low confidence:** Do more research\n\n### When to Trust the Signal\n\n- **High confidence + no major caveats**\n- **Multiple supporting points align**\n- **Sector is strong**\n- **Market regime is favorable**\n\n---\n\n## Common Workflows\n\n### Morning Check\n\n```bash\n# Check watchlist alerts\nuv run scripts/watchlist.py check --notify\n\n# Quick portfolio update\nuv run scripts/analyze_stock.py --portfolio \"Main\" --fast\n```\n\n### Research New Stock\n\n```bash\n# Full analysis\nuv run scripts/analyze_stock.py XYZ\n\n# If dividend stock\nuv run scripts/dividends.py XYZ\n\n# Add to watchlist for monitoring\nuv run scripts/watchlist.py add XYZ --alert-on signal\n```\n\n### Weekly Review\n\n```bash\n# Full portfolio analysis\nuv run scripts/analyze_stock.py --portfolio \"Main\" --period weekly\n\n# Check dividend holdings\nuv run scripts/dividends.py JNJ PG KO\n```\n\n---\n\n## Troubleshooting\n\n### \"Invalid ticker\"\n\n- Check spelling\n- For crypto, use `-USD` suffix\n- Non-US stocks may not work\n\n### \"Insufficient data\"\n\n- Stock might be too new\n- ETFs have limited data\n- OTC stocks often fail\n\n### Slow Performance\n\n- Use `--fast` for quick checks\n- Insider trading is slowest\n- Breaking news adds ~2s\n\n### Missing Data\n\n- Not all stocks have analyst coverage\n- Some metrics require options chains\n- Crypto has no sentiment data\n\nFile v6.2.0:TODO.md\n\n# Stock Analysis - Future Enhancements\n\n## Roadmap Overview\n\n### v4.0.0 (Current) - Geopolitical Risk & News Sentiment\n✅ 8 analysis dimensions with Fear/Greed, short interest, VIX structure, put/call ratio\n✅ Safe-haven indicators (GLD, TLT, UUP) with risk-off detection\n✅ Breaking news alerts via Google News RSS\n✅ Geopolitical risk mapping (Taiwan, China, Russia, Middle East, Banking)\n✅ Sector-specific crisis flagging with confidence penalties\n✅ 1h caching for shared indicators (Fear/Greed, VIX structure, breaking news)\n✅ Async parallel sentiment fetching (5 indicators with 10s timeouts)\n\n### v5.0.0 (Current) - Portfolio & Crypto\n✅ Portfolio management (create, add, remove, show assets)\n✅ Cryptocurrency support (Top 20 by market cap)\n✅ Portfolio analysis with --portfolio flag\n✅ Periodic returns (--period daily/weekly/monthly/quarterly/yearly)\n✅ Concentration warnings (>30% single asset)\n✅ Crypto fundamentals (market cap, category, BTC correlation)\n\n### v4.1.0 - Performance & Completeness\n✅ Full insider trading parsing via edgartools (Task #1)\n✅ Market context caching with 1h TTL (Task #3b)\n🔧 SEC EDGAR rate limit monitoring (Task #4 - low priority)\n\n### Future (v6.0+)\n💡 Research phase: Social sentiment, fund flows, on-chain metrics\n\n---\n\n## Sentiment Analysis Improvements\n\n### 1. Implement Full Insider Trading Parsing\n**Status**: ✅ DONE\n**Priority**: Medium\n**Effort**: 2-3 hours\n\n**Current State**:\n- ✅ `get_insider_activity()` fetches Form 4 filings via edgartools\n- ✅ SEC identity configured (`stock-analysis@clawd.bot`)\n- ✅ Aggregates buys/sells over 90-day window\n- ✅ Scoring logic: strong buying (+0.8), moderate (+0.4), neutral (0), moderate selling (-0.4), strong (-0.8)\n\n**Tasks**:\n- [ ] Research edgartools API for Form 4 parsing\n- [ ] Implement transaction aggregation (90-day window)\n- [ ] Calculate net shares bought/sold\n- [ ] Calculate net value in millions USD\n- [ ] Apply scoring logic:\n  - Strong buying (>100K shares or >$1M): +0.8\n  - Moderate buying (>10K shares or >$0.1M): +0.4\n  - Neutral: 0\n  - Moderate selling: -0.4\n  - Strong selling: -0.8\n- [ ] Add error handling for missing/incomplete filings\n- [ ] Test with multiple tickers (BAC, TSLA, AAPL)\n- [ ] Verify SEC rate limit compliance (10 req/s)\n\n**Expected Impact**:\n- Insider activity detection for 4th sentiment indicator\n- Increase from 3/5 to 4/5 indicators typically available\n\n---\n\n### 2. Add Parallel Async Fetching\n**Status**: ✅ DONE (sentiment indicators)\n**Priority**: High\n**Effort**: 4-6 hours\n\n**Current State**:\n- ✅ Sentiment indicators fetched in parallel via `asyncio.gather()`\n- ✅ 10s timeout per indicator\n- Main data fetches (yfinance) still sequential (acceptable)\n\n**Tasks**:\n- [ ] Convert sentiment helper functions to async\n  - [ ] `async def get_fear_greed_index()`\n  - [ ] `async def get_short_interest(data)`\n  - [ ] `async def get_vix_term_structure()`\n  - [ ] `async def get_insider_activity(ticker)`\n  - [ ] `async def get_put_call_ratio(data)`\n- [ ] Update `analyze_sentiment()` to use `asyncio.gather()`\n- [ ] Handle yfinance thread safety (may need locks)\n- [ ] Add timeout per indicator (10s max)\n- [ ] Test with multiple stocks in sequence\n- [ ] Measure actual runtime improvement\n- [ ] Update SKILL.md with new runtime (target: 3-4s)\n\n**Expected Impact**:\n- Reduce runtime from 6-10s to 3-4s per stock\n- Better user experience for multi-stock analysis\n\n---\n\n### 3. Add Caching for Shared Indicators\n**Status**: ✅ DONE (sentiment + breaking news)\n**Priority**: Medium\n**Effort**: 2-3 hours\n\n**Current State**:\n- ✅ Fear & Greed Index cached (1h TTL)\n- ✅ VIX term structure cached (1h TTL)\n- ✅ Breaking news cached (1h TTL)\n- ✅ Market context (VIX/SPY/QQQ/GLD/TLT/UUP) cached (1h TTL)\n\n**Tasks**:\n- [ ] Design cache structure (simple dict or functools.lru_cache)\n- [ ] Implement TTL (time-to-live):\n  - Fear & Greed: 1 hour\n  - VIX structure: 1 hour\n  - Short interest: No cache (per-stock)\n  - Insider activity: No cache (per-stock)\n  - Put/Call ratio: No cache (per-stock)\n- [ ] Add cache invalidation logic\n- [ ] Add verbose logging for cache hits/misses\n- [ ] Test multi-stock analysis (e.g., `BAC TSLA AAPL`)\n- [ ] Measure performance improvement\n- [ ] Document caching behavior in SKILL.md\n\n**Expected Impact**:\n- Multi-stock analysis faster (e.g., 3 stocks: 18-30s → 10-15s)\n- Reduced API calls to Fear/Greed and VIX data sources\n- Same-session analysis efficiency\n\n---\n\n### 4. Monitor SEC EDGAR Rate Limits\n**Status**: Not Started\n**Priority**: Low (until insider trading implemented)\n**Effort**: 1-2 hours\n\n**Current State**:\n- SEC EDGAR API has 10 requests/second rate limit\n- No rate limit tracking or logging\n- edgartools may handle rate limiting internally\n\n**Tasks**:\n- [ ] Research edgartools rate limit handling\n- [ ] Add request counter/tracker if needed\n- [ ] Implement exponential backoff on 429 errors\n- [ ] Add logging for rate limit hits\n- [ ] Test with high-volume scenarios (10+ stocks in quick succession)\n- [ ] Document rate limit behavior\n- [ ] Add error message if rate limited: \"SEC API rate limited, try again in 1 minute\"\n\n**Expected Impact**:\n- Robust handling of SEC API limits in production\n- Clear user feedback if limits hit\n- Prevent API blocking/banning\n\n---\n\n## Stock Analysis 4.0: Geopolitical Risk & News Sentiment\n\n### What's Currently Missing\n\nThe current implementation captures:\n- ✅ VIX (general market fear)\n- ✅ SPY/QQQ trends (market direction)\n- ✅ Sector performance\n\nWhat we **don't** have yet:\n- ❌ Geopolitical risk indicators\n- ❌ News sentiment analysis\n- ❌ Sector-specific crisis flags\n\n---\n\n### 7. Geopolitical Risk Index\n**Status**: ✅ DONE (keyword-based)\n**Priority**: High\n**Effort**: 8-12 hours\n\n**Proposed Approach**:\nOption A: Use GPRD (Geopolitical Risk Daily Index) from policyuncertainty.com\nOption B: Scan news APIs (NewsAPI, GDELT) for geopolitical keywords\n\n**Tasks**:\n- [ ] Research free geopolitical risk data sources\n  - [ ] Check policyuncertainty.com API availability\n  - [ ] Evaluate NewsAPI free tier limits\n  - [ ] Consider GDELT Project (free, comprehensive)\n- [ ] Design risk scoring system (0-100 scale)\n- [ ] Implement data fetching with caching (4-hour TTL)\n- [ ] Map risk levels to sentiment scores:\n  - Low risk (0-30): +0.2 (bullish)\n  - Moderate risk (30-60): 0 (neutral)\n  - High risk (60-80): -0.3 (caution)\n  - Extreme risk (80-100): -0.5 (bearish)\n- [ ] Add to sentiment analysis as 6th indicator\n- [ ] Test with historical crisis periods\n- [ ] Update SKILL.md with geopolitical indicator\n\n**Expected Impact**:\n- Early warning for market-wide risk events\n- Better context for earnings-season volatility\n- Complement to VIX (VIX is reactive, geopolitical is predictive)\n\n**Example Output**:\n```\n⚠️ GEOPOLITICAL RISK: HIGH (72/100)\n   Context: Elevated Taiwan tensions detected\n   Market Impact: Risk-off sentiment likely\n```\n\n---\n\n### 8. Sector-Specific Crisis Mapping\n**Status**: ✅ DONE\n**Priority**: High\n**Effort**: 6-8 hours\n\n**Current Gap**:\n- No mapping between geopolitical events and affected sectors\n- No automatic flagging of at-risk holdings\n\n**Proposed Risk Mapping**:\n\n| Geopolitical Event | Affected Sectors | Example Tickers |\n|-------------------|------------------|-----------------|\n| Taiwan conflict | Semiconductors | NVDA, AMD, TSM, INTC |\n| Russia-Ukraine | Energy, Agriculture | XLE, MOS, CF, NTR |\n| Middle East escalation | Oil, Defense | XOM, CVX, LMT, RTX |\n| China tensions | Tech supply chain, Retail | AAPL, QCOM, NKE, SBUX |\n| Banking crisis | Financials | JPM, BAC, WFC, C |\n\n**Tasks**:\n- [ ] Build event → sector → ticker mapping database\n- [ ] Implement keyword detection in news feeds:\n  - \"Taiwan\" + \"military\" → Semiconductors ⚠️\n  - \"Russia\" + \"sanctions\" → Energy ⚠️\n  - \"Iran\" + \"attack\" → Oil, Defense ⚠️\n  - \"China\" + \"tariffs\" → Tech, Consumer ⚠️\n- [ ] Add sector exposure check to analysis\n- [ ] Generate automatic warnings in output\n- [ ] Apply confidence penalty for high-risk sectors\n- [ ] Test with historical crisis events\n- [ ] Document in SKILL.md\n\n**Expected Impact**:\n- Automatic detection of sector-specific risks\n- Clear warnings for exposed holdings\n- Reduced false positives (only flag relevant sectors)\n\n**Example Output**:\n```\n⚠️ SECTOR RISK ALERT: Semiconductors\n   Event: Taiwan military exercises (elevated tensions)\n   Impact: NVDA HIGH RISK - supply chain exposure\n   Recommendation: HOLD → downgraded from BUY\n```\n\n---\n\n### 9. Breaking News Check\n**Status**: ✅ DONE\n**Priority**: Medium\n**Effort**: 4-6 hours\n\n**Current Gap**:\n- No real-time news scanning before analysis\n- User might get stale recommendation during breaking events\n\n**Proposed Solution**:\n- Scan Google News or Reuters RSS before analysis\n- Flag high-impact keywords within last 24 hours\n\n**Tasks**:\n- [ ] Choose news source (Google News RSS, Reuters API, or NewsAPI)\n- [ ] Implement news fetching with 24-hour lookback\n- [ ] Define crisis keywords:\n  - **War/Conflict**: \"war\", \"invasion\", \"military strike\", \"attack\"\n  - **Economic**: \"recession\", \"crisis\", \"collapse\", \"default\"\n  - **Regulatory**: \"sanctions\", \"embargo\", \"ban\", \"investigation\"\n  - **Natural disaster**: \"earthquake\", \"hurricane\", \"pandemic\"\n- [ ] Add ticker-specific news check (company name + keywords)\n- [ ] Generate automatic caveat in output\n- [ ] Cache news check results (1 hour TTL)\n- [ ] Add `--skip-news` flag for offline mode\n- [ ] Test with historical crisis dates\n- [ ] Document in SKILL.md\n\n**Expected Impact**:\n- Real-time awareness of breaking events\n- Automatic caveats during high volatility\n- User protection from stale recommendations\n\n**Example Output**:\n```\n⚠️ BREAKING NEWS ALERT (last 6 hours):\n   \"Fed announces emergency rate hike\"\n   Impact: Market-wide volatility expected\n   Caveat: Analysis may be outdated - rerun in 24h\n```\n\n---\n\n### 10. Safe-Haven Indicators\n**Status**: ✅ DONE\n**Priority**: Medium\n**Effort**: 3-4 hours\n\n**Current Gap**:\n- No detection of \"risk-off\" market regime\n- VIX alone is insufficient (measures implied volatility, not capital flows)\n\n**Proposed Indicators**:\n- Gold (GLD) - Flight to safety\n- US Treasuries (TLT) - Bond market fear\n- USD Index (UUP) - Dollar strength during crisis\n\n**Risk-Off Detection Logic**:\n```\nIF GLD +2% AND TLT +1% AND UUP +1% (all rising together)\nTHEN Market Regime = RISK-OFF\n```\n\n**Tasks**:\n- [ ] Fetch GLD, TLT, UUP price data (5-day change)\n- [ ] Implement risk-off detection algorithm\n- [ ] Add to market context analysis\n- [ ] Apply broad risk penalty:\n  - Risk-off detected → Reduce all BUY confidence by 30%\n  - Add caveat: \"Market in risk-off mode - defensive positioning recommended\"\n- [ ] Test with historical crisis periods (2008, 2020, 2022)\n- [ ] Add verbose output for safe-haven movements\n- [ ] Document in SKILL.md\n\n**Expected Impact**:\n- Detect market-wide flight to safety\n- Automatic risk reduction during panics\n- Complement geopolitical risk scoring\n\n**Example Output**:\n```\n🛡️ SAFE-HAVEN ALERT: Risk-off mode detected\n   - Gold (GLD): +3.2% (5d)\n   - Treasuries (TLT): +2.1% (5d)\n   - USD Index: +1.8% (5d)\n   Recommendation: Reduce equity exposure, favor defensives\n```\n\n---\n\n## General Improvements\n\n### 11. Add Social Sentiment (Future Phase)\n**Status**: Deferred\n**Priority**: Low\n**Effort**: 8-12 hours\n\n**Notes**:\n- Requires free API (Twitter/Reddit alternatives?)\n- Most sentiment APIs are paid (StockTwits, etc.)\n- Research needed for viable free sources\n\n### 12. Add Fund Flows (Future Phase)\n**Status**: Deferred\n**Priority**: Low\n**Effort**: 6-8 hours\n\n**Notes**:\n- Requires ETF flow data\n- May need paid data source\n- Research free alternatives\n\n---\n\n## Implementation Priorities\n\n### v4.1.0 Complete\n- ✅ Task #1 - Insider trading parsing via edgartools\n- ✅ Task #3b - Market context caching (1h TTL)\n- 🔧 Task #4 - SEC EDGAR rate limits (low priority, only if hitting limits)\n\n### Completed in v4.0.0\n- ✅ Task #2 - Async parallel fetching (sentiment)\n- ✅ Task #3 - Caching for shared indicators (sentiment + news)\n- ✅ Task #7 - Geopolitical risk (keyword-based)\n- ✅ Task #8 - Sector-specific crisis mapping\n- ✅ Task #9 - Breaking news check\n- ✅ Task #10 - Safe-haven indicators\n\n---\n\n## Version History\n\n- **v5.0.0** (2026-01-16): Portfolio management, cryptocurrency support (Top 20), periodic analysis\n- **v4.1.0** (2026-01-16): Full insider trading parsing via edgartools, market context caching\n- **v4.0.0** (2026-01-15): Geopolitical risk, breaking news, safe-haven detection, sector crisis mapping\n- **v3.0.0** (2026-01-15): Sentiment analysis added with 5 indicators (3-4 typically working)\n- **v2.0.0**: Market context, sector performance, earnings timing, momentum\n- **v1.0.0**: Initial release with earnings, fundamentals, analysts, historical\n\nArchive v6.1.0: 16 files, 74714 bytes\n\nFiles: App-Plan.md (14708b), docs/ARCHITECTURE.md (16594b), docs/CONCEPT.md (9101b), docs/HOT_SCANNER.md (5865b), docs/README.md (2405b), docs/USAGE.md (8898b), README.md (6390b), scripts/analyze_stock.py (89930b), scripts/dividends.py (13130b), scripts/hot_scanner.py (24620b), scripts/portfolio.py (18897b), scripts/test_stock_analysis.py (11958b), scripts/watchlist.py (11542b), SKILL.md (6963b), TODO.md (12848b), _meta.json (133b)\n\nFile v6.1.0:SKILL.md\n\n---\nname: stock-analysis\ndescription: Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management, watchlists with alerts, dividend analysis, 8-dimension stock scoring, and viral trend detection (Hot Scanner). Use for stock analysis, portfolio tracking, earnings reactions, crypto monitoring, or finding what's trending.\nversion: 6.1.0\nhomepage: https://finance.yahoo.com\ncommands:\n  - /stock - Analyze a stock or crypto (e.g., /stock AAPL)\n  - /stock_compare - Compare multiple tickers\n  - /stock_dividend - Analyze dividend metrics\n  - /stock_watch - Add/remove from watchlist\n  - /stock_alerts - Check triggered alerts\n  - /stock_hot - Find trending stocks & crypto (Hot Scanner)\n  - /portfolio - Show portfolio summary\n  - /portfolio_add - Add asset to portfolio\nmetadata: {\"clawdbot\":{\"emoji\":\"📈\",\"requires\":{\"bins\":[\"uv\"],\"env\":[]},\"install\":[{\"id\":\"uv-brew\",\"kind\":\"brew\",\"formula\":\"uv\",\"bins\":[\"uv\"],\"label\":\"Install uv (brew)\"}]}}\n---\n\n# Stock Analysis v6.1\n\nAnalyze US stocks and cryptocurrencies with 8-dimension analysis, portfolio management, watchlists, alerts, dividend analysis, and **viral trend detection**.\n\n## What's New in v6.1\n\n- 🔥 **Hot Scanner** — Find viral stocks & crypto across multiple sources\n- 🐦 **Twitter/X Integration** — Social sentiment via bird CLI\n- 📰 **Multi-Source Aggregation** — CoinGecko, Google News, Yahoo Finance\n- ⏰ **Cron Support** — Daily trend reports\n\n## What's in v6.0\n\n- 🆕 **Watchlist + Alerts** — Price targets, stop losses, signal changes\n- 🆕 **Dividend Analysis** — Yield, payout ratio, growth, safety score\n- 🆕 **Fast Mode** — `--fast` skips slow analyses (insider, news)\n- 🆕 **Improved Performance** — `--no-insider` for faster runs\n\n## Quick Commands\n\n### Stock Analysis\n```bash\n# Basic analysis\nuv run {baseDir}/scripts/analyze_stock.py AAPL\n\n# Fast mode (skips insider trading & breaking news)\nuv run {baseDir}/scripts/analyze_stock.py AAPL --fast\n\n# Compare multiple\nuv run {baseDir}/scripts/analyze_stock.py AAPL MSFT GOOGL\n\n# Crypto\nuv run {baseDir}/scripts/analyze_stock.py BTC-USD ETH-USD\n```\n\n### Dividend Analysis (NEW v6.0)\n```bash\n# Analyze dividends\nuv run {baseDir}/scripts/dividends.py JNJ\n\n# Compare dividend stocks\nuv run {baseDir}/scripts/dividends.py JNJ PG KO MCD --output json\n```\n\n**Dividend Metrics:**\n- Dividend Yield & Annual Payout\n- Payout Ratio (safe/moderate/high/unsustainable)\n- 5-Year Dividend Growth (CAGR)\n- Consecutive Years of Increases\n- Safety Score (0-100)\n- Income Rating (excellent/good/moderate/poor)\n\n### Watchlist + Alerts (NEW v6.0)\n```bash\n# Add to watchlist\nuv run {baseDir}/scripts/watchlist.py add AAPL\n\n# With price target alert\nuv run {baseDir}/scripts/watchlist.py add AAPL --target 200\n\n# With stop loss alert\nuv run {baseDir}/scripts/watchlist.py add AAPL --stop 150\n\n# Alert on signal change (BUY→SELL)\nuv run {baseDir}/scripts/watchlist.py add AAPL --alert-on signal\n\n# View watchlist\nuv run {baseDir}/scripts/watchlist.py list\n\n# Check for triggered alerts\nuv run {baseDir}/scripts/watchlist.py check\nuv run {baseDir}/scripts/watchlist.py check --notify  # Telegram format\n\n# Remove from watchlist\nuv run {baseDir}/scripts/watchlist.py remove AAPL\n```\n\n**Alert Types:**\n- 🎯 **Target Hit** — Price >= target\n- 🛑 **Stop Hit** — Price <= stop\n- 📊 **Signal Change** — BUY/HOLD/SELL changed\n\n### Portfolio Management\n```bash\n# Create portfolio\nuv run {baseDir}/scripts/portfolio.py create \"Tech Portfolio\"\n\n# Add assets\nuv run {baseDir}/scripts/portfolio.py add AAPL --quantity 100 --cost 150\nuv run {baseDir}/scripts/portfolio.py add BTC-USD --quantity 0.5 --cost 40000\n\n# View portfolio\nuv run {baseDir}/scripts/portfolio.py show\n\n# Analyze with period returns\nuv run {baseDir}/scripts/analyze_stock.py --portfolio \"Tech Portfolio\" --period weekly\n```\n\n### 🔥 Hot Scanner (NEW v6.1)\n```bash\n# Full scan - find what's trending NOW\npython3 {baseDir}/scripts/hot_scanner.py\n\n# Fast scan (skip social media)\npython3 {baseDir}/scripts/hot_scanner.py --no-social\n\n# JSON output for automation\npython3 {baseDir}/scripts/hot_scanner.py --json\n```\n\n**Data Sources:**\n- 📊 CoinGecko Trending — Top 15 trending coins\n- 📈 CoinGecko Movers — Biggest gainers/losers\n- 📰 Google News — Finance & crypto headlines\n- 📉 Yahoo Finance — Gainers, losers, most active\n- 🐦 Twitter/X — Social sentiment (requires auth)\n\n**Output:**\n- Top trending by mention count\n- Crypto highlights with 24h changes\n- Stock movers by category\n- Breaking news with tickers\n\n**Twitter Setup (Optional):**\n1. Install bird: `npm install -g @steipete/bird`\n2. Login to x.com in Safari/Chrome\n3. Create `.env` with `AUTH_TOKEN` and `CT0`\n\n## Analysis Dimensions (8 for stocks, 3 for crypto)\n\n### Stocks\n| Dimension | Weight | Description |\n|-----------|--------|-------------|\n| Earnings Surprise | 30% | EPS beat/miss |\n| Fundamentals | 20% | P/E, margins, growth |\n| Analyst Sentiment | 20% | Ratings, price targets |\n| Historical | 10% | Past earnings reactions |\n| Market Context | 10% | VIX, SPY/QQQ trends |\n| Sector | 15% | Relative strength |\n| Momentum | 15% | RSI, 52-week range |\n| Sentiment | 10% | Fear/Greed, shorts, insiders |\n\n### Crypto\n- Market Cap & Category\n- BTC Correlation (30-day)\n- Momentum (RSI, range)\n\n## Sentiment Sub-Indicators\n\n| Indicator | Source | Signal |\n|-----------|--------|--------|\n| Fear & Greed | CNN | Contrarian (fear=buy) |\n| Short Interest | Yahoo | Squeeze potential |\n| VIX Structure | Futures | Stress detection |\n| Insider Trades | SEC EDGAR | Smart money |\n| Put/Call Ratio | Options | Sentiment extreme |\n\n## Risk Detection\n\n- ⚠️ **Pre-Earnings** — Warns if < 14 days to earnings\n- ⚠️ **Post-Spike** — Flags if up >15% in 5 days\n- ⚠️ **Overbought** — RSI >70 + near 52w high\n- ⚠️ **Risk-Off** — GLD/TLT/UUP rising together\n- ⚠️ **Geopolitical** — Taiwan, China, Russia, Middle East keywords\n- ⚠️ **Breaking News** — Crisis keywords in last 24h\n\n## Performance Options\n\n| Flag | Effect | Speed |\n|------|--------|-------|\n| (default) | Full analysis | 5-10s |\n| `--no-insider` | Skip SEC EDGAR | 3-5s |\n| `--fast` | Skip insider + news | 2-3s |\n\n## Supported Cryptos (Top 20)\n\nBTC, ETH, BNB, SOL, XRP, ADA, DOGE, AVAX, DOT, MATIC, LINK, ATOM, UNI, LTC, BCH, XLM, ALGO, VET, FIL, NEAR\n\n(Use `-USD` suffix: `BTC-USD`, `ETH-USD`)\n\n## Data Storage\n\n| File | Location |\n|------|----------|\n| Portfolios | `~/.clawdbot/skills/stock-analysis/portfolios.json` |\n| Watchlist | `~/.clawdbot/skills/stock-analysis/watchlist.json` |\n\n## Limitations\n\n- Yahoo Finance may lag 15-20 minutes\n- Short interest lags ~2 weeks (FINRA)\n- Insider trades lag 2-3 days (SEC filing)\n- US markets only (non-US incomplete)\n- Breaking news: 1h cache, keyword-based\n\n## Disclaimer\n\n⚠️ **NOT FINANCIAL ADVICE.** For informational purposes only. Consult a licensed financial advisor before making investment decisions.\n\nFile v6.1.0:docs/README.md\n\n# Documentation\n\n## Stock Analysis v6.1\n\nThis folder contains detailed documentation for the Stock Analysis skill.\n\n## Contents\n\n| Document | Description |\n|----------|-------------|\n| [CONCEPT.md](./CONCEPT.md) | Philosophy, ideas, and design rationale |\n| [USAGE.md](./USAGE.md) | Practical usage guide with examples |\n| [ARCHITECTURE.md](./ARCHITECTURE.md) | Technical implementation details |\n| [HOT_SCANNER.md](./HOT_SCANNER.md) | 🔥 Viral trend detection (NEW) |\n\n## Quick Links\n\n### For Users\n\nStart with **[USAGE.md](./USAGE.md)** — it has practical examples for:\n- Basic stock analysis\n- Comparing stocks\n- Crypto analysis\n- Dividend investing\n- Portfolio management\n- Watchlist & alerts\n\n### For Understanding\n\nRead **[CONCEPT.md](./CONCEPT.md)** to understand:\n- Why 8 dimensions?\n- How scoring works\n- Contrarian signals\n- Risk detection philosophy\n- Limitations we acknowledge\n\n### For Developers\n\nCheck **[ARCHITECTURE.md](./ARCHITECTURE.md)** for:\n- System overview diagram\n- Data flow\n- Caching strategy\n- File structure\n- Performance optimization\n\n## Quick Start\n\n```bash\n# Analyze a stock\nuv run scripts/analyze_stock.py AAPL\n\n# Fast mode (2-3 seconds)\nuv run scripts/analyze_stock.py AAPL --fast\n\n# Dividend analysis\nuv run scripts/dividends.py JNJ\n\n# Watchlist\nuv run scripts/watchlist.py add AAPL --target 200\nuv run scripts/watchlist.py check\n```\n\n## Key Concepts\n\n### The 8 Dimensions\n\n1. **Earnings Surprise** (30%) — Did they beat expectations?\n2. **Fundamentals** (20%) — P/E, margins, growth, debt\n3. **Analyst Sentiment** (20%) — Professional consensus\n4. **Historical Patterns** (10%) — Past earnings reactions\n5. **Market Context** (10%) — VIX, SPY/QQQ trends\n6. **Sector Performance** (15%) — Relative strength\n7. **Momentum** (15%) — RSI, 52-week range\n8. **Sentiment** (10%) — Fear/Greed, shorts, insiders\n\n### Signal Thresholds\n\n| Score | Recommendation |\n|-------|----------------|\n| > +0.33 | **BUY** |\n| -0.33 to +0.33 | **HOLD** |\n| < -0.33 | **SELL** |\n\n### Risk Flags\n\n- ⚠️ Pre-earnings (< 14 days)\n- ⚠️ Post-spike (> 15% in 5 days)\n- ⚠️ Overbought (RSI > 70 + near 52w high)\n- ⚠️ Risk-off mode (GLD/TLT/UUP rising)\n- ⚠️ Geopolitical keywords\n- ⚠️ Breaking news alerts\n\n## Disclaimer\n\n⚠️ **NOT FINANCIAL ADVICE.** For informational purposes only. Always do your own research and consult a licensed financial advisor.\n\nFile v6.1.0:README.md\n\n# 📈 Stock Analysis v6.1\n\n> AI-powered stock & crypto analysis with portfolio management, watchlists, dividend analysis, and **viral trend detection**.\n\n[![ClawHub Downloads](https://img.shields.io/badge/ClawHub-1500%2B%20downloads-blue)](https://clawhub.ai)\n[![OpenClaw Skill](https://img.shields.io/badge/OpenClaw-Skill-green)](https://openclaw.ai)\n\n## What's New in v6.1\n\n- 🔥 **Hot Scanner** — Find viral stocks & crypto across multiple sources\n- 🐦 **Twitter/X Integration** — Social sentiment via bird CLI\n- 📰 **Multi-Source Aggregation** — CoinGecko, Google News, Yahoo Finance\n- ⏰ **Cron Support** — Daily trend reports\n\n## What's New in v6.0\n\n- 🆕 **Watchlist + Alerts** — Price targets, stop losses, signal change notifications\n- 🆕 **Dividend Analysis** — Yield, payout ratio, growth rate, safety score\n- 🆕 **Fast Mode** — Skip slow analyses for quick checks\n- 🆕 **Improved Commands** — Better OpenClaw/Telegram integration\n- 🆕 **Test Suite** — Unit tests for core functionality\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **8-Dimension Analysis** | Earnings, fundamentals, analysts, momentum, sentiment, sector, market, history |\n| **Crypto Support** | Top 20 cryptos with market cap, BTC correlation, momentum |\n| **Portfolio Management** | Track holdings, P&L, concentration warnings |\n| **Watchlist + Alerts** | Price targets, stop losses, signal changes |\n| **Dividend Analysis** | Yield, payout, growth, safety score |\n| **Risk Detection** | Geopolitical, earnings timing, overbought, risk-off |\n| **Breaking News** | Crisis keyword scanning (last 24h) |\n\n## Quick Start\n\n### Analyze Stocks\n```bash\nuv run scripts/analyze_stock.py AAPL\nuv run scripts/analyze_stock.py AAPL MSFT GOOGL\nuv run scripts/analyze_stock.py AAPL --fast  # Skip slow analyses\n```\n\n### Analyze Crypto\n```bash\nuv run scripts/analyze_stock.py BTC-USD\nuv run scripts/analyze_stock.py ETH-USD SOL-USD\n```\n\n### Dividend Analysis\n```bash\nuv run scripts/dividends.py JNJ PG KO\n```\n\n### Watchlist\n```bash\nuv run scripts/watchlist.py add AAPL --target 200 --stop 150\nuv run scripts/watchlist.py list\nuv run scripts/watchlist.py check --notify\n```\n\n### Portfolio\n```bash\nuv run scripts/portfolio.py create \"My Portfolio\"\nuv run scripts/portfolio.py add AAPL --quantity 100 --cost 150\nuv run scripts/portfolio.py show\n```\n\n### 🔥 Hot Scanner (NEW)\n```bash\n# Full scan with all sources\npython3 scripts/hot_scanner.py\n\n# Fast scan (skip social media)\npython3 scripts/hot_scanner.py --no-social\n\n# JSON output for automation\npython3 scripts/hot_scanner.py --json\n```\n\n## Analysis Dimensions\n\n### Stocks (8 dimensions)\n1. **Earnings Surprise** (30%) — EPS beat/miss\n2. **Fundamentals** (20%) — P/E, margins, growth, debt\n3. **Analyst Sentiment** (20%) — Ratings, price targets\n4. **Historical Patterns** (10%) — Past earnings reactions\n5. **Market Context** (10%) — VIX, SPY/QQQ trends\n6. **Sector Performance** (15%) — Relative strength\n7. **Momentum** (15%) — RSI, 52-week range\n8. **Sentiment** (10%) — Fear/Greed, shorts, insiders\n\n### Crypto (3 dimensions)\n- Market Cap & Category\n- BTC Correlation (30-day)\n- Momentum (RSI, range)\n\n## Dividend Metrics\n\n| Metric | Description |\n|--------|-------------|\n| Yield | Annual dividend / price |\n| Payout Ratio | Dividend / EPS |\n| 5Y Growth | CAGR of dividend |\n| Consecutive Years | Years of increases |\n| Safety Score | 0-100 composite |\n| Income Rating | Excellent → Poor |\n\n## 🔥 Hot Scanner\n\nFind what's trending RIGHT NOW across stocks & crypto.\n\n### Data Sources\n\n| Source | What it finds |\n|--------|---------------|\n| **CoinGecko Trending** | Top 15 trending coins |\n| **CoinGecko Movers** | Biggest gainers/losers (>3%) |\n| **Google News** | Breaking finance & crypto news |\n| **Yahoo Finance** | Top gainers, losers, most active |\n| **Twitter/X** | Social sentiment (requires auth) |\n\n### Output\n\n```\n📊 TOP TRENDING (by buzz):\n   1. BTC      (6 pts) [CoinGecko, Google News] 📉 bearish (-2.5%)\n   2. ETH      (5 pts) [CoinGecko, Twitter] 📉 bearish (-7.2%)\n   3. NVDA     (3 pts) [Google News, Yahoo] 📰 Earnings beat...\n\n🪙 CRYPTO HIGHLIGHTS:\n   🚀 RIVER    River              +14.0%\n   📉 BTC      Bitcoin             -2.5%\n\n📈 STOCK MOVERS:\n   🟢 NVDA (gainers)\n   🔴 TSLA (losers)\n\n📰 BREAKING NEWS:\n   [BTC, ETH] Crypto crash: $2.5B liquidated...\n```\n\n### Twitter/X Setup (Optional)\n\n1. Install bird CLI: `npm install -g @steipete/bird`\n2. Login to x.com in Safari/Chrome\n3. Create `.env` file:\n```\nAUTH_TOKEN=your_auth_token\nCT0=your_ct0_token\n```\n\nGet tokens from browser DevTools → Application → Cookies → x.com\n\n### Automation\n\nSet up a daily cron job for morning reports:\n```bash\n# Run at 8 AM daily\n0 8 * * * python3 /path/to/hot_scanner.py --no-social >> /var/log/hot_scanner.log\n```\n\n## Risk Detection\n\n- ⚠️ Pre-earnings warning (< 14 days)\n- ⚠️ Post-earnings spike (> 15% in 5 days)\n- ⚠️ Overbought (RSI > 70 + near 52w high)\n- ⚠️ Risk-off mode (GLD/TLT/UUP rising)\n- ⚠️ Geopolitical keywords (Taiwan, China, etc.)\n- ⚠️ Breaking news alerts\n\n## Performance Options\n\n| Flag | Speed | Description |\n|------|-------|-------------|\n| (default) | 5-10s | Full analysis |\n| `--no-insider` | 3-5s | Skip SEC EDGAR |\n| `--fast` | 2-3s | Skip insider + news |\n\n## Data Sources\n\n- [Yahoo Finance](https://finance.yahoo.com) — Prices, fundamentals, movers\n- [CoinGecko](https://coingecko.com) — Crypto trending, market data\n- [CNN Fear & Greed](https://money.cnn.com/data/fear-and-greed/) — Sentiment\n- [SEC EDGAR](https://www.sec.gov/edgar) — Insider trading\n- [Google News RSS](https://news.google.com) — Breaking news\n- [Twitter/X](https://x.com) — Social sentiment (via bird CLI)\n\n## Storage\n\n| Data | Location |\n|------|----------|\n| Portfolios | `~/.clawdbot/skills/stock-analysis/portfolios.json` |\n| Watchlist | `~/.clawdbot/skills/stock-analysis/watchlist.json` |\n\n## Testing\n\n```bash\nuv run pytest scripts/test_stock_analysis.py -v\n```\n\n## Limitations\n\n- Yahoo Finance may lag 15-20 minutes\n- Short interest lags ~2 weeks (FINRA)\n- US markets only\n\n## Disclaimer\n\n⚠️ **NOT FINANCIAL ADVICE.** For informational purposes only. Consult a licensed financial advisor before making investment decisions.\n\n---\n\nBuilt for [OpenClaw](https://openclaw.ai) 🦞 | [ClawHub](https://clawhub.ai)\n\nFile v6.1.0:_meta.json\n\n{\n  \"ownerId\": \"kn77fv9851hjcqe52zqx0bhhbx7z680h\",\n  \"slug\": \"stock-analysis\",\n  \"version\": \"6.1.0\",\n  \"publishedAt\": 1770030459843\n}\n\nFile v6.1.0:App-Plan.md\n\n# StockPulse - Commercial Product Roadmap\n\n## Vision\n\nTransform the stock-analysis skill into **StockPulse**, a commercial mobile app for retail investors with AI-powered stock and crypto analysis, portfolio tracking, and personalized alerts.\n\n## Technical Decisions\n\n- **Mobile:** Flutter (iOS + Android cross-platform)\n- **Backend:** Python FastAPI on AWS (ECS/Lambda)\n- **Database:** PostgreSQL (RDS) + Redis (ElastiCache)\n- **Auth:** AWS Cognito or Firebase Auth\n- **Monetization:** Freemium + Subscription ($9.99/mo or $79.99/yr)\n\n---\n\n## Architecture Overview\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                      MOBILE APP (Flutter)                        │\n│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │\n│  │Dashboard │ │Portfolio │ │ Analysis │ │ Alerts   │           │\n│  └──────────┘ └──────────┘ └──────────┘ └──────────┘           │\n└─────────────────────────────────────────────────────────────────┘\n                              │ HTTPS/REST\n                              ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                      API GATEWAY (AWS)                           │\n│                   Rate Limiting, Auth, Caching                   │\n└─────────────────────────────────────────────────────────────────┘\n                              │\n                              ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                   BACKEND (FastAPI on ECS)                       │\n│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │\n│  │ Auth Service │ │ Analysis API │ │ Portfolio API│            │\n│  └──────────────┘ └──────────────┘ └──────────────┘            │\n│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │\n│  │ Alerts Svc   │ │ Subscription │ │ User Service │            │\n│  └──────────────┘ └──────────────┘ └──────────────┘            │\n└─────────────────────────────────────────────────────────────────┘\n                              │\n        ┌─────────────────────┼─────────────────────┐\n        ▼                     ▼                     ▼\n┌──────────────┐     ┌──────────────┐     ┌──────────────┐\n│  PostgreSQL  │     │    Redis     │     │     S3       │\n│   (RDS)      │     │ (ElastiCache)│     │  (Reports)   │\n└──────────────┘     └──────────────┘     └──────────────┘\n\n                    BACKGROUND WORKERS (Lambda/ECS)\n┌─────────────────────────────────────────────────────────────────┐\n│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │\n│  │Price Updater │ │Alert Checker │ │Daily Reports │            │\n│  │  (5 min)     │ │  (1 min)     │ │  (Daily)     │            │\n│  └──────────────┘ └──────────────┘ └──────────────┘            │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Feature Tiers\n\n### Free Tier\n- 1 portfolio (max 10 assets)\n- Basic stock/crypto analysis\n- Daily market summary\n- Limited to 5 analyses/day\n- Ads displayed\n\n### Premium ($9.99/mo)\n- Unlimited portfolios & assets\n- Full 8-dimension analysis\n- Real-time price alerts\n- Push notifications\n- Period reports (daily/weekly/monthly)\n- No ads\n- Priority support\n\n### Pro ($19.99/mo) - Future\n- API access\n- Custom watchlists\n- Advanced screeners\n- Export to CSV/PDF\n- Portfolio optimization suggestions\n\n---\n\n## Development Phases\n\n### Phase 1: Backend API\n\n**Goal:** Convert Python scripts to production REST API\n\n#### Tasks:\n1. **Project Setup**\n   - FastAPI project structure\n   - Docker containerization\n   - CI/CD pipeline (GitHub Actions)\n   - AWS infrastructure (Terraform)\n\n2. **Core API Endpoints**\n   ```\n   POST /auth/register\n   POST /auth/login\n   POST /auth/refresh\n\n   GET  /analysis/{ticker}\n   POST /analysis/batch\n\n   GET  /portfolios\n   POST /portfolios\n   PUT  /portfolios/{id}\n   DELETE /portfolios/{id}\n\n   GET  /portfolios/{id}/assets\n   POST /portfolios/{id}/assets\n   PUT  /portfolios/{id}/assets/{ticker}\n   DELETE /portfolios/{id}/assets/{ticker}\n\n   GET  /portfolios/{id}/performance?period=weekly\n   GET  /portfolios/{id}/summary\n\n   GET  /alerts\n   POST /alerts\n   DELETE /alerts/{id}\n\n   GET  /user/subscription\n   POST /user/subscription/upgrade\n   ```\n\n3. **Database Schema**\n   ```sql\n   users (id, email, password_hash, created_at, subscription_tier)\n   portfolios (id, user_id, name, created_at, updated_at)\n   assets (id, portfolio_id, ticker, asset_type, quantity, cost_basis)\n   alerts (id, user_id, ticker, condition, threshold, enabled)\n   analysis_cache (ticker, data, expires_at)\n   subscriptions (id, user_id, stripe_id, status, expires_at)\n   ```\n\n4. **Refactor Existing Code**\n   - Extract `analyze_stock.py` into modules:\n     - `analysis/earnings.py`\n     - `analysis/fundamentals.py`\n     - `analysis/sentiment.py`\n     - `analysis/crypto.py`\n     - `analysis/market_context.py`\n   - Add async support throughout\n   - Implement proper caching (Redis)\n   - Rate limiting per user tier\n\n#### Files to Create:\n```\nbackend/\n├── app/\n│   ├── main.py              # FastAPI app\n│   ├── config.py            # Settings\n│   ├── models/              # SQLAlchemy models\n│   ├── schemas/             # Pydantic schemas\n│   ├── routers/             # API routes\n│   │   ├── auth.py\n│   │   ├── analysis.py\n│   │   ├── portfolios.py\n│   │   └── alerts.py\n│   ├── services/            # Business logic\n│   │   ├── analysis/        # Refactored from analyze_stock.py\n│   │   ├── portfolio.py\n│   │   └── alerts.py\n│   └── workers/             # Background tasks\n├── tests/\n├── Dockerfile\n├── docker-compose.yml\n└── requirements.txt\n```\n\n---\n\n### Phase 2: Flutter Mobile App\n\n**Goal:** Build polished cross-platform mobile app\n\n#### Screens:\n1. **Onboarding** - Welcome, feature highlights, sign up/login\n2. **Dashboard** - Market overview, portfolio summary, alerts\n3. **Analysis** - Search ticker, view full analysis, save to portfolio\n4. **Portfolio** - List portfolios, asset breakdown, P&L chart\n5. **Alerts** - Manage price alerts, notification settings\n6. **Settings** - Account, subscription, preferences\n\n#### Key Flutter Packages:\n```yaml\ndependencies:\n  flutter_bloc: ^8.0.0      # State management\n  dio: ^5.0.0               # HTTP client\n  go_router: ^12.0.0        # Navigation\n  fl_chart: ^0.65.0         # Charts\n  firebase_messaging: ^14.0.0  # Push notifications\n  in_app_purchase: ^3.0.0   # Subscriptions\n  shared_preferences: ^2.0.0\n  flutter_secure_storage: ^9.0.0\n```\n\n#### App Structure:\n```\nlib/\n├── main.dart\n├── app/\n│   ├── routes.dart\n│   └── theme.dart\n├── features/\n│   ├── auth/\n│   │   ├── bloc/\n│   │   ├── screens/\n│   │   └── widgets/\n│   ├── dashboard/\n│   ├── analysis/\n│   ├── portfolio/\n│   ├── alerts/\n│   └── settings/\n├── core/\n│   ├── api/\n│   ├── models/\n│   └── utils/\n└── shared/\n    └── widgets/\n```\n\n---\n\n### Phase 3: Infrastructure & DevOps\n\n**Goal:** Production-ready cloud infrastructure\n\n#### AWS Services:\n- **ECS Fargate** - Backend containers\n- **RDS PostgreSQL** - Database\n- **ElastiCache Redis** - Caching\n- **S3** - Static assets, reports\n- **CloudFront** - CDN\n- **Cognito** - Authentication\n- **SES** - Email notifications\n- **SNS** - Push notifications\n- **CloudWatch** - Monitoring\n- **WAF** - Security\n\n#### Terraform Modules:\n```\ninfrastructure/\n├── main.tf\n├── variables.tf\n├── modules/\n│   ├── vpc/\n│   ├── ecs/\n│   ├── rds/\n│   ├── elasticache/\n│   └── cognito/\n└── environments/\n    ├── dev/\n    ├── staging/\n    └── prod/\n```\n\n#### Estimated Monthly Costs (Production):\n| Service | Est. Cost |\n|---------|-----------|\n| ECS Fargate (2 tasks) | $50-100 |\n| RDS (db.t3.small) | $30-50 |\n| ElastiCache (cache.t3.micro) | $15-25 |\n| S3 + CloudFront | $10-20 |\n| Other (Cognito, SES, etc.) | $20-30 |\n| **Total** | **$125-225/mo** |\n\n---\n\n### Phase 4: Payments & Subscriptions\n\n**Goal:** Integrate Stripe for subscriptions\n\n#### Implementation:\n1. Stripe subscription products (Free, Premium, Pro)\n2. In-app purchase for iOS/Android\n3. Webhook handlers for subscription events\n4. Grace period handling\n5. Receipt validation\n\n#### Stripe Integration:\n```python\n# Backend webhook handler\n@router.post(\"/webhooks/stripe\")\nasync def stripe_webhook(request: Request):\n    event = stripe.Webhook.construct_event(...)\n\n    if event.type == \"customer.subscription.updated\":\n        update_user_tier(event.data.object)\n    elif event.type == \"customer.subscription.deleted\":\n        downgrade_to_free(event.data.object)\n```\n\n---\n\n### Phase 5: Push Notifications & Alerts\n\n**Goal:** Real-time price alerts and notifications\n\n#### Alert Types:\n- Price above/below threshold\n- Percentage change (daily)\n- Earnings announcement\n- Breaking news (geopolitical)\n- Portfolio performance\n\n#### Implementation:\n- Firebase Cloud Messaging (FCM)\n- Background worker checks alerts every minute\n- Rate limit: max 10 alerts/day per free user\n\n---\n\n### Phase 6: Analytics & Monitoring\n\n**Goal:** Track usage, errors, business metrics\n\n#### Tools:\n- **Mixpanel/Amplitude** - Product analytics\n- **Sentry** - Error tracking\n- **CloudWatch** - Infrastructure metrics\n- **Custom dashboard** - Business KPIs\n\n#### Key Metrics:\n- DAU/MAU\n- Conversion rate (free → premium)\n- Churn rate\n- API response times\n- Analysis accuracy feedback\n\n---\n\n## Security Considerations\n\n1. **Authentication**\n   - JWT tokens with refresh rotation\n   - OAuth2 (Google, Apple Sign-In)\n   - 2FA optional for premium users\n\n2. **Data Protection**\n   - Encrypt PII at rest (RDS encryption)\n   - TLS 1.3 for all API traffic\n   - No plaintext passwords\n\n3. **API Security**\n   - Rate limiting per tier\n   - Input validation (Pydantic)\n   - SQL injection prevention (SQLAlchemy ORM)\n   - CORS configuration\n\n4. **Compliance**\n   - Privacy policy\n   - Terms of service\n   - GDPR data export/deletion\n   - Financial disclaimer (not investment advice)\n\n---\n\n## Risks & Mitigations\n\n| Risk | Impact | Mitigation |\n|------|--------|------------|\n| Yahoo Finance rate limits | High | Implement caching, use paid API fallback |\n| App store rejection | Medium | Follow guidelines, proper disclaimers |\n| Data accuracy issues | High | Clear disclaimers, data validation |\n| Security breach | Critical | Security audit, penetration testing |\n| Low conversion rate | Medium | A/B testing, feature gating |\n\n---\n\n## Success Metrics (Year 1)\n\n| Metric | Target |\n|--------|--------|\n| App downloads | 10,000+ |\n| DAU | 1,000+ |\n| Premium subscribers | 500+ |\n| Monthly revenue | $5,000+ |\n| App store rating | 4.5+ stars |\n| Churn rate | <5%/month |\n\n---\n\n## Next Steps (Immediate)\n\n1. **Validate idea** - User interviews, landing page\n2. **Design** - Figma mockups for key screens\n3. **Backend MVP** - Core API endpoints\n4. **Flutter prototype** - Basic app with analysis feature\n5. **Beta testing** - TestFlight/Google Play beta\n\n---\n\n## Repository Structure (Final)\n\n```\nstockpulse/\n├── backend/                 # FastAPI backend\n│   ├── app/\n│   ├── tests/\n│   ├── Dockerfile\n│   └── requirements.txt\n├── mobile/                  # Flutter app\n│   ├── lib/\n│   ├── test/\n│   ├── ios/\n│   ├── android/\n│   └── pubspec.yaml\n├── infrastructure/          # Terraform\n│   ├── modules/\n│   └── environments/\n├── docs/                    # Documentation\n│   ├── api/\n│   └── architecture/\n└── scripts/                 # Utility scripts\n```\n\n---\n\n## Timeline Summary (Planning Only)\n\n| Phase | Duration | Dependencies |\n|-------|----------|--------------|\n| 1. Backend API | 4-6 weeks | - |\n| 2. Flutter App | 6-8 weeks | Phase 1 |\n| 3. Infrastructure | 2-3 weeks | Phase 1 |\n| 4. Payments | 2 weeks | Phase 2, 3 |\n| 5. Notifications | 2 weeks | Phase 2, 3 |\n| 6. Analytics | 1 week | Phase 2 |\n| **Total** | **17-22 weeks** | |\n\nThis is a planning document. No fixed timeline - execute phases as resources allow.\n\n---\n\n**Disclaimer:** This tool is for informational purposes only and does NOT constitute financial advice.\n\nFile v6.1.0:docs/ARCHITECTURE.md\n\n# Technical Architecture\n\nHow Stock Analysis v6.0 works under the hood.\n\n## System Overview\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                        Stock Analysis v6.0                           │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                      │\n│  ┌──────────────────────────────────────────────────────────────┐   │\n│  │                    CLI Interface                              │   │\n│  │  analyze_stock.py | dividends.py | watchlist.py | portfolio.py│   │\n│  └────────────────────────────┬─────────────────────────────────┘   │\n│                               │                                      │\n│  ┌────────────────────────────▼─────────────────────────────────┐   │\n│  │                   Analysis Engine                             │   │\n│  │                                                               │   │\n│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐            │   │\n│  │  │Earnings │ │Fundmtls │ │Analysts │ │Historical│            │   │\n│  │  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘            │   │\n│  │       │           │           │           │                   │   │\n│  │  ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐            │   │\n│  │  │ Market  │ │ Sector  │ │Momentum │ │Sentiment│            │   │\n│  │  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘            │   │\n│  │       │           │           │           │                   │   │\n│  │       └───────────┴───────────┴───────────┘                   │   │\n│  │                          │                                    │   │\n│  │                    [Synthesizer]                              │   │\n│  │                          │                                    │   │\n│  │                    [Signal Output]                            │   │\n│  └──────────────────────────────────────────────────────────────┘   │\n│                               │                                      │\n│  ┌────────────────────────────▼─────────────────────────────────┐   │\n│  │                    Data Sources                               │   │\n│  │                                                               │   │\n│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐            │   │\n│  │  │ Yahoo   │ │  CNN    │ │   SEC   │ │ Google  │            │   │\n│  │  │ Finance │ │Fear/Grd │ │ EDGAR   │ │  News   │            │   │\n│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘            │   │\n│  └──────────────────────────────────────────────────────────────┘   │\n│                                                                      │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Core Components\n\n### 1. Data Fetching (`fetch_stock_data`)\n\n```python\ndef fetch_stock_data(ticker: str, verbose: bool = False) -> StockData | None:\n    \"\"\"Fetch stock data from Yahoo Finance with retry logic.\"\"\"\n```\n\n**Features:**\n- 3 retries with exponential backoff\n- Graceful handling of missing data\n- Asset type detection (stock vs crypto)\n\n**Returns:** `StockData` dataclass with:\n- `info`: Company fundamentals\n- `earnings_history`: Past earnings\n- `analyst_info`: Ratings and targets\n- `price_history`: 1-year OHLCV\n\n### 2. Analysis Modules\n\nEach dimension has its own analyzer:\n\n| Module | Function | Returns |\n|--------|----------|---------|\n| Earnings | `analyze_earnings_surprise()` | `EarningsSurprise` |\n| Fundamentals | `analyze_fundamentals()` | `Fundamentals` |\n| Analysts | `analyze_analyst_sentiment()` | `AnalystSentiment` |\n| Historical | `analyze_historical_patterns()` | `HistoricalPatterns` |\n| Market | `analyze_market_context()` | `MarketContext` |\n| Sector | `analyze_sector_performance()` | `SectorComparison` |\n| Momentum | `analyze_momentum()` | `MomentumAnalysis` |\n| Sentiment | `analyze_sentiment()` | `SentimentAnalysis` |\n\n### 3. Sentiment Sub-Analyzers\n\nSentiment runs 5 parallel async tasks:\n\n```python\nresults = await asyncio.gather(\n    get_fear_greed_index(),      # CNN Fear & Greed\n    get_short_interest(data),    # Yahoo Finance\n    get_vix_term_structure(),    # VIX Futures\n    get_insider_activity(),      # SEC EDGAR\n    get_put_call_ratio(data),    # Options Chain\n    return_exceptions=True\n)\n```\n\n**Timeout:** 10 seconds per indicator\n**Minimum:** 2 of 5 indicators required\n\n### 4. Signal Synthesis\n\n```python\ndef synthesize_signal(\n    ticker, company_name,\n    earnings, fundamentals, analysts, historical,\n    market_context, sector, earnings_timing,\n    momentum, sentiment,\n    breaking_news, geopolitical_risk_warning, geopolitical_risk_penalty\n) -> Signal:\n```\n\n**Scoring:**\n1. Collect available component scores\n2. Apply normalized weights\n3. Calculate weighted average → `final_score`\n4. Apply adjustments (timing, overbought, risk-off)\n5. Determine recommendation threshold\n\n**Thresholds:**\n```python\nif final_score > 0.33:\n    recommendation = \"BUY\"\nelif final_score < -0.33:\n    recommendation = \"SELL\"\nelse:\n    recommendation = \"HOLD\"\n```\n\n---\n\n## Caching Strategy\n\n### What's Cached\n\n| Data | TTL | Key |\n|------|-----|-----|\n| Market Context | 1 hour | `market_context` |\n| Fear & Greed | 1 hour | `fear_greed` |\n| VIX Structure | 1 hour | `vix_structure` |\n| Breaking News | 1 hour | `breaking_news` |\n\n### Cache Implementation\n\n```python\n_SENTIMENT_CACHE = {}\n_CACHE_TTL_SECONDS = 3600  # 1 hour\n\ndef _get_cached(key: str):\n    if key in _SENTIMENT_CACHE:\n        value, timestamp = _SENTIMENT_CACHE[key]\n        if time.time() - timestamp < _CACHE_TTL_SECONDS:\n            return value\n    return None\n\ndef _set_cache(key: str, value):\n    _SENTIMENT_CACHE[key] = (value, time.time())\n```\n\n### Why This Matters\n\n- First stock: ~8 seconds (full fetch)\n- Second stock: ~4 seconds (reuses market data)\n- Same stock again: ~4 seconds (no stock-level cache)\n\n---\n\n## Data Flow\n\n### Single Stock Analysis\n\n```\nUser Input: \"AAPL\"\n     │\n     ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 1. FETCH DATA (yfinance)                                    │\n│    - Stock info, earnings, price history                    │\n│    - ~2 seconds                                             │\n└────────────────────────┬────────────────────────────────────┘\n                         │\n                         ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 2. PARALLEL ANALYSIS                                        │\n│                                                             │\n│    ┌──────────┐ ┌──────────┐ ┌──────────┐                  │\n│    │ Earnings │ │Fundmtls  │ │ Analysts │  ... (sync)      │\n│    └──────────┘ └──────────┘ └──────────┘                  │\n│                                                             │\n│    ┌────────────────────────────────────┐                  │\n│    │ Market Context (cached or fetch)   │  ~1 second       │\n│    └────────────────────────────────────┘                  │\n│                                                             │\n│    ┌────────────────────────────────────┐                  │\n│    │ Sentiment (5 async tasks)          │  ~3-5 seconds    │\n│    │  - Fear/Greed (cached)             │                  │\n│    │  - Short Interest                  │                  │\n│    │  - VIX Structure (cached)          │                  │\n│    │  - Insider Trading (slow!)         │                  │\n│    │  - Put/Call Ratio                  │                  │\n│    └────────────────────────────────────┘                  │\n└────────────────────────┬────────────────────────────────────┘\n                         │\n                         ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 3. SYNTHESIZE SIGNAL                                        │\n│    - Combine scores with weights                            │\n│    - Apply adjustments                                      │\n│    - Generate caveats                                       │\n│    - ~10 ms                                                 │\n└────────────────────────┬────────────────────────────────────┘\n                         │\n                         ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 4. OUTPUT                                                   │\n│    - Text or JSON format                                    │\n│    - Include disclaimer                                     │\n└─────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Risk Detection\n\n### Geopolitical Risk\n\n```python\nGEOPOLITICAL_RISK_MAP = {\n    \"taiwan\": {\n        \"keywords\": [\"taiwan\", \"tsmc\", \"strait\"],\n        \"sectors\": [\"Technology\", \"Communication Services\"],\n        \"affected_tickers\": [\"NVDA\", \"AMD\", \"TSM\", ...],\n        \"impact\": \"Semiconductor supply chain disruption\",\n    },\n    # ... china, russia_ukraine, middle_east, banking_crisis\n}\n```\n\n**Process:**\n1. Check breaking news for keywords\n2. If keyword found, check if ticker in affected list\n3. Apply confidence penalty (30% direct, 15% sector)\n\n### Breaking News\n\n```python\ndef check_breaking_news(verbose: bool = False) -> list[str] | None:\n    \"\"\"Scan Google News RSS for crisis keywords (last 24h).\"\"\"\n```\n\n**Crisis Keywords:**\n```python\nCRISIS_KEYWORDS = {\n    \"war\": [\"war\", \"invasion\", \"military strike\", ...],\n    \"economic\": [\"recession\", \"crisis\", \"collapse\", ...],\n    \"regulatory\": [\"sanctions\", \"embargo\", \"ban\", ...],\n    \"disaster\": [\"earthquake\", \"hurricane\", \"pandemic\", ...],\n    \"financial\": [\"emergency rate\", \"bailout\", ...],\n}\n```\n\n---\n\n## File Structure\n\n```\nstock-analysis/\n├── scripts/\n│   ├── analyze_stock.py      # Main analysis engine (2500+ lines)\n│   ├── portfolio.py          # Portfolio management\n│   ├── dividends.py          # Dividend analysis\n│   ├── watchlist.py          # Watchlist + alerts\n│   └── test_stock_analysis.py # Unit tests\n├── docs/\n│   ├── CONCEPT.md            # Philosophy & ideas\n│   ├── USAGE.md              # Practical guide\n│   └── ARCHITECTURE.md       # This file\n├── SKILL.md                  # OpenClaw skill definition\n├── README.md                 # Project overview\n└── .clawdhub/                # ClawHub metadata\n```\n\n---\n\n## Data Storage\n\n### Portfolio (`portfolios.json`)\n\n```json\n{\n  \"portfolios\": [\n    {\n      \"name\": \"Retirement\",\n      \"created_at\": \"2024-01-01T00:00:00Z\",\n      \"assets\": [\n        {\n          \"ticker\": \"AAPL\",\n          \"quantity\": 100,\n          \"cost_basis\": 150.00,\n          \"type\": \"stock\",\n          \"added_at\": \"2024-01-01T00:00:00Z\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n### Watchlist (`watchlist.json`)\n\n```json\n[\n  {\n    \"ticker\": \"NVDA\",\n    \"added_at\": \"2024-01-15T10:30:00Z\",\n    \"price_at_add\": 700.00,\n    \"target_price\": 800.00,\n    \"stop_price\": 600.00,\n    \"alert_on_signal\": true,\n    \"last_signal\": \"BUY\",\n    \"last_check\": \"2024-01-20T08:00:00Z\"\n  }\n]\n```\n\n---\n\n## Dependencies\n\n```python\n# /// script\n# requires-python = \">=3.10\"\n# dependencies = [\n#     \"yfinance>=0.2.40\",      # Stock data\n#     \"pandas>=2.0.0\",         # Data manipulation\n#     \"fear-and-greed>=0.4\",   # CNN Fear & Greed\n#     \"edgartools>=2.0.0\",     # SEC EDGAR filings\n#     \"feedparser>=6.0.0\",     # RSS parsing\n# ]\n# ///\n```\n\n**Why These:**\n- `yfinance`: Most reliable free stock API\n- `pandas`: Industry standard for financial data\n- `fear-and-greed`: Simple CNN F&G wrapper\n- `edgartools`: Clean SEC EDGAR access\n- `feedparser`: Robust RSS parsing\n\n---\n\n## Performance Optimization\n\n### Current\n\n| Operation | Time |\n|-----------|------|\n| yfinance fetch | ~2s |\n| Market context | ~1s (cached after) |\n| Insider trading | ~3-5s (slowest!) |\n| Sentiment (parallel) | ~3-5s |\n| Synthesis | ~10ms |\n| **Total** | **5-10s** |\n\n### Fast Mode (`--fast`)\n\nSkips:\n- Insider trading (SEC EDGAR)\n- Breaking news scan\n\n**Result:** 2-3 seconds\n\n### Future Optimizations\n\n1. **Stock-level caching** — Cache fundamentals for 24h\n2. **Batch API calls** — yfinance supports multiple tickers\n3. **Background refresh** — Pre-fetch watchlist data\n4. **Local SEC data** — Avoid EDGAR API calls\n\n---\n\n## Error Handling\n\n### Retry Strategy\n\n```python\nmax_retries = 3\nfor attempt in range(max_retries):\n    try:\n        # fetch data\n    except Exception as e:\n        wait_time = 2 ** attempt  # Exponential backoff: 1, 2, 4 seconds\n        time.sleep(wait_time)\n```\n\n### Graceful Degradation\n\n- Missing earnings → Skip dimension, reweight\n- Missing analysts → Skip dimension, reweight\n- Missing sentiment → Skip dimension, reweight\n- API failure → Return None, continue with partial data\n\n### Minimum Requirements\n\n- At least 2 of 8 dimensions required\n- At least 2 of 5 sentiment indicators required\n- Otherwise → HOLD with low confidence\n\nFile v6.1.0:docs/CONCEPT.md\n\n# Concept & Philosophy\n\n## The Problem\n\nMaking investment decisions is hard. There's too much data, too many opinions, and too much noise. Most retail investors either:\n\n1. **Over-simplify** — Buy based on headlines or tips\n2. **Over-complicate** — Get lost in endless research\n3. **Freeze** — Analysis paralysis, never act\n\n## The Solution\n\nStock Analysis provides a **structured, multi-dimensional framework** that:\n\n- Aggregates data from multiple sources\n- Weighs different factors objectively\n- Produces a clear **BUY / HOLD / SELL** signal\n- Explains the reasoning with bullet points\n- Flags risks and caveats\n\nThink of it as a **second opinion** — not a replacement for your judgment, but a systematic check.\n\n---\n\n## Core Philosophy\n\n### 1. Multiple Perspectives Beat Single Metrics\n\nNo single metric tells the whole story:\n- A low P/E might mean \"cheap\" or \"dying business\"\n- High analyst ratings might mean \"priced in\" or \"genuine upside\"\n- Strong momentum might mean \"trend\" or \"overbought\"\n\nBy combining **8 dimensions**, we get a more complete picture.\n\n### 2. Contrarian Signals Matter\n\nSome of our best signals are **contrarian**:\n\n| Indicator | Crowd Says | We Interpret |\n|-----------|------------|--------------|\n| Extreme Fear (Fear & Greed < 25) | \"Sell everything!\" | Potential buy opportunity |\n| Extreme Greed (> 75) | \"Easy money!\" | Caution, reduce exposure |\n| High Short Interest + Days to Cover | \"Stock is doomed\" | Squeeze potential |\n| Insider Buying | (often ignored) | Smart money signal |\n\n### 3. Timing Matters\n\nA good stock at the wrong time is a bad trade:\n\n- **Pre-earnings** — Even strong stocks can gap down 10%+\n- **Post-spike** — Buying after a 20% run often means buying the top\n- **Overbought** — RSI > 70 + near 52-week high = high-risk entry\n\nWe detect these timing issues and adjust recommendations accordingly.\n\n### 4. Context Changes Everything\n\nThe same stock behaves differently in different market regimes:\n\n| Regime | Characteristics | Impact |\n|--------|-----------------|--------|\n| **Bull** | VIX < 20, SPY up | BUY signals more reliable |\n| **Bear** | VIX > 30, SPY down | Even good stocks fall |\n| **Risk-Off** | GLD/TLT/UUP rising | Flight to safety, reduce equity |\n| **Geopolitical** | Crisis keywords | Sector-specific penalties |\n\n### 5. Dividends Are Different\n\nIncome investors have different priorities than growth investors:\n\n| Growth Investor | Income Investor |\n|-----------------|-----------------|\n| Price appreciation | Dividend yield |\n| Revenue growth | Payout sustainability |\n| Market share | Dividend growth rate |\n| P/E ratio | Safety of payment |\n\nThat's why we have a **separate dividend analysis** module.\n\n---\n\n## The 8 Dimensions\n\n### Why These 8?\n\nEach dimension captures a different aspect of investment quality:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    FUNDAMENTAL VALUE                         │\n│  ┌─────────────────┐  ┌─────────────────┐                   │\n│  │    Earnings     │  │  Fundamentals   │                   │\n│  │    Surprise     │  │   (P/E, etc.)   │                   │\n│  │     (30%)       │  │     (20%)       │                   │\n│  └─────────────────┘  └─────────────────┘                   │\n├─────────────────────────────────────────────────────────────┤\n│                    EXTERNAL VALIDATION                       │\n│  ┌─────────────────┐  ┌─────────────────┐                   │\n│  │    Analyst      │  │   Historical    │                   │\n│  │   Sentiment     │  │    Patterns     │                   │\n│  │     (20%)       │  │     (10%)       │                   │\n│  └─────────────────┘  └─────────────────┘                   │\n├─────────────────────────────────────────────────────────────┤\n│                    MARKET ENVIRONMENT                        │\n│  ┌─────────────────┐  ┌─────────────────┐                   │\n│  │    Market       │  │     Sector      │                   │\n│  │    Context      │  │  Performance    │                   │\n│  │     (10%)       │  │     (15%)       │                   │\n│  └─────────────────┘  └─────────────────┘                   │\n├─────────────────────────────────────────────────────────────┤\n│                    TECHNICAL & SENTIMENT                     │\n│  ┌─────────────────┐  ┌─────────────────┐                   │\n│  │    Momentum     │  │   Sentiment     │                   │\n│  │  (RSI, range)   │  │ (Fear, shorts)  │                   │\n│  │     (15%)       │  │     (10%)       │                   │\n│  └─────────────────┘  └─────────────────┘                   │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Weight Rationale\n\n| Weight | Dimension | Rationale |\n|--------|-----------|-----------|\n| 30% | Earnings | Most direct measure of company performance |\n| 20% | Fundamentals | Long-term value indicators |\n| 20% | Analysts | Professional consensus (with skepticism) |\n| 15% | Sector | Relative performance matters |\n| 15% | Momentum | Trend is your friend (until it isn't) |\n| 10% | Market | Rising tide lifts all boats |\n| 10% | Sentiment | Contrarian edge |\n| 10% | Historical | Past behavior predicts future reactions |\n\n**Note:** Weights auto-normalize when data is missing.\n\n---\n\n## Risk Detection Philosophy\n\n### \"Don't Lose Money\"\n\nWarren Buffett's Rule #1. Our risk detection is designed to **prevent bad entries**:\n\n1. **Pre-Earnings Hold** — Don't buy right before a binary event\n2. **Post-Spike Caution** — Don't chase a run-up\n3. **Overbought Warning** — Technical exhaustion\n4. **Risk-Off Mode** — When even good stocks fall\n5. **Geopolitical Flags** — Sector-specific event risk\n\n### False Positive vs False Negative\n\nWe err on the side of **caution**:\n\n- Missing a 10% gain is annoying\n- Catching a 30% loss is devastating\n\nThat's why our caveats are prominent, and we downgrade BUY → HOLD liberally.\n\n---\n\n## Crypto Adaptation\n\nCrypto is fundamentally different from stocks:\n\n| Stocks | Crypto |\n|--------|--------|\n| Earnings | No earnings |\n| P/E Ratio | Market cap tiers |\n| Sector ETFs | BTC correlation |\n| Dividends | Staking yields (not tracked) |\n| SEC Filings | No filings |\n\nWe adapted the framework:\n- **3 dimensions** instead of 8\n- **BTC correlation** as a key metric\n- **Category classification** (L1, DeFi, etc.)\n- **No sentiment** (no insider data for crypto)\n\n---\n\n## Why Not Just Use [X]?\n\n### vs. Stock Screeners (Finviz, etc.)\n- Screeners show data, we provide **recommendations**\n- We combine fundamental + technical + sentiment\n- We flag timing and risk issues\n\n### vs. Analyst Reports\n- Analysts have conflicts of interest\n- Reports are often stale\n- We aggregate multiple signals\n\n### vs. Trading Bots\n- Bots execute, we advise\n- We explain reasoning\n- Human stays in control\n\n### vs. ChatGPT/AI Chat\n- We have **structured scoring**, not just conversation\n- Real-time data fetching\n- Consistent methodology\n\n---\n\n## Limitations We Acknowledge\n\n1. **Data Lag** — Yahoo Finance is 15-20 min delayed\n2. **US Focus** — International stocks have incomplete data\n3. **No Execution** — We advise, you decide and execute\n4. **Past ≠ Future** — All models have limits\n5. **Black Swans** — Can't predict unpredictable events\n\n**This is a tool, not a crystal ball.**\n\n---\n\n## The Bottom Line\n\nStock Analysis v6.0 is designed to be your **systematic second opinion**:\n\n- ✅ Multi-dimensional analysis\n- ✅ Clear recommendations\n- ✅ Risk detection\n- ✅ Explained reasoning\n- ✅ Fast and automated\n\n**NOT:**\n- ❌ Financial advice\n- ❌ Guaranteed returns\n- ❌ Replacement for research\n- ❌ Trading signals\n\nUse it wisely. 📈\n\nFile v6.1.0:docs/HOT_SCANNER.md\n\n# 🔥 Hot Scanner\n\nFind viral stocks & crypto trends in real-time by aggregating multiple data sources.\n\n## Overview\n\nThe Hot Scanner answers one question: **\"What's hot right now?\"**\n\nIt aggregates data from:\n- CoinGecko (trending coins, biggest movers)\n- Google News (finance & crypto headlines)\n- Yahoo Finance (gainers, losers, most active)\n- Twitter/X (social sentiment, optional)\n\n## Quick Start\n\n```bash\n# Full scan with all sources\npython3 scripts/hot_scanner.py\n\n# Skip social media (faster)\npython3 scripts/hot_scanner.py --no-social\n\n# JSON output for automation\npython3 scripts/hot_scanner.py --json\n```\n\n## Output Format\n\n### Console Output\n\n```\n============================================================\n🔥 HOT SCANNER v2 - What's Trending Right Now?\n📅 2026-02-02 10:45:30 UTC\n============================================================\n\n📊 TOP TRENDING (by buzz):\n   1. BTC      (6 pts) [CoinGecko, Google News] 📉 bearish (-2.5%)\n   2. ETH      (5 pts) [CoinGecko, Twitter] 📉 bearish (-7.2%)\n   3. NVDA     (3 pts) [Google News, Yahoo] 📰 Earnings beat...\n\n🪙 CRYPTO HIGHLIGHTS:\n   🚀 RIVER    River              +14.0%\n   📉 BTC      Bitcoin             -2.5%\n   📉 ETH      Ethereum            -7.2%\n\n📈 STOCK MOVERS:\n   🟢 NVDA (gainers)\n   🔴 TSLA (losers)\n   📊 AAPL (most active)\n\n🐦 SOCIAL BUZZ:\n   [twitter] Bitcoin to $100k prediction...\n   [reddit_wsb] GME yolo update...\n\n📰 BREAKING NEWS:\n   [BTC, ETH] Crypto crash: $2.5B liquidated...\n   [NVDA] Nvidia beats earnings expectations...\n```\n\n### JSON Output\n\n```json\n{\n  \"scan_time\": \"2026-02-02T10:45:30+00:00\",\n  \"top_trending\": [\n    {\n      \"symbol\": \"BTC\",\n      \"mentions\": 6,\n      \"sources\": [\"CoinGecko Trending\", \"Google News\"],\n      \"signals\": [\"📉 bearish (-2.5%)\"]\n    }\n  ],\n  \"crypto_highlights\": [...],\n  \"stock_highlights\": [...],\n  \"social_buzz\": [...],\n  \"breaking_news\": [...]\n}\n```\n\n## Data Sources\n\n### CoinGecko (No Auth Required)\n\n| Endpoint | Data |\n|----------|------|\n| `/search/trending` | Top 15 trending coins |\n| `/coins/markets` | Top 100 by market cap with 24h changes |\n\n**Scoring:** Trending coins get 2 points, movers with >3% change get 1 point.\n\n### Google News RSS (No Auth Required)\n\n| Feed | Content |\n|------|---------|\n| Business News | General finance headlines |\n| Crypto Search | Bitcoin, Ethereum, crypto keywords |\n\n**Ticker Extraction:** Uses regex patterns and company name mappings.\n\n### Yahoo Finance (No Auth Required)\n\n| Page | Data |\n|------|------|\n| `/gainers` | Top gaining stocks |\n| `/losers` | Top losing stocks |\n| `/most-active` | Highest volume stocks |\n\n**Note:** Requires gzip decompression.\n\n### Twitter/X (Auth Required)\n\nUses [bird CLI](https://github.com/steipete/bird) for Twitter search.\n\n**Searches:**\n- `stock OR $SPY OR $QQQ OR earnings`\n- `bitcoin OR ethereum OR crypto OR $BTC`\n\n## Twitter/X Setup\n\n### 1. Install bird CLI\n\n```bash\n# macOS\nbrew install steipete/tap/bird\n\n# npm\nnpm install -g @steipete/bird\n```\n\n### 2. Get Auth Tokens\n\n**Option A: Browser cookies (macOS)**\n1. Login to x.com in Safari/Chrome\n2. Grant Terminal \"Full Disk Access\" in System Settings\n3. Run `bird whoami` to verify\n\n**Option B: Manual extraction**\n1. Open x.com in Chrome\n2. DevTools (F12) → Application → Cookies → x.com\n3. Copy `auth_token` and `ct0` values\n\n### 3. Configure\n\nCreate `.env` file in the skill directory:\n\n```bash\n# /path/to/stock-analysis/.env\nAUTH_TOKEN=your_auth_token_here\nCT0=your_ct0_token_here\n```\n\nOr export as environment variables:\n\n```bash\nexport AUTH_TOKEN=\"...\"\nexport CT0=\"...\"\n```\n\n### 4. Verify\n\n```bash\nbird whoami\n# Should show: 🙋 @YourUsername\n```\n\n## Scoring System\n\nEach mention from a source adds points:\n\n| Source | Points |\n|--------|--------|\n| CoinGecko Trending | 2 |\n| CoinGecko Movers | 1 |\n| Google News | 1 |\n| Yahoo Finance | 1 |\n| Twitter/X | 1 |\n| Reddit (high score) | 2 |\n| Reddit (normal) | 1 |\n\nSymbols are ranked by total points across all sources.\n\n## Ticker Extraction\n\n### Patterns\n\n```python\n# Cashtag: $AAPL\nr'\\$([A-Z]{1,5})\\b'\n\n# Parentheses: (AAPL)\nr'\\(([A-Z]{2,5})\\)'\n\n# Stock mentions: AAPL stock, AAPL shares\nr'\\b([A-Z]{2,5})(?:\\'s|:|\\s+stock|\\s+shares)'\n```\n\n### Company Mappings\n\n```python\n{\n    \"Apple\": \"AAPL\",\n    \"Microsoft\": \"MSFT\",\n    \"Tesla\": \"TSLA\",\n    \"Nvidia\": \"NVDA\",\n    \"Bitcoin\": \"BTC\",\n    \"Ethereum\": \"ETH\",\n    # ... etc\n}\n```\n\n### Crypto Keywords\n\n```python\n{\n    \"bitcoin\": \"BTC\",\n    \"ethereum\": \"ETH\",\n    \"solana\": \"SOL\",\n    \"dogecoin\": \"DOGE\",\n    # ... etc\n}\n```\n\n## Automation\n\n### Cron Job\n\n```bash\n# Daily at 8 AM\n0 8 * * * cd /path/to/stock-analysis && python3 scripts/hot_scanner.py --json > cache/daily_scan.json\n```\n\n### OpenClaw Integration\n\n```yaml\n# Cron job config\nname: \"🔥 Daily Hot Scanner\"\nschedule:\n  kind: cron\n  expr: \"0 8 * * *\"\n  tz: \"Europe/Berlin\"\npayload:\n  kind: agentTurn\n  message: \"Run hot scanner and summarize results\"\n  deliver: true\nsessionTarget: isolated\n```\n\n## Caching\n\nResults are saved to:\n- `cache/hot_scan_latest.json` — Most recent scan\n\n## Limitations\n\n- **Reddit:** Blocked without OAuth (403). Requires API application.\n- **Twitter:** Requires auth tokens, may expire.\n- **Yahoo:** Sometimes rate-limited.\n- **Google News:** RSS URLs may change.\n\n## Future Enhancements\n\n- [ ] Reddit API integration (PRAW)\n- [ ] StockTwits integration\n- [ ] Google Trends\n- [ ] Historical trend tracking\n- [ ] Alert thresholds (notify when score > X)\n\n## Troubleshooting\n\n### Twitter not working\n\n```bash\n# Check auth\nbird whoami\n\n# Should see your username\n# If not, re-export tokens\n```\n\n### Yahoo 403 or gzip errors\n\nThe scanner handles gzip automatically. If issues persist, Yahoo may be rate-limiting.\n\n### No tickers found\n\nCheck that news headlines contain recognizable patterns. The scanner uses conservative extraction to avoid false positives.\n\nFile v6.1.0:docs/USAGE.md\n\n# Usage Guide\n\nPractical examples for using Stock Analysis v6.0 in real scenarios.\n\n## Table of Contents\n\n1. [Basic Stock Analysis](#basic-stock-analysis)\n2. [Comparing Stocks](#comparing-stocks)\n3. [Crypto Analysis](#crypto-analysis)\n4. [Dividend Investing](#dividend-investing)\n5. [Portfolio Management](#portfolio-management)\n6. [Watchlist & Alerts](#watchlist--alerts)\n7. [Performance Tips](#performance-tips)\n8. [Interpreting Results](#interpreting-results)\n\n---\n\n## Basic Stock Analysis\n\n### Single Stock\n\n```bash\nuv run scripts/analyze_stock.py AAPL\n```\n\n**Output:**\n```\n===========================================================================\nSTOCK ANALYSIS: AAPL (Apple Inc.)\nGenerated: 2024-02-01T10:30:00\n===========================================================================\n\nRECOMMENDATION: BUY (Confidence: 72%)\n\nSUPPORTING POINTS:\n• Beat by 8.2% - EPS $2.18 vs $2.01 expected\n• Strong margin: 24.1%\n• Analyst consensus: Buy with 12.3% upside (42 analysts)\n• Momentum: RSI 58 (neutral)\n• Sector: Technology uptrend (+5.2% 1m)\n\nCAVEATS:\n• Earnings in 12 days - high volatility expected\n• High market volatility (VIX 24)\n\n===========================================================================\nDISCLAIMER: NOT FINANCIAL ADVICE.\n===========================================================================\n```\n\n### JSON Output\n\nFor programmatic use:\n\n```bash\nuv run scripts/analyze_stock.py AAPL --output json | jq '.recommendation, .confidence'\n```\n\n### Verbose Mode\n\nSee what's happening under the hood:\n\n```bash\nuv run scripts/analyze_stock.py AAPL --verbose\n```\n\n---\n\n## Comparing Stocks\n\n### Side-by-Side Analysis\n\n```bash\nuv run scripts/analyze_stock.py AAPL MSFT GOOGL\n```\n\nEach stock gets a full analysis. Compare recommendations and confidence levels.\n\n### Sector Comparison\n\nCompare stocks in the same sector:\n\n```bash\n# Banks\nuv run scripts/analyze_stock.py JPM BAC WFC GS\n\n# Tech\nuv run scripts/analyze_stock.py AAPL MSFT GOOGL AMZN META\n```\n\n---\n\n## Crypto Analysis\n\n### Basic Crypto\n\n```bash\nuv run scripts/analyze_stock.py BTC-USD\n```\n\n**Crypto-Specific Output:**\n- Market cap classification (large/mid/small)\n- Category (Smart Contract L1, DeFi, etc.)\n- BTC correlation (30-day)\n- Momentum (RSI, price range)\n\n### Compare Cryptos\n\n```bash\nuv run scripts/analyze_stock.py BTC-USD ETH-USD SOL-USD\n```\n\n### Supported Cryptos\n\n```\nBTC, ETH, BNB, SOL, XRP, ADA, DOGE, AVAX, DOT, MATIC,\nLINK, ATOM, UNI, LTC, BCH, XLM, ALGO, VET, FIL, NEAR\n```\n\nUse `-USD` suffix: `BTC-USD`, `ETH-USD`, etc.\n\n---\n\n## Dividend Investing\n\n### Analyze Dividend Stock\n\n```bash\nuv run scripts/dividends.py JNJ\n```\n\n**Output:**\n```\n============================================================\nDIVIDEND ANALYSIS: JNJ (Johnson & Johnson)\n============================================================\n\nCurrent Price:    $160.50\nAnnual Dividend:  $4.76\nDividend Yield:   2.97%\nPayment Freq:     quarterly\nEx-Dividend:      2024-02-15\n\nPayout Ratio:     65.0% (moderate)\n5Y Div Growth:    +5.8%\nConsecutive Yrs:  62\n\nSAFETY SCORE:     78/100\nINCOME RATING:    GOOD\n\nSafety Factors:\n  • Moderate payout ratio (65%)\n  • Good dividend growth (+5.8% CAGR)\n  • Dividend Aristocrat (62+ years)\n\nDividend History:\n  2023: $4.52\n  2022: $4.36\n  2021: $4.24\n  2020: $4.04\n  2019: $3.80\n============================================================\n```\n\n### Compare Dividend Stocks\n\n```bash\nuv run scripts/dividends.py JNJ PG KO MCD VZ T\n```\n\n### Dividend Aristocrats Screen\n\nLook for stocks with:\n- Yield > 2%\n- Payout < 60%\n- Growth > 5%\n- Consecutive years > 25\n\n---\n\n## Portfolio Management\n\n### Create Portfolio\n\n```bash\nuv run scripts/portfolio.py create \"Retirement\"\n```\n\n### Add Holdings\n\n```bash\n# Stocks\nuv run scripts/portfolio.py add AAPL --quantity 100 --cost 150.00\n\n# Crypto\nuv run scripts/portfolio.py add BTC-USD --quantity 0.5 --cost 40000\n```\n\n### View Portfolio\n\n```bash\nuv run scripts/portfolio.py show\n```\n\n**Output:**\n```\nPortfolio: Retirement\n====================\n\nAssets:\n  AAPL     100 shares @ $150.00 = $15,000.00\n           Current: $185.00 = $18,500.00 (+23.3%)\n  \n  BTC-USD  0.5 @ $40,000 = $20,000.00\n           Current: $45,000 = $22,500.00 (+12.5%)\n\nTotal Cost:    $35,000.00\nCurrent Value: $41,000.00\nTotal P&L:     +$6,000.00 (+17.1%)\n```\n\n### Analyze Portfolio\n\n```bash\n# Full analysis of all holdings\nuv run scripts/analyze_stock.py --portfolio \"Retirement\"\n\n# With period returns\nuv run scripts/analyze_stock.py --portfolio \"Retirement\" --period monthly\n```\n\n### Rebalance Check\n\nThe analysis flags concentration warnings:\n```\n⚠️ CONCENTRATION WARNINGS:\n   • AAPL: 45.1% (>30% of portfolio)\n```\n\n---\n\n## Watchlist & Alerts\n\n### Add to Watchlist\n\n```bash\n# Basic watch\nuv run scripts/watchlist.py add NVDA\n\n# With price target\nuv run scripts/watchlist.py add NVDA --target 800\n\n# With stop loss\nuv run scripts/watchlist.py add NVDA --stop 600\n\n# Alert on signal change\nuv run scripts/watchlist.py add NVDA --alert-on signal\n\n# All options\nuv run scripts/watchlist.py add NVDA --target 800 --stop 600 --alert-on signal\n```\n\n### View Watchlist\n\n```bash\nuv run scripts/watchlist.py list\n```\n\n**Output:**\n```json\n{\n  \"success\": true,\n  \"items\": [\n    {\n      \"ticker\": \"NVDA\",\n      \"current_price\": 725.50,\n      \"price_at_add\": 700.00,\n      \"change_pct\": 3.64,\n      \"target_price\": 800.00,\n      \"to_target_pct\": 10.27,\n      \"stop_price\": 600.00,\n      \"to_stop_pct\": -17.30,\n      \"alert_on_signal\": true,\n      \"last_signal\": \"BUY\",\n      \"added_at\": \"2024-01-15\"\n    }\n  ],\n  \"count\": 1\n}\n```\n\n### Check Alerts\n\n```bash\n# Check for triggered alerts\nuv run scripts/watchlist.py check\n\n# Format for notification (Telegram)\nuv run scripts/watchlist.py check --notify\n```\n\n**Alert Example:**\n```\n📢 Stock Alerts\n\n🎯 NVDA hit target! $802.50 >= $800.00\n🛑 TSLA hit stop! $195.00 <= $200.00\n📊 AAPL signal changed: HOLD → BUY\n```\n\n### Remove from Watchlist\n\n```bash\nuv run scripts/watchlist.py remove NVDA\n```\n\n---\n\n## Performance Tips\n\n### Fast Mode\n\nSkip slow analyses for quick checks:\n\n```bash\n# Skip insider trading + breaking news\nuv run scripts/analyze_stock.py AAPL --fast\n```\n\n**Speed comparison:**\n| Mode | Time | What's Skipped |\n|------|------|----------------|\n| Default | 5-10s | Nothing |\n| `--no-insider` | 3-5s | SEC EDGAR |\n| `--fast` | 2-3s | Insider + News |\n\n### Batch Analysis\n\nAnalyze multiple stocks in one command:\n\n```bash\nuv run scripts/analyze_stock.py AAPL MSFT GOOGL AMZN META\n```\n\n### Caching\n\nMarket context is cached for 1 hour:\n- VIX, SPY, QQQ trends\n- Fear & Greed Index\n- VIX term structure\n- Breaking news\n\nSecond analysis of different stock reuses cached data.\n\n---\n\n## Interpreting Results\n\n### Recommendation Thresholds\n\n| Score | Recommendation |\n|-------|----------------|\n| > +0.33 | BUY |\n| -0.33 to +0.33 | HOLD |\n| < -0.33 | SELL |\n\n### Confidence Levels\n\n| Confidence | Meaning |\n|------------|---------|\n| > 80% | Strong conviction |\n| 60-80% | Moderate conviction |\n| 40-60% | Mixed signals |\n| < 40% | Low conviction |\n\n### Reading Caveats\n\n**Always read the caveats!** They often contain critical information:\n\n```\nCAVEATS:\n• Earnings in 5 days - high volatility expected    ← Timing risk\n• RSI 78 (overbought) + near 52w high              ← Technical risk\n• ⚠️ BREAKING NEWS: Fed emergency rate discussion  ← External risk\n• ⚠️ SECTOR RISK: China tensions affect tech       ← Geopolitical\n```\n\n### When to Ignore the Signal\n\n- **Pre-earnings:** Even BUY → wait until after\n- **Overbought:** Consider smaller position\n- **Risk-off:** Reduce overall exposure\n- **Low confidence:** Do more research\n\n### When to Trust the Signal\n\n- **High confidence + no major caveats**\n- **Multiple supporting points align**\n- **Sector is strong**\n- **Market regime is favorable**\n\n---\n\n## Common Workflows\n\n### Morning Check\n\n```bash\n# Check watchlist alerts\nuv run scripts/watchlist.py check --notify\n\n# Quick portfolio update\nuv run scripts/analyze_stock.py --portfolio \"Main\" --fast\n```\n\n### Research New Stock\n\n```bash\n# Full analysis\nuv run scripts/analyze_stock.py XYZ\n\n# If dividend stock\nuv run scripts/dividends.py XYZ\n\n# Add to watchlist for monitoring\nuv run scripts/watchlist.py add XYZ --alert-on signal\n```\n\n### Weekly Review\n\n```bash\n# Full portfolio analysis\nuv run scripts/analyze_stock.py --portfolio \"Main\" --period weekly\n\n# Check dividend holdings\nuv run scripts/dividends.py JNJ PG KO\n```\n\n---\n\n## Troubleshooting\n\n### \"Invalid ticker\"\n\n- Check spelling\n- For crypto, use `-USD` suffix\n- Non-US stocks may not work\n\n### \"Insufficient data\"\n\n- Stock might be too new\n- ETFs have limited data\n- OTC stocks often fail\n\n### Slow Performance\n\n- Use `--fast` for quick checks\n- Insider trading is slowest\n- Breaking news adds ~2s\n\n### Missing Data\n\n- Not all stocks have analyst coverage\n- Some metrics require options chains\n- Crypto has no sentiment data\n\nFile v6.1.0:TODO.md\n\n# Stock Analysis - Future Enhancements\n\n## Roadmap Overview\n\n### v4.0.0 (Current) - Geopolitical Risk & News Sentiment\n✅ 8 analysis dimensions with Fear/Greed, short interest, VIX structure, put/call ratio\n✅ Safe-haven indicators (GLD, TLT, UUP) with risk-off detection\n✅ Breaking news alerts via Google News RSS\n✅ Geopolitical risk mapping (Taiwan, China, Russia, Middle East, Banking)\n✅ Sector-specific crisis flagging with confidence penalties\n✅ 1h caching for shared indicators (Fear/Greed, VIX structure, breaking news)\n✅ Async parallel sentiment fetching (5 indicators with 10s timeouts)\n\n### v5.0.0 (Current) - Portfolio & Crypto\n✅ Portfolio management (create, add, remove, show assets)\n✅ Cryptocurrency support (Top 20 by market cap)\n✅ Portfolio analysis with --portfolio flag\n✅ Periodic returns (--period daily/weekly/monthly/quarterly/yearly)\n✅ Concentration warnings (>30% single asset)\n✅ Crypto fundamentals (market cap, category, BTC correlation)\n\n### v4.1.0 - Performance & Completeness\n✅ Full insider trading parsing via edgartools (Task #1)\n✅ Market context caching with 1h T\n\nArchive v6.0.0: 10 files, 50773 bytes\n\nFiles: App-Plan.md (14708b), README.md (4321b), scripts/analyze_stock.py (89930b), scripts/dividends.py (13130b), scripts/portfolio.py (18897b), scripts/test_stock_analysis.py (11958b), scripts/watchlist.py (11542b), SKILL.md (5674b), TODO.md (12848b), _meta.json (133b)\n\nArchive v5.0.0: 7 files, 41538 bytes\n\nFiles: App-Plan.md (14708b), README.md (3295b), scripts/analyze_stock.py (88970b), scripts/portfolio.py (18897b), SKILL.md (8381b), TODO.md (12848b), _meta.json (133b)\n\nArchive v4.0.0: 4 files, 25321 bytes\n\nFiles: scripts/analyze_stock.py (69140b), SKILL.md (6322b), TODO.md (12243b), _meta.json (133b)\n\nArchive v3.5.0: 4 files, 20870 bytes\n\nFiles: scripts/analyze_stock.py (55960b), SKILL.md (4867b), TODO.md (12243b), _meta.json (133b)\n\nArchive v3.0.0: 3 files, 15312 bytes\n\nFiles: scripts/analyze_stock.py (53567b), SKILL.md (4829b), _meta.json (133b)\n\nArchive v2.0.0: 3 files, 11767 bytes\n\nFiles: scripts/analyze_stock.py (39895b), SKILL.md (3674b), _meta.json (133b)\n\nArchive v1.0.1: 3 files, 7117 bytes\n\nFiles: scripts/analyze_stock.py (20374b), SKILL.md (2532b), _meta.json (133b)\n\nArchive v1.0.0: 3 files, 6902 bytes\n\nFiles: scripts/analyze_stock.py (20374b), SKILL.md (2080b), _meta.json (133b)","readmeExcerpt":"Skill: Stock Analysis Owner: udiedrichsen Summary: Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management, watchlists with alerts, dividend analysis, 8-dimension stock scoring, viral trend detection (Hot Scanner), and rumor/early signal detection. Use for stock analysis, portfolio tracking, earnings reactions, crypto monitoring, trending stocks, or finding rumors before they hit m","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# Basic analysis\nuv run {baseDir}/scripts/analyze_stock.py AAPL\n\n# Fast mode (skips insider trading & breaking news)\nuv run {baseDir}/scripts/analyze_stock.py AAPL --fast\n\n# Compare multiple\nuv run {baseDir}/scripts/analyze_stock.py AAPL MSFT GOOGL\n\n# Crypto\nuv run {baseDir}/scripts/analyze_stock.py BTC-USD ETH-USD"},{"language":"bash","snippet":"# Analyze dividends\nuv run {baseDir}/scripts/dividends.py JNJ\n\n# Compare dividend stocks\nuv run {baseDir}/scripts/dividends.py JNJ PG KO MCD --output json"},{"language":"bash","snippet":"# Add to watchlist\nuv run {baseDir}/scripts/watchlist.py add AAPL\n\n# With price target alert\nuv run {baseDir}/scripts/watchlist.py add AAPL --target 200\n\n# With stop loss alert\nuv run {baseDir}/scripts/watchlist.py add AAPL --stop 150\n\n# Alert on signal change (BUY→SELL)\nuv run {baseDir}/scripts/watchlist.py add AAPL --alert-on signal\n\n# View watchlist\nuv run {baseDir}/scripts/watchlist.py list\n\n# Check for triggered alerts\nuv run {baseDir}/scripts/watchlist.py check\nuv run {baseDir}/scripts/watchlist.py check --notify  # Telegram format\n\n# Remove from watchlist\nuv run {baseDir}/scripts/watchlist.py remove AAPL"},{"language":"bash","snippet":"# Create portfolio\nuv run {baseDir}/scripts/portfolio.py create \"Tech Portfolio\"\n\n# Add assets\nuv run {baseDir}/scripts/portfolio.py add AAPL --quantity 100 --cost 150\nuv run {baseDir}/scripts/portfolio.py add BTC-USD --quantity 0.5 --cost 40000\n\n# View portfolio\nuv run {baseDir}/scripts/portfolio.py show\n\n# Analyze with period returns\nuv run {baseDir}/scripts/analyze_stock.py --portfolio \"Tech Portfolio\" --period weekly"},{"language":"bash","snippet":"# Full scan - find what's trending NOW\npython3 {baseDir}/scripts/hot_scanner.py\n\n# Fast scan (skip social media)\npython3 {baseDir}/scripts/hot_scanner.py --no-social\n\n# JSON output for automation\npython3 {baseDir}/scripts/hot_scanner.py --json"},{"language":"bash","snippet":"# Find early signals, M&A rumors, insider activity\npython3 {baseDir}/scripts/rumor_scanner.py"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: stock-analysis\ndescription: Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management, watchlists with alerts, dividend analysis, 8-dimension stock scoring, viral trend detection (Hot Scanner), and rumor/early signal detection. Use for stock analysis, portfolio tracking, earnings reactions, crypto monitoring, trending stocks, or finding rumors before they hit mainstream.\nversion: 6.2.0\nhomepage: https://finance.yahoo.com\ncommands:\n  - /stock - Analyze a stock or crypto (e.g., /stock AAPL)\n  - /stock_compare - Compare multiple tickers\n  - /stock_dividend - Analyze dividend metrics\n  - /stock_watch - Add/remove from watchlist\n  - /stock_alerts - Check triggered alerts\n  - /stock_hot - Find trending stocks & crypto (Hot Scanner)\n  - /stock_rumors - Find early signals, M&A rumors, insider activity (Rumor Scanner)\n  - /portfolio - Show portfolio summary\n  - /portfolio_add - Add asset to portfolio\nmetadata: {\"clawdbot\":{\"emoji\":\"📈\",\"requires\":{\"bins\":[\"uv\"],\"env\":[]},\"install\":[{\"id\":\"uv-brew\",\"kind\":\"brew\",\"formula\":\"uv\",\"bins\":[\"uv\"],\"label\":\"Install uv (brew)\"}]}}\n---\n\n# Stock Analysis v6.1\n\nAnalyze US stocks and cryptocurrencies with 8-dimension analysis, portfolio management, watchlists, alerts, dividend analysis, and **viral trend detection**.\n\n## What's New in v6.2\n\n- 🔮 **Rumor Scanner** — Early signals before mainstream news\n  - M&A rumors and takeover bids\n  - Insider buying/selling activity\n  - Analyst upgrades/downgrades\n  - Twitter/X \"hearing that...\", \"sources say...\" detection\n- 🎯 **Impact Scoring** — Rumors ranked by potential market impact\n\n## What's in v6.1\n\n- 🔥 **Hot Scanner** — Find viral stocks & crypto across multiple sources\n- 🐦 **Twitter/X Integration** — Social sentiment via bird CLI\n- 📰 **Multi-Source Aggregation** — CoinGecko, Google News, Yahoo Finance\n- ⏰ **Cron Support** — Daily trend reports\n\n## What's in v6.0\n\n- 🆕 **Watchlist + Alerts** — Price targets, stop losses, signal changes\n- 🆕 **Dividend Analysis** — Yield, payout ratio, growth, safety score\n- 🆕 **Fast Mode** — `--fast` skips slow analyses (insider, news)\n- 🆕 **Improved Performance** — `--no-insider` for faster runs\n\n## Quick Commands\n\n### Stock Analysis\n```bash\n# Basic analysis\nuv run {baseDir}/scripts/analyze_stock.py AAPL\n\n# Fast mode (skips insider trading & breaking news)\nuv run {baseDir}/scripts/analyze_stock.py AAPL --fast\n\n# Compare multiple\nuv run {baseDir}/scripts/analyze_stock.py AAPL MSFT GOOGL\n\n# Crypto\nuv run {baseDir}/scripts/analyze_stock.py BTC-USD ETH-USD\n```\n\n### Dividend Analysis (NEW v6.0)\n```bash\n# Analyze dividends\nuv run {baseDir}/scripts/dividends.py JNJ\n\n# Compare dividend stocks\nuv run {baseDir}/scripts/dividends.py JNJ PG KO MCD --output json\n```\n\n**Dividend Metrics:**\n- Dividend Yield & Annual Payout\n- Payout Ratio (safe/moderate/high/unsustainable)\n- 5-Year Dividend Growth (CAGR)\n- Consecutive Years of Increases\n- Safety Score (0-100)\n- Income Rating (excellent/good/moderate/poor)\n"},{"path":"docs/README.md","content":"# Documentation\n\n## Stock Analysis v6.1\n\nThis folder contains detailed documentation for the Stock Analysis skill.\n\n## Contents\n\n| Document | Description |\n|----------|-------------|\n| [CONCEPT.md](./CONCEPT.md) | Philosophy, ideas, and design rationale |\n| [USAGE.md](./USAGE.md) | Practical usage guide with examples |\n| [ARCHITECTURE.md](./ARCHITECTURE.md) | Technical implementation details |\n| [HOT_SCANNER.md](./HOT_SCANNER.md) | 🔥 Viral trend detection (NEW) |\n\n## Quick Links\n\n### For Users\n\nStart with **[USAGE.md](./USAGE.md)** — it has practical examples for:\n- Basic stock analysis\n- Comparing stocks\n- Crypto analysis\n- Dividend investing\n- Portfolio management\n- Watchlist & alerts\n\n### For Understanding\n\nRead **[CONCEPT.md](./CONCEPT.md)** to understand:\n- Why 8 dimensions?\n- How scoring works\n- Contrarian signals\n- Risk detection philosophy\n- Limitations we acknowledge\n\n### For Developers\n\nCheck **[ARCHITECTURE.md](./ARCHITECTURE.md)** for:\n- System overview diagram\n- Data flow\n- Caching strategy\n- File structure\n- Performance optimization\n\n## Quick Start\n\n```bash\n# Analyze a stock\nuv run scripts/analyze_stock.py AAPL\n\n# Fast mode (2-3 seconds)\nuv run scripts/analyze_stock.py AAPL --fast\n\n# Dividend analysis\nuv run scripts/dividends.py JNJ\n\n# Watchlist\nuv run scripts/watchlist.py add AAPL --target 200\nuv run scripts/watchlist.py check\n```\n\n## Key Concepts\n\n### The 8 Dimensions\n\n1. **Earnings Surprise** (30%) — Did they beat expectations?\n2. **Fundamentals** (20%) — P/E, margins, growth, debt\n3. **Analyst Sentiment** (20%) — Professional consensus\n4. **Historical Patterns** (10%) — Past earnings reactions\n5. **Market Context** (10%) — VIX, SPY/QQQ trends\n6. **Sector Performance** (15%) — Relative strength\n7. **Momentum** (15%) — RSI, 52-week range\n8. **Sentiment** (10%) — Fear/Greed, shorts, insiders\n\n### Signal Thresholds\n\n| Score | Recommendation |\n|-------|----------------|\n| > +0.33 | **BUY** |\n| -0.33 to +0.33 | **HOLD** |\n| < -0.33 | **SELL** |\n\n### Risk Flags\n\n- ⚠️ Pre-earnings (< 14 days)\n- ⚠️ Post-spike (> 15% in 5 days)\n- ⚠️ Overbought (RSI > 70 + near 52w high)\n- ⚠️ Risk-off mode (GLD/TLT/UUP rising)\n- ⚠️ Geopolitical keywords\n- ⚠️ Breaking news alerts\n\n## Disclaimer\n\n⚠️ **NOT FINANCIAL ADVICE.** For informational purposes only. Always do your own research and consult a licensed financial advisor."},{"path":"README.md","content":"# 📈 Stock Analysis v6.1\n\n> AI-powered stock & crypto analysis with portfolio management, watchlists, dividend analysis, and **viral trend detection**.\n\n[![ClawHub Downloads](https://img.shields.io/badge/ClawHub-1500%2B%20downloads-blue)](https://clawhub.ai)\n[![OpenClaw Skill](https://img.shields.io/badge/OpenClaw-Skill-green)](https://openclaw.ai)\n\n## What's New in v6.1\n\n- 🔥 **Hot Scanner** — Find viral stocks & crypto across multiple sources\n- 🐦 **Twitter/X Integration** — Social sentiment via bird CLI\n- 📰 **Multi-Source Aggregation** — CoinGecko, Google News, Yahoo Finance\n- ⏰ **Cron Support** — Daily trend reports\n\n## What's New in v6.0\n\n- 🆕 **Watchlist + Alerts** — Price targets, stop losses, signal change notifications\n- 🆕 **Dividend Analysis** — Yield, payout ratio, growth rate, safety score\n- 🆕 **Fast Mode** — Skip slow analyses for quick checks\n- 🆕 **Improved Commands** — Better OpenClaw/Telegram integration\n- 🆕 **Test Suite** — Unit tests for core functionality\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **8-Dimension Analysis** | Earnings, fundamentals, analysts, momentum, sentiment, sector, market, history |\n| **Crypto Support** | Top 20 cryptos with market cap, BTC correlation, momentum |\n| **Portfolio Management** | Track holdings, P&L, concentration warnings |\n| **Watchlist + Alerts** | Price targets, stop losses, signal changes |\n| **Dividend Analysis** | Yield, payout, growth, safety score |\n| **Risk Detection** | Geopolitical, earnings timing, overbought, risk-off |\n| **Breaking News** | Crisis keyword scanning (last 24h) |\n\n## Quick Start\n\n### Analyze Stocks\n```bash\nuv run scripts/analyze_stock.py AAPL\nuv run scripts/analyze_stock.py AAPL MSFT GOOGL\nuv run scripts/analyze_stock.py AAPL --fast  # Skip slow analyses\n```\n\n### Analyze Crypto\n```bash\nuv run scripts/analyze_stock.py BTC-USD\nuv run scripts/analyze_stock.py ETH-USD SOL-USD\n```\n\n### Dividend Analysis\n```bash\nuv run scripts/dividends.py JNJ PG KO\n```\n\n### Watchlist\n```bash\nuv run scripts/watchlist.py add AAPL --target 200 --stop 150\nuv run scripts/watchlist.py list\nuv run scripts/watchlist.py check --notify\n```\n\n### Portfolio\n```bash\nuv run scripts/portfolio.py create \"My Portfolio\"\nuv run scripts/portfolio.py add AAPL --quantity 100 --cost 150\nuv run scripts/portfolio.py show\n```\n\n### 🔥 Hot Scanner (NEW)\n```bash\n# Full scan with all sources\npython3 scripts/hot_scanner.py\n\n# Fast scan (skip social media)\npython3 scripts/hot_scanner.py --no-social\n\n# JSON output for automation\npython3 scripts/hot_scanner.py --json\n```\n\n## Analysis Dimensions\n\n### Stocks (8 dimensions)\n1. **Earnings Surprise** (30%) — EPS beat/miss\n2. **Fundamentals** (20%) — P/E, margins, growth, debt\n3. **Analyst Sentiment** (20%) — Ratings, price targets\n4. **Historical Patterns** (10%) — Past earnings reactions\n5. **Market Context** (10%) — VIX, SPY/QQQ trends\n6. **Sector Performance** (15%) — Relative strength\n7. **Momentum** (15%) — RSI, 52-week range\n8. **Sentiment**"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn77fv9851hjcqe52zqx0bhhbx7z680h\",\n  \"slug\": \"stock-analysis\",\n  \"version\": \"6.2.0\",\n  \"publishedAt\": 1770041353575\n}"},{"path":"App-Plan.md","content":"# StockPulse - Commercial Product Roadmap\n\n## Vision\n\nTransform the stock-analysis skill into **StockPulse**, a commercial mobile app for retail investors with AI-powered stock and crypto analysis, portfolio tracking, and personalized alerts.\n\n## Technical Decisions\n\n- **Mobile:** Flutter (iOS + Android cross-platform)\n- **Backend:** Python FastAPI on AWS (ECS/Lambda)\n- **Database:** PostgreSQL (RDS) + Redis (ElastiCache)\n- **Auth:** AWS Cognito or Firebase Auth\n- **Monetization:** Freemium + Subscription ($9.99/mo or $79.99/yr)\n\n---\n\n## Architecture Overview\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                      MOBILE APP (Flutter)                        │\n│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │\n│  │Dashboard │ │Portfolio │ │ Analysis │ │ Alerts   │           │\n│  └──────────┘ └──────────┘ └──────────┘ └──────────┘           │\n└─────────────────────────────────────────────────────────────────┘\n                              │ HTTPS/REST\n                              ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                      API GATEWAY (AWS)                           │\n│                   Rate Limiting, Auth, Caching                   │\n└─────────────────────────────────────────────────────────────────┘\n                              │\n                              ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                   BACKEND (FastAPI on ECS)                       │\n│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │\n│  │ Auth Service │ │ Analysis API │ │ Portfolio API│            │\n│  └──────────────┘ └──────────────┘ └──────────────┘            │\n│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │\n│  │ Alerts Svc   │ │ Subscription │ │ User Service │            │\n│  └──────────────┘ └──────────────┘ └──────────────┘            │\n└─────────────────────────────────────────────────────────────────┘\n                              │\n        ┌─────────────────────┼─────────────────────┐\n        ▼                     ▼                     ▼\n┌──────────────┐     ┌──────────────┐     ┌──────────────┐\n│  PostgreSQL  │     │    Redis     │     │     S3       │\n│   (RDS)      │     │ (ElastiCache)│     │  (Reports)   │\n└──────────────┘     └──────────────┘     └──────────────┘\n\n                    BACKGROUND WORKERS (Lambda/ECS)\n┌─────────────────────────────────────────────────────────────────┐\n│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │\n│  │Price Updater │ │Alert Checker │ │Daily Reports │            │\n│  │  (5 min)     │ │  (1 min)     │ │  (Daily)     │            │\n│  └──────────────┘ └──────────────┘ └──────────────┘            │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Feature Tiers\n\n### Free Tier\n- 1 portfolio (max 10 assets)\n- Basic stock/crypto analysis\n- Daily market summary\n- Limited to 5 analyses/day\n- Ads displayed\n\n"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management, watchlists with alerts, dividend analysis, 8-dimension stock scoring, viral trend detection (Hot Scanner), and rumor/early signal detection. Use for stock analysis, portfolio tracking, earnings reactions, crypto monitoring, trending stocks, or finding rumors before they hit mainstream. Skill: Stock Analysis Owner: udiedrichsen Summary: Analyze stocks and cryptocurrencies using Yahoo Finance data. Supports portfolio management, watchlists with alerts, dividend analysis, 8-dimension stock scoring, viral trend detection (Hot Scanner), and rumor/early signal detection. Use for stock analysis, portfolio tracking, earnings reactions, crypto monitoring, trending stocks, or finding rumors before they hit m","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1549,"uniquenessScore":47,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-05-19T07:00:23.045Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-05-19T07:00:23.045Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T00:35:17.353Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}