Merge pull request #16 from devonartis/fix/docs-review

Refs devonartis/agentwrit#31

Author: devonartis

docs/developer-guide.md

@@ -430,6 +430,63 @@ else:
 
 ---
 
+## Thread Safety
+
+`AgentWritApp` is **not thread-safe for mutations**. The app performs lazy one-time authentication on first use, and `app.close()` mutates internal state. Do not share the same `AgentWritApp` instance across threads or `asyncio` event loops without synchronization.
+
+The underlying `httpx.Client` **is thread-safe for concurrent requests** once the app is authenticated. This means multiple threads can safely call `app.create_agent()` or `agent.validate()` on the *same* authenticated instance, provided no thread calls `close()` while others are using it.
+
+### Recommended Patterns
+
+- **One app per thread** (safest):
+  ```python
+  import threading
+  from agentwrit import AgentWritApp
+
+  def worker():
+      app = AgentWritApp(...)
+      agent = app.create_agent(...)
+      # ... use agent ...
+      app.close()
+
+  threads = [threading.Thread(target=worker) for _ in range(4)]
+  for t in threads:
+      t.start()
+  ```
+
+- **Shared app with explicit lifecycle**:
+  Create one `AgentWritApp`, use it from many threads, and call `close()` only after all threads have finished.
+
+- **Always call `app.close()`** when you're done to avoid connection leaks.
+
+---
+
+## Async / Await Support
+
+The AgentWrit SDK is **synchronous only** in v0.3.0 (it uses `httpx`'s sync client). There is no native `async`/`await` support planned for this release.
+
+If you are building on an async framework such as FastAPI, Starlette, or Sanic, wrap SDK calls with `asyncio.to_thread()` so they do not block the event loop:
+
+```python
+import asyncio
+from agentwrit import AgentWritApp
+
+app = AgentWritApp(...)
+
+async def handle_request():
+    agent = await asyncio.to_thread(
+        app.create_agent,
+        orch_id="api-gateway",
+        task_id="request-123",
+        requested_scope=["read:data:customer-123"],
+        ttl=300,
+    )
+    # ... use agent ...
+    await asyncio.to_thread(agent.release)
+```
+
+---
+
 ## Next Steps
 
 | Guide | What You'll Learn |

docs/sample-apps/07-incident-response.md

@@ -102,7 +102,7 @@ def check_token(broker_url: str, token: str, label: str) -> bool:
 
 def main() -> None:
     broker_url = os.environ["AGENTWRIT_BROKER_URL"]
-    admin_secret = os.environ.get("AA_ADMIN_SECRET", "dev-secret")
+    admin_secret = os.environ.get("AGENTWRIT_ADMIN_SECRET", "dev-secret")
 
     app = AgentWritApp(
         broker_url=broker_url,
@@ -292,7 +292,7 @@ This app uses the **universal sample app** registered in the [README setup](READ
 This app revokes tokens using the admin API, which requires the **operator's admin secret**. This is the same secret used to start the broker:
 
 ```bash
-export AA_ADMIN_SECRET="dev-secret"  # match your broker's admin secret
+export AGENTWRIT_ADMIN_SECRET="dev-secret"  # match your broker's admin secret
 ```
 
 ### Additional Dependency
@@ -307,7 +307,7 @@ uv add httpx
 export AGENTWRIT_BROKER_URL="http://127.0.0.1:8080"
 export AGENTWRIT_CLIENT_ID="<from registration>"
 export AGENTWRIT_CLIENT_SECRET="<from registration>"
-export AA_ADMIN_SECRET="dev-secret"
+export AGENTWRIT_ADMIN_SECRET="dev-secret"
 
 uv run python incident_response.py
 ```

docs/sample-apps/README.md

@@ -72,11 +72,11 @@ docker compose up -d
 ### Step 2: Register the Universal Sample App
 
 ```bash
-export AA_ADMIN_SECRET="dev-secret"  # change if your broker uses a different secret
+export AGENTWRIT_ADMIN_SECRET="dev-secret"  # change if your broker uses a different secret
 
 ADMIN_TOKEN=$(curl -s -X POST http://127.0.0.1:8080/v1/admin/auth \
   -H "Content-Type: application/json" \
-  -d "{\"secret\": \"$AA_ADMIN_SECRET\"}" \
+  -d "{\"secret\": \"$AGENTWRIT_ADMIN_SECRET\"}" \
   | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
 
 curl -s -X POST http://127.0.0.1:8080/v1/admin/apps \

docs/testing-guide.md

@@ -43,13 +43,11 @@ Acceptance tests run against a live broker. They exercise every SDK operation en
 With env vars set from the Prerequisites step, run the suite directly with pytest:
 
 ```bash
-uv run pytest tests/integration/test_acceptance_1_8.py -v -s -m integration
+uv run pytest tests/integration/test_acceptance_stories.py -v -s -m integration
 ```
 
 The `-s` flag is important — it shows the banners in the console.
 
-> **Note on the file name:** `test_acceptance_1_8.py` contains all 15 stories. The name is historical — the suite grew past eight without a rename. A follow-up PR will rename it; until then, `grep "STORY 9"` finds it in the same file.
-
 You can also use the wrapper script, which starts the broker if needed:
 
 ```bash