chore(ci): add automated Surge preview deploy workflow

.github/workflows/surge-preview.yaml

@@ -0,0 +1,80 @@
+name: Surge Preview
+
+on:
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: 'PR number (used for deploy domain: opentdf-docs-pr-{number}.surge.sh)'
+        required: true
+      teardown:
+        description: 'Tear down the preview instead of deploying'
+        type: boolean
+        default: false
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+    paths:
+      - 'docs/**'
+      - 'code_samples/**'
+      - 'src/**'
+      - 'static/**'
+      - 'blog/**'
+      - 'specs/**'
+      - 'docusaurus.config.ts'
+      - 'sidebars.js'
+
+jobs:
+  deploy-preview:
+    if: github.event.action != 'closed' && (github.event_name != 'workflow_dispatch' || inputs.teardown == false)
+    name: Deploy Preview
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build website
+        run: npm run build
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Deploy to Surge
+        run: npx surge build/ https://opentdf-docs-pr-${{ inputs.pr_number || github.event.number }}.surge.sh
+        env:
+          SURGE_LOGIN: ${{ secrets.SURGE_LOGIN }}
+          SURGE_TOKEN: ${{ secrets.SURGE_TOKEN }}
+
+      - name: Comment with preview URL
+        if: github.event.action == 'opened' || github.event.action == 'reopened'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '📄 Preview deployed to https://opentdf-docs-pr-${{ inputs.pr_number || github.event.number }}.surge.sh'
+            })
+
+  teardown-preview:
+    if: github.event.action == 'closed' || (github.event_name == 'workflow_dispatch' && inputs.teardown == true)
+    name: Teardown Preview
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Teardown Surge preview
+        run: npx surge teardown opentdf-docs-pr-${{ inputs.pr_number || github.event.number }}.surge.sh
+        env:
+          SURGE_LOGIN: ${{ secrets.SURGE_LOGIN }}
+          SURGE_TOKEN: ${{ secrets.SURGE_TOKEN }}

AGENTS.md

@@ -35,16 +35,13 @@
 
 ## Preview Deployment
 
-After opening a PR, deploy a Surge preview so reviewers can see the changes live. Use the ticket number as the identifier.
+Surge previews are deployed automatically by CI when a PR is opened or updated (for content-affecting changes). The preview URL is posted as a PR comment on first open:
 
-```bash
-npm run build
-npx surge build opentdf-docs-preview-<ticket-number>.surge.sh
+```
+https://opentdf-docs-pr-<pr-number>.surge.sh
 ```
 
-Preview URL: `https://opentdf-docs-preview-<ticket-number>.surge.sh/`
-
-A free Surge account is required — first run will prompt to sign up or log in.
+To trigger a preview manually (e.g. for a PR with only config changes), use the **Surge Preview** workflow dispatch from the Actions tab, providing the PR number.
 
 ## Commit & Pull Request Guidelines
 

README.md

@@ -163,32 +163,15 @@
 
 ### Preview Deployment
 
-Deploy to a Surge preview domain for testing changes before merging to production. **A free Surge account is required** - you'll be prompted to sign up the first time you deploy.
+Surge previews are deployed automatically by CI when a PR is opened or updated (for content-affecting changes). A comment is posted on the PR with the preview URL on first open:
 
-**Important:** Each developer should use a unique preview domain name to avoid conflicts. Use a descriptive name based on your ticket number or feature:
-
-```bash
-# Build the site
-npm run build
-
-# Deploy to your unique preview URL
-# Replace <your-identifier> with your ticket number or feature name
-npx surge build opentdf-docs-preview-<your-identifier>.surge.sh
 ```
-
-**Examples:**
-
-```bash
-# Using ticket number
-npx surge build opentdf-docs-preview-dspx-2345.surge.sh
-
-# Using feature description
-npx surge build opentdf-docs-preview-troubleshooting-updates.surge.sh
+https://opentdf-docs-pr-<pr-number>.surge.sh
 ```
 
-Your preview will be available at `https://opentdf-docs-preview-<your-identifier>.surge.sh/`
+The preview is torn down automatically when the PR is closed.
 
-**Note:** The first time you deploy, Surge will prompt you to create a free account or login.
+To trigger a preview manually (e.g. for a PR with only config changes), use the **Surge Preview** workflow dispatch from the Actions tab, providing the PR number.
 
 ---