Merge remote-tracking branch 'origin/staging' into staging-v2

# Conflicts:
#	scripts/check-api-validation-contracts.ts

Author: icecrasher321

.github/workflows/ci.yml

@@ -5,6 +5,11 @@ on:
     branches: [main, staging, dev]
   pull_request:
     branches: [main, staging, dev]
+    # Docs content and markdown don't affect the app build or images; push
+    # runs stay unfiltered because they feed the deploy pipeline.
+    paths-ignore:
+      - 'apps/docs/content/**'
+      - '**/*.md'
 
 concurrency:
   group: ci-${{ github.ref }}
@@ -24,6 +29,7 @@ jobs:
   detect-version:
     name: Detect Version
     runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 5
     if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/staging' || github.ref == 'refs/heads/dev')
     outputs:
       version: ${{ steps.extract.outputs.version }}
@@ -76,6 +82,7 @@ jobs:
     needs: [detect-version, migrate-dev]
     if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
     runs-on: blacksmith-8vcpu-ubuntu-2404
+    timeout-minutes: 30
     permissions:
       contents: read
       id-token: write
@@ -139,6 +146,7 @@ jobs:
     needs: [migrate-dev]
     if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
     runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 15
     steps:
       - name: Checkout code
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
@@ -185,6 +193,7 @@ jobs:
       github.event_name == 'push' &&
       (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/staging')
     runs-on: blacksmith-8vcpu-ubuntu-2404
+    timeout-minutes: 30
     permissions:
       contents: read
       packages: write
@@ -284,6 +293,7 @@ jobs:
       github.event_name == 'push' &&
       (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/staging')
     runs-on: blacksmith-2vcpu-ubuntu-2404
+    timeout-minutes: 10
     permissions:
       contents: read
       id-token: write
@@ -298,19 +308,21 @@ jobs:
         id: login-ecr
         uses: aws-actions/amazon-ecr-login@d539f0932e70871a027e9d5a9d8fc38589180a64 # v2
 
-      # Re-running this job from an old run would retag the deploy tags back
-      # to that run's commit and immediately trigger a production deploy of
-      # stale code. Only promote while this commit is still the branch head;
-      # when superseded, skip cleanly — the newer run's promotion covers it.
+      # Deploy-tag moves must be monotonic: a re-run of an old run must never
+      # retag latest/staging back to stale code. A superseded first-attempt
+      # run still promotes — the ci-<ref> concurrency group executes runs
+      # serially in commit order, so an ancestor of head is a forward deploy.
       - name: Guard against stale promotion
         id: guard
+        env:
+          GH_TOKEN: ${{ github.token }}
         run: |
-          HEAD_SHA="$(git ls-remote "https://github.com/${{ github.repository }}.git" "refs/heads/${GITHUB_REF_NAME}" | cut -f1)"
-          if [ "$HEAD_SHA" != "${{ github.sha }}" ]; then
-            echo "::warning::Skipping promotion of ${{ github.sha }}: ${GITHUB_REF_NAME} has moved to ${HEAD_SHA}. Moving the deploy tags to this commit would deploy stale code; push a revert commit to roll back instead."
-            echo "fresh=false" >> $GITHUB_OUTPUT
-          else
+          STATUS="$(gh api "repos/${{ github.repository }}/compare/${{ github.sha }}...${GITHUB_REF_NAME}" --jq '.status' || echo "unknown")"
+          if [ "$STATUS" = "identical" ] || { [ "$STATUS" = "ahead" ] && [ "${{ github.run_attempt }}" = "1" ]; }; then
             echo "fresh=true" >> $GITHUB_OUTPUT
+          else
+            echo "::warning::Skipping promotion of ${{ github.sha }} (branch compare: ${STATUS}, attempt ${{ github.run_attempt }}). Moving the deploy tags here could deploy stale code; push a revert commit to roll back instead."
+            echo "fresh=false" >> $GITHUB_OUTPUT
           fi
 
       - name: Promote images to deploy tags
@@ -351,6 +363,7 @@ jobs:
   build-ghcr-arm64:
     name: Build ARM64 (GHCR Only)
     runs-on: blacksmith-8vcpu-ubuntu-2404-arm
+    timeout-minutes: 30
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     permissions:
       contents: read
@@ -399,9 +412,11 @@ jobs:
   create-ghcr-manifests:
     name: Create GHCR Manifests
     runs-on: blacksmith-2vcpu-ubuntu-2404
+    timeout-minutes: 10
     needs: [promote-images, build-ghcr-arm64, detect-version]
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     permissions:
+      contents: read
       packages: write
     strategy:
       matrix:
@@ -419,18 +434,19 @@ jobs:
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      # Same protection as promote-images: a re-run of an old run must not
-      # move the public latest tags back to a stale commit. Immutable tags
-      # (sha and version) are still published — only latest moves are gated.
+      # Same monotonic guard as promote-images, applied to the public latest
+      # tags only — immutable sha and version tags are always published.
       - name: Guard against stale latest tags
         id: guard
+        env:
+          GH_TOKEN: ${{ github.token }}
         run: |
-          HEAD_SHA="$(git ls-remote "https://github.com/${{ github.repository }}.git" "refs/heads/${GITHUB_REF_NAME}" | cut -f1)"
-          if [ "$HEAD_SHA" != "${{ github.sha }}" ]; then
-            echo "::warning::${GITHUB_REF_NAME} has moved to ${HEAD_SHA}; publishing immutable tags for ${{ github.sha }} but skipping the latest tags."
-            echo "fresh=false" >> $GITHUB_OUTPUT
-          else
+          STATUS="$(gh api "repos/${{ github.repository }}/compare/${{ github.sha }}...${GITHUB_REF_NAME}" --jq '.status' || echo "unknown")"
+          if [ "$STATUS" = "identical" ] || { [ "$STATUS" = "ahead" ] && [ "${{ github.run_attempt }}" = "1" ]; }; then
             echo "fresh=true" >> $GITHUB_OUTPUT
+          else
+            echo "::warning::Publishing immutable tags for ${{ github.sha }} but skipping the latest tags (branch compare: ${STATUS}, attempt ${{ github.run_attempt }})."
+            echo "fresh=false" >> $GITHUB_OUTPUT
           fi
 
       - name: Publish tags and manifests
@@ -462,6 +478,7 @@ jobs:
   check-docs-changes:
     name: Check Docs Changes
     runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 5
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     outputs:
       docs_changed: ${{ steps.filter.outputs.docs }}
@@ -490,6 +507,7 @@ jobs:
   create-release:
     name: Create GitHub Release
     runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 10
     needs: [create-ghcr-manifests, detect-version]
     if: needs.detect-version.outputs.is_release == 'true'
     permissions:

.github/workflows/companion-pr-check.yml

@@ -30,6 +30,7 @@ permissions:
 jobs:
   companion:
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
       - uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
         env:

.github/workflows/docs-embeddings.yml

@@ -11,6 +11,7 @@ jobs:
   process-docs-embeddings:
     name: Process Documentation Embeddings
     runs-on: blacksmith-8vcpu-ubuntu-2404
+    timeout-minutes: 30
     if: github.ref == 'refs/heads/main'
 
     steps:
@@ -25,7 +26,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: latest
+          node-version: 22
 
       - name: Cache Bun dependencies
         uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5

.github/workflows/i18n.yml

@@ -25,6 +25,7 @@ jobs:
   migrate:
     name: Apply Database Migrations
     runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 45
 
     steps:
       - name: Checkout code

.github/workflows/migrations.yml

@@ -12,6 +12,7 @@ permissions:
 jobs:
   publish-npm:
     runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 15
     steps:
       - name: Checkout repository
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6

.github/workflows/publish-cli.yml

@@ -12,6 +12,7 @@ permissions:
 jobs:
   publish-pypi:
     runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 15
     steps:
       - name: Checkout repository
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6

.github/workflows/publish-python-sdk.yml

@@ -12,6 +12,7 @@ permissions:
 jobs:
   publish-npm:
     runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 15
     steps:
       - name: Checkout repository
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6