feat(docs): enhance MCP Mesh documentation and navigation (#2112)

- Added new documentation files for API Keys, Authentication, Authorization & Roles, Concepts, Connect Clients, MCP Gateways, MCP Servers, Monitoring, and Overview in both English and Portuguese.
- Updated the introduction and quickstart sections to provide clearer guidance on using the MCP Mesh.
- Improved the navigation order in the sidebar to prioritize MCP Mesh documentation.
- Added a new screenshot for roles and permissions.
- Updated GitHub repository links in the site configuration.

Author: cecilia-marques

apps/docs/client/public/screenshots/roles-permissions.png

@@ -65,9 +65,34 @@ function buildTree(docs: any[]): TreeNode[] {
         // Get parent folder to determine which order to use
         const parentPath = a.path[a.path.length - 2];
 
+        // Custom order for MCP Mesh top-level pages
+        if (parentPath === "mcp-mesh") {
+          // NOTE: doc IDs do not include ".mdx" (e.g. "overview", not "overview.mdx")
+          const mcpMeshOrder = [
+            "overview",
+            "quickstart",
+            "concepts",
+            "connect-clients",
+            "authentication",
+            "authorization-and-roles",
+            "mcp-servers",
+            "mcp-gateways",
+            "api-keys",
+            "monitoring",
+            "api-reference",
+          ];
+          const aIndex = mcpMeshOrder.indexOf(a.name);
+          const bIndex = mcpMeshOrder.indexOf(b.name);
+          if (aIndex !== -1 && bIndex !== -1) {
+            return aIndex - bIndex;
+          }
+          if (aIndex !== -1) return -1;
+          if (bIndex !== -1) return 1;
+        }
+
         // Custom order for no-code-guides files
         if (parentPath === "no-code-guides") {
-          const noCodeOrder = ["creating-tools.mdx", "creating-agents.mdx"];
+          const noCodeOrder = ["creating-tools", "creating-agents"];
           const aIndex = noCodeOrder.indexOf(a.name);
           const bIndex = noCodeOrder.indexOf(b.name);
           if (aIndex !== -1 && bIndex !== -1) {
@@ -80,11 +105,11 @@ function buildTree(docs: any[]): TreeNode[] {
         // Custom order for full-code-guides files
         if (parentPath === "full-code-guides") {
           const fullCodeOrder = [
-            "project-structure.mdx",
-            "building-tools.mdx",
-            "building-views.mdx",
-            "resources.mdx",
-            "deployment.mdx",
+            "project-structure",
+            "building-tools",
+            "building-views",
+            "resources",
+            "deployment",
           ];
           const aIndex = fullCodeOrder.indexOf(a.name);
           const bIndex = fullCodeOrder.indexOf(b.name);
@@ -98,10 +123,7 @@ function buildTree(docs: any[]): TreeNode[] {
         // Custom order for MCP Mesh deploy docs
         const rootPath = a.path[0];
         if (rootPath === "mcp-mesh" && parentPath === "deploy") {
-          const deployOrder = [
-            "local-docker-compose.mdx",
-            "kubernetes-helm-chart.mdx",
-          ];
+          const deployOrder = ["local-docker-compose", "kubernetes-helm-chart"];
           const aIndex = deployOrder.indexOf(a.name);
           const bIndex = deployOrder.indexOf(b.name);
           if (aIndex !== -1 && bIndex !== -1) {
@@ -115,11 +137,11 @@ function buildTree(docs: any[]): TreeNode[] {
       // For folders - custom ordering
       if (a.type === "folder" && b.type === "folder") {
         const folderOrder: Record<string, number> = {
-          "getting-started": 0,
-          "no-code-guides": 1,
-          "full-code-guides": 2,
-          // Keep new platform docs after the legacy guides (as per the original intent)
-          "mcp-mesh": 3,
+          // Put Mesh docs first
+          "mcp-mesh": 0,
+          "getting-started": 1,
+          "no-code-guides": 2,
+          "full-code-guides": 3,
           "mcp-studio": 4,
         };
 
@@ -176,10 +198,15 @@ function groupLegacyAdminSections(nodes: TreeNode[]): TreeNode[] {
         }
       : null;
 
-  // Put MCP Mesh and MCP Studio at the top, then group legacy docs under Legacy Admin.
-  const next: TreeNode[] = [...files];
+  // Make "Introduction" the primary entry point, then product docs.
+  const introduction = files.find((f) => f.name === "introduction");
+  const otherFiles = files.filter((f) => f.name !== "introduction");
+
+  const next: TreeNode[] = [];
+  if (introduction) next.push(introduction);
   if (mcpMesh) next.push(mcpMesh);
   if (mcpStudio) next.push(mcpStudio);
+  next.push(...otherFiles);
   if (legacyFolder) next.push(legacyFolder);
   return next;
 }

apps/docs/client/src/components/ui/Sidebar.astro

@@ -212,11 +212,14 @@ function TreeList({
   const isNodeVisible = (node: FlatNode): boolean => {
     if (node.depth === 0) return true;
 
-    // Find the parent folder
-    const parentPath = node.path.slice(0, -1);
-    const parentId = parentPath.join("/");
+    // A node is visible only if ALL its ancestor folders are expanded.
+    // (This fixes cases where a grandparent folder is collapsed but a child still shows.)
+    for (let i = 1; i < node.path.length; i++) {
+      const ancestorId = node.path.slice(0, i).join("/");
+      if (treeState.get(ancestorId) === false) return false;
+    }
 
-    return treeState.get(parentId) !== false;
+    return true;
   };
 
   // Group nodes to determine when to add separators

apps/docs/client/src/components/ui/Sidebar.tsx

@@ -4,10 +4,10 @@ export const siteConfig = {
   url: "https://your-domain.com",
   ogImage: "https://your-domain.com/og.jpg",
   links: {
-    github: "https://github.com/deco-cx/chat",
+    github: "https://github.com/decocms/mesh",
   },
   // GitHub repository URL for edit links
-  githubRepo: "https://github.com/deco-cx/chat",
+  githubRepo: "https://github.com/decocms/mesh",
   // GitHub branch name (usually 'main' or 'master')
   githubBranch: "main",
 } as const;

apps/docs/client/src/config/site.ts

@@ -12,7 +12,7 @@ import Callout from "../../components/ui/Callout.astro";
 
 **deco CMS** is an open-source **Context Management System** for AI-native operations.
 
-If MCP is the standard interface for tool access, deco CMS is the **production layer around it**: connect MCP servers, enforce governance, and get observability as usage scales across teams and environments. The broader platform also includes a **builder framework** (MCP Studio — coming soon, replacing the legacy admin) and **distribution capabilities** (pre-built modules and store).
+If MCP is the standard interface for tool access, deco CMS is the **production layer around it**: connect MCP servers, enforce governance, and get observability as usage scales across teams and environments. The broader platform also includes a **builder framework** (MCP Studio — coming soon) and **distribution capabilities** (pre-built modules and store).
 
 **Official links:**
 
@@ -22,15 +22,37 @@ If MCP is the standard interface for tool access, deco CMS is the **production l
 
 If you know us from before (as **deco.cx**) and you’re looking for **headless CMS + storefront** capabilities, visit [deco.cx](https://www.decocms.com/use-case/deco-cx). See the deco.cx docs at [docs.deco.cx](https://docs.deco.cx/en/getting-started/overview).
 
-## Quick start (Mesh)
+## Start with the MCP Mesh
 
-### Option A: one-command local Mesh setup
+Choose one:
+
+### Option A: one-command local setup (npx)
 
 ```bash
 npx @decocms/mesh
 ```
 
-### Option B: run from source
+### Option B: local setup with Docker Compose
+
+```bash
+# 1. Configure environment variables
+# Edit .env and configure BETTER_AUTH_SECRET (required)
+# Generate a secret: openssl rand -base64 32
+cp conf-examples/env.example .env
+
+# 2. Configure authentication
+cp conf-examples/auth-config.json.example auth-config.json
+
+# 3. Start the application
+docker compose up -d
+
+# 4. Access
+open http://localhost:3000
+```
+
+**More details:** [Local: Docker Compose](/en/mcp-mesh/deploy/local-docker-compose)
+
+### Option C: run from source
 
 ```bash
 git clone https://github.com/decocms/mesh.git
@@ -39,32 +61,64 @@ bun install
 bun run dev
 ```
 
-## Deploy (Mesh)
+### Option D: deploy to Kubernetes (Helm)
+
+```bash
+# 1. Generate a secure secret for authentication
+SECRET=$(openssl rand -base64 32)
+
+# 2. Install the chart with the generated secret
+helm install deco-mcp-mesh . \
+  --namespace deco-mcp-mesh \
+  --create-namespace \
+  --set secret.BETTER_AUTH_SECRET="$SECRET"
+
+# 3. Wait for pods to be ready
+kubectl wait --for=condition=ready pod \
+  -l app.kubernetes.io/instance=deco-mcp-mesh \
+  -n deco-mcp-mesh \
+  --timeout=300s
+
+# 4. Access via port-forward
+kubectl port-forward svc/deco-mcp-mesh 8080:80 -n deco-mcp-mesh
+```
+
+The application will be available at `http://localhost:8080`.
+
+**More details:** [Kubernetes: Helm Chart](/en/mcp-mesh/deploy/kubernetes-helm-chart)
 
-- **[Local: Docker Compose](/en/mcp-mesh/deploy/local-docker-compose)**
-- **[Kubernetes: Helm Chart](/en/mcp-mesh/deploy/kubernetes-helm-chart)**
+## Learn the Mesh (concepts + product surfaces)
+
+- **[MCP Mesh Overview](/en/mcp-mesh/overview)**
+- **[Quickstart](/en/mcp-mesh/quickstart)**
+- **[Concepts](/en/mcp-mesh/concepts)**
+- **[MCP Servers (Connections)](/en/mcp-mesh/mcp-servers)**
+- **[MCP Gateways](/en/mcp-mesh/mcp-gateways)**
+- **[API Keys](/en/mcp-mesh/api-keys)**
+- **[Monitoring](/en/mcp-mesh/monitoring)**
 
 <Callout type="warning">
   **Docs split (quick guide):**
 
   - **The MCP Mesh** → Self-hosting, deploying, and operating the Mesh (recommended).
   - **Legacy Admin** → If you’re using `admin.decocms.com` (still supported, **deprecated soon**).
 
-  We’re launching **MCP Studio** (on top of Mesh), which will bring the current SaaS admin capabilities to the Mesh (including a hosted option by us) and replace the legacy SaaS over time.
+  We’re launching **MCP Studio** (on top of the Mesh), which will bring the current SaaS admin capabilities to the Mesh (including a hosted option by us) and replace the legacy SaaS over time.
 </Callout>
 
-## Problem (and what the Mesh fixes)
+## Problem: the production gap
+
+AI is easy to demo and hard to **operate**.
 
-When AI moves from demos to production, teams usually hit the same constraints:
+As tool surfaces and teams grow, most orgs run into the same production constraints:
 
-- **Governance gaps**: no single place to enforce SSO/RBAC, approvals, and audit trails
-- **Integration sprawl**: every client wires every tool with its own retries, auth, and config
-- **Operational blind spots**: debugging is slow; failures and costs are hard to trace end-to-end
-- **Context obesity**: bloated prompts and tool lists degrade quality and increase cost
+- **Autonomy breaks**: shipping gets bottlenecked by bespoke integrations, security reviews, and platform tickets
+- **Context fragments**: knowledge lives across many systems and teams rebuild connectors and retrieval repeatedly
+- **Governance is inconsistent**: no single place for SSO/RBAC, audit trails, and operational visibility
 
-The MCP Mesh centralizes those cross-cutting concerns **once** so you don’t rebuild them in every agent/app.
+For more context on our platform-level thesis, read [The architecture of an AI-native company](https://www.decocms.com/blog/post/ai-native-company).
 
-## Platform structure: Mesh → Studio → Distribution
+## Platform structure: Mesh → Studio → Apps & Store
 
 ### The MCP Mesh (foundation)
 An open-source **control plane for MCP traffic**. It sits between your MCP clients (Cursor, Claude, VS Code, custom agents) and your MCP servers, providing a unified layer for auth, policy, and observability.

apps/docs/client/src/content/en/introduction.mdx

@@ -0,0 +1,27 @@
+---
+title: API Keys
+description: Create scoped API keys to access management tools, proxies, and gateways
+icon: KeyRound
+---
+
+import Callout from "../../../components/ui/Callout.astro";
+
+## What are API keys for?
+
+API keys are the simplest way to give an agent/app access to the Mesh without an interactive login flow. Keys are:
+
+- **scoped** (explicit permissions)
+- **revocable**
+- **auditable** (calls show up in Monitoring)
+
+## Best practices
+
+- **Least privilege**: only grant the tool permissions you need.
+- **Separate keys per workload**: one key per app/agent is easier to rotate.
+- **Use gateways for surface control**: combine API-key permissions with a curated gateway.
+
+<Callout type="warning">
+  Treat API keys like production secrets. Store them in a secrets manager and rotate regularly.
+</Callout>
+
+

apps/docs/client/src/content/en/mcp-mesh/api-keys.mdx

@@ -0,0 +1,38 @@
+---
+title: API Reference
+description: The core HTTP endpoints exposed by the Mesh for MCP, gateways, OAuth, and ops
+icon: Code
+---
+
+## MCP endpoints
+
+### Management MCP
+
+- `POST /mcp`
+
+This endpoint exposes **management tools** via MCP (orgs, connections, gateways, API keys, monitoring, event bus).
+
+### Connection proxy
+
+- `POST /mcp/:connectionId`
+
+Proxies MCP requests to a single upstream connection.
+
+### Gateway (virtual server)
+
+- `POST /mcp/gateway/:gatewayId`
+- `POST /mcp/gateway` (default gateway; requires `x-org-id` or `x-org-slug`)
+
+Aggregates tools/resources/prompts across multiple connections.
+
+## OAuth discovery
+
+- `GET /.well-known/oauth-protected-resource`
+- `GET /.well-known/oauth-authorization-server`
+
+## Ops
+
+- `GET /health`
+- `GET /metrics`
+
+

apps/docs/client/src/content/en/mcp-mesh/api-reference.mdx

@@ -0,0 +1,31 @@
+---
+title: Authentication
+description: Supported auth methods and how to configure them for self-hosting
+icon: ShieldCheck
+---
+
+import Callout from "../../../components/ui/Callout.astro";
+
+## What’s supported
+
+The Mesh uses Better Auth and supports:
+
+- **Email/password**
+- **Magic link**
+- **Social providers** (e.g. Google, GitHub)
+- **SAML SSO** (for enterprise orgs)
+
+## Configure auth (self-hosting)
+
+Self-hosted deployments load an `auth-config.json` file at startup (see your deployment guides for mounting details).
+
+<Callout type="warning">
+  Keep provider secrets out of Git. In production, use Secrets management (Kubernetes Secrets, External Secrets Operator, etc.).
+</Callout>
+
+## Key environment variables
+
+- `BETTER_AUTH_SECRET` (required)
+- `BETTER_AUTH_URL` / `BASE_URL` (recommended to set explicitly in production)
+
+