docs: add architecture diagram and overview

[jyaunches]

Summary

Adds an Architecture section to the README with:

1. Mermaid diagram showing the relationship between NemoClaw and OpenShell
2. Explanatory text clarifying what each layer provides

What the diagram shows

• NemoClaw (green): Onboarding, Messaging Bridges, Blueprint, State Management
• OpenShell (dark): Gateway, CLI, Sandbox container
• Data flows: Credential-safe inference path, message relay via SSH, policy-gated egress

Key message

OpenShell handles how to sandbox an agent securely. NemoClaw handles what goes in the sandbox and makes the setup accessible.

Screenshots

The mermaid diagram renders natively on GitHub. Preview in the Files Changed tab.

Summary by CodeRabbit

• Documentation
  • Added Architecture section to README explaining NemoClaw's layered structure on top of OpenShell, covering onboarding, blueprint hardening, state management, and messaging bridges. Includes a comprehensive system diagram showing control and data flow between the CLI, messaging bridges, gateway, sandbox container, and external services like inference providers and messaging platforms.

[coderabbitai]

📝 Walkthrough

Walkthrough

The README.md file was updated with a new "Architecture" section that documents NemoClaw's layered design as an opinionated stack built on OpenShell. The section includes a tabular breakdown of architectural layers and a Mermaid diagram illustrating the end-to-end control and data flow across components.

Changes

Cohort / File(s)	Summary
Documentation README.md	Added "Architecture" section with layer-by-layer breakdown and Mermaid diagram detailing NemoClaw's stack design, component interactions, and data/control flow between CLI, messaging bridges, OpenShell gateway, sandbox container, and external services.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 A rabbit's tale of architecture fine,
NemoClaw's layers, all in line,
With diagrams drawn and flows on show,
The README now helps all to know! 🏗️

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the main change: adding documentation (architecture diagram and overview) to the README.
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

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@README.md`:
- Line 49: Replace the emoji labels in the Mermaid diagram nodes with plain
text: change the USER node label USER(["👤 User"]):::user to
USER(["User"]):::user (and the Auth/lock node that uses "🔒"—e.g. AUTH(["🔒
Auth"]):::auth—to AUTH(["Auth"]):::auth); update any other diagram node labels
containing emojis to their plain-text equivalents so README.md follows the "No
emoji in technical prose" rule.
- Line 70: Update the diagram node text that currently reads OSCLI["openshell
CLI<br/><small>provider · sandbox<br/>gateway · policy</small>"]:::openshell to
use the correct product casing: change "openshell CLI" to "OpenShell CLI" while
keeping the rest of the label (the HTML line breaks and small text) unchanged so
the node still reads OSCLI["OpenShell CLI<br/><small>provider ·
sandbox<br/>gateway · policy</small>"]:::openshell.

🪄 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: Pro

Run ID: 7c3cecae-3422-40db-ac1a-562c8a6fa8c1

📥 Commits

Reviewing files that changed from the base of the PR and between 3c7bd93 and 0cdc086.

📒 Files selected for processing (1)

• README.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Remove emoji from diagram labels in technical prose.

Line 49 (👤) and Line 72 (🔒) violate the Markdown prose rule; please replace with plain text labels.

As per coding guidelines, "**/*.md ... No emoji in technical prose."

Also applies to: 72-72

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 49, Replace the emoji labels in the Mermaid diagram nodes
with plain text: change the USER node label USER(["👤 User"]):::user to
USER(["User"]):::user (and the Auth/lock node that uses "🔒"—e.g. AUTH(["🔒
Auth"]):::auth—to AUTH(["Auth"]):::auth); update any other diagram node labels
containing emojis to their plain-text equivalents so README.md follows the "No
emoji in technical prose" rule.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Fix product casing in diagram node text.

Line 70 uses openshell CLI; this should be OpenShell CLI to match required product casing.

As per coding guidelines, "**/*.md ... NemoClaw, OpenClaw, and OpenShell must use correct casing."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 70, Update the diagram node text that currently reads
OSCLI["openshell CLI<br/><small>provider · sandbox<br/>gateway ·
policy</small>"]:::openshell to use the correct product casing: change
"openshell CLI" to "OpenShell CLI" while keeping the rest of the label (the HTML
line breaks and small text) unchanged so the node still reads OSCLI["OpenShell
CLI<br/><small>provider · sandbox<br/>gateway · policy</small>"]:::openshell.