Phase 2a: kamado-api Go middleware (core MVP)

Go 1.22 module that polls CKPool's Unix socket control API, queries
Bitcoin Core over JSON-RPC, merges both into a thread-safe snapshot, and
serves it over REST. Layout:

  api/
  ├── cmd/kamado-api/main.go              signal-aware entrypoint
  └── internal/
      ├── config/       env var loader with validation
      ├── ckpool/       socket client (4-byte LE length-prefixed wire
      │                 protocol verified against libckpool.c), typed
      │                 response models for poolstats/users/workers/
      │                 clients/uptime, + unit tests using a fake
      │                 unix socket server
      ├── bitcoind/     minimal JSON-RPC client, getblockchaininfo
      │                 and getnetworkhashps
      ├── state/        Aggregator that refreshes a merged Snapshot
      │                 on a ticker; readers get a copy under RWMutex
      └── httpapi/      REST handlers on Go 1.22 ServeMux:
                        /api/health /api/pool /api/users
                        /api/workers /api/clients /api/snapshot

CKPool stores hashrate as "dsps" (diff shares per second); we convert
to H/s via the 2^32 constant used by GoBrrr-Pool and other clients.
Every stat CKPool exposes to its socket API is surfaced — useragent,
IP, per-client diff, per-worker best diff — closing the gap against
Bassin which only reads the 60-second stats files.

Dockerfile does a CGO_ENABLED=0 static build on golang:1.22-bookworm
with -trimpath -ldflags=-s -w. docker-compose now runs both ckpool and
kamado-api, sharing a named volume for /run/ckpool so the API can
dial the stratifier socket directly.

Deferred to Phase 2b (called out in README):
  - Bitcoin Core ZMQ hashblock subscriber
  - WebSocket push for real-time UI updates
  - SQLite persistence (block history, best-share history)
  - CKPool log tailer for "Solved and confirmed block" detection

Tests and build NOT run in this commit — Go isn't installed in the
dev environment. Run `make api-test` or `make api` to verify.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -38,11 +38,33 @@ Three main components:
 ## Phases
 
 - [x] **Phase 1** — Fork & fix CKPool, build infrastructure
-- [ ] **Phase 2** — Go API middleware (socket client, REST, WebSocket, SQLite)
+- [~] **Phase 2** — Go API middleware
+    - [x] Phase 2a: CKPool socket client, bitcoind RPC, state aggregator, REST API
+    - [ ] Phase 2b: ZMQ block notifier, WebSocket push, SQLite persistence, log tailer
 - [ ] **Phase 3** — Svelte UI dashboard
 - [ ] **Phase 4** — Monorepo Docker build, full stack integration
 - [ ] **Phase 5** — Testing (regtest, testnet4), polish
 
+## Quick start (dev)
+
+```sh
+cp .env.example .env          # set POOL_BTCADDRESS and bitcoind creds
+make up                       # build + start ckpool + api
+curl localhost:8080/api/health
+curl localhost:8080/api/pool
+```
+
+REST endpoints (Phase 2a):
+
+| Route                | Returns                                              |
+| -------------------- | ---------------------------------------------------- |
+| `GET /api/health`    | CKPool + bitcoind health                             |
+| `GET /api/pool`      | Pool stats + derived hashrate windows + chain info   |
+| `GET /api/users`     | All users from `users` socket command                |
+| `GET /api/workers`   | All workers from `workers` socket command            |
+| `GET /api/clients`   | All connected stratum sessions (useragent, IP, diff) |
+| `GET /api/snapshot`  | Full merged snapshot (everything)                    |
+
 StartOS packaging lives in a separate repository.
 
 ## Upstream