From be4eb3a492b583bed0a5f829a005b68612a20fcb Mon Sep 17 00:00:00 2001
From: Claude-harness-bot <claude-harness-bot@users.noreply.github.com>
Date: Tue, 14 Apr 2026 16:19:09 -0400
Subject: [PATCH] docs: fix api-reference.md accuracy (V1-V4)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

V1: timeout default 30.0 → 10.0 (matches source)
V2: document user_agent constructor parameter
V3: document close() method
V4: remove hardcoded "agentwrit" from iss description —
    issuer is broker-configured, not a constant

Refs devonartis/agentwrit#31

Generated with Claude Code
---
 docs/api-reference.md   | 16 +++++++++++++---
 src/agentwrit/models.py |  2 +-
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/docs/api-reference.md b/docs/api-reference.md
index ee79930..b3095e4 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -20,7 +20,8 @@ AgentWritApp(
     client_id: str,
     client_secret: str,
     *,
-    timeout: float = 30.0,
+    timeout: float = 10.0,
+    user_agent: str | None = None,
 )
 ```
 
@@ -31,7 +32,8 @@ Creates an app instance. Authentication is lazy — the SDK does not contact the
 | `broker_url` | `str` | required | Base URL of the AgentWrit broker (e.g., `http://localhost:8080`) |
 | `client_id` | `str` | required | Application identifier from broker registration |
 | `client_secret` | `str` | required | Application secret. Never logged, printed, or included in any SDK output. |
-| `timeout` | `float` | `30.0` | HTTP request timeout in seconds |
+| `timeout` | `float` | `10.0` | HTTP request timeout in seconds |
+| `user_agent` | `str \| None` | `None` | Custom User-Agent header. If `None`, uses the SDK default. |
 
 ### create_agent()
 
@@ -89,6 +91,14 @@ Shortcut for `agentwrit.validate(app.broker_url, token)`.
 
 **Returns:** `ValidateResult`
 
+### close()
+
+```python
+app.close() -> None
+```
+
+Closes the underlying HTTP transport. Call this when you're done with the app to release connections.
+
 ---
 
 ## Agent
@@ -239,7 +249,7 @@ from agentwrit import AgentClaims
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `iss` | `str` | Issuer (always `"agentwrit"`) |
+| `iss` | `str` | Issuer — identifies the broker that issued the token |
 | `sub` | `str` | Subject — SPIFFE URI of the agent |
 | `aud` | `list[str]` | Audience (may be empty) |
 | `exp` | `int` | Expiration (Unix timestamp) |
diff --git a/src/agentwrit/models.py b/src/agentwrit/models.py
index 979acfb..c3b35d7 100644
--- a/src/agentwrit/models.py
+++ b/src/agentwrit/models.py
@@ -28,7 +28,7 @@ class AgentClaims:
     The `sub` field is a SPIFFE URI, ensuring the agent is a first-class
     identity in the trust domain.
     """
-    iss: str              # always "agentwrit"
+    iss: str              # broker-configured issuer
     sub: str              # SPIFFE URI
     aud: list[str]
     exp: int              # Unix timestamp