From e7d65ab249bed10cebf1346efc9f6830c8eb4bbc Mon Sep 17 00:00:00 2001
From: Lucas Giordano <giordano3102lucas@gmail.com>
Date: Tue, 25 Aug 2026 19:54:44 +0200
Subject: [PATCH] docs(browser): teach the eval-js output contract and piping

notte-cli#72 prints the evaluated value alone on stdout with the status
line on stderr, so eval-js is now composable: the agent can capture it
with $(...) or pipe it into jq instead of reading a banner and a
"Result:" prefix. Say that where eval-js is taught, show both shapes,
and recommend returning JSON.stringify(...) for structured answers so
jq filters locally rather than costing another round trip through the
page. Also correct the old "stdout is not captured" line - what is
discarded is console.log, not the returned value - and note that a
failing script now exits non-zero with the actual JavaScript error.

The same piping note goes on the functions-build exploration flow,
which drives eval-js to verify discovered endpoints.

Verified against staging: title=$(notte page eval-js 'document.title')
captures "Example Domain" and the JSON.stringify example pipes into jq.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 plugins/notte/skills/notte-browser/SKILL.md    | 18 +++++++++++++++++-
 .../references/exploration.md                  |  4 ++++
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/plugins/notte/skills/notte-browser/SKILL.md b/plugins/notte/skills/notte-browser/SKILL.md
index 1f5879d..dd607e1 100644
--- a/plugins/notte/skills/notte-browser/SKILL.md
+++ b/plugins/notte/skills/notte-browser/SKILL.md
@@ -285,8 +285,14 @@ notte page upload --session-id <session-id> "#file-input" --file report.pdf
 **Run JavaScript in the page:**
 
 - Escape single quotes if needed.
-- Don't use logging - stdout is not captured.
+- `console.log` output is discarded - only the returned value comes back.
 - Use a single expression, or a function that returns a value.
+- **The returned value is printed alone on stdout** (objects and arrays as JSON,
+  a JS `null` as `null`), with the status line on stderr - so it captures into a
+  shell variable and pipes without post-processing. Use `-o json` when you want
+  the whole execution result instead.
+- A failing script exits non-zero and reports the actual JavaScript error, so
+  `set -e` and `||` fallbacks behave.
 
 ```bash
 # Single expression
@@ -299,8 +305,18 @@ notte page eval-js --session-id <session-id> '
   return els.length;
 }
 '
+
+# Capture the value, or pipe it - the value is all stdout carries
+title=$(notte page eval-js --session-id <session-id> 'document.title')
+
+notte page eval-js --session-id <session-id> \
+  'JSON.stringify([...document.querySelectorAll("a")].map(a => a.href))' | jq length
 ```
 
+Return `JSON.stringify(...)` whenever the answer is structured: it arrives as a
+JSON document, so `jq` does the filtering instead of another round trip through
+the page.
+
 **Navigation:**
 ```bash
 notte page goto --session-id <session-id> "https://example.com"
diff --git a/plugins/notte/skills/notte-functions-build/references/exploration.md b/plugins/notte/skills/notte-functions-build/references/exploration.md
index 90d3df8..ff7a8bc 100644
--- a/plugins/notte/skills/notte-functions-build/references/exploration.md
+++ b/plugins/notte/skills/notte-functions-build/references/exploration.md
@@ -51,6 +51,10 @@ async () => {
 '
 ```
 
+The evaluated value is all stdout carries, so pipe it straight into `jq` while
+exploring - `... | jq '.count'` - and capture it with `$(...)` when a later
+command needs it.
+
 Inside a deployed Function the equivalent is `session.evaluate_js(code)`, which returns the evaluated string directly (objects and arrays as JSON) and raises with the actual JavaScript error on failure — so `json.loads(session.evaluate_js(code))` is the whole read.
 
 If the endpoint returns the data reliably, that is your path. Note it and move to generation.