NVIDIA · kjw3 · Mar 17, 2026 · Mar 17, 2026 · Mar 17, 2026 · Mar 17, 2026
diff --git a/.../skills/update-docs-from-commits/SKILL.md → .agents/skills/update-docs/SKILL.md b/.../skills/update-docs-from-commits/SKILL.md → .agents/skills/update-docs/SKILL.md
@@ -1,5 +1,5 @@
 ---
-name: update-docs-from-commits
+name: update-docs
 description: Scan recent git commits for changes that affect user-facing behavior, then draft or update the corresponding documentation pages. Use when docs have fallen behind code changes, after a batch of features lands, or when preparing a release. Trigger keywords - update docs, draft docs, docs from commits, sync docs, catch up docs, doc debt, docs behind, docs drift.
 ---
 

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Overview
+
+Define the code of conduct followed and enforced for NemoClaw
+
+### Intended audience
+
+Community | Developers | Project Leads
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting GitHub_Conduct@nvidia.com. All complaints will be reviewed and
+investigated and will result in a response that is deemed necessary and appropriate
+to the circumstances. The project team is obligated to maintain confidentiality with
+regard to the reporter of an incident. Further details of specific enforcement policies
+may be posted separately. 
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,63 +1,128 @@
-# Contributing
+# Contributing to NVIDIA NemoClaw
 
-## Signing Your Work
+Thank you for your interest in contributing to NVIDIA NemoClaw. This guide covers how to set up your development environment, run tests, and submit changes.
 
-* We require that all contributors "sign-off" on their commits. This certifies
-  that the contribution is your original work, or you have rights to submit it
-  under the same license, or a compatible license.
+## Before You Open an Issue
 
-  * Any contribution which contains commits that are not Signed-Off will not be
-    accepted.
+Open an issue when you encounter one of the following situations.
 
-* To sign off on a commit you simply use the `--signoff` (or `-s`) option when
-  committing your changes:
+- A real bug that you confirmed and could not fix.
+- A feature proposal with a design — not a "please build this" request.
+- Security vulnerabilities must follow [SECURITY.md](SECURITY.md) — **not** GitHub issues.
 
-  ```bash
-  git commit -s -m "Add cool feature."
-  ```
+## Prerequisites
 
-  This will append the following to your commit message:
+Install the following before you begin.
 
-  ```text
-  Signed-off-by: Your Name <your@email.com>
-  ```
+- Node.js 20+ and npm 10+
+- Python 3.11+ (for blueprint and documentation builds)
+- Docker (running)
+- [uv](https://docs.astral.sh/uv/) (for Python dependency management)
 
-* Full text of the DCO:
+## Getting Started
 
-  ```text
-    Developer Certificate of Origin
-    Version 1.1
+Install the root dependencies and build the TypeScript plugin:
 
-    Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
-    1 Letterman Drive
-    Suite D4700
-    San Francisco, CA, 94129
+```bash
+# Install root dependencies (OpenClaw + CLI entry point)
+npm install
 
-    Everyone is permitted to copy and distribute verbatim copies of this
-    license document, but changing it is not allowed.
-  ```
+# Install and build the TypeScript plugin
+cd nemoclaw && npm install && npm run build && cd ..
 
-  ```text
-    Developer's Certificate of Origin 1.1
+# Install Python deps for the blueprint
+cd nemoclaw-blueprint && uv sync && cd ..
+```
 
-    By making a contribution to this project, I certify that:
+## Building
 
-    (a) The contribution was created in whole or in part by me and I have the
-    right to submit it under the open source license indicated in the file; or
+The TypeScript plugin lives in `nemoclaw/` and compiles with `tsc`:
 
-    (b) The contribution is based upon previous work that, to the best of my
-    knowledge, is covered under an appropriate open source license and I have
-    the right under that license to submit that work with modifications,
-    whether created in whole or in part by me, under the same open source
-    license (unless I am permitted to submit under a different license), as
-    indicated in the file; or
+```bash
+cd nemoclaw
+npm run build        # one-time compile
+npm run dev          # watch mode
+```
 
-    (c) The contribution was provided directly to me by some other person who
-    certified (a), (b) or (c) and I have not modified it.
+## Main Tasks
 
-    (d) I understand and agree that this project and the contribution are
-    public and that a record of the contribution (including all personal
-    information I submit with it, including my sign-off) is maintained
-    indefinitely and may be redistributed consistent with this project or the
-    open source license(s) involved.
-  ```
+These are the primary `make` and `npm` targets for day-to-day development:
+
+| Task | Purpose |
+|------|---------|
+| `make check` | Run all linters (TypeScript + Python) |
+| `make lint` | Same as `make check` |
+| `make format` | Auto-format TypeScript and Python source |
+| `npm test` | Run root-level tests (`test/*.test.js`) |
+| `cd nemoclaw && npm test` | Run plugin unit tests (Vitest) |
+| `make docs` | Build documentation (Sphinx/MyST) |
+| `make docs-live` | Serve docs locally with auto-rebuild |
+
+## Project Structure
+
+The repository is organized as follows.
+
+| Path | Purpose |
+|------|---------|
+| `nemoclaw/` | TypeScript plugin (Commander CLI, OpenClaw extension) |
+| `nemoclaw-blueprint/` | Python blueprint for sandbox orchestration |
+| `bin/` | CLI entry point (`nemoclaw.js`) |
+| `scripts/` | Install helpers and automation scripts |
+| `test/` | Root-level integration tests |
+| `docs/` | User-facing documentation (Sphinx/MyST) |
+
+## Documentation
+
+If your change affects user-facing behavior (new commands, changed defaults, new features, bug fixes that contradict existing docs), update the relevant pages under `docs/` in the same PR.
+
+If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo includes the `/update-docs` skill that drafts doc updates. Use them before writing from scratch and follow the style guide in [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md).
+
+To build and preview docs locally:
+
+```bash
+make docs       # build the docs
+make docs-live  # serve locally with auto-rebuild
+```
+
+See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for the full style guide and writing conventions.
+
+## Pull Requests
+
+Follow these steps to submit a pull request.
+
+1. Create a feature branch from `main`.
+2. Make your changes with tests.
+3. Run `make check` and `npm test` to verify.
+4. Open a PR.
+
+### Commit Messages
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/). All commit messages must follow the format:
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+**Types:**
+
+- `feat` - New feature
+- `fix` - Bug fix
+- `docs` - Documentation only
+- `chore` - Maintenance tasks (dependencies, build config)
+- `refactor` - Code change that neither fixes a bug nor adds a feature
+- `test` - Adding or updating tests
+- `ci` - CI/CD changes
+- `perf` - Performance improvements
+
+**Examples:**
+
+```
+feat(cli): add --profile flag to nemoclaw onboard
+fix(blueprint): handle missing API key gracefully
+docs: update quickstart for new install wizard
+chore(deps): bump commander to 13.2
+```
diff --git a/README.md b/README.md
@@ -20,13 +20,13 @@ NVIDIA NemoClaw is an open source stack that simplifies running [OpenClaw](https
 
 ## Quick Start
 
-<!-- start-quickstart-guide -->
-
 Follow these steps to get started with NemoClaw and your first sandboxed OpenClaw agent.
 
 > [!NOTE]
 > NemoClaw currently requires a fresh installation of OpenClaw.
 
+<!-- start-quickstart-guide -->
+
 ### Prerequisites
 
 Check the prerequisites before you start to ensure you have the necessary software and hardware to run NemoClaw.
@@ -145,7 +145,7 @@ Run these on the host to set up, connect to, and manage sandboxes.
 | Command                              | Description                                            |
 |--------------------------------------|--------------------------------------------------------|
 | `nemoclaw onboard`                  | Interactive setup wizard: gateway, providers, sandbox. |
-| `nemoclaw deploy <instance>`         | Deploy to a remote GPU instance through Brev.          |
+| `nemoclaw deploy <instance>` (**experimental**)         | Deploy to a remote GPU instance through Brev.          |
 | `nemoclaw <name> connect`            | Open an interactive shell inside the sandbox.          |
 | `openshell term`                     | Launch the OpenShell TUI for monitoring and approvals. |
 | `nemoclaw start` / `stop` / `status` | Manage auxiliary services (Telegram bridge, tunnel).   |

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -8,7 +8,7 @@ If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo inclu
 
 | Skill | What it does | When to use |
 |---|---|---|
-| `update-docs-from-commits` | Scans recent commits for user-facing changes and drafts doc updates. | After landing features, before a release, or to find doc gaps. |
+| `update-docs` | Scans recent commits for user-facing changes and drafts doc updates. | After landing features, before a release, or to find doc gaps. |
 
 The skills live in `.agents/skills/` and follow the style guide below automatically. To use one, ask your agent to run it. For example, ask it to "catch up the docs for everything merged since v0.2.0".
 

diff --git a/docs/deployment/deploy-to-remote-gpu.md b/docs/deployment/deploy-to-remote-gpu.md
@@ -31,6 +31,10 @@ The deploy command provisions the VM, installs dependencies, and connects you to
 
 ## Deploy the Instance
 
+:::{warning}
+The `nemoclaw deploy` command is experimental and may not work as expected.
+:::
+
 Create a Brev instance and run the NemoClaw setup:
 
 ```console

diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.md
@@ -20,6 +20,12 @@ status: published
 
 # Quickstart
 
+Follow these steps to get started with NemoClaw and your first sandboxed OpenClaw agent.
+
+:::{note}
+NemoClaw currently requires a fresh installation of OpenClaw.
+:::
+
 ```{include} ../../README.md
 :start-after: <!-- start-quickstart-guide -->
 :end-before: <!-- end-quickstart-guide -->

diff --git a/docs/reference/commands.md b/docs/reference/commands.md
@@ -114,6 +114,10 @@ $ nemoclaw list
 
 ### `nemoclaw deploy`
 
+:::{warning}
+The `nemoclaw deploy` command is experimental and may not work as expected.
+:::
+
 Deploy NemoClaw to a remote GPU instance through [Brev](https://brev.nvidia.com).
 The deploy script installs Docker, NVIDIA Container Toolkit if a GPU is present, and OpenShell on the VM, then runs the nemoclaw setup and connects to the sandbox.