From 132444b49658d3052d022820e1b90d17034150b2 Mon Sep 17 00:00:00 2001
From: Vanshika-Rana <ranavanshika172000@gmail.com>
Date: Tue, 30 Jun 2026 22:49:38 +0530
Subject: [PATCH 1/2] docs: fix ZCP dark mode and sidebar, embed coding agents
 video, add GitHub lifecycle automation

---
 apps/docs/.env.sample                         |   3 +-
 apps/docs/content/features/coding-agents.mdx  |  14 ++
 .../content/references/github-integration.mdx |  45 +++-
 apps/docs/docusaurus.config.js                |  12 +-
 apps/docs/sidebars.js                         |   4 +
 apps/docs/src/css/custom.css                  | 104 ++++++++-
 .../theme/DocSidebarItem/Category/index.tsx   |  43 ++++
 yarn.lock                                     | 205 +-----------------
 8 files changed, 210 insertions(+), 220 deletions(-)

diff --git a/apps/docs/.env.sample b/apps/docs/.env.sample
index c681af3ec..80463d2b6 100644
--- a/apps/docs/.env.sample
+++ b/apps/docs/.env.sample
@@ -7,4 +7,5 @@ AI_ASSISTANT_URL=
 AI_API_ASSISTANT_TOKEN=
 AI_WEBSITE_ID=
 AI_API_ASSISTANT_RECAPTCHA_SITE_KEY=
-CLOUDINARY_CLOUD_NAME=
\ No newline at end of file
+CLOUDINARY_CLOUD_NAME=
+GTAG_TRACKING_ID=
\ No newline at end of file
diff --git a/apps/docs/content/features/coding-agents.mdx b/apps/docs/content/features/coding-agents.mdx
index d956ab9c6..4f581d3bc 100644
--- a/apps/docs/content/features/coding-agents.mdx
+++ b/apps/docs/content/features/coding-agents.mdx
@@ -9,6 +9,20 @@ import IntroAgentVisual from '@site/src/components/IntroAgentVisual';
 
 Zerops was built on the idea of **environment parity** — giving developers the full development lifecycle, from remote development to highly available production, with the observability and developer tools for maximum flexibility, and sensible defaults so the configs stay reasonable. Turns out that's **exactly what coding agents need** to produce and iterate on production-ready applications.
 
+<div className="w-full flex justify-center my-4">
+  <iframe
+    width="560"
+    height="315"
+    src="https://www.youtube.com/embed/spdmTicsIgg?si=laZjTGhiytJRkqoJ"
+    title="YouTube video player"
+    frameBorder="0"
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+    referrerPolicy="strict-origin-when-cross-origin"
+    allowFullScreen
+    className="w-full max-w-[560px] aspect-video rounded-xl"
+  />
+</div>
+
 <br/>
 
 ## What is it
diff --git a/apps/docs/content/references/github-integration.mdx b/apps/docs/content/references/github-integration.mdx
index 46d4844b3..affa49b31 100644
--- a/apps/docs/content/references/github-integration.mdx
+++ b/apps/docs/content/references/github-integration.mdx
@@ -106,25 +106,25 @@ As an alternative to direct integration, you can use GitHub Actions to manage yo
 1. **Create Workflow Configuration**
 
    Create a new file at `.github/workflows/deploy.yaml` in your repository:
-   
+
    Basic example:
 
    ```yaml
    name: Deploy to Zerops
-   
+
    on:
      push:
        branches:
          - main
-   
+
    jobs:
      deploy:
        runs-on: ubuntu-latest
-   
+
        steps:
          - name: Checkout code
            uses: actions/checkout@v7
-   
+
          - name: Deploy with Zerops
            uses: zeropsio/actions@main
            with:
@@ -133,14 +133,14 @@ As an alternative to direct integration, you can use GitHub Actions to manage yo
    ```
 
    Example with tag matching:
-   
+
    ```yaml
    name: Deploy to Zerops on Tag
 
    on:
      push:
        tags:
-         - 'v[0-9]+\.[0-9]+\.[0-9]+'  # Example: v1.0.0, v2.3.4
+         - 'v[0-9]+\.[0-9]+\.[0-9]+' # Example: v1.0.0, v2.3.4
 
    jobs:
      deploy:
@@ -179,3 +179,34 @@ Keep your access token secure and never commit it directly to your repository. T
 :::
 
 For more information about GitHub Actions, refer to the [official GitHub Actions documentation](https://docs.github.com/en/actions).
+
+---
+
+## Advanced: Full Lifecycle Automation
+
+:::tip Reference repository
+A complete, working example of this pattern is available at [zerops-showcase-deploy](https://github.com/zeropsio/zerops-showcase-deploy), a deployment orchestrator built entirely on GitHub Actions and the Zerops API, no Zerops CLI required. Clone it as a starting point for your own multi-environment pipeline.
+:::
+
+The workflow above deploys a single service on push to one branch. This reference repo extends that into a full lifecycle: every feature branch gets its own isolated environment, every PR gets a preview, and stage and prod stay permanent with their data intact across deploys.
+
+### What it sets up
+
+| You do this                 | Pipeline creates                                   | Lifetime                    |
+| --------------------------- | -------------------------------------------------- | --------------------------- |
+| Push to a feature branch    | A full isolated environment                        | Until the branch is deleted |
+| Open/update a PR to `stage` | A full isolated preview environment                | Until the PR is closed      |
+| Merge a PR into `stage`     | Redeploys app code to the shared stage environment | Permanent, data preserved   |
+| Push/merge to `main`        | Redeploys app code to production                   | Permanent, data preserved   |
+
+Permanent environments keep their databases, caches, queues, and storage across every deploy, only the application code gets updated. Ephemeral environments are created from scratch and torn down automatically when no longer needed, so every developer gets their own isolated copy of the full stack without manual cleanup.
+
+PR previews require a `stage` branch as the pull request target; the repo's setup guide covers creating it.
+
+### How it differs from the basic workflow above
+
+The basic GitHub Actions setup deploys one service to one Zerops project. This pattern manages entire **projects** programmatically instead: it checks whether a project for a given branch or PR already exists, creates one from an import template if not, and deploys to it. The key safeguard is that it never deletes or recreates infrastructure on permanent environments, only ephemeral ones get torn down. This is a reference implementation, not a Zerops-managed service, so you own the repo, the GitHub Actions minutes, and the Zerops API calls it makes on your behalf.
+
+:::tip Full setup guide
+Required secrets, customizing the project template for your own services, and the complete workflow reference are all covered in the [repo's README](https://github.com/zeropsio/zerops-showcase-deploy#readme).
+:::
diff --git a/apps/docs/docusaurus.config.js b/apps/docs/docusaurus.config.js
index aac6502b1..b4f9fd166 100644
--- a/apps/docs/docusaurus.config.js
+++ b/apps/docs/docusaurus.config.js
@@ -4,6 +4,8 @@ import { themes as prismThemes } from "prism-react-renderer"
 const reverseSidebar = require("./src/utils/reverse-sidebar")
 const excludeSidebarResults = require("./src/utils/exclude-sidebar-results")
 
+const gtagTrackingId = process.env.GTAG_TRACKING_ID
+
 /** @type {import('@medusajs/docs').MedusaDocusaurusConfig} */
 const config = {
   title: "Zerops",
@@ -250,9 +252,13 @@ const config = {
         theme: {
           customCss: require.resolve("./src/css/custom.css"),
         },
-        gtag: {
-          trackingID: "xxx",
-        },
+        ...(gtagTrackingId
+          ? {
+              gtag: {
+                trackingID: gtagTrackingId,
+              },
+            }
+          : {}),
         sitemap: {
           filename: "sitemap-docs.xml",
           ignorePatterns: ["/guides/**"],
diff --git a/apps/docs/sidebars.js b/apps/docs/sidebars.js
index b6c4ff87b..ef11b68e6 100644
--- a/apps/docs/sidebars.js
+++ b/apps/docs/sidebars.js
@@ -633,6 +633,7 @@ module.exports = {
         {
           type: 'category',
           label: 'Remote or local setup',
+          collapsed: true,
           link: {
             type: 'doc',
             id: 'zcp/setup/choose-workspace',
@@ -657,6 +658,7 @@ module.exports = {
         {
           type: 'category',
           label: 'Build and ship',
+          collapsed: true,
           link: {
             type: 'doc',
             id: 'zcp/workflows/build-with-zcp',
@@ -681,6 +683,7 @@ module.exports = {
         {
           type: 'category',
           label: 'Security',
+          collapsed: true,
           link: {
             type: 'doc',
             id: 'zcp/security/trust-model',
@@ -705,6 +708,7 @@ module.exports = {
         {
           type: 'category',
           label: 'Reference',
+          collapsed: true,
           link: {
             type: 'doc',
             id: 'zcp/reference/index',
diff --git a/apps/docs/src/css/custom.css b/apps/docs/src/css/custom.css
index 2bfb0e819..24bc738c2 100644
--- a/apps/docs/src/css/custom.css
+++ b/apps/docs/src/css/custom.css
@@ -576,6 +576,12 @@ html[data-theme='dark'] .zcp-agent-flow__node--proof {
 }
 
 html[data-theme='dark'] .zcp-lifecycle-stage {
+  background: rgba(24, 24, 27, 0.72);
+  border-color: rgba(63, 63, 70, 0.8);
+  color: #f8fafc;
+}
+
+html[data-theme='dark'] .zcp-lifecycle-stage h3 {
   color: #f8fafc;
 }
 
@@ -583,6 +589,14 @@ html[data-theme='dark'] .zcp-lifecycle-stage p {
   color: #cbd5e1;
 }
 
+html[data-theme='dark'] .zcp-lifecycle-stage li {
+  color: #cbd5e1;
+}
+
+html[data-theme='dark'] .zcp-lifecycle-stage::after {
+  color: #9ca3af;
+}
+
 html[data-theme='dark'] .zcp-lifecycle-stage--infra {
   background: rgba(20, 83, 45, 0.22);
 }
@@ -697,13 +711,91 @@ html[data-theme='dark'] .zcp-lifecycle-stage--delivery {
   .zcp-claim-callout { grid-column: 1 / -1; padding: 1.15rem 1.25rem; }
 }
 
-html[data-theme='dark'] .zcp-claim-card { color: #f8fafc; }
+html[data-theme='dark'] .zcp-claim-card {
+  background: rgba(24, 24, 27, 0.72);
+  border-color: rgba(63, 63, 70, 0.8);
+  color: #f8fafc;
+}
+
+html[data-theme='dark'] .zcp-claim-card h3 {
+  color: #f8fafc;
+}
+
+html[data-theme='dark'] .zcp-claim-card a {
+  color: #93c5fd;
+}
+
 html[data-theme='dark'] .zcp-claim-card p,
-html[data-theme='dark'] .zcp-claim-card span { color: #cbd5e1; }
-html[data-theme='dark'] .zcp-claim-card--services { background: rgba(20, 83, 45, 0.22); }
-html[data-theme='dark'] .zcp-claim-card--deploy   { background: rgba(76, 29, 149, 0.22); }
-html[data-theme='dark'] .zcp-claim-card--stack    { background: rgba(30, 58, 138, 0.22); }
-html[data-theme='dark'] .zcp-claim-card--handover { background: rgba(120, 53, 15, 0.2); }
+html[data-theme='dark'] .zcp-claim-card span {
+  color: #cbd5e1;
+}
+
+html[data-theme='dark'] .zcp-claim-card--services { background: rgba(20, 83, 45, 0.22); border-color: rgba(50, 132, 90, 0.35); }
+html[data-theme='dark'] .zcp-claim-card--deploy   { background: rgba(76, 29, 149, 0.22); border-color: rgba(113, 87, 217, 0.35); }
+html[data-theme='dark'] .zcp-claim-card--stack    { background: rgba(30, 58, 138, 0.22); border-color: rgba(45, 114, 217, 0.35); }
+html[data-theme='dark'] .zcp-claim-card--handover { background: rgba(120, 53, 15, 0.2); border-color: rgba(196, 127, 23, 0.35); }
+
+/* ZCP mermaid flowcharts (how-it-works classDef nodes) */
+
+html[data-theme='dark'] .mermaid .node.user > rect,
+html[data-theme='dark'] .mermaid .node.user > polygon,
+html[data-theme='dark'] .mermaid .node.user > path {
+  fill: rgba(30, 58, 138, 0.35) !important;
+  stroke: #60a5fa !important;
+}
+
+html[data-theme='dark'] .mermaid .node.zcpbox > rect,
+html[data-theme='dark'] .mermaid .node.zcpbox > polygon,
+html[data-theme='dark'] .mermaid .node.zcpbox > path {
+  fill: rgba(20, 83, 45, 0.3) !important;
+  stroke: #4ade80 !important;
+}
+
+html[data-theme='dark'] .mermaid .node.work > rect,
+html[data-theme='dark'] .mermaid .node.work > polygon,
+html[data-theme='dark'] .mermaid .node.work > path {
+  fill: rgba(120, 53, 15, 0.28) !important;
+  stroke: #fbbf24 !important;
+}
+
+html[data-theme='dark'] .mermaid .node.done > rect,
+html[data-theme='dark'] .mermaid .node.done > polygon,
+html[data-theme='dark'] .mermaid .node.done > path {
+  fill: rgba(76, 29, 149, 0.28) !important;
+  stroke: #a78bfa !important;
+}
+
+html[data-theme='dark'] .mermaid .node.stop > rect,
+html[data-theme='dark'] .mermaid .node.stop > polygon,
+html[data-theme='dark'] .mermaid .node.stop > path {
+  fill: rgba(127, 29, 29, 0.28) !important;
+  stroke: #f87171 !important;
+}
+
+html[data-theme='dark'] .mermaid .node.user .label,
+html[data-theme='dark'] .mermaid .node.zcpbox .label,
+html[data-theme='dark'] .mermaid .node.work .label,
+html[data-theme='dark'] .mermaid .node.done .label,
+html[data-theme='dark'] .mermaid .node.stop .label {
+  color: #f8fafc !important;
+}
+
+html[data-theme='dark'] .mermaid .node.user .label span,
+html[data-theme='dark'] .mermaid .node.zcpbox .label span,
+html[data-theme='dark'] .mermaid .node.work .label span,
+html[data-theme='dark'] .mermaid .node.done .label span,
+html[data-theme='dark'] .mermaid .node.stop .label span {
+  color: #f8fafc !important;
+}
+
+html[data-theme='dark'] .mermaid .node.user .label code,
+html[data-theme='dark'] .mermaid .node.zcpbox .label code,
+html[data-theme='dark'] .mermaid .node.work .label code,
+html[data-theme='dark'] .mermaid .node.done .label code,
+html[data-theme='dark'] .mermaid .node.stop .label code {
+  background: rgba(15, 23, 42, 0.55);
+  color: #e2e8f0;
+}
 
 /* gap objection cards */
 
diff --git a/apps/docs/src/theme/DocSidebarItem/Category/index.tsx b/apps/docs/src/theme/DocSidebarItem/Category/index.tsx
index 4cc9d6ed0..78259b0ac 100644
--- a/apps/docs/src/theme/DocSidebarItem/Category/index.tsx
+++ b/apps/docs/src/theme/DocSidebarItem/Category/index.tsx
@@ -14,6 +14,7 @@ import {
   isSamePath,
 } from '@docusaurus/theme-common/internal';
 import Link from '@docusaurus/Link';
+import { useLocation } from '@docusaurus/router';
 import { translate } from '@docusaurus/Translate';
 import useIsBrowser from '@docusaurus/useIsBrowser';
 import DocSidebarItems from '@theme/DocSidebarItems';
@@ -46,6 +47,42 @@ function useAutoExpandActiveCategory({
   }, [isActive, wasActive, collapsed, updateCollapsed]);
 }
 
+// Collapse a category when navigation leaves it (e.g. Reference → Overview).
+function useAutoCollapseInactiveCategory({
+  isActive,
+  collapsed,
+  updateCollapsed,
+  collapsible,
+}: {
+  isActive: boolean;
+  collapsed: boolean;
+  updateCollapsed: (b: boolean) => void;
+  collapsible: boolean;
+}) {
+  const { pathname } = useLocation();
+  const wasActive = usePrevious(isActive);
+  const previousPathname = usePrevious(pathname);
+  useEffect(() => {
+    if (!collapsible || collapsed || isActive) {
+      return;
+    }
+    const routeChanged =
+      previousPathname !== undefined && previousPathname !== pathname;
+    const justBecameInactive = !isActive && wasActive;
+    if (justBecameInactive || routeChanged) {
+      updateCollapsed(true);
+    }
+  }, [
+    isActive,
+    wasActive,
+    collapsed,
+    updateCollapsed,
+    collapsible,
+    pathname,
+    previousPathname,
+  ]);
+}
+
 /**
  * When a collapsible category has no link, we still link it to its first child
  * during SSR as a temporary fallback. This allows to be able to navigate inside
@@ -134,6 +171,12 @@ export default function DocSidebarItemCategory({
     setCollapsed(toCollapsed);
   };
   useAutoExpandActiveCategory({ isActive, collapsed, updateCollapsed });
+  useAutoCollapseInactiveCategory({
+    isActive,
+    collapsed,
+    updateCollapsed,
+    collapsible,
+  });
   useEffect(() => {
     if (
       collapsible &&
diff --git a/yarn.lock b/yarn.lock
index cd9a9e762..80c931e6e 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3357,84 +3357,6 @@
   resolved "https://registry.yarnpkg.com/@react-types/shared/-/shared-3.32.1.tgz#abfeb839d65d0abe923576f34ac08342c25dfa55"
   integrity sha512-famxyD5emrGGpFuUlgOP6fVW2h/ZaF405G5KDi3zPHzyjAWys/8W6NAVJtNbkCkhedmvL0xOhvt8feGXyXaw5w==
 
-"@resvg/resvg-js-android-arm-eabi@2.6.2":
-  version "2.6.2"
-  resolved "https://registry.yarnpkg.com/@resvg/resvg-js-android-arm-eabi/-/resvg-js-android-arm-eabi-2.6.2.tgz#e761e0b688127db64879f455178c92468a9aeabe"
-  integrity sha512-FrJibrAk6v29eabIPgcTUMPXiEz8ssrAk7TXxsiZzww9UTQ1Z5KAbFJs+Z0Ez+VZTYgnE5IQJqBcoSiMebtPHA==
-
-"@resvg/resvg-js-android-arm64@2.6.2":
-  version "2.6.2"
-  resolved "https://registry.yarnpkg.com/@resvg/resvg-js-android-arm64/-/resvg-js-android-arm64-2.6.2.tgz#b8cb564d7f6b3f37d9b43129f5dc5fe171e249e4"
-  integrity sha512-VcOKezEhm2VqzXpcIJoITuvUS/fcjIw5NA/w3tjzWyzmvoCdd+QXIqy3FBGulWdClvp4g+IfUemigrkLThSjAQ==
-
-"@resvg/resvg-js-darwin-arm64@2.6.2":
-  version "2.6.2"
-  resolved "https://registry.yarnpkg.com/@resvg/resvg-js-darwin-arm64/-/resvg-js-darwin-arm64-2.6.2.tgz#49bd3faeda5c49f53302d970e6e79d006de18e7d"
-  integrity sha512-nmok2LnAd6nLUKI16aEB9ydMC6Lidiiq2m1nEBDR1LaaP7FGs4AJ90qDraxX+CWlVuRlvNjyYJTNv8qFjtL9+A==
-
-"@resvg/resvg-js-darwin-x64@2.6.2":
-  version "2.6.2"
-  resolved "https://registry.yarnpkg.com/@resvg/resvg-js-darwin-x64/-/resvg-js-darwin-x64-2.6.2.tgz#e1344173aa27bfb4d880ab576d1acf1c1648faca"
-  integrity sha512-GInyZLjgWDfsVT6+SHxQVRwNzV0AuA1uqGsOAW+0th56J7Nh6bHHKXHBWzUrihxMetcFDmQMAX1tZ1fZDYSRsw==
-
-"@resvg/resvg-js-linux-arm-gnueabihf@2.6.2":
-  version "2.6.2"
-  resolved "https://registry.yarnpkg.com/@resvg/resvg-js-linux-arm-gnueabihf/-/resvg-js-linux-arm-gnueabihf-2.6.2.tgz#34c445eba45efd68f6130b2ab426d76a7424253d"
-  integrity sha512-YIV3u/R9zJbpqTTNwTZM5/ocWetDKGsro0SWp70eGEM9eV2MerWyBRZnQIgzU3YBnSBQ1RcxRZvY/UxwESfZIw==
-
-"@resvg/resvg-js-linux-arm64-gnu@2.6.2":
-  version "2.6.2"
-  resolved "https://registry.yarnpkg.com/@resvg/resvg-js-linux-arm64-gnu/-/resvg-js-linux-arm64-gnu-2.6.2.tgz#30da47087dd8153182198b94fe9f8d994890dae5"
-  integrity sha512-zc2BlJSim7YR4FZDQ8OUoJg5holYzdiYMeobb9pJuGDidGL9KZUv7SbiD4E8oZogtYY42UZEap7dqkkYuA91pg==
-
-"@resvg/resvg-js-linux-arm64-musl@2.6.2":
-  version "2.6.2"
-  resolved "https://registry.yarnpkg.com/@resvg/resvg-js-linux-arm64-musl/-/resvg-js-linux-arm64-musl-2.6.2.tgz#5d75b8ff5c83103729c1ca3779987302753c50d4"
-  integrity sha512-3h3dLPWNgSsD4lQBJPb4f+kvdOSJHa5PjTYVsWHxLUzH4IFTJUAnmuWpw4KqyQ3NA5QCyhw4TWgxk3jRkQxEKg==
-
-"@resvg/resvg-js-linux-x64-gnu@2.6.2":
-  version "2.6.2"
-  resolved "https://registry.yarnpkg.com/@resvg/resvg-js-linux-x64-gnu/-/resvg-js-linux-x64-gnu-2.6.2.tgz#411abedfaee5edc57cbb7701736cecba522e26f3"
-  integrity sha512-IVUe+ckIerA7xMZ50duAZzwf1U7khQe2E0QpUxu5MBJNao5RqC0zwV/Zm965vw6D3gGFUl7j4m+oJjubBVoftw==
-
-"@resvg/resvg-js-linux-x64-musl@2.6.2":
-  version "2.6.2"
-  resolved "https://registry.yarnpkg.com/@resvg/resvg-js-linux-x64-musl/-/resvg-js-linux-x64-musl-2.6.2.tgz#fe4984038f0372f279e3ff570b72934dd7eb2a5c"
-  integrity sha512-UOf83vqTzoYQO9SZ0fPl2ZIFtNIz/Rr/y+7X8XRX1ZnBYsQ/tTb+cj9TE+KHOdmlTFBxhYzVkP2lRByCzqi4jQ==
-
-"@resvg/resvg-js-win32-arm64-msvc@2.6.2":
-  version "2.6.2"
-  resolved "https://registry.yarnpkg.com/@resvg/resvg-js-win32-arm64-msvc/-/resvg-js-win32-arm64-msvc-2.6.2.tgz#d3a053cf7ff687087a2106330c0fdaae706254d1"
-  integrity sha512-7C/RSgCa+7vqZ7qAbItfiaAWhyRSoD4l4BQAbVDqRRsRgY+S+hgS3in0Rxr7IorKUpGE69X48q6/nOAuTJQxeQ==
-
-"@resvg/resvg-js-win32-ia32-msvc@2.6.2":
-  version "2.6.2"
-  resolved "https://registry.yarnpkg.com/@resvg/resvg-js-win32-ia32-msvc/-/resvg-js-win32-ia32-msvc-2.6.2.tgz#7cdda1ce29ef7209e28191d917fa5bef0624a4ad"
-  integrity sha512-har4aPAlvjnLcil40AC77YDIk6loMawuJwFINEM7n0pZviwMkMvjb2W5ZirsNOZY4aDbo5tLx0wNMREp5Brk+w==
-
-"@resvg/resvg-js-win32-x64-msvc@2.6.2":
-  version "2.6.2"
-  resolved "https://registry.yarnpkg.com/@resvg/resvg-js-win32-x64-msvc/-/resvg-js-win32-x64-msvc-2.6.2.tgz#cb0ad04525d65f3def4c8d346157a57976d5b388"
-  integrity sha512-ZXtYhtUr5SSaBrUDq7DiyjOFJqBVL/dOBN7N/qmi/pO0IgiWW/f/ue3nbvu9joWE5aAKDoIzy/CxsY0suwGosQ==
-
-"@resvg/resvg-js@^2.6.2":
-  version "2.6.2"
-  resolved "https://registry.yarnpkg.com/@resvg/resvg-js/-/resvg-js-2.6.2.tgz#3e92a907d88d879256c585347c5b21a7f3bb5b46"
-  integrity sha512-xBaJish5OeGmniDj9cW5PRa/PtmuVU3ziqrbr5xJj901ZDN4TosrVaNZpEiLZAxdfnhAe7uQ7QFWfjPe9d9K2Q==
-  optionalDependencies:
-    "@resvg/resvg-js-android-arm-eabi" "2.6.2"
-    "@resvg/resvg-js-android-arm64" "2.6.2"
-    "@resvg/resvg-js-darwin-arm64" "2.6.2"
-    "@resvg/resvg-js-darwin-x64" "2.6.2"
-    "@resvg/resvg-js-linux-arm-gnueabihf" "2.6.2"
-    "@resvg/resvg-js-linux-arm64-gnu" "2.6.2"
-    "@resvg/resvg-js-linux-arm64-musl" "2.6.2"
-    "@resvg/resvg-js-linux-x64-gnu" "2.6.2"
-    "@resvg/resvg-js-linux-x64-musl" "2.6.2"
-    "@resvg/resvg-js-win32-arm64-msvc" "2.6.2"
-    "@resvg/resvg-js-win32-ia32-msvc" "2.6.2"
-    "@resvg/resvg-js-win32-x64-msvc" "2.6.2"
-
 "@rtsao/scc@^1.1.0":
   version "1.1.0"
   resolved "https://registry.yarnpkg.com/@rtsao/scc/-/scc-1.1.0.tgz#927dd2fae9bc3361403ac2c7a00c32ddce9ad7e8"
@@ -3510,14 +3432,6 @@
   resolved "https://registry.yarnpkg.com/@segment/isodate/-/isodate-1.0.3.tgz#f44e8202d5edd277ce822785239474b2c9411d4a"
   integrity sha512-BtanDuvJqnACFkeeYje7pWULVv8RgZaqKHWwGFnL/g/TH/CcZjkIVTfGDp/MAxmilYHUkrX70SqwnYSTNEaN7A==
 
-"@shuding/opentype.js@1.4.0-beta.0":
-  version "1.4.0-beta.0"
-  resolved "https://registry.yarnpkg.com/@shuding/opentype.js/-/opentype.js-1.4.0-beta.0.tgz#5d1e7e9e056f546aad41df1c5043f8f85d39e24b"
-  integrity sha512-3NgmNyH3l/Hv6EvsWJbsvpcpUba6R8IREQ83nH83cyakCw7uM1arZKNfHwv1Wz6jgqrF/j4x5ELvR6PnK9nTcA==
-  dependencies:
-    fflate "^0.7.3"
-    string.prototype.codepointat "^0.2.1"
-
 "@sideway/address@^4.1.5":
   version "4.1.5"
   resolved "https://registry.yarnpkg.com/@sideway/address/-/address-4.1.5.tgz#4bc149a0076623ced99ca8208ba780d65a99b9d5"
@@ -5304,11 +5218,6 @@ base64-arraybuffer@^1.0.2:
   resolved "https://registry.yarnpkg.com/base64-arraybuffer/-/base64-arraybuffer-1.0.2.tgz#1c37589a7c4b0746e34bd1feb951da2df01c1bdc"
   integrity sha512-I3yl4r9QB5ZRY3XuJVEPfc2XhZO6YweFPI+UovAzn+8/hb3oJ6lnysaFcjVpkCPfVWFUDvoZ8kmVDP7WyRtYtQ==
 
-base64-js@0.0.8:
-  version "0.0.8"
-  resolved "https://registry.yarnpkg.com/base64-js/-/base64-js-0.0.8.tgz#1101e9544f4a76b1bc3b26d452ca96d7a35e7978"
-  integrity sha512-3XSA2cR/h/73EzlXXdU6YNycmYI7+kicTxks4eJg2g39biHR84slg2+des+p7iHYhbRg/udIS4TD53WabcOUkw==
-
 baseline-browser-mapping@^2.8.25:
   version "2.8.31"
   resolved "https://registry.yarnpkg.com/baseline-browser-mapping/-/baseline-browser-mapping-2.8.31.tgz#16c0f1814638257932e0486dbfdbb3348d0a5710"
@@ -5532,11 +5441,6 @@ camelcase@^7.0.1:
   resolved "https://registry.yarnpkg.com/camelcase/-/camelcase-7.0.1.tgz#f02e50af9fd7782bc8b88a3558c32fd3a388f048"
   integrity sha512-xlx1yCK2Oc1APsPXDL2LdlNP6+uu8OCDdhOBSVT279M/S+y75O30C2VuD8T2ogdePBBl7PfPF4504tnLgX3zfw==
 
-camelize@^1.0.0:
-  version "1.0.1"
-  resolved "https://registry.yarnpkg.com/camelize/-/camelize-1.0.1.tgz#89b7e16884056331a35d6b5ad064332c91daa6c3"
-  integrity sha512-dU+Tx2fsypxTgtLoE36npi3UqcjSSMNYfkqgmoEhtZrraP5VWq0K7FkWVTYa8eMPtnU/G2txVsfdCJTn9uzpuQ==
-
 caniuse-api@^3.0.0:
   version "3.0.0"
   resolved "https://registry.yarnpkg.com/caniuse-api/-/caniuse-api-3.0.0.tgz#5e4d90e2274961d46291997df599e3ed008ee4c0"
@@ -5757,7 +5661,7 @@ color-convert@^2.0.1:
   dependencies:
     color-name "~1.1.4"
 
-color-name@^1.0.0, color-name@^1.1.4, color-name@~1.1.4:
+color-name@^1.0.0, color-name@~1.1.4:
   version "1.1.4"
   resolved "https://registry.yarnpkg.com/color-name/-/color-name-1.1.4.tgz#c2a09a87acbde69543de6f63fa3995c826c536a2"
   integrity sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==
@@ -6063,31 +5967,11 @@ crypto-random-string@^4.0.0:
   dependencies:
     type-fest "^1.0.1"
 
-css-background-parser@^0.1.0:
-  version "0.1.0"
-  resolved "https://registry.yarnpkg.com/css-background-parser/-/css-background-parser-0.1.0.tgz#48a17f7fe6d4d4f1bca3177ddf16c5617950741b"
-  integrity sha512-2EZLisiZQ+7m4wwur/qiYJRniHX4K5Tc9w93MT3AS0WS1u5kaZ4FKXlOTBhOjc+CgEgPiGY+fX1yWD8UwpEqUA==
-
-css-box-shadow@1.0.0-3:
-  version "1.0.0-3"
-  resolved "https://registry.yarnpkg.com/css-box-shadow/-/css-box-shadow-1.0.0-3.tgz#9eaeb7140947bf5d649fc49a19e4bbaa5f602713"
-  integrity sha512-9jaqR6e7Ohds+aWwmhe6wILJ99xYQbfmK9QQB9CcMjDbTxPZjwEmUQpU91OG05Xgm8BahT5fW+svbsQGjS/zPg==
-
-css-color-keywords@^1.0.0:
-  version "1.0.0"
-  resolved "https://registry.yarnpkg.com/css-color-keywords/-/css-color-keywords-1.0.0.tgz#fea2616dc676b2962686b3af8dbdbe180b244e05"
-  integrity sha512-FyyrDHZKEjXDpNJYvVsV960FiqQyXc/LlYmsxl2BcdMb2WPx0OGRVgTg55rPSyLSNMqP52R9r8geSp7apN3Ofg==
-
 css-declaration-sorter@^7.2.0:
   version "7.3.0"
   resolved "https://registry.yarnpkg.com/css-declaration-sorter/-/css-declaration-sorter-7.3.0.tgz#edc45c36bcdfea0788b1d4452829f142ef1c4a4a"
   integrity sha512-LQF6N/3vkAMYF4xoHLJfG718HRJh34Z8BnNhd6bosOMIVjMlhuZK5++oZa3uYAgrI5+7x2o27gUqTR2U/KjUOQ==
 
-css-gradient-parser@^0.0.16:
-  version "0.0.16"
-  resolved "https://registry.yarnpkg.com/css-gradient-parser/-/css-gradient-parser-0.0.16.tgz#5735da0822aef39da9b1960b314792ab542d9bb5"
-  integrity sha512-3O5QdqgFRUbXvK1x5INf1YkBz1UKSWqrd63vWsum8MNHDBYD5urm3QtxZbKU259OrEXNM26lP/MPY3d1IGkBgA==
-
 css-line-break@^2.1.0:
   version "2.1.0"
   resolved "https://registry.yarnpkg.com/css-line-break/-/css-line-break-2.1.0.tgz#bfef660dfa6f5397ea54116bb3cb4873edbc4fa0"
@@ -6143,15 +6027,6 @@ css-select@^5.1.0:
     domutils "^3.0.1"
     nth-check "^2.0.1"
 
-css-to-react-native@^3.0.0:
-  version "3.2.0"
-  resolved "https://registry.yarnpkg.com/css-to-react-native/-/css-to-react-native-3.2.0.tgz#cdd8099f71024e149e4f6fe17a7d46ecd55f1e32"
-  integrity sha512-e8RKaLXMOFii+02mOlqwjbD00KSEKqblnpO9e++1aXS1fPQOpS1YoqdVHBqPjHNoxeF2mimzVqawm2KCbEdtHQ==
-  dependencies:
-    camelize "^1.0.0"
-    css-color-keywords "^1.0.0"
-    postcss-value-parser "^4.0.2"
-
 css-tree@^1.1.2, css-tree@^1.1.3:
   version "1.1.3"
   resolved "https://registry.yarnpkg.com/css-tree/-/css-tree-1.1.3.tgz#eb4870fb6fd7707327ec95c2ff2ab09b5e8db91d"
@@ -6985,11 +6860,6 @@ elkjs@^0.9.0:
   resolved "https://registry.yarnpkg.com/elkjs/-/elkjs-0.9.3.tgz#16711f8ceb09f1b12b99e971b138a8384a529161"
   integrity sha512-f/ZeWvW/BCXbhGEf1Ujp29EASo/lk1FDnETgNKwJrsVvGZhUWCZyg3xLJjAsxfOmt8KjswHmI5EwCQcPMpOYhQ==
 
-emoji-regex@^10.2.1:
-  version "10.6.0"
-  resolved "https://registry.yarnpkg.com/emoji-regex/-/emoji-regex-10.6.0.tgz#bf3d6e8f7f8fd22a65d9703475bc0147357a6b0d"
-  integrity sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==
-
 emoji-regex@^8.0.0:
   version "8.0.0"
   resolved "https://registry.yarnpkg.com/emoji-regex/-/emoji-regex-8.0.0.tgz#e818fd69ce5ccfcb404594f842963bf53164cc37"
@@ -7924,11 +7794,6 @@ feed@^4.2.2:
   dependencies:
     xml-js "^1.6.11"
 
-fflate@^0.7.3:
-  version "0.7.4"
-  resolved "https://registry.yarnpkg.com/fflate/-/fflate-0.7.4.tgz#61587e5d958fdabb5a9368a302c25363f4f69f50"
-  integrity sha512-5u2V/CDW15QM1XbbgS+0DfPxVB+jUKhWEKuuFuHncbk3tEEqzmoXL+2KyOFuKGqOnmdIy0/davWF1CkuwtibCw==
-
 fflate@^0.8.1:
   version "0.8.2"
   resolved "https://registry.yarnpkg.com/fflate/-/fflate-0.8.2.tgz#fc8631f5347812ad6028bbe4a2308b2792aa1dea"
@@ -8571,11 +8436,6 @@ hermes-parser@^0.25.1:
   dependencies:
     hermes-estree "0.25.1"
 
-hex-rgb@^4.1.0:
-  version "4.3.0"
-  resolved "https://registry.yarnpkg.com/hex-rgb/-/hex-rgb-4.3.0.tgz#af5e974e83bb2fefe44d55182b004ec818c07776"
-  integrity sha512-Ox1pJVrDCyGHMG9CFg1tmrRUMRPRsAWYc/PinY0XzJU4K7y7vjNoLKIQ7BR5UJMCxNN8EM1MNDmHWA/B3aZUuw==
-
 history@^4.9.0:
   version "4.10.1"
   resolved "https://registry.yarnpkg.com/history/-/history-4.10.1.tgz#33371a65e3a83b267434e2b3f3b1b4c58aad4cf3"
@@ -9635,14 +9495,6 @@ lilconfig@^3.0.0, lilconfig@^3.1.1, lilconfig@^3.1.3:
   resolved "https://registry.yarnpkg.com/lilconfig/-/lilconfig-3.1.3.tgz#a1bcfd6257f9585bf5ae14ceeebb7b559025e4c4"
   integrity sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==
 
-linebreak@^1.1.0:
-  version "1.1.0"
-  resolved "https://registry.yarnpkg.com/linebreak/-/linebreak-1.1.0.tgz#831cf378d98bced381d8ab118f852bd50d81e46b"
-  integrity sha512-MHp03UImeVhB7XZtjd0E4n6+3xr5Dq/9xI/5FptGk5FrbDR3zagPa2DS6U8ks/3HjbKWG9Q1M2ufOzxV2qLYSQ==
-  dependencies:
-    base64-js "0.0.8"
-    unicode-trie "^2.0.0"
-
 lines-and-columns@^1.1.6:
   version "1.2.4"
   resolved "https://registry.yarnpkg.com/lines-and-columns/-/lines-and-columns-1.2.4.tgz#eca284f75d2965079309dc0ad9255abb2ebc1632"
@@ -11344,11 +11196,6 @@ package-json@^8.1.0:
     registry-url "^6.0.0"
     semver "^7.3.7"
 
-pako@^0.2.5:
-  version "0.2.9"
-  resolved "https://registry.yarnpkg.com/pako/-/pako-0.2.9.tgz#f3f7522f4ef782348da8161bad9ecfd51bf83a75"
-  integrity sha512-NUcwaKxUxWrZLpDG+z/xZaCgQITkA/Dv4V/T6bw7VON6l1Xz/VnrBqrYjZQ12TamKHzITTfOEIYUj48y2KXImA==
-
 param-case@^3.0.4:
   version "3.0.4"
   resolved "https://registry.yarnpkg.com/param-case/-/param-case-3.0.4.tgz#7d17fe4aa12bde34d4a77d91acfb6219caad01c5"
@@ -11364,14 +11211,6 @@ parent-module@^1.0.0:
   dependencies:
     callsites "^3.0.0"
 
-parse-css-color@^0.2.1:
-  version "0.2.1"
-  resolved "https://registry.yarnpkg.com/parse-css-color/-/parse-css-color-0.2.1.tgz#b687a583f2e42e66ffdfce80a570706966e807c9"
-  integrity sha512-bwS/GGIFV3b6KS4uwpzCFj4w297Yl3uqnSgIPsoQkx7GMLROXfMnWvxfNkL0oh8HVhZA4hvJoEoEIqonfJ3BWg==
-  dependencies:
-    color-name "^1.1.4"
-    hex-rgb "^4.1.0"
-
 parse-entities@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/parse-entities/-/parse-entities-2.0.0.tgz#53c6eb5b9314a1f4ec99fa0fdf7ce01ecda0cbe8"
@@ -11913,7 +11752,7 @@ postcss-unique-selectors@^6.0.4:
   dependencies:
     postcss-selector-parser "^6.0.16"
 
-postcss-value-parser@^4.0.0, postcss-value-parser@^4.0.2, postcss-value-parser@^4.1.0, postcss-value-parser@^4.2.0:
+postcss-value-parser@^4.0.0, postcss-value-parser@^4.1.0, postcss-value-parser@^4.2.0:
   version "4.2.0"
   resolved "https://registry.yarnpkg.com/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz#723c09920836ba6d3e5af019f92bc0971c02e514"
   integrity sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==
@@ -12909,23 +12748,6 @@ safe-regex-test@^1.0.3, safe-regex-test@^1.1.0:
   resolved "https://registry.yarnpkg.com/safer-buffer/-/safer-buffer-2.1.2.tgz#44fa161b0187b9549dd84bb91802f9bd8385cd6a"
   integrity sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==
 
-satori@^0.12.2:
-  version "0.12.2"
-  resolved "https://registry.yarnpkg.com/satori/-/satori-0.12.2.tgz#b0b06ed5eed3cd1b9140777364ba6bd1cb32c37c"
-  integrity sha512-3C/laIeE6UUe9A+iQ0A48ywPVCCMKCNSTU5Os101Vhgsjd3AAxGNjyq0uAA8kulMPK5n0csn8JlxPN9riXEjLA==
-  dependencies:
-    "@shuding/opentype.js" "1.4.0-beta.0"
-    css-background-parser "^0.1.0"
-    css-box-shadow "1.0.0-3"
-    css-gradient-parser "^0.0.16"
-    css-to-react-native "^3.0.0"
-    emoji-regex "^10.2.1"
-    escape-html "^1.0.3"
-    linebreak "^1.1.0"
-    parse-css-color "^0.2.1"
-    postcss-value-parser "^4.2.0"
-    yoga-wasm-web "^0.3.3"
-
 sax@^1.2.4:
   version "1.4.3"
   resolved "https://registry.yarnpkg.com/sax/-/sax-1.4.3.tgz#fcebae3b756cdc8428321805f4b70f16ec0ab5db"
@@ -13447,11 +13269,6 @@ string-width@^5.0.1, string-width@^5.1.2:
     emoji-regex "^9.2.2"
     strip-ansi "^7.0.1"
 
-string.prototype.codepointat@^0.2.1:
-  version "0.2.1"
-  resolved "https://registry.yarnpkg.com/string.prototype.codepointat/-/string.prototype.codepointat-0.2.1.tgz#004ad44c8afc727527b108cd462b4d971cd469bc"
-  integrity sha512-2cBVCj6I4IOvEnjgO/hWqXjqBGsY+zwPmHl12Srk9IXSZ56Jwwmy+66XO5Iut/oQVR7t5ihYdLB0GMa4alEUcg==
-
 string.prototype.includes@^2.0.1:
   version "2.0.1"
   resolved "https://registry.yarnpkg.com/string.prototype.includes/-/string.prototype.includes-2.0.1.tgz#eceef21283640761a81dbe16d6c7171a4edf7d92"
@@ -13849,11 +13666,6 @@ thunky@^1.0.2:
   resolved "https://registry.yarnpkg.com/thunky/-/thunky-1.1.0.tgz#5abaf714a9405db0504732bbccd2cedd9ef9537d"
   integrity sha512-eHY7nBftgThBqOyHGVN+l8gF0BucP09fMo0oO/Lb0w1OF80dJv+lDVpXG60WMQvkcxAkNybKsrEIE3ZtKGmPrA==
 
-tiny-inflate@^1.0.0:
-  version "1.0.3"
-  resolved "https://registry.yarnpkg.com/tiny-inflate/-/tiny-inflate-1.0.3.tgz#122715494913a1805166aaf7c93467933eea26c4"
-  integrity sha512-pkY1fj1cKHb2seWDy0B16HeWyczlJA9/WW3u3c4z/NiWDsO3DOU5D7nhTLE9CF0yXv/QZFY7sEJmj24dK+Rrqw==
-
 tiny-invariant@^1.0.2:
   version "1.3.3"
   resolved "https://registry.yarnpkg.com/tiny-invariant/-/tiny-invariant-1.3.3.tgz#46680b7a873a0d5d10005995eb90a70d74d60127"
@@ -14223,14 +14035,6 @@ unicode-property-aliases-ecmascript@^2.0.0:
   resolved "https://registry.yarnpkg.com/unicode-property-aliases-ecmascript/-/unicode-property-aliases-ecmascript-2.2.0.tgz#301d4f8a43d2b75c97adfad87c9dd5350c9475d1"
   integrity sha512-hpbDzxUY9BFwX+UeBnxv3Sh1q7HFxj48DTmXchNgRa46lO8uj3/1iEn3MiNUYTg1g9ctIqXCCERn8gYZhHC5lQ==
 
-unicode-trie@^2.0.0:
-  version "2.0.0"
-  resolved "https://registry.yarnpkg.com/unicode-trie/-/unicode-trie-2.0.0.tgz#8fd8845696e2e14a8b67d78fa9e0dd2cad62fec8"
-  integrity sha512-x7bc76x0bm4prf1VLg79uhAzKw8DVboClSN5VxJuQ+LKDOVEW9CdH+VY7SP+vX7xCYQqzzgQpFqz15zeLvAtZQ==
-  dependencies:
-    pako "^0.2.5"
-    tiny-inflate "^1.0.0"
-
 unified@^10.0.0:
   version "10.1.2"
   resolved "https://registry.yarnpkg.com/unified/-/unified-10.1.2.tgz#b1d64e55dafe1f0b98bb6c719881103ecf6c86df"
@@ -14934,11 +14738,6 @@ yocto-queue@^1.0.0:
   resolved "https://registry.yarnpkg.com/yocto-queue/-/yocto-queue-1.2.2.tgz#3e09c95d3f1aa89a58c114c99223edf639152c00"
   integrity sha512-4LCcse/U2MHZ63HAJVE+v71o7yOdIe4cZ70Wpf8D/IyjDKYQLV5GD46B+hSTjJsvV5PztjvHoU580EftxjDZFQ==
 
-yoga-wasm-web@^0.3.3:
-  version "0.3.3"
-  resolved "https://registry.yarnpkg.com/yoga-wasm-web/-/yoga-wasm-web-0.3.3.tgz#eb8e9fcb18e5e651994732f19a220cb885d932ba"
-  integrity sha512-N+d4UJSJbt/R3wqY7Coqs5pcV0aUj2j9IaQ3rNj9bVCLld8tTGKRa2USARjnvZJWVx1NDmQev8EknoczaOQDOA==
-
 zod-to-json-schema@3.24.6:
   version "3.24.6"
   resolved "https://registry.yarnpkg.com/zod-to-json-schema/-/zod-to-json-schema-3.24.6.tgz#5920f020c4d2647edfbb954fa036082b92c9e12d"

From 48a6c0cf3de0eae069ac5388c98efcb18497fb3c Mon Sep 17 00:00:00 2001
From: Vanshika-Rana <ranavanshika172000@gmail.com>
Date: Thu, 2 Jul 2026 13:34:35 +0530
Subject: [PATCH 2/2] fix: mermaid diagrams, og image

---
 .../docs/content/zcp/concept/how-it-works.mdx |  10 +-
 apps/docs/docusaurus.config.js                |  30 ++-
 apps/docs/src/css/custom.css                  | 187 ++++++++++++++----
 apps/docs/src/mermaid/client.js               |  99 ++++++++++
 apps/docs/src/theme/DocItem/Content/index.tsx |   7 +-
 5 files changed, 269 insertions(+), 64 deletions(-)
 create mode 100644 apps/docs/src/mermaid/client.js

diff --git a/apps/docs/content/zcp/concept/how-it-works.mdx b/apps/docs/content/zcp/concept/how-it-works.mdx
index c1124ff8d..63d443f87 100644
--- a/apps/docs/content/zcp/concept/how-it-works.mdx
+++ b/apps/docs/content/zcp/concept/how-it-works.mdx
@@ -39,11 +39,11 @@ flowchart TD
   reachability -->|needs human| blocker
   behavior -->|needs human| blocker
 
-  classDef user fill:#f7fbff,stroke:#2d72d9,stroke-width:1.5px,color:#172033;
-  classDef zcpbox fill:#eef7f1,stroke:#32845a,stroke-width:1.5px,color:#172033;
-  classDef work fill:#fffaf0,stroke:#c47f17,stroke-width:1.5px,color:#172033;
-  classDef done fill:#f5f3ff,stroke:#7157d9,stroke-width:1.5px,color:#172033;
-  classDef stop fill:#fff1f2,stroke:#d33f49,stroke-width:1.5px,color:#172033;
+  classDef user stroke:#2d72d9,stroke-width:1.5px;
+  classDef zcpbox stroke:#32845a,stroke-width:1.5px;
+  classDef work stroke:#c47f17,stroke-width:1.5px;
+  classDef done stroke:#7157d9,stroke-width:1.5px;
+  classDef stop stroke:#d33f49,stroke-width:1.5px;
 
   class intent user;
   class state,scope zcpbox;
diff --git a/apps/docs/docusaurus.config.js b/apps/docs/docusaurus.config.js
index b4f9fd166..7af8a45a1 100644
--- a/apps/docs/docusaurus.config.js
+++ b/apps/docs/docusaurus.config.js
@@ -1,9 +1,13 @@
 /* eslint-disable @typescript-eslint/no-var-requires */
 import "dotenv/config"
+import path from "path"
+import { fileURLToPath } from "url"
 import { themes as prismThemes } from "prism-react-renderer"
 const reverseSidebar = require("./src/utils/reverse-sidebar")
 const excludeSidebarResults = require("./src/utils/exclude-sidebar-results")
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
 const gtagTrackingId = process.env.GTAG_TRACKING_ID
 
 /** @type {import('@medusajs/docs').MedusaDocusaurusConfig} */
@@ -50,6 +54,14 @@ const config = {
         name: "custom-webpack-plugin",
         configureWebpack() {
           return {
+            resolve: {
+              alias: {
+                "@docusaurus/theme-mermaid/client": path.resolve(
+                  __dirname,
+                  "src/mermaid/client.js"
+                ),
+              },
+            },
             devServer: {
               client: {
                 overlay: {
@@ -80,23 +92,7 @@ const config = {
         light: "base",
         dark: "base",
       },
-      options: {
-        themeVariables: {
-          background: "#ECEFF3",
-          mainBkg: "#ECEFF3",
-          primaryColor: "#ECEFF3",
-          primaryTextColor: "#030712",
-          primaryBorderColor: "#D1D5DB",
-          nodeBorder: "#D1D5DB",
-          lineColor: "#11181C",
-          fontFamily: "Inter",
-          fontSize: "14.75px",
-          tertiaryColor: "#F3F4F6",
-          tertiaryBorderColor: "#D1D5DB",
-          tertiaryTextColor: "#030712",
-          clusterBkg: "#F3F4F6",
-        },
-      },
+      options: {},
     },
     image: "img/docs-meta.jpg",
     colorMode: {
diff --git a/apps/docs/src/css/custom.css b/apps/docs/src/css/custom.css
index 24bc738c2..97180e0db 100644
--- a/apps/docs/src/css/custom.css
+++ b/apps/docs/src/css/custom.css
@@ -735,66 +735,175 @@ html[data-theme='dark'] .zcp-claim-card--deploy   { background: rgba(76, 29, 149
 html[data-theme='dark'] .zcp-claim-card--stack    { background: rgba(30, 58, 138, 0.22); border-color: rgba(45, 114, 217, 0.35); }
 html[data-theme='dark'] .zcp-claim-card--handover { background: rgba(120, 53, 15, 0.2); border-color: rgba(196, 127, 23, 0.35); }
 
-/* ZCP mermaid flowcharts (how-it-works classDef nodes) */
+/* Mermaid diagrams — theme-aware styling */
 
-html[data-theme='dark'] .mermaid .node.user > rect,
-html[data-theme='dark'] .mermaid .node.user > polygon,
-html[data-theme='dark'] .mermaid .node.user > path {
-  fill: rgba(30, 58, 138, 0.35) !important;
+.docusaurus-mermaid-container {
+  margin: 1.25rem 0;
+}
+
+.docusaurus-mermaid-container svg {
+  background: transparent !important;
+}
+
+/* Edges and arrowheads */
+html[data-theme='dark'] .docusaurus-mermaid-container .edgePath path,
+html[data-theme='dark'] .docusaurus-mermaid-container .flowchart-link {
+  stroke: #94a3b8 !important;
+}
+
+html[data-theme='dark'] .docusaurus-mermaid-container marker path {
+  fill: #94a3b8 !important;
+  stroke: #94a3b8 !important;
+}
+
+/* Edge labels (yes / no / etc.) */
+html[data-theme='dark'] .docusaurus-mermaid-container .edgeLabel rect,
+html[data-theme='dark'] .docusaurus-mermaid-container .edgeLabel .label-container {
+  fill: #1e293b !important;
+}
+
+html[data-theme='dark'] .docusaurus-mermaid-container .edgeLabel span,
+html[data-theme='dark'] .docusaurus-mermaid-container .edgeLabel p,
+html[data-theme='dark'] .docusaurus-mermaid-container .edgeLabel .label {
+  color: #e2e8f0 !important;
+  fill: #e2e8f0 !important;
+}
+
+/* Default nodes (diagrams without classDef) */
+html[data-theme='light'] .docusaurus-mermaid-container .node.default rect,
+html[data-theme='light'] .docusaurus-mermaid-container .node.default polygon,
+html[data-theme='light'] .docusaurus-mermaid-container .node.default circle {
+  fill: #eceff3 !important;
+  stroke: #d1d5db !important;
+}
+
+html[data-theme='dark'] .docusaurus-mermaid-container .node.default rect,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.default polygon,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.default circle {
+  fill: rgba(30, 41, 59, 0.92) !important;
+  stroke: #64748b !important;
+}
+
+html[data-theme='light'] .docusaurus-mermaid-container .node.default foreignObject div,
+html[data-theme='light'] .docusaurus-mermaid-container .node.default .label,
+html[data-theme='light'] .docusaurus-mermaid-container .node.default .nodeLabel {
+  color: #030712 !important;
+}
+
+html[data-theme='dark'] .docusaurus-mermaid-container .node.default foreignObject div,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.default .label,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.default .nodeLabel {
+  color: #f8fafc !important;
+  fill: #f8fafc !important;
+}
+
+/* classDef nodes — light mode fills */
+html[data-theme='light'] .docusaurus-mermaid-container .node.user rect,
+html[data-theme='light'] .docusaurus-mermaid-container .node.user polygon {
+  fill: #f7fbff !important;
+  stroke: #2d72d9 !important;
+}
+
+html[data-theme='light'] .docusaurus-mermaid-container .node.zcpbox rect,
+html[data-theme='light'] .docusaurus-mermaid-container .node.zcpbox polygon {
+  fill: #eef7f1 !important;
+  stroke: #32845a !important;
+}
+
+html[data-theme='light'] .docusaurus-mermaid-container .node.work rect,
+html[data-theme='light'] .docusaurus-mermaid-container .node.work polygon {
+  fill: #fffaf0 !important;
+  stroke: #c47f17 !important;
+}
+
+html[data-theme='light'] .docusaurus-mermaid-container .node.done rect,
+html[data-theme='light'] .docusaurus-mermaid-container .node.done polygon {
+  fill: #f5f3ff !important;
+  stroke: #7157d9 !important;
+}
+
+html[data-theme='light'] .docusaurus-mermaid-container .node.stop rect,
+html[data-theme='light'] .docusaurus-mermaid-container .node.stop polygon {
+  fill: #fff1f2 !important;
+  stroke: #d33f49 !important;
+}
+
+html[data-theme='light'] .docusaurus-mermaid-container .node.user foreignObject div,
+html[data-theme='light'] .docusaurus-mermaid-container .node.zcpbox foreignObject div,
+html[data-theme='light'] .docusaurus-mermaid-container .node.work foreignObject div,
+html[data-theme='light'] .docusaurus-mermaid-container .node.done foreignObject div,
+html[data-theme='light'] .docusaurus-mermaid-container .node.stop foreignObject div,
+html[data-theme='light'] .docusaurus-mermaid-container .node.user .label,
+html[data-theme='light'] .docusaurus-mermaid-container .node.zcpbox .label,
+html[data-theme='light'] .docusaurus-mermaid-container .node.work .label,
+html[data-theme='light'] .docusaurus-mermaid-container .node.done .label,
+html[data-theme='light'] .docusaurus-mermaid-container .node.stop .label {
+  color: #172033 !important;
+}
+
+/* classDef nodes — dark mode fills */
+html[data-theme='dark'] .docusaurus-mermaid-container .node.user rect,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.user polygon {
+  fill: rgba(30, 58, 138, 0.45) !important;
   stroke: #60a5fa !important;
 }
 
-html[data-theme='dark'] .mermaid .node.zcpbox > rect,
-html[data-theme='dark'] .mermaid .node.zcpbox > polygon,
-html[data-theme='dark'] .mermaid .node.zcpbox > path {
-  fill: rgba(20, 83, 45, 0.3) !important;
+html[data-theme='dark'] .docusaurus-mermaid-container .node.zcpbox rect,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.zcpbox polygon {
+  fill: rgba(20, 83, 45, 0.4) !important;
   stroke: #4ade80 !important;
 }
 
-html[data-theme='dark'] .mermaid .node.work > rect,
-html[data-theme='dark'] .mermaid .node.work > polygon,
-html[data-theme='dark'] .mermaid .node.work > path {
-  fill: rgba(120, 53, 15, 0.28) !important;
+html[data-theme='dark'] .docusaurus-mermaid-container .node.work rect,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.work polygon {
+  fill: rgba(120, 53, 15, 0.38) !important;
   stroke: #fbbf24 !important;
 }
 
-html[data-theme='dark'] .mermaid .node.done > rect,
-html[data-theme='dark'] .mermaid .node.done > polygon,
-html[data-theme='dark'] .mermaid .node.done > path {
-  fill: rgba(76, 29, 149, 0.28) !important;
+html[data-theme='dark'] .docusaurus-mermaid-container .node.done rect,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.done polygon {
+  fill: rgba(76, 29, 149, 0.38) !important;
   stroke: #a78bfa !important;
 }
 
-html[data-theme='dark'] .mermaid .node.stop > rect,
-html[data-theme='dark'] .mermaid .node.stop > polygon,
-html[data-theme='dark'] .mermaid .node.stop > path {
-  fill: rgba(127, 29, 29, 0.28) !important;
+html[data-theme='dark'] .docusaurus-mermaid-container .node.stop rect,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.stop polygon {
+  fill: rgba(127, 29, 29, 0.38) !important;
   stroke: #f87171 !important;
 }
 
-html[data-theme='dark'] .mermaid .node.user .label,
-html[data-theme='dark'] .mermaid .node.zcpbox .label,
-html[data-theme='dark'] .mermaid .node.work .label,
-html[data-theme='dark'] .mermaid .node.done .label,
-html[data-theme='dark'] .mermaid .node.stop .label {
+html[data-theme='dark'] .docusaurus-mermaid-container .node.user foreignObject div,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.zcpbox foreignObject div,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.work foreignObject div,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.done foreignObject div,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.stop foreignObject div,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.user .label,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.zcpbox .label,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.work .label,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.done .label,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.stop .label,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.user .nodeLabel,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.zcpbox .nodeLabel,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.work .nodeLabel,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.done .nodeLabel,
+html[data-theme='dark'] .docusaurus-mermaid-container .node.stop .nodeLabel {
   color: #f8fafc !important;
+  fill: #f8fafc !important;
 }
 
-html[data-theme='dark'] .mermaid .node.user .label span,
-html[data-theme='dark'] .mermaid .node.zcpbox .label span,
-html[data-theme='dark'] .mermaid .node.work .label span,
-html[data-theme='dark'] .mermaid .node.done .label span,
-html[data-theme='dark'] .mermaid .node.stop .label span {
-  color: #f8fafc !important;
+/* Inline code inside diagram labels */
+html[data-theme='light'] .docusaurus-mermaid-container foreignObject code {
+  background: rgba(3, 7, 18, 0.06) !important;
+  color: #172033 !important;
+  padding: 0.1em 0.35em;
+  border-radius: 4px;
 }
 
-html[data-theme='dark'] .mermaid .node.user .label code,
-html[data-theme='dark'] .mermaid .node.zcpbox .label code,
-html[data-theme='dark'] .mermaid .node.work .label code,
-html[data-theme='dark'] .mermaid .node.done .label code,
-html[data-theme='dark'] .mermaid .node.stop .label code {
-  background: rgba(15, 23, 42, 0.55);
-  color: #e2e8f0;
+html[data-theme='dark'] .docusaurus-mermaid-container foreignObject code {
+  background: rgba(15, 23, 42, 0.75) !important;
+  color: #e2e8f0 !important;
+  padding: 0.1em 0.35em;
+  border-radius: 4px;
 }
 
 /* gap objection cards */
diff --git a/apps/docs/src/mermaid/client.js b/apps/docs/src/mermaid/client.js
new file mode 100644
index 000000000..4f27bf6a0
--- /dev/null
+++ b/apps/docs/src/mermaid/client.js
@@ -0,0 +1,99 @@
+import { useState, useEffect, useMemo, useRef } from 'react';
+import { useColorMode, useThemeConfig } from '@docusaurus/theme-common';
+import mermaid from 'mermaid';
+
+export const MermaidContainerClassName = 'docusaurus-mermaid-container';
+
+const lightThemeVariables = {
+  background: 'transparent',
+  mainBkg: '#ECEFF3',
+  primaryColor: '#ECEFF3',
+  primaryTextColor: '#030712',
+  primaryBorderColor: '#D1D5DB',
+  nodeBorder: '#D1D5DB',
+  lineColor: '#11181C',
+  fontFamily: 'Inter',
+  fontSize: '14.75px',
+  tertiaryColor: '#F3F4F6',
+  tertiaryBorderColor: '#D1D5DB',
+  tertiaryTextColor: '#030712',
+  clusterBkg: '#F3F4F6',
+  edgeLabelBackground: '#ffffff',
+};
+
+const darkThemeVariables = {
+  background: 'transparent',
+  mainBkg: '#1e293b',
+  primaryColor: '#1e293b',
+  primaryTextColor: '#f8fafc',
+  primaryBorderColor: '#64748b',
+  nodeBorder: '#64748b',
+  lineColor: '#94a3b8',
+  fontFamily: 'Inter',
+  fontSize: '14.75px',
+  tertiaryColor: '#334155',
+  tertiaryBorderColor: '#64748b',
+  tertiaryTextColor: '#f8fafc',
+  clusterBkg: '#1e293b',
+  edgeLabelBackground: '#1e293b',
+  textColor: '#f8fafc',
+  secondaryColor: '#334155',
+  secondaryTextColor: '#e2e8f0',
+  secondaryBorderColor: '#64748b',
+};
+
+export function useMermaidThemeConfig() {
+  return useThemeConfig().mermaid;
+}
+
+export function useMermaidConfig() {
+  const { colorMode } = useColorMode();
+  const mermaidThemeConfig = useMermaidThemeConfig();
+  const theme = mermaidThemeConfig.theme[colorMode];
+  const { options } = mermaidThemeConfig;
+
+  return useMemo(() => {
+    const { themeVariables: _ignored, ...restOptions } = options;
+
+    return {
+      startOnLoad: false,
+      ...restOptions,
+      theme,
+      themeVariables:
+        colorMode === 'dark' ? darkThemeVariables : lightThemeVariables,
+    };
+  }, [theme, options, colorMode]);
+}
+
+function useMermaidId() {
+  return useRef(`mermaid-svg-${Math.round(Math.random() * 10000000)}`).current;
+}
+
+async function renderMermaid({ id, text, config }) {
+  mermaid.mermaidAPI.initialize(config);
+  try {
+    return await mermaid.render(id, text);
+  } catch (e) {
+    document.querySelector(`#d${id}`)?.remove();
+    throw e;
+  }
+}
+
+export function useMermaidRenderResult({ text, config: providedConfig }) {
+  const [result, setResult] = useState(null);
+  const id = useMermaidId();
+  const defaultMermaidConfig = useMermaidConfig();
+  const config = providedConfig ?? defaultMermaidConfig;
+
+  useEffect(() => {
+    renderMermaid({ id, text, config })
+      .then(setResult)
+      .catch((e) => {
+        setResult(() => {
+          throw e;
+        });
+      });
+  }, [id, text, config]);
+
+  return result;
+}
diff --git a/apps/docs/src/theme/DocItem/Content/index.tsx b/apps/docs/src/theme/DocItem/Content/index.tsx
index 3f9217307..2664772db 100644
--- a/apps/docs/src/theme/DocItem/Content/index.tsx
+++ b/apps/docs/src/theme/DocItem/Content/index.tsx
@@ -8,7 +8,6 @@ import type { Props } from '@theme/DocItem/Content';
 import { DocContextValue } from '@medusajs/docs';
 import { Badge, BadgeVariant } from 'docs-ui';
 import Head from '@docusaurus/Head';
-import { useLocation } from '@docusaurus/router';
 
 /**
  Title can be declared inside md content or declared through
@@ -35,10 +34,12 @@ export default function DocItemContent({ children }: Props): JSX.Element {
     frontMatter: { badge, description, image },
     metadata,
   } = useDoc() as DocContextValue;
-  const location = useLocation();
+  // OG microservice indexes pages by doc id (e.g. quickstart/quickstart), not
+  // custom permalinks (e.g. /quickstart/deploy-your-first-app).
+  const ogPath = `/${metadata.id}`;
   const ogImage =
     image ??
-    `https://docs.zerops.io/og?path=${encodeURIComponent(location.pathname)}`;
+    `https://docs.zerops.io/og?path=${encodeURIComponent(ogPath)}`;
   const syntheticTitle = useSyntheticTitle();
 
   return (