From d07ee968851a3eec1c0a1248747b40ed166866af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?C=C3=A9line=20Debled?= <celine@lightpanda.io>
Date: Fri, 2 Oct 2026 07:12:48 +0000
Subject: [PATCH] Document the new agent flags and stdin scripts for run and
 agent

---
 src/content/reference/cli/agent.mdx | 18 ++++++++++++++----
 src/content/reference/cli/index.mdx | 12 ++++++++----
 src/content/usage/agent.mdx         |  5 +++--
 3 files changed, 25 insertions(+), 10 deletions(-)

diff --git a/src/content/reference/cli/agent.mdx b/src/content/reference/cli/agent.mdx
index 50ba313..1f6a2bd 100644
--- a/src/content/reference/cli/agent.mdx
+++ b/src/content/reference/cli/agent.mdx
@@ -14,10 +14,10 @@ usage: lightpanda agent [SCRIPT] [OPTIONS] [COMMON_OPTIONS]
 
 Arguments:
 [SCRIPT]
-          Optional path to a .js script. Runs the script (no LLM calls) and
-          exits; `lightpanda run SCRIPT` is the preferred spelling. With no
-          script and no --task, the REPL starts; from there /load runs a
-          script and /save exports the session to a file.
+          Optional path to a .js script, or `-` for stdin. Runs the script
+          (no LLM calls) and exits; `lightpanda run SCRIPT` is the preferred
+          spelling. With no script and no --task, the REPL starts; from
+          there /load runs a script and /save exports the session to a file.
           Caution: .js files can contain evaluate(...) calls that run
           arbitrary JavaScript in the page. Only run scripts you trust, the
           same way you would a shell script.
@@ -91,12 +91,22 @@ Options:
           it to PATH, instead of printing the answer. Replay it later with
           `run PATH` (no LLM calls). Overwrites PATH if it exists.
           Requires --task.
+  --search-engine <ENGINE>
+          Which web search API the `search` tool uses. Default: auto,
+          which takes the first with a key in the environment, in the
+          order brave, tavily, exa, keenable. `keenable` also works with
+          no key at all, through a rate-limited public endpoint.
+          Allowed values: auto, brave, tavily, exa, keenable.
   --system-prompt <STRING>
           Override the default system prompt.
   --task <STRING>
           One-shot mode: run a single user turn, print the final answer
           to stdout, and exit. Conflicts with the positional script. With
           --save, the answer is suppressed and a script is written instead.
+  --url <URL>
+          Open this page before the first turn. With --task it saves the
+          model a turn spent navigating; with --save the opening
+          navigation is the first line of the script.
   --verbosity <LEVEL>
           Stderr chatter level. Default: high when --task captures stderr
           to a pipe or file; low otherwise. low/medium also raise
diff --git a/src/content/reference/cli/index.mdx b/src/content/reference/cli/index.mdx
index 02dce09..c24ad8b 100644
--- a/src/content/reference/cli/index.mdx
+++ b/src/content/reference/cli/index.mdx
@@ -29,7 +29,7 @@ Every command also accepts a shared set of [common options](/reference/cli/commo
 
 ## help
 
-Show the command list above, or `lightpanda help <command>` for one command's own reference.
+Show the command list above, or `lightpanda help <command>` for one command's own reference. `--help` and `-h` work too, at the top level or after any command.
 
 ```sh copy
 lightpanda help [command]
@@ -44,13 +44,17 @@ lightpanda run script.js
 ```
 
 ```console
-usage: lightpanda run <SCRIPT> [COMMON_OPTIONS]
+usage: lightpanda run <SCRIPT | -> [COMMON_OPTIONS]
+
+Examples:
+  lightpanda run script.js                        (replay a saved script)
+  cat script.js | lightpanda run -                (read the script from stdin)
 
 Arguments:
 <SCRIPT>
           Path to a .js script to run, then exit. Produce one with
-          `lightpanda agent --task "..." --save script.js`, or `/save` from
-          the agent REPL.
+          `lightpanda agent --task "..." --save script.js`, or `/save` from the
+          agent REPL. Pass `-` to read the script from stdin instead.
           Caution: .js files can contain evaluate(...) calls that run
           arbitrary JavaScript in the page. Only run scripts you trust, the
           same way you would a shell script.
diff --git a/src/content/usage/agent.mdx b/src/content/usage/agent.mdx
index 5996877..9a3b1f5 100644
--- a/src/content/usage/agent.mdx
+++ b/src/content/usage/agent.mdx
@@ -123,8 +123,9 @@ than a V8 stack trace.
 
 ### Web search
 
-`/searchEngine <engine>` sets the backend the agent's web search runs
-against: `auto` (the default), `brave`, `tavily`, `exa`, or `keenable`.
+Set the backend the agent's web search runs against with the CLI option
+`--search-engine` or the REPL command `/searchEngine`: `auto` (the default),
+`brave`, `tavily`, `exa`, or `keenable`.
 The choice is saved per-directory in `.lp-agent.zon`.
 
 An API key is optional. `auto` falls back to Keenable's keyless public