{"owner":"NVIDIA","repo":"NemoClaw","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"files":{"AGENTS.md":"<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->\n<!-- SPDX-License-Identifier: Apache-2.0 -->\n\n# Agent Instructions\n\n## Project Overview\n\nNVIDIA NemoClaw is an open-source reference stack for running always-on AI agents such as [OpenClaw](https://openclaw.ai) and [Hermes](https://get-hermes.ai/) inside [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) sandboxes more safely. It provides CLI tooling, a blueprint for sandbox orchestration, and security hardening.\n\nStatus: Active development. Interfaces may change without notice.\n\n## Product Scope Gate\n\nTechnical correctness, passing tests, and green CI do not establish product approval.\nBefore implementing or approving a change that creates a supported integration, solution recipe, custom image, third-party stack, or other product surface, confirm that an accepted issue or design decision establishes the scope and that ownership, lifecycle, compatibility, security, and validation expectations are defined.\nIf the product decision is missing, do not approve or document the contribution as canonical NemoClaw behavior.\nStop and request maintainer direction, or route an independent solution through [Community Solutions](docs/resources/community-contributions.mdx).\n\n## Agent Skills\n\nThis repo ships agent skills under `.agents/skills/`.\nUse `nemoclaw-user-guide` for end-user documentation routing, `nemoclaw-contributor-*` for contributor workflows, and `nemoclaw-maintainer-*` for maintainer workflows.\nThe contributor lifecycle has one owner for each stage: `nemoclaw-contributor-onboard` for checkout setup, `nemoclaw-contributor-plan-issue` for planning, `nemoclaw-contributor-implement-issue` for implementation and its tests, and `nemoclaw-contributor-create-pr` for publication and review follow-up.\nComponent-specific guidance belongs in the `AGENTS.md` file of the package it describes, not in a skill.\nLoad the `nemoclaw-skills-guide` skill for a full catalog and quick decision guide mapping tasks to skills.\nSkills that write or review explanatory text must follow the shared [Documentation Writing and Review](.agents/skills/_shared/documentation-writing-review.md) contract.\n\n## Architecture\n\n| Path | Language | Purpose |\n|------|----------|---------|\n| `bin/` | JavaScript (CJS) | CLI launcher (`nemoclaw.js`) and small compatibility helpers |\n| `src/lib/` | TypeScript | Core CLI logic: onboard, credentials, inference, policies, preflight, runner |\n| `nemoclaw/` | TypeScript | Plugin registering `/nemoclaw` TUI slash commands inside OpenClaw; `openclaw nemoclaw <cmd>` shell subcommand path is descoped |\n| `nemoclaw/src/blueprint/` | TypeScript | Runner, snapshot, SSRF validation, state management |\n| `nemoclaw/src/commands/` | TypeScript | Slash commands, migration state |\n| `nemoclaw/src/onboard/` | TypeScript | Onboarding config |\n| `nemoclaw-blueprint/` | YAML | Blueprint definition and network policies |\n| `nemoclaw-blueprint/model-specific-setup/` | JSON | Agent-scoped model/provider compatibility registry |\n| `scripts/` | Bash/JS/TS | Install helpers, setup, automation, E2E tooling |\n| `test/` | JavaScript (ESM) | Root-level integration tests (Vitest) |\n| `test/e2e/` | Bash/JS/TS | End-to-end tests, target registry, and live runner (see `test/e2e/README.md`) |\n| `docs/` | MDX/Markdown | User-facing Fern docs and Markdown routes for AI documentation clients |\n| `fern/` | YAML/CSS/SVG | Fern site configuration and shared assets |\n\nPackage-specific guides:\n\n- Messaging architecture and channel migration guidance: [`src/lib/messaging/AGENTS.md`](src/lib/messaging/AGENTS.md)\n\n## Quick Reference\n\n| Task | Command |\n|------|---------|\n| Set up contributor checkout | `npm run dev:setup` |\n| Check contributor environment | `npm run dev:doctor` |\n| Expose development CLI | `./scripts/dev-setup.sh --expose-cli` |\n| Launch pinned coding agent | `npm run agent` |\n| Build plugin | `cd nemoclaw && npm run build` |\n| Watch mode | `cd nemoclaw && npm run dev` |\n| Run all tests for broad changes | `npm test` |\n| Render behavior-oriented test tree | `npm run test:spec` |\n| Run fast source tests | `npm run test:fast` |\n| Run tests affected by current changes | `npm run test:changed` |\n| Watch focused source tests | `npm run test:watch` |\n| Shuffle focused tests without coverage | `npm run test:shuffle` |\n| Diagnose async leaks or shutdown hangs | `npm run test:diagnose:leaks` |\n| Run integration tests | `npm run test:integration` |\n| Run package contracts | `npm run test:package` |\n| Run E2E support tests | `npx vitest run --project e2e-support` |\n| Run live E2E targets | `npm run test:live-e2e` |\n| Run plugin tests | `cd nemoclaw && npm test` |\n| Validate a routine PR diff with `pre-commit`, `commit-msg`, and `pre-push` checks | `npm run validate:pr` |\n| Run the narrow custom repository checks used by lint and hooks | `npm run checks:repository` |\n| Run the broad repo-wide pre-commit and coverage baseline | `npm run check` |\n| Type-check CLI | `npm run typecheck:cli` |\n| Type-check plugin and plugin tests | `npm --prefix nemoclaw run typecheck` |\n| Auto-format added JavaScript and TypeScript files that Oxfmt does not exclude | `npm run format` |\n| Build docs | `npm run docs` |\n| Serve docs locally | `npm run docs:live` |\n\n## Key Architecture Decisions\n\n### Dual-Language Stack\n\n- **CLI and plugin**: TypeScript (`src/`, `nemoclaw/src/`) with a small CommonJS launcher in `bin/`; ESM in `test/`\n- **Blueprint**: YAML configuration (`nemoclaw-blueprint/`)\n- **Docs**: Fern MDX for user-facing pages, with Markdown routes exposed by Fern for AI documentation clients\n- **Tooling scripts**: Bash and Python\n\nThe `bin/` directory uses CommonJS intentionally for the launcher and a few compatibility helpers so the CLI still has a stable executable entry point. The main CLI implementation lives in `src/` and compiles to `dist/`. The `nemoclaw/` plugin uses TypeScript and requires compilation.\n\n### Testing Strategy\n\nTests are organized into disjoint Vitest projects defined in `vitest.config.ts`:\n\n1. **`cli`** — `src/**/*.test.ts` — CLI unit tests importing source\n2. **`integration`** — `test/**/*.test.{js,ts}` — root integration tests importing source; excludes the explicit lanes below\n3. **`installer-integration`** — installer tests that spawn real `install.sh` processes\n4. **`package-contract`** — `test/package-contract/**/*.test.ts` — the only non-live lane that imports compiled CLI/plugin artifacts\n5. **`plugin`** — `nemoclaw/src/**/*.test.ts` — plugin unit tests co-located with source\n6. **`e2e-support`** — fast tests for the E2E fixture/support layer; this project runs in the\n   aggregate checks for code-changing PRs and code-changing pushes to `main`\n7. **`e2e-live`** — opt-in live targets that mutate real external state\n\nWhen writing tests:\n\n- Root-level tests (`test/`) use ESM imports\n- Plugin tests use TypeScript and are co-located with their source files\n- Import CLI source from ordinary tests. Put genuine compiled-artifact assertions under `test/package-contract/`.\n- Keep project globs disjoint and exhaustive; `npm run test:projects:check` compares filesystem candidates with Vitest and rejects missing, overlapping, or unexpected membership.\n- Deterministic projects clear mock calls, restore `vi.spyOn`, and undo `vi.stubEnv` and `vi.stubGlobal` before each test. Create those spies and stubs in `beforeEach` or the test body unless a documented import-time stub must run before module evaluation. Restore direct environment or global mutations yourself, and reset mock implementations explicitly when needed. Live E2E and automatic `mockReset` are intentionally excluded.\n- Use `npm run test:changed` or `npm run test:watch` for focused CLI, plugin, and E2E-support feedback. Add only concrete opaque-input mappings to `test/helpers/vitest-watch-triggers.ts` when the import graph cannot see a YAML, Python, shell, generated, or workflow dependency.\n- Use `npm run test:shuffle -- --sequence.seed=<seed>` to replay a printed test-order seed. Use `npm run test:diagnose:leaks` for async-resource or shutdown-hang diagnostics; both commands keep coverage disabled, and leak diagnostics can accompany exit code 0 when assertions pass.\n- Write behavior-oriented titles, put local issue references in a final `(#1234)` suffix, and use `npm run test:spec` for the hierarchical specification view.\n- Mock external dependencies; don't call real NVIDIA APIs in unit tests\n- E2E tests run on ephemeral Brev cloud instances\n\n### Security Model\n\nNemoClaw isolates agents inside OpenShell sandboxes with:\n\n- Network policies (`nemoclaw-blueprint/policies/`) controlling egress\n- Credential sanitization to prevent leaks\n- SSRF validation (`nemoclaw/src/blueprint/ssrf.ts`)\n- Docker capability drops and process limits\n\nSecurity-sensitive code paths require extra test coverage.\n\n## Code Style and Conventions\n\n### Commit Messages\n\nConventional Commits required. Enforced by commitlint via prek `commit-msg` hook.\n\n```text\n<type>(<scope>): <description>\n```\n\nTypes: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `ci`, `perf`, `merge`\n\n### SPDX Headers\n\nEvery source file must include an SPDX license header. The pre-commit hook auto-inserts them:\n\n```javascript\n// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.\n// SPDX-License-Identifier: Apache-2.0\n```\n\nFor shell scripts use `#` comments. For Markdown use HTML comments.\n\n### JavaScript\n\n- `bin/` launcher and remaining `scripts/*.js`: **CommonJS** (`require`/`module.exports`), Node.js 22.19+\n- `test/`: **ESM** (`import`/`export`)\n- Oxlint uses `oxlint.config.ts`. The isolated `oxlint.type-aware.config.ts` configuration enforces `typescript/no-floating-promises` for plugin sources.\n\n- Use `eslint-plugin-sonarjs` only for the `oxlint.config.ts` cognitive-complexity rules documented in [`tools/lint/DEPENDENCY-REVIEW.md`](tools/lint/DEPENDENCY-REVIEW.md).\n- Keep function complexity low; existing complexity hotspots are tracked separately\n- Unused vars pattern: prefix with `_`\n\n### TypeScript\n\n- Oxlint lints plugin code in `nemoclaw/src/`. Oxfmt formats added plugin files that it does not exclude.\n- CLI type-checking via `tsconfig.cli.json`\n- Plugin production and test type-checking via `npm --prefix nemoclaw run typecheck`, using\n  `nemoclaw/tsconfig.json` and `nemoclaw/tsconfig.test.json`\n\n### Shell Scripts\n\n- ShellCheck enforced (`.shellcheckrc` at root)\n- `shfmt` for formatting\n- All scripts must have shebangs and be executable\n\n### No External Project Links\n\nDo not add links to third-party code repositories, community collections, or unofficial resources. Links to official tool documentation (Node.js and Python) are acceptable.\n\n## Git Hooks (prek)\n\nAll hooks managed by [prek](https://prek.j178.dev/) (installed via `npm install`):\n\n| Hook | What runs |\n|------|-----------|\n| **pre-commit** | Cheap structural and file-local checks, including fixers, formatters, and linters |\n| **commit-msg** | commitlint (Conventional Commits) |\n| **pre-push** | Path-scoped incremental CLI/plugin TypeScript checks and checked-JavaScript checks |\n\n## Working with This Repo\n\n### Before Making Changes\n\n1. Read `CONTRIBUTING.md` for the full contributor guide\n2. Before coding, state what success looks like. Ask only when a choice changes behavior, security, data safety, or a supported contract. Then make the smallest change that works. For a QA-escaped defect, also add the test or diagnostic that should have caught it.\n3. Apply the product scope gate above before implementing or approving a new supported surface\n4. For a first-time checkout, use `.agents/skills/nemoclaw-contributor-onboard/SKILL.md` or run `npm run dev:setup`\n5. Run `npm run dev:doctor` to verify the contributor environment without changing it\n6. Use `./scripts/dev-setup.sh --expose-cli` only with explicit approval for host-visible CLI exposure\n7. Run the tests targeted to the behavior you change once per relevant change set; rerun them after later edits or hook autofixes that can affect that behavior\n\n### Plain Language and Direct Design\n\n- Use existing repository vocabulary and name what a thing does.\n- Remove modifiers that do not distinguish a real current case.\n- Use one name for one concept across issues, code, workflows, checks, logs, tests, and docs.\n- Follow the [NemoClaw Writing Guide](WRITING.md) for every agent response, progress update, tool-call label or description, text published on GitHub, and changed explanatory text.\n  An agent must correct its text before it sends a message, publishes GitHub text, or starts a tool call with a visible label or description. The guide's review policy defines which findings can block changes to existing text.\n- Use the [NemoClaw Controlled Word List](.agents/skills/_shared/controlled-words.md) for approved project terms and exact product names.\n- Do not turn one case into a system of categories or a new abstraction.\n- Do not add configuration, fallback, migration, compatibility, or extension layers without a current requirement. Name the current consumer and the test that protects the contract.\n- Report conclusions and evidence, not an analysis transcript.\n- Stop exploring once the smallest safe solution is clear.\n\n### Git and GitHub Access Failures\n\nFollow `.agents/skills/_shared/git-github-hard-stop.md`: if SSH, `gh`, authentication, authorization, remote access, or push permission fails, stop and ask the user instead of working around access. Do not stop for ordinary merge conflicts or dirty-worktree state; resolve mechanical conflicts in the relevant workflow and ask the user only when resolution would change behavior or contributor intent.\n\n### Pull Request Follow-Up\n\nFollow `.agents/skills/_shared/pr-follow-up.md`: after opening or pushing to a PR, monitor required CI and automated review comments, address valid CodeRabbit and PR Review Advisor findings, and consult the user when feedback is ambiguous or design-changing.\n\nReviewer routing is repository-owned.\nReviewer selection can come from these sources:\n\n- `CODEOWNERS` loaded from the PR base SHA in `NVIDIA/NemoClaw`.\n- Rulesets configured for `NVIDIA/NemoClaw`.\n- NemoClaw workflow definitions loaded from the PR base SHA in `NVIDIA/NemoClaw`.\n- NemoClaw skills loaded from the PR base SHA in `NVIDIA/NemoClaw`.\n\nBefore you use a reviewer-request write, confirm that one of these conditions is true:\n\n- The current user names the exact reviewer.\n- You loaded a NemoClaw workflow definition from the PR base SHA in `NVIDIA/NemoClaw`, and it requires the exact reviewer-request write.\n\nOtherwise, do not use any of these reviewer-request writes:\n\n- Add a reviewer.\n- Remove a reviewer.\n- Re-request a review.\n\nGitHub can create an automatic review-request event when a contributor or agent pushes.\nGitHub can attribute the event to the pushing account.\nIf the command trace contains no reviewer-request write, report the event as an automatic review-request event.\n\n### Common Patterns\n\n**Adding a CLI command:**\n\n- Entry point: `bin/nemoclaw.js` (launches the compiled CLI in `dist/`)\n- Main CLI implementation lives in `src/lib/` and compiles to `dist/lib/`\n- Add tests in `test/`\n\n**Adding a plugin feature:**\n\n- Source: `nemoclaw/src/`\n- Co-locate tests as `*.test.ts`\n- Build with `cd nemoclaw && npm run build`\n\n**Adding a network policy preset:**\n\n- Add YAML to `nemoclaw-blueprint/policies/presets/`\n- Follow existing preset structure (see `slack.yaml`, `discord.yaml`)\n\n**Adding model-specific sandbox compatibility:**\n\n- Add a declarative manifest under `nemoclaw-blueprint/model-specific-setup/<agent>/`\n- Use one `agent` per manifest (`openclaw`, `hermes`, etc.); do not make shared multi-agent manifests\n- Put OpenClaw executable wrappers under `nemoclaw-blueprint/openclaw-plugins/`\n- Put Hermes executable wrappers under `agents/hermes/`\n- Keep `agents/hermes/generate-config.ts` as a thin build-time entrypoint; add Hermes env parsing, config construction, registry handling, and serialization under `agents/hermes/config/`\n- Do not add Hermes behavior for an OpenClaw issue without a Hermes-specific repro or acceptance test\n\n### Gotchas\n\n- `npm install` at root triggers `prek install` which sets up git hooks. If hooks fail, check that `core.hooksPath` is unset: `git config --unset core.hooksPath`\n- The `nemoclaw/` subdirectory has its own `package.json` and `node_modules`.\n  It is a separate npm project that shares the root Oxlint and Oxfmt configuration files.\n- SPDX headers are auto-inserted by pre-commit hooks; don't worry about adding them manually\n- Coverage thresholds are ratcheted in `ci/coverage-threshold-*.json` — new code should not decrease CLI or plugin coverage\n- The `.claude/skills` symlink points to `.agents/skills` — both paths resolve to the same content\n\n## Documentation\n\n- Treat `docs/` as the source of truth for public-facing documentation.\n  Follow the [Documentation Agent Guide](docs/AGENTS.md) for the documentation-agent workflow,\n  including DORI routing.\n- Before completing a code change, determine whether it changes a user-visible surface.\n  This includes a public API, CLI, configuration, UI or front-end behavior, workflow, default, error, or other supported product behavior.\n- When it does and the host supports subagents, start a documentation authoring subagent while the primary agent continues the implementation.\n  Direct it to read `docs/AGENTS.md`, update the affected docs, and run validation.\n  Give it the changed sources and user-visible impact.\n- Reconcile the authoring subagent's documentation changes and validation evidence before completing the implementation.\n  Include the required documentation in the same change.\n- If the host cannot run subagents, read `docs/AGENTS.md` in the primary task, complete the documentation work, and run its documented validation.\n  Do not omit required documentation because parallel execution is unavailable.\n- Before final handoff, a documentation writer subagent must independently review every completed code or documentation change.\n  Give it the changed files, change summary, and test or docs-build evidence.\n  For a documentation-only change, require review of the writing rules and documentation style.\n- If the current host cannot run this reviewer, hand the completed diff and validation evidence to a capable host.\n  If no capable host is available, record the review as `blocked` and do not complete final handoff.\n- After the review, follow the\n  [Documentation Writer Review Receipt](CONTRIBUTING.md#documentation-writer-review-receipt)\n  procedure.\n- During pre-tag release prep, run `nemoclaw-contributor-update-docs` and include the canonical release entry in the release-note docs PR. Create or update `docs/changelog/YYYY-MM-DD.mdx` for `vX.Y.Z` following `docs/CONTRIBUTING.md`; a PR that updates ordinary pages without the dated changelog entry is incomplete. Merge that PR, or record an explicit maintainer waiver, before generating the release plan.\n\n## PR Requirements\n\n- Create feature branch from `main`\n- Let normal `pre-commit`, `commit-msg`, and `pre-push` hooks provide hook verification before submitting\n- Contributor-owned PRs must self-serve the DCO declaration and GitHub commit verification before opening a PR\n- Every contributor-owned PR description must include a valid `Signed-off-by:` declaration for the contributor, and every commit in the PR must appear as `Verified` in GitHub\n- Contributor agents must stop before `gh pr create` if the PR body will not include the DCO declaration or any commit is missing GitHub verification; tell the contributor to fix the issue before opening a PR\n- If force-push is not allowed and an already-published branch contains an unverified commit, require a fresh branch and fresh PR with a clean compliant history\n- Run targeted tests once per relevant change set, rerunning after later behavior-affecting edits or hook autofixes, and run `npm run docs` for doc changes\n- Count successful normal hooks as verification; if hooks were skipped or unavailable, refresh `origin/main` and use `npm run validate:pr`\n- Follow PR template (`.github/PULL_REQUEST_TEMPLATE.md`)\n- PRs that change `scripts/prepare-dgx-station-host.sh` must include reviewable DGX Station test evidence identifying the tested commit, Station profile or scenario, result, and a supporting link. Any maintainer may review the evidence; without acceptable evidence, the PR is not ready to approve or merge. Treat the evidence as human-reviewed, not authenticated hardware provenance. Exceptional bypasses use existing repository governance and must document the reason on the PR.\n- No secrets, API keys, or credentials committed\n- Apply the 10-open-PR limit from `.github/workflows/pr-limit.yaml` only to accounts that the workflow does not exempt\n"}}