docs: Update proto activate docs.

website/docs/proto/commands/activate.mdx

@@ -26,6 +26,28 @@ Learn more about
 
 :::
 
+### Arguments
+
+- `<shell>` - The shell to activate for.
+
+### Options
+
+- `--export` - Print the activate instructions in shell-specific syntax.
+- `--include-global` - Include global tools configured in `~/.proto/.prototools`.
+- `--json` - Print the activate instructions in JSON format.
+- `--no-bin` - Do not include `~/.proto/bin` when appending `PATH`.
+- `--no-shim` - Do not include `~/.proto/shims` when prepending `PATH`.
+
+### Caveats
+
+- Only tools that have a [version configured in `.prototools`](../config#pinning-versions) will be
+  activated.
+- Tool versions configured in the global `~/.proto/.prototools` are _not_ included by default. Pass
+  `--include-global` during activation to include them.
+  - Do note that this will worsen performance depending on the number of tools.
+- Activation is only applied _after changing directories_ and not when a new shell session is
+  started. We are looking into ways to support this.
+
 ### Setup
 
 The following activation steps should be added _after_ all environment variable and `PATH`
@@ -98,15 +120,3 @@ Add the following line to the end of your `~/.zshrc`.
 ```shell
 eval "$(proto activate zsh)"
 ```
-
-### Arguments
-
-- `<shell>` - The shell to activate for.
-
-### Options
-
-- `--export` - Print the activate instructions in shell-specific syntax.
-- `--include-global` - Include global tools configured in `~/.proto/.prototools`.
-- `--json` - Print the activate instructions in JSON format.
-- `--no-bin` - Do not include `~/.proto/bin` when prepending `PATH`.
-- `--no-shim` - Do not include `~/.proto/shims` when prepending `PATH`.

website/docs/proto/commands/upgrade.mdx

@@ -2,11 +2,16 @@
 title: upgrade
 ---
 
+import VersionLabel from '@site/src/components/Docs/VersionLabel';
+
 The `proto upgrade` (or `proto up`) command can be used to upgrade your current proto binary to the
-latest version.
+latest version, or check if you're currently outdated.
 
 ```shell
 $ proto upgrade
+
+# Up/downgrade to a specific version
+$ proto upgrade 0.39.0
 ```
 
 :::info
@@ -15,3 +20,13 @@ The previous binary will be moved to `~/.proto/tools/proto/<version>`, while the
 installed to `~/.proto/bin`.
 
 :::
+
+### Arguments
+
+- `<version>` - The version of proto to explicitly upgrade or downgrade to.
+  <VersionLabel version="0.39.3" />
+
+### Options
+
+- `--check` - Check if there's a new version without executing the upgrade.
+- `--json` - Print the upgrade information as JSON.

website/docs/proto/commands/use.mdx

@@ -13,9 +13,6 @@ The `proto use` (or `proto u`) command will download and install _all_ tools and
 parent [`.prototools`](../config) configuration files, and any [versions detected](../detection) in
 the current working directory (if not defined in `.prototools`).
 
-If [`auto-clean`](../config#auto-clean) is enabled, the command will also remove any stale or unused
-tools.
-
 ```shell
 $ proto use
 ```

website/docs/proto/config.mdx

@@ -79,9 +79,9 @@ semantic version.
 proto = "0.38.0"
 ```
 
-When configured, all shims (tools) will be executed with that explicit version of proto. This _does
-not_ apply to the version of proto globally installed, or for binaries linked in `~/.proto/bin` or
-via [`proto activate`](./commands/activate).
+Locking is currently enforced through [`proto activate`](./commands/activate), and when activated,
+all shims (tools) will be executed with that explicit version of proto. This _does not_ apply to the
+version of proto globally installed (in some situations), or for binaries linked in `~/.proto/bin`.
 
 ## Available settings
 
@@ -125,8 +125,8 @@ auto-install = true
 
 #### `auto-clean`
 
-When enabled, will automatically clean up the proto cache when [`proto use`](./commands/use) is ran.
-Defaults to `false` or `PROTO_AUTO_CLEAN`.
+When enabled, will automatically clean up the proto store in the background, by removing unused
+tools and outdated plugins. Defaults to `false` or `PROTO_AUTO_CLEAN`.
 
 ```toml title=".prototools"
 [settings]

website/docs/proto/workflows.mdx

@@ -10,7 +10,7 @@ individually, or together, it's up to you!
 
 ## Shims
 
-proto is primarily powered the by industry standard concept of shims. For each tool installed in
+proto is primarily powered by the industry standard concept of shims. For each tool installed in
 proto, a shim file will exist at `~/.proto/shims` for the primary executable, and some secondary
 executables. Shims _are not_ symlinks to the tool's binary, but are thin wrappers around
 [`proto run`](./commands/run), enabling [runtime version detection](./detection) on every
@@ -27,9 +27,14 @@ $ which node
 ~/.proto/shims/node
 ```
 
+### Setup
+
 To make use of shims, prepend the `~/.proto/shims` directory to `PATH` in your shell profile. This
 _must come before_ the [bin directory](#binary-linking) if using both.
 
+If you're using or plan to use [shell activation](#shell-activation), this happens automatically and
+can be ignored.
+
 ## Binary linking
 
 Alternatively, we also support a non-shim based approach, which creates symlinks to a versioned
@@ -41,17 +46,14 @@ $ node --version
 20.0.0
 
 $ which node
-~/.proto/bin/node -> /.proto/tools/node/20.0.0/bin/node
+~/.proto/bin/node -> ~/.proto/tools/node/20.0.0/bin/node
 ```
 
 The version of a tool that's symlinked _is not_ dynamic and is manually linked by pinning the chosen
 version with [`proto install --pin=global`](./commands/install) or
 [`proto pin --global`](./commands/pin). This also happens automatically the first time a tool is
 installed.
 
-To make use of bins, prepend the `~/.proto/bin` directory to `PATH` in your shell profile. This
-_must come after_ the [shim directory](#shims) if using both.
-
 :::warning
 
 Not all tools support symlinking a binary, as not all files are executable. For example, most
@@ -60,6 +62,14 @@ Node.js package managers currently do not support this, as JavaScript files are
 
 :::
 
+### Setup
+
+To make use of bins, prepend the `~/.proto/bin` directory to `PATH` in your shell profile. This
+_must come after_ the [shim directory](#shims) if using both.
+
+If you're using or plan to use [shell activation](#shell-activation), this happens automatically and
+can be ignored.
+
 ## Shell activation<VersionLabel version="0.38.0" />
 
 :::danger
@@ -70,19 +80,23 @@ please report an issue on [GitHub](https://github.com/moonrepo/proto) or
 
 :::
 
-Our last workflow is what we call shell activation (or shell hooks), and its where the proto
+Our last workflow is what we call shell activation (or shell hooks), and it's where the proto
 environment is setup/reset every time you change directories. If you're coming from another version
 manager, you may be familiar with this kind of workflow.
 
 So how does this work exactly? In your shell profile, you'll evaluate a call to
 [`proto activate <shell>`](./commands/activate), which generates a bunch of shell specific syntax
 that registers a hook for "run this code when the current directory or prompt line changes". Once
-this hook is registered and you run `cd` (for example), proto will load all tools and...
+this hook is registered and you run `cd` (for example), proto will...
 
-- Export environment variables based on [`[env]`](./config#env) and
-  [`[tools.*.env]`](./config#toolsenv)
-- Prepend `PATH` with tool-specific directories (like local and global executables) for the detected
-  version
+- Load all `.prototools` files
+- Extract tools with a [configured version](./config#pinning-versions)
+- For each tool:
+  - Load associated WASM plugin
+  - Export environment variables based on [`[env]`](./config#env) and
+    [`[tools.*.env]`](./config#toolsenv)
+  - Prepend `PATH` with tool-specific directories (like local and global executables) for the
+    detected version
 
 ```shell
 $ cd /some/path && node --version
@@ -92,12 +106,10 @@ $ cd /another/path && node --version
 18.0.0
 ```
 
-:::info
-
-View the [`proto activate`](./commands/activate) documentation for information on how to setup your
-shell profile for this workflow.
+### Setup
 
-:::
+View the [`proto activate`](./commands/activate#setup) documentation for information on how to setup
+your shell profile for this workflow.
 
 ## Comparison
 
@@ -113,3 +125,4 @@ comparison table outlining the features each workflow supports.
 | Includes tool globals/packages | 🔴                     | 🔴   | 🟢                             |
 | Exports environment variables  | 🔴                     | 🔴   | 🟢                             |
 | Prepends `PATH`                | 🔴                     | 🔴   | 🟢                             |
+| Can pin proto's version        | 🔴                     | 🔴   | 🟢                             |