docs: comprehensive documentation restructuring and improvements

[tlgimenes]

What is this contribution about?

This PR implements a comprehensive documentation restructuring and improvement initiative across the entire documentation site. The changes focus on three main areas:

1. Branding & Consistency - Updated all references from "decocms" to "deco CMS" throughout the documentation, ensuring consistent branding and capitalization.

2. Documentation Restructuring - Reorganized navigation structure, simplified page titles, consolidated content, and improved information architecture for better user experience.

3. Example Focus Shift - Replaced generic DevOps/tech examples (GitHub, deployments, Slack notifications) with concrete e-commerce scenarios (Shopify orders, inventory management, fulfillment operations) to make documentation more accessible and relatable.

4. Decopilot Quickstart Redesign - Complete rewrite of the quickstart guide with progressive learning approach, focusing on practical usage for non-technical e-commerce teams (designers, content creators, project managers) rather than technical implementation details.

5. Technical Fixes - Resolved SSR hydration issues in DocsLayout component and improved sidebar structure.

Key Changes:

• NEW: Decopilot quickstart redesigned - Progressive learning structure (simple requests → subtasks → agents → context → scopes) with ASCII art conversation examples instead of code
• Updated all built-in tools API reference with e-commerce examples (subtask-run, tool-enable, tool-search)
• Updated Decopilot documentation examples (overview, tools) to use e-commerce scenarios
• Updated Virtual MCPs documentation with e-commerce workflow examples
• Updated all MCP Mesh documentation with e-commerce focused examples (agents, projects, virtual MCPs)
• Revised code guides with practical e-commerce tool examples (order confirmation, inventory checks, payment processing)
• Restructured API reference documentation with improved navigation
• Simplified Decopilot documentation for non-technical users
• Added comprehensive self-hosting guides
• Fixed React hydration issues and added proper keys to components
• Updated landing page redirect to quickstart for better first-time user experience

Screenshots/Demonstration

N/A - Documentation changes only

How to Test

1. Run the documentation site locally: bun run docs:dev
2. Navigate through the main sections:
   • Decopilot Quickstart: Verify the new progressive learning structure is clear and examples are easy to follow
   • Built-in Tools API Reference: Check that examples use e-commerce scenarios (inventory, orders, shipping)
   • MCP Mesh section: Verify agents, projects, and virtual MCPs pages render correctly with e-commerce examples
   • Full Code Guides: Check building-tools.mdx and building-views.mdx for updated e-commerce examples
   • No Code Guides: Review creating-tools.mdx for consistent example updates
3. Verify navigation structure is logical and pages load without hydration errors
4. Check that all internal links work correctly
5. Confirm branding is consistent (deco CMS vs decocms)
6. Verify ASCII art conversation examples in quickstart render properly

Migration Notes

N/A - Documentation only changes, no migrations required

Review Checklist

• PR title is clear and descriptive
• Changes are tested and working (all QA checks passed: fmt, lint, check:ci, knip, test)
• Documentation is updated (this PR IS the documentation update)
• No breaking changes

[cubic-dev-ai]

2 issues found across 28 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="apps/docs/client/src/content/en/mcp-mesh/deploy/kubernetes-helm-chart.mdx">

<violation number="1" location="apps/docs/client/src/content/en/mcp-mesh/deploy/kubernetes-helm-chart.mdx:3">
P2: These lines rename the target to “decocms,” but the rest of the document (and the linked URL) is about MCP Mesh. This inconsistency will confuse readers about which product the Helm chart deploys. Keep the MCP Mesh naming here to match the chart and the rest of the guide.</violation>

<violation number="2" location="apps/docs/client/src/content/en/mcp-mesh/deploy/kubernetes-helm-chart.mdx:11">
P3: The link text now says “decocms product page,” but the URL points to the MCP Mesh page (/mesh). Use MCP Mesh terminology here to match the destination and the rest of the page.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx">

<violation number="1" location="apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx:42">
P3: The new statement says there’s no inheritance between scopes, but the Context page explicitly documents org/project/agent inheritance of CLAUDE.md and other context. This contradiction can mislead readers about how scopes work.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

4 issues found across 32 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx">

<violation number="1" location="apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx:11">
P2: The URL includes a space (`deco CMS.com`), which makes the hostname invalid and breaks the link. Use the correct domain without spaces.</violation>
</file>

<file name="apps/docs/client/src/content/en/mcp-mesh/connections.mdx">

<violation number="1" location="apps/docs/client/src/content/en/mcp-mesh/connections.mdx:130">
P2: The Agent endpoint path is documented as `/mcp/agent/:agentId`, but the API routes use `/mcp/virtual-mcp/:virtualMcpId` (with `/mcp/gateway/:virtualMcpId` for backward compatibility). This will send readers to a non-existent endpoint.</violation>
</file>

<file name="apps/docs/client/src/content/en/mcp-mesh/api-keys.mdx">

<violation number="1" location="apps/docs/client/src/content/en/mcp-mesh/api-keys.mdx:50">
P3: The example URL contains a space in the hostname, which makes it invalid. Use a valid hostname (no spaces) so users can copy the snippet.</violation>
</file>

<file name="apps/docs/client/src/components/ui/Sidebar.tsx">

<violation number="1" location="apps/docs/client/src/components/ui/Sidebar.tsx:169">
P2: File nodes that have children become non-navigable because they render as a toggle-only button. Users can no longer click into the section’s overview page. Consider keeping a link for file nodes even when they’re collapsible, and use a separate control for expansion.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}