robobun · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026
diff --git a/docs/docs.json b/docs/docs.json
@@ -61,6 +61,7 @@
               "/quickstart",
               "/typescript",
               "/typescript-6",
+              "/upgrade-to-1.4",
               "/runtime/templating/init",
               "/runtime/templating/create"
             ]

diff --git a/docs/guides/util/upgrade.mdx b/docs/guides/util/upgrade.mdx
@@ -89,5 +89,6 @@ Use `scoop update bun` instead.
 
 ## See also
 
+- [Upgrading to Bun 1.4](/upgrade-to-1.4) — Behavior changes to check when moving from Bun 1.3
 - [Installation](/installation) — Install Bun for the first time
 - [Update packages](/pm/cli/update) — Update dependencies to latest versions
diff --git a/docs/pm/overrides.mdx b/docs/pm/overrides.mdx
@@ -150,4 +150,4 @@ Bun compares the selector with the range each dependent _declares_, not the reso
 
 - Bun supports only one parent level. It ignores `a>b>c`, `a/b/c`, and deeper object nesting with a warning.
 - Bun does not support pnpm's `"pkg@"` (empty selector) and `"-"` (remove dependency) forms, and skips them with a warning.
-- Bun writes a lockfile containing nested or version-scoped rules as `lockfileVersion` 3, which older versions of Bun cannot read.
+- Bun writes a lockfile containing nested or version-scoped rules as `lockfileVersion` 3, which Bun 1.3 and earlier cannot read. See [Upgrading to Bun 1.4](/upgrade-to-1.4) before adding such rules to a project that older Bun versions still install.