fix(workshop): harden staged learner setup

[maruthiprithivi]

Summary

• make workshop preflight stage-aware (base, --cdc, --otel, and --all) so learners are only checked for the module they are running
• harden ClickHouse, PostgreSQL, and OpenTelemetry credential handling, including stale shell-environment detection and loopback-only OTLP ports
• align learner/instructor documentation and add deterministic preflight policy/behavior checks to CI
• serialize Next/Fumadocs type generation to remove the intermittent generated-source race

Verification

• workshop documentation policy and shell syntax checks pass
• staged preflight behavior tests pass
• backend: 40 passed
• collector: 49 passed, 1 skipped
• real-time analytics: 2 passed
• ClickHouse integration: 1 passed
• playbook typecheck passes on three consecutive runs
• production webpack build succeeds with 166 static pages
• ClickHouse environment-password authentication and heredoc multiquery verified against ClickHouse 26.3

Review notes

• adversarial findings around stale exported variables, OTLP exposure/token validation, password argv exposure, and Docker-optional docs checks were fixed and reverified
• visual review not applicable (no frontend presentation changes)
• Codex CLI second-opinion review was unavailable because the local OpenAI API credential returned 401; the final diff received manual pre-landing and adversarial review

Documentation

• learner troubleshooting: aligned stale shell-environment recovery with the new fail-fast preflight behavior
• workshop app, observability, instructor, and learner guides: audited against the final staged behavior and CI commands
• repository entry-point docs: current; no project CHANGELOG, TODOS, or VERSION file exists for this workshop change

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

Maruthi Prithivi seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}