# AGENTS.md — LocalCloud for Google Cloud development

This repository uses LocalCloud for local Google Cloud development and tests. LocalCloud is a local Google Cloud emulator: one Docker container that answers Google Cloud SDK calls on localhost, so code and tests run without a GCP account, credentials, or billing. Validate against real Google Cloud before production.

## Facts
- 25 Google Cloud services run locally; ports, environment variables, and guides: https://local.cloud/ai/services.md
- Default project: `local-gcp-project`. No GCP account, Google credentials, service-account key, or billing project is needed.
- The proprietary Public Preview License permits individuals and organizations, including for-profit companies, to use LocalCloud free of charge for internal development, testing, CI, evaluation, and internal pilots.

## Start LocalCloud
```bash
curl -fsSL https://local.cloud/install.sh | sh
localcloud doctor
localcloud start --local-only
curl -fsS http://localhost:5380/readiness
eval "$(localcloud env)"
localcloud console
```

- Homebrew alternative to the first line: `brew install LocalGCloud/tap/localcloud`.
- Skip the install line when `localcloud --version` already works. If the installer prints a `source` command, run it before the next line.
- `localcloud start` waits for the runtime. The readiness check uses the default gateway port 5380; if the CLI remapped it, use the gateway URL from `localcloud status`.
- `localcloud console` opens the web console in a browser; skip it in headless sessions.

## Workflow
1. Find the Google Cloud services, SDKs, Terraform providers, and CLI commands the project uses.
2. Start LocalCloud, or reuse the running runtime (`localcloud status`).
3. Export the environment: `eval "$(localcloud env)"` for shells and SDKs, `localcloud env --format terraform` for Terraform.
4. Run the narrowest check that proves the service path works through localhost.
5. If a feature is unsupported locally, record the gap and link the service page.

## Rules
- Use only local endpoint values. If a step would need real Google Cloud or real credentials, stop and report it.
- Never ask for or use service-account keys, application default credentials, production project IDs, or billing accounts.
- Export the LocalCloud environment in the same shell or test runner before any SDK, CLI, or Terraform step.
- If Docker or LocalCloud is unavailable, stop and report the blocker instead of falling back to real Google Cloud.
- Prefer the LocalCloud CLI. The `latest` image tag is mutable, so pin an image digest when repeatability matters.
- Back service-specific claims with the service page or https://local.cloud/compatibility/.
- Use LocalCloud only for the non-production work the Public Preview License permits.
- Before production, unset the emulator variables and validate the change against real Google Cloud.

## References
- Agent guide: https://local.cloud/ai/agents.md
- Capabilities and boundaries per service: https://local.cloud/ai/compatibility.md
- SDK examples: https://local.cloud/docs/sdk-examples/
- Terraform: https://local.cloud/docs/terraform/
- Seed data: https://local.cloud/docs/seed-data/
- Contact for agent integrations: agent@local.cloud