Merge pull request #19 from devonartis/feature/architecture-diagrams

docs: add SVG architecture diagrams

Author: devonartis

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added — Architecture diagrams + splash pages (2026-04-13)
+
+- **`docs/diagrams/`** — 3 SVG architecture diagrams (architecture overview, token lifecycle, security topology) replacing the inline mermaid block. Built from code review, visual style adapted from agentauth-internal.
+- **`docs/python-sdk.md`** — splash page for the Python SDK (private repo). Shows status, code sample, and links to raw HTTP alternative.
+- **`docs/demos.md`** — splash page for MedAssist AI and Support Ticket demos (ship with Python SDK).
+- **`README.md`** — added Ephemeral Agent Credentialing v1.3 pattern lineage in "How it works". All private-repo links now point to splash pages instead of 404s.
+- **`docs/`** — 5 doc files updated: private `agentwrit-python` links replaced with splash page links.
+
 ### Changed — README overhaul for scannability and wayfinding (2026-04-13)
 
 - **`README.md`** — full restructure for newcomers who scan, not read:

README.md

@@ -87,7 +87,7 @@ You now have a launch token. The agent presents this once to register and get it
 
 | I want to... | Go to |
 |---|---|
-| Register an agent with this launch token (Python SDK) | [Python SDK →](https://github.com/devonartis/agentwrit-python) |
+| Register an agent with this launch token (Python SDK) | [Python SDK →](docs/python-sdk.md) |
 | See the raw HTTP registration flow (curl + openssl) | [Getting Started walkthrough →](docs/getting-started-user.md) |
 | Build from source or use Docker Compose instead | [Other install options →](#other-install-options) |
 | Understand what just happened (auth model, SPIFFE IDs, scopes) | [Concepts →](docs/concepts.md) |
@@ -96,14 +96,13 @@ You now have a launch token. The agent presents this once to register and get it
 
 ## How it works
 
-```mermaid
-flowchart LR
-    ADMIN["Operator"] -->|"create launch token"| BROKER["AgentWrit Broker"]
-    APP["Your App"] -->|"hand launch token to agent"| AGENT["AI Agent"]
-    AGENT -->|"register + get scoped JWT"| BROKER
-    AGENT -->|"Bearer token"| RS["Resource Server"]
-    BROKER -->|"audit every event"| AUDIT["Hash-chain log"]
-```
+AgentWrit implements the [Ephemeral Agent Credentialing v1.3](https://github.com/devonartis/AI-Security-Blueprints/blob/main/patterns/ephemeral-agent-credentialing/versions/v1.3.md) security pattern — an 8-component architecture purpose-built for autonomous AI agents. The pattern was developed as part of the [AI Security Blueprints](https://github.com/devonartis/AI-Security-Blueprints) project and AgentWrit is its reference implementation.
+
+<p align="center">
+  <img src="docs/diagrams/architecture-overview.svg" alt="AgentWrit Architecture Overview" width="100%">
+</p>
+
+> **Detailed diagrams:** [Token Lifecycle](docs/diagrams/token-lifecycle.svg) · [Security Topology](docs/diagrams/security-topology.svg)
 
 1. **Operator** creates a launch token with an allowed scope ceiling
 2. **App** hands the launch token to the agent for a specific task
@@ -142,15 +141,15 @@ The Python SDK includes **MedAssist AI**: a FastAPI web app where a local LLM dy
 | Clinical agent delegates to prescription agent | Delegation with scope attenuation |
 | Tokens renew and release at end of encounter | Full lifecycle management |
 
-**Run it:** [MedAssist AI demo →](https://github.com/devonartis/agentwrit-python/tree/main/demo) · [Beginner's guide →](https://github.com/devonartis/agentwrit-python/blob/main/demo/BEGINNERS_GUIDE.md) · [Presenter's guide →](https://github.com/devonartis/agentwrit-python/blob/main/demo/PRESENTERS_GUIDE.md)
+**Run it:** [MedAssist AI demo →](docs/demos.md) · [Beginner's guide →](docs/demos.md) · [Presenter's guide →](docs/demos.md)
 
 ---
 
 ## SDKs
 
 | Language | Repo | Install | Status |
 |----------|------|---------|--------|
-| **Python** | [agentwrit-python](https://github.com/devonartis/agentwrit-python) | `pip install agentauth` *(PyPI rename pending)* | v0.3.0 — 15 acceptance tests passing |
+| **Python** | [agentwrit-python](docs/python-sdk.md) | `pip install agentauth` *(PyPI rename pending)* | v0.3.0 — 15 acceptance tests passing |
 | **TypeScript** | Coming soon | — | Planned |
 
 ```python
@@ -170,7 +169,7 @@ response = httpx.get(url, headers=agent.bearer_header)
 agent.release()
 ```
 
-**Full SDK docs:** [Python SDK →](https://github.com/devonartis/agentwrit-python)
+**Full SDK docs:** [Python SDK →](docs/python-sdk.md)
 
 ---
 
@@ -304,8 +303,8 @@ go test ./... -short       # Unit tests only
 | Follow common workflows | [Common Tasks →](docs/common-tasks.md) |
 | Debug an issue | [Troubleshooting →](docs/troubleshooting.md) |
 | See real-world integration patterns | [Integration Patterns →](docs/integration-patterns.md) |
-| Use the Python SDK | [Python SDK →](https://github.com/devonartis/agentwrit-python) |
-| Run the MedAssist demo | [MedAssist AI →](https://github.com/devonartis/agentwrit-python/tree/main/demo) |
+| Use the Python SDK | [Python SDK →](docs/python-sdk.md) |
+| Run the MedAssist demo | [MedAssist AI →](docs/demos.md) |
 | Report a security vulnerability | [Security Policy →](SECURITY.md) |
 | Read the changelog | [CHANGELOG →](CHANGELOG.md) |
 

docs/README.md

@@ -60,12 +60,12 @@ Lookup documentation for endpoints, CLI commands, and internals.
 
 ## Live Demos
 
-See AgentWrit in action with the [Python SDK](https://github.com/devonartis/agentwrit-python) demo applications:
+See AgentWrit in action with the [Python SDK](python-sdk.md) demo applications:
 
 | Demo | What it shows |
 |------|-------------|
-| **[MedAssist AI](https://github.com/devonartis/agentwrit-python/tree/main/demo)** | Healthcare multi-agent pipeline — clinical, prescription, and billing agents operating under strict scope isolation with LLM tool-calling, delegation, and per-patient scoping |
-| **[Support Ticket Zero-Trust](https://github.com/devonartis/agentwrit-python/tree/main/demo2)** | Three LLM-driven agents processing support tickets with broker-issued scoped credentials, streaming execution via SSE, and natural token expiry |
+| **[MedAssist AI](demos.md)** | Healthcare multi-agent pipeline — clinical, prescription, and billing agents operating under strict scope isolation with LLM tool-calling, delegation, and per-patient scoping |
+| **[Support Ticket Zero-Trust](demos.md)** | Three LLM-driven agents processing support tickets with broker-issued scoped credentials, streaming execution via SSE, and natural token expiry |
 
 Both demos run against a real AgentWrit broker and show the full credential lifecycle: agent registration, scope enforcement, delegation, renewal, release, and revocation.
 

docs/agentwrit-explained.md

@@ -156,7 +156,7 @@ Ready to see it in action? Start here:
 **[Your First Five Minutes →](getting-started-user.md)**
 Run a local setup with Docker, walk through the registration flow, and get your first agent token.
 
-**[Live Demos →](https://github.com/devonartis/agentwrit-python)**
+**[Live Demos →](demos.md)**
 See AgentWrit in real applications — a healthcare multi-agent pipeline and a support ticket zero-trust demo, both running against a live broker with LLM-driven agents.
 
 Or jump to the topic that matches your interest:

docs/demos.md

@@ -0,0 +1,28 @@
+# AgentWrit Demos
+
+> **Coming soon.** The demo applications ship with the Python SDK and will be available when [`devonartis/agentwrit-python`](https://github.com/devonartis/agentwrit-python) goes public.
+
+## MedAssist AI
+
+A FastAPI web app where a local LLM dynamically creates broker agents with per-patient scoped credentials. You enter a patient ID and a plain-language request. The LLM chooses which tools to call, and the app creates agents with only the scopes those tools need — for that specific patient.
+
+| What you'll see | What it proves |
+|---|---|
+| Agents spawn on demand per LLM tool call | Dynamic agent creation |
+| Each agent scoped to one patient ID | Per-resource scope isolation |
+| LLM asks for wrong patient's data | Scope enforcement catches cross-boundary access |
+| Clinical agent delegates to prescription agent | Delegation with scope attenuation |
+| Tokens renew and release at end of encounter | Full lifecycle management |
+| Dedicated audit tab | Hash-chained broker events |
+
+## Support Ticket Zero-Trust
+
+Three LLM-driven agents process support tickets with broker-issued scoped credentials, streaming execution via SSE, and natural token expiry.
+
+## In the meantime
+
+You can follow the [Quick Start](../README.md#quick-start) to run the broker and issue your first agent token in five minutes. The [Getting Started walkthrough](getting-started-user.md) covers the full registration flow with curl.
+
+## Get notified
+
+Watch this repo or [file an issue](https://github.com/devonartis/agentwrit/issues) to be notified when demos are available.