Document breaking change: dotnet tool install --local creates manifest by default in .NET 10 (#48138)

Author: Copilot

docs/core/compatibility/10.0.md

@@ -109,6 +109,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | [`dotnet new sln` defaults to SLNX file format](sdk/10.0/dotnet-new-sln-slnx-default.md) | Behavioral change | RC 1 |
 | [`dotnet package list` performs restore](sdk/10.0/dotnet-package-list-restore.md) | Behavioral change | Preview 4 |
 | [`dotnet restore` audits transitive packages](sdk/10.0/nugetaudit-transitive-packages.md) | Behavioral change | Preview 3 |
+| [`dotnet tool install --local` creates manifest by default](sdk/10.0/dotnet-tool-install-local-manifest.md) | Behavioral change | Preview 7 |
 | [project.json not supported in `dotnet restore`](sdk/10.0/dotnet-restore-project-json-unsupported.md) | Source incompatible | Preview 7 |
 | [SHA-1 fingerprint support deprecated in `dotnet nuget sign`](sdk/10.0/dotnet-nuget-sign-sha1-deprecated.md) | Behavioral change | Preview 1 |
 | [MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed](sdk/10.0/custom-build-event-warning.md) | Behavioral change | Preview 1 |

docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md

@@ -0,0 +1,46 @@
+---
+title: "Breaking change: 'dotnet tool install --local' creates manifest by default"
+description: "Learn about the breaking change where 'dotnet tool install --local' now creates a manifest by default if no tools manifest is found."
+ms.date: 08/27/2025
+ai-usage: ai-generated
+---
+
+# dotnet tool install --local creates manifest by default
+
+When running [`dotnet tool install --local`](../../../tools/dotnet-tool-install.md), a manifest is now created if none exists instead of failing with an error. This change was implemented by making the [`--create-manifest-if-needed` option](../../../tools/dotnet-tool-install.md#options) enabled by default. This is a breaking change, since users might have relied on the failure behavior to check if they needed to create a manifest.
+
+The `-d` flag on `dotnet tool install` was previously added to show the locations that were searched for manifests. This information was relayed in the error given when there was no manifest. That error is no longer shown since a manifest is now created if necessary. You should no longer use the `-d` flag.
+
+## Version introduced
+
+.NET 10 Preview 7
+
+## Previous behavior
+
+Previously, if you tried to install a .NET tool as a local tool in a folder that didn't contain a manifest, you got an error:
+
+> Cannot find a manifest file.
+
+## New behavior
+
+Starting in .NET 10, the `--create-manifest-if-needed=true` functionality is now enabled by default. When a tool is installed as a local tool, the manifest is created automatically if it doesn't exist. The manifest is created according to the rules described in the [`--create-manifest-if-needed` option](../../../tools/dotnet-tool-install.md#options) documentation.
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+This change improves the user experience by making `dotnet tool install --local` work by default without requiring users to manually create a manifest first. Previously, there was a concern about creating a manifest in a working directory rather than the repository root, but the tool now puts the manifest in the repository root when possible.
+
+## Recommended action
+
+You can turn off the automatic manifest creation behavior by passing `--create-manifest-if-needed=false` when calling `dotnet tool install --local`.
+
+## Affected APIs
+
+N/A
+
+## See also
+
+- [dotnet tool install](../../../tools/dotnet-tool-install.md)

docs/core/compatibility/toc.yml

@@ -124,6 +124,8 @@ items:
                 href: sdk/10.0/dotnet-new-sln-slnx-default.md
               - name: "`dotnet package list` performs restore"
                 href: sdk/10.0/dotnet-package-list-restore.md
+              - name: "`dotnet tool install --local` creates manifest by default"
+                href: sdk/10.0/dotnet-tool-install-local-manifest.md
               - name: MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed
                 href: sdk/10.0/custom-build-event-warning.md
               - name: MSBuild custom culture resource handling

docs/core/tools/dotnet-tool-install.md

@@ -1,7 +1,7 @@
 ---
 title: dotnet tool install command
 description: The dotnet tool install command installs the specified .NET tool on your machine.
-ms.date: 04/07/2025
+ms.date: 08/27/2025
 ---
 # dotnet tool install
 
@@ -46,9 +46,9 @@ dotnet tool install -h|--help
 
 The `dotnet tool install` command provides a way for you to install .NET tools on your machine. To use the command, you specify one of the following installation options:
 
-* To install a global tool in the default location, use the `--global` option.
-* To install a global tool in a custom location,  use the `--tool-path` option.
-* To install a local tool, omit the `--global` and `--tool-path` options.
+- To install a global tool in the default location, use the `--global` option.
+- To install a global tool in a custom location,  use the `--tool-path` option.
+- To install a local tool, omit the `--global` and `--tool-path` options.
 
 > [!WARNING]
 > Make sure the directory you specify with the `--tool-path` option is secure. Tools installed in this location can be executed directly, so using an untrusted or shared path might introduce security risks.
@@ -80,7 +80,7 @@ Tools with explicit tool paths are stored wherever you specified the `--tool-pat
 
 Local tools are stored in the NuGet global directory, whatever you've set that to be. There are shim files in `$HOME/.dotnet/toolResolverCache` for each local tool that point to where the tools are within that location.
 
-References to local tools are added to a *dotnet-tools.json* file in a *.config* directory under the current directory. If a manifest file doesn't exist yet, create it by using the `--create-manifest-if-needed` option or by running the following command:
+References to local tools are added to a *dotnet-tools.json* file in a *.config* directory under the current directory. Starting in .NET 10, if a manifest file doesn't exist yet, one is created automatically. You can also create one manually by running the following command:
 
 ```dotnetcli
 dotnet new tool-manifest
@@ -112,19 +112,21 @@ For more information, see [Install a local tool](global-tools.md#install-a-local
 
 - **`--create-manifest-if-needed`**
 
-  Applies to local tools. Available starting with .NET 8 SDK. To find a manifest, the search algorithm searches up the directory tree for `dotnet-tools.json` or a `.config` folder that contains a `dotnet-tools.json` file.
+  Available starting in .NET 8 SDK.
 
-  If a tool-manifest can't be found and the `--create-manifest-if-needed` option is set to false, the `CannotFindAManifestFile` error occurs.
+  Applies to local tools. To find a manifest, the search algorithm searches up the directory tree for `dotnet-tools.json` or a `.config` folder that contains a `dotnet-tools.json` file.
 
-  If a tool-manifest can't be found and the `--create-manifest-if-needed` option is set to true, the tool creates a manifest automatically. It chooses a folder for the manifest as follows:
+  If a tool-manifest can't be found and the `--create-manifest-if-needed` option is set to `false`, the `CannotFindAManifestFile` error occurs.
 
-  * Walk up the directory tree searching for a directory that has a `.git` subfolder. If one is found, create the manifest in that directory.
-  * If the previous step doesn't find a directory, walk up the directory tree searching for a directory that has a `.sln` or `.git` file. If one is found, create the manifest in that directory.
-  * If neither of the previous two steps finds a directory, create the manifest in the current working directory.
+  If a tool-manifest can't be found and the `--create-manifest-if-needed` option is set to `true` (or, in .NET 10 and later versions, when not specified), the tool creates a manifest automatically. It chooses a folder for the manifest as follows:
+
+  - Walk up the directory tree searching for a directory that has a `.git` subfolder. If one is found, create the manifest in that directory.
+  - If the previous step doesn't find a directory, walk up the directory tree searching for a directory that has a `.sln` or `.git` file. If one is found, create the manifest in that directory.
+  - If neither of the previous two steps finds a directory, create the manifest in the current working directory.
 
   For more information on how manifests are located, see [Install a local tool](global-tools.md#install-a-local-tool).
 
-  Starting in .NET 10, this flag is applied automatically if no tools manifest is found.
+  Starting in .NET 10, a manifest is created automatically if no tools manifest is found. This change can be a [breaking change](../compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md). You can opt out by passing `--create-manifest-if-needed=false`.
 
   > [!WARNING]
   > Don't run tool commands from the **Downloads** folder or any shared location. The CLI walks up the directory tree to find a tool manifest, which might cause it to use a manifest you don't expect. Always run tool commands from a trusted, project-specific directory.