From 6854f95f97f90feb2ebfb64b69afd92977581cad Mon Sep 17 00:00:00 2001 From: Stefano Guerrini Date: Wed, 9 Sep 2026 16:42:08 +0200 Subject: [PATCH 1/4] fix(skills): make auto mode the obvious default in protected-fetch Measured: with the skills installed, the agent recommended premium_proxy in 6 of 8 answers to a plain 'fetch this Cloudflare page' question, where nobody asked about configuration. That pair with js_render is 25 credits per request against 1 for a basic call. The old text said to start with auto mode, then listed the manual line as a peer example with no cost attached, so it read as the stronger option for a hard target. Manual mode now sits in its own block, carries its price, and is framed as the path after auto mode has already failed. --- skills/protected-fetch/SKILL.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/skills/protected-fetch/SKILL.md b/skills/protected-fetch/SKILL.md index 9af8a46..b514379 100644 --- a/skills/protected-fetch/SKILL.md +++ b/skills/protected-fetch/SKILL.md @@ -1,6 +1,6 @@ --- name: protected-fetch -description: Use Zenrows Protected Fetch for anti-bot-protected page retrieval. +description: Use Zenrows Protected Fetch in auto mode for anti-bot-protected page retrieval. Auto mode handles the anti-bot escalation, so never enable JS rendering or premium proxies yourself on a first attempt. version: 0.1.0 requires_backend_capabilities: [protected_fetch] --- @@ -16,18 +16,32 @@ cannot. This is the **core primitive** — backed by Zenrows **Fetch** - The target has anti-bot protection, needs JS rendering, or geo-specific access. ## How to call + +Auto mode is the answer for anti-bot targets, Cloudflare included. It escalates +for you and bills only for the configuration that succeeds. + ``` -zenrows fetch # Adaptive Stealth Mode (recommended) +zenrows fetch # Adaptive Stealth Mode. Start here, always zenrows fetch --output markdown # convert to Markdown -zenrows fetch --manual --js-render --premium-proxy # full manual control -zenrows fetch --proxy-country us # geo-target (auto mode; in manual mode needs --premium-proxy) +zenrows fetch --proxy-country us # geo-target, works in auto mode zenrows fetch --wait-for ".price" # wait for a selector ``` +Manual mode exists for the rare case where auto mode has already failed and a +trace shows why. It costs more and it makes the escalation your problem: + +``` +zenrows fetch --manual --js-render --premium-proxy # 25 credits per request +``` + ## Rules -- Start with **auto mode**. In auto mode, `js_render` and `premium_proxy` are - managed for you — passing them manually requires `--manual` - (otherwise you get `PARAM_CONFLICT_AUTO_MANUAL`). +- Start with **auto mode**. Enabling `--js-render` and `--premium-proxy` yourself + costs 25 credits per request against 1 for a basic call, and auto mode reaches + the same configuration only when the target actually needs it. +- A hard target is not a reason to skip auto mode. It is the reason auto mode + exists. +- In auto mode `js_render` and `premium_proxy` are managed for you. Passing them + manually requires `--manual`, otherwise you get `PARAM_CONFLICT_AUTO_MANUAL`. - `--proxy-country` works in auto mode on its own; in `--manual` mode it also needs `--premium-proxy` (else `PARAM_PROXY_COUNTRY_REQUIRES_PREMIUM`). - You are billed only for the configuration that succeeds. From 4e2884d50c722f1d80ebdbd6d51ebb9f72da0d99 Mon Sep 17 00:00:00 2001 From: Stefano Guerrini Date: Wed, 9 Sep 2026 17:11:44 +0200 Subject: [PATCH 2/4] fix(skills): point extract at auto mode before manual JS rendering The extract skill offered --manual --js-render as an ordinary fix for missing fields, with no mention of auto mode and no cost. Auto mode already renders JS when the target needs it, and manual rendering is 5 credits per request against 1. --- skills/extract/SKILL.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/skills/extract/SKILL.md b/skills/extract/SKILL.md index c5d4672..1e444f2 100644 --- a/skills/extract/SKILL.md +++ b/skills/extract/SKILL.md @@ -28,7 +28,9 @@ zenrows extract --validate # fail if not valid JSON ## Rules - Validate on a single page before scaling across many URLs. -- If Autoparse misses fields, switch to `--css` with explicit selectors, or add - `--manual --js-render` for JS-heavy pages. +- If Autoparse misses fields, switch to `--css` with explicit selectors. Auto + mode already renders JS when the target needs it, so reach for + `--manual --js-render` only after auto mode has returned an incomplete page: + it costs 5 credits per request against 1, and it makes the escalation yours. See [[protected-fetch]] for retrieval semantics. From 991af4834cac1175db55dac78025785d2d1311a9 Mon Sep 17 00:00:00 2001 From: Stefano Guerrini Date: Wed, 9 Sep 2026 17:13:40 +0200 Subject: [PATCH 3/4] fix(skills): retry in auto mode before manual escalation in trace-debug The failure map sent the agent straight from FETCH_FAILED to --manual --js-render and then --premium-proxy, with no mention of auto mode and no cost. Auto mode escalates on its own and bills only for the configuration that succeeds, so it is the first retry, not the last resort. --- skills/trace-debug/SKILL.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/skills/trace-debug/SKILL.md b/skills/trace-debug/SKILL.md index c1e8406..10e264d 100644 --- a/skills/trace-debug/SKILL.md +++ b/skills/trace-debug/SKILL.md @@ -19,8 +19,11 @@ zenrows trace export # JSON for sharing ``` ## Failure → action map -- `FETCH_FAILED` / empty content → retry `--manual --js-render`, then add - `--premium-proxy`; for slow pages add `--wait-for `. +- `FETCH_FAILED` / empty content → first retry in auto mode (`mode=auto`), which + escalates for you and bills only for what succeeds. For slow pages add + `--wait-for `. Only when auto mode has failed on its own, take + manual control with `--manual --js-render` (5 credits per request), then + `--premium-proxy` (25 with both, against 1 for a basic call). - `REQUEST_TIMEOUT` → the CLI stopped waiting; the API was reached. Raise `--timeout` (default 120000ms, above the API's own 90s budget), or drop `--wait-for` so the request finishes inside that budget and the API returns From 17cd49d5ca4739c40e29f7ea898305d2658c8b89 Mon Sep 17 00:00:00 2001 From: Stefano Guerrini Date: Wed, 9 Sep 2026 17:20:47 +0200 Subject: [PATCH 4/4] fix(skills): cite the cost model instead of repeating prices The multipliers live in cost-control. Repeating the numbers in three more skills means they go stale in three more places the next time pricing moves, and a skill that quotes a wrong price is worse than one that quotes none. The wording keeps what made the change work: the cost warning stays at the point of temptation, next to the flag, and it still says which direction is expensive. Only the figure moves to the one file that owns it. --- skills/extract/SKILL.md | 3 ++- skills/protected-fetch/SKILL.md | 7 ++++--- skills/trace-debug/SKILL.md | 5 +++-- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/skills/extract/SKILL.md b/skills/extract/SKILL.md index 1e444f2..87bb271 100644 --- a/skills/extract/SKILL.md +++ b/skills/extract/SKILL.md @@ -31,6 +31,7 @@ zenrows extract --validate # fail if not valid JSON - If Autoparse misses fields, switch to `--css` with explicit selectors. Auto mode already renders JS when the target needs it, so reach for `--manual --js-render` only after auto mode has returned an incomplete page: - it costs 5 credits per request against 1, and it makes the escalation yours. + it costs several times a basic call ([[cost-control]]) and it makes the + escalation yours. See [[protected-fetch]] for retrieval semantics. diff --git a/skills/protected-fetch/SKILL.md b/skills/protected-fetch/SKILL.md index b514379..0448f46 100644 --- a/skills/protected-fetch/SKILL.md +++ b/skills/protected-fetch/SKILL.md @@ -31,13 +31,14 @@ Manual mode exists for the rare case where auto mode has already failed and a trace shows why. It costs more and it makes the escalation your problem: ``` -zenrows fetch --manual --js-render --premium-proxy # 25 credits per request +zenrows fetch --manual --js-render --premium-proxy # the most expensive path, see [[cost-control]] ``` ## Rules - Start with **auto mode**. Enabling `--js-render` and `--premium-proxy` yourself - costs 25 credits per request against 1 for a basic call, and auto mode reaches - the same configuration only when the target actually needs it. + is the most expensive configuration this API offers, by a wide margin, and auto + mode reaches the same place only when the target actually needs it. The + multipliers are in [[cost-control]]. - A hard target is not a reason to skip auto mode. It is the reason auto mode exists. - In auto mode `js_render` and `premium_proxy` are managed for you. Passing them diff --git a/skills/trace-debug/SKILL.md b/skills/trace-debug/SKILL.md index 10e264d..221dc5c 100644 --- a/skills/trace-debug/SKILL.md +++ b/skills/trace-debug/SKILL.md @@ -22,8 +22,9 @@ zenrows trace export # JSON for sharing - `FETCH_FAILED` / empty content → first retry in auto mode (`mode=auto`), which escalates for you and bills only for what succeeds. For slow pages add `--wait-for `. Only when auto mode has failed on its own, take - manual control with `--manual --js-render` (5 credits per request), then - `--premium-proxy` (25 with both, against 1 for a basic call). + manual control with `--manual --js-render`, then `--premium-proxy`. Each step + multiplies the cost of the request, and both together are the most expensive + configuration available ([[cost-control]]). - `REQUEST_TIMEOUT` → the CLI stopped waiting; the API was reached. Raise `--timeout` (default 120000ms, above the API's own 90s budget), or drop `--wait-for` so the request finishes inside that budget and the API returns