feat(docs): rebuild documentation with the shared Sim design system

.gitattributes

@@ -41,3 +41,6 @@ Dockerfile* text eol=lf
 *.ttf binary
 *.eot binary
 *.pdf binary
+
+apps/docs/migration/report.json linguist-generated=true
+apps/docs/migration/verification/** linguist-generated=true

.github/workflows/checks.yml

@@ -684,6 +684,9 @@ jobs:
           tar -xzf "$archive" -C "$RUNNER_TEMP" actionlint
           "$RUNNER_TEMP/actionlint" -color -shellcheck= -pyflakes=
 
+      - name: Generate documentation modules for import audits
+        run: bun run --cwd apps/docs content:generate
+
       # Every zero-argument `check:*` script, run concurrently. The list is derived in
       # scripts/run-audits.ts, which also writes the per-audit timing table to the job
       # summary and annotates failures. Audits needing a base ref stay separate below.

.github/workflows/ci.yml

@@ -1149,9 +1149,20 @@ jobs:
         with:
           filters: |
             docs:
-              - 'apps/docs/content/docs/**'
-              - 'apps/sim/scripts/process-docs.ts'
-              - 'apps/sim/lib/chunkers/**'
+              - 'apps/docs/content/**'
+              - 'apps/docs/components/workflow-preview/examples.ts'
+              - 'apps/docs/components/workflow-preview/block-display-workflows.ts'
+              - 'apps/docs/scripts/compile-content.ts'
+              - 'apps/docs/scripts/index-search.ts'
+              - 'apps/docs/lib/content/**'
+              - 'apps/docs/lib/search/**'
+              - 'apps/docs/lib/openapi-specs.ts'
+              - 'apps/docs/lib/urls.ts'
+              - 'apps/docs/openapi*.json'
+              - 'apps/docs/package.json'
+              - 'bun.lock'
+              - '.github/workflows/docs.yml'
+              - '.github/workflows/ci.yml'
 
   # Process docs embeddings (only when docs change, after images are promoted)
   docs:

.github/workflows/docs-negotiation.yml

@@ -17,51 +17,242 @@ on:
       - 'bun.lock'
       - '.github/workflows/docs-negotiation.yml'
   workflow_dispatch:
+    inputs:
+      benchmark:
+        description: Run bounded production navigation, image and Lighthouse measurements
+        type: boolean
+        default: false
+      build_ref:
+        description: Commit to build for the benchmark (empty uses this workflow revision)
+        type: string
+        default: ''
+      preview_artifact:
+        description: Save the verified production build for local visual inspection
+        type: boolean
+        default: false
+      benchmark_scope:
+        description: Full measurements, navigation without Lighthouse, or only interactive controls
+        type: choice
+        options: [full, navigation, interactions]
+        default: full
+      benchmark_production:
+        description: Also measure the public production origin (only when it permits automated access)
+        type: boolean
+        default: false
 
 permissions:
   contents: read
 
 concurrency:
-  group: docs-negotiation-${{ github.ref }}
-  cancel-in-progress: true
+  group: docs-negotiation-${{ github.ref }}-${{ inputs.benchmark && 'benchmark' || 'verification' }}
+  cancel-in-progress: ${{ !inputs.benchmark }}
 
 jobs:
+  benchmark:
+    if: github.event_name == 'workflow_dispatch' && inputs.benchmark
+    name: docs benchmark (${{ matrix.target }})
+    runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-8vcpu-ubuntu-2404' || 'linux-x64-8-core' }}
+    timeout-minutes: 150
+    strategy:
+      fail-fast: false
+      max-parallel: 2
+      matrix:
+        target: ${{ fromJSON(inputs.benchmark_production && '["build","production"]' || '["build"]') }}
+    env:
+      DATABASE_URL: ''
+      OPENAI_API_KEY: ''
+      DOCS_BENCHMARK_BASE_URL: ${{ matrix.target == 'production' && 'https://docs.sim.ai' || 'http://127.0.0.1:3001' }}
+    steps:
+      - name: Checkout measured revision
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
+        with:
+          ref: ${{ inputs.build_ref || github.sha }}
+          fetch-depth: 0
+          filter: blob:none
+      - name: Setup workspace
+        uses: ./.github/actions/setup
+        with:
+          provider: ${{ vars.CI_PROVIDER }}
+      - name: Checkout benchmark harness
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
+        with:
+          ref: ${{ github.sha }}
+          path: .readiness-harness
+          sparse-checkout: apps/docs/scripts/benchmark-readiness.ts
+          sparse-checkout-cone-mode: false
+      - name: Prepare measurements
+        env:
+          GH_TOKEN: ${{ github.token }}
+          MEASURED_TARGET: ${{ matrix.target }}
+        run: |
+          mkdir -p test-results/benchmark
+          cp .readiness-harness/apps/docs/scripts/benchmark-readiness.ts apps/docs/scripts/benchmark-readiness.ts
+          if [ "$MEASURED_TARGET" = production ]; then
+            gh api "repos/$GITHUB_REPOSITORY/deployments?environment=Production&per_page=1" >test-results/benchmark/deployment.json
+            # Candidate deployments do not establish which revision owns the public alias.
+            REVISION=unverified-public-origin
+          else
+            REVISION=$(git rev-parse HEAD)
+          fi
+          echo "DOCS_BENCHMARK_REVISION=$REVISION" >> "$GITHUB_ENV"
+          bunx --no-install playwright install --with-deps chromium
+      - name: Build measured production docs
+        id: build
+        if: matrix.target == 'build'
+        run: bun run --cwd apps/docs build
+      - name: Measure navigation and Lighthouse sequentially
+        env:
+          BENCHMARK_SCOPE: ${{ inputs.benchmark_scope || 'full' }}
+        run: |
+          if [ "$DOCS_BENCHMARK_BASE_URL" = http://127.0.0.1:3001 ]; then
+            bun run --cwd apps/docs start --port 3001 >test-results/benchmark/server.log 2>&1 &
+            DOCS_SERVER_PID=$!
+            trap 'kill "$DOCS_SERVER_PID" 2>/dev/null || true' EXIT
+            for attempt in $(seq 1 30); do
+              curl -fsS "$DOCS_BENCHMARK_BASE_URL/introduction" -o /dev/null && break
+              sleep 1
+            done
+          fi
+          NAVIGATION_STATUS=0
+          LIGHTHOUSE_STATUS=0
+          if [ "$BENCHMARK_SCOPE" = interactions ]; then
+            export DOCS_BENCHMARK_SCENARIOS=interactions
+          fi
+          DOCS_BENCHMARK_MODE=navigation DOCS_BENCHMARK_REPORT_PATH="$GITHUB_WORKSPACE/test-results/benchmark/navigation.json" bun run --cwd apps/docs scripts/benchmark-readiness.ts || NAVIGATION_STATUS=$?
+          if [ "$BENCHMARK_SCOPE" = full ]; then
+            DOCS_BENCHMARK_MODE=lighthouse DOCS_BENCHMARK_REPORT_PATH="$GITHUB_WORKSPACE/test-results/benchmark/lighthouse.json" bun run --cwd apps/docs scripts/benchmark-readiness.ts || LIGHTHOUSE_STATUS=$?
+          fi
+          test "$NAVIGATION_STATUS" -eq 0 && test "$LIGHTHOUSE_STATUS" -eq 0
+      - name: Upload measurements
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: docs-benchmark-${{ matrix.target }}
+          path: test-results/benchmark/
+          retention-days: 14
+      - name: Package measured production preview
+        if: always() && inputs.preview_artifact && steps.build.outcome == 'success'
+        run: tar -czf docs-preview-build.tar.gz --exclude='.next/cache' -C apps/docs .next .content
+      - name: Upload measured production preview
+        if: always() && inputs.preview_artifact && steps.build.outcome == 'success'
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: docs-preview-build
+          path: docs-preview-build.tar.gz
+          retention-days: 3
+
   http:
+    if: github.event_name != 'workflow_dispatch' || !inputs.benchmark
     name: docs HTTP
     runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-8vcpu-ubuntu-2404' || 'linux-x64-8-core' }}
-    timeout-minutes: 15
+    timeout-minutes: 45
+    services:
+      search-postgres:
+        image: pgvector/pgvector:pg17
+        env:
+          POSTGRES_USER: docs_test
+          POSTGRES_PASSWORD: docs_test
+          POSTGRES_DB: docs_search_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U docs_test -d docs_search_test"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
     env:
       DATABASE_URL: postgresql://docs_test:[email protected]:1/docs_test
       DOCS_E2E_BASE_URL: http://127.0.0.1:3001
-      DOCS_NEGOTIATION_REPORT_PATH: ${{ github.workspace }}/test-results/docs-negotiation.json
-      DOCS_HEADER_REPORT_PATH: ${{ github.workspace }}/test-results/docs-headers.json
-      DOCS_NAVIGATION_REPORT_PATH: ${{ github.workspace }}/test-results/navigation/docs.json
+      DOCS_NEGOTIATION_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/docs-negotiation.json
+      DOCS_SEARCH_E2E_DATABASE_URL: postgresql://docs_test:[email protected]:5432/docs_search_test
+      DOCS_SEARCH_E2E_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/search-postgres/report.json
+      DOCS_INTERFACES_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/docs-interfaces.json
+      DOCS_CORPUS_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/docs-corpus.json
+      DOCS_HEADER_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/docs-headers.json
+      DOCS_NAVIGATION_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/navigation/docs.json
+      DOCS_GENERATORS_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/generators/report.json
+      DOCS_MIGRATION_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/migration.json
+      DOCS_SAMPLES_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/samples/report.json
+      DOCS_SAMPLES_SYNTAX_LANGUAGES: javascript,python,bash,go,java,csharp
+      DOCS_SAMPLES_HTTP_BASE_URL: http://127.0.0.1:3001
+      DOCS_PROVIDER_E2E_DATABASE_URL: postgresql://docs_test:[email protected]:5432/docs_search_test
+      DOCS_PROVIDER_E2E_BASE_URL: http://127.0.0.1:3001
+      DOCS_PROVIDER_E2E_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/platform-consumer/report.json
     steps:
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
+        with:
+          fetch-depth: 0
+          filter: blob:none
       - name: Setup workspace
         uses: ./.github/actions/setup
         with:
           provider: ${{ vars.CI_PROVIDER }}
       - name: Build production docs
+        id: build
         run: bun run --cwd apps/docs build
+      - name: Verify generator idempotence and authored regions
+        run: bun run --cwd apps/docs scripts/test-generators-e2e.ts
+      - name: Verify preserved routes, anchors and examples
+        if: always() && steps.build.outcome == 'success'
+        run: bun run --cwd apps/docs content:verify-migration
       - name: Verify native header edge cases
+        if: always() && steps.build.outcome == 'success'
         run: bun run --cwd apps/docs test:headers:e2e
+      - name: Verify isolated PostgreSQL search and index lifecycle
+        if: always() && steps.build.outcome == 'success'
+        run: bun run --cwd apps/docs test:search:postgres:e2e
+      - name: Set up Java for copied request examples
+        if: always() && steps.build.outcome == 'success'
+        uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5
+        with:
+          distribution: temurin
+          java-version: '17'
+      - name: Set up .NET for copied request examples
+        if: always() && steps.build.outcome == 'success'
+        uses: actions/setup-dotnet@26b0ec14cb23fa6904739307f278c14f94c95bf1 # v5
+        with:
+          dotnet-version: '8.0.x'
+      - name: Set up Go for copied request examples
+        if: always() && steps.build.outcome == 'success'
+        uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
+        with:
+          go-version: '1.25.x'
+          cache: false
       - name: Install browser for navigation checks
-        run: bunx --no-install playwright install --with-deps chromium
+        if: always() && steps.build.outcome == 'success'
+        run: bunx --no-install playwright install --with-deps chromium webkit
       - name: Verify HTTP content negotiation
+        if: always() && steps.build.outcome == 'success'
         run: |
-          mkdir -p test-results
-          bun run --cwd apps/docs start --port 3001 >test-results/docs-server.log 2>&1 &
+          mkdir -p apps/docs/test-results
+          bun run --cwd apps/docs start --port 3001 >apps/docs/test-results/docs-server.log 2>&1 &
           DOCS_SERVER_PID=$!
           trap 'kill "$DOCS_SERVER_PID" 2>/dev/null || true' EXIT
-          bun run --cwd apps/docs test:negotiation:e2e
-          bun run --cwd apps/docs test:navigation:e2e
+          STATUS=0
+          bun run --cwd apps/docs test:negotiation:e2e || STATUS=1
+          bun run --cwd apps/docs scripts/test-docs-interfaces-e2e.ts || STATUS=1
+          bun run --cwd apps/docs test:corpus:e2e || STATUS=1
+          bun run --cwd apps/docs scripts/verify-api-samples.ts || STATUS=1
+          bun --cwd apps/sim --no-env-file scripts/test-docs-search-provider-e2e.ts || STATUS=1
+          bun run --cwd apps/docs test:navigation:e2e || STATUS=1
+          DOCS_NAVIGATION_BROWSER=webkit DOCS_NAVIGATION_REPORT_PATH="$GITHUB_WORKSPACE/apps/docs/test-results/navigation-webkit/docs.json" bun run --cwd apps/docs test:navigation:e2e || STATUS=1
+          exit "$STATUS"
+      - name: Package production preview for visual inspection
+        if: always() && inputs.preview_artifact && steps.build.outcome == 'success'
+        run: tar -czf docs-preview-build.tar.gz --exclude='.next/cache' -C apps/docs .next .content
+      - name: Upload production preview
+        if: always() && inputs.preview_artifact && steps.build.outcome == 'success'
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: docs-preview-build
+          path: docs-preview-build.tar.gz
+          retention-days: 3
       - name: Upload HTTP regression report
         if: always()
         uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: docs-negotiation-report
-          path: test-results/
+          path: apps/docs/test-results/
           if-no-files-found: warn
           retention-days: 14

.github/workflows/docs.yml

@@ -7,7 +7,25 @@ on:
         required: false
       OPENAI_API_KEY:
         required: false
-  workflow_dispatch: # Allow manual triggering
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: I verified the matching docs deployment and a restorable index backup
+        type: boolean
+        required: true
+        default: false
+      deployed_revision:
+        description: Full source SHA of the verified serving docs deployment
+        type: string
+        required: true
+      deployment_id:
+        description: Verified serving docs deployment ID
+        type: string
+        required: true
+      backup_reference:
+        description: Restorable docs_embeddings backup identifier (no credentials)
+        type: string
+        required: true
 
 permissions:
   contents: read
@@ -18,23 +36,53 @@ jobs:
     # Network-bound on the embeddings API: ~9% CPU and ~3% peak memory on 8 vCPU.
     runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
     timeout-minutes: 30
-    if: github.ref == 'refs/heads/main'
+    if: github.ref == 'refs/heads/main' && github.event_name == 'workflow_dispatch' && inputs.publish
+    concurrency:
+      group: docs-search-index-production
+      cancel-in-progress: false
 
     steps:
+      - name: Record verified deployment and backup
+        env:
+          DEPLOYED_REVISION: ${{ inputs.deployed_revision }}
+          DEPLOYMENT_ID: ${{ inputs.deployment_id }}
+          BACKUP_REFERENCE: ${{ inputs.backup_reference }}
+        run: |
+          test "$DEPLOYED_REVISION" = "$GITHUB_SHA"
+          test -n "$DEPLOYMENT_ID"
+          test -n "$BACKUP_REFERENCE"
+          jq -n --arg revision "$DEPLOYED_REVISION" --arg deployment "$DEPLOYMENT_ID" \
+            --arg backup "$BACKUP_REFERENCE" --arg actor "$GITHUB_ACTOR" \
+            '{revision: $revision, deploymentId: $deployment, backupReference: $backup, verifiedBy: $actor}' \
+            > "$RUNNER_TEMP/docs-search-authorization.json"
+
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
         with:
+          ref: ${{ github.sha }}
           persist-credentials: false
 
       - name: Setup workspace
         uses: ./.github/actions/setup
         with:
           provider: ${{ vars.CI_PROVIDER }}
-          node-version: '22'
+          node-version: '24'
 
       - name: Process docs embeddings
-        working-directory: ./apps/sim
+        working-directory: ./apps/docs
         env:
           DATABASE_URL: ${{ secrets.DATABASE_URL }}
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-        run: bun run scripts/process-docs.ts --clear 
+        run: |
+          bun run content:generate
+          DOCS_SEARCH_REPORT_PATH=test-results/docs-search-publish.json bun run scripts/index-search.ts
+          DOCS_SEARCH_REPORT_PATH=test-results/docs-search-check.json bun run scripts/index-search.ts --check
+
+      - name: Upload search index report
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: docs-search-index
+          path: |
+            apps/docs/test-results/docs-search-*.json
+            ${{ runner.temp }}/docs-search-authorization.json

apps/docs/.gitignore

@@ -35,13 +35,10 @@ bun-debug.log*
 *.tsbuildinfo
 next-env.d.ts
 
-# Fumadocs
-/.source/ 
+# Build-generated content
+/.content/
 .plans/
 
-# fumadocs generates .source dirs anywhere a source.config sits
-**/.source/
-
 # Build-generated documentation asset
 /public/llms-full.txt
 /public/.llms-full-*/