hypervibe 0.1.0

data/PLAN.md

@@ -0,0 +1,1484 @@
+# Hypervibe: Ruby Framework for AI & Vibe-Coders
+
+## Overview
+
+Hypervibe is a Ruby framework where **AI is the primary developer** and humans provide high-level guidance. Built on the principle that LLMs excel at SQL and JSON Schema but struggle with ORM abstractions, Hypervibe embraces explicit, observable, and streaming-first patterns.
+
+## Core Philosophy
+
+- **SQL as source of truth** - LLMs write SQL directly, no ORM abstractions
+- **Tools & Flows** - Declarative orchestration with machine-readable contracts
+- **Streaming first** - Every operation can stream partial results
+- **Observable by default** - Event logs, traces, and replay capabilities
+- **Schema everywhere** - JSON Schema validation on all boundaries
+- **AI-native testing** - Golden tests, dry-runs, and prompt versioning
+
+## Installation & Setup
+
+```bash
+# Install the gem
+gem install hypervibe
+
+# Create a new project
+vibe new my_app
+cd my_app
+
+# Start development server with trace viewer
+vibe server
+
+# Generate components
+vibe generate tool send_notification
+vibe generate flow user_onboarding
+vibe generate query users
+```
+
+## Core Architecture
+
+### 1. Data Layer: sqlc-style Repositories
+
+SQL files define all queries. Hypervibe generates type-safe Ruby methods automatically.
+
+#### SQL Query Files
+
+```sql
+-- queries/users.sql
+
+-- name: GetUser :one
+SELECT * FROM users WHERE id = $1;
+
+-- name: FindByEmail :one
+SELECT id, email, name, created_at
+FROM users
+WHERE email = $1
+LIMIT 1;
+
+-- name: ListActiveUsers :many
+-- cache: 5.minutes
+SELECT id, name, email
+FROM users
+WHERE deleted_at IS NULL
+ORDER BY created_at DESC
+LIMIT $1;
+
+-- name: CreateUser :one
+INSERT INTO users (email, name, password_hash)
+VALUES ($1, $2, $3)
+RETURNING *;
+
+-- name: UpdateLastLogin :exec
+UPDATE users
+SET last_login_at = NOW()
+WHERE id = $1;
+
+-- name: CountUserPosts :one
+SELECT COUNT(*) as post_count
+FROM posts
+WHERE user_id = $1 AND published = true;
+
+-- name: GetUserWithStats :one
+WITH post_stats AS (
+  SELECT
+    user_id,
+    COUNT(*) as post_count,
+    MAX(created_at) as last_post_at
+  FROM posts
+  WHERE user_id = $1
+  GROUP BY user_id
+)
+SELECT
+  u.*,
+  COALESCE(ps.post_count, 0) as post_count,
+  ps.last_post_at
+FROM users u
+LEFT JOIN post_stats ps ON ps.user_id = u.id
+WHERE u.id = $1;
+```
+
+#### Auto-Generated Repository Module
+
+```ruby
+# Auto-generated from queries/users.sql
+Repo[:users] do
+  query :get_user,
+        sql: "SELECT * FROM users WHERE id = $1",
+        args: [{id: :uuid}],
+        returns: User
+
+  query :find_by_email,
+        sql: "SELECT id, email, name, created_at FROM users WHERE email = $1 LIMIT 1",
+        args: [{email: :string}],
+        returns: {id: :uuid, email: :string, name: :string, created_at: :timestamp}
+
+  query :list_active_users,
+        sql: "SELECT id, name, email FROM users WHERE deleted_at IS NULL ORDER BY created_at DESC LIMIT $1",
+        args: [{limit: :int}],
+        returns: [{id: :uuid, name: :string, email: :string}],
+        cache: 5.minutes
+
+  cmd :create_user,
+      sql: "INSERT INTO users (email, name, password_hash) VALUES ($1, $2, $3) RETURNING *",
+      args: [{email: :string}, {name: :string}, {password_hash: :string}],
+      returns: User
+
+  cmd :update_last_login,
+      sql: "UPDATE users SET last_login_at = NOW() WHERE id = $1",
+      args: [{id: :uuid}]
+
+  query :count_user_posts,
+        sql: "SELECT COUNT(*) as post_count FROM posts WHERE user_id = $1 AND published = true",
+        args: [{user_id: :uuid}],
+        returns: {post_count: :integer}
+end
+```
+
+#### Usage in Code
+
+```ruby
+# Simple queries
+user = Repo[:users].get_user(id: params[:id])
+user = Repo[:users].find_by_email(email: "alice@example.com")
+
+# Returns array of hashes
+active_users = Repo[:users].list_active_users(limit: 10)
+
+# Commands
+new_user = Repo[:users].create_user(
+  email: "bob@example.com",
+  name: "Bob",
+  password_hash: BCrypt::Password.create("secret")
+)
+
+# Every query result includes metadata
+result = Repo[:users].get_user(id: 123)
+result._sql      # => "SELECT * FROM users WHERE id = $1"
+result._timing   # => 23.5 (ms)
+result._explain  # => Query plan
+```
+
+### 2. Vector & Document Stores
+
+Native support for modern AI data patterns:
+
+```sql
+-- queries/embeddings.sql
+
+-- name: SearchSimilarDocs :many
+-- adapter: pgvector
+SELECT
+  id,
+  content,
+  metadata,
+  1 - (embedding <=> $1) as similarity
+FROM documents
+WHERE 1 - (embedding <=> $1) > $2
+ORDER BY embedding <=> $1
+LIMIT $3;
+
+-- name: StoreDocument :one
+-- adapter: jsonb
+INSERT INTO documents (content, metadata, embedding)
+VALUES ($1, $2, $3)
+RETURNING id;
+
+-- name: UpdateDocumentMetadata :exec
+-- adapter: jsonb
+UPDATE documents
+SET metadata = metadata || $2
+WHERE id = $1;
+```
+
+```ruby
+# Vector search
+similar_docs = Repo[:embeddings].search_similar_docs(
+  embedding: AI.embed("user query"),
+  threshold: 0.7,
+  limit: 10
+)
+
+# Document storage with JSONB
+doc_id = Repo[:embeddings].store_document(
+  content: "Full text content...",
+  metadata: {source: "upload", user_id: 123},
+  embedding: AI.embed("Full text content...")
+)
+```
+
+### 3. Tools: Single Definition, Multiple Interfaces
+
+Tools are atomic units of side-effects with JSON Schema contracts:
+
+```ruby
+class Tools::SendEmail
+  include Hypervibe::Tool
+
+  tool "send_email",
+    desc: "Send a transactional email",
+    examples: [
+      {
+        input: {
+          to: "user@example.com",
+          subject: "Welcome!",
+          body_html: "<p>Hello</p>"
+        },
+        output: {
+          message_id: "msg_123",
+          status: "sent"
+        }
+      }
+    ],
+    input: {
+      to: {type: "string", format: "email", required: true},
+      subject: {type: "string", maxLength: 200, required: true},
+      body_html: {type: "string", required: true},
+      reply_to: {type: "string", format: "email"},
+      attachments: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            filename: {type: "string"},
+            content: {type: "string", format: "base64"}
+          }
+        }
+      }
+    },
+    output: {
+      message_id: {type: "string"},
+      status: {type: "string", enum: ["sent", "queued"]},
+      delivered_at: {type: "string", format: "date-time"}
+    },
+    errors: {
+      invalid_email: "The provided email address is not valid",
+      rate_limited: "Too many emails sent recently",
+      attachment_too_large: "Attachment exceeds 10MB limit"
+    },
+    capabilities: ["email:send"]
+
+  def call(to:, subject:, body_html:, reply_to: nil, attachments: [])
+    validate_rate_limit!(to)
+    validate_attachments!(attachments)
+
+    id = Mailer.deliver(
+      to: to,
+      subject: subject,
+      html: body_html,
+      reply_to: reply_to,
+      attachments: process_attachments(attachments)
+    )
+
+    emit :email_sent, {
+      to: to,
+      message_id: id,
+      timestamp: Time.now
+    }
+
+    {
+      message_id: id,
+      status: "sent",
+      delivered_at: Time.now.iso8601
+    }
+  rescue RateLimitError
+    error! :rate_limited
+  rescue AttachmentError => e
+    error! :attachment_too_large, details: e.message
+  end
+
+  private
+
+  def validate_attachments!(attachments)
+    attachments.each do |att|
+      size = Base64.decode64(att[:content]).bytesize
+      raise AttachmentError if size > 10.megabytes
+    end
+  end
+end
+```
+
+This single tool definition automatically generates:
+
+- HTTP endpoint: `POST /tools/send_email`
+- CLI command: `vibe tool send_email --to user@example.com --subject "Test"`
+- LLM tool spec (OpenAI/Anthropic format)
+- OpenAPI documentation
+- Contract tests from examples
+- GraphQL mutation (optional)
+
+### 4. Flows: Declarative Orchestration
+
+Flows compose tools, AI calls, and queries into resumable workflows:
+
+```ruby
+flow "onboard_user",
+     budget_cents: 5_00,
+     timeout: 30.seconds,
+     stream: true,
+     capabilities: [
+       "repo:users:write",
+       "repo:profiles:write",
+       "tool:send_email",
+       "tool:schedule_job"
+     ] do
+
+  # Step 1: Validate and create user
+  step :user do
+    existing = Repo[:users].find_by_email(email: params[:email])
+    error!(:user_exists) if existing
+
+    Repo[:users].create_user(
+      email: params[:email],
+      name: params[:name],
+      password_hash: hash_password(params[:password])
+    )
+  end
+
+  # Step 2: Generate personalized content with AI
+  ai :welcome_content,
+     model: "gpt-4o-mini",
+     temperature: 0.7,
+     cache: 1.hour,
+     max_tokens: 500,
+     schema: {
+       type: "object",
+       properties: {
+         subject: {type: "string", maxLength: 100},
+         body_html: {type: "string"},
+         onboarding_tips: {
+           type: "array",
+           items: {type: "string"},
+           minItems: 3,
+           maxItems: 5
+         },
+         suggested_connections: {
+           type: "array",
+           items: {
+             type: "object",
+             properties: {
+               user_id: {type: "integer"},
+               reason: {type: "string"}
+             }
+           }
+         }
+       },
+       required: ["subject", "body_html", "onboarding_tips"]
+     } do
+    system """
+      You are a friendly onboarding assistant. Be concise and helpful.
+      The app is a professional networking platform.
+    """
+
+    user """
+      Create a welcome email for a new user:
+      Name: {{ steps.user.name }}
+      Email: {{ steps.user.email }}
+      Company domain: {{ steps.user.email.split('@').last }}
+      Signed up: {{ steps.user.created_at }}
+
+      Include personalized onboarding tips based on their email domain.
+      Suggest potential connections if you recognize the company.
+    """
+  end
+
+  # Step 3: Create user profile
+  step :profile do
+    Repo[:profiles].create(
+      user_id: steps.user.id,
+      onboarding_tips: steps.welcome_content["onboarding_tips"],
+      suggested_connections: steps.welcome_content["suggested_connections"],
+      stage: "welcome_sent"
+    )
+  end
+
+  # Step 4: Send welcome email
+  tool :email, Tools::SendEmail,
+       to: params[:email],
+       subject: steps.welcome_content["subject"],
+       body_html: steps.welcome_content["body_html"]
+
+  # Step 5: Schedule follow-up sequence
+  parallel do
+    tool :follow_up_1, Tools::ScheduleJob,
+         job_type: "engagement_email",
+         run_at: 1.day.from_now,
+         params: {user_id: steps.user.id, email_type: "tips"}
+
+    tool :follow_up_2, Tools::ScheduleJob,
+         job_type: "engagement_email",
+         run_at: 3.days.from_now,
+         params: {user_id: steps.user.id, email_type: "connections"}
+
+    tool :follow_up_3, Tools::ScheduleJob,
+         job_type: "engagement_email",
+         run_at: 7.days.from_now,
+         params: {user_id: steps.user.id, email_type: "check_in"}
+  end
+
+  # Completion
+  emit :onboarding_complete, {
+    user_id: steps.user.id,
+    email_sent: steps.email.message_id,
+    follow_ups_scheduled: [
+      steps.follow_up_1.job_id,
+      steps.follow_up_2.job_id,
+      steps.follow_up_3.job_id
+    ]
+  }
+end
+```
+
+### 5. Event Log & Replay System
+
+Every flow execution creates an immutable event log:
+
+```ruby
+# Event log structure
+[
+  {
+    id: "evt_001",
+    type: "flow_started",
+    flow: "onboard_user",
+    run_id: "run_abc123",
+    params: {email: "alice@example.com"},
+    timestamp: "2024-01-15T10:00:00Z",
+    correlation_id: "req_xyz"
+  },
+  {
+    id: "evt_002",
+    type: "step_started",
+    step: "user",
+    run_id: "run_abc123",
+    timestamp: "2024-01-15T10:00:00.100Z"
+  },
+  {
+    id: "evt_003",
+    type: "sql_executed",
+    query: "SELECT id, email FROM users WHERE email = $1",
+    args: ["alice@example.com"],
+    duration_ms: 23,
+    rows_returned: 0,
+    run_id: "run_abc123",
+    timestamp: "2024-01-15T10:00:00.123Z"
+  },
+  {
+    id: "evt_004",
+    type: "sql_executed",
+    query: "INSERT INTO users...",
+    duration_ms: 45,
+    rows_affected: 1,
+    run_id: "run_abc123",
+    timestamp: "2024-01-15T10:00:00.168Z"
+  },
+  {
+    id: "evt_005",
+    type: "step_completed",
+    step: "user",
+    result: {id: 123, email: "alice@example.com"},
+    run_id: "run_abc123",
+    timestamp: "2024-01-15T10:00:00.213Z"
+  },
+  {
+    id: "evt_006",
+    type: "ai_request",
+    model: "gpt-4o-mini",
+    prompt_tokens: 234,
+    temperature: 0.7,
+    run_id: "run_abc123",
+    timestamp: "2024-01-15T10:00:00.250Z"
+  },
+  {
+    id: "evt_007",
+    type: "ai_response",
+    completion_tokens: 156,
+    total_tokens: 390,
+    cost_cents: 0.0234,
+    result: {subject: "Welcome!", body_html: "..."},
+    run_id: "run_abc123",
+    timestamp: "2024-01-15T10:00:01.750Z"
+  },
+  {
+    id: "evt_008",
+    type: "tool_called",
+    tool: "send_email",
+    input: {to: "alice@example.com", subject: "Welcome!"},
+    run_id: "run_abc123",
+    timestamp: "2024-01-15T10:00:01.800Z"
+  },
+  {
+    id: "evt_009",
+    type: "tool_completed",
+    tool: "send_email",
+    output: {message_id: "msg_789", status: "sent"},
+    duration_ms: 234,
+    run_id: "run_abc123",
+    timestamp: "2024-01-15T10:00:02.034Z"
+  },
+  {
+    id: "evt_010",
+    type: "flow_completed",
+    flow: "onboard_user",
+    run_id: "run_abc123",
+    duration_ms: 2034,
+    total_cost_cents: 0.0234,
+    timestamp: "2024-01-15T10:00:02.034Z"
+  }
+]
+```
+
+#### Replay & Time Travel
+
+```ruby
+# Replay a flow with fixed responses (for testing)
+replay = Flow.replay("onboard_user", run_id: "run_abc123") do
+  mock_ai :welcome_content, returns: {
+    subject: "Welcome to the platform!",
+    body_html: "<p>We're excited to have you...</p>",
+    onboarding_tips: ["Complete your profile", "Connect with colleagues", "Join groups"]
+  }
+  mock_tool :email, returns: {message_id: "msg_test", status: "sent"}
+end
+
+# Inspect any historical run
+run = Flow.runs.find("run_abc123")
+run.trace           # Full execution trace
+run.cost           # Token costs: $0.0234
+run.duration       # 2034ms
+run.events         # All events
+run.replay(until: :email)  # Partial replay up to email step
+
+# Time travel debugging
+Flow.debug("run_abc123") do |debugger|
+  debugger.step_forward   # Execute next event
+  debugger.inspect(:user) # See state at this point
+  debugger.rewind_to(:ai_request)  # Go back in time
+  debugger.modify_and_continue(     # What-if analysis
+    ai_response: {subject: "Different subject"}
+  )
+end
+```
+
+### 6. Prompts as Code
+
+Prompts are versioned, tested, and compiled:
+
+```ruby
+# prompts/summarizer.prompt.rb
+prompt "summarize_document",
+  model: "gpt-4o",
+  temperature: 0.3,
+  version: "1.2.0",
+  changelog: {
+    "1.2.0" => "Added sentiment analysis",
+    "1.1.0" => "Improved key point extraction",
+    "1.0.0" => "Initial version"
+  },
+  schema: {
+    type: "object",
+    properties: {
+      summary: {type: "string", minLength: 100, maxLength: 500},
+      key_points: {
+        type: "array",
+        items: {type: "string"},
+        minItems: 3,
+        maxItems: 7
+      },
+      sentiment: {type: "string", enum: ["positive", "neutral", "negative"]},
+      confidence: {type: "number", minimum: 0, maximum: 1}
+    },
+    required: ["summary", "key_points", "sentiment", "confidence"]
+  } do
+
+  system """
+    You are a document summarizer. Be concise and extract key information.
+    Focus on actionable insights and main arguments.
+    Always assess the overall sentiment and your confidence level.
+  """
+
+  user """
+    Summarize this document:
+
+    {{ document }}
+
+    Document metadata:
+    - Length: {{ document.length }} characters
+    - Source: {{ metadata.source }}
+    - Date: {{ metadata.date }}
+  """
+
+  # Golden examples for testing
+  example "earnings_report" do
+    input document: "Q3 2024 Earnings Report: Revenue increased 23% YoY to $4.5B...",
+          metadata: {source: "SEC Filing", date: "2024-10-15"}
+
+    output {
+      summary: "Q3 earnings exceeded expectations with 23% YoY revenue growth...",
+      key_points: [
+        "Revenue up 23% to $4.5B",
+        "New product line contributed 30% of growth",
+        "Guidance raised for Q4"
+      ],
+      sentiment: "positive",
+      confidence: 0.95
+    }
+  end
+
+  example "incident_report" do
+    input document: "Service Outage Report: At 14:30 UTC, our primary database...",
+          metadata: {source: "Internal", date: "2024-10-20"}
+
+    output {
+      summary: "Database outage affected 15% of users for 45 minutes...",
+      key_points: [
+        "45-minute outage on October 20",
+        "15% of users affected",
+        "Root cause: connection pool exhaustion"
+      ],
+      sentiment: "negative",
+      confidence: 0.90
+    }
+  end
+
+  # Validation rules
+  validate do |output|
+    # Summary should mention key numbers from input
+    if input[:document].include?("23%") && !output[:summary].include?("23")
+      error "Summary should include key metrics"
+    end
+
+    # Confidence should be lower for ambiguous content
+    if output[:sentiment] == "neutral" && output[:confidence] > 0.8
+      warning "High confidence unusual for neutral sentiment"
+    end
+  end
+end
+```
+
+Usage:
+
+```ruby
+# Use the prompt
+result = Prompts.summarize_document(
+  document: File.read("report.pdf"),
+  metadata: {source: "uploaded", date: Date.today}
+)
+
+# Access versioned prompts
+result_v1 = Prompts.summarize_document.v("1.0.0").call(document: "...")
+
+# Test prompts
+Prompts.test("summarize_document") do
+  run_golden_examples  # Runs all defined examples
+  run_validation_suite # Checks edge cases
+  run_regression_tests # Ensures backwards compatibility
+end
+```
+
+### 7. Streaming & Real-time Updates
+
+All flows stream by default via Server-Sent Events (SSE):
+
+```ruby
+# HTTP endpoint automatically streams
+GET /flows/onboard_user/run?email=user@example.com
+
+# Response stream:
+event: flow_started
+data: {"flow": "onboard_user", "run_id": "run_abc123"}
+
+event: step_completed
+data: {"step": "user", "result": {"id": 123, "email": "user@example.com"}}
+
+event: ai_token
+data: {"content": "Welcome"}
+
+event: ai_token
+data: {"content": " to"}
+
+event: ai_token
+data: {"content": " our platform!"}
+
+event: step_completed
+data: {"step": "welcome_content", "tokens_used": 156, "cost_cents": 0.0234}
+
+event: progress
+data: {"percent": 75, "message": "Sending email..."}
+
+event: tool_completed
+data: {"tool": "send_email", "result": {"message_id": "msg_123"}}
+
+event: flow_completed
+data: {"run_id": "run_abc123", "duration_ms": 2341, "cost_cents": 0.0234}
+```
+
+Ruby client with streaming:
+
+```ruby
+Flow.run("onboard_user", email: "test@example.com") do |event|
+  case event.type
+  when :ai_token
+    print event.data[:content]  # Stream AI response char by char
+  when :step_completed
+    puts "\n✓ #{event.step} completed"
+  when :progress
+    update_progress_bar(event.data[:percent])
+  when :error
+    handle_error(event.data)
+  end
+end
+```
+
+JavaScript client:
+
+```javascript
+const events = new EventSource(
+  "/flows/onboard_user/run?email=test@example.com",
+);
+
+events.addEventListener("ai_token", (e) => {
+  const data = JSON.parse(e.data);
+  document.getElementById("output").innerHTML += data.content;
+});
+
+events.addEventListener("flow_completed", (e) => {
+  const data = JSON.parse(e.data);
+  console.log(
+    `Completed in ${data.duration_ms}ms, cost: $${data.cost_cents / 100}`,
+  );
+  events.close();
+});
+```
+
+### 8. Development Tools
+
+#### Interactive Console
+
+```ruby
+$ vibe console
+
+> experiment do
+    # Test queries with immediate feedback
+    user = Repo[:users].find_by_email("test@example.com")
+    see_sql           # Shows: SELECT id, email, name FROM users WHERE email = $1
+    see_explain       # Shows query plan
+
+    # Test AI generations
+    draft = AI.generate("Write a haiku about #{user.name}")
+    show_tokens       # Token count: 45 prompt, 17 completion
+    show_cost         # Cost: $0.0003
+
+    # Compare variations
+    test_with temperature: 0.3
+    test_with temperature: 0.9
+    compare_results   # Shows diff between outputs
+
+    # Modify and retry
+    undo_last
+    retry_with model: "gpt-4o"
+  end
+
+> # Direct repository access
+> Repo[:users].get_user(id: 123)._timing
+=> 12.3  # milliseconds
+
+> # Test tools in isolation
+> Tools::SendEmail.dry_run(to: "test@example.com", subject: "Test")
+=> {message_id: "dry_run_msg_123", status: "sent", dry_run: true}
+```
+
+#### Web-based Trace Viewer
+
+```ruby
+# Built-in web UI at http://localhost:3000/__traces__
+# Features:
+# - Flow execution DAG visualization
+# - Step-by-step replay
+# - SQL queries with EXPLAIN ANALYZE
+# - AI prompts/responses with token counts
+# - Tool inputs/outputs
+# - Waterfall timing diagram
+# - Cost breakdown by step
+# - Event log browser
+# - Performance profiling
+```
+
+#### Golden Tests
+
+```ruby
+# test/flows/onboard_user_test.rb
+describe Flow["onboard_user"] do
+  test "successful onboarding" do
+    # Use recorded AI responses for deterministic tests
+    with_golden_fixtures do
+      result = run_flow(
+        email: "newuser@example.com",
+        name: "Alice",
+        password: "secure123"
+      )
+
+      # Assert on each step
+      assert_step :user do |user|
+        assert_equal "Alice", user.name
+        assert_equal "newuser@example.com", user.email
+      end
+
+      assert_ai :welcome_content do |prompt, response|
+        assert_includes prompt, "Alice"
+        assert response["onboarding_tips"].length >= 3
+      end
+
+      assert_tool :email do |input, output|
+        assert_equal "newuser@example.com", input[:to]
+        assert output[:message_id].present?
+      end
+
+      assert_event :onboarding_complete
+      assert_total_cost_under 0.10  # $0.10
+      assert_duration_under 3000    # 3 seconds
+    end
+  end
+
+  test "handles existing user" do
+    create_user(email: "existing@example.com")
+
+    assert_flow_error :user_exists do
+      run_flow(email: "existing@example.com")
+    end
+  end
+end
+```
+
+#### Contract Testing
+
+```ruby
+# Automatically generated from tool definitions
+describe Tools::SendEmail do
+  test_contract do
+    # Tests each example defined in the tool
+    example "welcome_email" do
+      assert_input_valid
+      assert_output_matches_schema
+      assert_idempotent
+    end
+
+    # Property-based testing
+    property "handles all valid emails" do
+      email = generate(:email)
+      result = call(to: email, subject: "Test", body_html: "<p>Test</p>")
+      assert result[:message_id].present?
+    end
+  end
+end
+```
+
+### 9. Security & Governance
+
+#### Capability-Based Security
+
+```ruby
+flow "process_payment",
+     capabilities: [
+       "repo:orders:read",
+       "repo:payments:write",
+       "tool:charge_card:max_amount:10000",
+       "tool:send_email:domain:receipts@myapp.com",
+       "ai:gpt-4o-mini:max_tokens:500"
+     ] do
+
+  # Runtime enforces capability boundaries
+  step :order do
+    Repo[:orders].find(id: params[:order_id])  # ✓ Allowed (read)
+    # Repo[:orders].update(...) would fail - no write capability
+  end
+
+  tool :charge, Tools::ChargeCard,
+       amount: steps.order.amount  # Runtime validates against max_amount
+
+  # This would fail - domain not in capabilities
+  # tool :email, Tools::SendEmail, to: "admin@evil.com"
+end
+
+# Capabilities can be delegated
+sub_flow "send_receipt",
+         inherit_capabilities: ["tool:send_email:domain:receipts@myapp.com"] do
+  # Can only send to receipts@myapp.com
+end
+```
+
+#### Policy Engine
+
+```yaml
+# config/policies.yml
+policies:
+  flows:
+    - pattern: "process_payment"
+      rules:
+        max_amount_cents: 100000
+        require_human_approval: "amount_cents > 50000"
+        rate_limit: "100/hour"
+        require_2fa: true
+
+    - pattern: "delete_*"
+      rules:
+        require_human_approval: true
+        audit_log: enhanced
+
+  tools:
+    - name: "send_email"
+      rules:
+        forbidden_domains: ["competitor.com", "spam.net"]
+        rate_limit: "10/minute per recipient"
+        require_spf_check: true
+
+    - name: "charge_card"
+      rules:
+        test_mode: "Rails.env.development?"
+        fraud_check: "amount > 1000"
+
+  ai:
+    - model: "gpt-4o"
+      rules:
+        max_tokens: 2000
+        require_approval: "tokens > 1000"
+        log_prompts: true
+
+    - model: "gpt-4o-mini"
+      rules:
+        max_tokens: 500
+        temperature_max: 0.8
+```
+
+#### Audit Logging
+
+```ruby
+# Every action is logged with full context
+AuditLog.recent
+# =>
+# [
+#   {
+#     action: "flow.executed",
+#     flow: "process_payment",
+#     user_id: 123,
+#     run_id: "run_xyz",
+#     capabilities_used: ["repo:payments:write", "tool:charge_card"],
+#     cost_cents: 0.0234,
+#     ip: "192.168.1.1",
+#     timestamp: "2024-01-15T10:00:00Z"
+#   }
+# ]
+```
+
+### 10. Deployment & Production
+
+#### Configuration
+
+```ruby
+# config/hypervibe.rb
+Hypervibe.configure do |config|
+  # Database pools
+  config.database_url = ENV["DATABASE_URL"]
+  config.read_replica_urls = [
+    ENV["READ_REPLICA_1"],
+    ENV["READ_REPLICA_2"]
+  ]
+
+  # Redis for caching & queues
+  config.redis_url = ENV["REDIS_URL"]
+
+  # AI Models
+  config.ai_providers = {
+    openai: {api_key: ENV["OPENAI_API_KEY"]},
+    anthropic: {api_key: ENV["ANTHROPIC_API_KEY"]},
+    local: {url: "http://localhost:11434"}  # Ollama
+  }
+
+  # Observability
+  config.telemetry = {
+    provider: :datadog,
+    api_key: ENV["DD_API_KEY"],
+    service_name: "hypervibe-app"
+  }
+
+  # Storage
+  config.event_store = :postgres  # or :kafka, :eventstore
+  config.file_storage = :s3       # or :disk, :gcs
+end
+```
+
+#### Deployment Commands
+
+```bash
+# Database setup
+vibe db:create
+vibe db:migrate
+vibe db:seed
+
+# Generate TypeScript types from schemas
+vibe generate:types
+
+# Run tests
+vibe test
+vibe test:golden  # Run golden prompt tests
+vibe test:contracts  # Test tool contracts
+
+# Production deployment
+vibe deploy --environment production
+
+# Scale workers
+vibe scale flow_workers=10
+vibe scale tool_workers=5
+
+# Monitor
+vibe logs --tail
+vibe metrics
+vibe traces --flow onboard_user
+```
+
+### 11. Migration from Rails/Sinatra
+
+Hypervibe can be gradually adopted in existing apps:
+
+```ruby
+# In Rails app - mount Hypervibe
+# config/routes.rb
+Rails.application.routes.draw do
+  mount Hypervibe::Web, at: "/flows"
+
+  # Existing routes still work
+  resources :users
+  resources :posts
+end
+
+# Gradually migrate controllers to flows
+class UsersController < ApplicationController
+  def create
+    # Old code still works
+    @user = User.create!(user_params)
+
+    # But trigger flows for new functionality
+    Flow.run_async("onboard_user",
+      email: @user.email,
+      name: @user.name
+    )
+
+    redirect_to @user
+  end
+end
+
+# Share database connections
+Hypervibe.configure do |config|
+  config.database = ActiveRecord::Base.connection_pool
+end
+
+# Reuse existing models if needed (read-only)
+class User < ActiveRecord::Base
+  # Existing AR model
+end
+
+# But write through repositories
+Repo[:users].create_user(...)  # Uses SQL directly
+```
+
+### 12. Project Structure
+
+```
+my_app/
+├── app/
+│   ├── queries/          # SQL files (source of truth)
+│   │   ├── users.sql
+│   │   ├── posts.sql
+│   │   ├── embeddings.sql
+│   │   └── analytics.sql
+│   ├── tools/            # Reusable tools with contracts
+│   │   ├── send_email.rb
+│   │   ├── charge_card.rb
+│   │   ├── generate_pdf.rb
+│   │   └── slack_notifier.rb
+│   ├── flows/            # Business workflows
+│   │   ├── onboard_user.rb
+│   │   ├── process_order.rb
+│   │   ├── weekly_digest.rb
+│   │   └── data_pipeline.rb
+│   ├── prompts/          # Versioned prompt templates
+│   │   ├── summarizer.prompt.rb
+│   │   ├── email_writer.prompt.rb
+│   │   └── code_reviewer.prompt.rb
+│   └── projections/      # Event projections for read models
+│       ├── user_stats.rb
+│       └── revenue_dashboard.rb
+│
+├── config/
+│   ├── hypervibe.rb      # Main configuration
+│   ├── policies.yml      # Security policies
+│   └── database.yml      # Database configuration
+│
+├── generated/            # Auto-generated (git-ignored)
+│   ├── repos/            # Type-safe query modules
+│   ├── openapi.json      # API documentation
+│   ├── tool_specs.json   # LLM tool definitions
+│   └── types.ts          # TypeScript definitions
+│
+├── test/
+│   ├── flows/            # Flow tests with golden examples
+│   ├── tools/            # Tool contract tests
+│   ├── prompts/          # Prompt regression tests
+│   └── fixtures/         # Recorded AI responses
+│
+├── web/                  # Optional web UI
+│   ├── traces/           # Trace viewer
+│   └── dashboard/        # Metrics dashboard
+│
+└── Vibefile              # Project configuration
+```
+
+### 13. Example: Complete Feature Implementation
+
+Here's how you'd implement a complete feature in Hypervibe:
+
+```sql
+-- queries/articles.sql
+
+-- name: CreateArticle :one
+INSERT INTO articles (author_id, title, content, status)
+VALUES ($1, $2, $3, 'draft')
+RETURNING *;
+
+-- name: PublishArticle :one
+UPDATE articles
+SET status = 'published', published_at = NOW()
+WHERE id = $1
+RETURNING *;
+
+-- name: GetArticleWithAuthor :one
+SELECT
+  a.*,
+  u.name as author_name,
+  u.email as author_email
+FROM articles a
+JOIN users u ON u.id = a.author_id
+WHERE a.id = $1;
+```
+
+```ruby
+# tools/moderate_content.rb
+class Tools::ModerateContent
+  include Hypervibe::Tool
+
+  tool "moderate_content",
+    desc: "Check content for policy violations",
+    input: {
+      content: {type: "string", required: true},
+      content_type: {type: "string", enum: ["article", "comment"]}
+    },
+    output: {
+      safe: {type: "boolean"},
+      issues: {type: "array", items: {type: "string"}},
+      confidence: {type: "number"}
+    }
+
+  def call(content:, content_type:)
+    result = AI.moderate(content)
+
+    {
+      safe: result[:safe],
+      issues: result[:issues],
+      confidence: result[:confidence]
+    }
+  end
+end
+```
+
+```ruby
+# flows/publish_article.rb
+flow "publish_article",
+     stream: true,
+     timeout: 30.seconds do
+
+  step :article do
+    Repo[:articles].get_article_with_author(id: params[:article_id])
+  end
+
+  guard "author must match" do
+    steps.article.author_id == params[:user_id]
+  end
+
+  tool :moderation, Tools::ModerateContent,
+       content: steps.article.content,
+       content_type: "article"
+
+  guard "content must be safe" do
+    steps.moderation.safe
+  end
+
+  ai :improvements,
+     model: "gpt-4o-mini",
+     optional: true,  # Don't fail if AI is down
+     schema: {
+       type: "object",
+       properties: {
+         seo_title: {type: "string", maxLength: 60},
+         meta_description: {type: "string", maxLength: 160},
+         tags: {type: "array", items: {type: "string"}}
+       }
+     } do
+    system "You are an SEO expert."
+    user "Generate SEO metadata for: {{ steps.article.title }}"
+  end
+
+  step :publish do
+    article = Repo[:articles].publish_article(id: params[:article_id])
+
+    if steps.improvements
+      Repo[:articles].update_metadata(
+        id: article.id,
+        seo_title: steps.improvements["seo_title"],
+        meta_description: steps.improvements["meta_description"],
+        tags: steps.improvements["tags"]
+      )
+    end
+
+    article
+  end
+
+  parallel do
+    tool :notify_followers, Tools::NotifyFollowers,
+         author_id: steps.article.author_id,
+         article_id: steps.article.id
+
+    tool :index_search, Tools::IndexForSearch,
+         type: "article",
+         id: steps.article.id,
+         content: steps.article.content
+
+    tool :social_share, Tools::ScheduleSocialPosts,
+         article_id: steps.article.id,
+         platforms: ["twitter", "linkedin"]
+  end
+
+  emit :article_published, {
+    article_id: steps.article.id,
+    author_id: steps.article.author_id,
+    published_at: steps.publish.published_at
+  }
+end
+```
+
+### 14. Advanced Features
+
+#### Sub-flows and Composition
+
+```ruby
+flow "process_batch",
+     concurrency: 10 do
+
+  step :items do
+    Repo[:queue].get_pending_items(limit: 100)
+  end
+
+  # Process items in parallel with sub-flows
+  map :processed, over: steps.items do |item|
+    sub_flow "process_item",
+            item_id: item.id,
+            inherit_capabilities: true
+  end
+
+  # Aggregate results
+  reduce :summary do
+    {
+      total: steps.processed.count,
+      successful: steps.processed.count(&:success?),
+      failed: steps.processed.count(&:failed?),
+      total_cost: steps.processed.sum(&:cost)
+    }
+  end
+
+  emit :batch_complete, steps.summary
+end
+```
+
+#### Human-in-the-Loop
+
+```ruby
+flow "content_review" do
+  ai :draft,
+     model: "gpt-4o" do
+    system "Write an article about AI safety"
+  end
+
+  # Pause for human review
+  checkpoint :human_review,
+            timeout: 24.hours,
+            notify: ["editor@example.com"] do
+
+    present steps.draft
+
+    actions [
+      {label: "Approve", value: "approve"},
+      {label: "Request Changes", value: "revise"},
+      {label: "Reject", value: "reject"}
+    ]
+  end
+
+  case steps.human_review.action
+  when "approve"
+    tool :publish, Tools::PublishArticle,
+         content: steps.draft
+  when "revise"
+    ai :revision do
+      system "Revise based on feedback"
+      user "Feedback: {{ steps.human_review.feedback }}"
+    end
+    # Loop back to human review
+    goto :human_review
+  when "reject"
+    emit :rejected
+  end
+end
+```
+
+#### Event Projections
+
+```ruby
+# projections/user_activity.rb
+projection "user_activity" do
+  # Subscribe to events
+  on "user_created" do |event|
+    Repo[:analytics].increment_counter(
+      metric: "users.total",
+      date: event.timestamp.to_date
+    )
+  end
+
+  on "article_published" do |event|
+    Repo[:analytics].track_activity(
+      user_id: event.author_id,
+      action: "published_article",
+      timestamp: event.timestamp
+    )
+  end
+
+  # Materialize views
+  every 5.minutes do
+    Repo[:analytics].refresh_materialized_view("user_stats")
+  end
+end
+```
+
+## Getting Started
+
+### Quick Start
+
+```bash
+# Install Hypervibe
+gem install hypervibe
+
+# Create a new project
+vibe new my_app
+cd my_app
+
+# Set up the database
+vibe db:setup
+
+# Generate your first flow
+vibe generate flow hello_world
+
+# Start the development server
+vibe server
+
+# In another terminal, run the flow
+vibe run hello_world name="World"
+```
+
+### Your First Flow
+
+```ruby
+# app/flows/hello_world.rb
+flow "hello_world" do
+  ai :greeting,
+     model: "gpt-4o-mini",
+     schema: {
+       type: "object",
+       properties: {
+         message: {type: "string"},
+         emoji: {type: "string"}
+       }
+     } do
+    system "You are a friendly greeter"
+    user "Say hello to {{ params.name }}"
+  end
+
+  emit :greeted, {
+    name: params.name,
+    message: steps.greeting["message"],
+    emoji: steps.greeting["emoji"]
+  }
+end
+```
+
+### CLI Commands
+
+```bash
+# Development
+vibe server              # Start dev server with hot reload
+vibe console            # Interactive Ruby console
+vibe test               # Run test suite
+
+# Generators
+vibe generate flow <name>
+vibe generate tool <name>
+vibe generate query <name>
+
+# Database
+vibe db:create
+vibe db:migrate
+vibe db:seed
+vibe db:reset
+
+# Production
+vibe deploy
+vibe scale <process>=<count>
+vibe logs --tail
+vibe metrics
+
+# Tools & Flows
+vibe run <flow> [params]
+vibe tool <name> [params]
+vibe replay <run_id>
+
+# Maintenance
+vibe traces:clean --before 30d
+vibe cache:clear
+vibe events:compact
+```
+
+## Philosophy
+
+Hypervibe embraces several core principles:
+
+1. **SQL is a Feature, Not a Bug**: LLMs understand SQL better than ORMs. We generate types from SQL, not the other way around.
+
+2. **Observability Over Debugging**: Every action leaves a trace. You can replay any flow execution and see exactly what happened.
+
+3. **Streams Over Requests**: AI is slow. Users need feedback. Everything streams by default.
+
+4. **Contracts Over Documentation**: JSON Schema defines everything. Tools, flows, and prompts all have contracts that are enforced at runtime.
+
+5. **Events Over State**: Event sourcing provides natural versioning, auditing, and time-travel debugging.
+
+6. **Composition Over Inheritance**: Small tools and flows compose into larger systems. No base classes or deep hierarchies.
+
+## Contributing
+
+Hypervibe is open source and welcomes contributions. See [CONTRIBUTING.md](https://github.com/hypervibe/hypervibe/blob/main/CONTRIBUTING.md) for details.
+
+## License
+
+MIT License. See [LICENSE](https://github.com/hypervibe/hypervibe/blob/main/LICENSE) for details.
+
+## Learn More
+
+- **Documentation**: [hypervibe.dev](https://hypervibe.dev)
+- **Examples**: [github.com/hypervibe/examples](https://github.com/hypervibe/examples)
+- **Discord**: [discord.gg/hypervibe](https://discord.gg/hypervibe)
+- **Twitter**: [@hypervibeframework](https://twitter.com/hypervibeframework)
+
+---
+
+Built for the age of AI-assisted development, where LLMs write the SQL and humans define the workflows.