Release v3.8.26 (#3875)

OmniRoute v3.8.26 — see CHANGELOG.md [3.8.26] for the full notes.

Highlights: Vertex AI media generation (#3929), GLM-5.2 effort-tier routing (#3885),
sticky round-robin combos (#3846), OpenRouter connection presets (#3878), compression
prompt-cache fix (#3936/#3890), and a security pass (form-data/vite + workflow hardening, #3949).

Co-authored-by: artickc <artickc@users.noreply.github.com>
Co-authored-by: rdself <rdself@users.noreply.github.com>
Co-authored-by: herjarsa <herjarsa@users.noreply.github.com>
Co-authored-by: Jack Smith <16862258+YunyunZhai@users.noreply.github.com>
Co-authored-by: dhaern <dhaern@users.noreply.github.com>
Co-authored-by: adivekar-utexas <adivekar-utexas@users.noreply.github.com>
Co-authored-by: megamen32 <megamen32@users.noreply.github.com>
Co-authored-by: zhiru <zhiru@users.noreply.github.com>
Co-authored-by: insoln <insoln@users.noreply.github.com>
Co-authored-by: diego-anselmo <diego-anselmo@users.noreply.github.com>

.github/workflows/ci.yml

@@ -70,6 +70,11 @@ jobs:
     runs-on: ubuntu-latest
     needs: test-coverage
     if: ${{ always() && needs.test-coverage.result == 'success' }}
+    # security-events: read lets the CodeQL ratchet read open code-scanning alerts
+    # via `gh api .../code-scanning/alerts`. contents: read keeps checkout working.
+    permissions:
+      contents: read
+      security-events: read
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
@@ -88,6 +93,15 @@ jobs:
       # coverage mergeado). Tamanho de arquivo e duplicação têm gates dedicados.
       - name: Ratchet check
         run: node scripts/quality/check-quality-ratchet.mjs --summary .artifacts/quality-ratchet.md
+      # Fase 6A.5: require-tighten — ADVISORY por enquanto (continue-on-error). Reporta
+      # quando uma métrica MELHOROU sem o baseline ter sido apertado no mesmo PR (força
+      # capturar ganhos permanentes). As métricas coverage.* carregam tightenSlack para
+      # o gap anti-flake (CI mergeado > baseline) não disparar falso-positivo. Promover a
+      # BLOQUEANTE no fim do ciclo removendo o `continue-on-error` (ver a nota
+      # _require_tighten_advisory em config/quality/quality-baseline.json).
+      - name: Require-tighten (advisory — flip to blocking at cycle-end)
+        continue-on-error: true
+        run: node scripts/quality/check-quality-ratchet.mjs --require-tighten
       # Catraca de duplicação (jscpd@4 sobre src+open-sse). Roda neste job (paralelo)
       # para não pesar no caminho crítico do lint.
       - name: Duplication ratchet
@@ -103,6 +117,14 @@ jobs:
         run: npm run check:cognitive-complexity
       - name: Type coverage ratchet
         run: npm run check:type-coverage
+      # CodeQL alerts ratchet — BLOQUEANTE (promovido de advisory na v3.8.26).
+      # Lê metrics.codeqlAlerts.value de quality-baseline.json e sai 1 SOMENTE numa
+      # regressão real (alertas abertos > baseline). Falha de medição (gh/auth/api)
+      # é skip gracioso com exit 0 — security-events:read no job-level permissions.
+      - name: CodeQL alerts ratchet (blocking)
+        run: npm run check:codeql-ratchet
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Append summary
         if: always()
         run: cat .artifacts/quality-ratchet.md >> "$GITHUB_STEP_SUMMARY"
@@ -114,17 +136,23 @@ jobs:
           path: .artifacts/quality-ratchet.md
           if-no-files-found: warn
 
-  # Phase 7 extended quality gates — ADVISORY (continue-on-error). The 5 npm-based
-  # ratchets (dead-code/cognitive-complexity/type-coverage/circular-deps/bundle-size)
-  # run for real. The external scans (vuln/secrets/workflows) skip gracefully until the
-  # owner adds install steps for osv-scanner/gitleaks/actionlint/zizmor; CodeQL ratchet
-  # works via the runner's gh token. SonarQube needs SONAR_TOKEN/SONAR_HOST_URL secrets.
+  # Phase 7 extended quality gates — ADVISORY (continue-on-error). The npm-based
+  # ratchets that remain here (circular-deps/bundle-size) run for real. The external
+  # scans (vuln/secrets/workflows) install via GitHub release downloads and skip
+  # gracefully if a binary is still absent. The CodeQL ratchet was PROMOTED to a
+  # blocking step in the quality-gate job (v3.8.26) — no longer runs here.
+  # SonarQube needs SONAR_TOKEN/SONAR_HOST_URL secrets.
   quality-extended:
     name: Quality Gates (Extended, advisory)
     runs-on: ubuntu-latest
     continue-on-error: true
     steps:
+      # fetch-depth: 0 — the OpenAPI breaking-change gate (oasdiff) reads the base
+      # spec via `git show <base_ref>:docs/reference/openapi.yaml`; a shallow clone
+      # would lack the base ref and the gate would self-skip (base-unresolved).
       - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
       - uses: actions/setup-node@v6
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
@@ -136,30 +164,70 @@ jobs:
         run: npm run check:circular-deps
       - name: Bundle size
         run: npm run check:bundle-size
-      - name: CodeQL alerts ratchet
-        run: npm run check:codeql-ratchet
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      # Fase 7 INT: install the advisory security scanners so the gates below
-      # actually run (they self-skip when the binaries are absent). go install
-      # uses documented module paths (no fragile version-pinned URLs); zizmor is
-      # a PyPI package. Whole job is continue-on-error, so an install hiccup never
-      # blocks the build. Exercised at the next release→main run.
+      # CodeQL ratchet foi PROMOVIDO a BLOQUEANTE no job quality-gate (v3.8.26) —
+      # não roda aqui para evitar duplo run/duplo report.
+      # Install the advisory security scanners so the gates below actually run
+      # (they self-skip when the binaries are absent). Robustness lessons baked in:
+      #   • `go install …/gitleaks/v8@latest` produces a binary WITHOUT the version
+      #     ldflags gitleaks needs (and often fails) — avoided.
+      #   • `curl …api.github.com/…/releases/latest` is UNAUTHENTICATED and
+      #     rate-limited to 60 req/hr/IP; when throttled it returns an empty body,
+      #     so the asset URL resolves to nothing and the install silently no-ops —
+      #     every gate then self-skips and the metric is never produced. We instead
+      #     use `gh release download`, which is preinstalled on GitHub runners and
+      #     authenticated via GITHUB_TOKEN (5000 req/hr) — robust under load.
+      #   • actionlint keeps its official download script; zizmor stays on pipx.
+      # We `set +e` (no single failure aborts the step), ALWAYS export $GITHUB_PATH
+      # at the end, and print diagnostics so the next CI run proves exactly what
+      # installed. The job is continue-on-error too, so an install hiccup never
+      # blocks the build.
       - name: Install advisory security scanners (gitleaks/osv/actionlint/zizmor)
         continue-on-error: true
+        env:
+          GH_TOKEN: ${{ github.token }}
         run: |
-          go install github.com/rhysd/actionlint/cmd/actionlint@latest
-          go install github.com/gitleaks/gitleaks/v8@latest
-          go install github.com/google/osv-scanner/v2/cmd/osv-scanner@latest
-          echo "$HOME/go/bin" >> "$GITHUB_PATH"
+          set +e
+          mkdir -p "$HOME/.local/bin"
+          # gitleaks — download latest linux x64 tarball via gh (authed), extract binary
+          rm -rf /tmp/gl && mkdir -p /tmp/gl
+          gh release download --repo gitleaks/gitleaks --pattern '*linux_x64.tar.gz' --dir /tmp/gl
+          tar -xzf /tmp/gl/*linux_x64.tar.gz -C "$HOME/.local/bin" gitleaks
+          # osv-scanner — download latest linux amd64 bare binary via gh (authed)
+          rm -rf /tmp/osv && mkdir -p /tmp/osv
+          gh release download --repo google/osv-scanner --pattern '*linux_amd64' --dir /tmp/osv
+          install -m 0755 /tmp/osv/*linux_amd64 "$HOME/.local/bin/osv-scanner"
+          # actionlint — official download script
+          bash <(curl -fsSL https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash) latest "$HOME/.local/bin"
+          # zizmor — PyPI (pipx preferred, pip --user fallback); lands in ~/.local/bin
           pipx install zizmor || pip install --user zizmor
+          # oasdiff — download latest linux amd64 tarball via gh (authed), extract binary
+          rm -rf /tmp/oasd && mkdir -p /tmp/oasd
+          gh release download --repo oasdiff/oasdiff --pattern '*linux_amd64.tar.gz' --dir /tmp/oasd
+          tar -xzf /tmp/oasd/*linux_amd64.tar.gz -C "$HOME/.local/bin" oasdiff
+          # ALWAYS export the bin dir (even if any step above failed)
           echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          # diagnostics — prove what installed on the next CI run
+          ls -la "$HOME/.local/bin"
+          "$HOME/.local/bin/gitleaks" version || true
+          "$HOME/.local/bin/actionlint" -version || true
+          "$HOME/.local/bin/osv-scanner" --version || true
+          "$HOME/.local/bin/oasdiff" --version || true
+          zizmor --version || true
       - name: Secret scan (gitleaks; skips if absent)
         run: npm run check:secrets
       - name: Vulnerability ratchet (osv-scanner; skips if absent)
         run: npm run check:vuln-ratchet
       - name: Workflow lint (actionlint+zizmor; skips if absent)
         run: npm run check:workflows
+      # OpenAPI breaking-change detection (oasdiff). Diffs the PR's public API
+      # contract (docs/reference/openapi.yaml) against the base branch's spec.
+      # ADVISORY: reports `openapiBreaking=N` and self-skips when oasdiff is absent
+      # or the base spec can't be resolved. BASE_REF is read by the script from the
+      # env (never interpolated into a shell body) — workflow-injection-safe.
+      - name: OpenAPI breaking-change (oasdiff; advisory)
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: npm run check:openapi-breaking
 
   docs-sync-strict:
     name: Docs Sync (Strict)
@@ -188,6 +256,30 @@ jobs:
       - name: i18n translation drift (warn)
         run: node scripts/i18n/check-translation-drift.mjs --warn
 
+  docs-lint:
+    name: Docs Lint (prose — advisory)
+    runs-on: ubuntu-latest
+    # Advisory (warning-first): prose/markdown style must not block merges while the
+    # existing doc corpus is brought up to style. Promote to blocking once it converges.
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - name: markdownlint (docs + root, advisory)
+        run: npx --yes markdownlint-cli2 "docs/**/*.md" "*.md" "!docs/i18n" "!docs/research" || true
+      - name: Vale prose lint (Microsoft style, advisory)
+        # Non-fatal: a Vale/reviewdog setup error must not turn this advisory job red.
+        continue-on-error: true
+        uses: errata-ai/vale-action@reviewdog
+        with:
+          files: docs
+          fail_on_error: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
   i18n-ui-coverage:
     name: i18n UI Coverage
     runs-on: ubuntu-latest
@@ -229,8 +321,14 @@ jobs:
           python-version: "3.12"
 
       - name: Validate ${{ matrix.lang }}
+        env:
+          # Pass the matrix value via env (never interpolate ${{ ... }} straight
+          # into the run: script body) so the shell receives a variable, not
+          # inlined text — zizmor template-injection mitigation. Named MATRIX_LANG
+          # to avoid clobbering the POSIX `LANG` locale variable.
+          MATRIX_LANG: ${{ matrix.lang }}
         run: |
-          python3 scripts/i18n/validate_translation.py quick -l '${{ matrix.lang }}' > result.txt
+          python3 scripts/i18n/validate_translation.py quick -l "$MATRIX_LANG" > result.txt
 
       - name: Upload result
         if: always()
@@ -511,10 +609,11 @@ jobs:
           path: coverage-shards/
           merge-multiple: true
       - name: Merge + report + gate
-        # Merging 8 shards of raw v8 coverage is memory-heavy; the default Node
-        # heap OOMs (exit 134). Raise it for the c8 merge/report step.
+        # Merging 8 shards of raw v8 coverage is memory-heavy; the 6 GB heap can
+        # still OOM on large PR runs. Keep this job focused on the gate and
+        # JSON summary that downstream ratchets consume.
         env:
-          NODE_OPTIONS: --max-old-space-size=6144
+          NODE_OPTIONS: --max-old-space-size=8192
         run: |
           mkdir -p coverage
           if [ ! -d coverage-shards ] || ! find coverage-shards -maxdepth 1 -type f -name '*.json' | grep -q .; then
@@ -532,9 +631,7 @@ jobs:
             --temp-directory coverage-shards \
             --reports-dir coverage \
             --reporter=text-summary \
-            --reporter=html \
             --reporter=json-summary \
-            --reporter=lcov \
             --exclude=tests/** \
             --exclude=**/*.test.* \
             --check-coverage \
@@ -563,7 +660,6 @@ jobs:
           name: coverage-report
           path: |
             coverage/coverage-summary.json
-            coverage/lcov.info
             coverage/coverage-report.md
           if-no-files-found: warn
 

.github/workflows/electron-release.yml

@@ -33,11 +33,18 @@ jobs:
 
       - name: Validate version format
         id: validate
+        env:
+          # Pass workflow context via env (never interpolate ${{ ... }} straight
+          # into the run: script body) so the shell receives variables, not
+          # inlined text — zizmor template-injection mitigation. INPUT_VERSION is
+          # the operator-supplied value and is regex-validated below before use.
+          EVENT_NAME: ${{ github.event_name }}
+          INPUT_VERSION: ${{ inputs.version }}
         run: |
-          if [[ "${{ github.event_name }}" == "push" ]]; then
+          if [[ "$EVENT_NAME" == "push" ]]; then
             VERSION="${GITHUB_REF#refs/tags/}"
           else
-            VERSION="${{ inputs.version }}"
+            VERSION="$INPUT_VERSION"
           fi
 
           if [[ ! "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
@@ -114,8 +121,13 @@ jobs:
 
       - name: Sync version in electron/package.json
         shell: bash
+        env:
+          # Pass the validated version via env (never interpolate ${{ ... }}
+          # straight into the run: script body) — zizmor template-injection
+          # mitigation. Already regex-validated (^v[0-9]+\.[0-9]+\.[0-9]+$) in
+          # the `validate` job, so it cannot carry shell metacharacters.
+          VERSION: ${{ needs.validate.outputs.version }}
         run: |
-          VERSION="${{ needs.validate.outputs.version }}"
           VERSION_NO_V="${VERSION#v}"
           node -e "
             const fs = require('fs');
@@ -212,14 +224,20 @@ jobs:
           merge-multiple: true
 
       - name: Create source archives
+        env:
+          # Pass the validated version via env (never interpolate ${{ ... }}
+          # straight into the run: script body) — zizmor template-injection
+          # mitigation. Already regex-validated (^v[0-9]+\.[0-9]+\.[0-9]+$) in
+          # the `validate` job, so it cannot carry shell metacharacters.
+          VERSION: ${{ needs.validate.outputs.version }}
         run: |
           # Create source code archives (excluding dev dependencies and build artifacts)
-          export TARBALL="OmniRoute-${{ needs.validate.outputs.version }}.source.tar.gz"
-          export ZIPBALL="OmniRoute-${{ needs.validate.outputs.version }}.source.zip"
+          export TARBALL="OmniRoute-${VERSION}.source.tar.gz"
+          export ZIPBALL="OmniRoute-${VERSION}.source.zip"
 
           # Use git archive for clean source export
-          git archive --format=tar.gz --prefix=OmniRoute-${{ needs.validate.outputs.version }}/ HEAD -o "release-assets/$TARBALL"
-          git archive --format=zip --prefix=OmniRoute-${{ needs.validate.outputs.version }}/ HEAD -o "release-assets/$ZIPBALL"
+          git archive --format=tar.gz --prefix="OmniRoute-${VERSION}/" HEAD -o "release-assets/$TARBALL"
+          git archive --format=zip --prefix="OmniRoute-${VERSION}/" HEAD -o "release-assets/$ZIPBALL"
 
           echo "✓ Created source archives:"
           ls -lh "release-assets/$TARBALL" "release-assets/$ZIPBALL"

.github/workflows/nightly-llm-security.yml

@@ -43,16 +43,35 @@ jobs:
   garak:
     name: garak probes (skip without provider secret)
     runs-on: ubuntu-latest
-    if: ${{ secrets.PROMPTFOO_PROVIDER_KEY != '' }}
+    # NOTE: the `secrets` context is NOT available in a job-level `if:` — referencing
+    # it there makes GitHub reject the file on push (startup_failure on every push).
+    # Map the secret into a job-level env and gate each step on a presence check, so
+    # the job stays green and simply skips the probes when the secret is absent.
+    env:
+      PROMPTFOO_PROVIDER_KEY: ${{ secrets.PROMPTFOO_PROVIDER_KEY }}
     steps:
+      - name: Gate on provider secret
+        id: gate
+        run: |
+          if [ -n "$PROMPTFOO_PROVIDER_KEY" ]; then
+            echo "run=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "run=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::PROMPTFOO_PROVIDER_KEY not set — skipping garak probes (advisory)."
+          fi
       - uses: actions/checkout@v6
+        if: steps.gate.outputs.run == 'true'
       - uses: actions/setup-node@v6
+        if: steps.gate.outputs.run == 'true'
         with: { node-version: "24", cache: npm }
       - run: npm ci
+        if: steps.gate.outputs.run == 'true'
       - name: Build CLI bundle
+        if: steps.gate.outputs.run == 'true'
         env: { JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation }
         run: npm run build:cli
       - name: Start OmniRoute
+        if: steps.gate.outputs.run == 'true'
         env:
           JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
           PORT: "20128"
@@ -64,13 +83,16 @@ jobs:
             sleep 2
           done
       - uses: actions/setup-python@v5
+        if: steps.gate.outputs.run == 'true'
         with: { python-version: "3.12" }
       - run: pip install garak
+        if: steps.gate.outputs.run == 'true'
       - name: garak limited probes
+        if: steps.gate.outputs.run == 'true'
         env:
           OPENAI_API_KEY: ${{ secrets.PROMPTFOO_PROVIDER_KEY }}
           OPENAI_BASE_URL: http://localhost:20128/v1
         run: garak --model_type openai --model_name gpt-4o-mini --probes promptinject,dan,leakreplay --report_prefix garak-omniroute || true
       - name: Stop server
-        if: always()
+        if: always() && steps.gate.outputs.run == 'true'
         run: kill "$(cat server.pid)" || true

.github/workflows/nightly-mutation.yml

@@ -0,0 +1,37 @@
+name: Nightly Mutation
+on:
+  schedule:
+    - cron: "17 3 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  stryker:
+    name: Stryker mutation testing (8 critical modules — advisory)
+    runs-on: ubuntu-latest
+    # Mutation testing is expensive (~200-500 mutants, 30-90 min). It runs only
+    # on the nightly schedule / manual dispatch, never on PRs. The score is NOT
+    # yet enforced as a ratchet (wired in a later INT phase) — for now the job
+    # just produces the HTML/JSON report and uploads it as an artifact.
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: npm
+      - run: npm ci
+      - name: Run Stryker (advisory)
+        id: stryker
+        continue-on-error: true
+        run: npx stryker run
+      - name: Upload mutation report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: mutation-report
+          path: reports/mutation/
+          if-no-files-found: warn
+          retention-days: 14

.github/workflows/nightly-schemathesis.yml

@@ -0,0 +1,70 @@
+name: Nightly Schemathesis
+on:
+  schedule:
+    - cron: "23 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  schemathesis:
+    name: Schemathesis — OpenAPI contract fuzz (advisory)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with: { node-version: "24", cache: npm }
+      - run: npm ci
+      - name: Build CLI bundle
+        env: { JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation }
+        run: npm run build:cli
+      - name: Start OmniRoute (background)
+        env:
+          JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
+          PORT: "20128"
+        run: |
+          node dist/server.js > server.log 2>&1 &
+          echo $! > server.pid
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:20128/api/monitoring/health >/dev/null; then echo "server up"; break; fi
+            sleep 2
+          done
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - name: Install schemathesis
+        run: pip install schemathesis
+      - name: Schemathesis contract fuzz (advisory)
+        # Advisory gate: never fails the job. `continue-on-error` covers a crash of the
+        # step itself; `|| true` covers schemathesis exiting non-zero when it finds spec
+        # violations / upstream 500s — both are expected here (most /v1 endpoints proxy an
+        # upstream that has no provider configured in CI). The point of the nightly is to
+        # PROVE the contract is fuzzable and surface regressions, not to gate the build.
+        continue-on-error: true
+        run: |
+          schemathesis run docs/reference/openapi.yaml \
+            --url http://localhost:20128 \
+            --max-examples 20 \
+            --workers 4 \
+            --checks all \
+            --max-response-time 30 \
+            --request-timeout 30 \
+            --suppress-health-check all \
+            --report junit \
+            --report-junit-path schemathesis-report/junit.xml \
+            --no-color \
+            || true
+      - name: Stop server
+        if: always()
+        run: kill "$(cat server.pid)" || true
+      - name: Upload schemathesis report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: schemathesis-report
+          path: |
+            schemathesis-report/
+            server.log
+          if-no-files-found: warn
+          retention-days: 14

.github/workflows/wiki-sync.yml

@@ -0,0 +1,69 @@
+name: Wiki Sync
+
+# Keeps the GitHub wiki in sync with docs/ on every release that lands on main.
+# The wiki has no native generator and historically drifts (it sat at "212+ providers /
+# 14 strategies / 37 MCP tools" while code was at 226 / 15 / 87, and new docs like
+# SUPPLY_CHAIN never appeared). This runs scripts/docs/sync-wiki.mjs, which:
+#   - ADDS any docs/ page missing from the wiki (curated; internal reports excluded),
+#   - syncs the four cover-page counts on Home.md.
+# It does NOT overwrite existing wiki pages by default: several docs sources still carry
+# stale counts (e.g. ARCHITECTURE.md says "177 providers" while the wiki cover is 226),
+# so blind overwrite would regress the wiki. Full content parity (--update-existing) is
+# gated on regenerating those sources — see docs/ops/DOCUMENTATION_AUDIT_REPORT.md.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "README.md"
+      - "AGENTS.md"
+      - "src/shared/constants/routingStrategies.ts"
+      - "config/i18n.json"
+      - "open-sse/mcp-server/server.ts"
+      - "scripts/docs/sync-wiki.mjs"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: wiki-sync
+  cancel-in-progress: false
+
+jobs:
+  sync-wiki:
+    name: Sync wiki with docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+
+      - name: Clone wiki
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+        run: |
+          git clone "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.wiki.git" wiki
+
+      - name: Sync wiki (add missing pages + cover counts)
+        run: node scripts/docs/sync-wiki.mjs --wiki-dir wiki
+
+      - name: Commit & push if changed
+        run: |
+          cd wiki
+          if [ -n "$(git status --porcelain)" ]; then
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git add -A
+            git commit -m "docs(wiki): auto-sync pages + cover counts with docs"
+            git push
+            echo "Wiki updated."
+          else
+            echo "Wiki already in sync — nothing to push."
+          fi