docs: update host files and state reference by miyoungc · Pull Request #6605 · NVIDIA/NemoClaw

miyoungc · 2026-07-09T21:06:02Z

Summary

Updates the host-files reference to match current credential and state behavior.
It marks credentials.json as a legacy migration artifact and documents usage-notice.json and the operational state/ directory.

Related Issue

Closes #6555

Changes

Clarify that current releases register provider credentials with the OpenShell gateway and do not create ~/.nemoclaw/credentials.json.
Document the accepted-version record in ~/.nemoclaw/usage-notice.json and its deletion behavior.
Document the operational coordination and history stored under ~/.nemoclaw/state/.

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: 52 focused credential migration and usage-notice tests pass across the integration, CLI, and package-contract projects.
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:
Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

PR description includes the DCO sign-off declaration 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: npx vitest run --project cli --project integration --project package-contract src/lib/actions/sandbox/rebuild-usage-notice.test.ts test/credentials.test.ts test/package-contract/onboard/usage-notice.test.ts passed, 3 files and 52 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) — result: passed with 0 errors; Fern reports the existing repository theme accent-color contrast warning.
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
- Clarified the host-state reference for files stored under ~/.nemoclaw/.
- Updated guidance for legacy credential data, including safer handling and migration instructions.
- Added clearer notes for usage-notice.json and other host JSON files, including whether they can be deleted.
- Documented the ~/.nemoclaw/state/ directory and its role in storing operational history and coordination data.

coderabbitai · 2026-07-09T21:07:11Z

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: 8256ed08-d295-43c3-a2ef-0b93e82ae3b7

📥 Commits

Reviewing files that changed from the base of the PR and between 614122b and 59969ff.

📒 Files selected for processing (1)

docs/reference/host-files-and-state.mdx

📝 Walkthrough

Walkthrough

The host-state reference updates descriptions of shared and sandbox-local state, strengthens sensitive-data warnings, revises credentials.json and usage-notice.json guidance, and documents ~/.nemoclaw/state/.

Changes

Host state documentation

Layer / File(s)	Summary
Update host files and state reference `docs/reference/host-files-and-state.mdx`	Revises page metadata and Deep Agents guidance, broadens warnings for sensitive legacy artifacts, updates `credentials.json` and `usage-notice.json` entries, and documents the non-deletable `~/.nemoclaw/state/` directory.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 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 describes the main doc update to the host files and state reference.
Linked Issues check	✅ Passed	The docs now cover the undocumented credentials.json, usage-notice.json, and state/ behavior requested in `#6555`.
Out of Scope Changes check	✅ Passed	The added guidance stays within the host-files/state documentation scope and matches the issue objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch codex/docs-host-files-state-6555

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

github-actions · 2026-07-09T21:09:25Z

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

github-actions · 2026-07-09T21:09:35Z

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: Add or justify PRA-T1 and any related test follow-ups.
Open items: 0 required · 0 warnings · 0 suggestions · 1 test follow-up

Action checklist

PRA-T1 Add or justify test follow-up: Acceptance clause

Test follow-ups to resolve or justify

If these cover changed behavior, prefer adding them in this PR; otherwise state why existing coverage is enough or link the follow-up.

PRA-T1 Acceptance clause — See NVBug for full reproduction steps and environment details. — add test evidence or identify existing coverage. The linked GitHub issue body contains only this sentence and no comments were returned by the context tool; NVBug content is not available in the repository context. The visible GitHub issue title clauses are covered by the documentation diff.

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

github-actions · 2026-07-09T21:10:17Z

PR Review Advisor (Nemotron Ultra) — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: No advisor follow-up required beyond maintainer review.
Open items: 0 required · 0 warnings · 0 suggestions · 0 test follow-ups
Since last review: 0 prior items resolved · 0 still apply · 0 new items found

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

github-actions · 2026-07-09T21:11:41Z

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

E2E Recommendation Advisor

Failed: Advisor SDK provider error: session: 429 status code (no body); turn: analysis: 429 status code (no body)

github-actions · 2026-07-09T21:11:42Z

E2E Target Recommendation

Required E2E targets: None
Optional E2E targets: None

Workflow run

Full E2E target advisor summary

E2E Target Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E targets

None. Docs-only change outside E2E target-relevant paths; no E2E target dispatch is required.

Optional E2E targets

None.

Relevant changed files

None.

miyoungc · 2026-07-09T21:14:12Z

PRA-1 justification: both PR Review Advisor backends failed before analysis because their SDK sessions received upstream HTTP 429 responses in workflow run 29050227437. Neither backend produced a file-specific finding.

The one-file documentation diff received a manual source-to-doc review against issue #6555 and the current credential migration, usage-notice, and operational-state implementations. A second scoped documentation review corrected precision before the final build. CodeRabbit reported no actionable comments, the focused credential and notice tests pass (3 files, 52 tests), and all required CI, CodeQL, docs-only, and image checks are green. No branch change is appropriate for this advisor infrastructure failure; final maintainer review remains required.

## Summary  Updates the host-files reference to match current credential and state behavior. It marks `credentials.json` as a legacy migration artifact and documents `usage-notice.json` and the operational `state/` directory. ## Related Issue  Closes NVIDIA#6555 ## Changes  - Clarify that current releases register provider credentials with the OpenShell gateway and do not create `~/.nemoclaw/credentials.json`. - Document the accepted-version record in `~/.nemoclaw/usage-notice.json` and its deletion behavior. - Document the operational coordination and history stored under `~/.nemoclaw/state/`. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [ ] Code change with doc updates - [x] Doc only (prose changes, no code sample modifications) - [ ] Doc only (includes code sample changes) ## Quality Gates  - [ ] Tests added or updated for changed behavior - [x] Existing tests cover changed behavior — justification: 52 focused credential migration and usage-notice tests pass across the integration, CLI, and package-contract projects. - [ ] Tests not applicable — justification: - [x] 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: - [ ] Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: ## Verification  - [x] PR description includes the DCO sign-off declaration and every commit appears as `Verified` in GitHub - [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or `npm run check:diff` passed when hooks were skipped or unavailable - [x] Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: `npx vitest run --project cli --project integration --project package-contract src/lib/actions/sandbox/rebuild-usage-notice.test.ts test/credentials.test.ts test/package-contract/onboard/usage-notice.test.ts` passed, 3 files and 52 tests. - [ ] Applicable broad gate passed — `npm test` for broad runtime/test-harness changes; `npm run check` for repo-wide validation/coverage changes — command/result: - [x] Quality Gates section completed with required justifications or waivers - [x] No secrets, API keys, or credentials committed - [ ] `npm run docs` builds without warnings (doc changes only) — result: passed with 0 errors; Fern reports the existing repository theme accent-color contrast warning. - [x] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (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** * Clarified the host-state reference for files stored under `~/.nemoclaw/`. * Updated guidance for legacy credential data, including safer handling and migration instructions. * Added clearer notes for `usage-notice.json` and other host JSON files, including whether they can be deleted. * Documented the `~/.nemoclaw/state/` directory and its role in storing operational history and coordination data.

docs: update host files and state reference

59969ff

miyoungc added the area: docs Documentation, examples, guides, or docs build label Jul 9, 2026

miyoungc self-assigned this Jul 9, 2026

miyoungc added the v0.0.80 label Jul 9, 2026

cv approved these changes Jul 9, 2026

View reviewed changes

cv merged commit e05536c into main Jul 9, 2026
43 of 49 checks passed

cv deleted the codex/docs-host-files-state-6555 branch July 9, 2026 21:42

Navigation Menu

Uh oh!

docs: update host files and state reference - #6605

docs: update host files and state reference#6605
cv merged 1 commit into
mainfrom
codex/docs-host-files-state-6555

miyoungc commented Jul 9, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 9, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

github-actions Bot commented Jul 9, 2026

Uh oh!

github-actions Bot commented Jul 9, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 9, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 9, 2026

E2E Recommendation Advisor

Uh oh!

github-actions Bot commented Jul 9, 2026

E2E Target Advisor

Required E2E targets

Optional E2E targets

Relevant changed files

Uh oh!

miyoungc commented Jul 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

miyoungc commented Jul 9, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Changes

Type of Change

Quality Gates

Verification

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

github-actions Bot commented Jul 9, 2026

Uh oh!

github-actions Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Advisor — No blocking findings

Action checklist

Uh oh!

github-actions Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Advisor (Nemotron Ultra) — No blocking findings

Uh oh!

github-actions Bot commented Jul 9, 2026

E2E Advisor Recommendation

E2E Recommendation Advisor

Uh oh!

github-actions Bot commented Jul 9, 2026

E2E Target Recommendation

E2E Target Advisor

Required E2E targets

Optional E2E targets

Relevant changed files

Uh oh!

miyoungc commented Jul 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

miyoungc commented Jul 9, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 9, 2026 •

edited

Loading

github-actions Bot commented Jul 9, 2026 •

edited

Loading

github-actions Bot commented Jul 9, 2026 •

edited

Loading