diff --git a/README.md b/README.md
new file mode 100644
index 0000000..37cbd95
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+# Bullmania Money Line
+
+ATR-based trend line and flip signals for TradingView (Pine v5). The indicator draws a “Money Line” that trails price and flips direction when price crosses it. Green dots mark bullish flips (trend turns up), red dots mark bearish flips (trend turns down).
+
+This repo contains multiple versions; v4 is the latest and adds optional noise controls while preserving v1’s defaults.
+
+## Files
+- `Bullmania_Money_Line_v1.pine` — Baseline behavior (original). Two inputs: ATR Period, Multiplier.
+- `Bullmania_Money_Line_v2.pine` — Historical variant.
+- `Bullmania_Money_Line_v3.pine` — Historical variant.
+- `Bullmania_Money_Line_v4.pine` — v1 + optional noise reduction (confirmation bars, ATR buffer). Tagged `v4.0.0`.
+
+## How it works (all versions)
+- Money Line is derived from a mid-price `(high + low) / 2` and `ATR(atrPeriod)` scaled by `multiplier`.
+- The line trails in the direction of the current trend and flips when price closes across it.
+- Plots:
+  - Green line when trend is up, red line when trend is down.
+  - Green dot below bar when trend flips up; red dot above bar when trend flips down.
+  - Optional green/red fill between price and the line for quick context.
+
+## Inputs
+Common inputs (v1–v4):
+- ATR Period — ATR length in bars.
+- Multiplier — distance from source to the line in ATRs.
+
+Additional inputs (v4 only):
+- Flip confirmation bars — require N consecutive closes beyond the Money Line to flip (default 1 = same as v1).
+- Flip buffer (×ATR) — require the cross to exceed the line by X × ATR to flip (default 0.0 = same as v1).
+
+Defaults in v4 match v1, so you can upgrade without changing results and then enable the new knobs as needed.
+
+## Quick presets
+Use these as starting points and adjust per symbol/volatility. Values are for Heikin Ashi unless noted.
+
+- 30m Conservative (quiet):
+  - ATR Period: 8
+  - Multiplier: 3.5
+  - Flip confirmation bars: 2
+  - Flip buffer (×ATR): 0.30
+
+- 30m Balanced:
+  - ATR Period: 6
+  - Multiplier: 3.2
+  - Flip confirmation bars: 2
+  - Flip buffer (×ATR): 0.25
+
+### Tuning cheat sheet
+- Too noisy (too many reversals):
+  1) Increase confirmation bars (e.g., 2 → 3)
+  2) Raise buffer by +0.05 to +0.10
+  3) Widen Multiplier by +0.3 to +0.5 if needed
+- Too late / too few signals:
+  1) Lower buffer by -0.05
+  2) Reduce confirmation bars (3 → 2)
+  3) Tighten Multiplier by -0.3 to -0.5
+
+### Timeframe scaling tip
+If you want a similar time horizon across timeframes, pick a target window `T` in minutes (e.g., ~150 minutes). Then
+
+```
+ATR Period ≈ round(T / timeframe_minutes)
+```
+
+Keep Multiplier roughly stable and fine-tune by small increments; HA candles allow slightly tighter settings than regular candles.
+
+## How to use in TradingView
+1) Open TradingView → Pine Editor.
+2) New blank script.
+3) Copy the contents of the desired `.pine` file and paste.
+4) Save and “Add to chart”.
+5) Open Inputs to adjust parameters.
+
+## Changelog
+- v4.0.0 — Adds Flip confirmation bars and Flip buffer (×ATR). Defaults keep v1 behavior. Tag: `v4.0.0`.
+- v1 — Initial baseline.
+
+## Notes
+- v4 is designed to reduce whips without changing the core Money Line logic.
+- Optional future add-ons (can be toggled if requested):
+  - RSI centerline or ADX filter to gate flips in weak trends.
+  - Timeframe-adaptive ATR period (auto scales with chart TF).
+  - Pivot-anchored dots (plot flip dot at prior swing high/low).
+
+(If you want a LICENSE file added, tell me which license you prefer.)