docs: add TEAM_GUIDE.md explaining the full v7.0 architecture and usage

TEAM_GUIDE.md

@@ -0,0 +1,189 @@
+# PrimoGreedy v7.0 — Team Guide
+
+## What Is PrimoGreedy?
+
+PrimoGreedy is an AI-powered micro-cap stock discovery agent. It systematically hunts for undervalued companies with market caps between **$10M and $300M**, priced under **$30/share**, across four markets: **USA, UK, Canada, and Australia**. It uses Benjamin Graham's value investing math combined with real-time data from multiple APIs, then delivers structured investment memos to the team via email.
+
+The system runs **automatically every day at 6:00 AM UTC** via a GitHub Actions cron job, and also has an **interactive web UI** (Chainlit) for on-demand analysis.
+
+---
+
+## How It Works — The Pipeline
+
+Every stock goes through a 4-step pipeline built with [LangGraph](https://langchain-ai.github.io/langgraph/):
+
+```
+SCOUT  ──>  GATEKEEPER  ──>  ANALYST  ──>  EMAIL
+```
+
+### Step 1: Scout (Discovery)
+
+The Scout uses a **two-pronged approach** to find candidates:
+
+1. **yFinance Screener** — Directly queries Yahoo Finance for stocks matching our market cap and price criteria. Uses a seed pool of known micro-cap tickers per region, updated over time.
+2. **Brave Search Trending** — Searches the web for currently-trending micro-cap discussions (Reddit, financial blogs, news). Extracts ticker symbols from the results and merges them into the screener pool.
+
+Both feeds are merged, then run through a **quantitative scoring system** (0–100 points) that ranks candidates on:
+
+| Criterion | Points |
+|-----------|--------|
+| Profitability (EPS > 0) | 20 |
+| Graham Number undervaluation | 25 |
+| Price-to-Book < 1.0 | 15 |
+| Free Cash Flow positive | 15 |
+| Low Debt (Net Debt/EBITDA) | 10 |
+| Current Ratio > 1.5 | 10 |
+| Cash runway (if unprofitable) | 5 |
+
+Only the **highest-scoring candidate** gets sent to the expensive LLM analyst step. Up to 4 backups are queued in case the top pick fails the Gatekeeper.
+
+### Step 2: Gatekeeper (Validation)
+
+Hard filters that reject stocks automatically:
+
+- **Price** > $30/share
+- **Market cap** outside $10M–$300M
+- **Financial health** fails sector-specific checks:
+  - *Banks*: Price/Book must be near or under 1.0
+  - *Tech/Healthcare*: Must have at least 6 months of cash runway (zombie filter)
+  - *Industrials/Default*: Net Debt/EBITDA must be under 3.5x
+
+If rejected, the pipeline loops back to Scout to try the next candidate. After 4 failed attempts per region, a failure report is sent instead.
+
+### Step 3: Analyst (AI Investment Memo)
+
+For stocks that pass the Gatekeeper, the AI writes a structured investment memo using two valuation frameworks:
+
+- **Graham Classic** — For profitable companies: `sqrt(22.5 × EPS × BookValue)` to calculate intrinsic value and margin of safety.
+- **Deep Value Asset Play** — For unprofitable companies (miners, biotech, turnarounds): evaluates Price vs Book Value as the safety net.
+
+The memo is structured in 4 sections:
+
+1. **Quantitative Base** — Price vs calculated intrinsic value, margin of safety math
+2. **Lynch Pitch** — What insiders are doing + the one catalyst that could move the stock
+3. **Munger Invert** — How you could lose money, what metric proves the bear case
+4. **Final Verdict** — STRONG BUY / BUY / WATCH / AVOID with a one-sentence bottom line
+
+**Data sources fed into the prompt:**
+- yFinance (price, EPS, book value, EBITDA, sector)
+- Finnhub (insider sentiment, company news, 52W high/low, beta, ROE)
+- Insider Feed (6-month insider buying/selling via MSPR score)
+- Brave Search (recent news and catalysts)
+
+### Step 4: Email
+
+The memo (or failure report) is sent to all team members via Resend. Each team member uses their own API key for reliability.
+
+---
+
+## How to Use the Web UI (Chainlit)
+
+The Chainlit app runs on Hugging Face Spaces. Commands:
+
+| Command | What It Does |
+|---------|-------------|
+| `AUTO` | Runs the full screener + Brave scan and returns a hot list |
+| `NVDA` | Analyses a single ticker through the full pipeline |
+| `NVDA, AMD, TSLA` | Analyses multiple tickers |
+| `@DeItaone` | Scouts the web for stocks mentioned by a social media personality |
+| `PORTFOLIO` | Shows the paper portfolio with live P&L for all past calls |
+| `BACKTEST` | Runs a Backtrader backtest on the paper portfolio vs Buy & Hold |
+| `What is the Graham Number?` | Chat mode — ask the AI broker anything |
+
+---
+
+## Architecture Overview
+
+```
+src/
+├── core/              # Shared modules used by everything
+│   ├── logger.py      # Structured logging
+│   ├── search.py      # Single Brave Search implementation
+│   ├── ticker_utils.py # Ticker extraction, suffix resolution, price normalization
+│   ├── memory.py      # Seen-tickers ledger (30-day TTL)
+│   └── state.py       # Shared LangGraph state schema
+│
+├── discovery/          # Stock discovery and ranking
+│   ├── screener.py    # yFinance micro-cap screener + Brave trending merge
+│   ├── scoring.py     # Quantitative 0-100 scoring system
+│   └── insider_feed.py # SEC Form 4 + Finnhub insider sentiment feeds
+│
+├── backtesting/        # Backtrader integration
+│   ├── engine.py      # Cerebro setup and run helpers
+│   ├── strategies.py  # PrimoAgent and Buy & Hold strategies
+│   ├── portfolio_bridge.py # Converts paper portfolio into backtest signals
+│   ├── data.py        # Data loading for backtests
+│   ├── plotting.py    # Chart generation
+│   └── reporting.py   # Markdown report generation
+│
+├── whale_hunter.py    # Daily cron pipeline (Scout→Gatekeeper→Analyst→Email)
+├── agent.py           # Interactive Chainlit pipeline (adds Chat, Chart, manual lookup)
+├── llm.py             # LLM connection with 6-model fallback chain
+├── finance_tools.py   # Graham Number, health checks, Finnhub tools
+├── portfolio_tracker.py # Paper portfolio ledger
+├── email_utils.py     # Thread-safe email dispatch via Resend
+├── scanner.py         # Trending stock scanner
+├── social_scout.py    # Social media handle scouting
+├── niche_hunter.py    # Standalone Brave-only global hunter
+└── global_router.py   # Market config (suffixes, gov filing links)
+
+app.py                 # Chainlit web UI entry point
+backtest.py            # Interactive backtesting CLI
+main.py                # Workflow-based analysis CLI
+```
+
+---
+
+## API Keys Required
+
+| Key | Service | Used For |
+|-----|---------|----------|
+| `OPENROUTER_API_KEY` | OpenRouter | LLM access (free tier) |
+| `BRAVE_API_KEY` | Brave Search | Web search for trending stocks and news |
+| `FINNHUB_API_KEY` | Finnhub | Insider sentiment, company news, fundamentals |
+| `RESEND_API_KEY_*` | Resend | Email delivery (one per team member) |
+| `EMAIL_*` | — | Team member email addresses |
+
+All keys are stored as GitHub Secrets for the cron job and in `.env` for local development.
+
+---
+
+## LLM Model Fallback
+
+The system uses free models via OpenRouter. If one model is rate-limited (429 error), it automatically tries the next:
+
+1. `nvidia/nemotron-3-nano-30b-a3b` (primary — fast, reliable)
+2. `stepfun/step-3.5-flash`
+3. `arcee-ai/trinity-large-preview`
+4. `google/gemma-3-27b-it`
+5. `meta-llama/llama-3.3-70b-instruct`
+6. `mistralai/mistral-small-3.1-24b-instruct`
+
+---
+
+## Daily Cron Schedule
+
+The GitHub Actions workflow (`.github/workflows/hunter.yml`) runs at **06:00 UTC daily**:
+
+1. Hunts all 4 regions: USA, UK, Canada, Australia
+2. Sends email reports for each region (success or failure)
+3. Commits the updated `seen_tickers.json` memory ledger to the repo
+4. 60-minute timeout
+
+To trigger manually: go to **Actions > Global Hunter Cron > Run workflow** on GitHub.
+
+---
+
+## Paper Portfolio
+
+Every BUY / STRONG BUY / WATCH call is recorded in `paper_portfolio.json` with the entry price and date. Use `PORTFOLIO` in the UI to see live P&L, or `BACKTEST` to compare against a Buy & Hold baseline using Backtrader.
+
+---
+
+## Key Concepts
+
+- **Graham Number**: `sqrt(22.5 × EPS × Book Value)` — the maximum price a defensive investor should pay. If the current price is below this, there's a margin of safety.
+- **Margin of Safety**: `(Graham Value - Price) / Graham Value` — the bigger this %, the more undervalued.
+- **MSPR (Monthly Share Purchase Ratio)**: Finnhub's insider sentiment metric. Positive = insiders buying, negative = insiders selling.
+- **Zombie Filter**: Rejects tech/healthcare companies burning cash with less than 6 months of runway.
+- **Seen Tickers Memory**: A JSON ledger that prevents re-analysing the same stock within 30 days.