Skip to content

docs: add CONTRIBUTING.md #4079

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Arvuno wants to merge 1 commit into from
Closed

docs: add CONTRIBUTING.md #4079

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 124 additions & 0 deletions 00_STATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
# 00_STATE.md — NemoClaw

@coderabbitai coderabbitai Bot May 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Add the required SPDX license header at the top of the file.

00_STATE.md currently starts directly with the title and is missing the required SPDX copyright/license header.

Suggested fix 
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
 # 00_STATE.md — NemoClaw

As per coding guidelines, "**/*.{js,ts,tsx,jsx,sh,yaml,yml,json,md,mdx}: Every source file must include an SPDX license header for copyright and Apache-2.0 license".

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
# 00_STATE.md — NemoClaw
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->
# 00_STATE.md — NemoClaw
🤖 Prompt for 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.

In `@00_STATE.md` at line 1, Add the required SPDX license header to the top of
00_STATE.md: insert a one-line SPDX copyright/ license declaration (including
SPDX-License-Identifier: Apache-2.0) and a short copyright holder line as the
first lines of the file so the file complies with the repository rule for all
source files.


## Repository Info
- **Upstream**: `NVIDIA/NemoClaw`
- **Fork**: `okwn/NemoClaw` (cloned to `/root/oss-pr-campaign/repos/NemoClaw`)
- **Default branch**: `main`
- **Language**: TypeScript
- **Archived**: No
- **License**: Apache-2.0

## Upstream Stats
- Stars: 20,596 | Forks: 2,714 | Open Issues: 473 | Watchers: 20,596
- Created: 2026-03-15

## Fork Status
- Forked at: 2026-05-22 17:14:06 UTC
- Branches synced: `main` (upstream) + all feature branches (500+ remote branches)
- No local development branches (main only)

## Repository Structure

```
nemoclaw/
├── bin/ # CJS CLI launchers (nemoclaw.js, nemohermes.js)
├── src/ # TypeScript CLI source
│ ├── lib/ # Core CLI logic
│ │ ├── actions/ # Sandbox, credentials, inference actions
│ │ ├── adapters/ # OpenShell, Docker, Gateway adapters
│ │ ├── cli/ # CLI entry point, commands
│ │ ├── cluster-image-patch.ts
│ │ ├── credentials/ # Credential management
│ │ ├── dashboard/ # Dashboard URL handling
│ │ ├── domain/ # Domain models, lifecycle
│ │ ├── gateway-runtime-action.ts
│ │ ├── inference/ # Inference provider config
│ │ ├── onboard/ # Onboarding FSM, providers
│ │ ├── policies/ # Network policy management
│ │ └── state/ # State management, paths
│ └── commands/ # CLI commands (oclif)
├── nemoclaw/ # OpenClaw plugin (Commander CLI extension)
│ └── src/
│ ├── blueprint/ # Runner, snapshot, SSRF validation
│ ├── commands/ # Slash commands, migration state
│ └── onboard/ # Plugin onboarding
├── nemoclaw-blueprint/ # YAML blueprint definition
│ ├── policies/ # Network policy presets
│ ├── model-specific-setup/ # Agent-scoped compatibility
│ ├── router/ # Model router config
│ └── scripts/ # Blueprint scripts (TypeScript)
├── agents/ # Agent definitions (Hermes, OpenClaw)
├── test/ # Root-level integration tests (Vitest/ESM)
│ └── e2e/ # End-to-end tests, scenario runner
├── docs/ # Fern MDX docs + legacy MyST
├── fern/ # Fern site config
├── scripts/ # Bash/JS/TS automation
├── ci/ # CI helper scripts
└── tools/ # Development tools
```

## Package Info
- **Name**: `nemoclaw`
- **Version**: `0.1.0`
- **Node requirement**: `>=22.16.0`
- **Package manager**: npm
- **Key dependencies**: `@oclif/core@^4.10.5`, `js-yaml`, `yaml`, `p-retry`, `@aws-sdk/client-bedrock-runtime`
- **Dev dependencies**: Vitest, Biome, TypeScript, tsx, commitlint

## Build & Test
- **Build**: `npm run build:cli` → TypeScript compiles `src/` to `dist/`, generates oclif manifest
- **Tests**: Vitest (5 projects: cli, installer-integration, plugin, e2e-scenario-framework, e2e-branch-validation)
- **Linting**: Biome + prek hooks (pre-commit, commit-msg, pre-push)
- **Format**: Biome format, shfmt for shell scripts
- **CI**: GitHub Actions (PR, nightly-e2e, sandbox-images, etc.)

## CI/CD Workflows (`.github/workflows/`)
- `pr.yaml` — PR checks, basic-checks, Ollama proxy E2E
- `pr-self-hosted.yaml` — Sandbox image builds on NVIDIA runners
- `main.yaml` — Main branch CI
- `nightly-e2e.yaml` — Nightly E2E test suite
- `e2e-scenarios-all.yaml` — Scenario-based E2E
- `regression-e2e.yaml` — Regression E2E tests
- `brev-nightly-e2e.yaml` — Brev cloud E2E
- `platform-vitest-main.yaml` — Platform-specific Vitest
- `macos-e2e.yaml`, `wsl-e2e.yaml` — Platform E2E
- `base-image.yaml` — Base image builds
- `docs-preview-pr.yaml` — Docs preview for PRs
- `code-scanning.yaml` — CodeQL scanning
- `docker-pin-check.yaml` — Docker image pin validation

## Test Status
```
✓ CLI tests run (selected)
✓ Plugin compilation works
✓ TypeScript compiles cleanly
✓ Build artifact: dist/ + nemoclaw/dist/
```

## Code Quality
- **Linter**: Biome (v2.4.14) + prek hooks
- **Formatter**: Biome + shfmt for shell scripts
- **Type system**: TypeScript strict (multiple tsconfig files)
- **Commit format**: Conventional Commits (enforced via commitlint)
- **SPDX headers**: Required on all source files
- **Shell scripts**: ShellCheck enforced

## Open Issues Summary (473 open)
- **Bug reports**: WSL2/Docker issues, macOS sandbox, DGX Spark GPU
- **Security**: Permission issues (world-readable config), sandbox isolation
- **Policy/Network**: npm/pypi preset restrictions, proxy test behavior
- **Inference**: Ollama local setup, NIM container timeouts, model compatibility
- **Messaging**: Discord Telegram integration issues, channel enrollment
- **E2E**: Nightly test flakiness, OpenClaw version drift, Slack API changes

## Key Observations
1. Very active development (500+ branches, 30 open PRs as of 2026-05-22)
2. Multi-project TypeScript monorepo (root CLI + nemoclaw plugin + blueprint)
3. Strong CI/CD culture — comprehensive E2E, platform-specific tests
4. Messaging subsystem under active VRDC development (workflow planner, manifest compiler)
5. Dual-language stack: TypeScript + YAML blueprint + Bash/Python scripts
6. Agent skills system for user/maintainer/contributor audiences
7. Large feature branch count suggests parallel development streams
8. Active security focus (permissions, sandbox isolation, SSRF validation)
9. OpenShell dependency critical — many issues reference OpenShell version compatibility
10. Brev cloud E2E testing for cloud provisioning validation
266 changes: 266 additions & 0 deletions 01_REPO_MAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,266 @@
# 01_REPO_MAP.md — NemoClaw

@coderabbitai coderabbitai Bot May 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Missing SPDX header in this Markdown source file.

Please add the SPDX copyright/license header before the H1.

As per coding guidelines, "**/*.{js,ts,tsx,jsx,sh,yaml,yml,json,md,mdx}: Every source file must include an SPDX license header for copyright and Apache-2.0 license".

🤖 Prompt for 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.

In `@01_REPO_MAP.md` at line 1, Add the required SPDX copyright/license header for
Apache-2.0 at the top of the Markdown file before the H1; specifically, open the
file that contains the line "# 01_REPO_MAP.md — NemoClaw" and insert the
standardized SPDX header (copyright notice + SPDX-License-Identifier:
Apache-2.0) as the very first lines above the existing H1.


## Repository Hierarchy

```
github.com/NVIDIA/NemoClaw (upstream, org: NVIDIA)
└── fork: github.com/okwn/NemoClaw (user fork)
```

## Branches

### Upstream (`NVIDIA/NemoClaw`)
| Branch | Description |
|--------|-------------|
| `main` | Primary development branch |
| `release/v0.0.7`, `release/v0.0.7.1` | Release branches |
| `docs-*` | Documentation updates |
| `ci-*` | CI/CD improvements |
| `refactor/*` | Large-scale refactoring (100+ branches) |
| `test/*` | Test coverage improvements |
| `fix/*` | Bug fixes |
| `feat/*` | Feature development |
| `worktree-*` | Worktree management |
| `upgrade/*` | Dependency upgrades |
| `u/*` | User branches |
| `revert/*` | Revert branches |
| `automation/*` | Automated sync branches |
| `codex/*` | Codex-assisted branches |
| `autoresearch/*` | Auto research branches |

### Local (`okwn/NemoClaw`)
| Branch | Description |
|--------|-------------|
| `main` | Synced with upstream main |

## Package Structure

### Root Package (`nemoclaw`)
```
nemoclaw (npm package)
├── bin/
│ ├── nemoclaw.js # CLI launcher entry point (CJS)
│ └── nemohermes.js # Hermes alias launcher (CJS)
├── dist/ # Compiled CLI output
├── src/lib/ # TypeScript source → compiled to dist/
├── src/commands/ # oclif command tree → dist/commands/
└── package.json # npm package manifest
```

### Plugin Package (`nemoclaw/`)
```
nemoclaw (oclif plugin)
├── dist/ # Compiled plugin output
├── src/
│ ├── blueprint/ # Runner, snapshot, SSRF, state
│ ├── commands/ # Slash commands, migration
│ └── onboard/ # Onboarding config
├── openclaw.plugin.json # Plugin manifest
└── package.json # Separate npm project
```

### Blueprint Package (`nemoclaw-blueprint/`)
```
nemoclaw-blueprint (YAML config + TS scripts)
├── blueprint.yaml # Main blueprint definition
├── policies/ # Network policy presets
│ └── presets/ # slack.yaml, discord.yaml, etc.
├── model-specific-setup/ # Per-agent compatibility manifests
├── router/ # Model router config
│ └── pool-config.yaml # Model pool definition
├── scripts/ # TypeScript helpers
└── tsconfig.json
```

## Source Code Structure

```
src/
├── lib/
│ ├── actions/ # Domain actions
│ │ ├── dev/ # npm link/shim actions
│ │ ├── sandbox/ # Sandbox lifecycle (create/destroy/rebuild)
│ │ └── skill-install.ts
│ ├── adapters/ # External system adapters
│ │ ├── openshell-adapter.ts
│ │ ├── docker-adapter.ts
│ │ └── gateway-adapter.ts
│ ├── cli/
│ │ └── index.ts # CLI entry point
│ ├── cluster-image-patch.ts
│ ├── credentials/ # Credential registry & sanitization
│ │ ├── registry.ts
│ │ └── sanitize.ts
│ ├── dashboard/ # Dashboard URL handling
│ ├── deploy/ # Deployment actions
│ ├── diagnostics/ # Diagnostic tools
│ ├── domain/ # Domain models
│ │ └── lifecycle/ # Lifecycle state machines
│ ├── inference/ # Inference provider config
│ │ ├── config.ts
│ │ ├── local.ts # Ollama, vLLM
│ │ └── nim.ts # NVIDIA NIM
│ ├── onboard/ # Onboarding FSM
│ │ ├── index.ts # Main onboarding orchestrator
│ │ ├── machine/ # State machine transitions
│ │ ├── providers.ts # Provider selection
│ │ └── docker-driver-gateway-env.ts
│ ├── policies/ # Network policy management
│ ├── state/ # State persistence
│ │ └── paths.ts # Path resolution
│ ├── messaging/ # Messaging channel integration
│ └── hermes-provider-auth.ts
│
└── commands/ # oclif command tree
├── onboard.ts
├── connect.ts
├── status.ts
├── logs.ts
├── rebuild.ts
├── destroy.ts
├── list.ts
├── inference/
│ ├── get.ts
│ └── set.ts
├── policy/
├── channels/
├── debug.ts
└── internal/
├── installer/
│ └── plan.ts
└── ...

nemoclaw/src/
├── blueprint/
│ ├── runner.ts # Sandbox runner
│ ├── snapshot.ts # Snapshot create/restore
│ ├── ssrf.ts # SSRF validation
│ └── state.ts # Blueprint state
├── commands/
│ ├── index.ts # Slash command registry
│ └── migrate.ts # Migration handling
├── onboard/
│ └── config.ts # Onboarding configuration
└── package-metadata.ts

nemoclaw-blueprint/
├── blueprint.yaml # Root blueprint YAML
├── private-networks.yaml # Private network config
├── policies/ # Policy definitions
│ ├── allowlisting/ # Allowlist rules
│ ├── presets/ # Preset policies
│ └── denylisting/ # Denylist rules
├── model-specific-setup/ # Per-model configuration
│ ├── openclaw/ # OpenClaw agent setup
│ └── hermes/ # Hermes agent setup
├── router/ # LLM router config
├── scripts/ # Blueprint TypeScript helpers
└── openclaw-plugins/ # OpenClaw plugin wrappers
```

## Test Structure

```
test/ # Root-level ESM tests (Vitest)
├── cli.test.ts
├── cli-oclif-compatibility.test.ts
├── install-preflight.test.ts # Slow, opt-in
├── install-openshell-version-check.test.ts # Slow, opt-in
├── seed-wechat-accounts.test.ts
├── generate-openclaw-config.test.ts
├── sandbox-build-context.test.ts
├── openclaw-tool-catalog-patch.test.ts
├── openclaw-tui-chat-correlation.test.ts
├── fetch-guard-patch-regression.test.ts
├── preinstall-node-version.test.ts
└── e2e/
├── test-cloud-inference-e2e.sh
├── test-skill-agent-e2e.sh
├── test-cloud-onboard-e2e.sh
├── test-docs-validation.sh
├── test-rebuild-openclaw.sh
├── test-openclaw-slack-pairing.sh
├── brev-e2e.test.ts # Cloud E2E (opt-in)
├── scenario-framework-tests/
│ └── e2e-lib-helpers.test.ts
└── lib/
└── slack-api-proof.sh

nemoclaw/src/ # Plugin unit tests (TypeScript, co-located)
├── package-metadata.test.ts
└── [co-located with source as *.test.ts]

vitest.config.ts # Root Vitest config (5 projects)
nemoclaw/vitest.config.ts # Plugin Vitest config
```

## Key Files

| File | Purpose |
|------|---------|
| `package.json` | Root package manifest (nemoclaw CLI) |
| `nemoclaw/package.json` | Plugin package manifest |
| `nemoclaw-blueprint/blueprint.yaml` | Blueprint definition |
| `vitest.config.ts` | Root Vitest configuration |
| `biome.json` | Biome linter/formatter config (shared) |
| `AGENTS.md` | Agent instructions and architecture docs |
| `CONTRIBUTING.md` | Contributing guidelines |
| `Makefile` | Make targets (check, lint, format, docs) |
| `install.sh` | Installer script |
| `uninstall.sh` | Uninstaller script |
| `Dockerfile` | Container build definition |
| `tsconfig.src.json` | CLI TypeScript config |
| `tsconfig.cli.json` | CLI type-check config |
| `jsconfig.json` | JS project references |
| `.github/workflows/*.yaml` | GitHub Actions workflows |
| `fern/fern.config.json` | Fern docs config |
| `pyproject.toml` | Python project config (uv) |

## Agent Skills

```
.agents/skills/
├── nemoclaw-user-* # End user skills
├── nemoclaw-maintainer-* # Project maintainer skills
└── nemoclaw-contributor-* # Codebase contributor skills
```

Load via `nemoclaw-skills-guide` skill for full catalog.

## Network Policy Presets

```
nemoclaw-blueprint/policies/presets/
├── slack.yaml
├── discord.yaml
├── brave.yaml
├── pypi.yaml
├── npm.yaml
└── [more platform-specific presets]
```

## Credentials System

- Registry at `~/.nemoclaw/credentials/` (or equivalent state dir)
- Sanitization layer prevents credential leakage to sandbox
- Provider credentials: NVIDIA NIM, Ollama, OpenAI, Anthropic, Bedrock, etc.

## Inference Providers

- `nvidia` — NVIDIA NIM endpoints
- `openai` — OpenAI compatible
- `anthropic` — Anthropic
- `bedrock` — AWS Bedrock
- `ollama` — Local Ollama
- `ollama-local` — Local Ollama with full features
- `vllm` — vLLM local
- `routed` — Model router (experimental, NVIDIA LLM Router v3)

## Platform Support Matrix

| OS | Runtime | Status |
|----|---------|--------|
| Linux | Docker | Primary |
| macOS (Apple Silicon) | Colima, Docker Desktop | Tested (limitations) |
| DGX Spark | Docker | Tested |
| Windows WSL2 | Docker Desktop (WSL backend) | Tested (limitations) |
Loading