[v2.0.2] Updates for README

Author: mykolademyanov

README.md

@@ -6,13 +6,29 @@ OnceOnly is a high-performance Python SDK that ensures **exactly-once execution*
 It prevents duplicate actions (payments, emails, tool calls) in unstable environments like
 AI agents, webhooks, retries, or background workers.
 
+
 Website: https://onceonly.tech/ai/  
 Documentation: https://onceonly.tech/docs/
 
 [![PyPI version](https://img.shields.io/pypi/v/onceonly-sdk.svg)](https://pypi.org/project/onceonly-sdk/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 ---
 
+## Why duplicates happen
+
+Duplicate actions are common in modern systems because:
+- AI agents retry or re-plan tool calls
+- Webhooks are delivered more than once
+- Workers crash after side-effects
+- Distributed systems replay events
+
+Without an idempotency layer, the same action may run multiple times.
+
+OnceOnly is designed to guard side-effects in non-deterministic AI agent loops,
+where the same tool call may be executed multiple times.
+
+---
+
 ## Features
 
 - Sync + Async client (httpx-based)
@@ -22,6 +38,17 @@ Documentation: https://onceonly.tech/docs/
 - Native AI API (long-running jobs, local side-effects)
 - Optional AI / LangChain integrations
 
+---
+
+## FAQ
+
+**Does this prevent duplicate payments or emails?**  
+Yes. OnceOnly guarantees exactly-once execution for side-effects.
+
+**Is this a retry library?**  
+No. Retries still happen — OnceOnly ensures the action itself runs only once.
+
+
 ---
 
 ## Installation

examples/README.md

@@ -5,7 +5,10 @@ This folder contains **small, runnable examples** demonstrating how to use the O
 Examples are organized into two groups:
 
 - `examples/general/` — core idempotency use cases (webhooks, workers, automations)
-- `examples/ai/` — AI agents, long-running jobs, and tool-calling integrations
+- `examples/ai/` — AI agents, long-running jobs, and tool-calling integrations. 
+
+These examples address common AI agent failure modes such as
+duplicate tool calls, retries after timeouts, and agent restarts.
 
 ---
 

onceonly/version.py

@@ -1 +1 @@
-__version__ = "2.0.1"
+__version__ = "2.0.2"

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "onceonly-sdk"
-version = "2.0.1"
+version = "2.0.2"
 description = "Python SDK for OnceOnly idempotency API"
 readme = "README.md"
 requires-python = ">=3.9"