flow_chat 0.9.0 → 0.10.0

data/README.md

@@ -3,392 +3,263 @@
 [![CI](https://github.com/radioactive-labs/flow_chat/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/radioactive-labs/flow_chat/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/flow_chat.svg)](https://badge.fury.io/rb/flow_chat)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.3.0-red.svg)](https://www.ruby-lang.org/)
-[![Rails](https://img.shields.io/badge/rails-%3E%3D%206.0-red.svg)](https://rubyonrails.org/)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0-red.svg)](https://www.ruby-lang.org/)
 
-FlowChat is a powerful Rails framework for building sophisticated conversational interfaces across **multiple platforms** with a **pluggable gateway architecture**. Create interactive flows with menus, prompts, validation, media support, and session management using a unified, intuitive API that works across USSD, WhatsApp, Telegram, HTTP, and any custom platforms you build.
+**Write a conversation as an ordinary Ruby method. FlowChat runs it across stateless webhooks, on every messaging channel.**
 
-## ✨ Key Features
-
-- **🔄 Unified API**: Single codebase that works across all platforms
-- **🔌 Pluggable Gateways**: Extensible architecture supporting multiple backends per platform
-- **📱 Multi-Platform**: Out of the box support for USSD, WhatsApp, Telegram, HTTP, and more, with simulator for testing
-- **🎯 Screen-Based Navigation**: Intuitive screen() method for building conversational flows
-- **💾 Advanced Session Management**: Flexible session boundaries and storage options
-- **🔧 Middleware Architecture**: Extensible middleware system for custom processing
-- **🎨 Rich Prompts**: Support for text, media, selections, yes/no prompts, validation, and transformations
-- **📊 Built-in Instrumentation**: Comprehensive logging and metrics collection
-- **🧪 Testing Support**: Built-in simulator for development and testing
-- **🏢 Multi-Tenancy**: In-built support for custom configuration per tenant and URL-based isolation
-- **🚀 Background Processing**: Job queue support for WhatsApp messaging
-
-## 🚀 Quick Start
-
-### Installation
-
-Add FlowChat to your Rails application:
-
-```ruby
-# Gemfile
-gem 'flow_chat'
-```
-
-```bash
-bundle install
-```
-
-### Define your flow
+A USSD or chat webhook is stateless: each message arrives as an isolated POST with no memory of the ones before it. The usual answer is a hand-rolled state machine: persist the current step, switch on it when the next message comes in, run the transition, persist the next step, repeat. FlowChat replaces that machine with a session and a replay engine, so you write the flow as a synchronous script that reads top to bottom.
 
 ```ruby
-# app/flow_chat/welcome_flow.rb
-
-class WelcomeFlow < FlowChat::Flow
+class RegistrationFlow < FlowChat::Flow
   def main_page
-    name = app.screen(:name) do |prompt|
-      prompt.ask "Welcome! What's your name?",
-        transform: ->(input) { input.strip.titleize }
-    end
+    name = app.screen(:name) { |prompt| prompt.ask "What's your name?" }
 
-    choice = app.screen(:main_menu) do |prompt|
-      prompt.select "Hi #{name}! Choose:", {
-        "1" => "Account Info",
-        "2" => "Make Payment",
-        "3" => "Support"
-      }
+    email = app.screen(:email) do |prompt|
+      prompt.ask "Your email?", validate: ->(input) { "Invalid email" unless input.include?("@") }
     end
 
-    case choice
-    when "1"
-      show_account_info
-    when "2"
-      make_payment  
-    when "3"
-      app.say "Call us: 123-456-7890"
-    end
+    app.say "Welcome #{name}!"
   end
-
-  # ... implement your flow methods
 end
 ```
 
-### Basic USSD Application
+Each `screen` returns its stored answer when one exists and re-prompts when it does not. The method runs top to bottom on every turn and blocks on the first screen that has no answer yet. The same flow runs unchanged on USSD, WhatsApp, Messenger, Instagram, Telegram, and HTTP, with per-platform rendering.
 
-```ruby
-# app/controllers/ussd_controller.rb
-class UssdController < ApplicationController
-  skip_forgery_protection
-
-  def process_request
-    processor = FlowChat::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Ussd::Gateway::Nalo
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
+## How the replay engine works
 
-    processor.run WelcomeFlow, :main_page
-  end
-end
-```
+There is no saved program counter. On each webhook FlowChat rebuilds the app from the request and re-runs your flow method from the first line.
 
-### Basic WhatsApp Application
+`app.screen(key)` is the fast-forward mechanism. When the session already holds a value for `key`, `screen` returns `session.get(key)` immediately and never yields. When it does not, `screen` yields a `FlowChat::Prompt`. If that prompt calls `ask` (or `select`, `yes?`) and no input is available yet, it raises `FlowChat::Interrupt::Prompt`. The interrupt unwinds the flow back to the Executor, which turns it into a rendered prompt and returns the response to the gateway.
 
-```ruby
-# app/controllers/whatsapp_controller.rb
-class WhatsappController < ApplicationController
-  skip_forgery_protection
+The next webhook replays the same method from the top. Every screen that already has a stored answer is skipped in place. The screen that raised last time now sees the incoming input, runs its `validate` and `transform`, stores the accepted value with `session.set(key, value)`, and returns it, so execution falls through into the next screen. The flow advances one screen per turn without ever holding state between requests beyond the session hash.
 
-  def webhook
-    processor = FlowChat::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
+Two rules follow from this design:
 
-    processor.run WelcomeFlow, :main_page
-  end
-end
-```
+- One inbound message is consumed by one screen per turn. Once a screen takes the turn's input, later screens in the same run see no input and will prompt.
+- A given screen key may be presented only once per run. Re-entering a key raises `ArgumentError`; use distinct keys or `app.go_back` to revisit.
 
-### Basic Telegram Application
+## Installation
 
-```ruby
-# app/controllers/telegram_controller.rb
-class TelegramController < ApplicationController
-  skip_forgery_protection
-
-  def webhook
-    processor = FlowChat::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Telegram::Gateway::BotApi
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
+Add the gem to your Gemfile:
 
-    processor.run WelcomeFlow, :main_page
-  end
-end
+```ruby
+gem "flow_chat"
 ```
 
-### Basic HTTP API Application
+Then run `bundle install`. FlowChat requires Ruby 3.0 or newer.
 
-```ruby
-# app/controllers/api_controller.rb
-class ApiController < ApplicationController
-  def chat
-    processor = FlowChat::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Http::Gateway::Simple
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
+The cache-backed session store needs a cache. Set it once during boot, for example in an initializer:
 
-    processor.run WelcomeFlow, :main_page
-  end
-end
+```ruby
+FlowChat::Config.cache = Rails.cache
 ```
-> Same WelcomeFlow works across ALL platforms!
 
+Without a cache configured, `FlowChat::Session::CacheSessionStore` raises when it tries to read or write a session. There are no migrations and no generators to run.
 
-## 🏗️ Architecture
+## Wiring a platform
 
-FlowChat uses a **composition-based architecture** with these core components:
+Build a processor, choose a gateway and session store, and run your flow:
 
-- **Processor**: Orchestrates request processing through middleware stack
-- **Gateway**: Platform-specific request/response handling (Nalo, WhatsApp Cloud API)
-- **App**: Unified application interface with screen-based navigation
-- **Session**: Flexible session management with configurable boundaries
-- **Middleware**: Extensible processing pipeline
+```ruby
+processor = FlowChat::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  config.use_session_store FlowChat::Session::CacheSessionStore
+end
 
-```
-┌─────────────┐    ┌──────────────┐    ┌─────────────┐
-│   Gateway   │ -> │ Session      │ -> │ Custom      │
-│             │    │ Middleware   │    │ Middleware  │
-└─────────────┘    └──────────────┘    └─────────────┘
-                                              │
-                                              v
-┌─────────────┐    ┌──────────────┐    ┌─────────────┐
-│ Flow/Action │ <- │   Executor   │ <- │     App     │
-│             │    │              │    │             │
-└─────────────┘    └──────────────┘    └─────────────┘
+processor.run RegistrationFlow, :main_page
 ```
 
-## 🔌 Pluggable Gateway Architecture
+Point your controller's webhook action at this code (`self` is the controller). Each platform has its own gateway class:
 
-FlowChat's power comes from its pluggable gateway system. Each platform can have multiple gateway implementations:
+| Platform | Gateway class | Platform symbol | Rendering |
+|---|---|---|---|
+| USSD | `FlowChat::Ussd::Gateway::Nalo` | `:ussd` | Numbered text menus, pagination, media as URL text |
+| WhatsApp | `FlowChat::Whatsapp::Gateway::CloudApi` | `:whatsapp` | Reply buttons (<=3 choices), lists (>3), rich media |
+| Messenger | `FlowChat::Messenger::Gateway::SendApi` | `:messenger` | Quick replies, carousel, numbered text |
+| Instagram | `FlowChat::Instagram::Gateway::SendApi` | `:instagram` | Quick replies, carousel, always numbered |
+| Telegram | `FlowChat::Telegram::Gateway::BotApi` | `:telegram` | Inline keyboards, rich media, HTML |
+| HTTP | `FlowChat::Http::Gateway::Simple` | `:http` | JSON responses (testing, custom clients) |
+| Intercom | `FlowChat::Intercom::Gateway::IntercomApi` | `:intercom` | Live-chat replies |
 
-```ruby
-# Create your own SMS gateway
-class MyCompany::Sms::Gateway::Twilio
-  def initialize(app, config)
-    @app = app
-    @config = config
-  end
+The same `RegistrationFlow` runs on any row by changing only `config.use_gateway`. To build a gateway for a platform not listed here, see [docs/gateway-development.md](docs/gateway-development.md).
 
-  def call(context)
-    # Parse Twilio webhook, set context values
-    context["request.msisdn"] = params["From"]
-    context["request.platform"] = :sms
-    context.input = params["Body"]
-    
-    # Process through middleware
-    type, prompt, choices, media = @app.call(context)
-    
-    # Send response via Twilio API
-    send_sms_response(prompt, to: context["request.msisdn"])
-  end
+## Building flows
 
-  # Optional: Configure platform-specific middleware
-  def self.configure_middleware_stack(builder, custom_middleware)
-    builder.use MyCompany::Sms::MessageTransformMiddleware
-    builder.use custom_middleware
-  end
-end
+A flow is a class that inherits `FlowChat::Flow` and reads and writes the conversation through `app`. Each unit of interaction is a screen:
 
-# Use your custom gateway
-processor = FlowChat::Processor.new(self) do |config|
-  config.use_gateway MyCompany::Sms::Gateway::Twilio, sms_config
-end
+```ruby
+value = app.screen(:key) { |prompt| prompt.ask "..." }
 ```
 
-## 📚 Documentation
+The block receives a `FlowChat::Prompt`. Its methods:
 
-### Getting Started
-- [**Getting Started Guide**](docs/getting-started.md) - Comprehensive setup and first app
-- [**Architecture Overview**](docs/architecture.md) - Deep dive into FlowChat's design
-- [**Configuration**](docs/configuration.md) - Complete configuration reference
+| Method | Signature | Behavior |
+|---|---|---|
+| `ask` | `ask(msg, choices: nil, transform: nil, validate: nil, media: nil)` | Prompt for free input; validate, then transform, then return the value |
+| `select` | `select(msg, choices, media: nil, error_message: "Invalid selection:")` | Prompt for one of `choices`; returns the chosen key |
+| `yes?` | `yes?(msg)` | A `select` over Yes/No; returns `true` or `false` |
+| `say` | `say(msg, media: nil)` | Send a terminal message and end the flow |
 
-### Platform Guides
-- [**USSD Development**](docs/platforms/ussd.md) - USSD-specific features and examples
-- [**WhatsApp Development**](docs/platforms/whatsapp.md) - WhatsApp Business API integration
-- [**Telegram Development**](docs/platforms/telegram.md) - Telegram Bot API integration
-- [**HTTP Development**](docs/platforms/http.md) 🚧 - API endpoints and webhooks
-- [**Multi-Platform Apps**](docs/platforms/multi-platform.md) 🚧 - Building unified experiences
+Details:
 
-### Advanced Topics
-- [**Gateway Development**](docs/gateway-development.md) - Creating custom gateways and platforms
-- [**Session Management**](docs/session-management.md) 🚧 - Session boundaries and storage
-- [**Middleware Development**](docs/middleware.md) 🚧 - Creating custom middleware
-- [**Testing & Simulation**](docs/testing.md) - Testing strategies and simulator usage
-- [**Background Jobs**](docs/background-jobs.md) 🚧 - Async processing for WhatsApp
-- [**Instrumentation**](docs/instrumentation.md) - Monitoring, logging, and error tracking
+- `validate` is a callable that returns an error string when the input is rejected and `nil` when it passes. The received argument behaves like the input text (`input.include?("@")`, `input.to_i`, `input.strip`), and also exposes `media`, `location`, and `contact` for attachment-carrying turns.
+- `transform` is a callable that maps the accepted input to the value `screen` stores and returns.
+- `choices` may be an Array (`["Yes", "No"]`) or a Hash (`{ "1" => "Account", "2" => "Support" }`). With a Hash, `select` returns the key.
+- Passing `media:` together with more than 3 `choices` raises `ArgumentError`. Use media or a longer choice list, not both.
 
-### API Reference
-- [**Core API**](docs/api-reference/core.md) 🚧 - Processor, App, Flow classes
-- [**Prompts & Validation**](docs/api-reference/prompts.md) 🚧 - Interactive prompts and validation
-- [**Gateways**](docs/api-reference/gateways.md) 🚧 - Platform gateway interfaces
-- [**Session Stores**](docs/api-reference/session-stores.md) 🚧 - Session storage options
+`app.say` outside a block ends the flow from anywhere:
+
+```ruby
+def main_page
+  confirmed = app.screen(:confirm) { |prompt| prompt.yes? "Place the order?" }
+  app.say("Cancelled.") unless confirmed
+  # ...
+end
+```
 
-## 🎯 Core Concepts
+To send the user back to the previous screen, call `app.go_back`. It clears the current screen's stored answer and restarts the flow from the top, so the earlier screen prompts again. Remember that a screen key may appear only once per run: reuse of a key in a single pass raises `ArgumentError`.
 
-### Screen-Based Navigation
+## Media and rich input
 
-Build conversational flows using the intuitive `screen()` method:
+An inbound turn is a `FlowChat::Input`. Read what the user sent through these accessors on `app`:
 
-```ruby
-def registration_flow
-  # Each screen automatically handles state and navigation
-  email = app.screen(:email) do |prompt|
-    prompt.ask "Enter your email:",
-      validate: ->(input) { 
-        "Invalid email" unless input.include?("@")
-      }
-  end
+| Accessor | Returns |
+|---|---|
+| `app.text` | The message text (`""` when the turn carries only an attachment) |
+| `app.media` | An Array of `FlowChat::Media` (empty array when none) |
+| `app.location` | The shared location payload, or `nil` |
+| `app.contact` | The shared contact card, or `nil` |
+| `app.attachment_type` | `:media`, `:location`, `:contact`, or `nil` |
 
-  name = app.screen(:name) do |prompt|
-    prompt.ask "Enter your full name:",
-      transform: ->(input) { input.strip.titleize }
-  end
+Reading an inbound photo:
 
-  # Confirmation screen with rich prompts
-  confirmed = app.screen(:confirm) do |prompt|
-    prompt.yes? "Confirm registration for #{name} (#{email})?"
+```ruby
+def main_page
+  app.screen(:photo) do |prompt|
+    prompt.ask "Send a photo of the receipt."
   end
 
-  if confirmed
-    create_user(name, email)
-    app.say "Welcome #{name}! Registration complete."
-  else
-    app.say "Registration cancelled."
+  photo = app.media.first
+  if photo
+    photo.type       # => :image  (a Symbol; normalized across platforms)
+    photo.mime_type  # => "image/jpeg"
+    photo.caption    # => the caption text, or nil
+    bytes = photo.download   # raw bytes, or nil on failure
+    link  = photo.url        # a fetchable URL, or nil
   end
 end
 ```
 
-### Multi-Platform Compatibility
+`app.media` is always an Array, so read a single item with `app.media.first` and check for `nil`; the type is a Symbol, read with `app.media.first&.type`. A caption-less photo still answers a screen: an attachment counts as submitted even when the text is blank.
 
-Write once, run everywhere:
+To send media outbound, pass `media:` to `ask` or `say`:
 
 ```ruby
-class MenuFlow < FlowChat::Flow
-  def main_menu
-    choice = app.screen(:menu) do |prompt|
-      prompt.select "Choose an option:", {
-        "info" => "📋 Information",      # Rich for WhatsApp
-        "help" => "❓ Help",             # Falls back to text for USSD  
-        "exit" => "👋 Exit"
-      }
-    end
-    
-    # Same logic works on both platforms
-    handle_choice(choice)
-  end
-end
+app.say "Here you go", media: { type: :image, url: "https://example.com/receipt.png" }
 ```
 
-### Flexible Session Management
+Caveat: a `Media` object that has been deserialized from a session store or a background job has lost its live platform client, so `url` and `download` return `nil`. If you need the bytes, call `download` eagerly in the same request that received the media, before the value round-trips through a session or job.
 
-Configure sessions for your use case:
+## Sessions
 
-```ruby
-# Durable sessions across timeouts
-processor = FlowChat::Processor.new(self) do |config|
-  config.use_durable_sessions  # Uses user identifier (usually phone number) for session ID
-end
+The default session boundaries are `[:flow, :gateway, :platform]`: a session is scoped to one flow, on one gateway, on one platform. Convenience methods adjust this:
 
-# Cross-platform sessions
-processor = FlowChat::Processor.new(self) do |config|
-  config.use_cross_platform_sessions  # Share sessions between platforms (e.g. USSD & WhatsApp)
-end
+| Method | Effect |
+|---|---|
+| `use_durable_sessions` | Key the session on a stable per-user identifier so it survives USSD session-id rotation across a conversation |
+| `use_cross_platform_sessions` | Narrow the boundary to flow only, so one session is shared across platforms (for example USSD and WhatsApp) |
+| `use_url_isolation` | Add a `:url` boundary for per-tenant or per-host isolation |
+| `use_session_config(boundaries:, identifier:, hash_identifiers:, &block)` | Set boundaries, the identifier, and identifier hashing directly for full control |
 
-# URL-based multi-tenancy
+```ruby
 processor = FlowChat::Processor.new(self) do |config|
-  config.use_url_isolation  # tenant1.app.com vs tenant2.app.com
+  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+  config.use_session_store FlowChat::Session::CacheSessionStore
+  config.use_durable_sessions
 end
 ```
 
-## 🛠️ Supported Platforms & Gateways
+See [docs/configuration.md](docs/configuration.md) for the full set of session options.
 
-| Platform | Available Gateways | Features |
-|----------|-------------------|----------|
-| **USSD** | `Nalo` ✅, Custom | Pagination, choice mapping, session management |
-| **WhatsApp** | `CloudApi` ✅, Custom | Rich media, buttons, lists, templates, background jobs |
-| **Telegram** | `BotApi` ✅, Custom | Inline keyboards, rich media, callbacks, group chats |
-| **HTTP** | `Simple` ✅, Custom | Testing, webhooks, API endpoints, JSON responses |
-| **Simulator** | Built-in ✅ | Development testing, conversation replay, flow debugging |
-| **Custom** | *Your Gateway* | Implement any platform by creating a gateway class |
+## Platform differences
 
-*✅ = Included with FlowChat*
+The flow code is the same everywhere, but each platform imposes limits that the rendering respects and that you should keep in mind:
 
-### Gateway Examples
+| Platform | Limits and behavior |
+|---|---|
+| USSD | Pages are split at 140 characters by default; media is rendered as a text line containing a URL, not an inline attachment; async processing is not available. |
+| WhatsApp | Reply-button titles are truncated near 20 characters and list titles near 24; a list section holds at most 10 rows. WhatsApp's 24-hour customer-service window and its template requirement are not abstracted away: you manage message templates yourself. |
+| Messenger | Up to 13 choices render as quick replies, up to 30 as a carousel (10 elements, 3 buttons each), and above that as numbered text. Neither platform abstracts the 24-hour messaging window; a send outside it is attempted and Meta's rejection surfaces as an API error. |
+| Instagram | Same quick-reply and carousel caps as Messenger (13, then 30), but both surfaces render on the mobile app only, not desktop or web, so Instagram always lists the options as numbered text as well. Text is capped at 1000 bytes UTF-8, not characters. |
+| Telegram | Choice taps arrive as callback queries; choices render as inline keyboards; message text supports HTML formatting. |
+| HTTP | Requests and responses are JSON; each request must supply `session_id` and `user_id`. |
 
-```ruby
-# Built-in gateways (included with FlowChat)
-config.use_gateway FlowChat::Ussd::Gateway::Nalo
-config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, whatsapp_config
-config.use_gateway FlowChat::Telegram::Gateway::BotApi, telegram_config
-config.use_gateway FlowChat::Http::Gateway::Simple
-
-# Custom gateway examples (you would build these)
-config.use_gateway MyCompany::Sms::Gateway::Twilio, twilio_config
-config.use_gateway MyCompany::Slack::Gateway::BoltJS, slack_config
-```
-
-## 📦 Example Applications
+Platform guides: [docs/platforms/ussd.md](docs/platforms/ussd.md), [docs/platforms/whatsapp.md](docs/platforms/whatsapp.md), [docs/platforms/messenger.md](docs/platforms/messenger.md), [docs/platforms/instagram.md](docs/platforms/instagram.md), [docs/platforms/telegram.md](docs/platforms/telegram.md).
 
-- [**USSD Banking App**](docs/examples/ussd-banking.md) 🚧 - Complete banking flow with validation
-- [**WhatsApp Customer Service**](docs/examples/whatsapp-support.md) 🚧 - Media support and templates  
-- [**HTTP API Chatbot**](docs/examples/http-api.md) 🚧 - JSON API for web/mobile integration
-- [**Multi-Platform E-commerce**](docs/examples/multi-platform-shop.md) 🚧 - Unified shopping across USSD, WhatsApp, and HTTP
-- [**Multi-Tenant SaaS**](docs/examples/multi-tenant.md) 🚧 - URL-based tenant isolation
-- [**Custom Gateway Example**](docs/examples/custom-gateway.md) 🚧 - Building a Telegram gateway
+## Background processing
 
-## 🧪 Testing & Development
-
-FlowChat includes a built-in simulator interface for easy development and testing:
+For platforms with an outbound API, you can acknowledge the webhook immediately and run the flow in a background job. Register a factory once, then call it from the webhook:
 
 ```ruby
-# Simulator is automatically enabled in development
-processor = FlowChat::Processor.new(self) do |config|
-  config.use_gateway FlowChat::Ussd::Gateway::Nalo  # or any gateway
+# config/initializers/flow_chat.rb
+FlowChat::Factory.register(:whatsapp) do |controller|
+  processor = FlowChat::Processor.new(controller) do |config|
+    config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+    config.use_session_store FlowChat::Session::CacheSessionStore
+    config.use_async(factory: :whatsapp)
+  end
+  processor.run RegistrationFlow, :main_page
 end
 
-# Explicitly control simulator mode if needed
-processor = FlowChat::Processor.new(self, enable_simulator: false) do |config|
-  # Disable simulator even in development
+# app/controllers/whatsapp_controller.rb
+def webhook
+  FlowChat::Factory.execute(:whatsapp, controller: self)
 end
 ```
 
-The simulator provides a web interface for testing your flows during development. It works the same regardless of which gateway you're using, allowing you to test your conversational logic before deploying to actual platforms.
+The webhook enqueues `GenericAsyncJob` and returns; the job re-runs the same factory in the background, where the gateway detects the background context and processes the flow inline before sending the reply through the platform API. USSD does not support async, since it depends on a synchronous request-response cycle. See [docs/factory-pattern.md](docs/factory-pattern.md) and [docs/async-background-processing.md](docs/async-background-processing.md).
 
-**Learn more**: [Testing & Simulation Guide](docs/testing.md)
+## Instrumentation
 
-## 🤝 Contributing
+FlowChat emits `ActiveSupport::Notifications` events for flow execution, session lifecycle, and gateway activity. `FlowChat.metrics` collects counters over those events. See [docs/instrumentation.md](docs/instrumentation.md).
 
-We welcome contributions!
+## Testing
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+FlowChat ships a web simulator for driving flows locally without a real gateway, useful during development. It requires `FlowChat::Config.simulator_secret` to be set. See [docs/testing.md](docs/testing.md).
 
-## 📄 License
+## Documentation
 
-FlowChat is released under the [MIT License](LICENSE.txt).
+Guides:
+
+- [Getting started](docs/getting-started.md)
+- [Configuration](docs/configuration.md)
+- [Testing](docs/testing.md)
+
+Platforms:
 
-## 🆘 Support
+- [USSD](docs/platforms/ussd.md)
+- [WhatsApp](docs/platforms/whatsapp.md)
+- [Messenger](docs/platforms/messenger.md)
+- [Instagram](docs/platforms/instagram.md)
+- [Telegram](docs/platforms/telegram.md)
 
-- **Documentation**: Comprehensive guides in the [docs/](docs/) directory
-- **Issues**: [GitHub Issues](https://github.com/radioactive-labs/flow_chat/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/radioactive-labs/flow_chat/discussions)
+Internals and advanced:
 
-## 🏢 Commercial Support
+- [Architecture](docs/architecture.md)
+- [Building a gateway](docs/gateway-development.md)
+- [Gateway context variables](docs/gateway-context-variables.md)
+- [Async and background processing](docs/async-background-processing.md)
+- [Factory pattern](docs/factory-pattern.md)
+- [Instrumentation](docs/instrumentation.md)
 
-FlowChat is developed by [Radioactive Labs](https://github.com/radioactive-labs). Commercial support, custom development, and consulting services are available.
+## Development
 
----
+Run the test suite with `rake test`. To run a single file, use `ruby -Itest test/unit/some_test.rb`.
 
-**Ready to build amazing conversational experiences?** Check out the [Getting Started Guide](docs/getting-started.md) to create your first FlowChat application.
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/radioactive-labs/flow_chat). Please add tests for behavior changes and keep them passing.
+
+## License
+
+FlowChat is released under the [MIT License](LICENSE.txt).

data/Rakefile

@@ -8,7 +8,18 @@ Dir.glob("lib/tasks/**/*.rake").each { |r| load r }
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  # test/performance holds benchmarks, which assert against wall-clock timings and
+  # so fail on a loaded machine for reasons that have nothing to do with the code
+  # under test. A suite that cries wolf is a suite people stop reading, so they
+  # run under `rake benchmark` instead of here.
+  t.test_files = FileList["test/**/*_test.rb"].exclude("test/performance/**/*_test.rb")
+end
+
+desc "Run the performance benchmarks (timing-sensitive, not part of rake test)"
+Rake::TestTask.new(:benchmark) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/performance/**/*_test.rb"]
 end
 
 task default: %i[test standard]

data/SECURITY.md

@@ -13,7 +13,7 @@ please upgrade before reporting an issue to confirm it still reproduces.
 
 | Version | Supported          |
 | ------- | ------------------ |
-| Latest release (`0.9.x`) | :white_check_mark: |
+| Latest release (`0.10.x`) | :white_check_mark: |
 | Older releases | :x: |
 
 ## Reporting a Vulnerability