rapitapir 0.1.2 → 2.0.0

data/docs/SINATRA_EXTENSION.md

@@ -1,467 +1,518 @@
-# RapiTapir Sinatra Extension
+# RapiTapir Sinatra Integration
 
 **Zero-boilerplate, enterprise-grade API development with RapiTapir and Sinatra**
 
-The RapiTapir Sinatra Extension provides a seamless, ergonomic experience for building production-ready APIs by eliminating repetitive configuration and following SOLID principles.
+RapiTapir provides two elegant ways to integrate with Sinatra: the recommended **SinatraRapiTapir base class** for maximum simplicity, and the **manual extension registration** for advanced customization.
 
-## 🚀 Quick Start
+## 🚀 Quick Start (Recommended)
+
+### Option 1: SinatraRapiTapir Base Class
+
+The simplest and cleanest way to create APIs:
 
 ```ruby
-require 'sinatra/base'
 require 'rapitapir'
-require 'rapitapir/sinatra/extension'
-
-class MyAPI < Sinatra::Base
-  register RapiTapir::Sinatra::Extension
 
+class MyAPI < SinatraRapiTapir
   rapitapir do
-    info title: 'My API', version: '1.0.0'
-    development_defaults!
+    info(title: 'My API', version: '2.0.0')
+    development_defaults! # Auto CORS, docs, health checks
   end
 
-  # Define a simple endpoint
+  # T shortcut and HTTP verbs automatically available
   endpoint(
-    RapiTapir.get('/hello')
-      .ok(RapiTapir::Types.hash({ "message" => RapiTapir::Types.string }))
+    GET('/hello')
+      .query(:name, T.string, description: 'Your name')
+      .ok(T.hash({ "message" => T.string }))
       .build
-  ) { { message: 'Hello, World!' } }
+  ) { |inputs| { message: "Hello, #{inputs[:name]}!" } }
+
+  run! if __FILE__ == $0
 end
 ```
 
-## 📋 Table of Contents
+### Option 2: Manual Extension Registration
 
-- [Features](#features)
-- [Installation](#installation)
-- [Configuration](#configuration)
-- [Endpoint Definition](#endpoint-definition)
-- [RESTful Resources](#restful-resources)
-- [Authentication](#authentication)
-- [Middleware](#middleware)
-- [Documentation](#documentation)
-- [Examples](#examples)
-- [Architecture](#architecture)
-
-## ✨ Features
-
-### Zero Boilerplate
-- **One-line configuration**: Set up authentication, middleware, and documentation with minimal code
-- **Smart defaults**: Production and development presets that just work
-- **Automatic registration**: Endpoints are automatically registered with proper validation
-
-### Enterprise-Ready
-- **Built-in authentication**: Bearer token, API key, and custom schemes
-- **Production middleware**: CORS, rate limiting, security headers
-- **Auto-generated OpenAPI**: Beautiful Swagger UI documentation
-- **Type-safe validation**: Automatic request/response validation
-
-### Developer Experience
-- **RESTful resource builder**: Create full CRUD APIs with a single block
-- **Helpful error messages**: Clear validation and authentication errors
-- **Hot reloading**: Development-friendly configuration
-- **Extensive examples**: Get started quickly with working code
-
-## 🔧 Installation
-
-Add to your Gemfile:
+For advanced customization and existing Sinatra applications:
 
 ```ruby
-gem 'rapitapir'
-```
-
-Or install directly:
-
-```bash
-gem install rapitapir
-```
-
-## ⚙️ Configuration
-
-### Basic Configuration
+require 'sinatra/base'
+require 'rapitapir/sinatra/extension'
 
-```ruby
 class MyAPI < Sinatra::Base
   register RapiTapir::Sinatra::Extension
 
   rapitapir do
-    # API metadata
-    info(
-      title: 'My API',
-      description: 'A fantastic API',
-      version: '1.0.0',
-      contact: { email: 'support@example.com' }
-    )
-
-    # Server configuration
-    server url: 'http://localhost:4567', description: 'Development'
-    server url: 'https://api.example.com', description: 'Production'
-
-    # Enable documentation
-    enable_docs path: '/docs', openapi_path: '/openapi.json'
+    info(title: 'My API', version: '2.0.0')
+    development_defaults!
   end
+
+  endpoint(
+    GET('/hello')
+      .query(:name, T.string)
+      .ok(T.hash({ "message" => T.string }))
+      .build
+  ) { |inputs| { message: "Hello, #{inputs[:name]}!" } }
 end
 ```
 
-### Environment-Specific Defaults
+## 📋 Key Features
 
-```ruby
-rapitapir do
-  if development?
-    development_defaults!  # Permissive CORS, high rate limits
-  else
-    production_defaults!   # Secure defaults for production
-  end
-end
-```
+### ✨ Zero Configuration
+- **SinatraRapiTapir base class**: Inherit and start building APIs immediately
+- **T shortcut**: Use `T.string` instead of `RapiTapir::Types.string` everywhere
+- **HTTP verbs**: `GET()`, `POST()`, `PUT()`, `DELETE()` methods built-in
+- **Smart defaults**: Production and development presets that just work
 
-## 🛡️ Authentication
+### 🏭 Enterprise Ready
+- **Built-in authentication**: OAuth2, Bearer token, API key, and custom schemes
+- **Production middleware**: CORS, rate limiting, security headers, request validation
+- **Auto-generated documentation**: Interactive Swagger UI with try-it-out functionality
+- **Type-safe validation**: Automatic request/response validation with helpful errors
 
-### Bearer Token Authentication
+### 🤖 AI Integration
+- **LLM instruction generation**: Auto-generate AI prompts for your endpoints
+- **RAG pipelines**: Retrieval-augmented generation for enhanced responses
+- **MCP export**: Model Context Protocol for AI agent consumption
+- **CLI toolkit**: Complete command-line development workflow
+
+## 📖 Configuration Options
 
+### API Information
 ```ruby
 rapitapir do
-  bearer_auth :bearer, {
-    realm: 'My API',
-    token_validator: proc do |token|
-      user = User.find_by_token(token)
-      next nil unless user
-
-      {
-        user: user,
-        scopes: user.scopes
-      }
-    end
-  }
+  info(
+    title: 'My API',
+    description: 'A comprehensive API for my application',
+    version: '2.0.0',
+    contact: { 
+      name: 'API Team', 
+      email: 'api@example.com',
+      url: 'https://example.com/support'
+    },
+    license: {
+      name: 'MIT',
+      url: 'https://opensource.org/licenses/MIT'
+    }
+  )
+  
+  # Server environments
+  server(url: 'http://localhost:4567', description: 'Development')
+  server(url: 'https://staging-api.example.com', description: 'Staging')
+  server(url: 'https://api.example.com', description: 'Production')
 end
 ```
 
-### API Key Authentication
+### Development vs Production Defaults
 
 ```ruby
+# Development mode (automatic CORS, docs, health checks)
 rapitapir do
-  api_key_auth :api_key, {
-    location: 'header',
-    name: 'X-API-Key',
-    key_validator: proc do |key|
-      # Validate API key
-    end
-  }
+  development_defaults!
 end
-```
 
-### Public Endpoints
+# Production mode (security headers, rate limiting, metrics)
+rapitapir do
+  production_defaults!
+end
 
-```ruby
+# Custom configuration
 rapitapir do
-  public_paths '/health', '/docs', '/openapi.json'
+  enable_docs(path: '/documentation', openapi_path: '/spec.json')
+  enable_cors(origins: ['https://myapp.com'], methods: %w[GET POST])
+  enable_health_checks(path: '/health')
+  enable_metrics(path: '/metrics')
 end
 ```
 
-## 📡 Endpoint Definition
+## 🏗️ Endpoint Definition
 
-### Simple Endpoints
+### Modern HTTP Verb DSL
 
 ```ruby
-endpoint(
-  RapiTapir.get('/users')
-    .summary('List users')
-    .ok(RapiTapir::Types.array(USER_SCHEMA))
-    .build
-) do |inputs|
-  User.all
-end
-```
-
-### With Authentication Requirements
+class BookAPI < SinatraRapiTapir
+  # Basic endpoint
+  endpoint(
+    GET('/books')
+      .summary('List all books')
+      .query(:limit, T.optional(T.integer(minimum: 1, maximum: 100)), description: 'Number of books to return')
+      .query(:genre, T.optional(T.string), description: 'Filter by genre')
+      .ok(T.array(T.hash({
+        "id" => T.integer,
+        "title" => T.string,
+        "author" => T.string,
+        "genre" => T.string
+      })))
+      .build
+  ) do |inputs|
+    books = Book.all
+    books = books.where(genre: inputs[:genre]) if inputs[:genre]
+    books = books.limit(inputs[:limit] || 50)
+    books.map(&:to_h)
+  end
 
-```ruby
-endpoint(
-  RapiTapir.post('/admin/users')
-    .summary('Create user (admin only)')
-    .json_body(USER_CREATE_SCHEMA)
-    .created(USER_SCHEMA)
-    .build
-) do |inputs|
-  require_scope!('admin')
-  User.create(inputs[:body])
+  # POST with body validation
+  endpoint(
+    POST('/books')
+      .summary('Create a new book')
+      .body(T.hash({
+        "title" => T.string(min_length: 1, max_length: 500),
+        "author" => T.string(min_length: 1),
+        "genre" => T.string,
+        "isbn" => T.optional(T.string(pattern: /^\d{13}$/)),
+        "pages" => T.optional(T.integer(minimum: 1))
+      }), description: 'Book data')
+      .ok(T.hash({
+        "id" => T.integer,
+        "title" => T.string,
+        "author" => T.string,
+        "created_at" => T.datetime
+      }), description: 'Created book')
+      .error_response(400, T.hash({ "error" => T.string, "details" => T.array(T.string) }))
+      .build
+  ) do |inputs|
+    begin
+      book = Book.create!(inputs[:body])
+      status 201
+      {
+        id: book.id,
+        title: book.title,
+        author: book.author,
+        created_at: book.created_at
+      }
+    rescue ValidationError => e
+      halt 400, {
+        error: 'Validation failed',
+        details: e.messages
+      }.to_json
+    end
+  end
 end
 ```
 
-## 🏗️ RESTful Resources
+### RESTful Resource Builder
 
-The resource builder creates full CRUD APIs with minimal code:
+Create complete CRUD APIs with minimal code:
 
 ```ruby
-api_resource '/api/v1/tasks', schema: TASK_SCHEMA do
-  # Enable all CRUD operations
-  crud do
-    index { Task.all }
-    show { |inputs| Task.find(inputs[:id]) }
-    create { |inputs| Task.create(inputs[:body]) }
-    update { |inputs| Task.update(inputs[:id], inputs[:body]) }
-    destroy { |inputs| Task.delete(inputs[:id]) }
+class UserAPI < SinatraRapiTapir
+  USER_SCHEMA = T.hash({
+    "id" => T.integer,
+    "name" => T.string(min_length: 1, max_length: 100),
+    "email" => T.email,
+    "active" => T.boolean,
+    "created_at" => T.datetime,
+    "updated_at" => T.datetime
+  })
+
+  api_resource '/users', schema: USER_SCHEMA do
+    crud do
+      index do |inputs|
+        users = User.all
+        users = users.where(active: true) if inputs[:active] == 'true'
+        users.limit(inputs[:limit] || 50).map(&:to_h)
+      end
+      
+      show { |inputs| User.find(inputs[:id])&.to_h || halt(404) }
+      
+      create do |inputs|
+        user = User.create!(inputs[:body])
+        status 201
+        user.to_h
+      end
+      
+      update do |inputs|
+        user = User.find(inputs[:id]) || halt(404)
+        user.update!(inputs[:body])
+        user.to_h
+      end
+      
+      destroy do |inputs|
+        user = User.find(inputs[:id]) || halt(404)
+        user.destroy!
+        status 204
+      end
+    end
+    
+    # Custom endpoints
+    custom :post, ':id/activate' do |inputs|
+      user = User.find(inputs[:id]) || halt(404)
+      user.update!(active: true)
+      { message: 'User activated', user: user.to_h }
+    end
   end
 end
 ```
 
-### Selective Operations
+## 🔐 Authentication
+
+### OAuth2 + Auth0 Integration
 
 ```ruby
-api_resource '/books', schema: BOOK_SCHEMA do
-  crud(except: [:destroy]) do  # All operations except delete
-    index { Book.published }
-    show { |inputs| Book.find(inputs[:id]) }
-    create { |inputs| Book.create(inputs[:body]) }
-    update { |inputs| Book.update(inputs[:id], inputs[:body]) }
+class SecureAPI < SinatraRapiTapir
+  rapitapir do
+    info(title: 'Secure API', version: '2.0.0')
+    
+    # Configure Auth0 OAuth2
+    oauth2_auth0 :auth0,
+      domain: ENV['AUTH0_DOMAIN'],
+      audience: ENV['AUTH0_AUDIENCE'],
+      realm: 'API Access'
+    
+    production_defaults!
   end
-end
-```
-
-### Custom Endpoints
 
-```ruby
-api_resource '/tasks', schema: TASK_SCHEMA do
-  crud { /* ... */ }
-
-  # Custom endpoint: /tasks/by-status/:status
-  custom(:get, 'by-status/:status',
-    summary: 'Get tasks by status',
-    configure: ->(endpoint) {
-      endpoint
-        .path_param(:status, RapiTapir::Types.string)
-        .ok(RapiTapir::Types.array(TASK_SCHEMA))
+  # Protected endpoint with scopes
+  endpoint(
+    GET('/profile')
+      .summary('Get user profile')
+      .bearer_auth(scopes: ['read:profile'])
+      .ok(T.hash({
+        "user" => T.hash({
+          "id" => T.string,
+          "email" => T.string,
+          "name" => T.string
+        })
+      }))
+      .build
+  ) do
+    user_info = current_auth_context[:user_info]
+    {
+      user: {
+        id: user_info['sub'],
+        email: user_info['email'],
+        name: user_info['name']
+      }
     }
-  ) do |inputs|
-    Task.where(status: inputs[:status])
   end
-end
-```
-
-### Different Scopes for Operations
 
-```ruby
-api_resource '/users', schema: USER_SCHEMA do
-  crud do
-    index(scopes: ['read']) { User.all }
-    show(scopes: ['read']) { |inputs| User.find(inputs[:id]) }
-    create(scopes: ['write']) { |inputs| User.create(inputs[:body]) }
-    update(scopes: ['write']) { |inputs| User.update(inputs[:id], inputs[:body]) }
-    destroy(scopes: ['admin']) { |inputs| User.delete(inputs[:id]) }
+  # Scope-based protection for multiple endpoints
+  protect_with_oauth2 scopes: ['api:read'] do
+    endpoint(GET('/protected').ok(T.hash({})).build) { { data: 'protected' } }
+    endpoint(GET('/also-protected').ok(T.hash({})).build) { { data: 'also protected' } }
   end
 end
 ```
 
-## 🔐 Authentication Helpers
+### Bearer Token Authentication
 
 ```ruby
-endpoint(...) do |inputs|
-  # Check if user is authenticated
-  require_authentication!
-
-  # Check specific scope
-  require_scope!('admin')
-
-  # Get current user
-  user = current_user
-
-  # Check if authenticated (non-throwing)
-  if authenticated?
-    # User is logged in
+class TokenAPI < SinatraRapiTapir
+  rapitapir do
+    bearer_auth :api_key, realm: 'API'
+    production_defaults!
   end
 
-  # Check scope (non-throwing)
-  if has_scope?('write')
-    # User has write permission
+  endpoint(
+    GET('/secure-data')
+      .bearer_auth
+      .ok(T.array(T.hash({})))
+      .build
+  ) do
+    # current_auth_context available here
+    SecureData.for_user(current_auth_context[:user_id])
   end
 end
 ```
 
-## 🛠️ Middleware Configuration
+## 🤖 AI Integration
 
-### CORS
+### LLM Instructions and RAG
 
 ```ruby
-rapitapir do
-  cors(
-    allowed_origins: ['https://myapp.com'],
-    allowed_methods: ['GET', 'POST', 'PUT', 'DELETE'],
-    allowed_headers: ['Authorization', 'Content-Type'],
-    allow_credentials: true
-  )
-end
-```
-
-### Rate Limiting
-
-```ruby
-rapitapir do
-  rate_limiting(
-    requests_per_minute: 60,
-    requests_per_hour: 1000
-  )
-end
-```
+class AIEnhancedAPI < SinatraRapiTapir
+  rapitapir do
+    info(title: 'AI-Enhanced API', version: '2.0.0')
+    development_defaults!
+  end
 
-### Security Headers
+  # AI-powered search with RAG
+  endpoint(
+    GET('/books/ai-search')
+      .query(:query, T.string, description: 'Natural language search query')
+      .summary('AI-powered semantic book search')
+      .tags('AI', 'Search')
+      .ok(T.hash({
+        "books" => T.array(BOOK_SCHEMA),
+        "reasoning" => T.string,
+        "confidence" => T.float
+      }))
+      .enable_rag(
+        retrieval_backend: :memory,
+        llm_provider: :openai
+      )
+      .enable_mcp # Export for AI agents
+      .build
+  ) do |inputs|
+    # RAG context automatically injected
+    results = AIBookSearch.semantic_search(
+      query: inputs[:query],
+      context: rag_context
+    )
+    
+    {
+      books: results[:books],
+      reasoning: results[:explanation],
+      confidence: results[:confidence_score]
+    }
+  end
 
-```ruby
-rapitapir do
-  security_headers(
-    csp: "default-src 'self'",
-    hsts: true
-  )
+  # Generate LLM instructions for endpoints
+  endpoint(
+    GET('/ai/instructions/:endpoint_id')
+      .path_param(:endpoint_id, T.string)
+      .query(:purpose, T.string(enum: %w[validation transformation analysis documentation testing completion]))
+      .summary('Generate LLM instructions for an endpoint')
+      .ok(T.hash({
+        "instructions" => T.string,
+        "metadata" => T.hash({})
+      }))
+      .build
+  ) do |inputs|
+    generator = RapiTapir::AI::LLMInstruction::Generator.new
+    endpoint = find_endpoint(inputs[:endpoint_id])
+    
+    instructions = generator.generate_instructions(
+      endpoint: endpoint,
+      purpose: inputs[:purpose].to_sym
+    )
+    
+    {
+      instructions: instructions,
+      metadata: {
+        endpoint_id: inputs[:endpoint_id],
+        purpose: inputs[:purpose],
+        generated_at: Time.now
+      }
+    }
+  end
 end
 ```
 
-## 📚 Documentation
-
-### Automatic OpenAPI Generation
-
-The extension automatically generates OpenAPI 3.0 specifications from your endpoint definitions:
-
-- **Swagger UI**: Beautiful, interactive documentation
-- **Type validation**: Schemas automatically derived from RapiTapir types
-- **Authentication schemes**: Security requirements automatically added
-- **Request/response examples**: Generated from your schemas
+## 📊 Observability
 
-### Custom Documentation
+### Comprehensive Monitoring
 
 ```ruby
-rapitapir do
-  info(
-    title: 'My API',
-    description: 'Comprehensive API documentation',
-    version: '1.0.0',
-    contact: {
-      name: 'Support Team',
-      email: 'support@example.com',
-      url: 'https://example.com/support'
-    },
-    license: {
-      name: 'MIT',
-      url: 'https://opensource.org/licenses/MIT'
-    }
-  )
+class MonitoredAPI < SinatraRapiTapir
+  rapitapir do
+    info(title: 'Monitored API', version: '2.0.0')
+    
+    enable_observability do |config|
+      # Health checks
+      config.health_checks.enable(path: '/health')
+      config.health_checks.add_check('database') { Database.healthy? }
+      config.health_checks.add_check('redis') { Redis.current.ping == 'PONG' }
+      
+      # OpenTelemetry tracing
+      config.tracing.enable_opentelemetry(
+        service_name: 'my-api',
+        exporters: [:honeycomb, :jaeger]
+      )
+      
+      # Prometheus metrics
+      config.metrics.enable_prometheus(namespace: 'my_api')
+      
+      # Structured logging
+      config.logging.enable_structured(format: :json)
+    end
+    
+    production_defaults!
+  end
+
+  # Endpoint with observability features
+  endpoint(
+    GET('/monitored-endpoint')
+      .with_metrics('endpoint_requests', labels: { operation: 'get' })
+      .with_tracing('fetch_data')
+      .ok(T.hash({ "data" => T.string }))
+      .build
+  ) do
+    # Automatic metrics and tracing
+    { data: 'monitored response' }
+  end
 end
 ```
 
-## 🎯 Complete Examples
+## 🧪 Testing
 
-### Minimal Bookstore API
+### Test Your Endpoints
 
 ```ruby
-require 'sinatra/base'
-require 'rapitapir/sinatra/extension'
+require 'rack/test'
 
-class BookstoreAPI < Sinatra::Base
-  register RapiTapir::Sinatra::Extension
+RSpec.describe MyAPI do
+  include Rack::Test::Methods
 
-  rapitapir do
-    info title: 'Bookstore API', version: '1.0.0'
-    development_defaults!
-    public_paths '/books'
+  def app
+    MyAPI
   end
 
-  BOOK_SCHEMA = RapiTapir::Types.hash({
-    "id" => RapiTapir::Types.integer,
-    "title" => RapiTapir::Types.string,
-    "author" => RapiTapir::Types.string
-  })
+  it 'returns hello message' do
+    get '/hello?name=World'
+    
+    expect(last_response).to be_ok
+    expect(JSON.parse(last_response.body)).to eq({
+      'message' => 'Hello, World!'
+    })
+  end
 
-  api_resource '/books', schema: BOOK_SCHEMA do
-    crud do
-      index { Book.all }
-      show { |inputs| Book.find(inputs[:id]) }
-      create { |inputs| Book.create(inputs[:body]) }
-      update { |inputs| Book.update(inputs[:id], inputs[:body]) }
-    end
+  it 'validates required parameters' do
+    get '/hello'
+    
+    expect(last_response.status).to eq(400)
+    expect(JSON.parse(last_response.body)).to include('error')
   end
 end
 ```
 
-### Enterprise Task Management API
-
-See `examples/enterprise_extension_demo.rb` for a comprehensive example with:
-- Bearer token authentication
-- Multiple resources
-- Custom endpoints
-- Admin-only operations
-- Full middleware stack
-
-## 🏛️ Architecture
+### Validate Endpoint Definitions
 
-The RapiTapir Sinatra Extension follows SOLID principles:
-
-### Single Responsibility Principle
-- **Extension**: Manages Sinatra integration only
-- **Configuration**: Handles API configuration only
-- **ResourceBuilder**: Creates RESTful endpoints only
-- **SwaggerUIGenerator**: Generates documentation UI only
+```ruby
+# Validate all endpoints
+validator = RapiTapir::CLI::Validator.new(MyAPI.rapitapir_endpoints)
+result = validator.validate
 
-### Open/Closed Principle
-- **Extensible**: Add new authentication schemes without modifying core
-- **Pluggable**: Custom middleware can be added
-- **Customizable**: Resource builder supports custom endpoints
+puts "Validation passed: #{result}"
+puts "Errors: #{validator.errors}" unless result
+```
 
-### Liskov Substitution Principle
-- **Endpoint compatibility**: Works with any RapiTapir endpoint
-- **Authentication schemes**: All auth schemes follow same interface
+## 🔗 Comparison: Base Class vs Extension
 
-### Interface Segregation Principle
-- **Focused interfaces**: Each component has a specific, minimal interface
-- **Optional features**: Documentation, authentication, middleware are optional
+| Feature | SinatraRapiTapir | Manual Extension |
+|---------|------------------|------------------|
+| Setup complexity | Single inheritance | Manual registration |
+| HTTP verb methods | ✅ Built-in | ✅ Available |
+| T shortcut | ✅ Automatic | ✅ Available |
+| Configuration | ✅ Simple | ✅ Full control |
+| Sinatra features | ✅ All available | ✅ All available |
+| Customization | Good | Excellent |
+| Use case | New APIs, rapid prototyping | Existing apps, advanced needs |
 
-### Dependency Inversion Principle
-- **Abstractions**: Depends on RapiTapir abstractions, not concrete implementations
-- **Injection**: Authentication and validation logic is injected via procs
+## 📚 Examples
 
-## 🔄 Migration from Manual Implementation
+### Complete RESTful API
+See [examples/working_simple_example.rb](../examples/working_simple_example.rb)
 
-Migrating from manual Sinatra routes to the extension:
+### Authentication with Auth0
+See [examples/oauth2/](../examples/oauth2/)
 
-### Before (Manual)
-```ruby
-class MyAPI < Sinatra::Base
-  use SomeMiddleware
-  use SomeOtherMiddleware
-  
-  get '/tasks' do
-    # Manual authentication
-    # Manual validation
-    # Manual response formatting
-  end
-  
-  post '/tasks' do
-    # Repeat authentication, validation, etc.
-  end
-  
-  # Repeat for every endpoint...
-end
-```
+### AI-Powered Features
+See [examples/auto_derivation_ruby_friendly.rb](../examples/auto_derivation_ruby_friendly.rb)
 
-### After (Extension)
-```ruby
-class MyAPI < Sinatra::Base
-  register RapiTapir::Sinatra::Extension
-  
-  rapitapir do
-    bearer_auth { /* config */ }
-    development_defaults!
-  end
-  
-  api_resource '/tasks', schema: TASK_SCHEMA do
-    crud { /* handlers */ }
-  end
-end
-```
+### Production Observability
+See [examples/observability/](../examples/observability/)
 
-## 🤝 Contributing
+## 🎯 Best Practices
 
-1. Fork the repository
-2. Create a feature branch
-3. Add tests for your changes
-4. Ensure all tests pass
-5. Submit a pull request
+1. **Use SinatraRapiTapir** for new projects - it's the simplest approach
+2. **Leverage T shortcuts** everywhere for cleaner type definitions
+3. **Use resource builders** for RESTful APIs to reduce boilerplate
+4. **Enable observability** for production deployments
+5. **Implement proper error handling** with meaningful error responses
+6. **Document with examples** using the built-in OpenAPI generation
+7. **Test endpoint validation** to ensure type safety works correctly
 
-## 📄 License
+---
 
-MIT License - see LICENSE file for details.
+RapiTapir + Sinatra = **APIs so fast and clean, they practically run wild!** 🦙⚡