docs: OpenCode 2.x usage — recommend bili paths, fix stale /acp note

[ranxianglei]

What

Consolidate all scattered OpenCode content in both READMEs into ONE ## OpenCode section, and document the client-native install paths beside bili plugin install (per review feedback on #985). Rebased onto current master — resolves the previous merge conflict.

Changes (README.md + README.zh-CN.md, docs-only)

1. One ## OpenCode section replaces six scattered spots.

• Removed: the two separate opencode rows in "Which do I need?" (now one row pointing to the guide), the standalone legacy v1-lane paragraph, the Option-1 note bullet, the long launcher-table comment, the ### OpenCode 1.x section, and the ### OpenCode 专属说明 section.
• Inserted: a single ## OpenCode section before "Running the proxy" with subsections Launcher / Native / Pure proxy / Status (/acp + acp_status) / Legacy opencode-acp sessions (opencode v1: keep opencode-acp legacy sessions working after switching to bili #920) / Caveats. All previously-documented mechanics are preserved (dual-shape V1 server() + V2 setup(), entry form by bili install source incl. git-checkout shim dir, self-spawn + watchdog, runtime-info catalog reporting [native] runtime-info protocol: plugins report real model config (model / contextWindow / maxOutput) to the proxy #955, legacy session routing opencode v1: keep opencode-acp legacy sessions working after switching to bili #920, verified versions 2.0.3 / 1.14.46 / 1.18.31).
• Cross-references wired up: table row, Option-1 notes, and launcher line all point to [OpenCode](#opencode).

2. Option 1 now documents client-native installs (not only bili plugin install).

• dsh: dsh plugin --profile <name> add billion-context — the very command the installer drives per profile; same end state, remove through the same channel.
• opencode: hand-write "plugin": ["billion-context"] (bare npm name) into your real config — the package publishes exports["./server"] → dist/agent/opencode-native.js, so opencode loads it via its own Npm.add machinery. With the two caveats the bili installer would have handled: set "compaction": { "auto": false } yourself (the V1/V2 plugins only report compaction boundaries, they never disable auto-compaction — verified in src/agent/opencode-v2.ts / opencode-native.ts) and back up the file first.
• pi / omp / kimi / claude: explicitly noted as having no client-side channel — bili plugin install <client> writes their config entries for you.

3. Structural cleanup from the consolidation: the now-orphaned #### dsh and #### Kimi Code sections are re-leveled to ###.

Verification

• All splice markers asserted unique (script .tmp/rewrite-readme-r3.py, not committed); failed-marker runs restored via git checkout -- before retry.
• Heading map re-checked for both languages: single ## OpenCode, no leftover ### OpenCode 1.x / ### OpenCode 专属说明, no stale cross-references (grep clean).
• Code claims verified against source: package.json exports, compaction handling in agent files, PI_NPM_ENTRY (pi uses npm: form, not bare name — deliberately not claimed as hand-installable).
• Base: master @ 409b397 (single fresh commit dac9b8a; branch force-updated).

Closes #985

[github-actions]

📦 Built Package Artifact

Branch: 2026-09-19_readme-opencode-v2 (dac9b8a)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-986

Each push to this PR publishes a new version under the pr-986 npm tag.

Option B — Download artifact

1. Download the artifact from the Actions run
2. Extract the tarball and install:

tar xzf billion-context-pr986.tgz
npm install -g package

---

Install instructions are refreshed on each push.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Received — this is the docs PR for #985. I'm reviewing the branch (2026-09-19_readme-opencode-v2): checking the diff scope, cross-checking every claim against src/agent/opencode-v2.ts / src/agent/opencode-native.ts / src/launcher.ts, and confirming CI status. Full verdict coming shortly.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review complete — verified against current code, one typo fixed in-place, CI fully green. Mergeable.

Diff scope ✅ Docs only: README.md + README.zh-CN.md, +23/−13, single linear commit, no source/test/config churn, no whitespace noise. zh/en in sync — all three hunks (intro, launcher bullet, caveats) correspond between languages.

Claim verification (against src/agent/opencode-v2.ts, unchanged since this branch's base):

1. Recommendation intro — matches the provenance record in src/agent/opencode-v2.ts:20-31 (end-to-end verified on @opencode/cli 2.0.1 + 2.0.3: true plugin mode, native tools via the plugin endpoint, zero wire-level injection). Both paths exist and are wired: launcher (src/launcher.ts) and bili plugin install opencode (src/agent/opencode-native.ts). Consistent with the existing "Which do I need?" table.
2. Catalog read → runtime-info — exact match: WINDOW_REFRESH_MS = 60000 (src/agent/opencode-v2.ts:107), ctx.catalog?.model?.list?.() (:131), per-request stamping of x-bili-plugin-context-window / x-bili-plugin-max-output plus reportRuntimeInfoOnChange(...) (:174-178) — the same [native] runtime-info protocol: plugins report real model config (model / contextWindow / maxOutput) to the proxy #955 protocol the README's runtime-info section documents.
3. Stale /acp note — correctly fixed. src/agent/opencode-v2.ts:242-315: /acp registered via ctx.command.transform(editor.add(...)) inside try/catch (warns "command registration unavailable; continuing without it" → inert on older shapes), rendered through ctx.session.synthetic({resume:false}) (synthetic non-model message), panel-first via status.panel. The old "deliberately registers no commands" sentence was indeed stale since opencode 2.x: no-launcher npm-plugin deployment — plugins: ["billion-context"], plugin lazily spawns the proxy #809.

Fixed directly on the branch (per review discipline, small fix inside a line this PR already rewrote):

• README.zh-CN.md:232 — pre-existing typo 插件保持情性 → 插件保持惰性 ("stays inert"; the PR's own new caveats sentence uses the correct 惰). Pushed as d85ce19.

Reported, not touched (kept out of the diff to stay clean):

• README.zh-CN.md ~line 254: the 注意事项 paragraph sits directly above ### 客户端用 http.proxy… with no blank line (pre-existing formatting quirk; renders fine).
• Base staleness: branch base b6c2ef3 is ~15 commits behind current master (519634b), but GitHub reports mergeable: true with no conflicts, and master's README churn since the base is confined to other client rows (kimi/omp/dsh/claude) — no semantic overlap with the OpenCode section. No rebase required.

CI on new head d85ce19: all 8 checks pass — test ubuntu-latest 22/24, windows-latest 22/24, both codex e2e gates, version-guard, build-artifact.

中文摘要:核对了 PR 里三处文档声明与 src/agent/opencode-v2.ts 实际代码(目录读取+60s 刷新+runtime-info、/acp 命令注册与惰性回退),全部属实;顺手修掉了被本 PR 重写的行里遗留的错别字「情性→惰性」(commit d85ce19),CI 全绿,可以合并。