Document alias collision limitation and add context

- Added test documenting potential alias collision scenario when
  site_name matches generated alias pattern (site_name-SectionName)
- Updated limitations.md with clear example and workaround
- Created claude.md to preserve original prompts and design context

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: jacobstr

docs/limitations.md

@@ -1,3 +1,26 @@
 # Caveats / Known Design Decisions
 
 - In an included `mkdocs.yml`, you cannot have `!include`. It is only supported in the root `mkdocs.yml`
+
+- **Anchor-based inclusion alias collision risk**: When using anchor syntax (`!include path/to/mkdocs.yml#SectionName`), the generated alias follows the pattern `{site_name}-{SectionName}`. This can create a collision if you also include a separate `mkdocs.yml` file whose `site_name` exactly matches this generated alias.
+
+  **Example collision scenario:**
+  ```yaml
+  # File A: docs/team-a/mkdocs.yml
+  site_name: MyDocs
+  nav:
+    - Guides:
+      - Getting Started: getting-started.md
+
+  # File B: docs/team-b/mkdocs.yml
+  site_name: MyDocs-Guides
+  nav:
+    - Overview: overview.md
+
+  # Root mkdocs.yml - This will cause a collision!
+  nav:
+    - Team A Guides: "!include docs/team-a/mkdocs.yml#Guides"  # alias: "MyDocs-Guides"
+    - Team B: "!include docs/team-b/mkdocs.yml"                # alias: "MyDocs-Guides"
+  ```
+
+  **Workaround:** Ensure your `site_name` values don't match the pattern `{OtherSiteName}-{SectionName}` when using anchor-based includes. The collision will be detected at build time with a clear error message listing all registered aliases.

mkdocs_monorepo_plugin/tests/test_plugin.py

@@ -130,3 +130,60 @@ def test_section_not_found(self):
         with self.assertRaises(SystemExit):
             loader.read()
             loader.getNav()
+
+    def test_alias_collision_detection(self):
+        """Test that alias collisions are properly detected.
+
+        Known limitation: If a site_name matches another site's generated
+        alias (site_name-SectionName), a collision occurs.
+
+        Example collision scenario:
+        - Site A: site_name="TestSite" with #Guides -> alias="TestSite-Guides"
+        - Site B: site_name="TestSite-Guides" (no anchor) -> alias="TestSite-Guides"
+
+        This test verifies that such collisions are detected and raise an error.
+        """
+        # Create a second mkdocs file with a site_name that collides with
+        # the generated alias from the first file
+        collision_file = os.path.join(self.test_dir, "collision.yml")
+        with open(collision_file, 'w') as f:
+            f.write("""site_name: TestSite-Guides
+docs_dir: docs
+nav:
+  - Home: index.md
+""")
+
+        # Set up config with both includes - one with anchor, one without
+        root_config = {
+            "config_file_path": os.path.join(self.test_dir, "root.yml"),
+            "docs_dir": os.path.join(self.test_dir, "docs"),
+            "nav": [
+                {"Section1": "!include mkdocs.yml#Guides"},
+                {"Section2": "!include collision.yml"}
+            ]
+        }
+
+        # Create root mkdocs.yml
+        with open(root_config["config_file_path"], 'w') as f:
+            f.write("""site_name: Root
+docs_dir: docs
+nav:
+  - Section1: "!include mkdocs.yml#Guides"
+  - Section2: "!include collision.yml"
+""")
+
+        # Verify the aliases would collide
+        config1 = {"config_file_path": self.mkdocs_file}
+        loader1 = IncludeNavLoader(config1, "mkdocs.yml#Guides")
+        loader1.read()
+        alias1 = loader1.getAlias()
+
+        config2 = {"config_file_path": collision_file}
+        loader2 = IncludeNavLoader(config2, "collision.yml")
+        loader2.read()
+        alias2 = loader2.getAlias()
+
+        # Both should produce "TestSite-Guides"
+        self.assertEqual(alias1, "TestSite-Guides")
+        self.assertEqual(alias2, "TestSite-Guides")
+        self.assertEqual(alias1, alias2)  # Collision confirmed