6 files changed, 163 insertions, 6 deletions
diff --git a/docs/guides/install/azure-artifacts.md b/docs/guides/install/azure-artifacts.md
new file mode 100644
index 000000000..659e75fd6
--- /dev/null
+++ b/docs/guides/install/azure-artifacts.md
@@ -0,0 +1,73 @@
+---
+name: Using bun install with an Azure Artifacts npm registry
+---
+
+{% callout %}
+In [Azure Artifact's](https://learn.microsoft.com/en-us/azure/devops/artifacts/npm/npmrc?view=azure-devops&tabs=windows%2Cclassic) instructions for `.npmrc`, they say to base64 encode the password. Do not do this for `bun install`. Bun will automatically base64 encode the password for you if needed.
+{% /callout %}
+
+[Azure Artifacts](https://azure.microsoft.com/en-us/products/devops/artifacts) is a package management system for Azure DevOps. It allows you to host your own private npm registry, npm packages, and other types of packages as well.
+
+---
+
+### Configure with bunfig.toml
+
+---
+
+To use it with `bun install`, add a `bunfig.toml` file to your project with the following contents. Make sure to replace `my-azure-artifacts-user` with your Azure Artifacts username, such as `jarred1234`.
+
+```toml#bunfig.toml
+[install.registry]
+url = "https://pkgs.dev.azure.com/my-azure-artifacts-user/_packaging/my-azure-artifacts-user/npm/registry"
+username = "my-azure-artifacts-user"
+# Bun v1.0.3+ supports using an environment variable here
+password = "$NPM_PASSWORD"
+```
+
+---
+
+Then assign your Azure Personal Access Token to the the `NPM_PASSWORD` environment variable. Bun [automatically reads](/docs/runtime/env) `.env` files, so create a file called `.env` in your project root. There is no need to base-64 encode this token! Bun will do this for you.
+
+```txt#.env
+NPM_PASSWORD=<paste token here>
+```
+
+---
+
+### Configure with environment variables
+
+---
+
+To configure Azure Artifacts without `bunfig.toml`, you can set the `NPM_CONFIG_REGISTRY` environment variable. The URL should include `:username` and `:_password` as query parameters. Replace `<USERNAME>` and `<PASSWORD>` with the apprropriate values.
+
+```bash#shell
+NPM_CONFIG_REGISTRY=https://pkgs.dev.azure.com/my-azure-artifacts-user/_packaging/my-azure-artifacts-user/npm/registry/:username=<USERNAME>:_password=<PASSWORD>
+```
+
+---
+
+### Don't base64 encode the password
+
+---
+
+In [Azure Artifact's](https://learn.microsoft.com/en-us/azure/devops/artifacts/npm/npmrc?view=azure-devops&tabs=windows%2Cclassic) instructions for `.npmrc`, they say to base64 encode the password. Do not do this for `bun install`. Bun will automatically base64 encode the password for you if needed.
+
+{% callout %}
+**Tip** — If it ends with `==`, it probably is base64 encoded.
+{% /callout %}
+
+---
+
+To decode a base64-encoded password, open your browser console and run:
+
+```js
+atob("<base64-encoded password>");
+```
+
+---
+
+Alternatively, use the `base64` command line tool, but doing so means it may be saved in your terminal history which is not recommended:
+
+```bash
+echo "base64-encoded-password" | base64 --decode
+```
diff --git a/docs/guides/install/custom-registry.md b/docs/guides/install/custom-registry.md
index 64b3cf76b..12bb3b77f 100644
--- a/docs/guides/install/custom-registry.md
+++ b/docs/guides/install/custom-registry.md
@@ -18,7 +18,7 @@ registry = "https://username:password@registry.npmjs.org"
 
 ---
 
-Your `bunfig.toml` can reference environment variables. Bun automatically loads environment variables from `.env.local`, `.env.[NODE_ENV]`, and `.env`. See [Docs > Environment variables](/docs/cli/run#environment-variables) for more information.
+Your `bunfig.toml` can reference environment variables. Bun automatically loads environment variables from `.env.local`, `.env.[NODE_ENV]`, and `.env`. See [Docs > Environment variables](/docs/runtime/env) for more information.
 
 ```toml#bunfig.toml
 [install]
diff --git a/docs/guides/install/jfrog-artifactory.md b/docs/guides/install/jfrog-artifactory.md
new file mode 100644
index 000000000..e4872982b
--- /dev/null
+++ b/docs/guides/install/jfrog-artifactory.md
@@ -0,0 +1,28 @@
+---
+name: Using bun install with Artifactory
+---
+
+[JFrog Artifactory](https://jfrog.com/artifactory/) is a package management system for npm, Docker, Maven, NuGet, Ruby, Helm, and more. It allows you to host your own private npm registry, npm packages, and other types of packages as well.
+
+To use it with `bun install`, add a `bunfig.toml` file to your project with the following contents:
+
+---
+
+### Configure with bunfig.toml
+
+Make sure to replace `MY_SUBDOMAIN` with your JFrog Artifactory subdomain, such as `jarred1234` and MY_TOKEN with your JFrog Artifactory token.
+
+```toml#bunfig.toml
+[install.registry]
+url = "https://MY_SUBDOMAIN.jfrog.io/artifactory/api/npm/npm/_auth=MY_TOKEN"
+# Bun v1.0.3+ supports using an environment variable here
+# url = "$NPM_CONFIG_REGISTRY"
+```
+
+---
+
+### Configure with `$NPM_CONFIG_REGISTRY`
+
+Like with npm, you can use the `NPM_CONFIG_REGISTRY` environment variable to configure JFrog Artifactory with bun install.
+
+---
diff --git a/docs/guides/install/registry-scope.md b/docs/guides/install/registry-scope.md
index 48f7dee79..aade23116 100644
--- a/docs/guides/install/registry-scope.md
+++ b/docs/guides/install/registry-scope.md
@@ -11,7 +11,11 @@ Bun does not read `.npmrc` files; instead private registries are configured via
 
 # as an object with username/password
 # you can reference environment variables
-"@myorg2" = { username = "myusername", password = "$npm_pass", url = "https://registry.myorg.com/" }
+"@myorg2" = {
+  username = "myusername",
+  password = "$npm_pass",
+  url = "https://registry.myorg.com/"
+}
 
 # as an object with token
 "@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" }
@@ -20,7 +24,7 @@ Bun does not read `.npmrc` files; instead private registries are configured via
 
 ---
 
-Your `bunfig.toml` can reference environment variables. Bun automatically loads environment variables from `.env.local`, `.env.[NODE_ENV]`, and `.env`. See [Docs > Environment variables](/docs/cli/run#environment-variables) for more information.
+Your `bunfig.toml` can reference environment variables. Bun automatically loads environment variables from `.env.local`, `.env.[NODE_ENV]`, and `.env`. See [Docs > Environment variables](/docs/runtime/env) for more information.
 
 ```toml#bunfig.toml
 [install.scopes]
diff --git a/docs/guides/install/trusted.md b/docs/guides/install/trusted.md
new file mode 100644
index 000000000..0c1ac6362
--- /dev/null
+++ b/docs/guides/install/trusted.md
@@ -0,0 +1,50 @@
+---
+name: Add a trusted dependency
+---
+
+Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts for installed dependencies, such as `postinstall` and `node-gyp` builds. These scripts represent a potential security risk, as they can execute arbitrary code on your machine.
+
+{% callout %}
+Soon, Bun will include a built-in allow-list that automatically allows lifecycle scripts to be run by popular packages that are known to be safe. This is still under development.
+{% /callout %}
+
+---
+
+If you are seeing one of the following errors, you are probably trying to use a package that uses `postinstall` to work properly:
+
+- `error: could not determine executable to run for package`
+- `InvalidExe`
+
+---
+
+To tell Bun to allow lifecycle scripts for a particular package, add the package to `trustedDependencies` in your package.json.
+
+Note that this only allows lifecycle scripts for the specific package listed in `trustedDependencies`, _not_ the dependencies of that dependency!
+
+<!-- Bun maintains an allow-list of popular packages containing `postinstall` scripts that are known to be safe. To run lifecycle scripts for packages that aren't on this list, add the package to `trustedDependencies` in your package.json. -->
+
+```json-diff
+  {
+    "name": "my-app",
+    "version": "1.0.0",
++   "trustedDependencies": ["my-trusted-package"]
+  }
+```
+
+---
+
+Once this is added, run a fresh install. Bun will re-install your dependencies and properly install
+
+```sh
+$ rm -rf node_modules
+$ rm bun.lockb
+$ bun install
+```
+
+---
+
+Note that this only allows lifecycle scripts for the specific package listed in `trustedDependencies`, _not_ the dependencies of that dependency!
+
+---
+
+See [Docs > Package manager > Trusted dependencies](/docs/install/lifecycle) for complete documentation of trusted dependencies.
diff --git a/docs/guides/install/workspaces.md b/docs/guides/install/workspaces.md
index f87c1e337..b271a33b0 100644
--- a/docs/guides/install/workspaces.md
+++ b/docs/guides/install/workspaces.md
@@ -4,6 +4,8 @@ name: Configuring a monorepo using workspaces
 
 Bun's package manager supports npm `"workspaces"`. This allows you to split a codebase into multiple distinct "packages" that live in the same repository, can depend on each other, and (when possible) share a `node_modules` directory.
 
+Clone [this sample project](https://github.com/colinhacks/bun-workspaces) to experiment with workspaces.
+
 ---
 
 The root `package.json` should not contain any `"dependencies"`, `"devDependencies"`, etc. Each individual package should be self-contained and declare its own dependencies. Similarly, it's conventional to declare `"private": true` to avoid accidentally publishing the root package to `npm`.
@@ -35,13 +37,13 @@ It's common to place all packages in a `packages` directory. The `"workspaces"`
 
 ---
 
-To add one workspace as a dependency of another, modify its `package.json`. Here we're adding `stuff-a` as a dependency of `stuff-b`.
+To add dependencies between workspaces, use the `"workspace:*"` syntax. Here we're adding `stuff-a` as a dependency of `stuff-b`.
 
-```json#packages/stuff-b/package.json
+```json-diff#packages/stuff-b/package.json
 {
   "name": "stuff-b",
   "dependencies": {
-+   "stuff-a": "*"
++   "stuff-a": "workspace:*"
   }
 }
 ```