From 82e3be9dc8422f461e979982bf869096bfe60cf8 Mon Sep 17 00:00:00 2001
From: Mario Zechner <badlogicgames@gmail.com>
Date: Sun, 25 Jan 2026 22:12:03 +0100
Subject: [PATCH] docs(coding-agent): add windows.md and shell-aliases.md

---
 packages/coding-agent/docs/shell-aliases.md | 13 +++++++++++++
 packages/coding-agent/docs/windows.md       | 17 +++++++++++++++++
 2 files changed, 30 insertions(+)
 create mode 100644 packages/coding-agent/docs/shell-aliases.md
 create mode 100644 packages/coding-agent/docs/windows.md

diff --git a/packages/coding-agent/docs/shell-aliases.md b/packages/coding-agent/docs/shell-aliases.md
new file mode 100644
index 00000000..af0cd25f
--- /dev/null
+++ b/packages/coding-agent/docs/shell-aliases.md
@@ -0,0 +1,13 @@
+# Shell Aliases
+
+Pi runs bash in non-interactive mode (`bash -c`), which doesn't expand aliases by default.
+
+To enable your shell aliases, add to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "shellCommandPrefix": "shopt -s expand_aliases\neval \"$(grep '^alias ' ~/.zshrc)\""
+}
+```
+
+Adjust the path (`~/.zshrc`, `~/.bashrc`, etc.) to match your shell config.
diff --git a/packages/coding-agent/docs/windows.md b/packages/coding-agent/docs/windows.md
new file mode 100644
index 00000000..007f649c
--- /dev/null
+++ b/packages/coding-agent/docs/windows.md
@@ -0,0 +1,17 @@
+# Windows Setup
+
+Pi requires a bash shell on Windows. Checked locations (in order):
+
+1. Custom path from `~/.pi/agent/settings.json`
+2. Git Bash (`C:\Program Files\Git\bin\bash.exe`)
+3. `bash.exe` on PATH (Cygwin, MSYS2, WSL)
+
+For most users, [Git for Windows](https://git-scm.com/download/win) is sufficient.
+
+## Custom Shell Path
+
+```json
+{
+  "shellPath": "C:\\cygwin64\\bin\\bash.exe"
+}
+```