e11y 0.2.0 → 1.1.0

data/docs/QUICK-START.md

@@ -1,234 +1,265 @@
 # E11y - Quick Start Guide
 
-> **TL;DR**: Ruby gem для структурированных бизнес-событий с request-scoped debug buffering, pattern-based метриками и pluggable адаптерами.
+> **TL;DR**: Ruby gem for structured business events with request-scoped debug buffering,
+> schema validation, and pluggable adapters (Loki, Sentry, OpenTelemetry, Yabeda, etc.).
+>
+> **Current version: 0.2.0** — ⚠️ Work in Progress, production validation in progress.
 
 ---
 
-## 🚀 Installation (5 minutes)
+## 🚀 Installation
 
 ```bash
 # Gemfile
-gem 'e11y', '~> 1.0'
+gem 'e11y', '~> 0.2'
 
 bundle install
+```
+
+Then run the generator to create the initializer and example event:
+
+```bash
 rails g e11y:install
 ```
 
+This creates:
+- `config/initializers/e11y.rb` — base configuration with comments
+- `app/events/` — directory for event classes (if it doesn't exist)
+
+> **Available generators:**
+> - `rails g e11y:install` — initializer + directory scaffold
+> - `rails g e11y:grafana_dashboard` — Grafana dashboard JSON (requires Yabeda/Prometheus)
+> - `rails g e11y:prometheus_alerts` — Prometheus alerting rules
+
+Or create the initializer manually:
+
+```bash
+touch config/initializers/e11y.rb
+```
+
 ---
 
 ## 🎯 Killer Features
 
 ### 1. Request-Scoped Debug Buffering
 
-**Проблема**: Debug логи в production = шум. Без debug = нет контекста при ошибках.
+**Problem**: Debug logs in production = noise. Without debug = no context when errors occur.
 
-**Решение**: Debug события буферизируются в thread-local storage. При success - дропаются, при error - флашатся.
+**Solution**: Debug events are buffered in thread-local storage. On success — discarded.
+On error — flushed with full context.
 
-```ruby
+```
 GET /api/orders/123
   ├─ [debug] Query: SELECT... (buffered, NOT sent)
   ├─ [debug] Cache miss (buffered, NOT sent)
-  ├─ [ERROR] Payment failed ← Exception!
-  └─> FLUSH все buffered debug события!
+  ├─ [ERROR] Payment failed ← 5xx raised
+  └─> FLUSH: all buffered debug events are sent to the adapter!
 ```
 
-**Результат**: Debug логи только когда нужны, zero overhead на happy path.
+> **Note:** By default the buffer flushes only on **5xx server errors** (`flush_on_error = true`).
+> On 4xx responses and successful requests the buffer is discarded.
+>
+> Two independent knobs let you customize this — see [Configuration](#-configuration):
+> - `flush_on_error = false` — disable the 5xx auto-flush
+> - `flush_on_statuses = [403]` — add extra statuses (independent of `flush_on_error`)
+
+**Result**: Debug logs only when needed, zero overhead on the happy path.
 
-### 2. :success Pseudo-Severity
+### 2. `:success` Pseudo-Severity
 
-Новый severity level между :info и :warn для успешных операций.
+A new severity level between `:info` and `:warn` for successful operations.
 
 ```ruby
-Events::OrderPaid.track(
-  order_id: '123',
-  severity: :success  # ← легко фильтровать успехи
-)
+Events::OrderPaid.track(order_id: '123', amount: 99.99, currency: 'USD')
+# severity is automatically :success (inferred from class name — "Paid")
 
-# В Grafana/Kibana:
-severity:success AND event_name:order.paid
+# Or explicitly:
+Events::SomeEvent.track(order_id: '123', severity: :success)
 ```
 
-**Результат**: Видимость успехов, не только ошибок. Легко построить success rate.
+**In Grafana/Kibana:**
+```
+{severity="success", event_name="OrderPaid"}
+```
 
-### 3. Pattern-Based Metrics
+**Result**: Visibility into successes, not just errors. Easy to build success rate dashboards.
 
-Вместо явных `metric :counter` на каждое событие - паттерны:
+### 3. Schema Validation (dry-schema)
 
 ```ruby
-E11y.configure do |config|
-  config.metrics do
-    # Автоматически для всех событий
-    counter_for pattern: '*', name: 'events_total'
-    
-    # Histogram для всех оплат
-    histogram_for pattern: '*.paid',
-                  value: ->(e) { e.payload[:amount] }
+class Events::OrderPaid < E11y::Event::Base
+  schema do
+    required(:order_id).filled(:string)
+    required(:amount).filled(:float, gt?: 0)
+    required(:currency).filled(:string, included_in?: %w[USD EUR GBP])
   end
 end
-```
 
-**Результат**: Метрики без boilerplate.
+Events::OrderPaid.track(order_id: nil, amount: -10)
+# => E11y::ValidationError: Validation failed for OrderPaid: {:order_id=>["must be filled"], ...}
+```
 
-### 4. Trace Context (OpenTelemetry + Sentry)
+### 4. Trace Context (W3C + OTel + Sentry fallback)
 
-Автоматическое извлечение trace_id с fallback chain:
+Automatic trace_id extraction with fallback chain:
 
-```ruby
-# Priority:
-1. X-Trace-ID header
+```
+1. traceparent header (W3C Trace Context)
 2. X-Request-ID header
-3. OpenTelemetry span context
-4. Sentry trace ID
-5. Generate new UUID v7
+3. X-Trace-Id header (custom)
+4. Generate new UUID
 ```
 
-**Результат**: Связанные события across services.
-
-### 5. Built-in SLO Tracking (Zero Config!)
+**Result**: Correlated events across services with no extra code.
 
-Включил флаг → получил SLO metrics из коробки:
+### 5. Built-in SLO Tracking
 
 ```ruby
 E11y.configure do |config|
-  config.slo_tracking = true  # ← ВСЁ!
+  config.rails_instrumentation_enabled = true
+  # config.slo_tracking_enabled = true  # enabled by default
 end
 
-# Автоматически:
-# ✅ HTTP availability + latency
-# ✅ Sidekiq jobs success rate + duration
-# ✅ ActiveJob success rate + duration
-# ✅ Error budget + burn rate
-# ✅ Grafana dashboards (generate)
-# ✅ Prometheus alerts (generate)
+# Automatically emits metrics:
+# e11y_http_requests_total, e11y_http_request_duration_seconds
+# e11y_sidekiq_jobs_total, e11y_sidekiq_job_duration_seconds
+# e11y_active_jobs_total, e11y_active_job_duration_seconds
 ```
 
-**Результат**: Production-ready SLO monitoring без написания middleware.
+> ⚠️ **Caveat:** SLO metrics may be imprecise when adaptive sampling is enabled
+> (sampling correction is planned for Phase 2.8).
+
+> 🚧 **Roadmap:** Per-controller/per-job SLO configuration, auto-generated Grafana dashboards
+> and Prometheus alerts — planned for future releases.
 
 ---
 
 ## ⚡ Quick Examples
 
-### Basic Event (v1.1 - Event-Level Configuration!)
-
-> **🎯 NEW in v1.1:** Event-level configuration reduces global config from 1400+ to <300 lines!
+### Basic Event (minimal configuration)
 
 ```ruby
-# 1. Define event (простой Ruby класс + конфигурация)
+# 1. Define the event (app/events/order_paid.rb)
 class Events::OrderPaid < E11y::Event::Base
-  # Schema (dry-schema для валидации)
   schema do
     required(:order_id).filled(:string)
-    required(:amount).filled(:decimal)
+    required(:amount).filled(:float)
     required(:currency).filled(:string)
   end
-  
-  # ✨ NEW: Event-level configuration (right next to schema!)
-  severity :success
-  rate_limit 1000, window: 1.second
-  sample_rate 1.0  # Never sample payments
-  retention 7.years  # Financial records
-  adapters [:loki, :sentry, :s3_archive]
-  
-  # Metric definition
-  metric :counter,
-         name: 'orders.paid.total',
-         tags: [:currency]
+
+  # Optional: Prometheus metrics via Yabeda
+  # NOTE: The metrics do...end DSL requires the Yabeda adapter to be registered.
+  # Without E11y::Adapters::Yabeda.new in config.adapters, metric definitions are
+  # stored but never updated. See the Yabeda / Prometheus Integration section below.
+  metrics do
+    counter :orders_paid_total, tags: [:currency]
+    histogram :order_amount, value: :amount, tags: [:currency],
+              buckets: [10, 50, 100, 500, 1000]
+  end
 end
 
-# 2. Track - ТОЛЬКО ТАК, больше никаких вариантов!
+# 2. Track — only this form, no alternatives
 Events::OrderPaid.track(
   order_id: '123',
   amount: 99.99,
   currency: 'USD'
 )
-
-# ❌ НЕТ других способов:
-# E11y.track_event(...) - НЕТ!
-# Severity.track(...) - НЕТ!
 ```
 
-**90% событий нужен ТОЛЬКО schema (zero config!):**
+**90% of events — just a schema, everything else from conventions:**
 
 ```ruby
-# Conventions = sensible defaults!
 class Events::OrderCreated < E11y::Event::Base
   schema do
     required(:order_id).filled(:string)
-    required(:amount).filled(:decimal)
+    required(:amount).filled(:float)
+  end
+  # severity: :success   (auto, inferred from "Created")
+  # adapters: [:logs]    (auto, from severity via adapter_mapping)
+  # sample_rate: 0.1     (auto, from severity)
+  # retention_period: 30.days (from config.default_retention_period)
+end
+```
+
+**Explicit configuration at the event-class level:**
+
+```ruby
+class Events::PaymentSucceeded < E11y::Event::Base
+  schema do
+    required(:transaction_id).filled(:string)
+    required(:amount).filled(:float)
   end
-  # ← That's it! All config from conventions:
-  #    severity: :success (from name)
-  #    adapters: [:loki] (from severity)
-  #    sample_rate: 0.1 (from severity)
-  #    retention: 30.days (from severity)
-  #    rate_limit: 1000 (default)
+
+  severity :success
+  sample_rate 1.0            # never sample-out payment events
+  retention_period 7.years   # financial records (also: `retention 7.years` is a valid alias)
+  adapters :logs, :errors_tracker
 end
 ```
 
-**Inheritance для DRY:**
+**Inheritance for DRY configuration:**
 
 ```ruby
-# Base class для payment events
 module Events
   class BasePaymentEvent < E11y::Event::Base
     severity :success
-    sample_rate 1.0  # Never sample
-    retention 7.years
-    adapters [:loki, :sentry, :s3_archive]
+    sample_rate 1.0
+    retention_period 7.years
+    adapters :logs, :errors_tracker
   end
 end
 
-# Inherit from base (1-2 lines per event!)
 class Events::PaymentSucceeded < Events::BasePaymentEvent
   schema do
     required(:transaction_id).filled(:string)
-    required(:amount).filled(:decimal)
+    required(:amount).filled(:float)
   end
-  # ← Inherits ALL config from BasePaymentEvent!
+  # Inherits ALL configuration from BasePaymentEvent
 end
 ```
 
-**Preset modules для 1-line includes:**
+**Preset modules:**
 
 ```ruby
 class Events::PaymentProcessed < E11y::Event::Base
-  include E11y::Presets::HighValueEvent  # ← All config inherited!
-  
+  include E11y::Presets::HighValueEvent
+  # → severity :success, sample_rate 1.0, adapters [:logs, :errors_tracker]
+
   schema do
     required(:transaction_id).filled(:string)
-    required(:amount).filled(:decimal)
+    required(:amount).filled(:float)
   end
 end
-```
 
-### With Duration Measurement
+class Events::UserDeleted < E11y::Event::Base
+  include E11y::Presets::AuditEvent
+  # → sample_rate 1.0, signing enabled, never rate-limited
 
-```ruby
-Events::OrderProcessing.track(order_id: '123') do
-  # Block execution time measured automatically
-  process_order(order)
+  schema do
+    required(:user_id).filled(:string)
+    required(:deleted_by).filled(:string)
+  end
 end
-# → event.duration_ms = 250
 ```
 
 ### Request-Scoped Debug Buffering
 
 ```ruby
-# Middleware (auto-configured)
 class OrdersController < ApplicationController
   def create
-    # Debug events buffered (not sent)
-    Events::ValidationStarted.track(severity: :debug)
+    # Debug events are buffered — not sent immediately
+    Events::ValidationStarted.track(severity: :debug, params: params.keys)
     Events::DatabaseQuery.track(sql: '...', severity: :debug)
-    
-    order = Order.create!(params)
-    
-    # Success event sent immediately
-    Events::OrderCreated.track(order_id: order.id, severity: :success)
-    
+
+    order = Order.create!(order_params)
+
+    # Non-debug events are sent immediately (not buffered)
+    Events::OrderCreated.track(order_id: order.id, amount: order.total)
+
     render json: order
+    # ← Successful request: debug buffer is discarded
   rescue => e
-    # Exception → all buffered debug events flushed with severity :error
+    # ← 5xx (or any configured flush status): debug buffer is flushed with error context
     raise
   end
 end
@@ -236,266 +267,186 @@ end
 
 ---
 
-## 🔧 Configuration (v1.1 - Simplified!)
-
-> **🎯 NEW in v1.1:** Global config reduced from 1400+ to <300 lines!
->
-> **Philosophy:** Global config = infrastructure only. Event config = in event classes.
-
-### Global Config (Infrastructure Only)
+## 🔧 Configuration
 
 ```ruby
-# config/initializers/e11y.rb (<300 lines!)
+# config/initializers/e11y.rb
 E11y.configure do |config|
-  # === ADAPTERS REGISTRATION (infrastructure) ===
-  config.register_adapter :loki, E11y::Adapters::LokiAdapter.new(
+  # === Service identity ===
+  config.service_name = 'myapp'
+  config.environment  = Rails.env
+
+  # === Adapters (key = name, value = instance) ===
+  # adapters is a Hash — use [] assignment or register_adapter (both are equivalent):
+  config.adapters[:logs] = E11y::Adapters::Loki.new(
     url: ENV['LOKI_URL'],
-    labels: { env: Rails.env, service: 'api' }
+    batch_size: 100,
+    batch_timeout: 5,
+    compress: true
   )
-  
-  config.register_adapter :sentry, E11y::Adapters::SentryAdapter.new(
+  # Equivalent form:
+  # config.register_adapter :logs, E11y::Adapters::Loki.new(url: ENV['LOKI_URL'])
+
+  config.adapters[:errors_tracker] = E11y::Adapters::Sentry.new(
     dsn: ENV['SENTRY_DSN']
   )
-  
-  config.register_adapter :s3, E11y::Adapters::S3Adapter.new(
-    bucket: 'events-archive'
+
+  # For Prometheus metrics (requires gem 'yabeda' + 'yabeda-prometheus')
+  config.adapters[:metrics] = E11y::Adapters::Yabeda.new(
+    cardinality_limit: 1000,
+    overflow_strategy: :relabel
   )
-  
-  # === DEFAULTS (conventions) ===
-  config.default_adapters = [:loki]  # Most events → Loki
-  config.default_sample_rate = 0.1   # 10% sampling
-  config.default_rate_limit = 1000   # 1000 events/sec
-  
-  # === REQUEST SCOPE BUFFERING ===
-  config.request_scope do
-    enabled true
-    buffer_limit 100  # max debug events per request
-    flush_on :error   # :error, :always, :never
-  end
-  
-  # === GLOBAL RATE LIMITING (infrastructure) ===
-  config.rate_limiting do
-    global limit: 10_000, window: 1.minute
-  end
-  
-  # === CARDINALITY PROTECTION (infrastructure) ===
-  config.cardinality_protection do
-    forbidden_labels :user_id, :order_id, :session_id
-    default_cardinality_limit 100
-  end
-  
-  # === SLO TRACKING (zero config!) ===
-  config.slo_tracking = true  # ← ВСЁ!
-  
-  # === AUDIT RETENTION (global default) ===
-  # Default for audit events, can be overridden per event
-  config.audit_retention = case ENV['JURISDICTION']
-                           when 'EU' then 7.years   # GDPR
-                           when 'US' then 10.years  # SOX
-                           else 5.years
-                           end
-  
-  # ✅ That's it! No per-event config here anymore!
+
+  # === Request-scoped buffering ===
+  config.ephemeral_buffer_enabled = true
+  # flush_on_error (default: true) — flush buffer on any 5xx server error
+  # config.ephemeral_buffer_flush_on_error = false  # disable 5xx auto-flush
+  # flush_on_statuses (default: []) — extra statuses, independent of flush_on_error
+  # config.ephemeral_buffer_flush_on_statuses = [403]       # also flush on 403 Forbidden
+  # config.ephemeral_buffer_flush_on_statuses = [401, 403]  # multiple codes
+
+  # === Rails auto-instrumentation (HTTP, ActiveRecord, ActiveJob, Cache) ===
+  config.rails_instrumentation_enabled = true
+
+  # === SLO tracking (enabled by default) ===
+  # config.slo_tracking_enabled = true  # already true
+
+  # === Rate limiting (now in default pipeline!) ===
+  # Rate limiting is wired into the default pipeline in v0.2.0.
+  # Enable and configure parameters:
+  # config.rate_limiting_enabled         = true
+  # config.rate_limiting_global_limit    = 10_000   # events/sec
+  # config.rate_limiting_per_event_limit  = 1_000    # events/sec per type
+  # config.rate_limiting_global_window    = 1.0      # seconds
+
+  # === Retention ===
+  config.default_retention_period = 30.days
 end
+
+# Lifecycle methods (v0.2.0):
+# E11y.start!                    # start background workers (batching, retry, DLQ)
+# at_exit { E11y.stop!(timeout: 5) }  # graceful shutdown
 ```
 
-### Event-Level Config (Locality of Behavior)
+### Buffer flush — manual trigger
+
+`EphemeralBuffer.flush_on_error` is a public method — you can call it directly in custom
+rescue handlers or background jobs:
 
 ```ruby
-# app/events/order_created.rb
-module Events
-  class OrderCreated < E11y::Event::Base
-    schema do
-      required(:order_id).filled(:string)
-      required(:amount).filled(:decimal)
-    end
-    
-    # ✨ Event-level config (right next to schema!)
-    severity :success
-    rate_limit 1000, window: 1.second
-    sample_rate 0.1  # 10% sampling
-    retention 30.days
-    adapters [:loki, :elasticsearch]
-    
-    # Metric definition
-    metric :counter,
-           name: 'orders.created.total',
-           tags: [:currency]
-  end
+# Custom error handler (e.g. Grape API, custom Rack app)
+rescue => e
+  E11y::Buffers::EphemeralBuffer.flush_on_error
+  raise
 end
+
+# Or flush to a specific adapter target (not yet implemented — placeholder)
+E11y::Buffers::EphemeralBuffer.flush_on_error(target: :errors_tracker)
 ```
 
-### Old vs New Config
+### Severity → Adapter mapping
 
-**Before (v1.0): 1400+ lines in global config**
+Default routing:
 
 ```ruby
-# config/initializers/e11y.rb (1400+ lines!)
+# error/fatal → [:logs, :errors_tracker]
+# all others  → [:logs]
+
+# Override globally:
 E11y.configure do |config|
-  # Adapters registration
-  config.register_adapter :loki, Loki.new(...)
-  config.register_adapter :sentry, Sentry.new(...)
-  
-  # ❌ Per-event config (100+ events!)
-  config.events do
-    event 'Events::OrderCreated' do
-      severity :success
-      adapters [:loki]
-      sample_rate 0.1
-      retention 30.days
-      rate_limit 1000
-    end
-    
-    event 'Events::PaymentSucceeded' do
-      severity :success
-      adapters [:loki, :sentry, :s3]
-      sample_rate 1.0
-      retention 7.years
-      rate_limit 1000
-    end
-    
-    # ... 98+ more events ...
-  end
+  config.adapter_mapping[:warn] = [:logs, :errors_tracker]
+end
+
+# Override per event:
+class Events::CriticalEvent < E11y::Event::Base
+  adapters :logs, :errors_tracker
 end
 ```
 
-**After (v1.1): <300 lines in global config**
+### PII Filtering
 
-```ruby
-# config/initializers/e11y.rb (<300 lines!)
-E11y.configure do |config|
-  # ONLY infrastructure
-  config.register_adapter :loki, Loki.new(...)
-  config.register_adapter :sentry, Sentry.new(...)
-  
-  # Defaults (conventions)
-  config.default_adapters = [:loki]
-  
-  # ✅ No per-event config here!
-end
+**Auto (:rails_filters):** E11y automatically applies `Rails.application.config.filter_parameters`.
 
-# app/events/order_created.rb
-class Events::OrderCreated < E11y::Event::Base
-  schema do; required(:order_id).filled(:string); end
-  # ← Uses conventions (zero config!)
-end
+```ruby
+# config/application.rb
+config.filter_parameters += [:password, :email, :ssn]
 
-# app/events/payment_succeeded.rb
-class Events::PaymentSucceeded < Events::BasePaymentEvent
-  schema do; required(:transaction_id).filled(:string); end
-  # ← Inherits config from BasePaymentEvent (DRY!)
-end
+# These fields become '[FILTERED]' automatically on track
+Events::UserRegistered.track(email: 'user@example.com', password: 'secret')
 ```
 
-### Migration Path (Backward Compatible)
+**Event-level DSL (:explicit_pii):**
 
 ```ruby
-# v1.1 supports BOTH styles (backward compatible!)
+class Events::PaymentCreated < E11y::Event::Base
+  contains_pii true
 
-# Old style (still works):
-E11y.configure do |config|
-  config.events do
-    event 'Events::OrderCreated' do
-      adapters [:loki]
-    end
+  pii_filtering do
+    masks   :card_number   # → '[FILTERED]'
+    hashes  :user_email    # → SHA256 (preserves searchability)
+    partials :phone        # → first/last characters visible
+    redacts :ssn           # → removed completely
+    allows  :amount        # → no filtering
   end
 end
+```
 
-# New style (preferred):
-class Events::OrderCreated < E11y::Event::Base
-  adapters [:loki]  # ← Event-level (overrides global)
+**Inheritance:** Use a base class for common rules, child events add or override:
+
+```ruby
+class BaseUserEvent < E11y::Event::Base
+  contains_pii true
+  pii_filtering do
+    masks   :password
+    hashes  :email
+    partials :phone
+  end
 end
 
-# Migrate incrementally (both work together!)
+class Events::PaymentCreated < BaseUserEvent
+  pii_filtering do
+    masks :card_number, :cvv
+  end
+end
 ```
 
----
-
-## 🔧 Old Configuration (v1.0 - Deprecated)
-
-> **⚠️ Deprecated:** This section shows v1.0 configuration style for reference.
-> Use event-level configuration (above) for new projects.
+### Adaptive Sampling
 
 ```ruby
-# config/initializers/e11y.rb (OLD STYLE)
 E11y.configure do |config|
-  # === SEVERITY ===
-  config.severity = Rails.env.production? ? :info : :debug
-  
-  # === ADAPTERS (old style) ===
-  config.adapters = [
-    # Loki for logs
-    E11y::Adapters::LokiAdapter.new(
-      url: ENV['LOKI_URL'],
-      labels: { env: Rails.env, service: 'api' }
-    ),
-    
-    # Sentry for errors
-    E11y::Adapters::SentryAdapter.new(
-      severity_filter: [:error, :fatal]
-    ),
-    
-    # Stdout for development
-    (E11y::Adapters::StdoutAdapter.new if Rails.env.development?)
-  ].compact
-  
-  # === PATTERN-BASED METRICS ===
-  config.metrics do
-    # Counter for all events
-    counter_for pattern: '*',
-                name: 'business_events_total',
-                tags: [:event_name, :severity]
-    
-    # Histogram for payments
-    histogram_for pattern: '*.paid',
-                  name: 'payment_amount',
-                  value: ->(e) { e.payload[:amount] },
-                  buckets: [10, 50, 100, 500, 1000]
-    
-    # Success rate auto-metric
-    success_rate_for pattern: 'order.*',
-                     name: 'order_operations_success_rate'
-  end
-  
-  # === PII FILTERING (Rails-compatible!) ===
-  config.pii_filter do
-    # AUTO: Uses Rails.application.config.filter_parameters (default: true)
-    use_rails_filter_parameters true
-    
-    # SIMPLE: Add more filters (Rails-style)
-    filter_parameters :api_key, :auth_token, /secret/i
-    
-    # WHITELIST: Allow specific IDs even if filtered by Rails
-    allow_parameters :user_id, :order_id, :transaction_id
-    
-    # ADVANCED: Pattern-based (beyond Rails)
-    filter_pattern /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i,
-                   replacement: '[EMAIL]'
-    filter_pattern /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/,
-                   replacement: '[CARD]'
-  end
-  
-  # === RATE LIMITING ===
-  config.rate_limiting do
-    global limit: 10_000, window: 1.minute
-    per_event 'user.login.failed', limit: 100, window: 1.minute
-  end
-  
-  # === CONTEXT ENRICHMENT ===
-  config.context_enricher do |event|
-    {
-      trace_id: E11y::TraceId.extract,
-      user_id: Current.user&.id,
-      tenant_id: Current.tenant&.id
+  config.pipeline.use E11y::Middleware::Sampling,
+    default_sample_rate: 0.1,
+
+    # Error-spike: on error burst → 100% sampling
+    error_based_adaptive: true,
+    error_spike_config: {
+      window: 60,
+      absolute_threshold: 100,
+      relative_threshold: 3.0,
+      spike_duration: 300
+    },
+
+    # Load-based: under high load → reduced sampling
+    load_based_adaptive: true,
+    load_monitor_config: {
+      window: 60,
+      thresholds: {
+        normal:    1_000,
+        high:     10_000,
+        very_high: 50_000,
+        overload: 100_000
+      }
     }
-  end
 end
+```
 
-# Start async workers
-E11y.start!
+**Value-based sampling at the event level:**
 
-# Graceful shutdown
-at_exit { E11y.stop!(timeout: 5) }
+```ruby
+class Events::Payment < E11y::Event::Base
+  sample_by_value :amount, greater_than: 1000  # large payments — always tracked
+  sample_by_value :total,  in_range: 100..500
+end
 ```
 
 ---
@@ -503,64 +454,78 @@ at_exit { E11y.stop!(timeout: 5) }
 ## 📊 Severity Levels
 
 ```ruby
-E11y::SEVERITIES = {
-  debug:   0,  # Detailed diagnostic (buffered in request scope)
-  info:    1,  # Informational
-  success: 2,  # ← NEW! Successful operations
-  warn:    3,  # Warnings
-  error:    4,  # Errors
-  fatal:   5   # Critical failures
-}
+# lib/e11y/event/base.rb
+SEVERITIES = %i[debug info success warn error fatal].freeze
+
+# Default sample rates by severity:
+SEVERITY_SAMPLE_RATES = {
+  error:   1.0,   # always
+  fatal:   1.0,   # always
+  debug:   0.01,  # 1%
+  info:    0.1,   # 10%
+  success: 0.1,   # 10%
+  warn:    0.1    # 10%
+}.freeze
 ```
 
-**When to use :success?**
+**When to use `:success`:**
 
 ```ruby
-# ✅ Use :success for completed operations
-Events::OrderPaid.track(order_id: '123', severity: :success)
-Events::JobCompleted.track(job_id: '456', severity: :success)
-Events::EmailSent.track(user_id: '789', severity: :success)
+Events::OrderPaid.track(order_id: '123')       # ← :success (explicit)
+Events::JobCompleted.track(job_id: '456')       # ← :success (from name "Completed")
+Events::UserLoggedIn.track(user_id: '123')      # ← :info   (default)
+Events::PaymentFailed.track(reason: 'timeout')  # ← :error  (from name "Failed")
+```
 
-# ✅ Use :info for informational events
-Events::UserLoggedIn.track(user_id: '123', severity: :info)
-Events::SessionStarted.track(session_id: '456', severity: :info)
+**Auto-resolved severity (convention over configuration):**
 
-# Why separate :success from :info?
-# → Easy filtering: severity:success = only successful ops
-# → Easy metrics: success_rate = count(:success) / count(:success OR :error)
-```
+| Name contains | Severity |
+|---|---|
+| `Failed`, `Error` | `:error` |
+| `Paid`, `Success`, `Completed` | `:success` |
+| `Warn`, `Warning` | `:warn` |
+| anything else | `:info` |
 
 ---
 
-## 🎭 Middleware (Auto-configured)
+## 🎭 Middleware (configuration)
 
 ### Rails / Rack
 
-```ruby
-# config/application.rb (auto-added by generator)
-config.middleware.use E11y::Middleware::Rack,
-  buffer_limit: 100,
-  flush_on: :error
-```
+`E11y::Middleware::Request` is automatically inserted by the Railtie when `ephemeral_buffer_enabled` is true.
 
 ### Sidekiq
 
 ```ruby
-# config/initializers/sidekiq.rb (auto-added by generator)
+# Automatically inserted by Railtie when Sidekiq is present.
+# For manual setup:
 Sidekiq.configure_server do |config|
   config.server_middleware do |chain|
-    chain.add E11y::Middleware::Sidekiq
+    chain.add E11y::Instruments::Sidekiq::ServerMiddleware
   end
 end
 ```
 
-### ActiveJob
+### Default pipeline order
+
+```
+TraceContext → Validation → PIIFilter → AuditSigning → Sampling → RateLimiting → Routing
+```
+
+As of v0.2.0, `RateLimiting` is wired into the default pipeline. To activate it, set
+`config.rate_limiting_enabled = true` (no manual `.use` call needed).
+
+**Versioning (opt-in):**
+
+`Middleware::Versioning` normalizes event names from CamelCase class names to dot-notation
+(e.g., `OrderPaidEvent` → `order.paid`). It is not in the default pipeline; add it explicitly:
 
 ```ruby
-# Auto-included by E11y (no config needed)
-# trace_id propagated automatically to background jobs
+config.pipeline.use E11y::Middleware::Versioning
 ```
 
+Without this middleware, event names in adapters are the raw class name (e.g., `"OrderPaidEvent"`).
+
 ---
 
 ## 🔍 Trace Context Flow
@@ -568,40 +533,52 @@ end
 ```ruby
 # Service A (API)
 POST /orders
-  trace_id: abc-123 (from X-Trace-ID header)
-  ├─ Events::OrderValidation.track (trace_id: abc-123)
-  ├─ Events::OrderCreated.track (trace_id: abc-123)
-  └─ ProcessOrderJob.perform_later(order_id, trace_id: abc-123)
+  trace_id: abc-123  # from X-Trace-ID header
+  ├─ Events::OrderValidation.track  # trace_id: abc-123
+  ├─ Events::OrderCreated.track     # trace_id: abc-123
+  └─ ProcessOrderJob.perform_later(order_id: id, trace_id: 'abc-123')
 
-# Service B (Background Job)
+# Background Job (Sidekiq)
 ProcessOrderJob
-  trace_id: abc-123 (from job args)
-  ├─ Events::OrderProcessing.track (trace_id: abc-123)
-  └─ HTTP → Service C (headers: X-Trace-ID: abc-123)
+  trace_id: abc-123  # propagated through middleware
+  └─ Events::OrderProcessed.track  # trace_id: abc-123
 
-# Service C (Payment API)
-POST /payments
-  trace_id: abc-123 (from X-Trace-ID header)
-  └─ Events::PaymentProcessed.track (trace_id: abc-123)
-
-# Result: All events linked by trace_id = full visibility
+# Result: all events are correlated by trace_id = full visibility
 ```
 
 ---
 
-## 📈 Yabeda Integration
+## 📈 Yabeda / Prometheus Integration
 
-Events автоматически становятся метриками через pattern-based rules:
+> **Note:** The `metrics do ... end` DSL requires the Yabeda adapter to be registered.
+> Without `E11y::Adapters::Yabeda.new` in `config.adapters`, metric definitions are stored
+> but never updated. Add the adapter as shown below before defining event metrics.
 
 ```ruby
-# After tracking event:
-Events::OrderPaid.track(amount: 99, currency: 'USD')
+# Gemfile
+gem 'yabeda'
+gem 'yabeda-prometheus'
+
+# config/initializers/e11y.rb
+E11y.configure do |config|
+  config.adapters[:metrics] = E11y::Adapters::Yabeda.new(
+    cardinality_limit: 1000,
+    forbidden_labels: [:user_id, :order_id],  # additional denylist
+    overflow_strategy: :relabel               # :drop, :alert, or :relabel
+  )
+end
+
+# Event with metrics:
+class Events::OrderPaid < E11y::Event::Base
+  metrics do
+    counter   :orders_paid_total, tags: [:currency]
+    histogram :order_amount, value: :amount, tags: [:currency]
+  end
+end
 
-# Auto-generated metrics:
-yabeda.business_events.events_total{event_name="order.paid",severity="success"} 1
-yabeda.business_events.payment_amount_bucket{currency="USD",le="100"} 1
-yabeda.business_events.order_operations_success 1
-yabeda.business_events.order_operations_total 1
+Events::OrderPaid.track(order_id: '123', amount: 99, currency: 'USD')
+# → Yabeda.e11y.orders_paid_total.increment({currency: 'USD'})
+# → Yabeda.e11y.order_amount.measure({currency: 'USD'}, 99)
 ```
 
 **Prometheus endpoint:**
@@ -611,241 +588,164 @@ yabeda.business_events.order_operations_total 1
 mount Yabeda::Prometheus::Exporter => '/metrics'
 ```
 
+
 ---
 
 ## 🧪 Testing
 
 ```ruby
-# spec/spec_helper.rb
+# spec/support/e11y_helper.rb
 RSpec.configure do |config|
+  let(:test_adapter) { E11y::Adapters::InMemory.new }
+
   config.before(:each) do
+    # adapters is a Hash — use [] assignment, not Array assignment
     E11y.configure do |c|
-      c.adapters = [E11y::Adapters::NullAdapter.new]
+      c.adapters[:test] = test_adapter
+      # For a no-op adapter that discards all events (no recording overhead):
+      # c.adapters[:null] = E11y::Adapters::NullAdapter.new
     end
   end
+
+  config.after(:each) do
+    test_adapter.clear!
+  end
 end
 
 # spec/controllers/orders_controller_spec.rb
 RSpec.describe OrdersController do
   it 'tracks order creation' do
-    expect(Events::OrderCreated).to receive(:track).with(
-      hash_including(order_id: anything)
+    post :create, params: { order_id: '123', amount: 99.99, currency: 'USD' }
+
+    events = test_adapter.events
+    expect(events).to include(
+      a_hash_including(
+        event_name: 'OrderCreated',
+        payload: hash_including(order_id: '123')
+      )
     )
-    
-    post :create, params: { ... }
+  end
+
+  it 'raises on invalid data' do
+    expect {
+      Events::OrderPaid.track(order_id: nil, amount: -1)
+    }.to raise_error(E11y::ValidationError)
   end
 end
 ```
 
----
+**InMemory Adapter API:**
 
-## 🚀 Performance
-
-| Metric | Target | Actual |
-|--------|--------|--------|
-| **Track latency (p99)** | <1ms | ✅ 0.8ms |
-| **Throughput** | 10k events/sec | ✅ 15k/sec |
-| **Memory** | <100MB @ 100k buffer | ✅ 80MB |
-| **CPU overhead** | <5% @ 1k events/sec | ✅ 3% |
+```ruby
+adapter = E11y::Adapters::InMemory.new(max_events: 1000)
 
-**Optimizations:**
-- Early severity filtering (<1μs для filtered events)
-- Lock-free ring buffer (SPSC)
-- Async workers (no blocking)
-- Lazy serialization (только перед отправкой)
+adapter.events       # => Array<Hash> — all events
+adapter.event_count  # => Integer
+adapter.last_event   # => Hash — last event
+adapter.clear!       # reset
+```
 
 ---
 
 ## 🔐 Security
 
-### PII Filtering (Rails-Compatible! 🎉)
+### PII Filtering — what works today
 
-**ZERO CONFIG**: E11y автоматически использует `Rails.application.config.filter_parameters`!
+**Auto (:rails_filters) — Rails filter_parameters:**
 
 ```ruby
 # config/application.rb
-config.filter_parameters += [:password, :email, :ssn]
-
-# E11y автоматически фильтрует эти поля - NO ADDITIONAL CONFIG!
-Events::UserRegistered.track(
-  email: 'user@example.com',  # → '[FILTERED]'
-  password: 'secret123'        # → '[FILTERED]'
-)
+config.filter_parameters += [:password, :email, :ssn, :credit_card]
+# E11y applies this list automatically — no extra config needed
 ```
 
-**EXTENDED**: Добавьте больше фильтров поверх Rails:
+**Event-level (:explicit_pii):**
 
 ```ruby
-# config/initializers/e11y.rb
-E11y.configure do |config|
-  config.pii_filter do
-    # Inherit Rails filters + add more
-    filter_parameters :api_key, :auth_token, /secret/i
-    
-    # Whitelist known-safe fields
-    allow_parameters :user_id, :order_id
-    
-    # Pattern-based (content filtering)
-    filter_pattern /\b\d{16}\b/, replacement: '[CARD]'
+class Events::UserRegistered < E11y::Event::Base
+  contains_pii true
+
+  pii_filtering do
+    masks   :password
+    hashes  :email      # SHA256, preserves searchability
+    redacts :ssn
+    allows  :user_id
   end
 end
 ```
 
-**See full guide**: `e11y-rails-compatible-pii-filtering.md`
+### Rate Limiting — now in default pipeline
 
-### Rate Limiting (защита от DoS)
+As of v0.2.0, `Middleware::RateLimiting` is included in the default pipeline. Activate it by
+enabling the config (no extra `.use` call required):
 
 ```ruby
-# Config
-config.rate_limiting do
-  global limit: 10_000, window: 1.minute
-  per_event 'user.login.failed', limit: 100, window: 1.minute
+E11y.configure do |config|
+  config.rate_limiting_enabled         = true
+  config.rate_limiting_global_limit     = 10_000  # events/sec
+  config.rate_limiting_per_event_limit  = 1_000   # events/sec per type
+  config.rate_limiting_global_window    = 1.0     # seconds
 end
-
-# При превышении - события дропаются
 ```
 
----
+> **Note:** When `config.rate_limiting_enabled = false` (default), the middleware is present in
+> the pipeline but passes all events through without limiting. Set `enabled = true` to activate.
 
-## 🎯 Built-in SLO Tracking (Zero Config!)
+> 🚧 **Roadmap:** Per-event and per-pattern rate limiting (e.g. `'user.login.failed'` → 100/min)
+> — planned for future releases.
 
-**Enable one flag → get SLO out of the box!**
+---
 
-```ruby
-# config/initializers/e11y.rb
-E11y.configure do |config|
-  config.slo_tracking = true  # ← ВСЁ! Этого достаточно!
-  
-  # Опционально: кастомизация
-  config.slo do
-    # Global defaults
-    http_ignore_statuses [404, 401]  # 404/401 не ошибки
-    latency_target_p95 200  # ms
-    
-    # 🎯 NEW: Per-controller overrides (РЕКОМЕНДУЕТСЯ для Rails!)
-    controller 'Api::Admin::BaseController' do
-      ignore true  # Весь admin не входит в SLO
-    end
-    
-    controller 'Api::OrdersController', action: 'show' do
-      latency_target_p95 50   # Show должен быть быстрым
-    end
-    
-    controller 'Api::OrdersController', action: 'create' do
-      latency_target_p95 200  # Create может быть медленнее
-      ignore_statuses [422]   # 422 Validation = not SLO breach
-    end
-    
-    # 🔧 LEGACY: Path-based (для non-Rails apps)
-    endpoint '/api/webhooks/*' do
-      ignore true
-    end
-    
-    # 🎯 Per-job overrides
-    job 'ReportGenerationJob' do
-      ignore true  # Долгие джобы не входят в SLO
-    end
-    
-    job 'ProcessPaymentJob' do
-      latency_target_p95 1000  # Критичные джобы = строгий SLO
-    end
-  end
-end
-```
+## 🎯 Built-in SLO Tracking
 
-**Автоматически получаем:**
+**What is tracked automatically** when `config.rails_instrumentation_enabled = true`:
 
 ```ruby
-# 🎯 HTTP Metrics (controller#action - автогруппировка!)
-yabeda_slo_http_requests_total{
-  status="200",
-  method="GET",
-  controller="Api::OrdersController",
-  action="show"
-} 1234
-
-yabeda_slo_http_request_duration_seconds{
-  method="GET",
-  controller="Api::OrdersController",
-  action="show"
-} histogram
+# HTTP Metrics (via Rack middleware)
+e11y_http_requests_total{
+  status="200", method="GET",
+  controller="Api::OrdersController", action="show"
+}
+e11y_http_request_duration_seconds{ ... }  # histogram
 
 # Sidekiq Metrics
-yabeda_slo_sidekiq_jobs_total{queue="default", class="ProcessOrderJob", status="success"} 456
-yabeda_slo_sidekiq_job_duration_seconds{queue="default", class="ProcessOrderJob"} histogram
+e11y_sidekiq_jobs_total{queue="default", class="ProcessOrderJob", status="success"}
+e11y_sidekiq_job_duration_seconds{ ... }
 
 # ActiveJob Metrics
-yabeda_slo_active_jobs_total{queue="mailers", class="EmailJob", status="success"} 789
-yabeda_slo_active_job_duration_seconds{queue="mailers", class="EmailJob"} histogram
+e11y_active_jobs_total{queue="mailers", class="EmailJob", status="success"}
+e11y_active_job_duration_seconds{ ... }
 ```
 
-**Преимущество:** `/orders/123`, `/orders/456` → один `OrdersController#show` (не нужна нормализация path!)
-
 **SLO Calculations (PromQL):**
 
 ```promql
 # HTTP Availability (30d rolling)
-100 * (sum(rate(yabeda_slo_http_successes_total[30d])) / 
-       (sum(rate(yabeda_slo_http_successes_total[30d])) + sum(rate(yabeda_slo_http_errors_total[30d]))))
-# Expected: >= 99.9%
+100 * (
+  sum(rate(e11y_http_requests_total{status=~"2.."}[30d])) /
+  sum(rate(e11y_http_requests_total[30d]))
+)
 
 # p95 Latency
-histogram_quantile(0.95, rate(yabeda_slo_http_request_duration_seconds_bucket[5m]))
-# Expected: < 200ms
-
-# Error Budget Remaining
-100 * (1 - (sum(rate(yabeda_slo_http_errors_total[30d])) / 
-            (sum(rate(yabeda_slo_http_successes_total[30d])) + sum(rate(yabeda_slo_http_errors_total[30d])))) / 0.001)
-# 100% = весь бюджет остался, 0% = исчерпан
-```
-
-**Auto-Generated:**
-
-```bash
-# Grafana dashboard
-rails g e11y:grafana_dashboard
-# → config/grafana/e11y_slo_dashboard.json
-
-# Prometheus alerts
-rails g e11y:prometheus_alerts
-# → config/prometheus/e11y_slo_alerts.yml
+histogram_quantile(0.95, rate(e11y_http_request_duration_seconds_bucket[5m]))
 ```
 
-**Что трекается автоматически:**
-- ✅ **Rack middleware** - все HTTP requests (availability, latency)
-- ✅ **Sidekiq middleware** - все jobs (success rate, duration)
-- ✅ **ActiveJob instrumentation** - все jobs (success rate, duration)
-- ✅ **Path normalization** - `/orders/123` → `/orders/:id`
-- ✅ **Error categorization** - configurable (5xx = error, 404 = ignore)
-- ✅ **Heartbeat** - auto-enabled (pod liveness detection)
+**⚠️ In-process SLO limitations:**
 
-**⚠️ ВАЖНО: Ограничения in-process SLO**
+E11y SLO runs inside the Ruby process and **does not see**:
+- Network issues (requests that never reach the app)
+- Load balancer failures
+- All pods down
 
-E11y SLO работает ВНУТРИ Ruby процесса и НЕ видит:
-- ❌ Network issues (requests не доходят до app)
-- ❌ Load balancer down
-- ❌ All pods crashed (метрик просто нет)
-- ❌ DNS issues
+Recommended: multi-layer monitoring — E11y SLO + K8s health probes + external synthetic checks.
 
-**Решение:** Multi-layer monitoring (см. полную документацию):
-1. **Layer 1**: E11y SLO (in-process)
-2. **Layer 2**: E11y Heartbeat (pod liveness) - **auto-enabled!**
-3. **Layer 3**: K8s health probes (`/health/live`, `/health/ready`) - **auto-created!**
-4. **Layer 4**: External synthetic monitoring (Prometheus Blackbox Exporter)
-
-```ruby
-# Heartbeat автоматически включен с slo_tracking = true
-# Метрики:
-yabeda_e11y_heartbeat_timestamp{pod="pod-1"} 1703500000  # Последний heartbeat
-yabeda_e11y_service_healthy{pod="pod-1"} 1               # 1 = healthy
-
-# Alert если pod мертв:
-# (time() - yabeda_e11y_heartbeat_timestamp) > 30s → Pod down!
-```
+> 🚧 **Roadmap:** Per-controller/per-job SLO configuration, auto-generated Grafana dashboards
+> (`rails g e11y:grafana_dashboard`) and Prometheus alerts (`rails g e11y:prometheus_alerts`)
+> — planned for future releases.
 
 ---
 
-## 🎯 Migration from Rails.logger
+## 🔄 Migration from Rails.logger
 
 ```ruby
 # ❌ Before
@@ -853,76 +753,135 @@ Rails.logger.info "Order #{order.id} paid #{order.amount} #{order.currency}"
 OrderMetrics.increment('orders.paid.total')
 OrderMetrics.observe('orders.paid.amount', order.amount)
 
-# ✅ After (1 строка вместо 3!)
+# ✅ After (1 line instead of 3, + validation + trace context)
 Events::OrderPaid.track(
   order_id: order.id,
-  amount: order.amount,
+  amount:   order.amount,
   currency: order.currency
 )
-# → Structured log + auto-metrics + trace context
 ```
 
 ---
 
 ## 🐛 Troubleshooting
 
-### Events not appearing?
+### Events not appearing in the adapter?
 
 ```ruby
-# Check 1: Severity
-E11y.enabled_for?(:debug) # Should be true
+# 1. Is E11y enabled?
+E11y.config.enabled  # => true
+
+# 2. Is the adapter registered?
+E11y.config.adapters  # => {:logs=>#<Loki...>, ...} — must not be empty
+
+# 3. Is severity routing configured?
+E11y.config.adapter_mapping
+# => {:error=>[:logs, :errors_tracker], :fatal=>[:logs, :errors_tracker], :default=>[:logs]}
 
-# Check 2: Adapters
-E11y.config.adapters # Should not be empty
+# 4. Is the adapter healthy?
+E11y.config.adapters[:logs].healthy?  # => true
 
-# Check 3: Buffer
-E11y.buffer_size # Should be < capacity
+# 5. Metrics not updating? Yabeda adapter must be explicitly configured:
+E11y.config.adapters[:metrics]  # should be E11y::Adapters::Yabeda
 
-# Check 4: Circuit breaker
-E11y.circuit_breaker_state # Should be :closed
+# 6. Diagnostic helpers (v0.2.0):
+E11y.enabled_for?(:debug)         # => true/false — is debug severity active?
+E11y.buffer_size                   # => Integer — current debug buffer size
+E11y.circuit_breaker_state         # => :closed/:open/:half_open
 ```
 
-### High latency?
+### Debug events not flushing on errors?
 
 ```ruby
-# Check metrics
-Yabeda.e11y.track_duration_seconds # p99 should be <1ms
+# Is the buffer enabled?
+E11y.config.ephemeral_buffer_enabled  # => true
+
+# Is Rails instrumentation enabled?
+E11y.config.rails_instrumentation_enabled  # => true
+
+# Is 5xx auto-flush enabled?
+E11y.config.ephemeral_buffer_flush_on_error    # => true (default)
+
+# Any extra statuses configured?
+E11y.config.ephemeral_buffer_flush_on_statuses # => [] (default) or [403] etc.
+
+# Note: flush_on_error and flush_on_statuses are independent.
+# flush_on_error=true  → flush on any 5xx.
+# flush_on_statuses=[403] → also flush on 403, regardless of flush_on_error.
+```
 
+### High latency?
+
+```ruby
 # Possible causes:
-# - PII filtering regex too complex
-# - Rate limiter Redis slow
-# - Adapter network slow
+# - Loki/Sentry unreachable → circuit breaker will open after 5 errors
+# - PII filtering: complex regexes → simplify
+# - batch_size too large → reduce or lower batch_timeout
+
+# Check adapter health:
+E11y.config.adapters[:logs].healthy?
 ```
 
 ---
 
 ## 📚 Full Documentation
 
-- **Complete spec**: `severity/e11y-final-spec.md` (2000+ lines)
-- **Old spec**: `severity/tz-improved.md` (reference)
-- **GitHub**: https://github.com/yourorg/e11y
+- **ADRs**: `docs/architecture/ADR-*.md` — architecture decision records
+- **GitHub**: https://github.com/arturseletskiy/e11y
 
 ---
 
-## ✅ Checklist
-
-- [ ] Install gem
-- [ ] Run generator: `rails g e11y:install`
-- [ ] Configure adapters (Loki/Sentry/ELK)
-- [ ] **Enable SLO tracking**: `config.slo_tracking = true`
-- [ ] Define first event class
-- [ ] Track first event
-- [ ] Check `/metrics` endpoint (Prometheus)
-- [ ] Verify events in Grafana/Kibana
-- [ ] **Verify SLO metrics**: `yabeda_slo_*` in Prometheus
-- [ ] Test request-scoped buffering (raise exception → see debug logs)
-- [ ] Configure PII filtering
-- [ ] Setup rate limiting
-- [ ] Configure pattern-based metrics
-- [ ] **Generate Grafana dashboard**: `rails g e11y:grafana_dashboard`
-- [ ] **Generate Prometheus alerts**: `rails g e11y:prometheus_alerts`
-- [ ] Deploy to staging
-- [ ] Monitor performance
-- [ ] Rollout to production (canary 1% → 10% → 100%)
+## ✅ Getting Started Checklist
+
+- [ ] Add `gem 'e11y', '~> 0.2'` to Gemfile, run `bundle install`
+- [ ] Run `rails g e11y:install` (or create `config/initializers/e11y.rb` manually)
+- [ ] Configure adapters: `config.adapters[:logs] = E11y::Adapters::Loki.new(...)`
+- [ ] For metrics: add `gem 'yabeda'`, set `config.adapters[:metrics] = E11y::Adapters::Yabeda.new`
+- [ ] Enable request buffering: `config.ephemeral_buffer_enabled = true`
+- [ ] Enable Rails instrumentation: `config.rails_instrumentation_enabled = true`
+- [ ] Define first event class in `app/events/`
+- [ ] Use `EventName.track(...)` in a controller or service
+- [ ] Write a test using `E11y::Adapters::InMemory`
+- [ ] Check `/metrics` endpoint (if Yabeda is configured)
+- [ ] Test request buffering: raise an exception → confirm debug events appeared
+- [ ] Configure PII filtering for events that handle personal data
+- [ ] Deploy to staging, monitor performance
 
+---
 
+## ✅ What's New in v0.2.0
+
+| Feature | Notes |
+|---------|-------|
+| `rails g e11y:install` | Generator available: creates initializer + `app/events/` |
+| `E11y.start!` / `E11y.stop!` | Lifecycle methods for graceful startup/shutdown |
+| Rate Limiting in default pipeline | `config.rate_limiting_enabled = true` now works |
+| Event name normalization (`Middleware::Versioning`) | Now in default pipeline |
+| OTelLogs payload attributes | All payload attributes now included in OTel log records |
+| `config.slo_tracking = true` | Boolean coercion now accepted |
+| `retention` / `retention_period` | Both work as aliases on event class |
+| `add_slo_controller` / `add_slo_job` | Helpers on `E11y::Configuration` (stored config; see UC-004) |
+| `config.rate_limiting do` | Rate limiting block DSL |
+| `config.cardinality_protection do` | Cardinality DSL block |
+| `config.register_adapter` | Alias for `config.adapters[name] =` |
+| `NullAdapter` | `E11y::Adapters::NullAdapter.new` for no-op testing |
+| `track() { }` block form | Block form measures duration automatically |
+| `E11y.enabled_for?` / `E11y.buffer_size` | Diagnostic helpers |
+| `metric :counter` single-call DSL | Single metric definition without `metrics do` block |
+| Full block DSLs | All config sections support `do...end` block form |
+
+## 🚧 Roadmap (still not implemented)
+
+The following features are **documented in ADRs** but not yet implemented:
+
+| Feature | ADR/UC |
+|---------|--------|
+| `rails g e11y:grafana_dashboard` | ADR-003 |
+| `rails g e11y:prometheus_alerts` | ADR-003 |
+| Wire `add_slo_controller` / `add_slo_job` into HTTP/job `Tracker` dimensions | UC-004, ADR-003 |
+| Per-event rate limiting (`rate_limit` DSL on event class) | UC-011 |
+| Tiered storage (archival) | UC-019 — filter by `retention_until` |
+| Cost Tracking / Budget Enforcement | ADR-009, UC-015 |
+| Outgoing HTTP trace propagation (Faraday/Net::HTTP) | UC-009 |
+| Event Registry (`E11y::Registry`) | UC-022 |
+| Key Rotation for AuditEncrypted | ADR-006 |