fix(setup): register explicit MCP runtimes and preserve launcher identity

docs/client-configuration.md

@@ -6,6 +6,40 @@ for the reviewed setup transaction and [client IDs](installation.md#supported-ag
 The versioned verification notes below describe their stated runs; live service
 acceptance is verified only where explicitly recorded.
 
+## Launchers and PATH
+
+A client launched from a desktop app, IDE or service can inherit a different
+`PATH` from your terminal. An absolute path to `rea-agents` does not resolve its
+interpreter: the npm launcher's `#!/usr/bin/env node` still searches `PATH` for
+Node. Running that command successfully in a terminal does not establish that
+the client can launch it.
+
+For direct JavaScript installations, setup registers the selected runtime
+executable and REA script by absolute path. On POSIX, it prefers executable
+`node` or `bun` and REA aliases on setup's `PATH` only when they resolve to the
+same selected files. This preserves manager-owned aliases across version updates;
+otherwise setup uses the selected paths directly. Package-runner registrations keep
+their selected runner. Setup does not copy your ambient environment into client
+settings. To refresh an older registration, preview
+`rea setup --client <client-id> --skill=false --dry-run`, then run the same command
+without `--dry-run` and approve the displayed changes. Setup preserves unrelated
+settings, backs up changed configuration and leaves an aligned registration
+unchanged. Restart the client after applying the update.
+
+If a runtime manager removes the registered executable and no surviving alias
+was available, doctor reports its identity as unknown and setup retains the
+registration. REA does not infer that an arbitrary missing executable was Node
+from its script argument. Back up the client's configuration, verify the absolute
+path and supported version of the runtime you intend to use, then update only
+the runtime command, preserving the REA script arguments and other settings.
+Rerun setup to review the registration and restart the client.
+
+`rea mcp doctor --json` tests the production MCP adapter using the runtime
+executable and environment of the terminal running doctor. It does not launch
+the client's configured command or reproduce the client's environment. If doctor
+passes but the client disconnects, inspect the client's startup error and registered
+launcher; see [verification scope](client-verification.md#launch-environment-verification).
+
 ## Runtime settings and client deadlines
 
 `update_analysis_settings` changes curated defaults inside the running REA
@@ -267,6 +301,15 @@ Setup and doctor follow Qwen Code's tilde and working-directory-relative home
 overrides. Qwen Code also discovers personal skills in `~/.agents/skills`,
 where setup installs the bundled workflow.
 
+If an existing direct-script registration fails with `env: node: No such file or
+directory`, refresh it through setup as described under [Launchers and PATH](#launchers-and-path).
+For an immediate Qwen-specific workaround, when Node is installed in
+`/opt/homebrew/bin`, add `"PATH": "/opt/homebrew/bin:${PATH}"` to that server's
+existing `env` object and restart Qwen. Qwen expands `${PATH}` from its parent
+environment; other clients can use different substitution syntax. Qwen's stdio
+launcher inherits the parent `PATH` and applies server overrides; a reduced
+parent environment does not establish that Qwen removed Homebrew from it.
+
 ## Antigravity
 
 Antigravity 2.0 discovers personal skills in `~/.gemini/config/skills`.

docs/client-verification.md

@@ -11,6 +11,16 @@ and provider lanes. Each record below states its host, client version, model
 fixture, and remaining coverage; a native-client run with a loopback model does
 not establish live model-service acceptance.
 
+## Launch environment verification
+
+`rea mcp doctor --json` starts the production MCP adapter with the current runtime
+executable and environment. A healthy result establishes that adapter's
+initialization, discovery and target-free request flow; it does not verify a
+client's configured launcher or its inherited environment. Test the generated
+registration through the actual client, including a reduced `PATH` when checking
+desktop or service startup. Record the client version and launch environment
+separately from terminal doctor results. See [launcher troubleshooting](client-configuration.md#launchers-and-path).
+
 ## Published Pi code-mode renderer limit
 
 A separate probe of the published `@earendil-works/pi-codemode` 1.1.0 and 1.2.0
@@ -53,6 +63,14 @@ skill setting; Hermes discovers it through the selected `HERMES_HOME`.
 Set `REA_VERIFY_HERMES_STICKY_PROFILE=1` to exercise native Hermes selection of
 a named sticky profile with `HERMES_HOME` still pointing to its root.
 
+For Qwen on POSIX, set `REA_VERIFY_QWEN_REDUCED_PATH=1` and select its JavaScript
+entry point with `REA_VERIFY_QWEN_COMMAND` to test a restricted client environment.
+Setup retains the caller's `PATH`; the native Qwen `chat` or `call` run then uses
+an isolated `PATH` containing only Bash for the shell-tool fixture. The lane
+checks that `node`, `npm` and `npx` cannot be found and uses the generated REA
+registration unchanged. Its receipt records `reducedPath`, `clientPath` and
+`registrationCommand`; the option alone does not establish a passing native run.
+
 The Qwen lane also supports native Windows (verified with Qwen Code 0.25.1 and
 Node 24.19.0 for both `chat` and `call`). With Node 24.18.0, the same `call`
 journey reached full Evidence readback but the client aborted during exit with