notification docs (#27406)

packages/web/src/content/docs/config.mdx

@@ -273,12 +273,20 @@ Use a dedicated `tui.json` (or `tui.jsonc`) file for TUI-specific settings.
     "enabled": true
   },
   "diff_style": "auto",
-  "mouse": true
+  "mouse": true,
+  "attention": {
+    "enabled": true,
+    "notifications": true,
+    "sound": true,
+    "volume": 0.4
+  }
 }
 ```
 
 Use `OPENCODE_TUI_CONFIG` to point to a custom TUI config file.
 
+Set `attention.enabled` to turn on TUI desktop notifications and sounds. See [TUI attention](/docs/tui#attention).
+
 Legacy `theme`, `keybinds`, and `tui` keys in `opencode.json` are deprecated and automatically migrated when possible.
 
 ---

packages/web/src/content/docs/tui.mdx

@@ -369,7 +369,17 @@ You can customize TUI behavior through `tui.json` (or `tui.jsonc`).
     "enabled": false
   },
   "diff_style": "auto",
-  "mouse": true
+  "mouse": true,
+  "attention": {
+    "enabled": true,
+    "notifications": true,
+    "sound": true,
+    "volume": 0.4,
+    "sound_pack": "opencode.default",
+    "sounds": {
+      "error": "./sounds/error.mp3"
+    }
+  }
 }
 ```
 
@@ -386,9 +396,21 @@ This is separate from `opencode.json`, which configures server/runtime behavior.
 - `scroll_speed` - Controls how fast the TUI scrolls when using scroll commands (minimum: `0.001`, supports decimal values). Defaults to `3`. **Note: This is ignored if `scroll_acceleration.enabled` is set to `true`.**
 - `diff_style` - Controls diff rendering. `"auto"` adapts to terminal width, `"stacked"` always shows a single-column layout.
 - `mouse` - Enable or disable mouse capture in the TUI (default: `true`). When disabled, the terminal's native mouse selection/scrolling behavior is preserved.
+- `attention` - Configures TUI desktop notifications and sounds. Disabled by default.
 
 Use `OPENCODE_TUI_CONFIG` to load a custom TUI config path.
 
+### Attention
+
+The TUI can request attention for questions, permissions, session errors, and completed sessions. Enable it with `attention.enabled`; built-in events play sounds when triggered, and non-subagent events request desktop notifications only when the terminal is blurred.
+
+- `enabled` - Enable all attention notifications and sounds. Defaults to `false`.
+- `notifications` - Allow terminal-mediated desktop notifications when attention is enabled. Defaults to `true`.
+- `sound` - Allow attention sounds when attention is enabled. Defaults to `true`.
+- `volume` - Default sound volume from `0` to `1`. Defaults to `0.4`.
+- `sound_pack` - Sound pack ID to use. Defaults to `opencode.default`.
+- `sounds` - Override sound files for `default`, `question`, `permission`, `error`, `done`, or `subagent_done`. Paths can be absolute, `file://` URLs, or relative to `tui.json`.
+
 ---
 
 ## Customization