Docs: Add comprehensive troubleshooting section to installation guide (#169)

Author: Vasanthadithya-mundrathi

docs/guide/installation.md

@@ -62,3 +62,90 @@ agent-starter-pack create my-awesome-agent
 *   **`pipx`:** `pipx uninstall agent-starter-pack`
 *   **`uv tool`:** `uv tool uninstall agent-starter-pack`
 *   **`pip`/`uv pip` (in .venv):** `(uv) pip uninstall agent-starter-pack`
+
+## Troubleshooting Common Installation Issues
+
+### Command Not Found After Installation
+
+If you encounter "command not found" errors after installation:
+
+1.  **Check your PATH**: Ensure that the Python scripts directory is in your PATH:
+    ```bash
+    echo $PATH
+    ```
+2.  **Verify installation location**: Check where the package was installed:
+    ```bash
+    pip show agent-starter-pack
+    ```
+3.  **Manual path addition**: If needed, add the scripts directory to your PATH:
+    ```bash
+    export PATH="$HOME/.local/bin:$PATH"
+    # For user installations
+    ```
+    Add this line to your `~/.bashrc` or `~/.zshrc` for persistence.
+
+### Permission Errors During Installation
+
+If you encounter permission errors:
+
+1.  **Use user installation mode**:
+    ```bash
+    pip install --user agent-starter-pack
+    ```
+2.  **Check directory permissions**:
+    ```bash
+    ls -la ~/.local/bin
+    ```
+3.  **Fix permissions if needed**:
+    ```bash
+    chmod +x ~/.local/bin/agent-starter-pack
+    ```
+
+### Python Version Compatibility Issues
+
+If you encounter Python version errors:
+
+1.  **Check your Python version**:
+    ```bash
+    python --version
+    ```
+2.  **Install a compatible Python version** if needed (3.10 or newer is required).
+3.  **Create a virtual environment with the correct Python version**:
+    ```bash
+    python3.10 -m venv .venv
+    source .venv/bin/activate
+    ```
+
+### Package Dependency Conflicts
+
+If you encounter dependency conflicts:
+
+1.  **Use a clean virtual environment**:
+    ```bash
+    python -m venv .venv
+    source .venv/bin/activate
+    pip install agent-starter-pack
+    ```
+2.  **Update pip and setuptools**:
+    ```bash
+    pip install --upgrade pip setuptools
+    ```
+3.  **Install with verbose output to identify conflicts**:
+    ```bash
+    pip install -v agent-starter-pack
+    ```
+
+### Installation Verification
+
+To verify your installation is working correctly:
+
+1.  **Check the installed version**:
+    ```bash
+    agent-starter-pack --version
+    ```
+2.  **Run the help command**:
+    ```bash
+    agent-starter-pack --help
+    ```
+
+If you continue to experience issues, please [file an issue](https://github.com/GoogleCloudPlatform/agent-starter-pack/issues) with details about your environment and the specific error messages you're encountering.