robot-resources 1.14.1 → 1.15.0

package/README.md

@@ -1,78 +1,91 @@
-# robot-resources
+# Robot Resources
 
-> One command to install Robot Resources tools for any agent stack.
+> Tools for AI agents and agentic software. Humans have HR. Agents have RR.
+
+Robot Resources builds tools for AI agents and any software that makes LLM API calls — chatbots, RAG pipelines, AI-powered apps, internal tools. Two products today: **Router** (smart model selection — picks the right model for each task, 60-90% cost savings as a side effect) and **Scraper** (token compression for web content, median 91% token reduction). Both run locally. Both free.
+
+## Quick Start
 
 ```bash
-npx robot-resources
+npx -y robot-resources
 ```
 
-The wizard detects what you're building and walks you through the right setup — OpenClaw plugin install, JS library path, Python SDK path, MCP config for Cursor / Claude Code, or just the docs URL.
+Detects your project shape (Node / Python / OpenClaw) and installs the right shim. No login, no API keys to enter, no signup. Router uses your existing provider keys — they never leave your machine.
+
+## Router
+
+Smart model selection. Classifies each prompt by task type (coding / reasoning / analysis / simple_qa / creative / general), filters by model capability, then within the qualifying set picks the cheapest. Routes the right model for the task — cost savings (60-90% across mixed workloads) follow from that, not the other way around. Hybrid classification: keyword fast-path (~5ms, ~70% of prompts) + LLM slow-path for ambiguous prompts (~200ms). Routes across Anthropic, OpenAI, and Google when the corresponding keys are present.
 
-## What the wizard does
+Three ways to install on a dev machine:
 
-1. **Provisions an anonymous API key** via `POST /v1/auth/signup` (saved to `~/.robot-resources/config.json`). Optional — routing works without it; the key just lights up the dashboard at robotresources.ai/dashboard.
-2. **Detects your stack**:
-   - OpenClaw installed (`~/.openclaw/`) → installs the router plugin (in-process HTTP server) + scraper OC plugin, patches `openclaw.json`, restarts the gateway. **No Python, no daemon, no system service.**
-   - Non-OC + cwd has `package.json` with LangChain/LangGraph/Mastra → preselects "JS/TS agent."
-   - Non-OC + cwd has `requirements.txt` / `pyproject.toml` → preselects "Python agent."
-   - Non-OC + Cursor or Claude Code installed → preselects "MCP tool."
-3. **Runs the chosen path**:
-   - **JS/TS agent** → prints `npm install @robot-resources/router` + `import { routePrompt }` example
-   - **Python agent** → prints `pip install robot-resources` + `from robot_resources.router import route` example, plus an httpx fallback if you'd rather skip the SDK
-   - **Cursor / Claude Code** → writes the scraper MCP config into `~/.cursor/mcp.json` / `~/.claude/settings.json`
-   - **Docs** → prints the URL + exits
-   - **Install OpenClaw first** → redirect message + exits
+- **OpenClaw users** get an in-process plugin inside the OC gateway. Anthropic, OpenAI, and Google calls each route to their native upstream — no cross-shape body translation.
+- **Node projects** get an auto-attach shim (`NODE_OPTIONS=--require .../auto.cjs`). Every Anthropic, OpenAI, and Google SDK call from any Node process routes automatically. No code changes.
+- **Python projects** get a `.pth` auto-attach shim in your venv. Every `anthropic` / `openai` / `google.generativeai` SDK call routes automatically. No code changes.
 
-## Flags
+For runtimes that ignore `NODE_OPTIONS` / `.pth` (Bun, Deno, Vercel Edge, Go, Rust, etc.), call the HTTP API directly: `POST https://api.robotresources.ai/v1/route`. Authed by API key, 100 req/min, CORS open.
 
+For explicit control inside JS / Python code, use the routing-decision library:
+
+```bash
+npm install @robot-resources/router      # JS / TS
+pip install robot-resources              # Python (singular package name)
 ```
---for=<target>      langchain | python | cursor | claude-code | docs
-                    Skip the prompt and run that path directly.
-                    Required for non-TTY contexts (CI, piped, etc.)
---non-interactive   Treat as CI run regardless of TTY state
---yes / -y          Same as --non-interactive
+
+```js
+import { routePrompt } from '@robot-resources/router/routing';
+const decision = routePrompt('write a python function that reverses a string');
+// decision.selected_model → 'claude-haiku-4-5' (or similar — cheapest qualifying)
 ```
 
-Without flags in a non-TTY context, the wizard prints the `--for=` hint and exits cleanly — never blocks waiting for stdin.
+```python
+from robot_resources.router import route
+decision = route('write a python function that reverses a string')
+```
 
-## Pre-set the API key
+Returns a routing decision; your code makes the actual LLM call with the selected model. Each request goes from your machine straight to the lab's API (`api.anthropic.com` / `api.openai.com` / `generativelanguage.googleapis.com`) using your existing key for that lab. Nothing is relayed through our infrastructure.
 
-For fleets or CI:
+## Scraper
 
-```bash
-export RR_API_KEY=rr_live_...        # skip signup, use this key
-npx robot-resources --for=cursor     # or whatever path applies
-```
+Token compression for web content. Fetches any URL, strips noise, returns clean markdown with token count. Median 91% token reduction per page (verified across 41 page types). Mozilla Readability extraction (0.97 F1). Content-aware token estimation calibrated per content type, ±15% of actual BPE. 3-tier fetch (fast / stealth via TLS fingerprint / render via headless browser), BFS multi-page crawl, robots.txt compliance.
 
-## Five paths, one wizard
+Three ways to consume:
 
-| Path | What you get | Where |
-|---|---|---|
-| OpenClaw plugin | In-process router inside the OC gateway. Auto-routes Anthropic calls to the cheapest capable model. | `~/.openclaw/extensions/robot-resources-router/` |
-| JS/TS agent | `@robot-resources/router/routing` — pure ESM, zero deps, offline keyword classifier. | npm |
-| Python agent | `robot-resources` (singular) — thin httpx client over `/v1/route`. | PyPI |
-| HTTP API | Any language with curl/fetch. Authed by API key. | `POST https://api.robotresources.ai/v1/route` |
-| Cursor / Claude Code MCP | Scraper MCP wired into your tool's config (web fetches → 91% smaller markdown). | `~/.cursor/mcp.json` or `~/.claude/settings.json` |
+- **JS library** — `npm install @robot-resources/scraper` → `import { scrape } from '@robot-resources/scraper'`
+- **MCP server** — `npx -y @robot-resources/scraper scraper-mcp` exposes `scraper_compress_url(url)` and crawl tools to any MCP-compatible client. Auto-wired into OpenClaw by the wizard; for other clients (Cursor, Claude Code, Windsurf), add manually to your client's MCP config.
+- **OpenClaw plugin** — installed automatically via `npx robot-resources`. Hooks `before_tool_call` to redirect `web_fetch` through scraper compression.
 
-Full integration docs: https://robotresources.ai/docs
+No API keys, no config.
 
-## Architecture (post-PR-2.5)
+## Deploying to production
 
-The router used to be a Python daemon on `localhost:3838`. **Not anymore.** It now runs in-process inside whichever surface consumes it:
+The wizard's shell-config install reaches dev machines only — production processes don't read `.bashrc`, and env vars come from your deploy config. Copy-paste recipes for setting `NODE_OPTIONS` (Node) or installing the `.pth` shim (Python) on Docker, Google Cloud Run, AWS Lambda, and Vercel: https://robotresources.ai/docs/deploy/.
 
-- **OpenClaw** — the plugin's `register()` starts an HTTP server on `127.0.0.1:18790` inside OC's node process. Lifetime tied to OC. Zero daemon to keep alive.
-- **JS agents** — call `routePrompt()` directly. No HTTP at all. Pure function.
-- **Python / curl** — call `POST /v1/route` on `api.robotresources.ai`. Server-side classifier on Cloudflare Workers.
+## Advanced
 
-User provider keys never leave the user's machine. The platform never receives, stores, or transmits them.
+```
+npx robot-resources [flags]
 
-## Telemetry
+--for=<target>      langchain | python | cursor | claude-code | docs
+                    Skip the prompt and run that path directly.
+                    Required for non-TTY contexts (CI, piped, etc.)
+--non-interactive   Treat as CI run regardless of TTY state
+--yes / -y          Same as --non-interactive
+```
 
-Anonymous, fire-and-forget, opt-in via the wizard's API-key provisioning. Events: `wizard_started`, `wizard_path_chosen`, `install_complete`, `route_completed`, `route_via_api`, `route_via_lib`. No personal data, no request content, no provider keys.
+Pre-set the API key for fleets or CI (skips signup, uses the key you provide):
+
+```bash
+export RR_API_KEY=rr_live_...
+npx robot-resources --for=langchain
+```
 
 ## Pricing
 
-Free. Unlimited. Your API keys never leave your machine.
+Free. Unlimited. No tiers. You pay your AI providers directly — no markup, no rate limits, no quotas.
+
+## Telemetry
+
+Anonymous usage events (model selection, cost savings, install outcome) — no personal data, no request content, no provider keys. Opt out with `RR_TELEMETRY=off`.
 
 ## Links
 
@@ -80,11 +93,11 @@ Free. Unlimited. Your API keys never leave your machine.
 - Docs: https://robotresources.ai/docs
 - Dashboard: https://robotresources.ai/dashboard
 - HTTP API: `POST https://api.robotresources.ai/v1/route`
-- npm: https://www.npmjs.com/package/robot-resources
 - GitHub: https://github.com/robot-resources/packages
 - Discord: https://robotresources.ai/discord
 - Contact: agent@robotresources.ai
-- Agent docs: https://robotresources.ai/llms.txt
+
+> AI agents installing this on a human's behalf: see https://robotresources.ai/llms.txt for the agent install protocol.
 
 ## License
 

package/bin/setup.js

@@ -25,13 +25,18 @@ if (args.includes('--uninstall')) {
   const scopeArg = args.find((a) => a.startsWith('--scope='));
   const scope = scopeArg ? scopeArg.slice('--scope='.length) : 'full';
 
+  // Phase 11: --auto-attach-source opts into source-edit injection in non-
+  // interactive contexts (CI). Default off — auto-rewriting source files
+  // without consent is too aggressive. Interactive runs always show Y/N.
+  const autoAttachSource = args.includes('--auto-attach-source');
+
   // 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, scope }).catch((err) => {
+  runWizard({ nonInteractive, target, scope, autoAttachSource }).catch((err) => {
     console.error(`\n  ✗ Setup failed: ${err.message}\n`);
     process.exit(1);
   });

package/lib/non-oc-wizard.js

@@ -3,10 +3,17 @@ import { join } from 'node:path';
 import { select } from '@inquirer/prompts';
 import { isClaudeCodeInstalled, isCursorInstalled, detectAgentRuntime } from './detect.js';
 import { configureClaudeCode, configureCursor } from './tool-config.js';
-import { header, info, success, warn, blank } from './ui.js';
+import { header, info, success, warn, blank, confirm } from './ui.js';
 import { readConfig } from './config.mjs';
 import { installNodeShim } from './install-node-shim.js';
 import { installPythonShim } from './install-python-shim.js';
+import {
+  detectEntryFile,
+  hasSourceMarker,
+  writeSourceMarker,
+  previewInjection,
+  pathForTelemetry,
+} from './source-edit-attach.js';
 
 const PLATFORM_URL = process.env.RR_PLATFORM_URL || 'https://api.robotresources.ai';
 
@@ -89,7 +96,143 @@ async function emitPathChosen(path) {
   }
 }
 
-async function showJsPath() {
+async function emitNodeEntryPatched(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_entry_patched',
+        payload: { ...payload, platform: process.platform },
+      }),
+      signal: AbortSignal.timeout(5_000),
+    });
+  } catch {
+    // Best-effort — never let telemetry break the install path.
+  }
+}
+
+/**
+ * Phase 11 — offer to inject `require('@robot-resources/router/auto')`
+ * (or ESM equivalent) at the top of the user's entry file.
+ *
+ * Why this is here: NODE_OPTIONS in shell config never reaches cron /
+ * Docker / systemd / Lambda agents because those launchers don't read
+ * shell rc files. A line in the source survives any launcher.
+ *
+ * Gates:
+ *   - No package.json or no detectable entry → skip with a hint
+ *   - Marker already present → skip silently
+ *   - Non-interactive without `autoAttachSource` → skip with a hint;
+ *     auto-rewriting source files in CI without consent is too aggressive
+ *   - Y/N declined → skip silently, user can always re-run
+ */
+async function maybeInjectSourceEdit({ nonInteractive, autoAttachSource, cwd = process.cwd() } = {}) {
+  const detection = detectEntryFile(cwd);
+  if (!detection.path) {
+    info('No agent entry file detected — skipping source-attach step.');
+    info('Re-run from your project root, or add this line yourself at the top of your entry file:');
+    info("  require('@robot-resources/router/auto');   // CJS");
+    info("  // or:  import '@robot-resources/router/auto';   // ESM/TS");
+    await emitNodeEntryPatched({ outcome: 'no_entry_detected' });
+    return;
+  }
+
+  if (hasSourceMarker(detection.path)) {
+    info(`${pathForTelemetry(detection.path, cwd)} already has the auto-attach line — leaving it as-is.`);
+    await emitNodeEntryPatched({
+      outcome: 'already_present',
+      entry_path: pathForTelemetry(detection.path, cwd),
+    });
+    return;
+  }
+
+  // Non-interactive: skip unless explicit opt-in. Source files are sacred.
+  if (nonInteractive && !autoAttachSource) {
+    blank();
+    info('Skipping source-attach in non-interactive mode (auto-rewriting source needs consent).');
+    info(`To enable it in CI, re-run with:  npx robot-resources --for=langchain --auto-attach-source`);
+    info(`Or add this line manually at the top of ${pathForTelemetry(detection.path, cwd)}:`);
+    info("  require('@robot-resources/router/auto');   // CJS, or import '...' for ESM/TS");
+    await emitNodeEntryPatched({
+      outcome: 'skipped_non_interactive',
+      entry_path: pathForTelemetry(detection.path, cwd),
+    });
+    return;
+  }
+
+  // Multi-candidate ambiguity → ask which entry the user actually runs.
+  let target = detection.path;
+  if (!nonInteractive && detection.candidates.length > 1) {
+    const choices = detection.candidates.map((c) => ({
+      name: pathForTelemetry(c, cwd),
+      value: c,
+    }));
+    choices.push({ name: 'Skip — I\'ll add the line manually', value: '__skip__' });
+    target = await select({
+      message: 'Multiple entry candidates found. Which file runs your agent?',
+      default: detection.path,
+      choices,
+    });
+    if (target === '__skip__') {
+      await emitNodeEntryPatched({ outcome: 'declined_ambiguous_pick' });
+      return;
+    }
+  }
+
+  // Show the diff and ask Y/N (unless auto-attach is explicitly opt-in).
+  const preview = previewInjection(target);
+  blank();
+  success('Add the auto-attach line so routing also works under cron / Docker / systemd / Lambda?');
+  blank();
+  info(`File: ${pathForTelemetry(target, cwd)}`);
+  blank();
+  for (const line of preview.split('\n')) info(line);
+  blank();
+
+  let proceed = autoAttachSource;
+  if (!nonInteractive && !autoAttachSource) {
+    proceed = await confirm('Add the line?', { defaultYes: true });
+  }
+
+  if (!proceed) {
+    info('Skipped — you can re-run anytime.');
+    await emitNodeEntryPatched({
+      outcome: 'declined',
+      entry_path: pathForTelemetry(target, cwd),
+    });
+    return;
+  }
+
+  const result = writeSourceMarker(target);
+  if (result.ok) {
+    success(`Added the auto-attach line to ${pathForTelemetry(target, cwd)} (${result.syntax}).`);
+    if (result.backupWritten) info(`  Backup written to ${pathForTelemetry(`${target}.rr-backup`, cwd)}`);
+    info('Now your agent loads the router on every startup — no env vars, no terminal restart.');
+    await emitNodeEntryPatched({
+      outcome: 'patched',
+      entry_path: pathForTelemetry(target, cwd),
+      import_syntax: result.syntax,
+      backup_written: !!result.backupWritten,
+    });
+  } else {
+    warn(`Could not patch ${pathForTelemetry(target, cwd)}: ${result.error}`);
+    info('You can add the line yourself — see the snippet above.');
+    await emitNodeEntryPatched({
+      outcome: 'failed',
+      entry_path: pathForTelemetry(target, cwd),
+      error: result.error,
+    });
+  }
+}
+
+async function showJsPath({ nonInteractive = false, autoAttachSource = false } = {}) {
   blank();
   success('JS/TS integration');
   blank();
@@ -105,14 +248,10 @@ async function showJsPath() {
       }
     }
     blank();
-    info('Once your shell picks up the new NODE_OPTIONS, every Node agent on');
-    info('this machine routes Anthropic, OpenAI, and Google SDK calls through');
-    info('Robot Resources.');
-    if (process.platform === 'win32') {
-      info('Open a new cmd / PowerShell window — current terminals will not see the change.');
-    } else {
-      info('Open a new terminal — or run:  source ~/.zshrc   (or your shell rc)');
-    }
+    info('Phase 3+ NODE_OPTIONS shim installed. Works for desktop dev sessions');
+    info('after a terminal restart, but does NOT reach cron / Docker / systemd /');
+    info('Lambda. The next step adds a one-line require to your agent source so');
+    info('routing works regardless of how the process is launched.');
   } else {
     warn(result.message);
     blank();
@@ -124,6 +263,11 @@ async function showJsPath() {
       info('  export NODE_OPTIONS="${NODE_OPTIONS:-} --require ~/.robot-resources/router/auto.cjs"');
     }
   }
+
+  // Phase 11 — source-edit injection. Reaches cron / Docker / systemd / Lambda
+  // since the line lives in the user's source, not in shell config.
+  await maybeInjectSourceEdit({ nonInteractive, autoAttachSource });
+
   blank();
   info('Docs: https://robotresources.ai/docs/langchain');
   blank();
@@ -204,9 +348,9 @@ function showInstallOcPath() {
   blank();
 }
 
-async function runPath(path) {
+async function runPath(path, opts = {}) {
   switch (path) {
-    case 'js': await showJsPath(); break;
+    case 'js': await showJsPath(opts); break;
     case 'python': await showPythonPath(); break;
     case 'mcp': showMcpPath(); break;
     case 'docs': showDocsPath(); break;
@@ -221,11 +365,11 @@ async function runPath(path) {
  * - non-interactive AND no target: print hint with --for= options and exit
  * - interactive: 5-option menu via @inquirer/prompts.select
  */
-export async function runNonOcWizard({ nonInteractive = false, target = null } = {}) {
+export async function runNonOcWizard({ nonInteractive = false, target = null, autoAttachSource = false } = {}) {
   const normalized = normalizeTarget(target);
 
   if (normalized) {
-    await runPath(normalized);
+    await runPath(normalized, { nonInteractive, autoAttachSource });
     await emitPathChosen(normalized);
     return;
   }
@@ -249,7 +393,7 @@ export async function runNonOcWizard({ nonInteractive = false, target = null } =
       info(`Detected a ${autoTarget === 'js' ? 'Node' : 'Python'} project — installing the matching shim automatically.`);
       info('  Pass --for=<other> to override, or --uninstall to remove later.');
       blank();
-      await runPath(autoTarget);
+      await runPath(autoTarget, { nonInteractive, autoAttachSource });
       await emitPathChosen(autoTarget);
       return;
     }
@@ -334,7 +478,9 @@ export async function runNonOcWizard({ nonInteractive = false, target = null } =
     if (autoTarget) {
       info(`Detected a ${autoTarget === 'js' ? 'Node' : 'Python'} project — installing the matching shim automatically.`);
       blank();
-      await runPath(autoTarget);
+      // Treat the timed-out interactive session as non-interactive for the
+      // source-edit step too — we don't have a TTY to ask the Y/N on.
+      await runPath(autoTarget, { nonInteractive: true, autoAttachSource });
       await emitPathChosen(autoTarget);
       return;
     }
@@ -347,6 +493,6 @@ export async function runNonOcWizard({ nonInteractive = false, target = null } =
     return;
   }
 
-  await runPath(chosen);
+  await runPath(chosen, { nonInteractive, autoAttachSource });
   await emitPathChosen(chosen);
 }

package/lib/source-edit-attach.js

@@ -0,0 +1,335 @@
+import { existsSync, readFileSync, writeFileSync, statSync, unlinkSync } from 'node:fs';
+import { dirname, extname, join, relative, resolve, sep } from 'node:path';
+
+/**
+ * Source-edit injection for non-OC Node agents (Phase 11).
+ *
+ * The Phase-3 NODE_OPTIONS approach only reaches processes that inherit
+ * from a shell that loaded ~/.bashrc or ~/.zshrc. Cron / Docker / systemd /
+ * Lambda / Cloud Run / serverless functions do NOT inherit shell rc files,
+ * so the shim never loads in the agents that matter most. Funnel data
+ * showed a 45-point cliff: 53% reach `node_shim_installed`, only 8.6% ever
+ * emit `adapter_attached`.
+ *
+ * This module injects ONE LINE at the top of the user's entry source file:
+ *
+ *   // >>> robot-resources: auto-attach >>>
+ *   require('@robot-resources/router/auto');
+ *   // <<< robot-resources <<<
+ *
+ * (or `import '@robot-resources/router/auto';` for ESM/TS files.)
+ *
+ * The line runs whenever the agent process starts, regardless of how it
+ * was launched. Cron, Docker, systemd, Lambda — all work the same.
+ *
+ * Marker-block convention mirrors shell-config.js exactly so an `--uninstall`
+ * remove pass is text-based and never destructive on partial state.
+ *
+ * Backup: a `.rr-backup` is written once on first inject (never overwritten
+ * on re-inject) so `--uninstall --purge` can restore the original source
+ * even if the marker block was tampered with.
+ */
+
+export const MARK_BEGIN = '// >>> robot-resources: auto-attach >>>';
+export const MARK_END = '// <<< robot-resources <<<';
+
+const REQUIRE_LINE = "require('@robot-resources/router/auto');";
+const IMPORT_LINE = "import '@robot-resources/router/auto';";
+
+// File extensions we'll treat as Node source — anything else, refuse to
+// edit. Keeps us out of build artifacts (.min.js), declaration files (.d.ts),
+// JSON, etc.
+const VALID_EXTS = new Set(['.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx']);
+
+/**
+ * Decide which import syntax to inject for a given source file.
+ * Implements Node's resolution rules verbatim:
+ *   .cjs → cjs
+ *   .mjs → esm
+ *   .ts / .tsx → emit `import` (works under both ts-node CJS and tsx/ESM)
+ *   .js / .jsx → walk up to nearest package.json, check "type" field.
+ *                "module" → esm; anything else (or absent) → cjs.
+ */
+export function detectImportSyntax(entryPath) {
+  const ext = extname(entryPath).toLowerCase();
+  if (ext === '.cjs') return 'cjs';
+  if (ext === '.mjs') return 'esm';
+  if (ext === '.ts' || ext === '.tsx') return 'esm';
+
+  // Walk up from the file's directory until we hit a package.json or
+  // exhaust the path. This is what Node itself does for `.js` files.
+  let dir = dirname(resolve(entryPath));
+  while (true) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        return pkg.type === 'module' ? 'esm' : 'cjs';
+      } catch {
+        return 'cjs';
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return 'cjs';
+    dir = parent;
+  }
+}
+
+/**
+ * Locate the user's agent entry file under cwd. Staged fallback through
+ * standard package.json fields, then a convention scan.
+ *
+ * Returns { path, candidates }:
+ *   - path: absolute path to the chosen entry, or null if nothing matched
+ *   - candidates: every viable candidate found (used by the wizard to
+ *     show a select() prompt when ambiguous)
+ *
+ * Priority (first match wins for `path`, all viable hits go in `candidates`):
+ *   1. package.json `bin` — single-string or single-key object → entry
+ *   2. package.json `main`
+ *   3. package.json `exports["."]` (or `exports["."].default`)
+ *   4. parsed package.json `scripts.start` — regex against
+ *      `(node|tsx|ts-node|bun) <file>`
+ *   5. convention scan: src/index.{ts,js,mjs,cjs}, index.{ts,js,mjs,cjs},
+ *      src/agent.{ts,js}, agent.{ts,js}, src/main.{ts,js}, main.{ts,js},
+ *      src/app.{ts,js}, app.{ts,js}, src/bot.{ts,js}, bot.{ts,js}
+ */
+export function detectEntryFile(cwd = process.cwd()) {
+  const candidates = [];
+  const pkgPath = join(cwd, 'package.json');
+  let pkg = null;
+  if (existsSync(pkgPath)) {
+    try { pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')); } catch { /* malformed */ }
+  }
+
+  if (pkg) {
+    // Tier 1: bin
+    if (typeof pkg.bin === 'string') {
+      addCandidate(candidates, cwd, pkg.bin);
+    } else if (pkg.bin && typeof pkg.bin === 'object') {
+      for (const v of Object.values(pkg.bin)) {
+        if (typeof v === 'string') addCandidate(candidates, cwd, v);
+      }
+    }
+
+    // Tier 2: main
+    if (typeof pkg.main === 'string') addCandidate(candidates, cwd, pkg.main);
+
+    // Tier 3: exports["."]
+    const root = pkg.exports?.['.'] ?? pkg.exports;
+    if (typeof root === 'string') addCandidate(candidates, cwd, root);
+    else if (root && typeof root === 'object') {
+      const dflt = root.default ?? root.import ?? root.require;
+      if (typeof dflt === 'string') addCandidate(candidates, cwd, dflt);
+    }
+
+    // Tier 4: scripts.start parse
+    if (typeof pkg.scripts?.start === 'string') {
+      // Match `node ./foo.js`, `tsx src/agent.ts`, `bun run agent.ts` etc.
+      const m = pkg.scripts.start.match(/(?:node|tsx|ts-node|bun(?:\s+run)?)\s+(\S+)/);
+      if (m) addCandidate(candidates, cwd, m[1]);
+    }
+  }
+
+  // Tier 5: convention scan — only adds if the candidate file actually exists.
+  const conventions = [
+    'src/index.ts', 'src/index.js', 'src/index.mjs', 'src/index.cjs',
+    'index.ts', 'index.js', 'index.mjs', 'index.cjs',
+    'src/agent.ts', 'src/agent.js', 'agent.ts', 'agent.js',
+    'src/main.ts', 'src/main.js', 'main.ts', 'main.js',
+    'src/app.ts', 'src/app.js', 'app.ts', 'app.js',
+    'src/bot.ts', 'src/bot.js', 'bot.ts', 'bot.js',
+  ];
+  for (const rel of conventions) {
+    const abs = join(cwd, rel);
+    if (existsSync(abs) && !candidates.includes(abs)) candidates.push(abs);
+  }
+
+  // Filter to files that exist and have a valid extension. The package.json
+  // tiers might point at files that don't exist yet (e.g. a `main` of
+  // `dist/index.js` before the user has built). Don't try to inject into
+  // missing files.
+  const viable = candidates.filter((c) => existsSync(c) && VALID_EXTS.has(extname(c).toLowerCase()));
+
+  return { path: viable[0] ?? null, candidates: viable };
+}
+
+function addCandidate(arr, cwd, rel) {
+  // Strip leading ./, normalize, resolve relative to cwd.
+  const cleaned = rel.replace(/^\.\//, '');
+  const abs = join(cwd, cleaned);
+  if (!arr.includes(abs)) arr.push(abs);
+}
+
+/**
+ * Returns true if the given source file already contains our marker.
+ * Used to skip-if-already-installed and to gate uninstall.
+ */
+export function hasSourceMarker(filePath) {
+  try {
+    return readFileSync(filePath, 'utf-8').includes(MARK_BEGIN);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Idempotently inject the auto-attach marker block at the top of the file
+ * (after shebang, if present). Writes a one-time backup at `${filePath}.rr-backup`.
+ *
+ * Returns { ok, alreadyInstalled, path, syntax, backupPath, error }.
+ */
+export function writeSourceMarker(filePath, opts = {}) {
+  const syntax = opts.syntax ?? detectImportSyntax(filePath);
+
+  let original;
+  try { original = readFileSync(filePath, 'utf-8'); }
+  catch (err) {
+    return { ok: false, alreadyInstalled: false, path: filePath, syntax, error: `read_failed: ${err.message}` };
+  }
+
+  if (original.includes(MARK_BEGIN)) {
+    return { ok: true, alreadyInstalled: true, path: filePath, syntax, backupPath: backupPathFor(filePath) };
+  }
+
+  // Backup once. Never overwrite — preserves the user's pristine original
+  // even if they manually edit before our second pass.
+  const backupPath = backupPathFor(filePath);
+  let backupWritten = false;
+  if (!existsSync(backupPath)) {
+    try {
+      writeFileSync(backupPath, original, { mode: getMode(filePath) });
+      backupWritten = true;
+    } catch (err) {
+      return { ok: false, alreadyInstalled: false, path: filePath, syntax, error: `backup_failed: ${err.message}` };
+    }
+  }
+
+  // Insert position: after shebang line if present, otherwise at top.
+  // We do NOT try to skip past `"use strict";` — modern Node treats it as
+  // a normal directive; placing our require/import before it is harmless.
+  const line = syntax === 'esm' ? IMPORT_LINE : REQUIRE_LINE;
+  const block = `${MARK_BEGIN}\n${line}\n${MARK_END}\n`;
+
+  let next;
+  if (original.startsWith('#!')) {
+    const nl = original.indexOf('\n');
+    if (nl === -1) {
+      // single-line file, only a shebang — append our block on a new line
+      next = original + '\n' + block;
+    } else {
+      next = original.slice(0, nl + 1) + block + original.slice(nl + 1);
+    }
+  } else {
+    next = block + original;
+  }
+
+  try {
+    writeFileSync(filePath, next, { mode: getMode(filePath) });
+  } catch (err) {
+    return { ok: false, alreadyInstalled: false, path: filePath, syntax, error: `write_failed: ${err.message}`, backupPath, backupWritten };
+  }
+
+  return { ok: true, alreadyInstalled: false, path: filePath, syntax, backupPath, backupWritten };
+}
+
+/**
+ * Idempotently remove the marker block from the source file. Mirror of
+ * writeSourceMarker. Returns { ok, removed, restored, path, error }.
+ *
+ * If `restoreFromBackup` is true and a `.rr-backup` exists, restores from
+ * the backup instead of splicing. Used for `--purge`. The backup is
+ * deleted after a successful restore.
+ */
+export function removeSourceMarker(filePath, { restoreFromBackup = false } = {}) {
+  let original;
+  try { original = readFileSync(filePath, 'utf-8'); }
+  catch (err) {
+    return { ok: false, removed: false, restored: false, path: filePath, error: `read_failed: ${err.message}` };
+  }
+
+  if (restoreFromBackup) {
+    const backupPath = backupPathFor(filePath);
+    if (existsSync(backupPath)) {
+      try {
+        const pristine = readFileSync(backupPath, 'utf-8');
+        writeFileSync(filePath, pristine, { mode: getMode(filePath) });
+        unlinkSync(backupPath);
+        return { ok: true, removed: true, restored: true, path: filePath };
+      } catch (err) {
+        return { ok: false, removed: false, restored: false, path: filePath, error: `restore_failed: ${err.message}` };
+      }
+    }
+    // No backup → fall through to marker splice.
+  }
+
+  const startIdx = original.indexOf(MARK_BEGIN);
+  if (startIdx === -1) {
+    return { ok: true, removed: false, restored: false, path: filePath };
+  }
+  const endIdx = original.indexOf(MARK_END, startIdx);
+  if (endIdx === -1) {
+    return { ok: false, removed: false, restored: false, path: filePath, error: 'marker_end_missing' };
+  }
+
+  // Splice from MARK_BEGIN through end of MARK_END line + the trailing
+  // newline our writer added. Walk backward over leading newlines so
+  // repeated install/uninstall cycles don't accumulate blanks.
+  const afterEnd = original.indexOf('\n', endIdx);
+  const sliceEnd = afterEnd === -1 ? original.length : afterEnd + 1;
+
+  let sliceStart = startIdx;
+  while (sliceStart > 0 && original[sliceStart - 1] === '\n') sliceStart--;
+
+  const next = original.slice(0, sliceStart) +
+    (sliceStart > 0 ? '\n' : '') +
+    original.slice(sliceEnd);
+
+  try {
+    writeFileSync(filePath, next, { mode: getMode(filePath) });
+  } catch (err) {
+    return { ok: false, removed: false, restored: false, path: filePath, error: `write_failed: ${err.message}` };
+  }
+
+  return { ok: true, removed: true, restored: false, path: filePath };
+}
+
+/**
+ * Build the proposed diff a wizard can show before asking Y/N. Returns a
+ * UI-friendly string with the marker block + a few lines of context.
+ */
+export function previewInjection(filePath, opts = {}) {
+  const syntax = opts.syntax ?? detectImportSyntax(filePath);
+  const line = syntax === 'esm' ? IMPORT_LINE : REQUIRE_LINE;
+  let original = '';
+  try { original = readFileSync(filePath, 'utf-8'); } catch { /* ignore */ }
+  const firstLines = original.split('\n').slice(0, 3).join('\n');
+  return [
+    `+ ${MARK_BEGIN}`,
+    `+ ${line}`,
+    `+ ${MARK_END}`,
+    firstLines.split('\n').map((l) => `  ${l}`).join('\n'),
+  ].join('\n');
+}
+
+function backupPathFor(filePath) {
+  return `${filePath}.rr-backup`;
+}
+
+function getMode(filePath) {
+  try { return statSync(filePath).mode & 0o777; } catch { return 0o644; }
+}
+
+/**
+ * Best-effort cwd-relative path for telemetry, falling back to basename
+ * if the file is outside cwd. Used to avoid leaking absolute paths (which
+ * can contain usernames) into Supabase.
+ */
+export function pathForTelemetry(filePath, cwd = process.cwd()) {
+  const rel = relative(cwd, filePath);
+  if (rel.startsWith('..') || rel.includes(sep + '..' + sep)) {
+    // Outside cwd — basename only.
+    return filePath.split(sep).pop();
+  }
+  return rel;
+}

package/lib/uninstall.js

@@ -6,6 +6,7 @@ import { removeShellLine } from './shell-config.js';
 import { detectVenv } from './venv-detect.js';
 import { spawnSync } from 'node:child_process';
 import { removePersistedNodeOptions } from './windows-env.js';
+import { detectEntryFile, hasSourceMarker, removeSourceMarker } from './source-edit-attach.js';
 
 /**
  * Single source of truth for `npx robot-resources --uninstall`.
@@ -115,6 +116,36 @@ export function runUninstall({ purge = false } = {}) {
     }
   }
 
+  // 3a. Phase 11 — source-edit auto-attach line. If the wizard injected
+  //     `require('@robot-resources/router/auto')` at the top of the user's
+  //     entry file, peel the marker block out (or restore from .rr-backup
+  //     when --purge). Idempotent: no-op when no entry detected or marker
+  //     not present. Runs against cwd, so users who --uninstall from a
+  //     different repo won't accidentally wipe the wrong file.
+  try {
+    const detection = detectEntryFile();
+    if (detection.path && hasSourceMarker(detection.path)) {
+      const r = removeSourceMarker(detection.path, { restoreFromBackup: !!purge });
+      if (r.ok && (r.removed || r.restored)) {
+        components_removed.push(r.restored ? 'node_entry_restored_from_backup' : 'node_entry_marker_removed');
+      } else if (!r.ok) {
+        errors.push({ component: 'node_entry_source_edit', message: r.error || 'unknown' });
+      }
+    }
+    // --purge also wipes any leftover .rr-backup (covers the case where the
+    // user manually deleted the marker but kept the backup file around).
+    if (purge && detection.path && existsSync(`${detection.path}.rr-backup`)) {
+      try {
+        rmSync(`${detection.path}.rr-backup`, { force: true });
+        components_removed.push('node_entry_backup_purged');
+      } catch (err) {
+        errors.push({ component: 'node_entry_backup_purged', message: err.message });
+      }
+    }
+  } catch (err) {
+    errors.push({ component: 'node_entry_source_edit', message: err.message });
+  }
+
   // 3b. Copied router dir at ~/.robot-resources/router/ (Phase 8). The shell
   //     line points at this absolute path — once the line is gone, the
   //     copied files are dead weight. Remove them.

package/lib/wizard.js

@@ -26,6 +26,43 @@ const CLI_VERSION = (() => {
   }
 })();
 
+/**
+ * Fire `install_complete` once after the wizard finishes — for BOTH OC
+ * and non-OC paths. Phase 11 fix: previously this only fired on the OC
+ * path because the non-OC branch returned early. The 7-day funnel showed
+ * 0/58 non-OC users hitting this event for a week. Now both paths fire
+ * with a `path: 'oc' | 'non-oc'` discriminator so funnel queries can
+ * segment without a second event type.
+ *
+ * Best-effort with one retry. Total budget: ~20s. Telemetry never blocks
+ * the wizard exit beyond that.
+ */
+async function emitInstallComplete({ apiKey, payload }) {
+  if (!apiKey) return;
+  const platformUrl = process.env.RR_PLATFORM_URL || 'https://api.robotresources.ai';
+  const body = JSON.stringify({
+    product: 'cli',
+    event_type: 'install_complete',
+    payload,
+  });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const res = await fetch(`${platformUrl}/v1/telemetry`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body,
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (res.ok) break;
+    } catch {
+      // Try again on next iteration.
+    }
+  }
+}
+
 /**
  * Main setup wizard. In Option 4 (post-PR-2.5) the wizard does NOT install
  * a Python daemon, register a system service, or run a localhost health
@@ -43,7 +80,7 @@ const CLI_VERSION = (() => {
  *
  * No Python, no venv, no systemd, no port probe.
  */
-export async function runWizard({ nonInteractive = false, target = null, scope = 'full' } = {}) {
+export async function runWizard({ nonInteractive = false, target = null, scope = 'full', autoAttachSource = false } = {}) {
   header();
 
   // Detect OC once up front. Used both to branch into the non-OC wizard and
@@ -165,7 +202,31 @@ export async function runWizard({ nonInteractive = false, target = null, scope =
   // MCP config / docs / install-OC). The non-OC wizard's wizard_path_chosen
   // telemetry now fires too, since Step 0 above provisioned an api_key.
   if (!openclawDetected) {
-    await runNonOcWizard({ nonInteractive, target });
+    await runNonOcWizard({ nonInteractive, target, autoAttachSource });
+
+    // Phase 11: install_complete now fires for non-OC too. Closes the
+    // funnel signal that was 0/58 for a week.
+    if (results.auth) {
+      try {
+        const config = readConfig();
+        await emitInstallComplete({
+          apiKey: config.api_key,
+          payload: {
+            source: 'wizard',
+            path: 'non-oc',
+            cli_version: CLI_VERSION,
+            target: target ?? null,
+            scope,
+            auto_attach_source: !!autoAttachSource,
+            platform: process.platform,
+            os_release: osRelease(),
+            node_version: process.version,
+            install_duration_ms: Date.now() - wizardStartMs,
+            non_interactive: nonInteractive,
+          },
+        });
+      } catch { /* non-fatal */ }
+    }
     return;
   }
 
@@ -250,54 +311,32 @@ export async function runWizard({ nonInteractive = false, target = null, scope =
 
   // ── Install Complete Telemetry ───────────────────────────────────────────
   //
-  // Fire once after install, using the API key directly (not from config read-back).
-  // This immediately populates last_used_at and proves the key works end-to-end.
-  //
-  // Retry once with longer timeout — Cloudflare analytics showed client-side
-  // aborts on the original 5s single-attempt, leaving stranded signups with
-  // no telemetry. Two 10s attempts catch the long tail. Still fire-and-forget.
+  // Fire once after the OC install path completes. Non-OC fires its own
+  // install_complete higher up (right after runNonOcWizard returns), so
+  // both paths now produce this funnel signal — see emitInstallComplete().
 
   if (results.auth) {
     try {
       const config = readConfig();
-      const platformUrl = process.env.RR_PLATFORM_URL || 'https://api.robotresources.ai';
-      const installPayload = {
-        source: 'wizard',
-        cli_version: CLI_VERSION,
-        plugin_installed: results.pluginInstalled,
-        scraper: results.scraper || false,
-        platform: process.platform,
-        os_release: osRelease(),
-        node_version: process.version,
-        install_duration_ms: Date.now() - wizardStartMs,
-        openclaw_detected: results.openclawDetected,
-        openclaw_config_patched: results.openclawConfigPatched,
-        scraper_mcp_registered: results.scraperMcpRegistered,
-      };
-      const body = JSON.stringify({
-        product: 'cli',
-        event_type: 'install_complete',
-        payload: installPayload,
+      await emitInstallComplete({
+        apiKey: config.api_key,
+        payload: {
+          source: 'wizard',
+          path: 'oc',
+          cli_version: CLI_VERSION,
+          plugin_installed: results.pluginInstalled,
+          scraper: results.scraper || false,
+          platform: process.platform,
+          os_release: osRelease(),
+          node_version: process.version,
+          install_duration_ms: Date.now() - wizardStartMs,
+          openclaw_detected: results.openclawDetected,
+          openclaw_config_patched: results.openclawConfigPatched,
+          scraper_mcp_registered: results.scraperMcpRegistered,
+        },
       });
-
-      for (let attempt = 0; attempt < 2; attempt++) {
-        try {
-          const res = await fetch(`${platformUrl}/v1/telemetry`, {
-            method: 'POST',
-            headers: {
-              'Authorization': `Bearer ${config.api_key}`,
-              'Content-Type': 'application/json',
-            },
-            body,
-            signal: AbortSignal.timeout(10_000),
-          });
-          if (res.ok) break;
-        } catch {
-          // Try again on next iteration; outer catch handles total failure
-        }
-      }
     } catch {
-      // Non-fatal — install_complete is best-effort
+      // Non-fatal — install_complete is best-effort.
     }
   }
 

package/package.json

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