From fdf547a5231b57347ac08b41cc93716a14aba059 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Thu, 9 Apr 2026 17:58:08 -0700 Subject: [PATCH] docs: catch up documentation for v0.0.11 changes and add docs-skip Update docs for user-facing changes since v0.0.10: remove github from baseline network policy (now opt-in preset), add github/brave/brew to preset tables, update huggingface/npm/pypi descriptions for tightened HTTP rules, and fix binary-scoping example. Add docs/.docs-skip exclusion file and update the contributor update-docs skill with skip-features, skip-terms, and agent matrix filtering to prevent documenting experimental or unreleased features. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../nemoclaw-contributor-update-docs/SKILL.md | 27 +++++++++++++- .../references/best-practices.md | 12 +++--- .../nemoclaw-user-manage-policy/SKILL.md | 3 +- .../references/network-policies.md | 14 ++----- docs/.docs-skip | 37 +++++++++++++++++++ .../customize-network-policy.md | 3 +- docs/reference/network-policies.md | 16 +++----- docs/security/best-practices.md | 12 +++--- 8 files changed, 91 insertions(+), 33 deletions(-) create mode 100644 docs/.docs-skip diff --git a/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md b/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md index 680026ef9d6..af6828f6530 100644 --- a/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md +++ b/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md @@ -18,6 +18,23 @@ Scan recent git history for commits that affect user-facing behavior and draft d - Before a release, to catch any doc gaps. - When a contributor asks "what docs need updating?" +## Step 0: Load the Skip List + +Before scanning commits, read `docs/.docs-skip` if it exists. This file lists features and commits that are merged but should not be documented yet (experimental, under review, etc.). + +```bash +cat docs/.docs-skip +``` + +Parse these sections from the file: + +- `skip-features:` — substring patterns matched against commit messages and changed file paths. Any commit whose message or file list contains a listed string is excluded. +- `skip-terms:` — terms that must never appear in generated documentation. Check all drafted content against this list before writing. If a drafted sentence contains a skip-term, remove that sentence or the entire section. This is a hard gate — no skip-term may appear in any doc output. + +Ignore comment lines (starting with `#`) and inline comments (everything after ` # `). + +Keep the loaded skip list in memory for use throughout the skill execution and the whole documentation process. + ## Step 1: Identify Relevant Commits Determine the commit range. The user may provide one explicitly (e.g., "since v0.1.0" or "last 30 commits"). If not, default to commits since the head of the main branch. @@ -30,11 +47,13 @@ git log v0.1.0..HEAD --oneline --no-merges git log -50 --oneline --no-merges ``` -Filter to commits that are likely to affect docs. Look for these signals: +Filter to commits that are likely to affect docs. Apply every rule below before proceeding. A commit excluded by any rule must not produce doc changes. 1. **Commit type**: `feat`, `fix`, `refactor`, `perf` commits often change behavior. `docs` commits are already doc changes. `chore`, `ci`, `test` commits rarely need doc updates. 2. **Files changed**: Changes to `nemoclaw/src/`, `nemoclaw-blueprint/`, `bin/`, `scripts/`, or policy-related code are high-signal. 3. **Ignore**: Changes limited to `test/`, `.github/`, or internal-only modules. +4. **Skip list**: Exclude any commit whose short hash appears in `skip-commits`, or whose commit message or changed file paths contain a `skip-features` substring. Report skipped commits in the final summary under a "Skipped (docs-skip)" heading. +5. **Agent support matrix**: Do not document agent support (e.g., Claude Code, OpenHands, Goose) unless the agent is listed in the tested agent support matrix in the quickstart or platform docs. Commits that add or modify agent integration code should only produce doc updates for agents already in the matrix. Report excluded agents under "Skipped (not in agent matrix)" in the summary. ```bash # Show files changed per commit to assess impact @@ -83,6 +102,8 @@ Identify where the new content should go. Follow the page's existing structure. ## Step 5: Draft the Update +Before writing, verify that the commit was not excluded in Step 1. Do not draft content for commits matched by the skip list or for agent integrations not in the tested agent support matrix. After drafting, scan the content for any `skip-terms` from `docs/.docs-skip`. Remove any sentence or section that contains a skip-term. If in doubt, skip the commit and report it. + Write the doc update following these conventions: - **Active voice, present tense, second person.** @@ -125,6 +146,9 @@ After drafting all updates, present a summary to the user: ### New pages needed - None (or list any new pages created). +### Skipped (docs-skip) +- `feat(sandbox): add experimental-flag` (abc1234) — matched skip-features: "experimental-flag". + ### Commits with no doc impact - `chore(deps): bump typescript` (abc1234) — internal dependency, no user-facing change. - `test: add launch command test` (def5678) — test-only change. @@ -150,6 +174,7 @@ Check for: - Group related commits that touch the same doc page into a single update rather than making multiple small edits. - If a commit is a breaking change, add a note at the top of the relevant section using a `:::{warning}` admonition. - PRs that are purely internal refactors with no behavior change do not need doc updates, even if they touch high-signal directories. +- To suppress documentation for a merged feature that is not ready for public docs, add it to `docs/.docs-skip`. Remove the entry once the feature is ready to document. ## Example Usage diff --git a/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md b/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md index ae3f9d5c657..47d0db9295e 100644 --- a/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md +++ b/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md @@ -130,7 +130,7 @@ If someone replaces a binary while the sandbox runs, the hash mismatch triggers | Aspect | Detail | |---|---| -| Default | Each endpoint restricts access to specific binaries. For example, only `/usr/bin/gh` and `/usr/bin/git` can reach `github.com`. Binary paths support glob patterns (`*` matches one path component, `**` matches recursively). | +| Default | Each endpoint restricts access to specific binaries. For example, the `github` preset restricts access so only `/usr/bin/gh` and `/usr/bin/git` can reach `github.com`. Binary paths support glob patterns (`*` matches one path component, `**` matches recursively). | | What you can change | Add binaries to an endpoint entry, or omit the `binaries` field to allow any executable. | | Risk if relaxed | Removing binary restrictions lets any process in the sandbox reach the endpoint. An agent could use `curl`, `wget`, or a Python script to exfiltrate data to an allowed host, bypassing the intended usage pattern. | | Recommendation | Always scope endpoints to the binaries that need them. If the agent needs a host from a new binary, add that binary explicitly rather than removing the restriction. | @@ -175,13 +175,15 @@ NemoClaw ships preset policy files in `nemoclaw-blueprint/policies/presets/` for | Preset | What it enables | Key risk | |---|---|---| +| `brave` | Brave Search API. | Agent can issue search queries. | +| `brew` | Homebrew (Linuxbrew) package manager. | Allows installing arbitrary Homebrew packages, which may contain malicious code. | | `discord` | Discord REST API, WebSocket gateway, CDN. | CDN endpoint (`cdn.discordapp.com`) allows GET to any path. WebSocket uses `access: full` (no inspection). | -| `docker` | Docker Hub, NVIDIA container registry. | Allows pulling arbitrary container images into the sandbox. | -| `huggingface` | Hugging Face model registry. | Allows downloading arbitrary models and datasets. | +| `github` | GitHub and GitHub REST API. | Gives agent read/write access to repositories and issues via `gh` and `git`. | +| `huggingface` | Hugging Face Hub (download-only) and inference router. | Allows downloading arbitrary models and datasets. POST is restricted to the inference router only. | | `jira` | Atlassian Jira API. | Gives agent read/write access to project issues and comments. | -| `npm` | npm and Yarn registries. | Allows installing arbitrary npm packages, which may contain malicious code. | +| `npm` | npm and Yarn registries (GET-only). | Allows installing arbitrary npm packages, which may contain malicious code. Publishing is blocked. | | `outlook` | Microsoft 365, Outlook. | Gives agent access to email. | -| `pypi` | Python Package Index. | Allows installing arbitrary Python packages, which may contain malicious code. | +| `pypi` | Python Package Index (GET and HEAD only). | Allows installing arbitrary Python packages, which may contain malicious code. Publishing is blocked. | | `slack` | Slack API, Socket Mode, webhooks. | WebSocket uses `access: full`. Agent can post to any channel the bot token has access to. | | `telegram` | Telegram Bot API. | Agent can send messages to any chat the bot token has access to. | diff --git a/.agents/skills/nemoclaw-user-manage-policy/SKILL.md b/.agents/skills/nemoclaw-user-manage-policy/SKILL.md index 5afa77d859a..844a1184418 100644 --- a/.agents/skills/nemoclaw-user-manage-policy/SKILL.md +++ b/.agents/skills/nemoclaw-user-manage-policy/SKILL.md @@ -146,7 +146,8 @@ Available presets: | `brave` | Brave Search API | | `brew` | Homebrew (Linuxbrew) package manager | | `discord` | Discord webhook API | -| `huggingface` | Hugging Face inference router | +| `github` | GitHub and GitHub REST API | +| `huggingface` | Hugging Face Hub (download-only) and inference router | | `jira` | Atlassian Jira API | | `npm` | npm and Yarn registries | | `outlook` | Microsoft 365 and Outlook | diff --git a/.agents/skills/nemoclaw-user-reference/references/network-policies.md b/.agents/skills/nemoclaw-user-reference/references/network-policies.md index 06048bb1df7..62fc7923473 100644 --- a/.agents/skills/nemoclaw-user-reference/references/network-policies.md +++ b/.agents/skills/nemoclaw-user-reference/references/network-policies.md @@ -43,16 +43,6 @@ The following endpoint groups are allowed by default: - `/usr/local/bin/claude`, `/usr/local/bin/openclaw` - All methods -* - `github` - - `github.com:443` - - `/usr/bin/gh`, `/usr/bin/git` - - All methods, all paths - -* - `github_rest_api` - - `api.github.com:443` - - `/usr/bin/gh` - - GET, POST, PATCH, PUT, DELETE - * - `clawhub` - `clawhub.ai:443` - `/usr/local/bin/openclaw`, `/usr/local/bin/node` @@ -77,6 +67,10 @@ The following endpoint groups are allowed by default: All endpoints use TLS termination and are enforced at port 443. +> **Note:** GitHub access (`github.com`, `api.github.com`) is not included in the baseline policy. +> Apply the `github` preset during onboarding if your agent needs GitHub access. +> See Customize the Network Policy (see the `nemoclaw-user-manage-policy` skill). + ### Inference The baseline policy allows only the `local` inference route. External inference diff --git a/docs/.docs-skip b/docs/.docs-skip new file mode 100644 index 00000000000..5da76cd4b02 --- /dev/null +++ b/docs/.docs-skip @@ -0,0 +1,37 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +# Docs Skip List +# +# Features and commits listed here are excluded from the +# nemoclaw-contributor-update-docs skill. The skill reads this file +# before mapping commits to doc pages and silently skips any match. +# +# Use this when a feature is merged but not ready for public docs +# (experimental, under UX review, pending approval, etc.). +# +# Format +# ------ +# skip-features: substring matches against commit messages and +# changed file paths. Any commit whose message or +# diff file list contains a listed string is skipped. +# +# skip-terms: terms that must never appear in generated docs, +# even if the commit itself is not skipped. The skill +# checks drafted content against this list before +# writing. Use for names, flags, or concepts that +# are not ready for public mention. +# +# Lines starting with '#' are comments. Inline comments after a value +# are supported (everything after ' # ' is ignored). +# +# Remember to remove entries once the feature is ready for docs. + +skip-features: + - "--dangerously-skip-permissions" # experimental flag, pending UX review + - "openclaw-sandbox-permissive.yaml" # permissive policy file, same feature + +skip-terms: + - "dangerously-skip-permissions" # do not mention this flag anywhere in docs + - "permissive mode" # do not reference this concept in docs + - "Hermes" diff --git a/docs/network-policy/customize-network-policy.md b/docs/network-policy/customize-network-policy.md index 737b6bca0d1..bbff7366b91 100644 --- a/docs/network-policy/customize-network-policy.md +++ b/docs/network-policy/customize-network-policy.md @@ -106,7 +106,8 @@ Available presets: | `brave` | Brave Search API | | `brew` | Homebrew (Linuxbrew) package manager | | `discord` | Discord webhook API | -| `huggingface` | Hugging Face inference router | +| `github` | GitHub and GitHub REST API | +| `huggingface` | Hugging Face Hub (download-only) and inference router | | `jira` | Atlassian Jira API | | `npm` | npm and Yarn registries | | `outlook` | Microsoft 365 and Outlook | diff --git a/docs/reference/network-policies.md b/docs/reference/network-policies.md index ac099309a50..5b5efbb45bf 100644 --- a/docs/reference/network-policies.md +++ b/docs/reference/network-policies.md @@ -63,16 +63,6 @@ The following endpoint groups are allowed by default: - `/usr/local/bin/claude`, `/usr/local/bin/openclaw` - All methods -* - `github` - - `github.com:443` - - `/usr/bin/gh`, `/usr/bin/git` - - All methods, all paths - -* - `github_rest_api` - - `api.github.com:443` - - `/usr/bin/gh` - - GET, POST, PATCH, PUT, DELETE - * - `clawhub` - `clawhub.ai:443` - `/usr/local/bin/openclaw`, `/usr/local/bin/node` @@ -97,6 +87,12 @@ The following endpoint groups are allowed by default: All endpoints use TLS termination and are enforced at port 443. +:::{note} +GitHub access (`github.com`, `api.github.com`) is not included in the baseline policy. +Apply the `github` preset during onboarding if your agent needs GitHub access. +See [Customize the Network Policy](../network-policy/customize-network-policy.md). +::: + ### Inference The baseline policy allows only the `local` inference route. External inference diff --git a/docs/security/best-practices.md b/docs/security/best-practices.md index 8e0da270ae6..274c42f28f7 100644 --- a/docs/security/best-practices.md +++ b/docs/security/best-practices.md @@ -150,7 +150,7 @@ If someone replaces a binary while the sandbox runs, the hash mismatch triggers | Aspect | Detail | |---|---| -| Default | Each endpoint restricts access to specific binaries. For example, only `/usr/bin/gh` and `/usr/bin/git` can reach `github.com`. Binary paths support glob patterns (`*` matches one path component, `**` matches recursively). | +| Default | Each endpoint restricts access to specific binaries. For example, the `github` preset restricts access so only `/usr/bin/gh` and `/usr/bin/git` can reach `github.com`. Binary paths support glob patterns (`*` matches one path component, `**` matches recursively). | | What you can change | Add binaries to an endpoint entry, or omit the `binaries` field to allow any executable. | | Risk if relaxed | Removing binary restrictions lets any process in the sandbox reach the endpoint. An agent could use `curl`, `wget`, or a Python script to exfiltrate data to an allowed host, bypassing the intended usage pattern. | | Recommendation | Always scope endpoints to the binaries that need them. If the agent needs a host from a new binary, add that binary explicitly rather than removing the restriction. | @@ -195,13 +195,15 @@ NemoClaw ships preset policy files in `nemoclaw-blueprint/policies/presets/` for | Preset | What it enables | Key risk | |---|---|---| +| `brave` | Brave Search API. | Agent can issue search queries. | +| `brew` | Homebrew (Linuxbrew) package manager. | Allows installing arbitrary Homebrew packages, which may contain malicious code. | | `discord` | Discord REST API, WebSocket gateway, CDN. | CDN endpoint (`cdn.discordapp.com`) allows GET to any path. WebSocket uses `access: full` (no inspection). | -| `docker` | Docker Hub, NVIDIA container registry. | Allows pulling arbitrary container images into the sandbox. | -| `huggingface` | Hugging Face model registry. | Allows downloading arbitrary models and datasets. | +| `github` | GitHub and GitHub REST API. | Gives agent read/write access to repositories and issues via `gh` and `git`. | +| `huggingface` | Hugging Face Hub (download-only) and inference router. | Allows downloading arbitrary models and datasets. POST is restricted to the inference router only. | | `jira` | Atlassian Jira API. | Gives agent read/write access to project issues and comments. | -| `npm` | npm and Yarn registries. | Allows installing arbitrary npm packages, which may contain malicious code. | +| `npm` | npm and Yarn registries (GET-only). | Allows installing arbitrary npm packages, which may contain malicious code. Publishing is blocked. | | `outlook` | Microsoft 365, Outlook. | Gives agent access to email. | -| `pypi` | Python Package Index. | Allows installing arbitrary Python packages, which may contain malicious code. | +| `pypi` | Python Package Index (GET and HEAD only). | Allows installing arbitrary Python packages, which may contain malicious code. Publishing is blocked. | | `slack` | Slack API, Socket Mode, webhooks. | WebSocket uses `access: full`. Agent can post to any channel the bot token has access to. | | `telegram` | Telegram Bot API. | Agent can send messages to any chat the bot token has access to. |