diff --git a/README.md b/README.md
index bfe63ea..9da1ac4 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,19 @@
 # ai-tool-guard
 
+[![CI](https://github.com/dortort/ai-tool-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/dortort/ai-tool-guard/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/ai-tool-guard)](https://www.npmjs.com/package/ai-tool-guard)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A520-green?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Vercel AI SDK](https://img.shields.io/badge/Vercel_AI_SDK-%E2%89%A54.0-black?logo=vercel&logoColor=white)](https://sdk.vercel.ai)
+[![Docs](https://readthedocs.org/projects/ai-tool-guard/badge/?version=latest)](https://ai-tool-guard.readthedocs.io/)
+
 Policy enforcement middleware for [Vercel AI SDK](https://sdk.vercel.ai) tool calls.
 
 Guards, approvals, argument validation, rate limiting, output filtering, prompt-injection detection, MCP drift detection, and OpenTelemetry observability — as a composable middleware layer around your AI SDK tools.
 
+**[Read the full documentation](https://ai-tool-guard.readthedocs.io/)**
+
 ```
 npm install ai-tool-guard
 ```
@@ -76,31 +86,9 @@ const result = await generateText({
 
 ## Architecture
 
-```
-                    ┌─────────────────────────────────────────┐
-                    │        createToolGuard(options)          │
-                    └──────────────┬──────────────────────────┘
-                                   │
-            ┌──────────────────────┼──────────────────────┐
-            │                      │                      │
-    guardTool(name,tool,cfg) guardTools({...})       (config)
-            │                      │                      │
-            └──────────┬───────────┘                      │
-                       ▼                                  │
-              ┌─── Execution Pipeline ───┐                │
-              │                          │                │
-              │  1. Injection detection  │     ┌──────────┴─────┐
-              │  2. Argument validation  │     │  PolicyBackend │
-              │  3. Policy evaluation ◄──┼─────┤  (OPA, Cedar)  │
-              │  4. Approval flow        │     └────────────────┘
-              │  5. Rate limiting        │
-              │  6. Tool execution       │
-              │  7. Output filtering     │
-              │                          │
-              │   OTel spans emitted     │
-              │   at each step           │
-              └──────────────────────────┘
-```
+Every guarded tool call passes through a 7-stage execution pipeline: injection detection, argument validation, policy evaluation, approval flow, rate limiting, tool execution, and output filtering. Each stage emits an OpenTelemetry span.
+
+See the **[architecture overview](https://ai-tool-guard.readthedocs.io/#architecture)** for the full pipeline diagram.
 
 ## API reference
 
diff --git a/docs/index.md b/docs/index.md
index 22886b5..5c97a02 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -44,30 +44,30 @@ npm install ai-tool-guard
 The execution pipeline wraps each tool call in a series of composable stages:
 
 ```
- ┌─────────────────────────────────────────────────────────────────┐
- │                        createToolGuard                          │
+ ┌──────────────────────────────────────────────────────────────────┐
+ │                        createToolGuard                           │
  │                    (configuration & backends)                    │
- └──────────────────────────────┬──────────────────────────────────┘
+ └──────────────────────────────┬───────────────────────────────────┘
                                 │
                ┌────────────────▼────────────────┐
-               │        guardTool / guardTools    │
-               │    (wraps Vercel AI SDK tools)   │
+               │     guardTool / guardTools      │
+               │ (wraps Vercel AI SDK tools)     │
                └────────────────┬────────────────┘
                                 │
                ┌────────────────▼────────────────┐
-               │            Pipeline              │
-               │                                  │
-               │  1. Injection detection          │◄── OTel span
-               │  2. Argument validation          │◄── OTel span
-               │  3. Policy evaluation            │◄── PolicyBackend
-               │     ├─ allow                     │
-               │     ├─ block ──────────────────► │ DecisionRecord
-               │     └─ require-approval ───────► │ ApprovalRequest
-               │  4. Approval flow                │◄── OTel span
-               │     └─ approve / edit / deny     │
-               │  5. Rate limit check             │◄── OTel span
-               │  6. Tool execution               │◄── OTel span
-               │  7. Output filtering             │◄── OTel span
+               │           Pipeline              │
+               │                                 │
+               │  1. Injection detection         │◄── OTel span
+               │  2. Argument validation         │◄── OTel span
+               │  3. Policy evaluation           │◄── PolicyBackend
+               │     ├─ allow                    │
+               │     ├─ block ─────────────────► │ DecisionRecord
+               │     └─ require-approval ──────► │ ApprovalRequest
+               │  4. Approval flow               │◄── OTel span
+               │     └─ approve / edit / deny    │
+               │  5. Rate limit check            │◄── OTel span
+               │  6. Tool execution              │◄── OTel span
+               │  7. Output filtering            │◄── OTel span
                └────────────────┬────────────────┘
                                 │
                     ┌───────────▼───────────┐