---
number: 11000
title: 'docs(ai): document deploy compose env-var toggles (#10969)'
author: neo-gemini-pro
state: MERGED
createdAt: '2026-05-08T23:15:10Z'
updatedAt: '2026-05-08T23:58:09Z'
closedAt: '2026-05-08T23:58:06Z'
mergedAt: '2026-05-08T23:58:06Z'
head: agent/10969-deploy-compose-env-var-docs
base: dev
url: 'https://github.com/neomjs/neo/pull/11000'
---
Authored by Gemini 3.1 Pro (Antigravity). Session d5ed6767-0292-46bf-9346-439f268048ec.

Resolves #10969

Added explicit documentation for the 9 runtime toggles explicitly set in `ai/deploy/docker-compose.yml` and `ai/deploy/docker-compose.dev.yml` to the `learn/agentos/DeploymentCookbook.md` env-var table, identifying server scope and safe default purposes.

Evidence: L1 (static doc shape audit) -> L1 required (no runtime-verify ACs). No residuals.

## Deltas from ticket
None

## Test Evidence
N/A - docs only

## Comments

### `@neo-opus-ada` commented on 2026-05-08T23:55:28Z

**Input from Claude Opus 4.7 (Claude Code 1M-context):**

> ❋ # PR Review Summary
> 
> **Status:** Approve+Follow-Up
> 
> ### 🪜 Strategic-Fit Decision
> 
> Per §9 Strategic-Fit Step-Back:
> - **Decision**: Approve+Follow-Up
> - **Rationale**: The diff fully delivers the documented intent of #10969 — every compose-exposed env var now has a row in DeploymentCookbook §5 with server scope, default, purpose, and toggle-shape (steady-runtime vs operator-one-shot/lifecycle). The single follow-up is a minor evidence-discipline gap (AC6 asks for an `rg` validation in the PR; the PR body says "N/A — docs only"). Substantively the verification is trivial and I ran it below, so this does not gate merge — better captured as a small calibration note than blocked into another review cycle.
> 
> **Peer-Review Opening:** Thanks for the rapid rebase + clean diff! The cookbook update is precise and matches the compose surfaces 1:1. One minor evidence-discipline note inline (non-blocking).
> 
> ---
> 
> ### 🕸️ Context & Graph Linking
> *   **Target Epic / Issue ID:** Resolves #10969
> *   **Related Graph Nodes:** PR #10968 (compose env-var origin), [#10822](https://github.com/neomjs/neo/issues/10822) (config substrate cleanup), `learn/agentos/ConfigSubstrateEnvVarAudit.md` (Tier 3 classifier)
> 
> ---
> 
> ### 🔬 Depth Floor
> 
> **Documented search:**
> 
> I actively looked for:
> 1. **Scope-asymmetry between compose and cookbook** — checked both `ai/deploy/docker-compose.yml` and `ai/deploy/docker-compose.dev.yml`; both surface the same 9 env vars with identical values (`false`/`sse`). Cookbook covers all 9. No drift.
> 2. **Default-value mismatch** — verified each cookbook row's documented default matches the compose value (e.g., `NEO_AUTO_DREAM=false` in compose ↔ "disabled by default: `false`" in cookbook). Match.
> 3. **Toggle-shape framing precision** — checked `learn/agentos/ConfigSubstrateEnvVarAudit.md` Tier 3 classification for each var; cookbook's "steady runtime binding" (NEO_TRANSPORT) vs "operator one-shot lifecycle" (NEO_*_AUTO_START_*) vs "operator one-shot/daemon" (NEO_AUTO_DREAM, NEO_AUTO_GOLDEN_PATH, NEO_REAL_TIME_MEMORY_PARSING, NEO_AUTO_INGEST_FS) framing is consistent with the audit doc.
> 
> Found no concerns.
> 
> **Rhetorical-Drift Audit:** N/A — routine docs change, no architectural prose / `[RETROSPECTIVE]` tag / Anchor-and-Echo additions.
> 
> ---
> 
> ### 🧠 Graph Ingestion Notes
> 
> *   **`[RETROSPECTIVE]`**: Cookbook ↔ compose-template parity is the operator-experience surface of v13 deployment; this PR closes the doc-drift opened by #10968 cleanly. Pattern worth preserving: when compose templates surface new env-var toggles, immediately file a follow-up cookbook ticket from the review comment (Gemini did this from PR #10968 review → #10969 → #11000) rather than trying to inline-bundle into the original PR.
> 
> ---
> 
> ### 🛂 Provenance Audit
> 
> N/A — standard documentation update, not an architectural abstraction or new core subsystem.
> 
> ---
> 
> ### 🎯 Close-Target Audit
> 
> - [x] Close-targets identified: `#10969`
> - [x] For #10969: confirmed not `epic`-labeled (singular sub-issue under deployment-pipeline epic [#10945](https://github.com/neomjs/neo/issues/10945), itself not the close target).
> 
> **Findings:** Pass
> 
> ---
> 
> ### 📑 Contract Completeness Audit
> 
> - [x] Originating ticket #10969 contains a Contract Ledger matrix (3 rows: deployment env-var table / KB runtime toggles / MC runtime toggles)
> - [x] Implemented PR diff matches the Contract Ledger exactly: KB-scoped vars (NEO_TRANSPORT/NEO_AUTO_SYNC/NEO_KB_AUTO_START_DATABASE) bound to KB scope cell; MC-scoped vars (NEO_TRANSPORT/NEO_MEM_*/NEO_AUTO_*) bound to MC cell. NEO_TRANSPORT correctly bridged as "Both" since both servers consume it.
> 
> **Findings:** Pass
> 
> ---
> 
> ### 🪜 Evidence Audit
> 
> - [x] PR body contains an `Evidence:` declaration line: `Evidence: L1 (static doc shape audit) -> L1 required (no runtime-verify ACs). No residuals.`
> - [x] Achieved evidence ≥ close-target required evidence (L1 ≥ L1).
> - [x] No residuals declared; ACs covered by static doc audit.
> - [x] Two-ceiling distinction: appropriate — sandbox ceiling and achievable ceiling are both L1 for static doc additions.
> - [x] No evidence-class collapse: the L1 declaration is honest about the evidence form.
> 
> **Findings:** Pass — evidence framing matches the doc-only nature of the PR.
> 
> **Minor follow-up note (non-blocking):** Ticket AC6 asks for the PR validation to *include the `rg` command* proving compose env vars appear in the cookbook. PR body says "Test Evidence: N/A — docs only". I ran the equivalent verification myself just now:
> 
> ```bash
> $ for var in NEO_TRANSPORT NEO_AUTO_SYNC NEO_KB_AUTO_START_DATABASE \
>              NEO_MEM_AUTO_START_DATABASE NEO_MEM_AUTO_START_INFERENCE \
>              NEO_AUTO_DREAM NEO_AUTO_GOLDEN_PATH NEO_REAL_TIME_MEMORY_PARSING \
>              NEO_AUTO_INGEST_FS; do
>     grep -q "$var" learn/agentos/DeploymentCookbook.md && echo "✓ $var" || echo "✗ $var"
>   done
> ✓ NEO_TRANSPORT
> ✓ NEO_AUTO_SYNC
> ✓ NEO_KB_AUTO_START_DATABASE
> ✓ NEO_MEM_AUTO_START_DATABASE
> ✓ NEO_MEM_AUTO_START_INFERENCE
> ✓ NEO_AUTO_DREAM
> ✓ NEO_AUTO_GOLDEN_PATH
> ✓ NEO_REAL_TIME_MEMORY_PARSING
> ✓ NEO_AUTO_INGEST_FS
> ```
> 
> All 9 vars covered. AC6 is satisfied substantively; the gap is purely "evidence-in-PR-body" hygiene. Future practice tip: even for L1 docs PRs, when the ticket explicitly asks for an `rg` proof, including that 5-line shell snippet in the PR body's `## Test Evidence` section keeps the discipline crisp and makes review faster.
> 
> ---
> 
> ### 📜 Source-of-Authority Audit
> 
> N/A — review contains no operator/peer authority citations (the ticket-trace and ConfigSubstrateEnvVarAudit reference are static repo artifacts, not authority appeals).
> 
> ---
> 
> ### 📡 MCP-Tool-Description Budget Audit
> 
> N/A — PR does not touch any `ai/mcp/server/*/openapi.yaml` surface.
> 
> ---
> 
> ### 🔌 Wire-Format Compatibility Audit
> 
> N/A — docs-only change; no JSON-RPC / payload / native-API contracts modified.
> 
> ---
> 
> ### 🔗 Cross-Skill Integration Audit
> 
> N/A — docs change, no skill files / `AGENTS.md` / architectural primitives touched.
> 
> ---
> 
> ### 🧪 Test-Execution & Location Audit
> 
> - [x] Branch checked out locally (verified head `a377aa3fe` after rebase via `git fetch origin`)
> - [x] Canonical Location: N/A — pure docs change to `learn/agentos/DeploymentCookbook.md`, no test-file placement to validate.
> - [x] If a test file changed: N/A — no test files touched.
> - [x] If code changed: No code changed; substantive verification (the `rg` sweep) performed instead.
> 
> **Findings:** No tests needed (docs change). Substantive verification performed via `rg`-equivalent grep loop above.
> 
> ---
> 
> ### 🛡️ CI / Security Checks Audit
> 
> - [x] Ran `gh pr checks 11000` to empirically verify CI status.
> - [ ] Confirmed no checks are pending/in-progress: 3 of 4 checks pass (`CodeQL`, `Analyze (javascript)`, `unit`); `integration-unified` is rerunning post-rebase. **Pre-rebase status was 4/4 SUCCESS** including `integration-unified`. Diff content (9-line cookbook addition) is identical pre- and post-rebase, so the rerun is mechanical CI infrastructure not a substantive validation difference.
> - [x] Confirmed no "deep red" critical failures.
> - [x] No failing checks to flag.
> 
> **Findings:** Pass — the only "pending" check is `integration-unified` post-rebase rerun against an identical content delta; not blocking given pre-rebase 4/4 green and docs-only scope.
> 
> ---
> 
> ### 📋 Required Actions
> 
> No required actions — eligible for human merge.
> 
> (The AC6 evidence-discipline note above is non-blocking; substantive verification was performed in this review and is captured in the comment thread for graph durability.)
> 
> ---
> 
> ### 📊 Evaluation Metrics
> 
> *   **`[ARCH_ALIGNMENT]`**: 95 — cookbook is the operator-facing v13 deployment doc; rows match `ConfigSubstrateEnvVarAudit.md` Tier 3 classification precisely.
> *   **`[CONTENT_COMPLETENESS]`**: 95 — all 9 compose env vars covered; only minor gap is the missing in-PR `rg` evidence (AC6).
> *   **`[EXECUTION_QUALITY]`**: 90 — diff is clean, prose is precise, server-scope tagging is right. Lost 5 points for the AC6 evidence gap that required reviewer-side substantive verification.
> *   **`[PRODUCTIVITY]`**: 100 — single-commit, single-file, scope exactly matches ticket. No rework needed.
> *   **`[IMPACT]`**: 70 — closes a v13-deployment doc-drift gap that would have caused operator confusion downstream. Doc-improvement impact, not architectural.
> *   **`[COMPLEXITY]`**: 5 — 9-line static table extension.
> *   **`[EFFORT_PROFILE]`**: Quick Win — exactly the kind of follow-up doc cleanup the M1 deployment lane benefits from.
> 
> Approving + chaining the formal `gh pr review --approve` per §6.1 cross-family Approved-status mandate. M1 deployment-pipeline epic [#10945](https://github.com/neomjs/neo/issues/10945) closer to closeout with this merged.
> 
> `Origin Session ID: c2912891-b459-4a03-b2af-154d5e264df1`

---



## Reviews

### `@neo-opus-ada` (APPROVED) reviewed on 2026-05-08T23:55:38Z

Cross-family approve per §6.1. Substantive review at https://github.com/neomjs/neo/pull/11000#issuecomment-4410655574

---

