cosmos: document Polkachu FULL snapshot bootstrap for gaiad

cosmos/scripts/README.cometbft.md

@@ -0,0 +1,39 @@
+# Cosmos Hub (gaiad) — CometBFT bootstrap notes
+
+Operator guidance for fresh provisioning of the cosmos-hub gaiad node. See also the shared
+family-C reference at `rpc/scripts/README.cometbft.md`.
+
+## Fresh bootstrap: use a Polkachu FULL snapshot
+
+For a wasm chain like cosmos-hub, prefer seeding from a **Polkachu FULL snapshot** over
+state-sync. The full archive includes everything on disk — application state, `wasm/`, and
+`data/08-light-client/` (IBC 08-wasm bytecode) — so gaia does not panic with
+`wasmlckeeper failed initialize pinned codes / Error opening Wasm file` on first start.
+
+Snapshot URL pattern:
+
+```
+https://snapshots.polkachu.com/snapshots/cosmos/cosmos_<HEIGHT>.tar.lz4
+```
+
+Replace `<HEIGHT>` with the height published on the Polkachu cosmos snapshot page. Extract
+into the node data volume (`/root/.gaia`) before `docker compose up`.
+
+## CL_VERSION must match the live chain
+
+Cosmos chains upgrade via governance; an old binary halts at the upgrade height or panics
+`upgrade handler is missing for vX.Y.Z`. Before pinning `CL_VERSION` / `COSMOS_MAINNET_GAIAD_VERSION`,
+check the live app version on Polkachu RPC:
+
+```sh
+curl -s https://cosmos-rpc.polkachu.com/abci_info | jq .result.response.version
+```
+
+The Docker image tag must match that version (verify pullability with a manifest HEAD, not
+only the ghcr tags list — it can lag).
+
+## Traefik WebSocket routing
+
+The split-WS router uses `HeadersRegexp('Upgrade','(?i)websocket')` (case-insensitive). Clients
+sending `Upgrade: WebSocket` (e.g. python websocket-client) require this — a case-sensitive
+`Headers('Upgrade','websocket')` matcher falls through to the RPC router (400/200 instead of 101).