3 files changed, 117 insertions, 58 deletions
diff --git a/docs/install/lifecycle.md b/docs/install/lifecycle.md
new file mode 100644
index 000000000..035ead24d
--- /dev/null
+++ b/docs/install/lifecycle.md
@@ -0,0 +1,44 @@
+Packages on `npm` can define _lifecycle scripts_ in their `package.json`. Some of the most common are below, but there are [many others](https://docs.npmjs.com/cli/v10/using-npm/scripts).
+
+- `preinstall`: Runs before the package is installed
+- `postinstall`: Runs after the package is installed
+- `preuninstall`: Runs before the package is uninstalled
+- `prepublishOnly`: Runs before the package is published
+
+These scripts are arbitrary shell commands that the package manager is expected to read and execute at the appropriate time. But executing arbitrary scripts represents a potential security risk, so—unlike other `npm` clients—Bun does not execute arbitrary lifecycle scripts by default.
+
+## `postinstall`
+
+The `postinstall` script is particularly important. It's widely used to build or install platform-specific binaries for packages that are implemented as [native Node.js add-ons](https://nodejs.org/api/addons.html). For example, `node-sass` is a popular package that uses `postinstall` to build a native binary for Sass.
+
+```json
+{
+  "name": "my-app",
+  "version": "1.0.0",
+  "dependencies": {
+    "node-sass": "^6.0.1"
+  }
+}
+```
+
+## `trustedDependencies`
+
+Instead of executing arbitrary scripts, Bun uses a "default-secure" approach. You can add certain packages to an allow list, and Bun will execute lifecycle scripts for those packages. To tell Bun to allow lifecycle scripts for a particular package, add the package name to `trustedDependencies` array in your `package.json`.
+
+```json-diff
+  {
+    "name": "my-app",
+    "version": "1.0.0",
++   "trustedDependencies": ["node-sass"]
+  }
+```
+
+Once added to `trustedDependencies`, install/re-install the package. Bun will read this field and run lifecycle scripts for `my-trusted-package`.
+
+## `--ignore-scripts`
+
+To disable lifecycle scripts for all packages, use the `--no-scripts` flag.
+
+```bash
+$ bun install --no-scripts
+```
diff --git a/docs/install/overrides.md b/docs/install/overrides.md
new file mode 100644
index 000000000..f226c35bd
--- /dev/null
+++ b/docs/install/overrides.md
@@ -0,0 +1,73 @@
+Bun supports npm's `"overrides"` and Yarn's `"resolutions"` in `package.json`. These are mechanisms for specifying a version range for _metadependencies_—the dependencies of your dependencies. Refer to [Package manager > Overrides and resolutions](/docs/install/overrides) for complete documentation.
+
+```json-diff#package.json
+  {
+    "name": "my-app",
+    "dependencies": {
+      "foo": "^2.0.0"
+    },
++   "overrides": {
++     "bar": "~4.4.0"
++   }
+  }
+```
+
+By default, Bun will install the latest version of all dependencies and metadependencies, according to the ranges specified in each package's `package.json`. Let's say you have a project with one dependency, `foo`, which in turn has a dependency on `bar`. This means `bar` is a _metadependency_ of our project.
+
+```json#package.json
+{
+  "name": "my-app",
+  "dependencies": {
+    "foo": "^2.0.0"
+  }
+}
+```
+
+When you run `bun install`, Bun will install the latest versions of each package.
+
+```
+# tree layout of node_modules
+node_modules
+├── foo@1.2.3
+└── bar@4.5.6
+```
+
+But what if a security vulnerability was introduced in `bar@4.5.6`? We may want a way to pin `bar` to an older version that doesn't have the vulerability. This is where `"overrides"`/`"resolutions"` come in.
+
+## `"overrides"`
+
+Add `bar` to the `"overrides"` field in `package.json`. Bun will defer to the specified version range when determining which version of `bar` to install, whether it's a dependency or a metadependency.
+
+{% callout %}
+**Note** — Bun currently only supports top-level `"overrides"`. [Nested overrides](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#overrides) are not supported.
+{% /callout %}
+
+```json-diff#package.json
+  {
+    "name": "my-app",
+    "dependencies": {
+      "foo": "^2.0.0"
+    },
++   "overrides": {
++     "bar": "~4.4.0"
++   }
+  }
+```
+
+## `"resolutions"`
+
+The syntax is similar for `"resolutions"`, which is Yarn's alternative to `"overrides"`. Bun supports this feature to make migration from Yarn easier.
+
+As with `"overrides"`, _nested resolutions_ are not currently supported.
+
+```json-diff#package.json
+  {
+    "name": "my-app",
+    "dependencies": {
+      "foo": "^2.0.0"
+    },
++   "resolutions": {
++     "bar": "~4.4.0"
++   }
+  }
+```
diff --git a/docs/install/utilities.md b/docs/install/utilities.md
deleted file mode 100644
index 689f177d8..000000000
--- a/docs/install/utilities.md
+++ /dev/null
@@ -1,58 +0,0 @@
-The `bun pm` command group provides a set of utilities for working with Bun's package manager.
-
-To print the path to the `bin` directory for the local project:
-
-```bash
-$ bun pm bin
-/path/to/current/project/node_modules/.bin
-```
-
-To print the path to the global `bin` directory:
-
-```bash
-$ bun pm bin -g
-<$HOME>/.bun/bin
-```
-
-To print a list of installed dependencies in the current project and their resolved versions, excluding their dependencies.
-
-```bash
-$ bun pm ls
-/path/to/project node_modules (135)
-├── eslint@8.38.0
-├── react@18.2.0
-├── react-dom@18.2.0
-├── typescript@5.0.4
-└── zod@3.21.4
-```
-
-To print all installed dependencies, including nth-order dependencies.
-
-```bash
-$ bun pm ls --all
-/path/to/project node_modules (135)
-├── @eslint-community/eslint-utils@4.4.0
-├── @eslint-community/regexpp@4.5.0
-├── @eslint/eslintrc@2.0.2
-├── @eslint/js@8.38.0
-├── @nodelib/fs.scandir@2.1.5
-├── @nodelib/fs.stat@2.0.5
-├── @nodelib/fs.walk@1.2.8
-├── acorn@8.8.2
-├── acorn-jsx@5.3.2
-├── ajv@6.12.6
-├── ansi-regex@5.0.1
-├── ...
-```
-
-To print the path to Bun's global module cache:
-
-```bash
-$ bun pm cache
-```
-
-To clear Bun's global module cache:
-
-```bash
-$ bun pm cache rm
-```