From 7849f8fe1fcbae6ac07712afdf5e96614d79beb8 Mon Sep 17 00:00:00 2001
From: karitham <kar@karitham.dev>
Date: Wed, 21 Jan 2026 14:15:07 +0100
Subject: [PATCH] doc: README

---
 README.md | 68 +++++++++++++++++++++----------------------------------
 1 file changed, 26 insertions(+), 42 deletions(-)

diff --git a/README.md b/README.md
index e440b64..f988472 100644
--- a/README.md
+++ b/README.md
@@ -21,45 +21,23 @@ export LAZULI_PASSWORD="your-app-password"
 
 ### Commands
 
-#### Export
-
-Parse and merge Last.fm/Spotify exports, output as JSON:
-
-```sh
-lazuli export --lastfm=history.csv --spotify=streaming_history.json --output=merged.json
-```
-
-#### Import
-
-Import listening history to Bluesky with proper rate limiting:
-
-```sh
-lazuli import --lastfm=history.csv --spotify=streaming_history.json
-```
-
-Resume is automatic - if interrupted, re-running skips already-imported records:
-
-Import modes:
-
-- `lastfm` - Import only Last.fm data
-- `spotify` - Import only Spotify data
-- `combined` - Merge both sources (default)
-
-#### Sync
-
-Fetch existing records and show statistics:
-
-```sh
-lazuli sync
-```
-
-#### Dedupe
-
-Find and remove duplicate records from your Bluesky profile:
-
-```sh
-lazuli dedupe --dry-run  # Preview without deleting
-```
+| Command | Usage |
+| :--- | :--- |
+| `export` | Parse and merge Last.fm/Spotify exports into a JSON file |
+| `import` | Import new records to Bluesky (auto-skips existing) |
+| `sync` | Refresh the local cache with records from Bluesky |
+| `stats` | Show database status and daily rate limit consumption |
+| `failed` | List records that failed to import |
+| `retry` | Attempt to re-import failed records |
+| `dedupe` | Remove duplicate records from your Bluesky profile |
+| `debug` | Dump raw records from Bluesky for troubleshooting |
+
+### Advanced Options
+
+- **Rate Limiting**: Lazuli automatically respects Bluesky/ATProto rate limits (default 9,000 writes/day). Use `lazuli stats` to see your remaining quota.
+- **Automatic Resume**: The local cache tracks which records were successfully imported. If a process is interrupted, re-running the same command will skip already-published entries.
+- **Output Formats**: Most commands support `--output-format=json` for machine-readable output.
+- **Fresh Sync**: Use `--fresh` to bypass the local cache and fetch everything directly from the server.
 
 ## Environment Variables
 
@@ -88,11 +66,17 @@ Export your listening history from Last.fm. The CSV file should have columns:
 
 ### Spotify
 
-Download your extended streaming history from Spotify (Privacy settings). Lazuli accepts:
+Lazuli is designed to work with your **Extended Streaming History** from Spotify. You can request this from your [Spotify Privacy Settings](https://www.spotify.com/account/privacy/).
+
+The recommended way to use Spotify data is by passing the **ZIP archive** you receive from Spotify directly. Lazuli will automatically find and parse all streaming history files within it.
 
-- Single JSON files
+Lazuli accepts:
+- **ZIP archives** containing extended history (Recommended)
 - Directories containing `Streaming_History_Audio_*.json` files
-- ZIP archives of the above
+- Single `Streaming_History_Audio_*.json` files
+
+> [!IMPORTANT]
+> Make sure to request "Extended streaming history", as the standard "Account data" export does not contain your full listening history.
 
 ## Features
 
-- 
2.51.2