Problem
Root .env / .env.example still document secrets and knobs that are not platform-service configuration. Those belong next to the consumer (services/web/, docs tooling) or in the gitignored .env.dev when they are development-only.
Current behaviour
ELEVENLABS_API_KEY is listed in root .env.example (~L363–368) even though the docs-video pipeline already tells authors to keep it in gitignored root .env.dev (services/platform/tests/docs-videos/README.md, doctor.ts, tts.ts).
- Web Discord form delivery uses
WEB_DISCORD_WEBHOOK_URL in services/web/.env.example / services/web/server.ts — correct home — but similar non-platform vars must not accumulate in the root platform env surface (and must stay out of platform service env sync).
- Root
.env.example is the operator-facing platform config contract; putting docs TTS or marketing-form secrets there blurs “required to run the platform” vs “optional tooling / other services”.
Proposed change
- Audit root
.env.example (and any loaders that merge it) for vars unrelated to running platform services.
- Move each to the right home:
- Web-only →
services/web/.env.example (and web README).
- Docs / docs-videos / other service → that service’s
.env.example or docs.
- Dev-tooling only (e.g. ElevenLabs narration) → document and load from
.env.dev only; remove from root .env.example (keep a short pointer comment if useful).
- Update doctor scripts, README, and any sync paths so nothing still expects the old location.
Acceptance criteria
Affected service
Repo-wide env layout (platform docs-videos, web); not a runtime product feature.
Related
#2787 (PostHog epic will replace Discord forms later — still move Discord out of any wrong root surface now). Closed #2389.
Problem
Root
.env/.env.examplestill document secrets and knobs that are not platform-service configuration. Those belong next to the consumer (services/web/, docs tooling) or in the gitignored.env.devwhen they are development-only.Current behaviour
ELEVENLABS_API_KEYis listed in root.env.example(~L363–368) even though the docs-video pipeline already tells authors to keep it in gitignored root.env.dev(services/platform/tests/docs-videos/README.md,doctor.ts,tts.ts).WEB_DISCORD_WEBHOOK_URLinservices/web/.env.example/services/web/server.ts— correct home — but similar non-platform vars must not accumulate in the root platform env surface (and must stay out of platform service env sync)..env.exampleis the operator-facing platform config contract; putting docs TTS or marketing-form secrets there blurs “required to run the platform” vs “optional tooling / other services”.Proposed change
.env.example(and any loaders that merge it) for vars unrelated to running platform services.services/web/.env.example(and web README)..env.exampleor docs..env.devonly; remove from root.env.example(keep a short pointer comment if useful).Acceptance criteria
.env.exampleno longer listsELEVENLABS_API_KEY(or peers) as platform config;.env.dev/ docs-videos docs are the source of truth.services/web/env docs — not duplicated as platform requirements..env.examplewithout an explicit “pointer comment only” rationale.Affected service
Repo-wide env layout (platform docs-videos, web); not a runtime product feature.
Related
#2787 (PostHog epic will replace Discord forms later — still move Discord out of any wrong root surface now). Closed #2389.