Add section about stray files

firebase.json

@@ -182,6 +182,7 @@
       { "source": "/go/flutter-upper-bound-deprecation", "destination": "https://github.com/flutter/flutter/issues/68143", "type": 301 },
       { "source": "/go/macros", "destination": "/language/macros", "type": 301 },
       { "source": "/go/pub-workspaces", "destination": "/tools/pub/workspaces", "type": 301 },
+      { "source": "/go/workspaces-stray-files", "destination": "/guides/workspaces#stray-files", "type": 301 },
       { "source": "/go/non-promo-conflicting-getter", "destination": "/tools/non-promotion-reasons#getter-name", "type": 301 },
       { "source": "/go/non-promo-conflicting-non-promotable-field", "destination": "/tools/non-promotion-reasons#field-name", "type": 301 },
       { "source": "/go/non-promo-conflicting-noSuchMethod-forwarder", "destination": "/tools/non-promotion-reasons#nosuchmethod", "type": 301 },

src/content/tools/pub/workspaces.md

@@ -107,6 +107,46 @@ To use pub workspaces, all your workspace packages (but not your dependencies)
 must have an SDK version constraint of `^3.6.0` or higher.
 :::
 
+<a name='stray-files'></a>
+## Stray files
+
+When you are migrating an existing mono-repo to use Pub workspaces, there will
+be existing "stray" `pubspec.lock` and `.dart_tool/package_config.json` files
+adjacent to each pubspec. These would shadow the `pubspec.lock` and
+`.dart_tool/package_config.json` placed next to the root
+
+Therefore `pub get` will delete any `pubspec.lock` and
+`.dart_tool/package_config.json` located in directories between the root and
+(including) any workspace package.
+
+```
+/
+  pubspec.yaml                       # Root
+  packages/
+    pubspec.lock                     # Deleted by `pub get`
+    .dart_tool/package_config.json   # Deleted by `pub get`
+    foo/
+      pubspec.yaml                   # Workspace member
+      pubspec.lock                   # Deleted by `pub get`
+      .dart_tool/package_config.json # Deleted by `pub get`
+```
+
+If any directory between the workspace root and a workspace package contains a
+"stray" `pubspec.yaml` file that is not member of the workspace, `pub get` will
+report an error and fail to resolve, as resolving such a `pubspec.yaml` would
+create a `.dart_tool/package_config.json` file that shadows the one at the root.
+
+For example:
+```
+/
+  pubspec.yaml                      # Root `workspace: ['foo/']`
+  packages/
+    pubspec.yaml                    # Not workspace member => error
+    foo/
+      pubspec.yaml                  # Workspace member
+```
+
+
 ## Interdependencies between workspace packages
 
 If any of the workspace packages depend on each other, they will automatically