1 files changed, 66 insertions, 0 deletions
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..5f944d4
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,66 @@
+# Epimetheus Documentation
+
+Documentation for Epimetheus: a Go tool for pushing metrics to Prometheus (and Prometheus-compatible backends) and ClickHouse.
+
+## Index
+
+### Guides
+
+| Document | Description |
+|----------|-------------|
+| [Quick Start](guides/quickstart.md) | Minimal path to first push: build, run, view in Prometheus or ClickHouse |
+| [Operating Modes](guides/modes.md) | Realtime, historic, backfill, auto, and watch modes with examples |
+| [Data Formats](guides/data-formats.md) | Epimetheus CSV and JSON input formats |
+| [CSV Format Flexibility](guides/csv-format-flexibility.md) | Use any tabular CSV; numeric vs string columns; sanitization and examples |
+| [DNS Resolution](guides/dns-resolution.md) | IP-to-hostname resolution for watch mode labels |
+| [Dtail Metrics Example](guides/dtail-metrics-example.md) | Walkthrough using dtail.csv |
+
+### Ingestion Backends
+
+| Document | Description |
+|----------|-------------|
+| [Prometheus (and Prometheus-compatible)](backends/prometheus.md) | Pushgateway, Remote Write, time ranges; VictoriaMetrics via same URL |
+| [ClickHouse](backends/clickhouse.md) | Watch-mode ingestion; table schema; verify script |
+
+### Operations
+
+| Document | Description |
+|----------|-------------|
+| [Setup: Prometheus](operations/setup-prometheus.md) | Enable Remote Write receiver, scrape config, retention |
+| [Setup: ClickHouse](operations/setup-clickhouse.md) | Table creation, verification |
+| [Troubleshooting](operations/troubleshooting.md) | Connection issues, metrics not appearing, out-of-order errors |
+| [Cleanup](operations/cleanup.md) | Benchmark cleanup, Pushgateway delete, port-forwards |
+| [macOS Setup](operations/macos-setup.md) | Homebrew, Prometheus args, Remote Write on macOS |
+| [Kubernetes](operations/kubernetes.md) | Port-forwards, Helm, ConfigMaps |
+
+### Reference
+
+| Document | Description |
+|----------|-------------|
+| [CLI Reference](reference/cli.md) | All flags by mode with defaults |
+| [Test Metrics](reference/test-metrics.md) | epimetheus_test_* metrics and types |
+| [Grafana Dashboard](reference/grafana-dashboard.md) | Panels, deployment options, datasource |
+| [Example Queries](reference/example-queries.md) | PromQL and curl examples |
+| [Magefile](reference/magefile.md) | Mage build and run targets |
+
+### Design
+
+| Document | Description |
+|----------|-------------|
+| [Architecture](design/architecture.md) | Data flow, when to use Pushgateway vs Remote Write, backend choice |
+
+### Helper scripts
+
+Helper shell scripts live in **`scripts/`** at the repo root. Run them from the repo root (e.g. `./scripts/verify-clickhouse.sh`).
+
+| Script | Purpose |
+|--------|---------|
+| `verify-clickhouse.sh` | Verify ClickHouse ingestion (row count, sample data) |
+| `generate-test-data.sh` | Generate `test-all-ages.csv` for auto mode |
+| `cleanup-benchmark-data.sh` | Delete benchmark metrics from Prometheus (Admin API) |
+| `cleanup-benchmark-metrics.sh` | Same + starts port-forward, then cleans up |
+| `benchmark-100mb.sh` | 100MB ingestion benchmark |
+| `benchmark-1gb.sh` | 1GB ingestion benchmark |
+| `backfill-historic-data.sh` | Backfill 7 days of historic data to Prometheus |
+| `run.sh` | Port-forward Pushgateway and run epimetheus in realtime mode |
+| `deploy-dashboard.sh` | Deploy Grafana dashboard via API (if present) |