diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx
index e969855382..e664620079 100644
--- a/src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx
+++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx
@@ -107,7 +107,7 @@ The following options are available:
- **`--isolated`**
- Run in isolated mode with randomized ports and isolated user secrets, allowing multiple instances of the same AppHost to run simultaneously. This is useful for parallel testing or comparing different configurations side-by-side.
+ Run in isolated mode with randomized ports and isolated user secrets, allowing multiple instances of the same AppHost to run simultaneously. Isolated runs don't use persisted generated ports unless `portAllocation.persistInIsolatedMode` is `true`. Pass `--isolated false` to turn isolation off, including in linked Git worktrees when `features.gitWorktreeIsolationEnabled` is enabled. This is useful for parallel testing or comparing different configurations side-by-side.
- **`--no-build`**
diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx
index 0fcf36f806..7e06ea8c08 100644
--- a/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx
+++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx
@@ -105,7 +105,7 @@ The following options are available:
- **`--isolated`**
- Run in isolated mode with randomized ports and isolated user secrets, allowing multiple instances of the same AppHost to run simultaneously.
+ Run in isolated mode with randomized ports and isolated user secrets, allowing multiple instances of the same AppHost to run simultaneously. Isolated runs don't use persisted generated ports unless `portAllocation.persistInIsolatedMode` is `true`. Pass `--isolated false` to turn isolation off, including in linked Git worktrees when `features.gitWorktreeIsolationEnabled` is enabled.
-
diff --git a/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md b/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md
index 37e54486ef..5a6ef649bd 100644
--- a/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md
+++ b/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md
@@ -15,6 +15,7 @@ title: Config Settings Table
| `features.experimentalPolyglot:java` | `false` | Enable or disable experimental Java AppHost support. |
| `features.experimentalPolyglot:python` | `false` | Enable or disable experimental Python AppHost support. |
| `features.experimentalPolyglot:rust` | `false` | Enable or disable experimental Rust AppHost support. |
+| `features.gitWorktreeIsolationEnabled` | `false` | Enable or disable automatic isolated mode for AppHosts in linked Git worktrees. An explicit `--isolated true` or `--isolated false` always takes precedence. |
| `features.nugetSignatureVerificationEnabled` | `true` | Enable or disable defaulting the `DOTNET_NUGET_SIGNATURE_VERIFICATION` environment variable for NuGet operations. When enabled on Linux, the CLI sets the variable to `true` unless you've set it to `false`. |
| `features.polyglotIntegrationFilterEnabled` | `false` | Enable or disable an experimental filter that restricts `aspire add`, `aspire integration list`, and `aspire integration search` in non-C# AppHosts to integrations with the `polyglot` NuGet tag. The filter fails closed, so enabling it against a remote feed hides every integration. Azure DevOps Artifacts feeds ignore `tags:` query scoping, and nuget.org returns no first-party integrations for the tag. Enable it only against a local package source or hive, where the CLI reads the tag from the package's `.nuspec` file. |
| `features.showAllTemplates` | `false` | Show all available templates, including experimental ones, in `aspire new` and `aspire init`. |
@@ -23,6 +24,7 @@ title: Config Settings Table
| `features.updateNotificationsEnabled` | `true` | Enable or disable Aspire CLI update notifications. |
| `overrideStagingFeed` | — | Feed URL for the `staging` channel. Any non-empty value lets every CLI build resolve the `staging` channel, and a valid `http` or `https` URL replaces the default staging feed. To set it, run `aspire config set -g overrideStagingFeed `. Without this setting or `features.stagingChannelEnabled`, `--channel staging` only resolves on `stable` or `staging` Aspire CLI builds. Daily, local, and per-PR builds refuse it and report the recovery options. This key isn't part of the published JSON Schema, so schema-aware editors flag it as an unknown property. |
| `packages.` | — | Version of a hosting integration package for a non-C# AppHost, keyed by package ID. A value that ends in `.csproj` is treated as a project reference. `aspire add` adds entries, and `aspire update` updates their versions. For more information, see [Add and restore integrations](/app-host/typescript-apphost/#add-and-restore-integrations). |
+| `portAllocation.persistInIsolatedMode` | `false` | Persist generated public ports in isolated mode. By default, isolated runs skip persisted port allocations. When `true`, each AppHost and worktree identity keeps stable generated ports across restarts. The AppHost stores persisted ports in `.aspire/state` next to the AppHost. |
| `profiles..applicationUrl` | — | Application URLs for the launch profile, such as `https://localhost:17000;http://localhost:15000`. To learn where each kind of AppHost stores launch profiles, see [AppHost configuration](/app-host/configuration/). |
| `profiles..environmentVariables` | — | Environment variables for the launch profile. |
| `sdk.version` | Installed CLI version | Aspire SDK version for a non-C# AppHost, which determines the version of the `Aspire.Hosting` packages to use. `aspire update` updates this value. |