docs: publish v4 and v5 docs

.github/actions/setup-docs-versioned/action.yml

@@ -0,0 +1,73 @@
+name: 'Setup Docs (Versioned)'
+description: 'Sets up everything needed to generate docs with Fern CLI for both v4 and v5'
+
+inputs:
+  v4-branch:
+    description: 'Branch name for v4 docs'
+    required: false
+    default: 'main'
+
+runs:
+  using: "composite"
+  steps:
+    - name: Setup working directories
+      shell: bash
+      run: |
+        # Clean up any stale worktree references
+        git worktree prune
+
+        # Remove existing v4 worktree if it exists
+        git worktree remove /tmp/aa-sdk-v4 --force 2>/dev/null || true
+        rm -rf /tmp/aa-sdk-v4
+
+        echo "✅ Cleaned up stale worktrees"
+
+    - name: Checkout v4 branch
+      shell: bash
+      run: |
+        git fetch origin ${{ inputs.v4-branch }}
+        git worktree add -f /tmp/aa-sdk-v4 origin/${{ inputs.v4-branch }}
+        echo "✅ Checked out ${{ inputs.v4-branch }} to /tmp/aa-sdk-v4"
+
+    - name: Extract code snippets for v4
+      shell: bash
+      run: |
+        cd /tmp/aa-sdk-v4
+        if [ -f "docs/scripts/extract-include-statements.js" ]; then
+          node docs/scripts/extract-include-statements.js
+          echo "✅ Extracted v4 code snippets"
+        else
+          echo "⚠️  extract-include-statements.js not found in v4, skipping"
+        fi
+
+    - name: Extract code snippets for v5 (current branch)
+      shell: bash
+      run: |
+        if [ -f "docs/scripts/extract-include-statements.js" ]; then
+          node docs/scripts/extract-include-statements.js
+          echo "✅ Extracted v5 code snippets"
+        else
+          echo "⚠️  extract-include-statements.js not found in v5, skipping"
+        fi
+
+    - name: Ensure docs-site submodule is up-to-date
+      shell: bash
+      run: |
+        git submodule update --init --remote docs-site/
+        echo "✅ Updated docs-site submodule"
+
+    - name: Insert versioned docs into docs-site
+      shell: bash
+      run: |
+        cd docs-site
+        ../docs/scripts/insert-docs-versioned.sh aa-sdk /tmp/aa-sdk-v4/docs $GITHUB_WORKSPACE/docs
+        echo "✅ Inserted versioned docs with tab variants"
+
+    - name: Cleanup worktrees
+      shell: bash
+      if: always()
+      run: |
+        git worktree remove /tmp/aa-sdk-v4 --force 2>/dev/null || true
+        rm -rf /tmp/aa-sdk-v4
+        echo "✅ Cleaned up temporary directories"
+

.github/workflows/on-pull-request.yml

@@ -49,14 +49,51 @@ jobs:
     steps:
       - name: Checkout aa-sdk
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for git worktree
+
+      - name: Setup Versioned Docs
+        uses: ./.github/actions/setup-docs-versioned
+        with:
+          v4-branch: main
+
+      - name: Set Build Comment to In Progress
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const workspace = process.env.GITHUB_WORKSPACE;
+            const { updatePreviewComment } = await import(`${workspace}/docs-site/scripts/preview-comment.js`);
+
+            await updatePreviewComment({
+              github,
+              context,
+              status: 'building',
+            });
 
       - name: Generate Documentation Preview
         id: preview
-        uses: ./.github/actions/preview-fern-docs
+        uses: ./.github/actions/publish-fern
         with:
           github-token: ${{ github.token }}
           fern-token: ${{ secrets.FERN_TOKEN }}
+          environment: docs-preview
           ref: ${{ github.head_ref }}
+          preview: "true"
+
+      - name: Comment Preview URL in PR
+        uses: actions/github-script@v7
+        if: always()
+        with:
+          script: |
+            const workspace = process.env.GITHUB_WORKSPACE;
+            const { updatePreviewComment } = await import(`${workspace}/docs-site/scripts/preview-comment.js`);
+
+            await updatePreviewComment({
+              github,
+              context,
+              previewUrl: '${{ steps.preview.outputs.url }}',
+              status: '${{ steps.preview.outcome }}',
+            });
 
   # TODO: Add this back when we write docs for v5
   # lint_docs:

.github/workflows/preview-fern-docs-versioned.yml.example

@@ -0,0 +1,68 @@
+name: Generate Fern Docs Preview (Versioned)
+
+# This is an EXAMPLE workflow showing how to use the versioned docs setup for previews
+# To activate this:
+#   1. Test it thoroughly
+#   2. Rename this file to remove .example extension
+#   3. Disable or remove the old preview-fern-docs.yml
+
+on:
+  pull_request:
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      deployments: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout aa-sdk (PR branch)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Need full history for worktree
+
+      - name: Setup Versioned Docs
+        uses: ./.github/actions/setup-docs-versioned
+        with:
+          v4-branch: main
+
+      - name: Set Build Comment to In Progress
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const workspace = process.env.GITHUB_WORKSPACE;
+            const { updatePreviewComment } = await import(`${workspace}/docs-site/scripts/preview-comment.js`);
+
+            await updatePreviewComment({
+              github,
+              context,
+              status: 'building',
+            });
+
+      - name: Generate Fern Docs Preview
+        id: preview
+        uses: ./.github/actions/publish-fern
+        with:
+          github-token: ${{ github.token }}
+          fern-token: ${{ secrets.FERN_TOKEN }}
+          environment: docs-preview
+          ref: ${{ github.head_ref }}
+          preview: "true"
+
+      - name: Comment Preview URL in PR
+        uses: actions/github-script@v7
+        if: always()
+        with:
+          script: |
+            const workspace = process.env.GITHUB_WORKSPACE;
+            const { updatePreviewComment } = await import(`${workspace}/docs-site/scripts/preview-comment.js`);
+
+            await updatePreviewComment({
+              github,
+              context,
+              previewUrl: '${{ steps.preview.outputs.url }}',
+              status: '${{ steps.preview.outcome }}',
+            });
+

.github/workflows/publish-fern-docs-versioned.yml.example

@@ -0,0 +1,55 @@
+name: Publish Docs (Versioned)
+
+# This is an EXAMPLE workflow showing how to use the versioned docs setup
+# To activate this:
+#   1. Test it thoroughly
+#   2. Rename this file to remove .example extension
+#   3. Disable or remove the old publish-fern-docs.yml
+
+on:
+  push:
+    branches:
+      - main  # v5 docs (post-launch)
+      - v4    # legacy v4 docs - allows updates to v4 to auto-deploy
+  workflow_dispatch:
+    inputs:
+      reason:
+        description: 'Reason for manual deploy'
+        required: false
+        default: 'Manual deployment'
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      deployments: write
+    if: ${{ github.event_name == 'push' && github.run_number > 1 }}
+    steps:
+      - name: Checkout aa-sdk (current branch)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Need full history for worktree
+
+      - name: Setup Versioned Docs
+        uses: ./.github/actions/setup-docs-versioned
+        with:
+          v4-branch: main
+
+      - name: Generate Fern Docs
+        id: publish
+        uses: ./.github/actions/publish-fern
+        with:
+          github-token: ${{ github.token }}
+          fern-token: ${{ secrets.FERN_TOKEN }}
+          environment: docs-production
+          ref: ${{ github.ref }}
+
+      - name: Trigger GitHub Pages Deploy Workflow
+        run: |
+          curl -X POST \
+            -H "Authorization: Bearer ${{ secrets.DOCS_GH_PAGES_DEPLOY_TOKEN }}" \
+            -H "Accept: application/vnd.github.v3+json" \
+            https://api.github.com/repos/alchemyplatform/docs/dispatches \
+            -d '{"event_type":"trigger-gh-pages-deploy","client_payload":{"source":"alchemyplatform/aa-sdk"}}'
+

.gitmodules

@@ -25,3 +25,4 @@
 [submodule "docs-site"]
 	path = docs-site
 	url = https://github.com/alchemyplatform/docs
+	branch = blake/update-fern