docs: add config comments to example, update README with ignoreRooms/ignoreUsers

- Add inline comments to matrix.json.example
- Add ignoreRooms and ignoreUsers to config table
- Add config priority section
- Add example config usage instructions

matrix.json.example

@@ -1,17 +1,55 @@
 {
+  // Matrix homeserver URL
   "homeserver": "https://matrix.org",
+
+  // Bot user ID (e.g., @bot:server.org)
   "userId": "@opencode-bot:matrix.org",
+
+  // Bot password for login (preferred over accessToken)
   "password": "",
+
+  // Static access token (alternative to password)
+  "accessToken": "",
+
+  // Device ID for login
   "deviceId": "opencode-matrix-plugin",
+
+  // Auto-join rooms the bot is invited to
   "autoJoin": true,
+
+  // Message prefixes to trigger the bot.
+  // Empty array = all messages are processed.
+  // Configured = only messages with trigger/mention/thread-reply are processed.
   "triggerPatterns": ["!oc "],
+
+  // Room IDs to completely ignore (messages not processed)
   "ignoreRooms": [],
+
+  // User IDs to completely ignore (messages not processed)
   "ignoreUsers": [],
+
+  // Allowlist of users who can interact with the bot.
+  // Empty = everyone allowed (subject to ignoreUsers).
   "allowedUsers": [],
+
+  // Send HTML-formatted responses (requires marked package)
   "formatHtml": false,
+
+  // Each Matrix thread gets its own isolated session
   "threadIsolation": true,
+
+  // Reply to plain messages in active threads (follow-up mode)
   "respondToThreadReplies": true,
+
+  // Per-user cooldown between messages (seconds)
   "rateLimitSeconds": 5,
+
+  // Bot display name for @mentions
   "botName": "opencode",
+
+  // Storage directory for bot state and crypto keys
+  "storagePath": "",
+
+  // Enable/disable the plugin
   "enabled": true
 }

plugins/matrix-plugin/README.md

@@ -115,6 +115,8 @@ ln -s /path/to/your/project/plugins/matrix-plugin ~/.config/opencode/plugins/mat
 | `deviceId` | string | `opencode-matrix-plugin` | Device ID for login |
 | `autoJoin` | boolean | `true` | Auto-join rooms the bot is invited to |
 | `triggerPatterns` | string[] | `[]` | Message prefixes to trigger the bot. Empty = all messages. |
+| `ignoreRooms` | string[] | `[]` | Room IDs to completely ignore |
+| `ignoreUsers` | string[] | `[]` | User IDs to completely ignore |
 | `allowedUsers` | string[] | `[]` | Allowlist (empty = everyone) |
 | `formatHtml` | boolean | `false` | Send HTML-formatted responses |
 | `threadIsolation` | boolean | `true` | Per-thread sessions |
@@ -124,6 +126,28 @@ ln -s /path/to/your/project/plugins/matrix-plugin ~/.config/opencode/plugins/mat
 | `storagePath` | string | auto | Directory for bot state and crypto keys |
 | `enabled` | boolean | `true` | Enable/disable the plugin |
 
+### Config Priority
+
+Configuration is loaded in this order (highest priority first):
+
+1. **Plugin options** from `opencode.jsonc` (`plugins[].options`)
+2. **Config file** — `matrix.json` or `matrix.jsonc` in:
+   - Project level: `.opencode/matrix.json` (next to `opencode.jsonc`)
+   - Global level: `~/.config/opencode/matrix.json`
+3. **Environment variables** — `MATRIX_*`
+
+> **Auto-create**: If no config is found, the plugin auto-creates `~/.config/opencode/matrix.json` with defaults (permissions `0o600`).
+
+### Example Config
+
+Copy `matrix.json.example` from the project root and customize:
+
+```bash
+cp matrix.json.example ~/.config/opencode/matrix.json
+```
+
+See the example file for fully commented configuration with all options.
+
 ## Usage
 
 ### Triggering the Bot

plugins/matrix-plugin/matrix-client.ts

@@ -25,6 +25,8 @@ export interface MatrixOptions {
   deviceId?: string
   autoJoin?: boolean
   triggerPatterns?: string[]
+  ignoreRooms?: string[]
+  ignoreUsers?: string[]
   allowedUsers?: string[]
   formatHtml?: boolean
   threadIsolation?: boolean
@@ -232,6 +234,8 @@ export class MatrixBotClient {
   private readonly threadIsolation: boolean
   private readonly respondToThreadReplies: boolean
   private readonly allowedUsers: string[]
+  private readonly ignoreRooms: string[]
+  private readonly ignoreUsers: string[]
   private readonly formatHtml: boolean
 
   constructor(options: MatrixOptions) {
@@ -242,6 +246,8 @@ export class MatrixBotClient {
     this.threadIsolation = options.threadIsolation !== false
     this.respondToThreadReplies = options.respondToThreadReplies !== false
     this.allowedUsers = options.allowedUsers || []
+    this.ignoreRooms = options.ignoreRooms || []
+    this.ignoreUsers = options.ignoreUsers || []
     this.formatHtml = options.formatHtml || false
   }
 
@@ -348,6 +354,16 @@ export class MatrixBotClient {
 
     if (message.sender === this.userId) return
 
+    // Check ignored rooms
+    if (this.ignoreRooms.length > 0 && this.ignoreRooms.includes(roomId)) {
+      return
+    }
+
+    // Check ignored users
+    if (this.ignoreUsers.length > 0 && this.ignoreUsers.includes(message.sender)) {
+      return
+    }
+
     // Check allowed users
     if (this.allowedUsers.length > 0 && !this.allowedUsers.includes(message.sender)) {
       return