From 581c3fc3fed6722906709a835ca55ba35368ed4f Mon Sep 17 00:00:00 2001
From: Gautam Kumar <gautamkumarofficial@users.noreply.github.com>
Date: Thu, 18 Jun 2026 08:43:43 +0530
Subject: [PATCH 1/2] docs: add troubleshooting for mouse wheel and Shift+Enter
 issues

Adds documentation for known Windows terminal issues:
- Mouse wheel behaving like arrow keys
- Shift+Enter not creating newlines

Includes solutions for MobaXTerm, Git Bash, and older terminals.

Closes #789
---
 WINDOWS.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/WINDOWS.md b/WINDOWS.md
index 885783a7e3..97854487d0 100644
--- a/WINDOWS.md
+++ b/WINDOWS.md
@@ -212,6 +212,35 @@ This is **not an error** - it's an informational message indicating:
 
 ---
 
+### Issue: Mouse wheel behaves like arrow keys / Shift+Enter doesn't create newline
+
+**Symptom**:
+- Mouse scroll wheel moves cursor up/down instead of scrolling
+- Shift+Enter behaves like Enter (submits instead of new line)
+
+**Cause**:
+Some Windows terminal emulators (MobaXTerm, Git Bash, older Windows Terminal versions) have incomplete terminal escape sequence support. They may:
+- Send different escape codes for mouse events
+- Not properly handle Shift+Enter as a distinct key from Enter
+
+**Solutions**:
+
+1. **Use Windows Terminal** (recommended):
+   - Install from Microsoft Store: `winget install Microsoft.WindowsTerminal`
+   - Windows Terminal has the best terminal emulation on Windows
+
+2. **Use VS Code integrated terminal**:
+   - Open VS Code → Terminal → New Terminal
+   - VS Code's terminal has better escape sequence support
+
+3. **Use PowerShell 7+**:
+   - Install: `winget install Microsoft.PowerShell`
+   - PowerShell 7 has improved terminal handling
+
+**Reference**: Issue [#789](https://github.com/CodebuffAI/codebuff/issues/789)
+
+---
+
 ### Still Having Issues?
 
 If these solutions don't resolve your problem:

From 49130d46e1d0e7e1f0c85465b74884c50e21741d Mon Sep 17 00:00:00 2001
From: Gautam Kumar <gautamkumarofficial@users.noreply.github.com>
Date: Thu, 18 Jun 2026 08:56:24 +0530
Subject: [PATCH 2/2] docs: add Linux troubleshooting for menu freeze,
 path-sandbox, and AVX issues

Documents known Linux-specific issues:
- CLI menu freeze on Enter (#775)
- Path-sandbox error for skills (#767)
- SIGILL on older CPUs (#797)

Includes workarounds and general troubleshooting tips.

Closes #775, #767, #797
---
 LINUX.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 LINUX.md

diff --git a/LINUX.md b/LINUX.md
new file mode 100644
index 0000000000..2d9e19d3f5
--- /dev/null
+++ b/LINUX.md
@@ -0,0 +1,74 @@
+# Codebuff for Linux
+
+Common Linux-specific issues and solutions.
+
+## Issue: CLI interactive menu freezes on Enter
+
+**Symptom**: Arrow keys work in menus, but pressing Enter does nothing — the CLI hangs.
+
+**Affected terminals**: KDE Konsole, some older terminal emulators.
+
+**Solutions**:
+
+1. **Use a different terminal emulator**:
+   - GNOME Terminal (most reliable)
+   - Alacritty
+   - Kitty
+
+2. **Check terminal settings**:
+   - Ensure terminal is set to use UTF-8 encoding
+   - Check that alternate screen buffer is enabled
+
+3. **Use tmux**:
+   ```bash
+   tmux new-session -s codebuff
+   codebuff
+   ```
+
+**Reference**: Issue [#775](https://github.com/CodebuffAI/codebuff/issues/775)
+
+---
+
+## Issue: Path-sandbox error for skills
+
+**Symptom**: `[FILE_OUTSIDE_PROJECT]` error when executing skills that reference files in `~/.agents/skills/`.
+
+**Cause**: The SDK's path validation blocks reads outside the project root. Skills stored in `~/.agents/skills/` are outside the project.
+
+**Workaround**: Copy skill files into your project directory before execution.
+
+**Reference**: Issue [#767](https://github.com/CodebuffAI/codebuff/issues/767)
+
+---
+
+## Issue: SIGILL on older CPUs
+
+**Symptom**: `linux-x64-baseline` binary crashes with illegal instruction on CPUs without AVX support.
+
+**Cause**: The baseline build target may still contain AVX instructions due to Bun's compilation.
+
+**Workaround**: Use the standard `linux-x64` target if your CPU supports AVX, or wait for a fix.
+
+**Reference**: Issue [#797](https://github.com/CodebuffAI/codebuff/issues/797)
+
+---
+
+## General Linux Troubleshooting
+
+### Check terminal capabilities
+```bash
+echo $TERM
+echo $LANG
+```
+
+### Test keyboard input
+```bash
+cat -v
+# Press keys to see their escape sequences
+```
+
+### Check Node.js version
+```bash
+node --version
+# Recommended: Node 20.x LTS or newer
+```