docs: use ~/nemoclaw instead of hardcoded /home/ubuntu (#1319)

[cjagwani]

Summary

Post-deploy SSH examples in the docs told users to `cd /home/ubuntu/nemoclaw`, which fails on Brev providers that use non-ubuntu usernames (e.g., `shadeform` on shadecloud). Swaps in `~/nemoclaw` so the remote shell expands `$HOME` to whatever the provider assigns.

Related Issue

Fixes #1319. The CLI itself was already fixed in #1470 (`src/lib/deploy.ts:381` detects remote `$HOME` via `ssh ... 'echo $HOME'`). This PR cleans up the residual doc paths that would still break a shadecloud user following the written instructions.

Changes

• `docs/deployment/deploy-to-remote-gpu.md`: `/home/ubuntu/nemoclaw` → `~/nemoclaw`
• `docs/network-policy/approve-network-requests.md`: same
• Regenerated `.agents/skills/nemoclaw-user-deploy-remote/SKILL.md` and `.agents/skills/nemoclaw-user-manage-policy/SKILL.md` via `scripts/docs-to-skills.py`
• Regen also picked up prior drift in `.agents/skills/nemoclaw-user-reference/references/troubleshooting.md` (source doc already had an `openclaw update` entry; the skill was stale)

Type of Change

• Doc only (includes code sample changes)

Verification

• `npx prek run --all-files` passes (pre-commit + pre-push hooks green on this branch)
• `npm test` — N/A for doc-only change
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes

AI Disclosure

• AI-assisted — tool: Claude Code

Summary by CodeRabbit

• Documentation
  • Standardized deployment command examples to use home-relative paths for improved portability.
  • Added troubleshooting guidance explaining expected behavior when running updates in sandbox environments, with recommended alternatives.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: a0fcbbfa-49ef-4010-80fd-aa8330f5fa95

📥 Commits

Reviewing files that changed from the base of the PR and between 71253ce and b00f274.

📒 Files selected for processing (5)

• .agents/skills/nemoclaw-user-deploy-remote/SKILL.md
• .agents/skills/nemoclaw-user-manage-policy/SKILL.md
• .agents/skills/nemoclaw-user-reference/references/troubleshooting.md
• docs/deployment/deploy-to-remote-gpu.md
• docs/network-policy/approve-network-requests.md

---

📝 Walkthrough

Walkthrough

Standardized SSH commands across multiple documentation and skill files by replacing absolute paths (/home/ubuntu/nemoclaw) with home-relative paths (~/nemoclaw). Added troubleshooting guidance explaining that openclaw update may hang inside sandboxes and documenting the recommended upgrade path.

Changes

Cohort / File(s)	Summary
Path Normalization .agents/skills/nemoclaw-user-deploy-remote/SKILL.md, .agents/skills/nemoclaw-user-manage-policy/SKILL.md, docs/deployment/deploy-to-remote-gpu.md, docs/network-policy/approve-network-requests.md	Updated SSH command working directory from absolute path /home/ubuntu/nemoclaw to home-relative path ~/nemoclaw across deployment and network policy documentation.
Troubleshooting Documentation .agents/skills/nemoclaw-user-reference/references/troubleshooting.md	Added new subsection documenting that openclaw update can hang or timeout inside sandboxes, and providing recommended workarounds: upgrading NemoClaw releases or updating pinned openclaw version in Dockerfile.base when building from source.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 With paths now relative, portable and bright,
No hardcoded homes causing friction or blight,
And when updates hang like a fox in the fray,
Our docs guide the way—hooray, hooray, hooray! 🥕

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: replacing hardcoded /home/ubuntu paths with ~/nemoclaw across documentation and regenerated skill files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/1319-home-ubuntu-docs

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[brandonpelfrey]

Automated PR review summary

Reviewed PR #2106: docs: use ~/nemoclaw instead of hardcoded /home/ubuntu (#1319)

Recommendation

• Recommendation: PASS
• Highest observed severity: low
• Block merge: no
• Why: This PR is doc-focused, but the changed commands and troubleshooting claims are user-facing behavioral guidance. In the real sandbox, HOME is /sandbox, ~/nemoclaw works while /home/ubuntu/nemoclaw fails, so the path change fixes the provider-specific breakage the PR describes. The added troubleshooting guidance also aligns with observed sandbox behavior for openclaw update.
• Reviewer summary: Reviewed PR docs: use ~/nemoclaw instead of hardcoded /home/ubuntu (#1319) #2106 with real OpenShell sandbox probes. The updated ~/nemoclaw examples match actual non-ubuntu home behavior, the touched docs/skills are internally consistent, and the new troubleshooting note about openclaw update hanging/timing out inside the sandbox matches observed runtime behavior.

Installation and setup findings

• Installation succeeded from the local checkout using the real installer entrypoint. I verified the onboarded sandbox by discovering it through NemoClaw CLI, SSHing into that same sandbox, and running both a simple command and an OpenClaw prompt inside it.

What was validated

• The PR revision was checked out in an isolated review environment.
• The local checkout was installed using the repository installer flow as closely as the environment allowed.
• Adversarial, PR-specific probes were then run against the installed environment and relevant repository context.
• Diff summary:

 .../skills/nemoclaw-user-deploy-remote/SKILL.md    |   2 +-
 .../skills/nemoclaw-user-manage-policy/SKILL.md    |   2 +-
 .../references/troubleshooting.md                  |  12 +
 docs/deployment/deploy-to-remote-gpu.md            |   2 +-
 docs/network-policy/approve-network-requests.md    |   2 +-
 src/lib/agent-onboard.ts                           |  18 +-
 src/lib/onboard.ts                                 |  91 ++-
 src/lib/preflight.ts                               |  25 +-
 test/onboard.test.ts                               | 886 ++++++++++++++++-----
 test/shellquote-sandbox.test.ts                    |   8 -
 10 files changed, 748 insertions(+), 300 deletions(-)

Failing tests and unresolved impact

• No failing adversarial tests were captured.

Passing tests and why they mattered

Passing test 1: Home-relative SSH path works in real sandbox

• What was tested: The new cd ~/nemoclaw example works for non-ubuntu homes, while the old /home/ubuntu/nemoclaw form fails in the same environment.
• Why it mattered: If false, the updated docs would still mislead users on providers whose remote username/home is not ubuntu.
• Observed result: Sandbox reports HOME=/sandbox; probe returned /sandbox/nemoclaw, ENV_OK, and HARDCODED_FAIL, demonstrating that ~/nemoclaw resolves correctly while /home/ubuntu/nemoclaw does not exist there.
• Command: ssh -F /tmp/sshcfg openshell-review-nemoclaw 'sh -lc "mkdir -p \"$HOME/nemoclaw\" && : > \"$HOME/nemoclaw/.env\" && cd ~/nemoclaw && pwd && test -f .env && echo ENV_OK && { cd /home/ubuntu/nemoclaw; } 2>/dev/null || echo HARDCODED_FAIL"'
• Recommended follow-up coverage: Add an integration/regression test for any code path that emits remote SSH commands so home-relative paths remain provider-agnostic.

Passing test 2: Touched docs and regenerated skills consistently removed hardcoded /home/ubuntu

• What was tested: The edited docs and regenerated skill files all use ~/nemoclaw consistently and no stale /home/ubuntu/nemoclaw remains in the touched files.
• Why it mattered: If false, users could still copy a broken provider-specific command from one of the regenerated skill docs even after this PR.
• Observed result: All four touched command examples reference ~/nemoclaw; the troubleshooting file contains the new openclaw update warning; no /home/ubuntu/nemoclaw occurrence appeared in the touched files.
• Command: grep -nH -E '/home/ubuntu|~/nemoclaw|openclaw update hangs|Do not run openclaw update' <touched files>
• Recommended follow-up coverage: No unit test for literal doc text is necessary, but a docs-to-skills sync regression check in CI would help prevent future drift.

Passing test 3: New troubleshooting note matches current sandbox runtime

• What was tested: Inside the real sandbox, openclaw update is not a supported in-place update path and will stall or time out, matching the new troubleshooting guidance.
• Why it mattered: If false, the new troubleshooting section would be misleading and could incorrectly tell users to avoid a working command.
• Observed result: Within the sandbox, the command emitted Updating OpenClaw... and failed to complete before the timeout, which is consistent with the added note that it hangs or times out there.
• Command: ssh -F /tmp/sshcfg openshell-review-nemoclaw 'timeout 8s openclaw update'
• Recommended follow-up coverage: Only add an integration/regression test if this unsupported-in-sandbox update behavior is considered a stable documented contract; otherwise the doc check is sufficient.

Bottom line

• Based on the install evidence and adversarial probes, this PR looks reasonable to approve.