docs: update/fix dfxvm docs

docs/cli-reference/dfx/dfx.mdx

@@ -1,82 +1,67 @@
 import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
 
-# dfx
+# Determining `dfx` version
 
 <MarkdownChipRow labels={["Reference"]} />
 
+When invoked as `dfx`, `dfxvm` determines which version of `dfx` to use for execution by checking these criteria in order:
 
-When invoked as `dfx`, `dfxvm` determines which version of dfx to use
-and dispatches execution to it.
+1. `+<version>` parameter from command line.
+2. `DFX_VERSION` environment variable.
+3. `dfx` setting in the current project's `dfx.json`.
+4. `default_version` in `$HOME/.config/dfx/version-manager.json`.
 
-## dfx version determination
+#### 1. Command line
 
-`dfxvm` determines which version of dfx to use by checking these criteria
-in order:
-
-1. `+<version>` parameter from command line
-2. `DFX_VERSION` environment variable
-3. `dfx` in the current project's `dfx.json`
-4. `default_version` in `$HOME/.config/dfx/version-manager.json`
-
-### Command Line
-
-You can specify the version of dfx to use on the command line by passing
-`+<version>` as the first parameter. For example, the following will deploy
-using dfx 0.15.0:
+You can specify the version of `dfx` on the command line by passing `+<version>` as the first parameter. For example, the following will deploy using `dfx v0.26.0`:
 
 ```bash
-dfx +0.15.0 deploy
+dfx +0.26.0 deploy
 ```
 
-### DFX_VERSION environment variable
+#### 2. `DFX_VERSION` environment variable
 
-You can specify the version of dfx to use by setting the `DFX_VERSION`
-environment variable.  For example, the following will start the replica using
-dfx 0.15.0:
+You can specify the version of `dfx` by setting the `DFX_VERSION` environment variable. For example, the following will start the local developer environment using `dfx v0.26.0`:
 
 ```bash
-DFX_VERSION=0.15.0 dfx start --clean --background
+DFX_VERSION=0.26.0 dfx start --clean --background
 ```
 
-### dfx field in the current project's dfx.json
+#### 3. `dfx` field in the current project's `dfx.json`
 
-If running dfxvm as dfx in a dfx project, and the project's dfx.json contains a
-top-level field "dfx", then dfxvm will use the version specified in that field.
+A project's `dfx.json` file can contain a top-level field "dfx". If specified, then `dfxvm` will use that version.
 
-Like dfx, dfxvm looks for dfx.json in the current directory and then in
-parent directories until it finds one or reaches the root directory.
+Like `dfx`, `dfxvm` looks for `dfx.json` in the current directory and then in parent directories until it finds one or reaches the root directory.
 
 For example:
 
 ```json
 {
-  "dfx": "0.14.4",
+  "dfx": "0.26.1",
   "canisters": {  }
 }
 ```
 
-If the above dfx.json were in the current directory or any parent directory,
-then any dfx command would use dfx 0.14.4.
+If the above `dfx.json` were in the current directory or any parent directory, then any `dfx` command would use `dfx v0.26.1`.
 
-### default_version in $HOME/.config/dfx/version-manager.json
+#### 4. `default_version` in `$HOME/.config/dfx/version-manager.json`
 
-If none of the above criteria are met, then dfxvm will use the version specified
-in `$HOME/.config/dfx/version-manager.json`. For example:
+If none of the above criteria are met, then `dfxvm` will use the version specified in `$HOME/.config/dfx/version-manager.json`. For example:
 
 ```json
 {
-  "default_version": "0.15.0"
+  "default_version": "0.26.0"
 }
 ```
 
 To configure the default dfx version, use the `dfxvm default` command:
 
 ```bash
-dfxvm default 0.15.1
+dfxvm default 0.26.1
 ```
 
-## Environment Variables
+## Environment variables
 
-When proxying to dfx, dfxvm alters the environment in two ways:
-- Sets `DFX_VERSION` to the version of dfx being used.
-- Prepends the bin directory for the dfx version to `PATH`.
+When proxying to `dfx`, `dfxvm` alters the environment in two ways:
+- Sets `DFX_VERSION` to the version of `dfx` being used.
+- Prepends the `bin` directory for the `dfx` version to `PATH`.

docs/cli-reference/dfxvm-init/dfxvm-init.mdx

@@ -6,10 +6,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
 
 When invoked as `dfxvm-init`, `dfxvm` performs one-time installation tasks.
 
-By default, installs the latest version of dfx, and gives you an opportunity
-to customize the installation.
-
-## Usage
+By default, installs the latest version of dfx, and gives you an opportunity to customize the installation.
 
 ```bash
 dfxvm-init [--dfx-version <version>] [--yes]
@@ -25,19 +22,17 @@ dfxvm-init [--dfx-version <version>] [--yes]
 
 ## Examples
 
-Install dfxvm and the latest version of dfx, with an opportunity
-to customize the installation
-
 ```bash
 dfxvm-init
 ```
 
-Install dfxvm and dfx 0.14.4, with an opportunity to customize the installation
+Install `dfxvm` and `dfx 0.14.4`, with an opportunity to customize the installation:
+
 ```bash
 dfxvm-init --dfx-version 0.14.4
 ```
 
-Install dfxvm and the latest version of dfx without prompting for confirmation
+Install `dfxvm` and the latest version of `dfx` without prompting for confirmation:
 
 ```bash
 dfxvm-init --yes

docs/cli-reference/dfxvm/dfxvm-default.mdx

@@ -1,19 +1,22 @@
+import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
+
 # dfxvm default
 
-Sets or displays the dfx version to use by default.
+<MarkdownChipRow labels={["Reference"]} />
+
+Sets or displays the `dfx` version that should be used by default.
 
-When setting the default version, installs the specified version
-if it is not already installed.
+When setting the default version, `dfxvm default` installs the specified version if it is not already installed.
 
 ## Usage
 
-Set the dfx version to use by default:
+Set the `dfx` version to be used by default:
 
 ```bash
 dfxvm default <version>
 ```
 
-Display the default dfx version:
+Display the currently configured default `dfx` version:
 
 ```bash
 dfxvm default

docs/cli-reference/dfxvm/dfxvm-install.mdx

@@ -4,9 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
 
 <MarkdownChipRow labels={["Reference"]} />
 
-Installs a version of dfx.
-
-## Usage
+Installs a version of `dfx`. Can be used for official release versions and beta releases.
 
 ```bash
 dfxvm install <version>

docs/cli-reference/dfxvm/dfxvm-list.mdx

@@ -4,9 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
 
 <MarkdownChipRow labels={["Reference"]} />
 
-List installed or available versions of dfx.
-
-## Usage
+List the currently installed or available versions of `dfx`.
 
 ```bash
 dfxvm list [OPTIONS]

docs/cli-reference/dfxvm/dfxvm-self-uninstall.mdx

@@ -4,9 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
 
 <MarkdownChipRow labels={["Reference"]} />
 
-Uninstalls dfxvm and all versions of dfx.
-
-## Usage
+Uninstalls `dfxvm` and all versions of `dfx` with the opportunity to confirm or cancel.
 
 ```bash
 dfxvm self uninstall [--yes]
@@ -20,8 +18,6 @@ dfxvm self uninstall [--yes]
 
 ## Examples
 
-Uninstall dfxvm and all versions of dfx, with an opportunity to confirm or cancel.
-
 ```bash
 dfxvm self uninstall
 ```

docs/cli-reference/dfxvm/dfxvm-self-update.mdx

@@ -4,9 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
 
 <MarkdownChipRow labels={["Reference"]} />
 
-Updates to the newest version of dfxvm.
-
-## Usage
+Updates to the newest version of `dfxvm`. Does not update to the latest version of `dfx`.
 
 ```bash
 dfxvm self update

docs/cli-reference/dfxvm/dfxvm-uninstall.mdx

@@ -4,17 +4,13 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
 
 <MarkdownChipRow labels={["Reference"]} />
 
-Uninstalls a version of dfx.
-
-## Usage
+Uninstalls a specific version of `dfx`. Does not uninstall `dfxvm` itself.
 
 ```bash
 dfxvm uninstall <version>
 ```
 
-## Examples
-
-Uninstall a beta that you don't want anymore:
+## Example
 
 ```bash
 dfxvm uninstall 0.15.1-beta.0

docs/cli-reference/dfxvm/dfxvm-update.mdx

@@ -4,10 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
 
 <MarkdownChipRow labels={["Reference"]} />
 
-Looks up the latest dfx version, installs it if not already installed, and
-sets it as the default version.
-
-## Usage
+Looks up the latest `dfx` version, installs it if not already installed, then sets it as the default version.
 
 ```bash
 dfxvm update

docs/cli-reference/dfxvm/dfxvm.mdx

@@ -4,4 +4,44 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
 
 <MarkdownChipRow labels={["Reference"]} />
 
-When invoked as `dfxvm`, manages dfx versions or itself.
+`dfxvm` is the version manager for the command-line tool `dfx`. 
+
+When invoked as `dfxvm`, manages `dfx` versions or itself.
+
+To set the default `dfx` version, use the `dfxvm default` command:
+
+```
+dfxvm default 0.25.1
+```
+
+Or, to set the `dfx` version for a single command:
+
+```
+dfx +0.25.1 --version
+```
+
+The `dfx` version can be set manually in a project's `dfx.json` file:
+
+```json
+{
+  "dfx": "0.25.0"
+}
+```
+
+## Subcommands
+
+Available subcommands are:
+
+- `dfxvm default`
+
+- `dfxvm install`
+
+- `dfxvm list`
+
+- `dfxvm self uninstall`
+
+- `dfxvm self update`
+
+- `dfxvm uninstall`
+
+- `dfxvm update`

docs/cli-reference/index.mdz → docs/cli-reference/index.md

@@ -1,9 +1,5 @@
-import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
-
 # Command-line reference
 
-<MarkdownChipRow labels={["Reference"]} />
-
 The dfxvm binary is a chimera, changing its behavior based on
 the name of the binary.