# CLAUDE.md — NSE Deep Research Engine

## What this project is
Paper-trading research engine for NSE equities. Two daily Telegram briefs: BTST (3:10 PM IST) and Swing (7 PM IST), backed by scanners + Claude-generated research notes, with full outcome tracking in PostgreSQL. **No real order placement anywhere in this codebase.**

## Authoritative documents — read before any work
1. `docs/blueprint.md` — architecture, locked tech stack, scope
2. `docs/requirements.md` — numbered acceptance criteria (cite these in commits)
3. `docs/design.md` — schema, module specs, prompts, cron plan
4. `docs/tasks.md` — the task list. Work strictly in order. ONE task per session.

## Session protocol
1. `git log --oneline -10` and read `claude-progress.txt` first.
2. Pick the FIRST unchecked task in docs/tasks.md.
3. Implement it fully, run its Verify step, and only then tick the checkbox.
4. Update `claude-progress.txt` (what done, what's next, blockers).
5. Commit: `feat(T##): <summary>` referencing requirement numbers.
6. If a session must end mid-task: commit as `WIP: T## — <state>`, do NOT tick the box.

## Hard rules
- Secrets ONLY via `.env` (never committed). `.env.example` lists all keys.
- Do not modify anything under `/root/fando/` or `/root/angel_tradebot/` — separate live systems.
- Database: `nse_research` only. Never touch other databases on this PostgreSQL instance.
- Prisma schema changes only via migrations.
- Recommendation rows are immutable after `publishedAt` is set.
- Telegram sends must go through the dedup helper (PublishedBrief) — never call the bot API directly from jobs.
- All jobs start with a trading-day check and exit silently on holidays/weekends.
- Timezone: all scheduling logic in IST (Asia/Kolkata). Confirm server TZ before writing cron entries.

## Environment
- AlmaLinux server, Node.js 20, PostgreSQL 15 local instance.
- Angel One SmartAPI credentials, Telegram bot token, Anthropic API key — ask the user to fill `.env` at T01; do not proceed to T03 without confirming Angel login works.
- NSE endpoints need browser-like headers + cookie bootstrap (see design.md §3.1).

## Testing conventions
- Unit tests: vitest, colocated `*.test.ts`, no network in unit tests (fixtures only).
- Every job runnable manually: `npm run job:<name> -- --date=YYYY-MM-DD` (dry-run support where design says so).