From 926f59e6671186221a5dbc0d601bec087789ac8d Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Thu, 30 Jul 2026 15:14:52 -0700 Subject: [PATCH 1/8] docs: address post-tag audit findings --- .gitignore | 1 + AGENTS.md | 62 +- docs/AGENTS.md | 8 +- docs/DORI_SETUP.md | 14 +- .../quickstart-langchain-deepagents-code.mdx | 148 +---- docs/index.yml | 48 ++ .../manage-sandboxes/run-deep-agents-code.mdx | 193 ++++++ docs/reference/commands.mdx | 7 +- docs/reference/troubleshooting.mdx | 20 + .../automate-documentation-workflows.mdx | 169 +++++ .../design-agent-ready-documentation.mdx | 159 +++++ .../engineer-agentic-documentation.mdx | 604 ------------------ .../generate-documentation-variants.mdx | 184 ++++++ .../govern-agentic-documentation.mdx | 157 +++++ .../hermes-0.19.0-dependency-review.md | 3 +- test/check-docs-published-routes.test.ts | 58 ++ 16 files changed, 1032 insertions(+), 803 deletions(-) create mode 100644 docs/manage-sandboxes/run-deep-agents-code.mdx create mode 100644 docs/resources/automate-documentation-workflows.mdx create mode 100644 docs/resources/design-agent-ready-documentation.mdx delete mode 100644 docs/resources/engineer-agentic-documentation.mdx create mode 100644 docs/resources/generate-documentation-variants.mdx create mode 100644 docs/resources/govern-agentic-documentation.mdx diff --git a/.gitignore b/.gitignore index 9abc41fed2..afda410960 100644 --- a/.gitignore +++ b/.gitignore @@ -19,6 +19,7 @@ Thumbs.db # Project-specific .nemoclaw-maintainer/ +# Legacy DORI status file; no longer read, kept ignored to prevent accidental commits. .dori_user_status draft_newsletter_* research/ diff --git a/AGENTS.md b/AGENTS.md index c052d60aa2..3dd7c2425b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -297,46 +297,28 @@ If the command trace contains no reviewer-request write, report the event as an ### NVIDIA DORI Routing -Use the ignored `.dori_user_status` file at the repository root to select the -documentation path. The file can contain only one line: `authorized` or -`external`. - -1. Read `.dori_user_status` before checking for DORI. - - If the value is `external`, use the - [Writing Style Guide](docs/AGENTS.md#writing-style-guide) without checking - DORI. - - If the value is `authorized`, continue to step 2. - - If the file is absent or invalid, ask the user to select one of these - options. Use selectable options when the host supports them. Otherwise, - present the numbered list: - - 1. Select `authorized` if you are an NVIDIA employee or authorized - contractor with access to `gitlab-master.nvidia.com`. - 2. Select `external` for all other contributors. - - - Normalize an unambiguous response and write only the corresponding - lowercase value to `.dori_user_status`. - - Store `authorized` for option 1, `1`, `authorized`, or a response that - clearly selects `authorized`, such as `yes, authorized`. - - Store `external` for option 2, `2`, `external`, or a response that - clearly selects `external`. - - If the response is ambiguous, selects both options, or does not select - either option, ask again and do not write the file. - - If the user declines to answer or store a value, do not create the file. - Use the [Writing Style Guide](docs/AGENTS.md#writing-style-guide). - - Tell the user that deleting `.dori_user_status` resets the choice. -2. Only after an `authorized` value, check whether the current agent exposes - `dori_handle` or `dori_route`. - - If DORI is available, use it for task routing. When `dori_collections` is - available, verify that a collection source contains - `tech-docs/skill-library`. - - If DORI is unavailable or the Skill Library is missing, follow - [NVIDIA DORI Setup](docs/DORI_SETUP.md). - -The stored value does not prove access or approve installation or host -configuration. Use the -[Writing Style Guide](docs/AGENTS.md#writing-style-guide) if setup is declined -or fails. +Select the documentation path from current host capabilities. +Do not ask the user to classify themselves or store repository-scoped identity +state during a normal documentation task. + +1. Check whether the current agent exposes `dori_handle` or `dori_route` and + `dori_collections`. + If the user explicitly asks not to use DORI, use the + [Writing Style Guide](docs/AGENTS.md#writing-style-guide) instead. +2. When those tools are available, list the installed collections. + - If a collection source contains `tech-docs/skill-library`, use DORI for + task routing. + - If the collection is missing, inaccessible, or cannot be verified, + continue with the + [Writing Style Guide](docs/AGENTS.md#writing-style-guide). +3. When the DORI tools are unavailable, continue with the Writing Style Guide. + Do not inspect a shell-visible CLI, install software, or configure the host + during a normal documentation task. +4. Use [NVIDIA DORI Setup](docs/DORI_SETUP.md) only when the user explicitly + asks to install or configure DORI. + +Capability detection does not approve installation or host configuration. +DORI unavailability must not block documentation work. ## PR Requirements diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 26d6c105e0..c032e359ff 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -75,9 +75,9 @@ Apply these rules to documentation, examples, headings, UI text, and release not ## Use DORI for Complete NVIDIA Doc Tools -Follow [NVIDIA DORI Routing](../AGENTS.md#nvidia-dori-routing) before checking for DORI. -Only an `authorized` value can select the DORI path. -When root routing selects that path, you can use DORI for additional documentation tools. +Follow [NVIDIA DORI Routing](../AGENTS.md#nvidia-dori-routing). +Use DORI only when current host capabilities include the verified NVIDIA documentation Skill Library. +Do not ask for or persist a user classification during a normal documentation task. Complete the documentation before the developer opens the pull or merge request. 1. Route the documentation task through DORI. Include the changed source files, @@ -91,7 +91,7 @@ Complete the documentation before the developer opens the pull or merge request. 4. When the host does not support subagents, complete the same documentation work in the primary task. -If root routing directs you to the Writing Style Guide, or if DORI is unavailable, inaccessible, declined, or fails, do not block the change. +If the verified Skill Library is unavailable, inaccessible, or fails, do not block the change or prompt for setup. Continue using the Writing Style Guide above. ## Before Editing diff --git a/docs/DORI_SETUP.md b/docs/DORI_SETUP.md index 5b36a7fec3..32d773940f 100644 --- a/docs/DORI_SETUP.md +++ b/docs/DORI_SETUP.md @@ -5,10 +5,10 @@ # NVIDIA DORI Setup -Use this guide only after the root `AGENTS.md` reads an `authorized` value from `.dori_user_status`. -The stored value does not prove private access or approve installation or host configuration. - -If the status is not `authorized`, stop this setup and use the checked-in [Writing Style Guide](AGENTS.md#writing-style-guide). +Use this guide only when the user explicitly asks to install or configure NVIDIA DORI. +Before inspecting or installing private components, ask the user to confirm that they can access `gitlab-master.nvidia.com`. +If the user does not confirm access, stop this setup and use the checked-in [Writing Style Guide](AGENTS.md#writing-style-guide). +Access confirmation does not approve installation or host configuration. ## Inspect the Environment @@ -50,7 +50,7 @@ Before an installation or host configuration change, ask: > Do you want me to install or configure these components in your user environment? Continue only after explicit approval. -An `authorized` status does not approve these changes. +The user's private-source access confirmation does not approve these changes. If the user declines, use the [Writing Style Guide](AGENTS.md#writing-style-guide). ## Install Missing Components @@ -103,8 +103,8 @@ Until the current agent exposes DORI tools, continue the original task with the - Never search for, request, print, copy, export, or embed a token, password, cookie, SSH key, or credential-bearing URL. - Let `uv`, Git, and DORI use credentials that the user already configured. If access is denied or authentication is missing, stop and refer to the internal DORI installation guide. -- Never stage or commit `.dori_user_status`. - Do not treat its value as proof of employment, authorization, or current private access. +- Do not create repository-scoped identity or authorization files. + Confirm private-source access only for an explicit setup request. - Do not bypass approval controls for writes outside the repository. - Do not create or commit project-scoped DORI state or MCP configuration without separate repository-owner authorization. - Do not retry a failed installation in the same task. diff --git a/docs/get-started/quickstart-langchain-deepagents-code.mdx b/docs/get-started/quickstart-langchain-deepagents-code.mdx index 36f3b6acd6..4205769893 100644 --- a/docs/get-started/quickstart-langchain-deepagents-code.mdx +++ b/docs/get-started/quickstart-langchain-deepagents-code.mdx @@ -133,150 +133,9 @@ The image includes `ripgrep`, and ordinary sessions suppress the optional Tavily - -### Choose the Default Sandbox - -When you manage multiple sandboxes, use the Deep Agents alias to promote a registered Deep Agents Code sandbox to the default. - -```bash -nemo-deepagents use -``` - -The command updates NemoClaw's host-side registry. -It does not modify the sandbox or the `dcode` configuration. - -### Use the Harness - -Connect to the sandbox, then launch the terminal UI. - -```bash -nemoclaw connect -dcode -``` - -For a single headless task, run: - -```bash -dcode -n "Summarize this repository" -``` - -For automation, add `--json`. -The managed runtime writes exactly one UTF-8 JSON object to stdout and suppresses other stdout text. -Progress is suppressed. -Warnings and diagnostics go to stderr. - -```bash -dcode -n "Summarize this repository" --json -``` - -A successful run has this version 1 envelope: - -```json -{ - "schema_version": 1, - "command": "non-interactive", - "data": { - "status": "success", - "exit_code": 0, - "response": "The repository contains...", - "completion": { - "thread_id": "thread-id", - "duration_ms": 842, - "response_bytes": 26 - } - } -} -``` - -`response` contains the exact final assistant text on success and is `null` on failure. -`response_bytes` is its UTF-8 byte length on success and is `0` on failure. -The process exit code matches `data.exit_code`. -The terminal statuses are `success`, `agent_failure`, `process_failure`, `timeout`, `turn_limit`, `cancelled`, and `output_limit`. -A timeout exits `124`, cancellation exits `130`, and other failures exit nonzero. - -The complete serialized envelope is limited to 1 MiB. -If the response cannot fit, the runtime discards it and emits a bounded `output_limit` failure envelope. -If it cannot write the envelope, the command exits nonzero and reports the write failure on stderr; callers must reject empty, malformed, additional, or unsupported-version stdout. - -The managed `dcode`, `dcode.real`, and `deepagents-code` launchers use `/opt/venv/bin/python3 -I` to run the pinned package with an isolated import path and `HOME=/sandbox`. -For interactive and headless sessions, each launcher supervises its own process descendants so completion, terminal exit, or disconnect terminates the associated LangGraph server tree without affecting another session. -After a disconnect, the supervisor uses bounded grace periods before it kills unresponsive processes from that session. -The supervisor runs inside the Linux OpenShell sandbox and fails closed if invoked outside Linux; the host operating system does not change this sandbox guarantee. -They disable Deep Agents Code package update checks and the LangGraph server version check, block CLI and TUI update/install commands, and disable nested remote sandbox providers, remote async subagents, MCP commands and project auto-loading, startup commands, executable hooks, ACP mode, interpreter tool calling, shell allow-list overrides, native LangSmith tracing, and ambient OpenTelemetry exporter configuration. -The managed model constructor accepts only Deep Agents Code's `openai` provider path and reads its endpoint from a root-owned image file. -It supplies the non-secret gateway placeholder key and ignores mutable provider classes, credentials, endpoints, and constructor parameters in Deep Agents Code config. -CLI and TUI model parameter overrides and custom rubric models are blocked. -For headless runs, `--max-retries` remains available after Deep Agents Code validates the retry count. -The managed boundary discards every other model parameter, including credentials, endpoints, and provider settings. -Project and user-defined subagents remain available, but they inherit the managed chat model instead of accepting their own model override. -MCP servers registered through `nemoclaw mcp add` remain available through NemoClaw's dedicated `/sandbox/.deepagents/.nemoclaw-mcp.json` projection and OpenShell egress policy. -Project and user MCP files are never auto-loaded. -Sandboxes with the older managed MCP v1 runtime must rebuild before `mcp add` or `mcp restart`; remove, rebuild, and destroy can still scrub exact registry-owned legacy entries without claiming unrelated user content. -Before launch, NemoClaw validates and canonicalizes the complete managed file as HTTPS-only definitions with exact OpenShell credential placeholders, then gives Deep Agents Code a process-local, integrity-bound snapshot for server starts and restarts. -It prefers a sealed in-memory file when available; the OpenShell-compatible anonymous read-only descriptor fallback verifies the inode, size, and SHA-256 digest and fails closed on drift. -Stdio commands, extra headers, raw credentials, and unrelated top-level configuration fail closed. -For authenticated MCP setup and credential rotation, see [Add an MCP Server](../manage-sandboxes/mcp-servers/add-an-mcp-server) and [Manage MCP Servers](../manage-sandboxes/mcp-servers/manage-mcp-servers). -This isolated-mode guarantee applies to those managed launchers, not arbitrary Python commands in the sandbox. - -Interactive shell execution and other destructive tools remain behind human-in-the-loop approval prompts by default. -Thread-wide auto-approval is unavailable unless you enable the managed thread opt-in capability, and shell allow-list auto-approval remains disabled. -Headless `dcode -n` is an explicit automation boundary. -It has no approval UI and automatically approves non-shell tool requests, including file writes and edits. -The managed headless path still disables shell execution, startup commands, interpreter tool calling, executable hooks, unmanaged MCP configuration, nested remote sandboxes, remote async subagents, and alternate model routes. -Use the interactive TUI when you need to inspect each destructive tool request before it runs. - -#### Configure Thread Auto-Approval - -Managed Deep Agents sandboxes keep interactive thread auto-approval disabled by default. -In this mode, the TUI auto-approval choice and `dcode -y` fail closed. - -Enable the capability for a named sandbox through a transactional rebuild because NemoClaw bakes the capability into the managed image. - -```bash -nemo-deepagents rebuild --dcode-auto-approval thread-opt-in --yes -``` - -The `thread-opt-in` setting grants permission to activate auto-approval, but it does not activate auto-approval by itself. -For each thread, select **Auto-approve for this thread** in the approval menu or start that `dcode` process with `dcode -y`. -The TUI shows the upstream active-state indicator and a warning while the current thread can run tool calls, including shell commands, without further confirmation. - -NemoClaw resets the active state when you start a new `dcode` process, run `/clear` or `/force-clear`, switch or resume a different thread, or switch agents. -You must opt in again after each reset. -The host-side status command reports the configured capability, not whether one live TUI thread currently has auto-approval active. - -```bash -nemo-deepagents status -``` - -Thread auto-approval does not bypass OpenShell network policy, credential isolation, the managed inference route, managed MCP validation, or the other Deep Agents runtime restrictions described above. -Headless `dcode -n` remains a separate automation boundary with non-shell auto-approval and managed shell execution disabled. - -Return the sandbox to the default posture with another transactional rebuild. - -```bash -nemo-deepagents rebuild --dcode-auto-approval disabled --yes -``` - -To confirm which sandbox a session is in, run the identity command: - -```bash -dcode status -``` - -The command prints the sandbox name, NemoClaw harness, active `dcode` agent, configured inference route, upstream provider, model, endpoint, and runtime, then exits without starting the interactive UI. -`dcode whoami` and `dcode identity` are aliases. -`dcode --help` lists the managed aliases before the upstream Deep Agents Code help. -The sandbox name resolves when you run the command from a `nemoclaw connect` shell, which loads the NemoClaw runtime environment. - -Inspect the generated Deep Agents configuration from the host with: - -```bash -nemo-deepagents config get -``` - -NemoClaw parses `config.toml`, removes gateway auth data, and redacts credential-shaped values before printing it. -`config set` is not supported for this image-baked configuration; re-onboard the named sandbox to change its managed provider or model selection. - + + + Continue with [Run Deep Agents Code](../manage-sandboxes/operate-sandboxes/run-deep-agents-code) for sandbox selection, interactive and headless tasks, the JSON output contract, runtime restrictions, thread auto-approval, and identity checks. @@ -402,6 +261,7 @@ There is no dashboard port or long-running gateway process for this harness. ## Next Steps +- [Run Deep Agents Code](../manage-sandboxes/operate-sandboxes/run-deep-agents-code) explains interactive and headless operation, automation output, and approval boundaries. - [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) explains how to choose a provider and model. - [Understand Sandbox State](../manage-sandboxes/state-and-backups/understand-sandbox-state) explains `/sandbox/.deepagents`, memory, skills, and what NemoClaw preserves. - [Create and Restore Snapshots](../manage-sandboxes/state-and-backups/create-and-restore-snapshots) explains snapshot and rebuild preservation. diff --git a/docs/index.yml b/docs/index.yml index 9abc8f647d..a1ac3bbe39 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -406,6 +406,21 @@ navigation: - page: "Community Solutions" path: _build/agent-variants/resources/community-contributions.openclaw.generated.mdx slug: community-contributions + - section: "Documentation Engineering" + slug: documentation-engineering + contents: + - page: "Design Agent-Ready Documentation" + path: _build/agent-variants/resources/design-agent-ready-documentation.openclaw.generated.mdx + slug: design-agent-ready-documentation + - page: "Automate Documentation Workflows" + path: _build/agent-variants/resources/automate-documentation-workflows.openclaw.generated.mdx + slug: automate-documentation-workflows + - page: "Generate Documentation Variants" + path: _build/agent-variants/resources/generate-documentation-variants.openclaw.generated.mdx + slug: generate-documentation-variants + - page: "Govern and Evaluate Agentic Documentation" + path: _build/agent-variants/resources/govern-agentic-documentation.openclaw.generated.mdx + slug: govern-agentic-documentation - link: "Discord" href: https://discord.gg/XFpfPv9Uvx - link: "Report Vulnerabilities" @@ -575,6 +590,9 @@ navigation: - page: "Run Sandboxes" path: _build/agent-variants/manage-sandboxes/run-sandboxes.deepagents.generated.mdx slug: run-sandboxes + - page: "Run Deep Agents Code" + path: manage-sandboxes/run-deep-agents-code.mdx + slug: run-deep-agents-code - page: "Recover and Rebuild Sandboxes" path: _build/agent-variants/manage-sandboxes/recover-rebuild-sandboxes.deepagents.generated.mdx slug: recover-and-rebuild-sandboxes @@ -719,6 +737,21 @@ navigation: - page: "Community Solutions" path: _build/agent-variants/resources/community-contributions.deepagents.generated.mdx slug: community-contributions + - section: "Documentation Engineering" + slug: documentation-engineering + contents: + - page: "Design Agent-Ready Documentation" + path: _build/agent-variants/resources/design-agent-ready-documentation.deepagents.generated.mdx + slug: design-agent-ready-documentation + - page: "Automate Documentation Workflows" + path: _build/agent-variants/resources/automate-documentation-workflows.deepagents.generated.mdx + slug: automate-documentation-workflows + - page: "Generate Documentation Variants" + path: _build/agent-variants/resources/generate-documentation-variants.deepagents.generated.mdx + slug: generate-documentation-variants + - page: "Govern and Evaluate Agentic Documentation" + path: _build/agent-variants/resources/govern-agentic-documentation.deepagents.generated.mdx + slug: govern-agentic-documentation - link: "Report Vulnerabilities" href: https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md - page: "License" @@ -1098,6 +1131,21 @@ navigation: - page: "Community Solutions" path: _build/agent-variants/resources/community-contributions.hermes.generated.mdx slug: community-contributions + - section: "Documentation Engineering" + slug: documentation-engineering + contents: + - page: "Design Agent-Ready Documentation" + path: _build/agent-variants/resources/design-agent-ready-documentation.hermes.generated.mdx + slug: design-agent-ready-documentation + - page: "Automate Documentation Workflows" + path: _build/agent-variants/resources/automate-documentation-workflows.hermes.generated.mdx + slug: automate-documentation-workflows + - page: "Generate Documentation Variants" + path: _build/agent-variants/resources/generate-documentation-variants.hermes.generated.mdx + slug: generate-documentation-variants + - page: "Govern and Evaluate Agentic Documentation" + path: _build/agent-variants/resources/govern-agentic-documentation.hermes.generated.mdx + slug: govern-agentic-documentation - link: "Report Vulnerabilities" href: https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md - page: "License" diff --git a/docs/manage-sandboxes/run-deep-agents-code.mdx b/docs/manage-sandboxes/run-deep-agents-code.mdx new file mode 100644 index 0000000000..21273e96b5 --- /dev/null +++ b/docs/manage-sandboxes/run-deep-agents-code.mdx @@ -0,0 +1,193 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Run LangChain Deep Agents Code" +sidebar-title: "Run Deep Agents Code" +description: "Run interactive and headless Deep Agents Code tasks inside a NemoClaw sandbox." +description-agent: "Explains how to select a Deep Agents sandbox, run dcode interactively or headlessly, consume the managed JSON envelope, understand runtime restrictions, configure thread auto-approval, and inspect runtime identity. Use when operating an existing Deep Agents Code sandbox." +keywords: ["run deep agents code", "dcode json", "dcode auto approval", "deep agents runtime"] +topics: ["manage-sandboxes", "terminal-runtime", "langchain-deepagents-code", "automation"] +tags: ["deep-agents-code", "dcode", "managed-runtime"] +difficulty: "intermediate" +audience: "operators" +status: published +content: + type: "how_to" +agent-variants: ["deepagents"] +--- + +Use the managed `dcode` launchers to run interactive or headless work inside an existing Deep Agents Code sandbox. +Complete [Quickstart with Deep Agents](../../get-started/quickstart) before you use these operating workflows. + +## Choose the Default Sandbox + +When you manage multiple sandboxes, use the Deep Agents alias to promote a registered Deep Agents Code sandbox to the default: + +```bash +nemo-deepagents use +``` + +The command updates NemoClaw's host-side registry. +It does not modify the sandbox or the `dcode` configuration. + +## Run Interactive or Headless Tasks + +Connect to the sandbox, then launch the terminal UI: + +```bash +nemo-deepagents connect +dcode +``` + +For a single headless task, run: + +```bash +dcode -n "Summarize this repository" +``` + +For automation, add `--json`: + +```bash +dcode -n "Summarize this repository" --json +``` + +The managed runtime writes exactly one UTF-8 JSON object to stdout and suppresses progress and other stdout text. +Warnings and diagnostics go to stderr. +A successful run has this version 1 envelope: + +```json +{ + "schema_version": 1, + "command": "non-interactive", + "data": { + "status": "success", + "exit_code": 0, + "response": "The repository contains...", + "completion": { + "thread_id": "thread-id", + "duration_ms": 842, + "response_bytes": 26 + } + } +} +``` + +`response` contains the exact final assistant text on success and is `null` on failure. +`response_bytes` is its UTF-8 byte length on success and is `0` on failure. +The process exit code matches `data.exit_code`. +The terminal statuses are `success`, `agent_failure`, `process_failure`, `timeout`, `turn_limit`, `cancelled`, and `output_limit`. +A timeout exits `124`, cancellation exits `130`, and other failures exit nonzero. + +The complete serialized envelope is limited to 1 MiB. +If the response cannot fit, the runtime discards it and emits a bounded `output_limit` failure envelope. +If it cannot write the envelope, the command exits nonzero and reports the write failure on stderr. +Callers must reject empty, malformed, additional, or unsupported-version stdout. + +## Understand the Managed Runtime + +The managed `dcode`, `dcode.real`, and `deepagents-code` launchers use `/opt/venv/bin/python3 -I` to run the pinned package with an isolated import path and `HOME=/sandbox`. +For interactive and headless sessions, each launcher supervises its own process descendants. +Completion, terminal exit, or disconnect terminates the associated LangGraph server tree without affecting another session. +After a disconnect, the supervisor uses bounded grace periods before it kills unresponsive processes from that session. +The supervisor runs inside the Linux OpenShell sandbox and fails closed if invoked outside Linux; the host operating system does not change this sandbox guarantee. + +The managed launchers disable the following mutable or unsupported behavior: + +- Deep Agents Code package update checks and the LangGraph server version check +- CLI and TUI update or install commands +- Nested remote sandbox providers and remote asynchronous subagents +- Deep Agents Model Context Protocol (MCP) commands, project MCP auto-loading, startup commands, and executable hooks +- ACP mode, interpreter tool calling, and shell allow-list overrides +- Native LangSmith tracing and ambient OpenTelemetry exporter configuration + +The managed model constructor accepts only Deep Agents Code's `openai` provider path and reads its endpoint from a root-owned image file. +It supplies the non-secret gateway placeholder key and ignores mutable provider classes, credentials, endpoints, and constructor parameters in Deep Agents Code config. +CLI and TUI model parameter overrides and custom rubric models are blocked. +For headless runs, `--max-retries` remains available after Deep Agents Code validates the retry count. +The managed boundary discards every other model parameter, including credentials, endpoints, and provider settings. +Project and user-defined subagents remain available, but they inherit the managed chat model instead of accepting their own model override. + +MCP servers registered through `nemo-deepagents mcp add` remain available through NemoClaw's dedicated `/sandbox/.deepagents/.nemoclaw-mcp.json` projection and OpenShell egress policy. +Project and user MCP files are never auto-loaded. +Sandboxes with the older managed MCP v1 runtime must rebuild before `mcp add` or `mcp restart`. +Remove, rebuild, and destroy can still scrub exact registry-owned legacy entries without claiming unrelated user content. +Before launch, NemoClaw validates and canonicalizes the complete managed file as HTTPS-only definitions with exact OpenShell credential placeholders. +It then gives Deep Agents Code a process-local, integrity-bound snapshot for server starts and restarts. +It prefers a sealed in-memory file when available. +The OpenShell-compatible anonymous read-only descriptor fallback verifies the inode, size, and SHA-256 digest and fails closed on drift. +Stdio commands, extra headers, raw credentials, and unrelated top-level configuration fail closed. +For authenticated MCP setup and credential rotation, see [Add an MCP Server](../mcp-servers/add-an-mcp-server) and [Manage MCP Servers](../mcp-servers/manage-mcp-servers). +This isolated-mode guarantee applies to the managed launchers, not arbitrary Python commands in the sandbox. + +## Choose an Approval Boundary + +Interactive shell execution and other destructive tools remain behind human-in-the-loop approval prompts by default. +Thread-wide auto-approval is unavailable unless you enable the managed thread opt-in capability, and shell allow-list auto-approval remains disabled. + +Headless `dcode -n` is an explicit automation boundary. +It has no approval UI and automatically approves non-shell tool requests, including file writes and edits. +The managed headless path still disables shell execution, startup commands, interpreter tool calling, executable hooks, unmanaged MCP configuration, nested remote sandboxes, remote asynchronous subagents, and alternate model routes. +Use the interactive TUI when you need to inspect each destructive tool request before it runs. + +## Configure Thread Auto-Approval + +Managed Deep Agents sandboxes keep interactive thread auto-approval disabled by default. +In this mode, the TUI auto-approval choice and `dcode -y` fail closed. + +Enable the capability for a named sandbox through a transactional rebuild because NemoClaw bakes the capability into the managed image: + +```bash +nemo-deepagents rebuild --dcode-auto-approval thread-opt-in --yes +``` + +The `thread-opt-in` setting grants permission to activate auto-approval, but it does not activate auto-approval by itself. +For each thread, select **Auto-approve for this thread** in the approval menu or start that `dcode` process with `dcode -y`. +The TUI shows the upstream active-state indicator and a warning while the current thread can run tool calls, including shell commands, without further confirmation. + +NemoClaw resets the active state when you start a new `dcode` process, run `/clear` or `/force-clear`, switch or resume a different thread, or switch agents. +You must opt in again after each reset. +The host-side status command reports the configured capability, not whether one live TUI thread currently has auto-approval active: + +```bash +nemo-deepagents status +``` + +Thread auto-approval does not bypass OpenShell network policy, credential isolation, the managed inference route, managed MCP validation, or the other Deep Agents runtime restrictions. +Headless `dcode -n` remains a separate automation boundary with non-shell auto-approval and managed shell execution disabled. + +Return the sandbox to the default posture with another transactional rebuild: + +```bash +nemo-deepagents rebuild --dcode-auto-approval disabled --yes +``` + +## Inspect Runtime Identity and Configuration + +To confirm which sandbox a session is in, run: + +```bash +dcode status +``` + +The command prints the sandbox name, NemoClaw harness, active `dcode` agent, configured inference route, upstream provider, model, endpoint, and runtime. +It then exits without starting the interactive UI. +`dcode whoami` and `dcode identity` are aliases. +`dcode --help` lists the managed aliases before the upstream Deep Agents Code help. +The sandbox name resolves when you run the command from a `nemo-deepagents connect` shell, which loads the NemoClaw runtime environment. + +Inspect the generated Deep Agents configuration from the host: + +```bash +nemo-deepagents config get +``` + +NemoClaw parses `config.toml`, removes gateway auth data, and redacts credential-shaped values before printing it. +`config set` is not supported for this image-baked configuration. +Re-onboard the named sandbox to change its managed provider or model selection. + +## Related Topics + +- [View Sandbox Status](view-sandbox-status) covers health, logs, and diagnostic collection. +- [Recover and Rebuild Sandboxes](recover-and-rebuild-sandboxes) explains recovery and transactional rebuild behavior. +- [Understand Sandbox State](../state-and-backups/understand-sandbox-state) explains the Deep Agents state directory and preservation boundaries. +- [Troubleshooting](../../reference/troubleshooting) covers common setup and runtime failures. diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index fc7a16bc88..2a789e7ed4 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -110,7 +110,7 @@ dcode -n "Summarize this repository" --json dcode status ``` -For the JSON schema, status and exit behavior, and 1 MiB output limit, refer to [Quickstart with LangChain Deep Agents Code](/user-guide/deepagents/get-started/quickstart#use-the-harness). +For the JSON schema, status and exit behavior, and 1 MiB output limit, refer to [Run Deep Agents Code](/user-guide/deepagents/manage-sandboxes/operate-sandboxes/run-deep-agents-code). @@ -1057,7 +1057,7 @@ Bare invocations run `dcode`, and `--help` runs `dcode --help`. Use `dcode -n` for explicit headless automation when you are already connected to the sandbox, or use `$$nemoclaw agent -n ""` from the host. Add `--json` to either form for one managed, versioned JSON envelope on stdout. The host wrapper forwards the flag to `dcode`. -For the schema, status and exit behavior, and 1 MiB output limit, refer to [Quickstart with LangChain Deep Agents Code](/user-guide/deepagents/get-started/quickstart#use-the-harness). +For the schema, status and exit behavior, and 1 MiB output limit, refer to [Run Deep Agents Code](/user-guide/deepagents/manage-sandboxes/operate-sandboxes/run-deep-agents-code). The host wrapper keeps `HOME=/sandbox`, the managed proxy environment, and the manifest-declared Deep Agents config path aligned with `connect`. Interactive `$$nemoclaw agent` launches the same terminal TUI as `dcode`. Headless `$$nemoclaw agent -n ""` uses the managed headless boundary, where non-shell tools can auto-run without the interactive approval UI. @@ -1378,7 +1378,8 @@ A successful recovery clears the stale stopped-container failure. If OpenShell already reports the registered Docker-driver sandbox as present and `Ready`, status verifies the OpenClaw gateway and host forward. It recovers either component when the verification reports it absent. -If Docker readiness or the agent delivery chain cannot be proven, status exits non-zero and reports the failed recovery layer. +If Docker readiness or the agent delivery chain cannot be proven, status exits non-zero and reports the `sandbox_recovery_failed` state. +Address the reported recovery layer, then run the displayed `$$nemoclaw recover` command. If the sandbox's recorded dashboard port is also held by a foreign listener, the header escalates to the `sandbox_dashboard_port_conflict` failure layer with the message `sandbox container is stopped and the dashboard port is held by a foreign listener.` so the operator can recover the port before restarting the sandbox. diff --git a/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx index 2537d6f8fc..949a8b2512 100644 --- a/docs/reference/troubleshooting.mdx +++ b/docs/reference/troubleshooting.mdx @@ -134,6 +134,26 @@ docker info The managed default gateway service accepts `DOCKER_HOST` only as an absolute local `unix://` socket path. It rejects remote endpoints and relative socket paths before service startup. +### Onboarding reports `invalid_docker_host` + +The `invalid_docker_host` advisory means that `DOCKER_HOST` is set to an endpoint that NemoClaw cannot safely pass to the managed OpenShell gateway service. +Remove the override to use Docker's default local socket: + +```bash +unset DOCKER_HOST +$$nemoclaw onboard +``` + +If your Docker daemon uses another local socket, set an absolute `unix://` path before you retry: + +```bash +export DOCKER_HOST=unix:///var/run/docker.sock +$$nemoclaw onboard +``` + +NemoClaw rejects TCP and SSH endpoints, relative socket paths, values that contain single quotes, and values that contain line breaks. +Do not wrap the socket path in single quotes inside the variable value. + ### macOS first-run failures The two most common first-run failures on macOS are missing developer tools and Docker connection errors. diff --git a/docs/resources/automate-documentation-workflows.mdx b/docs/resources/automate-documentation-workflows.mdx new file mode 100644 index 0000000000..919a9347ae --- /dev/null +++ b/docs/resources/automate-documentation-workflows.mdx @@ -0,0 +1,169 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Automate Documentation Workflows" +sidebar-title: "Automate Docs Workflows" +description: "Embed documentation updates, review evidence, and periodic curation in the engineering workflow." +description-agent: "Explains repository-embedded documentation updates, observable review receipts, workflow adoption metrics, bounded agent workflows, and periodic corpus curation. Use when automating documentation maintenance or measuring whether the workflow is followed." +keywords: ["documentation automation", "documentation review receipt", "docs workflow", "docs adoption metrics", "documentation curation"] +content: + type: "how_to" +--- + +Place documentation work close to the product change so the implementation, tests, and user guidance can be reviewed together. +Use observable workflow evidence and periodic information-architecture maintenance to keep routine updates accurate without turning every pull request into a restructuring project. + +## Move Documentation Into the Engineering Loop + +Many documentation workflows begin after engineering work is complete. +The writer identifies which features are shipping, finds the responsible engineers, interviews them to reconstruct the behavior, and then creates a separate documentation change. +This manual intake phase consumes time and can lose important context between implementation and publication. + +NemoClaw moves routine documentation work into the developer's engineering pull request. +The agent working on the developer's machine can inspect the code, tests, issue, and pull-request context while the change is still fresh. +Repository instructions tell that agent when documentation is required, where the content belongs, how to write it, and which checks prove the result. + +| Stage | Separate documentation handoff | Repository-embedded workflow | +|---|---|---| +| Discover changes | A writer collects release scope from meetings, messages, and issue lists. | The developer's agent inspects the current diff, issue, and changed behavior. | +| Transfer knowledge | A writer interviews engineers and reconstructs implementation details. | The agent reads the implementation and tests, then asks only when a decision or supported contract is unclear. | +| Draft documentation | A writer creates a later documentation task or pull request. | The agent updates the canonical page in the engineering pull request. | +| Review accuracy | Documentation and implementation may be reviewed at different times. | Reviewers see the behavior, tests, and documentation together. | +| Prepare a release | A writer performs a broad catch-up pass before publication. | Continuous updates reduce catch-up work, while the release workflow verifies completeness and creates the canonical changelog entry. | + +The repository provides a control stack for this workflow: + +- The root `AGENTS.md` defines repository-wide success criteria, product scope, and documentation expectations. +- `docs/AGENTS.md` defines the documentation role, source-of-truth rules, variant patterns, and verification requirements. +- `docs/CONTRIBUTING.md` defines the public writing, navigation, release, and review contracts. +- The `nemoclaw-contributor-update-docs` skill maps product changes to canonical pages and produces an evidence-backed documentation update. +- Build scripts, tests, hooks, previews, and publication workflows enforce the contracts after the agent edits the files. + +The expected pull-request loop is direct: + +1. The developer's agent reads the repository and documentation instructions. +2. It inspects the implemented behavior and its tests. +3. It decides whether the change has user-facing documentation impact. +4. It updates the canonical page in the same pull request when documentation is required. +5. It runs the relevant documentation and product-parity checks. +6. It reports the pages changed, behavior represented, and verification evidence. + +This model removes the need for a writer to manually reconstruct every incremental product change. +It does not remove documentation ownership. +It shifts the writer's role toward designing the system, maintaining the instructions, monitoring outcomes, and handling work that requires editorial judgment. +When the instructions are working, the writer can review by exception. +Routine pull-request updates that already meet the documentation contract do not need line editing, so the writer can focus on unclear product scope, structural pressure, and recurring failure patterns. + +## Make Documentation Review Observable + +A repository instruction can require a documentation writer subagent, but the instruction alone does not show whether an engineering agent followed it. +Add a structured pull-request receipt so each code or documentation change produces observable documentation-review evidence. + +NemoClaw records the following fields in the Documentation Writer Review section of the pull-request description: + +- A completed-review checkbox. +- One result: `docs-updated`, `no-docs-needed`, or `blocked`. +- Evidence that names the changed documentation or explains the result. +- The agent product and surface that ran the review. +- Hidden metadata for the reviewed head SHA and the `AGENTS.md` blob SHA. + +Keep one instance of each field. +GitHub supplies the pull-request identity to the workflow and report. +The head SHA binds the review to one pull-request revision. +The `AGENTS.md` blob SHA records which repository instruction version the review covered. + +Use the following sequence for a pull request that changes code or documentation: + +1. Run the documentation writer subagent after the changes and applicable validation are complete. +2. For code changes, update the canonical documentation or record why no documentation change is required. +3. For documentation changes, verify the writing rules and documentation style. +4. Commit all changes from the review. +5. Complete the visible receipt and hidden metadata for the committed head. +6. Rerun the documentation review after any later commit. + +The `CI / Documentation Writer Review` workflow runs when a pull request opens or reopens, when its description is edited, or when it receives a new commit. +It compares the receipt with the current head and current `AGENTS.md` blob. +A new commit makes the previous receipt stale until the documentation writer subagent runs again and refreshes the metadata. +The checker evaluates code-changing and documentation-only pull requests. +For documentation-only changes, the receipt records the agent's review of writing rules and documentation style. +NemoClaw keeps this check advisory during the data-collection pilot. + + +A valid receipt does not prove that an agent loaded or understood `AGENTS.md`. +It records observable workflow compliance that can be compared with documentation outcomes. + + +### Measure Workflow Adoption + +Export receipt data from pull-request descriptions with the authenticated GitHub CLI session. +The report returns JSON by default and also supports CSV and summary output. + +```bash +npm run docs-review:report -- --since 2026-07-01 --format summary +``` + +Use a consistent reporting window and track the following measures: + +| Measure | What it shows | +|---|---| +| Eligible pull requests | The total in `eligiblePrs`, plus the code and documentation-only counts in `eligibleCodePrs` and `eligibleDocsOnlyPrs`. | +| Receipt coverage | The share of eligible code-changing and documentation-only pull requests that contain a receipt. | +| Valid receipt rate | The share of eligible pull requests whose receipt has one complete and consistent set of fields. | +| Fresh receipt rate | The share of recorded receipts tied to the pull request's current head. | +| Result distribution | The number of receipts that report `docs-updated`, `no-docs-needed`, or `blocked`. | +| Agent surface | The agent products and surfaces recorded by valid receipts. | +| Unclassified pull requests | Pull requests whose Type of Change selection does not establish whether code or documentation changed. | + +Receipt trends show whether the repository workflow is being followed. +They do not establish that the instructions caused a documentation improvement. +Pair the report with accuracy sampling, editorial-intervention rates, and recurring review findings before changing the instruction or making the check required. + +## Encode Documentation Work as Agent Workflows + +Agentic docs include the workflows that maintain the corpus, not only the content agents retrieve. +Turn repeatable documentation engineering practices into bounded skills or repository instructions with explicit inputs, stop conditions, and evidence. + +| Workflow | Trigger | Required inputs | Completion evidence | +|---|---|---|---| +| Update docs | Product behavior changes or docs fall behind code. | Commit range, changed files, product scope, current pages. | Each user-visible change maps to an updated page or a documented no-impact decision. | +| Refactor information architecture | A section is oversized, duplicated, or hard to navigate. | Heading inventory, ownership map, inbound routes, supported variants. | One owner per topic, migrated routes, readable pages, and no content loss. | +| Review docs | A pull request changes a public procedure or reference. | Product implementation, tests, rendered preview, style policy. | Accuracy, links, route publication, and task verification pass. | +| Prepare a release | A release candidate is ready for documentation. | Merged change set, release scope, target version and date. | Canonical changelog entry lands before the release tag. | +| Publish | A docs change merges or a release tag is created. | Validated source, approved environment, immutable revision. | Staging or public output points to the expected revision. | + +NemoClaw applies this model through layered repository instructions and specialized contributor and maintainer skills. +The update workflow scans commits, respects a documentation skip list, maps behavior to canonical pages, and verifies the build. +The refactor workflow inventories every topic, defines ownership and URL migration contracts, and validates every supported variant. + +Design each workflow to produce evidence instead of a generic statement that the docs were updated. +The agent should report the files changed, source behavior represented, checks run, and intentionally deferred work. + +## Let the Corpus Grow and Tend It + +Do not require every engineering pull request to redesign the documentation structure. +Let agents make small, accurate updates to the current canonical page while the product evolves. +Restructure the corpus after repeated changes reveal its real shape. + +This is continuous growth with periodic curation. +The daily engineering loop keeps behavior and documentation aligned, while a daily or weekly maintenance pass improves sections that have outgrown their original purpose. + +Use observable signals to start a restructuring pass: + +- A page serves several distinct user tasks. +- A section has become difficult to scan or navigate. +- A paragraph contains several decisions, procedures, or failure modes. +- The same guidance appears in several pages. +- A common task is buried under an unrelated heading or navigation group. +- Product variants have started to drift because their shared and distinct behavior is unclear. + +During the maintenance pass, split overgrown pages, clarify headings, move reusable reference material to one owner, remove duplication, and preserve published routes. +If agents repeatedly produce the same structural or style problem, improve the repository instructions or workflow skill so later pull requests correct the pattern at its source. + +This cadence avoids premature reorganization while keeping the documentation usable as it grows. +It also reserves the writer's time for structure, user journeys, and editorial quality instead of routine transcription. + +## Related Topics + +- [Design Agent-Ready Documentation](design-agent-ready-documentation) defines the architecture and canonical ownership model. +- [Generate Documentation Variants](generate-documentation-variants) explains the deterministic variant build. +- [Govern and Evaluate Agentic Documentation](govern-agentic-documentation) defines scope gates and outcome measures. diff --git a/docs/resources/design-agent-ready-documentation.mdx b/docs/resources/design-agent-ready-documentation.mdx new file mode 100644 index 0000000000..ca5e2bf63f --- /dev/null +++ b/docs/resources/design-agent-ready-documentation.mdx @@ -0,0 +1,159 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Design Agent-Ready Documentation" +sidebar-title: "Design Agent-Ready Docs" +description: "Design a governed documentation architecture that serves people and AI agents from one canonical source." +description-agent: "Defines the product contract, layered architecture, canonical ownership, machine-readable delivery paths, and thin routing needed for agent-ready documentation. Use when designing an agentic documentation system or assigning canonical content ownership." +keywords: ["agent-ready documentation", "documentation architecture", "canonical documentation", "llms.txt", "docs MCP server"] +content: + type: "how_to" +--- + +Agent-ready documentation helps an AI agent find the right source, apply it to the user's context, take bounded action, and verify the result. +It serves people and agents from one governed source instead of maintaining a website, prompt library, and skill catalog as separate bodies of content. + +This page defines the architecture for that system. +The file names and tools are NemoClaw examples, but the contracts apply to any docs-as-code stack. + + +Making HTML available to a model is not enough. +An agent-ready system needs explicit retrieval paths, task metadata, stable routes, safety boundaries, and evidence that the published guidance still matches the product. + + +## Define the Product Contract + +Start with observable outcomes instead of selecting tools. +A reliable agentic documentation system supports the following contract. + +| Capability | Contract | Evidence | +|---|---|---| +| Discover | The agent can identify the relevant document for a user task. | A task query returns the intended page and variant. | +| Retrieve | The agent can fetch clean, current, citable content. | A stable Markdown route or read-only search tool returns the canonical source. | +| Apply | The guidance includes decisions, prerequisites, steps, and boundaries. | The agent produces instructions scoped to the user's environment. | +| Act | The agent knows which operations are safe, which need approval, and which are out of scope. | Workflow instructions stop before credentials, destructive changes, or unsupported surfaces. | +| Verify | Every procedure ends with an observable success check. | The agent runs or recommends the documented validation step. | +| Maintain | Product changes can be traced to documentation owners and release evidence. | Pull-request gates detect stale, missing, or unpublished guidance. | + +Treat failures in any row as documentation defects. +A polished site with weak retrieval or verification is not agent-ready. + +## Use a Layered Architecture + +Keep content, delivery, routing, workflow, and assurance separate so each layer has one responsibility. + +```mermaid +flowchart TB + PRODUCT["Authoritative product sources
Code, schemas, commands, support data"] + SOURCE["Canonical task-oriented source
Concepts, procedures, reference, troubleshooting"] + BUILD["Deterministic build
Metadata, variants, prompts, route graph"] + HUMAN["Human delivery
Rendered documentation site"] + MACHINE["Machine delivery
Markdown routes, llms.txt, read-only docs search"] + ROUTING["Agent routing
Starter prompt and thin docs skill"] + WORKFLOW["Engineering workflows
Update, refactor, review, release"] + ASSURANCE["Assurance
Parity checks, links, previews, publication gates"] + PEOPLE["Readers"] + AGENTS["User-facing agents"] + + PRODUCT --> WORKFLOW + SOURCE --> BUILD + BUILD --> HUMAN + BUILD --> MACHINE + HUMAN --> PEOPLE + MACHINE --> ROUTING + ROUTING --> AGENTS + WORKFLOW --> SOURCE + PRODUCT --> ASSURANCE + ASSURANCE --> BUILD + ASSURANCE --> WORKFLOW +``` + +The source remains authoritative throughout the loop. +Prompts, skills, generated variants, search indexes, and rendered pages are delivery or control artifacts, not alternate sources of truth. + +## Establish One Canonical Owner + +Write each fact once in its authoritative layer, then produce the human and machine experiences from one publication source. +Product behavior may be authoritative in code, schemas, command metadata, or support data, while the documentation corpus remains the canonical published explanation. +Generate structured reference content from product sources when practical and use parity tests when prose must remain hand-written. + +NemoClaw uses MDX under `docs/` as its user-facing source of truth and generates agent-specific pages during the docs build. + +Apply these source rules: + +- Give each page one primary concept or user task. +- Organize procedures around the reader journey from choosing through setup, operation, validation, and troubleshooting. +- Keep reusable troubleshooting and reference facts with one canonical owner, then link to that owner. +- Generate tables and reference values from authoritative product data when that removes manual synchronization. +- Store navigation and route slugs in a machine-readable index. +- Declare intentional partial variant scope in source metadata and validate it against published navigation membership. +- Treat generated pages as disposable build output and never edit them by hand. +- Preserve published routes with direct redirects when content moves. + +Use frontmatter to describe the page for both people and retrieval systems. +The human description explains the value of the page, while the agent description states what the page helps with and when to select it. + +```yaml +--- +title: "Configure a Private Package Registry" +description: "Connect the product to a private package registry and verify authenticated downloads." +description-agent: "Configures and validates private package registry access. Use when users ask about registry credentials, package download failures, or enterprise package mirrors." +keywords: ["private registry", "package authentication", "enterprise mirror"] +content: + type: "how_to" +--- +``` + +Good routing metadata names the user intent, scope, and likely trigger phrases. +It does not repeat the page body or make unsupported product claims. + +## Publish Machine-Readable Delivery Paths + +Publish clean content through more than one retrieval path because agent environments have different capabilities. +Use this retrieval order: + +1. Search a read-only documentation service when the client supports a structured tool such as Model Context Protocol (MCP). +2. Fetch a lightweight documentation index such as `llms.txt` when structured search is unavailable. +3. Fetch the specific Markdown page returned by search or listed in the index. +4. Fall back to rendered HTML only when a clean machine-readable route is unavailable. + +Each path should resolve to the same release and canonical page. +Do not make the agent reconcile copied content from several repositories or prompt bundles. + +Machine delivery is ready when the following checks pass: + +- Every published task page has a stable Markdown representation. +- The documentation index contains the current public route set. +- Search results return source URLs that an answer can cite. +- Variant-specific queries do not silently mix incompatible instructions. +- Moved pages redirect directly to a current published destination. +- Private drafts and unsupported features do not enter the public index. + +NemoClaw exposes its canonical pages through Markdown routes, `llms.txt`, and a read-only docs MCP server. +The [Use NemoClaw Docs with Your Coding Agents](../agent-skills) page shows the user-facing retrieval flow. + +## Keep Agent Routing Thin + +Use prompts and skills to route the agent, not to store another copy of the docs. +A routing layer should tell the agent where to look, how to choose a source, and what response constraints to follow. + +A small routing skill needs only the following elements: + +- The canonical search endpoint and fallback documentation index. +- The preferred order for retrieving pages. +- The main task areas and their starting pages. +- Variant or platform selection rules. +- Safety requirements for approvals, credentials, and destructive actions. +- Citation and verification requirements. + +This pattern keeps the routing artifact stable while the product documentation changes frequently. +It also avoids large generated skills that drift from the public site, consume context, and create ambiguous ownership. + +Pair the routing skill with a starter prompt for users who have not installed project instructions. +Keep the starter prompt in a standalone canonical file, generate any website component from that file, and test that embedded or pinned copies still match it. + +## Related Topics + +- [Automate Documentation Workflows](automate-documentation-workflows) explains how to place documentation work inside the engineering loop. +- [Generate Documentation Variants](generate-documentation-variants) explains shared-source variant generation. +- [Govern and Evaluate Agentic Documentation](govern-agentic-documentation) defines publication boundaries and quality measures. diff --git a/docs/resources/engineer-agentic-documentation.mdx b/docs/resources/engineer-agentic-documentation.mdx deleted file mode 100644 index 0ef65298c2..0000000000 --- a/docs/resources/engineer-agentic-documentation.mdx +++ /dev/null @@ -1,604 +0,0 @@ ---- -# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 -title: "Engineer Documentation for AI Agents" -sidebar-title: "Engineer Agentic Docs" -description: "A practical architecture and operating model for making technical documentation reliable for both people and AI agents." -description-agent: "Explains how to engineer agent-ready documentation with one canonical source, Markdown and MCP delivery, thin routing skills, workflow automation, review receipts, adoption metrics, variants, governance, and deterministic quality gates. Use when designing agentic documentation, docs engineering systems, AI documentation workflows, or docs-as-code automation." -keywords: ["agentic documentation", "agent-ready docs", "documentation engineering", "AI documentation workflow", "documentation review receipt", "docs as code", "llms.txt", "docs MCP server"] -content: - type: "how_to" ---- - -Agentic documentation is a documentation system that helps an AI agent find the right source, apply it to the user's context, take bounded action, and verify the result. -It serves people and agents from one governed source instead of maintaining a website, prompt library, and skill catalog as separate bodies of content. -It also places agents inside the documentation lifecycle so product changes arrive with accurate documentation instead of becoming a later handoff to a writing team. - -This guide turns the current NemoClaw documentation architecture into a reusable model for other engineering teams. -The file names and tools are NemoClaw examples, but the contracts apply to any docs-as-code stack. - - -Making HTML available to a model is not enough. -An agent-ready system needs explicit retrieval paths, task metadata, stable routes, safety boundaries, and evidence that the published guidance still matches the product. - - -## Define the Product Contract - -Start with observable outcomes instead of selecting tools. -A reliable agentic documentation system supports the following contract. - -| Capability | Contract | Evidence | -|---|---|---| -| Discover | The agent can identify the relevant document for a user task. | A task query returns the intended page and variant. | -| Retrieve | The agent can fetch clean, current, citable content. | A stable Markdown route or read-only search tool returns the canonical source. | -| Apply | The guidance includes decisions, prerequisites, steps, and boundaries. | The agent produces instructions scoped to the user's environment. | -| Act | The agent knows which operations are safe, which need approval, and which are out of scope. | Workflow instructions stop before credentials, destructive changes, or unsupported surfaces. | -| Verify | Every procedure ends with an observable success check. | The agent runs or recommends the documented validation step. | -| Maintain | Product changes can be traced to documentation owners and release evidence. | Pull-request gates detect stale, missing, or unpublished guidance. | - -Treat failures in any row as documentation defects. -A polished site with weak retrieval or verification is not agent-ready. - -## Move Documentation Into the Engineering Loop - -Many documentation workflows begin after engineering work is complete. -The writer identifies which features are shipping, finds the responsible engineers, interviews them to reconstruct the behavior, and then creates a separate documentation change. -This manual intake phase consumes time and can lose important context between implementation and publication. - -NemoClaw moves routine documentation work into the developer's engineering pull request. -The agent working on the developer's machine can inspect the code, tests, issue, and pull-request context while the change is still fresh. -Repository instructions tell that agent when documentation is required, where the content belongs, how to write it, and which checks prove the result. - -| Stage | Separate documentation handoff | Repository-embedded workflow | -|---|---|---| -| Discover changes | A writer collects release scope from meetings, messages, and issue lists. | The developer's agent inspects the current diff, issue, and changed behavior. | -| Transfer knowledge | A writer interviews engineers and reconstructs implementation details. | The agent reads the implementation and tests, then asks only when a decision or supported contract is unclear. | -| Draft documentation | A writer creates a later documentation task or pull request. | The agent updates the canonical page in the engineering pull request. | -| Review accuracy | Documentation and implementation may be reviewed at different times. | Reviewers see the behavior, tests, and documentation together. | -| Prepare a release | A writer performs a broad catch-up pass before publication. | Continuous updates reduce catch-up work, while the release workflow verifies completeness and creates the canonical changelog entry. | - -The repository provides a control stack for this workflow: - -- The root `AGENTS.md` defines repository-wide success criteria, product scope, and documentation expectations. -- `docs/AGENTS.md` defines the documentation role, source-of-truth rules, variant patterns, and verification requirements. -- `docs/CONTRIBUTING.md` defines the public writing, navigation, release, and review contracts. -- The `nemoclaw-contributor-update-docs` skill maps product changes to canonical pages and produces an evidence-backed documentation update. -- Build scripts, tests, hooks, previews, and publication workflows enforce the contracts after the agent edits the files. - -The expected pull-request loop is direct: - -1. The developer's agent reads the repository and documentation instructions. -2. It inspects the implemented behavior and its tests. -3. It decides whether the change has user-facing documentation impact. -4. It updates the canonical page in the same pull request when documentation is required. -5. It runs the relevant documentation and product-parity checks. -6. It reports the pages changed, behavior represented, and verification evidence. - -This model removes the need for a writer to manually reconstruct every incremental product change. -It does not remove documentation ownership. -It shifts the writer's role toward designing the system, maintaining the instructions, monitoring outcomes, and handling work that requires editorial judgment. -When the instructions are working, the writer can review by exception. -Routine pull-request updates that already meet the documentation contract do not need line editing, so the writer can focus on unclear product scope, structural pressure, and recurring failure patterns. - -## Make Documentation Review Observable - -A repository instruction can require a documentation writer subagent, but the instruction alone does not show whether an engineering agent followed it. -Add a structured pull-request receipt so each code or documentation change produces observable documentation-review evidence. - -NemoClaw records the following fields in the Documentation Writer Review section of the pull-request description: - -- A completed-review checkbox. -- One result: `docs-updated`, `no-docs-needed`, or `blocked`. -- Evidence that names the changed documentation or explains the result. -- The agent product and surface that ran the review. -- Hidden metadata for the reviewed head SHA and the `AGENTS.md` blob SHA. - -Keep one instance of each field. -GitHub supplies the pull-request identity to the workflow and report. -The head SHA binds the review to one pull-request revision. -The `AGENTS.md` blob SHA records which repository instruction version the review covered. - -Use the following sequence for a pull request that changes code or documentation: - -1. Run the documentation writer subagent after the changes and applicable validation are complete. -2. For code changes, update the canonical documentation or record why no documentation change is required. -3. For documentation changes, verify the writing rules and documentation style. -4. Commit all changes from the review. -5. Complete the visible receipt and hidden metadata for the committed head. -6. Rerun the documentation review after any later commit. - -The `CI / Documentation Writer Review` workflow runs when a pull request opens or reopens, when its description is edited, or when it receives a new commit. -It compares the receipt with the current head and current `AGENTS.md` blob. -A new commit makes the previous receipt stale until the documentation writer subagent runs again and refreshes the metadata. -The checker evaluates code-changing and documentation-only pull requests. -For documentation-only changes, the receipt records the agent's review of writing rules and documentation style. -NemoClaw keeps this check advisory during the data-collection pilot. - - -A valid receipt does not prove that an agent loaded or understood `AGENTS.md`. -It records observable workflow compliance that can be compared with documentation outcomes. - - -### Measure Workflow Adoption - -Export receipt data from pull-request descriptions with the authenticated GitHub CLI session. -The report returns JSON by default and also supports CSV and summary output. - -```bash -npm run docs-review:report -- --since 2026-07-01 --format summary -``` - -Use a consistent reporting window and track the following measures: - -| Measure | What it shows | -|---|---| -| Eligible pull requests | The total in `eligiblePrs`, plus the code and documentation-only counts in `eligibleCodePrs` and `eligibleDocsOnlyPrs`. | -| Receipt coverage | The share of eligible code-changing and documentation-only pull requests that contain a receipt. | -| Valid receipt rate | The share of eligible pull requests whose receipt has one complete and consistent set of fields. | -| Fresh receipt rate | The share of recorded receipts tied to the pull request's current head. | -| Result distribution | The number of receipts that report `docs-updated`, `no-docs-needed`, or `blocked`. | -| Agent surface | The agent products and surfaces recorded by valid receipts. | -| Unclassified pull requests | Pull requests whose Type of Change selection does not establish whether code or documentation changed. | - -Receipt trends show whether the repository workflow is being followed. -They do not establish that the instructions caused a documentation improvement. -Pair the report with accuracy sampling, editorial-intervention rates, and recurring review findings before changing the instruction or making the check required. - -## Use a Layered Architecture - -Keep content, delivery, routing, workflow, and assurance separate so each layer has one responsibility. - -```mermaid -flowchart TB - PRODUCT["Authoritative product sources
Code, schemas, commands, support data"] - SOURCE["Canonical task-oriented source
Concepts, procedures, reference, troubleshooting"] - BUILD["Deterministic build
Metadata, variants, prompts, route graph"] - HUMAN["Human delivery
Rendered documentation site"] - MACHINE["Machine delivery
Markdown routes, llms.txt, read-only docs search"] - ROUTING["Agent routing
Starter prompt and thin docs skill"] - WORKFLOW["Engineering workflows
Update, refactor, review, release"] - ASSURANCE["Assurance
Parity checks, links, previews, publication gates"] - PEOPLE["Readers"] - AGENTS["User-facing agents"] - - PRODUCT --> WORKFLOW - SOURCE --> BUILD - BUILD --> HUMAN - BUILD --> MACHINE - HUMAN --> PEOPLE - MACHINE --> ROUTING - ROUTING --> AGENTS - WORKFLOW --> SOURCE - PRODUCT --> ASSURANCE - ASSURANCE --> BUILD - ASSURANCE --> WORKFLOW -``` - -The source remains authoritative throughout the loop. -Prompts, skills, generated variants, search indexes, and rendered pages are delivery or control artifacts, not alternate sources of truth. - -## Establish One Canonical Owner - -Write each fact once in its authoritative layer, then produce the human and machine experiences from one publication source. -Product behavior may be authoritative in code, schemas, command metadata, or support data, while the documentation corpus remains the canonical published explanation. -Generate structured reference content from product sources when practical and use parity tests when prose must remain hand-written. - -NemoClaw uses MDX under `docs/` as its user-facing source of truth and generates agent-specific pages during the docs build. - -Apply these source rules: - -- Give each page one primary concept or user task. -- Organize procedures around the reader journey from choosing through setup, operation, validation, and troubleshooting. -- Keep reusable troubleshooting and reference facts with one canonical owner, then link to that owner. -- Generate tables and reference values from authoritative product data when that removes manual synchronization. -- Store navigation and route slugs in a machine-readable index. -- Declare intentional partial variant scope in source metadata and validate it against published navigation membership. -- Treat generated pages as disposable build output and never edit them by hand. -- Preserve published routes with direct redirects when content moves. - -Use frontmatter to describe the page for both people and retrieval systems. -The human description explains the value of the page, while the agent description states what the page helps with and when to select it. - -```yaml ---- -title: "Configure a Private Package Registry" -description: "Connect the product to a private package registry and verify authenticated downloads." -description-agent: "Configures and validates private package registry access. Use when users ask about registry credentials, package download failures, or enterprise package mirrors." -keywords: ["private registry", "package authentication", "enterprise mirror"] -content: - type: "how_to" ---- -``` - -Good routing metadata names the user intent, scope, and likely trigger phrases. -It does not repeat the page body or make unsupported product claims. - -## Publish Machine-Readable Delivery Paths - -Publish clean content through more than one retrieval path because agent environments have different capabilities. -Use this retrieval order: - -1. Search a read-only documentation service when the client supports a structured tool such as MCP. -2. Fetch a lightweight documentation index such as `llms.txt` when structured search is unavailable. -3. Fetch the specific Markdown page returned by search or listed in the index. -4. Fall back to rendered HTML only when a clean machine-readable route is unavailable. - -Each path should resolve to the same release and canonical page. -Do not make the agent reconcile copied content from several repositories or prompt bundles. - -Machine delivery is ready when the following checks pass: - -- Every published task page has a stable Markdown representation. -- The documentation index contains the current public route set. -- Search results return source URLs that an answer can cite. -- Variant-specific queries do not silently mix incompatible instructions. -- Moved pages redirect directly to a current published destination. -- Private drafts and unsupported features do not enter the public index. - -NemoClaw exposes its canonical pages through Markdown routes, `llms.txt`, and a read-only docs MCP server. -The [Use NemoClaw Docs with Your Coding Agents](agent-skills) page shows the user-facing retrieval flow. - -## Keep Agent Routing Thin - -Use prompts and skills to route the agent, not to store another copy of the docs. -A routing layer should tell the agent where to look, how to choose a source, and what response constraints to follow. - -A small routing skill needs only the following elements: - -- The canonical search endpoint and fallback documentation index. -- The preferred order for retrieving pages. -- The main task areas and their starting pages. -- Variant or platform selection rules. -- Safety requirements for approvals, credentials, and destructive actions. -- Citation and verification requirements. - -This pattern keeps the routing artifact stable while the product documentation changes frequently. -It also avoids large generated skills that drift from the public site, consume context, and create ambiguous ownership. - -Pair the routing skill with a starter prompt for users who have not installed project instructions. -Keep the starter prompt in a standalone canonical file, generate any website component from that file, and test that embedded or pinned copies still match it. - -## Encode Documentation Work as Agent Workflows - -Agentic docs include the workflows that maintain the corpus, not only the content agents retrieve. -Turn repeatable documentation engineering practices into bounded skills or repository instructions with explicit inputs, stop conditions, and evidence. - -| Workflow | Trigger | Required inputs | Completion evidence | -|---|---|---|---| -| Update docs | Product behavior changes or docs fall behind code. | Commit range, changed files, product scope, current pages. | Each user-visible change maps to an updated page or a documented no-impact decision. | -| Refactor information architecture | A section is oversized, duplicated, or hard to navigate. | Heading inventory, ownership map, inbound routes, supported variants. | One owner per topic, migrated routes, readable pages, and no content loss. | -| Review docs | A pull request changes a public procedure or reference. | Product implementation, tests, rendered preview, style policy. | Accuracy, links, route publication, and task verification pass. | -| Prepare a release | A release candidate is ready for documentation. | Merged change set, release scope, target version and date. | Canonical changelog entry lands before the release tag. | -| Publish | A docs change merges or a release tag is created. | Validated source, approved environment, immutable revision. | Staging or public output points to the expected revision. | - -NemoClaw applies this model through layered repository instructions and specialized contributor and maintainer skills. -The update workflow scans commits, respects a documentation skip list, maps behavior to canonical pages, and verifies the build. -The refactor workflow inventories every topic, defines ownership and URL migration contracts, and validates every supported variant. - -Design each workflow to produce evidence instead of a generic statement that the docs were updated. -The agent should report the files changed, source behavior represented, checks run, and intentionally deferred work. - -## Let the Corpus Grow and Tend It - -Do not require every engineering pull request to redesign the documentation structure. -Let agents make small, accurate updates to the current canonical page while the product evolves. -Restructure the corpus after repeated changes reveal its real shape. - -This is continuous growth with periodic curation. -The daily engineering loop keeps behavior and documentation aligned, while a daily or weekly maintenance pass improves sections that have outgrown their original purpose. - -Use observable signals to start a restructuring pass: - -- A page serves several distinct user tasks. -- A section has become difficult to scan or navigate. -- A paragraph contains several decisions, procedures, or failure modes. -- The same guidance appears in several pages. -- A common task is buried under an unrelated heading or navigation group. -- Product variants have started to drift because their shared and distinct behavior is unclear. - -During the maintenance pass, split overgrown pages, clarify headings, move reusable reference material to one owner, remove duplication, and preserve published routes. -If agents repeatedly produce the same structural or style problem, improve the repository instructions or workflow skill so later pull requests correct the pattern at its source. - -This cadence avoids premature reorganization while keeping the documentation usable as it grows. -It also reserves the writer's time for structure, user journeys, and editorial quality instead of routine transcription. - -## Generate Variants Without Duplicating Sources - -Many products publish documentation for editions, platforms, runtimes, or deployment models. -Generate a variant only when most of the source is shared. - -Use these rules: - -- Replace a build-time placeholder when only a literal name or command differs. -- Use a conditional block when the workflow, behavior, state layout, or security boundary differs. -- Use a separate source page when most of the procedure is variant-specific. -- Keep published guide variant membership and route slugs in the navigation model. -- Declare the intended guide variant subset in source metadata when a page does not apply to every guide variant. -- Regenerate every guide variant before route and link validation. -- Inspect rendered guide variants for broken lists, joined paragraphs, and missing context. - -NemoClaw generates shared OpenClaw, Hermes, and Deep Agents guide variants from one MDX source. -Its build rewrites the host CLI placeholder, removes inapplicable conditional blocks, and publishes a distinct route for each guide variant. - -### Separate the Source from Its Guide Variant Targets - -Authors edit the normal source page under `docs/`. -For this guide, the only source is `docs/resources/engineer-agentic-documentation.mdx`. -The repository does not maintain separate OpenClaw, Hermes, and Deep Agents source copies. - -### Author Shared and Variant-Specific Content - -Write ordinary prose once when the meaning is the same for every supported agent. -Use the $$nemoclaw placeholder when the only difference is the host CLI binary name. -The variant build resolves that placeholder as follows: - -| Generated variant | Placeholder output | -|---|---| -| OpenClaw | `nemoclaw`. | -| Hermes | `nemohermes`. | -| Deep Agents | `nemo-deepagents`. | - -Use the placeholder in prose, inline code, and fenced command examples on shared source pages. -Do not duplicate a paragraph or command block only to change the binary name. -Do not use the placeholder on a single-variant source page because that page does not pass through variant generation and would publish the placeholder literally. - -Use an `` block when the content differs by behavior, workflow, state layout, support, or agent-specific wording. -For example, start a Hermes-only block with <AgentOnly variant="hermes"> and close it with </AgentOnly>. -The `variant` attribute can name one variant or a comma-separated set such as `openclaw,hermes`. - -Do not import `AgentOnly` from a React component. -The canonical page is an intermediate source that the variant resolver compiles before Fern reads it. -The resolver removes the directive tags and keeps the block body only when the target variant appears in the `variant` attribute. - -Apply this decision rule: - -- Use ordinary shared prose when the meaning is identical. -- Use the host CLI placeholder when only the binary name differs. -- Use `` when the meaning or procedure differs. -- Use a separate source page when most of the page is specific to one agent. - -This page encodes the two dollar signs as character entities so a future generated variant can display the literal placeholder instead of resolving it. - -### Treat `AgentOnly` as a Build-Time Directive - -The `` syntax resembles an MDX component, but NemoClaw treats it as a build-time directive. -Agent variant selection does not depend on pathname detection or client-side logic in the rendered site. -The canonical source does not need an import because Fern receives only the resolved generated page. - -For each navigation target, `scripts/sync-agent-variant-docs.mts` reads the requested variant from `docs/index.yml` and parses the canonical source as text. -When an `` directive lists the active variant, the resolver copies its content into the generated page. -When the retained content starts with a Markdown list item, it discards blank lines immediately inside the opening and closing tags so wrapper formatting does not split the list. -For other retained content, it preserves those boundary blank lines and all interior blank lines so paragraphs and code sections keep their intended separation. -When the directive does not list the active variant, the resolver omits the body. -In both cases, it removes the opening and closing directive tags before writing the generated MDX. - -Keep the opening and closing `` tags at the first column on their own lines, and do not nest these blocks. -That line-oriented structure is the generator's authoring interface, and the resolver reports nested, unexpected, or unclosed blocks as errors. - -The `CLI_SENTINEL` constant and replacement table live in `scripts/sync-agent-variant-docs.mts` so placeholders can be resolved inside frontmatter, ordinary prose, inline code, and fenced command blocks before Fern renders the page. -Use $$nemoclaw for all shared host CLI references and wrap it in backticks when it should render as inline code. - -The resolver rejects a generated page if it still contains an unresolved line-oriented `` directive or a runtime agent component. -These checks make static resolution a publishing invariant instead of relying on client-side hydration to correct variant content. - -Published guide variant membership is explicit in `docs/index.yml`. -Each guide variant contains its own navigation tree, and a shared page appears in a tree through a generated target path with this contract: - -```text -_build/agent-variants//..generated.mdx -``` - -The `` value is `openclaw`, `hermes`, or `deepagents`. -The directory and base name before the guide variant suffix must match the canonical source path under `docs/`. - -When a source intentionally applies to fewer than all three guide variants, its frontmatter declares the exact subset: - -```yaml -agent-variants: ["openclaw", "hermes"] -``` - -The generator compares this declaration with the source's actual navigation membership and fails when the declaration is missing or differs. -An all-variant source omits the declaration, so removing one of its navigation targets also fails until the author restores the route or explicitly declares the narrower scope. - -If this source-only guide is added to Fern navigation, it would use the following mapping: - -| Guide variant | Generated target in `docs/index.yml` | Published route suffix | -|---|---|---| -| OpenClaw | `_build/agent-variants/resources/engineer-agentic-documentation.openclaw.generated.mdx` | `/user-guide/openclaw/resources/engineer-agentic-documentation`. | -| Hermes | `_build/agent-variants/resources/engineer-agentic-documentation.hermes.generated.mdx` | `/user-guide/hermes/resources/engineer-agentic-documentation`. | -| Deep Agents | `_build/agent-variants/resources/engineer-agentic-documentation.deepagents.generated.mdx` | `/user-guide/deepagents/resources/engineer-agentic-documentation`. | - -The site and version prefixes are added by the Fern site configuration. -The route suffix above comes from the variant, section, and page slug hierarchy in `docs/index.yml`. - -### Use the Fern Index as the Mapping Layer - -The version entry in `fern/docs.yml` points Fern to `docs/index.yml`. -That index defines the navigation and published route tree for every supported agent variant. - -An OpenClaw navigation entry for this guide would use the following shape: - -```yaml -- page: "Engineer Agentic Docs" - path: _build/agent-variants/resources/engineer-agentic-documentation.openclaw.generated.mdx - slug: engineer-agentic-documentation -``` - -The `path` tells Fern which generated MDX file to render. -The `slug` tells Fern the page's final route segment. -The surrounding `resources` section and `openclaw` variant contribute the parent route segments. - -This separation has several consequences: - -- A source file's filesystem location does not independently define its public URL. -- The same source can be published in several variant trees with the same page slug. -- A source page can apply to one guide variant by declaring that guide variant in frontmatter and pointing navigation directly to its source MDX file instead of a generated target. -- Moving or renaming a published page requires a navigation update and a redirect review, even when the source file stays in the same directory. -- Generated filenames are an interface with the generator and should not use an arbitrary naming pattern. - -### Resolve and Render Each Target - -The resolver is `scripts/sync-agent-variant-docs.mts`. -Run it directly through `npm run docs:sync-agent-variants`, or let `npm run docs` invoke it through the shared `docs:prepare` step. - -The script reads `docs/index.yml` before it reads shared source pages. -It derives each source page's published guide variant membership and validates every intentional subset declaration before rendering. -For each recognized generated path, it then performs the following work: - -1. It reads the active guide variant from the `openclaw`, `hermes`, or `deepagents` navigation tree. -2. It removes the `_build/agent-variants/` prefix and the `..generated.mdx` suffix. -3. It resolves the remaining path to one canonical `.mdx` source under `docs/`. -4. It renders that source for the active guide variant. -5. It writes the result under `docs/_build/agent-variants/` using the path declared in the index. -6. It removes stale generated files that no longer have a navigation target. - -Rendering replaces the host CLI placeholder with the correct binary name, removes conditional blocks that do not apply to the active guide variant, and adjusts relative image and component-import paths for the deeper generated directory. -Route-style links between documentation pages stay tied to the published navigation model instead of the generated filesystem location. - -The generated directory is ignored by Git. -Contributors commit the canonical source and `docs/index.yml` mapping, while the docs build recreates the variant files locally and in CI. - -### Validate the Complete Route Graph - -The `npm run docs` command prepares generated content before Fern validation. -The validation sequence checks the starter prompt, validates declared guide variant scope, regenerates the guide variants, verifies generated-page freshness, derives published routes from `docs/index.yml`, and runs the pinned Fern checker. - -This order matters because Fern cannot validate a guide variant route until the generated target named by `docs/index.yml` exists. -It also ensures that source edits, guide variant transforms, navigation mappings, and published routes are tested as one contract. - -## Treat Documentation as an Executable Product Surface - -Build deterministic checks around the contracts that matter to users and agents. -Syntax validation alone does not catch behavioral drift. - -| Gate | Defect it prevents | NemoClaw example | -|---|---|---| -| Source formatting | Unreadable diffs and inconsistent authoring. | Markdown linting, one sentence per source line, and copyable command rules. | -| Guide variant scope | A page is omitted from an applicable guide or silently published for the wrong agent. | Source `agent-variants` declarations checked against navigation membership. | -| Generated freshness | Stale prompts or guide variants. | Build-time generation followed by read-only freshness checks. | -| Route graph | Links or redirects that target unpublished pages. | Published-route validation derived from `docs/index.yml`. | -| Product parity | Reference documentation that disagrees with the product. | CLI command, flag, installer, and environment-variable parity checks. | -| Pull-request preview | Layout or navigation failures hidden by source checks. | An isolated Fern preview for each docs pull request. | -| Staging publish | A merge that cannot produce the deployed site. | Validation and publication from `main`. | -| Public release gate | Public docs from an unapproved or detached revision. | Release-tag publication only when the tagged commit is reachable from `main`. | - -Run the narrowest checks on every relevant change and keep broader checks at integration or release boundaries. -Tests should derive routes and behavior from the same source models used by the product instead of maintaining a second hard-coded catalog. - -## Govern What Agents May Publish - -Fast documentation automation needs a stronger scope gate, not a weaker one. -Documentation can accidentally turn an experiment into an apparent supported product surface. - -Define the following controls: - -- Require an accepted product decision before documenting a new integration, recipe, or supported workflow as canonical behavior. -- Maintain an explicit skip list for merged features that are not ready for public documentation. -- Block restricted terms and private implementation details from generated output. -- Separate public user guidance from contributor and maintainer procedures. -- Require agent workflows to stop before handling secrets, changing accounts, or performing destructive operations without approval. -- Assign an owner and lifecycle expectation to every canonical page and generated artifact. - -NemoClaw applies the same scope gate to code review and documentation review. -A working example and a green build establish technical evidence, but they do not establish product approval. - -## Keep High-Judgment Work Human-Owned - -Agents execute documented rules well when the repository gives them accurate context and deterministic checks. -People remain responsible for decisions that create or change those rules. - -Keep human ownership over the following work: - -- Decide whether a feature, integration, or workflow is a supported product surface. -- Decide which user problem a page owns and where readers should encounter it. -- Resolve conflicts between implementation details, product intent, security requirements, and user expectations. -- Restructure sections when accumulated changes reveal a better organization. -- Set the editorial voice, evidence standard, release narrative, and publication policy. -- Review recurring agent mistakes and improve the instructions, skills, tests, or source structure that allowed them. - -Formal information-architecture terminology can help teams discuss this work, but the terminology is not the source of quality. -If you can recognize that a page is doing too many jobs, decide where a user expects to find a topic, and give each topic one clear owner, you are already practicing the part of information architecture that this operating model needs. - -The durable division of labor is concise. -Agents handle repeatable work close to the engineering source, while people own product meaning, system design, exceptions, and editorial judgment. - -## Measure Retrieval and Task Quality - -Measure whether agents can complete documentation-backed tasks, not only whether pages receive traffic. - -Track a small evaluation set across common and high-risk user journeys: - -- Retrieval accuracy, measured by whether the intended canonical page appears in the first results. -- Variant accuracy, measured by whether the answer stays within the selected platform or product edition. -- Citation coverage, measured by whether behavior claims point to the current source page. -- Task completion, measured by whether the documented procedure reaches its success check. -- Safety compliance, measured by whether the agent stops at approval, credential, and destructive-action boundaries. -- Freshness, measured by the delay between a product change and its verified documentation update. -- Editorial intervention, measured by how often routine documentation changes require a manual rewrite after the agent follows the repository workflow. -- Drift detection, measured by which parity gate catches an intentionally stale fixture. - -Keep evaluation prompts versioned with the documentation system. -Add a regression case when a user report or review reveals that an agent selected the wrong source, mixed variants, skipped a safety boundary, or failed to verify the outcome. - -## Adopt the Model in Phases - -Build the smallest complete loop first, then add sophistication where evidence shows a need. - -| Phase | Deliverable | Exit condition | -|---|---|---| -| Foundation | One canonical, task-oriented Markdown or MDX corpus. | Humans can complete one priority journey from the source docs. | -| Machine delivery | Stable Markdown routes and a lightweight index. | An agent can retrieve and cite the same priority journey without scraping HTML. | -| Routing | A starter prompt and thin routing skill. | The agent selects the correct page, variant, and verification step. | -| Workflow | Repository instructions and an update-docs workflow. | A product change produces a traceable docs-impact decision. | -| Assurance | Route, link, generation, parity, and preview gates. | A deliberately stale or broken fixture fails before merge. | -| Scale | Variants, structured docs search, release automation, and evaluation suites. | Additional products or platforms do not create parallel content ownership. | - -Do not begin with a large generated skill catalog or autonomous publishing workflow. -Begin with one high-value user journey and prove the complete source-to-retrieval-to-verification loop. - -## Map the NemoClaw Implementation - -The current NemoClaw repository provides concrete examples for each layer. - -| Concern | NemoClaw implementation | -|---|---| -| Canonical content | `docs/**/*.mdx`. | -| Repository-wide documentation contract | `AGENTS.md`. | -| Authoring and review policy | `docs/CONTRIBUTING.md` and `docs/AGENTS.md`. | -| Navigation and published guide variants | `docs/index.yml`. | -| Intentional partial guide variant scope | Source `agent-variants` frontmatter validated by `scripts/sync-agent-variant-docs.mts`. | -| Site and redirect configuration | `fern/docs.yml` and `fern/fern.config.json`. | -| Machine delivery | Published Markdown routes, `llms.txt`, and the read-only docs MCP server. | -| Routing skill | `.agents/skills/nemoclaw-user-guide/SKILL.md`. | -| Starter prompt | `docs/resources/starter-prompt.md` and `scripts/generate-starter-prompt.mts`. | -| Product-owned generated facts | `ci/platform-matrix.json` and `scripts/generate-platform-docs.py`. | -| Guide variant generation | `scripts/sync-agent-variant-docs.mts`. | -| Route validation | `scripts/check-docs-published-routes.mts`. | -| Update workflow | `.agents/skills/nemoclaw-contributor-update-docs/SKILL.md`. | -| Documentation review receipt | `.github/PULL_REQUEST_TEMPLATE.md`, `.github/workflows/docs-review-receipt.yaml`, and `scripts/docs-review-receipt.mts`. | -| Information-architecture workflow | `.agents/skills/nemoclaw-maintainer-refactor-docs/SKILL.md`. | -| Pull-request assurance | Docs link, product parity, and preview workflows under `.github/workflows/`. | -| Release history | Dated entries under `docs/changelog/` that land before the release tag. | -| Release publication | Staging publication from `main` and public publication from release tags. | - -Use this map as a reference architecture, not a requirement to adopt the same vendor or repository layout. -Preserve the contracts when adapting the implementation. - -## Review Readiness - -Before calling a documentation system agent-ready, confirm the following conditions: - -- One governed source produces the human and machine documentation experiences. -- Every priority task has routing metadata, a stable machine-readable route, and a verification step. -- Search, the docs index, and rendered navigation resolve to the same release and canonical owner. -- Routing prompts and skills point to the source instead of copying it. -- Guide variant generation is deterministic, partial scope declarations match published routes, and guide variant behavior is tested. -- Agent workflows define scope, approvals, stop conditions, and completion evidence. -- Code-changing and documentation-only pull requests record a documentation-review result tied to the current head and instruction version. -- New commits invalidate the recorded review until the documentation writer subagent runs again. -- Pull requests validate generated output, routes, links, product parity, and rendered previews. -- Release publication uses an approved immutable revision. -- Retrieval, citation, task, guide variant, safety, and freshness regressions have repeatable evaluations. - -The first practical milestone is one product journey that passes every condition above. -Expand the system only after that loop is reliable. diff --git a/docs/resources/generate-documentation-variants.mdx b/docs/resources/generate-documentation-variants.mdx new file mode 100644 index 0000000000..6d1cd2d2ff --- /dev/null +++ b/docs/resources/generate-documentation-variants.mdx @@ -0,0 +1,184 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Generate Documentation Variants" +sidebar-title: "Generate Docs Variants" +description: "Generate product or agent documentation variants from shared MDX without duplicating canonical sources." +description-agent: "Explains when to share or separate variant sources, how NemoClaw resolves host CLI placeholders and AgentOnly directives, how navigation maps generated targets, and how to validate the route graph. Use when authoring or reviewing multi-variant documentation." +keywords: ["documentation variants", "AgentOnly", "MDX generation", "Fern navigation", "shared documentation source"] +content: + type: "how_to" +--- + +Generate documentation variants only when most of the source is shared. +Keep the canonical explanation in one MDX page, make behavioral differences explicit, and treat generated files as disposable build output. + +## Generate Variants Without Duplicating Sources + +Many products publish documentation for editions, platforms, runtimes, or deployment models. +Generate a variant only when most of the source is shared. + +Use these rules: + +- Replace a build-time placeholder when only a literal name or command differs. +- Use a conditional block when the workflow, behavior, state layout, or security boundary differs. +- Use a separate source page when most of the procedure is variant-specific. +- Keep published guide variant membership and route slugs in the navigation model. +- Declare the intended guide variant subset in source metadata when a page does not apply to every guide variant. +- Regenerate every guide variant before route and link validation. +- Inspect rendered guide variants for broken lists, joined paragraphs, and missing context. + +NemoClaw generates shared OpenClaw, Hermes, and Deep Agents guide variants from one MDX source. +Its build rewrites the host CLI placeholder, removes inapplicable conditional blocks, and publishes a distinct route for each guide variant. + +### Separate the Source from Its Guide Variant Targets + +Authors edit the normal source page under `docs/`. +For this page, the only source is `docs/resources/generate-documentation-variants.mdx`. +The repository does not maintain separate OpenClaw, Hermes, and Deep Agents source copies. + +### Author Shared and Variant-Specific Content + +Write ordinary prose once when the meaning is the same for every supported agent. +Use the $$nemoclaw placeholder when the only difference is the host CLI binary name. +The variant build resolves that placeholder as follows: + +| Generated variant | Placeholder output | +|---|---| +| OpenClaw | `nemoclaw`. | +| Hermes | `nemohermes`. | +| Deep Agents | `nemo-deepagents`. | + +Use the placeholder in prose, inline code, and fenced command examples on shared source pages. +Do not duplicate a paragraph or command block only to change the binary name. +Do not use the placeholder on a single-variant source page because that page does not pass through variant generation and would publish the placeholder literally. + +Use an `` block when the content differs by behavior, workflow, state layout, support, or agent-specific wording. +For example, start a Hermes-only block with <AgentOnly variant="hermes"> and close it with </AgentOnly>. +The `variant` attribute can name one variant or a comma-separated set such as `openclaw,hermes`. + +Do not import `AgentOnly` from a React component. +The canonical page is an intermediate source that the variant resolver compiles before Fern reads it. +The resolver removes the directive tags and keeps the block body only when the target variant appears in the `variant` attribute. + +Apply this decision rule: + +- Use ordinary shared prose when the meaning is identical. +- Use the host CLI placeholder when only the binary name differs. +- Use `` when the meaning or procedure differs. +- Use a separate source page when most of the page is specific to one agent. + +This page encodes the two dollar signs as character entities so a future generated variant can display the literal placeholder instead of resolving it. + +### Treat `AgentOnly` as a Build-Time Directive + +The `` syntax resembles an MDX component, but NemoClaw treats it as a build-time directive. +Agent variant selection does not depend on pathname detection or client-side logic in the rendered site. +The canonical source does not need an import because Fern receives only the resolved generated page. + +For each navigation target, `scripts/sync-agent-variant-docs.mts` reads the requested variant from `docs/index.yml` and parses the canonical source as text. +When an `` directive lists the active variant, the resolver copies its content into the generated page. +When the retained content starts with a Markdown list item, it discards blank lines immediately inside the opening and closing tags so wrapper formatting does not split the list. +For other retained content, it preserves those boundary blank lines and all interior blank lines so paragraphs and code sections keep their intended separation. +When the directive does not list the active variant, the resolver omits the body. +In both cases, it removes the opening and closing directive tags before writing the generated MDX. + +Keep the opening and closing `` tags at the first column on their own lines, and do not nest these blocks. +That line-oriented structure is the generator's authoring interface, and the resolver reports nested, unexpected, or unclosed blocks as errors. + +The `CLI_SENTINEL` constant and replacement table live in `scripts/sync-agent-variant-docs.mts` so placeholders can be resolved inside frontmatter, ordinary prose, inline code, and fenced command blocks before Fern renders the page. +Use $$nemoclaw for all shared host CLI references and wrap it in backticks when it should render as inline code. + +The resolver rejects a generated page if it still contains an unresolved line-oriented `` directive or a runtime agent component. +These checks make static resolution a publishing invariant instead of relying on client-side hydration to correct variant content. + +Published guide variant membership is explicit in `docs/index.yml`. +Each guide variant contains its own navigation tree, and a shared page appears in a tree through a generated target path with this contract: + +```text +_build/agent-variants//..generated.mdx +``` + +The `` value is `openclaw`, `hermes`, or `deepagents`. +The directory and base name before the guide variant suffix must match the canonical source path under `docs/`. + +When a source intentionally applies to fewer than all three guide variants, its frontmatter declares the exact subset: + +```yaml +agent-variants: ["openclaw", "hermes"] +``` + +The generator compares this declaration with the source's actual navigation membership and fails when the declaration is missing or differs. +An all-variant source omits the declaration, so removing one of its navigation targets also fails until the author restores the route or explicitly declares the narrower scope. + +This page uses the following published mapping: + +| Guide variant | Generated target in `docs/index.yml` | Published route suffix | +|---|---|---| +| OpenClaw | `_build/agent-variants/resources/generate-documentation-variants.openclaw.generated.mdx` | `/user-guide/openclaw/resources/documentation-engineering/generate-documentation-variants`. | +| Hermes | `_build/agent-variants/resources/generate-documentation-variants.hermes.generated.mdx` | `/user-guide/hermes/resources/documentation-engineering/generate-documentation-variants`. | +| Deep Agents | `_build/agent-variants/resources/generate-documentation-variants.deepagents.generated.mdx` | `/user-guide/deepagents/resources/documentation-engineering/generate-documentation-variants`. | + +The site and version prefixes are added by the Fern site configuration. +The route suffix comes from the variant, section, group, and page slug hierarchy in `docs/index.yml`. + +### Use the Fern Index as the Mapping Layer + +The version entry in `fern/docs.yml` points Fern to `docs/index.yml`. +That index defines the navigation and published route tree for every supported agent variant. + +The OpenClaw navigation entry for this page uses the following shape: + +```yaml +- page: "Generate Documentation Variants" + path: _build/agent-variants/resources/generate-documentation-variants.openclaw.generated.mdx + slug: generate-documentation-variants +``` + +The `path` tells Fern which generated MDX file to render. +The `slug` tells Fern the page's final route segment. +The surrounding `documentation-engineering` group, `resources` section, and `openclaw` variant contribute the parent route segments. + +This separation has several consequences: + +- A source file's filesystem location does not independently define its public URL. +- The same source can be published in several variant trees with the same page slug. +- A source page can apply to one guide variant by declaring that guide variant in frontmatter and pointing navigation directly to its source MDX file instead of a generated target. +- Moving or renaming a published page requires a navigation update and a redirect review, even when the source file stays in the same directory. +- Generated filenames are an interface with the generator and should not use an arbitrary naming pattern. + +### Resolve and Render Each Target + +The resolver is `scripts/sync-agent-variant-docs.mts`. +Run it directly through `npm run docs:sync-agent-variants`, or let `npm run docs` invoke it through the shared `docs:prepare` step. + +The script reads `docs/index.yml` before it reads shared source pages. +It derives each source page's published guide variant membership and validates every intentional subset declaration before rendering. +For each recognized generated path, it then performs the following work: + +1. It reads the active guide variant from the `openclaw`, `hermes`, or `deepagents` navigation tree. +2. It removes the `_build/agent-variants/` prefix and the `..generated.mdx` suffix. +3. It resolves the remaining path to one canonical `.mdx` source under `docs/`. +4. It renders that source for the active guide variant. +5. It writes the result under `docs/_build/agent-variants/` using the path declared in the index. +6. It removes stale generated files that no longer have a navigation target. + +Rendering replaces the host CLI placeholder with the correct binary name, removes conditional blocks that do not apply to the active guide variant, and adjusts relative image and component-import paths for the deeper generated directory. +Route-style links between documentation pages stay tied to the published navigation model instead of the generated filesystem location. + +The generated directory is ignored by Git. +Contributors commit the canonical source and `docs/index.yml` mapping, while the docs build recreates the variant files locally and in CI. + +### Validate the Complete Route Graph + +The `npm run docs` command prepares generated content before Fern validation. +The validation sequence checks the starter prompt, validates declared guide variant scope, regenerates the guide variants, verifies generated-page freshness, derives published routes from `docs/index.yml`, and runs the pinned Fern checker. + +This order matters because Fern cannot validate a guide variant route until the generated target named by `docs/index.yml` exists. +It also ensures that source edits, guide variant transforms, navigation mappings, and published routes are tested as one contract. + +## Related Topics + +- [Design Agent-Ready Documentation](design-agent-ready-documentation) explains canonical ownership and machine-readable delivery. +- [Automate Documentation Workflows](automate-documentation-workflows) explains how generated documentation fits the engineering loop. +- [Govern and Evaluate Agentic Documentation](govern-agentic-documentation) defines assurance and publication controls. diff --git a/docs/resources/govern-agentic-documentation.mdx b/docs/resources/govern-agentic-documentation.mdx new file mode 100644 index 0000000000..707c861091 --- /dev/null +++ b/docs/resources/govern-agentic-documentation.mdx @@ -0,0 +1,157 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Govern and Evaluate Agentic Documentation" +sidebar-title: "Govern and Evaluate Docs" +description: "Set publication boundaries, assurance gates, human ownership, and quality measures for agentic documentation." +description-agent: "Defines executable documentation gates, product scope controls, human-owned decisions, retrieval and task-quality measures, phased adoption, and readiness criteria. Use when governing automated documentation or evaluating whether a documentation system is agent-ready." +keywords: ["documentation governance", "agentic documentation evaluation", "documentation quality gates", "retrieval accuracy", "docs readiness"] +content: + type: "how_to" +--- + +Treat documentation as a product surface with deterministic assurance, explicit publication boundaries, and outcome-based evaluation. +Agents can execute repeatable checks and workflows, while maintainers retain ownership of product scope, information architecture, and editorial policy. + +## Treat Documentation as an Executable Product Surface + +Build deterministic checks around the contracts that matter to users and agents. +Syntax validation alone does not catch behavioral drift. + +| Gate | Defect it prevents | NemoClaw example | +|---|---|---| +| Source formatting | Unreadable diffs and inconsistent authoring. | Markdown linting, one sentence per source line, and copyable command rules. | +| Guide variant scope | A page is omitted from an applicable guide or silently published for the wrong agent. | Source `agent-variants` declarations checked against navigation membership. | +| Generated freshness | Stale prompts or guide variants. | Build-time generation followed by read-only freshness checks. | +| Route graph | Links or redirects that target unpublished pages. | Published-route validation derived from `docs/index.yml`. | +| Product parity | Reference documentation that disagrees with the product. | CLI command, flag, installer, and environment-variable parity checks. | +| Pull-request preview | Layout or navigation failures hidden by source checks. | An isolated Fern preview for each docs pull request. | +| Staging publish | A merge that cannot produce the deployed site. | Validation and publication from `main`. | +| Public release gate | Public docs from an unapproved or detached revision. | Release-tag publication only when the tagged commit is reachable from `main`. | + +Run the narrowest checks on every relevant change and keep broader checks at integration or release boundaries. +Tests should derive routes and behavior from the same source models used by the product instead of maintaining a second hard-coded catalog. + +## Govern What Agents May Publish + +Fast documentation automation needs a stronger scope gate, not a weaker one. +Documentation can accidentally turn an experiment into an apparent supported product surface. + +Define the following controls: + +- Require an accepted product decision before documenting a new integration, recipe, or supported workflow as canonical behavior. +- Maintain an explicit skip list for merged features that are not ready for public documentation. +- Block restricted terms and private implementation details from generated output. +- Separate public user guidance from contributor and maintainer procedures. +- Require agent workflows to stop before handling secrets, changing accounts, or performing destructive operations without approval. +- Assign an owner and lifecycle expectation to every canonical page and generated artifact. + +NemoClaw applies the same scope gate to code review and documentation review. +A working example and a green build establish technical evidence, but they do not establish product approval. + +## Keep High-Judgment Work Human-Owned + +Agents execute documented rules well when the repository gives them accurate context and deterministic checks. +People remain responsible for decisions that create or change those rules. + +Keep human ownership over the following work: + +- Decide whether a feature, integration, or workflow is a supported product surface. +- Decide which user problem a page owns and where readers should encounter it. +- Resolve conflicts between implementation details, product intent, security requirements, and user expectations. +- Restructure sections when accumulated changes reveal a better organization. +- Set the editorial voice, evidence standard, release narrative, and publication policy. +- Review recurring agent mistakes and improve the instructions, skills, tests, or source structure that allowed them. + +Formal information-architecture terminology can help teams discuss this work, but the terminology is not the source of quality. +If you can recognize that a page is doing too many jobs, decide where a user expects to find a topic, and give each topic one clear owner, you are already practicing the part of information architecture that this operating model needs. + +The durable division of labor is concise. +Agents handle repeatable work close to the engineering source, while people own product meaning, system design, exceptions, and editorial judgment. + +## Measure Retrieval and Task Quality + +Measure whether agents can complete documentation-backed tasks, not only whether pages receive traffic. + +Track a small evaluation set across common and high-risk user journeys: + +- Retrieval accuracy, measured by whether the intended canonical page appears in the first results. +- Variant accuracy, measured by whether the answer stays within the selected platform or product edition. +- Citation coverage, measured by whether behavior claims point to the current source page. +- Task completion, measured by whether the documented procedure reaches its success check. +- Safety compliance, measured by whether the agent stops at approval, credential, and destructive-action boundaries. +- Freshness, measured by the delay between a product change and its verified documentation update. +- Editorial intervention, measured by how often routine documentation changes require a manual rewrite after the agent follows the repository workflow. +- Drift detection, measured by which parity gate catches an intentionally stale fixture. + +Keep evaluation prompts versioned with the documentation system. +Add a regression case when a user report or review reveals that an agent selected the wrong source, mixed variants, skipped a safety boundary, or failed to verify the outcome. + +## Adopt the Model in Phases + +Build the smallest complete loop first, then add sophistication where evidence shows a need. + +| Phase | Deliverable | Exit condition | +|---|---|---| +| Foundation | One canonical, task-oriented Markdown or MDX corpus. | Humans can complete one priority journey from the source docs. | +| Machine delivery | Stable Markdown routes and a lightweight index. | An agent can retrieve and cite the same priority journey without scraping HTML. | +| Routing | A starter prompt and thin routing skill. | The agent selects the correct page, variant, and verification step. | +| Workflow | Repository instructions and an update-docs workflow. | A product change produces a traceable docs-impact decision. | +| Assurance | Route, link, generation, parity, and preview gates. | A deliberately stale or broken fixture fails before merge. | +| Scale | Variants, structured docs search, release automation, and evaluation suites. | Additional products or platforms do not create parallel content ownership. | + +Do not begin with a large generated skill catalog or autonomous publishing workflow. +Begin with one high-value user journey and prove the complete source-to-retrieval-to-verification loop. + +## Map the NemoClaw Implementation + +The current NemoClaw repository provides concrete examples for each layer. + +| Concern | NemoClaw implementation | +|---|---| +| Canonical content | `docs/**/*.mdx`. | +| Repository-wide documentation contract | `AGENTS.md`. | +| Authoring and review policy | `docs/CONTRIBUTING.md` and `docs/AGENTS.md`. | +| Navigation and published guide variants | `docs/index.yml`. | +| Intentional partial guide variant scope | Source `agent-variants` frontmatter validated by `scripts/sync-agent-variant-docs.mts`. | +| Site and redirect configuration | `fern/docs.yml` and `fern/fern.config.json`. | +| Machine delivery | Published Markdown routes, `llms.txt`, and the read-only Model Context Protocol (MCP) docs server. | +| Routing skill | `.agents/skills/nemoclaw-user-guide/SKILL.md`. | +| Starter prompt | `docs/resources/starter-prompt.md` and `scripts/generate-starter-prompt.mts`. | +| Product-owned generated facts | `ci/platform-matrix.json` and `scripts/generate-platform-docs.py`. | +| Guide variant generation | `scripts/sync-agent-variant-docs.mts`. | +| Route validation | `scripts/check-docs-published-routes.mts`. | +| Update workflow | `.agents/skills/nemoclaw-contributor-update-docs/SKILL.md`. | +| Documentation review receipt | `.github/PULL_REQUEST_TEMPLATE.md`, `.github/workflows/docs-review-receipt.yaml`, and `scripts/docs-review-receipt.mts`. | +| Information-architecture workflow | `.agents/skills/nemoclaw-maintainer-refactor-docs/SKILL.md`. | +| Pull-request assurance | Docs link, product parity, and preview workflows under `.github/workflows/`. | +| Release history | Dated entries under `docs/changelog/` that land before the release tag. | +| Release publication | Staging publication from `main` and public publication from release tags. | + +Use this map as a reference architecture, not a requirement to adopt the same vendor or repository layout. +Preserve the contracts when adapting the implementation. + +## Review Readiness + +Before calling a documentation system agent-ready, confirm the following conditions: + +- One governed source produces the human and machine documentation experiences. +- Every priority task has routing metadata, a stable machine-readable route, and a verification step. +- Search, the docs index, and rendered navigation resolve to the same release and canonical owner. +- Routing prompts and skills point to the source instead of copying it. +- Guide variant generation is deterministic, partial scope declarations match published routes, and guide variant behavior is tested. +- Agent workflows define scope, approvals, stop conditions, and completion evidence. +- Code-changing and documentation-only pull requests record a documentation-review result tied to the current head and instruction version. +- New commits invalidate the recorded review until the documentation writer subagent runs again. +- Pull requests validate generated output, routes, links, product parity, and rendered previews. +- Release publication uses an approved immutable revision. +- Retrieval, citation, task, guide variant, safety, and freshness regressions have repeatable evaluations. + +The first practical milestone is one product journey that passes every condition above. +Expand the system only after that loop is reliable. + +## Related Topics + +- [Design Agent-Ready Documentation](design-agent-ready-documentation) defines the source, delivery, and routing architecture. +- [Automate Documentation Workflows](automate-documentation-workflows) explains update, review, and curation workflows. +- [Generate Documentation Variants](generate-documentation-variants) explains shared-source variant generation and route validation. diff --git a/docs/security/hermes-0.19.0-dependency-review.md b/docs/security/hermes-0.19.0-dependency-review.md index e69ab9929d..573e9506e3 100644 --- a/docs/security/hermes-0.19.0-dependency-review.md +++ b/docs/security/hermes-0.19.0-dependency-review.md @@ -71,7 +71,8 @@ The outgoing release restricted cookies, storage, clipboard, form values, and ne Because NemoClaw exposes the browser toolset, generated configuration now writes `browser.restrict_evaluate: true` to preserve that fail-closed posture; broadening page-context JavaScript evaluation requires a separate security decision. Hermes 0.19 changes the omitted gateway session-reset policy from `both` (daily and idle expiry) to `none`. -Generated configuration now writes the complete outgoing policy—`mode: both`, 04:00 daily reset, 1,440-minute idle reset, notifications except on API server and webhook, and a 24-hour background-process age bound—so the upgrade does not silently make gateway sessions indefinitely durable or leave the remaining policy to mutable dependency defaults. +Generated configuration now writes the complete outgoing policy: `mode: both`, 04:00 daily reset, 1,440-minute idle reset, notifications except on API server and webhook, and a 24-hour background-process age bound. +This prevents the upgrade from silently making gateway sessions indefinitely durable or leaving the remaining policy to mutable dependency defaults. Hermes 0.19 also changes `display.show_reasoning` from `false` to `true`. Generated configuration now writes `display.show_reasoning: false` so internal reasoning is not newly disclosed through user-visible channel output. diff --git a/test/check-docs-published-routes.test.ts b/test/check-docs-published-routes.test.ts index 62b9cdc535..ec0840fbcb 100644 --- a/test/check-docs-published-routes.test.ts +++ b/test/check-docs-published-routes.test.ts @@ -459,6 +459,64 @@ describe("Manage Sandboxes extension routes", () => { index.routes.has("/user-guide/deepagents/manage-sandboxes/install-openclaw-plugins"), ).toBe(false); }); + + it("publishes the Deep Agents runtime guide only in the Deep Agents guide", () => { + const source = "manage-sandboxes/run-deep-agents-code.mdx"; + const quickstartSource = "get-started/quickstart-langchain-deepagents-code.mdx"; + const quickstart = readFileSync(path.join(repoRoot, "docs", quickstartSource), "utf8"); + + expect(index.sourceToRoutes.get(source)?.map(({ route }) => route)).toEqual([ + "/user-guide/deepagents/manage-sandboxes/operate-sandboxes/run-deep-agents-code", + ]); + expect(findBrokenPublishedRoutes(source, index)).toEqual([]); + expect(findBrokenPublishedRoutes(quickstartSource, index)).toEqual([]); + expect(quickstart.split('')).toHaveLength(2); + expect(quickstart).toContain( + "[Run Deep Agents Code](../manage-sandboxes/operate-sandboxes/run-deep-agents-code)", + ); + expect( + index.routes.has( + "/user-guide/openclaw/manage-sandboxes/operate-sandboxes/run-deep-agents-code", + ), + ).toBe(false); + expect( + index.routes.has( + "/user-guide/hermes/manage-sandboxes/operate-sandboxes/run-deep-agents-code", + ), + ).toBe(false); + }); +}); + +describe("Documentation Engineering routes", () => { + const index = buildPublishedRouteIndex(); + const pages = [ + "design-agent-ready-documentation", + "automate-documentation-workflows", + "generate-documentation-variants", + "govern-agentic-documentation", + ] as const; + + it("publishes every focused page under the non-clickable group for every agent variant", () => { + for (const page of pages) { + const source = `resources/${page}.mdx`; + + expect(index.sourceToRoutes.get(source)?.map(({ route }) => route)).toEqual([ + `/user-guide/openclaw/resources/documentation-engineering/${page}`, + `/user-guide/deepagents/resources/documentation-engineering/${page}`, + `/user-guide/hermes/resources/documentation-engineering/${page}`, + ]); + expect(findBrokenPublishedRoutes(source, index)).toEqual([]); + } + }); + + it("does not publish a stale route for the retired source-only guide", () => { + expect(index.sourceToRoutes.has("resources/engineer-agentic-documentation.mdx")).toBe(false); + for (const variant of ["openclaw", "deepagents", "hermes"]) { + expect( + index.routes.has(`/user-guide/${variant}/resources/engineer-agentic-documentation`), + ).toBe(false); + } + }); }); describe("headless server deployment routes", () => { From c93b61bd37c1e95cd4b6c48bc231f96ea9f3a9e3 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Thu, 30 Jul 2026 15:40:34 -0700 Subject: [PATCH 2/8] docs: restore agentic documentation page --- docs/index.yml | 54 +- .../automate-documentation-workflows.mdx | 169 ----- .../design-agent-ready-documentation.mdx | 159 ----- .../engineer-agentic-documentation.mdx | 604 ++++++++++++++++++ .../generate-documentation-variants.mdx | 184 ------ .../govern-agentic-documentation.mdx | 157 ----- test/check-docs-published-routes.test.ts | 35 +- 7 files changed, 622 insertions(+), 740 deletions(-) delete mode 100644 docs/resources/automate-documentation-workflows.mdx delete mode 100644 docs/resources/design-agent-ready-documentation.mdx create mode 100644 docs/resources/engineer-agentic-documentation.mdx delete mode 100644 docs/resources/generate-documentation-variants.mdx delete mode 100644 docs/resources/govern-agentic-documentation.mdx diff --git a/docs/index.yml b/docs/index.yml index a1ac3bbe39..44506d3947 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -406,21 +406,9 @@ navigation: - page: "Community Solutions" path: _build/agent-variants/resources/community-contributions.openclaw.generated.mdx slug: community-contributions - - section: "Documentation Engineering" - slug: documentation-engineering - contents: - - page: "Design Agent-Ready Documentation" - path: _build/agent-variants/resources/design-agent-ready-documentation.openclaw.generated.mdx - slug: design-agent-ready-documentation - - page: "Automate Documentation Workflows" - path: _build/agent-variants/resources/automate-documentation-workflows.openclaw.generated.mdx - slug: automate-documentation-workflows - - page: "Generate Documentation Variants" - path: _build/agent-variants/resources/generate-documentation-variants.openclaw.generated.mdx - slug: generate-documentation-variants - - page: "Govern and Evaluate Agentic Documentation" - path: _build/agent-variants/resources/govern-agentic-documentation.openclaw.generated.mdx - slug: govern-agentic-documentation + - page: "Engineer Documentation for AI Agents" + path: _build/agent-variants/resources/engineer-agentic-documentation.openclaw.generated.mdx + slug: engineer-agentic-documentation - link: "Discord" href: https://discord.gg/XFpfPv9Uvx - link: "Report Vulnerabilities" @@ -737,21 +725,9 @@ navigation: - page: "Community Solutions" path: _build/agent-variants/resources/community-contributions.deepagents.generated.mdx slug: community-contributions - - section: "Documentation Engineering" - slug: documentation-engineering - contents: - - page: "Design Agent-Ready Documentation" - path: _build/agent-variants/resources/design-agent-ready-documentation.deepagents.generated.mdx - slug: design-agent-ready-documentation - - page: "Automate Documentation Workflows" - path: _build/agent-variants/resources/automate-documentation-workflows.deepagents.generated.mdx - slug: automate-documentation-workflows - - page: "Generate Documentation Variants" - path: _build/agent-variants/resources/generate-documentation-variants.deepagents.generated.mdx - slug: generate-documentation-variants - - page: "Govern and Evaluate Agentic Documentation" - path: _build/agent-variants/resources/govern-agentic-documentation.deepagents.generated.mdx - slug: govern-agentic-documentation + - page: "Engineer Documentation for AI Agents" + path: _build/agent-variants/resources/engineer-agentic-documentation.deepagents.generated.mdx + slug: engineer-agentic-documentation - link: "Report Vulnerabilities" href: https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md - page: "License" @@ -1131,21 +1107,9 @@ navigation: - page: "Community Solutions" path: _build/agent-variants/resources/community-contributions.hermes.generated.mdx slug: community-contributions - - section: "Documentation Engineering" - slug: documentation-engineering - contents: - - page: "Design Agent-Ready Documentation" - path: _build/agent-variants/resources/design-agent-ready-documentation.hermes.generated.mdx - slug: design-agent-ready-documentation - - page: "Automate Documentation Workflows" - path: _build/agent-variants/resources/automate-documentation-workflows.hermes.generated.mdx - slug: automate-documentation-workflows - - page: "Generate Documentation Variants" - path: _build/agent-variants/resources/generate-documentation-variants.hermes.generated.mdx - slug: generate-documentation-variants - - page: "Govern and Evaluate Agentic Documentation" - path: _build/agent-variants/resources/govern-agentic-documentation.hermes.generated.mdx - slug: govern-agentic-documentation + - page: "Engineer Documentation for AI Agents" + path: _build/agent-variants/resources/engineer-agentic-documentation.hermes.generated.mdx + slug: engineer-agentic-documentation - link: "Report Vulnerabilities" href: https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md - page: "License" diff --git a/docs/resources/automate-documentation-workflows.mdx b/docs/resources/automate-documentation-workflows.mdx deleted file mode 100644 index 919a9347ae..0000000000 --- a/docs/resources/automate-documentation-workflows.mdx +++ /dev/null @@ -1,169 +0,0 @@ ---- -# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 -title: "Automate Documentation Workflows" -sidebar-title: "Automate Docs Workflows" -description: "Embed documentation updates, review evidence, and periodic curation in the engineering workflow." -description-agent: "Explains repository-embedded documentation updates, observable review receipts, workflow adoption metrics, bounded agent workflows, and periodic corpus curation. Use when automating documentation maintenance or measuring whether the workflow is followed." -keywords: ["documentation automation", "documentation review receipt", "docs workflow", "docs adoption metrics", "documentation curation"] -content: - type: "how_to" ---- - -Place documentation work close to the product change so the implementation, tests, and user guidance can be reviewed together. -Use observable workflow evidence and periodic information-architecture maintenance to keep routine updates accurate without turning every pull request into a restructuring project. - -## Move Documentation Into the Engineering Loop - -Many documentation workflows begin after engineering work is complete. -The writer identifies which features are shipping, finds the responsible engineers, interviews them to reconstruct the behavior, and then creates a separate documentation change. -This manual intake phase consumes time and can lose important context between implementation and publication. - -NemoClaw moves routine documentation work into the developer's engineering pull request. -The agent working on the developer's machine can inspect the code, tests, issue, and pull-request context while the change is still fresh. -Repository instructions tell that agent when documentation is required, where the content belongs, how to write it, and which checks prove the result. - -| Stage | Separate documentation handoff | Repository-embedded workflow | -|---|---|---| -| Discover changes | A writer collects release scope from meetings, messages, and issue lists. | The developer's agent inspects the current diff, issue, and changed behavior. | -| Transfer knowledge | A writer interviews engineers and reconstructs implementation details. | The agent reads the implementation and tests, then asks only when a decision or supported contract is unclear. | -| Draft documentation | A writer creates a later documentation task or pull request. | The agent updates the canonical page in the engineering pull request. | -| Review accuracy | Documentation and implementation may be reviewed at different times. | Reviewers see the behavior, tests, and documentation together. | -| Prepare a release | A writer performs a broad catch-up pass before publication. | Continuous updates reduce catch-up work, while the release workflow verifies completeness and creates the canonical changelog entry. | - -The repository provides a control stack for this workflow: - -- The root `AGENTS.md` defines repository-wide success criteria, product scope, and documentation expectations. -- `docs/AGENTS.md` defines the documentation role, source-of-truth rules, variant patterns, and verification requirements. -- `docs/CONTRIBUTING.md` defines the public writing, navigation, release, and review contracts. -- The `nemoclaw-contributor-update-docs` skill maps product changes to canonical pages and produces an evidence-backed documentation update. -- Build scripts, tests, hooks, previews, and publication workflows enforce the contracts after the agent edits the files. - -The expected pull-request loop is direct: - -1. The developer's agent reads the repository and documentation instructions. -2. It inspects the implemented behavior and its tests. -3. It decides whether the change has user-facing documentation impact. -4. It updates the canonical page in the same pull request when documentation is required. -5. It runs the relevant documentation and product-parity checks. -6. It reports the pages changed, behavior represented, and verification evidence. - -This model removes the need for a writer to manually reconstruct every incremental product change. -It does not remove documentation ownership. -It shifts the writer's role toward designing the system, maintaining the instructions, monitoring outcomes, and handling work that requires editorial judgment. -When the instructions are working, the writer can review by exception. -Routine pull-request updates that already meet the documentation contract do not need line editing, so the writer can focus on unclear product scope, structural pressure, and recurring failure patterns. - -## Make Documentation Review Observable - -A repository instruction can require a documentation writer subagent, but the instruction alone does not show whether an engineering agent followed it. -Add a structured pull-request receipt so each code or documentation change produces observable documentation-review evidence. - -NemoClaw records the following fields in the Documentation Writer Review section of the pull-request description: - -- A completed-review checkbox. -- One result: `docs-updated`, `no-docs-needed`, or `blocked`. -- Evidence that names the changed documentation or explains the result. -- The agent product and surface that ran the review. -- Hidden metadata for the reviewed head SHA and the `AGENTS.md` blob SHA. - -Keep one instance of each field. -GitHub supplies the pull-request identity to the workflow and report. -The head SHA binds the review to one pull-request revision. -The `AGENTS.md` blob SHA records which repository instruction version the review covered. - -Use the following sequence for a pull request that changes code or documentation: - -1. Run the documentation writer subagent after the changes and applicable validation are complete. -2. For code changes, update the canonical documentation or record why no documentation change is required. -3. For documentation changes, verify the writing rules and documentation style. -4. Commit all changes from the review. -5. Complete the visible receipt and hidden metadata for the committed head. -6. Rerun the documentation review after any later commit. - -The `CI / Documentation Writer Review` workflow runs when a pull request opens or reopens, when its description is edited, or when it receives a new commit. -It compares the receipt with the current head and current `AGENTS.md` blob. -A new commit makes the previous receipt stale until the documentation writer subagent runs again and refreshes the metadata. -The checker evaluates code-changing and documentation-only pull requests. -For documentation-only changes, the receipt records the agent's review of writing rules and documentation style. -NemoClaw keeps this check advisory during the data-collection pilot. - - -A valid receipt does not prove that an agent loaded or understood `AGENTS.md`. -It records observable workflow compliance that can be compared with documentation outcomes. - - -### Measure Workflow Adoption - -Export receipt data from pull-request descriptions with the authenticated GitHub CLI session. -The report returns JSON by default and also supports CSV and summary output. - -```bash -npm run docs-review:report -- --since 2026-07-01 --format summary -``` - -Use a consistent reporting window and track the following measures: - -| Measure | What it shows | -|---|---| -| Eligible pull requests | The total in `eligiblePrs`, plus the code and documentation-only counts in `eligibleCodePrs` and `eligibleDocsOnlyPrs`. | -| Receipt coverage | The share of eligible code-changing and documentation-only pull requests that contain a receipt. | -| Valid receipt rate | The share of eligible pull requests whose receipt has one complete and consistent set of fields. | -| Fresh receipt rate | The share of recorded receipts tied to the pull request's current head. | -| Result distribution | The number of receipts that report `docs-updated`, `no-docs-needed`, or `blocked`. | -| Agent surface | The agent products and surfaces recorded by valid receipts. | -| Unclassified pull requests | Pull requests whose Type of Change selection does not establish whether code or documentation changed. | - -Receipt trends show whether the repository workflow is being followed. -They do not establish that the instructions caused a documentation improvement. -Pair the report with accuracy sampling, editorial-intervention rates, and recurring review findings before changing the instruction or making the check required. - -## Encode Documentation Work as Agent Workflows - -Agentic docs include the workflows that maintain the corpus, not only the content agents retrieve. -Turn repeatable documentation engineering practices into bounded skills or repository instructions with explicit inputs, stop conditions, and evidence. - -| Workflow | Trigger | Required inputs | Completion evidence | -|---|---|---|---| -| Update docs | Product behavior changes or docs fall behind code. | Commit range, changed files, product scope, current pages. | Each user-visible change maps to an updated page or a documented no-impact decision. | -| Refactor information architecture | A section is oversized, duplicated, or hard to navigate. | Heading inventory, ownership map, inbound routes, supported variants. | One owner per topic, migrated routes, readable pages, and no content loss. | -| Review docs | A pull request changes a public procedure or reference. | Product implementation, tests, rendered preview, style policy. | Accuracy, links, route publication, and task verification pass. | -| Prepare a release | A release candidate is ready for documentation. | Merged change set, release scope, target version and date. | Canonical changelog entry lands before the release tag. | -| Publish | A docs change merges or a release tag is created. | Validated source, approved environment, immutable revision. | Staging or public output points to the expected revision. | - -NemoClaw applies this model through layered repository instructions and specialized contributor and maintainer skills. -The update workflow scans commits, respects a documentation skip list, maps behavior to canonical pages, and verifies the build. -The refactor workflow inventories every topic, defines ownership and URL migration contracts, and validates every supported variant. - -Design each workflow to produce evidence instead of a generic statement that the docs were updated. -The agent should report the files changed, source behavior represented, checks run, and intentionally deferred work. - -## Let the Corpus Grow and Tend It - -Do not require every engineering pull request to redesign the documentation structure. -Let agents make small, accurate updates to the current canonical page while the product evolves. -Restructure the corpus after repeated changes reveal its real shape. - -This is continuous growth with periodic curation. -The daily engineering loop keeps behavior and documentation aligned, while a daily or weekly maintenance pass improves sections that have outgrown their original purpose. - -Use observable signals to start a restructuring pass: - -- A page serves several distinct user tasks. -- A section has become difficult to scan or navigate. -- A paragraph contains several decisions, procedures, or failure modes. -- The same guidance appears in several pages. -- A common task is buried under an unrelated heading or navigation group. -- Product variants have started to drift because their shared and distinct behavior is unclear. - -During the maintenance pass, split overgrown pages, clarify headings, move reusable reference material to one owner, remove duplication, and preserve published routes. -If agents repeatedly produce the same structural or style problem, improve the repository instructions or workflow skill so later pull requests correct the pattern at its source. - -This cadence avoids premature reorganization while keeping the documentation usable as it grows. -It also reserves the writer's time for structure, user journeys, and editorial quality instead of routine transcription. - -## Related Topics - -- [Design Agent-Ready Documentation](design-agent-ready-documentation) defines the architecture and canonical ownership model. -- [Generate Documentation Variants](generate-documentation-variants) explains the deterministic variant build. -- [Govern and Evaluate Agentic Documentation](govern-agentic-documentation) defines scope gates and outcome measures. diff --git a/docs/resources/design-agent-ready-documentation.mdx b/docs/resources/design-agent-ready-documentation.mdx deleted file mode 100644 index ca5e2bf63f..0000000000 --- a/docs/resources/design-agent-ready-documentation.mdx +++ /dev/null @@ -1,159 +0,0 @@ ---- -# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 -title: "Design Agent-Ready Documentation" -sidebar-title: "Design Agent-Ready Docs" -description: "Design a governed documentation architecture that serves people and AI agents from one canonical source." -description-agent: "Defines the product contract, layered architecture, canonical ownership, machine-readable delivery paths, and thin routing needed for agent-ready documentation. Use when designing an agentic documentation system or assigning canonical content ownership." -keywords: ["agent-ready documentation", "documentation architecture", "canonical documentation", "llms.txt", "docs MCP server"] -content: - type: "how_to" ---- - -Agent-ready documentation helps an AI agent find the right source, apply it to the user's context, take bounded action, and verify the result. -It serves people and agents from one governed source instead of maintaining a website, prompt library, and skill catalog as separate bodies of content. - -This page defines the architecture for that system. -The file names and tools are NemoClaw examples, but the contracts apply to any docs-as-code stack. - - -Making HTML available to a model is not enough. -An agent-ready system needs explicit retrieval paths, task metadata, stable routes, safety boundaries, and evidence that the published guidance still matches the product. - - -## Define the Product Contract - -Start with observable outcomes instead of selecting tools. -A reliable agentic documentation system supports the following contract. - -| Capability | Contract | Evidence | -|---|---|---| -| Discover | The agent can identify the relevant document for a user task. | A task query returns the intended page and variant. | -| Retrieve | The agent can fetch clean, current, citable content. | A stable Markdown route or read-only search tool returns the canonical source. | -| Apply | The guidance includes decisions, prerequisites, steps, and boundaries. | The agent produces instructions scoped to the user's environment. | -| Act | The agent knows which operations are safe, which need approval, and which are out of scope. | Workflow instructions stop before credentials, destructive changes, or unsupported surfaces. | -| Verify | Every procedure ends with an observable success check. | The agent runs or recommends the documented validation step. | -| Maintain | Product changes can be traced to documentation owners and release evidence. | Pull-request gates detect stale, missing, or unpublished guidance. | - -Treat failures in any row as documentation defects. -A polished site with weak retrieval or verification is not agent-ready. - -## Use a Layered Architecture - -Keep content, delivery, routing, workflow, and assurance separate so each layer has one responsibility. - -```mermaid -flowchart TB - PRODUCT["Authoritative product sources
Code, schemas, commands, support data"] - SOURCE["Canonical task-oriented source
Concepts, procedures, reference, troubleshooting"] - BUILD["Deterministic build
Metadata, variants, prompts, route graph"] - HUMAN["Human delivery
Rendered documentation site"] - MACHINE["Machine delivery
Markdown routes, llms.txt, read-only docs search"] - ROUTING["Agent routing
Starter prompt and thin docs skill"] - WORKFLOW["Engineering workflows
Update, refactor, review, release"] - ASSURANCE["Assurance
Parity checks, links, previews, publication gates"] - PEOPLE["Readers"] - AGENTS["User-facing agents"] - - PRODUCT --> WORKFLOW - SOURCE --> BUILD - BUILD --> HUMAN - BUILD --> MACHINE - HUMAN --> PEOPLE - MACHINE --> ROUTING - ROUTING --> AGENTS - WORKFLOW --> SOURCE - PRODUCT --> ASSURANCE - ASSURANCE --> BUILD - ASSURANCE --> WORKFLOW -``` - -The source remains authoritative throughout the loop. -Prompts, skills, generated variants, search indexes, and rendered pages are delivery or control artifacts, not alternate sources of truth. - -## Establish One Canonical Owner - -Write each fact once in its authoritative layer, then produce the human and machine experiences from one publication source. -Product behavior may be authoritative in code, schemas, command metadata, or support data, while the documentation corpus remains the canonical published explanation. -Generate structured reference content from product sources when practical and use parity tests when prose must remain hand-written. - -NemoClaw uses MDX under `docs/` as its user-facing source of truth and generates agent-specific pages during the docs build. - -Apply these source rules: - -- Give each page one primary concept or user task. -- Organize procedures around the reader journey from choosing through setup, operation, validation, and troubleshooting. -- Keep reusable troubleshooting and reference facts with one canonical owner, then link to that owner. -- Generate tables and reference values from authoritative product data when that removes manual synchronization. -- Store navigation and route slugs in a machine-readable index. -- Declare intentional partial variant scope in source metadata and validate it against published navigation membership. -- Treat generated pages as disposable build output and never edit them by hand. -- Preserve published routes with direct redirects when content moves. - -Use frontmatter to describe the page for both people and retrieval systems. -The human description explains the value of the page, while the agent description states what the page helps with and when to select it. - -```yaml ---- -title: "Configure a Private Package Registry" -description: "Connect the product to a private package registry and verify authenticated downloads." -description-agent: "Configures and validates private package registry access. Use when users ask about registry credentials, package download failures, or enterprise package mirrors." -keywords: ["private registry", "package authentication", "enterprise mirror"] -content: - type: "how_to" ---- -``` - -Good routing metadata names the user intent, scope, and likely trigger phrases. -It does not repeat the page body or make unsupported product claims. - -## Publish Machine-Readable Delivery Paths - -Publish clean content through more than one retrieval path because agent environments have different capabilities. -Use this retrieval order: - -1. Search a read-only documentation service when the client supports a structured tool such as Model Context Protocol (MCP). -2. Fetch a lightweight documentation index such as `llms.txt` when structured search is unavailable. -3. Fetch the specific Markdown page returned by search or listed in the index. -4. Fall back to rendered HTML only when a clean machine-readable route is unavailable. - -Each path should resolve to the same release and canonical page. -Do not make the agent reconcile copied content from several repositories or prompt bundles. - -Machine delivery is ready when the following checks pass: - -- Every published task page has a stable Markdown representation. -- The documentation index contains the current public route set. -- Search results return source URLs that an answer can cite. -- Variant-specific queries do not silently mix incompatible instructions. -- Moved pages redirect directly to a current published destination. -- Private drafts and unsupported features do not enter the public index. - -NemoClaw exposes its canonical pages through Markdown routes, `llms.txt`, and a read-only docs MCP server. -The [Use NemoClaw Docs with Your Coding Agents](../agent-skills) page shows the user-facing retrieval flow. - -## Keep Agent Routing Thin - -Use prompts and skills to route the agent, not to store another copy of the docs. -A routing layer should tell the agent where to look, how to choose a source, and what response constraints to follow. - -A small routing skill needs only the following elements: - -- The canonical search endpoint and fallback documentation index. -- The preferred order for retrieving pages. -- The main task areas and their starting pages. -- Variant or platform selection rules. -- Safety requirements for approvals, credentials, and destructive actions. -- Citation and verification requirements. - -This pattern keeps the routing artifact stable while the product documentation changes frequently. -It also avoids large generated skills that drift from the public site, consume context, and create ambiguous ownership. - -Pair the routing skill with a starter prompt for users who have not installed project instructions. -Keep the starter prompt in a standalone canonical file, generate any website component from that file, and test that embedded or pinned copies still match it. - -## Related Topics - -- [Automate Documentation Workflows](automate-documentation-workflows) explains how to place documentation work inside the engineering loop. -- [Generate Documentation Variants](generate-documentation-variants) explains shared-source variant generation. -- [Govern and Evaluate Agentic Documentation](govern-agentic-documentation) defines publication boundaries and quality measures. diff --git a/docs/resources/engineer-agentic-documentation.mdx b/docs/resources/engineer-agentic-documentation.mdx new file mode 100644 index 0000000000..dd3a545985 --- /dev/null +++ b/docs/resources/engineer-agentic-documentation.mdx @@ -0,0 +1,604 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Engineer Documentation for AI Agents" +sidebar-title: "Engineer Agentic Docs" +description: "A practical architecture and operating model for making technical documentation reliable for both people and AI agents." +description-agent: "Explains how to engineer agent-ready documentation with one canonical source, Markdown and MCP delivery, thin routing skills, workflow automation, review receipts, adoption metrics, variants, governance, and deterministic quality gates. Use when designing agentic documentation, docs engineering systems, AI documentation workflows, or docs-as-code automation." +keywords: ["agentic documentation", "agent-ready docs", "documentation engineering", "AI documentation workflow", "documentation review receipt", "docs as code", "llms.txt", "docs MCP server"] +content: + type: "how_to" +--- + +Agentic documentation is a documentation system that helps an AI agent find the right source, apply it to the user's context, take bounded action, and verify the result. +It serves people and agents from one governed source instead of maintaining a website, prompt library, and skill catalog as separate bodies of content. +It also places agents inside the documentation lifecycle so product changes arrive with accurate documentation instead of becoming a later handoff to a writing team. + +This guide turns the current NemoClaw documentation architecture into a reusable model for other engineering teams. +The file names and tools are NemoClaw examples, but the contracts apply to any docs-as-code stack. + + +Making HTML available to a model is not enough. +An agent-ready system needs explicit retrieval paths, task metadata, stable routes, safety boundaries, and evidence that the published guidance still matches the product. + + +## Define the Product Contract + +Start with observable outcomes instead of selecting tools. +A reliable agentic documentation system supports the following contract. + +| Capability | Contract | Evidence | +|---|---|---| +| Discover | The agent can identify the relevant document for a user task. | A task query returns the intended page and variant. | +| Retrieve | The agent can fetch clean, current, citable content. | A stable Markdown route or read-only search tool returns the canonical source. | +| Apply | The guidance includes decisions, prerequisites, steps, and boundaries. | The agent produces instructions scoped to the user's environment. | +| Act | The agent knows which operations are safe, which need approval, and which are out of scope. | Workflow instructions stop before credentials, destructive changes, or unsupported surfaces. | +| Verify | Every procedure ends with an observable success check. | The agent runs or recommends the documented validation step. | +| Maintain | Product changes can be traced to documentation owners and release evidence. | Pull-request gates detect stale, missing, or unpublished guidance. | + +Treat failures in any row as documentation defects. +A polished site with weak retrieval or verification is not agent-ready. + +## Move Documentation Into the Engineering Loop + +Many documentation workflows begin after engineering work is complete. +The writer identifies which features are shipping, finds the responsible engineers, interviews them to reconstruct the behavior, and then creates a separate documentation change. +This manual intake phase consumes time and can lose important context between implementation and publication. + +NemoClaw moves routine documentation work into the developer's engineering pull request. +The agent working on the developer's machine can inspect the code, tests, issue, and pull-request context while the change is still fresh. +Repository instructions tell that agent when documentation is required, where the content belongs, how to write it, and which checks prove the result. + +| Stage | Separate documentation handoff | Repository-embedded workflow | +|---|---|---| +| Discover changes | A writer collects release scope from meetings, messages, and issue lists. | The developer's agent inspects the current diff, issue, and changed behavior. | +| Transfer knowledge | A writer interviews engineers and reconstructs implementation details. | The agent reads the implementation and tests, then asks only when a decision or supported contract is unclear. | +| Draft documentation | A writer creates a later documentation task or pull request. | The agent updates the canonical page in the engineering pull request. | +| Review accuracy | Documentation and implementation may be reviewed at different times. | Reviewers see the behavior, tests, and documentation together. | +| Prepare a release | A writer performs a broad catch-up pass before publication. | Continuous updates reduce catch-up work, while the release workflow verifies completeness and creates the canonical changelog entry. | + +The repository provides a control stack for this workflow: + +- The root `AGENTS.md` defines repository-wide success criteria, product scope, and documentation expectations. +- `docs/AGENTS.md` defines the documentation role, source-of-truth rules, variant patterns, and verification requirements. +- `docs/CONTRIBUTING.md` defines the public writing, navigation, release, and review contracts. +- The `nemoclaw-contributor-update-docs` skill maps product changes to canonical pages and produces an evidence-backed documentation update. +- Build scripts, tests, hooks, previews, and publication workflows enforce the contracts after the agent edits the files. + +The expected pull-request loop is direct: + +1. The developer's agent reads the repository and documentation instructions. +2. It inspects the implemented behavior and its tests. +3. It decides whether the change has user-facing documentation impact. +4. It updates the canonical page in the same pull request when documentation is required. +5. It runs the relevant documentation and product-parity checks. +6. It reports the pages changed, behavior represented, and verification evidence. + +This model removes the need for a writer to manually reconstruct every incremental product change. +It does not remove documentation ownership. +It shifts the writer's role toward designing the system, maintaining the instructions, monitoring outcomes, and handling work that requires editorial judgment. +When the instructions are working, the writer can review by exception. +Routine pull-request updates that already meet the documentation contract do not need line editing, so the writer can focus on unclear product scope, structural pressure, and recurring failure patterns. + +## Make Documentation Review Observable + +A repository instruction can require a documentation writer subagent, but the instruction alone does not show whether an engineering agent followed it. +Add a structured pull-request receipt so each code or documentation change produces observable documentation-review evidence. + +NemoClaw records the following fields in the Documentation Writer Review section of the pull-request description: + +- A completed-review checkbox. +- One result: `docs-updated`, `no-docs-needed`, or `blocked`. +- Evidence that names the changed documentation or explains the result. +- The agent product and surface that ran the review. +- Hidden metadata for the reviewed head SHA and the `AGENTS.md` blob SHA. + +Keep one instance of each field. +GitHub supplies the pull-request identity to the workflow and report. +The head SHA binds the review to one pull-request revision. +The `AGENTS.md` blob SHA records which repository instruction version the review covered. + +Use the following sequence for a pull request that changes code or documentation: + +1. Run the documentation writer subagent after the changes and applicable validation are complete. +2. For code changes, update the canonical documentation or record why no documentation change is required. +3. For documentation changes, verify the writing rules and documentation style. +4. Commit all changes from the review. +5. Complete the visible receipt and hidden metadata for the committed head. +6. Rerun the documentation review after any later commit. + +The `CI / Documentation Writer Review` workflow runs when a pull request opens or reopens, when its description is edited, or when it receives a new commit. +It compares the receipt with the current head and current `AGENTS.md` blob. +A new commit makes the previous receipt stale until the documentation writer subagent runs again and refreshes the metadata. +The checker evaluates code-changing and documentation-only pull requests. +For documentation-only changes, the receipt records the agent's review of writing rules and documentation style. +NemoClaw keeps this check advisory during the data-collection pilot. + + +A valid receipt does not prove that an agent loaded or understood `AGENTS.md`. +It records observable workflow compliance that can be compared with documentation outcomes. + + +### Measure Workflow Adoption + +Export receipt data from pull-request descriptions with the authenticated GitHub CLI session. +The report returns JSON by default and also supports CSV and summary output. + +```bash +npm run docs-review:report -- --since 2026-07-01 --format summary +``` + +Use a consistent reporting window and track the following measures: + +| Measure | What it shows | +|---|---| +| Eligible pull requests | The total in `eligiblePrs`, plus the code and documentation-only counts in `eligibleCodePrs` and `eligibleDocsOnlyPrs`. | +| Receipt coverage | The share of eligible code-changing and documentation-only pull requests that contain a receipt. | +| Valid receipt rate | The share of eligible pull requests whose receipt has one complete and consistent set of fields. | +| Fresh receipt rate | The share of recorded receipts tied to the pull request's current head. | +| Result distribution | The number of receipts that report `docs-updated`, `no-docs-needed`, or `blocked`. | +| Agent surface | The agent products and surfaces recorded by valid receipts. | +| Unclassified pull requests | Pull requests whose Type of Change selection does not establish whether code or documentation changed. | + +Receipt trends show whether the repository workflow is being followed. +They do not establish that the instructions caused a documentation improvement. +Pair the report with accuracy sampling, editorial-intervention rates, and recurring review findings before changing the instruction or making the check required. + +## Use a Layered Architecture + +Keep content, delivery, routing, workflow, and assurance separate so each layer has one responsibility. + +```mermaid +flowchart TB + PRODUCT["Authoritative product sources
Code, schemas, commands, support data"] + SOURCE["Canonical task-oriented source
Concepts, procedures, reference, troubleshooting"] + BUILD["Deterministic build
Metadata, variants, prompts, route graph"] + HUMAN["Human delivery
Rendered documentation site"] + MACHINE["Machine delivery
Markdown routes, llms.txt, read-only docs search"] + ROUTING["Agent routing
Starter prompt and thin docs skill"] + WORKFLOW["Engineering workflows
Update, refactor, review, release"] + ASSURANCE["Assurance
Parity checks, links, previews, publication gates"] + PEOPLE["Readers"] + AGENTS["User-facing agents"] + + PRODUCT --> WORKFLOW + SOURCE --> BUILD + BUILD --> HUMAN + BUILD --> MACHINE + HUMAN --> PEOPLE + MACHINE --> ROUTING + ROUTING --> AGENTS + WORKFLOW --> SOURCE + PRODUCT --> ASSURANCE + ASSURANCE --> BUILD + ASSURANCE --> WORKFLOW +``` + +The source remains authoritative throughout the loop. +Prompts, skills, generated variants, search indexes, and rendered pages are delivery or control artifacts, not alternate sources of truth. + +## Establish One Canonical Owner + +Write each fact once in its authoritative layer, then produce the human and machine experiences from one publication source. +Product behavior may be authoritative in code, schemas, command metadata, or support data, while the documentation corpus remains the canonical published explanation. +Generate structured reference content from product sources when practical and use parity tests when prose must remain hand-written. + +NemoClaw uses MDX under `docs/` as its user-facing source of truth and generates agent-specific pages during the docs build. + +Apply these source rules: + +- Give each page one primary concept or user task. +- Organize procedures around the reader journey from choosing through setup, operation, validation, and troubleshooting. +- Keep reusable troubleshooting and reference facts with one canonical owner, then link to that owner. +- Generate tables and reference values from authoritative product data when that removes manual synchronization. +- Store navigation and route slugs in a machine-readable index. +- Declare intentional partial variant scope in source metadata and validate it against published navigation membership. +- Treat generated pages as disposable build output and never edit them by hand. +- Preserve published routes with direct redirects when content moves. + +Use frontmatter to describe the page for both people and retrieval systems. +The human description explains the value of the page, while the agent description states what the page helps with and when to select it. + +```yaml +--- +title: "Configure a Private Package Registry" +description: "Connect the product to a private package registry and verify authenticated downloads." +description-agent: "Configures and validates private package registry access. Use when users ask about registry credentials, package download failures, or enterprise package mirrors." +keywords: ["private registry", "package authentication", "enterprise mirror"] +content: + type: "how_to" +--- +``` + +Good routing metadata names the user intent, scope, and likely trigger phrases. +It does not repeat the page body or make unsupported product claims. + +## Publish Machine-Readable Delivery Paths + +Publish clean content through more than one retrieval path because agent environments have different capabilities. +Use this retrieval order: + +1. Search a read-only documentation service when the client supports a structured tool such as MCP. +2. Fetch a lightweight documentation index such as `llms.txt` when structured search is unavailable. +3. Fetch the specific Markdown page returned by search or listed in the index. +4. Fall back to rendered HTML only when a clean machine-readable route is unavailable. + +Each path should resolve to the same release and canonical page. +Do not make the agent reconcile copied content from several repositories or prompt bundles. + +Machine delivery is ready when the following checks pass: + +- Every published task page has a stable Markdown representation. +- The documentation index contains the current public route set. +- Search results return source URLs that an answer can cite. +- Variant-specific queries do not silently mix incompatible instructions. +- Moved pages redirect directly to a current published destination. +- Private drafts and unsupported features do not enter the public index. + +NemoClaw exposes its canonical pages through Markdown routes, `llms.txt`, and a read-only docs MCP server. +The [Use NemoClaw Docs with Your Coding Agents](agent-skills) page shows the user-facing retrieval flow. + +## Keep Agent Routing Thin + +Use prompts and skills to route the agent, not to store another copy of the docs. +A routing layer should tell the agent where to look, how to choose a source, and what response constraints to follow. + +A small routing skill needs only the following elements: + +- The canonical search endpoint and fallback documentation index. +- The preferred order for retrieving pages. +- The main task areas and their starting pages. +- Variant or platform selection rules. +- Safety requirements for approvals, credentials, and destructive actions. +- Citation and verification requirements. + +This pattern keeps the routing artifact stable while the product documentation changes frequently. +It also avoids large generated skills that drift from the public site, consume context, and create ambiguous ownership. + +Pair the routing skill with a starter prompt for users who have not installed project instructions. +Keep the starter prompt in a standalone canonical file, generate any website component from that file, and test that embedded or pinned copies still match it. + +## Encode Documentation Work as Agent Workflows + +Agentic docs include the workflows that maintain the corpus, not only the content agents retrieve. +Turn repeatable documentation engineering practices into bounded skills or repository instructions with explicit inputs, stop conditions, and evidence. + +| Workflow | Trigger | Required inputs | Completion evidence | +|---|---|---|---| +| Update docs | Product behavior changes or docs fall behind code. | Commit range, changed files, product scope, current pages. | Each user-visible change maps to an updated page or a documented no-impact decision. | +| Refactor information architecture | A section is oversized, duplicated, or hard to navigate. | Heading inventory, ownership map, inbound routes, supported variants. | One owner per topic, migrated routes, readable pages, and no content loss. | +| Review docs | A pull request changes a public procedure or reference. | Product implementation, tests, rendered preview, style policy. | Accuracy, links, route publication, and task verification pass. | +| Prepare a release | A release candidate is ready for documentation. | Merged change set, release scope, target version and date. | Canonical changelog entry lands before the release tag. | +| Publish | A docs change merges or a release tag is created. | Validated source, approved environment, immutable revision. | Staging or public output points to the expected revision. | + +NemoClaw applies this model through layered repository instructions and specialized contributor and maintainer skills. +The update workflow scans commits, respects a documentation skip list, maps behavior to canonical pages, and verifies the build. +The refactor workflow inventories every topic, defines ownership and URL migration contracts, and validates every supported variant. + +Design each workflow to produce evidence instead of a generic statement that the docs were updated. +The agent should report the files changed, source behavior represented, checks run, and intentionally deferred work. + +## Let the Corpus Grow and Tend It + +Do not require every engineering pull request to redesign the documentation structure. +Let agents make small, accurate updates to the current canonical page while the product evolves. +Restructure the corpus after repeated changes reveal its real shape. + +This is continuous growth with periodic curation. +The daily engineering loop keeps behavior and documentation aligned, while a daily or weekly maintenance pass improves sections that have outgrown their original purpose. + +Use observable signals to start a restructuring pass: + +- A page serves several distinct user tasks. +- A section has become difficult to scan or navigate. +- A paragraph contains several decisions, procedures, or failure modes. +- The same guidance appears in several pages. +- A common task is buried under an unrelated heading or navigation group. +- Product variants have started to drift because their shared and distinct behavior is unclear. + +During the maintenance pass, split overgrown pages, clarify headings, move reusable reference material to one owner, remove duplication, and preserve published routes. +If agents repeatedly produce the same structural or style problem, improve the repository instructions or workflow skill so later pull requests correct the pattern at its source. + +This cadence avoids premature reorganization while keeping the documentation usable as it grows. +It also reserves the writer's time for structure, user journeys, and editorial quality instead of routine transcription. + +## Generate Variants Without Duplicating Sources + +Many products publish documentation for editions, platforms, runtimes, or deployment models. +Generate a variant only when most of the source is shared. + +Use these rules: + +- Replace a build-time placeholder when only a literal name or command differs. +- Use a conditional block when the workflow, behavior, state layout, or security boundary differs. +- Use a separate source page when most of the procedure is variant-specific. +- Keep published guide variant membership and route slugs in the navigation model. +- Declare the intended guide variant subset in source metadata when a page does not apply to every guide variant. +- Regenerate every guide variant before route and link validation. +- Inspect rendered guide variants for broken lists, joined paragraphs, and missing context. + +NemoClaw generates shared OpenClaw, Hermes, and Deep Agents guide variants from one MDX source. +Its build rewrites the host CLI placeholder, removes inapplicable conditional blocks, and publishes a distinct route for each guide variant. + +### Separate the Source from Its Guide Variant Targets + +Authors edit the normal source page under `docs/`. +For this guide, the only source is `docs/resources/engineer-agentic-documentation.mdx`. +The repository does not maintain separate OpenClaw, Hermes, and Deep Agents source copies. + +### Author Shared and Variant-Specific Content + +Write ordinary prose once when the meaning is the same for every supported agent. +Use the $$nemoclaw placeholder when the only difference is the host CLI binary name. +The variant build resolves that placeholder as follows: + +| Generated variant | Placeholder output | +|---|---| +| OpenClaw | `nemoclaw`. | +| Hermes | `nemohermes`. | +| Deep Agents | `nemo-deepagents`. | + +Use the placeholder in prose, inline code, and fenced command examples on shared source pages. +Do not duplicate a paragraph or command block only to change the binary name. +Do not use the placeholder on a single-variant source page because that page does not pass through variant generation and would publish the placeholder literally. + +Use an `` block when the content differs by behavior, workflow, state layout, support, or agent-specific wording. +For example, start a Hermes-only block with <AgentOnly variant="hermes"> and close it with </AgentOnly>. +The `variant` attribute can name one variant or a comma-separated set such as `openclaw,hermes`. + +Do not import `AgentOnly` from a React component. +The canonical page is an intermediate source that the variant resolver compiles before Fern reads it. +The resolver removes the directive tags and keeps the block body only when the target variant appears in the `variant` attribute. + +Apply this decision rule: + +- Use ordinary shared prose when the meaning is identical. +- Use the host CLI placeholder when only the binary name differs. +- Use `` when the meaning or procedure differs. +- Use a separate source page when most of the page is specific to one agent. + +This page encodes the two dollar signs as character entities so a future generated variant can display the literal placeholder instead of resolving it. + +### Treat `AgentOnly` as a Build-Time Directive + +The `` syntax resembles an MDX component, but NemoClaw treats it as a build-time directive. +Agent variant selection does not depend on pathname detection or client-side logic in the rendered site. +The canonical source does not need an import because Fern receives only the resolved generated page. + +For each navigation target, `scripts/sync-agent-variant-docs.mts` reads the requested variant from `docs/index.yml` and parses the canonical source as text. +When an `` directive lists the active variant, the resolver copies its content into the generated page. +When the retained content starts with a Markdown list item, it discards blank lines immediately inside the opening and closing tags so wrapper formatting does not split the list. +For other retained content, it preserves those boundary blank lines and all interior blank lines so paragraphs and code sections keep their intended separation. +When the directive does not list the active variant, the resolver omits the body. +In both cases, it removes the opening and closing directive tags before writing the generated MDX. + +Keep the opening and closing `` tags at the first column on their own lines, and do not nest these blocks. +That line-oriented structure is the generator's authoring interface, and the resolver reports nested, unexpected, or unclosed blocks as errors. + +The `CLI_SENTINEL` constant and replacement table live in `scripts/sync-agent-variant-docs.mts` so placeholders can be resolved inside frontmatter, ordinary prose, inline code, and fenced command blocks before Fern renders the page. +Use $$nemoclaw for all shared host CLI references and wrap it in backticks when it should render as inline code. + +The resolver rejects a generated page if it still contains an unresolved line-oriented `` directive or a runtime agent component. +These checks make static resolution a publishing invariant instead of relying on client-side hydration to correct variant content. + +Published guide variant membership is explicit in `docs/index.yml`. +Each guide variant contains its own navigation tree, and a shared page appears in a tree through a generated target path with this contract: + +```text +_build/agent-variants//..generated.mdx +``` + +The `` value is `openclaw`, `hermes`, or `deepagents`. +The directory and base name before the guide variant suffix must match the canonical source path under `docs/`. + +When a source intentionally applies to fewer than all three guide variants, its frontmatter declares the exact subset: + +```yaml +agent-variants: ["openclaw", "hermes"] +``` + +The generator compares this declaration with the source's actual navigation membership and fails when the declaration is missing or differs. +An all-variant source omits the declaration, so removing one of its navigation targets also fails until the author restores the route or explicitly declares the narrower scope. + +This guide uses the following Fern navigation mapping: + +| Guide variant | Generated target in `docs/index.yml` | Published route suffix | +|---|---|---| +| OpenClaw | `_build/agent-variants/resources/engineer-agentic-documentation.openclaw.generated.mdx` | `/user-guide/openclaw/resources/engineer-agentic-documentation`. | +| Hermes | `_build/agent-variants/resources/engineer-agentic-documentation.hermes.generated.mdx` | `/user-guide/hermes/resources/engineer-agentic-documentation`. | +| Deep Agents | `_build/agent-variants/resources/engineer-agentic-documentation.deepagents.generated.mdx` | `/user-guide/deepagents/resources/engineer-agentic-documentation`. | + +The site and version prefixes are added by the Fern site configuration. +The route suffix above comes from the variant, section, and page slug hierarchy in `docs/index.yml`. + +### Use the Fern Index as the Mapping Layer + +The version entry in `fern/docs.yml` points Fern to `docs/index.yml`. +That index defines the navigation and published route tree for every supported agent variant. + +The OpenClaw navigation entry for this guide uses the following shape: + +```yaml +- page: "Engineer Documentation for AI Agents" + path: _build/agent-variants/resources/engineer-agentic-documentation.openclaw.generated.mdx + slug: engineer-agentic-documentation +``` + +The `path` tells Fern which generated MDX file to render. +The `slug` tells Fern the page's final route segment. +The surrounding `resources` section and `openclaw` variant contribute the parent route segments. + +This separation has several consequences: + +- A source file's filesystem location does not independently define its public URL. +- The same source can be published in several variant trees with the same page slug. +- A source page can apply to one guide variant by declaring that guide variant in frontmatter and pointing navigation directly to its source MDX file instead of a generated target. +- Moving or renaming a published page requires a navigation update and a redirect review, even when the source file stays in the same directory. +- Generated filenames are an interface with the generator and should not use an arbitrary naming pattern. + +### Resolve and Render Each Target + +The resolver is `scripts/sync-agent-variant-docs.mts`. +Run it directly through `npm run docs:sync-agent-variants`, or let `npm run docs` invoke it through the shared `docs:prepare` step. + +The script reads `docs/index.yml` before it reads shared source pages. +It derives each source page's published guide variant membership and validates every intentional subset declaration before rendering. +For each recognized generated path, it then performs the following work: + +1. It reads the active guide variant from the `openclaw`, `hermes`, or `deepagents` navigation tree. +2. It removes the `_build/agent-variants/` prefix and the `..generated.mdx` suffix. +3. It resolves the remaining path to one canonical `.mdx` source under `docs/`. +4. It renders that source for the active guide variant. +5. It writes the result under `docs/_build/agent-variants/` using the path declared in the index. +6. It removes stale generated files that no longer have a navigation target. + +Rendering replaces the host CLI placeholder with the correct binary name, removes conditional blocks that do not apply to the active guide variant, and adjusts relative image and component-import paths for the deeper generated directory. +Route-style links between documentation pages stay tied to the published navigation model instead of the generated filesystem location. + +The generated directory is ignored by Git. +Contributors commit the canonical source and `docs/index.yml` mapping, while the docs build recreates the variant files locally and in CI. + +### Validate the Complete Route Graph + +The `npm run docs` command prepares generated content before Fern validation. +The validation sequence checks the starter prompt, validates declared guide variant scope, regenerates the guide variants, verifies generated-page freshness, derives published routes from `docs/index.yml`, and runs the pinned Fern checker. + +This order matters because Fern cannot validate a guide variant route until the generated target named by `docs/index.yml` exists. +It also ensures that source edits, guide variant transforms, navigation mappings, and published routes are tested as one contract. + +## Treat Documentation as an Executable Product Surface + +Build deterministic checks around the contracts that matter to users and agents. +Syntax validation alone does not catch behavioral drift. + +| Gate | Defect it prevents | NemoClaw example | +|---|---|---| +| Source formatting | Unreadable diffs and inconsistent authoring. | Markdown linting, one sentence per source line, and copyable command rules. | +| Guide variant scope | A page is omitted from an applicable guide or silently published for the wrong agent. | Source `agent-variants` declarations checked against navigation membership. | +| Generated freshness | Stale prompts or guide variants. | Build-time generation followed by read-only freshness checks. | +| Route graph | Links or redirects that target unpublished pages. | Published-route validation derived from `docs/index.yml`. | +| Product parity | Reference documentation that disagrees with the product. | CLI command, flag, installer, and environment-variable parity checks. | +| Pull-request preview | Layout or navigation failures hidden by source checks. | An isolated Fern preview for each docs pull request. | +| Staging publish | A merge that cannot produce the deployed site. | Validation and publication from `main`. | +| Public release gate | Public docs from an unapproved or detached revision. | Release-tag publication only when the tagged commit is reachable from `main`. | + +Run the narrowest checks on every relevant change and keep broader checks at integration or release boundaries. +Tests should derive routes and behavior from the same source models used by the product instead of maintaining a second hard-coded catalog. + +## Govern What Agents May Publish + +Fast documentation automation needs a stronger scope gate, not a weaker one. +Documentation can accidentally turn an experiment into an apparent supported product surface. + +Define the following controls: + +- Require an accepted product decision before documenting a new integration, recipe, or supported workflow as canonical behavior. +- Maintain an explicit skip list for merged features that are not ready for public documentation. +- Block restricted terms and private implementation details from generated output. +- Separate public user guidance from contributor and maintainer procedures. +- Require agent workflows to stop before handling secrets, changing accounts, or performing destructive operations without approval. +- Assign an owner and lifecycle expectation to every canonical page and generated artifact. + +NemoClaw applies the same scope gate to code review and documentation review. +A working example and a green build establish technical evidence, but they do not establish product approval. + +## Keep High-Judgment Work Human-Owned + +Agents execute documented rules well when the repository gives them accurate context and deterministic checks. +People remain responsible for decisions that create or change those rules. + +Keep human ownership over the following work: + +- Decide whether a feature, integration, or workflow is a supported product surface. +- Decide which user problem a page owns and where readers should encounter it. +- Resolve conflicts between implementation details, product intent, security requirements, and user expectations. +- Restructure sections when accumulated changes reveal a better organization. +- Set the editorial voice, evidence standard, release narrative, and publication policy. +- Review recurring agent mistakes and improve the instructions, skills, tests, or source structure that allowed them. + +Formal information-architecture terminology can help teams discuss this work, but the terminology is not the source of quality. +If you can recognize that a page is doing too many jobs, decide where a user expects to find a topic, and give each topic one clear owner, you are already practicing the part of information architecture that this operating model needs. + +The durable division of labor is concise. +Agents handle repeatable work close to the engineering source, while people own product meaning, system design, exceptions, and editorial judgment. + +## Measure Retrieval and Task Quality + +Measure whether agents can complete documentation-backed tasks, not only whether pages receive traffic. + +Track a small evaluation set across common and high-risk user journeys: + +- Retrieval accuracy, measured by whether the intended canonical page appears in the first results. +- Variant accuracy, measured by whether the answer stays within the selected platform or product edition. +- Citation coverage, measured by whether behavior claims point to the current source page. +- Task completion, measured by whether the documented procedure reaches its success check. +- Safety compliance, measured by whether the agent stops at approval, credential, and destructive-action boundaries. +- Freshness, measured by the delay between a product change and its verified documentation update. +- Editorial intervention, measured by how often routine documentation changes require a manual rewrite after the agent follows the repository workflow. +- Drift detection, measured by which parity gate catches an intentionally stale fixture. + +Keep evaluation prompts versioned with the documentation system. +Add a regression case when a user report or review reveals that an agent selected the wrong source, mixed variants, skipped a safety boundary, or failed to verify the outcome. + +## Adopt the Model in Phases + +Build the smallest complete loop first, then add sophistication where evidence shows a need. + +| Phase | Deliverable | Exit condition | +|---|---|---| +| Foundation | One canonical, task-oriented Markdown or MDX corpus. | Humans can complete one priority journey from the source docs. | +| Machine delivery | Stable Markdown routes and a lightweight index. | An agent can retrieve and cite the same priority journey without scraping HTML. | +| Routing | A starter prompt and thin routing skill. | The agent selects the correct page, variant, and verification step. | +| Workflow | Repository instructions and an update-docs workflow. | A product change produces a traceable docs-impact decision. | +| Assurance | Route, link, generation, parity, and preview gates. | A deliberately stale or broken fixture fails before merge. | +| Scale | Variants, structured docs search, release automation, and evaluation suites. | Additional products or platforms do not create parallel content ownership. | + +Do not begin with a large generated skill catalog or autonomous publishing workflow. +Begin with one high-value user journey and prove the complete source-to-retrieval-to-verification loop. + +## Map the NemoClaw Implementation + +The current NemoClaw repository provides concrete examples for each layer. + +| Concern | NemoClaw implementation | +|---|---| +| Canonical content | `docs/**/*.mdx`. | +| Repository-wide documentation contract | `AGENTS.md`. | +| Authoring and review policy | `docs/CONTRIBUTING.md` and `docs/AGENTS.md`. | +| Navigation and published guide variants | `docs/index.yml`. | +| Intentional partial guide variant scope | Source `agent-variants` frontmatter validated by `scripts/sync-agent-variant-docs.mts`. | +| Site and redirect configuration | `fern/docs.yml` and `fern/fern.config.json`. | +| Machine delivery | Published Markdown routes, `llms.txt`, and the read-only docs MCP server. | +| Routing skill | `.agents/skills/nemoclaw-user-guide/SKILL.md`. | +| Starter prompt | `docs/resources/starter-prompt.md` and `scripts/generate-starter-prompt.mts`. | +| Product-owned generated facts | `ci/platform-matrix.json` and `scripts/generate-platform-docs.py`. | +| Guide variant generation | `scripts/sync-agent-variant-docs.mts`. | +| Route validation | `scripts/check-docs-published-routes.mts`. | +| Update workflow | `.agents/skills/nemoclaw-contributor-update-docs/SKILL.md`. | +| Documentation review receipt | `.github/PULL_REQUEST_TEMPLATE.md`, `.github/workflows/docs-review-receipt.yaml`, and `scripts/docs-review-receipt.mts`. | +| Information-architecture workflow | `.agents/skills/nemoclaw-maintainer-refactor-docs/SKILL.md`. | +| Pull-request assurance | Docs link, product parity, and preview workflows under `.github/workflows/`. | +| Release history | Dated entries under `docs/changelog/` that land before the release tag. | +| Release publication | Staging publication from `main` and public publication from release tags. | + +Use this map as a reference architecture, not a requirement to adopt the same vendor or repository layout. +Preserve the contracts when adapting the implementation. + +## Review Readiness + +Before calling a documentation system agent-ready, confirm the following conditions: + +- One governed source produces the human and machine documentation experiences. +- Every priority task has routing metadata, a stable machine-readable route, and a verification step. +- Search, the docs index, and rendered navigation resolve to the same release and canonical owner. +- Routing prompts and skills point to the source instead of copying it. +- Guide variant generation is deterministic, partial scope declarations match published routes, and guide variant behavior is tested. +- Agent workflows define scope, approvals, stop conditions, and completion evidence. +- Code-changing and documentation-only pull requests record a documentation-review result tied to the current head and instruction version. +- New commits invalidate the recorded review until the documentation writer subagent runs again. +- Pull requests validate generated output, routes, links, product parity, and rendered previews. +- Release publication uses an approved immutable revision. +- Retrieval, citation, task, guide variant, safety, and freshness regressions have repeatable evaluations. + +The first practical milestone is one product journey that passes every condition above. +Expand the system only after that loop is reliable. diff --git a/docs/resources/generate-documentation-variants.mdx b/docs/resources/generate-documentation-variants.mdx deleted file mode 100644 index 6d1cd2d2ff..0000000000 --- a/docs/resources/generate-documentation-variants.mdx +++ /dev/null @@ -1,184 +0,0 @@ ---- -# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 -title: "Generate Documentation Variants" -sidebar-title: "Generate Docs Variants" -description: "Generate product or agent documentation variants from shared MDX without duplicating canonical sources." -description-agent: "Explains when to share or separate variant sources, how NemoClaw resolves host CLI placeholders and AgentOnly directives, how navigation maps generated targets, and how to validate the route graph. Use when authoring or reviewing multi-variant documentation." -keywords: ["documentation variants", "AgentOnly", "MDX generation", "Fern navigation", "shared documentation source"] -content: - type: "how_to" ---- - -Generate documentation variants only when most of the source is shared. -Keep the canonical explanation in one MDX page, make behavioral differences explicit, and treat generated files as disposable build output. - -## Generate Variants Without Duplicating Sources - -Many products publish documentation for editions, platforms, runtimes, or deployment models. -Generate a variant only when most of the source is shared. - -Use these rules: - -- Replace a build-time placeholder when only a literal name or command differs. -- Use a conditional block when the workflow, behavior, state layout, or security boundary differs. -- Use a separate source page when most of the procedure is variant-specific. -- Keep published guide variant membership and route slugs in the navigation model. -- Declare the intended guide variant subset in source metadata when a page does not apply to every guide variant. -- Regenerate every guide variant before route and link validation. -- Inspect rendered guide variants for broken lists, joined paragraphs, and missing context. - -NemoClaw generates shared OpenClaw, Hermes, and Deep Agents guide variants from one MDX source. -Its build rewrites the host CLI placeholder, removes inapplicable conditional blocks, and publishes a distinct route for each guide variant. - -### Separate the Source from Its Guide Variant Targets - -Authors edit the normal source page under `docs/`. -For this page, the only source is `docs/resources/generate-documentation-variants.mdx`. -The repository does not maintain separate OpenClaw, Hermes, and Deep Agents source copies. - -### Author Shared and Variant-Specific Content - -Write ordinary prose once when the meaning is the same for every supported agent. -Use the $$nemoclaw placeholder when the only difference is the host CLI binary name. -The variant build resolves that placeholder as follows: - -| Generated variant | Placeholder output | -|---|---| -| OpenClaw | `nemoclaw`. | -| Hermes | `nemohermes`. | -| Deep Agents | `nemo-deepagents`. | - -Use the placeholder in prose, inline code, and fenced command examples on shared source pages. -Do not duplicate a paragraph or command block only to change the binary name. -Do not use the placeholder on a single-variant source page because that page does not pass through variant generation and would publish the placeholder literally. - -Use an `` block when the content differs by behavior, workflow, state layout, support, or agent-specific wording. -For example, start a Hermes-only block with <AgentOnly variant="hermes"> and close it with </AgentOnly>. -The `variant` attribute can name one variant or a comma-separated set such as `openclaw,hermes`. - -Do not import `AgentOnly` from a React component. -The canonical page is an intermediate source that the variant resolver compiles before Fern reads it. -The resolver removes the directive tags and keeps the block body only when the target variant appears in the `variant` attribute. - -Apply this decision rule: - -- Use ordinary shared prose when the meaning is identical. -- Use the host CLI placeholder when only the binary name differs. -- Use `` when the meaning or procedure differs. -- Use a separate source page when most of the page is specific to one agent. - -This page encodes the two dollar signs as character entities so a future generated variant can display the literal placeholder instead of resolving it. - -### Treat `AgentOnly` as a Build-Time Directive - -The `` syntax resembles an MDX component, but NemoClaw treats it as a build-time directive. -Agent variant selection does not depend on pathname detection or client-side logic in the rendered site. -The canonical source does not need an import because Fern receives only the resolved generated page. - -For each navigation target, `scripts/sync-agent-variant-docs.mts` reads the requested variant from `docs/index.yml` and parses the canonical source as text. -When an `` directive lists the active variant, the resolver copies its content into the generated page. -When the retained content starts with a Markdown list item, it discards blank lines immediately inside the opening and closing tags so wrapper formatting does not split the list. -For other retained content, it preserves those boundary blank lines and all interior blank lines so paragraphs and code sections keep their intended separation. -When the directive does not list the active variant, the resolver omits the body. -In both cases, it removes the opening and closing directive tags before writing the generated MDX. - -Keep the opening and closing `` tags at the first column on their own lines, and do not nest these blocks. -That line-oriented structure is the generator's authoring interface, and the resolver reports nested, unexpected, or unclosed blocks as errors. - -The `CLI_SENTINEL` constant and replacement table live in `scripts/sync-agent-variant-docs.mts` so placeholders can be resolved inside frontmatter, ordinary prose, inline code, and fenced command blocks before Fern renders the page. -Use $$nemoclaw for all shared host CLI references and wrap it in backticks when it should render as inline code. - -The resolver rejects a generated page if it still contains an unresolved line-oriented `` directive or a runtime agent component. -These checks make static resolution a publishing invariant instead of relying on client-side hydration to correct variant content. - -Published guide variant membership is explicit in `docs/index.yml`. -Each guide variant contains its own navigation tree, and a shared page appears in a tree through a generated target path with this contract: - -```text -_build/agent-variants//..generated.mdx -``` - -The `` value is `openclaw`, `hermes`, or `deepagents`. -The directory and base name before the guide variant suffix must match the canonical source path under `docs/`. - -When a source intentionally applies to fewer than all three guide variants, its frontmatter declares the exact subset: - -```yaml -agent-variants: ["openclaw", "hermes"] -``` - -The generator compares this declaration with the source's actual navigation membership and fails when the declaration is missing or differs. -An all-variant source omits the declaration, so removing one of its navigation targets also fails until the author restores the route or explicitly declares the narrower scope. - -This page uses the following published mapping: - -| Guide variant | Generated target in `docs/index.yml` | Published route suffix | -|---|---|---| -| OpenClaw | `_build/agent-variants/resources/generate-documentation-variants.openclaw.generated.mdx` | `/user-guide/openclaw/resources/documentation-engineering/generate-documentation-variants`. | -| Hermes | `_build/agent-variants/resources/generate-documentation-variants.hermes.generated.mdx` | `/user-guide/hermes/resources/documentation-engineering/generate-documentation-variants`. | -| Deep Agents | `_build/agent-variants/resources/generate-documentation-variants.deepagents.generated.mdx` | `/user-guide/deepagents/resources/documentation-engineering/generate-documentation-variants`. | - -The site and version prefixes are added by the Fern site configuration. -The route suffix comes from the variant, section, group, and page slug hierarchy in `docs/index.yml`. - -### Use the Fern Index as the Mapping Layer - -The version entry in `fern/docs.yml` points Fern to `docs/index.yml`. -That index defines the navigation and published route tree for every supported agent variant. - -The OpenClaw navigation entry for this page uses the following shape: - -```yaml -- page: "Generate Documentation Variants" - path: _build/agent-variants/resources/generate-documentation-variants.openclaw.generated.mdx - slug: generate-documentation-variants -``` - -The `path` tells Fern which generated MDX file to render. -The `slug` tells Fern the page's final route segment. -The surrounding `documentation-engineering` group, `resources` section, and `openclaw` variant contribute the parent route segments. - -This separation has several consequences: - -- A source file's filesystem location does not independently define its public URL. -- The same source can be published in several variant trees with the same page slug. -- A source page can apply to one guide variant by declaring that guide variant in frontmatter and pointing navigation directly to its source MDX file instead of a generated target. -- Moving or renaming a published page requires a navigation update and a redirect review, even when the source file stays in the same directory. -- Generated filenames are an interface with the generator and should not use an arbitrary naming pattern. - -### Resolve and Render Each Target - -The resolver is `scripts/sync-agent-variant-docs.mts`. -Run it directly through `npm run docs:sync-agent-variants`, or let `npm run docs` invoke it through the shared `docs:prepare` step. - -The script reads `docs/index.yml` before it reads shared source pages. -It derives each source page's published guide variant membership and validates every intentional subset declaration before rendering. -For each recognized generated path, it then performs the following work: - -1. It reads the active guide variant from the `openclaw`, `hermes`, or `deepagents` navigation tree. -2. It removes the `_build/agent-variants/` prefix and the `..generated.mdx` suffix. -3. It resolves the remaining path to one canonical `.mdx` source under `docs/`. -4. It renders that source for the active guide variant. -5. It writes the result under `docs/_build/agent-variants/` using the path declared in the index. -6. It removes stale generated files that no longer have a navigation target. - -Rendering replaces the host CLI placeholder with the correct binary name, removes conditional blocks that do not apply to the active guide variant, and adjusts relative image and component-import paths for the deeper generated directory. -Route-style links between documentation pages stay tied to the published navigation model instead of the generated filesystem location. - -The generated directory is ignored by Git. -Contributors commit the canonical source and `docs/index.yml` mapping, while the docs build recreates the variant files locally and in CI. - -### Validate the Complete Route Graph - -The `npm run docs` command prepares generated content before Fern validation. -The validation sequence checks the starter prompt, validates declared guide variant scope, regenerates the guide variants, verifies generated-page freshness, derives published routes from `docs/index.yml`, and runs the pinned Fern checker. - -This order matters because Fern cannot validate a guide variant route until the generated target named by `docs/index.yml` exists. -It also ensures that source edits, guide variant transforms, navigation mappings, and published routes are tested as one contract. - -## Related Topics - -- [Design Agent-Ready Documentation](design-agent-ready-documentation) explains canonical ownership and machine-readable delivery. -- [Automate Documentation Workflows](automate-documentation-workflows) explains how generated documentation fits the engineering loop. -- [Govern and Evaluate Agentic Documentation](govern-agentic-documentation) defines assurance and publication controls. diff --git a/docs/resources/govern-agentic-documentation.mdx b/docs/resources/govern-agentic-documentation.mdx deleted file mode 100644 index 707c861091..0000000000 --- a/docs/resources/govern-agentic-documentation.mdx +++ /dev/null @@ -1,157 +0,0 @@ ---- -# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 -title: "Govern and Evaluate Agentic Documentation" -sidebar-title: "Govern and Evaluate Docs" -description: "Set publication boundaries, assurance gates, human ownership, and quality measures for agentic documentation." -description-agent: "Defines executable documentation gates, product scope controls, human-owned decisions, retrieval and task-quality measures, phased adoption, and readiness criteria. Use when governing automated documentation or evaluating whether a documentation system is agent-ready." -keywords: ["documentation governance", "agentic documentation evaluation", "documentation quality gates", "retrieval accuracy", "docs readiness"] -content: - type: "how_to" ---- - -Treat documentation as a product surface with deterministic assurance, explicit publication boundaries, and outcome-based evaluation. -Agents can execute repeatable checks and workflows, while maintainers retain ownership of product scope, information architecture, and editorial policy. - -## Treat Documentation as an Executable Product Surface - -Build deterministic checks around the contracts that matter to users and agents. -Syntax validation alone does not catch behavioral drift. - -| Gate | Defect it prevents | NemoClaw example | -|---|---|---| -| Source formatting | Unreadable diffs and inconsistent authoring. | Markdown linting, one sentence per source line, and copyable command rules. | -| Guide variant scope | A page is omitted from an applicable guide or silently published for the wrong agent. | Source `agent-variants` declarations checked against navigation membership. | -| Generated freshness | Stale prompts or guide variants. | Build-time generation followed by read-only freshness checks. | -| Route graph | Links or redirects that target unpublished pages. | Published-route validation derived from `docs/index.yml`. | -| Product parity | Reference documentation that disagrees with the product. | CLI command, flag, installer, and environment-variable parity checks. | -| Pull-request preview | Layout or navigation failures hidden by source checks. | An isolated Fern preview for each docs pull request. | -| Staging publish | A merge that cannot produce the deployed site. | Validation and publication from `main`. | -| Public release gate | Public docs from an unapproved or detached revision. | Release-tag publication only when the tagged commit is reachable from `main`. | - -Run the narrowest checks on every relevant change and keep broader checks at integration or release boundaries. -Tests should derive routes and behavior from the same source models used by the product instead of maintaining a second hard-coded catalog. - -## Govern What Agents May Publish - -Fast documentation automation needs a stronger scope gate, not a weaker one. -Documentation can accidentally turn an experiment into an apparent supported product surface. - -Define the following controls: - -- Require an accepted product decision before documenting a new integration, recipe, or supported workflow as canonical behavior. -- Maintain an explicit skip list for merged features that are not ready for public documentation. -- Block restricted terms and private implementation details from generated output. -- Separate public user guidance from contributor and maintainer procedures. -- Require agent workflows to stop before handling secrets, changing accounts, or performing destructive operations without approval. -- Assign an owner and lifecycle expectation to every canonical page and generated artifact. - -NemoClaw applies the same scope gate to code review and documentation review. -A working example and a green build establish technical evidence, but they do not establish product approval. - -## Keep High-Judgment Work Human-Owned - -Agents execute documented rules well when the repository gives them accurate context and deterministic checks. -People remain responsible for decisions that create or change those rules. - -Keep human ownership over the following work: - -- Decide whether a feature, integration, or workflow is a supported product surface. -- Decide which user problem a page owns and where readers should encounter it. -- Resolve conflicts between implementation details, product intent, security requirements, and user expectations. -- Restructure sections when accumulated changes reveal a better organization. -- Set the editorial voice, evidence standard, release narrative, and publication policy. -- Review recurring agent mistakes and improve the instructions, skills, tests, or source structure that allowed them. - -Formal information-architecture terminology can help teams discuss this work, but the terminology is not the source of quality. -If you can recognize that a page is doing too many jobs, decide where a user expects to find a topic, and give each topic one clear owner, you are already practicing the part of information architecture that this operating model needs. - -The durable division of labor is concise. -Agents handle repeatable work close to the engineering source, while people own product meaning, system design, exceptions, and editorial judgment. - -## Measure Retrieval and Task Quality - -Measure whether agents can complete documentation-backed tasks, not only whether pages receive traffic. - -Track a small evaluation set across common and high-risk user journeys: - -- Retrieval accuracy, measured by whether the intended canonical page appears in the first results. -- Variant accuracy, measured by whether the answer stays within the selected platform or product edition. -- Citation coverage, measured by whether behavior claims point to the current source page. -- Task completion, measured by whether the documented procedure reaches its success check. -- Safety compliance, measured by whether the agent stops at approval, credential, and destructive-action boundaries. -- Freshness, measured by the delay between a product change and its verified documentation update. -- Editorial intervention, measured by how often routine documentation changes require a manual rewrite after the agent follows the repository workflow. -- Drift detection, measured by which parity gate catches an intentionally stale fixture. - -Keep evaluation prompts versioned with the documentation system. -Add a regression case when a user report or review reveals that an agent selected the wrong source, mixed variants, skipped a safety boundary, or failed to verify the outcome. - -## Adopt the Model in Phases - -Build the smallest complete loop first, then add sophistication where evidence shows a need. - -| Phase | Deliverable | Exit condition | -|---|---|---| -| Foundation | One canonical, task-oriented Markdown or MDX corpus. | Humans can complete one priority journey from the source docs. | -| Machine delivery | Stable Markdown routes and a lightweight index. | An agent can retrieve and cite the same priority journey without scraping HTML. | -| Routing | A starter prompt and thin routing skill. | The agent selects the correct page, variant, and verification step. | -| Workflow | Repository instructions and an update-docs workflow. | A product change produces a traceable docs-impact decision. | -| Assurance | Route, link, generation, parity, and preview gates. | A deliberately stale or broken fixture fails before merge. | -| Scale | Variants, structured docs search, release automation, and evaluation suites. | Additional products or platforms do not create parallel content ownership. | - -Do not begin with a large generated skill catalog or autonomous publishing workflow. -Begin with one high-value user journey and prove the complete source-to-retrieval-to-verification loop. - -## Map the NemoClaw Implementation - -The current NemoClaw repository provides concrete examples for each layer. - -| Concern | NemoClaw implementation | -|---|---| -| Canonical content | `docs/**/*.mdx`. | -| Repository-wide documentation contract | `AGENTS.md`. | -| Authoring and review policy | `docs/CONTRIBUTING.md` and `docs/AGENTS.md`. | -| Navigation and published guide variants | `docs/index.yml`. | -| Intentional partial guide variant scope | Source `agent-variants` frontmatter validated by `scripts/sync-agent-variant-docs.mts`. | -| Site and redirect configuration | `fern/docs.yml` and `fern/fern.config.json`. | -| Machine delivery | Published Markdown routes, `llms.txt`, and the read-only Model Context Protocol (MCP) docs server. | -| Routing skill | `.agents/skills/nemoclaw-user-guide/SKILL.md`. | -| Starter prompt | `docs/resources/starter-prompt.md` and `scripts/generate-starter-prompt.mts`. | -| Product-owned generated facts | `ci/platform-matrix.json` and `scripts/generate-platform-docs.py`. | -| Guide variant generation | `scripts/sync-agent-variant-docs.mts`. | -| Route validation | `scripts/check-docs-published-routes.mts`. | -| Update workflow | `.agents/skills/nemoclaw-contributor-update-docs/SKILL.md`. | -| Documentation review receipt | `.github/PULL_REQUEST_TEMPLATE.md`, `.github/workflows/docs-review-receipt.yaml`, and `scripts/docs-review-receipt.mts`. | -| Information-architecture workflow | `.agents/skills/nemoclaw-maintainer-refactor-docs/SKILL.md`. | -| Pull-request assurance | Docs link, product parity, and preview workflows under `.github/workflows/`. | -| Release history | Dated entries under `docs/changelog/` that land before the release tag. | -| Release publication | Staging publication from `main` and public publication from release tags. | - -Use this map as a reference architecture, not a requirement to adopt the same vendor or repository layout. -Preserve the contracts when adapting the implementation. - -## Review Readiness - -Before calling a documentation system agent-ready, confirm the following conditions: - -- One governed source produces the human and machine documentation experiences. -- Every priority task has routing metadata, a stable machine-readable route, and a verification step. -- Search, the docs index, and rendered navigation resolve to the same release and canonical owner. -- Routing prompts and skills point to the source instead of copying it. -- Guide variant generation is deterministic, partial scope declarations match published routes, and guide variant behavior is tested. -- Agent workflows define scope, approvals, stop conditions, and completion evidence. -- Code-changing and documentation-only pull requests record a documentation-review result tied to the current head and instruction version. -- New commits invalidate the recorded review until the documentation writer subagent runs again. -- Pull requests validate generated output, routes, links, product parity, and rendered previews. -- Release publication uses an approved immutable revision. -- Retrieval, citation, task, guide variant, safety, and freshness regressions have repeatable evaluations. - -The first practical milestone is one product journey that passes every condition above. -Expand the system only after that loop is reliable. - -## Related Topics - -- [Design Agent-Ready Documentation](design-agent-ready-documentation) defines the source, delivery, and routing architecture. -- [Automate Documentation Workflows](automate-documentation-workflows) explains update, review, and curation workflows. -- [Generate Documentation Variants](generate-documentation-variants) explains shared-source variant generation and route validation. diff --git a/test/check-docs-published-routes.test.ts b/test/check-docs-published-routes.test.ts index ec0840fbcb..98d64ae90a 100644 --- a/test/check-docs-published-routes.test.ts +++ b/test/check-docs-published-routes.test.ts @@ -489,33 +489,16 @@ describe("Manage Sandboxes extension routes", () => { describe("Documentation Engineering routes", () => { const index = buildPublishedRouteIndex(); - const pages = [ - "design-agent-ready-documentation", - "automate-documentation-workflows", - "generate-documentation-variants", - "govern-agentic-documentation", - ] as const; - - it("publishes every focused page under the non-clickable group for every agent variant", () => { - for (const page of pages) { - const source = `resources/${page}.mdx`; - - expect(index.sourceToRoutes.get(source)?.map(({ route }) => route)).toEqual([ - `/user-guide/openclaw/resources/documentation-engineering/${page}`, - `/user-guide/deepagents/resources/documentation-engineering/${page}`, - `/user-guide/hermes/resources/documentation-engineering/${page}`, - ]); - expect(findBrokenPublishedRoutes(source, index)).toEqual([]); - } - }); - it("does not publish a stale route for the retired source-only guide", () => { - expect(index.sourceToRoutes.has("resources/engineer-agentic-documentation.mdx")).toBe(false); - for (const variant of ["openclaw", "deepagents", "hermes"]) { - expect( - index.routes.has(`/user-guide/${variant}/resources/engineer-agentic-documentation`), - ).toBe(false); - } + it("publishes the agentic documentation guide for every agent variant", () => { + const source = "resources/engineer-agentic-documentation.mdx"; + + expect(index.sourceToRoutes.get(source)?.map(({ route }) => route)).toEqual([ + "/user-guide/openclaw/resources/engineer-agentic-documentation", + "/user-guide/deepagents/resources/engineer-agentic-documentation", + "/user-guide/hermes/resources/engineer-agentic-documentation", + ]); + expect(findBrokenPublishedRoutes(source, index)).toEqual([]); }); }); From 35d8bc47e9eecb57ed80432e870499a39a1b5d43 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Thu, 30 Jul 2026 16:09:58 -0700 Subject: [PATCH 3/8] docs: clarify optional DORI routing Signed-off-by: Miyoung Choi --- docs/AGENTS.md | 11 +++++----- test/check-docs-published-routes.test.ts | 26 +++++++++++++++++------- 2 files changed, 25 insertions(+), 12 deletions(-) diff --git a/docs/AGENTS.md b/docs/AGENTS.md index c032e359ff..ac44d5a5f6 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -76,9 +76,9 @@ Apply these rules to documentation, examples, headings, UI text, and release not ## Use DORI for Complete NVIDIA Doc Tools Follow [NVIDIA DORI Routing](../AGENTS.md#nvidia-dori-routing). -Use DORI only when current host capabilities include the verified NVIDIA documentation Skill Library. -Do not ask for or persist a user classification during a normal documentation task. -Complete the documentation before the developer opens the pull or merge request. +Use the following DORI workflow only when current host capabilities include the +verified NVIDIA documentation Skill Library. Complete the documentation before +the developer opens the pull or merge request. 1. Route the documentation task through DORI. Include the changed source files, the user-visible impact, the documentation that might need updates, and the @@ -91,8 +91,9 @@ Complete the documentation before the developer opens the pull or merge request. 4. When the host does not support subagents, complete the same documentation work in the primary task. -If the verified Skill Library is unavailable, inaccessible, or fails, do not block the change or prompt for setup. -Continue using the Writing Style Guide above. +If the verified Skill Library is unavailable, inaccessible, or fails, skip DORI. +Do not attempt routing, prompt for setup, or ask for or persist a user +classification. Continue using the Writing Style Guide above. ## Before Editing diff --git a/test/check-docs-published-routes.test.ts b/test/check-docs-published-routes.test.ts index 98d64ae90a..d129cfd440 100644 --- a/test/check-docs-published-routes.test.ts +++ b/test/check-docs-published-routes.test.ts @@ -10,6 +10,7 @@ import { parse } from "yaml"; import { buildPublishedRouteIndex, + extractMarkdownLinks, findBrokenChangelogRoutes, findBrokenPublishedInferenceRoutes, findBrokenPublishedManageSandboxRoutes, @@ -464,16 +465,18 @@ describe("Manage Sandboxes extension routes", () => { const source = "manage-sandboxes/run-deep-agents-code.mdx"; const quickstartSource = "get-started/quickstart-langchain-deepagents-code.mdx"; const quickstart = readFileSync(path.join(repoRoot, "docs", quickstartSource), "utf8"); + const quickstartRoute = "/user-guide/deepagents/get-started/quickstart"; + const runtimeRoute = + "/user-guide/deepagents/manage-sandboxes/operate-sandboxes/run-deep-agents-code"; - expect(index.sourceToRoutes.get(source)?.map(({ route }) => route)).toEqual([ - "/user-guide/deepagents/manage-sandboxes/operate-sandboxes/run-deep-agents-code", - ]); + expect(index.sourceToRoutes.get(source)?.map(({ route }) => route)).toEqual([runtimeRoute]); expect(findBrokenPublishedRoutes(source, index)).toEqual([]); expect(findBrokenPublishedRoutes(quickstartSource, index)).toEqual([]); - expect(quickstart.split('')).toHaveLength(2); - expect(quickstart).toContain( - "[Run Deep Agents Code](../manage-sandboxes/operate-sandboxes/run-deep-agents-code)", - ); + expect( + extractMarkdownLinks(quickstart).map(({ target }) => + resolvePublishedRoute(quickstartRoute, target), + ), + ).toContain(runtimeRoute); expect( index.routes.has( "/user-guide/openclaw/manage-sandboxes/operate-sandboxes/run-deep-agents-code", @@ -485,6 +488,15 @@ describe("Manage Sandboxes extension routes", () => { ), ).toBe(false); }); + + it("preserves the legacy Deep Agents harness anchor", () => { + const quickstart = readFileSync( + path.join(repoRoot, "docs", "get-started/quickstart-langchain-deepagents-code.mdx"), + "utf8", + ); + + expect(quickstart.match(/<\/a>/g)).toHaveLength(1); + }); }); describe("Documentation Engineering routes", () => { From 19178aa05860f69f78008687d913d718d393960f Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Thu, 30 Jul 2026 17:51:18 -0700 Subject: [PATCH 4/8] docs: link DORI source libraries Signed-off-by: Miyoung Choi --- docs/DORI_SETUP.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/DORI_SETUP.md b/docs/DORI_SETUP.md index 32d773940f..b4b8e87faa 100644 --- a/docs/DORI_SETUP.md +++ b/docs/DORI_SETUP.md @@ -10,6 +10,11 @@ Before inspecting or installing private components, ask the user to confirm that If the user does not confirm access, stop this setup and use the checked-in [Writing Style Guide](AGENTS.md#writing-style-guide). Access confirmation does not approve installation or host configuration. +Use these internal sources for the current installation and registration instructions: + +- [NVIDIA Skill Library](https://gitlab-master.nvidia.com/tech-docs/skill-library) contains documentation-focused Agent Skills and guidance for installing them with DORI and other supported hosts. +- [NVIDIA Template Library](https://gitlab-master.nvidia.com/tech-docs/template-library) contains reusable documentation templates and guidance for installing its template skills with DORI. + ## Inspect the Environment 1. Check for DORI MCP tools. From ab9f920454e9bb112c72f8ef6b8b610d1fbbe974 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Thu, 30 Jul 2026 17:59:30 -0700 Subject: [PATCH 5/8] test(docs): validate rendered Deep Agents routes Signed-off-by: Miyoung Choi --- scripts/check-docs-published-routes.mts | 34 +++++++++++++++++------- test/check-docs-published-routes.test.ts | 14 +++++----- 2 files changed, 33 insertions(+), 15 deletions(-) diff --git a/scripts/check-docs-published-routes.mts b/scripts/check-docs-published-routes.mts index 99a5fc8eab..2ebe0a6cbc 100644 --- a/scripts/check-docs-published-routes.mts +++ b/scripts/check-docs-published-routes.mts @@ -413,6 +413,27 @@ export type RouteViolation = { resolved: string; }; +export type PublishedPageBody = { + route: string; + body: string; +}; + +export function renderPublishedPageBodies( + sourcePath: string, + index: PublishedRouteIndex, + docsDir: string = docsRoot, +): PublishedPageBody[] { + const publishedRoutes = index.sourceToRoutes.get(sourcePath); + if (!publishedRoutes || publishedRoutes.length === 0) { + throw new Error(`${sourcePath} is not a published navigation page in docs/index.yml`); + } + const source = readFileSync(path.join(docsDir, sourcePath), "utf8"); + return publishedRoutes.map((publishedRoute) => ({ + route: publishedRoute.route, + body: renderBodyForPublishedRoute(source, sourcePath, publishedRoute), + })); +} + /** * Validate every internal cross-page link on a docs source page against the * published route map. Returns the links that resolve to no published route. @@ -422,19 +443,14 @@ export function findBrokenPublishedRoutes( index: PublishedRouteIndex, docsDir: string = docsRoot, ): RouteViolation[] { - const publishedRoutes = index.sourceToRoutes.get(sourcePath); - if (!publishedRoutes || publishedRoutes.length === 0) { - throw new Error(`${sourcePath} is not a published navigation page in docs/index.yml`); - } - const source = readFileSync(path.join(docsDir, sourcePath), "utf8"); const violations: RouteViolation[] = []; - for (const publishedRoute of publishedRoutes) { - const body = renderBodyForPublishedRoute(source, sourcePath, publishedRoute); + for (const publishedPage of renderPublishedPageBodies(sourcePath, index, docsDir)) { + const { body } = publishedPage; const links = extractMarkdownLinks(body).filter((link) => isInternalRouteLink(link.target)); for (const link of links) { - const resolved = resolvePublishedRoute(publishedRoute.route, link.target); + const resolved = resolvePublishedRoute(publishedPage.route, link.target); if (!index.routes.has(resolved)) { - violations.push({ sourcePath, fromRoute: publishedRoute.route, ...link, resolved }); + violations.push({ sourcePath, fromRoute: publishedPage.route, ...link, resolved }); } } } diff --git a/test/check-docs-published-routes.test.ts b/test/check-docs-published-routes.test.ts index d129cfd440..450b7b8304 100644 --- a/test/check-docs-published-routes.test.ts +++ b/test/check-docs-published-routes.test.ts @@ -18,6 +18,7 @@ import { findBrokenPublishedRoutes, findMissingDirectLegacyManageSandboxRedirects, findMissingDirectLegacyReleaseNotesRedirects, + renderPublishedPageBodies, resolvePublishedRoute, } from "../scripts/check-docs-published-routes.mts"; @@ -464,16 +465,17 @@ describe("Manage Sandboxes extension routes", () => { it("publishes the Deep Agents runtime guide only in the Deep Agents guide", () => { const source = "manage-sandboxes/run-deep-agents-code.mdx"; const quickstartSource = "get-started/quickstart-langchain-deepagents-code.mdx"; - const quickstart = readFileSync(path.join(repoRoot, "docs", quickstartSource), "utf8"); const quickstartRoute = "/user-guide/deepagents/get-started/quickstart"; const runtimeRoute = "/user-guide/deepagents/manage-sandboxes/operate-sandboxes/run-deep-agents-code"; + const [quickstartPage] = renderPublishedPageBodies(quickstartSource, index); expect(index.sourceToRoutes.get(source)?.map(({ route }) => route)).toEqual([runtimeRoute]); expect(findBrokenPublishedRoutes(source, index)).toEqual([]); expect(findBrokenPublishedRoutes(quickstartSource, index)).toEqual([]); + expect(quickstartPage.route).toBe(quickstartRoute); expect( - extractMarkdownLinks(quickstart).map(({ target }) => + extractMarkdownLinks(quickstartPage.body).map(({ target }) => resolvePublishedRoute(quickstartRoute, target), ), ).toContain(runtimeRoute); @@ -490,12 +492,12 @@ describe("Manage Sandboxes extension routes", () => { }); it("preserves the legacy Deep Agents harness anchor", () => { - const quickstart = readFileSync( - path.join(repoRoot, "docs", "get-started/quickstart-langchain-deepagents-code.mdx"), - "utf8", + const [quickstartPage] = renderPublishedPageBodies( + "get-started/quickstart-langchain-deepagents-code.mdx", + index, ); - expect(quickstart.match(/<\/a>/g)).toHaveLength(1); + expect(quickstartPage.body.match(/<\/a>/g)).toHaveLength(1); }); }); From fa305bfb9140a9941852c1f493a2248d7d51ca1d Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Fri, 31 Jul 2026 11:08:16 -0700 Subject: [PATCH 6/8] docs: complete v0.0.99 audit follow-ups Signed-off-by: Miyoung Choi --- docs/changelog/2026-07-30.mdx | 3 ++- docs/configure-agents/configure-memory-search.mdx | 6 ++++-- docs/inference/set-up-vllm-on-two-dgx-stations.mdx | 13 +++++++++++++ docs/reference/configure-runtime-identity.mdx | 6 ++++-- docs/reference/troubleshooting.mdx | 9 ++++++--- 5 files changed, 29 insertions(+), 8 deletions(-) diff --git a/docs/changelog/2026-07-30.mdx b/docs/changelog/2026-07-30.mdx index a528c16766..4244295544 100644 --- a/docs/changelog/2026-07-30.mdx +++ b/docs/changelog/2026-07-30.mdx @@ -35,7 +35,8 @@ It also hardens host readiness, inference health checks, managed images, documen - Trusted CI now publishes agent-complete Open Container Initiative images by immutable digest, validates anonymous pulls and runtime contracts, and promotes aliases only after those checks pass. Dormant managed-image selection and startup-profile contracts resolve exact all-agent cohorts and bounded agent-specific startup data without activating buildless onboarding or changing the current `Dockerfile` path. - Documentation now keeps provider-switch sections within the applicable OpenClaw and Hermes guide variants, corrects the Omni sub-agent model ID, and generalizes agent-selection guidance. - The contributor workflow also separates pre-tag release entries from post-tag Announcements and corrects the NVIDIA DORI installation pin from 0.10.0 to 0.9.0. + The runtime identity, two-DGX Station vLLM, and memory search guides are now separate focused pages. + The NVIDIA DORI installation pin is corrected from 0.10.0 to 0.9.0. For more information, refer to [Switch Inference Providers](/user-guide/openclaw/inference/manage-inference/switch-providers) and [Set Up Task-Specific Sub-Agents](/user-guide/openclaw/configure-agents/set-up-sub-agent). - Release E2E now preserves command and agent first-turn latency separately, evaluates recurring anomalies within an exact 12-sample cohort, and routes retired rebuild selectors to focused replacement evidence. The credential-generation window runs independently, managed startup recovery covers the persisted startup command, and the standing Brev Launchable waits for the staging image family before deployment. diff --git a/docs/configure-agents/configure-memory-search.mdx b/docs/configure-agents/configure-memory-search.mdx index 4ec51c19aa..5c0f69179b 100644 --- a/docs/configure-agents/configure-memory-search.mdx +++ b/docs/configure-agents/configure-memory-search.mdx @@ -16,8 +16,8 @@ This setup lets another local server, such as managed vLLM, continue to serve th ## Prepare the Embedding Server -Start the host Ollama container with the embedding model. -This example uses `qwen3-embedding:4b` on port `11434`. +Before you continue, ensure that a host Ollama container is running on port `11434` and has the `qwen3-embedding:4b` model available. +This procedure does not start the container or pull the model. The sandbox reaches the container through `http://host.openshell.internal:11434`. Keep the container bound to the local host or a reviewed host interface. @@ -34,6 +34,8 @@ nemoclaw my-assistant policy add local-inference --yes nemoclaw my-assistant exec -- curl -fsS http://host.openshell.internal:11434/api/tags ``` +Continue only when the returned JSON `models` array contains an entry whose `name` is `qwen3-embedding:4b`. + ## Configure the Embedding Provider Open a bounded shields-down window before you change the OpenClaw configuration. diff --git a/docs/inference/set-up-vllm-on-two-dgx-stations.mdx b/docs/inference/set-up-vllm-on-two-dgx-stations.mdx index 59290e66da..d6b8062b54 100644 --- a/docs/inference/set-up-vllm-on-two-dgx-stations.mdx +++ b/docs/inference/set-up-vllm-on-two-dgx-stations.mdx @@ -70,6 +70,19 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | \ bash ``` +## Verify the Installed Route + +After the installer completes, inspect the live route and the sandbox inference path. + +```bash +$$nemoclaw my-assistant inference get +$$nemoclaw my-assistant status +``` + +Confirm that `inference get` reports the `vllm-local` provider and the `nemotron-ultra` model. +Continue only when the `Inference` row in the status output reports `reachable`. +This result confirms that the sandbox route returned HTTP `200` through `499`; it does not prove a successful model invocation. + ## Review Reboot and Resume Behavior If the local host requires a reboot during initial preparation, the installer stops with status `10`. diff --git a/docs/reference/configure-runtime-identity.mdx b/docs/reference/configure-runtime-identity.mdx index ace491e0fc..0c803cbbc6 100644 --- a/docs/reference/configure-runtime-identity.mdx +++ b/docs/reference/configure-runtime-identity.mdx @@ -162,8 +162,10 @@ identity: ``` Register a separate Entra application for the delegated runtime flow. -Grant only the Microsoft Graph delegated `User.Read` permission needed by [`GET /me`](https://learn.microsoft.com/en-us/graph/api/user-get?view=graph-rest-1.0), and request [`offline_access`](https://learn.microsoft.com/en-us/entra/identity-platform/scopes-oidc#the-offline_access-scope) during the external authorization-code bootstrap so the v2 endpoint returns a refresh token. -Microsoft documents `offline_access` as an explicit requirement for v2 refresh-token issuance and [documents replacement of the stored refresh token](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow#refresh-the-access-token) when a refresh response carries a new one. +Grant only the Microsoft Graph delegated `User.Read` permission needed by [`GET /me`](https://learn.microsoft.com/en-us/graph/api/user-get?view=graph-rest-1.0). +During the external authorization-code bootstrap, request [`offline_access`](https://learn.microsoft.com/en-us/entra/identity-platform/scopes-oidc#the-offline_access-scope) so the v2 endpoint returns a refresh token. +Microsoft documents `offline_access` as an explicit requirement for v2 refresh-token issuance. +It also [documents replacement of the stored refresh token](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow#refresh-the-access-token) when a refresh response carries a new refresh token. Use a confidential web application and `ENTRA_CLIENT_SECRET` when the bootstrap client can keep a secret. Omit `client_secret_env` for a public client rather than placing a public-client secret on the host. NemoClaw does not package the authorization redirect, consent UI, PKCE exchange, or MSAL cache. diff --git a/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx index 18a57b4232..21d98e9268 100644 --- a/docs/reference/troubleshooting.mdx +++ b/docs/reference/troubleshooting.mdx @@ -136,7 +136,7 @@ It rejects remote endpoints and relative socket paths before service startup. ### Onboarding reports `invalid_docker_host` -The `invalid_docker_host` advisory means that `DOCKER_HOST` is set to an endpoint that NemoClaw cannot safely pass to the managed OpenShell gateway service. +The `invalid_docker_host` advisory means that `DOCKER_HOST` is not an absolute local `unix://` socket path that NemoClaw can write to the managed OpenShell gateway service environment. Remove the override to use Docker's default local socket: ```bash @@ -2736,8 +2736,11 @@ If the command succeeds because the dashboard profile is missing, the dashboard ### Shields Reports Drift for the Hermes Configuration Root -The Hermes configuration root holds the agent's top-level runtime state, not only its configuration: `auth.json`, the drain request, and the temporary files that back every atomic `gateway_state.json` and `gateway.pid` replace are created directly in `/sandbox/.hermes`. -Lockdown therefore moves that directory to `root:sandbox` mode `3770`, keeping the set-id and sticky bits, so the gateway can still manage its own runtime files while the sticky bit stops the sandbox identity from unlinking or renaming the sealed root-owned configuration. +The Hermes configuration root holds the agent's top-level runtime state, not only its configuration. +The configuration root stores `auth.json`, the drain request, and temporary files for atomic `gateway_state.json` and `gateway.pid` replacement. +Lockdown moves that directory to `root:sandbox` mode `3770`, which preserves the set-group-ID and sticky bits. +The gateway can still manage its runtime files. +The sticky bit prevents the sandbox identity from unlinking or renaming sealed root-owned configuration. Run the following command to inspect a locked root: ```bash From 45f1a471601cb13a6495bf50ec555b2b72e5f4e4 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Fri, 31 Jul 2026 11:17:51 -0700 Subject: [PATCH 7/8] docs: clarify sandbox recovery state Signed-off-by: Miyoung Choi --- docs/reference/commands.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index 313d2d763d..323c4eb4da 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -1383,7 +1383,7 @@ A successful recovery clears the stale stopped-container failure. If OpenShell already reports the registered Docker-driver sandbox as present and `Ready`, status verifies the OpenClaw gateway and host forward. It recovers either component when the verification reports it absent. -If Docker readiness or the agent delivery chain cannot be proven, status exits non-zero and reports the `sandbox_recovery_failed` state. +When status finds the sandbox but cannot prove its agent delivery chain, it exits non-zero and reports the `sandbox_recovery_failed` state. Address the reported recovery layer, then run the displayed `$$nemoclaw recover` command. If the sandbox's recorded dashboard port is also held by a foreign listener, the header escalates to the `sandbox_dashboard_port_conflict` failure layer with the message `sandbox container is stopped and the dashboard port is held by a foreign listener.` so the operator can recover the port before restarting the sandbox. From d65f179397a72571cfae1f67d910594ef2d6a702 Mon Sep 17 00:00:00 2001 From: Senthil Ravichandran Date: Fri, 31 Jul 2026 15:22:27 -0700 Subject: [PATCH 8/8] docs: surface headless approval boundary Signed-off-by: Senthil Ravichandran --- docs/manage-sandboxes/run-deep-agents-code.mdx | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/manage-sandboxes/run-deep-agents-code.mdx b/docs/manage-sandboxes/run-deep-agents-code.mdx index 21273e96b5..e9ffc9f1c6 100644 --- a/docs/manage-sandboxes/run-deep-agents-code.mdx +++ b/docs/manage-sandboxes/run-deep-agents-code.mdx @@ -39,6 +39,11 @@ nemo-deepagents connect dcode ``` + +Headless `dcode -n` has no approval UI and automatically approves non-shell tool requests, including file writes and edits. +Use the interactive TUI when you need to inspect each destructive tool request before it runs. + + For a single headless task, run: ```bash @@ -97,7 +102,7 @@ The managed launchers disable the following mutable or unsupported behavior: - CLI and TUI update or install commands - Nested remote sandbox providers and remote asynchronous subagents - Deep Agents Model Context Protocol (MCP) commands, project MCP auto-loading, startup commands, and executable hooks -- ACP mode, interpreter tool calling, and shell allow-list overrides +- ACP mode, interpreter tool calling, and shell allowlist overrides - Native LangSmith tracing and ambient OpenTelemetry exporter configuration The managed model constructor accepts only Deep Agents Code's `openai` provider path and reads its endpoint from a root-owned image file. @@ -116,18 +121,16 @@ It then gives Deep Agents Code a process-local, integrity-bound snapshot for ser It prefers a sealed in-memory file when available. The OpenShell-compatible anonymous read-only descriptor fallback verifies the inode, size, and SHA-256 digest and fails closed on drift. Stdio commands, extra headers, raw credentials, and unrelated top-level configuration fail closed. -For authenticated MCP setup and credential rotation, see [Add an MCP Server](../mcp-servers/add-an-mcp-server) and [Manage MCP Servers](../mcp-servers/manage-mcp-servers). +For authenticated MCP setup and credential rotation, refer to [Add an MCP Server](../mcp-servers/add-an-mcp-server) and [Manage MCP Servers](../mcp-servers/manage-mcp-servers). This isolated-mode guarantee applies to the managed launchers, not arbitrary Python commands in the sandbox. ## Choose an Approval Boundary Interactive shell execution and other destructive tools remain behind human-in-the-loop approval prompts by default. -Thread-wide auto-approval is unavailable unless you enable the managed thread opt-in capability, and shell allow-list auto-approval remains disabled. +Thread-wide auto-approval is unavailable unless you enable the managed thread opt-in capability, and shell allowlist auto-approval remains disabled. Headless `dcode -n` is an explicit automation boundary. -It has no approval UI and automatically approves non-shell tool requests, including file writes and edits. The managed headless path still disables shell execution, startup commands, interpreter tool calling, executable hooks, unmanaged MCP configuration, nested remote sandboxes, remote asynchronous subagents, and alternate model routes. -Use the interactive TUI when you need to inspect each destructive tool request before it runs. ## Configure Thread Auto-Approval