docs: consolidate information architecture and author content

docs/about/architecture.md

@@ -0,0 +1,81 @@
+---
+title:
+  page: "Architecture Overview"
+  nav: "Architecture"
+description: "High-level overview of the OpenShell architecture: gateway, sandboxes, policy engine, and privacy router."
+keywords: ["nemoclaw architecture", "sandbox architecture", "agent isolation", "k3s", "policy engine"]
+topics: ["generative_ai", "cybersecurity"]
+tags: ["ai_agents", "sandboxing", "security", "architecture"]
+content:
+  type: concept
+  difficulty: technical_beginner
+  audience: [engineer, data_scientist]
+---
+
+<!--
+  SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+  SPDX-License-Identifier: Apache-2.0
+-->
+
+# How OpenShell Works
+
+NemoClaw runs as a [k3s](https://k3s.io/) Kubernetes cluster inside a Docker container.
+Each sandbox is an isolated Kubernetes pod managed by the OpenShell control plane.
+Four components work together to keep agents secure.
+
+```{mermaid}
+flowchart LR
+    CLI["CLI"] -->|gRPC| GW["Gateway"]
+    GW --> SBX["Sandbox"]
+
+    subgraph SBX["Sandbox"]
+        direction TB
+        AGENT["Agent Process"] -->|All traffic| PROXY["Network Proxy"]
+        PROXY -->|Evaluate| OPA["Policy Engine"]
+    end
+
+    PROXY -->|Allowed traffic| EXT["External Services"]
+
+    style CLI fill:#ffffff,stroke:#000000,color:#000000
+    style GW fill:#76b900,stroke:#000000,color:#000000
+    style SBX fill:#f5f5f5,stroke:#000000,color:#000000
+    style AGENT fill:#ffffff,stroke:#000000,color:#000000
+    style PROXY fill:#76b900,stroke:#000000,color:#000000
+    style OPA fill:#76b900,stroke:#000000,color:#000000
+    style EXT fill:#ffffff,stroke:#000000,color:#000000
+
+    linkStyle default stroke:#76b900,stroke-width:2px
+```
+
+## Components
+
+NemoClaw consists of the following components.
+
+Gateway
+: The control-plane API that manages sandbox lifecycle, stores encrypted credentials, distributes policies, and terminates SSH tunnels. The CLI communicates exclusively with the gateway—it never talks to sandbox pods directly.
+
+Sandbox
+: An isolated pod that runs your agent. Each sandbox contains a **supervisor** (sets up isolation and starts the agent), an **L7 proxy** (intercepts and evaluates every outbound connection), and the agent process itself.
+
+Policy Engine
+: Evaluates declarative YAML policies that define filesystem, network, and process constraints. The proxy queries the engine on every outbound connection. Policies can be hot-reloaded without restarting the agent.
+
+Privacy Router
+: Intercepts LLM API calls and routes them to local or self-hosted backends based on your routing policy. Sensitive prompts and completions stay on infrastructure you control.
+
+## How a Request Flows
+
+NemoClaw works in the following way:
+
+1. The agent makes an outbound connection (for example, an API call).
+2. The L7 proxy intercepts the connection and identifies the calling process.
+3. The proxy queries the policy engine with the destination and process identity.
+4. Based on the policy decision, the proxy either allows the connection, routes it through the privacy router for inference, or denies it.
+
+## Remote Deployment
+
+NemoClaw can also run on a remote host. Deploy with `nemoclaw gateway start --remote user@host`, then set up a tunnel with `nemoclaw gateway tunnel`. The architecture is identical—only the Docker container location changes.
+
+---
+
+For detailed component internals, refer to the [Architecture Reference](../reference/architecture.md).

docs/about/overview.md

@@ -0,0 +1,80 @@
+---
+title:
+  page: "Overview of NVIDIA OpenShell"
+  nav: "Overview"
+description: "NemoClaw is the safe, private runtime for autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure."
+keywords: ["nemoclaw", "ai agent sandbox", "agent security", "agent isolation", "inference routing"]
+topics: ["generative_ai", "cybersecurity"]
+tags: ["ai_agents", "sandboxing", "security", "privacy", "inference_routing"]
+content:
+  type: concept
+  difficulty: technical_beginner
+  audience: [engineer, data_scientist]
+---
+
+<!--
+  SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+  SPDX-License-Identifier: Apache-2.0
+-->
+
+# Overview of NVIDIA OpenShell
+
+NVIDIA OpenShell is an open-source runtime that executes autonomous AI agents inside sandboxed environments with kernel-level isolation. It prevents agents from accessing unauthorized files, exfiltrating data, leaking credentials, or making uncontrolled network requests. A single declarative YAML policy governs filesystem, network, process, and inference protections across all sandboxes and is hot-reloadable without restarting running agents.
+
+## Common Challenges with AI Agents
+
+AI agents are most useful when they have broad access to reading files, installing packages, calling APIs, and using credentials. However, this same access makes them dangerous. An unrestricted agent can leak your API keys, send proprietary code to unauthorized endpoints, or reach infrastructure it was never meant to touch.
+
+Conventional containers do not solve this. They isolate processes from the host, but they do not control what an agent does *inside* the container — which files it reads, which hosts it contacts, or where it sends your prompts.
+
+## Benefits of Using OpenShell
+
+NemoClaw addresses these risks through defense-in-depth enforcement across four policy domains: filesystem, network, process, and inference.
+
+:::{dropdown} 🛡️ Kernel-Level Isolation
+NemoClaw enforces isolation at the Linux kernel level using Landlock for filesystem restrictions, seccomp for system call filtering, and network namespaces for traffic control. These mechanisms operate below the application layer, so agents cannot bypass them regardless of the tools or languages they use.
+:::
+
+:::{dropdown} 📜 Declarative Policy Enforcement
+A single YAML policy file defines all security boundaries for a sandbox: allowed filesystem paths, permitted network destinations, restricted processes, and inference routing rules. Policies are hot-reloadable, so you can tighten or relax rules on a running sandbox without restarting the agent.
+:::
+
+:::{dropdown} 🔐 Credential Containment
+Credentials are injected into sandboxes as environment variables at startup and are scoped to the sandbox's isolated namespace. They cannot be read by processes outside the sandbox, and network policies prevent agents from transmitting them to unauthorized endpoints.
+:::
+
+:::{dropdown} 🔀 Private Inference Routing
+The built-in inference router intercepts LLM API calls and redirects them to local or self-hosted backends based on your routing policy. Sensitive prompts and completions stay on infrastructure you control. Routes are configurable per sandbox and can be updated without restarting agents.
+:::
+
+:::{dropdown} 🔍 Full L7 Traffic Inspection
+Every outbound TCP connection from a sandbox passes through an L7 proxy that resolves the calling process, evaluates the destination against the active policy, and either allows, denies, or reroutes the request. For REST endpoints, the proxy decrypts TLS, inspects HTTP method and path, and applies fine-grained access rules.
+:::
+
+## Use Cases
+
+The following are common use cases for OpenShell.
+
+:::{dropdown} 💻 Secure Coding Agents
+Run AI coding assistants such as Claude Code, OpenCode, or OpenClaw inside a sandbox where they can read and modify project files but cannot access SSH keys, cloud credentials, or files outside the project directory. Network policies restrict which package registries and APIs the agent can reach.
+:::
+
+:::{dropdown} 🏢 Private Enterprise Development
+Route all LLM inference through self-hosted NVIDIA NIM endpoints or private API backends. Proprietary source code and internal documentation stay on your infrastructure and are never sent to third-party LLM providers.
+:::
+
+:::{dropdown} ✅ Compliance and Audit
+Declarative policies serve as auditable security controls. Each sandbox runs under a well-defined policy that specifies exactly what the agent can access. Policy files can be version-controlled and reviewed as part of your security and compliance processes.
+:::
+
+:::{dropdown} 📦 Community and Custom Sandbox Images
+Use pre-built sandbox images from the [NemoClaw Community](https://github.com/NVIDIA/NemoClaw-Community) catalog or bring your own container. Community sandboxes bundle domain-specific tools, policies, and skills, while custom containers let you package any environment your agents need.
+:::
+
+---
+
+## Next Steps
+
+- [Architecture Overview](architecture.md): Understand the components that make up the OpenShell runtime.
+- [Get Started](../index.md): Install the CLI and create your first sandbox.
+- [Security Model](../safety-and-privacy/security-model.md): Learn how OpenShell enforces isolation across all protection layers.

docs/about/release-notes.md

@@ -0,0 +1,13 @@
+<!--
+  SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+  SPDX-License-Identifier: Apache-2.0
+-->
+
+# Release Notes
+
+This page covers the highlights of each OpenShell release.
+For more details, refer to the [NemoClaw GitHub Releases](https://github.com/NVIDIA/NemoClaw/releases).
+
+## 0.1.0
+
+This is the first release of NVIDIA OpenShell. It introduces sandboxed AI agent execution with kernel-level isolation, policy enforcement, and credential management.

docs/conf.py

@@ -7,7 +7,7 @@
 
 sys.path.insert(0, str(Path(__file__).parent.parent))
 
-project = "NVIDIA NemoClaw Developer Guide"
+project = "NVIDIA OpenShell Developer Guide"
 this_year = date.today().year
 copyright = f"2025-{this_year}, NVIDIA Corporation"
 author = "NVIDIA Corporation"
@@ -38,6 +38,7 @@
 
 exclude_patterns = [
     "README.md",
+    "SETUP.md",
     "_build/**",
 ]
 
@@ -63,6 +64,23 @@
 html_show_sourcelink = False
 html_show_sphinx = False
 
+mermaid_init_js = (
+    "mermaid.initialize({"
+    "  startOnLoad: true,"
+    "  theme: 'base',"
+    "  themeVariables: {"
+    "    background: '#ffffff',"
+    "    primaryColor: '#76b900',"
+    "    primaryTextColor: '#000000',"
+    "    primaryBorderColor: '#000000',"
+    "    lineColor: '#000000',"
+    "    textColor: '#000000',"
+    "    mainBkg: '#ffffff',"
+    "    nodeBorder: '#000000'"
+    "  }"
+    "});"
+)
+
 html_domain_indices = False
 html_use_index = False
 highlight_language = "console"
@@ -75,5 +93,11 @@
             "icon": "fa-brands fa-github",
             "type": "fontawesome",
         },
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/nemoclaw/",
+            "icon": "fa-brands fa-python",
+            "type": "fontawesome",
+        },
     ],
 }

docs/get-started/quickstart.md

@@ -0,0 +1,93 @@
+---
+title:
+  page: "Quickstart"
+  nav: "Quickstart"
+description: "Install the OpenShell CLI and create your first sandboxed AI agent in two commands."
+keywords: ["nemoclaw install", "quickstart", "sandbox create", "getting started"]
+topics: ["generative_ai", "cybersecurity"]
+tags: ["ai_agents", "sandboxing", "installation", "quickstart"]
+content:
+  type: get_started
+  difficulty: technical_beginner
+  audience: [engineer, data_scientist]
+---
+
+<!--
+  SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+  SPDX-License-Identifier: Apache-2.0
+-->
+
+# Quickstart
+
+This page gets you from zero to a running, policy-enforced sandbox in two commands.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- Python 3.12 or later
+- Docker Desktop running on your machine <!-- TODO: add compatible version -->
+
+## Install the OpenShell CLI
+
+```bash
+pip install nemoclaw
+```
+
+## Create Your First OpenShell Sandbox
+
+Choose the tab that matches your agent:
+
+::::{tab-set}
+
+:::{tab-item} Claude Code
+```console
+$ nemoclaw sandbox create -- claude
+```
+
+```text
+✓ Runtime ready
+✓ Discovered Claude credentials (ANTHROPIC_API_KEY)
+✓ Created sandbox: keen-fox
+✓ Policy loaded (4 protection layers active)
+
+Connecting to keen-fox...
+```
+
+The CLI detects your `ANTHROPIC_API_KEY`, creates a provider, builds the sandbox, applies a default policy, and drops you into an interactive session. No additional configuration is required.
+:::
+
+:::{tab-item} Community Sandbox
+```console
+$ nemoclaw sandbox create --from openclaw
+```
+
+The `--from` flag pulls a pre-built sandbox definition from the [NemoClaw Community](https://github.com/NVIDIA/NemoClaw-Community) catalog. Each definition bundles a container image, a tailored policy, and optional skills into a single package.
+:::
+
+::::
+
+## What Happens Behind the Scenes
+
+When you create a sandbox, OpenShell activates the following protection layers.
+
+| Protection Layer        | Description                                                                                   |
+|------------------------|-----------------------------------------------------------------------------------------------|
+| Filesystem isolation   | The agent can only read and write paths that the policy explicitly permits.                   |
+| Network enforcement    | Outbound connections are denied by default. The policy allowlists specific hosts, ports, and binaries. |
+| Process restrictions   | The agent runs as a non-root user inside the container.                                       |
+| Inference privacy     | LLM API traffic is routed through a privacy-aware proxy. Credentials never leak outside the sandbox. |
+
+A single YAML policy file controls all four layers. You can hot-reload network and inference rules on a running sandbox without restarting it.
+
+:::{note}
+For OpenCode or Codex, the default policy does not cover the required endpoints. Follow the [Run OpenCode with NVIDIA Inference](run-opencode.md) tutorial for agent-specific setup.
+:::
+
+## Next Steps
+
+You now have a working sandbox. From here, you can:
+
+- Follow the [Tutorials](tutorials.md) for step-by-step walkthroughs with Claude Code, OpenClaw, and OpenCode.
+- Learn how sandboxes work in [Sandboxes](../sandboxes/create-and-manage.md).
+- Write your own policies in [Safety and Privacy](../safety-and-privacy/index.md).