diff --git a/README.md b/README.md
index f64bb6b..0fefee0 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,84 @@
 # asin-check
 
-To install dependencies:
+Amazon product analysis and lead finder agent. Reads product leads from a CSV/XLSX file, enriches them with Keepa pricing and sales data, caches results in Redis, and runs each product through a local LLM to get an FBA/FBM/SKIP verdict.
+
+## Requirements
+
+- [Bun](https://bun.com) runtime
+- Redis (local or Docker)
+- [LM Studio](https://lmstudio.ai) running locally with a model loaded
+- Keepa API key ([keepa.com](https://keepa.com))
+
+## Setup
 
 ```bash
 bun install
+cp .env.example .env
+# Edit .env and set your KEEPA_API_KEY
 ```
 
-To run:
+## Usage
 
 ```bash
-bun run index.ts
+bun run src/index.ts <input.csv|xlsx> [--out results.csv]
 ```
 
-This project was created using `bun init` in bun v1.3.10. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+Examples:
+```bash
+bun run src/index.ts leads.xlsx
+bun run src/index.ts leads.csv --out results.xlsx
+```
+
+## Input file format
+
+Accepts `.csv` or `.xlsx` files. Column names are matched case-insensitively. Required column:
+
+| Column | Aliases |
+|--------|---------|
+| ASIN | — |
+
+Optional but recommended:
+
+| Column | Aliases |
+|--------|---------|
+| Product Name | Name, Title |
+| Unit Cost | Cost, Price, Buy Cost |
+| Brand | — |
+| Category | — |
+| Amazon Rank | Amazon Rank, BSR, Sales Rank |
+| FBA NET | — |
+| Gross Profit $ | Gross Profit |
+| Gross Profit % | — |
+| MOQ | Min Order Qty |
+| MOQ Cost | — |
+| Total Qty Avail | Qty Available |
+| Link | URL, Source |
+
+## Pipeline
+
+1. **Read** — parse input file, validate ASINs
+2. **Cache check** — look up each ASIN in Redis (24h TTL by default)
+3. **Keepa fetch** — batch all uncached ASINs in a single API call (up to 100 per request)
+4. **Enrich** — combine Keepa data with spreadsheet data and SP-API fee estimates
+5. **LLM analysis** — send batches of 5 products to LM Studio for FBA/FBM/SKIP verdict
+6. **Output** — print results table to console, optionally write CSV/XLSX
+
+## Output columns
+
+ASIN, Name, Brand, Category, Unit Cost, Current Price, Avg Price 90d, Sales Rank, Rank Avg 90d, Sellers, Monthly Sold, Rank Drops 30d, Rank Drops 90d, FBA Net (sheet), Gross Profit $, Gross Profit %, MOQ, MOQ Cost, Qty Available, FBA Fee, FBM Fee, Referral %, Verdict, Confidence, Reasoning
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `KEEPA_API_KEY` | — | **Required.** Keepa API key |
+| `REDIS_URL` | `redis://localhost:6379` | Redis connection URL |
+| `LLM_URL` | `http://localhost:1234/v1` | LM Studio API base URL |
+| `LLM_MODEL` | `default` | Model name to pass to LM Studio |
+| `CACHE_TTL` | `86400` | Redis cache TTL in seconds |
+
+## Notes
+
+- **Keepa rate limiting**: The client reads `tokensLeft` and `refillRate` from each API response and waits automatically when tokens are exhausted. With a Pro subscription (1 token/min), all 100 ASINs in a batch cost 1 token.
+- **Redis is optional**: If Redis is unavailable the tool runs without caching — every run re-fetches from Keepa.
+- **SP-API**: Fee data is currently stubbed with estimates. The `src/sp-api.ts` module has TODO comments marking where real LWA OAuth + fee endpoint calls should go.