diff --git a/CHANGELOG.md b/CHANGELOG.md
index 53924d4..fefba3d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,20 @@
 # Changelog
 
+## Unreleased
+
+Bug fixes from a review of 0.1.3. No new commands; two behaviour changes are marked.
+
+- **Retries are safe.** A connection that drops after the request was sent now exits 12 ("may have run and been billed"), not 10 ("nothing was sent, safe to retry"). A gateway 5xx without an API problem document is retried only for GET/HEAD, and is no longer mistaken for the target's status under `--original-status`. A 301/302/303 on a POST is an error naming the Location instead of a silent GET. `Retry-After` waits are capped at 60 s and announced on stderr.
+- **Ctrl-C exits 130** with "interrupted", including while `scrape -` waits on stdin. A mistyped subcommand (`spicrawl batch wiat`) is a usage error with a suggestion, not help and exit 0.
+- **Keys:** a trailing CR/LF or space on the key (flag, env or file) is trimmed. The config file is written via a private temp file, short keys are fully masked, and commands that get the key and base URL from flags work without `$HOME`.
+- **scrape:** `--body null` is a usage error, not a panic (also `batch submit`). Big integers survive `--json` (**key order now follows the API**, as `--jsonl` already did). Stdout write errors stop the run instead of exiting 0. `-o` writes atomically and **a target error page no longer overwrites the file**. `-o -` means stdout. Screenshot labels never overwrite each other. `--body` merges deeply. A BOM on stdin is stripped. Human output no longer HTML-escapes `<>&`. The multi-URL summary counts correctly. `--impersonate` help says it is on by default.
+- **batch:** `wait` and `submit --wait` exit 4 when the job failed or was cancelled. Polling survives transient 5xx and network errors. `results -o` no longer empties an existing file on failure.
+- **browser:** a server without the cloud browser says so (exit 8) instead of `NOT_FOUND`. `$(spicrawl browser url -q)` yields the bare URL.
+- **usage summary** shows the enforced monthly allowance. **status** fails when the key check cannot reach the API.
+- **mcp install / init** back up the client config to `.bak`, write through symlinks, refuse to replace a customised `spicrawl` entry without `--force`, and accept VS Code JSONC/BOM `mcp.json`.
+- **Docs:** the embedded skill, `openapi.yaml` and schemas are synced with the API (cache hits are billed, `impersonate` defaults to true, batch honours `--format`).
+- **install.sh** accepts `SPICRAWL_VERSION=0.1.3` as well as `v0.1.3` and explains a failed download. The npm launcher forwards Ctrl-C to the binary.
+
 ## 0.1.3 — 2026-10-05
 
 - The repository and Go module moved to `github.com/OfficialSpicrawl/cli`. Install from source with `go install github.com/OfficialSpicrawl/cli/cmd/spicrawl@latest`.
diff --git a/DESIGN.md b/DESIGN.md
index 0167139..669f814 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -129,7 +129,7 @@ spicrawl batch list [--status S] [--limit N]
 spicrawl batch get <id>
 spicrawl batch results <id> [--status S] [--all] [-o FILE]   JSONL
 spicrawl batch content <id> <seq> [-o FILE]                   one item's document
-spicrawl batch wait <id> [--max-wait 30m]                     exit 11 when it gives up
+spicrawl batch wait <id> [--max-wait 30m]                     exit 11 when it gives up, 4 if failed/cancelled
 spicrawl batch cancel <id> [--yes]                           --yes required without a TTY
 spicrawl batch retry|close <id>
 spicrawl batch append <id> <file|->
diff --git a/README.md b/README.md
index 0271aa4..7f84a46 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Spicrawl CLI: scrape websites to Markdown and JSON from the terminal
 
-The Spicrawl CLI is a command-line web scraper that turns any URL into Markdown, HTML, text or JSON, batch-scrapes up to 10,000 URLs per job, and connects Claude Code, Cursor, Codex and VS Code to Spicrawl over MCP, with JSON output and 13 stable exit codes for shell scripts, CI and AI agents.
+The Spicrawl CLI is a command-line web scraper that turns any URL into Markdown, HTML, text or JSON, batch-scrapes up to 10,000 URLs per job, and connects Claude Code, Cursor, Codex and VS Code to Spicrawl over MCP, with JSON output and 14 stable exit codes for shell scripts, CI and AI agents.
 
 [![npm version](https://img.shields.io/npm/v/@spicrawl/cli.svg)](https://www.npmjs.com/package/@spicrawl/cli)
 [![npm downloads](https://img.shields.io/npm/dm/@spicrawl/cli.svg)](https://www.npmjs.com/package/@spicrawl/cli)
@@ -50,7 +50,7 @@ The result is one JSON object with the page under `content`:
 - **Parallel scrapes from stdin.** `spicrawl scrape -` reads one URL per line and runs 4 requests at once by default (`--concurrency`), with every scrape flag available.
 - **Structured data without a model.** `--extract` (CSS selectors), `--autoparse` (JSON-LD, OpenGraph) and `--links`.
 - **One-command agent setup.** `spicrawl init` configures 4 clients (Claude Code, Cursor, VS Code and Codex) for the hosted MCP server and installs the agent skill.
-- **13 stable exit codes (0 to 12).** Each maps to an error class an agent can branch on; codes are never renumbered, only added.
+- **14 stable exit codes (0 to 12, and 130).** Each maps to an error class an agent can branch on; codes are never renumbered, only added.
 - **Offline request schemas.** `spicrawl schema` prints 4 JSON Schemas (`scrape`, `batch`, `batch-item`, `session`) from inside the binary.
 - **6 platforms.** Linux, macOS and Windows on x64 and arm64, built with GoReleaser.
 
@@ -71,7 +71,7 @@ npx @spicrawl/cli --help       # or run it without installing
 curl -fsSL https://raw.githubusercontent.com/OfficialSpicrawl/cli/main/install.sh | sh
 ```
 
-It downloads the archive for your OS and CPU from the latest GitHub release, checks its SHA-256 against `checksums.txt`, and installs `spicrawl` into `~/.local/bin` (`SPICRAWL_INSTALL_DIR` changes it; `SPICRAWL_VERSION=v0.1.3` pins a release). It never prompts and never uses `sudo`.
+It downloads the archive for your OS and CPU from the latest GitHub release, checks its SHA-256 against `checksums.txt`, and installs `spicrawl` into `~/.local/bin` (`SPICRAWL_INSTALL_DIR` changes it; `SPICRAWL_VERSION=v0.1.3` or `0.1.3` pins a release). It never prompts and never uses `sudo`.
 
 ### GitHub releases (prebuilt archives)
 
@@ -224,12 +224,12 @@ Screenshots are saved next to the `-o` file as `<name>.<label>.<format>`, or int
 
 ```sh
 id=$(spicrawl batch submit urls.txt --render --name nightly --json | jq -r .id)
-spicrawl batch wait "$id" --max-wait 10m    # exits 11 if the job is still running
+spicrawl batch wait "$id" --max-wait 10m    # exits 11 if still running, 4 if it failed or was cancelled
 spicrawl batch results "$id" --all -o results.jsonl
 spicrawl batch retry "$id"                  # re-run the failed items
 ```
 
-Batch items currently return raw page HTML: the worker applies `--render`, `--proxy` and `--block`, and accepts but does not yet apply other scrape flags such as `--format markdown`. For Markdown or extraction per URL, use `spicrawl scrape - --concurrency 8 < urls.txt`. Results stay readable until the job's `results_expire_at` (72 hours after submission by default). More in the [batch guide](https://docs.spicrawl.com/cli/batch).
+Each batch item is one fetch or render, returned as `html` (the default), `markdown`, `text` or `json` with `--format`. Screenshots, extraction (`--extract`, `--links`), actions, sessions, cache controls and PDF output are refused with a 400 at submit, before anything is queued or charged; use `spicrawl scrape - --concurrency 8 < urls.txt` for those. `batch wait` and `batch submit --wait` print the final job either way, and exit 4 when it ended `failed` or `cancelled`, so a script can tell it from `completed`; partial results stay readable with `batch results`. Results stay readable until the job's `results_expire_at` (72 hours after submission by default). More in the [batch guide](https://docs.spicrawl.com/cli/batch).
 
 ### How to keep cookies and logins across scrapes
 
@@ -266,7 +266,7 @@ All four call the same Spicrawl API with the same API key and the same credits.
 
 - If you want an agent to use Spicrawl with the least setup, run `spicrawl init`: it writes the MCP config and the skill for you.
 - If an agent already has a shell, it can call `spicrawl` directly instead of MCP: output is JSON when piped and the exit code says what went wrong.
-- If you need Markdown for a list of URLs, use `spicrawl scrape -` rather than `spicrawl batch`, because batch items return raw HTML today.
+- If you need Markdown for a list of URLs, use `spicrawl batch submit urls.txt --format markdown` for a server-side job, or `spicrawl scrape -` for one JSON line per URL as it finishes.
 
 ## Built for scripts and AI agents
 
@@ -278,7 +278,7 @@ All four call the same Spicrawl API with the same API key and the same credits.
 
 ### Exit codes
 
-There are 13 exit codes, 0 to 12. They are stable: never renumbered, only added. `spicrawl exit-codes --json` prints them as `[{code, name, meaning}]`.
+There are 14 exit codes: 0 to 12, and 130. They are stable: never renumbered, only added. `spicrawl exit-codes --json` prints them as `[{code, name, meaning}]`.
 
 | Code | Name | Meaning | What an agent should do |
 |---|---|---|---|
@@ -294,7 +294,8 @@ There are 13 exit codes, 0 to 12. They are stable: never renumbered, only added.
 | 9 | `session` | `ERR::SESSION::*` | Create a new session; if the session is busy, wait and retry. |
 | 10 | `network` | the Spicrawl API could not be reached (DNS, refused, TLS); nothing was sent | Safe to retry after a pause; check the network and `--base-url`. |
 | 11 | `pending` | a `--wait` gave up before the job finished | The job is still running: resume with `spicrawl batch wait <id>`. |
-| 12 | `timeout` | the request was sent but `--timeout` expired; it may have run and been billed | Check `spicrawl logs` before retrying. |
+| 12 | `timeout` | the request was sent but `--timeout` expired or the connection dropped; it may have run and been billed | Check `spicrawl logs` before retrying. |
+| 130 | `interrupted` | Ctrl-C | Nothing to do; a request already sent may still have run. |
 
 ## Configuration
 
@@ -315,7 +316,7 @@ Settings resolve in this order: command-line flag, environment variable, config
 
 ## Beta limitations and coming soon
 
-Spicrawl is in beta. Coming soon: AI extraction (`--ai`, `--ai-schema`), the cloud browser (`spicrawl browser url`), the managed proxy pool (`--premium-proxy`, `--country`, `--sticky-key`), stealth mode (`--stealth`), the `spicrawl.com/install.sh` installer and Homebrew. Today, batch items return raw HTML, and there is no whole-site crawl or sitemap command: collect URLs with `--links` and scrape or batch the list.
+Spicrawl is in beta. Coming soon: AI extraction (`--ai`, `--ai-schema`), the cloud browser (`spicrawl browser url`), the managed proxy pool (`--premium-proxy`, `--country`, `--sticky-key`), stealth mode (`--stealth`), the `spicrawl.com/install.sh` installer and Homebrew. Today there is no whole-site crawl or sitemap command: collect URLs with `--links` and scrape or batch the list.
 
 ## FAQ
 
diff --git a/install.sh b/install.sh
index dcbbbf2..ea08175 100755
--- a/install.sh
+++ b/install.sh
@@ -2,11 +2,11 @@
 #
 # Install the Spicrawl CLI (the spicrawl command).
 #
-#   curl -fsSL https://spicrawl.com/install.sh | sh
+#   curl -fsSL https://raw.githubusercontent.com/OfficialSpicrawl/cli/main/install.sh | sh
 #
 # Environment:
 #   SPICRAWL_INSTALL_DIR   where to put the binary (default: ~/.local/bin)
-#   SPICRAWL_VERSION       a release tag such as v1.2.3 (default: latest)
+#   SPICRAWL_VERSION       a release such as v1.2.3 or 1.2.3 (default: latest)
 #   SPICRAWL_REPO          GitHub owner/repo hosting the releases
 #   SPICRAWL_DOWNLOAD_URL  base URL holding the archives and checksums.txt
 #                        (a mirror; overrides SPICRAWL_REPO and SPICRAWL_VERSION)
@@ -51,6 +51,12 @@ if [ "$os" = darwin ] && [ "$arch" = amd64 ]; then
   fi
 fi
 
+# Release tags carry a "v"; accept the bare version too.
+case "$SPICRAWL_VERSION" in
+  latest | v*) ;;
+  *) SPICRAWL_VERSION="v${SPICRAWL_VERSION}" ;;
+esac
+
 archive="spicrawl_${os}_${arch}.tar.gz"
 if [ -n "${SPICRAWL_DOWNLOAD_URL:-}" ]; then
   base="${SPICRAWL_DOWNLOAD_URL%/}"
@@ -82,6 +88,14 @@ fi
 
 command -v tar >/dev/null 2>&1 || die "need tar"
 
+# download URL FILE: on failure say which URL and what to check.
+download() {
+  fetch "$1" "$2" || die "download failed: $1
+  The server was unreachable or has no such file (HTTP 404 means this release or platform does not exist).
+  Check your network, SPICRAWL_VERSION (a published tag such as v0.1.3), SPICRAWL_REPO and SPICRAWL_DOWNLOAD_URL,
+  or pick a release from https://github.com/${SPICRAWL_REPO}/releases"
+}
+
 # --- download and verify ----------------------------------------------------
 
 tmp=$(mktemp -d 2>/dev/null || mktemp -d -t spicrawl)
@@ -89,8 +103,8 @@ trap 'rm -rf "$tmp"' EXIT
 trap 'exit 130' INT TERM
 
 say "downloading ${base}/${archive}"
-fetch "${base}/${archive}" "${tmp}/${archive}" || die "download failed: ${base}/${archive}"
-fetch "${base}/checksums.txt" "${tmp}/checksums.txt" || die "download failed: ${base}/checksums.txt"
+download "${base}/${archive}" "${tmp}/${archive}"
+download "${base}/checksums.txt" "${tmp}/checksums.txt"
 
 want=$(awk -v f="$archive" '$2 == f || $2 == "*" f { print $1; exit }' "${tmp}/checksums.txt")
 [ -n "$want" ] || die "${archive} is not listed in checksums.txt"
diff --git a/internal/api/client.go b/internal/api/client.go
index 25a69ef..773c33d 100644
--- a/internal/api/client.go
+++ b/internal/api/client.go
@@ -30,16 +30,44 @@ type Client struct {
 	BaseURL string
 	APIKey  string
 	HTTP    *http.Client
+	// Notify, when set, receives progress lines (DoWithRetry waiting between
+	// attempts). The caller decides where they go and whether --quiet mutes them.
+	Notify func(format string, a ...any)
 }
 
 func New(baseURL, apiKey string, timeout time.Duration) *Client {
 	return &Client{
 		BaseURL: strings.TrimRight(baseURL, "/"),
 		APIKey:  apiKey,
-		HTTP:    &http.Client{Timeout: timeout},
+		HTTP:    &http.Client{Timeout: timeout, CheckRedirect: noMethodChangingRedirect},
 	}
 }
 
+// noMethodChangingRedirect follows redirects that keep the method (307/308,
+// or any redirect of a GET) and hands back the 3xx for the rest. Following a
+// 301/302/303 would silently turn a POST into a GET: the call would "succeed"
+// without the request ever being made. Do reports the 3xx as a *RedirectError.
+func noMethodChangingRedirect(req *http.Request, via []*http.Request) error {
+	if len(via) >= 10 {
+		return errors.New("stopped after 10 redirects")
+	}
+	if req.Method != via[0].Method {
+		return http.ErrUseLastResponse
+	}
+	return nil
+}
+
+// RedirectError means the API answered with a redirect the CLI will not
+// follow. It is almost always a wrong --base-url (http instead of https).
+type RedirectError struct {
+	Status   int
+	Location string
+}
+
+func (e *RedirectError) Error() string {
+	return fmt.Sprintf("the API answered %d and redirects to %s; the CLI does not follow redirects that would change POST to GET: use that URL as --base-url / SPICRAWL_BASE_URL", e.Status, e.Location)
+}
+
 // Response is a completed call that the API answered with a 2xx.
 type Response struct {
 	Status int
@@ -76,6 +104,17 @@ type NetworkError struct{ Err error }
 func (e *NetworkError) Error() string { return "cannot reach the Spicrawl API: " + e.Err.Error() }
 func (e *NetworkError) Unwrap() error { return e.Err }
 
+// ConnectionLostError means the connection failed after the request was
+// written (reset, EOF, broken body). The server may have run the request,
+// and billed it, so blindly retrying can pay twice. It exits like a timeout.
+type ConnectionLostError struct{ Err error }
+
+func (e *ConnectionLostError) Error() string {
+	return "lost the connection to the Spicrawl API after the request was sent; the request may have run and been billed. " +
+		"Check `spicrawl logs` before retrying (" + e.Err.Error() + ")"
+}
+func (e *ConnectionLostError) Unwrap() error { return e.Err }
+
 // TimeoutError means the request was sent but no complete answer arrived
 // before the client-side timeout (--timeout). The server may have run the
 // request, and billed it, so blindly retrying can pay twice.
@@ -100,14 +139,18 @@ func isTimeout(err error) bool {
 }
 
 // transportError classifies a failure of the HTTP round trip. sent reports
-// whether the request headers were written to the connection: a timeout
-// before that point is a connection failure (nothing reached the API), a
-// timeout after it may have left the request running server-side.
+// whether the request headers were written to the connection. Before that
+// point (dial, DNS, refused, TLS) nothing reached the API: a NetworkError. After
+// it the server may have the request and may have run it: a timeout is a
+// TimeoutError, any other failure a ConnectionLostError. Neither is safe to retry.
 func transportError(err error, sent bool) error {
-	if sent && isTimeout(err) {
+	switch {
+	case !sent:
+		return &NetworkError{Err: err}
+	case isTimeout(err):
 		return &TimeoutError{Err: err}
 	}
-	return &NetworkError{Err: err}
+	return &ConnectionLostError{Err: err}
 }
 
 // Do sends the request. A non-2xx answer is returned as *Problem.
@@ -160,14 +203,22 @@ func (c *Client) Do(ctx context.Context, req Request) (*Response, error) {
 	defer resp.Body.Close()
 	b, err := io.ReadAll(resp.Body)
 	if err != nil {
-		if ctx.Err() == nil && isTimeout(err) {
-			return nil, &TimeoutError{Err: fmt.Errorf("read response: %w", err)}
+		if ctx.Err() != nil {
+			return nil, ctx.Err()
 		}
-		return nil, &NetworkError{Err: fmt.Errorf("read response: %w", err)}
+		// The request was sent: only the answer is missing.
+		return nil, transportError(fmt.Errorf("read response: %w", err), true)
 	}
 	if resp.StatusCode < 200 || resp.StatusCode > 299 {
 		if req.AllowNonProblem && !strings.HasPrefix(resp.Header.Get("Content-Type"), "application/problem+json") {
-			return &Response{Status: resp.StatusCode, Header: resp.Header, Body: b}, nil
+			// A target's status is relayed with X-Target-Status. A 3xx or 5xx without
+			// it is the API's own redirect or a gateway page in front of it.
+			if resp.Header.Get("X-Target-Status") != "" || (resp.StatusCode >= 400 && resp.StatusCode < 500) {
+				return &Response{Status: resp.StatusCode, Header: resp.Header, Body: b}, nil
+			}
+		}
+		if loc := resp.Header.Get("Location"); resp.StatusCode/100 == 3 && loc != "" {
+			return nil, &RedirectError{Status: resp.StatusCode, Location: loc}
 		}
 		return nil, parseProblem(resp, b)
 	}
@@ -222,7 +273,10 @@ func parseProblem(resp *http.Response, b []byte) *Problem {
 			Title:  http.StatusText(resp.StatusCode),
 			Detail: strings.TrimSpace(truncate(string(b), 300)),
 		}
-		p.Retryable = resp.StatusCode >= 500
+		// A gateway page says nothing about whether the API ran the request, so
+		// only a read is safe to resend; a POST may pay twice.
+		p.Retryable = resp.StatusCode >= 500 && resp.Request != nil &&
+			(resp.Request.Method == http.MethodGet || resp.Request.Method == http.MethodHead)
 	}
 	if p.Status == 0 {
 		p.Status = resp.StatusCode
@@ -245,8 +299,12 @@ func AsProblem(err error) (*Problem, bool) {
 	return p, ok
 }
 
+// maxRetryWait caps one wait between attempts: a Retry-After of an hour must
+// not hang the CLI.
+var maxRetryWait = time.Minute
+
 // DoWithRetry retries only what the server marked retryable, honouring
-// Retry-After, with exponential backoff capped at 30 s. attempts <= 1 means
+// Retry-After (capped at maxRetryWait), with exponential backoff capped at 30 s. attempts <= 1 means
 // no retry. Transport failures are never retried here; in particular a
 // *TimeoutError is returned at once, because the request may already have
 // run and been billed (a POST retried after a timeout can pay twice).
@@ -269,6 +327,12 @@ func (c *Client) DoWithRetry(ctx context.Context, req Request, attempts int) (*R
 		if p.RetryAfterSeconds > 0 {
 			wait = time.Duration(p.RetryAfterSeconds) * time.Second
 		}
+		if wait > maxRetryWait {
+			wait = maxRetryWait
+		}
+		if c.Notify != nil {
+			c.Notify("retrying in %s (attempt %d of %d): %s", wait, i+1, attempts, p.Code)
+		}
 		select {
 		case <-ctx.Done():
 			return nil, ctx.Err()
diff --git a/internal/api/client_fix_test.go b/internal/api/client_fix_test.go
new file mode 100644
index 0000000..4a5e3d7
--- /dev/null
+++ b/internal/api/client_fix_test.go
@@ -0,0 +1,135 @@
+package api
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func post(c *Client, ctx context.Context, attempts int, allowNonProblem bool) (*Response, error) {
+	return c.DoWithRetry(ctx, Request{Method: http.MethodPost, Path: "/v1/scrape", Body: map[string]any{}, AllowNonProblem: allowNonProblem}, attempts)
+}
+
+// A connection that dies after the request was written is not "nothing was
+// sent": the server had the request, so a retry can double-bill.
+func TestDropAfterWriteIsNotNetworkError(t *testing.T) {
+	var n atomic.Int32
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		n.Add(1)
+		_, _ = io.Copy(io.Discard, r.Body)
+		conn, _, _ := w.(http.Hijacker).Hijack()
+		conn.Close()
+	}))
+	defer srv.Close()
+	_, err := post(New(srv.URL, "k", time.Second), context.Background(), 3, false)
+	var le *ConnectionLostError
+	var ne *NetworkError
+	if !errors.As(err, &le) || errors.As(err, &ne) || strings.Contains(err.Error(), "nothing was sent") {
+		t.Fatalf("err = %T %v, want *ConnectionLostError", err, err)
+	}
+	if n.Load() != 1 {
+		t.Errorf("%d attempts, want 1: a dropped POST must not be retried", n.Load())
+	}
+}
+
+// A gateway page is an API/infra error: not retried for a POST, and not the
+// scraped target's status even with AllowNonProblem. X-Target-Status marks
+// the target's own status.
+func TestGatewayPageIsNotATargetNorRetriedPost(t *testing.T) {
+	var n atomic.Int32
+	withHeader := false
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		n.Add(1)
+		w.Header().Set("Content-Type", "text/html")
+		if withHeader {
+			w.Header().Set("X-Target-Status", "504")
+		}
+		w.WriteHeader(504)
+		_, _ = fmt.Fprint(w, "<html>Gateway Time-out</html>")
+	}))
+	defer srv.Close()
+	c := New(srv.URL, "k", time.Second)
+
+	_, err := post(c, context.Background(), 3, true)
+	if p, ok := AsProblem(err); !ok || p.Retryable {
+		t.Fatalf("err = %v, want a non-retryable *Problem", err)
+	}
+	if n.Load() != 1 {
+		t.Errorf("%d attempts, want 1", n.Load())
+	}
+
+	withHeader = true
+	if r, err := post(c, context.Background(), 1, true); err != nil || r.Status != 504 {
+		t.Errorf("with X-Target-Status: resp %v err %v, want the relayed 504", r, err)
+	}
+}
+
+func TestRetryAfterIsCappedAndAnnounced(t *testing.T) {
+	old := maxRetryWait
+	maxRetryWait = 20 * time.Millisecond
+	defer func() { maxRetryWait = old }()
+	var n atomic.Int32
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		if n.Add(1) == 1 {
+			w.Header().Set("Content-Type", "application/problem+json")
+			w.Header().Set("Retry-After", "100000")
+			w.WriteHeader(429)
+			_, _ = w.Write([]byte(`{"code":"ERR::LIMIT::RATE","retryable":true,"status":429,"title":"x"}`))
+			return
+		}
+		_, _ = w.Write([]byte(`{}`))
+	}))
+	defer srv.Close()
+	c := New(srv.URL, "k", time.Second)
+	var notes []string
+	c.Notify = func(f string, a ...any) { notes = append(notes, fmt.Sprintf(f, a...)) }
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	if _, err := c.DoWithRetry(ctx, Request{Path: "/v1/usage"}, 2); err != nil {
+		t.Fatal(err)
+	}
+	if len(notes) != 1 || !strings.Contains(notes[0], "retrying in 20ms") {
+		t.Errorf("notes = %q", notes)
+	}
+}
+
+// A 301/302/303 would turn the POST into a GET and "succeed"; 307/308 keep
+// the method and are followed.
+func TestRedirectDoesNotChangePostToGet(t *testing.T) {
+	var methods []string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		methods = append(methods, r.Method)
+		switch r.URL.Path {
+		case "/v1/scrape":
+			http.Redirect(w, r, "/moved", 301)
+		case "/v1/temp":
+			http.Redirect(w, r, "/final", 307)
+		default:
+			_, _ = w.Write([]byte(`{}`))
+		}
+	}))
+	defer srv.Close()
+	c := New(srv.URL, "k", time.Second)
+
+	_, err := post(c, context.Background(), 1, false)
+	var re *RedirectError
+	if !errors.As(err, &re) || re.Location != "/moved" || !strings.Contains(err.Error(), "/moved") {
+		t.Fatalf("err = %T %v, want *RedirectError naming the Location", err, err)
+	}
+	if len(methods) != 1 {
+		t.Fatalf("methods = %v, want only the POST", methods)
+	}
+	if _, err := c.Do(context.Background(), Request{Method: http.MethodPost, Path: "/v1/temp", Body: map[string]any{}}); err != nil {
+		t.Fatal(err)
+	}
+	if got := methods[1:]; len(got) != 2 || got[1] != http.MethodPost {
+		t.Errorf("307 methods = %v, want POST kept", got)
+	}
+}
diff --git a/internal/cmd/agents.go b/internal/cmd/agents.go
index 3ef368b..de74132 100644
--- a/internal/cmd/agents.go
+++ b/internal/cmd/agents.go
@@ -398,6 +398,7 @@ type agentResult struct {
 	Action string `json:"action"` // created | updated | unchanged | skipped
 	Reason string `json:"reason,omitempty"`
 	Secret bool   `json:"secret,omitempty"` // the file now holds a literal API key
+	Backup string `json:"backup,omitempty"` // copy of the previous file, written before it was modified
 
 	content  []byte // what to write when applied
 	mode     os.FileMode
@@ -410,9 +411,12 @@ func agentApply(rs []*agentResult) error {
 		if r.Action != agentActionCreated && r.Action != agentActionUpdated {
 			continue
 		}
-		if err := agentWriteFile(r.File, r.content, r.mode, r.Secret); err != nil {
+		// A generated skill is not worth a backup; configs and AGENTS.md hold the user's own content.
+		bak, err := agentWriteFile(r.File, r.content, r.mode, r.Secret, r.Kind != "skill")
+		if err != nil {
 			return err
 		}
+		r.Backup = bak
 	}
 	return nil
 }
@@ -425,7 +429,14 @@ func agentReport(p *output.Printer, rs []*agentResult, s agentScope) error {
 	err := p.Result(rs, func(w io.Writer) {
 		rows := make([][]string, 0, len(rs))
 		for _, r := range rs {
-			rows = append(rows, []string{r.Client, r.Kind, r.Action, agentDisplayPath(r.File, s), r.Reason})
+			note := r.Reason
+			if r.Backup != "" {
+				if note != "" {
+					note += "; "
+				}
+				note += "backup: " + agentDisplayPath(r.Backup, s)
+			}
+			rows = append(rows, []string{r.Client, r.Kind, r.Action, agentDisplayPath(r.File, s), note})
 		}
 		p.Table([]string{"CLIENT", "KIND", "ACTION", "FILE", "NOTE"}, rows)
 	})
@@ -494,10 +505,22 @@ func agentPlanFile(r *agentResult, content []byte, mode os.FileMode) error {
 	return nil
 }
 
-// agentWriteFile writes atomically (temp file + rename). A non-secret write
-// keeps the mode of an existing file; a secret one always ends up 0600.
-func agentWriteFile(path string, data []byte, mode os.FileMode, secret bool) error {
-	if fi, err := os.Stat(path); err == nil && !secret {
+// agentWriteFile writes atomically (temp file + rename), through a symlink to
+// its target so the link survives. With backup, an existing file is first
+// copied to <file>.bak (same permissions); the copy's path is returned. A
+// non-secret write keeps the mode of an existing file; a secret one always
+// ends up 0600.
+func agentWriteFile(path string, data []byte, mode os.FileMode, secret, backup bool) (string, error) {
+	if real, err := filepath.EvalSymlinks(path); err == nil {
+		path = real
+	} else if l, err := os.Readlink(path); err == nil { // dangling link: create its target
+		if !filepath.IsAbs(l) {
+			l = filepath.Join(filepath.Dir(path), l)
+		}
+		path = l
+	}
+	fi, statErr := os.Stat(path)
+	if statErr == nil && !secret {
 		mode = fi.Mode().Perm()
 	}
 	if secret {
@@ -506,36 +529,48 @@ func agentWriteFile(path string, data []byte, mode os.FileMode, secret bool) err
 	if mode == 0 {
 		mode = 0o644
 	}
+	bak := ""
+	if backup && statErr == nil {
+		old, err := os.ReadFile(path)
+		if err == nil {
+			bak = path + ".bak"
+			_ = os.Remove(bak)
+			err = os.WriteFile(bak, old, fi.Mode().Perm())
+		}
+		if err != nil {
+			return "", fmt.Errorf("back up %s: %w", path, err)
+		}
+	}
 	dir := filepath.Dir(path)
 	if err := os.MkdirAll(dir, 0o755); err != nil {
-		return fmt.Errorf("create %s: %w", dir, err)
+		return "", fmt.Errorf("create %s: %w", dir, err)
 	}
 	f, err := os.CreateTemp(dir, "."+filepath.Base(path)+".tmp-*")
 	if err != nil {
-		return fmt.Errorf("write %s: %w", path, err)
+		return "", fmt.Errorf("write %s: %w", path, err)
 	}
 	tmp := f.Name()
 	defer os.Remove(tmp)
 	if err := f.Chmod(mode); err != nil {
 		f.Close()
-		return fmt.Errorf("write %s: %w", path, err)
+		return "", fmt.Errorf("write %s: %w", path, err)
 	}
 	if _, err := f.Write(data); err != nil {
 		f.Close()
-		return fmt.Errorf("write %s: %w", path, err)
+		return "", fmt.Errorf("write %s: %w", path, err)
 	}
 	if err := f.Close(); err != nil {
-		return fmt.Errorf("write %s: %w", path, err)
+		return "", fmt.Errorf("write %s: %w", path, err)
 	}
 	if err := os.Rename(tmp, path); err != nil {
-		return fmt.Errorf("write %s: %w", path, err)
+		return "", fmt.Errorf("write %s: %w", path, err)
 	}
 	if secret {
 		if err := os.Chmod(path, 0o600); err != nil {
-			return fmt.Errorf("restrict permissions of %s: %w", path, err)
+			return "", fmt.Errorf("restrict permissions of %s: %w", path, err)
 		}
 	}
-	return nil
+	return bak, nil
 }
 
 // agentAPIKey returns the configured key (flag > env > file), or "".
diff --git a/internal/cmd/agents_test.go b/internal/cmd/agents_test.go
index 2a6b764..13873e5 100644
--- a/internal/cmd/agents_test.go
+++ b/internal/cmd/agents_test.go
@@ -144,7 +144,7 @@ func TestMCPInstallMCPURLOverride(t *testing.T) {
 	if w["url"] != "https://env.example/mcp" {
 		t.Errorf("url = %v", w["url"])
 	}
-	if _, _, code := agentRun(t, "mcp", "install", "--client", "cursor", "--dir", dir, "--mcp-url", "https://flag.example/mcp"); code != 0 {
+	if _, _, code := agentRun(t, "mcp", "install", "--client", "cursor", "--dir", dir, "--mcp-url", "https://flag.example/mcp", "--force"); code != 0 {
 		t.Fatal(code)
 	}
 	w = agentReadJSON(t, filepath.Join(dir, ".cursor", "mcp.json"))["mcpServers"].(map[string]any)["spicrawl"].(map[string]any)
@@ -213,7 +213,7 @@ approval_mode = "approve"
 [mcp_servers.other]
 command = "x"
 `)
-	rs, errOut, code := agentRun(t, "mcp", "install", "--client", "codex", "--dir", dir)
+	rs, errOut, code := agentRun(t, "mcp", "install", "--client", "codex", "--dir", dir, "--force")
 	if code != 0 || rs[0].Action != "updated" {
 		t.Fatalf("exit %d %+v: %s", code, rs, errOut)
 	}
@@ -323,10 +323,10 @@ func TestMCPInstallNeedsClient(t *testing.T) {
 func TestMCPInstallRefusesInvalidJSON(t *testing.T) {
 	dir, _ := agentTestEnv(t)
 	path := filepath.Join(dir, ".vscode", "mcp.json")
-	orig := "{\n  // comment\n  \"servers\": {}\n}\n"
+	orig := "{\n  \"servers\": {\n"
 	agentWrite(t, path, orig)
 	if _, _, code := agentRun(t, "mcp", "install", "--client", "vscode", "--dir", dir); code == 0 {
-		t.Fatal("want failure on JSONC")
+		t.Fatal("want failure on truncated JSON")
 	}
 	b, _ := os.ReadFile(path)
 	if string(b) != orig {
@@ -703,7 +703,7 @@ func agentCodexRun(t *testing.T, dir, content string, extra ...string) (string,
 	t.Helper()
 	path := filepath.Join(dir, ".codex", "config.toml")
 	agentWrite(t, path, content)
-	_, errOut, code := agentRun(t, append([]string{"mcp", "install", "--client", "codex", "--dir", dir}, extra...)...)
+	_, errOut, code := agentRun(t, append([]string{"mcp", "install", "--client", "codex", "--dir", dir, "--force"}, extra...)...)
 	b, _ := os.ReadFile(path)
 	return string(b), errOut, code
 }
diff --git a/internal/cmd/assets/skill.md b/internal/cmd/assets/skill.md
index 064172a..e2d66c8 100644
--- a/internal/cmd/assets/skill.md
+++ b/internal/cmd/assets/skill.md
@@ -141,7 +141,7 @@ Unknown fields are rejected with `400`: send only the fields below.
 | `url` | string | **Required.** The page to fetch. |
 | `response_format` | string | `markdown` (best for LLMs), `html`, `text`, `json` (envelope with metadata), `pdf`. |
 | `js_render` | bool | The content is built by JavaScript (SPA, empty HTML shell). |
-| `impersonate` | bool | Fetch tier only: present a real browser's TLS/HTTP2 fingerprint. No JavaScript. POST only. |
+| `impersonate` | bool | Fetch tier only: present a current Chrome TLS/HTTP2 fingerprint. On by default and free; send `false` only to turn it off. |
 | `mode` | string | `auto` escalates fetch → obscura until one succeeds, billing only that rung. Not with `js_render` or `engine`. |
 | `engine` | string | Pin `fetch` / `obscura` / `chromium`. Not with `mode: auto`; `js_render` cannot pin `fetch`. |
 | `wait_for` / `wait_for_timeout` | string / int ms | CSS selector to wait for before capturing, and its cap. |
@@ -157,7 +157,7 @@ Unknown fields are rejected with `400`: send only the fields below.
 | `actions` | object[] | Browser workflow, at most 50 steps: `click`, `fill`, `wait_for`, `scroll`, `select`, `evaluate`, `screenshot`. |
 | `block_resources` | string[] | `images` `fonts` `media` `stylesheets` `scripts`, or `none`. |
 | `session_id` | string | Reuse a session's cookies and storage (see Sessions). Combine with `js_render` when you also send `actions` or `wait_for`. |
-| `cache` / `cache_ttl` | bool / int s | Cache is **on** (48h max). Send `cache: false` for prices, stock or anything time-sensitive. |
+| `cache` / `cache_ttl` | bool / int s | Cache is **on** (48h max). A hit is billed like the fetch that stored it: the cache saves time, not credits. Send `cache: false` for prices, stock or anything time-sensitive. |
 | `max_cost` | int | Refuse up front if the request would cost more credits than this. |
 | `proxy` / `proxy_verify` | string / bool | Your own proxy URL (+0 credits), optionally checked first. Use it when a site blocks our IPs or you need a specific country. |
 | `custom_headers` / `method` | object / string | Headers sent to the target (the field is `custom_headers`; `headers` is rejected). Default method `GET`. |
@@ -223,7 +223,7 @@ Every step accepts `label`, `timeout_ms` and `on_error` (`fail` or `skip`). `sec
 | `X-Credits-Remaining` | Monthly allowance left after this call (absent if the org has no limit). |
 | `X-Engine` | Engine that served it. |
 | `X-Final-Url` | URL after redirects. |
-| `Cache-State` | `hit` (0 credits), `miss` or `bypass`. |
+| `Cache-State` | `hit` (billed like the fetch that stored it), `miss` or `bypass`. |
 | `X-Warning` | Non-fatal decisions (a clamped `cache_ttl`, an ignored flag). |
 | `X-RateLimit-Limit` / `-Remaining` / `-Reset` | Rate limit state. |
 
@@ -299,8 +299,9 @@ allowance while it is open (24 credits for the default 3 minutes); unused minute
 | `chromium` | 8 |
 
 You pay for the engine that actually served (`X-Engine`). `ai_extract` adds +4. **Failures cost
-0.** Cache hits cost 0. A deployment may discount these prices: `X-Credits-Charged` and
-`X-Request-Cost` are authoritative.
+0.** A cache hit is billed at the same price as the fetch that stored it. The cache saves the
+fetch (latency and load on the target), not credits. A deployment may discount these prices:
+`X-Credits-Charged` and `X-Request-Cost` are authoritative.
 
 Each organization gets a monthly allowance (1,000 credits by default). The month starts on the
 day the organization was created and resets at 00:00 UTC on that day. What is left, and when it
diff --git a/internal/cmd/batch.go b/internal/cmd/batch.go
index 92cc732..91f7f05 100644
--- a/internal/cmd/batch.go
+++ b/internal/cmd/batch.go
@@ -3,10 +3,12 @@ package cmd
 import (
 	"bufio"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/url"
 	"os"
+	"path/filepath"
 	"strconv"
 	"strings"
 	"time"
@@ -15,6 +17,7 @@ import (
 	"github.com/spf13/pflag"
 
 	"github.com/OfficialSpicrawl/cli/internal/api"
+	"github.com/OfficialSpicrawl/cli/internal/exitcode"
 	"github.com/OfficialSpicrawl/cli/internal/output"
 )
 
@@ -129,7 +132,7 @@ read as JSON items, anything else as URLs).
 
 Scrape flags set job-wide defaults; items override them. Prints the job; with
 --wait, polls until the job finishes and prints the final job (exit 11 if
---max-wait elapses first).
+--max-wait elapses first, exit 4 if the job failed or was cancelled).
 
 Each item is one fetch or render, returned as html (default), markdown, text
 or json (--format). Only the scrape flags batch accepts are offered here; the
@@ -238,11 +241,15 @@ var (
 
 var batchWaitCmd = &cobra.Command{
 	Use:   "wait <id>",
-	Short: "Poll a job until it finishes, then print it (exit 11 on --max-wait)",
+	Short: "Poll a job until it finishes, then print it (exit 11 on --max-wait, 4 if failed or cancelled)",
 	Long: `Poll GET /v1/batch/{id} until the job is completed, failed or cancelled, then
 print the job. If --max-wait elapses first, prints the last job seen and exits
 11, so a script can resume with the same command. --max-wait 0 waits forever.
-Rate limits (429) are honoured: the next poll waits for Retry-After.`,
+A job that ends failed or cancelled is printed too, but exits 4: only completed
+exits 0 (partial results stay readable with "batch results").
+Rate limits (429) are honoured: the next poll waits for Retry-After. Transient
+5xx answers and network errors are retried with backoff; five polls in a row
+failing that way gives up with that error.`,
 	Example: `  spicrawl batch wait 01J9Z6V0Q8M4K2T7R3N5B1C9XA --max-wait 10m
   spicrawl batch wait "$id" --poll 10s --json | jq '.progress'
 
@@ -271,6 +278,13 @@ func batchWaitAndPrint(cmd *cobra.Command, c *api.Client, p *output.Printer, id
 		if werr == nil && !p.JSON && job.Status != "" {
 			p.Info("\nnext: spicrawl batch results %s --all -o %s.jsonl", job.ID, job.ID)
 		}
+		if werr == nil && (job.Status == "failed" || job.Status == "cancelled") {
+			msg := fmt.Sprintf("batch %s %s (%d of %d items finished)", id, job.Status, job.Progress.Completed, job.Progress.Total)
+			if e := strings.TrimSpace(job.ErrorCode + " " + job.ErrorMessage); e != "" {
+				msg += ": " + e
+			}
+			return &ExitError{Code: exitcode.Request, Err: errors.New(msg)}
+		}
 	}
 	return werr
 }
@@ -625,14 +639,42 @@ func init() {
 	rootCmd.AddCommand(batchCmd)
 }
 
-// batchOpenOut returns the writer for -o (or stdout) and a closer.
-func batchOpenOut(path string) (io.Writer, func() error, error) {
+// batchOpenOut returns the writer for -o (or stdout) and a finisher. A regular
+// file is written to a temp file next to it: finish(true) renames it into
+// place, finish(false) discards it, so a failed run never truncates or
+// half-overwrites an existing file. Devices and pipes (/dev/stdout) are
+// written directly.
+func batchOpenOut(path string) (io.Writer, func(commit bool) error, error) {
 	if path == "" || path == "-" {
-		return stdout, func() error { return nil }, nil
+		return stdout, func(bool) error { return nil }, nil
+	}
+	if r, err := filepath.EvalSymlinks(path); err == nil {
+		path = r // replace the file a symlink points at, not the link
+	}
+	old, statErr := os.Stat(path)
+	if statErr == nil && !old.Mode().IsRegular() {
+		f, err := os.Create(path)
+		if err != nil {
+			return nil, nil, Usagef("-o: %v", err)
+		}
+		return f, func(bool) error { return f.Close() }, nil
 	}
-	f, err := os.Create(path)
+	tmp := filepath.Join(filepath.Dir(path), fmt.Sprintf(".%s.%d.tmp", filepath.Base(path), os.Getpid()))
+	f, err := os.OpenFile(tmp, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0o666)
 	if err != nil {
 		return nil, nil, Usagef("-o: %v", err)
 	}
-	return f, f.Close, nil
+	if statErr == nil {
+		_ = f.Chmod(old.Mode().Perm())
+	}
+	return f, func(commit bool) error {
+		err := f.Close()
+		if commit && err == nil {
+			err = os.Rename(tmp, path)
+		}
+		if err != nil || !commit {
+			_ = os.Remove(tmp)
+		}
+		return err
+	}, nil
 }
diff --git a/internal/cmd/batch_fix_test.go b/internal/cmd/batch_fix_test.go
new file mode 100644
index 0000000..f1d70ff
--- /dev/null
+++ b/internal/cmd/batch_fix_test.go
@@ -0,0 +1,118 @@
+package cmd
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"testing"
+)
+
+// A job that ends failed or cancelled is not a success: wait and submit --wait
+// print it but exit 4.
+func TestBatchWaitFailedOrCancelledExitsNonZero(t *testing.T) {
+	for _, status := range []string{"failed", "cancelled"} {
+		srv, _ := newRecordingServer(t, func(w http.ResponseWriter, r *http.Request) {
+			if r.Method == "POST" {
+				w.WriteHeader(http.StatusAccepted)
+			}
+			fmt.Fprint(w, strings.Replace(batchJobJSON("JF", status, 1, 3), `"submitted_at"`, `"error_code":"ERR::LIMIT::BUDGET","submitted_at"`, 1))
+		})
+		file := batchWriteFile(t, "urls.txt", "https://example.com/1\n")
+		for _, args := range [][]string{{"batch", "wait", "JF"}, {"batch", "submit", file, "--wait"}} {
+			out, errOut, code := batchRunCLI(t, srv.URL, append(args, "--poll", "5ms")...)
+			if code != 4 {
+				t.Errorf("%v (%s): exit %d, want 4; stderr %s", args[:2], status, code, errOut)
+			}
+			if batchDecodeBody(t, []byte(out))["status"] != status || !strings.Contains(errOut, "batch JF "+status) || !strings.Contains(errOut, "ERR::LIMIT::BUDGET") {
+				t.Errorf("%v (%s): stdout %s stderr %s", args[:2], status, out, errOut)
+			}
+		}
+	}
+}
+
+// -o is written to a temp file and renamed on success: a 410 leaves the
+// existing file intact and no temp file behind.
+func TestBatchResultsKeepsExistingFileOnFailure(t *testing.T) {
+	fail := true
+	srv, _ := newRecordingServer(t, func(w http.ResponseWriter, r *http.Request) {
+		if fail {
+			writeProblem(w, http.StatusGone, "ERR::REQUEST::BEYOND_RETENTION", false)
+			return
+		}
+		fmt.Fprint(w, `{"seq":0,"url":"u","status":"succeeded"}`)
+	})
+	dir := t.TempDir()
+	path := filepath.Join(dir, "results.jsonl")
+	if err := os.WriteFile(path, []byte("previous\n"), 0o640); err != nil {
+		t.Fatal(err)
+	}
+	if _, errOut, code := batchRunCLI(t, srv.URL, "batch", "results", "J", "-o", path); code != 4 {
+		t.Fatalf("exit %d, want 4; stderr %s", code, errOut)
+	}
+	if b, _ := os.ReadFile(path); string(b) != "previous\n" {
+		t.Errorf("existing file changed: %q", b)
+	}
+	fail = false
+	if _, errOut, code := batchRunCLI(t, srv.URL, "batch", "results", "J", "-o", path); code != 0 {
+		t.Fatalf("exit %d; stderr %s", code, errOut)
+	}
+	if b, _ := os.ReadFile(path); !strings.Contains(string(b), `"seq":0`) {
+		t.Errorf("file not replaced: %q", b)
+	}
+	if fi, _ := os.Stat(path); fi.Mode().Perm() != 0o640 {
+		t.Errorf("mode %v, want the old file's 0640", fi.Mode().Perm())
+	}
+	if ents, _ := os.ReadDir(dir); len(ents) != 1 {
+		t.Errorf("leftover files in %s: %v", dir, ents)
+	}
+}
+
+// One 502 or dropped connection must not abort the wait; five in a row do.
+func TestBatchWaitToleratesTransientFailures(t *testing.T) {
+	var gets atomic.Int32
+	srv, _ := newRecordingServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch gets.Add(1) {
+		case 1:
+			w.WriteHeader(http.StatusBadGateway)
+			fmt.Fprint(w, "<html>bad gateway</html>")
+		case 2:
+			conn, _, _ := w.(http.Hijacker).Hijack()
+			conn.Close() // network error: the connection drops mid-request
+		case 3:
+			fmt.Fprint(w, batchJobJSON("JT", "running", 1, 2))
+		case 4:
+			w.WriteHeader(http.StatusGatewayTimeout)
+		default:
+			fmt.Fprint(w, batchJobJSON("JT", "completed", 2, 2))
+		}
+	})
+	out, errOut, code := batchRunCLI(t, srv.URL, "batch", "wait", "JT", "--poll", "2ms")
+	if code != 0 || batchDecodeBody(t, []byte(out))["status"] != "completed" {
+		t.Fatalf("exit %d stdout %s stderr %s", code, out, errOut)
+	}
+
+	var dead atomic.Int32
+	srv2, _ := newRecordingServer(t, func(w http.ResponseWriter, r *http.Request) {
+		dead.Add(1)
+		w.WriteHeader(http.StatusBadGateway)
+	})
+	if _, _, code := batchRunCLI(t, srv2.URL, "batch", "wait", "JD", "--poll", "1ms"); code == 0 || dead.Load() != batchWaitMaxFailures {
+		t.Errorf("exit %d after %d polls, want non-zero after %d", code, dead.Load(), batchWaitMaxFailures)
+	}
+}
+
+// --body null used to leave a nil map that batch submit then wrote into
+// (panic). It is a usage error now, and nothing is sent.
+func TestBatchSubmitBodyNullIsAUsageError(t *testing.T) {
+	srv, reqs := newRecordingServer(t, func(w http.ResponseWriter, r *http.Request) {})
+	file := batchWriteFile(t, "urls.txt", "https://example.com/1\n")
+	if _, errOut, code := batchRunCLI(t, srv.URL, "batch", "submit", file, "--body", "null"); code != 2 || !strings.Contains(errOut, "null") {
+		t.Errorf("exit %d: %s", code, errOut)
+	}
+	if len(*reqs) != 0 {
+		t.Errorf("%d requests sent", len(*reqs))
+	}
+}
diff --git a/internal/cmd/batch_input.go b/internal/cmd/batch_input.go
index fc22207..e4d0ba7 100644
--- a/internal/cmd/batch_input.go
+++ b/internal/cmd/batch_input.go
@@ -80,7 +80,7 @@ func batchDisplayPath(path string) string {
 // batchSplitLines mirrors readLines for bytes already in memory.
 func batchSplitLines(b []byte) []string {
 	var out []string
-	for _, line := range strings.Split(string(b), "\n") {
+	for _, line := range strings.Split(strings.TrimPrefix(string(b), "\ufeff"), "\n") {
 		line = strings.TrimSpace(line)
 		if line == "" || strings.HasPrefix(line, "#") {
 			continue
diff --git a/internal/cmd/batch_results.go b/internal/cmd/batch_results.go
index 0db7576..4222ed0 100644
--- a/internal/cmd/batch_results.go
+++ b/internal/cmd/batch_results.go
@@ -89,7 +89,7 @@ func batchRunResults(cmd *cobra.Command, args []string) error {
 
 	raw := p.JSON || batchResultsOut != ""
 	var w io.Writer
-	closeOut := func() error { return nil }
+	closeOut := func(bool) error { return nil }
 	if raw {
 		if w, closeOut, err = batchOpenOut(batchResultsOut); err != nil {
 			return err
@@ -106,7 +106,7 @@ func batchRunResults(cmd *cobra.Command, args []string) error {
 		}
 		resp, err := c.DoWithRetry(cmd.Context(), api.Request{Path: path, Query: q, Accept: "application/x-ndjson"}, 3)
 		if err != nil {
-			_ = closeOut()
+			_ = closeOut(false)
 			return err
 		}
 		body := resp.Body
@@ -115,7 +115,7 @@ func batchRunResults(cmd *cobra.Command, args []string) error {
 				body = append(body, '\n')
 			}
 			if _, err := w.Write(body); err != nil {
-				_ = closeOut()
+				_ = closeOut(false)
 				return err
 			}
 			lines += bytes.Count(body, []byte{'\n'})
@@ -132,7 +132,7 @@ func batchRunResults(cmd *cobra.Command, args []string) error {
 		}
 		cursor = next
 	}
-	if err := closeOut(); err != nil {
+	if err := closeOut(true); err != nil {
 		return err
 	}
 
@@ -253,10 +253,10 @@ func batchRunContent(cmd *cobra.Command, args []string) error {
 		return err
 	}
 	if _, err := w.Write(doc); err != nil {
-		_ = closeOut()
+		_ = closeOut(false)
 		return err
 	}
-	if err := closeOut(); err != nil {
+	if err := closeOut(true); err != nil {
 		return err
 	}
 	if batchContentOut != "" && batchContentOut != "-" {
diff --git a/internal/cmd/batch_wait.go b/internal/cmd/batch_wait.go
index 8c55f8b..c2f07a2 100644
--- a/internal/cmd/batch_wait.go
+++ b/internal/cmd/batch_wait.go
@@ -2,6 +2,7 @@ package cmd
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"net/http"
 	"net/url"
@@ -16,10 +17,31 @@ import (
 // batchTerminal are the job statuses at which polling stops.
 var batchTerminal = map[string]bool{"completed": true, "failed": true, "cancelled": true}
 
+// batchWaitMaxFailures is how many polls in a row may fail transiently before
+// batchWaitJob gives up with the last error.
+const batchWaitMaxFailures = 5
+
+// batchPollTransient reports whether a failed poll is worth repeating. A poll
+// is a GET, so a repeat is always safe, even after a timeout.
+func batchPollTransient(err error) bool {
+	if prob, ok := api.AsProblem(err); ok {
+		return prob.Status == http.StatusBadGateway || prob.Status == http.StatusGatewayTimeout ||
+			(prob.Status >= 500 && prob.Retryable)
+	}
+	var (
+		ne *api.NetworkError
+		te *api.TimeoutError
+		ce *api.ConnectionLostError
+	)
+	return errors.As(err, &ne) || errors.As(err, &te) || errors.As(err, &ce)
+}
+
 // batchWaitJob polls GET /v1/batch/{id} every poll until the job is terminal.
-// A 429 (or a retryable 503) is not fatal: the next poll waits for the
-// server's Retry-After instead. When timeout (> 0) elapses first it returns
-// the last job it saw together with an ExitError{Code: Pending}.
+// A 429 is not fatal: the next poll waits for the server's Retry-After
+// instead. Transient failures (502/504, retryable 5xx, network errors and
+// timeouts) are retried with exponential backoff; batchWaitMaxFailures in a
+// row return the last error. When timeout (> 0) elapses first it returns the
+// last job it saw together with an ExitError{Code: Pending}.
 func batchWaitJob(ctx context.Context, c *api.Client, p *output.Printer, id string, poll, timeout time.Duration) ([]byte, error) {
 	if poll <= 0 {
 		poll = time.Second
@@ -33,19 +55,25 @@ func batchWaitJob(ctx context.Context, c *api.Client, p *output.Printer, id stri
 
 	var last []byte
 	var lastJob batchJob
+	failures := 0
 	for {
 		delay := poll
 		resp, err := c.Do(ctx, api.Request{Path: "/v1/batch/" + url.PathEscape(id)})
 		if err != nil {
-			prob, ok := api.AsProblem(err)
-			if !ok || !(prob.Status == http.StatusTooManyRequests || (prob.Status == http.StatusServiceUnavailable && prob.Retryable)) {
-				return last, err
+			prob, isProb := api.AsProblem(err)
+			limited := isProb && prob.Status == http.StatusTooManyRequests
+			if !limited {
+				if failures++; !batchPollTransient(err) || failures >= batchWaitMaxFailures {
+					return last, err
+				}
+				delay = min(poll<<failures, max(poll, 30*time.Second))
 			}
-			if prob.RetryAfterSeconds > 0 {
-				delay = time.Duration(prob.RetryAfterSeconds) * time.Second
+			if isProb && prob.RetryAfterSeconds > 0 {
+				delay = min(time.Duration(prob.RetryAfterSeconds)*time.Second, time.Minute)
 			}
-			prog.note("rate limited; next poll in %s", delay)
+			prog.note("poll failed (%v); next poll in %s", err, delay)
 		} else {
+			failures = 0
 			var job batchJob
 			if err := resp.Decode(&job); err != nil {
 				return last, err
diff --git a/internal/cmd/browser.go b/internal/cmd/browser.go
index a37bd81..4cde7d7 100644
--- a/internal/cmd/browser.go
+++ b/internal/cmd/browser.go
@@ -1,6 +1,7 @@
 package cmd
 
 import (
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -11,6 +12,7 @@ import (
 
 	"github.com/OfficialSpicrawl/cli/internal/api"
 	"github.com/OfficialSpicrawl/cli/internal/config"
+	"github.com/OfficialSpicrawl/cli/internal/exitcode"
 )
 
 var (
@@ -43,11 +45,15 @@ options given here (changing them in the URL is refused). Mint a new URL for
 every connection. Clients that can set headers on the upgrade can skip the
 token and send "Authorization: Bearer <key>" to /v1/browser directly.
 
-Unlike sessions, the exit rotates unless you pass --sticky-key.`,
+Unlike sessions, the exit rotates unless you pass --sticky-key.
+
+-q prints only the URL, even when stdout is piped (--json keeps the JSON). On
+a server without a cloud browser it exits 8 ("cloud browser (CDP) is not enabled
+on this server").`,
 	Example: `  spicrawl browser url
   spicrawl browser url --engine obscura --region eu --ttl 600
   spicrawl browser url --country us --headless=false --sticky-key crawl-1
-  export SPICRAWL_BROWSER_URL="$(spicrawl browser url -q)"
+  export SPICRAWL_BROWSER_URL="$(spicrawl browser url -q)"   # -q: the bare URL, even when piped
   WS=$(spicrawl browser url --json | jq -r .url)`,
 	Args: cobra.NoArgs,
 	RunE: func(cmd *cobra.Command, _ []string) error {
@@ -104,6 +110,12 @@ Unlike sessions, the exit rotates unless you pass --sticky-key.`,
 		}
 		resp, err := c.Do(cmd.Context(), api.Request{Method: http.MethodPost, Path: "/v1/browser/token", Body: body})
 		if err != nil {
+			// No such route (404) or a deployment without a CDP browser (501): permanent.
+			if prob, ok := api.AsProblem(err); ok && (prob.Status == http.StatusNotFound ||
+				prob.Status == http.StatusNotImplemented && prob.Code == "ERR::ENGINE::UNAVAILABLE") {
+				return &ExitError{Code: exitcode.Engine, Err: errors.New(
+					"cloud browser (CDP) is not enabled on this server; \"spicrawl status\" shows its cdp field")}
+			}
 			return err
 		}
 		var tok struct {
@@ -119,6 +131,9 @@ Unlike sessions, the exit rotates unless you pass --sticky-key.`,
 		}
 
 		p := Printer()
+		if p.Quiet && !flagJSON {
+			p.JSON = false // -q prints the bare URL even when piped; only an explicit --json overrides it
+		}
 		if strings.HasPrefix(ws, "ws://") {
 			p.Warn("ws:// is unencrypted: the browser token in this URL travels in cleartext (use an https base URL)")
 		}
diff --git a/internal/cmd/browser_fix_test.go b/internal/cmd/browser_fix_test.go
new file mode 100644
index 0000000..e6f8887
--- /dev/null
+++ b/internal/cmd/browser_fix_test.go
@@ -0,0 +1,54 @@
+package cmd
+
+import (
+	"bytes"
+	"net/http"
+	"os"
+	"strings"
+	"testing"
+)
+
+// runCLIPiped is runCLI without --json, like a script capturing stdout: the
+// output is not a terminal, so the printer picks JSON unless told otherwise.
+func runCLIPiped(t *testing.T, baseURL string, args ...string) (string, string, int) {
+	t.Helper()
+	t.Setenv("SPICRAWL_CONFIG", t.TempDir()+"/config.json")
+	t.Setenv("SPICRAWL_API_KEY", "spicrawl_test_key")
+	var out, errb bytes.Buffer
+	stdout, stderr = &out, &errb
+	defer func() {
+		stdout, stderr = os.Stdout, os.Stderr
+		resetFlags(rootCmd)
+	}()
+	rootCmd.SetArgs(append([]string{"--base-url", baseURL}, args...))
+	code := Execute()
+	return out.String(), errb.String(), code
+}
+
+// A server without CDP (no route, or 501 ERR::ENGINE::UNAVAILABLE) is a
+// permanent condition: say so and exit 8, not "NOT_FOUND ... exit 4".
+func TestBrowserURLWhenCDPIsDisabled(t *testing.T) {
+	for name, h := range map[string]http.HandlerFunc{
+		"404": func(w http.ResponseWriter, r *http.Request) { http.NotFound(w, r) },
+		"501": func(w http.ResponseWriter, r *http.Request) { writeProblem(w, 501, "ERR::ENGINE::UNAVAILABLE", false) },
+	} {
+		srv, _ := newRecordingServer(t, h)
+		_, errb, code := runCLI(t, srv.URL, "browser", "url")
+		if code != 8 || !strings.Contains(errb, "cloud browser (CDP) is not enabled on this server") {
+			t.Errorf("%s: exit %d, stderr %s", name, code, errb)
+		}
+	}
+}
+
+// The documented $(spicrawl browser url -q) prints the bare URL although
+// stdout is piped; an explicit --json still gets JSON.
+func TestBrowserURLQuietPrintsBareURLWhenPiped(t *testing.T) {
+	srv := (&fakeTokenAPI{}).server(t)
+	out, errb, code := runCLIPiped(t, srv.URL, "-q", "browser", "url")
+	if code != 0 || !strings.HasPrefix(out, "ws://") || strings.Count(out, "\n") != 1 {
+		t.Fatalf("exit %d stdout %q stderr %q", code, out, errb)
+	}
+	if out, _, _ := runCLIPiped(t, srv.URL, "-q", "--json", "browser", "url"); !strings.HasPrefix(out, "{") {
+		t.Errorf("-q --json: %q", out)
+	}
+}
diff --git a/internal/cmd/initcmd.go b/internal/cmd/initcmd.go
index bc5de6f..b7bc085 100644
--- a/internal/cmd/initcmd.go
+++ b/internal/cmd/initcmd.go
@@ -22,6 +22,7 @@ var initFlags struct {
 	useEnv   bool
 	agentsMD bool
 	dir      string
+	force    bool
 }
 
 // Swapped out by tests.
@@ -43,6 +44,10 @@ With the default base URL (the hosted API) the MCP URL is ` + agentPublicMCPURL
 and the skill ` + docsPublicURL + agentSkillFile + `. $` + docsEnvURL + ` sets the
 docs URL the skill is read from.
 
+Changed files are copied to <file>.bak first and symlinked configs are written
+through. An existing "spicrawl" MCP entry that differs from the one to write is
+not replaced unless you pass --force.
+
 Without a terminal on stdin, --yes is required. See "spicrawl mcp install
 --help" for how the API key is referenced in each client's config.`,
 	Example: `  spicrawl init
@@ -62,6 +67,7 @@ func init() {
 	f.BoolVar(&initFlags.useEnv, "use-env", true, "reference $SPICRAWL_API_KEY instead of embedding the key, where the client supports it")
 	f.BoolVar(&initFlags.agentsMD, "agents-md", false, "also add a Spicrawl section to AGENTS.md")
 	f.StringVar(&initFlags.dir, "dir", "", "project directory (default: current directory)")
+	f.BoolVar(&initFlags.force, "force", false, "replace an existing spicrawl MCP entry that differs from the one to write")
 	rootCmd.AddCommand(initCmd)
 }
 
@@ -87,7 +93,7 @@ func runInit(cmd *cobra.Command, _ []string) error {
 	p.Info("MCP server: %s", ep.MCP)
 
 	key, _ := agentAPIKey()
-	opt := mcpOptions{URL: ep.MCP, UseEnv: initFlags.useEnv, Key: key}
+	opt := mcpOptions{URL: ep.MCP, UseEnv: initFlags.useEnv, Key: key, Force: initFlags.force}
 
 	var rs []*agentResult
 	for _, c := range clients {
diff --git a/internal/cmd/lines.go b/internal/cmd/lines.go
index b876c7a..ad996fd 100644
--- a/internal/cmd/lines.go
+++ b/internal/cmd/lines.go
@@ -2,6 +2,7 @@ package cmd
 
 import (
 	"bufio"
+	"context"
 	"io"
 	"os"
 	"strings"
@@ -10,20 +11,24 @@ import (
 // readLines returns the non-empty, non-comment lines of path ("-" = stdin).
 // Used for URL lists by `scrape -` and `batch submit`.
 func readLines(path string) ([]string, error) {
-	var r io.Reader = os.Stdin
-	if path != "-" {
-		f, err := os.Open(path)
-		if err != nil {
-			return nil, err
-		}
-		defer f.Close()
-		r = f
+	if path == "-" {
+		return scanLines(os.Stdin)
+	}
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
 	}
+	defer f.Close()
+	return scanLines(f)
+}
+
+func scanLines(r io.Reader) ([]string, error) {
 	var out []string
 	sc := bufio.NewScanner(r)
 	sc.Buffer(make([]byte, 64*1024), 1024*1024)
 	for sc.Scan() {
-		line := strings.TrimSpace(sc.Text())
+		// A UTF-8 BOM (Windows editors, `cat a b`) would end up in the URL.
+		line := strings.TrimSpace(strings.TrimPrefix(sc.Text(), "\uFEFF"))
 		if line == "" || strings.HasPrefix(line, "#") {
 			continue
 		}
@@ -31,3 +36,25 @@ func readLines(path string) ([]string, error) {
 	}
 	return out, sc.Err()
 }
+
+// readStdinLinesCtx is readLines("-") that returns ctx's error as soon as ctx
+// is cancelled, so Ctrl-C works while stdin is idle. The reader goroutine is
+// left blocked; the process is about to exit.
+func readStdinLinesCtx(ctx context.Context) ([]string, error) {
+	type result struct {
+		lines []string
+		err   error
+	}
+	in := os.Stdin
+	ch := make(chan result, 1)
+	go func() {
+		lines, err := scanLines(in)
+		ch <- result{lines, err}
+	}()
+	select {
+	case r := <-ch:
+		return r.lines, r.err
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	}
+}
diff --git a/internal/cmd/mcp_fix_test.go b/internal/cmd/mcp_fix_test.go
new file mode 100644
index 0000000..dd83e6c
--- /dev/null
+++ b/internal/cmd/mcp_fix_test.go
@@ -0,0 +1,95 @@
+package cmd
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestMCPInstallBacksUpAndWritesThroughSymlink(t *testing.T) {
+	dir, _ := agentTestEnv(t)
+	real := filepath.Join(dir, "dotfiles", "mcp.json")
+	orig := `{"mcpServers": {"other": {"command": "x"}}}`
+	agentWrite(t, real, orig)
+	link := filepath.Join(dir, ".mcp.json")
+	if err := os.Symlink(real, link); err != nil {
+		t.Skip("symlinks unavailable:", err)
+	}
+
+	rs, errOut, code := agentRun(t, "mcp", "install", "--client", "claude", "--dir", dir)
+	if code != 0 || rs[0].Action != "updated" {
+		t.Fatalf("exit %d %+v: %s", code, rs, errOut)
+	}
+	if fi, err := os.Lstat(link); err != nil || fi.Mode()&os.ModeSymlink == 0 {
+		t.Errorf("symlink was replaced: %v %v", fi, err)
+	}
+	servers := agentReadJSON(t, real)["mcpServers"].(map[string]any)
+	if _, ok := servers["spicrawl"]; !ok || servers["other"] == nil {
+		t.Errorf("target not merged: %v", servers)
+	}
+	if bak, _ := os.ReadFile(real + ".bak"); string(bak) != orig {
+		t.Errorf("backup = %q, want the original", bak)
+	}
+	if rs[0].Backup != real+".bak" {
+		t.Errorf("Backup = %q", rs[0].Backup)
+	}
+}
+
+func TestMCPInstallRefusesDifferentEntryUnlessForce(t *testing.T) {
+	dir, _ := agentTestEnv(t)
+	path := filepath.Join(dir, ".mcp.json")
+	orig := `{"mcpServers": {"spicrawl": {"type": "http", "url": "https://mine.example/mcp", "headers": {"Authorization": "Bearer sk-secret"}}}}`
+	agentWrite(t, path, orig)
+
+	_, errOut, code := agentRun(t, "mcp", "install", "--client", "claude", "--dir", dir)
+	if code != 2 || !strings.Contains(errOut, "--force") || !strings.Contains(errOut, "mine.example") {
+		t.Fatalf("exit %d, want refusal with a diff: %s", code, errOut)
+	}
+	if strings.Contains(errOut, "sk-secret") {
+		t.Error("diff leaked the literal key")
+	}
+	if b, _ := os.ReadFile(path); string(b) != orig {
+		t.Error("file changed without --force")
+	}
+
+	if _, errOut, code = agentRun(t, "mcp", "install", "--client", "claude", "--dir", dir, "--force"); code != 0 {
+		t.Fatalf("--force: exit %d: %s", code, errOut)
+	}
+	if got := agentReadJSON(t, path)["mcpServers"].(map[string]any)["spicrawl"].(map[string]any)["url"]; got != agentTestMCPURL {
+		t.Errorf("url = %v", got)
+	}
+	if bak, _ := os.ReadFile(path + ".bak"); string(bak) != orig {
+		t.Errorf("backup = %q", bak)
+	}
+}
+
+func TestMCPInstallAcceptsJSONCAndBOM(t *testing.T) {
+	dir, _ := agentTestEnv(t)
+	path := filepath.Join(dir, ".vscode", "mcp.json")
+	// A BOM, both comment styles, a trailing comma, and "//" inside a string.
+	orig := "\xef\xbb\xbf{\n  // my servers\n  \"servers\": {\n    \"other\": {\"url\": \"http://x//y\", /* inline */ },\n  },\n}\n"
+	agentWrite(t, path, orig)
+
+	rs, errOut, code := agentRun(t, "mcp", "install", "--client", "vscode", "--dir", dir)
+	if code != 0 || rs[0].Action != "updated" {
+		t.Fatalf("exit %d %+v: %s", code, rs, errOut)
+	}
+	if !strings.Contains(errOut, "comments") {
+		t.Errorf("no warning about dropped comments: %s", errOut)
+	}
+	servers := agentReadJSON(t, path)["servers"].(map[string]any)
+	if servers["spicrawl"] == nil || servers["other"].(map[string]any)["url"] != "http://x//y" {
+		t.Errorf("servers = %v", servers)
+	}
+	if bak, _ := os.ReadFile(path + ".bak"); string(bak) != orig {
+		t.Error("backup does not hold the original, comments included")
+	}
+
+	// A BOM alone is not lossy: no warning, and a second run is a no-op.
+	bom := filepath.Join(dir, "b", ".vscode", "mcp.json")
+	agentWrite(t, bom, "\xef\xbb\xbf{\"servers\": {}}")
+	if _, errOut, code = agentRun(t, "mcp", "install", "--client", "vscode", "--dir", filepath.Join(dir, "b")); code != 0 || strings.Contains(errOut, "comments") {
+		t.Errorf("BOM only: exit %d: %s", code, errOut)
+	}
+}
diff --git a/internal/cmd/mcpcmd.go b/internal/cmd/mcpcmd.go
index f1cd7f4..06c49d4 100644
--- a/internal/cmd/mcpcmd.go
+++ b/internal/cmd/mcpcmd.go
@@ -1,11 +1,13 @@
 package cmd
 
 import (
+	"bytes"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
 	"os"
+	"regexp"
 	"strconv"
 	"strings"
 
@@ -21,6 +23,7 @@ var mcpFlags struct {
 	url    string
 	useEnv bool
 	dir    string
+	force  bool
 }
 
 var mcpCmd = &cobra.Command{
@@ -33,7 +36,12 @@ var mcpInstallCmd = &cobra.Command{
 	Short: "Add the hosted Spicrawl MCP server to a client's config",
 	Long: `Merge a "spicrawl" server entry into an agent client's MCP config, keeping
 every other server and key in the file. Re-running is safe: an entry that is
-already correct is reported as unchanged.
+already correct is reported as unchanged. A file that is changed is first copied
+to <file>.bak, and a symlinked config is written through to its target. An
+existing "spicrawl" entry that differs from the one to write (say, one you
+customised) is not replaced unless you pass --force; the difference is shown.
+VS Code files may be JSONC (comments, trailing commas); comments do not survive
+a rewrite, so a warning is printed and the .bak copy keeps them.
 
 The server URL is --mcp-url, else $SPICRAWL_MCP_URL, else <API origin>/mcp, where
 the API origin is the scheme and host of the resolved base URL (--base-url,
@@ -69,6 +77,7 @@ func init() {
 	f.StringVar(&mcpFlags.url, "mcp-url", "", "MCP server URL (default: $"+agentEnvMCPURL+", then <API origin>/mcp from the base URL; "+agentPublicMCPURL+" for the hosted API)")
 	f.BoolVar(&mcpFlags.useEnv, "use-env", true, "reference $SPICRAWL_API_KEY instead of embedding the key, where the client supports it")
 	f.StringVar(&mcpFlags.dir, "dir", "", "project directory (default: current directory)")
+	f.BoolVar(&mcpFlags.force, "force", false, "replace an existing spicrawl entry that differs from the one to write")
 	mcpCmd.AddCommand(mcpInstallCmd)
 	rootCmd.AddCommand(mcpCmd)
 }
@@ -79,6 +88,7 @@ type mcpOptions struct {
 	UseEnv bool
 	Key    string // literal key, used only when an entry must embed it
 	Print  bool
+	Force  bool // replace an existing spicrawl entry that differs
 }
 
 func runMCPInstall(cmd *cobra.Command, _ []string) error {
@@ -96,7 +106,7 @@ func runMCPInstall(cmd *cobra.Command, _ []string) error {
 		return err
 	}
 	key, _ := agentAPIKey()
-	opt := mcpOptions{URL: ep.MCP, UseEnv: mcpFlags.useEnv, Key: key, Print: mcpFlags.print}
+	opt := mcpOptions{URL: ep.MCP, UseEnv: mcpFlags.useEnv, Key: key, Print: mcpFlags.print, Force: mcpFlags.force}
 
 	if mcpFlags.print {
 		return mcpPrint(p.JSON, clients, s, opt)
@@ -237,9 +247,9 @@ func mcpMergeJSON(c *agentClient, path string, s agentScope, opt mcpOptions) ([]
 	if err != nil && !os.IsNotExist(err) {
 		return nil, secret, false, fmt.Errorf("read %s: %w", path, err)
 	}
-	root, err := agentParseObject(old)
+	root, lossy, err := mcpParseConfig(old)
 	if err != nil {
-		return nil, secret, false, fmt.Errorf("parse %s: %v (it must be plain JSON without comments; fix it or merge the output of --print by hand)", path, err)
+		return nil, secret, false, fmt.Errorf("parse %s: %v (fix it or merge the output of --print by hand)", path, err)
 	}
 	serversKey := "mcpServers"
 	if c.MCPFormat == agentVSCodeJSON {
@@ -254,6 +264,11 @@ func mcpMergeJSON(c *agentClient, path string, s agentScope, opt mcpOptions) ([]
 	desired := agentRaw(entry)
 	current, had := servers.get(agentServerName)
 	changed := !had || !agentJSONEqual(current, desired)
+	if had && changed && !opt.Force {
+		o, _ := agentIndent(current)
+		n, _ := agentIndent(desired)
+		return nil, secret, false, mcpRefuse(path, string(o), string(n))
+	}
 	servers.set(agentServerName, desired)
 	root.set(serversKey, agentRaw(servers))
 
@@ -283,10 +298,116 @@ func mcpMergeJSON(c *agentClient, path string, s agentScope, opt mcpOptions) ([]
 	if !changed {
 		return old, secret, false, nil
 	}
+	if lossy {
+		Printer().Warn("%s has comments, which are dropped when it is rewritten (the original is kept as %s.bak)", path, path)
+	}
 	out, err := agentIndent(root)
 	return out, secret, true, err
 }
 
+// mcpParseConfig parses a client's JSON config. It accepts a UTF-8 BOM and,
+// as VS Code does for mcp.json, comments and trailing commas. lossy reports
+// that comments were present: rewriting the file drops them.
+func mcpParseConfig(b []byte) (root *agentJSONObject, lossy bool, err error) {
+	b = bytes.TrimPrefix(b, []byte("\xef\xbb\xbf"))
+	if root, err = agentParseObject(b); err == nil {
+		return root, false, nil
+	}
+	clean, comments := mcpStripJSONC(b)
+	if root2, err2 := agentParseObject(clean); err2 == nil {
+		return root2, comments, nil
+	}
+	return nil, false, err
+}
+
+// mcpStripJSONC removes // and /* */ comments and trailing commas, leaving
+// string contents alone, and reports whether it removed a comment.
+func mcpStripJSONC(b []byte) ([]byte, bool) {
+	out := make([]byte, 0, len(b))
+	comment, comma := false, -1 // comma: index in out of a comma not yet followed by a value
+	for i := 0; i < len(b); i++ {
+		c := b[i]
+		switch {
+		case c == '"':
+			j := i + 1
+			for j < len(b) && b[j] != '"' {
+				if b[j] == '\\' {
+					j++
+				}
+				j++
+			}
+			j = min(j, len(b)-1)
+			out, i, comma = append(out, b[i:j+1]...), j, -1
+		case c == '/' && i+1 < len(b) && b[i+1] == '/':
+			for i < len(b) && b[i] != '\n' {
+				i++
+			}
+			i--
+			comment = true
+		case c == '/' && i+1 < len(b) && b[i+1] == '*':
+			end := bytes.Index(b[i+2:], []byte("*/"))
+			if end < 0 {
+				return b, false // unterminated: let the parser report it
+			}
+			i += end + 3
+			comment = true
+		case c == ',':
+			comma = len(out)
+			out = append(out, c)
+		case c == '}' || c == ']':
+			if comma >= 0 {
+				out[comma] = ' '
+			}
+			out, comma = append(out, c), -1
+		case c == ' ' || c == '\t' || c == '\n' || c == '\r':
+			out = append(out, c)
+		default:
+			out, comma = append(out, c), -1
+		}
+	}
+	return out, comment
+}
+
+// mcpKeyRE matches a literal bearer token (not a ${VAR} or <PLACEHOLDER>).
+var mcpKeyRE = regexp.MustCompile(`(?i)(bearer )[^"'$<\s][^"'\s]*`)
+
+// mcpRefuse is the error for an existing spicrawl entry that differs from the
+// one we would write: it shows the difference briefly, with API keys masked.
+func mcpRefuse(path, oldText, newText string) error {
+	norm := func(t string) (lines []string) {
+		for _, l := range strings.Split(t, "\n") {
+			if l = strings.TrimRight(l, ", \t\r"); strings.TrimSpace(l) != "" {
+				lines = append(lines, l)
+			}
+		}
+		return
+	}
+	o, n := norm(oldText), norm(newText)
+	has := func(ls []string, l string) bool {
+		for _, x := range ls {
+			if x == l {
+				return true
+			}
+		}
+		return false
+	}
+	var d []string
+	for _, l := range o {
+		if !has(n, l) {
+			d = append(d, "  - "+mcpKeyRE.ReplaceAllString(l, "${1}****"))
+		}
+	}
+	for _, l := range n {
+		if !has(o, l) {
+			d = append(d, "  + "+mcpKeyRE.ReplaceAllString(l, "${1}****"))
+		}
+	}
+	if len(d) > 12 {
+		d = append(d[:12], fmt.Sprintf("  … %d more lines", len(d)-12))
+	}
+	return Usagef("%s: a %q server entry already exists and differs from the one to write (- existing, + new):\n%s\nre-run with --force to replace it (the file is copied to %s.bak first)", path, agentServerName, strings.Join(d, "\n"), path)
+}
+
 // mcpTOMLBlock renders the [mcp_servers.spicrawl] table.
 func mcpTOMLBlock(opt mcpOptions) ([]string, bool, error) {
 	lines := []string{
@@ -937,6 +1058,9 @@ func mcpMergeTOML(path string, _ agentScope, opt mcpOptions) ([]byte, bool, bool
 	if out == string(old) {
 		return old, secret, false, nil
 	}
+	if (table >= 0 || inline >= 0) && !opt.Force && out != strings.TrimSuffix(text, "\n")+"\n" {
+		return nil, secret, false, mcpRefuse(path, text, out)
+	}
 	// Never write something we would refuse to read back.
 	check, err := tomlScan(strings.Split(strings.TrimSuffix(out, "\n"), "\n"))
 	if err == nil {
diff --git a/internal/cmd/root.go b/internal/cmd/root.go
index f479d5b..bf3e0bc 100644
--- a/internal/cmd/root.go
+++ b/internal/cmd/root.go
@@ -11,6 +11,7 @@ import (
 	"io"
 	"os"
 	"os/signal"
+	"strings"
 	"time"
 
 	"github.com/spf13/cobra"
@@ -91,7 +92,9 @@ func Client() (*api.Client, error) {
 	if r.APIKey == "" {
 		return nil, ErrNoKey
 	}
-	return api.New(r.BaseURL, r.APIKey, flagTimeout), nil
+	c := api.New(r.BaseURL, r.APIKey, flagTimeout)
+	c.Notify = Printer().Info // retry waits; muted by --quiet
+	return c, nil
 }
 
 // ErrNoKey is returned when no API key is configured anywhere.
@@ -122,13 +125,47 @@ func Execute() int {
 	// second Execute in one process (tests) would inherit the first run's
 	// cancelled context. Set it on every command explicitly.
 	setContextTree(rootCmd, ctx)
+	rootCmd.InitDefaultCompletionCmd() // cobra adds it lazily; groups are fixed up below
+	requireKnownSubcommand(rootCmd)
 	err := rootCmd.ExecuteContext(ctx)
 	if err == nil {
 		return exitcode.OK
 	}
+	if ctx.Err() != nil { // Ctrl-C: whatever error the command made of it, say so briefly
+		Printer().Info("interrupted")
+		return exitcode.Interrupted
+	}
 	return report(err)
 }
 
+// requireKnownSubcommand makes a typo under a group command (batch, sessions,
+// mcp, ...) a usage error. cobra prints help and exits 0 for a group with no
+// Run, whatever follows it, and only suggests corrections for the root.
+func requireKnownSubcommand(c *cobra.Command) {
+	for _, sub := range c.Commands() {
+		requireKnownSubcommand(sub)
+	}
+	if c.Parent() == nil || !c.HasSubCommands() || c.Runnable() {
+		return
+	}
+	c.Args = func(cmd *cobra.Command, args []string) error {
+		if len(args) == 0 {
+			return nil
+		}
+		msg := fmt.Sprintf("unknown command %q for %q", args[0], cmd.CommandPath())
+		if cmd.SuggestionsMinimumDistance <= 0 {
+			cmd.SuggestionsMinimumDistance = 2 // cobra's own default, which it only applies for the root
+		}
+		if s := cmd.SuggestionsFor(args[0]); len(s) > 0 {
+			msg += "; did you mean " + strings.Join(s, " or ") + "?"
+		}
+		return Usagef("%s", msg)
+	}
+	c.RunE = func(cmd *cobra.Command, _ []string) error { return cmd.Help() }
+	// Runnable would add a "spicrawl batch [flags]" line to the help; keep it as before.
+	c.SetUsageTemplate(strings.Replace(c.UsageTemplate(), "{{if .Runnable}}", "{{if and .Runnable (not .HasAvailableSubCommands)}}", 1))
+}
+
 func setContextTree(c *cobra.Command, ctx context.Context) {
 	c.SetContext(ctx)
 	for _, sub := range c.Commands() {
@@ -160,17 +197,19 @@ func ExitCode(err error) int {
 		ue *UsageError
 		ne *api.NetworkError
 		te *api.TimeoutError
+		ce *api.ConnectionLostError
+		re *api.RedirectError
 		fe *config.FileError
 		ee *ExitError
 	)
 	switch {
 	case errors.As(err, &ee):
 		return ee.Code
-	case errors.As(err, &ue), errors.As(err, &fe):
+	case errors.As(err, &ue), errors.As(err, &fe), errors.As(err, &re):
 		return exitcode.Usage
 	case errors.Is(err, ErrNoKey):
 		return exitcode.Auth
-	case errors.As(err, &te):
+	case errors.As(err, &te), errors.As(err, &ce):
 		return exitcode.Timeout
 	case errors.As(err, &ne):
 		return exitcode.Network
diff --git a/internal/cmd/root_fix_test.go b/internal/cmd/root_fix_test.go
new file mode 100644
index 0000000..08e83c5
--- /dev/null
+++ b/internal/cmd/root_fix_test.go
@@ -0,0 +1,84 @@
+package cmd
+
+import (
+	"io"
+	"net/http"
+	"os"
+	"strings"
+	"sync/atomic"
+	"testing"
+
+	"github.com/OfficialSpicrawl/cli/internal/exitcode"
+)
+
+func TestUnknownGroupSubcommandIsUsageError(t *testing.T) {
+	for _, group := range []string{"batch", "sessions", "browser", "mcp", "skill", "completion"} {
+		_, errb, code := runCLI(t, "http://127.0.0.1:1", group, "lst")
+		if code != exitcode.Usage || !strings.Contains(errb, "unknown command") {
+			t.Errorf("%s lst: exit %d, want %d: %s", group, code, exitcode.Usage, errb)
+		}
+	}
+	_, errb, _ := runCLI(t, "http://127.0.0.1:1", "batch", "lst")
+	if !strings.Contains(errb, "did you mean get or list") {
+		t.Errorf("no suggestion: %s", errb)
+	}
+	rootCmd.SetOut(io.Discard) // the group's help
+	defer rootCmd.SetOut(nil)
+	if _, errb, code := runCLI(t, "http://127.0.0.1:1", "batch"); code != 0 {
+		t.Errorf("bare group should still print help, exit %d: %s", code, errb)
+	}
+}
+
+func TestInterruptExits130(t *testing.T) {
+	if os.PathSeparator == '\\' {
+		t.Skip("cannot signal self on Windows")
+	}
+	inflight, release := make(chan struct{}), make(chan struct{})
+	srv, _ := newRecordingServer(t, func(_ http.ResponseWriter, _ *http.Request) {
+		select {
+		case inflight <- struct{}{}:
+		default:
+		}
+		<-release
+	})
+	defer close(release)
+	go func() {
+		<-inflight // Execute is running and its signal handler is installed
+		p, _ := os.FindProcess(os.Getpid())
+		_ = p.Signal(os.Interrupt)
+	}()
+	_, errb, code := runCLI(t, srv.URL, "usage")
+	if code != exitcode.Interrupted || strings.Contains(errb, "context canceled") {
+		t.Errorf("exit %d, want %d, stderr %q", code, exitcode.Interrupted, errb)
+	}
+}
+
+// A gateway 504 page is an API/infra error: not the target's status (exit 6
+// with --allowed-status advice) and not resent.
+func TestGatewayPageWithOriginalStatus(t *testing.T) {
+	var n atomic.Int32
+	srv, _ := newRecordingServer(t, func(w http.ResponseWriter, _ *http.Request) {
+		n.Add(1)
+		w.Header().Set("Content-Type", "text/html")
+		w.WriteHeader(http.StatusGatewayTimeout)
+		_, _ = io.WriteString(w, "<html>504 Gateway Time-out</html>")
+	})
+	_, errb, code := runCLI(t, srv.URL, "scrape", "https://example.com", "--original-status", "--retry", "3")
+	if code != exitcode.Internal || strings.Contains(errb, "allowed-status") {
+		t.Errorf("exit %d, want %d: %s", code, exitcode.Internal, errb)
+	}
+	if got := n.Load(); got != 1 {
+		t.Errorf("%d requests, want 1", got)
+	}
+}
+
+func TestDropAfterSendIsExit12(t *testing.T) {
+	srv, _ := newRecordingServer(t, func(w http.ResponseWriter, _ *http.Request) {
+		c, _, _ := w.(http.Hijacker).Hijack()
+		c.Close()
+	})
+	_, errb, code := runCLI(t, srv.URL, "scrape", "https://example.com")
+	if code != exitcode.Timeout || !strings.Contains(errb, "spicrawl logs") || strings.Contains(errb, "nothing was sent") {
+		t.Errorf("exit %d, want %d: %s", code, exitcode.Timeout, errb)
+	}
+}
diff --git a/internal/cmd/root_test.go b/internal/cmd/root_test.go
index 507c6d3..22d6d2b 100644
--- a/internal/cmd/root_test.go
+++ b/internal/cmd/root_test.go
@@ -5,6 +5,7 @@ import (
 	"net/http"
 	"os"
 	"strings"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -24,7 +25,7 @@ func TestExitCodesJSON(t *testing.T) {
 		t.Fatalf("%d entries, want %d", len(got), len(exitcode.Table))
 	}
 	for i, e := range got {
-		if e.Code != i || e.Name == "" || e.Meaning == "" {
+		if e.Code != exitcode.Table[i].Code || e.Name == "" || e.Meaning == "" {
 			t.Errorf("entry %d: %+v", i, e)
 		}
 	}
@@ -75,7 +76,8 @@ func TestUnavailableCapabilityIsEngine(t *testing.T) {
 
 func TestTimeoutAfterSendIsExit12(t *testing.T) {
 	release := make(chan struct{})
-	srv, reqs := newRecordingServer(t, func(_ http.ResponseWriter, _ *http.Request) { <-release })
+	var n atomic.Int32 // the recorder's slice is only safe to read under its lock
+	srv, _ := newRecordingServer(t, func(_ http.ResponseWriter, _ *http.Request) { n.Add(1); <-release })
 	defer close(release)
 	_, errb, code := runCLI(t, srv.URL, "--timeout", "150ms", "scrape", "https://example.com")
 	if code != exitcode.Timeout {
@@ -85,8 +87,8 @@ func TestTimeoutAfterSendIsExit12(t *testing.T) {
 		t.Errorf("stderr should point at spicrawl logs: %s", errb)
 	}
 	time.Sleep(20 * time.Millisecond)
-	if n := len(*reqs); n != 1 {
-		t.Errorf("%d requests sent, want 1 (a timed-out POST must not be retried)", n)
+	if got := n.Load(); got != 1 {
+		t.Errorf("%d requests sent, want 1 (a timed-out POST must not be retried)", got)
 	}
 }
 
diff --git a/internal/cmd/scrape.go b/internal/cmd/scrape.go
index 3ea610e..930bcaf 100644
--- a/internal/cmd/scrape.go
+++ b/internal/cmd/scrape.go
@@ -54,8 +54,14 @@ Output
   --ai, --autoparse, --links, --network-capture, --screenshot) the envelope is
   printed as-is. When it answers with the raw document, the CLI wraps it:
     {"url","final_url","status","engine","proxy_source","credits_charged",
-     "request_cost","cache_state","request_id","warnings","content_type","content"}
-  where status is the target site's status (X-Target-Status).
+     "credits","request_cost","cache_state","request_id","warnings",
+     "content_type","content"}
+  where status is the target site's status (X-Target-Status). The two shapes
+  share url, final_url, status, engine, proxy_source, warnings and content;
+  the envelope names the credits "credits", so the wrapper repeats
+  credits_charged under that name. Only the wrapper has request_cost,
+  cache_state, request_id and content_type (the envelope leaves them to the
+  response headers); only the envelope has headers, truncated, data, links...
   --jsonl prints that same object as one compact JSON line, in every mode
   (also on a terminal), so a single scrape can be appended to a .jsonl file.
 
@@ -64,8 +70,8 @@ Target status
   returns HTTP 200 with the site's status in X-Target-Status (envelope
   "status") and the site's body. The CLI treats any target status outside
   2xx as a failure unless it is listed in --allowed-status: the document is
-  still printed (or written with -o), stderr gets "target returned 503" and
-  the exit code is 6 (upstream). In JSON mode the object also carries
+  still printed (not written with -o, see Files), stderr gets "target returned
+  503" and the exit code is 6 (upstream). In JSON mode the object also carries
   "target_error": "target returned 503". --allowed-status 404 makes a 404 page
   exit 0. --original-status only moves the target's status onto the API's HTTP
   status line; the CLI reads the target status either way, so exit codes and
@@ -76,11 +82,19 @@ Target status
   "content"; in human mode -o FILE is required.
 
 Files
-  -o FILE writes the document (raw bytes for pdf) to FILE instead of stdout. In
-  JSON mode stdout then carries the metadata object without the written field,
-  plus "output": FILE. Screenshots in the envelope are saved next to FILE as
-  <FILE stem>.<label>.<format> (or into --screenshot-dir as <label>.<format>);
-  their base64 "data" is replaced by "file" in the printed JSON.
+  -o FILE writes the document (raw bytes for pdf) to FILE instead of stdout;
+  "-o -" is stdout. The write is atomic (temp file in the same directory, then
+  rename). In JSON mode stdout then carries the metadata object without the
+  written field, plus "output": FILE. Screenshots in the envelope are saved
+  next to FILE as <FILE stem>.<label>.<format> (or into --screenshot-dir as
+  <label>.<format>, repeated labels get -2, -3...); their base64 "data" is
+  replaced by "file" in the printed JSON.
+
+  A target failure (status outside 2xx and --allowed-status) writes neither
+  FILE nor the screenshots next to it, so an earlier good FILE survives; the
+  exit code is 6 and in JSON mode the document stays in the printed object.
+  If FILE (or a screenshot) cannot be written, the result is printed to stdout
+  as JSON instead of being lost, and the exit code is 1.
 
 Many URLs
   "spicrawl scrape -" reads URLs from stdin, one per line (blank lines and #
@@ -90,7 +104,9 @@ Many URLs
   URL in the input), or {"index","url","error"} where error is the API's
   problem document. A target status outside 2xx/--allowed-status keeps the
   result and adds "target_error". Exit code is 0 when every URL succeeded,
-  else the code of the first failure.`,
+  else the code of the first failure. If stdout cannot be written the run
+  stops at once (exit 1) instead of billing the remaining URLs; Ctrl-C also
+  stops it, including while stdin is idle.`,
 	Example: `  # A page as clean markdown, for an LLM context window
   spicrawl scrape https://example.com/blog/launch --format markdown
 
@@ -121,7 +137,7 @@ Many URLs
 func init() {
 	scrapeFlagSet = addScrapeFlags(scrapeCmd)
 	f := scrapeCmd.Flags()
-	f.StringVarP(&scrapeOutput, "output", "o", "", "write the document to FILE instead of stdout (screenshots are saved next to it)")
+	f.StringVarP(&scrapeOutput, "output", "o", "", "write the document to FILE instead of stdout, '-' = stdout (not written when the target fails; screenshots are saved next to it)")
 	f.StringVar(&scrapeScreenshotDir, "screenshot-dir", "", "directory to save screenshots in (default: next to -o FILE)")
 	f.BoolVar(&scrapeJSONL, "jsonl", false, "print the result as one compact JSON line, even on a terminal (always on for '-')")
 	f.IntVar(&scrapeConcurrency, "concurrency", 4, "with '-': parallel requests")
@@ -146,7 +162,11 @@ func scrapeRun(cmd *cobra.Command, args []string) error {
 		return scrapeRunMany(cmd.Context(), p, body)
 	}
 	machine := p.JSON || scrapeJSONL
-	if format, _ := body["response_format"].(string); format == "pdf" && !machine && scrapeOutput == "" {
+	outFile := scrapeOutput // "-" is stdout, as everywhere else
+	if outFile == "-" {
+		outFile = ""
+	}
+	if format, _ := body["response_format"].(string); format == "pdf" && !machine && outFile == "" {
 		return Usagef("--format pdf is binary: pass -o FILE (or --json to get it base64-encoded)")
 	}
 	client, err := Client()
@@ -163,40 +183,55 @@ func scrapeRun(cmd *cobra.Command, args []string) error {
 		return err
 	}
 	targetErr := res.checkTarget(body)
+	// An error page must not replace a good file from an earlier run: -o (and
+	// the screenshots next to it) is written only for a target that is ok.
+	write := outFile != ""
+	if write && targetErr != nil {
+		write = false
+		p.Warn("not writing %s: the target failed (--allowed-status accepts it)", outFile)
+	}
+	// A failed write must not lose the billed result: it is printed instead.
+	var writeErr error
+	printInstead := func(err error) {
+		writeErr = fmt.Errorf("%w (the result is printed to stdout instead)", err)
+		machine = true
+	}
 
 	// Screenshots: save when there is somewhere to put them.
 	if shots := scrapeScreenshots(res.obj); len(shots) > 0 {
 		dir, stem := scrapeScreenshotDir, ""
-		if dir == "" && scrapeOutput != "" {
-			dir = filepath.Dir(scrapeOutput)
-			stem = strings.TrimSuffix(filepath.Base(scrapeOutput), filepath.Ext(scrapeOutput)) + "."
+		if dir == "" && write {
+			dir = filepath.Dir(outFile)
+			stem = strings.TrimSuffix(filepath.Base(outFile), filepath.Ext(outFile)) + "."
 		}
 		if dir != "" {
 			paths, err := scrapeSaveScreenshots(shots, dir, stem)
-			if err != nil {
-				return err
-			}
-			res.modified = true
+			res.modified = res.modified || len(paths) > 0
 			for _, path := range paths {
 				p.Info("saved screenshot %s", path)
 			}
+			if err != nil {
+				printInstead(err)
+			}
 		} else if !machine {
-			p.Info("%d screenshot(s) not saved: pass -o FILE or --screenshot-dir DIR", len(shots))
+			p.Info("%d screenshot(s) not saved: pass --screenshot-dir DIR, or -o FILE for a successful target", len(shots))
 		}
 	}
 
 	doc, docField := res.document(body)
-	if scrapeOutput != "" {
-		if err := os.WriteFile(scrapeOutput, doc, 0o644); err != nil {
-			return fmt.Errorf("write %s: %w", scrapeOutput, err)
+	if write {
+		if err := writeFileAtomic(outFile, doc); err != nil {
+			write = false
+			printInstead(fmt.Errorf("write %s: %w", outFile, err))
+		} else {
+			p.Info("wrote %d bytes to %s", len(doc), outFile)
 		}
-		p.Info("wrote %d bytes to %s", len(doc), scrapeOutput)
 	}
 
 	if machine {
-		if scrapeOutput != "" {
+		if write {
 			delete(res.obj, docField)
-			res.obj["output"] = scrapeOutput
+			res.obj["output"] = outFile
 			res.modified = true
 		}
 		var err error
@@ -217,10 +252,13 @@ func scrapeRun(cmd *cobra.Command, args []string) error {
 		if err != nil {
 			return err
 		}
+		if writeErr != nil {
+			return writeErr
+		}
 		return targetErr
 	}
 
-	if scrapeOutput == "" {
+	if outFile == "" {
 		if !res.text {
 			return Usagef("the response is binary (%s): pass -o FILE", res.mediaType)
 		}
@@ -371,13 +409,15 @@ func scrapeResultOf(url string, resp *api.Response) (*scrapeResult, error) {
 	if warnings == nil {
 		warnings = []string{}
 	}
+	credits := scrapeHeaderInt(h, "X-Credits-Charged")
 	r.obj = map[string]any{
 		"url":             url,
 		"final_url":       h.Get("X-Final-Url"),
 		"status":          scrapeHeaderInt(h, "X-Target-Status"),
 		"engine":          h.Get("X-Engine"),
 		"proxy_source":    h.Get("X-Proxy-Source"),
-		"credits_charged": scrapeHeaderInt(h, "X-Credits-Charged"),
+		"credits_charged": credits,
+		"credits":         credits, // the envelope's name for it
 		"request_cost":    scrapeHeaderInt(h, "X-Request-Cost"),
 		"cache_state":     h.Get("Cache-State"),
 		"request_id":      h.Get("X-Request-Id"),
@@ -404,9 +444,12 @@ func (r *scrapeResult) document(body map[string]any) ([]byte, string) {
 	}
 	if scrapeWantsData(body) {
 		if data, ok := r.obj["data"]; ok && data != nil {
-			b, err := json.MarshalIndent(data, "", "  ")
-			if err == nil {
-				return append(b, '\n'), "data"
+			var buf bytes.Buffer
+			enc := json.NewEncoder(&buf)
+			enc.SetEscapeHTML(false) // a human reads <, > and & as they are
+			enc.SetIndent("", "  ")
+			if err := enc.Encode(data); err == nil {
+				return buf.Bytes(), "data"
 			}
 		}
 	}
@@ -501,27 +544,30 @@ func scrapeSaveScreenshots(shots []map[string]any, dir, prefix string) ([]string
 	if err := os.MkdirAll(dir, 0o755); err != nil {
 		return nil, fmt.Errorf("screenshot dir: %w", err)
 	}
-	seen := map[string]int{}
+	used := map[string]bool{} // lower-cased: macOS and Windows ignore case
 	var paths []string
 	for i, s := range shots {
 		raw, err := base64.StdEncoding.DecodeString(s["data"].(string))
 		if err != nil {
 			return paths, fmt.Errorf("screenshot %d: bad base64: %w", i, err)
 		}
-		label := scrapeSafeName(fmt.Sprint(s["label"]))
-		if label == "" || label == "<nil>" {
+		l, _ := s["label"].(string)
+		label := scrapeSafeName(l)
+		if label == "" {
 			label = "screenshot"
 		}
-		if n := seen[label]; n > 0 {
-			label = fmt.Sprintf("%s-%d", label, n+1)
+		// Unique per shot: "a", "a-2", "a" must not share a file.
+		base := label
+		for n := 2; used[strings.ToLower(label)]; n++ {
+			label = fmt.Sprintf("%s-%d", base, n)
 		}
-		seen[label]++
+		used[strings.ToLower(label)] = true
 		ext, _ := s["format"].(string)
 		if ext == "" {
 			ext = "png"
 		}
 		path := filepath.Join(dir, prefix+label+"."+scrapeSafeName(ext))
-		if err := os.WriteFile(path, raw, 0o644); err != nil {
+		if err := writeFileAtomic(path, raw); err != nil {
 			return paths, fmt.Errorf("write %s: %w", path, err)
 		}
 		delete(s, "data")
@@ -531,6 +577,35 @@ func scrapeSaveScreenshots(shots []map[string]any, dir, prefix string) ([]string
 	return paths, nil
 }
 
+// writeFileAtomic writes data to path through a temp file in the same
+// directory and a rename, so a failed write never truncates an existing file.
+// An existing file keeps its mode; devices and symlinks are written in place.
+func writeFileAtomic(path string, data []byte) error {
+	perm := os.FileMode(0o644)
+	if st, err := os.Lstat(path); err == nil {
+		if !st.Mode().IsRegular() {
+			return os.WriteFile(path, data, perm)
+		}
+		perm = st.Mode().Perm()
+	}
+	tmp := fmt.Sprintf("%s.%d.tmp", path, os.Getpid())
+	f, err := os.OpenFile(tmp, os.O_WRONLY|os.O_CREATE|os.O_EXCL, perm)
+	if err != nil {
+		return err
+	}
+	_, err = f.Write(data)
+	if cerr := f.Close(); err == nil {
+		err = cerr
+	}
+	if err == nil {
+		err = os.Rename(tmp, path)
+	}
+	if err != nil {
+		os.Remove(tmp)
+	}
+	return err
+}
+
 func scrapeSafeName(s string) string {
 	return strings.Map(func(r rune) rune {
 		switch {
@@ -549,7 +624,10 @@ func scrapeRunMany(ctx context.Context, p *output.Printer, base map[string]any)
 	if scrapeConcurrency < 1 {
 		return Usagef("--concurrency must be at least 1")
 	}
-	urls, err := readLines("-")
+	urls, err := readStdinLinesCtx(ctx)
+	if ctx.Err() != nil {
+		return ctx.Err()
+	}
 	if err != nil {
 		return Usagef("read stdin: %v", err)
 	}
@@ -566,10 +644,16 @@ func scrapeRunMany(ctx context.Context, p *output.Printer, base map[string]any)
 		url   string
 	}
 	jobs := make(chan job)
+	// runCtx ends with ctx (Ctrl-C) or when stdout stops accepting results:
+	// requests nobody can read are not worth billing.
+	runCtx, stop := context.WithCancel(ctx)
+	defer stop()
 	var (
 		mu        sync.Mutex
+		ok        int
 		failed    int
 		firstCode int
+		writeErr  error
 	)
 	emit := func(line map[string]any, code int) {
 		mu.Lock()
@@ -579,8 +663,14 @@ func scrapeRunMany(ctx context.Context, p *output.Printer, base map[string]any)
 			if firstCode == exitcode.OK {
 				firstCode = code
 			}
+		} else {
+			ok++
+		}
+		if writeErr == nil {
+			if writeErr = p.Line(line); writeErr != nil {
+				stop()
+			}
 		}
-		_ = p.Line(line)
 	}
 	one := func(j job) {
 		body := make(map[string]any, len(base)+1)
@@ -588,7 +678,7 @@ func scrapeRunMany(ctx context.Context, p *output.Printer, base map[string]any)
 			body[k] = v
 		}
 		body["url"] = j.url
-		resp, err := scrapeDo(ctx, client, body)
+		resp, err := scrapeDo(runCtx, client, body)
 		var res *scrapeResult
 		if err == nil {
 			res, err = scrapeResultOf(j.url, resp)
@@ -629,7 +719,7 @@ feed:
 	for i, u := range urls {
 		select {
 		case jobs <- job{index: i + 1, url: u}:
-		case <-ctx.Done():
+		case <-runCtx.Done():
 			break feed
 		}
 	}
@@ -637,7 +727,14 @@ feed:
 	wg.Wait()
 
 	if !p.JSON {
-		p.Info("%d ok, %d failed", len(urls)-failed, failed)
+		if notRun := len(urls) - ok - failed; notRun > 0 {
+			p.Info("%d ok, %d failed, %d not run", ok, failed, notRun)
+		} else {
+			p.Info("%d ok, %d failed", ok, failed)
+		}
+	}
+	if writeErr != nil {
+		return fmt.Errorf("write results to stdout: %w (stopped after %d of %d URLs)", writeErr, ok+failed, len(urls))
 	}
 	if ctx.Err() != nil {
 		return ctx.Err()
diff --git a/internal/cmd/scrape_fix_test.go b/internal/cmd/scrape_fix_test.go
new file mode 100644
index 0000000..1403686
--- /dev/null
+++ b/internal/cmd/scrape_fix_test.go
@@ -0,0 +1,227 @@
+package cmd
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/OfficialSpicrawl/cli/internal/output"
+)
+
+func TestScrapeBodyNullIsUsageError(t *testing.T) {
+	_, stderr, code := scrapeRunCLI(t, "http://127.0.0.1:1", "scrape", "https://example.com", "--body", "null")
+	if code != 2 || !strings.Contains(stderr, "--body") {
+		t.Fatalf("exit %d, stderr %s; want usage error 2", code, stderr)
+	}
+}
+
+func TestScrapeBodyDeepMerge(t *testing.T) {
+	srv, reqs := newRecordingServer(t, scrapeMarkdownHandler)
+	_, stderr, code := scrapeRunCLI(t, srv.URL, "scrape", "https://example.com",
+		"--body", `{"custom_headers":{"A":"1","B":"2"},"extract":{"title":{"selector":"h1","attr":"x"},"price":".p"}}`,
+		"--header", "B: 9", "--extract", `{"title":{"selector":"h2"}}`)
+	if code != 0 {
+		t.Fatalf("exit %d, stderr %s", code, stderr)
+	}
+	got, _ := json.Marshal(scrapeTestBody(t, reqs))
+	for _, want := range []string{
+		`"custom_headers":{"A":"1","B":"9"}`,
+		`"extract":{"price":".p","title":{"attr":"x","selector":"h2"}}`,
+	} {
+		if !strings.Contains(string(got), want) {
+			t.Errorf("body %s lacks %s", got, want)
+		}
+	}
+}
+
+// A write error on stdout must stop the run (no more billing) and exit non-zero.
+func TestScrapeStdinStdoutWriteError(t *testing.T) {
+	old := scrapePrinter
+	scrapePrinter = func() *output.Printer { p := Printer(); p.Out = failingWriter{}; return p }
+	t.Cleanup(func() { scrapePrinter = old })
+	srv, reqs := newRecordingServer(t, scrapeMarkdownHandler)
+	scrapeWithStdin(t, "https://a.example\nhttps://b.example\nhttps://c.example\n")
+	_, stderr, code := scrapeRunCLI(t, srv.URL, "scrape", "-", "--concurrency", "1")
+	if code == 0 || !strings.Contains(stderr, "write results to stdout") {
+		t.Fatalf("exit %d, stderr %s; want a write error", code, stderr)
+	}
+	if len(*reqs) != 1 {
+		t.Errorf("%d URLs were requested after stdout failed, want 1", len(*reqs))
+	}
+}
+
+type failingWriter struct{}
+
+func (failingWriter) Write([]byte) (int, error) { return 0, errors.New("no space left on device") }
+
+// Ctrl-C mid-run: exit 130 and a summary that does not call unfinished URLs ok.
+func TestScrapeStdinInterruptedSummary(t *testing.T) {
+	scrapeHumanMode(t)
+	n := 0
+	srv, _ := newRecordingServer(t, func(w http.ResponseWriter, r *http.Request) {
+		if n++; n == 1 {
+			scrapeMarkdownHandler(w, r)
+			return
+		}
+		self, _ := os.FindProcess(os.Getpid())
+		_ = self.Signal(os.Interrupt)
+		select { // the client aborts once the signal cancels its context
+		case <-r.Context().Done():
+		case <-time.After(5 * time.Second):
+		}
+	})
+	scrapeWithStdin(t, "https://a.example\nhttps://b.example\nhttps://c.example\n")
+	_, stderr, code := scrapeRunCLI(t, srv.URL, "scrape", "-", "--concurrency", "1")
+	if code != 130 {
+		t.Errorf("exit %d, want 130", code)
+	}
+	if !strings.Contains(stderr, "1 ok, 1 failed, 1 not run") {
+		t.Errorf("stderr = %s", stderr)
+	}
+}
+
+// Ctrl-C used to be ignored while stdin was idle.
+func TestReadStdinLinesCtxCancelWhileIdle(t *testing.T) {
+	r, w, _ := os.Pipe()
+	old := os.Stdin
+	os.Stdin = r
+	t.Cleanup(func() { os.Stdin = old; r.Close(); w.Close() })
+	ctx, cancel := context.WithCancel(context.Background())
+	go func() { time.Sleep(20 * time.Millisecond); cancel() }()
+	done := make(chan error, 1)
+	go func() { _, err := readStdinLinesCtx(ctx); done <- err }()
+	select {
+	case err := <-done:
+		if !errors.Is(err, context.Canceled) {
+			t.Errorf("err = %v, want context.Canceled", err)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("readStdinLinesCtx still blocked on stdin after cancel")
+	}
+}
+
+func TestReadLinesStripsBOM(t *testing.T) {
+	f := filepath.Join(t.TempDir(), "urls.txt")
+	_ = os.WriteFile(f, []byte("\ufeffhttps://a.example\n\ufeff# c\nhttps://b.example\n"), 0o644)
+	got, err := readLines(f)
+	if err != nil || strings.Join(got, "|") != "https://a.example|https://b.example" {
+		t.Errorf("got %q, %v", got, err)
+	}
+}
+
+func TestScrapeScreenshotLabelsUnique(t *testing.T) {
+	data := base64.StdEncoding.EncodeToString([]byte("x"))
+	var shots []map[string]any
+	for _, l := range []any{"a", "a-2", "a", "A", nil} {
+		shots = append(shots, map[string]any{"label": l, "data": data})
+	}
+	dir := t.TempDir()
+	paths, err := scrapeSaveScreenshots(shots, dir, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	seen := map[string]bool{}
+	for _, p := range paths {
+		k := strings.ToLower(filepath.Base(p))
+		if seen[k] {
+			t.Errorf("duplicate file %s in %v", k, paths)
+		}
+		seen[k] = true
+	}
+	if ents, _ := os.ReadDir(dir); len(ents) != 5 {
+		t.Errorf("%d files written, want 5", len(ents))
+	}
+}
+
+func TestScrapeOutputKeepsGoodFileOnTargetFailure(t *testing.T) {
+	srv, _ := newRecordingServer(t, scrapeTargetHandler(503, 200))
+	dir := t.TempDir()
+	file := filepath.Join(dir, "page.md")
+	_ = os.WriteFile(file, []byte("good"), 0o600)
+	out, _, code := scrapeRunCLI(t, srv.URL, "scrape", "https://example.com", "-o", file)
+	if b, _ := os.ReadFile(file); code != 6 || string(b) != "good" {
+		t.Fatalf("exit %d, file %q: an error page replaced the good file", code, b)
+	}
+	if !strings.Contains(out, "Service Unavailable") {
+		t.Errorf("JSON mode must keep the unwritten document: %s", out)
+	}
+	if _, _, code = scrapeRunCLI(t, srv.URL, "scrape", "https://example.com", "-o", file, "--allowed-status", "503"); code != 0 {
+		t.Fatalf("allowed: exit %d", code)
+	}
+	b, _ := os.ReadFile(file)
+	st, _ := os.Stat(file)
+	if string(b) != "Service Unavailable\n" || st.Mode().Perm() != 0o600 {
+		t.Errorf("file = %q mode %v, want the page with the old mode", b, st.Mode().Perm())
+	}
+	if ents, _ := os.ReadDir(dir); len(ents) != 1 {
+		t.Errorf("leftover temp files: %v", ents)
+	}
+}
+
+func TestScrapeOutputDashIsStdout(t *testing.T) {
+	scrapeHumanMode(t)
+	t.Chdir(t.TempDir())
+	srv, _ := newRecordingServer(t, scrapeMarkdownHandler)
+	out, stderr, code := scrapeRunCLI(t, srv.URL, "scrape", "https://example.com", "-o", "-")
+	if code != 0 || out != "# Hello\n" {
+		t.Fatalf("exit %d, stdout %q, stderr %s", code, out, stderr)
+	}
+	if _, err := os.Stat("-"); err == nil {
+		t.Error(`a file named "-" was written`)
+	}
+}
+
+func TestScrapeOutputUnwritablePrintsResult(t *testing.T) {
+	srv, _ := newRecordingServer(t, scrapeMarkdownHandler)
+	file := filepath.Join(t.TempDir(), "missing", "page.md")
+	out, stderr, code := scrapeRunCLI(t, srv.URL, "scrape", "https://example.com", "-o", file)
+	if code != 1 || !strings.Contains(stderr, "printed to stdout instead") {
+		t.Errorf("exit %d, stderr %s", code, stderr)
+	}
+	var got map[string]any
+	if err := json.Unmarshal([]byte(out), &got); err != nil || got["content"] != "# Hello\n" || got["output"] != nil {
+		t.Errorf("billed result lost or mislabelled: %s", out)
+	}
+}
+
+func TestScrapeImpersonateToggle(t *testing.T) {
+	srv, reqs := newRecordingServer(t, scrapeMarkdownHandler)
+	if _, stderr, code := scrapeRunCLI(t, srv.URL, "scrape", "https://example.com", "--impersonate=false"); code != 0 {
+		t.Fatalf("exit %d, stderr %s", code, stderr)
+	}
+	if v, ok := scrapeTestBody(t, reqs)["impersonate"]; !ok || v != false {
+		t.Errorf("impersonate = %v, want false sent", v)
+	}
+	if u := scrapeCmd.Flags().Lookup("impersonate").Usage; !strings.Contains(u, "on by default") {
+		t.Errorf("help does not state the default: %q", u)
+	}
+}
+
+func TestScrapeHumanDataNotHTMLEscaped(t *testing.T) {
+	scrapeHumanMode(t)
+	srv, _ := newRecordingServer(t, func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"url":"u","status":200,"content":"","data":{"q":"a<b>&c"}}`))
+	})
+	out, stderr, code := scrapeRunCLI(t, srv.URL, "scrape", "https://example.com", "--extract", `{"q":"h1"}`)
+	if code != 0 || !strings.Contains(out, `"a<b>&c"`) {
+		t.Fatalf("exit %d, stdout %q, stderr %s", code, out, stderr)
+	}
+}
+
+func TestScrapeWrapperCreditsAlias(t *testing.T) {
+	srv, _ := newRecordingServer(t, scrapeMarkdownHandler)
+	out, _, _ := scrapeRunCLI(t, srv.URL, "scrape", "https://example.com", "--format", "markdown")
+	var got map[string]any
+	_ = json.Unmarshal([]byte(out), &got)
+	if got["credits"] != 1.0 || got["credits"] != got["credits_charged"] {
+		t.Errorf("credits = %v, credits_charged = %v", got["credits"], got["credits_charged"])
+	}
+}
diff --git a/internal/cmd/scrapeflags.go b/internal/cmd/scrapeflags.go
index 193813a..a9a784f 100644
--- a/internal/cmd/scrapeflags.go
+++ b/internal/cmd/scrapeflags.go
@@ -36,7 +36,7 @@ func addScrapeFlags(cmd *cobra.Command) *scrapeFlags {
 	f.StringVar(&s.method, "method", "", "HTTP method sent to the target (default GET)")
 	f.BoolVar(&s.render, "render", false, "render JavaScript in a browser (js_render)")
 	f.BoolVar(&s.stealth, "stealth", false, "hardened browser fingerprint (camoufox; dearest tier)")
-	f.BoolVar(&s.impersonate, "impersonate", false, "fetch tier: present a real browser TLS/HTTP2 fingerprint")
+	f.BoolVar(&s.impersonate, "impersonate", false, "fetch tier: present a real browser TLS/HTTP2 fingerprint (on by default; --impersonate=false turns it off)")
 	f.StringVar(&s.engine, "engine", "", "pin the engine: fetch|obscura|chromium|camoufox")
 	f.StringVar(&s.mode, "mode", "", "auto: escalate through tiers until one succeeds")
 	f.BoolVar(&s.premium, "premium-proxy", false, "residential exits (priced higher; fails rather than falling back)")
@@ -73,7 +73,7 @@ func addScrapeFlags(cmd *cobra.Command) *scrapeFlags {
 	f.IntVar(&s.maxCost, "max-cost", 0, "refuse if the request would cost more credits than this")
 	f.StringSliceVar(&s.allowedStatus, "allowed-status", nil, "extra target statuses to accept, e.g. 403: billed as a success (200/404/410 always are), ends --mode auto escalation, and scrape exits 0 instead of 6 on them")
 	f.BoolVar(&s.originalStatus, "original-status", false, "API answers with the target's status on its HTTP status line (the CLI reads the target status either way)")
-	f.StringVar(&s.body, "body", "", "raw request body as JSON or @file; flags override its fields")
+	f.StringVar(&s.body, "body", "", "raw request body as JSON or @file; flags override its fields (nested objects are merged key by key)")
 	return s
 }
 
@@ -84,6 +84,9 @@ func (s *scrapeFlags) build() (map[string]any, error) {
 		if err := decodeJSONArg("--body", s.body, &body); err != nil {
 			return nil, err
 		}
+		if body == nil { // --body null
+			return nil, Usagef("--body: want a JSON object, got null")
+		}
 	}
 	set := func(flag, field string, v any) {
 		if s.fs.Changed(flag) {
@@ -137,7 +140,7 @@ func (s *scrapeFlags) build() (map[string]any, error) {
 		body["cache"] = false
 	}
 	if len(s.headers) > 0 {
-		h := map[string]string{}
+		h := map[string]any{}
 		for _, raw := range s.headers {
 			name, val, ok := strings.Cut(raw, ":")
 			if !ok || strings.TrimSpace(name) == "" {
@@ -145,7 +148,7 @@ func (s *scrapeFlags) build() (map[string]any, error) {
 			}
 			h[strings.TrimSpace(name)] = strings.TrimSpace(val)
 		}
-		body["custom_headers"] = h
+		mergeField(body, "custom_headers", h)
 	}
 	if len(s.allowedStatus) > 0 {
 		codes := make([]int, 0, len(s.allowedStatus))
@@ -170,8 +173,9 @@ func (s *scrapeFlags) build() (map[string]any, error) {
 		if err := decodeJSONArg("--"+j.flag, j.val, &v); err != nil {
 			return nil, err
 		}
-		body[j.field] = v
+		mergeField(body, j.field, v)
 	}
+	// ai_extract below replaces --body's: prompt and schema are alternatives.
 	if s.aiPrompt != "" && s.aiSchema != "" {
 		return nil, Usagef("--ai and --ai-schema are mutually exclusive: the API takes a prompt or a schema, not both")
 	}
@@ -188,6 +192,20 @@ func (s *scrapeFlags) build() (map[string]any, error) {
 	return body, nil
 }
 
+// mergeField sets dst[k] = v. When both are JSON objects they are merged
+// recursively, so a flag overrides leaf fields and keeps --body's siblings.
+func mergeField(dst map[string]any, k string, v any) {
+	d, dok := dst[k].(map[string]any)
+	s, sok := v.(map[string]any)
+	if !dok || !sok {
+		dst[k] = v
+		return
+	}
+	for k2, v2 := range s {
+		mergeField(d, k2, v2)
+	}
+}
+
 // decodeJSONArg parses a flag value that is inline JSON or @path (@- = stdin).
 func decodeJSONArg(flag, val string, v any) error {
 	b, err := readArg(val)
diff --git a/internal/cmd/status.go b/internal/cmd/status.go
index 01e58ae..edec13e 100644
--- a/internal/cmd/status.go
+++ b/internal/cmd/status.go
@@ -51,7 +51,8 @@ var statusCmd = &cobra.Command{
   GET /v1/requests?limit=1 the key is accepted
 
 Exit codes: 0 all good, 3 the key is missing or rejected, 10 the API could not
-be reached. A reachable API that reports not ready still exits 0; read
+be reached; it also exits with the transport error's code when the connection
+fails during the key check. A reachable API that reports not ready still exits 0; read
 "ready" and "checks".`,
 	Example: `  spicrawl status
   spicrawl status --json | jq .workers
@@ -77,6 +78,7 @@ be reached. A reachable API that reports not ready still exits 0; read
 		}
 
 		f := false
+		var keyCheckErr error // the key check could not reach the API
 		if r.APIKey == "" {
 			rep.KeyValid = &f
 			rep.KeyError = "no API key configured"
@@ -94,6 +96,9 @@ be reached. A reachable API that reports not ready still exits 0; read
 				rep.KeyError = prob.Error()
 			default:
 				rep.KeyError = err.Error() // could not tell; key_valid stays null
+				if !isProb {
+					keyCheckErr = err // transport failure, not an API answer
+				}
 			}
 
 			if rep.KeyValid != nil && *rep.KeyValid {
@@ -113,7 +118,7 @@ be reached. A reachable API that reports not ready still exits 0; read
 			}
 			return &ExitError{Code: exitcode.Auth, Err: errors.New("the API rejected the key: " + rep.KeyError)}
 		}
-		return nil
+		return keyCheckErr
 	},
 }
 
diff --git a/internal/cmd/status_fix_test.go b/internal/cmd/status_fix_test.go
new file mode 100644
index 0000000..832f9ff
--- /dev/null
+++ b/internal/cmd/status_fix_test.go
@@ -0,0 +1,24 @@
+package cmd
+
+import (
+	"net/http"
+	"strings"
+	"testing"
+)
+
+// The API answers /readyz but drops the connection on the key check: status
+// cannot vouch for the key, so it must not exit 0.
+func TestStatusKeyCheckNetworkFailureExitsNonZero(t *testing.T) {
+	srv, _ := newRecordingServer(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/readyz" {
+			_, _ = w.Write([]byte(`{"status":"ready","checks":{},"cdp":"enabled"}`))
+			return
+		}
+		conn, _, _ := w.(http.Hijacker).Hijack()
+		conn.Close()
+	})
+	out, errb, code := runCLI(t, srv.URL, "status")
+	if code == 0 || !strings.Contains(out, `"key_valid": null`) {
+		t.Errorf("exit %d, stdout %s, stderr %s", code, out, errb)
+	}
+}
diff --git a/internal/cmd/usage.go b/internal/cmd/usage.go
index 79e04ea..960cbec 100644
--- a/internal/cmd/usage.go
+++ b/internal/cmd/usage.go
@@ -134,11 +134,18 @@ Needs a key with the read scope.`,
 var usageSummaryCmd = &cobra.Command{
 	Use:   "summary",
 	Short: "Current-period usage against the plan allowance (GET /v1/usage/summary)",
-	Long: `Usage for the billing period covering now, with the plan's credit allowance.
-When no subscription covers now, the period is the calendar month and there
-is no allowance; that is not a bill preview.`,
+	Long: `Usage for the billing period covering now, with the plan's included credits
+and the monthly allowance the API enforces. When no subscription covers now, the
+period is the allowance month and the free plan's allowance applies; that is not
+a bill preview.
+
+"allowance" is what requests are checked against: requests are refused once it
+is used up, and its used figure includes credits held for in-flight work (open
+browser sessions, unfinished batch items), so it can run ahead of "credits".
+The allowance line is absent when the API could not read its counter (a
+warning says so).`,
 	Example: `  spicrawl usage summary
-  spicrawl usage summary --json | jq .credits.remaining_micro`,
+  spicrawl usage summary --json | jq .allowance.remaining_micro`,
 	Args: cobra.NoArgs,
 	RunE: func(cmd *cobra.Command, _ []string) error {
 		body, err := usageGet(cmd.Context(), "/v1/usage/summary", nil)
@@ -165,6 +172,13 @@ is no allowance; that is not a bill preview.`,
 				Overage   int64  `json:"overage_micro"`
 				UsedBP    *int64 `json:"used_basis_points"`
 			} `json:"credits"`
+			Allowance *struct {
+				Limit     int64  `json:"limit_micro"`
+				Used      int64  `json:"used_micro"`
+				Remaining int64  `json:"remaining_micro"`
+				Unlimited bool   `json:"unlimited"`
+				ResetsAt  string `json:"resets_at"`
+			} `json:"allowance"`
 			Metrics  map[string]int64 `json:"metrics"`
 			Warnings []string         `json:"warnings"`
 		}
@@ -195,6 +209,14 @@ is no allowance; that is not a bill preview.`,
 			}
 			fmt.Fprintln(w)
 		}
+		if a := s.Allowance; a != nil {
+			if a.Unlimited {
+				fmt.Fprintf(w, "%-12s unlimited (no monthly ceiling is enforced), %s used, resets %s\n", "allowance:", logsCredits(a.Used), a.ResetsAt)
+			} else {
+				fmt.Fprintf(w, "%-12s %s of %s used (incl. credits held for in-flight work), %s remaining, resets %s\n", "allowance:",
+					logsCredits(a.Used), logsCredits(a.Limit), logsCredits(a.Remaining), a.ResetsAt)
+			}
+		}
 		fmt.Fprintln(w)
 		cols := usageColumns(s.Metrics)
 		rows := make([][]string, 0, len(cols))
diff --git a/internal/cmd/usage_fix_test.go b/internal/cmd/usage_fix_test.go
new file mode 100644
index 0000000..283676d
--- /dev/null
+++ b/internal/cmd/usage_fix_test.go
@@ -0,0 +1,27 @@
+package cmd
+
+import (
+	"net/http"
+	"strings"
+	"testing"
+)
+
+// The summary must show the enforced monthly allowance and what is left of it,
+// not only the plan's included credits.
+func TestUsageSummaryShowsEnforcedAllowance(t *testing.T) {
+	srv, _ := newRecordingServer(t, func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte(`{"period":{"start":"2026-10-01","end":"2026-11-01","days":31},"period_elapsed_days":5,
+"plan":{"code":"free","name":"Free","subscription_status":"none","period_source":"allowance_month"},
+"credits":{"included_micro":1000000000,"used_micro":10000000,"remaining_micro":990000000,"overage_micro":0},
+"allowance":{"limit_micro":1000000000,"limit_credits":1000,"used_micro":250500000,"remaining_micro":749500000,"unlimited":false,"resets_at":"2026-11-01T00:00:00Z"},
+"metrics":{"credits":10000000}}`))
+	})
+	out, errb, code := runCLIHuman(t, srv.URL, "usage", "summary")
+	if code != 0 {
+		t.Fatalf("exit %d: %s", code, errb)
+	}
+	if !strings.Contains(out, "allowance:") || !strings.Contains(out, "250.5 of 1000 used") ||
+		!strings.Contains(out, "749.5 remaining") || !strings.Contains(out, "resets 2026-11-01T00:00:00Z") {
+		t.Errorf("allowance line missing or wrong:\n%s", out)
+	}
+}
diff --git a/internal/config/config.go b/internal/config/config.go
index f868d55..090bc7d 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -98,29 +98,45 @@ func Save(f File) error {
 	if err != nil {
 		return err
 	}
-	tmp := p + ".tmp"
-	if err := os.WriteFile(tmp, append(b, '\n'), 0o600); err != nil {
-		return fmt.Errorf("write %s: %w", tmp, err)
+	// A fresh temp file (CreateTemp is 0600) rather than a fixed name: a stale
+	// world-readable "<path>.tmp" would otherwise keep its mode and carry the key.
+	tmp, err := os.CreateTemp(filepath.Dir(p), ".config-*.tmp")
+	if err != nil {
+		return fmt.Errorf("write %s: %w", p, err)
+	}
+	defer os.Remove(tmp.Name()) // no-op once renamed
+	_, werr := tmp.Write(append(b, '\n'))
+	if cerr := tmp.Close(); werr == nil {
+		werr = cerr
 	}
-	return os.Rename(tmp, p)
+	if werr != nil {
+		return fmt.Errorf("write %s: %w", tmp.Name(), werr)
+	}
+	return os.Rename(tmp.Name(), p)
 }
 
 // Resolve applies flag > env > file > default precedence.
 func Resolve(flagKey, flagBase string) (Resolved, error) {
 	r := Resolved{}
-	p, _ := Path()
-	r.Path = p
-	f, err := Load()
-	if err != nil {
-		return r, err
+	// The file is optional: with no $HOME (a container, cron) there is nowhere
+	// to look, and flags and env must still work.
+	var f File
+	if p, err := Path(); err == nil {
+		r.Path = p
+		if f, err = Load(); err != nil {
+			return r, err
+		}
 	}
-	switch {
+	// A key pasted or exported with a trailing newline would otherwise reach
+	// the Authorization header and fail as "cannot reach the API".
+	envKey, fileKey := strings.TrimSpace(os.Getenv(EnvAPIKey)), strings.TrimSpace(f.APIKey)
+	switch flagKey = strings.TrimSpace(flagKey); {
 	case flagKey != "":
 		r.APIKey, r.APIKeySource = flagKey, "flag"
-	case os.Getenv(EnvAPIKey) != "":
-		r.APIKey, r.APIKeySource = os.Getenv(EnvAPIKey), "env"
-	case f.APIKey != "":
-		r.APIKey, r.APIKeySource = f.APIKey, "file"
+	case envKey != "":
+		r.APIKey, r.APIKeySource = envKey, "env"
+	case fileKey != "":
+		r.APIKey, r.APIKeySource = fileKey, "file"
 	}
 	switch {
 	case flagBase != "":
@@ -139,13 +155,15 @@ func Resolve(flagKey, flagBase string) (Resolved, error) {
 // MaskKey shows enough of a key to recognise it and no more: the key's
 // prefix plus four secret characters. The width is derived from the prefix
 // rather than hard-coded, so a prefix rename cannot silently shift how much
-// secret is shown.
+// secret is shown. A key too short to hide at least minHidden characters
+// between the head and the last four is masked entirely.
 func MaskKey(k string) string {
 	keep := 16
 	if n := keyPrefixLen(k); n > 0 {
 		keep = n + 4
 	}
-	if len(k) <= keep {
+	const minHidden = 8
+	if len(k) < keep+4+minHidden {
 		return strings.Repeat("*", len(k))
 	}
 	return k[:keep] + "…" + k[len(k)-4:]
diff --git a/internal/config/config_fix_test.go b/internal/config/config_fix_test.go
new file mode 100644
index 0000000..d3bc80c
--- /dev/null
+++ b/internal/config/config_fix_test.go
@@ -0,0 +1,68 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestResolveTrimsKey(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "config.json")
+	t.Setenv(EnvConfig, path)
+	if err := os.WriteFile(path, []byte(`{"api_key":"filekey\r\n"}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	for _, tc := range []struct{ flag, env, want, src string }{
+		{"flagkey \n", "envkey", "flagkey", "flag"},
+		{"", "envkey\r\n", "envkey", "env"},
+		{"", "\n", "filekey", "file"}, // a blank env var must not shadow the file
+	} {
+		t.Setenv(EnvAPIKey, tc.env)
+		r, err := Resolve(tc.flag, "")
+		if err != nil || r.APIKey != tc.want || r.APIKeySource != tc.src {
+			t.Errorf("%+v: got %q from %q, err %v", tc, r.APIKey, r.APIKeySource, err)
+		}
+	}
+}
+
+// With no $HOME there is no config dir; flags and env must still work.
+func TestResolveWithoutHome(t *testing.T) {
+	t.Setenv(EnvConfig, "")
+	t.Setenv("HOME", "")
+	t.Setenv("XDG_CONFIG_HOME", "")
+	t.Setenv(EnvAPIKey, "")
+	r, err := Resolve("k", "http://localhost:1/")
+	if err != nil || r.APIKey != "k" || r.BaseURL != "http://localhost:1" {
+		t.Fatalf("got %+v, err %v", r, err)
+	}
+}
+
+func TestSaveIgnoresStaleTmpAndIsOwnerOnly(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "config.json")
+	t.Setenv(EnvConfig, path)
+	if err := os.WriteFile(path+".tmp", nil, 0o644); err != nil { // a stale world-readable leftover
+		t.Fatal(err)
+	}
+	if err := Save(File{APIKey: "secret"}); err != nil {
+		t.Fatal(err)
+	}
+	if fi, err := os.Stat(path); err != nil || fi.Mode().Perm() != 0o600 {
+		t.Errorf("config mode = %v, err %v, want 0600", fi.Mode(), err)
+	}
+	if left, _ := filepath.Glob(filepath.Join(filepath.Dir(path), ".config-*.tmp")); len(left) != 0 {
+		t.Errorf("temp files left behind: %v", left)
+	}
+}
+
+func TestMaskKeyNeverShowsAShortKey(t *testing.T) {
+	for _, k := range []string{"abc", "0123456789abcdef", "0123456789abcdefghij", "spicrawl_live_abcdefgh", "spicrawl_live_abcdefghijkl"} {
+		if got := MaskKey(k); got != strings.Repeat("*", len(k)) {
+			t.Errorf("MaskKey(%q) = %q, want all stars", k, got)
+		}
+	}
+	long := "spicrawl_live_0123456789abcdef0123456789abcdef"
+	if got := MaskKey(long); got != "spicrawl_live_0123…cdef" {
+		t.Errorf("MaskKey(long) = %q", got)
+	}
+}
diff --git a/internal/exitcode/exitcode.go b/internal/exitcode/exitcode.go
index 9ea4499..dae2eaa 100644
--- a/internal/exitcode/exitcode.go
+++ b/internal/exitcode/exitcode.go
@@ -19,7 +19,9 @@ const (
 	Session  = 9  // ERR::SESSION::*
 	Network  = 10 // could not reach the Spicrawl API at all; nothing was sent
 	Pending  = 11 // a --wait gave up before the job finished
-	Timeout  = 12 // the request was sent but --timeout expired; it may have run and been billed
+	Timeout  = 12 // the request was sent but --timeout expired or the connection dropped; it may have run and been billed
+
+	Interrupted = 130 // Ctrl-C (128 + SIGINT); the usual shell convention
 )
 
 // Entry describes one exit code for `spicrawl exit-codes`.
@@ -44,7 +46,8 @@ var Table = []Entry{
 	{Session, "session", "ERR::SESSION::*"},
 	{Network, "network", "the Spicrawl API could not be reached (DNS, refused, TLS); nothing was sent"},
 	{Pending, "pending", "a --wait gave up before the job finished"},
-	{Timeout, "timeout", "timed out waiting for the API; the request may have run and been billed: check `spicrawl logs` before retrying"},
+	{Timeout, "timeout", "timed out waiting for the API, or the connection dropped after the request was sent; the request may have run and been billed: check `spicrawl logs` before retrying"},
+	{Interrupted, "interrupted", "stopped with Ctrl-C"},
 }
 
 // ForCode returns the exit code for an API error code such as
diff --git a/internal/exitcode/exitcode_test.go b/internal/exitcode/exitcode_test.go
index 1e678dc..c586eeb 100644
--- a/internal/exitcode/exitcode_test.go
+++ b/internal/exitcode/exitcode_test.go
@@ -22,11 +22,15 @@ func TestForProblem(t *testing.T) {
 }
 
 func TestTableIsComplete(t *testing.T) {
-	if len(Table) != Timeout+1 {
-		t.Fatalf("%d entries, want %d", len(Table), Timeout+1)
+	if len(Table) != Timeout+2 {
+		t.Fatalf("%d entries, want %d", len(Table), Timeout+2)
 	}
 	for i, e := range Table {
-		if e.Code != i || e.Name == "" || e.Meaning == "" {
+		want := i
+		if i == Timeout+1 {
+			want = Interrupted
+		}
+		if e.Code != want || e.Name == "" || e.Meaning == "" {
 			t.Errorf("entry %d: %+v", i, e)
 		}
 	}
diff --git a/internal/output/output.go b/internal/output/output.go
index dd4fe3e..64ab378 100644
--- a/internal/output/output.go
+++ b/internal/output/output.go
@@ -6,6 +6,7 @@
 package output
 
 import (
+	"bytes"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -51,13 +52,17 @@ func (p *Printer) Line(v any) error {
 }
 
 // RawJSON writes bytes that are already JSON, re-indented in JSON mode.
+// It re-indents the bytes instead of decoding them, so numbers beyond
+// float64 (ids, counters) and the API's key order survive, as in --jsonl.
 func (p *Printer) RawJSON(b []byte) error {
-	var v any
-	if err := json.Unmarshal(b, &v); err != nil {
+	var buf bytes.Buffer
+	if err := json.Indent(&buf, bytes.TrimSpace(b), "", "  "); err != nil {
 		_, err := p.Out.Write(b)
 		return err
 	}
-	return p.Value(v)
+	buf.WriteByte('\n')
+	_, err := p.Out.Write(buf.Bytes())
+	return err
 }
 
 // Result prints v as JSON in JSON mode, otherwise calls human.
diff --git a/internal/output/output_fix_test.go b/internal/output/output_fix_test.go
new file mode 100644
index 0000000..1a482ab
--- /dev/null
+++ b/internal/output/output_fix_test.go
@@ -0,0 +1,26 @@
+package output
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+// --json used to decode envelopes into float64: 1234567890123456789 became
+// 1234567890123456800, and keys were re-sorted. Both must match --jsonl.
+func TestOutputRawJSONKeepsNumbersAndKeyOrder(t *testing.T) {
+	var out bytes.Buffer
+	p := &Printer{Out: &out}
+	if err := p.RawJSON([]byte(`{"z":1234567890123456789,"a":1.50,"s":"<&>"}` + "\n")); err != nil {
+		t.Fatal(err)
+	}
+	want := "{\n  \"z\": 1234567890123456789,\n  \"a\": 1.50,\n  \"s\": \"<&>\"\n}\n"
+	if out.String() != want {
+		t.Errorf("got %q, want %q", out.String(), want)
+	}
+
+	out.Reset() // not JSON: passed through untouched
+	if err := p.RawJSON([]byte("plain")); err != nil || !strings.HasPrefix(out.String(), "plain") {
+		t.Errorf("non-JSON: %q, %v", out.String(), err)
+	}
+}
diff --git a/internal/schema/batch-item.json b/internal/schema/batch-item.json
index 3c64e1d..8539042 100644
--- a/internal/schema/batch-item.json
+++ b/internal/schema/batch-item.json
@@ -6,7 +6,7 @@
   "allOf": [
     {
       "type": "object",
-      "description": "The /v1/scrape request object as accepted by batch, minus `url`. Field names, types and validation are exactly\nScrapeRequest's (enforced by a parity test); each property below references it. Every item is merged as\njob-level value, overridden by the item's value (an explicit `false` on an item wins), with the project's\ndashboard defaults underneath both. Validation happens for every item at submission.\n\nIMPORTANT — what the current batch worker actually executes: only `js_render`, `stealth`, `premium_proxy`,\n`proxy_country`, `proxy` (always with verify off) and, on rendered items, `block_resources`. Requests are always\nGET and the payload is the raw page (HTML, or the decoded body for non-rendered fetches). Every other field is\naccepted, validated and counted in the credit reservation for parity with /v1/scrape, but has no effect on the\nbatch result. If you need extraction, screenshots, actions, sessions or a non-HTML `response_format`, use /v1/scrape.\n",
+      "description": "The /v1/scrape request object as accepted by batch, minus `url`. Field names, types and validation are exactly\nScrapeRequest's (enforced by a parity test); each property below references it. Every item is merged as\njob-level value, overridden by the item's value (an explicit `false` on an item wins), with the project's\ndashboard defaults underneath both. Validation happens for every item at submission.\n\nWhat the batch worker executes: each item is one fetch or one render, and the document is returned as\n`response_format` (`html` by default, `json`, `markdown` or `text`). A field is either honoured on a batch item\nor refused at submission, never accepted and skipped. Refused with 400 INVALID_PARAMETER, naming every offending\nfield, with nothing queued or charged: `actions`, `screenshot` and its options, `network_capture`, `extract`,\n`extract_preset`, `ai_extract`, `autoparse`, `links`, `session_id`, `cache`/`cache_ttl`, `original_status`,\n`allowed_status_codes`, `parse_pdf=true`, `mode=auto`, `response_format=pdf`, and a non-GET `method` with\n`js_render` or `stealth`. A value that asks for nothing (`screenshot: false`, an empty list) is accepted. A\nrefusal caused by a project default says so in `detail`. Use /v1/scrape for those fields.\n\nA batch item is priced when it is accepted, so a bot challenge never climbs it to camoufox or retries it on a\ndifferent exit the way it can a /v1/scrape request with `premium_proxy` or `proxy`.\n",
       "properties": {
         "method": {
           "type": "string",
@@ -20,7 +20,7 @@
             "OPTIONS"
           ],
           "default": "GET",
-          "description": "Validated as on /v1/scrape, but the batch worker always sends GET. Leave unset."
+          "description": "Honoured on fetched items. A method other than GET with `js_render` or `stealth` is refused with 400, because a browser navigation is always a GET."
         },
         "js_render": {
           "type": "boolean",
@@ -34,15 +34,15 @@
         },
         "impersonate": {
           "type": "boolean",
-          "default": false,
-          "description": "Validated and priced as on /v1/scrape; not applied by the batch worker."
+          "default": true,
+          "description": "Applied by the batch worker on fetched items. Default true, as on /v1/scrape; false on the item, the job or the project defaults opts out."
         },
         "mode": {
           "type": "string",
           "enum": [
             "auto"
           ],
-          "description": "Validated and priced as on /v1/scrape (`auto` reserves the dearest tier). The batch worker does not escalate; it runs fetch unless `js_render` or `stealth` is set. Cannot be combined with `engine` (400 INCOMPATIBLE_FLAGS)."
+          "description": "`auto` is refused on batch with 400 INVALID_PARAMETER, also when it comes from the project defaults; the batch worker does not escalate. It runs the engine that `engine`, `js_render` or `stealth` selects."
         },
         "engine": {
           "type": "string",
@@ -66,38 +66,38 @@
         },
         "proxy": {
           "type": "string",
-          "description": "Your own proxy URL; wins over the pool flags. Honoured by the batch worker (without proxy verification)."
+          "description": "Your own proxy URL; wins over the pool flags. Honoured by the batch worker."
         },
         "proxy_verify": {
           "type": "boolean",
           "default": false,
-          "description": "Validated as on /v1/scrape; the batch worker always sends the custom proxy with verification off."
+          "description": "Honoured by the batch worker: the custom proxy is probed before the engine cost is spent."
         },
         "session_id": {
           "type": "string",
-          "description": "Validated as on /v1/scrape; batch items do not run inside a session. Not applied."
+          "description": "Batch items do not run inside a session. Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "sticky_key": {
           "type": "string",
-          "description": "Coming soon. Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Coming soon. Honoured by the batch worker: equal keys are pinned to the same pool exit."
         },
         "wait": {
           "type": "integer",
           "minimum": 0,
           "maximum": 30000,
           "default": 0,
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Honoured on rendered items."
         },
         "wait_for": {
           "type": "string",
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Honoured on rendered items."
         },
         "wait_for_timeout": {
           "type": "integer",
           "minimum": 0,
           "maximum": 120000,
           "default": 0,
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Honoured on rendered items."
         },
         "actions": {
           "type": "array",
@@ -620,7 +620,7 @@
               }
             ]
           },
-          "description": "Validated as on /v1/scrape; the batch worker does not run browser actions."
+          "description": "The batch worker does not run browser actions. A non-empty list is refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "block_resources": {
           "type": "array",
@@ -653,21 +653,21 @@
         },
         "headless": {
           "type": "boolean",
-          "description": "Validated as on /v1/scrape (the project default for headless is NOT merged on batch). `false` needs chromium, which batch cannot pin. Not applied by the batch worker."
+          "description": "Honoured on rendered items (the project default for headless is NOT merged on batch)."
         },
         "screenshot": {
           "type": "boolean",
           "default": false,
-          "description": "Validated and priced as on /v1/scrape; the batch worker returns no screenshot. With `engine` fetch/obscura it is a 400."
+          "description": "The batch worker returns no screenshot. `true` is refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "screenshot_fullpage": {
           "type": "boolean",
           "default": false,
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "screenshot_selector": {
           "type": "string",
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "screenshot_format": {
           "type": "string",
@@ -677,31 +677,31 @@
             "jpg",
             "webp"
           ],
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "screenshot_quality": {
           "type": "integer",
           "minimum": 0,
           "maximum": 100,
           "default": 0,
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "custom_headers": {
           "type": "object",
           "additionalProperties": {
             "type": "string"
           },
-          "description": "Validated as on /v1/scrape; the batch worker does not send custom headers."
+          "description": "Honoured by the batch worker on every item. Falls back to the project default when unset."
         },
         "autoparse": {
           "type": "boolean",
           "default": false,
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "links": {
           "type": "boolean",
           "default": false,
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape. Also refused when it comes from the project defaults, and `detail` says so."
         },
         "network_capture": {
           "allOf": [
@@ -762,7 +762,7 @@
               }
             }
           ],
-          "description": "Validated as on /v1/scrape (see NetworkCapture); not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "extract": {
           "allOf": [
@@ -885,11 +885,11 @@
               ]
             }
           ],
-          "description": "Validated as on /v1/scrape; the batch worker returns the raw page, not extracted fields."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "extract_preset": {
           "type": "string",
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "ai_extract": {
           "allOf": [
@@ -933,30 +933,30 @@
               ]
             }
           ],
-          "description": "Validated as on /v1/scrape (see AIExtract); not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "main_content_only": {
           "type": "boolean",
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Honoured on `markdown` and `text` items. Unset means off. Falls back to the project default when unset."
         },
         "include_tags": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Honoured on `markdown` and `text` items."
         },
         "exclude_tags": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Honoured on `markdown` and `text` items."
         },
         "parse_pdf": {
           "type": "boolean",
           "default": true,
-          "description": "Validated as on /v1/scrape (default true); not applied by the batch worker."
+          "description": "The batch worker has no PDF parser. `true` is refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape. `false` is accepted."
         },
         "response_format": {
           "type": "string",
@@ -968,18 +968,18 @@
             "pdf"
           ],
           "default": "html",
-          "description": "Validated as on /v1/scrape, but the batch worker always returns the raw page body regardless of this value (no markdown, json, text or pdf conversion)."
+          "description": "Honoured. `html` (the default) and `json` return the document as retrieved; `markdown` and `text` run the same conversion as /v1/scrape. A document that is not HTML (a PDF, an image, JSON) fails a `markdown` or `text` item with EXTRACTION_FAILED; request `html` to get it as retrieved. `pdf` is refused with 400, also when it comes from the project defaults."
         },
         "cache": {
           "type": "boolean",
           "default": true,
-          "description": "Validated as on /v1/scrape, but on batch it defaults to false (not true) and the worker never reads from the cache."
+          "description": "Batch never reads from the result cache. `true` is refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "cache_ttl": {
           "type": "integer",
           "minimum": 0,
           "default": 172800,
-          "description": "Validated as on /v1/scrape; `0` does not imply `cache=false` on batch. Not applied by the batch worker."
+          "description": "A non-zero value is refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "max_cost": {
           "type": "integer",
@@ -990,7 +990,7 @@
         "original_status": {
           "type": "boolean",
           "default": false,
-          "description": "Validated as on /v1/scrape; not applied (result lines always carry the target status in `http_status`)."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape. Result lines always carry the target status in `http_status`."
         },
         "allowed_status_codes": {
           "type": "array",
@@ -999,7 +999,7 @@
             "minimum": 100,
             "maximum": 599
           },
-          "description": "Validated as on /v1/scrape; not applied. Billing is fixed to target statuses 200, 404 and 410."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape. Billing is fixed to target statuses 200, 404 and 410."
         }
       }
     }
diff --git a/internal/schema/batch.json b/internal/schema/batch.json
index 46f2791..8fa5733 100644
--- a/internal/schema/batch.json
+++ b/internal/schema/batch.json
@@ -6,7 +6,7 @@
   "allOf": [
     {
       "type": "object",
-      "description": "The /v1/scrape request object as accepted by batch, minus `url`. Field names, types and validation are exactly\nScrapeRequest's (enforced by a parity test); each property below references it. Every item is merged as\njob-level value, overridden by the item's value (an explicit `false` on an item wins), with the project's\ndashboard defaults underneath both. Validation happens for every item at submission.\n\nIMPORTANT — what the current batch worker actually executes: only `js_render`, `stealth`, `premium_proxy`,\n`proxy_country`, `proxy` (always with verify off) and, on rendered items, `block_resources`. Requests are always\nGET and the payload is the raw page (HTML, or the decoded body for non-rendered fetches). Every other field is\naccepted, validated and counted in the credit reservation for parity with /v1/scrape, but has no effect on the\nbatch result. If you need extraction, screenshots, actions, sessions or a non-HTML `response_format`, use /v1/scrape.\n",
+      "description": "The /v1/scrape request object as accepted by batch, minus `url`. Field names, types and validation are exactly\nScrapeRequest's (enforced by a parity test); each property below references it. Every item is merged as\njob-level value, overridden by the item's value (an explicit `false` on an item wins), with the project's\ndashboard defaults underneath both. Validation happens for every item at submission.\n\nWhat the batch worker executes: each item is one fetch or one render, and the document is returned as\n`response_format` (`html` by default, `json`, `markdown` or `text`). A field is either honoured on a batch item\nor refused at submission, never accepted and skipped. Refused with 400 INVALID_PARAMETER, naming every offending\nfield, with nothing queued or charged: `actions`, `screenshot` and its options, `network_capture`, `extract`,\n`extract_preset`, `ai_extract`, `autoparse`, `links`, `session_id`, `cache`/`cache_ttl`, `original_status`,\n`allowed_status_codes`, `parse_pdf=true`, `mode=auto`, `response_format=pdf`, and a non-GET `method` with\n`js_render` or `stealth`. A value that asks for nothing (`screenshot: false`, an empty list) is accepted. A\nrefusal caused by a project default says so in `detail`. Use /v1/scrape for those fields.\n\nA batch item is priced when it is accepted, so a bot challenge never climbs it to camoufox or retries it on a\ndifferent exit the way it can a /v1/scrape request with `premium_proxy` or `proxy`.\n",
       "properties": {
         "method": {
           "type": "string",
@@ -20,7 +20,7 @@
             "OPTIONS"
           ],
           "default": "GET",
-          "description": "Validated as on /v1/scrape, but the batch worker always sends GET. Leave unset."
+          "description": "Honoured on fetched items. A method other than GET with `js_render` or `stealth` is refused with 400, because a browser navigation is always a GET."
         },
         "js_render": {
           "type": "boolean",
@@ -34,15 +34,15 @@
         },
         "impersonate": {
           "type": "boolean",
-          "default": false,
-          "description": "Validated and priced as on /v1/scrape; not applied by the batch worker."
+          "default": true,
+          "description": "Applied by the batch worker on fetched items. Default true, as on /v1/scrape; false on the item, the job or the project defaults opts out."
         },
         "mode": {
           "type": "string",
           "enum": [
             "auto"
           ],
-          "description": "Validated and priced as on /v1/scrape (`auto` reserves the dearest tier). The batch worker does not escalate; it runs fetch unless `js_render` or `stealth` is set. Cannot be combined with `engine` (400 INCOMPATIBLE_FLAGS)."
+          "description": "`auto` is refused on batch with 400 INVALID_PARAMETER, also when it comes from the project defaults; the batch worker does not escalate. It runs the engine that `engine`, `js_render` or `stealth` selects."
         },
         "engine": {
           "type": "string",
@@ -66,38 +66,38 @@
         },
         "proxy": {
           "type": "string",
-          "description": "Your own proxy URL; wins over the pool flags. Honoured by the batch worker (without proxy verification)."
+          "description": "Your own proxy URL; wins over the pool flags. Honoured by the batch worker."
         },
         "proxy_verify": {
           "type": "boolean",
           "default": false,
-          "description": "Validated as on /v1/scrape; the batch worker always sends the custom proxy with verification off."
+          "description": "Honoured by the batch worker: the custom proxy is probed before the engine cost is spent."
         },
         "session_id": {
           "type": "string",
-          "description": "Validated as on /v1/scrape; batch items do not run inside a session. Not applied."
+          "description": "Batch items do not run inside a session. Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "sticky_key": {
           "type": "string",
-          "description": "Coming soon. Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Coming soon. Honoured by the batch worker: equal keys are pinned to the same pool exit."
         },
         "wait": {
           "type": "integer",
           "minimum": 0,
           "maximum": 30000,
           "default": 0,
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Honoured on rendered items."
         },
         "wait_for": {
           "type": "string",
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Honoured on rendered items."
         },
         "wait_for_timeout": {
           "type": "integer",
           "minimum": 0,
           "maximum": 120000,
           "default": 0,
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Honoured on rendered items."
         },
         "actions": {
           "type": "array",
@@ -620,7 +620,7 @@
               }
             ]
           },
-          "description": "Validated as on /v1/scrape; the batch worker does not run browser actions."
+          "description": "The batch worker does not run browser actions. A non-empty list is refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "block_resources": {
           "type": "array",
@@ -653,21 +653,21 @@
         },
         "headless": {
           "type": "boolean",
-          "description": "Validated as on /v1/scrape (the project default for headless is NOT merged on batch). `false` needs chromium, which batch cannot pin. Not applied by the batch worker."
+          "description": "Honoured on rendered items (the project default for headless is NOT merged on batch)."
         },
         "screenshot": {
           "type": "boolean",
           "default": false,
-          "description": "Validated and priced as on /v1/scrape; the batch worker returns no screenshot. With `engine` fetch/obscura it is a 400."
+          "description": "The batch worker returns no screenshot. `true` is refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "screenshot_fullpage": {
           "type": "boolean",
           "default": false,
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "screenshot_selector": {
           "type": "string",
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "screenshot_format": {
           "type": "string",
@@ -677,31 +677,31 @@
             "jpg",
             "webp"
           ],
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "screenshot_quality": {
           "type": "integer",
           "minimum": 0,
           "maximum": 100,
           "default": 0,
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "custom_headers": {
           "type": "object",
           "additionalProperties": {
             "type": "string"
           },
-          "description": "Validated as on /v1/scrape; the batch worker does not send custom headers."
+          "description": "Honoured by the batch worker on every item. Falls back to the project default when unset."
         },
         "autoparse": {
           "type": "boolean",
           "default": false,
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "links": {
           "type": "boolean",
           "default": false,
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape. Also refused when it comes from the project defaults, and `detail` says so."
         },
         "network_capture": {
           "allOf": [
@@ -762,7 +762,7 @@
               }
             }
           ],
-          "description": "Validated as on /v1/scrape (see NetworkCapture); not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "extract": {
           "allOf": [
@@ -885,11 +885,11 @@
               ]
             }
           ],
-          "description": "Validated as on /v1/scrape; the batch worker returns the raw page, not extracted fields."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "extract_preset": {
           "type": "string",
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "ai_extract": {
           "allOf": [
@@ -933,30 +933,30 @@
               ]
             }
           ],
-          "description": "Validated as on /v1/scrape (see AIExtract); not applied by the batch worker."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "main_content_only": {
           "type": "boolean",
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Honoured on `markdown` and `text` items. Unset means off. Falls back to the project default when unset."
         },
         "include_tags": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Honoured on `markdown` and `text` items."
         },
         "exclude_tags": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "Validated as on /v1/scrape; not applied by the batch worker."
+          "description": "Honoured on `markdown` and `text` items."
         },
         "parse_pdf": {
           "type": "boolean",
           "default": true,
-          "description": "Validated as on /v1/scrape (default true); not applied by the batch worker."
+          "description": "The batch worker has no PDF parser. `true` is refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape. `false` is accepted."
         },
         "response_format": {
           "type": "string",
@@ -968,18 +968,18 @@
             "pdf"
           ],
           "default": "html",
-          "description": "Validated as on /v1/scrape, but the batch worker always returns the raw page body regardless of this value (no markdown, json, text or pdf conversion)."
+          "description": "Honoured. `html` (the default) and `json` return the document as retrieved; `markdown` and `text` run the same conversion as /v1/scrape. A document that is not HTML (a PDF, an image, JSON) fails a `markdown` or `text` item with EXTRACTION_FAILED; request `html` to get it as retrieved. `pdf` is refused with 400, also when it comes from the project defaults."
         },
         "cache": {
           "type": "boolean",
           "default": true,
-          "description": "Validated as on /v1/scrape, but on batch it defaults to false (not true) and the worker never reads from the cache."
+          "description": "Batch never reads from the result cache. `true` is refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "cache_ttl": {
           "type": "integer",
           "minimum": 0,
           "default": 172800,
-          "description": "Validated as on /v1/scrape; `0` does not imply `cache=false` on batch. Not applied by the batch worker."
+          "description": "A non-zero value is refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
         },
         "max_cost": {
           "type": "integer",
@@ -990,7 +990,7 @@
         "original_status": {
           "type": "boolean",
           "default": false,
-          "description": "Validated as on /v1/scrape; not applied (result lines always carry the target status in `http_status`)."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape. Result lines always carry the target status in `http_status`."
         },
         "allowed_status_codes": {
           "type": "array",
@@ -999,7 +999,7 @@
             "minimum": 100,
             "maximum": 599
           },
-          "description": "Validated as on /v1/scrape; not applied. Billing is fixed to target statuses 200, 404 and 410."
+          "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape. Billing is fixed to target statuses 200, 404 and 410."
         }
       }
     }
@@ -1029,7 +1029,7 @@
         "allOf": [
           {
             "type": "object",
-            "description": "The /v1/scrape request object as accepted by batch, minus `url`. Field names, types and validation are exactly\nScrapeRequest's (enforced by a parity test); each property below references it. Every item is merged as\njob-level value, overridden by the item's value (an explicit `false` on an item wins), with the project's\ndashboard defaults underneath both. Validation happens for every item at submission.\n\nIMPORTANT — what the current batch worker actually executes: only `js_render`, `stealth`, `premium_proxy`,\n`proxy_country`, `proxy` (always with verify off) and, on rendered items, `block_resources`. Requests are always\nGET and the payload is the raw page (HTML, or the decoded body for non-rendered fetches). Every other field is\naccepted, validated and counted in the credit reservation for parity with /v1/scrape, but has no effect on the\nbatch result. If you need extraction, screenshots, actions, sessions or a non-HTML `response_format`, use /v1/scrape.\n",
+            "description": "The /v1/scrape request object as accepted by batch, minus `url`. Field names, types and validation are exactly\nScrapeRequest's (enforced by a parity test); each property below references it. Every item is merged as\njob-level value, overridden by the item's value (an explicit `false` on an item wins), with the project's\ndashboard defaults underneath both. Validation happens for every item at submission.\n\nWhat the batch worker executes: each item is one fetch or one render, and the document is returned as\n`response_format` (`html` by default, `json`, `markdown` or `text`). A field is either honoured on a batch item\nor refused at submission, never accepted and skipped. Refused with 400 INVALID_PARAMETER, naming every offending\nfield, with nothing queued or charged: `actions`, `screenshot` and its options, `network_capture`, `extract`,\n`extract_preset`, `ai_extract`, `autoparse`, `links`, `session_id`, `cache`/`cache_ttl`, `original_status`,\n`allowed_status_codes`, `parse_pdf=true`, `mode=auto`, `response_format=pdf`, and a non-GET `method` with\n`js_render` or `stealth`. A value that asks for nothing (`screenshot: false`, an empty list) is accepted. A\nrefusal caused by a project default says so in `detail`. Use /v1/scrape for those fields.\n\nA batch item is priced when it is accepted, so a bot challenge never climbs it to camoufox or retries it on a\ndifferent exit the way it can a /v1/scrape request with `premium_proxy` or `proxy`.\n",
             "properties": {
               "method": {
                 "type": "string",
@@ -1043,7 +1043,7 @@
                   "OPTIONS"
                 ],
                 "default": "GET",
-                "description": "Validated as on /v1/scrape, but the batch worker always sends GET. Leave unset."
+                "description": "Honoured on fetched items. A method other than GET with `js_render` or `stealth` is refused with 400, because a browser navigation is always a GET."
               },
               "js_render": {
                 "type": "boolean",
@@ -1057,15 +1057,15 @@
               },
               "impersonate": {
                 "type": "boolean",
-                "default": false,
-                "description": "Validated and priced as on /v1/scrape; not applied by the batch worker."
+                "default": true,
+                "description": "Applied by the batch worker on fetched items. Default true, as on /v1/scrape; false on the item, the job or the project defaults opts out."
               },
               "mode": {
                 "type": "string",
                 "enum": [
                   "auto"
                 ],
-                "description": "Validated and priced as on /v1/scrape (`auto` reserves the dearest tier). The batch worker does not escalate; it runs fetch unless `js_render` or `stealth` is set. Cannot be combined with `engine` (400 INCOMPATIBLE_FLAGS)."
+                "description": "`auto` is refused on batch with 400 INVALID_PARAMETER, also when it comes from the project defaults; the batch worker does not escalate. It runs the engine that `engine`, `js_render` or `stealth` selects."
               },
               "engine": {
                 "type": "string",
@@ -1089,38 +1089,38 @@
               },
               "proxy": {
                 "type": "string",
-                "description": "Your own proxy URL; wins over the pool flags. Honoured by the batch worker (without proxy verification)."
+                "description": "Your own proxy URL; wins over the pool flags. Honoured by the batch worker."
               },
               "proxy_verify": {
                 "type": "boolean",
                 "default": false,
-                "description": "Validated as on /v1/scrape; the batch worker always sends the custom proxy with verification off."
+                "description": "Honoured by the batch worker: the custom proxy is probed before the engine cost is spent."
               },
               "session_id": {
                 "type": "string",
-                "description": "Validated as on /v1/scrape; batch items do not run inside a session. Not applied."
+                "description": "Batch items do not run inside a session. Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
               },
               "sticky_key": {
                 "type": "string",
-                "description": "Coming soon. Validated as on /v1/scrape; not applied by the batch worker."
+                "description": "Coming soon. Honoured by the batch worker: equal keys are pinned to the same pool exit."
               },
               "wait": {
                 "type": "integer",
                 "minimum": 0,
                 "maximum": 30000,
                 "default": 0,
-                "description": "Validated as on /v1/scrape; not applied by the batch worker."
+                "description": "Honoured on rendered items."
               },
               "wait_for": {
                 "type": "string",
-                "description": "Validated as on /v1/scrape; not applied by the batch worker."
+                "description": "Honoured on rendered items."
               },
               "wait_for_timeout": {
                 "type": "integer",
                 "minimum": 0,
                 "maximum": 120000,
                 "default": 0,
-                "description": "Validated as on /v1/scrape; not applied by the batch worker."
+                "description": "Honoured on rendered items."
               },
               "actions": {
                 "type": "array",
@@ -1643,7 +1643,7 @@
                     }
                   ]
                 },
-                "description": "Validated as on /v1/scrape; the batch worker does not run browser actions."
+                "description": "The batch worker does not run browser actions. A non-empty list is refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
               },
               "block_resources": {
                 "type": "array",
@@ -1676,21 +1676,21 @@
               },
               "headless": {
                 "type": "boolean",
-                "description": "Validated as on /v1/scrape (the project default for headless is NOT merged on batch). `false` needs chromium, which batch cannot pin. Not applied by the batch worker."
+                "description": "Honoured on rendered items (the project default for headless is NOT merged on batch)."
               },
               "screenshot": {
                 "type": "boolean",
                 "default": false,
-                "description": "Validated and priced as on /v1/scrape; the batch worker returns no screenshot. With `engine` fetch/obscura it is a 400."
+                "description": "The batch worker returns no screenshot. `true` is refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
               },
               "screenshot_fullpage": {
                 "type": "boolean",
                 "default": false,
-                "description": "Validated as on /v1/scrape; not applied by the batch worker."
+                "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
               },
               "screenshot_selector": {
                 "type": "string",
-                "description": "Validated as on /v1/scrape; not applied by the batch worker."
+                "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
               },
               "screenshot_format": {
                 "type": "string",
@@ -1700,31 +1700,31 @@
                   "jpg",
                   "webp"
                 ],
-                "description": "Validated as on /v1/scrape; not applied by the batch worker."
+                "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
               },
               "screenshot_quality": {
                 "type": "integer",
                 "minimum": 0,
                 "maximum": 100,
                 "default": 0,
-                "description": "Validated as on /v1/scrape; not applied by the batch worker."
+                "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
               },
               "custom_headers": {
                 "type": "object",
                 "additionalProperties": {
                   "type": "string"
                 },
-                "description": "Validated as on /v1/scrape; the batch worker does not send custom headers."
+                "description": "Honoured by the batch worker on every item. Falls back to the project default when unset."
               },
               "autoparse": {
                 "type": "boolean",
                 "default": false,
-                "description": "Validated as on /v1/scrape; not applied by the batch worker."
+                "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
               },
               "links": {
                 "type": "boolean",
                 "default": false,
-                "description": "Validated as on /v1/scrape; not applied by the batch worker."
+                "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape. Also refused when it comes from the project defaults, and `detail` says so."
               },
               "network_capture": {
                 "allOf": [
@@ -1785,7 +1785,7 @@
                     }
                   }
                 ],
-                "description": "Validated as on /v1/scrape (see NetworkCapture); not applied by the batch worker."
+                "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
               },
               "extract": {
                 "allOf": [
@@ -1908,11 +1908,11 @@
                     ]
                   }
                 ],
-                "description": "Validated as on /v1/scrape; the batch worker returns the raw page, not extracted fields."
+                "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
               },
               "extract_preset": {
                 "type": "string",
-                "description": "Validated as on /v1/scrape; not applied by the batch worker."
+                "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
               },
               "ai_extract": {
                 "allOf": [
@@ -1956,30 +1956,30 @@
                     ]
                   }
                 ],
-                "description": "Validated as on /v1/scrape (see AIExtract); not applied by the batch worker."
+                "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
               },
               "main_content_only": {
                 "type": "boolean",
-                "description": "Validated as on /v1/scrape; not applied by the batch worker."
+                "description": "Honoured on `markdown` and `text` items. Unset means off. Falls back to the project default when unset."
               },
               "include_tags": {
                 "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "description": "Validated as on /v1/scrape; not applied by the batch worker."
+                "description": "Honoured on `markdown` and `text` items."
               },
               "exclude_tags": {
                 "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "description": "Validated as on /v1/scrape; not applied by the batch worker."
+                "description": "Honoured on `markdown` and `text` items."
               },
               "parse_pdf": {
                 "type": "boolean",
                 "default": true,
-                "description": "Validated as on /v1/scrape (default true); not applied by the batch worker."
+                "description": "The batch worker has no PDF parser. `true` is refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape. `false` is accepted."
               },
               "response_format": {
                 "type": "string",
@@ -1991,18 +1991,18 @@
                   "pdf"
                 ],
                 "default": "html",
-                "description": "Validated as on /v1/scrape, but the batch worker always returns the raw page body regardless of this value (no markdown, json, text or pdf conversion)."
+                "description": "Honoured. `html` (the default) and `json` return the document as retrieved; `markdown` and `text` run the same conversion as /v1/scrape. A document that is not HTML (a PDF, an image, JSON) fails a `markdown` or `text` item with EXTRACTION_FAILED; request `html` to get it as retrieved. `pdf` is refused with 400, also when it comes from the project defaults."
               },
               "cache": {
                 "type": "boolean",
                 "default": true,
-                "description": "Validated as on /v1/scrape, but on batch it defaults to false (not true) and the worker never reads from the cache."
+                "description": "Batch never reads from the result cache. `true` is refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
               },
               "cache_ttl": {
                 "type": "integer",
                 "minimum": 0,
                 "default": 172800,
-                "description": "Validated as on /v1/scrape; `0` does not imply `cache=false` on batch. Not applied by the batch worker."
+                "description": "A non-zero value is refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape."
               },
               "max_cost": {
                 "type": "integer",
@@ -2013,7 +2013,7 @@
               "original_status": {
                 "type": "boolean",
                 "default": false,
-                "description": "Validated as on /v1/scrape; not applied (result lines always carry the target status in `http_status`)."
+                "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape. Result lines always carry the target status in `http_status`."
               },
               "allowed_status_codes": {
                 "type": "array",
@@ -2022,7 +2022,7 @@
                   "minimum": 100,
                   "maximum": 599
                 },
-                "description": "Validated as on /v1/scrape; not applied. Billing is fixed to target statuses 200, 404 and 410."
+                "description": "Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape. Billing is fixed to target statuses 200, 404 and 410."
               }
             }
           }
diff --git a/internal/schema/scrape.json b/internal/schema/scrape.json
index 60a1440..47af860 100644
--- a/internal/schema/scrape.json
+++ b/internal/schema/scrape.json
@@ -41,8 +41,8 @@
     },
     "impersonate": {
       "type": "boolean",
-      "default": false,
-      "description": "Fetch tier only: present a real browser TLS/HTTP2 fingerprint to pass passive fingerprint checks, at no extra cost and with no JavaScript. Ignored on render engines. POST only - the GET form rejects `impersonate` as an unknown query parameter. If omitted, the project's stored default applies."
+      "default": true,
+      "description": "Fetch tier only: present a current Chrome TLS/HTTP2 fingerprint, with matching browser headers and Accept-Encoding, to pass passive fingerprint checks. On by default, free, no JavaScript; `false` turns it off and the fetch uses a non-browser TLS handshake. Ignored on render engines. If omitted, the project's stored default applies, and `true` when the project sets none."
     },
     "mode": {
       "type": "string",
@@ -64,16 +64,16 @@
     "premium_proxy": {
       "type": "boolean",
       "default": false,
-      "description": "Coming soon. Use residential exits from the managed pool: fetch 10, obscura 25, chromium 32 credits (camoufox stays 25). If no residential exit is available the request fails 503 ERR::PROXY::EXHAUSTED rather than falling back; ignored (with X-Warning PROXY_FLAG_IGNORED) when `proxy` is set. If omitted, the project's stored default applies."
+      "description": "Coming soon. Use residential exits from the managed pool: fetch 10, obscura 25, chromium 32 credits (camoufox stays 25). If no residential exit is available the request fails 503 ERR::PROXY::EXHAUSTED rather than falling back; ignored (with X-Warning PROXY_FLAG_IGNORED) when `proxy` is set. A bot challenge from a named vendor is retried on a different exit (fetch tier), then climbs to camoufox; see \"Bot challenges\" in the operation description. If omitted, the project's stored default applies."
     },
     "proxy_country": {
       "type": "string",
       "pattern": "^[A-Za-z]{2}$",
-      "description": "Coming soon. ISO 3166-1 alpha-2 exit country (case-insensitive), within the residential pool. Requires premium_proxy=true (400 ERR::REQUEST::INCOMPATIBLE_FLAGS otherwise) unless `proxy` is set, in which case it is ignored with a warning; an unavailable country is 503 ERR::PROXY::EXHAUSTED, never substituted. If omitted, the project's stored default applies."
+      "description": "Coming soon. ISO 3166-1 alpha-2 exit country (case-insensitive), within the residential pool. Requires premium_proxy=true (400 ERR::REQUEST::INCOMPATIBLE_FLAGS otherwise) unless `proxy` is set, in which case it is ignored with a warning; an unavailable country is 503 ERR::PROXY::EXHAUSTED, never substituted. A browser render takes its timezone and locale from this country or, when it is omitted, from the country of the pool exit it was assigned. If omitted, the project's stored default applies."
     },
     "proxy": {
       "type": "string",
-      "description": "Your own proxy URL (http, https, socks5 or socks5h; credentials in userinfo). Takes precedence over premium_proxy/proxy_country and adds 0 proxy credits; loopback hosts are refused with 400 ERR::SECURITY::SSRF_BLOCKED. An unreachable proxy fails 502 ERR::PROXY::UNREACHABLE."
+      "description": "Your own proxy URL (http, https, socks5 or socks5h; credentials in userinfo). Takes precedence over premium_proxy/proxy_country and adds 0 proxy credits; loopback hosts are refused with 400 ERR::SECURITY::SSRF_BLOCKED. An unreachable proxy fails 502 ERR::PROXY::UNREACHABLE. A bot challenge from a named vendor climbs to camoufox when the proxy is http://; see \"Bot challenges\" in the operation description."
     },
     "proxy_verify": {
       "type": "boolean",
@@ -980,7 +980,7 @@
     "cache": {
       "type": "boolean",
       "default": true,
-      "description": "Serve a stored result younger than cache_ttl (Cache-State: hit, 0 credits). Only billable successes of GET-method requests without session_id or actions are stored. Set false for time-sensitive data; cache=false with cache_ttl>0 is 400 ERR::REQUEST::INCOMPATIBLE_FLAGS."
+      "description": "Serve a stored result younger than cache_ttl (Cache-State: hit). A hit is billed at the same price as the fetch that stored it: the cache saves the fetch (latency and load on the target), not credits. Only billable successes of GET-method requests without session_id or actions are stored. Set false for time-sensitive data; cache=false with cache_ttl>0 is 400 ERR::REQUEST::INCOMPATIBLE_FLAGS."
     },
     "cache_ttl": {
       "type": "integer",
diff --git a/npm/bin/spicrawl.js b/npm/bin/spicrawl.js
index 16cc08b..bc4d9cb 100755
--- a/npm/bin/spicrawl.js
+++ b/npm/bin/spicrawl.js
@@ -49,11 +49,11 @@ const bin = binaryPath();
 const child = spawn(bin, process.argv.slice(2), { stdio: "inherit" });
 
 // Forward termination signals so an agent that kills `npx @spicrawl/cli` stops the
-// real process too. Ctrl-C already reaches the child via the process group.
-for (const sig of ["SIGTERM", "SIGHUP"]) {
+// real process too. The exit handler below then re-raises the child's signal (or
+// returns its code), so this process ends the way the child did.
+for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
   process.on(sig, () => child.kill(sig));
 }
-process.on("SIGINT", () => {});
 
 child.on("error", (err) => {
   process.stderr.write(`spicrawl: failed to run ${path.basename(bin)}: ${err.message}\n`);
diff --git a/openapi.yaml b/openapi.yaml
index 024f9ec..8b97c4d 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -533,11 +533,12 @@ components:
             If omitted, the project's stored default applies.
         impersonate:
           type: boolean
-          default: false
-          description: 'Fetch tier only: present a real browser TLS/HTTP2 fingerprint to pass passive
-            fingerprint checks, at no extra cost and with no JavaScript. Ignored on render engines. POST
-            only - the GET form rejects `impersonate` as an unknown query parameter. If omitted, the project''s
-            stored default applies.'
+          default: true
+          description: 'Fetch tier only: present a current Chrome TLS/HTTP2 fingerprint, with matching
+            browser headers and Accept-Encoding, to pass passive fingerprint checks. On by default, free,
+            no JavaScript; `false` turns it off and the fetch uses a non-browser TLS handshake. Ignored
+            on render engines. If omitted, the project''s stored default applies, and `true` when the project sets
+            none.'
         mode:
           type: string
           enum:
@@ -564,19 +565,25 @@ components:
           description: 'Coming soon. Use residential exits from the managed pool: fetch 10, obscura 25, chromium 32
             credits (camoufox stays 25). If no residential exit is available the request fails 503 ERR::PROXY::EXHAUSTED
             rather than falling back; ignored (with X-Warning PROXY_FLAG_IGNORED) when `proxy` is set.
-            If omitted, the project''s stored default applies.'
+            A bot challenge from a named vendor is retried on a different exit (fetch tier), then climbs
+            to camoufox; see "Bot challenges" in the operation description. If omitted, the project''s stored default
+            applies.'
         proxy_country:
           type: string
           pattern: ^[A-Za-z]{2}$
           description: Coming soon. ISO 3166-1 alpha-2 exit country (case-insensitive), within the residential pool.
             Requires premium_proxy=true (400 ERR::REQUEST::INCOMPATIBLE_FLAGS otherwise) unless `proxy`
             is set, in which case it is ignored with a warning; an unavailable country is 503 ERR::PROXY::EXHAUSTED,
-            never substituted. If omitted, the project's stored default applies.
+            never substituted. A browser render takes its timezone and locale from this country or, when
+            it is omitted, from the country of the pool exit it was assigned. If omitted, the project's
+            stored default applies.
         proxy:
           type: string
           description: Your own proxy URL (http, https, socks5 or socks5h; credentials in userinfo). Takes
             precedence over premium_proxy/proxy_country and adds 0 proxy credits; loopback hosts are refused
             with 400 ERR::SECURITY::SSRF_BLOCKED. An unreachable proxy fails 502 ERR::PROXY::UNREACHABLE.
+            A bot challenge from a named vendor climbs to camoufox when the proxy is http://; see "Bot
+            challenges" in the operation description.
         proxy_verify:
           type: boolean
           default: false
@@ -772,9 +779,11 @@ components:
         cache:
           type: boolean
           default: true
-          description: 'Serve a stored result younger than cache_ttl (Cache-State: hit, 0 credits). Only
-            billable successes of GET-method requests without session_id or actions are stored. Set false
-            for time-sensitive data; cache=false with cache_ttl>0 is 400 ERR::REQUEST::INCOMPATIBLE_FLAGS.'
+          description: 'Serve a stored result younger than cache_ttl (Cache-State: hit). A hit is billed at
+            the same price as the fetch that stored it: the cache saves the fetch (latency and load on
+            the target), not credits. Only billable successes of GET-method requests without session_id
+            or actions are stored. Set false for time-sensitive data; cache=false with cache_ttl>0 is
+            400 ERR::REQUEST::INCOMPATIBLE_FLAGS.'
         cache_ttl:
           type: integer
           minimum: 0
@@ -1639,15 +1648,23 @@ components:
         job-level value, overridden by the item's value (an explicit `false` on an item wins), with the project's
         dashboard defaults underneath both. Validation happens for every item at submission.
 
-        IMPORTANT — what the current batch worker actually executes: only `js_render`, `stealth`, `premium_proxy`,
-        `proxy_country`, `proxy` (always with verify off) and, on rendered items, `block_resources`. Requests are always
-        GET and the payload is the raw page (HTML, or the decoded body for non-rendered fetches). Every other field is
-        accepted, validated and counted in the credit reservation for parity with /v1/scrape, but has no effect on the
-        batch result. If you need extraction, screenshots, actions, sessions or a non-HTML `response_format`, use /v1/scrape.
+        What the batch worker executes: each item is one fetch or one render, and the document is returned as
+        `response_format` (`html` by default, `json`, `markdown` or `text`). A field is either honoured on a batch item
+        or refused at submission, never accepted and skipped. Refused with 400 INVALID_PARAMETER, naming every offending
+        field, with nothing queued or charged: `actions`, `screenshot` and its options, `network_capture`, `extract`,
+        `extract_preset`, `ai_extract`, `autoparse`, `links`, `session_id`, `cache`/`cache_ttl`, `original_status`,
+        `allowed_status_codes`, `parse_pdf=true`, `mode=auto`, `response_format=pdf`, and a non-GET `method` with
+        `js_render` or `stealth`. A value that asks for nothing (`screenshot: false`, an empty list) is accepted. A
+        refusal caused by a project default says so in `detail`. Use /v1/scrape for those fields.
+
+        A batch item is priced when it is accepted, so a bot challenge never climbs it to camoufox or retries it on a
+        different exit the way it can a /v1/scrape request with `premium_proxy` or `proxy`.
       properties:
         method:
           $ref: '#/components/schemas/ScrapeRequest/properties/method'
-          description: Validated as on /v1/scrape, but the batch worker always sends GET. Leave unset.
+          description: >-
+            Honoured on fetched items. A method other than GET with `js_render` or `stealth` is refused with
+            400, because a browser navigation is always a GET.
         js_render:
           $ref: '#/components/schemas/ScrapeRequest/properties/js_render'
           description: Render the page with the obscura browser engine. Honoured by the batch worker.
@@ -1658,12 +1675,14 @@ components:
             Honoured by the batch worker. Default false (or the project default).
         impersonate:
           $ref: '#/components/schemas/ScrapeRequest/properties/impersonate'
-          description: Validated and priced as on /v1/scrape; not applied by the batch worker.
+          description: Applied by the batch worker on fetched items. Default true, as on /v1/scrape; false on
+            the item, the job or the project defaults opts out.
         mode:
           $ref: '#/components/schemas/ScrapeRequest/properties/mode'
-          description: Validated and priced as on /v1/scrape (`auto` reserves the dearest tier). The batch
-            worker does not escalate; it runs fetch unless `js_render` or `stealth` is set. Cannot be
-            combined with `engine` (400 INCOMPATIBLE_FLAGS).
+          description: >-
+            `auto` is refused on batch with 400 INVALID_PARAMETER, also when it comes from the project
+            defaults; the batch worker does not escalate. It runs the engine that `engine`, `js_render` or
+            `stealth` selects.
         engine:
           $ref: '#/components/schemas/ScrapeRequest/properties/engine'
           description: |
@@ -1683,30 +1702,38 @@ components:
           description: Coming soon. Exit country for pool proxies. Honoured by the batch worker.
         proxy:
           $ref: '#/components/schemas/ScrapeRequest/properties/proxy'
-          description: Your own proxy URL; wins over the pool flags. Honoured by the batch worker (without
-            proxy verification).
+          description: >-
+            Your own proxy URL; wins over the pool flags. Honoured by the batch worker.
         proxy_verify:
           $ref: '#/components/schemas/ScrapeRequest/properties/proxy_verify'
-          description: Validated as on /v1/scrape; the batch worker always sends the custom proxy with
-            verification off.
+          description: >-
+            Honoured by the batch worker: the custom proxy is probed before the engine cost is spent.
         session_id:
           $ref: '#/components/schemas/ScrapeRequest/properties/session_id'
-          description: Validated as on /v1/scrape; batch items do not run inside a session. Not applied.
+          description: >-
+            Batch items do not run inside a session. Refused on batch with 400 INVALID_PARAMETER (nothing
+            queued or charged); use /v1/scrape.
         sticky_key:
           $ref: '#/components/schemas/ScrapeRequest/properties/sticky_key'
-          description: Coming soon. Validated as on /v1/scrape; not applied by the batch worker.
+          description: >-
+            Coming soon. Honoured by the batch worker: equal keys are pinned to the same pool exit.
         wait:
           $ref: '#/components/schemas/ScrapeRequest/properties/wait'
-          description: Validated as on /v1/scrape; not applied by the batch worker.
+          description: >-
+            Honoured on rendered items.
         wait_for:
           $ref: '#/components/schemas/ScrapeRequest/properties/wait_for'
-          description: Validated as on /v1/scrape; not applied by the batch worker.
+          description: >-
+            Honoured on rendered items.
         wait_for_timeout:
           $ref: '#/components/schemas/ScrapeRequest/properties/wait_for_timeout'
-          description: Validated as on /v1/scrape; not applied by the batch worker.
+          description: >-
+            Honoured on rendered items.
         actions:
           $ref: '#/components/schemas/ScrapeRequest/properties/actions'
-          description: Validated as on /v1/scrape; the batch worker does not run browser actions.
+          description: >-
+            The batch worker does not run browser actions. A non-empty list is refused on batch with 400
+            INVALID_PARAMETER (nothing queued or charged); use /v1/scrape.
         block_resources:
           $ref: '#/components/schemas/ScrapeRequest/properties/block_resources'
           description: Resource classes to block while rendering. Honoured on rendered items only; unset
@@ -1714,82 +1741,107 @@ components:
             the project default when unset.
         headless:
           $ref: '#/components/schemas/ScrapeRequest/properties/headless'
-          description: Validated as on /v1/scrape (the project default for headless is NOT merged on batch).
-            `false` needs chromium, which batch cannot pin. Not applied by the batch worker.
+          description: >-
+            Honoured on rendered items (the project default for headless is NOT merged on batch).
         screenshot:
           $ref: '#/components/schemas/ScrapeRequest/properties/screenshot'
-          description: Validated and priced as on /v1/scrape; the batch worker returns no screenshot.
-            With `engine` fetch/obscura it is a 400.
+          description: >-
+            The batch worker returns no screenshot. `true` is refused on batch with 400 INVALID_PARAMETER
+            (nothing queued or charged); use /v1/scrape.
         screenshot_fullpage:
           $ref: '#/components/schemas/ScrapeRequest/properties/screenshot_fullpage'
-          description: Validated as on /v1/scrape; not applied by the batch worker.
+          description: >-
+            Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape.
         screenshot_selector:
           $ref: '#/components/schemas/ScrapeRequest/properties/screenshot_selector'
-          description: Validated as on /v1/scrape; not applied by the batch worker.
+          description: >-
+            Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape.
         screenshot_format:
           $ref: '#/components/schemas/ScrapeRequest/properties/screenshot_format'
-          description: Validated as on /v1/scrape; not applied by the batch worker.
+          description: >-
+            Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape.
         screenshot_quality:
           $ref: '#/components/schemas/ScrapeRequest/properties/screenshot_quality'
-          description: Validated as on /v1/scrape; not applied by the batch worker.
+          description: >-
+            Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape.
         custom_headers:
           $ref: '#/components/schemas/ScrapeRequest/properties/custom_headers'
-          description: Validated as on /v1/scrape; the batch worker does not send custom headers.
+          description: >-
+            Honoured by the batch worker on every item. Falls back to the project default when unset.
         autoparse:
           $ref: '#/components/schemas/ScrapeRequest/properties/autoparse'
-          description: Validated as on /v1/scrape; not applied by the batch worker.
+          description: >-
+            Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape.
         links:
           $ref: '#/components/schemas/ScrapeRequest/properties/links'
-          description: Validated as on /v1/scrape; not applied by the batch worker.
+          description: >-
+            Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape. Also
+            refused when it comes from the project defaults, and `detail` says so.
         network_capture:
           $ref: '#/components/schemas/ScrapeRequest/properties/network_capture'
-          description: Validated as on /v1/scrape (see NetworkCapture); not applied by the batch worker.
+          description: >-
+            Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape.
         extract:
           $ref: '#/components/schemas/ScrapeRequest/properties/extract'
-          description: Validated as on /v1/scrape; the batch worker returns the raw page, not extracted
-            fields.
+          description: >-
+            Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape.
         extract_preset:
           $ref: '#/components/schemas/ScrapeRequest/properties/extract_preset'
-          description: Validated as on /v1/scrape; not applied by the batch worker.
+          description: >-
+            Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape.
         ai_extract:
           $ref: '#/components/schemas/ScrapeRequest/properties/ai_extract'
-          description: Validated as on /v1/scrape (see AIExtract); not applied by the batch worker.
+          description: >-
+            Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape.
         main_content_only:
           $ref: '#/components/schemas/ScrapeRequest/properties/main_content_only'
-          description: Validated as on /v1/scrape; not applied by the batch worker.
+          description: >-
+            Honoured on `markdown` and `text` items. Unset means off. Falls back to the project default when
+            unset.
         include_tags:
           $ref: '#/components/schemas/ScrapeRequest/properties/include_tags'
-          description: Validated as on /v1/scrape; not applied by the batch worker.
+          description: >-
+            Honoured on `markdown` and `text` items.
         exclude_tags:
           $ref: '#/components/schemas/ScrapeRequest/properties/exclude_tags'
-          description: Validated as on /v1/scrape; not applied by the batch worker.
+          description: >-
+            Honoured on `markdown` and `text` items.
         parse_pdf:
           $ref: '#/components/schemas/ScrapeRequest/properties/parse_pdf'
-          description: Validated as on /v1/scrape (default true); not applied by the batch worker.
+          description: >-
+            The batch worker has no PDF parser. `true` is refused on batch with 400 INVALID_PARAMETER (nothing
+            queued or charged); use /v1/scrape. `false` is accepted.
         response_format:
           $ref: '#/components/schemas/ScrapeRequest/properties/response_format'
-          description: Validated as on /v1/scrape, but the batch worker always returns the raw page body
-            regardless of this value (no markdown, json, text or pdf conversion).
+          description: >-
+            Honoured. `html` (the default) and `json` return the document as retrieved; `markdown` and `text`
+            run the same conversion as /v1/scrape. A document that is not HTML (a PDF, an image, JSON) fails a
+            `markdown` or `text` item with EXTRACTION_FAILED; request `html` to get it as retrieved. `pdf` is
+            refused with 400, also when it comes from the project defaults.
         cache:
           $ref: '#/components/schemas/ScrapeRequest/properties/cache'
-          description: Validated as on /v1/scrape, but on batch it defaults to false (not true) and the
-            worker never reads from the cache.
+          description: >-
+            Batch never reads from the result cache. `true` is refused on batch with 400 INVALID_PARAMETER
+            (nothing queued or charged); use /v1/scrape.
         cache_ttl:
           $ref: '#/components/schemas/ScrapeRequest/properties/cache_ttl'
-          description: Validated as on /v1/scrape; `0` does not imply `cache=false` on batch. Not applied
-            by the batch worker.
+          description: >-
+            A non-zero value is refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use
+            /v1/scrape.
         max_cost:
           $ref: '#/components/schemas/ScrapeRequest/properties/max_cost'
           description: Per-ITEM credit ceiling, checked at submission against the item's dearest outcome
             (400 if exceeded). For a ceiling on the whole run use `credit_budget`.
         original_status:
           $ref: '#/components/schemas/ScrapeRequest/properties/original_status'
-          description: Validated as on /v1/scrape; not applied (result lines always carry the target status
-            in `http_status`).
+          description: >-
+            Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape. Result
+            lines always carry the target status in `http_status`.
         allowed_status_codes:
           $ref: '#/components/schemas/ScrapeRequest/properties/allowed_status_codes'
-          description: Validated as on /v1/scrape; not applied. Billing is fixed to target statuses 200,
-            404 and 410.
+          description: >-
+            Refused on batch with 400 INVALID_PARAMETER (nothing queued or charged); use /v1/scrape. Billing
+            is fixed to target statuses 200, 404 and 410.
     BatchItem:
       description: |
         One URL of a batch: a /v1/scrape request object (every BatchScrapeParams field plus `url`) and an optional
@@ -2021,8 +2073,10 @@ components:
           type: object
           additionalProperties: true
           description: The job-level scrape parameters as stored (your top-level BatchScrapeParams, without
-            `url`), plus `credit_budget_micro` — the run ceiling the worker enforces. Always present,
-            possibly only `credit_budget_micro`.
+            `url`), plus two keys the API sets and you cannot — `credit_budget_micro`, the run ceiling the
+            worker enforces, and `default_proxy_tier` (`direct` or `datacenter`), the exit an item that sets
+            no `proxy`, `premium_proxy`, `proxy_country` or `sticky_key` takes, decided at submission the way
+            `/v1/scrape` decides it. Always present, possibly only those two.
         total_items:
           type: integer
           format: int64
@@ -2217,8 +2271,9 @@ components:
       properties:
         content:
           type: string
-          description: The worker's stored `result` value as raw JSON text (currently a JSON string literal
-            holding the page HTML, so JSON-decode it once to get the HTML). May be a byte prefix when
+          description: The worker's stored `result` value as raw JSON text (a JSON string literal
+            holding the document in the item's `response_format`, so JSON-decode it once to get the html,
+            markdown or text). May be a byte prefix when
             `truncated`, in which case it is not valid JSON.
         bytes:
           type: integer
@@ -3783,18 +3838,20 @@ paths:
         Fetch one URL synchronously and return it as html, markdown, text, a PDF, or a JSON envelope with extracted data.
 
         Choosing an engine (cheapest first):
-        - Default (fetch, 1 credit): plain HTTP, no JavaScript. Add `impersonate=true` (POST only, free) when a site rejects non-browser TLS fingerprints.
+        - Default (fetch, 1 credit): plain HTTP, no JavaScript, presenting a current Chrome TLS/HTTP2 fingerprint (`impersonate`, on by default and free; `impersonate=false` turns it off).
         - `js_render=true` (obscura, 3): content is built by JavaScript, or you need wait/wait_for/actions/block_resources/network_capture.
         - `engine=chromium` (8): needed for screenshot and response_format=pdf. `stealth=true` (camoufox) is coming soon.
         - `mode=auto`: unsure - escalates through the available engines, bills only the rung that worked.
         - Managed proxy pools (`premium_proxy`) are coming soon; during the beta pass your own proxy with `proxy`.
         Browser-only flags on the fetch tier are a 400, never silently ignored.
 
-        Billing: failures cost 0 (errors, bot challenges, timeouts, target statuses other than 200/404/410 unless listed in allowed_status_codes, undelivered screenshots); cache hits cost 0. Check X-Credits-Charged.
+        Billing: failures cost 0 (errors, bot challenges, timeouts, target statuses other than 200/404/410 unless listed in allowed_status_codes, undelivered screenshots). A cache hit is billed at the same price as the fetch that stored it: the cache saves the fetch (latency and load on the target), not credits. Like any request, a hit is refused with 402 when the monthly allowance cannot cover its price. Check X-Credits-Charged.
+
+        Bot challenges: a challenge page attributed to a named vendor (Cloudflare, DataDome, PerimeterX, Akamai) is never returned as a success. A fetch through a managed pool exit that meets one is retried once on a different exit, free (GET/HEAD/OPTIONS only, not with `sticky_key` or `session_id`, never on your own `proxy`). With `premium_proxy=true` or your own `proxy`, no `engine` pin and no `mode=auto`, a request whose page is still a challenge then climbs to camoufox, which waits out or clicks through the interstitial. Only the rung that returned the page is billed (camoufox 25, or the first rung's price), and 0 if every rung was challenged (502 ERR::UPSTREAM::CHALLENGE). A transport error, a refusal with no vendor marker (such as a bare 403) or a non-billable status such as 404 does not climb. The climb is left off for a non-GET method, headless=false, response_format=pdf, a screenshot, actions, a `proxy` that is not http://, a max_cost below the camoufox price, or a deployment without camoufox; an allowance that covers the first rung but not camoufox runs the request without it. X-Engine names the engine that served, each abandoned rung adds an `X-Warning: ESCALATED`, and diagnostics.attempts lists every attempt (in the JSON envelope on a successful climb). Batch items never climb.
 
         Status: the HTTP status is the platform's. A blocked or erroring site is usually still HTTP 200 - read envelope `status` or X-Target-Status for the site's answer. Errors are application/problem+json; retry only when `retryable` is true.
 
-        Not idempotent: there is no idempotency key, and each call performs (and bills) a new scrape unless served from cache. GET and POST accept the same parameters and behave identically, except that GET does not accept `impersonate`.
+        Not idempotent: there is no idempotency key, and each call bills again, whether it performs a new scrape or is served from cache. GET and POST accept the same parameters and behave identically.
       security:
       - bearerAuth: []
       x-spicrawl-scope: scrape
@@ -3825,7 +3882,7 @@ paths:
         ai_extract: 4
         ai_extract_note: added on top of the engine price; the only additive item
         failures: 0
-        cache_hit: 0
+        cache_hit: the price of the fetch that stored it
         billable_target_statuses:
         - 200
         - 404
@@ -3833,6 +3890,8 @@ paths:
         billable_target_statuses_note: plus any in allowed_status_codes; other target statuses return
           the body at 0
         mode_auto: bills only the rung that succeeded; reserves the dearest rung against the monthly allowance
+        challenge_escalation: with premium_proxy or proxy, a vendor challenge may climb to camoufox; bills
+          only the rung that returned the page, 0 if every rung was challenged; batch items never climb
         impersonate: 0
         extract_autoparse_links_network_capture: 0
       parameters:
@@ -3882,6 +3941,18 @@ paths:
         schema:
           type: boolean
           default: false
+      - name: impersonate
+        in: query
+        required: false
+        description: Fetch tier only. Present a current Chrome TLS/HTTP2 fingerprint, with matching browser
+          headers and Accept-Encoding, to pass passive fingerprint checks. On by default, free, no JavaScript;
+          `impersonate=false` turns it off and the fetch uses a non-browser TLS handshake. Ignored on render
+          engines.
+          If omitted, the project's stored default applies, and true when the project sets none. Accepts
+          true/false/1/0; a bare `?impersonate` means true.
+        schema:
+          type: boolean
+          default: true
       - name: mode
         in: query
         required: false
@@ -3913,9 +3984,10 @@ paths:
         required: false
         description: 'Coming soon. Use residential exits from the managed pool: fetch 10, obscura 25, chromium 32 credits
           (camoufox stays 25). If no residential exit is available the request fails 503 ERR::PROXY::EXHAUSTED
-          rather than falling back; ignored (with X-Warning PROXY_FLAG_IGNORED) when `proxy` is set. If
-          omitted, the project''s stored default applies. Accepts true/false/1/0; a bare `?premium_proxy`
-          means true.'
+          rather than falling back; ignored (with X-Warning PROXY_FLAG_IGNORED) when `proxy` is set. A
+          bot challenge from a named vendor is retried on a different exit (fetch tier), then climbs to
+          camoufox; see "Bot challenges" in the operation description. If omitted, the project''s stored default applies.
+          Accepts true/false/1/0; a bare `?premium_proxy` means true.'
         schema:
           type: boolean
           default: false
@@ -3925,7 +3997,9 @@ paths:
         description: Coming soon. ISO 3166-1 alpha-2 exit country (case-insensitive), within the residential pool.
           Requires premium_proxy=true (400 ERR::REQUEST::INCOMPATIBLE_FLAGS otherwise) unless `proxy`
           is set, in which case it is ignored with a warning; an unavailable country is 503 ERR::PROXY::EXHAUSTED,
-          never substituted. If omitted, the project's stored default applies.
+          never substituted. A browser render takes its timezone and locale from this country or, when
+          it is omitted, from the country of the pool exit it was assigned. If omitted, the project's
+          stored default applies.
         schema:
           type: string
           pattern: ^[A-Za-z]{2}$
@@ -3935,6 +4009,8 @@ paths:
         description: Your own proxy URL (http, https, socks5 or socks5h; credentials in userinfo). Takes
           precedence over premium_proxy/proxy_country and adds 0 proxy credits; loopback hosts are refused
           with 400 ERR::SECURITY::SSRF_BLOCKED. An unreachable proxy fails 502 ERR::PROXY::UNREACHABLE.
+          A bot challenge from a named vendor climbs to camoufox when the proxy is http://; see "Bot
+          challenges" in the operation description.
         schema:
           type: string
       - name: proxy_verify
@@ -4235,10 +4311,11 @@ paths:
       - name: cache
         in: query
         required: false
-        description: 'Serve a stored result younger than cache_ttl (Cache-State: hit, 0 credits). Only
-          billable successes of GET-method requests without session_id or actions are stored. Set false
-          for time-sensitive data; cache=false with cache_ttl>0 is 400 ERR::REQUEST::INCOMPATIBLE_FLAGS.
-          Accepts true/false/1/0; a bare `?cache` means true.'
+        description: 'Serve a stored result younger than cache_ttl (Cache-State: hit). A hit is billed at
+          the same price as the fetch that stored it: the cache saves the fetch (latency and load on the
+          target), not credits. Only billable successes of GET-method requests without session_id or
+          actions are stored. Set false for time-sensitive data; cache=false with cache_ttl>0 is 400
+          ERR::REQUEST::INCOMPATIBLE_FLAGS. Accepts true/false/1/0; a bare `?cache` means true.'
         schema:
           type: boolean
           default: true
@@ -4315,13 +4392,13 @@ paths:
               schema:
                 type: string
             X-Credits-Charged:
-              description: Credits actually billed; 0 on any failure, cache hit, or non-billable target
-                status.
+              description: Credits actually billed; 0 on any failure or non-billable target status. A
+                cache hit is billed at the same price as the fetch that stored it.
               schema:
                 type: integer
             X-Request-Cost:
-              description: Price of the engine/proxy tier that ran (0 on a cache hit). Differs from X-Credits-Charged
-                exactly when nothing was billed.
+              description: Price of the engine/proxy tier that ran (on a cache hit, the tier that fetched
+                the stored copy). Differs from X-Credits-Charged exactly when nothing was billed.
               schema:
                 type: integer
             X-Credits-Remaining:
@@ -4333,7 +4410,8 @@ paths:
                 type: integer
                 minimum: 0
             X-Engine:
-              description: Engine that ran.
+              description: Engine that ran. After an escalation (mode=auto, or a bot challenge climbing
+                to camoufox), the rung that served the page.
               schema:
                 type: string
                 enum:
@@ -4502,18 +4580,20 @@ paths:
         Fetch one URL synchronously and return it as html, markdown, text, a PDF, or a JSON envelope with extracted data.
 
         Choosing an engine (cheapest first):
-        - Default (fetch, 1 credit): plain HTTP, no JavaScript. Add `impersonate=true` (POST only, free) when a site rejects non-browser TLS fingerprints.
+        - Default (fetch, 1 credit): plain HTTP, no JavaScript, presenting a current Chrome TLS/HTTP2 fingerprint (`impersonate`, on by default and free; `impersonate=false` turns it off).
         - `js_render=true` (obscura, 3): content is built by JavaScript, or you need wait/wait_for/actions/block_resources/network_capture.
         - `engine=chromium` (8): needed for screenshot and response_format=pdf. `stealth=true` (camoufox) is coming soon.
         - `mode=auto`: unsure - escalates through the available engines, bills only the rung that worked.
         - Managed proxy pools (`premium_proxy`) are coming soon; during the beta pass your own proxy with `proxy`.
         Browser-only flags on the fetch tier are a 400, never silently ignored.
 
-        Billing: failures cost 0 (errors, bot challenges, timeouts, target statuses other than 200/404/410 unless listed in allowed_status_codes, undelivered screenshots); cache hits cost 0. Check X-Credits-Charged.
+        Billing: failures cost 0 (errors, bot challenges, timeouts, target statuses other than 200/404/410 unless listed in allowed_status_codes, undelivered screenshots). A cache hit is billed at the same price as the fetch that stored it: the cache saves the fetch (latency and load on the target), not credits. Like any request, a hit is refused with 402 when the monthly allowance cannot cover its price. Check X-Credits-Charged.
+
+        Bot challenges: a challenge page attributed to a named vendor (Cloudflare, DataDome, PerimeterX, Akamai) is never returned as a success. A fetch through a managed pool exit that meets one is retried once on a different exit, free (GET/HEAD/OPTIONS only, not with `sticky_key` or `session_id`, never on your own `proxy`). With `premium_proxy=true` or your own `proxy`, no `engine` pin and no `mode=auto`, a request whose page is still a challenge then climbs to camoufox, which waits out or clicks through the interstitial. Only the rung that returned the page is billed (camoufox 25, or the first rung's price), and 0 if every rung was challenged (502 ERR::UPSTREAM::CHALLENGE). A transport error, a refusal with no vendor marker (such as a bare 403) or a non-billable status such as 404 does not climb. The climb is left off for a non-GET method, headless=false, response_format=pdf, a screenshot, actions, a `proxy` that is not http://, a max_cost below the camoufox price, or a deployment without camoufox; an allowance that covers the first rung but not camoufox runs the request without it. X-Engine names the engine that served, each abandoned rung adds an `X-Warning: ESCALATED`, and diagnostics.attempts lists every attempt (in the JSON envelope on a successful climb). Batch items never climb.
 
         Status: the HTTP status is the platform's. A blocked or erroring site is usually still HTTP 200 - read envelope `status` or X-Target-Status for the site's answer. Errors are application/problem+json; retry only when `retryable` is true.
 
-        Not idempotent: there is no idempotency key, and each call performs (and bills) a new scrape unless served from cache. GET and POST accept the same parameters and behave identically, except that GET does not accept `impersonate`.
+        Not idempotent: there is no idempotency key, and each call bills again, whether it performs a new scrape or is served from cache. GET and POST accept the same parameters and behave identically.
       security:
       - bearerAuth: []
       x-spicrawl-scope: scrape
@@ -4544,7 +4624,7 @@ paths:
         ai_extract: 4
         ai_extract_note: added on top of the engine price; the only additive item
         failures: 0
-        cache_hit: 0
+        cache_hit: the price of the fetch that stored it
         billable_target_statuses:
         - 200
         - 404
@@ -4552,6 +4632,8 @@ paths:
         billable_target_statuses_note: plus any in allowed_status_codes; other target statuses return
           the body at 0
         mode_auto: bills only the rung that succeeded; reserves the dearest rung against the monthly allowance
+        challenge_escalation: with premium_proxy or proxy, a vendor challenge may climb to camoufox; bills
+          only the rung that returned the page, 0 if every rung was challenged; batch items never climb
         impersonate: 0
         extract_autoparse_links_network_capture: 0
       requestBody:
@@ -4609,13 +4691,13 @@ paths:
               schema:
                 type: string
             X-Credits-Charged:
-              description: Credits actually billed; 0 on any failure, cache hit, or non-billable target
-                status.
+              description: Credits actually billed; 0 on any failure or non-billable target status. A
+                cache hit is billed at the same price as the fetch that stored it.
               schema:
                 type: integer
             X-Request-Cost:
-              description: Price of the engine/proxy tier that ran (0 on a cache hit). Differs from X-Credits-Charged
-                exactly when nothing was billed.
+              description: Price of the engine/proxy tier that ran (on a cache hit, the tier that fetched
+                the stored copy). Differs from X-Credits-Charged exactly when nothing was billed.
               schema:
                 type: integer
             X-Credits-Remaining:
@@ -4627,7 +4709,8 @@ paths:
                 type: integer
                 minimum: 0
             X-Engine:
-              description: Engine that ran.
+              description: Engine that ran. After an escalation (mode=auto, or a bot challenge climbing
+                to camoufox), the rung that served the page.
               schema:
                 type: string
                 enum: