robot-resources 1.11.2 → 1.12.1

package/bin/setup.js

@@ -19,13 +19,19 @@ if (args.includes('--uninstall')) {
   const targetArg = args.find((a) => a.startsWith('--for='));
   const target = targetArg ? targetArg.slice('--for='.length) : null;
 
+  // Phase 5: --scope=router-only is the entry from `npx @robot-resources/router`
+  // (the standalone bin). Skips scraper steps. Default 'full' matches the
+  // unified `npx robot-resources` behavior.
+  const scopeArg = args.find((a) => a.startsWith('--scope='));
+  const scope = scopeArg ? scopeArg.slice('--scope='.length) : 'full';
+
   // Treat piped/CI runs (no TTY on stdin OR stdout) as non-interactive so the
   // wizard never blocks on a prompt that can't be answered. The interactive
   // menu is only opened when both stdin and stdout are real terminals.
   const hasTty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
   const nonInteractive = explicitNonInteractive || !hasTty;
 
-  runWizard({ nonInteractive, target }).catch((err) => {
+  runWizard({ nonInteractive, target, scope }).catch((err) => {
     console.error(`\n  ✗ Setup failed: ${err.message}\n`);
     process.exit(1);
   });

package/lib/detect.js

@@ -125,3 +125,127 @@ export function isClaudeCodeInstalled() {
 export function isCursorInstalled() {
   return existsSync(join(homedir(), '.cursor'));
 }
+
+// ── Agent-runtime detection (Phase 3) ─────────────────────────────────────
+//
+// Used by the non-OC wizard to pick which shim to install: a NODE_OPTIONS
+// shell line for Node agents, or `pip install robot-resources` for Python.
+// Returns { kind: 'node'|'python'|null, evidence: string[] } so the wizard
+// can show the user WHY we picked a path (debuggable + builds trust).
+//
+// "Evidence" is the dep markers we found, in priority order. Empty string
+// means a generic project (e.g. just package.json, no LLM SDK deps yet) —
+// still picks the language but with low confidence.
+
+const NODE_AGENT_DEPS = [
+  '@anthropic-ai/sdk',
+  'openai',
+  '@google/generative-ai',
+  '@google-ai/generativelanguage',
+  'langchain',
+  '@langchain/core',
+  '@langchain/anthropic',
+  '@langchain/openai',
+  '@langchain/google-genai',
+  '@langchain/langgraph',
+  '@mastra/core',
+  'crewai-js',
+  'llamaindex',
+  'ai', // Vercel AI SDK
+];
+
+const PYTHON_AGENT_DEPS = [
+  'anthropic',
+  'openai',
+  'google-generativeai',
+  'langchain',
+  'langchain-anthropic',
+  'langchain-openai',
+  'langchain-google-genai',
+  'langgraph',
+  'crewai',
+  'llama-index',
+  'llama_index',
+];
+
+/**
+ * Inspect cwd for evidence of a Node agent project. Returns null if no
+ * package.json, or `{ evidence: [...] }` describing matched dep markers
+ * (empty list means "Node project but no LLM-SDK deps detected" — generic).
+ */
+export function detectNodeAgent(cwd = process.cwd()) {
+  const pkgPath = join(cwd, 'package.json');
+  if (!existsSync(pkgPath)) return null;
+
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    const allDeps = {
+      ...(pkg.dependencies ?? {}),
+      ...(pkg.devDependencies ?? {}),
+      ...(pkg.peerDependencies ?? {}),
+    };
+    const evidence = NODE_AGENT_DEPS.filter(
+      (d) => Object.prototype.hasOwnProperty.call(allDeps, d),
+    );
+    return { evidence };
+  } catch {
+    // package.json unreadable but exists — call it Node, no evidence
+    return { evidence: [] };
+  }
+}
+
+/**
+ * Inspect cwd for evidence of a Python agent project. Looks at
+ * requirements.txt + pyproject.toml. Returns null if neither exists, or
+ * `{ evidence: [...] }`. Empty evidence still resolves to Python — many
+ * agent projects use ad-hoc deps not in our markers list.
+ */
+export function detectPythonAgent(cwd = process.cwd()) {
+  const reqPath = join(cwd, 'requirements.txt');
+  const pyProjPath = join(cwd, 'pyproject.toml');
+  const hasReq = existsSync(reqPath);
+  const hasPy = existsSync(pyProjPath);
+  if (!hasReq && !hasPy) return null;
+
+  const text = [
+    hasReq ? safeRead(reqPath) : '',
+    hasPy ? safeRead(pyProjPath) : '',
+  ].join('\n').toLowerCase();
+
+  const evidence = PYTHON_AGENT_DEPS.filter((d) => {
+    // Match `dep`, `dep==`, `dep>=`, `dep[extras]`, or `"dep"`/`'dep'` in
+    // pyproject's dependencies array. Word-boundary on the left, anything
+    // version-ish on the right.
+    const escaped = d.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`(^|[\\s"'\\[])${escaped}(\\s|[<>=!~\\["',]|$)`, 'm');
+    return re.test(text);
+  });
+
+  return { evidence };
+}
+
+function safeRead(path) {
+  try { return readFileSync(path, 'utf-8'); } catch { return ''; }
+}
+
+/**
+ * Decide which shim to install when OpenClaw is NOT detected. Picks Node OR
+ * Python based on cwd shape. When BOTH are present (full-stack monorepo
+ * with package.json AND pyproject.toml) the caller is responsible for
+ * resolving the ambiguity (interactively, or default to JS in --yes mode
+ * per the team decision in the plan).
+ *
+ * Returns one of:
+ *   { kind: 'node',   evidence: [...] }
+ *   { kind: 'python', evidence: [...] }
+ *   { kind: 'both',   node: {...}, python: {...} }
+ *   { kind: null }     — unknown project shape, no clear path
+ */
+export function detectAgentRuntime(cwd = process.cwd()) {
+  const node = detectNodeAgent(cwd);
+  const python = detectPythonAgent(cwd);
+  if (node && python) return { kind: 'both', node, python };
+  if (node) return { kind: 'node', evidence: node.evidence };
+  if (python) return { kind: 'python', evidence: python.evidence };
+  return { kind: null };
+}

package/lib/install-node-shim.js

@@ -0,0 +1,142 @@
+import { writeShellLine, hasShellLine } from './shell-config.js';
+import { readConfig } from './config.mjs';
+import { detectNodeAgent } from './detect.js';
+
+const PLATFORM_URL = process.env.RR_PLATFORM_URL || 'https://api.robotresources.ai';
+
+/**
+ * Install the Node shim into the user's shell config. Phase 3 entry for
+ * the non-OC Node path.
+ *
+ * Steps:
+ *   1. Append the marker block to detected rc files (zsh / bash / fish)
+ *      via shell-config.writeShellLine. Idempotent: re-running does nothing
+ *      if the block is already present.
+ *   2. Emit `node_shim_installed` telemetry with the shell list, sdks
+ *      detected, dry-run flag, plus per-file errors.
+ *
+ * The user has to start a new shell (or `source` the file) for the
+ * NODE_OPTIONS to take effect — we tell them this in the wizard's
+ * post-install message. For Phase 3 we don't try to mutate the running
+ * shell; that's a Phase 6 nice-to-have.
+ *
+ * Windows: shell-config.writeShellLine returns no rc files on Windows
+ * (we only support POSIX in P3). The wizard prints manual instructions
+ * for Windows users in `non-oc-wizard.js`.
+ *
+ * Returns a UI-friendly result the wizard can format and print.
+ */
+export async function installNodeShim({ cwd = process.cwd(), dryRun = false } = {}) {
+  if (process.platform === 'win32') {
+    await emit({
+      shell: 'unsupported',
+      shell_config_path: null,
+      sdks_detected: detectSdks(cwd),
+      dry_run: dryRun,
+      reason: 'windows_not_supported_yet',
+    });
+    return {
+      ok: false,
+      reason: 'windows_not_supported_yet',
+      message:
+        'Windows shell-config writing is not yet supported. Set ' +
+        'NODE_OPTIONS=--require @robot-resources/router/auto manually in your ' +
+        'system environment variables, or wait for Phase 6.',
+    };
+  }
+
+  const sdks = detectSdks(cwd);
+
+  if (dryRun) {
+    await emit({
+      shell: 'dryrun',
+      shell_config_path: null,
+      sdks_detected: sdks,
+      dry_run: true,
+      reason: null,
+    });
+    return { ok: true, message: 'Dry-run: would have written NODE_OPTIONS to shell rc.' };
+  }
+
+  const alreadyInstalled = hasShellLine();
+  const result = writeShellLine();
+
+  // Single shell value for the funnel even though we may have written to
+  // multiple rc files. Pick the dominant one for telemetry.
+  const dominant = pickDominantShell(result.written);
+
+  await emit({
+    shell: dominant,
+    shell_config_path: result.written.join(','),
+    sdks_detected: sdks,
+    dry_run: false,
+    already_installed: alreadyInstalled,
+    files_written: result.written.length,
+    files_with_errors: result.errors.length,
+    error_messages: result.errors.map((e) => `${e.path}: ${e.message}`).slice(0, 3),
+  });
+
+  if (alreadyInstalled && result.written.length === 0) {
+    return {
+      ok: true,
+      already: true,
+      message: 'NODE_OPTIONS auto-attach already installed. No changes made.',
+    };
+  }
+
+  if (result.written.length === 0 && result.errors.length > 0) {
+    return {
+      ok: false,
+      message: `Could not write to any shell rc file. Errors: ${result.errors.map((e) => e.message).join(', ')}`,
+    };
+  }
+
+  return {
+    ok: true,
+    written: result.written,
+    errors: result.errors,
+    message:
+      `Installed NODE_OPTIONS auto-attach in ${result.written.length} shell file(s). ` +
+      'Open a new terminal (or source the file) for it to take effect.',
+  };
+}
+
+function detectSdks(cwd) {
+  const result = detectNodeAgent(cwd);
+  return result?.evidence ?? [];
+}
+
+function pickDominantShell(paths) {
+  // Use process.env.SHELL as the tiebreaker — that's the user's actual
+  // login shell. Fall back to the first written file's basename.
+  const shellEnv = (process.env.SHELL || '').toLowerCase();
+  if (shellEnv.includes('zsh')) return 'zsh';
+  if (shellEnv.includes('fish')) return 'fish';
+  if (shellEnv.includes('bash')) return 'bash';
+  if (paths[0]?.endsWith('.zshrc')) return 'zsh';
+  if (paths[0]?.endsWith('.bashrc') || paths[0]?.endsWith('.bash_profile')) return 'bash';
+  if (paths[0]?.endsWith('config.fish')) return 'fish';
+  return 'unknown';
+}
+
+async function emit(payload) {
+  const config = readConfig();
+  if (!config.api_key) return;
+  try {
+    await fetch(`${PLATFORM_URL}/v1/telemetry`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${config.api_key}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        product: 'cli',
+        event_type: 'node_shim_installed',
+        payload: { ...payload, platform: process.platform },
+      }),
+      signal: AbortSignal.timeout(5_000),
+    });
+  } catch {
+    // Best-effort — never let telemetry break the install path.
+  }
+}

package/lib/install-python-shim.js

@@ -0,0 +1,107 @@
+import { spawnSync } from 'node:child_process';
+import { detectVenv, runPipInstall } from './venv-detect.js';
+import { readConfig } from './config.mjs';
+import { detectPythonAgent } from './detect.js';
+
+const PLATFORM_URL = process.env.RR_PLATFORM_URL || 'https://api.robotresources.ai';
+
+/**
+ * Install the Python shim into the user's active/cwd venv. Phase 3 entry
+ * for the non-OC Python path.
+ *
+ * Steps:
+ *   1. Resolve Python via detectVenv. Bail with `confidence: 'low'` if we
+ *      can't find a venv — we never `pip install` into system Python (can
+ *      break OS Python on Linux).
+ *   2. Run `pip install --upgrade robot-resources`. Captures exit code +
+ *      stderr tail for telemetry.
+ *   3. Emit `python_shim_installed` telemetry with venv kind, Python
+ *      version, detected SDK markers, pip exit code.
+ *
+ * Returns a UI-friendly result the wizard can format and print. Never
+ * throws — any unexpected error becomes a structured `{ ok: false, ... }`.
+ */
+export async function installPythonShim({ cwd = process.cwd() } = {}) {
+  const venv = detectVenv(cwd);
+
+  if (!venv.python) {
+    await emit({
+      kind: 'none',
+      python_version: null,
+      sdks_detected: detectSdks(cwd),
+      pip_exit_code: null,
+      reason: 'no_venv_found',
+    });
+    return {
+      ok: false,
+      reason: 'no_venv_found',
+      message:
+        'No active venv or ./.venv detected. Activate your venv first ' +
+        '(source .venv/bin/activate) or pass --python=/path/to/python, ' +
+        'then re-run.',
+    };
+  }
+
+  const pipResult = runPipInstall({
+    python: venv.python,
+    packageSpec: 'robot-resources>=0.2.0',
+  });
+
+  const pythonVersion = readPythonVersion(venv.python);
+  const sdks = detectSdks(cwd);
+
+  await emit({
+    kind: venv.kind,
+    python_version: pythonVersion,
+    sdks_detected: sdks,
+    pip_exit_code: pipResult.code,
+    pip_stderr_tail: pipResult.ok ? null : pipResult.stderr,
+  });
+
+  return {
+    ok: pipResult.ok,
+    venv,
+    pythonVersion,
+    sdks,
+    pipResult,
+    message: pipResult.ok
+      ? `Installed robot-resources into ${venv.kind} venv (${venv.python})`
+      : `pip install failed (exit ${pipResult.code}): ${pipResult.stderr.slice(0, 200)}`,
+  };
+}
+
+function detectSdks(cwd) {
+  const result = detectPythonAgent(cwd);
+  return result?.evidence ?? [];
+}
+
+function readPythonVersion(python) {
+  try {
+    const r = spawnSync(python, ['--version'], { encoding: 'utf-8' });
+    return (r.stdout || r.stderr || '').trim().replace(/^Python\s+/, '');
+  } catch {
+    return null;
+  }
+}
+
+async function emit(payload) {
+  const config = readConfig();
+  if (!config.api_key) return;
+  try {
+    await fetch(`${PLATFORM_URL}/v1/telemetry`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${config.api_key}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        product: 'cli',
+        event_type: 'python_shim_installed',
+        payload: { ...payload, platform: process.platform },
+      }),
+      signal: AbortSignal.timeout(5_000),
+    });
+  } catch {
+    // Best-effort — never let telemetry break the install path.
+  }
+}

package/lib/non-oc-wizard.js

@@ -5,6 +5,8 @@ import { isClaudeCodeInstalled, isCursorInstalled } from './detect.js';
 import { configureClaudeCode, configureCursor } from './tool-config.js';
 import { header, info, success, warn, blank } from './ui.js';
 import { readConfig } from './config.mjs';
+import { installNodeShim } from './install-node-shim.js';
+import { installPythonShim } from './install-python-shim.js';
 
 const PLATFORM_URL = process.env.RR_PLATFORM_URL || 'https://api.robotresources.ai';
 
@@ -87,38 +89,61 @@ async function emitPathChosen(path) {
   }
 }
 
-function showJsPath() {
+async function showJsPath() {
   blank();
   success('JS/TS integration');
   blank();
-  info('Install:');
-  info('  npm install @robot-resources/router');
-  blank();
-  info('Use:');
-  info('  import { routePrompt } from \'@robot-resources/router/routing\';');
-  info('  const decision = routePrompt(\'write a python function\');');
-  info('  console.log(decision.selected_model); // e.g. \'claude-haiku-4-5\'');
+
+  const result = await installNodeShim();
+  if (result.ok) {
+    if (result.already) {
+      info(result.message);
+    } else {
+      success(result.message);
+      for (const path of result.written ?? []) {
+        info(`  • ${path}`);
+      }
+    }
+    blank();
+    info('Once your shell picks up the new NODE_OPTIONS, every Node agent on');
+    info('this machine routes Anthropic SDK calls through Robot Resources.');
+    info('Open a new terminal — or run:  source ~/.zshrc   (or your shell rc)');
+  } else {
+    warn(result.message);
+    blank();
+    info('Manual install (paste into ~/.zshrc or ~/.bashrc):');
+    info('  export NODE_OPTIONS="${NODE_OPTIONS:-} --require @robot-resources/router/auto"');
+  }
   blank();
-  info('Full docs: https://robotresources.ai/docs/langchain');
+  info('Docs: https://robotresources.ai/docs/langchain');
   blank();
 }
 
-function showPythonPath() {
+async function showPythonPath() {
   blank();
   success('Python integration');
   blank();
-  info('Install:');
-  info('  pip install robot-resources');
-  blank();
-  info('Use:');
-  info('  from robot_resources.router import route');
-  info('  decision = route(\'write a python function\')');
-  info('  print(decision[\'selected_model\'])  # e.g. \'claude-haiku-4-5\'');
-  blank();
-  info('Prefer no SDK? POST directly to https://api.robotresources.ai/v1/route');
-  info('with httpx / requests / any HTTP client. See docs.');
+
+  const result = await installPythonShim();
+  if (result.ok) {
+    success(result.message);
+    if (result.sdks?.length) {
+      info(`  Detected SDKs: ${result.sdks.join(', ')}`);
+    }
+    blank();
+    info('Set RR_AUTOATTACH=1 in your shell, then run your Python agent.');
+    info('Every anthropic.Anthropic() instance routes through Robot Resources.');
+    info('  echo \'export RR_AUTOATTACH=1\' >> ~/.zshrc   # or your shell rc');
+  } else {
+    warn(result.message);
+    blank();
+    info('Manual install (run inside your venv):');
+    info('  pip install --upgrade robot-resources');
+    info('Then set:');
+    info('  export RR_AUTOATTACH=1');
+  }
   blank();
-  info('Full docs: https://robotresources.ai/docs/crewai');
+  info('Docs: https://robotresources.ai/docs/crewai');
   blank();
 }
 
@@ -171,10 +196,10 @@ function showInstallOcPath() {
   blank();
 }
 
-function runPath(path) {
+async function runPath(path) {
   switch (path) {
-    case 'js': showJsPath(); break;
-    case 'python': showPythonPath(); break;
+    case 'js': await showJsPath(); break;
+    case 'python': await showPythonPath(); break;
     case 'mcp': showMcpPath(); break;
     case 'docs': showDocsPath(); break;
     case 'install-oc': showInstallOcPath(); break;
@@ -192,7 +217,7 @@ export async function runNonOcWizard({ nonInteractive = false, target = null } =
   const normalized = normalizeTarget(target);
 
   if (normalized) {
-    runPath(normalized);
+    await runPath(normalized);
     await emitPathChosen(normalized);
     return;
   }
@@ -242,6 +267,6 @@ export async function runNonOcWizard({ nonInteractive = false, target = null } =
     throw err;
   }
 
-  runPath(chosen);
+  await runPath(chosen);
   await emitPathChosen(chosen);
 }

package/lib/shell-config.js

@@ -0,0 +1,168 @@
+import { existsSync, readFileSync, writeFileSync, appendFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Idempotent writer for the NODE_OPTIONS auto-attach line in shell rc files.
+ *
+ * Phase 3 ships POSIX-only support: zsh, bash, fish. Windows ships a printed-
+ * instructions fallback (Phase 6 problem). Every write is wrapped in a
+ * marker block so `--uninstall` can find and remove cleanly without
+ * regex-matching against the user's actual shell content:
+ *
+ *     # >>> robot-resources: NODE_OPTIONS auto-attach >>>
+ *     export NODE_OPTIONS="${NODE_OPTIONS:-} --require @robot-resources/router/auto"
+ *     # <<< robot-resources <<<
+ *
+ * Behavior decisions (see plan):
+ *   - If NODE_OPTIONS is already set with a different --require (rare; e.g.
+ *     dd-trace), append ours after theirs. Both load. The user keeps their
+ *     existing tooling. The shell expansion `${NODE_OPTIONS:-} ...` handles
+ *     this correctly — POSIX shells concat space-separated --require flags.
+ *   - Never clobber. If our marker block already exists, it's a no-op.
+ *   - Write to ALL detected rc files (e.g. user has both .zshrc + .bashrc),
+ *     so the user gets routing in whichever shell they actually open.
+ */
+
+const MARK_BEGIN = '# >>> robot-resources: NODE_OPTIONS auto-attach >>>';
+const MARK_END = '# <<< robot-resources <<<';
+
+const POSIX_LINE =
+  'export NODE_OPTIONS="${NODE_OPTIONS:-} --require @robot-resources/router/auto"';
+
+// Fish has different syntax (no `export`, uses `set -x`). Detected separately.
+const FISH_LINE =
+  'set -x NODE_OPTIONS "$NODE_OPTIONS --require @robot-resources/router/auto"';
+
+/**
+ * Discover which rc files are present for this user. Returns a list of
+ * absolute paths in priority order (zsh first, bash second, fish third).
+ * The wizard writes to ALL of them — users frequently edit one shell's
+ * rc and forget another, and we'd rather over-cover than under-cover.
+ */
+export function listShellRcFiles(home = homedir()) {
+  const candidates = [
+    { kind: 'zsh', path: join(home, '.zshrc') },
+    { kind: 'bash', path: join(home, '.bashrc') },
+    { kind: 'bash', path: join(home, '.bash_profile') }, // macOS often uses this
+    { kind: 'fish', path: join(home, '.config', 'fish', 'config.fish') },
+  ];
+  return candidates.filter((c) => existsSync(c.path));
+}
+
+/**
+ * Returns true if at least one rc file already has our marker block.
+ * Used by both the wizard (skip-if-already-installed) and uninstall
+ * (gate the "remove" step).
+ */
+export function hasShellLine(home = homedir()) {
+  for (const { path } of listShellRcFiles(home)) {
+    try {
+      const text = readFileSync(path, 'utf-8');
+      if (text.includes(MARK_BEGIN)) return true;
+    } catch { /* unreadable rc, skip */ }
+  }
+  return false;
+}
+
+/**
+ * Idempotently append the marker block to every detected rc file. Returns
+ * a list of files actually modified (empty if everything already had it).
+ *
+ * Each rc file is treated independently: the writer never aborts the
+ * others on one failure. Per-file errors are returned as warnings the
+ * caller can surface.
+ */
+export function writeShellLine(home = homedir()) {
+  const rcs = listShellRcFiles(home);
+  const written = [];
+  const errors = [];
+
+  if (rcs.length === 0) {
+    // POSIX shells but no rc file yet — create ~/.zshrc on macOS (default
+    // since 10.15), ~/.bashrc on Linux. Better than silently no-op'ing.
+    const fallback = process.platform === 'darwin'
+      ? { kind: 'zsh', path: join(home, '.zshrc') }
+      : { kind: 'bash', path: join(home, '.bashrc') };
+    rcs.push(fallback);
+  }
+
+  for (const rc of rcs) {
+    try {
+      let text = '';
+      try { text = readFileSync(rc.path, 'utf-8'); } catch { /* file may not exist yet */ }
+
+      if (text.includes(MARK_BEGIN)) {
+        // Already installed. Skip silently.
+        continue;
+      }
+
+      const line = rc.kind === 'fish' ? FISH_LINE : POSIX_LINE;
+      const block =
+        (text && !text.endsWith('\n') ? '\n' : '') +
+        '\n' + MARK_BEGIN + '\n' + line + '\n' + MARK_END + '\n';
+
+      // Append, don't rewrite — preserves the user's content exactly.
+      appendFileSync(rc.path, block, { mode: 0o644 });
+      written.push(rc.path);
+    } catch (err) {
+      errors.push({ path: rc.path, message: err.message });
+    }
+  }
+
+  return { written, errors };
+}
+
+/**
+ * Idempotently REMOVE the marker block from every detected rc file.
+ * Mirror of writeShellLine. Returns a list of files actually modified.
+ *
+ * Removal is text-based (find MARK_BEGIN, find MARK_END, splice). If the
+ * block was tampered with — e.g. user manually deleted MARK_END — we leave
+ * the file alone and surface a warning. Never destructive on partial state.
+ */
+export function removeShellLine(home = homedir()) {
+  const rcs = listShellRcFiles(home);
+  const removed = [];
+  const errors = [];
+
+  for (const rc of rcs) {
+    try {
+      const text = readFileSync(rc.path, 'utf-8');
+      const startIdx = text.indexOf(MARK_BEGIN);
+      if (startIdx === -1) continue;
+      const endIdx = text.indexOf(MARK_END, startIdx);
+      if (endIdx === -1) {
+        errors.push({ path: rc.path, message: 'marker_end_missing' });
+        continue;
+      }
+
+      // Splice from MARK_BEGIN through end of MARK_END line + trailing newline.
+      const afterEnd = text.indexOf('\n', endIdx);
+      const sliceEnd = afterEnd === -1 ? text.length : afterEnd + 1;
+
+      // Walk back over the leading newline our writer added so we don't
+      // accumulate blank lines on repeated install/uninstall cycles.
+      let sliceStart = startIdx;
+      while (sliceStart > 0 && text[sliceStart - 1] === '\n') sliceStart--;
+
+      const next = text.slice(0, sliceStart) +
+        (sliceStart > 0 ? '\n' : '') +
+        text.slice(sliceEnd);
+
+      writeFileSync(rc.path, next, { mode: getMode(rc.path) });
+      removed.push(rc.path);
+    } catch (err) {
+      errors.push({ path: rc.path, message: err.message });
+    }
+  }
+
+  return { removed, errors };
+}
+
+function getMode(path) {
+  try { return statSync(path).mode & 0o777; } catch { return 0o644; }
+}
+
+// Exported for tests + telemetry payloads.
+export { MARK_BEGIN, MARK_END, POSIX_LINE, FISH_LINE };

package/lib/uninstall.js

@@ -2,21 +2,24 @@ import { existsSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { stripJson5 } from './json5.js';
+import { removeShellLine } from './shell-config.js';
+import { detectVenv } from './venv-detect.js';
+import { spawnSync } from 'node:child_process';
 
 /**
  * Single source of truth for `npx robot-resources --uninstall`.
  *
- * Reverses the install actions in tool-config.js: removes the router and
- * scraper OC plugin directories, deletes their entries from openclaw.json
- * (plugins.entries + plugins.allow + mcp.servers).
- *
- * Phase 0 scope is OC-only. Phase 3 will extend this with shell-config
- * removal (NODE_OPTIONS line) and `pip uninstall robot-resources` for the
- * Node and Python shim install paths.
+ * Reverses every install path the wizard might have taken:
+ *   1. OC plugin directories under ~/.openclaw/extensions/ (Phase 0)
+ *   2. Our entries in openclaw.json (plugins.entries + plugins.allow +
+ *      mcp.servers) (Phase 0)
+ *   3. NODE_OPTIONS marker block in shell rc files (Phase 3 — Node shim)
+ *   4. `robot-resources` PyPI package in the resolved venv (Phase 3 —
+ *      Python shim)
+ *   5. With --purge: ~/.robot-resources/ config dir (api_key + claim_url)
  *
  * `~/.robot-resources/config.json` is preserved by default so a subsequent
  * re-install reuses the same api_key (and the user's claim_url stays valid).
- * Pass { purge: true } to wipe it as well.
  *
  * Returns { components_removed: string[], errors: { component, message }[] }
  * for telemetry. Failure to remove one component never aborts the others —
@@ -83,7 +86,49 @@ export function runUninstall({ purge = false } = {}) {
     }
   }
 
-  // 3. Optionally wipe ~/.robot-resources/config.json (and any siblings)
+  // 3. Shell config — remove the NODE_OPTIONS marker block from any rc
+  //    files Phase 3's wizard wrote to. Idempotent: no-op if not present.
+  try {
+    const result = removeShellLine();
+    if (result.removed.length > 0) {
+      components_removed.push('shell_config_node_options');
+    }
+    for (const e of result.errors) {
+      errors.push({ component: 'shell_config_node_options', message: `${e.path}: ${e.message}` });
+    }
+  } catch (err) {
+    errors.push({ component: 'shell_config_node_options', message: err.message });
+  }
+
+  // 4. Python shim — `pip uninstall -y robot-resources` against the resolved
+  //    venv. Skip silently if no venv detected (the user may have installed
+  //    via the wizard but already deleted the venv themselves).
+  try {
+    const venv = detectVenv();
+    if (venv.python) {
+      const result = spawnSync(venv.python, ['-m', 'pip', 'uninstall', '-y', 'robot-resources'], {
+        encoding: 'utf-8',
+        timeout: 60_000,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      // pip exits 0 if removed, non-zero if package wasn't installed (also acceptable)
+      if (result.status === 0) {
+        components_removed.push('pip_robot_resources');
+      } else if (result.stderr && /not installed|skipping/i.test(result.stderr)) {
+        // Already gone — count as success silently.
+      } else if (result.status !== null) {
+        // Some other failure; record but don't abort
+        errors.push({
+          component: 'pip_robot_resources',
+          message: `pip exit ${result.status}: ${(result.stderr || '').slice(-200)}`,
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({ component: 'pip_robot_resources', message: err.message });
+  }
+
+  // 5. Optionally wipe ~/.robot-resources/config.json (and any siblings)
   if (purge) {
     const rrDir = join(homedir(), '.robot-resources');
     if (existsSync(rrDir)) {

package/lib/venv-detect.js

@@ -0,0 +1,85 @@
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+
+/**
+ * Resolve the Python interpreter we'll use for `pip install robot-resources`.
+ *
+ * Resolution order (decided in the plan; never silently install into system
+ * Python — that can break OS Python on Linux):
+ *
+ *   1. $VIRTUAL_ENV — currently-active venv. Strongest signal.
+ *   2. ./.venv/bin/python — common cwd venv (uv, hatch, plain venv default).
+ *   3. ./venv/bin/python — alternative cwd venv name.
+ *   4. pyproject.toml [tool.uv]/[tool.poetry] hint — best effort.
+ *   5. Bail with confidence='low'. Caller prompts user or errors out with
+ *      a `--python=/path/to/python` instruction in non-interactive mode.
+ *
+ * Returns:
+ *   { python: string, kind: 'active'|'cwd-venv'|'pyproject', confidence: 'high' }
+ *   OR
+ *   { python: null,   kind: 'none',                          confidence: 'low' }
+ */
+export function detectVenv(cwd = process.cwd()) {
+  // 1. Active venv — strongest signal.
+  const activeVenv = process.env.VIRTUAL_ENV;
+  if (activeVenv) {
+    const candidate = join(activeVenv, binSubdir(), 'python');
+    const candidate3 = join(activeVenv, binSubdir(), 'python3');
+    if (existsSync(candidate)) {
+      return { python: candidate, kind: 'active', confidence: 'high' };
+    }
+    if (existsSync(candidate3)) {
+      return { python: candidate3, kind: 'active', confidence: 'high' };
+    }
+  }
+
+  // 2. ./.venv (uv default, hatch default, plain venv default)
+  for (const dirname of ['.venv', 'venv']) {
+    const venvDir = join(cwd, dirname);
+    const cands = [
+      join(venvDir, binSubdir(), 'python'),
+      join(venvDir, binSubdir(), 'python3'),
+    ];
+    for (const c of cands) {
+      if (existsSync(c)) {
+        return { python: c, kind: 'cwd-venv', confidence: 'high' };
+      }
+    }
+  }
+
+  // 4. Bail. Never silently install into system Python.
+  return { python: null, kind: 'none', confidence: 'low' };
+}
+
+function binSubdir() {
+  return process.platform === 'win32' ? 'Scripts' : 'bin';
+}
+
+/**
+ * Run `python -m pip install <package>` against the resolved interpreter.
+ * Captures exit code + stderr tail for telemetry. Never throws.
+ *
+ * Phase 3 ships with `--upgrade` so existing 0.1.0 installs migrate to
+ * the auto-attach-capable 0.2.0 transparently.
+ */
+export function runPipInstall({ python, packageSpec, timeoutMs = 120_000 }) {
+  if (!python) {
+    return { ok: false, code: -1, stderr: 'no python interpreter resolved' };
+  }
+  const args = ['-m', 'pip', 'install', '--upgrade', packageSpec];
+  const result = spawnSync(python, args, {
+    encoding: 'utf-8',
+    timeout: timeoutMs,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  // Trim stderr to a sane size for telemetry — pip's full output is huge.
+  const stderr = (result.stderr || '').slice(-500);
+
+  return {
+    ok: result.status === 0,
+    code: result.status,
+    stderr,
+  };
+}

package/lib/wizard.js

@@ -43,7 +43,7 @@ const CLI_VERSION = (() => {
  *
  * No Python, no venv, no systemd, no port probe.
  */
-export async function runWizard({ nonInteractive = false, target = null } = {}) {
+export async function runWizard({ nonInteractive = false, target = null, scope = 'full' } = {}) {
   header();
 
   // Detect OC once up front. Used both to branch into the non-OC wizard and
@@ -142,6 +142,15 @@ export async function runWizard({ nonInteractive = false, target = null } = {})
             auth_method: results.authMethod,
             non_interactive: nonInteractive,
             openclaw_detected: openclawDetected,
+            // Phase 3: tags which install branch the wizard is about to take.
+            // 'oc' for the OpenClaw path, 'non-oc' covers everything the
+            // non-OC wizard handles (Node shim, Python shim, MCP, docs).
+            // Finer per-path attribution still comes from wizard_path_chosen.
+            entry: openclawDetected ? 'oc' : 'non-oc',
+            // Phase 5: 'full' is the unified `npx robot-resources` flow;
+            // 'router-only' is the standalone `npx @robot-resources/router`
+            // bin (skips scraper).
+            scope,
           },
         }),
         signal: AbortSignal.timeout(5_000),
@@ -209,27 +218,33 @@ export async function runWizard({ nonInteractive = false, target = null } = {})
   // Independent of router. Register scraper MCP in openclaw.json (if OC
   // is present). Gateway restart happens once at the very end (merged
   // with plugin restart).
-
-  blank();
-  step('Installing Scraper...');
+  //
+  // Phase 5: when invoked from `npx @robot-resources/router` (scope=router-only),
+  // we skip this step entirely. The standalone router CLI ships a smaller
+  // surface for users who explicitly want only routing, no scraper.
 
   let scraperRegistered = false;
 
-  scraperRegistered = registerScraperMcp();
-  if (scraperRegistered) {
-    success('Scraper MCP registered in OpenClaw — scraper_compress_url(url) available');
-    results.scraper = true;
-    results.scraperMcpRegistered = true;
-  } else {
-    try {
-      const ocConfig = JSON.parse(readFileSync(join(homedir(), '.openclaw', 'openclaw.json'), 'utf-8'));
-      if (ocConfig?.mcp?.servers?.['robot-resources-scraper']) {
-        success('Scraper MCP already registered in OpenClaw');
-        results.scraper = true;
-        results.scraperMcpRegistered = true;
+  if (scope !== 'router-only') {
+    blank();
+    step('Installing Scraper...');
+
+    scraperRegistered = registerScraperMcp();
+    if (scraperRegistered) {
+      success('Scraper MCP registered in OpenClaw — scraper_compress_url(url) available');
+      results.scraper = true;
+      results.scraperMcpRegistered = true;
+    } else {
+      try {
+        const ocConfig = JSON.parse(readFileSync(join(homedir(), '.openclaw', 'openclaw.json'), 'utf-8'));
+        if (ocConfig?.mcp?.servers?.['robot-resources-scraper']) {
+          success('Scraper MCP already registered in OpenClaw');
+          results.scraper = true;
+          results.scraperMcpRegistered = true;
+        }
+      } catch {
+        // No openclaw.json — not on OC, skip
       }
-    } catch {
-      // No openclaw.json — not on OC, skip
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "robot-resources",
-  "version": "1.11.2",
+  "version": "1.12.1",
   "description": "Robot Resources — AI agent tools. One command to install everything.",
   "type": "module",
   "bin": {