chore: improve readme (#44)

Author: psteinroe

README.md

@@ -1,20 +1,88 @@
-<div align="center">
+<p align="center">
   <img src="docs/media/logo.png" alt="Postgres Stream" width="300">
+</p>
 
-  # Postgres Stream
+<h1 align="center">Postgres Stream</h1>
+
+<p align="center">
   Reliably stream Postgres table changes to external systems with automatic failover and zero event loss.
+</p>
 
-  [Documentation](https://pg-stream.dev/)
-</div>
+## What is Postgres Stream?
 
+Postgres Stream captures changes from your Postgres tables and delivers them to external systems like Kafka, RabbitMQ, Redis, Webhooks, and cloud services. It uses Postgres native logical replication and stores events durably in the database itself.
 
-## Features
+## Key Features
 
 - **Single binary** - No complex infrastructure or high-availability destinations required
 - **Postgres-native durability** - Events are stored in the database, WAL can be released immediately
 - **Zero data loss** - As long as downtime is less than partition retention (7 days by default)
 - **Automatic recovery** - Handles both sink failures and slot invalidation without operator intervention
 
+## How It Works
+
+Events are inserted into the `pgstream.events` table and streamed via logical replication to your sink.
+
+**Two ways to create events:**
+
+1. **Subscriptions** (optional) - Define triggers that automatically capture table changes
+2. **Manual inserts** - Insert directly into `pgstream.events` from your application or database functions
+
+## Trade-offs
+
+While Postgres Stream provides strong durability guarantees, there are some considerations:
+
+- **Small overhead** - Additional INSERT into `events` table on every subscribed operation
+- **Partition management** - Monitor partition growth if event volume is very high
+- **Not for dynamic subscriptions** - Each subscription change recreates database triggers
+
+## Supported Sinks
+
+| Sink | Use Case |
+|------|----------|
+| [Kafka](https://pg-stream.dev/sinks/kafka) | High-throughput event streaming |
+| [NATS](https://pg-stream.dev/sinks/nats) | Lightweight pub/sub messaging |
+| [RabbitMQ](https://pg-stream.dev/sinks/rabbitmq) | Enterprise message broker |
+| [Redis Strings](https://pg-stream.dev/sinks/redis-strings) | Key-value caching |
+| [Redis Streams](https://pg-stream.dev/sinks/redis-streams) | Append-only event log |
+| [Webhook](https://pg-stream.dev/sinks/webhook) | HTTP POST delivery |
+| [AWS SQS](https://pg-stream.dev/sinks/sqs) | Managed queue service |
+| [AWS SNS](https://pg-stream.dev/sinks/sns) | Managed pub/sub service |
+| [AWS Kinesis](https://pg-stream.dev/sinks/kinesis) | Real-time data streaming |
+| [GCP Pub/Sub](https://pg-stream.dev/sinks/gcp-pubsub) | Google Cloud messaging |
+| [Elasticsearch](https://pg-stream.dev/sinks/elasticsearch) | Search indexing |
+| [Meilisearch](https://pg-stream.dev/sinks/meilisearch) | Search indexing |
+
+## Quick Start
+
+```yaml
+# config.yaml
+stream:
+  id: 1
+  pg_connection:
+    host: localhost
+    port: 5432
+    name: mydb
+    username: postgres
+    password: postgres
+    tls:
+      enabled: false
+  batch:
+    max_size: 1000
+    max_fill_secs: 5
+
+sink:
+  type: kafka
+  brokers: localhost:9092
+  topic: events
+```
+
+```bash
+# Run with Docker
+docker run -v $(pwd)/config.yaml:/config.yaml \
+  ghcr.io/psteinroe/postgres-stream:kafka-latest
+```
+
 ## License
 
 MIT

docs/index.md

@@ -28,6 +28,14 @@ Events are inserted into the `pgstream.events` table and streamed via logical re
 1. **Subscriptions** (optional) - Define triggers that automatically capture table changes
 2. **Manual inserts** - Insert directly into `pgstream.events` from your application or database functions
 
+## Trade-offs
+
+While Postgres Stream provides strong durability guarantees, there are some considerations:
+
+- **Small overhead** - Additional INSERT into `events` table on every subscribed operation
+- **Partition management** - Monitor partition growth if event volume is very high
+- **Not for dynamic subscriptions** - Each subscription change recreates database triggers
+
 ## Supported Sinks
 
 | Sink | Use Case |
@@ -75,14 +83,6 @@ docker run -v $(pwd)/config.yaml:/config.yaml \
   ghcr.io/psteinroe/postgres-stream:kafka-latest
 ```
 
-## Trade-offs
-
-While Postgres Stream provides strong durability guarantees, there are some considerations:
-
-- **Small overhead** - Additional INSERT into `events` table on every subscribed operation
-- **Partition management** - Monitor partition growth if event volume is very high
-- **Not for dynamic subscriptions** - Each subscription change recreates database triggers
-
 ## Next Steps
 
 - [Getting Started](getting-started.md) - Set up your first stream