docs: update API and benchmark operation guides

Author: mizchi

README.md

@@ -11,11 +11,36 @@
 - `GET /health`
 - `POST /api/v1/publish?room=<room>&sender=<sender>&topic=notify&id=<id>&sig=<sig?>`
 - `GET /api/v1/poll?room=<room>&after=<cursor>&limit=<n>`
+- `POST /api/v1/review?room=<room>&sender=<sender>&pr_id=<id>&verdict=approve|deny`
+- `GET /api/v1/review?room=<room>&pr_id=<id>`
 - `GET /api/v1/inbox/pending?room=<room>&consumer=<consumer>&limit=<n>`
 - `POST /api/v1/inbox/ack?room=<room>&consumer=<consumer>`
 - `GET /ws?room=<room>`
 - `GET /api/v1/key/info?sender=<sender>`
 - `POST /api/v1/key/rotate`
+- `POST /api/v1/key/verify-github`
+
+### Cache Exchange / Issue Cache
+
+- `GET /api/v1/cache/exchange/discovery`
+- `GET /api/v1/cache/exchange/pull?after=<cursor>&limit=<n>&peer=<node_id>&room=<room?>`
+- `POST /api/v1/cache/exchange/push`
+- `GET /api/v1/cache/issues/pull?room=<room>&after=<cursor>&limit=<n>`
+- `GET /api/v1/cache/issues/sync?room=<room>&after=<cursor>&limit=<n>`
+
+### Trigger / Callback / GitHub Webhook
+
+- `POST /api/v1/trigger/callback`
+- `GET /api/v1/trigger/results?room=<room>&after=<cursor>&limit=<n>`
+- `POST /api/v1/github/webhook`
+- `GET /api/v1/github/webhook/dlq?after=<cursor>&limit=<n>`
+- `POST /api/v1/github/webhook/dlq/retry?delivery_id=<id>`
+
+### Admin APIs (auth required)
+
+- `POST /api/v1/admin/github/repos/register`
+- `POST /api/v1/admin/github/repos/<id>/push`
+- `POST /api/v1/admin/github/repos/<id>/actions/dispatch`
 
 ### Git Serve Session (relay-proxied clone)
 
@@ -47,6 +72,19 @@ Clone side → (response resolved)
 - room validation: `[A-Za-z0-9][A-Za-z0-9._-]{0,63}`
 - dedupe: room 内の同一 `id` は `accepted=false`
 
+## Observability
+
+構造化ログ（JSON line）を標準出力へ出します。
+
+- `relay_event`: incoming ref / issue sync / cache replication などのイベントログ
+- `relay_audit`: API の監査ログ
+- `relay_metric`: メトリクスログ
+
+代表的なメトリクス:
+
+- `relay.request.success_rate`: 操作単位の成功率・平均レイテンシ・再試行回数
+- `relay.cache.persist.retry`: cache 永続化の再試行回数
+
 ## Auth
 
 `BIT_RELAY_AUTH_TOKEN` を設定すると `/api/v1/*` と `/ws` で Bearer 認証を要求します。
@@ -134,6 +172,22 @@ optional env:
 - `RELAY_MAX_CLOCK_SKEW_SEC` (default: `300`)
 - `RELAY_NONCE_TTL_SEC` (default: `600`)
 - `RELAY_MAX_NONCES_PER_SENDER` (default: `2048`)
+- `RELAY_NODE_ID` (cache exchange ノード ID)
+- `RELAY_PEERS` (CSV: peer relay URLs)
+- `RELAY_PEERS_JSON` (JSON: peer relay URLs, `RELAY_PEERS` より優先)
+- `RELAY_PEER_AUTH_TOKEN` (peer pull 時の Bearer token)
+- `RELAY_PEER_SYNC_INTERVAL_SEC` (default: `30`)
+- `RELAY_CACHE_PROVIDER` (`memory` or `r2`, default: `memory`)
+- `RELAY_CACHE_TTL_SEC` (default: `86400`)
+- `RELAY_CACHE_MAX_BYTES` (任意、上限 bytes)
+- `RELAY_CACHE_R2_BUCKET` (R2 利用時)
+- `RELAY_CACHE_R2_PREFIX` (default: `relay-cache/`)
+- `RELAY_GITHUB_WEBHOOK_SECRET`
+- `RELAY_TRIGGER_WEBHOOK_URL`
+- `RELAY_TRIGGER_WEBHOOK_TOKEN`
+- `RELAY_TRIGGER_EVENT_TYPE` (default: `relay.incoming_ref`)
+- `RELAY_TRIGGER_REF_PREFIXES` (CSV, default: `refs/relay/incoming/`)
+- `RELAY_CONFIG_JSON` (JSON override)
 
 互換モード（従来の unsigned publish 許可）:
 
@@ -242,3 +296,14 @@ just test-serve https://myapp.exe.dev
 ```bash
 just test
 ```
+
+## Benchmark
+
+```bash
+# 全シナリオ
+just bench https://bit-relay.mizchi.workers.dev
+
+# 新規: multi-relay + cache hit/miss + issue sync
+RELAY_URLS=https://relay-a.example,https://relay-b.example \
+  just bench-scenario multi-relay-cache-issue-sync https://relay-a.example
+```

TODO.md

@@ -209,7 +209,7 @@
 - [x] `just test` に新規テストを統合（失敗時に原因が追える粒度）
 - [x] 負荷計測シナリオを追加（multi-relay + cache hit/miss + issue sync）
 - [x] 監査ログとメトリクス（成功率、レイテンシ、再試行回数）を追加
-- [ ] ドキュメント更新（`README.md`, `docs/usage-guide-ja.md`, `docs/scaling.md`）
+- [x] ドキュメント更新（`README.md`, `docs/usage-guide-ja.md`, `docs/scaling.md`）
 
 ## 未確定事項（実装前に決める）
 

docs/scaling.md

@@ -3,6 +3,8 @@
 bit-relay (Cloudflare Workers + Durable Objects) のスケーリング特性を k6
 ベンチマークで計測した結果をまとめる。
 
+2026-02-24 に、multi-relay + issue cache sync のベンチシナリオを追加した。
+
 ## 計測環境
 
 - ターゲット: `bit-relay.mizchi.workers.dev` (Cloudflare Workers)
@@ -70,6 +72,25 @@ MAX_WS_SESSIONS=100 の制約内。100 同時接続で全く問題なし。
 
 register は新規 DO 生成を伴うため ~400-600ms。セッション確立の 1 回コスト。
 
+### Multi-relay + Cache Hit/Miss + Issue Sync（新規シナリオ）
+
+`bench/scenarios/multi-relay-cache-issue-sync.js` を追加。
+
+- relay A で issue 作成/更新を publish
+- relay A -> B へ `cache/exchange` pull/push
+- relay B で `cache/issues/pull` の miss/hit と `cache/issues/sync` を計測
+
+計測メトリクス:
+
+- `mr_issue_publish_latency`
+- `mr_exchange_pull_latency`
+- `mr_exchange_push_latency`
+- `mr_cache_issue_pull_miss_latency`
+- `mr_cache_issue_pull_hit_latency`
+- `mr_issue_sync_latency`
+- `mr_cache_hit_count`
+- `mr_cache_miss_count`
+
 ## スケーリング特性
 
 ### ボトルネックにならなかったもの
@@ -113,6 +134,10 @@ just bench-scenario health https://bit-relay.mizchi.workers.dev
 just bench-scenario publish-poll https://bit-relay.mizchi.workers.dev
 just bench-scenario publish-contention https://bit-relay.mizchi.workers.dev
 
+# 新規: 複数 relay 前提シナリオ
+RELAY_URLS=https://relay-a.example,https://relay-b.example \
+  just bench-scenario multi-relay-cache-issue-sync https://relay-a.example
+
 # JSON 出力
 just bench-json https://bit-relay.mizchi.workers.dev
 ```

docs/usage-guide-ja.md

@@ -202,6 +202,39 @@ bit relay sync push relay+https://bit-relay.mizchi.workers.dev
 | `relay+http://host`     | relay API を直接使用（非 TLS、ローカル開発用） |
 | `https://host/repo.git` | smart-http を試行、404 時に relay fallback     |
 
+## 運用者向け API（キャッシュ/同期）
+
+relay 運用者向けに、issue キャッシュと relay 間交換の確認 API を用意している。
+
+### issue キャッシュを直接確認する
+
+```bash
+# issue イベントをカーソルで取得
+curl "http://127.0.0.1:8788/api/v1/cache/issues/pull?room=main&after=0&limit=20"
+
+# issue snapshot + incremental event を取得
+curl "http://127.0.0.1:8788/api/v1/cache/issues/sync?room=main&after=0&limit=20"
+```
+
+### relay 間 cache exchange を手動確認する
+
+```bash
+# A から pull して
+curl "http://relay-a.local/api/v1/cache/exchange/pull?after=0&limit=50&peer=relay-b" > /tmp/exchange.json
+
+# B に push
+curl -X POST "http://relay-b.local/api/v1/cache/exchange/push" \
+  -H "content-type: application/json" \
+  --data @/tmp/exchange.json
+```
+
+### 負荷試験（multi-relay + cache hit/miss + issue sync）
+
+```bash
+RELAY_URLS=http://127.0.0.1:8788,http://127.0.0.1:8789 \
+  just bench-scenario multi-relay-cache-issue-sync http://127.0.0.1:8788
+```
+
 ## フルワークフロー: Alice と Bob
 
 ### Alice（ホスト側）