diff --git a/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md b/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md index 2e75dbab0f5..49bb044ab09 100644 --- a/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md +++ b/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md @@ -115,6 +115,7 @@ For each relevant commit, determine which doc page(s) it affects. Use this mappi If a commit does not map to any existing page but introduces a user-visible concept, flag it as needing a new page. If a commit already changes files under `docs/`, include those pages in the target page list and run a docs review or edit pass against them using the style guidance in Step 5. Do not assume an existing doc change is complete, correctly placed, or style-compliant just because it landed with the source commit. +If the target section has become too large or needs information-architecture changes, flag the structural work for a maintainer and use `nemoclaw-maintainer-refactor-docs` instead of improvising a structural rewrite during release catch-up. ## Step 3: Read the Commit Details diff --git a/.agents/skills/nemoclaw-maintainer-refactor-docs/SKILL.md b/.agents/skills/nemoclaw-maintainer-refactor-docs/SKILL.md new file mode 100644 index 00000000000..5f838faacf7 --- /dev/null +++ b/.agents/skills/nemoclaw-maintainer-refactor-docs/SKILL.md @@ -0,0 +1,220 @@ +--- +name: nemoclaw-maintainer-refactor-docs +description: "Plan and execute maintainer-owned refactors of oversized NemoClaw Fern documentation sections into focused one-topic pages with journey-based nested navigation, non-clickable group nodes, canonical troubleshooting and reference ownership, deduplicated content, variant-aware route-style links, and complete redirects. Use when a docs page or section has grown too large, when reorganizing documentation information architecture or a table of contents, when splitting pages, moving content across sections, consolidating duplicate guidance, or migrating URLs in docs/index.yml and fern/docs.yml. Trigger keywords - refactor docs, reorganize docs, split docs, nested TOC, documentation IA, one topic per page, move troubleshooting, deduplicate docs, docs too long." +--- + + + +# Refactor NemoClaw Documentation + +Refactor a bounded documentation section without changing product meaning. +Improve findability while preserving every useful fact, one canonical owner per topic, and every supported published route. + +## Prerequisites + +- Work from the NemoClaw repository root. +- Read `docs/CONTRIBUTING.md` before planning or editing. +- Treat `docs/` as the user-facing source of truth. +- Read the full target pages, their navigation entries in `docs/index.yml`, their redirects in `fern/docs.yml`, and their inbound links before editing. +- Read the authoritative code, tests, issue, or PR when the refactor might alter behavior claims rather than only move existing prose. + +## Choose the Deliverable + +- Treat cross-section ownership, navigation hierarchy, and published URL changes as maintainer-owned decisions. +- For a request to plan, audit, or propose a structure, stop after the information architecture, ownership map, and URL migration plan. +- For a request to refactor, implement the plan, validate it, and report the completed migration. +- Keep the work bounded to the named docs section. Report adjacent debt instead of folding unrelated cleanup into the refactor. +- Allow a cross-section move when canonical ownership requires it, but identify the move explicitly in the plan and migration report. +- Surface a choice only when it changes topic ownership, public URLs, supported variants, or user workflow. Use established repository conventions for routine details. + +## Step 1: Inventory Before Editing + +Read the complete section rather than sampling the longest page. + +1. List every page and nested group for every OpenClaw, Hermes, and Deep Agents navigation variant. +2. List every H2 and H3 in the source pages, then map meaningful prose blocks, tables, callouts, and provider-specific procedures that do not have their own heading. +3. Find inbound links, old route and anchor references, redirects, release-note links, README links, tests, generated-page mappings, source comments, and repository instructions that name the current docs owners. +4. Record which variants render each page or block. +5. Identify repeated procedures, troubleshooting guidance, reference facts, and related-topic lists. + +Use `rg` for repository-wide discovery. Useful starting points include: + +```bash +rg -n '^(##|###) ' docs/
+rg -n '||' docs fern README.md test scripts +``` + +Create an ownership inventory before proposing the new TOC: + +| Current page or section | User task | Variants | Canonical owner | Action | +|---|---|---|---|---| +| Existing topic | What the reader is trying to do | Applicable guides | Destination page | Keep, split, move, merge, or delete | + +Every old H2 and H3 must appear in this inventory. + +## Step 2: Design Around the User Journey + +Default to this sequence when it fits the subject. +Omit a phase when it has no substantial reader task; never invent a thin page only to complete the sequence. + +1. **Choose**: Help readers select an option, provider, model, deployment, or approach. +2. **Set up**: Give each provider, platform, integration, or setup path its own focused page when the procedures differ. +3. **Operate**: Cover inspection, switching, configuration, lifecycle, and routine management. +4. **Validate**: Prove configuration and runtime behavior without mixing in broad troubleshooting. +5. **Troubleshoot and reference**: Keep reusable failure remediation and lookup material under the canonical Reference section. + +Add an **About** or **Understand** page only when it explains a distinct mental model that readers need before choosing or operating. +Do not create an overview page merely to give a section a clickable first item. + +Apply these navigation rules: + +- Make section headings and foldable TOC nodes non-clickable grouping nodes. They must contain only `section`, `slug`, and `contents`, plus supported display settings such as `collapsed`. +- Put all reader-facing content on child pages. +- Default to `root section -> task group -> page`. Avoid deeper nesting unless the material demonstrates a real third-level distinction. +- Keep one primary topic or user task per page. Supporting prerequisites and immediate success verification may remain on the same page; split distinct user goals, provider flows, reusable concepts, and reusable reference material. +- Prefer verb-led page titles such as **Choose**, **Set Up**, **Configure**, **View**, **Switch**, **Verify**, and **Troubleshoot**. +- Use concise noun phrases for group labels. +- Keep provider-specific or platform-specific procedures on their own pages instead of adding more sections to a generic page. +- Reuse group slugs and ordering across variants where practical, omit unsupported pages, and never publish an empty group. + +## Step 3: Establish Canonical Ownership + +Assign each fact, procedure, and failure mode to one page before moving content. + +- Keep setup steps on the focused setup page. +- Keep routine operations on manage or operate pages. +- Keep validation behavior on validation pages. +- Move reusable failure symptoms, diagnosis, and remediation to the canonical Reference troubleshooting area. +- Use `docs/reference/troubleshooting.mdx` when it remains a focused owner. If the canonical page is itself oversized, create a non-clickable **Troubleshooting** group with focused child pages instead of growing another monolith. +- Keep structured lookup material in Reference. +- Link to canonical content instead of restating it on several pages. + +Before moving troubleshooting or reference content, search the destination for the same symptom, heading, commands, and distinctive phrases. +Merge with existing guidance when it is already documented. +Do not leave a shorter duplicate behind. + +Preserve every unique fact from the old pages. +When two pages disagree, verify the behavior from authoritative sources instead of choosing whichever wording is newer. + +## Step 4: Define the URL Migration Contract + +Create a route table before deleting or renaming files: + +| Old published route | New published route | Variants | Redirect required | Content owner | +|---|---|---|---|---| +| Legacy URL | Final page URL | Applicable guides | Yes or no | Source MDX page | + +Create a separate anchor migration table when one old page will split into several destinations: + +| Old route and anchor | New route and anchor | Inbound references | Action | +|---|---|---|---| +| Legacy page fragment | Final topic fragment | Docs, releases, README, tests, or source | Update inbound links and record any unavoidable fragment loss | + +Apply these route rules: + +- Derive published URLs from the section and page `slug` hierarchy in `docs/index.yml`, not from source-file directories. +- Use extensionless route-style links in MDX. +- Never link or redirect to a non-clickable section node. +- Add redirects for supported legacy forms, including `latest` and non-`latest`, variant routes, and pre-variant flat routes when they existed. +- Point every redirect directly to its final page. Do not create redirect chains. +- Audit wildcard precedence and ensure wildcard destinations also resolve directly to published pages. +- Preserve `.html` and `index.html` legacy forms when repository or external-facing references show that they were published or linked. +- Ensure each redirect destination is published for every variant represented by its source. +- Redirect removed landing or section-root routes to the first page that provides real value, not to an empty replacement overview. +- Update links to moved troubleshooting content to the canonical reference page and specific anchor when useful. +- Update historical release-note links to the most relevant canonical topic when their former broad page is split; do not rely on a page-level redirect to recover moved anchor meaning. + +Shared source pages can appear in navigation through `_build/agent-variants/*.generated.mdx` paths. +Those generated files are ignored build output. Edit the source page and navigation mapping, not the generated file. + +## Step 5: Implement in a Content-Safe Order + +1. Create the destination pages and move all mapped content. +2. Consolidate duplicate content into its canonical owner. +3. Update `docs/index.yml` for every supported guide variant. +4. Update route-style links and related-topic lists. +5. Add direct redirects in `fern/docs.yml`. +6. Delete superseded source pages only after their unique content and inbound routes are accounted for. + +Follow the documentation style guide and these refactor-specific rules: + +- Start each page with a concise statement of its purpose. +- Keep one sentence per source line. +- Keep consecutive items in a simple Markdown list compact, with no blank lines between items. +- Add **Related Topics** or **Next Steps** only when the links help readers continue the journey. +- Use `$$nemoclaw` for shared host CLI examples. +- Use `` only when behavior or guidance differs by agent, not only to change a binary name. +- Keep shared lists structurally intact after variant rendering. Verify the generated variant output when an `` block appears inside or next to a list. +- Preserve working commands and behavior claims during a structural split. Avoid opportunistic prose rewrites. + +## Step 6: Validate the Refactor + +Run the existing deterministic checks rather than inventing another route model: + +```bash +npm run docs:sync-agent-variants +npm run docs +npx vitest run test/check-docs-published-routes.test.ts test/check-docs-links.test.ts +git diff --check +``` + +Add or extend focused route tests when the refactored section is not covered by the current published-route checker. +Test observable published routes and redirects rather than source-file-relative assumptions. + +Complete these audits after the build: + +- Search for every deleted filename, old slug, old title, and old route. +- Search for every moved anchor and update references whose semantic destination changed. +- Search source comments, package-level `AGENTS.md` files, tests, and scripts for statements that name the former docs owner. +- Confirm no page links to a foldable section root. +- Confirm all redirects terminate at published pages for the applicable variants. +- Compare the old heading inventory with the new pages and account for every unique topic. +- Search canonical troubleshooting and reference destinations for duplicate headings or repeated remediation. +- Inspect generated OpenClaw, Hermes, and Deep Agents pages when variant blocks or shared lists changed. +- Check that simple lists have no blank lines between consecutive items. +- Visually inspect the Fern preview when navigation depth, titles, or conditional content changed. + +Treat automated link feedback as a hypothesis. +Fern links resolve from published slug routes, so a valid link may not match a source-file-relative path. +Verify link comments against `docs/index.yml`, `fern/docs.yml`, generated variant mappings, and the deterministic route checks before editing. +Missing anchors can still be real even when the page route exists. + +## Step 7: Run an Independent Docs Review + +When subagents are available, give a documentation reviewer the changed files, the old-to-new ownership map, and test evidence. +Ask it to check for content loss, duplicate ownership, variant drift, bad redirects, and style regressions without telling it the expected verdict. +Apply valid findings and rerun affected checks. + +## Completion Contract + +Do not call the refactor complete until all of these conditions hold: + +- Every visible TOC item that readers can select is a real topic page. +- Every foldable grouping node is non-clickable and has no page content. +- Each page owns one primary topic or task. +- Every old section is mapped to a destination or intentionally removed with a stated reason. +- Troubleshooting and reference guidance has one canonical owner. +- No supported variant renders a link or redirect to an unpublished page. +- Legacy URLs redirect directly to final published pages. +- Shared content renders correctly for every applicable agent variant. +- Simple lists remain compact. +- The docs build, route checks, link checks, and diff check pass. + +## Report the Result + +Summarize the refactor with: + +- The final journey-based TOC. +- Pages created, moved, consolidated, and deleted. +- Canonical troubleshooting and reference ownership decisions. +- Redirects and legacy routes preserved. +- Variant-specific differences. +- Validation commands and results. +- Any intentionally deferred adjacent cleanup. + +Use the Inference section as the living example of this method when a concrete pattern is needed. +Its structure separates **About Inference Routing**, choosing a provider and model, hosted/local/custom setup paths, management, validation, and canonical Reference troubleshooting. +Copy the reasoning and consistency rules, not the inference-specific page names. diff --git a/.agents/skills/nemoclaw-maintainer-refactor-docs/agents/openai.yaml b/.agents/skills/nemoclaw-maintainer-refactor-docs/agents/openai.yaml new file mode 100644 index 00000000000..220bfcf8475 --- /dev/null +++ b/.agents/skills/nemoclaw-maintainer-refactor-docs/agents/openai.yaml @@ -0,0 +1,7 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +interface: + display_name: "NemoClaw Maintainer Docs Refactor" + short_description: "Refactor growing docs into consistent topics" + default_prompt: "Use $nemoclaw-maintainer-refactor-docs to reorganize a large NemoClaw docs section into focused pages with consistent navigation, routes, and redirects." diff --git a/.agents/skills/nemoclaw-skills-guide/SKILL.md b/.agents/skills/nemoclaw-skills-guide/SKILL.md index decf16ec952..ad5b65bf005 100644 --- a/.agents/skills/nemoclaw-skills-guide/SKILL.md +++ b/.agents/skills/nemoclaw-skills-guide/SKILL.md @@ -22,10 +22,10 @@ The prefix in each skill name indicates who it is for. For end users operating a NemoClaw sandbox. Covers routing human users' AI agents to the canonical NemoClaw Markdown documentation. -### `nemoclaw-maintainer-*` (13 skills) +### `nemoclaw-maintainer-*` (14 skills) For project maintainers. -Covers the daily maintainer cadence (morning standup, daytime loop, evening handoff), workflow policy reference, cutting releases, drafting release notes, finding PRs to review, comparing PRs, cross-issue sweeps, triage, normalizing issue and PR title tags, performing security code reviews, and verifying whether stale bug reports still reproduce on the latest release. +Covers the daily maintainer cadence (morning standup, daytime loop, evening handoff), workflow policy reference, documentation information-architecture refactors, cutting releases, drafting release notes, finding PRs to review, comparing PRs, cross-issue sweeps, triage, normalizing issue and PR title tags, performing security code reviews, and verifying whether stale bug reports still reproduce on the latest release. ### `nemoclaw-contributor-*` (4 skills) @@ -57,6 +57,7 @@ Covers trusted checkout setup and readiness checks, creating pull requests that | `nemoclaw-maintainer-find-review-pr` | Find open security PRs with Urgent or High Project Priority, link each to its issue, detect duplicates, and present a review summary. | | `nemoclaw-maintainer-pr-comparator` | Compare competing PRs for the same issue and recommend which one to merge. | | `nemoclaw-maintainer-normalize-title-tags` | Preview and remove bracketed `NemoClaw` title tags from issues and PRs case-insensitively, even when the tag appears later in the title. | +| `nemoclaw-maintainer-refactor-docs` | Split oversized Fern docs into focused topics with journey-based navigation, canonical ownership, route-safe redirects, variant checks, and deduplication. | | `nemoclaw-maintainer-security-code-review` | Perform a 9-category security review of a PR or issue, producing per-category PASS/WARNING/FAIL verdicts. | | `nemoclaw-maintainer-verify-stale` | Verify whether old issues with native Issue Type `Bug` still reproduce on latest. Reuses or provisions a Brev box, scores confidence, and proposes evidence-backed Project/comment writes for approval; never auto-closes. | @@ -83,6 +84,6 @@ Skills are cumulative. Each role includes the skills from the roles above it: |------|----------------|-------|------------| | User | `nemoclaw-user-*` | 1 | `nemoclaw-user-guide` | | Contributor | `nemoclaw-user-*` + `nemoclaw-contributor-*` | 5 | `nemoclaw-contributor-onboard` | -| Maintainer | All skills | 18 | `nemoclaw-maintainer-morning` | +| Maintainer | All skills | 19 | `nemoclaw-maintainer-morning` | After identifying the role, present the applicable skills from the Skill Catalog above and recommend the starting skill. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 1b1d3f3b1fb..682dccfcbfc 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -28,7 +28,7 @@ Before documenting a new surface, confirm that an accepted issue or design decis Route independent solutions, complete use-case examples, and third-party integrations through [Community Solutions](resources/community-contributions.mdx). If the correct destination is unclear, request maintainer direction before drafting the page. -## Update Docs with Contributor Skills +## Update and Refactor Docs with Agent Skills If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo includes the `nemoclaw-contributor-update-docs` skill that automates doc work. Use it before writing from scratch. @@ -40,6 +40,10 @@ During release prep, run the skill first, make any doc version bumps, then open The skill lives in `.agents/skills/nemoclaw-contributor-update-docs/` and follows the style guide below automatically. +Use the maintainer-owned `nemoclaw-maintainer-refactor-docs` skill when a page or section has grown too large, mixes several user tasks, or needs a nested TOC. +Use it to inventory the existing content, organize topics around the user journey, keep foldable navigation groups non-clickable, assign one canonical owner per topic, and preserve Fern routes, redirects, and agent variants during the split. +Find the skill in `.agents/skills/nemoclaw-maintainer-refactor-docs/`. + ## Markdown Docs for AI Agents The `docs/` directory is the source of truth for user-facing documentation.