From ba108988010a4b1eeb2784eca6ff212019d83de5 Mon Sep 17 00:00:00 2001
From: kingchenc <kingchencp@gmail.com>
Date: Fri, 22 May 2026 22:47:13 +0200
Subject: [PATCH] docs: add a cross-language examples index

The top-level examples/ directory held only python/, which made the
examples look Python-only even though Rust, Node and WASM all ship their
own. Add examples/README.md: a single index of every runnable example
across Rust, Python, Node and WASM, each with its run command, plus a note
on the bundled BTCUSDT datasets.

Point the README "Languages" table at the Node backtest example and link
the new index from both the table and the project-layout section.
---
 README.md          |  7 +++++--
 examples/README.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+), 2 deletions(-)
 create mode 100644 examples/README.md

diff --git a/README.md b/README.md
index 26db9868..ce79e2ff 100644
--- a/README.md
+++ b/README.md
@@ -118,10 +118,13 @@ inherit it automatically.
 | Binding           | Install                                       | Example |
 |-------------------|-----------------------------------------------|---------|
 | Python (PyO3)     | `pip install wickra`                          | `examples/python/backtest.py` |
-| Node.js (napi-rs) | `npm install wickra`                          | `bindings/node/examples/streaming.js` |
+| Node.js (napi-rs) | `npm install wickra`                          | `bindings/node/examples/backtest.js` |
 | Browser / WASM    | `npm install wickra-wasm`                     | `bindings/wasm/examples/index.html` |
 | Rust              | `cargo add wickra`                            | `crates/wickra/examples/backtest.rs` |
 
+Each binding ships several runnable examples (streaming, backtest, live feed);
+[`examples/README.md`](examples/README.md) is the full cross-language index.
+
 The wickra-core crate is `unsafe`-forbidden, so every binding inherits a
 memory-safe implementation.
 
@@ -188,7 +191,7 @@ wickra/
 │   ├── python/              PyO3 + maturin (publishes on PyPI)
 │   ├── node/                napi-rs (publishes on npm) + examples/
 │   └── wasm/                wasm-bindgen (browsers, bundlers, Node) + examples/
-├── examples/
+├── examples/                examples/README.md indexes every language
 │   └── python/              backtest, live trading, parallel assets, multi-tf
 └── .github/workflows/       CI and release pipelines
 ```
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 00000000..5f71f0d6
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,49 @@
+# Wickra examples
+
+Runnable examples for every Wickra binding. Rust and Node examples live next
+to the code they exercise so the language tooling (`cargo run --example`,
+`node`) can find them; the Python examples have no crate of their own and
+live here under [`python/`](python/).
+
+## Rust — `crates/*/examples/`
+
+| Example | What it does | Run |
+| --- | --- | --- |
+| `backtest.rs` | Compute a basket of indicators over an OHLCV CSV and print a summary. | `cargo run -p wickra --example backtest -- <ohlcv.csv>` |
+| `fetch_btcusdt.rs` | Download real BTCUSDT klines from the Binance REST API into `crates/wickra/examples/data/`. | `cargo run -p wickra --example fetch_btcusdt` |
+| `live_binance.rs` | Stream live Binance klines through an indicator over a resilient WebSocket. | `cargo run -p wickra-data --example live_binance --features live-binance` |
+
+## Python — `examples/python/`
+
+| Example | What it does | Run |
+| --- | --- | --- |
+| `backtest.py` | Basket of indicators over an OHLCV CSV. | `python -m examples.python.backtest <ohlcv.csv>` |
+| `live_trading.py` | Live Binance feed → RSI / MACD / Bollinger → signals. | `python -m examples.python.live_trading --symbol BTCUSDT --interval 1m` |
+| `multi_timeframe.py` | Resample a 1-minute CSV to coarser timeframes and compare. | `python -m examples.python.multi_timeframe <1m.csv>` |
+| `parallel_assets.py` | Process many symbols in parallel — the Rust extension releases the GIL during batch computation. | `python -m examples.python.parallel_assets --assets 200 --bars 5000` |
+
+`live_trading.py` additionally needs `pip install websockets`.
+
+## Node.js — `bindings/node/examples/`
+
+Build the native module first: `cd bindings/node && npm install && npx napi build --platform --release`.
+
+| Example | What it does | Run |
+| --- | --- | --- |
+| `streaming.js` | Feed a synthetic price series through several indicators tick by tick. | `node examples/streaming.js` |
+| `backtest.js` | Basket of indicators over an OHLCV CSV; defaults to the bundled BTCUSDT daily dataset. | `node examples/backtest.js [ohlcv.csv]` |
+| `live_trading.js` | Live Binance feed → RSI / MACD / Bollinger → signals. | `node examples/live_trading.js --symbol BTCUSDT --interval 1m` |
+
+## WebAssembly — `bindings/wasm/examples/`
+
+| Example | What it does | Run |
+| --- | --- | --- |
+| `index.html` | Browser demo: streams a price series through six indicators and draws a live `<canvas>` chart. | `wasm-pack build bindings/wasm --target web --release --features panic-hook`, then serve `bindings/wasm/` and open `examples/index.html` |
+
+## Example datasets
+
+`crates/wickra/examples/data/` holds seven real BTCUSDT OHLCV datasets, one
+per timeframe (1m, 5m, 15m, 1h, 12h, 1d, 1month), in the standard
+`timestamp,open,high,low,close,volume` layout. The Rust and Node backtest
+examples and the indicator benchmarks run against them. Regenerate them with
+the latest market history via `cargo run -p wickra --example fetch_btcusdt`.