docs: Add proto v0.41 docs. (#1646)

* Update commands.

* Add offline settings.

website/docs/proto/commands/alias.mdx

@@ -2,6 +2,8 @@
 title: alias
 ---
 
+import VersionLabel from '@site/src/components/Docs/VersionLabel';
+
 The `proto alias <tool> <alias> <version>` (or `proto a`) command will define a custom alias that
 maps to a specific version for the provided tool. Aliases can be used anywhere a version is
 accepted.
@@ -10,12 +12,8 @@ accepted.
 $ proto alias node work 16.16
 ```
 
-By default this will update the local [`./.prototools`](../config) file. Pass `--global` to update
-the global [`~/.proto/.prototools`](../config) file instead.
-
-```shell
-$ proto alias yarn berry 4 --global
-```
+By default this will update the local [`./.prototools`](../config) file. Pass `--to` to customize
+the location.
 
 ### Arguments
 
@@ -25,4 +23,7 @@ $ proto alias yarn berry 4 --global
 
 ## Options
 
-- `--global` - Pin to the global `~/.proto/.prototools` instead of the local `./.prototools`.
+- `--global` (deprecated) - Pin to the global `~/.proto/.prototools` instead of the local
+  `./.prototools`.
+- `--to` - [Location of `.prototools`](../config#locations) to update.
+  <VersionLabel version="0.41.0" />

website/docs/proto/commands/install.mdx

@@ -50,6 +50,9 @@ $ proto install bun --pin local
 
 # ~/.proto/.prototools
 $ proto install bun --pin global
+
+# ~/.prototools
+$ proto install bun --pin user
 ```
 
 ### Handling plugin hooks

website/docs/proto/commands/pin.mdx

@@ -6,22 +6,15 @@ import VersionLabel from '@site/src/components/Docs/VersionLabel';
 
 <VersionLabel version="0.19.0" header />
 
-The `proto pin <tool> <version>` command will pin a version (or alias) of a tool. By default it will
-pin to a `./.prototools` file in the current directory. This version will be used when attempting to
-[detect a version](../detection).
+The `proto pin <tool> <version>` command will pin a version (or alias) of a tool. This version will
+be used when attempting to [detect a version](../detection).
 
 ```shell
 $ proto pin go 1.20
 ```
 
-When the `--global` option is passed, the version will be pinned globally in `~/.proto/.prototools`.
-This version will be used as a global fallback when attempting to [detect a version](../detection).
-
-```shell
-$ proto pin go 1.20 --global
-```
-
-> [Learn more about the `.prototools` configuration file!](../config)
+By default this will update the local [`./.prototools`](../config) file. Pass `--to` to customize
+the location.
 
 ### Arguments
 
@@ -30,5 +23,8 @@ $ proto pin go 1.20 --global
 
 ### Options
 
-- `--global` - Pin to the global `~/.proto/.prototools` instead of the local `./.prototools`.
+- `--global` (deprecated) - Pin to the global `~/.proto/.prototools` instead of the local
+  `./.prototools`.
 - `--resolve` - Resolve the version to a fully-qualified semantic version before pinning.
+- `--to` - [Location of `.prototools`](../config#locations) to update.
+  <VersionLabel version="0.41.0" />

website/docs/proto/commands/plugin/add.mdx

@@ -8,8 +8,7 @@ import VersionLabel from '@site/src/components/Docs/VersionLabel';
 <VersionLabel version="0.23.0" header />
 
 The `proto plugin add <id> <plugin>` command will add the provided ID and plugin locator string to
-the `[plugins]` section of the local (`./.prototools`) or global (`~/.proto/.prototools`) config
-file.
+the `[plugins]` section of a chosen `.prototools`.
 
 ```shell
 $ proto plugin add node "https://github.com/moonrepo/node-plugin/releases/latest/download/node_plugin.wasm"
@@ -24,4 +23,7 @@ $ proto plugin add node "https://github.com/moonrepo/node-plugin/releases/latest
 
 ### Options
 
-- `--global` - Add to the global `~/.proto/.prototools` instead of the local `./.prototools`.
+- `--global` (deprecated) - Add to the global `~/.proto/.prototools` instead of the local
+  `./.prototools`.
+- `--to` - [Location of `.prototools`](../../config#locations) to update.
+  <VersionLabel version="0.41.0" />

website/docs/proto/commands/plugin/remove.mdx

@@ -8,7 +8,7 @@ import VersionLabel from '@site/src/components/Docs/VersionLabel';
 <VersionLabel version="0.23.0" header />
 
 The `proto plugin remove <id>` command will remove the provided tool ID from the `[plugins]` section
-of the local (`./.prototools`) or global (`~/.proto/.prototools`) config file.
+of the chosen (`.prototools`).
 
 ```shell
 $ proto plugin remove node
@@ -22,4 +22,7 @@ $ proto plugin remove node
 
 ### Options
 
-- `--global` - Remove from the global `~/.proto/.prototools` instead of the local `./.prototools`.
+- `--from` - [Location of `.prototools`](../../config#locations) to update.
+  <VersionLabel version="0.41.0" />
+- `--global` (deprecated) - Remove from the global `~/.proto/.prototools` instead of the local
+  `./.prototools`.

website/docs/proto/commands/unalias.mdx

@@ -2,19 +2,17 @@
 title: unalias
 ---
 
+import VersionLabel from '@site/src/components/Docs/VersionLabel';
+
 The `proto unalias <tool> <alias>` (or `proto ua`) command will remove a custom alias for the
 provided tool.
 
 ```shell
 $ proto unalias node work
 ```
 
-By default this will update the local [`./.prototools`](../config) file. Pass `--global` to update
-the global [`~/.proto/.prototools`](../config) file instead.
-
-```shell
-$ proto unalias yarn berry --global
-```
+By default this will update the local [`./.prototools`](../config) file. Pass `--from` to customize
+the location.
 
 ### Arguments
 
@@ -23,4 +21,7 @@ $ proto unalias yarn berry --global
 
 ## Options
 
-- `--global` - Remove from the global `~/.proto/.prototools` instead of the local `./.prototools`.
+- `--from` - [Location of `.prototools`](../config#locations) to update.
+  <VersionLabel version="0.41.0" />
+- `--global` (deprecated) - Remove from the global `~/.proto/.prototools` instead of the local
+  `./.prototools`.

website/docs/proto/commands/unpin.mdx

@@ -6,24 +6,22 @@ import VersionLabel from '@site/src/components/Docs/VersionLabel';
 
 <VersionLabel version="0.36.0" header />
 
-The `proto unpin <tool>` command will unpin a version of a tool. By default it will remove from a
-`./.prototools` file in the current directory.
+The `proto unpin <tool>` command will unpin a version of a tool.
 
 ```shell
 $ proto unpin go
 ```
 
-When the `--global` option is passed, the version will be removed globally from
-`~/.proto/.prototools`.
-
-```shell
-$ proto unpin go --global
-```
+By default this will update the local [`./.prototools`](../config) file. Pass `--from` to customize
+the location.
 
 ### Arguments
 
 - `<tool>` - Type of tool.
 
 ### Options
 
-- `--global` - Unpin from the global `~/.proto/.prototools` instead of the local `./.prototools`.
+- `--from` - [Location of `.prototools`](../config#locations) to update.
+  <VersionLabel version="0.41.0" />
+- `--global` (deprecated) - Unpin from the global `~/.proto/.prototools` instead of the local
+  `./.prototools`.

website/docs/proto/config.mdx

@@ -10,6 +10,30 @@ We support configuration at both the project-level and user-level using a
 tools, provide tool specific configuration, enable new tools via plugins, define proto settings, and
 more.
 
+## Locations<VersionLabel version="0.41.0" />
+
+proto supports 3 locations in which a `.prototools` file can exist. These locations are used
+throughout the command line and proto's own settings.
+
+- `local` -> `./.prototools` (current directory)
+- `global` -> `~/.proto/.prototools`
+- `user` -> `~/.prototools`
+
+> Local is a bit of a misnomer as a `.prototools` file can theoretically exist in any directory, but
+> when reading/writing to a file, `local` refers to the current working directory.
+
+### Where to configure?
+
+With so many locations to store proto configuration, the question of where to store certain
+configurations become blurred, especially when [resolution](#resolution-mode) comes into play. We
+suggest the following locations:
+
+- Default/fallback [versions](#pinning-versions) of tools -> `global`
+- Project specific [versions](#pinning-versions) of tools -> `local`
+- Project specific [settings](#settings) -> `local`
+- Shared/developer [settings](#settings) -> `user`
+- Non-project related -> `user`
+
 ## Resolution mode<VersionLabel version="0.40.0" />
 
 When a `proto` command or shim is ran, we must find and load all applicable `.prototools` files. We
@@ -203,7 +227,9 @@ When defined and a tool is installed with the "latest" version, will automatical
 version to the configured location. Defaults to disabled or `PROTO_PIN_LATEST`.
 
 - `global` - Pins globally to `~/.proto/.prototools`.
-- `local` - Pins locally to `.prototools` in current directory.
+- `local` - Pins locally to `./.prototools` in current directory.
+- `user` - Pins to the user's `~/.prototools` in their home directory.
+  <VersionLabel version="0.41.0" />
 
 ```toml title=".prototools"
 [settings]
@@ -261,6 +287,42 @@ environment. Supports `pem` and `der` files.
 root-cert = "/path/to/root/cert.pem"
 ```
 
+### `[settings.offline]`<VersionLabel version="0.41.0" />
+
+Can be used to customize how we detect an internet connection for offline based logic. These
+settings are useful if you're behind a VPN or corporate proxy.
+
+#### `custom-hosts`
+
+A list of custom hosts to ping. Will be appended to our
+[default list of hosts](#override-default-hosts) and will be ran last.
+
+```toml title=".prototools"
+[settings.offline]
+custom-hosts = ["proxy.corp.domain.com:80"]
+```
+
+#### `override-default-hosts`
+
+If our default hosts are blocked or are too slow, you can disable pinging them by setting this
+option to true. Our default hosts are Google DNS, Cloudflare DNS, and then Google and Mozilla hosts.
+
+This should be used in parallel with [`custom-hosts`](#custom-hosts).
+
+```toml title=".prototools"
+[settings.offline]
+override-default-hosts = true
+```
+
+#### `timeout`
+
+The timeout in milliseconds to wait for a ping against a host to resolve. Default timeout is 750ms.
+
+```toml title=".prototools"
+[settings.offline]
+timeout = 500
+```
+
 ### `[plugins]`
 
 Additional [plugins](./plugins) can be configured with the `[plugins]` section.