docs: document workspace file persistence and backup/restore#663
Merged
docs: document workspace file persistence and backup/restore#663
Conversation
Add concept page explaining all six workspace files (SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md, memory/) with links to upstream OpenClaw template docs. Add how-to page for manual and scripted backup/restore using openshell sandbox download/upload. Add data-loss warning to the destroy command reference. Add Workspace section to docs navigation. Closes #434 Supersedes #456 and #476
|
Caution Review failedPull request was closed or merged during review Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughAdds documentation for OpenClaw workspace files and a backup/restore guide, updates the docs index and the Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Script as backup-workspace.sh
participant OpenShell as openshell CLI
participant Sandbox
User->>Script: backup <sandbox-name>
Script->>Script: create timestamped backup dir
loop for each workspace file/dir
Script->>OpenShell: sandbox download [item]
OpenShell->>Sandbox: request item
Sandbox-->>OpenShell: return content or error
OpenShell-->>Script: success or failure
Script->>Script: update counters & emit warnings
end
Script->>Script: verify >=1 item backed up
alt success
Script-->>User: show backup path & count
else
Script-->>User: exit with error
end
sequenceDiagram
participant User
participant Script as backup-workspace.sh
participant LocalFS as Local FS
participant OpenShell as openshell CLI
participant Sandbox
User->>Script: restore <sandbox-name> [timestamp]
Script->>LocalFS: list/validate backup directories
alt timestamp provided
Script->>Script: select provided timestamp
else
Script->>Script: choose most recent timestamp
end
loop for each backed-up item
Script->>OpenShell: sandbox upload [item]
OpenShell->>Sandbox: upload content
Sandbox-->>OpenShell: confirmation or error
OpenShell-->>Script: success or failure
Script->>Script: update counters & emit warnings
end
Script->>Script: verify >=1 item restored
alt success
Script-->>User: show restore count
else
Script-->>User: exit with error
end
Estimated Code Review Effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (4)
docs/reference/commands.md (2)
109-109: Format workspace filenames as inline code in the warning text.Line 109 lists filenames as plain text; wrap each filename in inline code formatting.
As per coding guidelines, "CLI commands, file paths, flags, parameter names, and values must use inline
codeformatting."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/reference/commands.md` at line 109, Update the warning text that currently lists SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md, and daily memory notes so each filename is wrapped in inline code formatting (e.g., `SOUL.md`) instead of plain text; locate the "workspace files" link/line in the commands reference content and replace the unformatted filenames with inline `code`-formatted filenames to comply with the CLI/docs style guideline.
108-109: Keep one complete sentence on one source line.Lines 108-109 split a single sentence across two source lines; keep each sentence on its own line.
As per coding guidelines, "One sentence per line in source (makes diffs readable). Flag paragraphs where multiple sentences appear on the same line."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/reference/commands.md` around lines 108 - 109, The sentence "Destroying a sandbox permanently deletes all files inside it, including [workspace files](../workspace/workspace-files.md) (SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md, and daily memory notes)." is split across two source lines; merge them so the entire sentence appears on a single source line in docs/reference/commands.md (locate the sentence by its text) to comply with the "one sentence per line" guideline.docs/workspace/workspace-files.md (1)
79-80: Remove bold emphasis from routine list labels (LLM pattern detected).Lines 79-80 apply bold to normal instructions; keep bold for UI labels, parameters, and genuine warnings.
As per coding guidelines, "Unnecessary bold on routine instructions ('This is a critical step' when nothing is actually critical). Bold is reserved for UI labels, parameter names, and genuine warnings."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/workspace/workspace-files.md` around lines 79 - 80, Remove the unnecessary bold from the routine list labels by changing the two list items' leading bolded phrases to plain text: replace "**Let the agent do it** — Ask your agent..." with "Let the agent do it — Ask your agent..." and replace "**Edit manually** — Use `openshell sandbox connect`..." with "Edit manually — Use `openshell sandbox connect`..." while preserving inline code spans/backticks (e.g., `openshell sandbox connect`, `openshell sandbox upload`) and keeping bold only for actual UI labels, parameter names, or genuine warnings elsewhere.docs/workspace/backup-restore.md (1)
28-38: Add introductory sentences under headings that currently jump straight to lists/code.Lines 28, 34, and 77 should each have a short lead sentence before the bullets or command block.
As per coding guidelines, "Sections use H2 and H3, each starting with an introductory sentence."
Also applies to: 77-83
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/workspace/backup-restore.md` around lines 28 - 38, Add a one-sentence introductory lead under each section header that currently jumps straight into a list or command block: specifically add short lead sentences beneath the H2 "Prerequisites" and the H2 "When to Back Up", and also add a lead sentence before the command block in the later section that starts at the command-example (the heading that contains that command block). For each, insert a single concise sentence that explains the purpose of the section (e.g., what the prerequisites are for, what triggers a backup, and what the command block shows) so the H2/H3 headers begin with a contextual introductory sentence per the documentation style guide.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/workspace/backup-restore.md`:
- Around line 122-126: Rename the bottom navigation heading from "Related
Topics" to "Next Steps" to conform to guidelines: update the header line that
currently reads "## Related Topics" to "## Next Steps" and ensure the rest of
the links (the list below that header) remain unchanged so the section functions
as the required "Next Steps" block.
In `@docs/workspace/workspace-files.md`:
- Around line 82-85: Replace the closing "Related Topics" heading with "Next
Steps" and keep the existing link list intact; specifically change the heading
text "Related Topics" to "Next Steps" in the section that currently contains the
two links so the page conforms to the new docs guideline requiring a "Next
Steps" section at the bottom.
In `@scripts/backup-workspace.sh`:
- Line 44: Remove the suppression of chmod errors on the backup directories:
locate the chmod invocation that sets permissions for "${HOME}/.nemoclaw" and
"$BACKUP_BASE" (the line with chmod 0700 "${HOME}/.nemoclaw" "$BACKUP_BASE") and
stop redirecting stderr to /dev/null and silencing failures with "|| true";
instead propagate failure (either let the script exit on error or check the
chmod exit status and exit non‑zero with a clear error message) so
permission-setting failures cause the script to fail closed and surface the
problem.
---
Nitpick comments:
In `@docs/reference/commands.md`:
- Line 109: Update the warning text that currently lists SOUL.md, USER.md,
IDENTITY.md, AGENTS.md, MEMORY.md, and daily memory notes so each filename is
wrapped in inline code formatting (e.g., `SOUL.md`) instead of plain text;
locate the "workspace files" link/line in the commands reference content and
replace the unformatted filenames with inline `code`-formatted filenames to
comply with the CLI/docs style guideline.
- Around line 108-109: The sentence "Destroying a sandbox permanently deletes
all files inside it, including [workspace
files](../workspace/workspace-files.md) (SOUL.md, USER.md, IDENTITY.md,
AGENTS.md, MEMORY.md, and daily memory notes)." is split across two source
lines; merge them so the entire sentence appears on a single source line in
docs/reference/commands.md (locate the sentence by its text) to comply with the
"one sentence per line" guideline.
In `@docs/workspace/backup-restore.md`:
- Around line 28-38: Add a one-sentence introductory lead under each section
header that currently jumps straight into a list or command block: specifically
add short lead sentences beneath the H2 "Prerequisites" and the H2 "When to Back
Up", and also add a lead sentence before the command block in the later section
that starts at the command-example (the heading that contains that command
block). For each, insert a single concise sentence that explains the purpose of
the section (e.g., what the prerequisites are for, what triggers a backup, and
what the command block shows) so the H2/H3 headers begin with a contextual
introductory sentence per the documentation style guide.
In `@docs/workspace/workspace-files.md`:
- Around line 79-80: Remove the unnecessary bold from the routine list labels by
changing the two list items' leading bolded phrases to plain text: replace
"**Let the agent do it** — Ask your agent..." with "Let the agent do it — Ask
your agent..." and replace "**Edit manually** — Use `openshell sandbox
connect`..." with "Edit manually — Use `openshell sandbox connect`..." while
preserving inline code spans/backticks (e.g., `openshell sandbox connect`,
`openshell sandbox upload`) and keeping bold only for actual UI labels,
parameter names, or genuine warnings elsewhere.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: aa744e5c-96ee-4084-9a7a-9144d597ba17
📒 Files selected for processing (5)
docs/index.mddocs/reference/commands.mddocs/workspace/backup-restore.mddocs/workspace/workspace-files.mdscripts/backup-workspace.sh
- Rename "Related Topics" to "Next Steps" in both doc pages - Fail hard on chmod instead of suppressing with 2>/dev/null
There was a problem hiding this comment.
🧹 Nitpick comments (1)
scripts/backup-workspace.sh (1)
47-47: Inconsistent error handling forchmodon the backup destination directory.Line 44-45 properly fails if
chmoderrors, but line 47 does not handle achmodfailure on$dest. Withset -e, the script will exit on failure but without a clear error message.Proposed fix for consistent error handling
mkdir -p "$dest" - chmod 0700 "$dest" + chmod 0700 "$dest" || \ + fail "Failed to set secure permissions on ${dest}"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scripts/backup-workspace.sh` at line 47, The chmod on the backup destination ($dest) lacks explicit error handling; mirror the existing pattern used earlier: run chmod 0700 "$dest" and, if it fails, print a clear stderr message including $dest and exit non‑zero. Locate the chmod invocation for $dest and append the same failure handler used for the earlier chmod (i.e., a short conditional or || block that echoes an informative error to stderr and exits with 1) so failures produce a clear log and consistent behavior.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@scripts/backup-workspace.sh`:
- Line 47: The chmod on the backup destination ($dest) lacks explicit error
handling; mirror the existing pattern used earlier: run chmod 0700 "$dest" and,
if it fails, print a clear stderr message including $dest and exit non‑zero.
Locate the chmod invocation for $dest and append the same failure handler used
for the earlier chmod (i.e., a short conditional or || block that echoes an
informative error to stderr and exits with 1) so failures produce a clear log
and consistent behavior.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 4bb8471d-7aa5-4d33-b1fe-9d65ad90d86b
📒 Files selected for processing (3)
docs/workspace/backup-restore.mddocs/workspace/workspace-files.mdscripts/backup-workspace.sh
✅ Files skipped from review due to trivial changes (1)
- docs/workspace/workspace-files.md
miyoungc
approved these changes
Mar 22, 2026
miyoungc
force-pushed
the
docs/workspace-files-backup-restore
branch
from
1d64ae0 to
9800bca
Compare
craigamcw
pushed a commit
to craigamcw/NemoClaw
that referenced
this pull request
Mar 22, 2026
) * docs: document workspace file persistence and backup/restore guidance Add concept page explaining all six workspace files (SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md, memory/) with links to upstream OpenClaw template docs. Add how-to page for manual and scripted backup/restore using openshell sandbox download/upload. Add data-loss warning to the destroy command reference. Add Workspace section to docs navigation. Closes NVIDIA#434 Supersedes NVIDIA#456 and NVIDIA#476 * fix: address CodeRabbit review on PR NVIDIA#663 - Rename "Related Topics" to "Next Steps" in both doc pages - Fail hard on chmod instead of suppressing with 2>/dev/null * fix: minor edit * fix: nit --------- Co-authored-by: Miyoung Choi <miyoungc@nvidia.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Combines the best of #456 and #476 to fully address #434 — documenting workspace file persistence and providing backup/restore guidance.
New files:
docs/workspace/workspace-files.md— Concept page covering all six workspace files (SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md,memory/) with links to upstream OpenClaw template docsdocs/workspace/backup-restore.md— How-to guide for manual and scripted backup/restorescripts/backup-workspace.sh— Convenience script for automated backup and restoreModified files:
docs/reference/commands.md— Added data-loss warning to thenemoclaw <name> destroysectiondocs/index.md— Added Workspace section to navigation and Explore gridWhat this fixes over #456 and #476
openshell sandbox shellopenshell sandbox connectopenshell sandbox restart2>/dev/nullCloses #434
Supersedes #456 and #476
Test plan
make docs-strict)scripts/backup-workspace.sh backup <name>against a running sandboxscripts/backup-workspace.sh restore <name>against a fresh sandboxSummary by CodeRabbit
New Features
Documentation