diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 8ff378fac5..e6301094a1 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -30,6 +30,7 @@ export default defineConfig({
             collapsed: true,
             items: [{ text: "Demo", link: "/demo" }],
           },
+          { text: "Installing mise", link: "/installing-mise" },
           { text: "IDE Integration", link: "/ide-integration" },
           { text: "Continuous Integration", link: "/continuous-integration" },
         ],
diff --git a/docs/dev-tools/shims.md b/docs/dev-tools/shims.md
index 843bee69a4..97c5fcb372 100644
--- a/docs/dev-tools/shims.md
+++ b/docs/dev-tools/shims.md
@@ -4,7 +4,14 @@
 The [beginner's guide](https://dev.to/jdxcode/beginners-guide-to-rtx-ac4), and my [blog post](https://jdx.dev/posts/2024-04-13-shims-how-they-work-in-mise-en-place/) are helpful resources to dive deeper into shims.
 :::
 
-While the PATH design of mise works great in most cases, there are some situations where shims are
+## Introduction
+
+There are two ways for dev tools to be loaded into your shell: `mise activate` and `shims`.
+
+- Mise's "PATH" activation method updates environment variables at each prompt by modifying `PATH`
+- The "shims" method uses symlinks to the mise binary that intercept commands and load the appropriate environment
+
+While the `PATH` design of mise works great in most cases, there are some situations where shims are
 preferable. One example is when calling mise binaries from an IDE.
 
 To support this, mise does have a shim dir that can be used. It's located at `~/.local/share/mise/shims`.
@@ -33,6 +40,34 @@ mise also runs a reshim anytime a tool is installed/updated/removed so you don't
 Also don't put things in there manually, mise will just delete it next reshim.
 :::
 
+## How to add mise shims to PATH
+
+If you prefer to use shims, you can run the following to use mise without activating it.
+
+You can use `.bashrc`/`.zshrc` instead of `.bash_profile`/`.zprofile` if you prefer to only use
+mise in interactive sessions (`.bash_profile`/`.zprofile` will work in non-interactive places
+like scripts or IDEs).
+
+::: code-group
+
+```sh [bash]
+# note that bash will read from ~/.profile or ~/.bash_profile if the latter exists
+# ergo, you may want to check to see which is defined on your system and only append to the existing file
+echo 'export PATH="$HOME/.local/share/mise/shims:$PATH"' >> ~/.bash_profile
+```
+
+```sh [zsh]
+echo 'export PATH="$HOME/.local/share/mise/shims:$PATH"' >> ~/.zprofile
+```
+
+```sh [fish]
+fish_add_path ~/.local/share/mise/shims
+```
+
+:::tip
+You can also run `mise activate --shims` which will do the above for you.
+:::
+
 ## Shims vs PATH
 
 In general, I recommend using PATH (`mise activate`) instead of shims for _interactive_ situations. The
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 47d6f0b0d6..3e830aada2 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -1,44 +1,40 @@
 # Getting Started
 
-Using mise typically involves 3 steps:
+This will show you how to install mise and get started with it. This is a suitatable way when using an interactive shell like `bash`, `zsh`, or `fish`.
 
-1. Installing the CLI
-2. Activating mise or adding its shims to PATH <Badge type="tip" text="optional" />
-3. Adding tools to mise
+## 1. Install `mise` CLI
 
-## Quickstart
+See [installing mise](/installing-mise) for other ways to install mise (`apt`, `yum`, `nix`, etc.).
 
-### 1. Install `mise` CLI
+```shell
+curl https://mise.run | sh
+```
 
-First we need to download the mise CLI.
-See [below](#alternate-installation-methods) for alternate installation methods.
-This directory is simply a suggestion.
-mise can be installed anywhere.
+By default, mise will be installed to `~/.local/bin` (this is simply a suggestion. `mise` can be installed anywhere).
+You can verify the installation by running:
 
-```sh
-$ curl https://mise.run | sh
-$ ~/.local/bin/mise --version
-mise 2024.x.x
+```shell
+~/.local/bin/mise --version
+# mise 2024.x.x
 ```
 
-::: tip
-"~/.local/bin" does not need to be in PATH. mise will automatically add its own directory to PATH
-when activated.
-:::
+::: info
 
-### 2a. Activate mise
+- `~/.local/bin` does not need to be in `PATH`. mise will automatically add its own directory to `PATH`
+  when activated.
+- mise respects [`MISE_DATA_DIR`](/configuration) and [`XDG_DATA_HOME`](/configuration) if you'd like
+  to change these locations.
+  :::
 
-`mise activate` is one way to setup mise but alternatively you can
-use [shims](dev-tools/shims.md), [direnv](./direnv), or skip
-this step entirely. If you skip it, then tools like `npm` and `node` will not be in PATH. You'll
-need to prefix
-commands with `mise exec` or run tasks with `mise run` in order to use tools managed with mise.
+## 2. Activate `mise`
 
-Make sure you restart your shell session after modifying your rc file in order for it to take
-effect. Also note that
-this uses `~/.local/bin/mise` as the binary location since that's what <https://mise.run> uses by
-default. If you've
-installed mise by some other means it may be on PATH or somewhere different.
+Now that `mise` is installed, you can optionally activate it or add its [shims](dev-tools/shims.md) to `PATH`.
+
+- [`mise activate`](/cli/activate) method updates your environment variable and `PATH` every time your prompt is run to ensure you use the correct versions.
+- [Shims](dev-tools/shims.md) are symlinks to the `mise` binary that intercept commands and load the appropriate environment
+
+For interactive shells, `mise activate` is recommended. In non-interactive sessions, like CI/CD, IDEs, and scripts, using `shims` might work best. You can also not use any and call `mise exec/run` directly instead.
+See [this guide](dev-tools/shims.md) for more information.
 
 ::: code-group
 
@@ -54,62 +50,32 @@ echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc
 echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish
 ```
 
-:::
-
-### 2b. Alternative: Add mise shims to PATH
-
-If you prefer to use shims, you can run the following to use mise without activating it.
-You can use .bashrc/.zshrc instead of .bash_profile/.zprofile if you prefer to only use
-mise in interactive sessions (.bash_profile/.zprofile will work in non-interactive places
-like scripts or IDEs).
-
-::: code-group
-
-```sh [bash]
-# note that bash will read from ~/.profile or ~/.bash_profile if the latter exists
-# ergo, you may want to check to see which is defined on your system and only append to the existing file
-echo 'export PATH="$HOME/.local/share/mise/shims:$PATH"' >> ~/.bash_profile
-```
-
-```sh [zsh]
-echo 'export PATH="$HOME/.local/share/mise/shims:$PATH"' >> ~/.zprofile
-```
-
-```sh [fish]
-fish_add_path ~/.local/share/mise/shims
-```
-
-:::tip
-You can also run `mise activate --shims` which will do the above for you.
-:::
-
-:::info
-mise respects [`MISE_DATA_DIR`](/configuration) and [`XDG_DATA_HOME`](/configuration) if you'd like
-to change these locations.
-:::
+- Make sure you restart your shell session after modifying your rc file in order for it to take
+  effect.
+- Also note that
+  this uses `~/.local/bin/mise` as the binary location since that's what <https://mise.run> uses by
+  default. If you've
+  installed mise by some other means it may be on `PATH` or somewhere different.
 
-### 3. Adding tools to mise <Badge type="tip" text="optional" />
+## 3. Using `mise`
 
 :::info
 Of course, if using mise solely for [environment management](/environments)
 or [running tasks](/tasks/)
-this step is not necessary.
+this step is not necessary. You can use it to make sure `mise` is correctly setup.
 :::
 
-Install node and set it as the global default:
+Install `node` and set it as the global default:
 
 ```sh
-$ mise use --global node@20
-$ node -v
-v20.x.x
+mise use --global node@22
 ```
 
-If you did not activate mise or add its shims to PATH, then you'll need to run the following:
+You can now run `node` using `mise exec`:
 
 ```sh
-$ mise use --global node@20
-$ mise exec -- node -v
-v20.x.x
+mise exec -- node -v
+# v22.x.x
 ```
 
 :::tip
@@ -117,332 +83,22 @@ Use `mise x -- node -v` or set a shell alias in your shell's rc file like `alias
 save some keystrokes.
 :::
 
-## Alternate Installation Methods
-
-### <https://mise.run>
-
-Note that it isn't necessary for `mise` to be on `PATH`. If you run the activate script in your
-shell's rc
-file, mise will automatically add itself to `PATH`.
-
-```sh
-curl https://mise.run | sh
-```
-
-Options:
-
-- `MISE_DEBUG=1` – enable debug logging
-- `MISE_QUIET=1` – disable non-error output
-- `MISE_INSTALL_PATH=/some/path` – change the binary path (default: `~/.local/bin/mise`)
-- `MISE_VERSION=v2024.5.17` – install a specific version
-
-If you want to verify the install script hasn't been tampered with:
-
-```sh
-gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 0x7413A06D
-curl https://mise.jdx.dev/install.sh.sig | gpg --decrypt > install.sh
-# ensure the above is signed with the mise release key
-sh ./install.sh
-```
-
-or if you're allergic to `| sh`:
-
-::: code-group
-
-```sh [macos-arm64]
-curl https://mise.jdx.dev/mise-latest-macos-arm64 > ~/.local/bin/mise
-chmod +x ~/.local/bin/mise
-```
-
-```sh [macos-x64]
-curl https://mise.jdx.dev/mise-latest-macos-x64 > ~/.local/bin/mise
-chmod +x ~/.local/bin/mise
-```
-
-```sh [linux-x64]
-curl https://mise.jdx.dev/mise-latest-linux-x64 > ~/.local/bin/mise
-chmod +x ~/.local/bin/mise
-```
-
-```sh [linux-arm64]
-curl https://mise.jdx.dev/mise-latest-linux-arm64 > ~/.local/bin/mise
-chmod +x ~/.local/bin/mise
-```
-
-:::
-
-It doesn't matter where you put it. So use `~/bin`, `/usr/local/bin`, `~/.local/bin` or whatever.
-
-Supported os/arch:
-
-- `macos-x64`
-- `macos-arm64`
-- `linux-x64`
-- `linux-x64-musl`
-- `linux-arm64`
-- `linux-arm64-musl`
-- `linux-armv6`
-- `linux-armv6-musl`
-- `linux-armv7`
-- `linux-armv7-musl`
-
-If you need something else, compile it with `cargo install mise` (see below).
-
-### apk
-
-For Alpine Linux:
-
-```sh
-apk add mise
-```
-
-_mise lives in
-the [community repository](https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/community/mise/APKBUILD)._
-
-### apt
-
-For installation on Ubuntu/Debian:
-
-::: code-group
-
-```sh [amd64]
-apt update -y && apt install -y gpg sudo wget curl
-sudo install -dm 755 /etc/apt/keyrings
-wget -qO - https://mise.jdx.dev/gpg-key.pub | gpg --dearmor | sudo tee /etc/apt/keyrings/mise-archive-keyring.gpg 1> /dev/null
-echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.gpg arch=amd64] https://mise.jdx.dev/deb stable main" | sudo tee /etc/apt/sources.list.d/mise.list
-sudo apt update
-sudo apt install -y mise
-```
-
-```sh [arm64]
-apt update -y && apt install -y gpg sudo wget curl
-sudo install -dm 755 /etc/apt/keyrings
-wget -qO - https://mise.jdx.dev/gpg-key.pub | gpg --dearmor | sudo tee /etc/apt/keyrings/mise-archive-keyring.gpg 1> /dev/null
-echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.gpg arch=arm64] https://mise.jdx.dev/deb stable main" | sudo tee /etc/apt/sources.list.d/mise.list
-sudo apt update
-sudo apt install -y mise
-```
-
-:::
-
-### aur
-
-For Arch Linux:
-
-```sh
-git clone https://aur.archlinux.org/mise.git
-cd mise
-makepkg -si
-```
-
-### Cargo
-
-Build from source with Cargo:
-
-```sh
-cargo install mise
-```
-
-Do it faster with [cargo-binstall](https://github.com/cargo-bins/cargo-binstall):
-
-```sh
-cargo install cargo-binstall
-cargo binstall mise
-```
-
-Build from the latest commit in main:
-
-```sh
-cargo install mise --git https://github.com/jdx/mise --branch main
-```
-
-### dnf
-
-For Fedora, CentOS, Amazon Linux, RHEL and other dnf-based distributions:
-
-```sh
-dnf install -y dnf-plugins-core
-dnf config-manager --add-repo https://mise.jdx.dev/rpm/mise.repo
-dnf install -y mise
-```
-
-### Docker
-
-```sh
-docker run jdxcode/mise x node@20 -- node -v
-```
-
-### Homebrew
-
-```sh
-brew install mise
-```
-
-### npm
-
-mise is available on npm as a precompiled binary. This isn't a Node.js package—just distributed
-via npm. This is useful for JS projects that want to setup mise via `package.json` or `npx`.
-
-```sh
-npm install -g @jdxcode/mise
-```
-
-Use npx if you just want to test it out for a single command without fully installing:
-
-```sh
-npx @jdxcode/mise exec python@3.11 -- python some_script.py
-```
-
-### GitHub Releases
-
-Download the latest release from [GitHub](https://github.com/jdx/mise/releases).
-
-```sh
-curl -L https://github.com/jdx/mise/releases/download/v2024.1.0/mise-v2024.1.0-linux-x64 > /usr/local/bin/mise
-chmod +x /usr/local/bin/mise
-```
-
-### MacPorts
-
-```sh
-sudo port install mise
-```
-
-### nix
-
-For the Nix package manager, at release 23.05 or later:
-
-```sh
-nix-env -iA mise
-```
-
-You can also import the package directly using
-`mise-flake.packages.${system}.mise`. It supports all default Nix
-systems.
-
-### yum
-
-```sh
-yum install -y yum-utils
-yum-config-manager --add-repo https://mise.jdx.dev/rpm/mise.repo
-yum install -y mise
-```
-
-### Windows
-
-Download the latest release from [GitHub](https://github.com/jdx/mise/releases) and add the binary
-to your PATH.
-
-If your shell does not support `mise activate`, you would want to edit PATH to include the shims directory (by default: `%LOCALAPPDATA%\mise\shims`).
-
-Note that Windows support is very minimal for now.
-
-## Shells
-
-### Bash
-
-```sh
-echo 'eval "$(mise activate bash)"' >> ~/.bashrc
-```
-
-### Zsh
-
-```sh
-echo 'eval "$(mise activate zsh)"' >> "${ZDOTDIR-$HOME}/.zshrc"
-```
-
-### Fish
-
-```sh
-echo 'mise activate fish | source' >> ~/.config/fish/config.fish
-```
-
-::: tip
-For homebrew and possibly other installs mise is automatically activated so
-this is not necessary.
-
-See [`MISE_FISH_AUTO_ACTIVATE=1`](/configuration#mise_fish_auto_activate1) for more information.
-:::
-
-### Nushell
-
-Nu
-does [not support `eval`](https://www.nushell.sh/book/how_nushell_code_gets_run.html#eval-function)
-Install Mise by appending `env.nu` and `config.nu`:
-
-```nushell
-'
-let mise_path = $nu.default-config-dir | path join mise.nu
-^mise activate nu | save $mise_path --force
-' | save $nu.env-path --append
-"\nuse ($nu.default-config-dir | path join mise.nu)" | save $nu.config-path --append
-```
-
-If you prefer to keep your dotfiles clean you can save it to a different directory then
-update `$env.NU_LIB_DIRS`:
-
-```nushell
-"\n$env.NU_LIB_DIRS ++= ($mise_path | path dirname | to nuon)" | save $nu.env-path --append
-```
-
-### Xonsh
-
-Since `.xsh` files are [not compiled](https://github.com/xonsh/xonsh/issues/3953) you may shave a
-bit off startup time by using a pure Python import: add the code below to, for
-example, `~/.config/xonsh/mise.py` config file and `import mise` it in `~/.config/xonsh/rc.xsh`:
-
-```python
-from pathlib         import Path
-from xonsh.built_ins import XSH
-
-ctx = XSH.ctx
-mise_init = subprocess.run([Path('~/bin/mise').expanduser(),'activate','xonsh'],capture_output=True,encoding="UTF-8").stdout
-XSH.builtins.execx(mise_init,'exec',ctx,filename='mise')
-```
-
-Or continue to use `rc.xsh`/`.xonshrc`:
+If you did activate `mise` or add its shims to `PATH`, then `node` is also available directly!
 
 ```sh
-echo 'execx($(~/bin/mise activate xonsh))' >> ~/.config/xonsh/rc.xsh # or ~/.xonshrc
+node -v
+# v22.x.x
 ```
 
-Given that `mise` replaces both shell env `$PATH` and OS environ `PATH`, watch out that your configs
-don't have these two set differently (might
-throw `os.environ['PATH'] = xonsh.built_ins.XSH.env.get_detyped('PATH')` at the end of a config to
-make sure they match)
-
-### Elvish
-
-Add following to your `rc.elv`:
+Note that when you ran `mise use --global node@22`, `mise` updated the global `mise` configuration.
 
 ```shell
-var mise: = (eval &ns=[&] &on-end=$put~ (mise activate elvish | slurp))
-mise:activate
+cat ~/.config/mise/config.toml
 ```
 
-Optionally alias `mise` to `mise:mise` for seamless integration of `mise {activate,deactivate,shell}`:
-
-```shell
-fn mise {|@args| mise:mise $@args }
+```toml
+[tools]
+node = "22"
 ```
 
-### Something else?
-
-Adding a new shell is not hard at all since very little shell code is
-in this project.
-[See here](https://github.com/jdx/mise/tree/main/src/shell) for how
-the others are implemented. If your shell isn't currently supported
-I'd be happy to help you get yours integrated.
-
-## Uninstalling
-
-Use `mise implode` to uninstall mise. This will remove the mise binary and all of its data. Use
-`mise implode --help` for more information.
-
-Alternatively, manually remove the following directories to fully clean up:
-
-- `~/.local/share/mise` (can also be `MISE_DATA_DIR` or `XDG_DATA_HOME/mise`)
-- `~/.local/state/mise` (can also be `MISE_STATE_DIR` or `XDG_STATE_HOME/mise`)
-- `~/.config/mise` (can also be `MISE_CONFIG_DIR` or `XDG_CONFIG_HOME/mise`)
-- on Linux: `~/.cache/mise` (can also be `MISE_CACHE_DIR` or `XDG_CACHE_HOME/mise`)
-- on macOS: `~/Library/Caches/mise` (can also be `MISE_CACHE_DIR`)
+Follow the [walkthrough](/walkthrough) for more examples on how to use mise.
diff --git a/docs/installing-mise.md b/docs/installing-mise.md
new file mode 100644
index 0000000000..9987c4c427
--- /dev/null
+++ b/docs/installing-mise.md
@@ -0,0 +1,338 @@
+# Installing Mise
+
+If you are new to `mise`, follow the [getting Started](/getting-started) guide first.
+
+## Installation Methods
+
+This page lists various ways to install `mise` on your system.
+
+### <https://mise.run>
+
+Note that it isn't necessary for `mise` to be on `PATH`. If you run the activate script in your
+shell's rc
+file, mise will automatically add itself to `PATH`.
+
+```sh
+curl https://mise.run | sh
+
+# or with options
+curl https://mise.run | MISE_INSTALL_PATH=/usr/local/bin/mise sh
+```
+
+Options:
+
+- `MISE_DEBUG=1` – enable debug logging
+- `MISE_QUIET=1` – disable non-error output
+- `MISE_INSTALL_PATH=/some/path` – change the binary path (default: `~/.local/bin/mise`)
+- `MISE_VERSION=v2024.5.17` – install a specific version
+
+If you want to verify the install script hasn't been tampered with:
+
+```sh
+gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 0x7413A06D
+curl https://mise.jdx.dev/install.sh.sig | gpg --decrypt > install.sh
+# ensure the above is signed with the mise release key
+sh ./install.sh
+```
+
+or if you're allergic to `| sh`:
+
+::: code-group
+
+```sh [macos-arm64]
+curl https://mise.jdx.dev/mise-latest-macos-arm64 > ~/.local/bin/mise
+chmod +x ~/.local/bin/mise
+```
+
+```sh [macos-x64]
+curl https://mise.jdx.dev/mise-latest-macos-x64 > ~/.local/bin/mise
+chmod +x ~/.local/bin/mise
+```
+
+```sh [linux-x64]
+curl https://mise.jdx.dev/mise-latest-linux-x64 > ~/.local/bin/mise
+chmod +x ~/.local/bin/mise
+```
+
+```sh [linux-arm64]
+curl https://mise.jdx.dev/mise-latest-linux-arm64 > ~/.local/bin/mise
+chmod +x ~/.local/bin/mise
+```
+
+:::
+
+It doesn't matter where you put it. So use `~/bin`, `/usr/local/bin`, `~/.local/bin` or whatever.
+
+Supported os/arch:
+
+- `macos-x64`
+- `macos-arm64`
+- `linux-x64`
+- `linux-x64-musl`
+- `linux-arm64`
+- `linux-arm64-musl`
+- `linux-armv6`
+- `linux-armv6-musl`
+- `linux-armv7`
+- `linux-armv7-musl`
+
+If you need something else, compile it with `cargo install mise` (see below).
+
+### apk
+
+For Alpine Linux:
+
+```sh
+apk add mise
+```
+
+_mise lives in
+the [community repository](https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/community/mise/APKBUILD)._
+
+### apt
+
+For installation on Ubuntu/Debian:
+
+::: code-group
+
+```sh [amd64]
+apt update -y && apt install -y gpg sudo wget curl
+sudo install -dm 755 /etc/apt/keyrings
+wget -qO - https://mise.jdx.dev/gpg-key.pub | gpg --dearmor | sudo tee /etc/apt/keyrings/mise-archive-keyring.gpg 1> /dev/null
+echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.gpg arch=amd64] https://mise.jdx.dev/deb stable main" | sudo tee /etc/apt/sources.list.d/mise.list
+sudo apt update
+sudo apt install -y mise
+```
+
+```sh [arm64]
+apt update -y && apt install -y gpg sudo wget curl
+sudo install -dm 755 /etc/apt/keyrings
+wget -qO - https://mise.jdx.dev/gpg-key.pub | gpg --dearmor | sudo tee /etc/apt/keyrings/mise-archive-keyring.gpg 1> /dev/null
+echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.gpg arch=arm64] https://mise.jdx.dev/deb stable main" | sudo tee /etc/apt/sources.list.d/mise.list
+sudo apt update
+sudo apt install -y mise
+```
+
+:::
+
+### aur
+
+For Arch Linux:
+
+```sh
+git clone https://aur.archlinux.org/mise.git
+cd mise
+makepkg -si
+```
+
+### Cargo
+
+Build from source with Cargo:
+
+```sh
+cargo install mise
+```
+
+Do it faster with [cargo-binstall](https://github.com/cargo-bins/cargo-binstall):
+
+```sh
+cargo install cargo-binstall
+cargo binstall mise
+```
+
+Build from the latest commit in main:
+
+```sh
+cargo install mise --git https://github.com/jdx/mise --branch main
+```
+
+### dnf
+
+For Fedora, CentOS, Amazon Linux, RHEL and other dnf-based distributions:
+
+```sh
+dnf install -y dnf-plugins-core
+dnf config-manager --add-repo https://mise.jdx.dev/rpm/mise.repo
+dnf install -y mise
+```
+
+### Docker
+
+```sh
+docker run jdxcode/mise x node@20 -- node -v
+```
+
+### Homebrew
+
+```sh
+brew install mise
+```
+
+### npm
+
+mise is available on npm as a precompiled binary. This isn't a Node.js package—just distributed
+via npm. This is useful for JS projects that want to setup mise via `package.json` or `npx`.
+
+```sh
+npm install -g @jdxcode/mise
+```
+
+Use npx if you just want to test it out for a single command without fully installing:
+
+```sh
+npx @jdxcode/mise exec python@3.11 -- python some_script.py
+```
+
+### GitHub Releases
+
+Download the latest release from [GitHub](https://github.com/jdx/mise/releases).
+
+```sh
+curl -L https://github.com/jdx/mise/releases/download/v2024.1.0/mise-v2024.1.0-linux-x64 > /usr/local/bin/mise
+chmod +x /usr/local/bin/mise
+```
+
+### MacPorts
+
+```sh
+sudo port install mise
+```
+
+### nix
+
+For the Nix package manager, at release 23.05 or later:
+
+```sh
+nix-env -iA mise
+```
+
+You can also import the package directly using
+`mise-flake.packages.${system}.mise`. It supports all default Nix
+systems.
+
+### yum
+
+```sh
+yum install -y yum-utils
+yum-config-manager --add-repo https://mise.jdx.dev/rpm/mise.repo
+yum install -y mise
+```
+
+### Windows
+
+Download the latest release from [GitHub](https://github.com/jdx/mise/releases) and add the binary
+to your PATH.
+
+If your shell does not support `mise activate`, you would want to edit PATH to include the shims directory (by default: `%LOCALAPPDATA%\mise\shims`).
+
+Note that Windows support is very minimal for now.
+
+## Shells
+
+### Bash
+
+```sh
+echo 'eval "$(mise activate bash)"' >> ~/.bashrc
+```
+
+### Zsh
+
+```sh
+echo 'eval "$(mise activate zsh)"' >> "${ZDOTDIR-$HOME}/.zshrc"
+```
+
+### Fish
+
+```sh
+echo 'mise activate fish | source' >> ~/.config/fish/config.fish
+```
+
+::: tip
+For homebrew and possibly other installs mise is automatically activated so
+this is not necessary.
+
+See [`MISE_FISH_AUTO_ACTIVATE=1`](/configuration#mise_fish_auto_activate1) for more information.
+:::
+
+### Nushell
+
+Nu
+does [not support `eval`](https://www.nushell.sh/book/how_nushell_code_gets_run.html#eval-function)
+Install Mise by appending `env.nu` and `config.nu`:
+
+```nushell
+'
+let mise_path = $nu.default-config-dir | path join mise.nu
+^mise activate nu | save $mise_path --force
+' | save $nu.env-path --append
+"\nuse ($nu.default-config-dir | path join mise.nu)" | save $nu.config-path --append
+```
+
+If you prefer to keep your dotfiles clean you can save it to a different directory then
+update `$env.NU_LIB_DIRS`:
+
+```nushell
+"\n$env.NU_LIB_DIRS ++= ($mise_path | path dirname | to nuon)" | save $nu.env-path --append
+```
+
+### Xonsh
+
+Since `.xsh` files are [not compiled](https://github.com/xonsh/xonsh/issues/3953) you may shave a
+bit off startup time by using a pure Python import: add the code below to, for
+example, `~/.config/xonsh/mise.py` config file and `import mise` it in `~/.config/xonsh/rc.xsh`:
+
+```python
+from pathlib         import Path
+from xonsh.built_ins import XSH
+
+ctx = XSH.ctx
+mise_init = subprocess.run([Path('~/bin/mise').expanduser(),'activate','xonsh'],capture_output=True,encoding="UTF-8").stdout
+XSH.builtins.execx(mise_init,'exec',ctx,filename='mise')
+```
+
+Or continue to use `rc.xsh`/`.xonshrc`:
+
+```sh
+echo 'execx($(~/bin/mise activate xonsh))' >> ~/.config/xonsh/rc.xsh # or ~/.xonshrc
+```
+
+Given that `mise` replaces both shell env `$PATH` and OS environ `PATH`, watch out that your configs
+don't have these two set differently (might
+throw `os.environ['PATH'] = xonsh.built_ins.XSH.env.get_detyped('PATH')` at the end of a config to
+make sure they match)
+
+### Elvish
+
+Add following to your `rc.elv`:
+
+```shell
+var mise: = (eval &ns=[&] &on-end=$put~ (mise activate elvish | slurp))
+mise:activate
+```
+
+Optionally alias `mise` to `mise:mise` for seamless integration of `mise {activate,deactivate,shell}`:
+
+```shell
+fn mise {|@args| mise:mise $@args }
+```
+
+### Something else?
+
+Adding a new shell is not hard at all since very little shell code is
+in this project.
+[See here](https://github.com/jdx/mise/tree/main/src/shell) for how
+the others are implemented. If your shell isn't currently supported
+I'd be happy to help you get yours integrated.
+
+## Uninstalling
+
+Use `mise implode` to uninstall mise. This will remove the mise binary and all of its data. Use
+`mise implode --help` for more information.
+
+Alternatively, manually remove the following directories to fully clean up:
+
+- `~/.local/share/mise` (can also be `MISE_DATA_DIR` or `XDG_DATA_HOME/mise`)
+- `~/.local/state/mise` (can also be `MISE_STATE_DIR` or `XDG_STATE_HOME/mise`)
+- `~/.config/mise` (can also be `MISE_CONFIG_DIR` or `XDG_CONFIG_HOME/mise`)
+- on Linux: `~/.cache/mise` (can also be `MISE_CACHE_DIR` or `XDG_CACHE_HOME/mise`)
+- on macOS: `~/Library/Caches/mise` (can also be `MISE_CACHE_DIR`)
diff --git a/docs/walkthrough.md b/docs/walkthrough.md
index 488876e4a6..9b652da28e 100644
--- a/docs/walkthrough.md
+++ b/docs/walkthrough.md
@@ -15,35 +15,49 @@ Both of these are required to use a tool. If you simply install a tool via `mise
 It must also be added to `mise.toml`—which is why I promote using `mise use` since it does both.
 :::
 
-You use it like so—note that mise must be [activated](/cli/activate) for this to work:
+You use it like so (note that `mise` must be [activated](/getting-started.html#_2-activate-mise) for this to work):
 
 ```bash
-$ mise use node@22
-$ node -v
-v22.0.0
+mkdir example-project && cd example-project
+mise use node@22
+node -v
+# v22.0.0
 ```
 
 And you'll also note that you now have a `mise.toml` file with the following content:
 
+```shell
+cat mise.toml
+```
+
 ```toml
 [tools]
 node = "22"
 ```
 
-If this file is in the root of a project, node will be installed whenever someone runs [`mise install|i`](/cli/install).
-This is the command you want to run when you first clone a project or when you want to update installed tools.
+- If this file is in the root of a project, `node` will be installed whenever someone runs [`mise install|i`](/cli/install).
+- This is the command you want to run when you first clone a project or when you want to update installed tools.
 
 ## `mise.toml` Configuration
 
-Share this file with others so they can get the same tools you're using. [`mise.local.toml`](/configuration#mise-toml)
-is an alternate config file you can use that is intended _not_ to be shared with others.
+Use [`mise.toml`](/configuration#mise-toml) to share your tool configurations with others. This file should be committed to version control and contains the common toolset needed for your project.
+
+For tools or settings you want to keep private, use [`mise.local.toml`](/configuration#mise-toml). This file should be added to `.gitignore` and is perfect for personal preferences or configurations.
+
+`mise` supports nested configuration files that cascade from broad to specific settings:
+
+1. `~/.config/mise/config.toml` - Global settings for all projects
+2. `~/work/mise.toml` - Work-specific settings
+3. `~/work/project/mise.toml` - Project-specific settings
+4. `~/work/project/mise.local.toml` - Project-specific settings that should not be shared
 
-Note that these files are hierarchical, so you can have a `~/mise.toml` file for global settings, a
-`~/work/mise.toml` file for settings specific to work projects, and `~/work/project/mise.toml` for
-settings specific to a project. mise will use all the parent directories together to determine the
-set of tools—overriding configuration as it goes lower in the hierarchy.
+`mise` will use all the parent directories together to determine the set of tools—overriding configuration as it goes lower in the hierarchy.
 
-In general, it's preferred to use loose versions like this in mise so that other people working
+:::tip
+Use [`mise config ls`](/cli/config/ls) to see the configuration files currently used by `mise`.
+:::
+
+In general, it's preferred to use loose versions like this in `mise` so that other people working
 on a project don't have to worry about the exact version of a tool you're using. If you'd like to
 pin the version to enforce a specific version, use `mise use --pin` or the [`lockfile`](/configuration/settings#lockfile) setting.
 
@@ -51,8 +65,10 @@ If you leave out the version, then mise will default to `node@latest`.
 
 ## Dev Tool Backends
 
-Tools are installed with a variety of backends like asdf, ubi, and vfox. See [registry](/registry.html) for
-the full list of shorthands like `node` you can use. You can also use other backends like `npm` or `cargo`
+Tools are installed with a variety of backends like `asdf`, `ubi`, or `vfox`. See [registry](/registry.html) for
+the full list of shorthands like `node` you can use.
+
+You can also use other backends like `npm` or `cargo`
 which can install any package from their respective registries:
 
 ```bash
@@ -66,11 +82,11 @@ Upgrading tool versions can be done with [`mise upgrade|up`](/cli/upgrade). By d
 the version prefix in `mise.toml`. If [lockfile](/configuration/settings#lockfile) is enabled,
 mise will update `mise.lock` to the latest version of the tool with the prefix from `mise.toml`.
 
-So if you have `node = "22"` in `mise.toml`, then `mise upgrade node` will upgrade to the latest version of node 22.
+So if you have `node = "22"` in `mise.toml`, then `mise upgrade node` will upgrade to the latest version of `node 22`.
 
 If you'd like to upgrade to the latest version of node, you can use `mise upgrade --bump node`. It will set the version
 at the same specificity as the current version, so if you have `node = "22"`, but use `mise upgrade --bump node` to update to
-node@24, then it will set `node = "24"` in `mise.toml`.
+`node@24`, then it will set `node = "24"` in `mise.toml`.
 
 _See [Dev Tools](/dev-tools/) for more information on working with tools._
 
@@ -80,9 +96,9 @@ mise can also be used to set environment variables for your project. You can set
 with the CLI:
 
 ```bash
-$ mise set MY_VAR=123
-$ echo $MY_VAR
-123
+mise set MY_VAR=123
+echo $MY_VAR
+# 123
 ```
 
 Or by directly modifying `mise.toml`:
@@ -99,7 +115,8 @@ Some examples on where this can be used:
 - Setting `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` for AWS
 - Setting `RUST_TEST_THREADS=1` to run cargo tests in series
 
-You can also modify PATH with `mise.toml`—in this example making CLIs installed with npm available:
+You can also modify `PATH` with `mise.toml`.
+This example makes CLIs installed with `npm` available:
 
 ```toml
 [env]