Merge pull request #8 from devonartis/fix/docs-review-v2

docs: fix F2-F13 findings for public release

Author: devonartis

.DS_Store

@@ -34,6 +34,8 @@ htmlcov/
 # Local AI tooling artifacts
 .playwright-mcp/
 .claude/settings.local.json
+.claude/scheduled_tasks.lock
+.DS_Store
 
 # Local archive (historical artifacts, not for repo)
 archive/

.claude/scheduled_tasks.lock

@@ -1,37 +1,38 @@
 # Changelog
 
-## v0.1.0 (2026-03-07)
+## v0.3.0 — Initial AgentWrit Public Release (2026-04-14)
 
-Initial release of the AgentWrit Python SDK.
+First public release of the AgentWrit Python SDK. Complete rewrite from the internal v0.1.0/v0.2.0 codebase.
 
-### Features
+### Core API
 
-- **AgentWritApp** -- main entry point with app authentication on init
-- **get_token()** -- full 8-step credential flow (app auth, launch token, Ed25519 challenge-response, caching)
-- **delegate()** -- scope-attenuated delegation to another registered agent (C7 Delegation Chain)
-- **revoke_token()** -- self-revocation for credential cleanup (C4 Expiration & Revocation)
-- **validate_token()** -- online token validation against the broker (C3 Zero-Trust)
-- **Token caching** -- by (agent_name, scope) key, proactive renewal at 80% TTL, thread-safe
-- **Retry with backoff** -- exponential backoff on 5xx/connection errors, Retry-After on 429
-- **Error hierarchy** -- AgentWritError, AuthenticationError, ScopeCeilingError, RateLimitError, BrokerUnavailableError, TokenExpiredError
-- **Type safety** -- mypy strict mode, no Any in source, TypedDict for all broker responses
-- **Security** -- ephemeral Ed25519 keys (never on disk), client_secret never in output, TLS verified by default, thread-safe app token state
+- **AgentWritApp** — main entry point; authenticates with the broker on first use (lazy auth)
+- **create_agent()** — registers an agent with Ed25519 challenge-response, returns an `Agent` object
+- **Agent** — lifecycle management: `renew()`, `release()`, `delegate()`
+- **validate()** — module-level online token validation against the broker
+- **scope_is_subset()** — module-level scope comparison utility
 
-### Testing
+### Models
+
+- `AgentClaims`, `ValidateResult`, `RegisterResult`, `HealthStatus`, `DelegatedToken`, `ProblemDetail` — typed dataclasses for all broker responses
+
+### Error Handling
 
-- 122 unit tests (no broker required)
-- 16 integration tests (live broker)
-- 7 live acceptance test scripts (SDK-S1 through SDK-S8)
-- Security review: all HIGH/MEDIUM findings resolved
+- `AgentWritError` base exception with RFC 7807 `ProblemDetail` support
+- Typed hierarchy: `AuthenticationError`, `AuthorizationError`, `RateLimitError`, `ProblemResponseError`, `TransportError`
 
-### Demo
+### Transport
+
+- `httpx`-based HTTP transport with automatic error dispatch
+- User-Agent: `agentwrit-python/0.3.0`
+
+### Testing
 
-- Interactive demo app (FastAPI + HTMX) with pattern/NIST annotations
-- 6 scenarios: Read Data, Write, Scope Violation, Delegation, Full Lifecycle, Blast Radius
+- 99 unit tests (no broker required)
+- 15 acceptance stories against live broker
+- Integration test suite with session-scoped fixtures
 
-### Documentation
+### Demos
 
-- README with full API, security properties, and pattern component mapping
-- API reference (docs/api-reference.md)
-- Getting started guide (docs/getting-started.md)
-- Pattern component annotations in all module docstrings
+- MedAssist AI (FastAPI + HTMX) — multi-agent medical encounter pipeline
+- Support Tickets (Flask + HTMX + SSE) — triage/knowledge/response agent pipeline

.gitignore

@@ -1,12 +1,5 @@
 # AgentWrit Python SDK
 
-## Rules
-
-**At session start, ALWAYS read these files before doing anything else:**
-- `~/proj/devflow/agentwrit-python/MEMORY.md` — current state, standing rules, known issues
-- `~/proj/devflow/agentwrit-python/FLOW.md` — decision log + **welcome note on first visit** (delete after reading)
-- Use `devflow-client` skill for all development work
-
 ## Rules — Non-Negotiable
 
 ### Strict Type Safety
@@ -35,8 +28,5 @@ uv run pytest tests/unit/              # unit tests
 
 ## Defaults
 
-- **Read `~/proj/devflow/agentwrit-python/MEMORY.md` first** every session — it has current state and lessons.
-- **Read `~/proj/devflow/agentwrit-python/FLOW.md`** for decision history and what's next.
-- **Use `devflow-client`** skill for all development work.
-- **API source of truth:** [https://github.com/devonartis/agentwrit/blob/main/docs/api.md](https://github.com/devonartis/agentwrit/blob/main/docs/api.md) — always verify SDK calls against it.
+- **API source of truth:** [AgentWrit broker API docs](https://github.com/devonartis/agentwrit/blob/main/docs/api.md) — always verify SDK calls against it.
 - **Live broker for verification:** Stand up broker via `docker compose up -d` (pulls `devonartis/agentwrit` from Docker Hub).

CHANGELOG.md

@@ -82,4 +82,4 @@ Demo work under [`demo/`](demo/) should follow the same rule: run against a real
 
 ## Security issues
 
-Please report security-sensitive problems through [GitHub Security Advisories](https://github.com/devonartis/agentauth-python/security/advisories) for this repository (or the maintainer's preferred private channel if one is published elsewhere). Do not file exploitable details in public issues before they are addressed.
+Please report security-sensitive problems through [GitHub Security Advisories](https://github.com/devonartis/agentwrit-python/security/advisories) for this repository (or the maintainer's preferred private channel if one is published elsewhere). Do not file exploitable details in public issues before they are addressed.

CLAUDE.md

@@ -30,14 +30,24 @@ This SDK is the Python client for the [AgentWrit broker](https://github.com/devo
 
 ## Installation
 
+Install from GitHub (not yet on PyPI):
+
 ```bash
-uv add agentwrit
+uv add git+https://github.com/devonartis/agentwrit-python.git
 ```
 
 Or with pip:
 
 ```bash
-pip install agentwrit
+pip install git+https://github.com/devonartis/agentwrit-python.git
+```
+
+For local development:
+
+```bash
+git clone https://github.com/devonartis/agentwrit-python.git
+cd agentwrit-python
+uv sync --all-extras
 ```
 
 **Requirements:** Python 3.10+ and a running [AgentWrit broker](https://github.com/devonartis/agentwrit) instance.
@@ -267,8 +277,8 @@ See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full workflow: `uv` setup, **
 Quick local checks (no broker required for unit tests):
 
 ```bash
-git clone https://github.com/devonartis/agentauth-python.git
-cd agentauth-python
+git clone https://github.com/devonartis/agentwrit-python.git
+cd agentwrit-python
 uv sync --all-extras
 
 uv run ruff check .
@@ -280,4 +290,4 @@ uv run pytest tests/unit/
 
 This SDK is licensed under the [MIT License](LICENSE).
 
-The [AgentWrit broker](https://github.com/devonartis/agentwrit) is licensed separately under AGPL-3.0. See the broker repo for details.
+The [AgentWrit broker](https://github.com/devonartis/agentwrit) is licensed separately under PolyForm Internal Use 1.0.0. See the broker repo for details.

CONTRIBUTING.md

@@ -195,6 +195,5 @@ See also [`.env.example`](.env.example) for variable names.
 
 ## 11. Further reading
 
-- **Product / technical spec:** [`.plans/specs/2026-04-08-medassist-demo-spec.md`](../.plans/specs/2026-04-08-medassist-demo-spec.md) (repo root)
 - **Presenter script:** [PRESENTERS_GUIDE.md](PRESENTERS_GUIDE.md)
-- **Broker API (source of truth for integration):** `broker/docs/api.md`
+- **Broker API (source of truth for integration):** [AgentWrit broker docs](https://github.com/devonartis/agentwrit/tree/main/docs)

README.md

@@ -484,7 +484,7 @@ This identity is:
 
 ## Standards Alignment
 
-The SDK implements the [Ephemeral Agent Credentialing](https://github.com/devonartis/AI-Security-Blueprints/blob/main/patterns/ephemeral-agent-credentialing/versions/v1.2.md) pattern (v1.2), which aligns with:
+The SDK implements the [Ephemeral Agent Credentialing](https://github.com/devonartis/AI-Security-Blueprints/blob/main/patterns/ephemeral-agent-credentialing/versions/v1.3.md) pattern (v1.3), which aligns with:
 
 | Standard | What it addresses |
 |----------|-------------------|

demo/BEGINNERS_GUIDE.md

@@ -72,7 +72,7 @@ For quick tasks, set a short TTL to minimize exposure:
 agent = app.create_agent(
     orch_id="quick-check",
     task_id="verify-customer",
-    requested_scope=["read:data:customer-artis"],
+    requested_scope=["read:data:customer-7291"],
     max_ttl=30,  # Token expires in 30 seconds
 )
 # If you forget to release, the token dies in 30 seconds anyway
@@ -233,7 +233,7 @@ from agentwrit import scope_is_subset
 agent = app.create_agent(
     orch_id="customer-service",
     task_id="lookup",
-    requested_scope=["read:data:customer-artis"],
+    requested_scope=["read:data:customer-7291"],
 )
 
 def handle_action(action_scope: list[str]) -> bool:
@@ -243,13 +243,13 @@ def handle_action(action_scope: list[str]) -> bool:
     return False  # block
 
 # Authorized
-handle_action(["read:data:customer-artis"])    # True
+handle_action(["read:data:customer-7291"])    # True
 
 # Blocked — different identifier
 handle_action(["read:data:all-customers"])     # False
 
 # Blocked — different action
-handle_action(["write:data:customer-artis"])   # False
+handle_action(["write:data:customer-7291"])   # False
 ```
 
 ### Validating with the Broker