Docs: validate MCP + identify curl examples, inventory_ratio convention, Redis key schema

Made-with: Cursor

docs/02-architecture/AI_AGENTS_57XX_DEPLOYMENT_PLAN.md

@@ -505,7 +505,50 @@ The **canonical implementation** lives in the **ai-mcp-pmm-controller** submodul
 ### Interface discovery and liquidity fields
 
 - **`dodo.identify_pool_interface`:** Implemented. Read-only tool; does not require the pool to be in the allowlist. Probes candidate getters (getMidPrice, getOraclePrice, getBaseReserve, _BASE_BALANCE_, getPMMState, etc.) and returns `detected_profile` (e.g. `dodo_pmm_v2_like` or `unknown`), `functions_found`, and `notes`. Use it with any pool address to choose the right ABI/profile before adding to allowlist.
-- **To complete liquidity fields (no trial-and-error):** Provide **one Arbitrum pool contract address** (or DODO type/version). Then: minimal ABI for reserves/state, `pool_profiles.json` additions, and `server.py` diff for `liquidity_base`, `liquidity_quote`, `inventory_ratio`. Optional: Redis keys `cb:<chain>:<pool>` and `cooldown:<chain>:<pool>` for circuit breaker and cooldown state.
+- **To complete liquidity fields (no trial-and-error):** Provide **one Arbitrum pool contract address** (or DODO type hint: DPP/DSP/DVM/PMM V2). Then: minimal ABI for reserves/state, `pool_profiles.json` additions, and `server.py` diff for `liquidity_base`, `liquidity_quote`, `inventory_ratio`.
+
+### Validate MCP hub and run interface discovery (before you have a pool)
+
+**On VM 5701:**
+
+```bash
+cd /opt/proxmox/ai-mcp-pmm-controller
+docker compose --env-file .env up -d
+curl -fsS http://127.0.0.1:3000/health
+```
+
+**Run interface discovery** (from 5701 or from 5703 calling MCP) once you have any candidate pool address:
+
+```bash
+curl -sS http://127.0.0.1:3000/mcp/call \
+  -H 'content-type: application/json' \
+  -d '{"tool":"dodo.identify_pool_interface","params":{"pool":"0xPOOL"}}' | jq
+```
+
+- `functions_found` → which getters exist on that contract  
+- `notes` → which reserve/state methods are missing  
+- `detected_profile` → whether `dodo_pmm_v2_like` fits or you need a new profile  
+
+### Inventory ratio convention
+
+Standardized so it’s comparable across pool types (unless the pool exposes a canonical ratio):
+
+- `base_value = base_reserve * mid_price`
+- `quote_value = quote_reserve` (in quote units)
+- **`inventory_ratio = base_value / (base_value + quote_value)`**
+
+Used consistently in `dodo.get_pool_state` and for policy thresholds.
+
+### Optional Redis state (circuit breaker + cooldown)
+
+When `REDIS_URL` is set, use this key schema; if unset, degrade to stateless mode.
+
+| Key | Value (example) | Purpose |
+|-----|-----------------|---------|
+| `cb:<chain>:<pool>` | `{ "tripped": true, "reason": "...", "ts": 170... }` | Circuit breaker state |
+| `cooldown:<chain>:<pool>` | Unix timestamp of next allowed action time | Cooldown window |
+
+Wire into `dodo.risk_check` and (later) write tools. Implementation: optional Redis client; if `REDIS_URL` missing, skip reads/writes and keep behavior stateless.
 
 ---