opencode-tbot 0.1.33 → 0.1.35

package/README.ja.md

@@ -1,29 +1,31 @@
 # opencode-tbot
 
-チャットから [OpenCode](https://opencode.ai) を操作するための Telegram プラグインです。
+Telegram から [OpenCode](https://opencode.ai) を操作するためのプラグインです。
 
 [English](./README.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md)
 
-> このプロジェクトは OpenCode チームによって開発されたものではなく、公式な関連もありません。
+> このプロジェクトは OpenCode チームによって開発されたものではなく、公式プロジェクトでもありません。
 
 ## 概要
 
-`opencode-tbot` を使うと、Telegram から OpenCode を操作できます。
+`opencode-tbot` を使うと、Telegram から OpenCode を操作でき、チャットごとに 1 つのバインド状態を維持できます。
 
-- テキストメッセージは現在アクティブな OpenCode セッションに転送されます。
+- プレーンテキストメッセージは現在の OpenCode セッションに転送されます。
 - Telegram の写真と画像ドキュメントは OpenCode のファイルパートとしてアップロードされます。
-- Telegram の音声メッセージは明示的に拒否され、ローカライズされた返信を返します。
+- 画像を含むターンは一時的に fork したセッションで実行されるため、後続のテキスト専用プロンプトに画像コンテキストが残りません。
 - OpenCode が発行した権限リクエストは、Telegram のインラインボタンから承認または拒否できます。
 - セッションエラーイベントは、紐付けられた Telegram チャットへ通知できます。
-- チャットの紐付け状態は JSON の state ファイルに保存されます。
+- 音声メッセージは明示的に拒否され、ローカライズされた案内を返します。
+- チャットのバインドとセッション選択状態は JSON の state ファイルに保存されます。
 
 ## 前提条件
 
-- このプラグインを読み込む OpenCode ホストプロセスが動作していること。
+- このプラグインを読み込む OpenCode Host プロセスが動作していること。
 - Telegram bot token を用意していること。
-- CLI とローカル開発には Node.js `>=22.12.0` が必要です。
+- CLI とローカル開発のために Node.js `>=22.12.0` が必要です。
+- リポジトリ開発には `pnpm` が必要です。
 
-## インストール
+## インストールと更新
 
 推奨インストール方法:
 
@@ -31,9 +33,15 @@
 npm exec --package opencode-tbot@latest opencode-tbot -- install
 ```
 
-インストーラーはプラグインをグローバルに登録し、実際に使われる OpenCode のグローバル設定ファイルを更新し、デフォルトのランタイム設定を書き込みます。あわせて OpenCode 設定パス、プラグイン設定パス、既定のログディレクトリを表示します。
+インストーラーは次を行います。
 
-`~/.config/opencode/opencode.jsonc` が既に存在する場合はそのファイルを優先して更新し、存在しない場合は `~/.config/opencode/opencode.json` を使います。
+- `~/.config/opencode/plugins/opencode-tbot.js` を書き込み
+- 必要な親ディレクトリがなければ自動で作成
+- グローバルのプラグイン実行設定を作成またはマージ
+- 古い `opencode-tbot` の npm 登録がグローバル OpenCode 設定に残っていれば削除し、二重読み込みを防止
+- OpenCode 設定パス、プラグイン bridge パス、プラグイン設定パス、既定のプラグインログディレクトリを表示
+
+`~/.config/opencode/opencode.jsonc` または `~/.config/opencode/opencode.json` に古い `opencode-tbot` の npm 登録が残っている場合、インストーラーが自動で削除し、グローバル bridge に一本化します。
 
 インストール済み CLI のバージョン確認:
 
@@ -41,38 +49,56 @@ npm exec --package opencode-tbot@latest opencode-tbot -- install
 npm exec --package opencode-tbot@latest opencode-tbot -- --version
 ```
 
-OpenCode に登録済みの npm プラグイン spec を更新:
+bot token を変更せず、グローバルプラグイン bridge を更新:
 
 ```bash
 npm exec --package opencode-tbot@latest opencode-tbot -- update
 ```
 
+`install` は既定コマンドです。たとえば、非対話インストールでは次の形でも実行できます。
+
+```bash
+npm exec --package opencode-tbot@latest opencode-tbot -- --bot-token <token>
+```
+
 ### CLI オプション
 
 `install` で利用可能:
 
 - `--bot-token <token>` Telegram bot token を非対話で設定
 - `--telegram-api-root <url>` Telegram Bot API のベース URL を上書き
-- `--plugin-spec <spec>` カスタム npm プラグイン spec を登録
-- `--skip-register` OpenCode 側のプラグイン登録は変更せず、プラグイン設定だけを書き換え
+- `--plugin-spec <spec>` 非推奨。無視されます
+- `--skip-register` グローバルプラグイン bridge を変更せず、プラグイン設定だけを書き換え
 - `--home-dir <path>` カスタム home ディレクトリを使用
 
 `update` で利用可能:
 
-- `--plugin-spec <spec>`
+- `--plugin-spec <spec>` 非推奨。無視されます
 - `--home-dir <path>`
 
 ## 設定
 
-ランタイム設定は `~/.config/opencode/opencode-tbot/config.json` からのみ読み込まれます。
+ランタイム設定は次のパスからのみ読み込まれます。
+
+- `~/.config/opencode/opencode-tbot/config.json`
+
+OpenCode はこのプラグインのグローバル bridge を次の場所から読み込みます。
 
-OpenCode のプラグイン登録はグローバル OpenCode 設定に保存されます。`~/.config/opencode/opencode.jsonc` がある場合はそれを使い、なければ `~/.config/opencode/opencode.json` を使います。
+- `~/.config/opencode/plugins/opencode-tbot.js`
 
-古い `<worktree>/tbot.config.json` はランタイムでは無視されます。検出された場合は、値をグローバル設定へ移行できるように警告ログを出します。
+古い npm 登録の移行時だけ、インストーラーは次のグローバル OpenCode 設定を必要に応じて掃除します。
 
-古い `openrouter` 音声転写設定はランタイムでは無視され、インストーラーが設定を書き直す際にも削除されます。
+- `~/.config/opencode/opencode.jsonc`
+- `~/.config/opencode/opencode.json`
 
-### グローバル `config.json` の例
+このプラグインは `.env` からランタイム設定を読み込みません。グローバル JSON 設定を使ってください。
+
+レガシー挙動:
+
+- `<worktree>/tbot.config.json` はランタイムで無視されます。見つかった場合は移行用の警告ログが出ます
+- 古い `openrouter` 音声文字起こし設定はランタイムで無視され、インストーラーが設定を書き直す際にも削除されます
+
+### `config.json` の例
 
 ```json
 {
@@ -89,55 +115,100 @@ OpenCode のプラグイン登録はグローバル OpenCode 設定に保存さ
     "pollRequestTimeoutMs": 15000,
     "recoveryInactivityTimeoutMs": 120000
   },
+  "logging": {
+    "level": "info",
+    "sinks": {
+      "host": true,
+      "file": true
+    },
+    "file": {
+      "dir": "C:/Users/your-user/.local/share/opencode/log/plugins/opencode-tbot",
+      "retention": {
+        "maxFiles": 30,
+        "maxTotalBytes": 314572800
+      }
+    }
+  },
   "logLevel": "info"
 }
 ```
 
-### フィールド
+### 設定項目
 
-| フィールド | 必須 | デフォルト | 説明 |
+| 項目 | 必須 | 既定値 | 説明 |
 | --- | --- | --- | --- |
-| `telegram.botToken` | はい | - | Telegram bot token。通常はインストーラーがグローバルプラグイン設定へ書き込みます。 |
-| `telegram.allowedChatIds` | いいえ | `[]` | 許可する Telegram chat ID の配列。空の場合はすべての chat を受け付けます。 |
-| `telegram.apiRoot` | いいえ | `https://api.telegram.org` | Telegram Bot API のベース URL。テストやセルフホストのゲートウェイ向けです。 |
+| `telegram.botToken` | はい | - | Telegram bot token。通常はインストーラーがグローバル設定に書き込みます。 |
+| `telegram.allowedChatIds` | いいえ | `[]` | 許可する Telegram chat ID。一覧が空なら任意の chat を受け付けます。 |
+| `telegram.apiRoot` | いいえ | `https://api.telegram.org` | Telegram Bot API のベース URL。テストやセルフホスト環境向けです。 |
 | `state.path` | いいえ | `./data/opencode-tbot.state.json` | JSON state ファイルのパス。現在の OpenCode worktree からの相対パスとして解決されます。 |
-| `logLevel` | いいえ | `info` | プラグインのログレベル。ログは `client.app.log()` 経由で出力されます。 |
+| `prompt.waitTimeoutMs` | いいえ | `1800000` | 1 回の非同期 prompt ライフサイクル全体に対する待機上限。 |
+| `prompt.pollRequestTimeoutMs` | いいえ | `15000` | OpenCode への各 recovery poll リクエストのタイムアウト。 |
+| `prompt.recoveryInactivityTimeoutMs` | いいえ | `120000` | 進捗が止まった場合にのみ適用される recovery タイムアウト。 |
+| `logging.level` | いいえ | `info` | host/file 両方に使う構造化ログレベル。`debug`、`info`、`warn`、`error` に正規化されます。 |
+| `logging.sinks.host` | いいえ | `true` | `client.app.log({ body: ... })` 経由で OpenCode Host ログへ書き込むかどうか。 |
+| `logging.sinks.file` | いいえ | `true` | プラグイン独自の JSONL ファイルログを有効にするかどうか。 |
+| `logging.file.dir` | いいえ | `%USERPROFILE%/.local/share/opencode/log/plugins/opencode-tbot` | プラグイン JSONL ログのディレクトリ。相対パスは現在の OpenCode worktree 基準で解決されます。 |
+| `logging.file.retention.maxFiles` | いいえ | `30` | 保持するプラグインログファイル数の上限。 |
+| `logging.file.retention.maxTotalBytes` | いいえ | `314572800` | 保持するプラグインログ合計サイズの上限。 |
+| `logLevel` | いいえ | `info` | `logging.level` の互換エイリアス。後方互換のため引き続き利用できます。 |
 
 ### 補足
 
 - `state.path` は現在の OpenCode worktree からの相対パスとして解決されます。
+- `logging.file.dir` が相対パスの場合も現在の worktree から解決されます。
+- Telegram の prompt 処理は async-first です。プラグインは `session.promptAsync()` を送信し、その後メッセージとセッション状態から最終応答を回収します。
 - `telegram.allowedChatIds` を空のままにすると、bot は任意の chat からのメッセージを受け付けます。本番では制限を設定してください。
-- 権限承認とセッションエラー通知はプラグインの hook で処理されます。
-- `/language` は現在 English、简体中文、日本語 をサポートしています。
+- 権限承認とセッションエラー通知はプラグイン hook で処理されます。
+- `/language` は現在 English、简体中文、日本語 をサポートし、その chat 用の Telegram コマンド説明も同期します。
+- ファイルログは既定でメタデータのみを記録し、prompt 本文、添付内容、生の URL、secret は書き込みません。
 
 ## クイックスタート
 
-1. `npm exec --package opencode-tbot@latest opencode-tbot -- install` でプラグインをインストールします。
-2. 特定の chat のみ許可したい場合は、`~/.config/opencode/opencode-tbot/config.json` で `telegram.allowedChatIds` を設定します。
-3. 対象の worktree で OpenCode を起動し、プラグインランタイムを読み込ませます。
-4. Telegram で `/status` を実行し、接続を確認します。
-5. `/new [title]` を実行するか、テキストメッセージを直接送信して使い始めます。
+1. `npm exec --package opencode-tbot@latest opencode-tbot -- install` を実行します。
+2. 特定の chat だけに制限したい場合は `~/.config/opencode/opencode-tbot/config.json` の `telegram.allowedChatIds` を設定します。
+3. 対象 worktree で OpenCode を起動し、プラグインランタイムを読み込ませます。
+4. Telegram で `/status` を実行して接続を確認します。
+5. `/new [title]` を実行するか、直接テキストメッセージを送信して使い始めます。
 
 ## コマンド
 
-- `/start` 短いウェルカムメッセージとクイックスタート手順を表示
-- `/status` OpenCode のヘルス、パス、プラグイン、LSP、MCP の状態をまとめて表示
-- `/new [title]` 新しい OpenCode セッションを作成
-- `/agents` または `/agent` 利用可能な agent を一覧表示し、アクティブな agent を切り替え
-- `/sessions` 利用可能なセッションを一覧表示し、アクティブなセッションを切り替え
-- `/cancel` セッション名の変更をキャンセルするか、現在のセッションで実行中のリクエストを中止
-- `/model` または `/models` 利用可能なモデルを一覧表示し、アクティブなモデルを切り替え
-- `/language` bot の表示言語を切り替え
+| コマンド | 内容 |
+| --- | --- |
+| `/start` | ウェルカムメッセージとクイックスタートを表示します。 |
+| `/status` | OpenCode のヘルス、バージョン、ワークスペースパス、プラグイン一覧、LSP、MCP の状態をまとめて表示します。 |
+| `/new [title]` | 現在のプロジェクトで新しい OpenCode セッションを作成します。 |
+| `/agents` または `/agent` | 利用可能なエージェントを表示し、現在のエージェントを切り替えます。 |
+| `/sessions` | 利用可能なセッションを表示し、切り替えやリネーム操作を提供します。 |
+| `/cancel` | 保留中のセッション名変更入力をキャンセルするか、現在のセッションで動作中のリクエストを中止します。 |
+| `/model` または `/models` | 利用可能なモデルを表示し、切り替えや推論レベル選択を行います。 |
+| `/language` | 現在の chat に対する bot 表示言語を切り替えます。 |
 
-メッセージ処理:
+### メッセージ動作
 
-- コマンド以外のテキストは prompt として扱われ、OpenCode に送信されます。
+- コマンド以外のテキストは prompt として OpenCode に送信されます。
 - Telegram の写真と画像ドキュメントは OpenCode のファイルパートとして転送されます。
+- 画像添付は現在のセッションの一時 fork 内で処理されるため、後続のテキスト専用コンテキストを汚しません。
+- `/cancel` は OpenCode セッション側の処理と Telegram 側の待機状態を同時に中止し、次の prompt をすぐ開始できるようにします。
 - Telegram の音声メッセージは未対応で、ローカライズされた拒否メッセージを返します。
 
+## ロギング
+
+- OpenCode Host ログディレクトリ: `%USERPROFILE%/.local/share/opencode/log`
+- プラグインログディレクトリ: `%USERPROFILE%/.local/share/opencode/log/plugins/opencode-tbot`
+- ファイル形式: 追記型 JSONL、1 行 1 イベント
+- 代表的な相関フィールド: `runtimeId`, `operationId`, `correlationId`, `updateId`, `chatId`, `sessionId`, `projectId`
+- よく出るコンポーネント: `runtime`, `telegram`, `opencode`, `prompt`, `plugin-event`, `storage`
+- 既定の保持ポリシー: 新しい 30 ファイルまで、合計 300 MB まで
+
 ## 開発
 
-プラグインバンドルをビルド:
+依存関係のインストール:
+
+```bash
+pnpm install
+```
+
+ビルド:
 
 ```bash
 pnpm build
@@ -149,13 +220,27 @@ pnpm build
 pnpm typecheck
 ```
 
-テスト実行:
+通常テストの実行:
 
 ```bash
 pnpm test
 ```
 
-通常の利用では、グローバルにインストールした npm プラグインとグローバル OpenCode 設定を使ってください。このリポジトリには既定の `.opencode/plugins` bridge は含めていません。
+CI に最も近い統合経路の実行:
+
+```bash
+npm install -g opencode-ai
+OPENCODE_HOST_E2E=1 pnpm test
+```
+
+PowerShell の場合:
+
+```powershell
+npm install -g opencode-ai
+$env:OPENCODE_HOST_E2E="1"; pnpm test
+```
+
+通常利用では、自動生成されるグローバル bridge `~/.config/opencode/plugins/opencode-tbot.js` とグローバルプラグイン設定を使ってください。このリポジトリは既定のプロジェクトローカル `.opencode/plugins` bridge を含みません。
 
 このリポジトリでソースベースのローカル読み込みを行いたい場合は、`.opencode/plugins/opencode-tbot.ts` を手動で作成してください。
 
@@ -163,13 +248,17 @@ pnpm test
 export { default } from "../../src/plugin.ts";
 ```
 
-有効にする読み込み経路は常に 1 つだけにしてください。手動で作成したローカル bridge か、グローバルにインストールした `opencode-tbot@latest` のどちらかを使います。
+有効にする読み込み経路は常に 1 つだけにしてください。手動で作成したローカル bridge か、`~/.config/opencode/plugins/` に生成されたグローバル bridge のどちらかを使います。
 
 ## FAQ
 
 ### 実行中の OpenCode インスタンスは必要ですか？
 
-はい。このリポジトリが提供するのは Telegram 連携レイヤーであり、プラグインを読み込む OpenCode ホストプロセスに依存します。
+はい。このリポジトリは Telegram 連携レイヤーのみを提供しており、プラグインを読み込む OpenCode Host プロセスに依存します。
+
+### 生成された bridge が `file:///.../node_modules/...` を指すことがあるのはなぜですか？
+
+通常は、`opencode-tbot` をローカル `node_modules` に持つプロジェクト内でインストーラーを実行したため、生成された bridge がそのパッケージ位置を参照していることを意味します。CLI はその状態を検出すると警告します。そのプロジェクトで `npm uninstall opencode-tbot` を実行してローカル依存を外し、推奨の `npm exec --package ...` インストールフローを使ってください。
 
 ### これは OpenCode の公式プロジェクトですか？
 

package/README.md

@@ -8,23 +8,24 @@ A Telegram plugin for driving [OpenCode](https://opencode.ai) from chat.
 
 ## Overview
 
-`opencode-tbot` lets you operate OpenCode from Telegram.
+`opencode-tbot` lets you operate OpenCode from Telegram with a single bot binding per chat.
 
-- Text messages are forwarded to the active OpenCode session.
+- Plain text messages are forwarded to the current OpenCode session.
 - Telegram photos and image documents are uploaded as OpenCode file parts.
 - Image turns run in a temporary forked session, so later text-only prompts do not inherit image context.
-- Telegram voice messages are explicitly rejected with a localized reply.
 - Permission requests raised by OpenCode can be approved or rejected from Telegram inline buttons.
 - Session error events can be reported back to the bound Telegram chat.
-- Chat bindings are stored in a JSON state file.
+- Voice messages are explicitly rejected with a localized reply.
+- Chat bindings and session selections are stored in a JSON state file.
 
 ## Requirements
 
 - A running OpenCode host process that loads the plugin.
 - A Telegram bot token.
 - Node.js `>=22.12.0` for the CLI and local development workflow.
+- `pnpm` for repository development.
 
-## Install
+## Install And Update
 
 Recommended install:
 
@@ -32,9 +33,15 @@ Recommended install:
 npm exec --package opencode-tbot@latest opencode-tbot -- install
 ```
 
-The installer registers the plugin globally, updates the resolved OpenCode config file, writes the default runtime config, and prints the OpenCode config path, plugin config path, and default plugin log directory.
+The installer:
 
-If `~/.config/opencode/opencode.jsonc` already exists, the installer updates that file. Otherwise it uses `~/.config/opencode/opencode.json`.
+- writes `~/.config/opencode/plugins/opencode-tbot.js`
+- creates missing parent directories automatically
+- writes or merges the global plugin runtime config
+- removes legacy `opencode-tbot` npm registration from the global OpenCode config when present
+- prints the OpenCode config path, plugin bridge path, plugin config path, and default plugin log directory
+
+If `~/.config/opencode/opencode.jsonc` or `~/.config/opencode/opencode.json` already contains an old `opencode-tbot` npm registration, the installer cleans it up so OpenCode only loads the global bridge once.
 
 Check the installed CLI version:
 
@@ -42,38 +49,56 @@ Check the installed CLI version:
 npm exec --package opencode-tbot@latest opencode-tbot -- --version
 ```
 
-Update the registered npm plugin spec in OpenCode:
+Refresh the global plugin bridge without touching your bot token:
 
 ```bash
 npm exec --package opencode-tbot@latest opencode-tbot -- update
 ```
 
+`install` is the default command. For example, this also works for a non-interactive install:
+
+```bash
+npm exec --package opencode-tbot@latest opencode-tbot -- --bot-token <token>
+```
+
 ### CLI Options
 
 `install` supports:
 
 - `--bot-token <token>` set the Telegram bot token non-interactively
 - `--telegram-api-root <url>` override the Telegram Bot API root
-- `--plugin-spec <spec>` register a custom npm plugin spec
-- `--skip-register` only rewrite plugin config without touching OpenCode plugin registration
+- `--plugin-spec <spec>` deprecated; ignored
+- `--skip-register` only rewrite plugin config without touching the global plugin bridge
 - `--home-dir <path>` use a custom home directory
 
 `update` supports:
 
-- `--plugin-spec <spec>`
+- `--plugin-spec <spec>` deprecated; ignored
 - `--home-dir <path>`
 
 ## Configuration
 
-Runtime config is loaded from `~/.config/opencode/opencode-tbot/config.json`.
+Runtime config is loaded only from:
+
+- `~/.config/opencode/opencode-tbot/config.json`
+
+OpenCode loads the plugin bridge from:
+
+- `~/.config/opencode/plugins/opencode-tbot.js`
+
+Legacy npm registration cleanup only touches the global OpenCode config when an older install left `opencode-tbot` in:
+
+- `~/.config/opencode/opencode.jsonc`
+- or `~/.config/opencode/opencode.json`
 
-OpenCode plugin registration is stored in the global OpenCode config (`~/.config/opencode/opencode.jsonc` when present, otherwise `~/.config/opencode/opencode.json`).
+This plugin does not read runtime settings from `.env`. Use the global JSON config instead.
 
-Legacy `<worktree>/tbot.config.json` files are ignored at runtime. If one is present, the plugin logs a warning so you can migrate its values into the global config.
+Legacy behavior:
 
-Legacy `openrouter` voice-transcription settings are ignored at runtime. When the installer rewrites the config, it removes them.
+- `<worktree>/tbot.config.json` is ignored at runtime. If one is present, the plugin logs a warning so you can migrate it.
+- legacy `openrouter` voice-transcription settings are ignored at runtime and removed when the installer rewrites the config
 
-### Example Global `config.json`
+### Example `config.json`
 
 ```json
 {
@@ -119,10 +144,10 @@ Legacy `openrouter` voice-transcription settings are ignored at runtime. When th
 | `prompt.waitTimeoutMs` | No | `1800000` | Maximum total wait for one async prompt lifecycle before the plugin stops waiting for OpenCode recovery. |
 | `prompt.pollRequestTimeoutMs` | No | `15000` | Timeout for each individual recovery poll request to OpenCode. |
 | `prompt.recoveryInactivityTimeoutMs` | No | `120000` | Recovery timeout that only applies when prompt progress stops advancing. |
-| `logging.level` | No | `info` | Structured log level for both host and file sinks. |
+| `logging.level` | No | `info` | Structured log level for host and file sinks. Accepted values normalize to `debug`, `info`, `warn`, or `error`. |
 | `logging.sinks.host` | No | `true` | Enable OpenCode host logging through `client.app.log({ body: ... })`. |
 | `logging.sinks.file` | No | `true` | Enable plugin-owned JSONL file logs. |
-| `logging.file.dir` | No | `%USERPROFILE%/.local/share/opencode/log/plugins/opencode-tbot` | Plugin JSONL log directory. |
+| `logging.file.dir` | No | `%USERPROFILE%/.local/share/opencode/log/plugins/opencode-tbot` | Plugin JSONL log directory. Relative paths are resolved from the current OpenCode worktree. |
 | `logging.file.retention.maxFiles` | No | `30` | Maximum number of retained plugin log files. |
 | `logging.file.retention.maxTotalBytes` | No | `314572800` | Maximum total size of retained plugin log files. |
 | `logLevel` | No | `info` | Legacy alias for `logging.level`. Still accepted for compatibility. |
@@ -130,25 +155,13 @@ Legacy `openrouter` voice-transcription settings are ignored at runtime. When th
 ### Notes
 
 - `state.path` is resolved relative to the current OpenCode worktree.
+- Relative `logging.file.dir` values are also resolved from the current worktree.
 - Telegram prompt handling is async-first: the plugin submits `session.promptAsync()` and then recovers the reply from session messages and session status.
-- `prompt.waitTimeoutMs` is the total safety cap; `prompt.recoveryInactivityTimeoutMs` only applies when OpenCode stops making progress.
 - If `telegram.allowedChatIds` is left empty, the bot accepts messages from any chat. Restrict it in production.
 - Permission approvals and session error notifications are handled through plugin hooks.
-- `/language` currently supports English, Simplified Chinese, and Japanese.
-- Plugin logs are dual-written by default: OpenCode host logs through `client.app.log({ body: ... })`, plus plugin JSONL files.
-- OpenCode host logs live under `%USERPROFILE%/.local/share/opencode/log`.
-- The default plugin JSONL log directory is `%USERPROFILE%/.local/share/opencode/log/plugins/opencode-tbot`.
+- `/language` currently supports English, Simplified Chinese, and Japanese, and syncs localized Telegram command descriptions for that chat.
 - File logs are metadata-only by default. Prompt bodies, attachment contents, raw URLs, and secrets are not written.
 
-## Logging
-
-- Host log directory: `%USERPROFILE%/.local/share/opencode/log`
-- Plugin log directory: `%USERPROFILE%/.local/share/opencode/log/plugins/opencode-tbot`
-- File format: append-only JSONL, one structured event per line
-- Correlation fields: `runtimeId`, `operationId`, `correlationId`, `updateId`, `chatId`, `sessionId`, `projectId`
-- Common components: `runtime`, `telegram`, `opencode`, `prompt`, `plugin-event`, `storage`
-- Retention: keep the newest 30 files and at most 300 MB by default
-
 ## Quick Start
 
 1. Install the plugin with `npm exec --package opencode-tbot@latest opencode-tbot -- install`.
@@ -159,26 +172,43 @@ Legacy `openrouter` voice-transcription settings are ignored at runtime. When th
 
 ## Commands
 
-- `/start` show a short welcome message and quick-start steps
-- `/status` show aggregated OpenCode health, path, plugin, LSP, and MCP status
-- `/new [title]` create a new OpenCode session
-- `/agents` or `/agent` list available agents and switch the active one
-- `/sessions` list available sessions and switch the active one
-- `/cancel` cancel session rename or abort the running request for the current session, including the local Telegram wait state
-- `/model` or `/models` list available models and switch the active one
-- `/language` switch the bot display language
+| Command | What it does |
+| --- | --- |
+| `/start` | Show a short welcome message and quick-start steps. |
+| `/status` | Show aggregated OpenCode health, version, workspace paths, plugin list, LSP status, and MCP status. |
+| `/new [title]` | Create a new OpenCode session in the current project. |
+| `/agents` or `/agent` | List available agents and switch the active one. |
+| `/sessions` | List available sessions, switch the active one, and offer rename actions. |
+| `/cancel` | Cancel pending session rename input or abort the running request for the current session. |
+| `/model` or `/models` | List available models, switch the active one, and choose a reasoning level when available. |
+| `/language` | Switch the bot display language for the current chat. |
 
-Message handling:
+### Message Behavior
 
 - Non-command text is treated as a prompt and sent to OpenCode.
 - Telegram photos and image documents are forwarded as OpenCode file parts.
 - Image attachments are processed in a temporary fork of the active session so later text-only prompts stay clean.
-- `/cancel` aborts both the OpenCode session and the local Telegram wait, so the next prompt can start immediately.
+- `/cancel` aborts both the OpenCode session and the local Telegram wait state, so the next prompt can start immediately.
 - Telegram voice messages are not supported and receive a localized rejection reply.
 
+## Logging
+
+- Host log directory: `%USERPROFILE%/.local/share/opencode/log`
+- Plugin log directory: `%USERPROFILE%/.local/share/opencode/log/plugins/opencode-tbot`
+- File format: append-only JSONL, one structured event per line
+- Correlation fields: `runtimeId`, `operationId`, `correlationId`, `updateId`, `chatId`, `sessionId`, `projectId`
+- Common components: `runtime`, `telegram`, `opencode`, `prompt`, `plugin-event`, `storage`
+- Default retention: newest 30 files and at most 300 MB total
+
 ## Development
 
-Build the plugin bundle:
+Install dependencies:
+
+```bash
+pnpm install
+```
+
+Build the bundle:
 
 ```bash
 pnpm build
@@ -190,13 +220,27 @@ Type-check:
 pnpm typecheck
 ```
 
-Run tests:
+Run the normal test suite:
 
 ```bash
 pnpm test
 ```
 
-Normal usage should rely on the globally installed npm plugin plus the global OpenCode config. This repository no longer ships a default `.opencode/plugins` bridge.
+Run the integration path closest to CI:
+
+```bash
+npm install -g opencode-ai
+OPENCODE_HOST_E2E=1 pnpm test
+```
+
+PowerShell:
+
+```powershell
+npm install -g opencode-ai
+$env:OPENCODE_HOST_E2E="1"; pnpm test
+```
+
+Normal usage should rely on the generated global bridge at `~/.config/opencode/plugins/opencode-tbot.js` plus the global plugin config. This repository does not ship a default project-local `.opencode/plugins` bridge.
 
 If you need source-based local loading while developing in this repository, create `.opencode/plugins/opencode-tbot.ts` manually:
 
@@ -204,7 +248,7 @@ If you need source-based local loading while developing in this repository, crea
 export { default } from "../../src/plugin.ts";
 ```
 
-Keep only one loading path enabled at a time: either the manual local bridge or the globally installed `opencode-tbot@latest` plugin.
+Keep only one loading path enabled at a time: either the manual local bridge or the generated global bridge in `~/.config/opencode/plugins/`.
 
 ## FAQ
 
@@ -212,6 +256,10 @@ Keep only one loading path enabled at a time: either the manual local bridge or
 
 Yes. This repository provides a Telegram integration layer and depends on the OpenCode host process that loads the plugin.
 
+### Why can the generated bridge point to `file:///.../node_modules/...`?
+
+That usually means the installer was run from a local project that has `opencode-tbot` in its own `node_modules`, so the generated bridge now points at that package location. The CLI warns when it detects that layout. Remove the local package with `npm uninstall opencode-tbot` in that project and use the recommended `npm exec --package ...` install flow instead.
+
 ### Is this an official OpenCode project?
 
 No. It integrates with OpenCode, but it is not built by the OpenCode team.