docs(env): stop presenting add-on credentials as required

[bettercalln1ck]

Summary

Fixes #4201.

.env.example opened with:

# ═══════════════════════════════════════════════════════════════════
# REQUIRED — these must be set or docker compose will refuse to start
# ═══════════════════════════════════════════════════════════════════

and then listed nine keys. .env.schema.json marks six. I checked which source was right rather than assuming, by scanning all 52 compose files for each key:

key	schema required[]	compose reference
WEBUI_SECRET	yes	${WEBUI_SECRET:?…}
SEARXNG_SECRET	yes	${SEARXNG_SECRET:?…}
N8N_USER	yes	${N8N_USER:?…}
N8N_PASS	yes	${N8N_PASS:?…}
OPENCLAW_TOKEN	yes	${OPENCLAW_TOKEN:?…}
LITELLM_KEY	yes	${LITELLM_KEY:-…} (has fallbacks)
LIVEKIT_API_KEY	no	not referenced anywhere
LIVEKIT_API_SECRET	no	not referenced anywhere
DIFY_SECRET_KEY	no	not referenced anywhere
OPENCODE_SERVER_PASSWORD	no	not referenced anywhere

So the header's claim is false for those four: compose never reads them, and a base install comes up without them. The cost is not cosmetic — every operator following this file generated four secrets they did not need, for two add-ons that are not even bundled services (LiveKit is the optional voice add-on; Dify lives in extensions/library/services/dify).

The four move to an OPTIONAL block, commented out, each naming the add-on it belongs to. The REQUIRED block is now exactly the schema's six keys, and its header says so instead of over-promising.

AI Assistance

AI-assisted: an AI coding assistant drafted the patch and the regression test and ran the validation recorded below. I reviewed the diff, chose the validation, and am accountable for the change.

Release Lane

• Stable hotfix targeting release/2.6.x
• Mainline change targeting main
• Next-minor work targeting the next feature/minor release
• Not sure; reviewer should help classify

Stable hotfix reason:

n/a

Changed Surface

• Docs only
• Tests only
• Dashboard UI
• Dashboard API / host agent
• Installer / bootstrap / lifecycle
• Docker Compose / service manifests
• Model routing / Hermes / capabilities
• Network exposure / auth / proxy
• Dependencies / runtime wiring

Risk And Validation

• Risk level: Low
• Validation run:
  • git diff --check
  • Markdown/link sanity for docs
  • Focused tests listed below
  • Dashboard lint/test/build
  • Extension audit / compose validation
  • Release-grade fleet or scoped hardware validation
  • Stable-lane patch validation, if targeting release/2.6.x
  • Not required because: no code path changes — the four relocated keys are read by nothing in any compose file, and the env-handling suites are unchanged.

Commands/results:

$ bash tests/test-env-example-required.sh
[PASS] REQUIRED block matches schema required[] (6 keys)
[PASS] no add-on credentials are presented as mandatory
PASS=2 FAIL=0

# against main, the test names the drift rather than just failing
$ git checkout origin/main -- ods/.env.example
$ bash tests/test-env-example-required.sh
[FAIL] REQUIRED block and schema required[] disagree
  only in .env.example:
    DIFY_SECRET_KEY
    LIVEKIT_API_KEY
    LIVEKIT_API_SECRET
    OPENCODE_SERVER_PASSWORD
[FAIL] LIVEKIT_API_KEY is listed as REQUIRED but no compose file references it
...

# env-handling suites
$ bash tests/test-safe-env.sh            -> PASS
$ bash tests/test-atomic-env-writes.sh   -> PASS
$ bash tests/test-dotenv-serializer.sh   -> PASS

# tests/smoke/installer-env-smoke.sh references LIVEKIT_API_SECRET, so I ran it
# side by side: identical single failure on this branch and on a pristine main
# worktree ("Found calls to undefined function 'ai_err'"), unrelated to this.

$ make lint
All lint checks passed.
$ shellcheck --exclude=SC1091,SC2034 --severity=error ods/tests/test-env-example-required.sh
(clean)

Operational Change Check

• This is not an operational change.
• This is an operational change and validation is recorded above.
• This is an operational change and validation is intentionally deferred for:

Notes For Reviewers

• The new test compares the REQUIRED block against jq -r '.required[]' and prints both directions of the drift, so a future mismatch says which key moved rather than just failing. It also re-checks the four keys from this issue by name, and verifies every REQUIRED key is a real schema property rather than only an entry in required[].
• The keys are relocated and commented out, not deleted. They are referenced by .env.schema.json, the macOS env generator, the extensions catalog and the Dify extension's setup.sh, so they remain valid settings — just not mandatory ones.
• LITELLM_KEY stays in REQUIRED because the schema marks it required, but it is the one key there that compose resolves with :- fallbacks rather than :?. I left the schema alone — deciding whether it truly belongs in required[] is a judgement about the LiteLLM auth model rather than a docs fix, and I did not want to smuggle it in here.
• Wired into ods/Makefile and the integration-smoke job in test-linux.yml; the workflow entry is what gates, since no workflow runs make test.
• The test skips cleanly when jq is unavailable rather than failing.