docs: split description into main/agent and clean up docs-to-skills

.agents/skills/nemoclaw-configure-inference/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: nemoclaw-configure-inference
-description: Changes the active inference model without restarting the sandbox. Use when change inference runtime, inference routing, openclaw, openshell, switch nemoclaw inference model, switch nemoclaw inference models.
+description: Changes the active inference model without restarting the sandbox. Use when switching inference providers, changing the model runtime, or reconfiguring inference routing.
 ---
 
-# Nemoclaw Configure Inference
+# NemoClaw Configure Inference
 
-Change the active inference model without restarting the sandbox.
+Changes the active inference model without restarting the sandbox. Use when switching inference providers, changing the model runtime, or reconfiguring inference routing.
 
 ## Prerequisites
 

.agents/skills/nemoclaw-deploy-remote/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: nemoclaw-deploy-remote
-description: Provisions a remote GPU VM with NemoClaw using Brev deployment. Also covers securities hardening measures applied to the NemoClaw sandbox container image; forwards messages between Telegram and the sandboxed OpenClaw agent. Use when container security, deploy nemoclaw remote gpu, deployment, docker capabilities, gpu, nemoclaw, nemoclaw brev cloud deployment, nemoclaw sandbox hardening.
+description: Provisions a remote GPU VM with NemoClaw using Brev deployment. Use when deploying to a cloud GPU, setting up a remote NemoClaw instance, or configuring Brev. Describes security hardening measures applied to the NemoClaw sandbox container image. Use when reviewing container security, Docker capabilities, process limits, or sandbox hardening controls. Forwards messages between Telegram and the sandboxed OpenClaw agent. Use when setting up a Telegram bot bridge, connecting a chat interface, or configuring Telegram integration.
 ---
 
-# Nemoclaw Deploy Remote
+# NemoClaw Deploy Remote
 
-Provision a remote GPU VM with NemoClaw using Brev deployment.
+Provisions a remote GPU VM with NemoClaw using Brev deployment. Use when deploying to a cloud GPU, setting up a remote NemoClaw instance, or configuring Brev.
 
 ## Prerequisites
 

.agents/skills/nemoclaw-get-started/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: nemoclaw-get-started
-description: Installs NemoClaw, launch a sandbox, and run your first agent prompt. Use when inference routing, install nemoclaw openclaw sandbox, nemoclaw, nemoclaw quickstart, nemoclaw quickstart install launch, openclaw, openshell, sandboxing.
+description: Installs NemoClaw, launches a sandbox, and runs the first agent prompt. Use when onboarding, installing, or launching a NemoClaw sandbox for the first time.
 ---
 
-# Nemoclaw Get Started
+# NemoClaw Get Started
 
-Install NemoClaw, launch a sandbox, and run your first agent prompt.
+Installs NemoClaw, launches a sandbox, and runs the first agent prompt. Use when onboarding, installing, or launching a NemoClaw sandbox for the first time.
 
 ## Prerequisites
 

.agents/skills/nemoclaw-manage-policy/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: nemoclaw-manage-policy
-description: Reviews and approve blocked agent network requests in the TUI. Also covers adds, remove, or modify allowed endpoints in the sandbox policy. Use when approve deny nemoclaw agent, customize nemoclaw network policy, customize nemoclaw sandbox network, nemoclaw, nemoclaw approve network requests, network policy, openclaw, openshell.
+description: Reviews and approves blocked agent network requests in the TUI. Use when approving or denying sandbox egress requests, managing blocked network calls, or using the approval TUI. Adds, removes, or modifies allowed endpoints in the sandbox policy. Use when customizing network policy, changing egress rules, or configuring sandbox endpoint access.
 ---
 
-# Nemoclaw Manage Policy
+# NemoClaw Manage Policy
 
-Review and approve blocked agent network requests in the TUI.
+Reviews and approves blocked agent network requests in the TUI. Use when approving or denying sandbox egress requests, managing blocked network calls, or using the approval TUI.
 
 ## Prerequisites
 

.agents/skills/nemoclaw-monitor-sandbox/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: nemoclaw-monitor-sandbox
-description: Inspects sandbox health, trace agent behavior, and diagnose problems. Use when debug nemoclaw agent issues, monitor nemoclaw sandbox, monitor nemoclaw sandbox activity, monitoring, nemoclaw, openclaw, openshell, troubleshooting.
+description: Inspects sandbox health, traces agent behavior, and diagnoses problems. Use when monitoring a running sandbox, debugging agent issues, or checking sandbox logs.
 ---
 
-# Nemoclaw Monitor Sandbox
+# NemoClaw Monitor Sandbox
 
-Inspect sandbox health, trace agent behavior, and diagnose problems.
+Inspects sandbox health, traces agent behavior, and diagnoses problems. Use when monitoring a running sandbox, debugging agent issues, or checking sandbox logs.
 
 ## Prerequisites
 

.agents/skills/nemoclaw-overview/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: nemoclaw-overview
-description: Learns how NemoClaw combines a lightweight CLI plugin with a versioned blueprint to move OpenClaw into a controlled sandbox. Also covers nemoClaws is an open source reference stack that simplifies running OpenClaw always-on assistants safely; changelogs and feature history for NemoClaw releases. Use when blueprints, how nemoclaw works, inference routing, nemoclaw, nemoclaw changelog, nemoclaw overview, nemoclaw overview does fits, nemoclaw release notes.
+description: Describes how NemoClaw combines a CLI plugin with a versioned blueprint to move OpenClaw into a controlled sandbox. Use when explaining the sandbox lifecycle, blueprint architecture, or how NemoClaw layers on top of OpenShell. Explains what NemoClaw does and how it fits with OpenClaw and OpenShell. Use when asking what NemoClaw is, how it works at a high level, or what the project provides. Lists changelogs and feature history for NemoClaw releases. Use when checking what changed in a release, looking up version history, or reviewing the changelog.
 ---
 
-# Nemoclaw Overview
+# NemoClaw Overview
 
-Learn how NemoClaw combines a lightweight CLI plugin with a versioned blueprint to move OpenClaw into a controlled sandbox.
+Describes how NemoClaw combines a CLI plugin with a versioned blueprint to move OpenClaw into a controlled sandbox. Use when explaining the sandbox lifecycle, blueprint architecture, or how NemoClaw layers on top of OpenShell.
 
 ## Context
 

.agents/skills/nemoclaw-reference/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: nemoclaw-reference
-description: Learns how NemoClaw combines a lightweight CLI plugin with a versioned blueprint to move OpenClaw into a controlled sandbox. Also covers fulls CLI reference for slash commands and standalone NemoClaw commands; configurations reference for NemoClaw routed inference providers. Use when blueprints, cli, inference routing, llms, nemoclaw, nemoclaw architecture, nemoclaw architecture plugin blueprint, nemoclaw cli commands.
+description: Describes how NemoClaw combines a CLI plugin with a versioned blueprint to move OpenClaw into a controlled sandbox. Use when looking up NemoClaw architecture, plugin structure, or blueprint design. Lists all slash commands and standalone NemoClaw CLI commands. Use when looking up a command, checking command syntax, or browsing the CLI reference. Documents configuration options for NemoClaw routed inference providers. Use when configuring inference profiles, looking up provider routing settings, or reviewing available LLM providers. Documents baseline network policy, filesystem rules, and operator approval flow. Use when reviewing default network policies, understanding egress controls, or looking up the approval flow. Diagnoses and resolves common NemoClaw installation, onboarding, and runtime issues. Use when troubleshooting errors, debugging sandbox problems, or resolving setup failures.
 ---
 
-# Nemoclaw Reference
+# NemoClaw Reference
 
-Learn how NemoClaw combines a lightweight CLI plugin with a versioned blueprint to move OpenClaw into a controlled sandbox.
+Describes how NemoClaw combines a CLI plugin with a versioned blueprint to move OpenClaw into a controlled sandbox. Use when looking up NemoClaw architecture, plugin structure, or blueprint design.
 
 ## Reference
 

.agents/skills/nemoclaw-security-best/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: nemoclaw-security-best
-description: As risk framework for every configurable security control in NemoClaw: defaults, what you can change, and what happens if you do. Use when nemoclaw, nemoclaw security best practices, network policy, openclaw, openshell, sandbox security controls risk framework, sandboxing, security.
+description: Presents a risk framework for every configurable security control in NemoClaw. Use when evaluating security posture, reviewing sandbox security defaults, or assessing control trade-offs.
 ---
 
-# Nemoclaw Security Best
+# NemoClaw Security Best
 
-A risk framework for every configurable security control in NemoClaw: defaults, what you can change, and what happens if you do.
+Presents a risk framework for every configurable security control in NemoClaw. Use when evaluating security posture, reviewing sandbox security defaults, or assessing control trade-offs.
 
 ## Context
 

.agents/skills/nemoclaw-workspace/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: nemoclaw-workspace
-description: Hows to back up and restore OpenClaw workspace files before destructive operations. Also covers whats workspace files are, where they live, and how they persist across sandbox restarts. Use when agents.md, back restore workspace files, backup, identity.md, memory.md, nemoclaw, nemoclaw backup, nemoclaw restore.
+description: Backs up and restores OpenClaw workspace files before destructive operations. Use when backing up a sandbox, restoring workspace state, or preparing for a destructive operation. Explains what workspace files are, where they live, and how they persist across sandbox restarts. Use when asking about soul.md, identity.md, memory.md, agents.md, or sandbox file persistence.
 ---
 
-# Nemoclaw Workspace
+# NemoClaw Workspace
 
-How to back up and restore OpenClaw workspace files before destructive operations.
+Backs up and restores OpenClaw workspace files before destructive operations. Use when backing up a sandbox, restoring workspace state, or preparing for a destructive operation.
 
 ## Context
 

docs/CONTRIBUTING.md

@@ -88,7 +88,7 @@ make docs-live
 ### Format
 
 - Docs use [MyST Markdown](https://myst-parser.readthedocs.io/), a Sphinx-compatible superset of CommonMark.
-- Every page starts with YAML frontmatter (title, description, topics, tags, content type).
+- Every page starts with YAML frontmatter (title, description.main, description.agent, topics, tags, content type).
 - Include the SPDX license header after frontmatter:
 
   ```html
@@ -105,7 +105,9 @@ make docs-live
 title:
   page: "NemoClaw Page Title — Subtitle with Context"
   nav: "Short Nav Title"
-description: "One-sentence summary of the page."
+description:
+  main: "One-sentence summary for readers, SEO, and doc search snippets."
+  agent: "Third-person verb summary for agent routing. Add 'Use when...' with trigger phrases."
 keywords: ["primary keyword", "secondary keyword phrase"]
 topics: ["generative_ai", "ai_agents"]
 tags: ["openclaw", "openshell", "relevant", "tags"]

docs/_ext/json_output/core/json_formatter.py

@@ -32,6 +32,24 @@
 logger = logging.getLogger(__name__)
 
 
+def _normalize_description_fields(metadata: dict[str, Any]) -> tuple[str, str]:
+    """Parse description from frontmatter: nested main/agent or legacy flat string."""
+    raw = metadata.get("description")
+    if isinstance(raw, dict):
+        main = str(raw.get("main") or "").strip()
+        agent = str(raw.get("agent") or "").strip()
+        if main and not agent:
+            agent = main
+        elif agent and not main:
+            main = agent
+        return main, agent
+    if raw is not None and not isinstance(raw, dict):
+        text = str(raw).strip()
+        if text:
+            return text, text
+    return "", ""
+
+
 class JSONFormatter:
     """Handles JSON data structure building and formatting."""
 
@@ -56,9 +74,12 @@ def add_metadata_fields(self, data: dict[str, Any], metadata: dict[str, Any]) ->
         New schema: topics, tags, industry, content.type, content.learning_level, content.audience, facets.modality
         Legacy schema: categories, personas, difficulty, content_type, modality
         """
-        # Basic metadata fields
-        if metadata.get("description"):
-            data["description"] = metadata["description"]
+        # Basic metadata fields — nested description.main / description.agent or legacy string
+        main_desc, agent_desc = _normalize_description_fields(metadata)
+        if main_desc:
+            data["description"] = main_desc
+        if agent_desc and agent_desc != main_desc:
+            data["description_agent"] = agent_desc
 
         # Tags (same in both schemas)
         if metadata.get("tags"):

docs/_ext/search_assets/modules/DocumentLoader.js

@@ -105,6 +105,7 @@ class DocumentLoader {
             title: this.sanitizeText(doc.title, 200),
             // Add description as separate indexed field (for improved search relevance)
             description: this.sanitizeText(doc.description, 300),
+            description_agent: this.sanitizeText(doc.description_agent, 300),
             content: this.sanitizeText(doc.content, 5000),
             summary: this.sanitizeText(doc.summary, 500),
             headings: this.sanitizeHeadings(doc.headings),

docs/_ext/search_assets/modules/SearchEngine.js

@@ -188,7 +188,8 @@ class SearchEngine {
 
             // Primary fields - highest relevance
             this.field('title', { boost: 10 });           // Title matches most important
-            this.field('description', { boost: 8 });      // Frontmatter description (hand-crafted)
+            this.field('description', { boost: 8 });      // Frontmatter description.main (hand-crafted)
+            this.field('description_agent', { boost: 6 }); // description.agent for agent-oriented phrasing
 
             // Secondary fields - structural relevance
             this.field('keywords', { boost: 7 });         // Explicit keywords
@@ -215,7 +216,10 @@ class SearchEngine {
                     this.add({
                         id: doc.id,
                         title: doc.title || '',
-                        description: doc.description || '',  // NEW: separate indexed field
+                        description: doc.description || '',
+                        description_agent: doc.description_agent && doc.description_agent !== doc.description
+                            ? doc.description_agent
+                            : '',
                         content: (doc.content || '').substring(0, 5000), // Limit content length
                         summary: doc.summary || '',
                         headings: self.extractHeadingsText(doc.headings),
@@ -641,19 +645,21 @@ class SearchEngine {
      * Calculate boost for description matches
      */
     calculateDescriptionBoost(doc, queryTerms) {
-        if (!doc.description) return 0;
+        const texts = [...new Set(
+            [doc.description, doc.description_agent].filter(Boolean)
+        )];
+        if (texts.length === 0) return 0;
 
-        const descLower = doc.description.toLowerCase();
         let boost = 0;
-
-        // Check if query terms appear early in description
-        queryTerms.forEach(term => {
-            const pos = descLower.indexOf(term);
-            if (pos !== -1) {
-                // Boost more if term appears early
-                boost += pos < 50 ? 1 : 0.5;
-            }
-        });
+        for (const text of texts) {
+            const descLower = text.toLowerCase();
+            queryTerms.forEach(term => {
+                const pos = descLower.indexOf(term);
+                if (pos !== -1) {
+                    boost += pos < 50 ? 1 : 0.5;
+                }
+            });
+        }
 
         return boost;
     }

docs/about/how-it-works.md

@@ -2,7 +2,9 @@
 title:
   page: "How NemoClaw Works — Plugin, Blueprint, and Sandbox Lifecycle"
   nav: "How It Works"
-description: "Learn how NemoClaw combines a lightweight CLI plugin with a versioned blueprint to move OpenClaw into a controlled sandbox."
+description:
+  main: "Learn how NemoClaw combines a lightweight CLI plugin with a versioned blueprint to move OpenClaw into a controlled sandbox."
+  agent: "Describes how NemoClaw combines a CLI plugin with a versioned blueprint to move OpenClaw into a controlled sandbox. Use when explaining the sandbox lifecycle, blueprint architecture, or how NemoClaw layers on top of OpenShell."
 keywords: ["how nemoclaw works", "nemoclaw sandbox lifecycle blueprint"]
 topics: ["generative_ai", "ai_agents"]
 tags: ["openclaw", "openshell", "sandboxing", "inference_routing", "blueprints", "network_policy"]

docs/about/overview.md

@@ -2,7 +2,9 @@
 title:
   page: "NemoClaw Overview — What It Does and How It Fits Together"
   nav: "Overview"
-description: "NemoClaw is an open source reference stack that simplifies running OpenClaw always-on assistants safely."
+description:
+  main: "NemoClaw is an open source reference stack that simplifies running OpenClaw always-on assistants safely."
+  agent: "Explains what NemoClaw does and how it fits with OpenClaw and OpenShell. Use when asking what NemoClaw is, how it works at a high level, or what the project provides."
 keywords: ["nemoclaw overview", "openclaw always-on assistants", "nvidia openshell", "nvidia nemotron"]
 topics: ["generative_ai", "ai_agents"]
 tags: ["openclaw", "openshell", "sandboxing", "inference_routing", "blueprints"]

docs/about/release-notes.md

@@ -2,7 +2,9 @@
 title:
   page: "NemoClaw Release Notes"
   nav: "Release Notes"
-description: "Changelog and feature history for NemoClaw releases."
+description:
+  main: "Changelog and feature history for NemoClaw releases."
+  agent: "Lists changelogs and feature history for NemoClaw releases. Use when checking what changed in a release, looking up version history, or reviewing the changelog."
 keywords: ["nemoclaw release notes", "nemoclaw changelog"]
 topics: ["generative_ai", "ai_agents"]
 tags: ["nemoclaw", "releases"]

docs/deployment/deploy-to-remote-gpu.md

@@ -2,7 +2,9 @@
 title:
   page: "Deploy NemoClaw to a Remote GPU Instance with Brev"
   nav: "Deploy to Remote GPU"
-description: "Provision a remote GPU VM with NemoClaw using Brev deployment."
+description:
+  main: "Provision a remote GPU VM with NemoClaw using Brev deployment."
+  agent: "Provisions a remote GPU VM with NemoClaw using Brev deployment. Use when deploying to a cloud GPU, setting up a remote NemoClaw instance, or configuring Brev."
 keywords: ["deploy nemoclaw remote gpu", "nemoclaw brev cloud deployment"]
 topics: ["generative_ai", "ai_agents"]
 tags: ["openclaw", "openshell", "deployment", "gpu", "nemoclaw"]

docs/deployment/sandbox-hardening.md

@@ -2,7 +2,9 @@
 title:
   page: "Sandbox Image Hardening"
   nav: "Sandbox Hardening"
-description: "Security hardening measures applied to the NemoClaw sandbox container image."
+description:
+  main: "Security hardening measures applied to the NemoClaw sandbox container image."
+  agent: "Describes security hardening measures applied to the NemoClaw sandbox container image. Use when reviewing container security, Docker capabilities, process limits, or sandbox hardening controls."
 keywords: ["nemoclaw sandbox hardening", "container security", "docker capabilities", "process limits"]
 topics: ["generative_ai", "ai_agents"]
 tags: ["nemoclaw", "sandboxing", "security"]

docs/deployment/set-up-telegram-bridge.md

@@ -2,7 +2,9 @@
 title:
   page: "Set Up the NemoClaw Telegram Bridge for Remote Agent Chat"
   nav: "Set Up Telegram Bridge"
-description: "Forward messages between Telegram and the sandboxed OpenClaw agent."
+description:
+  main: "Forward messages between Telegram and the sandboxed OpenClaw agent."
+  agent: "Forwards messages between Telegram and the sandboxed OpenClaw agent. Use when setting up a Telegram bot bridge, connecting a chat interface, or configuring Telegram integration."
 keywords: ["nemoclaw telegram bridge", "telegram bot openclaw agent"]
 topics: ["generative_ai", "ai_agents"]
 tags: ["openclaw", "openshell", "telegram", "deployment", "nemoclaw"]