diff --git a/.github/workflows/tutorials.yml b/.github/workflows/tutorials.yml
new file mode 100644
index 0000000..8c3476c
--- /dev/null
+++ b/.github/workflows/tutorials.yml
@@ -0,0 +1,70 @@
+name: Tutorial tests
+
+# Runs the beginner path's commands for real against the pinned OpenClaw
+# (scripts/openclaw-version.txt): onboarding, a Gateway on loopback with token
+# auth, automations, skills, backups, audits. One script per page in
+# scripts/tutorial-tests/. Steps that need a model key or a channel account are
+# listed as skipped, with the reason. See scripts/README.md.
+#
+# Report only for now: the job passes even when a page fails, and the summary
+# and tutorial-report.json say which steps failed. To make it blocking, set the
+# repository variable TUTORIALS_STRICT=1 (Settings > Secrets and variables >
+# Actions > Variables), or run it manually with "strict" ticked.
+
+on:
+  push:
+    branches: [gh-pages]
+    paths:
+      - 'docs/**'
+      - 'scripts/tutorial-tests/**'
+      - 'scripts/openclaw-version.txt'
+      - '.github/workflows/tutorials.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'scripts/tutorial-tests/**'
+      - 'scripts/openclaw-version.txt'
+      - '.github/workflows/tutorials.yml'
+  schedule:
+    - cron: '17 5 * * 1' # Mondays 05:17 UTC
+  workflow_dispatch:
+    inputs:
+      strict:
+        description: Fail the job when a page fails
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tutorials-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tutorials:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    env:
+      TUTORIALS_STRICT: ${{ (github.event_name == 'workflow_dispatch' && inputs.strict) && '1' || vars.TUTORIALS_STRICT || '0' }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24 # openclaw needs >=24.16
+      - name: Install pinned OpenClaw
+        run: |
+          npm i --prefix tools/openclaw --no-save --ignore-scripts --no-audit --no-fund \
+            "openclaw@$(tr -d '[:space:]' < scripts/openclaw-version.txt)"
+          tools/openclaw/node_modules/.bin/openclaw --version
+          node --version; npm --version
+      - name: Run tutorial tests
+        run: node scripts/tutorial-tests/run.mjs --json tutorial-report.json
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: tutorial-report
+          path: |
+            tutorial-report.json
+            tutorial-report/
+          if-no-files-found: ignore
diff --git a/.gitignore b/.gitignore
index c90cb90..bf2e203 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,3 +22,7 @@ yarn-error.log*
 # Snippet gates
 /tools/openclaw
 snippet-report.json
+
+# Tutorial tests
+tutorial-report.json
+/tutorial-report
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
index c01e567..f7e758f 100644
--- a/docs/getting-started/quick-start.md
+++ b/docs/getting-started/quick-start.md
@@ -2,6 +2,10 @@
 last_update:
   date: 2026-10-18
 verified_with: 2026.10.4
+ci_verified:
+  version: 2026.10.4
+  date: 2026-10-18
+  steps: 24
 title: Quick Start
 description: Get OpenClaw running and talking to you in about 5 minutes, from install to first conversation
 keywords: [openclaw, openclaw getting started, openclaw tutorial, openclaw quick start, openclaw first steps, how to use openclaw, openclaw beginner guide]
@@ -168,7 +172,7 @@ openclaw channels add discord
 Each command opens guided setup for that channel. By default, unknown senders who DM your bot get a pairing code instead of the agent. Approve them with:
 
 ```bash
-openclaw pairing list
+openclaw pairing list telegram
 openclaw pairing approve telegram <code>
 ```
 
@@ -206,7 +210,7 @@ openclaw cron add --name "Morning brief" --cron "0 9 * * *" --session isolated \
 `openclaw automations` is the same command under its new name. To give the heartbeat a short standing checklist, store it in its monitor scratch: find the job with `openclaw cron list --all` (it is listed as `Heartbeat (main)`), then `openclaw cron scratch <jobId> --set "..."`.
 
 :::note Coming from an older version?
-`HEARTBEAT.md` is retired and no longer read. `openclaw doctor --fix` imports an existing file into the heartbeat's monitor scratch and converts its `tasks:` entries into automations.
+`HEARTBEAT.md` is retired and no longer read. `openclaw doctor --fix`, run with the Gateway stopped, imports an existing file into the heartbeat's monitor scratch and converts its `tasks:` entries into automations.
 :::
 
 See the [Heartbeat Guide](/guides/heartbeat), [Automation](/guides/automation) and the official [heartbeat docs](https://docs.openclaw.ai/gateway/heartbeat).
diff --git a/docs/guides/first-7-days/day-1-make-it-yours.md b/docs/guides/first-7-days/day-1-make-it-yours.md
index 3ea8d72..8589ad9 100644
--- a/docs/guides/first-7-days/day-1-make-it-yours.md
+++ b/docs/guides/first-7-days/day-1-make-it-yours.md
@@ -2,6 +2,10 @@
 last_update:
   date: 2026-10-18
 verified_with: 2026.10.4
+ci_verified:
+  version: 2026.10.4
+  date: 2026-10-18
+  steps: 17
 title: "Day 1: Make It Yours"
 description: "Personalize your OpenClaw bot — name, personality, boundaries, and your first real conversation"
 keywords: [openclaw, setup, personalize, soul.md, agents.md, user.md, first day, customize agent, bot personality]
@@ -53,7 +57,7 @@ The workspace holds a handful of Markdown files that load at the start of every
 | `MEMORY.md` | Curated long-term facts and decisions (optional). |
 | `memory/YYYY-MM-DD.md` | Daily notes the agent writes as it goes. |
 
-You can edit them with any text editor, or in the Control UI under **Settings → Agents → Files**. If you delete one by accident, `openclaw setup` recreates missing defaults without overwriting the files you kept.
+You can edit them with any text editor, or in the Control UI under **Settings → Agents → Files**. If you delete one by accident, `openclaw setup --baseline` recreates missing defaults without overwriting the files you kept. (Bare `openclaw setup` on a configured install opens a chat instead.)
 
 ---
 
@@ -127,7 +131,7 @@ Edit `~/.openclaw/workspace/IDENTITY.md`:
 - **Avatar:** avatars/nova.png
 ```
 
-Replace `(pick one)` with a single emoji. Placeholder text in parentheses is ignored, not saved. The avatar is a workspace-relative path, an `http(s)` URL, or a data URI; drop the line if you don't have one.
+Replace `(pick one)` with a single emoji, or delete the line. Only the template's own placeholder text is ignored; anything else you leave there, including `(pick one)`, is saved as the value. The avatar is a workspace-relative path, an `http(s)` URL, or a data URI; drop the line if you don't have one.
 
 To push the file into the agent's config (used by the Control UI and other surfaces), run:
 
diff --git a/docs/guides/first-7-days/day-3-automation.md b/docs/guides/first-7-days/day-3-automation.md
index d14781c..ce055dd 100644
--- a/docs/guides/first-7-days/day-3-automation.md
+++ b/docs/guides/first-7-days/day-3-automation.md
@@ -2,6 +2,10 @@
 last_update:
   date: 2026-10-18
 verified_with: 2026.10.4
+ci_verified:
+  version: 2026.10.4
+  date: 2026-10-18
+  steps: 30
 title: "Day 3: Set It Free"
 description: "Schedule automations for morning briefings and checks, and tune the heartbeat monitor so your bot reaches out on its own"
 keywords: [openclaw, automation, automations, cron, heartbeat setup, scheduled tasks, morning briefing, proactive alerts]
@@ -28,7 +32,7 @@ OpenClaw has two kinds of scheduled work, and both are run by the Gateway's auto
 Rule of thumb: if the task has a time or interval in its name, it's an automation.
 
 :::info Coming from an older guide?
-Older OpenClaw versions read heartbeat tasks from a `HEARTBEAT.md` file in the workspace. That file was retired in 2026.8.1: OpenClaw no longer creates or reads it. If you still have one, run `openclaw doctor --fix`. Doctor imports its instructions into the heartbeat's monitor scratch, turns valid `tasks:` entries into automations, and archives the original ([retired HEARTBEAT.md](https://docs.openclaw.ai/reference/templates/HEARTBEAT)).
+Older OpenClaw versions read heartbeat tasks from a `HEARTBEAT.md` file in the workspace. That file was retired in 2026.8.1: OpenClaw no longer creates or reads it. If you still have one, stop the Gateway (`openclaw gateway stop`) and run `openclaw doctor --fix`. Doctor imports its instructions into the heartbeat's monitor scratch, turns valid `tasks:` entries into automations, and archives the original ([retired HEARTBEAT.md](https://docs.openclaw.ai/reference/templates/HEARTBEAT)).
 :::
 
 ## Before You Start: Where Messages Go
diff --git a/docs/guides/first-7-days/day-4-skills.md b/docs/guides/first-7-days/day-4-skills.md
index dd91a68..523f107 100644
--- a/docs/guides/first-7-days/day-4-skills.md
+++ b/docs/guides/first-7-days/day-4-skills.md
@@ -2,6 +2,10 @@
 last_update:
   date: 2026-10-18
 verified_with: 2026.10.4
+ci_verified:
+  version: 2026.10.4
+  date: 2026-10-18
+  steps: 20
 title: "Day 4: Supercharge It"
 description: "Use the skills that ship with OpenClaw, find more on ClawHub, and check them before you install"
 keywords: [openclaw, skills, install skills, clawhub, skill tutorial, community skills, extend bot]
diff --git a/docs/guides/first-7-days/day-7-production.md b/docs/guides/first-7-days/day-7-production.md
index f7bee0b..d31cd11 100644
--- a/docs/guides/first-7-days/day-7-production.md
+++ b/docs/guides/first-7-days/day-7-production.md
@@ -2,6 +2,10 @@
 last_update:
   date: 2026-10-18
 verified_with: 2026.10.4
+ci_verified:
+  version: 2026.10.4
+  date: 2026-10-18
+  steps: 30
 title: "Day 7: Lock It Down"
 description: "A validated security baseline, cost checks, monitoring, backups and safe upgrades for a long-running OpenClaw setup"
 keywords: [openclaw, production, hardening, monitoring, security, backup, upgrade, cost]
@@ -207,10 +211,12 @@ Use `openclaw update`, not `npm update -g openclaw`. The updater validates the t
 **4. Check:**
 
 ```bash
-openclaw doctor --fix
+openclaw doctor
 openclaw status --deep
 ```
 
+The updater already ran the required Doctor migrations; `openclaw doctor` reports anything left. If it suggests repairs, stop the Gateway first (`openclaw gateway stop`), run `openclaw doctor --fix`, then `openclaw gateway start`: with the Gateway running, `doctor --fix` cannot lock the state database and exits with `GatewayStateOwnerContentionError`.
+
 Confirm every channel reconnects and your automations are listed in `openclaw cron list`.
 
 **5. If something breaks:** don't just reinstall an older version. Downgrading the package does **not** reverse config or database migrations. Upstream's supported recovery is to restore a verified pre-update backup together with the OpenClaw release that made it ([rollback and recovery](https://docs.openclaw.ai/install/updating/rollback-and-recovery)):
diff --git a/docs/guides/heartbeat.md b/docs/guides/heartbeat.md
index 6b1d1e0..f3b78c9 100644
--- a/docs/guides/heartbeat.md
+++ b/docs/guides/heartbeat.md
@@ -2,6 +2,10 @@
 last_update:
   date: 2026-10-18
 verified_with: 2026.10.4
+ci_verified:
+  version: 2026.10.4
+  date: 2026-10-18
+  steps: 39
 title: Heartbeat Guide
 description: How OpenClaw's heartbeat works in v2026.10 — agents.defaults.heartbeat, monitor scratch, automation jobs for recurring checks, cost control, and migrating from HEARTBEAT.md
 keywords: [openclaw, openclaw heartbeat, monitor scratch, automations, activeHours, HEARTBEAT.md migration]
@@ -118,12 +122,18 @@ Scratch becomes part of the prompt. Do not put API keys, tokens or phone numbers
 
 ### Migrating from HEARTBEAT.md {#migrating-from-heartbeatmd}
 
-If you used `~/.openclaw/workspace/HEARTBEAT.md` (or a per-agent workspace copy) before v2026.8.1, run:
+If you used `~/.openclaw/workspace/HEARTBEAT.md` (or a per-agent workspace copy) before v2026.8.1, stop the Gateway and run Doctor:
 
 ```bash
+openclaw gateway stop
 openclaw doctor --fix
+openclaw gateway start
 ```
 
+Doctor needs exclusive access to the state database. With the Gateway running, `doctor --fix` exits with `GatewayStateOwnerContentionError` and changes nothing.
+
+Doctor only imports into an empty scratch. If the heartbeat already has different scratch, or you cleared it with `--unset`, Doctor warns and leaves `HEARTBEAT.md` where it is; copy what you need with `openclaw cron scratch <jobId> --file ~/.openclaw/workspace/HEARTBEAT.md`.
+
 Doctor creates the monitor rows from `agents.*.heartbeat`, imports each workspace `HEARTBEAT.md` into that agent's monitor scratch, converts a structured `tasks:` block into separate automation jobs, archives the original under the state directory (`backups/heartbeat-migration/`), and deletes the file. After that the runtime reads scratch only.
 
 :::warning Bare `interval` numbers are read as minutes
@@ -305,7 +315,7 @@ Common skip reasons:
 Checklist when nothing happens:
 
 1. `openclaw config validate` passes, and the config has no top-level `heartbeat` key.
-2. `openclaw cron list --all` shows an enabled `Heartbeat (<agent>)` job. If not, run `openclaw doctor --fix`.
+2. `openclaw cron list --all` shows an enabled `Heartbeat (<agent>)` job. If not, stop the Gateway and run `openclaw doctor --fix`.
 3. `cron.enabled` is not `false` and `OPENCLAW_SKIP_CRON` is not set.
 4. `every` is not `"0m"`, and the current time is inside `activeHours`.
 5. An owner route resolves (no `no-route` skips in `openclaw cron runs`).
diff --git a/scripts/README.md b/scripts/README.md
index 4826715..400f0bb 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -109,6 +109,101 @@ check whether the page's prose (batch sections, the latest release passed to
 `GITHUB_TOKEN` don't trigger other workflows; re-run the snippet check by hand
 or push a commit to the branch if needed.
 
+## Tutorial tests (`tutorial-tests/`)
+
+The snippet gates check that commands *exist*. The tutorial tests check that
+the beginner path *works*: each `*.test.sh` walks one page in order and runs its
+commands for real against the pinned OpenClaw, with a Gateway running on the
+GitHub Actions runner (`.github/workflows/tutorials.yml`: pushes and PRs that
+touch `docs/` or the tests, weekly, and on demand).
+
+| Test | Page |
+|---|---|
+| `quick-start.test.sh` | `getting-started/quick-start.md` |
+| `day-1-make-it-yours.test.sh` | `guides/first-7-days/day-1-make-it-yours.md` |
+| `day-3-automation.test.sh` | `guides/first-7-days/day-3-automation.md` |
+| `day-4-skills.test.sh` | `guides/first-7-days/day-4-skills.md` |
+| `day-7-production.test.sh` | `guides/first-7-days/day-7-production.md` |
+| `heartbeat.test.sh` | `guides/heartbeat.md` |
+
+Each test gets a fresh sandbox `HOME` (so `~/.openclaw/...` on the page is the
+sandbox), a non-interactive onboarding with no model credentials, and its own
+Gateway (`openclaw gateway run`, loopback, token auth), which is stopped at the
+end. Tests re-run themselves under `env -i`, so no API key or token from the
+calling shell reaches OpenClaw.
+
+**The page is the source.** A test names commands by their text on the page;
+`lib.sh` finds them in the page's shell blocks (or inline code) and runs the
+page's own text, so a test cannot drift from its page silently:
+
+```bash
+source "$(dirname "$0")/lib.sh"
+page docs/guides/heartbeat.md
+onboard                                  # CI stand-in for interactive onboarding
+gateway_start
+run -e 'Heartbeat \(main\)' "openclaw cron list --all"   # -e: output must match
+run "openclaw automations add \"every 30m\"..."         # "...": the one command with this prefix
+capture jobId "openclaw cron list --all --json" '(j.jobs).find(x=>x.displayName==="Heartbeat (main)").id'
+run "openclaw cron scratch <jobId>"      # <placeholders> come from capture/ph
+config_block 1                           # Nth openclaw.json block: config patch + validate
+config_block 4 --dry-run                 # reference block: validate the merge, don't apply
+file_block "~/.openclaw/workspace/SOUL.md"   # write a titled block to its path
+skip "openclaw tui" "interactive terminal UI"
+finish
+```
+
+Other helpers: `run_as "<page command>" "<CI variant>"` for steps that need a
+non-interactive form or the pinned version, `setup "<label>" "<command>"` for
+CI-only checks between steps, `skip_step` for non-command steps, `-x 0,1` for
+accepted exit codes, `-t <secs>` for a timeout. A step that needs a model key
+or a channel account is a `skip` with the reason, never faked. Page commands a
+test neither runs nor skips are listed as "unmapped" in the report.
+
+**Output:** a job summary table (page, steps run, skipped, failed, unmapped,
+with every step and reason under each page) and `tutorial-report.json`
+(artifact `tutorial-report`). For a passing page the summary prints the front
+matter to add.
+
+**Report only for now.** The job passes even when a page fails. To make it
+blocking, set the repository variable `TUTORIALS_STRICT=1`, or tick "strict"
+on a manual run (`run.mjs --strict` exits 1 on any failed page).
+
+### Running locally
+
+```bash
+TT_DRY=1 bash scripts/tutorial-tests/heartbeat.test.sh   # check the test/page mapping; runs nothing
+node scripts/tutorial-tests/run.mjs                      # full run: needs a Gateway, so CI only
+```
+
+`gateway_start` refuses to run outside GitHub Actions unless you set
+`TT_ALLOW_GATEWAY=1`. Do that only in a disposable VM or container: it starts a
+real Gateway on port 18789.
+
+### The "Verified in CI" banner
+
+Pages that pass get a front matter entry, added by hand after a green run
+(the workflow never commits):
+
+```yaml
+ci_verified:
+  version: 2026.10.4
+  date: 2026-10-18
+  steps: 24
+```
+
+`src/theme/DocItem/Content` (a wrapper around the theme's component) reads it
+and renders `src/components/CiVerified.tsx` above the page: "Verified in CI on
+OpenClaw 2026.10.4, 2026-10-18 — 24 steps run", linking to the workflow.
+`steps` is the "Steps run" count minus failures from the summary. When a page
+starts failing, fix the page or remove its `ci_verified` entry. Bump the
+entries when the pin moves.
+
+### Adding a page
+
+Copy a test, point `page` at the new file, and walk the page top to bottom.
+Run it with `TT_DRY=1` until it reports `0 page commands not mapped`, then
+push and read the job summary.
+
 ## Link check
 
 `.github/workflows/links.yml` runs lychee weekly over external links in
diff --git a/scripts/tutorial-tests/day-1-make-it-yours.test.sh b/scripts/tutorial-tests/day-1-make-it-yours.test.sh
new file mode 100755
index 0000000..30439f0
--- /dev/null
+++ b/scripts/tutorial-tests/day-1-make-it-yours.test.sh
@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Tutorial test: docs/guides/first-7-days/day-1-make-it-yours.md
+source "$(dirname "$0")/lib.sh"
+page docs/guides/first-7-days/day-1-make-it-yours.md
+
+onboard
+setup -e '^ok$' "onboarding seeded the workspace (BOOTSTRAP.md, AGENTS.md, SOUL.md, IDENTITY.md, USER.md)" \
+  "cd ~/.openclaw/workspace && ls BOOTSTRAP.md AGENTS.md SOUL.md IDENTITY.md USER.md > /dev/null && echo ok"
+gateway_start
+
+# Meet your bot
+skip "openclaw dashboard" "opens a browser"
+skip "openclaw tui" "interactive terminal UI"
+skip "openclaw agent --agent main --message \"Who are you?\"" "needs a model provider key"
+
+# The workspace files: deleting one and recreating it with setup
+setup "delete AGENTS.md and keep a custom SOUL.md" \
+  "rm ~/.openclaw/workspace/AGENTS.md && echo '# kept' > ~/.openclaw/workspace/SOUL.md"
+run "openclaw setup --baseline"
+setup -e '^ok$' "AGENTS.md is back and SOUL.md was not overwritten" \
+  "test -f ~/.openclaw/workspace/AGENTS.md && grep -qx '# kept' ~/.openclaw/workspace/SOUL.md && echo ok"
+
+# Write your SOUL.md
+file_block "~/.openclaw/workspace/SOUL.md"
+skip "openclaw agent --agent main --message \"Who are you?\"" "needs a model provider key"
+
+# Set your identity
+file_block "~/.openclaw/workspace/IDENTITY.md"
+run -e 'Name: Nova' "openclaw agents set-identity --agent main --from-identity"
+setup -e '"name": "Nova"' "identity stored in config" "openclaw config get agents.entries.main.identity"
+
+# Tell it about you
+file_block "~/.openclaw/workspace/USER.md"
+run "openclaw config set agents.defaults.userTimezone Europe/Berlin"
+setup -e 'Europe/Berlin' "timezone stored" "openclaw config get agents.defaults.userTimezone"
+setup "config still valid with the gateway running" "openclaw config validate && openclaw health"
+
+# Have a real conversation
+skip_step "The five example prompts" "need a model provider key"
+
+# Verify it remembers
+skip "openclaw agent --agent main --message \"What do you know about me?\"" "needs a model provider key"
+skip "cat ~/.openclaw/workspace/MEMORY.md" "MEMORY.md is written by the agent during a conversation; a fresh install has none"
+skip "ls ~/.openclaw/workspace/memory/" "daily notes are written by the agent during a conversation"
+run "openclaw memory search \"timezone\""
+run "openclaw memory index --force"
+
+finish
diff --git a/scripts/tutorial-tests/day-3-automation.test.sh b/scripts/tutorial-tests/day-3-automation.test.sh
new file mode 100755
index 0000000..89ca43a
--- /dev/null
+++ b/scripts/tutorial-tests/day-3-automation.test.sh
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Tutorial test: docs/guides/first-7-days/day-3-automation.md
+source "$(dirname "$0")/lib.sh"
+page docs/guides/first-7-days/day-3-automation.md
+
+onboard
+gateway_start
+
+# Before you start: where messages go
+run "openclaw config set commands.ownerAllowFrom '[\"telegram:123456789\"]'"
+
+# Your first automation (CLI form). Delivery targets a Telegram chat that does
+# not exist here; creating and listing the job must still work.
+run -e 'Morning brief' "openclaw cron add \"0 8 * * 1-5\"..."
+run -e 'Morning brief' "openclaw cron list"
+capture jobId "openclaw cron list --json" '(j.jobs||j).find(x=>x.name==="Morning brief").id'
+skip "openclaw cron run <jobId> --wait" "runs the job's prompt: needs a model provider key"
+
+# Practical automation ideas: each one is created for real
+run "openclaw cron add \"0 8 * * *\"..."
+run "openclaw cron add \"every 2h\" \"Check github.com/myorg/myrepo..."
+run "openclaw cron add \"0 * * * *\"..."
+run "openclaw cron add \"every 2h\" \"Check the current BTC..."
+run "openclaw cron add \"0 21 * * *\"..."
+run "openclaw cron add \"0 18 * * 0\"..."
+run -e 'Weekly summary' "openclaw cron list --all"
+
+# The heartbeat monitor
+config_block 1
+run "openclaw config validate"
+capture heartbeatJobId "openclaw cron list --all --json" '(j.jobs||j).find(x=>/Heartbeat/.test(x.displayName||x.name||"")).id'
+run "openclaw cron scratch <heartbeatJobId> --set \"If a background job..."
+setup -e 'background job' "scratch reads back" "openclaw cron scratch <heartbeatJobId>"
+
+# Model choice and cost
+run "openclaw gateway usage-cost --days 7"
+
+# Managing automations
+run -e 'Morning brief' "openclaw cron list"
+run -e 'Morning brief' "openclaw cron show <jobId>"
+run "openclaw cron disable <jobId>"
+run "openclaw cron enable <jobId>"
+skip "openclaw cron edit <jobId>" "no fields given on the page; see the cron edit reference"
+
+# Debugging
+run "openclaw cron status"
+run "openclaw cron runs <jobId>"
+skip "openclaw cron run <jobId> --wait" "runs the job's prompt: needs a model provider key"
+run "openclaw system heartbeat last"
+skip "openclaw system event --text \"Check whether my backup finished\" --mode now" "wakes a heartbeat turn: needs a model provider key"
+skip "openclaw logs --follow" "streams until interrupted"
+run "openclaw gateway status"
+run "openclaw cron rm <jobId>"
+setup -e '^gone$' "the job is gone" "openclaw cron list --all --json | grep -q '\"<jobId>\"' && echo still-there || echo gone"
+
+finish
diff --git a/scripts/tutorial-tests/day-4-skills.test.sh b/scripts/tutorial-tests/day-4-skills.test.sh
new file mode 100755
index 0000000..e295a8d
--- /dev/null
+++ b/scripts/tutorial-tests/day-4-skills.test.sh
@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Tutorial test: docs/guides/first-7-days/day-4-skills.md
+source "$(dirname "$0")/lib.sh"
+page docs/guides/first-7-days/day-4-skills.md
+
+onboard
+gateway_start
+
+# Start with the skills you already have
+run -e 'weather' "openclaw skills list"
+run "openclaw skills check"
+run -e 'github' "openclaw skills info github"
+skip "openclaw agent --agent main --message \"What's the weather in Berlin this afternoon?\"" "needs a model provider key"
+
+# Find more on ClawHub (network: clawhub.ai)
+run "openclaw skills search \"calendar\""
+run "openclaw skills search \"rss digest\" --limit 10"
+
+# Check before you install
+run -x 0,1 "openclaw skills verify @asleep123/caldav-calendar --card"
+
+# Install your first skill
+run "openclaw skills install @asleep123/caldav-calendar"
+setup -e '^ok$' "skill landed in the workspace" "test -f ~/.openclaw/workspace/skills/caldav-calendar/SKILL.md && echo ok"
+run -e 'caldav' "openclaw skills list"
+
+# Managing skills
+run "openclaw skills list"
+run "openclaw skills list --eligible"
+run "openclaw skills update --all"
+run "openclaw skills update @asleep123/caldav-calendar"
+config_block 1
+setup -e 'false' "weather is disabled in config" "openclaw config get skills.entries.weather.enabled"
+
+skip "npm i -g clawhub" "installs the third-party ClawHub CLI globally; out of scope for this test"
+skip "clawhub uninstall @asleep123/caldav-calendar" "needs the ClawHub CLI (above) and asks for confirmation"
+
+# Building vs installing: the minimal skill must load
+file_block "~/.openclaw/workspace/skills/my-custom-skill/SKILL.md"
+setup -e 'my-custom-skill' "custom skill is listed" "openclaw skills list"
+
+finish
diff --git a/scripts/tutorial-tests/day-7-production.test.sh b/scripts/tutorial-tests/day-7-production.test.sh
new file mode 100755
index 0000000..6d93a9b
--- /dev/null
+++ b/scripts/tutorial-tests/day-7-production.test.sh
@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Tutorial test: docs/guides/first-7-days/day-7-production.md
+source "$(dirname "$0")/lib.sh"
+page docs/guides/first-7-days/day-7-production.md
+
+onboard
+skip "openclaw update" "would replace the pinned version under test"
+skip "openclaw plugins update --all" "nothing installed from a registry on a fresh install; covered by the upgrade section skip"
+
+# A baseline config: the token comes from ~/.openclaw/.env, as the comment says
+setup "put the Gateway token in ~/.openclaw/.env" \
+  "printf 'OPENCLAW_GATEWAY_TOKEN=%s\n' '$TT_TOKEN' > ~/.openclaw/.env && chmod 600 ~/.openclaw/.env"
+config_block 1
+setup -e 'OPENCLAW_GATEWAY_TOKEN' "openclaw.json no longer holds the token itself" "grep -o 'OPENCLAW_GATEWAY_TOKEN' ~/.openclaw/openclaw.json && ! grep -qF '$TT_TOKEN' ~/.openclaw/openclaw.json"
+run "openclaw config validate"
+gateway_start
+skip "openclaw gateway restart" "needs an installed service; CI started the Gateway with the new config instead"
+run -e 'ask' "openclaw approvals get"
+run -x 0,1 "openclaw security audit --deep"
+run "openclaw security audit --fix"
+run "openclaw secrets audit --check"
+
+# Cost check
+run "openclaw gateway usage-cost"
+run "openclaw gateway usage-cost --days 7 --all-agents"
+
+# Monitoring
+run "openclaw status"
+run "openclaw status --deep"
+run "openclaw gateway status"
+run "openclaw doctor"
+skip "openclaw logs --follow" "streams until interrupted"
+run -e 'Daily self-check' "openclaw cron add \"30 7 * * *\"..."
+
+# Backups
+run "mkdir -p ~/Backups/openclaw"
+run -e 'erif' "openclaw backup create --output ~/Backups/openclaw --verify"
+capture archive "ls -t ~/Backups/openclaw/*.tar.gz | head -1 | xargs -n1 basename | sed 's/\\.tar\\.gz\$//' | node -e 'process.stdout.write(JSON.stringify([require(\"fs\").readFileSync(0,\"utf8\").trim()]))'" 'j[0]'
+setup "openclaw backup verify <archive> (inline on the page)" "openclaw backup verify ~/Backups/openclaw/<archive>.tar.gz"
+
+# Upgrades
+run "openclaw backup create --output ~/Backups/openclaw --verify"
+run "openclaw update status"
+skip "gh release view --repo openclaw/openclaw" "GitHub CLI call, not OpenClaw; needs a GH token"
+run "openclaw update --dry-run"
+skip "openclaw update" "would replace the pinned version under test"
+skip "openclaw plugins update --all" "would update bundled plugins away from the pin"
+run "openclaw skills update --all"
+run "openclaw doctor"
+run "openclaw status --deep"
+skip "openclaw gateway stop" "stops the installed service; CI stops its foreground Gateway at the end"
+run -e 'restore|Restore' "openclaw backup restore ~/Backups/openclaw/<archive>.tar.gz --target ~/openclaw-restore"
+setup -e '^ok$' "restore wrote a staging copy" "test -d ~/openclaw-restore && echo ok"
+
+finish
diff --git a/scripts/tutorial-tests/extract.mjs b/scripts/tutorial-tests/extract.mjs
new file mode 100644
index 0000000..a93a605
--- /dev/null
+++ b/scripts/tutorial-tests/extract.mjs
@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// extract.mjs: print the runnable parts of a docs page as JSON.
+//
+//   node scripts/tutorial-tests/extract.mjs docs/getting-started/quick-start.md
+//
+// Output: { page, title, commands: [{ line, text }], blocks: [{ lang, title, line, body }] }
+//   commands: every command line in bash/sh/shell/zsh/console blocks, with
+//             `\` continuations joined, multi-line quoted strings kept
+//             together (joined with "\n"), comment-only lines dropped and
+//             trailing `# comments` stripped. `line` is the 1-based page line.
+//   blocks:   every fenced block, with its `title="..."` and raw body.
+//
+// Used by lib.sh so tests run the page's own text instead of a copy.
+// No dependencies.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export function extractPage(file) {
+  const src = readFileSync(file, 'utf8');
+  const lines = src.split('\n');
+
+  const fm = /^---\n([\s\S]*?)\n---/.exec(src);
+  const title = fm ? ((/^title:\s*"?(.*?)"?\s*$/m.exec(fm[1]) || [])[1] || '') : '';
+
+  const SHELL = new Set(['bash', 'sh', 'shell', 'zsh', 'console']);
+  const blocks = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^(\s*)(`{3,}|~{3,})\s*([^\s`{]*)\s*(.*)$/.exec(lines[i]);
+    if (!m) continue;
+    const [, indent, fence, lang, meta] = m;
+    const close = new RegExp(`^\\s*${fence[0] === '`' ? '`' : '~'}{${fence.length},}\\s*$`);
+    const start = i;
+    const body = [];
+    for (i++; i < lines.length && !close.test(lines[i]); i++) {
+      body.push(lines[i].startsWith(indent) ? lines[i].slice(indent.length) : lines[i].trimStart());
+    }
+    const t = (/title=(?:"([^"]*)"|'([^']*)'|(\S+))/.exec(meta) || []).slice(1).find((x) => x !== undefined) || '';
+    blocks.push({ lang: lang.toLowerCase(), title: t, meta, line: start + 1, body: body.join('\n') });
+  }
+
+  // Quote state after scanning `s`, starting in state `q` ('' | "'" | '"').
+  function scanQuotes(s, q) {
+    for (let k = 0; k < s.length; k++) {
+      const c = s[k];
+      if (q === '"' && c === '\\') { k++; continue; }
+      if (!q && c === '\\') { k++; continue; }
+      if (q) { if (c === q) q = ''; continue; }
+      if (c === '"' || c === "'") q = c;
+    }
+    return q;
+  }
+
+  // Strip a trailing ` # comment` that is outside quotes.
+  function stripComment(s) {
+    let q = '';
+    for (let k = 0; k < s.length; k++) {
+      const c = s[k];
+      if (c === '\\' && q !== "'") { k++; continue; }
+      if (q) { if (c === q) q = ''; continue; }
+      if (c === '"' || c === "'") { q = c; continue; }
+      if (c === '#' && (k === 0 || /\s/.test(s[k - 1]))) return s.slice(0, k).trimEnd();
+    }
+    return s;
+  }
+
+  const commands = [];
+  for (const b of blocks) {
+    if (!SHELL.has(b.lang)) continue;
+    const body = b.body.split('\n');
+    for (let k = 0; k < body.length; k++) {
+      let text = body[k];
+      if (b.lang === 'console') { if (!/^\s*\$ /.test(text)) continue; text = text.replace(/^\s*\$ /, ''); }
+      if (!text.trim() || /^\s*#/.test(text)) continue;
+      const line = b.line + 1 + k;
+      let q = scanQuotes(text, '');
+      while (k + 1 < body.length && (q || /\\\s*$/.test(text))) {
+        if (q) { text += '\n' + body[++k]; }
+        else { text = text.replace(/\\\s*$/, '') + ' ' + body[++k].trim(); }
+        q = scanQuotes(text, '');
+      }
+      commands.push({ line, text: stripComment(text).trim() });
+    }
+  }
+
+  // Inline `openclaw ...` code spans outside fences (tables, prose). Tests may
+  // run these too, but they are not counted as "uncovered" when left out.
+  const inline = [];
+  const fenced = new Set();
+  for (const b of blocks) for (let n = b.line; n <= b.line + b.body.split('\n').length + 1; n++) fenced.add(n);
+  lines.forEach((l, idx) => {
+    if (fenced.has(idx + 1)) return;
+    for (const m of l.matchAll(/`(openclaw [^`]+)`/g)) inline.push({ line: idx + 1, text: m[1].trim() });
+  });
+
+  return { page: file, title, commands, inline, blocks };
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  if (!process.argv[2]) { console.error('usage: extract.mjs <page.md>'); process.exit(2); }
+  process.stdout.write(JSON.stringify(extractPage(process.argv[2]), null, 2) + '\n');
+}
diff --git a/scripts/tutorial-tests/heartbeat.test.sh b/scripts/tutorial-tests/heartbeat.test.sh
new file mode 100755
index 0000000..af2fa23
--- /dev/null
+++ b/scripts/tutorial-tests/heartbeat.test.sh
@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Tutorial test: docs/guides/heartbeat.md
+source "$(dirname "$0")/lib.sh"
+page docs/guides/heartbeat.md
+
+onboard
+gateway_start
+
+# How heartbeat works: one system-owned job per agent
+run -e 'Heartbeat \(main\)' "openclaw cron list --all"
+
+capture jobId "openclaw cron list --all --json" '(j.jobs||j).find(x=>/Heartbeat \(main\)/.test(x.displayName||x.name||"")).id'
+
+# Migrating from HEARTBEAT.md (page section after "Monitor scratch"). Run first:
+# Doctor leaves the file alone once the scratch has been set or unset.
+setup "write a legacy HEARTBEAT.md" "printf '# Heartbeat\n\n- Check whether the nightly backup finished.\n' > ~/.openclaw/workspace/HEARTBEAT.md"
+skip "openclaw gateway stop" "stops the installed service; CI stops its foreground Gateway instead"
+gateway_stop
+run "openclaw doctor --fix"
+skip "openclaw gateway start" "starts the installed service; CI starts its foreground Gateway instead"
+gateway_start
+setup -e '^ok$' "HEARTBEAT.md was removed from the workspace" "test ! -e ~/.openclaw/workspace/HEARTBEAT.md && echo ok"
+setup -e 'nightly backup' "its text is now the monitor scratch" "openclaw cron scratch <jobId>"
+setup -e '^ok$' "the original was archived under backups/heartbeat-migration/" "ls ~/.openclaw/backups/heartbeat-migration/ | grep -q . && echo ok"
+
+# Quick setup
+config_block 1
+run "openclaw config set commands.ownerAllowFrom '[\"telegram:123456789\"]'"
+skip "openclaw gateway restart" "needs an installed service; the running Gateway reloads config itself"
+run "openclaw cron list --all"
+capture jobId "openclaw cron list --all --json" '(j.jobs||j).find(x=>/Heartbeat \(main\)/.test(x.displayName||x.name||"")).id'
+run "openclaw cron scratch <jobId> --set \"- Anything urgent..."
+skip "openclaw system event --text \"Check for urgent follow-ups\" --mode now" "wakes a heartbeat turn: needs a model provider key"
+run "openclaw system heartbeat last"
+
+# Monitor scratch
+run -e 'Anything urgent' "openclaw cron scratch <jobId>"
+run "openclaw cron scratch <jobId> --set \"...\""
+setup "write checklist.md" "printf -- '- If a task is blocked, say what is missing.\n' > checklist.md"
+run "openclaw cron scratch <jobId> --file checklist.md"
+setup -e 'blocked' "scratch now holds the file" "openclaw cron scratch <jobId>"
+run "openclaw cron scratch <jobId> --unset"
+
+# Quiet replies and visibility
+config_block 2
+
+# Recipes: each table row is created for real (deliveries go nowhere here)
+run "openclaw automations add \"every 30m\"..."
+run "openclaw automations add \"every 1h\" \"List new issues..."
+run "openclaw automations add \"0 8 * * *\"..."
+run "openclaw automations add \"every 1h\" --name system-health..."
+run "openclaw automations add \"0 6 * * 1-5\"..."
+run -e 'code-health' "openclaw cron list --all"
+
+# Cost optimization
+config_block 3
+
+# Multi-agent heartbeat: validated, not applied (it adds an ops agent and workspace)
+config_block 4 --dry-run
+
+# Debugging
+skip "openclaw logs --follow" "streams until interrupted"
+run "openclaw system heartbeat last --json"
+run "openclaw cron list --all"
+run "openclaw cron runs <jobId> --limit 10"
+run "openclaw cron runs <jobId> --status skipped"
+run "openclaw config validate"
+
+# Complete configuration reference: validated, not applied
+config_block 5 --dry-run
+
+finish
diff --git a/scripts/tutorial-tests/lib.sh b/scripts/tutorial-tests/lib.sh
new file mode 100755
index 0000000..e7ed8ae
--- /dev/null
+++ b/scripts/tutorial-tests/lib.sh
@@ -0,0 +1,295 @@
+# lib.sh: shared helpers for tutorial tests. Source it from a *.test.sh file.
+#
+# A test names its page, then walks it in order:
+#
+#   page docs/getting-started/quick-start.md
+#   onboard                               # CI stand-in for the page's onboarding
+#   gateway_start                         # loopback + token, in the background
+#   run "openclaw gateway status"         # a command copied from the page
+#   run "openclaw cron add \"0 8 * * *\"..."   # "..." = the one page command with this prefix
+#   config_block 1                        # 1st openclaw.json block: patch + validate
+#   file_block "~/.openclaw/workspace/SOUL.md"
+#   skip "openclaw tui" "interactive terminal UI"
+#   finish
+#
+# `run` and `skip` look the command up on the page (whitespace-insensitive) and
+# fail if it is not there, so a test cannot drift from its page silently. The
+# command that runs is the page's text, with <placeholders> filled from
+# `ph name value`. Every process gets a throwaway HOME, so `~/.openclaw/...`
+# on the page means the sandbox.
+#
+# Env: OPENCLAW_BIN   pinned binary (default tools/openclaw/node_modules/.bin/openclaw)
+#      TT_OUT         where <slug>.json results go (default ./tutorial-report)
+#      TT_DRY=1       only check that every run/skip/block exists on the page; run nothing
+#      TT_ALLOW_GATEWAY=1  allow gateway_start outside GitHub Actions (off by default:
+#                     never start a Gateway on a workstation by accident)
+
+set -uo pipefail
+
+# Clean environment: re-run the test under `env -i` so nothing from the caller's
+# shell (API keys such as ANTHROPIC_API_KEY, tokens, OPENCLAW_* settings) can
+# reach OpenClaw. OpenClaw picks up provider keys from the environment, and
+# Doctor acts on them. Only the variables listed here pass through.
+if [[ -z "${TT_CLEAN_ENV:-}" ]]; then
+  exec env -i TT_CLEAN_ENV=1 PATH="$PATH" LANG=C.UTF-8 TMPDIR="${TMPDIR:-/tmp}" \
+    ${TT_OUT:+TT_OUT="$TT_OUT"} ${TT_DRY:+TT_DRY="$TT_DRY"} ${TT_STEP_TIMEOUT:+TT_STEP_TIMEOUT="$TT_STEP_TIMEOUT"} \
+    ${TT_ALLOW_GATEWAY:+TT_ALLOW_GATEWAY="$TT_ALLOW_GATEWAY"} ${OPENCLAW_BIN:+OPENCLAW_BIN="$OPENCLAW_BIN"} \
+    ${GITHUB_ACTIONS:+GITHUB_ACTIONS="$GITHUB_ACTIONS"} CI=1 \
+    bash "$0" "$@"
+fi
+
+TT_LIB_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+TT_ROOT=$(cd "$TT_LIB_DIR/../.." && pwd)
+TT_OUT=${TT_OUT:-$TT_ROOT/tutorial-report}
+TT_DRY=${TT_DRY:-0}
+TT_PIN=$(tr -d '[:space:]' < "$TT_ROOT/scripts/openclaw-version.txt")
+TT_STEP_TIMEOUT=${TT_STEP_TIMEOUT:-120}
+TT_GW_PID=
+TT_N=0
+
+if [[ -n "${OPENCLAW_BIN:-}" ]]; then TT_BIN=$OPENCLAW_BIN
+elif [[ -x "$TT_ROOT/tools/openclaw/node_modules/.bin/openclaw" ]]; then TT_BIN=$TT_ROOT/tools/openclaw/node_modules/.bin/openclaw
+else TT_BIN=$(command -v openclaw || true)
+fi
+
+_tt() { node "$TT_LIB_DIR/tt.mjs" "$@"; }
+_gh() { [[ "${GITHUB_ACTIONS:-}" == "true" ]]; }
+_group() { if _gh; then echo "::group::$*"; else echo "--- $*"; fi; }
+_endgroup() { if _gh; then echo "::endgroup::"; fi; }
+
+# _record kind status line cmd reason seconds exit
+_record() {
+  local json
+  json=$(node -e 'const [kind,status,line,cmd,reason,secs,exit]=process.argv.slice(1);
+    process.stdout.write(JSON.stringify({kind,status,line:line?Number(line):null,cmd,reason:reason||null,seconds:secs?Number(secs):null,exit:exit===""?null:Number(exit)}))' \
+    "$1" "$2" "$3" "$4" "$5" "${6:-}" "${7:-}")
+  _tt record "$TT_STEPS" "$json"
+  local mark=$2; [[ $2 == pass ]] && mark=ok
+  printf '[%s] %s%s%s\n' "$mark" "${3:+L$3 }" "${4%%$'\n'*}" "${5:+  ($5)}"
+}
+
+page() {
+  TT_PAGE=$1
+  TT_SLUG=$(sed 's#^docs/##; s#\.mdx\{0,1\}$##; s#/#__#g' <<< "$1")
+  mkdir -p "$TT_OUT"
+  TT_WORK=$(mktemp -d "${TMPDIR:-/tmp}/tt-$TT_SLUG.XXXXXX")
+  (cd "$TT_ROOT" && node "$TT_LIB_DIR/extract.mjs" "$TT_PAGE") > "$TT_WORK/page.json" || { echo "cannot read $TT_PAGE"; exit 2; }
+  TT_STEPS=$TT_WORK/steps.jsonl; : > "$TT_STEPS"
+  [[ -n "$TT_BIN" || "$TT_DRY" == 1 ]] || { echo "openclaw binary not found (set OPENCLAW_BIN)"; exit 2; }
+
+  # Sandbox: the page's ~ is this directory.
+  export HOME=$TT_WORK/home
+  export OPENCLAW_STATE_DIR=$HOME/.openclaw
+  export OPENCLAW_CONFIG_PATH=$HOME/.openclaw/openclaw.json
+  export OPENCLAW_DISABLE_UPDATE_CHECK=1 NO_COLOR=1 FORCE_COLOR=0 COLUMNS=200
+  # (environment already wiped by the env -i re-exec above)
+  mkdir -p "$HOME" "$TT_WORK/bin"
+  [[ -n "$TT_BIN" ]] && ln -sf "$TT_BIN" "$TT_WORK/bin/openclaw"
+  export PATH=$TT_WORK/bin:$PATH
+  cd "$HOME" || exit 2
+  trap _tt_cleanup EXIT
+  echo "== $TT_PAGE (OpenClaw $TT_PIN$([[ $TT_DRY == 1 ]] && echo ", dry run"))"
+}
+
+_tt_cleanup() { gateway_stop quiet; }
+
+# ph name value: fill <name> in page commands
+ph() { printf -v "PH_$1" '%s' "$2"; export "PH_$1"; }
+
+_fill() {
+  local text=$1 name var
+  while [[ $text =~ \<([A-Za-z][A-Za-z0-9_]*)\> ]]; do
+    name=${BASH_REMATCH[1]}; var=PH_$name
+    if [[ -z "${!var:-}" ]]; then echo "__MISSING__$name"; return 1; fi
+    text=${text//<$name>/${!var}}
+  done
+  printf '%s' "$text"
+}
+
+# _exec kind line label cmd codes expect timeout
+_exec() {
+  local kind=$1 line=$2 label=$3 cmd=$4 codes=$5 expect=$6 t=$7
+  TT_N=$((TT_N + 1))
+  if [[ "$TT_DRY" == 1 ]]; then _record "$kind" pass "$line" "$label" "dry run" 0 0; return 0; fi
+  local out=$TT_WORK/out.$TT_N start=$SECONDS rc status=pass reason=
+  _group "L${line:-?} $label"
+  printf '$ %s\n' "$cmd"
+  (cd "$HOME" && timeout "$t" bash -c "$cmd" < /dev/null) > "$out" 2>&1
+  rc=$?
+  head -c 20000 "$out"; echo
+  _endgroup
+  if [[ $rc == 124 ]]; then status=fail; reason="timed out after ${t}s"
+  elif [[ ",$codes," != *",$rc,"* ]]; then status=fail; reason="exit $rc (expected $codes): $(grep -v '^\s*$' "$out" | tail -n 3 | tr '\n' ' ' | cut -c1-300)"
+  elif [[ -n "$expect" ]] && ! grep -Eq -- "$expect" "$out"; then status=fail; reason="output did not match /$expect/"
+  fi
+  TT_LAST_OUT=$out
+  _record "$kind" "$status" "$line" "$label" "$reason" $((SECONDS - start)) "$rc"
+  [[ $status == pass ]]
+}
+
+_opts() {
+  TT_CODES=0; TT_EXPECT=; TT_T=$TT_STEP_TIMEOUT
+  while [[ $# -gt 1 ]]; do
+    case $1 in
+      -x) TT_CODES=$2; shift 2 ;;
+      -e) TT_EXPECT=$2; shift 2 ;;
+      -t) TT_T=$2; shift 2 ;;
+      *) break ;;
+    esac
+  done
+  TT_ARG=$1
+}
+
+# run [-x 0,1] [-e regex] [-t secs] "<command as on the page>"
+run() {
+  _opts "$@"
+  local hit line src text cmd
+  if ! hit=$(_tt resolve "$TT_WORK/page.json" "$TT_ARG" "$TT_STEPS" 2>&1); then
+    _record page fail "" "$TT_ARG" "$hit"; return 1
+  fi
+  { read -r line; read -r src; text=$(cat); } <<< "$hit"
+  if ! cmd=$(_fill "$text"); then
+    _record page fail "$line" "$text" "no value for placeholder <${cmd#__MISSING__}>"; return 1
+  fi
+  _exec page "$line" "$text" "$cmd" "$TT_CODES" "$TT_EXPECT" "$TT_T"
+}
+
+# run_as [-x ..] [-e ..] "<command as on the page>" "<what CI runs instead>"
+# For page steps that need a CI-safe variant (non-interactive flags, the pinned
+# version instead of @latest). Recorded against the page line, with both texts.
+run_as() {
+  _opts "$@"; local q=$TT_ARG; shift $(($# - 1)); local cmd=$1
+  local hit line src text
+  if ! hit=$(_tt resolve "$TT_WORK/page.json" "$q" "$TT_STEPS" 2>&1); then
+    _record page fail "" "$q" "$hit"; return 1
+  fi
+  { read -r line; read -r src; text=$(cat); } <<< "$hit"
+  _exec page "$line" "$text  [CI: $cmd]" "$cmd" "$TT_CODES" "$TT_EXPECT" "$TT_T"
+}
+
+# skip "<command as on the page>" "<why it cannot run in CI>"
+skip() {
+  local hit line src text
+  if ! hit=$(_tt resolve "$TT_WORK/page.json" "$1" "$TT_STEPS" 2>&1); then
+    _record page fail "" "$1" "skip target $hit"; return 1
+  fi
+  { read -r line; read -r src; text=$(cat); } <<< "$hit"
+  _record page skip "$line" "$text" "$2"
+}
+
+# skip_step "<page step that is not a command>" "<why>"
+skip_step() { _record page skip "" "$1" "$2"; }
+
+# setup [-x codes] [-e regex] "<label>" "<command>": CI scaffolding, not from
+# the page. <placeholders> are filled as in run.
+setup() {
+  _opts "$@"; local label=$TT_ARG; shift $(($# - 1)); local cmd=$1
+  [[ "$label" == "$cmd" ]] && { echo "setup needs a label and a command"; return 1; }
+  local filled
+  if ! filled=$(_fill "$cmd"); then
+    _record setup fail "" "$label" "no value for placeholder <${filled#__MISSING__}>"; return 1
+  fi
+  _exec setup "" "$label" "$filled" "$TT_CODES" "$TT_EXPECT" "$TT_T"
+}
+
+# config_block N [--dry-run]: merge the page's Nth openclaw.json block into the
+# sandbox config with `openclaw config patch` (as the page says: merge, don't
+# replace), then `openclaw config validate`. --dry-run validates the merge
+# without writing it (for reference blocks that are not meant to be applied).
+config_block() {
+  local n=$1 mode=${2:-} hit line title body f
+  if ! hit=$(_tt block "$TT_WORK/page.json" "config:$n" 2>&1); then
+    _record page fail "" "config block #$n" "$hit"; return 1
+  fi
+  { read -r line; read -r title; body=$(cat); } <<< "$hit"
+  f=$TT_WORK/block-L$line.json5
+  printf '%s\n' "$body" > "$f"
+  _exec page "$line" "config block #$n ($title)${mode:+ $mode}" \
+    "openclaw config patch --file '$f' $mode && openclaw config validate" 0 "" "$TT_STEP_TIMEOUT"
+}
+
+# file_block "<fence title>": write that block to its path (~ = sandbox HOME)
+file_block() {
+  local hit line title body dest
+  if ! hit=$(_tt block "$TT_WORK/page.json" "title:$1" 2>&1); then
+    _record page fail "" "write $1" "$hit"; return 1
+  fi
+  { read -r line; read -r title; body=$(cat); } <<< "$hit"
+  dest=${title/#\~/$HOME}
+  if [[ "$TT_DRY" == 1 ]]; then _record page pass "$line" "write $title" "dry run"; return 0; fi
+  mkdir -p "$(dirname "$dest")" && printf '%s\n' "$body" > "$dest"
+  _record page pass "$line" "write $title" "" 0 0
+}
+
+# onboard: non-interactive stand-in for the page's interactive onboarding.
+# No model credentials (--auth-choice skip), no service, loopback + token.
+onboard() {
+  TT_TOKEN=$(node -e 'process.stdout.write(require("crypto").randomBytes(24).toString("hex"))')
+  setup -e '"ok": true' "onboard (non-interactive, no model auth)" \
+    "openclaw onboard --non-interactive --accept-risk --mode local --auth-choice skip \
+      --gateway-bind loopback --gateway-auth token --gateway-token $TT_TOKEN \
+      --skip-daemon --skip-health --skip-channels --skip-search --skip-skills --skip-ui --json"
+}
+
+# gateway_start: `openclaw gateway run` in the background (the CI stand-in for
+# the installed service), then wait for `openclaw health`.
+gateway_start() {
+  [[ "$TT_DRY" == 1 ]] && { _record setup pass "" "gateway start" "dry run"; return 0; }
+  if ! _gh && [[ "${TT_ALLOW_GATEWAY:-}" != 1 ]]; then
+    _record setup fail "" "gateway start" "refusing to start a Gateway outside GitHub Actions (set TT_ALLOW_GATEWAY=1)"; return 1
+  fi
+  local start=$SECONDS ok=
+  (cd "$HOME" && exec openclaw gateway run --bind loopback < /dev/null > "$TT_WORK/gateway.log" 2>&1) &
+  TT_GW_PID=$!
+  for _ in $(seq 1 90); do
+    if openclaw health --json > "$TT_WORK/health.json" 2>&1; then ok=1; break; fi
+    kill -0 "$TT_GW_PID" 2> /dev/null || break
+    sleep 1
+  done
+  if [[ -n $ok ]]; then
+    _record setup pass "" "gateway start (openclaw gateway run, loopback, token auth)" "" $((SECONDS - start)) 0
+  else
+    _group "gateway.log"; tail -n 80 "$TT_WORK/gateway.log"; cat "$TT_WORK/health.json"; _endgroup
+    _record setup fail "" "gateway start (openclaw gateway run, loopback, token auth)" "no healthy Gateway after $((SECONDS - start))s" $((SECONDS - start)) 1
+    return 1
+  fi
+}
+
+gateway_stop() {
+  [[ -z "$TT_GW_PID" ]] && return 0
+  local pid=$TT_GW_PID; TT_GW_PID=
+  kill "$pid" 2> /dev/null
+  for _ in $(seq 1 20); do kill -0 "$pid" 2> /dev/null || break; sleep 1; done
+  kill -9 "$pid" 2> /dev/null
+  [[ "${1:-}" == quiet ]] && return 0
+  _group "gateway.log (tail)"; tail -n 40 "$TT_WORK/gateway.log"; _endgroup
+  _record setup pass "" "gateway stop" "" 0 0
+}
+
+# json_get '<js expr on j>': read JSON (after any leading noise) from stdin
+json_get() {
+  node -e 'const s=require("fs").readFileSync(0,"utf8");const i=s.search(/[\[{]/);const j=JSON.parse(s.slice(i));const v=eval(process.argv[1]);if(v===undefined||v===null)process.exit(1);process.stdout.write(String(v))' "$1"
+}
+
+# capture name "<command>" '<js expression on j>': run a command that prints
+# JSON, evaluate the expression and store it as <name> (see ph).
+capture() {
+  local name=$1 cmd=$2 expr=$3 v out=$TT_WORK/capture.$1
+  if [[ "$TT_DRY" == 1 ]]; then ph "$name" "DRY-$name"; return 0; fi
+  bash -c "$cmd" < /dev/null > "$out" 2>&1
+  if v=$(json_get "$expr" < "$out" 2> /dev/null) && [[ -n "$v" ]]; then
+    ph "$name" "$v"; _record setup pass "" "capture <$name> from: $cmd" "" 0 0
+  else
+    _group "capture <$name> output"; head -c 4000 "$out"; echo; _endgroup
+    _record setup fail "" "capture <$name> from: $cmd" "expression $expr found nothing"; return 1
+  fi
+}
+
+finish() {
+  gateway_stop
+  cd "$TT_ROOT" || true
+  _tt finish "$TT_WORK/page.json" "$TT_STEPS" "$TT_OUT/$TT_SLUG.json" "$TT_PIN"
+  local ok
+  ok=$(node -e 'process.stdout.write(String(require(process.argv[1]).ok))' "$TT_OUT/$TT_SLUG.json")
+  [[ "$ok" == true ]] && exit 0 || exit 1
+}
diff --git a/scripts/tutorial-tests/quick-start.test.sh b/scripts/tutorial-tests/quick-start.test.sh
new file mode 100755
index 0000000..55c4257
--- /dev/null
+++ b/scripts/tutorial-tests/quick-start.test.sh
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Tutorial test: docs/getting-started/quick-start.md
+source "$(dirname "$0")/lib.sh"
+page docs/getting-started/quick-start.md
+
+# Step 1: Install
+skip "curl -fsSL https://openclaw.ai/install.sh | bash" "installer script installs @latest and starts interactive onboarding; CI tests the npm path with the pin"
+run_as -t 300 "npm install -g openclaw@latest --allow-scripts=openclaw" \
+  "npm install -g openclaw@$TT_PIN --allow-scripts=openclaw --no-audit --no-fund && \"\$(npm prefix -g)/bin/openclaw\" --version | grep -F $TT_PIN"
+
+# Step 2: Onboard (interactive on the page; CI uses the non-interactive form, no service, no model auth)
+run_as "openclaw onboard --install-daemon" \
+  "openclaw onboard --non-interactive --accept-risk --mode local --auth-choice skip --gateway-bind loopback --gateway-auth token --skip-daemon --skip-health --skip-channels --skip-search --skip-skills --skip-ui --json"
+setup -e '^ok$' "workspace and config exist where the page says" \
+  "test -f ~/.openclaw/openclaw.json && test -f ~/.openclaw/workspace/SOUL.md && test -f ~/.openclaw/workspace/AGENTS.md && openclaw config get gateway.auth.mode | grep -q token && echo ok"
+gateway_start
+
+# Step 3: Check the Gateway
+run -e '18789' "openclaw gateway status"
+config_block 1 --dry-run          # port 18790 example: validated, not applied
+skip "openclaw gateway restart" "needs an installed service (launchd/systemd); CI runs the Gateway in the foreground"
+
+# Step 4: Chat
+skip "openclaw dashboard" "opens a browser"
+run -e 'http://127\.0\.0\.1:18789' "openclaw dashboard --no-open"
+skip "openclaw tui" "interactive terminal UI"
+skip "openclaw agent --agent main --message \"What files are in my home directory?\"" "needs a model provider key"
+
+# Step 5: Execution approval
+run "openclaw config set tools.exec.mode ask"
+run "openclaw approvals get"
+
+# Step 6: Personalize
+skip "vim ~/.openclaw/workspace/SOUL.md" "interactive editor; CI writes the page's SOUL.md block instead"
+file_block "~/.openclaw/workspace/SOUL.md"
+
+# Step 7: Channels
+skip "openclaw channels add telegram" "needs a Telegram bot token"
+skip "openclaw channels add whatsapp" "needs a phone to scan the QR code"
+skip "openclaw channels add discord" "needs a Discord bot token"
+skip "openclaw pairing list telegram" "needs a configured channel"
+skip "openclaw pairing approve telegram <code>" "needs a pairing code from a real DM"
+
+# Step 8: Heartbeat and scheduled tasks
+config_block 2
+run -e 'Morning brief' "openclaw cron add --name \"Morning brief\" --cron \"0 9 * * *\"..."
+run -e 'Heartbeat \(main\)' "openclaw cron list --all"
+capture jobId "openclaw cron list --all --json" '(j.jobs||j).find(x=>/Heartbeat/.test(x.displayName||x.name||"")).id'
+run "openclaw cron scratch <jobId> --set \"...\""
+
+# Verify your setup
+run -e "$TT_PIN" "openclaw --version"
+run "openclaw doctor"
+run -e '18789' "openclaw gateway status"
+run "openclaw status"
+skip "openclaw agent --agent main --message \"Hello! Tell me what you can do.\"" "needs a model provider key"
+run "openclaw channels list"
+run "openclaw system heartbeat last"
+
+# Common gotchas
+run "openclaw config validate"
+run "openclaw models status"
+
+finish
diff --git a/scripts/tutorial-tests/run.mjs b/scripts/tutorial-tests/run.mjs
new file mode 100644
index 0000000..a5aab3c
--- /dev/null
+++ b/scripts/tutorial-tests/run.mjs
@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// run.mjs: run the tutorial tests and write the report.
+//
+//   node scripts/tutorial-tests/run.mjs [--strict] [--json <file>] [tests...]
+//
+// Runs every scripts/tutorial-tests/*.test.sh (or the ones given), one after
+// another, each in its own sandbox HOME with its own Gateway. Writes
+// tutorial-report.json and a Markdown summary (to $GITHUB_STEP_SUMMARY when
+// set, else stdout). Exits 0 unless --strict or TUTORIALS_STRICT=1 and a page
+// failed.
+
+import { readdirSync, readFileSync, writeFileSync, appendFileSync, mkdirSync, rmSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, '../..');
+const argv = process.argv.slice(2);
+let strict = process.env.TUTORIALS_STRICT === '1';
+let jsonOut = path.join(ROOT, 'tutorial-report.json');
+const tests = [];
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === '--strict') strict = true;
+  else if (argv[i] === '--json') jsonOut = path.resolve(argv[++i]);
+  else tests.push(path.resolve(argv[i]));
+}
+if (!tests.length) for (const f of readdirSync(HERE).sort()) if (f.endsWith('.test.sh')) tests.push(path.join(HERE, f));
+
+const pin = readFileSync(path.join(ROOT, 'scripts/openclaw-version.txt'), 'utf8').trim();
+const outDir = path.join(ROOT, 'tutorial-report');
+rmSync(outDir, { recursive: true, force: true });
+mkdirSync(outDir, { recursive: true });
+
+const pages = [];
+for (const t of tests) {
+  const before = new Set(readdirSync(outDir));
+  console.log(`\n### ${path.relative(ROOT, t)}`);
+  const r = spawnSync('bash', [t], { cwd: ROOT, stdio: 'inherit', env: { ...process.env, TT_OUT: outDir }, timeout: 20 * 60 * 1000 });
+  const fresh = readdirSync(outDir).filter((f) => !before.has(f) && f.endsWith('.json'));
+  if (fresh.length) {
+    for (const f of fresh) pages.push({ test: path.relative(ROOT, t), ...JSON.parse(readFileSync(path.join(outDir, f), 'utf8')) });
+  } else {
+    pages.push({ test: path.relative(ROOT, t), page: path.relative(ROOT, t), title: '', ok: false, passed: 0, failed: 1, skipped: 0,
+      steps: [{ kind: 'setup', status: 'fail', cmd: 'test script', reason: `exited ${r.status ?? r.signal} without a result` }], uncovered: [] });
+  }
+}
+
+const runUrl = process.env.GITHUB_RUN_ID
+  ? `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`
+  : null;
+const date = new Date().toISOString().slice(0, 10);
+const report = { openclaw: pin, date, run: runUrl, ok: pages.every((p) => p.ok), pages };
+writeFileSync(jsonOut, JSON.stringify(report, null, 2) + '\n');
+
+// ---------------------------------------------------------------- summary
+const esc = (s) => String(s ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ');
+const short = (s, n = 110) => { s = esc(s); return s.length > n ? s.slice(0, n - 1) + '…' : s; };
+let md = `## Tutorial tests (OpenClaw ${pin})\n\n`;
+md += `Commands from each page, run in order against a real Gateway on this runner. Report only. See scripts/README.md.\n\n`;
+md += `| Page | Result | Steps run | Skipped | Failed | Unmapped |\n|---|---|---|---|---|---|\n`;
+for (const p of pages) {
+  md += `| \`${esc(p.page)}\` | ${p.ok ? 'pass' : '**FAIL**'} | ${p.passed + p.failed} | ${p.skipped} | ${p.failed} | ${p.uncovered.length} |\n`;
+}
+for (const p of pages) {
+  md += `\n<details><summary><b>${esc(p.page)}</b>: ${p.ok ? 'pass' : 'FAIL'}, ${p.passed} passed, ${p.failed} failed, ${p.skipped} skipped</summary>\n\n`;
+  md += `| | Line | Step | Note |\n|---|---|---|---|\n`;
+  for (const s of p.steps) {
+    md += `| ${s.status} | ${s.line ? 'L' + s.line : s.kind} | \`${short(s.cmd)}\` | ${short(s.reason, 200)} |\n`;
+  }
+  if (p.uncovered.length) {
+    md += `\nPage commands this test neither runs nor skips:\n\n`;
+    for (const u of p.uncovered) md += `- L${u.line} \`${short(u.text)}\`\n`;
+  }
+  if (p.ok) {
+    md += `\nFront matter for this page:\n\n\`\`\`yaml\nci_verified:\n  version: ${pin}\n  date: ${date}\n  steps: ${p.passed}\n\`\`\`\n`;
+  }
+  md += `\n</details>\n`;
+}
+if (process.env.GITHUB_STEP_SUMMARY) appendFileSync(process.env.GITHUB_STEP_SUMMARY, md);
+else console.log('\n' + md);
+
+const failed = pages.filter((p) => !p.ok);
+console.log(`\n${pages.length - failed.length}/${pages.length} pages passed. Report: ${path.relative(ROOT, jsonOut)}`);
+process.exit(strict && failed.length ? 1 : 0);
diff --git a/scripts/tutorial-tests/tt.mjs b/scripts/tutorial-tests/tt.mjs
new file mode 100644
index 0000000..2c89558
--- /dev/null
+++ b/scripts/tutorial-tests/tt.mjs
@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// tt.mjs: helpers for lib.sh (tutorial tests). Not meant to be run by hand.
+//
+//   tt.mjs resolve <page.json> <query> [steps.jsonl]    -> line, source, text of the page command
+//   tt.mjs block   <page.json> <selector>   -> line, title, body of a fenced block
+//   tt.mjs record  <steps.jsonl> <json>     -> append one step record
+//   tt.mjs finish  <page.json> <steps.jsonl> <out.json> <version>
+//
+// Query: the command text as it appears on the page (whitespace-insensitive).
+// A query ending in "..." matches the one page command that starts with it.
+// Selector: "config:N" (Nth openclaw.json block on the page, 1-based) or
+// "title:<exact fence title>".
+
+import { readFileSync, appendFileSync, writeFileSync } from 'node:fs';
+
+const [, , sub, ...args] = process.argv;
+const norm = (s) => s.replace(/\s+/g, ' ').trim();
+const load = (f) => JSON.parse(readFileSync(f, 'utf8'));
+const die = (msg) => { process.stderr.write(msg + '\n'); process.exit(1); };
+
+if (sub === 'resolve') {
+  const [pj, query, stepsFile] = args;
+  const page = load(pj);
+  let used = new Set();
+  try { used = new Set(readFileSync(stepsFile, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l).line)); } catch {}
+  const all = [
+    ...page.commands.map((c) => ({ ...c, source: 'fenced' })),
+    ...page.inline.map((c) => ({ ...c, source: 'inline' })),
+  ];
+  const q = norm(query);
+  let hits;
+  if (/(\.\.\.|…)$/.test(q)) {
+    const pre = q.replace(/(\.\.\.|…)$/, '').trimEnd();
+    hits = all.filter((c) => norm(c.text).startsWith(pre));
+    const uniq = new Set(hits.map((h) => norm(h.text)));
+    if (uniq.size > 1) die(`ambiguous prefix, matches ${uniq.size} commands on ${page.page}: ${[...hits].map((h) => 'L' + h.line).join(', ')}`);
+  } else {
+    hits = all.filter((c) => norm(c.text) === q);
+  }
+  if (!hits.length) die(`not on page ${page.page}: ${query}`);
+  // Repeated commands: take the first occurrence not already covered.
+  hits = [...hits.filter((h) => !used.has(h.line)), ...hits];
+  // line, source, then the command text (may span lines)
+  process.stdout.write(`${hits[0].line}\n${hits[0].source}\n${hits[0].text}\n`);
+} else if (sub === 'block') {
+  const [pj, sel] = args;
+  const page = load(pj);
+  let b;
+  if (sel.startsWith('config:')) {
+    const n = Number(sel.slice(7));
+    const cfg = page.blocks.filter((x) => ['json', 'json5', 'jsonc'].includes(x.lang) && /openclaw\.json/.test(x.title));
+    b = cfg[n - 1];
+    if (!b) die(`no openclaw.json block #${n} on ${page.page} (found ${cfg.length})`);
+  } else if (sel.startsWith('title:')) {
+    const t = sel.slice(6);
+    const hits = page.blocks.filter((x) => x.title === t);
+    if (hits.length !== 1) die(`expected one block titled "${t}" on ${page.page}, found ${hits.length}`);
+    b = hits[0];
+  } else die(`bad selector ${sel}`);
+  // line, title, then the body
+  process.stdout.write(`${b.line}\n${b.title}\n${b.body}\n`);
+} else if (sub === 'record') {
+  const [file, json] = args;
+  appendFileSync(file, JSON.stringify(JSON.parse(json)) + '\n');
+} else if (sub === 'finish') {
+  const [pj, stepsFile, out, version] = args;
+  const page = load(pj);
+  let steps = [];
+  try { steps = readFileSync(stepsFile, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l)); } catch {}
+  const covered = new Set(steps.filter((s) => s.line).map((s) => s.line));
+  const uncovered = page.commands.filter((c) => !covered.has(c.line)).map((c) => ({ line: c.line, text: c.text }));
+  const count = (st) => steps.filter((s) => s.status === st).length;
+  const res = {
+    page: page.page,
+    title: page.title,
+    openclaw: version,
+    date: new Date().toISOString().slice(0, 10),
+    passed: count('pass'),
+    failed: count('fail'),
+    skipped: count('skip'),
+    ok: count('fail') === 0 && steps.length > 0,
+    steps,
+    uncovered,
+  };
+  writeFileSync(out, JSON.stringify(res, null, 2) + '\n');
+  process.stdout.write(`${res.ok ? 'PASS' : 'FAIL'} ${page.page}: ${res.passed} passed, ${res.failed} failed, ${res.skipped} skipped, ${uncovered.length} page commands not mapped\n`);
+  for (const u of uncovered) process.stdout.write(`  unmapped L${u.line}: ${u.text.split('\n')[0]}\n`);
+} else {
+  die('usage: tt.mjs resolve|block|record|finish ...');
+}
diff --git a/src/components/CiVerified.module.css b/src/components/CiVerified.module.css
new file mode 100644
index 0000000..b0a860b
--- /dev/null
+++ b/src/components/CiVerified.module.css
@@ -0,0 +1,25 @@
+.banner {
+  display: inline-block;
+  margin-bottom: 1rem;
+  padding: 0.2rem 0.6rem;
+  border: 1px solid var(--ifm-color-success-dark);
+  border-radius: 999px;
+  font-size: 0.8rem;
+  color: var(--ifm-color-success-darkest);
+  background: var(--ifm-color-success-contrast-background);
+}
+
+[data-theme='dark'] .banner {
+  color: var(--ifm-color-success-lightest);
+  border-color: var(--ifm-color-success);
+}
+
+.banner a {
+  color: inherit;
+  font-weight: 600;
+  text-decoration: underline;
+}
+
+.mark {
+  font-weight: 700;
+}
diff --git a/src/components/CiVerified.tsx b/src/components/CiVerified.tsx
new file mode 100644
index 0000000..230a18b
--- /dev/null
+++ b/src/components/CiVerified.tsx
@@ -0,0 +1,38 @@
+import React from 'react';
+import styles from './CiVerified.module.css';
+
+// Front matter written by a human after a green run of the "Tutorial tests"
+// workflow (.github/workflows/tutorials.yml). See scripts/README.md.
+export type CiVerifiedData = {
+  version: string;
+  date: string;
+  steps?: number;
+};
+
+const WORKFLOW_URL =
+  'https://github.com/clawdocs/clawdocs.github.io/actions/workflows/tutorials.yml';
+
+function isCiVerified(v: unknown): v is CiVerifiedData {
+  if (!v || typeof v !== 'object') return false;
+  const o = v as Record<string, unknown>;
+  return (typeof o.version === 'string' || typeof o.version === 'number') &&
+    (typeof o.date === 'string' || o.date instanceof Date);
+}
+
+export default function CiVerified({data}: {data: unknown}): React.ReactElement | null {
+  if (!isCiVerified(data)) return null;
+  // YAML may parse an unquoted date as a Date object.
+  const raw = data.date as unknown;
+  const date = raw instanceof Date ? raw.toISOString().slice(0, 10) : String(raw);
+  const steps = typeof data.steps === 'number' ? data.steps : undefined;
+  return (
+    <div className={styles.banner}>
+      <span className={styles.mark} aria-hidden="true">✓</span>{' '}
+      <a href={WORKFLOW_URL} title="Commands on this page are run against a real Gateway in GitHub Actions">
+        Verified in CI
+      </a>{' '}
+      on OpenClaw {String(data.version)}, {date}
+      {steps !== undefined && <> — {steps} steps run</>}
+    </div>
+  );
+}
diff --git a/src/theme/DocItem/Content/index.tsx b/src/theme/DocItem/Content/index.tsx
new file mode 100644
index 0000000..a7efc28
--- /dev/null
+++ b/src/theme/DocItem/Content/index.tsx
@@ -0,0 +1,21 @@
+import React from 'react';
+import Content from '@theme-original/DocItem/Content';
+import type ContentType from '@theme/DocItem/Content';
+import type {WrapperProps} from '@docusaurus/types';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
+import CiVerified from '@site/src/components/CiVerified';
+
+type Props = WrapperProps<typeof ContentType>;
+
+// Shows the "Verified in CI" pill above pages whose front matter has
+// `ci_verified: { version, date, steps }`.
+export default function ContentWrapper(props: Props): React.ReactElement {
+  const {frontMatter} = useDoc();
+  const data = (frontMatter as Record<string, unknown>).ci_verified;
+  return (
+    <>
+      {data ? <CiVerified data={data} /> : null}
+      <Content {...props} />
+    </>
+  );
+}