quantwise 1.2.0 → 1.2.2

package/.claude/skills/market-top-detector/scripts/market_top_detector.py

@@ -0,0 +1,349 @@
+#!/usr/bin/env python3
+"""
+Market Top Detector - Main Orchestrator
+
+Integrates O'Neil (Distribution Days), Minervini (Leading Stock Deterioration),
+and Monty (Defensive Sector Rotation) approaches to detect market top probability.
+
+Usage:
+    # With FMP API (recommended):
+    python3 market_top_detector.py --api-key YOUR_KEY \\
+        --breadth-200dma 62.26 --breadth-50dma 55.0 \\
+        --put-call 0.67 --vix-term contango
+
+    # Using environment variable:
+    export FMP_API_KEY=YOUR_KEY
+    python3 market_top_detector.py --breadth-200dma 62.26
+
+    # Minimal (VIX from API, rest from CLI):
+    python3 market_top_detector.py --api-key YOUR_KEY \\
+        --breadth-200dma 62.26 --put-call 0.67
+
+Output:
+    - JSON: market_top_YYYY-MM-DD_HHMMSS.json
+    - Markdown: market_top_YYYY-MM-DD_HHMMSS.md
+"""
+
+import argparse
+import os
+import sys
+from datetime import datetime
+from typing import Dict, List, Optional
+
+# Add parent directory to path for imports
+sys.path.insert(0, os.path.dirname(__file__))
+
+from fmp_client import FMPClient
+from calculators.distribution_day_calculator import calculate_distribution_days
+from calculators.leading_stock_calculator import calculate_leading_stock_health, LEADING_ETFS
+from calculators.defensive_rotation_calculator import (
+    calculate_defensive_rotation, DEFENSIVE_ETFS, OFFENSIVE_ETFS
+)
+from calculators.breadth_calculator import calculate_breadth_divergence
+from calculators.index_technical_calculator import calculate_index_technical
+from calculators.sentiment_calculator import calculate_sentiment
+from scorer import calculate_composite_score, detect_follow_through_day
+from report_generator import generate_json_report, generate_markdown_report
+
+
+def parse_arguments():
+    parser = argparse.ArgumentParser(
+        description="Market Top Detector - O'Neil/Minervini/Monty Integration"
+    )
+
+    # API key
+    parser.add_argument(
+        "--api-key",
+        help="FMP API key (defaults to FMP_API_KEY environment variable)"
+    )
+
+    # WebSearch-sourced data (provided by Claude before script execution)
+    parser.add_argument(
+        "--breadth-200dma", type=float, default=None,
+        help="Percent of S&P 500 stocks above 200DMA (e.g., 62.26)"
+    )
+    parser.add_argument(
+        "--breadth-50dma", type=float, default=None,
+        help="Percent of S&P 500 stocks above 50DMA (e.g., 55.0)"
+    )
+    parser.add_argument(
+        "--put-call", type=float, default=None,
+        help="CBOE equity put/call ratio (e.g., 0.67)"
+    )
+    parser.add_argument(
+        "--vix-term", choices=["steep_contango", "contango", "flat", "backwardation"],
+        default=None,
+        help="VIX term structure state"
+    )
+    parser.add_argument(
+        "--margin-debt-yoy", type=float, default=None,
+        help="Margin debt year-over-year change percent (e.g., 36.0)"
+    )
+
+    # Additional context (not scored, but included in report)
+    parser.add_argument(
+        "--context", nargs="*", default=[],
+        help="Additional context items in 'key=value' format (e.g., 'Consumer Confidence=57.3')"
+    )
+
+    # Output
+    parser.add_argument(
+        "--output-dir", default=".",
+        help="Output directory for reports"
+    )
+
+    return parser.parse_args()
+
+
+def main():
+    args = parse_arguments()
+
+    print("=" * 70)
+    print("Market Top Detector")
+    print("O'Neil (Distribution) + Minervini (Leadership) + Monty (Rotation)")
+    print("=" * 70)
+    print()
+
+    # Initialize FMP client
+    try:
+        client = FMPClient(api_key=args.api_key)
+        print("FMP API client initialized")
+    except ValueError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # ========================================================================
+    # Step 1: Fetch shared data (indices, ETFs)
+    # ========================================================================
+    print()
+    print("Step 1: Fetching Market Data")
+    print("-" * 70)
+
+    # S&P 500 data
+    print("  Fetching S&P 500 data...", end=" ", flush=True)
+    sp500_quote_list = client.get_quote("^GSPC")
+    sp500_quote = sp500_quote_list[0] if sp500_quote_list else None
+    sp500_history_data = client.get_historical_prices("^GSPC", days=260)
+    sp500_history = sp500_history_data.get("historical", []) if sp500_history_data else []
+    if sp500_quote and sp500_history:
+        print(f"OK (${sp500_quote.get('price', 0):.2f}, {len(sp500_history)} days)")
+    else:
+        print("FAILED")
+        print("ERROR: Cannot proceed without S&P 500 data", file=sys.stderr)
+        sys.exit(1)
+
+    # NASDAQ/QQQ data
+    print("  Fetching NASDAQ (QQQ) data...", end=" ", flush=True)
+    qqq_quote_list = client.get_quote("QQQ")
+    qqq_quote = qqq_quote_list[0] if qqq_quote_list else None
+    qqq_history_data = client.get_historical_prices("QQQ", days=260)
+    qqq_history = qqq_history_data.get("historical", []) if qqq_history_data else []
+    if qqq_quote and qqq_history:
+        print(f"OK (${qqq_quote.get('price', 0):.2f}, {len(qqq_history)} days)")
+    else:
+        print("WARN - NASDAQ data unavailable, using S&P 500 only")
+
+    # VIX
+    print("  Fetching VIX...", end=" ", flush=True)
+    vix_quote_list = client.get_quote("^VIX")
+    vix_quote = vix_quote_list[0] if vix_quote_list else None
+    vix_level = vix_quote.get("price", None) if vix_quote else None
+    if vix_level:
+        print(f"OK ({vix_level:.2f})")
+    else:
+        print("WARN - VIX unavailable")
+
+    # Leading ETFs
+    print("  Fetching Leading ETFs...", end=" ", flush=True)
+    leading_quotes = client.get_batch_quotes(LEADING_ETFS)
+    leading_historical = client.get_batch_historical(LEADING_ETFS, days=60)
+    print(f"OK ({len(leading_quotes)} quotes, {len(leading_historical)} histories)")
+
+    # Sector ETFs
+    all_sector_etfs = list(set(DEFENSIVE_ETFS + OFFENSIVE_ETFS))
+    # Remove QQQ from sector fetching if already fetched
+    sector_etfs_to_fetch = [e for e in all_sector_etfs if e != "QQQ"]
+    print("  Fetching Sector ETFs...", end=" ", flush=True)
+    sector_historical = client.get_batch_historical(sector_etfs_to_fetch, days=30)
+    # Add QQQ history if available
+    if qqq_history:
+        sector_historical["QQQ"] = qqq_history[:30]
+    print(f"OK ({len(sector_historical)} ETFs)")
+
+    print()
+
+    # ========================================================================
+    # Step 2: Calculate Components
+    # ========================================================================
+    print("Step 2: Calculating Components")
+    print("-" * 70)
+
+    # Component 1: Distribution Days (25%)
+    print("  [1/6] Distribution Day Count...", end=" ", flush=True)
+    comp1 = calculate_distribution_days(sp500_history, qqq_history)
+    print(f"Score: {comp1['score']} ({comp1['signal']})")
+
+    # Component 2: Leading Stock Health (20%)
+    print("  [2/6] Leading Stock Health...", end=" ", flush=True)
+    comp2 = calculate_leading_stock_health(leading_quotes, leading_historical)
+    print(f"Score: {comp2['score']} ({comp2['signal']})")
+
+    # Component 3: Defensive Rotation (15%)
+    print("  [3/6] Defensive Sector Rotation...", end=" ", flush=True)
+    comp3 = calculate_defensive_rotation(sector_historical)
+    print(f"Score: {comp3['score']} ({comp3['signal']})")
+
+    # Component 4: Breadth Divergence (15%)
+    print("  [4/6] Market Breadth Divergence...", end=" ", flush=True)
+    # Calculate index distance from 52-week high
+    sp500_year_high = sp500_quote.get("yearHigh", 0)
+    sp500_price = sp500_quote.get("price", 0)
+    if sp500_year_high > 0:
+        index_dist = (sp500_price - sp500_year_high) / sp500_year_high * 100
+    else:
+        index_dist = 0
+
+    comp4 = calculate_breadth_divergence(
+        breadth_200dma=args.breadth_200dma,
+        breadth_50dma=args.breadth_50dma,
+        index_distance_from_high_pct=index_dist
+    )
+    print(f"Score: {comp4['score']} ({comp4['signal']})")
+
+    # Component 5: Index Technical (15%)
+    print("  [5/6] Index Technical Condition...", end=" ", flush=True)
+    comp5 = calculate_index_technical(
+        sp500_history, qqq_history,
+        sp500_quote=sp500_quote, nasdaq_quote=qqq_quote
+    )
+    print(f"Score: {comp5['score']} ({comp5['signal']})")
+
+    # Component 6: Sentiment (10%)
+    print("  [6/6] Sentiment & Speculation...", end=" ", flush=True)
+    comp6 = calculate_sentiment(
+        vix_level=vix_level,
+        put_call_ratio=args.put_call,
+        vix_term_structure=args.vix_term,
+        margin_debt_yoy_pct=args.margin_debt_yoy
+    )
+    print(f"Score: {comp6['score']} ({comp6['signal']})")
+
+    print()
+
+    # ========================================================================
+    # Step 3: Composite Score
+    # ========================================================================
+    print("Step 3: Calculating Composite Score")
+    print("-" * 70)
+
+    component_scores = {
+        "distribution_days": comp1["score"],
+        "leading_stocks": comp2["score"],
+        "defensive_rotation": comp3["score"],
+        "breadth_divergence": comp4["score"],
+        "index_technical": comp5["score"],
+        "sentiment": comp6["score"],
+    }
+
+    data_availability = {
+        "distribution_days": True,  # Always available (requires S&P data to run)
+        "leading_stocks": comp2.get("data_available", True),
+        "defensive_rotation": comp3.get("data_available", True),
+        "breadth_divergence": comp4.get("data_available", True),
+        "index_technical": comp5.get("data_available", True),
+        "sentiment": comp6.get("data_available", True),
+    }
+
+    composite = calculate_composite_score(component_scores, data_availability)
+
+    print(f"  Composite Score: {composite['composite_score']}/100")
+    print(f"  Risk Zone: {composite['zone']}")
+    print(f"  Risk Budget: {composite['risk_budget']}")
+    print(f"  Strongest Warning: {composite['strongest_warning']['label']} "
+          f"({composite['strongest_warning']['score']})")
+    print()
+
+    # ========================================================================
+    # Step 4: Follow-Through Day Check
+    # ========================================================================
+    ftd = detect_follow_through_day(sp500_history, composite['composite_score'])
+    if ftd.get("applicable"):
+        print("Step 4: Follow-Through Day Monitor")
+        print("-" * 70)
+        print(f"  {ftd['reason']}")
+        print()
+
+    # ========================================================================
+    # Step 5: Generate Reports
+    # ========================================================================
+    print("Step 5: Generating Reports")
+    print("-" * 70)
+
+    # Parse additional context
+    additional_context = {}
+    for item in args.context:
+        if "=" in item:
+            key, value = item.split("=", 1)
+            additional_context[key.strip()] = value.strip()
+
+    # Build full analysis
+    analysis = {
+        "metadata": {
+            "generated_at": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+            "data_mode": "FMP API + CLI inputs",
+            "api_calls": client.get_api_stats(),
+            "cli_inputs": {
+                "breadth_200dma": args.breadth_200dma,
+                "breadth_50dma": args.breadth_50dma,
+                "put_call_ratio": args.put_call,
+                "vix_term_structure": args.vix_term,
+                "margin_debt_yoy_pct": args.margin_debt_yoy,
+            },
+            "index_data": {
+                "sp500_price": sp500_price,
+                "sp500_year_high": sp500_year_high,
+                "sp500_distance_from_high_pct": round(index_dist, 2),
+                "qqq_price": qqq_quote.get("price", 0) if qqq_quote else None,
+                "vix_level": vix_level,
+            },
+        },
+        "composite": composite,
+        "components": {
+            "distribution_days": comp1,
+            "leading_stocks": comp2,
+            "defensive_rotation": comp3,
+            "breadth_divergence": comp4,
+            "index_technical": comp5,
+            "sentiment": comp6,
+        },
+        "follow_through_day": ftd,
+        "additional_context": additional_context,
+    }
+
+    timestamp = datetime.now().strftime("%Y-%m-%d_%H%M%S")
+    json_file = os.path.join(args.output_dir, f"market_top_{timestamp}.json")
+    md_file = os.path.join(args.output_dir, f"market_top_{timestamp}.md")
+
+    generate_json_report(analysis, json_file)
+    generate_markdown_report(analysis, md_file)
+
+    print()
+    print("=" * 70)
+    print("Market Top Detection Complete")
+    print("=" * 70)
+    print(f"  Composite Score: {composite['composite_score']}/100")
+    print(f"  Risk Zone: {composite['zone']}")
+    print(f"  Risk Budget: {composite['risk_budget']}")
+    print(f"  JSON Report: {json_file}")
+    print(f"  Markdown Report: {md_file}")
+    print()
+
+    stats = client.get_api_stats()
+    print(f"API Usage:")
+    print(f"  API calls made: {stats['api_calls_made']}")
+    print(f"  Cache entries: {stats['cache_entries']}")
+    print()
+
+
+if __name__ == "__main__":
+    main()

package/.claude/skills/market-top-detector/scripts/report_generator.py

@@ -0,0 +1,314 @@
+#!/usr/bin/env python3
+"""
+Market Top Detector - Report Generator
+
+Generates JSON and Markdown reports for market top detection analysis.
+"""
+
+import json
+from datetime import datetime
+from typing import Dict, List, Optional
+
+
+def generate_json_report(analysis: Dict, output_file: str):
+    """Save full analysis as JSON"""
+    with open(output_file, 'w') as f:
+        json.dump(analysis, f, indent=2, default=str)
+    print(f"JSON report saved to: {output_file}")
+
+
+def generate_markdown_report(analysis: Dict, output_file: str):
+    """Generate comprehensive Markdown report"""
+    lines = []
+    composite = analysis.get("composite", {})
+    components = analysis.get("components", {})
+    metadata = analysis.get("metadata", {})
+    ftd = analysis.get("follow_through_day", {})
+
+    score = composite.get("composite_score", 0)
+    zone = composite.get("zone", "Unknown")
+    risk_budget = composite.get("risk_budget", "N/A")
+
+    # Header
+    lines.append("# Market Top Detector Report")
+    lines.append("")
+    lines.append(f"**Generated:** {metadata.get('generated_at', 'N/A')}")
+    lines.append(f"**Data Mode:** {metadata.get('data_mode', 'N/A')}")
+    lines.append("")
+
+    # Overall Assessment Box
+    lines.append("---")
+    lines.append("")
+    lines.append("## Overall Assessment")
+    lines.append("")
+    zone_emoji = _zone_emoji(composite.get("zone_color", ""))
+    lines.append(f"| Metric | Value |")
+    lines.append(f"|--------|-------|")
+    lines.append(f"| **Composite Score** | **{score}/100** |")
+    lines.append(f"| **Risk Zone** | {zone_emoji} {zone} |")
+    lines.append(f"| **Risk Budget** | {risk_budget} |")
+    lines.append(f"| **Strongest Warning** | {composite.get('strongest_warning', {}).get('label', 'N/A')} "
+                 f"({composite.get('strongest_warning', {}).get('score', 0)}/100) |")
+    lines.append(f"| **Weakest Warning** | {composite.get('weakest_warning', {}).get('label', 'N/A')} "
+                 f"({composite.get('weakest_warning', {}).get('score', 0)}/100) |")
+    dq = composite.get("data_quality", {})
+    if dq:
+        lines.append(f"| **Data Quality** | {dq.get('label', 'N/A')} |")
+    lines.append("")
+
+    # Guidance
+    lines.append(f"> **Guidance:** {composite.get('guidance', '')}")
+    lines.append("")
+
+    # Component Scores Table
+    lines.append("---")
+    lines.append("")
+    lines.append("## Component Scores")
+    lines.append("")
+    lines.append("| # | Component | Weight | Score | Contribution | Signal |")
+    lines.append("|---|-----------|--------|-------|--------------|--------|")
+
+    component_order = [
+        "distribution_days", "leading_stocks", "defensive_rotation",
+        "breadth_divergence", "index_technical", "sentiment"
+    ]
+
+    for i, key in enumerate(component_order, 1):
+        comp = composite.get("component_scores", {}).get(key, {})
+        detail = components.get(key, {})
+        signal = detail.get("signal", "N/A")
+        score_val = comp.get("score", 0)
+        weight_pct = f"{comp.get('weight', 0)*100:.0f}%"
+        contribution = comp.get("weighted_contribution", 0)
+        bar = _score_bar(score_val)
+
+        lines.append(f"| {i} | **{comp.get('label', key)}** | {weight_pct} | "
+                     f"{bar} {score_val} | {contribution:.1f} | {signal} |")
+
+    lines.append("")
+
+    # Detailed Component Breakdowns
+    lines.append("---")
+    lines.append("")
+    lines.append("## Component Details")
+    lines.append("")
+
+    # Component 1: Distribution Days
+    dist = components.get("distribution_days", {})
+    lines.append("### 1. Distribution Day Count")
+    lines.append("")
+    if dist:
+        sp = dist.get("sp500", {})
+        nq = dist.get("nasdaq", {})
+        lines.append(f"- **Effective Count:** {dist.get('effective_count', 0)} "
+                     f"(Primary: {dist.get('primary_index', 'N/A')})")
+        lines.append(f"- **S&P 500:** {sp.get('distribution_days', 0)} distribution + "
+                     f"{sp.get('stalling_days', 0)} stalling")
+        lines.append(f"- **NASDAQ:** {nq.get('distribution_days', 0)} distribution + "
+                     f"{nq.get('stalling_days', 0)} stalling")
+        # Distribution day details
+        for idx_name, idx_data in [("S&P 500", sp), ("NASDAQ", nq)]:
+            details = idx_data.get("details", [])
+            if details:
+                lines.append(f"\n**{idx_name} Distribution Events:**")
+                for d in details[:5]:
+                    lines.append(f"  - {d.get('date', '?')}: {d.get('type', '?')} "
+                                 f"({d.get('pct_change', 0):+.2f}%, vol {d.get('volume_change', 0):+.1f}%)")
+    lines.append("")
+
+    # Component 2: Leading Stock Health
+    lead = components.get("leading_stocks", {})
+    lines.append("### 2. Leading Stock Health")
+    lines.append("")
+    if lead:
+        lines.append(f"- **ETFs Evaluated:** {lead.get('etfs_evaluated', 0)}")
+        lines.append(f"- **ETFs Deteriorating:** {lead.get('etfs_deteriorating', 0)} "
+                     f"({lead.get('deteriorating_pct', 0):.0f}%)")
+        lines.append(f"- **Amplification Applied:** {'Yes (60%+ deteriorating)' if lead.get('amplified') else 'No'}")
+        etf_details = lead.get("etf_details", {})
+        if etf_details:
+            lines.append("")
+            lines.append("| ETF | Score | Distance from High | Flags |")
+            lines.append("|-----|-------|--------------------|-------|")
+            for sym, det in sorted(etf_details.items(),
+                                   key=lambda x: x[1].get("deterioration_score", 0),
+                                   reverse=True):
+                flags = det.get("flags", [])
+                flags_joined = "; ".join(flags)
+                flags_str = flags_joined if len(flags_joined) <= 80 else flags_joined[:77] + "..."
+                lines.append(f"| {sym} | {det.get('deterioration_score', 0)} | "
+                             f"{det.get('distance_from_high_pct', 0):+.1f}% | {flags_str} |")
+    lines.append("")
+
+    # Component 3: Defensive Rotation
+    defr = components.get("defensive_rotation", {})
+    lines.append("### 3. Defensive Sector Rotation")
+    lines.append("")
+    if defr:
+        lines.append(f"- **Relative Performance (Def - Off):** "
+                     f"{defr.get('relative_performance', 0):+.2f}% "
+                     f"(over {defr.get('lookback_days', 20)} days)")
+        lines.append(f"- **Defensive Avg Return:** {defr.get('defensive_avg_return', 0):+.2f}%")
+        lines.append(f"- **Offensive Avg Return:** {defr.get('offensive_avg_return', 0):+.2f}%")
+
+        def_det = defr.get("defensive_details", {})
+        off_det = defr.get("offensive_details", {})
+        if def_det or off_det:
+            lines.append("")
+            lines.append("| Defensive ETF | Return | | Offensive ETF | Return |")
+            lines.append("|---------------|--------|-|---------------|--------|")
+            def_items = list(def_det.items())
+            off_items = list(off_det.items())
+            max_len = max(len(def_items), len(off_items))
+            for j in range(max_len):
+                d_sym = def_items[j][0] if j < len(def_items) else ""
+                d_ret = f"{def_items[j][1]:+.2f}%" if j < len(def_items) else ""
+                o_sym = off_items[j][0] if j < len(off_items) else ""
+                o_ret = f"{off_items[j][1]:+.2f}%" if j < len(off_items) else ""
+                lines.append(f"| {d_sym} | {d_ret} | | {o_sym} | {o_ret} |")
+    lines.append("")
+
+    # Component 4: Breadth
+    brd = components.get("breadth_divergence", {})
+    lines.append("### 4. Market Breadth Divergence")
+    lines.append("")
+    if brd:
+        lines.append(f"- **200DMA Breadth:** {brd.get('breadth_200dma', 'N/A')}%")
+        lines.append(f"- **50DMA Breadth:** {brd.get('breadth_50dma', 'N/A')}%")
+        lines.append(f"- **Index Near Highs:** {'Yes' if brd.get('index_near_highs') else 'No'} "
+                     f"({brd.get('index_distance_from_high_pct', 0):+.1f}% from 52wk high)")
+        lines.append(f"- **Divergence Detected:** {'YES' if brd.get('divergence_detected') else 'No'}")
+    lines.append("")
+
+    # Component 5: Index Technical
+    tech = components.get("index_technical", {})
+    lines.append("### 5. Index Technical Condition")
+    lines.append("")
+    if tech:
+        for idx_name in ["sp500", "nasdaq"]:
+            idx = tech.get(idx_name, {})
+            if idx:
+                label = "S&P 500" if idx_name == "sp500" else "NASDAQ"
+                lines.append(f"**{label}:** (Score: {idx.get('raw_score', 0)})")
+                for flag in idx.get("flags", []):
+                    lines.append(f"  - {flag}")
+                mas = idx.get("mas", {})
+                if mas:
+                    ma_str = ", ".join([f"{k}: ${v}" for k, v in mas.items()])
+                    lines.append(f"  - Moving Averages: {ma_str}")
+                lines.append("")
+    lines.append("")
+
+    # Component 6: Sentiment
+    sent = components.get("sentiment", {})
+    lines.append("### 6. Sentiment & Speculation")
+    lines.append("")
+    if sent:
+        details = sent.get("details", {})
+        pc = details.get("put_call_ratio", {})
+        vix = details.get("vix_level", {})
+        vts = details.get("vix_term_structure", {})
+        md = details.get("margin_debt", {})
+
+        lines.append(f"- **Put/Call Ratio:** {pc.get('value', 'N/A')} "
+                     f"(+{pc.get('points', 0)}pt) - {pc.get('interpretation', '')}")
+        lines.append(f"- **VIX Level:** {vix.get('value', 'N/A')} "
+                     f"({vix.get('points', 0):+d}pt) - {vix.get('interpretation', '')}")
+        lines.append(f"- **VIX Term Structure:** {vts.get('value', 'N/A')} "
+                     f"({vts.get('points', 0):+d}pt) - {vts.get('interpretation', '')}")
+        if md:
+            lines.append(f"- **Margin Debt YoY:** {md.get('yoy_pct', 'N/A')}% "
+                         f"- {md.get('interpretation', '')} *(context only, not scored)*")
+    lines.append("")
+
+    # Follow-Through Day Monitor
+    if ftd and ftd.get("applicable"):
+        lines.append("---")
+        lines.append("")
+        lines.append("## Follow-Through Day Monitor")
+        lines.append("")
+        if ftd.get("ftd_detected"):
+            lines.append(f"**FTD DETECTED** on {ftd.get('ftd_day', 'N/A')}")
+        else:
+            lines.append(f"- Rally Day Count: {ftd.get('rally_day_count', 0)}")
+        lines.append(f"- {ftd.get('reason', '')}")
+        lines.append("")
+
+    # Recommended Actions
+    lines.append("---")
+    lines.append("")
+    lines.append("## Recommended Actions")
+    lines.append("")
+    lines.append(f"**Risk Zone:** {zone}")
+    lines.append(f"**Risk Budget:** {risk_budget}")
+    lines.append("")
+    for action in composite.get("actions", []):
+        lines.append(f"- {action}")
+    lines.append("")
+
+    # Additional Context
+    extra = analysis.get("additional_context", {})
+    if extra:
+        lines.append("---")
+        lines.append("")
+        lines.append("## Additional Context (Not Scored)")
+        lines.append("")
+        for key, value in extra.items():
+            lines.append(f"- **{key}:** {value}")
+        lines.append("")
+
+    # Methodology
+    lines.append("---")
+    lines.append("")
+    lines.append("## Methodology")
+    lines.append("")
+    lines.append("This analysis integrates three complementary market top detection approaches:")
+    lines.append("")
+    lines.append("1. **O'Neil (Distribution Days):** Institutional selling pressure via volume-confirmed declines")
+    lines.append("2. **Minervini (Leading Stock Deterioration):** Growth leadership breakdown pattern")
+    lines.append("3. **Monty (Defensive Rotation):** Capital flow from offensive to defensive sectors")
+    lines.append("")
+    lines.append("Additional components (Breadth, Technical, Sentiment) provide confirmation signals.")
+    lines.append("Composite score is a weighted average of all 6 components (0-100 scale).")
+    lines.append("")
+    lines.append("For detailed methodology, see `references/market_top_methodology.md`.")
+    lines.append("")
+
+    # Disclaimer
+    lines.append("---")
+    lines.append("")
+    lines.append("**Disclaimer:** This analysis is for educational and informational purposes only. "
+                 "Not investment advice. Past patterns may not predict future outcomes. "
+                 "Conduct your own research and consult a financial advisor before making "
+                 "investment decisions.")
+    lines.append("")
+
+    with open(output_file, 'w') as f:
+        f.write('\n'.join(lines))
+
+    print(f"Markdown report saved to: {output_file}")
+
+
+def _zone_emoji(color: str) -> str:
+    mapping = {
+        "green": "🟢",
+        "yellow": "🟡",
+        "orange": "🟠",
+        "red": "🔴",
+        "critical": "⚫",
+    }
+    return mapping.get(color, "⚪")
+
+
+def _score_bar(score: int) -> str:
+    """Simple text bar for score visualization"""
+    if score >= 80:
+        return "████"
+    elif score >= 60:
+        return "███░"
+    elif score >= 40:
+        return "██░░"
+    elif score >= 20:
+        return "█░░░"
+    else:
+        return "░░░░"