From 3e5bcc8cb24ee0993327367022a67aa2babd6732 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 4 Apr 2026 14:53:40 +0100
Subject: [PATCH] docs: refresh isolated cron model switch refs

---
 docs/automation/cron-jobs.md | 17 +++++++++++++++++
 docs/cli/cron.md             | 13 +++++++++++++
 docs/help/faq.md             | 29 +++++++++++++++++++++++++++++
 3 files changed, 59 insertions(+)

diff --git a/docs/automation/cron-jobs.md b/docs/automation/cron-jobs.md
index 84594e46105..59cd2d75515 100644
--- a/docs/automation/cron-jobs.md
+++ b/docs/automation/cron-jobs.md
@@ -90,6 +90,23 @@ model selection instead. Configured fallback chains still apply, but a plain
 model override with no explicit per-job fallback list no longer appends the
 agent primary as a hidden extra retry target.
 
+Model-selection precedence for isolated jobs is:
+
+1. Gmail hook model override (when the run came from Gmail and that override is allowed)
+2. Per-job payload `model`
+3. Stored cron session model override
+4. Agent/default model selection
+
+Fast mode follows the resolved live selection too. If the selected model config
+has `params.fastMode`, isolated cron uses that by default. A stored session
+`fastMode` override still wins over config in either direction.
+
+If an isolated run hits a live model-switch handoff, cron retries with the
+switched provider/model and persists that live selection before retrying. When
+the switch also carries a new auth profile, cron persists that auth profile
+override too. Retries are bounded: after the initial attempt plus 2 switch
+retries, cron aborts instead of looping forever.
+
 ## Delivery and output
 
 | Mode       | What happens                                             |
diff --git a/docs/cli/cron.md b/docs/cli/cron.md
index f31c7ca6714..3dfa3fac086 100644
--- a/docs/cli/cron.md
+++ b/docs/cli/cron.md
@@ -50,6 +50,19 @@ model selection instead. Configured fallback chains still apply, but a plain
 model override with no explicit per-job fallback list no longer appends the
 agent primary as a hidden extra retry target.
 
+Note: isolated cron model precedence is Gmail-hook override first, then per-job
+`--model`, then any stored cron-session model override, then the normal
+agent/default selection.
+
+Note: isolated cron fast mode follows the resolved live model selection. Model
+config `params.fastMode` applies by default, but a stored session `fastMode`
+override still wins over config.
+
+Note: if an isolated run throws `LiveSessionModelSwitchError`, cron persists the
+switched provider/model (and switched auth profile override when present) before
+retrying. The outer retry loop is bounded to 2 switch retries after the initial
+attempt, then aborts instead of looping forever.
+
 Note: failure notifications use `delivery.failureDestination` first, then
 global `cron.failureDestination`, and finally fall back to the job's primary
 announce target when no explicit failure destination is configured.
diff --git a/docs/help/faq.md b/docs/help/faq.md
index d58cb5e2930..2bcea687182 100644
--- a/docs/help/faq.md
+++ b/docs/help/faq.md
@@ -1046,6 +1046,35 @@ for usage/billing and raise limits as needed.
 
   </Accordion>
 
+  <Accordion title="Why did an isolated cron run switch models or retry once?">
+    That is usually the live model-switch path, not duplicate scheduling.
+
+    Isolated cron can persist a runtime model handoff and retry when the active
+    run throws `LiveSessionModelSwitchError`. The retry keeps the switched
+    provider/model, and if the switch carried a new auth profile override, cron
+    persists that too before retrying.
+
+    Related selection rules:
+
+    - Gmail hook model override wins first when applicable.
+    - Then per-job `model`.
+    - Then any stored cron-session model override.
+    - Then the normal agent/default model selection.
+
+    The retry loop is bounded. After the initial attempt plus 2 switch retries,
+    cron aborts instead of looping forever.
+
+    Debug:
+
+    ```bash
+    openclaw cron runs --id <jobId> --limit 50
+    openclaw tasks show <runId-or-sessionKey>
+    ```
+
+    Docs: [Cron jobs](/automation/cron-jobs), [cron CLI](/cli/cron).
+
+  </Accordion>
+
   <Accordion title="How do I install skills on Linux?">
     Use native `openclaw skills` commands or drop skills into your workspace. The macOS Skills UI isn't available on Linux.
     Browse skills at [https://clawhub.ai](https://clawhub.ai).