docs(add-setup-md): add SETUP.md for Agentic Inner Loop KPI

Author: giuliastf

SETUP.MD

@@ -0,0 +1,110 @@
+# SETUP.md
+
+## Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) 0.5+
+
+### Supported platforms
+
+- [x] Linux
+- [ ] Windows
+- [ ] macOS
+
+## Environment Variables
+
+### Standard (injected by pipeline)
+
+None of the standard pipeline variables are required for environment setup, build, or unit tests.
+
+### Project-specific
+
+| Variable | Description | How to obtain |
+|----------|-------------|---------------|
+| `UIPATH_URL` | UiPath platform base URL — required only for E2E tests, which are excluded from the default test run | Set to your tenant URL (e.g. `https://cloud.uipath.com/myorg/mytenant`) |
+| `UIPATH_ACCESS_TOKEN` | Bearer token — required only for E2E tests | Generate from UiPath Cloud Platform |
+
+## Setup
+
+```bash
+# Install uv if not present
+curl -LsSf https://astral.sh/uv/install.sh | sh
+export PATH="$HOME/.local/bin:$PATH"
+
+# Sync all three packages with dev dependencies (dependency order: core → platform → main)
+uv --directory packages/uipath-core sync --all-extras
+uv --directory packages/uipath-platform sync --all-extras
+uv --directory packages/uipath sync --all-extras
+```
+
+## Verify Setup
+
+```bash
+python3 --version
+uv --version
+uv --directory packages/uipath-core run python -c "import uipath.core; print('uipath-core ok')"
+uv --directory packages/uipath-platform run python -c "import uipath.platform; print('uipath-platform ok')"
+uv --directory packages/uipath run python -c "import uipath; print('uipath ok')"
+```
+
+## Build
+
+```bash
+uv --directory packages/uipath-core build
+uv --directory packages/uipath-platform build
+uv --directory packages/uipath build
+```
+
+## Test
+
+```bash
+uv --directory packages/uipath-core run pytest -m "not e2e"
+uv --directory packages/uipath-platform run pytest -m "not e2e"
+uv --directory packages/uipath run pytest -m "not e2e"
+```
+
+## Sample Code Change
+
+### The change
+
+Add a new `size` property to `SpanRegistry` in `packages/uipath-core/src/uipath/core/tracing/span_utils.py`, immediately after the `clear` method (around line 130) and before the `# Global span registry instance` comment:
+
+```python
+@property
+def size(self) -> int:
+    """Return the number of currently registered spans."""
+    return len(self._spans)
+```
+
+Then create `packages/uipath-core/tests/tracing/test_span_registry_size.py` with two pytest tests:
+
+```python
+from unittest.mock import MagicMock
+
+from uipath.core.tracing.span_utils import SpanRegistry
+
+
+def _make_span(span_id: int) -> MagicMock:
+    span = MagicMock()
+    span.get_span_context.return_value.span_id = span_id
+    del span.parent  # ensure hasattr(span, "parent") is False
+    return span
+
+
+def test_size_empty_registry() -> None:
+    registry = SpanRegistry()
+    assert registry.size == 0
+
+
+def test_size_after_registrations() -> None:
+    registry = SpanRegistry()
+    registry.register_span(_make_span(1))
+    registry.register_span(_make_span(2))
+    assert registry.size == 2
+```
+
+### Verification
+
+```bash
+uv --directory packages/uipath-core run pytest tests/tracing/test_span_registry_size.py -v
+```