@nothumanwork/sauron 0.2.1 → 0.2.3

package/README.md

@@ -7,8 +7,9 @@ This is a rewrite of the attached Bun/TypeScript `sauron` project as a compiled
 ## Goals
 
 - **Agent-friendly** JSON output for all commands (v2 envelope)
+- **Task-first UX** for everyday browser commands (`open`, `snapshot`, `click`, `fill`, `wait`, `get`)
 - **Fast** startup and execution (single static-ish binary)
-- **Process-safe concurrency** with mandatory runtime sessions (`start` before browser commands)
+- **Process-safe concurrency** with runtime sessions, plus controlled auto-runtime on flat commands
 - **Per-session isolation** with generated `session_id`, `instance`, and `client` IDs by default
 - Filesystem-only runtime state storage under `~/.sauron/runtime/`
 - Uses Chrome **`--headless=new`** only (opinionated headless runtime)
@@ -72,38 +73,54 @@ The `sauron` launcher inside the package selects the matching binary for the cur
 
 ## Quick start
 
-Each shell/process must start a runtime session first:
+Use the flat surface directly (auto-runtime defaults to `auto` on flat commands):
 
 ```bash
-sauron runtime start
+sauron open https://example.com
+sauron snapshot -i
+sauron get title
+sauron click @e2
+sauron wait --load networkidle
+sauron screenshot --annotate --artifact-mode manifest
 ```
 
-macOS defaults to GPU + WebGL on `runtime start` (opt out with `--no-webgl --no-gpu`).
+To inspect resolved config and precedence:
+
+```bash
+sauron config show
+```
+
+`sauron` supports config layering:
+
+- `~/.sauron/config.json`
+- `./sauron.json`
+- environment variables
+- CLI flags
+
+Precedence is: `user config < project config < env < CLI`.
 
-Then run browser commands from the same project directory:
+To force explicit runtime behavior on flat commands:
 
 ```bash
-sauron page goto https://example.com
-sauron page snapshot --format json
-sauron input click --ref @e1
-sauron page screenshot --responsive --quality medium
+sauron --ensure-runtime require open https://example.com
+sauron --ensure-runtime off open https://example.com
 ```
 
-Clean up with:
+To stop the active runtime when finished:
 
 ```bash
 sauron runtime stop
 ```
 
-## Mandatory session lifecycle
+## Legacy Grouped Surface
 
-- Non-`runtime start` commands require an active runtime session.
+- Most non-`runtime start` commands require an active runtime session. `runtime status` is the exception: it can also report `stopped` when no active session exists.
 - Session resolution order is:
   - explicit `--session-id`
   - current process binding
   - current project binding
   - `SAURON_SESSION_ID` fallback
-- If none resolve to an active session, commands fail with `SESSION_REQUIRED`.
+- If none resolve to an active session, commands that need one fail with `SESSION_REQUIRED`.
 - `start` auto-generates:
   - `session_id` (`sess-...`)
   - `instance` (`inst-...`)
@@ -114,6 +131,15 @@ sauron runtime stop
 sauron --session-id mysession --instance work --client alice runtime start
 ```
 
+Grouped command examples remain valid and stable:
+
+```bash
+sauron page goto https://example.com
+sauron page snapshot --format nodes
+sauron input click --ref @e1
+sauron state show baseline
+```
+
 ## Interaction Flow
 
 ```mermaid
@@ -179,6 +205,7 @@ unset SAURON_SESSION_ID
 ## Runtime state
 
 Runtime session state is stored on the local filesystem under `~/.sauron/runtime/`.
+After `runtime stop` or `runtime cleanup`, `sauron runtime status` reports `stopped`.
 
 ## Session logs
 
@@ -190,10 +217,11 @@ Each line includes timestamp, session metadata, command name, status, and error
 
 ## CLI flag placement
 
-Global flags (`--session-id`, `--port`, etc.) must be placed before the subcommand:
+Global flags (`--session-id`/`--session`, `--port`, `--policy`, `--artifact-mode`, etc.) must be placed before the subcommand:
 
 ```bash
 sauron --session-id mysession page goto https://example.com
+sauron --session qa open https://example.com
 ```
 
 `--viewport` is global and applies to `start` and browser commands:
@@ -203,6 +231,12 @@ sauron --viewport 1440x900 runtime start
 sauron --viewport 390x844 page screenshot
 ```
 
+`--profile` is a higher-level alias for browser profile persistence:
+
+```bash
+sauron --profile ./profiles/qa runtime start
+```
+
 ## Output contract
 
 All commands return exactly one JSON object in a unified v2 envelope:
@@ -236,6 +270,17 @@ All commands return exactly one JSON object in a unified v2 envelope:
 }
 ```
 
+## Scorecard and Benchmarks
+
+Run the parity benchmark harness:
+
+```bash
+cargo build --release
+BENCH_RUNS=5 scripts/benchmark-matrix.sh
+```
+
+Latest comparison document: [docs/agent-browser-scorecard.md](/Users/mish/dev/sauron/docs/agent-browser-scorecard.md)
+
 ## Notes
 
 - You need a local Chrome/Chromium install.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nothumanwork/sauron",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Rust-native CLI for controlling Chrome via CDP",
   "license": "MIT",
   "homepage": "https://github.com/thehumanworks/sauron#readme",