Merge upstream/main into feat/secure-ticket-ids

Author: Ayush7614

.env.example

@@ -66,6 +66,52 @@ SLACK_APP_TOKEN=xapp-...
 SLACK_SIGNING_SECRET=
 SLACK_SOCKET_MODE=true
 
+# ─── Slack Ticket Mirror ─────────────────────────────────────────────────────
+# Mirrors tickets into one Slack channel: the ticket opens a thread, community
+# follow-ups and the AI reply thread under it. Read-only (replying in Slack does
+# NOT post back to the source).
+#
+# Which tickets: the allowlist in isMirrorableSource()
+# (packages/outpost/shared/src/platforms/slack-mirror-config.ts) — today Discord,
+# GitHub issues, and GitHub discussions. Slack-sourced tickets are excluded
+# (they already live in Slack); so are Teams/Email/Web/Manual/Linear.
+#
+# Mode: off (default, nothing is enqueued and the handler no-ops)
+#     | shadow (logs what it would post; posts nothing; needs NO token)
+#     | live   (posts; requires SLACK_BOT_TOKEN, or the mirror stays disabled
+#               and logs why once)
+# Any mode does nothing at all while SLACK_MIRROR_CHANNEL_ID is unset.
+#
+# Deliberately INDEPENDENT of SHADOW_MODE — that flag protects community
+# surfaces (Discord/GitHub) where real reporters watch; this posts to an
+# internal team channel, so staging posting here is intended.
+#
+# WHICH SERVICES need these vars: the handler runs in outpost-worker, but the
+# PRODUCERS gate on the same config — readSlackMirrorConfig() is called from
+# InboundHandler, which runs inside outpost-discord-bot and outpost-github-app.
+# Set SLACK_MIRROR_MODE + SLACK_MIRROR_CHANNEL_ID on the worker AND on every
+# service that creates tickets, or nothing is ever enqueued and the mirror is
+# silently dead.
+#
+# SCOPE IN v1: ticket-opens from Discord and GitHub, AI replies on both, and
+# community follow-ups from DISCORD ONLY. A follow-up comment on a GitHub issue
+# or discussion never reaches the mirror, and nothing logs that it did not — so
+# a Slack thread that stops after the AI reply does not mean the reporter went
+# quiet. See docs/deployment.md.
+SLACK_MIRROR_MODE=off
+# Channel ID, NOT a channel name. Slack: open channel -> click its name ->
+# bottom of the details pane -> Channel ID. Looks like C09AB2CD3EF.
+SLACK_MIRROR_CHANNEL_ID=
+# NOTE: SLACK_BOT_TOKEN above needs chat:write and must be set on the WORKER
+# service (outpost-worker) — the mirror handler posts from there, not from the
+# Slack bot. Invite the bot to the channel or posts fail not_in_channel (the
+# handler reports that as permanent and does not retry it).
+# Keep this channel OUT of MONITORED_CHANNEL_IDS. The Slack bot drops events
+# carrying a bot_id (apps/slack-bot/src/events/message.ts), so its own mirror
+# posts would not become tickets today — but monitoring the mirror channel
+# would duplicate every ticket's context into the bot's inbound path and makes
+# the loop one filter change away. Keep the two channel sets disjoint.
+
 # ─── Teams Bot ───────────────────────────────────────────────────────────────
 TEAMS_APP_ID=
 TEAMS_APP_PASSWORD=