ci: require docs lint when docs change (#25608)

Move docs linting into the required CI umbrella and reuse the existing
`changes` job so docs lint runs when docs or CI files change, plus on
`main` as a backstop.

This is motivated by the docs lint failures on #25601. That PR touched
`.claude/docs/TESTING.md`; the standalone `Docs CI` workflow picked it
up because `docs-ci.yaml` used broad `**.md` matching, but local `pnpm
lint-docs` and `make lint` did not catch the same file because they only
scanned `docs/**` plus root `*.md`. The first failed Docs CI run
reported markdownlint errors in `.claude/docs/TESTING.md` (`MD040` and
`MD031`), and the next run reported a markdown table formatter failure
in the same file.

That mismatch is why this PR exists: prevent unrelated PRs from being
surprised by stale `.claude/docs/**` lint drift only after they happen
to touch one of those files. The local docs scripts now include
`.claude/docs/**`, and the old standalone `Docs CI` workflow is removed
so we do not maintain separate path-filter logic outside the required CI
workflow.

> Generated by mux, but reviewed by a human

.github/workflows/ci.yaml

@@ -53,7 +53,8 @@ jobs:
               - "**"
             docs:
               - "docs/**"
-              - "README.md"
+              - ".claude/docs/**"
+              - "*.md"
               - "examples/web-server/**"
               - "examples/monitoring/**"
               - "examples/lima/**"
@@ -120,6 +121,28 @@ jobs:
         env:
           FILTER_JSON: ${{ toJSON(steps.filter.outputs) }}
 
+  lint-docs:
+    needs: changes
+    if: needs.changes.outputs.docs == 'true' || needs.changes.outputs.ci == 'true' || github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@f808768d1510423e83855289c910610ca9b43176 # v2.17.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Setup Node
+        uses: ./.github/actions/setup-node
+
+      - name: Check docs
+        run: pnpm check-docs
+
   # Disabled due to instability. See: https://github.com/coder/coder/issues/14553
   # Re-enable once the flake hash calculation is stable.
   # update-flake:
@@ -1132,6 +1155,7 @@ jobs:
       - changes
       - fmt
       - lint
+      - lint-docs
       - lint-actions
       - gen
       - test-go-pg
@@ -1157,6 +1181,7 @@ jobs:
           echo "- changes: ${{ needs.changes.result }}"
           echo "- fmt: ${{ needs.fmt.result }}"
           echo "- lint: ${{ needs.lint.result }}"
+          echo "- lint-docs: ${{ needs.lint-docs.result }}"
           echo "- lint-actions: ${{ needs.lint-actions.result }}"
           echo "- gen: ${{ needs.gen.result }}"
           echo "- test-go-pg: ${{ needs.test-go-pg.result }}"

.github/workflows/docs-ci.yaml

@@ -1,71 +0,0 @@
-name: Docs CI
-
-on:
-  push:
-    branches:
-      - main
-    # Self-reference removed from both push and pull_request: the `lint`
-    # and `fmt` steps gate on `tj-actions/changed-files` matching
-    # `docs/**` or `**.md`, so a workflow-only edit produced an empty
-    # run. `actionlint` and `make lint/actions` catch YAML problems
-    # before merge regardless. See DOCS-129.
-    paths:
-      - "docs/**"
-      - "**.md"
-
-  pull_request:
-    # Self-reference removed; see comment under `push:` above.
-    paths:
-      - "docs/**"
-      - "**.md"
-
-permissions:
-  contents: read
-
-jobs:
-  docs:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          persist-credentials: false
-
-      - name: Setup Node
-        uses: ./.github/actions/setup-node
-
-      # Per-tool changed-files filters. Each tool gets its own `changed-*`
-      # step scoped to the files it processes, keeping workflow-level `paths:`
-      # broad. Adding a tool (e.g. image linter) only needs a new step pair.
-      - uses: tj-actions/changed-files@22103cc46bda19c2b464ffe86db46df6922fd323 # v45.0.7
-        id: changed-md
-        with:
-          files: |
-            **.md
-          separator: ","
-
-      # Both downstream tools take file paths as argv. `tj-actions/changed-files`
-      # joins paths with `separator: ","`, which the shell does not split on, so
-      # run the output through `tr ',' '\n' | xargs -d '\n'` to hand each path to
-      # the tool as a distinct argument. This tolerates filenames containing
-      # spaces and prevents silent fallbacks: `markdownlint-cli2` would treat a
-      # comma-joined string as a single non-matching glob, and
-      # `markdown-table-formatter` would fall back to scanning every `.md` in
-      # the working tree when invoked with no positional args.
-      #
-      # `printf '%s\n'` is used instead of `echo` so a hypothetical leading
-      # `-e` or `-n` in a path is treated as data, not a bash builtin flag.
-
-      - name: lint
-        if: steps.changed-md.outputs.any_changed == 'true'
-        run: |
-          printf '%s\n' "$ALL_CHANGED_FILES" | tr ',' '\n' | xargs -d '\n' pnpm exec markdownlint-cli2
-        env:
-          ALL_CHANGED_FILES: ${{ steps.changed-md.outputs.all_changed_files }}
-
-      - name: fmt
-        if: steps.changed-md.outputs.any_changed == 'true'
-        run: |
-          printf '%s\n' "$ALL_CHANGED_FILES" | tr ',' '\n' | xargs -d '\n' pnpm exec markdown-table-formatter --check
-        env:
-          ALL_CHANGED_FILES: ${{ steps.changed-md.outputs.all_changed_files }}