Docs tweaks (#2160)

* Tweaks

* Add ecosystem. Add bunx. Flesh out install.

* Tweaks

* Add TS to installation

* Tweaks

* New readme

* Write new readme

* Tweak

* Center header

* Bun

* tweaks

* No dollar sign

* Fix links

* Update

* Tweak

5 files changed, 202 insertions, 90 deletions

diff --git a/docs/cli/bunx.md b/docs/cli/bunx.md
new file mode 100644
index 000000000..e8374cab1
--- /dev/null
+++ b/docs/cli/bunx.md
@@ -0,0 +1,73 @@
+Use `bunx` to auto-install and run packages from `npm`. The `bunx` CLI will be auto-installed when you install `bun`.
+
+```bash
+$ bunx cowsay "Hello world!"
+```
+
+{% callout %}
+⚡️ **Speed** — With Bun's fast startup times, `bunx` is [roughly 100x faster](https://twitter.com/jarredsumner/status/1606163655527059458) than `npx` for locally installed packages.
+{% /callout %}
+
+Packages can declare executables in the `"bin"` field of their `package.json`. These are known as _package executables_ or _package binaries_.
+
+```jsonc#package.json
+{
+  // ... other fields
+  "name": "my-cli",
+  "bin": {
+    "my-cli": "dist/index.js"
+  }
+}
+```
+
+These executables are commonly plain JavaScript files marked with a [shebang line](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) to indicate which program should be used to execute them. The following file indicates that it should be executed with `node`.
+
+```js#dist/index.js
+#!/usr/bin/env node
+
+console.log("Hello world!");
+```
+
+These executables can be run with `bunx`,
+
+```bash
+$ bunx my-cli
+```
+
+As with `npx`, `bunx` will check for a locally installed package first, then fall back to auto-installing the package from `npm`. Installed packages will be stored in Bun's global cache for future use.
+
+### Arguments and flags
+
+To pass additional command-line flags and arguments through to the executable, place them after the executable name.
+
+```bash
+$ bunx my-cli --foo bar
+```
+
+### Shebangs
+
+By default, Bun respects shebangs. If an executable is marked with `#!/usr/bin/env node`, Bun will spin up a `node` process to execute the file. However, in some cases it may be desirable to run executables using [Bun's runtime](/docs/runtime), even if the executable indicates otherwise. To do so, include the `--bun` flag.
+
+```bash
+$ bunx --bun my-cli
+```
+
+{% callout %}
+**Note** — The `--bun` flag must occur _before_ the executable name. Flags that appear _after_ the name are passed through to the executable.
+
+```bash
+$ bunx --bun my-cli # good
+$ bunx my-cli --bun # bad
+```
+
+{% /callout %}
+
+## Environment variables
+
+Bun automatically loads environment variables from `.env` files before running a file, script, or executable. The following files are checked, in order:
+
+1. `.env.local` (first)
+2. `NODE_ENV` === `"production"` ? `.env.production` : `.env.development`
+3. `.env`
+
+To debug environment variables, run `bun run env` to view a list of resolved environment variables.
diff --git a/docs/cli/create.md b/docs/cli/create.md
index 8542db68b..54595a6fe 100644
--- a/docs/cli/create.md
+++ b/docs/cli/create.md
@@ -188,9 +188,7 @@ When cloning a template, `bun create` will automatically remove the `"bun-create
 
 {% /table %}
 
-### How `bun create` works
-
-{% details summary="View details" %}
+{% details summary="How `bun create` works" %}
 
 When you run `bun create ${template} ${destination}`, here’s what happens:
 
diff --git a/docs/cli/install.md b/docs/cli/install.md
index 777ed2da1..09edc59ec 100644
--- a/docs/cli/install.md
+++ b/docs/cli/install.md
@@ -1,6 +1,4 @@
-The `bun` CLI contains an `npm`-compatible package manager designed to be a faster replacement for existing package management tools like `npm`, `yarn`, and `pnpm`.
-
-It can be be used as a drop-in replacement for these tools, _regardless of whether you're using Bun's runtime_.
+The `bun` CLI contains an `npm`-compatible package manager designed to be a faster replacement for existing package management tools like `npm`, `yarn`, and `pnpm`. It's designed for Node.js compatibility; use it in any Bun or Node.js project.
 
 {% callout %}
 
@@ -86,7 +84,7 @@ dryRun = false
 
 {% /details %}
 
-## Adding packages
+## Add and remove packages
 
 To add or remove a particular package:
 
@@ -149,6 +147,27 @@ To view a complete list of options for a given command:
 $ bun add --help
 ```
 
+## Git dependencies
+
+To add a dependency from a git repository:
+
+```bash
+$ bun install git@github.com:moment/moment.git
+```
+
+Bun supports a variety of protocols, including [`github`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#github-urls), [`git`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#git-urls-as-dependencies), `git+ssh`, `git+https`, and many more.
+
+```json
+{
+  "dependencies": {
+    "dayjs": "git+https://github.com/iamkun/dayjs.git",
+    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
+    "moment": "git@github.com:moment/moment.git",
+    "zod": "github:colinhacks/zod"
+  }
+}
+```
+
 ## Global cache
 
 All packages downloaded from the registry are stored in a global cache at `~/.bun/install/cache`. They are stored in subdirectories named like `${name}@${version}`, so multiple versions of a package can be cached.
@@ -328,7 +347,7 @@ registry = { url = "https://registry.npmjs.org", token = "123456" }
 registry = "https://username:password@registry.npmjs.org"
 ```
 
-To configure organization-scoped registries:
+To configure a private registry scoped to a particular organization:
 
 ```toml
 [install.scopes]
@@ -342,3 +361,85 @@ To configure organization-scoped registries:
 # registry with token
 "@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" }
 ```
+
+## Linking and unlinking
+
+Use `bun link` in a local directory to register the current package as a "linkable" package.
+
+```bash
+$ cd /path/to/cool-pkg
+$ cat package.json
+{
+  "name": "cool-pkg",
+  "version": "1.0.0"
+}
+$ bun link
+bun link v0.5.7 (7416672e)
+Success! Registered "cool-pkg"
+
+To use cool-pkg in a project, run:
+  bun link cool-pkg
+
+Or add it in dependencies in your package.json file:
+  "cool-pkg": "link:cool-pkg"
+```
+
+This package can now be "linked" into other projects using `bun link cool-pkg`. This will create a symlink in the `node_modules` directory of the target project, pointing to the local directory.
+
+```bash
+$ cd /path/to/my-app
+$ bun link cool-pkg
+```
+
+This will add `cool-pkg` to the `dependencies` field of your app's package.json with a special version specifier that tells Bun to load from the registered local directory instead of installing from `npm`.
+
+```json-diff
+  {
+    "name": "my-app",
+    "version": "1.0.0",
+    "dependencies": {
++     "cool-pkg": "link:cool-pkg"
+    }
+  }
+```
+
+## Utilities
+
+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 get the path to the global `bin` directory:
+
+```bash
+$ bun pm bin
+<$HOME>/.bun/bin
+```
+
+To print a list of packages installed in the current project and their resolved versions, excluding their dependencies. Use the `--all` flag to print the entire tree, including all nth-order dependencies.
+
+```bash
+/path/to/project node_modules (5)
+├── eslint@8.33.0
+├── react@18.2.0
+├── react-dom@18.2.0
+├── typescript@4.8.4
+└── zod@3.20.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
+```
diff --git a/docs/cli/run.md b/docs/cli/run.md
index f180868d2..133f3e1ec 100644
--- a/docs/cli/run.md
+++ b/docs/cli/run.md
@@ -1,6 +1,6 @@
 The `bun` CLI can be used to execute JavaScript/TypeScript files, `package.json` scripts, and [executable packages](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#bin).
 
-## Run a file
+## Running a file
 
 {% callout %}
 Compare to `node <file>`
@@ -25,7 +25,7 @@ Billie Eilish
 
 If no `node_modules` directory is found in the working directory or above, Bun will abandon Node.js-style module resolution in favor of the `Bun module resolution algorithm`. Under Bun-style module resolution, all packages are _auto-installed_ on the fly into a [global module cache](/docs/cli/install#global-cache). For full details on this algorithm, refer to [Runtime > Modules](/docs/runtime/modules).
 
-## Run a package script
+## Running a package script
 
 {% note %}
 Compare to `npm run <script>` or `yarn <script>`
@@ -80,77 +80,3 @@ quickstart scripts:
 ```
 
 Bun respects lifecycle hooks. For instance, `bun run clean` will execute `preclean` and `postclean`, if defined. If the `pre<script>` fails, Bun will not execute the script itself.
-
-## Run an executable
-
-{% callout %}
-Compare to `npx <command>`
-{% /callout %}
-
-Packages can declare executables in the `"bin"` field of their `package.json`. These are known as _package executables_ or _package binaries_.
-
-```jsonc#package.json
-{
-  // ... other fields
-  "name": "my-cli",
-  "bin": {
-    "my-cli": "dist/index.js"
-  }
-}
-```
-
-These executables are commonly plain JavaScript files marked with a [shebang line](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) to indicate which program should be used to execute them. The following file indicates that it should be executed with `node`.
-
-```js#dist/index.js
-#!/usr/bin/env node
-
-console.log("Hello world!");
-```
-
-These executables can be run with `bunx`, Bun's equivalent of `npx`.
-
-{% callout %}
-⚡️ **Speed** — With Bun's fast startup times, `bunx` is [roughly 100x faster](https://twitter.com/jarredsumner/status/1606163655527059458) than `npx` for locally installed packages.
-{% /callout %}
-
-```bash
-$ bunx my-cli
-```
-
-As with `npx`, `bunx` will check for a locally installed package first, then fall back to auto-installing the package from `npm`. Installed packages will be stored in Bun's global cache for future use.
-
-### Arguments and flags
-
-To pass additional command-line flags and arguments through to the executable:
-
-```bash
-$ bunx my-cli --foo bar
-```
-
-### Shebangs
-
-By default, Bun respects shebangs. If an executable is marked with `#!/usr/bin/env node`, Bun will spin up a `node` process to execute the file. However, in some cases it may be desirable to run executables using [Bun's runtime](/docs/runtime), even if the executable indicates otherwise. To do so, include the `--bun` flag.
-
-```bash
-$ bunx --bun my-cli
-```
-
-{% callout %}
-**Note** — The `--bun` flag must occur _before_ the executable name. Flags that appear _after_ the name are passed through to the executable.
-
-```bash
-$ bunx --bun my-cli # good
-$ bunx my-cli --bun # bad
-```
-
-{% /callout %}
-
-## Environment variables
-
-Bun automatically loads environment variables from `.env` files before running a file, script, or executable. The following files are checked, in order:
-
-1. `.env.local` (first)
-2. `NODE_ENV` === `"production"` ? `.env.production` : `.env.development`
-3. `.env`
-
-To debug environment variables, run `bun run env` to view a list of resolved environment variables.
diff --git a/docs/cli/test.md b/docs/cli/test.md
index 5513285f9..a3663f4d5 100644
--- a/docs/cli/test.md
+++ b/docs/cli/test.md
@@ -1,9 +1,23 @@
 Bun ships with a built-in test runner.
 
 ```bash
-$ bun wiptest
+$ bun test
 ```
 
+Tests are written in JavaScript or TypeScript with a Jest-like API.
+
+```ts#math.test.ts
+import { expect, test } from "bun:test";
+
+test("2 + 2", () => {
+  expect(2 + 2).toBe(4);
+});
+```
+
+It's fast.
+
+{% image src="/images/buntest.jpeg" caption="Bun runs 266 React SSR tests faster than Jest can print its version number." /%}
+
 The runner recursively searches the working directory for files that match the following patterns:
 
 - `*.test.{js|jsx|ts|tsx}`
@@ -11,10 +25,10 @@ The runner recursively searches the working directory for files that match the f
 - `*.spec.{js|jsx|ts|tsx}`
 - `*_spec.{js|jsx|ts|tsx}`
 
-You can filter the set of tests to run by passing additional positional arguments to `wiptest`. Any file in the directory with an _absolute path_ that contains one of the filters will run. Commonly, these filters will be file or directory names; glob patterns are not yet supported.
+You can filter the set of tests to run by passing additional positional arguments to `bun test`. Any file in the directory with an _absolute path_ that contains one of the filters will run. Commonly, these filters will be file or directory names; glob patterns are not yet supported.
 
 ```bash
-$ bun wiptest <filter> <filter> ...
+$ bun test <filter> <filter> ...
 ```
 
 <!--
@@ -33,13 +47,13 @@ Consider the following directory structure:
 To run both `a.test.ts` files:
 
 ```
-$ bun wiptest a
+$ bun test a
 ```
 
 To run all tests in the `foo` directory:
 
 ```
-$ bun wiptest foo
+$ bun test foo
 ```
 
 Any test file in the directory with an _absolute path_ that contains one of the targets will run. Glob patterns are not yet supported. -->
@@ -112,7 +126,7 @@ afterEach(() => {
 // tests...
 ```
 
-Perform per-scope setup and teardown logic with `beforeAll` and `afterAll`. At the top-level, the *scope* is the current file; in a `describe` block, the scope is the block itself.
+Perform per-scope setup and teardown logic with `beforeAll` and `afterAll`. At the top-level, the _scope_ is the current file; in a `describe` block, the scope is the block itself.
 
 ```ts
 import { expect, test, beforeAll, afterAll } from "bun:test";