From 67bd16f8fa614efc1cc35da66ce24d281d28efe3 Mon Sep 17 00:00:00 2001
From: Francis Bouvier <francis.bouvier@gmail.com>
Date: Tue, 16 Jun 2026 00:25:23 +0200
Subject: [PATCH 01/14] Add agent doc

---
 src/content/index.mdx             |   1 +
 src/content/usage/_meta.ts        |   2 +
 src/content/usage/agent.mdx       | 274 +++++++++++++++++++++
 src/content/usage/pandascript.mdx | 388 ++++++++++++++++++++++++++++++
 4 files changed, 665 insertions(+)
 create mode 100644 src/content/usage/agent.mdx
 create mode 100644 src/content/usage/pandascript.mdx

diff --git a/src/content/index.mdx b/src/content/index.mdx
index 1fb60d5..b500c90 100644
--- a/src/content/index.mdx
+++ b/src/content/index.mdx
@@ -9,6 +9,7 @@ Made for headless usage:
     - Javascript execution
     - Support of Web APIs
     - Compatible with [Playwright](https://playwright.dev/), [Puppeteer](https://pptr.dev/) through CDP
+    - Built-in automation: [agent](/usage/agent) with natural language and reproducible [script](/usage/pandascript)
 
 Fast web automation for AI agents, LLM training, scraping and testing:
     - Ultra-low memory footprint (16x less than Chrome)
diff --git a/src/content/usage/_meta.ts b/src/content/usage/_meta.ts
index 16c358f..e716f88 100644
--- a/src/content/usage/_meta.ts
+++ b/src/content/usage/_meta.ts
@@ -7,6 +7,8 @@ const meta: MetaRecord = {
       collapsed: false,
     },
   },
+  agent: 'Agent',
+  pandascript: 'PandaScript',
   mcp: 'MCP',
   api: 'HTTP API',
 }
diff --git a/src/content/usage/agent.mdx b/src/content/usage/agent.mdx
new file mode 100644
index 0000000..1404cae
--- /dev/null
+++ b/src/content/usage/agent.mdx
@@ -0,0 +1,274 @@
+---
+title: Agent
+description: Lightpanda agent lets you drive a headless browser by talking to it.
+---
+import { Callout, Tabs } from 'nextra/components'
+
+# Agent
+
+`lightpanda agent` lets you drive a headless browser by talking to it.
+
+You tell it where to go and what to extract, in plain English or with slash
+commands, and it controls a real browser to do the work. Think of it as a
+robot you're directing to use the web, more than a chatbot you're having a
+conversation with.
+
+Every session starts by navigating to a page, either by
+saying so ("go to this website") or by typing `/goto <url>`. There's
+no window to look at; the browser runs headlessly and you see its output
+(extracted data, the agent's answer) in your terminal.
+
+The agent stacks three layers:
+
+1. **The browser** Loads webpages, runs JavaScript and handles the DOM.
+   It's the same engine that powers Lightpanda CDP server.
+2. **The runtime** A small set of native tools that let's you drive the browser:
+   `goto`, `click`, `fill`, `extract`, `evaluate`, `search`, and more.
+   Each is available as a slash command (`/goto`, `/click`, ...).
+3. **An LLM** Reads your natural language request and decides which tools to
+   call. Optional, the agent can also run without it.
+
+## Quick start
+
+Set an API key for your preferred LLM provider:
+
+```sh copy
+export ANTHROPIC_API_KEY=<YOUR_ANTHROPIC_KEY>
+```
+
+Or `OPENAI_API_KEY`, `GOOGLE_API_KEY`, or a local LLM through an Ollama server.
+
+Launch the REPL:
+
+```sh copy
+lightpanda agent
+```
+
+Tell it what you want:
+
+```sh copy
+❯ go to news.ycombinator.com and get me the top story title and points
+```
+
+The agent navigates, extracts, prints the answer.
+
+You can also use slash commands:
+
+```sh copy
+❯ /goto news.ycombinator.com
+❯ /links # This will print all the HTML links on the current webpage
+```
+
+You can generate a reproducible PandaScript from your current session:
+
+```sh copy
+❯ /save <my_script>.js
+```
+
+Then after exiting you can replay the script directly with Lightpanda (no LLM needed) with:
+
+```sh copy
+lightpanda agent <my_script>.js
+```
+
+See our documentation on [PandaScript](/usage/pandascript) for more details.
+
+## LLM
+
+### Providers and API keys
+
+The agent needs an LLM to interpret natural language. Set the relevant API
+key as an environment variable, or pass `--provider` explicitly, or set `/provider`
+while on the REPL.
+
+| Provider  | Flag                   | API key env                          |
+|-----------|------------------------|--------------------------------------|
+| Anthropic | `--provider anthropic` | `ANTHROPIC_API_KEY`                  |
+| OpenAI    | `--provider openai`    | `OPENAI_API_KEY`                     |
+| Gemini    | `--provider gemini`    | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
+| Ollama    | `--provider ollama`    | none (local)                         |
+
+You can set explicitly the provider with the CLI option `--provider` or the REPL command `/provider`.
+Otherwise the agent will pick one on this order:
+
+1. **Remembered** - whatever you last selected with `/provider`,
+   persisted per-directory in `.lp-agent.zon`, as long as its key is still
+   set.
+2. **Auto-detected** - the first key found in priority order
+   (`ANTHROPIC_API_KEY` → `GOOGLE_API_KEY`/`GEMINI_API_KEY` →
+   `OPENAI_API_KEY`). With several keys on the REPL, you'll be prompted to
+   pick.
+3. **Local** - if no cloud key is set, the agent probes
+   `http://localhost:11434/v1` (Ollama default server endpoint)
+   and uses it if there's at least one model pulled.
+   You can change the server URL with the `--base-url` CLI option.
+4. **No provider at all** - If the CLI option `--no-llm` is set
+   it falls back to the basic REPL (slash commands only).
+   Natural language and LLM-driven commands (`/login`, `/logout`) will not work.
+
+### Models
+
+You can set explicitly a model with the CLI option `/model` or the REPL command `/model`.
+Otherwise the agent will pick either the last one persisted per-directory in `.lp-agent.zon`
+or a sensible per-provider default.
+
+The CLI option `--list-models` or pressing TAB on the REPL command `/model` prints the list of available models.
+
+The CLI option `--effot <none|minimal|low|medium|high|xhigh>` or the REPL command `/effort`
+sets the per-turn reasoning budget for thinking models.
+It maps to each provider's native reasoning-effort knob and is ignored by non-thinking models.
+The REPL defaults to `low` so turns stay snappy.
+`--task` defaults to `medium` where answer quality matters more than per-turn latency.
+Higher effort can mean fewer tool calls per task (the model plans better),
+so it's a real tradeoff rather than a pure slowdown
+Effort selection persists in `.lp-agent.zon`.
+
+The CLI option `--system-prompt` swaps in your own system prompt.
+
+## Slash commands
+
+The REPL uses a small slash-command language for browser actions. Each line
+you type at the prompt is either a slash command, a `#` comment, a blank
+line, or (when an LLM is configured) a natural-language prompt.
+
+`/help` list all available slash commands, `/help <command>` for details.
+
+Slash commands accept:
+
+- A single positional value, when the tool has exactly one required field.
+  `/goto 'https://example.com'`. The value can itself be quoted JSON when
+  that's what the field takes: `/extract '{"karma":"#karma"}'` passes the
+  string to extract's one required field, `schema`.
+- `key=value` pairs. Values may be bare or quoted; strings with whitespace
+  must be quoted. `/fill selector='#email' value='user@x.com'`. A positional
+  and `key=value` pairs can be mixed, but the positional must come first:
+  `/extract '{"karma":"#karma"}' save=me`.
+- A raw `{json}` blob, handed straight to the tool.
+  `/findElement {"role":"button"}`.
+
+Tools whose selector is optional (`/click`, `/hover`, `/findElement`) take
+no positional and must use `key=value` form: `/click selector='a.login'`.
+
+Quoting is content-aware: `'…'`, `"…"`, and triple-quoted `'''…'''` /
+`"""…"""` for values that mix quote styles or span multiple lines. Paste a
+multi-line command and the REPL keeps the whole paste as one input; typed
+line by line, Enter submits at each newline.
+
+### Extracting data 
+
+`/extract` takes a JSON schema where each value tells the extractor what to
+lift off the page. The result is printed to stdout as a single JSON object.
+
+Supported value forms:
+
+- `"<sel>"`: `textContent.trim()` of the first match.
+- `""`: the matched element's own text (only inside a `fields` block).
+- `["<sel>"]`: text of every match. Sugar for `[{"selector": "<sel>"}]`.
+- `{"selector": "<sel>", "attr": "<name>"}`: attribute of the first match.
+- `[{"selector": "<sel>", "fields": {…}}]`: array of records, each
+  `fields` value resolved relative to the matched element.
+
+A selector that matches nothing yields a null or empty field, not an error.
+That's deliberate, but it means a stale selector fails quietly. If a run
+comes back with blanks where you expected data, suspect the selectors or a
+missing wait before you suspect the page.
+
+The schema is parsed in Zig before the page-side walker runs, so malformed
+schemas are rejected up front with a plain `Error: InvalidParams` rather
+than a V8 stack trace.
+
+### Meta commands
+
+These don't drive the browser, they control the REPL itself:
+
+| Command                  | What it does                                       |
+|--------------------------|----------------------------------------------------|
+| `/help`                  | Lists tools. `/help <tool>` prints the JSON schema.|
+| `/provider [name]`       | Lists or switches provider.                        |
+| `/model [name]`          | Lists or switches model for the active provider.   |
+| `/effort <level>`        | Sets reasoning budget. Saved to `.lp-agent.zon`.   |
+| `/verbosity <level>`     | Tunes the log level. Levels: low, medium, high.    |
+| `/usage`                 | Prints cumulative token usage and cache hit rate.  |
+| `/save [file] [prompt]`  | Writes the session to a script. `.js` is appended to the name if missing; trailing words guide the synthesizer.|
+| `/load <path>`           | Runs a script from disk against the current session.|
+| `/clear`                 | Forgets the conversation (history, usage, recorded actions, node IDs); keeps the page and cookies.|
+| `/reset`                 | Full reset: everything `/clear` does, plus a fresh browser session, dropping the page, cookies, and storage.|
+| `/quit`                  | Exits the REPL.                                    |
+
+Meta commands are never recorded.
+
+Use `/clear` when you want to test a new prompt against the current
+page without losing your login or cookies. Use `/reset` when you need
+a completely clean browser (no cookies, no current page, no storage).
+
+### LLM-driven commands
+
+Three slash commands trigger an LLM turn rather than a direct tool call:
+
+| Command          | What it does                                          |
+|------------------|-------------------------------------------------------|
+| `/login`         | Fills credentials from `$LP_*` env vars.              |
+| `/logout`        | Finds the logout control and signs out.               |
+| `/acceptCookies` | Dismisses the consent banner.                         |
+
+All three require an LLM. `--no-llm` rejects them.
+
+## REPL features
+
+- **Ghost hints.** There's no separate status line; guidance renders as dim
+  ghost text after the cursor and disappears as you type over it. It
+  previews the rest of the first matching command name, the argument shape
+  of the tool you're typing (`/evaluate ` shows
+  `<script> [url=…] [timeout=…] [save=…]`), and contextual nudges like
+  "press Ctrl-D again to exit".
+- **JS mode (`!`).** Type `!` on an empty prompt to toggle a scratchpad
+  where the whole line runs as page-side JavaScript, same context as
+  `/evaluate` so `document` and `window` are in scope. The prompt switches
+  to `!` with a "JS mode - esc to exit" ghost hint. Handy for poking at
+  a page without wrapping every line in `/evaluate`:
+
+  ```
+  ❯ !
+  ! document.title
+  "Hacker News"
+  ! document.querySelectorAll('tr.athing').length
+  30
+  ```
+
+  `$LP_*` refs are still resolved at execution, console output is echoed
+  back, and `Esc` exits. JS-mode lines are not recorded.
+- **Tab completion** (case-insensitive). Cycles through `/<tool>` and meta
+  slash commands. The dim grey suffix shown after the cursor is the first
+  match.
+- **Persistent history.** Stored in `.lp-history` in the working directory.
+- **Stdout vs stderr.** The final assistant answer and data-producing slash
+  commands (`/extract`, `/evaluate`, `/markdown`, `/tree`, ...) write to
+  stdout. Tool calls, progress, and errors go to stderr. So
+  `lightpanda agent --task ... > out.txt` captures a clean answer.
+
+## One-shot mode (`--task`)
+
+```console
+./lightpanda agent --provider gemini \
+  --task "what is the top story on news.ycombinator.com?"
+```
+
+`--task` runs a single user turn, prints the final answer to stdout, and
+exits. On a TTY a spinner on stderr shows the tool currently running while
+the agent works; raise `--verbosity` for the full `[tool/result]` trace.
+
+Combine with `-a <path>` / `--attach <path>` (repeatable) to feed
+local files to providers that accept attachments — for example, a list of
+items to look up, or a document to cross-check against a live page:
+
+```console
+./lightpanda agent -a invoice.pdf \
+  --task "open shop.example.com/orders/1042 and check the order total matches the attached invoice"
+```
+
+Text files are inlined
+into the prompt (max 512 KiB each); binary files (image, audio, pdf) are
+base64-encoded inline (max 20 MiB each). Unsupported MIME types fail before
+any browser work runs.
+
+`--task` conflicts with the positional script argument.
diff --git a/src/content/usage/pandascript.mdx b/src/content/usage/pandascript.mdx
new file mode 100644
index 0000000..8b2d40c
--- /dev/null
+++ b/src/content/usage/pandascript.mdx
@@ -0,0 +1,388 @@
+---
+title: PandaScript
+description: Built-in automation script for Lightpanda
+---
+import { Callout, Tabs } from 'nextra/components'
+
+# PandaScript
+
+A PandaScript is a web automation script that can be run directly by Lightpanda binary.
+
+No environment to setup like NodeJS or Python, no Puppeteer/Playwright to write, no CDP serialization cost, no LLM required: just vanilla Javascript with a small set of native primitives.
+
+Use normal Javascript variables, functions, loops, objects, arrays, `JSON.parse`, `JSON.stringify`, and other standard ECMAScript built-ins.
+
+It's reproducible, deterministic and token-free (no LLM required).
+
+To run a PandaScript:
+
+```sh copy
+lightpanda agent <my_script>.js
+```
+
+## Runtime Environment
+
+Agent scripts run in their own V8 context. That context is separate from the
+web page's JavaScript context.
+
+- It is not the browser page environment. There is no `window`, `document`,
+  DOM, `localStorage`, `navigator`, or page global state in the agent script.
+  Read page data with `extract(...)`, or explicitly run page JavaScript with
+  `evaluate(...)` when that is the right tool.
+- It is not Node.js. There is no `require`, `process`, `fs`, `path`, npm
+  package loading, command-line argument API, or Node network/filesystem API.
+- Page scripts cannot see agent variables or Lightpanda primitives. Agent
+  scripts cannot directly see page variables.
+- The global `evaluate(...)` primitive runs JavaScript in the page context,
+  distinct from the agent context's own native `eval`.
+- Agent variables persist for the lifetime of one script run, across
+  navigations and primitive calls. A later `lightpanda agent script.js` run
+  starts with a fresh agent context.
+- The installed primitives are synchronous and blocking. Do not write an
+  `async`/`await` automation contract around them. Scripts compile as classic
+  scripts, so top-level `await` is a `SyntaxError`; promise callbacks
+  (`.then`) only run after the script body finishes, never in between
+  primitive calls.
+- Tool failures throw JavaScript `Error` exceptions and stop execution unless
+  you catch them.
+- The script's completion value — its last top-level expression — is printed
+  automatically (objects and arrays as JSON; other values coerced). End a
+  script with the bare expression you want as output, e.g. a final
+  `extract({ ... });` or `results;`. `console.log(...)` is for extra or debug
+  output and does not JSON-format objects.
+
+The agent context includes a small `console` object:
+
+```js
+console.log("printed to stdout");
+console.info("printed to stdout");
+console.debug("printed to stdout");
+console.warn("printed to stderr");
+console.error("printed to stderr");
+```
+
+## Values And Return Types
+
+Most primitives return the browser tool's result text as a JavaScript string.
+`extract(...)` is the exception: it returns extracted data as a normal
+JavaScript value, so local script logic can use it directly. The result mirrors
+your schema — an object schema returns an object keyed by your fields (even with
+a single field), and a bare array schema returns an array:
+
+```js
+goto("https://news.ycombinator.com/");
+
+const data = extract({
+  title: "title",
+  stories: [{
+    selector: "tr.athing",
+    limit: 5,
+    fields: {
+      id: { attr: "id" },
+      title: ".titleline > a"
+    }
+  }]
+});
+
+data; // printed automatically as JSON
+```
+
+Destructure when a single field is all you need:
+
+```js
+const { stories } = extract({
+  stories: [{
+    selector: "tr.athing",
+    limit: 5,
+    fields: {
+      id: { attr: "id" },
+      title: ".titleline > a"
+    }
+  }]
+});
+
+for (const story of stories) {
+  console.log(story.title);
+}
+```
+
+`evaluate(...)` still returns the page evaluate tool result text. When page `evaluate(...)`
+returns an object or array, that text is JSON.
+
+Primitive arguments must be JSON-serializable. Strings, numbers, booleans,
+arrays, plain objects, and `null` work. `undefined`, functions, symbols, and
+cyclic objects do not.
+
+## Installed Primitives
+
+Only recorded browser primitives are installed globally:
+
+| Primitive | Arguments | Runs in |
+|-----------|-----------|---------|
+| `goto` | `goto(url[, { timeout }])` | Browser session |
+| `extract` | `extract(schema)` or `extract({ schema })` | Browser page via extractor; returns a JS object or array |
+| `evaluate` | `evaluate(script[, { url, timeout, save }])` | Browser page JS context |
+| `click` | `click(selector)` or `click({ selector })` | Browser page |
+| `fill` | `fill(selector, value)` or `fill({ selector, value })` | Browser page |
+| `scroll` | `scroll()` or `scroll({ x, y })` | Browser page |
+| `waitForSelector` | `waitForSelector(selector[, { timeout }])` | Browser page |
+| `waitForScript` | `waitForScript(script[, { timeout }])` | Browser page JS context |
+| `waitForState` | `waitForState(state[, { timeout }])` | Browser page |
+| `hover` | `hover(selector)` or `hover({ selector })` | Browser page |
+| `press` | `press(selector, key)` or `press({ key[, selector] })` | Browser page |
+| `selectOption` | `selectOption(selector, value)` or `selectOption({ selector, value })` | Browser page |
+| `setChecked` | `setChecked(selector[, checked])` or `setChecked({ selector, checked })` | Browser page |
+
+`goto` returns at the `load` event (a fast snapshot). When a page's content is
+still loading (rendered by post-load JS), call `waitForState("networkidle")`
+before reading. `waitForState`'s `state` accepts `"load"`,
+`"domcontentloaded"`, `"networkalmostidle"`, `"networkidle"`, or `"done"`.
+`goto`'s `timeout` defaults to 10000 ms; the `waitFor*` timeouts default to
+5000 ms.
+
+The `[, { … }]` is an optional trailing options object: leading arguments are
+positional (`waitForSelector("#row", { timeout: 2000 })`), and the options ride
+in a final object. Passing a single object with everything
+(`waitForSelector({ selector: "#row", timeout: 2000 })`) is equivalent — that's
+the shape `/save` records into saved scripts. An option can't be a bare
+positional, though: `waitForSelector("#row", 2000)` is an error. A `null`
+positional omits that field (`press(null, "Enter")` presses on the focused
+element), and setting the same field positionally and in the options object
+(`goto(url, { url: ... })`) is an `invalid arguments` error.
+
+Script primitives address elements by CSS selector only. The tools that hand
+out `backendNodeId`s (`tree`, `findElement`, `nodeDetails`) aren't installed in
+the script context, and a raw node ID wouldn't survive replay anyway. When
+you're exploring in the REPL and have a `backendNodeId` — e.g. the leading
+number on a `/tree` line, or a `/findElement` hit — run `/nodeDetails
+backendNodeId=<id>` to get a durable CSS `selector`, then paste that into your
+script.
+
+## Navigation
+
+Use `goto(...)` to open a page:
+
+```js
+goto("https://example.com");
+
+goto({
+  url: "https://example.com/app",
+  timeout: 15000
+});
+```
+
+The call returns a status string and throws if navigation fails. A timeout
+does **not** throw: the call returns `"Navigation started but the page did not
+finish loading before the timeout."` and the page stays in whatever state it
+reached. Check the return value — or follow with `waitForState(...)` /
+`waitForSelector(...)` — when completeness matters.
+
+## Structured Extraction
+
+Use `extract(...)` to read data from the current page without writing page-side
+JavaScript. This is the preferred bridge from page content into local agent
+logic.
+
+```js
+const result = extract({
+  heading: "h1",
+  links: [{
+    selector: "a",
+    limit: 10,
+    fields: {
+      text: "",
+      href: { attr: "href" }
+    }
+  }]
+});
+```
+
+The schema forms are:
+
+| Schema value | Meaning |
+|--------------|---------|
+| `"<selector>"` | Text of the first matching element, or `null` |
+| `""` | Text of the current matched element inside a `fields` block |
+| `["<selector>"]` | Text of all matching elements |
+| `{ selector: "<selector>", attr: "<name>" }` | Attribute from the first match |
+| `[{ selector: "<selector>", attr: "<name>" }]` | Attribute from all matches |
+| `[{ selector: "<selector>", fields: { ... } }]` | Array of records, with fields resolved relative to each matched element |
+| `limit: N` | Cap array extraction to `N` matches |
+
+Return shape follows the top-level schema:
+
+- `extract({ title: "h1" })` returns `{ title: "..." }`.
+- `extract({ title: "h1", links: [{ selector: "a" }] })` returns an object
+  with both fields.
+- `extract({ links: [{ selector: "a" }] })` returns `{ links: [...] }` — an
+  object schema always returns an object, even with a single field.
+- `extract([{ selector: "a" }])` is shorthand for a single anonymous array
+  extraction and returns the array directly.
+
+Every value is a string (trimmed text or a raw attribute) or `null` — parse
+numbers in script logic. An array field that matches nothing yields `[]`
+without complaint (a page with zero comments is a valid result), but if
+*every* field in the schema misses, `extract(...)` throws
+`no schema selector matched any element` — treat that as "my selectors are
+wrong", not "the page is empty".
+
+`extract(...)` reads only the current page. For list-to-detail scraping —
+capture a list, then visit each row for more — capture the list, then loop in
+the script: `goto` each row's URL and `extract` the detail. The local agent
+context keeps the data across navigations, so the assembly happens in plain
+JavaScript. See the [complete example](#complete-example) below.
+
+When passing an object directly to `extract(...)`, the runtime serializes it as
+the extractor schema. These forms are equivalent:
+
+```js
+extract({ title: "h1" });
+extract({ schema: { title: "h1" } });
+extract('{ "title": "h1" }');
+```
+
+The wrapped form accepts only `schema`: the REPL's `save=` option does not
+exist in scripts (`extract({ schema: ..., save: ... })` is rejected). Keep
+results in local variables instead.
+
+Use local variables to keep extracted data available to later script logic:
+
+```js
+const page = extract({ title: "title" });
+```
+
+## Page JavaScript
+
+`evaluate(...)` is the explicit escape hatch into the current page's JavaScript
+context. Its script string runs where `window` and `document` exist.
+
+```js
+goto("https://example.com");
+
+const title = evaluate("document.title");
+console.log(title);
+```
+
+Keep the boundary clear:
+
+```js
+const selector = "h1";
+
+// Good: local agent logic builds an extract schema.
+const data = extract({ heading: selector });
+
+// Bad: page evaluate cannot see local agent variables.
+evaluate("document.querySelector(selector).textContent");
+```
+
+Page `evaluate(...)` cannot call `goto`, `extract`, or other agent primitives.
+Agent scripts cannot access `document` directly. If you need page DOM data,
+prefer `extract(...)`; use `evaluate(...)` only for page behavior that extraction
+cannot express.
+
+`waitForScript(...)` also evaluates in the page context, repeatedly, until the
+expression is truthy or the timeout expires:
+
+```js
+waitForScript("document.querySelectorAll('.row').length >= 5");
+```
+
+## Interaction Primitives
+
+The action primitives operate on the current page. Most take one object whose
+fields match the browser tool schema:
+
+```js
+click({ selector: "a.login" });
+fill({ selector: "input[name='acct']", value: "$LP_HN_USERNAME" });
+fill({ selector: "input[name='pw']", value: "$LP_HN_PASSWORD" });
+press({ key: "Enter" });
+
+waitForSelector("#logout");
+
+hover({ selector: "#menu" });
+selectOption({ selector: "select[name='country']", value: "FR" });
+setChecked({ selector: "input[name='terms']", checked: true });
+setChecked({ selector: "input[name='newsletter']", checked: false });
+
+scroll({ y: 600 });
+scroll();
+```
+
+`setChecked` defaults `checked` to `true` when the field is omitted
+(`setChecked("#chk")` checks the box). `press`'s leading positional is the
+optional `selector`, not `key`: a bare `press("Enter")` binds `"Enter"` to
+`selector` and fails. Press on the focused element with
+`press({ key: "Enter" })` or `press(null, "Enter")`; target an element with
+`press("#search", "Enter")` or `press({ key: "Enter", selector: "#search" })`.
+
+`$LP_*` placeholders in string arguments are resolved inside the Lightpanda
+process. This keeps credentials out of recorded scripts and LLM prompts. In
+recordings, resolved `LP_*` values are scrubbed back to placeholders.
+
+## Error Handling
+
+Primitive failures throw JavaScript exceptions:
+
+```js
+try {
+  waitForSelector({ selector: "#dashboard", timeout: 1000 });
+} catch (err) {
+  console.error("dashboard did not appear:", err.message);
+  throw err;
+}
+```
+
+Common failures:
+
+| Error | Meaning |
+|-------|---------|
+| `ReferenceError: document is not defined` | You tried to use browser DOM APIs in the agent context. Use `extract(...)` or page `evaluate(...)`. |
+| `ReferenceError: require is not defined` | Agent scripts are not Node.js scripts. |
+| `no page loaded - run goto(url) first` | A page-dependent primitive ran before navigation. |
+| `invalid arguments` | A primitive received the wrong number or shape of arguments, or a non-JSON-serializable value. |
+| `extract: no schema selector matched any element` | Every field in the schema missed. Fix the selectors; an empty page section yields `null`/`[]` per field, not this error. |
+
+## Complete Example
+
+This script opens Hacker News, extracts five stories, visits each comments
+page, and prints one JSON object. The looping and object assembly happen in
+the local agent script, not in the page.
+
+```js
+const HN = "https://news.ycombinator.com";
+
+goto(HN);
+
+const { stories } = extract({
+  stories: [{
+    selector: "tr.athing",
+    limit: 5,
+    fields: {
+      id: { attr: "id" },
+      title: ".titleline > a",
+      url: { selector: ".titleline > a", attr: "href" }
+    }
+  }]
+});
+
+for (const story of stories) {
+  story.comments = [];
+  if (!story.id) continue;
+
+  goto(`${HN}/item?id=${story.id}`);
+  const { comments } = extract({
+    comments: [{
+      selector: "tr.athing.comtr:has(.commtext)",
+      limit: 3,
+      fields: {
+        author: ".hnuser",
+        text: ".commtext"
+      }
+    }]
+  });
+  story.comments = comments;
+}
+
+stories; // printed automatically as JSON
+```

From 99151a9aa38aa9a08748a4fe1bc7a901ea12c6e3 Mon Sep 17 00:00:00 2001
From: Pierre Tachoire <pierre@lightpanda.io>
Date: Tue, 16 Jun 2026 10:03:57 +0200
Subject: [PATCH 02/14] update pandascript w/ await + OOP

---
 src/content/usage/pandascript.mdx | 96 ++++++++++++++++---------------
 1 file changed, 50 insertions(+), 46 deletions(-)

diff --git a/src/content/usage/pandascript.mdx b/src/content/usage/pandascript.mdx
index 8b2d40c..30b7d5e 100644
--- a/src/content/usage/pandascript.mdx
+++ b/src/content/usage/pandascript.mdx
@@ -70,9 +70,10 @@ your schema — an object schema returns an object keyed by your fields (even wi
 a single field), and a bare array schema returns an array:
 
 ```js
-goto("https://news.ycombinator.com/");
+const page = new Page();
+await page.goto("https://news.ycombinator.com/");
 
-const data = extract({
+const data = page.extract({
   title: "title",
   stories: [{
     selector: "tr.athing",
@@ -90,7 +91,7 @@ data; // printed automatically as JSON
 Destructure when a single field is all you need:
 
 ```js
-const { stories } = extract({
+const { stories } = page.extract({
   stories: [{
     selector: "tr.athing",
     limit: 5,
@@ -119,19 +120,20 @@ Only recorded browser primitives are installed globally:
 
 | Primitive | Arguments | Runs in |
 |-----------|-----------|---------|
-| `goto` | `goto(url[, { timeout }])` | Browser session |
-| `extract` | `extract(schema)` or `extract({ schema })` | Browser page via extractor; returns a JS object or array |
-| `evaluate` | `evaluate(script[, { url, timeout, save }])` | Browser page JS context |
-| `click` | `click(selector)` or `click({ selector })` | Browser page |
-| `fill` | `fill(selector, value)` or `fill({ selector, value })` | Browser page |
-| `scroll` | `scroll()` or `scroll({ x, y })` | Browser page |
-| `waitForSelector` | `waitForSelector(selector[, { timeout }])` | Browser page |
-| `waitForScript` | `waitForScript(script[, { timeout }])` | Browser page JS context |
-| `waitForState` | `waitForState(state[, { timeout }])` | Browser page |
-| `hover` | `hover(selector)` or `hover({ selector })` | Browser page |
-| `press` | `press(selector, key)` or `press({ key[, selector] })` | Browser page |
-| `selectOption` | `selectOption(selector, value)` or `selectOption({ selector, value })` | Browser page |
-| `setChecked` | `setChecked(selector[, checked])` or `setChecked({ selector, checked })` | Browser page |
+| `new Page()` ||Browser session |
+| `page.goto` | `goto(url[, { timeout }])` | Browser page |
+| `page.extract` | `extract(schema)` or `extract({ schema })` | Browser page via extractor; returns a JS object or array |
+| `page.evaluate` | `evaluate(script[, { url, timeout, save }])` | Browser page JS context |
+| `page.click` | `click(selector)` or `click({ selector })` | Browser page |
+| `page.fill` | `fill(selector, value)` or `fill({ selector, value })` | Browser page |
+| `page.scroll` | `scroll()` or `scroll({ x, y })` | Browser page |
+| `page.waitForSelector` | `waitForSelector(selector[, { timeout }])` | Browser page |
+| `page.waitForScript` | `waitForScript(script[, { timeout }])` | Browser page JS context |
+| `page.waitForState` | `waitForState(state[, { timeout }])` | Browser page |
+| `page.hover` | `hover(selector)` or `hover({ selector })` | Browser page |
+| `page.press` | `press(selector, key)` or `press({ key[, selector] })` | Browser page |
+| `page.selectOption` | `selectOption(selector, value)` or `selectOption({ selector, value })` | Browser page |
+| `page.setChecked` | `setChecked(selector[, checked])` or `setChecked({ selector, checked })` | Browser page |
 
 `goto` returns at the `load` event (a fast snapshot). When a page's content is
 still loading (rendered by post-load JS), call `waitForState("networkidle")`
@@ -160,12 +162,13 @@ script.
 
 ## Navigation
 
-Use `goto(...)` to open a page:
+Use `goto(...)` to navigate on an URL:
 
 ```js
-goto("https://example.com");
+const page = new Page();
+await page.goto("https://example.com");
 
-goto({
+await page.goto({
   url: "https://example.com/app",
   timeout: 15000
 });
@@ -179,12 +182,12 @@ reached. Check the return value — or follow with `waitForState(...)` /
 
 ## Structured Extraction
 
-Use `extract(...)` to read data from the current page without writing page-side
+Use `page.extract(...)` to read data from the current page without writing page-side
 JavaScript. This is the preferred bridge from page content into local agent
 logic.
 
 ```js
-const result = extract({
+const result = page.extract({
   heading: "h1",
   links: [{
     selector: "a",
@@ -236,9 +239,9 @@ When passing an object directly to `extract(...)`, the runtime serializes it as
 the extractor schema. These forms are equivalent:
 
 ```js
-extract({ title: "h1" });
-extract({ schema: { title: "h1" } });
-extract('{ "title": "h1" }');
+page.extract({ title: "h1" });
+page.extract({ schema: { title: "h1" } });
+page.extract('{ "title": "h1" }');
 ```
 
 The wrapped form accepts only `schema`: the REPL's `save=` option does not
@@ -248,7 +251,7 @@ results in local variables instead.
 Use local variables to keep extracted data available to later script logic:
 
 ```js
-const page = extract({ title: "title" });
+const data = page.extract({ title: "title" });
 ```
 
 ## Page JavaScript
@@ -257,9 +260,9 @@ const page = extract({ title: "title" });
 context. Its script string runs where `window` and `document` exist.
 
 ```js
-goto("https://example.com");
+await page.goto("https://example.com");
 
-const title = evaluate("document.title");
+const title = page.evaluate("document.title");
 console.log(title);
 ```
 
@@ -269,10 +272,10 @@ Keep the boundary clear:
 const selector = "h1";
 
 // Good: local agent logic builds an extract schema.
-const data = extract({ heading: selector });
+const data = page.extract({ heading: selector });
 
 // Bad: page evaluate cannot see local agent variables.
-evaluate("document.querySelector(selector).textContent");
+page.evaluate("document.querySelector(selector).textContent");
 ```
 
 Page `evaluate(...)` cannot call `goto`, `extract`, or other agent primitives.
@@ -284,7 +287,7 @@ cannot express.
 expression is truthy or the timeout expires:
 
 ```js
-waitForScript("document.querySelectorAll('.row').length >= 5");
+page.waitForScript("document.querySelectorAll('.row').length >= 5");
 ```
 
 ## Interaction Primitives
@@ -293,20 +296,20 @@ The action primitives operate on the current page. Most take one object whose
 fields match the browser tool schema:
 
 ```js
-click({ selector: "a.login" });
-fill({ selector: "input[name='acct']", value: "$LP_HN_USERNAME" });
-fill({ selector: "input[name='pw']", value: "$LP_HN_PASSWORD" });
-press({ key: "Enter" });
+page.click({ selector: "a.login" });
+page.fill({ selector: "input[name='acct']", value: "$LP_HN_USERNAME" });
+page.fill({ selector: "input[name='pw']", value: "$LP_HN_PASSWORD" });
+page.press({ key: "Enter" });
 
-waitForSelector("#logout");
+page.waitForSelector("#logout");
 
-hover({ selector: "#menu" });
-selectOption({ selector: "select[name='country']", value: "FR" });
-setChecked({ selector: "input[name='terms']", checked: true });
-setChecked({ selector: "input[name='newsletter']", checked: false });
+page.hover({ selector: "#menu" });
+page.selectOption({ selector: "select[name='country']", value: "FR" });
+page.setChecked({ selector: "input[name='terms']", checked: true });
+page.setChecked({ selector: "input[name='newsletter']", checked: false });
 
-scroll({ y: 600 });
-scroll();
+page.scroll({ y: 600 });
+page.scroll();
 ```
 
 `setChecked` defaults `checked` to `true` when the field is omitted
@@ -326,7 +329,7 @@ Primitive failures throw JavaScript exceptions:
 
 ```js
 try {
-  waitForSelector({ selector: "#dashboard", timeout: 1000 });
+  page.waitForSelector({ selector: "#dashboard", timeout: 1000 });
 } catch (err) {
   console.error("dashboard did not appear:", err.message);
   throw err;
@@ -352,9 +355,10 @@ the local agent script, not in the page.
 ```js
 const HN = "https://news.ycombinator.com";
 
-goto(HN);
+const page = new Page();
+await page.goto(HN);
 
-const { stories } = extract({
+const { stories } = page.extract({
   stories: [{
     selector: "tr.athing",
     limit: 5,
@@ -370,8 +374,8 @@ for (const story of stories) {
   story.comments = [];
   if (!story.id) continue;
 
-  goto(`${HN}/item?id=${story.id}`);
-  const { comments } = extract({
+  await page.goto(`${HN}/item?id=${story.id}`);
+  const { comments } = page.extract({
     comments: [{
       selector: "tr.athing.comtr:has(.commtext)",
       limit: 3,

From f82eb2ad4f954341bb9c9c447d0a8f5ce028eb85 Mon Sep 17 00:00:00 2001
From: Pierre Tachoire <pierre@lightpanda.io>
Date: Tue, 16 Jun 2026 10:05:08 +0200
Subject: [PATCH 03/14] adjust ligntpanda

---
 src/content/usage/pandascript.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/usage/pandascript.mdx b/src/content/usage/pandascript.mdx
index 30b7d5e..5f59b13 100644
--- a/src/content/usage/pandascript.mdx
+++ b/src/content/usage/pandascript.mdx
@@ -6,7 +6,7 @@ import { Callout, Tabs } from 'nextra/components'
 
 # PandaScript
 
-A PandaScript is a web automation script that can be run directly by Lightpanda binary.
+A PandaScript is a web automation script that can be run directly by Lightpanda browser.
 
 No environment to setup like NodeJS or Python, no Puppeteer/Playwright to write, no CDP serialization cost, no LLM required: just vanilla Javascript with a small set of native primitives.
 

From 32ef5498ecee808866df64a25b9c30bc984d4672 Mon Sep 17 00:00:00 2001
From: Pierre Tachoire <pierre@lightpanda.io>
Date: Tue, 16 Jun 2026 10:10:38 +0200
Subject: [PATCH 04/14] improve agent's page

---
 src/content/usage/_meta.ts  | 2 +-
 src/content/usage/agent.mdx | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/content/usage/_meta.ts b/src/content/usage/_meta.ts
index e716f88..dfa566f 100644
--- a/src/content/usage/_meta.ts
+++ b/src/content/usage/_meta.ts
@@ -4,7 +4,7 @@ const meta: MetaRecord = {
   cdp: {
     title: 'CDP',
     theme: {
-      collapsed: false,
+      collapsed: true,
     },
   },
   agent: 'Agent',
diff --git a/src/content/usage/agent.mdx b/src/content/usage/agent.mdx
index 1404cae..615a536 100644
--- a/src/content/usage/agent.mdx
+++ b/src/content/usage/agent.mdx
@@ -59,7 +59,7 @@ You can also use slash commands:
 ❯ /links # This will print all the HTML links on the current webpage
 ```
 
-You can generate a reproducible PandaScript from your current session:
+You can generate a reproducible [PandaScript](/usage/pandascript) from your current session:
 
 ```sh copy
 ❯ /save <my_script>.js
@@ -154,7 +154,7 @@ Quoting is content-aware: `'…'`, `"…"`, and triple-quoted `'''…'''` /
 multi-line command and the REPL keeps the whole paste as one input; typed
 line by line, Enter submits at each newline.
 
-### Extracting data 
+### Extracting data
 
 `/extract` takes a JSON schema where each value tells the extractor what to
 lift off the page. The result is printed to stdout as a single JSON object.
@@ -189,7 +189,7 @@ These don't drive the browser, they control the REPL itself:
 | `/effort <level>`        | Sets reasoning budget. Saved to `.lp-agent.zon`.   |
 | `/verbosity <level>`     | Tunes the log level. Levels: low, medium, high.    |
 | `/usage`                 | Prints cumulative token usage and cache hit rate.  |
-| `/save [file] [prompt]`  | Writes the session to a script. `.js` is appended to the name if missing; trailing words guide the synthesizer.|
+| `/save [file] [prompt]`  | Writes the session to a [PandaScript](/usage/pandascript). `.js` is appended to the name if missing; trailing words guide the synthesizer.|
 | `/load <path>`           | Runs a script from disk against the current session.|
 | `/clear`                 | Forgets the conversation (history, usage, recorded actions, node IDs); keeps the page and cookies.|
 | `/reset`                 | Full reset: everything `/clear` does, plus a fresh browser session, dropping the page, cookies, and storage.|

From 878881b62b413aa38dfcd4aec7035f1797d50e1a Mon Sep 17 00:00:00 2001
From: Pierre Tachoire <pierre@lightpanda.io>
Date: Tue, 16 Jun 2026 11:24:25 +0200
Subject: [PATCH 05/14] add agent command reference

---
 src/content/run-locally/commands/_meta.ts  |   1 +
 src/content/run-locally/commands/agent.mdx | 192 +++++++++++++++++++++
 src/content/run-locally/commands/mcp.mdx   |   2 +-
 3 files changed, 194 insertions(+), 1 deletion(-)
 create mode 100644 src/content/run-locally/commands/agent.mdx

diff --git a/src/content/run-locally/commands/_meta.ts b/src/content/run-locally/commands/_meta.ts
index ada85e5..82d7a2e 100644
--- a/src/content/run-locally/commands/_meta.ts
+++ b/src/content/run-locally/commands/_meta.ts
@@ -3,6 +3,7 @@ import type { MetaRecord } from 'nextra'
 const meta: MetaRecord = {
   fetch: 'Fetch',
   serve: 'CDP server',
+  agent: 'Agent',
   mcp: 'MCP',
 }
 
diff --git a/src/content/run-locally/commands/agent.mdx b/src/content/run-locally/commands/agent.mdx
new file mode 100644
index 0000000..fc1de20
--- /dev/null
+++ b/src/content/run-locally/commands/agent.mdx
@@ -0,0 +1,192 @@
+---
+title: Agent
+description: Starts an MCP (Model Context Protocol) server over stdio
+---
+
+# Agent
+
+Start Lightpanda as an interactive AI agent that can browse the web.
+
+```sh copy
+./lightpanda agent
+```
+
+## Options
+
+```bash
+Arguments:
+[SCRIPT]                   Optional path to a .js script. Runs the script
+                           (no LLM calls) and exits. 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.
+
+Options:
+--provider <PROVIDER>      The AI provider.
+                           When omitted, lightpanda auto-detects an API key
+                           from your environment (ANTHROPIC_API_KEY,
+                           OPENAI_API_KEY, GOOGLE_API_KEY/GEMINI_API_KEY).
+                           With exactly one key set: that provider is used.
+                           With multiple keys on a TTY: you'll be prompted
+                           to pick; in non-interactive contexts, pass
+                           --provider explicitly. With no keys set: falls
+                           back to the basic REPL (slash commands only, no
+                           natural-language input, no LOGIN /
+                           ACCEPT_COOKIES keywords).
+
+                           Allowed values:
+                             "anthropic", "openai", "gemini", "ollama".
+                           In the REPL, use /provider to list and change
+                           providers.
+
+--no-llm                   Force the basic REPL even when an API key is
+                           present or --provider is set. Useful for testing
+                           slash commands without burning tokens, or for
+                           disabling the LLM in a saved command without
+                           editing the existing flags. Wins over --provider.
+
+--model <MODEL>            The model name to use.
+                           Defaults to a sensible default per provider.
+                           In the REPL, use /model to list and change
+                           models for the active provider.
+
+--base-url <URL>           Override the API base URL for the provider.
+                           Defaults to the provider's standard endpoint.
+                           Ollama default: http://localhost:11434/v1.
+
+--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.
+
+-a, --attach <PATH>        Feed a local file to the model alongside --task.
+                           Repeatable, one file per flag. Text files are
+                           inlined (max 512 KiB each); images/audio/pdf are
+                           base64-encoded (max 20 MiB each). Requires --task.
+
+--list-models              Print the model IDs usable with `agent` for
+                           --provider, one per line, sorted, and exit.
+                           Auto-detects the provider from env when
+                           --provider is omitted.
+
+--verbosity <LEVEL>        Stderr chatter level.
+                           Default: high when --task captures stderr to a
+                           pipe or file; low otherwise. low/medium also
+                           raise --log-level to err (mutes page-side
+                           console.error spam) unless --log-level is set
+                           explicitly.
+
+                           Allowed values:
+                             low     Silent in --task mode (final answer to
+                                     stdout only); spinner + summary in REPL.
+                             medium  + one `● [tool: ...]` line per call.
+                             high    + the matching `[result: ...]` body
+                                     (required by the benchmarks harness).
+
+API keys are read from the environment: ANTHROPIC_API_KEY, OPENAI_API_KEY,
+or GOOGLE_API_KEY/GEMINI_API_KEY. Ollama does not require an API key.
+
+common options:
+  --insecure-disable-tls-host-verification
+          Disables host verification on all HTTP requests.
+          Only set this if you understand and accept the risk.
+  --obey-robots
+          Fetches and obeys robots.txt of the target page.
+          Defaults to false.
+  --disable-subframes
+          Skip loading <iframe> elements. The parser still registers them in the
+          DOM, but no child frame or Page.frameAttached events are produced.
+          Defaults to false.
+  --disable-workers
+          Skip loading dedicated Web Workers. The Worker constructor still
+          returns a Worker object, but no script fetch is initiated and its scope
+          never runs.
+          Defaults to false.
+  --enable-external-stylesheets
+          Fetch external <link rel=stylesheet> resources so their rules
+          contribute to computed styles (and therefore to visibility checks like
+          display, visibility, opacity, pointer-events).
+          Defaults to false, except in agent mode with an LLM, where it is on.
+  --block-private-networks
+          Block HTTP requests to private/internal IP addresses after DNS
+          resolution.
+          Defaults to false.
+  --block-cidrs <LIST>
+          Additional CIDR ranges to block, comma-separated.
+          Prefix with '-' to allow (exempt from blocking).
+          e.g. --block-cidrs 10.0.0.0/8,-10.0.0.42/32
+          Can be combined with --block-private-networks.
+  --http-proxy <URL>
+          HTTP proxy for all HTTP requests.
+          username:password may be included for basic auth.
+          Defaults to none.
+  --proxy-bearer-token <TOKEN>
+          Token sent for bearer authentication with the proxy:
+          Proxy-Authorization: Bearer <token>.
+  --http-max-concurrent <INT>
+          Maximum number of concurrent HTTP requests.
+          Defaults to 10.
+  --http-max-host-open <INT>
+          Maximum open connections to a given host:port.
+          Defaults to 4.
+  --http-connect-timeout <INT>
+          Time in ms to establish an HTTP connection before timing out. 0 means
+          never.
+          Defaults to 0.
+  --http-timeout <INT>
+          Maximum time in ms the transfer is allowed to complete. 0 means never.
+          Defaults to 10000.
+  --http-max-response-size <INT>
+          Limits the acceptable response size for any request
+          e.g. XHR, fetch, script loading.
+          Defaults to no limit.
+  --ws-max-concurrent <INT>
+          Maximum number of concurrent WebSocket connections.
+          Defaults to 8.
+  --log-level <LEVEL>
+          The log level.
+          Defaults to warn.
+          Allowed values: "debug", "info", "warn", "error", "fatal".
+  --log-format <FORMAT>
+          The log format.
+          Defaults to logfmt.
+          Allowed values: "pretty", "logfmt".
+  --log-filter-scopes <SCOPES>
+          Filter out too-verbose logs per scope, comma-separated.
+          e.g. http, unknown_prop, event.
+  --user-agent <STRING>
+          Override the User-Agent header entirely. Must not impersonate other
+          browsers; any value containing "Mozilla" is forbidden. The browser
+          still sends Sec-Ch-Ua. Incompatible with --user-agent-suffix.
+  --user-agent-suffix <STRING>
+          Suffix appended to the Lightpanda/X.Y User-Agent.
+  --web-bot-auth-key-file <PATH>
+          Path to the Ed25519 private key PEM file.
+  --web-bot-auth-keyid <STRING>
+          The JWK thumbprint of your public key.
+  --web-bot-auth-domain <DOMAIN>
+          Your domain, e.g. yourdomain.com.
+  --http-cache-dir <PATH>
+          Directory used as a filesystem cache for network resources. Omitting
+          this disables caching.
+          Defaults to no caching.
+  --cookie <PATH>
+          Path to a JSON file to load cookies from (read-only).
+          Defaults to no cookie loading.
+  --cookie-jar <PATH>
+          Path to a JSON file to save cookies to on exit (write-only).
+          Defaults to no cookie saving.
+  --storage-engine <ENGINE>
+          The storage engine to use.
+          Defaults to none.
+          Allowed values: "none", "sqlite".
+  --storage-sqlite-path <PATH>
+          Path to the SQLite database file for persistent storage.
+          Use ":memory:" for in-memory storage.
+```
+
+Find details about the [Agent](/usage/agent) and [PandaScript](/usage/pandascript) usage.
diff --git a/src/content/run-locally/commands/mcp.mdx b/src/content/run-locally/commands/mcp.mdx
index bcaf59b..a76f9e9 100644
--- a/src/content/run-locally/commands/mcp.mdx
+++ b/src/content/run-locally/commands/mcp.mdx
@@ -3,7 +3,7 @@ title: MCP
 description: Starts an MCP (Model Context Protocol) server over stdio
 ---
 
-# Serve
+# MCP
 
 Start Lightpanda as a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server over stdio to control it with LLMs.
 

From 307c01c53c65e002ef05f622daf3f4102b3727bb Mon Sep 17 00:00:00 2001
From: Pierre Tachoire <pierre@lightpanda.io>
Date: Tue, 16 Jun 2026 11:38:53 +0200
Subject: [PATCH 06/14] update MCP tools

---
 src/content/usage/mcp.mdx | 76 +++++++++++++++++++++++----------------
 1 file changed, 46 insertions(+), 30 deletions(-)

diff --git a/src/content/usage/mcp.mdx b/src/content/usage/mcp.mdx
index cdff3ea..4910e76 100644
--- a/src/content/usage/mcp.mdx
+++ b/src/content/usage/mcp.mdx
@@ -20,46 +20,38 @@ Start the MCP server:
 
 Find reference of [MCP command options](/run-locally/commands/mcp).
 
-  </Tabs.Tab>
-  <Tabs.Tab>
-<Callout type="info" emoji="ℹ️">
-This is still a work in progress version. The cloud version does not support all tools.
-</Callout>
-
-Lightpanda Cloud exposes the MCP server over [SSE](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse). Connect to the endpoint nearest to you:
-
-- `https://euwest.cloud.lightpanda.io/mcp/sse` (Europe West)
-- `https://uswest.cloud.lightpanda.io/mcp/sse` (US West)
-
-Pass your API token as a query parameter or in the `Authorization` header:
-
-```text copy
-https://euwest.cloud.lightpanda.io/mcp/sse?token=TOKEN
-```
-
-```text copy
-https://euwest.cloud.lightpanda.io/mcp/sse
-Authorization: Bearer TOKEN
-```
-  </Tabs.Tab>
-</Tabs>
-
 ## Tools
 
 | Name | Description |
-|-|-|
-| goto | Navigate to a specified URL and load the page in memory so it can be reused later for info extraction |
+|---|---|
+| goto | Navigate to a specified URL and load the page in memory so it can be reused later for info extraction. |
+| getUrl | Get the URL of the page currently loaded in the browser. |
+| getEnv | Read an `LP_*` environment variable by name, or list the `LP_*` names that are set when called without a name. |
+| getCookies | Get cookies stored in the browser. Defaults to the current page's host; pass `url` to filter another host or `all` to dump every cookie. |
+| consoleLogs | Get buffered console.log/warn/error messages from the current page, then clear the buffer. |
+| tree | Get the page content as a simplified semantic DOM tree for AI reasoning. If a url is provided, it navigates to that url first. |
 | markdown | Get the page content in markdown format. If a url is provided, it navigates to that url first. |
-| links | Extract all links in the opened page. If a url is provided, it navigates to that url first. |
-| evaluate | Evaluate JavaScript in the current page context. If a url is provided, it navigates to that url first. |
-| semantic_tree | Get the page content as a simplified semantic DOM tree for AI reasoning. If a url is provided, it navigates to that url first. |
+| html | Get the raw serialized HTML of the page, or a single node's outerHTML when a selector or backendNodeId is given. If a url is provided, it navigates to that url first. |
+| nodeDetails | Get details for a node by backendNodeId, including a ready-to-use CSS selector plus tag, role, name, attributes, and state. |
+| findElement | Find interactive elements by role and/or accessible name, returning their backend node IDs. |
 | interactiveElements | Extract interactive elements from the opened page. If a url is provided, it navigates to that url first. |
+| links | Extract all links in the opened page. If a url is provided, it navigates to that url first. |
+| extract | Extract structured data from the current page using a schema mapping output field names to CSS-selector specs. |
 | structuredData | Extract structured data (like JSON-LD, OpenGraph, etc) from the opened page. If a url is provided, it navigates to that url first. |
-| detectForms | Detect all forms on the page and return their structure including fields, types, and required status. If a url is provided, it navigates to that url first. |
+| search | Run a web search and return the results as markdown. |
 | click | Click on an interactive element. Returns the current page URL and title after the click. |
+| hover | Hover over an element, triggering mouseover and mouseenter events. |
 | fill | Fill text into an input element. Returns the filled value and current page URL and title. |
+| selectOption | Select an option in a `<select>` dropdown element by its value. Dispatches input and change events. |
+| setChecked | Check or uncheck a checkbox or radio button. Dispatches input, change, and click events. |
+| press | Press a keyboard key, dispatching keydown and keyup events. |
 | scroll | Scroll the page or a specific element. Returns the scroll position and current page URL and title. |
+| detectForms | Detect all forms on the page and return their structure including fields, types, and required status. If a url is provided, it navigates to that url first. |
+| evaluate | Evaluate JavaScript in the current page context. If a url is provided, it navigates to that url first. |
+| save | Save the session as a reusable Lightpanda agent script (.js). |
 | waitForSelector | Wait for an element matching a CSS selector to appear in the page. Returns the backend node ID of the matched element. |
+| waitForState | Wait for the current page to reach a load state (e.g. `networkidle`), with no navigation. |
+| waitForScript | Wait until a JavaScript expression returns truthy, re-evaluating on each tick of the event loop. |
 
 ### `goto`
 
@@ -224,6 +216,30 @@ lightpanda mcp --log-level info 2>lightpanda.log
 
 Use `--log-level debug` for the most verbose output. Keep `warn` in production.
 
+  </Tabs.Tab>
+  <Tabs.Tab>
+<Callout type="info" emoji="ℹ️">
+This is still a work in progress version. The cloud version does not support all tools.
+</Callout>
+
+Lightpanda Cloud exposes the MCP server over [SSE](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse). Connect to the endpoint nearest to you:
+
+- `https://euwest.cloud.lightpanda.io/mcp/sse` (Europe West)
+- `https://uswest.cloud.lightpanda.io/mcp/sse` (US West)
+
+Pass your API token as a query parameter or in the `Authorization` header:
+
+```text copy
+https://euwest.cloud.lightpanda.io/mcp/sse?token=TOKEN
+```
+
+```text copy
+https://euwest.cloud.lightpanda.io/mcp/sse
+Authorization: Bearer TOKEN
+```
+  </Tabs.Tab>
+</Tabs>
+
 ## References
 
 - [LP Domain & Native MCP — Lightpanda Blog](https://lightpanda.io/blog/posts/lp-domain-commands-and-native-mcp)

From 02e446bed9fa83e54d946b0317f6ec29409e44b2 Mon Sep 17 00:00:00 2001
From: Pierre Tachoire <pierre@lightpanda.io>
Date: Tue, 16 Jun 2026 11:54:23 +0200
Subject: [PATCH 07/14] add a link MCP->PandaScript

---
 src/content/usage/mcp.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/usage/mcp.mdx b/src/content/usage/mcp.mdx
index 4910e76..18be7c5 100644
--- a/src/content/usage/mcp.mdx
+++ b/src/content/usage/mcp.mdx
@@ -48,7 +48,7 @@ Find reference of [MCP command options](/run-locally/commands/mcp).
 | scroll | Scroll the page or a specific element. Returns the scroll position and current page URL and title. |
 | detectForms | Detect all forms on the page and return their structure including fields, types, and required status. If a url is provided, it navigates to that url first. |
 | evaluate | Evaluate JavaScript in the current page context. If a url is provided, it navigates to that url first. |
-| save | Save the session as a reusable Lightpanda agent script (.js). |
+| save | Save the session as a reusable [PandaScript](/usage/pandascript) (.js). |
 | waitForSelector | Wait for an element matching a CSS selector to appear in the page. Returns the backend node ID of the matched element. |
 | waitForState | Wait for the current page to reach a load state (e.g. `networkidle`), with no navigation. |
 | waitForScript | Wait until a JavaScript expression returns truthy, re-evaluating on each tick of the event loop. |

From ccb56697da8c9a500e1760d4435a1ca187b3efab Mon Sep 17 00:00:00 2001
From: Pierre Tachoire <pierre@lightpanda.io>
Date: Tue, 16 Jun 2026 12:15:47 +0200
Subject: [PATCH 08/14] add Hugging Face support

---
 src/content/usage/agent.mdx | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/content/usage/agent.mdx b/src/content/usage/agent.mdx
index 615a536..1be6cfc 100644
--- a/src/content/usage/agent.mdx
+++ b/src/content/usage/agent.mdx
@@ -36,7 +36,7 @@ Set an API key for your preferred LLM provider:
 export ANTHROPIC_API_KEY=<YOUR_ANTHROPIC_KEY>
 ```
 
-Or `OPENAI_API_KEY`, `GOOGLE_API_KEY`, or a local LLM through an Ollama server.
+Or `OPENAI_API_KEY`, `GOOGLE_API_KEY`, `HF_TOKEN`, or a local LLM through an Ollama server.
 
 Launch the REPL:
 
@@ -86,6 +86,7 @@ while on the REPL.
 | Anthropic | `--provider anthropic` | `ANTHROPIC_API_KEY`                  |
 | OpenAI    | `--provider openai`    | `OPENAI_API_KEY`                     |
 | Gemini    | `--provider gemini`    | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
+| Hugging Face    | `--provider huggingface`    | `HF_TOKEN`|
 | Ollama    | `--provider ollama`    | none (local)                         |
 
 You can set explicitly the provider with the CLI option `--provider` or the REPL command `/provider`.
@@ -96,7 +97,7 @@ Otherwise the agent will pick one on this order:
    set.
 2. **Auto-detected** - the first key found in priority order
    (`ANTHROPIC_API_KEY` → `GOOGLE_API_KEY`/`GEMINI_API_KEY` →
-   `OPENAI_API_KEY`). With several keys on the REPL, you'll be prompted to
+   `OPENAI_API_KEY` → `HF_TOKEN`). With several keys on the REPL, you'll be prompted to
    pick.
 3. **Local** - if no cloud key is set, the agent probes
    `http://localhost:11434/v1` (Ollama default server endpoint)

From a698238ea9f64ffe76ab684b9a431f860a392b61 Mon Sep 17 00:00:00 2001
From: Pierre Tachoire <pierre@lightpanda.io>
Date: Tue, 16 Jun 2026 15:16:45 +0200
Subject: [PATCH 09/14] typo fixes

---
 src/content/usage/agent.mdx | 36 ++++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/src/content/usage/agent.mdx b/src/content/usage/agent.mdx
index 1be6cfc..90eda04 100644
--- a/src/content/usage/agent.mdx
+++ b/src/content/usage/agent.mdx
@@ -15,20 +15,20 @@ conversation with.
 
 Every session starts by navigating to a page, either by
 saying so ("go to this website") or by typing `/goto <url>`. There's
-no window to look at; the browser runs headlessly and you see its output
+no window to look at; the browser runs in headless mode and you see its output
 (extracted data, the agent's answer) in your terminal.
 
 The agent stacks three layers:
 
 1. **The browser** Loads webpages, runs JavaScript and handles the DOM.
    It's the same engine that powers Lightpanda CDP server.
-2. **The runtime** A small set of native tools that let's you drive the browser:
+2. **The runtime** A small set of native tools that lets you drive the browser:
    `goto`, `click`, `fill`, `extract`, `evaluate`, `search`, and more.
-   Each is available as a slash command (`/goto`, `/click`, ...).
+   Each is available as a command (`/goto`, `/click`, ...).
 3. **An LLM** Reads your natural language request and decides which tools to
-   call. Optional, the agent can also run without it.
+   call. It's optional; the agent can also run without it.
 
-## Quick start
+## Quickstart
 
 Set an API key for your preferred LLM provider:
 
@@ -52,7 +52,7 @@ Tell it what you want:
 
 The agent navigates, extracts, prints the answer.
 
-You can also use slash commands:
+You can also use commands:
 
 ```sh copy
 ❯ /goto news.ycombinator.com
@@ -89,8 +89,8 @@ while on the REPL.
 | Hugging Face    | `--provider huggingface`    | `HF_TOKEN`|
 | Ollama    | `--provider ollama`    | none (local)                         |
 
-You can set explicitly the provider with the CLI option `--provider` or the REPL command `/provider`.
-Otherwise the agent will pick one on this order:
+You can set the provider explicitly with the CLI option `--provider` or the REPL command `/provider`.
+Otherwise the agent will pick one in this order:
 
 1. **Remembered** - whatever you last selected with `/provider`,
    persisted per-directory in `.lp-agent.zon`, as long as its key is still
@@ -109,32 +109,32 @@ Otherwise the agent will pick one on this order:
 
 ### Models
 
-You can set explicitly a model with the CLI option `/model` or the REPL command `/model`.
+You can set the model explicitly with the CLI option `/model` or the REPL command `/model`.
 Otherwise the agent will pick either the last one persisted per-directory in `.lp-agent.zon`
 or a sensible per-provider default.
 
 The CLI option `--list-models` or pressing TAB on the REPL command `/model` prints the list of available models.
 
-The CLI option `--effot <none|minimal|low|medium|high|xhigh>` or the REPL command `/effort`
+The CLI option `--effort <none|minimal|low|medium|high|xhigh>` or the REPL command `/effort`
 sets the per-turn reasoning budget for thinking models.
 It maps to each provider's native reasoning-effort knob and is ignored by non-thinking models.
 The REPL defaults to `low` so turns stay snappy.
 `--task` defaults to `medium` where answer quality matters more than per-turn latency.
 Higher effort can mean fewer tool calls per task (the model plans better),
-so it's a real tradeoff rather than a pure slowdown
+so it's a real tradeoff rather than a pure slowdown.
 Effort selection persists in `.lp-agent.zon`.
 
 The CLI option `--system-prompt` swaps in your own system prompt.
 
-## Slash commands
+## Commands
 
 The REPL uses a small slash-command language for browser actions. Each line
-you type at the prompt is either a slash command, a `#` comment, a blank
+you type at the prompt is either a command, a `#` comment, a blank
 line, or (when an LLM is configured) a natural-language prompt.
 
-`/help` list all available slash commands, `/help <command>` for details.
+`/help` lists all available commands, `/help <command>` for details.
 
-Slash commands accept:
+commands accept:
 
 - A single positional value, when the tool has exactly one required field.
   `/goto 'https://example.com'`. The value can itself be quoted JSON when
@@ -204,7 +204,7 @@ a completely clean browser (no cookies, no current page, no storage).
 
 ### LLM-driven commands
 
-Three slash commands trigger an LLM turn rather than a direct tool call:
+Three commands trigger an LLM turn rather than a direct tool call:
 
 | Command          | What it does                                          |
 |------------------|-------------------------------------------------------|
@@ -239,7 +239,7 @@ All three require an LLM. `--no-llm` rejects them.
   `$LP_*` refs are still resolved at execution, console output is echoed
   back, and `Esc` exits. JS-mode lines are not recorded.
 - **Tab completion** (case-insensitive). Cycles through `/<tool>` and meta
-  slash commands. The dim grey suffix shown after the cursor is the first
+  commands. The dim gray suffix shown after the cursor is the first
   match.
 - **Persistent history.** Stored in `.lp-history` in the working directory.
 - **Stdout vs stderr.** The final assistant answer and data-producing slash
@@ -259,7 +259,7 @@ exits. On a TTY a spinner on stderr shows the tool currently running while
 the agent works; raise `--verbosity` for the full `[tool/result]` trace.
 
 Combine with `-a <path>` / `--attach <path>` (repeatable) to feed
-local files to providers that accept attachments — for example, a list of
+local files to providers that accept attachments. For example, a list of
 items to look up, or a document to cross-check against a live page:
 
 ```console

From 6072c66443c2bc5c115c28d8f9f877bd083777c1 Mon Sep 17 00:00:00 2001
From: Pierre Tachoire <pierre@lightpanda.io>
Date: Tue, 16 Jun 2026 15:28:55 +0200
Subject: [PATCH 10/14] typo fix in pandascript

---
 src/content/usage/pandascript.mdx | 36 +++++++++++++++----------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/src/content/usage/pandascript.mdx b/src/content/usage/pandascript.mdx
index 5f59b13..e069826 100644
--- a/src/content/usage/pandascript.mdx
+++ b/src/content/usage/pandascript.mdx
@@ -8,9 +8,9 @@ import { Callout, Tabs } from 'nextra/components'
 
 A PandaScript is a web automation script that can be run directly by Lightpanda browser.
 
-No environment to setup like NodeJS or Python, no Puppeteer/Playwright to write, no CDP serialization cost, no LLM required: just vanilla Javascript with a small set of native primitives.
+No environment to set up like NodeJS or Python, no Puppeteer/Playwright to write, no CDP serialization cost, no LLM required: just vanilla Javascript with a small set of native primitives.
 
-Use normal Javascript variables, functions, loops, objects, arrays, `JSON.parse`, `JSON.stringify`, and other standard ECMAScript built-ins.
+Use normal JavaScript variables, functions, loops, objects, arrays, `JSON.parse`, `JSON.stringify`, and other standard ECMAScript built-ins.
 
 It's reproducible, deterministic and token-free (no LLM required).
 
@@ -45,7 +45,7 @@ web page's JavaScript context.
   primitive calls.
 - Tool failures throw JavaScript `Error` exceptions and stop execution unless
   you catch them.
-- The script's completion value — its last top-level expression — is printed
+- The script's completion value (its last top-level expression) is printed
   automatically (objects and arrays as JSON; other values coerced). End a
   script with the bare expression you want as output, e.g. a final
   `extract({ ... });` or `results;`. `console.log(...)` is for extra or debug
@@ -66,7 +66,7 @@ console.error("printed to stderr");
 Most primitives return the browser tool's result text as a JavaScript string.
 `extract(...)` is the exception: it returns extracted data as a normal
 JavaScript value, so local script logic can use it directly. The result mirrors
-your schema — an object schema returns an object keyed by your fields (even with
+your schema: an object schema returns an object keyed by your fields (even with
 a single field), and a bare array schema returns an array:
 
 ```js
@@ -145,7 +145,7 @@ before reading. `waitForState`'s `state` accepts `"load"`,
 The `[, { … }]` is an optional trailing options object: leading arguments are
 positional (`waitForSelector("#row", { timeout: 2000 })`), and the options ride
 in a final object. Passing a single object with everything
-(`waitForSelector({ selector: "#row", timeout: 2000 })`) is equivalent — that's
+(`waitForSelector({ selector: "#row", timeout: 2000 })`) is equivalent; that's
 the shape `/save` records into saved scripts. An option can't be a bare
 positional, though: `waitForSelector("#row", 2000)` is an error. A `null`
 positional omits that field (`press(null, "Enter")` presses on the focused
@@ -155,14 +155,14 @@ element), and setting the same field positionally and in the options object
 Script primitives address elements by CSS selector only. The tools that hand
 out `backendNodeId`s (`tree`, `findElement`, `nodeDetails`) aren't installed in
 the script context, and a raw node ID wouldn't survive replay anyway. When
-you're exploring in the REPL and have a `backendNodeId` — e.g. the leading
-number on a `/tree` line, or a `/findElement` hit — run `/nodeDetails
+you're exploring in the REPL and have a `backendNodeId` (e.g. the leading
+number on a `/tree` line, or a `/findElement` hit) run `/nodeDetails
 backendNodeId=<id>` to get a durable CSS `selector`, then paste that into your
 script.
 
 ## Navigation
 
-Use `goto(...)` to navigate on an URL:
+Use `goto(...)` to navigate to an URL:
 
 ```js
 const page = new Page();
@@ -177,8 +177,8 @@ await page.goto({
 The call returns a status string and throws if navigation fails. A timeout
 does **not** throw: the call returns `"Navigation started but the page did not
 finish loading before the timeout."` and the page stays in whatever state it
-reached. Check the return value — or follow with `waitForState(...)` /
-`waitForSelector(...)` — when completeness matters.
+reached. Check the return value, or follow with `waitForState(...)` /
+`waitForSelector(...)`, when completeness matters.
 
 ## Structured Extraction
 
@@ -217,23 +217,23 @@ Return shape follows the top-level schema:
 - `extract({ title: "h1" })` returns `{ title: "..." }`.
 - `extract({ title: "h1", links: [{ selector: "a" }] })` returns an object
   with both fields.
-- `extract({ links: [{ selector: "a" }] })` returns `{ links: [...] }` — an
+- `extract({ links: [{ selector: "a" }] })` returns `{ links: [...] }`. An
   object schema always returns an object, even with a single field.
 - `extract([{ selector: "a" }])` is shorthand for a single anonymous array
   extraction and returns the array directly.
 
-Every value is a string (trimmed text or a raw attribute) or `null` — parse
+Every value is a string (trimmed text or a raw attribute) or `null`; parse
 numbers in script logic. An array field that matches nothing yields `[]`
 without complaint (a page with zero comments is a valid result), but if
 *every* field in the schema misses, `extract(...)` throws
-`no schema selector matched any element` — treat that as "my selectors are
+`no schema selector matched any element`; treat that as "my selectors are
 wrong", not "the page is empty".
 
-`extract(...)` reads only the current page. For list-to-detail scraping —
-capture a list, then visit each row for more — capture the list, then loop in
-the script: `goto` each row's URL and `extract` the detail. The local agent
-context keeps the data across navigations, so the assembly happens in plain
-JavaScript. See the [complete example](#complete-example) below.
+`extract(...)` reads only the current page. For list-to-detail scraping:
+capture the list, then loop in the script (`goto` each row's URL and `extract`
+the detail). The local agent context keeps the data across navigations, so the
+assembly happens in plain JavaScript. See the [complete
+example](#complete-example) below.
 
 When passing an object directly to `extract(...)`, the runtime serializes it as
 the extractor schema. These forms are equivalent:

From 3ec87de212328846d018e44e3c51a4ce0e92992a Mon Sep 17 00:00:00 2001
From: Pierre Tachoire <pierre@lightpanda.io>
Date: Tue, 16 Jun 2026 15:30:58 +0200
Subject: [PATCH 11/14] fix code style for references

---
 src/content/run-locally/commands/agent.mdx | 2 +-
 src/content/run-locally/commands/fetch.mdx | 2 +-
 src/content/run-locally/commands/mcp.mdx   | 2 +-
 src/content/run-locally/commands/serve.mdx | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/content/run-locally/commands/agent.mdx b/src/content/run-locally/commands/agent.mdx
index fc1de20..78f5aa6 100644
--- a/src/content/run-locally/commands/agent.mdx
+++ b/src/content/run-locally/commands/agent.mdx
@@ -13,7 +13,7 @@ Start Lightpanda as an interactive AI agent that can browse the web.
 
 ## Options
 
-```bash
+```console
 Arguments:
 [SCRIPT]                   Optional path to a .js script. Runs the script
                            (no LLM calls) and exits. With no script and no
diff --git a/src/content/run-locally/commands/fetch.mdx b/src/content/run-locally/commands/fetch.mdx
index 7c910bf..01c909a 100644
--- a/src/content/run-locally/commands/fetch.mdx
+++ b/src/content/run-locally/commands/fetch.mdx
@@ -36,7 +36,7 @@ INFO  http : request complete . . . . . . . . . . . . . . . . [+234ms]
 
 ## Options
 
-```bash
+```console
   --host <HOST>
           Host of the CDP server.
           Defaults to "127.0.0.1".
diff --git a/src/content/run-locally/commands/mcp.mdx b/src/content/run-locally/commands/mcp.mdx
index a76f9e9..e33133f 100644
--- a/src/content/run-locally/commands/mcp.mdx
+++ b/src/content/run-locally/commands/mcp.mdx
@@ -13,7 +13,7 @@ Start Lightpanda as a [Model Context Protocol](https://modelcontextprotocol.io)
 
 ## Options
 
-```bash
+```console
 options:
   --cookie <PATH>
           Path to a JSON file to load cookies from (read-only).
diff --git a/src/content/run-locally/commands/serve.mdx b/src/content/run-locally/commands/serve.mdx
index fec84d1..826dc68 100644
--- a/src/content/run-locally/commands/serve.mdx
+++ b/src/content/run-locally/commands/serve.mdx
@@ -17,7 +17,7 @@ INFO  app : server running . . . . . . . . . . . . . . . . .  [+0ms]
 
 ## Options
 
-```bash
+```console
 options:
   --host <HOST>
           Host of the CDP server.

From 95babf481e9f7b5a43bc9451bd826b354fa36183 Mon Sep 17 00:00:00 2001
From: Pierre Tachoire <pierre@lightpanda.io>
Date: Tue, 16 Jun 2026 16:14:00 +0200
Subject: [PATCH 12/14] add agent guide

---
 src/content/guides/_meta.ts                   |   1 +
 .../guides/lightpanda-agent-tutorial.mdx      | 303 ++++++++++++++++++
 2 files changed, 304 insertions(+)
 create mode 100644 src/content/guides/lightpanda-agent-tutorial.mdx

diff --git a/src/content/guides/_meta.ts b/src/content/guides/_meta.ts
index 25f8c52..a9e1e23 100644
--- a/src/content/guides/_meta.ts
+++ b/src/content/guides/_meta.ts
@@ -1,6 +1,7 @@
 import type { MetaRecord } from 'nextra'
 
 const meta: MetaRecord = {
+  'lightpanda-agent-tutorial': 'Use Lightpanda Agent',
   'retrieve-an-html-webpage': 'Retrieve an HTML webpage',
   'configure-a-proxy': 'Configure a proxy',
   'markdown-axtree': 'Get Markdown and AX Tree',
diff --git a/src/content/guides/lightpanda-agent-tutorial.mdx b/src/content/guides/lightpanda-agent-tutorial.mdx
new file mode 100644
index 0000000..daec9e9
--- /dev/null
+++ b/src/content/guides/lightpanda-agent-tutorial.mdx
@@ -0,0 +1,303 @@
+---
+title: Use Lightpanda Agent
+description: Use Lightpanda Agent to create a reproducible JavaScript browser script.
+---
+
+# Use Lightpanda Agent
+
+This tutorial will walk you through how to use Lightpanda Agent to create a
+reproducible JavaScript browser script.
+
+See [reference](/run-locally/commands/agent) for flags and commands.
+
+## Prerequisites
+
+- Lightpanda installed and on your `PATH`.
+- A Hacker News account.
+- An LLM API key for the natural-language sections (Anthropic, OpenAI,
+  Gemini, Hugging Face or a local Ollama). Recorded `.js` PandaScripts need no key.
+
+Export your HN credentials as `LP_*` env vars. The `LP_` prefix
+matters for security: Lightpanda only resolves these placeholders
+inside its own subprocess (so your password never reaches the LLM),
+and the `getEnv` tool refuses any variable that doesn't start with
+`LP_` (so the LLM can't read your other secrets).
+
+```sh copy
+export LP_HN_USERNAME="your-hn-handle"
+export LP_HN_PASSWORD="your-hn-password"
+```
+
+Check the variables are set. If one is missing, `/fill` will silently
+type the literal `$LP_HN_USERNAME` into the form rather than your
+username:
+
+```sh copy
+lightpanda agent --no-llm
+```
+```console
+> /getEnv LP_HN_USERNAME
+```
+
+## 1. Start the REPL
+
+```sh copy
+lightpanda agent
+```
+
+The startup banner shows whether natural language is available;
+`/model` prints the resolved model. REPL history lives in `.lp-history`
+in the working directory.
+
+```console
+> /help            # list every browser tool
+> /help goto       # JSON schema for one tool
+> /quit
+```
+
+No API key? `lightpanda agent --no-llm` runs the slash-commands-only
+REPL.
+
+## 2. Run a single task
+
+Before doing anything complicated, run a one-shot task to check
+everything works:
+
+```sh copy
+lightpanda agent --task "what is the top story on news.ycombinator.com?"
+```
+
+`--task` runs one user turn, prints the answer on stdout, exits.
+Tool calls and progress go to stderr, so redirecting gives you a
+clean answer:
+
+```sh copy
+lightpanda agent --task "top story on news.ycombinator.com?" > out.txt
+```
+
+Use `-a <path>` (repeatable) to attach local files.
+
+## 3. Log in to Hacker News
+
+Paste these into the REPL in order:
+
+```console
+> /goto https://news.ycombinator.com/login
+> /fill selector='form[action="login"] input[name="acct"]' value='$LP_HN_USERNAME'
+> /fill selector='form[action="login"] input[name="pw"]' value='$LP_HN_PASSWORD'
+> /click selector='form[action="login"] input[type="submit"][value="login"]'
+> /waitForSelector '#logout'
+```
+
+A few things worth knowing:
+
+- **Slash commands only.** `click '#foo'` is forwarded to the LLM;
+  only `/click '#foo'` runs as a command. TAB completes tool names.
+- **`/waitForSelector '#logout'` is both a sync point and an
+  assertion.** It blocks until HN's logged-in DOM renders. If the
+  credentials are wrong (or the website throws a captcha, or the layout
+  changes), the command times out at the line where the failure
+  actually happened. Use this pattern after every state-changing
+  action.
+- **Selectors are CSS only.** The click-family tools (`/click`,
+  `/fill`, `/hover`, `/selectOption`, `/setChecked`) accept CSS
+  only. Backend node IDs are invalidated by any DOM mutation and
+  can't be serialized into recordings.
+
+Confirm the login worked:
+
+```console
+> /extract '{"karma": "#karma"}'
+{"karma":"42"}
+```
+
+`/extract` takes a JSON schema and prints one JSON object to stdout.
+Schema grammar:
+
+- `"<sel>"`: text of the first match.
+- `["<sel>"]`: text of every match.
+- `{"selector": "<sel>", "attr": "<name>"}`: attribute of the first match.
+- `[{"selector": "<sel>", "fields": {…}}]`: array of records, with
+  each `fields` entry resolved relative to the matched element.
+
+Now go to the front page and pull the story list:
+
+```console
+> /goto https://news.ycombinator.com
+> /extract '''
+{
+  "topStories": [{
+    "selector": ".athing",
+    "fields": {
+      "rank": ".rank",
+      "title": ".titleline > a",
+      "url": {"selector": ".titleline > a", "attr": "href"}
+    }
+  }]
+}
+'''
+```
+
+Triple-quoted values let a schema span multiple lines.
+
+### How we got those selectors
+
+Skip this if you're happy treating them as given.
+
+`/tree` prints the semantic tree. On the login page you'll see two
+forms (login and signup) with unlabeled textboxes, which means
+`/findElement role=textbox name=username` returns nothing.
+
+`/detectForms` reads the HTML directly and surfaces each form's
+`action` plus each input's `name`. The first form has `action: "login"`
+and fields named `acct` and `pw`, which gives us the form-scoped
+selector (`form[action="login"] input[name="acct"]`) that won't
+collide with signup.
+
+`/nodeDetails backendNodeId=<n>` is the alternative: it returns a
+ready-to-use CSS selector for any node ID from `/tree`.
+
+## 4. Save the session as a script
+
+Retype the login plus front-page sequence in a single REPL session,
+then:
+
+```console
+> /save hn_login.js
+> /quit
+```
+
+In `--no-llm` mode, `/save` transcribes the session deterministically.
+With an LLM, it synthesizes an idiomatic script. The result is
+JavaScript:
+
+```js copy
+const page = new Page();
+await page.goto("https://news.ycombinator.com/login");
+page.fill({ selector: "form[action=\"login\"] input[name=\"acct\"]", value: "$LP_HN_USERNAME" });
+page.fill({ selector: "form[action=\"login\"] input[name=\"pw\"]", value: "$LP_HN_PASSWORD" });
+page.click({ selector: "form[action=\"login\"] input[type=\"submit\"][value=\"login\"]" });
+page.waitForSelector("#logout");
+await page.goto("https://news.ycombinator.com");
+return page.extract({ topStories: [{ selector: ".athing", fields: { rank: ".rank", title: ".titleline > a", url: { selector: ".titleline > a", attr: "href" } } }] });
+```
+
+Only state-mutating commands are recorded; read-only ones (`/tree`,
+`/markdown`) are dropped. `/extract` is recorded because it shapes
+what the script returns.
+
+## 5. Replay the script without an LLM
+
+```sh copy
+lightpanda agent hn_login.js
+```
+
+No `--provider`, no API key, no token spend. Whatever the script
+`return`s is printed automatically as JSON. Because the saved script
+ends with `return page.extract(...)`, you get clean JSON on stdout:
+
+```sh copy
+lightpanda agent hn_login.js > stories.json
+```
+
+From inside the REPL, `/load hn_login.js` runs the same script against
+the current session.
+
+To reshape the output, assign the result and end with `return <value>`
+(what you return is what prints):
+
+```js copy
+const page = new Page();
+await page.goto("https://news.ycombinator.com");
+
+const topStories = page.extract({
+  topStories: [{
+    selector: ".athing",
+    fields: {
+      rank: ".rank",
+      title: ".titleline > a",
+      url: { selector: ".titleline > a", attr: "href" }
+    }
+  }]
+});
+
+return topStories;
+```
+
+## 6. Add your own JavaScript logic
+
+Agent scripts run in a separate JavaScript context from the page. No
+`window`, `document`, DOM API, `require`, or `process`. Browser
+interaction happens through the `Page` object: `new Page()` makes a
+page, `await page.goto(url)` navigates it, and every other primitive is
+a synchronous method on it.
+
+Use `page.extract(...)` to move page data into local logic, then
+process it with normal JavaScript:
+
+```js copy
+const page = new Page();
+await page.goto("https://news.ycombinator.com");
+
+const topStories = page.extract({
+  topStories: [{
+    selector: ".athing",
+    limit: 5,
+    fields: {
+      rank: ".rank",
+      title: ".titleline > a",
+      url: { selector: ".titleline > a", attr: "href" }
+    }
+  }]
+});
+
+return topStories.map((s) => ({ rank: s.rank, title: s.title, url: s.url }));
+```
+
+Use `page.evaluate(...)` only when you intentionally want a string to
+run in the page's JavaScript context. Page evaluate cannot see agent
+variables or call agent primitives.
+
+## 7. Use Lightpanda from another agent (MCP)
+
+If you're driving Lightpanda from a different agent (Claude Code, a
+custom MCP client, your own harness), use `lightpanda mcp` instead.
+The calling agent supplies the LLM, so Lightpanda needs no API key.
+
+```json copy
+{
+  "mcpServers": {
+    "lightpanda": {
+      "command": "/path/to/lightpanda",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Drive the browser with the usual tools (`goto`, `fill`, `click`,
+`waitForSelector`), then hand back a script with the `save` tool:
+
+```json
+{
+  "tool": "save",
+  "args": {
+    "path": "hn_login.js",
+    "script": "const page = new Page();\nawait page.goto(\"...\");\n..."
+  }
+}
+```
+
+The path must be relative and free of `..`. Literal `LP_*` values are
+scrubbed back to placeholders before the file is written. The output
+runs unmodified:
+
+```sh copy
+lightpanda agent hn_login.js
+```
+
+## Further reading
+
+- [Agent](/usage/agent): full documentation reference,
+- [PandaScript](/usage/pandascript): runtime, primitives,
+  return values.

From e9e8963396dbd255c3eb6f5d59279730a61a204b Mon Sep 17 00:00:00 2001
From: Pierre Tachoire <pierre@lightpanda.io>
Date: Tue, 16 Jun 2026 16:16:34 +0200
Subject: [PATCH 13/14] remove `./lightpanda` by `lightpanda`

---
 src/content/guides/configure-a-proxy.mdx   | 10 ++++-----
 src/content/guides/markdown-axtree.mdx     | 20 +++++++++---------
 src/content/run-locally/commands/agent.mdx |  2 +-
 src/content/run-locally/commands/fetch.mdx |  4 ++--
 src/content/run-locally/commands/mcp.mdx   |  2 +-
 src/content/run-locally/commands/serve.mdx |  2 +-
 src/content/usage/agent.mdx                | 16 +++++++--------
 src/content/usage/cdp/chromedp.mdx         |  2 +-
 src/content/usage/cdp/playwright.mdx       |  2 +-
 src/content/usage/cdp/puppeteer.mdx        |  2 +-
 src/content/usage/mcp.mdx                  |  2 +-
 src/content/usage/pandascript.mdx          | 24 +++++++++++-----------
 12 files changed, 44 insertions(+), 44 deletions(-)

diff --git a/src/content/guides/configure-a-proxy.mdx b/src/content/guides/configure-a-proxy.mdx
index 8adc0c9..a5b5b27 100644
--- a/src/content/guides/configure-a-proxy.mdx
+++ b/src/content/guides/configure-a-proxy.mdx
@@ -15,11 +15,11 @@ proxy. Ensure your proxy address starts with `http://` or `https://`.
 
 Use a local proxy with the `fetch` command:
 ```sh copy
-./lightpanda fetch --http-proxy http://127.0.0.1:3000 https://lightpanda.io
+lightpanda fetch --http-proxy http://127.0.0.1:3000 https://lightpanda.io
 ```
 Or configure the proxy with `serve` for the CDP server. All outgoing requests will use the proxy.
 ```sh copy
-./lightpanda serve --http-proxy http://127.0.0.1:3000
+lightpanda serve --http-proxy http://127.0.0.1:3000
 ```
 
 ### HTTP proxy with basic auth
@@ -30,7 +30,7 @@ for the proxy using the `username:password@` format in the proxy address. It
 works for both `fetch` and `serve` commands.
 
 ```sh copy
-./lightpanda fetch --http-proxy 'http://me:my-password@127.0.0.1:3000' https://lightpanda.io
+lightpanda fetch --http-proxy 'http://me:my-password@127.0.0.1:3000' https://lightpanda.io
 ```
 
 ### HTTP proxy with bearer auth
@@ -43,7 +43,7 @@ to authenticate with the `--proxy-bearer-token`. It works for both `fetch` and
 This option will add a `Proxy-Authorization` header all the outgoing requests.
 
 ```sh copy
-./lightpanda fetch --http-proxy 'http://127.0.0.1:3000' --proxy-bearer-token 'MY-TOKEN' https://lightpanda.io
+lightpanda fetch --http-proxy 'http://127.0.0.1:3000' --proxy-bearer-token 'MY-TOKEN' https://lightpanda.io
 ```
 
 ## Configure a proxy from your Puppeteer/Playwright script
@@ -57,7 +57,7 @@ With Puppeteer, you have to configure the proxy address when starting
 Lightpanda.
 
 ```sh copy
-./lightpanda fetch --http-proxy 'http://127.0.0.1:3000'
+lightpanda fetch --http-proxy 'http://127.0.0.1:3000'
 ```
 
 Then you can call `page.authenticate` function to inject your authentication
diff --git a/src/content/guides/markdown-axtree.mdx b/src/content/guides/markdown-axtree.mdx
index 4e66ddb..55260c1 100644
--- a/src/content/guides/markdown-axtree.mdx
+++ b/src/content/guides/markdown-axtree.mdx
@@ -54,7 +54,7 @@ lightpanda fetch --dump <format> [options] <URL>
 ### Basic example
 
 ```sh copy
-./lightpanda fetch --dump markdown https://example.com
+lightpanda fetch --dump markdown https://example.com
 ```
 
 <details>
@@ -76,10 +76,10 @@ Includes rendered iframe content in the output. Without it, iframe content is ex
 
 ```sh copy
 # Without iframe content (default)
-./lightpanda fetch --dump markdown https://example.com
+lightpanda fetch --dump markdown https://example.com
 
 # With iframe content included
-./lightpanda fetch --dump markdown --with-frames https://example.com
+lightpanda fetch --dump markdown --with-frames https://example.com
 ```
 
 On pages without iframes, output is identical either way.
@@ -90,10 +90,10 @@ Removes groups of tags from the output. Values can be combined with commas:
 
 ```sh copy
 # Remove JavaScript and CSS from output
-./lightpanda fetch --dump html --strip-mode js,css https://example.com
+lightpanda fetch --dump html --strip-mode js,css https://example.com
 
 # Remove all UI, scripts and styles
-./lightpanda fetch --dump html --strip-mode full https://example.com
+lightpanda fetch --dump html --strip-mode full https://example.com
 ```
 
 | Value | Tags removed |
@@ -108,7 +108,7 @@ Removes groups of tags from the output. Values can be combined with commas:
 The `semantic_tree` format returns the page's accessibility tree as structured JSON:
 
 ```sh copy
-./lightpanda fetch --dump semantic_tree https://example.com
+lightpanda fetch --dump semantic_tree https://example.com
 ```
 
 Each node includes:
@@ -156,7 +156,7 @@ Each node includes:
 The `semantic_tree_text` format outputs the same data in a compact readable form:
 
 ```sh copy
-./lightpanda fetch --dump semantic_tree_text https://example.com
+lightpanda fetch --dump semantic_tree_text https://example.com
 ```
 
 <details>
@@ -187,10 +187,10 @@ Unlike `--dump markdown` which processes a URL from scratch, `LP.getMarkdown` co
 
 ```sh copy
 # Start CDP server (default: ws://127.0.0.1:9222)
-./lightpanda serve
+lightpanda serve
 
 # Custom host and port
-./lightpanda serve --host 0.0.0.0 --port 9333
+lightpanda serve --host 0.0.0.0 --port 9333
 
 # Verify it's running
 curl http://127.0.0.1:9222/json/version
@@ -319,7 +319,7 @@ For `example.com`, the CDP accessibility tree contains **12 nodes**.
 Lightpanda includes a built-in MCP (Model Context Protocol) server for direct integration with AI tools and LLM frameworks.
 
 ```sh copy
-./lightpanda mcp
+lightpanda mcp
 ```
 
 The MCP server exposes `markdown` and `semantic_tree` tools.
diff --git a/src/content/run-locally/commands/agent.mdx b/src/content/run-locally/commands/agent.mdx
index 78f5aa6..fc4c4f9 100644
--- a/src/content/run-locally/commands/agent.mdx
+++ b/src/content/run-locally/commands/agent.mdx
@@ -8,7 +8,7 @@ description: Starts an MCP (Model Context Protocol) server over stdio
 Start Lightpanda as an interactive AI agent that can browse the web.
 
 ```sh copy
-./lightpanda agent
+lightpanda agent
 ```
 
 ## Options
diff --git a/src/content/run-locally/commands/fetch.mdx b/src/content/run-locally/commands/fetch.mdx
index 01c909a..aaf455e 100644
--- a/src/content/run-locally/commands/fetch.mdx
+++ b/src/content/run-locally/commands/fetch.mdx
@@ -5,10 +5,10 @@ description: Fetch a webpage and dump its content using the Lightpanda CLI.
 
 # Fetch
 
-Use `./lightpanda help` for all options.
+Use `lightpanda help` for all options.
 
 ```sh copy
-./lightpanda fetch --obey-robots --dump html https://demo-browser.lightpanda.io/campfire-commerce/
+lightpanda fetch --obey-robots --dump html https://demo-browser.lightpanda.io/campfire-commerce/
 ```
 ```sh
 INFO  http : navigate . . . . . . . . . . . . . . . . . . . . [+0ms]
diff --git a/src/content/run-locally/commands/mcp.mdx b/src/content/run-locally/commands/mcp.mdx
index e33133f..f53113c 100644
--- a/src/content/run-locally/commands/mcp.mdx
+++ b/src/content/run-locally/commands/mcp.mdx
@@ -8,7 +8,7 @@ description: Starts an MCP (Model Context Protocol) server over stdio
 Start Lightpanda as a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server over stdio to control it with LLMs.
 
 ```sh copy
-./lightpanda mcp
+lightpanda mcp
 ```
 
 ## Options
diff --git a/src/content/run-locally/commands/serve.mdx b/src/content/run-locally/commands/serve.mdx
index 826dc68..f9e2087 100644
--- a/src/content/run-locally/commands/serve.mdx
+++ b/src/content/run-locally/commands/serve.mdx
@@ -8,7 +8,7 @@ description: Start Lightpanda as a local CDP server.
 Start Lightpanda as a [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) (CDP) server to control it with clients like [Puppeteer](https://pptr.dev/), [Playwright](https://playwright.dev/) or [Chromedp](https://github.com/chromedp/chromedp).
 
 ```sh copy
-./lightpanda serve --obey-robots --host 127.0.0.1 --port 9222
+lightpanda serve --obey-robots --host 127.0.0.1 --port 9222
 ```
 ```sh
 INFO  app : server running . . . . . . . . . . . . . . . . .  [+0ms]
diff --git a/src/content/usage/agent.mdx b/src/content/usage/agent.mdx
index 90eda04..0e455c3 100644
--- a/src/content/usage/agent.mdx
+++ b/src/content/usage/agent.mdx
@@ -46,7 +46,7 @@ lightpanda agent
 
 Tell it what you want:
 
-```sh copy
+```console
 ❯ go to news.ycombinator.com and get me the top story title and points
 ```
 
@@ -54,14 +54,14 @@ The agent navigates, extracts, prints the answer.
 
 You can also use commands:
 
-```sh copy
+```console
 ❯ /goto news.ycombinator.com
 ❯ /links # This will print all the HTML links on the current webpage
 ```
 
 You can generate a reproducible [PandaScript](/usage/pandascript) from your current session:
 
-```sh copy
+```console
 ❯ /save <my_script>.js
 ```
 
@@ -228,7 +228,7 @@ All three require an LLM. `--no-llm` rejects them.
   to `!` with a "JS mode - esc to exit" ghost hint. Handy for poking at
   a page without wrapping every line in `/evaluate`:
 
-  ```
+  ```console
   ❯ !
   ! document.title
   "Hacker News"
@@ -249,8 +249,8 @@ All three require an LLM. `--no-llm` rejects them.
 
 ## One-shot mode (`--task`)
 
-```console
-./lightpanda agent --provider gemini \
+```sh copy
+lightpanda agent --provider gemini \
   --task "what is the top story on news.ycombinator.com?"
 ```
 
@@ -262,8 +262,8 @@ Combine with `-a <path>` / `--attach <path>` (repeatable) to feed
 local files to providers that accept attachments. For example, a list of
 items to look up, or a document to cross-check against a live page:
 
-```console
-./lightpanda agent -a invoice.pdf \
+```sh copy
+lightpanda agent -a invoice.pdf \
   --task "open shop.example.com/orders/1042 and check the order total matches the attached invoice"
 ```
 
diff --git a/src/content/usage/cdp/chromedp.mdx b/src/content/usage/cdp/chromedp.mdx
index 87a2a2b..78c215f 100644
--- a/src/content/usage/cdp/chromedp.mdx
+++ b/src/content/usage/cdp/chromedp.mdx
@@ -15,7 +15,7 @@ More examples in [demo/chromedp](https://github.com/lightpanda-io/demo/tree/main
 Start Lightpanda as a local CDP server (see [serve command](/run-locally/commands/serve) for all options):
 
 ```sh copy
-./lightpanda serve --host 127.0.0.1 --port 9222
+lightpanda serve --host 127.0.0.1 --port 9222
 ```
 
 Connect Chromedp using `NewRemoteAllocator`:
diff --git a/src/content/usage/cdp/playwright.mdx b/src/content/usage/cdp/playwright.mdx
index 0aa2362..a214173 100644
--- a/src/content/usage/cdp/playwright.mdx
+++ b/src/content/usage/cdp/playwright.mdx
@@ -15,7 +15,7 @@ More examples in [demo/playwright](https://github.com/lightpanda-io/demo/tree/ma
 Start Lightpanda as a local CDP server (see [serve command](/run-locally/commands/serve) for all options):
 
 ```sh copy
-./lightpanda serve --host 127.0.0.1 --port 9222
+lightpanda serve --host 127.0.0.1 --port 9222
 ```
 
 Connect Playwright using `chromium.connectOverCDP`:
diff --git a/src/content/usage/cdp/puppeteer.mdx b/src/content/usage/cdp/puppeteer.mdx
index d9cda8b..c0725db 100644
--- a/src/content/usage/cdp/puppeteer.mdx
+++ b/src/content/usage/cdp/puppeteer.mdx
@@ -15,7 +15,7 @@ More examples in [demo/puppeteer](https://github.com/lightpanda-io/demo/tree/mai
 Start Lightpanda as a local CDP server (see [serve command](/run-locally/commands/serve) for all options):
 
 ```sh copy
-./lightpanda serve --host 127.0.0.1 --port 9222
+lightpanda serve --host 127.0.0.1 --port 9222
 ```
 
 Connect Puppeteer using `browserWSEndpoint` — the WebSocket URL Puppeteer uses to attach to an already-running browser instead of launching one itself:
diff --git a/src/content/usage/mcp.mdx b/src/content/usage/mcp.mdx
index 18be7c5..287477d 100644
--- a/src/content/usage/mcp.mdx
+++ b/src/content/usage/mcp.mdx
@@ -15,7 +15,7 @@ Use Lightpanda via the [Model Context Protocol](https://modelcontextprotocol.io)
 Start the MCP server:
 
 ```sh copy
-./lightpanda mcp
+lightpanda mcp
 ```
 
 Find reference of [MCP command options](/run-locally/commands/mcp).
diff --git a/src/content/usage/pandascript.mdx b/src/content/usage/pandascript.mdx
index e069826..6fc3bda 100644
--- a/src/content/usage/pandascript.mdx
+++ b/src/content/usage/pandascript.mdx
@@ -69,7 +69,7 @@ JavaScript value, so local script logic can use it directly. The result mirrors
 your schema: an object schema returns an object keyed by your fields (even with
 a single field), and a bare array schema returns an array:
 
-```js
+```js copy
 const page = new Page();
 await page.goto("https://news.ycombinator.com/");
 
@@ -90,7 +90,7 @@ data; // printed automatically as JSON
 
 Destructure when a single field is all you need:
 
-```js
+```js copy
 const { stories } = page.extract({
   stories: [{
     selector: "tr.athing",
@@ -164,7 +164,7 @@ script.
 
 Use `goto(...)` to navigate to an URL:
 
-```js
+```js copy
 const page = new Page();
 await page.goto("https://example.com");
 
@@ -186,7 +186,7 @@ Use `page.extract(...)` to read data from the current page without writing page-
 JavaScript. This is the preferred bridge from page content into local agent
 logic.
 
-```js
+```js copy
 const result = page.extract({
   heading: "h1",
   links: [{
@@ -238,7 +238,7 @@ example](#complete-example) below.
 When passing an object directly to `extract(...)`, the runtime serializes it as
 the extractor schema. These forms are equivalent:
 
-```js
+```js copy
 page.extract({ title: "h1" });
 page.extract({ schema: { title: "h1" } });
 page.extract('{ "title": "h1" }');
@@ -250,7 +250,7 @@ results in local variables instead.
 
 Use local variables to keep extracted data available to later script logic:
 
-```js
+```js copy
 const data = page.extract({ title: "title" });
 ```
 
@@ -259,7 +259,7 @@ const data = page.extract({ title: "title" });
 `evaluate(...)` is the explicit escape hatch into the current page's JavaScript
 context. Its script string runs where `window` and `document` exist.
 
-```js
+```js copy
 await page.goto("https://example.com");
 
 const title = page.evaluate("document.title");
@@ -268,7 +268,7 @@ console.log(title);
 
 Keep the boundary clear:
 
-```js
+```js copy
 const selector = "h1";
 
 // Good: local agent logic builds an extract schema.
@@ -286,7 +286,7 @@ cannot express.
 `waitForScript(...)` also evaluates in the page context, repeatedly, until the
 expression is truthy or the timeout expires:
 
-```js
+```js copy
 page.waitForScript("document.querySelectorAll('.row').length >= 5");
 ```
 
@@ -295,7 +295,7 @@ page.waitForScript("document.querySelectorAll('.row').length >= 5");
 The action primitives operate on the current page. Most take one object whose
 fields match the browser tool schema:
 
-```js
+```js copy
 page.click({ selector: "a.login" });
 page.fill({ selector: "input[name='acct']", value: "$LP_HN_USERNAME" });
 page.fill({ selector: "input[name='pw']", value: "$LP_HN_PASSWORD" });
@@ -327,7 +327,7 @@ recordings, resolved `LP_*` values are scrubbed back to placeholders.
 
 Primitive failures throw JavaScript exceptions:
 
-```js
+```js copy
 try {
   page.waitForSelector({ selector: "#dashboard", timeout: 1000 });
 } catch (err) {
@@ -352,7 +352,7 @@ This script opens Hacker News, extracts five stories, visits each comments
 page, and prints one JSON object. The looping and object assembly happen in
 the local agent script, not in the page.
 
-```js
+```js copy
 const HN = "https://news.ycombinator.com";
 
 const page = new Page();

From 710d36c4f0221848400ffc0eec03f701f9ce9c2d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adri=C3=A0=20Arrufat?= <adria.arrufat@gmail.com>
Date: Tue, 16 Jun 2026 16:06:37 +0200
Subject: [PATCH 14/14] agent: document huggingface and --effort options

Updates the agent command documentation to include Hugging Face as a
provider, the HF_TOKEN environment variable, and the new --effort
option.
---
 src/content/run-locally/commands/agent.mdx | 27 +++++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/src/content/run-locally/commands/agent.mdx b/src/content/run-locally/commands/agent.mdx
index fc4c4f9..44a54c3 100644
--- a/src/content/run-locally/commands/agent.mdx
+++ b/src/content/run-locally/commands/agent.mdx
@@ -28,7 +28,8 @@ Options:
 --provider <PROVIDER>      The AI provider.
                            When omitted, lightpanda auto-detects an API key
                            from your environment (ANTHROPIC_API_KEY,
-                           OPENAI_API_KEY, GOOGLE_API_KEY/GEMINI_API_KEY).
+                           OPENAI_API_KEY, GOOGLE_API_KEY/GEMINI_API_KEY,
+                           HF_TOKEN).
                            With exactly one key set: that provider is used.
                            With multiple keys on a TTY: you'll be prompted
                            to pick; in non-interactive contexts, pass
@@ -37,8 +38,12 @@ Options:
                            natural-language input, no LOGIN /
                            ACCEPT_COOKIES keywords).
 
+                           ollama is never auto-detected (it needs no key);
+                           select it explicitly with --provider ollama.
+
                            Allowed values:
-                             "anthropic", "openai", "gemini", "ollama".
+                             "anthropic", "openai", "gemini",
+                             "huggingface", "ollama".
                            In the REPL, use /provider to list and change
                            providers.
 
@@ -56,6 +61,9 @@ Options:
 --base-url <URL>           Override the API base URL for the provider.
                            Defaults to the provider's standard endpoint.
                            Ollama default: http://localhost:11434/v1.
+                           Hugging Face default is the serverless router
+                           (https://router.huggingface.co/v1); point this
+                           at a dedicated Inference Endpoint to use one.
 
 --system-prompt <STRING>   Override the default system prompt.
 
@@ -87,8 +95,21 @@ Options:
                              high    + the matching `[result: ...]` body
                                      (required by the benchmarks harness).
 
+--effort <LEVEL>           Per-turn reasoning budget, mapped to each
+                           provider's native thinking/reasoning knob.
+                           Default: low in the REPL (snappy turns),
+                           medium in one-shot --task mode. In the REPL,
+                           use /effort to change it.
+
+                           Allowed values:
+                             none, minimal, low, medium, high, xhigh.
+
+The provider, model, effort, and verbosity you choose in the REPL are
+remembered per-directory in .lp-agent.zon and reused on the next run.
+
 API keys are read from the environment: ANTHROPIC_API_KEY, OPENAI_API_KEY,
-or GOOGLE_API_KEY/GEMINI_API_KEY. Ollama does not require an API key.
+GOOGLE_API_KEY/GEMINI_API_KEY, or HF_TOKEN. Ollama does not require an API
+key.
 
 common options:
   --insecure-disable-tls-host-verification