opencode-tbot 0.1.33 → 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 ファイルに保存されます。
+- 音声メッセージは明示的に拒否され、ローカライズされた案内を返します。
+- チャットのバインドとセッション選択状態は JSON の state ファイルに保存されます。
 
 ## 前提条件
 
-- このプラグインを読み込む OpenCode ホストプロセスが動作していること。
+- このプラグインを読み込む OpenCode Host プロセスが動作していること。
 - Telegram bot token を用意していること。
-- CLI とローカル開発には Node.js `>=22.12.0` が必要です。
+- CLI とローカル開発のために Node.js `>=22.12.0` が必要です。
+- リポジトリ開発には `pnpm` が必要です。
 
-## インストール
+## インストールと更新
 
 推奨インストール方法:
 
@@ -31,9 +33,14 @@
 npm exec --package opencode-tbot@latest opencode-tbot -- install
 ```
 
-インストーラーはプラグインをグローバルに登録し、実際に使われる OpenCode のグローバル設定ファイルを更新し、デフォルトのランタイム設定を書き込みます。あわせて OpenCode 設定パス、プラグイン設定パス、既定のログディレクトリを表示します。
+インストーラーは次を行います。
 
-`~/.config/opencode/opencode.jsonc` が既に存在する場合はそのファイルを優先して更新し、存在しない場合は `~/.config/opencode/opencode.json` を使います。
+- グローバル OpenCode プラグイン一覧に `opencode-tbot@latest` を登録
+- 実際に使われる OpenCode グローバル設定ファイルを更新
+- グローバルのプラグイン実行設定を作成またはマージ
+- OpenCode 設定パス、プラグイン設定パス、既定のプラグインログディレクトリを表示
+
+`~/.config/opencode/opencode.jsonc` がすでに存在する場合はそのファイルを優先して更新し、存在しない場合は `~/.config/opencode/opencode.json` を使います。
 
 インストール済み CLI のバージョン確認:
 
@@ -41,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` で利用可能:
@@ -64,15 +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 設定に保存されます。`~/.config/opencode/opencode.jsonc` がある場合はそれを使い、なければ `~/.config/opencode/opencode.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
 {
@@ -89,55 +110,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 +215,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
+```
+
+通常利用では、グローバルにインストールした npm プラグインとグローバル OpenCode 設定を使ってください。このリポジトリは既定の `.opencode/plugins` bridge を含みません。
 
 このリポジトリでソースベースのローカル読み込みを行いたい場合は、`.opencode/plugins/opencode-tbot.ts` を手動で作成してください。
 
@@ -169,7 +249,11 @@ export { default } from "../../src/plugin.ts";
 
 ### 実行中の 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 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,7 +33,12 @@ 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:
+
+- 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`.
 
@@ -42,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:
@@ -65,15 +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:
 
-OpenCode plugin registration is stored in the global OpenCode config (`~/.config/opencode/opencode.jsonc` when present, otherwise `~/.config/opencode/opencode.json`).
+- `~/.config/opencode/opencode-tbot/config.json`
 
-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.
+OpenCode plugin registration is stored in the global OpenCode config:
 
-Legacy `openrouter` voice-transcription settings are ignored at runtime. When the installer rewrites the config, it removes them.
+- `~/.config/opencode/opencode.jsonc` when present
+- otherwise `~/.config/opencode/opencode.json`
 
-### Example Global `config.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
 {
@@ -119,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. |
@@ -130,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 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 +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
@@ -190,13 +215,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 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:
 
@@ -212,6 +251,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 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.