Merge pull request #6 from socialdept/dev

Rewrite documentation with guides and contribution guidelines

CONTRIBUTING.md

···
+# Contributing
+
+Contributions are **welcome** and will be fully **credited**.
+
+## Etiquette
+
+This project is open source, and as such, the maintainers give their free time to build and maintain the source code held within. They make the code freely available in the hope that it will be of use to other developers. It would be extremely unfair for them to suffer abuse or anger for their hard work.
+
+Please be considerate towards maintainers when raising issues or presenting pull requests. Let's show the world that developers are civilized and selfless people.
+
+It's the duty of the maintainer to ensure that all submissions to the project are of sufficient quality to benefit the project. Many developers have different skillsets, strengths, and weaknesses. Respect the maintainer's decision, and do not be upset or abusive if your submission is not used.
+
+## Viability
+
+When requesting or submitting new features, first consider whether it might be useful to others. Open source projects are used by many developers, who may have entirely different needs to your own. Think about whether or not your feature is likely to be used by other users of the project.
+
+## Procedure
+
+### Before Filing an Issue
+
+- Search existing issues to avoid duplicates
+- Check the [documentation](docs/) to ensure it's not a usage question
+- Provide a clear title and description
+- Include steps to reproduce the issue
+- Specify your environment (PHP version, Laravel version, Signal version, mode)
+- Include relevant code samples and full error messages
+
+### Before Submitting a Pull Request
+
+- **Discuss non-trivial changes first** by opening an issue
+- **Fork the repository** and create a feature branch from `main`
+- **Follow all requirements** listed below
+- **Write tests** for your changes
+- **Update documentation** if behavior changes
+- **Run code style checks** with `vendor/bin/php-cs-fixer fix`
+- **Ensure all tests pass** with `vendor/bin/phpunit`
+- **Write clear commit messages** that explain what and why
+
+## Requirements
+
+- **[PSR-12 Coding Standard](https://www.php-fig.org/psr/psr-12/)** - Run `vendor/bin/php-cs-fixer fix` to automatically fix code style issues.
+
+- **Add tests** - Your patch won't be accepted if it doesn't have tests. All tests must use [PHPUnit](https://phpunit.de/).
+
+- **Document any change in behaviour** - Make sure the `README.md`, `docs/`, and any other relevant documentation are kept up-to-date.
+
+- **Consider our release cycle** - We follow [SemVer v2.0.0](https://semver.org/). Randomly breaking public APIs is not an option.
+
+- **One pull request per feature** - If you want to do more than one thing, send multiple pull requests.
+
+- **Send coherent history** - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please [squash them](https://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages) before submitting.
+
+## Running Tests
+
+```bash
+vendor/bin/phpunit
+```
+
+## Code Style
+
+Signal follows PSR-12 coding standard. Run PHP CS Fixer before submitting:
+
+```bash
+vendor/bin/php-cs-fixer fix
+```
+
+**Happy coding**!

README.md

···
-# Signal
+[![Signal Header](./header.png)](https://github.com/socialdept/signal)
 
-**Laravel package for building Signals that respond to AT Protocol events**
+<h3 align="center">
+    Consume real-time AT Protocol events in your Laravel application.
+</h3>
 
-Signal provides a clean, Laravel-style interface for consuming real-time events from the AT Protocol. Supports both **Jetstream** (simplified JSON events) and **Firehose** (raw CBOR/CAR format) for maximum flexibility. Build reactive applications, AppViews, and custom indexers that respond to posts, likes, follows, and other social interactions on the AT Protocol network.
+<p align="center">
+    <br>
+    <a href="https://packagist.org/packages/socialdept/signal" title="Latest Version on Packagist"><img src="https://img.shields.io/packagist/v/socialdept/signal.svg?style=flat-square"></a>
+    <a href="https://packagist.org/packages/socialdept/signal" title="Total Downloads"><img src="https://img.shields.io/packagist/dt/socialdept/signal.svg?style=flat-square"></a>
+    <a href="https://github.com/socialdept/signal/actions/workflows/tests.yml" title="GitHub Tests Action Status"><img src="https://img.shields.io/github/actions/workflow/status/socialdept/signal/tests.yml?branch=main&label=tests&style=flat-square"></a>
+    <a href="LICENSE" title="Software License"><img src="https://img.shields.io/github/license/socialdept/signal?style=flat-square"></a>
+</p>
 
 ---
 
-## Features
+## What is Signal?
 
-- 🔄 **Dual-Mode Support** - Choose between Jetstream (JSON) or Firehose (CBOR/CAR) based on your needs
-- 🔌 **WebSocket Connection** - Connect to AT Protocol with automatic reconnection and exponential backoff
-- 🎯 **Signal-based Architecture** - Clean, testable event handlers (avoiding Laravel's "listener" naming collision)
-- ⭐ **Wildcard Collection Filtering** - Match multiple collections with patterns like `app.bsky.feed.*`
-- 🏗️ **AppView Ready** - Full support for custom collections and building AT Protocol AppViews
-- 💾 **Cursor Management** - Resume from last position after disconnections (Database, Redis, or File storage)
-- ⚡ **Queue Integration** - Process events asynchronously with Laravel queues
-- 🔍 **Auto-Discovery** - Automatically find and register Signals in `app/Signals`
-- 🧪 **Testing Tools** - Test your Signals with sample data
-- 🛠️ **Artisan Commands** - Full CLI support for managing and testing Signals
+**Signal** is a Laravel package that lets you respond to real-time events from the AT Protocol network. Build reactive applications, custom feeds, moderation tools, analytics systems, and AppViews by listening to posts, likes, follows, and other social interactions as they happen across Bluesky and the entire AT Protocol ecosystem.
 
----
+Think of it as Laravel's event listeners, but for the decentralized social web.
 
-## Table of Contents
+## Why use Signal?
 
-<!-- TOC -->
-* [Installation](#installation)
-* [Quick Start](#quick-start)
-* [Jetstream vs Firehose](#jetstream-vs-firehose)
-* [Creating Signals](#creating-signals)
-* [Filtering Events](#filtering-events)
-* [Queue Integration](#queue-integration)
-* [Configuration](#configuration-1)
-* [Programmatic Usage](#programmatic-usage)
-* [Available Commands](#available-commands)
-* [Testing](#testing)
-* [External Resources](#external-resources)
-* [Examples](#examples)
-* [Requirements](#requirements)
-* [License](#license)
-* [Support](#support)
-<!-- TOC -->
-
----
-
-## Installation
-
-Install the package via Composer:
+- **Laravel-style code** - Familiar patterns you already know
+- **Real-time processing** - React to events as they happen
+- **Dual-mode support** - Choose Jetstream (efficient JSON) or Firehose (comprehensive CBOR)
+- **AppView ready** - Full support for custom collections and protocols
+- **Production features** - Queue integration, cursor management, auto-reconnection
+- **Easy filtering** - Target specific collections, operations, and users with wildcards
+- **Built-in testing** - Test your signals with sample data
 
-```bash
-composer require socialdept/signal
-```
-
-Run the installation command:
-
-```bash
-php artisan signal:install
-```
-
-This will:
-- Publish the configuration file to `config/signal.php`
-- Publish the database migration
-- Run migrations (with confirmation)
-- Display next steps
-
-### Manual Installation
-
-If you prefer manual installation:
-
-```bash
-php artisan vendor:publish --tag=signal-config
-php artisan vendor:publish --tag=signal-migrations
-php artisan migrate
-```
-
----
-
-## Quick Start
-
-### 1. Create Your First Signal
-
-```bash
-php artisan make:signal NewPostSignal
-```
-
-This creates `app/Signals/NewPostSignal.php`:
+## Quick Example
 
 ```php
-<?php
-
-namespace App\Signals;
-
 use SocialDept\Signal\Events\SignalEvent;
 use SocialDept\Signal\Signals\Signal;
 
···
 }
 ```
 
-### 2. Start Consuming Events
+Run `php artisan signal:consume` and start responding to every post on Bluesky in real-time.
 
-```bash
-php artisan signal:consume
-```
-
-Your Signal will now respond to new posts on the AT Protocol network in real-time!
-
----
-
-## Jetstream vs Firehose
-
-Signal supports two modes for consuming AT Protocol events. Choose based on your use case:
-
-### Jetstream Mode (Default)
-
-**Best for**: Standard Bluesky collections, production efficiency, lower bandwidth
+## Installation
 
 ```bash
-php artisan signal:consume --mode=jetstream
+composer require socialdept/signal
+php artisan signal:install
 ```
 
-**Characteristics:**
-- ✅ Simplified JSON events (easy to work with)
-- ✅ Server-side collection filtering (efficient)
-- ✅ Lower bandwidth and processing overhead
-- ⚠️ Only standard `app.bsky.*` collections get create/update operations
-- ⚠️ Custom collections only receive delete operations
+That's it. [Read the installation docs →](docs/installation.md)
 
-**Jetstream URL options:**
-- US East: `wss://jetstream2.us-east.bsky.network` (default)
-- US West: `wss://jetstream1.us-west.bsky.network`
+## Getting Started
 
-### Firehose Mode
+Once installed, you're three steps away from consuming AT Protocol events:
 
-**Best for**: Custom collections, AppViews, comprehensive indexing
+### 1. Create a Signal
 
 ```bash
-php artisan signal:consume --mode=firehose
-```
-
-**Characteristics:**
-- ✅ **All operations** (create, update, delete) for **all collections**
-- ✅ Perfect for custom collections (e.g., `app.yourapp.*.collection`)
-- ✅ Full CBOR/CAR decoding with package `revolution/laravel-bluesky`
-- ⚠️ Client-side filtering only (higher bandwidth)
-- ⚠️ More processing overhead
-
-**When to use Firehose:**
-- Building an AT Protocol AppView
-- Working with custom collections
-- Need create/update events for non-standard collections
-- Building comprehensive indexes
-
-### Configuration
-
-Set your preferred mode in `.env`:
-
-```env
-# Use Jetstream (default)
-SIGNAL_MODE=jetstream
-
-# Or use Firehose for custom collections
-SIGNAL_MODE=firehose
+php artisan make:signal NewPostSignal
 ```
 
-### Example: Custom Collections
-
-If you're tracking custom collections like `app.offprint.beta.publication`, you **must** use Firehose mode:
+### 2. Define What to Listen For
 
 ```php
-class PublicationSignal extends Signal
+public function collections(): ?array
 {
-    public function collections(): ?array
-    {
-        return ['app.offprint.beta.publication'];
-    }
-
-    public function handle(SignalEvent $event): void
-    {
-        // With Jetstream: Only sees deletes ❌
-        // With Firehose: Sees creates, updates, deletes ✅
-    }
+    return ['app.bsky.feed.post'];
 }
 ```
 
----
+### 3. Start Consuming
 
-## Creating Signals
+```bash
+php artisan signal:consume
+```
 
-### Basic Signal Structure
+Your Signal will now handle every matching event from the network. [Read the quickstart guide →](docs/quickstart.md)
 
-Every Signal extends the base `Signal` class and must implement:
+## What can you build?
 
-```php
-use SocialDept\Signal\Enums\SignalEventType;
-use SocialDept\Signal\Events\SignalEvent;
-use SocialDept\Signal\Signals\Signal;
+- **Custom feeds** - Curate content based on your own algorithms
+- **Moderation tools** - Detect and flag problematic content automatically
+- **Analytics platforms** - Track engagement, trends, and network growth
+- **Social integrations** - Mirror content to other platforms in real-time
+- **Notification systems** - Alert users about relevant activity
+- **AppViews** - Build custom AT Protocol applications with your own collections
 
-class MySignal extends Signal
-{
-    // Required: Define which event types to listen for
-    public function eventTypes(): array
-    {
-        return [SignalEventType::Commit];
+## Documentation
 
-        // Or use strings:
-        // return ['commit'];
-    }
+**Getting Started**
+- [Installation](docs/installation.md) - Detailed setup instructions
+- [Quickstart Guide](docs/quickstart.md) - Build your first Signal
+- [Jetstream vs Firehose](docs/modes.md) - Choose the right mode
 
-    // Required: Handle the event
-    public function handle(SignalEvent $event): void
-    {
-        // Your logic here
-    }
-}
-```
+**Building Signals**
+- [Creating Signals](docs/signals.md) - Complete Signal reference
+- [Filtering Events](docs/filtering.md) - Target specific collections and operations
+- [Queue Integration](docs/queues.md) - Process events asynchronously
 
-**Enums vs Strings**: Signal supports both typed enums and strings for better IDE support and type safety. Use whichever you prefer!
+**Advanced**
+- [Configuration](docs/configuration.md) - All config options explained
+- [Testing](docs/testing.md) - Test your Signals
+- [Examples](docs/examples.md) - Real-world use cases
 
-### Event Types
-
-Three event types are available:
+## Example Use Cases
 
-| Enum                        | String       | Description                                      | Use Cases                             |
-|-----------------------------|--------------|--------------------------------------------------|---------------------------------------|
-| `SignalEventType::Commit`   | `'commit'`   | Repository commits (posts, likes, follows, etc.) | Content creation, social interactions |
-| `SignalEventType::Identity` | `'identity'` | Identity changes (handle updates)                | User profile tracking                 |
-| `SignalEventType::Account`  | `'account'`  | Account status changes                           | Account monitoring                    |
-
-### Accessing Event Data
-
+### Track User Growth
 ```php
-use SocialDept\Signal\Enums\SignalCommitOperation;
-
-public function handle(SignalEvent $event): void
+public function collections(): ?array
 {
-    // Common properties
-    $did = $event->did;           // User's DID
-    $kind = $event->kind;         // Event type
-    $timestamp = $event->timeUs;  // Microsecond timestamp
-
-    // Commit events
-    if ($event->isCommit()) {
-        $collection = $event->getCollection();  // e.g., 'app.bsky.feed.post'
-        $operation = $event->getOperation();    // SignalCommitOperation enum
-        $record = $event->getRecord();          // The actual record data
-        $rkey = $event->commit->rkey;           // Record key
-
-        // Use enum for type-safe comparisons
-        if ($operation === SignalCommitOperation::Create) {
-            // Handle new records
-        }
-
-        // Or get string value
-        $operationString = $operation->value; // 'create', 'update', or 'delete'
-    }
-
-    // Identity events
-    if ($event->isIdentity()) {
-        $handle = $event->identity->handle;
-    }
-
-    // Account events
-    if ($event->isAccount()) {
-        $active = $event->account->active;
-        $status = $event->account->status;
-    }
+    return ['app.bsky.graph.follow'];
 }
 ```
 
----
-
-## Filtering Events
-
-### Collection Filtering (with Wildcards!)
-
-Filter events by AT Protocol collection.
-
-**Important**:
-- **Jetstream mode**: Exact collection names are sent as URL parameters for server-side filtering. Wildcards work for client-side filtering only.
-- **Firehose mode**: All filtering is client-side. Wildcards work normally.
-
+### Monitor Content Moderation
 ```php
-// Exact match - only posts
-public function collections(): ?array
-{
-    return ['app.bsky.feed.post'];
-}
-
-// Wildcard - all feed events
 public function collections(): ?array
 {
     return ['app.bsky.feed.*'];
 }
 
-// Multiple patterns
-public function collections(): ?array
-{
-    return [
-        'app.bsky.feed.post',
-        'app.bsky.feed.repost',
-        'app.bsky.graph.*',  // All graph collections
-    ];
-}
-
-// No filter - all collections
-public function collections(): ?array
+public function shouldQueue(): bool
 {
-    return null;
+    return true; // Process in background
 }
 ```
 
-### Common Collection Patterns
-
-| Pattern            | Matches                     |
-|--------------------|-----------------------------|
-| `app.bsky.feed.*`  | Posts, likes, reposts, etc. |
-| `app.bsky.graph.*` | Follows, blocks, mutes      |
-| `app.bsky.actor.*` | Profile updates             |
-| `app.bsky.*`       | All Bluesky collections     |
-
-### Operation Filtering
-
-Filter events by operation type (only applies to `commit` events):
-
+### Build Custom Collections (AppView)
 ```php
-use SocialDept\Signal\Enums\SignalCommitOperation;
-
-// Only handle creates (using enum)
-public function operations(): ?array
+public function collections(): ?array
 {
-    return [SignalCommitOperation::Create];
-}
-
-// Only handle creates and updates (using enums)
-public function operations(): ?array
-{
-    return [
-        SignalCommitOperation::Create,
-        SignalCommitOperation::Update,
-    ];
-}
-
-// Only handle deletes (using string)
-public function operations(): ?array
-{
-    return ['delete'];
-}
-
-// No filter - all operations (default)
-public function operations(): ?array
-{
-    return null;
+    return ['app.yourapp.custom.collection'];
 }
 ```
 
-**Available operations:**
-
-| Enum                            | String     | Description               |
-|---------------------------------|------------|---------------------------|
-| `SignalCommitOperation::Create` | `'create'` | New records created       |
-| `SignalCommitOperation::Update` | `'update'` | Existing records modified |
-| `SignalCommitOperation::Delete` | `'delete'` | Records removed           |
-
-**Example use cases:**
-```php
-use SocialDept\Signal\Enums\SignalCommitOperation;
-
-// Signal that only handles new posts (not edits)
-class NewPostSignal extends Signal
-{
-    public function collections(): ?array
-    {
-        return ['app.bsky.feed.post'];
-    }
+[See more examples →](docs/examples.md)
 
-    public function operations(): ?array
-    {
-        return [SignalCommitOperation::Create];
-    }
-}
+## Key Features Explained
 
-// Signal that only handles content updates
-class ContentUpdateSignal extends Signal
-{
-    public function collections(): ?array
-    {
-        return ['app.bsky.feed.post'];
-    }
+### Jetstream vs Firehose
 
-    public function operations(): ?array
-    {
-        return [SignalCommitOperation::Update];
-    }
-}
+Signal supports two modes for consuming AT Protocol events:
 
-// Signal that handles deletions for cleanup
-class CleanupSignal extends Signal
-{
-    public function collections(): ?array
-    {
-        return ['app.bsky.feed.*'];
-    }
+- **Jetstream** (default) - Simplified JSON events with server-side filtering
+- **Firehose** - Raw CBOR/CAR format with client-side filtering
 
-    public function operations(): ?array
-    {
-        return [SignalCommitOperation::Delete];
-    }
-}
-```
+[Learn more about modes →](docs/modes.md)
 
-### DID Filtering
+### Wildcard Filtering
 
-Filter events by specific users:
+Match multiple collections with patterns:
 
 ```php
-public function dids(): ?array
+public function collections(): ?array
 {
     return [
-        'did:plc:z72i7hdynmk6r22z27h6tvur',  // Specific user
-        'did:plc:ragtjsm2j2vknwkz3zp4oxrd',  // Another user
+        'app.bsky.feed.*',      // All feed events
+        'app.bsky.graph.*',     // All graph events
+        'app.yourapp.*',        // All your custom collections
     ];
 }
 ```
 
-### Custom Filtering
+[Learn more about filtering →](docs/filtering.md)
 
-Add complex filtering logic:
+### Queue Integration
 
-```php
-public function shouldHandle(SignalEvent $event): bool
-{
-    // Only handle posts with images
-    if ($event->isCommit() && $event->commit->collection === 'app.bsky.feed.post') {
-        $record = $event->getRecord();
-        return isset($record->embed);
-    }
-
-    return true;
-}
-```
-
----
-
-## Queue Integration
-
-Process events asynchronously using Laravel queues:
+Process events asynchronously for better performance:
 
 ```php
-class HeavyProcessingSignal extends Signal
+public function shouldQueue(): bool
 {
-    public function eventTypes(): array
-    {
-        return ['commit'];
-    }
-
-    // Enable queueing
-    public function shouldQueue(): bool
-    {
-        return true;
-    }
-
-    // Optional: Customize queue
-    public function queue(): string
-    {
-        return 'high-priority';
-    }
-
-    // Optional: Customize connection
-    public function queueConnection(): string
-    {
-        return 'redis';
-    }
-
-    public function handle(SignalEvent $event): void
-    {
-        // This runs in a queue job
-        $this->performExpensiveOperation($event);
-    }
-
-    // Handle failures
-    public function failed(SignalEvent $event, \Throwable $exception): void
-    {
-        Log::error('Signal failed', [
-            'event' => $event->toArray(),
-            'error' => $exception->getMessage(),
-        ]);
-    }
-}
-```
-
----
-
-## Configuration
-
-Configuration is stored in `config/signal.php`:
-
-### Consumer Mode
-
-Choose between Jetstream (JSON) or Firehose (CBOR) mode:
-
-```php
-'mode' => env('SIGNAL_MODE', 'jetstream'),
-```
-
-Options:
-- `jetstream` - JSON events, server-side filtering (default)
-- `firehose` - CBOR events, client-side filtering (required for custom collections)
-
-### Jetstream Configuration
-
-```php
-'websocket_url' => env('SIGNAL_JETSTREAM_URL', 'wss://jetstream2.us-east.bsky.network'),
-```
-
-Available endpoints:
-- **US East**: `wss://jetstream2.us-east.bsky.network` (default)
-- **US West**: `wss://jetstream1.us-west.bsky.network`
-
-### Firehose Configuration
-
-```php
-'firehose' => [
-    'host' => env('SIGNAL_FIREHOSE_HOST', 'bsky.network'),
-],
-```
-
-The raw firehose endpoint is: `wss://{host}/xrpc/com.atproto.sync.subscribeRepos`
-
-### Cursor Storage
-
-Choose how to store cursor positions:
-
-```php
-'cursor_storage' => env('SIGNAL_CURSOR_STORAGE', 'database'),
-```
-
-| Driver     | Best For                      | Configuration      |
-|------------|-------------------------------|--------------------|
-| `database` | Production, multi-server      | Default connection |
-| `redis`    | High performance, distributed | Redis connection   |
-| `file`     | Development, single server    | Storage path       |
-
-### Environment Variables
-
-Add to your `.env`:
-
-```env
-# Consumer Mode
-SIGNAL_MODE=jetstream  # or 'firehose' for custom collections
-
-# Jetstream Configuration
-SIGNAL_JETSTREAM_URL=wss://jetstream2.us-east.bsky.network
-
-# Firehose Configuration (only needed if using firehose mode)
-SIGNAL_FIREHOSE_HOST=bsky.network
-
-# Optional Configuration
-SIGNAL_CURSOR_STORAGE=database
-SIGNAL_QUEUE_CONNECTION=redis
-SIGNAL_QUEUE=signal
-SIGNAL_BATCH_SIZE=100
-SIGNAL_RATE_LIMIT=1000
-```
-
-### Auto-Discovery
-
-Signals are automatically discovered from `app/Signals`. Disable if needed:
-
-```php
-'auto_discovery' => [
-    'enabled' => true,
-    'path' => app_path('Signals'),
-    'namespace' => 'App\\Signals',
-],
-```
-
-Or manually register Signals:
-
-```php
-'signals' => [
-    \App\Signals\NewPostSignal::class,
-    \App\Signals\NewFollowSignal::class,
-],
-```
-
----
-
-## Programmatic Usage
-
-You can start and stop the consumer programmatically using the `Signal` facade:
-
-```php
-use SocialDept\Signal\Facades\Signal;
-
-// Start consuming events (uses mode from config)
-Signal::start();
-
-// Start from a specific cursor
-Signal::start(cursor: 123456789);
-
-// Check which mode is active
-$mode = Signal::getMode(); // Returns 'jetstream' or 'firehose'
-
-// Stop consuming events
-Signal::stop();
-```
-
-The facade automatically resolves the correct consumer (Jetstream or Firehose) based on your `config('signal.mode')` setting. This allows you to:
-
-- Switch between modes by changing configuration
-- Start consumers from application code (e.g., in a custom command)
-- Integrate Signal into existing application workflows
-
-```php
-// Example: Start consumer based on environment
-if (app()->environment('production')) {
-    config(['signal.mode' => 'jetstream']); // Use efficient Jetstream
-} else {
-    config(['signal.mode' => 'firehose']); // Use comprehensive Firehose for testing
+    return true;
 }
-
-Signal::start();
 ```
 
----
+[Learn more about queues →](docs/queues.md)
 
 ## Available Commands
-
-### `signal:install`
-Install the package (publish config, migrations, run migrations)
 
 ```bash
+# Install Signal
 php artisan signal:install
-```
-
-### `signal:consume`
-Start consuming events from AT Protocol
-
-```bash
-# Use default mode from config
-php artisan signal:consume
 
-# Override mode
-php artisan signal:consume --mode=jetstream
-php artisan signal:consume --mode=firehose
-
-# Start from specific cursor
-php artisan signal:consume --cursor=123456789
-
-# Start fresh (ignore stored cursor)
-php artisan signal:consume --fresh
+# Create a new Signal
+php artisan make:signal YourSignal
 
-# Combine options
-php artisan signal:consume --mode=firehose --fresh
-```
-
-### `signal:list`
-List all registered Signals
-
-```bash
+# List all registered Signals
 php artisan signal:list
-```
-
-### `signal:make`
-Create a new Signal class
-
-```bash
-php artisan make:signal NewPostSignal
 
-# With options
-php artisan make:signal FollowSignal --type=commit --collection=app.bsky.graph.follow
-```
-
-### `signal:test`
-Test a Signal with sample data
-
-```bash
-php artisan signal:test NewPostSignal
-```
-
----
-
-## Testing
-
-Signal includes a comprehensive test suite. Test your Signals:
-
-### Unit Testing
-
-```php
-use SocialDept\Signal\Events\CommitEvent;
-use SocialDept\Signal\Events\SignalEvent;
-
-class NewPostSignalTest extends TestCase
-{
-    /** @test */
-    public function it_handles_new_posts()
-    {
-        $signal = new NewPostSignal();
+# Start consuming events
+php artisan signal:consume
 
-        $event = new SignalEvent(
-            did: 'did:plc:test',
-            timeUs: time() * 1000000,
-            kind: 'commit',
-            commit: new CommitEvent(
-                rev: 'test',
-                operation: 'create',
-                collection: 'app.bsky.feed.post',
-                rkey: 'test',
-                record: (object) [
-                    'text' => 'Hello World!',
-                    'createdAt' => now()->toIso8601String(),
-                ],
-            ),
-        );
-
-        $signal->handle($event);
-
-        // Assert your expected behavior
-    }
-}
+# Test a Signal with sample data
+php artisan signal:test YourSignal
 ```
 
-### Testing with Artisan
+## Requirements
 
-```bash
-php artisan signal:test NewPostSignal
-```
+- PHP 8.2+
+- Laravel 11+
+- WebSocket support (enabled by default)
 
----
-
-## External Resources
+## Resources
 
 - [AT Protocol Documentation](https://atproto.com/)
+- [Bluesky API Docs](https://docs.bsky.app/)
 - [Firehose Documentation](https://docs.bsky.app/docs/advanced-guides/firehose)
-- [Bluesky Lexicon](https://atproto.com/lexicons)
-
----
-
-## Examples
-
-### Monitor All Feed Activity
-
-```php
-class FeedMonitorSignal extends Signal
-{
-    public function eventTypes(): array
-    {
-        return ['commit'];
-    }
-
-    public function collections(): ?array
-    {
-        return ['app.bsky.feed.*'];
-    }
-
-    public function handle(SignalEvent $event): void
-    {
-        // Handles posts, likes, reposts, etc.
-        Log::info('Feed activity', [
-            'collection' => $event->getCollection(),
-            'operation' => $event->getOperation(),
-            'did' => $event->did,
-        ]);
-    }
-}
-```
-
-### Track New Follows
-
-```php
-class NewFollowSignal extends Signal
-{
-    public function eventTypes(): array
-    {
-        return ['commit'];
-    }
-
-    public function collections(): ?array
-    {
-        return ['app.bsky.graph.follow'];
-    }
-
-    public function handle(SignalEvent $event): void
-    {
-        if ($event->commit->isCreate()) {
-            $record = $event->getRecord();
-
-            // Store follow relationship
-            Follow::create([
-                'follower_did' => $event->did,
-                'following_did' => $record->subject,
-            ]);
-        }
-    }
-}
-```
-
-### Content Moderation
-
-```php
-class ModerationSignal extends Signal
-{
-    public function eventTypes(): array
-    {
-        return ['commit'];
-    }
+- [Jetstream Documentation](https://github.com/bluesky-social/jetstream)
 
-    public function collections(): ?array
-    {
-        return ['app.bsky.feed.post'];
-    }
+## Support & Contributing
 
-    public function shouldQueue(): bool
-    {
-        return true;
-    }
+Found a bug or have a feature request? [Open an issue](https://github.com/socialdept/signal/issues).
 
-    public function handle(SignalEvent $event): void
-    {
-        $record = $event->getRecord();
+Want to contribute? We'd love your help! Check out the [contribution guidelines](CONTRIBUTING.md).
 
-        if ($this->containsProhibitedContent($record->text)) {
-            $this->flagForModeration($event->did, $record);
-        }
-    }
-}
-```
+## Credits
 
----
-
-## Requirements
-
-- PHP 8.2 or higher
-- Laravel 11.0 or higher
-- WebSocket support (enabled by default in most environments)
-
----
+- [Miguel Batres](https://batres.co) - founder & lead maintainer
+- [All contributors](https://github.com/socialdept/signal/graphs/contributors)
 
 ## License
 
-The MIT License (MIT). Please see [LICENSE](LICENSE) for more information.
+Signal is open-source software licensed under the [MIT license](LICENSE).
 
 ---
 
-## Support
-
-For issues, questions, or feature requests:
-- Read the [README.md](./README.md) before opening issues
-- Search through existing issues
-- Open new issue
-
----
-
-**Built for the AT Protocol ecosystem** • Made with ❤️ by Social Dept
+**Built for the Federation** • By Social Dept.

docs/configuration.md

···
+# Configuration
+
+Signal's configuration file provides complete control over how your application consumes AT Protocol events.
+
+## Configuration File
+
+After installation, configuration lives in `config/signal.php`.
+
+### Publishing Configuration
+
+Publish the config file manually if needed:
+
+```bash
+php artisan vendor:publish --tag=signal-config
+```
+
+This creates `config/signal.php` with all available options.
+
+## Environment Variables
+
+Most configuration can be set via `.env` for environment-specific values.
+
+### Basic Configuration
+
+```env
+# Consumer Mode (jetstream or firehose)
+SIGNAL_MODE=jetstream
+
+# Jetstream Configuration
+SIGNAL_JETSTREAM_URL=wss://jetstream2.us-east.bsky.network
+
+# Firehose Configuration
+SIGNAL_FIREHOSE_HOST=bsky.network
+
+# Cursor Storage (database, redis, or file)
+SIGNAL_CURSOR_STORAGE=database
+
+# Queue Configuration
+SIGNAL_QUEUE_CONNECTION=redis
+SIGNAL_QUEUE=signal
+```
+
+## Consumer Mode
+
+Choose between Jetstream and Firehose mode.
+
+### Configuration
+
+```php
+'mode' => env('SIGNAL_MODE', 'jetstream'),
+```
+
+**Options:**
+- `jetstream` - JSON events, server-side filtering (default)
+- `firehose` - CBOR/CAR events, client-side filtering
+
+**Environment Variable:**
+```env
+SIGNAL_MODE=jetstream
+```
+
+**When to use each:**
+- **Jetstream**: Standard Bluesky collections, production efficiency
+- **Firehose**: Custom collections, AppViews, comprehensive indexing
+
+[Learn more about modes →](modes.md)
+
+## Jetstream Configuration
+
+Configuration specific to Jetstream mode.
+
+### WebSocket URL
+
+```php
+'jetstream' => [
+    'websocket_url' => env(
+        'SIGNAL_JETSTREAM_URL',
+        'wss://jetstream2.us-east.bsky.network'
+    ),
+],
+```
+
+**Available Endpoints:**
+
+**US East (Default):**
+```env
+SIGNAL_JETSTREAM_URL=wss://jetstream2.us-east.bsky.network
+```
+
+**US West:**
+```env
+SIGNAL_JETSTREAM_URL=wss://jetstream1.us-west.bsky.network
+```
+
+Choose the endpoint closest to your server for best latency.
+
+## Firehose Configuration
+
+Configuration specific to Firehose mode.
+
+### Host
+
+```php
+'firehose' => [
+    'host' => env('SIGNAL_FIREHOSE_HOST', 'bsky.network'),
+],
+```
+
+The WebSocket URL is constructed as:
+```
+wss://{host}/xrpc/com.atproto.sync.subscribeRepos
+```
+
+**Environment Variable:**
+```env
+SIGNAL_FIREHOSE_HOST=bsky.network
+```
+
+**Default Host:** `bsky.network`
+
+**Custom Hosts:** If you're running your own AT Protocol PDS, specify it here:
+```env
+SIGNAL_FIREHOSE_HOST=my-pds.example.com
+```
+
+## Cursor Storage
+
+Configure how Signal stores cursor positions for resuming after disconnections.
+
+### Storage Driver
+
+```php
+'cursor_storage' => env('SIGNAL_CURSOR_STORAGE', 'database'),
+```
+
+**Available Drivers:**
+- `database` - Store in database (recommended for production)
+- `redis` - Store in Redis (high performance)
+- `file` - Store in filesystem (development only)
+
+**Environment Variable:**
+```env
+SIGNAL_CURSOR_STORAGE=database
+```
+
+### Database Driver
+
+Uses Laravel's default database connection.
+
+**Configuration:**
+```php
+'cursor_storage' => 'database',
+```
+
+**Requires:**
+- Migration published and run
+- Database connection configured
+
+**Table:** `signal_cursors`
+
+### Redis Driver
+
+Stores cursors in Redis for high performance.
+
+**Configuration:**
+```php
+'cursor_storage' => 'redis',
+
+'redis' => [
+    'connection' => env('SIGNAL_REDIS_CONNECTION', 'default'),
+    'key_prefix' => env('SIGNAL_REDIS_PREFIX', 'signal:cursor:'),
+],
+```
+
+**Environment Variables:**
+```env
+SIGNAL_CURSOR_STORAGE=redis
+SIGNAL_REDIS_CONNECTION=default
+SIGNAL_REDIS_PREFIX=signal:cursor:
+```
+
+**Requires:**
+- Redis connection configured in `config/database.php`
+- Redis server running
+
+### File Driver
+
+Stores cursors in the filesystem (development only).
+
+**Configuration:**
+```php
+'cursor_storage' => 'file',
+
+'file' => [
+    'path' => env('SIGNAL_FILE_PATH', storage_path('app/signal')),
+],
+```
+
+**Environment Variables:**
+```env
+SIGNAL_CURSOR_STORAGE=file
+SIGNAL_FILE_PATH=/path/to/storage/signal
+```
+
+**Not recommended for production:**
+- Single server only
+- No clustering support
+- Filesystem I/O overhead
+
+## Queue Configuration
+
+Configure how Signal dispatches queued jobs.
+
+### Queue Connection
+
+```php
+'queue' => [
+    'connection' => env('SIGNAL_QUEUE_CONNECTION', null),
+    'queue' => env('SIGNAL_QUEUE', 'default'),
+],
+```
+
+**Environment Variables:**
+```env
+# Queue connection (redis, database, sqs, etc.)
+SIGNAL_QUEUE_CONNECTION=redis
+
+# Queue name
+SIGNAL_QUEUE=signal
+```
+
+**Defaults:**
+- `connection`: Uses Laravel's default queue connection
+- `queue`: Uses Laravel's default queue name
+
+### Per-Signal Configuration
+
+Signals can override queue configuration:
+
+```php
+public function shouldQueue(): bool
+{
+    return true;
+}
+
+public function queueConnection(): string
+{
+    return 'redis'; // Override connection
+}
+
+public function queue(): string
+{
+    return 'high-priority'; // Override queue name
+}
+```
+
+[Learn more about queue integration →](queues.md)
+
+## Auto-Discovery
+
+Configure automatic Signal discovery.
+
+### Enable/Disable
+
+```php
+'auto_discovery' => [
+    'enabled' => true,
+    'path' => app_path('Signals'),
+    'namespace' => 'App\\Signals',
+],
+```
+
+**Options:**
+- `enabled`: Enable/disable auto-discovery (default: `true`)
+- `path`: Directory to scan for Signals (default: `app/Signals`)
+- `namespace`: Namespace for discovered Signals (default: `App\Signals`)
+
+### Disable Auto-Discovery
+
+Manually register Signals instead:
+
+```php
+'auto_discovery' => [
+    'enabled' => false,
+],
+
+'signals' => [
+    \App\Signals\NewPostSignal::class,
+    \App\Signals\NewFollowSignal::class,
+],
+```
+
+### Custom Discovery Path
+
+Organize Signals in a custom directory:
+
+```php
+'auto_discovery' => [
+    'enabled' => true,
+    'path' => app_path('Domain/Signals'),
+    'namespace' => 'App\\Domain\\Signals',
+],
+```
+
+## Manual Signal Registration
+
+Register Signals explicitly.
+
+### Configuration
+
+```php
+'signals' => [
+    \App\Signals\NewPostSignal::class,
+    \App\Signals\NewFollowSignal::class,
+    \App\Signals\ProfileUpdateSignal::class,
+],
+```
+
+**When to use:**
+- Auto-discovery disabled
+- Signals outside standard directory
+- Fine-grained control over which Signals run
+
+## Logging
+
+Signal uses Laravel's logging system.
+
+### Configure Logging
+
+Standard Laravel log configuration applies:
+
+```php
+// config/logging.php
+'channels' => [
+    'signal' => [
+        'driver' => 'daily',
+        'path' => storage_path('logs/signal.log'),
+        'level' => env('SIGNAL_LOG_LEVEL', 'debug'),
+        'days' => 14,
+    ],
+],
+```
+
+Use in Signals:
+
+```php
+use Illuminate\Support\Facades\Log;
+
+public function handle(SignalEvent $event): void
+{
+    Log::channel('signal')->info('Processing event', [
+        'did' => $event->did,
+    ]);
+}
+```
+
+## Complete Configuration Reference
+
+Here's the full `config/signal.php` with all options:
+
+```php
+<?php
+
+return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Consumer Mode
+    |--------------------------------------------------------------------------
+    |
+    | Choose between 'jetstream' (JSON events) or 'firehose' (CBOR/CAR events).
+    | Jetstream is more efficient for standard Bluesky collections.
+    | Firehose is required for custom collections.
+    |
+    | Options: 'jetstream', 'firehose'
+    |
+    */
+
+    'mode' => env('SIGNAL_MODE', 'jetstream'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Jetstream Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Configuration for Jetstream mode (JSON events).
+    |
+    */
+
+    'jetstream' => [
+        'websocket_url' => env(
+            'SIGNAL_JETSTREAM_URL',
+            'wss://jetstream2.us-east.bsky.network'
+        ),
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Firehose Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Configuration for Firehose mode (CBOR/CAR events).
+    |
+    */
+
+    'firehose' => [
+        'host' => env('SIGNAL_FIREHOSE_HOST', 'bsky.network'),
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Cursor Storage
+    |--------------------------------------------------------------------------
+    |
+    | Configure how Signal stores cursor positions for resuming after
+    | disconnections. Options: 'database', 'redis', 'file'
+    |
+    */
+
+    'cursor_storage' => env('SIGNAL_CURSOR_STORAGE', 'database'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Redis Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Configuration for Redis cursor storage.
+    |
+    */
+
+    'redis' => [
+        'connection' => env('SIGNAL_REDIS_CONNECTION', 'default'),
+        'key_prefix' => env('SIGNAL_REDIS_PREFIX', 'signal:cursor:'),
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | File Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Configuration for file-based cursor storage.
+    |
+    */
+
+    'file' => [
+        'path' => env('SIGNAL_FILE_PATH', storage_path('app/signal')),
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Queue Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Configure queue connection and name for processing events asynchronously.
+    |
+    */
+
+    'queue' => [
+        'connection' => env('SIGNAL_QUEUE_CONNECTION', null),
+        'queue' => env('SIGNAL_QUEUE', 'default'),
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Auto-Discovery
+    |--------------------------------------------------------------------------
+    |
+    | Automatically discover and register Signals from the specified directory.
+    |
+    */
+
+    'auto_discovery' => [
+        'enabled' => true,
+        'path' => app_path('Signals'),
+        'namespace' => 'App\\Signals',
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Manual Signal Registration
+    |--------------------------------------------------------------------------
+    |
+    | Manually register Signals if auto-discovery is disabled.
+    |
+    */
+
+    'signals' => [
+        // \App\Signals\NewPostSignal::class,
+    ],
+
+];
+```
+
+## Environment-Specific Configuration
+
+### Development
+
+```env
+SIGNAL_MODE=firehose
+SIGNAL_CURSOR_STORAGE=file
+SIGNAL_QUEUE_CONNECTION=sync
+```
+
+**Why:**
+- Firehose mode sees all events (comprehensive testing)
+- File storage is simple and adequate
+- Sync queue processes immediately (easier debugging)
+
+### Staging
+
+```env
+SIGNAL_MODE=jetstream
+SIGNAL_CURSOR_STORAGE=redis
+SIGNAL_QUEUE_CONNECTION=redis
+SIGNAL_QUEUE=signal-staging
+```
+
+**Why:**
+- Jetstream mode matches production
+- Redis for performance testing
+- Separate queue for staging isolation
+
+### Production
+
+```env
+SIGNAL_MODE=jetstream
+SIGNAL_CURSOR_STORAGE=database
+SIGNAL_QUEUE_CONNECTION=redis
+SIGNAL_QUEUE=signal
+```
+
+**Why:**
+- Jetstream mode for efficiency
+- Database storage for reliability
+- Redis queues for performance
+
+## Runtime Configuration
+
+Change configuration at runtime:
+
+```php
+use SocialDept\Signal\Facades\Signal;
+
+// Override mode
+config(['signal.mode' => 'firehose']);
+
+// Override cursor storage
+config(['signal.cursor_storage' => 'redis']);
+
+// Start consumer with new config
+Signal::start();
+```
+
+## Validation
+
+Signal validates configuration on startup:
+
+```bash
+php artisan signal:consume
+```
+
+**Checks:**
+- Mode is valid (`jetstream` or `firehose`)
+- Cursor storage driver exists
+- Required endpoints are configured
+- Queue configuration is valid
+
+**Validation errors prevent consumer from starting.**
+
+## Configuration Helpers
+
+### Check Current Mode
+
+```php
+$mode = config('signal.mode'); // 'jetstream' or 'firehose'
+```
+
+Or via Facade:
+
+```php
+use SocialDept\Signal\Facades\Signal;
+
+$mode = Signal::getMode();
+```
+
+### Check Cursor Storage
+
+```php
+$storage = config('signal.cursor_storage'); // 'database', 'redis', or 'file'
+```
+
+### Check Queue Configuration
+
+```php
+$connection = config('signal.queue.connection');
+$queue = config('signal.queue.queue');
+```
+
+## Best Practices
+
+### Use Environment Variables
+
+Don't hardcode values in config file:
+
+```php
+// Good
+'mode' => env('SIGNAL_MODE', 'jetstream'),
+
+// Bad
+'mode' => 'jetstream',
+```
+
+### Separate Staging and Production
+
+Use different queues and storage:
+
+```env
+# .env.staging
+SIGNAL_QUEUE=signal-staging
+
+# .env.production
+SIGNAL_QUEUE=signal-production
+```
+
+### Document Custom Configuration
+
+If you change defaults, document why:
+
+```php
+// We use Firehose mode because we have custom collections
+'mode' => env('SIGNAL_MODE', 'firehose'),
+```
+
+### Version Control
+
+Commit `config/signal.php` but not `.env`:
+
+```gitignore
+# .gitignore
+.env
+.env.*
+
+# Commit
+config/signal.php
+```
+
+## Troubleshooting
+
+### Configuration Not Loading
+
+Clear config cache:
+
+```bash
+php artisan config:clear
+php artisan config:cache
+```
+
+### Environment Variables Not Working
+
+Check `.env` file exists and is readable:
+
+```bash
+ls -la .env
+```
+
+Restart services after changing `.env`:
+
+```bash
+# If using Supervisor
+sudo supervisorctl restart signal-consumer:*
+```
+
+### Invalid Configuration
+
+Run consumer to see validation errors:
+
+```bash
+php artisan signal:consume
+```
+
+Signal will display specific errors about misconfiguration.
+
+## Next Steps
+
+- **[Learn about testing →](testing.md)** - Test your configuration
+- **[See real-world examples →](examples.md)** - Learn from production configurations
+- **[Review queue integration →](queues.md)** - Configure queues optimally

docs/examples.md

···
+# Real-World Examples
+
+Learn from production-ready Signal examples covering common use cases.
+
+## Social Media Analytics
+
+Track engagement metrics across Bluesky.
+
+```php
+<?php
+
+namespace App\Signals;
+
+use App\Models\EngagementMetric;
+use SocialDept\Signal\Enums\SignalCommitOperation;
+use SocialDept\Signal\Events\SignalEvent;
+use SocialDept\Signal\Signals\Signal;
+use Illuminate\Support\Facades\DB;
+
+class EngagementTrackerSignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function collections(): ?array
+    {
+        return [
+            'app.bsky.feed.post',
+            'app.bsky.feed.like',
+            'app.bsky.feed.repost',
+            'app.bsky.graph.follow',
+        ];
+    }
+
+    public function operations(): ?array
+    {
+        return [SignalCommitOperation::Create];
+    }
+
+    public function shouldQueue(): bool
+    {
+        return true;
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        $collection = $event->getCollection();
+        $timestamp = $event->getTimestamp();
+
+        // Increment counter for this hour
+        DB::table('engagement_metrics')
+            ->updateOrInsert(
+                [
+                    'collection' => $collection,
+                    'hour' => $timestamp->startOfHour(),
+                ],
+                [
+                    'count' => DB::raw('count + 1'),
+                    'updated_at' => now(),
+                ]
+            );
+    }
+}
+```
+
+**Use case:** Build analytics dashboards showing posts/hour, likes/hour, follows/hour.
+
+## Content Moderation
+
+Automatically flag problematic content.
+
+```php
+<?php
+
+namespace App\Signals;
+
+use App\Models\FlaggedPost;
+use App\Services\ModerationService;
+use SocialDept\Signal\Enums\SignalCommitOperation;
+use SocialDept\Signal\Events\SignalEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class ModerationSignal extends Signal
+{
+    public function __construct(
+        private ModerationService $moderation
+    ) {}
+
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function collections(): ?array
+    {
+        return ['app.bsky.feed.post'];
+    }
+
+    public function operations(): ?array
+    {
+        return [SignalCommitOperation::Create];
+    }
+
+    public function shouldQueue(): bool
+    {
+        return true;
+    }
+
+    public function queue(): string
+    {
+        return 'moderation';
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        $record = $event->getRecord();
+
+        if (!isset($record->text)) {
+            return;
+        }
+
+        $result = $this->moderation->analyze($record->text);
+
+        if ($result->needsReview) {
+            FlaggedPost::create([
+                'did' => $event->did,
+                'rkey' => $event->commit->rkey,
+                'text' => $record->text,
+                'reason' => $result->reason,
+                'confidence' => $result->confidence,
+                'flagged_at' => now(),
+            ]);
+        }
+    }
+
+    public function failed(SignalEvent $event, \Throwable $exception): void
+    {
+        Log::error('Moderation signal failed', [
+            'did' => $event->did,
+            'error' => $exception->getMessage(),
+        ]);
+    }
+}
+```
+
+**Use case:** Automated content moderation with human review queue.
+
+## User Activity Feed
+
+Build a personalized activity feed.
+
+```php
+<?php
+
+namespace App\Signals;
+
+use App\Models\Activity;
+use App\Models\User;
+use SocialDept\Signal\Enums\SignalCommitOperation;
+use SocialDept\Signal\Events\SignalEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class ActivityFeedSignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function collections(): ?array
+    {
+        return [
+            'app.bsky.feed.post',
+            'app.bsky.feed.like',
+            'app.bsky.feed.repost',
+        ];
+    }
+
+    public function operations(): ?array
+    {
+        return [SignalCommitOperation::Create];
+    }
+
+    public function shouldQueue(): bool
+    {
+        return true;
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        // Check if we're tracking this user
+        $user = User::where('did', $event->did)->first();
+
+        if (!$user) {
+            return;
+        }
+
+        // Check if any followers want to see this
+        $followerIds = $user->followers()->pluck('id');
+
+        if ($followerIds->isEmpty()) {
+            return;
+        }
+
+        $collection = $event->getCollection();
+
+        // Create activity for each follower's feed
+        foreach ($followerIds as $followerId) {
+            Activity::create([
+                'user_id' => $followerId,
+                'actor_did' => $event->did,
+                'type' => $this->getActivityType($collection),
+                'data' => $event->toArray(),
+                'created_at' => $event->getTimestamp(),
+            ]);
+        }
+    }
+
+    private function getActivityType(string $collection): string
+    {
+        return match ($collection) {
+            'app.bsky.feed.post' => 'post',
+            'app.bsky.feed.like' => 'like',
+            'app.bsky.feed.repost' => 'repost',
+            default => 'unknown',
+        };
+    }
+}
+```
+
+**Use case:** Show users activity from people they follow.
+
+## Real-Time Notifications
+
+Send notifications for mentions and interactions.
+
+```php
+<?php
+
+namespace App\Signals;
+
+use App\Models\User;
+use App\Notifications\MentionedInPost;
+use SocialDept\Signal\Enums\SignalCommitOperation;
+use SocialDept\Signal\Events\SignalEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class MentionNotificationSignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function collections(): ?array
+    {
+        return ['app.bsky.feed.post'];
+    }
+
+    public function operations(): ?array
+    {
+        return [SignalCommitOperation::Create];
+    }
+
+    public function shouldQueue(): bool
+    {
+        return true;
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        $record = $event->getRecord();
+
+        if (!isset($record->facets)) {
+            return;
+        }
+
+        // Extract mentions from facets
+        $mentions = collect($record->facets)
+            ->filter(fn($facet) => isset($facet->features))
+            ->flatMap(fn($facet) => $facet->features)
+            ->filter(fn($feature) => $feature->{'$type'} === 'app.bsky.richtext.facet#mention')
+            ->pluck('did')
+            ->unique();
+
+        foreach ($mentions as $mentionedDid) {
+            $user = User::where('did', $mentionedDid)->first();
+
+            if ($user) {
+                $user->notify(new MentionedInPost(
+                    authorDid: $event->did,
+                    text: $record->text ?? '',
+                    uri: "at://{$event->did}/app.bsky.feed.post/{$event->commit->rkey}"
+                ));
+            }
+        }
+    }
+}
+```
+
+**Use case:** Real-time notifications when users are mentioned.
+
+## Follow Tracker
+
+Track follow relationships and send notifications.
+
+```php
+<?php
+
+namespace App\Signals;
+
+use App\Models\Follow;
+use App\Models\User;
+use App\Notifications\NewFollower;
+use SocialDept\Signal\Enums\SignalCommitOperation;
+use SocialDept\Signal\Events\SignalEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class FollowTrackerSignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function collections(): ?array
+    {
+        return ['app.bsky.graph.follow'];
+    }
+
+    public function operations(): ?array
+    {
+        return [
+            SignalCommitOperation::Create,
+            SignalCommitOperation::Delete,
+        ];
+    }
+
+    public function shouldQueue(): bool
+    {
+        return true;
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        $record = $event->getRecord();
+        $operation = $event->getOperation();
+
+        if ($operation === SignalCommitOperation::Create) {
+            $this->handleNewFollow($event, $record);
+        } else {
+            $this->handleUnfollow($event);
+        }
+    }
+
+    private function handleNewFollow(SignalEvent $event, object $record): void
+    {
+        Follow::create([
+            'follower_did' => $event->did,
+            'following_did' => $record->subject,
+            'created_at' => $record->createdAt ?? now(),
+        ]);
+
+        // Notify the followed user
+        $followedUser = User::where('did', $record->subject)->first();
+
+        if ($followedUser) {
+            $followedUser->notify(new NewFollower($event->did));
+        }
+    }
+
+    private function handleUnfollow(SignalEvent $event): void
+    {
+        Follow::where('follower_did', $event->did)
+            ->where('rkey', $event->commit->rkey)
+            ->delete();
+    }
+}
+```
+
+**Use case:** Track follows and notify users of new followers.
+
+## Search Indexer
+
+Index posts for full-text search.
+
+```php
+<?php
+
+namespace App\Signals;
+
+use App\Models\Post;
+use Laravel\Scout\Searchable;
+use SocialDept\Signal\Enums\SignalCommitOperation;
+use SocialDept\Signal\Events\SignalEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class SearchIndexerSignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function collections(): ?array
+    {
+        return ['app.bsky.feed.post'];
+    }
+
+    public function shouldQueue(): bool
+    {
+        return true;
+    }
+
+    public function queue(): string
+    {
+        return 'indexing';
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        $operation = $event->getOperation();
+
+        match ($operation) {
+            SignalCommitOperation::Create,
+            SignalCommitOperation::Update => $this->indexPost($event),
+            SignalCommitOperation::Delete => $this->deletePost($event),
+        };
+    }
+
+    private function indexPost(SignalEvent $event): void
+    {
+        $record = $event->getRecord();
+
+        $post = Post::updateOrCreate(
+            [
+                'did' => $event->did,
+                'rkey' => $event->commit->rkey,
+            ],
+            [
+                'text' => $record->text ?? '',
+                'created_at' => $record->createdAt ?? now(),
+                'indexed_at' => now(),
+            ]
+        );
+
+        // Scout automatically indexes
+        $post->searchable();
+    }
+
+    private function deletePost(SignalEvent $event): void
+    {
+        $post = Post::where('did', $event->did)
+            ->where('rkey', $event->commit->rkey)
+            ->first();
+
+        if ($post) {
+            $post->unsearchable();
+            $post->delete();
+        }
+    }
+}
+```
+
+**Use case:** Full-text search across all Bluesky posts.
+
+## Trend Detection
+
+Identify trending topics and hashtags.
+
+```php
+<?php
+
+namespace App\Signals;
+
+use App\Models\TrendingTopic;
+use Illuminate\Support\Facades\Cache;
+use SocialDept\Signal\Enums\SignalCommitOperation;
+use SocialDept\Signal\Events\SignalEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class TrendDetectionSignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function collections(): ?array
+    {
+        return ['app.bsky.feed.post'];
+    }
+
+    public function operations(): ?array
+    {
+        return [SignalCommitOperation::Create];
+    }
+
+    public function shouldQueue(): bool
+    {
+        return true;
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        $record = $event->getRecord();
+
+        if (!isset($record->text)) {
+            return;
+        }
+
+        // Extract hashtags
+        preg_match_all('/#(\w+)/', $record->text, $matches);
+
+        foreach ($matches[1] as $hashtag) {
+            $this->incrementHashtag($hashtag);
+        }
+    }
+
+    private function incrementHashtag(string $hashtag): void
+    {
+        $key = "trending:hashtag:{$hashtag}";
+
+        // Increment counter (expires after 1 hour)
+        $count = Cache::increment($key, 1);
+
+        if (!Cache::has($key)) {
+            Cache::put($key, 1, now()->addHour());
+        }
+
+        // Update trending topics if threshold reached
+        if ($count > 100) {
+            TrendingTopic::updateOrCreate(
+                ['hashtag' => $hashtag],
+                ['count' => $count, 'updated_at' => now()]
+            );
+        }
+    }
+}
+```
+
+**Use case:** Identify trending hashtags and topics in real-time.
+
+## Custom AppView
+
+Index custom collections for your AppView.
+
+```php
+<?php
+
+namespace App\Signals;
+
+use App\Models\Publication;
+use SocialDept\Signal\Enums\SignalCommitOperation;
+use SocialDept\Signal\Events\SignalEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class PublicationIndexerSignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function collections(): ?array
+    {
+        return [
+            'app.offprint.beta.publication',
+            'app.offprint.beta.post',
+        ];
+    }
+
+    public function shouldQueue(): bool
+    {
+        return true;
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        $collection = $event->getCollection();
+        $operation = $event->getOperation();
+
+        if ($collection === 'app.offprint.beta.publication') {
+            $this->handlePublication($event, $operation);
+        } else {
+            $this->handlePost($event, $operation);
+        }
+    }
+
+    private function handlePublication(SignalEvent $event, SignalCommitOperation $operation): void
+    {
+        if ($operation === SignalCommitOperation::Delete) {
+            Publication::where('did', $event->did)
+                ->where('rkey', $event->commit->rkey)
+                ->delete();
+            return;
+        }
+
+        $record = $event->getRecord();
+
+        Publication::updateOrCreate(
+            [
+                'did' => $event->did,
+                'rkey' => $event->commit->rkey,
+            ],
+            [
+                'title' => $record->title ?? '',
+                'description' => $record->description ?? null,
+                'created_at' => $record->createdAt ?? now(),
+            ]
+        );
+    }
+
+    private function handlePost(SignalEvent $event, SignalCommitOperation $operation): void
+    {
+        // Handle custom post records
+    }
+}
+```
+
+**Use case:** Build AT Protocol AppViews with custom collections.
+
+## Rate-Limited API Integration
+
+Integrate with external APIs respecting rate limits.
+
+```php
+<?php
+
+namespace App\Signals;
+
+use App\Services\ExternalAPIService;
+use Illuminate\Support\Facades\RateLimiter;
+use SocialDept\Signal\Events\SignalEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class APIIntegrationSignal extends Signal
+{
+    public function __construct(
+        private ExternalAPIService $api
+    ) {}
+
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function collections(): ?array
+    {
+        return ['app.bsky.feed.post'];
+    }
+
+    public function shouldQueue(): bool
+    {
+        return true;
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        $record = $event->getRecord();
+
+        // Rate limit: 100 calls per minute
+        $executed = RateLimiter::attempt(
+            'external-api',
+            $perMinute = 100,
+            function () use ($event, $record) {
+                $this->api->sendPost([
+                    'author' => $event->did,
+                    'text' => $record->text ?? '',
+                    'timestamp' => $event->getTimestamp(),
+                ]);
+            }
+        );
+
+        if (!$executed) {
+            // Re-queue for later
+            dispatch(fn() => $this->handle($event))
+                ->delay(now()->addMinutes(1));
+        }
+    }
+}
+```
+
+**Use case:** Mirror content to external platforms with rate limiting.
+
+## Multi-Collection Analytics
+
+Track engagement across multiple collection types.
+
+```php
+<?php
+
+namespace App\Signals;
+
+use App\Models\UserMetrics;
+use SocialDept\Signal\Enums\SignalCommitOperation;
+use SocialDept\Signal\Events\SignalEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class UserMetricsSignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function collections(): ?array
+    {
+        return ['app.bsky.feed.*', 'app.bsky.graph.*'];
+    }
+
+    public function operations(): ?array
+    {
+        return [SignalCommitOperation::Create];
+    }
+
+    public function shouldQueue(): bool
+    {
+        return true;
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        $collection = $event->getCollection();
+
+        $metrics = UserMetrics::firstOrCreate(
+            ['did' => $event->did],
+            ['total_posts' => 0, 'total_likes' => 0, 'total_follows' => 0]
+        );
+
+        match ($collection) {
+            'app.bsky.feed.post' => $metrics->increment('total_posts'),
+            'app.bsky.feed.like' => $metrics->increment('total_likes'),
+            'app.bsky.graph.follow' => $metrics->increment('total_follows'),
+            default => null,
+        };
+
+        $metrics->touch('last_activity_at');
+    }
+}
+```
+
+**Use case:** User activity metrics and leaderboards.
+
+## Performance Tips
+
+### Batch Database Operations
+
+```php
+public function handle(SignalEvent $event): void
+{
+    // Bad - individual inserts
+    Post::create([...]);
+
+    // Good - batch inserts
+    $posts = Cache::get('pending_posts', []);
+    $posts[] = [...];
+
+    if (count($posts) >= 100) {
+        Post::insert($posts);
+        Cache::forget('pending_posts');
+    } else {
+        Cache::put('pending_posts', $posts, now()->addMinutes(5));
+    }
+}
+```
+
+### Use Queues for Heavy Operations
+
+```php
+public function shouldQueue(): bool
+{
+    // Queue if operation takes > 100ms
+    return true;
+}
+```
+
+### Add Indexes for Filtering
+
+```php
+// Migration for fast lookups
+Schema::table('posts', function (Blueprint $table) {
+    $table->index(['did', 'rkey']);
+    $table->index('created_at');
+});
+```
+
+## Next Steps
+
+- **[Review signal architecture →](signals.md)** - Understand Signal structure
+- **[Learn about filtering →](filtering.md)** - Master event filtering
+- **[Explore queue integration →](queues.md)** - Build high-performance Signals
+- **[Configure your setup →](configuration.md)** - Optimize configuration

docs/filtering.md

···
+# Filtering Events
+
+Filtering is how you control which events your Signals process. Signal provides multiple layers of filtering to help you target exactly the events you care about.
+
+## Why Filter?
+
+The AT Protocol generates millions of events per hour. Without filtering:
+
+- Your Signals would process every event (slow and expensive)
+- Your database would fill with irrelevant data
+- Your queues would be overwhelmed
+- Your costs would skyrocket
+
+Filtering lets you focus on what matters.
+
+## Filter Layers
+
+Signal provides four filtering layers, applied in order:
+
+1. **Event Type Filtering** - Which kind of events (commit, identity, account)
+2. **Collection Filtering** - Which AT Protocol collections
+3. **Operation Filtering** - Which operations (create, update, delete)
+4. **DID Filtering** - Which users
+5. **Custom Filtering** - Your own logic
+
+## Event Type Filtering
+
+The most basic filter - required for all Signals.
+
+### Available Event Types
+
+```php
+use SocialDept\Signal\Enums\SignalEventType;
+
+public function eventTypes(): array
+{
+    return [SignalEventType::Commit]; // Most common
+    // Or: return ['commit'];
+}
+```
+
+**Three event types:**
+
+| Type       | Description        | Use Cases                              |
+|------------|--------------------|----------------------------------------|
+| `commit`   | Repository changes | Posts, likes, follows, profile updates |
+| `identity` | Handle changes     | Username updates, account migrations   |
+| `account`  | Account status     | Deactivation, suspension               |
+
+### Multiple Event Types
+
+Listen to multiple types in one Signal:
+
+```php
+public function eventTypes(): array
+{
+    return [
+        SignalEventType::Commit,
+        SignalEventType::Identity,
+    ];
+}
+```
+
+Then check the type in your handler:
+
+```php
+public function handle(SignalEvent $event): void
+{
+    if ($event->isCommit()) {
+        $this->handleCommit($event);
+    }
+
+    if ($event->isIdentity()) {
+        $this->handleIdentity($event);
+    }
+}
+```
+
+## Collection Filtering
+
+Collections represent different types of data in the AT Protocol.
+
+### Basic Collection Filter
+
+```php
+public function collections(): ?array
+{
+    return ['app.bsky.feed.post'];
+}
+```
+
+### No Filter (All Collections)
+
+Return `null` to process all collections:
+
+```php
+public function collections(): ?array
+{
+    return null; // Handle everything
+}
+```
+
+### Multiple Collections
+
+```php
+public function collections(): ?array
+{
+    return [
+        'app.bsky.feed.post',
+        'app.bsky.feed.like',
+        'app.bsky.feed.repost',
+    ];
+}
+```
+
+### Wildcard Patterns
+
+Use `*` to match multiple collections:
+
+```php
+public function collections(): ?array
+{
+    return ['app.bsky.feed.*'];
+}
+```
+
+**This matches:**
+- `app.bsky.feed.post`
+- `app.bsky.feed.like`
+- `app.bsky.feed.repost`
+- Any other `app.bsky.feed.*` collection
+
+### Common Collection Patterns
+
+| Pattern            | Matches                 | Use Case               |
+|--------------------|-------------------------|------------------------|
+| `app.bsky.feed.*`  | All feed interactions   | Posts, likes, reposts  |
+| `app.bsky.graph.*` | All social graph        | Follows, blocks, mutes |
+| `app.bsky.actor.*` | All profile changes     | Profile updates        |
+| `app.bsky.*`       | All Bluesky collections | Everything Bluesky     |
+| `app.yourapp.*`    | Your custom collections | Custom AppView         |
+
+### Mixing Exact and Wildcards
+
+Combine exact matches with wildcards:
+
+```php
+public function collections(): ?array
+{
+    return [
+        'app.bsky.feed.post',        // Exact: only posts
+        'app.bsky.graph.*',          // Wildcard: all graph events
+        'app.myapp.custom.record',   // Exact: custom collection
+    ];
+}
+```
+
+### Standard Bluesky Collections
+
+**Feed Collections** (`app.bsky.feed.*`):
+- `app.bsky.feed.post` - Posts (text, images, videos)
+- `app.bsky.feed.like` - Likes on posts
+- `app.bsky.feed.repost` - Reposts (shares)
+- `app.bsky.feed.threadgate` - Thread reply controls
+- `app.bsky.feed.generator` - Custom feed generators
+
+**Graph Collections** (`app.bsky.graph.*`):
+- `app.bsky.graph.follow` - Follow relationships
+- `app.bsky.graph.block` - Blocked users
+- `app.bsky.graph.list` - User lists
+- `app.bsky.graph.listitem` - List memberships
+- `app.bsky.graph.listblock` - List blocks
+
+**Actor Collections** (`app.bsky.actor.*`):
+- `app.bsky.actor.profile` - User profiles
+
+**Labeler Collections** (`app.bsky.labeler.*`):
+- `app.bsky.labeler.service` - Labeler services
+
+### Important: Jetstream vs Firehose Filtering
+
+**Jetstream Mode:**
+- Exact collection names are sent to server for filtering (efficient)
+- Wildcards work client-side only (you receive more data)
+
+**Firehose Mode:**
+- All filtering is client-side
+- Wildcards work normally (no difference in data received)
+
+[Learn more about modes →](modes.md)
+
+### Custom Collections (AppViews)
+
+Filter your own custom collections:
+
+```php
+public function collections(): ?array
+{
+    return [
+        'app.offprint.beta.publication',
+        'app.offprint.beta.post',
+    ];
+}
+```
+
+## Operation Filtering
+
+Filter by operation type (only applies to commit events).
+
+### Available Operations
+
+```php
+use SocialDept\Signal\Enums\SignalCommitOperation;
+
+public function operations(): ?array
+{
+    return [SignalCommitOperation::Create];
+    // Or: return ['create'];
+}
+```
+
+**Three operation types:**
+
+| Operation | Description      | Example         |
+|-----------|------------------|-----------------|
+| `create`  | New records      | Creating a post |
+| `update`  | Modified records | Editing a post  |
+| `delete`  | Removed records  | Deleting a post |
+
+### No Filter (All Operations)
+
+```php
+public function operations(): ?array
+{
+    return null; // Handle all operations
+}
+```
+
+### Multiple Operations
+
+```php
+public function operations(): ?array
+{
+    return [
+        SignalCommitOperation::Create,
+        SignalCommitOperation::Update,
+    ];
+    // Or: return ['create', 'update'];
+}
+```
+
+### Common Patterns
+
+**Only track new content:**
+```php
+public function operations(): ?array
+{
+    return [SignalCommitOperation::Create];
+}
+```
+
+**Track modifications:**
+```php
+public function operations(): ?array
+{
+    return [SignalCommitOperation::Update];
+}
+```
+
+**Cleanup on deletions:**
+```php
+public function operations(): ?array
+{
+    return [SignalCommitOperation::Delete];
+}
+```
+
+### Checking Operations in Handler
+
+You can also check operation type in your handler:
+
+```php
+public function handle(SignalEvent $event): void
+{
+    $operation = $event->getOperation();
+
+    // Using enum
+    if ($operation === SignalCommitOperation::Create) {
+        $this->createRecord($event);
+    }
+
+    // Using commit helper
+    if ($event->commit->isCreate()) {
+        $this->createRecord($event);
+    }
+
+    if ($event->commit->isUpdate()) {
+        $this->updateRecord($event);
+    }
+
+    if ($event->commit->isDelete()) {
+        $this->deleteRecord($event);
+    }
+}
+```
+
+## DID Filtering
+
+Filter events by specific users (DIDs).
+
+### Basic DID Filter
+
+```php
+public function dids(): ?array
+{
+    return [
+        'did:plc:z72i7hdynmk6r22z27h6tvur',
+    ];
+}
+```
+
+### No Filter (All Users)
+
+```php
+public function dids(): ?array
+{
+    return null; // Handle all users
+}
+```
+
+### Multiple DIDs
+
+```php
+public function dids(): ?array
+{
+    return [
+        'did:plc:z72i7hdynmk6r22z27h6tvur',
+        'did:plc:ragtjsm2j2vknwkz3zp4oxrd',
+    ];
+}
+```
+
+### Use Cases
+
+**Monitor specific accounts:**
+```php
+// Track posts from specific content creators
+public function collections(): ?array
+{
+    return ['app.bsky.feed.post'];
+}
+
+public function dids(): ?array
+{
+    return [
+        'did:plc:z72i7hdynmk6r22z27h6tvur', // Creator 1
+        'did:plc:ragtjsm2j2vknwkz3zp4oxrd', // Creator 2
+    ];
+}
+```
+
+**Dynamic DID filtering:**
+```php
+use App\Models\MonitoredAccount;
+
+public function dids(): ?array
+{
+    return MonitoredAccount::pluck('did')->toArray();
+}
+```
+
+## Custom Filtering
+
+Implement complex filtering logic with `shouldHandle()`.
+
+### Basic Custom Filter
+
+```php
+public function shouldHandle(SignalEvent $event): bool
+{
+    // Only handle posts with images
+    if ($event->isCommit() && $event->getCollection() === 'app.bsky.feed.post') {
+        $record = $event->getRecord();
+        return isset($record->embed);
+    }
+
+    return true;
+}
+```
+
+### Advanced Examples
+
+**Filter by text content:**
+```php
+public function shouldHandle(SignalEvent $event): bool
+{
+    $record = $event->getRecord();
+
+    if (!isset($record->text)) {
+        return false;
+    }
+
+    // Only handle posts mentioning "Laravel"
+    return str_contains($record->text, 'Laravel');
+}
+```
+
+**Filter by language:**
+```php
+public function shouldHandle(SignalEvent $event): bool
+{
+    $record = $event->getRecord();
+
+    // Only handle English posts
+    return ($record->langs[0] ?? null) === 'en';
+}
+```
+
+**Filter by engagement:**
+```php
+use App\Services\EngagementCalculator;
+
+public function shouldHandle(SignalEvent $event): bool
+{
+    $engagement = EngagementCalculator::calculate($event);
+
+    // Only handle high-engagement content
+    return $engagement > 100;
+}
+```
+
+**Time-based filtering:**
+```php
+public function shouldHandle(SignalEvent $event): bool
+{
+    $timestamp = $event->getTimestamp();
+
+    // Only handle events from the last hour
+    return $timestamp->isAfter(now()->subHour());
+}
+```
+
+## Combining Filters
+
+Stack multiple filter layers for precise targeting:
+
+```php
+class HighEngagementPostsSignal extends Signal
+{
+    // Layer 1: Event type
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    // Layer 2: Collection
+    public function collections(): ?array
+    {
+        return ['app.bsky.feed.post'];
+    }
+
+    // Layer 3: Operation
+    public function operations(): ?array
+    {
+        return [SignalCommitOperation::Create];
+    }
+
+    // Layer 4: Custom logic
+    public function shouldHandle(SignalEvent $event): bool
+    {
+        $record = $event->getRecord();
+
+        // Must have text
+        if (!isset($record->text)) {
+            return false;
+        }
+
+        // Must be longer than 100 characters
+        if (strlen($record->text) < 100) {
+            return false;
+        }
+
+        // Must have media
+        if (!isset($record->embed)) {
+            return false;
+        }
+
+        return true;
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        // Only high-quality posts make it here
+    }
+}
+```
+
+## Performance Considerations
+
+### Server-Side vs Client-Side Filtering
+
+**Jetstream Mode (Server-Side):**
+- Collections filter applied on server (efficient)
+- Only receives matching events
+- Lower bandwidth usage
+
+```php
+// These collections are sent to Jetstream server
+public function collections(): ?array
+{
+    return ['app.bsky.feed.post', 'app.bsky.feed.like'];
+}
+```
+
+**Firehose Mode (Client-Side):**
+- All filtering happens in your application
+- Receives all events (higher bandwidth)
+- More control but higher cost
+
+[Learn more about modes →](modes.md)
+
+### Filter Early
+
+Apply the most restrictive filters first:
+
+```php
+// Good - filters early
+public function eventTypes(): array
+{
+    return ['commit']; // Narrows to commits only
+}
+
+public function collections(): ?array
+{
+    return ['app.bsky.feed.post']; // Further narrows to posts
+}
+
+// Less ideal - too broad
+public function eventTypes(): array
+{
+    return ['commit', 'identity', 'account']; // Too many events
+}
+
+public function shouldHandle(SignalEvent $event): bool
+{
+    // Filtering everything in custom logic (expensive)
+    return $event->isCommit() && $event->getCollection() === 'app.bsky.feed.post';
+}
+```
+
+### Avoid Heavy Logic in shouldHandle()
+
+Keep custom filtering lightweight:
+
+```php
+// Good - lightweight checks
+public function shouldHandle(SignalEvent $event): bool
+{
+    $record = $event->getRecord();
+    return isset($record->text) && strlen($record->text) > 10;
+}
+
+// Less ideal - heavy database queries
+public function shouldHandle(SignalEvent $event): bool
+{
+    // Database query on every event (slow!)
+    return User::where('did', $event->did)->exists();
+}
+```
+
+If you need heavy logic, use queues:
+
+```php
+public function shouldQueue(): bool
+{
+    return true; // Move heavy work to queue
+}
+```
+
+## Common Filter Patterns
+
+### Track All Activity from Specific Users
+
+```php
+public function eventTypes(): array
+{
+    return ['commit'];
+}
+
+public function dids(): ?array
+{
+    return [
+        'did:plc:z72i7hdynmk6r22z27h6tvur',
+    ];
+}
+```
+
+### Monitor All Feed Activity
+
+```php
+public function eventTypes(): array
+{
+    return ['commit'];
+}
+
+public function collections(): ?array
+{
+    return ['app.bsky.feed.*'];
+}
+```
+
+### Track Only New Posts
+
+```php
+public function eventTypes(): array
+{
+    return ['commit'];
+}
+
+public function collections(): ?array
+{
+    return ['app.bsky.feed.post'];
+}
+
+public function operations(): ?array
+{
+    return [SignalCommitOperation::Create];
+}
+```
+
+### Monitor Content Deletions
+
+```php
+public function eventTypes(): array
+{
+    return ['commit'];
+}
+
+public function operations(): ?array
+{
+    return [SignalCommitOperation::Delete];
+}
+```
+
+### Track Profile Changes
+
+```php
+public function eventTypes(): array
+{
+    return ['commit'];
+}
+
+public function collections(): ?array
+{
+    return ['app.bsky.actor.profile'];
+}
+```
+
+### Monitor Handle Changes
+
+```php
+public function eventTypes(): array
+{
+    return ['identity'];
+}
+```
+
+## Debugging Filters
+
+### Log What's Being Filtered
+
+```php
+public function shouldHandle(SignalEvent $event): bool
+{
+    $shouldHandle = $this->myCustomLogic($event);
+
+    if (!$shouldHandle) {
+        Log::debug('Event filtered out', [
+            'signal' => static::class,
+            'did' => $event->did,
+            'collection' => $event->getCollection(),
+            'reason' => 'Failed custom logic',
+        ]);
+    }
+
+    return $shouldHandle;
+}
+```
+
+### Test Your Filters
+
+```bash
+php artisan signal:test YourSignal
+```
+
+This runs your Signal with sample data to verify filtering works correctly.
+
+[Learn more about testing →](testing.md)
+
+## Next Steps
+
+- **[Understand Jetstream vs Firehose →](modes.md)** - Choose the right mode for your filters
+- **[Learn about queue integration →](queues.md)** - Handle high-volume filtered events
+- **[See real-world examples →](examples.md)** - Learn from production filter patterns

docs/installation.md

···
+# Installation
+
+Signal is designed to be installed quickly and easily in any Laravel 11+ application.
+
+## Requirements
+
+Before installing Signal, ensure your environment meets these requirements:
+
+- **PHP 8.2 or higher**
+- **Laravel 11.0 or higher**
+- **WebSocket support** (enabled by default in most environments)
+- **Database** (for cursor storage)
+
+## Composer Installation
+
+Install Signal via Composer:
+
+```bash
+composer require socialdept/signal
+```
+
+## Quick Setup
+
+Run the installation command to set up everything automatically:
+
+```bash
+php artisan signal:install
+```
+
+This interactive command will:
+
+1. Publish the configuration file to `config/signal.php`
+2. Publish database migrations for cursor storage
+3. Ask if you'd like to run migrations immediately
+4. Display next steps and helpful information
+
+### What Gets Created
+
+After installation, you'll have:
+
+- **Configuration file**: `config/signal.php` - All Signal settings
+- **Migration**: `database/migrations/2024_01_01_000000_create_signal_cursors_table.php` - Cursor storage
+- **Signal directory**: `app/Signals/` - Where your Signals live (created when you make your first Signal)
+
+## Manual Installation
+
+If you prefer more control, you can install manually:
+
+### 1. Publish Configuration
+
+```bash
+php artisan vendor:publish --tag=signal-config
+```
+
+This creates `config/signal.php` with all available options.
+
+### 2. Publish Migrations
+
+```bash
+php artisan vendor:publish --tag=signal-migrations
+```
+
+This creates the cursor storage migration in `database/migrations/`.
+
+### 3. Run Migrations
+
+```bash
+php artisan migrate
+```
+
+This creates the `signal_cursors` table for resuming from last position after disconnections.
+
+## Environment Configuration
+
+Add Signal configuration to your `.env` file:
+
+```env
+# Consumer Mode (jetstream or firehose)
+SIGNAL_MODE=jetstream
+
+# Jetstream URL (if using jetstream mode)
+SIGNAL_JETSTREAM_URL=wss://jetstream2.us-east.bsky.network
+
+# Firehose Host (if using firehose mode)
+SIGNAL_FIREHOSE_HOST=bsky.network
+
+# Optional: Cursor Storage Driver (database, redis, or file)
+SIGNAL_CURSOR_STORAGE=database
+
+# Optional: Queue Configuration
+SIGNAL_QUEUE_CONNECTION=redis
+SIGNAL_QUEUE=signal
+```
+
+## Choosing Your Mode
+
+Signal supports two modes for consuming events. Choose based on your use case:
+
+### Jetstream Mode (Recommended)
+
+Best for most applications:
+
+```env
+SIGNAL_MODE=jetstream
+SIGNAL_JETSTREAM_URL=wss://jetstream2.us-east.bsky.network
+```
+
+**Advantages:**
+- Simplified JSON events (easy to work with)
+- Server-side collection filtering (efficient)
+- Lower bandwidth and processing overhead
+
+### Firehose Mode
+
+Best for comprehensive indexing and raw data access:
+
+```env
+SIGNAL_MODE=firehose
+SIGNAL_FIREHOSE_HOST=bsky.network
+```
+
+**Advantages:**
+- Access to raw CBOR/CAR data
+- Full AT Protocol event stream
+- Complete control over event processing
+
+**Trade-offs:**
+- Client-side filtering only (higher bandwidth)
+- More processing overhead
+
+[Learn more about choosing the right mode →](modes.md)
+
+## Verify Installation
+
+Check that Signal is installed correctly:
+
+```bash
+php artisan signal:list
+```
+
+This should display available Signals (initially none until you create them).
+
+## Next Steps
+
+Now that Signal is installed, you're ready to start building:
+
+1. **[Create your first Signal →](quickstart.md)**
+2. **[Learn about Signal architecture →](signals.md)**
+3. **[Understand filtering options →](filtering.md)**
+
+## Troubleshooting
+
+### Migration Already Exists
+
+If you see "migration already exists" when running `signal:install`, you've likely already installed Signal. You can safely skip this step.
+
+### WebSocket Connection Issues
+
+If you experience WebSocket connection issues:
+
+1. Verify your firewall allows WebSocket connections
+2. Check that your hosting environment supports WebSockets
+3. Try switching Jetstream endpoints (US East vs US West)
+
+### Permission Errors
+
+If you encounter permission errors with cursor storage:
+
+- **Database mode**: Ensure database connection is configured correctly
+- **Redis mode**: Verify Redis connection is available
+- **File mode**: Check that Laravel has write permissions to `storage/app/signal/`
+
+## Uninstallation
+
+To remove Signal from your application:
+
+```bash
+# Remove the package
+composer remove socialdept/signal
+
+# Optionally, rollback migrations
+php artisan migrate:rollback
+```
+
+You can also manually delete:
+- `config/signal.php`
+- `app/Signals/` directory
+- Signal-related migrations

docs/modes.md

···
+# Jetstream vs Firehose
+
+Signal supports two modes for consuming AT Protocol events. Understanding the differences is crucial for building efficient, scalable applications.
+
+## Quick Comparison
+
+| Feature          | Jetstream         | Firehose               |
+|------------------|-------------------|------------------------|
+| **Event Format** | Simplified JSON   | Raw CBOR/CAR           |
+| **Filtering**    | Server-side       | Client-side            |
+| **Bandwidth**    | Lower             | Higher                 |
+| **Processing**   | Lighter           | Heavier                |
+| **Best For**     | Most applications | Comprehensive indexing |
+
+## Jetstream Mode
+
+Jetstream is a **simplified, JSON-based event stream** built on top of the AT Protocol Firehose.
+    
+### When to Use Jetstream
+
+Choose Jetstream if you're:
+
+- Building production applications where efficiency matters
+- Concerned about bandwidth and server costs
+- Processing high volumes of events
+- Want server-side filtering for reduced bandwidth
+
+### Configuration
+
+Set Jetstream as your mode in `.env`:
+
+```env
+SIGNAL_MODE=jetstream
+SIGNAL_JETSTREAM_URL=wss://jetstream2.us-east.bsky.network
+```
+
+### Available Endpoints
+
+Jetstream has multiple regional endpoints:
+
+**US East (Default):**
+```env
+SIGNAL_JETSTREAM_URL=wss://jetstream2.us-east.bsky.network
+```
+
+**US West:**
+```env
+SIGNAL_JETSTREAM_URL=wss://jetstream1.us-west.bsky.network
+```
+
+Choose the endpoint closest to your server for best performance.
+
+### Advantages
+
+**1. Simplified JSON Format**
+
+Events arrive as clean JSON objects:
+
+```json
+{
+  "did": "did:plc:z72i7hdynmk6r22z27h6tvur",
+  "time_us": 1234567890,
+  "kind": "commit",
+  "commit": {
+    "rev": "abc123",
+    "operation": "create",
+    "collection": "app.bsky.feed.post",
+    "rkey": "3k2yihcrr2c2a",
+    "record": {
+      "text": "Hello World!",
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  }
+}
+```
+
+No complex parsing or decoding required.
+
+**2. Server-Side Filtering**
+
+Your collection filters are sent to Jetstream:
+
+```php
+public function collections(): ?array
+{
+    return ['app.bsky.feed.post', 'app.bsky.feed.like'];
+}
+```
+
+Jetstream only sends matching events, dramatically reducing bandwidth.
+
+**3. Lower Bandwidth**
+
+Only receive the events you care about:
+
+- **Jetstream**: Receive ~1,000 events/sec for specific collections
+- **Firehose**: Receive ~50,000 events/sec for everything
+
+**4. Lower Processing Overhead**
+
+JSON parsing is faster than CBOR/CAR decoding:
+
+- **Jetstream**: Simple JSON deserialization
+- **Firehose**: Complex CBOR/CAR decoding with `revolution/laravel-bluesky`
+
+### Limitations
+
+**1. Client-Side Wildcards**
+
+Wildcard patterns work client-side only:
+
+```php
+public function collections(): ?array
+{
+    return ['app.bsky.feed.*']; // Still receives all collections
+}
+```
+
+The wildcard matching happens in your app, not on the server.
+
+### Example Configuration
+
+```php
+// config/signal.php
+return [
+    'mode' => env('SIGNAL_MODE', 'jetstream'),
+
+    'jetstream' => [
+        'websocket_url' => env(
+            'SIGNAL_JETSTREAM_URL',
+            'wss://jetstream2.us-east.bsky.network'
+        ),
+    ],
+];
+```
+
+## Firehose Mode
+
+Firehose is the **raw AT Protocol event stream** with comprehensive support for all collections.
+
+### When to Use Firehose
+
+Choose Firehose if you're:
+
+- Building comprehensive indexing systems
+- Developing AT Protocol infrastructure
+- Need access to raw CBOR/CAR data
+- Prefer client-side filtering control
+
+### Configuration
+
+Set Firehose as your mode in `.env`:
+
+```env
+SIGNAL_MODE=firehose
+SIGNAL_FIREHOSE_HOST=bsky.network
+```
+
+### Advantages
+
+**1. Raw Event Access**
+
+Full access to raw AT Protocol data:
+
+```php
+public function handle(SignalEvent $event): void
+{
+    // Access raw CBOR/CAR data
+    $cid = $event->commit->cid;
+    $blocks = $event->commit->blocks;
+}
+```
+
+**2. Comprehensive Events**
+
+Every event from the AT Protocol network arrives:
+
+- All collections (standard and custom)
+- All operations (create, update, delete)
+- All metadata and context
+- Complete repository commits
+
+**3. Complete Control**
+
+Full access to raw AT Protocol data:
+
+- CID (Content Identifiers)
+- Block structures
+- CAR file data
+- Complete repository commits
+
+### Trade-offs
+
+**1. Client-Side Filtering**
+
+All filtering happens in your application:
+
+```php
+public function collections(): ?array
+{
+    return ['app.bsky.feed.post']; // Still receives all events
+}
+```
+
+Your app receives everything and filters locally.
+
+**2. Higher Bandwidth**
+
+Receive the full event stream:
+
+- **~50,000+ events per second** during peak times
+- **~10-50 MB/s** of data throughput
+- Requires adequate network capacity
+
+**3. More Processing Overhead**
+
+Complex CBOR/CAR decoding:
+
+```php
+// Signal automatically handles decoding using revolution/laravel-bluesky
+$record = $event->getRecord(); // Decoded from CBOR/CAR
+```
+
+Processing is more CPU-intensive than Jetstream's JSON.
+
+**4. Requires revolution/laravel-bluesky**
+
+Firehose mode depends on the `revolution/laravel-bluesky` package for decoding:
+
+```bash
+composer require revolution/bluesky
+```
+
+Signal handles this dependency automatically.
+
+### Example Configuration
+
+```php
+// config/signal.php
+return [
+    'mode' => env('SIGNAL_MODE', 'jetstream'),
+
+    'firehose' => [
+        'host' => env('SIGNAL_FIREHOSE_HOST', 'bsky.network'),
+    ],
+];
+```
+
+The WebSocket URL is constructed as:
+```
+wss://{host}/xrpc/com.atproto.sync.subscribeRepos
+```
+
+## Choosing the Right Mode
+
+### Decision Tree
+
+```
+Do you need raw CBOR/CAR access?
+├─ Yes → Use Firehose
+└─ No
+    │
+    Do you want server-side filtering?
+    ├─ Yes → Use Jetstream (recommended)
+    └─ No → Use Firehose
+```
+
+### Use Case Examples
+
+**Social Media Analytics (Jetstream)**
+
+```php
+// Efficient monitoring with server-side filtering
+public function collections(): ?array
+{
+    return [
+        'app.bsky.feed.post',
+        'app.bsky.feed.like',
+        'app.bsky.graph.follow',
+    ];
+}
+```
+
+**Content Moderation (Jetstream)**
+
+```php
+// Standard content monitoring
+public function collections(): ?array
+{
+    return ['app.bsky.feed.*'];
+}
+```
+
+**Comprehensive Indexer (Firehose)**
+
+```php
+// Index everything with raw data access
+public function collections(): ?array
+{
+    return null; // All collections
+}
+```
+
+## Switching Between Modes
+
+You can switch modes without code changes:
+
+### Option 1: Environment Variable
+
+```env
+# Development - comprehensive testing
+SIGNAL_MODE=firehose
+
+# Production - efficient processing
+SIGNAL_MODE=jetstream
+```
+
+### Option 2: Runtime Configuration
+
+```php
+use SocialDept\Signal\Facades\Signal;
+
+// Set mode dynamically
+config(['signal.mode' => 'jetstream']);
+
+Signal::start();
+```
+
+## Performance Comparison
+
+### Bandwidth Usage
+
+**Processing 1 hour of posts:**
+
+| Mode      | Data Received     | Bandwidth |
+|-----------|-------------------|-----------|
+| Jetstream | ~50,000 events    | ~10 MB    |
+| Firehose  | ~5,000,000 events | ~500 MB   |
+
+**Savings:** 50x reduction with Jetstream
+
+### CPU Usage
+
+**Processing same events:**
+
+| Mode      | CPU Usage | Processing Time |
+|-----------|-----------|-----------------|
+| Jetstream | ~5%       | 0.1ms per event |
+| Firehose  | ~20%      | 0.4ms per event |
+
+**Savings:** 4x more efficient with Jetstream
+
+### Cost Implications
+
+For a medium-traffic application:
+
+| Mode      | Monthly Bandwidth | Est. Cost* |
+|-----------|-------------------|------------|
+| Jetstream | ~20 GB            | ~$2        |
+| Firehose  | ~10 TB            | ~$1000     |
+
+*Estimates vary by provider and usage
+
+## Best Practices
+
+### Start with Jetstream
+
+Start with Jetstream for most applications:
+
+```env
+SIGNAL_MODE=jetstream
+```
+
+Switch to Firehose only if you need raw CBOR/CAR access.
+
+### Use Firehose for Development
+
+Test with Firehose in development to see all events:
+
+```env
+# .env.local
+SIGNAL_MODE=firehose
+
+# .env.production
+SIGNAL_MODE=jetstream
+```
+
+### Monitor Performance
+
+Track your Signal's performance:
+
+```php
+public function handle(SignalEvent $event): void
+{
+    $start = microtime(true);
+
+    // Your logic
+
+    $duration = microtime(true) - $start;
+
+    if ($duration > 0.1) {
+        Log::warning('Slow signal processing', [
+            'signal' => static::class,
+            'duration' => $duration,
+            'mode' => config('signal.mode'),
+        ]);
+    }
+}
+```
+
+### Use Queues with Firehose
+
+Firehose generates high volume. Use queues to avoid blocking:
+
+```php
+public function shouldQueue(): bool
+{
+    // Queue when using Firehose
+    return config('signal.mode') === 'firehose';
+}
+```
+
+[Learn more about queue integration →](queues.md)
+
+## Testing Both Modes
+
+Test your Signals work in both modes:
+
+```bash
+# Test with Jetstream
+SIGNAL_MODE=jetstream php artisan signal:test MySignal
+
+# Test with Firehose
+SIGNAL_MODE=firehose php artisan signal:test MySignal
+```
+
+[Learn more about testing →](testing.md)
+
+## Common Questions
+
+### Can I use both modes simultaneously?
+
+No, each consumer runs in one mode. However, you can run multiple consumers:
+
+```bash
+# Terminal 1 - Jetstream consumer
+SIGNAL_MODE=jetstream php artisan signal:consume
+
+# Terminal 2 - Firehose consumer
+SIGNAL_MODE=firehose php artisan signal:consume
+```
+
+### Will my Signals break if I switch modes?
+
+Signals work in both modes without changes. The main difference is:
+- Jetstream provides server-side filtering (more efficient)
+- Firehose provides raw CBOR/CAR data access (more comprehensive)
+
+### How do I know which mode I'm using?
+
+Check at runtime:
+
+```php
+$mode = config('signal.mode'); // 'jetstream' or 'firehose'
+```
+
+Or via Facade:
+
+```php
+use SocialDept\Signal\Facades\Signal;
+
+$mode = Signal::getMode();
+```
+
+### Can I switch modes while consuming?
+
+No, you must restart the consumer:
+
+```bash
+# Stop current consumer (Ctrl+C)
+
+# Change mode
+# Edit .env: SIGNAL_MODE=firehose
+
+# Start new consumer
+php artisan signal:consume
+```
+
+## Next Steps
+
+- **[Learn about queue integration →](queues.md)** - Handle high-volume events efficiently
+- **[Review configuration options →](configuration.md)** - Fine-tune your setup
+- **[See real-world examples →](examples.md)** - Learn from production patterns

docs/queues.md

···
+# Queue Integration
+
+Processing AT Protocol events can be resource-intensive. Signal's queue integration lets you handle events asynchronously, preventing bottlenecks and improving performance.
+
+## Why Use Queues?
+
+### Without Queues (Synchronous)
+
+```php
+public function handle(SignalEvent $event): void
+{
+    $this->performExpensiveAnalysis($event);  // Blocks for 2 seconds
+    $this->sendNotifications($event);          // Blocks for 1 second
+    $this->updateDatabase($event);             // Blocks for 0.5 seconds
+}
+```
+
+**Problems:**
+- Consumer blocks while processing (3.5 seconds per event)
+- Events queue up during slow operations
+- Risk of disconnection during long processing
+- Can't scale horizontally
+- Memory issues with long-running processes
+
+### With Queues (Asynchronous)
+
+```php
+public function shouldQueue(): bool
+{
+    return true;
+}
+
+public function handle(SignalEvent $event): void
+{
+    $this->performExpensiveAnalysis($event);  // Runs in background
+    $this->sendNotifications($event);          // Runs in background
+    $this->updateDatabase($event);             // Runs in background
+}
+```
+
+**Benefits:**
+- Consumer stays responsive
+- Processing happens in parallel
+- Scale by adding queue workers
+- Better memory management
+- Automatic retry on failures
+
+## Basic Queue Configuration
+
+### Enable Queueing
+
+Simply return `true` from `shouldQueue()`:
+
+```php
+class MySignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function shouldQueue(): bool
+    {
+        return true; // Enable queuing
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        // This now runs in a queue job
+    }
+}
+```
+
+That's it! Signal automatically:
+- Creates a queue job for each event
+- Serializes the event data
+- Dispatches to Laravel's queue system
+- Handles retries and failures
+
+### Default Queue Configuration
+
+Signal uses your Laravel queue configuration:
+
+```env
+# Default queue connection
+QUEUE_CONNECTION=redis
+
+# Signal-specific queue (optional)
+SIGNAL_QUEUE=signal
+
+# Signal queue connection (optional)
+SIGNAL_QUEUE_CONNECTION=redis
+```
+
+## Customizing Queue Behavior
+
+### Specify Queue Name
+
+Send events to a specific queue:
+
+```php
+public function shouldQueue(): bool
+{
+    return true;
+}
+
+public function queue(): string
+{
+    return 'high-priority'; // Queue name
+}
+```
+
+Now your events go to the `high-priority` queue:
+
+```bash
+php artisan queue:work --queue=high-priority
+```
+
+### Specify Queue Connection
+
+Use a different queue connection:
+
+```php
+public function shouldQueue(): bool
+{
+    return true;
+}
+
+public function queueConnection(): string
+{
+    return 'redis'; // Connection name
+}
+```
+
+### Combine Queue Configuration
+
+```php
+public function shouldQueue(): bool
+{
+    return true;
+}
+
+public function queueConnection(): string
+{
+    return 'redis';
+}
+
+public function queue(): string
+{
+    return 'signal-events';
+}
+```
+
+## Running Queue Workers
+
+### Start a Worker
+
+Process queued events:
+
+```bash
+php artisan queue:work
+```
+
+### Process Specific Queue
+
+```bash
+php artisan queue:work --queue=signal
+```
+
+### Multiple Queues with Priority
+
+Process high-priority queue first:
+
+```bash
+php artisan queue:work --queue=high-priority,default
+```
+
+### Scale with Multiple Workers
+
+Run multiple workers for throughput:
+
+```bash
+# Terminal 1
+php artisan queue:work --queue=signal
+
+# Terminal 2
+php artisan queue:work --queue=signal
+
+# Terminal 3
+php artisan queue:work --queue=signal
+```
+
+### Supervisor Configuration
+
+For production, use Supervisor to manage workers:
+
+```ini
+[program:signal-queue-worker]
+process_name=%(program_name)s_%(process_num)02d
+command=php /path/to/artisan queue:work --sleep=3 --tries=3 --queue=signal
+autostart=true
+autorestart=true
+stopasgroup=true
+killasgroup=true
+user=www-data
+numprocs=4
+redirect_stderr=true
+stdout_logfile=/path/to/logs/signal-worker.log
+stopwaitsecs=3600
+```
+
+This creates 4 workers processing the `signal` queue.
+
+## Error Handling
+
+### Failed Method
+
+Handle job failures:
+
+```php
+public function shouldQueue(): bool
+{
+    return true;
+}
+
+public function handle(SignalEvent $event): void
+{
+    // Your logic that might fail
+    $this->riskyOperation($event);
+}
+
+public function failed(SignalEvent $event, \Throwable $exception): void
+{
+    Log::error('Signal processing failed', [
+        'signal' => static::class,
+        'did' => $event->did,
+        'collection' => $event->getCollection(),
+        'error' => $exception->getMessage(),
+        'trace' => $exception->getTraceAsString(),
+    ]);
+
+    // Optional: Send alerts
+    $this->notifyAdmin($exception);
+
+    // Optional: Store for manual review
+    FailedSignal::create([
+        'event_data' => $event->toArray(),
+        'exception' => $exception->getMessage(),
+    ]);
+}
+```
+
+### Automatic Retries
+
+Laravel automatically retries failed jobs:
+
+```bash
+# Retry up to 3 times
+php artisan queue:work --tries=3
+```
+
+Configure retry delay:
+
+```php
+public function retryAfter(): int
+{
+    return 60; // Wait 60 seconds before retry
+}
+```
+
+### Exponential Backoff
+
+Increase delay between retries:
+
+```php
+public function backoff(): array
+{
+    return [10, 30, 60]; // 10s, then 30s, then 60s
+}
+```
+
+## Performance Optimization
+
+### Batch Processing
+
+Process multiple events at once:
+
+```php
+use Illuminate\Support\Collection;
+
+class BatchPostSignal extends Signal
+{
+    public function shouldQueue(): bool
+{
+        return true;
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        // Collect events in cache
+        $events = Cache::get('pending_posts', []);
+        $events[] = $event->toArray();
+
+        Cache::put('pending_posts', $events, now()->addMinutes(5));
+
+        // Process in batches of 100
+        if (count($events) >= 100) {
+            $this->processBatch($events);
+            Cache::forget('pending_posts');
+        }
+    }
+
+    private function processBatch(array $events): void
+    {
+        // Bulk insert, API calls, etc.
+    }
+}
+```
+
+### Conditional Queuing
+
+Queue only expensive operations:
+
+```php
+public function shouldQueue(): bool
+{
+    // Queue during high traffic
+    return now()->hour >= 9 && now()->hour <= 17;
+}
+```
+
+Or based on event type:
+
+```php
+public function handle(SignalEvent $event): void
+{
+    if ($this->isExpensive($event)) {
+        dispatch(function () use ($event) {
+            $this->handleExpensive($event);
+        })->onQueue('slow-operations');
+    } else {
+        $this->handleQuick($event);
+    }
+}
+```
+
+### Rate Limiting
+
+Prevent overwhelming external APIs:
+
+```php
+use Illuminate\Support\Facades\RateLimiter;
+
+public function handle(SignalEvent $event): void
+{
+    RateLimiter::attempt(
+        'api-calls',
+        $perMinute = 100,
+        function () use ($event) {
+            $this->callExternalAPI($event);
+        }
+    );
+}
+```
+
+## Common Patterns
+
+### High-Volume Signal
+
+Process millions of events efficiently:
+
+```php
+class HighVolumeSignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function collections(): ?array
+    {
+        return ['app.bsky.feed.post'];
+    }
+
+    public function shouldQueue(): bool
+    {
+        return true;
+    }
+
+    public function queue(): string
+    {
+        return 'high-volume';
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        // Lightweight processing only
+        $this->incrementCounter($event);
+    }
+}
+```
+
+Run many workers:
+
+```bash
+# 10 workers on high-volume queue
+php artisan queue:work --queue=high-volume --workers=10
+```
+
+### Priority Queues
+
+Different priorities for different events:
+
+```php
+class PrioritySignal extends Signal
+{
+    public function shouldQueue(): bool
+    {
+        return true;
+    }
+
+    public function queue(): string
+    {
+        // Determine priority based on event
+        return $this->getQueueForEvent();
+    }
+
+    private function getQueueForEvent(): string
+    {
+        // Check event attributes
+        // Return 'high', 'medium', or 'low'
+    }
+}
+```
+
+Process high-priority first:
+
+```bash
+php artisan queue:work --queue=high,medium,low
+```
+
+### Delayed Processing
+
+Delay event processing:
+
+```php
+public function handle(SignalEvent $event): void
+{
+    // Dispatch with delay
+    dispatch(function () use ($event) {
+        $this->processLater($event);
+    })->delay(now()->addMinutes(5));
+}
+```
+
+### Scheduled Batch Processing
+
+Collect events and process on schedule:
+
+```php
+// Signal collects events
+class CollectorSignal extends Signal
+{
+    public function handle(SignalEvent $event): void
+    {
+        PendingEvent::create([
+            'data' => $event->toArray(),
+        ]);
+    }
+}
+
+// Scheduled command processes batch
+// app/Console/Kernel.php
+protected function schedule(Schedule $schedule)
+{
+    $schedule->call(function () {
+        $events = PendingEvent::all();
+        $this->processBatch($events);
+        PendingEvent::truncate();
+    })->hourly();
+}
+```
+
+## Monitoring Queues
+
+### Check Queue Status
+
+```bash
+# View failed jobs
+php artisan queue:failed
+
+# Retry failed job
+php artisan queue:retry {id}
+
+# Retry all failed
+php artisan queue:retry all
+
+# Clear failed jobs
+php artisan queue:flush
+```
+
+### Queue Metrics
+
+Track queue performance:
+
+```php
+use Illuminate\Support\Facades\Queue;
+
+Queue::after(function ($connection, $job, $data) {
+    Log::info('Job processed', [
+        'queue' => $job->queue,
+        'class' => $job->resolveName(),
+        'attempts' => $job->attempts(),
+    ]);
+});
+```
+
+### Horizon (Recommended)
+
+Use Laravel Horizon for Redis queues:
+
+```bash
+composer require laravel/horizon
+php artisan horizon:install
+php artisan horizon
+```
+
+View dashboard at `/horizon`.
+
+## Testing Queued Signals
+
+### Test with Fake Queue
+
+```php
+use Illuminate\Support\Facades\Queue;
+
+/** @test */
+public function it_queues_events()
+{
+    Queue::fake();
+
+    $signal = new MySignal();
+    $event = $this->createSampleEvent();
+
+    // Assert queue behavior
+    $this->assertTrue($signal->shouldQueue());
+
+    // Process would normally queue
+    $signal->handle($event);
+
+    // Verify job was queued
+    Queue::assertPushed(SignalJob::class);
+}
+```
+
+### Test Synchronously
+
+Disable queueing for tests:
+
+```php
+/** @test */
+public function it_processes_events()
+{
+    config(['queue.default' => 'sync']);
+
+    $signal = new MySignal();
+    $event = $this->createSampleEvent();
+
+    $signal->handle($event);
+
+    // Assert processing happened
+    $this->assertDatabaseHas('posts', [...]);
+}
+```
+
+[Learn more about testing →](testing.md)
+
+## Production Checklist
+
+### Infrastructure
+
+- [ ] Queue driver configured (Redis recommended)
+- [ ] Supervisor installed and configured
+- [ ] Multiple workers running
+- [ ] Worker auto-restart enabled
+- [ ] Logs configured and monitored
+
+### Configuration
+
+- [ ] Queue connection set correctly
+- [ ] Queue names configured
+- [ ] Retry attempts configured
+- [ ] Timeout values appropriate
+- [ ] Memory limits set
+
+### Monitoring
+
+- [ ] Queue length monitored
+- [ ] Failed jobs tracked
+- [ ] Worker health checked
+- [ ] Processing times measured
+- [ ] Horizon installed (if using Redis)
+
+### Scaling
+
+- [ ] Worker count appropriate for volume
+- [ ] Priority queues configured
+- [ ] Rate limiting implemented
+- [ ] Database connection pooling enabled
+- [ ] Redis maxmemory policy set
+
+## Common Issues
+
+### Queue Jobs Not Processing
+
+**Check worker is running:**
+```bash
+php artisan queue:work
+```
+
+**Check queue connection:**
+```php
+// Should match QUEUE_CONNECTION
+config('queue.default')
+```
+
+### Jobs Timing Out
+
+**Increase timeout:**
+```bash
+php artisan queue:work --timeout=300
+```
+
+**Or in Signal:**
+```php
+public function timeout(): int
+{
+    return 300; // 5 minutes
+}
+```
+
+### Memory Leaks
+
+**Restart workers periodically:**
+```bash
+php artisan queue:work --max-jobs=1000
+```
+
+Or:
+```bash
+php artisan queue:work --max-time=3600
+```
+
+### Failed Jobs Piling Up
+
+**Review failures:**
+```bash
+php artisan queue:failed
+```
+
+**Retry or delete:**
+```bash
+php artisan queue:retry all
+# or
+php artisan queue:flush
+```
+
+## Next Steps
+
+- **[Review configuration options →](configuration.md)** - Fine-tune queue settings
+- **[Learn about testing →](testing.md)** - Test queued Signals
+- **[See real-world examples →](examples.md)** - Learn from production queue patterns

docs/quickstart.md

···
+# Quickstart Guide
+
+This guide will walk you through building your first Signal and consuming AT Protocol events in under 5 minutes.
+
+## Prerequisites
+
+Before starting, ensure you have:
+
+- [Installed Signal](installation.md) in your Laravel application
+- Run `php artisan signal:install` successfully
+- Basic familiarity with Laravel
+
+## Your First Signal
+
+We'll build a Signal that logs every new post created on Bluesky.
+
+### Step 1: Generate a Signal
+
+Use the Artisan command to create a new Signal:
+
+```bash
+php artisan make:signal NewPostSignal
+```
+
+This creates `app/Signals/NewPostSignal.php` with a basic template.
+
+### Step 2: Define the Signal
+
+Open the generated file and update it:
+
+```php
+<?php
+
+namespace App\Signals;
+
+use SocialDept\Signal\Events\SignalEvent;
+use SocialDept\Signal\Signals\Signal;
+use Illuminate\Support\Facades\Log;
+
+class NewPostSignal extends Signal
+{
+    /**
+     * Define which event types to listen for.
+     */
+    public function eventTypes(): array
+    {
+        return ['commit']; // Listen for repository commits
+    }
+
+    /**
+     * Filter by specific collections.
+     */
+    public function collections(): ?array
+    {
+        return ['app.bsky.feed.post']; // Only handle posts
+    }
+
+    /**
+     * Handle the event when it arrives.
+     */
+    public function handle(SignalEvent $event): void
+    {
+        $record = $event->getRecord();
+
+        Log::info('New post created', [
+            'author' => $event->did,
+            'text' => $record->text ?? null,
+            'created_at' => $record->createdAt ?? null,
+        ]);
+    }
+}
+```
+
+### Step 3: Start Consuming Events
+
+Run the consumer to start listening:
+
+```bash
+php artisan signal:consume
+```
+
+You should see output like:
+
+```
+Starting Signal consumer in jetstream mode...
+Connecting to wss://jetstream2.us-east.bsky.network...
+Connected! Listening for events...
+```
+
+**Congratulations!** Your Signal is now processing every new post on Bluesky in real-time. Check your Laravel logs to see the posts coming in.
+
+## Understanding What Just Happened
+
+Let's break down the Signal you created:
+
+### Event Types
+
+```php
+public function eventTypes(): array
+{
+    return ['commit'];
+}
+```
+
+This tells Signal you want **commit** events, which represent changes to repositories (like creating posts, likes, follows, etc.).
+
+Available event types:
+- `commit` - Repository commits (most common)
+- `identity` - Identity changes (handle updates)
+- `account` - Account status changes
+
+### Collections
+
+```php
+public function collections(): ?array
+{
+    return ['app.bsky.feed.post'];
+}
+```
+
+This filters to only **post** collections. Without this filter, your Signal would receive all commit events for every collection type.
+
+Common collections:
+- `app.bsky.feed.post` - Posts
+- `app.bsky.feed.like` - Likes
+- `app.bsky.graph.follow` - Follows
+- `app.bsky.feed.repost` - Reposts
+
+[Learn more about filtering →](filtering.md)
+
+### Handler Method
+
+```php
+public function handle(SignalEvent $event): void
+{
+    $record = $event->getRecord();
+    // Your logic here
+}
+```
+
+This is where your code runs for each matching event. The `$event` object contains:
+
+- `did` - The user's DID (decentralized identifier)
+- `timeUs` - Timestamp in microseconds
+- `commit` - Commit details (collection, operation, record key)
+- `getRecord()` - The actual record data
+
+## Next Steps
+
+Now that you've built your first Signal, let's make it more useful.
+
+### Add More Filtering
+
+Track specific operations only:
+
+```php
+use SocialDept\Signal\Enums\SignalCommitOperation;
+
+public function operations(): ?array
+{
+    return [SignalCommitOperation::Create]; // Only new posts, not edits
+}
+```
+
+[Learn more about filtering →](filtering.md)
+
+### Process Events Asynchronously
+
+For expensive operations, use Laravel queues:
+
+```php
+public function shouldQueue(): bool
+{
+    return true;
+}
+
+public function handle(SignalEvent $event): void
+{
+    // This now runs in a background job
+    $this->performExpensiveAnalysis($event);
+}
+```
+
+[Learn more about queues →](queues.md)
+
+### Store Data
+
+Let's store posts in your database:
+
+```php
+use App\Models\Post;
+
+public function handle(SignalEvent $event): void
+{
+    $record = $event->getRecord();
+
+    Post::updateOrCreate(
+        [
+            'did' => $event->did,
+            'rkey' => $event->commit->rkey,
+        ],
+        [
+            'text' => $record->text ?? null,
+            'created_at' => $record->createdAt,
+        ]
+    );
+}
+```
+
+### Handle Multiple Collections
+
+Use wildcards to match multiple collections:
+
+```php
+public function collections(): ?array
+{
+    return [
+        'app.bsky.feed.*', // All feed events
+    ];
+}
+
+public function handle(SignalEvent $event): void
+{
+    $collection = $event->getCollection();
+
+    match ($collection) {
+        'app.bsky.feed.post' => $this->handlePost($event),
+        'app.bsky.feed.like' => $this->handleLike($event),
+        'app.bsky.feed.repost' => $this->handleRepost($event),
+        default => null,
+    };
+}
+```
+
+## Building Something Real
+
+Let's build a simple engagement tracker:
+
+```php
+<?php
+
+namespace App\Signals;
+
+use App\Models\EngagementMetric;
+use SocialDept\Signal\Enums\SignalCommitOperation;
+use SocialDept\Signal\Events\SignalEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class EngagementTrackerSignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function collections(): ?array
+    {
+        return [
+            'app.bsky.feed.post',
+            'app.bsky.feed.like',
+            'app.bsky.feed.repost',
+        ];
+    }
+
+    public function operations(): ?array
+    {
+        return [SignalCommitOperation::Create];
+    }
+
+    public function shouldQueue(): bool
+    {
+        return true; // Process in background
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        EngagementMetric::create([
+            'date' => now()->toDateString(),
+            'collection' => $event->getCollection(),
+            'event_type' => 'create',
+            'count' => 1,
+        ]);
+    }
+}
+```
+
+This Signal tracks all engagement activity (posts, likes, reposts) and stores metrics for analysis.
+
+## Testing Your Signal
+
+Before running in production, test your Signal with sample data:
+
+```bash
+php artisan signal:test NewPostSignal
+```
+
+This will run your Signal with a sample event and show you the output.
+
+[Learn more about testing →](testing.md)
+
+## Common Patterns
+
+### Only Process Specific Users
+
+```php
+public function dids(): ?array
+{
+    return [
+        'did:plc:z72i7hdynmk6r22z27h6tvur', // Specific user
+    ];
+}
+```
+
+### Add Custom Filtering Logic
+
+```php
+public function shouldHandle(SignalEvent $event): bool
+{
+    $record = $event->getRecord();
+
+    // Only handle posts with images
+    return isset($record->embed);
+}
+```
+
+### Handle Failures Gracefully
+
+```php
+public function failed(SignalEvent $event, \Throwable $exception): void
+{
+    Log::error('Signal processing failed', [
+        'event' => $event->toArray(),
+        'error' => $exception->getMessage(),
+    ]);
+
+    // Optionally notify admins, store for retry, etc.
+}
+```
+
+## Running in Production
+
+### Using Supervisor
+
+For production, run Signal under a process monitor like Supervisor:
+
+```ini
+[program:signal-consumer]
+process_name=%(program_name)s
+command=php /path/to/artisan signal:consume
+autostart=true
+autorestart=true
+user=www-data
+redirect_stderr=true
+stdout_logfile=/path/to/logs/signal-consumer.log
+```
+
+### Starting from Last Position
+
+Signal automatically saves cursor positions, so it resumes from where it left off:
+
+```bash
+php artisan signal:consume
+```
+
+To start fresh and ignore stored position:
+
+```bash
+php artisan signal:consume --fresh
+```
+
+To start from a specific cursor:
+
+```bash
+php artisan signal:consume --cursor=123456789
+```
+
+## What's Next?
+
+You now know the basics of building Signals! Explore more advanced topics:
+
+- **[Signal Architecture](signals.md)** - Deep dive into Signal structure
+- **[Advanced Filtering](filtering.md)** - Master collection patterns and wildcards
+- **[Jetstream vs Firehose](modes.md)** - Choose the right mode for your use case
+- **[Queue Integration](queues.md)** - Build high-performance processors
+- **[Real-World Examples](examples.md)** - Learn from production use cases
+
+## Getting Help
+
+- Check the [examples documentation](examples.md) for more patterns
+- Review the [configuration guide](configuration.md) for all options
+- Open an issue on GitHub if you encounter problems

docs/signals.md

···
+# Creating Signals
+
+Signals are the heart of the Signal package. They define how your application responds to AT Protocol events.
+
+## What is a Signal?
+
+A **Signal** is a PHP class that:
+
+1. Listens for specific types of AT Protocol events
+2. Filters those events based on your criteria
+3. Executes custom logic when matching events arrive
+
+Think of Signals like Laravel event listeners, but specifically designed for the AT Protocol.
+
+## Basic Signal Structure
+
+Every Signal extends the base `Signal` class:
+
+```php
+<?php
+
+namespace App\Signals;
+
+use SocialDept\Signal\Events\SignalEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class MySignal extends Signal
+{
+    /**
+     * Define which event types to listen for.
+     * Required.
+     */
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    /**
+     * Handle the event when it arrives.
+     * Required.
+     */
+    public function handle(SignalEvent $event): void
+    {
+        // Your logic here
+    }
+}
+```
+
+Only two methods are required:
+- `eventTypes()` - Which event types to listen for
+- `handle()` - What to do when events arrive
+
+## Creating Signals
+
+### Using Artisan (Recommended)
+
+Generate a new Signal with the make command:
+
+```bash
+php artisan make:signal MySignal
+```
+
+This creates `app/Signals/MySignal.php` with a basic template.
+
+#### With Options
+
+Generate a Signal with pre-configured filters:
+
+```bash
+# Create a Signal for posts only
+php artisan make:signal PostSignal --type=commit --collection=app.bsky.feed.post
+
+# Create a Signal for follows
+php artisan make:signal FollowSignal --type=commit --collection=app.bsky.graph.follow
+```
+
+### Manual Creation
+
+You can also create Signals manually in `app/Signals/`:
+
+```php
+<?php
+
+namespace App\Signals;
+
+use SocialDept\Signal\Events\SignalEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class ManualSignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        //
+    }
+}
+```
+
+Signals are automatically discovered from `app/Signals/` - no registration needed.
+
+## Event Types
+
+Signals can listen for three types of AT Protocol events:
+
+### Commit Events
+
+Repository commits represent changes to user data:
+
+```php
+use SocialDept\Signal\Enums\SignalEventType;
+
+public function eventTypes(): array
+{
+    return [SignalEventType::Commit];
+    // Or: return ['commit'];
+}
+```
+
+**Common commit events:**
+- Creating posts, likes, follows, reposts
+- Updating profile information
+- Deleting content
+
+This is the most common event type and what you'll use 99% of the time.
+
+### Identity Events
+
+Identity changes track handle updates:
+
+```php
+public function eventTypes(): array
+{
+    return [SignalEventType::Identity];
+    // Or: return ['identity'];
+}
+```
+
+**Use cases:**
+- Tracking handle changes
+- Updating local user records
+- Monitoring account migrations
+
+### Account Events
+
+Account status changes track account state:
+
+```php
+public function eventTypes(): array
+{
+    return [SignalEventType::Account];
+    // Or: return ['account'];
+}
+```
+
+**Use cases:**
+- Detecting account deactivation
+- Monitoring account status
+- Compliance tracking
+
+### Multiple Event Types
+
+Listen to multiple event types in one Signal:
+
+```php
+public function eventTypes(): array
+{
+    return [
+        SignalEventType::Commit,
+        SignalEventType::Identity,
+    ];
+}
+
+public function handle(SignalEvent $event): void
+{
+    if ($event->isCommit()) {
+        // Handle commit
+    }
+
+    if ($event->isIdentity()) {
+        // Handle identity change
+    }
+}
+```
+
+## The SignalEvent Object
+
+The `SignalEvent` object contains all event data:
+
+### Common Properties
+
+```php
+public function handle(SignalEvent $event): void
+{
+    // User's DID (decentralized identifier)
+    $did = $event->did; // "did:plc:z72i7hdynmk6r22z27h6tvur"
+
+    // Event type (commit, identity, account)
+    $kind = $event->kind;
+
+    // Timestamp in microseconds
+    $timestamp = $event->timeUs;
+
+    // Convert to Carbon instance
+    $date = $event->getTimestamp();
+}
+```
+
+### Commit Events
+
+For commit events, access the `commit` property:
+
+```php
+public function handle(SignalEvent $event): void
+{
+    if ($event->isCommit()) {
+        // Collection (e.g., "app.bsky.feed.post")
+        $collection = $event->commit->collection;
+        // Or: $collection = $event->getCollection();
+
+        // Operation (create, update, delete)
+        $operation = $event->commit->operation;
+        // Or: $operation = $event->getOperation();
+
+        // Record key (unique identifier)
+        $rkey = $event->commit->rkey;
+
+        // Revision
+        $rev = $event->commit->rev;
+
+        // The actual record data
+        $record = $event->commit->record;
+        // Or: $record = $event->getRecord();
+    }
+}
+```
+
+### Working with Records
+
+Records contain the actual data (posts, likes, etc.):
+
+```php
+public function handle(SignalEvent $event): void
+{
+    $record = $event->getRecord();
+
+    // For posts (app.bsky.feed.post)
+    $text = $record->text ?? null;
+    $createdAt = $record->createdAt ?? null;
+    $embed = $record->embed ?? null;
+    $facets = $record->facets ?? null;
+
+    // For likes (app.bsky.feed.like)
+    $subject = $record->subject ?? null;
+
+    // For follows (app.bsky.graph.follow)
+    $subject = $record->subject ?? null;
+}
+```
+
+Records are `stdClass` objects, so use null coalescing (`??`) for safety.
+
+### Identity Events
+
+For identity events, access the `identity` property:
+
+```php
+public function handle(SignalEvent $event): void
+{
+    if ($event->isIdentity()) {
+        // New handle
+        $handle = $event->identity->handle;
+
+        // User's DID
+        $did = $event->did;
+
+        // Sequence number
+        $seq = $event->identity->seq;
+
+        // Timestamp
+        $time = $event->identity->time;
+    }
+}
+```
+
+### Account Events
+
+For account events, access the `account` property:
+
+```php
+public function handle(SignalEvent $event): void
+{
+    if ($event->isAccount()) {
+        // Account status
+        $active = $event->account->active; // true/false
+
+        // Status reason
+        $status = $event->account->status ?? null;
+
+        // User's DID
+        $did = $event->did;
+
+        // Sequence number
+        $seq = $event->account->seq;
+
+        // Timestamp
+        $time = $event->account->time;
+    }
+}
+```
+
+## Helper Methods
+
+Signals provide several helper methods for common tasks:
+
+### Type Checking
+
+```php
+public function handle(SignalEvent $event): void
+{
+    // Check event type
+    if ($event->isCommit()) {
+        //
+    }
+
+    if ($event->isIdentity()) {
+        //
+    }
+
+    if ($event->isAccount()) {
+        //
+    }
+}
+```
+
+### Operation Checking (Commit Events)
+
+```php
+use SocialDept\Signal\Enums\SignalCommitOperation;
+
+public function handle(SignalEvent $event): void
+{
+    $operation = $event->getOperation();
+
+    // Using enum
+    if ($operation === SignalCommitOperation::Create) {
+        // Handle new records
+    }
+
+    // Using commit helper
+    if ($event->commit->isCreate()) {
+        // Handle new records
+    }
+
+    if ($event->commit->isUpdate()) {
+        // Handle updates
+    }
+
+    if ($event->commit->isDelete()) {
+        // Handle deletions
+    }
+}
+```
+
+### Data Extraction
+
+```php
+public function handle(SignalEvent $event): void
+{
+    // Get collection (commit events only)
+    $collection = $event->getCollection();
+
+    // Get operation (commit events only)
+    $operation = $event->getOperation();
+
+    // Get record (commit events only)
+    $record = $event->getRecord();
+
+    // Get timestamp as Carbon
+    $timestamp = $event->getTimestamp();
+
+    // Convert to array
+    $array = $event->toArray();
+}
+```
+
+## Optional Signal Methods
+
+Signals support several optional methods for advanced behavior:
+
+### Collections Filter
+
+Filter by AT Protocol collections:
+
+```php
+public function collections(): ?array
+{
+    return ['app.bsky.feed.post'];
+}
+```
+
+Return `null` to handle all collections.
+
+[Learn more about collection filtering →](filtering.md)
+
+### Operations Filter
+
+Filter by operation type (commit events only):
+
+```php
+public function operations(): ?array
+{
+    return [SignalCommitOperation::Create];
+}
+```
+
+Return `null` to handle all operations.
+
+[Learn more about operation filtering →](filtering.md)
+
+### DIDs Filter
+
+Filter by specific users:
+
+```php
+public function dids(): ?array
+{
+    return [
+        'did:plc:z72i7hdynmk6r22z27h6tvur',
+    ];
+}
+```
+
+Return `null` to handle all users.
+
+[Learn more about DID filtering →](filtering.md)
+
+### Custom Filtering
+
+Add complex filtering logic:
+
+```php
+public function shouldHandle(SignalEvent $event): bool
+{
+    // Only handle posts with images
+    if ($event->isCommit() && $event->getCollection() === 'app.bsky.feed.post') {
+        $record = $event->getRecord();
+        return isset($record->embed);
+    }
+
+    return true;
+}
+```
+
+### Queue Configuration
+
+Process events asynchronously:
+
+```php
+public function shouldQueue(): bool
+{
+    return true;
+}
+
+public function queue(): string
+{
+    return 'high-priority';
+}
+
+public function queueConnection(): string
+{
+    return 'redis';
+}
+```
+
+[Learn more about queue integration →](queues.md)
+
+### Failure Handling
+
+Handle processing failures:
+
+```php
+public function failed(SignalEvent $event, \Throwable $exception): void
+{
+    Log::error('Signal failed', [
+        'signal' => static::class,
+        'event' => $event->toArray(),
+        'error' => $exception->getMessage(),
+    ]);
+}
+```
+
+## Signal Lifecycle
+
+Understanding the Signal lifecycle helps you write better Signals:
+
+### 1. Event Arrives
+
+An event arrives from the AT Protocol (via Jetstream or Firehose).
+
+### 2. Event Type Matching
+
+Signal checks if the event type matches your `eventTypes()` definition.
+
+### 3. Collection Filtering
+
+If defined, Signal checks if the collection matches your `collections()` definition.
+
+### 4. Operation Filtering
+
+If defined, Signal checks if the operation matches your `operations()` definition.
+
+### 5. DID Filtering
+
+If defined, Signal checks if the DID matches your `dids()` definition.
+
+### 6. Custom Filtering
+
+If defined, Signal calls your `shouldHandle()` method.
+
+### 7. Queue Decision
+
+Signal checks `shouldQueue()` to determine if the event should be queued.
+
+### 8. Handler Execution
+
+Your `handle()` method is called (either synchronously or via queue).
+
+### 9. Failure Handling (if applicable)
+
+If an exception occurs, your `failed()` method is called (if defined).
+
+## Best Practices
+
+### Keep Handlers Focused
+
+Each Signal should do one thing well:
+
+```php
+// Good - focused on one task
+class TrackNewPostsSignal extends Signal
+{
+    public function collections(): ?array
+    {
+        return ['app.bsky.feed.post'];
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        $this->storePost($event);
+    }
+}
+
+// Less ideal - doing too much
+class MonitorEverythingSignal extends Signal
+{
+    public function handle(SignalEvent $event): void
+    {
+        $this->storePost($event);
+        $this->sendNotification($event);
+        $this->updateAnalytics($event);
+        $this->processRecommendations($event);
+    }
+}
+```
+
+### Use Queues for Heavy Work
+
+Don't block the consumer with expensive operations:
+
+```php
+class AnalyzePostSignal extends Signal
+{
+    public function shouldQueue(): bool
+    {
+        return true; // Process in background
+    }
+
+    public function handle(SignalEvent $event): void
+    {
+        $this->performExpensiveAnalysis($event);
+    }
+}
+```
+
+### Validate Data Safely
+
+Records can have missing or unexpected data:
+
+```php
+public function handle(SignalEvent $event): void
+{
+    $record = $event->getRecord();
+
+    // Use null coalescing
+    $text = $record->text ?? '';
+
+    // Validate before processing
+    if (empty($text)) {
+        return;
+    }
+
+    // Safe to process
+    $this->processText($text);
+}
+```
+
+### Add Logging
+
+Log important events for debugging:
+
+```php
+public function handle(SignalEvent $event): void
+{
+    Log::debug('Processing event', [
+        'signal' => static::class,
+        'collection' => $event->getCollection(),
+        'operation' => $event->getOperation()->value,
+    ]);
+
+    // Your logic
+}
+```
+
+### Handle Failures Gracefully
+
+Always implement failure handling for queued Signals:
+
+```php
+public function failed(SignalEvent $event, \Throwable $exception): void
+{
+    Log::error('Signal processing failed', [
+        'signal' => static::class,
+        'event_did' => $event->did,
+        'error' => $exception->getMessage(),
+        'trace' => $exception->getTraceAsString(),
+    ]);
+
+    // Optionally: send to error tracking service
+    // report($exception);
+}
+```
+
+## Auto-Discovery
+
+Signals are automatically discovered from `app/Signals/` by default. You can customize discovery in `config/signal.php`:
+
+```php
+'auto_discovery' => [
+    'enabled' => true,
+    'path' => app_path('Signals'),
+    'namespace' => 'App\\Signals',
+],
+```
+
+### Manual Registration
+
+Disable auto-discovery and register Signals manually:
+
+```php
+'auto_discovery' => [
+    'enabled' => false,
+],
+
+'signals' => [
+    \App\Signals\NewPostSignal::class,
+    \App\Signals\NewFollowSignal::class,
+],
+```
+
+## Testing Signals
+
+Test your Signals before deploying:
+
+```bash
+php artisan signal:test MySignal
+```
+
+[Learn more about testing →](testing.md)
+
+## Listing Signals
+
+View all registered Signals:
+
+```bash
+php artisan signal:list
+```
+
+This displays:
+- Signal class names
+- Event types they listen for
+- Collection filters (if any)
+- Queue configuration
+
+## Next Steps
+
+- **[Learn about filtering →](filtering.md)** - Master collection patterns and wildcards
+- **[Understand queue integration →](queues.md)** - Build high-performance processors
+- **[See real-world examples →](examples.md)** - Learn from production use cases

docs/testing.md

···
+# Testing Signals
+
+Testing your Signals ensures they behave correctly before deploying to production. Signal provides tools for both manual and automated testing.
+
+## Quick Testing with Artisan
+
+The fastest way to test a Signal is with the `signal:test` command.
+
+### Test a Signal
+
+```bash
+php artisan signal:test NewPostSignal
+```
+
+This runs your Signal with sample event data and displays the output.
+
+### What It Does
+
+1. Creates a sample `SignalEvent` matching your Signal's filters
+2. Calls your Signal's `handle()` method
+3. Displays output, logs, and any errors
+4. Shows execution time
+
+### Example Output
+
+```
+Testing Signal: App\Signals\NewPostSignal
+
+Creating sample commit event for collection: app.bsky.feed.post
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Event Details:
+  DID: did:plc:test123
+  Collection: app.bsky.feed.post
+  Operation: create
+  Text: Sample post for testing
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Processing event...
+✓ Signal processed successfully
+
+Execution time: 12ms
+```
+
+### Limitations
+
+- Uses sample data (not real events)
+- Doesn't test filtering logic comprehensively
+- Can't test queue behavior
+- Limited to basic scenarios
+
+For comprehensive testing, write automated tests.
+
+## Unit Testing
+
+Test your Signals in isolation.
+
+### Basic Test Structure
+
+```php
+<?php
+
+namespace Tests\Unit\Signals;
+
+use App\Signals\NewPostSignal;
+use SocialDept\Signal\Events\CommitEvent;
+use SocialDept\Signal\Events\SignalEvent;
+use Tests\TestCase;
+
+class NewPostSignalTest extends TestCase
+{
+    /** @test */
+    public function it_handles_new_posts()
+    {
+        $signal = new NewPostSignal();
+
+        $event = new SignalEvent(
+            did: 'did:plc:test123',
+            timeUs: time() * 1000000,
+            kind: 'commit',
+            commit: new CommitEvent(
+                rev: 'test',
+                operation: 'create',
+                collection: 'app.bsky.feed.post',
+                rkey: 'test123',
+                record: (object) [
+                    'text' => 'Hello World!',
+                    'createdAt' => now()->toIso8601String(),
+                ],
+            ),
+        );
+
+        $signal->handle($event);
+
+        // Assert expected behavior
+        $this->assertDatabaseHas('posts', [
+            'text' => 'Hello World!',
+        ]);
+    }
+}
+```
+
+### Testing Event Types
+
+Verify your Signal listens for correct event types:
+
+```php
+/** @test */
+public function it_listens_for_commit_events()
+{
+    $signal = new NewPostSignal();
+
+    $eventTypes = $signal->eventTypes();
+
+    $this->assertContains('commit', $eventTypes);
+}
+```
+
+### Testing Filters
+
+Verify collection filtering:
+
+```php
+/** @test */
+public function it_filters_to_posts_only()
+{
+    $signal = new NewPostSignal();
+
+    $collections = $signal->collections();
+
+    $this->assertEquals(['app.bsky.feed.post'], $collections);
+}
+```
+
+### Testing Operation Filtering
+
+```php
+/** @test */
+public function it_only_handles_creates()
+{
+    $signal = new NewPostSignal();
+
+    $operations = $signal->operations();
+
+    $this->assertEquals([SignalCommitOperation::Create], $operations);
+}
+```
+
+### Testing Custom Filtering
+
+```php
+/** @test */
+public function it_filters_posts_with_images()
+{
+    $signal = new ImagePostSignal();
+
+    // Event with image
+    $eventWithImage = $this->createEvent([
+        'text' => 'Check this out!',
+        'embed' => (object) ['type' => 'image'],
+    ]);
+
+    $this->assertTrue($signal->shouldHandle($eventWithImage));
+
+    // Event without image
+    $eventWithoutImage = $this->createEvent([
+        'text' => 'Just text',
+    ]);
+
+    $this->assertFalse($signal->shouldHandle($eventWithoutImage));
+}
+```
+
+## Feature Testing
+
+Test Signals in the context of your application.
+
+### Test with Database
+
+```php
+<?php
+
+namespace Tests\Feature\Signals;
+
+use App\Models\Post;
+use App\Signals\StorePostSignal;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use SocialDept\Signal\Events\CommitEvent;
+use SocialDept\Signal\Events\SignalEvent;
+use Tests\TestCase;
+
+class StorePostSignalTest extends TestCase
+{
+    use RefreshDatabase;
+
+    /** @test */
+    public function it_stores_posts_in_database()
+    {
+        $signal = new StorePostSignal();
+
+        $event = new SignalEvent(
+            did: 'did:plc:test123',
+            timeUs: time() * 1000000,
+            kind: 'commit',
+            commit: new CommitEvent(
+                rev: 'abc',
+                operation: 'create',
+                collection: 'app.bsky.feed.post',
+                rkey: 'test',
+                record: (object) [
+                    'text' => 'Test post',
+                    'createdAt' => now()->toIso8601String(),
+                ],
+            ),
+        );
+
+        $signal->handle($event);
+
+        $this->assertDatabaseHas('posts', [
+            'did' => 'did:plc:test123',
+            'text' => 'Test post',
+        ]);
+    }
+
+    /** @test */
+    public function it_updates_existing_posts()
+    {
+        Post::create([
+            'did' => 'did:plc:test123',
+            'rkey' => 'test',
+            'text' => 'Old text',
+        ]);
+
+        $signal = new StorePostSignal();
+
+        $event = $this->createUpdateEvent([
+            'text' => 'New text',
+        ]);
+
+        $signal->handle($event);
+
+        $this->assertDatabaseHas('posts', [
+            'did' => 'did:plc:test123',
+            'text' => 'New text',
+        ]);
+
+        $this->assertEquals(1, Post::count());
+    }
+
+    /** @test */
+    public function it_deletes_posts()
+    {
+        Post::create([
+            'did' => 'did:plc:test123',
+            'rkey' => 'test',
+            'text' => 'Test post',
+        ]);
+
+        $signal = new StorePostSignal();
+
+        $event = $this->createDeleteEvent();
+
+        $signal->handle($event);
+
+        $this->assertDatabaseMissing('posts', [
+            'did' => 'did:plc:test123',
+            'rkey' => 'test',
+        ]);
+    }
+}
+```
+
+### Test with External APIs
+
+```php
+use Illuminate\Support\Facades\Http;
+
+/** @test */
+public function it_sends_notifications()
+{
+    Http::fake();
+
+    $signal = new NotificationSignal();
+
+    $event = $this->createEvent();
+
+    $signal->handle($event);
+
+    Http::assertSent(function ($request) {
+        return $request->url() === 'https://api.example.com/notify' &&
+               $request['text'] === 'New post created';
+    });
+}
+```
+
+## Testing Queued Signals
+
+Test Signals that use queues.
+
+### Test Queue Dispatch
+
+```php
+use Illuminate\Support\Facades\Queue;
+
+/** @test */
+public function it_queues_events()
+{
+    Queue::fake();
+
+    $signal = new QueuedSignal();
+
+    $this->assertTrue($signal->shouldQueue());
+
+    // In production, this would queue
+    // For testing, we verify the intent
+}
+```
+
+### Test with Sync Queue
+
+Process queued jobs synchronously in tests:
+
+```php
+/** @test */
+public function it_processes_queued_events()
+{
+    // Use sync queue for immediate processing
+    config(['queue.default' => 'sync']);
+
+    $signal = new QueuedSignal();
+
+    $event = $this->createEvent();
+
+    $signal->handle($event);
+
+    // Assert side effects happened
+    $this->assertDatabaseHas('posts', [...]);
+}
+```
+
+### Test Queue Configuration
+
+```php
+/** @test */
+public function it_uses_high_priority_queue()
+{
+    $signal = new HighPrioritySignal();
+
+    $this->assertTrue($signal->shouldQueue());
+    $this->assertEquals('high-priority', $signal->queue());
+}
+
+/** @test */
+public function it_uses_redis_connection()
+{
+    $signal = new RedisQueueSignal();
+
+    $this->assertEquals('redis', $signal->queueConnection());
+}
+```
+
+## Testing Failure Handling
+
+Test how your Signal handles errors.
+
+### Test Failed Method
+
+```php
+use Illuminate\Support\Facades\Log;
+
+/** @test */
+public function it_logs_failures()
+{
+    Log::spy();
+
+    $signal = new FailureHandlingSignal();
+
+    $event = $this->createEvent();
+    $exception = new \Exception('Something went wrong');
+
+    $signal->failed($event, $exception);
+
+    Log::shouldHaveReceived('error')
+        ->with('Signal failed', \Mockery::any());
+}
+```
+
+### Test Exception Handling
+
+```php
+/** @test */
+public function it_handles_invalid_data_gracefully()
+{
+    $signal = new RobustSignal();
+
+    $event = new SignalEvent(
+        did: 'did:plc:test',
+        timeUs: time() * 1000000,
+        kind: 'commit',
+        commit: new CommitEvent(
+            rev: 'test',
+            operation: 'create',
+            collection: 'app.bsky.feed.post',
+            rkey: 'test',
+            record: (object) [], // Missing required fields
+        ),
+    );
+
+    // Should not throw
+    $signal->handle($event);
+
+    // Should handle gracefully (e.g., log and skip)
+    $this->assertDatabaseCount('posts', 0);
+}
+```
+
+## Test Helpers
+
+Create reusable helpers for common test scenarios.
+
+### Event Factory Helper
+
+```php
+trait CreatesSignalEvents
+{
+    protected function createCommitEvent(array $overrides = []): SignalEvent
+    {
+        $defaults = [
+            'did' => 'did:plc:test123',
+            'timeUs' => time() * 1000000,
+            'kind' => 'commit',
+            'commit' => new CommitEvent(
+                rev: 'test',
+                operation: $overrides['operation'] ?? 'create',
+                collection: $overrides['collection'] ?? 'app.bsky.feed.post',
+                rkey: $overrides['rkey'] ?? 'test',
+                record: (object) array_merge([
+                    'text' => 'Test post',
+                    'createdAt' => now()->toIso8601String(),
+                ], $overrides['record'] ?? []),
+            ),
+        ];
+
+        return new SignalEvent(...$defaults);
+    }
+
+    protected function createPostEvent(array $record = []): SignalEvent
+    {
+        return $this->createCommitEvent([
+            'collection' => 'app.bsky.feed.post',
+            'record' => $record,
+        ]);
+    }
+
+    protected function createLikeEvent(array $record = []): SignalEvent
+    {
+        return $this->createCommitEvent([
+            'collection' => 'app.bsky.feed.like',
+            'record' => array_merge([
+                'subject' => (object) [
+                    'uri' => 'at://did:plc:test/app.bsky.feed.post/test',
+                    'cid' => 'bafytest',
+                ],
+                'createdAt' => now()->toIso8601String(),
+            ], $record),
+        ]);
+    }
+
+    protected function createFollowEvent(array $record = []): SignalEvent
+    {
+        return $this->createCommitEvent([
+            'collection' => 'app.bsky.graph.follow',
+            'record' => array_merge([
+                'subject' => 'did:plc:target',
+                'createdAt' => now()->toIso8601String(),
+            ], $record),
+        ]);
+    }
+}
+```
+
+Use in tests:
+
+```php
+class MySignalTest extends TestCase
+{
+    use CreatesSignalEvents;
+
+    /** @test */
+    public function it_handles_posts()
+    {
+        $event = $this->createPostEvent([
+            'text' => 'Custom text',
+        ]);
+
+        // Test with event
+    }
+}
+```
+
+### Signal Factory Helper
+
+```php
+trait CreatesSignals
+{
+    protected function createSignal(string $class, array $config = [])
+    {
+        $signal = new $class();
+
+        // Override configuration for testing
+        foreach ($config as $method => $value) {
+            $signal->{$method} = $value;
+        }
+
+        return $signal;
+    }
+}
+```
+
+## Testing Best Practices
+
+### Use Descriptive Test Names
+
+```php
+// Good
+/** @test */
+public function it_stores_posts_with_valid_data()
+
+/** @test */
+public function it_skips_posts_without_text()
+
+/** @test */
+public function it_handles_duplicate_posts_gracefully()
+
+// Less descriptive
+/** @test */
+public function test_handle()
+```
+
+### Test Edge Cases
+
+```php
+/** @test */
+public function it_handles_empty_text()
+{
+    $event = $this->createPostEvent(['text' => '']);
+    // Test behavior
+}
+
+/** @test */
+public function it_handles_very_long_text()
+{
+    $event = $this->createPostEvent(['text' => str_repeat('a', 10000)]);
+    // Test behavior
+}
+
+/** @test */
+public function it_handles_missing_created_at()
+{
+    $event = $this->createPostEvent(['createdAt' => null]);
+    // Test behavior
+}
+```
+
+### Test All Operations
+
+```php
+/** @test */
+public function it_handles_creates()
+{
+    $event = $this->createEvent(['operation' => 'create']);
+    // Test
+}
+
+/** @test */
+public function it_handles_updates()
+{
+    $event = $this->createEvent(['operation' => 'update']);
+    // Test
+}
+
+/** @test */
+public function it_handles_deletes()
+{
+    $event = $this->createEvent(['operation' => 'delete']);
+    // Test
+}
+```
+
+### Mock External Dependencies
+
+```php
+/** @test */
+public function it_calls_external_api()
+{
+    Http::fake([
+        'api.example.com/*' => Http::response(['success' => true]),
+    ]);
+
+    $signal = new ApiSignal();
+    $event = $this->createEvent();
+
+    $signal->handle($event);
+
+    Http::assertSent(function ($request) {
+        return $request->url() === 'https://api.example.com/endpoint';
+    });
+}
+```
+
+### Test Database State
+
+```php
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+class DatabaseSignalTest extends TestCase
+{
+    use RefreshDatabase;
+
+    /** @test */
+    public function it_creates_records()
+    {
+        // Fresh database for each test
+    }
+}
+```
+
+## Continuous Integration
+
+Run tests automatically on every commit.
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/tests.yml
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.2
+
+      - name: Install Dependencies
+        run: composer install
+
+      - name: Run Tests
+        run: php artisan test
+```
+
+### Run Signal-Specific Tests
+
+```bash
+# Run all Signal tests
+php artisan test --testsuite=Signals
+
+# Run specific test file
+php artisan test tests/Unit/Signals/NewPostSignalTest.php
+
+# Run with coverage
+php artisan test --coverage
+```
+
+## Debugging Tests
+
+### Enable Debug Output
+
+```php
+/** @test */
+public function it_processes_events()
+{
+    $signal = new NewPostSignal();
+
+    $event = $this->createEvent();
+
+    dump($event); // Output event data
+
+    $signal->handle($event);
+
+    dump(Post::all()); // Output results
+}
+```
+
+### Use dd() to Stop Execution
+
+```php
+/** @test */
+public function it_processes_events()
+{
+    $event = $this->createEvent();
+
+    dd($event); // Dump and die
+
+    // This won't run
+}
+```
+
+### Check Logs
+
+```php
+/** @test */
+public function it_logs_processing()
+{
+    Log::spy();
+
+    $signal = new LoggingSignal();
+    $event = $this->createEvent();
+
+    $signal->handle($event);
+
+    Log::shouldHaveReceived('info')->once();
+}
+```
+
+## Next Steps
+
+- **[See real-world examples →](examples.md)** - Learn from production test patterns
+- **[Review queue integration →](queues.md)** - Test queued Signals
+- **[Review signals documentation →](signals.md)** - Understand Signal structure