# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

This is a Claude Code skill that generates comprehensive Taiwan stock analysis reports (Markdown + PDF). It depends on the sibling `stocks-query` skill (`../stocks-query/scripts/`) for all data-fetching scripts.

## Architecture

The skill has no code of its own — `SKILL.md` defines the orchestration workflow:

1. **Data collection**: Run 9+ Python scripts from `../stocks-query/scripts/` in parallel (Browserless-based scrapers for Yahoo Finance TW, plus direct TWSE API scripts)
2. **Report assembly**: Combine all script outputs into a structured Markdown file at `stocks/<代號>-report-YYYYMMDD.md`
3. **PDF conversion**: Use Python `markdown` + `weasyprint` to render Markdown → styled PDF with CJK font support
4. **Beginner version**: Generate a second "白話解讀版" (plain-language) report pair (`.md` + `.pdf`) with simplified explanations

## Key Dependencies

- **stocks-query skill** (`../stocks-query/`): All data scripts live there. See its `CLAUDE.md` for script details, environment variables (`BROWSERLESS_ENDPOINT`, `BROWSERLESS_TOKEN`), and API patterns.
- **Python packages**: `markdown`, `weasyprint` (for PDF generation)
- **CJK fonts**: PDF rendering requires "PingFang TC", "Heiti TC", or "Noto Sans CJK TC" installed on the system

## ETF vs. Individual Stock Logic

- ETFs (symbol starts with `00`): run `yahoo-etf-holdings.py`, skip `twse-monthly-revenue.py` and `twse-pe-pbr.py`
- Individual stocks: run `twse-monthly-revenue.py` and `twse-pe-pbr.py`, skip ETF holdings script

## Output

All reports go to `stocks/` directory:
- `stocks/<代號>-report-YYYYMMDD.md` — professional report
- `stocks/<代號>-report-YYYYMMDD.pdf` — professional PDF
- `stocks/<代號>-report-YYYYMMDD-beginner.md` — plain-language report
- `stocks/<代號>-report-YYYYMMDD-beginner.pdf` — plain-language PDF

## Language

All output, reports, and user-facing text must be in Traditional Chinese (Taiwan). Dates use `YYYY-MM-DD`, monetary values use thousands separators.