docs: fix ZCP dark mode and sidebar, embed coding agents video, add G…

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/cli.mdx

@@ -40,7 +40,7 @@ Execute following command in PowerShell:
 irm https://zerops.io/zcli/install.ps1 | iex
 ```
 
-zCLI will be installed inside `C:\Program Files\` or `C:\Program Files (x86)\`
+zCLI will be installed inside `C:\Users\<user>\.zerops\zcli.exe`.
 
 ### Using Package Managers
 

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/content/references/gitlab-integration.mdx

@@ -47,19 +47,6 @@ Zerops requires full access to configure webhooks and download your code. Your s
 4. **Finalize Setup**
    - Confirm your settings to complete the integration
 
-{/* TODO: IMAGE */}
-
-<figure style={{ textAlign: 'center', margin: '1rem 0' }}>
-<img
-    src="/img/gui/gitlab-integration.webp"
-    alt="image"
-    width="90%"
-    height="auto"
-  />
-
-</figure>
--->
-
 ---
 
 ### Skip the automatic pipeline once

apps/docs/content/references/networking/vpn.mdx

@@ -14,6 +14,12 @@ Before getting started, ensure you have:
 - [zCLI](/references/cli) (serves as the WireGuard client)
 - A Zerops project with at least one service
 
+:::info Windows prerequisite
+zCLI VPN relies on WireGuard, which requires the **Virtual Machine Platform**
+feature to be enabled on Windows 11. Open `optionalfeatures.exe`, check
+**Virtual Machine Platform**, then reboot.
+:::
+
 ## Usage
 
 You can interact with services within your project and even establish SSH connection to your services after connecting to project through VPN.

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;

apps/docs/content/zcp/overview.mdx

@@ -137,7 +137,7 @@ To start, add remote setup in Zerops or initialize local setup beside your edito
 
 **Zerops token.** The MCP server connects through `ZCP_API_KEY`, a Zerops token limited to one project. Remote setup gets it from the platform; local setup reads it from `.mcp.json`. Token details live in [Tokens and credentials](/zcp/security/tokens-and-project-access).
 
-**Workspace freedom.** The `zcp@1` service is still a normal Zerops service. You can install another agent CLI, add private MCP servers or helper tools, edit `CLAUDE.md`, add team dotfiles, and adapt the workspace. Details live in [What remote workspace gives you](/zcp/setup/hosted-workspace#make-customization-persistent).
+**Workspace freedom.** The `zcp@1` service is still a normal Zerops service. You can install another agent CLI, add private MCP servers or helper tools, edit `CLAUDE.md`, add team dotfiles, and adapt the workspace. Details live in [What remote workspace gives you](/zcp/setup/hosted-workspace).
 
 :::caution Production boundary
 Use this setup for development or staging work. Production should stay in a separate Zerops project and receive released work through your CI or release process; see [Promote to production](/zcp/workflows/promote-to-production) for the practical flow and [Production boundary](/zcp/security/production-policy) for the policy.

apps/docs/docusaurus.config.js

@@ -1,9 +1,15 @@
 /* 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} */
 const config = {
   title: "Zerops",
@@ -48,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: {
@@ -78,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: {
@@ -228,7 +226,9 @@ const config = {
           routeBasePath: "/",
           remarkPlugins: [
             [require("@docusaurus/remark-plugin-npm2yarn"), { sync: true }],
+            require('./src/plugins/remark-mdx-table-component'),
           ],
+          rehypePlugins: [require('./src/plugins/rehype-wrap-tables')],
           showLastUpdateTime: false,
           showLastUpdateAuthor: false,
           // breadcrumbs: false,
@@ -250,9 +250,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/components/NavigationButons/index.tsx

@@ -15,7 +15,7 @@ interface NavigationButtonsProps {
 
 export function NavigationButtons({ prevPage, nextPage }: NavigationButtonsProps) {
     return (
-        <div className="flex justify-between mt-2 border-t pt-4">
+        <div className="doc-pagination-nav flex justify-between mt-2 border-t pt-4">
             {prevPage ? (
                 <Link
                     href={`${prevPage.href}`}

apps/docs/src/components/ResourceTable/index.tsx

@@ -27,7 +27,8 @@ const ResourceTable = ({ resources = {} }) => {
   };
 
   return (
-      <table className="w-full my-1.5 whitespace-nowrap table-fixed">
+    <div className="table-scroll-wrapper">
+      <table className="w-full my-1.5">
         <thead>
           <tr>
             <th className="w-1/6 whitespace-nowrap">&nbsp;</th>
@@ -45,6 +46,7 @@ const ResourceTable = ({ resources = {} }) => {
           ))}
         </tbody>
       </table>
+    </div>
   );
 };
 

apps/docs/src/css/_docusaurus.css

@@ -150,7 +150,13 @@ details summary {
 }
 
 .reference-table {
-  @apply !table table-fixed w-full;
+  @apply !table w-full;
+}
+
+@media (min-width: 997px) {
+  .reference-table {
+    @apply table-fixed;
+  }
 }
 
 .reference-table p {
@@ -323,24 +329,17 @@ td {
   @apply bg-[#F2F5F7] dark:bg-[#1B1B1F];
 }
 
-/* Infima's default is `table { display: block; overflow: auto }`, which turns
-   the <table> into a block scroll-container whose actual grid becomes an
-   anonymous, shrink-to-fit table box. `width: 100%` then only sizes the outer
-   block — it never reaches the grid — so the table refuses to fill the page,
-   and forcing a cell width (the old `td { width: 100% }`) just bloats one
-   column instead of widening the table. On tablet/desktop, restore a real
-   table box so `width: 100%` + auto layout distribute columns and fill the
-   parent. Below 768px we keep Infima's display:block + overflow-x scroll so
-   wide tables stay swipeable on mobile. */
-@media (min-width: 768px) {
+/* Keep tables as real table boxes. Horizontal scroll is handled by
+   .table-scroll-wrapper (MDX Table swizzle) and responsive-content.css. */
+@media (min-width: 997px) {
   table {
     display: table;
     table-layout: auto;
   }
 
   th,
   td {
-    overflow-wrap: anywhere;
+    overflow-wrap: break-word;
   }
 }