added convenience docs

docs/TOKEN_STORAGE.md

@@ -0,0 +1,89 @@
+# Token Storage Configuration
+
+The application automatically detects and uses the appropriate token storage backend based on environment variables.
+
+## In-Memory Storage (Default)
+
+By default, tokens are stored in memory. This is suitable for:
+
+- Development
+- Single-instance deployments
+- Testing
+
+**No configuration needed** - this is the default behavior.
+
+## Redis Storage (Production Recommended)
+
+For production deployments with multiple instances, use Redis for shared token storage.
+
+### Setup
+
+1. **Install Redis dependency:**
+
+   ```bash
+   uv sync --extra redis
+   # or
+   pip install redis>=5.0.0
+   ```
+
+2. **Set environment variable:**
+
+   ```bash
+   export REDIS_URI=redis://localhost:6379/0
+   ```
+
+3. **Start the application:**
+   The app will automatically detect Redis and use it for token storage.
+
+### Docker Compose with Redis
+
+Uncomment the Redis service in `docker-compose.yml`:
+
+```yaml
+services:
+  app:
+    environment:
+      - REDIS_URI=redis://redis:6379/0
+
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redis-data:/data
+
+volumes:
+  redis-data:
+```
+
+Then run:
+
+```bash
+docker compose up
+```
+
+### Verification
+
+On startup, the application will print:
+
+- `✓ Connected to Redis at redis://...` - Using Redis
+- `ℹ Using in-memory token storage` - Using in-memory
+
+### Error Handling
+
+**Important**: If `REDIS_URI` is set, the application **requires** a successful Redis connection. It will **not** fall back to in-memory storage.
+
+If Redis connection fails, the application will exit with a clear error message:
+
+```
+RuntimeError: Failed to connect to Redis at redis://localhost:6379.
+Ensure Redis is running and accessible.
+```
+
+This prevents silent failures in production environments where Redis is expected.
+
+### Benefits of Redis
+
+- ✅ **Shared storage** across multiple app instances
+- ✅ **Automatic expiration** with TTL
+- ✅ **Persistent** (with proper Redis configuration)
+- ✅ **Scalable** for high-traffic applications
+- ✅ **Drop-in replacement** - no code changes needed