feat(skills): add maintainer docs refactor workflow

[miyoungc]

Summary

Add a maintainer skill that turns oversized Fern sections into journey-based, one-topic pages while preserving canonical ownership, variants, routes, anchors, and redirects.
Wire it into skill discovery, release-prep handoff, and docs contributor guidance so remaining sections follow the inference refactor consistently.

Changes

• Add nemoclaw-maintainer-refactor-docs as a reusable maintainer workflow; remaining sections need consistent information-architecture rules, and one-off edits cannot enforce ownership and route safety across future refactors.
• Encode the inference-derived structure: choose, set up, operate, validate, then canonical troubleshooting and reference, with provider-specific pages and non-clickable grouping nodes.
• Require content and anchor inventories, deduplication, variant-aware navigation, direct legacy redirects, release-note/source-reference audits, compact lists, deterministic checks, and independent docs review.
• Register the skill in the catalog and route structural release-prep work from nemoclaw-contributor-update-docs to the maintainer workflow.
• Document the workflow in docs/CONTRIBUTING.md; test/skills-frontmatter.test.ts protects the new skill's metadata and discoverability contract.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification: the skill frontmatter test validates checked-in skill metadata and the skill-creator validator confirms the package structure.
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: this adds an internal maintainer workflow and contributor guidance without changing NemoClaw runtime or user-facing product behavior.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: skill validator passed; npx vitest run test/skills-frontmatter.test.ts passed 26 tests.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: not applicable; this is a guidance-only skill and documentation change.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only) — result: passed with 0 errors and one suppressed Fern warning.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Miyoung Choi miyoungc@nvidia.com

Summary by CodeRabbit

• Documentation
  • Expanded contributor guidance to use the maintainer-owned docs refactor skill when a section is too large, mixes tasks, or needs improved navigation/TOC support.
  • Added a complete end-to-end process for planning and executing documentation refactors, including topic ownership rules and a URL/anchor migration and redirect contract.
  • Introduced an additional constraint in the contributor update workflow to route structural/IA changes to the refactor skill when needed.
  • Updated the maintainer skills guide and counts to include the new refactor skill.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 9fa966d4-434b-4873-bca9-8b2d86678ab3

📥 Commits

Reviewing files that changed from the base of the PR and between 7678c10 and 8d532ac.

📒 Files selected for processing (1)

• docs/CONTRIBUTING.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/CONTRIBUTING.md

---

📝 Walkthrough

Walkthrough

Adds a maintainer-owned NemoClaw documentation refactor skill, registers it in the skills catalog, and updates contributor guidance and release catch-up instructions to route structural documentation work through the new skill.

Changes

Documentation Refactor Workflow

Layer / File(s)	Summary
Refactor planning and content design .agents/skills/nemoclaw-maintainer-refactor-docs/SKILL.md	Defines prerequisites, documentation inventory, journey-based organization, navigation rules, and canonical ownership for refactored content.
Route migration and completion checks .agents/skills/nemoclaw-maintainer-refactor-docs/SKILL.md	Specifies route and anchor migration, content-safe implementation order, validation audits, independent review, completion criteria, and result reporting.
Skill registration and contributor handoff .agents/skills/nemoclaw-maintainer-refactor-docs/agents/openai.yaml, .agents/skills/nemoclaw-skills-guide/SKILL.md, docs/CONTRIBUTING.md, .agents/skills/nemoclaw-contributor-update-docs/SKILL.md	Registers the new agent interface, updates maintainer skill counts and listings, and directs contributors to use the refactor skill for oversized or structurally complex documentation changes.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested labels: feature, area: skills

Suggested reviewers: cv, ericksoa

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding a maintainer docs refactor workflow.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/maintainer-docs-refactor-skill

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage remains at 96%, unchanged from the main branch.

TypeScript / code-coverage/cli

The overall coverage in the codex/maintainer-doc... branch remains at 79%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main 73b35fc	codex/maintainer-doc... 8d532ac	+/-
src/lib/name-validation.ts	100%	94%	-6%
src/lib/runner.ts	75%	72%	-3%
src/lib/securit...ntial-filter.ts	99%	98%	-1%
src/lib/state/gateway.ts	88%	90%	+2%
src/lib/security/redact.ts	95%	99%	+4%
src/lib/onboard...reachability.ts	63%	72%	+9%

---

_{Updated July 13, 2026 18:29 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-6777.docs.buildwithfern.com/nemoclaw

[github-actions]

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• None. This is a documentation and agent-skill guidance-only PR. It does not change installer or onboarding execution, sandbox lifecycle, credentials, security boundaries, network policy, inference routing, deployment configuration, or real assistant user flows. Docs validation is appropriate, but no existing E2E job is warranted.

Optional E2E

• None.

New E2E recommendations

• None.

[github-actions]

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: No advisor follow-up required beyond maintainer review.
Findings: 0 required · 0 warnings · 0 optional suggestions
Since last review: 0 prior items resolved · 0 still apply · 0 new items found

Workflow run details

This is an automated review. Required findings need action before merge. Warnings and optional suggestions do not require a response or follow-up. A human maintainer makes the final merge decision.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.agents/skills/nemoclaw-maintainer-refactor-docs/SKILL.md:
- Line 160: Update the documented Vitest command in SKILL.md to use the
repository-pinned binary, replacing npx vitest with npx --no-install vitest or
the existing npm script while preserving the same test files and run behavior.

In `@docs/CONTRIBUTING.md`:
- Around line 43-46: Revise the added guidance following the skill reference so
every sentence uses active, present-tense second-person wording. Update the
descriptions beginning with “It inventories” and “The skill lives” to address
the reader directly while preserving the existing skill path and documented
behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 688a8538-6716-4e71-b8b8-140cf2d7ad17

📥 Commits

Reviewing files that changed from the base of the PR and between 7666b55 and 7678c10.

📒 Files selected for processing (5)

• .agents/skills/nemoclaw-contributor-update-docs/SKILL.md
• .agents/skills/nemoclaw-maintainer-refactor-docs/SKILL.md
• .agents/skills/nemoclaw-maintainer-refactor-docs/agents/openai.yaml
• .agents/skills/nemoclaw-skills-guide/SKILL.md
• docs/CONTRIBUTING.md