Add CI workflow, README, CLAUDE.md, AGENTS.md, and .cursorrules

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,46 @@
+# CLAUDE.md — dbx
+
+## Commands
+
+```bash
+go build ./...                          # compile
+go test ./...                           # all tests
+go test -race ./...                     # tests with race detector
+go test -v -run TestName ./...          # single test
+go vet ./...                            # static analysis
+```
+
+## Architecture
+
+- **Module**: `git.codelab.vc/pkg/dbx`, Go 1.24, depends on pgx/v5
+- **Single package** `dbx` (+ `dbxtest` for test helpers)
+
+### Core patterns
+
+- **Cluster** is the entry point — connects master + replicas, routes writes to master, reads to replicas with master fallback
+- **Routing is method-based**: `Exec`/`Query`/`QueryRow`/`Begin`/`BeginTx`/`CopyFrom`/`SendBatch` → master; `ReadQuery`/`ReadQueryRow` → replicas
+- **Retry** with exponential backoff + jitter, node fallback; retrier.do() iterates nodes then backs off
+- **Balancer** interface (`Next([]*Node) *Node`) — built-in `RoundRobinBalancer` skips unhealthy nodes
+- **Health checker** — background goroutine pings all nodes on an interval, flips `Node.healthy` atomic bool
+- **RunTx** — panic-safe transaction wrapper: recovers panics, rolls back, re-panics
+- **Querier injection** — `InjectQuerier`/`ExtractQuerier` pass `Querier` via context for service layers
+
+### Error classification
+
+- `IsRetryable(err)` — connection errors (class 08), serialization failures (40001), deadlocks (40P01), too_many_connections (53300)
+- `IsConnectionError(err)` — PG class 08 + string matching for pgx-wrapped errors
+- `IsConstraintViolation(err)` — PG class 23
+- `PgErrorCode(err)` — extract raw code from `*pgconn.PgError`
+
+## Conventions
+
+- Struct-based `Config` with `defaults()` method (not functional options for NewCluster constructor, but `Option` type exists for `ApplyOptions` in tests)
+- Functional options (`Option func(*Config)`) used via `ApplyOptions` (e.g., in dbxtest)
+- stdlib-only tests — no testify, no gomock
+- `atomic.Bool` for thread safety (`Node.healthy`, `Cluster.closed`)
+- `dbxtest.NewTestCluster` skips tests when DB unreachable, auto-closes via `t.Cleanup`
+- `dbxtest.TestLogger` writes to `testing.T` for test log output
+
+## See also
+
+- `AGENTS.md` — universal AI agent guide with common tasks, gotchas, and ASCII diagrams