From 632fb34154b1e78dd5467c5ab0dcebef43513b84 Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Thu, 11 Jun 2026 09:24:54 +1000
Subject: [PATCH 01/23] docs: clarify versioned override parent behavior

---
 .../content/configuring-npm/package-json.md   | 23 +++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index 8bdf3c3e74f2a..0d50eab0f3d0b 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -965,6 +965,29 @@ To override `@npm/foo` to `1.0.0`, but only when it's a child of `@npm/bar@2.0.0
 }
 ```
 
+Versioned override keys do not just limit when nested overrides apply.
+They also replace the matched package with that version or range.
+In the example above, `@npm/bar@2.0.0` both matches `@npm/bar` at `2.0.0`
+and keeps `@npm/bar` on `2.0.0` while applying the nested `@npm/foo`
+override.
+
+If you want to keep the parent package on its existing spec while only
+overriding its children, set `"."` explicitly:
+
+```json
+{
+  "dependencies": {
+    "@npm/bar": "^2.0.0"
+  },
+  "overrides": {
+    "@npm/bar@2.0.0": {
+      ".": "$bar",
+      "@npm/foo": "1.0.0"
+    }
+  }
+}
+```
+
 You may not set an override for a package that you directly depend on unless both the dependency and the override itself share the exact same spec.
 To make this limitation easier to deal with, overrides may also be defined as a reference to a spec for a direct dependency by prefixing the name of the package you wish the version to match with a `$`.
 

From 324cf79c97f39bae430dae9a4d99839ab8028903 Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Fri, 12 Jun 2026 06:35:24 +1000
Subject: [PATCH 02/23] docs: fix scoped override spec references

---
 docs/lib/content/configuring-npm/package-json.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index 0d50eab0f3d0b..a4fc822bc0901 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -981,7 +981,7 @@ overriding its children, set `"."` explicitly:
   },
   "overrides": {
     "@npm/bar@2.0.0": {
-      ".": "$bar",
+      ".": "$@npm/bar",
       "@npm/foo": "1.0.0"
     }
   }
@@ -1002,9 +1002,9 @@ To make this limitation easier to deal with, overrides may also be defined as a
     // GOOD, specs match so override is allowed
     // "foo": "^1.0.0"
     // BEST, the override is defined as a reference to the dependency
-    "@npm/foo": "$foo",
+    "@npm/foo": "$@npm/foo",
     // the referenced package does not need to match the overridden one
-    "@npm/bar": "$foo"
+    "@npm/bar": "$@npm/foo"
   }
 }
 ```

From a2c003bb2d7c1fdb26e0309ceb04dcea7f92bc97 Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Wed, 17 Jun 2026 22:17:21 +1000
Subject: [PATCH 03/23] docs: clarify scoped override reference usage

---
 docs/lib/content/configuring-npm/package-json.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index a4fc822bc0901..9d84fc5177378 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -1002,6 +1002,7 @@ To make this limitation easier to deal with, overrides may also be defined as a
     // GOOD, specs match so override is allowed
     // "foo": "^1.0.0"
     // BEST, the override is defined as a reference to the dependency
+    // For scoped packages, use the full scoped name in the reference.
     "@npm/foo": "$@npm/foo",
     // the referenced package does not need to match the overridden one
     "@npm/bar": "$@npm/foo"

From 4dd7ef6b497e45d7935c49b7d476f9ed5a4a89f1 Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Thu, 18 Jun 2026 01:14:44 +1000
Subject: [PATCH 04/23] docs: clarify scoped override reference syntax

---
 docs/lib/content/configuring-npm/package-json.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index 9d84fc5177378..e94e5ca9b99b3 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -1003,6 +1003,7 @@ To make this limitation easier to deal with, overrides may also be defined as a
     // "foo": "^1.0.0"
     // BEST, the override is defined as a reference to the dependency
     // For scoped packages, use the full scoped name in the reference.
+    // Using "$bar" (without the scope) is not valid for scoped packages.
     "@npm/foo": "$@npm/foo",
     // the referenced package does not need to match the overridden one
     "@npm/bar": "$@npm/foo"

From 2f5de911cfb57d8ddd0924336936754b720ba7d7 Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Thu, 18 Jun 2026 09:05:21 +1000
Subject: [PATCH 05/23] docs: clarify scoped override reference forms

---
 docs/lib/content/configuring-npm/package-json.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index e94e5ca9b99b3..f8a53e44bdcf0 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -1003,7 +1003,7 @@ To make this limitation easier to deal with, overrides may also be defined as a
     // "foo": "^1.0.0"
     // BEST, the override is defined as a reference to the dependency
     // For scoped packages, use the full scoped name in the reference.
-    // Using "$bar" (without the scope) is not valid for scoped packages.
+    // Use "$@npm/foo" instead of "$foo", and use "$@npm/bar" instead of "$bar".
     "@npm/foo": "$@npm/foo",
     // the referenced package does not need to match the overridden one
     "@npm/bar": "$@npm/foo"

From 6088f2b38361fe24e38b59838f75eaefde25b674 Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Thu, 18 Jun 2026 10:03:59 +1000
Subject: [PATCH 06/23] docs: clarify scoped override reference examples

---
 docs/lib/content/configuring-npm/package-json.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index f8a53e44bdcf0..ffeb5277bcb20 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -1004,6 +1004,7 @@ To make this limitation easier to deal with, overrides may also be defined as a
     // BEST, the override is defined as a reference to the dependency
     // For scoped packages, use the full scoped name in the reference.
     // Use "$@npm/foo" instead of "$foo", and use "$@npm/bar" instead of "$bar".
+    // `$foo` and `$bar` are unscoped references and will not match scoped packages.
     "@npm/foo": "$@npm/foo",
     // the referenced package does not need to match the overridden one
     "@npm/bar": "$@npm/foo"

From d1146bde10f4e2565062b72efe70f93043757898 Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Thu, 18 Jun 2026 11:02:21 +1000
Subject: [PATCH 07/23] docs: clarify scoped override references

---
 docs/lib/content/configuring-npm/package-json.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index ffeb5277bcb20..2a978224c898e 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -1003,6 +1003,9 @@ To make this limitation easier to deal with, overrides may also be defined as a
     // "foo": "^1.0.0"
     // BEST, the override is defined as a reference to the dependency
     // For scoped packages, use the full scoped name in the reference.
+    // BAD, will not resolve scoped package references.
+    // "@npm/foo": "$foo",
+    // "@npm/bar": "$bar",
     // Use "$@npm/foo" instead of "$foo", and use "$@npm/bar" instead of "$bar".
     // `$foo` and `$bar` are unscoped references and will not match scoped packages.
     "@npm/foo": "$@npm/foo",

From 597aff547e9ca34f9f70d35fa5fb48da26fcfe76 Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Thu, 18 Jun 2026 22:50:18 +1000
Subject: [PATCH 08/23] docs: correct scoped override reference example

---
 docs/lib/content/configuring-npm/package-json.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index 2a978224c898e..2d18c53b1d803 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -1010,7 +1010,7 @@ To make this limitation easier to deal with, overrides may also be defined as a
     // `$foo` and `$bar` are unscoped references and will not match scoped packages.
     "@npm/foo": "$@npm/foo",
     // the referenced package does not need to match the overridden one
-    "@npm/bar": "$@npm/foo"
+    "@npm/bar": "$@npm/bar"
   }
 }
 ```

From 2416b83c1080692a7f5b595335d7b30b40c014fb Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Thu, 18 Jun 2026 23:51:35 +1000
Subject: [PATCH 09/23] docs: clarify scoped override reference comments

---
 docs/lib/content/configuring-npm/package-json.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index 2d18c53b1d803..15e4c0092f317 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -1004,10 +1004,11 @@ To make this limitation easier to deal with, overrides may also be defined as a
     // BEST, the override is defined as a reference to the dependency
     // For scoped packages, use the full scoped name in the reference.
     // BAD, will not resolve scoped package references.
+    // Do not use unscoped references for scoped dependencies.
+    // Use "$@npm/foo" instead of "$foo", and use "$@npm/bar" instead of "$bar".
+    // "$foo" and "$bar" are unscoped references and will not match scoped packages.
     // "@npm/foo": "$foo",
     // "@npm/bar": "$bar",
-    // Use "$@npm/foo" instead of "$foo", and use "$@npm/bar" instead of "$bar".
-    // `$foo` and `$bar` are unscoped references and will not match scoped packages.
     "@npm/foo": "$@npm/foo",
     // the referenced package does not need to match the overridden one
     "@npm/bar": "$@npm/bar"

From 4dfff94dbb1cdaaf6f8c382134a53ec9be59eb78 Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Fri, 19 Jun 2026 01:47:12 +1000
Subject: [PATCH 10/23] docs: clarify scoped override references

---
 docs/lib/content/configuring-npm/package-json.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index 15e4c0092f317..da0a061dc13d4 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -991,6 +991,9 @@ overriding its children, set `"."` explicitly:
 You may not set an override for a package that you directly depend on unless both the dependency and the override itself share the exact same spec.
 To make this limitation easier to deal with, overrides may also be defined as a reference to a spec for a direct dependency by prefixing the name of the package you wish the version to match with a `$`.
 
+For scoped dependencies, the `$` reference must be the full scoped package name.
+Using only the unscoped package name, like `$foo`, does not match `@scope/foo`.
+
 ```json
 {
   "dependencies": {
@@ -1004,9 +1007,8 @@ To make this limitation easier to deal with, overrides may also be defined as a
     // BEST, the override is defined as a reference to the dependency
     // For scoped packages, use the full scoped name in the reference.
     // BAD, will not resolve scoped package references.
-    // Do not use unscoped references for scoped dependencies.
-    // Use "$@npm/foo" instead of "$foo", and use "$@npm/bar" instead of "$bar".
-    // "$foo" and "$bar" are unscoped references and will not match scoped packages.
+    // Use "$@npm/foo" instead of "$foo".
+    // "$foo" is an unscoped reference and will not match @npm/foo.
     // "@npm/foo": "$foo",
     // "@npm/bar": "$bar",
     "@npm/foo": "$@npm/foo",

From b574dac884efa68b03f30705c9a993edd789ce52 Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Fri, 19 Jun 2026 03:48:33 +1000
Subject: [PATCH 11/23] docs: correct scoped override reference example

---
 docs/lib/content/configuring-npm/package-json.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index da0a061dc13d4..d56ca40336fa2 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -1013,7 +1013,7 @@ Using only the unscoped package name, like `$foo`, does not match `@scope/foo`.
     // "@npm/bar": "$bar",
     "@npm/foo": "$@npm/foo",
     // the referenced package does not need to match the overridden one
-    "@npm/bar": "$@npm/bar"
+    "@npm/bar": "$@npm/foo"
   }
 }
 ```

From 74c39e9fc271205c743432b51baf0badbd7c555d Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Fri, 19 Jun 2026 05:43:59 +1000
Subject: [PATCH 12/23] docs: trim scoped override examples

---
 docs/lib/content/configuring-npm/package-json.md | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index d56ca40336fa2..beb9b7152c3d5 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -1005,12 +1005,6 @@ Using only the unscoped package name, like `$foo`, does not match `@scope/foo`.
     // GOOD, specs match so override is allowed
     // "foo": "^1.0.0"
     // BEST, the override is defined as a reference to the dependency
-    // For scoped packages, use the full scoped name in the reference.
-    // BAD, will not resolve scoped package references.
-    // Use "$@npm/foo" instead of "$foo".
-    // "$foo" is an unscoped reference and will not match @npm/foo.
-    // "@npm/foo": "$foo",
-    // "@npm/bar": "$bar",
     "@npm/foo": "$@npm/foo",
     // the referenced package does not need to match the overridden one
     "@npm/bar": "$@npm/foo"

From 15f02a8aceb14692f40fef13c62606b1d498c8e5 Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Fri, 19 Jun 2026 10:39:29 +1000
Subject: [PATCH 13/23] docs: clarify scoped override reference example

---
 docs/lib/content/configuring-npm/package-json.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index beb9b7152c3d5..1deb8b78d6096 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -1006,7 +1006,7 @@ Using only the unscoped package name, like `$foo`, does not match `@scope/foo`.
     // "foo": "^1.0.0"
     // BEST, the override is defined as a reference to the dependency
     "@npm/foo": "$@npm/foo",
-    // the referenced package does not need to match the overridden one
+    // The referenced package can differ from the override target
     "@npm/bar": "$@npm/foo"
   }
 }

From 7fb88bc5f5b374fb0abf362f05625d28e147378f Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Fri, 19 Jun 2026 12:38:14 +1000
Subject: [PATCH 14/23] docs: trim override scope reference note

---
 docs/lib/content/configuring-npm/package-json.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index 1deb8b78d6096..c23f2d49ee13d 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -993,6 +993,7 @@ To make this limitation easier to deal with, overrides may also be defined as a
 
 For scoped dependencies, the `$` reference must be the full scoped package name.
 Using only the unscoped package name, like `$foo`, does not match `@scope/foo`.
+The referenced package can also differ from the override target.
 
 ```json
 {
@@ -1004,9 +1005,7 @@ Using only the unscoped package name, like `$foo`, does not match `@scope/foo`.
     // "foo": "^2.0.0"
     // GOOD, specs match so override is allowed
     // "foo": "^1.0.0"
-    // BEST, the override is defined as a reference to the dependency
     "@npm/foo": "$@npm/foo",
-    // The referenced package can differ from the override target
     "@npm/bar": "$@npm/foo"
   }
 }

From 43d08560a5ece2da13c357fbfa1cb8c3cdfa223a Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Fri, 19 Jun 2026 13:36:26 +1000
Subject: [PATCH 15/23] docs: clarify scoped override difference in example

---
 docs/lib/content/configuring-npm/package-json.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index c23f2d49ee13d..0a1549c112256 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -1005,6 +1005,7 @@ The referenced package can also differ from the override target.
     // "foo": "^2.0.0"
     // GOOD, specs match so override is allowed
     // "foo": "^1.0.0"
+    // You can still reference a different direct dependency for the override
     "@npm/foo": "$@npm/foo",
     "@npm/bar": "$@npm/foo"
   }

From ee9fd09bca7c14be0d93c114089d416479370f55 Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Fri, 19 Jun 2026 14:33:55 +1000
Subject: [PATCH 16/23] docs: trim scoped override example block

---
 docs/lib/content/configuring-npm/package-json.md | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index 0a1549c112256..eb63d2947faa0 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -1001,11 +1001,6 @@ The referenced package can also differ from the override target.
     "@npm/foo": "^1.0.0"
   },
   "overrides": {
-    // BAD, will throw an EOVERRIDE error
-    // "foo": "^2.0.0"
-    // GOOD, specs match so override is allowed
-    // "foo": "^1.0.0"
-    // You can still reference a different direct dependency for the override
     "@npm/foo": "$@npm/foo",
     "@npm/bar": "$@npm/foo"
   }

From afe09b52f57dc20c32ab483efb0a7f4d22e85dcf Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Fri, 19 Jun 2026 16:31:44 +1000
Subject: [PATCH 17/23] docs: tighten scoped override example wording

---
 docs/lib/content/configuring-npm/package-json.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index eb63d2947faa0..85dc71f18812b 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -967,9 +967,8 @@ To override `@npm/foo` to `1.0.0`, but only when it's a child of `@npm/bar@2.0.0
 
 Versioned override keys do not just limit when nested overrides apply.
 They also replace the matched package with that version or range.
-In the example above, `@npm/bar@2.0.0` both matches `@npm/bar` at `2.0.0`
-and keeps `@npm/bar` on `2.0.0` while applying the nested `@npm/foo`
-override.
+In this example, the parent key both matches and preserves `@npm/bar@2.0.0`
+while applying the nested `@npm/foo` override.
 
 If you want to keep the parent package on its existing spec while only
 overriding its children, set `"."` explicitly:

From 008a0a33bada738a9bd1ada207402f9957bae84e Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Fri, 19 Jun 2026 17:31:24 +1000
Subject: [PATCH 18/23] docs: tighten scoped override reference wording

---
 docs/lib/content/configuring-npm/package-json.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index 85dc71f18812b..c33eb642ffc24 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -991,8 +991,8 @@ You may not set an override for a package that you directly depend on unless bot
 To make this limitation easier to deal with, overrides may also be defined as a reference to a spec for a direct dependency by prefixing the name of the package you wish the version to match with a `$`.
 
 For scoped dependencies, the `$` reference must be the full scoped package name.
-Using only the unscoped package name, like `$foo`, does not match `@scope/foo`.
-The referenced package can also differ from the override target.
+Using only the unscoped package name, like `$foo`, does not match `@scope/foo`,
+and the referenced package can differ from the override target.
 
 ```json
 {

From d49e6879d7c7f954012c13f0a651c72b804d7b75 Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Fri, 19 Jun 2026 18:29:43 +1000
Subject: [PATCH 19/23] docs: clarify scoped  override contrast

---
 docs/lib/content/configuring-npm/package-json.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index c33eb642ffc24..392db8c872b28 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -992,7 +992,8 @@ To make this limitation easier to deal with, overrides may also be defined as a
 
 For scoped dependencies, the `$` reference must be the full scoped package name.
 Using only the unscoped package name, like `$foo`, does not match `@scope/foo`,
-and the referenced package can differ from the override target.
+and the referenced package can differ from the override target. This lets
+`@npm/bar` keep the spec from `@npm/foo`, which must be direct dependency.
 
 ```json
 {

From c5088fb5c464a4558507b2d859b7345a61d63e43 Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Fri, 19 Jun 2026 21:28:16 +1000
Subject: [PATCH 20/23] docs: trim scoped override wording

---
 docs/lib/content/configuring-npm/package-json.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index 392db8c872b28..c33eb642ffc24 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -992,8 +992,7 @@ To make this limitation easier to deal with, overrides may also be defined as a
 
 For scoped dependencies, the `$` reference must be the full scoped package name.
 Using only the unscoped package name, like `$foo`, does not match `@scope/foo`,
-and the referenced package can differ from the override target. This lets
-`@npm/bar` keep the spec from `@npm/foo`, which must be direct dependency.
+and the referenced package can differ from the override target.
 
 ```json
 {

From 65a5b62dd1c6063b102d2cadbc325b7d46a4050f Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Sat, 20 Jun 2026 00:24:39 +1000
Subject: [PATCH 21/23] docs: trim scoped override note wording

---
 docs/lib/content/configuring-npm/package-json.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index c33eb642ffc24..87c0f6fd5476d 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -991,8 +991,7 @@ You may not set an override for a package that you directly depend on unless bot
 To make this limitation easier to deal with, overrides may also be defined as a reference to a spec for a direct dependency by prefixing the name of the package you wish the version to match with a `$`.
 
 For scoped dependencies, the `$` reference must be the full scoped package name.
-Using only the unscoped package name, like `$foo`, does not match `@scope/foo`,
-and the referenced package can differ from the override target.
+Using only the unscoped package name, like `$foo`, does not match `@scope/foo`.
 
 ```json
 {

From c63c1f5c6a79eaddeb83df9626371e447390b1af Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Sat, 20 Jun 2026 08:15:49 +1000
Subject: [PATCH 22/23] docs: simplify scoped override note

---
 docs/lib/content/configuring-npm/package-json.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index 87c0f6fd5476d..c42b2d5954046 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -988,10 +988,8 @@ overriding its children, set `"."` explicitly:
 ```
 
 You may not set an override for a package that you directly depend on unless both the dependency and the override itself share the exact same spec.
-To make this limitation easier to deal with, overrides may also be defined as a reference to a spec for a direct dependency by prefixing the name of the package you wish the version to match with a `$`.
-
-For scoped dependencies, the `$` reference must be the full scoped package name.
-Using only the unscoped package name, like `$foo`, does not match `@scope/foo`.
+You can resolve a child override against a direct dependency by using a `$` prefix with the full package name.
+For scoped packages, keep the scope: use `$@scope/name`.
 
 ```json
 {

From a22e68c146e48044a51f53a4855882cc16a2180d Mon Sep 17 00:00:00 2001
From: ded-furby <190979964+ded-furby@users.noreply.github.com>
Date: Sat, 20 Jun 2026 12:12:57 +1000
Subject: [PATCH 23/23] docs: clarify scoped override example intent

---
 docs/lib/content/configuring-npm/package-json.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
index c42b2d5954046..db2e16c4bd6c7 100644
--- a/docs/lib/content/configuring-npm/package-json.md
+++ b/docs/lib/content/configuring-npm/package-json.md
@@ -990,6 +990,7 @@ overriding its children, set `"."` explicitly:
 You may not set an override for a package that you directly depend on unless both the dependency and the override itself share the exact same spec.
 You can resolve a child override against a direct dependency by using a `$` prefix with the full package name.
 For scoped packages, keep the scope: use `$@scope/name`.
+That allows, for example, `@npm/bar` to inherit the direct dependency spec from `@npm/foo` while still overriding `@npm/bar` at the same time:
 
 ```json
 {