2 files changed, 15 insertions, 3 deletions
diff --git a/packages/web/src/content/docs/config.mdx b/packages/web/src/content/docs/config.mdx
index c02edd2ff..a27acc779 100644
--- a/packages/web/src/content/docs/config.mdx
+++ b/packages/web/src/content/docs/config.mdx
@@ -93,11 +93,19 @@ You can configure TUI-specific settings through the `tui` option.
 {
   "$schema": "https://opencode.ai/config.json",
   "tui": {
-    "scroll_speed": 3
+    "scroll_speed": 3,
+    "scroll_acceleration": {
+      "enabled": true
+    }
   }
 }
 ```
 
+Available options:
+
+- `scroll_acceleration.enabled` - Enable macOS-style scroll acceleration. **Takes precedence over `scroll_speed`.**
+- `scroll_speed` - Custom scroll speed multiplier (default: `1`, minimum: `1`). Ignored if `scroll_acceleration.enabled` is `true`.
+
 [Learn more about using the TUI here](/docs/tui).
 
 ---
diff --git a/packages/web/src/content/docs/tui.mdx b/packages/web/src/content/docs/tui.mdx
index 4dd7608be..f50409c41 100644
--- a/packages/web/src/content/docs/tui.mdx
+++ b/packages/web/src/content/docs/tui.mdx
@@ -336,11 +336,15 @@ You can customize TUI behavior through your OpenCode config file.
 {
   "$schema": "https://opencode.ai/config.json",
   "tui": {
-    "scroll_speed": 3
+    "scroll_speed": 3,
+    "scroll_acceleration": {
+      "enabled": true
+    }
   }
 }
 ```
 
 ### Options
 
-- `scroll_speed` - Controls how fast the TUI scrolls when using scroll commands (default: `2`, minimum: `1`)
+- `scroll_acceleration` - Enable macOS-style scroll acceleration for smooth, natural scrolling. When enabled, scroll speed increases with rapid scrolling gestures and stays precise for slower movements. **This setting takes precedence over `scroll_speed` and overrides it when enabled.**
+- `scroll_speed` - Controls how fast the TUI scrolls when using scroll commands (default: `1`, minimum: `1`). **Note: This is ignored if `scroll_acceleration.enabled` is set to `true`.**