diff --git a/README.md b/README.md
new file mode 100644
index 0000000..add37a4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,46 @@
+# Order Query
+
+A terminal TUI tool for querying order details from Azure Table Storage by userId.
+
+## Features
+
+- Search orders by userId against Azure Table Storage
+- Browse results in a sortable table view
+- View full order details (product info, revenue, timestamps, custom data)
+- Persistent configuration via `~/.order-query/config.toml`
+
+## Install
+
+Requires Python >= 3.11.
+
+```bash
+uv pip install .
+```
+
+Or with pip:
+
+```bash
+pip install .
+```
+
+## Setup
+
+1. Run the tool — it will create a config file at `~/.order-query/config.toml`.
+2. Edit the config with your Azure Storage connection string:
+
+```toml
+connection_string = "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;TableEndpoint=https://..."
+table_name = "order"
+```
+
+3. Run again and enter a userId to query.
+
+## Usage
+
+```bash
+order-query
+```
+
+- Enter a userId to search
+- Arrow keys to browse results, Enter to view details
+- `q` to quit