Flip docs default to released + support doc-only releases

Add a private @salesforce/b2c-dx-docs workspace package to enable:

- Doc-only releases via changesets without bumping CLI/SDK/MCP versions
- Automatic docs rebuild when SDK changes (via updateInternalDependencies cascade)
- Changelog tracking for documentation changes

Flip the docs deployment so released/stable docs are served at the root
URL and dev docs live at /dev/. Previously dev was at root and released
docs were at /release/.

Update deploy-docs workflow to build stable docs at root from the latest
tag (matching both @salesforce/* and docs@* patterns) and nest dev docs
under /dev/. Update publish workflow to create docs@<version> tags and
trigger docs deployment on stable releases.

Author: clavery

.github/workflows/deploy-docs.yml

@@ -12,7 +12,7 @@ permissions:
 
 concurrency:
   group: pages
-  cancel-in-progress: false
+  cancel-in-progress: true
 
 jobs:
   build:
@@ -54,20 +54,44 @@ jobs:
       - name: Get latest release tag
         id: release
         run: |
-          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+          # Find the most recent package tag and docs tag
+          PKG_TAG=$(git describe --tags --abbrev=0 --match '@salesforce/*' 2>/dev/null || echo "")
+          DOCS_TAG=$(git describe --tags --abbrev=0 --match 'docs@*' 2>/dev/null || echo "")
+
+          # Pick whichever tag is closer to HEAD (fewer commits behind)
+          LATEST_TAG=""
+          if [[ -n "$PKG_TAG" && -n "$DOCS_TAG" ]]; then
+            PKG_DISTANCE=$(git rev-list --count "${PKG_TAG}..HEAD")
+            DOCS_DISTANCE=$(git rev-list --count "${DOCS_TAG}..HEAD")
+            if [[ "$DOCS_DISTANCE" -le "$PKG_DISTANCE" ]]; then
+              LATEST_TAG="$DOCS_TAG"
+            else
+              LATEST_TAG="$PKG_TAG"
+            fi
+          elif [[ -n "$PKG_TAG" ]]; then
+            LATEST_TAG="$PKG_TAG"
+          elif [[ -n "$DOCS_TAG" ]]; then
+            LATEST_TAG="$DOCS_TAG"
+          fi
+
           echo "tag=$LATEST_TAG" >> $GITHUB_OUTPUT
           echo "exists=$([[ -n $LATEST_TAG ]] && echo true || echo false)" >> $GITHUB_OUTPUT
 
-      - name: Build main documentation
-        run: pnpm run docs:build
-        env:
-          RELEASE_VERSION: ${{ steps.release.outputs.tag }}
+      - name: Read CLI version for display
+        id: cli-version
+        run: |
+          CLI_VERSION=$(node -p "require('./packages/b2c-cli/package.json').version")
+          echo "version=$CLI_VERSION" >> $GITHUB_OUTPUT
 
-      - name: Build release documentation
+      - name: Build dev documentation
+        run: |
+          IS_DEV_BUILD=true RELEASE_VERSION=${{ steps.cli-version.outputs.version }} pnpm run docs:build
+          mv docs/.vitepress/dist docs/.vitepress/dist-dev
+
+      - name: Build stable documentation from release tag
         if: steps.release.outputs.exists == 'true'
         run: |
-          # Save main build and config (config has version dropdown code)
-          mv docs/.vitepress/dist docs/.vitepress/dist-main
+          # Save config from main (has version dropdown and dynamic base path)
           cp docs/.vitepress/config.mts /tmp/config.mts
 
           # Remove S3-extracted uxstudio files before checkout to avoid conflicts
@@ -87,14 +111,17 @@ jobs:
           # Restore config from main (has version dropdown and dynamic base path)
           cp /tmp/config.mts docs/.vitepress/config.mts
 
-          # Build at release tag with main's config
+          # Build at release tag with main's config (no IS_DEV_BUILD = stable at root)
           pnpm install --frozen-lockfile
           pnpm -r run build
-          RELEASE_VERSION=${{ steps.release.outputs.tag }} IS_RELEASE_BUILD=true pnpm run docs:build
+          RELEASE_VERSION=${{ steps.cli-version.outputs.version }} pnpm run docs:build
+
+          # Combine: stable at root, dev in /dev/
+          mv docs/.vitepress/dist-dev docs/.vitepress/dist/dev
 
-          # Combine: main at root, release in /release/
-          mv docs/.vitepress/dist docs/.vitepress/dist-main/release
-          mv docs/.vitepress/dist-main docs/.vitepress/dist
+      - name: Use dev as root when no release exists
+        if: steps.release.outputs.exists != 'true'
+        run: mv docs/.vitepress/dist-dev docs/.vitepress/dist
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3

.github/workflows/publish.yml

@@ -27,6 +27,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0 # Needed for docs tag detection
 
       - name: Determine release type
         id: release-type
@@ -81,6 +83,16 @@ jobs:
           check_package "@salesforce/b2c-cli" "packages/b2c-cli" "cli"
           check_package "@salesforce/b2c-dx-mcp" "packages/b2c-dx-mcp" "mcp"
 
+          # Check if docs version changed (private package — not published to npm, uses git tag)
+          DOCS_VERSION=$(node -p "require('./docs/package.json').version")
+          if git rev-parse "docs@${DOCS_VERSION}" >/dev/null 2>&1; then
+            echo "publish_docs=false" >> $GITHUB_OUTPUT
+          else
+            echo "publish_docs=true" >> $GITHUB_OUTPUT
+            echo "version_docs=${DOCS_VERSION}" >> $GITHUB_OUTPUT
+          fi
+          echo "@salesforce/b2c-docs: version=${DOCS_VERSION}"
+
       - name: Create snapshot versions
         if: steps.release-type.outputs.type == 'nightly'
         run: |
@@ -147,6 +159,14 @@ jobs:
             echo "No tags to create"
           fi
 
+      - name: Create docs tag if version changed
+        if: steps.release-type.outputs.type == 'stable' && steps.packages.outputs.publish_docs == 'true'
+        run: |
+          DOCS_TAG="docs@${{ steps.packages.outputs.version_docs }}"
+          git tag "$DOCS_TAG"
+          git push origin "$DOCS_TAG"
+          echo "Created docs tag: $DOCS_TAG"
+
       - name: Extract changelogs for release
         if: steps.release-type.outputs.type == 'stable'
         run: |
@@ -180,6 +200,13 @@ jobs:
               extract_latest packages/b2c-tooling-sdk/CHANGELOG.md
               echo ""
             fi
+
+            if [[ "${{ steps.packages.outputs.publish_docs }}" == "true" && -f docs/CHANGELOG.md ]]; then
+              echo "## Documentation"
+              echo ""
+              extract_latest docs/CHANGELOG.md
+              echo ""
+            fi
           } > /tmp/release-notes.md
 
       - name: Create GitHub Release
@@ -192,6 +219,8 @@ jobs:
             RELEASE_TAG="@salesforce/b2c-tooling-sdk@${{ steps.packages.outputs.version_sdk }}"
           elif [[ "${{ steps.packages.outputs.publish_mcp }}" == "true" ]]; then
             RELEASE_TAG="@salesforce/b2c-dx-mcp@${{ steps.packages.outputs.version_mcp }}"
+          elif [[ "${{ steps.packages.outputs.publish_docs }}" == "true" ]]; then
+            RELEASE_TAG="docs@${{ steps.packages.outputs.version_docs }}"
           else
             echo "No packages published, skipping release"
             exit 0
@@ -224,10 +253,16 @@ jobs:
           elif [[ "${{ steps.packages.outputs.publish_mcp }}" == "true" ]]; then
             RELEASE_TAG="@salesforce/b2c-dx-mcp@${{ steps.packages.outputs.version_mcp }}"
           else
-            echo "No release to upload to"
+            echo "No package release to upload to"
             exit 0
           fi
 
           gh release upload "$RELEASE_TAG" b2c-skills.zip b2c-cli-skills.zip
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Trigger documentation deployment
+        if: steps.release-type.outputs.type == 'stable'
+        run: gh workflow run deploy-docs.yml
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/.vitepress/config.mts

@@ -3,11 +3,11 @@ import typedocSidebar from '../api/typedoc-sidebar.json';
 
 // Version configuration from environment
 const releaseVersion = process.env.RELEASE_VERSION || 'unreleased';
-const isReleaseBuild = process.env.IS_RELEASE_BUILD === 'true';
+const isDevBuild = process.env.IS_DEV_BUILD === 'true';
 
-// Base paths - release build lives in /release/ subdirectory
+// Base paths - dev build lives in /dev/ subdirectory, stable/release is at root
 const siteBase = '/b2c-developer-tooling';
-const basePath = isReleaseBuild ? `${siteBase}/release/` : `${siteBase}/`;
+const basePath = isDevBuild ? `${siteBase}/dev/` : `${siteBase}/`;
 
 // Build version dropdown items
 // VitePress prepends base path to links starting with /, so we use relative paths
@@ -18,19 +18,19 @@ function getVersionItems() {
     return [{text: 'Development (main)', link: '/'}];
   }
 
-  if (isReleaseBuild) {
-    // Release build: base is /b2c-developer-tooling/release/
-    // Use ../ to navigate up to main docs
+  if (isDevBuild) {
+    // Dev build: base is /b2c-developer-tooling/dev/
+    // Use ../ to navigate up to stable docs at root
     return [
-      {text: 'Development (main)', link: '../'},
-      {text: 'Latest Release', link: '/'},
+      {text: 'Latest Release', link: '../'},
+      {text: 'Development (main)', link: '/'},
     ];
   }
 
-  // Main build: base is /b2c-developer-tooling/
+  // Stable build: base is /b2c-developer-tooling/
   return [
-    {text: 'Development (main)', link: '/'},
-    {text: 'Latest Release', link: '/release/'},
+    {text: 'Latest Release', link: '/'},
+    {text: 'Development (main)', link: '/dev/'},
   ];
 }
 
@@ -99,15 +99,15 @@ document.addEventListener('click', (e) => {
   if (!link) return;
   const href = link.getAttribute('href');
   // Check if this is a version switch link
-  if (href && (href.includes('/release/') || href === '../')) {
+  if (href && (href.includes('/dev/') || href === '../')) {
     e.preventDefault();
     e.stopPropagation();
     if (href === '../') {
-      // Navigate from /release/ back to main - construct path explicitly
+      // Navigate from /dev/ back to stable root - construct path explicitly
       // to avoid relative path issues with trailing slashes
       const path = window.location.pathname;
-      const mainPath = path.replace(/\\/release\\/.*$/, '/').replace(/\\/release$/, '/');
-      window.location.href = mainPath;
+      const stablePath = path.replace(/\\/dev\\/.*$/, '/').replace(/\\/dev$/, '/');
+      window.location.href = stablePath;
     } else {
       window.location.href = link.href;
     }
@@ -140,7 +140,7 @@ export default defineConfig({
       {text: 'CLI Reference', link: '/cli/'},
       {text: 'API Reference', link: '/api/'},
       {
-        text: isReleaseBuild ? 'Latest Release' : 'dev',
+        text: isDevBuild ? 'dev' : `v${releaseVersion}`,
         items: getVersionItems(),
       },
     ],

docs/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@salesforce/b2c-dx-docs",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Documentation for B2C Developer Tooling",
+  "devDependencies": {
+    "@salesforce/b2c-tooling-sdk": "workspace:*"
+  }
+}

pnpm-lock.yaml

@@ -1,5 +1,6 @@
 packages:
   - packages/*
+  - docs
 
 catalog:
   # Production dependencies (exact versions for published packages)