Setup Local Gcp Config

Workflow

1. Discover the target project with gcloud.
2. Discover or choose the bucket with gcloud.
3. Discover region and zone with gcloud.
4. Invent a stable service name if needed.
5. Write .karl/local.env.
6. Verify with the repo checker.

Discovery Rules

GOOGLE_CLOUD_PROJECT

Prefer, in order:

1. A project the user explicitly named.
2. gcloud config get-value core/project if it is set and the user has not said otherwise.
3. A project found from relevant existing resources in gcloud.

If multiple plausible projects exist and the correct one is unclear, ask the user instead of guessing.

GCS_BUCKET

Use gcloud storage buckets list --project="$GOOGLE_CLOUD_PROJECT" to discover candidates.

Prefer, in order:

1. A bucket the user explicitly named.
2. A bucket that already contains this repo's expected prefixes like corpus/, index/, synth/, rollouts/, training/, models/, or eval/.
3. A single obvious bucket for the project.

If there are multiple plausible buckets and no clear winner, ask the user.

If no bucket exists yet, it is acceptable to propose the repo's standard bootstrap path and use a planned bucket name, but tell the user that the bucket is a chosen local value rather than a discovered one.

GCP_REGION

Prefer, in order:

1. gcloud config get-value compute/region
2. The location of the chosen bucket when that clearly matches the intended deployment region
3. The region implied by an existing VM or other known repo runtime
4. us-central1 if nothing else is discoverable

GCP_ZONE

Prefer, in order:

1. gcloud config get-value compute/zone
2. The zone of an existing repo VM
3. <GCP_REGION>-a if nothing else is discoverable

SERVICE_NAME

This is not reliably discoverable from gcloud for this repo's local setup. It is acceptable to invent a concise, stable name such as karl-api unless the user provided one or an existing Cloud Run service clearly should be reused.

Writing Rules

• Start from config/local.env.example if it helps, but write the real local file at .karl/local.env.
• Keep the file simple KEY=value lines with no extra quoting unless needed.
• Never commit secrets or credentials there.
• Never commit .karl/local.env.
• Prefer explicit project flags in later gcloud commands: --project="$GOOGLE_CLOUD_PROJECT".

Verification

After writing .karl/local.env, run:

uv run python scripts/verify_gcp_setup.py

If the user wants a fuller smoke test, the next repo-native checks are:

make gcp-check
make bucket

Ambiguity Handling

• Ask the user when multiple projects or buckets are plausible.
• Be explicit about which values were discovered versus invented.
• SERVICE_NAME can be invented when needed.
• If gcloud is unavailable or unauthenticated, explain what is missing and stop before writing misleading values.

Additional Reference

• For command patterns and decision heuristics, see reference.md