fix(dream-agent-key): complete DREAM_AGENT_KEY lifecycle on macOS + docs

[yasinBursali]

What

Two related gaps in the DREAM_AGENT_KEY lifecycle (the independent 32-byte hex secret introduced by PR #979):

1. .env.example — adds a commented documentation entry for DREAM_AGENT_KEY next to the existing DASHBOARD_API_KEY entry, with a generation hint and a warning that rotation breaks host-agent authentication.
2. macOS installers/macos/lib/env-generator.sh — closes the upgrade gap: pre-PR-fix(security): generate dedicated DREAM_AGENT_KEY in installers #979 installs that re-run the installer without --force previously skipped DREAM_AGENT_KEY entirely. The host agent then fell back to DASHBOARD_API_KEY, defeating fix(security): generate dedicated DREAM_AGENT_KEY in installers #979's intent of making the two secrets independent. Fix adds an idempotent upsert inside the existing early-return block.

Why

After PR #979 made DREAM_AGENT_KEY a distinct secret from DASHBOARD_API_KEY, the lifecycle was only complete on Linux (installers/phases/06-directories.sh:208 — _env_get-or-generate). Windows landed in a separate PR. macOS was left with an inconsistency: fresh installs generated the key (via the heredoc ENVEOF path), but reinstalls/upgrades skipped the upsert and left pre-#979 installs without it. .env.example also never mentioned the key, making it invisible to anyone reading the example config.

How

• .env.example: one commented documentation line inserted between the existing # DASHBOARD_API_KEY= and the Qdrant section. Matches the style of surrounding commented-key entries.
• env-generator.sh: inside the if [[ -f "$env_path" ]] && [[ "$force_overwrite" != "true" ]] early-return block, immediately before return 0, adds:

  if [[ -z "$(read_env_value "$env_path" "DREAM_AGENT_KEY")" ]]; then
      upsert_env_value "$env_path" "DREAM_AGENT_KEY" "$(new_secure_hex 32)"
  fi

  Structurally equivalent to the Linux _env_get-or-generate pattern, expressed as an idempotent upsert. Re-runs produce no-ops. Fresh-install Path B (heredoc) is unchanged.

Testing

• bash -n installers/macos/lib/env-generator.sh — clean
• shellcheck installers/macos/lib/env-generator.sh — no new warnings (all pre-existing SC2034/SC2153/SC2006 are far from the edit)
• Pre-commit (gitleaks / private-key / large-file) — clean
• Manual reasoning verified against three scenarios: missing key, empty value, populated value — upsert is idempotent and preserves existing keys

Manual test steps (macOS)

1. Pre-fix(security): generate dedicated DREAM_AGENT_KEY in installers #979 upgrade: take a .env lacking DREAM_AGENT_KEY, re-run installer without --force → key is generated and upserted; DASHBOARD_API_KEY preserved.
2. Repeat the same installer invocation → no change to DREAM_AGENT_KEY (idempotent).
3. Fresh install (.env absent or --force) → key is still written via the existing heredoc path; no regression.

Platform Impact

• macOS (primary target): closes the upgrade gap; fresh installs unchanged.
• Linux: no impact — installers/phases/06-directories.sh:208 already had the equivalent _env_get-or-generate pattern.
• Windows (WSL2): no impact — Windows installer uses Get-EnvOrNew in its PowerShell env-generator.

Known Considerations

.env.schema.json line 269's description for DREAM_AGENT_KEY still mentions "falls back to DASHBOARD_API_KEY if unset", which is stale post-#979 (the two are fully independent now). Out-of-scope for this PR; worth a small follow-up to correct the description.