From a31b2e09bb6c6904d35dc732585ea75ee1535df8 Mon Sep 17 00:00:00 2001
From: Thieu Nguyen <thieunguyen.tech@gmail.com>
Date: Mon, 6 Apr 2026 01:07:27 +0700
Subject: [PATCH] feat: add branch deploy versioning for dev docs

Support parallel docs for stable (master) and dev branches:
- Deploy workflow triggers on both master and dev branches
- Dev site detection via hostname (pages.dev or dev.* subdomain)
- Warning banner with i18n (EN/VI/ZH) on dev site
- SEO noindex meta tag injected on dev site only
- Audit script accepts --source-branch param to target goclaw branch
---
 .github/workflows/deploy.yml |  1 +
 css/styles.css               | 17 +++++++++++++++++
 js/docs-app.js               | 27 +++++++++++++++++++++++++++
 scripts/audit-docs.sh        | 19 ++++++++++++++-----
 4 files changed, 59 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index d6e0aae..c249634 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - master
+      - dev
 
 jobs:
   deploy:
diff --git a/css/styles.css b/css/styles.css
index 58ae906..9a2feed 100644
--- a/css/styles.css
+++ b/css/styles.css
@@ -898,3 +898,20 @@ h1, h2, h3, h4, h5, h6 {
 .doc-source-sep {
   opacity: 0.3;
 }
+
+/* Dev site banner */
+#dev-banner {
+  background: #92400e;
+  color: #fef3c7;
+  text-align: center;
+  padding: 8px 16px;
+  font-size: 0.85rem;
+  position: sticky;
+  top: 0;
+  z-index: 100;
+}
+#dev-banner a {
+  color: #fbbf24;
+  text-decoration: underline;
+  margin-left: 8px;
+}
diff --git a/js/docs-app.js b/js/docs-app.js
index ca5233c..ae5c43e 100644
--- a/js/docs-app.js
+++ b/js/docs-app.js
@@ -3,6 +3,14 @@
  * Loads and renders markdown docs with marked.js + mermaid + highlight.js
  */
 
+/* ============================================================
+   DEV SITE DETECTION
+   ============================================================ */
+function isDevSite() {
+  const host = window.location.hostname;
+  return host.includes('pages.dev') || host.startsWith('dev.');
+}
+
 /* ============================================================
    I18N — UI string translations
    ============================================================ */
@@ -764,6 +772,25 @@ function migrateHashURL() {
    INIT
    ============================================================ */
 document.addEventListener('DOMContentLoaded', () => {
+  /* Dev site: show warning banner + noindex */
+  if (isDevSite()) {
+    const banner = document.createElement('div');
+    banner.id = 'dev-banner';
+    const lang = localStorage.getItem('goclaw-docs-lang') || 'en';
+    const msgs = {
+      en: '⚠️ Development docs — may differ from stable release.',
+      vi: '⚠️ Tài liệu phiên bản phát triển — có thể khác bản ổn định.',
+      zh: '⚠️ 开发版文档 — 可能与稳定版不同。',
+    };
+    banner.innerHTML = (msgs[lang] || msgs.en) + ' <a href="https://docs.goclaw.sh">Stable docs →</a>';
+    document.body.prepend(banner);
+
+    const noindex = document.createElement('meta');
+    noindex.name = 'robots';
+    noindex.content = 'noindex, nofollow';
+    document.head.appendChild(noindex);
+  }
+
   initMarked();
   initSidebar();
   initMobileSidebar();
diff --git a/scripts/audit-docs.sh b/scripts/audit-docs.sh
index c27c4a1..e4e8de7 100755
--- a/scripts/audit-docs.sh
+++ b/scripts/audit-docs.sh
@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 # audit-docs.sh — Find doc pages whose goclaw-source SHA is behind latest goclaw commit
-# Usage: ./scripts/audit-docs.sh [--update]
-#   --update  Update all outdated pages with current SHA and today's date
+# Usage: ./scripts/audit-docs.sh [--update] [--source-branch=main|dev]
+#   --update              Update all outdated pages with current SHA and today's date
+#   --source-branch=NAME  GoClaw branch to audit against (default: main)
 
 set -euo pipefail
 
@@ -9,12 +10,20 @@ GOCLAW_DIR="$(cd "$(dirname "$0")/../../goclaw" 2>/dev/null && pwd)" || {
   echo "Error: ../goclaw directory not found"; exit 1
 }
 DOCS_DIR="$(cd "$(dirname "$0")/.." && pwd)"
-LATEST_SHA=$(git -C "$GOCLAW_DIR" log -1 --format="%h")
 TODAY=$(date +%Y-%m-%d)
 UPDATE=false
-[[ "${1:-}" == "--update" ]] && UPDATE=true
+SOURCE_BRANCH="main"
 
-echo "GoClaw latest: $LATEST_SHA"
+for arg in "$@"; do
+  case "$arg" in
+    --update) UPDATE=true ;;
+    --source-branch=*) SOURCE_BRANCH="${arg#*=}" ;;
+  esac
+done
+
+LATEST_SHA=$(git -C "$GOCLAW_DIR" log -1 --format="%h" "$SOURCE_BRANCH")
+
+echo "GoClaw branch: $SOURCE_BRANCH (latest: $LATEST_SHA)"
 echo "Scanning docs in: $DOCS_DIR"
 echo "---"