docs(readme): document page eval-js and its output contract

[giordano-lucas]

Why

page eval-js was missing from the README's Page Actions list entirely — the command existed but was never documented there. And after #72 its output is worth explaining: the evaluated value now prints alone on stdout with the status line on stderr, which makes it composable in a shell.

What

• Add notte page eval-js to the Page Actions command list.
• New short "Evaluating JavaScript" section covering the contract: value alone on stdout (objects/arrays as JSON, a JS null as null), status on stderr, console.log discarded, failures exit non-zero with the actual JavaScript error, -o json for the full execution result — with the two shapes users actually want:

title=$(notte page eval-js "document.title")

notte page eval-js "JSON.stringify([...document.querySelectorAll('a')].map(a => a.href))" | jq length

Verification

Both examples were run verbatim against a live staging session with a CLI built from main: the capture returned Example Domain, the jq pipe returned a count.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

The PR documents page eval-js and its shell-oriented output contract.

• Adds eval-js to the Page Actions command list.
• Documents bare stdout values, stderr status output, structured values, JavaScript errors, and full JSON-envelope output.
• The failure wording does not distinguish JSON mode’s zero-exit success:false behavior, and no automated coverage is added for the documented contract.

Confidence Score: 4/5

The documentation-only PR appears safe to merge, but its JSON-mode failure wording should be clarified and the newly documented contract should receive automated coverage.

The command and examples are documented accurately for successful text and JSON output, while the failure statement overlooks JSON mode’s zero exit with a success:false envelope and the contract remains untested.

Files Needing Attention: README.md

Important Files Changed

Filename	Overview
README.md	Adds useful eval-js documentation, but overgeneralizes the non-zero failure contract to JSON mode and adds no automated contract coverage.

Comments Outside Diff (1)

1. README.md, line 169-170 (link)

   Clarify JSON failure exit behavior

   The non-zero exit guarantee applies to text mode, while -o json returns the full envelope before checking success and therefore exits zero for JavaScript failures. Without this distinction, shell automation can rely on the documented exit status and treat a success:false result as successful.

   Knowledge Base Used:

   • Output, validation, and errors
   • CLI runtime experience
   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: README.md
   Line: 169-170
   
   Comment:
   **Clarify JSON failure exit behavior**
   
   The non-zero exit guarantee applies to text mode, while `-o json` returns the full envelope before checking `success` and therefore exits zero for JavaScript failures. Without this distinction, shell automation can rely on the documented exit status and treat a `success:false` result as successful.
   
   **Knowledge Base Used:**
   - [Output, validation, and errors](https://app.greptile.com/nottelabs/-/custom-context/knowledge-base/nottelabs/notte-cli/-/docs/output-validation-and-errors.md)
   - [CLI runtime experience](https://app.greptile.com/nottelabs/-/custom-context/knowledge-base/nottelabs/notte-cli/-/docs/runtime-experience.md)
   
   ---
   
   For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

   

Prompt To Fix All With AI

### Issue 1
README.md:169-170
**Clarify JSON failure exit behavior**

The non-zero exit guarantee applies to text mode, while `-o json` returns the full envelope before checking `success` and therefore exits zero for JavaScript failures. Without this distinction, shell automation can rely on the documented exit status and treat a `success:false` result as successful.

### Issue 2
README.md:160-170
**Add output contract coverage**

This change documents concrete guarantees for serialization, stream separation, discarded logging, and failure handling without adding an automated test. A focused integration test would prevent these shell-facing guarantees from drifting unnoticed.

---

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

_{Reviews (1): Last reviewed commit: "docs(readme): document page eval-js and ..." | Re-trigger Greptile}