docs: Clarify auto-configuration settings documentation.

Author: hverlin

README.md

@@ -42,17 +42,19 @@ The extension will notify you if neither is installed.
 
 ## Important Defaults
 
-> [!NOTE]
-> The extension includes default settings that you might want to change. See the [configuration guide](https://hverlin.github.io/mise-vscode/tutorials/settinguptheextension/) to customize your set-up.
-> For example, you can choose to enable/disable automatic configuration of other extensions or change the path to the `mise` binary.
->
-> You can access the settings by clicking on the mise extension indicator in the status bar.
+The extension includes default settings that you might want to change. See the [configuration guide](https://hverlin.github.io/mise-vscode/tutorials/settinguptheextension/) to customize your set-up.
+
+For example, you can choose to enable/disable automatic configuration of other extensions or change the path to the `mise` binary.
+
+You can access the settings by clicking on the mise extension indicator in the status bar.
+
+### Enabling/Disabling Auto-Configuration
 
-### Recommended: Disable Global Tools in Auto-Configuration
+By default, the extension will not automatically configure other VS Code extensions to use tools provided by `mise` in your current project.
 
-By default, the extension includes tools from your global mise configuration (`~/.config/mise/config.toml`) when auto-configuring other VS Code extensions. This can pollute your project settings with extensions for tools not in your current project.
+To enable auto-configuration, set [`mise.configureExtensionsAutomatically`](https://hverlin.github.io/mise-vscode/reference/settings/#miseconfigureextensionsautomatically) to `true`. This will automatically configure other VS Code extensions to use tools provided by `mise` in your current project.
 
-**Recommended setting:** Set `mise.configureExtensionsIncludeGlobalTools` to `false` to only use tools from your local `mise.toml` file. This keeps your `.vscode/settings.json` clean and ensures extensions are only configured for tools actually used in your project.
+**Important:** By default, tools from your global mise configuration (`~/.config/mise/config.toml`) are included when auto-configuring other VS Code extensions ([`mise.configureExtensionsIncludeGlobalTools`](https://hverlin.github.io/mise-vscode/reference/settings/#miseconfigureextensionsincludeglobaltools) is `true` for backward compatibility). You can set it to `false` to keep your `.vscode/settings.json` clean and ensure extensions are only configured for tools actually used in your project.
 
 ## ✨ Features
 

docs/src/content/docs/guides/custom-extensions.mdx

@@ -0,0 +1,42 @@
+---
+title: Custom Extensions
+description: How to configure any VS Code extension to use mise tools
+sidebar:
+    order: 300
+---
+
+You can configure any VS Code extension to use mise tools via settings:
+
+- **`mise.customBinaryExtensions`**: Configure extensions that need a binary path
+- **`mise.customFolderExtensions`**: Configure extensions that need a folder path (e.g., JDK home)
+
+Example for binary mode:
+
+```json
+{
+  "mise.customBinaryExtensions": [
+    {
+      "extensionId": "example.my-extension",
+      "toolSources": ["aqua:mytool"],
+      "vscodeSetting": { "key": "myExtension.toolPath" }
+    }
+  ]
+}
+```
+
+Example for folder mode:
+
+```json
+{
+  "mise.customFolderExtensions": [
+    {
+      "extensionId": "example.java-extension",
+      "toolSources": ["jfox:java", "asdf:openjdk"],
+      "vscodeSetting": { "key": "java.jdkHome" },
+      "folderName": "custom-jdk"
+    }
+  ]
+}
+```
+
+See the [Extension Settings](/mise-vscode/reference/settings/) for full configuration options.

docs/src/content/docs/reference/Supported-extensions.md

@@ -46,41 +46,7 @@ Extensions which have built-in support for `mise`:
 
 ## Custom Extensions
 
-You can configure any VSCode extension to use mise tools via settings:
-
-- **`mise.customBinaryExtensions`**: Configure extensions that need a binary path
-- **`mise.customFolderExtensions`**: Configure extensions that need a folder path (e.g., JDK home)
-
-Example for binary mode:
-
-```json
-{
-  "mise.customBinaryExtensions": [
-    {
-      "extensionId": "example.my-extension",
-      "toolSources": ["aqua:mytool"],
-      "vscodeSetting": { "key": "myExtension.toolPath" }
-    }
-  ]
-}
-```
-
-Example for folder mode:
-
-```json
-{
-  "mise.customFolderExtensions": [
-    {
-      "extensionId": "example.java-extension",
-      "toolSources": ["jfox:java", "asdf:openjdk"],
-      "vscodeSetting": { "key": "java.jdkHome" },
-      "folderName": "custom-jdk"
-    }
-  ]
-}
-```
-
-See the Extension Settings for full configuration options.
+If the extension you're using is not listed above, you can still configure it manually. See the [Custom Extensions Guide](/mise-vscode/guides/custom-extensions/) for more details.
 
 Extensions that are not supported:
 - [Rust](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) does not offer to update the cargo path automatically. See [this discussion](https://github.com/hverlin/mise-vscode/discussions/70) for workarounds. 

docs/src/content/docs/tutorials/SettingUpTheExtension.mdx

@@ -24,6 +24,8 @@ By default, this extension **will not** automatically modify your `.vscode/setti
 
 You can [enable automatic configuration](/mise-vscode/reference/settings/#miseconfigureextensionsautomatically) so that [other extensions](/mise-vscode/reference/supported-extensions/) you use will automatically use the tools you installed with `mise`.
 
+By default, [`mise.configureExtensionsIncludeGlobalTools`](/mise-vscode/reference/settings/#miseconfigureextensionsincludeglobaltools) is `true`, meaning tools from your global mise configuration (`~/.config/mise/config.toml`) are also included. You can set it to `false` if you only want to use tools from the local project configuration.
+
 **If you enable this feature and are sharing the `.vscode/settings.json` file with others** (e.g., in a Git repository), you may want to configure the extension to create symlinks to tools so that the settings point to a relative path in your project. Use [`mise.configureExtensionsUseSymLinks`](/mise-vscode/reference/settings/#miseconfigureextensionsusesymlinks) for this. Note that I consider that sharing the `.vscode/settings.json` file is not a good idea in general (see details below).
 
 <details>

walkthrough/auto-configure.md

@@ -12,8 +12,8 @@ One of the main features of this extension is the ability to **automatically con
 When enabled, the extension will automatically update your `.vscode/settings.json` file to configure supported VSCode extensions.
 See [the list of supported extensions](https://github.com/hverlin/mise-vscode/wiki/Supported-extensions).
 
-> [!IMPORTANT]
-> **Recommended:** Set `mise.configureExtensionsIncludeGlobalTools` to `false` to only use tools from your local `mise.toml` file. This prevents your project settings from being polluted with extensions for tools not in your current project.
+> [!NOTE]
+> By default, `mise.configureExtensionsIncludeGlobalTools` is set to `true` (for backward compatibility), meaning tools from your global configuration (`~/.config/mise/config.toml`) are also included. You can set it to `false` to only use tools from your local `mise.toml` file.
 
 To enable this feature, simply click this button:
 **[Enable Auto-Configuration](command:mise.enableAutoConfiguration)**