e11y 0.2.0 → 1.0.0

data/docs/use_cases/UC-018-testing-events.md

@@ -52,7 +52,7 @@ end
 
 ## 🎯 Features
 
-> **Implementation:** See [ADR-011: Testing Strategy](../ADR-011-testing-strategy.md) for complete testing architecture, including [Section 3: RSpec Matchers](../ADR-011-testing-strategy.md#3-rspec-matchers), [Section 4: Test Adapters](../ADR-011-testing-strategy.md#4-test-adapters), [Section 6: Snapshot Testing](../ADR-011-testing-strategy.md#6-snapshot-testing), and [Section 8: Integration Testing](../ADR-011-testing-strategy.md#8-integration-testing).
+> **Implementation:** See [ADR-011: Testing Strategy](../architecture/ADR-011-testing-strategy.md) for complete testing architecture, including [Section 3: RSpec Matchers](../architecture/ADR-011-testing-strategy.md#3-rspec-matchers), [Section 4: Test Adapters](../architecture/ADR-011-testing-strategy.md#4-test-adapters), [Section 6: Snapshot Testing](../architecture/ADR-011-testing-strategy.md#6-snapshot-testing), and [Section 8: Integration Testing](../architecture/ADR-011-testing-strategy.md#8-integration-testing).
 
 ### 1. RSpec Matchers
 
@@ -325,7 +325,7 @@ end
 
 ### 6. Test Environment Configuration (C13)
 
-> **Implementation:** See [ADR-011 Section 10: Test Environment Configuration](../ADR-011-testing-strategy.md#10-test-environment-configuration) for detailed rationale on disabling production features in tests.
+> **Implementation:** See [ADR-011 Section 10: Test Environment Configuration](../architecture/ADR-011-testing-strategy.md#10-test-environment-configuration) for detailed rationale on disabling production features in tests.
 
 **Critical: Production features MUST be disabled in tests for predictability.**
 
@@ -387,7 +387,7 @@ RSpec.configure do |config|
       ]
       
       # === OPTIONAL: Disable rate limiting ===
-      config.rate_limiting.enabled = false
+      config.rate_limiting_enabled = false
       
       # === OPTIONAL: Disable PII filtering (test data is fake) ===
       config.pii_filtering.enabled = false

data/docs/use_cases/UC-019-retention-based-routing.md

@@ -53,24 +53,26 @@ class AuditEvent < E11y::Event::Base
 end
 ```
 
-**Centralized Routing:**
+**Routing at collection** (where to write now):
 ```ruby
 E11y.configure do |config|
   config.routing_rules = [
     ->(event) { :audit_encrypted if event[:audit_event] },
     ->(event) {
       days = (Time.parse(event[:retention_until]) - Time.now) / 86400
-      days > 90 ? :s3_glacier : :loki
+      days <= 7 ? :stdout : :loki  # Short retention → cheap storage at collection
     }
   ]
 end
 ```
 
 **Result:**
-- ✅ **80-97% cost savings** (automatic tiered routing)
-- ✅ **Compliance enforcement** (audit → encrypted storage)
+- ✅ **Cost savings** (short retention → stdout, not Loki)
+- ✅ **Compliance** (audit → encrypted storage)
 - ✅ **Developer experience** (declare intent, routing handles rest)
 
+> **Archival is a separate moment.** E11y collects events in real time and writes to Loki (hot storage). Each event carries `retention_until` (ISO8601) in its payload. **Archival** (hot → warm → cold) is done by a **separate job** (cron, Loki compaction, export script) — not at collection time. The job filters logs by `retention_until`: `WHERE retention_until > ?` — simple, no custom logic, easy cost control.
+
 ---
 
 ## 🎯 Use Case Scenarios
@@ -140,11 +142,8 @@ E11y.configure do |config|
     # Priority 1: Audit events always to encrypted storage
     ->(event) { :audit_encrypted if event[:audit_event] },
     
-    # Priority 2: Long retention to cold storage
-    ->(event) {
-      days = (Time.parse(event[:retention_until]) - Time.now) / 86400
-      :s3_glacier if days > 90 && !event[:audit_event]
-    }
+    # Other events → Loki (archival job handles cold tier later)
+    ->(event) { :loki }
   ]
 end
 
@@ -170,8 +169,8 @@ UserDeletedEvent.track(
 - ✅ **Immutable** → audit trail tamper-proof
 
 **Cost Impact:**
-- **Before:** Loki storage (30 days, then manual S3) = $5000/month
-- **After:** Audit-encrypted + S3 Glacier (automatic) = $50/month
+- **Before:** Loki storage (30 days, manual export) = $5000/month
+- **After:** Audit-encrypted at collection; archival job (separate) exports to cold tier by `retention_until` = $50/month
 - **Savings:** 99% ($4950/month)
 
 ---
@@ -192,37 +191,21 @@ class OrderPlacedEvent < E11y::Event::Base
   end
 end
 
-# Configuration
+# At collection: all events → Loki. retention_until in payload.
+# Archival job (cron, separate): filters Loki by retention_until, exports to warm/cold.
 E11y.configure do |config|
-  config.routing_rules = [
-    ->(event) {
-      days = (Time.parse(event[:retention_until]) - Time.now) / 86400
-      case days
-      when 0..30   then :loki        # Hot storage
-      when 31..90  then :s3_standard # Warm storage
-      else              :s3_glacier   # Cold storage
-      end
-    }
-  ]
+  config.routing_rules = [->(_event) { :loki }]
 end
 
 # Usage
-OrderPlacedEvent.track(
-  order_id: "ORD-123",
-  amount: 10000,
-  currency: "USD"
-)
-# ↓
-# retention_until: "2026-04-21T10:30:00Z" (90 days from now)
-# ↓
-# Routing: days = 90 → :s3_standard adapter (warm storage)
-# ↓
-# Event written to S3 Standard (cost-optimized)
+OrderPlacedEvent.track(order_id: "ORD-123", amount: 10000, currency: "USD")
+# → Written to Loki with retention_until: "2026-04-21T..."
+# → Archival job (runs later): WHERE retention_until > now + 30d → export to cold
 ```
 
 **Cost Impact:**
-- **Before:** Loki only = $200/month
-- **After:** Loki (30d) + S3 Standard (60d) = $120/month
+- **Before:** Loki only, no tiering = $200/month
+- **After:** Loki at collection; archival job exports by `retention_until` to cheaper storage = $120/month
 - **Savings:** 40% ($80/month)
 
 ---
@@ -243,17 +226,11 @@ class PaymentFailedEvent < E11y::Event::Base
   end
 end
 
-# Configuration
+# At collection: errors → Sentry + Loki. retention_until in payload for archival.
 E11y.configure do |config|
   config.routing_rules = [
-    # Rule 1: Errors always to Sentry
-    ->(event) { :sentry if event[:severity] == :error },
-    
-    # Rule 2: Retention-based storage
-    ->(event) {
-      days = (Time.parse(event[:retention_until]) - Time.now) / 86400
-      days > 30 ? :s3_standard : :loki
-    }
+    ->(event) { [:sentry, :loki] if event[:severity] == :error },
+    ->(_event) { :loki }
   ]
 end
 
@@ -268,14 +245,14 @@ PaymentFailedEvent.track(
 # ↓
 # Routing: 
 #   Rule 1: :sentry (error alerting)
-#   Rule 2: :s3_standard (90 days storage)
+#   Rule 2: :loki (archival job handles tiers later)
 # ↓
 # Event written to BOTH adapters
 ```
 
 **Benefits:**
 - ✅ **Alerting:** Sentry catches errors immediately
-- ✅ **Storage:** S3 Standard for 90-day retention
+- ✅ **Storage:** Loki at collection; archival job (separate) exports by `retention_until`
 - ✅ **Cost:** No duplicate Loki storage ($100/month savings)
 
 ---
@@ -345,17 +322,24 @@ CriticalPaymentEvent.track(amount: 100000, user_id: 789)
 │                                 │
 │  Apply routing rules:           │
 │  - Rule 1: audit → encrypted    │
-│  - Rule 2: >90d → cold storage  │
-│  - Rule 3: <30d → hot storage   │
+│  - Rule 2: errors → Sentry + Loki  │
+│  - Rule 3: default → Loki          │
 └─────────────────────────────────┘
                 │
                 ▼
         ┌───────┴───────┐
         │               │
   ┌─────▼─────┐   ┌─────▼─────┐
-  │  Adapter  │   │  Adapter  │
-  │   Loki    │   │   S3      │
+  │   Loki    │   │  Sentry   │  (at collection)
   └───────────┘   └───────────┘
+        │
+        │ retention_until in payload
+        ▼
+  ┌─────────────────────────────┐
+  │ Archival job (separate)     │
+  │ Filters by retention_until │
+  │ → export to cold storage    │
+  └─────────────────────────────┘
 ```
 
 ### Component Responsibilities
@@ -365,7 +349,7 @@ CriticalPaymentEvent.track(amount: 100000, user_id: 789)
 | **Event::Base** | Declare `retention_period`, calculate `retention_until` |
 | **Configuration** | Define `routing_rules` (lambdas), `default_retention_period` |
 | **Routing Middleware** | Apply rules, select adapters, write events |
-| **Adapters** | Write events to storage (Loki, S3, Sentry, etc.) |
+| **Adapters** | Write events to storage (Loki, File, Sentry, etc.) |
 
 ---
 
@@ -400,73 +384,36 @@ end
 
 ```ruby
 # config/initializers/e11y.rb
+# At collection: route to Loki (or stdout for very short retention).
+# retention_until is in every event payload — archival job (separate) uses it later.
 E11y.configure do |config|
-  # Default retention (fallback)
   config.default_retention_period = 30.days
   
-  # Routing rules (evaluated in order)
   config.routing_rules = [
-    # Priority 1: Audit events → encrypted storage
-    ->(event) {
-      :audit_encrypted if event[:audit_event]
-    },
-    
-    # Priority 2: Errors → Sentry + storage
-    ->(event) {
-      [:sentry, :loki] if event[:severity] == :error
-    },
-    
-    # Priority 3: Retention-based tiering
+    ->(event) { :audit_encrypted if event[:audit_event] },
+    ->(event) { [:sentry, :loki] if event[:severity] == :error },
     ->(event) {
       days = (Time.parse(event[:retention_until]) - Time.now) / 86400
-      case days
-      when 0..7    then :stdout       # Very short → console
-      when 8..30   then :loki         # Short → hot storage
-      when 31..90  then :s3_standard  # Medium → warm storage
-      else              :s3_glacier    # Long → cold storage
-      end
+      days <= 7 ? :stdout : :loki  # Short → cheap, long → Loki
     }
   ]
   
-  # Fallback if no rule matches
   config.fallback_adapters = [:stdout]
-  
-  # Register adapters
-  config.add_adapter :loki, E11y::Adapters::Loki.new(...)
-  config.add_adapter :s3_standard, E11y::Adapters::File.new(path: 's3://bucket/warm/')
-  config.add_adapter :s3_glacier, E11y::Adapters::File.new(path: 's3://bucket/cold/')
-  config.add_adapter :audit_encrypted, E11y::Adapters::AuditEncrypted.new(...)
-  config.add_adapter :sentry, E11y::Adapters::Sentry.new(...)
+  config.adapters[:loki] = E11y::Adapters::Loki.new(...)
+  config.adapters[:audit_encrypted] = E11y::Adapters::AuditEncrypted.new(...)
+  config.adapters[:sentry] = E11y::Adapters::Sentry.new(...)
 end
 ```
 
-### Step 3: Test Routing
+### Step 3: Archival Job (Separate Process)
+
+Archival runs **later**, not at collection. Example cron job:
 
 ```ruby
-# spec/e11y/routing_spec.rb
-RSpec.describe "Retention-based routing" do
-  it "routes debug events to stdout" do
-    event = DebugEvent.track(query: "SELECT...")
-    
-    expect(event[:retention_until]).to eq(7.days.from_now.iso8601)
-    expect(E11y.configuration.adapters[:stdout]).to have_received(:write)
-  end
-  
-  it "routes audit events to encrypted storage" do
-    event = UserDeletedEvent.track(user_id: 123, deleted_by: 456)
-    
-    expect(event[:retention_until]).to eq(7.years.from_now.iso8601)
-    expect(event[:audit_event]).to be true
-    expect(E11y.configuration.adapters[:audit_encrypted]).to have_received(:write)
-  end
-  
-  it "routes long retention to cold storage" do
-    event = BusinessEvent.track(data: "...")
-    allow(event).to receive(:[]).with(:retention_until).and_return(365.days.from_now.iso8601)
-    
-    expect(E11y.configuration.adapters[:s3_glacier]).to have_received(:write)
-  end
-end
+# lib/tasks/archival.rake or separate service
+# Runs daily: reads Loki, filters by retention_until, exports to cold storage
+# SELECT * FROM logs WHERE retention_until > ? AND timestamp < ?
+# → export to S3 / object storage
 ```
 
 ---
@@ -506,8 +453,8 @@ end
 
 **Monthly Costs:**
 - Debug logs (7d in stdout): **$0** ✅
-- Business events (30d Loki + 60d S3): **$120** ✅
-- Audit logs (7y S3 Glacier): **$50** ✅
+- Business events (Loki + archival job exports by retention_until): **$120** ✅
+- Audit logs (audit_encrypted + archival job): **$50** ✅
 - **Total: $170/month**
 
 **Savings: 97% ($5,530/month)**
@@ -573,7 +520,7 @@ end
 
 - ✅ **100% of audit events** go to `audit_encrypted` adapter
 - ✅ **Debug logs** (7d retention) → stdout (free)
-- ✅ **Business events** (90d retention) → tiered storage (Loki + S3)
+- ✅ **Business events** (90d retention) → Loki at collection; archival job exports by `retention_until`
 - ✅ **Cost reduction** of 80%+ compared to manual adapter selection
 - ✅ **Zero manual intervention** (routing is automatic)
 

data/docs/use_cases/UC-020-event-versioning.md

@@ -186,7 +186,7 @@ end
 
 ## 🏗️ Architecture
 
-> **Implementation:** See [ADR-012: Event Evolution](../ADR-012-event-evolution.md) for complete versioning architecture, including [Section 3: Naming Convention](../ADR-012-event-evolution.md#3-naming-convention), [Section 4: Version in Payload](../ADR-012-event-evolution.md#4-version-in-payload), [Section 6: Event Registry Integration](../ADR-012-event-evolution.md#6-event-registry-integration), and [Section 7: Migration Strategy](../ADR-012-event-evolution.md#7-migration-strategy).
+> **Implementation:** See [ADR-012: Event Evolution](../architecture/ADR-012-event-evolution.md) for complete versioning architecture, including [Section 3: Naming Convention](../architecture/ADR-012-event-evolution.md#3-naming-convention), [Section 4: Version in Payload](../architecture/ADR-012-event-evolution.md#4-version-in-payload), [Section 6: Event Registry Integration](../architecture/ADR-012-event-evolution.md#6-event-registry-integration), and [Section 7: Migration Strategy](../architecture/ADR-012-event-evolution.md#7-migration-strategy).
 
 ### Version Management
 
@@ -195,7 +195,7 @@ end
 │ Event Registry (tracks all versions)                            │
 │                                                                  │
 │  event_name: 'order.paid'                                       │
-│    ├─ V1: OrderPaidV1                                           │
+│    ├─ V1: OrderPaid (no suffix per ADR-012)                     │
 │    ├─ V2: OrderPaidV2 (current)                                 │
 │    └─ V3: OrderPaidV3 (future)                                  │
 │                                                                  │
@@ -209,7 +209,7 @@ end
 │  {                                                               │
 │    "@timestamp": "2026-01-12T10:30:00Z",                        │
 │    "event_name": "order.paid",                                  │
-│    "event_version": 2,        ← Version included!               │
+│    "v": 2,                     ← Version (ADR-012 uses v: for V2+)               │
 │    "payload": {                                                  │
 │      "order_id": "123",                                          │
 │      "amount": 99.99,                                            │
@@ -231,9 +231,8 @@ E11y.configure do |config|
   config.versioning do
     enabled true
     
-    # Include version in event payload
+    # Include version in event payload (ADR-012: field name is v: for V2+)
     include_version_in_payload true
-    version_field :event_version  # Field name
     
     # Deprecation warnings
     warn_on_deprecated_version true
@@ -475,9 +474,9 @@ end
 
 **4. Use semantic versioning for major changes**
 ```ruby
-# ✅ GOOD: Major version for major changes
-class OrderPaidV1 < E11y::Event::Base
-  version 1  # Initial version
+# ✅ GOOD: V1 no suffix (ADR-012), V2+ with suffix
+class OrderPaid < E11y::Event::Base
+  version 1  # Initial version (no V1 suffix)
 end
 
 class OrderPaidV2 < E11y::Event::Base
@@ -599,7 +598,7 @@ class OrderPaid < E11y::Event::Base  # V1
     # Track deprecation usage
     Events::DeprecatedEventUsed.track(
       event_class: 'OrderPaid',
-      event_version: 1,
+      version: 1,
       service: ENV['SERVICE_NAME']
     )
   end

data/docs/use_cases/UC-021-error-handling-retry-dlq.md

@@ -34,7 +34,7 @@
 
 - **Retry Policy:** Exponential backoff with jitter
 - **Dead Letter Queue:** Failed events stored for later analysis/replay
-- **Circuit Breaker:** Prevent cascading failures (already covered in UC-011)
+- **Circuit Breaker:** Prevent cascading failures (see [ADR-013 §5](../architecture/ADR-013-reliability-error-handling.md#5-circuit-breaker))
 - **Observability:** Metrics for failures, retries, DLQ size
 
 **Result:** Zero data loss, resilient to transient failures.
@@ -150,21 +150,17 @@ E11y::DeadLetterQueue.size  # => 1000 (mostly garbage)
 
 **With DLQ filter (GOOD!):**
 ```ruby
-# Config:
-E11y.configure do |config|
-  config.error_handling.dead_letter_queue.filter do
-    # Don't save health checks to DLQ
-    never_save do
-      event_patterns ['health_check.*', 'ping.*']
-    end
-    
-    # Always save payments
-    always_save do
-      event_patterns ['payment.*', 'order.*']
-    end
-  end
+# Event DSL: declare DLQ behavior per event class
+class Events::HealthCheck < E11y::Event::Base
+  use_dlq false  # Never save to DLQ
+end
+
+class Events::PaymentFailed < E11y::Event::Base
+  use_dlq true  # Always save to DLQ
 end
 
+# Audit events (Presets::AuditEvent) have use_dlq true by default
+
 # Health checks (not saved to DLQ):
 1000.times do
   Events::HealthCheck.track(status: 'ok')
@@ -183,7 +179,7 @@ E11y::DeadLetterQueue.size  # => 1 (only payment)
 
 ## 🏗️ Architecture
 
-> **Implementation:** See [ADR-013: Reliability & Error Handling](../ADR-013-reliability-error-handling.md) for complete error handling architecture, including retry policy with exponential backoff and jitter, circuit breaker pattern, Dead Letter Queue (DLQ) storage strategies, and self-monitoring metrics.
+> **Implementation:** See [ADR-013: Reliability & Error Handling](../architecture/ADR-013-reliability-error-handling.md) for complete error handling architecture, including retry policy with exponential backoff and jitter, circuit breaker pattern, Dead Letter Queue (DLQ) storage strategies, and self-monitoring metrics.
 
 ### Retry Pipeline
 
@@ -445,7 +441,7 @@ E11y::DeadLetterQueue.replay(
 ### DLQ Replay with PII & Schema Considerations (C07, C15)
 
 > **⚠️ CRITICAL:** DLQ replay requires special handling for PII filtering and schema migrations.  
-> **See:** [ADR-006 Section 5.6](../ADR-006-security-compliance.md#56-pii-handling-for-event-replay-from-dlq-c07-resolution) for C07 (PII double-hashing), [ADR-012 Section 8](../ADR-012-event-evolution.md#8-schema-migrations-and-dlq-replay-c15-resolution--critical) for C15 (schema migrations).
+> **See:** [ADR-006 Section 5.6](../architecture/ADR-006-security-compliance.md#56-pii-handling-for-event-replay-from-dlq-c07-resolution) for C07 (PII double-hashing), [ADR-012 Section 8](../architecture/ADR-012-event-evolution.md#8-schema-migrations-and-dlq-replay-c15-resolution--critical) for C15 (schema migrations).
 
 **Problem 1: PII Double-Hashing on Replay (C07)**
 
@@ -490,7 +486,7 @@ E11y.configure do |config|
     
     # === CRITICAL: Enable replay metadata (C07) ===
     # Replay service automatically adds flags:
-    # - :replayed => true (skip transformations)
+    # - :dlq_replayed => true (skip transformations)
     # - :pii_filtered => true (already filtered)
     mark_replayed_events true  # ← Default: true
   end
@@ -505,13 +501,13 @@ module E11y
         
         # ✅ CRITICAL: Add replay metadata flags
         event_data[:metadata] ||= {}
-        event_data[:metadata][:replayed] = true
+        event_data[:metadata][:dlq_replayed] = true
         event_data[:metadata][:pii_filtered] = true  # Already filtered!
         event_data[:metadata][:replayed_at] = Time.now.utc.iso8601
         event_data[:metadata][:original_event_id] = event_data[:event_id]
         
         # Send through pipeline
-        # PII filter middleware will skip (checks :replayed flag)
+        # PII filter middleware will skip (checks :dlq_replayed flag)
         E11y::Pipeline.process(event_data)
       end
     end
@@ -535,7 +531,7 @@ class PiiFilter < Base
   
   def already_filtered?(event_data)
     metadata = event_data[:metadata] || {}
-    metadata[:replayed] || metadata[:pii_filtered]
+    metadata[:dlq_replayed] || metadata[:pii_filtered]
   end
 end
 
@@ -603,7 +599,7 @@ E11y::DeadLetterQueue.replay_all
        # Lenient validation for replayed events
        # (user chooses to allow old schema)
        lenient_mode_if do |event_data|
-         event_data.dig(:metadata, :replayed) == true
+         event_data.dig(:metadata, :dlq_replayed) == true
        end
      end
    end
@@ -637,7 +633,7 @@ E11y::DeadLetterQueue.replay_all
 | Decision | Pro | Con | Mitigation |
 |----------|-----|-----|------------|
 | **Metadata flags** | Simple, automatic | Metadata size +24 bytes | Acceptable overhead |
-| **`:replayed` flag** | Clear intent | None | ✅ Best practice |
+| **`:dlq_replayed` flag** | Clear intent | None | ✅ Best practice |
 | **Skip PII filter** | Prevents double-hashing | Must trust DLQ integrity | DLQ stored securely (encrypted) |
 
 **Trade-offs (C15):**

data/docs/use_cases/UC-022-event-registry.md

@@ -18,10 +18,9 @@
    - Need to grep codebase to find event classes
    - Hard to document all events
 
-2. **No runtime introspection**
+2. **No runtime discovery**
    - Can't list all registered events at runtime
    - Can't find event class by name
-   - Can't inspect event schema programmatically
 
 3. **Hard to build tooling**
    - Can't build event explorer UI (no registry)
@@ -34,7 +33,7 @@
 
 - Automatic registration of all event classes
 - Query registry by event name, version, adapter
-- Schema introspection (fields, types, validations)
+- Query by name, severity, adapter (find, where)
 - Build developer tools (event explorer, documentation generator)
 
 **Result:** Full visibility into all events in the system.
@@ -53,7 +52,7 @@ $ grep -r "class.*< E11y::Event::Base" app/events/
 # → Manual, error-prone, outdated
 
 # With registry (AUTOMATIC):
-E11y::Registry.all_events
+E11y::Registry.event_classes
 # => [
 #   Events::OrderCreated,
 #   Events::OrderPaid,
@@ -63,7 +62,7 @@ E11y::Registry.all_events
 # ]
 
 # Generate documentation:
-E11y::Registry.all_events.each do |event_class|
+E11y::Registry.event_classes.each do |event_class|
   puts "## #{event_class.event_name}"
   puts "Version: #{event_class.version}"
   puts "Schema: #{event_class.schema_definition}"
@@ -135,7 +134,7 @@ event.severity_level
 # Rails controller for event explorer
 class EventExplorerController < ApplicationController
   def index
-    @events = E11y::Registry.all_events.map do |event_class|
+    @events = E11y::Registry.event_classes.map do |event_class|
       {
         name: event_class.event_name,
         version: event_class.version,
@@ -193,8 +192,8 @@ end
 │                                                                  │
 │  Indexes:                                                        │
 │  - by_name: 'order.created' → Events::OrderCreatedV2            │
-│  - by_adapter: :sentry → [Events::PaymentFailed, ...]           │
-│  - by_severity: :error → [Events::SystemError, ...]             │
+│  - where(adapter: :sentry) → [Events::PaymentFailed, ...]       │
+│  - where(severity: :error) → [Events::SystemError, ...]         │
 │  - by_version: 2 → [Events::OrderCreatedV2, ...]                │
 └─────────────────────────────────────────────────────────────────┘
 ```
@@ -239,7 +238,6 @@ E11y.configure do |config|
     ]
     
     # Registry features
-    enable_introspection true
     enable_event_explorer true  # Web UI at /e11y/events
   end
 end
@@ -249,13 +247,13 @@ end
 
 ## 📝 Registry API
 
-> **Implementation:** See [ADR-010 Section 5: Event Registry](../ADR-010-developer-experience.md#5-event-registry) for full registry architecture, including event discovery API, introspection, version tracking, and dynamic dispatch.
+> **Implementation:** See [ADR-010 Section 5: Event Registry](../architecture/ADR-010-developer-experience.md#5-event-registry) for full registry architecture (find, event_classes, where, to_documentation).
 
 ### Query Events
 
 ```ruby
 # === List All Events ===
-E11y::Registry.all_events
+E11y::Registry.event_classes
 # => [Events::OrderCreated, Events::OrderPaid, ...]
 
 E11y::Registry.count
@@ -278,10 +276,6 @@ E11y::Registry.where(severity: :error)
 E11y::Registry.where(version: 2)
 # => [Events::OrderCreatedV2, Events::OrderPaidV2, ...]
 
-# === Search ===
-E11y::Registry.search('payment')
-# => [Events::PaymentProcessed, Events::PaymentFailed, ...]
-
 # === Filtering ===
 E11y::Registry.filter do |event_class|
   event_class.adapters.include?(:sentry) &&
@@ -427,7 +421,7 @@ namespace :e11y do
     output.puts "Total events: #{E11y::Registry.count}"
     output.puts
     
-    E11y::Registry.all_events.each do |event_class|
+    E11y::Registry.event_classes.each do |event_class|
       output.puts "## #{event_class.event_name}"
       output.puts
       output.puts "**Version:** #{event_class.version}"
@@ -475,7 +469,7 @@ namespace :e11y do
   task validate: :environment do
     errors = []
     
-    E11y::Registry.all_events.each do |event_class|
+    E11y::Registry.event_classes.each do |event_class|
       # Check: has example payload
       if event_class.example_payloads.empty?
         errors << "#{event_class.name} has no example payloads"
@@ -522,7 +516,7 @@ namespace :e11y do
       paths: {}
     }
     
-    E11y::Registry.all_events.each do |event_class|
+    E11y::Registry.event_classes.each do |event_class|
       spec[:paths]["/events/#{event_class.event_name}"] = {
         post: {
           summary: "Track #{event_class.event_name} event",
@@ -557,9 +551,9 @@ end
 
 ```ruby
 RSpec.describe E11y::Registry do
-  describe '.all_events' do
+  describe '.event_classes' do
     it 'returns all registered events' do
-      events = E11y::Registry.all_events
+      events = E11y::Registry.event_classes
       
       expect(events).to include(Events::OrderCreated)
       expect(events).to include(Events::OrderPaid)
@@ -636,7 +630,7 @@ end
 
 - [ ] Enable registry in config
 - [ ] Enable eager loading of event classes
-- [ ] Access registry: `E11y::Registry.all_events`
+- [ ] Access registry: `E11y::Registry.event_classes`
 - [ ] Enable event explorer UI (development only)
 - [ ] Set up documentation generator rake task
 - [ ] Run validation in CI: `rake e11y:validate`