Expand docs, loosen agent-readable, refresh lock

- Bump version to 0.1.2 and reword description to match the new
  health-aware-selection framing.
- Loosen agent-readable pin from ==0.1.0 to >=0.1.0 so consumers
  pick up patch upgrades automatically.
- README: add an "Designed for AI coding agents" callout pointing
  at `python -m agent_readable rotapool.Pool`, and add a Pitfalls
  section covering the work-outside-run anti-pattern, common
  don'ts, and the younger-sibling-only cancellation gotcha.
- pool.py embedded agent-readable docs: add a primary_backup
  strategy example so the docs surfaced to coding agents match
  the new feature.
- LICENSE: attribute to "zydo and rotapool contributors".
- uv.lock: refreshed against the new pyproject.toml.

Author: zydo

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 zydo
+Copyright (c) 2026 zydo and rotapool contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -2,6 +2,8 @@
 
 Async resource pool with inline health feedback, automatic cooldown, and retry — for API keys, proxies, GPU workers, or anything that can rate-limit you or go down.
 
+> **Designed for AI coding agents,** `rotapool` exposes machine-readable usage notes via [agent-readable](https://github.com/zydo/agent-readable). When generating code that uses `Pool`, tell your coding agent to run `pip install agent-readable` and then `python -m agent_readable rotapool.Pool` to learn about the operation contract, do/don't rules, anti-patterns, and failure modes.
+
 ## Core idea
 
 Most resource pools are passive — they hand out resources round-robin or at random, and rely on external health checks to detect and remove bad ones. `rotapool` closes that gap: every call through the pool is also a health probe. The pool learns from caller signals in real time and immediately adjusts which resources to offer — no external probers or manual updates needed.
@@ -385,6 +387,45 @@ def call_in_thread(resource, payload):
 
 A callable that returns a non-Awaitable (e.g. a plain `int`) raises `TypeError` at call time. The resource is marked healthy (your bug, not the resource's) and the error propagates to the caller.
 
+## Pitfalls
+
+### Anti-pattern: doing the real work outside `run()`
+
+The pool only sees what happens **inside** the operation. Returning a client or handle from `run()` and using it afterwards means every later failure is invisible — the attempt is already recorded as success and the cooldown counter was reset.
+
+```python
+# WRONG — the actual API call is outside the pool's view.
+client = await pool.run(lambda r: build_client(r.value))
+response = await client.get("/things")  # invisible to pool
+```
+
+```python
+# RIGHT — the call lives inside the operation, so 429s reach the pool.
+async def fetch(resource):
+    client = build_client(resource.value)
+    try:
+        return await client.get("/things")
+    except RateLimited as e:
+        raise CooldownResource(cooldown_seconds=e.retry_after)
+
+response = await pool.run(fetch)
+```
+
+Return only plain values (bytes, dict, dataclass) from operations. For N backend calls, make N `run()` invocations.
+
+### Don't
+
+- **Don't raise `CooldownResource` for business errors** (404, validation failures). The next resource will return the same error and burn the retry budget for nothing — these belong in normal exceptions or return values.
+- **Don't catch and swallow exceptions inside the operation.** The pool needs to see `CooldownResource` / `DisableResource` to update health; swallowing them turns rate limits into invisible successes.
+- **Don't mutate `Resource` fields from outside the pool.** `status`, `cooldown_until`, `last_acquired_at`, and `consecutive_cooldown` are framework-owned lifecycle state.
+- **Don't share one `Pool` across asyncio event loops.** The internal lock binds to the loop where it was first awaited; reusing the pool from a different loop is undefined behaviour.
+
+### Gotcha: cancellation only hits younger siblings
+
+When a resource raises `CooldownResource` or `DisableResource`, the framework cancels **younger** in-flight usages on that resource and retries them elsewhere. **Older** usages are left to run to completion — they may already have side effects upstream that you can't unwind.
+
+`asyncio.CancelledError` from this sibling cancellation is swallowed by the framework and the affected usages retry on a fresh resource; only **outer caller cancellation** propagates back to the caller.
+
 ## Testing
 
 ```bash

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "rotapool"
-version = "0.1.1"
-description = "Generic async resource pool with rotation, cooldown, and retry"
+version = "0.1.2"
+description = "Generic async resource pool with health-aware selection, cooldown, and retry"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
@@ -27,9 +27,7 @@ classifiers = [
     "Framework :: AsyncIO",
     "Typing :: Typed",
 ]
-dependencies = [
-    "agent-readable==0.1.0",
-]
+dependencies = ["agent-readable>=0.1.0"]
 
 [project.urls]
 Source = "https://github.com/zydo/rotapool"

src/rotapool/pool.py

@@ -506,6 +506,24 @@ async def call(resource):
 async def fetch(resource, url): ...
 ```
 
+### Strategy: primary_backup
+
+Default strategy is ``"round_robin"`` (fairness across resources). Pass
+``strategy="primary_backup"`` to instead exhaust earlier resources before
+touching later ones -- list/dict order becomes the priority ranking.
+
+```python
+# Use the paid key first; only fall back to free when the paid key is
+# rate-limited (cooling_down), revoked (disabled), or at max_in_flight.
+pool = Pool(
+    resources=[
+        Resource(resource_id="paid",  value="sk-paid-...",  max_in_flight=8),
+        Resource(resource_id="free",  value="sk-free-..."),
+    ],
+    strategy="primary_backup",
+)
+```
+
 ### Anti-pattern: doing the real work OUTSIDE ``run()``
 
 The pool only sees what happens INSIDE the operation. Returning a client /