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

1 files changed, 106 insertions, 5 deletions

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
+```