[P1.5-S3-ARI-23] `.env.example` update + `deployment/README.md`

[bjridicodes]

Ticket: P1.5-S3-07

Type: Docs | Est: 0.5d

Goal: Operators know exactly which variables to set for each deployment scenario without reading source code.

Scope:

• .env.example (update):
  • Annotate each variable as: # [local-dev only], # [GCP deployments], # [optional], # [required]
  • Add new variables: VERTEX_AI_PROJECT_ID, VERTEX_AI_LOCATION, GCP_PROJECT_ID, ARIA_VAULT_BACKEND, ARIA_CONFIG_PATH, ARIA_DASHBOARD_ENABLED, ARIA_OPERATING_MODE, ARIA_LOG_FORMAT, ARIA_LOG_DIR, ARIA_RUN_DB_PATH
  • Mark ANTHROPIC_API_KEY as # [required only when llm.provider=anthropic]
• deployment/README.md (new file):
  • Section: Docker CLI — docker build + docker run with env vars
  • Section: docker-compose — one-command startup; how to prepare conf.yaml
  • Section: Cloud Run — gcloud run deploy pattern; env vars as Cloud Run env vars; secrets via Secret Manager
  • Section: GKE — ConfigMap YAML pattern for conf.yaml; how to reference Secret Manager secrets; service account annotation for Workload Identity
  • Section: LLM provider selection — table: provider name → required env vars → supported models

Acceptance criteria:

• Every env var referenced in core/config.py is documented in .env.example
• deployment/README.md covers all 4 runtime patterns
• No platform-specific manifests (Cloud Run YAML, GKE Deployment YAML) committed to repo — README describes patterns in prose and command examples only

[stevesagronegocios673-ux]

Quick config/docs-boundary note after reading this issue, .env.example, conf_template.yaml, core/config.py, api/dependencies.py, api/routers/agent2.py, the GCP connector, and the Terraform outputs: I would make this pass start with a variable inventory before writing the deployment README.

The repo currently has a useful split:

• .env.example is framed as secrets only.
• conf_template.yaml is framed as non-secret runtime config.
• core/config.py reads conf.yaml first, then env fallbacks for non-secret config.

So I would avoid turning .env.example into one giant mixed config file. A cleaner shape is:

1. Keep .env.example focused on secrets and secret-provider credentials.
2. Add a deployment README table that says, for each runtime mode, which values come from conf.yaml, env vars, Secret Manager, Cloud Run env vars, or GKE ConfigMap/Secret.
3. In .env.example, annotate secrets by runtime/provider: ServiceNow, LLM, Slack, CDP SSH, GCP, AWS SM, HashiCorp Vault, Azure Key Vault.

A few concrete drift points I would resolve before calling the AC done:

• core/config.py currently references GCS_BUCKET_LOGS, but Terraform outputs use GCS_LOG_BUCKET in at least the UC2/UC3 outputs. Pick one public name or document the translation.
• The GCP log connector default secret name is GCP_SA_JSON, while .env.example and api/routers/agent2.py refer to GCP_SA_KEY. That will confuse deployment docs unless one name is canonical.
• The issue lists VERTEX_AI_PROJECT_ID, VERTEX_AI_LOCATION, ARIA_VAULT_BACKEND, ARIA_CONFIG_PATH, ARIA_DASHBOARD_ENABLED, ARIA_OPERATING_MODE, ARIA_LOG_FORMAT, ARIA_LOG_DIR, and ARIA_RUN_DB_PATH, but I do not see those consumed in core/config.py yet. If they are S3 target variables, I would label them as planned/new runtime variables rather than implying they already satisfy the “every env var referenced in core/config.py” acceptance test.
• README.md and documentation/aria_apis.md mention ARIA_MODE, but the issue says ARIA_OPERATING_MODE. That naming should be aligned before the deployment guide repeats either name.

For deployment/README.md, I would structure the four runtime sections around the same matrix:

Value category          Docker CLI     docker-compose     Cloud Run        GKE
conf.yaml / config      bind file      bind file         mounted/generated ConfigMap
secrets                 --env-file     .env / secrets    Secret Manager   Secret + Workload Identity
LLM provider            env + conf     env + conf        env + Secret      env + Secret
logs/run state          local path     volume/path       mounted/cloud     PVC/cloud service

That keeps the Cloud Run/GKE sections as patterns, not committed manifests, while still giving operators enough detail to set the right variables.

If useful, I can do a compact $5 docs pass: variable inventory + paste-ready .env.example annotation plan + deployment/README.md outline for Docker CLI, compose, Cloud Run, GKE, and LLM provider selection. If that scope/price works, confirm here and I will send payment options.

[bjridicodes]

Closed by PR #91 (feat/p1.5-s3-docker-config-llm) — merged 2026-06-16.