docs: fix ZCP dark mode and sidebar, embed coding agents video, add GitHub lifecycle automation

Author: Vanshika-Rana

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=
+CLOUDINARY_CLOUD_NAME=
+GTAG_TRACKING_ID=

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

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).
+:::

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/**"],

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',

apps/docs/src/css/custom.css

@@ -576,13 +576,27 @@ 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;
 }
 
 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 */
 

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 &&