DOC: cross-OS troubleshooting + per-OS ODBC install steps (#1932)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: romanlutz

doc/getting_started/troubleshooting/azure_sql_db.md

@@ -108,7 +108,47 @@ ALTER ROLE db_datawriter ADD MEMBER [user@domain.com];
 
 ## 6. Configure Local Environment
 
-Connecting PyRIT to an Azure SQL Server database requires ODBC, PyODBC and Microsoft's [ODBC Driver for SQL Server](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server?view=sql-server-ver16) to be installed in your local environment. Consult PyODBC's [documentation](https://github.com/mkleehammer/pyodbc/wiki) for detailed instruction on.
+Connecting PyRIT to an Azure SQL Server database requires the **Microsoft ODBC Driver 18 for SQL Server**, which on macOS and Linux depends on **unixODBC**. The `pyodbc` Python package is already installed as a PyRIT dependency.
+
+Install the driver for your OS:
+
+::::{tab-set}
+
+:::{tab-item} Windows
+Download and install the [Microsoft ODBC Driver 18 for SQL Server](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server) MSI from Microsoft.
+:::
+
+:::{tab-item} macOS
+Install via [Homebrew](https://brew.sh):
+
+```bash
+brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
+brew install msodbcsql18 mssql-tools18
+```
+:::
+
+:::{tab-item} Linux (Ubuntu / Debian)
+```bash
+# Install unixODBC
+sudo apt-get update
+sudo apt-get install -y unixodbc unixodbc-dev
+
+# Add the Microsoft package repository
+curl -sSL -O https://packages.microsoft.com/config/ubuntu/$(grep VERSION_ID /etc/os-release | cut -d '"' -f 2)/packages-microsoft-prod.deb
+sudo dpkg -i packages-microsoft-prod.deb
+rm packages-microsoft-prod.deb
+
+# Install the driver
+sudo apt-get update
+sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18
+```
+
+For other Linux distributions (RHEL, SUSE, Alpine), see [Microsoft's installation guide](https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server).
+:::
+
+::::
+
+See [PyODBC's documentation](https://github.com/mkleehammer/pyodbc/wiki) for further details.
 
 ## 7. Testing
 

doc/getting_started/troubleshooting/local_dev.md

@@ -6,22 +6,34 @@ Common issues when setting up PyRIT for local development.
 
 ### uv command not found
 
-Make sure uv is in your PATH. Restart PowerShell after installation.
+Make sure uv is in your `PATH`. Restart your terminal (PowerShell, bash, zsh, etc.) after installing uv so the updated `PATH` is picked up.
 
 ### Import errors
 
 Ensure you're using `uv run python` or have activated the virtual environment:
 
+::::{tab-set}
+
+:::{tab-item} PowerShell (Windows)
 ```powershell
 .\.venv\Scripts\Activate.ps1
 ```
+:::
+
+:::{tab-item} Bash (macOS / Linux)
+```bash
+source .venv/bin/activate
+```
+:::
+
+::::
 
 ### Dependency conflicts
 
-Try regenerating the lock file:
+Try regenerating the lock file (`rm` works in PowerShell as an alias for `Remove-Item`, so the same commands work everywhere):
 
-```powershell
-Remove-Item uv.lock
+```bash
+rm uv.lock
 uv sync
 ```