Skip to content

docs: improve landing pages and about pages#3371

Merged
ericksoa merged 6 commits into
mainfrom
docs/improve-about-pages
May 12, 2026
Merged

docs: improve landing pages and about pages#3371
ericksoa merged 6 commits into
mainfrom
docs/improve-about-pages

Conversation

@miyoungc

@miyoungc miyoungc commented May 11, 2026

Copy link
Copy Markdown
Collaborator

Summary

Refresh the Get Started and About documentation so new users are directed to the right overview and quickstart pages from the entry pages.

Adds the high-level component diagram to Architecture Overview and aligns the entry pages around the intended reading path from Overview to Ecosystem, How It Works, and then Quickstart.

Preview: https://nvidia.github.io/NemoClaw/pr-preview/pr-3371/

Related Issue

Closes #2602

Changes

  • Added the high-level NemoClaw component diagram to docs/about/how-it-works.md.
  • Updated the How It Works text to describe the user/operator path, NemoClaw control, OpenShell gateway, sandbox, inference, integrations, and state/artifacts.
  • Updated README and Get Started/About pages so entry readers can find the system model before installation steps.

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)

Verification

  • npx prek run --all-files passes
  • npm test passes
  • Tests added or updated for new or changed behavior
  • No secrets, API keys, or credentials committed
  • Docs updated for user-facing behavior changes
  • make docs builds without warnings (doc changes only)
  • Doc pages follow the style guide (doc changes only)
  • New doc pages include SPDX header and frontmatter (new pages only)

Summary by CodeRabbit

  • Documentation
    • Reorganized docs navigation and landing page with refreshed cards and streamlined Get Started flow
    • Added/renamed Architecture Overview, Ecosystem, and Architecture Details entries; reworked architecture content and diagrams
    • Clarified CLI, plugin, and blueprint responsibilities and sandbox creation guidance
    • Updated Overview, Quickstart, Hermes note (marked experimental), and Windows prerequisites links

Review Change Stack

@coderabbitai

coderabbitai Bot commented May 11, 2026

Copy link
Copy Markdown
Contributor

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: 11e02809-290f-4f49-aaa6-37dda302c361

📥 Commits

Reviewing files that changed from the base of the PR and between 4512907 and 08d7e4e.

📒 Files selected for processing (2)
  • docs/get-started/prerequisites.md
  • docs/get-started/quickstart.md
✅ Files skipped from review due to trivial changes (2)
  • docs/get-started/prerequisites.md
  • docs/get-started/quickstart.md

📝 Walkthrough

Walkthrough

This pull request restructures the NemoClaw documentation to emphasize a new three-part architecture (host CLI, TypeScript sandbox plugin, versioned YAML blueprint), reorganizes the ecosystem and overview descriptions, and improves navigation across the documentation site through updated landing pages and quickstart guides.

Changes

Documentation Restructuring for Architecture & Navigation Update

Layer / File(s) Summary
Core Architecture & Design Model
docs/about/how-it-works.md, docs/reference/architecture.md
Establish host CLI + sandbox plugin + versioned YAML blueprint as the core architecture model. Updated front matter, system descriptions, design principles, and blueprint execution details to reflect host-side orchestration via OpenShell CLI rather than Python subprocess execution.
Component Overview & Benefits
docs/about/ecosystem.md, docs/about/overview.md
Reorganize ecosystem section to lead with three-part component description and diagram. Expand overview introduction with hardened sandboxing, routed inference, and declarative policy language. Update capabilities table and consolidate Benefits section with dedicated heading.
Navigation & Landing Page Restructuring
README.md, docs/index.md
Update README Documentation links from "How It Works" and "Architecture" to "Architecture Overview," "Ecosystem," and "Architecture Details." Restructure docs/index.md landing content and Explore grid tiles with standardized card descriptions, badges, and cross-links emphasizing installation, Architecture Overview, Ecosystem, and Quickstart paths.
Quickstart & Procedural Guide Updates
docs/get-started/quickstart.md, docs/get-started/prerequisites.md, docs/get-started/quickstart-hermes.md
Reorganize quickstart Next Steps into learning-focused list (Overview, Architecture Overview, Ecosystem) and usage-focused list (Manage Sandboxes, Inference Options, Network Policies, Troubleshooting). Update prerequisites Windows label and change Hermes experimental feature notice to admonition block style.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 The docs now tell a clearer tale,
Of CLI, plugin, blueprint—none shall fail,
With OpenShell routing the sandboxed way,
The architecture shines bright as day,
Ecosystem mapped, navigation refined.

🚥 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 'docs: improve landing pages and about pages' is concise and clearly describes the main change: refreshing documentation landing and about pages.
Linked Issues check ✅ Passed The PR successfully addresses #2602 by adding a high-level architecture diagram to how-it-works.md and updating entry pages with aligned architecture and system overview content as required.
Out of Scope Changes check ✅ Passed All changes are documentation-only updates to improve landing and about pages, aligned with the objectives of #2602. No out-of-scope code or unrelated changes are present.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/improve-about-pages

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

  • Generate code and open pull requests
  • Plan features and break down work
  • Investigate incidents and troubleshoot customer tickets together
  • Automate recurring tasks and respond to alerts with triggers
  • Summarize progress and report instantly

Built for teams:

  • Shared memory across your entire org—no repeating context
  • Per-thread sandboxes to safely plan and execute work
  • Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started


Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions

github-actions Bot commented May 12, 2026

Copy link
Copy Markdown
Contributor

E2E Advisor Recommendation

Required E2E: None
Optional E2E: docs-validation-e2e, docs-links-pr, docs-cli-parity-pr, docs-preview-pr

Dispatch hint: docs-validation-e2e

Workflow run

Full advisor summary

Pi Semantic E2E Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

  • None. This PR is documentation-only: it edits prose, reorders landing-page cards and the toctree, renames the 'How It Works' page to 'Architecture Overview', and adds one diagram image. There are no changes to the CLI, plugin, blueprint, policies, installer, workflows, or tests, so none of the product E2E flows (onboard, inference routing, sandbox lifecycle, networking, credentials, deployment) can be affected. Standard docs-validation, link-check, CLI-parity, and preview jobs already cover this class of change and are listed as optional.

Optional E2E

  • docs-validation-e2e (low): Docs-only PR that renames pages, edits toctree entries (e.g. prerequisites.md's windows-preparation entry uses a new label syntax), and rewrites intra-doc links (Ecosystem, Architecture Overview, Inference Options, Network Policies, Troubleshooting). The nightly docs-validation-e2e job (test/e2e/test-docs-validation.sh) is a cheap confidence check that the Sphinx/MyST build and doc references still resolve.
  • docs-links-pr (low): Several cross-references were rewritten or retargeted (e.g. 'How It Works' link now points to 'Architecture Overview', new Ecosystem link added to README's documentation table, quickstart next-steps replaced with new anchors). Running the PR link checker reduces the risk of broken anchors/links landing on main.
  • docs-cli-parity-pr (low): Quickstart and Hermes quickstart pages edit CLI-example sections (non-interactive onboard, next-steps). The docs-cli-parity PR workflow exists specifically to catch drift between the docs and the CLI reference, so it is a useful confidence check even though no command examples were substantively changed.
  • docs-preview-pr (low): A new image (nemoclaw-highlevel-component-diagram.png) is embedded via a {figure} directive in how-it-works.md. A docs preview build confirms the image renders and the page layout is correct.

New E2E recommendations

  • None.

Dispatch hint

  • Workflow: nightly-e2e.yaml
  • jobs input: docs-validation-e2e

@miyoungc miyoungc added documentation VDR Linked to VDR finding labels May 12, 2026

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

🧹 Nitpick comments (4)
docs/about/ecosystem.md (2)

31-32: ⚡ Quick win

Switch passive wording to active voice in the opening sentence.

Line 31 uses passive construction (“are put together”). Rephrase in active voice.

As per coding guidelines, "Active voice required. Flag passive constructions."

🤖 Prompt for 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.

In `@docs/about/ecosystem.md` around lines 31 - 32, Change the passive sentence
"There are three pieces that are put together in a NemoClaw deployment:
OpenClaw, OpenShell, and NemoClaw, each with a distinct scope." to active voice
by making the subject perform the action (for example: "Three components make up
a NemoClaw deployment: OpenClaw, OpenShell, and NemoClaw, each with a distinct
scope.") — update the opening sentence in docs/about/ecosystem.md accordingly to
satisfy the "Active voice required" guideline.

31-31: ⚡ Quick win

Avoid colons in prose clauses where no list follows.

These colons act as general punctuation rather than introducing lists. Use a period or comma structure instead.

As per coding guidelines, "Colons should only introduce a list. Flag colons used as general punctuation between clauses."

Also applies to: 64-64, 66-66

🤖 Prompt for 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.

In `@docs/about/ecosystem.md` at line 31, The sentence "There are three pieces
that are put together in a NemoClaw deployment: OpenClaw, OpenShell, and
NemoClaw, each with a distinct scope." uses a colon as general punctuation;
update that sentence (and the similar lines at 64 and 66) to remove the colon
and use a period or comma structure instead (e.g., "There are three pieces that
are put together in a NemoClaw deployment. OpenClaw, OpenShell, and NemoClaw
each have a distinct scope." or "There are three pieces that are put together in
a NemoClaw deployment — OpenClaw, OpenShell, and NemoClaw — each with a distinct
scope.") so colons only introduce actual lists.
docs/about/overview.md (2)

23-23: ⚡ Quick win

Align H1 with frontmatter page title.

The H1 does not match title.page ("NemoClaw Overview: What It Is"), which breaks the page-structure rule for docs pages.

As per coding guidelines, "H1 heading matches the title.page frontmatter value."

🤖 Prompt for 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.

In `@docs/about/overview.md` at line 23, The H1 heading currently reads "Overview
of NVIDIA NemoClaw" but must match the frontmatter key title.page ("NemoClaw
Overview: What It Is"); update the top-level H1 in this document to exactly
"NemoClaw Overview: What It Is" so the page title and H1 are identical and
comply with the page-structure rule.

48-48: ⚡ Quick win

Split this into one sentence per source line.

This line currently contains multiple sentences; docs require one sentence per line for review-friendly diffs.

As per coding guidelines, "One sentence per line in source (makes diffs readable). Flag paragraphs where multiple sentences appear on the same line."

🤖 Prompt for 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.

In `@docs/about/overview.md` at line 48, The table row containing "Messaging
channels | OpenShell-managed processes connect Telegram, Discord, Slack, and
similar platforms to the sandboxed agent. NemoClaw configures channels during
onboarding; OpenShell supplies the native constructs, credential flow, and
runtime supervision." should be split so each sentence occupies its own source
line; update the cell so one line reads "Messaging channels | OpenShell-managed
processes connect Telegram, Discord, Slack, and similar platforms to the
sandboxed agent." and the next line reads "NemoClaw configures channels during
onboarding; OpenShell supplies the native constructs, credential flow, and
runtime supervision." thereby ensuring one sentence per line while preserving
the table structure and wording (references: the "Messaging channels" table row
and the NemoClaw sentence).
🤖 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 `@docs/about/how-it-works.md`:
- Line 3: The page title string page: "NemoClaw Architecture Overview: Plugin,
Blueprint, and Sandbox Lifecycle" contains a colon which violates the docs title
rule; update that string to a no-colon variant (e.g., replace the colon with
"and" or split wording) so it reads something like page: "NemoClaw Architecture
Overview and Plugin, Blueprint, and Sandbox Lifecycle" (or another clear
no-colon phrasing) to satisfy the guideline; ensure you only change the title
string value.

In `@docs/about/overview.md`:
- Line 31: The docs line currently links to the third-party repo
"https://github.com/NVIDIA/OpenShell" which violates the markdown rule; remove
the hyperlink and either leave "NVIDIA OpenShell" as plain text or replace it
with a non-link reference (e.g., "NVIDIA OpenShell (project)") in the sentence
that mentions the sandbox runtime and the `nemoclaw` CLI so the prose no longer
contains an external GitHub link.
- Line 28: Update the sentence "This enables self-evolving claws to run more
safely in clouds, on prem, RTX PCs and DGX Spark." to use hyphenated "on-prem"
instead of "on prem" so it reads "This enables self-evolving claws to run more
safely in clouds, on-prem, RTX PCs and DGX Spark."; ensure only the
spacing/hyphenation is changed and no other wording is altered.

In `@docs/get-started/quickstart-hermes.md`:
- Around line 30-33: Replace the unsupported MyST admonition type "admonition"
with a supported callout such as "warning" (or "note"/"tip") in the Hermes agent
block so it conforms to the docs callout rule; specifically update the opening
tag :::{admonition} to :::{warning} (and keep the same inner text and closing
:::) so the Hermes experimental feature note uses a valid MyST admonition.

In `@docs/index.md`:
- Line 143: The sentence "To find detailed instruction on the installation
process, refer to the [Quickstart](get-started/quickstart.md) guide." uses
singular "instruction" incorrectly; update that phrase to "detailed
instructions" so the sentence reads "To find detailed instructions on the
installation process, refer to the [Quickstart](get-started/quickstart.md)
guide." and keep the rest of the sentence and link unchanged.

---

Nitpick comments:
In `@docs/about/ecosystem.md`:
- Around line 31-32: Change the passive sentence "There are three pieces that
are put together in a NemoClaw deployment: OpenClaw, OpenShell, and NemoClaw,
each with a distinct scope." to active voice by making the subject perform the
action (for example: "Three components make up a NemoClaw deployment: OpenClaw,
OpenShell, and NemoClaw, each with a distinct scope.") — update the opening
sentence in docs/about/ecosystem.md accordingly to satisfy the "Active voice
required" guideline.
- Line 31: The sentence "There are three pieces that are put together in a
NemoClaw deployment: OpenClaw, OpenShell, and NemoClaw, each with a distinct
scope." uses a colon as general punctuation; update that sentence (and the
similar lines at 64 and 66) to remove the colon and use a period or comma
structure instead (e.g., "There are three pieces that are put together in a
NemoClaw deployment. OpenClaw, OpenShell, and NemoClaw each have a distinct
scope." or "There are three pieces that are put together in a NemoClaw
deployment — OpenClaw, OpenShell, and NemoClaw — each with a distinct scope.")
so colons only introduce actual lists.

In `@docs/about/overview.md`:
- Line 23: The H1 heading currently reads "Overview of NVIDIA NemoClaw" but must
match the frontmatter key title.page ("NemoClaw Overview: What It Is"); update
the top-level H1 in this document to exactly "NemoClaw Overview: What It Is" so
the page title and H1 are identical and comply with the page-structure rule.
- Line 48: The table row containing "Messaging channels | OpenShell-managed
processes connect Telegram, Discord, Slack, and similar platforms to the
sandboxed agent. NemoClaw configures channels during onboarding; OpenShell
supplies the native constructs, credential flow, and runtime supervision."
should be split so each sentence occupies its own source line; update the cell
so one line reads "Messaging channels | OpenShell-managed processes connect
Telegram, Discord, Slack, and similar platforms to the sandboxed agent." and the
next line reads "NemoClaw configures channels during onboarding; OpenShell
supplies the native constructs, credential flow, and runtime supervision."
thereby ensuring one sentence per line while preserving the table structure and
wording (references: the "Messaging channels" table row and the NemoClaw
sentence).
🪄 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: 3aad401e-d879-4226-a037-5f5af24ce16c

📥 Commits

Reviewing files that changed from the base of the PR and between 81fc920 and dc7fa57.

⛔ Files ignored due to path filters (1)
  • docs/about/images/nemoclaw-highlevel-component-diagram.png is excluded by !**/*.png
📒 Files selected for processing (9)
  • README.md
  • docs/about/ecosystem.md
  • docs/about/how-it-works.md
  • docs/about/overview.md
  • docs/get-started/prerequisites.md
  • docs/get-started/quickstart-hermes.md
  • docs/get-started/quickstart.md
  • docs/index.md
  • docs/reference/architecture.md

Comment thread docs/about/how-it-works.md
Comment thread docs/about/overview.md
Comment thread docs/about/overview.md
Comment thread docs/get-started/quickstart-hermes.md
Comment thread docs/index.md Outdated
@miyoungc miyoungc marked this pull request as draft May 12, 2026 00:02
@copy-pr-bot

copy-pr-bot Bot commented May 12, 2026

Copy link
Copy Markdown

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.

Comment thread docs/index.md Outdated
@miyoungc miyoungc marked this pull request as ready for review May 12, 2026 01:20
@miyoungc miyoungc requested review from cv and ericksoa May 12, 2026 01:21

@ericksoa ericksoa left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the docs changes and linked diagram against #2602, checked the PR head against current main, and verified local docs validation with npm run docs:strict plus the docs-to-skills dry run. No regression blockers found.

@ericksoa ericksoa merged commit fc4a227 into main May 12, 2026
28 checks passed
@ericksoa ericksoa deleted the docs/improve-about-pages branch May 12, 2026 21:17
@wscurran wscurran added area: docs Documentation, examples, guides, or docs build chore Build, CI, dependency, or tooling maintenance and removed documentation labels Jun 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: docs Documentation, examples, guides, or docs build chore Build, CI, dependency, or tooling maintenance VDR Linked to VDR finding

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[All Platforms][Docs] Get Started materials lack a high-level architecture diagram

3 participants