docs(cloud-agents): document customizing workspace snapshots (#105)

hongyi-chen · oz-agent · web-flow · commit e91ee491e751 · 2026-05-19T17:00:45.000-07:00
* docs(cloud-agents): document customizing workspace snapshots Add a new page under cloud-agents/handoff documenting how to customize the end-of-run snapshot pipeline that backs local-to-cloud and cloud-to-cloud handoff. Targets self-hosted and CLI users who run outside the bundled warp-agent-docker image and need to provide their own declarations script (or a static declarations file) for handoff to work. The page covers: - When to customize (custom Docker image, Direct backend, unmanaged oz agent run in CI) - The two env vars Warp respects (OZ_SNAPSHOT_DECLARATIONS_SCRIPT, OZ_SNAPSHOT_DECLARATIONS_FILE) - The JSONL declarations file format (v1 schema, repo vs file kinds) - A minimal bash script template + the static declarations file pattern (no script needed) - --no-snapshot for disabling snapshots per run Wire the new page into the Handoff sidebar group and add single-sentence cross-links from local-to-cloud, cloud-to-cloud, self-hosting/unmanaged, and self-hosting/index so readers arriving from any of those entry points can find it. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cloud-agents): address self-audit findings on snapshots page - Drop the "Continue locally" mention from the intro. Cloud-to-local handoff doesn't apply workspace patches to a local checkout (per handoff/index.mdx), so the claim was misleading. - Replace "empty workspace" with "without the prior session's uncommitted changes". The cloud workspace isn't empty without a snapshot — the environment still clones repos at HEAD; what's missing is the uncommitted delta. - Restructure "How snapshotting works" to lead with the two modes (script-driven vs static) before walking through each one. Removes the implicit assumption that the script always runs. - Drop the setup_command half of the Direct backend tip. setup_command injects env vars via OZ_ENVIRONMENT_FILE, which is more indirection than this page should explain — just point at `environment` config. - Remove the local-to-cloud cross-link to the snapshots page. The local-to-cloud path uses upload_snapshot_for_handoff() with Vec arguments, not OZ_SNAPSHOT_DECLARATIONS_SCRIPT, so the cross-link could mislead readers. cloud-to-cloud, self-hosting/unmanaged, and self-hosting/index still link to the page. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cloud-agents): address Oz review on snapshots page Three suggestions from the Oz review on PR #105, all accepted: 1. Add a security caution after the declarations format section. Explicit warning that declared `file` paths are uploaded verbatim and `repo` paths upload the git diff (tracked + untracked, non-gitignored). Tells users to keep secrets, credentials, and API tokens out of declared `file` entries before copying the pattern. 2. Escape JSON metacharacters in repo paths in the bash template. The previous example printf'd `repo_root` straight into JSON; a path containing `"` or `\` would produce malformed JSON that Warp skips with a WARN. Added a sed pass that escapes `\` first, then `"`, matching the bot's suggested patch. 3. Drop the "including the --no-snapshot flag" claim from the Oz CLI Related pages bullet. /reference/cli/ doesn't document the flag today, so the claim sent readers somewhere that couldn't answer the flag-specific question. The flag is already covered on this page in the Disable snapshots section. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cloud-agents): align 'untracked files' precision with caution The "Prefer `repo` over `file`" rule said `repo` entries pick up "tracked changes plus untracked files" while the security caution right below said "tracked changes plus untracked, non-gitignored files". The caution is the accurate one (matches `git ls-files --others --exclude-standard` in `app/src/ai/agent_sdk/driver/snapshot.rs::build_repo_patch`), so tighten the rule to match. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cloud-agents): scrub private warp-agent-docker links from snapshots docs The two GitHub URLs the new snapshots page used were both pointing at warpdotdev/warp-agent-docker, which is a private repo — anonymous visitors get HTTP 404. Replaced both with link-free user-facing prose and reworded all text mentions of the internal repo name. Specifically: * snapshots.mdx frontmatter description: "bundled warp-agent-docker image" → "bundled cloud agent image". * snapshots.mdx intro paragraph: drop the link to the private repo root; refer to "Warp's bundled cloud agent image" instead. * snapshots.mdx "When to customize" intro: replace "bundled warp-agent-docker image" with "bundled cloud agent image". * snapshots.mdx env-var reference: same swap for OZ_SNAPSHOT_DECLARATIONS_SCRIPT description. * snapshots.mdx "Write a custom declarations script": drop the link to the private snapshot-declarations.sh file; the sentence now just introduces the minimal pattern. * snapshots.mdx: add a :::note callout under the script example describing what the bundled image's richer implementation does beyond the minimal pattern (OZ_SNAPSHOT_SCAN_ROOTS override, jq for JSON encoding, dedup against existing repo declarations) so power users know what's available without us pointing at private artifacts. * unmanaged.mdx Tracking and observability cross-link: drop the "warp-agent-docker" qualifier. Verified with grep: no more "warp-agent-docker" references anywhere in src/content/docs/. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cloud-agents): add full bundled snapshot script alongside minimal example Per Harry's Slack OK on showing the full script ("from a security POV, definitely no issues with showing the entire script... any user who cared could easily find the script by just running a cloud agent and cat-ing it out"), include the canonical declarations script Warp invokes inside the bundled cloud agent image in addition to (not replacing) the minimal sed-based example. Changes to snapshots.mdx: * Keep the minimal sed-based example unchanged. It's a clean starting point for users adapting a custom script. * Add a new "### The full bundled script" subsection right after the Direct backend tip. It introduces the canonical script in prose, then shows it verbatim in a second bash code block. * Add a :::note flagging that OZ_SNAPSHOT_JQ defaults to /agent/tools/jq (an image-only path). External users adapting the script need to put jq on PATH or override OZ_SNAPSHOT_JQ. * Drop the previous :::note that summarized what the bundled script did extra — the same information is now visible directly in the script. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(cloud-agents): address Harry's review on snapshots page Apply Harry's four outstanding review comments on PR #105: - "When to customize snapshots" no longer duplicates the example list from the intro paragraph. Reframed around user intent rather than failure modes: outside-bundled-image, repos/files outside the workspace, and dynamic scripted behavior. - Replaced the "snapshot a fixed set of repositories or files" bullet with a broader "dynamic snapshotting behavior" item that calls out that the script can implement any logic the operator wants, not just a fixed list. - The "Script-driven" bullet under "How snapshotting works" now names OZ_SNAPSHOT_DECLARATIONS_SCRIPT inline, so readers know the script path is overridable before they reach the Script-driven flow subsection. The "Static" bullet now names OZ_SNAPSHOT_DECLARATIONS_FILE for symmetry. - The OZ_SNAPSHOT_DECLARATIONS_FILE entry in the Environment variables section now spells out its relationship with OZ_SNAPSHOT_DECLARATIONS_SCRIPT: when the script var is set Warp picks a per-run path and exports it to the script; users can also override the file path themselves so both Warp and the script use a path they control (or to drive the static, no-script flow). Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev>
diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx
@@ -19,7 +19,7 @@ Use this handoff direction when:
 When you send a follow-up to a run whose session has ended, the run continues with:
 
 * **The same conversation** - The follow-up is appended to the same conversation. From your perspective, the run is one continuous conversation across sessions.
-* **The prior workspace state** - The prior session's repository changes (tracked and untracked) are restored before the agent answers your follow-up. For git-managed sessions, the new session continues on the same Git branch.
+* **The prior workspace state** - The prior session's repository changes (tracked and untracked) are restored before the agent answers your follow-up. For git-managed sessions, the new session continues on the same Git branch. You can [customize which repositories and files get snapshotted](/agent-platform/cloud-agents/handoff/snapshots/) when running outside the bundled cloud agent image.
 * **Stable run identity** - The run's ID, task, creator, environment, schedule trigger, and integration source are preserved. Compute usage is recorded per session but rolls up to the same run.
 
 If applying any change fails, the agent reports what couldn't be applied and proceeds with what it could rather than starting over silently.
diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/snapshots.mdx
@@ -0,0 +1,233 @@
+---
+title: Customizing workspace snapshots
+description: >-
+  Customize which repositories and files Warp snapshots at the end of a cloud
+  agent run, so handoff continues to work outside the bundled cloud agent
+  image.
+sidebar:
+  label: "Snapshots"
+---
+
+Workspace snapshots are how [handoff](/agent-platform/cloud-agents/handoff/) carries repository changes and other workspace state across cloud agent runs. At the end of every cloud agent run, Warp asks a small declarations script which repositories and files to snapshot, then uploads the resulting git diffs and file contents so the next cloud agent run can apply them.
+
+Warp's bundled cloud agent image ships with a declarations script that snapshots every git repository under the agent's workspace, so most cloud agent runs need no configuration. This page is for the cases where you need to customize what gets snapshotted — for example, when running cloud agents in a custom Docker image, on a self-hosted [Direct backend](/agent-platform/cloud-agents/self-hosting/managed-direct/), or as an [unmanaged](/agent-platform/cloud-agents/self-hosting/unmanaged/) `oz agent run` in CI.
+
+## When to customize snapshots
+
+The default snapshotting behavior covers the most common case: snapshot every git repository the agent worked on, inside the bundled cloud agent image. Customize snapshots when you need different behavior:
+
+* **You're running outside the bundled image** — for example, a custom Docker base image, a self-hosted Direct backend, or unmanaged `oz agent run` invocations — where Warp's default `snapshot-declarations.sh` isn't on disk.
+* **You want to snapshot repos or files outside the agent's workspace** — for example, a sibling repo the agent reads but doesn't `cd` into, or a log file the agent writes to `/tmp`.
+* **You want dynamic snapshotting behavior** — because the declarations file is generated by a script that Warp runs, you can script any logic you want (filter by git status, dedupe against a baseline, emit a fixed list, etc.) rather than being limited to a static set of paths.
+
+If you don't customize snapshots in any of these cases, the run still completes — Warp just uploads nothing, and handoff into the next run starts without the prior session's uncommitted changes.
+
+## How snapshotting works
+
+There are two ways to tell Warp what to snapshot at the end of a cloud agent run:
+
+* **Script-driven** (default in the bundled image) - Warp invokes a declarations script (configured via the `OZ_SNAPSHOT_DECLARATIONS_SCRIPT` environment variable) that emits one JSON line per repository or file to snapshot. Use this when the set of repos isn't fixed ahead of time (for example, the agent may `git init` a new directory during its work) or when you want any other dynamic logic to decide what to snapshot.
+* **Static** - You pre-populate the declarations file yourself (at the path given by `OZ_SNAPSHOT_DECLARATIONS_FILE`) and skip the script. Use this when the same set of repos and files should be snapshotted on every run.
+
+### Script-driven flow
+
+1. **Warp invokes your declarations script.** The script path comes from the `OZ_SNAPSHOT_DECLARATIONS_SCRIPT` environment variable. Warp runs it with the agent's workspace as the current directory.
+2. **Warp passes a per-run output file.** Warp sets `OZ_SNAPSHOT_DECLARATIONS_FILE` to an absolute path the script must write to. Each run gets its own file so concurrent runs don't clobber each other.
+3. **Warp reads the declarations file.** Warp parses the JSONL output (described below) and uploads the listed repositories and files.
+
+See [Write a custom declarations script](#write-a-custom-declarations-script) for the full pattern.
+
+### Static flow
+
+Set `OZ_SNAPSHOT_DECLARATIONS_FILE` to a path you've already populated and leave `OZ_SNAPSHOT_DECLARATIONS_SCRIPT` unset. Warp reads the file directly with no script invocation. See [Use a static declarations file](#use-a-static-declarations-file) for the full pattern.
+
+In both flows, snapshotting is automatically enabled for cloud agent runs when cloud conversations are enabled, and can be turned off per run with `--no-snapshot`. See [Disable snapshots](#disable-snapshots) below.
+
+## Environment variables
+
+* **`OZ_SNAPSHOT_DECLARATIONS_SCRIPT`** - Absolute path to the script Warp invokes at the end of each cloud agent run. The bundled cloud agent image sets this automatically. Set it yourself when running outside the bundled image.
+* **`OZ_SNAPSHOT_DECLARATIONS_FILE`** - Absolute path to the JSONL file the script writes to (and Warp reads from). When `OZ_SNAPSHOT_DECLARATIONS_SCRIPT` is set, Warp picks a per-run path by default and exports it to the script. Set or override this variable yourself when you want Warp to read from a static, pre-populated declarations file instead of running a script, or whenever you want both Warp and the script to use a specific path you control.
+
+## Declarations file format
+
+The declarations file is UTF-8 JSONL — one JSON object per non-empty line:
+
+```json title="snapshot-declarations.jsonl"
+{"version":1,"kind":"repo","path":"/workspace/my-repo"}
+{"version":1,"kind":"file","path":"/tmp/agent-output.log"}
+```
+
+Each line has exactly these fields:
+
+* **`version`** - Always `1`. Reserved for future schema versions.
+* **`kind`** - Either `"repo"` or `"file"`.
+* **`path`** - A non-empty absolute path.
+
+A few rules to follow when writing declarations:
+
+* **Paths must be absolute.** Relative paths are rejected and logged as malformed.
+* **Prefer `repo` over `file` for paths inside a repository.** Warp generates a git diff for each `repo` entry (tracked changes plus untracked, non-gitignored files), so individual `file` entries inside that repo are redundant and dropped before upload. Including a `repo` entry is also more extensible than enumerating files.
+* **Repos are diffed, not copied wholesale.** Only changed files are uploaded for each `repo` entry, so listing a large repository is cheap when the agent's changes are small.
+* **`file` entries are for paths outside any declared repo** — for example, logs the agent wrote to `/tmp` or scratch files in `$HOME`.
+
+Malformed lines (invalid JSON, missing fields, unknown `kind`, non-absolute path) are logged as warnings and skipped; they never abort the upload.
+
+:::caution
+**Declared paths are uploaded to Warp.** `file` entries upload the file's contents verbatim, and `repo` entries upload the repo's git diff (tracked changes plus untracked, non-gitignored files). Before declaring logs, scratch files, or other agent outputs as `file` entries, make sure they don't contain secrets, credentials, API tokens, or other sensitive data.
+:::
+
+## Write a custom declarations script
+
+A custom script writes one JSON line per repository or file it wants Warp to snapshot, then exits. The minimal pattern looks like this:
+
+```bash title="snapshot-declarations.sh"
+#!/bin/bash
+set -euo pipefail
+
+# Warp sets this to a per-run output path. Fail loudly if it's missing,
+# so a misconfigured runner doesn't silently overwrite a shared file.
+if [ -z "${OZ_SNAPSHOT_DECLARATIONS_FILE:-}" ]; then
+  echo "OZ_SNAPSHOT_DECLARATIONS_FILE must be set" >&2
+  exit 1
+fi
+
+mkdir -p "$(dirname "$OZ_SNAPSHOT_DECLARATIONS_FILE")"
+
+# Find every git repo under the agent's workspace and emit a JSONL
+# repo declaration for each one. Escape backslashes and double quotes in
+# the path before writing so paths containing those characters don't
+# produce malformed JSON (which Warp skips with a warning).
+find "$PWD" -type d -name .git -prune -print 2>/dev/null \
+  | while IFS= read -r git_dir; do
+      repo_root="$(cd "$(dirname "$git_dir")" && pwd)"
+      repo_json="$(printf '%s' "$repo_root" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+      printf '{"version":1,"kind":"repo","path":"%s"}\n' "$repo_json" \
+        >> "$OZ_SNAPSHOT_DECLARATIONS_FILE"
+    done
+```
+
+Then point Warp at it by exporting `OZ_SNAPSHOT_DECLARATIONS_SCRIPT` in the environment your cloud agent runs in:
+
+```bash
+export OZ_SNAPSHOT_DECLARATIONS_SCRIPT=/path/to/snapshot-declarations.sh
+```
+
+For a managed [Direct backend](/agent-platform/cloud-agents/self-hosting/managed-direct/) worker, set it via the worker's `environment` config so it's present when the agent process starts.
+
+### The full bundled script
+
+For reference, this is the canonical declarations script Warp invokes inside the bundled cloud agent image. It's a richer version of the minimal example above: it honors a colon-separated `OZ_SNAPSHOT_SCAN_ROOTS` override for operators who need to scan repos outside the default workspace, uses `jq` for canonical JSON encoding (which handles `"` and `\` escaping for you), and dedupes against repo declarations already written in the same run so repeated invocations stay additive.
+
+:::note
+The bundled script defaults `OZ_SNAPSHOT_JQ` to `/agent/tools/jq`, which only exists inside Warp's cloud agent image. If you adapt this script for a different image or for an unmanaged `oz agent run`, put `jq` on `PATH` or set `OZ_SNAPSHOT_JQ` to its absolute path.
+:::
+
+```bash title="snapshot-declarations.sh"
+#!/bin/bash
+# Generates the declarations file consumed by the end-of-run snapshot upload pipeline.
+#
+# Scans one or more roots for `.git` directories and appends one JSON object per
+# newly-discovered repository to the declarations file.
+#
+# Scan root selection (in order of precedence):
+#   - OZ_SNAPSHOT_SCAN_ROOTS: colon-separated list of absolute paths. Operators can use this
+#     to target repos outside the default workspace.
+#   - $PWD: the Rust driver sets this to the agent's workspace via `Command::current_dir`
+#     before invoking the script, so the default scan root is always the assigned workspace.
+#
+# Output file:
+#   - OZ_SNAPSHOT_DECLARATIONS_FILE must be set. The Rust driver sets this to a per-run path
+#     so concurrent runs don't clobber each other.
+#   - The file is created if missing, and appended to if it already exists. Existing lines are
+#     never rewritten, so operator-authored declarations are preserved.
+#   - Repeated invocations within a single run skip already-emitted repo declarations so the
+#     upload pipeline can stay additive without duplicating identical generated entries.
+
+set -euo pipefail
+
+SCAN_ROOTS_RAW="${OZ_SNAPSHOT_SCAN_ROOTS:-$PWD}"
+IFS=':' read -r -a SCAN_ROOTS <<< "$SCAN_ROOTS_RAW"
+
+if [ -z "${OZ_SNAPSHOT_DECLARATIONS_FILE:-}" ]; then
+    echo "OZ_SNAPSHOT_DECLARATIONS_FILE must be set" >&2
+    exit 1
+fi
+
+DECL_FILE="$OZ_SNAPSHOT_DECLARATIONS_FILE"
+JQ="${OZ_SNAPSHOT_JQ:-/agent/tools/jq}"
+mkdir -p "$(dirname "$DECL_FILE")"
+touch "$DECL_FILE"
+
+# Dedup set. Seed from repo declarations already emitted by this script so a repeated
+# invocation within the same run doesn't re-emit repos it already discovered earlier.
+# Keep the full canonical JSON line as the key; this lets us preserve unrelated JSONL entries
+# verbatim while ensuring identical generated declarations are emitted at most once.
+SEEN_FILE="$(mktemp)"
+trap 'rm -f "$SEEN_FILE"' EXIT
+"$JQ" --raw-input --compact-output '
+    fromjson?
+    | select(
+        type == "object"
+        and (. | keys_unsorted | sort == ["kind", "path", "version"])
+        and .version == 1
+        and .kind == "repo"
+        and (.path | type == "string")
+    )
+    | { version: 1, kind: "repo", path: .path }
+' "$DECL_FILE" > "$SEEN_FILE"
+
+repo_declaration_for_path() {
+    "$JQ" --compact-output --null-input \
+        --arg path "$1" \
+        '{ version: 1, kind: "repo", path: $path }'
+}
+
+for root in "${SCAN_ROOTS[@]}"; do
+    [ -d "$root" ] || continue
+    while IFS= read -r git_dir; do
+        repo_root="$(cd "$(dirname "$git_dir")" && pwd)"
+        repo_declaration="$(repo_declaration_for_path "$repo_root")"
+        if grep -Fxq -- "$repo_declaration" "$SEEN_FILE"; then
+            continue
+        fi
+        printf '%s\n' "$repo_declaration" >> "$SEEN_FILE"
+        printf '%s\n' "$repo_declaration" >> "$DECL_FILE"
+    done < <(find "$root" -type d -name .git -prune -print 2>/dev/null)
+done
+```
+
+## Use a static declarations file
+
+If the same set of repositories or files should be snapshotted on every run (for example, an unmanaged GitHub Actions job operating on a known checkout), you can skip the script entirely and pre-populate a JSONL file:
+
+```json title="/etc/oz/snapshot-declarations.jsonl"
+{"version":1,"kind":"repo","path":"/workspace/my-repo"}
+{"version":1,"kind":"repo","path":"/workspace/shared-libs"}
+```
+
+Then point Warp at the file directly:
+
+```bash
+export OZ_SNAPSHOT_DECLARATIONS_FILE=/etc/oz/snapshot-declarations.jsonl
+# Do not set OZ_SNAPSHOT_DECLARATIONS_SCRIPT in this mode.
+```
+
+Warp reads the file at end-of-run and uploads the listed repos and files. Because the file is the same on every run, this is best for environments where the workspace layout is fixed.
+
+## Disable snapshots
+
+To opt out of snapshotting for a single run, pass `--no-snapshot` to the CLI:
+
+```bash
+oz agent run-cloud --prompt "Fix the failing test" --no-snapshot
+```
+
+Snapshotting is also skipped automatically when cloud conversations are disabled for the team.
+
+## Related pages
+
+* [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/) - Promote a local conversation to a cloud run; the workspace snapshot is what carries your uncommitted changes across.
+* [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/) - Continue a finished cloud run; the prior session's workspace snapshot is what gets restored.
+* [Self-hosting overview](/agent-platform/cloud-agents/self-hosting/) - Architecture decision guide for self-hosted workers, where customizing snapshots is most often needed.
+* [Unmanaged architecture](/agent-platform/cloud-agents/self-hosting/unmanaged/) - Run `oz agent run` in CI, Kubernetes, or your dev environment outside the bundled image.
+* [Oz CLI](/reference/cli/) - Full reference for `oz agent run` and `oz agent run-cloud`.
diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx
@@ -216,3 +216,4 @@ For infrastructure-level observability, the `oz-agent-worker` daemon can export
 * [Troubleshooting](/agent-platform/cloud-agents/self-hosting/troubleshooting/) — Worker won't start, tasks not picked up, and other common issues.
 * [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) — How self-hosting compares to CLI-only and Warp-hosted deployment.
 * [Environments](/agent-platform/cloud-agents/environments/) — Define the runtime context for agent tasks.
+* [Customizing workspace snapshots](/agent-platform/cloud-agents/handoff/snapshots/) — Configure end-of-run snapshots so handoff works when running outside the bundled cloud agent image.
diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx
@@ -126,6 +126,8 @@ Unmanaged agents are tracked on Warp's backend. Each run creates a persistent se
 
 Unmanaged sessions benefit from the same shared configuration as other cloud agent runs — [MCP servers](/agent-platform/cloud-agents/mcp/), [secrets](/agent-platform/cloud-agents/secrets/), Warp Drive context, and saved prompts all apply.
 
+Unmanaged runs don't ship with the bundled declarations script, so end-of-run workspace snapshots are a no-op by default. To enable [handoff](/agent-platform/cloud-agents/handoff/) into a follow-up run, see [Customizing workspace snapshots](/agent-platform/cloud-agents/handoff/snapshots/).
+
 ---
 
 ## Related pages
diff --git a/src/sidebar.ts b/src/sidebar.ts
@@ -371,6 +371,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [
 								{ slug: 'agent-platform/cloud-agents/handoff', label: 'Overview' },
 								{ slug: 'agent-platform/cloud-agents/handoff/local-to-cloud', label: 'Local to cloud' },
 								{ slug: 'agent-platform/cloud-agents/handoff/cloud-to-cloud', label: 'Cloud to cloud' },
+								{ slug: 'agent-platform/cloud-agents/handoff/snapshots', label: 'Snapshots' },
 							],
 						},
 						'agent-platform/cloud-agents/secrets',
