Handle expired agreements and rewrite README

- Implement robust End User Agreement expiry detection and handling
- Add graceful error recovery for failed accounts
- Rewrite README.md to focus on user benefits
- Add documentation guidelines to AGENTS.md

README.md

@@ -2,84 +2,57 @@
 
 A robust command-line tool to synchronize bank transactions from GoCardless (formerly Nordigen) to Firefly III.
 
-## Architecture
+## ✨ Key Benefits
 
-This project is a Rust Workspace consisting of:
-- `banks2ff`: The main CLI application (Hexagonal Architecture).
-- `gocardless-client`: A hand-crafted, strongly-typed library for the GoCardless Bank Account Data API.
-- `firefly-client`: A hand-crafted, strongly-typed library for the Firefly III API.
+- **Automatic Transaction Sync**: Keep your Firefly III finances up-to-date with your bank accounts
+- **Multi-Currency Support**: Handles international transactions and foreign currencies correctly
+- **Smart Duplicate Detection**: Avoids double-counting transactions automatically
+- **Reliable Operation**: Continues working even when some accounts need attention
+- **Safe Preview Mode**: Test changes before applying them to your finances
+- **Rate Limit Aware**: Works within API limits to ensure consistent access
 
-## Features
+## 🚀 Quick Start
 
-- **Multi-Currency Support**: Correctly handles foreign currency transactions by extracting exchange rate data.
-- **Idempotency (Healer Mode)**:
-    - Detects duplicates using a windowed search (Date +/- 3 days, exact Amount).
-    - "Heals" historical transactions by updating them with the correct `external_id`.
-    - Skips transactions that already have a matching `external_id`.
-- **Clean Architecture**: Decoupled core logic makes it reliable and testable.
-- **Observability**: Structured logging via `tracing`.
-- **Dry Run**: Preview changes without writing to Firefly III.
-- **Rate Limit Protection**:
-    - Caches GoCardless account details to avoid unnecessary calls.
-    - Respects token expiry to minimize auth calls.
-    - Handles `429 Too Many Requests` gracefully by skipping affected accounts.
+### Prerequisites
+- Rust (latest stable)
+- GoCardless Bank Account Data account
+- Running Firefly III instance
 
-## Setup & Configuration
-
-1. **Prerequisites**:
-   - Rust (latest stable)
-   - An account with GoCardless Bank Account Data (get your `secret_id` and `secret_key`).
-   - A running Firefly III instance (get your Personal Access Token).
-
-2. **Environment Variables**:
-   Copy `env.example` to `.env` and fill in your details:
-
-   ```bash
-   cp env.example .env
-   ```
-
-   Required variables:
-   - `GOCARDLESS_ID`: Your GoCardless Secret ID.
-   - `GOCARDLESS_KEY`: Your GoCardless Secret Key.
-   - `FIREFLY_III_URL`: The base URL of your Firefly instance (e.g., `https://money.example.com`).
-   - `FIREFLY_III_API_KEY`: Your Personal Access Token.
-
-   Optional:
-   - `GOCARDLESS_URL`: Defaults to `https://bankaccountdata.gocardless.com`.
-   - `RUST_LOG`: Set log level (e.g., `info`, `debug`, `trace`).
-
-## Testing
-
-The project has a comprehensive test suite using `wiremock` for API clients and `mockall` for core logic.
-
-To run all tests:
+### Setup
+1. Copy environment template: `cp env.example .env`
+2. Fill in your credentials in `.env`:
+   - `GOCARDLESS_ID`: Your GoCardless Secret ID
+   - `GOCARDLESS_KEY`: Your GoCardless Secret Key
+   - `FIREFLY_III_URL`: Your Firefly instance URL
+   - `FIREFLY_III_API_KEY`: Your Personal Access Token
 
+### Usage
 ```bash
-cargo test --workspace
-```
-
-## Usage
-
-To run the synchronization:
-
-```bash
-# Run via cargo (defaults: Start = Last Firefly Date + 1, End = Yesterday)
+# Sync all accounts (automatic date range)
 cargo run -p banks2ff
 
-# Dry Run (Read-only)
+# Preview changes without saving
 cargo run -p banks2ff -- --dry-run
 
-# Custom Date Range
+# Sync specific date range
 cargo run -p banks2ff -- --start 2023-01-01 --end 2023-01-31
 ```
 
-## How it works
+## 📋 What It Does
 
-1. **Fetch**: Retrieves active accounts from GoCardless (filtered by those present in Firefly III to save requests).
-2. **Match**: Resolves the destination account in Firefly III by matching the IBAN.
-3. **Sync Window**: Determines the start date automatically by finding the latest transaction in Firefly for that account.
-4. **Process**: For each transaction:
-   - **Search**: Checks Firefly for an existing transaction (matching Amount and Date +/- 3 days).
-   - **Heal**: If found but missing an `external_id`, it updates the transaction.
-   - **Skip**: If found and matches `external_id`, it skips.
-   - **Create**: If not found, it creates a new transaction.
+Banks2FF automatically:
+1. Connects to your bank accounts via GoCardless
+2. Finds matching accounts in your Firefly III instance
+3. Downloads new transactions since your last sync
+4. Adds them to Firefly III (avoiding duplicates)
+5. Handles errors gracefully - keeps working even if some accounts have issues
+
+## 🔧 Troubleshooting
+
+- **Account not syncing?** Check that the IBAN matches between GoCardless and Firefly III
+- **Missing transactions?** The tool syncs from the last transaction date forward
+- **Rate limited?** The tool automatically handles API limits and retries appropriately
+
+---
+
+*For technical details, see [docs/architecture.md](docs/architecture.md)*