ci(docs): deploy Pages on wiki changes, drop the never-working Vercel job (#2746)

## Description

Two independent bugs in `.github/workflows/docs.yml`.

**1. Pages went stale because the push filter watched the wrong
directory.**

`mkdocs.yml` sets `docs_dir: wiki`, but the push filter listed `docs/**`
and not `wiki/**`. So a merge touching only `wiki/` never triggered the
workflow and the published Pages site silently went stale, while a
`docs/**`-only change triggered a Pages rebuild whose sources mkdocs
doesn't even read.

Push now filters on `wiki/**` + `mkdocs.yml`. **Pull requests keep
`docs/**`**, so `validate-nextjs` still catches a broken MDX change
before merge.

**2. `deploy-vercel` never worked — it wasn't a working path that went
stale.**

It ran `npx vercel deploy --prod --token=${{ secrets.VERCEL_TOKEN }}`,
but those secrets don't exist:

```text
$ gh api repos/headroomlabs-ai/headroom/actions/secrets --jq '.secrets[].name' | grep -i vercel
(nothing)
$ gh api orgs/headroomlabs-ai/actions/secrets  --jq '.secrets[].name' | grep -i vercel
(nothing)
```

So it invoked the CLI with an empty `--token=` and exited 1, every time:

```text
30 failed runs on main, 2026-07-14 .. 2026-08-04

most recent:
  30874173333  13a310a0  failure
  30845343100  6422a80a  failure
  30810614546  007446c7  failure

per-job on 30874173333:
  failure  Deploy Vercel Docs
  success  Deploy GitHub Pages     <- same run
  skipped  Validate mkdocs build
  skipped  Validate Next.js build
```

`deploy-github-pages` succeeded in those same runs, so this job
contributed nothing but a red X on every merge to main.

The Next.js site is published by **Vercel's own Git integration**, which
is what has actually been deploying it. Removing this job leaves exactly
one deploy path per site: Pages via mkdocs here, Vercel via its Git
integration.

## Why this PR previously said the opposite

I opened this as "drop the redundant Vercel job", then converted it to
draft and posted a correction saying the deletion was **wrong** —
because at that point the Vercel site had been stale since mid-June and
this looked like the only deploy path. That correction was itself based
on a wrong assumption: with no `VERCEL_TOKEN` configured, this job could
never have deployed anything. It wasn't the deploy path; it was a job
that had always failed. The site was stale because *nothing* was
publishing it until the Git integration was connected.

So: original intent right, first correction wrong, and the evidence
above is what settles it. Recording that rather than quietly re-flipping
the description.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- Push filter: `docs/**` → `wiki/**` (what mkdocs actually reads).
- Removed the `deploy-vercel` job.
- Replaced it with a comment recording *why* there is no Vercel job
here, so nobody re-adds one.

## Testing

- [x] Linting passes — workflow YAML parses, and the resulting shape is
what's intended:

```text
jobs:       ['validate-mkdocs', 'validate-nextjs', 'deploy-github-pages']
push paths: ['wiki/**', 'mkdocs.yml', '.github/workflows/docs.yml']
pr paths:   ['docs/**', 'wiki/**', 'mkdocs.yml', '.github/workflows/docs.yml']
```

CI is the real check for a workflow change. The observable proof after
merge is that the next push to `main` no longer reports a failing
`Deploy Vercel Docs`, and that a `wiki/**`-only change triggers a Pages
deploy (it currently does not).

## Real Behavior Proof

- **Environment:** GitHub Actions on `headroomlabs-ai/headroom`, branch
`main`.
- **Exact command / steps:** `gh run list --workflow "Deploy
Documentation" --branch main`; `gh api .../actions/secrets`; `gh run
view <id> --json jobs`.
- **Observed result:** 30 consecutive `Deploy Documentation` failures on
main attributable solely to `Deploy Vercel Docs`; no Vercel secrets
configured at repo or org level; `Deploy GitHub Pages` green throughout.

## What this does NOT fix

This is unrelated to the failing **`Vercel`** check currently showing on
~18 open PRs. That one comes from the Vercel GitHub App with
`Authorization required to deploy.` — Vercel asking each PR author to
authorize its app — and is a Vercel-side setting, not a workflow file.
Two different mechanisms that both say "Vercel":

| | mechanism | where it fails | fixed here? |
|---|---|---|---|
| `Deploy Vercel Docs` | Actions job in this file | pushes to `main` |
**yes** |
| `Vercel` / `Vercel Preview Comments` | Vercel GitHub App | contributor
PRs | no — dashboard setting |

For the record: `Vercel` is not a required status check (`template`,
`label`, `merge-conflicts`, `no-manual-changelog`, `Secret scan
(gitleaks)` are), so it has never actually blocked a merge.

.github/workflows/docs.yml

@@ -8,11 +8,18 @@ on:
       - 'wiki/**'
       - 'mkdocs.yml'
       - '.github/workflows/docs.yml'
+  # Push only deploys GitHub Pages, and `mkdocs.yml` sets `docs_dir: wiki` — so the
+  # sources that matter here are wiki/ and mkdocs.yml, NOT docs/ (that is the
+  # Next.js site, which Vercel deploys through its own Git integration).
+  #
+  # wiki/** was missing, so a merge touching only wiki/ never triggered this
+  # workflow and the published Pages site silently went stale. docs/** was present
+  # but mkdocs never reads it, so it only bought a no-op Pages rebuild.
   push:
     branches:
       - main
     paths:
-      - 'docs/**'
+      - 'wiki/**'
       - 'mkdocs.yml'
       - '.github/workflows/docs.yml'
   workflow_dispatch:
@@ -99,32 +106,13 @@ jobs:
       - name: Build and deploy
         run: mkdocs gh-deploy --force
 
-  deploy-vercel:
+# The Next.js docs site is deployed by Vercel's own Git integration, so there is no
-    name: Deploy Vercel Docs
+# deploy job for it here. A `deploy-vercel` job used to run `npx vercel deploy
-    if: >-
+# --prod` on every push to main, but VERCEL_TOKEN / VERCEL_ORG_ID /
-      github.event_name != 'pull_request'
+# VERCEL_PROJECT_ID are not configured as secrets (repo or org), so it invoked the
-      && github.ref == 'refs/heads/main'
+# CLI with an empty `--token=` and exited 1. It therefore never deployed anything:
-      && github.repository_owner == 'headroomlabs-ai'
+# 30 failed runs on main between 2026-07-14 and 2026-08-04. `deploy-github-pages`
-    runs-on: ubuntu-latest
+# succeeded in those same runs — only this job failed — so the red was pure noise.
-    permissions:
+#
-      contents: read
+# `Validate Next.js build` above still guards docs/** on pull requests, so a broken
-    steps:
+# MDX change is caught before merge.
-      - uses: actions/checkout@v6
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: '20'
-          cache: npm
-          cache-dependency-path: docs/package-lock.json
-
-      - name: Install dependencies
-        run: npm ci
-        working-directory: docs
-
-      - name: Deploy to Vercel
-        run: npx vercel deploy --prod --token=${{ secrets.VERCEL_TOKEN }}
-        working-directory: docs
-        env:
-          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
-          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}