opencode-tbot 0.1.32 → 0.1.34

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 ファイルに保存されます。
+- セッションエラーイベントは、紐付けられた Telegram チャットへ通知できます。
+- 音声メッセージは明示的に拒否され、ローカライズされた案内を返します。
+- チャットのバインドとセッション選択状態は JSON の state ファイルに保存されます。
 
 ## 前提条件
 
-- このプラグインを読み込む OpenCode ホストプロセスが動作していること。
+- このプラグインを読み込む OpenCode Host プロセスが動作していること。
 - Telegram bot token を用意していること。
-- CLI とローカル開発には Node.js `>=22.12.0` が必要です。
+- CLI とローカル開発のために Node.js `>=22.12.0` が必要です。
+- リポジトリ開発には `pnpm` が必要です。
 
-## インストール
+## インストールと更新
 
 推奨インストール方法:
 
@@ -31,7 +33,14 @@
 npm exec --package opencode-tbot@latest opencode-tbot -- install
 ```
 
-インストーラーはプラグインをグローバルに登録し、デフォルトのランタイム設定を書き込みます。
+インストーラーは次を行います。
+
+- グローバル OpenCode プラグイン一覧に `opencode-tbot@latest` を登録
+- 実際に使われる OpenCode グローバル設定ファイルを更新
+- グローバルのプラグイン実行設定を作成またはマージ
+- OpenCode 設定パス、プラグイン設定パス、既定のプラグインログディレクトリを表示
+
+`~/.config/opencode/opencode.jsonc` がすでに存在する場合はそのファイルを優先して更新し、存在しない場合は `~/.config/opencode/opencode.json` を使います。
 
 インストール済み CLI のバージョン確認:
 
@@ -39,12 +48,18 @@ npm exec --package opencode-tbot@latest opencode-tbot -- install
 npm exec --package opencode-tbot@latest opencode-tbot -- --version
 ```
 
-OpenCode に登録済みの npm プラグイン spec を更新:
+bot token を変更せず、OpenCode に登録された npm プラグイン spec だけを更新:
 
 ```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` で利用可能:
@@ -62,13 +77,23 @@ npm exec --package opencode-tbot@latest opencode-tbot -- update
 
 ## 設定
 
-ランタイム設定は `~/.config/opencode/opencode-tbot/config.json` からのみ読み込まれます。
+ランタイム設定は次のパスからのみ読み込まれます。
+
+- `~/.config/opencode/opencode-tbot/config.json`
+
+OpenCode のプラグイン登録情報はグローバル OpenCode 設定に保存されます。
 
-古い `<worktree>/tbot.config.json` はランタイムでは無視されます。検出された場合は、値をグローバル設定へ移行できるように警告ログを出します。
+- 存在する場合は `~/.config/opencode/opencode.jsonc`
+- なければ `~/.config/opencode/opencode.json`
 
-古い `openrouter` 音声転写設定はランタイムでは無視され、インストーラーが設定を書き直す際にも削除されます。
+このプラグインは `.env` からランタイム設定を読み込みません。グローバル JSON 設定を使ってください。
 
-### グローバル `config.json` の例
+レガシー挙動:
+
+- `<worktree>/tbot.config.json` はランタイムで無視されます。見つかった場合は移行用の警告ログが出ます
+- 古い `openrouter` 音声文字起こし設定はランタイムで無視され、インストーラーが設定を書き直す際にも削除されます
+
+### `config.json` の例
 
 ```json
 {
@@ -85,55 +110,100 @@ npm exec --package opencode-tbot@latest opencode-tbot -- update
     "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
@@ -145,19 +215,45 @@ pnpm build
 pnpm typecheck
 ```
 
-テスト実行:
+通常テストの実行:
 
 ```bash
 pnpm test
 ```
 
-このリポジトリでソースベースのローカル読み込みを行う場合、OpenCode は [.opencode/plugins/opencode-tbot.ts](./.opencode/plugins/opencode-tbot.ts) を使って `src/plugin.ts` を再エクスポートできます。
+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
+```
+
+通常利用では、グローバルにインストールした npm プラグインとグローバル OpenCode 設定を使ってください。このリポジトリは既定の `.opencode/plugins` bridge を含みません。
+
+このリポジトリでソースベースのローカル読み込みを行いたい場合は、`.opencode/plugins/opencode-tbot.ts` を手動で作成してください。
+
+```ts
+export { default } from "../../src/plugin.ts";
+```
+
+有効にする読み込み経路は常に 1 つだけにしてください。手動で作成したローカル bridge か、グローバルにインストールした `opencode-tbot@latest` のどちらかを使います。
 
 ## FAQ
 
 ### 実行中の OpenCode インスタンスは必要ですか？
 
-はい。このリポジトリが提供するのは Telegram 連携レイヤーであり、プラグインを読み込む OpenCode ホストプロセスに依存します。
+はい。このリポジトリは Telegram 連携レイヤーのみを提供しており、プラグインを読み込む OpenCode Host プロセスに依存します。
+
+### なぜ OpenCode に `file:///.../node_modules/...` 形式のプラグインパスが表示されるのですか？
+
+通常は、どこかのローカルプロジェクトに `opencode-tbot` が `node_modules` として入っていることを意味します。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 completion and error events can be reported back to the bound Telegram chat.
-- Chat bindings are stored in a JSON state file.
+- Session error events can be reported back to the bound Telegram chat.
+- 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,7 +33,14 @@ Recommended install:
 npm exec --package opencode-tbot@latest opencode-tbot -- install
 ```
 
-The installer registers the plugin globally, writes the default runtime config, and prints both the config path and the default plugin log directory.
+The installer:
+
+- registers `opencode-tbot@latest` in the global OpenCode plugin list
+- updates the resolved OpenCode config file
+- writes or merges the global plugin runtime config
+- prints the OpenCode config path, plugin config path, and default plugin log directory
+
+If `~/.config/opencode/opencode.jsonc` already exists, the installer updates that file. Otherwise it uses `~/.config/opencode/opencode.json`.
 
 Check the installed CLI version:
 
@@ -40,12 +48,18 @@ Check the installed CLI version:
 npm exec --package opencode-tbot@latest opencode-tbot -- --version
 ```
 
-Update the registered npm plugin spec in OpenCode:
+Update the registered npm plugin spec in OpenCode 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:
@@ -63,13 +77,23 @@ npm exec --package opencode-tbot@latest opencode-tbot -- update
 
 ## Configuration
 
-Runtime config is loaded from `~/.config/opencode/opencode-tbot/config.json`.
+Runtime config is loaded only from:
 
-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.
+- `~/.config/opencode/opencode-tbot/config.json`
 
-Legacy `openrouter` voice-transcription settings are ignored at runtime. When the installer rewrites the config, it removes them.
+OpenCode plugin registration is stored in the global OpenCode config:
 
-### Example Global `config.json`
+- `~/.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 behavior:
+
+- `<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 `config.json`
 
 ```json
 {
@@ -115,10 +139,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. |
@@ -126,25 +150,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 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`.
+- Permission approvals and session error notifications are handled through plugin hooks.
+- `/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`.
@@ -155,26 +167,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
@@ -186,15 +215,35 @@ Type-check:
 pnpm typecheck
 ```
 
-Run tests:
+Run the normal test suite:
 
 ```bash
 pnpm test
 ```
 
-For local source-based loading in this repository, OpenCode can use [.opencode/plugins/opencode-tbot.ts](./.opencode/plugins/opencode-tbot.ts), which re-exports `src/plugin.ts`.
+Run the integration path closest to CI:
 
-OpenCode may load both the local `.opencode/plugins/` bridge and an installed npm plugin such as `opencode-tbot@latest` in the same process. This repository now guards against duplicate Telegram runners, but local development is still clearer if you keep only one loading path enabled at a time.
+```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 globally installed npm plugin plus the global OpenCode config. This repository does not ship a default `.opencode/plugins` bridge.
+
+If you need source-based local loading while developing in this repository, create `.opencode/plugins/opencode-tbot.ts` manually:
+
+```ts
+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.
 
 ## FAQ
 
@@ -202,6 +251,10 @@ OpenCode may load both the local `.opencode/plugins/` bridge and an installed np
 
 Yes. This repository provides a Telegram integration layer and depends on the OpenCode host process that loads the plugin.
 
+### Why does OpenCode show the plugin as `file:///.../node_modules/...`?
+
+That usually means a local project has `opencode-tbot` installed in its own `node_modules`. 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.