docs(connections): launch flag semantics, upgrade trap, DNT coupling

[pepmach]

What

Post-launch handoff documentation for the Connections default-on launch (#9148 + #9149), appended to the owning spec docs/system-specs/modules/connections.md.

Why

The launch surfaced five operational caveats that live nowhere except this week's PR threads and one session's memory. The next phase (provider expansion) walks straight into three of them:

• The upgrade trap: pre-launch builds materialized connections_ui: false into saved configs; after upgrade it reads as a deliberate opt-out and the gallery is silently empty. Hit the owner's own gateway on launch day. Diagnosis + fix documented; migration flagged as proposed-not-built.
• DNT coupling: every newly rendering provider name must join glossary.json dnt + ALWAYS_LATIN + the renderScan truth table, with the launch-gated (Superhuman Mail) and brand-gate (added-lines) edges spelled out.
• Config-baseline regeneration on any flag-default change.
• The i18n gate hides inside the E2E job — its failure signature reads as infra flake; step-list check documented before blind reruns.
• Evidence-based needs-attention copy contract for new providers' error strings.

Verification

bash scripts/docs-lint.sh — all documentation checks passed. Docs-only change; no code paths touched.

[github-actions]

Opus 4.8 Review — ✅ no blocking findings

Reviewed 6b8407e6e64a24ec6d2fce5bf95749a3c468ddc6 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 6b8407e

Verdict parsed from the review's SHA-scoped output markers for commit 6b8407e6e64a24ec6d2fce5bf95749a3c468ddc6.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 6b8407e6e64a24ec6d2fce5bf95749a3c468ddc6: <one-sentence reason>

[github-actions]

Design Review (Fable 5) — ✅ PASS

Design-level review of 6b8407e6e64a24ec6d2fce5bf95749a3c468ddc6 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

All referenced tests, scripts, and files exist; every description bullet has a backing hunk and vice versa. The section is appended to the owning spec (no new markdown file), matching the docs rules.

Design-Verdict: PASS

Real post-launch knowledge captured in the owning spec, with the unfixed migration honestly labeled proposed-not-built rather than claimed.

Suggestions

• The E2E-job failure-signature caveat (i18n gate failing reads as infra flake) is not connections-specific — mirror it into docs/ci/e2e-gate.md or docs/ci/i18n-gates.md with a pointer here, so a non-connections contributor hitting the same signature can find it.

[DESIGN-REVIEWED] 6b8407e

[github-actions]

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 6b8407e6e64a24ec6d2fce5bf95749a3c468ddc6 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6b8407e

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 6b8407e6e64a24ec6d2fce5bf95749a3c468ddc6: <one-sentence reason>

[pepmach]

Withdrawn — the handoff caveats belong in the Connections workstream artifact, not the repo spec.