From 6d34588a8ca16b97320a66e444c2b3396c52bb0c Mon Sep 17 00:00:00 2001
From: ridhima-splunk <rsatam@splunk.com>
Date: Mon, 31 Aug 2026 13:19:13 -0700
Subject: [PATCH] HYBIM-841 Updated migration tool README

---
 splunk-ao-migration-tool/README.md            | 72 +++++++++++--------
 .../splunk_ao_migrate/README.md               | 36 ++++++----
 2 files changed, 65 insertions(+), 43 deletions(-)

diff --git a/splunk-ao-migration-tool/README.md b/splunk-ao-migration-tool/README.md
index c2397fd5..d8e9ce2a 100644
--- a/splunk-ao-migration-tool/README.md
+++ b/splunk-ao-migration-tool/README.md
@@ -21,64 +21,80 @@ Additionally there are a handful of **removed features** (Protect, `GalileoScore
 
 ---
 
-## 1. Dependency Changes
+## Automated Migration Tool
 
-### 1.1 Package Availability
+Most of the changes above can be applied automatically using the `splunk-ao-migrate` CLI.
 
-> **`splunk-ao` is not yet published to PyPI.**  
-> Use one of the two installation methods below until a public release is available.
+### Installation
 
-**Option A — Install directly from GitHub (recommended for most users)**
+From the `splunk-ao-migration-tool/` directory:
 
 ```bash
-pip install "splunk-ao @ git+https://github.com/splunk/splunk-ao-python.git"
+uv pip install ./splunk_ao_migrate
 ```
 
-With extras:
+### Usage
+
+After installing, invoke the tool with `uv run` so the workspace virtual environment is used automatically (no manual activation needed):
 
 ```bash
-pip install "splunk-ao[langchain] @ git+https://github.com/splunk/splunk-ao-python.git"
-pip install "splunk-ao[otel] @ git+https://github.com/splunk/splunk-ao-python.git"
-```
+# Rewrite an entire directory in place
+uv run splunk-ao-migrate src/
 
-In `requirements.txt`:
+# Rewrite a single file
+uv run splunk-ao-migrate my_agent.py
 
-```text
-splunk-ao @ git+https://github.com/splunk/splunk-ao-python.git
+# Preview changes without writing (dry run)
+uv run splunk-ao-migrate --dry-run src/
+
+# Suppress the summary report
+uv run splunk-ao-migrate --no-report src/
 ```
 
-In `pyproject.toml` (poetry):
+Alternatively, activate the virtual environment first and then call the command directly:
 
-```toml
-splunk-ao = { git = "https://github.com/splunk/splunk-ao-python.git" }
+```bash
+source .venv/bin/activate
+splunk-ao-migrate --dry-run src/
 ```
 
-**Option B — Local install from a cloned repo (recommended for development / contribution)**
+### Run without installing
 
 ```bash
-git clone https://github.com/splunk/splunk-ao-python.git
-pip install -e ./splunk-ao-python
+# With uv (from the splunk-ao-migration-tool/ directory)
+uv run python splunk_ao_migrate/src/splunk_ao_migrate/migrate.py --dry-run src/
+
+# As a module (after uv sync)
+uv run python -m splunk_ao_migrate.migrate --dry-run src/
 ```
 
-In `requirements-dev.txt`:
+After running the tool, review the printed warnings and work through the [migration checklist](#9-migration-checklist) for any steps that require manual action.
 
-```text
--e ../splunk-ao-python          # adjust the relative path to where you cloned it
-```
+---
 
-Or with Poetry:
+## 1. Dependency Changes
 
-```toml
-splunk-ao = { path = "../splunk-ao-python", develop = true }
-```
+### 1.1 Package Availability
 
-**Once `splunk-ao` is published to PyPI**, both install forms above can be replaced with the standard version pin:
+`splunk-ao` is available on PyPI. Replace the `galileo` dependency with:
 
 ```diff
 - galileo>=2.3.0
 + splunk-ao>=0.1.0
 ```
 
+In `requirements.txt`:
+
+```text
+splunk-ao>=0.1.0
+```
+
+In `pyproject.toml` (Poetry):
+
+```toml
+splunk-ao = ">=0.1.0"
+```
+
 ### 1.2 Optional Extra Groups
 
 The extras keys are unchanged (`langchain`, `openai`, `crewai`, `middleware`, `otel`, `all`).  
diff --git a/splunk-ao-migration-tool/splunk_ao_migrate/README.md b/splunk-ao-migration-tool/splunk_ao_migrate/README.md
index a9945347..810d22b0 100644
--- a/splunk-ao-migration-tool/splunk_ao_migrate/README.md
+++ b/splunk-ao-migration-tool/splunk_ao_migrate/README.md
@@ -18,41 +18,47 @@ directories or files whose names contain `galileo`:
 
 ## Installation
 
-```bash
-# Install from the package directory
-pip install ./splunk_ao_migrate
+From the `splunk-ao-migration-tool/` directory (the workspace root):
 
-# Or with uv
+```bash
 uv pip install ./splunk_ao_migrate
 ```
 
-> Run from `splunk-ao-migration-tool/` (the workspace root).
-
 No external dependencies — uses Python stdlib only.
 
 ## Usage
 
+After installing, invoke the tool with `uv run` so the workspace virtual environment is used automatically (no manual activation needed):
+
 ```bash
 # Rewrite an entire directory in place
-splunk-ao-migrate src/
+uv run splunk-ao-migrate src/
 
 # Rewrite a single file
-splunk-ao-migrate my_agent.py
+uv run splunk-ao-migrate my_agent.py
 
 # Preview changes without writing (dry run)
-splunk-ao-migrate --dry-run src/
+uv run splunk-ao-migrate --dry-run src/
 
 # Suppress the summary report
-splunk-ao-migrate --no-report src/
+uv run splunk-ao-migrate --no-report src/
+```
 
-# Run directly without installing (from the workspace root)
-python splunk_ao_migrate/src/splunk_ao_migrate/migrate.py --dry-run src/
+Alternatively, activate the virtual environment first:
 
-# Run as a module (after uv sync)
-python -m splunk_ao_migrate.migrate --dry-run src/
+```bash
+source .venv/bin/activate
+splunk-ao-migrate --dry-run src/
+```
+
+### Run without installing
 
-# Run with uv (from the workspace root)
+```bash
+# Run directly (from the workspace root)
 uv run python splunk_ao_migrate/src/splunk_ao_migrate/migrate.py --dry-run src/
+
+# Run as a module (after uv sync)
+uv run python -m splunk_ao_migrate.migrate --dry-run src/
 ```
 
 ## Package layout