docs: comprehensive documentation restructuring and improvements

AGENTS.md

@@ -2,6 +2,10 @@
 
 This file provides guidance when working with code in this repository, including for Claude Code (claude.ai/code) and other AI coding assistants.
 
+## Documentation Philosophy
+
+**IMPORTANT**: The documentation in `apps/docs/` describes the **intended system design and behavior**, not necessarily the current implementation state. Documentation represents the target architecture and how the system should work, serving as both specification and aspiration. When implementation and documentation differ, the documentation defines the goal, not a bug to be "fixed" in the docs.
+
 ## Overview
 
 MCP Mesh is an open-source control plane for Model Context Protocol (MCP) traffic. It provides a unified layer for authentication, routing, and observability between MCP clients (Cursor, Claude, VS Code) and MCP servers. The system is built as a monorepo using Bun workspaces with TypeScript, Hono (API), and React 19 (UI).

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

@@ -51,34 +51,45 @@ function buildTree(docs: any[]): TreeNode[] {
   // Sort the tree for consistent ordering
   const sortTree = (nodes: TreeNode[]): TreeNode[] => {
     const sorted = nodes.sort((a, b) => {
+      // Special case: api-reference should come after folders
+      if (a.name === "api-reference" && b.type === "folder") {
+        return 1; // api-reference comes after folders
+      }
+      if (b.name === "api-reference" && a.type === "folder") {
+        return -1; // folders come before api-reference
+      }
+
       // First sort by type: files before folders
       if (a.type !== b.type) {
         return a.type === "file" ? -1 : 1;
       }
 
       // For files only - custom ordering
       if (a.type === "file" && b.type === "file") {
-        // Force introduction to be first
-        if (a.name.includes("introduction")) return -1;
-        if (b.name.includes("introduction")) return 1;
-
         // 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
+        // Custom order for decocms top-level pages
         if (parentPath === "mcp-mesh") {
           // NOTE: doc IDs do not include ".mdx" (e.g. "overview", not "overview.mdx")
+          // Order follows: Quickstart → Overview → Core Concepts → Working with MCP → Monitoring → User Management → Reference
           const mcpMeshOrder = [
-            "overview",
+            // Quickstart & Overview
             "quickstart",
+            "overview",
+            // Core Concepts
             "concepts",
-            "connect-clients",
-            "authentication",
-            "authorization-and-roles",
-            "mcp-servers",
-            "mcp-gateways",
-            "api-keys",
+            // Working with MCP
+            "connections",
+            "virtual-mcps",
+            "projects",
+            "agents",
+            // Monitoring & Observability
             "monitoring",
+            // User Management
+            "api-keys",
+            "user-management",
+            // Reference
             "api-reference",
           ];
           const aIndex = mcpMeshOrder.indexOf(a.name);
@@ -90,6 +101,26 @@ function buildTree(docs: any[]): TreeNode[] {
           if (bIndex !== -1) return 1;
         }
 
+        // Custom order for decopilot subfolder
+        if (parentPath === "decopilot") {
+          const decopilotOrder = [
+            "overview",
+            "quickstart",
+            "context",
+            "tasks-and-spawning",
+            "tools",
+            "scopes",
+            "architecture",
+          ];
+          const aIndex = decopilotOrder.indexOf(a.name);
+          const bIndex = decopilotOrder.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", "creating-agents"];
@@ -120,10 +151,54 @@ function buildTree(docs: any[]): TreeNode[] {
           if (bIndex !== -1) return 1;
         }
 
-        // Custom order for MCP Mesh deploy docs
+        // Custom order for self-hosting section
+        if (parentPath === "self-hosting") {
+          const selfHostingOrder = ["quickstart", "authentication"];
+          const aIndex = selfHostingOrder.indexOf(a.name);
+          const bIndex = selfHostingOrder.indexOf(b.name);
+          if (aIndex !== -1 && bIndex !== -1) {
+            return aIndex - bIndex;
+          }
+          if (aIndex !== -1) return -1;
+          if (bIndex !== -1) return 1;
+        }
+
+        // Custom order for api-reference section
+        if (parentPath === "api-reference") {
+          const apiRefOrder = ["built-in-tools"];
+          const aIndex = apiRefOrder.indexOf(a.name);
+          const bIndex = apiRefOrder.indexOf(b.name);
+          if (aIndex !== -1 && bIndex !== -1) {
+            return aIndex - bIndex;
+          }
+          if (aIndex !== -1) return -1;
+          if (bIndex !== -1) return 1;
+        }
+
+        // Custom order for built-in-tools section
+        if (parentPath === "built-in-tools") {
+          const builtInToolsOrder = [
+            "tool-search",
+            "tool-enable",
+            "agent-search",
+            "subtask-run",
+            "user-ask",
+            "resource-read",
+            "prompt-read",
+          ];
+          const aIndex = builtInToolsOrder.indexOf(a.name);
+          const bIndex = builtInToolsOrder.indexOf(b.name);
+          if (aIndex !== -1 && bIndex !== -1) {
+            return aIndex - bIndex;
+          }
+          if (aIndex !== -1) return -1;
+          if (bIndex !== -1) return 1;
+        }
+
+        // Custom order for deploy docs (now under self-hosting)
         const rootPath = a.path[0];
         if (rootPath === "mcp-mesh" && parentPath === "deploy") {
-          const deployOrder = ["local-docker-compose", "kubernetes-helm-chart"];
+          const deployOrder = ["docker-compose", "kubernetes"];
           const aIndex = deployOrder.indexOf(a.name);
           const bIndex = deployOrder.indexOf(b.name);
           if (aIndex !== -1 && bIndex !== -1) {
@@ -137,12 +212,14 @@ function buildTree(docs: any[]): TreeNode[] {
       // For folders - custom ordering
       if (a.type === "folder" && b.type === "folder") {
         const folderOrder: Record<string, number> = {
-          // Put Mesh docs first
-          "mcp-mesh": 0,
-          "getting-started": 1,
-          "no-code-guides": 2,
-          "full-code-guides": 3,
-          "mcp-studio": 4,
+          // Order follows improved information architecture
+          "mcp-mesh": 0, // decocms docs (main product)
+          "getting-started": 1, // Getting Started (after intro)
+          decopilot: 2, // Decopilot (elevated section within mcp-mesh)
+          "self-hosting": 3, // Self-hosting section
+          deploy: 4, // Deploy section (under self-hosting)
+          "no-code-guides": 5, // Legacy admin guides
+          "full-code-guides": 6, // Legacy admin guides
         };
 
         const aOrder = folderOrder[a.name] ?? Number.POSITIVE_INFINITY;
@@ -180,10 +257,7 @@ function groupLegacyAdminSections(nodes: TreeNode[]): TreeNode[] {
   const folders = nodes.filter((n) => n.type === "folder");
 
   const mcpMesh = folders.find((f) => f.name === "mcp-mesh");
-  const mcpStudio = folders.find((f) => f.name === "mcp-studio");
-  const legacyChildren = folders.filter(
-    (f) => f.name !== "mcp-mesh" && f.name !== "mcp-studio",
-  );
+  const legacyChildren = folders.filter((f) => f.name !== "mcp-mesh");
 
   const legacyFolder: TreeNode | null =
     legacyChildren.length > 0
@@ -198,16 +272,21 @@ function groupLegacyAdminSections(nodes: TreeNode[]): TreeNode[] {
         }
       : null;
 
-  // 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");
-
+  // Flatten mcp-mesh folder - bring its children to the top level
+  // mcp-mesh children will be shown at the top level
   const next: TreeNode[] = [];
-  if (introduction) next.push(introduction);
-  if (mcpMesh) next.push(mcpMesh);
-  if (mcpStudio) next.push(mcpStudio);
-  next.push(...otherFiles);
+
+  // Add all mcp-mesh children directly at top level (order controlled by mcpMeshOrder array)
+  if (mcpMesh && mcpMesh.children.length > 0) {
+    next.push(...mcpMesh.children);
+  }
+
+  // Add any other top-level files
+  next.push(...files);
+
+  // Add legacy admin section at the end
   if (legacyFolder) next.push(legacyFolder);
+
   return next;
 }