Cross-repo env-var documentation follow-up for PR #12092 + PR #12093 (cloud-deployment guides + downstream-deployment env-example + README)

Premise

PRs #12092 + #12093 introduce 5 new env vars without corresponding updates to the cloud-deployment documentation + downstream-deployment env-example/README files. Operators reading the existing guides won't know the new vars exist, what their defaults are, or when to override.

New env vars introduced:

Friction: relationship between native + Neo env vars

NEO_OLLAMA_KEEP_ALIVE (Neo provider per-request override, default -1) is distinct from OLLAMA_KEEP_ALIVE (native Ollama server config controlling default cache retention). Operators need to understand the interaction:

• Native OLLAMA_KEEP_ALIVE is the Ollama server default for requests that DON'T carry per-request keep_alive
• Neo's per-request keep_alive (sourced from NEO_OLLAMA_KEEP_ALIVE default -1) OVERRIDES the server default on every Neo-issued request
• With Neo's -1 default, the model stays resident regardless of native OLLAMA_KEEP_ALIVE value
• Operators tuning native OLLAMA_KEEP_ALIVE shorter need to also set NEO_OLLAMA_KEEP_ALIVE to match if they want Neo requests to respect the shorter retention

Prescription

Update both surfaces in parallel per the dogfooding-flywheel pattern (feedback_first_deployment_direct_client_repo_pattern.md):

Neo side

• learn/agentos/cloud-deployment/Configuration.md — add the 5 new env vars with defaults + override guidance
• learn/agentos/cloud-deployment/Overview.md — brief mention if env-var topology section exists
• learn/agentos/ConfigSubstrateEnvVarAudit.md — PR #12093 already added NEO_OLLAMA_KEEP_ALIVE + NEO_OPENAI_COMPATIBLE_KEEP_ALIVE; verify PR #12092 also adds the 3 NEO_ORCHESTRATOR_PROVIDER_READY_* rows (if missing, backfill)

Downstream-deployment side (separate MR in the downstream repo)

• .env.example — add commented examples for all 5 new Neo env vars; add a section explaining the OLLAMA_KEEP_ALIVE ↔ NEO_OLLAMA_KEEP_ALIVE interaction
• README.md — operator-tuning section referencing the new env vars + the interaction note
• tenant-tokens.env.example — verify: no changes needed (the new env vars are provider-wide, not tenant-scoped)

Acceptance Criteria

• AC1: learn/agentos/cloud-deployment/Configuration.md documents all 5 new env vars with their defaults + override guidance
• AC2: learn/agentos/ConfigSubstrateEnvVarAudit.md lists all 5 new env vars (verify PR #12092 additions present; backfill if missing)
• AC3: Downstream-deployment .env.example adds commented examples for all 5 new env vars with the OLLAMA_KEEP_ALIVE-vs-NEO_OLLAMA_KEEP_ALIVE interaction documented
• AC4: Downstream-deployment README.md operator-tuning section references the new env vars
• AC5: AC10 of #12089 (external operator-side compose validation) is now operationally addressable — operators have visibility into which env vars to set
• AC6: No production code changes (docs + env-example only)
• AC7: §15.6 diagnostic clean on any new prose anchors (doc updates allowed per snapshot-archaeology exception; production code untouched)

Empirical Anchor

• PR #12092 env binding additions: ai/config.template.mjs orchestrator.providerReadiness env bindings block
• PR #12093 env binding additions: ai/config.template.mjs + ai/mcp/server/memory-core/config.template.mjs keep_alive env bindings
• Downstream-deployment current state: OLLAMA_KEEP_ALIVE=5m (native ollama server var) but no Neo-equivalent vars documented
• Neo cloud-deployment Configuration.md: grep returned zero hits for any of the 5 new env vars

Related

• PR #12092 (orchestrator readiness gate)
• PR #12093 (keep_alive defaults)
• #12089 AC10 (external operator validation residual)
• feedback_first_deployment_direct_client_repo_pattern.md (work-in-both-repos discipline)
• Capability-framing discipline: Neo-side docs use generic capability framing, never name specific commercial partners