docs(browser): teach the eval-js output contract and piping

[giordano-lucas]

Why

nottelabs/notte-cli#72 (merged) changed what notte page eval-js prints: the evaluated value now lands alone on stdout (objects/arrays as JSON, a JS null as null) with the status line on stderr, and a failing script exits non-zero with the actual JavaScript error instead of the generic user-facing sentence.

That makes eval-js composable, which matters more for a skill than for docs — the agent can now chain it instead of reading a banner and a Result: prefix.

What

In notte-browser/SKILL.md, where eval-js is taught:

• State the output contract (value alone on stdout, status on stderr, -o json for the full envelope).
• Show both shell shapes:

  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

• Recommend returning JSON.stringify(...) for structured answers so jq filters locally instead of costing another round trip through the page.
• Note that failures exit non-zero with the real JS error, so set -e and || fallbacks behave.
• Correct a stale line: "Don't use logging - stdout is not captured" → what's discarded is console.log; the returned value is exactly what stdout carries now.

In notte-functions-build/references/exploration.md, add the same piping note to the endpoint-verification flow, which drives eval-js.

Verification

python3 scripts/validate-plugins.py → 37 checks, no problems. Both taught commands were run against staging with a CLI built from notte-cli main: title=$(...) captured Example Domain, and the JSON.stringify(...) | jq length pipe returned a count.

Gate

None for the CLI teaching — notte-cli#72 is merged; it applies once a CLI release ships. (The session.evaluate_js mapping added in #39 still waits on the SDK release, unchanged here.)

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR documents the revised notte page eval-js output contract and teaches direct shell capture and jq piping.

• Clarifies stdout, stderr, JSON-envelope, and JavaScript failure behavior.
• Adds command-substitution and structured-output pipeline examples.
• Extends the same piping guidance to Function endpoint exploration.

Confidence Score: 4/5

The documentation-only PR appears safe to merge, with the non-blocking concern that its exact CLI output contract has no automated regression coverage.

The changed guidance is internally consistent and the only accepted concern is missing test coverage for stream-sensitive shell examples.

Files Needing Attention: plugins/notte/skills/notte-browser/SKILL.md; plugins/notte/skills/notte-functions-build/references/exploration.md

Important Files Changed

Filename	Overview
plugins/notte/skills/notte-browser/SKILL.md	Documents the composable eval-js output contract and shell examples, but adds no automated regression coverage.
plugins/notte/skills/notte-functions-build/references/exploration.md	Adds direct jq-piping and command-substitution guidance without automated coverage.

Prompt To Fix All With AI

### Issue 1
plugins/notte/skills/notte-browser/SKILL.md:290-296
**Output contract lacks regression coverage**

These stream-sensitive examples depend on exact stdout, stderr, JSON, and exit-status behavior, but this PR adds no unit or integration test to keep the documentation aligned with the CLI contract as it changes.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "docs(browser): teach the eval-js output ..." | Re-trigger Greptile}