{"id":"49c1e343-dddd-4217-ae6c-cbee7d64dab8","entityType":"agent","slug":"clawhub-udiedrichsen-stock-analysis","name":"Stock Analysis","canonicalUrl":"https://www.xpersona.co/agent/clawhub-udiedrichsen-stock-analysis","canonicalPath":"/agent/clawhub-udiedrichsen-stock-analysis","generatedAt":"2026-10-09T00:09:28.532Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-05-31T06:21:41.781Z","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. 52.3K downloads reported by the source. Last updated 5/31/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-31T06:21:41.781Z","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-31T06:21:41.781Z","emptyReason":null},"stars":null,"forks":null,"downloads":52343,"packageName":null,"latestVersion":"6.2.0","tractionLabel":"52.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-05-31T06:21:41.781Z","emptyReason":null},"lastUpdatedAt":"2026-05-31T06:21:41.781Z","lastCrawledAt":"2026-05-31T06:21:41.781Z","lastIndexedAt":null,"nextCrawlAt":"2026-06-01T06:21:41.781Z","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":18,"zipByteSize":80513},{"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/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis/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-09T00:09:28.530Z"}},"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/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-udiedrichsen-stock-analysis/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-31T06:21:41.781Z","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: 18 files, 80513 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-card.md (2643b), 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[](https://clawhub.ai)\n[](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:skill-card.md\n\n## Description:
\nAnalyzes stocks and cryptocurrencies with Yahoo Finance data, portfolio and watchlist tracking, dividend metrics, stock scoring, trend detection, and rumor scanning.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[udiedrichsen](https://clawhub.ai/user/udiedrichsen)
\n\n### License/Terms of Use:
\n\n\n## Use Case:
\nExternal users and developers use this skill to run command-line stock, crypto, dividend, portfolio, watchlist, trend, and rumor analyses for informational market research.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Optional Twitter/X scanning can expose live AUTH_TOKEN and CT0 session credentials to an external CLI.
\nMitigation: Use finance-only commands or run the hot scanner with --no-social unless social-media data is required; do not provide AUTH_TOKEN or CT0 unless the credential exposure is acceptable.
\nRisk: The Twitter/X setup may require broad local permissions such as Terminal Full Disk Access.
\nMitigation: Avoid granting broad local permissions casually, and keep any .env file containing session credentials out of shared folders and repositories.
\nRisk: Market, short-interest, filing, news, and social signals may be delayed, cached, rate-limited, or keyword-based.
\nMitigation: Treat outputs as informational market research, verify important claims against primary sources, and do not use the skill as financial advice.
\n\n\n## Reference(s):
\n- [ClawHub Skill Page](https://clawhub.ai/udiedrichsen/stock-analysis)
\n- [Yahoo Finance](https://finance.yahoo.com)
\n- [Stock Analysis README](artifact/README.md)
\n- [Usage Guide](artifact/docs/USAGE.md)
\n- [Hot Scanner Documentation](artifact/docs/HOT_SCANNER.md)
\n- [Architecture Notes](artifact/docs/ARCHITECTURE.md)
\n\n\n## Skill Output:
\n**Output Type(s):** [Text, JSON, Shell commands, Configuration, Guidance]
\n**Output Format:** [Console text and optional JSON, with command examples and local configuration guidance]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [May write local portfolio, watchlist, and scanner cache JSON files under user or skill storage paths.]
\n\n## Skill Version(s):
\n6.2.0 (source: frontmatter and server release metadata)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\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[](https://clawhub.ai)\n[](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\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[](https://clawhub.ai)\n[](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-31T06:21:41.781Z","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-31T06:21:41.781Z","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-09T00:09:28.532Z","emptyReason":null},"items":[{"id":"959108e7-5f7c-45ac-bea0-9ab67f017226","entityType":"agent","canonicalPath":"/agent/langchain-x1pay-langchain","slug":"langchain-x1pay-langchain","name":"@x1pay/langchain","description":"LangChain/LangGraph tools for AI agent x402 payments on X1","url":"https://www.npmjs.com/package/@x1pay/langchain","homepage":null,"source":"GITHUB_OPENCLEW","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":70,"overallRank":65,"updatedAt":"2026-06-01T00:29:07.099Z","createdAt":"2026-05-23T06:52:58.553Z","downloads":null},{"id":"4f8f8f95-34f7-49a9-b516-391d1c355d6c","entityType":"agent","canonicalPath":"/agent/langchain-langchain-langgraph-swarm","slug":"langchain-langchain-langgraph-swarm","name":"@langchain/langgraph-swarm","description":"An implementation of a multi-agent swarm using LangGraph","url":"git+ssh://git@github.com/langchain-ai/langgraphjs.git","homepage":"https://github.com/langchain-ai/langgraphjs#readme","source":"GITHUB_OPENCLEW","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":70,"overallRank":65,"updatedAt":"2026-06-01T00:29:03.792Z","createdAt":"2026-05-23T06:52:55.396Z","downloads":null},{"id":"e36fd59b-38d7-4e73-aa20-c1431a8f7434","entityType":"agent","canonicalPath":"/agent/langchain-langchain-langgraph-supervisor","slug":"langchain-langchain-langgraph-supervisor","name":"@langchain/langgraph-supervisor","description":"LangGraph Multi-Agent Supervisor","url":"git+ssh://git@github.com/langchain-ai/langgraphjs.git","homepage":"https://github.com/langchain-ai/langgraphjs#readme","source":"GITHUB_OPENCLEW","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":70,"overallRank":65,"updatedAt":"2026-06-01T00:29:03.756Z","createdAt":"2026-05-23T06:52:55.353Z","downloads":null},{"id":"d1d0f93e-b722-4791-9bbf-2532470054c2","entityType":"agent","canonicalPath":"/agent/langchain-oceanbus-langchain","slug":"langchain-oceanbus-langchain","name":"oceanbus-langchain","description":"LangChain tools for OceanBus โ give your LangChain and CrewAI agents a global identity, encrypted messaging, and Yellow Pages service discovery with a single import.","url":"git+https://github.com/oceanbus/oceanbus.git","homepage":"https://github.com/oceanbus/oceanbus#readme","source":"GITHUB_OPENCLEW","protocols":["OPENCLAW"],"capabilities":["oceanbus","langchain","langchain-tools","agent-to-agent","ai-agent","communication","messaging","e2ee","structured-tool","yellow-pages","service-discovery","reputation","crewai"],"safetyScore":70,"overallRank":65,"updatedAt":"2026-06-01T00:29:02.595Z","createdAt":"2026-05-23T06:52:54.240Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}