← all branches

feat/discovery

safeviewing older commit
7521b17 · incrementalPR #305reviewed 2026-07-17 23:35 UTC0H · 0M · 0L · 1I
The branch
Purpose
Contextual feature discovery for existing Batu platform users — ambient spotlights, a Descubre hub, and a first-run linear tour, all flag-gated behind feature-discovery-spotlights.
Goal
Ship Feature Discovery v1 with ambient coachmarks, the Descubre hub, and a first-run tour; pure-decision FCIS core with full i18n and PostHog analytics.
Sub-goals
  • SG-1: Ambient spotlights — one contextual coachmark per page, ≤1/rolling-day pacing
  • SG-2: Descubre hub — header badge + self-serve pull + tour relaunch
  • SG-3: First-run linear tour — 5 steps, dimmed scrim, RPU sub-tour
  • SG-4: discovery_state table (migration 0062) + FCIS shell + RLS
  • SG-5: Adversarial review + prod blockers fixed (VERCEL_ENV gate, spotlight latch)
  • SG-6: docs(discovery) — rolling cooldown design note (this commit)
The changes (whole branch)
What
Added a 7-line JSDoc paragraph to shouldHoldAmbientForTour explaining that its 20h cooldown is rolling (lastSeenAt bumped on every report('seen')), not a permanent one-way latch. Contrasts with the old isFirstRunTourPending semantics.
Why
The rolling behaviour was non-obvious and risked being changed by a future maintainer who might mistake it for a permanent flag. The note guards that invariant without touching any logic.
Areas
apps/platform+2100−36domains/core/src/discovery+261−0domains/cross-domain/src+835−0packages/analytics/src+92−0packages/api/src/schemas+99−0packages/database+137−8packages/secrets+164−0e2e/platform+61−0
Blast
60 files (excl. generated/messages), +5013/−63 lines across 8 areas; flag-gated, nothing reaches users until feature-discovery-spotlights is enabled.
flag-gated: feature-discovery-spotlights (OFF by default) new DB table: discovery_state (migration 0062) deploy precondition: run organizations.segment reclassify script before enabling
➖CI· Check API requires higher token scope➖CodeRabbit· No .coderabbit.yaml in repo

Findings · 1

conventions1

info

Minor hub UI reference in comment

domains/cross-domain/src/feature-discovery.decisions.ts:250

The phrase 'driving discovery from the hub' references a specific UI surface — borderline by CLAUDE.md conventions, but acceptable since it explains a non-obvious design intent.

History · 36 commits

  1. c1fe7b7needs attentionincremental3H · 4M · 3L2026-07-27 06:02
  2. 414db56safeincremental0H · 0M · 2L2026-07-23 00:52
  3. ea68968needs attentionincremental0H · 4M · 7L2026-07-22 23:01
  4. 4bdb2c9needs attentionincremental1H · 3M · 5L2026-07-21 23:22
  5. 6e3f255safeincremental0H · 0M · 0L2026-07-20 16:46
  6. cc41079blockedincremental5H · 5M · 3L2026-07-20 16:25
  7. 2451ee0needs attentionincremental0H · 5M · 6L2026-07-20 16:09
  8. ab7c103needs attentionincremental0H · 1M · 6L2026-07-20 15:52
  9. 7eff611needs attentionincremental0H · 1M · 2L2026-07-18 00:41
  10. 246c67csafeincremental0H · 0M · 0L2026-07-17 23:58
  11. 7521b17safeincremental0H · 0M · 0L2026-07-17 23:35current
  12. 1847ec8needs attentionincremental0H · 2M · 4L2026-07-17 23:28
  13. 5d3175cneeds attentionincremental3H · 6M · 4L2026-07-17 19:31
  14. d3f875dneeds attentionincremental1H · 2M · 4L2026-07-17 18:01
  15. 47d25faneeds attentionincremental1H · 1M · 2L2026-07-17 00:46
  16. 440d838needs attentionincremental4H · 9M · 9L2026-07-17 00:27
  17. 7466f97needs attentionincremental0H · 1M · 5L2026-07-16 23:20
  18. b686d58needs attentionincremental0H · 2M · 2L2026-07-16 14:24
  19. 9ea1446blockedincremental2H · 7M · 10L2026-07-16 13:44
  20. 6f39bb9needs attentionincremental0H · 2M · 7L2026-07-14 21:53
  21. 2eadf2aneeds attentionincremental0H · 1M · 2L2026-07-14 20:12
  22. 97bd08fneeds attentionincremental0H · 2M · 5L2026-07-14 19:40
  23. a48e3ffneeds attentionincremental5H · 8M · 6L2026-07-14 18:22
  24. 69473b7needs attentionincremental2H · 5M · 3L2026-07-14 01:34
  25. 92e4235needs attentionincremental2H · 1M · 3L2026-07-14 01:04
  26. 6be8018safeincremental0H · 0M · 3L2026-07-14 00:15
  27. 090b4daneeds attentionincremental1H · 3M · 5L2026-07-13 23:50
  28. fa7683bneeds attentionincremental1H · 4M · 3L2026-07-13 18:55
  29. d64cd72needs attentionincremental2H · 3M · 2L2026-07-13 16:27
  30. c1f337bneeds attentionincremental3H · 7M · 14L2026-07-13 13:30
  31. 46e32b2safeincremental0H · 0M · 3L2026-07-11 02:54
  32. 3b30949needs attentionincremental0H · 2M · 3L2026-07-11 02:39
  33. 9f8dbdfneeds attentionincremental3H · 5M · 5L2026-07-11 02:32
  34. 23191eeneeds attentionincremental5H · 12M · 7L2026-07-11 02:18
  35. fa9b88fneeds attentionincremental0H · 1M · 2L2026-07-11 01:30
  36. 6a8bf42blockedfull8H · 11M · 8L2026-07-11 01:08