diff --git a/AGENTS.md b/AGENTS.md
index aa6202ca13..363eb031e9 100644
--- a/AGENTS.md
+++ b/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).
diff --git a/apps/docs/client/src/components/ui/Sidebar.astro b/apps/docs/client/src/components/ui/Sidebar.astro
index b05f95a351..e89bd119d7 100644
--- a/apps/docs/client/src/components/ui/Sidebar.astro
+++ b/apps/docs/client/src/components/ui/Sidebar.astro
@@ -51,6 +51,14 @@ 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;
@@ -58,27 +66,30 @@ function buildTree(docs: any[]): TreeNode[] {
 
       // 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;
 }
 
diff --git a/apps/docs/client/src/components/ui/Sidebar.tsx b/apps/docs/client/src/components/ui/Sidebar.tsx
index 927d0e5b81..7fcbd52d3e 100644
--- a/apps/docs/client/src/components/ui/Sidebar.tsx
+++ b/apps/docs/client/src/components/ui/Sidebar.tsx
@@ -13,7 +13,7 @@ function GitHubStars() {
     const fetchStars = async () => {
       try {
         const response = await fetch(
-          "https://api.github.com/repos/deco-cx/chat",
+          "https://api.github.com/repos/decocms/mesh",
         );
         if (response.ok) {
           const data = await response.json();
@@ -97,99 +97,129 @@ function TreeItem({
 }: TreeItemProps) {
   if (!isVisible) return null;
 
-  // Check if this item is active (current page) - client-side only
+  // Active state: start false (matches server), update after hydration
   const [active, setActive] = useState(false);
 
   useEffect(() => {
     if (node.type !== "file") return;
+    if (typeof window === "undefined") return;
 
-    const currentPath = globalThis.location.pathname;
+    const currentPath = window.location.pathname;
     const docId = node.doc?.id;
     const docPath = docId ? docId.split("/").slice(1).join("/") : null;
     const itemPath = `/${locale}/${docPath ?? node.path.join("/")}`;
 
     setActive(currentPath === itemPath);
-  }, [node.type, node.path, locale, node.doc?.id]);
+  }, [node.type, node.doc?.id, node.path, locale]);
 
   const docId = node.doc?.id;
   const docPath = docId ? docId.split("/").slice(1).join("/") : null;
+
   const href =
     node.type === "file"
       ? `/${locale}/${docPath ?? node.path.join("/")}`
       : null;
 
+  // A node should be collapsible if it has children, regardless of whether it's a file or folder
+  const isCollapsible = node.hasChildren;
+  const isFolder = node.type === "folder";
+
+  // Shared icon rendering logic
+  const renderIcon = () => {
+    if (isFolder || (isCollapsible && !node.doc?.data?.icon)) {
+      return (
+        <Icon
+          name={
+            node.id === "mcp-mesh/self-hosting"
+              ? "Database"
+              : node.id === "mcp-mesh/self-hosting/deploy"
+                ? "Rocket"
+                : node.id === "mcp-mesh/decopilot"
+                  ? "Cpu"
+                  : "Folder"
+          }
+          size={16}
+          className={`shrink-0 ${active ? "text-primary" : ""}`}
+        />
+      );
+    }
+    if (node.doc?.data?.icon) {
+      return (
+        <Icon
+          name={node.doc.data.icon}
+          size={16}
+          className={`shrink-0 ${active ? "text-primary" : ""}`}
+        />
+      );
+    }
+    return (
+      <Icon
+        name="FileText"
+        size={16}
+        className={`shrink-0 ${active ? "text-primary" : ""}`}
+      />
+    );
+  };
+
+  const sharedClasses = `flex items-center gap-3 px-3 py-2 rounded-lg text-sm transition-colors ${
+    active
+      ? "bg-primary/5 text-primary" // Active state
+      : "text-muted-foreground hover:bg-muted hover:text-foreground"
+  }`;
+
   return (
     <li>
-      <div
-        className={`flex items-center gap-3 px-3 py-2 rounded-lg text-sm transition-colors cursor-pointer ${
-          active
-            ? "bg-primary/5 text-primary" // Active state
-            : node.type === "folder"
-              ? "text-muted-foreground hover:bg-muted hover:text-foreground"
-              : "text-muted-foreground hover:bg-muted hover:text-foreground"
-        }`}
-      >
-        {/* Indentation spacer for nested items */}
-        {node.depth > 0 && (
-          <div className="shrink-0" style={{ width: `${node.depth * 24}px` }} />
-        )}
-
-        {/* Icon */}
-        {node.type === "folder" ? (
-          <Icon
-            name={
-              node.id === "mcp-mesh"
-                ? "Network"
-                : node.id === "mcp-studio"
-                  ? "LayoutDashboard"
-                  : node.id === "mcp-mesh/deploy"
-                    ? "Rocket"
-                    : "Folder"
-            }
-            size={16}
-            className={`shrink-0 ${active ? "text-primary" : ""}`}
-          />
-        ) : node.doc?.data?.icon ? (
-          <Icon
-            name={node.doc.data.icon}
-            size={16}
-            className={`shrink-0 ${active ? "text-primary" : ""}`}
-          />
-        ) : (
-          <Icon
-            name="FileText"
-            size={16}
-            className={`shrink-0 ${active ? "text-primary" : ""}`}
-          />
-        )}
-
-        {/* Content */}
-        {node.type === "folder" ? (
+      {isCollapsible ? (
+        <div className={`${sharedClasses} cursor-pointer`}>
+          {/* Indentation spacer for nested items */}
+          {node.depth > 0 && (
+            <div
+              className="shrink-0"
+              style={{ width: `${node.depth * 24}px` }}
+            />
+          )}
+
+          {/* Icon */}
+          {renderIcon()}
+
+          {/* Content */}
           <button
             type="button"
             className="flex items-center justify-between w-full text-left"
             onClick={() => onToggle(node.id)}
           >
             <span className="flex-1">
-              {translations[`sidebar.section.${node.name}`] || node.name}
+              {node.doc?.data?.title ||
+                translations[`sidebar.section.${node.name}`] ||
+                node.name}
             </span>
-            {node.hasChildren && (
-              <Icon
-                name={isExpanded ? "ChevronDown" : "ChevronRight"}
-                size={16}
-                className={`shrink-0 ${active ? "text-primary" : ""}`}
-              />
-            )}
+            <Icon
+              name={isExpanded ? "ChevronDown" : "ChevronRight"}
+              size={16}
+              className={`shrink-0 ${active ? "text-primary" : ""}`}
+            />
           </button>
-        ) : (
-          <a
-            href={href ?? `/${locale}/${node.path.join("/")}`}
-            className="flex-1"
-          >
-            {node.doc?.data?.title || node.name}
-          </a>
-        )}
-      </div>
+        </div>
+      ) : (
+        <a
+          href={href ?? `/${locale}/${node.path.join("/")}`}
+          className={sharedClasses}
+        >
+          {/* Indentation spacer for nested items */}
+          {node.depth > 0 && (
+            <div
+              className="shrink-0"
+              style={{ width: `${node.depth * 24}px` }}
+            />
+          )}
+
+          {/* Icon */}
+          {renderIcon()}
+
+          {/* Content */}
+          <span className="flex-1">{node.doc?.data?.title || node.name}</span>
+        </a>
+      )}
     </li>
   );
 }
@@ -222,12 +252,6 @@ function TreeList({
     return true;
   };
 
-  // Group nodes to determine when to add separators
-  const getNodeGroup = (node: FlatNode): "root-files" | "root-folders" => {
-    if (node.depth === 0 && node.type === "file") return "root-files";
-    return "root-folders";
-  };
-
   return (
     <ul className="space-y-0.5">
       {tree.map((node, index) => {
@@ -235,16 +259,24 @@ function TreeList({
         const isExpanded = treeState.get(node.id) !== false;
         const prevNode = tree[index - 1];
 
-        // Add separator when switching between different groups at root level
+        // Add separator logic:
+        // 1. After "overview" file (before concepts and other content)
+        // 2. Before "Legacy Admin" section
         let needsSeparator = false;
-        if (prevNode && node.depth === 0 && prevNode.depth === 0) {
-          const currentGroup = getNodeGroup(node);
-          const prevGroup = getNodeGroup(prevNode);
-          needsSeparator = currentGroup !== prevGroup;
+
+        // Check if previous node is "overview" file at root level
+        if (
+          prevNode &&
+          prevNode.depth === 0 &&
+          prevNode.type === "file" &&
+          prevNode.name === "overview" &&
+          node.depth === 0
+        ) {
+          needsSeparator = true;
         }
 
-        // Also add separator when going from nested items back to root level
-        if (prevNode && node.depth === 0 && prevNode.depth > 0) {
+        // Add separator before Legacy Admin section
+        if (node.depth === 0 && node.id === "admin-decocms-com") {
           needsSeparator = true;
         }
 
@@ -271,49 +303,71 @@ function TreeList({
 }
 
 export default function Sidebar({ tree, locale, translations }: SidebarProps) {
-  const [treeState, setTreeState] = useState<Map<string, boolean>>(new Map());
-
-  useEffect(() => {
-    // Load saved state from localStorage
-    const savedState = JSON.parse(
-      localStorage.getItem("sidebar-tree-state") || "{}",
-    );
+  // Initialize with default state (same on server and client for hydration match)
+  const [treeState, setTreeState] = useState<Map<string, boolean>>(() => {
     const initialState = new Map();
 
-    // If the current page is inside a folder, ensure its ancestor folders are expanded
-    // so the active item is visible (even if the default is collapsed).
-    const currentPath = globalThis.location.pathname;
-    const relativePath = currentPath.replace(`/${locale}/`, "");
-    const parts = relativePath.split("/").filter(Boolean);
-    const expandedAncestors = new Set<string>();
-    for (let i = 1; i <= parts.length - 1; i++) {
-      expandedAncestors.add(parts.slice(0, i).join("/"));
-    }
+    // Default: most sections expanded, some collapsed
+    const collapsedByDefault = new Set<string>([
+      "admin-decocms-com/getting-started",
+      "admin-decocms-com/no-code-guides",
+      "admin-decocms-com/full-code-guides",
+    ]);
 
-    // Initialize tree state - default to expanded (with a few collapsed-by-default sections)
     tree.forEach((node) => {
-      if (node.type === "folder") {
-        const saved = savedState[node.id];
-        // Default: show "Legacy Admin" open, but keep its sections closed (as a compact TOC).
+      if (node.hasChildren) {
+        initialState.set(node.id, !collapsedByDefault.has(node.id));
+      }
+    });
+
+    return initialState;
+  });
+
+  // After hydration, apply localStorage state and expand ancestors of current page
+  useEffect(() => {
+    try {
+      if (typeof window !== "undefined" && window.localStorage) {
+        const savedState = JSON.parse(
+          window.localStorage.getItem("sidebar-tree-state") || "{}",
+        );
+
+        // Get current path to expand ancestors
+        const currentPath = window.location.pathname;
+        const relativePath = currentPath.replace(`/${locale}/`, "");
+        const parts = relativePath.split("/").filter(Boolean);
+        const expandedAncestors = new Set<string>();
+        for (let i = 1; i <= parts.length - 1; i++) {
+          expandedAncestors.add(parts.slice(0, i).join("/"));
+        }
+
+        // Build new state with saved values and expanded ancestors
+        const newState = new Map();
         const collapsedByDefault = new Set<string>([
           "admin-decocms-com/getting-started",
           "admin-decocms-com/no-code-guides",
           "admin-decocms-com/full-code-guides",
         ]);
-        const defaultExpanded = collapsedByDefault.has(node.id) ? false : true;
 
-        const shouldExpand =
-          typeof saved === "boolean" ? saved : defaultExpanded;
-
-        initialState.set(
-          node.id,
-          expandedAncestors.has(node.id) ? true : shouldExpand,
-        );
+        tree.forEach((node) => {
+          if (node.hasChildren) {
+            const saved = savedState[node.id];
+            const defaultExpanded = !collapsedByDefault.has(node.id);
+            const shouldExpand =
+              typeof saved === "boolean" ? saved : defaultExpanded;
+
+            newState.set(
+              node.id,
+              expandedAncestors.has(node.id) ? true : shouldExpand,
+            );
+          }
+        });
+
+        setTreeState(newState);
       }
-    });
-
-    setTreeState(initialState);
-  }, [tree]);
+    } catch (error) {
+      console.error("Failed to load sidebar state:", error);
+    }
+  }, [tree, locale]);
 
   const updateFolderVisibility = (folderId: string, isExpanded: boolean) => {
     setTreeState((prev) => {
@@ -322,13 +376,23 @@ export default function Sidebar({ tree, locale, translations }: SidebarProps) {
       return newState;
     });
 
-    // Save state to localStorage
-    const stateToSave: Record<string, boolean> = {};
-    treeState.forEach((value, key) => {
-      stateToSave[key] = value;
-    });
-    stateToSave[folderId] = isExpanded;
-    localStorage.setItem("sidebar-tree-state", JSON.stringify(stateToSave));
+    // Save state to localStorage (client-side only)
+    try {
+      if (typeof window !== "undefined" && window.localStorage) {
+        const stateToSave: Record<string, boolean> = {};
+        treeState.forEach((value, key) => {
+          stateToSave[key] = value;
+        });
+        stateToSave[folderId] = isExpanded;
+        window.localStorage.setItem(
+          "sidebar-tree-state",
+          JSON.stringify(stateToSave),
+        );
+      }
+    } catch (error) {
+      // Ignore localStorage errors
+      console.error("Failed to save sidebar state to localStorage:", error);
+    }
   };
 
   const handleFolderToggle = (folderId: string) => {
diff --git a/apps/docs/client/src/content/en/full-code-guides/building-tools.mdx b/apps/docs/client/src/content/en/full-code-guides/building-tools.mdx
index baf8253b43..5899b77d1d 100644
--- a/apps/docs/client/src/content/en/full-code-guides/building-tools.mdx
+++ b/apps/docs/client/src/content/en/full-code-guides/building-tools.mdx
@@ -28,31 +28,38 @@ Every tool requires four components:
 import { createTool } from "@deco/workers-runtime";
 import { z } from "zod";
 
-const createEmailTool = (env: Env) =>
+const createOrderConfirmationTool = (env: Env) =>
   createTool({
-    id: "EMAIL_SEND",
-    description: "Send an email via Gmail. Use for notifications and communications.",
+    id: "ORDER_CONFIRMATION_SEND",
+    description: "Send order confirmation email to customer. Use after successful order placement.",
     inputSchema: z.object({
-      to: z.string().email(),
-      subject: z.string(),
-      body: z.string(),
+      customerEmail: z.string().email(),
+      orderNumber: z.string(),
+      orderTotal: z.number().positive(),
+      items: z.array(z.object({
+        name: z.string(),
+        quantity: z.number(),
+        price: z.number(),
+      })),
     }),
-    outputSchema: z.object({ 
+    outputSchema: z.object({
       success: z.boolean(),
       messageId: z.string().optional(),
+      sentAt: z.string(),
     }),
     execute: async ({ context }) => {
-      const response = await env["gmail"].SEND_EMAIL({
-        to: context.to,
-        subject: context.subject,
-        body: context.body,
+      const response = await env["sendgrid"].SEND_EMAIL({
+        to: context.customerEmail,
+        subject: `Order Confirmation - #${context.orderNumber}`,
+        body: `Thank you for your order! Total: $${context.orderTotal}`,
       });
-      return { 
+      return {
         success: true,
         messageId: response.id,
+        sentAt: new Date().toISOString(),
       };
     },
-  }); 
+  });
 ```
 
 **Key points:**
@@ -65,32 +72,44 @@ const createEmailTool = (env: Env) =>
 ### External API Calls
 
 ```typescript
-const createWeatherTool = (env: Env) =>
+const createInventoryCheckTool = (env: Env) =>
   createTool({
-    id: "WEATHER_FETCH",
-    description: "Get current weather for a city using OpenWeather API",
+    id: "PRODUCT_INVENTORY_CHECK",
+    description: "Check product inventory levels across warehouses using inventory API",
     inputSchema: z.object({
-      city: z.string().min(1),
+      sku: z.string().min(1),
+      warehouseIds: z.array(z.string()).optional(),
     }),
     outputSchema: z.object({
-      temperature: z.number(),
-      condition: z.string(),
-      humidity: z.number().optional(),
+      sku: z.string(),
+      totalQuantity: z.number(),
+      locations: z.array(z.object({
+        warehouseId: z.string(),
+        quantity: z.number(),
+        reserved: z.number(),
+      })),
+      lowStock: z.boolean(),
     }),
     execute: async ({ context }) => {
       const response = await fetch(
-        `https://api.openweathermap.org/data/2.5/weather?q=${context.city}&appid=${env.OPENWEATHER_API_KEY}`
+        `https://api.inventory-system.com/v1/products/${context.sku}/stock`,
+        {
+          headers: { "Authorization": `Bearer ${env.INVENTORY_API_KEY}` }
+        }
       );
-      
+
       if (!response.ok) {
-        throw new Error(`Weather API error: ${response.statusText}`);
+        throw new Error(`Inventory API error: ${response.statusText}`);
       }
-      
+
       const data = await response.json();
+      const totalQuantity = data.locations.reduce((sum, loc) => sum + loc.quantity, 0);
+
       return {
-        temperature: data.main.temp,
-        condition: data.weather[0].description,
-        humidity: data.main.humidity,
+        sku: context.sku,
+        totalQuantity,
+        locations: data.locations,
+        lowStock: totalQuantity < 10,
       };
     },
   });
@@ -101,32 +120,41 @@ const createWeatherTool = (env: Env) =>
 Call installed integrations through the environment:
 
 ```typescript
-const createNotificationTool = (env: Env) =>
+const createOrderNotificationTool = (env: Env) =>
   createTool({
-    id: "SLACK_NOTIFY",
-    description: "Send a notification to a Slack channel",
+    id: "ORDER_NOTIFICATION_SEND",
+    description: "Send order status notification to fulfillment team via Slack",
     inputSchema: z.object({
-      channel: z.string(),
-      message: z.string(),
+      orderNumber: z.string(),
+      status: z.enum(["pending", "processing", "shipped", "delivered"]),
+      customerName: z.string(),
+      totalAmount: z.number(),
     }),
-    outputSchema: z.object({ 
+    outputSchema: z.object({
       sent: z.boolean(),
       timestamp: z.string(),
+      channel: z.string(),
     }),
     execute: async ({ context }) => {
+      const message = `🛒 Order #${context.orderNumber} - ${context.status.toUpperCase()}\n` +
+                     `Customer: ${context.customerName}\n` +
+                     `Amount: $${context.totalAmount}`;
+
       const result = await env["slack"].POST_MESSAGE({
-        channel: context.channel,
-        text: context.message,
+        channel: "#order-fulfillment",
+        text: message,
       });
+
       return {
         sent: true,
         timestamp: result.ts,
+        channel: "#order-fulfillment",
       };
     },
   });
 ```
 
-Install integrations from **Apps** in your workspace. Each integration's tools are available at `env["integration-id"]` where the ID is shown in the Apps section (e.g., `env["gmail"]`, `env["slack"]`).
+Install integrations from **Apps** in your workspace. Each integration's tools are available at `env["integration-id"]` where the ID is shown in the Apps section (e.g., `env["shopify"]`, `env["slack"]`, `env["stripe"]`).
 
 ### Database Operations
 
@@ -139,15 +167,23 @@ import { customers } from "./schema";
 const createCustomerTool = (env: Env) =>
   createTool({
     id: "CUSTOMER_CREATE",
-    description: "Create a new customer in the database",
+    description: "Create a new customer in the ecommerce database with loyalty tier",
     inputSchema: z.object({
       name: z.string().min(1),
       email: z.string().email(),
-      city: z.string(),
-      state: z.string().length(2),
+      phone: z.string().optional(),
+      shippingAddress: z.object({
+        street: z.string(),
+        city: z.string(),
+        state: z.string().length(2),
+        zipCode: z.string(),
+      }),
+      loyaltyTier: z.enum(["bronze", "silver", "gold", "platinum"]).default("bronze"),
     }),
-    outputSchema: z.object({ 
+    outputSchema: z.object({
       id: z.number(),
+      email: z.string(),
+      loyaltyTier: z.string(),
       createdAt: z.date(),
     }),
     execute: async ({ context }) => {
@@ -157,13 +193,16 @@ const createCustomerTool = (env: Env) =>
         .values({
           name: context.name,
           email: context.email,
-          city: context.city,
-          state: context.state,
+          phone: context.phone,
+          shippingAddress: JSON.stringify(context.shippingAddress),
+          loyaltyTier: context.loyaltyTier,
         })
         .returning();
 
-      return { 
+      return {
         id: result.id,
+        email: result.email,
+        loyaltyTier: result.loyaltyTier,
         createdAt: result.createdAt,
       };
     },
@@ -178,13 +217,17 @@ Add tools to `server/main.ts`:
 
 ```typescript
 import { withRuntime } from "@deco/workers-runtime";
-import { createEmailTool } from "./tools/email";
+import { createOrderConfirmationTool } from "./tools/notifications";
+import { createInventoryCheckTool } from "./tools/inventory";
 import { createCustomerTool } from "./tools/customers";
+import { createOrderNotificationTool } from "./tools/fulfillment";
 
 const { Workflow, ...runtime } = withRuntime<Env>({
   tools: [
-    createEmailTool,
+    createOrderConfirmationTool,
+    createInventoryCheckTool,
     createCustomerTool,
+    createOrderNotificationTool,
     // Add more tools here
   ],
   workflows: [],
@@ -212,10 +255,13 @@ Start your dev server and test in two ways:
 // In your React component
 import { client } from "./lib/rpc";
 
-const result = await client.tools.EMAIL_SEND({
-  to: "user@example.com",
-  subject: "Test",
-  body: "Hello!",
+const result = await client.tools.ORDER_CONFIRMATION_SEND({
+  customerEmail: "customer@example.com",
+  orderNumber: "ORD-12345",
+  orderTotal: 299.99,
+  items: [
+    { name: "Wireless Headphones", quantity: 1, price: 299.99 }
+  ],
 });
 ```
 
@@ -225,14 +271,14 @@ Tools are immediately available via typed RPC, no API layer needed.
 
 **Single Responsibility**
 ```
-✅ EMAIL_SEND, CUSTOMER_CREATE, INVOICE_GENERATE
-❌ CUSTOMER_CREATE_AND_EMAIL_AND_NOTIFY
+✅ ORDER_CONFIRMATION_SEND, CUSTOMER_CREATE, PRODUCT_INVENTORY_CHECK
+❌ CUSTOMER_CREATE_AND_EMAIL_AND_SYNC_INVENTORY
 ```
 
 **Descriptive Names** - Follow `RESOURCE_ACTION` pattern:
 ```
-✅ ORDER_TOTAL_CALCULATE, LEAD_QUALIFY
-❌ calculateTotal, qualify_lead
+✅ ORDER_TOTAL_CALCULATE, PRODUCT_PRICE_UPDATE, CART_ABANDONED_SEND
+❌ calculateTotal, updatePrice, sendCart
 ```
 
 **Strong Typing** - Zod schemas provide runtime validation and compile-time types:
@@ -263,14 +309,18 @@ Group related tools in files:
 ```
 server/tools/
 ├── index.ts          # Export all tools
-├── customers.ts      # CUSTOMER_CREATE, CUSTOMER_FETCH, etc.
-├── emails.ts         # EMAIL_SEND, EMAIL_VALIDATE
-└── billing.ts        # INVOICE_CREATE, PAYMENT_PROCESS
+├── customers.ts      # CUSTOMER_CREATE, CUSTOMER_FETCH, CUSTOMER_UPDATE
+├── orders.ts         # ORDER_CREATE, ORDER_UPDATE, ORDER_CANCEL
+├── inventory.ts      # PRODUCT_INVENTORY_CHECK, INVENTORY_UPDATE
+├── notifications.ts  # ORDER_CONFIRMATION_SEND, SHIPPING_NOTIFICATION_SEND
+└── payments.ts       # PAYMENT_PROCESS, REFUND_CREATE, TRANSACTION_VERIFY
 ```
 
 Export from `index.ts`:
 ```typescript
 export { createCustomerTool, createCustomerFetchTool } from "./customers";
-export { createEmailTool } from "./emails";
-export { createInvoiceTool } from "./billing";
+export { createOrderTool, createOrderUpdateTool } from "./orders";
+export { createInventoryCheckTool } from "./inventory";
+export { createOrderConfirmationTool } from "./notifications";
+export { createPaymentTool } from "./payments";
 ```
\ No newline at end of file
diff --git a/apps/docs/client/src/content/en/full-code-guides/building-views.mdx b/apps/docs/client/src/content/en/full-code-guides/building-views.mdx
index aee2bb6fc2..ffb5f6d4f5 100644
--- a/apps/docs/client/src/content/en/full-code-guides/building-views.mdx
+++ b/apps/docs/client/src/content/en/full-code-guides/building-views.mdx
@@ -269,6 +269,21 @@ const { data, isLoading } = useQuery({
   queryKey: ["customers"],
   queryFn: () => client.tools.CUSTOMERS_LIST(),
 });
+
+// Display customer list with loyalty tier and total orders
+if (isLoading) return <div>Loading customers...</div>;
+
+return (
+  <div>
+    {data?.customers.map(customer => (
+      <div key={customer.id}>
+        <h3>{customer.name}</h3>
+        <p>Loyalty: {customer.loyaltyTier}</p>
+        <p>Total Orders: {customer.totalOrders}</p>
+      </div>
+    ))}
+  </div>
+);
 ```
 
 <Callout type="info">
diff --git a/apps/docs/client/src/content/en/full-code-guides/deployment.mdx b/apps/docs/client/src/content/en/full-code-guides/deployment.mdx
index 785c1785d8..ef626a4d49 100644
--- a/apps/docs/client/src/content/en/full-code-guides/deployment.mdx
+++ b/apps/docs/client/src/content/en/full-code-guides/deployment.mdx
@@ -103,7 +103,7 @@ Test production immediately after deploy:
 
 1. Open `https://<app-name>.deco.page`
 2. Verify frontend loads correctly
-3. Test tool calls through UI
+3. Test tool invocations through UI
 4. Check integrations work (production may use different credentials than dev)
 5. Test as an end user would interact with the app
 6. Review Cloudflare Worker logs if issues occur
diff --git a/apps/docs/client/src/content/en/introduction.mdx b/apps/docs/client/src/content/en/introduction.mdx
deleted file mode 100644
index bca92a27ee..0000000000
--- a/apps/docs/client/src/content/en/introduction.mdx
+++ /dev/null
@@ -1,156 +0,0 @@
----
-title: Introduction
-description: Developer docs for the MCP Mesh and the deco CMS platform
-icon: Rocket
----
-
-import Callout from "../../components/ui/Callout.astro";
-
-![deco](https://assets.decocache.com/mcp/9a3facd8-1199-4635-becc-bdc3f5ee7ab1/deco-banner-capy.png)
-
-## What is deco CMS?
-
-**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) and **distribution capabilities** (pre-built modules and store).
-
-**Official links:**
-
-- **deco CMS**: [decocms.com](https://www.decocms.com/)
-- **The MCP Mesh**: [decocms.com/mesh](https://www.decocms.com/mesh)
-- **MCP Studio**: [decocms.com/mcp-studio](https://www.decocms.com/mcp-studio)
-
-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).
-
-## Start with the MCP Mesh
-
-Choose one:
-
-### Option A: one-command local setup (npx)
-
-```bash
-npx @decocms/mesh
-```
-
-### 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
-cd mesh
-bun install
-bun run dev
-```
-
-### 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)
-
-## 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 Agents](/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 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: the production gap
-
-AI is easy to demo and hard to **operate**.
-
-As tool surfaces and teams grow, most orgs run into the same production constraints:
-
-- **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
-
-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 → 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.
-
-### MCP Studio (development)
-A no-code admin + SDK to package MCP capabilities as reusable building blocks.
-
-<Callout type="info">
-  **Coming soon:** This is the successor to the current SaaS admin, built on top of the MCP Mesh.
-</Callout>
-
-### MCP Apps & Store (distribution)
-A path to distribute reusable MCP-native capabilities across teams (and eventually a store).
-
-<Callout type="info">
-  **Coming soon.**
-</Callout>
-
-## Why MCP?
-
-We’re built on MCP because enterprises need interoperability at the tool layer — and a way to operate that tool access with the rigor of any production surface.
-
-MCP gives you a standard interface. deco CMS provides the **control plane** around it:
-
-- **Portable**: self-host on Docker/Kubernetes; cloud hosted option coming soon
-- **Composable**: swap models, swap MCP servers, adopt community tools, build your own
-- **Auditable**: centralized policies, logs, and traces across tool + model calls
-- **No lock-in**: your context, your infrastructure
-
-## Legacy Admin quick start (admin.decocms.com)
-
-If you’re using the current SaaS admin at `admin.decocms.com` (still supported, deprecated soon), start here:
-
-- **[For AI Builders](/en/getting-started/ai-builders)**
-- **[For Developers](/en/getting-started/developers)**
diff --git a/apps/docs/client/src/content/en/mcp-mesh/agents.mdx b/apps/docs/client/src/content/en/mcp-mesh/agents.mdx
new file mode 100644
index 0000000000..b7198e9f0a
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/agents.mdx
@@ -0,0 +1,101 @@
+---
+title: Agents
+description: Single-purpose virtual MCPs designed for specific tasks
+icon: Bot
+---
+
+import Callout from "../../../components/ui/Callout.astro";
+
+<Callout type="info">
+  This page documents the **planned architecture** for agents in deco CMS. The implementation is in development.
+</Callout>
+
+## What Are Agents?
+
+**Agents** are single-purpose virtual MCPs optimized for specific tasks. While [Projects](/en/mcp-mesh/projects) provide general-purpose work environments, agents focus narrowly on accomplishing one thing well.
+
+Agents provide:
+
+- **Focused capabilities** - Curated tools for specific tasks
+- **Task-specific context** - Resources and guidelines tailored to the agent's purpose
+- **Single-purpose design** - Clear objective with no unnecessary complexity
+
+Agents are organization-wide configurations available in the sidebar under the **Agents** section. Each agent can be spawned in any scope (tasks, subtasks, projects) with fresh execution context, providing a focused workspace for its specific task.
+
+The key distinction: projects organize capabilities for broad work contexts, while agents optimize for single-purpose execution.
+
+## How Agents Work
+
+Agents follow the same pattern as standard agent skills (`SKILL.md` files), making them familiar and easy to understand:
+
+**Like SKILL.md skills:**
+- **Description** - Brief explanation of what the agent does and when to use it (like the `description:` field in `SKILL.md`)
+- **Instructions** - Detailed guidelines for how the agent operates (like the body of a `SKILL.md` file)
+
+**Plus Virtual MCP capabilities:**
+- **Name** - Identifies the agent (e.g., "Deployment Agent", "Research Agent")
+- **Tools** - Actions the agent can take (select from [connections](/en/mcp-mesh/connections) or define inline)
+- **Resources** - Additional context and documentation
+- **Prompts** - Workflow templates
+
+[decopilot](/en/mcp-mesh/decopilot/overview) uses the **description** field to understand when to spawn each agent—just like it uses skill descriptions to know when to invoke skills. This makes agents discoverable and automatically available when relevant to the task at hand.
+
+Since agents are [Virtual MCPs](/en/mcp-mesh/virtual-mcps), you can compose them from existing connections, define capabilities inline, or mix both approaches.
+
+## Example: Order Fulfillment Agent
+
+An order fulfillment agent might aggregate Shopify tools for order management, ShipStation tools for shipping label generation, and Slack tools for fulfillment team notifications. The agent handles order fulfillment with a focused toolset—fetch pending orders, check inventory, generate shipping labels, send tracking notifications—all within its single-purpose scope.
+
+## Built-in Agents
+
+deco CMS includes built-in agents for common mesh operations. These agents use the **Management MCP**—a self-referential MCP that exposes mesh management capabilities through the MCP protocol.
+
+Built-in agents available out-of-the-box:
+
+- **Agent Management** - Create, edit, and delete agents
+- **Connection Management** - Manage MCP server connections
+- **Permission Management** - Control access and authorization
+- **MCP Store** - Browse and install MCPs from the store
+- **User Management** - Invite and manage organization members
+
+These agents operate at organization level and leverage Management MCP tools for platform configuration.
+
+## Agent Design Principles
+
+**Single-purpose focus**: Each agent should do one thing well. Narrow scope improves clarity, reliability, and maintainability.
+
+**Clear description**: Write descriptions that help decopilot understand when to spawn the agent. Use `[Verb] + [Object] + [Context]` pattern:
+- "Fulfill customer orders and generate shipping labels"
+- "Analyze sales data for inventory optimization"
+- "Process customer refunds and returns"
+
+**Detailed instructions**: Provide clear guidelines in the instructions field—just like you would in a `SKILL.md` file. Include constraints, workflow steps, and behavioral guidelines.
+
+**Tool selection**: Choose tools that align with the agent's description. A customer service agent needs order lookup and refund tools; an inventory agent needs stock checking and alert tools. Overly broad tool access dilutes focus.
+
+**Good**: "Order Fulfillment Agent" (processes and ships orders)
+**Too broad**: "Ecommerce Operations Agent" (fulfillment, customer service, inventory, marketing, analytics...)
+
+## Using Agents
+
+Agents can be used in several ways:
+
+- **Spawned by decopilot** - Agents created on-demand with fresh context for specific tasks
+- **Built-in agents** - Pre-configured agents for mesh operations, ready immediately
+- **Custom agents** - Domain-specific agents for your team's unique workflows
+
+When working with an agent, you'll only see the tools, resources, and prompts configured for that agent's specific purpose. This focused view helps you stay on task without distraction.
+
+## Benefits Summary
+
+Agents provide focused capabilities with clear advantages:
+
+- **Focused capabilities** - Single-purpose design ensures clarity and reliability
+- **Fresh context** - Spawned agents start with clean context for their task
+- **Reusable patterns** - Define once, use across projects and workflows
+- **Built-in operations** - Pre-configured agents for common mesh tasks
+- **Self-referential management** - Management MCP enables agents to manage mesh itself
+
+---
+
+**Next steps**: Learn about [Virtual MCPs](/en/mcp-mesh/virtual-mcps) to understand the foundation, or explore [decopilot](/en/mcp-mesh/decopilot/overview) to see how agents are spawned dynamically.
diff --git a/apps/docs/client/src/content/en/mcp-mesh/api-keys.mdx b/apps/docs/client/src/content/en/mcp-mesh/api-keys.mdx
index d02c5ac46d..ff4e85490c 100644
--- a/apps/docs/client/src/content/en/mcp-mesh/api-keys.mdx
+++ b/apps/docs/client/src/content/en/mcp-mesh/api-keys.mdx
@@ -6,22 +6,74 @@ icon: KeyRound
 
 import Callout from "../../../components/ui/Callout.astro";
 
-## What are API keys for?
+## What are API Keys?
 
-API keys are the simplest way to give an agent/app access to the Mesh without an interactive login flow. Keys are:
+API keys let external systems connect to deco CMS without needing a user to log in. They're simple tokens you can use in scripts, automation tools, or any system that needs to access deco CMS programmatically.
 
-- **scoped** (explicit permissions)
-- **revocable**
-- **auditable** (calls show up in Monitoring)
+<Callout type="warning">
+  API keys are for **external systems connecting to deco CMS**. To connect deco CMS to upstream MCP servers, see [Connections](/en/mcp-mesh/connections).
+</Callout>
+
+## When to Use API Keys vs OAuth
+
+**OAuth** (Recommended for most users)
+- Use with Cursor, Claude Desktop, VS Code
+- Login with your browser
+- Easiest setup
+
+**API Keys**
+- Use for scripts and automation
+- No browser login needed
+- Better for servers and CI/CD
+
+## Creating an API Key
+
+1. Open the **deco CMS Dashboard**
+2. Go to **Settings** → **API Keys**
+3. Click **Create API Key**
+4. Give it a name (like "My Automation Script")
+5. Assign [roles and permissions](/en/mcp-mesh/user-management)
+6. **Copy the key immediately**
+
+<Callout type="error">
+  You can only see the API key once. Copy it now and store it somewhere safe like a password manager.
+</Callout>
 
-## Best practices
+## Using Your API Key
 
-- **Least privilege**: only grant the tool permissions you need.
-- **Separate keys per workload**: one key per app/agent is easier to rotate.
-- **Use agents for surface control**: combine API-key permissions with a curated agent.
+Add the API key to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "deco CMS": {
+      "url": "https://mesh.deco CMS.com/mcp/agent/your-agent-id",
+      "transport": "http",
+      "headers": {
+        "Authorization": "Bearer mcp_key_abc123..."
+      }
+    }
+  }
+}
+```
+
+## Security Best Practices
 
 <Callout type="warning">
-  Treat API keys like production secrets. Store them in a secrets manager and rotate regularly.
+  Treat API keys like passwords. Never share them or commit them to code repositories.
 </Callout>
 
+**Give minimum permissions**: Only grant what's actually needed.
+
+**Create separate keys**: Use one key per tool or script—easier to manage if something goes wrong.
+
+**Store securely**: Keep keys in a password manager or secrets manager, never in plain text files.
+
+**Rotate regularly**: Create new keys every few months and delete old ones.
+
+**Monitor usage**: Check the dashboard regularly for unusual activity.
+
+<Callout type="tip">
+  Combine API keys with [Agents](/en/mcp-mesh/agents) to control exactly which tools your scripts can access.
+</Callout>
 
diff --git a/apps/docs/client/src/content/en/mcp-mesh/api-reference.mdx b/apps/docs/client/src/content/en/mcp-mesh/api-reference.mdx
deleted file mode 100644
index b2f4a49833..0000000000
--- a/apps/docs/client/src/content/en/mcp-mesh/api-reference.mdx
+++ /dev/null
@@ -1,38 +0,0 @@
----
-title: API Reference
-description: The core HTTP endpoints exposed by the Mesh for MCP, agents, OAuth, and ops
-icon: Code
----
-
-## MCP endpoints
-
-### Management MCP
-
-- `POST /mcp`
-
-This endpoint exposes **management tools** via MCP (orgs, connections, agents, API keys, monitoring, event bus).
-
-### Connection proxy
-
-- `POST /mcp/:connectionId`
-
-Proxies MCP requests to a single upstream connection.
-
-### Agent (virtual server)
-
-- `POST /mcp/gateway/:gatewayId`
-- `POST /mcp/gateway` (default Agent; 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`
-
-
diff --git a/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools.mdx b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools.mdx
new file mode 100644
index 0000000000..aee457c13d
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools.mdx
@@ -0,0 +1,61 @@
+---
+title: Built-in Tools
+description: Core tools provided by decopilot for discovering capabilities and managing work
+icon: Wrench
+---
+
+import Callout from "../../../../components/ui/Callout.astro";
+
+## Overview
+
+Decopilot provides built-in tools that are always available (subject to task/subtask restrictions). These tools enable capability discovery, work management, and context access.
+
+## Tool Categories
+
+### Discovery & Enablement
+
+Tools for discovering and activating capabilities:
+
+- [**tool_search**](/en/mcp-mesh/api-reference/built-in-tools/tool-search) - Search for tools in current scope
+- [**tool_enable**](/en/mcp-mesh/api-reference/built-in-tools/tool-enable) - Activate a tool for use in current task
+
+### Agent Management
+
+Tools for working with agents:
+
+- [**agent_search**](/en/mcp-mesh/api-reference/built-in-tools/agent-search) - Find agents configured in the organization
+
+### Task Management
+
+Tools for spawning and managing work:
+
+- [**subtask_run**](/en/mcp-mesh/api-reference/built-in-tools/subtask-run) - Spawn subtask with isolated context
+
+### User Interaction
+
+Tools for gathering user input:
+
+- [**user_ask**](/en/mcp-mesh/api-reference/built-in-tools/user-ask) - Ask user for input or clarification
+
+### Context Access
+
+Tools for reading resources and prompts:
+
+- [**resource_read**](/en/mcp-mesh/api-reference/built-in-tools/resource-read) - Read documentation/guidelines from current scope
+- [**prompt_read**](/en/mcp-mesh/api-reference/built-in-tools/prompt-read) - Read prompt templates from current scope
+
+## Availability Matrix
+
+| Tool | Task | Subtask | Description |
+|------|:----:|:-------:|-------------|
+| `tool_search` | ✓ | ✓ | Search for tools in current scope |
+| `tool_enable` | ✓ | ✓ | Activate a tool for use in current task |
+| `agent_search` | ✓ | ✗ | Find agents configured in the organization |
+| `subtask_run` | ✓ | ✗ | Spawn subtask with fresh context |
+| `user_ask` | ✓ | ✗ | Ask user for input or clarification |
+| `resource_read` | ✓ | ✓ | Read documentation/guidelines from current scope |
+| `prompt_read` | ✓ | ✓ | Read prompt templates from current scope |
+
+<Callout type="info">
+  **Tasks** are user-initiated and have full access to all built-in tools. **Subtasks** are spawned by decopilot and have restricted access to prevent infinite delegation and blocking user interactions.
+</Callout>
diff --git a/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/agent-search.mdx b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/agent-search.mdx
new file mode 100644
index 0000000000..97a2a2d050
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/agent-search.mdx
@@ -0,0 +1,59 @@
+---
+title: agent_search
+description: Search for agents configured in the organization
+icon: Bot
+---
+
+## Overview
+
+Searches for agents configured in the organization. Returns agent metadata including purpose and capabilities.
+
+## Availability
+
+- **Tasks**: ✓ Available
+- **Subtasks**: ✗ Not available
+
+## Signature
+
+```typescript
+agent_search(search_term?: string)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `search_term` | `string` | Optional | Search term to filter agents. Empty search returns all available agents. |
+
+## Returns
+
+Array of agent definitions with:
+- **agent_id**: Unique identifier for the agent
+- **name**: Human-readable agent name
+- **purpose**: What the agent is designed to do
+- **capabilities**: List of capabilities the agent has
+
+## Behavior
+
+- Returns agents configured in the organization
+- Empty search returns all available agents
+- Agent metadata includes purpose and capabilities
+- Use with `subtask_run` to delegate work to specific agents
+
+## Example Usage
+
+```typescript
+// Search for all agents
+agent_search()
+
+// Search for deployment agents
+agent_search("deploy")
+
+// Search for code review agents
+agent_search("review")
+```
+
+## Related
+
+- [**subtask_run**](/en/mcp-mesh/api-reference/built-in-tools/subtask-run) - Spawn subtask with specific agent
+- [Built-in Tools Overview](/en/mcp-mesh/api-reference/built-in-tools)
diff --git a/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/prompt-read.mdx b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/prompt-read.mdx
new file mode 100644
index 0000000000..9f40f66aa3
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/prompt-read.mdx
@@ -0,0 +1,175 @@
+---
+title: prompt_read
+description: Read a prompt template from the current scope
+icon: MessageSquare
+---
+
+## Overview
+
+Reads a prompt template from the current scope. Supports scope inheritance like resources (project inherits from org, agent inherits from project+org). Prompt templates provide reusable instructions and workflows.
+
+## Availability
+
+- **Tasks**: ✓ Available
+- **Subtasks**: ✓ Available
+
+## Signature
+
+```typescript
+prompt_read(
+  prompt_name: string,
+  options?: RangeOptions
+)
+
+type RangeOptions = {
+  lineStart?: number
+  lineEnd?: number
+}
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prompt_name` | `string` | Required | Name of the prompt template |
+| `options` | `RangeOptions` | Optional | Line range options |
+| `options.lineStart` | `number` | Optional | Starting line number (default: 0) |
+| `options.lineEnd` | `number` | Optional | Ending line number (default: 20) |
+
+## Returns
+
+Prompt template content and metadata:
+- **content**: The prompt template text
+- **name**: Prompt template name
+- **metadata**: Additional prompt information
+
+## Behavior
+
+- Supports scope inheritance (same as `resource_read`):
+  - Project prompts inherit from organization prompts
+  - Agent prompts inherit from project + organization prompts
+- Set both `options.lineStart` and `options.lineEnd` to 0 to read entire prompt
+- Default behavior (no options) reads first 20 lines (lines 0-20)
+- Line numbers are zero-indexed
+
+## Example Usage
+
+### Read Entire Prompt
+
+```typescript
+// Read entire code review prompt
+prompt_read("code-review-workflow", { lineStart: 0, lineEnd: 0 })
+```
+
+### Read Specific Lines
+
+```typescript
+// Read lines 5-15 of deployment prompt
+prompt_read("deployment-steps", { lineStart: 5, lineEnd: 15 })
+```
+
+### Read Beginning of Prompt
+
+```typescript
+// Read first 20 lines (default)
+prompt_read("bug-fix-workflow")
+```
+
+### Workflow Templates
+
+```typescript
+// Read feature development workflow
+prompt_read("feature-workflow", { lineStart: 0, lineEnd: 0 })
+
+// Read bug triage workflow
+prompt_read("bug-triage", { lineStart: 0, lineEnd: 0 })
+
+// Read code review checklist
+prompt_read("review-checklist", { lineStart: 0, lineEnd: 0 })
+```
+
+## Use Cases
+
+### Workflow Execution
+
+Follow standardized workflows:
+
+```typescript
+// Read deployment workflow
+const workflow = prompt_read("deploy-to-production", { lineStart: 0, lineEnd: 0 })
+
+// Execute each step in the workflow
+// ... workflow execution logic
+```
+
+### Template Reuse
+
+Use prompt templates for consistent task execution:
+
+```typescript
+// Read bug fix template
+const template = prompt_read("bug-fix-template", { lineStart: 0, lineEnd: 0 })
+
+// Apply template structure to current bug
+// ... bug fix logic
+```
+
+### Domain-Specific Instructions
+
+Access specialized instructions:
+
+```typescript
+// Read security review prompt
+const securityPrompt = prompt_read("security-review", { lineStart: 0, lineEnd: 0 })
+
+// Perform security review using the prompt
+// ... security review logic
+```
+
+## Scope Inheritance
+
+Prompts follow scope hierarchy (same as resources):
+
+1. **Agent scope**: Inherits from project + organization
+2. **Project scope**: Inherits from organization
+3. **Organization scope**: Base level prompts
+
+When reading a prompt, the system searches from most specific (agent) to least specific (organization) scope.
+
+## Prompt Template Format
+
+Prompt templates typically include:
+- **Instructions**: Step-by-step guidance
+- **Context**: Background information needed
+- **Examples**: Sample inputs/outputs
+- **Checklist**: Items to verify
+
+Example prompt template structure:
+
+```markdown
+# Feature Development Workflow
+
+## Instructions
+1. Review the feature requirements
+2. Design the implementation approach
+3. Write tests first (TDD)
+4. Implement the feature
+5. Run all tests
+6. Create pull request
+
+## Context
+- Follow the coding standards in coding-guidelines.md
+- Ensure test coverage > 80%
+- Document public APIs
+
+## Checklist
+- [ ] Tests written and passing
+- [ ] Documentation updated
+- [ ] No breaking changes
+```
+
+## Related
+
+- [**resource_read**](/en/mcp-mesh/api-reference/built-in-tools/resource-read) - Read documentation resources
+- [Context Documentation](/en/mcp-mesh/decopilot/context)
+- [Built-in Tools Overview](/en/mcp-mesh/api-reference/built-in-tools)
diff --git a/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/resource-read.mdx b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/resource-read.mdx
new file mode 100644
index 0000000000..3aef0f0bc4
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/resource-read.mdx
@@ -0,0 +1,143 @@
+---
+title: resource_read
+description: Read a resource from the current scope
+icon: FileText
+---
+
+## Overview
+
+Reads a resource from the current scope. Supports scope inheritance (project inherits from org, agent inherits from project+org). Resources can be documentation, guidelines, code snippets, or any contextual information.
+
+## Availability
+
+- **Tasks**: ✓ Available
+- **Subtasks**: ✓ Available
+
+## Signature
+
+```typescript
+resource_read(
+  resource_uri: string,
+  options?: RangeOptions
+)
+
+type RangeOptions = {
+  lineStart?: number
+  lineEnd?: number
+}
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `resource_uri` | `string` | Required | URI identifier for the resource |
+| `options` | `RangeOptions` | Optional | Line range options |
+| `options.lineStart` | `number` | Optional | Starting line number (default: 0) |
+| `options.lineEnd` | `number` | Optional | Ending line number (default: 20) |
+
+## Returns
+
+Resource content and metadata:
+- **content**: The resource text content
+- **uri**: Resource URI
+- **metadata**: Additional resource information
+
+## Behavior
+
+- Supports scope inheritance:
+  - Project resources inherit from organization resources
+  - Agent resources inherit from project + organization resources
+- Set both `options.lineStart` and `options.lineEnd` to 0 to read entire resource
+- Default behavior (no options) reads first 20 lines (lines 0-20)
+- Line numbers are zero-indexed
+
+## Example Usage
+
+### Read Entire Resource
+
+```typescript
+// Read entire coding guidelines document
+resource_read("coding-guidelines.md", { lineStart: 0, lineEnd: 0 })
+```
+
+### Read Specific Lines
+
+```typescript
+// Read lines 10-30 of API documentation
+resource_read("api-docs.md", { lineStart: 10, lineEnd: 30 })
+```
+
+### Read Beginning of Resource
+
+```typescript
+// Read first 20 lines (default)
+resource_read("onboarding-guide.md")
+```
+
+### Resource Types
+
+```typescript
+// Read coding standards
+resource_read("standards/typescript-style.md", { lineStart: 0, lineEnd: 0 })
+
+// Read deployment procedures
+resource_read("procedures/deployment-checklist.md", { lineStart: 0, lineEnd: 0 })
+
+// Read API documentation
+resource_read("docs/rest-api-reference.md", { lineStart: 0, lineEnd: 0 })
+```
+
+## Use Cases
+
+### Context-Driven Execution
+
+Read guidelines before executing work:
+
+```typescript
+// Read coding standards
+const standards = resource_read("coding-standards.md", { lineStart: 0, lineEnd: 0 })
+
+// Apply standards when generating code
+// ... code generation logic
+```
+
+### Documentation Reference
+
+Access reference documentation during task:
+
+```typescript
+// Read API docs
+const apiDocs = resource_read("api-reference.md", { lineStart: 0, lineEnd: 0 })
+
+// Use docs to make correct API calls
+// ... API call logic
+```
+
+### Procedure Compliance
+
+Follow documented procedures:
+
+```typescript
+// Read deployment checklist
+const checklist = resource_read("deployment-checklist.md", { lineStart: 0, lineEnd: 0 })
+
+// Follow each step in the checklist
+// ... deployment logic
+```
+
+## Scope Inheritance
+
+Resources follow scope hierarchy:
+
+1. **Agent scope**: Inherits from project + organization
+2. **Project scope**: Inherits from organization
+3. **Organization scope**: Base level resources
+
+When reading a resource, the system searches from most specific (agent) to least specific (organization) scope.
+
+## Related
+
+- [**prompt_read**](/en/mcp-mesh/api-reference/built-in-tools/prompt-read) - Read prompt templates
+- [Context Documentation](/en/mcp-mesh/decopilot/context)
+- [Built-in Tools Overview](/en/mcp-mesh/api-reference/built-in-tools)
diff --git a/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/subtask-run.mdx b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/subtask-run.mdx
new file mode 100644
index 0000000000..1c5441d78c
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/subtask-run.mdx
@@ -0,0 +1,100 @@
+---
+title: subtask_run
+description: Spawn a subtask with isolated context
+icon: GitBranch
+---
+
+import Callout from "../../../../../components/ui/Callout.astro";
+
+## Overview
+
+Spawns a subtask with isolated context. Optionally specify an agent to use for the subtask. Subtask runs until completion, then returns results.
+
+## Availability
+
+- **Tasks**: ✓ Available
+- **Subtasks**: ✗ Not available (prevents infinite delegation)
+
+<Callout type="warning">
+  **Restriction**: This tool is only available in tasks, not subtasks. This prevents infinite delegation chains and ensures subtasks complete independently.
+</Callout>
+
+## Signature
+
+```typescript
+subtask_run(prompt: string, agent_id?: string)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prompt` | `string` | Required | The task description for the subtask |
+| `agent_id` | `string` | Optional | Specific agent to use for the subtask |
+
+## Returns
+
+Subtask results and completion status.
+
+## Behavior
+
+- Spawns a subtask with isolated context
+- If `agent_id` is omitted, subtask uses current scope capabilities
+- If `agent_id` is specified, subtask uses that agent's capabilities
+- Subtask runs until completion, then returns results
+- Subtasks cannot spawn additional subtasks (prevents infinite delegation)
+- Subtasks cannot ask user questions (prevents blocking)
+
+## Example Usage
+
+```typescript
+// Spawn subtask with current scope
+subtask_run("Analyze the error logs and identify the root cause")
+
+// Spawn subtask with specific agent
+subtask_run(
+  "Review the pull request for code quality issues",
+  "code-review-agent"
+)
+
+// Parallel subtasks for independent work
+subtask_run("Deploy to staging environment")
+subtask_run("Run integration tests")
+```
+
+## Use Cases
+
+### Parallel Execution
+
+Spawn multiple subtasks for independent work that can run in parallel:
+
+```typescript
+subtask_run("Analyze inventory levels across all warehouses")
+subtask_run("Fetch pending customer orders from Shopify")
+subtask_run("Check shipping carrier delivery status")
+```
+
+### Specialized Execution
+
+Delegate work to specialized agents:
+
+```typescript
+// Use agent search to find specialists
+const agents = agent_search("code review")
+
+// Spawn subtask with specialist
+subtask_run("Review this pull request", agents[0].agent_id)
+```
+
+### Isolated Context
+
+Create isolated context for focused work without cluttering main task:
+
+```typescript
+subtask_run("Generate a detailed technical report on the performance bottlenecks")
+```
+
+## Related
+
+- [**agent_search**](/en/mcp-mesh/api-reference/built-in-tools/agent-search) - Find agents for subtasks
+- [Built-in Tools Overview](/en/mcp-mesh/api-reference/built-in-tools)
diff --git a/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/tool-enable.mdx b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/tool-enable.mdx
new file mode 100644
index 0000000000..13770b56bc
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/tool-enable.mdx
@@ -0,0 +1,68 @@
+---
+title: tool_enable
+description: Enable a tool for use in the current task
+icon: ToggleRight
+---
+
+## Overview
+
+Enables a tool for use in the current task. Can only enable tools that exist in the current scope's virtual MCP. Tool remains enabled for task duration only.
+
+## Availability
+
+- **Tasks**: ✓ Available
+- **Subtasks**: ✓ Available
+
+## Signature
+
+```typescript
+tool_enable(tool_name: string)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `tool_name` | `string` | Required | Name of the tool to enable |
+
+## Returns
+
+Success status and enabled confirmation.
+
+## Behavior
+
+- Can only enable tools that exist in the current scope's virtual MCP
+- Tool remains enabled for task duration only
+- Must be called before invoking target tools
+- Tools are discovered via `tool_search` first
+
+## Example Usage
+
+```typescript
+// Enable a Shopify tool
+tool_enable("GET_ORDERS")
+
+// Enable an inventory tool
+tool_enable("UPDATE_STOCK_LEVELS")
+
+// Enable a shipping tool
+tool_enable("CREATE_SHIPPING_LABEL")
+```
+
+## Workflow Pattern
+
+```typescript
+// 1. Discover available tools
+const tools = tool_search("order")
+
+// 2. Enable specific tool
+tool_enable("GET_ORDERS")
+
+// 3. Use the enabled tool
+GET_ORDERS({ status: "pending", limit: 50 })
+```
+
+## Related
+
+- [**tool_search**](/en/mcp-mesh/api-reference/built-in-tools/tool-search) - Discover available tools
+- [Built-in Tools Overview](/en/mcp-mesh/api-reference/built-in-tools)
diff --git a/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/tool-search.mdx b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/tool-search.mdx
new file mode 100644
index 0000000000..0af671a299
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/tool-search.mdx
@@ -0,0 +1,57 @@
+---
+title: tool_search
+description: Search for tools available in the current scope
+icon: Search
+---
+
+## Overview
+
+Searches for tools available in the current scope (organization, project, or agent). Returns tools from the current scope's virtual MCP only.
+
+## Availability
+
+- **Tasks**: ✓ Available
+- **Subtasks**: ✓ Available
+
+## Signature
+
+```typescript
+tool_search(search_term?: string)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `search_term` | `string` | Optional | Search term to filter tools. Empty search returns all available tools. |
+
+## Returns
+
+Array of tool definitions with:
+- **name**: Tool identifier
+- **description**: What the tool does
+- **source**: Where the tool comes from (connection/server)
+
+## Behavior
+
+- Returns tools from the current scope's virtual MCP only
+- Empty search returns all available tools in the current scope
+- Tools must be enabled via `tool_enable` before they can be invoked
+
+## Example Usage
+
+```typescript
+// Search for all tools
+tool_search()
+
+// Search for order-related tools
+tool_search("order")
+
+// Search for inventory tools
+tool_search("inventory")
+```
+
+## Related
+
+- [**tool_enable**](/en/mcp-mesh/api-reference/built-in-tools/tool-enable) - Activate discovered tools
+- [Built-in Tools Overview](/en/mcp-mesh/api-reference/built-in-tools)
diff --git a/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/user-ask.mdx b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/user-ask.mdx
new file mode 100644
index 0000000000..30abdd82bd
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/user-ask.mdx
@@ -0,0 +1,136 @@
+---
+title: user_ask
+description: Ask the user a question to gather input or clarification
+icon: MessageCircle
+---
+
+import Callout from "../../../../../components/ui/Callout.astro";
+
+## Overview
+
+Asks the user a question to gather input or clarification. Supports text input, multiple choice, or confirmation. Task status changes to "Needs Input" until user responds.
+
+## Availability
+
+- **Tasks**: ✓ Available
+- **Subtasks**: ✗ Not available (prevents blocking)
+
+<Callout type="warning">
+  **Restriction**: This tool is only available in tasks, not subtasks. Subtasks run autonomously without blocking on user input.
+</Callout>
+
+## Signature
+
+```typescript
+user_ask(
+  question: string,
+  options?: UserAskOptions
+)
+
+type UserAskOptions = {
+  type?: "text" | "choice" | "confirm"
+  choices?: string[]
+  default?: string | boolean
+}
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `question` | `string` | Required | The question to ask the user |
+| `options` | `UserAskOptions` | Optional | Options for the question |
+| `options.type` | `"text" \| "choice" \| "confirm"` | Optional | Type of input expected (default: "text") |
+| `options.choices` | `string[]` | Optional | Available choices (required for `type: "choice"`) |
+| `options.default` | `string \| boolean` | Optional | Default value |
+
+## Returns
+
+User's response as a string or boolean (depending on question type).
+
+## Behavior
+
+- Task status changes to "Needs Input" until user responds
+- Blocks task execution until user provides answer
+- Only available in tasks (not subtasks) to prevent blocking autonomous work
+
+## Example Usage
+
+### Text Input
+
+```typescript
+const apiKey = user_ask("What is your GitHub API key?")
+```
+
+### Multiple Choice
+
+```typescript
+const environment = user_ask(
+  "Which environment should I deploy to?",
+  {
+    type: "choice",
+    choices: ["staging", "production"],
+    default: "staging"
+  }
+)
+```
+
+### Confirmation
+
+```typescript
+const proceed = user_ask(
+  "This will delete all data. Are you sure?",
+  {
+    type: "confirm",
+    default: false
+  }
+)
+
+if (proceed) {
+  // Execute destructive action
+}
+```
+
+### Clarification During Execution
+
+```typescript
+// Gather requirements
+const features = user_ask("Which features should I enable? (comma-separated)")
+
+// Use the input
+const featureList = features.split(",").map(f => f.trim())
+```
+
+## Use Cases
+
+### Gather Missing Information
+
+```typescript
+const dbUrl = user_ask("What is the database connection string?")
+```
+
+### Confirm Destructive Actions
+
+```typescript
+const confirmed = user_ask(
+  "This will overwrite existing files. Continue?",
+  { type: "confirm" }
+)
+```
+
+### Get User Preferences
+
+```typescript
+const style = user_ask(
+  "Which code style do you prefer?",
+  {
+    type: "choice",
+    choices: ["functional", "object-oriented"],
+    default: "functional"
+  }
+)
+```
+
+## Related
+
+- [Built-in Tools Overview](/en/mcp-mesh/api-reference/built-in-tools)
diff --git a/apps/docs/client/src/content/en/mcp-mesh/api-reference/connection-proxy.mdx b/apps/docs/client/src/content/en/mcp-mesh/api-reference/connection-proxy.mdx
new file mode 100644
index 0000000000..04abb358cc
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/api-reference/connection-proxy.mdx
@@ -0,0 +1,326 @@
+---
+title: Connection Proxy Endpoint
+description: Connect MCP clients directly to upstream MCP servers through deco CMS
+icon: Network
+---
+
+import Callout from "../../../../components/ui/Callout.astro";
+
+## Overview
+
+The **Connection Proxy** endpoint (`/mcp/:connectionId`) enables MCP clients (like Cursor, Claude Desktop, or custom applications) to connect directly to a specific upstream MCP server through deco CMS. This endpoint acts as a secure, observable proxy that handles authentication, authorization, credential management, and monitoring.
+
+## Endpoint
+
+```
+POST https://your-mesh-instance.com/mcp/:connectionId
+```
+
+### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `connectionId` | `string` (UUID) | Required | The unique identifier of the connection to proxy requests to |
+
+## Authentication
+
+The Connection Proxy requires authentication using one of:
+
+- **OAuth Bearer Token**: `Authorization: Bearer <token>`
+- **API Key**: `Authorization: Bearer <api_key>`
+
+When unauthenticated, the endpoint returns a `401` response with an `WWW-Authenticate` header containing OAuth discovery metadata:
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer realm="mcp",resource_metadata="https://your-mesh-instance.com/mcp/:connectionId/.well-known/oauth-protected-resource"
+```
+
+<Callout type="info">
+  Clients supporting OAuth 2.1 can use the resource metadata URL to discover authorization endpoints and complete the OAuth flow automatically.
+</Callout>
+
+## How It Works
+
+When a client sends an MCP request through the Connection Proxy:
+
+1. **Authentication**: deco CMS verifies the client's credentials (OAuth token or API key)
+2. **Connection Lookup**: deco CMS retrieves the connection configuration and verifies it's active
+3. **Authorization**: deco CMS checks if the client has permission to invoke the requested tool
+4. **Credential Injection**: deco CMS decrypts stored credentials and injects them into the upstream request
+5. **Request Proxying**: deco CMS forwards the MCP request to the upstream server
+6. **Monitoring**: deco CMS logs metrics (duration, status, errors) for observability
+7. **Response Return**: deco CMS returns the upstream server's response to the client
+
+## Request Format
+
+The Connection Proxy accepts standard MCP protocol requests. The request body should be a JSON-RPC 2.0 message following the MCP specification.
+
+### Example: List Tools
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/list"
+}
+```
+
+### Example: Call Tool
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/call",
+  "params": {
+    "name": "github_create_issue",
+    "arguments": {
+      "repo": "myorg/myrepo",
+      "title": "Bug report",
+      "body": "Description of the bug"
+    }
+  }
+}
+```
+
+## Response Format
+
+Responses follow standard MCP protocol format:
+
+### Success Response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "Issue created successfully: #123"
+      }
+    ]
+  }
+}
+```
+
+### Error Response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "error": {
+    "code": -32603,
+    "message": "Tool execution failed"
+  }
+}
+```
+
+## Authorization
+
+The Connection Proxy enforces fine-grained authorization using deco CMS's permission system:
+
+- **Per-Tool Permissions**: Users must have explicit permission for each tool they invoke
+- **Connection-Scoped**: Permissions are scoped to the specific connection
+- **Role-Based**: Permissions are inherited from user roles and organization settings
+
+### Permission Format
+
+Permissions are stored in the format:
+
+```json
+{
+  "<connectionId>": ["tool_name_1", "tool_name_2"]
+}
+```
+
+### Public Tools
+
+Tools can be marked as public using metadata:
+
+```json
+{
+  "_meta": {
+    "mcp.mesh": {
+      "public_tool": true
+    }
+  }
+}
+```
+
+Public tools allow unauthenticated access and bypass authorization checks.
+
+## Error Responses
+
+| Status Code | Description | Example Scenario |
+|-------------|-------------|------------------|
+| `401` | Unauthorized | No valid OAuth token or API key provided |
+| `403` | Forbidden | User lacks permission to invoke the requested tool |
+| `404` | Not Found | Connection ID doesn't exist or user doesn't have access |
+| `500` | Internal Server Error | Unexpected error during request processing |
+| `503` | Service Unavailable | Connection is inactive or upstream server is unreachable |
+
+## Streaming Support
+
+The Connection Proxy supports **streaming tool responses** for HTTP-based connections:
+
+### Streamable Tool Endpoint
+
+```
+POST https://your-mesh-instance.com/mcp/:connectionId/call-tool/:toolName
+```
+
+This endpoint allows tools to stream responses back to the client, useful for long-running operations or large data transfers.
+
+<Callout type="warning">
+  Streaming is only supported for HTTP connections. STDIO and VIRTUAL connections fall back to regular tool calls.
+</Callout>
+
+## Monitoring & Observability
+
+Every request through the Connection Proxy generates:
+
+### Metrics
+
+- **Duration Histograms**: `connection.proxy.duration` and `connection.proxy.streamable.duration`
+- **Request Counters**: `connection.proxy.requests` and `connection.proxy.streamable.requests`
+- **Error Counters**: `connection.proxy.errors` and `connection.proxy.streamable.errors`
+
+All metrics include labels:
+- `connection.id`: The connection UUID
+- `tool.name`: The tool being invoked
+- `status`: success or error
+
+### Traces
+
+OpenTelemetry spans are created for:
+- `mcp.proxy.callTool`: Regular tool invocations
+- `mcp.proxy.callStreamableTool`: Streaming tool invocations
+
+Traces include attributes:
+- `connection.id`: Connection identifier
+- `tool.name`: Tool name
+- `request.id`: Unique request identifier
+
+## Configuration Options
+
+Connections can be configured with:
+
+### Timeout Settings
+
+The default timeout for tool calls is **5 minutes** (300,000ms). This can be adjusted per connection based on tool execution characteristics.
+
+### Custom Headers
+
+Connections can include custom HTTP headers for authentication or routing:
+
+```json
+{
+  "connection_headers": {
+    "headers": {
+      "X-Custom-Header": "value"
+    }
+  }
+}
+```
+
+## Use Cases
+
+### Direct MCP Access
+
+Connect Cursor or Claude Desktop directly to a specific upstream MCP:
+
+**Cursor Configuration:**
+```json
+{
+  "mcpServers": {
+    "github-production": {
+      "url": "https://mesh.example.com/mcp/conn_abc123",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### Tool-Specific Clients
+
+Build custom clients that need access to a specific MCP server's tools without Virtual MCP composition:
+
+```typescript
+const response = await fetch('https://mesh.example.com/mcp/conn_abc123', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': 'Bearer YOUR_API_KEY'
+  },
+  body: JSON.stringify({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'tools/call',
+    params: {
+      name: 'database_query',
+      arguments: { query: 'SELECT * FROM users LIMIT 10' }
+    }
+  })
+});
+```
+
+### Multi-Tenant Isolation
+
+Each connection is organization-scoped, providing natural tenant isolation:
+
+```
+Organization A → conn_123 (GitHub Org A) → GitHub Tools (Org A only)
+Organization B → conn_456 (GitHub Org B) → GitHub Tools (Org B only)
+```
+
+## Connection States
+
+Connections have a `status` field that affects proxy behavior:
+
+- **`active`**: Connection is ready to proxy requests
+- **`inactive`**: Connection is disabled; proxy returns `503` error
+- **`error`**: Connection has configuration issues; proxy may fail
+
+## Security Considerations
+
+### Credential Handling
+
+- **Encrypted at Rest**: Credentials are stored encrypted using AES-256-GCM
+- **Decrypted Just-in-Time**: Credentials are only decrypted when proxying requests
+- **Never Exposed to Clients**: Clients never receive upstream credentials
+
+### Request Validation
+
+- **Schema Validation**: Tool arguments are validated against input schemas
+- **Rate Limiting**: (Planned) Per-connection and per-user rate limits
+- **Audit Logging**: All tool invocations are logged with user identity
+
+### Network Security
+
+- **TLS Required**: All connections to upstream servers use HTTPS
+- **Certificate Validation**: SSL certificates are validated by default
+- **Proxy Headers**: Upstream servers receive authenticated requests with credentials
+
+## Comparison with Other Endpoints
+
+| Endpoint | Use Case | Tools Available |
+|----------|----------|-----------------|
+| `/mcp/:connectionId` | Direct access to one upstream MCP | All tools from that connection only |
+| `/mcp/gateway/:agentId` | Curated tool surface (agent/virtual MCP) | Tools from multiple connections, composed |
+| `/mcp/self` | Management operations | deco CMS management tools only |
+
+<Callout type="tip">
+  For most production use cases, use **Agents** (`/mcp/gateway/:agentId`) instead of direct connection proxies. Agents provide better control over tool exposure, support context and resources, and allow multi-connection composition.
+</Callout>
+
+## Related
+
+- [**Connections**](/en/mcp-mesh/connections) - Understanding the Connection abstraction
+- [**Virtual MCPs**](/en/mcp-mesh/virtual-mcps) - Compose multiple connections into agents
+- [**API Keys**](/en/mcp-mesh/api-keys) - Authentication setup
+- [**Monitoring**](/en/mcp-mesh/monitoring) - Observability and metrics
diff --git a/apps/docs/client/src/content/en/mcp-mesh/authorization-and-roles.mdx b/apps/docs/client/src/content/en/mcp-mesh/authorization-and-roles.mdx
deleted file mode 100644
index 0371406972..0000000000
--- a/apps/docs/client/src/content/en/mcp-mesh/authorization-and-roles.mdx
+++ /dev/null
@@ -1,44 +0,0 @@
----
-title: Authorization & Roles
-description: How permissions are enforced across management tools and proxied tool calls
-icon: Users
----
-
-import Callout from "../../../components/ui/Callout.astro";
-
-## The model
-
-The Mesh enforces access control at two layers:
-
-- **Organization roles** (member permissions inside an org)
-- **Tool permissions** (what an API key or user session is allowed to call)
-
-## Roles (built-in + custom)
-
-Every organization starts with three default roles:
-
-- **Owner**: full access (including sensitive actions like deletes)
-- **Admin**: elevated access for day-to-day operations
-- **User**: least privilege by default
-
-You can also create **custom roles** with granular permissions:
-
-- Go to **Members** → **Manage Roles**
-- Create a new role
-- Select which organization permissions that role can perform (tool-scoped toggles)
-
-## API key permissions (tool-scoped)
-
-API keys are created with explicit permissions for specific management tools (and, when applicable, proxied tool usage).
-
-<Callout type="tip">
-  Treat permissions like production infrastructure: default to least privilege and grant only what a client needs.
-</Callout>
-
-## Where this shows up in the product
-
-- **Members**: manage roles and invitations
-- **API Keys**: create/update/delete keys and restrict permissions
-- **Agents**: expose only the desired tool surface (include/exclude strategies)
-
-
diff --git a/apps/docs/client/src/content/en/mcp-mesh/concepts.mdx b/apps/docs/client/src/content/en/mcp-mesh/concepts.mdx
index 4f54fa7627..f988796cec 100644
--- a/apps/docs/client/src/content/en/mcp-mesh/concepts.mdx
+++ b/apps/docs/client/src/content/en/mcp-mesh/concepts.mdx
@@ -1,31 +1,161 @@
 ---
 title: Concepts
-description: The mental model for organizations, connections, agents, API keys, and tool calls
+description: The foundational concepts that power deco CMS
 icon: BookOpen
 ---
 
-## Core entities
+## Core Entities
 
-- **Organization**: the top-level tenant boundary. Everything (connections, agents, logs) is org-scoped.
-- **Members**: users invited into an organization.
-- **Roles**: role assignments for members, used by access control checks.
-- **Connection**: a configured upstream MCP endpoint (usually HTTP), optionally with stored credentials.
-- **Agent**: a virtual MCP server that aggregates multiple connections into a single MCP surface.
-- **Tool call**: a `tools/call` request routed through the Mesh to a downstream MCP server (or via an agent).
-- **Monitoring log**: a record of a tool call (inputs, outputs, duration, error), used for debugging and ops.
+- **Organization**: the top-level tenant boundary. Everything (connections, agents, projects, logs) is org-scoped.
+- **Members**: users invited into an organization with specific roles and permissions.
+- **Connection**: a configured upstream MCP endpoint (usually HTTP), optionally with stored credentials. See [Connections](/en/mcp-mesh/connections).
+- **Virtual MCP**: aggregates tools/resources/prompts from connected servers into a single MCP. See [Virtual MCPs](/en/mcp-mesh/virtual-mcps).
+- **Agent**: single-purpose Virtual MCPs optimized for specific tasks. See [Agents](/en/mcp-mesh/agents).
+- **Project**: Virtual MCPs to organize project-specific tools, resources, prompts, and config. See [Projects](/en/mcp-mesh/projects).
 
-## Data and security boundaries
+## Understanding Agents vs. Projects
 
-- **Credential Vault**: sensitive connection credentials are encrypted at rest (vaulted) and only decrypted at request time.
-- **Permissions**: API keys are scoped to tool permissions; the Mesh enforces authorization before proxying.
+Both agents and projects are Virtual MCPs, but they serve different purposes in your workflow:
 
-## How requests flow
+**Projects** are general-purpose organizational units for ongoing work:
+- **Broad scope** - Cover multiple workflows and capabilities within a work context
+- **Long-lived** - Evolve over time as work progresses
+- **Team collaboration** - Shared workspace for team members
+- **Example** - "Multi-Brand Store Migration" project with inventory sync, order management, and customer data migration tools
+- **When to use** - Organizing work by product line, client, team, or initiative
 
-1. A client authenticates (OAuth session or API key).
-2. The client calls either:
-   - the **Management MCP** (admin tools), or
-   - a **Proxy endpoint** (one connection), or
-   - an **Agent endpoint** (aggregated tools/resources/prompts).
-3. The Mesh authorizes, loads credentials, proxies to the downstream Connection(s), and logs monitoring events.
+**Agents** are organization-wide configurations that can be spawned in any context:
+- **Narrow scope** - Clear, focused objective with curated toolset
+- **Task-specific** - Designed for particular operations or workflows
+- **Fresh execution state** - Each spawn starts with clean context in tasks, subtasks, or projects
+- **Example** - "Refund Processing Agent" that only handles customer refunds and return authorizations
+- **When to use** - Focused operations, built-in mesh management, or specialized workflows
 
+Both follow the same Virtual MCP architecture, but their design principles differ: projects organize capabilities for broad work contexts, while agents are reusable configurations that can be instantiated on-demand with fresh execution state.
 
+## MCP Protocol Primitives
+
+deco CMS is fully [MCP compliant](https://modelcontextprotocol.io/). The Model Context Protocol defines three core primitives:
+
+- **[Tools](https://modelcontextprotocol.io/docs/concepts/tools)**: Executable functions exposed by MCP servers that enable AI agents to take actions (create files, query databases, call APIs, etc.).
+- **[Resources](https://modelcontextprotocol.io/docs/concepts/resources)**: Read-only data sources with URIs (like `org://`, `project://`, `agent://`) that provide context to AI agents.
+- **[Prompts](https://modelcontextprotocol.io/docs/concepts/prompts)**: Reusable templates with variables for common workflows and operations.
+
+deco CMS works exclusively with MCP-compliant clients and servers, providing a standard protocol layer for AI agent communication. For the complete protocol architecture, see the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/concepts/architecture).
+
+## Platform Capabilities
+
+### User Management & Access Control
+
+deco CMS provides organization-level user management with fine-grained permissions:
+
+- **Multi-user organizations** - Invite team members and manage their access
+- **Role-based permissions** - Control what users can see and do within the organization
+- **API key management** - Generate scoped API keys for programmatic access
+- **Connection-level permissions** - Restrict tool access per connection (e.g., read-only GitHub access)
+
+See [User Management](/en/mcp-mesh/user-management) for details on managing team access.
+
+### Security & Credential Management
+
+- **Credential Vault**: Connection credentials are encrypted at rest and only decrypted at request time
+- **Least privilege**: API keys and permissions are scoped to specific tools
+- **Audit logs**: Every tool invocation is logged with caller identity, inputs, and outputs
+- **Zero trust**: All requests are authenticated and authorized, regardless of source
+
+### Built-in Monitoring
+
+deco CMS includes first-class monitoring for all MCP traffic:
+
+- **Tool invocation logs**: See every tool call with inputs, outputs, timing, and caller
+- **Request tracing**: Follow requests across multiple MCP servers
+- **Replay & debug**: Replay past tool invocations to understand behavior
+- **Usage analytics**: Understand which tools and capabilities are being used
+
+See [Monitoring](/en/mcp-mesh/monitoring) for details.
+
+## How the Platform Works
+
+deco CMS sits between MCP clients and MCP servers, providing a unified control layer:
+
+```
+┌─────────┐                    ┌──────────┐                  ┌────────────┐
+│ Client  │ ──[authenticate]──▶│ deco CMS │ ──[with creds]──▶│ MCP Server │
+│ (Cursor)│                    │          │                  │  (GitHub)  │
+└─────────┘ ◀──[response]──────└──────────┘ ◀─[response]─────└────────────┘
+                                     │
+                                     └──▶ [audit log]
+```
+
+### Request Flow
+
+1. **Client authenticates** to deco CMS (OAuth session or API key)
+2. **Client makes request** to a Connection, Agent, Project, or the Management MCP
+3. **deco CMS authorizes** the request against the client's permissions
+4. **deco CMS loads credentials** from the encrypted vault for the target Connection(s)
+5. **deco CMS proxies** the MCP protocol request to the upstream server(s)
+6. **deco CMS logs** the invocation for monitoring and audit
+7. **deco CMS returns** the response to the client
+
+This flow ensures clients never handle credentials directly, all access is authorized consistently, and every operation is observable.
+
+## Architectural Patterns
+
+### Multi-Tenancy Through Organizations
+
+Organizations provide the top-level isolation boundary. Everything in deco CMS is **organization-scoped**:
+
+- Connections, Virtual MCPs, Projects, and Agents are organization-specific
+- Credentials stored in isolated vaults per organization
+- Members, roles, and permissions are organization-scoped
+- Monitoring logs and audit trails isolated per organization
+
+This multi-tenancy model enables SaaS providers to serve multiple customers, enterprises to separate departments, and agencies to isolate client organizations.
+
+### Composition Over Configuration
+
+deco CMS follows a **composition model** rather than requiring complex configuration:
+
+**Connect** individual MCP servers (GitHub, Slack, databases)
+↓
+**Compose** them into Virtual MCPs with curated tool surfaces
+↓
+**Organize** into Projects (for teams) and Agents (for specific tasks)
+↓
+**Expose** through a single MCP-compliant endpoint
+
+This pattern enables building complex capabilities from simple, reusable components without infrastructure changes or deployments.
+
+## Design Decisions
+
+### Why Virtual MCPs Are Editable
+
+Traditional MCP servers expose a fixed set of tools defined in their code. deco CMS's Virtual MCPs are **editable at runtime** because they're configuration, not code. This enables:
+
+- **Dynamic tool surfaces**: Add or remove tools without deployments
+- **Resource creation**: Generate documentation and context on the fly
+- **Prompt evolution**: Update templates based on usage patterns
+- **No-code workflows**: Non-developers can compose capabilities
+
+This editability is why Projects and Agents are Virtual MCPs—they need to evolve as work progresses.
+
+### Why Monitoring is Built-In
+
+In traditional MCP deployments, observability is an afterthought—each client logs independently (or not at all), and there's no unified view of tool usage. deco CMS makes monitoring **first-class** by logging every tool invocation that flows through the platform.
+
+This built-in monitoring enables:
+- **Debugging**: Trace failures across multiple MCP servers
+- **Cost visibility**: See which tools are expensive or slow
+- **Usage patterns**: Understand which capabilities teams actually use
+- **Security audit**: Track who accessed what, when, and why
+
+### Why the MCP Protocol
+
+deco CMS could have invented its own protocol for agent-tool communication, but building on MCP provides:
+
+- **Ecosystem compatibility**: Works with any MCP-compliant client (Claude Desktop, Cursor) and server
+- **Standard semantics**: Tools, Resources, and Prompts have well-defined meanings
+- **Open specification**: MCP is vendor-neutral and evolving through community input
+- **Network effects**: As the MCP ecosystem grows, deco CMS users benefit automatically
+
+By being MCP-native, deco CMS becomes infrastructure for the broader ecosystem, not a proprietary silo.
diff --git a/apps/docs/client/src/content/en/mcp-mesh/connect-clients.mdx b/apps/docs/client/src/content/en/mcp-mesh/connect-clients.mdx
deleted file mode 100644
index 4daf540ce4..0000000000
--- a/apps/docs/client/src/content/en/mcp-mesh/connect-clients.mdx
+++ /dev/null
@@ -1,31 +0,0 @@
----
-title: Connect MCP Clients
-description: How Cursor/Claude/custom clients authenticate to the Mesh and consume tools via MCP
-icon: PlugZap
----
-
-import Callout from "../../../components/ui/Callout.astro";
-
-## Client options
-
-There are two common ways to connect clients to the Mesh:
-
-- **OAuth (recommended for interactive clients)**: supports standard OAuth flows, consent, and organization-aware access.
-- **API Keys (recommended for servers/agents)**: scoped keys with explicit tool permissions.
-
-## Endpoints you’ll use
-
-- **Management MCP**: `POST /mcp`
-- **Connection proxy**: `POST /mcp/:connectionId`
-- **Agent (virtual server)**: `POST /mcp/gateway/:gatewayId` (or omit `:gatewayId` to use the org default Agent with headers)
-
-<Callout type="tip">
-  If your goal is a "single MCP URL" for a curated tool surface, use **Agents**. If you want a direct pipe to one upstream MCP, use **Connection proxy**.
-</Callout>
-
-## Authentication quick notes
-
-- **OAuth** is ideal when you want per-user identity and browser-based sign-in.
-- **API keys** are ideal for automation and server-to-server access (least friction to bootstrap).
-
-
diff --git a/apps/docs/client/src/content/en/mcp-mesh/connections.mdx b/apps/docs/client/src/content/en/mcp-mesh/connections.mdx
new file mode 100644
index 0000000000..7d0770898d
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/connections.mdx
@@ -0,0 +1,143 @@
+---
+title: Connections
+description: How deco CMS connects to upstream MCP servers and how clients connect to deco CMS
+icon: Network
+---
+
+import Callout from "../../../components/ui/Callout.astro";
+
+## What are Connections?
+
+**Connections** represent the bridge between deco CMS and external MCP servers. A Connection is deco CMS's registered relationship with an upstream MCP server—whether that's GitHub, Slack, a database, or your custom MCP implementation.
+
+## Connecting to Upstream MCP Servers
+
+### Why Connections Exist
+
+The Connection abstraction solves a critical problem: **separating connection configuration from usage**. Instead of every client (Cursor, Claude Desktop, custom agents) managing their own credentials and endpoints for each MCP server, deco CMS centralizes this once.
+
+#### The Problem Without Connections
+
+Without a centralized connection layer:
+- Every client must store and manage credentials for every MCP server they use
+- Credential rotation means updating every client
+- No unified audit trail of which tools were accessed and by whom
+- Authorization policies drift across different clients
+- No way to temporarily revoke access to an MCP server without updating all clients
+
+#### How Connections Solve This
+
+Connections provide:
+
+**Centralized credential management**: Store credentials once in deco CMS's encrypted vault. Clients authenticate to deco CMS, not to individual MCP servers.
+
+**Unified authorization**: Define who can access which tools through deco CMS's permission system, rather than managing access per MCP server.
+
+**Credential rotation without client updates**: Update credentials in deco CMS; all clients automatically use the new credentials without reconfiguration.
+
+**Complete observability**: Every tool invocation flows through deco CMS, creating a unified audit trail across all MCP servers.
+
+**Secure credential handling**: Credentials are encrypted at rest and only decrypted at request time, never exposed to clients.
+
+### Design Principles
+
+#### 1. Connections are Read-Only From Client Perspective
+
+Clients interact with tools exposed by Connections, but they cannot modify the Connection configuration itself. This separation ensures:
+- Credentials remain protected
+- Configuration changes require appropriate authorization
+- Audit trails remain trustworthy
+
+#### 2. Connections Compose Into Virtual MCPs
+
+Connections are the building blocks for [Virtual MCPs](/en/mcp-mesh/virtual-mcps). You connect individual MCP servers (GitHub, Slack, databases), then compose them into Virtual MCPs that expose curated tool surfaces.
+
+```
+GitHub Connection  ──┐
+Slack Connection   ──┼──▶ Virtual MCP (Project) ──▶ Clients
+Database Connection──┘
+```
+
+This composition model keeps external MCP servers isolated and secure while enabling flexible, dynamic tool surfaces through Virtual MCPs.
+
+#### 3. Connections are Organization-Scoped
+
+All Connections belong to an organization. This scoping ensures:
+- Clear tenant isolation
+- Organization-wide credential management
+- Consistent access policies across projects and agents
+
+### How Connections Work
+
+When a client invokes a tool through deco CMS:
+
+1. **Client authenticates** to deco CMS (OAuth or API key)
+2. **Authorization check**: deco CMS verifies the client has permission to invoke the requested tool
+3. **Credential loading**: deco CMS decrypts stored credentials for the target Connection
+4. **Request proxying**: deco CMS forwards the MCP request to the upstream server with credentials
+5. **Monitoring**: deco CMS logs the invocation (tool, duration, status, errors)
+6. **Response return**: deco CMS returns the MCP server's response to the client
+
+This flow ensures credentials never leave deco CMS's secure boundary while enabling seamless tool invocation.
+
+### Connection Types
+
+Connections typically fall into three categories:
+
+**SaaS Integration MCPs**: Services like GitHub, Slack, Notion, Google Drive—external systems with their own authentication (often OAuth).
+
+**Infrastructure MCPs**: Database connections, Kubernetes clusters, cloud provider APIs—systems requiring sensitive credentials.
+
+**Custom MCPs**: Your own MCP servers exposing domain-specific tools and operations.
+
+All connection types follow the same pattern: register once in deco CMS, use everywhere through Virtual MCPs and agents.
+
+### Connections vs. Direct Access
+
+**Direct Access** (client → MCP server):
+- ✅ Simple for single-client, single-server scenarios
+- ❌ Credentials managed per client
+- ❌ No unified observability
+- ❌ Authorization logic duplicated
+
+**Through Connections** (client → deco CMS → MCP server):
+- ✅ Centralized credential management
+- ✅ Unified authorization and observability
+- ✅ Credential rotation without client updates
+- ✅ Foundation for Virtual MCPs and composition
+
+For production usage, Connections provide the control plane capabilities needed to operate MCP traffic at scale.
+
+---
+
+## Connecting MCP Clients to deco CMS
+
+Once you've configured upstream connections, you need to connect your MCP clients (Cursor, Claude Desktop, custom agents) to deco CMS to consume the tools.
+
+### Client Authentication Options
+
+There are two common ways to connect clients to deco CMS:
+
+- **OAuth (recommended for interactive clients)**: supports standard OAuth flows, consent, and organization-aware access.
+- **API Keys (recommended for servers/agents)**: scoped keys with explicit tool permissions.
+
+### Endpoints
+
+Depending on your use case, you'll connect to one of these endpoints:
+
+- **Management MCP**: `POST /mcp` - Access deco CMS management tools (creating connections, projects, agents)
+- **Connection proxy**: `POST /mcp/:connectionId` - Direct access to a specific upstream connection
+- **Agent (virtual server)**: `POST /mcp/agent/:agentId` - Access a curated tool surface through an agent
+
+<Callout type="tip">
+  If your goal is a "single MCP URL" for a curated tool surface, use **Agents**. If you want a direct pipe to one upstream MCP, use **Connection proxy**.
+</Callout>
+
+### Authentication Quick Notes
+
+- **OAuth** is ideal when you want per-user identity and browser-based sign-in.
+- **API keys** are ideal for automation and server-to-server access (least friction to bootstrap).
+
+<Callout type="info">
+  Connections are the foundation for [Virtual MCPs](/en/mcp-mesh/virtual-mcps), [Projects](/en/mcp-mesh/projects), and [Agents](/en/mcp-mesh/agents)—you'll connect individual MCP servers first, then compose them into higher-level abstractions.
+</Callout>
diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/context.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/context.mdx
new file mode 100644
index 0000000000..7ebd315f41
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/context.mdx
@@ -0,0 +1,150 @@
+---
+title: Context
+description: Understanding context windows and how decopilot keeps your workspace focused and efficient
+icon: FileText
+---
+
+import Callout from "../../../../components/ui/Callout.astro";
+
+<Callout type="info">
+  This page documents the **planned architecture** for decopilot context. The implementation is in development.
+</Callout>
+
+Every AI [model](https://code.claude.com/docs/en/how-claude-code-works#models) works within a fixed context window—think of it as the model's "working memory" for your conversation. Managing this space well is essential for smooth, productive workflows with decopilot.
+
+Decopilot automatically balances what goes into your context window: instructions from your current [scope](/en/mcp-mesh/decopilot/overview#scopes), available [tools](/en/mcp-mesh/concepts#tools), conversation history, and more. Larger context windows mean you can accomplish more complex work in a single session before needing to refresh.
+
+## Understanding Context Slots
+
+Decopilot organizes your context window into distinct slots, each serving a specific purpose:
+
+1. **System prompt** - Core decopilot behavior and capabilities
+2. **Scope instructions** - Guidelines from your current scope (organization, project, or agent-specific)
+3. **Built-in tools** - Essential decopilot operations always available
+4. **Enabled tools** - Additional [tools](/en/mcp-mesh/concepts#tools) you've activated during your session
+5. **Conversation history** - Your recent messages and decopilot's responses
+6. **Compactification buffer** - Summarized older conversation context
+
+This slot system ensures the most important context stays available while managing space efficiently.
+
+## Context Health: The 40/80 Rule
+
+Your context window performs best when it's not too full. Here's what to watch for:
+
+- **Below 40%**: Optimal performance—plenty of room for complex reasoning and long conversations
+- **40-80%**: Context starts to degrade—still functional but approaching limits
+- **Above 80%**: Time to refresh—decopilot automatically compactifies your conversation history
+
+When your context reaches 80% capacity, decopilot automatically clears the conversation history slot and compactifies it into the buffer. This process summarizes your conversation while preserving important context, giving you room to continue working.
+
+<Callout type="tip">
+You can manually trigger compactification anytime using the `/compact` command—useful when you want to free up space before starting a new phase of work.
+</Callout>
+
+## Keeping Context Lean
+
+The best way to work efficiently is to avoid filling your context unnecessarily. Here are two key techniques:
+
+### Compactification
+
+Compactification summarizes older conversation history while preserving key information. Think of it as consolidating your notes—you keep the important decisions and outcomes, but remove the back-and-forth exploration that led there.
+
+**When to compact:**
+- Automatically triggers at 80% context capacity
+- Manually via `/compact` command before starting complex work
+- After completing a major task but before moving to the next one
+
+### Subtasks
+
+Using subtasks for specific work keeps your main context clean. Subtasks run in their own isolated context space, then return only a summary of results to your main conversation. You can optionally spawn [agents](/en/mcp-mesh/agents)—specialists in specific fields—into subtasks to bring domain expertise to the isolated work.
+
+**Example with subtask only:**
+
+```
+You: "Spawn subtask to analyze stock ruptures"
+  │
+  ▼
+Decopilot creates subtask
+  │
+  ▼
+Subtask analyzes inventory (isolated context)
+  │
+  ▼
+Returns: "3 critical SKUs need reorder, 5 can wait..."
+  │
+  ▼
+Main context: Only sees summary
+```
+
+**Example with specialist agent:**
+
+```
+You: "Use inventory specialist to analyze stock ruptures"
+  │
+  ▼
+Decopilot searches for agents
+  │
+  ▼
+Finds: "Inventory Optimizer" & "Supply Chain Analyst"
+  │
+  ▼
+Decopilot: "Which agent would you prefer?"
+  │
+  ▼
+You: "Inventory Optimizer"
+  │
+  ▼
+Spawns Inventory Optimizer as subtask
+  │
+  ▼
+Specialist forecasts demand, optimizes reorders (isolated context)
+  │
+  ▼
+Returns: "Reorder 500 units SKU-123 from supplier B..."
+  │
+  ▼
+Main context: Only sees summary
+```
+
+This pattern is especially powerful for:
+- Research and exploration tasks
+- Running tests and analyzing results
+- Code reviews and security scans
+- Any work that generates lots of output you don't need to see in full detail
+
+See [Agents](/en/mcp-mesh/agents) for more on how agents provide fresh, focused context for specific tasks.
+
+## How Scopes Affect Context
+
+Each [scope](/en/mcp-mesh/decopilot/scopes) has access only to its own tools and resources. When you switch scopes, the tools available through `tool_search` change to match that scope's virtual MCP, and the instructions that load into the scope instructions slot change—organization, project, or agent-specific. See [Scopes](/en/mcp-mesh/decopilot/scopes) for details.
+
+## Practical Tips
+
+Here are actionable ways to keep your context healthy and productive:
+
+**Watch your context health** - Pay attention to how full your context is. When it hits 40%, consider wrapping up the current phase of work or compacting.
+
+**Use `/compact` strategically** - Manually compact before starting complex new work, after completing major tasks, or when switching between different focus areas.
+
+**Spawn agents for heavy lifting** - Research, testing, code reviews, and any work that generates verbose output should happen in spawned agents. Keep summaries, not details, in your main context.
+
+**Enable tools selectively** - Don't enable every available tool "just in case." Enable tools from your current scope as you need them for specific tasks.
+
+**Work in the right scope** - Use organization scope for cross-project work, project scope for focused development, and let agents handle task-specific work with fresh context.
+
+**Think modular** - Break complex work into phases. Complete one phase, compact or spawn for the next. This keeps each phase focused and your context manageable.
+
+## Why Context Matters
+
+Good context management isn't just about staying under limits—it's about maintaining quality. When context is clean and focused:
+
+- Decopilot reasons more clearly about your specific problem
+- Conversations stay on track without getting lost in accumulated details
+- Complex multi-step workflows remain manageable
+- You spend more time making progress, less time resetting context
+
+By understanding how context works and using the tools available—compactification, agent spawning, selective tool enabling—you can work more effectively with decopilot across projects of any complexity.
+
+---
+
+**Next steps**: Learn about [Scopes](/en/mcp-mesh/decopilot/overview#scopes) to understand how context changes at different levels, or explore [Agents](/en/mcp-mesh/agents) to see how fresh context isolation works in practice.
diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx
new file mode 100644
index 0000000000..2562d91499
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx
@@ -0,0 +1,124 @@
+---
+title: Overview
+description: The agentic AI assistant that runs on deco CMS, operating through distributed MCP architecture
+icon: Sparkles
+---
+
+import Callout from "../../../../components/ui/Callout.astro";
+
+<Callout type="info">
+  This page documents the **planned architecture** for decopilot. The implementation is in development.
+</Callout>
+
+## What is decopilot?
+
+**decopilot** is an agentic AI assistant that orchestrates work across your entire stack—from Shopify and inventory systems to email, customer service platforms, and custom services. Unlike traditional AI assistants confined to code editors, decopilot operates through the Model Context Protocol, giving it reach into the productive applications where real work happens.
+
+You interact through a **chat interface**. Start a conversation, and decopilot works autonomously in the background. Continue with other tasks—when decopilot needs your input, you'll receive a notification. This human-in-the-loop design keeps you in control while letting AI handle coordination across multiple services.
+
+The power comes from **[virtual MCPs](/en/mcp-mesh/virtual-mcps)**—decopilot can create and modify its own capabilities dynamically as it works, adapting to your needs in real-time. This programmable foundation makes decopilot not just a tool user, but a tool builder.
+
+<Callout type="tip" title="New to decopilot?">
+Start with the [Quick Start](/en/mcp-mesh/decopilot/quickstart) guide to see decopilot in action with practical workflows.
+</Callout>
+
+## The Agentic Loop
+
+Decopilot follows the same proven agentic loop pattern as [Claude Code](https://code.claude.com/docs/en/how-claude-code-works#the-agentic-loop): **gather context → take action → verify results**. This cycle runs continuously as you work, with decopilot adapting based on what it learns.
+
+The key difference is where this loop operates. While Claude Code works with local filesystems and terminal commands, decopilot orchestrates **distributed MCP servers** over HTTP. Instead of reading local files, decopilot queries Shopify, inventory systems, customer service platforms, databases, and your custom MCP servers—all through standardized MCP protocol.
+
+Each phase uses MCP tools:
+- **Gather context**: Read from connected MCP servers to understand current state
+- **Take action**: Execute tools across multiple services in a coordinated workflow
+- **Verify results**: Check outcomes, spawn specialized agents for review, adapt approach
+
+The distributed nature means decopilot can orchestrate complex workflows spanning multiple services in a single loop—processing orders in Shopify, managing inventory across warehouses, and sending customer notifications, all while operating on editable virtual MCPs.
+
+## Models
+
+Unlike solutions like [Claude Code](https://code.claude.com/docs/en/how-claude-code-works#models) that are tied to a single provider, decopilot is **multi-model**—it works with various AI model providers to understand your architecture, reason about MCP orchestration, and coordinate distributed workflows.
+
+You can use:
+- **Anthropic models**: Claude Sonnet handles most orchestration tasks well, while Opus provides stronger reasoning for complex multi-service workflows
+- **Other providers**: OpenAI, Google, and other commercial model providers
+- **Free and open source models**: Self-hosted models via compatible APIs
+
+Model choice affects reasoning quality, speed, and cost. Configure which model decopilot uses based on your needs—stronger models for complex coordination, faster models for simple operations, or open source models for full control and privacy.
+
+When this documentation says "decopilot chooses" or "decopilot decides," it's the model doing the reasoning—selecting which MCP servers to query, which tools to enable, and how to coordinate work across distributed systems.
+
+## Context
+
+Context is critical in decopilot. Your conversation history, tool definitions, resources, and MCP server configurations all compete for space in the model's limited token window. The more MCP servers you connect and tools you enable, the more context you consume.
+
+When decopilot starts a task, it loads context based on your current scope—org-level instructions, project-specific guidelines, and agent instructions are all layered according to the scope levels described above. Resources and tools are loaded strategically to keep context usage under control.
+
+Decopilot manages context through:
+- **Strategic tool filtering**: Only enabled tools consume context. Use the discover → enable → use pattern to keep overhead low.
+- **Agent spawning for isolation**: Spawn agents with fresh context for focused work. They return summaries instead of full conversation history.
+- **Reserved token slots**: Decopilot reserves slots for certain operations, ensuring room for critical work even when context is full.
+
+You can always check your current context usage in the decopilot UI to understand what's consuming space and when to spawn an agent for complex work. See [Context](/en/mcp-mesh/decopilot/context) for token budgets, optimization strategies, and practical examples.
+
+## Tasks
+
+As you work, decopilot can delegate specialized work to **[agents](/en/mcp-mesh/agents)**—focused assistants optimized for specific tasks like customer support, research, or data analysis. When you spawn an agent, it gets its own fresh context to work independently, then reports back with a summary.
+
+This lets you handle complex work in parallel. For example, spawn a support agent to answer a customer question about product compatibility while you continue building the checkout flow. The agent works separately with clean context, preventing your main conversation from getting bloated with support details.
+
+Learn more about when to spawn agents and spawning patterns in [Tasks](/en/mcp-mesh/decopilot/tasks-and-spawning).
+
+## Scopes
+
+Decopilot always operates within a **scope**—the virtual MCP context that determines which tools, resources, and instructions are available. Scopes let you work at different levels of focus, from organization-wide operations to project-specific tasks to individual agent work.
+
+Your current scope is determined by where you are in the deco CMS UI, and decopilot automatically loads the appropriate capabilities for that context. The three scope levels are:
+
+- **Org scope**: The default level with organization-wide [connections](/en/mcp-mesh/connections), resources, and [agents](/en/mcp-mesh/agents). Always available as the foundation.
+- **Project scope**: Adds project-specific tools, resources, and prompts from the [project's virtual MCP](/en/mcp-mesh/virtual-mcps). Inherits org scope.
+- **Agent scope**: Adds specialized instructions and bounded tools when working with a specific [agent](/en/mcp-mesh/agents). Inherits org or project scope.
+
+### How Scopes Layer
+
+Scopes layer naturally as you navigate:
+
+- **Org scope alone**: Access org-wide capabilities
+- **Org + Project scope**: Access org capabilities plus project-specific context
+- **Org + Agent scope**: Access org capabilities plus agent-specific instructions
+
+This layered approach means you're never locked into a narrow view—org-level tools remain available even when working in focused project or agent contexts. See [Context](/en/mcp-mesh/decopilot/context#scope-specific-context-loading) for technical details on what context loads at each scope level, and [Tasks](/en/mcp-mesh/decopilot/tasks-and-spawning) to understand how spawned agents create isolated task scopes with fresh context.
+
+## Built-in Tools
+
+Decopilot comes with built-in tools that enable meta-level operations:
+- **`agent_spawn`**: Create child tasks with specialized agents
+- **`agent_search`**: Discover available agents in your organization
+- **`tools_search`**: Find tools in the current scope's virtual MCP
+- **`tool_enable`**: Activate tools in the current scope before use
+- **`resource_read` / `resource_edit`**: Manage project documentation and resources
+- **`prompt_read` / `prompt_edit`**: Create reusable prompt templates
+
+These built-in tools are always available and provide the foundation for working with virtual MCPs. Beyond these, you discover and enable tools from your connected MCP servers (Shopify, inventory systems, customer service platforms, etc.) as needed.
+
+See [Tools](/en/mcp-mesh/decopilot/tools) for complete specifications, usage patterns, and examples of coordinating tools across multiple services.
+
+## Next Steps
+
+Ready to learn more? Explore these guides to understand how decopilot works:
+
+**[Quick Start](/en/mcp-mesh/decopilot/quickstart)**: See decopilot in action with step-by-step workflows. Start here for hands-on examples.
+
+**[Context](/en/mcp-mesh/decopilot/context)**: Learn strategies for managing token usage, when to spawn agents, and how to optimize context.
+
+**[Tasks](/en/mcp-mesh/decopilot/tasks-and-spawning)**: Understand task lifecycles, agent selection, and patterns for parallel execution.
+
+**[Tools](/en/mcp-mesh/decopilot/tools)**: Complete reference for built-in tools and working with target virtual MCP tools.
+
+**[Scopes](/en/mcp-mesh/decopilot/scopes)**: Deep-dive into scope-based routing and how org/project/agent contexts work.
+
+**[Architecture](/en/mcp-mesh/decopilot/architecture)**: Technical implementation details and distributed coordination patterns.
+
+---
+
+Decopilot brings proven agentic patterns to MCP orchestration. By coordinating work across distributed MCP servers while operating on editable virtual MCPs, decopilot enables complex workflows that span multiple services—all through standardized MCP protocol. This is the agentic assistant that runs on deco CMS.
diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx
new file mode 100644
index 0000000000..40c05852e4
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx
@@ -0,0 +1,468 @@
+---
+title: Quick Start
+description: Learn how to work with decopilot through practical e-commerce examples
+icon: Rocket
+---
+
+import Callout from "../../../../components/ui/Callout.astro";
+
+This guide shows you how to use decopilot for common e-commerce tasks. We'll start simple and progressively introduce features like subtasks, agents, context management, and scopes as you need them.
+
+<Callout type="info" title="Progressive Learning">
+Each section builds on the previous one. Feel free to skip ahead if you're already familiar with basic concepts.
+</Callout>
+
+## Prerequisites
+
+Before starting, you'll need:
+
+- **Access to a deco CMS organization** with at least one project
+- **Connected integrations** like Shopify, GitHub, or other MCP servers (recommended but not required)
+- **Basic familiarity** with your e-commerce platform
+
+If you haven't set up integrations yet, see [Connections](/en/mcp-mesh/connections).
+
+## 1. Simple Requests
+
+Just ask decopilot for what you need in natural language. Behind the scenes, decopilot follows a three-step flow:
+
+1. **Search** - Discovers what tools are available for your request
+2. **Enable** - Activates the specific tools it needs
+3. **Execute** - Uses those tools to accomplish your task
+
+You don't need to tell decopilot which tools to use—it figures this out automatically based on what you ask for.
+
+### Example: Check Inventory
+
+```
+You → "Check inventory levels for products below 20 units"
+     ↓
+Decopilot searches for inventory tools
+     ↓
+Decopilot enables inventory tools
+     ↓
+Decopilot queries your inventory system
+     ↓
+You ← "Found 8 products with low stock:
+       • SKU-2847: 12 units (Wireless Headphones)
+       • SKU-1923: 8 units (Phone Case - Black)
+       • SKU-4156: 15 units (Laptop Stand)
+       • SKU-3891: 5 units (USB-C Cable 2m)
+       • SKU-5672: 18 units (Water Bottle)
+       • SKU-7234: 9 units (Desk Lamp)
+       • SKU-8901: 14 units (Keyboard - Mechanical)
+       • SKU-4523: 7 units (Mouse Pad - Large)"
+```
+
+Decopilot automatically discovers and enables the tools it needs—you don't have to tell it which tools to use.
+
+### Example: Update Product Descriptions
+
+```
+You → "Update descriptions for the summer collection
+       to emphasize breathable fabrics and UV protection"
+     ↓
+Decopilot searches for product management tools
+     ↓
+Decopilot enables needed tools
+     ↓
+Decopilot identifies summer collection products
+     ↓
+Decopilot updates 24 product descriptions
+     ↓
+You ← "Updated 24 products in Summer 2026 collection:
+       ✓ Added 'breathable fabric' mentions
+       ✓ Highlighted UPF 50+ sun protection
+       ✓ Emphasized lightweight materials
+
+       Preview: example.com/products/summer-dress-azure"
+```
+
+### Example: Find Missing Content
+
+```
+You → "Find products missing images or descriptions"
+     ↓
+Decopilot searches for content audit tools
+     ↓
+Decopilot enables tools and scans catalog
+     ↓
+You ← "Found 12 products with missing content:
+
+       Missing images (5):
+       • SKU-8821: Ceramic Mug Set
+       • SKU-9234: Garden Tool Kit
+       • SKU-7755: Yoga Mat - Purple
+       • SKU-6543: Plant Hanger - Macrame
+       • SKU-8192: Candle - Lavender
+
+       Missing descriptions (7):
+       • SKU-3421: Travel Backpack
+       • SKU-5667: Stainless Steel Thermos
+       • SKU-2198: Notebook - Dotted
+       • SKU-4456: Pen Set - Gel
+       • SKU-9981: Desk Organizer
+       • SKU-7722: Wall Clock - Wooden
+       • SKU-3388: Picture Frame - 8x10"
+```
+
+**Key takeaway:** For straightforward tasks, just describe what you want. Decopilot automatically discovers and enables the right tools, then executes your request.
+
+---
+
+## 2. Using Subtasks for Heavy Work
+
+When tasks involve analyzing lots of data or doing complex research, use **subtasks**. Subtasks run in isolated context and return just a summary—keeping your main conversation clean and focused.
+
+### When to Use Subtasks
+
+- Analyzing data across many products or orders
+- Research tasks (competitor pricing, trend analysis)
+- Quality audits (checking data consistency, finding errors)
+- Any work that generates verbose output you don't need to see in full
+
+### Example: Analyze Stock Ruptures
+
+```
+You → "Run a subtask to analyze potential stock ruptures
+       across all warehouses for the next 30 days"
+     ↓
+Subtask starts with fresh context
+     ↓
+Subtask searches for inventory & analytics tools
+     ↓
+Subtask enables needed tools
+     ↓
+Subtask analyzes:
+  • 547 SKUs across 3 warehouses
+  • Historical sales data
+  • Seasonal trends
+  • Supplier lead times
+     ↓
+You ← "Stock Rupture Analysis Complete
+
+       CRITICAL (need immediate action):
+       • SKU-2847 Wireless Headphones
+         Current: 12 units | Projected shortage: Feb 18
+         Recommendation: Order 200 units from Supplier A
+
+       • SKU-7234 Desk Lamp
+         Current: 9 units | Projected shortage: Feb 15
+         Recommendation: Order 150 units from Supplier B
+
+       HIGH PRIORITY (order within 1 week):
+       • SKU-8901 Mechanical Keyboard - 14 units
+       • SKU-4156 Laptop Stand - 15 units
+       • SKU-1923 Phone Case Black - 8 units
+
+       MODERATE (monitor closely):
+       • 8 additional SKUs flagged
+
+       Full analysis saved to subtask history."
+```
+
+### Example: Research Competitor Pricing
+
+```
+You → "Run a subtask: research competitor pricing
+       for our top 20 bestselling products"
+     ↓
+Subtask searches for web research & pricing tools
+     ↓
+Subtask enables tools and analyzes competitor sites
+     ↓
+You ← "Pricing Analysis Summary:
+
+       OVERPRICED (consider reducing):
+       • Wireless Headphones: Our $79 vs avg $65
+       • Laptop Stand: Our $45 vs avg $35
+
+       COMPETITIVE (maintain):
+       • Phone Cases: Our $18 vs avg $17
+       • USB Cables: Our $12 vs avg $13
+
+       UNDERPRICED (opportunity to increase):
+       • Mechanical Keyboard: Our $89 vs avg $110
+       • Desk Lamp: Our $32 vs avg $42
+
+       Full competitor breakdown in subtask history."
+```
+
+**Key takeaway:** Use subtasks when you need analysis or research but only want to see the actionable summary. The full details are saved in task history if you need them later.
+
+Learn more: [Tasks & Subtasks](/en/mcp-mesh/decopilot/tasks-and-spawning)
+
+---
+
+## 3. Working with Specialist Agents
+
+**Agents** are specialists with focused expertise in specific domains. When you need specialized analysis or domain knowledge, use an agent—they run in subtasks with tools and instructions tailored to their area.
+
+### Available Agent Types
+
+Common agents for e-commerce teams:
+- **Inventory Specialist** - Demand forecasting, stock optimization, supplier coordination
+- **Shipping & Logistics** - Route optimization, carrier selection, delivery scheduling
+- **Customer Service** - Support strategy, communication planning, issue resolution
+- **Content Specialist** - SEO optimization, copy refinement, brand consistency
+- **Pricing Analyst** - Market analysis, competitive positioning, promotion strategy
+
+### Example: Demand Forecasting
+
+```
+You → "Use the Inventory Specialist to forecast
+       demand for winter collection launch"
+     ↓
+Decopilot searches for agents
+     ↓
+Decopilot → "Found 2 agents:
+             • Inventory Specialist (recommended)
+             • Supply Chain Analyst
+
+             Which would you prefer?"
+     ↓
+You → "Inventory Specialist"
+     ↓
+Agent spawns in subtask with specialized scope
+     ↓
+Agent searches for forecasting & inventory tools
+     ↓
+Agent enables domain-specific tools
+     ↓
+Agent analyzes with specialized expertise
+     ↓
+You ← "Winter Collection Demand Forecast
+
+       HIGH DEMAND (stock heavily):
+       • Wool Scarves: 850-1100 units
+       • Insulated Boots: 650-800 units
+       • Fleece Jackets: 920-1200 units
+
+       MODERATE DEMAND:
+       • Winter Gloves: 400-550 units
+       • Thermal Leggings: 350-480 units
+
+       STRATEGY RECOMMENDATIONS:
+       ✓ Order 70% of forecasted volume upfront
+       ✓ Schedule second shipment for mid-season
+       ✓ Monitor sell-through weekly
+       ✓ Plan flash sales if inventory exceeds 40% after Week 4
+
+       Detailed forecast model in agent task history."
+```
+
+### Example: Shipping Optimization
+
+```
+You → "Use Shipping Agent to optimize delivery
+       routes for holiday orders"
+     ↓
+Agent spawns with logistics & shipping scope
+     ↓
+Agent searches for routing & carrier tools
+     ↓
+Agent enables specialized logistics tools
+     ↓
+Agent analyzes delivery optimization
+     ↓
+You ← "Holiday Shipping Strategy
+
+       ROUTE OPTIMIZATION:
+       • West Coast: Use Carrier A (2-day) - saves $3.20/order
+       • East Coast: Use Carrier B (priority) - saves $1.80/order
+       • Midwest: Split between A & B based on weight
+
+       COST SAVINGS: $8,400/month projected
+
+       CARRIER RECOMMENDATIONS:
+       ✓ Negotiate volume discount with Carrier A (15%)
+       ✓ Set up weekend pickups with Carrier B
+       ✓ Reserve backup capacity with Carrier C for peak days
+
+       Implementation plan in agent history."
+```
+
+**Key takeaway:** Agents bring specialized knowledge to complex tasks. They analyze with domain expertise and return strategic recommendations.
+
+Learn more: [Agents](/en/mcp-mesh/agents)
+
+---
+
+## 4. Managing Context for Long Workflows
+
+When working on complex projects over multiple days, **context** matters. Your conversation history uses working memory—keeping it clean helps decopilot stay focused and productive.
+
+### The 40/80 Rule
+
+- **Below 40%** - Plenty of room, work freely
+- **40-80%** - Context filling up, consider compacting
+- **Above 80%** - Automatic compactification triggers
+
+### When to Compact
+
+Use the `/compact` command to summarize your conversation before:
+- Starting a major new project phase
+- Beginning complex multi-step work
+- Switching between different focus areas
+
+### Example: Product Launch Preparation
+
+```
+Day 1:
+You → "Let's plan the Spring Collection launch"
+     ↓
+[Discussion of strategy, timeline, SKUs...]
+     ↓
+Context: 25% full
+     ↓
+     ↓
+Day 2:
+You → "Run /compact"
+     ↓
+Decopilot summarizes previous work
+     ↓
+Context: 15% full (compacted)
+     ↓
+You → "Now create launch announcement content"
+     ↓
+[Fresh context for new phase...]
+```
+
+### Using Subtasks to Manage Context
+
+Remember: Subtasks keep your main conversation lean. When you spawn a subtask for analysis, only the summary comes back—not the detailed work.
+
+```
+You → "Run subtask: audit product data quality
+       across entire catalog"
+     ↓
+Subtask analyzes 1,200 products
+(generates 15,000 tokens of detailed findings)
+     ↓
+You ← "Quality Audit Summary (450 tokens)
+
+       CRITICAL ISSUES: 23 products
+       HIGH PRIORITY: 87 products
+       MEDIUM PRIORITY: 156 products
+       PASSED: 934 products
+
+       [Summary of top issues...]"
+```
+
+The subtask used 15,000 tokens of context—but your main conversation only sees 450 tokens. This keeps your working memory focused on what matters.
+
+**Key takeaway:** Use `/compact` before major work phases, and use subtasks to keep detailed work isolated. This maintains conversation quality and productivity.
+
+Learn more: [Context Management](/en/mcp-mesh/decopilot/context)
+
+---
+
+## 5. Switching Scopes for Different Work
+
+**Scopes** determine what tools and resources are available. Switch scopes based on what you're working on.
+
+### Three Scope Types
+
+**Organization Scope**
+- Setting up integrations (Shopify, GitHub, Slack)
+- Managing team access and permissions
+- Organization-wide configurations
+
+**Project Scope**
+- Day-to-day feature work
+- Product management
+- Content updates and campaigns
+
+**Agent Scope**
+- Specialized tasks with focused tools
+- Domain expertise (inventory, shipping, etc.)
+- Isolated analysis work
+
+### How to Switch Scopes
+
+Use the **agent selector** at the bottom-left of the chat:
+- No agent selected = Organization or Project scope (depends on current view)
+- Agent selected = Agent scope
+
+### Example: Multi-Scope Workflow
+
+```
+Organization Scope (no agent):
+You → "Connect our Shopify store to decopilot"
+     ↓
+Decopilot searches for connection tools
+     ↓
+Decopilot enables OAuth tools
+     ↓
+Decopilot guides through OAuth setup
+     ↓
+You ← "✓ Shopify connected successfully
+       Store: mystore.myshopify.com
+       Products: 1,247 available"
+     ↓
+     ↓
+Switch to Project Scope (navigate to project):
+You → "Update all summer products with new descriptions"
+     ↓
+Decopilot searches project-specific tools
+     ↓
+Decopilot enables product management tools
+     ↓
+Decopilot updates products
+     ↓
+You ← "✓ Updated 24 products in Summer 2026 collection"
+     ↓
+     ↓
+Switch to Agent Scope (select Inventory Specialist):
+You → "Analyze demand for these summer products"
+     ↓
+Agent searches specialized inventory tools
+     ↓
+Agent enables forecasting tools
+     ↓
+Agent analyzes demand
+     ↓
+You ← "Demand Forecast: [specialist analysis...]"
+```
+
+**Key takeaway:** Switch scopes based on your task. Organization for setup, project for daily work, agents for specialized analysis.
+
+Learn more: [Scopes](/en/mcp-mesh/decopilot/scopes)
+
+---
+
+## Putting It All Together
+
+You've learned the core decopilot workflow:
+
+1. **Simple requests** - Just ask for what you need
+2. **Subtasks** - Isolate complex work, get back summaries
+3. **Agents** - Bring in specialists for domain expertise
+4. **Context** - Use `/compact` and subtasks to stay focused
+5. **Scopes** - Switch contexts for different types of work
+
+### Quick Reference
+
+**When to use what:**
+- Basic task → Just ask decopilot
+- Complex analysis → Run a subtask
+- Need expertise → Use a specialist agent
+- Long project → Compact regularly, use subtasks
+- Setup work → Organization scope
+- Daily work → Project scope
+- Specialized task → Agent scope
+
+### Start Experimenting
+
+The best way to learn is to try. Start with simple requests, then progressively use subtasks and agents as your needs grow more complex.
+
+**Next steps:**
+- [Tools](/en/mcp-mesh/decopilot/tools) - See what decopilot can do
+- [Tasks](/en/mcp-mesh/decopilot/tasks-and-spawning) - Deep dive into subtasks
+- [Context](/en/mcp-mesh/decopilot/context) - Optimize your workflow
+- [Agents](/en/mcp-mesh/agents) - Learn about specialists
+- [Architecture](/en/mcp-mesh/decopilot/architecture) - Technical details
+
+---
+
+Ready to dive in? Open decopilot in your deco CMS organization and start with a simple request. The agentic harness will guide you from there.
diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx
new file mode 100644
index 0000000000..acf52e567d
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx
@@ -0,0 +1,85 @@
+---
+title: Scopes
+description: Understanding how decopilot adapts to different contexts and what's available at each level
+icon: Target
+---
+
+import Callout from "../../../../components/ui/Callout.astro";
+
+<Callout type="info">
+  This page documents the **planned architecture** for decopilot scopes. The implementation is in development.
+</Callout>
+
+## What is Scope?
+
+**Scope** is decopilot's current working context—it determines what instructions, tools, and resources are available as you work.
+
+Scope links your current task context with an MCP (Model Context Protocol server) where tools, resources, and prompts are pulled from. Decopilot automatically adapts based on which view you're in, shifting between organization and project contexts.
+
+## Three Scope Types
+
+**Organization Scope**: Work on organization-wide infrastructure, connections, and team management.
+
+**Project Scope**: Day-to-day development work with project-specific tools and resources.
+
+**Agent Scope**: Focused, specialized tasks with bounded capabilities (security reviews, code analysis, testing).
+
+## How Scope is Determined
+
+Scope is determined by **two simple factors**:
+
+1. **Which view you're in**: Organization view or project view
+2. **Agent selection**: Whether you have an agent selected in the bottom-left of the chat
+
+**When viewing organization**:
+- No agent selected → **Organization scope**
+- Agent selected → **Agent scope**
+
+**When viewing a project**:
+- No agent selected → **Project scope**
+- Agent selected → **Agent scope**
+
+Each scope is completely isolated—there's no inheritance between scopes. When you select an agent, you only have access to that agent's specific tools and resources.
+
+## Scope and Subtasks
+
+[Subtasks](/en/mcp-mesh/decopilot/tasks-and-spawning) can run in different scopes than your main task—this enables agent collaboration.
+
+**Example**: While working in project scope on order fulfillment, you can spawn multiple agents:
+- **Inventory Agent** - Assesses stock availability
+- **Shipping Agent** - Plans logistics
+- **Customer Service Agent** - Prepares support strategy
+
+Your main task coordinates the strategy while each agent handles specialized work in isolation.
+
+<Callout type="tip">
+Start in project scope for most work. Switch to agents when you need specialized capabilities or parallel execution.
+</Callout>
+
+## Switching Scopes
+
+Use the agent selector at the bottom-left of the chat to switch between scopes:
+
+**Example workflow**:
+```
+Project (no agent) → implementing features
+  ↓
+Select security agent → agent scope for security review
+  ↓
+Deselect agent → back to project scope
+```
+
+When you switch, decopilot automatically adjusts available tools and context.
+
+## Key Takeaways
+
+- **Scope adjusts automatically** based on which view you're in and whether an agent is selected
+- **Three scope types** provide different capabilities: organization, project, and agent
+- **Each scope is isolated** with its own tools and resources
+- **Agents are focused** on specialized tasks to maintain clarity
+
+Understanding scope helps you work effectively with decopilot—you'll know what's available and how to organize your work.
+
+---
+
+**Next steps**: Explore [Tools](/en/mcp-mesh/decopilot/tools) to see what decopilot can do, or check out [Tasks](/en/mcp-mesh/decopilot/tasks-and-spawning) to understand task organization.
diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/tasks-and-spawning.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tasks-and-spawning.mdx
new file mode 100644
index 0000000000..6b345cd673
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tasks-and-spawning.mdx
@@ -0,0 +1,191 @@
+---
+title: Tasks
+description: Understanding how tasks and subtasks keep your work organized and context efficient
+icon: Layers
+---
+
+import Callout from "../../../../components/ui/Callout.astro";
+
+<Callout type="info">
+  This page documents the **planned architecture** for tasks in decopilot. The implementation is in development.
+</Callout>
+
+## What Are Tasks?
+
+A **task** is your conversation with decopilot. It's where work happens—where you chat back and forth, decopilot uses tools, and context accumulates as you progress.
+
+Tasks are accessible throughout deco CMS:
+- **Homepage** - Your organization's chat interface shows the current task
+- **Sidebar** - Click the chat icon to open the side panel and continue your task
+- **Task history** - Browse past tasks to review previous work
+
+Every task has a [scope](/en/mcp-mesh/decopilot/scopes) (organization, project, or agent) that determines which instructions load into context. You can switch scopes anytime using the button at the bottom of the chat input—switch between organization-wide work, project-specific focus, or specialized agent scopes as needed.
+
+Think of tasks as persistent workspaces where context builds up naturally as you work.
+
+## Task States and Monitoring
+
+Tasks move through different states as work progresses. Understanding these states helps you manage work and know when tasks need your attention.
+
+### Task Status Overview
+
+Every task has one of four statuses:
+
+- **In Progress** - Active work happening, agent is executing or waiting for next message
+- **Requires Action** - Paused, waiting for your input (tool approval or question response)
+- **Success** - Work completed successfully
+- **Failed** - Something went wrong or task timed out
+
+### When Tasks Require Attention
+
+Tasks pause and transition to "Requires Action" status when:
+
+**Tool approval needed** - Some tools require explicit user approval before execution. The task pauses until you review and approve or deny the tool call.
+
+**Question from agent** - When decopilot needs clarification or decisions, it asks questions using the `user_ask` tool. The task waits for your response.
+
+You can see all tasks requiring attention by clicking the **tasks icon** in the deco CMS sidebar. This view shows tasks grouped by status—letting you quickly identify which tasks need your input.
+
+### Task Timeouts
+
+Tasks automatically timeout after **30 minutes of inactivity**. When this happens:
+
+- Task transitions from "In Progress" to "Failed" status
+- You'll see the timeout noted in task history
+- You can restart work by creating a new task
+
+Timeouts prevent tasks from staying in limbo indefinitely. If you're working on something that naturally takes longer, just send a message or interact with the task periodically to keep it active.
+
+### Viewing Subtask Progress
+
+Subtasks appear in the chat interface while they execute. You can see:
+
+- Subtask status and progress
+- Tools being used
+- Agent reasoning (if enabled)
+
+However, **inputs are disabled** during subtask execution—you can't interact with a subtask directly. Subtasks run autonomously and return summaries to the parent task when complete.
+
+## What Are Subtasks?
+
+A **subtask** is a separate conversation that branches off from your main task to handle focused work. The key difference: subtasks start with fresh [context](/en/mcp-mesh/decopilot/context)—they don't inherit your accumulated conversation history.
+
+This makes subtasks perfect for intensive work that would otherwise fill up your main context window.
+
+### How Subtasks Work
+
+When you spawn a subtask:
+
+1. **Fresh start** - Subtask begins with clean context (just scope instructions and system prompt)
+2. **Independent execution** - Subtask is a regular task with restricted built-in tools (no `subtask_run` or `user_ask`)
+3. **Summary return** - Parent task receives only a concise summary (200-500 tokens)
+4. **Full details preserved** - Complete subtask conversation saved in task history
+
+The parent task sees just the summary—keeping your main conversation lean—while full details remain accessible in the subtask history.
+
+### Key Differences
+
+| Feature | Main Task | Subtask |
+|---------|-----------|---------|
+| Context | Accumulated history | Fresh, clean start |
+| Available tools | All built-in tools + current scope's tools | Same, but no `subtask_run` or `user_ask` |
+| Result visibility | Full conversation | Summary only to parent |
+| User interaction | Can ask questions (`user_ask`) | Cannot ask questions |
+
+Subtasks can't spawn additional subtasks (prevents infinite nesting) and can't ask user questions (they run autonomously).
+
+## When to Use Subtasks
+
+Subtasks shine when you need focused work that would clutter your main conversation.
+
+### Research and Analysis
+
+Deep dives into data, exploring options, or investigating issues work well in subtasks.
+
+**Example**: You're planning inventory purchases and need demand analysis. Spawn a subtask to research sales trends, seasonal patterns, and competitor behavior—then get back just the recommendation, not the dozens of data points analyzed.
+
+### Complex Calculations
+
+Number-crunching work that generates verbose output belongs in subtasks.
+
+**Example**: Calculating optimal shipping routes across multiple warehouses. The subtask analyzes distances, traffic, carrier schedules—you get back just the routing plan, not the calculation details.
+
+### Quality Checks and Reviews
+
+Audits, validation, and review work benefit from isolated context.
+
+**Example**: Before transferring 500 SKUs between warehouses, spawn a subtask with an "Inventory Auditor" agent to verify stock levels. Get back a summary of issues found and transfers validated—keep the detailed audit work out of your main task.
+
+### Parallel Work
+
+When you have independent operations that can run simultaneously, spawn multiple subtasks.
+
+**Example**: Monthly reporting across departments—spawn separate subtasks for apparel, electronics, and home goods analysis. All run in parallel, summaries come back to your main task for synthesis.
+
+## Working with Agent Scopes
+
+Subtasks can run in different [agent](/en/mcp-mesh/agents) scopes than your main task—this is how specialized agents collaborate.
+
+**Example**: Your main task is in organization scope working on order fulfillment. You spawn subtasks using:
+- **Inventory Agent** - Assesses stock availability
+- **Shipping Agent** - Plans logistics and routing
+- **Customer Service Agent** - Prepares support strategies
+
+Each agent brings specialized expertise. Your main task coordinates the overall strategy while agents handle domain-specific details in isolation.
+
+This pattern keeps specialized work contained while letting you benefit from agent expertise.
+
+## Common Patterns
+
+### Pattern 1: Parallel Execution
+
+Spawn multiple subtasks for independent work that can run simultaneously.
+
+**When to use**: Monthly reporting, multi-department analysis, independent validations
+
+**Benefit**: Faster execution, isolated contexts prevent cross-contamination
+
+### Pattern 2: Sequential Delegation
+
+Chain subtasks where each step builds on previous results.
+
+**When to use**: Multi-stage workflows, progressive refinement, decision pipelines
+
+**Benefit**: Clear progression, focused subtasks, results build toward comprehensive outcome
+
+### Pattern 3: Specialist Collaboration
+
+Use different agent scopes for subtasks requiring specialized knowledge.
+
+**When to use**: Cross-functional work, domain expertise needed, coordinated strategies
+
+**Benefit**: Leverage specialized agents, integrate multi-domain insights
+
+## Practical Tips
+
+**Offload heavy lifting** - Research, calculations, and analysis should happen in subtasks. Keep summaries in your main task, not verbose details.
+
+**Match scope to work** - Use specialized agents for domain tasks, organization scope for general work. The right scope brings relevant instructions and context.
+
+**Work in parallel** - Independent subtasks can run simultaneously. Don't wait if the next subtask doesn't depend on the previous one.
+
+**Name clearly** - Give descriptive prompts when spawning: "Analyze Q4 apparel demand trends" rather than "Do analysis". This helps when reviewing task history.
+
+**Review full details when needed** - The complete subtask conversation lives in task history. If you need raw data or detailed analysis, open the subtask from history.
+
+**Watch for clutter signals** - When your main task feels heavy or context-full, spawn subtasks for the next phase of work.
+
+## Context Benefits
+
+Subtasks are powerful for managing your [context window](/en/mcp-mesh/decopilot/context):
+
+- **Main task stays lean** - Only summaries accumulate, not analysis details
+- **Fresh context for complexity** - Subtasks start clean, ideal for deep work
+- **Longer productivity** - Avoid premature compactification in main task
+- **Focused execution** - Each subtask tackles one thing without baggage
+
+By keeping intensive work in subtasks, your main task remains focused and productive across longer sessions.
+
+---
+
+**Next steps**: Learn about [Context](/en/mcp-mesh/decopilot/context) to understand how tasks manage your working memory, explore [Tools](/en/mcp-mesh/decopilot/tools) to see what decopilot can do, or check out [Agents](/en/mcp-mesh/agents) for specialized scopes you can use with subtasks.
diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx
new file mode 100644
index 0000000000..3ca310f369
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx
@@ -0,0 +1,112 @@
+---
+title: Tools
+description: Understanding how decopilot discovers and enables capabilities to stay focused on what matters
+icon: Wrench
+---
+
+import Callout from "../../../../components/ui/Callout.astro";
+
+<Callout type="info">
+  This page documents the **planned architecture** for decopilot tools. The specification serves as the implementation guide for the decopilot module.
+</Callout>
+
+## Overview
+
+Decopilot uses two types of tools: **built-in tools** for discovering capabilities and managing work, and **scope tools** from the current [scope](/en/mcp-mesh/decopilot/scopes) for domain-specific actions. Tools are discovered with `tool_search` and activated on-demand with `tool_enable`, keeping execution focused and preventing tool overload.
+
+## Tool Reference
+
+### Built-in Tools
+
+All built-in tools are available across all scopes. Availability varies between tasks and subtasks.
+
+| Tool | Task | Subtask | Description |
+|------|:----:|:-------:|-------------|
+| **Discovery** |
+| `tool_search` | ✓ | ✓ | Search for tools in current scope |
+| `tool_enable` | ✓ | ✓ | Activate a tool for use in current task |
+| `agent_search` | ✓ | ✓ | Find agents configured in the organization |
+| **Execution** |
+| `subtask_run` | ✓ | ✗ | Spawn subtask with fresh context, optionally specifying an agent |
+| `user_ask` | ✓ | ✗ | Ask user for input or clarification |
+| **Context** |
+| `resource_read` | ✓ | ✓ | Read documentation/guidelines from current scope (supports line ranges) |
+| `prompt_read` | ✓ | ✓ | Read prompt templates from current scope |
+
+### Scope Tools
+
+Scope tools come from the current scope—domain-specific capabilities like Shopify, inventory systems, or shipping tools. These are discovered via `tool_search` and enabled via `tool_enable`.
+
+**Example**: A project with Shopify and ShipStation connections might expose:
+- `GET_ORDERS` - Fetch customer orders
+- `UPDATE_INVENTORY` - Update product stock levels
+- `CREATE_SHIPPING_LABEL` - Generate shipping labels
+- `GET_PRODUCTS` - List product catalog
+
+Scope tool availability in tasks vs subtasks depends on the tool's configuration.
+
+#### Tool Annotations
+
+All tools (both built-in and scope tools) use [standard MCP annotations](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/f385c94cbd5857ac17b611edc823a37606bdb1cc/schema/2025-03-26/schema.ts#L737) to declare their capabilities and restrictions:
+
+- **`readOnlyHint`** - Tool does not modify its environment (default: false)
+- **`destructiveHint`** - Tool may perform destructive updates vs. only additive updates (default: true, only meaningful when `readOnlyHint` is false)
+- **`idempotentHint`** - Calling repeatedly with same arguments has no additional effect (default: false, only meaningful when `readOnlyHint` is false)
+- **`openWorldHint`** - Tool may interact with external entities; false means closed domain (default: true)
+
+These annotations allow decopilot to respect tool constraints automatically. For example, a read-only agent will only discover and enable tools marked as `readOnlyHint: true`, ensuring it never performs destructive actions.
+
+## Understanding Availability
+
+### Tasks vs Subtasks
+
+**Tasks** are user-initiated and top-level. They have full access to all built-in tools, can spawn subtasks, and can ask user questions.
+
+**Subtasks** are spawned by decopilot for parallel work, specialized execution, or isolated context. They have restricted access:
+- **Cannot spawn additional subtasks** - Prevents infinite delegation
+- **Cannot ask user questions** - Subtasks run autonomously without blocking
+
+These restrictions ensure subtasks complete independently and don't create blocking dependencies.
+
+## Tool Discovery Flow
+
+Decopilot starts each task with only built-in tools, then discovers and enables capabilities as needed:
+
+1. **Explore** - Use `tool_search` to see what's available in the current scope
+2. **Enable** - Use `tool_enable` to activate specific tools for the task
+3. **Execute** - Use enabled tools to accomplish work
+4. **Delegate** - Spawn subtasks via `subtask_run` for parallel or specialized work
+
+This discover-and-enable pattern ensures decopilot deliberately chooses its toolset rather than being overwhelmed by every available capability.
+
+## Common Workflows
+
+### Discover-Enable-Execute
+
+The most common pattern for using scope tools:
+
+1. Search for capabilities with `tool_search`
+2. Enable specific tools with `tool_enable`
+3. Use enabled tools to accomplish work
+
+### Delegate to Specialists
+
+For work requiring specialized expertise:
+
+1. Search for agents with `agent_search`
+2. Spawn a subtask with `subtask_run` and specific agent
+3. Continue main task while subtask runs in parallel
+
+### Context-Driven Execution
+
+For tasks requiring domain knowledge:
+
+1. Read relevant resources with `resource_read`
+2. Read workflow templates with `prompt_read`
+3. Use context to inform tool selection and execution
+
+---
+
+**Next steps**: Learn about [Tasks and Spawning](/en/mcp-mesh/decopilot/tasks-and-spawning) to understand how decopilot manages work, or explore [Context](/en/mcp-mesh/decopilot/context) to see how resources and prompts provide guidance.
+
+For technical tool documentation, see [Built-in Tools Reference](/en/mcp-mesh/api-reference/built-in-tools).
diff --git a/apps/docs/client/src/content/en/mcp-mesh/mcp-gateways.mdx b/apps/docs/client/src/content/en/mcp-mesh/mcp-gateways.mdx
deleted file mode 100644
index 757ee00b60..0000000000
--- a/apps/docs/client/src/content/en/mcp-mesh/mcp-gateways.mdx
+++ /dev/null
@@ -1,98 +0,0 @@
----
-title: Agents
-description: Publish a virtual MCP server that aggregates tools/resources/prompts from multiple connections
-icon: Waypoints
----
-
-import Callout from "../../../components/ui/Callout.astro";
-
-## What is an Agent?
-
-An **Agent** is a **virtual MCP server** that aggregates multiple connections into a single MCP surface:
-
-- tools (`tools/list`, `tools/call`)
-- resources (`resources/list`, `resources/read`)
-- prompts (`prompts/list`, `prompts/get`)
-
-This is how you create a curated endpoint for clients without exposing every tool from every connected integration.
-
-## Endpoint
-
-- `POST /mcp/gateway/:gatewayId`
-
-You can also omit `:gatewayId` and rely on the organization's default Agent by providing one of these headers:
-
-- `x-org-id`, or
-- `x-org-slug`
-
-## Selection modes
-
-- **Include**: only the listed connections/tools are exposed.
-- **Exclude**: expose the whole org surface *except* excluded connections/tools.
-
-## Tool exposure strategies
-
-Agents also control **how tools are exposed** to clients (useful when tool surfaces get large).
-These strategies ship by default:
-
-### Passthrough (baseline)
-
-- Exposes all agent tools directly via `tools/list`.
-- Best for small tool surfaces and deterministic behavior.
-
-### Smart tool selection
-
-- Exposes meta-tools for discovery and targeted execution:
-  - `GATEWAY_SEARCH_TOOLS` (keyword search)
-  - `GATEWAY_DESCRIBE_TOOLS` (fetch full schemas)
-  - `GATEWAY_CALL_TOOL` (execute a chosen tool)
-- Goal: keep the tool list small and let the client request details on demand.
-
-### Code execution
-
-- Exposes meta-tools for discovery + sandboxed execution:
-  - `GATEWAY_SEARCH_TOOLS`
-  - `GATEWAY_DESCRIBE_TOOLS`
-  - `GATEWAY_RUN_CODE` (run JS in a sandbox that can call tools)
-- Goal: reduce tool exposure overhead on large surfaces by shifting work into a constrained runtime.
-
-## The default Agent (auto-created per org)
-
-Every new organization gets a **Default Agent**:
-
-- **Strategy**: `passthrough`
-- **Mode**: `exclusion`
-- **Default exclusions**: the built-in **Mesh MCP** connection (management tools) and the **Store/Registry** connection are excluded by default
-- **Default behavior**: everything else in the org is included — so as you connect Integrations, this endpoint becomes the "all tools in the org" Agent
-
-This is the endpoint most teams use as the single aggregated MCP surface for an org.
-
-## Benchmark: strategy tradeoffs
-
-We ran an agent strategy benchmark here: [MCP Agent Benchmark (GitHub Actions run)](https://github.com/decocms/mesh/actions/runs/20584203227).
-
-**Summary (high level):**
-
-- **Small tool surface (~10 tools)**:
-  - **Passthrough** used fewer tokens, but had lower success than **Code execution**
-  - **Smart tool selection** was the least reliable in this run
-- **Large tool surface (~128 tools)**:
-  - **Code execution** reduced token usage substantially vs **Passthrough** and had the highest success
-  - **Smart tool selection** was the most expensive in tokens in this run
-
-If you want the raw numbers, open the run and download the **benchmark-results** artifact.
-
-## Code Execution Tools in the Management MCP
-
-In addition to gateway strategies, you can use code execution tools directly from the **Management MCP** (`/mcp`):
-
-- `CODE_EXECUTION_SEARCH_TOOLS` - search tools by name or description
-- `CODE_EXECUTION_DESCRIBE_TOOLS` - get detailed tool schemas
-- `CODE_EXECUTION_RUN_CODE` - run JS in a sandbox with tool access
-
-These tools operate on:
-- All active connections in the organization (by default)
-- Agent-specific connections (if `gatewayId` is set in context)
-
-This lets you use the code execution paradigm without configuring a specific gateway strategy.
-
diff --git a/apps/docs/client/src/content/en/mcp-mesh/mcp-servers.mdx b/apps/docs/client/src/content/en/mcp-mesh/mcp-servers.mdx
deleted file mode 100644
index 3014f280a9..0000000000
--- a/apps/docs/client/src/content/en/mcp-mesh/mcp-servers.mdx
+++ /dev/null
@@ -1,39 +0,0 @@
----
-title: Connections
-description: Register upstream MCP servers, store credentials, and proxy requests securely
-icon: Server
----
-
-import Callout from "../../../components/ui/Callout.astro";
-
-## What is a connection?
-
-A **Connection** in the Mesh is a configured upstream MCP endpoint (typically HTTP). The Mesh stores its configuration and (optionally) credentials, and can then proxy MCP requests to it.
-
-## In the UI
-
-Go to **Connections** to:
-
-- browse connected connections
-- create a new connection (**Create Connection**)
-- search and manage existing connections
-
-## Proxying to a single connection
-
-Once you have a connection ID, clients can call tools via:
-
-- `POST /mcp/:connectionId`
-
-The Mesh will:
-
-1. authenticate the caller
-2. authorize the tool call
-3. decrypt credentials (if needed)
-4. forward the MCP request to the upstream server
-5. log a monitoring event
-
-<Callout type="info">
-  If you need a single aggregated endpoint for multiple connections, use [Agents](/en/mcp-mesh/mcp-gateways) instead.
-</Callout>
-
-
diff --git a/apps/docs/client/src/content/en/mcp-mesh/monitoring.mdx b/apps/docs/client/src/content/en/mcp-mesh/monitoring.mdx
index 842f6961f6..ced1f82fd1 100644
--- a/apps/docs/client/src/content/en/mcp-mesh/monitoring.mdx
+++ b/apps/docs/client/src/content/en/mcp-mesh/monitoring.mdx
@@ -1,34 +1,141 @@
 ---
 title: Monitoring
-description: Inspect tool calls, errors, and latency across connections and agents
+description: Why observability is built into the control plane and how it enables production MCP operations
 icon: Activity
 ---
 
-## What gets recorded
+import Callout from "../../../components/ui/Callout.astro";
 
-The Mesh records monitoring logs for proxied tool calls, including:
+## Observability as Infrastructure
 
-- tool name
-- connection / agent attribution
-- user identity (user ID or API key user)
-- duration and error status
-- inputs and output (normalized)
+deco CMS treats monitoring as **infrastructure, not an afterthought**. Every tool invocation that flows through the control plane creates a monitoring log—there's no way to disable this, and that's by design.
 
-## In the UI
+<Callout type="tip">
+**Every tool call is monitored by deco CMS.** Whether it's a simple GitHub query or a complex database operation, every MCP tool invocation creates a structured log entry with full request/response details, timing, attribution, and error information. This happens automatically—no configuration required.
+</Callout>
 
-Go to **Monitoring** to:
+Traditional MCP deployments have fragmented observability: each client logs independently (or doesn't log at all), each MCP server has its own logging strategy, and there's no unified view of what happened across the system. deco CMS solves this by logging **at the control plane level**, creating a single source of truth for all MCP traffic.
 
-- view tool call volume, errors, and latency
-- filter by tool/connection/agent/status
-- tail logs via **Streaming**
-- drill into individual calls
+## Why Monitoring is First-Class
 
-## Why this matters
+### The Distributed System Problem
 
-Monitoring is the backbone for:
+MCP deployments are inherently distributed systems:
+- **Multiple clients**: Cursor, Claude Desktop, custom agents
+- **Multiple MCP servers**: GitHub, Slack, databases, custom tools
+- **Multiple operations**: A single user workflow might invoke 10+ tools across 5 MCP servers
 
-- debugging broken tool calls
-- verifying permissions and agent selection
-- tracking latency regressions and error spikes
+When something breaks, you need to reconstruct what happened across this distributed system. Without centralized monitoring, you're correlating logs from different sources with different formats, timestamps, and levels of detail—if those logs even exist.
+
+### Control Plane Logging Solves This
+
+By logging at the control plane (deco CMS), monitoring becomes:
+
+**Centralized**: One place to see all tool invocations across all clients and MCP servers.
+
+**Consistent**: Every log entry follows the same schema with the same level of detail.
+
+**Complete**: No invocation can bypass monitoring—if it went through deco CMS, it's logged.
+
+**Correlated**: Request context connects related operations, enabling distributed tracing across multiple tool invocations.
+
+## What Gets Recorded
+
+Every tool invocation creates a monitoring log with:
+
+### Identity & Attribution
+- **Caller**: Which user or API key made the request
+- **Organization**: Which tenant the request belongs to
+- **Connection**: Which upstream MCP server was invoked
+- **Agent/Project**: If accessed through a Virtual MCP, which one
+
+### Operation Details
+- **Tool name**: The specific tool that was invoked
+- **Input arguments**: What parameters were sent (normalized and sanitized)
+- **Output results**: What the tool returned
+- **Timestamp**: When the invocation occurred
+
+### Performance & Status
+- **Duration**: How long the operation took (milliseconds)
+- **Status**: Success or failure
+- **Error details**: If failed, what went wrong
+- **HTTP status**: The underlying HTTP response code (if applicable)
+
+This comprehensive logging enables multiple use cases beyond debugging.
+
+## Use Cases Enabled by Monitoring
+
+### Debugging Production Failures
+
+When a tool invocation fails, monitoring logs provide:
+- **Exact inputs**: What arguments were passed (to verify correctness)
+- **Error messages**: What the MCP server returned
+- **Timing context**: When the failure occurred and how long it took
+- **Attribution**: Which user/agent made the request
+
+This information is available immediately in the deco CMS UI, without SSH-ing into servers or grepping log files.
+
+### Security & Compliance
+
+Monitoring creates an **immutable audit trail** of all MCP activity:
+- Who accessed which tools, when
+- What data was read or modified
+- Which credentials were used
+- Failed authorization attempts
+
+For regulated industries (finance, healthcare), this audit trail is essential for compliance. For any production system, it's essential for security incident response.
+
+### Cost & Performance Analysis
+
+Monitoring data reveals:
+- **Expensive operations**: Which tools are slowest or most resource-intensive
+- **Usage patterns**: Which tools are actually used (vs. which are just configured)
+- **Bottlenecks**: Where latency spikes occur
+- **Optimization opportunities**: Which Virtual MCPs could benefit from filtering or caching
+
+This visibility enables data-driven decisions about MCP infrastructure optimization.
+
+### Behavior Analysis
+
+Understanding how teams actually use MCP capabilities:
+- **Tool adoption**: Which connections are most valuable
+- **Workflow patterns**: Common sequences of tool invocations
+- **Agent effectiveness**: How agents' tool selection evolves over time
+- **User friction**: Where errors or retries happen most frequently
+
+This informs product decisions about which capabilities to prioritize or improve.
+
+## Monitoring as a Feedback Loop
+
+deco CMS monitoring isn't just passive logging—it creates a feedback loop that improves the platform:
+
+**Error patterns** → Better authorization policies or connection health checks
+
+**Performance data** → Virtual MCP filtering strategies or caching policies
+
+**Usage analytics** → Recommendations for which tools to add or deprecate
+
+**Security events** → Automated responses or enhanced access controls
+
+This feedback loop is only possible with centralized, structured monitoring.
+
+## Privacy & Data Handling
+
+<Callout type="info">
+Monitoring logs include tool inputs and outputs by default. For sensitive operations (e.g., querying customer data), consider:
+- Using API keys with appropriate scope restrictions
+- Implementing connection-level logging policies
+- Leveraging organization-level data retention controls
+
+deco CMS provides the observability infrastructure; your organization defines the privacy policies.
+</Callout>
+
+## Monitoring Philosophy
+
+Traditional systems treat monitoring as "nice to have"—something you add after building the core functionality. deco CMS inverts this:
+
+**Monitoring is not optional**. It's how the control plane operates. Without monitoring logs, you cannot debug, audit, optimize, or secure MCP traffic at scale.
+
+By making observability first-class infrastructure, deco CMS enables teams to run MCP in production with the same confidence they have in other critical systems.
 
 
diff --git a/apps/docs/client/src/content/en/mcp-mesh/overview.mdx b/apps/docs/client/src/content/en/mcp-mesh/overview.mdx
index ebb5e57b9c..241e6d3ff6 100644
--- a/apps/docs/client/src/content/en/mcp-mesh/overview.mdx
+++ b/apps/docs/client/src/content/en/mcp-mesh/overview.mdx
@@ -1,58 +1,70 @@
 ---
 title: Overview
-description: What the MCP Mesh is, what it solves, and the main product surfaces
-icon: Network
+description: MCP platform for teams - connect once, orchestrate everywhere, audit everything
+icon: Info
 ---
 
 import Callout from "../../../components/ui/Callout.astro";
 
-## What is the MCP Mesh?
+![deco](https://assets.decocache.com/mcp/9a3facd8-1199-4635-becc-bdc3f5ee7ab1/deco-banner-capy.png)
 
-The **MCP Mesh** is a **control plane for MCP traffic**. It sits between MCP clients (Cursor, Claude Desktop, custom agents) and MCP servers, providing a centralized layer for **authentication, authorization, credential management, and observability**.
+## MCP is the standard for AI tool access. At scale, you need more than connections—you need audit trails, access controls, and unified logging.
 
-## The problem
+**deco CMS is the context management platform that makes MCP work for teams.**
 
-When MCP moves from a few PoCs to production usage, teams start paying an “integration tax”:
+It's the control plane for MCP traffic—register each MCP server once with centralized credentials, and it becomes available (with proper access controls and audit logging) across all your projects, agents, and workflows.
 
-- **Connection sprawl**: every client wires and maintains its own MCP connections and auth
-- **Inconsistent policy enforcement**: SSO/RBAC and approvals drift across apps and teams
-- **Operational blind spots**: no unified logs/traces to debug failures end-to-end
-- **Tool surface explosion**: too many tools increases context size, latency, and tool-selection errors
+### The Problem
 
-The Mesh centralizes these concerns once, so you can operate MCP traffic like any other production surface.
+As AI agents become core infrastructure, managing their access creates critical challenges:
 
-## High-level architecture
+- **Connection sprawl**: Every employee manually configures MCP connections on their laptop
+- **No audit trails**: Agent actions invisible to logging and compliance systems
+- **Fragmented security**: No centralized control over who accesses what
 
-```
-┌───────────────────┐   ┌──────────────────┐   ┌────────────────────┐
-│ MCP Clients       │   │ MCP Mesh (Proxy) │   │ Downstream MCPs     │
-│ - Cursor          │──▶│ - AuthN/AuthZ    │──▶│ - Slack / Gmail     │
-│ - Claude Desktop  │   │ - Vault          │   │ - Notion / Stripe   │
-│ - Custom agents   │   │ - Agents         │   │ - Your MCP servers  │
-└───────────────────┘   │ - Monitoring     │   └────────────────────┘
-                        └──────────────────┘
-```
+At enterprise scale, teams either abandon internal MCP integration, operate with dangerously broad permissions, or spend months building custom infrastructure.
 
-## What the Mesh centralizes
+### How deco CMS Solves It
 
-- **Routing + execution**: which MCP to call and how to authenticate it
-- **Policy enforcement**: who can access which tools (and through which agents)
-- **Observability**: logs, latency, errors, and request context across tool calls
-- **Runtime strategies (agents)**: different exposure strategies as tool surfaces grow
+**Connect**: Register each MCP server once. Credentials stored securely in the vault, available across your organization. Update API keys once, not on every machine.
 
-## Product surfaces (what you can do today)
+**Orchestrate**: Fine-grained access control with RBAC. Control who uses which tools, when, and how. Complete audit trail showing caller identity, tool name, input/output, and timing.
 
-- **Store**: browse a catalog of Connections you can connect to (default: the official MCP Registry).
-- **Connections**: connect and manage MCP servers (HTTP MCP endpoints).
-- **Hubs**: publish a curated "virtual MCP server" that aggregates tools/resources/prompts from multiple connections.
-- **API Keys**: create scoped keys with explicit tool permissions.
-- **Members & Roles**: invite teammates and manage roles + permissions.
-- **Monitoring**: tool-call logs, errors, latency, filtering, and streaming.
-- **Deploy**: self-host locally (npx / Docker Compose) or on Kubernetes (Helm).
+**Remix**: Combine and filter MCPs into Virtual MCPs at runtime—no code deployment. Create read-only versions, aggregate tools from multiple sources, or build role-specific tool collections.
 
-<Callout type="info">
-  We’re releasing the MCP Mesh to the open-source community in **December 2025**.
-  It’s new, so these docs reflect what exists **in production today** — but we ship new features every week and will keep updating this documentation as those features land. 
-</Callout>
+### Key Features
+
+- **Centralized authentication**: SSO/OAuth 2.1, API keys, encrypted credential vault
+- **Unified audit logging**: Every MCP request logged with full context
+- **Virtual MCPs**: Runtime-editable tool surfaces without deploying code
+- **decopilot**: Built-in orchestration for multi-step agentic workflows
+- **Model-agnostic**: Works with Claude, OpenAI, or any AI provider
+
+### Who It's For
+
+- **Enterprises** managing AI agent access to internal systems (GitHub, Slack, databases, APIs)
+- **Teams** running agentic workflows who need orchestration, logging, and access control
+- **Security teams** requiring audit trails and compliance reporting for AI systems
+
+## Getting Started
+
+Choose your path:
 
+**Quickstart** - Get your first connection running in 5 minutes
+→ [Quickstart Guide](/en/mcp-mesh/quickstart)
 
+**Core Concepts** - Understand connections, virtual MCPs, authorization, and monitoring
+→ [Concepts](/en/mcp-mesh/concepts)
+
+**Self-Host** - Deploy with Docker Compose or Kubernetes
+→ [Self-Hosting Guide](/en/mcp-mesh/self-hosting/quickstart)
+
+## Official Links
+
+- **deco CMS**: [decocms.com](https://www.decocms.com/)
+- **deco CMS (Control Plane)**: [decocms.com/mesh](https://www.decocms.com/mesh)
+- **GitHub Repository**: [github.com/decocms/mesh](https://github.com/decocms/mesh)
+
+<Callout type="info">
+  If you know us from before as **deco.cx** (headless CMS + storefront platform), visit [deco.cx](https://www.decocms.com/use-case/deco-cx). Those docs are at [docs.deco.cx](https://docs.deco.cx/en/getting-started/overview).
+</Callout>
diff --git a/apps/docs/client/src/content/en/mcp-mesh/projects.mdx b/apps/docs/client/src/content/en/mcp-mesh/projects.mdx
new file mode 100644
index 0000000000..97050a00d0
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/projects.mdx
@@ -0,0 +1,69 @@
+---
+title: Projects
+description: Organizational units for managing tools, resources, and prompts scoped to specific work contexts
+icon: FolderTree
+---
+
+import Callout from "../../../components/ui/Callout.astro";
+
+<Callout type="info">
+  This page documents the **planned architecture** for projects in deco CMS. The implementation is in development.
+</Callout>
+
+## What are Projects?
+
+**Projects** are organizational units that leverage [Virtual MCPs](/en/mcp-mesh/virtual-mcps) to manage tools, resources, and prompts within a specific work context. Use projects to isolate capabilities by product, client, team, or initiative.
+
+Projects provide:
+
+- **Work organization** - Group capabilities by product line, client, or feature initiative
+- **Scope isolation** - Each project operates with its own set of tools and credentials
+- **Contextual configuration** - Project-specific guidelines, documentation, and workflows
+- **Team boundaries** - Match your organizational structure with technical boundaries
+
+Projects are available in the sidebar under the **Projects** section, where each operates as a self-contained workspace.
+
+## How Projects Work
+
+Create a project, then configure it by remixing capabilities:
+
+1. **Name** - Identifies the project (e.g., "Mobile App Rewrite", "Client XYZ Portal")
+2. **Description** - Explains the project's purpose, scope, and goals for your team
+3. **Instructions** - Guidelines for how AI agents should work in this project (like `CLAUDE.md` or `AGENTS.md`)
+4. **Tools** - Actions agents may take on this project (select from [connections](/en/mcp-mesh/connections) or create inline)
+5. **Resources** - Extra info for detailed skills the agent may need (documentation, guidelines, domain knowledge)
+6. **Prompts** - How users are supposed to use this project (detailed workflows that combine tools and resources to accomplish specific goals)
+
+Since projects are [Virtual MCPs](/en/mcp-mesh/virtual-mcps), you get full composability—remix external capabilities with custom definitions to build exactly what your team needs.
+
+## Example: Multi-Brand Storefront Project
+
+A multi-brand storefront project might aggregate Shopify tools for product catalog management, Stripe tools for payment processing, analytics tools for conversion tracking, and brand-specific guidelines as resources. AI agents working in this project manage product listings, process orders, analyze sales performance, and follow brand standards—all within the project's isolated scope. Each brand gets its own project with isolated credentials and brand-specific configuration.
+
+## Scope Isolation
+
+Projects enforce boundaries through routing. When AI agents connect to a project, they:
+
+- Access only tools configured for that project
+- See project-specific resources and guidelines
+- Operate within isolated credentials and permissions
+
+Project A cannot access Project B's tools or credentials. Organization-level capabilities remain available across all projects.
+
+## Use Cases
+
+- **Multi-brand stores** - One project per brand with isolated product catalogs and credentials
+- **Marketplace operations** - Separate vendor management, fulfillment, and customer service projects with distinct toolsets
+- **Seasonal campaigns** - Temporary projects for holiday sales with curated marketing and inventory tools
+- **B2B portals** - Projects as tenant boundaries for wholesale customer accounts with custom pricing and catalogs
+
+## Why Use Projects?
+
+- **Clear boundaries** - Prevent tool and credential cross-contamination between initiatives
+- **Organized work** - Match technical scope to organizational structure
+- **Flexible tooling** - Add or remove capabilities without infrastructure changes
+- **Familiar patterns** - `.claude/` (project) and `~/.claude/` (global) convention
+
+---
+
+**Next steps**: Learn about [Virtual MCPs](/en/mcp-mesh/virtual-mcps) to understand how projects aggregate capabilities, or see [Authorization and Roles](/en/mcp-mesh/user-management) for access control.
diff --git a/apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx b/apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx
index eb9a905bce..c182a06475 100644
--- a/apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx
+++ b/apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx
@@ -1,111 +1,65 @@
 ---
 title: Quickstart
-description: Run Mesh locally, connect an Integration, create an Agent, and verify monitoring
+description: Get started with deco CMS managed service in 5 minutes
 icon: Rocket
 ---
 
 import Callout from "../../../components/ui/Callout.astro";
 
-## 1) Run the Mesh
+## Get Started in 5 Minutes
 
-Pick one:
+The fastest way to experience deco CMS is through our managed service at **mesh-admin.decocms.com**. You'll be up and running with your first MCP connection in minutes.
 
-### Option A: one-command local setup (npx)
+### Step 1: Sign Up
 
-```bash
-npx @decocms/mesh
-```
+Navigate to [mesh-admin.decocms.com](https://mesh-admin.decocms.com) and create your account using:
+- Email and password
+- GitHub OAuth
+- Google OAuth
 
-### Option B: local setup with Docker Compose
+### Step 2: Create Your First Organization
 
-```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
+After signing in, you'll be prompted to create an organization. This is your top-level tenant boundary where you'll manage connections, agents, and team members.
 
-# 2. Configure authentication
-cp conf-examples/auth-config.json.example auth-config.json
+Choose an organization name (e.g., "Acme Store" or "My Ecommerce Business") and click **Create Organization**.
 
-# 3. Start the application
-docker compose up -d
+### Step 3: Add a Connection from the Store
 
-# 4. Access
-open http://localhost:3000
-```
+Connections are MCP servers you want to use. deco CMS comes with a built-in store of popular integrations:
 
-**More details:** [Local: Docker Compose](/en/mcp-mesh/deploy/local-docker-compose)
+1. Navigate to **Connections** in the sidebar
+2. Click **Add from Store**
+3. Browse available connections (Shopify, Stripe, WooCommerce, BigCommerce, etc.)
+4. Select a connection and click **Install**
+5. Provide required credentials:
+   - For OAuth connections: Follow the OAuth flow to authorize
+   - For API key connections: Paste your API key
 
-### Option C: run from source
+Your connection is now registered and credentials are encrypted in deco CMS's vault.
 
-```bash
-git clone https://github.com/decocms/mesh.git
-cd mesh
-bun install
-bun run dev
-```
+### Step 4: Start Using Chat
 
-### Option D: deploy to Kubernetes (Helm)
+Once you've connected at least one MCP server, you can start using the built-in chat interface:
 
-```bash
-# 1. Generate a secure secret for authentication
-SECRET=$(openssl rand -base64 32)
+1. Navigate to **Chat** in the sidebar
+2. Your connected tools are automatically available to the AI assistant
+3. Try asking questions or requesting actions that use your connections:
+   - "Show me today's orders from Shopify"
+   - "What's my current inventory for product SKU-12345?"
+   - "List recent failed payment transactions from Stripe"
+   - "Create a refund for order #1234"
+   - "Update the stock quantity for product 'Wireless Headphones' to 150 units"
+   - "Generate a sales report for the last 30 days"
+   - "Send abandoned cart reminders to customers from last week"
 
-# 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"
+The AI will automatically invoke the right tools from your connections to fulfill your requests.
 
-# 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)
-
-## 2) Create a Connection
-
-When you open a new organization, the Mesh will prompt you to:
-
-- **Browse Store** or
-- **Create Connection** directly - provide the MCP URL (HTTP endpoint) and any required credentials
-
-The **Store** is a catalog of Connections you can connect to. By default, the Store points to the **official MCP Registry**.
-
-## 3) Create an organization and invite members
-
-- Go to **Members**
-- Invite teammates
-- Assign roles (Admin/User) as needed
-
-## 4) Create an Agent (virtual server)
-
-- Go to **Agents**
-- Click **Create Agent**
-- Choose **Include** (only selected connections/tools) or **Exclude** (everything except the exclusions)
-
-## 5) Generate an API key for a client
-
-Create an API key with the minimum tool permissions needed (see [API Keys](/en/mcp-mesh/api-keys)).
-
-## 6) Verify monitoring
-
-Use **Monitoring** to confirm:
-
-- tool calls are being logged
-- latency + error rates show up
-- filters (time range, tool name, connection, agent) work as expected
-
-<Callout type="tip">
-  The fastest smoke test is to call a tool through an agent endpoint (so you exercise aggregation + proxy + monitoring).
+<Callout type="success">
+  Congratulations! You've successfully set up your first MCP control plane. From here, you can add more connections, create specialized agents for different workflows, invite team members, and monitor all tool invocations in the **Monitoring** tab.
 </Callout>
 
+## Next Steps
 
+- **[Learn core concepts](/en/mcp-mesh/concepts)** - Understand connections, virtual MCPs, projects, and agents
+- **[Connect your MCP client](/en/mcp-mesh/agents)** - Use your connections with Claude Desktop, Cursor, or custom AI agents
+- **[Monitor tool invocations](/en/mcp-mesh/monitoring)** - Track usage, debug issues, and audit activity
diff --git a/apps/docs/client/src/content/en/mcp-mesh/authentication.mdx b/apps/docs/client/src/content/en/mcp-mesh/self-hosting/authentication.mdx
similarity index 87%
rename from apps/docs/client/src/content/en/mcp-mesh/authentication.mdx
rename to apps/docs/client/src/content/en/mcp-mesh/self-hosting/authentication.mdx
index 414bbebc91..56158167a8 100644
--- a/apps/docs/client/src/content/en/mcp-mesh/authentication.mdx
+++ b/apps/docs/client/src/content/en/mcp-mesh/self-hosting/authentication.mdx
@@ -4,11 +4,11 @@ description: Supported auth methods and how to configure them for self-hosting
 icon: ShieldCheck
 ---
 
-import Callout from "../../../components/ui/Callout.astro";
+import Callout from "../../../../components/ui/Callout.astro";
 
 ## What’s supported
 
-The Mesh uses Better Auth and supports:
+deco CMS uses Better Auth and supports:
 
 - **Email/password**
 - **Magic link**
diff --git a/apps/docs/client/src/content/en/mcp-mesh/deploy/local-docker-compose.mdx b/apps/docs/client/src/content/en/mcp-mesh/self-hosting/deploy/docker-compose.mdx
similarity index 93%
rename from apps/docs/client/src/content/en/mcp-mesh/deploy/local-docker-compose.mdx
rename to apps/docs/client/src/content/en/mcp-mesh/self-hosting/deploy/docker-compose.mdx
index 7f0a3d9c3d..34a0c42b10 100644
--- a/apps/docs/client/src/content/en/mcp-mesh/deploy/local-docker-compose.mdx
+++ b/apps/docs/client/src/content/en/mcp-mesh/self-hosting/deploy/docker-compose.mdx
@@ -1,16 +1,16 @@
 ---
-title: "Local: Docker Compose"
-description: Deploy the MCP Mesh locally using Docker Compose for testing and development
+title: "Docker Compose"
+description: Deploy deco CMS locally using Docker Compose for testing and development
 icon: Container
 ---
 
-import Callout from "../../../../components/ui/Callout.astro";
+import Callout from "../../../../../components/ui/Callout.astro";
 
-This guide covers deploying the MCP Mesh locally using Docker Compose for quick testing and development.
+This guide covers deploying the deco CMS locally using Docker Compose for quick testing and development.
 
-Learn more: [the MCP Mesh product page](https://www.decocms.com/mesh)
+Learn more: [the deco CMS product page](https://www.deco CMS.com/mesh)
 
-Source (Docker Compose + README): [decocms/mesh/deploy](https://github.com/decocms/mesh/tree/main/deploy)
+Source (Docker Compose + README): [deco CMS/mesh/deploy](https://github.com/deco CMS/mesh/tree/main/deploy)
 
 ## Overview
 
@@ -47,7 +47,7 @@ open http://localhost:3000
 ```
 
 <Callout type="tip">
-  These configurations are all you need to start testing with MCP-MESH. If you need other options, check the sections below.
+  These configurations are all you need to start testing with deco CMS. If you need other options, check the sections below.
 </Callout>
 
 ### Minimum Configuration
@@ -68,7 +68,7 @@ The `.env` file contains all configurations.
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `IMAGE_REPOSITORY` | `ghcr.io/decocms/mesh/mesh` | Image repository |
+| `IMAGE_REPOSITORY` | `ghcr.io/deco CMS/mesh/mesh` | Image repository |
 | `IMAGE_TAG` | `latest` | Image tag |
 | `PORT` | `3000` | Port exposed on host |
 | `NODE_ENV` | `production` | Node.js environment |
@@ -187,7 +187,7 @@ volumes:
 
 #### When it's Loaded
 
-The Mesh application loads this file on startup to configure:
+The deco CMS application loads this file on startup to configure:
 
 - Email/Password authentication
 - Social providers (Google, GitHub)
diff --git a/apps/docs/client/src/content/en/mcp-mesh/deploy/kubernetes-helm-chart.mdx b/apps/docs/client/src/content/en/mcp-mesh/self-hosting/deploy/kubernetes.mdx
similarity index 93%
rename from apps/docs/client/src/content/en/mcp-mesh/deploy/kubernetes-helm-chart.mdx
rename to apps/docs/client/src/content/en/mcp-mesh/self-hosting/deploy/kubernetes.mdx
index 3c696a1d88..27a180eebf 100644
--- a/apps/docs/client/src/content/en/mcp-mesh/deploy/kubernetes-helm-chart.mdx
+++ b/apps/docs/client/src/content/en/mcp-mesh/self-hosting/deploy/kubernetes.mdx
@@ -1,16 +1,16 @@
 ---
-title: "Kubernetes: Helm Chart"
-description: Deploy the MCP Mesh on Kubernetes using the Helm chart
+title: "Kubernetes"
+description: Deploy deco CMS on Kubernetes using Helm
 icon: Rocket
 ---
 
-import Callout from "../../../../components/ui/Callout.astro";
+import Callout from "../../../../../components/ui/Callout.astro";
 
-This guide explains how to deploy the MCP Mesh on Kubernetes using the Helm chart.
+This guide explains how to deploy deco CMS on Kubernetes using the Helm chart.
 
-Learn more: [the MCP Mesh product page](https://www.decocms.com/mesh)
+Learn more: [the deco CMS product page](https://www.deco CMS.com/mesh)
 
-Helm chart source: [decocms/helm-chart-deco-mcp-mesh](https://github.com/decocms/helm-chart-deco-mcp-mesh)
+Helm chart source: [deco CMS/helm-chart-deco-mcp-mesh](https://github.com/deco CMS/helm-chart-deco-mcp-mesh)
 
 ## Overview
 
@@ -34,7 +34,7 @@ This Helm chart encapsulates all Kubernetes resources necessary to run the appli
 
 ### Architecture
 
-![Infrastructure](https://raw.githubusercontent.com/decocms/helm-chart-deco-mcp-mesh/main/img/mcp-mesh-infra-arch.jpg)
+![Infrastructure](https://raw.githubusercontent.com/deco CMS/helm-chart-deco-mcp-mesh/main/img/mcp-mesh-infra-arch.jpg)
 
 ## Prerequisites
 
@@ -155,7 +155,7 @@ configMap:
         provider: "resend"
         config:
           apiKey: ""  # Leave empty when using Secret
-          fromEmail: "noreply@decocms.com"
+          fromEmail: "noreply@deco CMS.com"
 ```
 
 #### Step 3: Install/Upgrade
@@ -185,7 +185,7 @@ The main configurable values are in `values.yaml`.
 | Parameter | Description | Default |
 |-----------|-------------|---------|
 | `replicaCount` | Number of replicas | `3` |
-| `image.repository` | Image repository | `ghcr.io/decocms/mesh/mesh` |
+| `image.repository` | Image repository | `ghcr.io/deco CMS/mesh/mesh` |
 | `image.tag` | Image tag | `latest` |
 | `service.type` | Service type | `ClusterIP` |
 | `persistence.enabled` | Enable PVC | `true` |
@@ -261,7 +261,7 @@ chart-deco-mcp-mesh/
 
 ## Templates and Functionality
 
-This section explains how the chart behaves at render/runtime. For the full sources, see the chart repository: [decocms/helm-chart-deco-mcp-mesh](https://github.com/decocms/helm-chart-deco-mcp-mesh).
+This section explains how the chart behaves at render/runtime. For the full sources, see the chart repository: [deco CMS/helm-chart-deco-mcp-mesh](https://github.com/deco CMS/helm-chart-deco-mcp-mesh).
 
 ### `_helpers.tpl` (naming + labels)
 
@@ -307,7 +307,7 @@ The full list lives in `values.yaml`; below are the most important knobs.
 
 ```yaml
 image:
-  repository: ghcr.io/decocms/mesh/mesh
+  repository: ghcr.io/deco CMS/mesh/mesh
   pullPolicy: Always # Always, IfNotPresent, Never
   tag: "latest"
 ```
diff --git a/apps/docs/client/src/content/en/mcp-mesh/self-hosting/quickstart.mdx b/apps/docs/client/src/content/en/mcp-mesh/self-hosting/quickstart.mdx
new file mode 100644
index 0000000000..363ee0edfb
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/self-hosting/quickstart.mdx
@@ -0,0 +1,111 @@
+---
+title: Quickstart
+description: Run Mesh locally or deploy to your infrastructure
+icon: Rocket
+---
+
+import Callout from "../../../../components/ui/Callout.astro";
+
+## 1) Run deco CMS
+
+Pick one:
+
+### Option A: one-command local setup (npx)
+
+```bash
+npx @decocms/mesh
+```
+
+### 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/self-hosting/deploy/docker-compose)
+
+### Option C: run from source
+
+```bash
+git clone https://github.com/decocms/mesh.git
+cd mesh
+bun install
+bun run dev
+```
+
+### 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/self-hosting/deploy/kubernetes)
+
+## 2) Create a Connection
+
+When you open a new organization, deco CMS will prompt you to:
+
+- **Browse Store** or
+- **Create Connection** directly - provide the MCP URL (HTTP endpoint) and any required credentials
+
+The **Store** is a catalog of Connections you can connect to. By default, the Store points to the **official MCP Registry**.
+
+## 3) Create an organization and invite members
+
+- Go to **Members**
+- Invite teammates
+- Assign roles (Admin/User) as needed
+
+## 4) Create an Agent (virtual server)
+
+- Go to **Agents**
+- Click **Create Agent**
+- Choose **Include** (only selected connections/tools) or **Exclude** (everything except the exclusions)
+
+## 5) Generate an API key for a client
+
+Create an API key with the minimum tool permissions needed (see [API Keys](/en/mcp-mesh/api-keys)).
+
+## 6) Verify monitoring
+
+Use **Monitoring** to confirm:
+
+- tool invocations are being logged
+- latency + error rates show up
+- filters (time range, tool name, connection, agent) work as expected
+
+<Callout type="tip">
+  The fastest smoke test is to call a tool through an agent endpoint (so you exercise aggregation + proxy + monitoring).
+</Callout>
+
+
diff --git a/apps/docs/client/src/content/en/mcp-mesh/user-management.mdx b/apps/docs/client/src/content/en/mcp-mesh/user-management.mdx
new file mode 100644
index 0000000000..0e8e86c749
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/user-management.mdx
@@ -0,0 +1,92 @@
+---
+title: User Management
+description: Control who can access your organization and what they're allowed to do
+icon: Users
+---
+
+import Callout from "../../../components/ui/Callout.astro";
+
+## How access control works
+
+deco CMS helps you manage who can do what in your organization. Think of it like managing access to a shared Google Drive or Slack organization—you decide who's on your team and what they can do.
+
+There are two main ways to control access:
+
+- **Team member roles** — What people in your organization can do (view, edit, manage settings, etc.)
+- **API key permissions** — What automated systems or external tools can do when they connect to your organization
+
+## Team roles
+
+When you create an organization, you automatically get three roles to assign to team members:
+
+- **Owner**: Full control over everything, including deleting the organization or removing team members
+- **Admin**: Can manage day-to-day operations like adding connections, creating agents, and inviting users
+- **User**: Basic access to view and use existing connections (great for team members who just need to work with what's already set up)
+
+### Creating custom roles
+
+Need something more specific? You can create custom roles tailored to your team's needs.
+
+**Example**: Create a "Developer" role that can manage connections and agents but can't delete anything, or a "Viewer" role that can only see what's configured without making changes.
+
+To create a custom role:
+
+1. Go to **Members** in your organization
+2. Click **Manage Roles**
+3. Click **Create Role**
+4. Give it a name (like "Developer" or "Support Team")
+5. Select which actions this role should be allowed to perform
+
+<Callout type="tip">
+  **Tip**: Start with the least amount of access needed and add more permissions as needed. It's easier to grant more access later than to deal with accidental changes or deletions.
+</Callout>
+
+## API key permissions
+
+API keys let external tools or automated systems access your organization without requiring someone to log in. When you create an API key, you choose exactly what it's allowed to do.
+
+**Example use cases**:
+- A monitoring system that only needs to read connection status
+- A deployment script that needs to create new connections
+- A third-party integration that should only access specific agents
+
+**Best practice**: Give each API key only the permissions it actually needs. If a script only reads data, don't give it permission to delete things.
+
+## Where to manage access
+
+You'll work with these settings in a few different places:
+
+- **Members page**: Invite teammates, assign roles, and create custom roles
+- **API Keys page**: Create keys for automated tools and set their permissions
+- **Agents page**: Control which tools and connections each agent can access (useful for limiting what AI assistants or automation can do)
+
+## Practical examples
+
+### Give a team member admin access
+
+**When**: You want someone to help manage connections and invite new team members
+
+1. Go to **Members**
+2. Find the person's name
+3. Click their current role (probably "User")
+4. Select **Admin**
+
+### Create an API key for a monitoring tool
+
+**When**: You have a system that needs to check if your connections are working
+
+1. Go to **API Keys**
+2. Click **Create API Key**
+3. Give it a name like "Status Monitor"
+4. Select only "View Connections" permission
+5. Copy the key and use it in your monitoring tool
+
+### Set up a "Read-Only Analyst" role
+
+**When**: You have team members who need to see configurations but shouldn't change anything
+
+1. Go to **Members** → **Manage Roles**
+2. Click **Create Role**
+3. Name it "Read-Only Analyst"
+4. Select only viewing permissions (no create, update, or delete)
+5. Assign this role to the appropriate team members
diff --git a/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx
new file mode 100644
index 0000000000..b6fa334cb2
--- /dev/null
+++ b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx
@@ -0,0 +1,157 @@
+---
+title: Virtual MCPs
+description: Remix connections into reusable packages—select tools and context from multiple sources, add custom logic, and create purpose-built MCPs for your workflows
+icon: Waypoints
+---
+
+import Callout from "../../../components/ui/Callout.astro";
+
+## What Are Virtual MCPs?
+
+In deco CMS, a **Virtual MCP** is a reusable package of capabilities—[tools, resources, and prompts](/en/mcp-mesh/concepts#mcp-protocol-primitives)—remixed from multiple [connections](/en/mcp-mesh/connections).
+
+Instead of giving your AI agent access to everything from every connection, you **compose virtual MCPs** that expose exactly what's needed for each use case. You can:
+
+- **Remix connections**: Select specific tools and context from each connection
+- **Combine multiple sources**: Package Shopify + inventory systems + databases into one unified MCP
+- **Add custom logic**: Extend with inline tools, prompts, and resources
+- **Update dynamically**: Change what's included without reconfiguring your agents
+
+Virtual MCPs are the **backbone of deco CMS**—powering [Projects](/en/mcp-mesh/projects), [Agents](/en/mcp-mesh/agents), and organizational boundaries for how capabilities are packaged and composed.
+
+## How Virtual MCPs Work
+
+Virtual MCPs are built by **remixing connections**—selecting capabilities from external MCPs—and optionally **extending with custom tools, prompts, and resources**.
+
+### Remix from Connections
+
+**Remixing** lets you select and combine tools, resources, and prompts from multiple [connections](/en/mcp-mesh/connections).
+
+A **connection** is how you wire up an external MCP server to deco CMS (see [Connections](/en/mcp-mesh/connections) for details). Once you have connections set up, remixing works like this:
+
+1. **Select specific capabilities** from each connection—tools, resources, prompts
+2. **Combine them** into a single virtual MCP package
+3. **Your agent gets** aggregated access to all selected capabilities in one place
+
+**Example**: An "order-fulfillment-ops" virtual MCP might remix:
+- **Shopify connection**: Order management tools + product catalog
+- **ShipStation connection**: Shipping label generation and tracking tools
+- **Email provider connection**: Order confirmation and shipping notification tools
+
+Your AI agent uses this one virtual MCP to orchestrate the entire order fulfillment process across all three systems.
+
+### Extend with Inline Capabilities
+
+**Inline creation** lets you define tools, resources, and prompts directly within a virtual MCP—extending what connections provide.
+
+Inline tools can **call any MCP connection** available in your deco CMS instance, enabling powerful patterns like orchestration, validation, and feature gating.
+
+Inline tools can call other tools using `callTool(connectionId:TOOL_NAME, params)`, enabling orchestration, validation, and feature gating across your MCP infrastructure.
+
+This remixing approach is perfect for:
+
+- **Custom prompts** that guide agents through team-specific workflows
+- **Context resources** like guidelines, documentation, or domain knowledge
+- **Orchestration tools** that compose tools from multiple connections into higher-level operations
+- **Feature gating and validation** that wrap connection tools with authorization logic (see [Authorization and Roles](/en/mcp-mesh/user-management))
+
+#### Use Case: Feature Gating
+
+Inline tools are ideal for **feature gating**—wrapping connection tools with validation, authorization, or custom behavior.
+
+**Example**: A read-only database tool that validates queries before calling the underlying connection, blocking dangerous operations like `DROP`, `DELETE`, or `UPDATE`.
+
+#### Use Case: Orchestration
+
+Inline tools can coordinate multiple connections in a single operation.
+
+**Example**: An order fulfillment tool that checks inventory (warehouse connection), creates a shipping label (ShipStation connection), sends order confirmation (SendGrid connection), and updates order status (Shopify connection)—all in one coordinated workflow.
+
+These patterns enable **authorization enforcement**, **input validation**, **audit logging** (see [Monitoring](/en/mcp-mesh/monitoring)), and **workflow orchestration** across your MCP infrastructure.
+
+### Combine Both
+
+The real power comes from combining both approaches—remixing capabilities from connections and extending them with inline definitions.
+
+**Example**: A "customer-service-assistant" virtual MCP that combines:
+- **Shopify connection tools**: Order lookup, refund processing
+- **Shopify connection resources**: Product catalog and return policies
+- **Inline prompts**: Custom customer communication templates
+- **Inline resources**: Customer service guidelines and FAQ responses
+
+One virtual MCP, multiple sources (connections + inline definitions), unified agent experience.
+
+## Namespacing & Collision Avoidance
+
+When aggregating capabilities from multiple connections, deco CMS uses **connection-based namespacing** to avoid collisions. Each connection gets a unique ID, and all capabilities from that connection are prefixed with this ID.
+
+### Tools and Prompts
+
+Tools and prompts use the format: `connection_id::CAPABILITY_NAME`
+
+- **Namespace separator**: `::` (double colon) between connection ID and capability name
+- **64-character limit**: The entire namespaced name cannot exceed 64 characters
+
+**Example**: Two Shopify connections can both expose a `GET_ORDERS` tool:
+- `shopify_store_a_456::GET_ORDERS` (Store A account)
+- `shopify_store_b_789::GET_ORDERS` (Store B account)
+
+This ensures capabilities remain distinct even when multiple connections expose tools with the same name.
+
+### Resources
+
+Resources use URI-based namespacing, **except for well-known protocols**.
+
+**Custom protocols** (like `store://`, `inventory://`) get namespaced with the connection ID and URL-encoded:
+- Original: `store://my-brand/products/catalog.json`
+- Namespaced: `shopify_conn_123://store%3A%2F%2Fmy-brand%2Fproducts%2Fcatalog.json`
+
+**Well-known protocols** (like `http://`, `https://`, `ws://`) are **NOT namespaced** and remain unchanged.
+
+**Automatic content rewriting**: When resources are read through a virtual MCP, deco CMS automatically rewrites internal resource links to use the namespaced format. This ensures resources can reference each other correctly.
+
+<Callout type="info">
+Tools and prompts use `connection_id::CAPABILITY_NAME` format (max 64 chars). Resources use `connection_id://encodedUri` for custom protocols, or stay unchanged for well-known protocols.
+</Callout>
+
+## Features Powered by Virtual MCPs
+
+Virtual MCPs provide the **foundational capability** that powers specialized features across deco CMS. All of these inherit full [monitoring capabilities](/en/mcp-mesh/monitoring) for audit trails and observability.
+
+**MCP Client Compatibility**: Virtual MCPs are callable by any MCP-compatible client—including Cursor, Claude Code, VS Code extensions, and any application that implements the Model Context Protocol. This makes your composed capability packages universally accessible across the AI tooling ecosystem.
+
+**Specialized features built on virtual MCPs:**
+
+- **[Agents](/en/mcp-mesh/agents)**: Single-purpose capability packages optimized for specific tasks
+- **[Projects](/en/mcp-mesh/projects)**: Team-scoped capability packages for organizational boundaries
+
+## Use Cases & Benefits
+
+Virtual MCPs turn fragmented MCP connections into unified, reusable capability packages:
+
+**Real-world applications:**
+- **Order Fulfillment Operations**: Package Shopify (orders) + ShipStation (shipping) + email provider (notifications) into one fulfillment MCP
+- **Customer Service Hub**: Remix Shopify tools with inline customer service prompts and return policy guidelines
+- **Inventory Management**: Combine warehouse APIs + Shopify inventory tools with inline stock alert workflows
+- **Multi-brand Store Management**: Share access to a Shopify MCP connection across your team while filtering brand-specific operations—giving managers scoped access to their brand's products and orders without exposing other brands
+- **Ecommerce Analytics**: Package Shopify, Google Analytics, and Stripe tools for end-to-end sales and conversion tracking
+
+**Key benefits:**
+- **Selective remixing**: Choose exactly which tools, resources, and prompts to include from each connection
+- **Inline extensions**: Add custom orchestration, validation, and feature gating logic
+- **Dynamic updates**: Modify what's included without reconfiguring agents
+- **Foundation for specialization**: Building block for [Projects](/en/mcp-mesh/projects) and [Agents](/en/mcp-mesh/agents)
+
+---
+
+## Next Steps
+
+<Callout type="info">
+Start with [Connections](/en/mcp-mesh/connections) to understand how to wire up external MCP servers first.
+</Callout>
+
+**Ready to build?** Follow the [Quickstart](/en/mcp-mesh/quickstart) for step-by-step setup.
+
+**Building for teams?** Learn about [Projects](/en/mcp-mesh/projects) for team-scoped virtual MCPs, or [Agents](/en/mcp-mesh/agents) for single-purpose capability packages.
+
+**Need authorization controls?** See [Authorization and Roles](/en/mcp-mesh/user-management) for securing virtual MCP access with feature gating and policies.
diff --git a/apps/docs/client/src/content/en/mcp-studio/overview.mdx b/apps/docs/client/src/content/en/mcp-studio/overview.mdx
deleted file mode 100644
index 4c53ba02c9..0000000000
--- a/apps/docs/client/src/content/en/mcp-studio/overview.mdx
+++ /dev/null
@@ -1,32 +0,0 @@
----
-title: Overview
-description: No-code admin + SDK to package MCP capabilities as reusable building blocks (coming soon)
-icon: LayoutDashboard
----
-
-import Callout from "../../../components/ui/Callout.astro";
-
-## What is MCP Studio?
-
-**MCP Studio** is the development layer of deco CMS: a **no-code admin + SDK** to package MCP-native capabilities into durable, reusable building blocks.
-
-Learn more: [MCP Studio product page](https://www.decocms.com/mcp-studio)
-
-Use it to turn **tools + schemas + workflows** into apps with:
-
-- Consistent interfaces
-- Explicit permissions and policies
-- Versioning and curation
-- A safe path for other teams to adopt what works
-
-<Callout type="info">
-  **Coming soon:** MCP Studio is being built on top of **the MCP Mesh** and will replace the legacy SaaS admin (`admin.decocms.com`) over time (including a hosted option by us).
-</Callout>
-
-## Where does it fit?
-
-- **The MCP Mesh (foundation):** connect, govern, and observe MCP traffic
-- **MCP Studio (development):** package and curate reusable capabilities
-- **MCP Apps & Store (distribution):** distribute what works across teams
-
-
diff --git a/apps/docs/client/src/content/en/no-code-guides/creating-agents.mdx b/apps/docs/client/src/content/en/no-code-guides/creating-agents.mdx
index 5ff6729628..7044cc75bd 100644
--- a/apps/docs/client/src/content/en/no-code-guides/creating-agents.mdx
+++ b/apps/docs/client/src/content/en/no-code-guides/creating-agents.mdx
@@ -266,7 +266,7 @@ Install Pinecone from **Integrations** → **Browse Store** → **Pinecone**, th
 Fine-tune behavior (most agents work well with defaults):
 
 **Max Steps** (default: 15)
-- How many tool calls the agent can make per response
+- How many tool invocations the agent can make per response
 - Higher = can complete more complex tasks
 - Lower = faster, simpler responses
 
@@ -334,7 +334,7 @@ Open the agent in a thread and try real conversations. Watch which tools it call
 Track agent performance and usage:
 
 - Go to **Usage** in your org
-- See conversations, messages, tool calls, costs per agent
+- See conversations, messages, tool invocations, costs per agent
 - Filter threads by agent to see all conversations
 
 Use these insights to:
diff --git a/apps/docs/client/src/content/en/no-code-guides/creating-tools.mdx b/apps/docs/client/src/content/en/no-code-guides/creating-tools.mdx
index 24378a7ef9..2cf3c162cc 100644
--- a/apps/docs/client/src/content/en/no-code-guides/creating-tools.mdx
+++ b/apps/docs/client/src/content/en/no-code-guides/creating-tools.mdx
@@ -28,13 +28,13 @@ The easiest way to create tools is by describing what you need:
 
 **Example prompts:**
 ```
-I need a tool that checks if a domain is available for purchase
+I need a tool that checks if a product is in stock across all warehouses
 
-Create a tool to fetch weather data for a given city
+Create a tool to calculate discounts based on customer loyalty tier
 
-Help me build a tool that calculates shipping costs based on weight and destination
+Help me build a tool that recommends products based on customer purchase history
 
-I want to validate email addresses and check if the domain has MX records
+I want to validate customer email addresses and send welcome discount codes
 ```
 
 **What happens next:**
@@ -45,11 +45,11 @@ I want to validate email addresses and check if the domain has MX records
 
 **Refine as you go:**
 ```
-Add validation to the email parameter
+Add validation to ensure the customer has a valid loyalty account
 
-Include a timeout parameter with default of 30 seconds
+Include a minimum order total parameter with default of $50
 
-Change the output to also return the domain registrar
+Change the output to also return the discount expiration date
 ```
 
 This conversational approach means you start with a rough idea and iterate toward exactly what you need.
@@ -69,13 +69,13 @@ When you create a tool (whether via deco chat or by clicking the code icon to wr
 Tools follow the `RESOURCE_ACTION` pattern with `UPPERCASE_WITH_UNDERSCORES`:
 
 **Examples:**
-- `CUSTOMER_FETCH` - Fetch a customer record
-- `EMAIL_SEND` - Send an email
-- `INVOICE_CREATE` - Create an invoice
+- `PRODUCT_INVENTORY_CHECK` - Check product inventory levels
+- `ORDER_CONFIRMATION_SEND` - Send order confirmation email
+- `CART_DISCOUNT_APPLY` - Apply discount to shopping cart
 
 ```
-Good: LEAD_QUALIFY, ORDER_TOTAL_CALCULATE
-Bad: qualifyLead, calculate-order-total
+Good: CUSTOMER_LOYALTY_UPDATE, PRODUCT_PRICE_CALCULATE
+Bad: updateLoyalty, calculate-product-price
 ```
 
 **Why this matters:** Agents use tool names to decide when to use them. Descriptive names = better decisions.
@@ -84,10 +84,10 @@ Bad: qualifyLead, calculate-order-total
 
 Tells agents and workflows what the tool does and when to use it:
 ```
-Good: "Qualify a lead based on company size, industry, and budget. 
-Returns score 0-100 and tier (A/B/C)."
+Good: "Check product inventory across all warehouses and calculate available stock.
+Returns total quantity, location breakdown, and low stock alert status."
 
-Bad: "Qualifies leads"
+Bad: "Checks inventory"
 ```
 
 The better the description, the better agents understand when to use it.
@@ -136,7 +136,8 @@ deco CMS automatically generates a form based on your input schema. Fill in the
 
 **Via chat:**
 ```
-@YOUR_TOOL_NAME param1="value" param2=123
+@PRODUCT_INVENTORY_CHECK sku="SKU-12345"
+@ORDER_CONFIRMATION_SEND customerEmail="customer@example.com" orderNumber="ORD-789"
 ```
 
 Iterate until it works as expected.
@@ -182,7 +183,8 @@ Once connected, any tools your custom app provides will automatically appear in
 Ask deco chat to make changes or edit TypeScript directly:
 
 ```
-Update CUSTOMER_FETCH to also return the customer's last order date
+Update PRODUCT_INVENTORY_CHECK to also return the product's reorder threshold
+Update ORDER_CONFIRMATION_SEND to include estimated delivery date
 ```
 
 **Other actions:**
@@ -197,9 +199,10 @@ Hover over any tool card and click **...** to:
 Organize related tools for easier discovery:
 
 **Examples:**
-- **Customer Management** - `CUSTOMER_CREATE`, `CUSTOMER_FETCH`, `CUSTOMER_UPDATE`, `CUSTOMER_DELETE`
-- **Email** - `EMAIL_SEND`, `EMAIL_VALIDATE`, `EMAIL_TEMPLATE_RENDER`
-- **Billing** - `INVOICE_CREATE`, `PAYMENT_PROCESS`, `SUBSCRIPTION_UPDATE`
+- **Customer Management** - `CUSTOMER_CREATE`, `CUSTOMER_FETCH`, `CUSTOMER_UPDATE`, `CUSTOMER_LOYALTY_UPDATE`
+- **Order Processing** - `ORDER_CREATE`, `ORDER_UPDATE`, `ORDER_CANCEL`, `ORDER_REFUND`
+- **Inventory** - `PRODUCT_INVENTORY_CHECK`, `INVENTORY_UPDATE`, `INVENTORY_ALERT_CREATE`
+- **Notifications** - `ORDER_CONFIRMATION_SEND`, `SHIPPING_NOTIFICATION_SEND`, `CART_ABANDONED_SEND`
 
 ## Composition Principles
 
@@ -207,10 +210,10 @@ Organize related tools for easier discovery:
 
 Don't build monolithic tools:
 ```
-❌ CUSTOMER_ONBOARD_AND_EMAIL_AND_SYNC
+❌ ORDER_CREATE_AND_EMAIL_AND_UPDATE_INVENTORY_AND_NOTIFY
 
-✅ CUSTOMER_CREATE → EMAIL_WELCOME_SEND → CRM_SYNC
-   (Three simple tools composed in a workflow)
+✅ ORDER_CREATE → INVENTORY_UPDATE → ORDER_CONFIRMATION_SEND → ORDER_NOTIFICATION_SEND
+   (Four simple tools composed in a workflow)
 ```
 
 ### Schemas Enable Automation
diff --git a/apps/docs/client/src/content/pt-br/introduction.mdx b/apps/docs/client/src/content/pt-br/introduction.mdx
index 40b34276b6..908ec799c7 100644
--- a/apps/docs/client/src/content/pt-br/introduction.mdx
+++ b/apps/docs/client/src/content/pt-br/introduction.mdx
@@ -1,6 +1,6 @@
 ---
 title: Introdução
-description: Documentação de desenvolvimento do MCP Mesh e da plataforma deco CMS
+description: Documentação de desenvolvimento do decocms e da plataforma deco CMS
 icon: Rocket
 ---
 
@@ -12,17 +12,16 @@ import Callout from "../../components/ui/Callout.astro";
 
 **deco CMS** é um **Context Management System** open-source para operações nativas de IA.
 
-Se MCP é a interface padrão para acesso a tools, o deco CMS é a **camada de produção ao redor disso**: conectar servidores MCP, aplicar governança e ter observabilidade conforme o uso escala entre times e ambientes. A plataforma mais ampla também inclui um **framework de builder** (MCP Studio — em breve, substituindo o admin legado) e **capacidades de distribuição** (módulos pré-construidos e uma store).
+Se MCP é a interface padrão para acesso a tools, o deco CMS é a **camada de produção ao redor disso**: conectar servidores MCP, aplicar governança e ter observabilidade conforme o uso escala entre times e ambientes.
 
 **Links oficiais:**
 
 - **deco CMS**: [decocms.com](https://www.decocms.com/)
-- **O MCP Mesh**: [decocms.com/mesh](https://www.decocms.com/mesh)
-- **MCP Studio**: [decocms.com/mcp-studio](https://www.decocms.com/mcp-studio)
+- **decocms**: [decocms.com/mesh](https://www.decocms.com/mesh)
 
 Se você conheceu a gente antes, como **deco.cx**, e está buscando **headless CMS + storefront**, visite [deco.cx](https://www.decocms.com/use-case/deco-cx). Veja a documentação do deco.cx em [docs.deco.cx](https://docs.deco.cx/en/getting-started/overview).
 
-## Comece pelo MCP Mesh
+## Comece com decocms
 
 Escolha uma opção:
 
@@ -87,24 +86,21 @@ A aplicação ficará disponível em `http://localhost:8080`.
 
 **Mais detalhes:** [Kubernetes: Helm Chart](/pt-br/mcp-mesh/deploy/kubernetes-helm-chart)
 
-## Aprenda o Mesh (conceitos + superfícies do produto)
+## Aprenda decocms (conceitos + superfícies do produto)
 
 - **[Visão geral](/pt-br/mcp-mesh/overview)**
 - **[Quickstart](/pt-br/mcp-mesh/quickstart)**
 - **[Conceitos](/pt-br/mcp-mesh/concepts)**
-- **[MCP Servers](/pt-br/mcp-mesh/mcp-servers)**
-- **[MCP Agents](/pt-br/mcp-mesh/mcp-gateways)**
+- **[Conexões](/pt-br/mcp-mesh/connections)**
+- **[Virtual MCPs](/pt-br/mcp-mesh/virtual-mcps)**
 - **[API Keys](/pt-br/mcp-mesh/api-keys)**
 - **[Monitoring](/pt-br/mcp-mesh/monitoring)**
-- **[API Reference](/pt-br/mcp-mesh/api-reference)**
 
 <Callout type="warning">
   **Divisão da documentação (guia rápido):**
 
-  - **O MCP Mesh** → Auto-hospedagem, deploy e operação do Mesh (recomendado).
+  - **decocms** → Auto-hospedagem, deploy e operação do decocms (recomendado).
   - **Admin Legado** → Se você usa `admin.decocms.com` (ainda suportado, **em breve descontinuado**).
-
-  Estamos lançando o **MCP Studio** (em cima do Mesh), que vai trazer as capacidades do admin SaaS atual para o Mesh (incluindo uma versão hospedada por nós) e substituir o SaaS legado ao longo do tempo.
 </Callout>
 
 ## Problema: a lacuna entre demo e produção
@@ -119,18 +115,11 @@ IA é fácil de demonstrar e difícil de **operar**.
 
 Para contexto sobre a visão da plataforma, leia [The architecture of an AI-native company](https://www.decocms.com/blog/post/ai-native-company).
 
-## Estrutura da plataforma: Mesh → Studio → Apps & Store
+## Estrutura da plataforma: Core → Apps & Store
 
-### O MCP Mesh (fundação)
+### decocms (fundação)
 Um **control plane** open-source para tráfego MCP. Ele fica entre seus clientes MCP (Cursor, Claude, VS Code, agentes customizados) e seus servidores MCP, oferecendo uma camada unificada de auth, policy e observabilidade.
 
-### MCP Studio (desenvolvimento)
-Um admin no-code + SDK para empacotar capacidades MCP como blocos reutilizáveis.
-
-<Callout type="info">
-  **Em breve:** este é o sucessor do admin SaaS atual, construído em cima do MCP Mesh.
-</Callout>
-
 ### MCP Apps & Store (distribuição)
 Um caminho para distribuir capacidades MCP-native reutilizáveis entre times (e eventualmente uma store).
 
diff --git a/apps/docs/client/src/content/pt-br/mcp-mesh/deploy/kubernetes-helm-chart.mdx b/apps/docs/client/src/content/pt-br/mcp-mesh/deploy/kubernetes-helm-chart.mdx
index 9952104397..9c266f57db 100644
--- a/apps/docs/client/src/content/pt-br/mcp-mesh/deploy/kubernetes-helm-chart.mdx
+++ b/apps/docs/client/src/content/pt-br/mcp-mesh/deploy/kubernetes-helm-chart.mdx
@@ -1,14 +1,14 @@
 ---
 title: "Kubernetes: Helm Chart"
-description: Deploy do MCP Mesh no Kubernetes usando o Helm chart
+description: Deploy do decocms no Kubernetes usando o Helm chart
 icon: Rocket
 ---
 
 import Callout from "../../../../components/ui/Callout.astro";
 
-Este guia explica como fazer deploy do MCP Mesh no Kubernetes usando o Helm chart.
+Este guia explica como fazer deploy do decocms no Kubernetes usando o Helm chart.
 
-Saiba mais: [página do MCP Mesh](https://www.decocms.com/mesh)
+Saiba mais: [página do decocms](https://www.decocms.com/mesh)
 
 Código-fonte do Helm chart: [decocms/helm-chart-deco-mcp-mesh](https://github.com/decocms/helm-chart-deco-mcp-mesh)
 
diff --git a/apps/docs/client/src/content/pt-br/mcp-mesh/deploy/local-docker-compose.mdx b/apps/docs/client/src/content/pt-br/mcp-mesh/deploy/local-docker-compose.mdx
index 33b04c5640..af3cef27ef 100644
--- a/apps/docs/client/src/content/pt-br/mcp-mesh/deploy/local-docker-compose.mdx
+++ b/apps/docs/client/src/content/pt-br/mcp-mesh/deploy/local-docker-compose.mdx
@@ -1,14 +1,14 @@
 ---
 title: "Local: Docker Compose"
-description: Deploy do MCP Mesh localmente usando Docker Compose para testes e desenvolvimento
+description: Deploy do decocms localmente usando Docker Compose para testes e desenvolvimento
 icon: Container
 ---
 
 import Callout from "../../../../components/ui/Callout.astro";
 
-Este guia cobre o deploy do MCP Mesh localmente usando Docker Compose para testes rápidos e desenvolvimento.
+Este guia cobre o deploy do decocms localmente usando Docker Compose para testes rápidos e desenvolvimento.
 
-Saiba mais: [página do MCP Mesh](https://www.decocms.com/mesh)
+Saiba mais: [página do decocms](https://www.decocms.com/mesh)
 
 Código-fonte (Docker Compose + README): [decocms/mesh/deploy](https://github.com/decocms/mesh/tree/main/deploy)
 
@@ -47,7 +47,7 @@ open http://localhost:3000
 ```
 
 <Callout type="tip">
-  Essas configurações são tudo que você precisa para começar a testar com o MCP-MESH. Se precisar de outras opções, confira as seções abaixo.
+  Essas configurações são tudo que você precisa para começar a testar com o decocms. Se precisar de outras opções, confira as seções abaixo.
 </Callout>
 
 ### Configuração Mínima
@@ -187,7 +187,7 @@ volumes:
 
 #### Quando é Carregado
 
-A aplicação Mesh carrega este arquivo na inicialização para configurar:
+A aplicação decocms carrega este arquivo na inicialização para configurar:
 
 - Autenticação por Email/Senha
 - Provedores sociais (Google, GitHub)
diff --git a/apps/docs/client/src/content/pt-br/mcp-mesh/overview.mdx b/apps/docs/client/src/content/pt-br/mcp-mesh/overview.mdx
index 15a961c739..47f89d90cc 100644
--- a/apps/docs/client/src/content/pt-br/mcp-mesh/overview.mdx
+++ b/apps/docs/client/src/content/pt-br/mcp-mesh/overview.mdx
@@ -1,14 +1,14 @@
 ---
 title: Visão geral
-description: O que é o MCP Mesh, o problema que ele resolve e as principais superfícies do produto
+description: O que é decocms, o problema que ele resolve e as principais superfícies do produto
 icon: Network
 ---
 
 import Callout from "../../../components/ui/Callout.astro";
 
-## O que é o MCP Mesh?
+## O que é decocms?
 
-O **MCP Mesh** é um **control plane para tráfego MCP**. Ele fica entre clientes MCP (Cursor, Claude Desktop, agentes) e servidores MCP, oferecendo uma camada centralizada de **autenticação, autorização, vault de credenciais e observabilidade**.
+**decocms** é um **control plane para tráfego MCP**. Ele fica entre clientes MCP (Cursor, Claude Desktop, agentes) e servidores MCP, oferecendo uma camada centralizada de **autenticação, autorização, vault de credenciais e observabilidade**.
 
 ## O problema
 
@@ -19,39 +19,39 @@ Quando MCP sai de alguns PoCs e vai para produção, os times começam a pagar u
 - **Pontos cegos operacionais**: falta um lugar único para ver logs/traces e depurar ponta a ponta
 - **Explosão de tools**: muitas tools aumentam contexto, latência e pioram a seleção de tool
 
-O Mesh centraliza isso uma vez, para você operar MCP como qualquer outra superfície de produção.
+decocms centraliza isso uma vez, para você operar MCP como qualquer outra superfície de produção.
 
 ## Arquitetura (alto nível)
 
 ```
 ┌───────────────────┐   ┌──────────────────┐   ┌────────────────────┐
-│ MCP Clients       │   │ MCP Mesh (Proxy) │   │ Downstream MCPs     │
+│ MCP Clients       │   │ decocms (Proxy)  │   │ Downstream MCPs     │
 │ - Cursor          │──▶│ - AuthN/AuthZ    │──▶│ - Slack / Gmail     │
 │ - Claude Desktop  │   │ - Vault          │   │ - Notion / Stripe   │
-│ - Custom agents   │   │ - Agents         │   │ - Seus MCP servers  │
+│ - Custom agents   │   │ - Virtual MCPs   │   │ - Seus MCP servers  │
 └───────────────────┘   │ - Monitoring     │   └────────────────────┘
                         └──────────────────┘
 ```
 
-## O que o Mesh centraliza
+## O que decocms centraliza
 
 - **Roteamento + execução**: qual MCP chamar e como autenticar
-- **Policy enforcement**: quem pode acessar quais tools (e via quais agents)
+- **Policy enforcement**: quem pode acessar quais tools (e via quais virtual MCPs)
 - **Observabilidade**: logs, latência, erros e contexto de requisição
-- **Runtime strategies (agents)**: diferentes estratégias de exposição de tools conforme a superfície cresce
+- **Runtime strategies (virtual MCPs)**: diferentes estratégias de exposição de tools conforme a superfície cresce
 
 ## Superfícies do produto (o que dá para fazer hoje)
 
 - **Store**: catálogo de Conexões para conectar (por padrão: o **MCP Registry** oficial).
 - **Conexões**: conectar e gerenciar MCP servers (endpoints MCP via HTTP).
-- **Agents**: publicar um "MCP virtual" curado que agrega tools/resources/prompts de múltiplas conexões.
+- **Virtual MCPs**: publicar um "MCP virtual" curado que agrega tools/resources/prompts de múltiplas conexões.
 - **API Keys**: criar chaves com permissões explícitas.
 - **Members & Roles**: convidar pessoas e gerenciar roles + permissões.
 - **Monitoring**: logs de tool calls, erros, latência, filtros e streaming.
 - **Deploy**: auto-hospedar localmente (npx / Docker Compose) ou em Kubernetes (Helm).
 
 <Callout type="info">
-  Estamos lançando o MCP Mesh para a comunidade open-source em **dezembro de 2025**.
+  Estamos lançando decocms para a comunidade open-source em **dezembro de 2025**.
   Ele ainda é novo: esta documentação reflete o que existe **em produção hoje**, mas estamos lançando features toda semana e vamos atualizar os docs conforme elas forem chegando.
 </Callout>
 
diff --git a/apps/docs/client/src/content/pt-br/mcp-mesh/mcp-gateways.mdx b/apps/docs/client/src/content/pt-br/mcp-mesh/virtual-mcps.mdx
similarity index 100%
rename from apps/docs/client/src/content/pt-br/mcp-mesh/mcp-gateways.mdx
rename to apps/docs/client/src/content/pt-br/mcp-mesh/virtual-mcps.mdx
diff --git a/apps/docs/client/src/content/pt-br/mcp-studio/overview.mdx b/apps/docs/client/src/content/pt-br/mcp-studio/overview.mdx
deleted file mode 100644
index ecd1f0c309..0000000000
--- a/apps/docs/client/src/content/pt-br/mcp-studio/overview.mdx
+++ /dev/null
@@ -1,32 +0,0 @@
----
-title: Visão Geral
-description: Admin no-code + SDK para empacotar capacidades MCP como blocos reutilizáveis (em breve)
-icon: LayoutDashboard
----
-
-import Callout from "../../../components/ui/Callout.astro";
-
-## O que é MCP Studio?
-
-**MCP Studio** é a camada de desenvolvimento do deco CMS: um **admin no-code + SDK** para empacotar capacidades MCP-native como blocos duráveis e reutilizáveis.
-
-Saiba mais: [página do MCP Studio](https://www.decocms.com/mcp-studio)
-
-Ele transforma **tools + schemas + workflows** em apps com:
-
-- Interfaces consistentes
-- Permissões e políticas explícitas
-- Versionamento e curadoria
-- Um caminho seguro para outros times adotarem o que funciona
-
-<Callout type="info">
-  **Em breve:** o MCP Studio está sendo construído em cima do **MCP Mesh** e vai substituir o admin SaaS legado (`admin.decocms.com`) ao longo do tempo (incluindo uma versão hospedada por nós).
-</Callout>
-
-## Onde isso se encaixa?
-
-- **O MCP Mesh (fundação):** conectar, governar e observar tráfego MCP
-- **MCP Studio (desenvolvimento):** empacotar e curar capacidades reutilizáveis
-- **MCP Apps & Store (distribuição):** distribuir o que funciona entre times
-
-
diff --git a/apps/docs/client/src/i18n/ui.ts b/apps/docs/client/src/i18n/ui.ts
index 9490d6c438..d3e83325c3 100644
--- a/apps/docs/client/src/i18n/ui.ts
+++ b/apps/docs/client/src/i18n/ui.ts
@@ -10,10 +10,16 @@ export const ui = {
     "head.title": "Deco - Docs",
     "sidebar.section.admin-decocms-com": "Legacy Admin",
     "sidebar.section.getting-started": "Getting Started",
+    "sidebar.section.core-concepts": "Core Concepts",
+    "sidebar.section.working-with-mcp": "Working with MCP",
+    "sidebar.section.decopilot": "Decopilot",
+    "sidebar.section.security": "Security & Access Control",
+    "sidebar.section.operations": "Operations & Deployment",
+    "sidebar.section.reference": "Reference",
     "sidebar.section.no-code-guides": "No-Code Guides",
     "sidebar.section.full-code-guides": "Full-Code Guides",
-    "sidebar.section.mcp-mesh": "MCP Mesh",
-    "sidebar.section.mcp-studio": "MCP Studio",
+    "sidebar.section.mcp-mesh": "decocms",
+    "sidebar.section.self-hosting": "Self-Hosting",
     "sidebar.section.deploy": "Deploy",
     "hero.title": "Build AI Agents That Connect Everything",
     "hero.subtitle":
@@ -28,10 +34,16 @@ export const ui = {
     "head.title": "Deco - Documentação",
     "sidebar.section.admin-decocms-com": "Admin Legado",
     "sidebar.section.getting-started": "Primeiros Passos",
+    "sidebar.section.core-concepts": "Conceitos Principais",
+    "sidebar.section.working-with-mcp": "Trabalhando com MCP",
+    "sidebar.section.decopilot": "Decopilot",
+    "sidebar.section.security": "Segurança e Controle de Acesso",
+    "sidebar.section.operations": "Operações e Implantação",
+    "sidebar.section.reference": "Referência",
     "sidebar.section.no-code-guides": "Guias No-Code",
     "sidebar.section.full-code-guides": "Guias Full-Code",
-    "sidebar.section.mcp-mesh": "MCP Mesh",
-    "sidebar.section.mcp-studio": "MCP Studio",
+    "sidebar.section.mcp-mesh": "decocms",
+    "sidebar.section.self-hosting": "Auto-Hospedagem",
     "sidebar.section.deploy": "Deploy",
     "hero.title": "Construa Agentes de IA Que Conectam Tudo",
     "hero.subtitle":
diff --git a/apps/docs/client/src/layouts/DocsLayout.astro b/apps/docs/client/src/layouts/DocsLayout.astro
index e2bf34c17b..0b4a6bfaac 100644
--- a/apps/docs/client/src/layouts/DocsLayout.astro
+++ b/apps/docs/client/src/layouts/DocsLayout.astro
@@ -353,12 +353,13 @@ const editUrl = doc
         root.render(
           React.createElement("div", { className: "flex items-center gap-2" }, [
             React.createElement(LanguageSelector, {
+              key: "language-selector",
               locale:
                 document.querySelector("nav")?.getAttribute("data-locale") ||
                 "en",
               className: "w-32",
             }),
-            React.createElement(ThemeToggle),
+            React.createElement(ThemeToggle, { key: "theme-toggle" }),
           ])
         );
       }
diff --git a/apps/docs/client/src/pages/[locale]/[...slug].astro b/apps/docs/client/src/pages/[locale]/[...slug].astro
index f94bada716..a54db2418f 100644
--- a/apps/docs/client/src/pages/[locale]/[...slug].astro
+++ b/apps/docs/client/src/pages/[locale]/[...slug].astro
@@ -43,9 +43,9 @@ if (slug === "getting-started/context-engineers") {
   return Astro.redirect(`/${lang}/getting-started/developers`);
 }
 
-// Redirect to introduction if no document is found (i.e., when visiting /en)
+// Redirect to quickstart if no document is found (i.e., when visiting /en)
 if (!doc) {
-  return Astro.redirect(`/${lang}/introduction`);
+  return Astro.redirect(`/${lang}/mcp-mesh/quickstart`);
 }
 ---
 
diff --git a/apps/docs/client/src/utils/navigation.ts b/apps/docs/client/src/utils/navigation.ts
index 5b676c92b4..9e51c4da5c 100644
--- a/apps/docs/client/src/utils/navigation.ts
+++ b/apps/docs/client/src/utils/navigation.ts
@@ -15,23 +15,57 @@ export async function getNavigationLinks(
 
   // Define the correct order for navigation
   const order = [
-    "introduction",
-    // MCP Mesh (product docs)
-    "mcp-mesh/overview",
+    // 1. Quickstart & Overview
     "mcp-mesh/quickstart",
-    "mcp-mesh/concepts",
-    "mcp-mesh/connect-clients",
-    "mcp-mesh/authentication",
-    "mcp-mesh/authorization-and-roles",
-    "mcp-mesh/mcp-servers",
-    "mcp-mesh/mcp-gateways",
-    "mcp-mesh/api-keys",
-    "mcp-mesh/monitoring",
-    "mcp-mesh/api-reference",
-    "mcp-mesh/deploy/local-docker-compose",
-    "mcp-mesh/deploy/kubernetes-helm-chart",
+    "mcp-mesh/overview",
+
+    // 2. Getting Started
     "getting-started/ai-builders",
     "getting-started/developers",
+
+    // 4. Core Concepts
+    "mcp-mesh/concepts",
+
+    // 5. Working with MCP
+    "mcp-mesh/connections",
+    "mcp-mesh/virtual-mcps",
+    "mcp-mesh/projects",
+    "mcp-mesh/agents",
+
+    // 6. Decopilot
+    "mcp-mesh/decopilot/overview",
+    "mcp-mesh/decopilot/quickstart",
+    "mcp-mesh/decopilot/context",
+    "mcp-mesh/decopilot/tasks-and-spawning",
+    "mcp-mesh/decopilot/tools",
+    "mcp-mesh/decopilot/scopes",
+    "mcp-mesh/decopilot/architecture",
+
+    // 7. Monitoring & Observability
+    "mcp-mesh/monitoring",
+
+    // 8. User Management
+    "mcp-mesh/api-keys",
+    "mcp-mesh/user-management",
+
+    // 9. API Reference
+    "mcp-mesh/api-reference/connection-proxy",
+    "mcp-mesh/api-reference/built-in-tools",
+    "mcp-mesh/api-reference/built-in-tools/tool-search",
+    "mcp-mesh/api-reference/built-in-tools/tool-enable",
+    "mcp-mesh/api-reference/built-in-tools/agent-search",
+    "mcp-mesh/api-reference/built-in-tools/subtask-run",
+    "mcp-mesh/api-reference/built-in-tools/user-ask",
+    "mcp-mesh/api-reference/built-in-tools/resource-read",
+    "mcp-mesh/api-reference/built-in-tools/prompt-read",
+
+    // 10. Self-Hosting
+    "mcp-mesh/self-hosting/quickstart",
+    "mcp-mesh/self-hosting/authentication",
+    "mcp-mesh/self-hosting/deploy/docker-compose",
+    "mcp-mesh/self-hosting/deploy/kubernetes",
+
+    // 11. Legacy Admin Guides (no-code and full-code guides)
     "no-code-guides/creating-tools",
     "no-code-guides/creating-agents",
     "full-code-guides/project-structure",