From 9afc351401868afede33ced4401340c65c56cb61 Mon Sep 17 00:00:00 2001
From: "Chih-Chung, Chang" <81843268+novis10813@users.noreply.github.com>
Date: Wed, 10 Jun 2026 13:32:03 +0800
Subject: [PATCH] docs: clarify factorium readme

---
 README.md | 37 +++++++++++++++++++++----------------
 1 file changed, 21 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index a06d6d2..7ffce35 100644
--- a/README.md
+++ b/README.md
@@ -4,25 +4,29 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![PyPI](https://img.shields.io/pypi/v/factorium.svg)](https://pypi.org/project/factorium/)
 
-Factorium is a **Polars-first factor research & backtesting toolkit**.
+Factorium is a **Polars-first factor research and backtesting toolkit** for quantitative finance.
 
-- Data pipeline: `BinanceDataLoader` + `AggBar` → multi-symbol OHLCV panel in one line.
-- Factor engine: `Factor` with rich TS/CS/math ops and expression parsing.
-- Analysis: `FactorAnalyzer` + `FactorAnalysisResult` for IC, quantile returns, and plots.
-- Backtest: `VectorizedBacktester` (exposed as `factorium.backtest.Backtester`) with Polars-vectorized PnL.
-- Research workflow: `ResearchSession` + `FactorReport` to tie everything into a notebook-friendly API.
+It is designed for researchers who want a notebook-friendly workflow for loading market data, building cross-sectional or time-series factors, evaluating factor quality, and running fast vectorized backtests.
 
-For a Chinese introduction, see `README_zh.md`.
+For a Chinese introduction, see [`README_zh.md`](README_zh.md).
 
----
+## What It Provides
+
+- Data pipeline: `BinanceDataLoader` + `AggBar` for multi-symbol OHLCV panels.
+- Factor engine: `Factor` with time-series, cross-sectional, math, and expression operations.
+- Analysis: `FactorAnalyzer` and `FactorAnalysisResult` for IC, quantile returns, and plots.
+- Backtesting: `VectorizedBacktester`, exposed as `factorium.backtest.Backtester`, with Polars-vectorized PnL.
+- Research workflow: `ResearchSession` and `FactorReport` for end-to-end notebook experiments.
 
 ## Installation
 
 ```bash
-# Recommended
 uv add factorium
+```
 
-# Or with pip
+Or with pip:
+
+```bash
 pip install factorium
 ```
 
@@ -34,9 +38,7 @@ cd factorium
 uv sync --dev
 ```
 
----
-
-## Quick example
+## Quick Example
 
 ```python
 from factorium import ResearchSession
@@ -49,6 +51,8 @@ momentum = (close.ts_delta(20) / close.ts_shift(20)).cs_rank()
 print(session.quick_report(momentum, periods=1))
 ```
 
+## Documentation
+
 More complete guides live under `docs/`:
 
 - `docs/getting-started/quickstart.md`
@@ -57,9 +61,10 @@ More complete guides live under `docs/`:
 - `docs/user-guide/analyzer.md`
 - `docs/user-guide/backtest.md`
 
----
+## Status
 
-## License
+Factorium is in active alpha development. APIs may still change, but the project already has packaged installation, tests, docs, and examples.
 
-MIT – see `LICENSE`.
+## License
 
+MIT. See `LICENSE`.