docs: explain auto-generated .mermaid files (#1506) (#1579)

Author: radu-mocanu

packages/uipath/docs/cli/index.md

@@ -82,6 +82,12 @@ Running `uipath init` will process these function definitions and create the cor
 ✓  Created '.uipath/studio_metadata.json' file.
 ✓  Created: CLAUDE.md, CLI_REFERENCE.md, SDK_REFERENCE.md, AGENTS.md, REQUIRED_STRUCTURE.md.
 ```
+
+/// info
+### About the `.mermaid` files
+
+`uipath init` generates one `<entrypoint>.mermaid` file per function/agent containing a static call graph, rendered in the UiPath Orchestrator UI. These files are regenerated on every `uipath init`.
+///
 ---
 
 ::: mkdocs-click

packages/uipath/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath"
-version = "2.10.49"
+version = "2.10.50"
 description = "Python SDK and CLI for UiPath Platform, enabling programmatic interaction with automation services, process management, and deployment tools."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

packages/uipath/src/uipath/_cli/cli_init.py

@@ -277,6 +277,12 @@ def write_studio_metadata_file(directory: str) -> None:
     )
 
 
+MERMAID_FILE_HEADER = (
+    "%% AUTO-GENERATED by `uipath init`. Do not edit manually.\n"
+    "%% Regenerated on every `uipath init`.\n"
+)
+
+
 def write_mermaid_files(entry_points: list[UiPathRuntimeSchema]) -> list[Path]:
     """Write mermaid diagram files for each entrypoint.
 
@@ -299,6 +305,7 @@ def write_mermaid_files(entry_points: list[UiPathRuntimeSchema]) -> list[Path]:
         mermaid_file_path = Path(os.getcwd()) / f"{ep.file_path}.mermaid"
 
         with open(mermaid_file_path, "w") as f:
+            f.write(MERMAID_FILE_HEADER)
             f.write(str(chart))
 
         mermaid_paths.append(mermaid_file_path)

packages/uipath/tests/cli/test_init.py

@@ -659,3 +659,29 @@ def test_init_does_not_overwrite_existing_studio_metadata(
                 metadata = json.load(f)
                 assert metadata["schemaVersion"] == 99
                 assert metadata["codeVersion"] == "5.0.0"
+
+
+class TestWriteMermaidFiles:
+    def test_mermaid_file_starts_with_header_comment(
+        self, runner: CliRunner, temp_dir: str
+    ) -> None:
+        """Generated .mermaid files begin with the clarifying header comment."""
+        from uipath._cli.cli_init import MERMAID_FILE_HEADER, write_mermaid_files
+        from uipath.runtime.schema import UiPathRuntimeGraph, UiPathRuntimeSchema
+
+        ep = UiPathRuntimeSchema(
+            filePath="main.py",
+            uniqueId="main",
+            type="function",
+            input={},
+            output={},
+            graph=UiPathRuntimeGraph(),
+        )
+
+        with runner.isolated_filesystem(temp_dir=temp_dir):
+            paths = write_mermaid_files([ep])
+            assert len(paths) == 1
+            contents = paths[0].read_text()
+            assert contents.startswith(MERMAID_FILE_HEADER)
+            assert "AUTO-GENERATED" in contents
+            assert "uipath init" in contents