feat: comprehensive TUI enhancements and features

.gitignore

@@ -6,4 +6,5 @@ dist/
 .ralph-done
 .ralph.log
 
-.reference/
+.reference/
+CONTEXT/

.ignore

@@ -0,0 +1 @@
+!CONTEXT/

.ralph-prompt.md.example

@@ -0,0 +1,22 @@
+# Ralph Custom Prompt Template
+
+This is an example custom prompt file for Ralph. Copy this to `.ralph-prompt.md` and customize.
+
+## Usage
+
+Ralph will automatically read `.ralph-prompt.md` from your project root, or you can specify a custom path:
+
+```bash
+ralph --prompt-file ./my-custom-prompt.md
+```
+
+## Placeholders
+
+- `{{PLAN_FILE}}` - Replaced with the plan file path (e.g., `plan.md`)
+- `{plan}` - Also replaced with the plan file path (legacy format)
+
+---
+
+## Example Prompt
+
+READ all of {{PLAN_FILE}}. Pick ONE task. If needed, verify via web/code search (this applies to packages, knowledge, deterministic data - NEVER VERIFY EDIT TOOLS WORKED OR THAT YOU COMMITED SOMETHING. BE PRAGMATIC ABOUT EVERYTHING). Complete task. Commit change (update the {{PLAN_FILE}} in the same commit). ONLY do one task unless GLARINGLY OBVIOUS steps should run together. Update {{PLAN_FILE}}. If you learn a critical operational detail, update AGENTS.md. When ALL tasks complete, create .ralph-done and exit. NEVER GIT PUSH. ONLY COMMIT.

AGENTS.md

@@ -90,6 +90,83 @@ useKeyboard((e: KeyEvent) => {
 
 4. **Terminal title reset**: Call `renderer.setTerminalTitle("")` before `renderer.destroy()` to reset the window title on exit.
 
+## Local Development & Building
+
+### Building and Installing Locally
+
+**ALWAYS follow this exact sequence when asked to build/install:**
+
+```bash
+# 1. Run tests first
+bun test
+
+# 2. Build all platform binaries
+bun run build
+
+# 3. Install to /usr/local/bin (Linux/macOS)
+sudo cp dist/hona-ralph-cli-linux-x64/bin/ralph /usr/local/bin/ralph
+
+# 4. Verify installation
+ralph -v
+```
+
+**Platform-specific binary paths:**
+- Linux x64: `dist/hona-ralph-cli-linux-x64/bin/ralph`
+- Linux arm64: `dist/hona-ralph-cli-linux-arm64/bin/ralph`
+- macOS x64: `dist/hona-ralph-cli-darwin-x64/bin/ralph`
+- macOS arm64: `dist/hona-ralph-cli-darwin-arm64/bin/ralph`
+- Windows x64: `dist/hona-ralph-cli-windows-x64/bin/ralph.exe`
+
+### Version Handling
+
+**CRITICAL**: Version is injected at build time via Bun's `define` option, NOT read from package.json at runtime.
+
+In `src/index.ts`:
+```typescript
+// @ts-expect-error - RALPH_VERSION is replaced at build time
+const version: string = RALPH_VERSION;
+```
+
+In `scripts/build.ts`:
+```typescript
+define: {
+  RALPH_VERSION: JSON.stringify(version),
+},
+```
+
+**Never import version from package.json** - it won't work in compiled binaries.
+
+### Version Bumping Workflow
+
+When releasing a new version:
+
+```bash
+# 1. Bump version (creates commit automatically if --no-git-tag-version is omitted)
+npm version patch --no-git-tag-version
+
+# 2. Commit the version bump
+git add package.json
+git commit -m "chore: bump version to X.Y.Z"
+
+# 3. Build and install
+bun run build
+sudo cp dist/hona-ralph-cli-linux-x64/bin/ralph /usr/local/bin/ralph
+
+# 4. Verify
+ralph -v
+
+# 5. Push
+git push origin master
+```
+
+### Common Pitfalls
+
+1. **Stale binary in PATH**: Check `which -a ralph` - there may be an old binary in `~/.bun/bin/ralph` shadowing the new one. Remove it: `rm ~/.bun/bin/ralph`
+
+2. **Shell hash cache**: After installing, run `hash -r` to clear the shell's command cache
+
+3. **Forgetting to rebuild**: The version is baked into the binary at build time. Changing package.json does nothing until you rebuild.
+
 ## NPM Publishing
 
 To release a new version to npm, run:

README.md

@@ -60,12 +60,46 @@ ralph --reset                      # start fresh, ignore previous state
 | `--model, -m` | `opencode/claude-opus-4-5` | Model (provider/model format) |
 | `--prompt` | see below | Custom prompt (`{plan}` placeholder) |
 | `--reset, -r` | `false` | Reset state |
+| `--server, -s` | (none) | OpenCode server URL to connect to |
+| `--server-timeout` | `5000` | Health check timeout in ms |
 
 **Default prompt:**
 ```
 READ all of {plan}. Pick ONE task. If needed, verify via web/code search (this applies to packages, knowledge, deterministic data - NEVER VERIFY EDIT TOOLS WORKED OR THAT YOU COMMITED SOMETHING. BE PRAGMATIC ABOUT EVERYTHING). Complete task. Commit change (update the plan.md in the same commit). ONLY do one task unless GLARINGLY OBVIOUS steps should run together. Update {plan}. If you learn a critical operational detail, update AGENTS.md. When ALL tasks complete, create .ralph-done and exit. NEVER GIT PUSH. ONLY COMMIT.
 ```
 
+### Connecting to an Existing Server
+
+Ralph can connect to an already-running OpenCode server instead of starting its own:
+
+```bash
+# Connect to local server on custom port
+ralph --server http://localhost:5000
+
+# Connect to remote server (requires shared filesystem)
+ralph -s http://192.168.1.100:4190
+
+# With custom timeout
+ralph --server http://localhost:4190 --server-timeout 10000
+```
+
+**Important:** Ralph reads `plan.md` and git state locally. When connecting to a remote server, ensure both machines have access to the same working directory (e.g., via NFS mount or the same repo checkout).
+
+## Configuration
+
+Ralph reads configuration from `~/.config/ralph/config.json`:
+
+```json
+{
+  "model": "opencode/claude-opus-4-5",
+  "plan": "plan.md",
+  "server": "http://localhost:4190",
+  "serverTimeout": 5000
+}
+```
+
+CLI arguments override config file values.
+
 ## Keybindings
 
 | Key | Action |

bin/ralph

@@ -0,0 +1 @@
+../dist/hona-ralph-cli-linux-x64/bin/ralph

docs/command-palette-fix.md

@@ -0,0 +1,4 @@
+## Command palette keyboard handling
+
+- **Issue**: Pressing `c` locked the app because the command palette dialog could be triggered while another dialog/input was focused and no repaint was forced, so the UI stopped responding but kept consuming `c`.
+- **Fix**: Made the keyboard-notified flag reactive to avoid repeated logging, prevented the palette from opening if a dialog is already stacked, and explicitly requested a render after showing the palette so the overlay appears immediately.