ralph-cli-sandboxed 0.6.3 → 0.6.5

package/docs/CHAT-RESPONDERS.md

@@ -240,10 +240,10 @@ LLM responders automatically detect file paths mentioned in messages and include
 The responder will automatically read the file, extract ~20 lines around line 50, and include it in the LLM context.
 
 **Limits:**
-- Max 50KB total file content per message
-- Max 30KB per individual file
+- Max 15KB total file content per message
+- Max 8KB per individual file
 - Files larger than 100KB are skipped
-- 50+ file extensions supported (ts, js, py, go, rs, java, etc.)
+- 42 file extensions supported (ts, js, py, go, rs, java, etc.)
 
 #### Git Diff Keywords
 

package/docs/DEVELOPMENT.md

@@ -47,23 +47,61 @@ ralph-cli-sandboxed/
 ├── src/
 │   ├── index.ts              # CLI entry point
 │   ├── commands/             # Command implementations
+│   │   ├── action.ts         # ralph action
+│   │   ├── branch.ts         # ralph branch (list, merge, delete, pr)
+│   │   ├── chat.ts           # ralph chat
+│   │   ├── config.tsx        # ralph config (TUI launcher)
+│   │   ├── daemon.ts         # ralph daemon
+│   │   ├── docker.ts         # ralph docker
+│   │   ├── fix-config.ts     # ralph fix-config
+│   │   ├── fix-prd.ts        # ralph fix-prd
+│   │   ├── help.ts           # ralph help
 │   │   ├── init.ts           # ralph init
-│   │   ├── run.ts            # ralph run
+│   │   ├── listen.ts         # ralph listen
+│   │   ├── logo.ts           # ralph logo
+│   │   ├── notify.ts         # ralph notify
 │   │   ├── once.ts           # ralph once
 │   │   ├── prd.ts            # PRD management commands
-│   │   ├── docker.ts         # Docker commands
+│   │   ├── prd-convert.ts    # PRD YAML-to-JSON conversion
+│   │   ├── progress.ts       # ralph progress
 │   │   ├── prompt.ts         # ralph prompt
-│   │   ├── fix-prd.ts        # ralph fix-prd
-│   │   └── help.ts           # ralph help
+│   │   ├── run.ts            # ralph run
+│   │   └── slack.ts          # ralph slack
+│   ├── providers/            # Chat platform providers
+│   │   ├── discord.ts        # Discord bot provider
+│   │   ├── slack.ts          # Slack bot provider
+│   │   └── telegram.ts       # Telegram bot provider
+│   ├── responders/           # Chat responder implementations
+│   │   ├── claude-code-responder.ts
+│   │   ├── cli-responder.ts
+│   │   └── llm-responder.ts
+│   ├── tui/                  # Terminal UI (config editor)
+│   │   ├── ConfigEditor.tsx  # Main config editor component
+│   │   ├── components/       # UI components
+│   │   ├── hooks/            # React hooks
+│   │   └── utils/            # TUI utilities
 │   ├── utils/
+│   │   ├── chat-client.ts    # Chat client interface
 │   │   ├── config.ts         # Configuration loading
+│   │   ├── daemon-actions.ts # Daemon action handling
+│   │   ├── daemon-client.ts  # Daemon client interface
+│   │   ├── llm-client.ts     # LLM API client
+│   │   ├── message-queue.ts  # Message queue management
+│   │   ├── notification.ts   # Notification utilities
 │   │   ├── prd-validator.ts  # PRD validation and recovery
-│   │   └── prompt.ts         # Interactive prompts
+│   │   ├── prompt.ts         # Interactive prompts
+│   │   ├── responder-logger.ts # Responder logging
+│   │   ├── responder-presets.ts # Responder preset loading
+│   │   ├── responder.ts      # Base responder logic
+│   │   └── stream-json.ts    # JSON streaming utilities
 │   ├── templates/
+│   │   ├── macos-scripts.ts  # macOS/Swift script templates
 │   │   └── prompts.ts        # Prompt template generation
 │   └── config/
-│       ├── languages.json    # Language configurations
-│       └── cli-providers.json # CLI provider configurations
+│       ├── cli-providers.json    # CLI provider configurations
+│       ├── languages.json        # Language configurations
+│       ├── responder-presets.json # Chat responder presets
+│       └── skills.json           # Skill definitions
 ├── docs/                     # Documentation
 ├── dist/                     # Compiled output (generated)
 └── package.json

package/docs/DOCKER.md

@@ -18,8 +18,8 @@ ralph docker run
 | `ralph docker init` | Generate/regenerate Docker configuration files |
 | `ralph docker build` | Build the Docker image |
 | `ralph docker run` | Run ralph inside the container (auto-builds if needed) |
-| `ralph docker shell` | Open an interactive shell in the container |
-| `ralph docker status` | Show container and image status |
+| `ralph docker clean` | Remove Docker image and associated resources |
+| `ralph docker help` | Show help message |
 
 ## Generated Files
 
@@ -29,7 +29,8 @@ After running `ralph init` or `ralph docker init`, you'll find:
 .ralph/docker/
 ├── Dockerfile           # Container image definition
 ├── docker-compose.yml   # Container orchestration
-└── firewall.sh          # Network sandbox rules
+├── init-firewall.sh     # Network sandbox rules
+└── .dockerignore        # Build exclusions
 ```
 
 ## Features
@@ -206,7 +207,7 @@ sudo chown -R $(id -u):$(id -g) .ralph/
 
 The firewall script restricts outbound connections. If you need additional access:
 
-1. Edit `.ralph/docker/firewall.sh`
+1. Edit `.ralph/docker/init-firewall.sh`
 2. Add your required domains/IPs
 3. Rebuild: `ralph docker build`
 

package/docs/FAQ.md

@@ -0,0 +1,125 @@
+# FAQ
+
+## Getting Started
+
+### How do I initialize Ralph in my project?
+
+Run `ralph init` in your project root. The interactive wizard walks you through selecting a language, CLI provider (Claude Code, Aider, Codex, etc.), and optional skills. It creates the `.ralph/` directory with config files and generates Docker files automatically. Use `ralph init -y` to accept defaults (Claude Code + Node.js).
+
+### Which AI CLI tools does Ralph support?
+
+Ralph supports **Claude Code**, **Aider**, **Codex**, **Gemini CLI**, **OpenCode**, **AMP**, **Goose**, and **Ollama** out of the box. You can also use the `custom` provider to configure any CLI tool. Select your provider during `ralph init` or change it later in `.ralph/config.json` under `cliProvider`.
+
+### Which programming languages are supported?
+
+18 languages: TypeScript/Node, Python, Go, Rust, Java, Kotlin, C#/.NET, Ruby, PHP, Swift, Elixir, Scala, Zig, Haskell, Clojure, Deno, Bun, and Custom. Each comes with pre-configured `checkCommand` and `testCommand`.
+
+## Running Ralph
+
+### What's the difference between `ralph once` and `ralph run`?
+
+`ralph once` runs a single iteration inside the container. `ralph run` supports multiple modes:
+- `ralph run 5` — run 5 iterations
+- `ralph run --all` — run until all PRD items pass
+- `ralph run --loop` — run indefinitely, polling for new items every 30 seconds
+
+### When does Ralph stop running?
+
+Ralph stops when:
+- All PRD items are marked `passes: true`
+- The requested number of iterations is reached
+- 3 consecutive failures with the same exit code occur (likely a config error)
+- 3 iterations pass without progress (no tasks completed and no new tasks added)
+
+### Can I run Ralph without `ralph run`?
+
+Sometimes the execution (e.g. OpenCode) doesn't work or get stuck or isn't possible with free AMP. The following prompt lets Ralph loop, but keep in mind that no event is triggered when a task is finished:
+
+> Call in a loop `ralph prompt` and use this prompt — then check if @.ralph/prd.yaml has a task which isn't passes=true and start over with a fresh session and read the prompt and execute it.
+
+### How do I use a specific model?
+
+Pass `--model <name>` to `ralph run`, e.g. `ralph run --model claude-sonnet-4-5-20250929`. You can also set the model via environment variable (provider-specific: `CLAUDE_MODEL`, `AIDER_MODEL`, `CODEX_MODEL`, etc.).
+
+## PRD Management
+
+### What's the PRD format?
+
+PRD files (`.ralph/prd.yaml` or `.ralph/prd.json`) contain an array of items with:
+- `category` — one of: ui, feature, bugfix, setup, development, testing, docs
+- `description` — single sentence, imperative verb (e.g. "Add login page")
+- `steps` — concrete actions including verification steps
+- `passes` — boolean, set to `true` when the item is complete
+- `branch` — (optional) groups items onto a git branch
+
+### How do I write good PRD items?
+
+Keep items small and focused. Each item should be completable in one iteration. Write clear, concrete steps — include verification steps so the AI agent can confirm its work. Use `@{filepath}` syntax in steps to reference file contents.
+
+### My PRD got corrupted — what do I do?
+
+Run `ralph fix-prd`. It auto-diagnoses and repairs corruption (common when an LLM modifies the file incorrectly). Ralph also creates automatic backups in `.ralph/backups/` before each run. Use `ralph fix-prd --verify` to check without modifying, or restore from a specific backup file.
+
+## Docker & Containers
+
+### Why does Ralph need Docker?
+
+Docker provides a sandboxed environment where the AI agent runs with autonomous permissions (`--dangerously-skip-permissions` for Claude Code). This keeps your host system safe. The container also enforces network restrictions — only essential domains (GitHub, npm, your API provider) are allowed by default.
+
+### How do I add domains to the firewall whitelist?
+
+Add domains to `docker.firewall.allowedDomains` in `.ralph/config.json`, then rebuild the image with `ralph docker build`. You can also edit `.ralph/docker/init-firewall.sh` directly.
+
+### How do I add custom packages to the Docker image?
+
+Use `docker.packages` in config.json for system packages (installed via apt-get), or use `docker.buildCommands.root` / `docker.buildCommands.node` for custom build steps.
+
+### Can I customize ports, volumes, and environment variables?
+
+Yes — configure `docker.ports`, `docker.volumes`, and `docker.environment` in `.ralph/config.json`. Run `ralph docker init` to regenerate the docker-compose.yml after changes.
+
+## Branching
+
+### How does branching work in Ralph?
+
+Add a `branch` field to PRD items to group them onto a git branch. Ralph uses **git worktrees** (not `git checkout`) to isolate branch work — this avoids changing the host's mounted volume. Configure `docker.worktreesPath` in config.json to set where worktrees are stored on the host.
+
+### What branch commands are available?
+
+- `ralph branch list` — show all branches with item counts and status
+- `ralph branch merge <name>` — merge a completed branch back to base
+- `ralph branch pr <name>` — create a GitHub PR from the branch
+- `ralph branch delete <name>` — remove a worktree and delete the branch
+
+## Notifications & Monitoring
+
+### How do I set up notifications?
+
+Ralph supports **ntfy** (recommended — no install needed, just HTTP) and **command-based** notifications. Configure in `.ralph/config.json` under `notifications`. Events include `task_complete`, `prd_complete`, `ralph_complete`, `iteration_complete`, `run_stopped`, and `error`.
+
+### How do I monitor Ralph's progress?
+
+- `ralph status` — shows completion count, remaining items, and branch info
+- `ralph status --head` — compact status without item headlines
+- `.ralph/progress.txt` — detailed log of each iteration's work
+- `ralph progress summarize` — creates a timestamped backup and compresses the progress file
+
+## Troubleshooting
+
+### Ralph keeps failing after a few iterations
+
+If you see "CLI failed N times with exit code X", it's likely a configuration issue. Check:
+1. Your API key is set correctly (environment variable or mounted credentials)
+2. The CLI provider is installed and working outside Ralph
+3. Network connectivity — the firewall may be blocking required domains
+
+### Ralph seems stuck with "no progress"
+
+"No progress" means no PRD items were completed **and** no new items were added across 3 consecutive iterations. This usually means:
+- PRD steps are too vague for the AI to verify completion
+- The task is too large for a single iteration — break it into smaller items
+- The AI is hitting an error it can't resolve — check `.ralph/progress.txt` for details
+
+### The Docker image won't build
+
+Check that Docker is running, you have enough disk space, and platform-specific dependencies are available. If a provider installation fails, try `ralph docker build` again — transient network issues are common. For persistent failures, check the Dockerfile in `.ralph/docker/`.

package/docs/HOW-TO-WRITE-PRDs.md

@@ -22,16 +22,13 @@ Use consistent categories to organize your PRD:
 
 | Category | Use for |
 |----------|---------|
-| `setup` | Initial project configuration, build verification |
+| `ui` | User interface changes |
 | `feature` | New functionality |
 | `bugfix` | Fixing broken behavior |
-| `refactor` | Code improvements without behavior change |
+| `setup` | Initial project configuration, build verification |
+| `development` | Code improvements, refactoring, configuration |
+| `testing` | Adding or updating tests |
 | `docs` | Documentation updates |
-| `test` | Adding or updating tests |
-| `release` | Version bumps, changelog updates |
-| `config` | Configuration file changes |
-| `ui` | User interface changes |
-| `integration` | Connecting components, wiring, orchestration |
 
 ## Writing Good Descriptions
 
@@ -186,7 +183,7 @@ Break large features into smaller, independently completable items. Each item sh
 ## Quick Reference
 
 ```yaml
-- category: setup|feature|bugfix|refactor|docs|test|release|config|ui|integration
+- category: ui|feature|bugfix|setup|development|testing|docs
   description: Imperative verb + specific what + where (context)
   steps:
     - Concrete action with `commands` and file paths

package/docs/MACOS-DEVELOPMENT.md

@@ -392,9 +392,9 @@ ralph action gen_xcode
 With Ralph's Telegram integration, you can trigger actions remotely:
 
 ```
-/notify gen_xcode     # Generate Xcode project
-/notify build         # Build the project
-/notify fastlane_beta # Deploy to TestFlight
+/action gen_xcode     # Generate Xcode project
+/action build         # Build the project
+/action fastlane_beta # Deploy to TestFlight
 ```
 
 See the [Chat documentation](../README.md#chat-client-configuration) for setup.

package/docs/PRD-GENERATOR.md

@@ -39,7 +39,7 @@ tasks:    # <-- This wrapper causes issues
     description: ...
 ```
 
-> **Note:** Ralph will attempt to auto-unwrap common wrapper structures like `{tasks: [...]}`, `{items: [...]}`, or `{features: [...]}`, but it's best to use the correct format from the start.
+> **Note:** Ralph will attempt to auto-unwrap common wrapper structures like `{tasks: [...]}`, `{items: [...]}`, `{features: [...]}`, `{entries: [...]}`, `{prd: [...]}`, `{requirements: [...]}`, `{todo: [...]}`, or `{checklist: [...]}`, but it's best to use the correct format from the start.
 
 ### Required Fields
 
@@ -47,7 +47,7 @@ Each PRD item must have these fields:
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `category` | string | One of: setup, feature, bugfix, refactor, docs, test, release, config, ui, integration |
+| `category` | string | One of: ui, feature, bugfix, setup, development, testing, docs |
 | `description` | string | What to implement (imperative verb + specific action) |
 | `steps` | string[] | Concrete actions to complete the task |
 | `passes` | boolean | **Must be `false` for new items** - Ralph sets to `true` when completed |
@@ -144,16 +144,13 @@ If a task takes 2 minutes without thinking, combine with related work.
 
 | Category | When to Use |
 |----------|-------------|
-| `setup` | Project initialization, tooling, dependencies |
+| `ui` | User interface changes, frontend components |
 | `feature` | New functionality for users |
 | `bugfix` | Fixing broken behavior |
-| `refactor` | Code improvements, no behavior change |
+| `setup` | Project initialization, tooling, dependencies |
+| `development` | Code improvements, refactoring, configuration |
+| `testing` | Test coverage (unit, integration, e2e) |
 | `docs` | Documentation (README, guides, comments) |
-| `test` | Test coverage (unit, integration, e2e) |
-| `release` | Version bumps, changelogs, packaging |
-| `config` | Configuration files, settings |
-| `ui` | User interface changes, frontend components |
-| `integration` | Connecting components, wiring, orchestration |
 
 ## Branch Field (Optional)
 
@@ -197,7 +194,7 @@ PRD items can include an optional `branch` field to group related work into git
 ralph branch list              # Show all branches and their status
 ralph branch merge <name>      # Merge a completed branch into main
 ralph branch delete <name>     # Delete a branch and its worktree
-ralph branch pr <name>         # Create a PRD item to open a PR
+ralph branch pr <name>         # Create a GitHub PR from the branch
 ```
 
 ### When to Use Branches
@@ -406,7 +403,7 @@ Convert the following document into a Ralph prd.yaml file.
 
 Rules:
 1. Each sub-task or atomic feature = one PRD item
-2. Use categories: setup, feature, bugfix, refactor, docs, test, release, config, ui, integration
+2. Use categories: ui, feature, bugfix, setup, development, testing, docs
 3. Descriptions: imperative verb + specific what + context
 4. Steps: 2-4 concrete actions + verification step
 5. Reference source document sections instead of copying code
@@ -444,7 +441,7 @@ Convert the following document into a Ralph prd.json file.
 
 Rules:
 1. Each sub-task or atomic feature = one PRD item
-2. Use categories: setup, feature, bugfix, refactor, docs, test, release, config, ui, integration
+2. Use categories: ui, feature, bugfix, setup, development, testing, docs
 3. Descriptions: imperative verb + specific what + context
 4. Steps: 2-4 concrete actions + verification step
 5. Reference source document sections instead of copying code

package/docs/RALPH-SETUP-TEMPLATE.md

@@ -89,29 +89,30 @@ Set up a Ralph CLI project based on the configuration above.
 
 | Stack | language | checkCommand | testCommand |
 |-------|----------|--------------|-------------|
-| Node/TS (pnpm) | `typescript` | `pnpm lint && pnpm build` | `pnpm test` |
-| Node/TS (npm) | `node` | `npm run lint && npm run build` | `npm test` |
-| Node/TS (bun) | `typescript` | `bun run lint && bun run build` | `bun test` |
-| Python (pip) | `python` | `mypy . && ruff check .` | `pytest` |
-| Python (poetry) | `python` | `poetry run mypy . && poetry run ruff check .` | `poetry run pytest` |
-| Python (uv) | `python` | `uv run mypy . && uv run ruff check .` | `uv run pytest` |
-| Go | `go` | `go build ./... && go vet ./...` | `go test ./...` |
-| Rust | `rust` | `cargo build && cargo clippy` | `cargo test` |
-
-### Required Domains by Tech Stack
-
-| Stack | Package Registry Domains |
-|-------|--------------------------|
-| Node.js | `registry.npmjs.org`, `github.com` |
-| Python | `pypi.org`, `files.pythonhosted.org`, `github.com` |
-| Go | `proxy.golang.org`, `sum.golang.org`, `github.com` |
-| Rust | `crates.io`, `static.crates.io`, `github.com` |
+| Node/TS (npm) | `node` | `npm run typecheck` | `npm test` |
+| Node/TS (bun) | `bun` | `bun check` | `bun test` |
+| Python | `python` | `mypy .` | `pytest` |
+| Go | `go` | `go build ./...` | `go test ./...` |
+| Rust | `rust` | `cargo check` | `cargo test` |
+
+### Firewall Domains
+
+The Docker firewall allows these domains by default: `github.com`, `api.github.com`, `raw.githubusercontent.com`, `registry.npmjs.org`, `api.anthropic.com`.
+
+Add additional domains to `docker.firewall.allowedDomains` in `.ralph/config.json` based on your stack:
+
+| Stack | Recommended Additions |
+|-------|----------------------|
+| Python | `pypi.org`, `files.pythonhosted.org` |
+| Go | `proxy.golang.org`, `sum.golang.org` |
+| Rust | `crates.io`, `static.crates.io` |
 
 ### API Provider Domains
 
+Add these to `docker.firewall.allowedDomains` if using external APIs:
+
 | Provider | Domains |
 |----------|---------|
-| Anthropic Claude | `api.anthropic.com` |
 | OpenAI | `api.openai.com` |
 | Google AI | `generativelanguage.googleapis.com` |
 | AWS | `*.amazonaws.com` |
@@ -124,6 +125,8 @@ Set up a Ralph CLI project based on the configuration above.
 
 ### Notifications Config
 
+Supported providers: `ntfy`, `pushover`, `gotify`, `command`.
+
 Using ntfy (recommended - no install needed):
 ```json
 {
@@ -137,6 +140,32 @@ Using ntfy (recommended - no install needed):
 }
 ```
 
+Using pushover:
+```json
+{
+  "notifications": {
+    "provider": "pushover",
+    "pushover": {
+      "user": "your-user-key",
+      "token": "your-app-token"
+    }
+  }
+}
+```
+
+Using gotify:
+```json
+{
+  "notifications": {
+    "provider": "gotify",
+    "gotify": {
+      "server": "https://gotify.example.com",
+      "token": "your-app-token"
+    }
+  }
+}
+```
+
 Using custom command:
 ```json
 {
@@ -205,10 +234,14 @@ Log task completions and ralph finished to file:
 ```
 
 Chat commands (send in Telegram):
-- `/run` - Start ralph automation
+- `/run [category]` - Start ralph automation
 - `/status` - Show PRD progress
+- `/stop` - Stop a running ralph process
 - `/add [desc]` - Add new task
 - `/exec [cmd]` - Execute shell command
+- `/action [name]` - Execute a daemon action
+- `/claude [prompt]` - Run Claude Code with a prompt
+- `/branch [subcommand]` - Manage git branches
 - `/help` - Show help
 
 ### PRD Task Categories
@@ -216,12 +249,11 @@ Chat commands (send in Telegram):
 | Category | Use For |
 |----------|---------|
 | `setup` | Project initialization, dependency installation |
-| `config` | Environment variables, configuration files |
 | `feature` | New functionality implementation |
-| `integration` | External API clients, third-party services |
-| `test` | Unit tests, integration tests |
-| `refactor` | Code restructuring without behavior change |
 | `bugfix` | Bug fixes |
+| `ui` | User interface changes |
+| `development` | Development tooling, build configuration |
+| `testing` | Unit tests, integration tests |
 | `docs` | Documentation |
 
 ### PRD Guidelines
@@ -231,7 +263,7 @@ Chat commands (send in Telegram):
 - Include 2-4 concrete steps per task
 - End with a verification step (build, typecheck, test)
 - All tasks start with `"passes": false`
-- Order by dependency: setup -> config -> features -> tests -> docs
+- Order by dependency: setup -> development -> feature -> testing -> docs
 
 ### Sandbox Safety
 

package/docs/SECURITY.md

@@ -20,7 +20,9 @@ When running inside a container, ralph automatically passes the appropriate auto
 | AMP | `--dangerously-allow-all` | ✅ Supported |
 | Aider | `--yes-always` | ✅ Supported |
 | Goose | (none needed) | ✅ Supported |
-| OpenCode | `--yolo` | ❌ Not yet implemented |
+| OpenCode | (none) | ❌ Not yet implemented |
+| Ollama | (none needed) | ✅ Supported |
+| Custom | (none) | ⚙️ User-configured |
 
 For providers without autonomous mode support, you may need to manually approve actions during execution.
 
@@ -64,7 +66,7 @@ For Claude Code users with Pro/Max subscriptions, the `~/.claude` directory is m
 
 ```yaml
 volumes:
-  - ~/.claude:/home/node/.claude:ro
+  - ~/.claude:/home/node/.claude
 ```
 
 This allows the AI agent to use your existing OAuth credentials without exposing API keys.

package/docs/SKILLS.md

@@ -174,11 +174,11 @@ Target project-specific requirements:
 
 ## How Skills Are Applied
 
-When ralph runs an iteration:
+During `ralph docker init`:
 
 1. Skills from `claude.skills` are loaded from config
-2. Skill instructions are injected into the prompt template
-3. Claude receives the combined prompt with all active skill instructions
+2. Each skill is written as a `.claude/commands/<name>.md` file with YAML frontmatter (`description`, `user-invocable`)
+3. Claude Code natively reads these command files and applies the skill instructions
 
 This ensures Claude consistently follows your defined rules across all iterations.
 

package/docs/chat-architecture.md

@@ -47,7 +47,8 @@ The Ralph CLI chat system enables external control of Ralph projects via chat pl
 │  │ └─────────┘ │                    ▼                                        │
 │  └─────────────┘    ┌───────────────────────────────────────┐               │
 │                     │           Command Handler              │               │
-│                     │  run, stop, status, exec, add, claude  │               │
+│                     │  run, stop, status, exec, add, claude, │               │
+│                     │  help, start, action, branch           │               │
 │                     └───────────────────┬───────────────────┘               │
 │                                         │                                    │
 │                                         ▼                                    │
@@ -96,7 +97,7 @@ The Ralph CLI chat system enables external control of Ralph projects via chat pl
 ┌─────────────────────────────────────────────────────────────────┐
 │                    ResponderMatcher                              │
 │                                                                  │
-│  1. Check @mention triggers: @qa, @review, @explain, @code      │
+│  1. Check @mention triggers: @qa, @review, @arch, @explain, @code│
 │  2. Check keyword triggers: !lint, help                          │
 │  3. Fall back to default responder                               │
 └─────────────────────────────┬───────────────────────────────────┘
@@ -111,11 +112,11 @@ The Ralph CLI chat system enables external control of Ralph projects via chat pl
 ┌─────────────────────────────────────────────────────────────────┐
 │                    LLM Responder                                 │
 │                                                                  │
-│  1. Detect git keyword: "last" → git show HEAD                  │
+│  1. Detect git keyword: "last" → git show HEAD --stat --patch   │
 │  2. Fetch git diff content                                       │
 │  3. Build message with diff                                      │
 │  4. Load conversation history (if thread)                        │
-│  5. Send to LLM (Anthropic/OpenAI)                              │
+│  5. Send to LLM (Anthropic/OpenAI/Ollama)                       │
 │  6. Log to .ralph/logs/responder-YYYY-MM-DD.log                 │
 │  7. Return response                                              │
 └─────────────────────────────┬───────────────────────────────────┘
@@ -168,48 +169,54 @@ Reply in thread               history (max 20 messages)
 
 ## Message Queue Format
 
+The messages file stores a direct JSON array (no wrapper object):
+
 ```json
-{
-  "messages": [
-    {
-      "id": "uuid-1234",
-      "from": "host",
-      "action": "run",
-      "args": ["feature"],
-      "timestamp": 1706789012345,
-      "status": "pending"
-    },
-    {
-      "id": "uuid-1234",
-      "from": "host",
-      "action": "run",
-      "args": ["feature"],
-      "timestamp": 1706789012345,
-      "status": "done",
-      "response": {
-        "success": true,
-        "output": "Ralph run started (category: feature)"
-      }
+[
+  {
+    "id": "uuid-1234",
+    "from": "host",
+    "action": "run",
+    "args": ["feature"],
+    "timestamp": 1706789012345,
+    "status": "pending"
+  },
+  {
+    "id": "uuid-1234",
+    "from": "host",
+    "action": "run",
+    "args": ["feature"],
+    "timestamp": 1706789012345,
+    "status": "done",
+    "response": {
+      "success": true,
+      "output": "Ralph run started (category: feature)"
     }
-  ]
-}
+  }
+]
 ```
 
+Fields:
+- `from`: `"sandbox"` or `"host"`
+- `args`: optional string array
+- `status`: `"pending"` or `"done"`
+- `response`: optional, contains `success` (boolean), `output` (optional string), and `error` (optional string)
+
 ## Git Diff Keywords
 
 | Keyword | Git Command | Description |
 |---------|-------------|-------------|
 | `diff` / `changes` | `git diff` | Unstaged changes |
 | `staged` | `git diff --cached` | Staged changes |
-| `last` / `last commit` | `git show HEAD` | Last commit |
+| `last` / `last commit` | `git show HEAD --stat --patch` | Last commit |
 | `all` | `git diff HEAD` | All uncommitted |
-| `HEAD~N` | `git show HEAD~N` | N commits ago |
+| `HEAD~N` | `git show HEAD~N --stat --patch` | N commits ago |
 
 ## Responder Types
 
 | Type | Description | Example Trigger |
 |------|-------------|-----------------|
-| `llm` | Send to LLM (Anthropic/OpenAI) | `@qa`, `@review` |
+| `llm` | Send to LLM (Anthropic/OpenAI/Ollama) | `@qa`, `@review` |
 | `claude-code` | Spawn Claude Code CLI | `@code` |
 | `cli` | Run shell command | `!lint` |