diff --git a/README.md b/README.md
index 472d55c..53b710c 100644
--- a/README.md
+++ b/README.md
@@ -5,105 +5,111 @@
-### Your trading journal. On your machine. Synced from your broker.
+### The open-source trading journal for Indian markets.
+
+Self-hosted. Broker-synced. Your tokens never leave your machine.
[](https://github.com/khata-dev/khata/actions/workflows/ci.yml)
[](LICENSE)
[](pyproject.toml)
-[](docs/ROADMAP.md)
+[](docs/ROADMAP.md)
[](CONTRIBUTING.md)
+[](docs/SECURITY.md)
-[Quick start](#quick-start) · [What you'll see](#what-youll-see) · [Why khata](#why-khata) · [Supported brokers](#supported-brokers) · [Roadmap](docs/ROADMAP.md) · [Contributing](CONTRIBUTING.md)
+[**Quick start**](#quick-start) · [**Features**](#features) · [**Supported brokers**](#supported-brokers) · [**Architecture**](#architecture) · [**Roadmap**](docs/ROADMAP.md) · [**Contributing**](CONTRIBUTING.md)
---
-**khata** (खाता — Hindi for *ledger*) is an open-source trading journal built for Indian markets. It syncs automatically from your broker, reconstructs round-trip trades from fills, and lets you attach screenshots, voice memos, and screen recordings to any trade.
+**khata** (खाता — Hindi for *ledger*) is a self-hosted trading journal built for Indian retail traders. It pulls executions directly from your broker, reconstructs round-trip trades with correct fees, and gives you a fast, keyboard-friendly UI to review your edge — without surrendering your broker tokens or P&L data to a foreign SaaS.
-Self-hosted. Your broker tokens never leave your machine. Zero telemetry.
+## Why khata exists
-```bash
-uv run khata sync --broker dhan --since-days 30
-→ authenticating with dhan…
-→ fetching executions since 2026-03-21…
- got 247 executions
- inserted 247 new rows
-→ rebuilding round-trip trades…
- ✓ trades=89 (open=3) across 14 contracts
-```
+Indian retail traders have had to pick one of three bad options:
-## Why khata
+- **Your broker's built-in console** — scoped to that broker, shallow journaling, no cross-broker view.
+- **International SaaS** (Tradezella, Tradervue, TradesViz, TWI Journal) — closed source, no Indian broker APIs, no Indian tax logic, and you upload your P&L to foreign infrastructure.
+- **Spreadsheets** — work until trade 200, then the FIFO math quietly breaks.
-Every other tool forces a tradeoff you shouldn't have to make:
+khata is the fourth option: the data and the code live on your machine, the broker integration is open for inspection, and the journal takes the behavioural loop — notes, tags, reflections — seriously enough to matter.
-| Tool | Auto-sync from Indian brokers | Open source | Self-hosted | Journal + attachments | Indian tax |
-|---|:-:|:-:|:-:|:-:|:-:|
-| Zerodha Console | Zerodha only | ✗ | ✗ | Shallow | ✓ |
-| Tradezella / Tradervue | ✗ (CSV only) | ✗ | ✗ | ✓ | ✗ |
-| TradesViz / TWI Journal | ✗ (CSV only) | ✗ | ✗ | ✓ | ✗ |
-| Spreadsheets | ✗ | — | ✓ | Manual | Manual |
+| | Auto-sync
Indian brokers | Self-hosted | Open source | Journal +
attachments | Indian tax |
+|---|:---:|:---:|:---:|:---:|:---:|
+| Zerodha Console | Zerodha only | — | — | Shallow | ✓ |
+| Tradezella · Tradervue | CSV only | — | — | ✓ | — |
+| TradesViz · TWI Journal | CSV only | — | — | ✓ | — |
+| Spreadsheets | — | ✓ | — | Manual | Manual |
| **khata** | **✓** | **✓** | **✓** | **✓** | **Planned (v1)** |
-The sensitive bit — your broker tokens and your P&L — stays on your machine. Read the code, self-host, and nobody can change their mind about your data.
+---
+
+## What's in the box today
-## Features
+### Command-line sync
-- **Auto-sync** from your broker. Historical backfill and intraday polls.
-- **Canonical trade schema.** One shape for every broker — portable, queryable, analytics-friendly.
-- **FIFO round-trip reconstruction** across executions: partial fills, scale-ins, scale-outs, overshoots, expiry settlements. [5/5 tests green.](tests/test_roundtrip.py)
-- **Attachments** — photos, voice memos, screen recordings, and PDFs on any trade or daily note.
-- **Analytics** *(v0.3)* — calendar heatmap, equity curve, win rate / profit factor / expectancy, R-multiple distribution, strategy and psychology breakdowns.
-- **Mobile PWA** *(v0.3)* — quick capture on your phone in under ten seconds.
-- **Tax engine** *(v1.0)* — F&O P&L, SEBI turnover, ITR-3 ready output.
-- **Boring stack.** FastAPI + SQLite + HTMX + Python. One Docker command to run.
+```bash
+$ uv run khata sync --broker dhan --since-days 30
+→ authenticating with dhan…
+→ fetching executions since 2026-03-21 …
+ got 103 executions
+ inserted 103 new rows
+→ rebuilding round-trip trades…
+ ✓ trades=18 (open=0) across 16 contracts
+```
-## What you'll see
+Historical backfill paginates through your broker's statement API. Intraday re-sync just re-runs the command. Everything is idempotent.
-Get the last month of trades and a quick summary:
+### Local web UI
```bash
-$ uv run khata stats
- khata
- ┏━━━━━━━━━━┳━━━━━━━━━━━━━━┓
- ┃ metric ┃ value ┃
- ┡━━━━━━━━━━╇━━━━━━━━━━━━━━┩
- │ trades │ 89 │
- │ wins │ 52 │
- │ losses │ 34 │
- │ open │ 3 │
- │ win rate │ 60.5% │
- │ net P&L │ ₹1,24,350.80 │
- └──────────┴──────────────┘
+$ uv run khata web
+→ starting khata web at http://127.0.0.1:8000
```
-Or drop to raw executions for debugging:
+- **Calendar** — month grid, P&L-coloured days, weekly-expiry markers, prev/next nav.
+- **Day view** — every trade with IST times, direction badges, fees, inline daily reflection.
+- **Trade view** — entry/exit, fills breakdown, tag chips (`setup` / `psych` / `mistake` / `custom`), freeform note editor.
+
+HTMX for interactivity. No build step, no SPA. Loads in under a second on a laptop.
+
+### Stats at a glance
```bash
-$ uv run khata dump-executions --limit 5
- broker symbol side qty price ts
- dhan NIFTY 24350 CE BUY 75 ₹75.30 2026-04-15T04:15:22Z
- dhan NIFTY 24350 CE SELL 75 ₹85.60 2026-04-15T04:32:08Z
- dhan BANKNIFTY 51000 PE BUY 30 ₹142.50 2026-04-15T05:03:11Z
- ...
+$ uv run khata stats
+ khata
+┏━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
+┃ metric ┃ value ┃
+┡━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
+│ trades │ 18 │
+│ wins │ 4 │
+│ losses │ 14 │
+│ open │ 0 │
+│ win rate │ 22.2% │
+│ net P&L │ -₹2,53,270.53 │
+└──────────┴───────────────┘
```
-## Supported brokers
+---
-| Broker | Status | Auth | Notes |
-|---|---|---|---|
-| **Dhan** | ✅ v0.0.1 | 24h JWT | REST + postback webhooks |
-| Zerodha (Kite) | 🔜 v0.4 | Daily login | Largest retail user base |
-| Fyers | 🔜 v0.4 | OAuth | REST + WebSocket |
-| Upstox | 🔜 v0.4 | OAuth | REST |
-| Angel One | 🔜 v0.5 | TOTP | |
-| Groww / ICICI Direct / HDFC Sec | Planned | No API | Contract-note import |
+## Features
-Want your broker added sooner? Read [`docs/ADAPTERS.md`](docs/ADAPTERS.md) — each adapter is ~200 lines of code + recorded fixtures. Open a PR or a [broker adapter request](../../issues/new?template=broker_adapter.yml).
+- **Auto-sync from your broker.** Historical backfill + intraday re-sync, paginated where the API requires it.
+- **Canonical trade schema.** One shape across every broker — portable, queryable, analytics-friendly.
+- **FIFO round-trip reconstruction.** Partial fills, scale-ins, scale-outs, direction overshoots, expiry settlements. All covered by unit tests.
+- **Accurate Indian fees.** STT, stamp duty, exchange transaction charges, SEBI turnover fee, IPFT, GST — recomputed from first principles when the broker hasn't settled yet.
+- **Web UI with inline journaling.** Calendar heatmap → day → trade → tags and notes, each saved on blur. No floating dialogs.
+- **Zero telemetry.** No outbound calls to any khata-owned server. There are none.
+- **Attachments** *(v0.2)* — images, voice memos, screen recordings, contract-note PDFs.
+- **Mobile PWA** *(v0.3)* — installable on your phone for sub-ten-second capture of photo, voice, and tags.
+- **Analytics** *(v0.3)* — equity curve, R-multiple histogram, strategy/psych breakdowns.
+- **Tax engine** *(v1.0)* — F&O P&L, SEBI turnover, ITR-3 schedule output.
+
+---
## Quick start
-### With uv (recommended)
+### With `uv` (recommended)
```bash
git clone https://github.com/khata-dev/khata
@@ -114,9 +120,11 @@ cp .env.example .env
uv sync
uv run khata init
uv run khata sync --broker dhan --since-days 30
-uv run khata stats
+uv run khata web
```
+Open http://127.0.0.1:8000.
+
### With Docker
```bash
@@ -127,51 +135,122 @@ docker compose exec khata khata sync --broker dhan
### Getting Dhan API credentials
1. Log in at [dhan.co](https://dhan.co) → **Trading APIs** → **Access DhanHQ APIs**.
-2. Generate an access token. It's a ~24-hour JWT — regenerate around 08:50 IST each market morning.
-3. Copy your `dhanClientId` and the token into `.env`.
+2. Generate an access token — it's a ~24-hour JWT, so regenerate each market morning around 08:50 IST.
+3. Paste your `dhanClientId` and the token into `.env`.
+
+---
+
+## Supported brokers
+
+| Broker | Status | Auth | Notes |
+|---|---|---|---|
+| **Dhan** | ✅ shipped | 24h JWT | REST + postback webhooks, paginated statement API |
+| Zerodha (Kite) | 🔜 v0.4 | Daily login | Largest retail user base in India |
+| Fyers | 🔜 v0.4 | OAuth | REST + WebSocket |
+| Upstox | 🔜 v0.4 | OAuth | REST |
+| Angel One | 🔜 v0.5 | TOTP | |
+| Groww · ICICI Direct · HDFC Sec | Planned | No retail API | Contract-note import |
+
+Want your broker sooner? Each adapter is ~200 lines of code plus recorded fixtures — see [`docs/ADAPTERS.md`](docs/ADAPTERS.md). Open a PR or a [broker adapter request](../../issues/new?template=broker_adapter.yml).
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────┐
+│ Broker APIs │ Dhan today — others next
+│ (auth, trades, │
+│ positions, orders) │
+└───────────┬─────────────┘
+ │
+ ┌────────▼────────┐
+ │ Adapter layer │ khata/adapters//
+ │ canonical out │ One file per broker, one protocol
+ └────────┬────────┘
+ │
+ ┌────────▼────────┐ ┌──────────────────┐
+ │ Round-trip │──────▶ SQLite DB │ Canonical schema.
+ │ FIFO engine │ │ (executions, │ Multi-user by design.
+ └─────────────────┘ │ trades, notes, │ Single-user default.
+ │ tags, …) │
+ └────┬─────────────-┘
+ │
+ ┌───────────▼───────────┐
+ │ CLI · Web UI │ Typer · FastAPI + HTMX
+ │ (both local-only) │ No telemetry. No cloud.
+ └───────────────────────┘
+```
+
+Stack choices are intentionally boring — Python 3.11+, FastAPI, SQLite, Jinja2, HTMX. You can understand the whole codebase in an afternoon and patch it in an hour.
+
+---
## Design principles
-1. **Self-hosted, always.** Your data stays on your machine. No telemetry.
-2. **Broker adapters are pluggable.** Canonical schema is the only contract.
-3. **Journaling is a behaviour, not a form.** Mobile capture takes under ten seconds.
-4. **Boring stack.** Modify it in one afternoon.
-5. **Apache 2.0, forever.** No open-core rug-pull.
+1. **Self-hosted, always.** Data stays on your machine. No exceptions.
+2. **Zero telemetry.** khata has no servers. We couldn't phone home if we wanted to.
+3. **Adapters are pluggable.** The canonical schema is the contract — drop in a new broker without touching analytics.
+4. **Journaling is a behaviour, not a form.** Mobile capture under ten seconds is the goal.
+5. **Boring stack.** A contributor should be able to modify any subsystem in one afternoon.
+6. **Apache 2.0, forever.** No open-core rug-pull. No relicensing.
+
+---
## FAQ
-**Is khata a trading platform?** No. khata is read-only — it never places orders. It's a journal.
+**Is khata a trading platform?**
+No. It's strictly read-only — it never places an order, modifies a position, or holds funds. It's a journal.
+
+**Do I need a VPS?**
+No. Runs on your laptop with zero dependencies beyond Python. If you want mobile access, Tailscale your laptop and use the PWA — no public tunnel required.
+
+**Is my broker token safe?**
+Read the code. The token lives in your `.env` file (gitignored), is sent only to your broker's API, and never leaves your machine. khata has no servers and makes no outbound calls to any third party.
-**Do I need a VPS to run it?** No. Runs fine on your laptop (SQLite, zero dependencies beyond Python). If you want mobile access, Tailscale + your laptop works.
+**What about tax reports?**
+On the roadmap for v1.0 — F&O P&L, SEBI turnover, ITR-3 schedule output. Not in the current release.
-**Can I trust it with my broker token?** Read the code. The token sits in your `.env` file, is sent only to your broker's API, and never leaves your machine. khata has no servers and makes no outbound calls to any third party.
+**How does this compare to Zerodha Console?**
+Console sets the bar for broker-integrated analytics, but it's Zerodha-only and the journaling is shallow. khata is Console-across-every-broker, plus a real journal, plus (eventually) Indian tax.
-**What about tax reports?** On the roadmap for v1.0 — F&O P&L, SEBI turnover, ITR-3 schedule output. Not in the current release.
+**Why not just a spreadsheet?**
+Works until trade 200. Then FIFO breaks, fees get rounded wrong, and P&L stops matching your broker statement. khata handles all of that for you, deterministically.
-**How does this compare to Zerodha Console?** Console is great, but it's Zerodha-only and the journaling is shallow. khata aims to be Console-across-every-broker, plus a real journal, plus Indian tax.
+**Can I use this for equity / futures / currency / commodities?**
+The schema supports all of them today. The fee recomputation logic is options-only for now; futures and equity land as needed — open an issue if you need them sooner.
-**Why not just a spreadsheet?** A spreadsheet works until it doesn't — by trade 200 you're copying data by hand, rebuilding round-trips manually, and P&L stops matching your broker statement. khata handles all of that.
+---
## Contributing
-See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup. The fastest path to a useful contribution is writing an adapter for your broker — [`docs/ADAPTERS.md`](docs/ADAPTERS.md).
+Three of the most welcome kinds of contribution:
+
+- **A new broker adapter** — canonical schema is the contract, each adapter is ~200 lines plus recorded fixtures. Read [`docs/ADAPTERS.md`](docs/ADAPTERS.md).
+- **A regression test from real data** — even one fixture covering an edge case we hadn't seen helps.
+- **Docs** — anything that makes the first ten minutes of setup faster.
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup, local test commands, and PR conventions.
## Security
-Broker tokens are sensitive. Keep them in `.env` (gitignored) or encrypted in the DB via `KHATA_SECRET`. See [`docs/SECURITY.md`](docs/SECURITY.md) for responsible-disclosure guidance.
+Broker tokens are the most sensitive thing khata touches. We keep them in `.env` (gitignored) or encrypted in the DB via `KHATA_SECRET`. Never commit your token. Never paste it in an issue. Report security issues privately as described in [`docs/SECURITY.md`](docs/SECURITY.md).
## Licence
-Apache 2.0. See [`LICENSE`](LICENSE).
+Apache 2.0 — see [`LICENSE`](LICENSE).
## Acknowledgments
-- **[Zerodha Console](https://console.zerodha.com/)** set the bar for what broker-integrated analytics can feel like.
-- **[Tradezella](https://www.tradezella.com/), [Tradervue](https://www.tradervue.com/), [TradesViz](https://www.tradesviz.com/), [TWI Journal](https://journal.tradewithinsight.com/)** are the journals Indian traders reach for when they need more than a spreadsheet — and each one is the reason this exists.
-- **[Dhan](https://dhanhq.co/docs/v2/)** for shipping a clean, documented REST API with a generous developer tier.
+- **[Zerodha Console](https://console.zerodha.com/)** set the bar for what broker-integrated analytics can feel like for Indian traders.
+- **[Tradezella](https://www.tradezella.com/), [Tradervue](https://www.tradervue.com/), [TradesViz](https://www.tradesviz.com/), [TWI Journal](https://journal.tradewithinsight.com/)** — the journals Indian traders reach for when spreadsheets stop scaling. Each is a reason khata exists.
+- **[Dhan](https://dhanhq.co/docs/v2/)** — for shipping a clean REST API with a generous developer tier.
+- **[HTMX](https://htmx.org/)** — for making server-rendered UI legible again.
---