Gemini integration

The orchestration system can route bulk sweeps and second-opinion requests to Google Gemini via a PowerShell REST wrapper. This gives an independent, non-Anthropic perspective on code, infrastructure, and docs.

---

Components

Component	Location	Purpose
Invoke-HCSGeminiPrompt.ps1	D:\git\platform\scripts\	PowerShell 7 REST wrapper — calls the Gemini API
HCS.KeyVault.psm1	D:\git\platform\scripts\lib\	Resolves keyvault://kv-hcs-vault-01/gemini-api-key at runtime
gemini-runner agent	.claude\agents\gemini-runner.md	Orchestration agent that wraps the script
/second-opinion command	.claude\commands\second-opinion.md	One-artifact Gemini analysis
/sweep command	.claude\commands\sweep.md	Bulk estate sweep (high-volume → routes to gemini-runner)

---

Setup

1. Store the API key

The Gemini API key is stored as a Key Vault secret — never committed to any repo.

# One-time setup (already done in Phase 0b)
az keyvault secret set `
    --vault-name kv-hcs-vault-01 `
    --name gemini-api-key `
    --value "<your-key>"

The key is registered in docs/identity/secret-inventory.md. The wrapper resolves it at runtime — you never pass it as a parameter.

2. Enable billing

The free tier has a quota of 0 requests. Billing must be enabled at aistudio.google.com before any actual requests return results. Dry-run mode works without billing.

3. Authenticate Azure CLI

The HCS.KeyVault.psm1 module resolves the key via the Azure CLI:

az login                           # or az login --use-device-code for MFA

The Az.KeyVault PowerShell module is tried first and may fail with Unauthorized (wrong-tenant cached token). This is expected — the az CLI fallback handles it automatically.

---

Using the wrapper directly

Import-Module D:\git\platform\scripts\lib\HCS.KeyVault.psm1

# Dry run — resolves key, constructs request, does NOT send
D:\git\platform\scripts\Invoke-HCSGeminiPrompt.ps1 `
    -Prompt "Analyze this Terraform config for WAF security gaps." `
    -DryRun

# Real request (requires billing enabled)
D:\git\platform\scripts\Invoke-HCSGeminiPrompt.ps1 `
    -Prompt "Analyze this Terraform config for WAF security gaps." `
    -FilePaths @("D:\git\turnerlegacy\turner-infrastructure\main.tf") `
    -OutputFormat text

Parameters:

Parameter	Required	Default	Description
-Prompt	Yes	—	The question or instruction
-Model	No	gemini-2.0-flash	Gemini model to use
-FilePaths	No	—	Files to inline into the prompt
-OutputFormat	No	text	text or json
-VaultName	No	kv-hcs-vault-01	Key Vault for the API key
-DryRun	No	false	Construct but do not send the request

---

Using via orchestration commands

/second-opinion D:\git\turnerlegacy\turner-infrastructure\main.tf -- "WAF security gaps?"

/sweep caf-naming              # routes to gemini-runner for high-volume analysis

---

Key Vault secret

Secret name	Vault	Purpose
gemini-api-key	kv-hcs-vault-01	Google AI API key for Gemini REST calls

See docs/identity/secret-inventory.md for the full secret record.