docs: update README with V1/V2 support, trigger behavior, session management

plugins/matrix-plugin/README.md

@@ -1,6 +1,6 @@
 # opencode-matrix-plugin
 
-OpenCode V2 plugin that connects your OpenCode agent to Matrix messaging servers.
+OpenCode plugin that connects your OpenCode agent to Matrix messaging servers. Supports both V1 (SDK) and V2 (full context) APIs.
 
 ## Features
 
@@ -8,14 +8,13 @@ OpenCode V2 plugin that connects your OpenCode agent to Matrix messaging servers
 - **Thread Isolation**: Each Matrix thread gets its own isolated session
 - **E2EE Support**: End-to-end encryption via Rust crypto SDK
 - **Auto-join**: Bot auto-joins rooms it's invited to
-- **Multiple Trigger Modes**: Prefix trigger (`!oc`), @mention, or DM
+- **Configurable Triggers**: `triggerPatterns` array — empty = all messages, configured = only trigger/mention/thread-reply
-- **Thread Replies**: Respond to plain replies within active threads
+- **Thread Replies**: Respond to plain replies within active threads (follow-up mode)
 - **Bridge Commands**: `/status`, `/clear`, `/help` for session management
 - **Rate Limiting**: Configurable per-user rate limiting
 - **User Allowlisting**: Restrict who can interact with the bot
-- **Image Support**: Upload and display images in Matrix
+- **Session Persistence**: Sessions survive plugin reloads via `~/.opencode-matrix-sessions.json`
-- **HTML Formatting**: Optional HTML-formatted responses
+- **V1/V2 Dual Support**: Works with OpenCode 1.18.x (V1 SDK) and V2 (full context)
-- **Session Persistence**: Sessions survive plugin reloads
 
 ## Installation
 
@@ -25,7 +24,7 @@ OpenCode V2 plugin that connects your OpenCode agent to Matrix messaging servers
 
 ```bash
 mkdir -p ~/.config/opencode/plugins
-cp -r ./opencode-matrix-plugin ~/.config/opencode/plugins/
+cp -r ./plugins/matrix-plugin ~/.config/opencode/plugins/
 ```
 
 2. Add the plugin to your `opencode.jsonc`:
@@ -33,34 +32,16 @@ cp -r ./opencode-matrix-plugin ~/.config/opencode/plugins/
 ```jsonc
 {
   "plugins": [
-    "./plugins/opencode-matrix-plugin"
+    "./plugins/matrix-plugin"
   ]
 }
 ```
 
-### Option 2: npm Package
+### Option 2: Symlink
 
 ```bash
-cd ~/.config/opencode
+mkdir -p ~/.config/opencode/plugins
-npm init -y
+ln -s /path/to/your/project/plugins/matrix-plugin ~/.config/opencode/plugins/matrix-plugin
-npm install ./path/to/opencode-matrix-plugin
-```
-
-Then in `opencode.jsonc`:
-
-```jsonc
-{
-  "plugins": [
-    {
-      "package": "opencode-matrix-plugin",
-      "options": {
-        "homeserver": "https://matrix.org",
-        "userId": "@opencode:matrix.org",
-        "password": "your-bot-password"
-      }
-    }
-  ]
-}
 ```
 
 ## Configuration
@@ -133,13 +114,11 @@ Then in `opencode.jsonc`:
 | `password` | string | - | Bot password (preferred, auto-refreshes token) |
 | `deviceId` | string | `opencode-matrix-plugin` | Device ID for login |
 | `autoJoin` | boolean | `true` | Auto-join rooms the bot is invited to |
-| `triggerPatterns` | string[] | `["!oc "]` | Message prefixes to trigger the bot |
+| `triggerPatterns` | string[] | `[]` | Message prefixes to trigger the bot. Empty = all messages. |
-| `ignoreRooms` | string[] | `[]` | Room IDs to ignore |
-| `ignoreUsers` | string[] | `[]` | User IDs to ignore |
 | `allowedUsers` | string[] | `[]` | Allowlist (empty = everyone) |
 | `formatHtml` | boolean | `false` | Send HTML-formatted responses |
 | `threadIsolation` | boolean | `true` | Per-thread sessions |
-| `respondToThreadReplies` | boolean | `true` | Reply to plain thread messages |
+| `respondToThreadReplies` | boolean | `true` | Reply to plain thread messages (follow-up) |
 | `rateLimitSeconds` | number | `5` | Per-user cooldown between messages |
 | `botName` | string | `opencode` | Bot display name for @mentions |
 | `storagePath` | string | auto | Directory for bot state and crypto keys |
@@ -149,10 +128,15 @@ Then in `opencode.jsonc`:
 
 ### Triggering the Bot
 
+Behavior depends on `triggerPatterns` config:
+
+**With triggers configured** (e.g., `["!oc "]`):
 1. **Prefix trigger**: Send `!oc What is TypeScript?`
 2. **@Mention**: Send `@opencode What is TypeScript?`
-3. **DM**: Send any message in a direct message with the bot
+3. **Thread reply**: Reply to any message in an active thread (follow-up mode)
-4. **Thread reply**: Reply to any message in an active thread
+
+**With empty triggers** (`triggerPatterns: []`):
+- All messages are processed
 
 ### Bridge Commands
 
@@ -194,21 +178,27 @@ SessionManager
     ├── Rate limiting
     ├── Event deduplication
     ├── Thread isolation (room:threadId)
-    └── Session lifecycle
+    └── Session persistence (~/.opencode-matrix-sessions.json)
     │
     ▼
-OpenCode V2 Plugin API
+OpenCode API
     │
-    ├── ctx.session.prompt() - send queries
+    ├── V2: ctx.session.prompt() / ctx.session.create()
-    ├── ctx.session.hook("prompt") - intercept
+    ├── V1: sdkClient.session.prompt() / sdkClient.session.create()
-    ├── ctx.command.transform() - bridge commands
+    └── Session mapping: Matrix thread → OpenCode session
-    ├── ctx.event.subscribe() - event stream
-    └── ctx.storage - persistence
     │
     ▼
 Response → MatrixBotClient → Matrix Room
 ```
 
+## Session Management
+
+Sessions are persisted across plugin restarts in `~/.opencode-matrix-sessions.json`.
+
+- **V1 API**: Sessions are created with auto-generated IDs, mapped via JSON file
+- **V2 API**: Sessions can be created with custom deterministic IDs (no map needed)
+- **Sync**: Use `sessionManager.syncWithOpenCode(sessionIds)` to prune orphaned sessions
+
 ## Security
 
 - **E2EE**: Full end-to-end encryption support via `@matrix-org/matrix-sdk-crypto-nodejs`
@@ -243,10 +233,10 @@ Response → MatrixBotClient → Matrix Room
 ## Development
 
 ```bash
-cd plugins/opencode-matrix-plugin
+cd plugins/matrix-plugin
-npm install
+bun install
-npm run typecheck
+bun run typecheck
-npm run build
+bun run build
 ```
 
 ## License