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"
+}
+```