docs: refactor sidebar navigation, rename "Context Engineers" to "Developers", and expand Mesh deployment guides. (#2080)

* Added MCP mesh deploy docs to deco CMS docs

* Update documentation and navigation for MCP Mesh and Studio

- Refactored sidebar component to prioritize MCP Mesh and Studio documentation.
- Updated package.json scripts for documentation deployment.
- Removed outdated context engineers documentation and redirected to developers.
- Enhanced introduction and deployment guides for clarity and added official links.
- Improved navigation links to reflect recent changes in documentation structure.

* Update PostgreSQL connection examples in local Docker Compose documentation

- Changed `DATABASE_URL` examples to use service name `postgres` instead of `localhost` for containerized PostgreSQL.
- Updated local PostgreSQL example to use `host.docker.internal` for better compatibility with Docker Desktop.
- Added a callout note clarifying the use of `localhost` within containers and connection instructions for local and remote PostgreSQL setups.

Author: cecilia-marques

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

@@ -176,12 +176,11 @@ function groupLegacyAdminSections(nodes: TreeNode[]): TreeNode[] {
         }
       : null;
 
-  // Keep legacy guides grouped and listed before Mesh/Studio.
-  // This also ensures Mesh isn't forced to the top by this grouping layer.
+  // Put MCP Mesh and MCP Studio at the top, then group legacy docs under Legacy Admin.
   const next: TreeNode[] = [...files];
-  if (legacyFolder) next.push(legacyFolder);
   if (mcpMesh) next.push(mcpMesh);
   if (mcpStudio) next.push(mcpStudio);
+  if (legacyFolder) next.push(legacyFolder);
   return next;
 }
 

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

@@ -130,7 +130,9 @@ function TreeItem({
         }`}
       >
         {/* Indentation spacer for nested items */}
-        {node.depth > 1 && <div className="w-6 shrink-0" />}
+        {node.depth > 0 && (
+          <div className="shrink-0" style={{ width: `${node.depth * 24}px` }} />
+        )}
 
         {/* Icon */}
         {node.type === "folder" ? (
@@ -243,35 +245,21 @@ function TreeList({
           needsSeparator = true;
         }
 
-        // Add section title for root folders
-        const needsSectionTitle = node.type === "folder" && node.depth === 0; // All root folders get section titles
-
         return (
           <React.Fragment key={node.id}>
             {needsSeparator && (
               <li className="my-3">
                 <div className="h-px bg-border/50" />
               </li>
             )}
-            {needsSectionTitle && (
-              <li className="mt-3 first:mt-0">
-                <div className="px-3 py-2">
-                  <h3 className="text-sm font-medium text-foreground">
-                    {translations[`sidebar.section.${node.name}`] || node.name}
-                  </h3>
-                </div>
-              </li>
-            )}
-            {!needsSectionTitle && (
-              <TreeItem
-                node={node}
-                isVisible={isVisible}
-                isExpanded={isExpanded}
-                onToggle={onToggle}
-                locale={locale}
-                translations={translations}
-              />
-            )}
+            <TreeItem
+              node={node}
+              isVisible={isVisible}
+              isExpanded={isExpanded}
+              onToggle={onToggle}
+              locale={locale}
+              translations={translations}
+            />
           </React.Fragment>
         );
       })}
@@ -289,10 +277,35 @@ export default function Sidebar({ tree, locale, translations }: SidebarProps) {
     );
     const initialState = new Map();
 
-    // Initialize tree state - default to expanded
+    // 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("/"));
+    }
+
+    // Initialize tree state - default to expanded (with a few collapsed-by-default sections)
     tree.forEach((node) => {
       if (node.type === "folder") {
-        initialState.set(node.id, savedState[node.id] !== false);
+        const saved = savedState[node.id];
+        // Default: show "Legacy Admin" open, but keep its sections closed (as a compact TOC).
+        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,
+        );
       }
     });
 

…en/getting-started/context-engineers.mdx …ontent/en/getting-started/developers.mdxapps/docs/client/src/content/en/getting-started/context-engineers.mdx renamed to apps/docs/client/src/content/en/getting-started/developers.mdx apps/docs/client/src/content/en/getting-started/context-engineers.mdx renamed to apps/docs/client/src/content/en/getting-started/developers.mdx

@@ -1,5 +1,5 @@
 ---
-title: For Context Engineers
+title: For Developers
 description: Set up your local development environment and deploy your first MCP server
 icon: Code
 ---
@@ -23,15 +23,15 @@ npm install
 deco login
 ```
 
-Opens browser for authentication. You can create a new account if you don’t have one. 
+Opens browser for authentication. You can create a new account if you don’t have one.
 
 ### Local Development
 
 ```bash
 npm run dev
 ```
 
-Starts local server on port 8787 with hot reload enabled. The preview URL is accessible anywhere now. 
+Starts local server on port 8787 with hot reload enabled. The preview URL is accessible anywhere now.
 
 ### Project Structure
 
@@ -49,11 +49,12 @@ The server serves both:
 ### Deploy
 
 When you are ready to share your MCP:
+
 ```bash
 npm run deploy
 ```
 
-This builds and deploys your MCP app to Cloudflare Workers, making it available on your organization's private registry. 
+This builds and deploys your MCP app to Cloudflare Workers, making it available on your organization's private registry.
 
 ## Understanding the Current Workflow
 
@@ -108,3 +109,5 @@ deco project import --from ./my-project --org <org>
 **Get Help:** [Discord](https://decocms.com/discord)
 
 **Non-developer?** See [For AI Builders](/en/getting-started/ai-builders) for no-code workflow.
+
+

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

@@ -8,30 +8,51 @@ import Callout from "../../components/ui/Callout.astro";
 
 ![deco](https://assets.decocache.com/mcp/9a3facd8-1199-4635-becc-bdc3f5ee7ab1/deco-banner-capy.png)
 
-## Welcome
-
-These docs are primarily **developer docs** for **MCP Mesh** and the broader **deco CMS** platform.
-
 ## 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.
+If MCP is the standard interface for tool access, deco CMS is the **production layer around it**: connect MCP servers, enforce governance, and get observability as usage scales across teams and environments. The broader platform also includes a **builder framework** (MCP Studio — coming soon, replacing the legacy admin) and **distribution capabilities** (pre-built modules and store).
+
+**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).
+
+## Quick start (Mesh)
+
+### Option A: one-command local Mesh setup
+
+```bash
+npx @decocms/mesh init
+```
+
+### Option B: run from source
+
+```bash
+git clone https://github.com/decocms/mesh.git
+cd mesh
+bun install
+bun run dev
+```
+
+## Deploy (Mesh)
+
+- **[Local: Docker Compose](/en/mcp-mesh/deploy/local-docker-compose)**
+- **[Kubernetes: Helm Chart](/en/mcp-mesh/deploy/kubernetes-helm-chart)**
 
 <Callout type="warning">
   **Docs split (quick guide):**
 
-  - **MCP Mesh** → Self-hosting, deploying, and operating the Mesh (recommended).
+  - **The MCP Mesh** → Self-hosting, deploying, and operating the Mesh (recommended).
   - **Legacy Admin** → If you’re using `admin.decocms.com` (still supported, **deprecated soon**).
 
   We’re launching **MCP Studio** (on top of Mesh), which will bring the current SaaS admin capabilities to the Mesh (including a hosted option by us) and replace the legacy SaaS over time.
 </Callout>
 
-## Start here (most common paths)
-
-- **[Deploy MCP Mesh locally (Docker Compose)](/en/mcp-mesh/deploy/local-docker-compose)**
-- **[Deploy MCP Mesh on Kubernetes (Helm)](/en/mcp-mesh/deploy/kubernetes-helm-chart)**
-
 ## Problem (and what the Mesh fixes)
 
 When AI moves from demos to production, teams usually hit the same constraints:
@@ -41,18 +62,18 @@ When AI moves from demos to production, teams usually hit the same constraints:
 - **Operational blind spots**: debugging is slow; failures and costs are hard to trace end-to-end
 - **Context obesity**: bloated prompts and tool lists degrade quality and increase cost
 
-MCP Mesh centralizes those cross-cutting concerns **once** so you don’t rebuild them in every agent/app.
+The MCP Mesh centralizes those cross-cutting concerns **once** so you don’t rebuild them in every agent/app.
 
 ## Platform structure: Mesh → Studio → Distribution
 
-### MCP Mesh (foundation)
+### 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 MCP Mesh.
+  **Coming soon:** This is the successor to the current SaaS admin, built on top of the MCP Mesh.
 </Callout>
 
 ### MCP Apps & Store (distribution)
@@ -73,26 +94,9 @@ MCP gives you a standard interface. deco CMS provides the **control plane** arou
 - **Auditable**: centralized policies, logs, and traces across tool + model calls
 - **No lock-in**: your context, your infrastructure
 
-## Quick start
-
-### Option A: one-command local Mesh setup
-
-```bash
-npx @decocms/mesh init
-```
-
-### Option B: run from source
-
-```bash
-git clone https://github.com/decocms/mesh.git
-cd mesh
-bun install
-bun run dev
-```
-
 ## 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 Context Engineers](/en/getting-started/context-engineers)**
+- **[For Developers](/en/getting-started/developers)**