diff --git a/README.md b/README.md
index fd3bddc..8edc565 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,17 @@
-# Kappopher
+<p align="center">
+  <img src="docs/assets/images/logo.png" alt="Kappopher" width="180">
+</p>
 
-[![Go Reference](https://pkg.go.dev/badge/github.com/Its-donkey/kappopher.svg)](https://pkg.go.dev/github.com/Its-donkey/kappopher)
-[![Go Report Card](https://goreportcard.com/badge/github.com/Its-donkey/kappopher)](https://goreportcard.com/report/github.com/Its-donkey/kappopher)
-[![Tests](https://github.com/Its-donkey/kappopher/actions/workflows/test.yml/badge.svg)](https://github.com/Its-donkey/kappopher/actions/workflows/test.yml)
-[![Coverage](https://raw.githubusercontent.com/Its-donkey/kappopher/main/.github/coverage.svg)](https://github.com/Its-donkey/kappopher/actions/workflows/test.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Go Version](https://img.shields.io/github/go-mod/go-version/Its-donkey/kappopher)](https://github.com/Its-donkey/kappopher)
+<h1 align="center">Kappopher</h1>
+
+<p align="center">
+  <a href="https://pkg.go.dev/github.com/Its-donkey/kappopher"><img src="https://pkg.go.dev/badge/github.com/Its-donkey/kappopher.svg" alt="Go Reference"></a>
+  <a href="https://goreportcard.com/report/github.com/Its-donkey/kappopher"><img src="https://goreportcard.com/badge/github.com/Its-donkey/kappopher" alt="Go Report Card"></a>
+  <a href="https://github.com/Its-donkey/kappopher/actions/workflows/test.yml"><img src="https://github.com/Its-donkey/kappopher/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
+  <a href="https://github.com/Its-donkey/kappopher/actions/workflows/test.yml"><img src="https://raw.githubusercontent.com/Its-donkey/kappopher/main/.github/coverage.svg" alt="Coverage"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://github.com/Its-donkey/kappopher"><img src="https://img.shields.io/github/go-mod/go-version/Its-donkey/kappopher" alt="Go Version"></a>
+</p>
 
 A comprehensive Twitch API toolkit for Go.
 
@@ -25,6 +31,8 @@ A comprehensive Twitch API toolkit for Go.
 - **Rate Limiting**: Automatic rate limit tracking with retry support
 - **Type-Safe**: Fully typed request/response structures with Go generics
 
+**[View Full Documentation and a complete cookbook of examples](https://its-donkey.github.io/kappopher/)**
+
 ## Installation
 
 ```bash
@@ -70,20 +78,6 @@ func main() {
 - [Quick Start Guide](./docs/quickstart.md) - Installation, authentication, and basic usage
 - [API Reference](./docs/README.md) - Full endpoint documentation
 
-## Comparison
-
-| Feature | Kappopher | Other Helix wrappers |
-|---------|-----------|----------------------|
-| IRC/TMI Chat | Yes | Varies |
-| EventSub WebSocket | Yes | No |
-| EventSub Conduits | Yes | Varies |
-| PubSub Compatibility Layer | Yes | No |
-| Middleware System | Yes | No |
-| Caching Layer | Yes | No |
-| Batch Operations | Yes | No |
-| All OAuth Flows | Yes | Partial |
-| Extension JWT | Full | Basic |
-
 ## License
 
 MIT License - see [LICENSE](./LICENSE) for details.
diff --git a/docs/Gemfile b/docs/Gemfile
new file mode 100644
index 0000000..3310869
--- /dev/null
+++ b/docs/Gemfile
@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+gem "github-pages", group: :jekyll_plugins
+gem "jekyll-remote-theme"
diff --git a/docs/README.md b/docs/README.md
index 476e137..1fe236a 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -5,10 +5,12 @@ This documentation provides detailed guides and examples for using the Twitch He
 ## Table of Contents
 
 - [Quick Start](quickstart.md) - Installation, basic usage, authentication, and error handling
-- [Available Endpoints](#available-endpoints) - All API methods
+- [Helix API](#helix-api) - All API endpoints
+- [IRC Client](#irc-client) - Real-time chat for bots
+- [Advanced Features](#advanced-features) - Batch operations, caching, EventSub
 - [Examples](#examples) - Working code samples
 
-## Available Endpoints
+## Helix API
 
 | Category | Documentation |
 |----------|---------------|
@@ -16,16 +18,14 @@ This documentation provides detailed guides and examples for using the Twitch He
 | [Analytics](analytics.md) | Extension and game analytics |
 | [Auth](auth.md) | OAuth flows, token management, OIDC |
 | [Bits](bits.md) | Bits leaderboard, cheermotes |
-| [Channel Points](channel-points.md) | Custom rewards, redemptions |
-| [Channels](channels.md) | Channel info, followers, editors, VIPs |
+| [Channel Points](Projects/Programming/Kappopher/Documents/channel-points.md) | Custom rewards, redemptions |
+| [Channels](Projects/Programming/Kappopher/Documents/channels.md) | Channel info, followers, editors, VIPs |
 | [Charity](charity.md) | Charity campaigns and donations |
 | [Chat](chat.md) | Chatters, emotes, badges, settings, messages |
 | [Clips](clips.md) | Create and get clips |
 | [CCL](ccl.md) | Content classification labels |
 | [Conduits](conduits.md) | EventSub conduit management |
 | [Entitlements](entitlements.md) | Drops entitlements |
-| [EventSub](eventsub.md) | Event subscriptions |
-| [PubSub Compatibility](pubsub-compat.md) | PubSub-style API backed by EventSub |
 | [Extensions](extensions.md) | Extension management |
 | [Games](games.md) | Game information |
 | [Goals](goals.md) | Creator goals |
@@ -45,14 +45,28 @@ This documentation provides detailed guides and examples for using the Twitch He
 | [Videos](videos.md) | VODs, highlights, uploads |
 | [Whispers](whispers.md) | Send whisper messages |
 
+## IRC Client
+
+| Category | Documentation |
+|----------|---------------|
+| [IRC Client](Projects/Programming/Kappopher/Documents/irc-client.md) | WebSocket-based chat client for building bots |
+
+## Advanced Features
+
+| Category | Documentation |
+|----------|---------------|
+| [EventSub](eventsub.md) | Event subscriptions (WebSocket & Webhooks) |
+| [PubSub Compatibility](pubsub-compat.md) | PubSub-style API backed by EventSub |
+| [Advanced](advanced.md) | Batch operations, rate limiting, caching, middleware |
+
 ## Examples
 
 See the [examples](./examples/) directory for code samples:
 
-- [Basic Usage](./examples/basic.md) - Simple API calls and error handling
-- [Chat Bot](./examples/chatbot.md) - Building a chat bot
-- [API Usage](./examples/api-usage.md) - Common API patterns
-- [EventSub Webhooks](./examples/eventsub-webhooks.md) - Webhook notifications
-- [EventSub WebSocket](./examples/eventsub-websocket.md) - Real-time events
-- [PubSub Migration](./examples/pubsub-migration.md) - Migrating from PubSub to EventSub
-- [Extension JWT](./examples/extension-jwt.md) - Extension authentication
+- [Basic Usage](basic.md) - Simple API calls and error handling
+- [Chat Bot](chatbot.md) - Building a chat bot
+- [API Usage](api-usage.md) - Common API patterns
+- [EventSub Webhooks](eventsub-webhooks.md) - Webhook notifications
+- [EventSub WebSocket](eventsub-websocket.md) - Real-time events
+- [PubSub Migration](pubsub-migration.md) - Migrating from PubSub to EventSub
+- [Extension JWT](Projects/Programming/Kappopher/Documents/examples/extension-jwt.md) - Extension authentication
diff --git a/docs/_config.yml b/docs/_config.yml
new file mode 100644
index 0000000..45b5bab
--- /dev/null
+++ b/docs/_config.yml
@@ -0,0 +1,31 @@
+title: Kappopher
+description: A comprehensive Go wrapper for the Twitch Helix API
+url: "https://its-donkey.github.io"
+baseurl: "/kappopher"
+
+# Syntax highlighting
+highlighter: rouge
+markdown: kramdown
+kramdown:
+  syntax_highlighter: rouge
+  input: GFM
+
+# Default front matter for all pages
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: "default"
+  - scope:
+      path: "examples"
+    values:
+      layout: "default"
+
+# Exclude files
+exclude:
+  - General.html
+  - "*.sh"
+  - Gemfile
+  - Gemfile.lock
+  - node_modules
+  - vendor
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
new file mode 100644
index 0000000..59a57d0
--- /dev/null
+++ b/docs/_layouts/default.html
@@ -0,0 +1,77 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{% if page.title %}{{ page.title }} | {% endif %}{{ site.title }}</title>
+  <meta name="description" content="{{ page.description | default: site.description }}">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="{{ '/assets/css/main.css' | relative_url }}">
+</head>
+<body>
+  <nav class="navbar">
+    <div class="nav-container">
+      <a href="{{ '/' | relative_url }}" class="nav-brand">
+        <img src="{{ '/assets/images/logo.png' | relative_url }}" alt="Kappopher" class="brand-logo">
+        <span class="brand-text">{{ site.title }}</span>
+      </a>
+      <div class="nav-links">
+        <a href="{{ '/' | relative_url }}" class="nav-link{% if page.url == '/' %} active{% endif %}">Home</a>
+        <a href="{{ '/quickstart' | relative_url }}" class="nav-link{% if page.url contains 'quickstart' %} active{% endif %}">Quick Start</a>
+        <a href="{{ '/api-reference' | relative_url }}" class="nav-link{% if page.url contains 'api-reference' or page.url contains '.md' and page.url != '/' %} active{% endif %}">API Reference</a>
+        <a href="{{ '/cookbook' | relative_url }}" class="nav-link{% if page.url contains 'cookbook' or page.url contains 'examples' %} active{% endif %}">Cookbook</a>
+        <a href="https://github.com/Its-donkey/kappopher" class="nav-link nav-github" target="_blank">
+          <svg height="20" width="20" viewBox="0 0 16 16" fill="currentColor">
+            <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/>
+          </svg>
+        </a>
+      </div>
+      <button class="nav-toggle" aria-label="Toggle navigation">
+        <span></span>
+        <span></span>
+        <span></span>
+      </button>
+    </div>
+  </nav>
+
+  <main class="main-content">
+    <div class="content-container">
+      {% if page.title and page.url != '/' %}
+      <header class="page-header">
+        <h1>{{ page.title }}</h1>
+        {% if page.description %}
+        <p class="page-description">{{ page.description }}</p>
+        {% endif %}
+      </header>
+      {% endif %}
+
+      <article class="content">
+        {{ content }}
+      </article>
+    </div>
+  </main>
+
+  <footer class="footer">
+    <div class="footer-container">
+      <div class="footer-content">
+        <p>Built with Jekyll for GitHub Pages</p>
+        <p class="footer-links">
+          <a href="https://github.com/Its-donkey/kappopher">GitHub</a>
+          <span class="separator">|</span>
+          <a href="https://pkg.go.dev/github.com/Its-donkey/kappopher">Go Docs</a>
+        </p>
+      </div>
+    </div>
+  </footer>
+
+  <script>
+    // Mobile navigation toggle
+    document.querySelector('.nav-toggle').addEventListener('click', function() {
+      document.querySelector('.nav-links').classList.toggle('active');
+      this.classList.toggle('active');
+    });
+  </script>
+</body>
+</html>
diff --git a/docs/ads.md b/docs/ads.md
index 7f5fc4a..28f9ea6 100644
--- a/docs/ads.md
+++ b/docs/ads.md
@@ -1,6 +1,27 @@
-# Ads API
+---
+layout: default
+title: Ads API
+description: Manage commercial breaks and ad schedules for Twitch channels.
+---
 
-Manage commercial breaks and ad schedules for Twitch channels.
+## Overview
+
+Control advertising on your Twitch channel programmatically:
+
+**Commercial Breaks**: Run ads during your stream
+- Start commercials of various lengths (30-180 seconds)
+- Check cooldown before next commercial
+
+**Ad Schedule**: Manage automatic ad scheduling
+- View upcoming scheduled ads
+- Check preroll-free time remaining
+- Snooze scheduled ads (limited per stream)
+
+## Prerequisites
+
+- **Start Commercial:** `channel:edit:commercial` scope
+- **Ad Schedule (read):** `channel:read:ads` scope
+- **Ad Schedule (manage):** `channel:manage:ads` scope
 
 ## StartCommercial
 
@@ -99,3 +120,4 @@ for _, schedule := range resp.Data {
   ]
 }
 ```
+
diff --git a/docs/advanced.md b/docs/advanced.md
new file mode 100644
index 0000000..d246fc4
--- /dev/null
+++ b/docs/advanced.md
@@ -0,0 +1,420 @@
+---
+layout: default
+title: Advanced Features
+description: This guide covers advanced features for optimizing performance and handling complex use cases.
+---
+
+## Overview
+
+Optimize your application with these advanced capabilities:
+
+**Batch Operations**: Execute multiple API requests efficiently
+- `Batch`: Concurrent requests for maximum throughput
+- `BatchSequential`: Ordered execution with easier error handling
+- `BatchWithCallback`: Progress tracking for large operations
+
+**Rate Limiting**: Stay within Twitch's API limits
+- Automatic tracking via response headers
+- Wait functions for graceful handling
+- Retry logic with rate limit awareness
+
+**Caching**: Reduce redundant API calls
+- In-memory cache with configurable TTL
+- Custom cache implementations (Redis, etc.)
+- Cache key isolation for multi-tenant apps
+
+**Middleware**: Extend client functionality
+- Request/response logging
+- Automatic retries with backoff
+- Custom headers and request modification
+
+## Prerequisites
+
+These advanced features work with any authenticated client. Ensure you have:
+- A valid `AuthClient` configured with appropriate credentials
+- Required scopes for the specific API endpoints you're calling
+
+## Batch Operations
+
+Execute multiple API requests efficiently with built-in concurrency control.
+
+### Basic Batch
+
+```go
+// Execute multiple requests concurrently
+results := client.Batch(ctx, []helix.BatchRequest{
+    {
+        Request: &helix.Request{
+            Method:   "GET",
+            Endpoint: "/users",
+            Query:    url.Values{"id": []string{"123"}},
+        },
+        Result: &user1Response,
+    },
+    {
+        Request: &helix.Request{
+            Method:   "GET",
+            Endpoint: "/users",
+            Query:    url.Values{"id": []string{"456"}},
+        },
+        Result: &user2Response,
+    },
+}, nil)
+
+// Check for errors
+if helix.HasErrors(results) {
+    for _, r := range results {
+        if r.Error != nil {
+            log.Printf("Request %d failed: %v", r.Index, r.Error)
+        }
+    }
+}
+```
+
+### Batch Options
+
+```go
+opts := &helix.BatchOptions{
+    MaxConcurrent: 5,    // Limit to 5 concurrent requests (0 = unlimited)
+    StopOnError:   true, // Stop on first error
+}
+
+results := client.Batch(ctx, requests, opts)
+```
+
+### BatchGet (Convenience)
+
+```go
+// Simplified batch GET requests
+results := client.BatchGet(ctx, []helix.GetRequest{
+    {Endpoint: "/users", Query: url.Values{"id": []string{"123"}}, Result: &user1},
+    {Endpoint: "/users", Query: url.Values{"id": []string{"456"}}, Result: &user2},
+    {Endpoint: "/streams", Query: url.Values{"user_id": []string{"123"}}, Result: &stream1},
+}, nil)
+```
+
+### BatchSequential
+
+```go
+// Execute requests one at a time (preserves order, easier error handling)
+results := client.BatchSequential(ctx, requests)
+
+for _, r := range results {
+    if r.Error != nil {
+        // Stop processing on error
+        break
+    }
+}
+```
+
+### BatchWithCallback
+
+```go
+// Process results as they complete
+var mu sync.Mutex
+completed := 0
+
+client.BatchWithCallback(ctx, requests, nil, func(result helix.BatchResult) {
+    mu.Lock()
+    defer mu.Unlock()
+    completed++
+
+    if result.Error != nil {
+        log.Printf("Request %d failed: %v", result.Index, result.Error)
+    } else {
+        log.Printf("Request %d completed (%d/%d)", result.Index, completed, len(requests))
+    }
+})
+```
+
+### Helper Functions
+
+```go
+// Check if any request failed
+if helix.HasErrors(results) { ... }
+
+// Get first error (or nil)
+if err := helix.FirstError(results); err != nil { ... }
+
+// Get all errors
+for _, err := range helix.Errors(results) { ... }
+```
+
+## Rate Limiting
+
+The client tracks rate limit information from API responses.
+
+### Checking Rate Limits
+
+```go
+// Get current rate limit info
+info := client.GetRateLimitInfo()
+fmt.Printf("Remaining: %d/%d, Resets at: %v\n",
+    info.Remaining, info.Limit, info.Reset)
+```
+
+### Waiting for Rate Limits
+
+```go
+// Wait until rate limit resets (with context for cancellation)
+ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+defer cancel()
+
+if err := client.WaitForRateLimit(ctx); err != nil {
+    log.Printf("Wait cancelled: %v", err)
+}
+```
+
+### Automatic Rate Limit Handling
+
+```go
+// Implement retry logic with rate limit awareness
+func doRequestWithRetry(ctx context.Context, fn func() error) error {
+    for i := 0; i < 3; i++ {
+        err := fn()
+        if err == nil {
+            return nil
+        }
+
+        // Check if rate limited
+        var apiErr *helix.APIError
+        if errors.As(err, &apiErr) && apiErr.StatusCode == 429 {
+            if waitErr := client.WaitForRateLimit(ctx); waitErr != nil {
+                return waitErr
+            }
+            continue
+        }
+
+        return err
+    }
+    return errors.New("max retries exceeded")
+}
+```
+
+## Caching
+
+The client supports caching API responses to reduce redundant requests.
+
+### Enabling Cache
+
+```go
+// Use built-in memory cache
+cache := helix.NewMemoryCache(1000) // Max 1000 entries
+client := helix.NewClient(authClient, helix.WithCache(cache))
+```
+
+### Cache Operations
+
+```go
+// Clear entire cache
+client.ClearCache()
+
+// Invalidate specific endpoint
+client.InvalidateCache("/users")
+
+// Invalidate with token context (for multi-tenant scenarios)
+client.InvalidateCacheWithContext(ctx, "/users")
+```
+
+### Custom Cache Implementation
+
+```go
+// Implement the Cache interface
+type Cache interface {
+    Get(key string) ([]byte, bool)
+    Set(key string, value []byte, ttl time.Duration)
+    Delete(key string)
+    Clear()
+}
+
+// Example: Redis cache
+type RedisCache struct {
+    client *redis.Client
+}
+
+func (c *RedisCache) Get(key string) ([]byte, bool) {
+    val, err := c.client.Get(ctx, key).Bytes()
+    if err != nil {
+        return nil, false
+    }
+    return val, true
+}
+
+// ... implement other methods
+
+client := helix.NewClient(authClient, helix.WithCache(&RedisCache{client: redisClient}))
+```
+
+### Cache Key Generation
+
+```go
+// Generate cache keys with token isolation
+key := helix.CacheKeyWithContext(ctx, "GET", "/users", query)
+
+// Generate token hash for cache isolation
+hash := helix.TokenHash(token)
+```
+
+## Middleware
+
+Add custom middleware to intercept and modify requests/responses.
+
+### Adding Middleware
+
+```go
+// Middleware function signature
+type Middleware func(next http.RoundTripper) http.RoundTripper
+
+// Add logging middleware
+client.Use(func(next http.RoundTripper) http.RoundTripper {
+    return RoundTripperFunc(func(req *http.Request) (*http.Response, error) {
+        start := time.Now()
+
+        resp, err := next.RoundTrip(req)
+
+        log.Printf("%s %s - %v (%v)",
+            req.Method, req.URL.Path, resp.StatusCode, time.Since(start))
+
+        return resp, err
+    })
+})
+```
+
+### Common Middleware Examples
+
+#### Request Logging
+
+```go
+func LoggingMiddleware(next http.RoundTripper) http.RoundTripper {
+    return RoundTripperFunc(func(req *http.Request) (*http.Response, error) {
+        log.Printf("-> %s %s", req.Method, req.URL)
+        resp, err := next.RoundTrip(req)
+        if resp != nil {
+            log.Printf("<- %d %s", resp.StatusCode, req.URL)
+        }
+        return resp, err
+    })
+}
+```
+
+#### Retry Middleware
+
+```go
+func RetryMiddleware(maxRetries int) Middleware {
+    return func(next http.RoundTripper) http.RoundTripper {
+        return RoundTripperFunc(func(req *http.Request) (*http.Response, error) {
+            var resp *http.Response
+            var err error
+
+            for i := 0; i <= maxRetries; i++ {
+                resp, err = next.RoundTrip(req)
+                if err == nil && resp.StatusCode < 500 {
+                    return resp, nil
+                }
+
+                if i < maxRetries {
+                    time.Sleep(time.Duration(i+1) * time.Second)
+                }
+            }
+
+            return resp, err
+        })
+    }
+}
+```
+
+#### Custom Headers
+
+```go
+func CustomHeadersMiddleware(headers map[string]string) Middleware {
+    return func(next http.RoundTripper) http.RoundTripper {
+        return RoundTripperFunc(func(req *http.Request) (*http.Response, error) {
+            for k, v := range headers {
+                req.Header.Set(k, v)
+            }
+            return next.RoundTrip(req)
+        })
+    }
+}
+```
+
+## Low-Level Request Execution
+
+For advanced use cases, you can execute raw requests directly.
+
+### Using Do()
+
+```go
+// Execute a custom request
+var result MyCustomResponse
+err := client.Do(ctx, &helix.Request{
+    Method:   "POST",
+    Endpoint: "/some/endpoint",
+    Query:    url.Values{"param": []string{"value"}},
+    Body:     requestBody,
+}, &result)
+```
+
+### Request Structure
+
+```go
+type Request struct {
+    Method   string      // HTTP method (GET, POST, PUT, PATCH, DELETE)
+    Endpoint string      // API endpoint path (e.g., "/users")
+    Query    url.Values  // Query parameters
+    Body     interface{} // Request body (will be JSON encoded)
+}
+```
+
+## Performance Tips
+
+### 1. Use Batch Requests
+
+```go
+// Instead of multiple sequential calls:
+user1, _ := client.GetUsers(ctx, &helix.GetUsersParams{IDs: []string{"123"}})
+user2, _ := client.GetUsers(ctx, &helix.GetUsersParams{IDs: []string{"456"}})
+
+// Use a single call with multiple IDs:
+users, _ := client.GetUsers(ctx, &helix.GetUsersParams{IDs: []string{"123", "456"}})
+```
+
+### 2. Enable Caching for Repeated Requests
+
+```go
+// Cache frequently accessed data
+cache := helix.NewMemoryCache(1000)
+client := helix.NewClient(authClient, helix.WithCache(cache))
+
+// First call hits API
+users, _ := client.GetUsers(ctx, params)
+
+// Second call uses cache
+users, _ := client.GetUsers(ctx, params) // No API call
+```
+
+### 3. Limit Concurrent Requests
+
+```go
+// Avoid overwhelming the API
+opts := &helix.BatchOptions{
+    MaxConcurrent: 10, // Twitch recommends limiting concurrent requests
+}
+```
+
+### 4. Use Context for Timeouts
+
+```go
+// Set reasonable timeouts
+ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+defer cancel()
+
+result, err := client.GetUsers(ctx, params)
+```
+
+## See Also
+
+- [Quick Start](quickstart.md) - Basic setup and usage
+- [Auth](auth.md) - Authentication and token management
+- [EventSub](eventsub.md) - Real-time event subscriptions
+
diff --git a/docs/analytics.md b/docs/analytics.md
index 6a528d0..5a9d3da 100644
--- a/docs/analytics.md
+++ b/docs/analytics.md
@@ -1,6 +1,8 @@
-# Analytics API
-
-Retrieve analytics reports for extensions and games, including downloadable CSV reports.
+---
+layout: default
+title: Analytics API
+description: Retrieve analytics reports for extensions and games, including downloadable CSV reports.
+---
 
 ## GetExtensionAnalytics
 
@@ -85,3 +87,4 @@ for _, report := range resp.Data {
   }
 }
 ```
+
diff --git a/docs/api-reference.md b/docs/api-reference.md
new file mode 100644
index 0000000..71b2fd4
--- /dev/null
+++ b/docs/api-reference.md
@@ -0,0 +1,62 @@
+---
+layout: default
+title: API Reference
+description: Complete documentation for all Twitch Helix API endpoints.
+---
+
+## Authentication
+- [Authentication API](auth.md) - OAuth flows and token management
+
+## Chat & Messaging
+- [Chat API](chat.md) - Chat rooms, emotes, badges, messages
+- [IRC/Chat Client](irc-client.md) - Real-time chat via WebSocket
+- [Whispers API](whispers.md) - Private messages
+
+## Channels & Streams
+- [Channels API](channels.md) - Channel information, followers, editors
+- [Streams API](streams.md) - Live streams and markers
+- [Schedule API](schedule.md) - Stream schedules
+- [Raids API](raids.md) - Channel raids
+
+## Monetization
+- [Bits API](bits.md) - Bits leaderboards and cheermotes
+- [Subscriptions API](subscriptions.md) - Subscriber information
+- [Channel Points API](channel-points.md) - Custom rewards and redemptions
+- [Ads API](ads.md) - Commercial breaks and ad schedules
+- [Charity API](charity.md) - Charity campaigns
+
+## Engagement
+- [Polls API](polls.md) - Channel polls
+- [Predictions API](predictions.md) - Outcome predictions
+- [Hype Train API](hype-train.md) - Hype train events
+- [Goals API](goals.md) - Creator goals
+
+## Events
+- [EventSub API](eventsub.md) - Real-time event subscriptions
+- [EventSub Conduits API](conduits.md) - High-availability event routing
+- [PubSub Compatibility](pubsub-compat.md) - Legacy PubSub migration
+
+## Content
+- [Videos API](videos.md) - VODs, highlights, uploads
+- [Clips API](clips.md) - Clip creation and retrieval
+- [Games API](games.md) - Game/category information
+- [Search API](search.md) - Search channels and categories
+
+## Users & Teams
+- [Users API](users.md) - User information and blocks
+- [Teams API](teams.md) - Team information
+
+## Moderation
+- [Moderation API](moderation.md) - Bans, moderators, AutoMod
+
+## Extensions
+- [Extensions API](extensions.md) - Extension management
+- [Extension JWT](extension-jwt.md) - JWT authentication
+
+## Other
+- [Analytics API](analytics.md) - Extension and game analytics
+- [Drops Entitlements API](entitlements.md) - Twitch Drops
+- [Ingest Servers API](ingest.md) - Streaming servers
+- [Guest Star API](guest-star.md) - Guest Star (beta)
+- [Content Classification](ccl.md) - Content labels
+- [Advanced Features](advanced.md) - Batch, caching, middleware
diff --git a/docs/assets/css/main.css b/docs/assets/css/main.css
new file mode 100644
index 0000000..3bff890
--- /dev/null
+++ b/docs/assets/css/main.css
@@ -0,0 +1,594 @@
+/* ========================================
+   Kappopher Documentation Theme
+   A modern, Twitch-inspired documentation theme
+   ======================================== */
+
+:root {
+  /* Twitch-inspired colors */
+  --purple-primary: #9146FF;
+  --purple-dark: #772CE8;
+  --purple-darker: #5C16C5;
+  --purple-light: #BF94FF;
+  --purple-subtle: #F0E6FF;
+
+  /* Dark theme colors */
+  --dark-bg: #0E0E10;
+  --dark-surface: #18181B;
+  --dark-surface-light: #1F1F23;
+  --dark-border: #2F2F35;
+
+  /* Light theme colors */
+  --light-bg: #FFFFFF;
+  --light-surface: #F7F7F8;
+  --light-border: #E5E5E5;
+  --light-text: #0E0E10;
+  --light-text-muted: #53535F;
+
+  /* Semantic colors */
+  --success: #00C853;
+  --warning: #FFB300;
+  --error: #FF5252;
+  --info: #2196F3;
+
+  /* Typography */
+  --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  --font-mono: 'JetBrains Mono', 'Fira Code', 'SF Mono', Consolas, monospace;
+
+  /* Spacing */
+  --space-xs: 0.25rem;
+  --space-sm: 0.5rem;
+  --space-md: 1rem;
+  --space-lg: 1.5rem;
+  --space-xl: 2rem;
+  --space-2xl: 3rem;
+  --space-3xl: 4rem;
+
+  /* Shadows */
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.07);
+  --shadow-lg: 0 10px 25px rgba(0, 0, 0, 0.1);
+
+  /* Border radius */
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  --radius-xl: 16px;
+
+  /* Transitions */
+  --transition-fast: 150ms ease;
+  --transition-normal: 250ms ease;
+}
+
+/* ========================================
+   Reset & Base
+   ======================================== */
+
+*, *::before, *::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  font-size: 16px;
+  scroll-behavior: smooth;
+}
+
+body {
+  font-family: var(--font-sans);
+  font-size: 1rem;
+  line-height: 1.6;
+  color: var(--light-text);
+  background: var(--light-bg);
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+/* ========================================
+   Navigation
+   ======================================== */
+
+.navbar {
+  position: sticky;
+  top: 0;
+  z-index: 100;
+  background: var(--dark-bg);
+  border-bottom: 1px solid var(--dark-border);
+  backdrop-filter: blur(10px);
+}
+
+.nav-container {
+  max-width: 1400px;
+  margin: 0 auto;
+  padding: 0 var(--space-lg);
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  height: 64px;
+}
+
+.nav-brand {
+  display: flex;
+  align-items: center;
+  gap: var(--space-sm);
+  text-decoration: none;
+  color: white;
+  font-weight: 600;
+  font-size: 1.125rem;
+}
+
+.brand-logo {
+  width: 40px;
+  height: 40px;
+  border-radius: var(--radius-md);
+  object-fit: contain;
+}
+
+.brand-text {
+  color: white;
+}
+
+.nav-links {
+  display: flex;
+  align-items: center;
+  gap: var(--space-xs);
+}
+
+.nav-link {
+  padding: var(--space-sm) var(--space-md);
+  color: rgba(255, 255, 255, 0.8);
+  text-decoration: none;
+  font-size: 0.9375rem;
+  font-weight: 500;
+  border-radius: var(--radius-md);
+  transition: all var(--transition-fast);
+}
+
+.nav-link:hover {
+  color: white;
+  background: rgba(255, 255, 255, 0.1);
+}
+
+.nav-link.active {
+  color: var(--purple-light);
+  background: rgba(145, 70, 255, 0.15);
+}
+
+.nav-github {
+  margin-left: var(--space-sm);
+  padding: var(--space-sm);
+}
+
+.nav-toggle {
+  display: none;
+  flex-direction: column;
+  gap: 5px;
+  background: none;
+  border: none;
+  cursor: pointer;
+  padding: var(--space-sm);
+}
+
+.nav-toggle span {
+  display: block;
+  width: 24px;
+  height: 2px;
+  background: white;
+  border-radius: 2px;
+  transition: all var(--transition-fast);
+}
+
+/* ========================================
+   Main Content
+   ======================================== */
+
+.main-content {
+  flex: 1;
+  padding: var(--space-2xl) var(--space-lg);
+}
+
+.content-container {
+  max-width: 900px;
+  margin: 0 auto;
+}
+
+.page-header {
+  margin-bottom: var(--space-2xl);
+  padding-bottom: var(--space-xl);
+  border-bottom: 1px solid var(--light-border);
+}
+
+.page-header h1 {
+  font-size: 2.5rem;
+  font-weight: 700;
+  color: var(--light-text);
+  margin-bottom: var(--space-sm);
+}
+
+.page-description {
+  font-size: 1.125rem;
+  color: var(--light-text-muted);
+}
+
+/* ========================================
+   Typography
+   ======================================== */
+
+.content h1 {
+  font-size: 2.25rem;
+  font-weight: 700;
+  margin-top: var(--space-3xl);
+  margin-bottom: var(--space-lg);
+  color: var(--light-text);
+  line-height: 1.3;
+}
+
+.content h1:first-child {
+  margin-top: 0;
+}
+
+.content h2 {
+  font-size: 1.75rem;
+  font-weight: 600;
+  margin-top: var(--space-2xl);
+  margin-bottom: var(--space-md);
+  color: var(--light-text);
+  padding-bottom: var(--space-sm);
+  border-bottom: 2px solid var(--purple-subtle);
+}
+
+.content h3 {
+  font-size: 1.375rem;
+  font-weight: 600;
+  margin-top: var(--space-xl);
+  margin-bottom: var(--space-md);
+  color: var(--light-text);
+}
+
+.content h4 {
+  font-size: 1.125rem;
+  font-weight: 600;
+  margin-top: var(--space-lg);
+  margin-bottom: var(--space-sm);
+  color: var(--light-text);
+}
+
+.content p {
+  margin-bottom: var(--space-md);
+}
+
+.content a {
+  color: var(--purple-primary);
+  text-decoration: none;
+  font-weight: 500;
+  transition: color var(--transition-fast);
+}
+
+.content a:hover {
+  color: var(--purple-darker);
+  text-decoration: underline;
+}
+
+.content strong {
+  font-weight: 600;
+  color: var(--light-text);
+}
+
+/* ========================================
+   Lists
+   ======================================== */
+
+.content ul, .content ol {
+  margin-bottom: var(--space-md);
+  padding-left: var(--space-xl);
+}
+
+.content li {
+  margin-bottom: var(--space-sm);
+}
+
+.content li > ul, .content li > ol {
+  margin-top: var(--space-sm);
+  margin-bottom: 0;
+}
+
+/* ========================================
+   Code
+   ======================================== */
+
+.content code {
+  font-family: var(--font-mono);
+  font-size: 0.875em;
+  background: var(--purple-subtle);
+  color: var(--purple-darker);
+  padding: 0.2em 0.4em;
+  border-radius: var(--radius-sm);
+}
+
+.content pre {
+  margin: var(--space-lg) 0;
+  padding: var(--space-lg);
+  background: var(--dark-surface);
+  border-radius: var(--radius-lg);
+  overflow-x: auto;
+  border: 1px solid var(--dark-border);
+}
+
+.content pre code {
+  background: transparent;
+  color: #E4E4E7;
+  padding: 0;
+  font-size: 0.875rem;
+  line-height: 1.7;
+}
+
+/* Syntax Highlighting */
+.highlight .c, .highlight .c1, .highlight .cm { color: #6B7280; font-style: italic; }
+.highlight .k, .highlight .kd, .highlight .kn, .highlight .kp, .highlight .kr, .highlight .kt { color: var(--purple-light); font-weight: 500; }
+.highlight .s, .highlight .s1, .highlight .s2, .highlight .sb, .highlight .sc, .highlight .sd, .highlight .se, .highlight .sh, .highlight .si, .highlight .sx, .highlight .sr { color: #86EFAC; }
+.highlight .n, .highlight .na, .highlight .nb, .highlight .nc, .highlight .nd, .highlight .ne, .highlight .nf, .highlight .ni, .highlight .nl, .highlight .nn, .highlight .no, .highlight .nt, .highlight .nv { color: #E4E4E7; }
+.highlight .m, .highlight .mi, .highlight .mf, .highlight .mh, .highlight .mo, .highlight .il { color: #FCD34D; }
+.highlight .o, .highlight .ow { color: #F472B6; }
+.highlight .p { color: #A1A1AA; }
+.highlight .err { color: #F87171; }
+
+/* ========================================
+   Tables
+   ======================================== */
+
+.content table {
+  width: 100%;
+  margin: var(--space-lg) 0;
+  border-collapse: collapse;
+  font-size: 0.9375rem;
+  border-radius: var(--radius-lg);
+  overflow: hidden;
+  box-shadow: var(--shadow-sm);
+  border: 1px solid var(--light-border);
+}
+
+.content thead {
+  background: linear-gradient(135deg, var(--purple-primary) 0%, var(--purple-dark) 100%);
+}
+
+.content th {
+  padding: var(--space-md) var(--space-lg);
+  text-align: left;
+  font-weight: 600;
+  color: white;
+  font-size: 0.875rem;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+.content td {
+  padding: var(--space-md) var(--space-lg);
+  border-bottom: 1px solid var(--light-border);
+}
+
+.content tbody tr:last-child td {
+  border-bottom: none;
+}
+
+.content tbody tr:nth-child(even) {
+  background: var(--light-surface);
+}
+
+.content tbody tr:hover {
+  background: var(--purple-subtle);
+}
+
+/* ========================================
+   Blockquotes
+   ======================================== */
+
+.content blockquote {
+  margin: var(--space-lg) 0;
+  padding: var(--space-md) var(--space-lg);
+  background: var(--light-surface);
+  border-left: 4px solid var(--purple-primary);
+  border-radius: 0 var(--radius-md) var(--radius-md) 0;
+  color: var(--light-text-muted);
+}
+
+.content blockquote p:last-child {
+  margin-bottom: 0;
+}
+
+/* ========================================
+   Horizontal Rule
+   ======================================== */
+
+.content hr {
+  margin: var(--space-2xl) 0;
+  border: none;
+  height: 1px;
+  background: linear-gradient(90deg, transparent, var(--light-border), transparent);
+}
+
+/* ========================================
+   Images
+   ======================================== */
+
+.content img {
+  max-width: 100%;
+  height: auto;
+  border-radius: var(--radius-md);
+  margin: var(--space-lg) 0;
+}
+
+/* ========================================
+   Footer
+   ======================================== */
+
+.footer {
+  background: var(--dark-bg);
+  border-top: 1px solid var(--dark-border);
+  padding: var(--space-xl) var(--space-lg);
+  margin-top: auto;
+}
+
+.footer-container {
+  max-width: 1400px;
+  margin: 0 auto;
+}
+
+.footer-content {
+  text-align: center;
+  color: rgba(255, 255, 255, 0.6);
+  font-size: 0.875rem;
+}
+
+.footer-links {
+  margin-top: var(--space-sm);
+}
+
+.footer-links a {
+  color: var(--purple-light);
+  text-decoration: none;
+  transition: color var(--transition-fast);
+}
+
+.footer-links a:hover {
+  color: white;
+}
+
+.footer-links .separator {
+  margin: 0 var(--space-sm);
+  opacity: 0.5;
+}
+
+/* ========================================
+   Responsive Design
+   ======================================== */
+
+@media (max-width: 768px) {
+  .nav-links {
+    position: fixed;
+    top: 64px;
+    left: 0;
+    right: 0;
+    background: var(--dark-bg);
+    flex-direction: column;
+    padding: var(--space-md);
+    gap: var(--space-xs);
+    border-bottom: 1px solid var(--dark-border);
+    transform: translateY(-100%);
+    opacity: 0;
+    visibility: hidden;
+    transition: all var(--transition-normal);
+  }
+
+  .nav-links.active {
+    transform: translateY(0);
+    opacity: 1;
+    visibility: visible;
+  }
+
+  .nav-link {
+    width: 100%;
+    text-align: center;
+    padding: var(--space-md);
+  }
+
+  .nav-toggle {
+    display: flex;
+  }
+
+  .nav-toggle.active span:nth-child(1) {
+    transform: rotate(45deg) translate(5px, 5px);
+  }
+
+  .nav-toggle.active span:nth-child(2) {
+    opacity: 0;
+  }
+
+  .nav-toggle.active span:nth-child(3) {
+    transform: rotate(-45deg) translate(5px, -5px);
+  }
+
+  .main-content {
+    padding: var(--space-xl) var(--space-md);
+  }
+
+  .page-header h1 {
+    font-size: 2rem;
+  }
+
+  .content h1 {
+    font-size: 1.75rem;
+  }
+
+  .content h2 {
+    font-size: 1.5rem;
+  }
+
+  .content h3 {
+    font-size: 1.25rem;
+  }
+
+  .content pre {
+    padding: var(--space-md);
+    margin-left: calc(-1 * var(--space-md));
+    margin-right: calc(-1 * var(--space-md));
+    border-radius: 0;
+    max-width: 100vw;
+    overflow-x: hidden;
+    white-space: pre-wrap;
+    word-wrap: break-word;
+    word-break: break-all;
+    overflow-wrap: anywhere;
+  }
+
+  .content pre code {
+    white-space: pre-wrap;
+    word-wrap: break-word;
+    word-break: break-all;
+    overflow-wrap: anywhere;
+    display: block;
+    max-width: 100%;
+  }
+
+  .content table {
+    display: block;
+    overflow-x: auto;
+    white-space: nowrap;
+  }
+}
+
+/* ========================================
+   Utility Classes
+   ======================================== */
+
+.text-center { text-align: center; }
+.text-muted { color: var(--light-text-muted); }
+.mt-0 { margin-top: 0; }
+.mb-0 { margin-bottom: 0; }
+
+/* Feature cards for homepage */
+.feature-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: var(--space-lg);
+  margin: var(--space-xl) 0;
+}
+
+.feature-card {
+  padding: var(--space-lg);
+  background: var(--light-surface);
+  border-radius: var(--radius-lg);
+  border: 1px solid var(--light-border);
+  transition: all var(--transition-normal);
+}
+
+.feature-card:hover {
+  border-color: var(--purple-primary);
+  box-shadow: var(--shadow-md);
+  transform: translateY(-2px);
+}
+
+.feature-card h3 {
+  margin-top: 0;
+  color: var(--purple-dark);
+}
diff --git a/docs/assets/images/logo.png b/docs/assets/images/logo.png
new file mode 100644
index 0000000..39b4409
Binary files /dev/null and b/docs/assets/images/logo.png differ
diff --git a/docs/auth.md b/docs/auth.md
index 2ba5b52..3b98659 100644
--- a/docs/auth.md
+++ b/docs/auth.md
@@ -1,6 +1,8 @@
-# Authentication API
-
-OAuth 2.0 authentication client for Twitch, supporting multiple authorization flows and OIDC.
+---
+layout: default
+title: Authentication API
+description: OAuth 2.0 authentication client for Twitch, supporting multiple authorization flows and OIDC.
+---
 
 ## Setup
 
@@ -610,3 +612,4 @@ if err != nil {
     }
 }
 ```
+
diff --git a/docs/bits.md b/docs/bits.md
index dde3f35..755d534 100644
--- a/docs/bits.md
+++ b/docs/bits.md
@@ -1,6 +1,8 @@
-# Bits API
-
-Retrieve Bits leaderboards and cheermote information for Twitch channels.
+---
+layout: default
+title: Bits API
+description: Retrieve Bits leaderboards and cheermote information for Twitch channels.
+---
 
 ## GetBitsLeaderboard
 
@@ -294,3 +296,4 @@ for _, cheermote := range resp.Data {
   ]
 }
 ```
+
diff --git a/docs/ccl.md b/docs/ccl.md
index 5c31ab1..5a31280 100644
--- a/docs/ccl.md
+++ b/docs/ccl.md
@@ -1,6 +1,8 @@
-# Content Classification Labels API
-
-Content Classification Labels (CCL) are used to categorize streams based on their content. These labels help viewers make informed decisions about the content they watch.
+---
+layout: default
+title: Content Classification Labels API
+description: Content Classification Labels (CCL) are used to categorize streams based on their content. These labels help viewers make informed decisions about the content they watch.
+---
 
 ## GetContentClassificationLabels
 
@@ -61,3 +63,4 @@ for _, label := range resp.Data {
   ]
 }
 ```
+
diff --git a/docs/channel-points.md b/docs/channel-points.md
index 9ad934f..5a6d26a 100644
--- a/docs/channel-points.md
+++ b/docs/channel-points.md
@@ -1,6 +1,8 @@
-# Channel Points API
-
-Manage custom Channel Points rewards and redemptions.
+---
+layout: default
+title: Channel Points API
+description: Manage custom Channel Points rewards and redemptions.
+---
 
 ## GetCustomRewards
 
@@ -387,3 +389,4 @@ for _, redemption := range resp.Data {
   ]
 }
 ```
+
diff --git a/docs/channels.md b/docs/channels.md
index 11adeed..61f4743 100644
--- a/docs/channels.md
+++ b/docs/channels.md
@@ -1,6 +1,8 @@
-# Channels API
-
-Retrieve and manage Twitch channel information, followers, editors, and VIPs.
+---
+layout: default
+title: Channels API
+description: Retrieve and manage Twitch channel information, followers, editors, and VIPs.
+---
 
 ## GetChannelInformation
 
@@ -281,5 +283,5 @@ if err != nil {
 ```json
 {}
 ```
-
 Note: This endpoint returns no content on success (204 No Content).
+
diff --git a/docs/charity.md b/docs/charity.md
index 931fc73..42dc843 100644
--- a/docs/charity.md
+++ b/docs/charity.md
@@ -1,6 +1,8 @@
-# Charity API
-
-Manage charity campaigns and donations for Twitch channels.
+---
+layout: default
+title: Charity API
+description: Manage charity campaigns and donations for Twitch channels.
+---
 
 ## GetCharityCampaign
 
@@ -119,3 +121,4 @@ if resp.Pagination.Cursor != "" {
   }
 }
 ```
+
diff --git a/docs/chat.md b/docs/chat.md
index 29dffae..21a1115 100644
--- a/docs/chat.md
+++ b/docs/chat.md
@@ -1,6 +1,8 @@
-# Chat API
-
-Manage chat rooms, emotes, badges, settings, and send messages to Twitch channels.
+---
+layout: default
+title: Chat API
+description: Manage chat rooms, emotes, badges, settings, and send messages to Twitch channels.
+---
 
 ## GetChatters
 
@@ -744,3 +746,4 @@ for _, emote := range resp.Data {
   }
 }
 ```
+
diff --git a/docs/clips.md b/docs/clips.md
index 452b9b4..d0a0d94 100644
--- a/docs/clips.md
+++ b/docs/clips.md
@@ -1,6 +1,8 @@
-# Clips API
-
-Create and retrieve Twitch clips from broadcasts and VODs.
+---
+layout: default
+title: Clips API
+description: Create and retrieve Twitch clips from broadcasts and VODs.
+---
 
 ## CreateClip
 
@@ -264,3 +266,4 @@ for _, clip := range resp.Data {
   ]
 }
 ```
+
diff --git a/docs/conduits.md b/docs/conduits.md
index c6784f0..6f28e44 100644
--- a/docs/conduits.md
+++ b/docs/conduits.md
@@ -1,6 +1,8 @@
-# EventSub Conduits API
-
-Manage EventSub conduits for receiving event notifications. Conduits allow you to manage multiple shards for high-availability event subscriptions.
+---
+layout: default
+title: EventSub Conduits API
+description: Manage EventSub conduits for receiving event notifications. Conduits allow you to manage multiple shards for high-availability event subscriptions.
+---
 
 ## GetConduits
 
@@ -304,3 +306,4 @@ for _, shard := range resp.Data {
   ]
 }
 ```
+
diff --git a/docs/cookbook.md b/docs/cookbook.md
new file mode 100644
index 0000000..9b039e8
--- /dev/null
+++ b/docs/cookbook.md
@@ -0,0 +1,82 @@
+---
+layout: default
+title: Cookbook
+description: Comprehensive code examples covering all kappopher features.
+---
+
+## Getting Started
+
+- [Basic Usage](examples/basic.md) - Simple API calls, pagination, and error handling
+
+## Authentication
+
+- [Authentication](examples/authentication.md) - All OAuth 2.0 flows (client credentials, authorization code, device code, implicit, token refresh, OIDC)
+
+## Chat & Real-Time
+
+- [Chat Bot](examples/chatbot.md) - Building a chat bot with EventSub
+- [IRC Client](examples/irc-client.md) - Low-level IRC/WebSocket chat client
+
+## EventSub
+
+- [EventSub Webhooks](examples/eventsub-webhooks.md) - Handle webhook notifications with signature verification
+- [EventSub WebSocket](examples/eventsub-websocket.md) - Real-time event streaming without a public endpoint
+- [PubSub Migration](examples/pubsub-migration.md) - PubSub-style API using EventSub
+
+## API Usage
+
+- [API Usage Examples](examples/api-usage.md) - Common API patterns for users, channels, streams, chat, moderation, polls, predictions, and clips
+- [Channel Points](examples/channel-points.md) - Custom rewards, redemptions, real-time tracking
+- [Bits & Subscriptions](examples/bits-subscriptions.md) - Bits leaderboard, cheermotes, subscriber management
+- [Videos & Clips](examples/videos-clips.md) - VODs, highlights, clips, stream markers
+- [Schedule & Goals](examples/schedule-goals.md) - Stream schedule management, creator goals
+- [Raids & Hype Train](examples/raids-hypetrain.md) - Channel raids, hype train tracking
+- [Analytics & Charity](examples/analytics-charity.md) - Extension/game analytics, charity campaigns, teams, guest star, conduits
+
+## Advanced
+
+- [Batch & Caching](examples/batch-caching.md) - Batch operations, caching, rate limiting, middleware
+- [Extension JWT](examples/extension-jwt.md) - JWT authentication for Twitch Extensions
+
+## Quick Reference
+
+### By Feature
+
+| Feature | Example |
+|---------|---------|
+| OAuth Authentication | [Authentication](examples/authentication.md) |
+| Get Users/Channels | [Basic](examples/basic.md), [API Usage](examples/api-usage.md) |
+| Send Chat Messages | [Chat Bot](examples/chatbot.md), [IRC Client](examples/irc-client.md) |
+| Handle Chat Events | [IRC Client](examples/irc-client.md), [EventSub WebSocket](examples/eventsub-websocket.md) |
+| Moderation | [Chat Bot](examples/chatbot.md), [API Usage](examples/api-usage.md) |
+| Channel Points | [Channel Points](examples/channel-points.md) |
+| Bits | [Bits & Subscriptions](examples/bits-subscriptions.md) |
+| Subscriptions | [Bits & Subscriptions](examples/bits-subscriptions.md) |
+| Stream Schedule | [Schedule & Goals](examples/schedule-goals.md) |
+| Creator Goals | [Schedule & Goals](examples/schedule-goals.md) |
+| Raids | [Raids & Hype Train](examples/raids-hypetrain.md) |
+| Hype Train | [Raids & Hype Train](examples/raids-hypetrain.md) |
+| Clips | [Videos & Clips](examples/videos-clips.md) |
+| Videos/VODs | [Videos & Clips](examples/videos-clips.md) |
+| Polls & Predictions | [API Usage](examples/api-usage.md) |
+| EventSub WebSocket | [EventSub WebSocket](examples/eventsub-websocket.md) |
+| EventSub Webhooks | [EventSub Webhooks](examples/eventsub-webhooks.md) |
+| Batch Requests | [Batch & Caching](examples/batch-caching.md) |
+| Caching | [Batch & Caching](examples/batch-caching.md) |
+| Middleware | [Batch & Caching](examples/batch-caching.md) |
+| Extensions | [Extension JWT](examples/extension-jwt.md) |
+| Analytics | [Analytics & Charity](examples/analytics-charity.md) |
+| Charity | [Analytics & Charity](examples/analytics-charity.md) |
+
+### By Use Case
+
+| Use Case | Start Here |
+|----------|-----------|
+| Build a chat bot | [Chat Bot](examples/chatbot.md) or [IRC Client](examples/irc-client.md) |
+| Monitor stream events | [EventSub WebSocket](examples/eventsub-websocket.md) |
+| Create a dashboard | [Batch & Caching](examples/batch-caching.md) |
+| Manage channel points | [Channel Points](examples/channel-points.md) |
+| Track subscriptions | [Bits & Subscriptions](examples/bits-subscriptions.md) |
+| Server-side integration | [EventSub Webhooks](examples/eventsub-webhooks.md) |
+| Build an extension | [Extension JWT](examples/extension-jwt.md) |
+| Migrate from PubSub | [PubSub Migration](examples/pubsub-migration.md) |
diff --git a/docs/entitlements.md b/docs/entitlements.md
index 3cb47cd..7414cab 100644
--- a/docs/entitlements.md
+++ b/docs/entitlements.md
@@ -1,6 +1,8 @@
-# Drops Entitlements API
-
-Manage Twitch Drops entitlements for games and viewers.
+---
+layout: default
+title: Drops Entitlements API
+description: Manage Twitch Drops entitlements for games and viewers.
+---
 
 ## GetDropsEntitlements
 
@@ -154,3 +156,4 @@ for _, status := range resp.Data {
 - `NOT_FOUND`: The entitlement was not found
 - `UNAUTHORIZED`: The app or user is not authorized to update this entitlement
 - `UPDATE_FAILED`: The update failed for an unknown reason
+
diff --git a/docs/eventsub.md b/docs/eventsub.md
index 65067de..f236947 100644
--- a/docs/eventsub.md
+++ b/docs/eventsub.md
@@ -1,6 +1,8 @@
-# EventSub API
-
-Manage Twitch EventSub subscriptions for real-time event notifications.
+---
+layout: default
+title: EventSub API
+description: Manage Twitch EventSub subscriptions for real-time event notifications.
+---
 
 ## GetEventSubSubscriptions
 
@@ -266,3 +268,161 @@ This allows existing code using `IsGoldenKappaTrain` to continue working while y
 ### User Events
 
 - `EventSubTypeUserUpdate` - User profile updated
+
+## Helper Functions
+
+These convenience functions simplify common EventSub operations.
+
+### Condition Builders
+
+Build condition maps for EventSub subscriptions:
+
+```go
+// For channel events (broadcaster_user_id)
+cond := helix.BroadcasterCondition("12345")
+// Returns: map[string]string{"broadcaster_user_id": "12345"}
+
+// For events requiring moderator (follows v2, chat settings, etc.)
+cond := helix.BroadcasterModeratorCondition("12345", "67890")
+// Returns: map[string]string{"broadcaster_user_id": "12345", "moderator_user_id": "67890"}
+
+// For user events (user_id)
+cond := helix.UserCondition("12345")
+// Returns: map[string]string{"user_id": "12345"}
+
+// For channel points with optional reward filter
+cond := helix.ChannelPointsCondition("12345", "reward-uuid")
+// Returns: map[string]string{"broadcaster_user_id": "12345", "reward_id": "reward-uuid"}
+```
+
+### SubscribeToChannel
+
+Subscribe to channel events with automatic version selection.
+
+```go
+transport := helix.CreateEventSubTransport{
+    Method:    "websocket",
+    SessionID: wsClient.SessionID(),
+}
+
+// Subscribe to stream online events
+sub, err := client.SubscribeToChannel(ctx, helix.EventSubTypeStreamOnline, "12345", transport)
+if err != nil {
+    log.Fatal(err)
+}
+fmt.Printf("Subscribed: %s\n", sub.ID)
+
+// Subscribe to raid events
+sub, err = client.SubscribeToChannel(ctx, helix.EventSubTypeChannelRaid, "12345", transport)
+```
+
+### SubscribeToChannelWithModerator
+
+Subscribe to channel events that require moderator authorization (e.g., follows v2, chat settings).
+
+```go
+transport := helix.CreateEventSubTransport{
+    Method:    "websocket",
+    SessionID: wsClient.SessionID(),
+}
+
+// Subscribe to follow events (requires moderator)
+sub, err := client.SubscribeToChannelWithModerator(ctx,
+    helix.EventSubTypeChannelFollow,
+    "12345",  // broadcaster ID
+    "67890",  // moderator ID (often same as broadcaster)
+    transport,
+)
+
+// Subscribe to chat settings updates
+sub, err = client.SubscribeToChannelWithModerator(ctx,
+    helix.EventSubTypeChannelChatSettingsUpdate,
+    "12345",
+    "67890",
+    transport,
+)
+```
+
+### SubscribeToUser
+
+Subscribe to user-specific events.
+
+```go
+transport := helix.CreateEventSubTransport{
+    Method:    "websocket",
+    SessionID: wsClient.SessionID(),
+}
+
+// Subscribe to user update events
+sub, err := client.SubscribeToUser(ctx, helix.EventSubTypeUserUpdate, "12345", transport)
+
+// Subscribe to whisper events
+sub, err = client.SubscribeToUser(ctx, helix.EventSubTypeWhisperReceived, "12345", transport)
+```
+
+### GetAllSubscriptions
+
+Retrieve all EventSub subscriptions with automatic pagination.
+
+```go
+// Get all subscriptions
+subs, err := client.GetAllSubscriptions(ctx, nil)
+if err != nil {
+    log.Fatal(err)
+}
+fmt.Printf("Total subscriptions: %d\n", len(subs))
+
+// Get all enabled subscriptions
+subs, err = client.GetAllSubscriptions(ctx, &helix.GetEventSubSubscriptionsParams{
+    Status: "enabled",
+})
+
+// Get all subscriptions of a specific type
+subs, err = client.GetAllSubscriptions(ctx, &helix.GetEventSubSubscriptionsParams{
+    Type: helix.EventSubTypeStreamOnline,
+})
+
+// Get all subscriptions for a user
+subs, err = client.GetAllSubscriptions(ctx, &helix.GetEventSubSubscriptionsParams{
+    UserID: "12345",
+})
+```
+
+### DeleteAllSubscriptions
+
+Delete all EventSub subscriptions matching a filter.
+
+```go
+// Delete all subscriptions (use with caution!)
+deleted, err := client.DeleteAllSubscriptions(ctx, nil)
+if err != nil {
+    log.Fatal(err)
+}
+fmt.Printf("Deleted %d subscriptions\n", deleted)
+
+// Delete all subscriptions of a specific type
+deleted, err = client.DeleteAllSubscriptions(ctx, &helix.GetEventSubSubscriptionsParams{
+    Type: helix.EventSubTypeStreamOnline,
+})
+
+// Delete all failed subscriptions
+deleted, err = client.DeleteAllSubscriptions(ctx, &helix.GetEventSubSubscriptionsParams{
+    Status: "webhook_callback_verification_failed",
+})
+```
+
+### GetEventSubVersion
+
+Get the current default version for an EventSub subscription type.
+
+```go
+version := helix.GetEventSubVersion(helix.EventSubTypeChannelFollow)
+// Returns "2" for channel.follow
+
+version = helix.GetEventSubVersion(helix.EventSubTypeChannelHypeTrainBegin)
+// Returns "2" for hype train events (v1 deprecated)
+
+version = helix.GetEventSubVersion(helix.EventSubTypeStreamOnline)
+// Returns "1" for most events
+```
+
diff --git a/docs/examples/README.md b/docs/examples/README.md
index ad94026..62f0459 100644
--- a/docs/examples/README.md
+++ b/docs/examples/README.md
@@ -1,26 +1,83 @@
 # Examples
 
-Code examples for common use cases.
+Comprehensive code examples covering all kappopher features.
 
 ## Getting Started
 
-- [Quick Start Guide](../quickstart.md) - Installation, authentication, and basic setup
+- [Quick Start Guide](quickstart.md) - Installation, authentication, and basic setup
 - [Basic Usage](basic.md) - Simple API calls, pagination, and error handling
 
-## Bots
+## Authentication
 
-- [Chat Bot](chatbot.md) - Building a chat bot with commands, moderation, and announcements
+- [Authentication](authentication.md) - All OAuth 2.0 flows (client credentials, authorization code, device code, implicit, token refresh, OIDC)
 
-## API Usage
+## Chat & Real-Time
 
-- [API Usage Examples](api-usage.md) - Common API patterns for users, channels, streams, chat, moderation, polls, predictions, and clips
+- [Chat Bot](chatbot.md) - Building a chat bot with EventSub
+- [IRC Client](Projects/Programming/Kappopher/Documents/examples/irc-client.md) - Low-level IRC/WebSocket chat client
 
 ## EventSub
 
 - [EventSub Webhooks](eventsub-webhooks.md) - Handle webhook notifications with signature verification
 - [EventSub WebSocket](eventsub-websocket.md) - Real-time event streaming without a public endpoint
-- [PubSub Migration](pubsub-migration.md) - PubSub-style API using EventSub (for migration from deprecated PubSub)
+- [PubSub Migration](pubsub-migration.md) - PubSub-style API using EventSub
+
+## API Usage
+
+- [API Usage Examples](api-usage.md) - Common API patterns for users, channels, streams, chat, moderation, polls, predictions, and clips
+- [Channel Points](Projects/Programming/Kappopher/Documents/examples/channel-points.md) - Custom rewards, redemptions, real-time tracking
+- [Bits & Subscriptions](bits-subscriptions.md) - Bits leaderboard, cheermotes, subscriber management
+- [Videos & Clips](videos-clips.md) - VODs, highlights, clips, stream markers
+- [Schedule & Goals](schedule-goals.md) - Stream schedule management, creator goals
+- [Raids & Hype Train](raids-hypetrain.md) - Channel raids, hype train tracking
+- [Analytics & Charity](analytics-charity.md) - Extension/game analytics, charity campaigns, teams, guest star, conduits
+
+## Advanced
+
+- [Batch & Caching](batch-caching.md) - Batch operations, caching, rate limiting, middleware
+- [Extension JWT](Projects/Programming/Kappopher/Documents/examples/extension-jwt.md) - JWT authentication for Twitch Extensions
+
+## Quick Reference
+
+### By Feature
+
+| Feature | Example File |
+|---------|-------------|
+| OAuth Authentication | [authentication.md](authentication.md) |
+| Get Users/Channels | [basic.md](basic.md), [api-usage.md](api-usage.md) |
+| Send Chat Messages | [chatbot.md](chatbot.md), [irc-client.md](Projects/Programming/Kappopher/Documents/examples/irc-client.md) |
+| Handle Chat Events | [irc-client.md](Projects/Programming/Kappopher/Documents/examples/irc-client.md), [eventsub-websocket.md](eventsub-websocket.md) |
+| Moderation | [chatbot.md](chatbot.md), [api-usage.md](api-usage.md) |
+| Channel Points | [channel-points.md](Projects/Programming/Kappopher/Documents/examples/channel-points.md) |
+| Bits | [bits-subscriptions.md](bits-subscriptions.md) |
+| Subscriptions | [bits-subscriptions.md](bits-subscriptions.md) |
+| Stream Schedule | [schedule-goals.md](schedule-goals.md) |
+| Creator Goals | [schedule-goals.md](schedule-goals.md) |
+| Raids | [raids-hypetrain.md](raids-hypetrain.md) |
+| Hype Train | [raids-hypetrain.md](raids-hypetrain.md) |
+| Clips | [videos-clips.md](videos-clips.md) |
+| Videos/VODs | [videos-clips.md](videos-clips.md) |
+| Polls & Predictions | [api-usage.md](api-usage.md) |
+| EventSub WebSocket | [eventsub-websocket.md](eventsub-websocket.md) |
+| EventSub Webhooks | [eventsub-webhooks.md](eventsub-webhooks.md) |
+| Batch Requests | [batch-caching.md](batch-caching.md) |
+| Caching | [batch-caching.md](batch-caching.md) |
+| Middleware | [batch-caching.md](batch-caching.md) |
+| Extensions | [extension-jwt.md](Projects/Programming/Kappopher/Documents/examples/extension-jwt.md) |
+| Analytics | [analytics-charity.md](analytics-charity.md) |
+| Charity | [analytics-charity.md](analytics-charity.md) |
+| Teams | [analytics-charity.md](analytics-charity.md) |
+| Conduits | [analytics-charity.md](analytics-charity.md) |
 
-## Extensions
+### By Use Case
 
-- [Extension JWT](extension-jwt.md) - JWT authentication for Twitch Extensions
+| Use Case | Start Here |
+|----------|-----------|
+| Build a chat bot | [chatbot.md](chatbot.md) or [irc-client.md](Projects/Programming/Kappopher/Documents/examples/irc-client.md) |
+| Monitor stream events | [eventsub-websocket.md](eventsub-websocket.md) |
+| Create a dashboard | [batch-caching.md](batch-caching.md) |
+| Manage channel points | [channel-points.md](Projects/Programming/Kappopher/Documents/examples/channel-points.md) |
+| Track subscriptions | [bits-subscriptions.md](bits-subscriptions.md) |
+| Server-side integration | [eventsub-webhooks.md](eventsub-webhooks.md) |
+| Build an extension | [extension-jwt.md](Projects/Programming/Kappopher/Documents/examples/extension-jwt.md) |
+| Migrate from PubSub | [pubsub-migration.md](pubsub-migration.md) |
diff --git a/docs/examples/analytics-charity.md b/docs/examples/analytics-charity.md
new file mode 100644
index 0000000..7f4939f
--- /dev/null
+++ b/docs/examples/analytics-charity.md
@@ -0,0 +1,619 @@
+---
+layout: default
+title: Analytics, Charity & Miscellaneous Examples
+description: Extension analytics, game analytics, charity campaigns, teams, and more.
+---
+
+## Overview
+
+This guide covers various specialized Twitch features:
+
+**Analytics**: View performance data for extensions and games you own
+- Extension usage statistics and reports
+- Game viewership analytics
+
+**Charity Campaigns**: Support charitable giving through your channel
+- View current campaign progress
+- Track donations in real-time via EventSub
+
+**Teams**: Groups of streamers who collaborate together
+- View team membership and details
+- Get team rosters
+
+**Additional Features**:
+- Guest Star: Bring guests onto your stream
+- Content Classification Labels: View available content labels
+- Ingest Servers: Get streaming server endpoints
+- Drops Entitlements: Manage game drops
+- Conduits: Manage EventSub at scale
+
+## Prerequisites
+
+- **Analytics:** `analytics:read:extensions` or `analytics:read:games`
+- **Charity:** `channel:read:charity`
+- **Teams:** No scope needed (public data)
+- **Guest Star:** `channel:read:guest_star` or `channel:manage:guest_star`
+
+## Extension Analytics
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    // Get extension analytics
+    analytics, err := client.GetExtensionAnalytics(ctx, &helix.GetExtensionAnalyticsParams{
+        First: 20,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("=== Extension Analytics ===")
+    for _, ext := range analytics.Data {
+        fmt.Printf("\nExtension ID: %s\n", ext.ExtensionID)
+        fmt.Printf("  Type: %s\n", ext.Type)
+        fmt.Printf("  Date Range: %s to %s\n", ext.DateRange.StartedAt, ext.DateRange.EndedAt)
+        fmt.Printf("  Report URL: %s\n", ext.URL)
+    }
+
+    // Get analytics for specific extension
+    extAnalytics, err := client.GetExtensionAnalytics(ctx, &helix.GetExtensionAnalyticsParams{
+        ExtensionID: "extension-id",
+    })
+
+    // Get analytics for a time period
+    startTime := time.Now().AddDate(0, -1, 0) // 1 month ago
+    endTime := time.Now()
+    periodAnalytics, err := client.GetExtensionAnalytics(ctx, &helix.GetExtensionAnalyticsParams{
+        StartedAt: &startTime,
+        EndedAt:   &endTime,
+        Type:      "overview_v2",
+    })
+}
+```
+
+## Game Analytics
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    // Get game analytics (for games you own)
+    analytics, err := client.GetGameAnalytics(ctx, &helix.GetGameAnalyticsParams{
+        First: 20,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("=== Game Analytics ===")
+    for _, game := range analytics.Data {
+        fmt.Printf("\nGame ID: %s\n", game.GameID)
+        fmt.Printf("  Type: %s\n", game.Type)
+        fmt.Printf("  Date Range: %s to %s\n", game.DateRange.StartedAt, game.DateRange.EndedAt)
+        fmt.Printf("  Report URL: %s\n", game.URL)
+    }
+
+    // Get analytics for specific game
+    gameAnalytics, err := client.GetGameAnalytics(ctx, &helix.GetGameAnalyticsParams{
+        GameID: "game-id",
+    })
+
+    // Get analytics for a time period
+    startTime := time.Now().AddDate(0, 0, -7) // Last week
+    endTime := time.Now()
+    weeklyAnalytics, err := client.GetGameAnalytics(ctx, &helix.GetGameAnalyticsParams{
+        GameID:    "game-id",
+        StartedAt: &startTime,
+        EndedAt:   &endTime,
+    })
+}
+```
+
+## Charity Campaigns
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Get current charity campaign
+    campaign, err := client.GetCharityCampaign(ctx, broadcasterID)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    if len(campaign.Data) == 0 {
+        fmt.Println("No active charity campaign")
+        return
+    }
+
+    c := campaign.Data[0]
+    fmt.Printf("=== Charity Campaign ===\n")
+    fmt.Printf("Charity: %s\n", c.CharityName)
+    fmt.Printf("Description: %s\n", c.CharityDescription)
+    fmt.Printf("Website: %s\n", c.CharityWebsite)
+    fmt.Printf("Logo: %s\n", c.CharityLogo)
+    fmt.Printf("\nCurrent Amount: %d %s\n", c.CurrentAmount.Value, c.CurrentAmount.Currency)
+    fmt.Printf("Target Amount: %d %s\n", c.TargetAmount.Value, c.TargetAmount.Currency)
+
+    progress := float64(c.CurrentAmount.Value) / float64(c.TargetAmount.Value) * 100
+    fmt.Printf("Progress: %.1f%%\n", progress)
+
+    // Get charity donations
+    donations, err := client.GetCharityCampaignDonations(ctx, &helix.GetCharityCampaignDonationsParams{
+        BroadcasterID: broadcasterID,
+        First:         20,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("\n=== Recent Donations ===\n")
+    for _, d := range donations.Data {
+        fmt.Printf("%s donated %d %s\n", d.UserName, d.Amount.Value, d.Amount.Currency)
+    }
+}
+```
+
+## Track Charity Events with EventSub
+
+```go
+package main
+
+import (
+    "context"
+    "encoding/json"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    ws := helix.NewEventSubWebSocket(client)
+    if err := ws.Connect(ctx); err != nil {
+        log.Fatal(err)
+    }
+    defer ws.Close()
+
+    // Subscribe to charity donations
+    ws.Subscribe(ctx, helix.EventSubTypeCharityDonation, "1",
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.CharityDonationEvent](event)
+            fmt.Printf("💝 %s donated %d %s to %s!\n",
+                e.UserName, e.Amount.Value, e.Amount.Currency, e.CharityName)
+        },
+    )
+
+    // Subscribe to campaign start
+    ws.Subscribe(ctx, helix.EventSubTypeCharityCampaignStart, "1",
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.CharityCampaignEvent](event)
+            fmt.Printf("🎗️ Charity campaign started for %s!\n", e.CharityName)
+            fmt.Printf("   Goal: %d %s\n", e.TargetAmount.Value, e.TargetAmount.Currency)
+        },
+    )
+
+    // Subscribe to campaign progress
+    ws.Subscribe(ctx, helix.EventSubTypeCharityCampaignProgress, "1",
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.CharityCampaignEvent](event)
+            progress := float64(e.CurrentAmount.Value) / float64(e.TargetAmount.Value) * 100
+            fmt.Printf("📊 Campaign progress: %d/%d %s (%.1f%%)\n",
+                e.CurrentAmount.Value, e.TargetAmount.Value, e.CurrentAmount.Currency, progress)
+        },
+    )
+
+    // Subscribe to campaign end
+    ws.Subscribe(ctx, helix.EventSubTypeCharityCampaignStop, "1",
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.CharityCampaignEvent](event)
+            fmt.Printf("🎉 Charity campaign ended!\n")
+            fmt.Printf("   Final amount: %d %s\n", e.CurrentAmount.Value, e.CurrentAmount.Currency)
+        },
+    )
+
+    fmt.Println("Listening for charity events...")
+    select {}
+}
+```
+
+## Teams
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    // Get teams a channel belongs to
+    channelTeams, err := client.GetChannelTeams(ctx, "broadcaster-id")
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("=== Channel Teams ===")
+    for _, team := range channelTeams.Data {
+        fmt.Printf("\n%s\n", team.TeamDisplayName)
+        fmt.Printf("  ID: %s\n", team.ID)
+        fmt.Printf("  Name: %s\n", team.TeamName)
+        fmt.Printf("  Info: %s\n", team.Info)
+        fmt.Printf("  Created: %s\n", team.CreatedAt)
+    }
+
+    // Get team details by ID
+    teamByID, err := client.GetTeams(ctx, &helix.GetTeamsParams{
+        ID: "team-id",
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    if len(teamByID.Data) > 0 {
+        team := teamByID.Data[0]
+        fmt.Printf("\n=== Team: %s ===\n", team.TeamDisplayName)
+        fmt.Printf("Members: %d\n", len(team.Users))
+        for _, user := range team.Users {
+            fmt.Printf("  - %s\n", user.UserName)
+        }
+    }
+
+    // Get team by name
+    teamByName, err := client.GetTeams(ctx, &helix.GetTeamsParams{
+        Name: "team-name",
+    })
+}
+```
+
+## Guest Star
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Get Guest Star channel settings
+    settings, err := client.GetChannelGuestStarSettings(ctx, broadcasterID, broadcasterID)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("=== Guest Star Settings ===")
+    fmt.Printf("Enabled: %v\n", settings.Data.IsModeratorSendLiveEnabled)
+    fmt.Printf("Group Layout: %s\n", settings.Data.GroupLayout)
+    fmt.Printf("Regenerate Browser Sources: %v\n", settings.Data.BrowserSourceToken)
+
+    // Get Guest Star session
+    session, err := client.GetGuestStarSession(ctx, broadcasterID, broadcasterID)
+    if err != nil {
+        // No active session
+        fmt.Println("No active Guest Star session")
+    } else {
+        fmt.Printf("\n=== Active Session ===\n")
+        fmt.Printf("ID: %s\n", session.Data[0].ID)
+        fmt.Printf("Guests:\n")
+        for _, guest := range session.Data[0].Guests {
+            fmt.Printf("  - %s (Slot: %s)\n", guest.UserDisplayName, guest.SlotID)
+        }
+    }
+
+    // Get Guest Star invites
+    invites, err := client.GetGuestStarInvites(ctx, broadcasterID, broadcasterID, "session-id")
+    if err == nil {
+        fmt.Printf("\n=== Pending Invites ===\n")
+        for _, invite := range invites.Data {
+            fmt.Printf("  - %s (Invited: %s)\n", invite.UserDisplayName, invite.InvitedAt)
+        }
+    }
+}
+```
+
+## Content Classification Labels
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    // Get all content classification labels
+    labels, err := client.GetContentClassificationLabels(ctx, "en") // locale
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("=== Content Classification Labels ===")
+    for _, label := range labels.Data {
+        fmt.Printf("\n%s (%s)\n", label.Name, label.ID)
+        fmt.Printf("  Description: %s\n", label.Description)
+    }
+}
+```
+
+## Ingest Servers
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    // Get ingest servers
+    servers, err := client.GetIngestServers(ctx)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("=== Ingest Servers ===")
+    for _, server := range servers.Ingests {
+        fmt.Printf("\n%s\n", server.Name)
+        fmt.Printf("  URL Template: %s\n", server.URLTemplate)
+        fmt.Printf("  Default: %v\n", server.Default)
+        fmt.Printf("  Availability: %.2f\n", server.Availability)
+        fmt.Printf("  Priority: %d\n", server.Priority)
+    }
+}
+```
+
+## Drops Entitlements
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    // Get drops entitlements
+    entitlements, err := client.GetDropsEntitlements(ctx, &helix.GetDropsEntitlementsParams{
+        First: 20,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("=== Drops Entitlements ===")
+    for _, ent := range entitlements.Data {
+        fmt.Printf("\nEntitlement: %s\n", ent.ID)
+        fmt.Printf("  User: %s\n", ent.UserID)
+        fmt.Printf("  Game: %s\n", ent.GameID)
+        fmt.Printf("  Benefit: %s\n", ent.BenefitID)
+        fmt.Printf("  Status: %s\n", ent.FulfillmentStatus)
+        fmt.Printf("  Timestamp: %s\n", ent.Timestamp)
+    }
+
+    // Get entitlements for specific user
+    userEntitlements, err := client.GetDropsEntitlements(ctx, &helix.GetDropsEntitlementsParams{
+        UserID: "user-id",
+    })
+
+    // Get entitlements for specific game
+    gameEntitlements, err := client.GetDropsEntitlements(ctx, &helix.GetDropsEntitlementsParams{
+        GameID: "game-id",
+    })
+
+    // Update entitlement fulfillment status
+    updated, err := client.UpdateDropsEntitlements(ctx, &helix.UpdateDropsEntitlementsParams{
+        EntitlementIDs:    []string{"entitlement-id-1", "entitlement-id-2"},
+        FulfillmentStatus: "FULFILLED",
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+    fmt.Printf("Updated %d entitlements\n", len(updated.Data))
+}
+```
+
+## Conduits (EventSub)
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    // Create a conduit
+    conduit, err := client.CreateConduit(ctx, 5) // 5 shards
+    if err != nil {
+        log.Fatal(err)
+    }
+    fmt.Printf("Created conduit: %s with %d shards\n", conduit.Data[0].ID, conduit.Data[0].ShardCount)
+
+    // Get conduits
+    conduits, err := client.GetConduits(ctx)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("\n=== Conduits ===")
+    for _, c := range conduits.Data {
+        fmt.Printf("ID: %s, Shards: %d\n", c.ID, c.ShardCount)
+    }
+
+    // Get conduit shards
+    shards, err := client.GetConduitShards(ctx, &helix.GetConduitShardsParams{
+        ConduitID: conduit.Data[0].ID,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("\n=== Shards for %s ===\n", conduit.Data[0].ID)
+    for _, shard := range shards.Data {
+        fmt.Printf("Shard %s: Status=%s\n", shard.ID, shard.Status)
+    }
+
+    // Update conduit shards
+    _, err = client.UpdateConduitShards(ctx, &helix.UpdateConduitShardsParams{
+        ConduitID: conduit.Data[0].ID,
+        Shards: []helix.ConduitShardUpdate{
+            {
+                ID: "0",
+                Transport: helix.ConduitShardTransport{
+                    Method:   "websocket",
+                    SessionID: "websocket-session-id",
+                },
+            },
+        },
+    })
+
+    // Delete conduit
+    err = client.DeleteConduit(ctx, conduit.Data[0].ID)
+    if err != nil {
+        log.Printf("Failed to delete conduit: %v", err)
+    }
+}
+```
+
diff --git a/docs/examples/api-usage.md b/docs/examples/api-usage.md
index ea13b6d..f1aa289 100644
--- a/docs/examples/api-usage.md
+++ b/docs/examples/api-usage.md
@@ -1,9 +1,20 @@
-# API Usage Examples
+---
+layout: default
+title: API Usage Examples
+description: Quick reference for common Twitch Helix API operations. These snippets show the most frequently used endpoints organized by category.
+---
 
-Common API usage patterns and examples.
+For complete examples with error handling and setup, see [Basic Usage](basic.md).
 
 ## Users
 
+User operations for fetching profiles, managing blocks, and getting the authenticated user's information.
+
+**Scopes required**:
+- `GetUsers`: None (public data)
+- `GetCurrentUser`: `user:read:email` (optional, for email)
+- `BlockUser`/`UnblockUser`: `user:manage:blocked_users`
+
 ```go
 // Get users by ID or login
 users, _ := client.GetUsers(ctx, &helix.GetUsersParams{
@@ -21,6 +32,13 @@ client.UnblockUser(ctx, "12345")
 
 ## Channels
 
+Retrieve and modify channel information, and access follower data.
+
+**Scopes required**:
+- `GetChannelInformation`: None (public data)
+- `ModifyChannelInformation`: `channel:manage:broadcast`
+- `GetChannelFollowers`: `moderator:read:followers` (for follower details)
+
 ```go
 // Get channel information
 channels, _ := client.GetChannelInformation(ctx, &helix.GetChannelInformationParams{
@@ -42,6 +60,13 @@ followers, _ := client.GetChannelFollowers(ctx, &helix.GetChannelFollowersParams
 
 ## Streams
 
+Access live stream data, stream keys, and create markers for VOD highlights.
+
+**Scopes required**:
+- `GetStreams`: None (public data)
+- `GetStreamKey`: `channel:read:stream_key`
+- `CreateStreamMarker`: `channel:manage:broadcast`
+
 ```go
 // Get live streams
 streams, _ := client.GetStreams(ctx, &helix.GetStreamsParams{
@@ -60,6 +85,13 @@ marker, _ := client.CreateStreamMarker(ctx, &helix.CreateStreamMarkerParams{
 
 ## Chat
 
+Send messages, announcements, and manage chat settings. For real-time chat events, see [EventSub WebSocket](eventsub-websocket.md) or [IRC Client](Projects/Programming/Kappopher/Documents/examples/irc-client.md).
+
+**Scopes required**:
+- `SendChatMessage`: `user:write:chat`
+- `SendChatAnnouncement`: `moderator:manage:announcements`
+- `UpdateChatSettings`: `moderator:manage:chat_settings`
+
 ```go
 // Send chat message
 resp, _ := client.SendChatMessage(ctx, &helix.SendChatMessageParams{
@@ -88,6 +120,15 @@ client.UpdateChatSettings(ctx, &helix.UpdateChatSettingsParams{
 
 ## Moderation
 
+Ban/timeout users, manage the ban list, and control channel moderators.
+
+**Scopes required**:
+- `BanUser`/`UnbanUser`: `moderator:manage:banned_users`
+- `GetBannedUsers`: `moderation:read`
+- `AddChannelModerator`/`RemoveChannelModerator`: `channel:manage:moderators`
+
+**Note**: Duration of 0 means permanent ban; any positive value is a timeout in seconds.
+
 ```go
 // Ban user
 client.BanUser(ctx, &helix.BanUserParams{
@@ -115,6 +156,14 @@ client.RemoveChannelModerator(ctx, "12345", "mod-id")
 
 ## Polls & Predictions
 
+Create interactive polls and channel point predictions for viewer engagement.
+
+**Scopes required**:
+- `CreatePoll`/`EndPoll`: `channel:manage:polls`
+- `CreatePrediction`/`EndPrediction`: `channel:manage:predictions`
+
+**Limitations**: Polls can have 2-5 choices; predictions always have exactly 2 outcomes. Duration is in seconds.
+
 ```go
 // Create poll
 poll, _ := client.CreatePoll(ctx, &helix.CreatePollParams{
@@ -141,6 +190,14 @@ prediction, _ := client.CreatePrediction(ctx, &helix.CreatePredictionParams{
 
 ## Clips
 
+Create clips from live streams and retrieve existing clips. For more clip operations including VOD clips, see [Videos & Clips](videos-clips.md).
+
+**Scopes required**:
+- `CreateClip`: `clips:edit`
+- `GetClips`: None (public data)
+
+**Note**: Clip creation requires the stream to be live. The clip captures approximately 30 seconds of content.
+
 ```go
 // Create clip
 clip, _ := client.CreateClip(ctx, &helix.CreateClipParams{
@@ -164,3 +221,4 @@ helix.CommonScopes.Moderation  // Moderation tools
 helix.CommonScopes.Channel     // Channel management
 helix.CommonScopes.Broadcaster // Full broadcaster access
 ```
+
diff --git a/docs/examples/authentication.md b/docs/examples/authentication.md
new file mode 100644
index 0000000..f24d1bd
--- /dev/null
+++ b/docs/examples/authentication.md
@@ -0,0 +1,478 @@
+---
+layout: default
+title: Authentication Examples
+description: Complete examples for all OAuth 2.0 authentication flows supported by the Twitch API.
+---
+
+## Overview
+
+Twitch uses OAuth 2.0 for authentication. The flow you choose depends on your application type:
+
+| Flow | Use Case | User Interaction | Token Type |
+|------|----------|------------------|------------|
+| **Client Credentials** | Server-side apps, public data | None | App Access Token |
+| **Authorization Code** | Web apps with backend | Browser redirect | User Access Token |
+| **Device Code** | CLIs, TVs, IoT devices | Code on separate device | User Access Token |
+| **Implicit Grant** | Single-page apps (SPAs) | Browser redirect | User Access Token |
+
+**Key Concepts**:
+- **App Access Tokens**: Identify your application, used for public API endpoints
+- **User Access Tokens**: Identify a specific user, required for user-specific data and actions
+- **Scopes**: Define what permissions your app requests (e.g., `chat:read`, `channel:manage:redemptions`)
+- **Refresh Tokens**: Used to get new access tokens without re-authenticating the user
+
+## Client Credentials Flow (App Access Token)
+
+Use this flow for server-to-server API calls that don't require user authorization. This is the simplest flow - your server exchanges its client credentials directly for an access token.
+
+**When to use**: Fetching public data like user profiles, live streams, or game information.
+
+**Limitations**: Cannot access user-specific data or perform actions on behalf of a user.
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+
+    // Get app access token
+    token, err := authClient.GetAppAccessToken(ctx)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("Access Token: %s\n", token.AccessToken)
+    fmt.Printf("Expires In: %d seconds\n", token.ExpiresIn)
+    fmt.Printf("Token Type: %s\n", token.TokenType)
+
+    // Create Helix client with app token
+    client := helix.NewClient("your-client-id", authClient)
+
+    // Now make API calls (limited to endpoints that accept app tokens)
+    users, _ := client.GetUsers(ctx, &helix.GetUsersParams{
+        Logins: []string{"twitchdev"},
+    })
+    fmt.Printf("User: %s\n", users.Data[0].DisplayName)
+}
+```
+
+## Authorization Code Flow (User Access Token)
+
+The most common flow for web applications. The user is redirected to Twitch to authorize your app, then redirected back with an authorization code that you exchange for tokens.
+
+**How it works**:
+1. Generate an authorization URL with requested scopes and a CSRF state token
+2. Redirect user to Twitch to authorize your application
+3. User approves, Twitch redirects back with an authorization code
+4. Your server exchanges the code for access and refresh tokens
+
+**Security**: Always validate the `state` parameter to prevent CSRF attacks. The state should be a cryptographically random string stored in the user's session.
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "net/http"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+        RedirectURI:  "http://localhost:3000/callback",
+        Scopes: []string{
+            helix.ScopeUserReadEmail,
+            helix.ScopeChatRead,
+            helix.ScopeChatEdit,
+        },
+    })
+
+    // Generate authorization URL with CSRF state
+    state := "random-csrf-token"
+    url := authClient.GetCodeAuthURLWithState(state)
+    fmt.Printf("Open this URL in your browser:\n%s\n\n", url)
+
+    // Handle the OAuth callback
+    var authCode string
+    http.HandleFunc("/callback", func(w http.ResponseWriter, r *http.Request) {
+        // Verify state to prevent CSRF
+        if r.URL.Query().Get("state") != state {
+            http.Error(w, "Invalid state", http.StatusBadRequest)
+            return
+        }
+
+        authCode = r.URL.Query().Get("code")
+        fmt.Fprintf(w, "Authorization successful! You can close this window.")
+
+        // Exchange code for token
+        token, err := authClient.ExchangeCode(ctx, authCode)
+        if err != nil {
+            log.Printf("Token exchange failed: %v", err)
+            return
+        }
+
+        fmt.Printf("\nAccess Token: %s\n", token.AccessToken)
+        fmt.Printf("Refresh Token: %s\n", token.RefreshToken)
+        fmt.Printf("Scopes: %v\n", token.Scope)
+    })
+
+    log.Fatal(http.ListenAndServe(":3000", nil))
+}
+```
+
+## Device Code Flow
+
+Designed for devices that don't have a browser or have limited input capabilities (smart TVs, game consoles, CLI tools). The user authorizes on a separate device (like their phone) by entering a code.
+
+**How it works**:
+1. Request a device code and user code from Twitch
+2. Display the user code and verification URL to the user
+3. User visits the URL on another device and enters the code
+4. Your app polls for the token until authorization completes or times out
+
+**User experience**: The user sees something like "Go to twitch.tv/activate and enter code: ABCD-1234"
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID: "your-client-id",
+        Scopes: []string{
+            helix.ScopeUserReadEmail,
+            helix.ScopeChatRead,
+        },
+    })
+
+    // Request device code
+    deviceCode, err := authClient.GetDeviceCode(ctx)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("Go to: %s\n", deviceCode.VerificationURI)
+    fmt.Printf("Enter code: %s\n", deviceCode.UserCode)
+    fmt.Printf("Expires in: %d seconds\n", deviceCode.ExpiresIn)
+
+    // Poll for token (blocks until user authorizes or timeout)
+    token, err := authClient.WaitForDeviceToken(ctx, deviceCode)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("\nAuthorization successful!\n")
+    fmt.Printf("Access Token: %s\n", token.AccessToken)
+}
+```
+
+## Implicit Grant Flow
+
+For client-side JavaScript applications (SPAs) where the client secret cannot be kept confidential. The access token is returned directly in the URL fragment.
+
+**Important limitations**:
+- No refresh tokens - user must re-authorize when token expires
+- Token is exposed in browser history and potentially to JavaScript on the page
+- Consider using Authorization Code Flow with PKCE for better security
+
+**When to use**: Legacy SPAs or simple browser extensions where you can't use a backend server.
+
+```go
+package main
+
+import (
+    "fmt"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:    "your-client-id",
+        RedirectURI: "http://localhost:3000/callback",
+        Scopes: []string{
+            helix.ScopeUserReadEmail,
+        },
+    })
+
+    // Generate implicit auth URL
+    // Token will be in the URL fragment after redirect
+    state := "random-csrf-token"
+    url := authClient.GetImplicitAuthURLWithState(state)
+    fmt.Printf("Redirect user to:\n%s\n", url)
+
+    // After redirect, extract token from URL fragment:
+    // http://localhost:3000/callback#access_token=xxx&token_type=bearer&scope=user:read:email
+}
+```
+
+## Token Refresh
+
+User access tokens expire (typically after 4 hours). Use the refresh token to get a new access token without requiring the user to re-authorize.
+
+**Important**: Refresh tokens can also expire or be revoked. Always handle refresh failures by falling back to re-authentication.
+
+**Best practice**: Store refresh tokens securely (encrypted in database) and update them after each refresh, as Twitch may issue new refresh tokens.
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+
+    // Refresh an expired token
+    refreshToken := "stored-refresh-token"
+    newToken, err := authClient.RefreshToken(ctx, refreshToken)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("New Access Token: %s\n", newToken.AccessToken)
+    fmt.Printf("New Refresh Token: %s\n", newToken.RefreshToken)
+
+    // Store the new refresh token for future use
+}
+```
+
+## Token Validation
+
+Verify that a token is still valid and retrieve information about it. This is useful for checking token status before making API calls, or for getting the user ID associated with a token.
+
+**Returns**: Client ID, user ID (for user tokens), login name, granted scopes, and time until expiration.
+
+**When to use**: On app startup to check stored tokens, or periodically to ensure tokens haven't been revoked.
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID: "your-client-id",
+    })
+
+    token := "access-token-to-validate"
+    validation, err := authClient.ValidateToken(ctx, token)
+    if err != nil {
+        log.Printf("Token is invalid: %v", err)
+        return
+    }
+
+    fmt.Printf("Client ID: %s\n", validation.ClientID)
+    fmt.Printf("User ID: %s\n", validation.UserID)
+    fmt.Printf("Login: %s\n", validation.Login)
+    fmt.Printf("Scopes: %v\n", validation.Scopes)
+    fmt.Printf("Expires In: %d seconds\n", validation.ExpiresIn)
+}
+```
+
+## Token Revocation
+
+Invalidate a token so it can no longer be used. This is important for security when users log out of your application.
+
+**When to use**: User logout, account deletion, or when you detect suspicious activity.
+
+**Note**: Revoking an access token also invalidates its associated refresh token.
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID: "your-client-id",
+    })
+
+    token := "token-to-revoke"
+    err := authClient.RevokeToken(ctx, token)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("Token revoked successfully")
+}
+```
+
+## Automatic Token Refresh
+
+For long-running applications, you can set up automatic token refresh to ensure your tokens never expire during operation. The library will refresh tokens before they expire and notify you via a callback.
+
+**How it works**: The auto-refresh mechanism monitors token expiration and refreshes proactively (before expiry). The callback lets you persist the new tokens.
+
+**Use case**: Bots, dashboards, or any service that runs continuously.
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+
+    // Set initial token
+    authClient.SetToken(&helix.TokenResponse{
+        AccessToken:  "current-access-token",
+        RefreshToken: "current-refresh-token",
+        ExpiresIn:    3600,
+    })
+
+    // Start automatic refresh (refreshes when token is near expiry)
+    stopRefresh := authClient.StartAutoRefresh(ctx, func(token *helix.TokenResponse, err error) {
+        if err != nil {
+            log.Printf("Auto-refresh failed: %v", err)
+            return
+        }
+        fmt.Printf("Token auto-refreshed at %s\n", time.Now().Format(time.RFC3339))
+        // Store new token in database
+    })
+
+    // Stop auto-refresh when done
+    defer stopRefresh()
+
+    // Your application runs here...
+    select {}
+}
+```
+
+## OpenID Connect (OIDC)
+
+OIDC extends OAuth 2.0 to provide identity verification. When you request the `openid` scope, you can retrieve verified user information like email address and profile picture.
+
+**When to use**: User registration/login where you need verified identity information rather than just authorization.
+
+**Required scope**: `openid` (optionally with `user:read:email` for email access)
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+        RedirectURI:  "http://localhost:3000/callback",
+        Scopes: []string{
+            helix.ScopeOpenID,
+            helix.ScopeUserReadEmail,
+        },
+    })
+
+    // After getting an access token with openid scope...
+    // Get user info from OIDC endpoint
+    userInfo, err := authClient.GetOIDCUserInfo(ctx)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("Subject (User ID): %s\n", userInfo.Sub)
+    fmt.Printf("Preferred Username: %s\n", userInfo.PreferredUsername)
+    fmt.Printf("Email: %s\n", userInfo.Email)
+    fmt.Printf("Email Verified: %v\n", userInfo.EmailVerified)
+    fmt.Printf("Picture: %s\n", userInfo.Picture)
+}
+```
+
+## Common Scope Combinations
+
+The library provides pre-defined scope combinations for common use cases. These help you request the right permissions without having to look up individual scope names.
+
+**Principle of least privilege**: Only request the scopes you actually need. Users are more likely to authorize apps that request minimal permissions.
+
+```go
+// Chat bot scopes
+helix.CommonScopes.Chat // chat:read, chat:edit
+
+// Full bot functionality
+helix.CommonScopes.Bot // chat scopes + whispers, user read
+
+// Moderation tools
+helix.CommonScopes.Moderation // ban, manage messages, automod, etc.
+
+// Channel management
+helix.CommonScopes.Channel // channel:manage:*, channel:read:*
+
+// Full broadcaster access
+helix.CommonScopes.Broadcaster // all broadcaster-level scopes
+```
+
diff --git a/docs/examples/basic.md b/docs/examples/basic.md
index b9977a5..e68ce0d 100644
--- a/docs/examples/basic.md
+++ b/docs/examples/basic.md
@@ -1,9 +1,32 @@
-# Basic Usage
+---
+layout: default
+title: Basic Usage
+description: Simple examples for getting started with the Twitch Helix API.
+---
 
-Simple examples for getting started with the Twitch Helix API.
+## Overview
+
+This guide covers the fundamental operations you'll need when working with the Twitch Helix API:
+
+- **Authentication**: Obtain an app access token using client credentials
+- **User Operations**: Fetch user information by username or ID
+- **Stream Data**: Check if channels are live and get stream details
+- **Channel Information**: Retrieve channel metadata like title and game
+- **Search**: Find channels and games/categories
+- **Pagination**: Handle large result sets efficiently
+- **Error Handling**: Properly handle API errors and edge cases
+
+These examples use app access tokens (client credentials flow), which are suitable for public data that doesn't require user authorization. For user-specific data, see the [Authentication Examples](authentication.md).
 
 ## Setup
 
+Before making any API calls, you need to:
+1. Create an `AuthClient` with your Twitch application credentials
+2. Obtain an access token (app token for public data, user token for private data)
+3. Create a `Client` instance that handles all API requests
+
+The `AuthClient` manages token acquisition, refresh, and storage. The `Client` uses the `AuthClient` to automatically attach authorization headers to requests.
+
 ```go
 package main
 
@@ -12,26 +35,28 @@ import (
     "fmt"
     "log"
 
-    "github.com/Its-donkey/helix/helix"
+    "github.com/Its-donkey/kappopher/helix"
 )
 
 func main() {
     ctx := context.Background()
 
-    // Create auth client
+    // Create auth client with your Twitch Developer Console credentials
     authClient := helix.NewAuthClient(helix.AuthConfig{
         ClientID:     "your-client-id",
         ClientSecret: "your-client-secret",
     })
 
-    // Get app access token
+    // Get app access token - this authenticates your application
+    // App tokens are used for public data that doesn't require user authorization
     token, err := authClient.GetAppAccessToken(ctx)
     if err != nil {
         log.Fatal(err)
     }
     fmt.Printf("Token expires in: %d seconds\n", token.ExpiresIn)
 
-    // Create Helix client
+    // Create Helix client - this is your main interface to the Twitch API
+    // The client automatically uses the auth client for token management
     client := helix.NewClient("your-client-id", authClient)
 
     // Now you can make API calls
@@ -41,6 +66,10 @@ func main() {
 
 ## Get User Information
 
+Retrieve detailed information about Twitch users. You can look up users by their login name (username) or by their numeric user ID. This is often the first API call you'll make since many other endpoints require user IDs.
+
+**What you get**: Display name, profile image URL, account creation date, broadcaster type (affiliate/partner), and more.
+
 ```go
 // Get user by login name
 users, err := client.GetUsers(ctx, &helix.GetUsersParams{
@@ -61,6 +90,12 @@ for _, user := range users.Data {
 
 ## Get Live Streams
 
+Check if specific channels are currently live and retrieve stream metadata. This is useful for building stream directories, notifications, or checking stream status before performing stream-specific operations.
+
+**What you get**: Stream title, game/category, viewer count, start time, thumbnail URL, and tags.
+
+**Note**: The API only returns data for streams that are currently live. If a channel is offline, it won't appear in the results.
+
 ```go
 // Get live streams for specific users
 streams, err := client.GetStreams(ctx, &helix.GetStreamsParams{
@@ -84,6 +119,12 @@ if len(streams.Data) == 0 {
 
 ## Get Channel Information
 
+Retrieve channel metadata that persists even when the stream is offline. Unlike stream data which only exists during a live broadcast, channel information is always available.
+
+**What you get**: Current stream title, game/category, language, tags, and content classification labels.
+
+**Use case**: Display channel info on a profile page, or check what game a streamer typically plays.
+
 ```go
 channels, err := client.GetChannelInformation(ctx, &helix.GetChannelInformationParams{
     BroadcasterIDs: []string{"12345"},
@@ -102,6 +143,10 @@ for _, channel := range channels.Data {
 
 ## Search for Channels
 
+Search for channels by keyword. Results include both live and offline channels, with live channels prioritized. The `IsLive` field indicates current broadcast status.
+
+**Use case**: Build a search feature for finding streamers, or discover channels in specific categories.
+
 ```go
 results, err := client.SearchChannels(ctx, &helix.SearchChannelsParams{
     Query: "programming",
@@ -123,6 +168,10 @@ for _, channel := range results.Data {
 
 ## Search for Games/Categories
 
+Search for games and categories by name. This returns the game ID which is required for many other API calls (filtering streams by game, getting game analytics, etc.).
+
+**Use case**: Autocomplete for game selection, or find the correct game ID for filtering.
+
 ```go
 games, err := client.SearchCategories(ctx, &helix.SearchCategoriesParams{
     Query: "minecraft",
@@ -139,6 +188,10 @@ for _, game := range games.Data {
 
 ## Get Top Games
 
+Retrieve the most popular games/categories on Twitch right now, ranked by current viewer count. This data updates in real-time.
+
+**Use case**: Build a "Browse" page showing trending categories, or display popular games for discovery.
+
 ```go
 topGames, err := client.GetTopGames(ctx, &helix.GetTopGamesParams{
     First: 10,
@@ -155,6 +208,16 @@ for i, game := range topGames.Data {
 
 ## Pagination Example
 
+Most Twitch API endpoints return paginated results. The `First` parameter controls how many results per page (max 100 for most endpoints), and the `Pagination.Cursor` in the response tells you where to continue.
+
+**How it works**:
+1. Make initial request with `First` set to your page size
+2. Check if `Pagination.Cursor` exists in the response
+3. If it exists, make another request with `After` set to the cursor
+4. Repeat until no cursor is returned
+
+**Note**: For large datasets (like all followers of a popular channel), consider implementing rate limiting and storing results incrementally to avoid memory issues.
+
 ```go
 var allFollowers []helix.ChannelFollower
 cursor := ""
@@ -183,6 +246,16 @@ fmt.Printf("Total followers: %d\n", len(allFollowers))
 
 ## Error Handling
 
+The library returns `*helix.APIError` for HTTP errors from the Twitch API. This allows you to inspect the status code and error message to handle different error conditions appropriately.
+
+**Common error codes**:
+- `401 Unauthorized`: Token expired or invalid - refresh or re-authenticate
+- `404 Not Found`: Resource doesn't exist (but note: `GetUsers` returns empty data, not 404, for non-existent users)
+- `429 Too Many Requests`: Rate limited - wait before retrying
+- `500+`: Server errors - retry with exponential backoff
+
+**Important**: Some endpoints return empty results instead of errors for "not found" cases. Always check both the error and the result data length.
+
 ```go
 users, err := client.GetUsers(ctx, &helix.GetUsersParams{
     Logins: []string{"nonexistent_user_12345"},
@@ -208,3 +281,4 @@ if len(users.Data) == 0 {
     fmt.Println("User not found")
 }
 ```
+
diff --git a/docs/examples/batch-caching.md b/docs/examples/batch-caching.md
new file mode 100644
index 0000000..17fd251
--- /dev/null
+++ b/docs/examples/batch-caching.md
@@ -0,0 +1,690 @@
+---
+layout: default
+title: Batch Operations & Caching Examples
+description: Efficient API usage with batch requests, caching, rate limiting, and middleware.
+---
+
+## Overview
+
+When building applications that make many API calls, optimization is essential to stay within rate limits and provide responsive experiences.
+
+**Batch Requests**: Execute multiple operations efficiently
+- `Batch`: Concurrent requests for maximum throughput
+- `BatchGet`: Concurrent with built-in rate limiting
+- `BatchSequential`: Sequential execution for ordered operations
+- `BatchWithCallback`: Progress tracking for large operations
+
+**Caching**: Reduce redundant API calls
+- In-memory cache with configurable TTL
+- Cache key isolation for multi-tenant apps
+- Manual invalidation when needed
+
+**Rate Limiting**: Stay within Twitch's limits (800 requests/minute)
+- Automatic tracking via response headers
+- Wait functions for graceful handling
+
+**Middleware**: Extend client functionality
+- Logging, retries, metrics, custom headers
+- Chainable for complex behaviors
+
+## Batch Requests
+
+Execute multiple API calls concurrently for maximum throughput:
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    // Batch get users (concurrent requests)
+    userLogins := []string{"user1", "user2", "user3", "user4", "user5"}
+
+    results, err := helix.Batch(ctx, userLogins, func(ctx context.Context, login string) (*helix.GetUsersResponse, error) {
+        return client.GetUsers(ctx, &helix.GetUsersParams{
+            Logins: []string{login},
+        })
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    for i, result := range results {
+        if result.Error != nil {
+            fmt.Printf("Failed to get user %s: %v\n", userLogins[i], result.Error)
+            continue
+        }
+        if len(result.Value.Data) > 0 {
+            fmt.Printf("User: %s (ID: %s)\n", result.Value.Data[0].DisplayName, result.Value.Data[0].ID)
+        }
+    }
+}
+```
+
+## BatchGet with Built-in Rate Limiting
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    // Get multiple channel information with automatic rate limiting
+    broadcasterIDs := []string{"12345", "67890", "11111", "22222", "33333"}
+
+    results, err := helix.BatchGet(ctx, client, broadcasterIDs,
+        func(ctx context.Context, client *helix.Client, id string) (*helix.GetChannelInformationResponse, error) {
+            return client.GetChannelInformation(ctx, &helix.GetChannelInformationParams{
+                BroadcasterIDs: []string{id},
+            })
+        },
+    )
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    for _, result := range results {
+        if result.Error != nil {
+            fmt.Printf("Error: %v\n", result.Error)
+            continue
+        }
+        if len(result.Value.Data) > 0 {
+            ch := result.Value.Data[0]
+            fmt.Printf("Channel: %s - %s\n", ch.BroadcasterName, ch.Title)
+        }
+    }
+}
+```
+
+## Sequential Batch (Rate Limited)
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    // Process sequentially (useful when order matters or for heavy operations)
+    userIDs := []string{"12345", "67890", "11111"}
+
+    results, err := helix.BatchSequential(ctx, userIDs, func(ctx context.Context, id string) (*helix.GetUsersResponse, error) {
+        return client.GetUsers(ctx, &helix.GetUsersParams{
+            IDs: []string{id},
+        })
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    for _, result := range results {
+        if result.Error == nil && len(result.Value.Data) > 0 {
+            fmt.Printf("User: %s\n", result.Value.Data[0].DisplayName)
+        }
+    }
+}
+```
+
+## Batch with Callback
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "sync/atomic"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    userIDs := make([]string, 100)
+    for i := range userIDs {
+        userIDs[i] = fmt.Sprintf("%d", 10000+i)
+    }
+
+    var processed int64
+
+    // Process with progress callback
+    err := helix.BatchWithCallback(ctx, userIDs,
+        func(ctx context.Context, id string) (*helix.GetUsersResponse, error) {
+            return client.GetUsers(ctx, &helix.GetUsersParams{
+                IDs: []string{id},
+            })
+        },
+        func(input string, result *helix.GetUsersResponse, err error) {
+            atomic.AddInt64(&processed, 1)
+            current := atomic.LoadInt64(&processed)
+            if current%10 == 0 {
+                fmt.Printf("Progress: %d/%d\n", current, len(userIDs))
+            }
+        },
+    )
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("Processed %d users\n", processed)
+}
+```
+
+## Caching Setup
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+
+    // Create client with caching enabled
+    cache := helix.NewMemoryCache(5 * time.Minute) // 5 minute TTL
+    client := helix.NewClient("your-client-id", authClient,
+        helix.WithCache(cache),
+    )
+
+    // First request - hits API
+    start := time.Now()
+    users1, _ := client.GetUsers(ctx, &helix.GetUsersParams{
+        Logins: []string{"twitchdev"},
+    })
+    fmt.Printf("First request: %v (API call)\n", time.Since(start))
+
+    // Second request - hits cache
+    start = time.Now()
+    users2, _ := client.GetUsers(ctx, &helix.GetUsersParams{
+        Logins: []string{"twitchdev"},
+    })
+    fmt.Printf("Second request: %v (cached)\n", time.Since(start))
+
+    fmt.Printf("Same data: %v\n", users1.Data[0].ID == users2.Data[0].ID)
+
+    // Invalidate cache for specific endpoint
+    client.InvalidateCache(ctx, "users")
+
+    // Third request - hits API again
+    start = time.Now()
+    _, _ = client.GetUsers(ctx, &helix.GetUsersParams{
+        Logins: []string{"twitchdev"},
+    })
+    fmt.Printf("Third request: %v (API call after invalidation)\n", time.Since(start))
+}
+```
+
+## Custom Cache Implementation
+
+```go
+package main
+
+import (
+    "context"
+    "sync"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+// RedisCache implements helix.Cache using Redis
+type RedisCache struct {
+    // Add your Redis client here
+    mu sync.RWMutex
+    data map[string]cacheEntry
+}
+
+type cacheEntry struct {
+    value     []byte
+    expiresAt time.Time
+}
+
+func NewRedisCache() *RedisCache {
+    return &RedisCache{
+        data: make(map[string]cacheEntry),
+    }
+}
+
+func (c *RedisCache) Get(ctx context.Context, key string) ([]byte, bool) {
+    c.mu.RLock()
+    defer c.mu.RUnlock()
+
+    entry, ok := c.data[key]
+    if !ok || time.Now().After(entry.expiresAt) {
+        return nil, false
+    }
+    return entry.value, true
+}
+
+func (c *RedisCache) Set(ctx context.Context, key string, value []byte, ttl time.Duration) {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+
+    c.data[key] = cacheEntry{
+        value:     value,
+        expiresAt: time.Now().Add(ttl),
+    }
+}
+
+func (c *RedisCache) Delete(ctx context.Context, key string) {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+    delete(c.data, key)
+}
+
+func main() {
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+
+    cache := NewRedisCache()
+    client := helix.NewClient("your-client-id", authClient,
+        helix.WithCache(cache),
+        helix.WithCacheTTL(10*time.Minute),
+    )
+
+    // Use client normally - caching is automatic
+    _ = client
+}
+```
+
+## Cache Key Isolation
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // Generate cache key with context isolation
+    // This prevents cache collisions between different tokens/environments
+    key := helix.CacheKeyWithContext("users", "https://api.twitch.tv", "access-token-123")
+    fmt.Printf("Cache key: %s\n", key)
+
+    // Generate token hash for cache isolation
+    hash := helix.TokenHash("access-token-123")
+    fmt.Printf("Token hash: %s\n", hash)
+
+    // Invalidate cache with context
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID: "your-client-id",
+    })
+    cache := helix.NewMemoryCache(5 * time.Minute)
+    client := helix.NewClient("your-client-id", authClient, helix.WithCache(cache))
+
+    client.InvalidateCacheWithContext(ctx, "users")
+}
+```
+
+## Rate Limiting
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    // Make a request
+    _, _ = client.GetUsers(ctx, &helix.GetUsersParams{
+        Logins: []string{"twitchdev"},
+    })
+
+    // Check rate limit status
+    rateLimit := client.GetRateLimitInfo()
+    fmt.Printf("Rate Limit: %d/%d\n", rateLimit.Remaining, rateLimit.Limit)
+    fmt.Printf("Resets at: %s\n", rateLimit.Reset.Format(time.RFC3339))
+
+    // Wait if rate limited
+    if rateLimit.Remaining < 10 {
+        waitTime := client.WaitForRateLimit(ctx)
+        if waitTime > 0 {
+            fmt.Printf("Rate limited, waiting %v\n", waitTime)
+            time.Sleep(waitTime)
+        }
+    }
+
+    // Continue making requests...
+}
+```
+
+## Middleware
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "net/http"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+// LoggingMiddleware logs all API requests
+func LoggingMiddleware(next helix.RoundTripper) helix.RoundTripper {
+    return helix.RoundTripperFunc(func(req *http.Request) (*http.Response, error) {
+        start := time.Now()
+        log.Printf("→ %s %s", req.Method, req.URL.Path)
+
+        resp, err := next.RoundTrip(req)
+
+        duration := time.Since(start)
+        if err != nil {
+            log.Printf("← ERROR: %v (%v)", err, duration)
+        } else {
+            log.Printf("← %d %s (%v)", resp.StatusCode, resp.Status, duration)
+        }
+
+        return resp, err
+    })
+}
+
+// RetryMiddleware retries failed requests
+func RetryMiddleware(maxRetries int) helix.Middleware {
+    return func(next helix.RoundTripper) helix.RoundTripper {
+        return helix.RoundTripperFunc(func(req *http.Request) (*http.Response, error) {
+            var resp *http.Response
+            var err error
+
+            for i := 0; i <= maxRetries; i++ {
+                resp, err = next.RoundTrip(req)
+                if err == nil && resp.StatusCode < 500 {
+                    return resp, nil
+                }
+
+                if i < maxRetries {
+                    time.Sleep(time.Duration(i+1) * time.Second)
+                    log.Printf("Retrying request (attempt %d/%d)", i+2, maxRetries+1)
+                }
+            }
+
+            return resp, err
+        })
+    }
+}
+
+// MetricsMiddleware tracks request metrics
+type Metrics struct {
+    TotalRequests int64
+    Errors        int64
+    TotalLatency  time.Duration
+}
+
+func MetricsMiddleware(metrics *Metrics) helix.Middleware {
+    return func(next helix.RoundTripper) helix.RoundTripper {
+        return helix.RoundTripperFunc(func(req *http.Request) (*http.Response, error) {
+            start := time.Now()
+            metrics.TotalRequests++
+
+            resp, err := next.RoundTrip(req)
+
+            metrics.TotalLatency += time.Since(start)
+            if err != nil || (resp != nil && resp.StatusCode >= 400) {
+                metrics.Errors++
+            }
+
+            return resp, err
+        })
+    }
+}
+
+func main() {
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+
+    metrics := &Metrics{}
+
+    // Create client with middleware stack
+    client := helix.NewClient("your-client-id", authClient,
+        helix.WithMiddleware(LoggingMiddleware),
+        helix.WithMiddleware(RetryMiddleware(3)),
+        helix.WithMiddleware(MetricsMiddleware(metrics)),
+    )
+
+    ctx := context.Background()
+
+    // Make some requests
+    for i := 0; i < 5; i++ {
+        _, _ = client.GetUsers(ctx, &helix.GetUsersParams{
+            Logins: []string{"twitchdev"},
+        })
+    }
+
+    // Print metrics
+    fmt.Printf("\n=== Metrics ===\n")
+    fmt.Printf("Total Requests: %d\n", metrics.TotalRequests)
+    fmt.Printf("Errors: %d\n", metrics.Errors)
+    fmt.Printf("Average Latency: %v\n", metrics.TotalLatency/time.Duration(metrics.TotalRequests))
+}
+```
+
+## Complete Example: Efficient Multi-Channel Dashboard
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "sync"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+type ChannelData struct {
+    User    *helix.User
+    Channel *helix.ChannelInformation
+    Stream  *helix.Stream
+}
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    _, _ = authClient.GetAppAccessToken(ctx)
+
+    // Setup client with caching
+    cache := helix.NewMemoryCache(1 * time.Minute)
+    client := helix.NewClient("your-client-id", authClient,
+        helix.WithCache(cache),
+    )
+
+    // Channels to monitor
+    channels := []string{"streamer1", "streamer2", "streamer3", "streamer4", "streamer5"}
+
+    // Fetch all data concurrently
+    channelData := make(map[string]*ChannelData)
+    var mu sync.Mutex
+
+    // Get users
+    userResults, _ := helix.Batch(ctx, channels, func(ctx context.Context, login string) (*helix.GetUsersResponse, error) {
+        return client.GetUsers(ctx, &helix.GetUsersParams{Logins: []string{login}})
+    })
+
+    for i, result := range userResults {
+        if result.Error == nil && len(result.Value.Data) > 0 {
+            mu.Lock()
+            channelData[channels[i]] = &ChannelData{User: &result.Value.Data[0]}
+            mu.Unlock()
+        }
+    }
+
+    // Get user IDs for next requests
+    var userIDs []string
+    for _, login := range channels {
+        if data, ok := channelData[login]; ok && data.User != nil {
+            userIDs = append(userIDs, data.User.ID)
+        }
+    }
+
+    // Get channel info and streams concurrently
+    var wg sync.WaitGroup
+    wg.Add(2)
+
+    go func() {
+        defer wg.Done()
+        channelResults, _ := helix.Batch(ctx, userIDs, func(ctx context.Context, id string) (*helix.GetChannelInformationResponse, error) {
+            return client.GetChannelInformation(ctx, &helix.GetChannelInformationParams{BroadcasterIDs: []string{id}})
+        })
+        for i, result := range channelResults {
+            if result.Error == nil && len(result.Value.Data) > 0 {
+                mu.Lock()
+                for _, data := range channelData {
+                    if data.User != nil && data.User.ID == userIDs[i] {
+                        data.Channel = &result.Value.Data[0]
+                        break
+                    }
+                }
+                mu.Unlock()
+            }
+        }
+    }()
+
+    go func() {
+        defer wg.Done()
+        streams, _ := client.GetStreams(ctx, &helix.GetStreamsParams{UserIDs: userIDs})
+        mu.Lock()
+        for _, stream := range streams.Data {
+            for _, data := range channelData {
+                if data.User != nil && data.User.ID == stream.UserID {
+                    s := stream // Copy
+                    data.Stream = &s
+                    break
+                }
+            }
+        }
+        mu.Unlock()
+    }()
+
+    wg.Wait()
+
+    // Display dashboard
+    fmt.Println("=== Channel Dashboard ===\n")
+    for login, data := range channelData {
+        if data.User == nil {
+            fmt.Printf("❌ %s: Not found\n", login)
+            continue
+        }
+
+        status := "⚫ Offline"
+        viewers := 0
+        if data.Stream != nil {
+            status = "🔴 LIVE"
+            viewers = data.Stream.ViewerCount
+        }
+
+        title := "N/A"
+        game := "N/A"
+        if data.Channel != nil {
+            title = data.Channel.Title
+            game = data.Channel.GameName
+        }
+
+        fmt.Printf("%s %s\n", status, data.User.DisplayName)
+        fmt.Printf("   Title: %s\n", title)
+        fmt.Printf("   Game: %s\n", game)
+        if viewers > 0 {
+            fmt.Printf("   Viewers: %d\n", viewers)
+        }
+        fmt.Println()
+    }
+
+    // Show rate limit status
+    rateLimit := client.GetRateLimitInfo()
+    fmt.Printf("Rate Limit: %d/%d remaining\n", rateLimit.Remaining, rateLimit.Limit)
+}
+```
+
diff --git a/docs/examples/bits-subscriptions.md b/docs/examples/bits-subscriptions.md
new file mode 100644
index 0000000..2e7a8c3
--- /dev/null
+++ b/docs/examples/bits-subscriptions.md
@@ -0,0 +1,444 @@
+---
+layout: default
+title: Bits & Subscriptions Examples
+description: Work with Bits leaderboards, cheermotes, and channel subscriptions.
+---
+
+## Overview
+
+This guide covers two monetization features for Twitch channels:
+
+**Bits**: Virtual currency viewers use to "cheer" in chat
+- View bits leaderboards (top cheerers)
+- Get cheermote images for different bit amounts
+- React to cheer events in real-time
+
+**Subscriptions**: Recurring monthly support from viewers
+- Get subscriber list with tier information
+- Check if specific users are subscribed
+- React to new subscriptions, gift subs, and resubs in real-time
+
+## Prerequisites
+
+- **Bits:** `bits:read` scope for leaderboard
+- **Subscriptions:** `channel:read:subscriptions` scope
+
+## Bits Leaderboard
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // Setup client
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Get all-time bits leaderboard
+    leaderboard, err := client.GetBitsLeaderboard(ctx, &helix.GetBitsLeaderboardParams{
+        Count: 10,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("=== All-Time Bits Leaderboard ===")
+    fmt.Printf("Period: %s to %s\n", leaderboard.DateRange.StartedAt, leaderboard.DateRange.EndedAt)
+    fmt.Printf("Total: %d\n\n", leaderboard.Total)
+
+    for _, entry := range leaderboard.Data {
+        fmt.Printf("%d. %s - %d bits\n", entry.Rank, entry.UserName, entry.Score)
+    }
+
+    // Get weekly leaderboard
+    weeklyLeaderboard, err := client.GetBitsLeaderboard(ctx, &helix.GetBitsLeaderboardParams{
+        Period: "week",
+        Count:  10,
+    })
+
+    // Get monthly leaderboard
+    monthlyLeaderboard, err := client.GetBitsLeaderboard(ctx, &helix.GetBitsLeaderboardParams{
+        Period: "month",
+        Count:  10,
+    })
+
+    // Get leaderboard for a specific time period
+    startTime := time.Now().AddDate(0, -1, 0) // 1 month ago
+    customLeaderboard, err := client.GetBitsLeaderboard(ctx, &helix.GetBitsLeaderboardParams{
+        Period:    "all",
+        StartedAt: startTime,
+        Count:     25,
+    })
+
+    // Get specific user's rank
+    userLeaderboard, err := client.GetBitsLeaderboard(ctx, &helix.GetBitsLeaderboardParams{
+        UserID: "user-id",
+    })
+    if len(userLeaderboard.Data) > 0 {
+        fmt.Printf("User rank: %d with %d bits\n",
+            userLeaderboard.Data[0].Rank, userLeaderboard.Data[0].Score)
+    }
+}
+```
+
+## Cheermotes
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // Setup client
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    // Get global cheermotes
+    globalCheermotes, err := client.GetCheermotes(ctx, &helix.GetCheermotesParams{})
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("=== Global Cheermotes ===")
+    for _, cheermote := range globalCheermotes.Data {
+        fmt.Printf("Prefix: %s (Type: %s)\n", cheermote.Prefix, cheermote.Type)
+        fmt.Printf("  Tiers: ")
+        for _, tier := range cheermote.Tiers {
+            fmt.Printf("%d+ ", tier.MinBits)
+        }
+        fmt.Println()
+    }
+
+    // Get channel-specific cheermotes
+    channelCheermotes, err := client.GetCheermotes(ctx, &helix.GetCheermotesParams{
+        BroadcasterID: "12345",
+    })
+
+    // Find cheermote URLs for different tiers
+    for _, cheermote := range channelCheermotes.Data {
+        if cheermote.Prefix == "Cheer" {
+            for _, tier := range cheermote.Tiers {
+                fmt.Printf("Cheer%d: %s\n", tier.MinBits, tier.Images.Dark.Animated["1"])
+            }
+        }
+    }
+}
+```
+
+## Handle Bits with EventSub
+
+```go
+package main
+
+import (
+    "context"
+    "encoding/json"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // Setup clients
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Create WebSocket client
+    ws := helix.NewEventSubWebSocket(client)
+    if err := ws.Connect(ctx); err != nil {
+        log.Fatal(err)
+    }
+    defer ws.Close()
+
+    // Subscribe to bits events
+    ws.Subscribe(ctx, helix.EventSubTypeChannelCheer, "1",
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.ChannelCheerEvent](event)
+            handleCheer(e)
+        },
+    )
+
+    fmt.Println("Listening for bits...")
+    select {}
+}
+
+func handleCheer(e *helix.ChannelCheerEvent) {
+    fmt.Printf("=== CHEER ===\n")
+    fmt.Printf("From: %s\n", e.UserName)
+    fmt.Printf("Bits: %d\n", e.Bits)
+    fmt.Printf("Message: %s\n", e.Message)
+    fmt.Printf("Anonymous: %v\n", e.IsAnonymous)
+
+    // Trigger actions based on bits amount
+    switch {
+    case e.Bits >= 10000:
+        fmt.Println("MEGA CHEER! Playing special alert...")
+    case e.Bits >= 1000:
+        fmt.Println("Big cheer! Playing alert...")
+    case e.Bits >= 100:
+        fmt.Println("Nice cheer! Playing sound...")
+    default:
+        fmt.Println("Thanks for the bits!")
+    }
+}
+```
+
+## Get Subscriptions
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // Setup client with broadcaster token
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Get all subscribers
+    subs, err := client.GetBroadcasterSubscriptions(ctx, &helix.GetBroadcasterSubscriptionsParams{
+        BroadcasterID: broadcasterID,
+        First:         100,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("=== Subscribers ===\n")
+    fmt.Printf("Total: %d\n", subs.Total)
+    fmt.Printf("Subscriber Points: %d\n\n", subs.Points)
+
+    for _, sub := range subs.Data {
+        fmt.Printf("%s (Tier %s)\n", sub.UserName, sub.Tier)
+        fmt.Printf("  Gifter: %s\n", sub.GifterName)
+        fmt.Printf("  Gift: %v\n", sub.IsGift)
+    }
+
+    // Check if specific user is subscribed
+    userSub, err := client.CheckUserSubscription(ctx, &helix.CheckUserSubscriptionParams{
+        BroadcasterID: broadcasterID,
+        UserID:        "user-to-check",
+    })
+    if err != nil {
+        fmt.Println("User is not subscribed")
+    } else {
+        fmt.Printf("User is subscribed at tier %s\n", userSub.Data[0].Tier)
+    }
+
+    // Get subscribers with pagination
+    var allSubs []helix.BroadcasterSubscription
+    cursor := ""
+    for {
+        resp, err := client.GetBroadcasterSubscriptions(ctx, &helix.GetBroadcasterSubscriptionsParams{
+            BroadcasterID: broadcasterID,
+            First:         100,
+            After:         cursor,
+        })
+        if err != nil {
+            log.Fatal(err)
+        }
+        allSubs = append(allSubs, resp.Data...)
+        if resp.Pagination == nil || resp.Pagination.Cursor == "" {
+            break
+        }
+        cursor = resp.Pagination.Cursor
+    }
+    fmt.Printf("Fetched all %d subscribers\n", len(allSubs))
+}
+```
+
+## Handle Subscriptions with EventSub
+
+```go
+package main
+
+import (
+    "context"
+    "encoding/json"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // Setup clients
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Create WebSocket client
+    ws := helix.NewEventSubWebSocket(client)
+    if err := ws.Connect(ctx); err != nil {
+        log.Fatal(err)
+    }
+    defer ws.Close()
+
+    // Subscribe to new subscriptions
+    ws.Subscribe(ctx, helix.EventSubTypeChannelSubscribe, "1",
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.ChannelSubscribeEvent](event)
+            fmt.Printf("New sub: %s (Tier %s, Gift: %v)\n", e.UserName, e.Tier, e.IsGift)
+        },
+    )
+
+    // Subscribe to gift subs
+    ws.Subscribe(ctx, helix.EventSubTypeChannelSubscriptionGift, "1",
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.ChannelSubscriptionGiftEvent](event)
+            fmt.Printf("%s gifted %d subs! (Tier %s, Total: %d)\n",
+                e.UserName, e.Total, e.Tier, e.CumulativeTotal)
+        },
+    )
+
+    // Subscribe to resub messages
+    ws.Subscribe(ctx, helix.EventSubTypeChannelSubscriptionMessage, "1",
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.ChannelSubscriptionMessageEvent](event)
+            fmt.Printf("Resub: %s - %d months! Message: %s\n",
+                e.UserName, e.CumulativeMonths, e.Message.Text)
+            if e.StreakMonths > 0 {
+                fmt.Printf("  Streak: %d months\n", e.StreakMonths)
+            }
+        },
+    )
+
+    // Subscribe to sub ends
+    ws.Subscribe(ctx, helix.EventSubTypeChannelSubscriptionEnd, "1",
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.ChannelSubscriptionEndEvent](event)
+            fmt.Printf("Sub ended: %s (Tier %s, Gift: %v)\n", e.UserName, e.Tier, e.IsGift)
+        },
+    )
+
+    fmt.Println("Listening for subscription events...")
+    select {}
+}
+```
+
+## Subscription Tier Analysis
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Get all subscribers
+    var allSubs []helix.BroadcasterSubscription
+    cursor := ""
+    for {
+        resp, err := client.GetBroadcasterSubscriptions(ctx, &helix.GetBroadcasterSubscriptionsParams{
+            BroadcasterID: broadcasterID,
+            First:         100,
+            After:         cursor,
+        })
+        if err != nil {
+            log.Fatal(err)
+        }
+        allSubs = append(allSubs, resp.Data...)
+        if resp.Pagination == nil || resp.Pagination.Cursor == "" {
+            break
+        }
+        cursor = resp.Pagination.Cursor
+    }
+
+    // Analyze tiers
+    tiers := map[string]int{"1000": 0, "2000": 0, "3000": 0}
+    gifted := 0
+
+    for _, sub := range allSubs {
+        tiers[sub.Tier]++
+        if sub.IsGift {
+            gifted++
+        }
+    }
+
+    fmt.Println("=== Subscription Analysis ===")
+    fmt.Printf("Total Subscribers: %d\n", len(allSubs))
+    fmt.Printf("Tier 1 (1000): %d (%.1f%%)\n", tiers["1000"], float64(tiers["1000"])/float64(len(allSubs))*100)
+    fmt.Printf("Tier 2 (2000): %d (%.1f%%)\n", tiers["2000"], float64(tiers["2000"])/float64(len(allSubs))*100)
+    fmt.Printf("Tier 3 (3000): %d (%.1f%%)\n", tiers["3000"], float64(tiers["3000"])/float64(len(allSubs))*100)
+    fmt.Printf("Gifted: %d (%.1f%%)\n", gifted, float64(gifted)/float64(len(allSubs))*100)
+
+    // Calculate estimated monthly revenue (rough estimate)
+    // Tier 1 = $4.99, Tier 2 = $9.99, Tier 3 = $24.99 (50% split assumed)
+    revenue := float64(tiers["1000"])*2.50 + float64(tiers["2000"])*5.00 + float64(tiers["3000"])*12.50
+    fmt.Printf("Estimated Monthly Revenue: $%.2f\n", revenue)
+}
+```
+
diff --git a/docs/examples/channel-points.md b/docs/examples/channel-points.md
new file mode 100644
index 0000000..6a6e5b8
--- /dev/null
+++ b/docs/examples/channel-points.md
@@ -0,0 +1,387 @@
+---
+layout: default
+title: Channel Points Examples
+description: Manage custom rewards and handle redemptions.
+---
+
+## Overview
+
+Channel Points are a loyalty system where viewers earn points by watching and engaging with streams. Broadcasters can create custom rewards that viewers redeem with their points.
+
+**What you can do**:
+- Create, update, and delete custom rewards
+- Get pending redemptions and update their status (fulfill/cancel)
+- Listen for real-time redemption events via EventSub
+- Build automated reward fulfillment systems
+
+**Common use cases**:
+- Song request systems
+- TTS (text-to-speech) messages
+- Game actions triggered by viewers
+- VIP perks and special interactions
+
+## Prerequisites
+
+Channel Points require user authentication with these scopes:
+- `channel:read:redemptions` - Read redemptions
+- `channel:manage:redemptions` - Manage redemption status
+- `channel:manage:rewards` - Create/manage custom rewards (broadcaster only)
+
+## Create Custom Rewards
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // Setup client with broadcaster token
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Create a simple reward
+    reward, err := client.CreateCustomReward(ctx, &helix.CreateCustomRewardParams{
+        BroadcasterID: broadcasterID,
+        Title:         "Hydrate!",
+        Cost:          100,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+    fmt.Printf("Created reward: %s (ID: %s)\n", reward.Data[0].Title, reward.Data[0].ID)
+
+    // Create a reward with all options
+    fullReward, err := client.CreateCustomReward(ctx, &helix.CreateCustomRewardParams{
+        BroadcasterID:                    broadcasterID,
+        Title:                            "Song Request",
+        Cost:                             500,
+        Prompt:                           "Enter the song name and artist",
+        IsEnabled:                        boolPtr(true),
+        BackgroundColor:                  "#FF0000",
+        IsUserInputRequired:              true,
+        IsMaxPerStreamEnabled:            true,
+        MaxPerStream:                     10,
+        IsMaxPerUserPerStreamEnabled:     true,
+        MaxPerUserPerStream:              2,
+        IsGlobalCooldownEnabled:          true,
+        GlobalCooldownSeconds:            300,
+        ShouldRedemptionsSkipRequestQueue: false,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+    fmt.Printf("Created reward: %s\n", fullReward.Data[0].Title)
+}
+
+func boolPtr(b bool) *bool { return &b }
+```
+
+## Get Custom Rewards
+
+```go
+// Get all custom rewards
+rewards, err := client.GetCustomRewards(ctx, &helix.GetCustomRewardsParams{
+    BroadcasterID: broadcasterID,
+})
+if err != nil {
+    log.Fatal(err)
+}
+
+for _, reward := range rewards.Data {
+    fmt.Printf("Reward: %s\n", reward.Title)
+    fmt.Printf("  ID: %s\n", reward.ID)
+    fmt.Printf("  Cost: %d\n", reward.Cost)
+    fmt.Printf("  Enabled: %v\n", reward.IsEnabled)
+    fmt.Printf("  Paused: %v\n", reward.IsPaused)
+    fmt.Printf("  In Stock: %v\n", reward.IsInStock)
+}
+
+// Get specific rewards by ID
+specificRewards, err := client.GetCustomRewards(ctx, &helix.GetCustomRewardsParams{
+    BroadcasterID: broadcasterID,
+    IDs:           []string{"reward-id-1", "reward-id-2"},
+})
+
+// Get only manageable rewards (created by your app)
+manageableRewards, err := client.GetCustomRewards(ctx, &helix.GetCustomRewardsParams{
+    BroadcasterID:      broadcasterID,
+    OnlyManageableRewards: true,
+})
+```
+
+## Update Custom Rewards
+
+```go
+// Update reward cost and title
+updated, err := client.UpdateCustomReward(ctx, &helix.UpdateCustomRewardParams{
+    BroadcasterID: broadcasterID,
+    ID:            "reward-id",
+    Title:         "Song Request (Updated)",
+    Cost:          750,
+})
+
+// Pause a reward
+paused, err := client.UpdateCustomReward(ctx, &helix.UpdateCustomRewardParams{
+    BroadcasterID: broadcasterID,
+    ID:            "reward-id",
+    IsPaused:      boolPtr(true),
+})
+
+// Disable a reward
+disabled, err := client.UpdateCustomReward(ctx, &helix.UpdateCustomRewardParams{
+    BroadcasterID: broadcasterID,
+    ID:            "reward-id",
+    IsEnabled:     boolPtr(false),
+})
+```
+
+## Delete Custom Rewards
+
+```go
+// Delete a reward (only rewards created by your app can be deleted)
+err := client.DeleteCustomReward(ctx, broadcasterID, "reward-id")
+if err != nil {
+    log.Printf("Failed to delete reward: %v", err)
+}
+```
+
+## Get Redemptions
+
+```go
+// Get unfulfilled redemptions
+redemptions, err := client.GetCustomRewardRedemptions(ctx, &helix.GetCustomRewardRedemptionsParams{
+    BroadcasterID: broadcasterID,
+    RewardID:      "reward-id",
+    Status:        "UNFULFILLED",
+})
+if err != nil {
+    log.Fatal(err)
+}
+
+for _, redemption := range redemptions.Data {
+    fmt.Printf("Redemption by %s\n", redemption.UserName)
+    fmt.Printf("  ID: %s\n", redemption.ID)
+    fmt.Printf("  User Input: %s\n", redemption.UserInput)
+    fmt.Printf("  Redeemed At: %s\n", redemption.RedeemedAt)
+    fmt.Printf("  Status: %s\n", redemption.Status)
+}
+
+// Get redemptions with pagination
+allRedemptions, err := client.GetCustomRewardRedemptions(ctx, &helix.GetCustomRewardRedemptionsParams{
+    BroadcasterID: broadcasterID,
+    RewardID:      "reward-id",
+    Status:        "UNFULFILLED",
+    First:         50,
+    Sort:          "NEWEST",
+})
+```
+
+## Update Redemption Status
+
+```go
+// Fulfill a redemption
+fulfilled, err := client.UpdateCustomRewardRedemptionStatus(ctx, &helix.UpdateRedemptionStatusParams{
+    BroadcasterID: broadcasterID,
+    RewardID:      "reward-id",
+    IDs:           []string{"redemption-id"},
+    Status:        "FULFILLED",
+})
+
+// Cancel a redemption (refunds points)
+cancelled, err := client.UpdateCustomRewardRedemptionStatus(ctx, &helix.UpdateRedemptionStatusParams{
+    BroadcasterID: broadcasterID,
+    RewardID:      "reward-id",
+    IDs:           []string{"redemption-id"},
+    Status:        "CANCELED",
+})
+
+// Batch update multiple redemptions
+batchUpdated, err := client.UpdateCustomRewardRedemptionStatus(ctx, &helix.UpdateRedemptionStatusParams{
+    BroadcasterID: broadcasterID,
+    RewardID:      "reward-id",
+    IDs:           []string{"id-1", "id-2", "id-3"},
+    Status:        "FULFILLED",
+})
+```
+
+## Real-Time Redemptions with EventSub
+
+Handle redemptions in real-time:
+
+```go
+package main
+
+import (
+    "context"
+    "encoding/json"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // Setup clients
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Create WebSocket client
+    ws := helix.NewEventSubWebSocket(client)
+    if err := ws.Connect(ctx); err != nil {
+        log.Fatal(err)
+    }
+    defer ws.Close()
+
+    // Subscribe to all redemptions
+    ws.Subscribe(ctx, helix.EventSubTypeChannelPointsRedemptionAdd, "1",
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.ChannelPointsRedemptionEvent](event)
+            handleRedemption(ctx, client, e)
+        },
+    )
+
+    // Subscribe to specific reward redemptions
+    ws.Subscribe(ctx, helix.EventSubTypeChannelPointsRedemptionAdd, "1",
+        map[string]string{
+            "broadcaster_user_id": broadcasterID,
+            "reward_id":           "specific-reward-id",
+        },
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.ChannelPointsRedemptionEvent](event)
+            fmt.Printf("Specific reward redeemed by %s\n", e.UserName)
+        },
+    )
+
+    fmt.Println("Listening for redemptions...")
+    select {}
+}
+
+func handleRedemption(ctx context.Context, client *helix.Client, e *helix.ChannelPointsRedemptionEvent) {
+    fmt.Printf("Redemption: %s by %s\n", e.Reward.Title, e.UserName)
+
+    switch e.Reward.Title {
+    case "Song Request":
+        // Process song request
+        fmt.Printf("Song requested: %s\n", e.UserInput)
+        // Fulfill after processing
+        client.UpdateCustomRewardRedemptionStatus(ctx, &helix.UpdateRedemptionStatusParams{
+            BroadcasterID: e.BroadcasterUserID,
+            RewardID:      e.Reward.ID,
+            IDs:           []string{e.ID},
+            Status:        "FULFILLED",
+        })
+
+    case "Hydrate!":
+        // Auto-fulfill simple rewards
+        client.UpdateCustomRewardRedemptionStatus(ctx, &helix.UpdateRedemptionStatusParams{
+            BroadcasterID: e.BroadcasterUserID,
+            RewardID:      e.Reward.ID,
+            IDs:           []string{e.ID},
+            Status:        "FULFILLED",
+        })
+
+    default:
+        fmt.Printf("Unhandled reward: %s\n", e.Reward.Title)
+    }
+}
+```
+
+## Reward Queue Manager
+
+Complete example for managing a reward queue:
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "sync"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+type RewardQueue struct {
+    client        *helix.Client
+    broadcasterID string
+    queue         []helix.ChannelPointsRedemptionEvent
+    mu            sync.Mutex
+}
+
+func NewRewardQueue(client *helix.Client, broadcasterID string) *RewardQueue {
+    return &RewardQueue{
+        client:        client,
+        broadcasterID: broadcasterID,
+        queue:         make([]helix.ChannelPointsRedemptionEvent, 0),
+    }
+}
+
+func (q *RewardQueue) Add(redemption helix.ChannelPointsRedemptionEvent) {
+    q.mu.Lock()
+    defer q.mu.Unlock()
+    q.queue = append(q.queue, redemption)
+    fmt.Printf("Added to queue: %s by %s (queue size: %d)\n",
+        redemption.Reward.Title, redemption.UserName, len(q.queue))
+}
+
+func (q *RewardQueue) ProcessNext(ctx context.Context) *helix.ChannelPointsRedemptionEvent {
+    q.mu.Lock()
+    if len(q.queue) == 0 {
+        q.mu.Unlock()
+        return nil
+    }
+    redemption := q.queue[0]
+    q.queue = q.queue[1:]
+    q.mu.Unlock()
+
+    return &redemption
+}
+
+func (q *RewardQueue) Fulfill(ctx context.Context, redemption *helix.ChannelPointsRedemptionEvent) error {
+    _, err := q.client.UpdateCustomRewardRedemptionStatus(ctx, &helix.UpdateRedemptionStatusParams{
+        BroadcasterID: q.broadcasterID,
+        RewardID:      redemption.Reward.ID,
+        IDs:           []string{redemption.ID},
+        Status:        "FULFILLED",
+    })
+    return err
+}
+
+func (q *RewardQueue) Cancel(ctx context.Context, redemption *helix.ChannelPointsRedemptionEvent) error {
+    _, err := q.client.UpdateCustomRewardRedemptionStatus(ctx, &helix.UpdateRedemptionStatusParams{
+        BroadcasterID: q.broadcasterID,
+        RewardID:      redemption.Reward.ID,
+        IDs:           []string{redemption.ID},
+        Status:        "CANCELED",
+    })
+    return err
+}
+
+func (q *RewardQueue) Size() int {
+    q.mu.Lock()
+    defer q.mu.Unlock()
+    return len(q.queue)
+}
+```
+
diff --git a/docs/examples/chatbot.md b/docs/examples/chatbot.md
index cf380f6..40b7009 100644
--- a/docs/examples/chatbot.md
+++ b/docs/examples/chatbot.md
@@ -1,6 +1,21 @@
-# Chat Bot Example
+---
+layout: default
+title: Chat Bot Example
+description: Build a Twitch chat bot using the Helix API and EventSub WebSocket for real-time message handling.
+---
 
-Build a Twitch chat bot using the Helix API.
+## Overview
+
+This guide demonstrates how to build a feature-rich chat bot that can:
+- Receive and respond to chat messages in real-time
+- Execute custom commands (e.g., `!hello`, `!dice`)
+- Perform moderation actions (ban, timeout, delete messages)
+- Send announcements and shoutouts
+- Control chat settings (slow mode, sub-only mode, etc.)
+
+**Architecture**: The bot uses EventSub WebSocket to receive chat events and the Helix API to send messages and perform actions. This approach provides reliable event delivery with acknowledgment.
+
+**Alternative**: For lower latency chat handling, see the [IRC Client](Projects/Programming/Kappopher/Documents/examples/irc-client.md) examples.
 
 ## Prerequisites
 
@@ -12,6 +27,10 @@ Chat bots require user authentication with the following scopes:
 
 ## Basic Chat Bot
 
+A minimal chat bot that sends a single message to chat. This demonstrates the core setup required for any bot: authentication, client creation, and message sending.
+
+**Note**: This example only sends messages - it doesn't receive them. For a fully interactive bot, see the EventSub example below.
+
 ```go
 package main
 
@@ -68,7 +87,17 @@ func sendMessage(ctx context.Context, client *helix.Client, broadcasterID, sende
 
 ## Responding to Events with EventSub
 
-Use EventSub WebSocket to receive chat messages and respond:
+A complete chat bot with command handling using EventSub WebSocket. This approach:
+- Receives chat messages in real-time via WebSocket
+- Parses messages to detect commands (starting with `!`)
+- Executes registered command handlers
+- Sends responses back to chat
+
+**Key components**:
+- `ChatBot` struct: Manages client, configuration, and command registry
+- `CommandHandler`: Function signature for command implementations
+- `HandleMessage`: Parses incoming messages and routes to commands
+- `RegisterCommand`: Adds new commands dynamically
 
 ```go
 package main
@@ -212,6 +241,12 @@ func main() {
 
 ## Moderation Features
 
+Add moderation capabilities to your bot. These require the bot to have moderator privileges in the channel and appropriate scopes.
+
+**Required scope**: `moderator:manage:banned_users` for bans/timeouts, `moderator:manage:chat_messages` for message deletion.
+
+**Note**: The bot must be a moderator in the channel to perform these actions.
+
 ```go
 // Timeout a user
 func (b *ChatBot) TimeoutUser(ctx context.Context, userID string, duration int, reason string) error {
@@ -263,6 +298,12 @@ func (b *ChatBot) ClearChat(ctx context.Context) error {
 
 ## Announcements
 
+Send highlighted announcements that stand out in chat. Announcements appear with a colored background and are useful for important messages.
+
+**Required scope**: `moderator:manage:announcements`
+
+**Colors available**: `"blue"`, `"green"`, `"orange"`, `"purple"`, or `"primary"` (channel accent color)
+
 ```go
 // Send an announcement
 func (b *ChatBot) Announce(ctx context.Context, message, color string) error {
@@ -277,6 +318,12 @@ func (b *ChatBot) Announce(ctx context.Context, message, color string) error {
 
 ## Shoutouts
 
+Send a shoutout to promote another streamer. This displays a card in chat with information about the target channel.
+
+**Required scope**: `moderator:manage:shoutouts`
+
+**Cooldown**: There's a 2-minute cooldown between shoutouts to the same user.
+
 ```go
 // Give a shoutout to another streamer
 func (b *ChatBot) Shoutout(ctx context.Context, targetUserID string) error {
@@ -290,6 +337,16 @@ func (b *ChatBot) Shoutout(ctx context.Context, targetUserID string) error {
 
 ## Chat Settings
 
+Control chat modes programmatically. Useful for automating chat management during raids, high-activity moments, or scheduled events.
+
+**Required scope**: `moderator:manage:chat_settings`
+
+**Available modes**:
+- **Slow mode**: Limit how often users can send messages
+- **Subscriber-only mode**: Only subscribers can chat
+- **Emote-only mode**: Only emotes allowed in messages
+- **Follower-only mode**: Only followers can chat (with optional minimum follow time)
+
 ```go
 // Enable slow mode
 func (b *ChatBot) EnableSlowMode(ctx context.Context, seconds int) error {
@@ -321,3 +378,4 @@ func (b *ChatBot) EnableEmoteOnlyMode(ctx context.Context) error {
 
 func boolPtr(b bool) *bool { return &b }
 ```
+
diff --git a/docs/examples/eventsub-webhooks.md b/docs/examples/eventsub-webhooks.md
index b5716f7..60bef91 100644
--- a/docs/examples/eventsub-webhooks.md
+++ b/docs/examples/eventsub-webhooks.md
@@ -1,9 +1,34 @@
-# EventSub Webhooks
+---
+layout: default
+title: EventSub Webhooks
+description: Handle EventSub webhook notifications with built-in signature verification.
+---
 
-Handle EventSub webhook notifications with built-in signature verification.
+## Overview
+
+EventSub Webhooks allow Twitch to push real-time notifications to your server. Unlike WebSocket, webhooks require a publicly accessible HTTPS endpoint.
+
+**When to use Webhooks**:
+- Server-side applications with a public endpoint
+- When you need events even when your app isn't actively connected
+- For high-reliability scenarios (Twitch retries failed deliveries)
+
+**When to use WebSocket instead**:
+- Client-side or local applications
+- When you don't have a public HTTPS endpoint
+- For simpler setup without SSL certificate management
+
+**How it works**:
+1. Your server exposes an HTTPS endpoint
+2. You create subscriptions telling Twitch where to send events
+3. Twitch verifies your endpoint ownership via a challenge request
+4. Twitch sends signed notifications to your endpoint
+5. Your handler verifies signatures and processes events
 
 ## Basic Setup
 
+The handler automatically verifies HMAC signatures to ensure notifications are from Twitch.
+
 ```go
 handler := helix.NewEventSubWebhookHandler(
     helix.WithWebhookSecret("your-webhook-secret"),
@@ -27,6 +52,11 @@ http.Handle("/webhook", handler)
 
 ## Complete Example
 
+A full webhook server handling multiple event types. The handler uses separate callbacks for:
+- **Notifications**: Actual events (follows, subscriptions, stream status, etc.)
+- **Verification**: Challenge requests when creating subscriptions
+- **Revocation**: When Twitch revokes a subscription (e.g., token expired)
+
 ```go
 package main
 
@@ -110,7 +140,12 @@ func handleRevocation(msg *helix.EventSubWebhookMessage) {
 
 ## Creating Subscriptions
 
-To receive webhook notifications, you must first create EventSub subscriptions:
+After setting up your webhook handler, create subscriptions to tell Twitch which events to send.
+
+**Important**:
+- The callback URL must be HTTPS (HTTP is not accepted)
+- The secret must match between subscription creation and webhook handler
+- Twitch will send a verification challenge immediately after subscription creation
 
 ```go
 ctx := context.Background()
@@ -134,5 +169,5 @@ if err != nil {
 ```
 
 ## Supported Event Types
+See [EventSub documentation](eventsub.md) for a complete list of event types.
 
-See [EventSub documentation](../eventsub.md) for a complete list of event types.
diff --git a/docs/examples/eventsub-websocket.md b/docs/examples/eventsub-websocket.md
index 29d7aa7..0f0a7fd 100644
--- a/docs/examples/eventsub-websocket.md
+++ b/docs/examples/eventsub-websocket.md
@@ -1,10 +1,31 @@
-# EventSub WebSocket
+---
+layout: default
+title: EventSub WebSocket
+description: Real-time event streaming without requiring a public endpoint.
+---
 
-Real-time event streaming without requiring a public endpoint.
+## Overview
+
+EventSub WebSocket provides real-time Twitch events over a persistent WebSocket connection. Unlike webhooks, no public HTTPS endpoint is required.
+
+**Advantages over Webhooks**:
+- No public endpoint needed - works behind firewalls/NAT
+- Lower latency - direct connection, no HTTP overhead
+- Simpler setup - no SSL certificates required
+- Ideal for bots, overlays, and local applications
+
+**How it works**:
+1. Connect to Twitch's WebSocket endpoint
+2. Receive a session ID in the welcome message
+3. Create subscriptions using the session ID
+4. Receive events on the WebSocket connection
+5. Handle keepalives and reconnection messages
+
+**Connection limits**: Each WebSocket session can have up to 300 subscriptions. For more, use multiple connections.
 
 ## Low-Level Client
 
-Full control over WebSocket connection and event handling:
+Full control over WebSocket connection and event handling. Use this when you need direct access to connection lifecycle events or custom subscription management.
 
 ```go
 package main
@@ -86,7 +107,9 @@ func main() {
 
 ## High-Level Wrapper
 
-Simplified interface that manages subscriptions automatically:
+Simplified interface that manages subscriptions automatically. The `Subscribe` method handles both creating the EventSub subscription and registering the event handler in one call.
+
+**Recommended for most use cases** - handles session management, subscription creation, and event routing internally.
 
 ```go
 package main
@@ -146,7 +169,9 @@ func main() {
 
 ## Handling Reconnection
 
-Twitch may send a reconnect message before maintenance. Handle it gracefully:
+Twitch sends a reconnect message when the server needs to migrate your connection (e.g., before maintenance). You have 30 seconds to reconnect to the new URL.
+
+**Important**: Your subscriptions are preserved - just reconnect to the new URL and continue receiving events.
 
 ```go
 wsClient := helix.NewEventSubWebSocketClient(
@@ -168,6 +193,10 @@ wsClient := helix.NewEventSubWebSocketClient(
 
 ## Error Handling
 
+Handle connection errors and implement automatic reconnection. Common errors include network issues, connection timeouts, and server-side disconnects.
+
+**Best practice**: Implement exponential backoff when reconnecting to avoid overwhelming the server.
+
 ```go
 wsClient := helix.NewEventSubWebSocketClient(
     helix.WithWSNotificationHandler(handleNotification),
@@ -188,5 +217,5 @@ wsClient := helix.NewEventSubWebSocketClient(
 Note: Expected close errors (like "use of closed network connection" during shutdown) are automatically filtered and won't trigger the error handler.
 
 ## Supported Event Types
+See [EventSub documentation](eventsub.md) for a complete list of event types.
 
-See [EventSub documentation](../eventsub.md) for a complete list of event types.
diff --git a/docs/examples/extension-jwt.md b/docs/examples/extension-jwt.md
index 2a737e8..f3ab0a9 100644
--- a/docs/examples/extension-jwt.md
+++ b/docs/examples/extension-jwt.md
@@ -1,9 +1,28 @@
-# Extension JWT Authentication
+---
+layout: default
+title: Extension JWT Authentication
+description: For Twitch Extensions that require JWT authentication.
+---
 
-For Twitch Extensions that require JWT authentication.
+## Overview
+
+Twitch Extensions use JSON Web Tokens (JWT) to securely authenticate requests between your Extension Backend Service (EBS) and Twitch's API. JWTs are signed with your extension's secret, ensuring requests are authorized.
+
+**When you need JWT authentication**:
+- Sending messages to the extension PubSub
+- Accessing extension configuration segments
+- Making API calls that require extension context
+- Authenticating requests from your EBS to Twitch
+
+**Key concepts**:
+- **Extension Secret**: A base64-encoded secret from your Extension settings, used to sign JWTs
+- **EBS Token**: Authenticates your backend service to Twitch
+- **Broadcaster Token**: Performs actions on behalf of a specific broadcaster's channel
 
 ## Creating JWT Tokens
 
+Create tokens for different authorization contexts. The JWT handler manages signing and claims automatically.
+
 ```go
 package main
 
@@ -44,6 +63,8 @@ func main() {
 
 ## Using with Extension Client
 
+The `ExtensionClient` automatically handles JWT token creation and attachment for extension API calls.
+
 ```go
 package main
 
@@ -111,9 +132,11 @@ client.SetExtensionJWT(jwt)
 
 ## Token Types
 
+Different token types authorize different actions. Choose the appropriate type based on what your request needs to do.
+
 ### EBS Token
 
-Used for Extension Backend Service calls:
+General-purpose token for your Extension Backend Service. Use this for operations that don't require specific broadcaster context.
 
 ```go
 ebsToken, _ := jwt.CreateEBSToken(time.Hour)
@@ -121,7 +144,7 @@ ebsToken, _ := jwt.CreateEBSToken(time.Hour)
 
 ### Broadcaster Token
 
-Used for calls on behalf of a specific broadcaster:
+Used when performing actions in the context of a specific broadcaster's channel. Required for channel-specific operations like sending PubSub messages to a channel or reading channel configuration.
 
 ```go
 broadcasterToken, _ := jwt.CreateBroadcasterToken("channel-id", time.Hour)
@@ -129,7 +152,7 @@ broadcasterToken, _ := jwt.CreateBroadcasterToken("channel-id", time.Hour)
 
 ### Custom Claims
 
-For advanced use cases with custom claims:
+For advanced use cases where you need fine-grained control over token permissions, including PubSub listen/send permissions and custom roles.
 
 ```go
 token, _ := jwt.CreateToken(helix.ExtensionJWTClaims{
@@ -144,5 +167,5 @@ token, _ := jwt.CreateToken(helix.ExtensionJWTClaims{
 ```
 
 ## Extension API Endpoints
+See [Extensions documentation](extensions.md) for all available extension endpoints.
 
-See [Extensions documentation](../extensions.md) for all available extension endpoints.
diff --git a/docs/examples/irc-client.md b/docs/examples/irc-client.md
new file mode 100644
index 0000000..49ced9b
--- /dev/null
+++ b/docs/examples/irc-client.md
@@ -0,0 +1,571 @@
+---
+layout: default
+title: IRC Client Examples
+description: Build chat bots using the low-level IRC/WebSocket client.
+---
+
+## Overview
+
+The IRC client provides direct WebSocket connection to Twitch chat, offering:
+- Lower latency than EventSub for chat messages
+- Direct message sending without API rate limits
+- Full IRC message parsing with tags (badges, emotes, etc.)
+- Support for all TMI (Twitch Messaging Interface) events
+
+## Basic IRC Client
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // Create IRC client
+    irc := helix.NewIRCClient(
+        helix.WithIRCToken("oauth:your-oauth-token"), // Get from twitchtokengenerator.com
+        helix.WithIRCNick("your_bot_username"),
+        helix.WithIRCMessageHandler(func(msg *helix.IRCMessage) {
+            if msg.Command == "PRIVMSG" {
+                fmt.Printf("[%s] %s: %s\n", msg.Channel, msg.User, msg.Text)
+            }
+        }),
+    )
+
+    // Connect
+    if err := irc.Connect(ctx); err != nil {
+        log.Fatal(err)
+    }
+    defer irc.Close()
+
+    // Join channels
+    if err := irc.Join("channel1"); err != nil {
+        log.Fatal(err)
+    }
+    if err := irc.Join("channel2"); err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("Connected to chat!")
+
+    // Keep running
+    select {}
+}
+```
+
+## ChatBotClient (High-Level)
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // Setup auth client
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+
+    // Create Helix client for API calls
+    helixClient := helix.NewClient("your-client-id", authClient)
+
+    // Create ChatBotClient (combines IRC + Helix API)
+    bot := helix.NewChatBotClient(helixClient,
+        helix.WithChatBotMessageHandler(func(msg *helix.IRCMessage) {
+            handleMessage(ctx, bot, msg)
+        }),
+        helix.WithChatBotAutoReconnect(true),
+    )
+
+    // Connect with user token
+    if err := bot.Connect(ctx); err != nil {
+        log.Fatal(err)
+    }
+    defer bot.Close()
+
+    // Join channel
+    if err := bot.Join("channel_name"); err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("Bot is running!")
+    select {}
+}
+
+func handleMessage(ctx context.Context, bot *helix.ChatBotClient, msg *helix.IRCMessage) {
+    if msg.Command != "PRIVMSG" {
+        return
+    }
+
+    // Respond to commands
+    switch msg.Text {
+    case "!ping":
+        bot.Say(msg.Channel, "Pong!")
+    case "!time":
+        bot.Say(msg.Channel, fmt.Sprintf("Current time: %s", time.Now().Format(time.RFC1123)))
+    }
+}
+```
+
+## IRC Message Handling
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    irc := helix.NewIRCClient(
+        helix.WithIRCToken("oauth:token"),
+        helix.WithIRCNick("bot_name"),
+        helix.WithIRCMessageHandler(handleIRCMessage),
+    )
+
+    if err := irc.Connect(ctx); err != nil {
+        log.Fatal(err)
+    }
+    defer irc.Close()
+
+    irc.Join("channel")
+    select {}
+}
+
+func handleIRCMessage(msg *helix.IRCMessage) {
+    switch msg.Command {
+    case "PRIVMSG":
+        handleChatMessage(msg)
+
+    case "USERNOTICE":
+        handleUserNotice(msg)
+
+    case "ROOMSTATE":
+        handleRoomState(msg)
+
+    case "CLEARCHAT":
+        handleClearChat(msg)
+
+    case "CLEARMSG":
+        handleClearMsg(msg)
+
+    case "NOTICE":
+        fmt.Printf("Notice: %s\n", msg.Text)
+
+    case "RECONNECT":
+        fmt.Println("Server requested reconnect")
+
+    case "USERSTATE":
+        fmt.Printf("User state updated in %s\n", msg.Channel)
+    }
+}
+
+func handleChatMessage(msg *helix.IRCMessage) {
+    // Access IRC tags
+    displayName := msg.Tags["display-name"]
+    badges := msg.Tags["badges"]
+    color := msg.Tags["color"]
+    emotes := msg.Tags["emotes"]
+    msgID := msg.Tags["id"]
+
+    // Check for bits
+    if bits, ok := msg.Tags["bits"]; ok {
+        fmt.Printf("💎 %s cheered %s bits: %s\n", displayName, bits, msg.Text)
+        return
+    }
+
+    // Check user status
+    isMod := msg.Tags["mod"] == "1"
+    isSub := msg.Tags["subscriber"] == "1"
+    isVIP := msg.Tags["vip"] == "1"
+
+    prefix := ""
+    if isMod {
+        prefix = "🗡️"
+    } else if isVIP {
+        prefix = "💎"
+    } else if isSub {
+        prefix = "⭐"
+    }
+
+    fmt.Printf("%s[%s] %s: %s\n", prefix, msg.Channel, displayName, msg.Text)
+
+    // Store message ID for potential moderation
+    _ = msgID
+    _ = badges
+    _ = color
+    _ = emotes
+}
+
+func handleUserNotice(msg *helix.IRCMessage) {
+    msgID := msg.Tags["msg-id"]
+    displayName := msg.Tags["display-name"]
+
+    switch msgID {
+    case "sub":
+        plan := msg.Tags["msg-param-sub-plan"]
+        fmt.Printf("🎉 %s subscribed! (Tier %s)\n", displayName, tierName(plan))
+
+    case "resub":
+        months := msg.Tags["msg-param-cumulative-months"]
+        plan := msg.Tags["msg-param-sub-plan"]
+        fmt.Printf("🎉 %s resubscribed for %s months! (Tier %s)\n", displayName, months, tierName(plan))
+        if msg.Text != "" {
+            fmt.Printf("   Message: %s\n", msg.Text)
+        }
+
+    case "subgift":
+        recipient := msg.Tags["msg-param-recipient-display-name"]
+        plan := msg.Tags["msg-param-sub-plan"]
+        fmt.Printf("🎁 %s gifted a sub to %s! (Tier %s)\n", displayName, recipient, tierName(plan))
+
+    case "submysterygift":
+        count := msg.Tags["msg-param-mass-gift-count"]
+        fmt.Printf("🎁 %s gifted %s subs to the community!\n", displayName, count)
+
+    case "raid":
+        viewers := msg.Tags["msg-param-viewerCount"]
+        fmt.Printf("🚀 %s is raiding with %s viewers!\n", displayName, viewers)
+
+    case "announcement":
+        fmt.Printf("📢 Announcement from %s: %s\n", displayName, msg.Text)
+    }
+}
+
+func handleRoomState(msg *helix.IRCMessage) {
+    channel := msg.Channel
+    fmt.Printf("Room state for %s:\n", channel)
+
+    if emoteOnly := msg.Tags["emote-only"]; emoteOnly == "1" {
+        fmt.Println("  - Emote-only mode ON")
+    }
+    if followersOnly := msg.Tags["followers-only"]; followersOnly != "-1" {
+        fmt.Printf("  - Followers-only: %s minutes\n", followersOnly)
+    }
+    if slow := msg.Tags["slow"]; slow != "0" {
+        fmt.Printf("  - Slow mode: %s seconds\n", slow)
+    }
+    if subsOnly := msg.Tags["subs-only"]; subsOnly == "1" {
+        fmt.Println("  - Subscribers-only mode ON")
+    }
+    if r9k := msg.Tags["r9k"]; r9k == "1" {
+        fmt.Println("  - R9K mode ON")
+    }
+}
+
+func handleClearChat(msg *helix.IRCMessage) {
+    if targetUser := msg.Tags["target-user-id"]; targetUser != "" {
+        duration := msg.Tags["ban-duration"]
+        if duration == "" {
+            fmt.Printf("🔨 %s was permanently banned\n", msg.Text)
+        } else {
+            fmt.Printf("⏰ %s was timed out for %s seconds\n", msg.Text, duration)
+        }
+    } else {
+        fmt.Printf("🧹 Chat was cleared in %s\n", msg.Channel)
+    }
+}
+
+func handleClearMsg(msg *helix.IRCMessage) {
+    targetMsgID := msg.Tags["target-msg-id"]
+    login := msg.Tags["login"]
+    fmt.Printf("🗑️ Message from %s deleted (ID: %s)\n", login, targetMsgID)
+}
+
+func tierName(plan string) string {
+    switch plan {
+    case "Prime":
+        return "Prime"
+    case "1000":
+        return "1"
+    case "2000":
+        return "2"
+    case "3000":
+        return "3"
+    default:
+        return plan
+    }
+}
+```
+
+## Sending Messages
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    irc := helix.NewIRCClient(
+        helix.WithIRCToken("oauth:token"),
+        helix.WithIRCNick("bot_name"),
+    )
+
+    if err := irc.Connect(ctx); err != nil {
+        log.Fatal(err)
+    }
+    defer irc.Close()
+
+    channel := "channel_name"
+    irc.Join(channel)
+
+    // Send a message
+    if err := irc.Say(channel, "Hello, chat!"); err != nil {
+        log.Printf("Failed to send message: %v", err)
+    }
+
+    // Reply to a message
+    if err := irc.Reply(channel, "message-id-here", "This is a reply!"); err != nil {
+        log.Printf("Failed to send reply: %v", err)
+    }
+
+    // Send /me action
+    if err := irc.Say(channel, "/me waves at chat"); err != nil {
+        log.Printf("Failed to send action: %v", err)
+    }
+}
+```
+
+## Auto-Reconnect
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    irc := helix.NewIRCClient(
+        helix.WithIRCToken("oauth:token"),
+        helix.WithIRCNick("bot_name"),
+        helix.WithIRCAutoReconnect(true),
+        helix.WithIRCReconnectHandler(func() {
+            fmt.Println("Reconnected! Rejoining channels...")
+            // Rejoin channels after reconnect
+            irc.Join("channel1")
+            irc.Join("channel2")
+        }),
+        helix.WithIRCErrorHandler(func(err error) {
+            log.Printf("IRC error: %v", err)
+        }),
+    )
+
+    if err := irc.Connect(ctx); err != nil {
+        log.Fatal(err)
+    }
+    defer irc.Close()
+
+    irc.Join("channel1")
+    irc.Join("channel2")
+
+    fmt.Println("Bot running with auto-reconnect...")
+    select {}
+}
+```
+
+## Complete Chat Bot Example
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "math/rand"
+    "strings"
+    "sync"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+type ChatBot struct {
+    irc      *helix.IRCClient
+    commands map[string]CommandFunc
+    cooldown map[string]time.Time
+    cdMu     sync.Mutex
+}
+
+type CommandFunc func(msg *helix.IRCMessage, args []string) string
+
+func NewChatBot(token, nick string) *ChatBot {
+    bot := &ChatBot{
+        commands: make(map[string]CommandFunc),
+        cooldown: make(map[string]time.Time),
+    }
+
+    bot.irc = helix.NewIRCClient(
+        helix.WithIRCToken(token),
+        helix.WithIRCNick(nick),
+        helix.WithIRCAutoReconnect(true),
+        helix.WithIRCMessageHandler(bot.handleMessage),
+    )
+
+    // Register commands
+    bot.commands["!ping"] = func(msg *helix.IRCMessage, args []string) string {
+        return "Pong!"
+    }
+
+    bot.commands["!dice"] = func(msg *helix.IRCMessage, args []string) string {
+        return fmt.Sprintf("@%s rolled a %d!", msg.Tags["display-name"], rand.Intn(6)+1)
+    }
+
+    bot.commands["!uptime"] = func(msg *helix.IRCMessage, args []string) string {
+        // Implement actual uptime check
+        return "Stream has been live for 2 hours!"
+    }
+
+    bot.commands["!commands"] = func(msg *helix.IRCMessage, args []string) string {
+        cmds := make([]string, 0, len(bot.commands))
+        for cmd := range bot.commands {
+            cmds = append(cmds, cmd)
+        }
+        return "Commands: " + strings.Join(cmds, ", ")
+    }
+
+    bot.commands["!8ball"] = func(msg *helix.IRCMessage, args []string) string {
+        answers := []string{
+            "Yes!", "No!", "Maybe...", "Ask again later",
+            "Definitely!", "I don't think so", "It is certain",
+        }
+        return fmt.Sprintf("🎱 %s", answers[rand.Intn(len(answers))])
+    }
+
+    return bot
+}
+
+func (b *ChatBot) handleMessage(msg *helix.IRCMessage) {
+    if msg.Command != "PRIVMSG" {
+        return
+    }
+
+    text := strings.TrimSpace(msg.Text)
+    if !strings.HasPrefix(text, "!") {
+        return
+    }
+
+    parts := strings.Fields(text)
+    if len(parts) == 0 {
+        return
+    }
+
+    cmdName := strings.ToLower(parts[0])
+    args := parts[1:]
+
+    // Check cooldown (5 seconds per user per command)
+    cdKey := fmt.Sprintf("%s:%s:%s", msg.Channel, msg.User, cmdName)
+    b.cdMu.Lock()
+    if lastUse, ok := b.cooldown[cdKey]; ok && time.Since(lastUse) < 5*time.Second {
+        b.cdMu.Unlock()
+        return
+    }
+    b.cooldown[cdKey] = time.Now()
+    b.cdMu.Unlock()
+
+    // Execute command
+    if handler, ok := b.commands[cmdName]; ok {
+        response := handler(msg, args)
+        if response != "" {
+            b.irc.Say(msg.Channel, response)
+        }
+    }
+}
+
+func (b *ChatBot) Connect(ctx context.Context) error {
+    return b.irc.Connect(ctx)
+}
+
+func (b *ChatBot) Join(channel string) error {
+    return b.irc.Join(channel)
+}
+
+func (b *ChatBot) Close() error {
+    return b.irc.Close()
+}
+
+func main() {
+    ctx := context.Background()
+
+    bot := NewChatBot("oauth:your-token", "your_bot_name")
+
+    if err := bot.Connect(ctx); err != nil {
+        log.Fatal(err)
+    }
+    defer bot.Close()
+
+    // Join channels
+    channels := []string{"channel1", "channel2"}
+    for _, ch := range channels {
+        if err := bot.Join(ch); err != nil {
+            log.Printf("Failed to join %s: %v", ch, err)
+        }
+    }
+
+    fmt.Println("Bot is running!")
+    select {}
+}
+```
+
+## IRC vs EventSub Comparison
+
+| Feature | IRC Client | EventSub |
+|---------|-----------|----------|
+| Chat Messages | ✅ Real-time | ✅ Real-time |
+| Latency | Lower (~50ms) | Higher (~200ms) |
+| Message Sending | Direct | Via API |
+| Rate Limits | IRC limits (20/30s) | API limits |
+| Badges/Emotes | In tags | In event data |
+| Subscriptions | USERNOTICE | EventSub events |
+| Bits | In message tags | EventSub events |
+| Raids | USERNOTICE | EventSub events |
+| Moderation | CLEARCHAT/CLEARMSG | EventSub events |
+| Connection | WebSocket to TMI | WebSocket to EventSub |
+
+**Use IRC when:**
+- You need lowest latency chat
+- Building a chat-focused bot
+- You need to send many messages
+
+**Use EventSub when:**
+- You need non-chat events (follows, subs, etc.)
+- Building a dashboard/overlay
+- You need reliable delivery with acknowledgment
+
diff --git a/docs/examples/pubsub-migration.md b/docs/examples/pubsub-migration.md
index d14adc0..5d0c8d3 100644
--- a/docs/examples/pubsub-migration.md
+++ b/docs/examples/pubsub-migration.md
@@ -1,11 +1,30 @@
-# PubSub Migration Example
-
-This example demonstrates how to use the PubSub compatibility layer to receive real-time events using familiar PubSub-style topic subscriptions.
+---
+layout: default
+title: PubSub Migration Example
+description: This example demonstrates how to use the PubSub compatibility layer to receive real-time events using familiar PubSub-style topic subscriptions.
+---
 
 > **Note:** Twitch PubSub was decommissioned on April 14, 2025. This compatibility layer uses EventSub WebSocket internally but provides a PubSub-like API for easier migration.
 
+## Overview
+
+If you're migrating from the old Twitch PubSub system, this compatibility layer provides a familiar API while using EventSub WebSocket under the hood.
+
+**Why use this compatibility layer**:
+- Familiar topic-based subscription model
+- Minimal code changes from old PubSub code
+- Automatic translation of PubSub topics to EventSub subscriptions
+- Same event data, just with EventSub field names
+
+**What changes**:
+- Event field names follow EventSub conventions (slightly different from old PubSub)
+- Some topics create multiple EventSub subscriptions (e.g., subscribe-events creates 3)
+- Uses WebSocket instead of the old PubSub WebSocket endpoint
+
 ## Basic Usage
 
+The PubSub client wraps EventSub WebSocket with a topic-based API similar to the original PubSub.
+
 ```go
 package main
 
@@ -233,3 +252,4 @@ For reference, here are the EventSub event types that PubSub topics map to:
 | `automod-queue` | `automod.message.hold` |
 | `chat_moderator_actions` | `channel.moderate` |
 | `whispers` | `user.whisper.message` |
+
diff --git a/docs/examples/raids-hypetrain.md b/docs/examples/raids-hypetrain.md
new file mode 100644
index 0000000..3b1ce36
--- /dev/null
+++ b/docs/examples/raids-hypetrain.md
@@ -0,0 +1,533 @@
+---
+layout: default
+title: Raids & Hype Train Examples
+description: Manage channel raids and track hype train events.
+---
+
+## Overview
+
+**Raids**: Send your viewers to another channel at the end of your stream
+- Programmatically start and cancel raids
+- React to incoming raids from other channels
+- Build auto-raid systems for friends
+
+**Hype Trains**: Community engagement events triggered by bits and subs
+- Track hype train progress in real-time
+- Display hype train status on overlays
+- React to hype train milestones (level ups)
+- Support for regular, golden kappa, and shared hype trains
+
+## Prerequisites
+
+- **Raids:** `channel:manage:raids` scope
+- **Hype Train:** `channel:read:hype_train` scope
+
+## Start a Raid
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    fromBroadcasterID := "12345" // Your channel
+    toBroadcasterID := "67890"   // Target channel
+
+    // Start a raid
+    raid, err := client.StartRaid(ctx, &helix.StartRaidParams{
+        FromBroadcasterID: fromBroadcasterID,
+        ToBroadcasterID:   toBroadcasterID,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("Raid started!\n")
+    fmt.Printf("  Created at: %s\n", raid.Data[0].CreatedAt)
+    fmt.Printf("  Raid is mature: %v\n", raid.Data[0].IsMature)
+}
+```
+
+## Cancel a Raid
+
+```go
+// Cancel an in-progress raid
+err := client.CancelRaid(ctx, broadcasterID)
+if err != nil {
+    log.Printf("Failed to cancel raid: %v", err)
+} else {
+    fmt.Println("Raid cancelled")
+}
+```
+
+## Handle Raid Events with EventSub
+
+```go
+package main
+
+import (
+    "context"
+    "encoding/json"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    ws := helix.NewEventSubWebSocket(client)
+    if err := ws.Connect(ctx); err != nil {
+        log.Fatal(err)
+    }
+    defer ws.Close()
+
+    // Subscribe to incoming raids (someone raiding you)
+    ws.Subscribe(ctx, helix.EventSubTypeChannelRaid, "1",
+        map[string]string{"to_broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.ChannelRaidEvent](event)
+            fmt.Printf("=== INCOMING RAID ===\n")
+            fmt.Printf("From: %s\n", e.FromBroadcasterUserName)
+            fmt.Printf("Viewers: %d\n", e.Viewers)
+
+            // Welcome the raiders
+            welcomeRaiders(ctx, client, broadcasterID, e)
+        },
+    )
+
+    // Subscribe to outgoing raids (you raiding someone)
+    ws.Subscribe(ctx, helix.EventSubTypeChannelRaid, "1",
+        map[string]string{"from_broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.ChannelRaidEvent](event)
+            fmt.Printf("Raid sent to %s with %d viewers\n",
+                e.ToBroadcasterUserName, e.Viewers)
+        },
+    )
+
+    fmt.Println("Listening for raid events...")
+    select {}
+}
+
+func welcomeRaiders(ctx context.Context, client *helix.Client, broadcasterID string, raid *helix.ChannelRaidEvent) {
+    // Send a shoutout
+    err := client.SendShoutout(ctx, &helix.SendShoutoutParams{
+        FromBroadcasterID: broadcasterID,
+        ToBroadcasterID:   raid.FromBroadcasterUserID,
+        ModeratorID:       broadcasterID,
+    })
+    if err != nil {
+        log.Printf("Failed to send shoutout: %v", err)
+    }
+
+    // Send welcome message
+    message := fmt.Sprintf("Welcome raiders from %s! Thanks for bringing %d viewers!",
+        raid.FromBroadcasterUserName, raid.Viewers)
+    _, _ = client.SendChatMessage(ctx, &helix.SendChatMessageParams{
+        BroadcasterID: broadcasterID,
+        SenderID:      broadcasterID,
+        Message:       message,
+    })
+}
+```
+
+## Get Hype Train Events
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Get hype train events
+    hypeTrain, err := client.GetHypeTrainEvents(ctx, &helix.GetHypeTrainEventsParams{
+        BroadcasterID: broadcasterID,
+        First:         5,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    if len(hypeTrain.Data) == 0 {
+        fmt.Println("No hype train events found")
+        return
+    }
+
+    for _, event := range hypeTrain.Data {
+        fmt.Printf("=== Hype Train ===\n")
+        fmt.Printf("ID: %s\n", event.ID)
+        fmt.Printf("Type: %s\n", event.Type) // regular, golden_kappa, shared
+        fmt.Printf("Level: %d\n", event.Level)
+        fmt.Printf("Total: %d\n", event.Total)
+        fmt.Printf("Progress: %d / %d\n", event.Progress, event.Goal)
+        fmt.Printf("Started: %s\n", event.StartedAt)
+        fmt.Printf("Expires: %s\n", event.ExpiresAt)
+
+        if event.IsSharedTrain {
+            fmt.Printf("Shared train with: ")
+            for _, p := range event.SharedTrainParticipants {
+                fmt.Printf("%s ", p.BroadcasterUserName)
+            }
+            fmt.Println()
+        }
+
+        fmt.Printf("\nTop Contributors:\n")
+        for _, contrib := range event.TopContributions {
+            fmt.Printf("  %s: %d (%s)\n", contrib.UserName, contrib.Total, contrib.Type)
+        }
+        fmt.Println()
+    }
+}
+```
+
+## Get Current Hype Train Status
+
+```go
+// Get the current/most recent hype train status
+status, err := client.GetHypeTrainStatus(ctx, broadcasterID)
+if err != nil {
+    log.Fatal(err)
+}
+
+if len(status.Data) > 0 {
+    ht := status.Data[0]
+    fmt.Printf("Current Hype Train Level: %d\n", ht.Level)
+    fmt.Printf("Progress: %d/%d\n", ht.Progress, ht.Goal)
+    fmt.Printf("Expires: %s\n", ht.ExpiresAt)
+} else {
+    fmt.Println("No active hype train")
+}
+```
+
+## Track Hype Train with EventSub
+
+```go
+package main
+
+import (
+    "context"
+    "encoding/json"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    ws := helix.NewEventSubWebSocket(client)
+    if err := ws.Connect(ctx); err != nil {
+        log.Fatal(err)
+    }
+    defer ws.Close()
+
+    // Subscribe to hype train start (using v2)
+    ws.Subscribe(ctx, helix.EventSubTypeChannelHypeTrainBegin, helix.EventSubVersionHypeTrainV2,
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.HypeTrainBeginEvent](event)
+            fmt.Printf("🚂 HYPE TRAIN STARTED!\n")
+            fmt.Printf("Type: %s\n", e.Type) // regular, golden_kappa, shared
+            fmt.Printf("Level: %d, Goal: %d\n", e.Level, e.Goal)
+            fmt.Printf("Expires: %s\n", e.ExpiresAt)
+
+            if e.IsSharedTrain {
+                fmt.Printf("Shared with: ")
+                for _, p := range e.SharedTrainParticipants {
+                    fmt.Printf("%s ", p.BroadcasterUserName)
+                }
+                fmt.Println()
+            }
+        },
+    )
+
+    // Subscribe to hype train progress
+    ws.Subscribe(ctx, helix.EventSubTypeChannelHypeTrainProgress, helix.EventSubVersionHypeTrainV2,
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.HypeTrainProgressEvent](event)
+            progress := float64(e.Progress) / float64(e.Goal) * 100
+            fmt.Printf("🚂 Level %d: %d/%d (%.1f%%)\n", e.Level, e.Progress, e.Goal, progress)
+            fmt.Printf("   Total: %d\n", e.Total)
+
+            // Show latest contribution
+            if e.LastContribution.UserName != "" {
+                fmt.Printf("   Latest: %s contributed %d via %s\n",
+                    e.LastContribution.UserName,
+                    e.LastContribution.Total,
+                    e.LastContribution.Type)
+            }
+        },
+    )
+
+    // Subscribe to hype train end
+    ws.Subscribe(ctx, helix.EventSubTypeChannelHypeTrainEnd, helix.EventSubVersionHypeTrainV2,
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.HypeTrainEndEvent](event)
+            fmt.Printf("🚂 HYPE TRAIN ENDED!\n")
+            fmt.Printf("Final Level: %d\n", e.Level)
+            fmt.Printf("Total Points: %d\n", e.Total)
+            fmt.Printf("Ended: %s\n", e.EndedAt)
+
+            // Check if this was a new record
+            if e.Level > e.AllTimeHighLevel {
+                fmt.Printf("🎉 NEW ALL-TIME HIGH! Previous: Level %d\n", e.AllTimeHighLevel)
+            }
+
+            fmt.Printf("\nTop Contributors:\n")
+            for i, contrib := range e.TopContributions {
+                fmt.Printf("  %d. %s: %d (%s)\n", i+1, contrib.UserName, contrib.Total, contrib.Type)
+            }
+        },
+    )
+
+    fmt.Println("Listening for hype train events...")
+    select {}
+}
+```
+
+## Hype Train Overlay Example
+
+Build a hype train display overlay:
+
+```go
+package main
+
+import (
+    "context"
+    "encoding/json"
+    "fmt"
+    "log"
+    "sync"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+type HypeTrainTracker struct {
+    Active    bool
+    Level     int
+    Progress  int
+    Goal      int
+    Total     int
+    Type      string
+    ExpiresAt string
+    TopContributions []helix.HypeTrainContribution
+    mu        sync.RWMutex
+}
+
+func (h *HypeTrainTracker) Update(e *helix.HypeTrainProgressEvent) {
+    h.mu.Lock()
+    defer h.mu.Unlock()
+    h.Active = true
+    h.Level = e.Level
+    h.Progress = e.Progress
+    h.Goal = e.Goal
+    h.Total = e.Total
+    h.Type = e.Type
+    h.ExpiresAt = e.ExpiresAt
+    h.TopContributions = e.TopContributions
+}
+
+func (h *HypeTrainTracker) End() {
+    h.mu.Lock()
+    defer h.mu.Unlock()
+    h.Active = false
+}
+
+func (h *HypeTrainTracker) GetStatus() string {
+    h.mu.RLock()
+    defer h.mu.RUnlock()
+
+    if !h.Active {
+        return "No active hype train"
+    }
+
+    progress := float64(h.Progress) / float64(h.Goal) * 100
+    emoji := "🚂"
+    if h.Type == "golden_kappa" {
+        emoji = "✨🚂✨"
+    } else if h.Type == "shared" {
+        emoji = "🚂🤝🚂"
+    }
+
+    return fmt.Sprintf("%s HYPE TRAIN Level %d: %d/%d (%.1f%%) | Total: %d",
+        emoji, h.Level, h.Progress, h.Goal, progress, h.Total)
+}
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    tracker := &HypeTrainTracker{}
+    broadcasterID := "12345"
+
+    ws := helix.NewEventSubWebSocket(client)
+    if err := ws.Connect(ctx); err != nil {
+        log.Fatal(err)
+    }
+    defer ws.Close()
+
+    ws.Subscribe(ctx, helix.EventSubTypeChannelHypeTrainBegin, helix.EventSubVersionHypeTrainV2,
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.HypeTrainBeginEvent](event)
+            tracker.Update(&helix.HypeTrainProgressEvent{
+                Level:    e.Level,
+                Progress: e.Progress,
+                Goal:     e.Goal,
+                Total:    e.Total,
+                Type:     e.Type,
+            })
+            fmt.Println(tracker.GetStatus())
+        },
+    )
+
+    ws.Subscribe(ctx, helix.EventSubTypeChannelHypeTrainProgress, helix.EventSubVersionHypeTrainV2,
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.HypeTrainProgressEvent](event)
+            tracker.Update(e)
+            fmt.Println(tracker.GetStatus())
+        },
+    )
+
+    ws.Subscribe(ctx, helix.EventSubTypeChannelHypeTrainEnd, helix.EventSubVersionHypeTrainV2,
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            tracker.End()
+            fmt.Println("Hype train ended!")
+        },
+    )
+
+    fmt.Println("Hype train tracker running...")
+    select {}
+}
+```
+
+## Auto-Raid Feature
+
+Automatically raid a friend when going offline:
+
+```go
+package main
+
+import (
+    "context"
+    "encoding/json"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    myBroadcasterID := "12345"
+    friendBroadcasterID := "67890" // Auto-raid target
+
+    ws := helix.NewEventSubWebSocket(client)
+    if err := ws.Connect(ctx); err != nil {
+        log.Fatal(err)
+    }
+    defer ws.Close()
+
+    // Subscribe to stream offline event
+    ws.Subscribe(ctx, helix.EventSubTypeStreamOffline, "1",
+        map[string]string{"broadcaster_user_id": myBroadcasterID},
+        func(event json.RawMessage) {
+            fmt.Println("Stream went offline, checking if friend is live...")
+
+            // Check if friend is live
+            streams, err := client.GetStreams(ctx, &helix.GetStreamsParams{
+                UserIDs: []string{friendBroadcasterID},
+            })
+            if err != nil {
+                log.Printf("Failed to check friend's stream: %v", err)
+                return
+            }
+
+            if len(streams.Data) > 0 {
+                fmt.Printf("Friend %s is live! Starting raid...\n", streams.Data[0].UserName)
+
+                _, err := client.StartRaid(ctx, &helix.StartRaidParams{
+                    FromBroadcasterID: myBroadcasterID,
+                    ToBroadcasterID:   friendBroadcasterID,
+                })
+                if err != nil {
+                    log.Printf("Failed to start raid: %v", err)
+                } else {
+                    fmt.Println("Raid started!")
+                }
+            } else {
+                fmt.Println("Friend is not live, no auto-raid")
+            }
+        },
+    )
+
+    fmt.Println("Auto-raid bot running...")
+    select {}
+}
+```
+
diff --git a/docs/examples/schedule-goals.md b/docs/examples/schedule-goals.md
new file mode 100644
index 0000000..861ea58
--- /dev/null
+++ b/docs/examples/schedule-goals.md
@@ -0,0 +1,448 @@
+---
+layout: default
+title: Schedule & Goals Examples
+description: Manage stream schedules and track creator goals.
+---
+
+## Overview
+
+This guide covers two related features for channel management:
+
+**Stream Schedule**: Allow viewers to see when you plan to stream
+- Create one-time and recurring stream segments
+- Set vacation mode when taking breaks
+- Export schedule as iCalendar for calendar apps
+
+**Creator Goals**: Track progress toward milestones
+- Follower goals, subscriber goals, etc.
+- Real-time progress updates via EventSub
+- Display goal progress on overlays
+
+## Prerequisites
+
+- **Schedule:** `channel:manage:schedule` to modify, `channel:read:schedule` to read
+- **Goals:** `channel:read:goals` scope
+
+## Get Stream Schedule
+
+Retrieve a channel's stream schedule including upcoming segments, vacation status, and category information. You can also export the schedule as iCalendar format for integration with calendar applications.
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Get full schedule
+    schedule, err := client.GetChannelStreamSchedule(ctx, &helix.GetChannelStreamScheduleParams{
+        BroadcasterID: broadcasterID,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("=== Schedule for %s ===\n", schedule.Data.BroadcasterName)
+
+    if schedule.Data.Vacation != nil {
+        fmt.Printf("On vacation: %s to %s\n",
+            schedule.Data.Vacation.StartTime, schedule.Data.Vacation.EndTime)
+    }
+
+    for _, segment := range schedule.Data.Segments {
+        fmt.Printf("\n%s\n", segment.Title)
+        fmt.Printf("  Start: %s\n", segment.StartTime.Format(time.RFC1123))
+        fmt.Printf("  End: %s\n", segment.EndTime.Format(time.RFC1123))
+        if segment.Category != nil {
+            fmt.Printf("  Category: %s\n", segment.Category.Name)
+        }
+        fmt.Printf("  Recurring: %v\n", segment.IsRecurring)
+        if segment.CanceledUntil != nil {
+            fmt.Printf("  Canceled until: %s\n", segment.CanceledUntil)
+        }
+    }
+
+    // Get schedule with time filter
+    startTime := time.Now()
+    filteredSchedule, err := client.GetChannelStreamSchedule(ctx, &helix.GetChannelStreamScheduleParams{
+        BroadcasterID: broadcasterID,
+        StartTime:     &startTime,
+        First:         10,
+    })
+
+    // Get schedule as iCalendar
+    ical, err := client.GetChannelICalendar(ctx, broadcasterID)
+    if err != nil {
+        log.Fatal(err)
+    }
+    fmt.Printf("\niCalendar data:\n%s\n", ical)
+}
+```
+
+## Update Schedule Settings
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Update schedule settings (vacation mode)
+    vacationStart := time.Now().AddDate(0, 0, 7)  // Start in 1 week
+    vacationEnd := time.Now().AddDate(0, 0, 14)   // End in 2 weeks
+
+    err := client.UpdateChannelStreamSchedule(ctx, &helix.UpdateChannelStreamScheduleParams{
+        BroadcasterID:     broadcasterID,
+        IsVacationEnabled: boolPtr(true),
+        VacationStartTime: &vacationStart,
+        VacationEndTime:   &vacationEnd,
+        Timezone:          "America/New_York",
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+    fmt.Println("Vacation mode enabled!")
+
+    // Disable vacation mode
+    err = client.UpdateChannelStreamSchedule(ctx, &helix.UpdateChannelStreamScheduleParams{
+        BroadcasterID:     broadcasterID,
+        IsVacationEnabled: boolPtr(false),
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+    fmt.Println("Vacation mode disabled!")
+}
+
+func boolPtr(b bool) *bool { return &b }
+```
+
+## Create Schedule Segments
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Create a one-time stream
+    startTime := time.Now().AddDate(0, 0, 1).Truncate(time.Hour) // Tomorrow at the top of the hour
+    segment, err := client.CreateScheduleSegment(ctx, &helix.CreateScheduleSegmentParams{
+        BroadcasterID: broadcasterID,
+        StartTime:     startTime,
+        Timezone:      "America/New_York",
+        Duration:      180, // 3 hours in minutes
+        IsRecurring:   false,
+        Title:         "Special Event Stream",
+        CategoryID:    "509658", // Just Chatting
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+    fmt.Printf("Created segment: %s (ID: %s)\n", segment.Data.Segments[0].Title, segment.Data.Segments[0].ID)
+
+    // Create a recurring weekly stream
+    weeklyStart := time.Date(2024, 1, 15, 19, 0, 0, 0, time.UTC) // Monday 7 PM
+    recurringSegment, err := client.CreateScheduleSegment(ctx, &helix.CreateScheduleSegmentParams{
+        BroadcasterID: broadcasterID,
+        StartTime:     weeklyStart,
+        Timezone:      "America/New_York",
+        Duration:      240, // 4 hours
+        IsRecurring:   true,
+        Title:         "Weekly Game Night",
+        CategoryID:    "509658",
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+    fmt.Printf("Created recurring segment: %s\n", recurringSegment.Data.Segments[0].Title)
+}
+```
+
+## Update Schedule Segments
+
+```go
+// Update a segment
+updated, err := client.UpdateScheduleSegment(ctx, &helix.UpdateScheduleSegmentParams{
+    BroadcasterID: broadcasterID,
+    ID:            "segment-id",
+    Title:         "Updated Stream Title",
+    CategoryID:    "26936", // Music
+    Duration:      120,
+    IsCanceled:    false,
+})
+if err != nil {
+    log.Fatal(err)
+}
+fmt.Printf("Updated segment: %s\n", updated.Data.Segments[0].Title)
+
+// Cancel a segment (keeps it in schedule but marks as canceled)
+_, err = client.UpdateScheduleSegment(ctx, &helix.UpdateScheduleSegmentParams{
+    BroadcasterID: broadcasterID,
+    ID:            "segment-id",
+    IsCanceled:    true,
+})
+
+// Reschedule a segment
+newStartTime := time.Now().AddDate(0, 0, 3)
+_, err = client.UpdateScheduleSegment(ctx, &helix.UpdateScheduleSegmentParams{
+    BroadcasterID: broadcasterID,
+    ID:            "segment-id",
+    StartTime:     &newStartTime,
+    Timezone:      "America/New_York",
+})
+```
+
+## Delete Schedule Segments
+
+```go
+// Delete a single segment
+err := client.DeleteScheduleSegment(ctx, broadcasterID, "segment-id")
+if err != nil {
+    log.Printf("Failed to delete segment: %v", err)
+}
+
+// Delete all future instances of a recurring segment
+// (Delete the segment itself to remove all future occurrences)
+```
+
+## Get Creator Goals
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Get all active goals
+    goals, err := client.GetCreatorGoals(ctx, broadcasterID)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    if len(goals.Data) == 0 {
+        fmt.Println("No active goals")
+        return
+    }
+
+    fmt.Println("=== Creator Goals ===")
+    for _, goal := range goals.Data {
+        fmt.Printf("\n%s\n", goal.Description)
+        fmt.Printf("  Type: %s\n", goal.Type)
+        fmt.Printf("  Progress: %d / %d (%.1f%%)\n",
+            goal.CurrentAmount, goal.TargetAmount,
+            float64(goal.CurrentAmount)/float64(goal.TargetAmount)*100)
+        fmt.Printf("  Created: %s\n", goal.CreatedAt)
+    }
+}
+```
+
+## Track Goals with EventSub
+
+```go
+package main
+
+import (
+    "context"
+    "encoding/json"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    ws := helix.NewEventSubWebSocket(client)
+    if err := ws.Connect(ctx); err != nil {
+        log.Fatal(err)
+    }
+    defer ws.Close()
+
+    // Subscribe to goal start
+    ws.Subscribe(ctx, helix.EventSubTypeChannelGoalBegin, "1",
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.ChannelGoalEvent](event)
+            fmt.Printf("New goal started: %s\n", e.Description)
+            fmt.Printf("  Type: %s, Target: %d\n", e.Type, e.TargetAmount)
+        },
+    )
+
+    // Subscribe to goal progress
+    ws.Subscribe(ctx, helix.EventSubTypeChannelGoalProgress, "1",
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.ChannelGoalEvent](event)
+            progress := float64(e.CurrentAmount) / float64(e.TargetAmount) * 100
+            fmt.Printf("Goal progress: %d/%d (%.1f%%) - %s\n",
+                e.CurrentAmount, e.TargetAmount, progress, e.Description)
+        },
+    )
+
+    // Subscribe to goal completion
+    ws.Subscribe(ctx, helix.EventSubTypeChannelGoalEnd, "1",
+        map[string]string{"broadcaster_user_id": broadcasterID},
+        func(event json.RawMessage) {
+            e, _ := helix.ParseWSEvent[helix.ChannelGoalEvent](event)
+            if e.IsAchieved {
+                fmt.Printf("GOAL ACHIEVED: %s!\n", e.Description)
+            } else {
+                fmt.Printf("Goal ended (not achieved): %s\n", e.Description)
+            }
+        },
+    )
+
+    fmt.Println("Listening for goal events...")
+    select {}
+}
+```
+
+## Schedule Widget Example
+
+Build a simple schedule display:
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Get upcoming streams
+    startTime := time.Now()
+    schedule, err := client.GetChannelStreamSchedule(ctx, &helix.GetChannelStreamScheduleParams{
+        BroadcasterID: broadcasterID,
+        StartTime:     &startTime,
+        First:         7, // Next 7 segments
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("=== Upcoming Streams for %s ===\n\n", schedule.Data.BroadcasterName)
+
+    if schedule.Data.Vacation != nil {
+        fmt.Printf("⚠️  On vacation until %s\n\n",
+            schedule.Data.Vacation.EndTime.Format("January 2, 2006"))
+    }
+
+    for _, segment := range schedule.Data.Segments {
+        if segment.CanceledUntil != nil {
+            continue // Skip canceled segments
+        }
+
+        // Format the date nicely
+        day := segment.StartTime.Format("Monday, Jan 2")
+        startTimeStr := segment.StartTime.Format("3:04 PM")
+        endTimeStr := segment.EndTime.Format("3:04 PM")
+
+        category := "No category"
+        if segment.Category != nil {
+            category = segment.Category.Name
+        }
+
+        recurring := ""
+        if segment.IsRecurring {
+            recurring = " 🔁"
+        }
+
+        fmt.Printf("📅 %s%s\n", day, recurring)
+        fmt.Printf("   %s - %s\n", startTimeStr, endTimeStr)
+        fmt.Printf("   📺 %s\n", segment.Title)
+        fmt.Printf("   🎮 %s\n\n", category)
+    }
+}
+```
+
diff --git a/docs/examples/videos-clips.md b/docs/examples/videos-clips.md
new file mode 100644
index 0000000..35143ee
--- /dev/null
+++ b/docs/examples/videos-clips.md
@@ -0,0 +1,561 @@
+---
+layout: default
+title: Videos & Clips Examples
+description: Work with VODs, highlights, and clips.
+---
+
+## Overview
+
+Manage video content on Twitch, including:
+
+**Videos (VODs)**: Recorded broadcasts, highlights, and uploads
+- Retrieve video metadata (title, duration, views)
+- Delete videos from your channel
+- Filter by type (archive, highlight, upload), game, and time period
+
+**Clips**: Short highlight moments from streams
+- Create clips from live streams
+- Create clips from VODs at specific timestamps
+- Retrieve clips by broadcaster, game, or clip ID
+- Build automated clip compilation systems
+
+**Stream Markers**: Timestamps you can place during a stream for VOD editing
+- Create markers with descriptions
+- Retrieve markers for a video
+
+## Prerequisites
+
+- **Videos:** `channel:manage:videos` to delete, no scope needed to read
+- **Clips:** `clips:edit` to create clips
+
+## Get Videos (VODs)
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    // Get videos by user ID
+    videos, err := client.GetVideos(ctx, &helix.GetVideosParams{
+        UserID: "12345",
+        First:  10,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("=== Recent Videos ===")
+    for _, video := range videos.Data {
+        fmt.Printf("\n%s\n", video.Title)
+        fmt.Printf("  ID: %s\n", video.ID)
+        fmt.Printf("  Type: %s\n", video.Type) // archive, highlight, upload
+        fmt.Printf("  Duration: %s\n", video.Duration)
+        fmt.Printf("  Views: %d\n", video.ViewCount)
+        fmt.Printf("  Created: %s\n", video.CreatedAt)
+        fmt.Printf("  URL: %s\n", video.URL)
+    }
+
+    // Get specific videos by ID
+    specificVideos, err := client.GetVideos(ctx, &helix.GetVideosParams{
+        IDs: []string{"video-id-1", "video-id-2"},
+    })
+
+    // Get videos by game
+    gameVideos, err := client.GetVideos(ctx, &helix.GetVideosParams{
+        GameID: "509658", // Just Chatting
+        First:  20,
+        Sort:   "views", // time, trending, views
+        Type:   "all",   // all, archive, highlight, upload
+    })
+
+    // Filter by language and period
+    filteredVideos, err := client.GetVideos(ctx, &helix.GetVideosParams{
+        GameID:   "509658",
+        Language: "en",
+        Period:   "week", // all, day, week, month
+    })
+}
+```
+
+## Delete Videos
+
+```go
+// Delete specific videos
+deleted, err := client.DeleteVideos(ctx, []string{"video-id-1", "video-id-2"})
+if err != nil {
+    log.Fatal(err)
+}
+
+fmt.Printf("Deleted %d videos\n", len(deleted.Data))
+for _, id := range deleted.Data {
+    fmt.Printf("  Deleted: %s\n", id)
+}
+```
+
+## Get Clips
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Get clips by broadcaster
+    clips, err := client.GetClips(ctx, &helix.GetClipsParams{
+        BroadcasterID: broadcasterID,
+        First:         20,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("=== Top Clips ===")
+    for _, clip := range clips.Data {
+        fmt.Printf("\n%s\n", clip.Title)
+        fmt.Printf("  ID: %s\n", clip.ID)
+        fmt.Printf("  Creator: %s\n", clip.CreatorName)
+        fmt.Printf("  Views: %d\n", clip.ViewCount)
+        fmt.Printf("  Duration: %.1fs\n", clip.Duration)
+        fmt.Printf("  Created: %s\n", clip.CreatedAt)
+        fmt.Printf("  URL: %s\n", clip.URL)
+        fmt.Printf("  Thumbnail: %s\n", clip.ThumbnailURL)
+    }
+
+    // Get clips by game
+    gameClips, err := client.GetClips(ctx, &helix.GetClipsParams{
+        GameID: "509658",
+        First:  10,
+    })
+
+    // Get specific clips by ID
+    specificClips, err := client.GetClips(ctx, &helix.GetClipsParams{
+        IDs: []string{"clip-id-1", "clip-id-2"},
+    })
+
+    // Get clips from a time range
+    startTime := time.Now().AddDate(0, 0, -7) // Last 7 days
+    endTime := time.Now()
+    recentClips, err := client.GetClips(ctx, &helix.GetClipsParams{
+        BroadcasterID: broadcasterID,
+        StartedAt:     &startTime,
+        EndedAt:       &endTime,
+        First:         50,
+    })
+
+    // Get featured clips
+    featuredClips, err := client.GetClips(ctx, &helix.GetClipsParams{
+        BroadcasterID: broadcasterID,
+        IsFeatured:    true,
+    })
+}
+```
+
+## Create Clips
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Create a clip from live stream
+    clip, err := client.CreateClip(ctx, &helix.CreateClipParams{
+        BroadcasterID: broadcasterID,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("Clip created!\n")
+    fmt.Printf("  ID: %s\n", clip.Data[0].ID)
+    fmt.Printf("  Edit URL: %s\n", clip.Data[0].EditURL)
+
+    // Wait for clip to be processed
+    fmt.Println("Waiting for clip to process...")
+    time.Sleep(15 * time.Second)
+
+    // Get the processed clip
+    processedClip, err := client.GetClips(ctx, &helix.GetClipsParams{
+        IDs: []string{clip.Data[0].ID},
+    })
+    if err == nil && len(processedClip.Data) > 0 {
+        fmt.Printf("Clip ready: %s\n", processedClip.Data[0].URL)
+    }
+
+    // Create clip with delay (captures content from 30 seconds ago)
+    delayedClip, err := client.CreateClip(ctx, &helix.CreateClipParams{
+        BroadcasterID: broadcasterID,
+        HasDelay:      true, // Adds a delay to capture content from slightly before
+    })
+}
+```
+
+## Create Clip from VOD
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    // Create a clip from a VOD
+    clip, err := client.CreateClipFromVOD(ctx, &helix.CreateClipFromVODParams{
+        VideoID:      "video-id",
+        OffsetSeconds: 3600,  // Start at 1 hour mark
+        Duration:      30,    // 30 second clip (5-60 seconds allowed)
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("VOD clip created!\n")
+    fmt.Printf("  ID: %s\n", clip.Data[0].ID)
+    fmt.Printf("  Edit URL: %s\n", clip.Data[0].EditURL)
+}
+```
+
+## Stream Markers
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Create a stream marker
+    marker, err := client.CreateStreamMarker(ctx, &helix.CreateStreamMarkerParams{
+        UserID:      broadcasterID,
+        Description: "Epic moment!",
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("Marker created at %d seconds\n", marker.Data[0].PositionSeconds)
+
+    // Get stream markers
+    markers, err := client.GetStreamMarkers(ctx, &helix.GetStreamMarkersParams{
+        UserID: broadcasterID,
+        First:  20,
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    for _, video := range markers.Data {
+        fmt.Printf("\nVideo: %s\n", video.VideoID)
+        for _, m := range video.Markers {
+            fmt.Printf("  [%d:%02d] %s (ID: %s)\n",
+                m.PositionSeconds/60, m.PositionSeconds%60,
+                m.Description, m.ID)
+        }
+    }
+
+    // Get markers for specific video
+    videoMarkers, err := client.GetStreamMarkers(ctx, &helix.GetStreamMarkersParams{
+        VideoID: "video-id",
+    })
+}
+```
+
+## Clip Compilation Bot
+
+Auto-clip highlights based on chat activity:
+
+```go
+package main
+
+import (
+    "context"
+    "encoding/json"
+    "fmt"
+    "log"
+    "sync"
+    "time"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+type ClipBot struct {
+    client        *helix.Client
+    broadcasterID string
+    chatActivity  int
+    threshold     int
+    cooldown      time.Duration
+    lastClip      time.Time
+    mu            sync.Mutex
+}
+
+func NewClipBot(client *helix.Client, broadcasterID string) *ClipBot {
+    return &ClipBot{
+        client:        client,
+        broadcasterID: broadcasterID,
+        threshold:     50,            // Clip when 50 messages in 10 seconds
+        cooldown:      30 * time.Second,
+    }
+}
+
+func (b *ClipBot) TrackMessage() {
+    b.mu.Lock()
+    defer b.mu.Unlock()
+    b.chatActivity++
+}
+
+func (b *ClipBot) CheckAndClip(ctx context.Context) {
+    b.mu.Lock()
+    activity := b.chatActivity
+    b.chatActivity = 0 // Reset counter
+    canClip := time.Since(b.lastClip) > b.cooldown
+    b.mu.Unlock()
+
+    if activity >= b.threshold && canClip {
+        fmt.Printf("High activity detected (%d messages)! Creating clip...\n", activity)
+
+        clip, err := b.client.CreateClip(ctx, &helix.CreateClipParams{
+            BroadcasterID: b.broadcasterID,
+            HasDelay:      true, // Capture the moment that just happened
+        })
+        if err != nil {
+            log.Printf("Failed to create clip: %v", err)
+            return
+        }
+
+        b.mu.Lock()
+        b.lastClip = time.Now()
+        b.mu.Unlock()
+
+        fmt.Printf("Clip created: %s\n", clip.Data[0].EditURL)
+    }
+}
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+    bot := NewClipBot(client, broadcasterID)
+
+    ws := helix.NewEventSubWebSocket(client)
+    if err := ws.Connect(ctx); err != nil {
+        log.Fatal(err)
+    }
+    defer ws.Close()
+
+    // Track chat messages
+    ws.Subscribe(ctx, helix.EventSubTypeChannelChatMessage, "1",
+        map[string]string{
+            "broadcaster_user_id": broadcasterID,
+            "user_id":             broadcasterID,
+        },
+        func(event json.RawMessage) {
+            bot.TrackMessage()
+        },
+    )
+
+    // Check activity every 10 seconds
+    ticker := time.NewTicker(10 * time.Second)
+    go func() {
+        for range ticker.C {
+            bot.CheckAndClip(ctx)
+        }
+    }()
+
+    fmt.Println("Clip bot running...")
+    select {}
+}
+```
+
+## Video Stats Dashboard
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "sort"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+    client := helix.NewClient("your-client-id", authClient)
+
+    broadcasterID := "12345"
+
+    // Get all videos
+    var allVideos []helix.Video
+    cursor := ""
+    for {
+        resp, err := client.GetVideos(ctx, &helix.GetVideosParams{
+            UserID: broadcasterID,
+            First:  100,
+            After:  cursor,
+        })
+        if err != nil {
+            log.Fatal(err)
+        }
+        allVideos = append(allVideos, resp.Data...)
+        if resp.Pagination == nil || resp.Pagination.Cursor == "" {
+            break
+        }
+        cursor = resp.Pagination.Cursor
+    }
+
+    // Get all clips
+    var allClips []helix.Clip
+    cursor = ""
+    for {
+        resp, err := client.GetClips(ctx, &helix.GetClipsParams{
+            BroadcasterID: broadcasterID,
+            First:         100,
+            After:         cursor,
+        })
+        if err != nil {
+            log.Fatal(err)
+        }
+        allClips = append(allClips, resp.Data...)
+        if resp.Pagination == nil || resp.Pagination.Cursor == "" {
+            break
+        }
+        cursor = resp.Pagination.Cursor
+    }
+
+    // Calculate stats
+    fmt.Println("=== Video & Clip Statistics ===\n")
+
+    // Video stats
+    totalVideoViews := 0
+    videoTypes := map[string]int{}
+    for _, v := range allVideos {
+        totalVideoViews += v.ViewCount
+        videoTypes[v.Type]++
+    }
+
+    fmt.Printf("Videos: %d\n", len(allVideos))
+    fmt.Printf("  Archives: %d\n", videoTypes["archive"])
+    fmt.Printf("  Highlights: %d\n", videoTypes["highlight"])
+    fmt.Printf("  Uploads: %d\n", videoTypes["upload"])
+    fmt.Printf("  Total Views: %d\n", totalVideoViews)
+
+    // Top videos
+    sort.Slice(allVideos, func(i, j int) bool {
+        return allVideos[i].ViewCount > allVideos[j].ViewCount
+    })
+    fmt.Printf("\nTop 5 Videos:\n")
+    for i := 0; i < 5 && i < len(allVideos); i++ {
+        fmt.Printf("  %d. %s (%d views)\n", i+1, allVideos[i].Title, allVideos[i].ViewCount)
+    }
+
+    // Clip stats
+    totalClipViews := 0
+    for _, c := range allClips {
+        totalClipViews += c.ViewCount
+    }
+
+    fmt.Printf("\nClips: %d\n", len(allClips))
+    fmt.Printf("  Total Views: %d\n", totalClipViews)
+
+    // Top clips
+    sort.Slice(allClips, func(i, j int) bool {
+        return allClips[i].ViewCount > allClips[j].ViewCount
+    })
+    fmt.Printf("\nTop 5 Clips:\n")
+    for i := 0; i < 5 && i < len(allClips); i++ {
+        fmt.Printf("  %d. %s (%d views) - by %s\n",
+            i+1, allClips[i].Title, allClips[i].ViewCount, allClips[i].CreatorName)
+    }
+}
+```
+
diff --git a/docs/extension-jwt.md b/docs/extension-jwt.md
index b16da3e..7a2becb 100644
--- a/docs/extension-jwt.md
+++ b/docs/extension-jwt.md
@@ -1,6 +1,8 @@
-# Extension JWT Authentication
-
-Certain Twitch Extension API endpoints require a special **Extension JWT** (JSON Web Token) instead of a regular OAuth access token.
+---
+layout: default
+title: Extension JWT Authentication
+description: Certain Twitch Extension API endpoints require a special **Extension JWT** (JSON Web Token) instead of a regular OAuth access token.
+---
 
 ## How It Works
 
@@ -68,3 +70,4 @@ resp, err := client.GetExtensionConfigurationSegment(ctx, &helix.GetExtensionCon
     BroadcasterID: "67890",
 })
 ```
+
diff --git a/docs/extensions.md b/docs/extensions.md
index b27b220..0297bd3 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -1,12 +1,14 @@
-# Extensions API
-
-Some endpoints require [Extension JWT authentication](extension-jwt.md) instead of standard OAuth tokens.
+---
+layout: default
+title: Extensions API
+description: Some endpoints require [Extension JWT authentication](Projects/Programming/Kappopher/Documents/extension-jwt.md) instead of standard OAuth tokens.
+---
 
 ## GetExtensionConfigurationSegment
 
 Get extension configuration segments (broadcaster, developer, or global).
 
-**Requires:** [Extension JWT](extension-jwt.md)
+**Requires:** [Extension JWT](Projects/Programming/Kappopher/Documents/extension-jwt.md)
 
 ```go
 resp, err := client.GetExtensionConfigurationSegment(ctx, &helix.GetExtensionConfigurationSegmentParams{
@@ -47,7 +49,7 @@ for _, segment := range resp.Data {
 
 Set extension configuration segment data.
 
-**Requires:** [Extension JWT](extension-jwt.md)
+**Requires:** [Extension JWT](Projects/Programming/Kappopher/Documents/extension-jwt.md)
 
 ```go
 err := client.SetExtensionConfigurationSegment(ctx, &helix.SetExtensionConfigurationSegmentParams{
@@ -66,7 +68,7 @@ No response body on success (204 No Content)
 
 Set the required configuration for an extension.
 
-**Requires:** [Extension JWT](extension-jwt.md)
+**Requires:** [Extension JWT](Projects/Programming/Kappopher/Documents/extension-jwt.md)
 
 ```go
 err := client.SetExtensionRequiredConfiguration(ctx, &helix.SetExtensionRequiredConfigurationParams{
@@ -83,7 +85,7 @@ No response body on success (204 No Content)
 
 Send a PubSub message to extension users.
 
-**Requires:** [Extension JWT](extension-jwt.md)
+**Requires:** [Extension JWT](Projects/Programming/Kappopher/Documents/extension-jwt.md)
 
 ```go
 // Broadcast to all users viewing the channel
@@ -157,7 +159,7 @@ for _, channel := range resp.Data {
 
 Get the secrets for an extension.
 
-**Requires:** [Extension JWT](extension-jwt.md)
+**Requires:** [Extension JWT](Projects/Programming/Kappopher/Documents/extension-jwt.md)
 
 ```go
 resp, err := client.GetExtensionSecrets(ctx, "your-extension-id")
@@ -196,7 +198,7 @@ for _, secret := range resp.Data {
 
 Create a new secret for an extension.
 
-**Requires:** [Extension JWT](extension-jwt.md)
+**Requires:** [Extension JWT](Projects/Programming/Kappopher/Documents/extension-jwt.md)
 
 ```go
 // Create a new secret with a 300-second delay before activation
@@ -233,7 +235,7 @@ for _, secret := range resp.Data {
 
 Send a chat message from an extension.
 
-**Requires:** [Extension JWT](extension-jwt.md)
+**Requires:** [Extension JWT](Projects/Programming/Kappopher/Documents/extension-jwt.md)
 
 ```go
 err := client.SendExtensionChatMessage(ctx, &helix.SendExtensionChatMessageParams{
@@ -251,7 +253,7 @@ No response body on success (204 No Content)
 
 Get information about an extension (any version).
 
-**Requires:** [Extension JWT](extension-jwt.md)
+**Requires:** [Extension JWT](Projects/Programming/Kappopher/Documents/extension-jwt.md)
 
 ```go
 // Get latest version
@@ -563,3 +565,4 @@ for _, tx := range resp.Data {
   }
 }
 ```
+
diff --git a/docs/games.md b/docs/games.md
index 645bfd1..df1cd56 100644
--- a/docs/games.md
+++ b/docs/games.md
@@ -1,6 +1,8 @@
-# Games API
-
-Retrieve information about games and categories on Twitch.
+---
+layout: default
+title: Games API
+description: Retrieve information about games and categories on Twitch.
+---
 
 ## GetGames
 
@@ -111,3 +113,4 @@ if resp.Pagination.Cursor != "" {
   }
 }
 ```
+
diff --git a/docs/goals.md b/docs/goals.md
index 088c502..4a3605e 100644
--- a/docs/goals.md
+++ b/docs/goals.md
@@ -1,6 +1,8 @@
-# Goals API
-
-Manage creator goals for Twitch channels.
+---
+layout: default
+title: Goals API
+description: Manage creator goals for Twitch channels.
+---
 
 ## GetCreatorGoals
 
@@ -71,5 +73,5 @@ You can receive real-time updates when goals are created, updated, or achieved u
 - `channel.goal.begin` - A goal is created
 - `channel.goal.progress` - Progress is made toward a goal
 - `channel.goal.end` - A goal ends (achieved or cancelled)
-
 See [EventSub documentation](eventsub.md) for more details.
+
diff --git a/docs/guest-star.md b/docs/guest-star.md
index 16c5430..5cfe861 100644
--- a/docs/guest-star.md
+++ b/docs/guest-star.md
@@ -1,6 +1,8 @@
-# Guest Star API
-
-> **Note:** These are BETA endpoints and may be subject to changes.
+---
+layout: default
+title: Guest Star API
+description: > **Note:** These are BETA endpoints and may be subject to changes.
+---
 
 ## GetChannelGuestStarSettings
 
@@ -343,5 +345,5 @@ if err != nil {
     fmt.Printf("Failed to update slot settings: %v\n", err)
 }
 ```
-
 **Returns:** No response body on success (HTTP 204 No Content)
+
diff --git a/docs/hype-train.md b/docs/hype-train.md
index 8e54bb7..9c796b0 100644
--- a/docs/hype-train.md
+++ b/docs/hype-train.md
@@ -1,6 +1,8 @@
-# Hype Train API
-
-Manage hype train events for Twitch channels.
+---
+layout: default
+title: Hype Train API
+description: Manage hype train events for Twitch channels.
+---
 
 > **Note:** The Get Hype Train Events endpoint is deprecated and will be removed January 15, 2026. Use [EventSub](eventsub.md) for real-time hype train events instead.
 
@@ -187,5 +189,5 @@ For real-time hype train events, use EventSub subscriptions instead of polling t
 - `channel.hype_train.begin` - Hype train starts
 - `channel.hype_train.progress` - Hype train level increases
 - `channel.hype_train.end` - Hype train ends
-
 See [EventSub documentation](eventsub.md) for more details.
+
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..efde3a7
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,75 @@
+---
+layout: default
+title: Kappopher Documentation
+---
+
+<div style="text-align: center; margin-bottom: 2rem;">
+  <img src="{{ '/assets/images/logo.png' | relative_url }}" alt="Kappopher" style="width: 180px; height: 180px;">
+  <h1 style="margin-top: 1rem;">Kappopher</h1>
+  <p style="font-size: 1.125rem; color: #53535F;">A comprehensive Go wrapper for the Twitch Helix API with full endpoint coverage, multiple authentication flows, and real-time event support.</p>
+</div>
+
+## Quick Links
+
+### [Getting Started](quickstart.md)
+Get up and running with Kappopher in minutes.
+
+### [API Reference](api-reference.md)
+Complete documentation for all Twitch Helix API endpoints.
+
+### [Cookbook](cookbook.md)
+Practical code examples and recipes for common use cases.
+
+## Features
+
+- **Full Helix API Coverage** - All endpoints implemented with typed responses
+- **Multiple Auth Flows** - Client Credentials, Authorization Code, Device Code, Implicit
+- **EventSub Support** - WebSocket and Webhook handlers for real-time events
+- **IRC Client** - Built-in chat client for bot development
+- **Batch Operations** - Concurrent requests with rate limiting
+- **Caching** - Built-in response caching with configurable TTL
+
+## Installation
+
+```bash
+go get github.com/Its-donkey/kappopher
+```
+
+## Basic Example
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/Its-donkey/kappopher/helix"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // Create auth client
+    authClient := helix.NewAuthClient(helix.AuthConfig{
+        ClientID:     "your-client-id",
+        ClientSecret: "your-client-secret",
+    })
+
+    // Create Helix client
+    client := helix.NewClient("your-client-id", authClient)
+
+    // Get user info
+    users, err := client.GetUsers(ctx, &helix.GetUsersParams{
+        Logins: []string{"twitchdev"},
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    for _, user := range users.Data {
+        fmt.Printf("User: %s (ID: %s)\n", user.DisplayName, user.ID)
+    }
+}
+```
diff --git a/docs/ingest.md b/docs/ingest.md
index 32882ff..933104e 100644
--- a/docs/ingest.md
+++ b/docs/ingest.md
@@ -1,6 +1,8 @@
-# Ingest Servers API
-
-Get information about Twitch ingest servers for streaming.
+---
+layout: default
+title: Ingest Servers API
+description: Get information about Twitch ingest servers for streaming.
+---
 
 > **Note:** This endpoint uses a different base URL (`ingest.twitch.tv`) than the Helix API.
 
@@ -143,3 +145,4 @@ if server != nil {
 
 **Returns:**
 - `string`: Complete RTMP URL ready for use with streaming software
+
diff --git a/docs/irc-client.md b/docs/irc-client.md
new file mode 100644
index 0000000..ee76f55
--- /dev/null
+++ b/docs/irc-client.md
@@ -0,0 +1,258 @@
+---
+layout: default
+title: IRC/Chat Client
+description: The IRC client provides real-time chat functionality via Twitch's IRC (Internet Relay Chat) interface over WebSocket. This is ideal for building chat bots that need to read and send messages in Twitch channels.
+---
+
+## NewIRCClient
+
+Create a new IRC client for connecting to Twitch chat.
+
+```go
+client := helix.NewIRCClient("bot_username", "oauth:your-token",
+    helix.WithMessageHandler(func(msg *helix.ChatMessage) {
+        fmt.Printf("[%s] %s: %s\n", msg.Channel, msg.User, msg.Text)
+    }),
+)
+```
+
+## NewIRCClientE
+
+Create a new IRC client with error handling for invalid inputs.
+
+```go
+client, err := helix.NewIRCClientE("bot_username", "oauth:your-token",
+    helix.WithAutoReconnect(true),
+)
+if err != nil {
+    log.Fatal(err)
+}
+```
+
+## Connect
+
+Establish a connection to Twitch IRC.
+
+```go
+ctx := context.Background()
+if err := client.Connect(ctx); err != nil {
+    log.Fatal(err)
+}
+defer client.Close()
+```
+
+## Join
+
+Join a channel to receive messages.
+
+```go
+if err := client.Join("channel_name"); err != nil {
+    log.Printf("Failed to join: %v", err)
+}
+```
+
+## Part
+
+Leave a channel.
+
+```go
+if err := client.Part("channel_name"); err != nil {
+    log.Printf("Failed to part: %v", err)
+}
+```
+
+## Say
+
+Send a message to a channel.
+
+```go
+if err := client.Say("channel_name", "Hello, chat!"); err != nil {
+    log.Printf("Failed to send: %v", err)
+}
+```
+
+## Reply
+
+Reply to a specific message.
+
+```go
+if err := client.Reply("channel_name", "message-id", "This is a reply!"); err != nil {
+    log.Printf("Failed to reply: %v", err)
+}
+```
+
+## Close
+
+Close the IRC connection.
+
+```go
+if err := client.Close(); err != nil {
+    log.Printf("Failed to close: %v", err)
+}
+```
+
+## Configuration Options
+
+### WithAutoReconnect
+
+Enable or disable automatic reconnection.
+
+```go
+helix.WithAutoReconnect(true)
+```
+
+### WithReconnectDelay
+
+Set the delay between reconnection attempts.
+
+```go
+helix.WithReconnectDelay(5 * time.Second)
+```
+
+### WithIRCURL
+
+Set a custom WebSocket URL.
+
+```go
+helix.WithIRCURL("wss://custom-irc.example.com")
+```
+
+## Event Handlers
+
+### WithMessageHandler
+
+Handle incoming chat messages.
+
+```go
+helix.WithMessageHandler(func(msg *helix.ChatMessage) {
+    fmt.Printf("%s: %s\n", msg.User, msg.Text)
+})
+```
+
+### WithUserNoticeHandler
+
+Handle user notices (subscriptions, raids, etc.).
+
+```go
+helix.WithUserNoticeHandler(func(notice *helix.UserNotice) {
+    fmt.Printf("User notice: %s\n", notice.MsgID)
+})
+```
+
+### WithRoomStateHandler
+
+Handle room state changes (slow mode, emote-only, etc.).
+
+```go
+helix.WithRoomStateHandler(func(state *helix.RoomState) {
+    fmt.Printf("Room state updated: %s\n", state.Channel)
+})
+```
+
+### WithClearChatHandler
+
+Handle timeout and ban events.
+
+```go
+helix.WithClearChatHandler(func(clear *helix.ClearChat) {
+    fmt.Printf("User %s was timed out\n", clear.TargetUserID)
+})
+```
+
+### WithClearMessageHandler
+
+Handle deleted messages.
+
+```go
+helix.WithClearMessageHandler(func(clear *helix.ClearMessage) {
+    fmt.Printf("Message deleted: %s\n", clear.TargetMsgID)
+})
+```
+
+### WithWhisperHandler
+
+Handle whisper (private) messages.
+
+```go
+helix.WithWhisperHandler(func(whisper *helix.Whisper) {
+    fmt.Printf("Whisper from %s: %s\n", whisper.User, whisper.Text)
+})
+```
+
+### WithJoinHandler
+
+Handle channel join events.
+
+```go
+helix.WithJoinHandler(func(channel, user string) {
+    fmt.Printf("%s joined %s\n", user, channel)
+})
+```
+
+### WithPartHandler
+
+Handle channel leave events.
+
+```go
+helix.WithPartHandler(func(channel, user string) {
+    fmt.Printf("%s left %s\n", user, channel)
+})
+```
+
+### WithConnectHandler
+
+Handle successful connection events.
+
+```go
+helix.WithConnectHandler(func() {
+    fmt.Println("Connected to IRC!")
+})
+```
+
+### WithDisconnectHandler
+
+Handle disconnection events.
+
+```go
+helix.WithDisconnectHandler(func() {
+    fmt.Println("Disconnected from IRC")
+})
+```
+
+### WithReconnectHandler
+
+Handle reconnection events.
+
+```go
+helix.WithReconnectHandler(func() {
+    fmt.Println("Reconnected!")
+    // Rejoin channels
+})
+```
+
+### WithIRCErrorHandler
+
+Handle errors.
+
+```go
+helix.WithIRCErrorHandler(func(err error) {
+    log.Printf("IRC error: %v", err)
+})
+```
+
+### WithRawMessageHandler
+
+Handle raw IRC messages for debugging.
+
+```go
+helix.WithRawMessageHandler(func(raw string) {
+    fmt.Printf("Raw: %s\n", raw)
+})
+```
+
+## See Also
+
+- [IRC Client Examples](examples/irc-client.md) - Complete code examples
+- [Chat Bot Example](examples/chatbot.md) - Building a chat bot
+- [Chat API](chat.md) - Helix API chat endpoints
+
diff --git a/docs/moderation.md b/docs/moderation.md
index 244c682..ee81ca2 100644
--- a/docs/moderation.md
+++ b/docs/moderation.md
@@ -1,6 +1,8 @@
-# Moderation API
-
-Manage channel moderation including bans, moderators, blocked terms, AutoMod, and shield mode.
+---
+layout: default
+title: Moderation API
+description: Manage channel moderation including bans, moderators, blocked terms, AutoMod, and shield mode.
+---
 
 ## GetBannedUsers
 
@@ -782,3 +784,57 @@ for _, channel := range resp.Data {
   }
 }
 ```
+
+## AddSuspiciousUserStatus
+
+Add a suspicious status to a chat user. Suspicious users can be marked as "restricted" (cannot chat) or "monitored" (messages are flagged for review).
+
+**Requires:** `moderator:manage:suspicious_users`
+
+```go
+// Mark a user as restricted (cannot send messages)
+err := client.AddSuspiciousUserStatus(ctx, &helix.AddSuspiciousUserStatusParams{
+    BroadcasterID: "12345",
+    ModeratorID:   "67890",
+    UserID:        "11111",
+    Status:        helix.SuspiciousUserStatusRestricted,
+})
+
+// Mark a user as monitored (messages flagged for review)
+err = client.AddSuspiciousUserStatus(ctx, &helix.AddSuspiciousUserStatusParams{
+    BroadcasterID: "12345",
+    ModeratorID:   "67890",
+    UserID:        "22222",
+    Status:        helix.SuspiciousUserStatusMonitored,
+})
+
+if err != nil {
+    fmt.Printf("Failed to add suspicious user status: %v\n", err)
+}
+```
+
+**Status Values:**
+- `helix.SuspiciousUserStatusRestricted` ("restricted") - User cannot send messages in chat
+- `helix.SuspiciousUserStatusMonitored` ("monitored") - User's messages are flagged for moderator review
+
+**Response:** This endpoint returns 204 No Content on success.
+
+## RemoveSuspiciousUserStatus
+
+Remove a suspicious status from a chat user, allowing them to chat normally again.
+
+**Requires:** `moderator:manage:suspicious_users`
+
+```go
+err := client.RemoveSuspiciousUserStatus(ctx, &helix.RemoveSuspiciousUserStatusParams{
+    BroadcasterID: "12345",
+    ModeratorID:   "67890",
+    UserID:        "11111",
+})
+
+if err != nil {
+    fmt.Printf("Failed to remove suspicious user status: %v\n", err)
+}
+```
+**Response:** This endpoint returns 204 No Content on success.
+
diff --git a/docs/polls.md b/docs/polls.md
index e5017a8..9219634 100644
--- a/docs/polls.md
+++ b/docs/polls.md
@@ -1,6 +1,8 @@
-# Polls API
-
-Manage Twitch polls for a broadcaster's channel.
+---
+layout: default
+title: Polls API
+description: Manage Twitch polls for a broadcaster's channel.
+---
 
 ## GetPolls
 
@@ -270,3 +272,4 @@ fmt.Printf("Ended poll: %s with status %s\n", resp.Data[0].Title, resp.Data[0].S
   ]
 }
 ```
+
diff --git a/docs/predictions.md b/docs/predictions.md
index 12b4f5d..c935d62 100644
--- a/docs/predictions.md
+++ b/docs/predictions.md
@@ -1,6 +1,8 @@
-# Predictions API
-
-Manage Twitch predictions for a broadcaster's channel.
+---
+layout: default
+title: Predictions API
+description: Manage Twitch predictions for a broadcaster's channel.
+---
 
 ## GetPredictions
 
@@ -286,3 +288,4 @@ fmt.Printf("Ended prediction: %s with status %s\n", resp.Data[0].Title, resp.Dat
   ]
 }
 ```
+
diff --git a/docs/pubsub-compat.md b/docs/pubsub-compat.md
index a405bde..29a8730 100644
--- a/docs/pubsub-compat.md
+++ b/docs/pubsub-compat.md
@@ -1,6 +1,8 @@
-# PubSub Compatibility Layer
-
-The PubSub compatibility layer provides a familiar PubSub-style API (`Listen`/`Unlisten` with topic strings) while internally using EventSub WebSocket. This enables a smooth migration path for developers transitioning from the deprecated Twitch PubSub system.
+---
+layout: default
+title: PubSub Compatibility Layer
+description: The PubSub compatibility layer provides a familiar PubSub-style API (`Listen`/`Unlisten` with topic strings) while internally using EventSub WebSocket. This enables a smooth migration path for developers transitioning from the deprecated Twitch PubSub system.
+---
 
 > **Note:** Twitch PubSub was fully decommissioned on April 14, 2025. This compatibility layer uses EventSub under the hood, which is Twitch's current real-time event system.
 
@@ -318,3 +320,4 @@ Key differences:
 2. Uses `context.Context` for all operations
 3. Messages are wrapped in a `PubSubMessage` envelope with the EventSub type
 4. Event payloads use EventSub format (not old PubSub format)
+
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 7cb5ec3..3f98cab 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -1,11 +1,13 @@
-# Quick Start Guide
-
-Get up and running with the Twitch Helix API wrapper.
+---
+layout: default
+title: Quick Start
+description: Get up and running with the Twitch Helix API wrapper.
+---
 
 ## Installation
 
 ```bash
-go get github.com/Its-donkey/helix
+go get github.com/Its-donkey/kappopher
 ```
 
 ## Basic Example
@@ -18,7 +20,7 @@ import (
     "fmt"
     "log"
 
-    "github.com/Its-donkey/helix/helix"
+    "github.com/Its-donkey/kappopher/helix"
 )
 
 func main() {
@@ -200,6 +202,6 @@ fmt.Printf("Requests remaining: %d, resets at: %s\n", remaining, reset)
 
 ## Next Steps
 
-- Browse the [Available Endpoints](README.md#available-endpoints) to see all API methods
-- Check out [complete examples](./examples/) for working code samples
+- Browse the [API Reference](api-reference.md) to see all available endpoints
+- Check out [complete examples](cookbook.md) for working code samples
 - Read the [Auth documentation](auth.md) for detailed authentication info
diff --git a/docs/raids.md b/docs/raids.md
index 74fe594..a5022d8 100644
--- a/docs/raids.md
+++ b/docs/raids.md
@@ -1,6 +1,8 @@
-# Raids API
-
-Manage raids between Twitch channels.
+---
+layout: default
+title: Raids API
+description: Manage raids between Twitch channels.
+---
 
 ## StartRaid
 
@@ -61,3 +63,4 @@ fmt.Println("Raid cancelled successfully")
 ```
 No response body. Returns 204 No Content on success.
 ```
+
diff --git a/docs/schedule.md b/docs/schedule.md
index 8c01809..49c2c4a 100644
--- a/docs/schedule.md
+++ b/docs/schedule.md
@@ -1,6 +1,8 @@
-# Schedule API
-
-Manage Twitch channel stream schedules.
+---
+layout: default
+title: Schedule API
+description: Manage Twitch channel stream schedules.
+---
 
 ## GetChannelStreamSchedule
 
@@ -319,3 +321,4 @@ if err != nil {
 
 **Sample Response:**
 This endpoint returns no content on success (HTTP 204 No Content).
+
diff --git a/docs/search.md b/docs/search.md
index b54a161..6646a45 100644
--- a/docs/search.md
+++ b/docs/search.md
@@ -1,6 +1,8 @@
-# Search API
-
-Search for categories (games) and channels on Twitch.
+---
+layout: default
+title: Search API
+description: Search for categories (games) and channels on Twitch.
+---
 
 ## SearchCategories
 
@@ -147,3 +149,4 @@ if resp.Pagination.Cursor != "" {
   }
 }
 ```
+
diff --git a/docs/streams.md b/docs/streams.md
index d0015db..aa25486 100644
--- a/docs/streams.md
+++ b/docs/streams.md
@@ -1,6 +1,8 @@
-# Streams API
-
-Get information about active streams and manage stream markers.
+---
+layout: default
+title: Streams API
+description: Get information about active streams and manage stream markers.
+---
 
 ## GetStreams
 
@@ -389,4 +391,5 @@ if resp.Pagination.Cursor != "" {
   - `ID` (string): Marker ID
   - `CreatedAt` (string): UTC timestamp when the marker was created
   - `Description` (string): Marker description
-  - `PositionSeconds` (int): Position in the stream (in seconds)
+- `PositionSeconds` (int): Position in the stream (in seconds)
+
diff --git a/docs/subscriptions.md b/docs/subscriptions.md
index 680d505..eda0a4c 100644
--- a/docs/subscriptions.md
+++ b/docs/subscriptions.md
@@ -1,6 +1,8 @@
-# Subscriptions API
-
-Retrieve subscriber information for Twitch channels.
+---
+layout: default
+title: Subscriptions API
+description: Retrieve subscriber information for Twitch channels.
+---
 
 ## GetBroadcasterSubscriptions
 
@@ -156,3 +158,4 @@ if sub != nil {
 
 **Response:**
 - Returns `UserSubscription` object if subscribed, `nil` if not subscribed
+
diff --git a/docs/teams.md b/docs/teams.md
index 1e8742e..48a395d 100644
--- a/docs/teams.md
+++ b/docs/teams.md
@@ -1,6 +1,8 @@
-# Teams API
-
-Retrieve information about Twitch teams and their members.
+---
+layout: default
+title: Teams API
+description: Retrieve information about Twitch teams and their members.
+---
 
 ## GetChannelTeams
 
@@ -111,3 +113,4 @@ for _, team := range resp.Data {
   ]
 }
 ```
+
diff --git a/docs/users.md b/docs/users.md
index a30d11a..f4816d2 100644
--- a/docs/users.md
+++ b/docs/users.md
@@ -1,6 +1,8 @@
-# Users API
-
-Retrieve and manage Twitch user information, blocks, and extensions.
+---
+layout: default
+title: Users API
+description: Retrieve and manage Twitch user information, blocks, and extensions.
+---
 
 ## GetUsers
 
@@ -465,3 +467,4 @@ fmt.Printf("Scopes: %v\n", auth.Scopes)
   ]
 }
 ```
+
diff --git a/docs/videos.md b/docs/videos.md
index 6d8f0bc..b6cac12 100644
--- a/docs/videos.md
+++ b/docs/videos.md
@@ -1,6 +1,8 @@
-# Videos API
-
-Retrieve and manage Twitch videos (VODs, highlights, and uploads).
+---
+layout: default
+title: Videos API
+description: Retrieve and manage Twitch videos (VODs, highlights, and uploads).
+---
 
 ## GetVideos
 
@@ -117,3 +119,4 @@ for _, videoID := range resp.Data {
 
 **Returns:**
 - Array of deleted video IDs
+
diff --git a/docs/whispers.md b/docs/whispers.md
index 879e3d9..8ae8428 100644
--- a/docs/whispers.md
+++ b/docs/whispers.md
@@ -1,6 +1,8 @@
-# Whispers API
-
-Send private whisper messages between Twitch users.
+---
+layout: default
+title: Whispers API
+description: Send private whisper messages between Twitch users.
+---
 
 ## SendWhisper
 
@@ -26,5 +28,5 @@ if err != nil {
 - `Message` (string, required): The whisper message to send (max 500 characters)
 
 **Sample Response:**
-
 Returns `204 No Content` on success with an empty response body.
+