feat: add go support to upgrade command and update docs

agent_starter_pack/base_templates/go/README.md

@@ -124,6 +124,16 @@ make local-backend  # In one terminal
 make load-test      # In another terminal
 ```
 
+## Keeping Up-to-Date
+
+To upgrade this project to the latest agent-starter-pack version:
+
+```bash
+uvx agent-starter-pack upgrade
+```
+
+This intelligently merges updates while preserving your customizations. Use `--dry-run` to preview changes first. See the [upgrade CLI reference](https://googlecloudplatform.github.io/agent-starter-pack/cli/upgrade.html) for details.
+
 ## Learn More
 
 - [ADK for Go Documentation](https://google.github.io/adk-docs/)

agent_starter_pack/base_templates/python/README.md

@@ -348,4 +348,14 @@ The application provides two levels of observability:
 {%- endif %}
 
 See the [observability guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html) for detailed instructions, example queries, and visualization options.
+
+## Keeping Up-to-Date
+
+To upgrade this project to the latest agent-starter-pack version:
+
+```bash
+uvx agent-starter-pack upgrade
+```
+
+This intelligently merges updates while preserving your customizations. Use `--dry-run` to preview changes first. See the [upgrade CLI reference](https://googlecloudplatform.github.io/agent-starter-pack/cli/upgrade.html) for details.
 {%- endif %}

docs/.vitepress/config.js

@@ -111,6 +111,8 @@ export default defineConfig({
         items: [
           { text: 'create', link: '/cli/create' },
           { text: 'enhance', link: '/cli/enhance' },
+          { text: 'extract', link: '/cli/extract' },
+          { text: 'upgrade', link: '/cli/upgrade' },
           { text: 'list', link: '/cli/list' },
           { text: 'register-gemini-enterprise', link: '/cli/register_gemini_enterprise' },
           { text: 'setup-cicd', link: '/cli/setup_cicd' }

docs/cli/extract.md

@@ -0,0 +1,129 @@
+# extract
+
+The `extract` command creates a minimal, shareable version of your agent by stripping away deployment infrastructure while preserving your core agent logic. This is useful for sharing agents, creating starter templates, or distributing agent code without the full project scaffolding.
+
+## Usage
+
+```bash
+uvx agent-starter-pack extract OUTPUT_PATH [OPTIONS]
+```
+
+## Arguments
+
+- `OUTPUT_PATH` (required): Path where the extracted agent will be created
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--source, -s` | `.` (current directory) | Source project directory |
+| `--dry-run` | `false` | Show what would be extracted without making changes |
+| `--force, -f` | `false` | Overwrite output directory if it exists |
+| `--debug` | `false` | Enable debug logging |
+
+## Examples
+
+### Basic Extraction
+
+```bash
+# Extract current project to a new directory
+uvx agent-starter-pack extract ../my-agent-share
+
+# Extract from a specific source directory
+uvx agent-starter-pack extract ./shared-agent --source /path/to/project
+```
+
+### Preview Changes
+
+```bash
+# See what would be extracted without making changes
+uvx agent-starter-pack extract ../my-agent-share --dry-run
+```
+
+### Overwrite Existing
+
+```bash
+# Force overwrite if output directory exists
+uvx agent-starter-pack extract ../my-agent-share --force
+```
+
+## What Gets Extracted
+
+The extract command preserves your core agent code while removing deployment scaffolding:
+
+**Kept (Agent Code):**
+- Agent directory (e.g., `app/`) with your `agent.py` and custom modules
+- `pyproject.toml` (with scaffolding dependencies removed)
+- `.gitignore`
+- `GEMINI.md` (if present)
+
+**Removed (Scaffolding):**
+- `deployment/` - Terraform infrastructure
+- `.github/` or `.cloudbuild/` - CI/CD pipelines
+- `frontend/` - UI components
+- `data_ingestion/` - Data pipeline code
+- `notebooks/` - Jupyter notebooks
+- `tests/` - Test files
+- `tools/` - Build tools
+- Scaffolding files in agent directory (`fast_api_app.py`, `agent_engine_app.py`, `app_utils/`)
+
+**Generated:**
+- Minimal `Makefile` with basic commands (`install`, `playground`, `lint`)
+- Simplified `README.md` for the extracted project
+
+## How It Works
+
+1. **Detects project language** (Python or Go) from project files
+2. **Reads ASP metadata** from `pyproject.toml` or `.asp.toml`
+3. **Copies agent code** excluding scaffolding files
+4. **Strips scaffolding dependencies** from `pyproject.toml`
+5. **Generates minimal Makefile and README** for standalone use
+6. **Regenerates lock file** (`uv lock` or `go mod tidy`)
+
+## Relationship to `enhance`
+
+The `extract` and `enhance` commands are complementary:
+
+```
+Full Project ──extract──> Minimal Agent ──enhance──> Full Project
+```
+
+- **extract**: Remove scaffolding to create a shareable, minimal agent
+- **enhance**: Add scaffolding back to restore production capabilities
+
+This workflow enables:
+1. **Sharing**: Extract your agent, share it with others
+2. **Receiving**: Others run `enhance` to add their own deployment infrastructure
+3. **Customization**: Recipients can choose different deployment targets, CI/CD runners, etc.
+
+## Example Workflow
+
+```bash
+# 1. Create a full project
+uvx agent-starter-pack create my-agent -a adk -d cloud_run
+
+# 2. Develop your agent...
+cd my-agent
+# ... edit app/agent.py ...
+
+# 3. Extract for sharing
+uvx agent-starter-pack extract ../my-agent-share
+
+# 4. Share the extracted agent (e.g., push to GitHub)
+cd ../my-agent-share
+git init && git add . && git commit -m "Initial agent"
+
+# 5. Recipients can enhance with their own preferences
+uvx agent-starter-pack enhance --deployment-target agent_engine
+```
+
+## Language Support
+
+The extract command supports both Python and Go projects:
+
+| Language | Config File | Lock Command |
+|----------|-------------|--------------|
+| Python | `pyproject.toml` | `uv lock` |
+| Go | `.asp.toml` | `go mod tidy` |
+
+Language is auto-detected from project files.

docs/cli/index.md

@@ -7,6 +7,8 @@ The Agent Starter Pack provides a command-line interface (CLI) to create and set
 - [`create`](create.md) - Create a new generative AI application project
 - [`setup-cicd`](setup_cicd.md) - Set up CI/CD pipeline for your project
 - [`enhance`](enhance.md) - Add agent-starter-pack capabilities to existing projects without creating a new directory
+- [`extract`](extract.md) - Create a minimal, shareable agent by removing deployment scaffolding
+- [`upgrade`](upgrade.md) - Upgrade project to the latest agent-starter-pack version
 - [`list`](list.md) - List available agents and templates
 - [`register-gemini-enterprise`](register_gemini_enterprise.md) - Register a deployed Agent Engine to Gemini Enterprise
 

docs/cli/upgrade.md

@@ -0,0 +1,160 @@
+# upgrade
+
+The `upgrade` command updates your project to the latest version of agent-starter-pack using an intelligent 3-way merge. It automatically applies updates to scaffolding files while preserving your customizations.
+
+## Usage
+
+```bash
+uvx agent-starter-pack upgrade [PROJECT_PATH] [OPTIONS]
+```
+
+## Arguments
+
+- `PROJECT_PATH` (optional): Path to the project to upgrade (default: current directory)
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--dry-run` | `false` | Preview changes without applying them |
+| `--auto-approve, -y` | `false` | Auto-apply non-conflicting changes without prompts |
+| `--debug` | `false` | Enable debug logging |
+
+## Examples
+
+### Basic Upgrade
+
+```bash
+# Upgrade current project
+uvx agent-starter-pack upgrade
+
+# Upgrade a specific project
+uvx agent-starter-pack upgrade /path/to/project
+```
+
+### Preview Changes
+
+```bash
+# See what would change without applying
+uvx agent-starter-pack upgrade --dry-run
+```
+
+### Non-Interactive Upgrade
+
+```bash
+# Auto-approve all non-conflicting changes
+uvx agent-starter-pack upgrade -y
+```
+
+## How the 3-Way Merge Works
+
+The upgrade command uses a 3-way comparison between:
+1. **Your current project** - The files as they exist now
+2. **Old ASP template** - What ASP generated at your project's version
+3. **New ASP template** - What ASP generates at the latest version
+
+This enables intelligent decision-making:
+
+| Your Changes | ASP Changes | Result |
+|--------------|-------------|--------|
+| None | Updated | **Auto-update** - Apply ASP's changes |
+| Modified | None | **Preserve** - Keep your changes |
+| Modified | Updated | **Conflict** - Prompt for resolution |
+| N/A | New file | **Add** - Prompt to add new file |
+| N/A | Removed | **Remove** - Prompt to remove file |
+
+### Files Always Preserved
+
+The following are never modified by upgrade:
+- **Agent code** (e.g., `app/agent.py`, custom modules)
+- **Configuration files** (`.env`, secrets, local configs)
+
+### Conflict Resolution
+
+When both you and ASP have modified a file, you'll be prompted:
+- **(v)iew diff** - See the differences between versions
+- **(k)eep yours** - Preserve your current version
+- **(u)se new** - Replace with ASP's new version
+- **(s)kip** - Don't change the file
+
+## Dependency Handling
+
+The upgrade command intelligently merges dependencies in `pyproject.toml`:
+
+- **ASP dependencies updated** → Automatically update version
+- **Your custom dependencies** → Preserved unchanged
+- **New ASP dependencies** → Added to your project
+- **Removed ASP dependencies** → Optionally removed
+
+Version constraints are respected, and your custom additions are never removed.
+
+## Requirements
+
+- **uvx**: Required for re-generating templates at specific versions
+- **Project metadata**: Your `pyproject.toml` must have `[tool.agent-starter-pack]` with `asp_version`
+
+## How It Works
+
+1. **Reads project metadata** to determine current ASP version
+2. **Re-generates old template** using `uvx agent-starter-pack@{old_version}`
+3. **Re-generates new template** using current ASP version
+4. **Compares all files** using 3-way diff
+5. **Applies changes** based on comparison results
+6. **Updates metadata** to reflect new version
+
+## Example Workflow
+
+```bash
+# Check current version in pyproject.toml
+grep asp_version pyproject.toml
+# asp_version = "0.30.0"
+
+# Preview what would change
+uvx agent-starter-pack upgrade --dry-run
+
+# Output shows:
+# Auto-updating (unchanged by you):
+#   ✓ deployment/terraform/main.tf
+#   ✓ .github/workflows/ci.yaml
+#
+# Preserving (you modified, ASP unchanged):
+#   ✓ Makefile
+#
+# Conflicts (both changed):
+#   ⚠ deployment/terraform/variables.tf
+
+# Apply the upgrade
+uvx agent-starter-pack upgrade
+
+# Resolve any conflicts interactively
+# ...
+
+# Verify upgrade
+grep asp_version pyproject.toml
+# asp_version = "0.31.0"
+```
+
+## Best Practices
+
+1. **Commit before upgrading** - Ensure you can easily revert if needed
+2. **Use dry-run first** - Preview changes before applying
+3. **Review conflicts carefully** - Don't blindly accept new versions
+4. **Test after upgrade** - Run `make test` to verify everything works
+5. **Check dependency changes** - Review any updated package versions
+
+## Troubleshooting
+
+**"No agent-starter-pack metadata found"**
+- Ensure `pyproject.toml` has `[tool.agent-starter-pack]` section
+- This project may not have been created with agent-starter-pack
+
+**"No asp_version found"**
+- Add `asp_version = "X.Y.Z"` to `[tool.agent-starter-pack]` in `pyproject.toml`
+- Use the version you originally created the project with
+
+**"Failed to generate old template"**
+- The old version may not be available on PyPI
+- Try upgrading from a more recent version
+
+**"uvx is required but not installed"**
+- Install uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`

docs/guide/development-guide.md

@@ -177,7 +177,26 @@ Track your agent's performance using integrated observability tools. OpenTelemet
 
 ➡️ For complete setup instructions, example queries, and testing in dev, see the [Observability Guide](./observability.md).
 
-## 4. Advanced Customization
+## 4. Keeping Your Project Up-to-Date
+
+As agent-starter-pack evolves with new features, security fixes, and best practices, you can upgrade your existing projects to newer versions using the `upgrade` command.
+
+```bash
+# Preview what would change
+uvx agent-starter-pack upgrade --dry-run
+
+# Apply the upgrade
+uvx agent-starter-pack upgrade
+```
+
+The upgrade uses an intelligent 3-way merge:
+- **Auto-updates** scaffolding files you haven't modified
+- **Preserves** your customizations when ASP hasn't changed those files
+- **Prompts** you to resolve conflicts when both have changed
+
+➡️ See the [`upgrade` CLI reference](../cli/upgrade.md) for detailed usage.
+
+## 5. Advanced Customization
 
 Tailor the starter pack further to meet your specific requirements.