docs(guides): reorganize User Guides nav, fill stubs, trim bloated guides

docs/docs.json

@@ -74,27 +74,62 @@
                 "group": "User Guides",
                 "pages": [
                   "guides/index",
-                  "guides/hardware-advisor",
-                  "guides/npu",
-                  "guides/chat",
-                  "guides/browse",
-                  "guides/analyze",
-                  "guides/talk",
-                  "guides/code",
-                  "guides/telegram-adapter",
-                  "guides/code-index",
-                  "guides/sd",
-                  "guides/emr",
-                  "guides/blender",
-                  "guides/jira",
-                  "guides/email",
-                  "guides/docker",
-                  "guides/routing",
-                  "guides/custom-agent",
-                  "guides/hub-publishing",
-                  "guides/mcp/agent-ui",
-                  "guides/mcp/client",
-                  "guides/mcp/windows-system-health"
+                  {
+                    "group": "Setup & Hardware",
+                    "pages": [
+                      "guides/hardware-advisor",
+                      "guides/npu"
+                    ]
+                  },
+                  {
+                    "group": "Core Agents",
+                    "pages": [
+                      "guides/chat",
+                      "guides/talk",
+                      "guides/browse",
+                      "guides/analyze"
+                    ]
+                  },
+                  {
+                    "group": "Developer Tools",
+                    "pages": [
+                      "guides/code",
+                      "guides/code-index",
+                      "guides/docker"
+                    ]
+                  },
+                  {
+                    "group": "Connected Agents",
+                    "pages": [
+                      "guides/email",
+                      "guides/telegram-adapter",
+                      "guides/jira"
+                    ]
+                  },
+                  {
+                    "group": "Specialized Agents",
+                    "pages": [
+                      "guides/sd",
+                      "guides/blender",
+                      "guides/emr",
+                      "guides/routing"
+                    ]
+                  },
+                  {
+                    "group": "Build & Extend",
+                    "pages": [
+                      "guides/custom-agent",
+                      "guides/hub-publishing"
+                    ]
+                  },
+                  {
+                    "group": "MCP Integration",
+                    "pages": [
+                      "guides/mcp/agent-ui",
+                      "guides/mcp/client",
+                      "guides/mcp/windows-system-health"
+                    ]
+                  }
                 ]
               },
               {

docs/guides/analyze.mdx

@@ -1,13 +1,25 @@
 ---
 title: "Analyst Agent"
 description: "Load structured rows into scratchpad tables and query them with a focused GAIA agent."
+icon: "chart-column"
 ---
 
-# Analyst Agent
+<Info>
+  **First time here?** Complete the [Setup](/setup) guide first to install GAIA and its dependencies.
+</Info>
 
-The Analyst Agent is a focused structured-data agent for users who want scratchpad table tools without the full Chat Agent tool surface. It is useful for CSV-style rows, extracted records, and calculations that should be performed by SQL instead of mental arithmetic.
+The Analyst Agent is a focused structured-data agent for users who want scratchpad table tools without the full Chat Agent tool surface. It's useful for CSV-style rows, extracted records, and calculations that should be performed by SQL instead of mental arithmetic.
 
-## Quick start
+**Who it's for:** anyone who has rows of data and wants the model to compute over them reliably — totals, group-bys, filters — by writing SQL against an in-memory scratchpad table rather than guessing at numbers.
+
+## Prerequisites
+
+- GAIA installed (see [Setup](/setup)).
+- A local model available — run `gaia init` if you haven't set one up. By default the agent uses the local Lemonade backend.
+
+## Quick Start
+
+Run a single analysis task with `-q`:
 
 ```bash
 gaia analyze -q "Create a sales table, insert these rows, and calculate revenue by region"
@@ -19,25 +31,62 @@ Use interactive mode when you want to build up tables and ask follow-up question
 gaia analyze
 ```
 
-## Tool surface
+## Tool Surface
 
 `gaia analyze --list-tools` shows the exact tools available in your installed version. The focused Analyst Agent exposes:
 
-- `create_table` for creating scratchpad tables.
-- `insert_data` for loading structured rows.
-- `query_data` for SQL calculations and filtering.
-- `list_tables` for inspecting available tables.
-- `drop_table` for removing scratchpad tables.
+- `create_table` — create a scratchpad SQL table.
+- `insert_data` — load structured rows.
+- `query_data` — run SQL calculations and filtering.
+- `list_tables` — inspect available tables.
+- `drop_table` — remove a scratchpad table.
 
-The Analyst Agent does not register browser tools. Use `gaia browse` for web research, or `gaia chat` when you need the broader mixed tool set.
+The Analyst Agent does not register browser tools. Use [`gaia browse`](/guides/browse) for web research, or [`gaia chat`](/guides/chat) when you need the broader mixed tool set.
 
-## Local model options
+## Model and Backend Options
 
 By default, `gaia analyze` uses the local Lemonade backend configured for GAIA. You can override the model or backend with the common agent flags:
 
 ```bash
+# Use a smaller local model for lighter tasks
 gaia analyze --model Qwen3-4B-Instruct-2507-GGUF -q "Summarize this table"
+
+# Run against the Claude API instead of local inference
 gaia analyze --use-claude -q "Normalize these rows and calculate totals"
 ```
 
+Other shared agent flags work here too — `--max-steps` to bound the run, `--trace` to save a JSON execution trace, and `--stats` for performance metrics.
+
 In the Agent UI the analyst appears as a single `data` card with a model-size selector — pick **Lite (~4B)** for shorter analysis tasks on lighter hardware, or **Full** for the default model. (The old `data-lite` registry ID still resolves to `data` on the lite tier for existing sessions.)
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Browser Agent" icon="globe" href="/guides/browse">
+    Search the web, fetch pages, and download files.
+  </Card>
+
+  <Card title="Document Q&A" icon="message" href="/guides/chat">
+    The full chat agent with RAG, memory, and the broader tool set.
+  </Card>
+
+  <Card title="CLI Reference" icon="terminal" href="/reference/cli">
+    Every `gaia` command and flag.
+  </Card>
+
+  <Card title="All Guides" icon="book" href="/guides">
+    Browse every GAIA agent.
+  </Card>
+</CardGroup>
+
+---
+
+<small style="color: #666;">
+
+**License**
+
+Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.
+
+SPDX-License-Identifier: MIT
+
+</small>

docs/guides/blender.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Blender Agent"
+description: "Create and modify 3D scenes in Blender through natural-language commands."
 icon: "cube"
 ---
 

docs/guides/browse.mdx

@@ -1,13 +1,26 @@
 ---
 title: "Browser Agent"
 description: "Search the web, fetch pages, and download files with a focused GAIA agent."
+icon: "globe"
 ---
 
-# Browser Agent
+<Info>
+  **First time here?** Complete the [Setup](/setup) guide first to install GAIA and its dependencies.
+</Info>
 
 The Browser Agent is a focused web-research agent for users who want GAIA's browser tools without the full Chat Agent tool surface. It can search the web, fetch readable page text, and download files through the same path validation and web-client limits used by the broader agent stack.
 
-## Quick start
+**Who it's for:** anyone doing quick, repeatable web research from the CLI — gathering links on a topic, pulling the readable text out of a page, or grabbing a file — without loading RAG, scratchpad, or file-editing tools.
+
+## Prerequisites
+
+- GAIA installed (see [Setup](/setup)).
+- A local model available — run `gaia init` if you haven't set one up. By default the agent uses the local Lemonade backend.
+- Network access for web search and page fetches.
+
+## Quick Start
+
+Run a single research task with `-q`:
 
 ```bash
 gaia browse -q "Find recent AMD Ryzen AI SDK docs and summarize the relevant links"
@@ -19,23 +32,60 @@ Use interactive mode when you want to refine a web-research task over multiple t
 gaia browse
 ```
 
-## Tool surface
+## Tool Surface
 
 `gaia browse --list-tools` shows the exact tools available in your installed version. The focused Browser Agent exposes:
 
-- `search_web` for web search.
-- `fetch_page` for extracting readable page text.
-- `download_file` for saving a user-requested URL locally.
+- `search_web` — run a web search for a query.
+- `fetch_page` — fetch a URL and return readable page text.
+- `download_file` — download a user-requested URL to a local file.
 
-The Browser Agent does not register scratchpad or file-system analysis tools. Use `gaia analyze` for structured data work, or `gaia chat` when you need the broader mixed tool set.
+The Browser Agent does not register scratchpad or file-system analysis tools. Use [`gaia analyze`](/guides/analyze) for structured data work, or [`gaia chat`](/guides/chat) when you need the broader mixed tool set.
 
-## Local model options
+## Model and Backend Options
 
 By default, `gaia browse` uses the local Lemonade backend configured for GAIA. You can override the model or backend with the common agent flags:
 
 ```bash
+# Use a smaller local model for lighter tasks
 gaia browse --model Qwen3-4B-Instruct-2507-GGUF -q "Fetch this page and list citations"
+
+# Run against the Claude API instead of local inference
 gaia browse --use-claude -q "Compare these two URLs"
 ```
 
+Other shared agent flags work here too — `--max-steps` to bound the run, `--trace` to save a JSON execution trace, `--stats` for performance metrics, and `--allowed-paths` to control where downloads may be written.
+
 In the Agent UI the browser appears as a single `web` card with a model-size selector — pick **Lite (~4B)** for shorter browser tasks on lighter hardware, or **Full** for the default model. (The old `web-lite` registry ID still resolves to `web` on the lite tier for existing sessions.)
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Analyst Agent" icon="chart-column" href="/guides/analyze">
+    Load structured rows into scratchpad tables and query them with SQL.
+  </Card>
+
+  <Card title="Document Q&A" icon="message" href="/guides/chat">
+    The full chat agent with RAG, memory, and the broader tool set.
+  </Card>
+
+  <Card title="CLI Reference" icon="terminal" href="/reference/cli">
+    Every `gaia` command and flag.
+  </Card>
+
+  <Card title="All Guides" icon="book" href="/guides">
+    Browse every GAIA agent.
+  </Card>
+</CardGroup>
+
+---
+
+<small style="color: #666;">
+
+**License**
+
+Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.
+
+SPDX-License-Identifier: MIT
+
+</small>

docs/guides/docker.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Docker Agent"
+description: "Containerize applications with natural-language commands — no Docker expertise required."
 icon: "docker"
 ---
 

docs/guides/email.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Email Triage"
 description: "Read, organize, and reply to Gmail with all email content processed locally on your machine."
+icon: "envelope"
 ---
 
 # Email Triage Agent