Billing docs improvement + build opt

api/gateway/chsettle/README.md

@@ -0,0 +1,101 @@
+# ChimeraSettle Gateway (`chsettle`)
+
+ChimeraSettle is a dummy settlement gateway for dev/test flows.
+It simulates settlement outcomes deterministically, without real fund movement.
+
+## What It Simulates
+
+- Fast success
+- Slow success
+- Immediate failure
+- Timeout-like failure
+- Stuck pending/processing
+- Retry-like progression before success
+- Deterministic chaos bucket
+
+## How Behavior Is Chosen
+
+Selection order:
+
+1. Explicit scenario override from request metadata:
+- `chsettle_scenario`
+- `scenario` (alias)
+
+2. Amount bucket routing based on:
+- `amount_minor % 1000`
+
+3. Hash fallback using idempotency key (if amount cannot be parsed)
+
+## Scenario Overrides
+
+Accepted override values (aliases supported in code):
+
+- `fast_success`
+- `slow_success`
+- `fail_immediate`
+- `fail_timeout`
+- `stuck_pending` (also `stuck`)
+- `retry_then_success`
+- `webhook_delayed_success`
+- `slow_then_fail`
+- `partial_progress_stuck`
+- `chaos`
+
+## Amount Bucket Map (`%1000`)
+
+| Slot range | Scenario |
+|---|---|
+| `000-099` | `fast_success` |
+| `100-199` | `slow_success` |
+| `200-299` | `fail_immediate` |
+| `300-399` | `fail_timeout` |
+| `400-499` | `stuck_pending` |
+| `500-599` | `retry_then_success` |
+| `600-699` | `webhook_delayed_success` |
+| `700-799` | `slow_then_fail` |
+| `800-899` | `partial_progress_stuck` |
+| `900-999` | `chaos` (deterministic by idempotency key) |
+
+## Request Usage
+
+### Through Connector `SubmitOperation`
+
+Use operation param:
+
+- `scenario` (optional)
+
+or put it inside `metadata` as:
+
+- `chsettle_scenario`
+
+### Through Gateway `SubmitTransfer`
+
+Set metadata key directly:
+
+- `chsettle_scenario`
+
+## Dev Environment
+
+Compose service:
+
+- `dev-chsettle-gateway`
+
+Ports:
+
+- gRPC: `50080`
+- metrics: `9406`
+
+Start only this gateway:
+
+```bash
+docker compose -f docker-compose.dev.yml --env-file .env.dev up -d dev-chsettle-gateway
+```
+
+## Logging
+
+ChimeraSettle emits:
+
+- `info` logs for scenario decisions and transition milestones
+- `warn` logs for recoverable/non-fatal errors
+- `error` logs for startup-fatal failures
+- detailed `debug` logs for request execution tracing