docs: recommend native protocols + translation issue reporting guide

- README (EN + zh-CN mirror): Protocol fidelity note under API
  Reference — native endpoints preferred, cross-protocol is
  best-effort (messages inbound only), rule out backend flakiness
  then file an issue with minimal repro.
- architecture.md section 5: user-facing guidance mirroring READMEs.
- troubleshooting.md: new cross-protocol FAQ (exclude flakiness:
  retry, /health/details, native-endpoint repro, DEBUG capture)
  plus redacted issue checklist.
- CONTRIBUTING.md: bug reports require flakiness exclusion and, for
  translation bugs, endpoint + direction + minimal JSON + native repro.

Author: samson910022

CONTRIBUTING.md

@@ -11,11 +11,13 @@ Please be respectful and professional. We follow the [Contributor Covenant](http
 ### Reporting Bugs
 
 1. Check if the issue already exists
-2. Create a detailed issue with:
+2. Rule out backend flakiness first: retry the request and check backend status (`GET /health/details`)
+3. Create a detailed issue with:
    - Clear title and description
    - Steps to reproduce
    - Environment details
-   - Relevant logs
+   - Relevant logs (redact `API_KEY` and other secrets)
+   - For suspected protocol-translation bugs: the endpoint plus the translation direction (e.g. messages→chat), a minimal request JSON, expected vs actual response, and whether the native-protocol endpoint reproduces it
 
 ### Suggesting Features
 

README.md

@@ -322,6 +322,10 @@ OPENCODE_PROXY_AUTO_CLEANUP_CONVERSATIONS=true
 | `POST` | `/v1beta/interactions` | Gemini-compatible thin layer (text + `google_search` grounding, `previous_interaction_id`, `store`, SSE without `[DONE]`) |
 | `POST` | `/v1/interactions` | Alias of `/v1beta/interactions` |
 
+### Protocol fidelity
+
+Use the endpoint native to your client (OpenAI SDKs → `/v1/chat/completions` or `/v1/responses`, Anthropic SDKs → `/v1/messages`, Gemini SDKs → `/v1beta/interactions`). Cross-protocol conversion is best-effort and only wired where documented (currently `POST /v1/messages` inbound): non-native paths may drop or zero-fill tool deltas, thinking signatures, token usage, and truncation signals (see [Architecture](./docs/architecture.md#5-nn-translator-registry-srcconverters)). If output looks wrong, first reproduce on the native endpoint and rule out backend flakiness (retry, check `/health/details`); if it persists, file an issue with a minimal repro (see [Troubleshooting](./docs/troubleshooting.md)).
+
 ### Model name formats
 
 - Direct: `opencode/big-pickle`

README.zh-CN.md

@@ -323,6 +323,10 @@ OPENCODE_PROXY_AUTO_CLEANUP_CONVERSATIONS=true
 | `POST` | `/v1beta/interactions` | Gemini 兼容薄层（文本 + `google_search` 联网、`previous_interaction_id`、`store`、SSE 无 `[DONE]`） |
 | `POST` | `/v1/interactions` | `/v1beta/interactions` 的别名 |
 
+### 协议保真度
+
+请使用与客户端原生对应的端点（OpenAI SDK → `/v1/chat/completions` 或 `/v1/responses`，Anthropic SDK → `/v1/messages`，Gemini SDK → `/v1beta/interactions`）。跨协议转换是 best-effort，且仅在已接线处生效（目前为 `POST /v1/messages` 入站）：非原生路径可能丢失或零填充工具增量、thinking 签名、token 用量与截断信号（见 [Architecture](./docs/architecture.md#5-nn-translator-registry-srcconverters)）。若输出异常，请先在原生端点复现并排除后端波动（重试、检查 `/health/details`）；确认存在后再附最小复现提 issue（见 [故障排查](./docs/troubleshooting.md)）。
+
 ### 模型名称格式
 
 - 直接使用: `opencode/big-pickle`

docs/architecture.md

@@ -158,6 +158,15 @@ Wiring status (live, not tests-only):
 - TokenCount stays unregistered — use `isTokenCountRegistered(registry)`
   (live registry query).
 
+User-facing guidance (also stated in both READMEs and
+`docs/troubleshooting.md`): clients should use their native protocol
+endpoint. Only `POST /v1/messages` inbound goes through the registry
+today; every other cross-protocol path is best-effort and may degrade
+(TEXT-CORE: dropped tool/thinking deltas, zero-filled usage, lost
+truncation signals). Suspected translation bugs must be reproduced on the
+native endpoint first — ruling out backend flakiness — and reported with
+a minimal repro.
+
 ## 6. Roadmap (accepted, not yet implemented)
 
 - Extract shared `preflight(ctx, body)` (resolve model → tool context →

docs/troubleshooting.md

@@ -118,6 +118,29 @@ curl -H "Authorization: Bearer YOUR_API_KEY" ...
 
 ---
 
+### 9️⃣ 跨协议转换结果异常
+
+| 项目 | 说明 |
+|:-----|:-----|
+| **症状** | 非原生协议客户端收到缺字段、空工具调用、`usage` 为 0、截断信号丢失 |
+| **说明** | 网关建议各客户端使用原生协议端点（OpenAI SDK → `/v1/chat/completions` 或 `/v1/responses`，Anthropic SDK → `/v1/messages`，Gemini SDK → `/v1beta/interactions`）。跨协议转换是 best-effort，目前仅 `POST /v1/messages` 入站走转换矩阵，其余路径可能降级（纯文本 + 零填充用量），属已知限制而非后端故障 |
+
+提 issue 前请先排除偶发因素：
+
+```bash
+# 1. 重试一次，并检查后端状态（排除波动/限流）
+curl -H "Authorization: Bearer YOUR_API_KEY" http://127.0.0.1:10000/health/details
+
+# 2. 用原生协议端点复现同一请求（确认是转换问题，而非模型/后端问题）
+
+# 3. 开调试日志抓最小复现
+OPENCODE_PROXY_DEBUG=true
+```
+
+提 issue 时请附（并删掉 `API_KEY` 等密钥）：端点 + 协议方向（如 messages→chat）、最小请求 JSON、期望 vs 实际响应、模型 ID、原生端点是否同样复现。
+
+---
+
 ## 🔍 调试模式
 
 开启调试日志: