diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..98373f0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,220 @@
+# AGENTS.md — AI Agent Guide for onprem-templates
+
+> This file documents conventions, architecture, and workflows for AI agents
+> working on the **IriusRisk On-Prem Automation** repository.
+
+---
+
+## Project Overview
+
+This repository provides **automation scripts** for deploying, upgrading, and
+managing **IriusRisk on-premises** installations on Linux servers. It supports
+both **Docker** and **Podman (rootless)** container engines across multiple
+distributions (RHEL 9, Rocky, Amazon Linux 2023, Ubuntu 22–26).
+
+### Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Template-based compose** | Compose files are generated from `.tpl` templates in `templates/`, then customized per-deployment. Generated `.yml` files are `.gitignore`d. |
+| **Container engine detection** | Auto-selected by OS: Podman on RHEL-like, Docker on Ubuntu/Amazon Linux. |
+| **PostgreSQL** | Either internal (containerized) or external (user-provided connection). |
+| **Jeff (AI Assistant)** | Optional AI component deployed as an additional compose layer. |
+| **Offline mode** | Full air-gapped deployment via `--offline --bundle` flags. |
+| **Version metadata** | `versions/<ver>.json` maps IriusRisk versions to Startleft/Reporting Module tags. |
+
+---
+
+## Directory Structure
+
+```
+onprem-templates/
+├── .github/
+│   ├── .gitleaks.toml          # Secret-scanning config
+│   └── workflows/
+│       └── validate-config.yml # CI: validates version JSON schemas
+├── .pre-commit-config.yaml     # shfmt formatter for scripts/*.sh
+├── .gitignore
+├── README.md
+├── scripts/                    # All automation scripts (bash)
+│   ├── bootstrap.sh            # Entry point: clones repo + runs one-click
+│   ├── one-click.sh            # Main end-to-end installer
+│   ├── setup-wizard.sh         # Interactive configuration wizard
+│   ├── preflight.sh            # Environment validation checks
+│   ├── upgrade.sh              # Version upgrade with backups
+│   ├── rollback.sh             # Rollback from upgrade backups
+│   ├── migrate.sh              # Migrate legacy → template-based system
+│   └── functions.sh            # Shared library (prompts, installs, helpers)
+├── templates/                  # Compose templates (source of truth)
+│   ├── docker/
+│   │   ├── docker-compose.tpl          # Main services (nginx, tomcat, startleft, reporting)
+│   │   ├── docker-compose.override.tpl # Environment overrides
+│   │   ├── docker-compose.jeff.tpl     # Jeff AI assistant services
+│   │   └── docker-compose.postgres.tpl # Internal PostgreSQL
+│   └── podman/
+│       ├── podman-compose.tpl
+│       ├── podman-compose.override.tpl
+│       ├── podman-compose.jeff.tpl
+│       └── podman-compose.postgres.tpl
+├── versions/                   # Version → component tag mappings
+│   ├── 4.46.9.json
+│   ├── 4.47.19.json
+│   └── ...
+└── logs/                       # Deployment logs (gitignored)
+```
+
+---
+
+## Script Architecture
+
+### Execution Flow
+
+```
+bootstrap.sh  (clones repo, jumps to one-click)
+    └── one-click.sh
+            ├── preflight.sh      (validate environment)
+            ├── setup-wizard.sh   (interactive config)
+            └── deploy_stack      (compose up + systemd)
+
+upgrade.sh
+    ├── backup_db + backup compose/service
+    ├── refresh_generated_compose_files_from_templates()
+    ├── update images/tags
+    └── redeploy
+
+rollback.sh
+    └── restore from ~/irius_backups/
+
+migrate.sh
+    └── legacy compose → template-based system
+```
+
+### Shared Library: `functions.sh`
+
+All scripts `source functions.sh`. This is the **single source of truth** for:
+- Prompt helpers (`prompt_yn`, `prompt_engine`, `prompt_registry_settings`)
+- Dependency installers (`install_docker`, `install_podman`, `install_java`, etc.)
+- Image reference resolution (`image_ref`, `postgres_image_ref`, `redis_image_ref`)
+- Compose file manipulation (`refresh_generated_compose_files_from_templates`)
+- Systemd service generation
+- Logging framework (`init_logging`)
+- Offline mode helpers
+- Podman secret management (GPG-encrypted passwords)
+- Health checks (`wait_for_health`, `fetch_health`)
+
+**Convention:** New shared functionality should be added to `functions.sh`, not duplicated across scripts.
+
+### Template System
+
+Templates in `templates/<engine>/` use **shell variable placeholders** (`${VAR}`) that are resolved at deployment time. The workflow is:
+
+1. Copy `.tpl` → `.yml` in the engine-specific directory (`docker/` or `podman/`)
+2. Replace placeholders with actual values via `sed` or variable expansion
+3. Generated `.yml` files are **never committed** (`.gitignore`d)
+
+**When updating compose structure:** Edit the `.tpl` files, not generated `.yml` files.
+
+---
+
+## Version Metadata
+
+Each `versions/<ver>.json` file maps an IriusRisk version to component tags:
+
+```json
+{
+  "Startleft": { "S": "v2.3.1" },
+  "ReportingModule": { "S": "1.4.0" }
+}
+```
+
+- Filename = IriusRisk version (e.g., `4.46.9.json`)
+- Used by `upgrade.sh` to update Startleft and Reporting Module image tags
+- Validated by CI workflow (`.github/workflows/validate-config.yml`)
+
+**Adding a new version:** Create `versions/<ver>.json` with the correct component tags.
+
+---
+
+## Conventions
+
+### Shell Scripts
+
+- **Shebang:** `#!/usr/bin/env bash`
+- **Strict mode:** `set -e` (and `set -e -o pipefail` for upgrade.sh)
+- **Formatting:** `shfmt -ci -s` (enforced by pre-commit hook)
+- **Sourcing:** Always `source functions.sh` at the top, never duplicate logic
+- **Paths:** Use `SCRIPT_PATH` and `REPO_ROOT` variables, never hardcode relative paths
+- **User input:** Use `prompt_yn`, `prompt_nonempty`, etc. from `functions.sh`
+- **Logging:** Use `init_logging "$0"` to auto-log to `logs/<script>_<timestamp>.log`
+
+### Compose Templates
+
+- Use `${VARIABLE_NAME}` placeholders for dynamic values
+- Keep Docker and Podman templates in sync (same structure, engine-specific differences only)
+- Generated files go in `docker/` or `podman/` at repo root (not in `templates/`)
+
+### Git
+
+- Generated compose files (`.yml`), logs, certificates, and `.env` are `.gitignore`d
+- Only `.tpl` templates, scripts, and version metadata are tracked
+
+### Security
+
+- **Never commit secrets** — passwords are handled via prompts or Podman secrets (GPG-encrypted)
+- `.gitleaks.toml` is configured for pre-commit secret scanning
+- Certificates (`.pem`) are gitignored
+
+---
+
+## Common Tasks for Agents
+
+### Adding a New IriusRisk Version
+
+1. Create `versions/<ver>.json` with Startleft and Reporting Module tags
+2. Run `./.github/workflows/validate-config.yml` locally or push to trigger CI
+
+### Adding a New Service to Compose
+
+1. Add the service block to both `templates/docker/docker-compose.tpl` and `templates/podman/podman-compose.tpl`
+2. If the service needs environment variables, add them to the override template
+3. Update `functions.sh` if new image placeholders or registry logic is needed
+
+### Modifying the Upgrade Flow
+
+1. Edit `upgrade.sh` — it is the canonical upgrade script
+2. Ensure backward compatibility with existing backups
+3. Test with both Docker and Podman engines
+
+### Adding a New Dependency Check
+
+1. Add the check to `preflight.sh`
+2. Add the installer function to `functions.sh`
+3. Call the installer from `one-click.sh` based on preflight output
+
+---
+
+## Testing & Validation
+
+- **Pre-commit:** Run `pre-commit run --all-files` to format all scripts with shfmt
+- **CI:** Push to `main` triggers `validate-config.yml` (validates version JSON schemas)
+- **Manual testing:** Always test scripts on the target OS distribution (RHEL, Ubuntu, Amazon Linux)
+- **Offline mode:** Test with `--offline --bundle` flags for air-gapped scenarios
+
+---
+
+## Troubleshooting Patterns
+
+| Symptom | Likely Cause | Fix |
+|---------|-------------|-----|
+| `permission denied` on Docker | User not in `docker` group yet | `newgrp docker` or re-login |
+| Podman boot ID mismatch | `/tmp` storage reset on reboot | Symlinks to `/run/user/<uid>` (handled by scripts) |
+| Compose merge conflicts on `git pull` | Generated `.yml` files tracked | Move `.yml` to `/tmp`, `git pull`, move back |
+| `No medium found` on systemctl | Missing XDG env vars in SSH | Scripts install `/etc/profile.d/10-xdg-user-bus.sh` |
+
+---
+
+## External References
+
+- [Hardware & Software Requirements](https://enterprise-support.iriusrisk.com/s/article/Hardware-and-Software-Requirements-for-IriusRisk)
+- Container registry: `docker.io/continuumsecurity/iriusrisk-prod`
+- Supported OS: RHEL 9, Rocky 9.7, Amazon Linux 2023, Ubuntu 22–26
diff --git a/README.md b/README.md
index 571e927..77db40e 100644
--- a/README.md
+++ b/README.md
@@ -62,7 +62,7 @@ Do **not** run these scripts on a machine that already has a PostgreSQL database
 - Runs interactively and asks questions about:
   - PostgreSQL setup (internal or external)
   - Hostname and external URLs
-  - Azure and Gemini endpoints and API keys if installing Jeff
+  - Azure endpoint/API key, GCP Project ID, Gemini region, and GCP Service Account JSON if installing Jeff
 - Updates configuration files accordingly.
 - Can be run standalone if you want to just configure and not deploy.
 
@@ -95,9 +95,9 @@ Do **not** run these scripts on a machine that already has a PostgreSQL database
 3. **Answer interactive prompts**:
    - Select container registry (default or custom)
    - Decide how to set up PostgreSQL (internal container or external DB)
-   - Choose whether to install Jeff (AI assistant)
+- Decide whether to install Jeff (AI assistant)
    - Provide hostname
-   - Provide Azure and Gemini endpoints and API keys if installing Jeff
+   - Provide Azure endpoint/API key and GCP Project ID, Gemini region, and GCP Service Account JSON if installing Jeff
    - Confirm deployment
 
 4. **Deployment starts**:
@@ -148,35 +148,60 @@ The container engine is selected automatically based on the detected Linux distr
 
 ## 🤖 Jeff (AI Assistant)
 
-Jeff is the IriusRisk AI assistant and can be installed either:
+Jeff is the IriusRisk AI assistant, composed of a multi-service stack deployed during IriusRisk setup. The stack includes:
 
--   During initial setup (`one-click.sh`)
--   During an upgrade (`upgrade.sh`)
+- **Jeff** — orchestration layer, handles user queries and routes to AI providers
+- **RAG** — retrieval-augmented generation with Azure OpenAI embeddings
+- **Ash** — Gemini provider service (uses GCP Service Account credentials for Vertex AI)
+- **Haven** — secure storage and indexing layer
+- **Redis** — caching and session persistence
+
+Jeff can be installed either:
+
+- During initial setup (`one-click.sh`)
+- During an upgrade (`upgrade.sh`)
+
+### Prerequisites
+
+To enable Jeff, you need credentials for **both** AI providers:
+
+| Provider | Credentials |
+|----------|-------------|
+| **Azure OpenAI** | Endpoint URL and API key |
+| **Gemini (Ash)** | GCP Project ID, Gemini region, and GCP Service Account JSON key |
+
+#### GCP Service Account
+
+The Gemini provider (Ash) authenticates using a GCP Service Account JSON key rather than a direct API key. Ash performs a JWT (RS256) token exchange with Google's OAuth2 endpoint to obtain an access token, then calls the Vertex AI `generateContent` API.
+
+During setup, you will paste the full SA JSON key (multi-line) when prompted. The automation inlines the SA credentials into the Jeff compose configuration.
 
 ### Installation (Fresh Setup)
 
 During setup, you will be prompted to enable Jeff.
 
-If enabled: 
-   - Jeff services are included in deployment 
-   - Configuration is applied automatically
+If enabled:
+- All Jeff services are included in deployment
+- Configuration is applied automatically
 
 ### Installation During Upgrade
 
-During upgrade, you can: 
+During upgrade, you can:
 
 - Enable Jeff if not already installed
 
-If enabled: 
+If enabled:
 
-- Compose file is created from template 
-- Systemd service is updated 
+- Compose file is created from template
+- Systemd service is updated
 - Stack is restarted with Jeff enabled
 
 ### Notes
 
--   Jeff is deployed as an additional compose layer
--   Existing installations are preserved during upgrades
+- Jeff is deployed as an additional compose layer
+- Existing installations are preserved during upgrades
+- **Podman**: All Jeff/Ash secrets (Azure API key, GCP SA credentials, Redis password) are encrypted and injected via Podman secrets
+- Ash uses GCP Service Account JWT flow — no raw API keys are stored
 
 ---
 
@@ -526,7 +551,7 @@ postgres-15.4
 
 ### 🤖 Jeff (AI Assistant) Dependencies
 
-If installing **Jeff**, the following image must be available:
+If installing **Jeff**, the following images must be available:
 
 ```text
 redis-stack-latest
diff --git a/scripts/functions.sh b/scripts/functions.sh
index 75ef43c..a7b2e07 100755
--- a/scripts/functions.sh
+++ b/scripts/functions.sh
@@ -914,7 +914,7 @@ function build_podman_custom_images() {
 	postgres_image="${POSTGRES_BASE_IMAGE:-docker.io/library/postgres:15.4}"
 	jeff_image="$(image_ref "ai-jeff-4.6.2")"
 	rag_image="$(image_ref "ai-rag-1.2.2")"
-	ash_image="$(image_ref "ai-ash-1.7.0")"
+	ash_image="$(image_ref "ai-ash-1.9.0")"
 	haven_image="$(image_ref "ai-haven-1.0.1")"
 	redis_image="${REDIS_BASE_IMAGE:-docker.io/redis/redis-stack:latest}"
 
@@ -971,8 +971,8 @@ export_from_secret_env KEY_ALIAS_PASSWORD KEY_ALIAS_PWD_GPG KEY_ALIAS_PRIVKEY_AS
 
 		build_podman_secret_image "$rag_image" "temp-rag" "localhost/ai-rag-1.2.2" "$(podman_secret_to_env_snippet AZURE_API_KEY AZURE_API_KEY_GPG AZURE_API_PRIVKEY_ASC)"
 
-		build_podman_secret_image "$ash_image" "temp-ash" "localhost/ai-ash-1.7.0" $'export_from_secret_env GEMINI_API_KEY GEMINI_API_KEY_GPG GEMINI_API_PRIVKEY_ASC
-export_from_secret_env AZURE_OPENAI_API_KEY AZURE_API_KEY_GPG AZURE_API_PRIVKEY_ASC'
+		build_podman_secret_image "$ash_image" "temp-ash" "localhost/ai-ash-1.9.0" $'export_from_secret_env AZURE_OPENAI_API_KEY AZURE_API_KEY_GPG AZURE_API_PRIVKEY_ASC
+export_from_secret_env GCP_SERVICE_ACCOUNT_KEY GCP_S_A_CREDENTIALS_GPG GCP_S_A_PRIVKEY_ASC'
 
 		build_podman_secret_image "$haven_image" "temp-haven" "localhost/ai-haven-1.0.1" $'export_from_secret_env AZURE_API_KEY AZURE_API_KEY_GPG AZURE_API_PRIVKEY_ASC
 export_from_secret_env REDIS_PASSWORD REDIS_PASSWORD_GPG REDIS_PRIVKEY_ASC'
@@ -1943,13 +1943,14 @@ function validate_preserved_values() {
 		# Needed on both engines because they remain in the compose file
 		require_preserved_value "AZURE_ENDPOINT"
 		require_preserved_value "AZURE_OPENAI_ENDPOINT"
-		require_preserved_value "GEMINI_ENDPOINT"
+		require_preserved_value "PROJECT_ID"
+		require_preserved_value "GEMINI_REGION"
 
 		# Only Docker keeps these in the Jeff compose file
 		if [[ ${CONTAINER_ENGINE:-} == "docker" ]]; then
 			require_preserved_value "AZURE_API_KEY"
 			require_preserved_value "AZURE_OPENAI_API_KEY"
-			require_preserved_value "GEMINI_API_KEY"
+			require_preserved_value "GCP_S_A_CREDENTIALS"
 			require_preserved_value "REDIS_PASSWORD"
 		fi
 	fi
@@ -2128,9 +2129,6 @@ function capture_preserved_values() {
 			POSTGRES_PASSWORD)
 				PRESERVED_VALUES["$p"]="$(extract_postgres_password "$override_file" "$postgres_file" || true)"
 				;;
-			GEMINI_ENDPOINT)
-				[[ -n $jeff_file ]] && PRESERVED_VALUES["$p"]="$(extract_env_value "GEMINI_API_BASE" "$jeff_file" || true)"
-				;;
 			AZURE_ENDPOINT)
 				[[ -n $jeff_file ]] && PRESERVED_VALUES["$p"]="$(extract_env_value "AZURE_ENDPOINT" "$jeff_file" || true)"
 				;;
@@ -2140,11 +2138,22 @@ function capture_preserved_values() {
 					[[ -z ${PRESERVED_VALUES[$p]} ]] && PRESERVED_VALUES["$p"]="$(extract_env_value "AZURE_ENDPOINT" "$jeff_file" || true)"
 				fi
 				;;
-			AZURE_API_KEY | AZURE_OPENAI_API_KEY | GEMINI_API_KEY | REDIS_PASSWORD)
+			PROJECT_ID)
+				[[ -n $jeff_file ]] && PRESERVED_VALUES["$p"]="$(extract_env_value "GEMINI_PROJECT_ID" "$jeff_file" || true)"
+				;;
+			GEMINI_REGION)
+				[[ -n $jeff_file ]] && PRESERVED_VALUES["$p"]="$(extract_env_value "GEMINI_REGION" "$jeff_file" || true)"
+				;;
+			AZURE_API_KEY | AZURE_OPENAI_API_KEY | REDIS_PASSWORD)
 				if [[ ${CONTAINER_ENGINE:-} == "docker" && -n $jeff_file ]]; then
 					PRESERVED_VALUES["$p"]="$(extract_env_value "$p" "$jeff_file" || true)"
 				fi
 				;;
+			GCP_S_A_CREDENTIALS)
+				if [[ ${CONTAINER_ENGINE:-} == "docker" && -n $jeff_file ]]; then
+					PRESERVED_VALUES["$p"]="$(extract_env_value "GCP_SERVICE_ACCOUNT_KEY" "$jeff_file" || true)"
+				fi
+				;;
 			NGINX_IMAGE | TOMCAT_IMAGE | STARTLEFT_IMAGE | REPORTING_MODULE_IMAGE)
 				PRESERVED_VALUES["$p"]="$(extract_image_value_for_placeholder "$p" "$compose_file" || true)"
 				;;
@@ -2711,37 +2720,136 @@ function save_local_with_fullref() {
 # —————————————————————————————————————————————————————————————
 
 function check_gemini_api() {
-	local endpoint="$1"
-	local api_key="$2"
-	local tmp_out status
+	# $1 = GEMINI_PROJECT_ID
+	# $2 = GEMINI_REGION
+	# $3 = GCP_SERVICE_ACCOUNT_KEY (full JSON)
+	local project_id="$1"
+	local region="$2"
+	local sa_json="$3"
+	local model="${4:-gemini-2.5-flash}"
+	local tmp_dir sa_file key_file client_email private_key
+
+	# Dependency checks
+	for cmd in openssl jq; do
+		if ! command -v "$cmd" &>/dev/null; then
+			msg="ERROR: $cmd is required for Gemini connectivity check but not installed"
+			echo "$msg"
+			ERRORS+=("$msg")
+			return 1
+		fi
+	done
 
-	tmp_out=$(mktemp)
+	tmp_dir=$(mktemp -d)
+	trap "rm -rf '$tmp_dir'" RETURN
 
-	status=$(curl -sS -o "$tmp_out" -w "%{http_code}" \
+	sa_file="$tmp_dir/sa.json"
+	key_file="$tmp_dir/key.pem"
+
+	# Extract SA fields
+	printf '%s' "$sa_json" >"$sa_file"
+	client_email=$(jq -r '.client_email' "$sa_file" 2>/dev/null) || {
+		msg="ERROR: Failed to parse GCP service account JSON"
+		echo "$msg"
+		ERRORS+=("$msg")
+		return 1
+	}
+
+	private_key=$(jq -r '.private_key' "$sa_file" 2>/dev/null) || {
+		msg="ERROR: Failed to extract private_key from service account JSON"
+		echo "$msg"
+		ERRORS+=("$msg")
+		return 1
+	}
+
+	printf '%s' "$private_key" >"$key_file"
+
+	# Validate key
+	if ! openssl pkey -in "$key_file" -check -noout 2>/dev/null; then
+		msg="ERROR: Invalid GCP service account private key"
+		echo "$msg"
+		ERRORS+=("$msg")
+		return 1
+	fi
+
+	# Build JWT assertion (RS256)
+	local now exp header_b64 payload_b64 signing_input signature_b64 assertion
+	now=$(date +%s)
+	exp=$((now + 300))
+
+	header_b64=$(printf '{"alg":"RS256","typ":"JWT"}' |
+		base64 | tr '+/' '-_' | tr -d '=' | tr -d '\n')
+
+	payload_b64=$(printf '{"iss":"%s","scope":"https://www.googleapis.com/auth/cloud-platform","aud":"https://oauth2.googleapis.com/token","iat":%d,"exp":%d}' \
+		"$client_email" "$now" "$exp" |
+		base64 | tr '+/' '-_' | tr -d '=' | tr -d '\n')
+
+	signing_input="${header_b64}.${payload_b64}"
+
+	signature_b64=$(printf '%s' "$signing_input" |
+		openssl dgst -sha256 -sign "$key_file" -binary |
+		base64 | tr '+/' '-_' | tr -d '=' | tr -d '\n')
+
+	assertion="${signing_input}.${signature_b64}"
+
+	# Exchange JWT for access token
+	local post_body token_file http_code access_token
+	post_body="$tmp_dir/post_body.txt"
+	printf '%s' "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=$(printf '%s' "$assertion" | jq -sRr @uri)" >"$post_body"
+
+	token_file="$tmp_dir/token.json"
+	http_code=$(curl -sS -X POST \
+		-H "Content-Type: application/x-www-form-urlencoded" \
+		--data-binary "@$post_body" \
+		-w "%{http_code}" \
+		-o "$token_file" \
+		"https://oauth2.googleapis.com/token")
+
+	if [[ $http_code != "200" ]]; then
+		msg="ERROR: GCP token exchange failed (HTTP $http_code). Check service account credentials"
+		echo "$msg"
+		ERRORS+=("$msg")
+		return 1
+	fi
+
+	access_token=$(jq -r '.access_token // empty' "$token_file")
+	if [[ -z $access_token ]]; then
+		msg="ERROR: No access_token in GCP token response"
+		echo "$msg"
+		ERRORS+=("$msg")
+		return 1
+	fi
+
+	# Call Gemini API via Vertex AI endpoint
+	local api_url response_file generated_text
+	api_url="https://${region}-aiplatform.googleapis.com/v1/projects/${project_id}/locations/${region}/publishers/google/models/${model}:generateContent"
+
+	response_file="$tmp_dir/response.json"
+	http_code=$(curl -sS -o "$response_file" -w "%{http_code}" \
+		-H "Authorization: Bearer $access_token" \
 		-H "Content-Type: application/json" \
-		-H "Authorization: Bearer $api_key" \
 		-X POST \
 		-d '{
-			"model": "gemini-2.5-flash",
-			"messages": [
-				{"role": "user", "content": "Reply with exactly OK"}
-			],
-			"max_tokens": 5
+			"contents": [{"role": "user", "parts": [{"text": "Reply with exactly OK"}]}],
+			"generationConfig": {"maxOutputTokens": 5, "thinkingConfig": {"thinkingBudget": 0}}
 		}' \
-		"${endpoint%/}/chat/completions")
+		"$api_url")
 
-	if [[ $status == "200" ]]; then
-		echo "Gemini API connectivity OK"
-	else
-		msg="ERROR: Gemini API check failed (HTTP $status). Check GEMINI_ENDPOINT and GEMINI_API_KEY"
+	if [[ $http_code != "200" ]]; then
+		msg="ERROR: Gemini API check failed (HTTP $http_code). Check project, region, and service account permissions"
 		echo "$msg"
 		ERRORS+=("$msg")
-		echo "Gemini response snippet:"
-		head -c 300 "$tmp_out"
-		echo
+		echo "   Response: $(head -c 300 "$response_file")"
+		return 1
 	fi
 
-	rm -f "$tmp_out"
+	generated_text=$(jq -r '.candidates[0].content.parts[0].text // "NO TEXT"' "$response_file")
+	if [[ $generated_text == "OK" ]]; then
+		echo "Gemini API connectivity OK (project=$project_id, region=$region)"
+	else
+		msg="WARNING: Gemini API responded but returned unexpected text: '$generated_text'"
+		echo "$msg"
+		WARNINGS+=("$msg")
+	fi
 }
 
 function check_azure_endpoint() {
@@ -2783,10 +2891,22 @@ function prompt_jeff_config() {
 
 	AZURE_ENDPOINT=$(prompt_nonempty "Enter the Azure endpoint for Jeff AI assistant")
 	AZURE_API_KEY=$(prompt_nonempty "Enter the Azure API key for Jeff AI assistant")
-	GEMINI_ENDPOINT=$(prompt_nonempty "Enter the Gemini endpoint for Jeff AI assistant")
-	GEMINI_API_KEY=$(prompt_nonempty "Enter the Gemini API key for Jeff AI assistant")
+	PROJECT_ID=$(prompt_nonempty "Enter the GCP Project ID for Ash")
+	GEMINI_REGION=$(prompt_nonempty "Enter the Gemini region for Ash")
+	# GCP SA JSON is multi-line — read until empty line
+	echo "Paste the GCP Service Account JSON key, then press enter twice:"
+	GCP_S_A_CREDENTIALS=""
+	while IFS= read -r line; do
+		[[ -z $line ]] && break
+		[[ -n $GCP_S_A_CREDENTIALS ]] && GCP_S_A_CREDENTIALS+=$'\n'
+		GCP_S_A_CREDENTIALS+="$line"
+	done
+	if [[ -z $GCP_S_A_CREDENTIALS ]]; then
+		echo "Invalid input: GCP Service Account credentials cannot be empty." >&2
+		exit 1
+	fi
 
-	export AZURE_ENDPOINT AZURE_API_KEY GEMINI_ENDPOINT GEMINI_API_KEY
+	export AZURE_ENDPOINT AZURE_API_KEY PROJECT_ID GEMINI_REGION GCP_S_A_CREDENTIALS
 }
 
 function update_base_override_env() {
@@ -2867,24 +2987,39 @@ function configure_jeff_file() {
 
 	sed -i "s|AZURE_ENDPOINT=.*|AZURE_ENDPOINT=$AZURE_ENDPOINT|g" "$jeff_file"
 	sed -i "s|AZURE_OPENAI_ENDPOINT=.*|AZURE_OPENAI_ENDPOINT=$AZURE_ENDPOINT|g" "$jeff_file"
-	sed -i "s|GEMINI_API_BASE=.*|GEMINI_API_BASE=$GEMINI_ENDPOINT|g" "$jeff_file"
+	sed -i "s|PROJECT_ID=.*|PROJECT_ID=$PROJECT_ID|g" "$jeff_file"
+	sed -i "s|GEMINI_REGION=.*|GEMINI_REGION=$GEMINI_REGION|g" "$jeff_file"
+	# Write SA key as compact JSON (single line) to replace placeholder
+	_tmp_sa=$(mktemp)
+	echo "$GCP_S_A_CREDENTIALS" >"$_tmp_sa"
+	python3 -c "
+import sys, json, re
+# Read the SA JSON
+with open(sys.argv[1]) as f:
+    sa_data = json.load(f)
+# Read the Jeff compose file
+with open(sys.argv[2]) as f:
+    content = f.read()
+# Replace placeholder with compact JSON
+placeholder = '\${GCP_S_A_CREDENTIALS}'
+content = content.replace(placeholder, json.dumps(sa_data, separators=(',', ':')))
+# Write back
+with open(sys.argv[2], 'w') as f:
+    f.write(content)
+" "$_tmp_sa" "$jeff_file"
+	rm -f "$_tmp_sa"
 
 	if [[ $CONTAINER_ENGINE == "docker" ]]; then
 		sed -i "s|AZURE_API_KEY=.*|AZURE_API_KEY=$AZURE_API_KEY|g" "$jeff_file"
 		sed -i "s|AZURE_OPENAI_API_KEY=.*|AZURE_OPENAI_API_KEY=$AZURE_API_KEY|g" "$jeff_file"
-		sed -i "s|GEMINI_API_KEY=.*|GEMINI_API_KEY=$GEMINI_API_KEY|g" "$jeff_file"
 
-		escaped_redis_password=$(printf '%s\n' "$REDIS_PASSWORD" | sed 's/[&/\]/\\&/g')
+		escaped_redis_password=$(printf '%s\n' "$REDIS_PASSWORD" | sed 's/[&/\\]/\\&/g')
 		sed -i "s|\"\${REDIS_PASSWORD}\"|\"$escaped_redis_password\"|g" "$jeff_file"
 		sed -i "s|\${REDIS_PASSWORD}|$escaped_redis_password|g" "$jeff_file"
 	else
-		sed -i '/AZURE_API_KEY=/d' "$jeff_file"
-		sed -i '/AZURE_OPENAI_API_KEY=/d' "$jeff_file"
-		sed -i '/GEMINI_API_KEY=/d' "$jeff_file"
-		sed -i '/REDIS_PASSWORD=/d' "$jeff_file"
 
 		encrypt_and_store_secret "$AZURE_API_KEY" "azure_api_key" "azure_api_privkey"
-		encrypt_and_store_secret "$GEMINI_API_KEY" "gemini_api_key" "gemini_api_privkey"
+		encrypt_and_store_secret "$GCP_S_A_CREDENTIALS" "gcp_sa_credentials" "gcp_sa_privkey"
 		encrypt_and_store_secret "$REDIS_PASSWORD" "redis_password" "redis_privkey"
 	fi
 
@@ -2923,7 +3058,7 @@ function update_compose_image_placeholders() {
 		if [[ -f $jeff_file ]]; then
 			jeff_image="$(image_ref "ai-jeff-4.6.2")"
 			rag_image="$(image_ref "ai-rag-1.2.2")"
-			ash_image="$(image_ref "ai-ash-1.7.0")"
+			ash_image="$(image_ref "ai-ash-1.9.0")"
 			haven_image="$(image_ref "ai-haven-1.0.1")"
 			redis_image="$(redis_image_ref)"
 
diff --git a/scripts/preflight.sh b/scripts/preflight.sh
index ba6bf7c..535dd7d 100755
--- a/scripts/preflight.sh
+++ b/scripts/preflight.sh
@@ -218,19 +218,29 @@ if [[ $JEFF_ENABLED == "y" ]]; then
 			echo "AZURE_ENDPOINT: $AZURE_ENDPOINT_VALUE"
 		fi
 
-		GEMINI_ENDPOINT_VALUE=$(grep 'GEMINI_API_BASE=' "$JEFF_FILE" | head -1 | sed 's/.*GEMINI_API_BASE=//;s/"//g' | xargs)
-		if [[ -z $GEMINI_ENDPOINT_VALUE || $GEMINI_ENDPOINT_VALUE == '${GEMINI_API_BASE}' ]]; then
-			msg="WARNING: GEMINI_API_BASE must be set to a real value in $JEFF_FILE when Jeff is enabled"
+		PROJECT_ID_VALUE=$(grep 'GEMINI_PROJECT_ID=' "$JEFF_FILE" | head -1 | sed 's/.*GEMINI_PROJECT_ID=//;s/"//g' | xargs)
+		if [[ -z $PROJECT_ID_VALUE || $PROJECT_ID_VALUE == '${PROJECT_ID}' ]]; then
+			msg="WARNING: GEMINI_PROJECT_ID must be set to a real value in $JEFF_FILE when Jeff is enabled"
 			echo "$msg"
 			WARNINGS+=("$msg")
 			JEFF_VALUES_FILLED=0
 		else
-			echo "GEMINI_API_BASE: $GEMINI_ENDPOINT_VALUE"
+			echo "GEMINI_PROJECT_ID: $PROJECT_ID_VALUE"
+		fi
+
+		GEMINI_REGION_VALUE=$(grep 'GEMINI_REGION=' "$JEFF_FILE" | head -1 | sed 's/.*GEMINI_REGION=//;s/"//g' | xargs)
+		if [[ -z $GEMINI_REGION_VALUE || $GEMINI_REGION_VALUE == '${GEMINI_REGION}' ]]; then
+			msg="WARNING: GEMINI_REGION must be set to a real value in $JEFF_FILE when Jeff is enabled"
+			echo "$msg"
+			WARNINGS+=("$msg")
+			JEFF_VALUES_FILLED=0
+		else
+			echo "GEMINI_REGION: $GEMINI_REGION_VALUE"
 		fi
 
 		if [[ $CONTAINER_ENGINE == "podman" ]]; then
 			AZURE_API_KEY_VALUE="$(read_podman_secret_plaintext azure_api_key azure_api_privkey || true)"
-			GEMINI_API_KEY_VALUE="$(read_podman_secret_plaintext gemini_api_key gemini_api_privkey || true)"
+			GCP_S_A_CREDENTIALS_VALUE="$(read_podman_secret_plaintext gcp_sa_credentials gcp_sa_privkey || true)"
 			REDIS_PASSWORD_VALUE="$(read_podman_secret_plaintext redis_password redis_privkey || true)"
 
 			if [[ -z $AZURE_API_KEY_VALUE ]]; then
@@ -242,13 +252,13 @@ if [[ $JEFF_ENABLED == "y" ]]; then
 				echo "azure_api_key Podman secret is set"
 			fi
 
-			if [[ -z $GEMINI_API_KEY_VALUE ]]; then
-				msg="WARNING: Podman secret 'gemini_api_key' must exist and be readable when Jeff is enabled"
+			if [[ -z $GCP_S_A_CREDENTIALS_VALUE ]]; then
+				msg="WARNING: Podman secret 'gcp_sa_credentials' must exist and be readable when Jeff is enabled"
 				echo "$msg"
 				WARNINGS+=("$msg")
 				JEFF_VALUES_FILLED=0
 			else
-				echo "gemini_api_key Podman secret is set"
+				echo "gcp_sa_credentials Podman secret is set"
 			fi
 
 			if [[ -z $REDIS_PASSWORD_VALUE ]]; then
@@ -270,14 +280,14 @@ if [[ $JEFF_ENABLED == "y" ]]; then
 				echo "AZURE_API_KEY is set"
 			fi
 
-			GEMINI_API_KEY_VALUE=$(grep 'GEMINI_API_KEY=' "$JEFF_FILE" | head -1 | sed 's/.*GEMINI_API_KEY=//;s/"//g' | xargs)
-			if [[ -z $GEMINI_API_KEY_VALUE || $GEMINI_API_KEY_VALUE == '${GEMINI_API_KEY}' ]]; then
-				msg="WARNING: GEMINI_API_KEY must be set to a real value in $JEFF_FILE when Jeff is enabled"
+			GCP_S_A_CREDENTIALS_VALUE=$(grep 'GCP_SERVICE_ACCOUNT_KEY=' "$JEFF_FILE" | head -1 | sed 's/.*GCP_SERVICE_ACCOUNT_KEY=//')
+			if [[ -z $GCP_S_A_CREDENTIALS_VALUE || $GCP_S_A_CREDENTIALS_VALUE == '${GCP_S_A_CREDENTIALS}' ]]; then
+				msg="WARNING: GCP_SERVICE_ACCOUNT_KEY must be set to a real value in $JEFF_FILE when Jeff is enabled"
 				echo "$msg"
 				WARNINGS+=("$msg")
 				JEFF_VALUES_FILLED=0
 			else
-				echo "GEMINI_API_KEY is set"
+				echo "GCP_SERVICE_ACCOUNT_KEY is set"
 			fi
 
 			REDIS_PASSWORD_VALUE=$(grep 'REDIS_PASSWORD=' "$JEFF_FILE" | head -1 | sed 's/.*REDIS_PASSWORD=//;s/"//g' | xargs)
@@ -321,11 +331,13 @@ fi
 # —————————————————————————————————————————————————————————————
 
 if [[ $JEFF_ENABLED == "y" && $JEFF_VALUES_FILLED -eq 1 ]]; then
-	echo "Checking Azure and Gemini API connectivity..."
-	check_gemini_api "$GEMINI_ENDPOINT_VALUE" "$GEMINI_API_KEY_VALUE"
+	echo "Checking Azure API connectivity..."
 	check_azure_endpoint "$AZURE_ENDPOINT_VALUE" "$AZURE_API_KEY_VALUE"
+
+	echo "Checking Gemini API connectivity..."
+	check_gemini_api "$PROJECT_ID_VALUE" "$GEMINI_REGION_VALUE" "$GCP_S_A_CREDENTIALS_VALUE"
 else
-	echo "Azure/Gemini connectivity checks skipped."
+	echo "Azure and Gemini connectivity checks skipped."
 fi
 
 # —————————————————————————————————————————————————————————————
diff --git a/templates/docker/docker-compose.jeff.tpl b/templates/docker/docker-compose.jeff.tpl
index 3ac54b1..3d661fa 100644
--- a/templates/docker/docker-compose.jeff.tpl
+++ b/templates/docker/docker-compose.jeff.tpl
@@ -40,18 +40,20 @@ services:
   ash:
     environment:
       - CORS_ORIGINS=http://localhost:5173, http://localhost:8003
-      - GEMINI_API_KEY=${GEMINI_API_KEY}
-      - AZURE_OPENAI_API_KEY=${AZURE_OPENAI_API_KEY}
+      - AZURE_OPENAI_ENDPOINT=${AZURE_ENDPOINT}
+      - AZURE_OPENAI_API_KEY=${AZURE_API_KEY}
       - RAG_HOST=http://rag:8010
-      - GEMINI_API_BASE=${GEMINI_ENDPOINT}
-      - AZURE_OPENAI_ENDPOINT=${AZURE_OPENAI_ENDPOINT}
+      - GEMINI_API_KEY=""
+      - GEMINI_PROJECT_ID=${PROJECT_ID}
+      - GEMINI_REGION=${GEMINI_REGION}
+      - GCP_SERVICE_ACCOUNT_KEY=${GCP_S_A_CREDENTIALS}
     ports:
       - 8009:8009
     image: ${ASH_IMAGE}
     container_name: ash
     restart: unless-stopped
     networks:
-    - iriusrisk-backend  
+    - iriusrisk-backend
   haven:
     environment:
       - ENVIRONMENT=PROD
diff --git a/templates/podman/podman-compose.jeff.tpl b/templates/podman/podman-compose.jeff.tpl
index 4abaaae..936da99 100644
--- a/templates/podman/podman-compose.jeff.tpl
+++ b/templates/podman/podman-compose.jeff.tpl
@@ -52,20 +52,22 @@ services:
   ash:
     environment:
       - CORS_ORIGINS=http://localhost:5173, http://localhost:8003
+      - AZURE_OPENAI_ENDPOINT=${AZURE_ENDPOINT}
       - RAG_HOST=http://rag:8010
-      - GEMINI_API_BASE=${GEMINI_ENDPOINT}
-      - AZURE_OPENAI_ENDPOINT=${AZURE_OPENAI_ENDPOINT}
+      - GEMINI_API_KEY=""
+      - GEMINI_PROJECT_ID=${PROJECT_ID}
+      - GEMINI_REGION=${GEMINI_REGION}
     ports:
       - 8009:8009
-    image: localhost/ai-ash-1.7.0
+    image: localhost/ai-ash-1.9.0
     container_name: ash
     restart: unless-stopped
     secrets:
-      - source: gemini_api_key
-        target: GEMINI_API_KEY_GPG
+      - source: gcp_sa_credentials
+        target: GCP_S_A_CREDENTIALS_GPG
         type: env
-      - source: gemini_api_privkey
-        target: GEMINI_API_PRIVKEY_ASC
+      - source: gcp_sa_privkey
+        target: GCP_S_A_PRIVKEY_ASC
         type: env
       - source: azure_api_key
         target: AZURE_API_KEY_GPG
@@ -128,9 +130,9 @@ secrets:
     external: true
   azure_api_privkey:
     external: true
-  gemini_api_key:
+  gcp_sa_credentials:
     external: true
-  gemini_api_privkey:
+  gcp_sa_privkey:
     external: true
   redis_password:
     external: true