ci: skip the pipeline for documentation-only changes (#1949)

Two documentation-only PRs were running the full pipeline simultaneously
this afternoon: #1948 (`CHANGELOG.md` plus a release note) and #1947
(deleting a stale `docs/DEPLOYMENT.md`). Each spends about 12 minutes on
Go Build & Test and about 16 minutes on Playwright to establish that a
text file does not break a browser.

**The cost is the queue, not the minutes.** On the same afternoon a
`pull_request` run was created at 12:13 and its first job did not start
until 16:19. Four hours in the queue. Every unnecessary run pushes the
ones that matter further back, and this repository has been merging
heavily today.

## Checked before adding the filter

Rather than assumed:

- **Nothing reads markdown at build or test time.** Grepping every Go
and JS source for a runtime read (`ReadFile`, `readFileSync`, `os.Open`)
of a `.md` path returns nothing. The `docs/` matches in `cmd/` and
`test-*.js` are all comments pointing at documentation.
- `/api/docs` serves Swagger UI generated from `cmd/server/openapi.go`,
not from `docs/`.
- `docs/` holds markdown plus screenshots (`png`, `gif`) and no build
input.
- **This workflow has no tag trigger**, so release tagging is
unaffected; that runs from `release-fast-path.yml`. Worth stating
explicitly given a `v3.10.0` tag is imminent.

`paths-ignore` skips only when **every** changed file matches, so a PR
touching both code and documentation still runs the full pipeline.

## The trap, stated in the file

If required status checks are ever enabled on master, a skipped workflow
never reports, and a docs-only PR would wait forever on a check that
cannot arrive. At that point this needs to become a change-detection job
with conditional heavy jobs rather than a trigger filter.

Master has no required checks today. Verified: the branch protection
endpoint returns 404.

That caveat is in a comment above the `on:` block, not just in this
description, because the person who enables required checks in six
months will be reading the workflow and not this PR.

## Note

This PR itself changes only `.github/workflows/deploy.yml`, so it is not
documentation-only and will run the full pipeline, as it should.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

.github/workflows/deploy.yml

@@ -1,10 +1,33 @@
 name: CI/CD Pipeline
 
+# Documentation-only changes skip this pipeline entirely. Nothing under
+# docs/ or any *.md file is read at build or test time: no Go or JS source
+# opens one, and /api/docs serves Swagger generated from openapi.go, not
+# from docs/. Running a 16-minute Playwright suite to prove that a
+# markdown file does not break the browser only pushed the runs that do
+# matter further down a queue that has been hours deep.
+#
+# paths-ignore skips only when EVERY changed file matches, so a PR that
+# touches both code and docs still runs the full pipeline.
+#
+# Caveat if required status checks are ever enabled on master: a skipped
+# workflow never reports, so a docs-only PR would wait forever on a check
+# that cannot arrive. At that point this needs to become a change-detection
+# job with conditional heavy jobs, not a trigger filter. There are no
+# required checks on master today.
 on:
   push:
     branches: [master]
+    paths-ignore:
+      - '**/*.md'
+      - 'docs/**'
+      - 'LICENSE'
   pull_request:
     branches: [master]
+    paths-ignore:
+      - '**/*.md'
+      - 'docs/**'
+      - 'LICENSE'
   workflow_dispatch:
 
 permissions: