From cb0d33d53497103c82db85c759ccacf6af70ae44 Mon Sep 17 00:00:00 2001
From: Simon KP <simon@techops.services>
Date: Sun, 15 Mar 2026 17:42:05 +1100
Subject: [PATCH] ci: add docs sync workflow to keeperhub

On release or manual trigger, regenerates CLI command docs and syncs
them to the keeperhub docs-site via cross-repo PR. Keeps CLI reference
pages in sync without manual maintenance.
---
 .github/workflows/docs-sync.yml | 117 ++++++++++++++++++++++++++++++++
 1 file changed, 117 insertions(+)
 create mode 100644 .github/workflows/docs-sync.yml

diff --git a/.github/workflows/docs-sync.yml b/.github/workflows/docs-sync.yml
new file mode 100644
index 0000000..a1314f7
--- /dev/null
+++ b/.github/workflows/docs-sync.yml
@@ -0,0 +1,117 @@
+name: Sync CLI Docs to KeeperHub
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+concurrency:
+  group: cli-docs-sync
+  cancel-in-progress: true
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout CLI repo
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Regenerate CLI docs
+        run: go generate ./docs/...
+
+      - name: Checkout KeeperHub repo
+        uses: actions/checkout@v4
+        with:
+          repository: techops-services/keeperhub
+          token: ${{ secrets.KEEPERHUB_PAT }}
+          path: keeperhub
+          ref: staging
+
+      - name: Sync docs to KeeperHub
+        id: sync
+        run: |
+          CLI_DOCS="docs"
+          KH_DOCS="keeperhub/docs/cli"
+
+          # Sync command reference files
+          rm -rf "$KH_DOCS/commands/"kh*.md
+          cp "$CLI_DOCS/"kh*.md "$KH_DOCS/commands/"
+
+          # Sync hand-written guides (add frontmatter for Nextra)
+          for file in quickstart.md concepts.md; do
+            TITLE=$(head -1 "$CLI_DOCS/$file" | sed 's/^# //')
+
+            # Build the Nextra-compatible version with frontmatter
+            {
+              echo "---"
+              echo "title: \"$TITLE\""
+              echo "description: \"KeeperHub CLI $TITLE\""
+              echo "---"
+              echo ""
+              cat "$CLI_DOCS/$file"
+            } > "$KH_DOCS/$file"
+          done
+
+          # Regenerate commands/_meta.ts from the synced files
+          {
+            echo "export default {"
+            for f in "$KH_DOCS/commands/"kh*.md; do
+              stem=$(basename "$f" .md)
+              label=$(echo "$stem" | sed 's/_/ /g')
+              # Quote keys that contain hyphens
+              if echo "$stem" | grep -q '-'; then
+                echo "  \"$stem\": \"$label\","
+              else
+                echo "  $stem: \"$label\","
+              fi
+            done
+            echo "};"
+          } > "$KH_DOCS/commands/_meta.ts"
+
+          # Fix internal links in quickstart and concepts for Nextra
+          sed -i 's|\[Command reference\](kh\.md)|[Command reference](./commands/kh)|g' "$KH_DOCS/quickstart.md"
+          sed -i 's|\[concepts\.md\](concepts\.md)|[Concepts](./concepts)|g' "$KH_DOCS/quickstart.md"
+          sed -i 's|\[quickstart\.md\](quickstart\.md)|[Quickstart](./quickstart)|g' "$KH_DOCS/concepts.md"
+
+          # Check if anything changed
+          cd keeperhub
+          if git diff --quiet && [ -z "$(git ls-files --others --exclude-standard docs/cli/)" ]; then
+            echo "No changes to sync."
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_changes=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create PR in KeeperHub
+        if: steps.sync.outputs.has_changes == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.KEEPERHUB_PAT }}
+          RELEASE_TAG: ${{ github.event.release.tag_name || 'manual' }}
+        run: |
+          cd keeperhub
+
+          # Sanitize tag for branch name
+          SAFE_TAG=$(echo "$RELEASE_TAG" | sed 's/[^a-zA-Z0-9.-]/-/g')
+          BRANCH="docs/cli-sync-${SAFE_TAG}"
+
+          git checkout -b "$BRANCH"
+          git add docs/cli/
+          git commit -m "docs: sync CLI reference from ${RELEASE_TAG}"
+          git push origin "$BRANCH"
+
+          gh pr create \
+            --base staging \
+            --title "docs: sync CLI reference from ${RELEASE_TAG}" \
+            --body "Auto-synced CLI command reference from cli@${RELEASE_TAG}.
+
+Changes were generated by go generate ./docs/... in the CLI repo and copied to docs/cli/."