/{README.md,examples}: readmes

README.md

@@ -1 +1,28 @@
 # eventkit
+
+Fire-and-forget event telemetry for Go CLIs. Buffers events in-process, spills to a durable disk queue, and ships them out-of-band via a detached flusher subprocess so the user-facing command never blocks on the network.
+
+```
+Event → Collector → FileEmitter → .evtq on disk → FileFlusher → transport (PostHog)
+```
+
+## Install
+
+```bash
+go get github.com/dolthub/eventkit
+```
+
+Requires Go 1.26+.
+
+## Usage
+
+See [`examples/mycli`](examples/mycli) for the worked pattern: construct a `FileEmitter`, wrap it in a `Collector`, emit events with `NewEvent` + `AddMetric` + `CloseEventAndAdd`, then on exit spawn a detached subcommand that runs `FileFlusher.Flush` against `transport/posthog`.
+
+## Durability
+
+Each batch is a single `.evtq` file named by the first 22 chars of base64-URL MD5 of its contents (corruption check). A cross-process `eventkit.lock` ensures only one flusher runs at a time. Transports that implement `Drainable` report per-event failures; files with any undelivered event are retained for the next run.
+
+## Transports
+
+- `transport/posthog` — ships via the PostHog SDK.
+- Roll your own by implementing `Emitter` (and optionally `Drainable`).

examples/mycli/README.md

@@ -44,4 +44,4 @@ The pattern boils down to four code locations:
 1. **Startup** (`runInstrumented`): construct `FileEmitter`, wrap in a `Collector` with `WithDistinctID` / `WithAppName` / `WithAppVersion` / `WithDisabled`, set it as the global.
 2. **Per-command instrumentation** (`doFoo` / `doBar` / `doBaz`): `NewEvent` + `defer Global().CloseEventAndAdd(evt)`; enrich with `SetAttribute`, `AddMetric(NewCounter(...))`, `AddMetric(NewTimer(...))`.
 3. **Shutdown** (end of `runInstrumented`): bounded `Collector.Close(ctx)` to flush the final partial batch to disk; spawn detached `send-metrics`.
-4. **Hidden subcommand** (`runSendMetrics`): build a `PostHog.Emitter`, wrap in a `FileFlusher`, call `Flush(ctx)`. The flusher takes the cross-process lock, ships every queued batch via the SDK's batching, and deletes only the files whose events all delivered successfully.
+4. **Hidden subcommand** (`runSendMetrics`): build a `posthog.Emitter`, wrap in a `FileFlusher`, call `Flush(ctx)`. The flusher takes the cross-process lock, ships every queued batch via the SDK's batching, and deletes only the files whose events all delivered successfully.