docs: tighten README, AGENTS, CLAUDE with production deploy instructions

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

1 files changed, 56 insertions, 62 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index ea7a26f..8ac44a0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,98 +1,92 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Guidance for Claude Code working in this repo.
 
 ## What This Is
 
-Prism v2 is a financial overview app: FastAPI backend (Python) + Next.js frontend (TypeScript). The backend pulls market data from yfinance with TTL caching and stores a watchlist in SQLite. The frontend renders a single Overview page with ticker search, price chart (Plotly), market bar, and watchlist.
+Prism v2: FastAPI backend (yfinance + SQLite watchlist) + Next.js frontend (Plotly chart, ticker search, market bar, watchlist). Single Overview page.
 
 ## Commands
 
-**Backend — run from repo root or `backend/`:**
 ```bash
-# Start API (ports 8001 to avoid conflicts)
+# Backend (port 8001 to avoid conflicts with other local services)
 backend/.venv/bin/uvicorn app.main:app --reload --host 127.0.0.1 --port 8001
-
-# Run all tests (pytest.ini sets pythonpath=backend)
-pytest
-
-# Run a single test file
-pytest backend/tests/test_api.py
-
-# Compile-check without running
+pytest                                       # all backend tests
+pytest backend/tests/test_api.py             # single file
 backend/.venv/bin/python -m py_compile backend/app/main.py backend/app/schemas.py
-```
 
-**Frontend — run from `frontend/`:**
-```bash
+# Frontend (port 3001)
 NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8001 npm run dev -- --hostname 127.0.0.1 --port 3001
-npm run lint      # ESLint
-npm run build     # Production build (validates TypeScript + Next.js)
+npm run lint
+npm run build
 ```
 
+`./scripts/stack.sh {start|stop|restart|status}` runs both locally; logs in `.run/logs/`.
+
 ## Architecture
 
-### Backend data flow
-`main.py` routes → `services/data_service.py` → yfinance (primary source).  
-`data_service.py` has three data-fetching helpers that `get_ticker_overview()` calls in priority order: `get_company_info()` (full yfinance `.info`), `get_fast_info()` (lightweight), then search + price history as last resort. `OverviewMeta.sources` records which source each field came from.
+**Backend:** `app/main.py` routes → `app/services/data_service.py` → yfinance. `get_ticker_overview()` tries `get_company_info()` (full `.info`), then `get_fast_info()`, then search + price history. `OverviewMeta.sources` records which source supplied each field. TTL caching in `HISTORY_CACHE`.
 
-### Key backend files
-- `app/main.py` — FastAPI routes, CORS config, lifespan (DB init)
-- `app/schemas.py` — all Pydantic response models
-- `app/services/data_service.py` — yfinance wrapper, TTL cache (`HISTORY_CACHE`), signal/stat computation
-- `app/db/watchlist.py` — SQLite CRUD; watchlist capped at 10 symbols, normalized to uppercase
+Key files:
+- `app/main.py` — routes, CORS, lifespan (DB init)
+- `app/schemas.py` — Pydantic models (keep in sync with `frontend/types/api.ts`)
+- `app/services/data_service.py` — yfinance wrapper, caching, signal/stat computation
+- `app/db/watchlist.py` — SQLite CRUD; uppercase, capped at 10 symbols
 
-### Frontend data flow
-`app/page.tsx` (Overview shell) → `lib/api.ts` (typed fetch client) → backend.  
-Selected ticker lives in the URL query param `?ticker=SYMBOL`. Types are shared in `frontend/types/api.ts` — keep these in sync with `backend/app/schemas.py`.
+**Frontend:** `app/page.tsx` → `lib/api.ts` (typed fetch) → backend. Selected ticker in URL `?ticker=SYMBOL`.
 
-### Testing approach
-Backend tests use `monkeypatch` to stub `data_service` functions — never make live yfinance calls in tests. Use a `tmp_path` fixture for any test that touches SQLite. There is no frontend test runner; use `npm run lint` and `npm run build` for frontend validation.
+**Tests:** Stub `data_service` with `monkeypatch` — never hit live yfinance. Use `tmp_path` for SQLite tests. No frontend test runner; use lint + build.
 
-## Design System (`design-system/`)
+## Production
 
-The repo includes a full personal-brand design system at `design-system/`. All frontend work must follow it — never invent colors, radii, or type choices.
+Topology: uvicorn on `127.0.0.1:8001`, `next start` on `127.0.0.1:3001`, nginx TLS reverse-proxy at `prism.tylerhoang.xyz` (`/api/` → backend, `/` → frontend). Service user `www-data`, code at `/var/www/prism-v2/`. Full deploy instructions in `README.md`.
 
-**Token entry point:** `design-system/colors_and_type.css` (also mirrored into `frontend/public/design-system/` for serving). Import it for all new components; it declares every CSS custom property: ink surfaces, fg tints, brass/champagne accent, oxford navy, burgundy, semantic gain/loss/caution/info colors, spacing scale, radii, shadows, and font stacks.
+**Redeploy:**
+```bash
+cd /var/www/prism-v2 && sudo -u www-data git pull origin master
+sudo -u www-data backend/.venv/bin/pip install -r backend/requirements.txt
+sudo -u www-data env HOME=/var/www/prism-v2/frontend NPM_CONFIG_CACHE=/var/www/prism-v2/frontend/.npm npm --prefix frontend ci
+sudo -u www-data env HOME=/var/www/prism-v2/frontend NPM_CONFIG_CACHE=/var/www/prism-v2/frontend/.npm npm --prefix frontend run build
+sudo systemctl restart prismv2-backend.service prismv2-frontend.service
+```
 
-**Typefaces:**
-- `--font-serif` — EB Garamond (variable). Display + body serif; italic at large sizes is the signature move.
-- `--font-sans` — IBM Plex Sans. UI labels, eyebrows, buttons, badges.
-- `--font-mono` — IBM Plex Mono. All prices, percentages, and tabular numerics (`font-variant-numeric: tabular-nums`).
+**Logs / status:**
+```bash
+sudo systemctl status prismv2-backend.service prismv2-frontend.service --no-pager
+sudo journalctl -u prismv2-backend.service -f
+```
 
-**Visual rules that must not be broken:**
-- Background is `#0B0E13` (ink-0), never pure black. Text is `#F2ECDC` (fg-0), never pure white.
-- Primary accent is champagne `#C2AA7A` — for links, focus rings, eyebrows, button fills. Never as a large background fill.
-- Semantic colors: gain `#4F8C5E`, loss `#B5494B`, caution `#C49545`, info `#4A78B5`.
-- Card radius is 6px; buttons are 2px. No radius above 6px except capsule chips (999px). No bubbly rounding.
-- Hairline `1px` borders only (`#232934`). No gradients except the chart area fill. No glass effects.
-- Transitions are 150ms ease. No bounces, springs, or scroll-jacking.
-- No emoji — ever. Use SVG icons from `design-system/assets/icons/` or unicode geometrics (`▲ ▼ ◈ ✦ ↗ ·`).
+**Rules:**
+- Browser code must NOT hardcode a localhost API base. `frontend/lib/api.ts` defaults to empty so production hits same-origin `/api/*` via nginx.
+- Frontend runs `next start` in production — never `next dev`.
+- nginx config and systemd units are in-tree at `nginx/` and `systemd/`; redeploying those requires sudo cp + reload.
 
-**Prism UI kit:** `design-system/ui_kits/prism/` is a forward-looking redesign showing the target component shapes: `<Sidebar>`, `<TopBar>`, `<TickerHeader>`, `<KPIStrip>`, `<ChartCard>`, `<QuoteTable>`, `<ValuationPanel>`, `<FilingsList>`, `<InsiderRow>`. Read `parts{1,2,3}.jsx` and `prism.css` before building new dashboard surfaces.
+## Design System (`design-system/`)
 
-**Skill:** `design-system/SKILL.md` is a Claude Code skill (`tyler-hoang-design`) — invoke it when doing design-heavy frontend work.
+All frontend work must follow it — never invent colors, radii, or type choices. Import `design-system/colors_and_type.css` (mirrored to `frontend/public/design-system/`).
 
-## Reference: Prism v1 (`../prism`)
+- Background `#0B0E13`, text `#F2ECDC`. Champagne `#C2AA7A` for accents (never a large fill).
+- Semantic: gain `#4F8C5E`, loss `#B5494B`, caution `#C49545`, info `#4A78B5`.
+- Card radius 6px, button 2px, chip 999px. Hairline `1px` borders (`#232934`). No gradients (except chart fill), no glass, no bounces.
+- Fonts: `--font-serif` EB Garamond, `--font-sans` IBM Plex Sans, `--font-mono` IBM Plex Mono (`tabular-nums` on all numerics).
+- No emoji. SVGs from `design-system/assets/icons/` or unicode geometrics (`▲ ▼ ◈ ✦ ↗ ·`).
 
-The old Streamlit-based app at `../prism` is the canonical reference for finance logic being ported into v2. Do not import from it at runtime, but read it when implementing new financial features.
+Read `design-system/ui_kits/prism/parts{1,2,3}.jsx` and `prism.css` before building new dashboard surfaces. Skill: `design-system/SKILL.md` (`tyler-hoang-design`).
 
-Key source files to consult:
+## Reference: Prism v1 (`../prism`)
 
-- **`services/data_service.py`** — yfinance wrappers for price history, financials (income/balance/cash flow), options chain, insider transactions, SEC filings, market indices, and analyst targets. Contains `compute_ttm_ratios()` which self-computes P/E, P/B, P/S, EV/EBITDA, margins, ROE/ROA/ROIC, leverage ratios, and dividend metrics from raw quarterly statements (avoiding FMP quota). Includes outlier safeguards (e.g. P/B and EV/Sales capped at 100).
-- **`services/valuation_service.py`** — DCF engine (`run_dcf()`) using Gordon Growth Model: projects FCF with median historical growth (capped ±50%, skips sign flips), computes terminal value, bridges enterprise value to equity per share via net debt/preferred equity/minority interest. Also has `run_ev_ebitda()`, `run_ev_revenue()`, `run_price_to_book()`.
-- **`services/fmp_service.py`** — FMP REST calls for peers, forward analyst estimates, historical ratios, and news. Falls back to yfinance when FMP is unavailable.
-- **`services/news_service.py`** — Finnhub sentiment wrapper.
-- **`components/overview.py`** — signal badge logic (6 signals), 52-week range bar, short interest rendering.
-- **`utils/formatters.py`** — number formatting helpers (market cap abbreviations, percent display, etc.).
+Read-only reference for finance logic — do not import at runtime.
 
-**Caching strategy in v1:** `@st.cache_data` with staggered TTLs — financials at 1 h, indices at 5 min, search at 60 s. Mirror these TTLs when adding new cached endpoints in v2's `data_service.py`.
+- `services/data_service.py` — yfinance wrappers; `compute_ttm_ratios()` self-computes P/E, P/B, P/S, EV/EBITDA, margins, ROE/ROA/ROIC, leverage, dividends from quarterly statements. Caps outliers (P/B and EV/Sales at 100).
+- `services/valuation_service.py` — `run_dcf()` (Gordon Growth, median historical FCF growth capped ±50%, skips sign flips, EV→equity bridge), plus `run_ev_ebitda`, `run_ev_revenue`, `run_price_to_book`.
+- `services/fmp_service.py`, `services/news_service.py` — FMP peers/estimates/news, Finnhub sentiment.
+- `components/overview.py`, `utils/formatters.py` — signal badges, 52w range, number formatting.
 
-**Data source hierarchy in v1:** yfinance primary → FMP fallback → Finnhub for news/sentiment. FMP free tier is 250 req/day; `FMP_API_KEY` and `FINNHUB_API_KEY` are set via `.env`.
+v1 cache TTLs to mirror: financials 1 h, indices 5 min, search 60 s. Data hierarchy: yfinance → FMP fallback → Finnhub for sentiment.
 
-## Environment Variables
+## Environment
 
-Copy `.env.example` → `.env`. The current feature set works without API keys; yfinance is the active data source.
+`.env.example` → `.env`. Current feature set works without keys.
 
-- `NEXT_PUBLIC_API_BASE_URL` — frontend points to backend (default `http://localhost:8000`)
-- `FMP_API_KEY`, `FINNHUB_API_KEY` — reserved for future enrichment endpoints (see v1 `fmp_service.py` / `news_service.py`)
+- `NEXT_PUBLIC_API_BASE_URL` — empty in production (same-origin via nginx); `http://127.0.0.1:8001` locally
+- `FMP_API_KEY`, `FINNHUB_API_KEY` — reserved for future enrichment