@pikaa-ai/pikaa 0.2.4 → 0.3.0

package/skills/pi-agent/references/termux.md

@@ -0,0 +1,31 @@
+# Termux Setup
+
+Source: https://pi.dev/docs/latest/termux
+
+Pi runs on Android through Termux.
+
+## Prerequisites
+
+Install Termux from GitHub or F-Droid, not Google Play. Install Termux:API for clipboard and device integrations.
+
+## Install
+
+```bash
+pkg update && pkg upgrade
+pkg install nodejs termux-api git
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+mkdir -p ~/.pi/agent
+pi
+```
+
+## Clipboard
+
+Pi uses `termux-clipboard-set` and `termux-clipboard-get` when available. Image clipboard is not supported in Termux.
+
+## Useful `AGENTS.md` Context
+
+Add Termux environment notes to `~/.pi/agent/AGENTS.md`: OS is Android/Termux, home is `/data/data/com.termux/files/home`, prefix is `/data/data/com.termux/files/usr`, shared storage is `/storage/emulated/0`, use `termux-open-url`, `termux-open`, `termux-share`, `termux-notification`, and clipboard commands where appropriate.
+
+## Limitations and Troubleshooting
+
+No image clipboard. Some optional native binaries may be unavailable on Android ARM64. Run `termux-setup-storage` once for `/storage/emulated/0`. If npm fails, try `npm cache clean --force`.

package/skills/pi-agent/references/themes.md

@@ -0,0 +1,69 @@
+# Themes
+
+Source: https://pi.dev/docs/latest/themes
+
+Themes are JSON files defining TUI colors.
+
+## Locations
+
+- Built-in: `dark`, `light`
+- Global: `~/.pi/agent/themes/*.json`
+- Project: `.pi/themes/*.json` (only after project trust)
+- Packages: `themes/` directories or `pi.themes` entries in `package.json`
+- Settings: `themes` array
+- CLI: `--theme <path>` (repeatable) loads a theme file; `--use-theme <name[/name]>` selects the initial theme for one run
+
+Disable discovery with `--no-themes`. Select via `/settings` or `{"theme": "my-theme"}`. On first run Pi detects the terminal background and defaults to `dark` or `light`. Editing the active custom theme file hot-reloads it for immediate feedback.
+
+`--use-theme light` starts a run with that theme without changing the saved setting; `--use-theme light/dark` uses `lightTheme/darkTheme` syntax to follow terminal appearance. Picking another theme later in `/settings` applies immediately and saves normally.
+
+## Format
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "name": "my-theme",
+  "vars": { "primary": "#00aaff", "secondary": 242 },
+  "colors": { "accent": "primary", "muted": "secondary", "text": "" }
+}
+```
+
+- `name` is required, must be unique, and must not contain `/`.
+- `vars` is optional — reusable colors referenced by name from `colors`.
+- `colors` must define all 51 required tokens. Optional tokens fall back: `thinkingMax` → `thinkingXhigh`, `scrollbarThumb` and `searchMatchBg` → `selectedBg`, `searchMatchText` → `text`.
+- `$schema` enables editor auto-completion and validation.
+
+## Color Tokens (51 required + 4 optional)
+
+- **Core UI (11)**: `accent`, `border`, `borderAccent`, `borderMuted`, `success`, `error`, `warning`, `muted`, `dim`, `text`, `thinkingText`
+- **Backgrounds & content (11 required + 3 optional)**: `selectedBg`, `userMessageBg`, `userMessageText`, `customMessageBg`, `customMessageText`, `customMessageLabel`, `toolPendingBg`, `toolSuccessBg`, `toolErrorBg`, `toolTitle`, `toolOutput`, plus optional `scrollbarThumb` (fullscreen scrollbar thumb), `searchMatchBg`, and `searchMatchText` (transcript search). Non-current search matches render `searchMatchText` on `searchMatchBg` with an underline; the current match reverses that pair and uses bold.
+- **Markdown (10)**: `mdHeading`, `mdLink`, `mdLinkUrl`, `mdCode`, `mdCodeBlock`, `mdCodeBlockBorder`, `mdQuote`, `mdQuoteBorder`, `mdHr`, `mdListBullet`
+- **Tool diffs (3)**: `toolDiffAdded`, `toolDiffRemoved`, `toolDiffContext`
+- **Syntax (9)**: `syntaxComment`, `syntaxKeyword`, `syntaxFunction`, `syntaxVariable`, `syntaxString`, `syntaxNumber`, `syntaxType`, `syntaxOperator`, `syntaxPunctuation`
+- **Thinking level borders (6 required + 1 optional)**: `thinkingOff`, `thinkingMinimal`, `thinkingLow`, `thinkingMedium`, `thinkingHigh`, `thinkingXhigh`, and optional `thinkingMax`
+- **Bash mode (1)**: `bashMode`
+
+## HTML Export (optional)
+
+```json
+{ "export": { "pageBg": "#18181e", "cardBg": "#1e1e24", "infoBg": "#3c3728" } }
+```
+
+Controls `/export` HTML output. If omitted, colors are derived from `userMessageBg`.
+
+## Color Values
+
+| Format | Example | Notes |
+|---|---|---|
+| Hex | `"#ff0000"` | 6-digit RGB |
+| 256-color | `39` | xterm palette index 0–255 |
+| Variable | `"primary"` | Reference to a `vars` entry |
+| Default | `""` | Terminal default color |
+
+256-color ranges: `0-15` basic ANSI (terminal-dependent), `16-231` the 6×6×6 RGB cube (`16 + 36R + 6G + B`), `232-255` grayscale.
+
+Pi emits 24-bit RGB; older 256-color terminals get the nearest approximation. Check truecolor with `echo $COLORTERM`. In VS Code set `terminal.integrated.minimumContrastRatio` to `1` for accurate colors.
+
+## Tips
+
+Dark terminals want bright saturated colors with higher contrast; light terminals want darker muted colors. Start from a base palette (Nord, Gruvbox, Tokyo Night) in `vars` and reference it consistently. Test against different message types, tool states, markdown, and long wrapped text. Built-in themes to copy: `src/modes/interactive/theme/dark.json` and `light.json`.

package/skills/pi-agent/references/tmux.md

@@ -0,0 +1,44 @@
+# tmux Setup
+
+Source: https://pi.dev/docs/latest/tmux
+
+tmux strips modifier information from some keys by default, so without configuration `Shift+Enter` and `Ctrl+Enter` are indistinguishable from plain `Enter`.
+
+## Recommended Configuration
+
+Add to `~/.tmux.conf`:
+
+```tmux
+set -g extended-keys on
+set -g extended-keys-format csi-u
+```
+
+Then restart tmux fully:
+
+```bash
+tmux kill-server
+tmux
+```
+
+Pi requests extended key reporting automatically when the Kitty keyboard protocol is unavailable. `extended-keys-format csi-u` requires **tmux 3.5 or later** (check with `tmux -V`). With tmux 3.2–3.4, omit that line; Pi still supports tmux's default xterm `modifyOtherKeys` format.
+
+## Why csi-u
+
+With only `set -g extended-keys on`, tmux defaults to `extended-keys-format xterm` and forwards modified keys as `modifyOtherKeys` sequences — `Ctrl+C` as `ESC [27;5;99~`, `Ctrl+Enter` as `ESC [27;5;13~`. With `csi-u` the same keys arrive as `ESC [99;5u` and `ESC [13;5u`. Pi supports both formats; `csi-u` is the recommended setup.
+
+## What It Fixes
+
+`ESC` below is the escape byte (`0x1b`).
+
+| Key | Without extended keys | With `csi-u` |
+|---|---|---|
+| Enter | `CR` | `CR` |
+| Shift+Enter | `CR` | `ESC [13;2u` |
+| Ctrl+Enter | `CR` | `ESC [13;5u` |
+| Alt/Option+Enter | `ESC CR` | `ESC [13;3u` |
+
+This affects the default bindings (Enter to submit, Shift+Enter for newline) and any custom keybindings using modified Enter.
+
+## Requirements
+
+tmux 3.5+ for `extended-keys-format csi-u`, plus a terminal emulator that supports extended keys: Ghostty, Kitty, iTerm2, WezTerm, or Windows Terminal.

package/skills/pi-agent/references/tui.md

@@ -0,0 +1,97 @@
+# TUI Components
+
+Source: https://pi.dev/docs/latest/tui
+
+Extensions and custom tools render custom terminal UI through `@earendil-works/pi-tui`.
+
+## Component Interface
+
+```ts
+interface Component {
+  render(width: number): string[];
+  handleInput?(data: string): void;
+  wantsKeyRelease?: boolean;   // receive key release events (Kitty protocol)
+  invalidate(): void;          // clear cached render state; called on theme changes
+}
+```
+
+Each line from `render(width)` **must not exceed `width`**. The TUI appends a full SGR reset and OSC 8 reset at the end of every rendered line, so styles do not carry across lines — reapply styles per line or use `wrapTextWithAnsi()`.
+
+Width helpers: `visibleWidth(str)` (ignores ANSI), `truncateToWidth(str, width, ellipsis?)`, `wrapTextWithAnsi(str, width)`.
+
+## Focusable and IME
+
+Components that draw a text cursor should implement `Focusable { focused: boolean }`. When focused, the TUI sets `focused = true`, scans output for `CURSOR_MARKER` (a zero-width APC sequence emitted right before the fake cursor), and positions the hardware cursor there. The cursor stays hidden by default; some terminals need it visible for IME candidate windows — enable with `showHardwareCursor`, `setShowHardwareCursor(true)`, or `PI_HARDWARE_CURSOR=1`. The built-in `Editor` and `Input` already implement this.
+
+Container components (dialogs, selectors) that embed an `Input`/`Editor` must implement `Focusable` and propagate `focused` to the child, or IME candidate windows appear in the wrong place.
+
+## Usage
+
+```ts
+const result = await ctx.ui.custom<string | null>((tui, theme, keybindings, done) =>
+  new MyComponent({ theme, keybindings, onChange: () => tui.requestRender(), onSelect: done, onCancel: () => done(null) })
+);
+```
+
+The same call works inside a custom tool's `execute(toolCallId, params, signal, onUpdate, ctx)`. Returning a plain `{ render, invalidate, handleInput }` object is also fine.
+
+## Overlays
+
+Pass `{ overlay: true }` to render on top of existing content without clearing the screen. `overlayOptions` controls layout:
+
+- Size: `width`, `minWidth`, `maxHeight` (numbers or percentage strings)
+- Position: `anchor` (9 positions, default `"center"`), `offsetX`/`offsetY`, or `row`/`col`
+- Margins: `margin` (number or `{ top, right, bottom, left }`)
+- Responsive: `visible(termWidth, termHeight)`
+
+`onHandle: (handle) => …` gives `focus()` (focus and bring to front), `unfocus()` (release input to the normal fallback), `unfocus({ target })` (hand input to a specific component, or `null` for none), `setHidden(true|false)`, and `hide()` (permanent removal).
+
+A focused visible overlay keeps input ownership across temporary non-overlay UI and can reclaim input when that UI closes. Overlay components are disposed when closed — never reuse a reference; call the show function again to re-show.
+
+## Built-in Components
+
+Import from `@earendil-works/pi-tui`: `Text` (multi-line with word wrapping, `new Text(content, paddingX, paddingY, bgFn?)`, `setText()`), `Box` (padding + background, `addChild`, `setBgFn`), `Container` (vertical grouping, `addChild`/`removeChild`/`clear`), `Spacer(lines)`, `Markdown(text, paddingX, paddingY, theme)`, `Image(base64, mimeType, theme, { maxWidthCells, maxHeightCells })` (Kitty, iTerm2, Ghostty, WezTerm, Warp), `SelectList(items, visibleCount, theme)` with `SelectItem { value, label, description? }`, `SettingsList(items, visibleCount, theme, onChange, onClose, { enableSearch })` with `SettingItem { id, label, currentValue, values }`, plus `AutocompleteItem` types.
+
+From `@earendil-works/pi-coding-agent`: `DynamicBorder`, `BorderedLoader` (spinner + abort signal + `onAbort`), `CustomEditor`, `getMarkdownTheme()`, `getSettingsListTheme()`, `keyHint`/`keyText`/`rawKeyHint`, `highlightCode`, `getLanguageFromPath`.
+
+## Keyboard Input
+
+```ts
+import { matchesKey, Key } from "@earendil-works/pi-tui";
+
+if (matchesKey(data, Key.up)) { /* ... */ }
+if (matchesKey(data, Key.ctrl("c"))) { /* ... */ }
+```
+
+`Key.enter`, `Key.escape`, `Key.tab`, `Key.space`, `Key.backspace`, `Key.delete`, `Key.home`, `Key.end`, arrows, and modifier helpers `Key.ctrl`, `Key.shift`, `Key.alt`, `Key.ctrlShift`. String literals (`"enter"`, `"ctrl+c"`, `"shift+tab"`) also work.
+
+## Theming
+
+Use the `theme` passed into the callback or renderer — never import a global theme. `theme.fg(color, text)` covers general (`text`, `accent`, `muted`, `dim`, `searchMatchText`), status (`success`, `error`, `warning`), borders (`border`, `borderAccent`, `borderMuted`), messages (`userMessageText`, `customMessageText`, `customMessageLabel`), tools (`toolTitle`, `toolOutput`), diffs (`toolDiffAdded`/`Removed`/`Context`), markdown (`md*`), syntax (`syntax*`), thinking levels (`thinkingOff`…`thinkingMax`), and `bashMode`. `theme.bg(color, text)` covers `selectedBg`, `searchMatchBg`, `userMessageBg`, `customMessageBg`, `toolPendingBg`, `toolSuccessBg`, `toolErrorBg`. Text styles: `theme.bold`, `theme.italic`, `theme.strikethrough`.
+
+Components that pre-bake theme colors into cached strings must rebuild that content in `invalidate()` — clearing a render cache is not enough. This applies to `theme.fg`/`theme.bg` strings stored in child components, `highlightCode()` output, and child trees that embed colors. It is unnecessary when you pass theme callbacks that run at render time, for simple containers, or for stateless render.
+
+## Common Patterns
+
+1. **Selection dialog** — `SelectList` framed with `DynamicBorder`, `onSelect`/`onCancel` calling `done`.
+2. **Async with cancel** — `BorderedLoader(tui, theme, "Fetching…")`, pass `loader.signal` to the async work, `loader.onAbort = () => done(null)`.
+3. **Settings toggles** — `SettingsList` with `getSettingsListTheme()`.
+4. **Persistent status** — `ctx.ui.setStatus("my-ext", text)`; clear with `undefined`.
+5. **Working indicator** — `ctx.ui.setWorkingIndicator({ frames, intervalMs })`; `{ frames: [] }` hides it, no argument restores the default spinner. Frames render verbatim, so add colors yourself. Compaction and retry loaders keep built-in styling. `setWorkingMessage()` and `setWorkingVisible()` control the loader row.
+6. **Widgets** — `ctx.ui.setWidget(key, lines | factory, { placement: "aboveEditor" | "belowEditor" })`; `undefined` clears.
+7. **Custom footer** — `ctx.ui.setFooter((tui, theme, footerData) => ({ render, invalidate, dispose }))`. `footerData.getGitBranch()`, `getExtensionStatuses()`, and `onBranchChange(cb)` expose data extensions cannot otherwise reach; token stats come from `ctx.sessionManager.getBranch()` and `ctx.model`. `setFooter(undefined)` restores the default.
+8. **Custom editor** — extend `CustomEditor` (not base `Editor`) so app keybindings still work, call `super.handleInput(data)` for keys you do not handle, and install with `ctx.ui.setEditorComponent((tui, theme, keybindings) => new MyEditor(...))`. Capture `ctx.ui.getEditorComponent()` first to wrap another extension's editor; `setEditorComponent(undefined)` restores the default.
+
+## Key Rules
+
+1. Respect `render(width)` on every line.
+2. Always use the `theme` from the callback; type `DynamicBorder` color params explicitly (`(s: string) => theme.fg("accent", s)`).
+3. Call `tui.requestRender()` after state changes in `handleInput`.
+4. Implement `invalidate()` on custom components and their child trees.
+5. Propagate focus to embedded inputs.
+6. Reuse `SelectList`, `SettingsList`, and `BorderedLoader` before building primitives.
+7. Guard TUI features in non-TUI modes (`ctx.mode === "tui"`).
+
+## Debug Logging
+
+`PI_TUI_WRITE_LOG=/tmp/tui-ansi.log` captures the raw ANSI stream written to stdout.

package/skills/pi-agent/references/usage.md

@@ -0,0 +1,129 @@
+# Using Pi
+
+Source: https://pi.dev/docs/latest/usage
+
+## Interface
+
+Interactive mode has four areas: startup header (shortcuts, loaded context files, prompt templates, skills, extensions), messages, editor, and footer. The footer shows cwd, session name, token/cache usage, cost, context usage, and current model; totals include assistant responses, usage reported by tools, and summary generation. The editor border indicates thinking level. Built-in UI (`/settings`) or extension UI can temporarily replace the editor.
+
+## Editor Features
+
+| Feature | How |
+|---|---|
+| File reference | Type `@` to fuzzy-search project files |
+| Path completion | Tab |
+| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
+| Copy response | Ctrl+X copies the last assistant message; in `/tree` it copies the selected message |
+| Images | Paste with Ctrl+V (Alt+V on Windows), or drag into the terminal |
+| Shell command | `!command` runs and sends output to the model |
+| Hidden shell command | `!!command` runs without sending output to the model |
+| External editor | Ctrl+G opens `externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere |
+
+## Slash Commands
+
+| Command | Description |
+|---|---|
+| `/login`, `/logout` | Manage OAuth or API-key credentials |
+| `/llama` | Download, load, unload llama.cpp router models (`references/llama-cpp.md`) |
+| `/model` | Switch models |
+| `/scoped-models` | Enable/disable models for Ctrl+P cycling |
+| `/settings` | Thinking level, theme, message delivery, transport |
+| `/resume`, `/new`, `/name <name>`, `/session` | Session management |
+| `/tree` | Jump to any point in the session and continue from there |
+| `/trust` | Save project trust decision for future sessions |
+| `/fork`, `/clone` | New session from a previous user message / duplicate active branch |
+| `/compact [prompt]` | Manually compact context, optionally with custom instructions |
+| `/copy` | Copy last assistant message to clipboard |
+| `/export [file]` | Export session to HTML or JSONL |
+| `/import <file>` | Import and resume a session from a JSONL file |
+| `/share` | Upload as private GitHub gist with shareable HTML link |
+| `/reload` | Reload keybindings, extensions, skills, prompts, themes, context files |
+| `/hotkeys`, `/changelog`, `/quit` | Shortcuts, version history, quit |
+
+Skills are available as `/skill:name`; prompt templates expand as `/templatename`; extensions can register custom commands.
+
+## Message Queue
+
+- Enter queues a steering message, delivered after the current assistant turn finishes its tool calls.
+- Alt+Enter queues a follow-up message, delivered after the agent finishes all work.
+- Escape aborts and restores queued messages to the editor; Alt+Up retrieves them.
+- `steeringMode` and `followUpMode` control one-at-a-time vs all-at-once delivery.
+
+On Windows Terminal, Alt+Enter is fullscreen by default — remap it (`references/terminal-setup.md`).
+
+## Context and System Prompt Files
+
+Pi loads `AGENTS.md` or `CLAUDE.md` from `~/.pi/agent/AGENTS.md`, parent directories walking up from cwd, and the current directory. A directory containing `AGENTS.override.md` contributes that file instead of its `AGENTS.md`/`CLAUDE.md`; other directories still layer normally. Disable with `--no-context-files` / `-nc`.
+
+Replace the default system prompt with `.pi/SYSTEM.md` (project) or `~/.pi/agent/SYSTEM.md` (global). Append instead of replacing with `APPEND_SYSTEM.md` in either location.
+
+## Project Trust
+
+Interactive startup asks before trusting a project folder that has project-local settings, resources, or project `.agents/skills` and no saved decision for that folder or a parent in `~/.pi/agent/trust.json`. Before the decision, Pi loads only context files, user/global extensions, and CLI `-e` extensions so they can handle `project_trust`. Non-interactive modes (`-p`, `--mode json`, `--mode rpc`) never prompt and follow `defaultProjectTrust` (`ask` default, `never`, `always`); `--approve`/`-a` and `--no-approve`/`-na` override for one run. `/trust` saves a decision (including for the immediate parent folder) to `trust.json` without reloading the session. `pi config` and package commands use the same flow, except `pi update` never prompts.
+
+## Exporting and Sharing
+
+`/export [file]` writes HTML; `/share` uploads a private GitHub gist with a shareable HTML link. `badlogic/pi-share-hf` publishes sessions to Hugging Face datasets for research.
+
+## CLI Modes
+
+```bash
+pi [options] [@files...] [messages...]
+pi -p "prompt"                # print and exit
+pi --mode json "prompt"       # JSONL event stream
+pi --mode rpc                 # RPC over stdin/stdout
+pi --export <in> [out]        # export a session to HTML
+```
+
+Print mode reads piped stdin and merges it into the initial prompt.
+
+## Package Commands
+
+```bash
+pi install <source> [-l]     # -l writes to project settings
+pi remove <source> [-l]      # pi uninstall is an alias
+pi update [source|self|pi]   # update pi only, or one package source
+pi update --all              # pi + packages; reconcile pinned git refs
+pi update --extensions       # packages only
+pi update --models           # refresh model catalogs only
+pi update --self             # update pi only
+pi update --extension <src>  # update one package
+pi list                      # list installed packages
+pi config                    # enable/disable package resources
+```
+
+## Options
+
+Model: `--provider <name>`, `--model <pattern>` (supports `provider/id` and `:<thinking>`), `--api-key`, `--thinking <off|minimal|low|medium|high|xhigh|max>`, `--models <patterns>`, `--list-models [search]`.
+
+Session: `-c/--continue`, `-r/--resume`, `--session <path|id>`, `--fork <path|id>`, `--session-dir`, `--no-session`, `-n/--name`.
+
+Tools: `-t/--tools`, `-xt/--exclude-tools`, `-nbt/--no-builtin-tools` (keeps extension/custom tools), `-nt/--no-tools`. Built-ins: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`.
+
+Resources: `-e/--extension <source>` (path, npm, or git; repeatable), `--no-extensions`, `--skill`, `--no-skills`, `--prompt-template`, `--no-prompt-templates`, `--theme`, `--no-themes`, `-nc/--no-context-files`. Combine `--no-*` with explicit flags to load exactly what you need: `pi --no-extensions -e ./my-extension.ts`.
+
+Other: `--system-prompt <text>` (context files and skills are still appended), `--append-system-prompt`, `--tui-mode <regular|fullscreen>`, `--use-theme <name[/name]>` (initial theme for this run only), `--verbose`, `-a/--approve`, `-na/--no-approve`, `-h/--help`, `-v/--version`.
+
+## Fullscreen TUI Mode
+
+`--tui-mode fullscreen` (experimental) scrolls the transcript inside the terminal viewport while queued messages, working status, extension widgets, editor, and footer stay pinned at the bottom. Mouse/trackpad input scrolls the region under the pointer, and keyboard viewport actions (`tui.altScreen.*` in `references/keybindings.md`) stay available. Inline images work in terminals supporting the Kitty graphics protocol (Kitty, Ghostty); iTerm2 renders text placeholders instead. `regular` mode uses the main screen and terminal-owned scrollback. Switch at runtime and set the default in `/settings`; `fullscreenExitOutput` controls whether exiting prints the final transcript or only the resume hint.
+
+File arguments: prefix with `@` to include in the message (`pi @code.ts @test.ts "Review these"`).
+
+Environment variables are documented separately in `references/environment-variables.md`.
+
+## Examples
+
+```bash
+pi "List all .ts files in src/"
+pi --name "release audit" -p "Audit this repository"
+pi --model openai/gpt-4o "Help me refactor"
+pi --model sonnet:high "Solve this complex problem"
+pi --models "claude-*,gpt-4o"
+pi --tools read,grep,find,ls -p "Review the code"
+pi --exclude-tools ask_question
+```
+
+## Design Principles
+
+Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages. It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. Build or install those workflows as extensions/packages, or use external tools such as containers and tmux.

package/skills/pi-agent/references/windows.md

@@ -0,0 +1,23 @@
+# Windows Setup
+
+Source: https://pi.dev/docs/latest/windows
+
+Pi requires a bash shell on Windows. It checks, 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)
+
+[Git for Windows](https://git-scm.com/download/win) is sufficient for most users.
+
+## Custom Shell Path
+
+```json
+{
+  "shellPath": "C:\\cygwin64\\bin\\bash.exe"
+}
+```
+
+The value is JSON, so each literal backslash in the Windows path must be doubled.
+
+Related Windows notes: Ctrl+Enter for multi-line input, Alt+V to paste images, `app.suspend` has no default binding (`references/keybindings.md`), and Alt+Enter must be remapped away from fullscreen (`references/terminal-setup.md`).