docs: clarify versioned override parent behavior

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": {
+      ".": "$@npm/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 `$`.
 
@@ -979,9 +1002,11 @@ 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",
+    // 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": "$foo"
+    "@npm/bar": "$@npm/foo"
   }
 }
 ```