diff --git a/docs/cli/backup.md b/docs/cli/backup.md
index 18ca10d188a..79f7683482a 100644
--- a/docs/cli/backup.md
+++ b/docs/cli/backup.md
@@ -26,5 +26,43 @@ openclaw backup verify ./openclaw-backup-2026-03-09T00-00-00.000Z.tar.gz
 - If the current working directory is inside a backed-up source tree, OpenClaw falls back to your home directory for the default archive location.
 - Existing archive files are never overwritten.
 - Output paths inside the source state/workspace trees are rejected to avoid self-inclusion.
-- `openclaw backup verify <archive>` validates that the archive contains exactly one manifest and that every manifest-declared payload exists in the tarball.
+- `openclaw backup verify <archive>` validates that the archive contains exactly one root manifest, rejects traversal-style archive paths, and checks that every manifest-declared payload exists in the tarball.
 - `openclaw backup create --verify` runs that validation immediately after writing the archive.
+
+## What gets backed up
+
+`openclaw backup create` plans backup sources from your local OpenClaw install:
+
+- The state directory returned by OpenClaw's local state resolver, usually `~/.openclaw`
+- The active config file path
+- The OAuth / credentials directory
+- Workspace directories discovered from the current config, unless you pass `--no-include-workspace`
+
+OpenClaw canonicalizes paths before building the archive. If config, credentials, or a workspace already live inside the state directory, they are not duplicated as separate top-level backup sources. Missing paths are skipped.
+
+The archive payload stores file contents from those source trees, and the embedded `manifest.json` records the resolved absolute source paths plus the archive layout used for each asset.
+
+## Invalid config behavior
+
+`openclaw backup` intentionally bypasses the normal config preflight so it can still help during recovery. Because workspace discovery depends on a valid config, `openclaw backup create` now fails fast when the config file exists but is invalid and workspace backup is still enabled.
+
+If you still want a partial backup in that situation, rerun:
+
+```bash
+openclaw backup create --no-include-workspace
+```
+
+That keeps state, config, and credentials in scope while skipping workspace discovery entirely.
+
+## Size and performance
+
+OpenClaw does not enforce a built-in maximum backup size or per-file size limit.
+
+Practical limits come from the local machine and destination filesystem:
+
+- Available space for the temporary archive write plus the final archive
+- Time to walk large workspace trees and compress them into a `.tar.gz`
+- Time to rescan the archive if you use `openclaw backup create --verify` or run `openclaw backup verify`
+- Filesystem behavior at the destination path. OpenClaw prefers a no-overwrite hard-link publish step and falls back to exclusive copy when hard links are unsupported
+
+Large workspaces are usually the main driver of archive size. If you want a smaller or faster backup, use `--no-include-workspace`.