docs: write for end users and add comparison with jasonxu114514/opencode2api

- Drop developer-facing details from user docs: the tool-lock section
  no longer narrates probe results or request-shape internals, and the
  2.x troubleshooting entry now states the symptom and the fix instead
  of the API-migration backstory.
- READMEs open with a fact-based comparison against the same-named
  jasonxu114514/opencode2api Go gateway (approach, compatibility model,
  runtime deps, protocols, tool support, multi-user operation,
  license) with guidance on when each fits.

Author: TiaraBasori

README.en.md

@@ -10,6 +10,23 @@ English | [简体中文](./README.md)
 
 Turns a local [OpenCode](https://opencode.ai) runtime into an OpenAI-compatible API gateway, so any client can use unlimited free OpenCode Zen models.
 
+## 🆚 Comparison with jasonxu114514/opencode2api
+
+There is another project with the same name, [jasonxu114514/opencode2api](https://github.com/jasonxu114514/opencode2api): a Go gateway that talks to the OpenCode cloud service directly (single binary, built-in WebUI, multi-key/proxy pools, and an Anthropic Messages endpoint), aimed at shared multi-user operation. The two projects take different approaches:
+
+| | This project | jasonxu114514/opencode2api |
+|:---|:---|:---|
+| How it works | Runs the **real OpenCode CLI** locally and proxies its local API | Standalone Go gateway that emulates the official client against the cloud |
+| Free-model compatibility | Requests come from the official client itself — updating the backend keeps up with upstream policy changes | Relies on the project emulating official client behavior; needs project updates to catch up |
+| Runtime requirements | Node.js 18+ and the OpenCode CLI | None — a single Go binary |
+| API protocol | OpenAI-compatible (Chat Completions / Responses, with SSE) | OpenAI-compatible + Anthropic Messages |
+| Reasoning control | `reasoning_effort` passed through directly | `auto` probing mode (probe requests consume upstream allowance) |
+| Client-defined tools | Supported: the client declares `tools` and the proxy returns standard `tool_calls` | Forwarded (the anonymous free lane is constrained by the official tool-list validation) |
+| Multi-user operation | None (single-machine, personal use) | Key/proxy pools, WebUI console, per-key usage stats |
+| License | MIT | GPL-3.0 |
+
+**Which to pick**: for personal use, exact parity with official client behavior, or making your client's own tools work, use this project. For an Anthropic endpoint, sharing one gateway across several users (key pools + usage dashboard), or a zero-dependency single-binary deployment, use the jasonxu version. Both can also run side by side.
+
 ## ✨ Features
 
 - **OpenAI compatible** — `/v1/models`, `/v1/chat/completions`, `/v1/responses` with full SSE streaming

README.md

@@ -10,6 +10,23 @@
 
 把本地 [OpenCode](https://opencode.ai) 运行时转换为 OpenAI 兼容 API 网关，在任何客户端中使用不限量的 OpenCode Zen 免费模型。
 
+## 🆚 与 jasonxu114514/opencode2api 的对比
+
+社区里还有另一个同名项目 [jasonxu114514/opencode2api](https://github.com/jasonxu114514/opencode2api)：一个直连 OpenCode 云端服务的 Go 网关（单二进制、内置 WebUI、支持多 key/代理池和 Anthropic Messages 端点），面向多用户共享运营。两者目标不同：
+
+| | 本项目 | jasonxu114514/opencode2api |
+|:---|:---|:---|
+| 工作方式 | 运行**真实的 OpenCode CLI** 并代理其本地接口 | 独立 Go 网关，直接模拟官方客户端请求云端 |
+| 免费模型兼容性 | 请求由官方客户端本体发出，官方策略变化时升级后端即可跟进 | 依赖项目代码模拟官方客户端行为，需等项目发布更新 |
+| 运行依赖 | Node.js 18+ 与 OpenCode CLI | 无，单个 Go 二进制 |
+| API 协议 | OpenAI 兼容（Chat Completions / Responses，含 SSE） | OpenAI 兼容 + Anthropic Messages |
+| 推理控制 | `reasoning_effort` 直接透传 | `auto` 探测模式（探测请求会消耗上游额度） |
+| 客户端自定义工具 | 支持：客户端声明 `tools`，代理返回标准 `tool_calls` | 支持转发（匿名免费通道受官方工具列表校验约束） |
+| 多用户运营能力 | 无（单机自用定位） | key 池/代理池、WebUI 管理台、按 key 用量统计 |
+| 许可证 | MIT | GPL-3.0 |
+
+**怎么选**：个人使用、希望与官方客户端行为完全一致、或需要让客户端自带工具生效，选本项目；需要 Anthropic 端点、多人共享一个网关（key 池 + 配额面板）、或想要零依赖的单二进制部署，选 jasonxu 版。两者也可以并存部署。
+
 ## ✨ 功能特性
 
 - **OpenAI 兼容** — `/v1/models`、`/v1/chat/completions`、`/v1/responses`，完整 SSE 流式输出

docs/en/configuration.md

@@ -82,7 +82,7 @@ Env vars use the `OPENCODE_` prefix; config.json uses the short names (see table
 
 ### Tool-Lock Plugin
 
-OpenCode Zen free models fingerprint requests: the tool list must match the official client's **verbatim** (a list-shape check, not a minimum tool count). Live-tested 2026-10-15 against backend 1.19.0: a request that strips tools via `tools:{id:false}` is rejected (`free tier can only be used from within OpenCode`), while a bare request with no `tools` field at all passes. So the backend the proxy starts loads `plugin/opencode2api-tool-lock.js`: the tool list stays intact, the tool policy rides in the session title, and the plugin blocks tools at execution time.
+The OpenCode service rejects requests whose tool list has been modified (with the error `free tier can only be used from within OpenCode`). The proxy therefore loads `plugin/opencode2api-tool-lock.js` into the backend it starts automatically: the tool list stays intact, the tool policy rides in the session title, and the plugin blocks tools at execution time. No configuration needed.
 
 - With a backend you start yourself (`MANAGE_BACKEND=false`), add the absolute path of that file to the backend's `plugin` config. Otherwise the proxy falls back to per-request tool overrides and free models are rejected.
 

docs/en/troubleshooting.md

@@ -53,14 +53,14 @@ You can also point to the full binary path via `OPENCODE_PATH`.
 
 ### Empty model list / completions fail, logs show `/config/providers` errors
 
-The backend is OpenCode 2.x. 2.x moved the server API under `/api/*` and removed the 1.x routes used by the bundled SDK, so it is incompatible with this proxy (the proxy rejects it at startup: `OpenCode backend 2.x is not compatible`). Downgrade to the newest 1.x release:
+The installed backend is OpenCode 2.x. This proxy currently supports OpenCode 1.x backends only and refuses 2.x at startup with `OpenCode backend 2.x is not compatible`. Install the newest 1.x release:
 
 ```bash
 npm install -g opencode-ai@1.19.0
 # or point OPENCODE_PATH at a 1.x binary
 ```
 
-There is no JS SDK for 2.x yet; do not upgrade the backend until the proxy supports it.
+Keep OpenCode on 1.x and do not upgrade until the proxy announces 2.x support.
 
 ### Docker container fails to start
 

docs/zh/configuration.md

@@ -82,7 +82,7 @@
 
 ### 工具锁插件
 
-OpenCode Zen 免费模型对请求做客户端指纹校验：工具列表必须与官方客户端**逐字一致**（是列表形状校验，不是工具数量下限）。实测（2026-10-15，后端 1.19.0）：带 `tools:{id:false}` 剥离的请求会被拒绝（`free tier can only be used from within OpenCode`），完全不带 `tools` 字段的裸请求反而能通过。因此代理拉起后端时会加载 `plugin/opencode2api-tool-lock.js`：工具列表保持原样，工具策略写在会话标题里，由插件在执行时拦截。
+OpenCode 官方服务会拒绝工具列表被改动的请求（报错 `free tier can only be used from within OpenCode`），因此代理拉起后端时会自动加载 `plugin/opencode2api-tool-lock.js`：工具列表保持原样，工具策略写在会话标题里，由插件在执行时拦截。整个过程无需任何配置。
 
 - 使用自行启动的后端（`MANAGE_BACKEND=false`）时，需要把该文件的绝对路径加入后端配置的 `plugin` 列表，否则代理退回按请求关闭工具，免费模型会被拒绝。
 

docs/zh/troubleshooting.md

@@ -53,14 +53,14 @@ npm install -g opencode-ai@1.19.0
 
 ### 模型列表为空 / 补全报错，日志出现 `/config/providers` 失败
 
-后端是 OpenCode 2.x。2.x 把 server API 挪到了 `/api/*` 下并移除了 1.x 路由，与本代理内置的 SDK 1.x 不兼容（代理启动时会在健康检查处直接报 `OpenCode backend 2.x is not compatible`）。降到 1.x 线最新版：
+后端装的是 OpenCode 2.x。本代理目前仅兼容 OpenCode 1.x 后端，检测到 2.x 会在启动时报 `OpenCode backend 2.x is not compatible`。安装 1.x 线最新版：
 
 ```bash
 npm install -g opencode-ai@1.19.0
 # 或 OPENCODE_PATH 指向 1.x 二进制
 ```
 
-注意 2.x 没有可用的 JS SDK，在后端适配 2.x 之前请勿升级。
+在代理支持 2.x 之前，请保持 OpenCode 为 1.x，不要升级。
 
 ### Docker 容器无法启动