diff --git a/README.md b/README.md
new file mode 100644
index 0000000..676a717
--- /dev/null
+++ b/README.md
@@ -0,0 +1,57 @@
+# caddy-atproto-auth
+
+A native Caddy module that provides Identity-Aware Proxy (IAP) capabilities using the **atproto** (Bluesky) OAuth 2.1 ecosystem. 
+
+Turn any atproto identity into a "Web Passport" for your self-hosted services. The module acts as an OAuth Confidential Client, managing the DPoP cryptographic handshake, session persistence, and DID-based authorization without requiring external authentication sidecars like Authelia.
+
+## Features
+
+- **Zero-Dependency**: Plugs directly into Caddy, no external databases (uses embedded SQLite).
+- **Stateless Verification**: Uses signed, domain-scoped cookies for lightning-fast request verification at the edge without database lookups.
+- **Two Deployment Modes**:
+  - *Standalone*: Add to any individual app's Caddyfile route directly.
+  - *Centralized Hub*: Act as an Identity Provider (`auth.example.com`) granting SSO access to many subdomains (`app.example.com`).
+- **Full Customization**: Fully override the login and forbidden pages with your own HTML templates.
+
+## Usage
+
+Build a custom Caddy binary with `xcaddy`:
+
+```bash
+xcaddy build \
+    --with github.com/vvill/caddy-atproto-auth
+```
+
+### Example: Centralized Auth Hub
+
+```caddyfile
+{
+    atproto {
+        storage_path /var/lib/caddy/atproto.db
+        cookie_secret "your-very-long-random-secret-key"
+    }
+}
+
+# The Portal (Login page and OAuth endpoints)
+auth.example.com {
+    atproto_portal {
+        name "My HomeLab"
+        domain auth.example.com
+    }
+}
+
+# A protected application
+app.example.com {
+    atproto_gate {
+        allow @alice.bsky.social
+        allow did:plc:1234...
+        portal_url https://auth.example.com
+    }
+    
+    reverse_proxy localhost:8080
+}
+```
+
+## Documentation
+
+See the `docs/` folder for detailed architectural constraints and configuration options.