fix: getting started and installation docs (#166)

* fix: getting started and installation docs

* fix: getting started and installation docs

Author: eliasecchig

README.md

@@ -31,7 +31,7 @@ Ready to build your AI agent? Simply run this command:
 
 ```bash
 # Create and activate a Python virtual environment
-python -m venv venv && source venv/bin/activate
+python -m venv .venv && source .venv/bin/activate
 
 # Install the agent starter pack
 pip install agent-starter-pack

docs/guide/getting-started.md

@@ -13,12 +13,13 @@ This guide quickly walks you through setting up your first agent project.
 
 ```bash
 # Create and activate a Python virtual environment (Recommended)
-python -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 
 # Install the package
 pip install agent-starter-pack
 ```
+Check the [Installation Guide](/guide/installation) for alternative installation methods.
 
 ### 2. Create Your Agent Project
 
@@ -62,10 +63,8 @@ Inside your new project directory (`my-awesome-agent`), you'll find:
 
 ### Next Steps
 
-You're ready to go!
+You're ready to go! See the [Development Guide](/guide/development-guide) for detailed instructions on extending, customizing and deploying your agent.
 
-*   **Customize:** Modify the code in `app/` to edit prompts, configure tools, adjust API endpoints, customize business logic, extend functionality!
-*   **Deploy in minutes:** Use the [setup-cicd](/cli/setup_cicd) command.
-*   **Customized the deployment:** Use Terraform in `deployment/` to deploy to Google Cloud or follow the deployment guide ([Deployment Guide](/guide/deployment)). 
-*   **Add Data (RAG):** Configure [Data Ingestion](/guide/data-ingestion).
-*   **Monitor:** Explore [Observability](/guide/observability) features.
+- **Add Data (RAG):** Configure [Data Ingestion](/guide/data-ingestion) for knowledge-based agents.
+- **Monitor Performance:** Explore [Observability](/guide/observability) features for production monitoring.
+- **Deploy to Production:** Follow the [Deployment Guide](/guide/deployment) to deploy your agent to Google Cloud.

docs/guide/installation.md

@@ -1,74 +1,64 @@
 # Installation
 
-There are several ways to install the Agent Starter Pack. Choose the method that works best for your workflow. You can also [try it in Firebase Studio](https://studio.firebase.google.com/new?template=https%3A%2F%2Fgithub.com%2FGoogleCloudPlatform%2Fagent-starter-pack%2Ftree%2Fmain%2Fsrc%2Fresources%2Fid), a cloud-based development environment with zero setup. 
+There are several ways to install the Agent Starter Pack. Choose the method that works best for your workflow.
 
-## Using pipx (Recommended)
+**Want zero setup?** 👉 [Try in Firebase Studio](https://studio.firebase.google.com/new?template=https%3A%2F%2Fgithub.com%2FGoogleCloudPlatform%2Fagent-starter-pack%2Ftree%2Fmain%2Fsrc%2Fresources%2Fidx) or in [Cloud Shell](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Feliasecchig%2Fasp-open-in-cloud-shell&cloudshell_print=open-in-cs)
 
-The recommended way to install the Agent Starter Pack is with [pipx](https://pypa.github.io/pipx/), which installs the package in an isolated environment while making the commands globally available:
+## `uvx` for Quick Project Creation
 
+If you have [uv](https://astral.sh/uv) installed, you can create projects without a permanent installation:
 ```bash
-# Install pipx if you don't have it
-python3 -m pip install --user pipx && python3 -m pipx ensurepath
-source ~/.bashrc  # or ~/.zshrc depending on your shell
-
-# Install the Agent Starter Pack
-pipx install agent-starter-pack
+uvx agent-starter-pack create my-awesome-agent
 ```
 
-## Using pip with a virtual environment
+## Virtual Environment Installation
 
-You can also install the Agent Starter Pack in a virtual environment:
+Installs into an isolated Python environment.
 
 ```bash
-# Create and activate a Python virtual environment
-python -m venv venv && source venv/bin/activate
+# Create and activate venv
+python -m venv .venv && source .venv/bin/activate # source .venv/Scripts/activate for Windows Git Bash
 
-# Install the Agent Starter Pack
+# Install using pip or uv
 pip install agent-starter-pack
 ```
 
-## Using uv (Fast Python package installer)
+## Persistent CLI Installation
 
-For a faster installation experience, you can use [uv](https://astral.sh/uv):
+Installs the `agent-starter-pack` command globally.
 
+### With `pipx` (Isolated Global Tool)
 ```bash
-# Install uv if you don't have it
-curl -LsSf https://astral.sh/uv/install.sh | sh
-
-# For sh, bash, zsh
-# For fish: source $HOME/.local/bin/env.fish
-source $HOME/.local/bin/env 
+# Install pipx (if needed)
+python3 -m pip install --user pipx && python3 -m pipx ensurepath
 
-# Install the Agent Starter Pack
-uv tool install agent-starter-pack
+# Install Agent Starter Pack
+pipx install agent-starter-pack
 ```
 
-## Getting Started
-
-After installation, you can create a new agent project:
-
+### With `uv tool install` (Fast, Isolated Global Tool)
+Requires `uv` (see `uvx` section for install).
 ```bash
-# Create a new agent project
-agent-starter-pack create my-awesome-agent
+uv tool install agent-starter-pack
 ```
 
+## Create Project (After Persistent/Venv Install)
 
-## Upgrading
-
-To upgrade, use the same tool you used for installation:
-
+If you installed via `pipx`, `uv tool install`, or in a virtual environment:
 ```bash
-pipx upgrade agent-starter-pack  # Using pipx
-pip install --upgrade agent-starter-pack  # Using pip
-uv pip install --upgrade agent-starter-pack  # Using uv
+agent-starter-pack create my-awesome-agent
 ```
 
-## Uninstalling
+## Managing Installation
 
-To uninstall, use the same tool you used for installation:
+### Upgrading
+*   **`uvx`:** Not needed (always uses latest).
+*   **`pipx`:** `pipx upgrade agent-starter-pack`
+*   **`uv tool`:** `uv tool install agent-starter-pack` (this upgrades)
+*   **`pip`/`uv pip` (in .venv):** `(uv) pip install --upgrade agent-starter-pack`
 
-```bash
-pipx uninstall agent-starter-pack # Using pipx
-pip uninstall agent-starter-pack  # Using pip
-uv tool uninstall agent-starter-pack  # Using uv
-```
+### Uninstalling
+*   **`uvx`:** Not applicable.
+*   **`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`

src/deployment_targets/agent_engine/tests/load_test/README.md

@@ -19,8 +19,8 @@ Follow these steps to execute load tests:
 
    ```bash
    # Create and activate virtual environment
-   python3 -m venv locust_env
-   source locust_env/bin/activate
+   python3 -m venv .locust_env
+   source .locust_env/bin/activate
 
    # Install required packages
    pip install locust==2.31.1 "google-cloud-aiplatform[langchain,reasoningengine]>=1.77.0"

src/deployment_targets/cloud_run/tests/load_test/README.md

@@ -18,7 +18,7 @@ uv run uvicorn app.server:app --host 0.0.0.0 --port 8000 --reload
 Using another terminal tab, This is suggested to avoid conflicts with the existing application python environment.
 
 ```bash
-python3 -m venv locust_env && source locust_env/bin/activate && pip install locust==2.31.1
+python3 -m venv .locust_env && source locust_env/bin/activate && pip install locust==2.31.1
 ```
 
 **3. Execute the Load Test:**
@@ -69,7 +69,7 @@ export _ID_TOKEN=$(gcloud auth print-identity-token -q)
 **3. Execute the Load Test:**
 Create virtual environment with Locust:
 ```bash
-python3 -m venv locust_env && source locust_env/bin/activate && pip install locust==2.31.1
+python3 -m venv .locust_env && source locust_env/bin/activate && pip install locust==2.31.1
 ```
 
 Execute load tests. The following command executes the same load test parameters as the local test but targets your remote Cloud Run instance.