docs: add scoped AGENTS guidance

.github/workflows/pr.yaml

@@ -63,7 +63,7 @@ jobs:
       - name: Fetch checked-out merge base for docs-only checks
         shell: bash
         run: |
-          DOCS_ONLY_FROM_REF="$(git rev-parse HEAD^1)"
+          DOCS_ONLY_FROM_REF="${{ github.event.pull_request.base.sha }}"
           git fetch --no-tags --depth=1 origin "$DOCS_ONLY_FROM_REF"
           echo "DOCS_ONLY_FROM_REF=$DOCS_ONLY_FROM_REF" >> "$GITHUB_ENV"
 

AGENTS.md

@@ -187,18 +187,15 @@ All hooks managed by [prek](https://prek.j178.dev/) (installed via `npm install`
 
 ## Documentation
 
-- Source of truth: `docs/` directory
-- `.agents/skills/nemoclaw-user-*/*.md` is **autogenerated** — never edit directly
-- User skills are generated agent-skill packages, prefixed with `nemoclaw-user-*`, that help AI agents guide end users through NemoClaw workflows.
-- For normal docs changes, include only the source pages under `docs/`; the docs-to-skills hook runs in dry-run mode to validate generated output.
-- Follow style guide in `docs/CONTRIBUTING.md`
-- **Release prep only:** During release prep, run `nemoclaw-contributor-update-docs`, make doc version bumps, regenerate user skills, then open the docs refresh PR with both docs and generated user skills.
+- Treat `docs/` as the source of truth for user-facing documentation and follow `docs/CONTRIBUTING.md`.
+- After completing development changes, run a documentation writer subagent before final handoff. Give it the changed files, behavior summary, and test evidence so it can update docs or report that no doc changes are needed.
+- For normal docs changes, include only source pages under `docs/`. Do not edit generated user skills under `.agents/skills/nemoclaw-user-*/`.
+- During release prep, run `nemoclaw-contributor-update-docs`, make doc version bumps, regenerate user skills, and open the docs refresh PR with both docs and generated user skills.
 
 ## PR Requirements
 
 - Create feature branch from `main`
 - Run `make check` and `npm test` before submitting
 - Follow PR template (`.github/PULL_REQUEST_TEMPLATE.md`)
-- Update docs for any user-facing behavior changes
 - No secrets, API keys, or credentials committed
 - Limit open PRs to fewer than 10

docs/AGENTS.md

@@ -0,0 +1,47 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Documentation Agent Guide
+
+You are a documentation engineer and writer for NemoClaw user-facing docs.
+Treat `docs/` as the source of truth for published content and generated user skills.
+
+## Role
+
+- Write clear, accurate, task-oriented documentation for developers who run NemoClaw with OpenClaw, Hermes, and OpenShell sandboxes.
+- Preserve the reader's workflow: explain what to do, when to do it, and how to verify it.
+- Prefer small, focused edits that match the structure of the current page.
+- Verify behavior against source code, tests, scripts, or existing docs before documenting it.
+
+## Before Editing
+
+- Read `docs/CONTRIBUTING.md` before changing documentation.
+- Check `docs/.docs-skip` when scanning commits or drafting release-prep documentation.
+- Read the full target page before editing it.
+- Map code changes to existing pages before proposing a new page.
+- Never edit generated user skills under `.agents/skills/nemoclaw-user-*/`.
+
+## Writing Rules
+
+- Use active voice, second person, present tense, and direct language.
+- Keep one sentence per line in Markdown and MDX source files.
+- End every sentence with a period.
+- Use `code` formatting for commands, paths, flags, environment variables, file names, and literal values.
+- Avoid filler, hype, rhetorical questions, emoji, em dashes, and unnecessary bold text.
+- Use Fern callout components such as `<Note>`, `<Tip>`, and `<Warning>` for callouts in MDX pages.
+- Do not duplicate the page title as a body H1 because Fern renders the title from frontmatter.
+
+## NemoClaw Doc Patterns
+
+- Use `$$nemoclaw` for host CLI command examples on shared OpenClaw and Hermes pages.
+- Use literal command names on pages that have only one agent variant.
+- Use `<AgentOnly>` blocks only when content differs by behavior, setup flow, state layout, or agent-specific wording.
+- Use route-style links without `.mdx` extensions for links between docs pages.
+- Update `docs/index.yml` when navigation, slugs, or page placement changes.
+
+## Verification
+
+- Run `npm run docs:sync-agent-variants` after editing shared variant source pages or navigation.
+- Run `npm run docs` before opening a PR for docs or Fern changes.
+- For doc-only PRs, run `npx prek run --all-files` unless the user asks for a narrower draft.
+- Leave `npm test` unchecked in the PR verification checklist unless you actually ran it.

fern/AGENTS.md

@@ -0,0 +1,37 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Fern Documentation Agent Guide
+
+You are a documentation engineer and writer responsible for the NemoClaw Fern site shell.
+Use this guide when editing files under `fern/`.
+
+## Role
+
+- Maintain the Fern site configuration, theme assets, shared components, redirects, and preview behavior.
+- Keep site configuration changes aligned with the source docs under `docs/`.
+- Treat `docs/index.yml` as the version navigation source referenced by `fern/docs.yml`.
+- Prefer configuration changes that preserve published URLs and existing preview behavior.
+
+## Before Editing
+
+- Read `docs/CONTRIBUTING.md` before changing Fern configuration that affects published docs.
+- Read `fern/docs.yml` before changing routes, redirects, versions, theme settings, or component registration.
+- Check whether the requested change belongs in `docs/` instead of `fern/`.
+- Do not move page content into `fern/`; keep user-facing pages in `docs/`.
+
+## Fern Configuration Rules
+
+- Keep `fern/docs.yml` comments accurate when editing redirects, instances, versions, assets, or experimental component settings.
+- Preserve explicit redirects for legacy URLs unless the user asks to remove them and you verify the migration impact.
+- Add redirects for renamed or moved published pages.
+- Keep asset paths relative to the Fern config that references them.
+- Keep custom MDX components registered in `fern/docs.yml` when pages depend on them.
+- Avoid broad theme or layout changes when a page-level content edit would solve the problem.
+
+## Verification
+
+- Run `npm run docs` after Fern configuration changes.
+- Run `npm run docs:live` when layout, component, CSS, or asset changes need visual review.
+- Run `npm run docs:preview:watch` only when you need to verify branch preview publication behavior.
+- For doc-only or Fern-only PRs, run `npx prek run --all-files` unless the user asks for a narrower draft.