docs: complete coding-agent starter prompt guidance

[miyoungc]

Summary

Make the coding-agent starter prompt construct non-interactive installs with explicit agent, provider, and release-tag variables.
Add tool-neutral Docker approval guidance that keeps escalation command-scoped and preserves the execution-sandbox boundary.

Related Issue

Fixes #7311

Changes

• Name NEMOCLAW_AGENT for every supported agent and pair it with NEMOCLAW_PROVIDER during non-interactive command construction.
• Document NEMOCLAW_INSTALL_TAG=vX.Y.Z on the bash side of the installer pipeline and clear any inherited higher-priority NEMOCLAW_INSTALL_REF.
• Align the environment-variable reference and explicit lkg upgrade example with the same install-ref precedence.
• Tell a coding agent to use its command-scoped approval flow only for the exact Docker command blocked by its execution sandbox.
• Prohibit Docker socket permission changes and broad host access as sandbox workarounds.
• Add a regression contract for all three requested variables, release-tag precedence and placement, and the coding-agent Docker approval boundary.
• Record the QA detection gap: existing tests protected prompt generation and Deep Agents selection but did not assert the complete install-variable or execution-sandbox contract.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: Independent documentation review confirmed the guidance is coding-agent-neutral, narrowed escalation to Docker commands, required explicit denial behavior, and prohibited socket-permission and broad-host-access workarounds.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: vitest run --project integration test/starter-prompt-docs.test.ts passed 18 tests.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only) — the command passed with 0 errors and one existing Fern light-mode accent contrast warning outside this diff.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Miyoung Choi miyoungc@nvidia.com

Summary by CodeRabbit

• Documentation

  • Expanded non-interactive onboarding with explicit agent/provider environment variables and clearer installation version pinning guidance.
  • Updated precedence rules for install reference vs install tag, including how CLI flags override each.
  • Added execution-sandbox guidance for when Docker commands are blocked, including narrowly scoped re-approval and what to avoid.

• Tests

  • Added a starter-prompt documentation test to verify required environment variables, sandbox approval language, and correct precedence/tag formatting rules.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: b770aa7c-06b2-45cb-bfcc-9f3295657e77

📥 Commits

Reviewing files that changed from the base of the PR and between b1f268e and 0ba277a.

📒 Files selected for processing (1)

• test/starter-prompt-docs.test.ts

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

• test/starter-prompt-docs.test.ts

---

📝 Walkthrough

Walkthrough

The PR updates NemoClaw onboarding documentation with explicit agent and installer-version variables, Docker sandbox approval guidance, and clarified precedence rules. A new test validates the starter prompt and related documentation content.

Changes

Non-interactive onboarding guidance

Layer / File(s)	Summary
Installer selection and version controls docs/get-started/quickstart.mdx, docs/manage-sandboxes/update-sandboxes.mdx, docs/reference/commands.mdx	Documents agent selection, maintained or pinned releases, clearing inherited install references, and CLI/environment-variable precedence.
Starter prompt execution guidance docs/resources/starter-prompt.md, docs/get-started/quickstart.mdx	Adds supported agent values, scoped Docker approval instructions, and non-interactive installation rules.
Cross-document assertions test/starter-prompt-docs.test.ts	Verifies required environment-variable names, precedence wording, sandbox guidance, and disallowed content across the documentation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• NVIDIA/NemoClaw#6894: Updates the starter-prompt generation and related non-interactive guidance.
• NVIDIA/NemoClaw#6990: Modifies the starter prompt and tests for environment-variable and sandbox guidance.
• NVIDIA/NemoClaw#7321: Adds overlapping installer environment-variable guidance in onboarding documentation.

Suggested labels: area: onboarding, feature

Suggested reviewers: apurvvkumaria, cv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the docs-focused starter prompt guidance update.
Linked Issues check	✅ Passed	The changes add the required env vars and Docker sandbox guidance, matching #7311's requirements.
Out of Scope Changes check	✅ Passed	The modified docs and regression test all support the stated starter-prompt guidance work.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-7311-starter-prompt

---

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

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-7328.docs.buildwithfern.com/nemoclaw

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit cfa20b7 in the codex/fix-7311-start... branch remains at 96%, unchanged from commit d3d5171 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit cfa20b7 in the codex/fix-7311-start... branch remains at 80%, unchanged from commit d3d5171 in the main branch.

Show a code coverage summary of the most impacted files.

File	main d3d5171	codex/fix-7311-start... cfa20b7	+/-
src/lib/inferen...time-context.ts	93%	92%	-1%
src/lib/state/g...way-registry.ts	95%	94%	-1%
src/lib/messagi...flow-planner.ts	93%	93%	0%
src/lib/inference/local.ts	80%	80%	0%
src/lib/inferen...lama-version.ts	100%	100%	0%
src/lib/onboard...-patch-clone.ts	94%	94%	0%
src/lib/onboard...er-gpu-route.ts	91%	92%	+1%
src/lib/domain/.../connect-env.ts	89%	97%	+8%
src/lib/onboard...ider-cleanup.ts	88%	100%	+12%
src/lib/onboard...atch-adapter.ts	83%	100%	+17%

---

_{Updated July 21, 2026 18:14 UTC}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: None

1 optional E2E recommendation

• docs-validation

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@test/starter-prompt-docs.test.ts`:
- Around line 495-534: Strengthen the assertions in the starter-prompt
documentation test so they verify the complete non-interactive contract, not
just variable-name presence. In the existing promptSource, quickstartSource,
commandsSource, and updateSource checks, assert the correct
NEMOCLAW_AGENT/NEMOCLAW_PROVIDER pairing, Hermes and Deep Agents assignments,
and CLI precedence wording, while preserving the current negative assertions and
avoiding implementation-specific checks.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 9f21ad78-8964-4b23-96c8-92bb8ae01a1c

📥 Commits

Reviewing files that changed from the base of the PR and between 2ad613d and b1f268e.

📒 Files selected for processing (5)

• docs/get-started/quickstart.mdx
• docs/manage-sandboxes/update-sandboxes.mdx
• docs/reference/commands.mdx
• docs/resources/starter-prompt.md
• test/starter-prompt-docs.test.ts

[cjagwani]

Exact-head maintainer gate passed: all 54 checks green, current base, no conflicts, contributor compliance verified, resolved review feedback, and focused documentation tests cover the supported onboarding contract.