marcleblanc2 · Oct 6, 2026 · Oct 6, 2026 · Oct 6, 2026
diff --git a/.github/workflows/check-duplicates.yml b/.github/workflows/check-duplicates.yml
@@ -0,0 +1,119 @@
+name: Check duplicated content
+
+# Reports passages a pull request adds that say the same thing as a passage
+# elsewhere under docs/, compared with the merge base, as a summary comment
+# plus an inline comment on each added passage. Duplication already on the
+# base branch is ignored. Advisory: never fails the PR.
+
+on:
+    pull_request:
+        paths:
+            - 'docs/**'
+            - 'dev/check-duplicates.mjs'
+            - 'dev/sync-review-comments.sh'
+            - '.github/workflows/check-duplicates.yml'
+
+# A new push supersedes the run for the previous one
+concurrency:
+    group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+    cancel-in-progress: true
+
+permissions:
+    contents: read
+    pull-requests: write
+
+jobs:
+    check-duplicates:
+        name: Duplicated content introduced by this PR (advisory)
+        runs-on: ubuntu-latest
+        steps:
+            - name: Check out pull request head
+              uses: actions/checkout@v4
+              with:
+                  ref: ${{ github.event.pull_request.head.sha }}
+                  fetch-depth: 0
+
+            - name: Check out merge base
+              env:
+                  BASE_SHA: ${{ github.event.pull_request.base.sha }}
+              run: |
+                  merge_base=$(git merge-base "$BASE_SHA" HEAD)
+                  git worktree add "$RUNNER_TEMP/base" "$merge_base"
+                  git diff -U0 "$merge_base" HEAD -- docs > "$RUNNER_TEMP/changes.diff"
+
+            # The script exits 1 both with findings and when it crashes. It writes
+            # its output in one go at the end, so a crash leaves it empty. A crash
+            # does not fail the check, since it says nothing about the PR; the
+            # comment step reports it instead of posting the empty report.
+            - name: Record duplicated passages already present on the base branch
+              run: |
+                  node dev/check-duplicates.mjs --format json \
+                      --root "$RUNNER_TEMP/base" > "$RUNNER_TEMP/base-duplicates.json" || true
+
+            - name: Find duplicated passages introduced by this PR
+              id: check
+              env:
+                  # File links in the report open the file on the PR branch
+                  LINK_BASE: ${{ github.event.pull_request.head.repo.html_url }}/blob/${{ github.event.pull_request.head.ref }}
+              run: |
+                  if ! [ -s "$RUNNER_TEMP/base-duplicates.json" ]; then
+                      echo "::warning::check-duplicates crashed on the base branch, so this PR was not checked"
+                      echo "result=crashed" >> "$GITHUB_OUTPUT"
+                      exit 0
+                  fi
+                  if node dev/check-duplicates.mjs --format markdown \
+                      --baseline "$RUNNER_TEMP/base-duplicates.json" \
+                      --diff "$RUNNER_TEMP/changes.diff" \
+                      --review "$RUNNER_TEMP/review.json" \
+                      --link-base "$LINK_BASE" > "$RUNNER_TEMP/report.md"; then
+                      echo "result=clean" >> "$GITHUB_OUTPUT"
+                  elif [ -s "$RUNNER_TEMP/report.md" ]; then
+                      echo "result=found" >> "$GITHUB_OUTPUT"
+                  else
+                      echo "::warning::check-duplicates crashed, so this PR was not checked"
+                      echo "result=crashed" >> "$GITHUB_OUTPUT"
+                  fi
+                  cat "$RUNNER_TEMP/report.md"
+
+            - name: Comment on the pull request
+              # Fork PRs get a read-only token; the report is still in the job log
+              if: github.event.pull_request.head.repo.full_name == github.repository
+              env:
+                  GH_TOKEN: ${{ github.token }}
+                  PR_NUMBER: ${{ github.event.pull_request.number }}
+                  RESULT: ${{ steps.check.outputs.result }}
+                  RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+              run: |
+                  marker='<!-- check-duplicates-report -->'
+                  existing_comment=$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" \
+                      --paginate --jq ".[] | select(.body | startswith(\"$marker\")) | .id" | head -n 1)
+
+                  # Comment when there is something to report, or an earlier report to resolve
+                  case "$RESULT" in
+                      found)
+                          { echo "$marker"; cat "$RUNNER_TEMP/report.md"; } > "$RUNNER_TEMP/comment.md" ;;
+                      crashed)
+                          printf '%s\n### ⚠️ The duplicated content check could not run on this revision\n\nThis is a problem with the check, not with this PR; see the [job log](%s).\n' \
+                              "$marker" "$RUN_URL" > "$RUNNER_TEMP/comment.md" ;;
+                      *)
+                          [ -n "$existing_comment" ] || exit 0
+                          { echo "$marker"; cat "$RUNNER_TEMP/report.md"; } > "$RUNNER_TEMP/comment.md" ;;
+                  esac
+
+                  if [ -n "$existing_comment" ]; then
+                      gh api --method PATCH "repos/$GITHUB_REPOSITORY/issues/comments/$existing_comment" \
+                          --field body=@"$RUNNER_TEMP/comment.md"
+                  else
+                      gh pr comment "$PR_NUMBER" --body-file "$RUNNER_TEMP/comment.md"
+                  fi
+
+            - name: Point out the duplicates as review comments
+              # One comment per added passage, kept in sync with the findings;
+              # see dev/sync-review-comments.sh
+              if: >-
+                  github.event.pull_request.head.repo.full_name == github.repository
+                  && contains(fromJSON('["clean", "found"]'), steps.check.outputs.result)
+              env:
+                  GH_TOKEN: ${{ github.token }}
+                  PR_NUMBER: ${{ github.event.pull_request.number }}
+              run: dev/sync-review-comments.sh '<!-- check-duplicates-finding:' "$RUNNER_TEMP/review.json"
diff --git a/AGENTS.md b/AGENTS.md
@@ -40,30 +40,48 @@
   Add product names and identifiers to `cspell-allow-list.txt`, in
   alphabetical order; the check reports out-of-order entries. CSpell is not a
   project dependency: `npx cspell@10 --no-progress <file>` to run it locally
-- **Example hostnames**: placeholder hostnames in docs are `*.example.com` 
-  (`sourcegraph.example.com` for the reader's instance, 
-  `github.example.com` for a code host, 
-  `https://sourcegraph.example.com` where a whole URL is meant); 
+- **Example hostnames**: placeholder hostnames in docs are `*.example.com`
+  (`sourcegraph.example.com` for the reader's instance,
+  `github.example.com` for a code host,
+  `https://sourcegraph.example.com` where a whole URL is meant);
   never `<URL>`, `[hostname]`, or a `$VARIABLE` the reader has to guess.
-  Example URLs use `https://`, except where needed, eg. loopback, 
-  in-cluster, proxy, and XML-namespace addresses. 
-  In a shell snippet a `$VARIABLE` is fine only when the same snippet 
-  exports it with an example value. 
+  Example URLs use `https://`, except where needed, eg. loopback,
+  in-cluster, proxy, and XML-namespace addresses.
+  In a shell snippet a `$VARIABLE` is fine only when the same snippet
+  exports it with an example value.
   `.github/workflows/check-hostnames.yml` runs `dev/check-hostnames.mjs`
   on the lines a PR adds and comments the findings with suggested changes
-  (advisory, never fails the PR). 
-  `dev/example-hostnames.json` maps each recommended hostname to the 
-  placeholders seen in its place, 
-  as either literal text,  a `*` glob, or a `/regex/`, 
-  matched case-insensitively with `-`, `_`, and `.` interchangeable; 
-  add to it when the check misses one, keeping keys and lists sorted. 
+  (advisory, never fails the PR).
+  `dev/example-hostnames.json` maps each recommended hostname to the
+  placeholders seen in its place,
+  as either literal text,  a `*` glob, or a `/regex/`,
+  matched case-insensitively with `-`, `_`, and `.` interchangeable;
+  add to it when the check misses one, keeping keys and lists sorted.
   `node dev/check-hostnames.mjs` checks all of `docs/`
   The `🤖 Sync generated docs` PRs overwrite the
   `SCHEMA_SYNC_START`…`SCHEMA_SYNC_END` blocks and whole pages
   (`self-hosted/observability/{alerts,dashboards}.mdx`, `cli/references/`,
   `ai/models.mdx`, `cody/capabilities/supported-models.mdx`,
   `admin/telemetry/`); fix those in sourcegraph/sourcegraph instead.
   `git log --author=sourcegraph-buildkite -- <file>` shows whether a page is one
+- **Duplicated content**: `.github/workflows/check-duplicates.yml` runs
+  `dev/check-duplicates.mjs` and comments the passages a PR adds that say the
+  same thing as a passage elsewhere under `docs/`, paraphrased or verbatim,
+  and the passages a PR edits that were already duplicated, so the author can
+  pick the home and replace the other copy with a link (advisory, never fails
+  the PR). Not part of `pnpm run check`: main has hundreds of pre-existing
+  findings, and CI only reports the ones a PR adds or edits.
+  `node dev/check-duplicates.mjs --diff <(git diff -U0 origin/main)` runs it
+  on your branch; without `--diff` it lists every duplicate in `docs/`
+
+### One home per fact
+
+- Each fact has one home. Link to it instead of copying it, so the copies
+  cannot drift apart.
+- Before writing a config snippet, `rg` the key under `docs/` and link to the
+  existing one.
+- The `SCHEMA_SYNC_START`…`SCHEMA_SYNC_END` blocks are the home for every
+  setting's default. Never restate a default elsewhere.
 
 ### Links
 
@@ -83,12 +101,13 @@ pnpm run check links --check-anchors --check-self-links \
 
 ### PR check comments
 
-The spelling, links, redirects, and example hostnames checks comment on the
-PR: a summary comment per check, plus an inline review comment with a
-`suggestion` block on each flagged line. After pushing, read them and follow
-the instructions they give (fix the spelling, the link, the redirect, or the
-hostname); do not work around a finding, and add a word to
-`cspell-allow-list.txt` only when it is correct.
+The spelling, links, redirects, example hostnames, and duplicated content
+checks comment on the PR: a summary comment per check, plus an inline review
+comment on each flagged line, with a `suggestion` block where the fix is
+mechanical. After pushing, read them and follow the instructions they give
+(fix the spelling, the link, the redirect, or the hostname; replace the
+duplicated passage with a link to its home); do not work around a finding,
+and add a word to `cspell-allow-list.txt` only when it is correct.
 
 ```sh
 gh pr checks <pr>

diff --git a/cspell-allow-list.txt b/cspell-allow-list.txt
@@ -274,6 +274,7 @@ istari
 itable
 iterm
 itoa
+Jaccard
 JCEF
 jiapantw
 jiti
-Original file line number
+Diff line change
@@ Expand Up / @@ -274,6 +274,7 @@ istari @@
     itable
     iterm
     itoa
+    Jaccard
     JCEF
     jiapantw
     jiti
@@ Expand Down @@