surf-cli 2.8.0 → 2.10.0

package/native/workflow-runtime.cjs

@@ -0,0 +1,225 @@
+const { redactCommandArgs } = require("./workflow-definition.cjs");
+
+const MAX_LOOP_ITERATIONS = 100;
+const AUTO_WAIT_COMMANDS = ["go", "navigate", "click", "key", "form.fill", "submit", "tab.switch", "tab.new", "back", "forward"];
+const AUTO_WAIT_MAP = {
+  navigate: "wait.load",
+  go: "wait.load",
+  click: "wait.dom",
+  key: "wait.dom",
+  "form.fill": "wait.dom",
+  submit: "wait.load",
+  "tab.switch": "wait.load",
+  "tab.new": "wait.load",
+  back: "wait.load",
+  forward: "wait.load",
+};
+
+function shouldAutoWait(cmd) {
+  return AUTO_WAIT_COMMANDS.some((candidate) => cmd === candidate || cmd.startsWith(`${candidate}.`));
+}
+
+function getAutoWaitCommand(cmd) {
+  if (AUTO_WAIT_MAP[cmd] !== undefined) return AUTO_WAIT_MAP[cmd];
+  for (const [prefix, waitCmd] of Object.entries(AUTO_WAIT_MAP)) {
+    if (cmd.startsWith(`${prefix}.`)) return waitCmd;
+  }
+  return null;
+}
+
+function resolveVar(template, vars) {
+  if (typeof template !== "string") return template;
+  const match = template.match(/^%\{(\w+)\}$/);
+  if (match) return vars[match[1]] !== undefined ? vars[match[1]] : template;
+  return template.replace(/%\{(\w+)\}/g, (_, name) => {
+    const value = vars[name];
+    if (value === undefined) return `%{${name}}`;
+    return typeof value === "object" ? JSON.stringify(value) : String(value);
+  });
+}
+
+function substituteVars(value, vars) {
+  if (!value || typeof value !== "object") return typeof value === "string" ? resolveVar(value, vars) : value;
+  if (Array.isArray(value)) return value.map((item) => substituteVars(item, vars));
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, substituteVars(item, vars)]));
+}
+
+function extractStepOutput(response) {
+  if (response?.result?.content?.[0]?.text) {
+    const text = response.result.content[0].text;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  if (response?.value !== undefined) return response.value;
+  if (response?.output !== undefined) {
+    try {
+      return JSON.parse(response.output);
+    } catch {
+      return response.output;
+    }
+  }
+  if (response?.result !== undefined) return response.result;
+  return response;
+}
+
+function abortMessage(signal) {
+  if (!signal?.aborted) return null;
+  return signal.reason instanceof Error ? signal.reason.message : String(signal.reason || "Workflow aborted");
+}
+
+function assertNotAborted(signal) {
+  const message = abortMessage(signal);
+  if (message) throw new Error(message);
+}
+
+async function executeSingleStep(step, vars, options) {
+  const {
+    autoWait = true,
+    executeTool,
+    includeInputValues = false,
+    onEvent = () => {},
+    signal,
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    stepDelay = 100,
+  } = options;
+  if (typeof executeTool !== "function") throw new Error("workflow runtime requires executeTool");
+  const args = substituteVars(step.args || {}, vars);
+  const startedAt = new Date().toISOString();
+  const baseEvent = { command: step.cmd, argsRedacted: redactCommandArgs(step.cmd, args, includeInputValues), startedAt };
+  onEvent({ type: "tool.started", ...baseEvent });
+  try {
+    assertNotAborted(signal);
+    const response = await executeTool(step.cmd, args, { signal });
+    assertNotAborted(signal);
+    if (response?.error) {
+      const error = response.error.content?.[0]?.text || (typeof response.error === "string" ? response.error : JSON.stringify(response.error));
+      onEvent({ type: "tool.failed", ...baseEvent, endedAt: new Date().toISOString(), resultSummary: error });
+      return { success: false, error };
+    }
+    if (step.as) vars[step.as] = extractStepOutput(response);
+    if (autoWait) {
+      const waitCmd = getAutoWaitCommand(step.cmd);
+      if (waitCmd) {
+        const waitArgs = waitCmd === "wait.load" ? { timeout: 10000 } : { stable: 100, timeout: 5000 };
+        try {
+          await executeTool(waitCmd, waitArgs, { signal });
+        } catch {}
+      }
+    }
+    if (stepDelay > 0) {
+      assertNotAborted(signal);
+      await sleep(stepDelay, signal);
+      assertNotAborted(signal);
+    }
+    onEvent({ type: "tool.completed", ...baseEvent, endedAt: new Date().toISOString(), resultSummary: "success" });
+    return { success: true, ...(step.as ? { output: vars[step.as] } : {}) };
+  } catch (error) {
+    const message = error?.message || String(error);
+    onEvent({ type: "tool.failed", ...baseEvent, endedAt: new Date().toISOString(), resultSummary: message });
+    return { success: false, error: message };
+  }
+}
+
+async function executeStep(step, vars, options) {
+  const { onError = "stop" } = options;
+  assertNotAborted(options.signal);
+  if (step.repeat !== undefined) {
+    let max = resolveVar(step.repeat, vars);
+    if (typeof max === "string") max = Number.parseInt(max, 10);
+    if (typeof max !== "number" || Number.isNaN(max)) max = 1;
+    max = Math.min(max, MAX_LOOP_ITERATIONS);
+    if (!Array.isArray(step.steps) || step.steps.length === 0) return { success: false, error: "repeat: steps array required", stepsExecuted: 0 };
+    let stepsExecuted = 0;
+    for (let index = 0; index < max; index++) {
+      const loopVars = { ...vars, _index: index, _iteration: index + 1 };
+      for (const nestedStep of step.steps) {
+        const result = await executeStep(nestedStep, loopVars, options);
+        stepsExecuted += result.stepsExecuted || 1;
+        if (!result.success && onError === "stop") return { success: false, error: result.error, stepsExecuted };
+      }
+      copyCapturedVars(step.steps, loopVars, vars);
+      if (step.until) {
+        const untilResult = await executeSingleStep(step.until, loopVars, options);
+        stepsExecuted++;
+        if (untilResult.output) break;
+      }
+    }
+    return { success: true, stepsExecuted };
+  }
+  if (step.each !== undefined) {
+    const items = resolveVar(step.each, vars);
+    if (!Array.isArray(items)) return { success: false, error: `each: expected array, got ${typeof items}${items === undefined ? " (undefined)" : ""}`, stepsExecuted: 0 };
+    if (!Array.isArray(step.steps) || step.steps.length === 0) return { success: false, error: "each: steps array required", stepsExecuted: 0 };
+    const itemVar = step.as || "item";
+    let stepsExecuted = 0;
+    for (let index = 0; index < Math.min(items.length, MAX_LOOP_ITERATIONS); index++) {
+      const loopVars = { ...vars, [itemVar]: items[index], _index: index, _iteration: index + 1 };
+      for (const nestedStep of step.steps) {
+        const result = await executeStep(nestedStep, loopVars, options);
+        stepsExecuted += result.stepsExecuted || 1;
+        if (!result.success && onError === "stop") return { success: false, error: result.error, stepsExecuted };
+      }
+      copyCapturedVars(step.steps, loopVars, vars);
+    }
+    return { success: true, stepsExecuted };
+  }
+  return { ...(await executeSingleStep(step, vars, options)), stepsExecuted: 1 };
+}
+
+function copyCapturedVars(steps, source, target) {
+  for (const step of steps) {
+    const isLoop = step.repeat !== undefined || step.each !== undefined;
+    if (!isLoop && step.as && source[step.as] !== undefined) target[step.as] = source[step.as];
+  }
+}
+
+async function executeWorkflow(steps, options = {}) {
+  const vars = { ...(options.vars || {}), ...(options.context?.vars || {}) };
+  const results = [];
+  let failed = 0;
+  let stepsExecuted = 0;
+  const startTotal = Date.now();
+  for (let index = 0; index < steps.length; index++) {
+    const step = steps[index];
+    const startTime = Date.now();
+    const type = step.repeat !== undefined || step.each !== undefined ? "loop" : "tool";
+    options.onProgress?.({ phase: "start", index, total: steps.length, step, type });
+    let result;
+    try {
+      result = await executeStep(step, vars, options);
+    } catch (error) {
+      result = { success: false, error: error?.message || String(error), stepsExecuted: 0 };
+    }
+    const ms = Date.now() - startTime;
+    stepsExecuted += type === "loop" ? result.stepsExecuted || 0 : 1;
+    if (!result.success) {
+      failed++;
+      results.push({ step: index + 1, ...(type === "loop" ? { type: "loop" } : { cmd: step.cmd }), status: "error", error: result.error, ms });
+      options.onProgress?.({ phase: "fail", index, total: steps.length, step, type, ms, error: result.error });
+      if ((options.onError || "stop") === "stop") {
+        return { status: "failed", completedSteps: type === "loop" ? stepsExecuted : stepsExecuted - 1, totalSteps: steps.length, results, error: result.error, totalMs: Date.now() - startTotal, vars };
+      }
+    } else {
+      results.push({ step: index + 1, ...(type === "loop" ? { type: "loop", stepsExecuted: result.stepsExecuted } : { cmd: step.cmd }), status: "ok", ms });
+      options.onProgress?.({ phase: "ok", index, total: steps.length, step, type, ms, stepsExecuted: result.stepsExecuted });
+    }
+  }
+  return { status: failed > 0 ? "partial" : "completed", completedSteps: stepsExecuted, totalSteps: steps.length, results, failed, totalMs: Date.now() - startTotal, vars };
+}
+
+module.exports = {
+  AUTO_WAIT_COMMANDS,
+  AUTO_WAIT_MAP,
+  MAX_LOOP_ITERATIONS,
+  executeSingleStep,
+  executeStep,
+  executeWorkflow,
+  extractStepOutput,
+  getAutoWaitCommand,
+  resolveVar,
+  shouldAutoWait,
+  substituteVars,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surf-cli",
-  "version": "2.8.0",
+  "version": "2.10.0",
   "description": "CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.",
   "keywords": [
     "chrome",
@@ -28,6 +28,7 @@
   },
   "files": [
     "native/",
+    "playbooks/",
     "scripts/",
     "dist/",
     "skills/",
@@ -43,6 +44,7 @@
     "lint:test": "biome check test/",
     "format": "biome format --write .",
     "test": "vitest run",
+    "test:e2e:chrome": "node test/e2e/real-chrome.mjs",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:ui": "vitest --ui",
@@ -56,16 +58,17 @@
     "crypto-browserify": "^3.12.1",
     "events": "^3.3.0",
     "stream-browserify": "^3.0.0",
-    "vite-plugin-node-polyfills": "^0.25.0",
+    "vite-plugin-node-polyfills": "^0.28.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.4",
-    "@types/chrome": "^0.1.37",
+    "@biomejs/biome": "^2.5.4",
+    "@types/chrome": "^0.2.2",
     "@vitest/coverage-v8": "^4.1.9",
     "@vitest/ui": "^4.1.9",
-    "typescript": "^6.0.3",
-    "vite": "^7.3.1",
+    "puppeteer": "25.3.0",
+    "typescript": "^7.0.2",
+    "vite": "^8.1.4",
     "vitest": "^4.1.9"
   }
 }

package/playbooks/page/ops/read.json

@@ -0,0 +1,22 @@
+{
+  "id": "read",
+  "description": "Read the current site's root document",
+  "effect": "read",
+  "run": [
+    {
+      "using": "network",
+      "request": { "method": "GET", "url": "/" },
+      "extract": { "field": "body" },
+      "expect": { "truthy": true }
+    },
+    {
+      "using": "workflow",
+      "steps": [
+        { "tool": "page.text", "args": {}, "as": "content" }
+      ],
+      "extract": { "jsonPath": "$.vars.content" },
+      "expect": { "truthy": true }
+    }
+  ],
+  "on": { "drift": { "fallback": "next", "report": true } }
+}

package/playbooks/page/playbook.json

@@ -0,0 +1,7 @@
+{
+  "id": "page",
+  "name": "Current page",
+  "version": "1.0.0",
+  "description": "Read the current browser page with a network fast path and UI fallback",
+  "origins": []
+}

package/scripts/install-native-host.cjs

@@ -3,6 +3,8 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 const { execFileSync, execSync } = require("child_process");
+const { parseListenEndpoint } = require("../native/listener.cjs");
+const { getStateDir, loadHostIdentity, loadRegistry } = require("../native/remote-auth.cjs");
 
 const HOST_NAME = "surf.browser.host";
 
@@ -164,7 +166,7 @@ function wslPathToWindowsPath(wslPath) {
   }
 }
 
-function createWrapper(wrapperDir, nodePath, hostPath, target = process.platform) {
+function createWrapper(wrapperDir, nodePath, hostPath, target = process.platform, listen) {
   fs.mkdirSync(wrapperDir, { recursive: true });
 
   if (target === "wsl-windows") {
@@ -186,13 +188,19 @@ function createWrapper(wrapperDir, nodePath, hostPath, target = process.platform
   const hostDir = path.dirname(hostPath);
   const content = `#!/usr/bin/env bash
 cd "${hostDir}"
-exec "${nodePath}" "${hostPath}" "$@"
+${listen ? `: "\${SURF_LISTEN:=${listen}}"\nexport SURF_LISTEN\n` : ""}exec "${nodePath}" "${hostPath}" "$@"
 `;
   fs.writeFileSync(shPath, content);
   fs.chmodSync(shPath, "755");
   return shPath;
 }
 
+function assertListenTargetSupported(listen, target) {
+  if (listen && (target === "win32" || target === "wsl-windows")) {
+    throw new Error("--listen is not supported for Windows native-host wrappers");
+  }
+}
+
 function readExistingManifest(manifestPath) {
   if (!fs.existsSync(manifestPath)) return {};
   return JSON.parse(fs.readFileSync(manifestPath, "utf8"));
@@ -268,7 +276,7 @@ function installWindowsRegistry(browser, extensionId, wrapperPath) {
 
 function parseArgs() {
   const args = process.argv.slice(2);
-  const result = { extensionId: null, browsers: ["chrome"], target: "auto" };
+  const result = { extensionId: null, browsers: ["chrome"], target: "auto", listen: undefined };
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -281,6 +289,9 @@ function parseArgs() {
       }
     } else if (arg === "--target") {
       result.target = args[++i];
+    } else if (arg === "--listen") {
+      result.listen = args[++i];
+      if (!result.listen || result.listen.startsWith("--")) throw new Error("--listen requires a Tailnet IP and port");
     } else if (arg === "--help" || arg === "-h") {
       printHelp();
       process.exit(0);
@@ -307,17 +318,24 @@ Options:
                   Multiple: --browser chrome,brave
   --target        Install target: auto, linux, windows
                   On WSL2, auto installs for Windows Chrome. Use linux for WSLg/Linux browsers.
+  --listen <tailscale-ip>:<port>
+                  Persist an authenticated Tailnet-only listener endpoint.
+                  Requires at least one surf remote authorize client first.
+                  Supports Tailscale IPv4 or IPv6 addresses; POSIX wrappers only.
 
 Examples:
   node install-native-host.cjs abcdefghijklmnopabcdefghijklmnop
   node install-native-host.cjs abcdefghijklmnop --browser brave
   node install-native-host.cjs abcdefghijklmnop --browser all
   node install-native-host.cjs abcdefghijklmnop --target linux
+  node install-native-host.cjs abcdefghijklmnop --listen 100.64.1.2:4321
 `);
 }
 
 function main() {
-  const { extensionId, browsers, target } = parseArgs();
+  let parsed;
+  try { parsed = parseArgs(); } catch (error) { console.error(`Error: ${error.message}`); process.exit(1); }
+  const { extensionId, browsers, target, listen } = parsed;
 
   if (!extensionId) {
     console.error("Error: Extension ID required");
@@ -331,6 +349,17 @@ function main() {
     console.error("Expected 32 lowercase letters (a-p)");
     process.exit(1);
   }
+  let listener;
+  try {
+    listener = listen ? parseListenEndpoint(listen).display : undefined;
+    if (listener) {
+      const stateDir = getStateDir();
+      loadHostIdentity(stateDir);
+      if (loadRegistry(stateDir).clients.length === 0) {
+        throw new Error("--listen requires at least one authorized remote client; run `surf remote authorize <label> --output <path>` first");
+      }
+    }
+  } catch (error) { console.error(`Error: ${error.message}`); process.exit(1); }
 
   if (!["auto", "linux", "windows"].includes(target)) {
     console.error("Error: Invalid --target value. Expected auto, linux, or windows");
@@ -349,6 +378,7 @@ function main() {
   }
 
   const effectiveTarget = runningInWsl && target !== "linux" ? "wsl-windows" : process.platform;
+  try { assertListenTargetSupported(listen, effectiveTarget); } catch (error) { console.error(`Error: ${error.message}`); process.exit(1); }
 
   const nodePath = findNode();
   if (!nodePath) {
@@ -377,7 +407,7 @@ function main() {
   console.log(`Wrapper dir: ${wrapperDir}`);
   console.log("");
 
-  const wrapperPath = createWrapper(wrapperDir, nodePath, hostPath, effectiveTarget);
+  const wrapperPath = createWrapper(wrapperDir, nodePath, hostPath, effectiveTarget, listener);
   console.log(`Created wrapper: ${wrapperPath}`);
   console.log("");
 
@@ -419,4 +449,5 @@ if (require.main === module) {
 module.exports = {
   createWrapper,
   writeManifest,
+  assertListenTargetSupported,
 };

package/skills/README.md

@@ -1,21 +1,27 @@
 # Surf Skills
 
-This directory contains skill files for AI coding agents.
+This directory contains skill files for AI coding agents:
+
+- **`surf/`** — the core browser-automation reference: every surf command, workflows, AI assistants, troubleshooting.
+- **`deep-x-research/`** — a research procedure built on surf: exhaustive, multi-angle X (Twitter) research with categorized findings and full post-URL traceability. Requires x.com login in Chrome.
+
+Install each skill folder the same way (symlink or copy).
 
 ## Pi Agent
 
-To use the surf skill with [Pi coding agent](https://github.com/badlogic/pi-mono):
+To use a skill with [Pi coding agent](https://github.com/badlogic/pi-mono):
 
 ```bash
 # Option 1: Symlink (auto-updates)
 ln -s "$(pwd)/skills/surf" ~/.agents/skills/surf
+ln -s "$(pwd)/skills/deep-x-research" ~/.agents/skills/deep-x-research
 
 # Option 2: Copy
-cp -r skills/surf ~/.agents/skills/
+cp -r skills/surf skills/deep-x-research ~/.agents/skills/
 ```
 
-The skill will be available when pi detects browser automation tasks.
+The skills will be available when pi detects browser automation or X research tasks.
 
 ## Other Agents
 
-The `SKILL.md` file is a comprehensive reference that can be adapted for other AI coding agents or used as documentation for LLM prompts.
+Each `SKILL.md` file can be adapted for other AI coding agents (Claude Code, Codex) or used as documentation for LLM prompts — copy the skill folder into the agent's skills directory (e.g. `~/.claude/skills/`, `~/.agents/skills/`).

package/skills/deep-x-research/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: deep-x-research
+description: Deep, exhaustive research on a topic across X (Twitter) by driving Grok (x.com/i/grok) through surf. Use when the user wants comprehensive X research on a concept, technique, trend, tool, or creator scene; needs categorized findings with every claim traceable to post URLs; or when a single Grok query is not enough.
+---
+
+# Deep X Research
+
+Research a topic across X by putting Grok to work from multiple angles — it runs keyword and semantic X searches and watches videos natively — then deliver categorized findings where every claim is traceable to a post URL.
+
+Requires: surf installed and connected (`surf doctor`), Chrome logged into x.com. Command reference: the `surf` skill or `surf --help`.
+
+**Quota:** X caps Grok requests (typically 15 per 20 hours on a standard plan). Every `surf grok` call spends one. Budget the session before the first query and make each query do multi-angle work — never spend a request on what a quota-free step can answer.
+
+## Steps
+
+### 1. Decompose the topic and budget the queries
+
+Break the topic into angles: showcases/examples, techniques & tutorials, tools, notable creators, community discussion — adapt to the topic. Plan a Grok budget of **4-8 queries** covering every angle (combine related angles into one query rather than spending two). Done when each angle is assigned to a budgeted query.
+
+### 2. Grok sweep
+
+Run the budgeted queries sequentially. Engineer each so Grok does the fan-out internally and returns traceable sources:
+
+```bash
+# Broad pass — force multi-angle search and URLs
+surf grok "Do deep research on TOPIC on X. Search both latest and top posts, keyword and semantic. Return the most relevant posts with full post URLs (x.com/user/status/ID) and a one-line description of each."
+
+# Focused passes — one per remaining angle group
+surf grok "TOPIC on X: tutorials, techniques, and the tools people use. Include post URLs for every example."
+
+# Deepest pass — spend DeepSearch on the highest-value angle
+surf grok "TOPIC: notable creators, how the trend is evolving, and the standout posts of the last 6 months. Post URLs required." --deep-search
+```
+
+Record every post Grok cites: author, one-line gist, full `https://x.com/USER/status/ID` URL. If a response gives claims without URLs, the *next* query in the budget re-asks for sources — never leave an angle sourceless. Done when every planned angle has been queried and the final response adds no new relevant posts, or the budget is spent.
+
+### 3. Video pass (visual topics)
+
+When the topic involves video, editing, or visual style, spend 1-3 budgeted queries having Grok analyze the strongest video posts — it can watch X videos natively:
+
+```bash
+surf grok "Analyze the videos in these posts: URL1 URL2 URL3 — for each, describe the techniques, pacing, and style, and why it works."
+```
+
+Batch several URLs per query to conserve budget. Done when each analyzed video has notes on what it shows and why it matters for the topic.
+
+### 4. Enrich and verify — quota-free
+
+For each cited post, open it directly with surf (no Grok spend) to verify the URL resolves and harvest detail Grok didn't give:
+
+```bash
+surf navigate "https://x.com/USER/status/ID" && surf wait 2
+surf page.read --compact          # engagement numbers, thread context
+surf network | grep video.twimg   # direct video URL after playback
+```
+
+Done when every URL destined for the References section has been resolved (dead or hallucinated links dropped or replaced).
+
+### 5. Categorize and analyze
+
+Group findings into categories that fit the topic. Extract trends: momentum on X, recurring techniques, notable creators, how the topic is evolving. Done when every recorded post is either placed in a category or deliberately dropped as irrelevant.
+
+### 6. Report with full traceability
+
+```md
+# Deep Research on [Topic]
+
+## Summary
+[2-4 paragraphs: state of the topic on X]
+
+## Key Trends
+- ...
+
+## Categorized Findings
+### [Category]
+- [Finding with inline post reference]
+
+## Notable Creators & Techniques
+- ...
+
+## References
+1. [Author — one-line description]
+   https://x.com/USER/status/ID
+   Video: https://video.twimg.com/... (when captured)
+```
+
+The report is done when **every post mentioned anywhere in it appears in References with its full, verified URL** — no bare @handles, no "a viral post showed…" without a link.
+
+## Fallback: direct search when the Grok quota is exhausted
+
+The x.com search UI costs no Grok requests. Slower and keyword-only, but it keeps the sweep going:
+
+```bash
+surf navigate "https://x.com/search?q=QUERY&f=live" && surf wait 3   # Latest
+surf page.read --compact
+surf scroll down 2000    # then page.read again — repeat to load more
+```
+
+Modes via the `f=` param: **Top is the default (no `f` param)** — there is no `f=top`; `f=live` = Latest, `f=user` = People, `f=media` = Media. Operators compose into the URL-encoded `q=`: `"exact phrase"`, `filter:videos`, `min_faves:100`, `min_retweets:50`, `from:user`, `since:2026-01-01`, `until:2026-06-01`.
+
+## Troubleshooting
+
+- Grok replies with a rate-limit message → quota exhausted; switch to the fallback sweep and tell the user when the quota resets.
+- Grok queries fail outright → `surf grok --validate`, then retry with a model from the validation output (see the `surf` skill's AI troubleshooting section).
+- Grok cites posts without URLs → re-ask in the next budgeted query; do not invent URLs.
+- Search page shows a login wall → Chrome isn't logged into x.com; ask the user to log in.