diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 50e243a..258e83b 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -46,6 +46,24 @@ updates:
         update-types:
           - minor
           - patch
+    ignore:
+      # Two TypeScripts live here and they are not free to move together. The build
+      # runs 7; `tools/docs` pins 6.0.3 because typedoc's peer range stops at 6.0.x,
+      # and 6.0.3 is the newest version that range allows. Dependabot matches by
+      # dependency name and cannot tell the two apart, so it proposed 6.0.3 → 7.0.2
+      # for the docs package the day this repository went public — an upgrade that
+      # would leave typedoc unable to load.
+      #
+      # Majors are blocked here as a result, which also means the build's own
+      # TypeScript major is a deliberate, manual bump. The question to answer first
+      # is always the same: has typedoc's peer range moved?
+      #
+      #   npm view typedoc version peerDependencies
+      #
+      # If it accepts the new major, raise both together. If it does not, the pin
+      # stays and this rule is why. Minors and patches are unaffected.
+      - dependency-name: typescript
+        update-types: ["version-update:semver-major"]
 
   # One PR for all action bumps — they are independent of each other and of the npm
   # tree. Pinned at the current majors here, so the first weekly run should be quiet.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d09bfc6..86d260a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -54,6 +54,21 @@ Node 22 and pnpm 11 (`corepack enable` picks up the pinned version).
 | `config/` | Shared tool configuration; `api-extractor-base.json` is the API gate's |
 | `tools/docs` | TypeDoc, in a package of its own because it needs a TypeScript the build does not use |
 
+**Two TypeScripts, and they do not move together.** The build runs 7; `tools/docs` pins
+6.0.3, because typedoc's peer range stops at `6.0.x` and 6.0.3 is the newest version it
+accepts. Dependabot matches by name and cannot tell the two apart, so majors are ignored
+for `typescript` — which makes the build's own major a manual decision.
+
+Before touching either pin, ask what decides it:
+
+```sh
+npm view typedoc version peerDependencies   # has the range moved?
+```
+
+If typedoc accepts the newer major, raise both and drop the ignore. If it has not, the
+pin stays — and a "typescript is out of date" report is answered by that command rather
+than by bumping.
+
 Where a test goes follows from what it can see. Logic that can be checked without a
 canvas belongs in a package's own suite, because it runs in a second. Anything about what
 is *painted* — geometry, continuity, whether a click lands on the byte that was drawn —