From d1327f87f208ef857caa887234e218babb1a3177 Mon Sep 17 00:00:00 2001
From: gaurav0107 <gauravdubey0107@gmail.com>
Date: Thu, 7 May 2026 00:36:46 +0530
Subject: [PATCH 1/3] docs: document pnpm as unsupported and add exit-code-2
 troubleshooting note

Users installing @testmuai/kane-cli via pnpm hit a silent exit with
status 2 because the v16-runner resolver in dist/index.js only searches
three levels above the package's dist/ directory, while pnpm places the
project-root node_modules/ four levels up. Without KANE_DEV_MODE=1 the
CLI produces no stdout or stderr, which makes the failure mode hard to
recognise.

This change only documents the user-visible symptom and the workaround;
the actual resolver fix lives in the downstream runtime and is tracked
in issue #24.

- docs/user-guide/installation.md: new "Install with pnpm or yarn"
  subsection that lists pnpm as unsupported, points at the new
  troubleshooting entry, and re-states the three supported install
  paths (npm global, Homebrew, shell installer).
- docs/user-guide/troubleshooting.md: new "CLI exits with code 2 and
  no output" entry covering the two common causes (missing
  auth/setup, pnpm install) and the KANE_DEV_MODE=1 diagnostic.

Refs: #24
---
 docs/user-guide/installation.md    | 12 ++++++++++++
 docs/user-guide/troubleshooting.md | 15 +++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/docs/user-guide/installation.md b/docs/user-guide/installation.md
index 9e59d20..0a855af 100644
--- a/docs/user-guide/installation.md
+++ b/docs/user-guide/installation.md
@@ -23,6 +23,18 @@ npm install -g @testmuai/kane-cli
 
 If your global `npm` prefix is not on `PATH`, add it before running `kane-cli`. You can find the prefix with `npm config get prefix`; the `kane-cli` binary lives in `<prefix>/bin` on macOS and Linux, and `<prefix>` on Windows.
 
+## Install with pnpm or yarn
+
+Installing kane-cli via **pnpm** is not currently supported. pnpm uses a different `node_modules` layout (the project-root `node_modules/` is one level deeper than with npm), and kane-cli's resolver for the platform-specific `v16-runner` binary does not yet search deep enough to find it. The symptom is a silent exit with status 2 shortly after startup — see [CLI exits with code 2 and no output](./troubleshooting.md#cli-exits-with-code-2-and-no-output) in the troubleshooting guide. This limitation is tracked in [issue #24](https://github.com/LambdaTest/kane-cli/issues/24).
+
+Until that is resolved, install kane-cli through one of the supported paths:
+
+- **npm** globally (`npm install -g @testmuai/kane-cli`, above).
+- **Homebrew** on macOS or Linux (`brew install LambdaTest/kane/kane-cli`). Does not require Node.
+- The **shell installer** for any POSIX system (`curl -fsSL https://raw.githubusercontent.com/LambdaTest/kane-cli/main/install.sh | sh`).
+
+yarn (classic and Berry) has not been verified end-to-end. If you use yarn, prefer the Homebrew or shell-installer path until it is explicitly supported.
+
 ## Verify installation
 
 Confirm the install by printing the version:
diff --git a/docs/user-guide/troubleshooting.md b/docs/user-guide/troubleshooting.md
index 9eafd7f..5998b22 100644
--- a/docs/user-guide/troubleshooting.md
+++ b/docs/user-guide/troubleshooting.md
@@ -88,6 +88,21 @@ kane-cli uploads run artifacts to TestmuAI TMS at the end of the session. If the
 
    If `project_id` is empty, set it with `kane-cli config project` or pick one in the TUI.
 
+## CLI exits with code 2 and no output
+
+If `kane-cli run` ends with exit status 2 and the run produces no stdout or stderr after the early startup lines, one of two things is usually happening:
+
+1. **Authentication or setup is missing.** This is the common case on a fresh machine. Run `kane-cli whoami`; if it reports "not configured", re-run `kane-cli login` (or pass `--username` / `--access-key` in non-interactive environments). See also ["Authentication failed"](#authentication-failed) above.
+2. **kane-cli was installed via an unsupported package manager** — most commonly **pnpm**. pnpm places the project-root `node_modules/` one level deeper than npm does, and the resolver for the bundled `v16-runner` binary does not yet search that deep, so the CLI aborts before it can print a useful error. This limitation is tracked in [issue #24](https://github.com/LambdaTest/kane-cli/issues/24); switch to one of the supported install paths listed in [Install with pnpm or yarn](./installation.md#install-with-pnpm-or-yarn) as a workaround.
+
+To surface the underlying error instead of a silent exit, re-run the same command with `KANE_DEV_MODE=1`:
+
+```bash
+KANE_DEV_MODE=1 kane-cli run "<objective>" --agent --headless
+```
+
+In dev mode, setup and resolver failures print an explanatory line before the process exits. Use that message to decide which of the two cases above applies; do not ship `KANE_DEV_MODE=1` in production scripts.
+
 ## "Update available" notice
 
 kane-cli checks the public npm registry for a newer release of `@testmuai/kane-cli` once every 24 hours. The result is cached locally so the check itself is non-blocking and silent on failure. When a newer version exists, kane-cli surfaces it as an "update available" notification with the current and latest versions and a severity label (`major`, `minor`, or `patch`).

From 8e378ce3ccda0db67461423c99815462e7763027 Mon Sep 17 00:00:00 2001
From: gaurav0107 <gauravdubey0107@gmail.com>
Date: Thu, 7 May 2026 00:39:06 +0530
Subject: [PATCH 2/3] docs: describe pnpm layout more precisely in installation
 note

Replaces the "one level deeper" phrasing (which depends on whether pnpm
is in hoisted or isolated mode) with a mode-independent explanation:
pnpm stores packages under node_modules/.pnpm/ and the resolver does
not search far enough up the tree to reach that layout.

Refs: #24
---
 docs/user-guide/installation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/user-guide/installation.md b/docs/user-guide/installation.md
index 0a855af..e6ac33c 100644
--- a/docs/user-guide/installation.md
+++ b/docs/user-guide/installation.md
@@ -25,7 +25,7 @@ If your global `npm` prefix is not on `PATH`, add it before running `kane-cli`.
 
 ## Install with pnpm or yarn
 
-Installing kane-cli via **pnpm** is not currently supported. pnpm uses a different `node_modules` layout (the project-root `node_modules/` is one level deeper than with npm), and kane-cli's resolver for the platform-specific `v16-runner` binary does not yet search deep enough to find it. The symptom is a silent exit with status 2 shortly after startup — see [CLI exits with code 2 and no output](./troubleshooting.md#cli-exits-with-code-2-and-no-output) in the troubleshooting guide. This limitation is tracked in [issue #24](https://github.com/LambdaTest/kane-cli/issues/24).
+Installing kane-cli via **pnpm** is not currently supported. pnpm places packages inside a nested `node_modules/.pnpm/` store, so the project-root `node_modules/` ends up deeper on disk than it would with npm. kane-cli's resolver for the platform-specific `v16-runner` binary does not yet search that far up the directory tree, so the runner is never found and the CLI aborts. The symptom is a silent exit with status 2 shortly after startup — see [CLI exits with code 2 and no output](./troubleshooting.md#cli-exits-with-code-2-and-no-output) in the troubleshooting guide. This limitation is tracked in [issue #24](https://github.com/LambdaTest/kane-cli/issues/24).
 
 Until that is resolved, install kane-cli through one of the supported paths:
 

From f5e71f5f35e3b42cbd18cf01ec2648cf4cc3a9e9 Mon Sep 17 00:00:00 2001
From: gaurav0107 <gauravdubey0107@gmail.com>
Date: Thu, 7 May 2026 00:41:24 +0530
Subject: [PATCH 3/3] docs: align troubleshooting pnpm phrasing with
 installation page

Brings the troubleshooting entry in line with the structural
explanation now used in installation.md (pnpm's node_modules/.pnpm/
store is the layout the resolver does not yet traverse), so the two
pages describe the same limitation in the same terms.

Refs: #24
---
 docs/user-guide/troubleshooting.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/user-guide/troubleshooting.md b/docs/user-guide/troubleshooting.md
index 5998b22..3534821 100644
--- a/docs/user-guide/troubleshooting.md
+++ b/docs/user-guide/troubleshooting.md
@@ -93,7 +93,7 @@ kane-cli uploads run artifacts to TestmuAI TMS at the end of the session. If the
 If `kane-cli run` ends with exit status 2 and the run produces no stdout or stderr after the early startup lines, one of two things is usually happening:
 
 1. **Authentication or setup is missing.** This is the common case on a fresh machine. Run `kane-cli whoami`; if it reports "not configured", re-run `kane-cli login` (or pass `--username` / `--access-key` in non-interactive environments). See also ["Authentication failed"](#authentication-failed) above.
-2. **kane-cli was installed via an unsupported package manager** — most commonly **pnpm**. pnpm places the project-root `node_modules/` one level deeper than npm does, and the resolver for the bundled `v16-runner` binary does not yet search that deep, so the CLI aborts before it can print a useful error. This limitation is tracked in [issue #24](https://github.com/LambdaTest/kane-cli/issues/24); switch to one of the supported install paths listed in [Install with pnpm or yarn](./installation.md#install-with-pnpm-or-yarn) as a workaround.
+2. **kane-cli was installed via an unsupported package manager** — most commonly **pnpm**. pnpm stores packages under a nested `node_modules/.pnpm/` directory, and the resolver for the bundled `v16-runner` binary does not yet search that layout, so the CLI aborts before it can print a useful error. This limitation is tracked in [issue #24](https://github.com/LambdaTest/kane-cli/issues/24); switch to one of the supported install paths listed in [Install with pnpm or yarn](./installation.md#install-with-pnpm-or-yarn) as a workaround.
 
 To surface the underlying error instead of a silent exit, re-run the same command with `KANE_DEV_MODE=1`:
 
