docs(cli): clarify OpenShell compatibility recovery

[WuKongAI-CMU]

Summary

• document that NemoClaw-managed deployments should not upgrade or recreate OpenShell resources independently
• add recovery guidance to README, quickstart, and troubleshooting
• update the CLI incompatibility hint and lock it with a CLI test

Verification

• ./node_modules/.bin/vitest run test/cli.test.js
• npm run typecheck:cli

Summary by CodeRabbit

• Documentation

  • Added OpenShell version compatibility guidance, recovery workflow, and warnings to avoid running manual OpenShell/NPM lifecycle commands on NemoClaw-managed deployments.

• Bug Fixes

  • Clarified user-facing guidance for incompatible OpenShell instances, advising backup and rerunning nemoclaw onboard rather than standalone OpenShell lifecycle commands.

• Tests

  • Updated CLI tests to expect the revised compatibility guidance text.

[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

Run ID: fdde9cab-fcc7-4218-bb8f-46fd1ff6dbe6

📥 Commits

Reviewing files that changed from the base of the PR and between f648912 and 27110b8.

📒 Files selected for processing (5)

• README.md
• bin/nemoclaw.js
• docs/get-started/quickstart.md
• docs/reference/troubleshooting.md
• test/cli.test.js

✅ Files skipped from review due to trivial changes (2)

• README.md
• docs/get-started/quickstart.md

🚧 Files skipped from review as they are similar to previous changes (3)

• test/cli.test.js
• bin/nemoclaw.js
• docs/reference/troubleshooting.md

---

📝 Walkthrough

Walkthrough

Added documentation and CLI/test messaging clarifying that NemoClaw pins the OpenShell runtime; users must not run standalone OpenShell/NPM lifecycle or sandbox/gateway recreate commands on NemoClaw-managed deployments. Recovery guidance: back up workspace and rerun nemoclaw onboard to restore the expected runtime and managed resources.

Changes

Cohort / File(s)	Summary
Version Compatibility Documentation README.md, docs/get-started/quickstart.md, docs/reference/troubleshooting.md	Added guidance that OpenShell version is tied to NemoClaw releases, warned against running standalone openshell/npm lifecycle or gateway/sandbox recreate commands on NemoClaw-managed deployments, and documented recovery: back up workspace and rerun nemoclaw onboard.
OpenShell Compatibility Error Messages bin/nemoclaw.js	Reworded printOldLogsCompatibilityGuidance() to separately instruct rerunning nemoclaw onboard to reinstall the pinned OpenShell and to explicitly warn against running openshell self-update or recreating sandboxes/gateways via openshell.
Test Updates test/cli.test.js	Updated CLI test assertions to expect the new guidance substrings about reinstalling the pinned OpenShell and not running openshell self-update.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 OpenShell snug, tied to the release,
Hop not at the shell with a wild, brisk increase.
Back up your nest, then call onboard once more—
I'll twirl my ears when the sandbox is restored.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately summarizes the main purpose of the changeset: clarifying OpenShell compatibility recovery guidance across documentation and CLI error messages.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

🧹 Nitpick comments (1)

docs/get-started/quickstart.md (1)

82-86: Use an allowed MyST admonition type here.

important is not in the allowed callout set for docs pages in this repo. Use warning (or note/tip) instead.

Suggested diff

-:::{important} OpenShell version compatibility
+:::{warning} OpenShell version compatibility
 Treat the OpenShell version installed or reused by NemoClaw as part of the NemoClaw release you installed.
 Do not run `openshell self-update`, `npm update -g openshell`, `openshell gateway start --recreate`, or `openshell sandbox create` directly for a NemoClaw-managed deployment.
 If you suspect an incompatible OpenShell upgrade, [back up your workspace](../workspace/backup-restore.md) and rerun `nemoclaw onboard` so NemoClaw can reinstall the expected runtime and rebuild the managed resources.
 :::

As per coding guidelines, “Use MyST admonitions (:::{tip}, :::{note}, :::{warning}) for callouts, not bold text or blockquotes.”

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/get-started/quickstart.md` around lines 82 - 86, The MyST admonition
currently uses an unsupported type "important" (the block starting with
":::important"); change it to a supported callout such as ":::warning" (or
":::note"/":::tip") so the docs lint and render correctly—update the admonition
header and closing token to match (e.g., replace ":::important" ... ":::” with
":::warning" ... ":::") and keep the existing content unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/get-started/quickstart.md`:
- Around line 82-86: The MyST admonition currently uses an unsupported type
"important" (the block starting with ":::important"); change it to a supported
callout such as ":::warning" (or ":::note"/":::tip") so the docs lint and render
correctly—update the admonition header and closing token to match (e.g., replace
":::important" ... ":::” with ":::warning" ... ":::") and keep the existing
content unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d408196c-4826-4231-a563-3cb9b78c3655

📥 Commits

Reviewing files that changed from the base of the PR and between e231d32 and 87ed7a5.

📒 Files selected for processing (5)

• README.md
• bin/nemoclaw.js
• docs/get-started/quickstart.md
• docs/reference/troubleshooting.md
• test/cli.test.js

[wscurran]

✨ Thanks for submitting this pull request, which proposes a way to clarify OpenShell compatibility recovery.

---

Possibly related open issues:

• #1261 Upgrading OpenShell independently breaks NemoClaw sandbox — version coupling should be documented
• #1260 Multi-agent deployments need workspace sync strategy — docs assume single agent
• #1237 refactor(cli): extract pure functions from onboard.js to typed TypeScript modules