@ralph-orchestrator/ralph-cli 2.9.1 → 2.9.3

package/CHANGELOG.md

@@ -6,6 +6,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+### Fixed
+
+- Claude child sessions now default to `--setting-sources project,local`, preventing host user-level `~/.claude/settings.json` hooks, plugins, and MCP servers from leaking into Ralph orchestration runs. Users who want the old behavior can opt back in with `cli.args: ["--setting-sources", "user,project,local"]`.
+
+## [2.9.2] - 2026-04-10
+
+### Changed
+
+- Added a post-publish `cargo install` smoke test to the release workflow for faster detection of broken release artifacts.
+- Expanded `ralph doctor` auth environment variable detection for the Pi and Roo backends.
+- Documented the Pi backend in the backend guide.
+
+### Fixed
+
+- Fixed Claude + TUI blank/stuck output on large prompts by avoiding the PTY stdin deadlock in non-interactive PTY execution.
+
 ## [2.9.1] - 2026-04-04
 
 ### Fixed

package/README.md

@@ -181,6 +181,88 @@ Full documentation is available at **[mikeyobrien.github.io/ralph-orchestrator](
 - [Concepts: Hats & Events](https://mikeyobrien.github.io/ralph-orchestrator/concepts/hats-and-events/)
 - [Architecture](https://mikeyobrien.github.io/ralph-orchestrator/advanced/architecture/)
 
+
+## FAQ
+
+### General
+
+**What is Ralph Orchestrator?**
+Ralph is a hat-based orchestration framework that implements the Ralph Wiggum technique — autonomous task completion through continuous iteration. It keeps AI agents in a loop until the task is done, supporting multiple backends like Claude Code, Gemini CLI, Codex, and more.
+
+**How is Ralph different from other AI coding tools?**
+Unlike single-shot AI assistants, Ralph iterates until completion using a "hat system" with specialized personas. It includes backpressure gates (tests, lint, typecheck) that reject incomplete work, plus persistent memories and tasks for continuous learning.
+
+### Installation & Setup
+
+**What are the system requirements?**
+- Rust 1.75+ (for the `ralph-api` component)
+- Node.js >= 18 + npm (for the web dashboard frontend)
+- An AI coding assistant CLI (Claude Code, Codex, Gemini CLI, etc.)
+
+**Which installation method should I use?**
+- **npm** (recommended for most users): `npm install -g @ralph-orchestrator/ralph-cli`
+- **Cargo**: `cargo install ralph-cli` (best for Rust developers)
+- **GitHub Releases installer**: One-link install with `curl ... | sh`
+
+**Is Homebrew supported?**
+Homebrew is not currently published from this repository's automated release flow. Prefer npm, Cargo, or the GitHub Releases installer.
+
+### Usage
+
+**How do I start a new project with Ralph?**
+```bash
+ralph init --backend claude
+ralph plan "Add user authentication with JWT"
+ralph run -p "Implement the feature in specs/user-authentication/"
+```
+
+**What backends does Ralph support?**
+Claude Code, Kiro, Gemini CLI, Codex, Amp, Copilot CLI, and OpenCode.
+
+**What is the "hat system"?**
+Ralph uses specialized personas (hats) that coordinate through events. Each hat has a specific role — code-assist, debug, research, review, and pdd-to-code-assist — enabling structured multi-step task execution.
+
+### RObot (Human-in-the-Loop)
+
+**What is RObot?**
+RObot enables human interaction during orchestration via Telegram. Agents can ask questions and block until answered; humans can send proactive guidance mid-loop.
+
+**How do I set up Telegram integration?**
+```bash
+ralph bot onboard --telegram   # guided setup
+ralph bot status               # verify config
+ralph bot test                 # send a test message
+```
+
+### Web Dashboard
+
+**How do I access the web dashboard?**
+Run `ralph web` to start the Rust RPC API + frontend and open your browser. The dashboard is currently in Alpha — expect rough edges and breaking changes.
+
+**Can I customize the dashboard ports?**
+Yes: `ralph web --backend-port 4000 --frontend-port 8080`
+
+### MCP Server
+
+**How do I run Ralph as an MCP server?**
+```bash
+ralph mcp serve --workspace-root /path/to/repo
+```
+Each MCP server instance is scoped to a single workspace root. For multi-repo use, run one instance per workspace.
+
+### Troubleshooting
+
+**Ralph fails to start with "node_modules not found"**
+Run `npm install` in the project directory, or let `ralph web` auto-detect and install on first run.
+
+**How do I set up Node.js if not installed?**
+Use nvm (recommended): `nvm install` (reads `.nvmrc`), or install directly from https://nodejs.org/
+
+**Where can I get help?**
+- Join our [Discord server](https://discord.gg/XWUyeUNffh)
+- Report bugs on the [Issue Tracker](https://github.com/mikeyobrien/ralph-orchestrator/issues)
+- Read full documentation at [mikeyobrien.github.io/ralph-orchestrator](https://mikeyobrien.github.io/ralph-orchestrator/)
+
 ## Contributing
 
 Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards.

package/npm-shrinkwrap.json

@@ -23,7 +23,7 @@
       "hasInstallScript": true,
       "license": "MIT",
       "name": "@ralph-orchestrator/ralph-cli",
-      "version": "2.9.1"
+      "version": "2.9.3"
     },
     "node_modules/@isaacs/balanced-match": {
       "engines": {
@@ -515,5 +515,5 @@
     }
   },
   "requires": true,
-  "version": "2.9.1"
+  "version": "2.9.3"
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "artifactDownloadUrl": "https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.9.1",
+  "artifactDownloadUrl": "https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.9.3",
   "bin": {
     "ralph": "run-ralph.js"
   },
@@ -20,7 +20,7 @@
   },
   "glibcMinimum": {
     "major": 2,
-    "series": 35
+    "series": 31
   },
   "homepage": "https://github.com/mikeyobrien/ralph-orchestrator",
   "license": "MIT",
@@ -41,7 +41,21 @@
       "zipExt": ".tar.xz"
     },
     "aarch64-unknown-linux-gnu": {
-      "artifactName": "ralph-cli-aarch64-unknown-linux-gnu.tar.xz",
+      "artifactName": "ralph-cli-aarch64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "ralph": "ralph"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "aarch64-unknown-linux-musl-dynamic": {
+      "artifactName": "ralph-cli-aarch64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "ralph": "ralph"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "aarch64-unknown-linux-musl-static": {
+      "artifactName": "ralph-cli-aarch64-unknown-linux-musl.tar.xz",
       "bins": {
         "ralph": "ralph"
       },
@@ -55,14 +69,28 @@
       "zipExt": ".tar.xz"
     },
     "x86_64-unknown-linux-gnu": {
-      "artifactName": "ralph-cli-x86_64-unknown-linux-gnu.tar.xz",
+      "artifactName": "ralph-cli-x86_64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "ralph": "ralph"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-unknown-linux-musl-dynamic": {
+      "artifactName": "ralph-cli-x86_64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "ralph": "ralph"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-unknown-linux-musl-static": {
+      "artifactName": "ralph-cli-x86_64-unknown-linux-musl.tar.xz",
       "bins": {
         "ralph": "ralph"
       },
       "zipExt": ".tar.xz"
     }
   },
-  "version": "2.9.1",
+  "version": "2.9.3",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"